DirectX 스타트 페이지

DirectX 7.0

목적

Microsoft® DirectX® 는, 매력적인 멀티미디어 어플리케이션을 생성하기 위한 백 스테이지 패스이다.

용도

DirectX 에는, 프로그래밍을 위한 범용적인 어프로치가 2 개 준비되어 있다. 그것이, DirectX Foundation 와 DirectX Media 이다.

DirectX Foundation 는, 게임이나 고성능인 멀티미디어 어플리케이션을 생성하기 위한 , 하위 레벨의 API (Application Programming Interfaces) 세트이다. 이것에는, 2 차원 (2-D) 및 3 차원 (3-D)의 고성능인 그래픽, 사운드, 음악, 입력, 피드백등의 지원이나, 멀티 플레이어 게임 등에 대하는 네트워크 통신의 지원이 포함되어 있다.

DirectX Media 는, 멀티미디어를 채용한 Web 컨텐츠나 스탠드얼론 어플리케이션을 생성하기 위한 , 상위 레벨의 API 세트이다. DirectX Media 는 DirectX Foundation 를 기반으로서 구축되고 있어, 유연성은 뒤떨어지지만, 보다 풍부한 기능 세트를 제공한다.

대상 개발자

DirectX 를 사용할 수 있는 것은, C/C++ 프로그래머 및 Visual Basic 프로그래머이다.

실행시의 요건

DirectX 는, Microsoft Windows® 95, Windows 98, 및 Windows 2000 의 환경에서 사용할 수 있다.

DirectX Foundation 의 소개

DirectX, 문서의 관례 사항, 신기능, 및 C/C++ 와 Visual Basic 에서의 DirectX API 의 사용에 관한, 일반적인 정보.

DirectX Foundation 의 컴퍼넌트

DirectX Foundation 를 구성하는 각 컴퍼넌트에 관한 정보.

DirectX 샘플

DirectX Foundation 의 각 컴퍼넌트의 샘플 정보에의 퀵 링크.

DirectX 튜토리얼

각 컴퍼넌트의 튜토리얼 정보에의 퀵 링크.

피드백

에러 리포트와 기능 요구를 Microsoft 사에 직접 송신한다.

Built on 2000년 4월 13일


동작환경

DirectX SDK

한글판 DirectX 7.0 Ver 1.94(2002.09.05) - by dxk(,dex,덱스 케이)

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

8.0에 이어 7.0의 다이렉트 드로우 부분도 요청 하신 분이 있어서 7.0도 제작했습니다.

물론 이것도... 일본어 도큐먼트를 일한 번역기를 이용해서 제작 한 것 입니다.

부족한 점이 많이 눈에 띄나... 양해 바랍니다.

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

참고로 이 파일 은 절대 비상업용의 목적으로 사용되어져야 합니다.

개인적인 공부를 위해서만 사용되어 져야 합니다.

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

그리고 제가 개인 홈페이지가 없기 때문에 아래의 사이트를 임시 거처로 정합니다.

홈페이지 주인에게 허락 받았을 뿐 홈페이지 주인과는 전혀 무관합니다.

http://www.spirit3d.net

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

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

참고로 http://www.spirit3d.net 은 3D 프로그래밍 아티클 전문 사이트 입니다.

개인적으로 좋은 자료가 많이 올라 오는 훌륭한 사이트 라고 생각합니다.^^;;;;;;

많이 들 방문 해주시고 좋은 자료가 있다면 올려 주시기 바랍니다.

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

정식 한글판 도큐먼트가 나오길 바라면서...혹시 영어 잘하시는 분은 MS에 항의 좀 해주세요..ㅡ.ㅡ;;;

(일본어 도큐먼트는 있는데... 한국어는 왜 없냐고... 무시 하는 거냐고...)

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

이메일 : dx-kor@hanmail.net

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

2002년 9월 5일


법적 정보

DirectX 7.0
프로그래머 레퍼런스

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

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

© 1995-1999 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 (P) 1996 Roland Corporation U.S.

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

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

저작권에 관한 주의

특별한 주의 : 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를 실행하고 있는 컴퓨터에 직접 접속하지 않아도, 음악의 사운드를 생성할 수가 있는 디바이스입니다. 어떠한 환경에 있어도, 샘플 세트를 수정하는 것은 허가되고 있지 않습니다.


DirectX Foundation 의 소개

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

여기에서는, DirectX Foundation 의 개요에 관한 정보를 이하의 주제로 나누어 설명한다.

  • DirectX 의 헬프에 대해
  • DirectX Foundation 의 신기능
  • DirectX Foundation 의 컴퍼넌트
  • DirectX 샘플
  • DirectX 튜토리얼
  • DirectX 툴
  • C 및 C++ 의 프로그래밍 항목
  • Visual Basic 프로그래밍에 대해
  • 참고 자료


DirectX 의 헬프에 대해

여기에서는, C, C++, 및 Microsoft® Visual Basic® 에서의 Microsoft® DirectX® 어플리케이션 카이하츠에 도착해 설명한다.

DirectX 는 C 와 C++ 의 양쪽 모두를 완전하게 지원 하고 있다. 여기에서는, C++ 구문을 빈번하게 사용하지만, 몇개의 예나 튜토리얼 (샘플 어플리케이션도 마찬가지)에서는 C 를 사용하고 있다. 게다가 이하의 주제는 DirectX 로 C 를 사용하는 방법을 나타내고 있다.

  • 매크로 정의의 사용
  • C 로부터의 COM 오브젝트에의 액세스

여기에서는, 정보를 알기 쉽게 가리키기 위해서(때문에), 언어 정보를 나타내는 경우,[C++] ( 「C 또는 C++」를 의미한다)라고 표시한다. Visual Basic 에 대해서는 [Visual Basic] 라고 표시한다. C++ 에 관한 개념의 설명은, 구문을 필요에 따라서 변경하는 것으로 C 에도 유효하다.

여기에서는, programming environment 에 관한 정보만을 표시할 수 있도록(듯이), 언어의 필터링 기능을 이행 하고 있다. 이 주제도 포함한 많은 주제의 타이틀 바의 좌상에는, pop-up 하는 언어 선택용의 버튼이 있다. 이 버튼을 클릭하는 것으로써, C++ ( 및 C) 또는 Visual Basic 의 몇개의 설명을 표시할 수 있다. [모두 표시] 를 클릭 하면, 양언어에 대한 언어 고유의 정보를 참조할 수 있다. 선택하는 언어와는 관계없이, 모든 언어에 관한 정보 (일반적인 개념등)는 항상 참조할 수 있다.

[C++]

이 텍스트는, 언어 선택용의 버튼으로부터 [C++] 또는 [모두 표시] 를 클릭했을 때만 표시된다.

[Visual Basic]

이 텍스트는, 언어 선택용의 버튼으로부터 [Visual Basic] 또는 [모두 표시] 를 클릭했을 때만 표시된다.

주제의 타이틀 바에 있는 버튼의 설명을 이하에 나타낸다.

버튼 | 설명
L | 그 주제로 언어의 필터링이 가능한 일을 나타낸다. 메뉴상에서 표시 가능한 프로그램 언어를 선택한다.
+ | 상세 정보가 있는 것을 나타내, 그러한 주제에의 링크를 제공한다. [참조] 로서 나타난다.
! | 레퍼런스를 사용하기 위한 동작환경을 나타낸다. 이전에는,[대응 정보] 로서 나타나고 있었다. 이 정보에는, operating system의 버젼, 헤더 정보등이 포함된다.

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

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


DirectX Foundation 의 신기능

DirectX 7.0 의 신기능의 몇개인가를 이하에 나타낸다.

  • 새로운 Visual Basic 타입 라이브러리에 의해, 주된 DirectX 의 기능을 그 환경에서 개발된 어플리케이션으로 이용할 수 있다.
  • Microsoft® Direct3D® 직접 모드 API 는, 디바이스 상태의 블록, 지오메트리 블렌딩, 큐브 환경 맵, 유저 정의의 클립면등이 많은 신기능을 제공한다. 상세한 것에 대하여는, 「DirectX 7.0 에서의 직접 모드의 변경점」을 참조할것.
  • 새로운 Direct3DX 유틸리티 라이브러리는, Direct3D 와 Microsoft® DirectDraw® 의 최상정도에 있는 헬퍼-층으로서 이용할 수 있어 3D 그래픽스 개발의 일반적인 태스크를 간략화한다.
  • Microsoft® DirectMusic® 는, Downloadable Sounds level 2 규격을 지원 한다.
  • Microsoft® DirectInput® 는, 현시점에서 8 개까지의 mouse button, 키보드에의 배타 액세스, force feedback 이펙트의 지연 시작을 지원 한다. 새로운 메소드에서는 force feedback 이펙트 파일의 읽고 쓰기를 할 수 있어 Force Editor 어플리케이션을 사용해 이펙트를 생성 할 수가 있다.
  • Microsoft® DirectSound® 는, 확장된 하드웨어 음성 관리를 제공한다.
  • 새로운 3D 오디오 처리 알고리즘에 의해, DirectSound 에서의 CPU 사용율이 효율화된다.
  • DirectDraw 의 스테레오 지원이, 액티브 디바이스에 추가되었다.
  • Microsoft® DirectPlay® 로비 어플리케이션은, 립르라운치를 제공한다.
  • 헬프 파일이 확장되어 언어 고유의 정보를 표시하기 위한 동적인 필터링 기능이 준비되었다.
  • 많은 샘플 어플리케이션을 제공한다.


DirectX Foundation 의 컴퍼넌트

DirectX Foundation 는 이하의 컴퍼넌트로 구성된다.

  • Direct3D 는, 상위 레벨의 보관 유지 모드 인터페이스와 하위 레벨의 직접 모드 인터페이스를 제공한다. 보관 유지 모드 인터페이스를 사용하면(자), 완전한 3D 그래픽 시스템을 간단하게 이행 할 수가 있어 직접 모드 인터페이스를 사용하면(자), 렌더링 파이프라인을 어플리케이션으로부터 완전하게 제어하는 것이 가능하게 된다. 직접 모드의 상세한 것에 대하여는, 「Direct3D 직접 모드에 대하며」를 참조할것. 보관 유지 모드의 상세한 것에 대하여는, 「Direct3D 보관 유지 모드의 소개」를 참조할것.
  • Direct3D 에는 이번, 헬퍼-층의 Direct3DX 유틸리티 라이브러리가 준비되어 3D 그래픽스 개발의 일반적인 태스크를 간략화할 수가 있다. 「Direct3DX 유틸리티 라이브러리에 도착하며」를 참조할것.
  • DirectDraw 는, 오프 스크린 디스플레이 메모리내에 놓여진 비트 맵에의 직접 액세스나, 하드웨어의 블리트 기능, 버퍼 플립핑 기능등에의 초고속 액세스를 제공하는 것으로써, 하드웨어 및 소프트웨어의 애니메이션 기술의 질을 향상시킨다. 상세한 것에 대하여는, 「DirectDraw 에 대하며」를 참조할것.
  • DirectInput 는, 모든 종류의 입력과 force feedback 디바이스를 지원 한다. 상세한 것에 대하여는, 「DirectInput 에 대하며」를 참조할것.
  • DirectMusic 는, 메세지 베이스의 데이터와 함께 기능해, 음악 재생, 및 리얼타임 어레인지나 다양한 연주를 수반하는 DLS 베이스의 사운드 이펙트용으로 완전한 시스템을 제공한다. DirectX 의 이 컴퍼넌트의 상세한 것에 대하여는, 「DirectMusic 에 대하며」를 참조할것.
  • DirectPlay는, 모뎀 또는 네트워크를 개입시킨 게임 간접속을 용이하게 실시할 수 있도록(듯이) 한다. 상세한 것에 대하여는, 「DirectPlay 에 대하며」를 참조할것.
  • DirectSetup 는, 한 번의 호출로 인스톨을 완료할 수 있는 DirectX 프로시저를 제공한다. 상세한 것에 대하여는, 「DirectSetup 에 대하며」를 참조할것.
  • DirectSound 는, 웨이브 사운드를 재생할 수 있어 하드웨어와 소프트웨어의 믹싱, 3D 포지셔닝, 및 사운드 캡춰를 지원 한다. 상세한 것에 대하여는, 「DirectSound 에 대하며」를 참조할것.


DirectX 샘플

산 샘플로부터 코드를 배우는 것이야말로, DirectX 를 이해하기 위한 가장 좋은 방법이다. 샘플 어플리케이션은 DirectX SDK 의 Dxf\Samples\Multimedia 폴더에 놓여져 있어 Platform SDK 의 레퍼런스의 DirectX 샘플 코드에도 코드가 기술되어 있다.

이 샘플의 간단한 개요는 이하의 각 컴퍼넌트에 나타나고 있다.

  • Direct3D 직접 모드의 툴과 샘플
  • Direct3DX 유틸리티 라이브러리 샘플
  • DirectDraw 의 툴과 샘플
  • DirectInput 의 툴과 샘플
  • DirectMusic 샘플
  • DirectPlay 의 툴과 샘플
  • DirectSetup 샘플
  • DirectSound 의 툴과 샘플


DirectX 튜토리얼

DirectX 의 컴퍼넌트마다의 튜토리얼에는, 각 컴퍼넌트의 기본적인 이행 방법이 순서를 쫓아 나타나고 있다. 코드 패스와 설명으로부터, API 의 사용법과 주의점을 이해할 수가 있다.

각 컴퍼넌트마다의 튜토리얼은 이하대로이다.

  • Direct3D 직접 모드 튜토리얼
  • DirectDraw 튜토리얼
  • DirectInput 튜토리얼
  • DirectMusic 튜토리얼
  • DirectPlay 튜토리얼
  • DirectSound 튜토리얼


DirectX 툴

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

  • DirectX Caps Viewer
  • DirectX Diagnostic Tool
  • DirectX Property Sheet

참조

  • Direct3D 직접 모드 툴
  • DirectDraw 툴
  • DirectInput 툴
  • DirectPlay 툴


DirectX Caps Viewer

설명

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

패스

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

유저즈 가이드

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


DirectX Diagnostic Tool

설명

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

패스

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

유저즈 가이드

DirectX Diagnostic Tool 에는 독자적인 헬프 파일이 준비되어 있어[Help] 버튼을 클릭 하면 액세스 할 수 있다.


DirectX Property Sheet

설명

컨트롤 패널의 이 컴퍼넌트는, 시스템으로 이용 가능한 DirectX 컴퍼넌트, 드라이버, 및 하드웨어 기능에 대한 정보를 취득한다. 또, DirectX 직접 링크 라이브러리 (DLL)의 디버그 버젼으로 생성되는 디버그 출력량을 설정하거나 테스트용으로 하드웨어 가속화 기능을 무효로 하기 위해서(때문에) 사용할 수도 있다.

패스

컨트롤 패널의 [DirectX] 아이콘을 더블 클릭 한다.


C 및 C++ 의 프로그래밍 항목

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Visual Basic 프로그래밍에 대하며」를 참조할것.

[C++]

여기에서는, DirectX Foundation API 의 모든 프로그래밍에 관한 일반적인 항목을 소개한다. 설명하는 내용은 이하대로이다.

  • 컴퍼넌트 오브젝트 모델
  • 콜백 함수의 사용
  • 버젼 체크
  • DirectX 의 샘플 및 그 외의 DirectX 어플리케이션의 컴파일
  • DirectX 어플리케이션의 디버그


컴퍼넌트 오브젝트 모델

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Visual Basic 프로그래밍에 대하며」를 참조할것.

[C++]

DirectX API 의 대부분은, COM 를 기본으로 하는 오브젝트와 인터페이스로 구성되어 있다. COM 는, 인터페이스의 재이용에 중점을 둔 오브젝트 베이스의 시스템을 위한 토대이다. 또, 임의의 수의 인터페이스의 구축을 가능하게 하는 인터페이스 사양이기도 하다.

DirectX 어플리케이션은, COM 오브젝트의 인스턴스로부터 구축된다. 오브젝트란,인터페이스로부터 액세스 하는 하드웨어나 데이터를 나타내는 블랙 박스와 같은 것이라고 생각할 수가 있다. 커멘드는, COM 인터페이스의메소드로부터 오브젝트에 송신된다. 예를 들어, 디스플레이 어댑터의 현재의 표시 모드를 DirectDraw 오브젝트로부터 취득하려면 ,IDirectDraw7 인터페이스의 IDirectDraw7::GetDisplayMode 메소드를 호출한다.

오브젝트는, 실행시에 다른 오브젝트에 바인드 해, 바인드처 오브젝트가 제공하는 인터페이스의 이행을 이용할 수가 있다. 또, COM 오브젝트라고 알고 있는 오브젝트가 있어, 그 오브젝트에 의해 지원 되고 있는 인터페이스도 알고 있으면, 그 오브젝트를 실행할 수 있는 서비스를 어플리케이션 (또는 다른 오브젝트)으로부터 조사할 수가 있다. 모든 COM 오브젝트가 계승하는 메소드의 1 개인 QueryInterface 메소드를 사용하면(자), 오브젝트가 어느 인터페이스를 지원 하고 있을까를 조사해 지원 되고 있는 인터페이스에의 포인터를 취득할 수가 있다. 상세한 것에 대하여는, 「IUnknown 인터페이스」를 참조할것.

DirectX 의 COM 프로그래밍의 상세한 것에 대하여는, 이하의 주제를 참조할것.

  • IUnknown 인터페이스
  • C++ 와 COM 인터페이스
  • 새로운 인터페이스의 취득
  • 인터페이스 메소드의 이름과 구문
  • C 로부터의 COM 오브젝트에의 액세스
  • 매크로 정의의 사용


IUnknown 인터페이스

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Visual Basic 프로그래밍에 대하며」를 참조할것.

[C++]

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

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

AddRef 메소드와 Release 메소드는, 오브젝트의 참조 카운트를 관리한다. 예를 들어, DirectDrawSurface 오브젝트를 생성 했다고 한다. 생성 직후, 이 오브젝트의 참조 카운트는 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

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

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

HRESULT QueryInterface(
  REFIID riid,
  LPVOID* obp
);

파라미터

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

반환값

메소드가 성공하면, S_OK 가 돌려주어진다.

메소드가 실패하면, E_NOINTERFACE 또는 E_POINTER 가 돌려주어진다. 또, 컴퍼넌트안에는, 이러한 에러값에 대한 개별의 정의를 헤더 파일에 저장 하고 있는 것도 있다. 예를 들어, DirectInput 에서는 DIERR_NOINTERFACE 와 E_NOINTERFACE 는 같은 값이다.

주의

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

동작환경

Windows NT/2000 : Windows NT 3.1 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요.
헤더 : unknwn.h 로 선언.


IUnknown::Release

IUnknown::Release 메소드는, 오브젝트의 참조 카운트를 1 만 감소시킨다.

ULONG Release();

파라미터

파라미터 없음.

반환값

새로운 참조 카운트값을 돌려준다. 이 값은, 진단 및 테스트를 목적으로 해 사용하기 (위해)때문에인 만큼 준비된 것이다.

주의

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

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

동작환경

Windows NT/2000 : Windows NT 3.1 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요.
헤더 : unknwn.h 로 선언.


C++ 와 COM 인터페이스

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Visual Basic 프로그래밍에 대하며」를 참조할것.

[C++]

COM 인터페이스는, C++ 로 말하는 곳(중)의 추상 기본 클래스와 같은 것이다. 즉, 일련의 특징이나 의미는 정의하지만, 구체적인 이행은 정의하지 않고, 상태 데이터도 일절 관련지을 수 있지 않았다. C++ 의 추상 기본 클래스에서는, 방법에서의 메소드가순수 가상 함수로서 정의되어 코드는 일절 할당할 수 없다.

C++ 의 순수 가상 함수와 COM 인터페이스는, 어느쪽이나 vtable 로 불리는 기구를 사용한다. vtable 에는, 인터페이스를 이행 하기 위해서 필요한 모든 함수의 주소가 저장 된다. 어플리케이션 또는 오브젝트내에서 이러한 함수를 사용하고 싶은 경우는,QueryInterface 메소드를 호출해, 목적의 오브젝트에 그 인터페이스가 있을지 어떨지를 조사해 그 인터페이스에의 포인터를 취득하면 좋다. QueryInterface 를 호출한 후, 이 오브젝트는 어플리케이션이나 오브젝트에 vtable 에의 포인터를 보낸다. 이 메소드가 오브젝트에 의해 이행 되는 각종 인터페이스 메소드를 호출할 수 있는 것도,vtable 에의 포인터를 사용하고 있기 때문에 있다. 이 메카니즘에 의해, 오브젝트가 사용하는 Private 데이터라고 불러 방편측의 클라이언트의 처리는 완전하게 떼어내진다.

COM 오브젝트와 C++ 의 오브젝트의 이제(벌써) 1 개의 유사점은, 메소드의 최초의 인수가 인터페이스 (C++ 의 경우는 클래스)의 이름인 것이다. 이것은, C++ 에서는 this 인수로 불린다. COM 오브젝트와 C++ 의 오브젝트는 바이너리 레벨로 완전하게 호환성이 있기 (위해)때문에, 컴파일러는, COM 인터페이스를 C++ 의 추상 클래스와 같이 취급해, 같은 구문을 가지는 것을 전제로 처리한다. 이 때문에, 코드의 복잡함은 경감된다. 예를 들어, C++ 에서의 this 인수는, 이미 해석된 파라미터로서 다루어져 코드화 되지 않고,vtable 를 사용한 간접적인 호출도 C++ 에서는 암묵적으로 처리된다.


새로운 인터페이스의 취득

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Visual Basic 프로그래밍에 대하며」를 참조할것.

[C++]

COM 에서는, 오브젝트의 기능을 갱신하려면 , 기존 인터페이스의 메소드를 변경하는 것이 아니라, 새로운 기능을 실현하기 위한 새로운 인터페이스를 추가하도록(듯이) 정해져 있다. COM 상에 구축된 오브젝트는, 기존 인터페이스를 변경하지 않고 남겨 두는 것으로, 낡은 어플리케이션과의 호환성을 잃을리가 없는 채, 서비스 내용을 자유롭게 확장할 수 있다.

DirectX 의 컴퍼넌트는, 이 시도에 따라 개발되고 있다. 예를 들어, DirectDraw 컴퍼넌트에서는,IDirectDrawSurface,IDirectDrawSurface2,IDirectDrawSurface3,IDirectDrawSurface4, 및 IDirectDrawSurface7 의 5 개의 인터페이스의 머지않아를 사용해도, DirectDrawSurface 오브젝트에 액세스 할 수 있게 되어 있다. 이러한 각 인터페이스는, 그것보다 이전의 버젼으로 제공되고 있던 메소드를 무변경으로 지원 하지만, 새로운 기능을 지원 하기 위해서 새로운 메소드를 추가하고 있다.

어플리케이션으로 새로운 기능이 필요한 차면, 새로운 인터페이스를 취득할 필요는 없다. 새로운 인터페이스가 제공하는 기능을 이용하고 싶은 경우는, 그 인터페이스의 글로벌 유니크 식별자 (GUID)를 지정해, 대상 오브젝트의 IUnknown::QueryInterface 메소드를 호출하지 않으면 안 된다. 인터페이스의 GUID 는, 대응하는 헤더 파일내에서 선언되고 있다.

다음의 예는, 새로운 인터페이스가 지원 되고 있는지 어떤지를 조사하는 방법을 나타내고 있다.

LPDIRECTDRAW    lpDD1;
LPDIRECTDRAW2   lpDD2;

ddrval = DirectDrawCreate( NULL, &lpDD1, NULL );
if( FAILED(ddrval))
    goto ERROROUT;

// IDirectDraw2 인터페이스가 있을지 어떨지를 문의한다.
ddrval = lpDD1->QueryInterface(IID_IDirectDraw2, (void **) &lpDD2);
if( FAILED(ddrval))
    goto ERROROUT;

// IDirectDraw2 가 있는 것을 알 수 있었으므로, 원의 인터페이스를 릴리즈 한다.
lpDD1->Release();

보기 드물게, 새로운 인터페이스가, 구버젼의 인터페이스로 지원 되고 있던 메소드의 일부를 지원 하지 않는 경우도 있다. 그 일례로서IDirect3DDevice2 인터페이스를 들 수 있다. 구버젼의 인터페이스로 제공되고 있던 기능을 필요로 하는 어플리케이션에서는, 전의 예로 가리킨 것과 같은 방법으로, 구버젼의 인터페이스의 GUID 를 사용해, 낡은 인터페이스를 취득하면 좋다.


인터페이스 메소드의 이름과 구문

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Visual Basic 프로그래밍에 대하며」를 참조할것.

[C++]

이 문서에서는, COM 인터페이스의 메소드를 모두 C++ 의 클래스명으로 가리킨다. 이 명명 규칙을 채용한 것은, 기술에 일관성을 갖게하기 (위해)때문에와 복수의 DirectX 오브젝트가 같은 이름의 메소드를 가지는 경우에 (QueryInterface,AddRef,Release 등), 다른 오브젝트의 메소드와의 구별을 명확하게 하기 위한(해)이다. 이러한 표기 규칙 그렇다고 해서, 이러한 메소드가 C++ 로 밖에 사용할 수 없다고 하는 것은 아니다.

메소드의 구문에도 C++ 의 표기를 이용하고 있다. 이 때문에, 인수에는 인터페이스에의 this 포인터가 포함되지 않았다. C 로 프로그래밍 하는 경우는, 반드시 어느 메소드에도 인터페이스에의 포인터를 지정해야 한다. 다음에 나타내는 예는, C++ 의 표기에서의 IDirectDraw7::GetCaps 메소드의 구문이다.

HRESULT GetCaps(
  LPDDCAPS lpDDDriverCaps,
  LPDDCAPS lpDDHELCaps
);

C 의 표기에서는, 같은 메소드의 구문이 다음과 같이 된다.

HRESULT GetCaps(
  LPDIRECTDRAW7 lpDD,
  LPDDCAPS lpDDDriverCaps,
  LPDDCAPS lpDDHELCaps
);

인수 lpDD 에는, DirectDraw 오브젝트를 나타내는 DirectDraw 인터페이스에의 포인터를 지정한다.


C 로부터의 COM 오브젝트에의 액세스

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Visual Basic 프로그래밍에 대하며」를 참조할것.

[C++]

COM 인터페이스의 메소드는, C 프로그램으로부터도 호출할 수가 있다. C 로부터 인터페이스 메소드를 호출하는 경우에는, 이하의 2 점에 대해 주의하지 않으면 안 된다.

  • 메소드의 최초의 인수에는, 이미 생성되고 있어 그 메소드를 호출하는 오브젝트에의 포인터 (인수 this)를 지정한다.
  • 인터페이스가 가지는 각 메소드를 참조하려면 , 오브젝트의 vtable 에의 포인터를 사용한다.

다음의 예는, C 로 IDirectDraw7::CreateSurface 메소드를 호출해, DirectDraw 오브젝트에 관련지을 수 있었던 표면을 생성 하고 있다.

ret = lpDD->lpVtbl->CreateSurface (lpDD, &ddsd, &lpDDS,
      NULL);

인수 lpDD 는, 새로운 표면을 관련지을 수 있는 DirectDraw 오브젝트를 참조하고 있다. 이 메소드의 호출은, 표면 정보 구조체 (&ddsd)에 값을 저장 해, 새로운 표면에의 포인터 (&lpDDS)를 돌려준다.

IDirectDraw7::CreateSurface 메소드를 호출하려면 , 우선, DirectDraw 오브젝트의 vtable 에의 참조를 제외해, 한층 더 vtable 로부터 메소드에의 참조를 제외한다. 이 메소드의 최초의 파라미터는 이미 생성 되고 있어 이 메소드를 호출하는 DirectDraw 오브젝트에의 참조를 지정한다.

COM 오브젝트의 메소드를 호출하는 방법의 C 와 C++ 에서의 차이를 나타내기 위해서(때문에), 같은 메소드를 C++ 로 가리킨다 (C++ 에서는, 암묵적으로 lpVtbl 에의 참조가 떼어져this 포인터도 암묵적으로 건네받는다).

ret = lpDD->CreateSurface(&ddsd, &lpDDS, NULL)


매크로 정의의 사용

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Visual Basic 프로그래밍에 대하며」를 참조할것.

[C++]

DirectX 인터페이스의 헤더 파일이 많게는, 각 메소드용의 매크로 정의가 기술되고 있다. 이러한 매크로는, 프로그래밍시에 메소드를 간단하게 사용할 수 있도록(듯이) 하기 위해서 준비된 것이지만, C, C++ 의 머지않아로 프로그래밍 하고 있는 경우에서도, __cplusplus 가 정의되고 있는지 어떤지에 응해, 메소드의 호출을 그 때 사용하고 있는 구문에 맞은 적절한 형태에 전개해 준다고 하는 이점도 있다.

다음의 예에서는,IDirectDraw7::CreateSurface 메소드의 호출에 IDirectDraw7_CreateSurface 매크로를 사용하고 있다. 최초의 파라미터는, 이미 생성되고 있어 이 메소드를 기동하는 DirectDraw 오브젝트에의 참조이다.

ret = IDirectDraw7_CreateSurface (lpDD, &ddsd, &lpDDS,
    NULL);

현재 매크로 정의가 지원 되고 있는 메소드를 조사하려면 , 사용하는 DirectX 컴퍼넌트의 적절한 헤더 파일을 참조할것.


콜백 함수의 사용

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Visual Basic 프로그래밍에 대하며」를 참조할것.

[C++]

DirectX 에는, 하드웨어 리소스나 어플리케이션으로 이용 가능한 그 외의 항목을 열거하기 위해서 사용하는 메소드가 많이 준비되어 있다. 이러한 메소드는, 기본적으로 모두 같은 방법으로 기능한다.

prototype의 콜백 함수는, 각 DirectX 컴퍼넌트로 나타나고 있다. 어플리케이션은, 이러한 prototype와 같은 반환값과 파라미터로 함수를 선언한다. 콜백 함수는 CALLBACK,WINAPI, 또는 FAR PASCAL 타입으로서 선언된다. 이것들은 모두 동등하다.

어플리케이션이 열거 메소드를 호출하는 경우는, 이행 된 적절한 콜백 함수에의 포인터를 제공한다. 메소드는, 열거하는 항목 마다 1 회 함수를 호출해, 항목에 대한 정보를 건네준다. 함수내에서, 어플리케이션은 이 정보를 사용해, 리스트의 구축이나 특정의 디바이스 능력의 검색이라고 한 모든 태스크를 실행할 수 있다. 모든 항목이 열거되는지, 또는 콜백 함수가 열거의 종료를 나타내는 값 (콜백 함수의 귀가형에 의해, FALSE 또는 지정된 HRESULT)을 돌려주면(자), 열거 메소드는 돌아온다.

예에 대해서는, 「DirectInput 디바이스의 열거」를 참조할것.


버젼 체크

유저의 시스템으로 현재 실행중의 DirectX 의 버젼에 있어서의 기능을 조정하기 위해서, 어플리케이션측에서 현재 인스톨 되고 있는 DirectX 의 버젼을 확인해야 하는 경우가 있다.

DirectX 소프트웨어 개발 킷에는, (SDK 루트) \Samples\Multimedia\DXMisc\Src\GetDXVer 에 소스 코드 첨부의 샘플 어플리케이션이 준비되어 있다. 이것은 시스템에 DirectX 가 존재할지 어떨지를 확인해, DirectX 가 존재하는 경우에는 그 버젼을 확인한다. 각 DirectX 의 새로운 버젼은 이전의 버젼의 기능을 모두 지원 하지만, 어플리케이션이 장래적인 버젼에서도 동작하도록, 특정의 버젼 또는그 이후의 버젼으로 반드시 테스트하는 것.

또,QueryInterface 를 사용해 특정의 기능을 테스트할 수도 있다. 예를 들어, 어플리케이션 전반은 DirectX 3.0 이후의 버젼으로 동작하도록(듯이) 설계되고 있지만, 옵션의 force feedback 이펙트가 DirectX 5.0 이후의 버젼만으로 지원 된다고 한다. 이 경우,IDirectInputDevice 인터페이스를 취득하고 나서 IDirectInputDevice2 에 문의하는 것으로, force feedback가 지원 될지 어떨지를 확인할 수 있다.

다양한 이유로부터, 어플리케이션측에서 현재 실행되고 있는 operating system의 버젼의 확인이 필요한 경우도 있다. 컴퍼넌트나 Windows operating system의 장래의 버젼에 용이하게 이행 할 수 있도록(듯이) 하려면 , 어플리케이션이 대응하는 가장 낡은 버젼을 확인해, 그 이후의 버젼에서의 인스톨과 실행을 실시할 수 있도록(듯이) 한다. Windows 2000 에는 DirectX 7.0 의 기능 또는 그 이상의 것이 갖춰져 있으므로, 개발자는 Windows 2000 또는 그 이상의 것을 검출해, 검출되었을 경우는 거기서 어플리케이션이 동작하는 것 같은 코드를 기술할 필요가 있다. 반대로, 검출된 버젼이 Windows NT 4. 0 의 경우, DirectX 7.0 의 기능은 이용할 수 없다.

다음의 샘플 함수는, operating system가 파라미터의 가리키는 버젼 (메이저 버젼, 마이너 버젼, 서비스 팩)과 같은, 또는 그 이후의 경우에 TRUE 를 돌려준다.

BOOL bIsWindowsVersionOK(DWORD dwMajor, DWORD dwMinor, WORD dwSPMajor)
{
    OSVERSIONINFO osvi;

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

    osvi.dwOSVersionInfoSize = sizeof(OSVERSIONINFO);
    GetVersionEx((OSVERSIONINFO*) &osvi);

    // 메이저 버젼을 체크한다.
    if (osvi.dwMajorVersion > dwMajor)
        return TRUE;
    else if (osvi.dwMajorVersion == dwMajor)
    {
        // 마이너 버젼을 체크한다.
        if (osvi.dwMinorVersion > dwMinor)
            return TRUE;
        else if (osvi.dwMinorVersion == dwMinor)
        {
            // 서비스 팩을 체크한다.
            if (dwSPMajor && osvi.dwPlatformId ==
                    VER_PLATFORM_WIN32_NT)
            {
                HKEY    hKey;
                DWORD   dwCSDVersion;
                DWORD   dwSize;
                BOOL    fMeetsSPRequirement = FALSE;

                if (RegOpenKeyEx (HKEY_LOCAL_MACHINE,
                        "System\\CurrentControlSet\\Control\\Windows",
                        0,
                        KEY_QUERY_VALUE,
                        &hKey) == ERROR_SUCCESS)
                {
                    dwSize = sizeof(dwCSDVersion);
                    if (RegQueryValueEx (hKey,
                            "CSDVersion",
                            NULL,
                            NULL,
                            (unsigned char*) &dwCSDVersion,
                            &dwSize) == ERROR_SUCCESS)
                    {
                        fMeetsSPRequirement =
                                (LOWORD(dwCSDVersion)  >= dwSPMajor);
                    }
                    RegCloseKey(hKey);
                }

                return fMeetsSPRequirement;
            }
            return TRUE;
        }
    }
    return FALSE;
}


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

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Visual Basic 프로그래밍에 대하며」를 참조할것.

[C++]

여기에서는, DirectX 어플리케이션의 컴파일시에 고려해야 할 점에 대해 설명한다. 설명하는 내용은 이하대로이다.

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


컴파일의 준비

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Visual Basic 프로그래밍에 대하며」를 참조할것.

[C++]

이 SDK 에 포함되어 있는 각 샘플에는, 그것용의 소스 파일, 프로젝트 리소스, 링커등의 설정 정보를 기술한 Microsoft® Visual C++® 의 프로젝트 파일 (MDP 파일)이 준비되어 있다. 그러나, 샘플을 확실히 컴파일 해, 링크하려면 , 샘플을 컴파일 하는 개발자가 약간 설정 작업을 실시하지 않으면 안 되는 경우도 있다. 또, 독자적으로 새로운 프로젝트를 생성 하는 경우는, 그 프로젝트용의 설정 정보를 개발자가 스스로 준비해야 한다. (샘플에 대해서는, 필요한 라이브러리에 관한 정보를 제공하는 목적으로, 범용적인 makefile 도 준비되어 있다. Microsoft Visual C++ 이외의 컴파일러를 사용해 샘플을 컴파일 하는 경우는, 이 makefile 를 참조한 다음, 각자가 사용하고 있는 환경에 맞추어 적당 이 파일을 수정하는 것. ) 여기에서는, DirectX 의 샘플에도, 개발자가 독자적으로 개발하는 DirectX 어플리케이션에도 해당하는 내용을 설명한다.

Visual C++ 로 프로젝트 파일을 연 후, 어플리케이션을 컴파일 하기 전에 몇개의 설정값을 체크해야 한다. 이후의 설명은, Microsoft Visual C++ 5.0 및 4.2 에 유효하지만, Visual C++ 외의 버젼 및 그 외의 컴파일러에서도 동등의 설정값을 설정할 수 있을 것이다. Version 5.0 또는 4.2 의 Visual C++ 를 사용하지 않은 경우, 이러한 설정값을 변경하는 방법에 대해서는, 사용하고 있는 개발 환경에서 제공되는 문서를 참조할것.

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

인클루드 파일의 검색 패스

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

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

링커의 검색 패스

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

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

이 설정값은 프로젝트 파일내에서 지정되기 (위해)때문에, 샘플과 함께 제공된 프로젝트 파일을 사용하는 경우는, 이 설정을 확인할 필요는 없다. 신규 어플리케이션의 경우는, 확인이 필요하다. 확인하려면 ,[프로젝트] 메뉴의 [설정] 을 클릭한다 (Visual C++ 4.2 에서는,[빌드] 메뉴의 [설정] 을 클릭한다). 이 커멘드를 실행 하면, 다음과 같은 다이알로그 박스가 표시된다.

DirectX 를 사용하는 어플리케이션은, 반드시 Dxguid.lib 인클루드 라이브러리를 링크한다. 이 라이브러리는, 모든 DirectX Foundation COM 인터페이스를 위한 글로벌 유니크 식별자 (GUID)를 정의하고 있다 (단독의 소스 모듈내에서, 그 외의 모든 인클루드에 앞서 INITGUID 를 정의하고 나서, 스테이트먼트를 정의 하면 말하는 방법을 취해도 괜찮다). 게다가 어플리케이션이 적절한 표준 DirectX 링크 라이브러리에 링크되는 일도 확인해야 한다. 다음 표에 나타내는 것은, 이용 가능한 각종 DirectX 기본 컴퍼넌트와 거기에 대응하는 링크 라이브러리의 일람이다.

컴퍼넌트 | 링크 라이브러리 (*. lib)
Direct3D 직접 모드 | D3dim.lib, D3du.lib
Direct3DX 유틸리티 라이브러리 | D3dx.lib, D3dxd.lib (디버그)
Direct3D 보관 유지 모드 | D3drm.lib, D3dxof.lib
DirectDraw | Ddraw.lib
DirectInput | Dinput.lib
DirectMusic | 없음.
DirectPlay | Dplayx.lib
DirectSetup | Dsetup.lib
DirectSound | Dsound.lib
(모든 컴퍼넌트) | Dxguid.lib


컴퍼넌트의 버젼 정수

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Visual Basic 프로그래밍에 대하며」를 참조할것.

[C++]

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

#ifndef   DIRECTDRAW_VERSION
#define   DIRECTDRAW_VERSION 0x0700
#endif /* DIRECTDRAW_VERSION */

이러한 정수에 다른 값을 정의 하면, 이전의 버젼의 컴퍼넌트로 이 컴퍼넌트보다 새로운 버젼의 헤더 파일을 사용할 수가 있다. 예를 들어, DirectX 3.0 버젼의 DirectDraw 의 컴파일에 최신의 헤더 파일을 사용하려면 , DIRECTDRAW_VERSION 에 0x0300 를 정의한다. 개발 환경에서 정수의 값을 설정하거나 헤더 파일 그 자체의 값을 변경하거나 할 수 있다.


DirectX 어플리케이션의 디버그

여기에서는, C 및 C++ 어플리케이션의 디버그에 대해 설명한다. 설명하는 내용은 이하대로이다.

  • 디버그와 DLL 제품
  • 심볼 정보


디버그와 DLL 제품

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

[Visual Basic]

Visual Basic 로 개발하고 있는 경우는, 어플리케이션의 실행이 한층 더 늦어질 우려가 있기 때문에, DLL 의 디버그 버젼을 인스톨 하는 이점은 없다.

[C++]

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

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


심볼 정보

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Visual Basic 프로그래밍에 대하며」를 참조할것.

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


Visual Basic 프로그래밍에 대해

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[Visual Basic]

여기에서는, DirectX® for Visual Basic® 를 사용해 어플리케이션을 개발하는 방법을 기술한다.

이하의 토픽에 대해 설명한다.

  • 타입 라이브러리의 참조
  • DirectX 오브젝트의 생성
  • GUID 의 사용
  • 메소드에의 배열의 수수
  • 플래그의 사용
  • 비트 마스크의 사용
  • DirectX 열거
  • Visual Basic 에러 트래핑
  • DirectX 클래스의 레퍼런스


타입 라이브러리의 참조

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[Visual Basic]

프로젝트로 DirectX for Visual Basic 를 사용하기 위해서는, 우선 그 프로젝트에 타입 라이브러리에의 액세스권이 있는 것을 확인할 필요가 있다.

Visual Basic 로 [프로젝트] 메뉴의 [참조 설정] 을 클릭한다. [참조 설정] 다이알로그 박스가 표시된다. [DirectX 7 for Visual Basic Type Library] 의 좌측의 체크 박스를 온으로 해,[OK] 를 클릭한다.


DirectX 오브젝트의 생성

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[Visual Basic]

DirectX for Visual Basic 어플리케이션의 모두로,DirectX7 오브젝트가 필요하다. 이것은, 각 DirectX 컴퍼넌트에 대해서 주요한 오브젝트를 생성 할 경우에 사용하는 메소드의 친오브젝트이다. DirectX7 에는, Direct3D 의 계산을 실행하는 메소드 등, 그 외에도 다수의 메소드가 있다.

DirectX7 오브젝트는, 다음의 예의 같게 새로운 오브젝트로서 선언하는 것만으로 취득할 수 있다.

Public gObjDX As New DirectX7

DirectSound 등의 DirectX 컴퍼넌트를 생성 하려면 , 우선 그 오브젝트의 변수를 선언해, 적절한 DirectX7 생성 메소드를 호출해 생성 한 오브젝트를 그 변수로 설정한다. 다음에, 예를 나타낸다.

Public gObjDSound As DirectSound
Set gObjDSound = DirectX7.DirectSoundCreate

다음의 오브젝트는, DirectX 의 주요한 컴퍼넌트이며,DirectX7 의 메소드를 사용해 생성 한다.

컴퍼넌트 | 오브젝트 | DirectX7 생성 메소드
Direct3D 보관 유지 모드 | Direct3DRM | Direct3DRMCreate
DirectDraw | DirectDraw7 | DirectDrawCreate
DirectInput | DirectInput | DirectInputCreate
DirectMusic | DirectMusicComposer | DirectMusicComposerCreate
 | DirectMusicLoader | DirectMusicLoaderCreate
 | DirectMusicPerformance | DirectMusicPerformanceCreate
DirectPlay | DirectPlay4 | DirectPlayCreate
 | DirectPlayLobby | DirectPlayLobbyCreate
DirectSound | DirectSound | DirectSoundCreate
 | DirectSoundCapture | DirectSoundCaptureCreate

그 외의 주요한 DirectX 컴퍼넌트의 Direct3D 직접 모드는,DirectDraw7.GetDirect3D 메소드를 호출해 취득할 필요가 있는 Direct3D7 오브젝트에 의해 나타내진다.


GUID 의 사용

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[Visual Basic]

DirectX 의 기본으로 되어 있는 컴퍼넌트 오브젝트 모델 (COM)로 자주(잘) 사용되는 글로벌 유니크 식별자 (GUID)는, 보통 DirectX for Visual Basic 에서는 표시할 수 없다. 그러나, 몇개의 장소에서는 표시할 수 있다. 그 경우, 그것들은 수치는 아니고 캐릭터 라인으로서 다루어진다.

새로운 GUID 를 취득할 필요가 있는 경우는, Vbguidgen.exe (SDK 의 \Samples\Multimedia\VBSamples\DXMisc\Bin 폴더에 저장 되고 있다)를 실행해,[Copy] 버튼을 클릭한다. GUID 를 Visual Basic 어플리케이션에 붙여, 그 주위에 물음표를 설정한다.

DirectX7.CreateNewGuid 메소드를 사용해 실행시에 GUID 를 생성할 수도 있다.

어플리케이션으로 정의한 GUID 는, 다음과 같이 DirectPlay 프로그램으로 사용할 수 있다 (다만,SessionData 는 초기화된 DirectPlaySessionData 오브젝트이다).

Const guidApp = "{AC330441-9B71-11D2-9AAB-0020781461AC}"
Call SessionData.SetGuidApplication(guidApp)

DirectX 메소드안에는, GUID 멤버가 저장 된 데이터 타입을 돌려주는 것이 있다. 이러한 GUID 의 포맷은, 예와 같은 캐릭터 라인 포맷이다.

DirectX 는, 특정의 프로퍼티나 그 외의 엔티티에 대해서 다수의 GUID 를 정의하고 있어, 메소드안에는, 이와 같이 사전에 정의된 GUID 의 어느쪽이든으로 수수를 해야 하는 것이 있다. 거기에는, 전의 예의 같게, (C++ 헤더 파일의) 실제의 값을 캐릭터 라인으로서 건네준다. 그러나, 일반적으로는 좀 더 간단하게, 문서화한 캐릭터 라인 앨리어스(alias)로 수수를 한다. 예를 들어,DirectInput.CreateDevice 메소드를 사용하면, 표준 키보드의 디바이스를 생성 하면 와, 실제의 GUID 는 아니고 "GUID_SysKeyboard" 로 수수를 하는 것이 가능하다.


메소드에의 배열의 수수

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[Visual Basic]

몇개의 DirectX 메소드에서는, 지정되어 있지 않은 형태의 데이터가 돌려주어진다. 예를 들어,DirectSoundCaptureBuffer.ReadBuffer 메소드의 buffer 파라미터에는 Any 형의 데이터가 돌려주어진다.

일반적으로는, 그러한 메소드로부터 데이터가 바이트 배열로서 돌려주어지면(자) 형편이 좋다. Visual Basic 배열에서는 열매 데이터의 전에 다른 정보가 포함되어 있으므로, 배열의 이름을 메소드에 건네주는 것은 간단하지 않다. 그 때문에, 차례와 같이 배열의 최초의 요소를 건네줄 필요가 있다. 여기서,dsCaptureBuffer 는 DirectSoundCaptureBuffer 오브젝트,buffer 는 0 베이스의 바이트 배열,nBytes 는 읽힌 바이트수가 저장 되는 Long 형 데이터이다.

ReDim buffer(nBytes)
Call dsCaptureBuffer.ReadBuffer(0, nBytes, buffer(0), 0)

다만, 메소드안에는 실제로 유저가 입력한 데이터의 배열을 파라미터로서 주고 받는 것이 있으므로 주의 해야 한다 (예를 들어, 「DirectInputDevice.SetDataFormat 」를 참조할것). 이 경우, 차례와 같이 배열의 선두의 요소는 아니고 배열 자체를 주고 받을 필요가 있다. 여기서,formatArray 는 DIOBJECTDATAFORMAT 형의 배열이다.

MyDevice.SetDataFormat(diDataFormat, formatArray())


플래그의 사용

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[Visual Basic]

DirectX for Visual Basic 가 많은 오브젝트 메소드에서는,flags 파라미터나, 거기에 닮은 이름의 파라미터가 사용된다. 또, 형태안에는 플래그를 포함한 멤버를 가지는 것도 있다. 메소드 호출의 다양한 동작을 제어하거나 디바이스 능력등의 상세를 보고할 때 사용한다.

플래그는 1 비트의 정보이다. 특정의 동작 또는 능력이 있는지 없는지를 지정하거나 보고한다. 관련 플래그 세트는, 일반적으로 각 비트를 공유하지 않는 멤버를 열거하는 것으로 나타낸다 (다만, 플래그안에는 다른 플래그와 조합해 나타내는 것도 있다).

각 플래그는 1 비트로 나타내지므로, 복수의 플래그를 조합해 1 개의 값으로 나타낼 수가 있다. 예를 들어, DirectInput 디바이스의 협조 레벨을 foreground와 배타의 양쪽 모두에 설정하고 싶다고 한다. 거기에는, 다음과 같이 논리 연산 Or 를 사용해 2 개의 플래그를 조합한다.

' diDevice 는 DirectInputDevice 오브젝트, hwnd 는 윈도우 핸들이다.
diDevice.SetCooperativeLevel(hwnd, _
    DISCL_FOREGROUND Or DISCL_EXCLUSIVE)

대부분의 경우, 논리 연산자 Or 를 사용해 복수의 플래그를 조합하는 연산은, 덧셈 연산자를 사용해 플래그를 합계하는 연산과 등가이다. 그러나, 몇개의 플래그는 비트의 편성을 나타내고 있는 것으로부터, 플래그를 합계하는 연산은 너무 영리한 선택이다고는 말할 수 없다. 다음의 예로, 플래그 CF_PURPLE 는 CF_RED 와 CF_BLUE 의 편성을 나타내고 있다.

Enum COLORFLAGS
    CF_RED    = 1
    CF_BLUE   = 2
    CF_PURPLE = 3
    CF_GREEN  = 4
End Enum

Dim Color As Integer
Color = CF_RED Or CF_PURPLE

여기서,Color 의 값은 3 이다. CF_RED 는, CF_PURPLE 에 그 값이 이미 포함되어 있으므로 불필요하다.

한편, 다음의 연산에서는 부정한 값이 설정된다.

'이것은 실수이다 !
Color = CF_RED + CF_PURPLE

여기서, 변수에 4 가 설정되어 CF_GREEN 와 등가가 된다.

유저는, 플래그의 값을 취득하면(자),And 논리 연산을 사용해 개별의 플래그의 설정값을 추출할 수 있다. 플래그값에 플래그 정수로 나타내진 비트가 포함되어 있는 경우,And 연산에 의해 0 이외의 값이 돌려주어질 때, 그 플래그는 "온" 이다. And 연산으로 0 이 돌려주어졌을 경우, 그 플래그는 "오프" 이다. 예를 들어, 다음의 호출은,DIDEVCAPS 형의 변수에 돌려주어지는 능력의 입력 디바이스가 물리적으로 시스템에 Attach 되고 있는지 어떤지를 판정한다.

Dim IsAttached As Boolean
IsAttached = diDevCaps.lFlags And DIDC_ATTACHED

차례와 같이, 등가일지 어떨지를 테스트해서는 안 된다.

'이것은, 실수이다 !
IsAttached = (diDevCaps.lFlags = DIDC_ATTACHED)

이와 같이 하면 올바르게 기능하지 않는 이유는,lFlags 에는 DIDC_FORCEFEEDBACK 등의 외 비트도 포함되어 있을지도 모르기 때문에이다 ( 「CONST_DIDEVCAPSFLAGS 」를 참조할것).


비트 마스크의 사용

DDSURFACEDESC2 등, DirectX 형안에는 비트 마스크로서 기능하는 Long 형 멤버를 가지는 것이 있다. 일반적으로, 이러한 멤버에는 16 진형식에서 값을 할당한다. 그러나, Visual Basic 는 보통 16 진정수를 제일 짧은 타입으로 변환하려고 한다. 그 때문에, 예를 들어 &HFF 은 –1 값을 가지는 Integer 형 데이터에 변환된다. Long 형 데이터가 돌려주어진다고 예상하고 있는 DirectX for Visual Basic 에 이 값이 돌려주어지면(자), 그것은 &HFFFFFFFF 에 변환되어 버린다.

16 진의 비트 마스크를 적절히 변환하기 위해서는, 다음과 같이 식의 뒤에 ampersand(&) (&)를 이제(벌써) 1 개(살) 설정한다.

DDSD.ddpfPixelFormat.lRBitMask = &HFF&


DirectX 열거

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[Visual Basic]

대부분의 DirectX 어플리케이션은, 보통 초기화시에, 사용 가능한 리소스를 열거할 필요가 있다. 예를 들어, DirectDraw 를 사용하는 어플리케이션은 사용 가능한 표시 모드를 판정할 필요가 있어, 또는 DirectInput 를 사용하는 어플리케이션은 죠이스틱으로 사용 가능한 버튼이나 축을 열거할 필요가 있다.

DirectX for Visual Basic 에서는, 어플리케이션이 열거 오브젝트를 취득 하면 자동적으로 열거가 처리된다. 열거 오브젝트가 생성 되면(자), 콜렉션이 구축된다. 이 콜렉션은 오브젝트가 존재하는 한 존재해, 열거 오브젝트의 메소드를 사용해 액세스 할 수 있다.

열거 오브젝트안에는,DirectX7 오브젝트로부터 취득해야 하는 것이 있다. 예를 들어, DirectSound 디바이스를 열거하려면 ,DirectX7.GetDSEnum 메소드를 호출한다. 콜렉션으로부터 적절한 디바이스의 GUID 를 취득한 다음이 아니면,DirectSound 오브젝트를 생성 할 수 없다.

그 외의 열거 오브젝트는, DirectX 컴퍼넌트 오브젝트로부터 취득된다. 예를 들어,DirectInput 오브젝트를 취득하면,DirectInput.GetDIEnumDevices 메소드를 호출해 입력 디바이스의 열거 오브젝트를 취득할 수 있다.

다음의 샘플 코드에서는, 시스템에 Attach 떠날 수 있어 모든 입력 디바이스가 열거된다. 다만,di 는 DirectInput 오브젝트이다.

Dim diEnum As DirectInputEnumDevices
Set diEnum = di.GetDIEnumDevices(0, DIEDFL_ATTACHEDONLY)

DirectInputEnumDevices 오브젝트의 2 개의 메소드를 사용하면, Attach 된 디바이스를 반복해 검색해, 특정의 능력을 가지는 디바이스를 검색하거나 또는 다른 처리를 실행할 수 있다. 다음의 예에서는, 디바이스의 이름을 리스트 박스로 설정한다.

Dim diDevice As DirectInputDeviceInstance
Dim X As Integer

For X = 1 To diEnum.GetCount
    Set diDevice = diEnum.GetItem(X)
    Call List1.AddItem(diDevice.ProductName)
Next X

다만, DirectX 열거에 의해 생성 된 콜렉션은 모두 1 베이스이다.


Visual Basic 에러 트래핑

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[Visual Basic]

C 언어나 C++ 에서는, 모든 메소드의 호출로 HRESULT 값이 돌려주어진다. 어플리케이션은, 반환값을 조사해, 거기에 기초를 두어 처리를 실시하거나 또는 그것을 무시할 수가 있다.

DirectX for Visual Basic 에서의 에러 처리는, 완전히 다르다. Visual Basic 에서는, 메소드 호출은 성공하는지, 실패할까의 언젠가이다. Visual Basic 에는, S_FALSE 등의 정의 HRESULT 값과 등가의 성공 코드는 없다. 호출이 실패했을 경우, 에러가 발생해, 어플리케이션에 에러 핸들러가 없는 한 처리는 종료한다. 에러 번호는, Visual Basic 의 글로벌 오브젝트 Err 로 설정된다. 각 메소드로 발생할 가능성이 있는 에러의 대부분은, 이 문서의 메소드의 레퍼런스 페이지에 게재하고 있다.

다음의 예에서는,gObjDPlay 는 DirectPlay4 오브젝트이다. DirectPlay4.CreatePlayer 호출이 실패 하면, FAILEDCREATEPLAYER 라벨로부터 처리가 속행된다.

Function GetPlayerID(PlayerName As String, PlayerHandle As String) _
        as Long

  On Error GoTo FAILEDCREATEPLAYER
  GetPlayerID = gObjDPlay.CreatePlayer(PlayerName, PlayerHandle, 0, 0)
  On Error GoTo 0

  '이 섹션의 코드는, CreatePlayer 가 성공했을 경우에게만 실행된다.
  .
  .
  .
  Exit Function

FAILEDCREATEPLAYER:

  If Err.Number = DPERR_INVALIDPLAYER Then
      MsgBox ("Not a valid player. ")
  Else
      MsgBox("Unidentified player creation error. ")
  End If
  GetPlayerID = 0

End Function


DirectX 클래스의 레퍼런스

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[Visual Basic]

여기에서는, DirectX 의 모든 컴퍼넌트에 공통의 이하의 클래스에 관한 레퍼런스를 제공한다.

  • DirectX7
  • DirectXEvent


DirectX7

DirectX7 클래스는, DirectX 컴퍼넌트 기술의 최초의 입구로서 기능한다. 이 클래스에는, DirectDraw®, Direct3D®, DirectSound®, DirectInput®, DirectPlay®, 및 DirectMusic® 어플리케이션 프로그래밍 인터페이스의 메인 오브젝트를 생성 하는 메소드가 포함된다. 또, 다양한 DirectX 컴퍼넌트로 사용되는 글로벌 메소드도 포함되어 있다.

일반적으로, 이 클래스의 인스턴스는 DirectX 어플리케이션으로 최초로 생성 되는 오브젝트이다. 이것은, 다음의 예의 같게 오브젝트 변수를 New 로서 선언하는 것으로 취득할 수 있다.

Public objDX7 As New DirectX7

DirectX7 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

오브젝트 생성 | Direct3DRMCreate
 | DirectDrawCreate
 | DirectInputCreate
 | DirectMusicComposerCreate
 | DirectMusicLoaderCreate
 | DirectMusicPerformanceCreate
 | DirectPlayCreate
 | DirectPlayLobbyCreate
 | DirectSoundCaptureCreate
 | DirectSoundCreate
열거 | GetDDEnum
 | GetDSCaptureEnum
 | GetDSEnum
컬러 관리 | ColorGetAlpha
 | ColorGetBlue
 | ColorGetGreen
 | ColorGetRed
 | CreateColorRGB
 | CreateColorRGBA
벡터 관리 | VectorAdd
 | VectorCopy
 | VectorCrossProduct
 | VectorDotProduct
 | VectorModulus
 | VectorNormalize
 | VectorRandom
 | VectorReflect
 | VectorRotate
 | VectorScale
 | VectorSubtract
버텍스 관리 | CreateD3DLVertex
 | CreateD3DTLVertex
 | CreateD3DVertex
행렬 | CopyMatrix
 | IdentityMatrix
 | MatrixFromQuaternion
 | MatrixMultiply
 | ProjectionMatrix
 | QuaternionMultiply
 | QuaternionRotation
 | QuaternionSlerp
 | RotateXMatrix
 | RotateYMatrix
 | RotateZMatrix
 | ViewMatrix
 | ZeroMatrix
그 외 | CreateEvent
 | CreateNewGuid
 | DestroyEvent
 | GetWindowRect
 | SetEvent
 | SystemBpp
 | TickCount


DirectX7.ColorGetAlpha

DirectX7.ColorGetAlpha 메소드는, 색의 알파 성분을 취득한다.

object. ColorGetAlpha(color As Long) As Single

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
color
알파 성분을 취득하는 색. 값의 범위는, 0~255 이다.

반환값

성공하면, 알파값을 돌려준다. 실패하면, 0 을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectX7.ColorGetBlue ,DirectX7.ColorGetGreen ,DirectX7.ColorGetRed


DirectX7.ColorGetBlue

DirectX7.ColorGetBlue 메소드는, 색의 파랑 성분을 취득한다.

object. ColorGetBlue(color As Long) As Single

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
color
파랑 성분을 취득하는 색. 값의 범위는, 0~255 이다.

반환값

성공하면, 파랑의 값을 돌려준다. 실패하면, 0 을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectX7.ColorGetAlpha ,DirectX7.ColorGetGreen ,DirectX7.ColorGetRed


DirectX7.ColorGetGreen

DirectX7.ColorGetGreen 메소드는, 색의 초록 성분을 취득한다.

object. ColorGetGreen(color As Long) As Single

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
color
초록 성분을 취득하는 색. 값의 범위는, 0~255 이다.

반환값

성공하면, 초록의 값을 돌려준다. 실패하면, 0 을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectX7.ColorGetAlpha ,DirectX7.ColorGetBlue ,DirectX7.ColorGetRed


DirectX7.ColorGetRed

DirectX7.ColorGetRed 메소드는, 색의 빨강 성분을 취득한다.

object. ColorGetRed(color As Long) As Single

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
color
빨강 성분을 취득하는 색. 값의 범위는, 0~255 이다.

반환값

성공하면, 빨강의 값을 돌려준다. 실패하면, 0 을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectX7.ColorGetAlpha ,DirectX7.ColorGetGreen ,DirectX7.ColorGetBlue


DirectX7.CopyMatrix

DirectX7.CopyMatrix 메소드는, 소스 행렬을 목적지 행렬에 카피한다.

object. CopyMatrix(mDest As D3DMATRIX, _
    mSrc As D3DMATRIX)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
mDest
행렬의 카피가 저장 되는 D3DMATRIX 형.
mSrc
카피되는 소스 행렬의 D3DMATRIX 형.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.CreateColorRGB

DirectX7.CreateColorRGB 메소드는, 지정된 적, 초록, 파랑의 성분으로부터 RGB 색을 생성 한다.

object. CreateColorRGB(r As Single, _
    g As Single, _
    b As Single) As Long

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
r, g,및 b
RGB 색의 성분.

반환값

성공하면, 새로운 RGB 값을 돌려준다. 실패하면, 0 을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectX7.CreateColorRGBA


DirectX7.CreateColorRGBA

DirectX7.CreateColorRGBA 메소드는, 지정된 적, 록, 청, 알파 성분으로부터 RGBA 색을 생성 한다.

object. CreateColorRGBA(r As Single, _
    g As Single, _
    b As Single, _
    a As Single) As Long

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
r, g, b,및 a
RGBA 색의 성분. 값의 범위는, 0~1 이다.

반환값

성공하면, 새로운 RGBA 값을 돌려준다. 실패하면, 0 을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectX7.CreateColorRGB


DirectX7.CreateD3DLVertex

DirectX7.CreateD3DLVertex 메소드는, 각각이 버텍스 성분을 나타내는 값을 사용해 D3DLVERTEX 형을 설정한다.

object. CreateD3DLVertex(x As Single, _
    y As Single, _
    z As Single, _
    color As Long, _
    specular As Long, _
    tu As Single, _
    tv As Single, _
    v As D3DLVERTEX)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
x,y, 및 z
버텍스의 x, y, z 좌표를 나타내는 값.
color 및 specular
버텍스의 디퓨즈색과 스펙큐러색의 RGBA 표기법을 지정하는 값. DirectX7.CreateColorRGBA 메소드를 사용하면, 개별의 적, 록, 청, 알파 성분으로부터 목적의 컬러값을 생성할 수 있다.
tu 및 tv
버텍스의 u 및 v 텍스쳐 좌표를 기술한 값.
v
지정된 버텍스의 컴퍼넌트 데이터가 설정된 D3DLVERTEX 형의 변수.

에러 코드

실패하면 에러가 발생해,Err.Number 에 에러 코드가 설정된다.

참조

DirectX7.CreateD3DVertex ,DirectX7.CreateD3DTLVertex


DirectX7.CreateD3DTLVertex

DirectX7.CreateD3DTLVertex 메소드는, 별개의 버텍스 성분을 나타내는 각각의 값을 사용해,D3DTLVERTEX 형을 설정한다.

object. CreateD3DTLVertex(sx As Single, _
    sy As Single, _
    sz As Single, _
    rhw As Single, _
    color As Long, _
    specular As Long, _
    tu As Single, _
    tv As Single, _
    v As D3DTLVERTEX)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
sx,sy, 및 sz
화면 좌표로 버텍스의 위치를 기술한 값.
rhw
버텍스의 동차 W 의 역수.
color 및 specular
버텍스의 디퓨즈색과 스펙큐러색의 RGBA 표기법을 지정하는 값. DirectX7.CreateColorRGBA 메소드를 사용하면, 개별의 적, 록, 청, 알파 성분으로부터 목적의 컬러값을 생성할 수 있다.
tu 및 tv
버텍스의 u 및 v 텍스쳐 좌표를 기술한 값.
v
지정된 버텍스의 성분 데이터가 설정된 D3DTLVERTEX 형의 변수.

에러 코드

실패하면 에러가 발생해,Err.Number 에 에러 코드가 설정된다.

참조

DirectX7.CreateD3DVertex ,DirectX7.CreateD3DTLVertex


DirectX7.CreateD3DVertex

DirectX7.CreateD3DVertex 메소드는, 별개의 버텍스 성분을 나타내는 각각의 값을 사용해 D3DVERTEX 형을 설정한다.

object. CreateD3DVertex(x As Single, _
    y As Single, _
    z As Single, _
    nx As Single, _
    ny As Single, _
    nz As Single, _
    tu As Single, _
    tv As Single, _
    v As D3DVERTEX)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
x,y, 및 z
버텍스의 x, y, z 좌표를 나타내는 값.
nx,ny, 및 nz
버텍스의 정규 벡터의 방향을 기술한 값.
tu 및 tv
버텍스의 u 및 v 텍스쳐 좌표를 기술한 값.
v
지정된 버텍스의 성분 데이터가 설정된 D3DVERTEX 형의 변수.

에러 코드

실패하면 에러가 발생해,Err.Number 에 에러 코드가 설정된다.

참조

DirectX7.CreateD3DLVertex ,DirectX7.CreateD3DTLVertex


DirectX7.CreateEvent

DirectX7.CreateEvent 메소드는, 폼에 이행 된 이벤트 오브젝트에의 핸들을 돌려준다.

object. CreateEvent(event As DirectXEvent) As Long

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
event
폼에 이행 된 DirectXEvent 오브젝트.

반환값

성공하면, 생성 된 이벤트에의 핸들을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

DirectX 로부터의 통지를 받기 위해서(때문에)는,DirectXEvent 오브젝트가 폼에 의해 이행되어 있지 않으면 안 된다. 생성 된 이벤트 핸들은, DirectSound, DirectMusic, DirectPlay, 및 DirectInput 의 통지 메소드로 사용된다.

DirectX 는, 이벤트 오브젝트를, 해당하는 이벤트가 발생하면(자) 신호를 보내도록(듯이) 자동적으로 설정한다. DirectX7.SetEvent 메소드를 사용하면, 이벤트를 수동에서도 설정할 수 있다. 이것은, 이벤트 처리 코드를 테스트할 경우에 행해진다.

생성 한 이벤트는 모두, 생성원어플리케이션에 의해 DirectX7.DestroyEvent 를 호출해 명시적으로 파기할 필요가 있다. 이 요건을 채우지 않으면, 미정도리의 동작을 할 가능성이 있다.

참조

DirectX7.SetEvent ,DirectX7.DestroyEvent ,DirectSoundBuffer.SetNotificationPositions ,DirectSoundCaptureBuffer.SetNotificationPositions ,DirectInputDevice.SetEventNotification ,DirectPlayLobby3.SetLobbyMessageEvent ,DirectMusicPerformance.SetNotificationHandle


DirectX7.CreateNewGuid

DirectX7.CreateNewGuid 메소드는, 글로벌 유니크 식별자를 생성한다.

object. CreateNewGuid() As String

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.

반환값

성공하면, GUID 를 캐릭터 라인 형식에서 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

GUID 의 사용


DirectX7.DestroyEvent

DirectX7.DestroyEvent 메소드는,DirectX7.CreateEvent 메소드에 의해 생성 된 이벤트 핸들을 삭제한다.

object. DestroyEvent(eventid As Long)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
eventid
DirectX7.CreateEvent 로부터 돌려주어진 파기하는 이벤트의 핸들.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.Direct3DRMCreate

DirectX7.Direct3DRMCreate 메소드는,Direct3DRM3 오브젝트의 인스턴스를 생성 한다.

object. Direct3DRMCreate() As Direct3DRM3

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.

반환값

성공하면,Direct3DRM3 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.DirectDrawCreate

DirectX7.DirectDrawCreate 메소드는,DirectDraw7 오브젝트를 생성 한다.

object. DirectDrawCreate(guid As String) As DirectDraw7

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
guid
생성 하는 드라이버를 나타내는 글로벌 유니크 식별자 (GUID)의 주소. 하늘의 캐릭터 라인을 지정하면 액티브한 디스플레이 드라이버를 나타내, 다음의 플래그의 어느쪽이든을 지정하면 디버그를 위해서(때문에) 액티브한 디스플레이 드라이버의 동작을 제한할 수 있다.
DDCREATE_EMULATIONONLY
DirectDraw 오브젝트는, 모든 기능으로 열거를 사용한다. 하드웨어로 지원 되고 있는 기능은 사용하지 않는다.
DDCREATE_HARDWAREONLY
DirectDraw 오브젝트는, 하드웨어로 지원되어 있지 않은 기능은 열거하지 않는다. 지원되어 있지 않은 기능이 필요한 메소드를 호출하려고 하면 실패해,DDERR_UNSUPPORTED 를 돌려준다.

반환값

성공하면,DirectDraw7 오브젝트에의 레퍼런스를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.DirectInputCreate

DirectX7.DirectInputCreate 메소드는,DirectInput 오브젝트를 생성 한다.

object. DirectInputCreate() As DirectInput

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectInput 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_BETADIRECTINPUTVERSION
DIERR_INVALIDPARAM
DIERR_OLDDIRECTINPUTVERSION
DIERR_OUTOFMEMORY


DirectX7.DirectMusicComposerCreate

DirectX7.DirectMusicComposerCreate 메소드는, 작곡가 오브젝트를 생성 할 경우에 사용된다.

object. DirectMusicComposerCreate() As DirectMusicComposer

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.

반환값

이 메소드는,DirectMusicComposer 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.DirectMusicLoaderCreate

DirectX7.DirectMusicLoaderCreate 메소드를 사용해, 로더 오브젝트를 생성 할 경우에 사용된다.

object. DirectMusicLoaderCreate() As DirectMusicLoader

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.

반환값

이 메소드는,DirectMusicLoader 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.DirectMusicPerformanceCreate

DirectX7.DirectMusicPerformanceCreate 메소드는, 퍼포먼스 오브젝트를 생성 할 경우에 사용된다.

object. DirectMusicPerformanceCreate() _
    As DirectMusicPerformance

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.

반환값

이 메소드는,DirectMusicPerformance 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.DirectPlayCreate

DirectX7.DirectPlayCreate 메소드는,DirectPlay4 오브젝트를 생성 한다.

object. DirectPlayCreate(guid As String) As DirectPlay4

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
guid
DirectPlay4 오브젝트에 바인드 되는 서비스 프로바이더를 지정하는 GUID, 또는 하늘의 캐릭터 라인. 「주의」를 참조할것.

반환값

성공하면,DirectPlay4 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

guid 파라미터가 하늘의 캐릭터 라인의 경우, DirectPlay 접속은 초기화되지 않기 때문에, 어플리케이션은 DirectPlay4.InitializeConnection 를 호출할 필요가 있다.

참조

GUID 의 사용


DirectX7.DirectPlayLobbyCreate

DirectX7.DirectPlayLobbyCreate 메소드는,DirectPlayLobby3 오브젝트를 생성 한다.

object. DirectPlayLobbyCreate() As DirectPlayLobby3

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectPlayLobby3 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.DirectSoundCaptureCreate

DirectX7.DirectSoundCaptureCreate 메소드는,DirectSoundCapture 오브젝트를 생성 한다.

object. DirectSoundCaptureCreate(guid As String) _
    As DirectSoundCapture

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
guid
사운드 캡춰 디바이스를 지정하는 GUID. 이 파라미터의 값은,DirectX7.GetDSCaptureEnum 를 호출해 돌려주어지는 GUID 가 아니면 안된다. 디폴트의 디바이스를 지정 하면나무는, 이 파라미터에 하늘의 캐릭터 라인을 지정한다.

반환값

성공하면,DirectSoundCapture 오브젝트에의 레퍼런스를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_INVALIDPARAM
DSERR_NOAGGREGATION
DSERR_OUTOFMEMORY

주의

이 메소드는, 전이중이 지원되어 있지 않은 사운드 카드의 경우 실패한다. DirectX7.DirectSoundCreate 를 호출하면, 지원되어 있지 않은 캡춰 주파수가 캡춰 디바이스로 설정되어DirectX7.DirectSoundCaptureCreate 가 실패한다.


DirectX7.DirectSoundCreate

DirectX7.DirectSoundCreate 메소드는,DirectSound 오브젝트를 생성 한다.

object. DirectSoundCreate(guid As String) As DirectSound

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
guid
사운드 캡춰 디바이스를 지정하는 GUID. 이 파라미터의 값은,DirectSoundEnum.GetGuid 를 호출하는 것으로 돌려주어지는 GUID 가 아니면 안된다. 디폴트의 디바이스를 지정 하면나무는, 이 파라미터에 하늘의 캐릭터 라인을 지정한다.

반환값

성공하면,DirectSound 오브젝트에의 레퍼런스를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_ALLOCATED
DSERR_INVALIDPARAM
DSERR_NOAGGREGATION
DSERR_NODRIVER
DSERR_OUTOFMEMORY


DirectX7.GetDDEnum

DirectX7.GetDDEnum 메소드는, 프라이머리 DirectDraw 디스플레이 디바이스나 비디스플레이 디바이스 (2D 능력이 없는 3D 가속기등)가 인스톨 되고 있는 경우에, 그것을 열거할 경우에 사용되는 DirectDrawEnum 오브젝트를 생성 한다.

object. GetDDEnum() As DirectDrawEnum

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectDrawEnum 오브젝트에의 레퍼런스를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DDERR_OUTOFMEMORY 에러값이 설정된다.


DirectX7.GetDSCaptureEnum

DirectX7.GetDSCaptureEnum 메소드는, 시스템에 인스톨 되고 있는 DirectSoundCapture 오브젝트를 열거할 경우에 사용되는 DirectSoundEnum 오브젝트를 생성한다.

object. GetDSCaptureEnum() As DirectSoundEnum

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectSoundEnum 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_OUTOFMEMORY 가 설정된다.

참조

DirectX7.GetDSEnum


DirectX7.GetDSEnum

DirectX7.GetDSEnum 메소드는, 시스템에 인스톨 되고 있는 DirectSound 드라이버를 열거할 경우에 사용되는 DirectSoundEnum 오브젝트를 생성 한다.

object. GetDSEnum() As DirectSoundEnum

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectSoundEnum 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_OUTOFMEMORY 가 설정된다.

참조

DirectX7.GetDSCaptureEnum


DirectX7.GetWindowRect

DirectX7.GetWindowRect 메소드는, 윈도우의 클라이언트 영역을 기술한 직사각형을 취득한다.

object. GetWindowRect(hwnd As Long, r As RECT)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
hwnd
클라이언트 영역의 직사각형을 취득하는 윈도우의 윈도우 핸들.
r
메소드가 성공했을 경우에 윈도우의 클라이언트 영역이 설정되는 RECT 형의 변수.

에러 코드

실패하면 에러가 발생해,Err.Number 에 에러 코드가 설정된다.


DirectX7.IdentityMatrix

DirectX7.IdentityMatrix 메소드는, 단위행렬을 생성 한다.

object. IdentityMatrix(mDest As D3DMATRIX)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
mDest
조작 결과인 D3DMATRIX 형.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

단위행렬은,[1,1][2,2][3,3][4,4] 계수에 1.0 이 설정되어 있는 것 제외해, 모든 계수가 0.0 의 행렬이다. 단위행렬은, 버텍스에 적용되어도 그것들이 변경되지 않는다고 하는 점으로써 특별하다. 단위행렬은, 버텍스값을 변경해 회전, 평행이동, 및 4×4 행렬로 표현할 수 있는 그 외의 변환을 실시하는 행렬의 기점으로서 사용된다.


DirectX7.MatrixFromQuaternion

DirectX7.MatrixFromQuaternion 메소드는, 쿼터니온이 나타내는 회전의 행렬을 산출한다.

object. MatrixFromQuaternion(matrix As D3DMATRIX, _
    quat As D3DRMQUATERNION)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
matrix
함수가 돌아왔을 때에 산출된 행렬.
quat
D3DRMQUATERNION 형.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.MatrixMultiply

DirectX7.MatrixMultiply 메소드는, 2 개의 행렬의 적을 산출한다.

object. MatrixMultiply(mDest As D3DMATRIX, _
    mA As D3DMATRIX, _
    mB As D3DMATRIX)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
mDest
mA 행렬과 mB 행렬의 적이 저장 되는 D3DMATRIX 형.
mA
피승수로서 지정하는 D3DMATRIX 형.
mB
승수로서 지정하는 D3DMATRIX 형.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

이것을 적합 가능하게 하려면 ,mA 행렬의 렬수와 mB 행렬의 행수를 같게 할 필요가 있다.


DirectX7.ProjectionMatrix

DirectX7.ProjectionMatrix 메소드는, 근처먼 클립면과 시야의 각도를 설정한다.

object. ProjectionMatrix(mDest As D3DMATRIX, _
    nearPlane As Single, _
    farPlane As Single, _
    fov As Single)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
mDest
새롭고 생성 된 투영 행렬.
nearPlane
가까이의 클립면까지의 거리. 단위는, 어플리케이션에 고유하다.
farPlane
먼 클립면까지의 거리. 단위는, 어플리케이션에 고유하다.
fov
시야의 각도 (라디안 단위).

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

fov 는, 투영기의 중심으로부터 전방 클립면의 중심에의 직선과 투영기의 중심으로부터 전방 클립면의 최상부에의 직선을 드로잉(Drawing) 해, 그 결과의 각도를 2 배로 하는 것으로 산출할 수 있다.


DirectX7.QuaternionMultiply

DirectX7.QuaternionMultiply 메소드는, 2 개의 쿼터니온 타입의 적을 산출한다.

object. QuaternionMultiply(quat As D3DRMQUATERNION, _
    quatA As D3DRMQUATERNION, _
    quatB As D3DRMQUATERNION)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
quat
곱셈의 적이 저장 되는 D3DRMQUATERNION 형.
quatA 및 quatB
곱셈하는 D3DRMQUATERNION 형.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.QuaternionRotation

DirectX7.QuaternionRotation 메소드는, 지정축을 회전축으로 한 지정 라디안수의 회전을 나타내는 쿼터니온을 취득한다.

object. QuaternionRotatation(quat As D3DRMQUATERNION, _
    axis As D3DVECTOR, _
    theta As Single)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
quat
조작 결과가 저장 되는 D3DRMQUATERNION 형.
axis
회전의 축을 지정하는 D3DVECTOR 형.
theta
axis 파라미터에 의해 지정된 축을 회전축으로서 회전하는 라디안수.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.QuaternionSlerp

DirectX7.QuaternionSlerp 메소드는, 구(공) 선형 보간을 사용해 2 개의 쿼터니온 타입간을 선형 보간 한다.

object. QuaternionSlerp(quat As D3DRMQUATERNION, _
    quatA As D3DRMQUATERNION, _
    quatB As D3DRMQUATERNION, _
    alpha As Single)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
quat
보간이 저장 되는 D3DRMQUATERNION 형.
quatA 및 quatB
각각 보간의 기점과 종점으로서 사용하는 D3DRMQUATERNION 형.
alpha
quatA 와 quatB 간을 선형 보간 하면나무의 정도를 지정하는 0~1 의 값.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.RotateXMatrix

DirectX7.RotateXMatrix 메소드는, x 축을 회전축으로서 점 (x, y, z)을 회전해, 새로운 점 (x', y', z')을 생성한다.

object. RotateXMatrix(mDest As D3DMATRIX, _
    radians As Single)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
mDest
변환 결과가 저장 되는 D3DMATRIX .
radians
회전의 각도 (라디안 단위). 각도는, 회전축으로부터 원점을 봐 시계회전에 계측 한다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectX7.RotateYMatrix ,DirectX7.RotateZMatrix .


DirectX7.RotateYMatrix

DirectX7.RotateYMatrix 메소드는, y 축을 회전축으로서 점 (x, y, z)을 회전해, 새로운 점 (x', y', z')을 생성한다.

object. RotateYMatrix(mDest As D3DMATRIX, _
    radians As Single)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
mDest
변환 결과가 저장 되는 D3DMATRIX .
radians
회전의 각도 (라디안 단위). 각도는, 회전축으로부터 원점을 봐 시계회전에 계측 한다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectX7.RotateXMatrix ,DirectX7.RotateZMatrix .


DirectX7.RotateZMatrix

DirectX7.RotateZMatrix 메소드는, z 축을 회전축으로서 점 (x, y, z)을 회전해, 새로운 점 (x', y', z')을 생성한다.

object. RotateZMatrix(mDest As D3DMATRIX, _
    radians As Single)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
mDest
변환 결과가 저장 되는 D3DMATRIX .
radians
회전의 각도 (라디안 단위). 각도는, 회전축으로부터 원점을 봐 시계회전에 계측 한다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectX7.RotateYMatrix ,DirectX7.RotateXMatrix .


DirectX7.SetEvent

DirectX7.SetEvent 는, 이벤트 오브젝트 상태를 신호 발신 끝나로 설정한다.

object. SetEvent(eventid As Long)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
eventid
신호 발신이 끝난 상태로서 설정하는 이벤트 핸들.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

이 메소드는,DirectX7.CreateEvent 에 의해 생성 된 이벤트 핸들을 사용해 호출할 필요가 있다.

DirectX 는, 해당하는 이벤트가 발생 하면, 생성 된 모든 이벤트 오브젝트를 신호 발신 끝나에 자동 설정한다. 이 메소드는, 주로 테스트시의 사용을 목적으로 하고 있다.


DirectX7.SystemBpp

DirectX7.SystemBpp 메소드는, 시스템의 픽셀 근처의 현재 비트수를 돌려준다.

object. SystemBpp() As Long

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 시스템의 픽셀 근처의 현재 비트수를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.TickCount

DirectX7.TickCount 메소드는, 시스템의 틱수를 돌려준다.

object. TickCount() As Long

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 시스템의 틱수를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.VectorAdd

DirectX7.VectorAdd 메소드는, 2 개의 벡터를 덧셈 한다.

object. VectorAdd(v As D3DVECTOR, _
    vA As D3DVECTOR, _
    vB As D3DVECTOR)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
v
덧셈 결과가 저장 되는 D3DVECTOR 형.
vA 및 vB
덧셈 하는 D3DVECTOR 형.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.VectorCopy

DirectX7.VectorCopy 메소드는, 벡터를 카피한다.

object. VectorCopy(vDest As D3DVECTOR, _
    vSrc As D3DVECTOR)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
vDest
카피처 D3DVECTOR .
vSrc
카피원 D3DVECTOR.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.VectorCrossProduct

DirectX7.VectorCrossProduct 메소드는, 2 개의 벡터 인수의 외적을 산출한다.

object. VectorCrossProduct(v As D3DVECTOR, _
    vA As D3DVECTOR, _
    vB As D3DVECTOR)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
v
외적이 저장 되는 D3DVECTOR 형.
vA 및 vB
외적을 산출하는 D3DVECTOR 형.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.VectorDotProduct

DirectX7.VectorDotProduct 메소드는, 벡터의 내적을 돌려준다.

object. VectorDotProduct(vA As D3DVECTOR, _
    vB As D3DVECTOR) As Single

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
vA 및 vB
내적을 산출하는 D3DVECTOR 형.

반환값

성공하면, 내적의 결과를 돌려준다. 실패했을 경우는, 0 을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.VectorModulus

DirectX7.VectorModulus 메소드는, 벡터의 크기를 돌려준다.

object. VectorModulus(vA As D3DVECTOR) As Single

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
vA
길이를 돌려주는 D3DVECTOR 형.

반환값

성공하면,D3DVECTOR 형의 길이를 돌려준다. 실패하면, 0 을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

이 메소드는, 다음의 식을 사용해 벡터의 크기를 산출한다.


DirectX7.VectorNormalize

DirectX7.VectorNormalize 메소드는, 절대치를 1 으로서 벡터를 스케일링 한다.

object. VectorNormalize(v As D3DVECTOR)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
v
스케일링 처리의 결과가 저장 되는 D3DVECTOR 형.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.VectorRandom

DirectX7.VectorRandom 메소드는, 랜덤의단위벡터를 돌려준다.

object. VectorRandom(v As D3DVECTOR)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
v
랜덤의 단위벡터가 저장 되는 D3DVECTOR 형.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.VectorReflect

DirectX7.VectorReflect 메소드는, 지정된 법선에 대한 반사 벡터를 돌려준다.

object. VectorReflect(vDest As D3DVECTOR, _
    vRay As D3DVECTOR, _
    vNormal As D3DVECTOR)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
vDest
처리 결과가 저장 되는 D3DVECTOR 형.
vRay
법선에 대해서 반사하는 D3DVECTOR 형.
vNormal
vRay 로 지정한 벡터를 반사할 경우에 기준이 되는 법선을 지정한 D3DVECTOR 형.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.VectorRotate

DirectX7.VectorRotate 메소드는, 지정된 축을 회전축으로서 벡터를 회전한다. 성공했을 경우, 정규화한 벡터를 돌려준다.

object. VectorRotate(vDest As D3DVECTOR, _
    vA As D3DVECTOR, _
    vAxis As D3DVECTOR, _
    theta As Single)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
vDest
정규화의 결과가 저장 되는 D3DVECTOR 형.
vA
지정된 축을 회전축으로서 회전되는 D3DVECTOR 형.
vAxis
회전축인 D3DVECTOR 형.
theta
회전 각도 (라디안 단위).

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.VectorScale

DirectX7.VectorScale 메소드는, 벡터를 3 개의 축 모두에게 한결같게 스케일링 한다.

object. VectorScale(vDest As D3DVECTOR, _
    vA As D3DVECTOR, _
    factor As Single)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
vDest
처리 결과가 저장 되는 D3DVECTOR 형.
vA
스케일링 대상의 D3DVECTOR 형.
factor
스케일링 계수. 값이 1 의 경우, 스케일링은 변함없다. 값이 2 의 경우, 스케일링은 2 배가 된다. 이하 같이이다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.VectorSubtract

DirectX7.VectorSubtract 메소드는, 2 개의 벡터의 차분을 취한다.

object. VectorSubtract(v As D3DVECTOR, _
    vA As D3DVECTOR, _
    vB As D3DVECTOR)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
v
처리 결과가 저장 되는 D3DVECTOR 형.
vA
vB 를 나눗셈 하는 D3DVECTOR 형.
vB
vA 로부터 나눗셈 하는 D3DVECTOR 형.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.ViewMatrix

DirectX7.ViewMatrix 메소드는, 지정된 카메라의 위치에 근거해 뷰 행렬을 생성 한다.

object. ViewMatrix(mDest As D3DMATRIX, _
    vFrom As D3DVECTOR, _
    vTo As D3DVECTOR, _
    vUp As D3DVECTOR, _
    roll As Single)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
mDest
새롭게 생성 되는 뷰 행렬.
vFrom
카메라의 위치를 정의하는 D3DVECTOR 형.
vTo
카메라의 목시 대상을 정의한 D3DVECTOR 형.
vUp
현재 월드의 높이를 정의한 D3DVECTOR 형. 보통은,[0, 1, 0] 이다.
roll
목시 방향을 회전축으로 한 시계회전의 회전 (라디안 단위).

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectX7.ZeroMatrix

DirectX7.ZeroMatrix 메소드는, 행렬의 모든 멤버에 0 을 설정한다.

object. ZeroMatrix(mDest As D3DMATRIX)

파라미터

object
DirectX7 오브젝트를 나타내는오브젝트식.
mDest
처리 결과가 저장 되는 D3DMATRIX 형.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectXEvent

DirectXEvent 클래스는, DirectSound, DirectMusic, DirectPlay, 및 DirectInput 로 사용하는 이벤트 오브젝트를 생성 한다. DirectXEvent 오브젝트는, 클래스를 폼에 이행 하는 것으로 생성 된다. 이 클래스의 목적은, 통지 이벤트를 처리하기 위한 콜백 메소드를 제공하는 것에 있다.

DirectXEvent 클래스에는,DirectXEvent.DXCallback 라고 하는 메소드가 1 개만 있다.


DirectXEvent.DXCallback

DirectXEvent.DXCallback 메소드는, 이벤트 핸들에 콜백 루틴을 제공한다.

object. DXCallback(eventid As Long)

파라미터

object
DirectXEvent 오브젝트를 나타내는오브젝트식.
eventid
이벤트에의 핸들.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

폼에 DirectXEvent 를 이행 하면나무는,DirectXEvent.DXCallback 메소드도 이행 할 필요가 있다. [Object] 박스의 [DirectXEvent] 와 [Procedures/Events] 박스의 [DXCallback] 를 클릭 하면,[Code] 윈도우에 메소드의 선언과 종료 코드가 자동적으로 설정된다. 다음에, 메소드의 형식을 나타낸다.

Private Sub DirectXEvent_DXCallBack(ByVal eventid as Long)
  '각자의 이벤트 처리 코드를 추가한다.
  .
  .
  .
End Sub

이 메소드에 건네주는 이벤트 핸들은, 유저가 DirectX7.CreateEvent 를 사용해 생성 한 것이다.

참조

DirectX7.SetEvent


참고 자료

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

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

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

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

DirectX 7 을 사용할 때의 노하우나 힌트등을 포함한 최신의 기술 문서에 대해서는,http://www.microsoft.com/japan/developer/directx/ 의 「Technical Articles」를 참조할것.


Direct3D 직접 모드

Direct3D® 직접 모드 어플리케이션 프로그래밍 인터페이스 (API)는, DirectX® 의 3 차원 (3D) 그래픽스 컴퍼넌트의 일부이다. 여기에서는, Direct3D 직접 모드에 대해, 이하의 주제로 나누어 설명한다.

  • Direct3D 직접 모드에 대해
  • Direct3D 직접 모드를 사용하는 이유
  • 직접 모드의 기초지식
  • Direct3D 직접 모드 아키텍쳐
  • Direct3D 직접 모드의 요점
  • Direct3D 직접 모드 튜토리얼
  • Direct3D 직접 모드 레퍼런스
  • Direct3D 직접 모드의 툴과 샘플


Direct3D 직접 모드에 대해

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

Direct3D 에는, 직접 모드 및 보관 유지 모드의 2 개의 모드가 있다. 보관 유지 모드는, 단시간에서의 개발을 필요로 하거나 계층 구조나 애니메이션용으로 보관 유지 모드가 지원 하는 기능을 이용하는 프로그래머전용의, 상위 레벨 3D API (application programming interface)이다.

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

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

  • 바꾸고 가능한 깊이 버퍼링 (Z 버퍼 또는 W 버퍼를 사용)
  • 플랫 및 gouraud shading
  • 복수의 광원과 라이트 타입
  • MIP Mapping 등, 머트리얼 및 텍스쳐의 완전 지원
  • 강력한 소프트웨어 에뮬레이션 드라이버
  • 트랜스 폼과 클리핑
  • 하드웨어비의존성
  • Windows 95, Windows 98, 및 Windows 2000 의 완전 지원
  • Intel 의 MMX 아키텍쳐의 지원

보관 유지 모드 대신에 직접 모드를 사용하는 개발자는, 일반적으로는 하이 퍼포먼스 프로그래밍의 경험이 있어, 3D 그래픽스를 경험하고 있을지도 모른다. 이 SDK 부속의 샘플 코드는, 직접 모드에 대해 이해하기 위한 최선의 정보원이다. 샘플 코드는, 실제의 어플리케이션에서의 Direct3D 직접 모드의 사용 방법을 나타낸다.


Direct3D 직접 모드를 사용하는 이유

직접 모드의 월드 관리는, 버텍스, 다각형, 및 이것들을 제어하는 커멘드에 근거해 행해진다. 이것에 의해, 트랜스 폼, 라이팅, 라스터화 3D 그래픽스 파이프라인에 직접 액세스 할 수 있다. 하드웨어 가속화를 이용해 렌더링 할 수 없는 경우, Direct3D 는 강력한 소프트웨어 에뮬레이션 기능을 제공한다. 기존의 3D 어플리케이션을 가지는 개발자나, 어플리케이션과 하드웨어간에 가능한 한 얇은 계층을 두어 최고의 퍼포먼스를 실현할 필요가 있는 개발자는, 보관 유지 모드는 아니고 직접 모드를 사용 하면이야 있고.

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

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


직접 모드의 기초지식

이하의 섹션에서는, 3D 그래픽스를 짜넣는 프로그램을 생성 하기 전에 이해해 둘 필요가 있는 몇개의 기술적 개념에 대해 설명한다. 이러한 내용은 일반적인 것이다. 특정의 주제에 대해서는, 「Direct3D 직접 모드 아키텍쳐」 및 「Direct3D 직접 모드의 요점」을 참조할것.

3D 그래픽스를 생성 한 경험이 있는 경우는, 이하의 섹션으로 Direct3D 에 특정의 정보를 참조할 수 있다.

이 섹션에는 이하의 주제가 있다.

  • 3D 좌표계와 지오메트리
  • 행렬과 트랜스 폼


3D 좌표계와 지오메트리

Direct3D 어플리케이션을 프로그래밍 하려면 , 3D 지오메트리 원리에 대해 이해하고 있을 필요가 있다. 이 섹션에서는, 3D 신의 생성에 대해 가장 중요한 지오메트리 원리에 대해 설명한다. 이하의 토픽에 대해 기술한다.

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

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


3D 좌표계

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

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

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

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

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

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


3D 프리미티브

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

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

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

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


삼각형 라스터화 룰

버텍스로 지정된 점은 스크린 위에의 픽셀과 정확하게 일치하지 않는 것이 많다. 이 경우, 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 다각형의 쉐이딩을 제어하기 위해서 Direct3D 로 사용하는 기법에 대해 설명한다.

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


쉐이딩 모드

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

  • flat 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가 존재하지 않는 것처럼 면이 렌더링 되고 있다.


쉐이딩 모드의 설정

[C++]

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

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

// gouraud shading로 설정한다 (Direct3D 의 디폴트 설정).
hr = lpDev->SetRenderState(D3DRENDERSTATE_SHADEMODE,
                            D3DSHADE_GOURAUD);
if(FAILED(hr))
{
    // 에러 처리 코드
}
[Visual Basic]

Direct3D 에서는, 한 번에 1 개의 쉐이딩 모드 밖에 선택할 수 없다. 디폴트에서는, gouraud shading가 선택되고 있다. Visual Basic 에서는,Direct3DDevice7.SetRenderState 메소드를 호출해 쉐이딩 모드를 변경할 수 있다. state 파라미터를 D3DRENDERSTATE_SHADEMODE 로 설정한다. renderstate 파라미터에는,CONST_D3DSHADEMODE 열거의 멤버를 설정한다. 다음의 샘플 코드는, Direct3D 어플리케이션의 현재의 쉐이딩 모드를, flat shading 모드 또는 gouraud shading 모드로 설정하는 방법을 나타낸다.

'flat shading로 설정한다.
'이 코드에서는, d3dDev 가 Direct3DDevice7 오브젝트에의
'유효한 참조이다고 한다.
On Local Error Resume Next
Call d3dDev.SetRenderState(D3DRENDERSTATE_SHADEMODE, _
                           D3DSHADE_FLAT)

'에러를 조사한다.
If Err.Number <> DD_OK Then
    '에러 처리
End If

'gouraud shading로 설정한다 (Direct3D 의 디폴트 설정).
Call d3dDev.SetRenderState(D3DRENDERSTATE_SHADEMODE, _
                           D3DSHADE_GOURAUD)

If Err.Number <> DD_OK Then
    '에러 처리
End If


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

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

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

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

[C++]

C++ 로 기술된 Direct3D 어플리케이션에서는, 보통, 버텍스에 D3DVERTEX 구조체를 사용한다. D3DVERTEX 구조체의 멤버로, 버텍스의 위치 좌표와 방향을 지정한다. 버텍스의 방향은 버텍스 법선 벡터로 나타난다. 다음의 코드는, 버텍스 법선을 포함 버텍스의 값을 설정하는 방법을 나타낸다. 법선 벡터는 뷰포트의 방향을 향해, 뷰포트는 월드 좌표계의 원점에 있다. 이 예에서는, 버텍스의 위치 좌표는 월드 좌표로 지정되고 있다.

D3DVERTEX lpVertices[3];

// 1 개의 버텍스는 1 개의 구조체로 한 번으로 지정할 수 있다.
lpVertices[0]. x = 0;
lpVertices[0]. y = 5;
lpVertices[0]. z = 5;
lpVertices[0]. nx = 0;    // 법선 벡터의 x 성분.
lpVertices[0]. ny = 0;    // 법선 벡터의 y 성분.
lpVertices[0]. nz = -1;   // 원점의 뒤의 법선을 가리킨다.
lpVertices[0]. tu = 0;    // 텍스쳐를 사용하는 경우에게만 사용.
lpVertices[0]. tv = 0;    // 텍스쳐를 사용하는 경우에게만 사용.

// 버텍스는, 몇개의 D3DOVERLOADS 매크로를 사용하는 것으로써,
// 버텍스 마다 1 행의 코드로 지정할 수도 있다.
lpVertices[1] = D3DVERTEX(D3DVECTOR(-5,-5, 5), D3DVECTOR(0,0,-1), 0,0);
lpVertices[2] = D3DVERTEX(D3DVECTOR(5,-5, 5), D3DVECTOR(0,0,-1), 0,0);
[Visual Basic]

Visual Basic 로 기술된 Direct3D 어플리케이션에서는, 보통, 버텍스에 D3DVERTEX 형을 사용한다. D3DVERTEX 구조체의 멤버로, 버텍스의 위치 좌표와 방향을 지정한다. 버텍스의 방향은 버텍스 법선 벡터로 나타난다. 다음의 코드는, 버텍스 법선을 포함 버텍스의 값을 설정하는 방법을 나타낸다. 법선 벡터는 뷰포트의 방향을 향해, 뷰포트는 월드 좌표계의 원점에 있다. 이 예에서는, 버텍스의 위치 좌표는 월드 좌표로 지정되고 있다.

D3DVERTEX Vertices(3)

' 1 개의 버텍스에는, 한 번에 1 개의 구조체 멤버를 지정할 수 있다.
Vertices(0). x = 0
Vertices(0). y = 5
Vertices(0). z = 5
Vertices(0). nx = 0    '법선 벡터의 x 성분.
Vertices(0). ny = 0;    '법선 벡터의 y 성분.
Vertices(0). nz = -1;   '원점의 뒤의 법선을 가리킨다.
Vertices(0). tu = 0;    '텍스쳐를 사용하는 경우에게만 사용.
Vertices(0). tv = 0;    '텍스쳐를 사용하는 경우에게만 사용.

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

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

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

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

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

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

[C++]

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

[Visual Basic]

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

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


삼각형 보간 요소

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

  • 색
  • 스펙큐러
  • 알파

이러한 삼각형 보간 요소는 모두, 현재의 쉐이딩 모드에 의해 바뀐다.

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

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

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

C++ 어플리케이션에서는,D3DPRIMCAPS 구조체의 dwShadeCaps 멤버를 사용해, 현재의 드라이버가 지원 하고 있는 보간의 종류를 결정한다. 같이 Visual Basic 어플리케이션에서는,D3DPRIMCAPS 형의 lShadeCaps 멤버를 사용해 이 정보를 이용한다.


행렬과 트랜스 폼

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

  • 행렬
  • 3D 트랜스 폼


행렬

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

Direct3D 에서는, 행렬은 4�4 4 동차 행렬로 나타내져 C++ 의 경우는 D3DMATRIX 구조체, Visual Basic 의 경우는 D3DMATRIX 형으로 정의된다.

[C++]

D3DMATRIX 구조체의 D3D_OVERLOADS (D3DMATRIX (D3D_OVERLOADS) )를 이행 해, 외모 ("()") 연산자를 사용할 수 있다. 이 연산자를 사용하면, 행렬의 값에 간단하게 액세스 할 수 있다. 이름으로 구조체 멤버를 참조할 필요는 없고, 행 및 열번호로 멤버를 참조할 수 있어 필요에 따라서 이 번호를 인덱스로서 사용할 수 있다. 이 인덱스는 0 으로부터 시작되어, 예를 들어, 3 행 2 열의 요소는 M(2, 1)가 된다. D3D_OVERLOADS 연산자를 사용하려면 , D3dtypes.h 헤더 파일을 인클루드 하기 전에 D3D_OVERLOADS 를 정의한다.

또, D3dutil.cpp 소스 파일에는, 행렬의 생성 및 연결을 실시하는 헬퍼-함수가 있다. 헬퍼-함수는 그대로 사용할 수 있다. 또, 헬퍼-함수를 기본으로 독자적인 행렬 처리 함수를 생성 할 수도 있다.

[C++, Visual Basic]


3D 트랜스 폼

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

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

Direct3D 직접 모드에서의 트랜스 폼의 상세한 것에 대하여는, 「지오메트리 파이프라인」을 참조할것.


3D 트랜스 폼에 대해

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

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

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

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

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

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

[C++]

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

D3DMATRIX scale = {
    D3DVAL(s),    0,            0,            0,
    0,            D3DVAL(s),    0,            0,
    0,            0,            D3DVAL(s),    0,
    0,            0,            0,            D3DVAL(1)
};
[Visual Basic]

Visual Basic 의 경우, Direct3D 직접 모드에서는,D3DMATRIX 형을 사용해 2 차원 배열로서 선언된 행렬을 사용한다. 다음의 예는, 한결같은 스케일링을 실시하는 행렬로서 기능하도록(듯이) D3DMATRIX 형을 초기화하는 방법을 나타낸다.

Dim ScaleMatrix As D3DMATRIX

'이 예에서는, s 는 Single 형의 변수이다
With ScaleMatrix
. rc11 = s
. rc22 = s
. rc33 = s
. rc44 = 1
End With


평행이동

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

[C++]

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

D3DMATRIX Translate(const float dx, const float dy, const float dz)
{
D3DMATRIX ret = D3DUtil_SetIdentityMatrix(); // d3dutil.h 에 선언된다.
ret(3, 0) = dx;
ret(3, 1) = dy;
ret(3, 2) = dz;
return ret;
}    // 이동 종료
[Visual Basic]

Visual Basic 에서는, 독자적인 평행이동 행렬을 생성 할 수 있다. 또, 이 SDK 부속의 Math.bas 파일에 있는 TranslateMatrix 헬퍼-서브 루틴을 사용할 수도 있다. 다음의 예는,TranslateMatrix 서브 루틴의 소스 코드를 나타낸다.

Sub TranslateMatrix(m As D3DMATRIX, v As D3DVECTOR)
Call dx.IdentityMatrix(m) ' DirectX7 오브젝트의 메소드.
m.rc41 = v.x
m.rc42 = v.y
m.rc43 = v.z
End Sub


회전

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

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

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

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

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

[C++]

C++ 어플리케이션에서는, D3dutil.cpp 파일내의 D3DUtil_SetRotateXMatrix,D3DUtil_SetRotateYMatrix, 및 D3DUtil_SetRotateZMatrix 헬퍼-함수를 사용해 회전 행렬을 생성 한다 (D3dutil.cpp 파일은 이 SDK 에 부속되어 있다). 다음은,D3DUtil_SetRotateXMatrix 헬퍼-함수의 샘플 코드이다.

VOID D3DUtil_SetRotateXMatrix( D3DMATRIX& mat, FLOAT fRads )
{
D3DUtil_SetIdentityMatrix( mat );
mat. _22 =  cosf( fRads );
mat. _23 =  sinf( fRads );
mat. _32 = -sinf( fRads );
mat. _33 =  cosf( fRads );
}v
[Visual Basic]

Visual Basic 어플리케이션에서는,DirectX7.RotateXMatrix ,DirectX7.RotateYMatrix , 및 DirectX7.RotateZMatrix 메소드를 사용해 회전 행렬을 생성 할 수 있다.

예를 들어, x 축을 중심으로 회전하는 행렬을 수동으로 생성 하는 경우는, 다음과 같은 소스 코드가 된다.

Sub CreateXRotation(ret As D3DMATRIX, rads As Single)
    Dim cosine As Single
    Dim sine As Single
    cosine = Cos(rads)
    sine = Sin(rads)

    Call dx.IdentityMatrix(ret) ' DirectX7 오브젝트의 메소드.

    ret.rc22 = cosine
    ret.rc23 = sine
    ret.rc32 = -sine
    ret.rc33 = cosine
End Sub


스케일링

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


행렬 연결

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

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

C++ 어플리케이션에서는, DirectX SDK. 에 부속되는 D3dmath.cpp 소스 파일을 사용할 수 있다. 이 파일에는 행렬을 곱셈하는 D3DMath_MatrixMultiply 헬퍼-함수가 있다. Visual Basic 어플리케이션의 경우는, 이 SDK 에 부속되는 Math.bas 파일의 MatrixMult 서브 루틴을 사용할 수 있다.

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

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

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

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


Direct3D 직접 모드 아키텍쳐

여기에서는, Direct3D® 직접 모드의 문서의 구성에 관한 고도의 내용에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • 직접 모드 아키텍쳐의 개요
  • 직접 모드 오브젝트 타입
  • 직접 모드 COM 인터페이스


직접 모드 아키텍쳐의 개요

Direct3D 어플리케이션에서는, 보관 유지 모드와 직접 모드의 어느 경우에서도, 같은 방법으로 그래픽스 하드웨어와의 교환을 실시한다. HAL (하드웨어 에뮬레이션 계층)와 상호작용 하기 전에, 소프트웨어 에뮬레이션을 이용하는 경우 또는 이용하지 않는 경우가 있다. Direct3D 는 DirectDraw® 오브젝트에의 인터페이스이기 (위해)때문에, HAL 는 DirectDraw/Direct3D HAL 로 불린다.

Direct3D 는, DirectX® 의 DirectDraw 컴퍼넌트와 밀접하게 통합되고 있다. DirectDraw 표면은, 렌더링 타겟 (프런트 및 백 표면)이나 Z 버퍼로서 사용된다. 실제, Direct3D 인터페이스는, DirectDraw 오브젝트에의 인터페이스이다.


직접 모드 오브젝트 타입

Direct3D 직접 모드는, 일련의 오브젝트로부터 완성된다. C++ 에서는, 이러한 오브젝트를 이용해 버추얼 세계를 조작하거나 Direct3D 어플리케이션을 구축할 수가 있다. Visual Basic 어플리케이션의 경우도, DirectX for Visual Basic 에는 오브젝트 모델에 다소의 차이가 있지만, 최종적으로는 이러한 오브젝트에 액세스 한다.

[C++]
DirectDraw 오브젝트
DirectDraw 오브젝트는, Direct3D 의 기능을 제공한다. IDirect3D,IDirect3D2,IDirect3D3, 및 IDirect3D7 는, DirectDraw 오브젝트에의 인터페이스이다. DirectDraw 오브젝트는 디스플레이 디바이스를 나타내, 디스플레이 디바이스는 Direct3D 의 가장 중요한 기능의 대부분을 이행 하고 있는 것으로부터, Direct3D 의 기능은 DirectDraw 에 짜넣어지고 있다. IDirect3D7 인터페이스는, 종래의 것과는 완전히 다른 오브젝트에의 인터페이스이다. 상세한 것에 대하여는, 「Direct3D 인터페이스」를 참조할것. Direct3D 의 경우와 같이, 어느 메소드를 사용해 DirectDraw 오브젝트를 생성 할까에 의해, 사용할 수 있는 인터페이스는 다르다.

DirectDrawCreateEx 함수를 호출해, 최신의 Direct3D 인터페이스를 지원 하는 DirectDraw 오브젝트를 생성 한다. 상세한 것에 대하여는, 「Direct3D 인터페이스」를 참조할것.

DirectDrawSurface 오브젝트
3D 기능 (DDSCAPS_3DDEVICE)을 사용해 생성 한 DirectDrawSurface 오브젝트는, 표면을 렌더링 타겟으로서 사용하는 Direct3D 디바이스 오브젝트를 생성 하기 위해서 사용할 수 있다. 어플리케이션에서는,IDirect3D7::CreateDevice 메소드를 호출해 표면으로부터 디바이스를 생성 한다.

텍스쳐 맵핑 기능을 사용해 생성 한 DirectDrawSurface 오브젝트에는, Direct3D 어플리케이션으로 장면내의 오브젝트에 텍스쳐를 적용할 때에 사용하는 비트 맵이 포함된다. 어플리케이션에서는, 표면의 IDirectDrawSurface7 인터페이스에의 포인터를 사용해 Direct3D 에의 텍스쳐를 특정한다. 어플리케이션에서는,IDirectDraw7::CreateSurface 메소드를 호출하는 것으로, 텍스쳐를 생성 해 그 인터페이스 포인터를 취득한다 (이 점에 대해서는 이전의 버젼과는 달라, 이전에는 이 메소드로 텍스쳐를 생성 해,IUnknown::QueryInterface 메소드를 호출해 표면의 IDirect3DTexture2 인터페이스를 취득해, IID_IDirect3DTexture2 참조 식별자를 지정했다).

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

Direct3DDevice 오브젝트
Direct3DDevice 오브젝트는, 직접 모드 어플리케이션의 렌더링 스테이트를 캡슐화해 저장 한다. Direct3D 디바이스는, 렌더링 타겟으로서 사용하는 표면에는 의존하지 않고, 이 디바이스를 사용해 복수의 렌더링 타겟 표면을 렌더링 할 수가 있다 (DirectX 5.0 이전으로는 할 수 없었다). DirectX 7.0 에서는, 추천 디바이스 오브젝트는 IDirect3DDevice7 인터페이스이다. Direct3D 어플리케이션에서는,IDirect3D7::CreateDevice 메소드를 호출해 디바이스를 생성 해,IDirect3DDevice7 인터페이스에의 포인터를 취득할 수 있다. 이 방법으로 생성 한 디바이스 오브젝트만, 최신의 인터페이스를 공개한다. 상세한 것에 대하여는, 「디바이스 인터페이스」 및 「Direct3D 디바이스」를 참조할것.

종래와는 달라,IDirect3DDevice7 인터페이스를 공개하는 디바이스 오브젝트는, 머트리얼, 라이트, 및 뷰포트 마다 개별의 오브젝트를 사용하지 않는다. DirectX 7.0 에서는, 이러한 오브젝트는 실제로는 폐지되고 있다. 그 대신해, 이것들 종래의 오브젝트의 기능을 디바이스의 내부 데이터 구조의 일부로서 제공하는 메소드가, 새로운 인터페이스에 포함되어 있다.

Direct3DVertexBuffer 오브젝트
Direct3DVertexBuffer 오브젝트는 메모리 버퍼이며, 이 오브젝트에는 IDirect3DDevice7 인터페이스의 버텍스 버퍼 렌더링 메소드로 렌더링 되는 버텍스가 포함된다. 버텍스 버퍼를 종래의 실행 버퍼 아키텍쳐와 혼동 해 안 된다. 버텍스 버퍼에는 Direct3DDevice 오브젝트에 의해 처리되는 버텍스 데이터만 포함되어 렌더링의 퍼포먼스를 개선하는 기능이 제공된다. 버텍스 버퍼를 생성 해, 그 인터페이스를 취득하려면 ,IDirect3D7::CreateVertexBuffer 메소드를 호출한다.

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

[Visual Basic]

DirectX for Visual Basic 에서는, Direct3D 직접 모드에서의 프로그래밍용으로 이하의 클래스를 공개하고 있다.

DirectX7 클래스
DirectX7 클래스는,Direct3D7 ,DirectDraw7 오브젝트 등, 그 외 모든 컴퍼넌트 레벨의 오브젝트를 생성 하기 위해서 사용하는 오브젝트를 정의한다.
DirectDraw7 클래스
DirectDraw7 클래스의 역할은, 디스플레이 디바이스를 나타내는,Direct3D7 클래스를 생성하는, 및 렌더링용의 텍스쳐와 렌더링 타겟 표면을 생성 하는 것이다. DirectDraw7 클래스의 오브젝트를 생성 하려면 ,DirectX7.DirectDrawCreate 메소드를 호출한다.
DirectDrawSurface7 클래스
DirectDrawSurface7 클래스는, 표시용 또는 텍스쳐 처리용의 화면 데이터, 혹은 Direct3D 디바이스의 렌더링 타겟으로서의 화면 데이터를 저장메모리를 나타낸다. DirectDraw7.CreateSurface 메소드를 호출해 하늘의 표면을 생성 하는지,DirectDraw7.CreateSurfaceFromFile 메소드를 호출해 표면을 생성 해, 그 표면에 비트 맵 파일로부터 화면 데이터를 로드한다.
Direct3D7 클래스
Direct3D7 클래스는, 장면을 렌더링 하는데 필요한 오브젝트를 생성 및 조작하는, Direct3D 의 기능을 제공하는 오브젝트를 정의한다. Direct3D7 클래스의 오브젝트를 생성 하려면 ,DirectDraw7.GetDirect3D 메소드를 호출한다.
Direct3DDevice7 클래스
Direct3DDevice7 클래스는, Visual Basic 로 기술된 직접 모드 어플리케이션의 렌더링 스테이트, 라이팅과 머트리얼의 스테이트, 및 뷰포트 파라미터를 캡슐화해 저장 하는 오브젝트를 정의한다. Direct3DDevice7 클래스의 오브젝트를 생성 하려면 ,Direct3D7.CreateDevice 메소드를 호출한다. 상세한 것에 대하여는, 「Direct3D 디바이스」, 「라이팅과 머트리얼」, 및 「뷰포트와 클리핑」을 참조할것.
Direct3DEnumDevices 클래스
Direct3DEnumDevices 클래스는, 시스템의 렌더링 디바이스를 열거하는 오브젝트를 정의한다. Direct3DEnumDevices 클래스의 오브젝트를 생성 하려면 ,Direct3D7.GetDevicesEnum 메소드를 호출한다.
Direct3DEnumPixelFormats 클래스
Direct3DEnumPixelFormats 클래스는, 지정 디바이스용으로 시스템으로 지원 되고 있는 픽셀 포맷을 열거하는 오브젝트를 정의한다. Direct3DEnumPixelFormats 클래스의 오브젝트를 생성 하려면 ,Direct3D7.GetEnumZBufferFormats 또는 Direct3DDevice7.GetTextureFormatsEnum 메소드를 호출한다.
Direct3DVertexBuffer7 클래스
Direct3DVertexBuffer7 클래스는, 버텍스의 메모리 버퍼로서 기능하는 오브젝트를 정의한다. 메모리 버퍼내의 버텍스는,Direct3DDevice7 클래스의 버텍스 버퍼 렌더링 메소드를 사용해 렌더링 할 수 있다. Direct3D7.CreateVertexBuffer 메소드를 호출해 버텍스 버퍼를 생성 한다.

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


직접 모드 COM 인터페이스

[Visual Basic]

주 : 여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에서는, COM 인터페이스는 공개되지 않는다.

[C++]

Direct3D 직접 모드 API 는, 주로 다음의 COM 인터페이스로 구성된다.

IDirect3D7 | 루트 인터페이스. 다른 인터페이스의 취득에 사용한다.
IDirect3DDevice7 | DrawPrimitive 베이스의 프로그래밍용 3D 디바이스.
IDirect3DVertexBuffer7 | 버텍스 버퍼를 처리하는 인터페이스.

DirectX 의 구버젼과의 하위 호환성을 유지하기 (위해)때문에, DirectX 7.0 에서는, 종래의 인터페이스의 버젼을 모두 지원 하고 있다. 다만, 새로운 오브젝트는 최신의 인터페이스만 지원 한다. 상세한 것에 대하여는, 「Direct3D 인터페이스」 및 「디바이스 인터페이스」를 참조할것.


Direct3D 직접 모드의 요점

Direct3D 직접 모드는, 오브젝트를 생성해, 데이터를 묻어, 각 오브젝트를 연결하는 비교적 소수의 API 요소로부터 구성되어 있다. API 는 COM 에 근거하고 있다. 직접 모드 API 는, Direct3D 드라이버의 상부에 있는 매우 얇은 계층이다.

이 섹션에서는, Direct3D 직접 모드의 컴퍼넌트의 기술적인 내용에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • DirectX 7.0 에서의 직접 모드의 변경점
  • Direct3D 와 DirectDraw
  • Direct3D 디바이스
  • 지오메트리 파이프라인
  • 라이팅과 머트리얼
  • 버텍스 포맷
  • 텍스쳐
  • 깊이 버퍼
  • 스텐실 버퍼
  • 버텍스 버퍼
  • 공통의 테크놀러지와 특수 효과
  • GUID
  • 퍼포먼스의 최적화
  • 트러블 슈팅


DirectX 7.0 에서의 직접 모드의 변경점

[Visual Basic]
Visual Basic 어플리케이션의 지원
DirectX 7.0 의 그 외의 컴퍼넌트와 같이, Direct3D 직접 모드에서는 현재, Visual Basic 어플리케이션에 서비스를 제공한다. 이 서비스의 제공은, Visual Basic 어플리케이션으로부터 DirectX 런타임에 데이터를 배치하는 클래스 세트에 의해 실현되고 있다. 또, 이 SDK 의 문서로부터는, Visual Basic 개발자도 대상이 되고 있다.
[C++]

DirectX 7.0 에서는, 구릴리스의 DirectX 의 오브젝트와 인터페이스를 공개 및 지원 하는 것으로써, 후방 호환성을 유지하고 있다. 다만,IDirect3D7 및 IDirect3DDevice7 의 2 개의 주요한 Direct3D 인터페이스가 DirectX 7.0 의 원가요소로서 추가되고 있다. 이러한 인터페이스는, 구릴리스의 오브젝트와는 다른 새로운 오브젝트에의 인터페이스이다. 구버젼의 DirectX 의 오브젝트와 비교했을 경우, 이러한 새로운 오브젝트에는 몇개의 신기능이 있어, 퍼포먼스 향상을 실현해, 간단하게 확장할 수가 있다.

하드웨어 가속화에 의한 트랜스 폼 & 라이팅
현재 Direct3D 에서는, 3D 가속기를 이용해 하드웨어에서의 트랜스 폼 & 라이팅 처리를 고속화하고 있다. 대응 하드웨어가 사용 가능한 경우,IDirect3D7::EnumDevices 메소드에 의해, 대응하는 D3DDEVICEDESC7 구조체의 dwDevCaps 멤버에 D3DDEVCAPS_HWTRANSFORMANDLIGHT 능력 플래그를 설정한다. 상세한 것에 대하여는, 「TnLHAL 디바이스」를 참조할것.
큐브 환경 맵에 의한 환경 맵핑
현재 Direct3D 및 DirectDraw 에서는, 환경 맵핑으로 사용하는 특수한 텍스쳐 맵을 지원 하고 있어, 이것을 큐브 환경 맵이라고 부른다. 큐브 환경 맵을 실행 하면나무는, 장면의 오브젝트에 적용하는 화면을 포함한 6 면텍스쳐를 사용한다. 큐브 환경 맵에 의해, 어플리케이션에서는 리얼한 환경 맵핑을 간단하게 실행할 수 있어 동적인 환경 맵핑도 가능하다.
API 의 변경점
Direct3D for DirectX 7.0 에서는, 라이팅, 머트리얼, 및 뷰포트의 파라미터를 디바이스 인터페이스로 이동한다. 따라서, 이러한 파라미터를 처리하는 개별의 오브젝트는 필요없고, 그 인터페이스도 필요없다. 이러한 파라미터를 처리하기 위해서, 몇개의 메소드가 IDirect3DDevice7 인터페이스에 추가되고 있다.

현재, 버텍스 버퍼는 보폭 버텍스로써 사용할 수 있다. 이것은,IDirect3DVertexBuffer7::ProcessVerticesStrided 메소드를 새로운 IDirect3DVertexBuffer7 인터페이스에 추가하는 것으로 실현되고 있다.

지오메트리 블렌딩
Direct3D 지오메트리 파이프라인을 사용하는 어플리케이션에서는, 새롭게 지원 되는 지오메트리 블렌딩을 이용할 수 있다. 지오메트리 블렌딩은, 특히 캐릭터 등 장면내의 각각의 오브젝트를 리얼하게 표현하는 "스키닝" 이펙트를 베푼다. 상세한 것에 대하여는, 「지오메트리 블렌딩」을 참조할것.
디바이스 스테이트 블록
IDirect3DDevice7 인터페이스를 대상으로 하는 어플리케이션에서는, 프로그램 가능한 스테이트 변경 세트를 이용할 수 있어 이것을 스테이트 블록이라고 부른다. 스테이트 블록에 의해, Direct3D 어플리케이션에서는 디바이스의 스테이트 변경을 공통의 순서로, 고유의 식별자, 즉 블록 핸들을 가지는 원가요소에 기록할 수 있다. 어플리케이션에서는, 블록 핸들을 사용해, 이전에 기록된 스테이트 블록을 1 회의 메소드 호출로 실행할 수 있다. 스테이트 블록에 의해, 호출을 최소한으로 억제해 디바이스 스테이트를 변경할 수 있는 것 외에도, 디바이스에서는 실행을 최적화하기 위해서 스테이트 변경의 프리컴파일이 끝난 세트를 캐쉬해 둘 수가 있다. 이것에 의해 보통은 퍼포먼스가 향상한다. 상세한 것에 대하여는, 「스테이트 블록」을 참조할것.
텍스쳐 관리의 향상
Direct3D 텍스쳐 매니저가, 어플리케이션측에서 관리하의 텍스쳐에 우선 순위를 붙일 수가 있도록(듯이) 확장되고 있다. Direct3D 에서는, 텍스쳐의 우선 순위에 따라, 메모리 로 유지하는 텍스쳐나, 메모리로부터 삭제하는 텍스쳐를 결정한다.
Visual Basic 어플리케이션의 지원
DirectX 7.0 의 그 외의 컴퍼넌트와 같이, Direct3D 직접 모드에서는 현재, Visual Basic 어플리케이션에 서비스를 제공한다. 이 서비스의 제공은, Visual Basic 어플리케이션으로부터 DirectX 런타임에 데이터를 배치하는 클래스 세트에 의해 실현되고 있다. 또, 이 SDK 의 문서로부터는, Visual Basic 개발자도 대상이 되고 있다.
확장 소프트웨어 에뮬레이션
Direct3D 는, CPU 로 지원 되는 특수한 명령을 사용할 수 있도록(듯이) 최적화되고 있다. 지원 되는 명령 세트에는, 몇개의 AMD 프로세서의 AMD 3D-Now! 명령 세트나, 많은 Itel 프로세서로 지원 되는 MMX 명령 세트등이 있다. 이러한 명령 세트가 사용 가능한 경우, Direct3D 에서는 3D-Now! 명령 세트를 이용해 트랜스 폼 & 라이팅 처리를 고속화해, MMX 명령 세트 이용해 라스터화를 고속화한다. Direct3D 의 트랜스 폼 & 라이팅 파이프라인을 사용하는 어플리케이션에서는, 이 기능에 의해 자동적으로 고속 처리가 실현된다.

Direct3D 오브젝트의 새로운 세트에의 이행에서는 다소의 희생이 생긴다. Direct3D 오브젝트는, 지원 하는 인터페이스의 이름에는 관계없이, 구릴리스로 대응하는 오브젝트와는 달라서 , 같은 인터페이스를 지원 하고 있지 않다. IUnknown::QueryInterface 를 사용해도, 새로운 인터페이스를 지원 하는 오브젝트로부터는 종래의 인터페이스를 취득할 수 없다. 또, 종래의 오브젝트로부터 새로운 인터페이스를 문의하는 일도 할 수 없다. 이러한 처리의 실행은 실패해, E_NOINTERFACE 가 돌려주어진다.

렌더링에 실행 버퍼를 사용하는 기존의 어플리케이션에서는, 그 실행 버퍼 아키텍쳐를 파기하지 않는 한, 새로운 오브젝트를 사용할 수 없다. 실행 버퍼 아키텍쳐를 파기하지 않는 것이면, 종래의 오브젝트 (계속 지원 될 예정)를 사용해야 한다. 실제, 실행 버퍼의 렌더링은 일반적으로 하행 깨지지 않게 되어 있다. 이것으로부터, 실행 버퍼의 사용에 대해서는, 이 문서에서는 설명하지 않는다.


Direct3D 와 DirectDraw

이 섹션에서는, Direct3D 와 DirectDraw 의 밀접한 관계에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • DirectDraw 오브젝트와 Direct3D
  • Direct3D 인터페이스
  • Direct3D 에의 액세스
  • Direct3D 의 종속 오브젝트의 생성
  • DirectDraw 협조 레벨과 FPU 정밀도


DirectDraw 오브젝트와 Direct3D

Direct3D 는, COM 오브젝트와 인터페이스에 의해 이행 된다. C++ 로 기술된 어플리케이션으로부터는 이러한 인터페이스와 오브젝트에 직접 액세스 할 수 있지만, Visual Basic 어플리케이션의 경우는, Visual Basic 어플리케이션으로부터 DirectX 런타임에 데이터를 배치하는, DirectX for Visual Basic 클래스로서 나타나는 코드 계층과의 상호 처리를 실시한다. 여기에서는, C++ 에 고유의 정보로서 DirectDraw 와 Direct3D 간의 중요한 관계에 대해 설명한다. 게다가 그 후로, DirectX for Visual Basic 에서 공개되는 클래스간의 같은 관계에 대해 자세하게 설명한다.

[C++]

Direct3D 인터페이스는, 실제로는 DirectDraw 오브젝트에의 인터페이스이다. DirectDraw 에서는, DirectDraw 와 Direct3D 의 양쪽 모두의 스테이트를 캡슐화하는 단일의 통일 오브젝트를 사용할 수 있다. DirectDraw 오브젝트는, 어플리케이션으로 최초로 생성 되어 마지막에 릴리즈 되는 오브젝트이다. DirectDraw 오브젝트는 디스플레이 디바이스를 나타내, 디스플레이 디바이스는 Direct3D 의 가장 중요한 기능의 대부분을 이행 하고 있는 것으로부터, Direct3D 의 기능은 DirectDraw 에 짜넣어지고 있다.

주 : DirectX 7.0 에서는, Direct3D 에 액세스 하는 DirectDraw 오브젝트를 2 개의 방법으로 생성 할 수 있다. 1 개(살)은 새로운 DirectDrawCreateEx 함수를 사용하는 방법으로, 이제(벌써) 1 개(살)은 구릴리스의 DirectX 의 DirectDrawCreate 함수를 사용하는 방법이다. DirectDrawCreateEx 함수는, DirectX 7.0 의 Direct3D 인터페이스의 최신 세트를 공개할 수 있는 DirectDraw 오브젝트를 생성 한다. 한편,DirectDrawCreate 함수도 DirectDraw 오브젝트를 생성 하지만, 이 오브젝트는 DirectX 7.0 의 기능을 지원 하는 Direct3D 인터페이스를 생성할 수 없다. 이 문서에서는, 모든 어플리케이션으로 DirectDrawCreateEx 함수를 사용해 DirectDraw 오브젝트가 생성 되는 것을 전제로 한다. 상세한 것에 대하여는, 「Direct3D 인터페이스」 및 「디바이스 인터페이스」를 참조할것.

즉, Direct3D 드라이버의 스테이트의 수명은 DirectDraw 오브젝트의 수명과 같다. Direct3D 인터페이스를 릴리즈 해도, Direct3D 드라이버의 스테이트는 파괴되지 않는다. 이 스테이트가 파괴되는 것은, DirectDraw 참조의 경우에서도 Direct3D 참조의 경우에서도, DirectDraw 오브젝트에의 참조가 모두 릴리즈 될 때이다. 따라서, DirectDraw 드라이버 인터페이스에의 참조를 보관 유지하고 있는 동안에 Direct3D 인터페이스를 일단 릴리즈 해도, 그 후로 다시 Direct3D 인터페이스를 문의하면(자), Direct3D 의 스테이트가 보관 유지되고 있다.

DirectDrawCreateEx 함수로 생성 한 DirectDraw 오브젝트에는, 단일의 Direct3D 인터페이스 IDirect3D7 가 포함된다 (종래의 DirectDrawCreate 함수로 생성 한 DirectDraw 오브젝트의 경우는, 종래의 인터페이스 IDirect3D,IDirect3D2, 및 IDirect3D3 가 지원 된다. 이러한 인터페이스는 현재는 사용되어 있지 않지만, 후방 호환성을 위해서(때문에) 제공된다). 새로운 어플리케이션에서는,IDirect3D7 인터페이스를 사용해 다른 Direct3D 오브젝트를 생성 할 필요가 있다. 상세한 것에 대하여는, 「Direct3D 인터페이스」를 참조할것.

[Visual Basic]

DirectDraw 와 Direct3D 는, 실제의 곳, 기본적으로는 같은 루트 오브젝트이며, 같은 코드를 다수 공유하는 것에도 불구하고, DirectX for Visual Basic 에서는 이러한 오브젝트의 사용 방법으로 응해, 기능적으로 다른 클래스로서 공개된다. DirectX for Visual Basic 에서는, 어플리케이션으로 오브젝트를 생성 하면나무의 기본으로 되는 DirectDraw7 및 Direct3D7 클래스를 사용한다. (이 주제의 C++ 의 부분에서 설명한 것처럼) DirectDraw 와 Direct3D 의 기본이 되는 관계는, Visual Basic 의 내부로부터에서도 분명하다. 글로벌 DirectX7 클래스에는,DirectDraw7 오브젝트를 생성 하는 메소드가 포함되어 있지만, Direct3D 용의 같은 메소드는 포함되지 않았다. 그 대신해,DirectDraw7 클래스는 Direct3D7 클래스를 취득하는 메소드를 정의해, 이 메소드는 DirectDraw7.GetDirect3D 로 불린다. 이것들 2 개의 클래스는, 실제로는 DirectX 내의 같은 오브젝트를 참조하기 위해(때문에)이다.

GetDirect3D 메소드는 새로운 오브젝트를 생성 하지 않는다. 그 대신해, Direct3D 관련 기능을 공개하는 새로운 클래스를 생성 한다. 이 때 공개되는 것은, 이 클래스를 생성 한 DirectDraw 오브젝트에 의해 제공되는 Direct3D 관련 기능이다.

DirectDraw7 클래스에는 디스플레이 디바이스용의 2D 기능이 있어,Direct3D7 클래스에는 디바이스용의 3D 기능이 있다. DirectDraw7 클래스를 사용해, Direct3D 클래스에서 렌더링 타겟, 깊이 버퍼, 및 텍스쳐에 사용하는 표면을 생성 한다. 그 후, Direct3D 클래스를 사용해, 버텍스 버퍼, 열거 클래스 등 Direct3D 오브젝트로 필요한 종속 오브젝트를 생성 한다.


Direct3D 인터페이스

[Visual Basic]

주 : 여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에서는, 어플리케이션에의 COM 인터페이스는 직접은 공개되지 않는다.

[C++]

Direct3D 오브젝트의 기능을 이용하려면 , 인터페이스 IDirect3D,IDirect3D2,IDirect3D3, 및 IDirect3D7 를 사용한다. 이 섹션에서는, DirectX 7.0 으로 도입된 IDirect3D7 인터페이스로부터 순서에 IDirect3D 인터페이스까지, 이것들 3 개의 인터페이스의 개요에 대해 설명한다.

IDirect3D7 인터페이스
IDirect3D7 인터페이스는, 이름으로부터는 종래의 것과 같은 인상을 받지만, 실제로는 완전히 새로운 Direct3D 오브젝트에의 인터페이스를 나타낸다. 이 오브젝트는 DrawPrimitive 아키텍쳐를 지원 및 확장하지만, 이 주제로 이미 설명한 종래의 인터페이스는 지원 하지 않는다. 어플리케이션은,DirectDrawCreateEx 함수를 호출해 생성 된 DirectDraw 오브젝트의 QueryInterface 메소드를 호출하는 것에 의해,IDirect3D7 인터페이스에의 포인터를 취득한다.

IDirect3D7 인터페이스는, 어플리케이션에서의 렌더링 디바이스 및 버텍스 버퍼의 생성, 픽셀 포맷의 열거 등,IDirect3D3 인터페이스와 같은 기능을 다수 지원 하고 있다. 이 인터페이스는, 텍스쳐 생성 기능을 추가하기 위해(때문에), 텍스쳐 인터페이스에 대해 DirectDraw 표면을 문의할 필요는 없어진다.

IDirect3D7 와 그 외의 인터페이스와의 큰 차이는, 라이팅, 머트리얼, 또는 뷰포트 오브젝트를 생성 하는 메소드가 없는 것이다. 이것은,IDirect3DDevice7 인터페이스에서의 처리에 반영되고 있어 라이팅, 머트리얼, 및 뷰포트 파라미터를 개별의 오브젝트로서가 아니고, 디바이스의 내부 데이터 구조의 일부로서 짜넣는다.

IDirect3D7 오브젝트는, 「DirectX 7.0 에서의 직접 모드의 변경점」으로써 설명하는 기능을 지원 한다.

어플리케이션은, 새로운 IDirectDraw7 인터페이스의 QueryInterface 메소드를 사용해 IDirect3D7 인터페이스에의 포인터를 취득한다. 상세한 것에 대하여는, 「Direct3D 에의 액세스」를 참조할것.

IDirect3D2 및 IDirect3D3 인터페이스
어플리케이션은, (새로운 DirectDrawCreateEx 함수와는 대조적으로) DirectDrawCreate 함수로 생성 된 DirectDraw 오브젝트로부터 종래의 IDirect3D2 및 IDirect3D3 인터페이스에의 포인터를 취득한다. 이러한 인터페이스는, DirectDraw 오브젝트의 QueryInterface 메소드를 호출해 취득한다. 이러한 인터페이스를 사용하는 것으로써, 어플리케이션은, 특정의 DirectDraw 오브젝트가 지원 하는 Direct3D 디바이스의 타입을 검출해 열거할 수 있다. 또, 이러한 인터페이스는, 뷰포트, 머트리얼, 라이팅 등 그 외의 Direct3D 직접 모드 오브젝트의 생성에 필요한 메소드도 공개한다 (라이팅, 머트리얼, 및 뷰포트를 개별의 오브젝트로서 취급한다고 하는 개념은,IDirect3D7 인터페이스에서는 폐지되고 있다).

IDirect3D2 와 IDirect3D 와의 가장 중요한 차이는,IDirect3D2 가 IDirect3D2::CreateDevice 메소드를 이행 하고 있다고 하는 점이다. 이 메소드는, DrawPrimitive 를 지원 하는 Direct3D 디바이스를 생성 한다. IDirect3D2::CreateDevice 메소드로 생성 되는 디바이스의 상세한 것에 대하여는, 「Direct3D 디바이스」를 참조할것.

IDirect3D2 인터페이스와 같이,IDirect3D3 인터페이스는 Direct3D 프로그래밍의 DrawPrimitive 스타일을 지원 하고 있다. 게다가IDirect3D3 인터페이스는,IDirect3DDevice3 인터페이스를 도입하는 것으로 DrawPrimitive 스타일의 기능을 확장한다. 이 인터페이스에 의해, 유연한 버텍스 포맷, 버텍스 버퍼, 및 새로운 텍스쳐 기능의 개념이 도입되고 있다. 상세한 것에 대하여는, 「버텍스 포맷」, 「텍스쳐」, 「버텍스 버퍼」, 및 「렌더링」을 참조할것.

어플리케이션은,QueryInterface 메소드를 사용해 DirectDraw 오브젝트로부터 IDirect3D3 인터페이스에의 포인터를 취득한다.

IDirect3D 인터페이스
IDirect3D 인터페이스는, 실행 버퍼의 사용을 지원 한다. 이 인터페이스는, 기존의 코드와의 호환성을 위해서(때문에) 준비되어 있다. 새로운 어플리케이션에서는 IDirect3D7 인터페이스를 사용한다. 어플리케이션으로 실행 버퍼를 사용하고 있는 경우는, DirectX 7.0 이 제공하는 기능에는 이행 할 수 없다. 상세한 것에 대하여는, 「DirectX 7.0 에서의 직접 모드의 변경점」을 참조할것.


Direct3D 에의 액세스

[C++]

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

IDirect3D7 인터페이스에의 포인터를 취득하려면

  1. DirectDrawCreateEx 를 호출해 DirectDraw 디바이스를 생성 한다. 어플리케이션에서는,DirectDrawCreateEx 함수를 사용해,IDirect3D7 를 지원 하는 DirectDraw 오브젝트를 생성 해야 한다. DirectDrawCreate 함수로 생성 한 DirectDraw 오브젝트는,IDirect3D7 인터페이스를 지원 하지 않는다.
  2. IUnknown::QueryInterface 메소드를 호출해 IDirect3D7 인터페이스에의 포인터를 취득한다.

다음의 그림은, 이러한 순서를 나타내, 그 과정을 종래의 어플리케이션으로 필요한 것에 관련시키고 있다.

주 : 이 그림에 나타내도록(듯이), DirectDraw 컴퍼넌트는 2 개의 COM 오브젝트로부터 구성되어 있다. DirectDrawCreateEx 함수를 호출해 생성 되는, DirectDraw7 로 불리는 최신의 오브젝트만,IDirect3D7 인터페이스를 공개한다. DirectDraw7 오브젝트는, 종래의 Direct3D 인터페이스는 공개하지 않는다. 종래의 Direct3D 가 필요한 어플리케이션에서는,DirectDrawCreate 메소드를 사용해 DirectDraw 오브젝트를 생성 해, 그 후로 그 인터페이스를 문의하지 않으면 안 된다.

다음의 코드는, DirectDraw7 오브젝트의 생성 방법과IDirect3D7 인터페이스의 문의 방법을 나타낸다.

LPDIRECTDRAW7   lpDD;               // IDirectDraw7 인터페이스.
LPDIRECT3D7     lpD3D;              // IDirect3D7 인터페이스.
HRESULT hr;

// IDirect3D7 인터페이스를 취득한다.
// 현재의 디스플레이 드라이버를 사용한다.
hr = DirectDrawCreateEx (NULL, (void **) &lpDD, IID_IDirectDraw7, NULL);
if (FAILED (hr))
{
    // 에러 처리 코드.
}

// D3D 인터페이스를 취득한다.
hr = lpDD->QueryInterface (IID_IDirect3D7, (void **) &lpD3D);
if (FAILED (hr))
{
    // 에러 처리 코드
}
[Visual Basic]

Visual Basic 로 기술된 Direct3D 어플리케이션에서는, 기동시에, Direct3D 기능을 이용하기 위해서 Direct3D7 클래스에의 참조를 취득해야 한다. 이하의 순서에 따라 참조를 취득한다.

Direct3D7 클래스에의 참조를 취득하려면

  1. DirectX7.DirectDrawCreate 를 호출해 DirectDraw7 클래스 오브젝트를 생성 한다.
  2. DirectDraw7.GetDirect3D 메소드를 호출해,Direct3D7 클래스에의 DirectDraw 오브젝트의 참조를 취득한다.

다음의 그림은, 이러한 순서를 나타낸다.

다음의 코드는,DirectDraw7 클래스 오브젝트로부터 Direct3D7 클래스를 취득하는 방법을 나타낸다.

' Direct3D7 클래스에의 참조를 취득한다.
'
'이 예에서는, dx 는 DirectX7 클래스에의 유효한 참조이다.
On Local Error Resume Next
Dim ddraw As DirectDraw7
Dim d3d As Direct3D7

'디폴트의 DirectDraw7 오브젝트를 생성 한다.
Set ddraw = dx.DirectDrawCreate("")
If (Err.Number <> DD_OK) Then
'에러 처리
End If

' DirectDraw7 오브젝트로부터 Direct3D7 참조를 취득한다.
Set d3d = ddraw.GetDirect3D
If (Err.Number <> DD_OK) Then
'에러 처리
End If


Direct3D 의 종속 오브젝트의 생성

[C++]

C++ 로 기술된 어플리케이션에서는,IDirect3D7 인터페이스를 사용해, Direct3D 렌더링 디바이스와 버텍스 버퍼를 생성 한다. Direct3D 어플리케이션에서는,IDirect3D7::CreateDevice 메소드를 호출해 렌더링 디바이스를 생성 한다. 상세한 것에 대하여는, 「Direct3D 디바이스」를 참조할것. 렌더링 디바이스에는, 렌더링, 라이팅, 머트리얼, 및 뷰포트 스테이트가 포함된다.

IDirect3D7::CreateVertexBuffer 메소드를 호출해 뷰포트 오브젝트를 생성 한다. 버텍스 버퍼에는, 버텍스 데이터의 단순한 배열보다 재빠르게 렌더링을 실시하기 위해서(때문에) 특별히 준비된 버텍스 데이터가 포함된다. 상세한 것에 대하여는, 「버텍스 버퍼」를 참조할것.

[Visual Basic]

Visual Basic 로 기술된 어플리케이션에서는,Direct3D7 클래스의 메소드를 사용해, Direct3D 렌더링 디바이스와 버텍스 버퍼를 생성 한다. Direct3D 어플리케이션에서는,Direct3D7.CreateDevice 메소드를 호출해 렌더링 디바이스를 생성 한다. 상세한 것에 대하여는, 「Direct3D 디바이스」를 참조할것. 렌더링 디바이스에는, 렌더링, 라이팅, 머트리얼, 및 뷰포트 스테이트가 포함된다.

Direct3D7.CreateVertexBuffer 메소드를 호출해 버텍스 버퍼를 생성 한다. 버텍스 버퍼에는, 버텍스 데이터의 단순한 배열보다 재빠르게 렌더링을 실시하기 위해서(때문에) 특별히 준비된 버텍스 데이터가 포함된다. 상세한 것에 대하여는, 「버텍스 버퍼」를 참조할것.


DirectDraw 협조 레벨과 FPU 정밀도

[Visual Basic]

주 : 여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에서는, 부동 소수점 단위 (FPU: floating-point unit) 정밀도의 변경을 지원 하고 있지 않다.

[C++]

Direct3D 에서는, 항상 단정밀도 부동 소수점 계산을 사용해, 3D 신의 렌더링의 퍼포먼스를 향상시킨다. 디폴트에서는,IDirect3DDevice7 인터페이스를 지원 하는 렌더링 디바이스를 생성 하면 와, Direct3D 는 FPU 를 단정밀도, 바로 옆값 둥근 모드로 예외 무효로 설정한다. 이 시점으로부터, 그 디바이스가 릴리즈 될 때까지는 FPU 의 스테이트는 변경되지 않는 것이 전제가 되어, 디바이스가 릴리즈 되면(자) FPU 는 배정밀도 모드에 리셋 된다.

주 : 이러한 시스템 동작은, 종래의 IDirect3DDevice3 인터페이스의 것과는 다르다. IDirect3DDevice3 를 공개하는 디바이스는, 전의 IDirectDraw4::SetCooperative 메소드의 호출로 DirectDraw 협조 레벨을 설정했을 때에 DDSCL_FPUSETUP 플래그가 사용되어 있지 않은 경우에 한정해, 각 렌더링 패스의 FPU 모드를 체크한다.

배정밀도의 정밀도가 필요한 어플리케이션에서는,IDirectDraw7::SetCooperativeLevel 메소드를 호출해 DirectDraw 협조 레벨을 설정할 경우에 DDSCL_FPUPRESERVE 플래그를 포함할 수가 있다. DDSCL_FPUPRESERVE 플래그를 사용 하면, 단정밀도 모드가 사용되지만, 정밀도 모드를 변경하기 전에 FPU 의 스테이트가 보존되어 제어를 어플리케이션에 돌려줄 때 원의 모드가 복원된다 (DDSCL_FPUSETUP 플래그를 사용해 재차 메소드를 호출하면, Direct3D 는 디폴트의 동작하러 돌아온다). 이 체크, 보존, 및 복원 처리에는 분명하게 시간이 걸려, 퍼포먼스에 크게 영향을 주는 일도 있다. 이 플래그는, 어플리케이션으로 배정밀도를 사용할 필요가 있어, 어플리케이션에서의 필요에 따라서 FPU 모드를 수동으로 설정 및 복원하는 코드를 포함하지 않는 경우에게만 사용하도록(듯이) 한다.

부동 소수점 정밀도는 thread 고유하기 때문에, multi-thread 어플리케이션을 개발 하면나무는, FPU 의 정밀도 스테이트를 체크해, thread 마다 설정과 리셋이 적절히 행해지고 있는지 어떤지를 확인할 필요가 있다.

중요 일부의 동적 링크 라이브러리 (DLL)를 실행시에 로드하면(자), FPU 가 배정밀도 모드에 리셋 되는 일이 있다. Visual C++ 등의 컴파일러는, C/C++ 런타임 컴퍼넌트를 초기화하는 _DllMainCrtStartup 에 디폴트의 DLL 엔트리 포인트를 설정한다. 이 함수도, FPU 정밀도 모드를 배정밀도로 설정한다. 어플리케이션이 DDSCL_FPUSETUP 협조 레벨을 설정한 후라고 DLL 를 로드하면(자), Direct3D 는 FPU 가 리셋 된 것을 검출할 수 없기 때문에, 퍼포먼스에 영향을 준다.

실행시에 DLL 를 로드하는 경우는,LoadLibrary Win32 함수가 돌아온 직후와 Direct3D 함수를 호출하기 전에, FPU 정밀도를 체크해 리셋 할 필요가 있다. 정밀도 모드를 리셋 하려면 , 명시적으로 리셋 하는지, DDSCL_FPUSETUP 플래그를 설정해 IDirectDraw7::SetCooperativeLevel 메소드를 재차 호출한다. SetCooperativeLevel 를 사용해 FPU 정밀도 모드를 설정 하면, DirectDraw 서페이스가 없어진다.

/ENTRY: 링커 스윗치를 사용하면, 컴파일 하는 DLL 의 엔트리 포인트를 명시적으로 설정할 수 있다. 다만, 이 경우, C/C++ 런타임은 자동적으로는 초기화되지 않는다.

다음에 나타내는 것은, 인 라인 어셈블리 언어를 사용해, FPU 정밀도의 설정을 체크 및 설정하는 콘솔 프로그램용의 샘플 소스 파일이다.

#include <windows.h>
#include <math.h>

// 이 함수는,
// 부동 소수점 제어어가, 단정밀도/바로 옆값 둥근/예외 무효로 설정되어 있는지 어떤지를
// 평가한다. 설정되어 있지 않은 경우,
// 함수는 제어어를 변경해 조건을 설정해, TRUE 를 돌려준다.
// 낡은 제어어값은, pwOldCW 가
// 포인트 하는 패스 백 위치 좌표에 배치한다.
BOOL MungeFPCW( WORD *pwOldCW )
{
    BOOL ret = FALSE;
    WORD wTemp, wSave;

    __asm fstcw wSave
    if (wSave & 0x300 ||            // 단정밀도 모드는 아니다.
        0x3f ! = (wSave & 0x3f) ||   // 예외 유효.
        wSave & 0xC00)              // 바로 옆값 둥근 모드는 아니다.
    {
        __asm
        {
            mov ax, wSave
            and ax, not 300h    ;; 단정밀도 모드.
            or  ax, 3fh         ;; 모든 예외 무효.
            and ax, not 0xC00   ;; 바로 옆값 둥근 모드
            mov wTemp, ax
            fldcw   wTemp
        }
        ret = TRUE;
    }
    *pwOldCW = wSave;
    return ret;
}

void RestoreFPCW(WORD wSave)
{
    __asm fldcw wSave
}

void __cdecl main()
{
    WORD wOldCW;
    BOOL bChangedFPCW = MungeFPCW( &wOldCW );
    // MungeFPCW 의 설정에 따라 제어어를 처리한다.
    if ( bChangedFPCW )
        RestoreFPCW( wOldCW );
}


Direct3D 디바이스

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

  • Direct3D 디바이스란
  • Direct3D 디바이스의 종류
  • 디바이스 인터페이스
  • 디바이스 스테이트
  • 디바이스의 사용
  • AGP 표면과 Direct3D 디바이스


Direct3D 디바이스란

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

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

[C++]

C++ 에는, 렌더링에 사용할 수 있는 IDirect3DDevice,IDirect3DDevice2,IDirect3DDevice3, 및 IDirect3DDevice7 의 4 개의 COM 인터페이스가 있다. 이 문서에서는, 어플리케이션으로 최신 버젼의 인터페이스를 사용하는 것을 전제로 하고 있다. 상세한 것에 대하여는, 「디바이스 인터페이스」를 참조할것.

[Visual Basic]

DirectX for Visual Basic 에서는,Direct3DDevice7 클래스를 개입시켜 Direct3D 직접 모드의 디바이스에 액세스 한다. Direct3DDevice7 클래스는, 장면 렌더링 메소드의 DrawPrimitive 패밀리를 지원 한다. Direct3DDevice7 오브젝트는, 어플리케이션으로 필요한 경우, 다양한 DirectDraw 표면을 렌더링 타겟으로서 사용할 수 있다. 상세한 것에 대하여는, 「Direct3DDevice7.SetRenderTarget 」를 참조할것.


Direct3D 디바이스의 종류

이 섹션에서는, Direct3D 디바이스에 대해, 및 디바이스의 각종류에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • 디바이스의 종류에 대해
  • HAL 디바이스
  • TnLHAL 디바이스
  • RGB 디바이스
  • 레퍼런스 래스터라이저
  • 종래의 디바이스의 종류


디바이스의 종류에 대해

Direct3D 가 현재 지원 하고 있는 Direct3D 디바이스에는, HAL 디바이스, 트랜스 폼 & 라이팅의 가속화를 지원 한 TnLHAL 디바이스, 소프트웨어 에뮬레이션 RGB 디바이스, 및 레퍼런스 래스터라이저의 4 종류가 있다. 최초의 2 종류의 디바이스는 어플리케이션을 출하하기 위해서 사용할 수 있어 레퍼런스 래스터라이저는 기능 테스트용으로 지원 되고 있다.

[C++]

주 : 구릴리스의 DirectX 에서 공개되고 있던 추가 디바이스의 MMX 및 램프 디바이스는 현재 사용되어 있지 않다. 이러한 디바이스는, 구버젼의 Direct3D 를 대상으로 하는 C++ 어플리케이션에서는 현재도 사용할 수 있지만, 최신의 인터페이스에서는 지원되어 있지 않다. 상세한 것에 대하여는, 「종래의 디바이스의 종류」를 참조할것.

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

하드웨어 가속화 디바이스는, 소프트웨어 에뮬레이션 디바이스보다 높은 퍼포먼스를 실현한다. 대부분의 경우, 어플리케이션이 대상으로 하는 것은, 어떠한 하드웨어 가속화를 갖춘 컴퓨터이며, 로앤드 컴퓨터에 대해서는 소프트웨어 에뮬레이션 기능을 사용한다.

레퍼런스 래스터라이저를 제외해, 소프트웨어 디바이스는, 항상 하드웨어 디바이스와 같은 기능을 지원 하고 있는 것은 아니다. 예를 들어, 소프트웨어 디바이스는, 텍스쳐를 한 번에 복수의 텍스쳐 스테이지에 할당하는 기능을 지원 하고 있지 않다. 어플리케이션은, 디바이스 기능을 조사해, 지원 되고 있는 기능을 확인할 필요가 있다.

[C++, Visual Basic]


HAL 디바이스

어플리케이션이 동작하는 컴퓨터에, Direct3D 를 지원 하는 디스플레이 어댑터가 장착되고 있는 경우, 어플리케이션에서는 그 어댑터를 3D 처리에 사용할 필요가 있다. Direct3D 의 HAL 디바이스는, 하드웨어의 트랜스 폼, 라이팅, 및 라스터화 모듈을 모두 또는 그 일부를 이행 한다.

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

[C++]

C++ 로 HAL 디바이스를 생성 하려면 ,IDirect3D7::CreateDevice 를 호출해, 제 1 파라미터로서 IID_IDirect3DHALDevice 값을 건네준다. 상세한 것에 대하여는, 「Direct3D 디바이스의 생성」을 참조할것.

[Visual Basic]

Visual Basic 로 HAL 디바이스를 생성 하려면 ,Direct3D7.CreateDevice 메소드를 호출해, 제 1 파라미터로서 "IID_IDirect3DHALDevice" 캐릭터 라인 정수를 건네준다. 상세한 것에 대하여는, 「Direct3D 디바이스의 생성」을 참조할것.

주 : 소프트웨어 에뮬레이션 RGB 디바이스와는 달라, 하드웨어 디바이스는 8 비트 렌더링 타겟 표면에 렌더링 할 수 없다.


TnLHAL 디바이스

일부의 새로운 3D 하드웨어에는, 트랜스 폼 & 라이팅 처리에 하드웨어 가속화를 실행해, CPU 의 작업 부하를 릴리즈 하는 것이 있다. 이것이 가능한 경우, 어플리케이션에서는, 이러한 디바이스를 사용해 퍼포먼스를 최적화할 수 있다. Direct3D 의 TnLHAL 디바이스는, 하드웨어의 트랜스 폼, 라이팅, 및 라스터화 모듈을 모두 이행 한다.

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

[C++]

트랜스 폼 & 라이팅의 하드웨어 가속화를 실행할 수 있는 하드웨어 디바이스는, D3DDEVCAPS_HWTRANSFORMANDLIGHT 디바이스 기능을 공개한다. C++ 로 TnLHAL 디바이스를 생성 하려면 ,IDirect3D7::CreateDevice 메소드를 호출해, 제 1 파라미터로서 IID_IDirect3DTnLHalDevice 값을 건네준다. 상세한 것에 대하여는, 「Direct3D 디바이스의 생성」을 참조할것.

[Visual Basic]

트랜스 폼 & 라이팅의 하드웨어 가속화를 실행할 수 있는 하드웨어 디바이스는, D3DDEVCAPS_HWTRANSFORMANDLIGHT 디바이스 기능을 공개한다. Visual Basic 로 TnLHAL 디바이스를 생성 하려면 ,Direct3D7.CreateDevice 메소드를 호출해, 제 1 파라미터로서 "IID_IDirect3DTnLHALDevice" 캐릭터 라인 정수를 건네준다. 상세한 것에 대하여는, 「Direct3D 디바이스의 생성」을 참조할것.


RGB 디바이스

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

[C++]

C++ 로 기술된 어플리케이션에서는,IDirect3D7::CreateDevice 메소드를 사용해 RGB 디바이스를 생성 한다. 제 1 파라미터로서 IID_IDirect3DRGBDevice 를 건네준다. 상세한 것에 대하여는, 「Direct3D 디바이스의 생성」을 참조할것.

[Visual Basic]

Visual Basic 로 기술된 어플리케이션에서는,Direct3D7.CreateDevice 메소드를 사용해 RGB 디바이스를 생성 한다. 제 1 파라미터로서 "IID_IDirect3DRGBDevice" 캐릭터 라인 정수를 건네준다. 상세한 것에 대하여는, 「Direct3D 디바이스의 생성」을 참조할것.


레퍼런스 래스터라이저

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

보통, 레퍼런스 래스터라이저는 Direct3D 에 의해 열거되지 않는다. 열거되도록(듯이) 하려면 ,HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Direct3D\Drivers 레지스트리 키의 EnumReference 이름 첨부값을, 제로 이외의 DWORD 값으로 설정한다.

[C++]

C++ 로 기술된 어플리케이션에서는,IDirect3D7::CreateDevice 메소드를 사용해 참조 디바이스를 생성 한다. 제 1 파라미터로서 IID_IDirect3DRefDevice 를 건네준다. 상세한 것에 대하여는, 「Direct3D 디바이스의 생성」을 참조할것.

[Visual Basic]

Visual Basic 어플리케이션에서는,Direct3D7.CreateDevice 메소드를 사용해 참조 디바이스를 생성 한다. 제 1 파라미터로서 "IID_IDirect3DefDevice" 캐릭터 라인 정수를 건네준다. 상세한 것에 대하여는, 「Direct3D 디바이스의 생성」을 참조할것.


종래의 디바이스의 종류

[Visual Basic]

주 : 여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에서는, 이하의 디바이스의 종류는 지원 하고 있지 않다.

[C++]

구릴리스의 DirectX 에서는, MMX 디바이스 및 램프 디바이스라고 하는 2 개의 추가의 디바이스의 종류를 지원 하고 있었다. 이러한 디바이스는 현재의 버젼의 DirectX 에서는 사용되지 않지만, 종래의 인터페이스를 개입시켜 사용할 수 있다.

MMX 디바이스

MMX 란, 몇개의 마이크로 프로세서가 지원 하는 특별한 명령 세트이다. MMX 디바이스를 이용하는 것으로, 멀티미디어 및 3D 처리의 퍼포먼스가 향상한다. MMX 지원이 인스톨 되고 있는 경우, Direct3D 는 그것을 사용해 렌더링의 처리 속도를 올린다.

MMX 디바이스는, HAL 디바이스와 같은 하드웨어 가속화 디바이스는 아니다. 트랜스 폼, 라이팅, 및 라스터화 모듈은, 소프트웨어에 완전 이행 된다. 그러나, MMX 디바이스는, 다른 종류의 소프트웨어 에뮬레이션 Direct3D 디바이스보다 퍼포먼스면에서 우수하다.

어플리케이션으로 IDirect3D2 인터페이스를 사용하는 경우는, 명시적으로 MMX 디바이스를 생성 해야 한다. 그러나,IDirect3D3 인터페이스로부터는, MMX 디바이스와 RGB 디바이스는 완전히 같은 기능 세트를 이행 한다 ( 「RGB 디바이스」를 참조할것). 마이크로 프로세서가 MMX 테크놀러지를 지원 하고 있는 경우, 어플리케이션으로 RGB 디바이스를 생성 하려고 하면(자), Direct3D 는 자동적으로 MMX 디바이스를 생성 한다.

어플리케이션에서는,IDirect3D3::CreateDevice 메소드를 호출해, 제 1 파라미터로서 IID_IDirect3DMMXDevice 를 건네주어 MMX 디바이스를 생성 한다. 상세한 것에 대하여는, 「Direct3D 디바이스의 생성」을 참조할것. 유저의 컴퓨터로 MMX 테크놀러지가 지원되어 있지 않은 경우, 어플리케이션이 MMX 디바이스의 생성을 명시적으로 요구 하면,CreateDevice 는 실패한다.

램프 디바이스

IDirect3D3 또는 IDirect3D7 인터페이스를 사용해 Direct3D 램프 디바이스를 생성 할 수 없다. 또,IDirect3DDevice3 또는 IDirect3DDevice7 인터페이스에 대해 기존의 램프 디바이스를 문의하는 일도 할 수 없다. 간단하게 말하면, 램프 디바이스는, 멀티 텍스쳐 블렌딩 옵션을 지원 하고 있지 않다. 이러한 기능을 에뮬레이트 하려면 , MMX 또는 RGB 소프트웨어 에뮬레이션 디바이스를 사용한다.

램프 디바이스는, 흑백 라이팅을 사용하는 소프트웨어 에뮬레이션 디바이스이다. 유저의 컴퓨터에, 다른 종류의 Direct3D 디바이스를 지원 할 뿐(만큼)의 처리 능력이 없는 경우, 어플리케이션은 램프 디바이스를 선택할 수 있다. 램프 모드에서는, 트랜스 폼 모듈은 완전하게 이용할 수 있지만, 컬러 라이팅은 지원되어 있지 않다. 램프 모드 디바이스에서는, 흑백 그레이 스케일 라이팅용의 Direct3D 라이팅 모듈만 사용한다. 따라서, 램프 모드의 라이팅에는 휘도(Luminance)는 있지만 색은 없다. 그레이 스케일값은, 라이팅색의 파랑 성분에 저장 된다.

램프 모드에서는, 색머트리얼과 텍스쳐를 사용할 수 있다. Direct3D 에서는, 머트리얼 또는 텍스쳐의 색을 베이스 컬러로서 사용한다. 백색광 (휘도(Luminance)가 가장 높다)을 머트리얼이나 텍스쳐에 맞히는 경우는, 베이스 컬러가 사용된다. 다만, 라이팅의 강도가 최대가 아닌 경우, 머트리얼 또는 텍스쳐의 색에 회색이나 흑이 섞인다. 어플리케이션으로 텍스쳐를 램프 모드로 사용하는 경우, 종래의 D3DLIGHTSTATETYPE 열거형의 D3DLIGHTSTATE_MATERIAL 멤버를 설정할 필요가 있다. 램프 모드에서는, 8 비트의 텍스쳐만 사용할 수 있다.

램프 모드로 머트리얼 또는 텍스쳐의 컬러값을 제어하려면 , 어플리케이션의 생성시에 D3DMATERIAL 구조체의 dwRampSize 멤버를 설정할 필요가 있다. Direct3D 는 머트리얼 및 텍스쳐의 색을 베이스 컬러로서 사용한다. dwRampSize 멤버의 값에 의해, 라이팅의 명도에 응한, 베이스 컬러의 그라데이션수가 정해진다. Direct3D 는,dwRampSize 멤버로 지정된 엔트리수 (1 베이스)의 색팔레트를 생성 한다. 팔레트의 최대 엔트리수는 256 미만 (Windows 가 사용하는 예약이 끝난 색 가지수를 256 으로부터 뺀 수)이기 (위해)때문에, 어플리케이션에 필요한 그레이 스케일값의 최소수를 지정할 필요가 있다.

최적인 결과를 얻으려면 , 어플리케이션의 머트리얼의 대부분 또는 모든 램프 사이즈를 같은 값으로 한다. Direct3D 가 팔레트의 엔트리를 다 사용하면(자), 기존의 머트리얼을 검색해 가장 가까운 색을 검출한다. 램프 사이즈가 같은 머트리얼만 일치하는 것이라고 보여진다.

램프 디바이스는, 주로 기존의 어플리케이션과의 호환성을 유지하기 위해서(때문에) 준비되어 있다. 일반적으로, RGB 디바이스를 지원 할 뿐(만큼)의 처리 능력이 없는 컴퓨터는, 3D 어플리케이션에는 적합하지 않다.

어플리케이션으로 IDirect3D2::CreateDevice 메소드를 호출해, 제 1 파라미터로서 IID_IDirect3DRampDevice 를 건네주어 램프 디바이스를 생성 한다. 상세한 것에 대하여는, 「Direct3D 디바이스의 생성」을 참조할것.


디바이스 인터페이스

[Visual Basic]

주 : 여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에서는 COM 인터페이스는 사용하지 않는다. 또, 실행 버퍼를 사용한 렌더링은 지원 하고 있지 않다.

[C++]

C++ 로 기술된 어플리케이션에서는, 디바이스 인터페이스를 사용해, Direct3DDevice 오브젝트의 렌더링 스테이트와 라이팅 스테이트를 조작해, 렌더링 처리를 실행한다. Direct3D 에는 디바이스용의 COM 인터페이스로서IDirect3DDevice,IDirect3DDevice2,IDirect3DDevice3, 및 IDirect3DDevice7 . 의 4 개가 있다. 이러한 인터페이스의 기본이 되는 것은, 최초의 3 개의 인터페이스를 모두 또는 IDirect3DDevice7 인터페이스만 공개하는 2 개의 COM 오브젝트의 언젠가이다. 어플리케이션으로 사용하는 디바이스 오브젝트, 즉 인터페이스는, 그 디바이스의 생성에 사용하는 메소드에 완전하게 의존한다. 상세한 것에 대하여는, 「Direct3D 디바이스의 생성」을 참조할것. 종래의 IDirect3DDevice,IDirect3DDevice2, 및 IDirect3DDevice3 인터페이스는, DirectX 7.0 보다 이전의 버젼의 DirectX 에서 공개되고 있는 기능과 렌더링 기능을 나타낸다. 이 문서에서는, 이러한 오브젝트를 구디바이스로서 취급하고 있다. IDirect3DDevice7 인터페이스를 공개하는 오브젝트는, 이 문서에서는 새로운 디바이스로서 취급해, 렌더링 기능의 최신 세트를 나타낸다. 어플리케이션에서는,IUnknown::QueryInterface 메소드를 사용해도, 이것들 신구의 인터페이스간에 이행 할 수 없다. 이것은, 구디바이스 오브젝트가 최신 기능에 대응하고 있지 않는 것과 새로운 디바이스 오브젝트는 후방 호환성보다 퍼포먼스 최적화를 위해서(때문에) 설계되고 있는 것이 이유이다. Direct3D 에서는, 어플리케이션으로 사용하는 인터페이스를 사전에 선택할 필요가 있다.

이 문서에서는, 일반적으로, 최신 인터페이스가 사용되는 것을 전제로 하고 있다. 다만, 이전의 이행에 대한 지식이 도움이 되는 경우도 있다. 구버젼의 DirectX 에서 공개되고 있던 IDirect3DDevice 인터페이스는,실행 버퍼를 사용하는 프로그래밍용의 메소드를 제공하고 있다. 실행 버퍼는, 주로 후방 호환성을 유지하기 위해서(때문에) 제공되고 있었다. 그 이후의 DirectX 의 버젼에서는, 보다 심플한 DrawPrimitive 모델이 사용되게 되어, 장면을 렌더링하기 위한 코드가 매우 간소화되었기 때문에, 실행 버퍼는 사용되지 않게 되었다. DrawPrimitive 에 의한 렌더링은,IDirect3DDevice 인터페이스 이후의 모든 인터페이스로 채용되고 있다. DirectX 7.0 의 Direct3D 직접 모드에서는 IDirect3DDevice7 인터페이스가 새롭게 사용되게 되어, 작업이 보다 한층 간소화되는 것과 동시에, 하드웨어 가속화를 이용할 수 있게 되었다. IDirect3DDevice7 를 공개하는 디바이스 오브젝트에서는, 어떠한 하드웨어로 실행하고 있는 경우 하드웨어 가속화에 의한 트랜스 폼 & 라이팅 처리를 실행할 수 있다. 상세한 것에 대하여는, 「DirectX 7.0 에서의 직접 모드의 변경점」을 참조할것. 이러한 인터페이스는, 몇개의 공통의 메소드, 특히 DrawPrimitive 의 렌더링을 실행하는 인터페이스를 공유하고 있다. 상세한 것에 대하여는, 「렌더링」을 참조할것.

DirectX 5.0 으로 IDirect3DDevice2 인터페이스가 도입되기 이전은, Direct3D 디바이스가 DirectDrawSurface 오브젝트에의 인터페이스였다. IDirect3DDevice2 및 IDirect3DDevice3 인터페이스가 이행 하는 것은, Direct3DDevice 오브젝트가 DirectDraw 표면으로부터 완전히 독립하고 있는 디바이스 오브젝트 모델, 및 라이팅, 머트리얼, 뷰포트 등은 장면을 렌더링 하기 위해서 1 개(살) 또는 복수의 디바이스에 관련짓고 가능한 오브젝트이다고 하는 개념이다. 한편,IDirect3DDevice7 인터페이스는, 라이팅, 머트리얼, 및 뷰포트 파라미터를 개별의 오브젝트로부터 디바이스 자체로 이동하는 것으로, Direct3D 오브젝트 모델을 한층 더 간소화하고 있다.

주 : IDirect3DDevice3 와 IDirect3DDevice7. 사이에는 인터페이스의 버젼 번호는 없다.

Direct3D 디바이스 오브젝트는 DirectDraw 표면으로부터 독립해, 독자적으로 수명을 가지고 있다. 따라서, Direct3D 디바이스 오브젝트는, 어플리케이션으로 필요한 경우에는 언제라도, 다양한 DirectDraw 표면을 렌더링 타겟으로서 사용할 수 있다. 상세한 것에 대하여는, 「IDirect3DDevice7::SetRenderTarget 」를 참조할것.


디바이스 스테이트

Direct3D 디바이스는 스테이트 머신이다. 즉, 어플리케이션으로 라이팅, 렌더링, 및 트랜스 폼 모듈의 스테이트를 설정해, 렌더링시에 그러한 모듈을 개입시켜 데이터를 건네준다. 이 섹션에서는, 렌더링 스테이트, 및 Direct3D 직접 모드로 사용하는 각 렌더링 스테이트에 대해 자세하게 설명한다. 또, 디바이스 스테이트의 그룹을 1 회의 호출로 처리할 수 있는 디바이스 스테이트 블록에 대해서도 설명한다. 설명하는 주제는 다음과 같다.

  • 렌더링 스테이트
  • 스테이트 블록
[C++]

C++ 어플리케이션에서는,IDirect3DDevice7::SetRenderState 메소드를 사용해 대부분의 디바이스 스테이트를 설정한다.

[Visual Basic]

Visual Basic 로 개발된 어플리케이션에서는,Direct3DDevice7.SetRenderState 메소드를 사용해 대부분의 디바이스 스테이트를 설정한다.

주 : 디바이스 스테이트에는, 유저 정의 클립면, 트랜스 폼, 및 라이팅 스테이트도 포함된다. 상세한 것에 대하여는, 「유저 정의 클립면」, 「지오메트리 파이프라인」, 및 「라이팅과 머트리얼」을 참조할것.


렌더링 스테이트

이 섹션에서는, 렌더링 스테이트의 개념에 대해 설명해, 렌더링 스테이트와 텍스쳐 스테이지 스테이트를 비교한다. 또, 다양한 렌더링 스테이트에 대해 자세하게 설명한다. 설명하는 주제는 이하대로이다.

  • 렌더링 스테이트에 대해
  • 현재 텍스쳐
  • anti-aliasing 스테이트
  • 텍스쳐 애드레싱 스테이트
  • 텍스쳐 랩핑 스테이트
  • 텍스쳐 경계
  • 텍스쳐 퍼스펙티브 스테이트
  • 텍스쳐 필터링 스테이트
  • 아우트라인 및 전부 칠해 스테이트
  • 쉐이딩 스테이트
  • 포그(안개:fog) 스테이트
  • 알파 블렌딩 스테이트
  • 알파 실험 스테이트
  • 텍스쳐 블렌딩 스테이트
  • 컬링(Culling) 스테이트
  • 깊이 버퍼링 스테이트
  • 램프 스테이트
  • 서브 픽셀 보정 스테이트
  • 면마스크 스테이트
  • 컬러 키잉 스테이트
  • 렌더링 커멘드 배치처리 스테이트
  • 스텐실 버퍼 스테이트
  • 프리미티브 클리핑 스테이트
  • 라이팅 스테이트
  • 범위의 갱신 스테이트
  • 앰비언트 라이트 스테이트
  • 버텍스색스테이트


스테이트 블록

Direct3D 직접 모드의 스테이트 블록이란, 디바이스 스테이트의 그룹이다. 이것에는, 렌더링 스테이트, 라이팅 및 머트리얼 파라미터, 트랜스 폼 스테이트, 텍스쳐 스테이지 스테이트, 및 현재 텍스쳐 정보가 있다. 스테이트 블록은, 디바이스의 현재의 스테이트의 snapshot로서 처리되는지, 또는 명시적으로 기록되어 1 회의 호출로 디바이스에 적용할 수가 있다. 디바이스 스테이트 블록은, 어플리케이션으로 필요한 공통된 일련의 스테이트 변경을 고속화하기 위해서, 렌더링 디바이스로 최적화할 수가 있다. 또, 디바이스 스테이트 블록의 사용은, 단지 디바이스 스테이트의 적용을 간소화에도 연결된다.

이 섹션의 이하의 주제에서는, 디바이스 스테이트 블록의 주요한 개념에 대해, 및 어플리케이션에서의 사용 방법에 대해 설명한다.

  • 스테이트 블록 핸들
  • 스테이트 블록의 기록
  • 스테이트 블록의 취득
  • 스테이트 블록의 적용
  • 사전 정의하는 스테이트 블록의 생성
  • 스테이트 블록의 삭제


디바이스의 사용

이 섹션에서는, Direct3D 직접 모드의 어플리케이션으로 Direct3D 디바이스를 사용하는 방법에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • Direct3D 디바이스의 열거
  • Direct3D 디바이스의 생성
  • 트랜스 폼의 설정
  • 렌더링


Direct3D 디바이스의 열거

어플리케이션은, 어플리케이션의 동작환경의 하드웨어에 문의를 실시해, 그 하드웨어로 지원 되고 있는 Direct3D 디바이스의 종류를 검출할 수가 있다. 이 섹션에서는, Direct3D 디바이스의 열거에 관해서 주요한 2 개의 태스크에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • 디바이스 열거의 시작
  • 열거된 디바이스의 선택


Direct3D 디바이스의 생성

퍼포먼스에 관한 중요 사항 지정의 Direct3D 오브젝트에 의해 생성 된 렌더링 디바이스는, 모두 같은 물리 리소스를 공유한다. 단일의 Direct3D 오브젝트로부터 복수의 렌더링 디바이스를 생성 하는 것은 가능하지만, 이것들은 모두 같은 하드웨어를 공유하기 위해(때문에), 퍼포먼스가 크게 저하한다.

[C++]

C++ 어플리케이션으로 Direct3D 디바이스를 생성 하려면 , 우선 DirectDrawCreateEx 함수를 호출해 DirectDraw 오브젝트를 생성 해,IDirect3D7 인터페이스를 취득해야 한다. 상세한 것에 대하여는, 「Direct3D 에의 액세스」를 참조할것. 다음에,IDirect3D7::CreateDevice 메소드를 호출해 Direct3D 디바이스를 생성 한다. 이 메소드는,IDirect3DDevice7 인터페이스에의 포인터를 어플리케이션에 건네준다.

다음의 그림은, C++ 로 Direct3D 디바이스를 생성 하는 처리를 나타낸다.

주 : 「Direct3D 에의 액세스」로 설명하도록(듯이),DirectDraw 컴퍼넌트는 2 개의 COM 오브젝트로부터 구성된다. 최신의 오브젝트는 DirectDraw7 로 불려DirectDrawCreateEx 함수를 호출하는 것으로 생성 된다. 이 오브젝트는,IDirect3D7 인터페이스를 공개하는 유일한 오브젝트이다. IDirect3DDevice7 인터페이스를 공개하는 Direct3D 디바이스를 생성할 수 있는 것은, 이 오브젝트뿐이다. 이와 같이 해 생성 된 Direct3DDevice 오브젝트는, 종래의 Direct3D 인터페이스를 공개하지 않는다. 이전의 Direct3D 디바이스 인터페이스를 필요로 하는 어플리케이션에서는,DirectDrawCreate 메소드를 사용해 DirectDraw 오브젝트를 생성 해, 다음에 목적의 오브젝트를 생성 할 필요가 있다.

다음의 코드는,IDirect3Device7 인터페이스를 지원 하는 Direct3D 렌더링 디바이스를 생성 하는 처리를 나타낸다.

LPDIRECTDRAW7    lpDD;              // IDirectDraw7 인터페이스
LPDIRECT3D7     lpD3D;              // IDirect3D7 인터페이스
LPDIRECTDRAWSURFACE7  lpddsRender;  // 렌더링 표면
LPDIRECT3DDEVICE7     lpd3dDevice;  // D3D 디바이스
HRESULT hr;

// DirectDraw 인터페이스를 생성 한다.
// 현재의 디스플레이 드라이버를 사용한다.
hr = DirectDrawCreateEx (NULL, (void **) &lpDD, IID_IDirectDraw7, NULL);
if (FAILED (hr))
{
// 에러 처리 코드
}

// IDirect3D7 인터페이스를 취득한다.
hr =
    lpDD->QueryInterface (IID_IDirect3D7, (void **) &lpD3D);
if (FAILED (hr))
{
// 에러 처리 코드
}

//
// 간단하게 하기 위해서, 이하의 태스크의 코드는 생략 한다.
//
// 이 시점에서, 어플리케이션의 협조 레벨을 설정할 필요가 있다.
// 풀 스크린으로 사용하는 경우는,
// 디스플레이 모드를 설정할 필요가 있다.
// 여기서, 프라이머리 표면을 생성 한다.
// 이 시점에서, 렌더링 표면을 생성 한다. 이 코드에서는,
// 생성 된 렌더링 표면은,
// 변수 lpddsRender 에 의해 포인트 되고 있다고 한다.
// Z 버퍼를 사용하는 경우는, 여기서 생성 한다.
// 이 시점에서, Direct3D 디바이스의 열거를 실행할 수 있다.

hr = lpD3D->CreateDevice (IID_IDirect3DHALDevice,
                               lpddsRender,
                               &lpd3dDevice,
                               NULL);

이 예에서는,IDirect3D7::CreateDevice 메소드를 호출해 Direct3D 디바이스를 생성 하고 있다. 여기에서는, 호출이 성공하면(자) Direct3D HAL 디바이스가 생성 된다.

어플리케이션으로 생성 하는 타겟 DirectDraw 렌더링 표면은, Direct3D 렌더링 타겟으로서 사용할 수 있도록(듯이) 생성 할 필요가 있다. 그 때문에(위해)는,DDSURFACEDESC2 구조체를 IDirectDraw7::CreateSurface 메소드에 건네줄 필요가 있다. DDSURFACEDESC2 구조체에는 ddsCaps 라고 하는 멤버가 있어, 이것은 DDSCAPS2 형의 구조체이다. DDSCAPS2 구조체에는 dwCaps 라고 하는 멤버가 있어, 이것은,IDirectDraw7::CreateSurface 를 호출하면나무에 DDSCAPS_3DDEVICE 로 설정해야 한다.

렌더링 타겟 표면을 하드웨어 가속화 렌더링 디바이스로 사용할때는, 그 렌더링 타겟 표면을 디스플레이 메모리로 생성 할 필요가 있다 (DDSCAPS_VIDEOMEMORY 플래그를 사용). 그렇지 않은 경우는, 시스템 메모리로 렌더링 타겟 표면을 생성 한다 (DDSCAPS_SYSTEMMEMORY 플래그를 사용).

주 : 넓게 사용되고 있는 일부의 하드웨어 디바이스에서는, 렌더링 타겟 및 깊이 버퍼 표면으로 같은 비트 깊이를 사용할 필요가 있다. 그러한 하드웨어에서는, 어플리케이션으로 16 비트의 렌더링 타겟 표면을 사용하는 경우는, Attach 하는 깊이 버퍼도 16 비트가 아니면 안된다. 32 비트의 렌더링 타겟 표면이면, 32 비트의 깊이 버퍼가 아니면 안된다. 8 비트의 깊이 버퍼는, 필요에 따라서 스텐실 버퍼링에 사용할 수 있다.

어플리케이션이 동작하는 하드웨어에 이러한 요건이 있어, 어플리케이션이 이것을 채우지 않은 경우, 비대응 표면을 사용하는 렌더링 디바이스를 생성 하려고 하면(자) 실패한다. IDirectDraw7::GetDeviceIdentifier 를 사용해, 이 제한이 있는 하드웨어를 특정할 수 있다.

[Visual Basic]

Direct3D 디바이스를 생성 하려면 , 우선 보통의 방법으로 DirectDraw 오브젝트를 초기화해,Direct3D7 클래스에의 참조를 취득할 필요가 있다. 상세한 것에 대하여는, 「Direct3D 에의 액세스」를 참조할것. 다음에,Direct3D7::CreateDevice 메소드를 호출해 Direct3D 디바이스를 생성 해야 한다. 이 메소드는,Direct3DDevice7 클래스 오브젝트에의 참조를 돌려준다.

다음의 그림은, Visual Basic 로 Direct3D 디바이스를 생성 하는 처리를 나타낸다.

다음의 코드는, Visual Basic 로 Direct3D 디바이스를 생성 하는 처리를 나타낸다.

'이 예에서는, g_dx 변수에 DirectX7 오브젝트에의
'유효한 참조가 저장 되고 있다.
Private Sub Test()
On Local Error Resume Next

Dim ddraw As DirectDraw7        ' DirectDraw7 클래스
Dim d3d As Direct3D7            ' Direct3D3 클래스
Dim ddsRender As DirectDrawSurface7 '렌더링 표면
Dim d3dDev As Direct3DDevice7   '  Direct3D 디바이스

' DirectDraw7 오브젝트를 생성 한다.
'현재의 디스플레이 드라이버를 사용한다.
Set ddraw = g_dx.DirectDrawCreate("")
If Err.Number <> DD_OK Then
'에러 처리 코드
End If

' Direct3D7 오브젝트를 취득한다.
Set d3d = ddraw.GetDirect3D
If Err.Number <> DD_OK Then
'에러 처리 코드
End If

    '
'간단하게 하기 위해서, 이하의 태스크의 코드는 생략 되어 있다.
    '
'여기서, 어플리케이션의 협조 레벨을 설정할 필요가 있다.
'풀 스크린으로 사용하는 경우는,
'디스플레이 모드를 설정할 필요가 있다.
'여기서, 프라이머리 표면을 생성 한다.
'여기서, 렌더링 표면을 생성 한다. 이 코드에서는,
'생성 된 렌더링 표면은,
'변수 ddsRender 에 의해 포인트 되고 있다고 한다.
' Z 버퍼를 사용하는 경우는, 여기서 생성 한다.
'이 시점에서, Direct3D 디바이스의 열거를 실행할 수 있다.

Set d3dDev = d3d.CreateDevice("IID_IDirect3DHALDevice", ddsRender)
End Sub

이 코드에서는,Direct3D7.CreateDevice 메소드를 호출해 Direct3D 디바이스를 생성 하고 있다. 이 예에서는, 호출이 성공하면(자) Direct3D HAL 디바이스가 생성 된다.

어플리케이션으로 생성 하는 타겟 DirectDraw 렌더링 표면은, Direct3D 렌더링 타겟으로서 사용할 수 있도록(듯이) 생성 할 필요가 있다. 그 때문에(위해)는,DDSURFACEDESC2 변수를 DirectDraw7::CreateSurface 메소드에 건네줄 필요가 있다. DDSURFACEDESC2 형에는,DDSCAPS2 형의 ddsCaps 라고 하는 멤버가 있다. DDSCAPS2 형에는 lCaps 라고 하는 멤버가 있어, 이것은,DirectDraw7::CreateSurface 를 호출하면나무에 DDSCAPS_3DDEVICE 로 설정해야 한다.

렌더링 타겟 표면을 하드웨어 가속화 렌더링 디바이스로 사용하려면 , 그 렌더링 타겟 표면을 디스플레이 메모리로 생성 할 필요가 있다 (DDSCAPS_VIDEOMEMORY 플래그를 사용). 그렇지 않은 경우는, 시스템 메모리로 렌더링 타겟 표면을 생성 한다 (DDSCAPS_SYSTEMMEMORY 플래그를 사용).

주 : 넓게 사용되고 있는 일부의 하드웨어에서는, 렌더링 타겟 및 깊이 버퍼 표면으로 같은 비트 깊이를 사용할 필요가 있다. 그러한 하드웨어에서는, 어플리케이션으로 16 비트의 렌더링 타겟 표면을 사용하는 경우는, Attach 하는 깊이 버퍼도 16 비트가 아니면 안된다. 32 비트의 렌더링 타겟 표면이면, 32 비트의 깊이 버퍼가 아니면 안된다. 8 비트의 깊이 버퍼는, 필요에 따라서 스텐실 버퍼링에 사용할 수 있다.

어플리케이션이 동작하는 하드웨어에 이러한 요건이 있어, 어플리케이션으로 이것채우지 않은 경우, 비대응 표면을 사용하는 렌더링 디바이스를 생성 하려고 하면(자) 실패한다.


트랜스 폼의 설정

[C++]

C++ 에서는,IDirect3DDevice7::SetTransform 메소드를 호출해 트랜스 폼을 적용한다. 예를 들어, 뷰 트랜스 폼을 설정하려면 , 다음과 같은 코드를 사용한다.

    HRESULT hr
    D3DMATRIX  view;

// 뷰 행렬에 데이터를 설정한다.

    hr = lpDev->SetTransform(D3DTRANSFORMSTATE_VIEW, &view);

if(FAILED(hr)){
// 에러 처리 코드
    }

IDirect3DDevice7::SetTransform 를 호출하는 경우, 제 1 파라미터로 설정할 수 있는 값은 몇개인가 있지만, 일반적으로는 D3DTRANSFORMSTATE_WORLD, D3DTRANSFORMSTATE_VIEW, 및 D3DTRANSFORMSTATE_PROJECTION 를 설정한다. 이러한 트랜스 폼 스테이트는,D3DTRANSFORMSTATETYPE 열거형에 정의되고 있다. 또, 이 열거에는, 텍스쳐 좌표에 적용하는 트랜스 폼을 설정하는 D3DTRANSFORMSTATE_TEXTURE1 ~ D3DTRANSFORMSTATE_TEXTURE7 스테이트도 정의되고 있다.

[Visual Basic]

Visual Basic 에서는,Direct3DDevice7.SetTransform 메소드를 호출해 트랜스 폼을 적용한다. 예를 들어, 뷰 트랜스 폼을 설정하려면 , 다음과 같은 코드를 사용한다.

On Local Error Resume Next
Dim view As D3DMATRIX

'뷰 행렬에 데이터를 설정한다.
Call d3dDev.SetTransform(D3DTRANSFORMSTATE_VIEW, view)

If Err.Number <> DD_OK Then
'에러 처리 코드
End If

Direct3DDevice7.SetTransform 를 호출하는 경우, 제 1 파라미터로 설정할 수 있는 값은 몇개인가 있지만, 일반적으로는 D3DTRANSFORMSTATE_WORLD, D3DTRANSFORMSTATE_VIEW, 및 D3DTRANSFORMSTATE_PROJECTION 를 설정한다. 이러한 트랜스 폼 스테이트는,CONST_D3DTRANSFORMSTATETYPE 열거에 정의되고 있다. 또, 이 열거에는, 텍스쳐 좌표에 적용하는 트랜스 폼을 설정하는 D3DTRANSFORMSTATE_TEXTURE1 ~ D3DTRANSFORMSTATE_TEXTURE7 스테이트도 정의되고 있다.


렌더링

어플리케이션에서는, DrawPrimitive 패밀리의 메소드를 사용해 3D 신을 렌더링 한다. 종래의 실행 버퍼를 사용한 렌더링 모델보다, DrawPrimitive 아키텍쳐를 사용하는 것을 추천 한다. 따라서, 이하의 주제에서는 DrawPrimitive 를 사용한 렌더링에 대해 설명한다.

  • 버텍스의 그룹화
  • 장면의 시작과 종료
  • 표면의 클리어
  • 프리미티브의 렌더링
  • 프리미티브의 종류
  • 렌더링 스테이트


AGP 표면과 Direct3D 디바이스

3D 어플리케이션으로 텍스쳐를 사용 하면, 3 D 화면의 리얼리티가 큰폭으로 늘어난다. 텍스쳐를 저장 하는 메모리는, 개발자가 생각하는 만큼 풍부하지 않다. DirectDraw 와 Direct3D 에서는, AGP (Accelerated Graphics Port) 아키텍쳐가 지원 되고 있다. AGP 아키텍쳐를 채용하는 것으로, 어플리케이션의 메모리 공간에서 DirectDraw 표면을 생성 할 수 있게 된다. 그 결과, 텍스쳐를 저장 하는 메모리가 큰폭으로 확대한다.

AGP 아키텍쳐를 지원 하는 것은, Direct3D HAL 디바이스뿐이다. AGP 아키텍쳐의 사용의 상세한 것에 대하여는, 「비로컬 비디오 메모리 표면의 사용」을 참조할것.


지오메트리 파이프라인

3D 어플리케이션을 설계 하면 와, 편리성을 고려해 미크론으로부터 파섹까지, 모든 단위로 월드를 정의한다. 어플리케이션은, 이 월드의 기술을 Direct3D 에 건네준다. 이 기술에는, 월드내에 있는 모든 오브젝트의 사이즈와 상대 위치 좌표, 및 뷰아의 위치 좌표와 정정도가 포함된다. Direct3D 는, 이 기술을 스크린 위에의 일련의 픽셀에 트랜스 폼 한다. 이 처리 (지오메트리의 2 D 화면에의 트랜스 폼)를, 지오메트리 파이프라인 또는 트랜스 폼 파이프라인이라고 부른다.

이 섹션에서는, 주로 Direct3D 에 있어서의 지오메트리 파이프라인에 대해 설명한다. 이하의 주제에서는, 중요한 개념에 대해, 및 이러한 개념에 대응하는 Direct3D API 의 개념에 대해 설명한다.

  • 파이프라인의 개요
  • 월드 트랜스 폼
  • 뷰 트랜스 폼
  • 투영 트랜스 폼
  • 뷰포트와 클리핑
  • 래스터라이저


파이프라인의 개요

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

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

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

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

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

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

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


월드 트랜스 폼

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

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


월드 트랜스 폼이란

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

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


월드 행렬의 설정

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

[C++]

다음의 예는, C++ 로 기술된 가공의 3D 모델 클래스에 관한 것이다. 여기에서는, D3dutil.cpp 및 D3dmath.cpp 파일 (DirectX SDK 에 부속)의 헬퍼-함수를 사용해, 모델을 방향 짓는 회전을 3 회 실시해, 한층 더 월드 공간에서의 위치 좌표를 기준에 그 모델을 재배치하는 평행이동을 실시하는 월드 행렬을 생성 한다.

/*
* 이 예에서는,
* 이하의 변수가 유효해, 초기화되고 있다고 한다.
 *
* m_vPos 변수는, 이 모델의 월드 좌표에서의 위치 좌표를 저장 한다
* D3DVECTOR 이다.
 *
* m_fPitch, m_fYaw, 및 m_fRoll 변수는,
* 경사각, 편흔들림각, 및 회전각 (라디안)으로 나타내는 모델의 방향을 저장 한다
* D3DVALUE 이다.
 */

D3DMATRIX C3DModel::MakeWorldMatrix(void)
{
D3DMATRIX matWorld, // 생성 하는 월드 행렬.
matTemp,  // 회전용의 일시 행렬.
matRot;   // 최종적인 회전 행렬 (matWorld 에 적용한다).

// 행렬 연결에 관한 "왼쪽에서 오른쪽" 룰을 사용해,
// 회전을 적용하기 전에
// 평행이동을 오브젝트의 월드 위치 좌표에 적용한다.
    D3DUtil_SetTranslateMatrix(matWorld, m_vPos);
    D3DUtil_SetIdentityMatrix(matRot);

    //
// 다음에, 방향 짓고 변수를
// 월드 행렬에 적용한다.
    //
    if(m_fPitch || m_fYaw || m_fRoll)
    {
// 회전 행렬을 생성 해 결합한다.
D3DUtil_SetRotateXMatrix(matTemp, m_fPitch);    // 경사
D3DMath_MatrixMultiply(matRot, matRot, matTemp);
D3DUtil_SetRotateYMatrix(matTemp, m_fYaw);      // 편 흔들어라
D3DMath_MatrixMultiply(matRot, matRot, matTemp);
D3DUtil_SetRotateZMatrix(matTemp, m_fRoll);     // 회전
D3DMath_MatrixMultiply(matRot, matRot, matTemp);

// 회전 행렬을 적용해 월드 행렬을 완성한다.
D3DMath_MatrixMultiply(matWorld, matRot, matWorld);
    }
    return (matWorld);
}

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

[Visual Basic]

다음의 예는, 가공의 3D 모델 클래스에 관한 것이다. 여기에서는,DirectX7 클래스의 함수를 사용해, 모델을 방향 짓는 회전을 3 회 실시해, 한층 더 월드 공간에서의 위치 좌표를 기준에 그 모델을 재배치하는 평행이동을 실시하는 월드 행렬을 생성 한다.

'
'이 예에서는,
'이하의 변수가 유효해, 초기화되고 있다고 한다.
'
'   g_dx 변수에는, DirectX7 오브젝트에의 유효한 참조가 저장 된다.
'
' m_vPos 변수는, 이 모델의 월드 좌표에 있어서의 위치 좌표를 저장 한다
' D3DVECTOR 이다.
'
' m_fPitch, m_fYaw, 및 m_fRoll 는,
'경사각, 편흔들림각, 및 회전각 (라디안)으로 나타내는 모델의 방향을 저장 한다
' Single 형의 변수이다.
'
Public Function MakeWorldMatrix() As D3DMATRIX
Dim matWorld As D3DMATRIX   '결과적으로 돌려주는 월드 행렬.
Dim matTemp As D3DMATRIX    '각 회전을 저장하기 위한 일시 행렬.
Dim matRot As D3DMATRIX     '회전을 나타내는 일시 행렬.

' matWorld 를 수정해 평행이동 행렬을 생성 한다.
Call g_dx.IdentityMatrix(matWorld)
matWorld.rc41 = m_vPos.x
matWorld.rc42 = m_vPos.y
matWorld.rc43 = m_vPos.z

Call g_dx.IdentityMatrix(matRot) '회전 행렬을 설정한다.

    '
'행렬 연결의 "왼쪽에서 오른쪽" 룰을 사용해,
'회전을 적용하기 전에
'평행이동을 오브젝트의 월드 위치 좌표에 적용한다.
    '

'회전 행렬을 생성 해 결합한다.
If (m_sPitch <> 0) Or (m_sYaw <> 0) Or (m_sRoll <> 0) Then
'최초로 X축회전,
Call g_dx.RotateXMatrix(matTemp, m_sPitch)
Call g_dx.MatrixMultiply(matRot, matRot, matTemp)

'다음에 Y축회전,
Call g_dx.RotateYMatrix(matTemp, m_sYaw)
Call g_dx.MatrixMultiply(matRot, matRot, matTemp)

'마지막에 Z축회전.
Call g_dx.RotateZMatrix(matTemp, m_sRoll)
Call g_dx.MatrixMultiply(matRot, matRot, matTemp)

' matWorld 에 이미 존재하는 평행이동 행렬에 회전 행렬을 적용해,
'월드 행렬을 완성한다.
Call g_dx.MatrixMultiply(matWorld, matRot, matWorld)
End If

MakeWorldMatrix = matWorld
End Function

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

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


뷰 트랜스 폼

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

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


뷰 트랜스 폼이란

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

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

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

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

다른 방법으로서 복잡한 뷰 행렬을 직접 생성 하는 방법도 있다 (D3dutil.cpp 소스 파일에 있는 D3DUTIL_SetViewMatrix 헬퍼-함수에서는, Visual Basic 어플리케이션으로 사용하는 DirectX7.ViewMatrix 메소드와 같게, 이 방법을 사용한다). 이 방법에서는, 카메라의 월드 공간에 있어서의 위치 좌표와 장면내의 "주시점" 을 사용해, 카메라 공간의 좌표축의 방향을 기술하는 벡터를 파생시킨다. 주시점으로부터 카메라 위치 좌표를 뺄셈 해, 카메라의 방향 벡터 (벡터 n) 용의 벡터를 생성한다. 다음에, 벡터 n 와 월드 공간의 y 축의 외 츠무를 잡아, 정규화해,"우측향" 벡터 (벡터 u)를 생성한다. 다음에, 벡터 u 와 n 의 외 츠무를 잡아,"윗방향" 벡터 (벡터 v)를 결정한다. 우측향 (u), 윗방향 (v), 및 뷰 방향 (n)의 벡터는, 월드 공간에 있어서의 카메라 공간의 좌표축의 방향을 기술한다. x, y, z 의 평행이동 계수는, 카메라 위치 좌표와 u,v,n 벡터의 사이의 내적의 음수를 취해 계산한다.

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

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

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


뷰 행렬의 설정

[C++]

이 SDK 부속의 D3dutil.cpp 소스 파일의 D3DUtil_SetViewMatrix 헬퍼-함수는, 이 함수에게 건네지는 카메라 위치 좌표와 주시점에 근거해 뷰 행렬을 생성 한다. 이 함수는,Magnitude ,CrossProduct , 및 DotProduct D3D_OVERLOADS 헬퍼-함수를 사용한다.

HRESULT D3DUtil_SetViewMatrix( D3DMATRIX& mat, D3DVECTOR& vFrom,
       D3DVECTOR& vAt, D3DVECTOR& vWorldUp )
{
// 깊이를 나타내는 Z 축의 기저 벡터를 취득한다. 이것은,
// 주시점에 대한 시점과는 다르다.
    D3DVECTOR vView = vAt - vFrom;

    FLOAT fLength = Magnitude( vView );
    if( fLength < 1e-6f )
return E_INVALIDARG;

// z 축의 기저 벡터를 정규화한다.
    vView /= fLength;

// 내적을 취득해, 윗방향 벡터에 대한, Z 축의 기저 벡터의
// 투영을 계산한다. 이 투영은 y 축의 기저 벡터이다.
    FLOAT fDotProduct = DotProduct( vWorldUp, vView );

    D3DVECTOR vUp = vWorldUp - fDotProduct * vView;

// 부정한 윗방향 벡터를 입력했기 때문에
// 벡터가 제로에 근처 되었을 경우는, 벡터를 디폴트값으로 한다.
    if( 1e-6f > ( fLength = Magnitude( vUp ) ) )
    {
vUp = D3DVECTOR( 0.0f, 1.0f, 0.0f ) - vView.y * vView;

// 벡터가 더 제로에 가까우면, 다른 축을 이용한다.
if( 1e-6f > ( fLength = Magnitude( vUp ) ) )
{
    vUp = D3DVECTOR( 0.0f, 0.0f, 1.0f ) - vView.z * vView;

    if( 1e-6f > ( fLength = Magnitude( vUp ) ) )
return E_INVALIDARG;
}
    }

// y 축의 기저 벡터를 정규화한다.
vUp /= fLength;

// x 축의 기저 벡터는, y 축 및 z 축의 기저 벡터의
// 외적으로서 간단하게 요구된다.
D3DVECTOR vRight = CrossProduct( vUp, vView );

// 행렬의 생성을 시작 한다. 선두의 3 행에는,
// 뷰를 주시점으로써 회전하기 위한 기저 벡터를 저장 한다.
    D3DUtil_SetIdentityMatrix( mat );
    mat. _11 = vRight.x;    mat. _12 = vUp.x;    mat. _13 = vView.x;
    mat. _21 = vRight.y;    mat. _22 = vUp.y;    mat. _23 = vView.y;
    mat. _31 = vRight.z;    mat. _32 = vUp.z;    mat. _33 = vView.z;

// 이동값을 실행한다 (회전은 아직 시점에 있다).
    mat. _41 = - DotProduct( vFrom, vRight );
    mat. _42 = - DotProduct( vFrom, vUp );
    mat. _43 = - DotProduct( vFrom, vView );

    return S_OK;
}

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

[Visual Basic]

Visual Basic 어플리케이션에서는,DirectX7.ViewMatrix 메소드를 사용해, 카메라 위치 좌표, 주시점,"윗방향" 벡터 (보통은 0,1,0), 및 라디안 단위로 지정하는 회전값에 근거해 뷰 행렬을 생성 한다.

다음의 Visual Basic 코드는,ViewMatrix 메소드의 사용 방법을 나타낸다.

'이 예에서는, g_dx 변수에 글로벌 DirectX7 오브젝트에의
'유효한 참조가 저장 되고 있다고 한다.
Dim matView  As D3DMATRIX
Dim vFrom As D3DVECTOR, _
vTo As D3DVECTOR, _
vUp As D3DVECTOR

vFrom.x = 0:vFrom.y = 0:vFrom.z = -15
vTo.x = 0:vTo.y = 0:vTo.z = 0
vUp.x = 0:vUp.y = 1:vUp.z = 0

'행렬을 초기화해 단위행렬로 한다.
g_dx.IdentityMatrix matView

' 0,0,-15 에 있는 카메라로 뷰 행렬을 생성 한다.
'이것은, 월드 원점을 가리켜, vFrom->vTo 벡터를 중심으로 한 회전을 실시하지 않는다.
Call g_dx.ViewMatrix(matView, vFrom, vTo, vUp, 0)

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

퍼포먼스의 최적화 Direct3D 에서는, 설정된 월드 행렬 및 뷰 행렬을 사용해, 몇개의 내부 데이터 구조를 구축한다. 새로운 월드 행렬 또는 뷰 행렬을 설정할 때마다, 관계하는 내부 구조가 재계산된다. 이러한 행렬을 프레임 마다 2 만회나 설정하는 등 빈번하게 설정 하면, 다대한 계산 부하가 발생한다. 필요한 계산을 최소한으로 억제하려면 , 월드 행렬로서 설정하는 "월드 뷰" 행렬에 월드 행렬 및 뷰 행렬을 연결해, 다음에 뷰 행렬을 단위행렬로 설정한다. 월드 행렬 및 뷰 행렬의 각 캐쉬 카피는 보관 유지해 두는 것. 필요에 따라서 월드 행렬을 수정, 연결, 및 리셋 할 수 있다 (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++]

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

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

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

[Visual Basic]

Visual Basic 어플리케이션에서는, 폭과 높이의 치수는,D3DVIEWPORT7 형의 lWidth 및 lHeight 멤버에 직접 대응한다.

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

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


투영 행렬의 설정

[C++]

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

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()의 마지막

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

[Visual Basic]

Visual Basic 로 기술된 어플리케이션에서는, 「투영 트랜스 폼이란」으로 설명하도록(듯이), 스스로 투영 행렬을 생성 할 수 있다. 다만,DirectX7 오브젝트에는 이 방법의 이행이 포함되어 있어DirectX7.ProjectionMatrix 메소드에 의해 제공된다.

다음의 Visual Basic 코드에서는, 이 DirectX7.ProjectionMatrix 의 일반적인 사용 방법을 나타낸다.

'
'이 예에서는, g_dx 변수에 글로벌 DirectX7 오브젝트에의
'참조가 저장 되고 있다.
'
' pi 변수는,
'π의 근사치 (3.141592)가 저장 되는 Single 형의 변수이다.
Dim matProj As D3DMATRIX

'행렬을 초기화해 단위행렬로 한다.
g_dx.IdentityMatrix matProj

' 1 으로 1000 에 있는 전방 및 후방 클립면, 및π/2 라디안 (90о)의 시점 각도의
'절두체를 나타낸다
'투영 행렬을 생성 한다.
Call g_dx.ProjectionMatrix(matProj, 1, 1000, pi / 2)

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


W 버퍼에 유효한 투영 행렬

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

다음의 그림은, 대응하고 있지 않는 투영 행렬, 및 같은 행렬을 스케일링 해 시점으로부터의 상대 시점으로부터의 상대 위치 좌표에 의한 포그(안개:fog)가 유효하게 되도록(듯이) 한 행렬을 나타낸다.

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

주 : Direct3D 에서는, 현재 설정되어 있는 투영 행렬이 w 베이스의 심도계산에 사용된다. 그 결과, 어플리케이션에서는 Direct3D 트랜스 폼 파이프라인을 사용하지 않는 경우에서도, 희망의 w 베이스 기능을 받는, 대응한 투영 행렬을 설정할 필요가 있다.


뷰포트와 클리핑

이 섹션에서는, 지오메트리 파이프라인의 마지막 단계의 클리핑에 대해 설명한다. 이것에 대해서는, 이하의 주제로 나누어 설명한다.

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

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

[C++]

IDirect3DDevice7 인터페이스는, C++ 어플리케이션으로 디바이스에 대한 뷰포트 파라미터의 조작을 가능하게 하는 메소드를 공개한다 ( 구릴리스의 DirectX 에서는, 뷰포트는, COM 오브젝트 자체의 인터페이스를 공개하는 개별의 COM 오브젝트로서 이행 되고 있었다).

[Visual Basic]

Direct3DDevice7 클래스에는, Visual Basic 어플리케이션으로 디바이스에 대한 뷰포트 파라미터의 조작을 가능하게 하는 메소드가 있다.


뷰포트란

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

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

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


뷰포트 직사각형

[C++]

주 : DirectX 7.0 으로 사용하는 뷰포트 구조체는, 구릴리스로 추천 된 D3DVIEWPORT2 구조체와는 완전히 다르다. 다음의 설명에 확실히 대충 훑어본 데다가, 뷰포트 파라미터를 적절히 사용하는 것.

C++ 의 뷰포트 직사각형은,D3DVIEWPORT7 구조체를 사용해 정의한다. D3DVIEWPORT7 구조체는,IDirect3DDevice7 인터페이스가 제공하는 뷰포트 조작 메소드의IDirect3DDevice7::SetViewport 및 IDirect3DDevice7::GetViewport 로 사용한다. D3DVIEWPORT7 구조체에는 dwX,dwY,dwWidth, 및 dwHeight 의 4 개의 멤버가 있다. 이것들을 사용해, 장면이 렌더링 되는 렌더링 타겟 표면 영역 "뷰포트 직사각형" 을 정의한다.

이러한 값은, 다음의 그림에 나타내도록(듯이), 목적지의 직사각형, 즉 뷰포트 직사각형에 대응한다.

D3DVIEWPORT7 구조체의 dwX,dwY,dwWidth, 및 dwHeight 멤버로 지정하는 값은, 렌더링 타겟 표면의 맨 왼쪽 위쪽으로부터의 화면 좌표이다. 이 구조체는, 장면이 렌더링 되는 깊이 범위를 나타내는 2 개의 추가 멤버 dvMinZ 및 dvMaxZ 를 정의한다.

DirectX 7.0 으로 사용하는 뷰포트 구조체는, 구릴리스로 추천 된 D3DVIEWPORT2 구조체와는 완전히 다르다. 즉,D3DVIEWPORT7 구조체는 종래의 구조체를 간소화한 것으로, 3D 투영 공간에 있어서의 뷰포트의 사이즈 및 치수를 기술하는 멤버가 없어져 있다. 대부분의 어플리케이션에서는, 현재 존재하고 있지 않는 멤버는 항상 같은 값으로 설정하지만, 뷰포트의 어스펙트비(가로세로 비율)의 조정하기 위해서 그러한 멤버를 사용하는 어플리케이션도 조금 있다. 이 이펙트를 정확하고 확실히 실행하는 것은 곤란하다.

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

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

[Visual Basic]

Visual Basic 어플리케이션에서는,D3DVIEWPORT7 형을 사용해 뷰포트 직사각형을 정의한다. D3DVIEWPORT7 형은,Direct3DDevice7 클래스가 제공하는 뷰포트 조작 메소드의 Direct3DDevice7.SetViewport 및 Direct3DDevice7.GetViewport 로 사용한다. D3DVIEWPORT7 형에는 lX,lY,lWidth, 및 lHeight 의 4 개의 멤버가 있다. 이것들을 사용해, 장면이 렌더링 되는 렌더링 타겟 표면 영역 "뷰포트 직사각형" 을 정의한다.

이러한 값은, 다음의 그림에 나타내도록(듯이), 목적지의 직사각형, 즉 뷰포트 직사각형에 대응한다.

D3DVIEWPORT7 형의 lX,lY,lWidth, 및 lHeight 멤버로 지정하는 값은, 렌더링 타겟 표면의 맨 왼쪽 위쪽으로부터의 화면 좌표이다. 이 형태는, 장면이 렌더링 되는 깊이 범위를 나타내는 2 개의 추가 멤버 minz 및 maxz 를 정의한다.

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


클리핑 볼륨

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

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

[C++]

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

[Visual Basic]

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


뷰포트의 스케일링

[C++]

뷰포트용의 D3DVIEWPORT7 구조체의 dwX,dwY,dwWidth, 및 dwHeight 멤버에 치수를 지정해, 렌더링 타겟 표면의 뷰포트의 위치 좌표 및 크기를 정의한다. 이러한 값은, 렌더링 타겟 표면의 맨 왼쪽 위쪽으로부터의 화면 좌표이다.

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

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

주 : DirectX 7.0 의 뷰포트 스케일링 행렬은, 버텍스를 스케일링 하는 D3DVIEWPORT7 구조체의 dvMinZ 및 dvMaxZ 멤버를 짜넣어 깊이 범위 [dvMinZ, dvMaxZ] 를 맞춘다. 이것은, 이러한 멤버가 클리핑에 사용되고 있던 구릴리스의 DirectX 의 의미들과는 다르다. 상세한 것에 대하여는, 「뷰포트 직사각형」 및 「클리핑 볼륨」을 참조할것. 어플리케이션에서는, 보통,dvMinZ 및 dvMaxZ 를 각각 0.0 및 1.0 으로 설정해 깊이 범위 전체에의 렌더링을 실행한다. 다만, 다른 값을 설정해 어떠한 이펙트를 얻을 수도 있다. 양쪽 모두의 값을 0.0 으로 설정해 모든 오브젝트를 강제적으로 foreground에 렌더링 하거나 양쪽 모두의 값을 1.0 으로 설정해 모든 오브젝트를 백그라운드에 렌더링 할 수가 있다.

[Visual Basic]

뷰포트용의 D3DVIEWPORT7 형의 IX,IY,IWidth, 및 IHeight 멤버에 치수를 지정해, 렌더링 타겟 표면의 뷰포트의 위치 좌표 및 크기를 정의한다. 이러한 값은, 렌더링 타겟 표면의 맨 왼쪽 위쪽으로부터의 화면 좌표이다.

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

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


뷰포트의 사용

이 섹션에서는, 뷰포트의 조작에 대해 자세하게 설명한다. 설명하는 주제는 다음과 같다.

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


래스터라이저

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

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


라이팅과 머트리얼

이 섹션에서는, Direct3D 직접 모드에서의 앰비언트 라이트 레벨의 사용, 및 3D 신내의 오브젝트에의 라이팅과 머트리얼의 적용에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • 라이팅과 머트리얼의 개요

    Direct3D 직접 모드 신에 있어서의 광원과 머트리얼의 역할에 대해 평이한 말로 설명한다.

  • Direct3D 의 라이팅 모델과 자연광의 비교

    Direct3D 의 라이팅 모델에 대해 자세하게 설명해, 이 라이팅 모델과 자연광을 비교한다.

  • 라이팅과 머트리얼의 컬러값

    Direct3D 직접 모드에 대해 라이팅과 머트리얼로 사용하는 RGBA 컬러값에 대해 설명한다.

  • 다이렉트 라이트와 앰비언트 라이트의 비교

    실제의 광원과 앰비언트 라이트의 역할을 비교한다.

  • 라이팅 엔진의 유효/무효

    Direct3D 의 라이팅 엔진의 유효/무효를 바꾸는 방법에 대해 설명한다.

  • 라이트

    Direct3D 의 라이팅에 대해, 및 이 라이팅을 장면내에서 사용하는 방법에 대해 설명한다.

  • 머트리얼

    Direct3D 직접 모드의 머트리얼에 대해, 및 이 머트리얼을 장면내에서 사용하는 방법에 대해 설명한다.

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

    Direct3D 의 라이팅 모델로 기본이 되는 수학적 계산에 대해 자세하게 설명한다.


라이팅과 머트리얼의 개요

라이팅이 유효하게 되어 있을 때, Direct3D 는 렌더링의 최종 단계로서 장면을 rasterize 할 때, 장면의 광원에 의해 생성되는 라이팅의 색과 강도나, 장면의 앰비언트 라이트 레벨 외에도, 현재의 머트리얼 컬러 ( 및 관련지을 수 있었던 텍스쳐 맵의 텍셀), 버텍스의 디퓨즈색과 스펙큐러색 (지정되고 있는 경우) 의 편성에 근거해, 렌더링 하는 각 픽셀의 색을 결정한다. Direct3D 의 라이팅과 머트리얼을 사용할때는, Direct3D 측에서 자동적으로 라이팅의 상세를 제어하도록 할 수 있다. 다만, 경험을 쌓은 유저이면, 필요에 따라서 스스로 라이팅을 실행할 수 있다.

라이팅과 머트리얼의 처리 방법에 따라, 렌더링 한 장면의 표시는 크게 다르다. 머트리얼은, 표면으로부터의 반사광 상태를 정의한다. 다이렉트 라이트와 앰비언트 라이트 레벨은, 반사광을 정의한다. Direct3D 측에서 라이팅을 제어하는 경우는, 머트리얼을 사용해 장면을 렌더링 해야 한다. 라이팅은 장면의 렌더링에 대해 실제로는 반드시 필요하지 않지만, 라이팅없이 렌더링 한 장면은 매우 보기 나쁘다. 라이팅이 없는 장면을 렌더링 했을 경우는, 겨우 장면의 오브젝트의 실루엣이 표시되는 것만으로, 세부는 충분히 표시되지 않는다.


Direct3D 의 라이팅 모델과 자연광의 비교

자연계에서는, 광원으로부터 방사된 빛은, (몇천이나 몇백만은 아닌으로 해도) 몇백의 물체에 반사한 끝에 우리의 눈에 닿는다. 빛은 반사할 때마다, 그 일부가 물체의 표면에 흡수되거나 주위에 확산해, 그 나머지가 다른 물체의 표면이나 우리를 향한다. 이 과정은, 빛이 감쇠해 사라져 없어지는지, 또는 우리가 빛이 닿은 것을 지각할 때까지 반복해진다. 그러나, 빛이 몇회 반사할까 등 아는 사람이 있을까. 1 회밖에 반사하지 않는 경우도 있을 것이다. 또, 백회 혹은 몇백만회나 반사하는 일도 있을 것이다.

자연광의 움직임을 완전하게 시뮬레이트 하는 계산에는, 너무 방대한 시간이 걸리기 (위해)때문에, 리얼타임 3D 그래픽스로 사용할 수 없는 것은 명백하다. 거기서, 속도를 고려해, Direct3D 의 라이팅 모델에서는 자연광의 움직임을 대략적으로 시뮬레이트 한다. Direct3D 에서는, 최종적인 색을 생성 하는 색성분, 적, 록, 및 파랑에 의해 빛을 그린다. 상세한 것에 대하여는, 「라이팅과 머트리얼의 컬러값」을 참조할것. Direct3D 에서는, 빛이 표면에 반사했을 때, 빛의 색과 표면 자체를 수학적으로 처리하는 것으로, 최종적으로 스크린에 드로잉(Drawing) 되는 색을 생성 한다. Direct3D 로 사용하는 알고리즘에 관한 특정의 정보에 대해서는, 「Direct3D 의 라이팅에 있어서의 수학적 계산」을 참조할것.

Direct3D 직접 모드의 라이팅 모델은, 크게 나누어 앰비언트 라이트와 다이렉트 라이트의 2 개가 있다. 이것들은 서로 다른 속성을 가져, 표면의 머트리얼과의 상호작용도 다르다. 앰비언트 라이트는, 방향도 광원도 가지지 않고, 환경내를 산란하고 있는 빛으로, 환경빛이라고도 말한다. 앰비언트 라이트의 강도는, 어느 위치 좌표에 대해도 하위 레벨로 유지된다. 앰비언트 라이트의 적절한 예로서는, 카메라맨이 사용하는 간접조명이 있다. Direct3D 의 앰비언트 라이트에게는, 자연광과 같이, 실제의 방향이나 광원은 없다. 어느 색과 강도뿐이다. 실제, 앰비언트 라이트의 레벨은, 장면내의 미츠를 출발하는 오브젝트와는 전혀 관계하지 않는다. 앰비언트 라이트는 스펙큐러 반사를 일으키지 않는다.

다이렉트 라이트는, 장면내의 광원이 생성하는 빛이다. 다이렉트 라이트에게는 항상 색과 강도가 있어, 특정의 방향으로 나아간다. 다이렉트 라이트는, 표면의 머트리얼과 상호작용 해 스펙큐러 하이라이트를 낳아, 그 방향은 gouraud shading등의 쉐이딩 알고리즘으로 계수로서 사용된다. 다이렉트 라이트의 반사는, 장면의 앰비언트 라이트의 레벨에 영향을 주지 않는다. 장면내의 다이렉트 라이트를 생성하는 광원에는 다양한 특성이 있어, 거기에 따라 장면을 어떻게 비출지가 다르다. 상세한 것에 대하여는, 「라이트」를 참조할것.

게다가 다각형의 머트리얼에는, 다각형이 빛을 어떻게 반사할까를 결정하는 특성이 있다. 머트리얼이 어떻게 앰비언트 라이트를 반사하는지를 나타내는 단일의 반사 특성을 설정해, 머트리얼의 스펙큐러 반사율 및 디퓨즈 반사율을 결정하는 각각의 특성을 설정한다. 상세한 것에 대하여는, 「머트리얼」을 참조할것.


라이팅과 머트리얼의 컬러값

Direct3D 직접 모드에는, 색을 기술하는 4 개의 성분 (적, 록, 청, 및 알파)이 있어, 이것들을 조합해 최종적인 색이 생성된다. C++ 의 D3DCOLORVALUE 구조체는, 이러한 각 성분을 저장 한다 (Visual Basic 어플리케이션에서는 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 의 경우는, 녹색의 빛을 모두 반사한다. 머트리얼에 복수의 반사율을 지정해, 다양한 이펙트를 생성 할 수 있다. 상세한 것에 대하여는, 「머트리얼 프로퍼티」를 참조할것.

앰비언트 라이트의 컬러값은, 다이렉트 라이트 광원과 머트리얼에 사용하는 컬러값과는 다르다. 상세한 것에 대하여는, 「다이렉트 라이트와 앰비언트 라이트의 비교」를 참조할것.


다이렉트 라이트와 앰비언트 라이트의 비교

다이렉트 라이트와 앰비언트 라이트는 ,함께 장면내의 오브젝트를 비추지만, 양자는 서로 서로 영향을 줄 것은 없고, 각각이 가지는 이펙트는 크게 달라서 , 이러한 조작 방법에 대해서도 완전히 다르다.

[C++]

다이렉트 라이트는, 문자 대로, 다이렉트이다. 다이렉트 라이트는 항상 방향과 색을 가져, 이것은 gouraud shading등의 쉐이딩 알고리즘의 계수로서 사용된다. 라이팅의 종류가 다르면, 다이렉트 라이트의 방사도 달라, 각각 특별한 감쇠 이펙트를 낳는다. 다이렉트 라이트의 라이팅 파라미터 세트는,IDirect3DDevice7::SetLight 메소드를 호출해 생성 한다. 상세한 것에 대하여는, 「라이트」를 참조할것.

앰비언트 라이트는, 장면내의 어느 위치 좌표에도 이펙트를 미친다. 앰비언트 라이트는, 오브젝트나 오브젝트의 장면내의 위치 좌표에 관계없이, 장면 전체를 같은 강도의 빛으로 비추는 라이팅이라고 생각할 수가 있다. 앰비언트 라이트는 모든 위치에 존재해, 색과 강도를 가질 뿐으로, 위치 좌표나 방향은 가지지 않는다. 앰비언트 라이트 레벨을 설정하려면 ,IDirect3DDevice7::SetRenderState 를 호출해,dwRenderStateType 파라미터로서 D3DRENDERSTATE_AMBIENT 를 지정해,dwRenderState 파라미터로서 희망의 RGBA 색을 지정한다.

앰비언트 라이트의 색은, RGBA 값의 형태를 취해, 각 성분은 0 ~ 255 의 정수값이다 (이것은, Direct3D 직접 모드의 대부분의 컬러값과는 다르다. 상세한 것에 대하여는, 「라이팅과 머트리얼의 컬러값」을 참조할것). RGBA_MAKE 매크로를 사용해, 정수로부터 RGBA 값을 생성할 수 있다. 적, 초록, 및 파랑 성분을 조합해, 앰비언트 라이트의 최종적인 색을 생성 한다. 알파 성분은 색의 투명도를 제어한다. 램프 에뮬레이션에서는, 앰비언트 라이트는 색을 가지지 않기 때문에, 알파 성분은 휘도(Luminance)에 사용된다. 하드웨어 가속화 또는 RGB 에뮬레이션을 사용할때는, 알파 성분은 무시된다.

[Visual Basic]

다이렉트 라이트는, 문자 대로, 다이렉트이다. 다이렉트 라이트는 항상 방향과 색을 가져, 이것은 gouraud shading등의 쉐이딩 알고리즘의 계수로서 사용된다. 라이팅의 종류가 다르면, 다이렉트 라이트의 방사도 달라, 각각 특별한 감쇠 이펙트를 낳는다. 다이렉트 라이트의 라이팅 파라미터 세트는,Direct3DDevice7.SetLight 메소드를 호출해 설정한다. 상세한 것에 대하여는, 「라이트」를 참조할것.

앰비언트 라이트는, 장면내의 어느 위치 좌표에도 이펙트를 미친다. 앰비언트 라이트는, 오브젝트나 오브젝트의 장면내의 위치 좌표에 관계없이, 장면 전체를 같은 강도의 빛으로 비추는 라이팅이라고 생각할 수가 있다. 앰비언트 라이트는 모든 위치 좌표에 존재해, 색과 강도를 가질 뿐으로, 위치 좌표나 방향은 가지지 않는다. 앰비언트 라이트 레벨을 설정하려면 ,Direct3DDevice7.SetRenderState 메소드를 호출해,state 파라미터로서 D3DRENDERSTATE_AMBIENT 를 지정해,renderstate 파라미터로서 희망의 RGBA 색을 지정한다.

DirectX7.CreateColorRGBA 메소드를 사용해,Single 형의 값으로부터 RGBA 값을 생성할 수 있다. 적, 초록, 및 파랑 성분을 조합해, 앰비언트 라이트의 최종적인 색을 생성 한다. 알파 성분은 색의 투명도를 제어한다. 램프 에뮬레이션에서는, 앰비언트 라이트는 색을 가지지 않기 때문에, 알파 성분은 휘도(Luminance)에 사용된다. 하드웨어 가속화 또는 RGB 에뮬레이션을 사용할때는, 알파 성분은 무시된다.


라이팅 엔진의 유효/무효

[C++]

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

어플리케이션으로 버텍스 버퍼를 사용하는 경우는, 처리는 약간 다르지만, 다음과 같이 간단하다. IDirect3DVertexBuffer7::ProcessVertices 또는 IDirect3DVertexBuffer7::ProcessVerticesStrided 메소드를 호출하면나무에 D3DVOP_LIGHT 플래그를 지정할지 어떨지로, 버텍스 버퍼에 대해서 라이팅을 유효 또는 무효로 한다.

[Visual Basic]

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

어플리케이션으로 버텍스 버퍼를 사용하는 경우는, 처리는 약간 다르지만, 다음과 같이 간단하다. Direct3DVertexBuffer7.ProcessVertices 메소드를 호출하면나무에 D3DVOP_LIGHT 플래그를 지정할지 어떨지로, 버텍스 버퍼에 대해서 라이팅을 유효 또는 무효로 한다.


라이트

라이트는, 장면의 오브젝트를 비추기 위해서(때문에) 사용한다. 이 섹션에서는, 라이팅에 대해, 및 Direct3D 직접 모드에서의 라이트의 사용 방법에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • 라이트 오브젝트의 개요
  • 라이트 프로퍼티
  • 라이트의 사용


라이트 오브젝트의 개요

Direct3D 에서는, 포인트 라이트, spotlight, 및 디렉셔널 라이트의 3 종류의 라이트를 사용한다. 라이트 프로퍼티 세트를 생성 할 경우에, 사용하는 라이트의 종류를 선택한다. 라이트 프로퍼티와 거기에 따르는 계산 위에의 오버헤드는, 라이팅의 종류에 따라서 다르다. Direct3D 라이팅 모듈로 지원 되는, 이하의 광원에 도착해 설명한다.

  • 포인트 라이트
  • spotlight
  • 디렉셔널 라이트

주 : DirectX 7.0 에서는, 구릴리스의 DirectX 로 사용한 패러럴 포인트 라이트는 사용하지 않는다.

광원과 앰비언트 라이트 레벨을 혼동 하지 않는 것. 상세한 것에 대하여는, 「다이렉트 라이트와 앰비언트 라이트의 비교」, 「라이트 프로퍼티」, 및 「라이트의 사용」을 참조할것.


라이트 프로퍼티

라이트 프로퍼티는, 광원의 종류와 색을 결정한다. 사용하는 라이트의 종류에 의해, 라이트는 감쇠와 범위의 프로퍼티나 spotlight 이펙트의 프로퍼티를 가질 수가 있다. 그러나, 라이트의 종류에 따라서는 사용할 수 없는 프로퍼티도 있다. Direct3D 직접 모드에서는, C++ 의 경우는 D3DLIGHT7 구조체, Visual Basic 의 경우는 D3DLIGHT7 형에, 모든 종류의 광원의 라이트 프로퍼티에 관한 정보를 보관 유지한다. 이 섹션에서는, 모든 라이트 프로퍼티에 대해 설명한다. 설명하는 주제는 이하대로이다.

  • 라이트의 종류
  • 라이트의 색
  • 라이트의 위치 좌표, 범위, 및 감쇠
  • 라이트의 방향
  • spotlight 프로퍼티

라이트 프로퍼티는, 광원이 장면내의 오브젝트를 어떻게 비출까에 영향을 준다. 상세한 것에 대하여는, 「라이트의 사용」, 「라이트 프로퍼티의 설정」, 및 「Direct3D 의 라이팅에 있어서의 수학적 계산」을 참조할것.


라이트의 사용

이 섹션에서는, Direct3D 직접 모드 어플리케이션에서의 라이트의 사용에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • 라이트 프로퍼티의 설정
  • 라이트의 유효/무효
  • 라이트 프로퍼티의 취득


머트리얼

이 섹션에서는, 머트리얼과 Direct3D 직접 모드 어플리케이션에서의 머트리얼의 사용 방법에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • 머트리얼이란
  • 머트리얼 프로퍼티
  • 머트리얼의 사용

디폴트의 머트리얼 프로퍼티 어플리케이션으로, 렌더링 처리에 머트리얼 프로퍼티가 지정되어 있지 않은 경우는, 디폴트의 머트리얼이 사용된다. 디폴트의 머트리얼은, 모든 디퓨즈 라이트 (거의 백색)를 반사하지만, 앰비언트 반사 또는 스펙큐러 반사는 생기지 않고, 에미션(emission)색이 없다.


머트리얼이란

머트리얼은, 3D 신으로 다각형이 빛을 어떻게 반사하는지, 또는 어떻게 빛을 방사하는 것처럼 보이는지를 지정한다. 본질적으로는, 머트리얼은, Direct3D 가 렌더링 하는 다각형에 대해 다음의 정보를 Direct3D 에 지시하는 프로퍼티의 집합이다.

  • 다각형에 의한 앰비언트 라이트와 디퓨즈 라이트의 반사 방법
  • 다각형으로부터의 스펙큐러 하이라이트 상태
  • 다각형이 미츠를 출발하고 있도록(듯이) 보이게 할지 어떨지
[C++]

C++ 로 기술된, Direct3D 직접 모드의 어플리케이션에서는,D3DMATERIAL7 구조체를 사용해 머트리얼 프로퍼티를 정의한다. 상세한 것에 대하여는, 「머트리얼 프로퍼티」를 참조할것.

[Visual Basic]

Visual Basic 로 기술된, Direct3D 직접 모드의 어플리케이션에서는,D3DMATERIAL7 형을 사용해 머트리얼 프로퍼티를 정의한다. 상세한 것에 대하여는, 「머트리얼 프로퍼티」를 참조할것.


머트리얼 프로퍼티

[C++]

머트리얼 프로퍼티는, 머트리얼의 디퓨즈, 앰비언트 반사, 에미션(emission), 및 스펙큐러 하이라이트 특성을 상세하게 지정한다. Direct3D 는,D3DMATERIAL7 구조체에 모든 머트리얼 프로퍼티를 보관 유지한다. 머트리얼 프로퍼티는, 그 머트리얼을 사용하는 다각형을 라스터화할 때 Direct3D 가 사용하는 색에 영향을 준다. 스펙큐러 속성을 제외해, 각 프로퍼티는, 머트리얼이 소정의 종류의 라이트의 적, 초록, 및 파랑 성분을 어느 정도 반사하는지를 나타내는 RGBA 색과 알파 블렌딩 계수 (RGBA 색의 알파 성분)로서 지정한다. 머트리얼의 스펙큐러 속성은, 색 및 강도로 지정한다. 상세한 것에 대하여는, 「라이팅과 머트리얼의 컬러값」을 참조할것.

디퓨즈 반사와 앰비언트 반사

D3DMATERIAL7 구조체의 dcvDiffuse 및 dcvAmbient 멤버는, 장면내에서 머트리얼이 앰비언트 라이트와 디퓨즈 라이트를 어떻게 반사하는지를 지정한다. 대부분의 장면에서는, 앰비언트 라이트보다 디퓨즈 라이트가 훨씬 많이 사용되기 (위해)때문에, 색의 결정에 대해 디퓨즈 반사가 가장 크게 영향을 준다. 게다가 디퓨즈 라이트는 방향을 가지고 있기 (위해)때문에, 그 입사각은 반사의 전체적인 강도에 영향을 준다. 디퓨즈 반사는, 라이트가 버텍스 법선과 평행에 버텍스에 해당될 때가 가장 강하다. 입사각이 커지는 것에 따라, 디퓨즈 반사의 이펙트는 감소한다. 다음에 나타내도록(듯이), 반사광의 양은 입사빛과 버텍스 법선이 이루는 각도의 코사인이다.

앰비언트 라이트와 같이, 앰비언트 반사는 방향을 가지지 않는다. 앰비언트 반사는, 렌더링 한 오브젝트의 외관의 색에의 영향은 적지만, 전체의 색에 영향을 주어, 머트리얼로부터 반사하는 디퓨즈 라이트가 전혀 없는지, 그저 적을 때 가장 눈에 띈다. 머트리얼의 앰비언트 반사는, D3DLIGHTSTATE_AMBIENT 플래그를 지정해 IDirect3DDevice7::SetLightState 메소드를 호출하는 것으로 장면으로 설정한 앰비언트 라이트의 영향을 받는다.

디퓨즈 반사 및 앰비언트 반사는 ,함께 작용해 오브젝트로 지각되는 색을 결정한다. 이것들은 보통은 같은 값이다. 예를 들어, 청색의 수정 오브젝트를 렌더링 하려면 , 디퓨즈 라이트와 앰비언트 라이트의 파랑 성분만 반사하는 머트리얼을 생성 한다. 이 수정을 백색광으로 비추어진 방에 두면(자) 청색으로 보인다. 그러나, 적색빛 밖에 없는 방에서는, 같은 수정에서도 검게 보인다. 이것은, 수정의 머트리얼이 적색빛을 반사하지 않기 때문이다.

에미션(emission)

머트리얼을 사용해, 렌더링 한 오브젝트 자체가 미츠를 출발하고 있도록(듯이) 보이게 할 수가 있다. D3DMATERIAL7 구조체의 dcvEmissive 멤버를 사용해, 에미션(emission)빛의 색 및 투명도를 지정한다. 에미션(emission)는 오브젝트의 색에 영향을 준다. 예를 들어, 어두운 머트리얼을 밝게 해, 발광색의 일부가 될 수가 있다.

머트리얼의 에미션(emission) 속성을 사용해, 오브젝트가 미츠를 출발하고 있도록(듯이) 보이게 할 수가 있다. 이 방법에서는, 장면에 라이트를 추가할 때의 오버헤드가 발생하지 않는다. 청색의 수정의 예로, 장면내외의 오브젝트에는 라이트를 비추지 않고 , 수정만이 빛나고 있도록(듯이) 보이게 하는 경우는, 에미션(emission) 속성을 사용 하면이야 있고. 에미션(emission) 속성을 가지는 머트리얼이 발하는 빛은, 장면내외의 오브젝트로 반사할 수 있는 빛은 아니기 때문에 주의 해야 한다. 이 이펙트를 얻으려면 , 장면내에 추가의 라이트를 배치할 필요가 있다.

스펙큐러 반사

스펙큐러 반사는 오브젝트상에 하이라이트를 생성 해, 오브젝트가 빛나고 있도록(듯이) 보이게 한다. D3DMATERIAL7 구조체에는, 스펙큐러 하이라이트색과 머트리얼의 전체적인 빛남을 지정하는 2 개의 멤버가 포함된다. dcvSpecular 멤버를 희망의 RGBA 색 (가장 일반적인 색은 백색 또는 밝은 회색이다)으로 설정해, 스펙큐러 하이라이트의 색을 결정한다. dvPower 멤버로 설정하는 값은, 스펙큐러 이펙트의 샤프함을 제어한다.

스펙큐러 하이라이트를 사용 하면, 훌륭한 이펙트를 얻을 수 있다. 다시 청색의 수정을 예로서 생각한다. dvPower 의 값이 큰 만큼 선명한 스펙큐러 하이라이트가 되어, 수정의 빛남이 늘어난다. 이 값이 작을 정도 이펙트가 미치는 영역은 확대하지만, 반사가 둔해져 수정이 서리로 덮인 것처럼 보인다. 전혀 광택이 없는 오브젝트로 하려면 ,dvPower 멤버를 제로로 설정해,dcvSpecular 의 색을 흑으로 설정한다. 생각 대로의 리얼한 표시가 되도록(듯이), 다양한 반사 레벨을 시험해 본다. 다음의 그림은, 2 개(살)의 같은 모델을 나타낸다. 좌측의 모델에서는 스펙큐러 반사 강도를 10 으로 설정해, 우측의 모델에서는 스펙큐러 반사를 설정하고 있지 않다.

[Visual Basic]

머트리얼 프로퍼티는, 머트리얼의 디퓨즈 반사, 앰비언트 반사, 에미션(emission), 및 스펙큐러 하이라이트 특성을 상세하게 지정한다. Direct3D 는,D3DMATERIAL7 형에 모든 머트리얼 프로퍼티를 보관 유지한다. 머트리얼 프로퍼티는, 그 머트리얼을 사용하는 다각형을 라스터화할 때 Direct3D 가 사용하는 색에 영향을 준다. 스펙큐러 속성을 제외해, 각 프로퍼티는, 머트리얼이 소정의 종류의 라이트의 적, 초록, 및 파랑 성분을 어느 정도 반사하는지를 나타내는 RGBA 색과 알파 블렌딩 계수 (RGBA 색의 알파 성분)로서 지정한다. 머트리얼의 스펙큐러 속성은, 색 및 강도로 지정한다. 상세한 것에 대하여는, 「라이팅과 머트리얼의 컬러값」을 참조할것.

디퓨즈 반사와 앰비언트 반사

D3DMATERIAL7 형의 diffuse 및 ambient 멤버는, 장면내에서 머트리얼이 앰비언트 라이트와 디퓨즈 라이트를 어떻게 반사하는지를 지정한다. 대부분의 장면에서는, 앰비언트 라이트보다 디퓨즈 라이트가 훨씬 많이 사용되기 (위해)때문에, 색의 결정에 대해 디퓨즈 반사가 가장 크게 영향을 준다. 게다가 디퓨즈 라이트는 방향을 가지고 있기 (위해)때문에, 그 입사각은 반사의 전체적인 강도에 영향을 준다. 디퓨즈 반사는, 라이트가 버텍스 법선과 평행에 버텍스에 해당될 때가 가장 강하다. 입사각이 커지는 것에 따라, 디퓨즈 반사의 이펙트는 감소한다. 다음에 나타내도록(듯이), 반사광의 양은 입사빛과 버텍스 법선이 이루는 각도의 코사인이다.

앰비언트 라이트와 같이, 앰비언트 반사는 방향을 가지지 않는다. 앰비언트 반사는, 렌더링 한 오브젝트의 외관의 색에의 영향은 적지만, 전체의 색에 영향을 주어, 머트리얼로부터 반사하는 디퓨즈 라이트가 전혀 없는지, 그저 적을 때 가장 눈에 띈다. 머트리얼의 앰비언트 반사는, D3DRENDERSTATE_AMBIENT 플래그를 지정해 Direct3DDevice7.SetRenderState 메소드를 호출하는 것으로 장면으로 설정한 앰비언트 라이트의 영향을 받는다.

디퓨즈 반사 및 앰비언트 반사는 ,함께 작용해 오브젝트로 지각되는 색을 결정한다. 이것들은 보통은 같은 값이다. 예를 들어, 청색의 수정 오브젝트를 렌더링 하려면 , 디퓨즈 라이트와 앰비언트 라이트의 파랑 성분만 반사하는 머트리얼을 생성 한다. 이 수정을 백색광으로 비추어진 방에 두면(자) 청색으로 보인다. 그러나, 적색빛 밖에 없는 방에서는, 같은 수정에서도 검게 보인다. 이것은, 수정의 머트리얼이 적색빛을 반사하지 않기 때문이다.

에미션(emission)

머트리얼을 사용해, 렌더링 한 오브젝트 자체가 미츠를 출발하고 있도록(듯이) 보이게 할 수가 있다. D3DMATERIAL7 형의 emissive 멤버를 사용해, 에미션(emission)빛의 색과 투명도를 지정한다. 에미션(emission)는 오브젝트의 색에 영향을 준다. 예를 들어, 어두운 머트리얼을 밝게 해, 에미션(emission)색의 일부가 될 수가 있다.

머트리얼의 에미션(emission) 속성을 사용해, 오브젝트가 미츠를 출발하고 있도록(듯이) 보이게 할 수가 있다. 이 방법에서는, 장면에 라이트를 추가할 때의 오버헤드가 발생하지 않는다. 청색의 수정의 예로, 장면내외의 오브젝트에는 라이트를 비추지 않고 , 수정만이 빛나고 있도록(듯이) 보이게 하는 경우는, 에미션(emission) 속성을 사용 하면이야 있고. 에미션(emission) 속성을 가지는 머트리얼이 발하는 빛은, 장면내외의 오브젝트로 반사할 수 있는 빛은 아니기 때문에 주의 해야 한다. 이 이펙트를 얻으려면 , 장면내에 추가의 라이트를 배치할 필요가 있다.

스펙큐러 반사

스펙큐러 반사는 오브젝트상에 하이라이트를 생성 해, 오브젝트가 빛나고 있도록(듯이) 보이게 한다. D3DMATERIAL7 형에는, 스펙큐러 하이라이트색과 머트리얼의 전체적인 빛남을 지정하는 2 개의 멤버가 포함된다. specular 멤버를 희망의 RGBA 색 (가장 일반적인 색은 백색 또는 밝은 회색이다)으로 설정해, 스펙큐러 하이라이트의 색을 결정한다. power 멤버로 설정하는 값은, 스펙큐러 이펙트의 샤프함을 제어한다.

스펙큐러 하이라이트를 사용 하면, 훌륭한 이펙트를 얻을 수 있다. 다시 청색의 수정을 예로서 생각한다. power 의 값이 큰 만큼 선명한 스펙큐러 하이라이트가 되어, 수정의 빛남이 늘어난다. 이 값이 작을 정도 이펙트가 미치는 영역은 확대하지만, 반사가 둔해져 수정이 서리로 덮인 것처럼 보인다. 전혀 광택이 없는 오브젝트로 하려면 ,power 멤버를 제로로 설정해,specular 의 색을 흑으로 설정한다. 생각 대로의 리얼한 표시가 되도록(듯이), 다양한 반사 레벨을 시험해 본다. 다음의 그림은, 2 개(살)의 같은 모델을 나타낸다. 좌측의 모델에서는 스펙큐러 반사 강도를 10 으로 설정해, 우측의 모델에서는 스펙큐러 반사를 설정하고 있지 않다.


머트리얼의 사용

이 섹션에서는, Direct3D 어플리케이션에서의 머트리얼의 사용에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • 머트리얼 프로퍼티의 설정
  • 머트리얼 프로퍼티의 취득


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

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

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

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

  • 라이트의 색의 종류와 소스
  • 거리의 증가에 의한 라이트의 감쇠
  • 반사율 모델
  • spotlight 폴 오프 모델
  • 포그(안개:fog) 이펙트


라이트의 색의 종류와 소스

Direct3D 의 광원은, 서로 독립해 라이팅 계산의 계수로서 일하는 각각의 라이팅 컴퍼넌트로서 디퓨즈색, 앰비언트색, 및 스펙큐러색을 발한다 (이 라이팅 모델은, DirectX 7.0 보다 전의 버젼으로 사용한 것과는 다르다. 이전에는, 모든 라이팅 계산에 단일의 라이팅색이 사용되었다). 같이 시스템이 렌더링 하는 버텍스는, 그 버텍스 포맷에 의해 정의된 개별의 디퓨즈색, 앰비언트색, 스펙큐러색, 및 에미션(emission)색을 사용한다.

[C++]

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

[Visual Basic]

Visual Basic 의 경우, 버텍스색은,D3DRENDERSTATE_COLORVERTEX 렌더링 스테이트를 TRUE 로 설정했을 때에 마셔, 시스템에 의해 사용된다. 버텍스의 색소스는 선택 가능하다. 즉, 실행시에 라이팅식의 버텍스 이로베 분의 소스를 선택하도록(듯이) 설정할 수 있다. D3DRENDERSTATE_AMBIENTMATERIALSOURCE ,D3DRENDERSTATE_DIFFUSEMATERIALSOURCE , 및 D3DRENDERSTATE_SPECULARMATERIALSOURCE 렌더링 스테이트는, 라이팅 계산에 대해 시스템이 드로잉(Drawing) 하는 색의 색소스를 제어한다. 이러한 각 렌더링 스테이트는,CONST_D3DMATERIALCOLORSOURCE 열거의 멤버로 설정할 수 있다. 이것은, 색소스로서 현재의 머트리얼을 사용하는지, 또는 버텍스의 색을 사용하는지를 지정하는 값을 정의한다.


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

[C++]

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

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

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

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

DirectX 6. x 의 경우, Direct3D 의 감쇠 공식에서는, 보통, 광원을 1.0, 라이트의 최대 범위를 0.0 으로 하는 범위에서 감쇠값이 계산되었다. 그런데 , DirectX 7. x 에서는, 라이트의 최대 범위에 있어서의 감쇠는 0.0 은 아니다. 라이트의 범위내에서 라이트가 돌연 나타나는 것을 방지하기 위해서, 어플리케이션에서는 라이트의 범위를 늘릴 수가 있다. 또, 어플리케이션으로, 라이트의 범위에 있어서의 감쇠 계수가 0.0 에 가까워지도록(듯이) 감쇠 정수를 설정할 수 있다. 감쇠값을 곱셈해 라이트의 색의 적, 초록, 및 파랑 성분을 산출해, 라이트의 강도를 빛이 버텍스까지 진행되는 거리의 계수로서 정할 수가 있다.

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

[Visual Basic]

Direct3D 에서는, 라이팅으로 비추어진 버텍스와 광원의 사이의 거리를, 라이팅의 위치 좌표와 버텍스의 사이의 벡터의 크기에 의해 결정한다. 이것을 다음의 공식에서 나타낸다.

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

이 감쇠 공식에서는,A 는 계산한 전감쇠,D 는 광원으로부터 버텍스까지의 거리이다. attenuation0,attenuation1, 및 attenuation2 의 값은, 라이트 오브젝트의 D3DLIGHT7 형의 멤버에 의해 지정되는, 라이팅의 감쇠 정수이다. 대응하는 멤버는 각각,attenuation0,attenuation1, 및 attenuation2 이다.

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

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

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


반사율 모델

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

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

이 섹션에서는, 시스템에 의한 반사율의 계산방법에 대해 설명한다. 다음의 주제는, 계산하는 반사율의 종류에 대응하고 있다.

  • 디퓨즈 반사 모델
  • 스펙큐러 반사 모델


spotlight 폴 오프 모델

[C++]

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

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

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

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

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

dvFalloff 값이 변화해도 실제의 라이팅에게 주는 영향은 적어,dvFalloff 값이 1.0 이외 때에 형성되는 폴 오프 곡선으로 약간의 퍼포먼스 저하가 생길 뿐이다. 이러한 이유로부터, 대부분의 경우, 이 값은 1.0 으로 설정한다.

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

[Visual Basic]

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

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

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

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

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

falloff 값이 변화해도 실제의 라이팅에게 주는 영향은 적어,falloff 값이 1.0 이외 때에 형성되는 폴 오프 곡선으로 약간의 퍼포먼스 저하가 생길 뿐이다. 이러한 이유로부터, 대부분의 경우, 이 값은 1.0 으로 설정한다.

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


포그(안개:fog) 이펙트

Direct3D 의 트랜스 폼 & 라이팅 엔진에서는, 라이팅중에 포그(안개:fog) 이펙트를 생성 할 수 있다. 이러한 포그(안개:fog)는, 포그(안개:fog) 정보가, 라스터화 되는 버텍스의 알파 성분에 배치되는 것으로부터, 보통은 "버텍스 포그(안개:fog)" 로 불린다. 상세한 것에 대하여는, 「포그(안개:fog)」 및 「버텍스 포그(안개:fog)」를 참조할것.


버텍스 포맷

이 섹션에서는, Direct3D 로 버텍스를 지정하기 위해서 이해해 둘 필요가 있는 개념에 대해 설명해, 버텍스를 선언하기 위해서 어플리케이션으로 사용할 수 있는 각종 포맷의 정보에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • 버텍스 포맷에 대해
  • 트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스
  • 트랜스폼 되지 않은 라이팅 끝난 버텍스
  • 트랜스 폼이 끝난 라이팅 끝난 버텍스
  • 보폭 버텍스 포맷
[C++]

주 : Direct 6.0 보다 전은, Direct3D 지오메트리 파이프라인의 어느 부분이 사용되고 있을까에 의해, 어플리케이션에서는 3 개의 버텍스 타입 D3DVERTEX ,D3DLVERTEX , 및 D3DTLVERTEX 의 어느쪽이든을 사용할 필요가 있었다. DirectX 6.0 이후, 보다 유연한 버텍스 포맷이 도입되어 이전보다 많은 방법으로 버텍스를 선언할 수 있게 되어 있지만, 미리 정의된 구조체를 사용해, 「트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스」, 「트랜스폼 되지 않은 라이팅 끝난 버텍스」, 및 「트랜스 폼이 끝난 라이팅 끝난 버텍스」를 기술할 수도 있다. 상세한 것에 대하여는, 이 섹션의 각 버텍스 타입의 주제를 참조할것.

[C++, Visual Basic]


버텍스 포맷에 대해

Direct3D 직접 모드의 어플리케이션에서는, 복수의 방법으로 모델의 버텍스를 정의할 수 있다. 유연한 버텍스 정의 ("유연한 버텍스 포맷" 이라고도 부른다)가 지원 되고 있는 것으로부터, 필요한 버텍스 성분만 어플리케이션으로 사용해, 사용하지 않는 버텍스 성분은 삭제할 수 있다. 필요한 버텍스 성분만 사용할 수 있으므로, 어플리케이션으로 메모리를 절약할 수 있어 모델의 렌더링에 필요한 처리 대역폭을 최소한으로 억제할 수가 있다. 유연한 버텍스 포맷 플래그를 조합해 사용해, 버텍스의 포맷 방법을 지정한다.

[C++]

C++ 어플리케이션에서는,IDirect3DDevice7 인터페이스의 렌더링 메소드에 의해, 이러한 플래그의 편성을 받는 메소드를 사용할 수 있어 그 편성을 사용해 프리미티브의 렌더링 방법을 결정한다. 기본적으로는, 이러한 플래그는, 어플리케이션으로 어느 버텍스 성분 (위치 좌표, 버텍스 블렌딩 웨이트 (중량감), 법선, 색, 및 텍스쳐 좌표의 수와 포맷)를 사용할까를 시스템에 알려 또, Direct3D 로 렌더링 파이프라인의 어느 부분을 버텍스 성분에 적용할까를 간접적으로 알린다. 게다가 특정의 버텍스 포맷 플래그의 유무에 의해, 메모리에 존재하는 버텍스 성분 필드와 생략 한 버텍스 성분을 시스템에 알린다.

디바이스의 제한을 조사하려면 , D3DFVFCAPS_DONOTSTRIPELEMENTS 및 D3DFVFCAPS_TEXCOORDCOUNTMASK 유연한 버텍스 포맷 플래그에 대해 디바이스를 문의한다. 상세한 것에 대하여는, 「D3DDEVICEDESC7 구조체의 dwFVFCaps 멤버」를 참조할것.

주 : 어플리케이션으로IDirect3DDevice7::DrawPrimitiveStrided 또는 IDirect3DDevice7::DrawIndexedPrimitiveStrided 메소드를 사용하는 경우는, 이것은 조금 다르다. 상세한 것에 대하여는, 「보폭 버텍스 포맷」을 참조할것.

버텍스의 포맷 방법에 관한 시스템 조건 중(안)에서 중요한 것은, 데이터의 표시 순서이다. 다음의 그림은, 메모리내의 모든 버텍스 성분의 순서와 거기에 관계하는 데이터형을 나타낸다.

주 : DirectX 7.0 에서는, 텍스쳐 좌표는 다양한 방법으로 선언할 수 있어 최소 1 요소의 좌표, 최대 3 요소의 텍스쳐 좌표 (2D 투영 텍스쳐 좌표의 경우)를 사용해 텍스쳐를 처리할 수 있다. 상세한 것에 대하여는, 「텍스쳐 좌표 포맷」을 참조할것. 매크로의 D3DFVF_TEXCOORDSIZEn 세트를 사용해, 버텍스 포맷으로 사용하는 텍스쳐 좌표 포맷을 식별하기 위한 비트 패턴을 생성 한다.

실제의 어플리케이션으로, 모든 단일 컴퍼넌트를 사용 하면은 한정되지 않는다. RHW (동차 W 의 역수)와 버텍스 법선 필드는 서로 배타적이다. 또, 대부분의 어플리케이션으로 8 개의 텍스쳐 좌표 세트를 모두 사용 하면도 한정되지 않는다. 그러나, 그런데도 유연성은 있다. 어느 플래그를 다른 플래그와 병용 하는 경우에는, 몇개의 제한이 있다. 이러한 제한은 거의 상식으로 판단할 수 있다. 예를 들어, D3DFVF_XYZ 플래그와 D3DFVF_XYZRHW 플래그는 병용 할 수 없다. 이 경우, 트랜스폼 되지 않은의 버텍스와 트랜스 폼 된 버텍스의 양쪽 모두를 사용해, 1 개의 버텍스의 위치 좌표를 정의하게 되기 때문이다. 상세한 것에 대하여는 「유연한 버텍스 포맷 플래그」의 각 플래그의 설명을 참조할것.

[Visual Basic]

Visual Basic 의 Direct3DDevice7 클래스에는, 이러한 플래그를 편성을 받는 메소드가 있어, 이 편성을 사용해 프리미티브의 렌더링 방법을 결정한다. 기본적으로는, 이러한 플래그는, 어플리케이션으로 어느 버텍스 성분 (위치 좌표, 버텍스 블렌딩 웨이트 (중량감), 법선, 색, 및 텍스쳐 좌표의 수와 포맷)를 사용할까를 시스템에 알려 또, Direct3D 로 렌더링 파이프라인의 어느 부분을 버텍스 성분에 적용할까를 간접적으로 알린다. 게다가 특정의 버텍스 포맷 플래그의 유무에 의해, 메모리에 존재하는 버텍스 성분 필드와 생략 한 버텍스 성분을 시스템에 알린다.

디바이스의 제한을 조사하려면 , D3DFVFCAPS_DONOTSTRIPELEMENTS 및 D3DFVFCAPS_TEXCOORDCOUNTMASK 유연한 버텍스 포맷 플래그에 대해 디바이스를 문의한다. 상세한 것에 대하여는, 「D3DDEVICEDESC7 형의 lFVFCaps 멤버」를 참조할것.

버텍스의 포맷 방법에 관한 시스템 조건 중(안)에서 중요한 것은, 데이터의 표시 순서이다. 다음의 그림은, 메모리내의 모든 버텍스 성분의 순서와 거기에 관계하는 데이터형을 나타낸다.

텍스쳐 좌표는 다양한 포맷으로 선언할 수 있어 최소 1 요소의 좌표, 최대 3 요소의 텍스쳐 좌표 (2D 투영 텍스쳐 좌표의 경우)를 사용해 텍스쳐를 처리할 수 있다. Math.bas 로부터 헬퍼-함수의 D3DFVF_TEXCOORDSIZEn 세트를 사용해, 버텍스 포맷으로 사용하는 텍스쳐 좌표 포맷을 식별하기 위한 비트 패턴을 생성 한다. Math.bas 의 Visual Basic 코드 모듈이, 이 SDK 에 부속되어 있다.

실제의 어플리케이션으로, 모든 단일 컴퍼넌트를 사용 하면은 한정되지 않는다. RHW (동차 W 의 역수)와 버텍스 법선 필드는 서로 배타적이다. 또, 대부분의 어플리케이션으로 8 개의 텍스쳐 좌표 세트를 모두 사용 하면도 한정되지 않는다. 그러나, 그런데도 유연성은 있다. 어느 플래그를 다른 플래그와 병용 하는 경우에는, 몇개의 제한이 있다. 이러한 제한은 거의 상식으로 판단할 수 있다. 예를 들어, D3DFVF_XYZ 플래그와 D3DFVF_XYZRHW 플래그는 병용 할 수 없다. 이 경우, 트랜스폼 되지 않은의 버텍스와 트랜스 폼 끝난 버텍스의 양쪽 모두를 사용해, 1 개의 버텍스의 위치 좌표를 정의하게 되기 때문이다. 상세한 것에 대하여는 「유연한 버텍스 포맷 플래그」의 각 플래그의 설명을 참조할것.


트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스

렌더링 메소드에 건네주는 버텍스 기술에 D3DFVF_XYZ (또는 D3DFVF_XYZBn 플래그의 몇개인가) 및 D3DFVF_NORMAL 플래그가 있는 경우, 「트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스」타입이 지정되고 있다. 「트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스」를 사용 하면, 어플리케이션은 Direct3D 에 그 내부 알고리즘을 사용해 모든 트랜스 폼 & 라이팅 처리를 실행하도록(듯이) 효율적으로 요구할 수 있다 (필요하면, D3DRENDERSTATE_LIGHTING 렌더링 스테이트를 FALSE 로 설정해, 렌더링 하는 프리미티브에 대해서 Direct3D 라이팅 엔진을 무효로 할 수 있다).

이 버텍스 타입은, 어플리케이션으로 독자적인 트랜스 폼 & 라이팅 엔진을 이행 할 필요가 없기 때문에, 대부분의 어플리케이션으로 사용된다. 다만, 시스템에 의해 자동적으로 계산이 실행되기 (위해)때문에, 각 버텍스에 대해서 얼마인가의 정보를 지정해 둘 필요가 있다.

  • 트랜스폼 되지 않은의모델 좌표로 버텍스를 지정할 필요가 있다 (모델 좌표 버텍스는, 월드에 대해서는 아니고, 모델의 로컬 원점에 대한 상대 위치 좌표에 배치된다). 다음에, 시스템은, 월드 트랜스 폼, 뷰 트랜스 폼, 및 투영 트랜스 폼을 모델 좌표에 적용해 장면내에 버텍스를 배치해, 버텍스의 화면상에서의 최종 위치 좌표를 결정한다.
  • 보다 리얼한 라이팅 이펙트를 내기 위해서(때문에), 버텍스 법선을 포함한다 (버텍스 법선을 포함하지 않은 버텍스를 라이팅으로 비추는 경우, 그 버텍스는 0 의 내적을 사용한다. 즉, 그 버텍스는 입사빛을 받지 않는 것으로서 처리된다). 시스템은, 현재 머트리얼에 가세해, 버텍스 법선을 사용해 라이팅 계산을 실행한다. 상세한 것에 대하여는, 「면법선 벡터와 버텍스 법선 벡터」, 「라이팅과 머트리얼」, 및 「Direct3D 의 라이팅에 있어서의 수학적 계산」을 참조할것.
[C++]

이러한 조건 이외에서는, 그 외의 버텍스 성분을 유연하게 사용 (또는 무시)할 수 있다. 예를 들어, 디퓨즈 또는 스펙큐러색을 트랜스폼 되지 않은의 버텍스에 포함할 수가 있다 (이것은 DirectX 6.0 이전으로는 할 수 없었다). 각 버텍스에 각각의 색을 포함하면(자), 머트리얼 컬러만 사용한 라이팅 계산을 실행하는 것보다도, 훨씬 섬세하고 유연한 쉐이딩 이펙트를 얻을 수 있다. 다만, 이 경우,D3DRENDERSTATE_COLORVERTEX 렌더링 스테이트를 사용해 각각의 버텍스색을 유효하게 할 필요가 있다. 또, 트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스에는, 최대 8 개(살)까지 텍스쳐 좌표 세트를 포함할 수가 있다.

어플리케이션에서는, 버텍스에 대해서 종래의 D3DVERTEX 구조체도 사용할 수 있다. 실제, 이 버텍스 포맷을 식별하는 쇼트 컷 매크로가, d3dtypes.h 헤더 파일에 정의되고 있다.

#define D3DFVF_VERTEX ( D3DFVF_XYZ | D3DFVF_NORMAL | D3DFVF_TEX1 )

D3DVERTEX 구조체가 어플리케이션의 요건에 맞지 않을 때는, 그 요건을 채우도록(듯이) 독자적으로 정의할 수 있다. 다만, 어느 버텍스 성분이 어플리케이션으로 필요한가에 주의해, 반드시 올바르고 순서 붙인 구조체를 선언해, 필요한 순서로 버텍스 성분이 표시되도록(듯이) 해야 한다. 다음의 코드는, 위치 좌표, 버텍스 법선, 디퓨즈색, 및 2 개의 텍스쳐 좌표 세트를 포함한 유효한 버텍스 포맷 구조체를 선언한다.

//
// 이 버텍스의 버텍스 포맷 기술은,
// (D3DFVF_XY | D3DFVF_NORMAL |// D3DFVF_DIFFUSE | D3DFVF_TEX2)
// (이)가 된다.
//
typedef struct _UNLITVERTEX {
float x, y, z;        // 위치 좌표

float nx, ny, nz;     // 법선

DWORD dwDiffuseRGBA;  // 디퓨즈색

float tu1,    // 텍스쳐 좌표
tv1;

float tu2,
tv2;
} UNLITVERTEX, *LPUNLITVERTEX;

이 구조체의 버텍스 기술은, 유연한 버텍스 포맷 플래그 D3DFVF_XYZ, D3DFVF_NORMAL, D3DFVF_DIFFUSE, 및 D3DFVF_TEX2 의 편성이 된다. IDirect3DDevice7::DrawPrimitive 등의 렌더링 메소드는, 버텍스 배열의 주소를 void 형의 포인터로서 받으므로, 렌더링 메소드를 호출하면나무는, 버텍스 배열 포인터를 LPVOID 데이터형에 캐스트 해야 한다.

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

[Visual Basic]

이러한 조건 이외에서는, 그 외의 버텍스 성분을 유연하게 사용 (또는 무시)할 수 있다. 예를 들어, 디퓨즈 또는 스펙큐러색을 트랜스폼 되지 않은의 버텍스에 포함할 수가 있다 (이것은 DirectX 6.0 이전으로는 할 수 없었다). 각 버텍스에 각각의 색을 포함하면(자), 머트리얼 컬러만 사용한 라이팅 계산을 실행하는 것보다도, 훨씬 섬세하고 유연한 쉐이딩 이펙트를 얻을 수 있다. 다만, 이 경우,D3DRENDERSTATE_COLORVERTEX 렌더링 스테이트를 사용해 각각의 버텍스색을 유효하게 할 필요가 있다. 또, 트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스에는, 최대 8 개(살)까지 텍스쳐 좌표 세트를 포함할 수가 있다. Visual Basic 어플리케이션에서는, 버텍스에 D3DVERTEX 형을 사용할 수 있다.

D3DVERTEX 형이 어플리케이션의 요건에 맞지 않을 때는, 그 요건을 채우도록(듯이) 독자적으로 정의를 할 수 있다. 다만, 어느 버텍스 성분이 어플리케이션으로 필요한가에 주의해, 반드시 올바르고 순서 붙인 구조체를 선언해, 필요한 순서로 버텍스 성분이 표시되도록(듯이) 해야 한다. 다음의 코드는, 위치 좌표, 버텍스 법선, 디퓨즈색, 및 2 개의 텍스쳐 좌표 세트를 포함한 유효한 버텍스 포맷 구조체를 선언한다.

'
// 이 버텍스의 버텍스 포맷 기술은,
// (D3DFVF_XYZ Or D3DFVF_NORMAL Or D3dFVF_DIFFUSE Or D3DFVF_TEX2)(D3DFVF_XYZ Or D3DFVF_NORMAL Or
// (이)가 된다.
'
Type UNLITVERTEX
x As Single '위치 좌표
y As Single
z As Single

nx As Single '법선
ny As Single
nz As Single

DiffuseRGBA As Long  '디퓨즈색

tu1 As Single '텍스쳐 좌표
tv1 As Single

tu2 As Single '텍스쳐 좌표
tv2 As Single
End Type

이 구조체의 버텍스 기술은, 유연한 버텍스 포맷 플래그 D3DFVF_XYZ, D3DFVF_NORMAL, D3DFVF_DIFFUSE, 및 D3DFVF_TEX2 의 편성이 된다. Direct3DDevice7.DrawPrimitive 등의 렌더링 메소드는, 버텍스 배열의 제 1 요소를 형태 Any 로서 받아, 모든 종류의 버텍스 포맷을 저장 한다.

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


트랜스폼 되지 않은 라이팅 끝난 버텍스

Direct3D 렌더링 메소드로 사용하는 버텍스 포맷 기술에 D3DFVF_XYZ 플래그를 포함해 D3DFVF_NORMAL 플래그를 포함하지 않은 경우, 그 버텍스는 「트랜스폼 되지 않은 라이팅 끝난 버텍스」로서 식별된다 (플래그의 의존 및 배타 관계의 상세한 것에 대하여는, 「유연한 버텍스 포맷 플래그」를 참조할것).

「트랜스폼 되지 않은 라이팅 끝난 버텍스」를 사용 하면, 어플리케이션은 Direct3D 에 버텍스에 대한 라이팅 계산을 실행하지 않게 요구하지만, Direct3D 는 이전으로 설정된 월드 행렬, 뷰 행렬, 및 투영 행렬을 사용해 버텍스를 트랜스 폼 한다. 라이팅 계산은 실행되지 않기 때문에, 버텍스 법선은 필요없다. 시스템은, 각 버텍스의 디퓨즈 성분과 스펙큐러 성분을 쉐이딩에 사용한다. 이러한 색은 임의로 지정해도, 독자적인 라이팅 공식을 사용해 계산해도 괜찮다. 디퓨즈 성분 또는 스펙큐러 성분을 포함하지 않는 경우는, 디폴트 컬러가 사용된다. 디퓨즈색의 디폴트값은 0xFFFFFFFF 로, 스펙큐러색의 디폴트값은 0x0 이다.

위치 좌표 물어 창고인가의 색정보를 포함한다고 하는 점을 제외해서는, 그 외의 버텍스 타입과 같이, 라이팅 계산 되지 않은의 버텍스 포맷에 텍스쳐 좌표 세트를 포함하거나 무시할 수가 있다.

[C++]

C++ 어플리케이션에서는, 버텍스에 대해서 종래의 D3DLVERTEX 구조체도 사용할 수 있다. d3dtypes.h 헤더 파일에는,D3DLVERTEX 구조체의 포맷을 기술하기 위해서 사용할 수 있는, 다음의 헬퍼-매크로가 정의되고 있다.

#define D3DFVF_LVERTEX ( D3DFVF_XYZ | D3DFVF_RESERVED1 | D3DFVF_DIFFUSE | \
 D3DFVF_SPECULAR | D3DFVF_TEX1 )

여기서 주의하는 것은, 헬퍼-매크로에는 D3DLVERTEX 구조체를 사용하는 것을 시스템에 지시하는 D3DFVF_RESERVED1 플래그가 포함되어 있어 이 구조체에는 dwReserved 멤버가 포함되어 있는 것이다. D3DLVERTEX 를 사용할때에 이 멤버가 필요한 것은, 버텍스 포맷에는 보통 예약 끝난 필드가 포함되지 않기 때문이다. D3DFVF_RESERVED1 플래그는, 버텍스의 위치 좌표와 디퓨즈색버텍스 성분의 사이에 미사용의 DWORD 가 존재하는 것을 시스템에 알린다.

D3DLVERTEX 구조체에 어플리케이션으로 필요한 모든 필드가 포함되지 않은 경우는, 다른 구조체를 정의할 수가 있다. 새로운 구조체를 선언 하면나무는, 반드시 버텍스 성분이 올바른 순서가 되도록(듯이) 한다. 다음의 코드는, 디퓨즈 버텍스색, 스펙큐러 버텍스색, 및 3 개의 텍스쳐 좌표 세트를 가지는, 트랜스폼 되지 않은으로 라이팅 끝난 유효한 버텍스를 선언한다.

//
// 이 버텍스의 버텍스 포맷 기술은,
// (D3DFVF_XYZ | D3DFVF_DIFFUSE |// D3DFVF_SPECULAR | D3DFVF_TEX3)
// (이)가 된다.
//
typedef struct _LITVERTEX {
float x, y, z;        // 위치 좌표

DWORD dwDiffuseRGBA;  // 디퓨즈색

DWORD dwSpecularRGBA; // 스펙큐러색

float tu1,    // 텍스쳐 좌표
tv1;

float tu2,
tv2;

float tu3,
tv3;
} LITVERTEX, *LPLITVERTEX;

이 구조체의 버텍스 기술은, 유연한 버텍스 포맷 플래그 D3DFVF_XYZ, D3DFVF_DIFFUSE, D3DFVF_SPECULAR, 및 D3DFVF_TEX3 의 편성이 된다. IDirect3DDevice7::DrawPrimitive 등의 렌더링 메소드는, 버텍스 배열의 주소를 void 형의 포인터로서 받으므로, 렌더링 메소드를 호출하면나무는, 버텍스 배열 포인터를 LPVOID 데이터형에 캐스트 해야 한다.

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

[Visual Basic]

Visual Basic 로 기술된 어플리케이션에서는, 독자적인 버텍스 포맷을 정의해도, 라이팅이 있는 버텍스에 D3DLVERTEX 형을 사용해도 괜찮다. D3DLVERTEX 형에 어플리케이션으로 필요한 모든 필드가 포함되지 않은 경우는, 다른 형태를 정의할 수가 있다. 새로운 구조체를 선언 하면나무는, 반드시 버텍스 성분이 올바른 순서가 되도록(듯이) 한다. 다음의 코드는, 디퓨즈 버텍스색, 스펙큐러 버텍스색, 및 3 개의 텍스쳐 좌표 세트를 가지는, 트랜스폼 되지 않은으로 라이팅 끝난 유효한 버텍스를 선언한다.

'
// 이 버텍스의 버텍스 포맷 기술은,
// (D3DFVF_XYZ Or D3DFVF_DIFFUSE Or D3DFVF_SPECULAR Or D3DFVF_TEX3)(D3DFVF_XYZ Or D3DFVF_DIFFUSE Or
// (이)가 된다.
'
Type LITVERTEX
x As Single '위치 좌표
y As Single
z As Single

DiffuseRGBA As Long '디퓨즈색

SpecularRGBA As Long '스펙큐러색

tu1 As Single '텍스쳐 좌표
tv1 As Single

tu2 As Single
tv2 As Single

tu3 As Single
tv3 As Single
End Type

이 구조체에서의 버텍스 기술은, 유연한 버텍스 포맷 플래그 D3DFVF_XYZ, D3DFVF_DIFFUSE, D3DFVF_SPECULAR, 및 D3DFVF_TEX3 의 편성이 된다. Direct3DDevice7.DrawPrimitive 등의 렌더링 메소드는, 버텍스 배열의 제 1 요소를 형태 Any 로서 받아, 모든 종류의 버텍스 포맷을 저장 한다.

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


트랜스 폼이 끝난 라이팅 끝난 버텍스

버텍스 포맷 기술에 D3DFVF_XYZRHW 플래그를 포함했을 경우, 어플리케이션으로 「트랜스 폼이 끝난 라이팅 끝난 버텍스」를 사용하는 것이 시스템에 통지된다. 이것은, 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 의 조건을 제외하면, 이 버텍스 포맷은, 「트랜스폼 되지 않은 라이팅 끝난 버텍스」와 같다. 지금까지의 설명을 이하에 정리한다.

  • 이 포맷의 경우, 라이팅 계산은 실행되지 않기 때문에, 버텍스 법선은 필요없다.
  • 디퓨즈색 또는 스펙큐러색을 지정할 수 있다. 이것을 지정하지 않는 경우는, 양쪽 모두의 컴퍼넌트에 0xFFFFFFFF 가 사용된다.
  • 텍스쳐 좌표 세트는, 최대 8 개(살)까지 사용할 수 있다. 또, 사용 하지 않아도 되다.
[C++]

C++ 로 기술된 어플리케이션에서는, 「트랜스 폼이 끝난 라이팅 끝난 버텍스」에 대해서 종래의 D3DTLVERTEX 구조체도 사용할 수 있다. d3dtypes.h 헤더 파일에는,D3DTLVERTEX 구조체로 선언하는 버텍스 포맷을 기술하기 위해서 사용할 수 있는, 다음의 헬퍼-매크로가 정의되고 있다.

#define D3DFVF_TLVERTEX ( D3DFVF_XYZRHW | D3DFVF_DIFFUSE | D3DFVF_SPECULAR | \
  D3DFVF_TEX1 )

필요한 필드가 D3DTLVERTEX 구조체에 포함되지 않은 것이 있다. 이러한 경우, 필요한 필드를 포함한 다른 구조체를 정의할 수 있지만, 반드시 버텍스 성분을 올바른 순서로 배치하는 것. 다음의 코드는, 디퓨즈 버텍스색, 스펙큐러 버텍스색, 및 텍스쳐 좌표 세트를 1 개만 가지는, 트랜스 폼이 끝난 상태로 라이팅이 있는 유효한 버텍스를 선언한다.

//
// 이 버텍스의 버텍스 포맷 기술은,
// (D3DFVF_XYZRHW | D3DFVF_DIFFUSE |// D3DFVF_SPECULAR | D3DFVF_TEX1)
// (이)가 된다.
//
typedef struct _TRANSLITVERTEX {
    float x, y;   // 화면 좌표

    float z;      // Z 버퍼 깊이

    float rhw;    // 동차 W 의 역수

    DWORD dwDiffuseRGBA;  // 디퓨즈색

    DWORD dwSpecularRGBA; // 스펙큐러색

    float tu1,    // 텍스쳐 좌표
  tv1;
} TRANSLITVERTEX, *LPTRANSLITVERTEX;

이 구조체의 버텍스 기술은, 유연한 버텍스 포맷 플래그 D3DFVF_XYZRHW, D3DFVF_DIFFUSE, D3DFVF_SPECULAR, 및 D3DFVF_TEX1 의 편성이 된다. IDirect3DDevice7::DrawPrimitive 등의 렌더링 메소드는, 버텍스 배열의 주소를 void 형의 포인터로서 받으므로, 렌더링 메소드를 호출하면나무는, 버텍스 배열 포인터를 LPVOID 데이터형에 캐스트 해야 한다.

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

[Visual Basic]

Visual Basic 어플리케이션에서는, 「트랜스 폼이 끝난 라이팅 끝난 버텍스」에 대해서 종래의 D3DTLVERTEX 형도 사용할 수 있다. 필요한 필드가 D3DTLVERTEX 형에 포함되지 않은 것이 있다. 이러한 경우, 필요한 필드를 포함한 다른 구조체를 정의할 수 있지만, 반드시 버텍스 성분을 올바른 순서로 배치하는 것. 다음의 코드는, 디퓨즈 버텍스색, 스펙큐러 버텍스색, 및 텍스쳐 좌표 세트를 1 개만 가지는, 트랜스 폼이 끝난 상태로 라이팅이 있는 유효한 버텍스를 선언한다.

'
'이 버텍스의 버텍스 포맷 기술은,
' (D3DFVF_XYZRHW Or D3DFVF_DIFFUSE Or (D3DFVF_XYZRHW Or D3DFVF_DIFFUSE Or
' D3DFVF_SPECULAR Or D3DFVF_TEX1)이다.
'
Type TRANSLITVERTEX
x As Single '화면 좌표
y As Single

z As Single ' z 버퍼 깊이

rhw As Single '동차 W 의 역수

DiffuseRGBA As Long '디퓨즈색

dwSpecularRGBA As Long '스펙큐러색

tu1 As Single '텍스쳐 좌표
tv1 As Single
End Type

이 구조체의 버텍스 기술은, 유연한 버텍스 포맷 플래그 D3DFVF_XYZRHW, D3DFVF_DIFFUSE, D3DFVF_SPECULAR, 및 D3DFVF_TEX1 의 편성이 된다. Direct3DDevice7.DrawPrimitive 등의 렌더링 메소드는, 버텍스 배열의 제 1 요소를 형태 Any 로서 받아, 모든 종류의 버텍스 포맷을 저장 한다.

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


보폭 버텍스 포맷

[Visual Basic]

주 : 여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에서는, 보폭 버텍스는 지원 하고 있지 않다.

[C++]

보폭 버텍스 포맷에는,IDirect3DDevice7::DrawPrimitiveStrided ,IDirect3DDevice7::DrawIndexedPrimitiveStrided , 및 IDirect3DVertexBuffer7::ProcessVerticesStrided 메소드로 사용하는, 트랜스폼 되지 않은의 버텍스, 「트랜스폼 되지 않은 라이팅 끝난 버텍스」, 또는 「트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스」를 나타내는 필드가 포함된다. 보폭 버텍스 포맷은, 트랜스 폼 된 버텍스에는 사용할 수 없다. "보통" 의 버텍스는, 필요한 버텍스 성분을 물리적으로 모두 포함한 구조체이다. 이것과는 달라,"보폭" 버텍스는, 버텍스 성분에의 포인터를 포함한 구조체로, 버텍스 성분 자체를 포함하는 것은 아니다.

이전 접적인 액세스는,DrawPrimitiveStrided,DrawIndexedPrimitiveStrided, 및 ProcessVerticesStrided 메소드가 받는 D3DDRAWPRIMITIVESTRIDEDDATA 구조체에 의해 행해진다. 보폭 버텍스는, 비보폭 버텍스와 같게 유연한 버텍스 포맷 플래그를 조합해 기술한다. 그러나, 비보폭 버텍스와는 달라, 이것들 사용하는 플래그는, 지정의 필드가 메모리내에 존재하는 것을 나타내는 것이 아니라 (D3DDRAWPRIMITIVESTRIDEDDATA 에는 이러한 플래그가 모두 포함된다), 어느 구조체 멤버를 어플리케이션으로 사용하는지를 나타낸다. 이러한 플래그에 대한 제약은, 비보폭 버텍스의 경우와 같다. 상세한 것에 대하여는, 「유연한 버텍스 포맷 플래그」를 참조할것.

D3DDRAWPRIMITIVESTRIDEDDATA 구조체에는 12 개의 D3DDP_PTRSTRIDE 구조체가 포함되어 각각의 구조체는 버텍스의 위치 좌표, 법선, 디퓨즈색, 스펙큐러색, 및 텍스쳐 좌표 세트를 나타낸다. 각 D3DDP_PTRSTRIDE 구조체에는, 데이터 배열에의 포인터와 그 배열의 보폭이 포함된다. 이것들 12 개의 구조체에 의한 간접적인 액세스에 의해, 어플리케이션은 버텍스 성분을 어떻게에서도 배치할 수 있다. 예를 들어, 다음의 그림에 나타내도록(듯이), 버텍스 성분 마다 다른 배열을 사용할 수 있다.

대응하는 D3DDP_PTRSTRIDE 구조체의 lpvData 멤버는, 버텍스 성분의 배열이 있는 버퍼의 주소를 포함한다. 각 배열의 각 요소는 1 개의 버텍스에 대한 1 개의 컴퍼넌트를 나타내, 이 컴퍼넌트는 몇개의 부동 소수점값 (위치 좌표, 법선, 및 텍스쳐 좌표) 또는 1 개의 RGBA 값 (디퓨즈색과 스펙큐러색)으로부터 완성된다. 각 배열에는, 렌더링 하는 버텍스 1 개(살)에 대해 1 개의 엔트리가 있다. D3DDP_PTRSTRIDE 구조체의 dwStride 멤버에는, 배열내의 엔트리간의 메모리 보폭을 바이트수로 설정해야 한다. 다음의 표는, 컴퍼넌트와 거기에 대응하는 보폭을 나타낸다.

컴퍼넌트 | 보폭
트랜스폼 되지 않은의 위치 좌표 | 3 ~ 6 개의 부동 소수점값 (x, y, z, 라고 0 ~ 3 개의 블렌드 웨이트)
버텍스 법선 | 3 개의 부동 소수점값 (nx, ny, nz)
디퓨즈색 | 1 개의 DWORD (RGBA)
스펙큐러색 | 1 개의 DWORD (RGBA)
텍스쳐 좌표 | 1, 2, 3, 또는 4 개의 부동 소수점값 ( 제 1, 제 2, 제 3, 또는 제 4 텍스쳐 좌표)

주 : DirectX 7.0 에서는, 텍스쳐 좌표는 복수의 포맷으로 선언할 수 있어 최소 1 개의 좌표, 최대 3 개의 텍스쳐 좌표 (2D 투영 텍스쳐 좌표의 경우)를 사용해 텍스쳐를 처리할 수 있다. 상세한 것에 대하여는, 「텍스쳐 좌표 포맷」을 참조할것. 매크로의 D3DFVF_TEXCOORDSIZEn 세트를 사용해, 버텍스 포맷으로 사용하는 텍스쳐 좌표 포맷을 식별하기 위한 비트 패턴을 생성 한다.

경우에 따라서는, 인타리브 배열에 버텍스 성분의 일부 또는 모든 것을 포함하는 일도 있다. 보폭 버텍스 포맷에서는, 이것을 간단하게 실시할 수가 있다. 예를 들어, 어플리케이션으로 버텍스 위치 좌표와 법선 컴퍼넌트를 인타리브 했을 경우, 메모리 레이아웃과 D3DDP_PTRSTRIDE 구조체의 대응하는 설정은, 다음과 같이 나타낼 수가 있다.

이 경우,D3DDP_PTRSTRIDE 구조체의 lpvData 멤버는 동일 버퍼내의 2 개의 위치 좌표를 포인트 해, 보폭은 인타리브 된 컴퍼넌트의 폭을 결합한 값으로 설정된다. 물론, 이것은 특정의 인타리브스킴으로 한정되는 것은 아니다. 데이터 포인터와 그 보폭을 올바르게 설정해 있으면, 어떠한 인타리브스킴에서도 가능하다.


텍스쳐

텍스쳐는, 컴퓨터로 리얼한 3D 화면을 생성하기 위한 강력한 툴이다. Direct3D 에서는, 다채로운 텍스쳐 기능을 지원 하고 있어, 고도의 텍스쳐 기술을 간단하게 이용할 수 있다. 이 섹션에서는, Direct3D 에서의 텍스쳐의 용도와 그 사용 방법에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • 기본적인 텍스쳐 처리의 개념
  • 텍스쳐 좌표
  • 텍스쳐 표면 오브젝트
  • 텍스쳐 필터링
  • 텍스쳐 랩핑
  • 텍스쳐 블렌딩
  • 텍스쳐 압축
  • 자동 텍스쳐 관리
  • 텍스쳐 처리에 있어서의 하드웨어 제약

텍스쳐에 대한 지식이 있어, 그 사용 방법에 대해서도 이해하고 있는 경우는, 「기본적인 텍스쳐 처리의 개념」은 생략 해도 괜찮다. 다만, Direct3D 에서는 현재로서는, 텍스쳐 인터페이스를 사용해, 많은 파워풀한 텍스쳐 기능을 이용 하면 말하는 점을 기억해 두는 것. 따라서, 「텍스쳐 표면 오브젝트」에 대충 훑어봐 두면(자) 좋다.


기본적인 텍스쳐 처리의 개념

이 섹션에서는, Direct3D 에서의 텍스쳐 처리의 이해에 필요한 가장 기본적인 개념에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • 텍스쳐란
  • 텍스쳐 addressing mode
  • 텍스쳐 인터페이스와 텍스쳐 핸들
  • 팔레트화 텍스쳐


텍스쳐란

지금까지는 컴퓨터로 생성하는 3D 화면은, 당시로서는 일반적으로 고도의 것이었지만, 플라스틱이 빛나 있는 것처럼 보이는 경향이 있었다. 당시의 3D 화면에는, 상처, 금, 지문, 더러움등을 3D 오브젝트로 리얼하게 표현할 방법이 없었다. 근년, 개발자의 사이에서는, 컴퓨터로 보다 리얼한 3D 화면을 생성하기 위한 툴로서 텍스쳐가 넓게 사용되게 되어 있다.

기본적으로는, 텍스쳐와는 단지 픽셀 컬러의 비트 맵이다. 이 의미에서는, 텍스쳐라고 하는 용어는, 컴퓨터 그래픽스 분야에 있어 특정의 정의를 가진다. 텍스쳐라는 말로부터 연상하는 의미는, 보통, 오브젝트의 색의 모양과 오브젝트의 엉성함이나 매끄러움의 양쪽 모두를 말한다. Direct3D 의 텍스쳐에서는, 오브젝트에 "요철" 은 추가하지 않는다. 텍스쳐, 즉 색의 패턴에 의해, 오브젝트에 요철이 있도록(듯이) 보이게 하는 것만으로 있다.

Direct3D 의 텍스쳐는 단순한 비트 맵이기 (위해)때문에, 비트 맵조차 있으면 Direc3D 원시적으로 적용할 수 있다. 예를 들어, 어플리케이션에서는, 나뭇결 모양으로 보이는 오브젝트를 생성 해 조작할 수가 있다. 언덕을 형성하는 3D 프리미티브 세트에, 잔디, 흙, 바위를 적용할 수 있다. 그 결과, 진짜와 같은 언덕의 경사면이 완성된다. 텍스쳐 처리에서는, 또, 도로겨드랑이의 표지, 벼랑의 암층등의 이펙트를 생성 하거나 대리석의 마루를 생성 할 수도 있다.

게다가 Direct3D 는, 텍스쳐 블렌딩 (투명도 있어/없음)이나 라이트 맵핑 등, 보다 고도의 텍스쳐 기법도 지원 하고 있다. 이러한 기법에 대해서는, 「텍스쳐 블렌딩」 및 「텍스쳐에 의한 라이트 맵핑」을 참조할것.

어플리케이션으로 HAL 디바이스, MMX 디바이스, 또는 RGB 디바이스 ( 「Direct3D 디바이스의 종류」를 참조할것)를 생성 하는 경우는,8 비트, 16 비트, 24 비트, 또는 32 비트 텍스쳐를 사용할 수 있다. 흑백 (또는 램프) 디바이스를 사용하는 종래의 어플리케이션에서는, 8 비트 텍스쳐를 사용해야 한다.


텍스쳐 addressing mode

이 섹션에서는, Direct3D 텍스쳐 addressing mode의 용도 및 그 사용 방법에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • 텍스쳐 addressing mode란
  • 랩 텍스쳐 addressing mode에 대해
  • 밀러 텍스쳐 addressing mode에 대해
  • 클램프 텍스쳐 addressing mode에 대해
  • 경계색텍스쳐 addressing mode에 대해
  • 텍스쳐 addressing mode의 설정과 취득
  • 텍스쳐 addressing mode와 텍스쳐 랩핑
  • 텍스쳐 애드레싱에 있어서의 디바이스 제한


텍스쳐 인터페이스와 텍스쳐 핸들

[Visual Basic]

주 : 여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에서는, 텍스쳐 핸들은 사용하지 않는다.

[C++]

텍스쳐 핸들은, 현재는 일반적으로는 사용되어 있지 않다. 텍스쳐 핸들은,IDirect3D 및 IDirect3D2 인터페이스를 이용하는 어플리케이션으로 사용되고 있었다.

IDirect3D7 인터페이스 ( 및 종래의 IDirect3D3 인터페이스)에서는, 텍스쳐 표면에의 인터페이스 포인터에 의해 텍스쳐를 생성 및 사용한다. IDirectDraw7::CreateSurface 메소드를 호출해 텍스쳐 표면을 생성 하면, 텍스쳐 표면 인터페이스 포인트를 취득할 수 있다. Direct3D 에서는, 원시적으로 한 번에 최대 8 개(살)까지 텍스쳐를 블렌딩 할 수 있다. 상세한 것에 대하여는, 「텍스쳐 표면 오브젝트」를 참조할것.


팔레트화 텍스쳐

[C++]

Direct3D 디바이스는, Attach 된 팔레트를 사용하는 텍스쳐 표면으로부터의 텍스쳐 처리를 지원 한다. 이 타입의 텍스쳐를 "팔레트화 텍스쳐" 라고 부른다. 팔레트화 텍스쳐는 DirectDrawSurface 오브젝트이다. 이 오브젝트는, DDSCAPS_TEXTURE 기능에 의해 생성되어 DDPF_PALETTEINDEXEDn 픽셀 포맷 (n 는 1, 2, 4, 또는 8)의 어느쪽이든을 사용한다. 이 기능은, 텍스쳐의 생성에 사용하는 DDSURFACEDESC2 구조체 ( 및, 이 기술에 포함되는 DDPIXELFORMAT 구조체)에 포함되어 있다. 모든 팔레트화 표면과 같이, 색은 아니고 각 픽셀이, Attach 된 DirectDrawPalette 오브젝트내에 보관 유지되는 값의 테이블에의 인덱스가 된다. 팔레트화 표면의 생성 및 사용의 상세한 것에 대하여는, DirectDraw 문서의 「표면」 및 「팔레트」를 참조할것. 텍스쳐 관련 디바이스 기능을 체크하는 경우와 같이,IDirect3DDevice7::EnumTextureFormats 메소드를 호출해, 지원 되고 있는 텍스쳐 픽셀 포맷을 반드시 확인하는 것.

팔레트화 텍스쳐를 준비하려면

  1. 여기서 설명한 것처럼, DirectDraw 와 Direct3D 의 기능을 체크한다.
  2. DDSCAPS_TEXTURE 기능을 포함해, DDPF_PALETTEINDEXEDn 픽셀 포맷의 어느쪽이든을 사용하는 표면을 필요한 크기로 생성 한다.
  3. DirectDrawPalette 오브젝트를 생성 해, 초기화한다. 상세한 것에 대하여는, DirectDraw 문서의 「팔레트」를 참조할것 (알파 전용 팔레트화 텍스쳐를 사용하려면 , 팔레트를 생성 할 경우에 DDPCAPS_ALPHA 기능을 포함한다. 상세한 것에 대하여는,IDirectDraw7::CreatePalette 의 레퍼런스를 참조할것).
  4. 텍스쳐 표면에 대해서 IDirectDrawSurface7::SetPalette 메소드를 호출해, 팔레트를 표면에 Attach 한다.

주 : 팔레트화 텍스쳐 표면을 생성 했지만, 팔레트를 Attach 하지 않았던 경우, 렌더링중에 Direct3D 직접 모드내에서 어플리케이션의 액세스 위반이 발생한다.

팔레트화 텍스쳐로 사용하는 팔레트는, 색데이터만 사용할 필요는 없다. 경우에 따라서는, 디바이스가, 알파 정보를 포함한 텍스쳐 팔레트를 지원 하고 있는 일도 있다. 그 경우,IDirectDraw7::GetCaps 메소드를 호출하면, DirectDraw 는 DDPCAPS_ALPHA 팔레트 능력 플래그를 공개한다. 이 플래그는, 관련하는 DDCAPS 구조체의 dwPalCaps 멤버에 있다. 렌더링 디바이스로 알파 대응 팔레트화 텍스쳐로부터의 텍스쳐 처리를 실행할 수 있는 경우,IDirect3DDevice7::GetCaps 을 호출하면, 이 렌더링 디바이스는 D3DPTEXTURECAPS_ALPHAPALETTE 기능을 공개한다 (D3DPTEXTURECAPS_ALPHAPALETTE 플래그는, 이 호출로 건네주는 D3DDEVICEDESC7 구조체에 포함되는 2 개의 D3DPRIMCAPS 구조체에 있다).

[Visual Basic]

Direct3D 디바이스는, Attach 된 팔레트를 사용하는 텍스쳐 표면으로부터의 텍스쳐 처리를 지원 한다. 이 타입의 텍스쳐를 "팔레트화 텍스쳐" 라고 부른다. 팔레트화 텍스쳐는 DirectDrawSurface 오브젝트이다. 이 오브젝트는, DDSCAPS_TEXTURE 기능에 의해 생성되어 DDPF_PALETTEINDEXEDn 픽셀 포맷 (n 는 1, 2, 4, 또는 8)의 어느쪽이든을 사용한다. 이 기능은, 텍스쳐의 생성에 사용하는 DDSURFACEDESC2 형 ( 및, 이 기술에 포함되는 DDPIXELFORMAT 형)에 포함되어 있다. 모든 팔레트화 표면과 같이, 색은 아니고 각 픽셀이, Attach 된 DirectDrawPalette 오브젝트내에 보관 유지되는 값의 테이블에의 인덱스가 된다. 팔레트화 표면의 생성 및 사용의 상세한 것에 대하여는, DirectDraw 문서의 「표면」 및 「팔레트」를 참조할것. 텍스쳐 관련 디바이스 기능을 체크하는 경우와 같이,Direct3DDevice7.GetTextureFormatsEnum 메소드에 의해 취득한 Direct3DEnumPixelFormats 클래스를 사용해, 지원 되고 있는 텍스쳐 픽셀 포맷을 반드시 확인하는 것.

팔레트화 텍스쳐를 준비하려면

  1. 여기서 설명한 것처럼, DirectDraw 와 Direct3D 의 기능을 체크한다.
  2. DDSCAPS_TEXTURE 기능을 포함해, DDPF_PALETTEINDEXEDn 픽셀 포맷의 어느쪽이든을 사용하는 표면을 필요한 크기로 생성 한다.
  3. DirectDrawPalette 오브젝트를 생성 해, 초기화한다. 상세한 것에 대하여는, DirectDraw 문서의 「팔레트」를 참조할것 (알파 전용 팔레트화 텍스쳐를 사용하려면 , 팔레트를 생성 할 경우에 DDPCAPS_ALPHA 기능을 포함한다. 상세한 것에 대하여는,DirectDraw7.CreatePalette 의 레퍼런스를 참조할것).
  4. 텍스쳐 표면에 대해서 DirectDrawSurface7.SetPalette 메소드를 호출해, 팔레트를 표면에 Attach 한다.

주 : 팔레트화 텍스쳐 표면을 생성 했지만, 팔레트를 Attach 하지 않았던 경우, 렌더링중에 Direct3D 직접 모드내에서 어플리케이션의 액세스 위반이 발생한다.

팔레트화 텍스쳐로 사용하는 팔레트는, 색데이터만 사용할 필요는 없다. 경우에 따라서는, 디바이스가, 알파 정보를 포함한 텍스쳐 팔레트를 지원 하고 있는 일도 있다. 그 경우,DirectDraw7, GetCaps 메소드를 호출하면, DirectDraw 는 DDPCAPS_ALPHA 팔레트 능력 플래그를 공개한다. 이 플래그는, 관련하는 DDCAPS 형의 lPalCaps 멤버에 있다. 렌더링 디바이스로 알파 대응 팔레트화 텍스쳐로부터의 텍스쳐 처리를 실행할 수 있는 경우,Direct3DDevice7.GetCaps 를 호출하면, 이 렌더링 디바이스는 D3DPTEXTURECAPS_ALPHAPALETTE 기능을 공개한다 (D3DPTEXTURECAPS_ALPHAPALETTE 플래그는, 이 호출로 건네주는 D3DDEVICEDESC7 형에 포함되는 2 개의 D3DPRIMCAPS 형에 있다).


텍스쳐 좌표

이하의 주제에서는, 텍스쳐 좌표의 개념, 텍스쳐 좌표 포맷, 및 텍스쳐 좌표 포맷을 조작하는 Direct3D 서비스에 대해 설명한다.

  • 텍스쳐 좌표에 대해
  • 텍셀과 픽셀간의 직접 맵핑
  • 텍스쳐 좌표 포맷
  • 텍스쳐 좌표 처리


텍스쳐 좌표에 대해

대부분의 텍스쳐는, 비트 맵과 같이, 컬러값의 2 차원 배열이다 (큐브 환경 맵 텍스쳐는 제외하다. 상세한 것에 대하여는, 「큐브 환경 맵」을 참조할것). 각각의 컬러값은, 텍스쳐 요소 또는텍셀로 불린다. 각 텍셀은, 텍스쳐내의 일의의 주소를 가진다. 이 주소는, 각각 u 와 v 로 나타내지는 행과 열의 번호이다고 생각할 수가 있다.

텍스쳐 좌표는 텍스쳐 공간에 있다. 즉, 텍스쳐 좌표는, 텍스쳐내의 것 (0,0)을 기준으로 한 상대 위치 좌표에 존재한다. 텍스쳐를 3D 공간의 원시적으로 적용 하면 와, 그 텍셀 주소를 오브젝트 좌표에 맵핑 해야 한다. 그 후, 이 주소를 화면 좌표, 즉 픽셀 위치 좌표에 평행이동 할 필요가 있다.

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 가 픽셀 컬러를 얻기 위해서(때문에) 사용하는 메소드를 결정한다. 상세한 것에 대하여는, 「텍스쳐 필터링」을 참조할것.

어플리케이션은, 텍스쳐 좌표를 직접 버텍스에 할당할 수가 있다. 상세한 것에 대하여는, C++ 의 D3DVERTEX 구조체 (또는 Visual Basic 의 D3DVERTEX 형)의 레퍼런스를 참조할것. 이 기능에 의해, 원시적으로 맵핑 하는 텍스쳐의 부분을 결정할 수가 있다. 예를 들어, 다음의 그림의 텍스쳐와 완전히 같은 사이즈의 직사각형 프리미티브를 생성 하는 경우를 생각한다. 이 예에서는, 어플리케이션으로 텍스쳐 전체를 벽전체에 맵핑 한다. 어플리케이션이 프리미티브의 버텍스에 할당하는 텍스쳐 좌표는, (0.0, 0.0), (1.0, 0.0), (1.0, 1.0), 및 (0.0, 1.0)이다.

벽의 높이를 반으로 하면(자) 가정한다. 이 때문에는, 작은 벽에 맞추어 텍스쳐를 비뚤어지게 하는지, 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」를 참조할것.


텍셀과 픽셀간의 직접 맵핑

스크린 위에의 픽셀에 텍셀을 직접 맵핑 하는 등, 어플리케이션에서는 보통, 장면내의 지오메트리에 텍스쳐를 적용할 필요가 있다. 예를 들어, 텍스쳐내의 텍스트를 장면내의 오브젝트에 표시할 필요가 있는 어플리케이션을 생각한다. 텍스쳐내의 텍스트 정보를 분명히 표시하려면 , 텍스쳐를 베푸는 지오메트리가, 텍스쳐 필터링에 의해 무너지지 않은 텍셀을 확실히 받기 위한 어떠한 방법이 필요하다. 이것을 하지 않으면 멍하니 한 화면이 되거나 포인트 샘플 텍스쳐 필터링의 경우에는 엣지가 엉성해질 가능성이 있다.

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 을 사용하는 경우, 2 개(살)이 일렬에 줄선다. 양쪽 모두의 사이즈가 거의 같아 적절히 정렬하고 있으면, 다음의 그림에 나타내도록(듯이), 이것들은 텍셀과 픽셀간에 정확하게 대응한다.


텍스쳐 좌표 포맷

Direct3D 의 텍스쳐 좌표에는, 1, 2, 3, 또는 4 개의 부동 소수점 요소를 포함해, 다양한 크기의 텍스쳐를 처리할 수 있다. 1D 텍스쳐 (크기가 1 x n 의 텍스쳐 표면)의 경우, 1 개의 텍스쳐 좌표로 처리된다. 가장 일반적인 2D 텍스쳐의 경우는, 보통 u 와 v 로 불리는 2 개의 텍스쳐 좌표에 의해 처리된다. Direct3D 에서는, 큐브 환경 맵이라고 하는 3D 텍스쳐를 1 종류만 지원 하고 있다. 큐브 환경 맵은, 실제로는 3D 는 아니지만, 3 요소 벡터에 의해 처리된다. 상세한 것에 대하여는, 「큐브 환경 맵」을 참조할것.

[C++]

「버텍스 포맷에 대하며」로 설명하도록(듯이), 어플리케이션에서는 버텍스 포맷내의 텍스쳐 좌표를 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;
[Visual Basic]

「버텍스 포맷에 대하며」로 설명하도록(듯이), 어플리케이션에서는 버텍스 포맷내의 텍스쳐 좌표를 encode 한다. 버텍스 포맷에는 텍스쳐 좌표의 복수세트를 포함할 수가 있다. D3DFVF_TEX0 ~ D3DFVF_TEX8 유연한 버텍스 포맷 플래그를 사용해, 텍스쳐 좌표를 포함하지 않는가, 최대 8 개세트까지 포함하는 것을 지정한다.

각 텍스쳐 좌표 세트에는, 1 ~4 개의 요소를 포함할 수가 있다. 이 SDK 부속의 Math.bas 소스 파일에 있는 헬퍼-함수 D3DFVF_TEXCOORDSIZEn 세트를 사용해, 버텍스 포맷의 특정의 텍스쳐 좌표 세트로 사용되는 요소의 개수를 기술하는 비트 패턴을 생성 한다. 이러한 매크로는, 요소수를 정의하는 좌표 세트의 인덱스를 식별하는 파라미터를 1 개 받는다. 다음의 그림은, 이러한 매크로의 사용 방법을 나타낸다.

Private Sub Form_Load()
'이 버텍스 포맷에는, 2 개의 텍스쳐 좌표 세트가 포함되어 있다.
' 1 번째세트 (인덱스 0)에는 2 개의 요소가 있어, 2 번째세트에는 요소가 1 개 있다.
'
'이 버텍스 포맷은 다음과 같이 기술된다.
'     lFVF = D3DFVF_XYZ Or D3DFVF_NORMAL Or _
'            D3DFVF_DIFFUSE Or D3DFVF_TEX2 Or _
'            D3DFVF_TEXCOORDSIZE2(0) Or D3DFVF_TEXCOORDSIZE1(1)
'
Type CustomVertexFormat
position As D3DVECTOR
normal As D3DVECTOR
diffuse  As D3DVECTOR
' 1 번째세트, 2D
u As Single
v As Single
' 2 번째세트, 1D
t As Single
End Type

주 : 큐브 환경 맵을 제외해, 래스터라이저에서는 3 개 이상의 요소를 사용해 텍스쳐를 처리할 수 없다. 어플리케이션에서는 텍스쳐 좌표에 최대 3 개(살)까지 요소를 지정할 수 있지만, 이것이 가능한 것은, 텍스쳐가 큐브 맵의 경우인가, D3DTTFF_PROJECTED 텍스쳐 트랜스 폼 플래그가 사용되고 있는 경우뿐이다. D3DTTFF_PROJECTED 플래그가 사용되고 있는 경우, 래스터라이저는 최초의 2 개의 요소를 3 번째 (또는 n 번째)의 요소로 나눗셈 한다. 상세한 것에 대하여는, 「텍스쳐 좌표 트랜스 폼」을 참조할것.


텍스쳐 좌표 처리

이 섹션에서는, Direct3D 로 지원 하는 텍스쳐 좌표 처리에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • 텍스쳐 좌표 처리의 흐름
  • 텍스쳐 좌표의 자동 생성
  • 텍스쳐 좌표 트랜스 폼
  • 텍스쳐 좌표 처리의 사용


텍스쳐 표면 오브젝트

이 섹션에서는, 이하에 나타내도록(듯이), 텍스쳐 인터페이스 포인터에 의한 생성 및 렌더링에 대해 설명한다.

  • 텍스쳐 표면 오브젝트의 취득
  • 텍스쳐 표면을 사용한 렌더링


텍스쳐 표면 오브젝트의 취득

[C++]

텍스쳐와는 단지 DirectDraw 표면 오브젝트이며,IDirectDrawSurface7 인터페이스를 공개한다. 텍스쳐 인터페이스에의 포인터를 취득하기 위해서 최초로 하는 것은, DDSCAPS_TEXTURE 기능 세트를 사용해 DirectDraw 표면을 생성 하는 것이다. 「표면의 생성」 및 「DDSCAPS2 」를 참조할것.

표면을 생성 하면, 어플리케이션은 텍스쳐 표면의 IDirectDrawSurface7 인터페이스에의 포인터를 취득한다. 표면 인터페이스의 메소드를 사용해, 그 외의 표면의 경우와 같게, 그 표면에 포함되는 데이터를 조작할 수 있다. 텍스쳐의 IDirectDrawSurface7 는, 텍스쳐의 식별자로서 기능한다. 즉,IDirect3DDevice7 인터페이스의 텍스쳐 관련 메소드는 모두, 이 인터페이스에의 포인터를 받는다.

주 : IDirect3DDevice7::Load 메소드를 사용해, 화면을 텍스쳐에 로드한다. 이 메소드를 호출해 비디오 메모리에 텍스쳐를 로드하는 (분)편이, 블리트 처리보다 추천 된다.

[Visual Basic]

텍스쳐와는 단지 DirectDraw 표면 오브젝트이며,DirectDrawSurface7 클래스에 의해 나타내진다. 텍스쳐를 취득하기 위해서 최초로 하는 것은, DDSCAPS_TEXTURE 기능 세트를 사용해 DirectDraw 표면을 생성 하는 것이다. 「표면의 생성」 및 「DDSCAPS2 」를 참조할것.

표면을 생성 하면, 어플리케이션에서는 표면 클래스 오브젝트에의 참조를 취득한다. DirectDrawSurface7 의 메소드를 사용해, 그 외의 표면의 경우와 같게, 그 표면에 포함되는 데이터를 조작할 수 있다. 텍스쳐는, 어플리케이션이 보관 유지하는 DirectDrawSurface7 클래스에의 참조에 의해 식별된다. Direct3DDevice7 클래스의 텍스쳐 관련 메소드는 모두, 이 클래스 참조를 파라미터로서 받는다.

주 : Direct3DDevice7.Load 메소드를 사용해, 화면을 텍스쳐에 로드한다. 이 메소드를 호출해 비디오 메모리에 텍스쳐를 로드하는 (분)편이, 블리트 처리보다 추천 된다.


텍스쳐 표면을 사용한 렌더링

Direct3D 에서는, 텍스쳐 스테이지라고 하는 개념을 이용해 멀티 텍스쳐 블렌딩을 지원 한다. 텍스쳐 스테이지 마다, 텍스쳐와 그 텍스쳐로 실행 가능한 처리가 있다. 텍스쳐 스테이지의 텍스쳐는, 현재 텍스쳐의 모임을 형성한다. 상세한 것에 대하여는, 「멀티 텍스쳐 블렌딩」을 참조할것. 각 텍스쳐의 스테이트는, 그 텍스쳐 스테이지에 캡슐화된다.

[C++]

C++ 어플리케이션에서는, 각 텍스쳐의 스테이트는 IDirect3DDevice7::SetTextureStageState 메소드로 설정할 필요가 있다. 제 1 파라미터의 값으로서 스테이지 번호 (0 ~ 7)를 건네준다. 제 2 파라미터의 값에는,D3DTEXTURESTAGESTATETYPE 열거형의 멤버를 설정한다. 마지막 파라미터는, 특정의 텍스쳐 스테이트에 대한 스테이트값이다.

텍스쳐 인터페이스 포인터를 사용해, 최대 8 개의 텍스쳐의 블렌드를 렌더링 할 수 있다. IDirect3DDevice7::SetTexture 메소드를 호출해 현재 텍스쳐를 설정한다. Direct3D 는, 렌더링 하는 프리미티브에 대해서, 현재 텍스쳐를 모두 블렌드 한다.

주 : SetTexture 메소드는, 할당할 수 있는 텍스쳐 표면의 참조 카운트를 증분 한다. 텍스쳐가 불필요하게 되었을 경우, 해당하는 스테이지의 텍스쳐를 NULL 로 설정할 필요가 있다. 이것을 실시하지 않았던 경우, 표면은 릴리즈 되지 않고, 메모리 누수가 발생한다.

IDirect3DDevice7::SetRenderState 메소드를 호출해, 현재 텍스쳐의 텍스쳐 랩핑 스테이트를 설정할 수 있다. 제 1 파라미터의 값으로서D3DRENDERSTATE_WRAP0 ~ D3DRENDERSTATE_WRAP7 로부터 값을 1 개 건네준다. 또, D3DWRAPCOORD_0, D3DWRAPCOORD_1, D3DWRAPCOORD_2, 및 D3DWRAPCOORD_3 플래그의 편성을 사용해, u 또는 v 방향의 랩핑을 유효하게 한다.

또, 텍스쳐 퍼스펙티브 스테이트와 텍스쳐 필터링 스테이트를 설정할 수도 있다. 「텍스쳐 퍼스펙티브 스테이트」, 「텍스쳐 필터링」, 및 「텍스쳐 필터링 스테이트」를 참조할것.

[Visual Basic]

Visual Basic 에서는, 각 텍스쳐의 스테이트는 Direct3DDevice7.SetTextureStageState 메소드로 설정할 필요가 있다. 제 1 파라미터의 값으로서 스테이지 번호 (0 ~ 7)를 건네준다. 제 2 파라미터의 값에는,CONST_D3DTEXTURESTAGESTATETYPE 열거의 멤버의 멤버를 설정한다. 마지막 파라미터는, 특정의 텍스쳐 스테이트에 대한 스테이트값이다.

어플리케이션에서는, 최대 8 개의 텍스쳐의 블렌드를 렌더링 할 수 있다. Direct3DDevice7.SetTexture 메소드를 호출해 현재 텍스쳐를 설정한다. Direct3D 는, 렌더링 하는 프리미티브에 대해서, 현재 텍스쳐를 모두 블렌드 한다.

주 : 텍스쳐가 불필요하게 되었을 경우, 해당하는 스테이지의 텍스쳐를 Nothing 로 설정할 필요가 있다. 이것을 실시하지 않았던 경우, 어플리케이션을 닫았을 때에 표면용의 메모리가 없어지는 일이 있다.

Direct3DDevice7.SetRenderState 메소드를 호출해, 현재 텍스쳐의 텍스쳐 랩핑 스테이트를 설정할 수 있다. 제 1 파라미터의 값으로서D3DRENDERSTATE_WRAP0 ~ D3DRENDERSTATE_WRAP7 의 값을 1 개 건네준다. 또, D3DWRAPCOORD_0, D3DWRAPCOORD_1, D3DWRAPCOORD_2, 및 D3DWRAPCOORD_3 플래그 (CONST_D3D 열거로부터) 의 편성을 사용해, u 또는 v 방향의 랩핑을 유효하게 한다.

또, 텍스쳐 퍼스펙티브 스테이트와 텍스쳐 필터링 스테이트를 설정할 수도 있다. 「텍스쳐 퍼스펙티브 스테이트」, 「텍스쳐 필터링」, 및 「텍스쳐 필터링 스테이트」를 참조할것.


텍스쳐 필터링

Direct3D 는 프리미티브를 렌더링 하면 와, 3D 프리미티브를 2D 스크린에 맵핑 한다. 프리미티브가 텍스쳐를 가지고 있는 경우, Direct3D 는 그 텍스쳐를 사용해, 프리미티브의 2D 렌더링 화면의 각 픽셀의 색을 생성해야 한다. 프리미티브의 스크린 위에의 화면의 모든 픽셀에 대해서, 텍스쳐로부터 컬러값을 취득해야 한다. 이 처리를텍스쳐 필터링이라고 부른다.

텍스쳐 필터링 처리를 실행 하면 와, 사용하는 텍스쳐는 보통 확대 또는 축소된다. 즉, 텍스쳐는, 그 자체보다 큰 또는 작은 프리미티브 화면에 맵핑 된다. 텍스쳐의 확대에 의해, 다수의 픽셀이 1 개의 텍셀에 맵핑 되는 일이 있다. 이 결과, 화면이 엉성해지는 일이 있다. 텍스쳐의 축소에서는, 많은 경우, 단일의 픽셀이 다수의 텍셀에 맵핑 된다. 이 결과, 화면이 불선명하게 되거나 톱니 모양이 생기는 일이 있다. 이러한 문제를 해결하려면 , 픽셀의 색이 되도록(듯이) 텍셀색의 블렌딩을 실행할 필요가 있다.

Direct3D 에서는, 텍스쳐 필터링의 복잡한 처리를 간소화한다. Direct3D 에서는, 선형 필터링, 비등방성 필터링, 및 밉맵 필터링의 3 종류의 텍스쳐 필터링을 사용할 수 있다. 텍스쳐 필터링을 선택하지 않는 경우, Direct3D 에서는 최근점샘플링이라고 하는 방법을 사용한다.

각각의 텍스쳐 필터링에는, 장점과 단점이 있다. 예를 들어, 선형 텍스쳐 필터링을 사용했을 경우, 최종적인 화면으로 엣지가 깔쭉깔쭉하게 되거나 화질이 엉성해지는 일이 있다. 그러나, 이 필터링은 오버헤드가 적다. 한편, 밉맵에 의한 필터링을 사용 하면, 보통은 최선의 결과를 얻을 수 있다. 특히, 비등방성 필터링과 조합해 사용했을 경우는 그렇다. 그러나, 이 필터링은, Direct3D 가 지원 하는 방법 중(안)에서 가장 메모리를 필요로 하는 것이다.

[C++]

텍스쳐 인터페이스 포인터를 사용하는 어플리케이션에서는,IDirect3DDevice7::SetTextureStageState 메소드를 호출해 현재의 텍스쳐 필터링 방법을 설정할 필요가 있다. 제 1 파라미터의 값에는, 텍스쳐 필터링 방법을 선택하는 텍스쳐의 정수 인덱스 번호 (0 ~ 7)를 설정한다. 제 2 파라미터의 값으로서 D3DTSS_MAGFILTER, D3DTSS_MINFILTER, 또는 D3DTSS_MIPFILTER 의 어느쪽이든을 건네준다. 제 3 파라미터에는,D3DTEXTUREMAGFILTER ,D3DTEXTUREMINFILTER , 또는 D3DTEXTUREMIPFILTER 열거형의 멤버를 설정한다.

[Visual Basic]

Visual Basic 어플리케이션에서는,Direct3DDevice7.SetTextureStageState 메소드를 호출해 현재의 텍스쳐 필터링 방법을 설정할 필요가 있다. 제 1 파라미터의 값에는, 텍스쳐 필터링 방법을 선택하는 텍스쳐의 정수 인덱스 번호 (0 ~ 7)를 설정한다. 제 2 파라미터의 값으로서 D3DTSS_MAGFILTER, D3DTSS_MINFILTER, 또는 D3DTSS_MIPFILTER 의 어느쪽이든을 건네준다. 제 3 파라미터에는,CONST_D3DTEXTUREMAGFILTER ,CONST_D3DTEXTUREMINFILTER , 또는 CONST_D3DTEXTUREMIPFILTER 열거형의 멤버를 설정한다.

이 섹션에서는, Direct3D 로 지원 하는 텍스쳐 필터링 방법에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • 최근점샘플링
  • 선형 텍스쳐 필터링
  • 비등방성 텍스쳐 필터링
  • 밉맵에 의한 텍스쳐 필터링
[C++]

주 : D3DRENDERSTATETYPE 열거형에 있는 텍스쳐 필터링 스테이트는, 텍스쳐 스테이지 스테이트로 옮겨지고 있지만, 이 렌더링 스테이트를 사용해도 IDirect3DDevice7::SetRenderState (IDirect3DDevice2 버젼과는 대조적으로)의 실행이 실패할 것은 없다. 그 대신해, 시스템에서는, 이 렌더링 스테이트의 이펙트를 멀티 텍스쳐 cascade의 최초의 스테이지 (스테이지 0)에 맵핑 한다. 어플리케이션에서는, 종래의 렌더링 스테이트를 그것과 대응하는 텍스쳐 스테이지 스테이트와 병용 하지 않는 것. 예기치 못한 결과가 생길 우려가 있다.


최근점샘플링

어플리케이션에서는, 텍스쳐 필터링을 사용할 필요는 없다. Direct3D 는, 텍셀 주소를 계산 (이 주소는 정수가 아닌 것이 많다)하거나 이 값에 가장 가까운 정수 주소를 가지는 텍셀의 색을 단지 카피하도록(듯이) 설정할 수 있다. 이 처리를 최근점샘플링이라고 부른다. 텍스쳐의 사이즈가 스크린 위에의 프리미티브의 화면의 사이즈와 거의 같은 경우에는, 이 방법에 따라 텍스쳐는 고속으로 효율적으로 처리할 수 있다. 양쪽 모두의 사이즈의 차이가 큰 경우는, 텍스쳐를 확대하거나 축소할 필요가 있다. 이러한 처리를 실행한 결과, 화면이 엉성해지거나 톱니 모양이 생기거나 불선명하게 되는 일이 있다.

[C++]

C++ 어플리케이션에서는,IDirect3DDevice7::SetTextureStageState 메소드를 호출해 최근점샘플링을 선택할 수 있다. 제 1 파라미터의 값을, 텍스쳐 필터링 방법을 선택하는 텍스쳐의 정수 인덱스 번호 (0 ~ 7)로 설정한다. 제 2 파라미터를 D3DTSS_MAGFILTER, D3DTSS_MIMIFILTER, 또는 D3D_MIPFILTER 로 설정한다. D3DTEXTUREMAGFILTER ,D3DTEXTUREMINFILTER , 또는 D3DTEXTUREMIPFILTER 열거형의 멤버를 다음의 파라미터의 값으로서 건네주어, 확대, 축소, 또는 밉맵 필터를 설정한다.

상세한 것에 대하여는, 「텍스쳐 필터링 스테이트」를 참조할것.

[Visual Basic]

Visual Basic 어플리케이션에서는,Direct3DDevice7.SetTextureStageState 메소드를 호출해 최근점샘플링을 선택할 수 있다. 제 1 파라미터의 값을, 텍스쳐 필터링 방법을 선택하는 텍스쳐의 정수 인덱스 번호 (0 ~ 7)로 설정한다. 제 2 파라미터를 D3DTSS_MAGFILTER, D3DTSS_MIMIFILTER, 또는 D3D_MIPFILTER 로 설정한다. CONST_D3DTEXTUREMAGFILTER ,CONST_D3DTEXTUREMINFILTER , 또는 CONST_D3DTEXTUREMIPFILTER 열거의 멤버를 다음의 파라미터에 건네주어, 확대, 축소, 또는 밉맵 필터를 설정한다.

상세한 것에 대하여는, 「텍스쳐 필터링 스테이트」를 참조할것.

최근점샘플링은 주의해 사용하는 것. 2 개의 텍셀간의 경계에서 텍스쳐가 샘플링 될 때, 경우에 따라서는 부자연스러운 그래픽스 효과가 생기는 일이 있다. 이 경계란, 샘플링 대상의 텍셀이 다음의 텍셀로 옮길 때의, 텍스쳐에 따른 위치 좌표 (u 또는 v)이다. 포인트 샘플링을 사용할때, 시스템에서는 샘플 텍셀을 1 개 선택하는지, 다른 텍셀을 선택한다. 이것에 의해, 경계가 교차하고 있을 때는 결과가 텍셀간에 갑자기 변화하는 일이 있다. 이 영향으로부터, 표시되는 텍스쳐안에, 바람직하지 않은 부자연스러운 그래픽스 이펙트가 나타나는 일이 있다 (선형 필터링을 사용했을 경우, 결과 텍셀은 인접 텍셀간에 계산되어 텍스쳐 인덱스가 경계를 따라 옮기는데 따라서 매끄럽게 블렌드 된다).

이러한 이펙트는, 매우 작은 텍스쳐를 매우 큰 다각형에 맵핑 하는 (많은 경우 "확대" 라고 부른다) 풀어에 발생할 가능성이 있다. 예를 들어, checker반과 같은 텍스쳐로 포인트 샘플링을 사용 하면, checker반은 확대되어 엣지가 두드러진다. 대조적으로, 선형 텍스쳐 필터링을 사용했을 경우는, checker반의 색이 다각형 전체에 걸쳐서 매끄럽게 변화한 화면이 완성된다.

대부분의 경우, 최선의 결과를 얻기 위해서(때문에)는, 최근점샘플링의 사용을 가능한 한 피하도록(듯이) 한다. 최근의 하드웨어의 대부분은, 선형 필터링용으로 최적화되고 있기 (위해)때문에, 퍼포먼스가 저하할 것은 없다. 다만, 텍스쳐를 사용해 읽기 쉬운 텍스트 문자를 표시하는 경우 등, 희망의 이펙트를 내기 위해서(때문에) 아무래도 최근점샘플링을 사용해야 하는 경우는, 텍셀 경계에서 샘플링을 실시하지 않게 유의하고 생각하지 않는 이펙트가 생기지 않게 세심의 주위를 기울일 필요가 있다. 다음의 그림은, 부자연스러운 그래픽스 효과가 어떠한 것인지를 나타낸다.

그룹내의 우상에 있는 2 개의 사각형이 인접하는 사각형과는 다른 것에 주의한다. 이러한 부자연스러운 그래픽스 효과를 피하기 위해서(때문에)는, 우선 최근점샘플링에 관한 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) 해 부자연스러운 효과의 발생을 막는 것이 추천 된다.


선형 텍스쳐 필터링

Direct3D 에서는, 바이리니아피르타링으로 불리는 선형 텍스쳐 필터링을 사용한다. 최근점샘플링과 같이, 바이리니아테크스체피르타링에서는 최초로 텍셀 주소를 계산하지만, 보통, 이 값이 정수 주소가 될 것은 없다. 정수 주소가 아닌 경우는, 최근점샘플링과 같이, 계산한 주소에 가장 가까운 정수 주소를 가지는 텍셀이 검색된다. 게다가 Direct3D 렌더링 모듈에서는, 샘플링 한 최근점의 상하 좌우에 있는 텍셀의 가중평균을 계산한다.

[C++]

IDirect3DDevice7::SetTextureStageState 메소드를 호출해, 바이리니아테크스체피르타링을 선택한다. 제 1 파라미터의 값을, 텍스쳐 필터링 방법을 선택하는 텍스쳐의 정수 인덱스 번호 (0 ~ 7)로 설정한다. 확대 필터를 설정하는 경우는, 제 2 파라미터의 값으로서 D3DTEXTUREMAGFILTER 를 건네준다. 축소 필터를 설정하는 경우는, 제 2 파라미터의 값으로서 D3DTEXTUREMINFILTER 를 건네준다. 밉맵 필터를 설정하는 경우는, 제 2 파라미터의 값으로서 D3DTEXTUREMIPFILTER 를 건네준다. 제 3 파라미터를, 확대 필터를 설정하는 경우는 D3DTFG_LINEAR, 축소 필터를 설정하는 경우는 D3DTFN_LINEAR, 밉맵 필터를 설정하는 경우는 D3DTFP_LINEAR 에 각각 설정한다. 상세한 것에 대하여는, 「텍스쳐 필터링 스테이트」를 참조할것.

[Visual Basic]

Direct3DDevice7.SetTextureStageState 메소드를 호출해, 바이리니아테크스체피르타링을 선택한다. 제 1 파라미터의 값을, 텍스쳐 필터링 방법을 선택하는 텍스쳐의 정수 인덱스 번호 (0 ~ 7)로 설정한다. 제 2 파라미터에,CONST_D3DTEXTUREMAGFILTER ,CONST_D3DTEXTUREMINFILTER , 또는 CONST_D3DTEXTUREMIPFILTER 열거의 멤버를 건네주어, 확대, 축소, 또는 밉맵 필터를 설정한다. 제 3 파라미터를, 확대 필터를 설정하는 경우는 D3DTFG_LINEAR, 축소 필터를 설정하는 경우는 D3DTFN_LINEAR, 밉맵 필터를 설정하는 경우는 D3DTFP_LINEAR 를 각각 설정한다. 상세한 것에 대하여는, 「텍스쳐 필터링 스테이트」를 참조할것.


비등방성 텍스쳐 필터링

비등방성이란, 스크린 평면에 대해서 각도를 이루어 위치 좌표 한 표면을 가지는 3D 오브젝트의 텍셀의 가시적인 왜곡이다. 비등방성 프리미티브로부터의 픽셀을 텍셀에 맵핑 하면 와, 프리미티브의 형상이 뒤틀린다. Direct3D 에서는, 텍스쳐 공간에 역맵핑 되는 스크린 픽셀의 신장도 (길이÷폭)로서 픽셀의 비등방성을 측정한다.

[C++]

비등방성 텍스쳐 필터링은, 선형 텍스쳐 필터링 또는 밉맵 텍스쳐 필터링과 병용 하는 것으로, 렌더링 결과를 향상시킬 수가 있다. IDirect3DDevice7::SetTextureStageState 메소드를 호출해, 비등방성 텍스쳐 필터링을 유효하게 한다. 제 1 파라미터의 값에는, 텍스쳐 필터링 방법을 선택하는 텍스쳐의 정수 인덱스 번호 (0 ~ 7)를 설정한다. 확대 필터를 설정하는 경우는, 제 2 파라미터의 값으로서 D3DTEXTUREMAGFILTER 를 건네준다. 축소 필터를 설정하는 경우는, 제 2 파라미터의 값으로서 D3DTEXTUREMINFILTER 를 건네준다. 제 3 파라미터에는, 확대 필터를 설정하는 경우는 D3DTFG_ANISOTROPIC, 축소 필터를 설정하는 경우는 D3DTFN_ANISOTROPIC 를 각각 설정한다. 상세한 것에 대하여는, 「텍스쳐 필터링 스테이트」를 참조할것.

또, 비등방성의 정도를 제로보다 큰 값으로 설정할 필요가 있다. 이것을 설정하려면 ,IDirect3DDevice7::SetTextureStageState 메소드를 호출한다. 제 1 파라미터에는, 비등방성의 정도를 설정하는 텍스쳐의 정수 인덱스 번호 (0 ~ 7)를 설정한다. 제 2 파라미터에는, D3DTSS_MAXANISOTROPY 를 건네준다. 마지막 파라미터는, 비등방성의 정도가 아니면 안된다.

비등방성의 정도를 1 으로 설정 하면, 비등방성 필터링이 무효가 된다 (1 보다 큰 값을 설정 하면, 비등방성 필터링이 유효하게 된다). 비등방성의 정도로서 설정 가능한 값의 범위를 판별하려면 ,D3DPRIMCAPS 구조체의 D3DPRASTERCAPS_ANISOTROPY 플래그를 체크한다.

[Visual Basic]

비등방성 텍스쳐 필터링은, 선형 텍스쳐 필터링 또는 밉맵 텍스쳐 필터링과 병용 하는 것으로, 렌더링 결과를 향상시킬 수가 있다. Direct3DDevice7.SetTextureStageState 메소드를 호출해, 비등방성 텍스쳐 필터링을 유효하게 한다. 제 1 파라미터에는, 텍스쳐 필터링 방법을 선택하는 텍스쳐의 정수 인덱스 번호 (0 ~ 7)를 설정한다. 제 2 파라미터에는,CONST_D3DTEXTUREMAGFILTER ,CONST_D3DTEXTUREMINFILTER , 또는 CONST_D3DTEXTUREMIPFILTER 열거의 멤버를 건네주어, 확대, 축소, 또는 밉맵 필터를 설정한다. 제 3 파라미터에는, 확대 필터를 설정하는 경우는 D3DTFG_ANISOTROPIC, 축소 필터를 설정하는 경우는 D3DTFN_ANISOTROPIC 를 각각 설정한다. 상세한 것에 대하여는, 「텍스쳐 필터링 스테이트」를 참조할것.

또, 비등방성의 정도를 제로보다 큰 값으로 설정할 필요가 있다. 이것을 설정하려면 ,Direct3DDevice7.SetTextureStageState 메소드를 호출한다. 제 1 파라미터에는, 비등방성의 정도를 설정하는 텍스쳐의 정수 인덱스 번호 (0 ~ 7)를 설정한다. 제 2 파라미터에는, D3DTSS_MAXANISOTROPY 를 건네준다. 마지막 파라미터는, 비등방성의 정도가 아니면 안된다.

비등방성의 정도를 1 으로 설정 하면, 비등방성 필터링이 무효가 된다 (1 보다 큰 값을 설정 하면, 비등방성 필터링이 유효하게 된다). 비등방성의 정도로서 설정 가능한 값의 범위를 조사하려면 ,D3DPRIMCAPS 구조체의 D3DPRASTERCAPS_ANISOTROPY 플래그를 체크한다.


밉맵에 의한 텍스쳐 필터링

밉맵 텍스쳐는, 장면의 렌더링에 필요한 시간을 단축하기 위해서 3D 신으로 사용된다. 또, 밉맵 텍스쳐를 사용 하면, 장면의 리얼리티가 늘어난다. 그러나, 밉맵 텍스쳐를 사용하려면 메모리가 대량으로 필요한 것이 많다.

이 섹션에서는, 이하의 주제에 나타내도록(듯이), 3D 신에서의 밉맵 텍스쳐의 사용에 관한 기본 사항에 대해 설명한다.

  • 밉맵이란
  • 밉맵 세트의 생성
  • 밉맵의 선택과 표시


텍스쳐 랩핑

이 섹션에서는, 3D 프리미티브에의 텍스쳐 랩핑에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • 텍스쳐 랩핑이란
  • 텍스쳐 랩핑의 사용

주 : 텍스쳐 랩핑을 텍스쳐 addressing mode와 혼동 하지 않는 것. 상세한 것에 대하여는, 「텍스쳐 addressing mode와 텍스쳐 랩핑」 및 「텍스쳐 addressing mode」를 참조할것.


텍스쳐 랩핑이란

텍스쳐 랩핑이란, 간단하게 말하면, Direct3D 로 각 버텍스에 대해서 지정된 텍스쳐 좌표를 사용해, 텍스쳐 처리한 다각형을 라스터화할 때의 기본적인 방법을 변경하는 처리이다 (텍스쳐 랩핑을 "랩" 텍스쳐 addressing mode와 혼동 하지 않는 것. 상세한 것에 대하여는, 「텍스쳐 addressing mode와 텍스쳐 랩핑」을 참조할것). 다각형의 라스터화중에, 시스템은 다각형의 각 버텍스의 텍스쳐 좌표의 사이를 보간 해, 다각형의 모든 픽셀에 사용하는 텍셀을 결정한다. 보통, 시스템은 텍스쳐를 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 간의 텍셀이, 텍스쳐의 중심을 통과할 때 수평 방향으로 압축되어 이펙트가 망가진다.


텍스쳐 랩핑의 사용

[C++]

C++ 어플리케이션의 경우, 텍스쳐 랩핑을 유효하게 하는 처리는, Direct3D 디바이스 인터페이스의 버젼에 따라서 다르다. 어플리케이션으로 IDirect3DDevice7 인터페이스를 사용하는 경우는, 버텍스로써 사용되는 텍스쳐 좌표 세트에 대해서 텍스쳐 랩핑을 유효하게 해, 텍스쳐 스테이지 스테이트 자체에 대해서 유효하게 하는 것은 아니다. 이 경우,IDirect3DDevic7::SetRenderState 메소드를 호출해, 제 1 파라미터로서 D3DRENDERSTATE_WRAP0 ~ D3DRENDERSTATE_WRAP7 의 열거값의 어느쪽이든을 건네주어, 랩핑의 적용처 텍스쳐 좌표 세트를 지정한다. 제 2 파라미터에 D3DWRAPCOORD_0 ~ D3DWRAPCOORD_3 플래그를 지정해, 대응할 방향의 텍스쳐 랩핑을 유효하게 하는지, 이러한 플래그를 조합해 복수의 방향의 랩핑을 유효하게 한다. 플래그를 생략 하면, 대응할 방향에서의 텍스쳐 랩핑이 무효가 된다. 텍스쳐 좌표의 특정세트에 대해서 텍스쳐 랩핑을 무효로 하려면 , 대응하는 렌더링 스테이트의 값을 0 으로 설정한다.

어플리케이션으로 종래의 IDirect3DDevice2 인터페이스를 사용하는 경우에서도,SetRenderState 메소드를 호출해 텍스쳐 랩핑을 유효하게 할 수 있다. 그러나, 이 인터페이스에서는, D3DRENDERSTATE_WRAP0 ~ D3DRENDERSTATE_WRAP7 는 지원되어 있지 않다. 이러한 대신으로서D3DRENDERSTATE_WRAPU 또는 D3DRENDERSTATE_WRAPV 값을 제 1 파라미터에 사용한다. 제 2 파라미터로 TRUE 를 지정 하면 랩핑이 유효하게 되어, FALSE 를 지정 하면 랩핑이 무효가 된다.

주 : IDirect3DDevice7 인터페이스는, D3DRENDERSTATE_WRAP0 ~ D3DRENDERSTATE_WRAP7 으로 옮겨진 종래의 D3DRENDERSTATE_WRAPU 및 D3DRENDERSTATE_WRAPV 렌더링 스테이트도 인식한다. 이러한 구렌더링 스테이트를 SetRenderState 의 IDirect3DDevice7 버젼에 건네주면(자), 텍스쳐 좌표의 최초세트의 u 및 v 텍스쳐 랩핑에 영향을 준다.

[Visual Basic]

Visual Basic 의 경우, 버텍스로써 사용되는 텍스쳐 좌표 세트에 대해서, 텍스쳐 랩핑을 유효하게 한다. Direct3DDevice7.SetRenderState 메소드를 호출해 텍스쳐 랩핑을 유효하게 해, 제 1 파라미터로서 D3DRENDERSTATE_WRAP0 ~ D3DRENDERSTATE_WRAP7 열거값의 어느쪽이든을 건네주어, 랩핑의 적용처 텍스쳐 좌표 세트를 지정한다. 제 2 파라미터에는 D3DWRAPCOORD_0 ~ D3DWRAPCOORD_3 플래그 (CONST_D3D 열거로부터)를 사용해, 대응할 방향의 텍스쳐 랩핑을 유효하게 하는지, 이러한 플래그를 조합해 복수의 방향의 랩핑을 유효하게 한다. 플래그를 생략 하면, 대응할 방향에서의 텍스쳐 랩핑이 무효가 된다. 텍스쳐 좌표의 특정세트에 대해서 텍스쳐 랩핑을 무효로 하려면 , 대응하는 렌더링 스테이트의 값을 0 으로 설정한다.


텍스쳐 블렌딩

Direct3D 에서는, 텍스쳐를 프리미티브의 색과 블렌드 해 반투명 이펙트를 생성할 수 있다. 또, 복수의 텍스쳐를 1 개의 원시적으로 블렌드 할 수도 있다. 이 섹션에서는, 텍스쳐 블렌딩의 실행 방법에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • 알파 텍스쳐 블렌딩
  • 멀티 패스 텍스쳐 블렌딩
  • 멀티 텍스쳐 블렌딩
  • 텍스쳐에 의한 라이트 맵핑
[C++]

C++ 어플리케이션으로 텍스쳐 블렌딩을 사용하는 경우는, 우선, 유저의 하드웨어로 텍스쳐 블렌딩이 지원 되고 있는지 어떤지를 프로그램으로 조사할 필요가 있다. 이러한 지원 정보에 대해서는,D3DPRIMCAPS 구조체의 dwTextureCaps 멤버를 조사한다. 텍스쳐 블렌딩 기능에 대해 유저의 하드웨어에 문의하는 방법의 상세한 것에 대하여는, 「IDirect3DDevice7::GetCaps 」 및 「D3DDEVICEDESC7 」를 참조할것.

[Visual Basic]

Visual Basic 어플리케이션으로 텍스쳐 블렌딩을 사용하는 경우는, 우선, 유저의 하드웨어로 텍스쳐 블렌딩이 지원 되고 있는지 어떤지를 프로그램으로 조사할 필요가 있다. 이러한 지원 정보에 대해서는,D3DPRIMCAPS 형의 lTextureCaps 멤버를 조사한다. 텍스쳐 블렌딩 기능에 대해 유저의 하드웨어에 문의하는 방법의 상세한 것에 대하여는, 「Direct3DDevice7.GetCaps 」 및 「D3DDEVICEDESC7 」를 참조할것.


알파 텍스쳐 블렌딩

Direct3D 에서는, 프리미티브를 렌더링 하면 와, 프리미티브의 머트리얼 및 라이팅 정보에 근거해 프리미티브의 색을 생성한다. 상세한 것에 대하여는, 「라이팅과 머트리얼」을 참조할것. 어플리케이션으로 텍스쳐 블렌딩이 유효하게 되어 있는 경우, Direct3D 는 1 개 또는 복수의 텍스쳐의 텍셀색을 프리미티브의 현재색과 블렌드 한다. Direct3D 에서는, 다음의 공식을 사용해, 프리미티브의 화면의 각 픽셀에 대한 최종색을 결정한다.

이 공식에서,FinalColor 는, 타겟 렌더링 표면에 출력되는 픽셀 컬러이다. TexelColor 는, 현재 픽셀에 대응하는 텍셀의 색을 나타낸다. Direct3D 로 픽셀을 텍셀에 맵핑 하는 방법의 상세한 것에 대하여는, 「텍스쳐 필터링」을 참조할것. SourceBlendFactor 는, 최종색에 적용하는 텍셀색의 비율을 결정하기 위해서(때문에) Direct3D 가 사용하는 계산값이다. PixelColor 는, 프리미티브의 화면내의 현재 픽셀의 색이다. DestBlendFactor 는, 최종색으로 사용되는 현재 픽셀의 색의 비율을 나타낸다. SourceBlendFactor 와 DestBlendFactor 의 값의 범위는, 0.0 으로 1.0 을 포함한 0.0 ~ 1.0 이다.

위에의 공식으로부터 알 수 있듯이,SourceBlendFactor 가 1.0 으로 DestBlendFactor 가 0.0 의 경우, 텍스쳐는 전혀 투명도가 없는 것으로서 렌더링 된다. SourceBlendFactor 가 0.0 으로 DestBlendFactor 가 1.0 의 경우는, 텍스쳐는 완전하게 투명하게 된다. 이러한 계수에 상기 이외의 값을 설정했을 경우는, 텍스쳐는 어느 정도의 투명을 가지고 색과 블렌드 된다.

텍스쳐의 모든 텍셀은, 적색, 녹색, 및 청색의 컬러값을 가지고 있다. 디폴트에서는, Direct3D 는 텍셀의 알파값을 SourceBlendFactor 로서 사용한다. 따라서, 어플리케이션에서는, 텍스쳐의 알파값을 설정하는 것으로 텍스쳐의 투명도를 제어할 수 있다.

[C++]

C++ 로 개발하는 어플리케이션에서는,D3DRENDERSTATE_SRCBLEND 및 D3DRENDERSTATE_DESTBLEND 렌더링 스테이트를 사용해 블렌딩 계수를 제어한다. IDirect3DDevice7::SetRenderState 메소드를 호출해, 제 1 파라미터의 값으로서 D3DRENDERSTATE_SRCBLEND 또는 D3DRENDERSTATE_DESTBLEND 의 어느쪽이든을 건네준다. 제 2 파라미터는,D3DBLEND 열거형의 멤버가 아니면 안된다.

[Visual Basic]

Visual Basic 어플리케이션에서는,D3DRENDERSTATE_SRCBLEND 및 D3DRENDERSTATE_DESTBLEND 렌더링 스테이트를 사용해 블렌딩 계수를 제어할 수 있다. Direct3DDevice7.SetRenderState 메소드를 호출해, 제 1 파라미터에 렌더링 스테이트의 어느쪽이든을 건네준다. 제 2 파라미터는,CONST_D3DBLEND 열거의 멤버가 아니면 안된다.


멀티 패스 텍스쳐 블렌딩

Direct3D 어플리케이션에서는, 멀티 렌더링 패스로 각종 텍스쳐를 원시적으로 적용해, 수많은 특수 효과를 실현할 수 있다. 이 처리는 일반적으로멀티 패스 텍스쳐 블렌딩으로 불린다. 멀티 패스 텍스쳐 블렌딩의 일반적인 용도는, 몇개의 다른 텍스쳐로부터 복수의 색을 적용해, 복잡한 라이팅 및 쉐이딩 모델의 이펙트를 에뮬레이트 하는 것이다. 이것을 라이트 맵핑이라고 부른다. 상세한 것에 대하여는, 「텍스쳐에 의한 라이트 맵핑」을 참조할것.

주 : 디바이스에 따라서는, 단일의 패스로, 복수의 텍스쳐를 원시적으로 적용할 수 있는 경우도 있다. 상세한 것에 대하여는, 「멀티 텍스쳐 블렌딩」을 참조할것.

유저의 하드웨어로 멀티 텍스쳐 블렌딩이 지원되어 있지 않은 경우에서도, 어플리케이션에서는, 멀티 패스 텍스쳐 블렌딩을 사용해 같은 시각 이펙트를 실현할 수 있다. 다만, 멀티 텍스쳐 블렌딩을 사용했을 경우에는 가능한 frame rate를 유지할 수 없다.

[C++]

C++ 어플리케이션으로 멀티 텍스쳐 블렌딩을 실행하려면

  1. IDirect3DDevice7::SetTexture 메소드를 호출해, 텍스쳐 스테이지 0 에 텍스쳐를 설정한다.
  2. IDirect3DDevice7::SetTextureStageState 메소드를 사용해, 희망의 색 및 알파 블렌딩 인수와 처리를 선택한다 (멀티 패스 텍스쳐 블렌딩용의 최적인 설정은 디폴트 설정이다).
  3. 장면내의 적절한 오브젝트를 렌더링 한다.
  4. 다음의 텍스쳐를 텍스쳐 스테이지 0 으로 설정한다.
  5. D3DRENDERSTATE_SRCBLEND 및 D3DRENDERSTATE_DESTBLEND 렌더링 스테이트를 설정해, 블렌드원 및 블렌드처의 블렌딩 계수를 필요에 따라서 조정한다. 이러한 파라미터에 근거해, 새로운 텍스쳐가 렌더링 타겟 표면내의 기존의 픽셀로 블렌드 된다.
  6. 필요에 따라서, 다른 텍스쳐에 대해서 순서 3, 4, 및 5 를 반복한다.
[Visual Basic]

Visual Basic 어플리케이션으로 멀티 텍스쳐 블렌딩을 실행하려면

  1. Direct3DDevice7.SetTexture 메소드를 호출해, 텍스쳐 스테이지 0 에 텍스쳐를 설정한다.
  2. Direct3DDevice7.SetTextureStageState 메소드를 사용해, 희망의 색 및 알파 블렌딩 인수와 처리를 선택한다 (멀티 패스 텍스쳐 블렌딩용의 최적인 설정은 디폴트 설정이다).
  3. 장면내의 적절한 오브젝트를 렌더링 한다.
  4. 다음의 텍스쳐를 텍스쳐 스테이지 0 으로 설정한다.
  5. D3DRENDERSTATE_SRCBLEND 및 D3DRENDERSTATE_DESTBLEND 렌더링 스테이트를 설정해, 블렌드원 및 블렌드처의 블렌딩 계수를 필요에 따라서 조정한다. 이러한 파라미터에 근거해, 새로운 텍스쳐가 렌더링 타겟 표면내의 기존의 픽셀로 블렌드 된다.
  6. 필요에 따라서, 다른 텍스쳐에 대해서 순서 3, 4, 및 5 를 반복한다.


멀티 텍스쳐 블렌딩

Direct3D 에서는, 단일의 패스로, 최대 8 개의 텍스쳐를 원시적으로 블렌드 할 수 있다. 멀티 텍스쳐 블렌딩을 사용하면, Direct3D 어플리케이션의 frame rate를 큰폭으로 올릴 수가 있다. 어플리케이션은, 멀티 텍스쳐 블렌딩을 채용해, 텍스쳐, 그림자, 스펙큐러 라이트, 디퓨즈 라이트등의 특수 효과를 단일 패스로 적용할 수 있다.

멀티 텍스쳐를 블렌드 하려면 , 어플리케이션으로 그러한 텍스쳐를 현재 텍스쳐 세트에 할당해 다음에블렌딩 스테이지를 생성 한다. 이하의 주제에서는, 이러한 순서의 실행 방법에 대해 설명한다.

  • 텍스쳐 스테이지와 텍스쳐 블렌딩 cascade
  • 텍스쳐 블렌딩 처리와 인수
  • 현재 텍스쳐의 할당
  • 블렌딩 스테이지의 생성


텍스쳐에 의한 라이트 맵핑

3D 신을 리얼하게 렌더링 하려면 , 광원이 장면의 표시에게 주는 이펙트를 고려해야 한다. flat shading나 gouraud shading등의 기술은 이 점으로써 귀중한 툴이지만, 이러한 기술만으로는 불충분하다. Direct3D 는, 멀티 패스 텍스쳐 블렌딩과 멀티 텍스쳐 블렌딩을 지원 하고 있다. 이러한 기능에 의해, 쉐이딩 기술만으로 렌더링 한 장면보다 훨씬 리얼한 장면을 렌더링 할 수 있다. 1 개(살) 또는 복수의라이트 맵을 이용하면, 원시적으로 라이팅과 그림자의 영역을 맵 할 수 있다.

라이트 맵이란, 3D 신의 라이팅에 대한 정보를 포함한 텍스쳐 또는 텍스쳐 그룹이다. 이 라이팅 정보를 라이트 맵의 알파값, 컬러값, 또는 그 양쪽 모두에 저장 할 수 있다.

멀티 패스 텍스쳐 블렌딩을 사용해 라이트 맵핑을 실현하는 경우는, 최초의 패스로 원시적으로 라이트 맵을 렌더링 할 필요가 있다. 또, 제 2 의 패스를 사용해, 베이스 텍스쳐를 렌더링 할 필요가 있다. 다만, 스펙큐러 라이트 맵핑은 제외하다. 스펙큐러 라이트 맵의 경우는, 최초로 베이스 텍스쳐를 렌더링 해, 다음에 라이트 맵을 추가한다.

멀티 텍스쳐 블렌딩에 의해, 1 살의 패스로 라이트 맵과 베이스 텍스쳐의 양쪽 모두를 렌더링 할 수 있다. 유저의 하드웨어로 멀티 텍스쳐 블렌딩이 지원 되고 있는 경우는, 라이트 맵핑을 실시할 때 이 블렌딩을 이용하도록(듯이) 한다. 이것에 의해, 어플리케이션의 퍼포먼스가 큰폭으로 향상한다.

라이트 맵을 사용하면, Direct3D 어플리케이션에서는, 프리미티브를 렌더링 할 경우에 다양한 라이팅 이펙트를 생성할 수 있다. 흑백 라이팅이나 컬러 라이팅을 장면에 맵핑 할 수 있는 것 외에도, 스펙큐러 하이라이트나 디퓨즈 라이트등이 섬세한 이펙트를 추가할 수 있다.

Direct3D 텍스쳐 블렌딩을 사용해 라이트 맵핑을 실행하는 방법에 대해서는, 이하의 주제로 설명한다.

  • 흑백 라이트 맵
  • 컬러 라이팅 맵
  • 스펙큐러 라이트 맵
  • 디퓨즈 라이트 맵


텍스쳐 압축

DirectDraw 에는, 3D 모델의 텍스쳐에 사용하는 표면 압축기노우가 있다. 압축 텍스쳐 표면의 데이터의 생성 및 조작에 대해서는, DirectDraw 문서의 「압축한 텍스쳐 표면」을 참조할것.

[C++]

어플리케이션으로 렌더링 디바이스를 생성 한 후,IDirect3DDevice7::EnumTextureFormats 메소드를 호출해, 압축 텍스쳐 표면으로부터의 텍스쳐 처리를 디바이스가 지원 할지 어떨지를 조사할 수가 있다. 이 메소드는,D3DEnumPixelFormatsCallback 콜백 함수를 호출한다. 이 함수는, 텍스쳐 맵용으로 디바이스가 지원 하는 픽셀 포맷 마다 준비한다. 열거되는 픽셀 포맷으로 DXT1, DXT2, DXT3, DXT4, 또는 DXT5 의 4 문자 코드 (FOURCCs)를 사용하는 경우, 디바이스는 그 포맷을 사용하는 압축 텍스쳐 표면으로부터 직접 텍스쳐를 얻을 수 있다. 이 경우,IDirect3DDevice7::SetTexture 메소드를 호출해, Direct3D 로 압축 텍스쳐 표면을 직접 사용할 수 있다. 디바이스가 압축 텍스쳐 표면으로부터의 텍스쳐 처리를 지원 하지 않는 경우에서도, 텍스쳐 데이터를 압축 포맷 표면내에 저장 할 수 있다. 다만, 압축 텍스쳐를 텍스쳐로서 사용하기 전에, 지원 되는 포맷으로 변환하지 않으면 안 된다. DirectDraw 의 블리트 메소드의 IDirectDrawSurface7::Blt 및IDirectDrawSurface7::BltFast 는, 압축 포맷화등 표준 RGBA 포맷에의 변환을 자동적으로 실행한다. 정보의 손실을 최소한으로 억제하려면 , 압축 포맷과 일치하는 목적지 픽셀 포맷을 선택하도록(듯이) 한다. 예를 들어, ARGB:1555 는 DXT1 의 목적지 포맷에는 적합하지만, DXT3 에는 ARGB:4444 가 적합하다. DXT3 에는 4 비트의 알파 정보가 포함되기 때문에 있다.

[Visual Basic]

어플리케이션으로 렌더링 디바이스를 생성 한 후,Direct3DDevice7.GetTextureFormatsEnum 메소드를 호출해, 압축 텍스쳐 표면으로부터의 텍스쳐 처리를 디바이스가 지원 할지 어떨지를 조사할 수가 있다. 이 메소드는,Direct3DEnumPixelFormats 클래스 오브젝트에의 참조를 돌려준다. 이 클래스 오브젝트는, 지원 되고 있는 텍스쳐 표면 픽셀 포맷에 대한 정보를 취득하기 위한 메소드를 공개한다. Direct3DEnumPixelFormats.GetItem 메소드는, 지원 되고 있는 텍스쳐 포맷을 기술하는 DDPIXELFORMAT 형에 값을 설정한다. 열거되는 픽셀 포맷으로 DXT1, DXT2, DXT3, DXT4, 또는 DXT5 의 4 문자 코드 (FOURCCs)를 사용하는 경우, 디바이스는 그 포맷을 사용하는 압축 텍스쳐 표면으로부터 직접 텍스쳐를 얻을 수 있다. 이 경우,Direct3DDevice7.SetTexture 메소드를 호출해, Direct3D 로 압축 텍스쳐 표면을 직접 사용할 수 있다. 디바이스가 압축 텍스쳐 표면으로부터의 텍스쳐 처리를 지원 하지 않는 경우에서도, 텍스쳐 데이터를 압축 포맷 표면내에 저장 할 수 있다. 다만, 압축 텍스쳐를 텍스쳐로서 사용하기 전에, 지원 되는 포맷으로 변환하지 않으면 안 된다. DirectDraw 의 블리트 메소드의 DirectDrawSurface7.Blt 및 DirectDrawSurface7.BltFast 는, 압축 포맷화등 표준 RGBA 포맷에의 변환을 자동적으로 실행한다. 정보의 손실을 최소한으로 억제하려면 , 압축 포맷과 일치하는 목적지 픽셀 포맷을 선택하도록(듯이) 한다. 예를 들어, ARGB:1555 는 DXT1 의 목적지 포맷에는 적합하지만, DXT3 에는 ARGB:4444 가 적합하다. DXT3 에는 4 비트의 알파 정보가 포함되기 때문에 있다.


자동 텍스쳐 관리

텍스쳐 관리란, 요컨데, 어떤 시점에 있어 어느 텍스쳐가 렌더링에 필요한가를 판단해, 그러한 텍스쳐를 비디오 메모리에 확실히 로드하는 처리이다. 다른 알고리즘과 같이, 텍스쳐 관리 스킴도 그 복잡함은 다양하지만, 어떠한 어프로치로 텍스쳐 관리를 실시하는 경우여도, 이하에 나타내는 태스크가 중요하다.

  • 사용 가능한 텍스쳐 메모리의 양의 추적
  • 현시점에서 렌더링에 필요한 텍스쳐와 필요하지 않은 텍스쳐의 계산
  • 기존의 텍스쳐 표면 가운데, 다른 텍스쳐 화면에 재로드할 수 있는 텍스쳐 표면의 판단, 또 파기할 필요가 있는 표면, 및 새로운 텍스쳐 표면으로 옮겨놓을 필요가 있는 표면의 판단

종래는, Direct3D 어플리케이션 자체로 텍스쳐 관리를 실시할 필요가 있었다. DirectX 6.0 의 Direct3D 직접 모드로 도입된, 시스템에 의한 텍스쳐 관리에 의해, Direct3D 에서는 텍스쳐 관리가 효율적 또한 인텔리전트에 행해져 텍스쳐는 퍼포먼스 최적화를 위해서(때문에) 확실히 로드 된다 (Direct3D 가 관리하는 텍스쳐 표면을 "관리하의 텍스쳐" 라고 부르는 일도 있다).

텍스쳐 매니저는, least-recently-used (LRU) 알고리즘을 이용해, 삭제할 필요가 있는 텍스쳐를 판단한다. 이 알고리즘에서는, 텍스쳐의 최종 사용시를 나타내는 타임 스탬프를 이용해 텍스쳐를 추적한다. 메모리로부터 삭제하는 텍스쳐가 2 개 있는 경우, 텍스쳐의 우선도에 근거해 텍스쳐가 삭제된다. 2 개의 텍스쳐의 우선도가 같은 경우는, 최종 사용시가 새로운 (분)편의 텍스쳐가 삭제된다. 다만, 2 개의 텍스쳐로 타임 스탬프가 같은 경우는, 우선도의 낮은 텍스쳐가 먼저 삭제된다.

[C++]

텍스쳐 표면을 생성 하면 와, 그 자동 텍스쳐 관리를 요구한다. C++ 어플리케이션으로 관리하의 텍스쳐를 취득하려면 , 관련하는 DDSCAPS2 구조체의 dwCaps2 멤버에 DDSCAPS2_TEXTUREMANAGE 또는 DDSCAPS2_D3DTEXTUREMANAGE 플래그를 포함한 텍스쳐 표면을 생성 하는 것만으로 좋다. 다만, 텍스쳐의 생성 장소를 지정할 수 없다. 관리하의 텍스쳐를 생성 할 경우에는, DDSCAPS_SYSTEMMEMORY 또는 DDSCAPS_VIDEOMEMORY 플래그는 사용할 수 없다. 관리하의 텍스쳐를 생성 한 후,IDirect3DDevice7::SetTexture 메소드를 호출해, 그 관리하의 텍스쳐를 렌더링 디바이스의 텍스쳐 cascade의 스테이지로 설정할 수 있다.

텍스쳐 표면에 대해서 IDirectDrawSurface7::SetPriority 메소드를 호출해, 관리하의 텍스쳐에 우선도를 할당할 수가 있다.

[Visual Basic]

텍스쳐를 생성 할 경우에, 그 텍스쳐의 자동 텍스쳐 관리를 요구한다. Visual Basic 로부터 관리하의 텍스쳐를 취득하려면 , 관련하는 DDSCAPS2 형의 lCaps2 멤버에 DDSCAPS2_TEXTUREMANAGE 또는 DDSCAPS2_D3DTEXTUREMANAGE 플래그를 포함한 텍스쳐 표면을 생성 한다. 다만, 텍스쳐의 생성 장소를 지정할 수 없다. 관리하의 텍스쳐를 생성 할 경우에는, DDSCAPS_SYSTEMMEMORY 또는 DDSCAPS_VIDEOMEMORY 플래그는 사용할 수 없다. 관리하의 텍스쳐를 생성 한 후,Direct3DDevice7.SetTexture 메소드를 호출해, 그 관리하의 텍스쳐를 렌더링 디바이스의 텍스쳐 cascade의 스테이지로 설정할 수 있다.

텍스쳐 표면에 대해서 DirectDrawSurface7.SetPriority 메소드를 호출해, 관리하의 텍스쳐에 우선도를 할당할 수가 있다.

Direct3D 에서는, 필요에 따라서 텍스쳐를 비디오 메모리에 자동적으로 다운로드할 수 있다 (시스템은, 비로컬 비디오 메모리나 그 외의 요소가 사용 가능한지 어떤지에 의해, 관리하의 텍스쳐를 로컬 또는 비로컬 비디오 메모리에 캐쉬한다. 관리하의 텍스쳐가 캐쉬되는 장소는, 어플리케이션에 통지되지 않는다. 자동 텍스쳐 관리를 이용할 때에, 이 정보는 필요없다). 어플리케이션으로 사용하는 텍스쳐가 비디오 메모리에 들어가지 않을 정도(수록) 있는 경우, Direct3D 는 비디오 메모리로부터 낡은 텍스쳐를 삭제해, 새로운 텍스쳐용의 영역을 확보한다. 삭제한 텍스쳐를 재차 사용하는 경우, 시스템은 오리지날 시스템 메모리 텍스쳐 표면을 사용해, 텍스쳐를 비디오 메모리 캐쉬에 재로드한다. 텍스쳐의 재로드는, 어플리케이션의 퍼포먼스 정원않고인가이지만 영향을 주어 퍼포먼스의 저하는 피할 수 없다.

텍스쳐 표면을 블리트 또는 잠그는 것으로, 텍스쳐의 오리지날 시스템 메모리 카피를 동적으로 변경할 수 있다. "더러워진" 표면이 검출되었을 경우 (블리트의 완료 후, 또는 표면의 락 해제시), 텍스쳐 매니저는 텍스쳐의 비디오 메모리 카피를 자동적으로 갱신한다. 이 때의 퍼포먼스는, 삭제된 텍스쳐를 재로드하는 경우와 같다.

[C++]

게임에서 새로운 레벨로 옮길 때, 어플리케이션으로 비디오 메모리로부터 모든 관리하의 텍스쳐를 플래시 해야 할 때가 있다. IDirect3D7::EvictManagedTextures 메소드를 호출해, 모든 관리하의 텍스쳐를 삭제하도록(듯이) 명시적으로 요구할 수 있다. 이 메소드를 호출하면, 캐쉬되고 있는 로컬 또는 비로컬 비디오 메모리 텍스쳐가 Direct3D 에 의해 파기되지만, 오리지날 시스템 메모리 카피는 그대로 남는다.

[Visual Basic]

게임에서 새로운 레벨로 옮길 때, 어플리케이션으로 비디오 메모리로부터 모든 관리하의 텍스쳐를 플래시 해야 할 때가 있다. Direct3D7.EvictManagedTextures 메소드를 호출해, 모든 관리하의 텍스쳐를 삭제하도록(듯이) 명시적으로 요구할 수 있다. 이 메소드를 호출하면, 캐쉬되고 있는 로컬 또는 비로컬 비디오 메모리 텍스쳐가 Direct3D 에 의해 파기되지만, 오리지날 시스템 메모리 카피는 그대로 남는다.


텍스쳐 처리에 있어서의 하드웨어 제약

현재의 하드웨어로, Direct3D 인터페이스에 의해 가능하게 되는 기능을 모두 이용할 수 있다고는 할 수 없다. 프로그램으로 유저의 하드웨어를 테스트해, 렌더링 방법을 조정할 필요가 있다.

3D accelerator card의 상당수는, 블렌딩 유니트에의 인수로서 디퓨즈 반복값을 지원 하고 있지 않다. 그러나, 텍스쳐 블렌딩을 실행할 때, 프로그램으로 반복색데이터를 도입할 수 있다.

3D 하드웨어에 따라서는, 블렌딩 스테이지를 최초의 텍스쳐에 관련지을 수가 없는 경우도 있다. 이러한 어댑터의 경우, 어플리케이션에서는 현재 텍스쳐 세트의 2 번째 및 3 번째의 스테이지에서 블렌딩을 실행할 필요가 있다.

[C++]

현시점에서는 많은 하드웨어로 제약이 있기 (위해)때문에,IDirect3DDevice7 가 제공하는 멀티 텍스쳐 블렌딩 인터페이스에 의한 트라이 리니어 밉맵 보간을 실행할 수 있는 디스플레이 어댑터는 소수이다. 특히, D3DTSS_MIPFILTER 텍스쳐 스테이지 스테이트를 D3DTFP_LINEAR 로 설정할 수 있는 것은 거의 없다. 어플리케이션으로 멀티 패스 텍스쳐 블렌딩을 사용해 같은 이펙트를 얻는지, 넓게 지원 되고 있는 D3DTFP_POINT 밉맵 필터 모드를 사용 하면이야 있고.

[Visual Basic]

현시점에서는 많은 하드웨어로 제약이 있기 (위해)때문에, Visual Basic 의 Direct3DDevice7 클래스가 제공하는 멀티 텍스쳐 블렌딩 인터페이스에 의한 트라이 리니어 밉맵 보간을 실행할 수 있는 디스플레이 어댑터는 소수이다. 특히, D3DTSS_MIPFILTER 텍스쳐 스테이지 스테이트를 D3DTFP_LINEAR 로 설정할 수 있는 것은 거의 없다. 어플리케이션으로 멀티 패스 텍스쳐 블렌딩을 사용해 같은 이펙트를 얻는지, 넓게 지원 되고 있는 D3DTFP_POINT 밉맵 필터 모드를 사용 하면이야 있고.


깊이 버퍼

이 섹션에서는, 깊이 버퍼를 사용해 은선과 은면을 지우는 방법에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • 깊이 버퍼란
  • 깊이 버퍼의 사용
[C++]

Direct3D 직접 모드의 C++ 튜토리얼에서는, 깊이 버퍼의 사용 방법에 대한 추가 정보가 있다. 상세한 것에 대하여는, 「튜토리얼 2 : 깊이 버퍼를 추가한다 (C++)」를 참조할것.

[Visual Basic]

Direct3D 직접 모드의 Visual Basic 튜토리얼에서는, 깊이 버퍼의 사용 방법에 대한 추가 정보가 있다. 상세한 것에 대하여는, 「튜토리얼 2 : 깊이 버퍼를 추가한다 (Visual Basic)」를 참조할것.


깊이 버퍼란

z 버퍼 또는 w 버퍼로 불리는 깊이 버퍼란, Direct3D 로 사용하는 깊이 정보를 저장 하는 DirectDraw 표면이다. Direct3D 가 3D 신을 타겟 표면에 렌더링 하면 와, Attach 된 깊이 버퍼 표면의 메모리를 작업 공간으로서 사용해, 라스터화한 다각형의 픽셀이 서로 어떻게 서로 가리는지 를 판정할 수 있다. Direct3D 는, 오프 스크린 DirectDraw 표면을, 최종적인 컬러값을 기입하는 타겟으로서 사용한다. 렌더링 타겟 표면에 Attach 한 깊이 버퍼 표면은, 장면에서의 가시적 픽셀 각각의 「깊이」를 Direct3D 에 알리는 깊이 정보의 저장에 사용한다.

깊이 버퍼링을 유효하게 해 3D 신을 라스터화할 때, 렌더링 표면 위에의 각 점이 조사할 수 있다. 깊이 버퍼의 값은, 점의 z 좌표 또는 동차 w 좌표 (투영 공간의 점의 (x, y, z, w) 위치 좌표가) 일수 있다. z 값을 사용하는 깊이 버퍼는 「Z 버퍼」라고 불려 w 값을 사용하는 깊이 버퍼는 「W 버퍼」라고 불린다. 어느 쪽의 종류의 깊이 버퍼에도, 각각의 이점과 결점이 있지만, 이것에 대해서는 후술 한다.

테스트의 최초로, 깊이 버퍼의 깊이값을 장면에서 가능한 최대치에 세트 한다. 렌더링 표면 위에의 컬러값은, 배경의 컬러값 또는 그 점의 배경 텍스쳐의 컬러값에 세트 한다. 장면의 각 다각형을 조사해, 렌더링 표면 위에의 현재 좌표 (x, y)와 교차할지 어떨지를 확인한다. 교차하면, 현재점에서의 깊이값 (Z 버퍼의 z 좌표 또는 W 버퍼의 w 좌표)을 테스트해, 깊이 버퍼에 이미 저장 되고 있는 깊이값보다 작은지 어떤지를 확인한다. 다각형의 깊이값이 작으면, 그 값이 깊이 버퍼에 저장 되어 그 다각형으로부터의 컬러값이 렌더링 표면 위에의 현재점에 기입해진다. 그 점에서의 다각형의 깊이값이 크면, 리스트의 다음의 다각형이 조사할 수 있다. 다음의 그림에, 이 처리를 나타낸다.

[C++]

주 : 대부분의 어플리케이션에서는 이 기능을 사용하지 않지만, 깊이 버퍼에 들어가는 값과 렌더링 타겟 표면을 판정하기 위해서 Direct3D 가 사용하는 이 비교를 변경할 수 있다. 이것을 실시하려면 ,D3DRENDERSTATE_ZFUNC 렌더링 스테이트의 값을 변경하는 것.

[Visual Basic]

주 : 대부분의 어플리케이션에서는 이 기능을 사용하지 않지만, 깊이 버퍼에 들어가는 값과 렌더링 타겟 표면을 판정하기 위해서 Direct3D 가 사용하는 이 비교를 변경할 수 있다. 이것을 실시하려면 ,D3DRENDERSTATE_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 버퍼링만큼 넓지는 지원되어 있지 않다.

[C++]

DirectDraw 의 HEL 에서는, Direct3D 또는 그 외의 3D 렌더링 소프트웨어용의 깊이 버퍼를 생성 할 수 있다. HEL 는, 16 비트 깊이 버퍼를 지원 한다. 이 3D 가속기용의 DirectDraw 디바이스 드라이버에서는, DDSCAPS_ZBUFFER 플래그를 개시하고 있으므로, 디스플레이 메모리의 깊이 버퍼를 생성 할 수 있다. IDirect3D7::EnumZBufferFormats 메소드를 호출해, 지원 되고 있는 깊이 버퍼의 비트 깊이를 문의할 수가 있다.

Z 버퍼 표면을 어느 시점에서 생성 해도, 어플리케이션은, Direct3D 시스템을 슛다운 할 때까지 Z 버퍼에의 포인터를 보관 유지해야 한다. 프로그램에서는, 렌더링 표면을 릴리즈 하기 직전에 Z 버퍼 표면을 릴리즈 해야 한다.

[Visual Basic]

DirectDraw 의 HEL 에서는, Direct3D 또는 그 외의 3D 렌더링 소프트웨어용의 깊이 버퍼를 생성 할 수 있다. HEL 는, 16 비트 깊이 버퍼를 지원 한다. 이 3D 가속기용의 DirectDraw 디바이스 드라이버에서는, DDSCAPS_ZBUFFER 플래그를 개시하고 있으므로, 디스플레이 메모리의 깊이 버퍼를 생성 할 수 있다. Direct3D7.GetEnumZBufferFormats 메소드를 호출해, 지원 되고 있는 깊이 버퍼의 비트 깊이를 문의할 수가 있다. GetEnumZBufferFormats 메소드는, 깊이 버퍼용으로 지원 되고 있는 픽셀 포맷을 포함한 Direct3DEnumPixelFormats 클래스 오브젝트에의 참조를 돌려준다.

z 버퍼링에는, 렌더링 때에 오버헤드가 있다. Z 버퍼를 사용할때에, 렌더링을 최적화하기 위해서 사용할 수 있는 다양한 기술이 있다. 상세한 것에 대하여는, 「Z 버퍼의 퍼포먼스」를 참조할것.

주 : 깊이값의 실제의 해석은, 3D 렌더러에 따라서 다르다.


깊이 버퍼의 사용

이하의 주제에서는, 일반적인 깊이 버퍼의 사용 방법에 대해 설명한다.

  • 깊이 버퍼의 지원 상황의 문의
  • 깊이 버퍼의 생성
  • 깊이 버퍼링의 유효화
  • 깊이 버퍼의 클리어
  • 깊이 버퍼에의 쓰기 액세스의 변경
  • 깊이 버퍼 비교 함수의 변경
  • Z 바이어스의 사용

참조

깊이 버퍼란,깊이 버퍼를 추가하는 (C++),튜토리얼 2: 깊이 버퍼를 추가한다 (Visual Basic)


깊이 버퍼의 지원 상황의 문의

다른 기능에서도 같이이지만, 어플리케이션으로 사용하는 드라이버가 깊이 버퍼링을 지원 하고 있다고 결정해 걸리지 않는 것. 항상 드라이버의 기능을 조사할 필요가 있다. z 베이스의 깊이 버퍼링은 대부분의 디바이스로 지원 되고 있지만, w 베이스의 깊이 버퍼링은 일부의 디바이스로 밖에 지원되어 있지 않다 (깊이 버퍼링의 일반 정보에 대해서는, 「깊이 버퍼란」을 참조할것). 지원되어 있지 않은 스킴을 유효하게 하려고 하면(자), 드라이버는 다른 깊이 버퍼링에 의지했을 경우에 따라서는 모든 깊이 버퍼링을 무효로 해, 그 결과, 렌더링 후의 장면에 깊이 소트에 의한 부자연스러운 효과가 나타나는 일이 있다.

Direct3D 디바이스를 생성 하기 전에 어플리케이션으로 사용하는 디스플레이 디바이스에 대해 DirectDraw 에 조회하는 것으로, 깊이 버퍼의 지원을 조사할 수가 있다. DirectDraw 오브젝트로부터 깊이 버퍼링을 지원 하고 있다라는 보고가 있으면, 이 DirectDraw 오브젝트로부터 생성 하는 하드웨어 디바이스는 z 버퍼링을 지원 한다 (그러나, 이 드라이버가 w 버퍼링을 지원 할지 어떨지는 모른다).

[C++]

C++ 로 일반적인 깊이 버퍼링의 지원 상황을 문의하려면

  1. 어플리케이션으로 사용하는 디스플레이 디바이스에 대해서, DirectDraw 오브젝트의 IDirectDraw7::GetCaps 메소드를 호출해, 초기화한 DDCAPS 구조체를 파라미터로서 건네준다. 이 호출의 뒤,DDCAPS 구조체에 DirectDraw 의 하드웨어 및 에뮬레이션 기능에 대한 정보가 들어간다.
  2. 제 1 파라미터로서 건네준 구조체의 ddsCaps 멤버를 조사한다. 이 멤버 (DDSCAPS2 구조체)에 DDSCAPS_ZBUFFER 플래그가 포함되는 경우, 이 디바이스에서는 z 버퍼를 이용한 깊이 버퍼링을 지원 하고 있다.
[Visual Basic]

Visual Basic 로 일반적인 깊이 버퍼링의 지원 상황을 문의하려면

  1. 어플리케이션으로 사용하는 디스플레이 디바이스에 대해서, DirectDraw 오브젝트의 DirectDraw7.GetCaps 메소드를 호출해,DDCAPS 형의 변수를 파라미터로서 건네준다. 이 호출의 뒤,DDCAPS 구조체에 DirectDraw 의 하드웨어 및 에뮬레이션 기능에 대한 정보가 들어간다.
  2. 제 1 파라미터로서 건네준 변수의 ddsCaps 멤버를 조사한다. 이 멤버 (DDSCAPS2 형)에 DDSCAPS_ZBUFFER 플래그가 포함되는 경우, 이 디바이스에서는 z 버퍼를 이용한 깊이 버퍼링을 지원 하고 있다.

드라이버로 z 버퍼가 지원 되고 있는 것을 알면(자), 다음은 w 버퍼의 지원 상황을 조사할 수가 있다. z 버퍼는 모든 소프트웨어 래스터라이저로 지원 되고 있지만, w 버퍼는 레퍼런스 래스터라이저로 밖에 지원되어 있지 않다. 이것으로는, 실제의 어플리케이션에서는 거의 사용할 수 없다. 어플리케이션으로 사용하는 디바이스가 어떠한 종류에서도, w 베이스 깊이 버퍼링을 유효하게 하기 전에, w 버퍼의 지원 상황을 조사할 필요가 있다.

[C++]

C++ 어플리케이션으로 w 버퍼의 지원 상황을 조사하려면

  1. 디바이스를 생성 한 후 (HAL 또는 에뮬레이션),IDirect3DDevice7::GetCaps 메소드를 호출해, 초기화한 D3DDEVICEDESC7 구조체를 건네준다.
  2. 이 호출의 뒤, 프리미티브의 렌더링에 관한 드라이버의 지원의 정보가 dpcTriCaps 과 dpcLineCaps 멤버 (D3DPRIMCAPS 구조몸)에 들어간다.
  3. 이러한 구조체의 dwRasterCaps 멤버에 D3DPRASTERCAPS_WBUFFER 플래그가 포함되어 있는 경우, 드라이버는 해당의 프리미티브 종류에 대한 W 깊이 버퍼링을 지원 한다.
[Visual Basic]

Visual Basic 로 w 버퍼의 지원 상황을 조사하려면

  1. 디바이스 (HAL 또는 에뮬레이션)를 생성 한 후,Direct3DDevice7.GetCaps 메소드를 호출해,D3DDEVICEDESC7 형의 변수를 파라미터로서 건네준다.
  2. 이 호출의 뒤,dpcTriCaps 및 dpcLineCaps 멤버 (D3DPRIMCAPS 형)에, 프리미티브의 렌더링에 관한 드라이버에서의 지원 정보가 들어간다.
  3. dpcTriCaps 및 dpcLineCaps 의 lRasterCaps 멤버에 D3DPRASTERCAPS_WBUFFER 플래그가 포함되어 있는 경우, 드라이버에서는 그 프리미티브의 종류에 대해서 w 베이스 깊이 버퍼링을 지원 하고 있다.


깊이 버퍼의 생성

보통, 어플리케이션의 기동 순서중에 깊이 버퍼를 생성 한 다음에, 렌더링용으로 Direct3D 디바이스 오브젝트를 생성 한다. 다음의 순서를 실행해, 깊이 버퍼 표면을 생성 해, 렌더링 타겟 표면에 Attach 한다.

[C++]

C++ 어플리케이션으로 깊이 버퍼를 생성 하려면

  1. IDirect3D7::EnumZBufferFormats 메소드를 호출해, 디바이스가 지원 하는 깊이 버퍼 픽셀 포맷을 판단한다.
  2. DDSURFACEDESC2 구조체를 준비해, 렌더링 타겟 표면의 크기에 적합해, DDSCAPS_ZBUFFER 플래그를 포함해, 지원 되는 깊이 버퍼 픽셀 포맷 (스텝 1 으로 취득)을 사용하는 DirectDraw 표면을 기술한다.
  3. 어플리케이션으로 사용하는 렌더링 디바이스의 종류에 응해, 비디오 메모리 또는 시스템 메모리의 어딘가에 표면을 생성 한다. ( 「주의」를 참조할것.
  4. IDirectDrawSurface7::AddAttachedSurface 메소드를 사용해, 깊이 버퍼 표면을 렌더링 표면에 Attach 한다.

깊이 버퍼 표면을 생성 해, 렌더링 타겟 표면에 Attach 한 후,IDirect3D7::CreateDevice 메소드를 호출해 렌더링 타겟 표면과 그 깊이 버퍼를 사용하는 렌더링 디바이스를 생성 한다.

어플리케이션으로 하드웨어 드라이버 (HAL 디바이스)를 사용할때는, DDSCAPS_VIDEOMEMORY 표면 기능을 이용해 비디오 메모리에 깊이 버퍼를 생성 한다. 소프트웨어 에뮬레이션 드라이버 (MMX 또는 RGB 디바이스)를 사용할때는, DDSCAPS_SYSTEMMEMORY 표면 기능을 이용해 시스템 메모리에 깊이 버퍼를 생성 한다. 해당하는 종류의 메모리로 깊이 버퍼의 생성이 실패했을 경우,CreateDevice 메소드도 실패한다.

주 : 넓게 사용되고 있는 일부의 하드웨어에서는, 렌더링 타겟 및 깊이 버퍼 표면으로 같은 비트 깊이를 사용할 필요가 있다. 그러한 하드웨어에서는, 어플리케이션으로 16 비트의 렌더링 타겟 표면을 사용하는 경우는, Attach 하는 깊이 버퍼도 16 비트가 아니면 안된다. 32 비트의 렌더링 타겟 표면이면, 32 비트의 깊이 버퍼가 아니면 안된다. 8 비트의 깊이 버퍼는, 필요에 따라서 스텐실 버퍼링에 사용할 수 있다.

어플리케이션이 동작하는 하드웨어에 이러한 요건이 있어, 어플리케이션이 이것을 채우지 않은 경우, 비대응 표면을 사용하는 렌더링 디바이스를 생성 하려고 하면(자) 실패한다. DirectDraw 메소드의 IDirectDraw7::GetDeviceIdentifier 를 사용해, 이 제한이 있는 하드웨어를 특정할 수 있다.

[Visual Basic]

Visual Basic 어플리케이션으로 깊이 버퍼를 생성 하려면

  1. Direct3D7.GetEnumZBufferFormats 메소드를 호출해, 지원 되고 있는 깊이 버퍼 포맷을 열거할 수 있는 Direct3DEnumPixelFormats 오브젝트에의 참조를 취득한다. 디바이스로 지원 되고 있는 깊이 버퍼 픽셀 포맷에 대해, 이 열거 오브제크에 문의한다.
  2. DDSURFACEDESC2 형을 준비해, 렌더링 타겟 표면의 크기와 일치해, DDSCAPS_ZBUFFER 플래그를 포함해, 지원 되는 깊이 버퍼 픽셀 포맷 (순서 2 로 취득)을 사용하는 DirectDraw 표면을 기술한다.
  3. 어플리케이션으로 사용하는 렌더링 디바이스의 종류에 응해, 비디오 메모리 또는 시스템 메모리의 어딘가에 표면을 생성 한다. ( 「주의」를 참조할것.
  4. DirectDrawSurface7.AddAttachedSurface 메소드를 사용해, 깊이 버퍼 표면을 렌더링 표면에 Attach 한다.

깊이 버퍼 표면을 생성 해, 렌더링 타겟 표면에 Attach 한 후,Direct3D7.CreateDevice 메소드를 호출해, 렌더링 타겟 표면과 그 깊이 버퍼를 사용하는 렌더링 디바이스를 생성 한다.

어플리케이션으로 하드웨어 드라이버 (HAL 디바이스)를 사용할때는, DDSCAPS_VIDEOMEMORY 표면 기능을 이용해 비디오 메모리에 깊이 버퍼를 생성 한다. 소프트웨어 에뮬레이션 드라이버 (MMX 또는 RGB 디바이스)를 사용할때는, DDSCAPS_SYSTEMMEMORY 표면 기능을 이용해 시스템 메모리에 깊이 버퍼를 생성 한다. 해당하는 종류의 메모리로 깊이 버퍼의 생성이 실패했을 경우,CreateDevice 메소드도 실패한다.

주 : 넓게 사용되고 있는 일부의 하드웨어에서는, 렌더링 타겟 및 깊이 버퍼 표면으로 같은 비트 깊이를 사용할 필요가 있다. 그러한 하드웨어에서는, 어플리케이션으로 16 비트의 렌더링 타겟 표면을 사용하는 경우는, Attach 하는 깊이 버퍼도 16 비트가 아니면 안된다. 32 비트의 렌더링 타겟 표면이면, 32 비트의 깊이 버퍼가 아니면 안된다. 8 비트의 깊이 버퍼는, 필요에 따라서 스텐실 버퍼링에 사용할 수 있다.

어플리케이션이 동작하는 하드웨어에 이러한 요건이 있어, 어플리케이션이 이것을 채우지 않은 경우, 비대응 표면을 사용하는 렌더링 디바이스를 생성 하려고 하면(자) 실패한다. DirectDraw 메소드의 DirectDraw7.GetDeviceIdentifier 및 관련하는 오브젝트 (DirectDrawIdentifier )를 사용해, 이 제한이 있는 하드웨어를 특정할 수 있다.


깊이 버퍼링의 유효화

[C++]

깊이 버퍼를 생성 한 후 ( 「깊이 버퍼의 생성」으로 설명),IDirect3DDevice7::SetRenderState 메소드를 호출해 깊이 버퍼링을 유효하게 한다. D3DRENDERSTATE_ZENABLE 렌더링 스테이트를 설정해 깊이 버퍼를 유효하게 한다. z 버퍼링을 유효하게 하려면 D3DZB_TRUE (또는 TRUE)를, w 버퍼링을 유효하게 하려면 D3DZB_USEW 를, 깊이 버퍼링을 무효로 하려면 D3DZB_FALSE (또는 FALSE)를 각각 설정한다.

주 : w 버퍼링을 사용하려면 , 어플리케이션으로 Direct3D 트랜스 폼 파이프라인을 사용하지 않는 경우여도, 대응하는 투영 행렬을 설정해야 한다. 적절한 투영 행렬의 설정에 대해서는, 「W 버퍼에 유효한 투영 행렬」을 참조할것 ( 「투영 트랜스 폼이란」으로 설명하는 투영 행렬은 적절한 것이다).

[Visual Basic]

깊이 버퍼를 생성 한 후 ( 「깊이 버퍼의 생성」으로 설명),Direct3DDevice7.SetRenderState 메소드를 호출해 깊이 버퍼링을 유효하게 한다. D3DRENDERSTATE_ZENABLE 렌더링 스테이트를 설정해 깊이 버퍼링을 유효하게 한다. z 버퍼링을 유효하게 하려면 CONST_D3DZBUFFERTYPE 열거의 D3DZB_TRUE 멤버를, w 버퍼링을 유효하게 하려면 D3DZB_USEW 를, 깊이 버퍼링을 무효로 하려면 D3DZB_FALSE 를 각각 설정한다.

주 : w 버퍼링을 사용하려면 , 어플리케이션으로 Direct3D 변환 파이프라인을 사용하지 않는 경우여도, 대응하는 투영 행렬을 설정해야 한다. 적절한 투영 행렬의 설정에 대해서는, 「W 버퍼에 유효한 투영 행렬」을 참조할것 ( 「투영 트랜스 폼이란」으로 설명하는 투영 행렬은 적절한 것이다).


깊이 버퍼의 클리어

[C++]

많은 C++ 어플리케이션에서는, 새로운 프레임을 렌더링 하기 전에 깊이 버퍼를 클리어 한다. IDirect3DDevice7::Clear 메소드를 호출하는 것으로, Direct3D 로 깊이 버퍼를 명시적으로 클리어 할 수 있다. Clear 메소드에서는,dvZ 파라미터에 임의의 깊이값을 지정할 수 있다.

DirectDraw 를 사용해 깊이 버퍼를 클리어 할 수도 있다. 이것을 클리어 하려면 , 깊이 버퍼 표면의 IDirectDrawSurface7::Blt 메소드를 호출한다. DDBLT_DEPTHFILL 플래그는, 블리트에 의해 깊이 버퍼를 클리어 하는 것을 나타낸다. 이 플래그를 지정 하면나무는,IDirectDrawSurface7::Blt 메소드에 건네주는 DDBLTFX 구조체를 초기화해, 그 dwFillDepth 멤버를 필요한 깊이로 설정해야 한다.

3D 가속기용의 DirectDraw 디바이스 드라이버가 하드웨어에서의 깊이 버퍼의 클리어를 지원 하고 있는 경우, 그 드라이버는 DDCAPS_BLTDEPTHFILL 플래그를 보고해, DDBLT_DEPTHFILL 블리트를 처리해야 한다. 깊이 매입 블리트의 목적지 표면은, 깊이 버퍼 표면이 아니면 안된다.

[Visual Basic]

많은 Visual Basic 어플리케이션에서는, 새로운 프레임을 렌더링 하기 전에 깊이 버퍼를 클리어 한다. Direct3DDevice7.Clear 메소드를 호출하는 것으로, Direct3D 로 깊이 버퍼를 명시적으로 클리어 할 수 있다. Clear 메소드에서는,z 파라미터에 임의의 깊이값을 지정할 수 있다.

DirectDraw 를 사용해 깊이 버퍼를 클리어 할 수도 있다. 이것을 클리어 하려면 , 깊이 버퍼 표면의 DirectDrawSurface7.Blt 메소드를 호출한다. DDBLT_DEPTHFILL 플래그는, 블리트에 의해 깊이 버퍼를 클리어 하는 것을 나타낸다. 이 플래그를 지정 하면나무는,DirectDrawSurface7.Blt 메소드에게 건네지는 DDBLTFX 형이 그 lFill 멤버를 필요한 깊이로 설정한다.

3D 가속기용의 DirectDraw 디바이스 드라이버가 하드웨어에서의 깊이 버퍼의 클리어를 지원 하고 있는 경우, 그 드라이버는 DDCAPS_BLTDEPTHFILL 플래그를 보고해, DDBLT_DEPTHFILL 블리트를 처리해야 한다. 깊이 매입 블리트의 목적지 표면은, 깊이 버퍼 표면이 아니면 안된다.


깊이 버퍼에의 쓰기 액세스의 변경

디폴트에서는, Direct3D 시스템은 깊이 버퍼에의 쓰기가 용서되고 있다. 대부분의 어플리케이션에서는 깊이 버퍼에의 쓰기를 유효하게 한채로 있지만, Direct3D 시스템에 의한 깊이 버퍼에의 쓰기를 금지하는 것에 의해, 특수 효과를 생성할 수가 있다.

[C++]

C++ 로 깊이 버퍼에의 쓰기를 무효로 하려면 ,dwRenderStateType 파라미터를 D3DRENDERSTATE_ZWRITEENABLE 로 설정해,dwRenderState 파라미터를 0 으로 설정해 IDirect3DDevice7::SetRenderState 메소드를 호출한다.

[Visual Basic]

Visual Basic 어플리케이션으로 깊이 버퍼에의 쓰기를 무효로 하려면 ,state 파라미터를 D3DRENDERSTATE_ZWRITEENABLE 로 설정해,renderstate 파라미터를 0 으로 설정해 Direct3DDevice7.SetRenderState 메소드를 호출한다.


깊이 버퍼 비교 함수의 변경

[C++]

디폴트에서는, 렌더링 표면의 깊이 테스트를 실시할 때, Direct3D 시스템은, 각 점에 대응하는 깊이값 (z 또는 w)이 깊이 버퍼의 기존의 값보다 작은 경우, 렌더링 타겟 표면을 갱신한다. C++ 어플리케이션으로, 시스템에 의한 깊이값의 비교 방법을 변경하려면 ,dwRenderStateType 파라미터를 D3DRENDERSTATE_ZFUNC 로 설정해 IDirect3DDevice7::SetRenderState 메소드를 호출한다. dwRenderState 파라미터에는,D3DCMPFUNC 열거형의 값의 어느쪽이든을 설정한다.

[Visual Basic]

디폴트에서는, 렌더링 표면의 깊이 테스트를 실시할 때, Direct3D 시스템은, 각 점에 대응하는 깊이값 (z 또는 w)이 깊이 버퍼의 기존의 값보다 작은 경우, 렌더링 타겟 표면을 갱신한다. Visual Basic 어플리케이션으로, 시스템에 의한 깊이값의 비교 방법을 변경하려면 ,state 파라미터를 D3DRENDERSTATE_ZFUNC 로 설정해 Direct3DDevice7.SetRenderState 메소드를 호출한다. renderstate 파라미터에는,CONST_D3DCMPFUNC 열거의 값의 어느쪽이든을 설정한다.


Z 바이어스의 사용

3D 공간에서 동일 평면상에 있는 다각형은, 각각의 다각형에 Z 바이어스를 추가하는 것으로, 마치 동일 평면상에 없게 표시할 수가 있다. 이 기술은, 장면내의 그림자를 올바르게 표시하기 위해서 사용되는 것이 많다. 예를 들어, 벽위에의그림자의 깊이값이 벽의 깊이값과 같게 될 가능성이 있다. 최초로 벽을 렌더링 해, 다음에 그림자를 렌더링 하면, 그림자가 안보이는지, 또는 깊이에 의한 부자연스러운 효과가 보인다. 동일 평면상의 오브젝트의 렌더링순서를 반대로 하면, 이것과는 역의 이펙트를 얻을 수 있지만, 깊이에 의한 부자연스러운 효과가 남은채로 있는 것이 많다.

[C++]

C++ 어플리케이션에서는, 동일 평면상의 다각형 세트를 렌더링 할 때에 시스템이 사용하는 z 값에 바이어스를 추가하는 것으로, 동일 평면상의 다각형을 올바르게 렌더링 할 수 있다. z 바이어스를 다각형 세트에 추가하려면 , 렌더링의 직전에 IDirect3DDevice7::SetRenderState 메소드를 호출한다. 이 때,dwRenderStateType 파라미터를 D3DRENDERSTATE_ZBIAS 로 설정해,dwRenderState 파라미터를 0 으로 16 을 포함한 0 ~ 16 의 값으로 설정한다. z 바이어스값이 높을 정도(수록), 동일 평면상외의 다각형과 함께 표시 하면 와, 렌더링 하는 다각형이 보일 가능성이 높아진다.

[Visual Basic]

Visual Basic 어플리케이션에서는, 동일 평면상의 다각형 세트를 렌더링 할 때에 시스템이 사용하는 z 값에 바이어스를 추가하는 것으로, 동일 평면상의 다각형을 올바르게 렌더링 할 수 있다. z 바이어스를 다각형 세트에 추가하려면 , 렌더링의 직전에 Direct3DDevice7.SetRenderState 메소드를 호출한다. 이 때, 제 1 파라미터를 D3DRENDERSTATE_ZBIAS 로 설정해, 제 2 파라미터를 0 으로 16 을 포함한 0 ~ 16 의 값으로 설정한다. z 바이어스값이 높을 정도(수록), 동일 평면상외의 다각형과 함께 표시 하면 와, 렌더링 하는 다각형이 보일 가능성이 높아진다.


스텐실 버퍼

이 섹션에서는, 스텐실 버퍼의 목적과 사용 방법에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • 스텐실 버퍼란
  • 스텐실 버퍼의 동작
  • 스텐실 버퍼의 커스터마이즈


스텐실 버퍼란

스텐실 버퍼는, 렌더링 타겟 표면의 픽셀마다의 드로잉(Drawing)를 유효 또는 무효로 한다. 이 버퍼의 가장 기본적인 레벨에서는, 어플리케이션이 렌더링 한 화면의 부분을 마스크로 가리는 것이 가능하게 되어, 그 화면이 표시되지 않는다. 어플리케이션은 디조르브, 십-링, 및 아웃 라이닝등의 특수 효과를 위해서(때문에) 스텐실 버퍼를 사용하는 것이 많다. 상세한 것에 대하여는, 「스텐실 버퍼 기술」을 참조할것.

[C++]

스텐실 버퍼 정보는, Z 버퍼 데이터에 파묻히고 있다. IDirect3D7::EnumZBufferFormats 메소드를 호출해, 유저의 하드웨어가 스텐실 버퍼를 지원 하고 있을지 어떨지를 조사할 수가 있다. 이 메소드는, 깊이 버퍼 포맷을 DDPIXELFORMAT 구조체로 어플리케이션에 건네준다. 관련 정보는,dwZBufferBitDepth,dwStencilBitDepth,dwZBitMask, 및 dwStencilBitMask 멤버에 포함되어 있다.

디바이스에서의 스텐실 버퍼 제한을 조사하려면 , 지원 되고 있는 스텐실 버퍼 처리에 대해 D3DDEVICEDESC7 구조체의 dwStencilCaps 멤버에 문의한다.

[Visual Basic]

스텐실 버퍼 정보는, Z 버퍼 데이터에 파묻히고 있다. 어플리케이션에서는,Direct3D7.GetEnumZBufferFormats 메소드를 호출해, 유저의 하드웨어가 스텐실 버퍼를 지원 하고 있을지 어떨지를 조사해 다음에, 이 메소드가 돌려주는 Direct3DEnumPixelFormats 오브젝트를 사용해, 지원 되고 있는 각 깊이 버퍼 픽셀 포맷에 대한 정보를 취득한다. Direct3DenumPixelFormats.GetItem 메소드는, 각각 DDPIXELFORMAT 형으로 깊이 버퍼 포맷을 취득한다. 관련 정보는,lZBufferBitDepth,lStencilBitDepth,lZBitMask, 및 lStencilBitMask 멤버에 포함되어 있다.

디바이스에서의 스텐실 버퍼 제한을 조사하려면 , 지원 되고 있는 스텐실 버퍼 처리에 대해 D3DDEVICEDESC7 형의 lStencilCaps 멤버에 문의한다.


스텐실 버퍼의 동작

[C++]

Direct3D 는, 스텐실 버퍼의 내용을 픽셀 마다 조사한다. 스텐실 버퍼의 대응하는 값, 스텐실 참조값, 및 스텐실 마스크값을 사용해, 타겟 표면의 각 픽셀에 대한 테스트를 실시한다. 테스트에 패스 하면, Direct3D 는 액션을 실행한다. 이 테스트는 다음의 순서로 실행된다.

  1. 스텐실 참조값과 스텐실 마스크의 AND 를 취한다.
  2. 현재 픽셀에 대한 스텐실 버퍼값과 스텐실 마스크의 AND 를 취한다.
  3. 비교 함수를 사용해, 순서 1 으로 순서 2 의 결과를 비교한다.

의사 코드로 기술 하면, 이러한 순서는 다음과 같이 된다.

(StencilRef & StencilMask) CompFunc (StencilBufferValue & StencilMask)

여기서, StencilBufferValue 는, 현재 픽셀에 대한 스텐실 버퍼의 내용이다. 이 의사 코드에서는, & 기호는논리적연산자를 나타내고 있다. StencilMask 는 스텐실 마스크, StencilRef 는 스텐실 참조값을 나타내고 있다. CompFunc 는 비교 함수이다.

이 스텐실 테스트에 패스 하면, 현재 픽셀은 타겟 표면에 기입해지지만, 실패했을 경우는 무시된다. 디폴트의 비교 처리는, 각 비트 조작의 결과에 관계없이, 픽셀을 기입하는 것이다 (D3DCMP_ALWAYS). 이 동작을 변경하려면 , 희망의 비교 함수를 지정하는 D3DCMPFUNC 열거형의 멤버의 어느쪽이든을 건네주어,D3DRENDERSTATE_STENCILFUNC 렌더링 스테이트의 값을 변경한다.

[Visual Basic]

Direct3D 는, 스텐실 버퍼의 내용을 픽셀 마다 조사한다. 스텐실 버퍼의 대응하는 값, 스텐실 참조값, 및 스텐실 마스크값을 사용해, 타겟 표면의 각 픽셀에 대한 테스트를 실시한다. 테스트에 패스 하면, Direct3D 는 액션을 실행한다. 이 테스트는 다음의 순서로 실행된다.

  1. 스텐실 참조값과 스텐실 마스크의 AND 를 취한다.
  2. 현재 픽셀에 대한 스텐실 버퍼값과 스텐실 마스크의 AND 를 취한다.
  3. 비교 함수를 사용해, 순서 1 으로 순서 2 의 결과를 비교한다.

의사 코드로 기술 하면, 이러한 순서는 다음과 같이 된다.

(StencilRef And StencilMask) CompFunc (StencilBufferValue And StencilMask)

여기서, StencilBufferValue 는, 현재 픽셀에 대한 스텐실 버퍼의 내용이다. StencilMask 는 스텐실 마스크, StencilRef 는 스텐실 참조값을 나타내고 있다. CompFunc 는 비교 함수이다.

이 스텐실 테스트에 패스 하면, 현재 픽셀은 타겟 표면에 기입해지지만, 실패했을 경우는 무시된다. 디폴트의 비교 처리는, 각 비트 조작의 결과에 관계없이, 픽셀을 기입하는 것이다 (D3DCMP_ALWAYS). 이 동작을 변경하려면 ,D3DRENDERSTATE_STENCILFUNC 렌더링 스테이트의 값을 변경해, 희망의 비교 함수를 지정하는 CONST_D3DCMPFUNC 열거의 멤버의 어느쪽이든을 건네준다.


스텐실 버퍼의 커스터마이즈

어플리케이션에서는, 스텐실 버퍼의 처리를 커스터마이즈 할 수 있다. 어플리케이션에서는, 비교 함수, 스텐실 마스크, 및 스텐실 참조값을 설정할 수 있다. 또, 스텐실 테스트에 패스했을 경우 또는 실패했을 경우에 실행하는 Direct3D 의 처리를 제어할 수도 있다. 상세한 것에 대하여는, 「스텐실 버퍼 스테이트」를 참조할것.


버텍스 버퍼

이 섹션에서는, Direct3D 어플리케이션에 대해 버텍스 버퍼를 이해해 사용하는데 필요한 개념을 설명한다. 설명하는 주제는 다음과 같다.

  • 버텍스 버퍼란
  • 버텍스 버퍼의 기술
  • 디바이스의 종류와 버텍스 처리의 요건
  • 버텍스 버퍼의 사용


버텍스 버퍼란

[C++]

버텍스 버퍼란,IDirect3DVertexBuffer7 인터페이스로 나타내지는, 버텍스 데이터를 포함한 단순한 메모리 버퍼이다. 버텍스 버퍼는, 트랜스 폼 끝난 버텍스, 트랜스폼 되지 않은의 버텍스, 라이팅 끝난 버텍스, 라이팅 계산 되지 않은의 버텍스 등,IDirect3DDevice7 인터페이스의 버텍스 버퍼 렌더링 메소드로 렌더링 가능한 모든 종류의 버텍스를 포함할 수가 있다. 버텍스 버퍼내의 버텍스를 처리해, 트랜스 폼, 라이팅, 클리핑 플래그의 생성등의 처리를 실행할 수 있다 (트랜스 폼은 항상 실행된다).

[Visual Basic]

버텍스 버퍼란,Direct3DVertexBuffer7 클래스에서 나타내지는, 버텍스 데이터를 포함한 단순한 메모리 버퍼이다. 버텍스 버퍼는, 트랜스 폼 끝난 버텍스, 트랜스폼 되지 않은의 버텍스, 라이팅 끝난 버텍스, 라이팅 계산 되지 않은의 버텍스 등,Direct3DDevice7 클래스의 버텍스 버퍼 렌더링 메소드로 렌더링 가능한 모든 종류의 버텍스를 포함할 수가 있다. 버텍스 버퍼내의 버텍스를 처리해, 트랜스 폼, 라이팅, 클리핑 플래그의 생성등의 처리를 실행할 수 있다 (트랜스 폼은 항상 실행된다).

버텍스 버퍼는 유연해서, 트랜스 폼 된 지오메트리를 재사용하기 위한 이상적인 스테이지 포인트가 된다. 단일의 버텍스 버퍼를 생성 해, 버텍스를 트랜스 폼, 라이팅을 적용, 및 그 버텍스 버퍼에 버텍스를 잘라내, 비록 인타리브 된 렌더링 스테이트가 변화했을 경우에서도, 장면의 모델을 몇번도 재트랜스 폼 하지 않고 렌더링 할 수 있다. 이것은, 멀티 텍스쳐를 사용하는 모델의 렌더링에 대해 매우 유용하다. 지오메트리를 한 번 트랜스 폼 하면, 요구된 텍스쳐의 변경에 맞추어 인타리브 해, 필요에 따라서 그 일부를 렌더링 할 수 있다. 버텍스를 처리한 다음에 변경한 렌더링 스테이트는, 다음에 버텍스를 처리할 경우에 유효하게 된다. 상세한 것에 대하여는, 「버텍스의 처리」를 참조할것.

버텍스 버퍼의 지오메트리를 최적화하면, 버텍스 조작과 렌더링에 대해 최고의 퍼포먼스를 얻을 수 있다. 상세한 것에 대하여는, 「버텍스 버퍼의 최적화」를 참조할것.

[C++]

주 : 내부적으로는, 버텍스 버퍼는, DirectDrawSurface 오브젝트를 메모리 메니지먼트 서비스에 사용한다. 그 결과, 버텍스 버퍼 메모리에 액세스 하는 의미들은, DirectDrawSurface 오브젝트의 의미들에 유사한다. 실제,IDirect3DVertexBuffer7::Lock 메소드는,IDirectDrawSurface7::Lock 메소드와 같은 플래그를 받는다. 상세한 것에 대하여는, 「버텍스 버퍼의 내용에의 액세스」를 참조할것.

[Visual Basic]

주 : 내부적으로는, 버텍스 버퍼는, DirectDrawSurface 오브젝트를 메모리 메니지먼트 서비스에 사용한다. 그 결과, 버텍스 버퍼 메모리에 액세스 하는 의미들은, DirectDrawSurface 오브젝트의 의미들에 유사한다. 실제,Direct3DVertexBuffer7.Lock 메소드는,DirectDrawSurface7.Lock 메소드와 같은 플래그를 받는다. 상세한 것에 대하여는, 「버텍스 버퍼의 내용에의 액세스」를 참조할것.


버텍스 버퍼의 기술

[C++]

버텍스 버퍼의 기술은, 능력에 대해 실시한다. 버텍스 버퍼는, 시스템 메모리내에만 존재할 수 있는지, 쓰기 조작인 만큼 사용되는지, 버텍스 버퍼가 포함할 수가 있는 버텍스의 종류와 수, 버텍스 버퍼가 생성 되고 나서 최적화되었는지 어떠했는지 등을 기술한다. 이러한 특성은 모두 D3DVERTEXBUFFERDESC 구조체안에 보관 유지된다.

[Visual Basic]

버텍스 버퍼의 기술은, 능력에 대해 실시한다. 버텍스 버퍼는, 시스템 메모리내에만 존재할 수 있는지, 쓰기 조작인 만큼 사용되는지, 버텍스 버퍼가 포함할 수가 있는 버텍스의 종류와 수, 버텍스 버퍼가 생성 되고 나서 최적화되었는지 어떠했는지 등을 기술한다. 이러한 특성은 모두 D3DVERTEXBUFFERDESC 형에 보관 유지된다.

버텍스 버퍼의 기술은, 버텍스 버퍼의 생성 방법을 시스템에 알리거나 또는 기존의 버퍼의 생성 방법 (혹은, 버퍼가 생성 된 이후 최적화되었는지 어떠했는지)을 어플리케이션에 알린다. 새로운 버텍스 버퍼를 생성 하려면 , 완전한 기술을 지정해야 한다. 또, 하늘의 기술 구조체를 건네주면(자), 이전 생성 한 버텍스 버퍼의 능력이 시스템에 의해 기입된다. 이러한 태스크의 상세한 것에 대하여는, 「버텍스 버퍼의 생성」 및 「버텍스 버퍼의 기술의 취득」을 참조할것.

[C++]

대부분의 DirectX 구조체에 공통의 dwSize 멤버는, 구조체 버젼의 식별로 사용되기 (위해)때문에, 어느 메소드로 구조체를 사용하는 경우에서도, 우선, 이 멤버를 구조체 사이즈로 설정해야 한다. dwCaps 구조체 멤버는, 일반적인 능력 플래그를 포함한다. D3DVBCAPS_SYSTEMMEMORY 플래그는, 시스템이 버텍스 버퍼를 시스템 메모리내에 생성 하는 (또는 생성이 끝난 상태이다) 일을 나타낸다. 어플리케이션으로 소프트웨어 렌더링 디바이스 또는 HAL 디바이스 (IID_IDirect3DHALDevice)를 사용하는 경우는, 명시적으로 시스템 메모리 버텍스 버퍼를 생성 한다. 그렇지 않은 경우는, 플래그를 생략 해, 최선의 생성 장소의 판단을 시스템에 맡긴다. 명시적인 시스템 메모리 버텍스 버퍼의 상세한 것에 대하여는, 「디바이스의 종류와 버텍스 처리의 요건」을 참조할것.

dwCaps 에 D3DVBCAPS_WRITEONLY 플래그를 지정 하면, 버텍스 버퍼 메모리를 쓰기 조작에게만 사용하는 것이 시스템에 통지된다. 이것에 의해 드라이버는, 처리와 렌더링을 가능한 한 고속으로 하는 최선의 메모리 위치 좌표에 버텍스 데이터를 배치하는 것을 그만둔다. 이 플래그를 사용하는 버텍스 버퍼로부터의 읽기에서는, 메모리 액세스 시간이 매우 저속이 되는 일이 있다. D3DVBCAPS_WRITEONLY 플래그를 사용하지 않으면 일부의 처리와 렌더링의 속도를 희생하지만, 읽기 조작이 비효율적이 되는 위치 좌표에 드라이버가 데이터를 두는 것은 적게 된다. 플래그를 아무것도 지정하지 않으면 어플리케이션은 버텍스 버퍼내에서 데이터의 읽기 조작과 쓰기 조작을 실시하는 것이라고 보여진다.

주 : D3DVBCAPS_OPTIMIZED 플래그는, 버텍스 버퍼의 생성시에는 사용되지 않는다. 시스템은, 버텍스 버퍼를 최적화할 경우에 이 능력 플래그를 설정한다.

마지막 2 개의 D3DVERTEXBUFFERDESC 구조체 멤버는, 그 외의 능력을 기술한다. dwFVF 멤버에는, 버퍼에 포함할 수가 있는 버텍스의 종류를 식별하는유연한 버텍스 포맷 플래그의 편성이 포함된다. 버텍스 버퍼의 용량은,dwNumVertices 멤버로 지정하는, 버텍스 버퍼에 거둘 수가 있는 버텍스의 합계수에 의해 측정된다.

[Visual Basic]

lCaps 멤버는, 일반적인 능력 플래그를 포함한다. D3DVBCAPS_SYSTEMMEMORY 플래그는, 시스템이 버텍스 버퍼를 시스템 메모리내에 생성 하는 (또는 생성이 끝난 상태이다) 일을 나타낸다. 어플리케이션으로 소프트웨어 렌더링 디바이스 또는 HAL 디바이스 (IID_IDirect3DHALDevice)를 사용하는 경우는, 명시적으로 시스템 메모리 버텍스 버퍼를 생성 한다. 그렇지 않은 경우는, 플래그를 생략 해, 최선의 생성 장소의 판단을 시스템에 맡긴다. 명시적인 시스템 메모리 버텍스 버퍼의 상세한 것에 대하여는, 「디바이스의 종류와 버텍스 처리의 요건」을 참조할것.

lCaps 에 D3DVBCAPS_WRITEONLY 플래그를 지정 하면, 버텍스 버퍼 메모리를 쓰기 조작에게만 사용하는 것이 시스템에 통지된다. 이것에 의해 드라이버는, 처리와 렌더링을 가능한 한 고속으로 하는 최선의 메모리 위치 좌표에 버텍스 데이터를 배치하는 것을 그만둔다. 이 플래그를 사용하는 버텍스 버퍼로부터의 읽기에서는, 메모리 액세스 시간이 매우 저속이 되는 일이 있다. D3DVBCAPS_WRITEONLY 플래그를 사용하지 않으면 일부의 처리와 렌더링의 속도를 희생하지만, 읽기 조작이 비효율적이 되는 위치 좌표에 드라이버가 데이터를 두는 것은 적게 된다. 플래그를 아무것도 지정하지 않으면 어플리케이션은 버텍스 버퍼내에서 데이터의 읽기 조작과 쓰기 조작을 실시하는 것이라고 보여진다.

주 : D3DVBCAPS_OPTIMIZED 플래그는, 버텍스 버퍼의 생성시에는 사용되지 않는다. 시스템은, 버텍스 버퍼를 최적화할 경우에 이 능력 플래그를 설정한다.

마지막 2 개의 D3DVERTEXBUFFERDESC 멤버는, 그 외의 능력을 기술한다. lFVF 멤버에는, 버퍼에 포함할 수가 있는 버텍스의 종류를 식별하는유연한 버텍스 포맷 플래그의 편성이 포함된다. 버텍스 버퍼의 용량은,lNumVertices 멤버로 지정하는, 버텍스 버퍼에 거둘 수가 있는 버텍스의 합계수에 의해 측정된다.


디바이스의 종류와 버텍스 처리의 요건

트랜스 폼이나 라이팅등의 버텍스 처리의 퍼포먼스는, 버텍스 버퍼의 메모리내에서의 위치 좌표와 사용되는 렌더링 디바이스의 종류에 크게 의존한다. 버텍스 버퍼를 생성 하면, 어플리케이션은 그 버텍스 버퍼에의 메모리 어로케이션을 제어할 수 있다. 버텍스 버퍼의 기술에 D3DVBCAPS_SYSTEMMEMORY 능력 플래그가 설정되어 있을 때는, 시스템 메모리에 버텍스 버퍼가 생성 된다. 이 능력 플래그를 사용하지 않는 경우는, 버텍스 버퍼용의 메모리의 최선의 할당 장소를 디바이스 드라이버가 결정되어, 이와 같이 해 결정된 메모리를 많은 경우 "드라이버 최적화" 메모리라고 부른다. 드라이버 최적화 메모리로서는, 로컬 비디오 메모리, 비로컬 비디오 메모리, 또는 시스템 메모리가 지정된다.

[C++]

IDirect3DDevice7::DrawPrimitiveVB ,IDirect3DDevice7::DrawIndexedPrimitiveVB , 또는 IDirect3DVertexBuffer7::ProcessVertices 메소드를 호출하면, Direct3D 는 버텍스 처리를 적용한다. 이러한 버텍스 처리에는, 트랜스 폼, 라이팅등이 있다. 이러한 호출의 퍼포먼스는, 메모리내에서의 버퍼의 위치 좌표, 및 그 위치 좌표가 특정의 종류의 디바이스 (하드웨어 또는 소프트웨어)에 대해서 최적인 것일지 어떨지에 따라서 다르다.

[Visual Basic]

Direct3DDevice7.DrawPrimitiveVB ,Direct3DDevice7.DrawIndexedPrimitiveVB , 또는 Direct3DVertexBuffer7.ProcessVertices 메소드를 호출하면, Direct3D 는 버텍스 처리를 적용한다. 이러한 버텍스 처리에는, 트랜스 폼, 라이팅등이 있다. 이러한 호출의 퍼포먼스는, 메모리내에서의 버퍼의 위치 좌표, 및 그 위치 좌표가 특정의 종류의 디바이스 (하드웨어 또는 소프트웨어)에 대해서 최적인 것일지 어떨지에 따라서 다르다.

버텍스 버퍼가 시스템 메모리에 있는지, 드라이버 최적화 메모리에 있을까를 조사할 필요가 있는 것은, 텍스쳐의 경우와 같은 이유로부터이다. 텍스쳐의 경우, 하드웨어 라스터화에는, 드라이버 최적화 메모리에 할당할 수 있었던 텍스쳐가 최적이어, 소프트웨어 라스터화에는, 시스템 메모리에 할당할 수 있었던 텍스쳐가 최적이다. 같이 하드웨어에 있어서의 버텍스 처리 (트랜스 폼이나 라이팅등)에 최적인 것은, 드라이버 최적화 메모리에 할당할 수 있었던 버텍스 버퍼로, 소프트웨어에서의 버텍스 처리에 최적인 것은, 시스템 메모리에 할당할 수 있었던 버텍스 버퍼이다.

주 : ProcessVertices 메소드에 의한 버텍스 처리는, 항상 소프트웨어로 실행할 필요가 있기 (위해)때문에, 전송원버텍스 버퍼는 항상 시스템 메모리에 할당할 수 있을 필요가 있다. 어플리케이션으로 목적지 버텍스 버퍼를 직접 잠그어 읽어내지 않는 이상 또,ProcessVertices (버텍스 버퍼 렌더링 메소드가 불려 갔을 때, 버텍스 버퍼로부터의 읽기를 요구한다)의 호출로 클리핑이 요구되는 경우에는, 목적지 버텍스 버퍼는 드라이버 최적화 메모리에 할당할 수가 있다.

어플리케이션이 독자적인 버텍스 처리를 실행하는 ( 및, 트랜스 폼이 끝난 상태로, 라이팅이 적용되어 클리핑 된 버텍스를 버텍스 버퍼 렌더링 메소드에 건네준다) 경우, 어플리케이션은 드라이버 최적화 메모리에 할당할 수 있었던 버텍스 버퍼에 버텍스를 직접 기입할 수가 있다. 이 방법에 의해, 이후의 장황한 카피 처리를 방지한다. 다만, 드라이버 최적화 메모리로부터 호스트에 의해 실행되는 읽기 처리는, 매우 처리 속도가 늦은 일이 있기 (위해)때문에, 어플리케이션이 버텍스 버퍼로부터 데이터를 다시 읽는 경우에는, 이 방법은 잘 기능하지 않는다. 따라서, 어플리케이션으로 처리중에 읽기, 또는 버퍼에의 데이터 쓰기를 불규칙하게 실행할 필요가 있는 경우는, 시스템 메모리에 버텍스 버퍼를 할당하면(자) 좋다.

Direct3D 버텍스 처리 기능을 사용하는 경우 (트랜스폼 되지 않은의 버텍스를 버텍스 버퍼 렌더링 메소드에 건네줘), 디바이스의 종류에 응해 하드웨어 또는 소프트웨어의 어느쪽이든으로 처리를 실행할 수 있다. 디바이스가 TnLHAL 디바이스 (IID_IDirect3DTnLHALDevice)의 경우, 버텍스 처리는 하드웨어로 행해지기 (위해)때문에, 최고의 퍼포먼스를 얻으려면 드라이버 최적화 메모리에 버텍스 버퍼를 생성 한다. 디바이스가 HAL 디바이스 (IID_IDirect3DHALDevice)의 경우, 버텍스 처리는 소프트웨어로 행해지기 (위해)때문에, 시스템 메모리에 버텍스 버퍼를 생성 한다. RGB 디바이스 (IID_IDirect3DRGBDevice)로 렌더링 하는 경우는, 모든 버텍스 버퍼를 시스템 메모리에 할당한다.

[C++]

다음의 C++ 코드는, 버텍스 버퍼를 생성 및 처리할 경우에 적용하는 논리를 집계한 것이다.

if (소프트웨어의 라스터화)
시스템 메모리의 버텍스 버퍼를 사용한다. (D3DVBCAPS_SYSTEMMEMORY)
else if (어플리케이션의 버텍스 처리)
if (어플리케이션으로 읽기 및 불규칙한 쓰기를 실시하지 않는다)
드라이버 최적화 메모리의 버텍스 버퍼를 사용한다.
else
시스템 메모리의 버텍스 버퍼를 사용한다. (D3DVBCAPS_SYSTEMMEMORY)
else // Direct3D 의 버텍스 처리.
if (TnLHAL 디바이스)
드라이버 최적화 메모리의 버텍스 버퍼를 사용한다.
else if (HAL 디바이스)
시스템 메모리의 버텍스 버퍼를 사용한다. (D3DVBCAPS_SYSTEMMEMORY)
[Visual Basic]

다음의 Visual Basic 코드는, 버텍스 버퍼를 생성 및 처리할 경우에 적용하는 논리를 집계한 것이다.

If (소프트웨어의 라스터화) Then
시스템 메모리의 버텍스 버퍼를 사용한다. (D3DVBCAPS_SYSTEMMEMORY)
Else If (어플리케이션의 버텍스 처리) Then
If (어플리케이션으로 읽기 및 불규칙한 쓰기를 실시하지 않는다) Then
드라이버 최적화 메모리의 버텍스 버퍼를 사용한다.
Else
시스템 메모리의 버텍스 버퍼를 사용한다. (D3DVBCAPS_SYSTEMMEMORY)
Else // Direct3D 의 버텍스 처리.
If (TnLHAL 디바이스) Then
드라이버 최적화 메모리의 버텍스 버퍼를 사용한다.
Else If (HAL 디바이스)
시스템 메모리의 버텍스 버퍼를 사용한다. (D3DVBCAPS_SYSTEMMEMORY)
End If


버텍스 버퍼의 사용

이하의 주제에서는, 어플리케이션이 버텍스 버퍼로 실행하는 일반적인 태스크에 대해 설명한다.

  • 버텍스 버퍼의 생성
  • 버텍스 버퍼의 내용에의 액세스
  • 버텍스의 처리
  • 버텍스 버퍼의 최적화
  • 버텍스 버퍼로부터의 렌더링
  • 버텍스 버퍼의 기술의 취득


버텍스 버퍼의 생성

[C++]

다음의 그림은, C++ 로 1 개의 버텍스 버퍼를 생성 하기 위해서 필요한 순서를 나타낸다.

주 : 「Direct3D 에의 액세스」로 설명하도록(듯이),DirectDraw 컴퍼넌트는 2 개의 COM 오브젝트로부터 구성된다. DirectDraw7 로 불리는 최신의 오브젝트는,DirectDrawCreateEx 함수를 호출해 생성 되어IDirect3D7 인터페이스를 공개하는 유일한 오브젝트이다. 또, 이 오브젝트는,IDirect3DVertexBuffer7 인터페이스를 공개하는 버텍스 오브젝트를 생성할 수 있는 유일한 오브젝트이기도 하다. 이와 같이 생성 된 Direct3DDevice 오브젝트는, 종래의 Direct3D 인터페이스를 공개하지 않는다. 어플리케이션으로 종래의 Direct3D 오브젝트를 사용할 필요가 있는 경우는,DirectDrawCreate 메소드를 사용해 DirectDraw 오브젝트를 생성 하고 나서, 종래의 오브젝트를 생성 해야 한다.

4 개의 파라미터를 받는 IDirect3D7::CreateVertexBuffer 메소드를 호출해, 버텍스 버퍼 오브젝트를 생성 한다. 제 1 파라미터는, 희망의 버텍스 포맷, 버퍼 사이즈, 및 일반 능력을 기술하는 D3DVERTEXBUFFERDESC 구조체의 주소이다. 이러한 능력에 대해서는, 「버텍스 버퍼의 기술」로 설명한다. 보통, 시스템은, 버텍스 버퍼에 최적인 메모리 위치 좌표 (시스템 또는 디스플레이 메모리)를 자동적으로 할당한다. 다만, 소프트웨어 디바이스 또는 HAL 디바이스 (IID_IDirect3DHALDevice)는, 명시적인 시스템 메모리의 버텍스 버퍼에서만 사용할 수 있다. 상세한 것에 대하여는, 「디바이스의 종류와 버텍스 처리의 요건」을 참조할것.

CreateVertexBuffer 가 받는 제 2 파라미터는, 호출이 성공했을 때에 버텍스 버퍼 오브젝트의 새로운 IDirect3DVertexBuffer7 인터페이스에의 포인터가 저장 되는 변수의 주소이다. 제 3 파라미터는, 버텍스 버퍼에, 표시 영역외에 있는 버텍스의 클리핑 정보를 (클립 플래그 형식에서) 포함할 수가 있을지 어떨지를 지정한다. 이 파라미터를 0 으로 설정 하면,"클리핑 가능" 인 버텍스 버퍼가 생성 된다. D3DDP_DONOTCLIP 플래그를 포함하면(자), 클립 플래그를 포함할 수가 없는 버텍스 버퍼가 생성 된다. D3DDP_DONOTCLIP 플래그가 적용되는 것은, 트랜스 폼 끝난 버텍스를 버텍스 버퍼에 포함하도록 지시했을 경우 (D3DFVF_XYZRHW 플래그가 기술 구조체의 dwFVF 멤버에 포함되어 있다) 뿐인다. 트랜스폼 되지 않은의 버텍스 (D3DFVF_XYZ 플래그)를 버퍼에 포함하도록 지시했을 경우는,CreateVertexBuffer 메소드는 D3DDP_DONOTCLIP 플래그를 무시한다. 클리핑 플래그는 추가 메모리를 점유 하기 위한(해), 클리핑 가능한 버텍스 버퍼는, 클리핑 플래그를 포함하지 않는 버텍스 버퍼보다 약간 커진다. 리소스는 버텍스 버퍼가 생성 될 때 할당할 수 있기 (위해)때문에, 클리핑 가능한 버텍스 버퍼는 먼저 요구해 두지 않으면 안 된다.

주 : 클립 플래그를 포함할 수가 있는 버텍스 버퍼를 생성 해도, 반드시 버텍스의 처리중에 클립 플래그를 생성하도록(듯이) 요구하거나 렌더링중에 클립 플래그를 적용하도록(듯이) 요구 하지 않아도 되다. 각 버텍스 버퍼 렌더링 메소드는, D3DDP_DONOTCLIP 플래그를 받으면(자), 렌더링시에 클리핑 처리를 실시하지 않는다. 또,IDirect3DVertexBuffer7::ProcessVertices 메소드는 D3DVOP_CLIP 플래그를 받지만, 이것을 지정하고 있지 않는 것으로, 버텍스의 처리중에 시스템이 클립 플래그를 생성하는 것을 방지할 수 있다.

클립 플래그를 지원 하지 않고 생성 된 버텍스 버퍼에 클립 플래그를 생성할 수 없다. 이 경우,IDirect3DVertexBuffer7::ProcessVertices 메소드를 사용해 클립 플래그를 생성하려고 하면(자), 디버그 빌드에 실패해,D3DERR_INVALIDVERTEXFORMAT 가 돌려주어진다. 클립 플래그를 포함하지 않는 트랜스 폼이 끝난 버텍스 버퍼로부터 렌더링 하면 와, 렌더링 메소드는 클리핑의 요구를 무시한다.

CreateVertexBuffer 가 받는 마지막 파라미터는, 장래의 COM 집약 기능과의 호환성을 위해서(때문에) 준비되어 있다. 현재, 집약은 지원되어 있지 않기 때문에, 이 파라미터는 NULL 로 설정해 둔다.

다음의 C++ 코드는, 버텍스 버퍼의 생성 방법을 나타낸다.

    /*
* 이 예에서는, g_lpD3D 변수는 Direct3D 오브젝트에 의해 공개된다
* IDirect3D7 인터페이스의 주소로,
* g_vbVertexBuffer 는 LPD3DVERTEXBUFFER7 형의 변수이며,
* fIsATLHardwareDevice 변수는, 어플리케이션을 초기화했을 때에 설정된다
*  BOOL 변수이다.
     */

    D3DVERTEXBUFFERDESC vbdesc;
    ZeroMemory(&vbdesc, sizeof(D3DVERTEXBUFFERDESC));
    vbdesc.dwSize= sizeof(D3DVERTEXBUFFERDESC);
    vbdesc.dwCaps        = 0L;
    vbdesc.dwFVF         = D3DFVF_VERTEX;
    vbdesc.dwNumVertices = NUM_FLAG_VERTICES;

// 이것이 트랜스 폼 & 라이팅에 대응한 하드웨어 디바이스가 아닌 경우,
// 버텍스 버퍼는 반드시 시스템 메모리를 사용한다.
if( ! fIsATLHardwareDevice )
        vbdesc.dwCaps |= D3DVBCAPS_SYSTEMMEMORY;

// 클리핑 가능 버텍스 버퍼를 생성 한다.
    if(FAILED(g_lpD3D->CreateVertexBuffer(&vbdesc,
                                          &g_pvbVertexBuffer, 0L,
                                          NULL)))
        return E_FAIL;
[Visual Basic]

다음의 그림은, Visual Basic 로 1 개의 버텍스 버퍼를 생성 하기 위해서 필요한 순서를 나타낸다.

Visual Basic 에서는, 4 개의 파라미터를 받는 Direct3D7.CreateVertexBuffer 메소드를 호출해, 버텍스 버퍼 오브젝트를 생성 한다. 제 1 파라미터는, 희망의 버텍스 포맷, 버퍼 사이즈, 및 일반 능력을 기술하는 D3DVERTEXBUFFERDESC 형의 주소이다. 이러한 능력에 대해서는, 「버텍스 버퍼의 기술」로 설명한다. 보통, 시스템은, 버텍스 버퍼에 최적인 메모리 위치 좌표 (시스템 또는 디스플레이 메모리)를 자동적으로 할당한다. 다만, 소프트웨어 디바이스 또는 HAL 디바이스 (IID_IDirect3DHALDevice)는, 명시적인 시스템 메모리의 버텍스 버퍼에서만 사용할 수 있다. 상세한 것에 대하여는, 「디바이스의 종류와 버텍스 처리의 요건」을 참조할것.

제 2 파라미터는, 버텍스 버퍼에, 표시 영역외에 있는 버텍스의 클리핑 정보를 (클립 플래그 형식에서) 포함할 수가 있을지 어떨지를 지정한다. 이 파라미터를 0 으로 설정 하면,"클리핑 가능" 인 버텍스 버퍼가 생성 된다. D3DDP_DONOTCLIP 플래그를 포함하면(자), 클립 플래그를 포함할 수가 없는 버텍스 버퍼가 생성 된다. D3DDP_DONOTCLIP 플래그가 적용되는 것은, 트랜스 폼 끝난 버텍스를 버텍스 버퍼에 포함하도록 지시했을 (D3DFVF_XYZRHW 플래그가 기술의 lFVF 멤버에 포함된다) 경우뿐이다. 트랜스폼 되지 않은의 버텍스 (D3DFVF_XYZ 플래그)를 버퍼에 포함하도록 지시했을 경우,CreateVertexBuffer 메소드는 D3DDP_DONOTCLIP 플래그를 무시한다. 클리핑 플래그는 추가 메모리를 점유 하기 위한(해), 클리핑 가능한 버텍스 버퍼는, 클리핑 플래그를 포함하지 않는 버텍스 버퍼보다 약간 커진다. 리소스는 버텍스 버퍼가 생성 될 때 할당할 수 있기 (위해)때문에, 클리핑 가능한 버텍스 버퍼는 먼저 요구해 두지 않으면 안 된다.

호출이 성공하면(자),CreateVertexBuffer 메소드는 새로운 Direct3DVertexBuffer7 오브젝트에의 참조를 돌려준다.

주 : 클립 플래그를 포함할 수가 있는 버텍스 버퍼를 생성 해도, 반드시 버텍스의 처리중에 클립 플래그를 생성하도록(듯이) 요구하거나 렌더링중에 클립 플래그를 적용하도록(듯이) 요구 하지 않아도 되다. 각 버텍스 버퍼 렌더링 메소드는, D3DDP_DONOTCLIP 플래그를 받으면(자), 렌더링시에 클리핑 처리를 실시하지 않는다. 또,Direct3DVertexBuffer7.ProcessVertices 메소드는 D3DVOP_CLIP 플래그를 받지만, 이것을 지정하고 있지 않는 것으로, 버텍스의 처리중에 시스템이 클립 플래그를 생성하는 것을 방지할 수 있다.

클립 플래그를 지원 하지 않고 생성 된 버텍스 버퍼에 클립 플래그를 생성할 수 없다. 이 경우,Direct3DVertexBuffer7.ProcessVertices 메소드를 사용해 클립 플래그를 생성하려고 하면(자), 디버그 빌드에 실패해,D3DERR_INVALIDVERTEXFORMAT 에러가 돌려주어진다. 클립 플래그를 포함하지 않는 트랜스 폼이 끝난 버텍스 버퍼로부터 렌더링 하면 와, 렌더링 메소드는 클리핑의 요구를 무시한다.

다음의 Visual Basic 코드는, 버텍스 버퍼의 생성 방법을 나타낸다.

    '
'이 예에서는, g_D3D 변수는 Direct3D7 오브젝트에의 참조로,
' g_VertexBuffer 는 Direct3DVertexBuffer7 오브젝트에의
'참조이다.
    '
On Local Error Resume Next

Dim VBDesc As D3DVERTEXBUFFERDESC
VBDesc.lFVF = D3DFVF_VERTEX
VBDesc.lNumVertices = NUM_FLAG_VERTICES

'클리핑 가능 버텍스 버퍼를 생성 한다.
Set g_VertexBuffer = g_D3D.CreateVertexBuffer(VBDesc, D3DDP_DEFAULT)

If Err.Number <> DD_OK Then
'에러 처리 코드
End If


버텍스 버퍼의 내용에의 액세스

[C++]

버텍스 버퍼 오브젝트를 사용하면(자), 버텍스 데이터에 할당할 수 있었던 메모리에 어플리케이션이 직접 액세스 할 수 있다. IDirect3DVertexBuffer7::Lock 메소드를 호출해 버텍스 버퍼 메모리에의 포인터를 취득해, 다음에 필요에 따라서 메모리에 액세스 해 새로운 버텍스 데이터를 버퍼로 설정하는지, 이미 설정되어 있는 데이터를 읽어낸다.

IDirect3DVertexBuffer7::Lock 메소드는 3 개의 파라미터를 받는다. 제 1 파라미터의 dwFlags 는, 메모리의 락 방법을 시스템에 알린다. 이 파라미터는, 버퍼내의 데이터에 어플리케이션이 어떻게 액세스 할까를 알리기 위해서(때문에) 사용할 수 있다 (읽기 전용 또는 쓰기 전용 액세스를 지정할 수 있다. 이것에 의해, 드라이버는 메모리를 잠그어, 요구되고 있는 액세스 타입으로 최고의 퍼포먼스를 제공한다. 힌트는 필수는 아니지만, 상황에 따라서는 메모리 액세스의 퍼포먼스를 개선할 수 있다). 버텍스 버퍼는 DirectDrawSurface 오브젝트를 사용해 버텍스 데이터를 저장 하기 위한(해),IDirect3DVertexBuffer7::Lock 가 받는 플래그는 IDirectDrawSurface7::Lock 메소드의 플래그와 같아, 결과도 같다.

Lock 메소드가 받는 제 2 파라미터 lplpData 는,LPVOID 변수의 주소로, 호출이 성공했을 경우는, 버텍스 버퍼 메모리를 가리키는 유효한 포인터가 설정된다. 마지막 파라미터 lpdwSize 는, 호출이 돌려주어진 후,lplpData 가 가리키는 버퍼의 바이트 단위에서의 사이즈가 설정되는 변수의 주소이다. 어플리케이션이 버퍼 사이즈의 정보를 필요로 하지 않는 경우는,lpdwSize 에 NULL 를 설정할 수 있다.

퍼포먼스에 관한 주의 : 어플리케이션이 버텍스 버퍼 메모리로부터의 읽기만을 실시하는 경우는, DDLOCK_READONLY 플래그를 사용한다. 이 플래그를 포함하면(자), Direct3D 가 내부 순서를 최적화하므로 효율이 오른다. 다만, 메모리에의 액세스는 읽어내기 전용이 된다. DDLOCK_READONLY 플래그로 잠근 메모리에 기입하는 것은 가능하지만, 예기치 못한 결과가 되는 일이 있다. 또, D3DVBCAPS_WRITEONLY 플래그로 생성 한 버텍스 버퍼로부터 읽어내려고 하면, 버퍼를 읽어내기 전용에 잠그었을 경우에서도 극단적으로 저속이 되는 일이 있다.

C++ 의 경우, 버텍스 버퍼에 할당할 수 있고 있는 메모리에 직접 액세스 한다. 이 때, 목적의 메모리에는 올바르게 액세스 하도록(듯이) 주의 해야 한다. 그렇지 않으면 부정한 메모리가 렌더링 될 우려가 있다. 어플리케이션으로 사용하는 버텍스 포맷의 보폭을 이용해, 할당할 수 있고 있는 버퍼의 버텍스로부터 다음의 버텍스로 이동한다. 버텍스 버퍼 메모리 자체는, 유연한 버텍스 포맷으로 지정된 버텍스의 단순한 배열이다. 어플리케이션으로 종래의 버텍스 구조체의 D3DVERTEX ,D3DLVERTEX , 및 D3DTLVERTEX 를 사용하는 경우, 보폭은 단지 바이트 단위의 구조체의 사이즈이다. 종래의 포맷과 다른 버텍스 포맷을 사용하고 있는 경우는, 정의한 임의의 버텍스 포맷 구조체의 보폭을 사용한다. 버텍스 버퍼의 기술에 포함되는유연한 버텍스 포맷 플래그를 조사하는 것으로, 실행시에 각 버텍스의 보폭을 계산할 수 있다. 다음의 표는, 각 버텍스 성분의 사이즈를 나타낸다.

버텍스 포맷 플래그 | 사이즈
D3DFVF_DIFFUSE | sizeof(DWORD)
D3DFVF_NORMAL | sizeof(float) × 3
D3DFVF_SPECULAR | sizeof(DWORD)
D3DFVF_TEXn | sizeof(float) × 2 × n
D3DFVF_XYZ | sizeof(float) × 3
D3DFVF_XYZRHW | sizeof(float) × 4

버텍스 포맷에 존재하는 텍스쳐 좌표의 수는, D3DFVF_TEXn 플래그로 기술된다 (n 는 0 ~ 8 까지의 값). 버텍스 포맷의 텍스쳐 좌표 세트는,float 변수 2 개 분의 공간을 차지하기 (위해)때문에, 그 수의 텍스쳐 좌표에 요구되는 메모리를 계산하려면 , 텍스쳐 좌표 세트의 수에 텍스쳐 좌표 1 세트의 사이즈를 탄다.

특정의 버텍스에 액세스 하려면 , 합계 버텍스 보폭을 사용해, 메모리 포인터를 필요한 만큼 인크리먼트(increment) 또는 감소 한다.

[Visual Basic]

버텍스 버퍼를 사용 하면, Visual Basic 어플리케이션에서는, 버텍스 버퍼내의 버텍스 데이터를 간단하게 갱신할 수 있다. 버텍스 버퍼내의 데이터에 액세스 하려면 ,Direct3DVertexBuffer7.Lock 메소드를 호출한다. Lock 메소드에는, 메모리의 락 방법을 시스템에 알리는 flags 파라미터가 있다. flags 파라미터는, 버퍼내의 데이터에 어플리케이션이 어떻게 액세스 할까를 알린다. (읽기 전용 또는 쓰기 전용 액세스를 요구할 수 있다. 이것에 의해, 드라이버는 메모리를 잠그어, 요구되고 있는 액세스 타입으로 최고의 퍼포먼스를 제공한다. 힌트는 필수는 아니지만, 상황에 따라서는 메모리 액세스의 퍼포먼스를 개선할 수 있다). 버텍스 버퍼는 DirectDrawSurface 오브젝트를 사용해 버텍스 데이터를 저장 하기 위한(해),Direct3DVertexBuffer7.Lock 가 받는 플래그는,DirectDrawSurface7.Lock 메소드의 플래그와 같아, 결과도 같다.

퍼포먼스의 주의 : 어플리케이션이 버텍스 버퍼 메모리로부터의 읽기만을 실시하는 경우는, DDLOCK_READONLY 플래그를 사용한다. 이 플래그를 포함하면(자), Direct3D 가 내부 순서를 최적화하므로 효율이 오른다. 다만, 메모리에의 액세스는 읽어내기 전용이 된다. DDLOCK_READONLY 플래그로 잠근 메모리에 기입하는 것은 가능하지만, 예기치 못한 결과가 되는 일이 있다. 또, D3DVBCAPS_WRITEONLY 플래그로 생성 한 버텍스 버퍼로부터 읽어내려고 하면, 버퍼를 읽어내기 전용에 잠그었을 경우에서도 극단적으로 저속이 되는 일이 있다.

버텍스 버퍼를 잠그면(자),Direct3DVertexBuffer7.GetVertices 메소드를 호출해, 버텍스 버퍼의 현재의 내용을 배열에 넣을 수가 있다. 제 1 파라미터에는, 필요한 버퍼내에 있는 최초의 버텍스의 0 으로부터 시작되는 인덱스를 설정해, 제 2 파라미터에는, 취득하는 버텍스의 합계수를 설정한다. 마지막 파라미터에는, 호출 후에 요구되는 데이터를 넣는 버텍스 버퍼와 같은 버텍스 포맷을 사용하는 배열내의 최초의 요소를 설정해야 한다.

버텍스 버퍼 메모리 자체는, 유연한 버텍스 포맷으로 지정된 버텍스의 단순한 배열이다. 버텍스 포맷에 존재하는 텍스쳐 좌표의 수는, D3DFVF_TEXn 플래그로 기술된다 (n 는 0 ~ 8 의 값). 버텍스 포맷의 텍스쳐 좌표 세트는,Single 변수 2 개 분의 공간을 차지하기 (위해)때문에, 그 개수의 텍스쳐 좌표로 필요한 메모리를 계산하려면 , 텍스쳐 좌표 세트의 개수에 텍스쳐 좌표 1 세트 분의 사이즈를 탄다.

버텍스 버퍼를 잠근 다음에 그 내용을 변경하려면 , 배열의 내용을 변경해, 다음에 Direct3DVertexBuffer7.SetVertices 메소드를 호출해 버텍스를 버퍼에 카피한다. 버텍스 버퍼 처리나 렌더링 처리를 실행하기 전에,Direct3DVertexBuffer7.Unlock 메소드로 버텍스 버퍼를 락 해제할 필요도 있다.


버텍스의 처리

[C++]

옵션으로, 라이팅, 클립 플래그의 생성, 및 범위의 갱신등의 버텍스 조작도 적용할 수 있다. IDirect3DVertexBuffer7 인터페이스는, 버텍스 처리용의 IDirect3DVertexBuffer7::ProcessVertices 메소드를 공개한다. 전송원버퍼는 아니고 목적지 버텍스 버퍼의 ProcessVertices 메소드를 호출해, 버텍스를 전송원버텍스 버퍼로부터 목적지 버텍스 버퍼에 처리한다. 이 메소드가 받는 7 개의 파라미터에는, 실행하는 조작, 전송원버텍스 버퍼의 IDirect3DVertexBuffer7 인터페이스의 위치 좌표, 버텍스 조작을 실시하는 렌더링 디바이스, 및 메소드의 타겟이 되는 버텍스의 위치 좌표와 수를 기술한다. 호출의 뒤, 목적지 버퍼에는 처리된 버텍스 데이터가 설정되지만, 전송원버퍼는 변화하지 않는다.

버텍스의 처리를 준비 하면나무는, 제 1 파라미터 dwVertexOp 에 실시하고 싶은 버텍스 조작을 설정한다. D3DVOP_TRANSFORM 플래그는 반드시 포함하지 않으면 안되어, 포함하지 않으면 메소드는 실패한다. 나머지의 조작은 옵션이다. 버텍스의 처리에, 버텍스의 라이팅, 클립 플래그의 생성, 범위의 갱신 등, 옵션의 플래그는 어떠한 편성에서도 포함할 수가 있다.

제 2 파라미터 dwDestIndex 와 제 3 파라미터 dwCount 는, 버텍스가 놓여지는 목적지 버퍼의 인덱스와 처리되어 목적지 버퍼내에 놓여지는 버텍스의 합계수를 나타낸다. 제 4 파라미터 lpSrcBuffer 에는, 전송 되는 버텍스를 포함한 버텍스 버퍼 오브젝트의 IDirect3DVertexBuffer7 의 주소를 설정한다. dwSrcIndex 는, 메소드가 버텍스 처리를 시작 하는 위치 좌표를 나타내는 인덱스를 지정한다 (처리의 대상이 되는 전송원의 버텍스의 합계수는 dwCount 파라미터로 지정된다). lpD3DDevice 파라미터에는, 버텍스를 처리하는 렌더링 디바이스의 IDirect3DDevice7 인터페이스의 주소를 설정한다.

마지막 파라미터 dwFlags 는, 메소드의 특수 처리 옵션을 지정한다. 이 파라미터를 0 으로 설정 하면, 디폴트의 버텍스 처리가 실행되어 D3DPV_DONOTCOPYDATA 를 설정 하면, 어떠한 상황에 있어 처리가 최적화된다. dwFlags 를 0 으로 설정 하면, 전송원버텍스 버퍼의 버텍스 포맷의 버텍스 성분은, 버텍스 처리의 영향을 받지 않고 전송원버텍스 버퍼로부터 카피되는지 (전송원버퍼에 있는 경우), 0 으로 설정된다. 다만, D3DPV_DONOTCOPYDATA 를 사용하는 것으로써, 전송원버퍼의 버텍스 포맷의 버텍스 성분은,ProcessVertices 의 호출의 일부로서 계산되지 않고 그대로 남는다. ProcessVertices 메소드를 호출해, 라이트를 대지 않은 버텍스를 트랜스 폼 (이 메소드의 D3DVOP_TRANSFORM 버텍스 처리를 이용) 하는 경우를 생각해 본다. 목적지 버텍스 버퍼로 D3DFVF_TLVERTEX 버텍스 포맷을 사용하고 있는 경우, D3DPV_DONOTCOPYDATA 플래그를 지정 하면, 목적지 버퍼의 디퓨즈, 스펙큐러, 및 텍스쳐 좌표 컴퍼넌트는 무시된다. 그 결과, 시스템에는 버텍스의 트랜스 폼만 요구하게 되어, 처리와 데이터 전송의 오버헤드가 가벼워진다. D3DPV_DONOTCOPYDATA 를 지정하고 있지 않는 경우는, 어플리케이션으로 불필요함에도 불구하고, 라이팅 및 텍스쳐 좌표 컴퍼넌트가 목적지 버퍼에 카피된다. D3DPV_DONOTCOPYDATA 플래그는, 버텍스 처리 시에 시스템으로 필요한 작업량을 경감하는데 유효한 플래그이다. ProcessVertices 를 사용하는 어플리케이션에서는, 스태틱 버텍스 성분을 목적지 버텍스 버퍼에 직접 카피할 수 있기 (위해)때문에, 시스템측에서 전송원버퍼로부터 목적지 버퍼에 카피할 필요는 없어진다.

디바이스에서의 버텍스 처리의 제한을 조사하려면 , 지원 되고 있는 버텍스 처리 능력에 대해,D3DDEVICEDESC7 구조체의 dwVertexProcessingCaps 멤버를 문의한다.

[Visual Basic]

옵션으로, 라이팅, 클립 플래그의 생성, 및 범위의 갱신등의 버텍스 조작도 적용할 수 있다. Direct3DVertexBuffer7 클래스에는, 버텍스를 처리하는 Direct3DVertexBuffer7.ProcessVertices 메소드가 있다. 전송원버퍼는 아니고 목적지 버텍스 버퍼의 ProcessVertices 메소드를 호출해, 버텍스를 전송원버텍스 버퍼로부터 목적지 버텍스 버퍼에 처리한다. 이 메소드에는 7 개의 파라미터가 있어, 실행하는 조작, 전송원 Direct3DVertexBuffer7 오브젝트에의 참조, 버텍스 처리를 실행하는 렌더링 디바이스, 및 메소드의 대상이 되는 버텍스의 위치 좌표와 개수를 각각 기술한다. 호출의 뒤, 목적지 버퍼에는 처리된 버텍스 데이터가 설정되지만, 전송원버퍼는 변화하지 않는다.

버텍스의 처리를 하면나무는, 제 1 파라미터 vertexOp 에 실행하는 버텍스 처리를 설정한다. D3DVOP_TRANSFORM 플래그는 반드시 포함하지 않으면 안되어, 포함하지 않으면 메소드는 실패한다. 나머지의 조작은 옵션이다. 버텍스의 처리에, 버텍스의 라이팅, 클립 플래그의 생성, 범위의 갱신 등, 옵션의 플래그는 어떠한 편성에서도 포함할 수가 있다.

제 2 파라미터 destIndex 및 제 3 파라미터 count 는, 버텍스가 배치되는 목적지 버퍼의 인덱스, 및 처리되어 목적지 버퍼에 배치되는 버텍스의 합계수를 각각 나타낸다. 제 4 파라미터 srcBuffer 에는, 전송 되는 버텍스를 포함한 Direct3DVertexBuffer7 오브젝트를 설정할 필요가 있다. srcIndex 는, 메소드가 버텍스 처리를 시작 하는 위치 좌표를 나타내는 인덱스를 지정한다 (처리의 대상이 되는 전송원의 버텍스의 합계수는 count 파라미터로 지정된다). dev 파라미터에는, 버텍스를 처리하는 Direct3DDevice7 오브젝트를 설정한다.

마지막 파라미터 flags 는, 메소드의 특수 처리 옵션을 지정한다. 이 파라미터를 0 으로 설정 하면, 디폴트의 버텍스 처리가 실행되어 D3DPV_DONOTCOPYDATA 를 설정 하면, 어떠한 상황에 있어 처리가 최적화된다. flags 를 0 으로 설정 하면, 전송원버텍스 버퍼의 버텍스 포맷의 버텍스 성분은, 버텍스 처리의 영향을 받지 않고 전송원버텍스 버퍼로부터 카피되는지 (전송원버퍼에 있는 경우), 0 으로 설정된다. 다만, D3DPV_DONOTCOPYDATA 를 사용하는 것으로써, 전송원버퍼의 버텍스 포맷의 버텍스 성분은,ProcessVertices 의 호출의 일부로서 계산되지 않고 그대로 남는다. ProcessVertices 메소드를 호출해, 라이트를 대지 않은 버텍스를 트랜스 폼 (이 메소드의 D3DVOP_TRANSFORM 버텍스 처리를 이용) 하는 경우를 생각해 본다. 목적지 버텍스 버퍼로 D3DFVF_TLVERTEX 버텍스 포맷을 사용하고 있는 경우, D3DPV_DONOTCOPYDATA 플래그를 지정 하면, 목적지 버퍼의 디퓨즈, 스펙큐러, 및 텍스쳐 좌표 컴퍼넌트는 무시된다. 그 결과, 시스템에 버텍스의 트랜스 폼만 요구하게 되어, 처리와 데이터 전송의 오버헤드가 가벼워진다. D3DPV_DONOTCOPYDATA 를 지정하고 있지 않는 경우는, 어플리케이션으로 불필요함에도 불구하고, 라이팅 및 텍스쳐 좌표 컴퍼넌트가 목적지 버퍼에 카피된다. D3DPV_DONOTCOPYDATA 플래그는, 버텍스 처리 시에 시스템으로 필요한 작업량을 경감하는데 유효한 플래그이다. ProcessVertices 를 사용하는 어플리케이션에서는, 스태틱 버텍스 성분을 목적지 버텍스 버퍼에 직접 카피할 수 있기 (위해)때문에, 시스템측에서 전송원버퍼로부터 목적지 버퍼에 카피할 필요는 없어진다.

디바이스에서의 버텍스 처리의 제한을 조사하려면 , 지원 되고 있는 버텍스 처리 능력에 대해,D3DDEVICEDESC7 형의 lVertexProcessingCaps 멤버를 문의한다.

호환성이 있는 버텍스 포맷을 사용한 버텍스 버퍼를 생성 하도록(듯이) 주의 해야 한다. 적어도, 전송원버퍼는 트랜스폼 되지 않은의 버텍스를 포함해 (버퍼 기술의 버텍스 포맷에 D3DFVF_XYZ 플래그를 사용), 목적지 버퍼는 트랜스 폼 된 버텍스를 포함하는 것으로 한다 (D3DFVF_XYZRHW 플래그를 사용). 라이팅 또는 그리핑 서비스를 위해서(때문에), 전송원과 목적지의 버텍스 포맷은 적절한 필드를 포함하는 것이 요구된다. 예를 들어, 버텍스 포맷에 버텍스 법선을 포함하지 않은 경우는, 버텍스의 라이팅을 요구하지 않는 것. 같이 클리핑 기능없이 생성 된 목적지 버텍스 버퍼에, 시스템이 클립 플래그를 생성하도록(듯이) 요구할 수 없다. 호환성이 없는 버퍼로 조작을 실시하려고 하면, 디버그 빌드의 경우, 실패한다.

어플리케이션으로 버텍스 버퍼로부터 렌더링을 실행하는 경우는, 버텍스 버퍼 메소드를 사용할 필요가 있다.

전송원 또는 목적지의 버텍스 버퍼가 락 되고 있을 때는, 버텍스를 처리할 수 없다.


버텍스 버퍼의 최적화

버텍스 버퍼를 최적화 하면, 시스템은 버퍼의 내용을 수정해, 버텍스의 처리 또는 렌더링의 퍼포먼스가 양호하게 된다. 버텍스가 어떻게 최적화될까는, 플랫폼 고유하고, 변경되는 일이 있다. 이 때문에, 최적화된 버텍스 버퍼의 내용을 잠그거나 액세스 할 수 없다.

[C++]

하드웨어 및 소프트웨어의 양쪽 모두의 퍼포먼스는, 버텍스 버퍼를 최적화하는 것으로 개선할 수 있다. 버텍스 버퍼의 최적화는, 버텍스 버퍼가 하드웨어 또는 소프트웨어의 버텍스 처리의 어느 쪽을 위해서(때문에) 사용되고 있을까에 따라서 다르다. D3DVBCAPS_SYSTEMMEMORY 플래그를 지정해 생성 한 버텍스 버퍼는, 소프트웨어 버텍스 처리에 대해서 최적화되어IDirect3DVertexBuffer7::ProcessVertices 메소드 또는 HAL 디바이스 (TnLHAL 디바이스와는 대조적)의 버텍스 버퍼 렌더링 메소드에서만 사용할 수 있다. D3DVBCAPS_SYSTEMMEMORY 플래그 (드라이버 최적화 메모리용)를 지정하지 않고 생성 한 버텍스 버퍼는, 하드웨어 버텍스 처리에 대해서 최적화되어 따라,TnLHAL 디바이스의 렌더링 메소드에서만 사용할 수 있다. 최적화된 버텍스 버퍼는,IDirect3DVertexBuffer7::ProcessVertices 또는 IDirect3DVertexBuffer7::ProcessVerticesStrided 메소드의 목적지 버퍼로서 사용할 수 없다.

IDirect3DVertexBuffer7::Optimize 메소드를 호출해 버텍스 버퍼를 최적화한다. 버텍스 버퍼를 최적화 하면, 버텍스 조작과 렌더링의 퍼포먼스가 개선된다. IDirect3DVertexBuffer7::Optimize 메소드는 2 개의 파라미터를 받지만, 그 중 1 개(살)만이 사용된다. lpD3DDevice 파라미터에 버텍스를 최적화하는 디바이스의 주소를 설정해, 마지막 파라미터에 0 을 설정한다. 락 된 버텍스 버퍼는, 언락 할 때까지 최적화할 수 없다.

버텍스가 최적화된 포맷에 유지하는 것으로 퍼포먼스를 개선할 수 있다. 다만, 최적화된 버텍스 버퍼는, 스태틱 지오메트리인 만큼 사용한다. 버텍스 버퍼를 한 번 최적화 하면, 최적화된 내용을 변경하기 위해서 잠글 수 없기 때문에이다. 최적화된 버텍스 버퍼는,IDirect3DVertexBuffer7::ProcessVertices 메소드 및 버텍스 버퍼 렌더링 메소드에서만 사용할 수 있다.

[Visual Basic]

하드웨어 및 소프트웨어의 양쪽 모두의 퍼포먼스는, 버텍스 버퍼를 최적화하는 것으로 개선할 수 있다. 버텍스 버퍼의 최적화는, 버텍스 버퍼가 하드웨어 또는 소프트웨어의 버텍스 처리의 어느 쪽을 위해서(때문에) 사용되고 있을까에 따라서 다르다. D3DVBCAPS_SYSTEMMEMORY 플래그를 지정해 생성 한 버텍스 버퍼는, 소프트웨어 버텍스 처리 에 대해서만 최적화되어Direct3DVertexBuffer7.ProcessVertices 메소드 또는 HAL 디바이스 (TnLHAL 디바이스와는 대조적)의 버텍스 버퍼 렌더링 메소드에서만 사용할 수 있다. D3DVBCAPS_SYSTEMMEMORY 플래그 (드라이버 최적화 메모리용)를 지정하지 않고 생성 한 버텍스 버퍼는, 하드웨어 버텍스 처리에 대해서 최적화되어 따라,TnLHAL 디바이스의 렌더링 메소드에서만 사용할 수 있다. 최적화된 버텍스 버퍼는,Direct3DVertexBuffer7.ProcessVertices 메소드의 목적지 버퍼로서 사용할 수 없다.

Direct3DVertexBuffer7.Optimize 메소드를 호출해 버텍스 버퍼를 최적화한다. 버텍스 버퍼를 최적화 하면, 버텍스 처리 및 렌더링의 퍼포먼스가 개선된다. Direct3DVertexBuffer7.Optimize 메소드는 파라미터를 1 개 받는다. 이 파라미터에는, 버텍스의 최적화의 대상이 되는 Direct3DDevice7 오브젝트를 설정한다. 락 되고 있는 버텍스 버퍼는, 락 해제할 때까지 최적화할 수 없다.

버텍스가 최적화된 포맷에 유지하는 것으로 퍼포먼스를 개선할 수 있다. 다만, 최적화된 버텍스 버퍼는, 스태틱 지오메트리인 만큼 사용한다. 버텍스 버퍼를 한 번 최적화 하면, 최적화된 내용을 변경하기 위해서 잠글 수 없기 때문에이다. 최적화된 버텍스 버퍼는,Direct3DVertexBuffer7.ProcessVertices 메소드 및 버텍스 버퍼 렌더링 메소드에서만 사용할 수 있다.


버텍스 버퍼로부터의 렌더링

「렌더링」으로 설명하도록(듯이), 렌더링 디바이스에서는, 버텍스 버퍼로부터 프리미티브를 렌더링하기 위한 메소드를 이용할 수 있다. 이러한 메소드는, 그 외의 대부분의 렌더링 메소드와 거의 같은 기능을 가지지만, 버텍스 버퍼 오브젝트를 지정하는 파라미터에 약간의 차이가 있다.

이하의 주제에서는, 일반적인 렌더링 상황에 대해, 및 버텍스 버퍼 렌더링 메소드의 호출해에 관한 특정의 문제에 대해 설명한다.

  • 버텍스 버퍼 렌더링에 대해
  • 버텍스 버퍼 렌더링 메소드의 호출


버텍스 버퍼의 기술의 취득

[C++]

어플리케이션에서는, 자주, 실행시에 기존의 버텍스 버퍼에 대한 정보를 취득하는 것이 필요하게 된다. Direct3D 에서는,IDirect3DVertexBuffer7::GetVertexBufferDesc 메소드를 사용해 이 정보를 취득한다. 이 메소드는, 현재의 기술을 취득하는 버텍스 버퍼의 IDirect3DVertexBuffer7 인터페이스를 사용해 호출한다.

GetVertexBufferDesc 메소드는 파라미터를 1 개만 받는다. 이 파라미터에는, 적절히 초기화된 D3DVERTEXBUFFERDESC 구조체의 주소를 설정한다. 구조체를 초기화하려면 ,dwSize 멤버를 구조체의 바이트 단위의 사이즈로 설정해, 나머지의 멤버는 0 으로 설정한다. 메소드가 돌아가면(자), 버텍스 버퍼 기능, 버퍼내의 버텍스 포맷, 버퍼가 포함할 수가 있는 버텍스의 합계수에 대한 정보가 구조체로 설정되어 있다.

주 : 버텍스 버퍼를 최적화 하면, D3DVBCAPS_OPTIMIZED 능력 플래그가D3DVERTEXBUFFERDESC 구조체의 dwCaps 멤버로 설정된다. 이 플래그가 설정되어 있을 때는, 버텍스 버퍼는 잠글 수 없다. 최적화된 버텍스 버퍼의 내용은, 렌더링 메소드 및 버텍스 버퍼 처리 메소드 (IDirect3DVertexBuffer7::ProcessVertices 및 IDirect3DVertexBuffer7::ProcessVerticesStrided ) 이외에서는 사용할 수 없다.

일반적인 정보에 대해서는, 「버텍스 버퍼의 기술」을 참조할것.

[Visual Basic]

어플리케이션에서는, 자주, 실행시에 기존의 버텍스 버퍼에 대한 정보를 취득하는 것이 필요하게 된다. Direct3D 에서는,Direct3DVertexBuffer7.GetVertexBufferDesc 메소드를 사용해, Visual Basic 어플리케이션으로 이 정보를 취득할 수 있도록(듯이) 한다.

GetVertexBufferDesc 메소드는 파라미터를 1 개만 받는다. 이 파라미터에는,D3DVERTEXBUFFERDESC 형의 적절한 변수를 설정한다. 이 메소드가 돌아가면(자), 구조체에는, 버텍스 버퍼의 능력, 버퍼의 버텍스 포맷, 및 버퍼에 포함되는 버텍스의 합계수에 대한 정보가 들어간다.

주 : 버텍스 버퍼를 최적화 하면, D3DVBCAPS_OPTIMIZED 능력 플래그가,GetVertexBufferDesc 에 의해 취득되는 D3DVERTEXBUFFERDESC 형의 lCaps 멤버로 설정된다. 이 플래그가 설정되어 있을 때는, 버텍스 버퍼는 잠글 수 없다. 최적화된 버텍스 버퍼의 내용은, 렌더링 메소드 및 Direct3DVertexBuffer7.ProcessVertices 메소드 이외에서는 사용할 수 없다.

일반적인 정보에 대해서는, 「버텍스 버퍼의 기술」을 참조할것.


공통의 테크놀러지와 특수 효과

Direct3D 는, 3D 신을 보다 리얼하게 표시하기 위한 강력한 툴군을 제공하고 있다. 이 섹션에서는, Direct3D 로 생성할 수 있는 일반적인 특수 효과에 대해 설명한다. 생성할 수 있는 이펙트의 범위는, 여기서 설명하는 이펙트로 한정되는 것은 아니다. 설명하는 주제는 다음과 같다.

  • 포그(안개:fog)
  • 지오메트리 블렌딩
  • 유저 정의 클립면
  • 환경 맵핑
  • 범프 맵핑
  • 빌보드화
  • 운, 연기, 증기
  • 화, 불길, 폭발 등
  • 모션브라
  • 스텐실 버퍼 기술
  • 컬러 라이팅
  • anti-aliasing


포그(안개:fog)

이하의 주제에서는, 포그(안개:fog)에 대해, 및 Direct3D 어플리케이션에서의 각종 포그(안개:fog) 기능의 사용에 대해 설명한다.

  • 포그(안개:fog)의 개요
  • 포그(안개:fog) 공식
  • 포그(안개:fog) 파라미터
  • 포그(안개:fog) 블렌딩
  • 포그(안개:fog) 컬러
  • 픽셀 포그(안개:fog)
  • 버텍스 포그(안개:fog)


포그(안개:fog)의 개요

3D 신에 포그(안개:fog)를 추가하는 것으로써, 보다 리얼한 정경을 표현하거나 분위기를 내거나 먼 경치를 애매하게 할 수가 있다. Direct3D 직접 모드는, 픽셀 포그(안개:fog)와 버텍스 포그(안개:fog)라고 하는 2 개의 포그(안개:fog) 모델을 지원 한다. 이 2 개(살)은, 각각 고유의 기능과 프로그래밍 인터페이스를 가진다.

포그(안개:fog)는, 기본적으로는, 장면내의 오브젝트의 깊이 또는 시점으로부터의 거리에 근거해, 장면내의 오브젝트의 색과 선택한 포그(안개:fog) 컬러를 블렌드 해 실현된다. 오브젝트가 멀어지는에 따라, 원의 색과 포그(안개:fog) 컬러의 블렌드가 늘어나, 장면에 떠오르는 작은 입자, 즉 "포그(안개:fog)" 에 의해 오브젝트의 표시가 노망나 간다. 다음의 화면은, 포그(안개:fog)없이 드로잉(Drawing) 한 장면과 포그(안개:fog)를 유효하게 해 드로잉(Drawing) 한 같은 장면을 나타낸다.

위에의도로, 좌측의 장면에는 명료한 수평선이 있어, 저 너머에는 열매 세계에서는 보여야할 풍경이 안보인다. 우측의 장면에서는 배경색과 동일한 포그(안개:fog) 컬러를 사용해 수평선이 애매하게 해져 다각형이 먼 곳에서는 사라지는 것처럼 보인다. 개별의 포그(안개:fog) 이펙트와 크리에이티브인 장면 디자인을 조합하면(자), 장면내의 오브젝트의 색을 완화시켜 분위기를 늘릴 수가 있다.

Direct3D 는, 장면에 포그(안개:fog)를 추가하기 위해서, 어플리케이션에 2 개의 방법을 제공한다. 픽셀 포그(안개:fog)와 버텍스 포그(안개:fog)이며, 포그(안개:fog) 이펙트를 어떻게 적용할까에 따라 이름이 붙여지고 있다. 상세한 것에 대하여는, 「픽셀 포그(안개:fog)」 및 「버텍스 포그(안개:fog)」를 참조할것. 간단하게 말하면, 픽셀 포그(안개:fog) ("테이블 포그(안개:fog)" 라고도 불린다)는 디바이스 드라이버로 실현되어 버텍스 포그(안개:fog)는 Direct3D 라이팅 엔진으로 실현된다.

주 : 버텍스 포그(안개:fog) 및 픽셀 포그(안개:fog)의 머지않아를 사용하고 있는 경우에서도, 어플리케이션에서는 포그(안개:fog) 이펙트가 올바르게 적용되도록(듯이) 적절한 투영 행렬을 준비할 필요가 있다. 이 제약은, Direct3D 트랜스 폼 & 라이팅 엔진을 사용하지 않는 어플리케이션에도 들어맞는다. 적절한 행렬의 생성 방법의 상세한 것에 대하여는, 「W 버퍼에 유효한 투영 행렬」을 참조할것.


포그(안개:fog) 공식

[C++]

C++ 어플리케이션에서는, Direct3D 로 거리에 응해 포그(안개:fog) 이펙트의 계산을 변경하는 것으로써, 포그(안개:fog)가 장면의 오브젝트의 색에게 주는 영향을 제어할 수 있다. D3DFOGMODE 열거형에는, 3 개의 포그(안개:fog) 공식을 식별하는 멤버가 포함되어 있다. 모든 식은, 어플리케이션이 설정하는 파라미터가 주어져 거리의 함수로서 포그(안개:fog) 계수를 계산한다. 거리 자체가 어떻게 계산될까는, 범위 베이스의 포그(안개:fog)가 유효한지 어떤지와 투영 행렬에 의해 변화한다. 상세한 것에 대하여는, 「시점으로부터의 상대 깊이대 Z 베이스의 깊이」 및 「범위 베이스의 포그(안개:fog)」를 참조할것.

[Visual Basic]

Visual Basic 로 기술된 어플리케이션에서는, Direct3D 로 거리에 응해 포그(안개:fog) 이펙트의 계산을 변경하는 것으로써, 포그(안개:fog)가 장면의 오브젝트의 색에게 주는 영향을 제어할 수 있다. CONST_D3DFOGMODE 열거에는, 3 개의 포그(안개:fog) 공식을 식별하는 멤버가 포함되어 있다. 모든 식은, 어플리케이션이 설정하는 파라미터가 주어져 거리의 함수로서 포그(안개:fog) 계수를 계산한다. 거리 자체가 어떻게 계산될까는, 범위 베이스의 포그(안개:fog)가 유효한지 어떤지와 투영 행렬에 의해 변화한다. 상세한 것에 대하여는, 「시점으로부터의 상대 깊이대 Z 베이스의 깊이」 및 「범위 베이스의 포그(안개:fog)」를 참조할것.

D3DFOG_LINEAR

이 선형 공식에서,start 는 포그(안개:fog) 이펙트가 시작되는 거리,end 는 포그(안개:fog) 이펙트가 그 이상 증가하지 않게 되는 거리,d 는 장면의 범위내에서의 깊이 (또는 시점으로부터의 거리)를 나타낸다. 오브젝트가 먼 곳이 되는에 따라 d 의 값이 증가한다. 선형 공식은 픽셀 포그(안개:fog)와 버텍스 포그(안개: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) 컬러와 원의 색의 블렌드이며, 거리의 계수이기도 하다. 이 공식은, DirectX 7,0 이 지원 하는 모든 디바이스에 적용된다. 종래부터의 램프 디바이스에 대해서는, 포그(안개:fog) 계수는 디퓨즈색성분과 스펙큐러색성분을 스케일링 해, 0.0 에서 1.0 의 범위내 (0.0 으로 1.0 을 포함한다)에 넣는다. 포그(안개:fog) 계수는, 보통, 전방 클립면을 1.0 으로서 시작되어, 후방 클립면을 0.0 으로서 감소한다.


포그(안개:fog) 파라미터

[C++]

포그(안개:fog) 파라미터는, 디바이스 렌더링 스테이트에 의해 제어된다. 픽셀 포그(안개:fog) 및 버텍스 포그(안개:fog)에서는 함께, 「포그(안개:fog) 공식」에서 설명하는 포그(안개:fog) 공식을 모두 지원 하고 있다. D3DFOGMODE 열거형은, Direct3D 로 사용하는 포그(안개:fog) 공식을 식별하는 정수를 정의한다. D3DRENDERSTATE_FOGTABLEMODE 렌더링 스테이트는, Direct3D 가 픽셀 포그(안개:fog)에 사용하는 포그(안개:fog) 모드를 제어해,D3DRENDERSTATE_FOGVERTEXMODE 렌더링 스테이트는 버텍스 포그(안개:fog)의 모드를 제어한다.

선형 포그(안개:fog) 공식을 사용할때는,D3DRENDERSTATE_FOGSTART 및 D3DRENDERSTATE_FOGEND 렌더링 스테이트를 사용해 시작 거리 및 종료 거리를 설정한다. 이러한 값을 시스템이 어떻게 해석할까는, 어플리케이션으로 픽셀 포그(안개:fog) 및 버텍스 포그(안개:fog)의 어느 쪽을 사용하고 있을까에 따라서 다르다. 픽셀 포그(안개:fog)를 사용하고 있는 경우는, z 베이스 또는 w 베이스의 깊이가 사용된다 (z 베이스 및 w 베이스의 깊이의 상세한 것에 대하여는, 「시점으로부터의 상대 깊이대 Z 베이스의 깊이」를 참조할것). 다음 표에 정리한다.

포그(안개:fog)의 종류 | 포그(안개:fog)의 시작/종료 단위
픽셀 (Z) | 디바이스 공간 [0.0, 1.0]
픽셀 (W) | 카메라 공간
버텍스 | 카메라 공간

D3DRENDERSTATE_FOGDENSITY 렌더링 스테이트는, 지수 포그(안개:fog) 공식이 유효한 때에 적용되는 포그(안개:fog) 밀도를 제어한다. 포그(안개:fog) 밀도는, 본질적으로는 가중 계수이며, 지수의 거리값을 0.0 에서 1.0 (0.0 으로 1.0 을 포함한다)에 스케일링 한다.

시스템이 포그(안개:fog) 블렌딩에 사용하는 색은,D3DRENDERSTATE_FOGCOLOR 디바이스 렌더링 스테이트를 사용해 제어한다. 상세한 것에 대하여는, 「포그(안개:fog) 컬러」 및 「포그(안개:fog) 블렌딩」을 참조할것.

[Visual Basic]

포그(안개:fog) 파라미터는, 디바이스 렌더링 스테이트에 의해 제어된다. 픽셀 포그(안개:fog) 및 버텍스 포그(안개:fog)에서는 함께, 「포그(안개:fog) 공식」에서 설명하는 포그(안개:fog) 공식을 모두 지원 하고 있다. CONST_D3DFOGMODE 열거에는, Direct3D 로 사용하는 포그(안개:fog) 공식을 식별하는 정수가 정의되고 있다. D3DRENDERSTATE_FOGTABLEMODE 렌더링 스테이트는, Direct3D 가 픽셀 포그(안개:fog)에 사용하는 포그(안개:fog) 모드를 제어해,D3DRENDERSTATE_FOGVERTEXMODE 렌더링 스테이트는 버텍스 포그(안개:fog)의 모드를 제어한다.

선형 포그(안개:fog) 공식을 사용할때는,D3DRENDERSTATE_FOGSTART 및 D3DRENDERSTATE_FOGEND 렌더링 스테이트를 사용해 시작 거리 및 종료 거리를 설정한다. 이러한 값을 시스템이 어떻게 해석할까는, 어플리케이션으로 픽셀 포그(안개:fog) 및 버텍스 포그(안개:fog)의 어느 쪽을 사용하고 있을까에 따라서 다르다. 픽셀 포그(안개:fog)를 사용하고 있는 경우는, z 베이스 또는 w 베이스의 깊이가 사용된다 (z 베이스 및 w 베이스의 깊이의 상세한 것에 대하여는, 「시점으로부터의 상대 깊이대 Z 베이스의 깊이」를 참조할것). 다음 표에 정리한다.

포그(안개:fog)의 종류 | 포그(안개:fog)의 시작/종료 단위
픽셀 (Z) | 디바이스 공간 [0.0, 1.0]
픽셀 (W) | 카메라 공간
버텍스 | 카메라 공간

D3DRENDERSTATE_FOGDENSITY 렌더링 스테이트는, 지수 포그(안개:fog) 공식이 유효한 때에 적용되는 포그(안개:fog) 밀도를 제어한다. 포그(안개:fog) 밀도는, 본질적으로는 가중 계수이며, 지수의 거리값을 0.0 에서 1.0 (0.0 으로 1.0 을 포함한다)에 스케일링 한다.

시스템이 포그(안개:fog) 블렌딩에 사용하는 색은,D3DRENDERSTATE_FOGCOLOR 디바이스 렌더링 스테이트에서 제어된다. DirectX7.CreateColorRGB 메소드를 사용해, 이 렌더링 스테이트에 유효한 컬러값을 생성한다. 상세한 것에 대하여는, 「포그(안개:fog) 컬러」 및 「포그(안개:fog) 블렌딩」을 참조할것.


포그(안개:fog) 블렌딩

[C++]

포그(안개:fog) 블렌딩이란, 「포그(안개:fog) 공식」에서 설명하도록(듯이), 장면에 표시하는 최종색을 생성하기 위해서, 포그(안개:fog) 및 오브젝트의 색에 포그(안개:fog) 계수를 적용하는 것이다. D3DRENDERSTATE_FOGENABLE 렌더링 스테이트는, 포그(안개:fog) 블렌딩을 제어한다. 다음의 코드로 가리키도록(듯이), 이 렌더링 스테이트를 TRUE 로 설정해 (디폴트는 FALSE) 포그(안개:fog) 블렌딩을 유효하게 한다.

//
// 이 예에서는, g_lpDevice 는 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다.
HRESULT hr;
hr = g_lpDevice->SetRenderState(
                     D3DRENDERSTATE_FOGENABLE,
                     TRUE);
if FAILED(hr)
    return hr;

포그(안개:fog) 블렌딩은, 픽셀 포그(안개:fog)와 버텍스 포그(안개:fog)의 양쪽 모두에 대해서 유효하게 해야 한다. 이러한 종류의 포그(안개:fog)의 사용 방법에 대해서는, 「픽셀 포그(안개:fog)」 및 「버텍스 포그(안개:fog)」를 참조할것.

[Visual Basic]

포그(안개:fog) 블렌딩이란, 「포그(안개:fog) 공식」에서 설명하도록(듯이), 장면에 표시하는 최종색을 생성하기 위해서, 포그(안개:fog) 및 오브젝트의 색에 포그(안개:fog) 계수를 적용하는 것이다. D3DRENDERSTATE_FOGENABLE 렌더링 스테이트는, 포그(안개:fog) 블렌딩을 제어한다. 다음의 코드로 가리키도록(듯이), 이 렌더링 스테이트를 TRUE 로 설정해 (디폴트는 FALSE) 포그(안개:fog) 블렌딩을 유효하게 한다.

'
'이 예에서는, g_d3dDevice 에 Direct3DDevice7 오브젝트에의
'유효한 참조가 저장 되고 있다.
'
On Local Error Resume Next

Call g_d3dDevice.SetRenderState( _
D3DRENDERSTATE_FOGENABLE, _
True);

If Err.Number <> DD_OK Then
'에러 처리 코드
End If

포그(안개:fog) 블렌딩은, 픽셀 포그(안개:fog)와 버텍스 포그(안개:fog)의 양쪽 모두에 대해서 유효하게 해야 한다. 이러한 종류의 포그(안개:fog)의 사용 방법에 대해서는, 「픽셀 포그(안개:fog)」 및 「버텍스 포그(안개:fog)」를 참조할것.


포그(안개:fog) 컬러

[C++]

픽셀 포그(안개:fog)와 버텍스 포그(안개:fog)의 양쪽 모두의 포그(안개:fog) 컬러는,D3DRENDERSTATE_FOGCOLOR 렌더링 스테이트를 사용해 설정한다. 렌더링 스테이트값은, RGBA 색 (알파 성분은 무시된다)으로서 지정하는 임의의 RGB 색이다.

다음의 C++ 코드는, 포그(안개:fog) 컬러를 흰색으로 설정한다.

/* 이 예에서는, g_lpD3DDevice 변수는 IDirect3DDevice7 인터페이스에의
* 유효한 포인터이다.
 */
HRESULT hr;

hr = g_lpd3dDevice->SetRenderState(
                    D3DRENDERSTATE_FOGCOLOR,
                    0x00FFFFFF); // 상위 8 비트는 사용되지 않는다.

if(FAILED(hr))
    return hr;
[Visual Basic]

픽셀 포그(안개:fog) 및 버텍스 포그(안개:fog)의 양쪽 모두의 포그(안개:fog) 컬러는,D3DRENDERSTATE_FOGCOLOR 렌더링 스테이트를 사용해 설정한다. 렌더링 스테이트값에는,DirectX7.CreateColorRGB 메소드가 돌려주는 RGB 색을 지정할 수 있다.

다음의 Visual Basic 코드는, 포그(안개:fog) 컬러를 흰색으로 설정한다.

'
'이 예에서는, g_d3dDevice 변수는 Direct3DDevice7 오브젝트에의
'유효한 참조로,
' g_dx 는 DirectX7 오브젝트에의 유효한 참조이다.
'
On Local Error Resume Next

Call g_d3dDevice.SetRenderState( _
D3DRENDERSTATE_FOGCOLOR, _
g_dx.CreateColorRGB(1#, 1#, 1#))

If Err.Number <> DD_OK Then
'에러 처리 코드
End If


픽셀 포그(안개:fog)

이 섹션에서는, 픽셀 포그(안개:fog)의 개념에 대해, 및 Direct3D 어플리케이션에서의 사용에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • 픽셀 포그(안개:fog)에 대해
  • 시점으로부터의 상대 깊이대 Z 베이스의 깊이
  • 픽셀 포그(안개:fog)의 사용


버텍스 포그(안개:fog)

이 섹션에서는, 버텍스 포그(안개:fog)에 대해, 및 Direct3D 어플리케이션에서의 사용에 대해 자세하게 설명한다. 설명하는 주제는 다음과 같다.

  • 버텍스 포그(안개:fog)에 대해
  • 범위 베이스의 포그(안개:fog)
  • 버텍스 포그(안개:fog)의 사용


지오메트리 블렌딩

이 섹션에서는, DirectX 7.0 의 신기능, 지오메트리 블렌딩에 대해 설명한다. 설명하는 주제는 다음과 같다.

  • 지오메트리 블렌딩에 대해
  • 블렌딩 트랜스 폼과 렌더링 스테이트
  • 블렌딩의 중량감
  • 지오메트리 블렌딩의 사용


지오메트리 블렌딩에 대해

DirectX 7.0 의 Direct3D 직접 모드에서는, Joint부가 매끄럽게 블렌드 되고 있는 각 다각형을, 특히 캐릭터를 렌더링 하는 것으로, 장면을 한층 리얼하게 표현할 수가 있다 (이러한 이펙트를 일반적으로는 "스키닝" 이라고 부른다). 이 이펙트는, 추가의 "월드" 트랜스 폼 행렬을 버텍스의 단일 세트에 적용해, 그 결과 생성되는 복수의 트랜스 폼 후의 버텍스간에 선형 블렌드를 실행해 렌더링용의 지오메트리의 단일 세트를 생성하는 것으로 실현된다. 다음에 나타내는 것은,Bend 샘플에 의해 렌더링 된 바나나에 근거하는 화면이다.

이 화면은, 지오메트리 블렌딩의 처리가 어떠한 것인지를 나타낸다. 1 회의 렌더링의 호출로, 시스템은 바나나의 버텍스를 취득해, 이 버텍스에 대해서 회전하지 않는 트랜스 폼과 단순한 회전의 트랜스 폼을 1 회씩 실행해, 그 결과 "구부러진" 바나나를 생성한다. 시스템은, 버텍스 법선 (라이팅이 유효한 경우) 뿐만이 아니라 버텍스 위치 좌표도 블렌드 한다. 어플리케이션은 2 개의 블렌딩 방법으로 한정되는 것은 아니다. Direct3D 는, 최대 4 개(살)이 다른 월드 행렬 (표준 월드 행렬의 D3DTRANSFORMSTATE_WORLD 등) 간에서 지오메트리를 블렌드 할 수 있다.

[C++]

주 : 라이팅이 유효하게 되어 있는 경우, 버텍스 법선이, 대응하는 월드 뷰 행렬의 역행열에 의해 트랜스 폼 된다. 이 때, 중요는, 버텍스 위치 좌표의 계산의 경우와 같게 행해진다. D3DRENDERSTATE_NORMALIZENORMALS 렌더링 스테이트가 TRUE 로 설정되어 있는 경우는, 결과의 법선 벡터가 시스템에 의해 정규화된다.

가동 결합부가 있는 모델의 경우, 지오메트리 블렌딩을 사용하지 않고 부분 마다 렌더링 되는 것이 많다. 예를 들어, 인간의 팔의 3D 모델을 생각한다. 가장 단순하게 해, 팔에는 신체로 연결되는 상완과 손으로 연결되는 팔뚝이 있다. 2 개의 팔은 함께 팔꿈치로 연결되어 있어 팔뚝은 이 정도치좌표로 회전한다. 어플리케이션으로 팔을 렌더링 하는 경우, 상완과 팔뚝의 버텍스 데이터는 보관 유지되어 각각 개별의 월드 트랜스 폼 행렬이 적용된다. 다음의 코드는 이것을 나타낸다.

typedef struct _Arm {
D3DVERTEX upper_arm_verts[200];
D3DMATRIX matWorld_Upper;

D3DVERTEX lower_arm_verts[200];
D3DMATRIX matWorld_Lower;
} ARM, *LPARM;

ARM MyArm; // 이것은 초기화할 필요가 있다.

팔을 렌더링 하려면 , 다음의 코드로 가리키도록(듯이), 렌더링의 호출을 2 회 실행한다.

// 상완을 렌더링 한다.
d3dDevice->SetTransform( D3DTRANSFORMSTATE_WORLD, &MyArm.matWorld_Upper );
d3dDevice->DrawPrimitive( D3DPT_TRIANGLELIST, D3DFVF_VERTEX,
MyArm.upper_arm_verts, 200, 0 );

// 팔뚝을 렌더링 해, 팔을 관절로 잇는 월드 행렬을 갱신한다.
// 팔꿈치로π/4 라디안 (45о) 두개회전하도록(듯이) 한다.
MyArm.matWorld_Lower = RotateMyArm(MyArm.matWorld, pi/4);
d3dDevice->SetTransform( D3DTRANSFORMSTATE_WORLD, &MyArm.matWorld_Lower );
d3dDevice->DrawPrimitive( D3DPT_TRIANGLELIST, D3DFVF_VERTEX,
MyArm.lower_arm_verts, 200, 0 );
[Visual Basic]

주 : 라이팅이 유효하게 되어 있는 경우, 버텍스 법선이, 대응하는 월드 뷰 행렬의 역행열에 의해 트랜스 폼 된다. 이 때, 중요는, 버텍스 위치 좌표의 계산의 경우와 같게 행해진다. D3DRENDERSTATE_NORMALIZENORMALS 렌더링 스테이트가 TRUE 로 설정되어 있는 경우는, 결과의 법선 벡터가 시스템에 의해 정규화된다.

가동 결합부가 있는 모델의 경우, 지오메트리 블렌딩을 사용하지 않고 부분 마다 렌더링 되는 것이 많다. 예를 들어, 인간의 팔의 3D 모델을 생각한다. 가장 단순하게 해, 팔에는 신체로 연결되는 상완과 손으로 연결되는 팔뚝이 있다. 2 개의 팔은 함께 팔꿈치로 연결되어 있어 팔뚝은 이 정도치좌표로 회전한다. 어플리케이션으로 팔을 렌더링 하는 경우, 상완과 팔뚝의 버텍스 데이터는 보관 유지되어 각각 개별의 월드 트랜스 폼 행렬이 적용된다. 다음의 코드는 이것을 나타낸다.

Type Arm
upper_arm_verts(200) As D3DVERTEX
matWorld_Upper As D3DMATRIX

lower_arm_verts(200) As D3DVERTEX
matWorld_Lower As D3DMATRIX
End Type

Dim MyArm As Arm '이것은 초기화할 필요가 있다.

팔을 렌더링 하려면 , 다음의 코드로 가리키도록(듯이), 렌더링의 호출을 2 회 실행한다.

'상완을 렌더링 한다.
Call d3DDevice.SetTransform(D3DTRANSFORMSTATE_WORLD, MyArm.matWorld_Upper)
Call d3DDevice.DrawPrimitive(D3DPT_TRIANGLELIST, D3DFVF_VERTEX, _
MyArm.upper_arm_verts, 200, 0)

'팔뚝을 렌더링 해, 팔을 관절로 잇는 월드 행렬을 갱신한다.
'팔꿈치로π/4 라디안 (45о) 두개회전하도록(듯이) 한다.
MyArm.matWorld_Lower = RotateMyArm(MyArm.matWorld, pi / 4)
Call d3DDevice.SetTransform(D3DTRANSFORMSTATE_WORLD, MyArm.matWorld_Lower)
Call d3DDevice.DrawPrimitive(D3DPT_TRIANGLELIST, D3DFVF_VERTEX, _
MyArm.lower_arm_verts, 200, 0)

다음의 화면은,Bend 샘플로 렌더링 한 바나나를, 이 테크닉을 사용하기 위해서 수정한 것이다.

블렌드 된 지오메트리와 블렌드되어 있지 않은 지오메트리의 차이는 분명하다. 이 예에서도 그 차이는 분명히 안다. 실제의 어플리케이션에서는, 각 모델을 "Joint" 해도, 그만큼 Joint부가 눈에 띌 것은 없다. 그러나, Joint부가 보기 흉하게 표시되는 일도 있다. 이것은, 모데르데자이나에 있어 향후의 과제이다.

Direct3D 의 지오메트리 블렌딩에서는, 종래의 세그먼트(segment) 모델 시나리오를 사용할 수도 있다. 지오메트리 블렌딩을 사용하는 경우에도 부하가 걸린다. 즉, 분할되고 있는 각각의 오브젝트의 표시 품질을 올리기 위해서(때문에) 렌더링시에 블렌딩 계산을 한 끝에, 이것이 적용된다. 이러한 추가 처리에 의한 영향을 최소한으로 억제하기 위해서(때문에), Direct3D 지오메트리 파이프라인은, 가능한 한 오버헤드를 발생시키지 않고 지오메트리를 블렌드 할 수 있도록(듯이) 최적화된다. 어플리케이션에서는 Direct3D 의 지오메트리 블렌딩 서비스를 유효하게 사용하는 것으로, 퍼포먼스에의 심각한 영향을 피하면서, 캐릭터를 보다 진짜인것 같게 표현할 수가 있다.


블렌딩 트랜스 폼과 렌더링 스테이트

[C++]

IDirect3DDevice7::SetTransform 및 IDirect3DDevice7::SetTransform 메소드는, 지오메트리가 블렌드 될 때의 행렬을 식별하는 D3DTRANSFORMSTATETYPE 열거형의 D3DTRANSFORMSTATE_WORLD ,D3DTRANSFORMSTATE_WORLD1 ,D3DTRANSFORMSTATE_WORLD2 , 및 D3DTRANSFORMSTATE_WORLD3 멤버를 인식한다 (D3DTRANSFORMSTATE_WORLD 멤버가 "D3DTRANSFORMSTATE_WORLD0" 로서 인식되는 일도 있다).

D3DRENDERSTATETYPE 열거형에는, 지오메트리 블렌딩을 유효하게 해 제어하는 D3DRENDERSTATE_VERTEXBLEND 렌더링 스테이트가 포함된다. 이 렌더링 스테이트의 유효값은,D3DVERTEXBLENDFLAGS 열거형에 의해 정의된다. 이 열거형에는, D3DVBLEND_DISABLE, D3DVBLEND_1 WEIGHT, D3DVBLEND_2 WEIGHT, D3DVBLEND_3WEIGHT 멤버등이 포함된다. 지오메트리브렌딘이 유효하게 되어 있는 경우, 버텍스 포맷에는 블렌딩의 적절한 가중값이 포함되지 않으면 안 된다.

[Visual Basic]

Direct3DDevice7.SetTransform 및 Direct3DDevice7.SetTransform 메소드는, 지오메트리가 블렌드 될 때의 행렬을 식별하는 CONST_D3DTRANSFORMSTATETYPE 열거의D3DTRANSFORMSTATE_WORLD ,D3DTRANSFORMSTATE_WORLD1 ,D3DTRANSFORMSTATE_WORLD2 , 및 D3DTRANSFORMSTATE_WORLD3 멤버를 인식한다 (D3DTRANSFORMSTATE_WORLD 멤버가 "D3DTRANSFORMSTATE_WORLD0" 로서 인식되는 일도 있다).

CONST_D3DRENDERSTATETYPE 열거에는, 지오메트리 블렌딩의 유효하게 해 제어하는 D3DRENDERSTATE_VERTEXBLEND 렌더링 스테이트가 포함된다. 이 렌더링 스테이트의 유효값은,CONST_D3DVERTEXBLENDFLAGS 열거형에 의해 정의된다. 이 열거형에는, D3DVBLEND_DISABLE, D3DVBLEND_1 WEIGHT, D3DVBLEND_2 WEIGHT, D3DVBLEND_3WEIGHT 멤버등이 포함된다. 지오메트리브렌딘이 유효하게 되어 있는 경우, 버텍스 포맷에는 블렌딩의 적절한 가중값이 포함되지 않으면 안 된다.

참조

블렌딩 행렬의 설정,지오메트리 블렌딩의 유효화,블렌딩의 중량감


블렌딩의 중량감

블렌딩의 중량감 ("베타의 중량감" 이라고 부를 때도 있다)은, 지정된 월드 행렬에 의해 버텍스가 받는 영향의 범위를 제어한다. 블렌딩의 중량감이란, 0.0 ~ 1.0 의 범위의 부동 소수점값이며, 버텍스 포맷으로 encode 된다. 값이 0.0 의 경우, 버텍스는 그 행렬로 블렌드 되지 않는다. 값이 1.0 의 경우, 버텍스는 행렬의 영향을 모두 받는다.

[C++]

지오메트리 블렌딩의 중량감은, 버텍스 포맷으로 encode 되어 「버텍스 포맷에 대하며」로 설명하도록(듯이), 각 버텍스의 위치 좌표의 바로 후에 나타난다. Direct3D 렌더링 메소드로 지정하는 버텍스 기술에 D3DFVF_XYZB1 ~ D3DFVF_XYZB5 의유연한 버텍스 포맷 플래그의 어느쪽이든을 포함하는 것으로, 버텍스 포맷에 블렌딩의 중량감을 지정한다.

[Visual Basic]

지오메트리 블렌딩의 중량감은, 버텍스 포맷으로 encode 되어 「버텍스 포맷에 대하며」로 설명하도록(듯이), 각 버텍스의 위치 좌표의 바로 후에 나타난다. Direct3D 렌더링 메소드로 지정하는 버텍스 기술에 D3DFVF_XYZB1 ~ D3DFVF_XYZB5 의유연한 버텍스 포맷 플래그의 어느쪽이든을 포함하는 것으로, 버텍스 포맷에 블렌딩의 중량감을 지정한다.

중요 된 블렌드 행렬간으로, 시스템에 의해 선형 블렌드가 실행된다. 다음에, 정식적 블렌딩 공식을 나타낸다.

이 공식에서는,vBlend 는 출력 버텍스이며, v 요소는 적용 후의 월드 행렬 (D3DTRANSFORMSTATE_WORLDn)에 의해 생성되는 버텍스이다. W 요소는, 버텍스 포맷내의 대응하는 중량감이다. n 개의 행렬간에 블렌드 되는 버텍스는,n–1 개의 블렌딩의 중량감을 가질 수가 있다 (마지막 블렌딩 행렬을 제외해, 각 블렌딩 행렬에 1 개의 중량감). 마지막 월드 행렬의 중량감은, 이 공식에서는 Σ 으로 나타내도록(듯이), 중량감의 합계가 1.0 이 되도록(듯이) 시스템에 의해 자동적으로 생성된다. 이 공식은, 현재 Direct3D 가 지원 하고 있는 케이스에 맞추어, 다음과 같이 간략화할 수 있다.

이 공식은, 정식적 블렌딩 공식을, 2, 3, 및 4 개의 블렌드 행렬의 케이스 (현재 지원 되고 있는 것은 이만큼)에 맞추어 간략화한 것이다.

주 : Direct3D 에서는, 최대 5 개의 블렌딩의 중량감을 가지는 버텍스를 정의하는 유연한 버텍스 포맷 기술자를 포함할 수가 있지만, 이 릴리스의 DirectX 에서는 3 개까지 밖에 사용할 수 없다.


지오메트리 블렌딩

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

  • 블렌딩용의 버텍스의 정의
  • 블렌딩 행렬의 설정
  • 지오메트리 블렌딩의 유효화


유저 정의 클립면

Direct3D 를 사용하면, 어플리케이션에서는, 임의에 정의된 클립면에 따라 지오메트리를 잘라낼 수가 있다. 이 주제에서는, 유저 정의 클립면에 도착해, 및 어플리케이션으로 유저 정의 클립면을 사용하는 방법에 대해 설명한다.

  • 유저 정의 클립면이란
  • 유저 정의 클립면의 사용


유저 정의 클립면이란

유저 정의 클립면을 사용 하면, 어플리케이션에서는, 임의의 클립면을 적용해 장면의 지오메트리를 클리핑 할 수가 있다. 클립면은 일반 평면식에서 정의된다. 시스템에서는 이 식을 월드 공간의 것이라고 본다.

다음의 그림은,Spheremap 샘플을 이용한 것으로, 클리핑의 이펙트를 강조하기 위해서 약간 수정을 더하고 있다 (샘플은, 와이어 프레임으로 렌더링 하도록(듯이) 수정되어 뒷면 컬링(Culling)는 무효가 되어 있다). 이 화면에는 클립면은 적용되지 않았다.

유저 정의 클립면을 적용 하면, 장면의 지오메트리를 간단하게 클리핑 할 수가 있다. 이하의 부등식이 성립되는 경우, 월드 좌표 (x, y, z)의 점이 면에서 단락지어진 반의 공간으로부터 잘라내진다.

이 공식에서는, A, B, C, 및 D 는, 면을 정의하기 위해서 어플리케이션으로부터 시스템에 제공되는 계수이다. 클립 얼굴 또는 그 후 (분)편에게 있는 점이 장면으로부터 잘라내진다. 다음의 화면은 2 개의 티폿(주전자)를 나타낸다. 2 개(살)이 다른 면에서 잘라내지고 있다.

좌측의 티폿(주전자)를 잘라낸 면의 계수는 [A = -1. 0, B = 0.0, C = 0.0, D = 0.0] 이며, x >=0 를 채우는 버텍스가 모두 잘라내진다. 우측의 티폿(주전자)를 절취면은, 계수 [A = 1.0, B = 0.0, C = 1.0, D = 0.0] 으로 정의되어 z >= 0.0 을 채우는 버텍스가 모두 잘라내진다.

지오메트리는, 복수의 면을 사용해 클리핑 할 수가 있다. 복수의 클립면을 사용하는 경우, 각면에 의해 정의되는 단락지어진 공간의 편성이 렌더링 영역이 된다. 다음의 화면은, 2 개의 면에서 클리핑 된 티폿(주전자)를 나타낸다.

이 티폿(주전자)는 2 개의 면에서 잘라내지고 있다. 1 개(살)은 계수 [A = 1.0, B = 0.0, C = 0.0, D = 0.0] 의 면에서, 이제(벌써) 1 개(살)은 계수 [A = 0.0, B = -1. 0, C = 0.0, D = 0.0] 으로 정의되는 면이다.

[C++]

Direct3D 에서는 최대 32 개 (D3DMAXUSERCLIPPLANES)의 클립면에 의한 절취가 가능하지만, 디바이스로 최대 몇개(살)의 클립면을 사용할 수 있을까는 가지각색이다. 이 점을 잘못하지 않게, 현재의 디바이스 (D3DDEVICEDESC7 구조체의 wMaxUserClipPlanes 멤버)의 디바이스 기능을 항상 체크하도록(듯이) 한다.

[Visual Basic]

Direct3D 에서는 최대 32 개의 클립면에 의한 절취가 가능하지만, 디바이스로 최대 몇개(살)의 클립면을 사용할 수 있을까는 가지각색이다. 이 점을 잘못하지 않게, 현재의 디바이스 (D3DDEVICEDESC7 형의 nMaxUserClipPlanes 멤버)의 디바이스 기능을 항상 체크하도록(듯이) 한다.

여기에 나타내는 단순한 지오메트리 클리핑도 많은 경우는 유효한 수단으로서 사용되지만, 유저 정의 클립면은 그것보다 한층 더 많은 용도를 가진다. 유저 정의 클립면과 스텐실 버퍼를 조합하면(자), 캡핑, 간섭 테스트등의 고도의 태스크를 실행할 수 있다.


유저 정의 클립면의 사용

유저 정의 클립면은, 간단하게 정의, 조작, 및 유효하게 할 수 있다. 이하의 주제에서는, 유저 정의 클립면의 공통 태스크에 대해 설명한다.

  • 클립면의 설정과 취득
  • 클립면의 유효/무효


환경 맵핑

이 섹션에서는, Direct3D 직접 모드의 일반적인 2 종류의 환경 맵핑의 실행에 대해 설명한다. 그래픽스 업계에서는 다종 다양한 환경 맵핑이 사용되고 있지만, 이하의 주제에서는, 가장 일반적인 큐브 환경 맵 및 구(공)체 환경 맵핑에 대해 설명한다.

  • 환경 맵핑이란
  • 큐브 환경 맵
  • 구(공)체 환경 맵핑


환경 맵핑이란

환경 맵핑이란, 반사성의 높은 표면을 레이 트래싱을 사용하지 않고 시뮬레이트 하는 방법이다. 실제, 환경 맵핑에서는, 오브젝트의 주위의 경치를 포함한 특수한 텍스쳐 맵이 그 오브젝트 자체에 적용된다. 그 결과, 반사성을 가지는 표면에는, 충분히 사람의 눈을 속일 수 있는 정도로 주위의 경치가 비친다. 레이 트래싱을 실행했을 경우에 생기는 계산 부하도 발생하지 않는다.

다음의 화면은,Spheremap 샘플 (C++) 의 것이다. 이름으로부터 알 수 있듯이, 이 샘플에서는 "구(공)체 환경 맵핑" 으로 불리는 환경 맵핑을 사용하고 있다. 상세한 것에 대하여는, 「구(공)체 환경 맵핑」을 참조할것.

이 티폿(주전자)는 주위의 경치를 반사하고 있는 것처럼 보이지만, 실제로는 텍스쳐가 적용되고 있다. 환경 맵핑은, 텍스쳐 (특수한 계산으로 요구한 텍스쳐 좌표를 조합한 것)를 사용하기 위해(때문에) 순간에 실행된다.


큐브 환경 맵

큐브 환경 맵에서는, 오브젝트의 주위의 공간 또는 라이팅의 이펙트가 그 오브젝트의 표면을 따라 적용된다. 이것은 입방체의 내부의 6 개의 면에 의해 표현된다. 이 섹션에서는 이하의 토픽에 대해 설명한다.

  • 큐브 환경 맵이란
  • 큐브 환경 맵 표면의 생성
  • 큐브 환경 맵 표면에의 액세스
  • 큐브 환경 맵의 밉맵화
  • 큐브 환경 맵에의 렌더링
  • 큐브 환경 맵의 텍스쳐 좌표


구(공)체 환경 맵핑

구(공)체 환경 맵핑은, 많은 경우 "구(공)체 맵핑" 으로 불리지만, 오브젝트의 주위의 공간의 화면과 라이팅의 이펙트를 그 오브젝트의 표면을 따라 붙여 간다. 이 때, 오브젝트의 주위의 공간은, 특수한 포맷의 텍스쳐 맵에 encode 된다. 이하의 주제에서는, 구(공)체 맵핑의 개념에 대해, 및 Direct3D 어플리케이션에서의 구(공)체 맵핑의 사용 방법에 대해 설명한다.

  • 구(공)체 환경 맵이란
  • 구(공)체 환경 맵의 텍스쳐 좌표
  • 구(공)체 환경 맵의 적용


범프 맵핑

여기에서는, Direct3D 에서의 범프 맵핑의 실행에 대해 설명한다. 이하의 주제에서는, 범프 맵핑을 소개해, 그 주요한 개념을 특정 및 정의해, 어플리케이션에서의 범프 맵핑의 사용 방법에 대해 설명한다.

  • 범프 맵핑이란
  • 범프 맵 픽셀 포맷
  • 범프 맵핑의 공식
  • 범프 맵핑의 사용


범프 맵핑이란

범프 맵핑은, 소수의 다각형만으로 예쁘게 테셀레이트 된 오브젝트의 반사 상태를 시뮬레이트 하는, 특수한 스펙큐러 또는 디퓨즈 환경 맵핑이다. 다음의 화면은,BumpEarth 샘플에 근거해 범프 맵핑의 이펙트를 나타낸다.

좌측의 지구는, 지구의 표면의 화면으로 텍스쳐 처리되어 스펙큐러 환경 맵이 적용되고 있다. 우측의 지구도 완전히 같지만, 범프 맵이 적용되고 있다. 2 번째의 지구의 화면의 다각형수는, 1 번째의 화면의 다각형수로 변함없다.

Direct3D 의 범프 맵핑에서는, 개발자는 델타값에 의한 윤곽선의 정보를 제공하는 것으로부터, 범프 맵핑은, 정확하게는 "스펙큐러 또는 디퓨즈 환경 맵의 픽셀 단위에서의 텍스쳐 좌표의 보정" 과 기술할 수 있다. 윤곽선의 정보는, 시스템에 의해 다음의 텍스쳐 스테이지의 환경 맵의 u 및 v 텍스쳐 좌표에 적용된다. 델타값은, 범프 맵 표면의 픽셀 포맷으로 encode 된다. 상세한 것에 대하여는, 「범프 맵 픽셀 포맷」을 참조할것.

BumpEarth 샘플에서는, 고도 맵을 사용해 윤곽선데이터를 저장 한다. 샘플을 시작 하면, 고도 맵내의 픽셀이 처리되어 적절한 u 및 v 가 계산된다 (인접하는 4 개의 픽셀을 기준으로 한, 각 픽셀의 상대 고도로 기초를 둔다).

주 : 본래, Direct3D 에서는 고도 맵을 지원 하고 있지 않다. 고도 맵은, 윤곽선데이터를 저장 및 시각화하는데 편리한 포맷인 것에 지나지 않는다. 전의 화면은 고도 맵을 기초를 두어 생성 된 것으로, BumpEarth 샘플에서는 이 고도 맵을 사용해, Direct3D 에 제공하는 범프 맵을 생성하고 있다. 이 화면은 설명을 목적으로 나타낸 것이다. 어플리케이션에서는 윤곽선정보를 어떠한 포맷에서도 저장 할 수 있어 또,BumpWaves 샘플 과 같이 각각의 범프 맵을 생성할 수도 있다.

다음은, BumpEarth 샘플로 사용하는 고도 맵 화면이다. 이 샘플에서는, 이것을 사용해, 범프 맵 텍스쳐의 픽셀 포맷으로 encode 되는 델타값을 계산한다.

범프 맵핑은, 복수의 텍스쳐 블렌딩 서비스에 완전하게 의존하고 있어, 디바이스는 적어도 2 개의 블렌딩 스테이지 (1 개(살)은 범프 맵용, 이제(벌써) 1 개(살)은 환경 맵용)를 지원 하고 있을 필요가 있다. 베이스 텍스쳐 맵을 적용하려면 , 최저 3 개의 텍스쳐 블렌딩 스테이지가 요구된다 (가장 일반적인 경우). 다음의 그림은, 텍스쳐 블렌딩 cascade에 있어서의, 베이스 텍스쳐, 범프 맵, 및 환경 맵간의 관계를 나타낸다.

텍스쳐 스테이지를 적절히 준비해, 범프 맵핑을 유효하게 할 필요가 있다. 이 태스크에 대해서는, 「범프 맵핑 파라미터의 설정」으로 설명한다.


범프 맵 픽셀 포맷

범프 맵이란, 특수한 픽셀 포맷을 사용하는 DirectDraw 표면 오브젝트이다. 적, 초록, 및 파랑의 색성분을 저장 하는 것이 아니라, 범프 맵의 각 픽셀은,u 및 v 의 델타값 (Du 및 Dv)을 저장 해, 휘도(Luminance) L. (을)를 저장 하면 간 있다. 이러한 값은, 「범프 맵핑의 공식」에서 설명하도록(듯이), 시스템에 의해 적용된다.

[C++]

그 외의 표면의 경우와 같이,DDPIXELFORMAT 구조체를 사용해 범프 맵 픽셀 포맷을 지정한다. 이 구조체의 dwFlags 멤버의 DDPF_BUMPDUDV 플래그는, 범프 맵 텍스쳐의 픽셀 포맷을 식별한다. 이 플래그가 있는 경우,dwBumpBitCount,dwBumpDuBitMask,dwBumpDvBitMask, 및 dwBumpLuminanceBitMask 멤버는, 범프 맵의 비트 깊이 및 각 픽셀 컴퍼넌트의 마스크값을 기술하기 위해서 사용할 수 있다.

픽셀의 Du 및 Dv 컴퍼넌트는, –1. 0 ~ +1. 0 의 범위의 부호 첨부값이다. 휘도(Luminance) 컴퍼넌트가 사용되고 있는 경우, 이 값은 0 ~ 255 의 범위의 부호 없음 정수값이다.

주 : IDirect3DDevice7::EnumTextureFormats 메소드를 호출해, 지원 되고 있는 범프 맵 픽셀 포맷을 열거할 필요가 있다. 상세한 것에 대하여는, 「범프 맵핑의 지원의 검출」을 참조할것.

[Visual Basic]

그 외의 표면의 경우와 같이,DDPIXELFORMAT 형을 사용해 범프 맵 픽셀 포맷을 지정한다. 이 형태의 lFlags 멤버의 DDPF_BUMPDUDV 플래그는, 범프 맵 텍스쳐의 픽셀 포맷을 식별한다. 이 플래그가 있는 경우,lBumpBitCount,lBumpDuBitMask,lBumpDvBitMask, 및 lBumpLuminanceBitMask 멤버는, 범프 맵의 비트 깊이 및 각 픽셀 컴퍼넌트의 마스크값을 기술하기 위해서 사용할 수 있다.

픽셀의 Du 및 Dv 컴퍼넌트는, –1. 0 ~ +1. 0 의 범위의 부호 첨부값이다. 휘도(Luminance) 컴퍼넌트가 사용되고 있는 경우, 이 값은 0 ~ 255 의 범위의 부호 없음 정수값이다.

주 : 지원 되고 있는 범프 맵 픽셀 포맷을 열거해, 사용하는 픽셀 포맷이 유효한 것을 확인할 필요가 있다. Direct3DDevice7.GetTextureFormatsEnum 메소드를 호출해, 텍스쳐 포맷의 Direct3DEnumPixelFormats 열거 클래스에의 참조를 취득한다. 이 열거를 사용해, 범프 맵 포맷 등 지원 되고 있는 텍스쳐 포맷의 정보를 취득한다. 상세한 것에 대하여는, 「범프 맵핑의 지원의 검출」


범프 맵핑의 공식

[C++]

Direct3D 에서는, 각 범프 맵 픽셀의 Du 및 Dv 컴퍼넌트에 다음의 공식을 적용한다.

이 공식에서는,Du 및 Dv 변수는 범프 맵 픽셀로부터 직접 취득되어 출력 델타값 Du' 및 Dv' 를 생성하기 위해서 2×2 행렬로 트랜스 폼 된다. 시스템에서는, 이 출력값을 사용해, 다음의 텍스쳐 스테이지의 환경 맵을 처리하는 텍스쳐 좌표를 수정한다. 트랜스 폼 행렬의 계수는,D3DTSS_BUMPENVMAT00 ,D3DTSS_BUMPENVMAT10 ,D3DTSS_BUMPENVMAT01 , 및 D3DTSS_BUMPENVMAT11 텍스쳐 스테이지 스테이트에서 설정한다.

u 및 v 델타값 외에도, 시스템에서는, 다음의 블렌딩 스테이지의 환경 맵의 색조정에 사용하는 휘도(Luminance)를 계산할 수 있다.

이 공식에서는,L' 는 계산되는 출력 휘도(Luminance)이다. L 변수는 범프 맵 픽셀로부터 취득되는 휘도(Luminance)이며, 스케일링 계수 S 로 곱셈되어 변수 O 의 값으로 오프셋(offset) 된다. D3DTSS_BUMPENVLSCALE 및 D3DTSS_BUMPENVLOFFSET 텍스쳐 스테이지 스테이트는, 공식의 변수 S 및 O 의 값을 제어한다. 이 공식이 적용되는 것은, 범프 맵을 포함한 스테이지의 텍스쳐 블렌딩 처리가 D3DTOP_BUMPENVMAPLUMINANCE 로 설정되어 있는 경우뿐이다. D3DTOP_BUMPENVMAP 를 사용할때는,L' 의 값에 1.0 이 사용된다.

출력 델타값 Du' 및 Dv' 의 계산 후, 시스템에서는, 이러한 값을 다음의 텍스쳐 스테이지의 텍스쳐 좌표에 추가해, 선택되고 있는 색의 휘도(Luminance)를 조정해, 다각형에 적용하는 색을 생성한다.

[Visual Basic]

Direct3D 에서는, 각 범프 맵 픽셀의 Du 및 Dv 컴퍼넌트에 다음의 공식을 적용한다.

이 공식에서는,Du 및 Dv 변수는 범프 맵 픽셀로부터 직접 취득되어 출력 델타값 Du' 및 Dv' 를 생성하기 위해서 2×2 행렬로 트랜스 폼 된다. 시스템에서는, 이 출력값을 사용해, 다음의 텍스쳐 스테이지의 환경 맵을 처리하는 텍스쳐 좌표를 수정한다. 트랜스 폼 행렬의 계수는,D3DTSS_BUMPENVMAT00 ,D3DTSS_BUMPENVMAT10 ,D3DTSS_BUMPENVMAT01 , 및 D3DTSS_BUMPENVMAT11 텍스쳐 스테이지 스테이트에서 설정한다.

u 및 v 델타값 외에도, 시스템에서는, 다음의 블렌딩 스테이지의 환경 맵의 색조정에 사용하는 휘도(Luminance)를 계산할 수 있다.

이 공식에서는,L' 는 계산되는 출력 휘도(Luminance)이다 (L' 는, 0.0 으로 1.0 을 포함한 0.0 ~ 1.0 의 범위에 고정된다). L 변수는 범프 맵 픽셀로부터 취득되는 휘도(Luminance)이며, 스케일링 계수 S 로 곱셈되어 변수 O 의 값으로 오프셋(offset) 된다. D3DTSS_BUMPENVLSCALE 및 D3DTSS_BUMPENVLOFFSET 텍스쳐 스테이지 스테이트는, 공식의 변수 S 및 O 의 값을 제어한다. 이 공식이 적용되는 것은, 범프 맵을 포함한 스테이지의 텍스쳐 블렌딩 처리가 D3DTOP_BUMPENVMAPLUMINANCE 로 설정되어 있는 경우뿐이다. D3DTOP_BUMPENVMAP 를 사용할때는,L' 의 값에 1.0 이 사용된다.

출력 델타값 Du' 및 Dv' 의 계산 후, 시스템에서는, 이러한 값을 다음의 텍스쳐 스테이지의 텍스쳐 좌표에 추가해, 선택되고 있는 색의 휘도(Luminance)를 조정해, 다각형에 적용하는 색을 생성한다.


범프 맵핑의 사용

이 섹션의 이하의 주제에서는, Direct3D 의 범프 맵핑을 사용할 때에 실행해야 하는 가장 일반적인 태스크에 대해 자세하게 설명한다.

  • 범프 맵핑의 지원의 검출
  • 범프 맵 텍스쳐의 생성
  • 범프 맵핑 파라미터의 설정


빌보드화

3D 신을 생성 하면 와, 2D 오브젝트를 3D 오브젝트인것 같이 표시하는 것에 의해 퍼포먼스를 향상할 수 있는 일이 있다. 이 생각이, 빌보드 처리 기술의 기본으로 되어 있다.

보통의 의미에서의 빌보드는, 도로 가의 게시판이다. Direct3D 어플리케이션은, 직사각형 솔리드를 정의해, 거기에 텍스쳐를 적용하는 것으로, 이런 종류의 빌보드를 간단하게 생성, 렌더링 할 수 있다. 3D 그래픽스에서의 특수한 의미에서의 빌보드는, 이것을 확장한 것이다. 이 의미에서의 빌보드 처리의 목적은, 2D 오브젝트를 3D 오브젝트와 같이 보이는 것이다. 이 기술은, 오브젝트의 화면을 포함한 텍스쳐를 직사각형 원시적으로 적용하는 것이다. 이 프리미티브는, 정면이 항상 뷰아의 분을 향하도록(듯이) 회전된다. 이 오브젝트의 화면은 직사각형이 아니어도 문제 없다. 빌보드의 부분을 투명하게 해, 표시하고 싶지 않은 빌보드 화면의 부분을 불가시로 할 수 있다.

많은 게임에서, 애니메이션 한 스프라이트에 빌보드 처리가 채용되고 있다. 예를 들어, 플레이어가 3D 의 미로를 이동 하면 와, 수집할 수 있는 무기나 포상이 표시된다. 이것들은, 직사각형 원시적으로 텍스쳐를 적용한 전형적인 2D 화면이다. 빌보드 처리는, 게임에서 나무나 관목의 화면을 렌더링 하기 위해서 사용되는 것이 많다.

빌보드에 화면을 적용 하면나무는, 최초로, 정면이 뷰아의 분을 향하도록(듯이) 직사각형 프리미티브를 회전해야 한다. 다음에, 이 프리미티브를 배치 장소에 평행이동 해야 한다. 그 후, 이 원시적으로 텍스쳐를 적용할 수 있다.

빌보드 처리는, 대칭적인 오브젝트, 특히 수직 축으로 대해 대칭적인 오브젝트의 처리에 최적이다. 또, 빌보드 처리에는, 시점의 높이가 그다지 오르지 않는 것이 필요하다. 유저가 빌보드를 위로부터 보는 것이 허락되고 있는 경우, 그 오브젝트가 3D 는 아니고 2D 인 것을 곧바로 알아 버린다.


운, 연기, 증기

운, 연기, 증기간, 모두, 빌보드 처리 기술을 확장해 생성 할 수 있다 ( 「빌보드화」를 참조할것). 1 개의 축이 아니라 2 개의 축을 중심으로 빌보드를 회전하는 것으로, 뷰아가 빌보드를 어느 각도로부터에서도 볼 수가 있다. 보통, 어플리케이션에서는 수평축과 수직축을 중심으로 빌보드를 회전한다.

간단한 구름을 생성 하기 위한(해), 정면이 뷰아의 분을 향하도록(듯이) 1 개(살) 또는 2 개의 축을 중심으로 직사각형 프리미티브를 회전한다. 다음에, 구름과 같은 텍스쳐를 투명도와 함께 이 원시적으로 적용한다. 투명도가 있는 텍스쳐의 프리미티브에의 적용의 상세한 것에 대하여는, 「텍스쳐 블렌딩」을 참조할것. 구름을 애니메이션 하려면 , 일련의 텍스쳐를 연속해 적용한다.

프리미티브의 그룹에서 구름을 형성하면, 보다 복잡한 구름을 생성 할 수 있다. 이 경우, 구름의 각 부분이 직사각형 원시적으로 된다. 이러한 프리미티브를 각각 독립에 연속적으로 이동해, 동적인 안개와 같이 보일 수가 있다. 다음의 그림에 이것을 나타낸다.

연기는, 구름과 같은 방법으로 표시한다. 보통, 연기에서는 복잡한 구름과 같이 복수의 빌보드가 필요하다. 연기는 연속해 꾸불꾸불하거나 상승하므로, 서 오르는 연기를 형성하는 빌보드를 이동시키는 것이 필요하다. 연기가 상승하거나 소산 하면나무는, 빌보드를 추가해야 하는 것이 있다.

증기나무는, 상승하지 않는 연기와 같은 것이다. 증기는, 서 오르는 연기와 같이 서서히 소산한다. 다음의 그림은, 증기나무를 시뮬레이트 하기 위해서 빌보드를 사용하는 기술을 나타낸다.


화, 불길, 폭발 등

어플리케이션은 Direct3D 를 사용해, 에너지를 발하는 자연현상을 시뮬레이션 할 수 있다. 예를 들어, 불길과 같은 텍스쳐를 빌보드 세트에 적용해, 불을 표현할 수 있다. 이것이 특히 효과적인 것은, 불의 텍스쳐를 연속적으로 사용해, 불타는 빌보드 각각의 위에의염을 애니메이션 하는 경우이다. 빌보드 마다 애니메이션 재생의 속도를 바꾸면(자), 불길의 리얼리티가 늘어난다. 서로 섞인 3D 의 불길에 보이려면 , 빌보드를 거듭해 맞추어 빌보드 위에의 텍스쳐를 거듭해 맞추면 좋다.

섬광은, 장면의 모든 원시적으로 서서히 밝아지는 라이트 맵을 적용해 시뮬레이션 할 수 있다. 이것은 오버헤드의 높은 기술이지만, 국소적인 불길이나 섬광의 시뮬레이션은 가능하다. 즉, 불길이나 섬광을 발하는 장면의 일부를 최초로 밝게 할 수가 있다.

다른 기술로서는, 렌더링 타겟 영역 전체를 가리도록(듯이) 장면의 전면에 빌보드를 배치하는 방법이 있다. 프로그램으로 서서히 희어지는 텍스쳐를 빌보드에 적용해, 점점 투명도를 감소시킨다. 시간이 경과 하면 신 전체가 희어진다. 이것은, 불길을 생성 하는 방법으로서는 오버헤드의 낮은 방법이다. 그러나, 이 기술을 사용 하면, 단일의 포인트 라이트의 광원으로부터 밝은 섬광을 표현하는 것이 곤란하게 되는 일이 있다.

폭발은, 불, 섬광, 및 불길로 사용한 것 같은 3D 신 방법에 따라 표시할 수 있다. 예를 들어, 프로그램으로 빌보드를 사용해, 폭발의 충격파나 연기를 표시할 수 있다. 동시에, 빌보드 세트를 사용해 불길을 시뮬레이트 할 수 있다. 게다가 장면의 전면에 단일의 빌보드를 배치해, 장면 전체에 섬광을 추가할 수 있다.

에너지 빔은, 빌보드를 사용해 시뮬레이션 할 수 있다. 또, 선리스트 또는 선스트립으로서 정의한 프리미티브를 사용해도 이 빔을 표시할 수 있다. 상세한 것에 대하여는, 「선리스트」 및 「선스트립」을 참조할것.

빌보드나 삼각형 리스트로서 정의한 프리미티브를 사용해, 전자력계를 생성 할 수 있다. 삼각형 리스트로부터 전자력계를 생성 하려면 , 전자력계의 범위와 같은 공간을 차지하는 삼각형 리스트에 있는 분리한 삼각형세트를 정의하는 것. 뷰아는, 삼각형 끼리의 틈새로부터 삼각형의 배후의 장면을 볼 수가 있어 마치 전자력계를 봐 있는 것과 같게 느껴진다. 삼각형이 에너지로 빛나고 있도록(듯이) 보이게 하는 텍스쳐를 삼각형 리스트에 적용한다. 상세한 것에 대하여는, 「삼각형 리스트」 및 「현재 텍스쳐」를 참조할것.


모션브라

3D 신의 오브젝트의 지각 속도는, 오브젝트를 불선명하게 하는 것, 및 오브젝트의 뒤로 오브젝트 화면의 불선명한 자취를 남기는 것에 의해 높일 수가 있다. Direct3D 어플리케이션은, 프레임 마다 오브젝트를 여러 차례 렌더링 하는 것으로 이것을 실현할 수 있다.

[Visual Basic]

보통, Direct3D 어플리케이션은 장면을 오프 스크린 버퍼에 렌더링 하는 것을 생각해 내면 좋겠다. 버퍼의 내용은, 어플리케이션으로 DirectDrawSurface7.Flip 메소드를 호출했을 때에 스크린에 표시된다. Direct3D 프로그램은, 스크린에 프레임을 표시하기 전에 오브젝트를 장면에 여러 차례 렌더링 할 수 있다.

어플리케이션으로 DrawPrimitive 메소드에의 호출을 여러 차례 실시해, 같은 3D 오브젝트를 반복해 건네준다. 각각의 호출전에, 오브젝트의 위치 좌표를 조금 갱신해, 타겟 렌더링 표면상에 일련의 불선명한 오브젝트 화면을 생성한다. 오브젝트가 1 개 또는 복수의 텍스쳐를 가지고 있는 경우, 텍스쳐 모든 것을 거의 투명하게 해 오브젝트의 최초의 화면을 렌더링 하면, 모션브라에페크트를 높일 수가 있다. 오브젝트의 렌더링마다, 오브젝트의 텍스쳐의 투명도가 감소한다. 최종 위치 좌표로 오브젝트를 렌더링 하면나무는, 투명도없이 오브젝트를 렌더링 하는 것. 예외는, 텍스쳐의 투명도를 필요로 하는 것 외의 이펙트에 모션브라를 추가하는 경우이다. 어느 경우에서도, 프레임의 오브젝트의 최초의 화면이 가장 투명하지 않으면 안 된다. 마지막 화면의 투명도가 가장 낮지 않으면 안 된다.

[C++]

타겟 렌더링 표면에 일련의 오브젝트 화면을 렌더링 해, 나머지의 장면도 렌더링 하면(자),IDirectDrawSurface7::Flip 메소드를 호출해 스크린에 프레임을 표시한다.

[Visual Basic]

타겟 렌더링 표면에 일련의 오브젝트 화면을 렌더링 해, 나머지의 장면도 렌더링 하면(자),DirectDrawSurface7.Flip 메소드를 호출해 스크린에 프레임을 표시한다.

유저가 장면을 고속으로 이동하는 이펙트를 시뮬레이션 하는 경우는, 스크린 전체에 모션브라를 추가할 수 있다. 이 경우, 어플리케이션은 프레임 마다 장면 전체를 여러 차례 렌더링 하게 된다. 장면을 렌더링 할 때마다, 시점을 조금 이동해야 한다. 장면이 매우 복잡한 경우, 프레임마다의 장면의 렌더링 회수가 증가하므로, 고속으로 이동하는 장면만큼 퍼포먼스가 저하하는 것이 유저로 보인다.


스텐실 버퍼 기술

어플리케이션으로 스텐실 버퍼를 사용해, 화면의 픽셀을 마스크 한다. 이 마스크는, 픽셀을 드로잉(Drawing) 할지 어떨지를 제어한다. 스텐실 버퍼의 상세한 것에 대하여는, 「스텐실 버퍼」를 참조할것.

Direct3D 어플리케이션은, 스텐실 버퍼를 사용해 광범위한 특수 효과를 낳을 수가 있다. 빈번하게 사용되는 이펙트는 이하대로이다. 이러한 이펙트가 모두는 아니기 때문에, 주의 해야 한다.

  • 디조르브, 페이드, 및 와이프
  • 십-링
  • 합성
  • 아우트라인과 실루엣


디조르브, 페이드, 및 와이프

디조르브, 와이프, 및 페이드등의 영화나 비디오로 자주(잘) 사용되는 특수 효과를 어플리케이션으로 이용하는 것이 증가하고 있다.

디조르브에서는, 프레임이 서서히 바뀌는 것에 의해 있는 화면이 다른 화면에 순조롭게 이행 한다. Direct3D 는 이것과 같은 이펙트를 실현하기 위해서(때문에) 멀티 텍스쳐 블렌딩을 사용하는 방법을 제공하고 있지만, 디조르브에 스텐실 버퍼를 사용하는 어플리케이션은, 디조르브의 실행중에 이 텍스쳐 블렌딩 기능을 다른 이펙트에 이용할 수 있다.

디조르브를 실행 하면 와, 어플리케이션은 2 개가 다른 화면을 렌더링 해야 한다. 어플리케이션은 스텐실 버퍼를 사용해, 렌더링 타겟 표면에 각 화면의 어느 픽셀을 드로잉(Drawing) 하는지를 제어한다. 일련의 스텐실 마스크를 정의해, 연속하는 프레임의 스텐실 버퍼에 이러한 마스크를 카피할 수 있다. 다른 방법으로서 최초의 프레임용의 기본 스텐실 마스크를 정의해, 이 마스크를 증분 해 변경할 수도 있다.

디조르브의 최초로, 최초의 화면의 대부분의 픽셀이 테스트에 패스하도록(듯이) 스텐실 함수와 스텐실 마스크를 어플리케이션으로 설정한다. 마지막 화면의 대부분의 픽셀은, 스텐실 테스트에 실패해야 한다. 프레임이 계속되는 것에 따라, 최초의 화면의 픽셀로 테스트에 패스하는 픽셀이 서서히 적게 되도록(듯이), 스텐실 마스크를 갱신한다. 프레임이 계속되는 것에 따라, 마지막 화면의 픽셀로 테스트에 실패하는 픽셀이 서서히 적게 된다. 이와 같이, 임의의 디조르브파탄을 사용해 디조르브를 실행할 수 있다.

용명 또는 용암은, 디조르브의 특수한 케이스이다. 용명 하면나무는, 스텐실 버퍼를 사용해, 흑색의 (또는 백색의) 화면으로부터 3D 신의 렌더링에 디조르브 한다. 용암은 이것과 역으로, 3D 신의 렌더링으로부터 시작되어, 흑색의 (또는 백색의) 화면에 디조르브 한다. 페이드에는, 어떠한 패턴에서도 사용할 수 있다.

Direct3D 어플리케이션은, 와이프에도 동일한 기술을 사용한다. 예를 들어, 어플리케이션은 왼쪽에서 오른쪽에의 와이프를 실행한다. 마지막 화면은, 최초의 화면 위에 서서히 슬라이드하도록(듯이) 왼쪽에서 오른쪽으로 이동한다. 디조르브의 경우와 같이, 연속 프레임의 스텐실 버퍼에 로드하는 일련의 스텐실 마스크를 정의하는지, 계속해 최초의 스텐실 마스크를 수정할 필요가 있다. 이 스텐실 마스크는, 최초의 화면의 픽셀의 쓰기를 무효로 해, 마지막 화면의 픽셀의 쓰기를 유효하게 하기 위해서 사용한다.

와이프의 순서와는 역의 순서로 마지막 화면의 픽셀을 읽어내지 않으면 안 된다고 하는 점으로써, 와이프는 디조르브보다 조금 복잡하다. 즉, 와이프가 왼쪽에서 오른쪽으로 이동하는 경우, 어플리케이션은 마지막 화면의 픽셀을 오른쪽에서 왼쪽으로 읽어내지 않으면 안 된다.


십-링

Direct3D 어플리케이션은, 십-링 기술을 사용해, 렌더링 타겟 표면에 특정의 프리미티브의 어느 픽셀을 드로잉(Drawing) 하는지를 제어한다. 프로그램으로 디칼을 프리미티브의 화면에 적용해, 동일 평면상의 다각형을 올바르게 렌더링 할 수 있도록(듯이) 한다.

예를 들어, 타이어의 자취와 황색의 선을 도로에 적용 하면 와, 이 자취는 직접 도로 위에 표시해야 한다. 그러나, 이 자취와 도로의 z 값은 동일하다. 따라서, 깊이 버퍼에서는, 양자를 분명히 구별할 수 없다. 배후의 프리미티브의 픽셀이 전면의 프리미티브상에 렌더링 되거나 그 역의 렌더링을 하는 경우가 있다. 이 결과, 화면은 프레임 마다 흔들린다. 이 이펙트를 "Z 화이팅" 또는 "flimmering" 라고 부른다.

이 문제를 해결하려면 , 스텐실을 사용해, 디칼이 표시되는 뒷면 프리미티브의 부분의 마스크를 벗는다. z 버퍼링을 오프로 해, 렌더링 타겟 표면의 마스크로 가리고 있는 영역에 전면 프리미티브의 화면을 렌더링 한다.

멀티 텍스쳐 블렌딩을 사용해 이 문제를 해결할 수도 있지만, 이 방법을 사용 하면, 어플리케이션으로 생성할 수 있는 다른 특수 효과의 수가 제한된다. 스텐실 버퍼를 사용해 디칼을 적용 하면, 다른 이펙트에 대한 텍스쳐 블렌딩 스테이지의 제한이 릴리즈 된다.


합성

어플리케이션으로 스텐실 버퍼를 사용해, 2D 또는 3D 화면을 3D 신에 합성할 수 있다. 스텐실 버퍼의 마스크를 사용해, 렌더링 타겟 표면의 영역을 가림한다. 다음에, 텍스트나 비트 맵등의 저장 2D 정보를 가림 영역에 기입할 수가 있다. 다른 방법으로서 추가 3D 프리미티브를 렌더링 타겟 표면의 스텐실 마스크 된 영역에 렌더링 할 수 있다. 이 경우, 장면 전체를 렌더링 할 수도 있다.

게임에서는, 복수의 3D 신을 합성하는 것이 많다. 예를 들어, 운전 게임에서는 보통 백미러를 표시한다. 백미러에는, 운전자의 배후의 3D 신의 표시가 포함된다. 따라서, 백미러는, 본질적으로는 운전자의 전방의 풍경과 합성된 제 2 의 3D 신이라고 말할 수 있다.


아우트라인과 실루엣

스텐실 버퍼는, 아우트라인이나 실루엣등의 보다 추상적인 이펙트에 사용할 수도 있다.

프로그램으로, 프리미티브와 같은 형상이지만 조금 작은 스텐실 마스크를 프리미티브의 화면에 적용 하면, 화면은 프리미티브의 아우트라인만으로 된다. 다음에 화면의 스텐실 마스크를 한 영역을 한결같은 색으로 묻어, 프리미티브가 떠올라 보이도록(듯이) 할 수가 있다.

렌더링 하는 프리미티브와 스텐실 마스크가 같은 사이즈로 같은 형상인 경우, 본래 프리미티브가 존재하는 장소에 "구멍" 이 생긴다. 이 "구멍" 을 흑색으로 묻으면(자), 프리미티브의 실루엣을 생성할 수 있다.


컬러 라이팅

[C++]

D3DLIGHT7 구조체 (dcvDiffuse,dcvSpecular,dcvAmbient)의 색에 관련하는 멤버는,D3DCOLORVALUE 구조체이다. 이러한 구조체로 정의하는 색은, 일반적으로는 0 ~ 1 의 범위의 RGBA 값이며, 0 이 흑에 상당한다. 대부분은 광색이 이 범위가 되도록(듯이) 하지만, 특수 효과를 겨냥할 때는, 이 범위외의 값을 사용할 수도 있다. 예를 들어, 큰 값의 색을 설정해, 장면을 엉망으로 할 만큼 강한 빛을 만들 수가 있다. 또, 색을 부의 값으로 설정해,암색빛을 만들 수가 있다. 어두운 빛은, 장면에서 극적인그림자를 강하게 하거나 그 외의 이펙트에 유용하다.

[Visual Basic]

D3DLIGHT7 형 (diffuse,specular,ambient)의 색에 관련하는 멤버는,D3DCOLORVALUE 형이다. 이러한 형태로 정의하는 색은, 일반적으로는 0 ~ 1 의 범위의 RGBA 값이며, 0 이 흑에 상당한다. 대부분은 광색이 이 범위가 되도록(듯이) 하지만, 특수 효과를 겨냥할 때는, 이 범위외의 값을 사용할 수도 있다. 예를 들어, 큰 값의 색을 설정해, 장면을 엉망으로 할 만큼 강한 빛을 만들 수가 있다. 또, 색을 부의 값으로 설정해,암색빛을 만들 수가 있다. 어두운 빛은, 장면에서 극적인그림자를 강하게 하거나 그 외의 이펙트에 유용하다.


anti-aliasing

anti-aliasing란,"톱니모양" (정확하게 수평 또는 수직이 아닌 선을 그리는 경우에 사용되는 계단상의 픽셀)을 줄이기 위해서(때문에) 사용하는 기법이다. 3 차원 신의 경우, 이 부자연스러운 효과는 다른 색의 다각형간의 경계선상에서 가장 눈에 띈다. anti-aliasing는, 픽셀을 효과적으로 경계선상에서 블렌드 해, 장면의 외관을 보다 자연스럽게 한다.

Direct3D 로 지원 하는 anti-aliasing 기술은, 엣지 anti-aliasing 및 풀 신 anti-aliasing의 2 종류가 있다. 어느 쪽의 anti-aliasing가 어플리케이션에 좋은가는, 퍼포먼스와 시각적 품질의 요건에 의존한다.

  • 엣지 anti-aliasing
  • 풀 신 anti-aliasing

주 : 어플리케이션으로 anti-aliasing를 사용하는 경우는, DDSCAPS2_HINTANTIALIASING 플래그로 렌더링 타겟 표면을 생성 할 필요가 있다. 이 플래그를 생략 하면, anti-aliasing를 유효하게 했을 때에 퍼포먼스가 저하하거나 anti-aliasing가 실행되지 않는 것이 있다.


엣지 anti-aliasing

엣지 anti-aliasing에서는, 장면을 렌더링 한 후, 오브젝트의 볼록한 모양 실루엣을 선에 anti-aliasing 하기 위해서 재렌더링 한다. 시스템은 옆을 재드로잉(Drawing) 해, 애매하게 해, 부자연스러운 효과를 축소한다.

[C++]

디바이스가 엣지 anti-aliasing를 지원 하고 있는 경우는,D3DPRIMCAPS 구조체 (IDirect3DDevice7::GetCaps 메소드를 호출해 설정한다)에 D3DPRASTERCAPS_ANTIALIASEDGES 능력 플래그가 공개된다. 이 경우,D3DRENDERSTATE_EDGEANTIALIAS 렌더링 스테이트를 TRUE 로 설정해, 다음에 IDirect3DDevice7::DrawPrimitive , 및 D3DPT_LINESTRIP 또는 D3DPT_LINELIST 프리미티브 타입의 어느쪽이든을 사용해, 장면내의 엣지만 재드로잉(Drawing) 한다. 엣지 anti-aliasing의 동작은, 선 이외의 프리미티브에 대해서는 정의되어 있지 않기 때문에, anti-aliasing가 완료하면(자), D3DRENDERSTATE_EDGEANTIALIAS 를 FALSE 로 설정해 기능을 확실히 무효로 한다.

[Visual Basic]

디바이스가 엣지 anti-aliasing를 지원 하고 있는 경우는,D3DPRIMCAPS 형 (Direct3DDevice7.GetCaps 메소드를 호출해 설정한다)에 D3DPRASTERCAPS_ANTIALIASEDGES 능력 플래그가 공개된다. 이 경우,D3DRENDERSTATE_EDGEANTIALIAS 렌더링 스테이트를 True 로 설정해, 다음에 Direct3DDevice7.DrawPrimitive , 및 D3DPT_LINESTRIP 또는 D3DPT_LINELIST 프리미티브 타입의 어느쪽이든을 사용해, 장면내의 엣지만 재드로잉(Drawing) 한다. 엣지 anti-aliasing의 동작은, 선 이외의 프리미티브에 대해서는 정의되어 있지 않기 때문에, anti-aliasing가 완료하면(자), D3DRENDERSTATE_EDGEANTIALIAS 를 False 로 설정해 기능을 확실히 무효 한다.

장면안의 모든 엣지를 재드로잉(Drawing) 하면, 큰 부자연스러운 효과를 일으키게 한 하지않고서 살지만, 계산량이 방대하게 된다. 또, 이 방법에서는 어느 엣지를 anti-aliasing 해야할 것인가 판단이 곤란한 일도 있다. 재드로잉(Drawing) 하는데 가장 중요한 엣지는, 매우 다른 색의 영역의 사이의 엣지 (예를 들어 그림자의 엣지), 또는 매우 다른 머트리얼의 사이의 경계이다. 거의 같은 색의 2 개의 다각형의 사이의 엣지를 anti-aliasing 하는 것은, 이펙트가 없는것에 비해서 계산량은 방대하다. 이러한 이유에 의해, 현재의 하드웨어가 지원 하는 경우는, 풀 신 anti-aliasing가 바람직한 일이 많다. 상세한 것에 대하여는, 「풀 신 anti-aliasing」를 참조할것.


풀 신 anti-aliasing

풀 신 anti-aliasing와는, 장면내의 각 다각형의 엣지를 싱글 패스로 rasterize 해 애매하게 하는 것을 가리킨다. 2 개째의 패스는 필요없다. 풀 신 anti-aliasing는 (지원 되고 있는 경우), 삼각형 및 삼각형의 그룹에게만 영향을 준다. Direct3D 서비스를 사용해, 선에 anti-aliasing를 적용할 수 없다.

[C++]

하드웨어에 따라서는, 소트 한 다각형을 어플리케이션이 뒤로부터 전에 렌더링 하면나무밖에, 풀 신 anti-aliasing를 적용할 수 없다. 이것이 현재의 디바이스에 들어맞을지 어떨지를 조사하려면 ,IDirect3DDevice7::GetCaps 메소드를 호출해 디바이스 기능을 취득한다. 호출한 다음에, 관련지을 수 있었던 D3DPRIMCAPS 구조체의 dwRasterCaps 멤버를 체크한다. 디바이스가 anti-aliasing에 대해서 뒤로부터 전에의 렌더링을 요구하고 있는 경우는,D3DPRASTERCAPS_ANTIALIASSORTDEPENDENT 능력 플래그가 dwRasterCaps 에 나타나고 있다. 다각형의 순서에 관계없이 디바이스를 anti-aliasing를 실시할 수 있는 경우는,D3DPRASTERCAPS_ANTIALIASSORTINDEPENDENT 플래그가 나타나고 있다. 어느 쪽의 플래그도 없는 경우는, 디바이스가 풀 신 anti-aliasing를 실시할 수 없는 것을 나타낸다.

다각형을 소트 할 필요가 있을지 어떨지 조사한 다음에,D3DRENDERSTATE_ANTIALIAS 렌더링 스테이트를 D3DANTIALIAS_SORTDEPENDENT 또는 D3DANTIALIAS_SORTINDEPENDENT 에 세트 해, 장면을 드로잉(Drawing) 한다.

풀 신 anti-aliasing가 필요없게 되면(자), D3DRENDERSTATE_ANTIALIAS 를 D3DANTIALIAS_NONE 로 설정해 무효로 한다.

[Visual Basic]

하드웨어에 따라서는, 소트 한 다각형을 어플리케이션이 뒤로부터 전에 렌더링 하면나무밖에, 풀 신 anti-aliasing를 적용할 수 없다. 이것이 현재의 디바이스에 들어맞을지 어떨지를 조사하려면 ,Direct3DDevice7.GetCaps 메소드를 호출해 디바이스 기능을 취득한다. 이 호출의 뒤, 관련지을 수 있고 있는 D3DPRIMCAPS 형의 lRasterCaps 멤버를 조사한다. 디바이스가 후방에서 전방에의 렌더링을 anti-aliasing에 요구하고 있는 경우는,D3DPRASTERCAPS_ANTIALIASSORTDEPENDENT 능력 플래그가 lRasterCaps 에 공개된다. 다각형의 순서에 관계없이 디바이스가 anti-aliasing를 실행할 수 있는 경우는,D3DPRASTERCAPS_ANTIALIASSORTINDEPENDENT 플래그가 공개된다. 어느 쪽의 플래그도 없는 경우는, 디바이스가 풀 신 anti-aliasing를 실시할 수 없는 것을 나타낸다.

다각형을 소트 할 필요가 있을지 어떨지를 조사한 후,D3DRENDERSTATE_ANTIALIAS 렌더링 스테이트를 D3DANTIALIAS_SORTDEPENDENT 또는 D3DANTIALIAS_SORTINDEPENDENT 로 설정해, 장면을 드로잉(Drawing) 한다.

풀 신 anti-aliasing가 필요없게 되면(자), D3DRENDERSTATE_ANTIALIAS 를 D3DANTIALIAS_NONE 로 설정해 무효로 한다.


GUID

[C++]

Direct3D 에서는, 글로벌 유니크 식별자 (GUID)를 사용해, 인터페이스의 각부를 식별한다. QueryInterface 메소드를 사용해, 오브젝트가 인터페이스를 지원 하고 있을지 어떨지 확인하려면 , 대상이 되는 인터페이스를, 그 GUID 를 사용해 특정한다.

GUID 를 어플리케이션으로 잘 사용하려면 , 그 외 모든 include 및 define 문에 앞서 INITGUID 를 정의하는지, 또는 DXGUID.LIB 라이브러리를 링크해야 한다. INITGUID 는, 소스 모듈의 어떤 것이나 1 개만으로 정의한다.

GUID 는, 어플리케이션이 C 또는 C++ 의 어디에서 쓰여져 있을까에 의해 사용법이 다르므로 주의한다. C 의 경우는, GUID (예를 들어, &IID_IDirect3D)에 포인터를 건네주지만, C++ 에서는 참조를 건네준다 (단지 IID_IDirect3D).

[Visual Basic]

DirectX 의 그 외의 컴퍼넌트와 같이, Direct3D 컴퍼넌트는 글로벌 유니크 식별자, 즉 GUID (globally unique identifiers)를 사용해 API 의 각부를 식별한다. DirectX for Visual Basic 에서는, GUID 가 필요한 경우, 예를 들어,DirectX7.DirectDrawCreate 메소드를 호출해 DirectDraw7 오브젝트를 생성 하는 경우는 GUID 를 캐릭터 라인으로서 사용한다.

상세한 것에 대하여는, 「GUID 의 사용」을 참조할것.


퍼포먼스의 최적화

3D 그래픽스를 사용한 리얼타임 어플리케이션을 생성 하는 개발자라면, 누구라도 퍼포먼스의 최적화에 관심이 있다. 이 섹션에서는, 코드로부터 최고의 퍼포먼스를 얻기 위한 가이드 라인을 나타낸다.

이하의 섹션의 가이드 라인은, 모든 Direct3D 어플리케이션에 적용할 수 있다.

  • 데이타베이스와 컬링(Culling)
  • 프리미티브의 배치처리
  • 라이팅의 힌트
  • 텍스쳐의 사이즈
  • 일반적인 퍼포먼스의 힌트
  • Z 버퍼의 퍼포먼스


데이타베이스와 컬링(Culling)

신뢰성의 높은 오브젝트의 데이타베이스를 구축하는 것은, Direct3D 가 뛰어난 퍼포먼스를 얻는 키가 된다. 이것은, 라스터화나 하드웨어의 개량보다 중요하다.

관리 가능한 최저의 다각형수를 유지해야 한다. 소수 다각형의 설계에서는, 처음은 다각형의 적은 모델을 만들어, 개발 프로세스의 후반에 퍼포먼스를 희생하지 않아도 할 수 있을 것 같다고 느끼면(자) 다각형을 추가한다. 다각형의 총수는 2,500 부근을 유지하도록(듯이) 한다. "최고 속도의 다각형은 드로잉(Drawing) 하지 않는 다각형" 인 것을 잊지 않는 것.


프리미티브의 배치처리

실행중에 최고의 렌더링 퍼포먼스를 얻으려면 , 프리미티브를 배치처리 해, 렌더링 스테이트의 변경을 가능한 한 줄인다. 예를 들어, 2 개의 텍스쳐를 가지는 오브젝트가 있을 때, 우선 최초의 텍스쳐를 사용하는 삼각형을 그룹화 해, 계속되어, 텍스쳐를 변경하는데 필요한 렌더링 스테이트를 설정한다. 그리고, 2 번째의 텍스쳐를 사용하는 삼각형을 모두 그룹화 한다. Direct3D 를 지원 하는 가장 단순한 하드웨어에서는, 하드웨어 추상 계층 (HAL)을 통해, 렌더링 스테이트나 프리미티브의 배치처리를 실시한다. 배치 명령이 효율적인 만큼, 실행중에 HAL 가 불려 가는 것이 적게 된다


라이팅의 힌트

라이팅은, 각 렌더링 프레임으로 전버텍스로써 부하가 걸리므로, 어플리케이션에서의 라이트의 사용에 세심의 주위를 기울이는 것으로, 대폭적인 퍼포먼스의 향상을 달성할 수가 있다. 이하에 주는 힌트의 대부분은,"가장 빠른 코드는, 결코 불려 갈리가 없는 코드이다" 라고 하는 표어로부터 이끌린 것이다.

  • 광원의 사용을 가능한 한 삼가한다. 전체적 레벨의 라이팅만으로 좋은 경우는, 새로운 광원을 추가하는 것이 아니라, 앰비언트 라이트를 사용한다 (부하가 가볍다).
  • 디렉셔널 라이트가, 포인트 라이트나 spotlight보다 부하가 가볍다. 디렉셔널 라이트의 경우, 빛의 진행 방향은 일정해, 버텍스 마다 계산할 필요는 없다.
  • spotlight가, 포인트 라이트보다 부하가 가볍다. 빛의 콘의 외측 영역의 계산을 재빠르게 할 수 있기 때문이다. spotlight가 부하가 가벼운지 어떤지는, 얼마나의 장면을 spotlight로 조사할까로 정해진다.
  • 조사할 필요가 있는 부분에만 빛을 제한하기 위해서 범위 파라미터를 사용한다. 모든 라이트 타입은, 범위외가 되면(자) 꽤 빨리 나간다.
  • 스펙큐러 하이라이트는 부하가 거의 배증하기 위해(때문에), 필요한 때에게만 사용한다. D3DRENDERSTATE_SPECULARENABLE 렌더링 스테이트는, 할 수 있는 한 0 (디폴트값)으로 설정해 둔다. 머트리얼을 정의 하면나무는, 스펙큐러 강도값을 제로로 설정해, 머트리얼의 스펙큐러 하이라이트를 오프 할 필요가 있다. 스펙큐러색을 0,0,0 으로 설정하는 것 만으로는 불충분하다.


텍스쳐의 사이즈

텍스쳐 맵핑의 퍼포먼스는, 메모리의 속도에 크게 의존한다. 텍스쳐의 캐쉬 퍼포먼스를 최대로 하려면 , 많은 방법이 생각된다.

  • 텍스쳐를 작게 한다. 텍스쳐가 작을 정도(수록), 메인의 CPU 의 세컨드리 캐쉬에 보관 유지될 가능성이 높아진다.
  • 프리미티브 마다 텍스쳐를 변경하지 않는다. 또, 사용하는 텍스쳐의 순서에 다각형을 그룹화 해 둔다.
  • 할 수 있는 한 정방형의 텍스쳐를 사용한다. 치수가 256x256 의 텍스쳐가 최고 속도이다. 예를 들어, 128x128 의 텍스쳐를 4 개 사용하는 경우는, 같은 팔레트를 사용해, 그러한 텍스쳐를 1 개의 256x256 의 텍스쳐에 거두도록(듯이) 한다. 이 테크닉에 의해, 텍스쳐 부부 교환 파티의 회수를 줄일 수도 있다. 어플리케이션으로 소수의 텍스쳐 밖에 필요하지 않은 경우는, 256x256 의 텍스쳐는 사용하지 않는다. 이미 설명한 것처럼, 텍스쳐는 가능한 한 작게 하는 것이 좋기 때문에이다.


일반적인 퍼포먼스의 힌트

몇개의 일반적인 가이드 라인에 따르면, 어플리케이션의 퍼포먼스를 높일 수가 있다.

  • 필요한 때만 클리어 한다.
  • 스테이트의 변화를 최소한으로 한다.
  • 필요한 때만 투시 수정을 사용한다.
  • 가능하면 작은 텍스쳐를 사용한다.
  • 어울리지 않은 system resource의 공유가 필요한 특수 효과는 눈에 띄지 않게 약하게 한다.
  • 어플리케이션의 퍼포먼스를 항상 테스트한다.
  • 어플리케이션이, 하드웨어 가속화와 소프트웨어 에뮬레이션의 양쪽 모두로 양호하게 동작하도록(듯이) 한다.


Z 버퍼의 퍼포먼스

램프 드라이버를 사용하는 어플리케이션에서는, 장면이 전부터 뒤에 렌더링 되도록(듯이), z 버퍼링을 사용해 텍스쳐를 처리 하면, 퍼포먼스를 향상시킬 수가 있다. 텍스쳐를 적용해, Z 버퍼를 이용한 원시적인 것은, 기준이 되는 스캔 라인상에서 Z 버퍼에 대한 프레테스트를 한다. 미리 렌더링 된 다각형의 스캔 라인이 숨어 있는 경우는, 시스템이 다각형을 고속이고 효율적으로 없앤다. z 버퍼링에 의해 퍼포먼스는 개선되지만, 이 방법은 장면에서 몇번이나오버 드로우가 필요한 때에 가장 효과적이다. 오버 드로우란, 스크린 픽셀의 평균 드로잉(Drawing) 회수이다. 오버 드로우를 정확하게 계산하는 것은 어렵지만, 근사치를 요구하는 것은 가능하다. 오버 드로우의 평균이 2 보다 작을 때는, z 버퍼링을 오프로 해, 뒷면으로부터 전면으로 장면을 렌더링 하면 최고의 퍼포먼스를 얻을 수 있다.

[C++]

렌더링의 전에 표시 테스트를 실행해, 어플리케이션의 퍼포먼스를 개선할 수도 있다. Direct3D 직접 모드에는, 이것을 행하기 위한 IDirect3DDevice7::ComputeSphereVisibility 메소드가 있다. ComputeSphereVisibility 메소드는, 지정된 다각형 세트에 대한 정보를 제공한다. 이 메소드에 의해, 지오메트리가 표시 불능인 것이 통지되었을 경우는, 오브젝트의 렌더링을 회피할 수도 있다.

[Visual Basic]

렌더링의 전에 표시 테스트를 실행해, 어플리케이션의 퍼포먼스를 개선할 수도 있다. Direct3D 직접 모드에는, 이것을 행하기 위한 Direct3DDevice7.ComputeSphereVisibility 메소드가 있다. ComputeSphereVisibility 메소드는, 지정된 다각형 세트에 대한 정보를 제공한다. 이 메소드에 의해, 지오메트리가 표시 불능인 것이 통지되었을 경우는, 오브젝트의 렌더링을 회피할 수도 있다.

고속의 퍼스널 컴퓨터에서는, 소프트웨어적으로 시스템 메모리에 렌더링 한 (분)편이, 비디오 메모리에의 렌더링보다 빠른 일이 적지 않다. 다만, 이 경우는, 더블 버퍼링이나 하드웨어 가속기에 의한 클리어 처리를 사용할 수 없다고 하는 디메리트가 있다. 시스템 메모리에도 비디오 메모리에도 렌더링 할 수가 있어 어느 쪽이 고속인가를 테스트하는 루틴이 있으면, 어플리케이션에서는, 현행 시스템으로 최적인 방법을 이용할 수 있다. 이 SDK 의 Direct3D 샘플 코드에서는, 이 방법을 실현하고 있다. 다만, 스피드를 테스트할 방법이 그 밖에 없기 때문에, 이 양쪽 모두의 순서를 실현할 필요가 있다. 컴퓨터에 의해 스피드는 완전히 달라, 메인 메모리의 아키텍쳐나 사용되고 있는 그래픽스 어댑터의 종류에 의존한다.


트러블 슈팅

여기에서는, Direct3D 프로그램을 생성 할 경우에 자주(잘) 경험하는 공통 카테고리의 문제점과 그것을 막기 위한 방법을 기술한다.

  • 디바이스의 생성
  • 라이팅 끝난 버텍스의 사용
  • 아무것도 표시되지 않는다
  • 디버그
  • 볼랜드 부동 소수점의 초기화
  • 파라미터 타당성의 검증


디바이스의 생성

디바이스의 생성중에 어플리케이션이 실패했을 경우는, 이하와 같은 에러가 있는지 없는지를 조사한다.

  • DirectDraw 표면을 생성 하면 와, DDSCAPS_3DDEVICE 를 지정하고 있을까.
  • 팔레트화한 디바이스를 사용할 때, 팔레트를 Attach 하고 있을까.
  • Z 버퍼를 사용할 때, 렌더링 타겟으로 Attach 하고 있을까.
  • 디바이스의 능력, 특히 렌더링의 깊이를 확실히 체크하고 있을까.
  • 시스템 메모리와 비디오 메모리의 어느 쪽을 사용하고 있는 것인가.
  • 레지스트리가 망가지지 않은가.


라이팅 끝난 버텍스의 사용

[C++]

D3DLVERTEX 구조체에 유사하는, 라이팅 끝난 버텍스를 사용하는 어플리케이션에서는,D3DRENDERSTATE_LIGHTING 렌더링 스테이트를 FALSE 로 설정해 Direct3D 라이팅 엔진을 무효로 할 필요가 있다. 디폴트에서는, 라이팅이 유효하게 되어 있는 경우, 입력 버텍스에 제로 이외의 컬러값이 포함되어 있어도, 법선 벡터를 포함하지 않은 버텍스의 색은 0 (흑)으로 설정된다. D3DLVERTEX 등 라이트를 댄 버텍스는, 본래, 버텍스 법선을 포함하지 않기 때문에, 라이팅 엔진이 유효하게 되어 있으면(자) Direct3D 에게 건네지는 색정보가 렌더링시에 없어진다.

독자적인 라이팅을 실행하는 어플리케이션에 있어서는, 버텍스색이 중요한 요소인 것은 분명하다. 디폴트값의 사용을 피하기 위해서(때문에), D3DRENDERSTATE_LIGHTING 를 FALSE 로 설정하는 것.

[Visual Basic]

D3DLVERTEX 형에 유사하는, 라이팅 끝난 버텍스를 사용하는 어플리케이션에서는,D3DRENDERSTATE_LIGHTING 렌더링 스테이트를 FALSE 로 설정해 Direct3D 라이팅 엔진을 무효로 할 필요가 있다. 디폴트에서는, 라이팅이 유효하게 되어 있는 경우, 입력 버텍스에 제로 이외의 컬러값이 포함되어 있어도, 법선 벡터를 포함하지 않은 버텍스의 색은 0 (흑)으로 설정된다. D3DLVERTEX 등 라이트를 댄 버텍스는, 본래, 버텍스 법선을 포함하지 않기 때문에, 라이팅 엔진이 유효하게 되어 있으면(자) Direct3D 에게 건네지는 색정보가 렌더링시에 없어진다.

독자적인 라이팅을 실행하는 어플리케이션에 있어서는, 버텍스색이 중요한 요소인 것은 분명하다. 디폴트값의 사용을 피하기 위해서(때문에), D3DRENDERSTATE_LIGHTING 를 False 로 설정하는 것.


아무것도 표시되지 않는다

어플리케이션은 동작하고 있는데 아무것도 표시되지 않는 경우는, 이하와 같은 에러가 있는지 없는지 조사한다.

  • 삼각형이 변질하고 있지 않는가.
  • 삼각형이 컬링(Culling)되어 있지 않은가.
  • 트랜스 폼에 내부적인 모순이 없는가.
  • 삼각형이 표시되도록(듯이) 뷰포트 설정이 지정되고 있는지 어떤지를 조사한다.


디버그

[Visual Basic]

주 : 여기에서는, C 또는 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

Direct3D 어플리케이션의 디버그는 어려울지도 모른다. 모든 돌아가 값을 조사하는 (Direct3D 프로그래밍 중(안)에서도 특히 중요한 것이어, 하드웨어 이행에 틀림에 따라 크게 다르다) 그 밖에도, 이하의 방법을 시험해 본다.

  • 디버그 DLL 에 새로 바꾼다.
  • 강제적으로 소프트웨어 온리 디바이스로 해, 사용 가능해도 하드웨어 가속화를 정지한다.
  • 표면을 강제적으로 시스템 메모리에 넣는다.
  • 윈도우로 동작하는 옵션을 생성 해, 내장된 디버거를 사용할 수 있도록(듯이) 한다.

전의 리스트에 있는 2 번째와 3 번째의 옵션은, Win16 의 락을 막는데 도움이 된다. 그렇게 하지 않으면 디버거가 헹 하는 일이 있다.

또, 이하의 엔트리를 WIN.INI 에 추가해 본다.

[Direct3D]
debug=3
[DirectDraw]
debug=3


볼랜드 부동 소수점의 초기화

[Visual Basic]

주 : 여기에서는, C 또는 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

Borland 사제의 컴파일러는, Direct3D 와 호환성이 없는 방법으로 부동 소수점의 예외를 보고한다. 이 문제를 해결하려면 , 다음과 같이 _matherr() 예외 핸들러를 인클루드 해야 한다.

// Borland 부동 소수점의 초기화
#include <math.h>
#include <float.h>

void initfp(void)
{
// 부동 소수점의 예외를 무효로 한다.
    _control87(MCW_EM, MCW_EM);
}

int _matherr(struct _exception  *e)
{
e;               // 경고를 받아들이는 더미 참조
return 1;    // 에러 처리는 끝났다
}


파라미터 타당성의 검증

[Visual Basic]

주 : 여기에서는, C 또는 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

퍼포먼스 위에의 이유에 의해, Direct3D 직접 모드의 디버그 버젼은 리테일 버젼보다 빈번하게, 실행시의 파라미터 타당성 검증을 실시한다. 리테일 버젼은 타당성 검증을 전혀 실시하지 않는 것도 있다. Debug 판의 타당성 검증을 이용하면, 저속의 디버그 런타임 컴퍼넌트로 견뢰한 디버그를 실행한 다음에, Retail 판을 사용해 퍼포먼스를 조정해, 최종 릴리스를 실현할 수 있다.

몇개의 Direct3D 직접 모드 메소드가 받을 수가 있는 값에는 제한이 있는 것에도 불구하고, 이러한 제한은 Direct3D 직접 모드 런타임의 디버그 버젼이 체크해 강제하는 것만으로 있는 것이 많다. 어플리케이션은, 이러한 제한을 준수해야 한다. 그렇게 하지 않으면 Direct3D 의 리테일 버젼을 실행했을 때에, 예기 할 수 없는 (또, 매우 바람직하지 않다) 결과가 발생하는 일이 있다. 예를 들어,IDirect3DDevice7::DrawPrimitive 메소드가 받는 파라미터 (dwVertexCount)는, 메소드가 렌더링 하는 버텍스의 수를 나타낸다. 메소드가 받을 수가 있는 것은 0 에서 65,535 (0x0000 에서 0xFFFF)의 사이의 값 뿐이다. Direct3D 의 디버그 버젼으로 65,536 (제한보다 1 크다)을 건네주면(자), 메소드는 실패해, 에러 로그에 에러 메세지를 써내, 어플리케이션에 에러값을 돌려준다. 그러나, 리테일 버젼 런타임을 실행중에 같은 에러가 발생했을 경우는, 동작은 예측할 수 없다. 퍼포먼스 위에의 이유에 의해, 메소드는 파라미터를 검증하지 않기 때문에, 파라미터가 유효하지 않은 경우는, 결과는 완전한 상황 의존으로 예측할 수 없는 동작이 된다. 어느 경우에는 호출이 동작해, 다른 경우에는 호출에 의해 Direct3D 의 메모리에 장해가 발생한다. 무효인 호출이 특정의 하드웨어 구성과 DirectX 버젼으로 정상적으로 동작하는 일도 있지만, 다른 하드웨어 또는 장래의 릴리스의 DirectX 에서도 기능이 계속하는 보증은 없다.

Retail 판의 Direct3D 직접 모드 런타임에서의 실행중에, 설명할 수 없는 것 같은 에러가 발생했을 경우는, Debug 판으로 테스트해, 어플리케이션이 무효인 파라미터를 건네주지 않은지 어떤지를 자세하게 조사한다.


Direct3D 직접 모드 튜토리얼

여기에서는, Direct3D® 직접 모드의 기본적인 기능을 C/C++ 또는 Visual Basic 어플리케이션에 이행 하는 방법에 대해 스텝바이스텝으로 설명하는 튜토리얼을 제공한다. 각 튜토리얼은, 이 SDK 의 \Samples\Multimedia\D3DIM\Tutorials 디렉토리에서 제공되는 일련의 샘플 파일과 대응해, 코드의 흐름에 따라 설명한다. 샘플 코드를 참조하면서 튜토리얼을 읽어 진행시켜 나가는 것을 권한다.

  • Direct3D 직접 모드의 C/C++ 튜토리얼
  • Direct3D 직접 모드 Visual Basic 튜토리얼


Direct3D 직접 모드의 C/C++ 튜토리얼

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

여기에서는, Direct3D 를 사용하는 방법에 대해, 공통의 태스크의 각 태스크를 필요한 스텝으로 나누어 설명한다. 경우에 따라서는, 이해하기 쉽게 하기 위해서, 스텝이 한층 더 세세한 스텝으로 나누어져 있다. 다음의 튜토리얼을 제공한다.

  • 튜토리얼 1 : 단일의 삼각형을 렌더링 한다
  • 튜토리얼 2 : 깊이 버퍼를 추가한다
  • 튜토리얼 3 : 다양한 프리미티브 스타일을 사용한다
  • 튜토리얼 4 : 디바이스 열거를 사용한다
  • 튜토리얼 5 : 텍스쳐 맵을 사용한다

주 : 각 튜토리얼의 샘플 파일은 C++ 로 기술되고 있다. C 컴파일러를 사용하고 있는 경우, 샘플 파일에 적절한 변경을 더해, 에러 없게 컴파일 할 수 있도록(듯이) 해야 한다. 적어도, 인터페이스 메소드에는,vtable 포인터와 this 포인터를 추가할 필요가 있다.

첨부되고 있는 샘플 코드중의 코멘트에는, SDK 의 소스 파일과는 다른 것도 있다. 변경은, 코드의 동작이 바뀌는 것을 피하기 (위해)때문에, 코멘트인 만큼 한정해, 간결하게 하기 위한(해)인 만큼 가고 있다.


튜토리얼 1 : 단일의 삼각형을 렌더링 한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

Direct3D 를 사용하려면 , 우선, 어플리케이션 윈도우를 생성 한 후, DirectDraw® 과 Direct3D 관련 오브젝트를 생성 해, 초기화한다. 유저는, 오브젝트가 이행 하고 있는 COM 인터페이스를 사용해 오브젝트를 처리해, 장면의 렌더링에 필요한 종속 오브젝트를 생성한다. 이 튜토리얼로 사용하는 샘플 프로젝트 Triangle 는, 가장 단순한 장면이다. 단일의 삼각형을 렌더링 하는 태스크를 통해 이러한 태스크를 구체적으로 가리킨다. 샘플 프로젝트 Triangle 에서는, 다음의 스텝을 사용해, Direct3D 를 셋업 해, 장면을 렌더링 해, 마지막에 슛다운을 실시한다.

  • 스텝 1 : 윈도우를 생성 한다
  • 스텝 2 : 시스템 오브젝트를 초기화한다
  • 스텝 3 : 신을 초기화한다
  • 스텝 4 : 시스템 메세지를 감시한다
  • 스텝 5 : 신을 렌더링 및 표시한다
  • 스텝 6 : 슛다운

위의 스텝에 가세해, Triangle 에서는, 윈도우 어플리케이션에 공통되는 표준적인 태스크를 몇개인가 실행한다. 이 태스크는 어려운 것으로는 없다. 샘플 Triangle ( 및, 다른 모든 윈도우 어플리케이션의 샘플)에서는, 필요에 따라서 다음의 태스크를 실행하고 있다.

  • 윈도우의 이동을 처리한다
  • 윈도우의 사이즈 변경을 처리한다


스텝 1 : 윈도우를 생성 한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

어느 Windows 어플리케이션에서도, 실행시에, 우선 실시하지 않으면 안 되는 것은, 어플리케이션 윈도우를 생성 해, 유저 인터페이스를 표시하는 것이다. 이것에 따라, Triangle 에서는,WinMain 함수의 실행 시작시에, 다음의 코드를 사용해 윈도우의 초기화를 실행하고 있다.

INT WINAPI WinMain( HINSTANCE hInst, HINSTANCE, LPSTR strCmdLine, INT )
{
    // 윈도우 클래스를 등록한다.
    WNDCLASS wndClass = { CS_HREDRAW | CS_VREDRAW, WndProc, 0, 0, hInst,
                          LoadIcon( hInst, MAKEINTRESOURCE(IDI_MAIN_ICON)),
                          LoadCursor(NULL, IDC_ARROW),
                          (HBRUSH) GetStockObject(WHITE_BRUSH), NULL,
                          TEXT("Render Window") };
    RegisterClass( &wndClass );

    // 메인 윈도우를 생성 한다.
    HWND hWnd = CreateWindow( TEXT("Render Window"),
                              TEXT("D3D Tutorial: Drawing One Triangle"),
                              WS_OVERLAPPEDWINDOW, CW_USEDEFAULT,
                              CW_USEDEFAULT, 300, 300, 0L, 0L, hInst, 0L );
    ShowWindow( hWnd, SW_SHOWNORMAL );
    UpdateWindow( hWnd );

위의 코드는, 표준적인 Windows 프로그래밍이며, 여기에서는 주로, 전체를 설명하기 위해서 기술하고 있다. 이 샘플에서는, 최초로,"Render Window" 라고 하는 윈도우 클래스의 정의 및 등록을 실시하고 있다. 이 윈도우 클래스는, 사이즈 이벤트에 의해 재드로잉(Drawing)를 실시해, 리소스로서 어플리케이션 제공 아이콘을 사용해, 백그라운드를 백색으로 하도록(듯이) 정의되고 있다. 클래스의 등록 후, 샘플 코드는, 등록 클래스를 사용하는 기본적인 최상정도 레벨의 윈도우를 생성 한다. 이 윈도우는, 폭 300 픽셀, 높이 300 픽셀의 클라이언트 영역을 가져, 메뉴와 자식 윈도우는 가지지 않는다. 이 샘플에서는, WS_OVERLAPPEDWINDOW 윈도우 스타일을 사용해, 윈도우 어플리케이션에 공통되는 [최소화],[최대화], 및 [닫는] 박스가 붙은 윈도우를 생성 한다. (샘플을 풀 스크린 모드로 실행하는 경우는, 윈도우 스타일에 WS_EX_TOPMOST 를 사용 하면이야 있고). 이 윈도우가 생성 되면(자), 샘플 코드는 Win32® 표준 함수를 호출해, 윈도우의 표시와 갱신을 실시한다.

어플리케이션 윈도우의 준비가 종료 하면, DirectX® 의 주요 오브젝트의 셋업을 시작 할 수가 있다. 이것이, 「스텝 2 : 시스템 오브젝트를 초기화한다」의 설명 내용이다.


스텝 2 : 시스템 오브젝트를 초기화한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

어플리케이션 윈도우를 생성 하면, DirectX 프라이머리 오브젝트의 초기화를 시작 할 수 있다. 이 오브젝트의 서비스를 이용해, 장면의 렌더링을 실시한다. Direct3D 어플리케이션에 있어, 초기화란, DirectDraw, 렌더링 표면, 렌더링 디바이스, 및 뷰포트를 생성 및 구성하는 것을 의미한다. 이해하기 쉽게하기 위해(때문에), 샘플 Triangle 에서는, 시스템 오브젝트 초기화 코드와 장면 초기화 코드를 따로 따로 하고 있다. 그 결과, 지오메트리, 어플리케이션에 특유인 데이터 구조체, 머트리얼등의 Direct3D 의 세컨드리 오브젝트가, 장면과 함께 초기화되고 있다. 이것은 필수는 아니고, 코드를 보다 간단하게 하기 위해서 간 것이다.

샘플 Triangle 는, 윈도우의 생성 후에, 어플리케이션 정의 함수 Initialize3Denvironment 를 WinMain 로부터 호출해 시스템 초기화를 실행한다. 그러한 오브젝트의 준비는 복잡하지 않지만, 코드는 약간 길어져, 1 개소에서만 설명할 수 없다. 거기서, Initialize3Denvironment 함수가 취하는 스텝을 이하에 나타낸다.

  • 스텝 2.1 : DirectDraw 를 초기화한다
  • 스텝 2.2 : DirectDraw 표면을 셋업 한다
  • 스텝 2.3 : Direct3D 를 초기화한다
  • 스텝 2.4 : 뷰포트를 준비한다

주 : 샘플 코드 Triangle 는, WM_CREATE 등의 시스템 생성 메세지에 응답하는 것이 아니라, 어플리케이션 윈도우의 생성 직후에 WinMain 함수의 내부로부터 메소드를 호출해 초기화를 실시한다. 이것은, 플랫폼간에 다를 가능성이 있는 시스템 메세지의 지시에 의존하는 것을 피하기 때문에 있다.


스텝 3 : 신을 초기화한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

Direct3D 에 관련하는 프라이머리 오브젝트의 DirectDraw 오브젝트, 렌더링 디바이스, 및 뷰포트를 생성 하면(자), 다음은 지오메트리의 설정, 머트리얼의 준비, 및 어플리케이션으로 사용하는 트랜스 폼 행렬의 설정을 실시해, 장면의 초기화를 시작 한다. 샘플 Triangle 에서는, 어플리케이션 정의 함수의 App_InitDeviceObjects 를 사용해, 장면을 초기화하는 다음의 스텝을 실행하고 있다.

  • 스텝 3.1 : 지오메트리를 준비한다
  • 스텝 3.2 : 머트리얼과 초기 라이팅 스테이트를 셋업 한다
  • 스텝 3.3 : 좌표 트랜스 폼 행렬을 준비, 설정한다


스텝 4 : 시스템 메세지를 감시한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

어플리케이션 윈도우의 생성 및 DirectX 오브젝트의 생성에 계속되어, 장면의 초기화를 종료 하면, 언제라도 장면을 렌더링 할 수 있는 상태가 된다. 보통, Windows 어플리케이션은 메시지 루프의 시스템 메세지를 감시해, 큐에 메세지가 없으면 언제라도 프레임의 렌더링을 실시한다. 샘플 Triangle 도, 똑같이 메시지 루프에 대해서 다음의 코드를 사용한다.

    BOOL bGotMsg;
    MSG  msg;
    PeekMessage( &msg, NULL, 0U, 0U, PM_NOREMOVE );
    g_bReady = TRUE;

    while( WM_QUIT ! = msg.message  )
    {
        // 어플리케이션이 액티브한 경우는, PeekMessage()를 사용한다. 이것에 의해, 아이돌 시간을 사용해,
        // 장면의 렌더링을 할 수가 있다. 그 이외의 경우에는, GetMessage()를 사용해, CPU 시간의 낭비를 피한다.
        if( g_bActive )
            bGotMsg = PeekMessage( &msg, NULL, 0U, 0U, PM_REMOVE );
        else
            bGotMsg = GetMessage( &msg, NULL, 0U, 0U );

        if( bGotMsg )
        {
                TranslateMessage( &msg );
                DispatchMessage( &msg );
        }
        else
        {
            // 아이돌 시간의 사이에 프레임을 렌더링 한다 (대기중의 메세지 없음).
            if( g_bActive && g_bReady )
                Render3DEnvironment();
        }
    }

위의 코드에서는, 글로벌 플래그 변수의 g_bActive 를 사용해 액티브하게 되는 시점을 추적해, 다른 변수의 g_bReady 를 사용해, 모든 시스템 오브젝트가, 장면의 렌더링의 준비가 되어 있는 것을 나타낸다. 어플리케이션에서는, 윈도우가 표시되어 있지 않은 경우는 항상 g_bActive 를 FALSE 로 설정해, 장면의 렌더링에 사용하는 오브젝트의 재생성이 필요한 경우는 항상 g_bReady 변수를 FALSE 로 설정한다. (후자에 대해서는, 「윈도우의 사이즈 변경을 처리한다」로 설명한다).

어플리케이션은, 액티브한 때에 메시지 큐를 체크해, 대기중의 메세지가 있는지 없는지를 확인한다. 큐에 메세지가 있는 경우는, 다른 Windows 어플리케이션과 같게 메세지를 디스팟치 한다. 큐에 메세지가 없는 경우는, 어플리케이션 정의 함수 Render3DEnvironment 를 호출해, 장면의 프레임을 렌더링 한다. 이것이, 「스텝 5 : 신을 렌더링, 표시한다」의 설명 내용이다.


스텝 5 : 신을 렌더링, 표시한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

어플리케이션은, 시스템 메세지를 처리하고 있지 않으면 언제라도, 장면의 프레임의 렌더링을 실시할 수가 있다. 샘플 Triangle 는, 메시지 큐가 하늘의 경우에 반드시, WinMain 로부터 어플리케이션 정의 함수 Render3Denvironment 를 호출해, 장면의 렌더링을 실시한다. Render3DEnvironment 함수는, 이 태스크를 다음의 3 개의 하위 스텝에 분할한다.

  • 스텝 5.1 : 신을 갱신한다
  • 스텝 5.2 : 신을 렌더링 한다
  • 스텝 5.3 : 디스플레이를 갱신한다


스텝 6 : 슛다운

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

어플리케이션은, 실행중이 있는 시점에서, 슛다운 해야 한다. DirectX 어플리케이션을 슛다운 하면은, 어플리케이션 윈도우를 파괴할 뿐만 아니라, 어플리케이션이 사용하고 있는 모든 DirectX 오브젝트의 할당을 해제해, 오브젝트에의 포인터를 무효로 하는 것을 의미한다. Triangle 에서는, WM_DESTROY 메세지를 받아들였을 때에, Cleanup3Denvironment 라고 하는 어플리케이션 정의 함수를 호출해, 이 클린 업 (정리 작업)을 실시하고 있다.

HRESULT Cleanup3DEnvironment()
{
    // 장면에 생성 된 모든 오브젝트의 클린 업을 실시한다.
    App_DeleteDeviceObjects( g_pd3dDevice );

    // 어플리케이션이 사용하고 있던 DDraw 와 D3D 의 오브젝트를 릴리즈 한다.
    if( g_pD3D )           g_pD3D->Release();
    if( g_pddsBackBuffer ) g_pddsBackBuffer->Release();
    if( g_pddsPrimary )    g_pddsPrimary->Release();

    // D3DDEVICE 를 릴리즈 할 때에 안전 체크를 실시한다. RefCount 는 제로일 것이다.
    if( g_pd3dDevice )
        if( 0 < g_pd3dDevice->Release() )
            return E_FAIL;

    // DDRAW 를 릴리즈 할 때에 안전 체크를 실시한다. RefCount 는 제로일 것이다.
    if( g_pDD )
        if( 0 < g_pDD->Release() )
            return E_FAIL;

    g_pd3dDevice     = NULL;
    g_pD3D           = NULL;
    g_pddsBackBuffer = NULL;
    g_pddsPrimary    = NULL;
    g_pDD            = NULL;

    return S_OK;
}

위의 함수는, 각 오브젝트에 대해서 IUnknown::Release 메소드를 호출해, 어플리케이션이 사용하고 있는 DirectX 오브젝트의 할당을 해제하고 있다. 이 튜토리얼은 COM 규칙에 따르고 있기 (위해)때문에, 대부분의 오브젝트에 대한 참조 카운트는 제로일 것으로, 자동적으로 메모리로부터 삭제된다.

슛다운 하면나무 이외에도, 유저가 데스크탑 해상도나 색깊이를 변경했을 때등의 보통의 실행시에, 사용중의 DirectX 오브젝트를 파기해 재생성 할 필요가 생기는 일도 있다. 그 때문에, 필요한 경우에 호출할 수가 있도록, 어플리케이션의 클린 업 코드를 1 개소에 유지해 두면(자) 편리하다.


윈도우의 이동을 처리한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

윈도우로 실행되는 DirectX 어플리케이션은, 윈도우에 대한 블리트가 데스크탑의 올바른 위치에 나타나도록(듯이), 윈도우의 클라이언트 영역의 위치를 추적해야 한다. 이 추적을 게을리하면(자), 그래픽스가 어플리케이션 윈도우의 외측에 나타나 유저를 혼란시키게 된다. 샘플 Triangle 는, 다음에 나타내도록(듯이), 시스템이 윈도우 프로시저에 보내는 WM_MOVE 메세지에 응답한다.

 .
 .
 .
    case WM_MOVE:
        // 이동 메세지는, 프라이머리 표면에 백 버퍼를 블리트 하는데 사용한다.
        // 화면의 직사각형을 갱신하기 위해서 추적할 필요가 있다.
        if( g_bActive && g_bReady )
            OnMove( (SHORT) LOWORD(lParam), (SHORT) HIWORD(lParam) );
        break;
 .
 .
 .

g_bActive 변수는, 윈도우 프로시저의 다른 개소에서 설정되어 윈도우가 액티브한가 어떤가를 나타내, 윈도우가 최소화되고 있는 경우에는 FALSE 로 설정된다. 변수 g_bReady 에는, 어플리케이션이 사용중의 DirectX 오브젝트를 재생성 하고 있을 때를 제외해, TRUE 가 설정된다. 이 2 개의 변수가 모두 TRUE 인 경우에, 다음의 어플리케이션 정의 함수 OnMove 가 불려 간다.

VOID OnMove( INT x, INT y )
{
    DWORD dwWidth  = g_rcScreenRect.right - g_rcScreenRect.left;
    DWORD dwHeight = g_rcScreenRect.bottom - g_rcScreenRect.top;
    SetRect( &g_rcScreenRect, x, y, x + dwWidth, y + dwHeight );
}

이 함수는, 글로벌 변수 g_rcScreenRect 의 사이즈를 단지 재계산하는 것이다. 이 튜토리얼에서는, 「스텝 5.3 : 디스플레이를 갱신한다」로 디스플레이를 갱신할 경우에, 이 글로벌 변수를 목적의 직사각형으로서 사용하고 있다.


윈도우의 사이즈 변경을 처리한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

윈도우로 실행되는 DirectX 어플리케이션은, 시스템이 보내는 모든 WM_SIZE 메세지에 응답해야 한다. 렌더링 타겟 표면은, 보통, 메모리의 절약을 위해서(때문에) 최소한으로 유지되고 있다. 그 최소 사이즈는, 보통, 윈도우의 클라이언트 영역의 사이즈가 된다. 윈도우 사이즈가 커졌을 경우, 렌더링 타겟 표면과 관련 오브젝트를 파기해, 적절한 사이즈로 재생성 할 필요가 생긴다. 실제로는, 어플리케이션이 이 처리를 실행하는 것은, 윈도우가 커졌을 경우만으로 좋다. 윈도우 사이즈가 작아졌을 경우에는, 그 정도로 응해, 뷰포트를 조절해, 블리트의 사이즈를 축소하는 것으로써 대응할 수 있다. 이 튜토리얼에서는, 이해하기 쉽게하기 위해(때문에), WM_SIZE 메세지를 받아들이면(자) 반드시 사용하고 있는 오브젝트를 파기해, 재생성 하도록(듯이) 하고 있다.

         .
         .
         .
        case WM_SIZE:
            // 윈도우가 사용 가능한가 어떤가의 확인을 실시한다.
            // 액티브 플래그에 대응하는 값을 설정한다.
            if( SIZE_MAXHIDE==wParam || SIZE_MINIMIZED==wParam )
                g_bActive = FALSE;
            else g_bActive = TRUE;

            // 새로운 윈도우 사이즈에 의해, 새로운 백 버퍼 사이즈가 필요하게 된다.
            // 이것을 실시하는 가장 간단한 방법은, 모든 것을 릴리즈 해, 재생성 하는 것이다.
            // 주 ：  윈도우가 너무 커졌을 경우에는, 메모리 부족하게 되어,
            // 종료할 필요가 생길 가능성이 있다. 이 단순한 어플리케이션은,
            // 에러 메세지를 표시하지 않고 종료하지만,
            // 실제의 어플리케이션에서는, 좀 더 잘 동작할 필요가 있다.
            if( g_bActive && g_bReady )
            {
                g_bReady = FALSE;
                if( FAILED( Cleanup3DEnvironment() ) )
                    DestroyWindow( hWnd );
                if( FAILED( Initialize3DEnvironment( hWnd ) ) )
                    DestroyWindow( hWnd );
                g_bReady = TRUE;
            }
            break;
         .
         .
         .

위의 코드에서는, 글로벌 변수를 설정해, 사용중의 DirectX 오브젝트가 무효화되고 있는 것을, 코드외의 부분에 통지하고 있는 것에 주의한다. 게다가 이 코드는, 어플리케이션의 슛다운시에도 불려 가는 어플리케이션 정의 함수 Cleanup3Denvironment 를 호출하고 있다. 어플리케이션의 종료에 대해서는, 「스텝 6 : 슛다운」으로 설명한다.


튜토리얼 2 : 깊이 버퍼를 추가한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

Direct3D 어플리케이션에서는, 장면의 오브젝트를 올바르게 표시하는데, 깊이 버퍼에 의존하는 것이 많다. 개념적인 개요에 대해서는, 「깊이 버퍼」를 참조할것. 깊이 버퍼를 사용하려면 , 지원 되고 있는 깊이 버퍼 포맷을 열거해, 깊이 버퍼 표면을 생성 해, 렌더링 타겟 표면에 깊이 버퍼 표면을 Attach 한 후, 렌더링 디바이스의 깊이 버퍼링을 유효하게 해야 한다.

이 튜토리얼에서는, 샘플 프로젝트 Triangle 의 코드를 사용하면서 설명한다. 이 코드에서는, 가장 일반적으로 지원 되고 있는 깊이 버퍼의 타입인, z 버퍼가 사용되고 있다. 샘플 ZBuffer 는, 다음의 스텝을 실행해, z 버퍼를 사용한다.

  • 스텝 1 : 깊이 버퍼 포맷을 열거한다
  • 스텝 2 : 깊이 버퍼를 생성 한다
  • 스텝 3 : 깊이 버퍼를 Attach 한다
  • 스텝 4 : 깊이 버퍼링을 유효하게 한다

주 : ZBuffer 샘플의 코드는, Triangle 의 코드와 거의 같다. 이 튜토리얼에서는, Zbuffer 에 특유인 깊이 버퍼 코드만을 채택해 Direct3D 의 셋업, 렌더링, 슛다운, Windows 메세지의 처리는 설명하지 않는 것으로 한다. 이러한 태스크에 대해서는, 「튜토리얼 1 : 단일의 삼각형을 렌더링 한다」를 참조할것.

렌더링 디바이스에 따라서는, 깊이 버퍼를 메모리의 특정의 장소에 위치시킬 필요가 있기 (위해)때문에, 렌더링 디바이스를 생성 하기 전에, 깊이 버퍼 표면을 생성 해, 렌더링 타겟 표면에 Attach 할 필요가 있다.


스텝 1 : 깊이 버퍼 포맷을 열거한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

렌더링 디바이스가 깊이 버퍼를 지원 하고 있다면, 깊이 버퍼의 생성전에, 어떠한 깊이 버퍼 포맷을 지원 하고 있는지를 확인해 두지 않으면 안 된다. IDirect3D7::EnumZBufferFormats 메소드를 호출해, 디바이스로 지원 하고 있는 깊이 버퍼 포맷을 열거한다. 샘플 ZBuffer 에서는, 다음의 코드를 사용해, 깊이 버퍼 포맷을 열거하고 있다.

    //-------------------------------------------------------------------------
    // 백 버퍼를 생성 하고 나서 d3ddevice 를 생성 하기까지
    // Z 버퍼를 생성 한다.
    //
    // 주 :  Z 버퍼의 생성전에, 어플리케이션에서는,
    // D3DPRASTERCAPS_ZBUFFERLESSHSR 플래그의 디바이스 능력을 체크하는 경우도 있다.
    // 플래그는, z 버퍼없이, HSR (hidden-surface-removal)를
    // 실시할 수가 있는 하드웨어에 대해서 TRUE 가 된다. 그러한 디바이스에 대해서는, z 버퍼를 생성 할 필요는 없다.
    //-------------------------------------------------------------------------

    DDPIXELFORMAT ddpfZBuffer;
    g_pD3D->EnumZBufferFormats( *pDeviceGUID,
                                 EnumZBufferCallback, (VOID*) &ddpfZBuffer );

EnumZBufferFormats 메소드는, 포맷을 열거하는 대상이 되는 디바이스의 글로벌 유니크 식별자 (GUID), 콜백 함수의 주소, 및 콜백 함수에게 건네지는 임의의 데이터 구조체의 주소를 받아들인다. 유저가 제공하는 콜백 함수는,D3DEnumPixelFormatsCallback 함수 prototype에 따르지 않으면 안 된다. 시스템은, 콜백 함수가 D3DENUMRET_CANCEL 를 돌려주지 않는 이상 지정된 콜백 함수를, 지원 되고 있는 각 깊이 버퍼 포맷에 대해서 한 번 두개 호출한다. 샘플 ZBuffer 는, 다음과 같은 콜백 함수를 처리한다.

static HRESULT WINAPI EnumZBufferCallback( DDPIXELFORMAT* pddpf,
                                           VOID* pddpfDesired )
{
    // 이 튜토리얼에서의 대상은 Z 버퍼만으로,
    // 다른 포맷 (DDPF_STENCILBUFFER 등)이 열거되어도 모두 무시한다. 또,
    // 어플리케이션에서는, Z 버퍼의 깊이 (16 비트등)를 조사해
    // 그 결과에 근거해 선택할 수도 있다. 이 튜토리얼에서는, 최초로 열거되었다
    // 포맷을 선택한다.
    if( pddpf->dwFlags == DDPF_ZBUFFER )
    {
        memcpy( pddpfDesired, pddpf, sizeof(DDPIXELFORMAT) );

        // D3DENUMRET_CANCEL 를 돌려주어 검색을 종료한다.
        return D3DENUMRET_CANCEL;
    }

    // D3DENUMRET_OK 를 돌려주어 검색을 속행한다.
    return D3DENUMRET_OK;
}

시스템이 이 콜백 함수를 호출하면나무에는, 깊이 버퍼의 픽셀 포맷을 기술하는 DDPIXELFORMAT 구조체의 주소를 건네준다. dwFlags 멤버에는, 깊이 버퍼 비트를 포함한 임의의 픽셀 포맷에 대해서 DDPF_ZBUFFER 가 저장 된다. 그 경우,dwZBufferBitDepth 멤버에 깊이 정보에 예약되고 있는 픽셀 포맷중의 비트수를 나타내는 정수가 저장 되어dwZBitMask 멤버가 관련 비트를 마스크 한다.

이 튜토리얼에서는, 이해하기 쉽게하기 위해(때문에), 가장 일반적인 타입의 깊이 버퍼인 z 버퍼만을 사용하고 있다. 시스템이 열거하는 것 외의 포맷 (DDPF_STENCILBUFFER 등)은, 모두 무시한다. 어플리케이션은, z 버퍼의 비트 깊이 (8, 16, 24, 32 비트)를 체크해, 비트 깊이에 근거한 선택을 실시할 수도 있다. 적절한 포맷이 발견되면(자), 이 콜백 함수는, 주어진 DDPIXELFORMAT 구조체를 2 번째의 파라미터로 건네받은 주소 (이것도,DDPIXELFORMAT 구조체)에 카피해, 열거를 종료시키기 (위해)때문에 D3DENUMRET_CANCEL 를 돌려준다.

깊이 버퍼의 포맷을 결정하면(자), 그 포맷을 사용하는 DirectDrawSurface 를 생성 할 수가 있다. 이것이, 「스텝 2 : 깊이 버퍼를 생성 한다」의 설명 내용이다.


스텝 2 : 깊이 버퍼를 생성 한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

여기서, 깊이 버퍼 포맷의 선택을 종료했으므로, 깊이 버퍼가 되는 DirectDrawSurface 오브젝트를 생성 할 수가 있다. 표면의 픽셀 포맷은, 열거에 의해 결정된 것이지만, 표면의 치수는, Attach 되는 렌더링 타겟 표면과 동일하게 해야 한다. 샘플 ZBuffer 에서는, 이 태스크에 대해서 다음의 코드를 사용한다.

    // 적절한 Z 버퍼 포맷이 발견되면(자),
    // 열거중에 dwSize 필드가 올바르게 설정된다. 적절한 Z 버퍼 포맷이 발견되지 않았던 경우는, 문제가 있기 (위해)때문에 종료한다.
    if( sizeof(DDPIXELFORMAT) ! = ddpfZBuffer.dwSize )
        return E_FAIL;

    // 렌더링 타겟으로부터 z 버퍼의 사이즈를 취득한다.
    // z 버퍼의 표면 기술을 셋업 한다.
    ddsd.dwFlags        = DDSD_CAPS|DDSD_WIDTH|DDSD_HEIGHT|DDSD_PIXELFORMAT;
    ddsd.ddsCaps.dwCaps = DDSCAPS_ZBUFFER;
    ddsd.dwWidth        = g_rcScreenRect.right - g_rcScreenRect.left;
    ddsd.dwHeight       = g_rcScreenRect.bottom - g_rcScreenRect.top;
    memcpy( &ddsd.ddpfPixelFormat, &ddpfZBuffer, sizeof(DDPIXELFORMAT) );

    // 하드웨어 디바이스의 경우, Z 버퍼를 비디오 메모리내에 생성 해야 한다. 소프트웨어 디바이스의 경우는,
    // Z 버퍼를 시스템 메모리내에 생성 한다.
    if( IsEqualIID( *pDeviceGUID, IID_IDirect3DHALDevice ) )
        ddsd.ddsCaps.dwCaps |= DDSCAPS_VIDEOMEMORY;
    else
        ddsd.ddsCaps.dwCaps |= DDSCAPS_SYSTEMMEMORY;

    // Z 버퍼를 생성 해 Attach 한다. 실제의 어플리케이션에서는,
    // 여기서 에러 처리를 실시한다 (DDERR_OUTOFVIDEOMEMORY 가 발생하는 경우가 있다). 다만,
    // 이 튜토리얼에서는, 이 에러 처리를 실시하지 않고 종료한다.
    if( FAILED( hr = g_pDD->CreateSurface( &ddsd, &g_pddsZBuffer, NULL ) ) )
        return hr;

위의 코드는, 설정 끝난 글로벌 변수로부터 계산된 렌더링 타겟 표면의 치수를 사용해, 깊이 버퍼용의 DDSURFACEDESC2 구조체를 준비해 있는 것만으로 있다. 전의 스텝 「스텝 1 : 깊이 버퍼 포맷을 열거한다」로 취득한 픽셀 포맷 정보는, 표면 기술에 카피된다.

주 : 하드웨어 디바이스에서는, 깊이 버퍼를 메모리내에서의 그 위치에 관계없이 사용할 수 있다. 하드웨어 디바이스의 사용시에는, 표면 능력 플래그 DDSCAPS_VIDEOMEMORY 및 DDSCAPS_SYSTEMMEMORY 를 생략 해, 버퍼의 최적 위치를 디바이스로 결정시키는 것이 최선이다. 그러나, 소프트웨어 디바이스는, 깊이 버퍼가 시스템 메모리에 존재하지 않으면 생성 할 수가 없다. 위의 코드에서는, 소프트웨어 디바이스일 가능성을 체크해, 필요에 따라서 DDSCAPS_SYSTEMMEMORY 플래그를 포함하도록(듯이) 하고 있다.

표면 기술의 준비를 할 수 있으면(자), 이 코드에서는,IDirectDraw7::CreateSurface 메소드를 호출해 새로운 깊이 버퍼 표면을 생성 한다. 깊이 버퍼를 생성 한 후, 그 깊이 버퍼를 렌더링 타겟으로서 사용되는 표면에 Attach 할 수 있다. 이 처리에 대해서는, 「스텝 3 : 깊이 버퍼를 Attach 한다」로 설명한다.


스텝 3 : 깊이 버퍼를 Attach 한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

깊이 버퍼를 생성 하면(자), 렌더링 타겟으로서 사용되는 표면에 Attach 할 필요가 있다. 이것을 실시하려면 , 렌더링 타겟 표면의 IDirectDrawSurface7::AddAttachedSurface 메소드를 호출한다. 샘플 ZBuffer 에서는, 다음의 코드를 사용해 이 처리를 실행한다.

    // 백 버퍼에 Z 버퍼를 Attach 한다.
    if( FAILED( hr = g_pddsBackBuffer->AddAttachedSurface( g_pddsZBuffer ) ) )
        return hr;

깊이 버퍼를 렌더링 타겟 표면에 Attach 하면, 깊이 버퍼링이 유효하게 되어 있는 경우, 시스템은 항상, 이 깊이 버퍼를 자동적으로 사용한다. 이것에 대해서는, 「스텝 4 : 깊이 버퍼링을 유효하게 한다」로 설명한다.


스텝 4 : 깊이 버퍼링을 유효하게 한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

깊이 버퍼를 렌더링 타겟 표면에 Attach 하면, 렌더링 타겟으로부터 렌더링 디바이스를 생성 할 수가 있다.

어플리케이션으로 깊이 버퍼를 사용하는 경우, 뷰포트 및 깊이 버퍼의 양쪽 모두를 클리어 할 필요가 있다. 깊이 버퍼를 클리어 하려면 ,IDirect3DDevice7::Clear 메소드에 D3DCLEAR_ZBUFFER 플래그를 지정한다.

    pd3dDevice->Clear( 0, NULL, D3DCLEAR_TARGET|D3DCLEAR_ZBUFFER,
                       0x000000ff, 1.0f, 0L );

렌더링 디바이스가 준비되면(자), 그 디바이스의 D3DRENDERSTATE_ZENABLE 렌더링 스테이트를 설정해, 깊이 버퍼링을 유효하게 할 수가 있다. D3DZBUFFERTYPE 열거형에는, 깊이 버퍼의 렌더링 스테이트를 설정하는 멤버가 포함되어 있다. D3DZB_TRUE 멤버 (또는 TRUE)에 의해, z 버퍼링을 유효하게 한다. 샘플 ZBuffer 는, 어플리케이션 정의 함수 App_Render 에서의 장면의 렌더링중에, z 버퍼링을 유효하게 하고 있다. 다음의 코드는, App_Render 로부터의 해당 부분의 발췌이다.

    // z 버퍼링을 유효하게 한다 (주 :  실제로는 이 처리를 프레임 마다 실시할 필요는 없다).
    pd3dDevice->SetRenderState( D3DRENDERSTATE_ZENABLE, TRUE );

이 튜토리얼에서는, 프레임 단위에 깊이 버퍼링을 유효하게 하고 있지만, 이것은 필수는 아니다. 실제의 어플리케이션에서는, 장면의 초기화중에 D3DRENDERSTATE_ZENABLE 렌더링 스테이트를 설정해 두어, 깊이 버퍼링을 무효로 하거나 깊이 버퍼링의 다른 타입을 선택할 경우에만 변경하는 것이 보통이다.

주 : D3DZBUFFERTYPE 열거형에는, 준거 하드웨어에서의 W 베이스의 깊이 비교를 유효하게 하는 D3DZB_USEW 값이 포함된다. 상세한 것에 대하여는, 「깊이 버퍼」를 참조할것.


튜토리얼 3 : 다양한 프리미티브 스타일을 사용한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

여기에서는, Direct3D 의 다양한 드로잉(Drawing) 프리미티브의 호출을 사용해 다각형을 렌더링 하는 방법에 대해 설명한다. 이 튜토리얼로 사용하는 프리미티브는, 적어도 3 개의 버텍스를 가지는 닫은 3 차원 (3D) 오브젝트로서의 다각형이다.

이 튜토리얼에서는, 특히 일련의 프리미티브 (벽세그먼트(segment), 원추, 입방체)에 지오메트리를 준비하는 방법을 나타낸다. 즉, 뷰 포인트를 회전하는 방법이나, 행렬을 연결해 입방체의 평행이동, 회전, 및 스케일링등의 3D 트랜스 폼을 실행하는 방법에 대해 설명한다.

  • 스텝 1 : 신의 지오메트리를 초기화한다
  • 스텝 2 : 신을 렌더링, 표시한다

3D 프리미티브의 상세한 것에 대하여는, 「3D 프리미티브」를 참조할것.

주 : DrawPrims 어플리케이션의 코드는, Triangle 로 사용하는 코드에 유사하고 있다. 이 튜토리얼에서는, 지오메트리의 준비, 및 DrawPrims 어플리케이션 고유의 렌더링 코드에게만 중점을 두어, Direct3D 의 셋업, 슛다운, 또는 시스템 이벤트의 처리에 대해서는 접하지 않는다. 이러한 태스크의 상세한 것에 대하여는, 「튜토리얼 1 : 단일의 삼각형을 렌더링 한다」를 참조할것.

여기에서는, 깊이 버퍼를 사용해 장면의 깊이 정보를 저장 한다. 깊이 버퍼를 사용하려면 , 지원 되고 있는 깊이 버퍼 포맷을 열거해, 깊이 버퍼 표면을 생성 해, 그 깊이 버퍼 표면을 렌더링 타겟 표면에 Attach 해, 렌더링 디바이스에 대해서 깊이 버퍼링을 유효하게 할 필요가 있다. 이러한 태스크의 상세한 것에 대하여는, 「튜토리얼 2 : 깊이 버퍼를 추가한다」를 참조할것.


스텝 1 : 신의 지오메트리를 초기화한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

이 튜토리얼에서는, 어플리케이션 정의의 App_InitDeviceObjects 메소드로 원시적으로 지오메트리를 준비한다. App_InitDeviceObjects 는, 각 오브젝트에 일련의 버텍스를 정의해, 글로벌 정의된 데이터 구조체에 각 프리미티브의 버텍스 정보를 저장 한다. 버텍스 정보는, 렌더링시에 DrawPrimitive 메소드로 사용된다.

기술적으로는, 이 시점에서 지오메트리를 설정할 필요는 없다. 렌더링 메소드를 호출하기 전에 언제라도 설정할 수 있다.

  • 스텝 1.1 : 벽세그먼트(segment)를 준비한다
  • 스텝 1.2 : 원추를 준비한다
  • 스텝 1.3 : 입방체를 준비한다

프리미티브의 종류의 상세한 것에 대하여는, 「프리미티브의 종류」를 참조할것.

Direct3D 에 있어서의 버텍스의 지정 방법의 상세한 것에 대하여는, 「버텍스 포맷」을 참조할것.

주 : 특정의 원시적으로 준비하는 지오메트리의 순서는, 장면의 오브젝트의 레이아웃에 영향을 주지 않는다.


스텝 2 : 신을 렌더링, 표시한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

장면의 오브젝트를 올바르게 표시 및 조작하려면 , 장면의 시점을 정의해, 뷰 행렬을 생성 해, 필요한 트랜스 폼을 실행해, 완성한 장면을 렌더링 할 필요가 있다. 이러한 태스크에 대해서는, 다음의 스텝에서 설명한다.

  • 스텝 2.1 : 뷰 포인트를 정의한다
  • 스텝 2.2 : 뷰 행렬을 생성 및 설정한다
  • 스텝 2.3 : 3D 트랜스 폼을 실행한다
  • 스텝 2.4 : 신을 렌더링 한다

장면의 렌더링의 상세한 것에 대하여는, 「프리미티브의 렌더링」을 참조할것.


튜토리얼 4 : 디바이스 열거를 사용한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

디바이스 열거가 편리한 것은, 하드웨어가 지원 하는 Direct3D 디바이스에 대해, 어플리케이션으로부터 하드웨어에 문의할 수가 있는 점이다. 그 결과, 특정의 하드웨어 구성을 활용한 어플리케이션을 구축하거나 시스템의 하드웨어가 지원 하는 특정의 구성을 유저측에서의 선택에 맡길 수가 있다. 여기에서는, 드라이버, 디스플레이 모드, 및 디바이스를 열거해, 한층 더 각 디바이스로 지원 되는 디스플레이 모드의 리스트를 생성 한다.

기본적으로, 디바이스 열거에는 크게 나누어 2 개의 스텝이 있어, (1) 디바이스 열거를 초기화해 실행하는, (2) 열거된 디바이스의 선택, 이라고 하는 처리를 실시한다.

여기에서는, 이 처리를 다음의 항으로 나누어 설명한다.

  • 스텝 1 : 디바이스 열거를 초기화해 실행한다
  • 스텝 2 : 열거된 디바이스의 선택

Direct3D 디바이스의 상세한 것에 대하여는, 「Direct3D 디바이스」를 참조할것.

디바이스의 열거의 상세한 것에 대하여는, 「Direct3D 디바이스의 열거」를 참조할것.

주 : Enumeration 어플리케이션으로 사용하는 코드는, Triangle 어플리케이션의 코드에 유사하고 있다. 이 튜토리얼에서는, Enumeration 어플리케이션 고유의 디바이스 열거 코드에게만 중점을 두어, Direct3D 의 셋업, 장면 지오메트리의 준비, 슛다운, 또는 시스템 이벤트의 처리에 대해서는 접하지 않는다. 이러한 태스크의 상세한 것에 대하여는, 「튜토리얼 1 : 단일의 삼각형을 렌더링 한다」를 참조할것.

여기에서는, 깊이 버퍼를 사용해 장면의 깊이 정보를 저장 한다. 깊이 버퍼를 사용하려면 , 지원 되고 있는 깊이 버퍼 포맷을 열거해, 깊이 버퍼 표면을 생성 해, 그 깊이 버퍼 표면을 렌더링 타겟 표면에 Attach 해, 렌더링 디바이스에 대해서 깊이 버퍼링을 유효하게 할 필요가 있다. 이러한 태스크의 상세한 것에 대하여는, 「튜토리얼 2 : 깊이 버퍼를 추가한다」를 참조할것.

여기에서는, 일련의 원추 프리미티브를 그린다. 프리미티브의 드로잉(Drawing) 방법의 상세한 것에 대하여는, 「튜토리얼 3 : 다양한 프리미티브 스타일을 사용한다」를 참조할것.


스텝 1 : 디바이스 열거를 초기화해 실행한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

Enumeration 어플리케이션은, 다음의 구조체를 사용해, 열거된 Direct3D 디바이스에 대한 정보를 보관 유지한다.

struct D3DDEVICEINFO
{
    // D3D 디바이스 정보.
    CHAR           strDesc[40];
    GUID*          pDeviceGUID;
    D3DDEVICEDESC7 ddDeviceDesc;
    BOOL           bHardware;

    // DDraw 드라이버 정보.
    GUID*          pDriverGUID;
    DDCAPS         ddDriverCaps;
    DDCAPS         ddHELCaps;

    // DDraw 모드 정보.
    DDSURFACEDESC2 ddsdMode;
    BOOL           bFullscreen;

    // 내부 사용의 경우 (어플리케이션에서는 이것들은 필요없다).
    GUID           guidDevice;
    GUID           guidDriver;
    DDSURFACEDESC2 ddsdModes[100];
    DWORD          dwNumModes;
    DWORD          dwCurrentMode;
    BOOL           bDesktopCompatible;
};

Enumeration 어플리케이션에서는, 다음의 호출에 의해 열거를 초기화한다.

INT UserDlgSelectDriver( HWND hwndParent )
{
    // 드라이버, 디바이스, 및 모드를 열거한다.
    DirectDrawEnumerateEx( DriverEnumCallback, NULL,
                           DDENUM_ATTACHEDSECONDARYDEVICES |
                           DDENUM_DETACHEDSECONDARYDEVICES |
                           DDENUM_NONDISPLAYDEVICES );

위의 코드에서는, 시스템으로 사용할 수 있는 드라이버, 디바이스, 및 디스플레이 모드를 열거하는데 DirectDrawEnumerateEx 메소드를 사용하고 있다. 제 1 파라미터 DriverEnumCallback, 는, 열거되는 각각의 DirectDraw 로 유효한 HAL 의 기술로 불려 가는 DDEnumCallbackEx 함수의 주소이다.

어플리케이션의 디바이스 열거 프로세스는, 다음의 스텝으로 나누어진다.

  • 스텝 1.1 : 드라이버 정보를 열거한다
  • 스텝 1.2 : 디스플레이 모드 정보를 열거한다
  • 스텝 1.3 : 디바이스 정보를 열거한다

디바이스 열거를 사용하는 어플리케이션의 최초의 스텝은, DirectDraw 드라이버에의 참조의 취득이다. 드라이버 열거에 대해서는, 「스텝 1.1 : 드라이버 정보를 열거한다」로 설명한다.

디바이스 열거의 시작의 상세한 것에 대하여는, 「디바이스 열거의 시작」을 참조할것.


스텝 2 : 열거된 디바이스의 선택

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

열거된 디바이스를 선택 하면나무는, 보통, 다음의 스텝을 실행한다.

  • 스텝 2.1 : 디바이스를 취득한다
  • 스텝 2.2 : 디바이스를 테스트한다

열거된 디바이스의 선택의 상세한 것에 대하여는, 「열거된 디바이스의 선택」을 참조할것.


튜토리얼 5 : 텍스쳐 맵을 사용한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

이 튜토리얼에서는, 텍스쳐를 사용한 간단한 3D 신의 드로잉(Drawing) 방법에 대해 설명한다. 본래, Direct3D 텍스쳐란, 픽셀 컬러의 비트 맵이다. 이 때문에, Direct3D 원시적이게는, 모든 비트 맵 이미지를 적용할 수 있다. 텍스쳐는, 지오메트리를 변경하는 일 없이 3D 오브젝트를 리얼하게 표현할 수 있는, 간단하고 효과적인 방법이다. 텍스쳐를 이와 같이 활용하면, 색, 엉성함, 투과성, 및 매끄러움의 패턴과 일루젼을 더해 프리미티브의 질을 향상시킬 수가 있다. 특히, 여기에서는, 파일 베이스의 비트 맵으로부터 텍스쳐를 생성 하는 방법이나, 텍스쳐를 사용해 입방체를 렌더링 하는 방법에 대해 설명한다.

현재 Direct3D 에서는 텍스쳐 핸들이 폐지되고 있다. 이 때문에, 텍스쳐를 생성 및 사용할때는, 텍스쳐 표면의 인터페이스 포인터를 이용한다. 상세한 것에 대하여는, 「텍스쳐 인터페이스와 텍스쳐 핸들」을 참조할것.

3D 신의 원시적으로 텍스쳐를 추가하려면 , 다음의 스텝을 실행한다.

  • 스텝 1 : 텍스쳐 표면을 준비한다
  • 스텝 2 : 텍스쳐 표면을 생성 한다
  • 스텝 3 : 텍스쳐 프리미티브의 렌더링

Direct3D 에서는 확장 텍스쳐 기능 세트를 지원 하고 있어, 고도의 텍스쳐 처리 기술을 간단하게 이용할 수 있다. 텍스쳐, 및 Direct3D 에서의 텍스쳐의 사용 방법과 최적화 방법의 상세한 것에 대하여는, 「텍스쳐」를 참조할것.

주 : Texture 어플리케이션의 코드는, Triangle 어플리케이션의 코드에 유사하고 있다. 이 튜토리얼에서는, Texture 어플리케이션 고유의 텍스쳐 코드에게만 중점을 두어, Direct3D 의 셋업, 장면 지오메트리의 준비, 슛다운, 또는 시스템 이벤트의 처리에 대해서는 접하지 않는다. 이러한 태스크의 상세한 것에 대하여는, 「튜토리얼 1 : 단일의 삼각형을 렌더링 한다」를 참조할것.

여기에서는 입방체를 그린다. 프리미티브의 드로잉(Drawing) 방법의 상세한 것에 대하여는, 「튜토리얼 3 : 다양한 프리미티브 스타일을 사용한다」를 참조할것.

여기에서는, 열거를 사용해 텍스쳐 포맷을 열거한다. 열거의 기술 및 원리의 상세한 것에 대하여는, 「튜토리얼 4 : 디바이스 열거를 사용한다」를 참조할것.


스텝 1 : 텍스쳐 표면을 준비한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

3D 신으로 시스템 관리하의 텍스쳐를 올바르게 준비하려면 , 다음의 스텝을 실행한다.

  • 스텝 1.1 : 텍스쳐 좌표를 설정한다
  • 스텝 1.2 : 텍스쳐 표면을 준비한다
  • 스텝 1.3 : 텍스쳐 관리를 유효하게 한다
  • 스텝 1.4 : 텍스쳐 포맷을 열거한다

원시적으로 텍스쳐를 생성 하기 전에, 텍스쳐 좌표에 따라 프리미티브의 버텍스를 정의할 필요가 있다. 이 태스크에 대해서는, 「스텝 1.1: 텍스쳐 좌표를 설정한다」로 설명한다.


스텝 2 : 텍스쳐 표면을 생성 한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

준비한 표면으로부터 텍스쳐 표면을 생성 하는 태스크에 대해, 다음의 스텝으로 나누어 설명한다.

  • 스텝 2.1 : 렌더링 타겟을 취득한다
  • 스텝 2.2 : 새로운 표면을 생성 한다
  • 스텝 2.3 : 렌더링 표면에 카피한다

텍스쳐 표면 오브젝트는, 단순한 DirectDraw 표면 오브젝트이다. 텍스쳐 표면의 상세한 것에 대하여는, 「텍스쳐 표면 오브젝트」를 참조할것.

텍스쳐 표면을 생성 하기 전에, 디바이스의 렌더링 타겟을 취득할 필요가 있다. 이 처리에 대해서는, 「스텝 2.1 : 렌더링 타겟을 취득한다」로 설명한다.


스텝 3 : 텍스쳐 프리미티브의 렌더링

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

텍스쳐 처리된 프리미티브와 텍스쳐 처리되어 있지 않은 프리미티브의 렌더링에는 1 개만 차이가 있다. 그것은, 텍스쳐 처리된 프리미티브의 경우, 렌더링 시에 텍스쳐를 설정할 필요가 있다고 하는 점이다.

다음의 코드는 Texture 어플리케이션의 코드의 일부이다. 이 코드에서는, 텍스쳐 표면 g_pddsTexture1 를 사용해 입방체의 전면 및 뒷면을 드로잉(Drawing) 하고 있다.

    pd3dDevice->SetTexture( 0, g_pddsTexture1 );
    pd3dDevice->DrawPrimitive( D3DPT_TRIANGLESTRIP, D3DFVF_VERTEX,
                               g_pCubeVertices+0, 4, NULL );
    pd3dDevice->DrawPrimitive( D3DPT_TRIANGLESTRIP, D3DFVF_VERTEX,
                               g_pCubeVertices+4, 4, NULL );

IDirect3DDevice7::SetTexture 메소드는, 디바이스로 지정된 스테이지에 텍스쳐를 할당한다. 이 튜토리얼에서는 멀티 텍스쳐 블렌딩을 사용하지 않기 때문에,SetTexture 의 제 1 파라미터를 0 으로 해 스테이지 식별자에 0 을 지정하고 있다. 제 2 파라미터는, 텍스쳐로서 설정하는 IDirectDrawSurface7 오브젝트를 지정한다.

입방체의 표면과 저면, 및 좌측면과 우측면에도 같은 프로시저를 사용해, 각각 g_pddsTexture2 과 g_pddsTexture3 를 설정한다. 이 방법에 대해서는, SDK 부속의 Texture 어플리케이션을 참조할것.

텍스쳐의 렌더링의 상세한 것에 대하여는, 「텍스쳐 표면을 사용한 렌더링」을 참조할것.

멀티 텍스쳐 블렌딩의 상세한 것에 대하여는, 「멀티 텍스쳐 블렌딩」을 참조할것.


Direct3D 직접 모드 Visual Basic 튜토리얼

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

이 Microsoft® Visual Basic® 튜토리얼에서는, 일반적인 태스크를 실행하는 간단한 Direct3D® 어플리케이션의 생성 방법에 대해 설명한다. 이러한 튜토리얼에서는, DirectX® SDK 에 첨부되고 있는 Direct3D 의 샘플 파일을 사용한다. 다음의 튜토리얼을 제공한다.

  • 튜토리얼 1 : 단일의 삼각형을 렌더링 한다
  • 튜토리얼 2 : 깊이 버퍼를 추가한다
  • 튜토리얼 3 : 다양한 프리미티브 스타일을 사용한다
  • 튜토리얼 4 : 디바이스 열거를 사용한다
  • 튜토리얼 5 : 텍스쳐 맵을 사용한다


튜토리얼 1 : 단일의 삼각형을 렌더링 한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

Visual Basic 로 Direct3D 를 사용하려면 , 우선, 어플리케이션 윈도우로부터 폼을 생성 한 후, DirectDraw® 와 Direct3D 관련 오브젝트를 생성 해, 초기화한다. 이러한 오브젝트는, 정의 끝난 메소드에 의해 조작한다. 또, 이러한 메소드를 사용해, 완성 신의 렌더링에 필요한 종속 오브젝트의 초기화도 실시한다.

이 튜토리얼에서는, 가능한 한 단순한 장면, 즉 단일의 삼각형을 표시하는 순서를 나타낸다. 메인 폼의 프로퍼티를 셋업 한 후, 샘플 Triangle 로, Direct3D 디바이스 오브젝트의 렌더링, 라이팅, 뷰포트, 머트리얼, 모델의 지오메트리 등, DirectDraw 와 Direct3D 의 초기화 방법을 자세하게 설명한다. 다음에, 삼각형을 프레임 마다 렌더링 하거나 Y 축을 중심으로 조금씩 회전하는 방법을 나타내는 서브 루틴을 나타낸다.

샘플 Triangle 에서는, 다음의 스텝을 사용해, DirectDraw 와 Direct3D 를 셋업 해, 장면을 렌더링 한다.

  • 스텝 1 : 폼을 생성 한다
  • 스텝 2 : 시스템 오브젝트를 초기화한다
  • 스텝 3 : 신을 초기화한다
  • 스텝 4 : 렌더링 루프를 실행한다
  • 스텝 5 : 슛다운을 실시한다

주 : 샘플 Triangle 의 Visual Basic 코드에서는, DirectDraw 및 Direct3D 의 초기화 코드와 어플리케이션 고유의 코드가 따로 따로 되어 있지만, 이것은 필수는 아니고, 이해하기 쉽게 하기 위해서 간 것이다.


스텝 1 : 폼을 생성 한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

Visual Basic 폼은, 어플리케이션 윈도우의 역할을 완수한다. 다음의 방법으로 폼의 프로퍼티를 설정한다.

BorderStyle     =   1  '실선
Caption         =   "Triangle"
ClientHeight    =   3195
ClientLeft      =   5415
ClientTop       =   3300
ClientWidth     =   3720
LinkTopic       =   "Form1"
MaxButton       =   0   'False
MinButton       =   0   'False
ScaleHeight     =   213
ScaleMode       =   0  '유저
ScaleWidth      =   254
StartUpPosition =   3  'Windows 의 디폴트

어플리케이션 윈도우를 표시하려면 ,Form_Load 프로시저에 다음의 행을 추가한다.

Me.Show

어플리케이션 윈도우의 준비가 종료 하면, DirectX 의 주요 오브젝트의 셋업을 시작 할 수가 있다. 이것이, 「스텝 2 : 시스템 오브젝트를 초기화한다」의 설명 내용이다.


스텝 2 : 시스템 오브젝트를 초기화한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

어플리케이션 윈도우를 생성 하면, 장면의 렌더링에 필요한 DirectX 주요 오브젝트의 초기화를 시작 할 수 있다. Direct3D 어플리케이션에 있어, 초기화란, DirectDraw, 렌더링 표면, 렌더링 디바이스, 뷰포트를 생성 및 구성하는 것을 의미한다.

샘플 Triangle 에서는,Form_Load 프로시저라는 이름의 어플리케이션 정의 서브 루틴 InitDDraw 로 시스템의 초기화를 실시한다. InitDDraw 서브 루틴으로 실행되는 스텝을 이하에 나타낸다.

  • 스텝 2.1 : DirectDraw 를 초기화한다
  • 스텝 2.2 : DirectDraw 표면을 셋업 한다
  • 스텝 2.3 : Direct3D 를 초기화한다
  • 스텝 2.4 : 뷰포트를 준비한다


스텝 3 : 신을 초기화한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

Direct3D 관련의 프라이머리 오브젝트인, DirectDraw 오브젝트, 렌더링 디바이스, 및 뷰포트를 생성 하면, 머트리얼의 준비, 트랜스 폼 행렬의 구성, 및 어플리케이션이 사용하는 지오메트리의 셋업을 실시해, 장면의 초기화를 시작 할 수 있다. 샘플 Triangle 에서는, 다음의 스텝을 실행해 장면을 초기화한다.

  • 스텝 3.1 : 머트리얼과 초기 라이팅 스테이트를 셋업 한다
  • 스텝 3.2 : 좌표 트랜스 폼 행렬을 준비, 설정한다
  • 스텝 3.3 : 지오메트리를 준비한다


스텝 4 : 렌더링 루프를 실행한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

어플리케이션 윈도우의 생성과 DirectX 오브젝트의 생성에 계속되어, 장면의 초기화를 종료 하면, 언제라도 장면의 렌더링을 실시할 수 있는 상태가 된다. 샘플 Triangle 의 렌더링 루프에서는, 어플리케이션 정의 서브 루틴 RenderScene 와 FrameMove 를 호출해 장면을 렌더링 한다.

Do While g_bRunning = True
CNT = CNT + 1
RenderScene
FrameMove (CNT / 360)

g_dx.GetWindowRect Me.hWnd, g_rcDest

j = g_ddsPrimary.Blt(g_rcDest, g_ddsBackBuffer, g_rcSrc, DDBLT_WAIT)
If j <> DD_OK Then
MsgBox "전송원직사각형을 목적지 표면에 카피할 수 없습니다. " & _
Chr$(13) & Hex(j)
End
End If
DoEvents
Loop

렌더링 루프는 무한하게 계속되는 것처럼 보이지만,Form_Unload 프로시저가 방아쇠 되면(자) 종료한다. 상세한 것에 대하여는, 「스텝 5 : 슛다운을 실시한다」를 참조할것.

장면을 렌더링 하는 렌더링 루프는, 다음의 스텝으로 나눌 수 있다.

  • 스텝 4.1 : 신을 갱신한다
  • 스텝 4.2 : 신을 렌더링 한다
  • 스텝 4.3 : 디스플레이를 갱신한다
  • 스텝 4.4 : DoEvents 를 호출한다


스텝 5 : 슛다운을 실시한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

샘플 Triangle 에서는, 이하에 나타내는 간단한 코드를 사용해 슛다운을 실시한다.

Private Sub Form_Unload(Cancel As Integer)
g_bRunning = False
End Sub

위의 코드에서는,Form_Unload 프로시저가 글로벌 변수 g_bRunning 를 false 로 설정해, 이것에 의해 렌더링 루프를 종료한다.


튜토리얼 2 : 깊이 버퍼를 추가한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

Direct3D 어플리케이션에서는, 장면의 오브젝트를 올바르게 표시하는데, 깊이 버퍼에 의존하는 것이 많다. 개념적인 개요에 대해서는, 「깊이 버퍼」를 참조할것. 깊이 버퍼를 사용하려면 , 지원 되고 있는 깊이 버퍼 포맷을 열거해, 깊이 버퍼 표면을 생성 해, 렌더링 타겟 표면에 깊이 버퍼 표면을 Attach 한 후, 렌더링 디바이스의 깊이 버퍼링을 유효하게 해야 한다.

샘플 ZBuffer 에서는, 다음의 스텝을 실행해, z 버퍼를 사용한다.

  • 스텝 1 : 깊이 버퍼 포맷을 열거한다
  • 스텝 2 : 깊이 버퍼를 생성 한다
  • 스텝 3 : 깊이 버퍼를 Attach 한다
  • 스텝 4 : 깊이 버퍼링을 유효하게 한다

z 버퍼는, 렌더링 되는 각 픽셀의 스테이트, 즉 렌더링 하는 픽셀이 표시되는 깊이를 보관 유지한다. 이것에 의해, 다른 픽셀상에서 픽셀을 렌더링 하는 경우, 이미 렌더링 되고 있는 픽셀의 뒤로 표시할지 어떨지를 결정할 수 있다.

주 : 샘플 ZBuffer 의 코드는, 거의, Triangle 의 코드와 동일하다. 이 튜토리얼에서는, Zbuffer 에 특유인 깊이 버퍼 코드만을 채택해 Direct3D 의 셋업, 렌더링, 슛다운, 어플리케이션에 의해 기동되는 이벤트의 처리에 대해서는 설명하지 않는 것으로 한다. 이러한 태스크의 상세한 것에 대하여는, 「튜토리얼 1 : 단일의 삼각형을 렌더링 한다」를 참조할것.

렌더링 디바이스에 따라서는, 깊이 버퍼를 메모리의 특정의 장소에 위치시킬 필요가 있기 (위해)때문에, 렌더링 디바이스를 생성 하기 전에, 깊이 버퍼 표면을 생성 해, 렌더링 타겟 표면에 Attach 할 필요가 있다.


스텝 1 : 깊이 버퍼 포맷을 열거한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

렌더링 디바이스가 깊이 버퍼를 지원 하고 있는 경우, 깊이 버퍼의 생성전에, 어떠한 깊이 버퍼 포맷을 지원 하고 있는지를 확인해 두지 않으면 안 된다. Direct3D7.GetEnumZBufferFormats 메소드를 호출해, 디바이스가 지원 하고 있는 깊이 버퍼 포맷을 열거한다. 샘플 ZBuffer 에서는, 다음의 코드를 사용해, 깊이 버퍼 포맷을 열거하고 있다.

'백 버퍼의 생성 후, Direct3D 디바이스를 생성 하기 전에,
' z 버퍼를 생성 한다. 주 ：z 버퍼의 생성전에, 어플리케이션이,
' D3DPRASTERCAPS_ZBUFFERLESSHSR 플래그로 디바이스 능력을 체크하는 경우가 있다. 이 플래그는,
' z 버퍼없이, HSR (hidden-surface-removal)를 실시할 수가 있는 하드웨어에 대해서 실로 된다.
'그러한 디바이스에 대해서는, z 버퍼를 생성 할 필요는 없다.
    '
Dim ddpfZBuffer As DDPIXELFORMAT
Dim d3dEnumPFs As Direct3DEnumPixelFormats

Set g_d3d = g_dd.GetDirect3D
Set d3dEnumPFs = g_d3d.GetEnumZBufferFormats("IID_IDirect3DRGBDevice")

GetEnumZBufferFormats 메소드는, 포맷을 열거하는 대상이 되는 디바이스의 글로벌 유니크 식별자 (GUID)를 받아들인다. ZBuffer 어플리케이션에서는, GUID 를 코드중에 기입해 사용하고 있지만, 실제의 어플리케이션에서는, 렌더링 디바이스의 GUID 를 확인하는 테스트 메카니즘, IID_IDirect3DRGBDevice 또는 IID_IDirect3DHALDevice 의 어느쪽이든을 이행 한다.

여기서, 디바이스의 포맷이 열거되므로, 지원 되는 깊이 버퍼 포맷을 확인할 수 있다.

Dim I As Long

For I = 1 To d3dEnumPFs.GetCount()
Call d3dEnumPFs.GetItem(I, ddpfZBuffer)
If ddpfZBuffer.lFlags = DDPF_ZBUFFER Then
Exit For
End If
Next I

Direct3DEnumPixelFormats.GetItem 를 호출하면, 2 번째의 인수에 의해, 깊이 버퍼의 픽셀 포맷을 나타내는 DDPIXELFORMAT 형을 건네준다. 멤버 IFlags 에는, 깊이 버퍼 비트를 포함한 임의의 픽셀 포맷에 대해서 DDPF_ZBUFFER 가 저장 된다. 최초의 인수에 의해,GetItem 는 열거된 포맷에 인덱스를 생성 한다. 적절한 포맷이 발견되었을 경우,GetItem 는 그 픽셀 포맷을 ddpfZBuffer 파라미터,DDPIXELFORMAT 형에 보존해, 루프가 종료한다.

이 튜토리얼에서는, 이해하기 쉽게하기 위해(때문에), 가장 일반적인 타입의 깊이 버퍼인 z 버퍼만을 사용하고 있다. 시스템이 열거하는 것 외의 포맷 (DDPF_STENCILBUFFER 등)은, 모두 무시한다. 어플리케이션은, z 버퍼의 비트 깊이 (8, 16, 24, 32 비트)를 체크해, 비트 깊이에 근거한 선택을 실시할 수도 있다.

깊이 버퍼의 포맷을 결정하면(자), 그 포맷을 사용하는 DirectDrawSurface 를 생성 할 수가 있다. 이것이, 「스텝 2 : 깊이 버퍼를 생성 한다」의 설명 내용이다.


스텝 2 : 깊이 버퍼를 생성 한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

여기서, 깊이 버퍼 포맷의 선택을 종료했으므로, 깊이 버퍼가 되는 DirectDrawSurface 오브젝트를 생성 할 수가 있다. 표면의 픽셀 포맷은, 열거에 의해 결정된 것이지만, 표면의 치수는, Attach 되는 렌더링 타겟 표면과 동일하게 해야 한다. 샘플 ZBuffer 에서는, 이 태스크에 대해서 다음의 코드를 사용한다.

g_ddsd.lFlags = DDSD_CAPS Or DDSD_WIDTH Or DDSD_HEIGHT Or DDSD_PIXELFORMAT
    g_ddsd.ddsCaps.lCaps = DDSCAPS_ZBUFFER
g_ddsd.lWidth = g_rcDest.Right - g_rcDest.Left
g_ddsd.lHeight = g_rcDest.Bottom - g_rcDest.Top
g_ddsd.ddpfPixelFormat = ddpfZBuffer

위의 코드는, 설정 끝난 글로벌 변수로부터 계산된 렌더링 타겟 표면의 치수를 사용해, 깊이 버퍼용의 DDSURFACEDESC2 형을 준비해 있는 것만으로 있다. 최종적으로는, 전의 스텝의스텝 1 : 깊이 버퍼 포맷을 열거한다」로 취득한 픽셀 포맷 정보가, 표면 기술에 카피된다.

g_ddsd.ddpfPixelFormat = ddpfZBuffer

주 : 하드웨어 디바이스는, 깊이 버퍼를, 메모리중의 위치에 관계없이 사용할 수가 있다. 하드웨어 디바이스의 사용시에는, 표면 능력 플래그 DDSCAPS_VIDEOMEMORY 및 DDSCAPS_SYSTEMMEMORY 를 생략 해, 버퍼의 최적 위치를 디바이스로 결정시키는 것이 최선이다. 그러나, 소프트웨어 디바이스는, 깊이 버퍼가 시스템 메모리에 존재하지 않으면 생성 할 수가 없다. 샘플 ZBuffer 의 다음의 코드에서는, DDSCAPS_SYSTEMMEMORY 플래그를 세트 하고 있지만, 실제의 어플리케이션에서는, 표면 메모리가 시스템 메모리와 디스플레이 메모리의 어느 쪽으로 존재하는지를 확인하는, 간단한 검색 메카니즘을 이행 할 필요가 있다.

'표면이 디스플레이 메모리에 존재하는 경우, DDSCAPS_VIDEOMEMORY 와 지정한다.
'상세한 것에 대하여는, SDK 의 문서를 참조할것.
g_ddsd.ddsCaps.lCaps = g_ddsd.ddsCaps.lCaps Or DDSCAPS_SYSTEMMEMORY

표면 기술의 준비를 할 수 있으면(자), 코드는 DirectDraw7.CreateSurface 메소드를 호출해, 새로운 깊이 버퍼 표면을 생성 한다.

Set g_ddsZBuffer = g_dd.CreateSurface(g_ddsd)

생성 된 깊이 버퍼는, 「스텝 3 : 깊이 버퍼를 Attach 한다」로 설명하도록(듯이), 렌더링 타겟으로서 사용되는 표면에 Attach 할 수가 있다.


스텝 3 : 깊이 버퍼를 Attach 한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

깊이 버퍼를 생성 하면(자), 렌더링 타겟으로서 사용되는 표면에 Attach 할 필요가 있다. 이것은, 렌더링 타겟 표면의 DirectDrawSurface7.AddAttachedSurface 메소드를 호출해 실시한다. 샘플 ZBuffer 에서는, 다음의 코드를 사용해 이 처리를 실행한다.

'백 버퍼에 Z 버퍼를 Attach 한다.
g_ddsBackBuffer.AddAttachedSurface g_ddsZBuffer

깊이 버퍼를 렌더링 타겟 표면에 Attach 하면, 깊이 버퍼링이 유효하게 되어 있는 경우, 시스템은 항상, 이 깊이 버퍼를 자동적으로 사용한다. 이것에 대해서는, 「스텝 4 : 깊이 버퍼링을 유효하게 한다」로 설명한다.


스텝 4 : 깊이 버퍼링을 유효하게 한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

깊이 버퍼를 렌더링 타겟 표면에 Attach 하면, 렌더링 타겟으로부터 렌더링 디바이스를 생성 할 수가 있다.

깊이 버퍼를 사용하는 어플리케이션에서는, 뷰포트와 깊이 버퍼의 양쪽 모두를 클리어 할 필요가 있다. 깊이 버퍼를 클리어 하려면 ,Direct3DDevice7.Clear 메소드로 D3DCLEAR_ZBUFFER 플래그를 지정한다.

g_d3dDevice.Clear 1, g_d3drcViewport(), D3DCLEAR_TARGET Or D3DCLEAR_ZBUFFER, &HFF, 1, 0

렌더링 디바이스가 준비되면(자), 그 디바이스의 D3DREMDERSTATE_ZENABLE 렌더링 스테이트를 설정해, 깊이 버퍼링을 유효하게 할 수가 있다. CONST_D3DZBUFFERTYPE 열거형에는, 깊이 버퍼의 렌더링 스테이트를 설정하는 멤버가 포함되어 있다. 멤버 D3DZB_TRUE (또는 TRUE)에 의해, z 버퍼링을 유효하게 한다. 샘플 Zbuffer 는, 어플리케이션 정의 서브 루틴 RenderScene 에서의 장면의 렌더링중에, z 버퍼링을 유효하게 하고 있다. 다음의 코드는, RenderScene 로부터의 해당 부분의 발췌이다.

g_d3dDevice.SetRenderState D3DRENDERSTATE_ZENABLE, D3DZB_TRUE

이 튜토리얼에서는, 프레임 단위에 깊이 버퍼링을 유효하게 하고 있지만, 이것은 필수는 아니다. 실제의 어플리케이션에서는, 장면의 초기화중에 D3DRENDERSTATE_ZENABLE 렌더링 스테이트를 설정해 두어, 깊이 버퍼링을 무효로 하거나 깊이 버퍼링의 다른 타입을 선택할 경우에만 변경하는 것이 보통이다.

주 : D3DZBUFFERTYPE 열거형은, 준거 하드웨어상에서의 w 베이스의 깊이 조합을 유효하게 하는 D3DZB_USEW 값을 포함하고 있다. 상세한 것에 대하여는, 「깊이 버퍼」를 참조할것.


튜토리얼 3 : 다양한 프리미티브 스타일을 사용한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

이 튜토리얼에서는, Direct3D Visual Basic 에 의해 제공되는, 다양한 드로잉(Drawing) 프리미티브 호출을 사용해 다각형을 렌더링 하는 방법을 나타낸다. 이 튜토리얼의 프리미티브는, 닫은 다각형의, 적어도 3 버텍스로써 식별되는 3D 오브젝트이다. 이 튜토리얼에서는, 샘플 DrawPrims 를 사용한다.

이 튜토리얼에서는 주로, 일련의 프리미티브 (벽세그먼트(segment), 원추, 입방체)의 지오메트리를 준비하는 방법, 시점을 회전하는 방법, 및 행렬 연결을 사용해 3D 트랜스 폼 (입방체의 평행이동, 회전, 스케일)을 실행하는 방법에 대해 설명한다.

  • 스텝 1 : 신 지오메트리를 초기화한다
  • 스텝 2 : 신을 렌더링, 표시한다

3D 프리미티브의 상세한 것에 대하여는, 「3D 프리미티브」를 참조할것.

주 : 샘플 DrawPrims 의 코드는, 샘플 Triangle 의 코드에 유사하고 있다. 이 튜토리얼에서는, 지오메트리의 준비와 샘플 DrawPrim 에 특유인 렌더링 코드만을 채택해 Direct3d 의 셋업, 슛다운, 시스템 이벤트의 처리에 대해서는 설명하지 않는 것으로 한다. 이러한 태스크에 대해서는, 「튜토리얼 1 : 단일의 삼각형을 렌더링 한다」를 참조할것.

이 튜토리얼에서는, 깊이 버퍼를 사용해 장면의 깊이 정보를 보존한다. 깊이 버퍼를 사용하려면 , 지원 되고 있는 깊이 버퍼 포맷을 열거해, 깊이 버퍼 표면을 생성 해, 렌더링 타겟 표면에 깊이 버퍼 표면을 Attach 한 후, 렌더링 디바이스의 깊이 버퍼링을 유효하게 해야 한다. 이러한 태스크에 대해서는, 「튜토리얼 2 : 깊이 버퍼를 추가한다」를 참조할것.


스텝 1 : 신 지오메트리를 초기화한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

이 튜토리얼에서는, 어플리케이션 정의 서브 루틴 InitGeometry 로 프리미티브의 지오메트리를 준비한다. InitGeometry 는, 각 오브젝트의 버텍스를 정의해, 각 프리미티브의 버텍스 정보를 글로벌하게 정의된 데이터 구조체 로 유지한다. 이 버텍스 정보는, 렌더링시에DrawPrimitive 메소드 에 의해 사용된다.

기술적으로는, 이 시점에서 지오메트리의 셋업을 실시할 필요는 없다. 지오메트리의 셋업은, 메소드의 호출전에 수시 실행할 수 있다.

  • 스텝 1.1 : 벽세그먼트(segment)를 준비한다
  • 스텝 1.2 : 원추를 준비한다
  • 스텝 1.3 : 입방체를 준비한다

프리미티브의 종류의 상세한 것에 대하여는, 「프리미티브의 종류」를 참조할것.

Direct3D 에서의 버텍스의 지정에 대해서는, 「버텍스 포맷」을 참조할것.

주 : 프리미티브의 지오메트리를 준비한 순서는, 장면내의 오브젝트의 레이아웃에는 영향을 주지 않는다.


스텝 2 : 신을 렌더링, 표시한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

장면내의 오브젝트를 적절히 표시 및 조작하려면 , 장면의 뷰를 갱신해, 필요한 트랜스 폼을 실시해, 완성한 장면을 렌더링 할 필요가 있다. 이러한 태스크에 대해서는, 다음의 스텝에서 설명한다.

  • 스텝 2.1 : 신을 갱신한다
  • 스텝 2.2 : 3D 트랜스 폼을 실행한다
  • 스텝 2.3 : 신을 렌더링 한다

프리미티브의 렌더링에 대해서는, 「프리미티브의 렌더링」을 참조할것.


튜토리얼 4 : 디바이스 열거를 사용한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

디바이스 열거를 사용 하면, 하드웨어가 지원 하는 Direct3D 디바이스를 조회할 수가 있다. 이것에 의해, 특정의 하드웨어 구성을 사용하는 어플리케이션을 생성 하거나 유저의 하드웨어로 지원 되는 구성을 선택할 수가 있다. 이 튜토리얼에서는, 시스템의 드라이버, 디스플레이 모드, 및 디바이스를 열거해, 각 디바이스로 지원 되는 디스플레이 모드의 리스트를 생성 한다.

기본적으로, 디바이스 열거는 다음의 2 개의 스텝, (1) 디바이스 열거의 시작과 종료, (2) 열거된 디바이스의 선택, 으로 나눌 수가 있다.

이 튜토리얼에서는, 이러한 스텝이 이하의 스텝에 대응한다.

  • 스텝 1 : 디바이스 열거를 시작, 종료한다
  • 스텝 2 : 열거된 디바이스의 선택

Direct3D 디바이스의 상세한 것에 대하여는, 「Direct3D 디바이스」를 참조할것.

디바이스의 열거에 대해서는, 「Direct3D 디바이스의 열거」를 참조할것.

주 : 샘플 Enumeration 의 코드는, 샘플 Triangle 의 코드에 유사하고 있다. 이 튜토리얼에서는, 샘플 Enumeration 에 특유인 디바이스 열거 코드만을 채택해 Direct3D 의 셋업, 장면 지오메트리의 준비, 슛다운, 시스템 이벤트의 처리에 대해서는 설명하지 않는 것으로 한다. 이러한 태스크에 대해서는, 「튜토리얼 1 : 단일의 삼각형을 렌더링 한다」를 참조할것.

이 튜토리얼에서는, 깊이 버퍼를 사용해 장면의 깊이 정보를 보존한다. 깊이 버퍼를 사용하려면 , 지원 되고 있는 깊이 버퍼 포맷을 열거해, 깊이 버퍼 표면을 생성 해, 렌더링 타겟 표면에 깊이 버퍼 표면을 Attach 한 후, 렌더링 디바이스의 깊이 버퍼링을 유효하게 해야 한다. 이러한 태스크에 대해서는, 「튜토리얼 2 : 깊이 버퍼를 추가한다」를 참조할것.

이 튜토리얼에서는, 일련의 원추 프리미티브를 드로잉(Drawing) 한다. 프리미티브의 드로잉(Drawing)에 대해서는,튜토리얼 3 : 다양한 프리미티브 스타일을 사용한다」를 참조할것.


스텝 1 : 디바이스 열거를 시작, 종료한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

Visual Basic 어플리케이션에서는, 열거 클래스에의 참조를 취득하는 것에 의해 열거를 시작 한다. 이 튜토리얼에서는, 다음의 열거 클래스에의 참조를 선언할 필요가 있다.

  • DirectDrawEnum
  • DirectDrawEnumModes
  • Direct3DEnumDevices

어플리케이션의 디바이스 열거 처리는, 이하의 스텝으로 나눌 수가 있다.

  • 스텝 1.1 : 드라이버 정보를 열거한다
  • 스텝 1.2 : 디스플레이 모드 정보를 열거한다
  • 스텝 1.3 : 디바이스 정보를 열거한다

디바이스 열거를 사용하는 어플리케이션의 최초의 스텝은, DirectDraw 드라이버에의 참조의 취득이다. 샘플 Enumeration 에서는, 다음의 어플리케이션 정의 서브 루틴 호출을 사용해, DirectDraw 로 사용할 수 있는 드라이버를 열거한다.

'드라이버 정보를 취득한다.
EnumDriver

드라이버의 열거에 대해서는, 「스텝 1.1 :드라이버 정보를 열거한다」로 설명한다.

디바이스 열거의 시작에 대해서는, 「디바이스 열거의 시작」을 참조할것.


스텝 2 : 열거된 디바이스의 선택

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

보통, 다음의 스텝에 의해 열거된 디바이스의 선택.

  • 스텝 2.1 : 디바이스를 취득한다
  • 스텝 2.2 : 디바이스를 테스트한다

샘플 Enumeration 에서는, 다음의 어플리케이션 정의 서브 루틴 호출을 사용해, 열거된 디바이스를 선택해, 그 디바이스로 지원 되고 있는 디스플레이 모드의 리스트를 생성 한다.

'열거된 디바이스를 선택해, 그 디바이스로
'지원 되는 디스플레이 모드의 리스트를 생성 한다.
SelectDisplayModes

열거된 디바이스의 취득에 대해서는,스텝 2.1 : 디바이스를 취득한다」로 설명한다.

열거된 디바이스의 선택에 대해서는, 「열거된 디바이스의 선택」을 참조할것.


튜토리얼 5 : 텍스쳐 맵을 사용한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

이 튜토리얼에서는, 텍스쳐를 사용해 간단한 3D 신을 드로잉(Drawing) 하는 방법에 대해 설명한다. 기본적으로, Direct3D 텍스쳐는 픽셀 컬러의 비트 맵이므로, Direct3D 원시적으로 비트 맵 이미지를 적용할 수가 있다. 텍스쳐는 간단하게 사용할 수 있어 3D 오브젝트의 지오메트리를 변경하는 일 없이, 3D 신을 보다 리얼하게 보이게 할 수가 있다. 이와 같이, 텍스쳐를 사용 하면, 프리미티브의 컬러 패턴과 일루젼, 엉성함이나 매끄러움, 투과성을 강화할 수 있다. 이 튜토리얼에서는, 파일 베이스의 비트 맵으로부터 텍스쳐를 생성 하는 방법과 텍스쳐를 적용한 입방체의 프리미티브를 렌더링 하는 방법을 중심으로 설명한다.

Direct3D for Visual Basic 에서는, 텍스쳐 핸들을 사용하지 않기 때문에 주의한다. 그 대신에, 텍스쳐 표면의 생성시에 텍스쳐 표면 오브젝트에의 참조를 취득한다.

3D 신으로 원시적으로 텍스쳐를 추가하려면 , 다음의 스텝을 실행한다.

  • 스텝 1 : 텍스쳐를 적용한 표면을 생성 한다
  • 스텝 2 : 텍스쳐를 적용한 프리미티브를 렌더링 한다

Direct3D 에서는, 광범위한 텍스쳐링 기능을 지원 하고 있으므로, 개발자는 고도의 텍스쳐링 기법을 용이하게 이용할 수가 있다. 텍스쳐의 사용법과 Direct3D 에서의 최적화에 대해서는, 「텍스쳐」를 참조할것.

주 : 샘플 Texture 의 코드는, 샘플 Triangle 의 코드에 유사하고 있다. 이 튜토리얼에서는, 샘플 Texture 에 특유인 코드만을 채택해 Direct3D 의 셋업, 장면 지오메트리의 준비, 슛다운, 시스템 이벤트의 처리에 대해서는 설명하지 않는 것으로 한다. 이러한 태스크에 대해서는,튜토리얼 1 : 단일의 삼각형을 렌더링 한다」를 참조할것.

샘플 Texture 에서는, 입방체의 프리미티브를 드로잉(Drawing) 한다. 프리미티브의 드로잉(Drawing) 방법에 대해서는, 「튜토리얼 3 : 다양한 프리미티브 스타일을 사용한다」를 참조할것.

샘플 Texture 에서는, 텍스쳐 포맷의 열거를 사용한다. 열거의 원리와 방법에 대해서는, 「튜토리얼 4 : 디바이스 열거를 사용한다」를 참조할것.


스텝 1 : 텍스쳐를 적용한 표면을 생성 한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

Direct3D for Visual Basic 에서는, 텍스쳐의 생성과 관리 태스크가 큰폭으로 단순화 되고 있다. 3D 신으로 시스템의 관리하의 텍스쳐를 준비, 생성, 및 이행 하려면 , 다음의 스텝을 실행한다.

  • 스텝 1.1 : 텍스쳐 좌표를 설정한다
  • 스텝 1.2 : 텍스쳐 표면을 준비한다
  • 스텝 1.3 : 텍스쳐 포맷을 열거한다
  • 스텝 1.4 : 텍스쳐에 신규 표면을 생성 한다

원시적으로 텍스쳐를 생성 하기 전에, 프리미티브의 버텍스와 그 텍스쳐 좌표를 정의할 필요가 있다. 이 태스크에 대해서는, 「스텝 1.1 : 텍스쳐 좌표를 설정한다」로 설명한다.


스텝 2 : 텍스쳐를 적용한 프리미티브를 렌더링 한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

텍스쳐를 적용한 프리미티브와 적용하고 있지 않는 프리미티브를 렌더링 할 때의 상위는, 텍스쳐를 적용한 프리미티브는, 렌더링시에 텍스쳐를 설정해야 하는 것 뿐이다.

샘플 Texture 의 다음의 코드에서는, 텍스쳐 표면 g_ddsTexture1: 를 사용해, 입방체의 전면과 뒷면을 드로잉(Drawing) 한다.

g_d3dDevice.SetTexture 0, g_ddsTexture1
Call g_d3dDevice.DrawPrimitive(D3DPT_TRIANGLESTRIP, D3DFVF_VERTEX, g_vCube(0), _
4, D3DDP_DEFAULT)
Call g_d3dDevice.DrawPrimitive(D3DPT_TRIANGLESTRIP, D3DFVF_VERTEX, g_vCube(4), _
4, D3DDP_DEFAULT)

입방체의 표면과 저면, 및 좌면과 우면에도, 각각 g_ddsTexture2 과 g_ddsTexture3 를 설정해, 같은 순서를 실행할 필요가 있다. 이 순서에 대해서는, SDK 의 샘플 Texture 코드를 참조할것.

Direct3DDevice7.SetTexture 메소드는, 디바이스의 소정의 스테이지에 텍스쳐를 할당한다. 이 튜토리얼에서는, 멀티 텍스쳐 블렌딩을 사용하지 않기 때문에, 스테이지 식별자가 되는 최초의 파라미터 SetTexture 가 0 이 되어 있다. 2 번째의 파라미터는, 텍스쳐로서 설정되는 DirectDrawSurface7 오브젝트를 나타낸다.

텍스쳐 표면을 사용한 렌더링에 대해서는, 「텍스쳐 표면을 사용한 렌더링」을 참조할것.

멀티 텍스쳐의 블렌드에 대해서는, 「멀티 텍스쳐 블렌딩」을 참조할것.


Direct3D 직접 모드 레퍼런스

여기에서는, C/C++ 및 Microsoft Visual Basic® 프로그램 언어로 Microsoft® Direct3D® 직접 모드가 제공하는 어플리케이션 프로그래밍 인터페이스 (API) 요소의 레퍼런스 정보를 기술한다. 레퍼런스 정보는 이하의 언어별로 구성된다.

  • Direct3D 직접 모드 C/C++ 레퍼런스
  • Direct3D 직접 모드 Visual Basic 레퍼런스


Direct3D 직접 모드 C/C++ 레퍼런스

여기에서는, Direct3D 직접 모드가 제공하는 API 요소의 레퍼런스 정보를 기술한다. 레퍼런스 정보는 이하의 카테고리로 분류된다.

  • 인터페이스
  • D3D_OVERLOADS
  • 콜백 함수
  • 매크로
  • 구조체
  • 열거형
  • 그 외의 형태
  • 유연한 버텍스 포맷 플래그
  • 반환값


인터페이스

여기에서는, Direct3D 직접 모드가 제공하는 COM 인터페이스의 레퍼런스 정보를 기술한다. Direct3D 직접 모드로 사용되는 주된 인터페이스는, 이하대로이다.

  • IDirect3D7
  • IDirect3DDevice7
  • IDirect3DVertexBuffer7

주 : Direct3D 에서는, 텍스쳐용의 개별의 인터페이스는 불필요하다. 현재, Direct3D 의 모든 텍스쳐 관련 메소드는, 표면이 텍스쳐 능력 (DDSCAPS_TEXTURE)을 사용해 생성 되고 있으면 IDirectDrawSurface7 인터페이스에의 포인터를 받게 되어 있다.

실행 버퍼를 필요로 하는 어플리케이션에서는, DirectX 의 구릴리스로 제공되고 있던 인터페이스를 사용해야 한다.

DirectX 의 종래의 릴리스로 제공되고 있던 그루터기 메소드 가운데 일부는, 현재 제공되어 있지 않다. 상세한 것에 대하여는, 「이행되어 있지 않은 메소드」를 참조할것.

새로운 IDirect3DDevice7 인터페이스에는,IDirect3DLight,IDirect3DMaterial3, 및 IDirect3DViewport3 인터페이스에 대신해 사용되는 메소드가 포함된다. 상세한 것에 대하여는, 「폐지된 인터페이스」를 참조할것. 이러한 인터페이스에 대한 문서는, DirectX 의 구릴리스로부터 입수할 수 있다.


IDirect3D7

어플리케이션은,IDirect3D7 인터페이스의 메소드를 사용해, Direct3D 오브젝트를 생성 해, 오브젝트의 환경을 셋업 한다. 여기에서는, IDirect3D7 인터페이스의 메소드에 대한 레퍼런스 정보를 기술한다. 개요에 대해서는, 「Direct3D 인터페이스」를 참조할것.

IDirect3D7 인터페이스는, DirectDraw 오브젝트로부터 QueryInterface 메소드를 호출하는 것으로 얻을 수 있다.

IDirect3D7 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

생성 | CreateDevice
 | CreateVertexBuffer
열거 | EnumDevices
 | EnumZBufferFormats
그 외 | EvictManagedTextures

IDirect3D7 인터페이스는,IDirect3D3 인터페이스를 간략화한 것이어, 디바이스 및 버텍스 버퍼를 생성 하는 경우를 제외해서는, 오브젝트 생성용 메소드가 필요없다. IDirect3D3 인터페이스와는 달라,IDirect3D7 에는 IDirect3D7::CreateLight,IDirect3D7::CreateMaterial, 및 IDirect3D7::CreateViewport 메소드가 존재하지 않는다. 이러한 메소드의 기능성은, 현재는 IDirect3DDevice7 인터페이스에 포함되어 있다.

모든 COM 인터페이스와 같이,IDirect3D7 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3D7,LPDIRECT3D3,LPDIRECT3D2, 및 LPDIRECT3D 형은,IDirect3D7,IDirect3D7,IDirect3D2, 및 IDirect3D 인터페이스에의 포인터로서 정의된다.

typedef struct IDirect3D    *LPDIRECT3D;
typedef struct IDirect3D2   *LPDIRECT3D2;
typedef struct IDirect3D3   *LPDIRECT3D3;
typedef struct IDirect3D7   *LPDIRECT3D7;

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

Direct3D 에의 액세스,Direct3D 와 DirectDraw


IDirect3D7::CreateDevice

IDirect3D7::CreateDevice 메소드는, DrawPrimitive 메소드에 사용하기 위해서, Direct3D 디바이스를 생성한다.

HRESULT CreateDevice(
  REFCLSID rclsid,
  LPDIRECTDRAWSURFACE7 lpDDS,
  LPDIRECT3DDEVICE7 *  lplpD3DDevice,
);

파라미터

rclsid
새로운 디바이스에 대한 클래스 식별자. 이 값은, IID_IDirect3DTnLHalDevice, IID_IDirect3DHALDevice, IID_IDirect3DMMXDivice, 또는 IID_IDirect3DRGBDevice 이다. 램프 에뮬레이션 디바이스용의 IID_IDirect3DRampDevice 는,IDirect3D2 이후의 인터페이스에서는 지원 되지 않는다. 램프 에뮬레이션을 이용할 때는, 종래의 IDirect3D2 인터페이스를 이용하는 것.
lpDDS
디바이스의 렌더링 타겟이 되는 DirectDrawSurface 오브젝트의 IDirectDrawSurface7 인터페이스의 주소. DDSCAPS_3DDEVICE 능력을 이용해 표면은 3-D 디바이스로서 생성되었다.
lplpD3DDevice
메소드가 돌아갔을 때에, 새로운 IDirect3DDevice7 인터페이스를 포인트 하는 포인터의 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면 에러를 돌려준다. 이 메소드는, 인수의 1 개가 무효인 경우에는,DDERR_INVALIDPARAMS 를 돌려준다.

주의

특정의 Direct3D 오브젝트에 의해 생성되는 렌더링 디바이스는, 같은 물리 리소스를 공유한다. 어플리케이션으로 단일의 Direct3D 오브젝트로부터 복수의 렌더링 디바이스를 생성 할 수 있는 경우에서도, 이러한 디바이스는 같은 하드웨어를 공유하기 위해(때문에), 퍼포먼스가 현저하게 저하한다.

종래의 IDirect3D3 인터페이스에서는, 이 메소드는 IDirectDrawSurface4 및 IDirect3DDevice3 인터페이스에의 포인터를 받았다.

IDirect3D7::CreateDevice 를 호출하면, DirectDraw 표면 오브젝트와는 별개의 디바이스 오브젝트를 생성 할 수 있다. 이 디바이스는, DirectDraw 표면을 렌더링 타겟으로서 사용한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7 ,Direct3D 디바이스의 생성,Direct3D 디바이스


IDirect3D7::CreateVertexBuffer

IDirect3D7::CreateVertexBuffer 메소드는, 버텍스 버퍼 오브젝트를 생성 한다.

HRESULT CreateVertexBuffer(
  LPD3DVERTEXBUFFERDESC    lpVBDesc,
  LPDIRECT3DVERTEXBUFFER7* lplpD3DVertexBuffer,
  DWORD dwFlags
);

파라미터

lpVBDesc
버텍스 버퍼가 받는 버텍스의 포맷 및 개수를 기술하는 D3DVERTEXBUFFERDESC 구조체의 주소.
lplpD3DVertexBuffer
새로운 버텍스 버퍼의 IDirect3DVertexBuffer7 인터페이스에의 포인터를 받는 변수의 주소.
dwFlags
이 메소드를 위해서(때문에) 현재 정의되고 있는 플래그는 없다. 이 파라미터에는 0 을 설정한다.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

CLASS_E_NOAGGREGATION
D3DERR_INVALIDVERTEXFORMAT
D3DERR_VBUF_CREATE_FAILED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

주의

이 메소드는,IDirect3D3 인터페이스와 함께 도입되었다. IDirect3D3 의 일부로서 이 메소드는 종래의 IDirect3DVertexBuffer 인터페이스에의 포인터 및 dwFlags 파라미터로 지정되는 플래그를 받았다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DVertexBuffer7 ,버텍스 버퍼


IDirect3D7::EnumDevices

IDirect3D7::EnumDevices 메소드는, 시스템에 인스톨 되고 있는 Direct3D 디바이스 드라이버를 모두 열거한다.

HRESULT EnumDevices(
  LPD3DENUMDEVICESCALLBACK7 lpEnumDevicesCallback,
  LPVOID lpUserArg
);

파라미터

lpEnumDevicesCallback
조건이 일치할 때마다 열거 프로시저가 호출하는 D3DEnumDevicesCallback7 콜백 함수의 주소.
lpUserArg
콜백 함수에게 건네지는 어플리케이션 정의 데이터의 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

IDirect3D3 인터페이스에서는, 이 메소드는 D3DEnumDevicesCallback 함수에의 포인터를 받았다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.


IDirect3D7::EnumZBufferFormats

IDirect3D7::EnumZBufferFormats 메소드는, 지정된 디바이스가 지원 하고 있는 깊이 버퍼 포맷을 열거한다.

HRESULT EnumZBufferFormats(
  REFCLSID riidDevice,
  LPD3DENUMPIXELFORMATSCALLBACK lpEnumCallback,
  LPVOID   lpContext
);

파라미터

riidDevice
깊이 버퍼 포맷이 열거되는 디바이스의 글로벌 유니크 식별자에의 참조.
lpEnumCallback
지원 되고 있는 깊이 버퍼 포맷 마다 불려 가는 D3DEnumPixelFormatsCallback 콜백 함수의 주소.
lpContext
콜백 함수에게 건네지는 어플리케이션 정의 데이터.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.


IDirect3D7::EvictManagedTextures

IDirect3D7::EvictManagedTextures 메소드는, 로컬 또는 비로컬 비디오 메모리로부터 관리하의 텍스쳐를 모두 삭제한다.

HRESULT EvictManagedTextures();

파라미터

없음.

반환값

D3D_OK 를 돌려준다.

주의

이 메소드를 사용 하면, Direct3D 는, DDSCAPS2_TEXTUREMANAGE 또는 DDSCAPS2_D3DTEXTUREMANAGE 플래그로 생성 된 텍스쳐 표면을, 로컬 또는 비로컬 비디오 메모리로부터 삭제한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

자동 텍스쳐 관리


IDirect3DDevice7

IDirect3DDevice7 인터페이스에는, 어플리케이션으로 DrawPrimitive 베이스의 렌더링을 가능하게 하는 메소드가 있다. 이 점에 대해서는,IDirect3DDevice 인터페이스의 경우, 어플리케이션이 실행 버퍼를 사용해 렌더링 하는 것과 대조적이다. IDirect3D7::CreateDevice 메소드를 호출하는 것으로, Direct3DDevice 오브젝트를 생성 해, 이 인터페이스에의 포인터를 취득할 수 있다.

개요에 대해서는, 「Direct3D 디바이스」 및 「DrawPrimitive 메소드」를 참조할것.

IDirect3DDevice7 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

정보 | GetCaps
 | GetDirect3D
 | GetInfo
디바이스 스테이트 | ApplyStateBlock
 | BeginStateBlock
 | CaptureStateBlock
 | CreateStateBlock
 | DeleteStateBlock
 | EndStateBlock
 | GetClipStatus
 | GetRenderState
 | GetRenderTarget
 | GetStateData
 | GetTransform
 | SetClipStatus
 | SetRenderState
 | SetRenderTarget
 | SetStateData
 | SetTransform
라이팅과 머트리얼 | GetLight
 | GetLightEnable
 | GetMaterial
 | LightEnable
 | SetLight
 | SetMaterial
그 외 | ComputeSphereVisibility
 | MultiplyTransform
렌더링 | DrawIndexedPrimitive
 | DrawIndexedPrimitiveStrided
 | DrawIndexedPrimitiveVB
 | DrawPrimitive
 | DrawPrimitiveStrided
 | DrawPrimitiveVB
장면 | BeginScene
 | EndScene
텍스쳐 | EnumTextureFormats
 | GetTexture
 | GetTextureStageState
 | Load
 | PreLoad
 | SetTexture
 | SetTextureStageState
 | ValidateDevice
유저 정의 클립면 | GetClipPlane
 | SetClipPlane
뷰포트 | Clear
 | GetViewport
 | SetViewport

모든 COM 인터페이스와 같이,IDirect3DDevice7 인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

이 인터페이스는, 디바이스 스테이트 블록용의 메소드를 더하는 것으로 IDirect3DDevice3 인터페이스를 확장하고 있다. 디바이스 스테이트 블록에 의해, 어플리케이션이 요구하는 공통된 일련의 스테이트 변화를 재빠르게 실행할 수 있다. 또,IDirect3DDevice7 인터페이스에는, 디바이스내의 뷰포트, 라이트, 및 머트리얼을 조작하는 메소드가 있어, 이러한 메소드가 IDirect3DViewport3,IDirect3DMaterial3, 및 IDirect3DLight 인터페이스에 대신해 사용된다.

이 인터페이스와 이전의 IDirect3DDevice3 인터페이스로 공통되는 많은 메소드에서는, 받는 파라미터에 약간의 차이가 있다. IDirect3DDevice3 인터페이스 메소드는 IDirectDrawSuface3 인터페이스에의 포인터를 파라미터로서 받아,IDirect3DDevice7 인터페이스 메소드는 IDirectDrawSurface7 인터페이스에의 포인터를 받는다. 지금까지 IDirect3DVertexBuffer 또는 IDirect3DTexture2 인터페이스에의 포인터를 받고 있던 메소드는, 현재는 IDirect3DVertexBuffer7 또는 IDirectDrawSurface7 인터페이스에의 포인터를 받게 되어 있다. 인터페이스에 추가된 뷰포트, 머트리얼, 및 라이팅용의 메소드는, 새로운 구조체에의 포인터를 받는다. 이러한 구조체에 대해서는, 각각의 새로운 메소드의 레퍼런스 페이지로 설명한다.

이 인터페이스는, 실행 버퍼와 함께 사용하는 것을 고려하고 있지 않았기 때문에, 실행 버퍼 관련의 메소드는 일절 가지고 있지 않다. 실행 버퍼에 대해서는, 구릴리스의 DirectX 의 문서를 참조할것.

LPDIRECT3DDEVICE2,LPDIRECT3DDEVICE3, 또는 LPDIRECT3DDEVICE7 데이터형을 사용해,IDirect3DDevice2,IDirect3DDevice3, 또는 IDirect3DDevice7 인터페이스에의 포인터를 저장 하는 변수를 선언할 수 있다. d3d.h 헤더 파일은, 이하의 코드로 이러한 데이터형을 선언하고 있다.

typedef struct IDirect3DDevice2    *LPDIRECT3DDEVICE2;
typedef struct IDirect3DDevice3    *LPDIRECT3DDEVICE3;
typedef struct IDirect3DDevice7    *LPDIRECT3DDEVICE7;

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

Direct3D 디바이스,렌더링


IDirect3DDevice7::ApplyStateBlock

IDirect3DDevice7::ApplyStateBlock 메소드는, 기존의 디바이스 스테이트 블록을 렌더링 디바이스에 적용한다.

HRESULT ApplyStateBlock(
  DWORD dwBlockHandle
);

파라미터

dwBlockHandle
실행하는 디바이스 스테이트 블록에의 핸들. 이것은 전에 호출한 IDirect3DDevice7::EndStateBlock 메소드에 의해 돌려주어진다.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

D3DERR_INBEGINSTATEBLOCK
D3DERR_INVALIDVERTEXTYPE

주의

어플리케이션으로 다른 블록을 기록하고 있을 때, 디바이스 스테이트 블록을 적용할 수 없다.

이 메소드는 IDirect3DDevice7 인터페이스와 함께 도입되었다.

렌더링 디바이스의 스테이트에 영향을 주는 모든 처리와 같이, 스테이트 블록의 적용은, 장면의 렌더링중, 즉 IDirect3DDevice7::BeginScene 메소드를 호출하고 나서 IDirect3DDevice7::EndScene 를 호출할 때까지 에 실시하는 것을 추천 한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::BeginStateBlock ,IDirect3DDevice7::EndStateBlock ,IDirect3DDevice7::CaptureStateBlock ,IDirect3DDevice7::CreateStateBlock ,IDirect3DDevice7::DeleteStateBlock ,스테이트 블록


IDirect3DDevice7::BeginScene

IDirect3DDevice7::BeginScene 메소드는 장면을 시작 한다. 어플리케이션에서는, 렌더링을 실행하기 전에는 반드시 이 메소드를 호출해, 렌더링의 종료시 및 재차 IDirect3DDevice7::BeginScene 를 호출하기 전에는 반드시 IDirect3DDevice7::EndScene 를 호출한다.

HRESULT BeginScene();

파라미터

없음.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면 에러를 돌려준다. Direct3D 직접 모드의 에러값 및 그 설명에 대해서는, 「반환값」을 참조할것.

주의

BeginScene 메소드가 실패 하면, 디바이스는 장면을 시작 할 수 없기 때문에,IDirect3DDevice7::EndScene 메소드를 호출할 필요는 없다. 실제, 그 전의 BeginScene 의 호출이 실패 하면,IDirect3DDevice7::EndScene 메소드의 호출도 실패한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::EndScene ,장면의 시작과 종료


IDirect3DDevice7::BeginStateBlock

IDirect3DDevice7::BeginStateBlock 메소드는, Direct3D 에 디바이스 스테이트 블록의 기록을 시작 하도록(듯이) 알린다.

HRESULT BeginStateBlock();

파라미터

없음.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

D3DERR_INBEGINSTATEBLOCK
DDERR_OUTOFMEMORY

주의

이 메소드는 IDirect3DDevice7 인터페이스와 함께 도입되었다.

어플리케이션에서는, 이 메소드를 호출하기 전에 IDirect3DDevice7::ValidateDevice 메소드를 호출해, 기록하는 모든 스테이트가 유효한 것을 확인할 수 있다.

스테이트 블록 (IDirect3DDevice7::BeginStateBlock 를 호출하고 나서 IDirect3DDevice7::EndStateBlock 를 호출할 때까지)에 기록할 수 있는 메소드는 이하대로이다.

  • IDirect3DDevice7::LightEnable
  • IDirect3DDevice7::SetClipPlane
  • IDirect3DDevice7::SetLight
  • IDirect3DDevice7::SetMaterial
  • IDirect3DDevice7::SetRenderState
  • IDirect3DDevice7::SetTexture
  • IDirect3DDevice7::SetTextureStageState
  • IDirect3DDevice7::SetTransform
  • IDirect3DDevice7::SetViewport

스테이트 블록내에서는, 스테이트 변경의 순서는 보증되지 않는다. 스테이트 블록으로 같은 스테이트가 여러 차례 지정되었을 경우, 사용되는 것은 마지막 값뿐이다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::ApplyStateBlock ,IDirect3DDevice7::EndStateBlock ,IDirect3DDevice7::CaptureStateBlock ,IDirect3DDevice7::CreateStateBlock ,IDirect3DDevice7::DeleteStateBlock ,스테이트 블록


IDirect3DDevice7::CaptureStateBlock

IDirect3DDevice7::CaptureStateBlock 메소드는, 기존의 스테이트 블록내의 값을, 디바이스에 현재 설정되어 있는 값에 갱신한다.

HRESULT CaptureStateBlock(
  DWORD dwBlockHandle
);

파라미터

dwBlockHandle
현재의 디바이스 스테이트를 수중에 넣는 스테이트 블록에의 핸들.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 표준의 에러 코드를 돌려주는지, 스테이트 블록의 기록중이면 D3DERR_INBEGINSTATEBLOCK 를 돌려준다.

주의

이 메소드는, 기존의 스테이트 블록에 포함되는 스테이트의 갱신 후의 값을 수중에 넣는다. 디바이스 전체의 스테이트는 수중에 넣지 않는다. 상세한 것에 대하여는, 「스테이트 블록의 취득」을 참조할것.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::ApplyStateBlock ,IDirect3DDevice7::BeginStateBlock ,IDirect3DDevice7::CreateStateBlock ,IDirect3DDevice7::EndStateBlock ,IDirect3DDevice7::DeleteStateBlock ,스테이트 블록,스테이트 블록의 취득


IDirect3DDevice7::CreateStateBlock

IDirect3DDevice7::CreateStateBlock 메소드는, 모든 디바이스 스테이트, 버텍스 관련의 스테이트, 또는 픽셀 관련의 스테이트의 현재의 값을 포함한 새로운 스테이트 블록을 생성 한다.

HRESULT CreateStateBlock(
  D3DSTATEBLOCKTYPE d3dsbType,
  LPDWORD lpdwBlockHandle
);

파라미터

d3dsbType
메소드로 수중에 넣는 스테이트 데이터의 종류. 이 파라미터는,D3DSTATEBLOCKTYPE 열거형에 정의되는 값의 어느 쪽인가에 설정한다.
lpdwBlockHandle
메소드가 성공했을 경우에, 스테이트 블록의 핸들을 저장 하는 변수의 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

D3DERR_INBEGINSTATEBLOCK
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

주의

버텍스 관련의 디바이스 스테이트란, 일반적으로는 시스템의 버텍스의 처리 방법으로 영향을 주는 스테이트를 말한다. 픽셀 관련의 스테이트란, 라스터화에 있어서의 시스템의 픽셀 또는 깊이 버퍼의 처리 방법으로 영향을 주는 디바이스 스테이트를 말한다. 스테이트에 따라서는 양쪽 모두에 속하는 경우도 있다. 각각의 스테이트의 상세한 것에 대하여는, 「사전 정의하는 스테이트 블록의 생성」을 참조할것.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::ApplyStateBlock ,IDirect3DDevice7::BeginStateBlock ,IDirect3DDevice7::CaptureStateBlock ,IDirect3DDevice7::EndStateBlock ,IDirect3DDevice7::DeleteStateBlock ,스테이트 블록


IDirect3DDevice7::Clear

IDirect3DDevice7::Clear 메소드는, 뷰포트 (또는 뷰포트내의 직사각형 세트)를 특정의 RGBA 색에 클리어, 깊이 버퍼를 클리어, 및 스텐실 버퍼를 삭제한다. 이 메소드는, 종래의 IDirect3DViewport3 인터페이스가 공개한 클리어 메소드에 대신해 사용된다.

HRESULT Clear(
  DWORD     dwCount,
  LPD3DRECT lpRects,
  DWORD     dwFlags,
  DWORD     dwColor,
  D3DVALUE  dvZ,
  DWORD     dwStencil
);

파라미터

dwCount
lpRects 의 배열에 있는 직사각형의 수. lpRects 를 NULL 로 설정하는 경우는, 이 파라미터를 0 으로 설정한다.
lpRects
클리어 하는 직사각형을 기술하는 D3DRECT 구조체의 배열. 직사각형을 렌더링 타겟의 치수로 설정 하면, 표면 전체가 클리어 된다. 각 직사각형은, 렌더링 타겟 표면 위에의점에 대응하는 화면 좌표를 사용한다. 좌표는 뷰포트의 직사각형의 경계에서 클립 된다. 이 파라미터를 NULL 로 설정 하면, 뷰포트 직사각형 전체를 클리어 하게 된다.
dwFlags
클리어 하는 표면을 나타내는 플래그. 이 파라미터는, 다음의 플래그의 임의의 편성을 취할 수가 있지만, 플래그를 최저 1 개(살)은 사용하지 않으면 안 된다.
D3DCLEAR_TARGET
렌더링 타겟을 클리어 해,dwColor 파라미터의 색으로 한다.
D3DCLEAR_STENCIL
스텐실 버퍼를 클리어 해,dwStencil 파라미터의 값으로 한다.
D3DCLEAR_ZBUFFER
깊이 버퍼를 클리어 해,dvZ 파라미터의 값으로 한다.
dwColor
렌더링 타겟 표면을 클리어 하는 32 비트 RGBA 컬러값.
dvZ
이 메소드가 깊이 버퍼에 보존하는 새로운 z 값. 이 파라미터에는 0.0 에서 1.0 까지의 값을 사용할 수 있다 (Z 베이스 또는 W 베이스의 깊이 버퍼의 경우). 0.0 은 뷰아에 가장 가까운 거리, 1.0 은 가장 먼 거리를 나타낸다.
dwStencil
각 스텐실 버퍼의 엔트리에 보존하는 정수값. 이 파라미터에는 0 에서 2n-1 까지의 값을 사용할 수 있다. n 는 스텐실 버퍼의 비트 깊이.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

D3DERR_STENCILBUFFER_NOTPRESENT
D3DERR_VIEWPORTHASNODEVICE
D3DERR_ZBUFFER_NOTPRESENT
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는 IDirect3DDevice7 인터페이스와 함께 도입되었다.

이 메소드는, 렌더링 타겟으로 깊이 버퍼가 Attach되어 있지 않을 때에 D3DCLEAR_ZBUFFER 또는 D3DCLEAR_STENCIL 플래그를 지정 하면 실패한다. 같이 깊이 버퍼 포맷에 스텐실 버퍼 정보가 포함되지 않은 경우, D3DCLEAR_STENCIL 플래그를 지정 하면, 이 메소드는 실패한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.


IDirect3DDevice7::ComputeSphereVisibility

IDirect3DDevice7::ComputeSphereVisibility 메소드는, 이 디바이스의 현재의 뷰포트에 있어서의 구(공)의 배열의 가시성 (완전, 일부, 불가시)을 계산한다.

HRESULT ComputeSphereVisibility(
  LPD3DVECTOR lpCenters,
  LPD3DVALUE  lpRadii,
  DWORD       dwNumSpheres,
  DWORD       dwFlags,
  LPDWORD     lpdwReturnValues
);

파라미터

lpCenters
월드 공간 좌표에 있어서의, 각 구(공)의 중심점을 기술하는 D3DVECTOR 구조체의 배열.
lpRadii
각 구(공)의 반경을 나타내는 D3DVALUE 변수의 배열.
dwNumSpheres
구(공)의 수. 0 보다 큰 값을 설정한다.
dwFlags
현재는 사용되어 있지 않다. 0 을 설정한다.
lpdwReturnValues
DWORD 값의 배열. 이 배열은 초기화의 필요는 없지만, 테스트되는 구(공) 마다 DWORD 를 포함할 수가 있는 크기가 없으면 안 된다. 이 메소드가 돌아가면(자), 배열의 각 요소에는, 이 디바이스의 현재의 뷰포트에 있어서의 구(공)의 가시성을 나타내는 플래그의 편성이 저장 된다. 구(공)의 가시성이 완전의 경우,lpdwReturnValues 의 대응하는 엔트리는 0 이 된다. 이하에 나타내는 플래그를 조합해 배열에게 줄 수가 있다.

기본 클리핑 플래그

D3DCLIP_BACK
모든 버텍스를절두체의 뒷면에서 클리핑 한다.
D3DCLIP_BOTTOM
모든 버텍스를절두체의 저면에서 클리핑 한다.
D3DCLIP_FRONT
모든 버텍스를절두체의 전면에서 클리핑 한다.
D3DCLIP_LEFT
모든 버텍스를절두체의 좌측면에서 클리핑 한다.
D3DCLIP_RIGHT
모든 버텍스를절두체의 우측면에서 클리핑 한다.
D3DCLIP_TOP
모든 버텍스를절두체의 표면에서 클리핑 한다.
D3DCLIP_GEN0 through D3DCLIP_GEN5
모든 버텍스를 대응하는 어플리케이션 정의 클립면에서 클리핑 한다.

편성과 일반 플래그

D3DSTATUS_CLIPINTERSECTIONALL
모든 CLIPINTERSECTION 플래그의 편성.
D3DSTATUS_CLIPUNIONALL
모든 CLIPUNION 플래그의 편성.
D3DSTATUS_DEFAULT
D3DSTATUS_CLIPINTERSECTIONALL 와 D3DSTATUS_ZNOTVISIBLE 플래그의 편성. 이 값이, 디폴트이다.
D3DSTATUS_ZNOTVISIBLE
렌더링 된 프리미티브가 불가시인 것을 나타낸다. 이 플래그는, Z 체크를 사용하는 렌더링을 실행할 때, 시스템에 의해 설정 또는 클리어 된다 (D3DRENDERSTATE_ZVISIBLE 를 참조할것).

클립 교차 플래그

D3DSTATUS_CLIPINTERSECTIONBACK
절두체의후방 클립면의 버텍스의 클립 플래그의논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONBOTTOM
절두체아래의 버텍스의 클립 플래그의논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONFRONT
절두체의전방 클립면의 버텍스의 클립 플래그의논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONGEN0 through D3DSTATUS_CLIPINTERSECTIONGEN5
어플리케이션 정의 클립면의 클립 플래그의논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONLEFT
절두체의 좌측의 버텍스의 클립 플래그의논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONRIGHT
절두체의 우측의 버텍스의 클립 플래그의논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONTOP
절두체의 위에의 버텍스의 클립 플래그의논리츠무를 잡는다.

클립 결합 플래그

D3DSTATUS_CLIPUNIONBACK
D3DCLIP_BACK 와 같다.
D3DSTATUS_CLIPUNIONBOTTOM
D3DCLIP_BOTTOM 와 같다.
D3DSTATUS_CLIPUNIONFRONT
D3DCLIP_FRONT 와 같다.
D3DSTATUS_CLIPUNIONGEN0 through D3DSTATUS_CLIPUNIONGEN5
D3DCLIP_GEN0 로부터 D3DCLIP_GEN5 와 같다.
D3DSTATUS_CLIPUNIONLEFT
D3DCLIP_LEFT 와 같다.
D3DSTATUS_CLIPUNIONRIGHT
D3DCLIP_RIGHT 와 같다.
D3DSTATUS_CLIPUNIONTOP
D3DCLIP_TOP 와 같다.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDMATRIX
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

구(공)의 가시성은, 월드, 뷰, 및 투영의 합성 행렬의 역행열을 사용해 절두체를 모델 공간에 역트랜스 폼 하는 것으로써 계산한다. 이 합성 행렬을 역행열에 트랜스 폼 할 수 없는 경우 (행렬식이 0 의 경우)는, 메소드는 실패해,D3DERR_INVALIDMATRIX 를 돌려준다.

다음의 C 코드는,ComputeSphereVisibility 의 사용 방법을 나타낸다.

D3DVECTOR center = {0,0,0};
D3DVALUE  radius = 1;
DWORD result = 0;

res = m_pd3dDevice->ComputeSphereVisibility(&center, &radius, 1, 0, &result);

if (res == D3D_OK)
{
    if (result & D3DSTATUS_CLIPINTERSECTIONALL)
    {
        // 구(공)이 외측에 있다.
        if (result & D3DSTATUS_CLIPINTERSECTIONLEFT)
            printf("Sphere left outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONRIGHT)
            printf("Sphere right outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONTOP)
            printf("Sphere top outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONBOTTOM)
            printf("Sphere bottom outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONFRONT)
            printf("Sphere front outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONBACK)
            printf("Sphere back outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONGEN0)
            printf("Sphere gen0 outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONGEN1)
            printf("Sphere gen1 outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONGEN2)
            printf("Sphere gen2 outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONGEN3)
            printf("Sphere gen3 outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONGEN4)
            printf("Sphere gen4 outside\n");
        if (result & D3DSTATUS_CLIPINTERSECTIONGEN5)
            printf("Sphere gen5 outside\n");
        }
    else
    if (result & D3DSTATUS_CLIPUNIONALL)
    {
        // 구(공)이 시추대로 교차한다.
        if (result & D3DSTATUS_CLIPUNIONLEFT)
            printf("Sphere left intersect\n");
        if (result & D3DSTATUS_CLIPUNIONRIGHT)
            printf("Sphere right intersect\n");
        if (result & D3DSTATUS_CLIPUNIONTOP)
            printf("Sphere top intersect\n");
        if (result & D3DSTATUS_CLIPUNIONBOTTOM)
            printf("Sphere bottom intersect\n");
        if (result & D3DSTATUS_CLIPUNIONFRONT)
            printf("Sphere front intersect\n");
        if (result & D3DSTATUS_CLIPUNIONBACK)
            printf("Sphere back intersect\n");
        if (result & D3DSTATUS_CLIPUNIONGEN0)
            printf("Sphere gen0 intersect\n");
        if (result & D3DSTATUS_CLIPUNIONGEN1)
            printf("Sphere gen1 intersect\n");
        if (result & D3DSTATUS_CLIPUNIONGEN2)
            printf("Sphere gen2 intersect\n");
        if (result & D3DSTATUS_CLIPUNIONGEN3)
            printf("Sphere gen3 intersect\n");
        if (result & D3DSTATUS_CLIPUNIONGEN4)
            printf("Sphere gen4 intersect\n");
        if (result & D3DSTATUS_CLIPUNIONGEN5)
            printf("Sphere gen5 intersect\n");
    }
    else
    {
        printf("Sphere is inside\n");
    }
}
else
    printf("Invalid return value\n");

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.


IDirect3DDevice7::DeleteStateBlock

IDirect3DDevice7::DeleteStateBlock 메소드는, 이전에 기록한 디바이스 스테이트 블록을 삭제한다.

HRESULT DeleteStateBlock (
  DWORD dwBlockHandle
);

파라미터

dwBlockHandle
삭제하는 디바이스 스테이트 블록에의 핸들. 이것은 전에 호출한 IDirect3DDevice7::EndStateBlock 메소드에 의해 돌려주어진다.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

D3DERR_INBEGINSTATEBLOCK
D3DERR_INVALIDVERTEXTYPE

주의

다른 스테이트 블록의 기록중에, 디바이스 스테이트 블록을 삭제할 수 없다.

이 메소드는 IDirect3DDevice7 인터페이스와 함께 도입되었다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::ApplyStateBlock ,IDirect3DDevice7::BeginStateBlock ,IDirect3DDevice7::CaptureStateBlock ,IDirect3DDevice7::CreateStateBlock ,IDirect3DDevice7::EndStateBlock ,스테이트 블록


IDirect3DDevice7::DrawIndexedPrimitive

IDirect3DDevice7::DrawIndexedPrimitive 메소드는, 버텍스의 배열에의 인덱스에 근거해, 지정된 지오메트리 프리미티브를 렌더링 한다.

HRESULT DrawIndexedPrimitive(
  D3DPRIMITIVETYPE d3dptPrimitiveType,
  DWORD  dwVertexTypeDesc,
  LPVOID lpvVertices,
  DWORD  dwVertexCount,
  LPWORD lpwIndices,
  DWORD  dwIndexCount,
  DWORD  dwFlags
);

파라미터

d3dptPrimitiveType
이 커멘드에 의해 렌더링 되는 프리미티브의 형태. 이것은,D3DPRIMITIVETYPE 열거형의 멤버의 1 개가 아니면 안된다.

D3DPRIMITIVETYPE 의 D3DPT_POINTLIST 멤버는 인덱스 붙이고 되지 않는다.

dwVertexTypeDesc
이 프리미티브 세트의 버텍스 포맷을 기술하는,유연한 버텍스 포맷 플래그의 편성.
lpvVertices
프리미티브 순서로 사용되는 버텍스의 리스트에의 포인터.
dwVertexCount
리스트중의 버텍스수를 정의한다.

이 파라미터의 사용 방법은,IDirect3DDevice7::DrawPrimitive 메소드의 dwVertexCount 파라미터와는 다르다. IDirect3DDevice7::DrawPrimitive 메소드에서는,dwVertexCount 파라미터는 드로잉(Drawing) 해야 할 버텍스수를 주지만, 이 메소드는 lpvVertices 파라미터가 가리키는 배열의 합계 버텍스수를 준다. IDirect3DDevice7::DrawIndexedPrimitive 를 호출하면나무에는,dwIndexCount 파라미터로 드로잉(Drawing) 해야 할 버텍스수를 지정한다.

lpwIndices
렌더링 하는 지오메트리를 생성 할 경우에, 지정된 버텍스 리스트에의 인덱스부를 하는데 사용되는 WORD 의 리스트에의 포인터.
dwIndexCount
지오메트리를 생성 하는데 준비하는 인덱스수를 지정한다. 허용 되는 최대 인덱스수는 D3DMAXNUMVERTICES (0xFFFF)이다.
dwFlags
대기하지 않고 프리미티브를 렌더링 하는 경우는 제로, 또는 이하의 플래그를 지정한다.
D3DDP_WAIT
메소드는, 다각형이 카드로 보내지자마자 돌아가는 것이 아니라, 렌더링이 끝날 때까지 기다린다. (장면 캡춰 카드로는, 카드로부터의 응답이 있는 대로, 메소드는 돌아간다. ) 이 플래그는 디버그에 자주(잘) 사용된다. 어플리케이션은, 장면을 먼저 진행하기 전에 확실히 갱신해 두기 위해서(때문에)도, 이 플래그를 사용해서는 안된다.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
DDERR_INVALIDPARAMS
DDERR_WASSTILLDRAWING

주의

렌더링 하는 버텍스가, 지정한 버텍스 포맷과 일치하고 있는 것을 확인한다. 퍼포먼스 위에의 이유로부터, Direct3D 는 버텍스의 사이즈 및 보폭과 제공된 유연한 버텍스 포맷과의 조합을 실시하지 않는다. 이것이 일치하고 있지 않으면 메모리 장해가 발생하기 쉽다.

이 메소드는, 버텍스 버퍼로부터의 렌더링에는 사용하지 않고, 대신에 버텍스 버퍼 메소드를 사용한다.

이 메소드는, 종래의 인터페이스로 사용된 메소드와는 달라,dwFlags 파라미터로 D3DDP_DONOTCLIP, D3DDP_DONOTLIGHT, 및 D3DDP_DONOTUPDATEEXTENTS 플래그를 받지 않는다. 이러한 플래그의 기능성은, 현재는 D3DRENDERSTATE_CLIPPING ,D3DRENDERSTATE_LIGHTING , 및 D3DRENDERSTATE_EXTENTS 렌더링 스테이트에 의해 사용할 수 있다.

극단적으로 큰 버텍스 배열의 매우 작은 부분 집합인 버텍스를 렌더링 하는데, 이 메소드를 사용하지 않는 것. 이 메소드는, 렌더링 하는 버텍스의 위치 좌표나 수에 관계없이, 지정된 버퍼의 모든 버텍스를 트랜스 폼 한다. 따라서, 수천의 버텍스를 저장 하는 배열을 건네주어, 그 중 수백의 버텍스 밖에 렌더링 하지 않는 것 같은 경우는, 어플리케이션의 퍼포먼스가 현저하게 저하한다. 큰 버퍼로부터 소수의 버텍스를 렌더링 할 필요가 있는 경우는, Direct3D 버텍스 버퍼 렌더링 메소드를 사용한다. 상세한 것에 대하여는, 「버텍스 버퍼」를 참조할것.

이 메소드는, 대응하는 IDirect3DDevice2 인터페이스의 것이란, 제 2 파라미터로서 D3DVERTEXTYPE 열거형의 멤버는 아니고, 유연한 버텍스 포맷의 기술자를 사용하는 점이 다르다. D3DVERTEXTYPE 의 멤버의 어느쪽이든을 사용하려고 하면(자), 이 메소드는 실패해,DDERR_INVALIDPARAMS 를 돌려준다. 상세한 것에 대하여는, 「버텍스 포맷」을 참조할것.

DirectX 의 현재의 버젼에서는,IDirect3DDevice7::DrawIndexedPrimitive 가 필요이상으로 큰 갱신 직사각형을 생성하는 일이 있다. 다수의 버텍스수를 처리할 경우에는, 이것은 어플리케이션의 퍼포먼스에 악영향을 준다. D3DTLVERTEX 버텍스를 사용해, 시스템으로 필요 이상의 버텍스를 처리하는 경우는, D3DDP_DONOTCLIP 및 D3DDP_DONOTUPDATEEXTENTS 플래그를 사용해 이 문제를 해결한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::DrawPrimitive ,IDirect3DDevice7::DrawPrimitiveStrided ,IDirect3DDevice7::DrawPrimitiveVB ,IDirect3DDevice7::DrawIndexedPrimitiveStrided ,IDirect3DDevice7::DrawIndexedPrimitiveVB


IDirect3DDevice7::DrawIndexedPrimitiveStrided

IDirect3DDevice7::DrawIndexedPrimitiveStrided 메소드는, 보폭 버텍스의 배열에의 인덱스에 근거해, 지오메트리 프리미티브를 렌더링 한다. 상세 정보에 대해서는, 「보폭 버텍스 포맷」을 참조할것.

HRESULT DrawIndexedPrimitiveStrided(
  D3DPRIMITIVETYPE d3dptPrimitiveType,
  DWORD  dwVertexTypeDesc,
  LPD3DDRAWPRIMITIVESTRIDEDDATA lpVertexArray,
  DWORD  dwVertexCount,
  LPWORD lpwIndices,
  DWORD  dwIndexCount,
  DWORD  dwFlags
);

파라미터

d3dptPrimitiveType
이 커멘드에 의해 렌더링 되는 프리미티브의 형태. 이것은,D3DPRIMITIVETYPE 열거형의 멤버의 1 개가 아니면 안된다.

D3DPRIMITIVETYPE 의 D3DPT_POINTLIST 멤버에는 인덱스가 없다.

dwVertexTypeDesc
이 프리미티브의 버텍스 포맷을 기술하는,유연한 버텍스 포맷 플래그의 편성.
lpVertexArray
이 프리미티브의 버텍스 성분의 포인터 및 메모리 보폭을 저장 하는 D3DDRAWPRIMITIVESTRIDEDDATA 구조체의 주소. 이 때의 포맷은,dwVertexTypeDesc 의 플래그로 지정하는 포맷이다.
dwVertexCount
리스트중의 버텍스수를 정의한다.

이 파라미터의 사용 방법은,IDirect3DDevice7::DrawPrimitive 메소드의 dwVertexCount 파라미터와는 다르다. IDirect3DDevice7::DrawPrimitive 메소드에서는,dwVertexCount 파라미터는 드로잉(Drawing) 해야 할 버텍스수를 주지만, 이 메소드는 lpVertexArray 파라미터가 가리키는 배열의 합계 버텍스수를 준다. IDirect3DDevice7::DrawIndexedPrimitiveStrided 를 호출하면나무에는,dwIndexCount 파라미터로 드로잉(Drawing) 해야 할 버텍스수를 지정한다.

lpwIndices
렌더링 하는 지오메트리를 생성 할 경우에, 지정된 버텍스 리스트에의 인덱스부를 하는데 사용되는 WORD 의 리스트에의 포인터.
dwIndexCount
지오메트리를 생성 하는데 준비하는 인덱스수를 지정한다. 허용 되는 최대 인덱스수는 D3DMAXNUMVERTICES (0xFFFF)이다.
dwFlags
대기하지 않고 프리미티브를 렌더링 하는 경우는 제로, 또는 이하의 플래그를 지정한다.
D3DDP_WAIT
메소드는, 다각형이 카드로 보내지자마자 돌아가는 것이 아니라, 렌더링이 끝날 때까지 기다린다. (장면 캡춰 카드로는, 카드로부터의 응답이 있는 대로, 메소드는 돌아간다. ) 이 플래그는 디버그에 자주(잘) 사용된다. 어플리케이션은, 장면을 먼저 진행하기 전에 확실히 갱신해 두기 위해서(때문에)도, 이 플래그를 사용해서는 안된다.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
DDERR_INVALIDPARAMS
DDERR_WASSTILLDRAWING

주의

렌더링 하는 버텍스가, 지정한 버텍스 포맷과 일치하고 있는 것을 확인한다. 퍼포먼스 위에의 이유로부터, Direct3D 는 버텍스의 사이즈 및 보폭과 제공된 유연한 버텍스 포맷과의 조합을 실시하지 않는다. 이것이 일치하고 있지 않으면 메모리 장해가 발생하기 쉽다.

이 메소드는, 버텍스 버퍼로부터의 렌더링에는 사용하지 않고, 대신에 버텍스 버퍼 메소드를 사용한다.

이 메소드는, 종래의 인터페이스로 사용된 메소드와는 달라,dwFlags 파라미터로 D3DDP_DONOTCLIP, D3DDP_DONOTLIGHT, 및 D3DDP_DONOTUPDATEEXTENTS 플래그를 받지 않는다. 이러한 플래그의 기능성은, 현재는 D3DRENDERSTATE_CLIPPING ,D3DRENDERSTATE_LIGHTING , 및 D3DRENDERSTATE_EXTENTS 렌더링 스테이트에 의해 사용할 수 있다.

이 메소드는, 트랜스 폼 된 버텍스를 지원 하지 않는다. 따라서, D3DFVF_XYZRHW 버텍스 포맷 기술자를 dwVertexTypeDesc 파라미터에 포함하면(자), 메소드는 실패해,D3DERR_INVALIDVERTEXTYPE 를 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::DrawPrimitive ,IDirect3DDevice7::DrawPrimitiveStrided ,IDirect3DDevice7::DrawPrimitiveVB ,IDirect3DDevice7::DrawIndexedPrimitive ,IDirect3DDevice7::DrawIndexedPrimitiveVB ,보폭 버텍스 포맷


IDirect3DDevice7::DrawIndexedPrimitiveVB

IDirect3DDevice7::DrawIndexedPrimitiveVB 메소드는, 버텍스 버퍼내의 버텍스의 배열에 대한 인덱스에 근거해, 지오메트리 프리미티브를 렌더링 한다.

HRESULT DrawIndexedPrimitiveVB(
  D3DPRIMITIVETYPE        d3dptPrimitiveType,
  LPDIRECT3DVERTEXBUFFER7 lpd3dVertexBuffer,
  DWORD  dwStartVertex,
  DWORD  dwNumVertices,
  LPWORD lpwIndices,
  DWORD  dwIndexCount,
  DWORD  dwFlags
);

파라미터

d3dptPrimitiveType
이 커멘드에 의해 렌더링 되는 프리미티브의 형태. 이것은,D3DPRIMITIVETYPE 열거형의 멤버의 1 개가 아니면 안된다.

D3DPRIMITIVETYPE 의 D3DPT_POINTLIST 멤버는 인덱스 붙이고 되지 않는다.

lpd3dVertexBuffer
버텍스의 배열을 저장 하는 버텍스 버퍼의 IDirect3DVertexBuffer7 인터페이스의 주소. 버텍스는, 트랜스 폼 되고 있지 않아도, 최적화되고 있지 않아도 좋다.
dwStartVertex
버텍스 버퍼내의 렌더링 되는 최초의 버텍스의 인덱스
dwNumVertices
버텍스 버퍼내의 렌더링 되는 버텍스의 합계 개수.
lpwIndices
버텍스 버퍼내의 버텍스에의 인덱스부에 사용되는,WORD 의 배열의 주소. 배열의 값은, 범위 [0, dwNumVertices – 1] 으로 버텍스를 인덱스 붙이고 할 필요가 있다.
dwIndexCount
lpwIndices. 에 있어서의 배열내의 인덱스수. 허용 되는 최대 인덱스수는 D3DMAXNUMVERTICES (0xFFFF)이다.
dwFlags
대기하지 않고 프리미티브를 렌더링 하는 경우는 제로, 또는 이하의 플래그를 지정한다.
D3DDP_WAIT
메소드는, 다각형이 카드로 보내지자마자 돌아가는 것이 아니라, 렌더링이 끝날 때까지 기다린다. (장면 캡춰 카드로는, 카드로부터의 응답이 있는 대로, 메소드는 돌아간다. ) 이 플래그는 디버그에 자주(잘) 사용된다. 어플리케이션은, 장면을 먼저 진행하기 전에 확실히 갱신해 두기 위해서(때문에)도, 이 플래그를 사용해서는 안된다.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
D3DERR_VERTEXBUFFERLOCKED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_WASSTILLDRAWING

주의

렌더링 하는 버텍스가, 지정한 버텍스 포맷과 일치하고 있는 것을 확인한다. 퍼포먼스 위에의 이유로부터, Direct3D 는 버텍스의 사이즈 및 보폭과 제공된 유연한 버텍스 포맷과의 조합을 실시하지 않는다. 이것이 일치하고 있지 않으면 메모리 장해가 발생하기 쉽다.

버텍스 버퍼로부터 렌더링 하면나무는, 버텍스 버퍼 메소드를 사용할 필요가 있다.

이 메소드는, 종래의 인터페이스로 사용된 메소드와는 달라,dwFlags 파라미터로 D3DDP_DONOTCLIP, D3DDP_DONOTLIGHT, 및 D3DDP_DONOTUPDATEEXTENTS 플래그를 받지 않는다. 이러한 플래그의 기능성은, 현재는 D3DRENDERSTATE_CLIPPING ,D3DRENDERSTATE_LIGHTING , 및 D3DRENDERSTATE_EXTENTS 렌더링 스테이트에 의해 사용할 수 있다.

소프트웨어 디바이스 (MMX 및 RGB 디바이스)는, 로컬 또는 비로컬일지 어떨지에 관계없이, 비디오 메모리로부터 버텍스 버퍼를 렌더링 할 수 없다. 소프트웨어 디바이스를 사용해 버텍스 버퍼를 렌더링 하려면 , 버텍스 버퍼가 시스템 메모리에 존재해야 한다. 하드웨어 디바이스는, 시스템 메모리 또는 비디오 메모리의 어느 쪽의 버텍스 버퍼로부터에서도, 렌더링 할 수가 있다.

버텍스 버퍼가 락 되고 있을 때는 렌더링 할 수 없다. 락 된 버텍스 버퍼를 사용해 IDirect3DDevice7::DrawIndexedPrimitiveVB 또는 IDirect3DDevice7::DrawPrimitiveVB 메소드를 호출하려고 하면 실패해,D3DERR_VERTEXBUFFERLOCKED 가 돌려주어진다.

IDirect3DDevice3 인터페이스에서는, 이 메소드는 종래의 IDirect3DVertexBuffer 인터페이스에의 포인터를 받았다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::DrawPrimitive ,IDirect3DDevice7::DrawPrimitiveStrided ,IDirect3DDevice7::DrawPrimitiveVB ,IDirect3DDevice7::DrawIndexedPrimitive ,IDirect3DDevice7::DrawIndexedPrimitiveStrided


IDirect3DDevice7::DrawPrimitive

IDirect3DDevice7::DrawPrimitive 메소드는, 지정의 형태의 도형 프리미티브의 순서로서 버텍스의 지정의 배열을 렌더링 한다.

HRESULT DrawPrimitive(
  D3DPRIMITIVETYPE dptPrimitiveType,
  DWORD  dwVertexTypeDesc,
  LPVOID lpvVertices,
  DWORD  dwVertexCount,
  DWORD  dwFlags
);

파라미터

dptPrimitiveType
이 커멘드에 의해 렌더링 되는 프리미티브의 형태. 이것은,D3DPRIMITIVETYPE 열거형의 멤버의 1 개가 아니면 안된다.
dwVertexTypeDesc
이 프리미티브세트에 대한 버텍스 포맷을 기술하는유연한 버텍스 포맷 플래그의 편성.
lpvVertices
프리미티브 순서중에서 사용하는 버텍스의 배열에의 포인터.
dwVertexCount
배열중의 버텍스수. 허용 되는 최대 버텍스수는 D3DMAXNUMVERTICES (0xFFFF)이다.
dwFlags
대기하지 않고 프리미티브를 렌더링 하는 경우는 제로, 또는 이하의 플래그를 지정한다.
D3DDP_WAIT
메소드는, 다각형이 카드로 보내지자마자 돌아가는 것이 아니라, 렌더링이 끝날 때까지 기다린다. (장면 캡춰 카드로는, 카드로부터의 응답이 있는 대로, 메소드는 돌아간다. ) 이 플래그는 디버그에 자주(잘) 사용된다. 어플리케이션은, 장면을 먼저 진행하기 전에 확실히 갱신해 두기 위해서(때문에)도, 이 플래그를 사용해서는 안된다.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
DDERR_INVALIDPARAMS
DDERR_WASSTILLDRAWING

주의

렌더링 하는 버텍스가, 지정한 버텍스 포맷과 일치하고 있는 것을 확인한다. 퍼포먼스 위에의 이유로부터, Direct3D 는 버텍스의 사이즈 및 보폭과 제공된 유연한 버텍스 포맷과의 조합을 실시하지 않는다. 이것이 일치하고 있지 않으면 메모리 장해가 발생하기 쉽다.

이 메소드는, 버텍스 버퍼로부터의 렌더링에는 사용하지 않고, 대신에 버텍스 버퍼 메소드를 사용한다.

이 메소드는, 종래의 인터페이스로 사용된 메소드와는 달라,dwFlags 파라미터로 D3DDP_DONOTCLIP, D3DDP_DONOTLIGHT, 및 D3DDP_DONOTUPDATEEXTENTS 플래그를 받지 않는다. 이러한 플래그의 기능성은, 현재는 D3DRENDERSTATE_CLIPPING ,D3DRENDERSTATE_LIGHTING , 및 D3DRENDERSTATE_EXTENTS 렌더링 스테이트에 의해 사용할 수 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::DrawPrimitiveStrided ,IDirect3DDevice7::DrawPrimitiveVB ,IDirect3DDevice7::DrawIndexedPrimitive ,IDirect3DDevice7::DrawIndexedPrimitiveStrided ,IDirect3DDevice7::DrawIndexedPrimitiveVB


IDirect3DDevice7::DrawPrimitiveStrided

IDirect3DDevice7::DrawPrimitiveStrided 메소드는, 지정한 보폭 버텍스의 배열을 지오메트리 프리미티브 순서로서 렌더링 한다. 상세 정보에 대해서는,보폭 버텍스 포맷을 참조할것.

HRESULT DrawPrimitiveStrided(
  D3DPRIMITIVETYPE dptPrimitiveType,
  DWORD  dwVertexTypeDesc,
  LPD3DDRAWPRIMITIVESTRIDEDDATA lpStrideData,
  DWORD  dwVertexCount,
  DWORD  dwFlags
);

파라미터

dptPrimitiveType
이 커멘드에 의해 렌더링 되는 프리미티브의 형태. 이것은,D3DPRIMITIVETYPE 열거형의 멤버의 1 개가 아니면 안된다.
dwVertexTypeDesc
버텍스 포맷을 기술하는유연한 버텍스 포맷 플래그의 편성.
lpStrideData
이 프리미티브의 버텍스 성분의 포인터 및 메모리 보폭을 저장 하는 D3DDRAWPRIMITIVESTRIDEDDATA 구조체의 주소. 이 때의 포맷은,dwVertexTypeDesc 의 플래그로 지정하는 포맷이다.
dwVertexCount
lpVertexArray 에 있어서의 배열내의 버텍스수. 허용 되는 최대 버텍스수는 D3DMAXNUMVERTICES (0xFFFF)이다.
dwFlags
대기하지 않고 프리미티브를 렌더링 하는 경우는 제로, 그렇지 않은 경우는 이하의 플래그를 지정한다.
D3DDP_WAIT
메소드는, 다각형이 카드로 보내지자마자 돌아가는 것이 아니라, 렌더링이 끝날 때까지 기다린다. (장면 캡춰 카드로는, 카드로부터의 응답이 있는 대로, 메소드는 돌아간다. ) 이 플래그는 디버그에 자주(잘) 사용된다. 어플리케이션은, 장면을 먼저 진행하기 전에 확실히 갱신해 두기 위해서(때문에)도, 이 플래그를 사용해서는 안된다.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
DDERR_INVALIDPARAMS
DDERR_WASSTILLDRAWING

주의

렌더링 하는 버텍스가, 지정한 버텍스 포맷과 일치하고 있는 것을 확인한다. 퍼포먼스 위에의 이유로부터, Direct3D 는 버텍스의 사이즈 및 보폭과 제공된 유연한 버텍스 포맷과의 조합을 실시하지 않는다. 이것이 일치하고 있지 않으면 메모리 장해가 발생하기 쉽다.

이 메소드는, 버텍스 버퍼로부터의 렌더링에는 사용하지 않고, 대신에 버텍스 버퍼 메소드를 사용한다.

이 메소드는, 종래의 인터페이스로 사용된 메소드와는 달라,dwFlags 파라미터로 D3DDP_DONOTCLIP, D3DDP_DONOTLIGHT, 및 D3DDP_DONOTUPDATEEXTENTS 플래그를 받지 않는다. 이러한 플래그의 기능성은, 현재는 D3DRENDERSTATE_CLIPPING ,D3DRENDERSTATE_LIGHTING , 및 D3DRENDERSTATE_EXTENTS 렌더링 스테이트에 의해 사용할 수 있다.

이 메소드는, 트랜스 폼 된 버텍스를 지원 하지 않는다. 따라서, D3DFVF_XYZRHW 버텍스 포맷 기술자를 dwVertexTypeDesc 파라미터에 포함하면(자), 메소드는 실패해,D3DERR_INVALIDVERTEXTYPE 를 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::DrawPrimitive ,IDirect3DDevice7::DrawPrimitiveVB ,IDirect3DDevice7::DrawIndexedPrimitive ,IDirect3DDevice7::DrawIndexedPrimitiveStrided ,IDirect3DDevice7::DrawIndexedPrimitiveVB ,보폭 버텍스 포맷


IDirect3DDevice7::DrawPrimitiveVB

IDirect3DDevice7::DrawPrimitiveVB 메소드는, 버텍스 버퍼내의 버텍스의 배열을 지오메트리 프리미티브 순서로서 렌더링 한다.

HRESULT DrawPrimitiveVB(
  D3DPRIMITIVETYPE        d3dptPrimitiveType,
  LPDIRECT3DVERTEXBUFFER7 lpd3dVertexBuffer,
  DWORD dwStartVertex,
  DWORD dwNumVertices,
  DWORD dwFlags
);

파라미터

d3dptPrimitiveType
이 커멘드에 의해 렌더링 되는 프리미티브의 형태. 이것은,D3DPRIMITIVETYPE 열거형의 멤버의 1 개가 아니면 안된다.
lpd3dVertexBuffer
버텍스의 배열을 저장 하는 버텍스 버퍼의 IDirect3DVertexBuffer7 인터페이스의 주소. 버텍스는, 트랜스 폼 되고 있지 않아도, 최적화되고 있지 않아도 좋다.
dwStartVertex
프리미티브중의 최초의 버텍스의 인덱스값. 시점 인덱스로서 가능한 최대치는 D3DMAXNUMVERTICES (0xFFFF)이다. 디버그 빌드에서는, 이 제한값을 넘는 시점 인덱스를 지정 하면, 메소드는 실패해,DDERR_INVALIDPARAMS 를 돌려준다.
dwNumVertices
렌더링 하는 버텍스수. 허용 되는 최대 버텍스수는 D3DMAXNUMVERTICES (0xFFFF)이다.
dwFlags
대기하지 않고 프리미티브를 렌더링 하는 경우는 제로, 그렇지 않은 경우는 이하의 플래그를 지정한다
D3DDP_WAIT
메소드는, 다각형이 카드로 보내지자마자 돌아가는 것이 아니라, 렌더링이 끝날 때까지 기다린다. (장면 캡춰 카드로는, 카드로부터의 응답이 있는 대로, 메소드는 돌아간다. ) 이 플래그는 디버그에 자주(잘) 사용된다. 어플리케이션은, 장면을 먼저 진행하기 전에 확실히 갱신해 두기 위해서(때문에)도, 이 플래그를 사용해서는 안된다.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
D3DERR_VERTEXBUFFERLOCKED
DDERR_INVALIDPARAMS
DDERR_WASSTILLDRAWING

주의

렌더링 하는 버텍스가, 지정한 버텍스 포맷과 일치하고 있는 것을 확인한다. 퍼포먼스 위에의 이유로부터, Direct3D 는 버텍스의 사이즈 및 보폭과 제공된 유연한 버텍스 포맷과의 조합을 실시하지 않는다. 이것이 일치하고 있지 않으면 메모리 장해가 발생하기 쉽다.

버텍스 버퍼로부터 렌더링 하면나무는, 버텍스 버퍼 메소드를 사용할 필요가 있다.

이 메소드는, 종래의 인터페이스로 사용된 메소드와는 달라,dwFlags 파라미터로 D3DDP_DONOTCLIP, D3DDP_DONOTLIGHT, 및 D3DDP_DONOTUPDATEEXTENTS 플래그를 받지 않는다. 이러한 플래그의 기능성은, 현재는 D3DRENDERSTATE_CLIPPING ,D3DRENDERSTATE_LIGHTING , 및 D3DRENDERSTATE_EXTENTS 렌더링 스테이트에 의해 사용할 수 있다.

소프트웨어 디바이스 (MMX 및 RGB 디바이스)는, 로컬 또는 비로컬일지 어떨지에 관계없이, 비디오 메모리로부터 버텍스 버퍼를 렌더링 할 수 없다. 소프트웨어 디바이스를 사용해 버텍스 버퍼를 렌더링 하려면 , 버텍스 버퍼가 시스템 메모리에 존재해야 한다. 하드웨어 디바이스는, 시스템 메모리 또는 비디오 메모리의 어느 쪽의 버텍스 버퍼로부터에서도, 렌더링 할 수가 있다.

버텍스 버퍼가 락 되고 있을 때는 렌더링 할 수 없다. 락 된 버텍스 버퍼를 사용해 IDirect3DDevice7::DrawIndexedPrimitiveVB 또는 IDirect3DDevice7::DrawPrimitiveVB 메소드를 호출하려고 하면 실패해,D3DERR_VERTEXBUFFERLOCKED 가 돌려주어진다.

IDirect3DDevice3 인터페이스에서는, 이 메소드는 종래의 IDirect3DVertexBuffer 인터페이스에의 포인터를 받았다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::DrawPrimitive ,IDirect3DDevice7::DrawPrimitiveStrided ,IDirect3DDevice7::DrawIndexedPrimitive ,IDirect3DDevice7::DrawIndexedPrimitiveStrided ,IDirect3DDevice7::DrawIndexedPrimitiveVB


IDirect3DDevice7::EndScene

IDirect3DDevice7::EndScene 메소드는,IDirect3DDevice7::BeginScene 메소드의 호출에 의해 시작 된 장면을 종료한다.

HRESULT EndScene();

파라미터

없음.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면 에러를 돌려준다.

주의

이 메소드가 성공하면(자), 장면이 렌더링 되어 렌더링 후의 장면이 디바이스 표면에 보관 유지된다.

장면의 렌더링이 정상적으로 시작 하고 있는 경우, 다른 장면의 렌더링을 시작 하기 위해서 IDirect3DDevice7::BeginScene 메소드를 호출하려면 , 그 전에 이 메소드를 호출할 필요가 있다(BeginScene 메소드의 호출이 실패하고 있는 경우는 장면의 렌더링은 시작 하고 있지 않기 때문에, 이 메소드를 호출할 필요는 없다).

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::BeginScene ,장면의 시작과 종료


IDirect3DDevice7::EndStateBlock

IDirect3DDevice7::EndStateBlock 메소드는, 디바이스 스테이트 블록의 기록을 정지해 스테이트 블록의 핸들을 취득하도록(듯이) Direct3D 에 지시한다.

HRESULT EndStateBlock(
  LPDWORD lpdwBlockHandle
);

파라미터

lpdwBlockHandle
기록을 종료하는 디바이스 스테이트 블록의 핸들을 저장 하는 변수의 주소. 이 값은,IDirect3DDevice7::ApplyStateBlock 및 IDirect3DDevice7::DeleteStateBlock 메소드로 사용된다.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

D3DERR_NOTINBEGINSTATEBLOCK
DDERR_INVALIDPARAMS

주의

이 메소드는 IDirect3DDevice7 인터페이스와 함께 도입되었다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::ApplyStateBlock ,IDirect3DDevice7::BeginStateBlock ,IDirect3DDevice7::CaptureStateBlock ,IDirect3DDevice7::CreateStateBlock ,IDirect3DDevice7::DeleteStateBlock ,스테이트 블록


IDirect3DDevice7::EnumTextureFormats

IDirect3DDevice7::EnumTextureFormats 메소드는, 지원 되고 있는 텍스쳐 포맷의 리스트에 대한 현재의 드라이버를 조사한다.

HRESULT EnumTextureFormats(
  LPD3DENUMPIXELFORMATSCALLBACK lpd3dEnumPixelProc,
  LPVOID lpArg
);

파라미터

lpd3dEnumPixelProc
열거 프로시저가 텍스쳐 포맷 마다 호출하는 D3DEnumPixelFormatsCallback 콜백 함수의 주소.
lpArg
콜백 함수에게 건네지는 어플리케이션 정의 데이터의 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

IDirect3DDevice2 인터페이스의 경우, 이 메소드는,D3DEnumPixelFormatsCallback 는 아니고, 종래의 D3DEnumTextureFormatsCallback 함수에의 포인터를 받는다.

이 메소드는, 일부의 디바이스에 새롭고 이행 된 텍스쳐 포맷을 열거할 수 없는 경우가 있다. 열거되지 않는 텍스쳐 포맷을 필요로 하는 어플리케이션에서는, 그 포맷의 표면을 생성 하려고 시도한다. 생성 할 수 있었을 경우는, 그 포맷이 지원 된다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.


IDirect3DDevice7::GetCaps

IDirect3DDevice7::GetCaps 메소드는, Direct3D 의 디바이스의 능력을 검색해 꺼낸다.

HRESULT GetCaps(
  LPD3DDEVICEDESC7 lpD3DDevDesc,
);

파라미터

lpD3DDevDesc
디바이스의 하드웨어 기능을 저장 하는 D3DDEVICEDESC7 구조체의 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는, 디스플레이 디바이스의 능력을 검색하지 않는다. 이 정보를 검색하려면 ,IDirectDraw7::GetCaps 메소드를 사용한다.

이 인터페이스의 구버젼의 경우, 이 메소드는 종래의 D3DDEVICEDESC 구조체에의 포인터를 받는 것으로, 하드웨어 추상 계층 (HAL) 디바이스 및 하드웨어 에뮬레이션 계층 (HEL)의 능력도 동시에 취득하고 있었다. IDirect3DDevice7 인터페이스에서는, 이 메소드는 메소드 호출을 하고 있는 디바이스의 능력만 취득한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.


IDirect3DDevice7::GetClipPlane

IDirect3DDevice7::GetClipPlane 메소드는, 디바이스의 유저 정의 클립면의 계수를 취득한다.

HRESULT GetClipPlane(
  DWORD dwIndex,
  D3DVALUE* pPlaneEquation
);

파라미터

dwIndex
평면 방정식의 계수를 취득하는 클립면의 인덱스.
pPlaneEquation
일반 평면 방정식에 대해 클립면의 계수를 나타내는 값의, 4 요소로 구성되는 배열의 주소. 「주의」를 참조할것.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면 DDERR_INVALIDPARAMS 를 돌려준다. 이 에러는,dwIndex 의 값이 디바이스로 지원 되는 최대 클립면인덱스를 넘고 있는지,pPlaneEquation 의 배열이 4 개의 부동 소수점값을 저장 할 만큼 크지 않은 것을 나타낸다.

주의

이 메소드로 취득하는 계수는, 일반 평면 방정식의 형태를 취한다. pPlaneEquation 의 배열의 값이 배열내에서의 순서에 A, B, C, 및 D 와 라벨 붙이고 되고 있는 경우, 이러한 값은 일반 평면 방정식이 Ax + By + Cz + D = 0 이 되도록(듯이) 적용된다. Ax + By + Cz + Dw >= 0 인 경우, 동차 좌표 (x, y, z, w)의 점은 면의 하프 공간에 표시된다. 클립 얼굴 또는 배후에 존재하는 점은 장면으로부터 클리핑 된다.

이 메소드로 사용되는 평면 방정식은 월드 공간에 존재해, 그 전에 호출하는 IDirect3DDevice7::SetClipPlane 메소드에 의해 설정된다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::SetClipPlane ,D3DRENDERSTATE_CLIPPLANEENABLE ,유저 정의 클립면


IDirect3DDevice7::GetClipStatus

IDirect3DDevice7::GetClipStatus 메소드는, 현재의 클립 스테이터스를 취득한다.

HRESULT GetClipStatus(
  LPD3DCLIPSTATUS lpD3DClipStatus
);

파라미터

lpD3DClipStatus
현재의 클립 스테이터스를 기술하는 D3DCLIPSTATUS 구조체의 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면 에러를 돌려준다. 이 메소드는, 인수의 1 개가 무효인 경우에는,DDERR_INVALIDPARAMS 를 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::SetClipStatus


IDirect3DDevice7::GetDirect3D

IDirect3DDevice7::GetDirect3D 메소드는, 이 디바이스의 Direct3D 오브젝트를 검색해 꺼낸다.

HRESULT GetDirect3D(
  LPDIRECT3D7 *lplpD3D
);

파라미터

lplpD3D
메소드가 돌아갔을 때에, Direct3D 오브젝트의 IDirect3D7 인터페이스에의 포인터를 받는 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 직접 모드의 반환값」을 참조할것.

주의

이 인터페이스의 구버젼에서는, 이 메소드는 종래의 IDirect3D3 인터페이스에의 포인터를 받았다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.


IDirect3DDevice7::GetInfo

IDirect3DDevice7::GetInfo 메소드는, 렌더링 디바이스 정보를 취득한다. 이 정보는, Direct3D 관련 또는 기본이 되는 디바이스 드라이버에 관련하는 것이다.

HRESULT GetInfo(
  DWORD  dwDevInfoID,
  LPVOID pDevInfoStruct,
  DWORD  dwSize
);

파라미터

dwDevInfoID
pDevInfoStruct 의 디바이스 정보의 구조체의 타입을 나타내는 플래그. 이 파라미터는, 이하의 플래그의 어느 쪽인가에 설정할 수 있다.
D3DDEVINFOID_TEXTUREMANAGER
pDevInfoStruct 의 구조체는, 드라이버로 행해지는 텍스쳐 관리에 대한 정보를 저장 하는 D3DDEVINFO_TEXTUREMANAGER 구조체이다. 드라이버로 텍스쳐 관리를 하지 않은 경우는, Direct3D 에 의한 텍스쳐 관리에 대한 정보가 취득된다.
D3DDEVINFOID_D3DTEXTUREMANAGER
pDevInfoStruct 의 구조체는, Direct3D 에 의한 텍스쳐 관리에 대한 정보를 저장 하는 D3DDEVINFO_TEXTUREMANAGER 구조체이다.
D3DDEVINFOID_TEXTURING
pDevInfoStruct 의 구조체는, 어플리케이션의 텍스쳐 처리 액티버티에 대한 정보를 저장 하는 D3DDEVINFO_TEXTURING 구조체이다.
pDevInfoStruct
호출이 성공했을 경우에, 지정된 디바이스 정보를 받는 구조체의 주소. 구조체의 타입 및 저장 된 데이터의 해석 방법은,dwDevInfoID 의 플래그에 의해 정해진다.
dwSize
pDevInfoStruct 의 구조체의 바이트 단위에서의 사이즈.

반환값

성공하면 D3D_OK 를 돌려준다. 이 메소드는, DirectX 의 리테일 빌드로 S_FALSE 를 돌려준다.

실패하면, 다음의 몇개의 에러값을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드를 사용 하면, 드라이버에서는 특정의 종류의 정보 및 거기에 대응하는 구조체를 선언할 수 있다. 이것들에 대해서는, 이 SDK 에서는 설명되어 있지 않다.

이 메소드는 동기 해 실행되지만, 이 실행 속도가 늦은 경우는 어플리케이션의 퍼포먼스가 저하하는 일이 있다. 장면의 렌더링중 (IDirect3DDevice7::BeginScene 를 호출하고 나서 IDirect3DDevice7::EndScene 를 호출할 때까지)은, 이 메소드를 호출해서는 안 된다.

이 메소드는, 제품 개발시의 퍼포먼스 추적 및 디버그에 사용한다 (DirectX 의 디버그 버젼). 이 메소드가 성공해 S_FALSE 를 돌려주어도, 디바이스 데이터를 취득하고 있지 않을 때가 있다. 호스트 시스템에 DirectX 런타임의 리테일 버젼이 인스톨 되고 있는 경우에는, 이러한 일이 일어난다.

동작환경

Windows NT:Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

D3DDEVINFO_TEXTUREMANAGER


IDirect3DDevice7::GetLight

IDirect3DDevice7::GetLight 메소드는, 이 디바이스로 사용하는 일련의 라이트 프로퍼티를 취득한다.

HRESULT GetLight(
  DWORD dwLightIndex,
  LPD3DLIGHT7 lpLight
);

파라미터

dwLightIndex
취득하는 라이트 프로퍼티 세트의 제로 베이스 인덱스.
lpLight
취득한 라이팅 파라미터 세트를 저장 하는 D3DLIGHT7 구조체의 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면 에러를 돌려준다. lpLight 파라미터가 무효인 경우, 이 메소드는 DDERR_INVALIDPARAMS 를 돌려준다.

주의

이 메소드는 IDirect3DDevice7 인터페이스와 함께 도입되었다.

구인터페이스와는 달라,IDirect3DDevice7 인터페이스는 라이팅 오브젝트를 사용하지 않는다. 이 메소드, 및 이 메소드에 있어서의 라이트 프로퍼티 세트를 기술하는 D3DLIGHT7 구조체는, 구버젼의 디바이스 인터페이스에서의 라이팅 의미들에 대신하는 것이다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::SetLight ,IDirect3DDevice7::GetLightEnable ,IDirect3DDevice7::LightEnable


IDirect3DDevice7::GetLightEnable

IDirect3DDevice7::GetLightEnable 메소드는, 디바이스내의 라이팅 파라미터 세트의 액티버티 스테이터스 (유효/무효)를 취득한다.

HRESULT GetLightEnable(
  DWORD dwLightIndex,
  BOOL* pbEnable
);

파라미터

dwLightIndex
이 메소드의 대상이 되는 라이팅 파라미터 세트의 제로 베이스 인덱스.
pbEnable
지정된 라이팅 파라미터의 스테이터스를 저장 하는 변수의 주소. 호출의 뒤, 이 주소의 값이 제로 이외의 경우는, 지정된 라이팅 파라미터가 유효한 것을 나타내, 0 의 경우는 무효라는 점을 나타낸다.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면 에러를 돌려준다. Direct3D 직접 모드의 에러의 일람 및 그 설명에 대해서는, 「반환값」을 참조할것.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::GetLight ,IDirect3DDevice7::LightEnable ,IDirect3DDevice7::SetLight


IDirect3DDevice7::GetMaterial

IDirect3DDevice7::GetMaterial 메소드는, 디바이스의 현재의 머트리얼 프로퍼티를 취득한다.

HRESULT GetMaterial(
  LPD3DMATERIAL7 lpMaterial
);

파라미터

lpMaterial
현재 설정되어 있는 머트리얼 프로퍼티를 저장 하는 D3DMATERIAL7 구조체의 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면 에러를 돌려준다. lpMaterial 파라미터가 무효인 경우, 이 메소드는 DDERR_INVALIDPARAMS 을 돌려준다.

주의

이 메소드는 IDirect3DDevice7 인터페이스와 함께 도입되었다.

구인터페이스와는 달라,IDirect3DDevice7 인터페이스는 머트리얼의 핸들을 사용하지 않는다. 이 메소드, 및 이 메소드에 있어서의 머트리얼 프로퍼티를 기술하는 D3DMATERIAL7 구조체는, 구버젼의 디바이스 인터페이스에서의 머트리얼 핸들의 의미들에 대신하는 것이다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::SetMaterial


IDirect3DDevice7::GetRenderState

IDirect3DDevice7::GetRenderState 메소드는, 단일의 Direct3DDevice 렌더링 스테이트 파라미터를 취득한다.

HRESULT GetRenderState(
  D3DRENDERSTATETYPE dwRenderStateType,
  LPDWORD lpdwRenderState
);

파라미터

dwRenderStateType
조사 대상의 디바이스 스테이트 변수. 이 파라미터는,D3DRENDERSTATETYPE 열거형의 임의의 멤버로 할 수 있다.
lpdwRenderState
메소드가 돌아갔을 때에, Direct3DDevice 렌더링 스테이트를 받는 변수의 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면 에러를 돌려준다. 이 메소드는, 인수의 1 개가 무효인 경우에는,DDERR_INVALIDPARAMS 를 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::SetRenderState


IDirect3DDevice7::GetRenderTarget

IDirect3DDevice7::GetRenderTarget 메소드는, 렌더링의 대상으로 해 이용되는 DirectDraw 표면에의 포인터를 검색해 꺼낸다.

HRESULT GetRenderTarget(
  LPDIRECTDRAWSURFACE7 *lplpRenderTarget
);

파라미터

lplpRenderTarget
이 디바이스에 있어서의 렌더링 타겟 표면의 IDirectDrawSurface7 인터페이스에의 포인터를 받는 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면 에러를 돌려준다. 이 메소드는, 인수의 1 개가 무효인 경우에는,DDERR_INVALIDPARAMS 를 돌려준다.

주의

IDirect3DDevice3 인터페이스에서는, 이 메소드는 종래의 IDirectDrawSurface4 인터페이스에의 포인터를 받았다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::SetRenderTarget


IDirect3DDevice7::GetStateData

IDirect3DDevice7::GetStateDate 메소드는 이행되어 있지 않다.

HRESULT GetStateData(
  DWORD dwState,
  LPVOID* lplpStateData
);

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.


IDirect3DDevice7::GetTexture

IDirect3DDevice7::GetTexture 메소드는, 디바이스의, 지정의 스테이지에 할당할 수 있었던 텍스쳐를 검색해 꺼낸다.

HRESULT GetTexture(
  DWORD dwStage,
  LPDIRECTDRAWSURFACE7 * lplpTexture
);

파라미터

dwStage
검색해 꺼내는 텍스쳐의 스테이지 식별자. 스테이지 식별자는 제로를 베이스로 한다. 현재, 디바이스는 최대 8 세트까지 텍스쳐를 가질 수가 있다. 따라서,dwStage 에 허용 되는 최대치는 7 이다.
lplpTexture
호출이 성공했을 때에, 지정된 텍스쳐의 IDirectDrawSurface7 인터페이스에의 포인터를 저장 하는 변수의 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

종래의 IDirect3DDevice3 인터페이스에서는, 이 메소드는 IDirect3DTexture2 인터페이스에의 포인터를 받는다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::SetTexture ,IDirect3DDevice7::GetTextureStageState ,IDirect3DDevice3::SetTextureStageState ,텍스쳐


IDirect3DDevice7::GetTextureStageState

IDirect3DDevice7::GetTextureStageState 메소드는, 현재 할당할 수 있고 있는 텍스쳐 스테이트값을 검색해 꺼낸다.

HRESULT GetTextureStageState(
  DWORD   dwStage,
  D3DTEXTURESTAGESTATETYPE dwState,
  LPDWORD lpdwValue
);

파라미터

dwStage
스테이트를 취득하는 대상이 되는 텍스쳐의 스테이지 식별자. 스테이지 식별자는 제로를 베이스로 한다. 현재, 디바이스는 최대 8 세트까지 텍스쳐를 가질 수가 있다. 따라서,dwStage 로 허용 되는 최대치는 7 이다.
dwState
검색되고 꺼내지는 텍스쳐의 스테이트. 이 파라미터는,D3DTEXTURESTAGESTATETYPE 열거형의 임의의 멤버로 할 수 있다.
lpdwValue
취득한 스테이트값을 저장 하는 변수의 주소. 꺼내진 값의 의미는 dwState 파라미터로 정해진다.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::SetTextureStageState ,IDirect3DDevice7::GetTexture ,IDirect3DDevice7::SetTexture ,텍스쳐


IDirect3DDevice7::GetTransform

IDirect3DDevice7::GetTransform 메소드는, 트랜스 폼 스테이트를 기술하는 행렬을 취득한다.

HRESULT GetTransform(
  D3DTRANSFORMSTATETYPE dtstTransformStateType,
  LPD3DMATRIX lpD3DMatrix
);

파라미터

dtstTransformStateType
변경 대상의 디바이스 스테이트 변수. 이 파라미터에는,D3DTRANSFORMSTATETYPE 열거형의 임의의 멤버를 설정할 수 있다.
lpD3DMatrix
트랜스 폼을 기술하는 D3DMATRIX 구조체의 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면 에러를 돌려준다. 이 메소드는, 인수의 1 개가 무효인 경우에는,DDERR_INVALIDPARAMS 를 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::SetTransform


IDirect3DDevice7::GetViewport

IDirect3DDevice7::GetViewport 메소드는, 디바이스에 현재 설정되어 있는 뷰포트 파라미터를 취득한다.

HRESULT GetViewport(
  LPD3DVIEWPORT7 lpViewport
);

파라미터

lpViewport
호출이 성공했을 경우에, 현재의 뷰포트 파라미터를 저장 하는 D3DVIEWPORT7 구조체의 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면 에러를 돌려준다. lpViewport 파라미터가 무효인 경우, 이 메소드는 DDERR_INVALIDPARAMS 를 돌려준다.

주의

이 메소드는 IDirect3DDevice7 인터페이스와 함께 도입되었다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::SetViewport


IDirect3DDevice7::LightEnable

IDirect3DDevice7::LightEnable 메소드는, 디바이스내의 라이팅 파라미터 세트를 유효 또는 무효로 한다.

HRESULT LightEnable(
  DWORD dwLightIndex,
  BOOL bEnable
);

파라미터

dwLightIndex
이 메소드의 대상이 되는 라이팅 파라미터 세트의 제로 베이스 인덱스.
bEnable
라이팅 파라미터 세트가 유효 또는 무효의 머지않아인지를 나타내는 값. 이 파라미터에 TRUE 를 설정 하면, 지정된 인덱스의 파라미터의 라이트가 유효하게 되어, FALSE 를 설정 하면 무효가 된다.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면 에러를 돌려준다. Direct3D 직접 모드의 에러값의 일람 및 그 설명에 대해서는, 「반환값」을 참조할것.

주의

dwLightIndex 의 값을 디바이스내에서 현재 할당할 수 있고 있는 라이트 프로퍼티의 범위외의 값으로 설정 하면,LightEnable 메소드는 이하의 프로퍼티로 라이트를 생성 해, 유효한 스테이트를 bEnable 로 지정된 값으로 설정한다.

Member | 디폴트
dltType | D3DLIGHT_DIRECTIONAL
dcvDiffuse | (R:1, G:1, B:1, A:0)
dcvSpecular | (R:0, G:0, B:0, A:0)
dcvAmbient | (R:0, G:0, B:0, A:0)
dvPosition | (0, 0, 0)
dvDirection | (0, 0, 1)
dvRange | 0
dvFalloff | 0
dvAttenuation0 | 0
dvAttenuation1 | 0
dvAttenuation2 | 0
dvTheta | 0
dvPhi | 0

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::GetLight ,IDirect3DDevice7::GetLightEnable ,IDirect3DDevice7::SetLight ,라이팅과 머트리얼


IDirect3DDevice7::Load

IDirect3DDevice7::Load 메소드는, 목적지 텍스쳐의 지정된 포인트 또는 큐브 환경 맵의 면에, 전송원텍스쳐의 직사각형 영역을 로드한다.

HRESULT Load(
  LPDIRECTDRAWSURACE7 lpDestTex,
  LPPOINT lpDestPoint,
  LPDIRECTDRAWSURACE7 lpSrcTex,
  LPRECT lprcSrcRect,
  DWORD dwFlags
);

파라미터

lpDestTex
전송원텍스쳐로부터 화면 데이터를 받는 텍스쳐의 IDirectDrawSurface7 인터페이스의 주소. 목적지 텍스쳐는 큐브 환경 맵이라도 좋다. 큐브 환경 맵이나 밉맵등의 복합 텍스쳐의 경우, 이 파라미터는 최상정도 표면을 포인트 해야 한다.
lpDestPoint
이 메소드로 화면 데이터를 목적지 텍스쳐에 로드할 때의 포인트를 기술하는 POINT 구조체의 주소. 목적지 포인트를 목적지 텍스쳐의 원점으로 하는 경우는, 이 파라미터를 NULL 로 설정한다.
lpSrcTex
로드하는 화면 데이터를 저장 하는 텍스쳐의 IDirect3DTexture7 인터페이스의 주소. 큐브 환경 맵이나 밉맵등의 복합 텍스쳐의 경우, 이 파라미터는 최상정도 표면을 포인트 해야 한다.
lprcSrcRect
메소드로 로드하는 전송원텍스쳐내의 영역을 기술하는 RECT 구조체의 주소. 전송원직사각형이 전송원텍스쳐 전체를 포함한 경우는, 이 파라미터를 NULL 로 설정한다.
dwFlags
큐브 환경 맵의 경우, 화면 데이터를 받는 목적지 텍스쳐의 면을 나타내는 값. 이 파라미터에는, 이하의 플래그의 편성을 설정할 수 있다.
0
목적지 텍스쳐가 관리하의 텍스쳐의 경우에 필요.
DDSCAPS2_CUBEMAP_ALLFACES
전송원텍스쳐내의 화면 데이터를 모든 면에 로드한다.
DDSCAPS2_CUBEMAP_NEGATIVEX,DDSCAPS2_CUBEMAP_NEGATIVEY, 및 DDSCAPS2_CUBEMAP_NEGATIVEZ
부방향의 x, y, 또는 z 면에 화면 데이터를 로드한다.
DDSCAPS2_CUBEMAP_POSITIVEX, DDSCAPS2_CUBEMAP_POSITIVEY, or DDSCAPS2_CUBEMAP_POSITIVEZ
정방향의 x, y, 또는 z 면에 화면 데이터를 로드한다.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

목적지 텍스쳐는, 이것을 생성 한 렌더링 디바이스 뿐만 아니라, 어느 렌더링 디바이스에서도 사용할 수 있다. 하드웨어 디바이스에서는, 로드 처리는 하드웨어 가속화로 실행된다.

텍스쳐를 비디오 메모리에 로드하는 경우는, 블리트 처리로 실시하는 것보다도 이 메소드를 호출하는 것이 좋다.

이 메소드는, 모든 밉레벨, 큐브 맵면, 팔레트, 및 컬러 키를 전송원텍스쳐로부터 목적지 텍스쳐에 카피한다.

이 메소드를 사용해 밉맵을 로드하는 경우는, 이하의 특별 사항이 적용된다.

  • 목적지 텍스쳐는, 전송원텍스쳐에 저장 된 밉레벨의 서브 세트라도 좋다. 이 경우, 양쪽 모두의 텍스쳐에 공통의 밉레벨만 카피된다. 이것은, 텍스쳐 LOD 를 이행 하는 경우에 편리하다. 2 개의 밉레벨만 사용해 비디오 메모리 텍스쳐를 생성 해, 다음에 이 메소드를 사용해, 밉레벨 전체를 구성하는 전송원텍스쳐로부터 2 개의 레벨을 카피할 수 있다.
  • 전송원 및 목적지 표면의 포인터는, 최상정도 표면을 포인트 해야 한다.
  • 밉맵의 서브 직사각형을 로드하는 경우, 서브 직사각형은 밉맵 체인의 최상정도 표면을 참조해, 각각의 하위 밉레벨에 대해서 2 개로 분할된다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.


IDirect3DDevice7::MultiplyTransform

IDirect3DDevice7::MultiplyTransform 메소드는, 디바이스의 월드 행렬, 뷰 행렬, 또는 투영 행렬에, 지정된 행렬을 곱셈한다. 곱셈의 순서는,lpD3Dmatrix 거는 dtstTransformStateType 이다.

HRESULT MultiplyTransform(
  D3DTRANSFORMSTATETYPE dtstTransformStateType,
  LPD3DMATRIX lpD3DMatrix
);

파라미터

dtstTransformStateType
변경하는 디바이스 행렬을 지정하는 D3DTRANSFORMSTATETYPE 열거형의 멤버. 가장 일반적인 설정은 D3DTRANSFORMSTATE_WORLD 로, 월드 행렬을 변경하지만, 필요하면, 뷰 행렬이나 투영 행렬을 변경하도록(듯이) 지정할 수도 있다.
lpD3DMatrix
현재의 트랜스 폼을 변경하는 D3DMATRIX 구조체의 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면 에러를 돌려준다. 이 메소드는, 인수의 1 개가 무효인 경우에는,DDERR_INVALIDPARAMS 를 돌려준다.

주의

어플리케이션이, 트랜스 폼의 계층 구조를 사용해 동작하기 위해서,MultiplyTransform 메소드를 사용하는 일도 생각할 수 있다. 예를 들어, 팔을 나타내는 지오메트리와 트랜스 폼은, 이하의 계층에서 구성하는 일도 있다.

shoulder_transformation
    upper_arm geometry
    elbow transformation
        lower_arm geometry
        wrist transformation
            hand geometry

어플리케이션에서는, 이 계층을 렌더링 하기 위해서 이하의 일련의 호출을 실시할 수가 있다 (이 코드에서는 일부의 파라미터만 가리킨다).

IDirect3DDevice7::SetTransform(D3DTRANSFORMSTATE_WORLD,
    shoulder_transform)
IDirect3DDevice7::DrawPrimitive(upper_arm)
IDirect3DDevice7::MultiplyTransform(D3DTRANSFORMSTATE_WORLD,
    elbow_transform)
IDirect3DDevice7::DrawPrimitive(lower_arm)
IDirect3DDevice7::MultiplyTransform(D3DTRANSFORMSTATE_WORLD,
    wrist_transform)
IDirect3DDevice7::DrawPrimitive(hand)

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::DrawPrimitive ,IDirect3DDevice7::SetTransform


IDirect3DDevice7::PreLoad

IDirect3DDevice7::Preload 메소드는, Direct3D 텍스쳐 매니저에 관리하의 텍스쳐를 비디오 메모리에 로드하도록 지시한다.

HRESULT PreLoad(
  LPDIRECTDRAWSURFACE7 lpddsTexture
);

파라미터

lpddsTexture
메모리에 로드하는 텍스쳐의 IDirectDrawSurface7 인터페이스의 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는, 관리하의 텍스쳐를 비디오 메모리에 강제적으로 로드한다. 사용할 수 있는 비디오 메모리가 충분히 없는 경우, 시스템은 그 외의 텍스쳐를 삭제해 메모리를 확보한 후, 텍스쳐를 로드한다. 로드하는 텍스쳐는 관리하의 텍스쳐가 아니면 안된다 (DDSCAPS2_TEXTUREMANAGE 또는 DDSCAPS2_D3DTEXTUREMANAGE 플래그로 생성 된 것). 이외의 경우에는, 메소드는 실패해,DDERR_INVALIDPARAMS 를 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

자동 텍스쳐 관리


IDirect3DDevice7::SetClipPlane

IDirect3DDevice7::SetClipPlane 메소드는, 디바이스의 유저 정의 클립면의 계수를 설정한다.

HRESULT SetClipPlane(
  DWORD dwIndex,
  D3DVALUE* pPlaneEquation
);

파라미터

dwIndex
평면 방정식의 계수를 설정하는 클립면의 인덱스.
pPlaneEquation
일반 평면 방정식에 있어서의 클립면계수를 나타내는 값을 저장 하는, 4 요소로 구성되는 배열의 주소. 「주의」를 참조할것.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면 DDERR_INVALIDPARAMS 를 돌려준다. 이 에러는,dwIndex 의 값이 디바이스에 의해 지원 되는 최대 클립면인덱스를 넘고 있는지,pPlaneEquation 의 배열이 4 개의 부동 소수점값을 저장 할 만큼 크지 않은 것을 나타낸다.

주의

이 메소드로 설정하는 계수는, 일반 평면 방정식의 형태를 취한다. pPlaneEquation 의 배열의 값이 배열내에서의 순서에 A, B, C, 및 D 와 라벨 붙이고 되고 있는 경우, 이러한 값은 일반 평면 방정식이 Ax + By + Cz + D = 0 이 되도록(듯이) 적용된다. Ax + By + Cz + Dw >= 0 인 경우, 동차 좌표 (x, y, z, w)의 점은 평면의 하프 공간에 표시된다. 클립 얼굴 또는 배후에 존재하는 점은 장면으로부터 클리핑 된다.

이 메소드로 사용되는 평면 방정식은, 월드 공간에 존재한다.

이 메소드는, 설정된 클립면의 평면 방정식을 유효하게는 하지 않는다. 클립면을 유효하게 하려면 ,DWORD 값의 대응하는 비트를 D3DRENDERSTATE_CLIPPLANEENABLE 렌더링 스테이트로 설정한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::GetClipPlane ,D3DRENDERSTATE_CLIPPLANEENABLE ,유저 정의 클립면


IDirect3DDevice7::SetClipStatus

IDirect3DDevice7::SetClipStatus 메소드는, 현재의 클립 스테이터스를 설정한다.

HRESULT SetClipStatus(
  LPD3DCLIPSTATUS lpD3DClipStatus
);

파라미터

lpD3DClipStatus
클립 스테이터스의 새로운 설정값을 기술하는 D3DCLIPSTATUS 구조체의 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면 에러를 돌려준다. 이 메소드는, 인수의 1 개가 무효인 경우에는,DDERR_INVALIDPARAMS 를 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::GetClipStatus


IDirect3DDevice7::SetLight

IDirect3DDevice7::SetLight 메소드는, 이 디바이스의 라이트 프로퍼티 세트를 할당한다.

HRESULT SetLight(
  DWORD dwLightIndex,
  LPD3DLIGHT7 lpLight
);

파라미터

dwLightIndex
설정하는 라이트 프로퍼티 세트의 제로 베이스 인덱스. 인덱스에 이미 라이트 프로퍼티 세트가 존재하는 경우,lpLight. 의 새로운 프로퍼티로 덧쓰기된다.
lpLight
설정하는 라이팅 파라미터를 저장 하는 D3DLIGHT7 구조체의 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

주의

이 메소드는 IDirect3DDevice7 인터페이스와 함께 도입되었다.

종래의 인터페이스와는 달라,IDirect3DDevice7 인터페이스는 라이팅 오브젝트를 사용하지 않는다. 이 메소드, 및 이 메소드에 있어서의 라이트 프로퍼티 세트를 기술하는 D3DLIGHT7 구조체는, 구버젼의 디바이스 인터페이스에서의 라이팅 의미들에 대신하는 것이다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::GetLight ,IDirect3DDevice7::GetLightEnable ,IDirect3DDevice7::LightEnable


IDirect3DDevice7::SetMaterial

IDirect3DDevice7::SetMaterial 메소드는, 디바이스의 머트리얼 프로퍼티를 설정한다.

HRESULT SetMaterial(
  LPD3DMATERIAL7 lpMaterial
);

파라미터

lpMaterial
설정하는 머트리얼 프로퍼티를 기술하는 D3DMATRIAL7 구조체의 주소.

반환값

성공하면 D3D_OK 돌려준다.

실패하면 에러를 돌려준다. lpMaterial 파라미터가 무효인 경우, 이 메소드는 DDERR_INVALIDPARAMS 를 돌려준다.

주의

이 메소드는 IDirect3DDevice7 인터페이스와 함께 도입되었다.

종래의 인터페이스와는 달라,IDirect3DDevice7 인터페이스는 머트리얼 핸들을 사용하지 않는다. 이 메소드, 및 이 메소드에 있어서의 머트리얼 프로퍼티를 기술하는 D3DMATERIAL7 구조체는, 구버젼의 디바이스 인터페이스에서의 머트리얼 핸들의 의미들에 대신하는 것이다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::GetMaterial


IDirect3DDevice7::SetRenderState

IDirect3DDevice7::SetRenderState 메소드는, 단일의 Direct3DDevice 렌더링 스테이트 파라미터를 설정한다.

HRESULT SetRenderState(
  D3DRENDERSTATETYPE dwRenderStateType,
  DWORD dwRenderState
);

파라미터

dwRenderStateType
변경 대상의 디바이스 스테이트 변수. 이 파라미터는,D3DRENDERSTATETYPE 열거형의 임의의 멤버로 할 수 있다.
dwRenderState
Direct3D 디바이스 렌더링 스테이트의 새로운 값. 이 파라미터의 의미는,dwRenderStateType 의 지정값에 의존한다. 예를 들어,dwRenderStateType 가 D3DRENDERSTATE_SHADEMODE 인 경우, 제 2 파라미터는 D3DSHADEMODE 열거형의 멤버의 어느 쪽인가에 된다.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면 에러를 돌려준다. 이 메소드는, 인수의 1 개가 무효인 경우,DDERR_INVALIDPARAMS 를 돌려준다.

주의

텍스쳐 스테이트를 설정하려면 , 종래의 텍스쳐 관련 렌더링 스테이트는 아니고,IDirect3DDevice7::SetTextureStageState 메소드를 사용한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::GetRenderState ,IDirect3DDevice7::SetTransform ,렌더링 스테이트에 대해


IDirect3DDevice7::SetRenderTarget

IDirect3DDevice7::SetRenderTarget 메소드는, 렌더링 타겟으로서 새로운 DirectDraw 표면의 방향으로, 렌더링 출력을 간단하게 지정하는 것을 어플리케이션에 허가한다.

HRESULT SetRenderTarget(
  LPDIRECTDRAWSURFACE7 lpNewRenderTarget,
  DWORD dwFlags
);

파라미터

lpNewRenderTarget
새로운 렌더링 타겟이 되는 표면 오브젝트의 IDirectDrawSurface7 인터페이스의 주소. 이 표면은 DDSCAPS_3DDEVICE 능력과 함께, 생성되지 않으면 안 된다.
dwFlags
현재는 사용되어 있지 않다. 제로를 설정한다.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면 에러를 돌려준다. 에러는 다음의 값의 언젠가이다.

DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE

주의

현재의 렌더링 타겟으로 깊이 버퍼가 없는 경우, 깊이 버퍼가 있는 새로운 렌더링 타겟 표면을 설정하기 위해서 이 메소드를 사용할 수 없다. 같이 이 메소드는, 깊이 버퍼가 없는 렌더링 타겟으로부터 깊이 버퍼가 있는 렌더링 타겟으로 바꾸기 위해서(때문에) 사용하는 일도 할 수 없다. 이러한 처리를 실행하려고 하면(자) 디버그 빌드로 실패해, 리테일 빌드에서는 신뢰할 수 없는 동작이 발생하는 일이 있다. 신구의 렌더링 타겟에서는 모두 깊이 버퍼를 사용하기 위해(때문에), 새로운 렌더링 타겟으로 깊이 버퍼를 Attach 하면, 그 깊이 버퍼는 내용이 낡은 깊이 버퍼를 옮겨놓는다.

종래의 인터페이스에 있어서의 이 메소드의 이행과는 달라,IDirect3DDevice7::SetRenderTarget 는 디바이스의 현재의 머트리얼 또는 뷰포트를 무효로 하지 않는다.

능력은, 렌더링 타겟 표면의 프로퍼티의 변화에 따라서는 변함없다. Direct3D HAL 및 소프트웨어 래스터라이저는, 어플리케이션에 대해서 한 번만 능력을 공개한다. 시스템은, 목적의 표면의 포맷에 의해 다른 능력 세트를 제시할 수 없다.

복수의 깊이 버퍼가 렌더링 타겟으로 Attach 되고 있으면(자), 이 함수는 실패한다.

IDirect3DDevice3 인터페이스에서는, 이 메소드는 종래의 IDirect3DrawSurface4 인터페이스에의 포인터를 받았다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::GetRenderTarget


IDirect3DDevice7::SetStateData

IDirect3DDevice7::SetStateData 메소드는 이행되어 있지 않다.

HRESULT SetStateData(
  DWORD dwState,
  LPVOID lpStateData
);

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.


IDirect3DDevice7::SetTexture

IDirect3DDevice7::SetTexture 메소드는, 텍스쳐를, 디바이스의 지정된 스테이지에 할당한다.

HRESULT SetTexture(
  DWORD dwStage,
  LPDIRECTDRAWSURFACE7 lpTexture
);

파라미터

dwStage
텍스쳐를 설정하는 스테이지 식별자. 스테이지 식별자는 0 으로부터 시작된다. 현재, 디바이스는 최대 8 세트까지 텍스쳐를 가질 수가 있다. 따라서,dwStage 로 지정할 수 있는 최대치는 7 이다.
lpTexture
설정하는 텍스쳐의 IDirectDrawSurfece7 인터페이스의 주소. 밉맵이나 큐브 환경 맵등의 복합 텍스쳐의 경우, 이 파라미터는 최상정도 표면을 포인트 해야 한다.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는, 할당할 수 있고 있는 텍스쳐 표면의 참조 카운트를 인크리먼트(increment) 한다. 텍스쳐가 불필요하게 되었을 경우는, 해당하는 스테이지의 텍스쳐를 NULL 로 설정해야 한다. 이것을 실시하지 않으면 표면이 릴리즈 되지 않고 메모리 누수가 발생한다.

소프트웨어 디바이스는, 1 개의 텍스쳐를 한 번에 복수의 텍스쳐 스테이지에 할당하는 것은 지원 하고 있지 않다.

IDirect3DDevice3 인터페이스에서는, 이 메소드는 IDirect3DTexture2 인터페이스에의 포인터를 사용한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::GetTexture ,IDirect3DDevice7::GetTextureStageState ,IDirect3DDevice7::SetTextureStageState ,텍스쳐


IDirect3DDevice7::SetTextureStageState

IDirect3DDevice7::SetTextureStageState 메소드는, 현재 할당할 수 있고 있는 텍스쳐의 스테이트값을 설정한다.

HRESULT SetTextureStageState(
  DWORD dwStage,
  D3DTEXTURESTAGESTATETYPE dwState,
  DWORD dwValue
);

파라미터

dwStage
스테이트값을 설정하는 텍스쳐의 스테이지 식별자. 스테이지 식별자는 0 으로부터 시작된다. 현재, 디바이스는 최대 8 세트까지 텍스쳐를 가질 수가 있다. 따라서,dwStage 로 지정할 수 있는 최대치는 7 이다.
dwState
설정하는 텍스쳐 스테이트. 이 파라미터는,D3DTEXTURESTAGESTATETYPE 열거형의 임의의 멤버로 할 수 있다.
dwValue
설정하는 스테이트값. 이 값의 의미는 dwState 파라미터로 정해진다.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

텍스쳐 스테이트의 설정에는 이 메소드를 사용해, 종래의 텍스쳐 관련 렌더링 스테이트는 사용하지 않는다. 상세한 것에 대하여는, 「렌더링 스테이트에 대하며」를 참조할것.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::GetTextureStageState ,IDirect3DDevice7::GetTexture ,IDirect3DDevice7::SetTexture ,텍스쳐


IDirect3DDevice7::SetTransform

IDirect3DDevice7::SetTransform 메소드는, 단일의 Direct3D 디바이스의 트랜스 폼 관련 스테이트를 설정한다.

HRESULT SetTransform(
  D3DTRANSFORMSTATETYPE dtstTransformStateType,
  LPD3DMATRIX lpD3DMatrix
);

파라미터

dtstTransformStateType
변경 대상의 디바이스 스테이트 변수. 이 파라미터에는,D3DTRANSFORMSTATETYPE 열거형의 어느 멤버에서도 설정할 수 있다.
lpD3DMatrix
현재의 트랜스 폼을 변경하는 D3DMATRIX 구조체의 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면 에러를 돌려준다. 이 메소드는, 인수의 1 개가 무효인 경우에는,DDERR_INVALIDPARAMS 를 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::GetTransform ,IDirect3DDevice7::SetRenderState


IDirect3DDevice7::SetViewport

IDirect3DDevice7::SetViewport 메소드는, 디바이스의 뷰포트 파라미터를 설정한다.

HRESULT SetViewport(
  LPD3DVIEWPORT7 lpViewport
);

파라미터

lpViewport
설정하는 뷰포트 파라미터를 저장 하는 D3DVIEWPORT7 구조체의 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면 에러를 돌려준다. lpViewport 파라미터가 무효인 경우, 이 메소드는 DDERR_INVALIDPARAMS 를 돌려준다.

주의

이 메소드는 IDirect3DDevice7 인터페이스와 함께 도입되었다.

D3DVIEWPORT7 구조체로 기술하는 뷰포트 파라미터가, 렌더링 타겟 표면내에 존재할 수 없는 영역을 기술하고 있는 경우, 메소드는 실패해,DDERR_INVALIDPARAMS 를 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::GetViewport


IDirect3DDevice7::ValidateDevice

IDirect3DDevice7::ValidateDevice 메소드는, 현재 설정되어 있는 텍스쳐의 블렌딩 조작과 인수에 대해, 디바이스가 1 회의 처리로 렌더링 할 수 있는 능력을 보고한다.

HRESULT ValidateDevice(
  LPDWORD lpdwPasses
);

파라미터

lpdwPasses
멀티 패스 렌더링에 의해 희망의 이펙트를 완성하기 위한 렌더링 패스의 수를 저장 하는 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
D3DERR_CONFLICTINGTEXTUREFILTER
D3DERR_CONFLICTINGTEXTUREPALETTE
D3DERR_TOOMANYOPERATIONS
D3DERR_UNSUPPORTEDALPHAARG
D3DERR_UNSUPPORTEDALPHAOPERATION
D3DERR_UNSUPPORTEDCOLORARG
D3DERR_UNSUPPORTEDCOLOROPERATION
D3DERR_UNSUPPORTEDFACTORVALUE
D3DERR_UNSUPPORTEDTEXTUREFILTER
D3DERR_WRONGTEXTUREFORMAT

주의

현재의 하드웨어가, 반드시 조작과 인수의 가능한 모든 편성을 이행 하고 있을 필요는 없다. 특정의 블렌딩 조작이 주어진 인수로 완성될지 어떨지는, 필요한 블렌딩 조작을 설정해,ValidateDevice 메소드를 호출하는 것으로 확인할 수가 있다.

ValidateDevice 메소드는, 현재 설정되어 있는 렌더링 스테이트, 텍스쳐, 텍스쳐 스테이지의 스테이트를 사용해, 불려 간 시점에서의 확인을 실시한다. 이 호출의 후에 이러한 요소로 변경이 있으면(자), 지금까지의 확인 결과는 무효가 되므로, 장면의 렌더링을 하기 전에 이 메소드를 재차 호출하지 않으면 안 된다.

디 푸즈 반복값의 인수 또는 처리 (D3DTA_DIFFUSE 또는 D3DTOP_BLENDDIFFUSEALPHA )로서의 사용은, 현재의 하드웨어에서는 거의 지원되어 있지 않다. 대부분의 하드웨어에서는, 직전의 텍스쳐 조작 스테이지에 있어서의 색데이터의 반복값을 도입하고 있는 정도이다.

각 스테이지의 텍스쳐 (D3DTA_TEXTURE )는, 제 2 인수는 아니고 제 1 인수로서 지정하도록(듯이) 한다.

많은 카드는, 임의의 텍스쳐의 스테이지에 있어서의 디 푸즈값이나 스칼라-값의 사용은 지원 하고 있지 않다. 이것들은 최초인가 마지막 텍스쳐의 블렌딩 스테이지에서만 사용할 수 있는 것이 많다.

알파의 색채널에의 복제, 입력 반전 등 이상의 능력이 있는 최초의 텍스쳐에 블렌딩 유니트를 관련짓는 카드는 적다. 따라서, 어플리케이션에서는, 가능한 경우, 2 번째의 텍스쳐 스테이지만 사용해야 할 때가 있다. 이러한 하드웨어에서는, 최초의 유니트는 디폴트 스테이트에 있으면(자) 가정되어D3DTOP_SELECTARG1 처리로 제 1 컬러 인수는 D3DTA_TEXTURE 로 설정된다.

색조작에 비해 보다 복잡해 실질적으로도 다른, 출력된 알파값에 대한 조작을 지원 하는 하드웨어는, 한층 더 적다.

하드웨어에 따라서는,D3DTA_TFACTOR 및 D3DTA_DIFFUSE 의 동시 사용을 지원 하고 있지 않는 경우도 있다.

또 많은 카드는, 멀티 텍스쳐와 밉맵 트라이 리니어 필터링의 동시 사용은 지원 하지 않는다. 멀티 텍스쳐 블렌딩 처리에 있어서의 텍스쳐에 대해서 트라이 리니어 필터링이 요구되었을 경우, 타당성 검증이 실패 하면, 트라이 리니어 필터링은 오프가 되어 재검증을 한다. 이러한 경우에는, 대신에 멀티 패스 렌더링을 실행할 수가 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DDevice7::GetTextureStageState ,IDirect3DDevice7::SetTextureStageState


IDirect3DVertexBuffer7

어플리케이션에서는,IDirect3DVertexBuffer7 인터페이스의 메소드를 사용해,IDirect3DDevice7::DrawPrimitiveVB 및 IDirect3DDevice7::DrawIndexedPrimitiveVB 렌더링 메소드로 이용하는 버텍스의 집합을 조작한다. 여기에서는, 이 인터페이스의 메소드에 대한 레퍼런스 정보를 기술한다. 개요에 대해서는, 「버텍스 버퍼」를 참조할것.

IDirect3DVertexBuffer 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

정보 | GetVertexBufferDesc
버텍스 데이터 | Lock
 | Optimize
 | ProcessVertices
 | ProcessVerticesStrided
 | Unlock

IDirect3DVertexBuffer7 인터페이스는, 보폭 버텍스 포맷을 지원 하는 IDirect3DVertexBuffer7::ProcessVerticesStrided 메소드를 더하는 것으로,IDirect3DVertexBuffer 인터페이스를 확장하고 있다.

모든 COM 인터페이스와 같이,IDirect3DVertexBuffer7 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECT3DVERTEXBUFFER7 및 LPDIRECT3DVERTEXBUFFER 데이터형은,IDirect3DVertex7 및 IDirect3DVertexBuffer 인터페이스에의 포인터로서 정의된다.

typedef struct IDirect3DVertexBuffer *LPDIRECT3DVERTEXBUFFER;
typedef struct IDirect3DVertexBuffer7 *LPDIRECT3DVERTEXBUFFER7;

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

버텍스 버퍼


IDirect3DVertexBuffer7::GetVertexBufferDesc

IDirect3DVertexBuffer7::GetVertexBufferDesc 메소드는, 버텍스 버퍼의 기술을 검색해 꺼낸다.

HRESULT GetVertexBufferDesc(
  LPD3DVERTEXBUFFERDESC lpVBDesc
);

파라미터

lpVBDesc
버텍스 버퍼의 기술을 저장 하는 D3DVERTEXBUFFERDESC 구조체의 주소.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면,DDERR_INVALIDPARAMS 또는 다른 에러값을 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.


IDirect3DVertexBuffer7::Lock

IDirect3DVertexBuffer7::Lock 메소드는, 버텍스 버퍼를 잠그어, 버텍스 버퍼 메모리에의 포인터를 취득한다.

HRESULT Lock(
  DWORD   dwFlags,
  LPVOID* lplpData,
  LPDWORD lpdwSize
);

파라미터

dwFlags
버텍스 버퍼의 락의 방법을 나타내는 플래그.
DDLOCK_EVENT
현재는 이행되어 있지 않다.
DDLOCK_NOSYSLOCK
가능하면, Win16Mutex (Win16Lock 라고도 말한다)는 이용하지 않는다.
DDLOCK_READONLY
락 된 메모리는 읽어내기 전용인 것을 나타낸다.
DDLOCK_SURFACEMEMORYPTR
버텍스 버퍼에의 유효한 메모리 포인터가 돌려주어지는 것을 나타낸다. 이것은 디폴트이다.
DDLOCK_WAIT
락을 즉석에서 할 수 없는 경우, 메소드는 잠글 수 없을지, 또는, 다른 에러가 생길 때까지 리트라이 한다.
DDLOCK_WRITEONLY
락 된 메모리는 쓰기 전용인 것을 나타낸다.
DDLOCK_DISCARDCONTENTS
DirectX 7.0 의 신기능. Direct3D 버텍스 버퍼의 락에서만 사용. 락중에 버텍스 버퍼의 내용이 보증되지 않는 것을 나타낸다. 이 플래그를 사용 하면, Direct3D 또는 드라이버가 대체 메모리 영역을 버텍스 버퍼로서 제공하게 된다. 이 플래그는, 버텍스 버퍼의 내용을 클리어 해 새로운 데이터를 저장 하는 경우에 편리하다.
DDLOCK_NOOVERWRITE
DirectX 7.0 의 신기능. Direct3D 버텍스 버퍼의 락에서만 사용. 락중에 최초의 프레임 (이 플래그가 지정되어 있지 않은 경우는 마지막 락)이 수정되고 있기 (위해)때문에, 버텍스 버퍼의 DrawPrimitive 호출로 참조된 버텍스가 존재하지 않는 것을 나타낸다. 이 플래그는, 버텍스 버퍼에 데이터만 추가하는 경우에 편리하다.
lplpData
호출이 성공했을 때에, 버텍스 버퍼 메모리의 주소를 저장 하는 변수의 주소.
lpdwSize
lplpData 의 버텍스 버퍼 메모리의 사이즈를 저장 하는 변수의 주소. 버퍼 사이즈가 불필요하면 NULL 를 설정한다.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

D3DERR_VERTEXBUFFEROPTIMIZED
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACEBUSY
DDERR_SURFACELOST

주의

버텍스 버퍼를 잠근 후는,IDirect3DVertexBuffer7::Unlock 를 호출할 때까지 이 메모리에 액세스 할 수 있다.

락 된 버텍스 버퍼로부터 렌더링 할 수 없다. 락 된 버텍스 버퍼를 사용해 IDirect3DDevice7::DrawIndexedPrimitiveVB 또는 IDirect3DDevice7::DrawPrimitiveVB 메소드를 호출하면 실패해,D3DERR_VERTEXBUFFERLOCKED 가 돌려주어진다.

이 메소드는,IDirect3DVertexBuffer7::Unlock 메소드를 호출할 때까지, Win16Mutex 를 hold 시키는 것이 자주 있다. GUI 디버거는, Win16Mutex 가 hold 되고 있는 동안은 동작하지 않는다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DVertexBuffer7::Unlock ,버텍스 버퍼의 내용에의 액세스


IDirect3DVertexBuffer7::Optimize

IDirect3DVertexBuffer7::Optimize 메소드는, 최적화되어 있지 않은 버텍스 버퍼를 트랜스 폼 해 최적화한다.

HRESULT Optimize(
  LPDIRECT3DDEVICE7 lpD3DDevice,
  DWORD dwFlags
);

파라미터

lpD3DDevice
이 버텍스 버퍼를 최적화하는 대상이 되는 디바이스의 IDirect3DDevice7 인터페이스의 주소.
dwFlags
현재는 사용되어 있지 않다. 제로를 설정한다.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

D3DERR_VERTEXBUFFEROPTIMIZED
D3DERR_VERTEXBUFFERLOCKED
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

주의

종래의 IDirect3DVertexBuffer 인터페이스에서는, 이 메소드는 IDirect3DDevice3 인터페이스에의 포인터를 받았다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

버텍스 버퍼의 최적화,버텍스 버퍼


IDirect3DVertexBuffer7::ProcessVertices

IDirect3DVertexBuffer7::ProcessVertices 메소드는, 트랜스 폼되어 있지 않은 버텍스를 처리해, 트랜스 폼 또는 최적화된 버텍스 버퍼로 한다.

HRESULT ProcessVertices(
  DWORD dwVertexOp,
  DWORD dwDestIndex,
  DWORD dwCount,
  LPDIRECT3DVERTEXBUFFER7 lpSrcBuffer,
  DWORD dwSrcIndex,
  LPDIRECT3DDEVICE7       lpD3DDevice,
  DWORD dwFlags
);

파라미터

dwVertexOp
원의 버퍼로부터 전송 된 버텍스를 메소드가 처리하는 방법을 정의하는 플래그. 다음의 플래그의 임의의 편성을 지정할 수가 있다.
D3DVOP_CLIP
버텍스를 트랜스 폼 해, 절두체의 외측에 나오는 모든 버텍스를 클립 한다. 이 플래그는, (D3DDP_DONOTCLIP 플래그로 생성 되었다는 등의) 클리핑 정보를 포함하지 않는 버텍스 버퍼에는 사용할 수 없다.
D3DVOP_EXTENTS
버텍스를 트랜스 폼 해, 버텍스가 렌더링 되면(자), 스크린 직사각형의 범위를 갱신한다. 이 플래그를 사용 하면 잠재적으로 퍼포먼스가 향상할 가능성이 있지만,IDirect3DDevice7::GetClipStatus 가 돌려주는 범위에 대해서, 버텍스의 렌더링 시에 그 버텍스를 고려한 갱신을 하지 않는다.
D3DVOP_LIGHT
버텍스를 라이팅 한다.
D3DVOP_TRANSFORM
월드 행렬, 뷰 행렬, 투영 행렬을 사용해 버텍스를 트랜스 폼 한다. 이 플래그는 항상 설정할 필요가 있다.
dwDestIndex
처리의 뒤, 버텍스의 배치처가 되는 버텍스 버퍼 (이 버퍼)에의 인덱스.
dwCount
원의 버퍼에 있는, 처리하는 버텍스의 수.
lpSrcBuffer
원의 버텍스 버퍼의 IDirect3DVertexBuffer7 인터페이스의 주소.
dwSrcIndex
원의 버텍스 버퍼에 있는, 처리하는 버텍스 가운데, 최초의 버텍스의 인덱스
lpD3DDevice
버텍스의 트랜스 폼에 사용하는 디바이스의 IDirect3DDevice7 인터페이스의 주소.
dwFlags
처리 옵션. 디폴트 처리에 대해서는 이 파라미터를 0 으로 설정한다. D3DPV_DONOTCOPYDATA 로 설정 하면, 현재의 버텍스의 처리에 무관계한 버텍스 데이터를 카피처 버퍼에 카피하는 것을 막을 수가 있다. 상세한 것에 대하여는, 「버텍스의 처리」를 참조할것.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDVERTEXFORMAT
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACEBUSY
DDERR_SURFACELOST

주의

dwVertexOp 파라미터에는 항상 D3DVOP_TRANSFORMED 플래그를 포함하는 것. 이 플래그를 포함하지 않으면 메소드가 실패해,DDERR_INVALIDPARAMS 를 돌려준다.

IDirect3DVertexBuffer 인터페이스에서는, 이 메소드는 IDirect3DDevice3 및 IDirect3DVertexBuffer 인터페이스에의 포인터를 받았다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

버텍스의 처리,버텍스 버퍼


IDirect3DVertexBuffer7::ProcessVerticesStrided

IDirect3DVertexBuffer::ProcessVerticesStrided 메소드는, 트랜스폼 되지 않은의 버텍스를 트랜스 폼 끝나 또는 최적화가 끝난 버텍스 버퍼로 한다.

HRESULT ProcessVerticesStrided(
  DWORD dwVertexOp,
  DWORD dwDestIndex,
  DWORD dwCount,
  LPD3DDRAWPRIMITIVESTRIDEDDATA lpStrideData,
  DWORD dwVertexTypeDesc,
  LPDIRECT3DDEVICE7 lpD3DDevice,
  DWORD dwFlags
);

파라미터

dwVertexOp
원의 버퍼로부터 전송 된 버텍스를 메소드가 처리하는 방법을 정의하는 플래그. 다음의 플래그의 임의의 편성을 지정할 수가 있다.
D3DVOP_CLIP
버텍스를 트랜스 폼 해, 절두체의 외측에 나오는 모든 버텍스를 클립 한다. 이 플래그는, (D3DDP_DONOTCLIP 플래그로 생성 되었다는 등의) 클리핑 정보를 포함하지 않는 버텍스 버퍼에는 사용할 수 없다.
D3DVOP_EXTENTS
버텍스를 트랜스 폼 해, 버텍스가 렌더링 되면(자), 스크린 직사각형의 범위를 갱신한다. 이 플래그를 사용 하면 잠재적으로 퍼포먼스가 향상할 가능성이 있지만,IDirect3DDevice7::GetClipStatus 가 돌려주는 범위에 대해서, 버텍스의 렌더링 시에 그 버텍스를 고려한 갱신을 하지 않는다.
D3DVOP_LIGHT
버텍스를 라이팅 한다.
D3DVOP_TRANSFORM
월드 행렬, 뷰 행렬, 투영 행렬을 사용해 버텍스를 트랜스 폼 한다. 이 플래그는 항상 설정할 필요가 있다.
dwDestIndex
처리의 뒤, 버텍스의 배치처가 되는 버텍스 버퍼 (이 버퍼)에의 인덱스.
dwCount
원의 버퍼에 있는, 처리하는 버텍스의 수.
lpStrideData
이 프리미티브의 버텍스 성분의 포인터 및 메모리 보폭을 저장 하는 D3DDRAWPRIMITIVESTRIDEDDATA 구조체의 주소.
dwVertexTypeDesc
버텍스 포맷을 기술하는유연한 버텍스 포맷 플래그의 편성.
lpD3DDevice
버텍스의 트랜스 폼에 사용하는 디바이스의 IDirect3DDevice7 인터페이스의 주소.
dwFlags
처리 옵션. 디폴트 처리에 대해서는 이 파라미터를 0 으로 설정한다. D3DPV_DONOTCOPYDATA 로 설정 하면, 현재의 버텍스의 처리에 무관계한 버텍스 데이터를 카피처 버퍼에 카피하는 것을 막을 수가 있다. 상세한 것에 대하여는, 「버텍스의 처리」를 참조할것.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

D3DERR_INVALIDVERTEXFORMAT
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACEBUSY
DDERR_SURFACELOST

주의

dwVertexOp 파라미터에는 항상 D3DVOP_TRANSFORM 플래그를 포함하는 것. 이 플래그를 포함하지 않으면 메소드가 실패해,DDERR_INVALIDPARAMS 를 돌려준다.

이 메소드는,IDirect3DVertexBuffer7 인터페이스와 함께 도입되었다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DVertexBuffer7::ProcessVertices ,버텍스의 처리,버텍스 버퍼


IDirect3DVertexBuffer7::Unlock

IDirect3DVertexBuffer7::Unlock 메소드는, 전에 잠근 버텍스 버퍼의 락을 해제한다.

HRESULT Unlock();

파라미터

없음.

반환값

성공하면 D3D_OK 를 돌려준다.

실패하면, 다음의 몇개의 값을 돌려준다.

D3DERR_VERTEXBUFFEROPTIMIZED
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACEBUSY
DDERR_SURFACELOST

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3d.h 로 선언.

참조

IDirect3DVertexBuffer7::Lock ,버텍스 버퍼의 내용에의 액세스


이행되어 있지 않은 메소드

이하의 메소드는, DirectX 의 구버젼에서는 사용되고 있었지만, 그 최신 버젼의 인터페이스에서는 이행되어 있지 않다. 인터페이스 전체가 폐지되고 있는 경우도 있다. 이러한 인터페이스에 대해서는, 구버젼의 DirectX 에 기재되어 있다.

이전의 그루터기 메소드. 이하의 메소드는 이행 되지 않고, 어느 인터페이스에 대해도 지원되어 있지 않다.

IDirect3D::Initialize

IDirect3DMaterial::Initialize

IDirect3DMaterial::Reserve

IDirect3DMaterial::Unreserve

IDirect3DTexture::Initialize

IDirect3DTexture::Unload

폐지된 메소드. 이하의 메소드는, 최신 버젼의 인터페이스에서는 지원되어 있지 않다.

IDirect3D3::CreateLight

IDirect3D3::CreateMaterial

IDirect3D3::CreateViewport

IDirect3DDevice3::GetStats

IDirect3DDevice3::GetLightState

IDirect3DDevice3::SetLightState

옮겨놓을 수 있었던 뷰포트 메소드. 이하의 메소드에 대해서는,IDirect3DDevice7::GetViewport 및 IDirect3DDevice7::SetViewport 메소드가 대신해 사용된다.

IDirect3DDevice3::AddViewport

IDirect3DDevice3::DeleteViewport

IDirect3DDevice3::GetCurrentViewport

IDirect3DDevice3::NextViewport

IDirect3DDevice3::SetCurrentViewport

폐지된 단일 버텍스 렌더링 메소드. 이하의 메소드는,IDirect3DDevice7 인터페이스에서는 지원되어 있지 않다.

IDirect3DDevice3::Begin

IDirect3DDevice3::BeginIndexed

IDirect3DDevice3::End

IDirect3DDevice3::Index

IDirect3DDevice3::Vertex


폐지된 인터페이스

실행 버퍼를 사용한 렌더링을 지원 하는 IDirect3DDevice 및 IDirect3DExecuteBuffer 인터페이스는 폐지되고 있다. 이러한 인터페이스에 대해서는, 구릴리스의 DirectX 의 문서를 참조할것.

IDirect3DLight,IDirect3DMaterial3, 및 IDirect3DViewport3 인터페이스는,IDirect3DDevice3 인터페이스보다 새로운 인터페이스에서는 지원되어 있지 않다. 이러한 인터페이스의 기능성은, 현재는 디바이스 인터페이스 자체 (IDirect3DDevice7 )에 포함되어 있다.

IDirect3DLight 인터페이스는 폐지되고 있다. 이 인터페이스의 기능성은, 현재는 IDirect3DDevice7 인터페이스에 포함되어 있다. 이 2 개의 인터페이스의 관계는 이하와 같이 요약된다.

IDirect3DLight::GetLight 및 IDirect3DLight::GetLight
IDirect3DDevice7::GetLight 및 IDirect3DDevice7::SetLight 메소드가 대신해 사용된다.
IDirect3DLight::Initialize
지원 되지 않는다.

이하의 메소드는, 폐지된 IDirect3DMaterial3 인터페이스의 메소드이다. 필요에 따라서 IDirect3DDevice7 인터페이스의 메소드와의 상관관계를 나타내고 있다.

IDirect3DMaterial3::GetHandle
지원 되지 않는다. 머트리얼 핸들은 IDirect3DDevice7 인터페이스에서는 사용되지 않는다.
IDirect3DMaterial3::GetMaterial 및 IDirect3DMaterial3::SetMaterial
IDirect3DDevice7::GetMaterial 및 IDirect3DDevice7::SetMaterial 메소드가 대신해 사용된다.

이하의 일람은, 폐지된 IDirect3DViewport3 인터페이스의 메소드를 나타낸다. 위에의 머트리얼 관련 메소드의 일람과 같이,IDirect3DDevice7 로 대응하는 메소드에 대해서도 가리킨다.

IDirect3DViewport3::GetBackground 및 IDirect3DViewport3::SetBackground
지원 되지 않는다. 백그라운드 머트리얼은 IDirect3DDevice7 인터페이스에서는 사용되지 않는다.
IDirect3DViewport3::GetBackgroundDepth, IDirect3DViewport3::GetBackgroundDepth2, IDirect3DViewport3::SetBackgroundDepth,및 IDirect3DViewport3::SetBackgroundDepth2
지원 되지 않는다.
IDirect3DViewport3::AddLight, IDirect3DViewport3::NextLight,및 IDirect3DViewport3::DeleteLight
각각의 라이트의 파라미터에는,IDirect3DDevice7::GetLight 및 IDirect3DDevice7::SetLight 메소드로 액세스 한다. 라이트의 유효/무효를 개별적으로 바꾸려면 ,IDirect3DDevice7::GetLightEnable 및 IDirect3DDevice7::LightEnable 메소드를 사용한다.
IDirect3DViewport3::LightElements
지원 되지 않는다.
IDirect3DViewport3::Clear 및 IDirect3DViewport3::Clear2
IDirect3DDevice7::Clear 메소드가 대신해 사용된다.
IDirect3DViewport3::GetViewport, IDirect3DViewport3::GetViewport2, IDirect3DViewport3::SetViewport,및 IDirect3DViewport3::SetViewport2
IDirect3DDevice7::GetViewport 및 IDirect3DDevice7::SetViewport 메소드가 대신해 사용된다.
IDirect3DViewport3::Initialize
지원 되지 않는다.
IDirect3DViewport3::TransformVertices
지원 되지 않는다. 버텍스 버퍼를 사용해 버텍스를 수동으로 트랜스 폼 한다.


D3D_OVERLOADS

D3D_OVERLOADS 를 정의하는 것으로, C++ 의 프로그래머는, 여기에 기술된 확장 기능을 이용해, Direct3D 직접 모드 어플리케이션의 코드를 간략화할 수가 있다. D3D_OVERLOADS 의 이용은 DirectX® 5.0 과 함께 도입되었다. 여기에서는 D3D_OVERLOADS 확장 기능의 레퍼런스를 기술한다.

이러한 확장 기능은, C++ 의 링크를 사용해 정의해야 한다. D3D_OVERLOADS 가 정의되어 d3dtypes.h 또는 d3d.h 의 인클루드의 전후에 extern "C" 가 있으면(자), 링크 에러가 발생한다. 예를 들어, 이하의 구문에서는 D3D_OVERLOADS 기능을 C 로 링크하기 위해서, 링크 에러가 발생한다.

#define D3D_OVERLOADS
extern "C" {
#include <d3d.h>
};

D3D_OVERLOADS 확장 기능은, 이하의 그룹에 정리할 수가 있다.

constructor | D3DVERTEX
 | D3DTLVERTEX
 | D3DVECTOR
 | D3DVERTEX
연산자 | 액세스 허가 연산자
 | 덧셈 연산자
 | 대입 연산자
 | 비트마다의 등가 연산자
 | D3DMATRIX
 | 나눗셈 연산자
 | 곱셈 연산자
 | 뺄셈 연산자
 | 단항 연산자
 | 벡터 지배 연산자
헬퍼-함수 | CrossProduct
 | DotProduct
 | Magnitude
 | Max
 | Maximize
 | Min
 | Minimize
 | Normalize
 | SquareMagnitude


D3D_OVERLOADS constructor

여기에서는, D3D_OVERLOADS C++ 확장 기능이 제공하는 constructor　 　 의 레퍼런스를 기술한다.

  • D3DVERTEX
  • D3DTLVERTEX
  • D3DVECTOR
  • D3DVERTEX

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.


D3DLVERTEX constructor

D3DLVERTEX 구조체의 D3D_OVERLOADS constructor　 　 은, C++ 로 라이팅 끝난 버텍스를 생성 할 경우에 편리하다.

_D3DLVERTEX() { }
_D3DLVERTEX(const D3DVECTOR& v,
            D3DCOLOR _color, D3DCOLOR _specular,
            float _tu, float _tv)
    { x = v.x; y = v.y; z = v.z; dwReserved = 0;
      color = _color; specular = _specular;
      tu = _tu; tv = _tv;
    }

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.


D3DTLVERTEX constructor

D3DTLVERTEX 구조체의 D3D_OVERLOADS constructor　 　 은, C++ 로 트랜스 폼이 끝난 라이팅 끝난 버텍스를 생성 할 경우에 편리하다.

_D3DTLVERTEX() { }
_D3DTLVERTEX(const D3DVECTOR& v, float _rhw,
             D3DCOLOR _color, D3DCOLOR _specular,
             float _tu, float _tv)
    { sx = v.x; sy = v.y; sz = v.z; rhw = _rhw;
      color = _color; specular = _specular;
      tu = _tu; tv = _tv;
    }

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.


D3DVECTOR constructor

D3DVECTOR 구조체의 D3D_OVERLOADS constructor　 　 은, C++ 로 벡터를 생성 할 경우에 편리하다.

_D3DVECTOR() { }
_D3DVECTOR(D3DVALUE f);
_D3DVECTOR(D3DVALUE _x, D3DVALUE _y, D3DVALUE _z);
_D3DVECTOR(const D3DVALUE f[3]);

이 constructor　 　 은, 이하와 같이 정의된다.

inline _D3DVECTOR::_D3DVECTOR(D3DVALUE f)
    {    x = y = z = f; }

inline _D3DVECTOR::_D3DVECTOR(D3DVALUE _x, D3DVALUE _y, D3DVALUE _z)
    {     x = _x; y = _y; z = _z; }

inline _D3DVECTOR::_D3DVECTOR(const D3DVALUE f[3])
    {     x = f[0]; y = f[1]; z = f[2]; }

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.


D3DVERTEX constructor

D3DVERTEX 구조체의 D3D_OVERLOADS constructor　 　 은, C++ 로 라이팅 끝난 버텍스를 생성 할 경우에 편리하다.

_D3DVERTEX() { }
_D3DVERTEX(const D3DVECTOR& v, const D3DVECTOR& n, float _tu, float _tv)
    { x = v.x; y = v.y; z = v.z;
      nx = n.x; ny = n.y; nz = n.z;
      tu = _tu; tv = _tv;
    }

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.


D3D_OVERLOADS 연산자

여기에서는, D3D_OVERLOADS C++ 확장 기능이 제공하는 연산자의 레퍼런스 정보를 기술한다.

  • 액세스 허가 연산자
  • 덧셈 연산자
  • 대입 연산자
  • 비트마다의 등가 연산자
  • D3DMATRIX
  • 나눗셈 연산자
  • 곱셈 연산자
  • 뺄셈 연산자
  • 단항 연산자
  • 벡터 지배 연산자

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.


액세스 허가 연산자 (D3D_OVERLOADS)

브랙킷 ("[ ]") 연산자는, D3D_OVERLOADS 확장 기능의 overload 연산자이다. 액세스의 허가에는 하늘의 브랙킷 ("[ ]")을, 벡터의 x 요소에 액세스 하려면 "v[0]" 을, y 요소에 액세스 하려면 "v[1]" 을, z 요소에 액세스 하려면 "v[2]" 를, 각각 사용할 수가 있다. 이러한 연산자는, 이하와 같이 정의된다.

const D3DVALUE&operator[ ](int i) const;
D3DVALUE&operator[ ](int i);

inline const D3DVALUE&
_D3DVECTOR::operator[ ](int i) const
{
    return (&x)[i];
}

inline D3DVALUE&
_D3DVECTOR::operator[ ](int i)
{
    return (&x)[i];
}

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.


덧셈 연산자 (D3D_OVERLOADS)

이 2 항연산자는, D3D_OVERLOADS 확장 기능의 overload 연산자이다. 덧셈 연산자는, 이하와 같이 정의된다.

_D3DVECTOR operator + (const _D3DVECTOR& v1, const _D3DVECTOR& v2);

inline _D3DVECTOR
operator + (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
   return _D3DVECTOR(v1.x+v2.x, v1.y+v2.y, v1.z+v2.z);
}

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.


대입 연산자 (D3D_OVERLOADS)

대입 연산자는, D3D_OVERLOADS 확장 기능의 overload 연산자이다. 스칼라- 및 벡터의 양형식의 것 "*=" 및 "/=" 연산자가 이행 되고 있다(벡터에 있어서의 곱셈 및 나눗셈은 멤버에 대한 연산이다).

_D3DVECTOR& operator += (const _D3DVECTOR& v);
_D3DVECTOR& operator -= (const _D3DVECTOR& v);
_D3DVECTOR& operator *= (const _D3DVECTOR& v);
_D3DVECTOR& operator /= (const _D3DVECTOR& v);
_D3DVECTOR& operator *= (D3DVALUE s);
_D3DVECTOR& operator /= (D3DVALUE s);

대입 연산자는, 이하와 같이 정의된다.

inline _D3DVECTOR&
_D3DVECTOR::operator += (const _D3DVECTOR& v)
{
   x += v.x;   y += v.y;   z += v.z;
   return *this;
}

inline _D3DVECTOR&
_D3DVECTOR::operator -= (const _D3DVECTOR& v)
{
   x -= v.x;   y -= v.y;   z -= v.z;
   return *this;
}

inline _D3DVECTOR&
_D3DVECTOR::operator *= (const _D3DVECTOR& v)
{
   x *= v.x;   y *= v.y;   z *= v.z;
   return *this;
}

inline _D3DVECTOR&
_D3DVECTOR::operator /= (const _D3DVECTOR& v)
{
   x /= v.x;   y /= v.y;   z /= v.z;
   return *this;
}

inline _D3DVECTOR&
_D3DVECTOR::operator *= (D3DVALUE s)
{
   x *= s;   y *= s;   z *= s;
   return *this;
}

inline _D3DVECTOR&
_D3DVECTOR::operator /= (D3DVALUE s)
{
   x /= s;   y /= s;   z /= s;
   return *this;
}

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.


비트마다의 등가 연산자 (D3D_OVERLOADS)

이 2 항연산자는, D3D_OVERLOADS 확장 기능의 overload 연산자이다. 비트마다의 등가 연산자는 이하와 같이 정의된다.

int operator == (const _D3DVECTOR& v1, const _D3DVECTOR& v2);

inline int
operator == (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
   return v1.x==v2.x && v1.y==v2.y && v1.z == v2.z;
}

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.


D3DMATRIX (D3D_OVERLOADS)

D3DMATRIX 구조체의 D3D_OVERLOADS 이행에는, 외모 ("()") 연산자가 포함되어 있다. 이 연산자는, C++ 프로그래머에 대해서 행렬중의 값에 액세스 하는 편리한 방법을 제공한다. C++ 에서는, 구조체의 멤버의 참조는, 이름은 아니고 행 및 열번호로 실시할 수가 있어 필요에 따라서 그러한 번호를 인덱스로서 사용할 수 있다.

typedef struct _D3DMATRIX {
#if (defined __cplusplus) && (defined D3D_OVERLOADS)
    union {
        struct {
#endif

            D3DVALUE        _11, _12, _13, _14;
            D3DVALUE        _21, _22, _23, _24;
            D3DVALUE        _31, _32, _33, _34;
            D3DVALUE        _41, _42, _43, _44;

#if (defined __cplusplus) && (defined D3D_OVERLOADS)
        };
        D3DVALUE m[4][4];
    };
    _D3DMATRIX() { }

    D3DVALUE& operator()(int iRow, int iColumn) { return m[iRow][iColumn]; }
    const D3DVALUE& operator()(int iRow, int iColumn) const { return m[iRow][iColumn]; }
#endif
} D3DMATRIX, *LPD3DMATRIX;

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.

참조

D3DMATRIX


나눗셈 연산자 (D3D_OVERLOADS)

이 2 항연산자는, D3D_OVERLOADS 확장 기능의 overload 연산자이다. 이 연산자는 스칼라- 및 벡터의 양쪽 모두의 형식에서 이행 되고 있다. 나눗셈 연산자는, 이하와 같이 정의된다.

_D3DVECTOR operator / (const _D3DVECTOR& v, D3DVALUE s);
_D3DVECTOR operator / (const _D3DVECTOR& v1, const _D3DVECTOR& v2);

inline _D3DVECTOR
operator / (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
   return _D3DVECTOR(v1.x/v2.x, v1.y/v2.y, v1.z/v2.z);
}

inline _D3DVECTOR
operator / (const _D3DVECTOR& v, D3DVALUE s)
{
   return _D3DVECTOR(v.x/s, v.y/s, v.z/s);
}

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.


곱셈 연산자 (D3D_OVERLOADS)

이 2 항연산자는, D3D_OVERLOADS 확장 기능의 overload 연산자이다. 이 연산자는 스칼라- 및 벡터의 양쪽 모두의 형식에서 이행 되고 있다. 곱셈 연산자는, 이하와 같이 정의된다.

_D3DVECTOR operator * (const _D3DVECTOR& v, D3DVALUE s);
_D3DVECTOR operator * (D3DVALUE s, const _D3DVECTOR& v);
_D3DVECTOR operator * (const _D3DVECTOR& v1, const _D3DVECTOR& v2);

inline _D3DVECTOR
operator * (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
   return _D3DVECTOR(v1.x*v2.x, v1.y*v2.y, v1.z*v2.z);
}

inline _D3DVECTOR
operator * (const _D3DVECTOR& v, D3DVALUE s)
{
   return _D3DVECTOR(s*v.x, s*v.y, s*v.z);
}

inline _D3DVECTOR
operator * (D3DVALUE s, const _D3DVECTOR& v)
{
   return _D3DVECTOR(s*v.x, s*v.y, s*v.z);
}

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.


뺄셈 연산자 (D3D_OVERLOADS)

이 2 항연산자는, D3D_OVERLOADS 확장 기능의 overload 연산자이다. 뺄셈 연산자는, 이하와 같이 정의된다.

_D3DVECTOR operator - (const _D3DVECTOR& v1, const _D3DVECTOR& v2);

inline _D3DVECTOR
operator - (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
   return _D3DVECTOR(v1.x-v2.x, v1.y-v2.y, v1.z-v2.z);
}

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


단항 연산자 (D3D_OVERLOADS)

이 단항 연산자는, D3D_OVERLOADS 확장 기능의 overload 연산자이다. 단항 연산자는, 이하와 같이 정의된다.

_D3DVECTOR operator + (const _D3DVECTOR& v);
_D3DVECTOR operator - (const _D3DVECTOR& v);

inline _D3DVECTOR
operator + (const _D3DVECTOR& v)
{
   return v;
}

inline _D3DVECTOR
operator - (const _D3DVECTOR& v)
{
   return _D3DVECTOR(-v.x, -v.y, -v.z);
}

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


벡터 지배 연산자 (D3D_OVERLOADS)

이 2 항연산자군은, D3D_OVERLOADS 확장 기능의 overload 연산자이다. 벡터 v1 의 임의의 요소가, v2 의 대응하는 요소보다 큰 경우, 전자가 후자를 지배한다. 따라서, 지정한 2 개의 벡터의 어느쪽이나 한편을 지배하지 않는다고 하는 상태가 일어날 수 있다.

int operator < (const _D3DVECTOR& v1, const _D3DVECTOR& v2);
int operator <= (const _D3DVECTOR& v1, const _D3DVECTOR& v2);

벡터 지배 연산자는, 이하와 같이 정의된다.

inline int
operator < (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
   return v1[0] < v2[0] && v1[1] < v2[1] && v1[2] < v2[2];
}

inline int
operator <= (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
   return v1[0] <= v2[0] && v1[1] <= v2[1] && v1[2] <= v2[2];
}

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


D3D_OVERLOADS 헬퍼-함수

여기에서는, D3D_OVERLOADS C++ 확장 기능이 제공하는 헬퍼-함수의 레퍼런스 정보를 기술한다.

  • CrossProduct
  • DotProduct
  • Magnitude
  • Max
  • Maximize
  • Min
  • Minimize
  • Normalize
  • SquareMagnitude

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


CrossProduct

이 헬퍼-함수는, 지정한 벡터의 외적을 돌려준다. CrossProduct 는, D3D_OVERLOADS 를 정의하는 C++ 프로그래머가 사용할 수 있는 확장 기능 세트의 일부이다.

_D3DVECTOR CrossProduct (const _D3DVECTOR& v1, const _D3DVECTOR& v2);

이 함수는, 이하와 같이 정의된다.

inline _D3DVECTOR
CrossProduct (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
    _D3DVECTOR result;

    result[0] = v1[1] * v2[2] - v1[2] * v2[1];
    result[1] = v1[2] * v2[0] - v1[0] * v2[2];
    result[2] = v1[0] * v2[1] - v1[1] * v2[0];

    return result;
}

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.

참조

DotProduct


DotProduct

이 헬퍼-함수는, 지정한 벡터의 내적을 돌려준다. DotProduct 는, D3D_OVERLOADS 를 정의하는 C++ 프로그래머가 사용할 수 있는 확장 기능 세트의 일부이다.

D3DVALUE DotProduct (const _D3DVECTOR& v1, const _D3DVECTOR& v2);

이 함수는, 이하와 같이 정의된다.

inline D3DVALUE
DotProduct (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
   return v1.x*v2.x + v1.y * v2.y + v1.z*v2.z;
}

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.

참조

CrossProduct


Magnitude

이 헬퍼-함수는, 지정한 벡터의 절대치를 돌려준다. Magnitude 은, D3D_OVERLOADS 를 정의하는 C++ 프로그래머가 사용할 수 있는 확장 기능 세트의 일부이다.

D3DVALUE Magnitude (const _D3DVECTOR& v);

이 함수는, 이하와 같이 정의된다.

inline D3DVALUE
Magnitude (const _D3DVECTOR& v)
{
   return (D3DVALUE) sqrt(SquareMagnitude(v));
}

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.

참조

SquareMagnitude


Max

이 헬퍼-함수는, 지정한 벡터의 최대 요소를 돌려준다. Max 는, D3D_OVERLOADS 를 정의하는 C++ 프로그래머가 사용할 수 있는 확장 기능 세트의 일부이다.

D3DVALUE Max (const _D3DVECTOR& v);

이 함수는, 이하와 같이 정의된다.

inline D3DVALUE
Max (const _D3DVECTOR& v)
{
   D3DVALUE ret = v.x;
   if (ret < v.y) ret = v.y;
   if (ret < v.z) ret = v.z;
   return ret;
}

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.

참조

Min


Maximize

이 헬퍼-함수는, 지정한 2 개의 벡터의 최대 성분으로 구성되는 벡터를 돌려준다. Maximize 는, D3D_OVERLOADS 를 정의하는 C++ 프로그래머가 사용할 수 있는 확장 기능 세트의 일부이다.

_D3DVECTOR Maximize (const _D3DVECTOR& v1, const _D3DVECTOR& v2);

이 함수는, 이하와 같이 정의된다.

inline _D3DVECTOR
Maximize (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
   return _D3DVECTOR( v1[0] > v2[0] ?  v1[0] : v2[0],
                      v1[1] > v2[1] ?  v1[1] : v2[1],
                      v1[2] > v2[2] ?  v1[2] : v2[2]);
}

주의

이하와 같은 함수로,Maximize 및 Minimize 함수를 사용해 점의 집합을 둘러싸는 박스를 계산할 수 있다.

    void
    ComputeBoundingBox(const D3DVECTOR *pts, int N, D3DVECTOR *min, D3DVECTOR *max)
    {
        int i;
        *min = *max = pts[0];
        for (i = 1; i < N; i += 1)
        {
            *min = Minimize(*min, pts[i]);
            *max = Maximize(*max, pts[i]);
        }
    }

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.

참조

Minimize


Min

이 헬퍼-함수는, 지정한 벡터의 최소 요소를 돌려준다. Min 는, D3D_OVERLOADS 를 정의하는 C++ 프로그래머가 사용할 수 있는 확장 기능 세트의 일부이다.

D3DVALUE Min (const _D3DVECTOR& v);

이 함수는, 이하와 같이 정의된다.

inline D3DVALUE
Min (const _D3DVECTOR& v)
{
   D3DVALUE ret = v.x;
   if (v.y < ret) ret = v.y;
   if (v.z < ret) ret = v.z;
   return ret;
}

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.

참조

Max


Minimize

이 헬퍼-함수는, 지정한 2 개의 벡터의 최소 요소를 포함한 벡터를 돌려준다. Minimize 는, D3D_OVERLOADS 를 정의하는 C++ 프로그래머가 사용할 수 있는 확장 기능 세트의 일부이다.

_D3DVECTOR Minimize (const _D3DVECTOR& v1, const _D3DVECTOR& v2);

이 함수는, 이하와 같이 정의된다.

inline _D3DVECTOR
Minimize (const _D3DVECTOR& v1, const _D3DVECTOR& v2)
{
   return _D3DVECTOR( v1[0] < v2[0] ?  v1[0] : v2[0],
                      v1[1] < v2[1] ?  v1[1] : v2[1],
                      v1[2] < v2[2] ?  v1[2] : v2[2]);
}

주의

이하와 같은 함수로,Maximize 및 Minimize 함수를 사용해 점의 집합을 둘러싸는 박스를 계산할 수 있다.

    void
    ComputeBoundingBox(const D3DVECTOR *pts, int N, D3DVECTOR *min, D3DVECTOR *max)
    {
        int i;
        *min = *max = pts[0];
        for (i = 1; i < N; i += 1)
        {
            *min = Minimize(*min, pts[i]);
            *max = Maximize(*max, pts[i]);
        }
    }

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.

참조

Maximize


Normalize

이 헬퍼-함수는, 지정한 벡터의 정규화한 형식 (즉, 소스와 같은 방향을 가지는 단위길이 벡터)을 돌려준다. Normalize 은, D3D_OVERLOADS 를 정의하는 C++ 프로그래머가 사용할 수 있는 확장 기능 세트의 일부이다.

_D3DVECTOR Normalize (const _D3DVECTOR& v);

이 함수는, 이하와 같이 정의된다.

inline _D3DVECTOR
Normalize (const _D3DVECTOR& v)
{
   return v / Magnitude(v);
}

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.


SquareMagnitude

이 헬퍼-함수는, 지정한 벡터의 절대치의 2 승을 돌려준다. SquareMagnitude 는, D3D_OVERLOADS 를 정의하는 C++ 프로그래머가 사용할 수 있는 확장 기능 세트의 일부이다.

D3DVALUE SquareMagnitude (const _D3DVECTOR& v);

이 함수는, 이하와 같이 정의된다.

inline D3DVALUE
SquareMagnitude (const _D3DVECTOR& v)
{
   return v.x*v.x + v.y*v.y + v.z*v.z;
}

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3d.h 로 선언.

참조

Magnitude


콜백 함수

여기에서는, Direct3D 직접 모드를 사용하는 경우에 이행이 필요한 일이 있는 콜백 함수의 레퍼런스 정보를 기술한다. 이하의 함수가 이행 된다.

  • D3DEnumDevicesCallback7
  • D3DEnumPixelFormatsCallback


D3DEnumDevicesCallback7

D3DEnumDevicesCallback7 는,Direct3D7::EnumDevices 메소드의 어플리케이션 정의 콜백 함수이다.

HRESULT CALLBACK D3DEnumDevicesCallback7(
  LPSTR lpDeviceDescription,
  LPSTR lpDeviceName,
  LPD3DDEVICEDESC7 lpD3DDeviceDesc,
  LPVOID lpContext
);

파라미터

lpDeviceDescription
디바이스의 텍스쳐 기술의 주소.
lpDeviceName
디바이스명의 주소.
lpD3DDeviceDesc
Direct3D 디바이스의 하드웨어 능력을 포함한 D3DDEVICEDESC7 구조체의 주소.
lpContext
이 콜백 함수에 건네주는 어플리케이션 정의 데이터의 주소.

반환값

열거를 반복하는 경우, 어플리케이션은 D3DENUMRET_OK 를 돌려주지 않으면 안 된다. 캔슬하는 경우는 D3DENUMRET_CANCEL 를 돌려준다.

주의

이 콜백 함수는,IDirect3D3 보다 새로운 모든 인터페이스의 D3DEnumDevicesCallback 콜백에 대신해 사용된다.

콜백 함수를 호출하는 순서를 결정할 때, 시스템은 최초로 가장 높은 계층의 오브젝트를 검색해, 다음에 그것들이 생성 된 순서로 콜백 함수를 호출한다.

데이터형 PD3DENUMDEVICESCALLBACK7 는, 이 콜백 함수에의 포인터로서 정의되고 있다.

typedef HRESULT (CALLBACK * LPD3DENUMDEVICESCALLBACK7)(
  LPSTR lpDeviceDescription, LPSTR lpDeviceName,
  LPD3DDEVICEDESC7, LPVOID);

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요

버젼 :DirectX 7.0 이 필요.
헤더 : d3dcaps.h 로 선언.


D3DEnumPixelFormatsCallback

D3DEnumPixelFormatsCallback 은,IDirect3D3::EnumZBufferFormats 및 IDirect3DDevice3::EnumTextureFormats 메소드의 어플리케이션 정의 콜백 함수이다.

HRESULT CALLBACK D3DEnumPixelFormatsCallback(
  LPDDPIXELFORMAT lpDDPixFmt,
  LPVOID          lpContext
);

파라미터

lpDDPixFmt
열거되는 픽셀 포맷을 기술하는 DDPIXELFORMAT 구조체의 주소.
lpContext
호출원으로부터 함수에게 건네지는 어플리케이션 정의 데이터의 주소.

반환값

열거를 반복하는 경우, 어플리케이션은 D3DENUMRET_OK 를 돌려주지 않으면 안 된다. 캔슬하는 경우는 D3DENUMRET_CANCEL 를 돌려준다.

주의

데이터형 LPD3DENUMPIXELFORMATSCALLBACK 는, 이 콜백 함수에의 포인터로서 정의되고 있다.

typedef HRESULT (WINAPI* LPD3DENUMPIXELFORMATSCALLBACK)(LPDDPIXELFORMAT lpDDPixFmt, LPVOID lpContext);

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 6.0 이후가 필요.
헤더 : d3dcaps.h 로 선언.


폐지된 콜백 함수

Direct3D 의 헤더 파일은, 폐지된 콜백 함수나 새로운 콜백 함수가 대신해 사용되게 된 콜백 함수를, 후방 호환성을 유지하기 위해서 선언하고 있다. 폐지되고 있어도, 그 문서는 구릴리스의 DirectX 로부터 입수할 수 있다.

D3DEnumDevicesCallback
폐지되어D3DEnumDevicesCallback7 콜백 함수가 대신해 사용된다.
D3DEnumTextureFormatsCallback
폐지되어D3DEnumPixelFormatsCallback 콜백 함수가 대신해 사용된다.
D3DValidateCallback
폐지되고 있다. 이 함수 및 실행 버퍼의 렌더링에 대해서는, 구릴리스의 DirectX 의 문서를 참조할것.


매크로

여기에서는, Direct3D 직접 모드가 제공하는 매크로의 레퍼런스 정보를 기술한다.

  • D3DCLIPPLANEn
  • D3DDivide
  • D3DFVF_TEXCOORDSIZEn
  • D3DMultiply
  • D3DRGB
  • D3DRGBA
  • D3DVAL
  • D3DVALP
  • RGB_GETBLUE
  • RGB_GETGREEN
  • RGB_GETRED
  • RGB_MAKE
  • RGB_TORGBA
  • RGBA_GETALPHA
  • RGBA_GETBLUE
  • RGBA_GETGREEN
  • RGBA_GETRED
  • RGBA_MAKE
  • RGBA_SETALPHA
  • RGBA_TORGB


D3DCLIPPLANEn

D3DCLIPPLANEn 매크로는, 유저 정의 클립면을 유효하게 하는 비트 패턴을 정의한다. 이 매크로는,D3DRENDERSTATE_CLIPPLANEENABLE 렌더링 스테이트값의 설정을 간소화하기 위해서 정의되고 있다.

#define D3DCLIPPLANE0 (1 << 0)
#define D3DCLIPPLANE1 (1 << 1)
#define D3DCLIPPLANE2 (1 << 2)
#define D3DCLIPPLANE3 (1 << 3)
#define D3DCLIPPLANE4 (1 << 4)
#define D3DCLIPPLANE5 (1 << 5)
#define D3DCLIPPLANE6 (1 << 6)
#define D3DCLIPPLANE7 (1 << 7)

파라미터

없음.

주의

유저 정의 클립면은, D3DRENDERSTATE_CLIPPLANEENABLE 렌더링 스테이트로 설정되는 DWORD 값에 1 개 또는 복수의 비트 (즉 0 은 아니다)가 저장 되고 있는 경우에 유효하게 된다. 렌더링 스테이트값의 DWORD 에 중요성은 없고, 시스템은 그 값을 번호로서 해석하지 않는다. 그 대신해,DWORD 를 해석해, 대응하는 비트가 설정된 클립면을 유효하게 한다. 비트 0 은 최초의 클립면 (인덱스 0)을 제어해, 비트 1 은 2 번째의 면을 제어한다, 라고 하는 순서로 면은 제어된다.

이러한 매크로로 생성 하는 비트 패턴은,논리합연산자로 결합하는 것으로, 동시에 복수의 클립면을 유효하게 할 수 있다. 이 편성으로부터 매크로의 어느쪽이든을 생략하는 것만으로, 그 인덱스의 클립면을 간단하게 무효로 할 수 있다.

참조

D3DRENDERSTATE_CLIPPLANEENABLE


D3DDivide

D3DDivide 매크로는, 2 수의 나눗셈을 실시한다.

D3DDivide(a, b)    (float)((double) (a) / (double) (b))

파라미터

a and b
식의 피제수와 제수.

반환값

나눗셈의 상을 돌려준다.

동작환경

Windows NT/2000 :WindowsNT 4.0 Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

D3DMultiply


D3DFVF_TEXCOORDSIZEn

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 차원)가 적용되는 텍스쳐 좌표 세트를 식별하는 값.

주의

이하의 유연한 버텍스 포맷의 기술은, 위치 좌표, 법선, 디 푸즈색, 스펙큐러색, 및 2 개의 텍스쳐 좌표 세트를 가지는 버텍스 포맷을 식별한다. 1 번째의 텍스쳐 좌표 세트에는 단일의 요소가 포함되어 2 번째세트에는 2 개의 요소가 포함된다.

DWORD dwFVF;
dwFVF = D3DFVF_XYZ | D3DFVF_NORMAL | D3DFVF_DIFFUSE | D3DFVF_SPECULAR |
        D3DFVF_TEXCOORDSIZE1(0) |  \\ 1 번째의 텍스쳐 좌표 세트 (인덱스 0)에 1D 텍스쳐 좌표를 사용한다.
        D3DFVF_TEXCOORDSIZE2(1);   \\ 2 번째의 텍스쳐 좌표 세트 (인덱스 1)에 2D 텍스쳐 좌표를 사용한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3dtypes.h 로 선언.


D3DMultiply

D3DMultiply 매크로는, 2 수의 곱셈을 실시한다.

D3DMultiply(a, b)    ((a) * (b))

파라미터

a and b
걸어 맞추는 값.

반환값

곱셈의 적을 돌려준다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

D3DDivide


D3DRGB

D3DRGB 매크로는, 지정의 RGB 값을 사용해 색을 초기화한다.

D3DRGB(r, g, b) \
    (0xff000000L | ( ((long)((r) * 255)) << 16) | \
    (((long)((g) * 255)) << 8) | (long)((b) * 255))

파라미터

r, g, and b
색의 적 (red), 초록 (green), 및 파랑 (blue)의 성분. 이러한 값은 0 에서 1 의 범위에 있는 부동 소수점값이다.

반환값

지정된 RGB 값에 대응하는 D3DCOLOR 값을 돌려준다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

D3DRGBA


D3DRGBA

D3DRGBA 매크로는, 지정의 RGBA 값을 사용해 색을 초기화한다.

D3DRGBA(r, g, b, a) \
    ((((long)((a) * 255)) << 24) |
    (((long)((r) * 255)) << 16) |
    (((long)((g) * 255)) << 8) | (long)((b) * 255))

파라미터

r, g, b, and a
색의 적 (red), 록 (green), 청 (blue), 및 알파 (alpha)의 성분.

반환값

지정된 RGBA 값에 대응하는 D3DCOLOR 값을 돌려준다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

D3DRGB


D3DVAL

D3DVAL 매크로는,D3DVALUE 형의 값을 생성한다.

D3DVAL(val)    ((float) val)

파라미터

val
트랜스 폼 대상의 값.

반환값

트랜스 폼 후의 값을 돌려준다.

동작환경

Windows NT/2000 :Winsows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

D3DVALP


D3DVALP

D3DVALP 매크로는, 지정된 정밀도의 값을 생성한다.

D3DVALP(val, prec)    ((float) val)

파라미터

val
트랜스 폼 대상의 값.
prec
무효.

반환값

트랜스 폼 후의 값을 돌려준다.

주의

D3DVAL 매크로가 이행 하는 정밀도는, 값의 소수부에 대해서 16 비트이다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

D3DVAL


RGB_GETBLUE

RGB_GETBLUE 매크로는,D3DCOLOR 값의 파랑 성분을 취득한다.

RGB_GETBLUE(rgb)    ((rgb) & 0xff)

파라미터

rgb
파랑 성분을 꺼내는 색의 인덱스.

반환값

파랑 성분을 돌려준다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


RGB_GETGREEN

RGB_GETGREEN 매크로는,D3DCOLOR 값의 초록 성분을 취득한다.

RGB_GETGREEN(rgb)    (((rgb) >> 8) & 0xff)

파라미터

rgb
초록 성분을 꺼내는 색의 인덱스.

반환값

초록 성분을 돌려준다.

동작환경

Windows NT/2000 :Winsows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


RGB_GETRED

RGB_GETRED 매크로는,D3DCOLOR 값의 빨강 성분을 취득한다.

RGB_GETRED(rgb)    (((rgb) >> 16) & 0xff)

파라미터

rgb
빨강 성분을 꺼내는 색의 인덱스.

반환값

빨강 성분을 돌려준다.

동작환경

Windows NT/2000 :Winsows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


RGB_MAKE

RGB_MAKE 매크로는, 지정된 값으로부터 RGB 색을 생성 한다.

RGB_MAKE(r, g, b)    ((D3DCOLOR) (((r) << 16) |
    ((g) << 8) | (b)))

파라미터

r, g, and b
생성 하는 색의 적 (red), 초록 (green), 파랑 (blue)의 성분. 0 에서 255 의 정수값을 지정한다.

반환값

컬러를 돌려준다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


RGB_TORGBA

RGB_TORGBA 매크로는, 지정된 RGB 색으로부터 RGBA 색을 생성한다.

RGB_TORGBA(rgb)    ((D3DCOLOR) ((rgb) | 0xff000000))

파라미터

rgb
RGBA 색에 트랜스 폼 하는 RGB 색.

반환값

RGBA 색을 돌려준다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

RGBA_TORGB


RGBA_GETALPHA

RGBA_GETALPHA 매크로는, RGBA D3DCOLOR 값의 알파 성분을 취득한다.

RGBA_GETALPHA(rgb)    ((rgb) >> 24)

파라미터

rgb
알파 성분을 꺼내는 색의 인덱스.

반환값

알파 성분을 돌려준다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


RGBA_GETBLUE

RGBA_GETBLUE 매크로는, RGBA D3DCOLOR 값의 파랑 성분을 취득한다.

RGBA_GETBLUE(rgb)    ((rgb) & 0xff)

파라미터

rgb
파랑 성분을 꺼내는 색의 인덱스.

반환값

파랑 성분을 돌려준다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


RGBA_GETGREEN

RGBA_GETGREEN 매크로는, RGBA D3DCOLOR 값의 초록 성분을 취득한다.

RGBA_GETGREEN(rgb)    (((rgb) >> 8) & 0xff)

파라미터

rgb
초록 성분을 꺼내는 색의 인덱스.

반환값

초록 성분을 돌려준다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


RGBA_GETRED

RGBA_GETRED 매크로는, RGBA D3DCOLOR 값의 빨강 성분을 취득한다.

RGBA_GETRED(rgb)    (((rgb) >> 16) & 0xff)

파라미터

rgb
빨강 성분을 꺼내는 색의 인덱스.

반환값

빨강 성분을 돌려준다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


RGBA_MAKE

RGBA_MAKE 매크로는, 지정된 적, 록, 청, 및 알파 성분으로부터 RGBA D3DCOLOR 값을 생성한다.

RGBA_MAKE(r, g, b, a)   \
 ((D3DCOLOR) (((a) << 24) | ((r) << 16) | ((g) << 8) | (b)))

파라미터

r, g, b, and a
생성 하는 RGBA 색의 적 (red), 록 (green), 청 (blue), 및 알파 (alpha)의 성분.

반환값

컬러를 돌려준다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


RGBA_SETALPHA

RGBA_SETALPHA 매크로는, RGBA D3DCOLOR 값의 알파 성분을 설정한다.

RGBA_SETALPHA(rgba, x) (((x) << 24) | ((rgba) & 0x00ffffff))

파라미터

rgba
알파 성분을 설정하는 RGBA 색.
x
설정하는 알파 성분값.

반환값

알파 성분이 설정된 RGBA 색을 돌려준다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


RGBA_TORGB

RGBA_TORGB 매크로는, 컬러의 알파 성분을 없애는 것으로, 지정된 RGBA D3DCOLOR 값으로부터 RGB D3DCOLOR 값을 생성한다.

RGBA_TORGB(rgba)    ((D3DCOLOR) ((rgba) & 0xffffff))

파라미터

rgba
RGB 색에 트랜스 폼 하는 RGBA 색.

반환값

RGB 색을 돌려준다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

RGB_TORGBA


폐지된 매크로

D3DSTATE_OVERRIDE 매크로는, 폐지된 실행 버퍼 렌더링 아키텍쳐로 사용되고 있었다. 폐지 후도, Direct3D 헤더 파일은 후방 호환성을 유지하기 위해서 매크로를 선언한다. 이 매크로 및 실행 버퍼의 상세한 것에 대하여는, 구릴리스의 DirectX 의 문서를 참조할것.


구조체

여기에서는, Direct3D 직접 모드로 사용하는 이하의 구조체에 대해 설명한다.

  • D3DCLOPSTATUS
  • D3DCOLORVALUE
  • D3DDEVICEDESC
  • D3DDEVINFO_TEXTUREMANAGER
  • D3DDEVINFO_TEXTURING
  • D3DDP_PTRSTRIDE
  • D3DDRAWPRIMITIVESTRIDEDDATA
  • D3DLIGHT
  • D3DLINEPATTERN
  • D3DVERTEX
  • D3DMATERIAL
  • D3DMATRIX
  • D3DPRIMCAPS
  • D3DRECT
  • D3DTLVERTEX
  • D3DVECTOR
  • D3DVERTEX
  • D3DVERTEXBUFFERDESC
  • D3DVIEWPORT2

주 : 모든 DirectX 구조 체용의 메모리는, 사용하기 전에 0 에 초기화할 필요가 있다. 게다가dwSize 멤버를 포함한 모든 구조체는, 사용전에, 이 멤버에 구조체의 사이즈를 바이트 단위로 설정해 두지 않으면 안 된다. 다음의 예에서는, 이러한 태스크를 공통의 구조체 DDCAPS 로 실행하고 있다.

DDCAPS ddcaps; // 아직, 사용할 수 없다.

ZeroMemory(&ddcaps, sizeof(ddcaps));
ddcaps.dwSize = sizeof(ddcaps);

// 이것으로, 구조체는 사용 가능하게 되었다.
.
.


D3DCLIPSTATUS

D3DCLIPSTATUS 구조체는, 현재의 클립 스테이터스 및 클립 영역의 extent를 기술한다. 이 구조체는 DirectX 5.0 으로 도입되었다.

typedef struct _D3DCLIPSTATUS {
    DWORD dwFlags;
    DWORD dwStatus;
    float minx, maxx;
    float miny, maxy;
    float minz, maxz;
} D3DCLIPSTATUS, *LPD3DCLIPSTATUS;

멤버

dwFlags
이 구조체가 2D 영역, 3D 영역, 또는 클립 스테이터스를 기술할지 어떨지를 나타내는 플래그. 이 멤버는, 이하의 플래그의 1 개 이상으로 할 수 있다.
D3DCLIPSTATUS_STATUS
이 구조체는 현재의 클립 스테이터스를 기술한다.
D3DCLIPSTATUS_EXTENTS2
이 구조체는 현재의 2D 영역을 기술한다. 이 플래그는 D3DCLIPSTATUS_EXTENTS3 와 조합할 수 없다.
D3DCLIPSTATUS_EXTENTS3
현재는 이행되어 있지 않다.
dwStatus
현재의 클립 스테이터스를 기술한다. 이 멤버는, 다음의 플래그의 1 개 이상을 설정한다.

편성과 일반 플래그

D3DSTATUS_CLIPINTERSECTIONALL
모든 CLIPINTERSECTION 플래그의 편성.
D3DSTATUS_CLIPUNIONALL
모든 CLIPUNION 플래그의 편성.
D3DSTATUS_DEFAULT
D3DSTATUS_CLIPINTERSECTIONALL 와 D3DSTATUS_ZNOTVISIBLE 플래그의 편성. 이 값이, 디폴트이다.
D3DSTATUS_ZNOTVISIBLE
렌더링 된 프리미티브가 불가시인 것을 나타낸다. 이 플래그는, Z 체크를 사용하는 렌더링을 실행할 때, 시스템에 의해 설정 또는 클리어 된다 (D3DRENDERSTATE_ZVISIBLE 를 참조할것).

클립 교차 플래그

D3DSTATUS_CLIPINTERSECTIONBACK
절두체의후방 클립면이라고 비교되는 버텍스의 클립 플래그의논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONBOTTOM
절두체아래라고 비교되는 버텍스의 클립 플래그의논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONFRONT
절두체의전방 클립면이라고 비교되는 버텍스의 클립 플래그의논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONGEN0 through D3DSTATUS_CLIPINTERSECTIONGEN5
어플리케이션 정의 클립면의논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONLEFT
절두체의 좌측이라고 비교되는 버텍스의 클립 플래그의논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONRIGHT
절두체의 우측이라고 비교되는 버텍스의 클립 플래그의논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONTOP
절두체 위라고 비교되는 버텍스의 클립 플래그의논리츠무를 잡는다.

클립 결합 플래그

D3DSTATUS_CLIPUNIONBACK
D3DCLIP_BACK 와 같다.
D3DSTATUS_CLIPUNIONBOTTOM
D3DCLIP_BOTTOM 와 같다.
D3DSTATUS_CLIPUNIONFRONT
D3DCLIP_FRONT 와 같다.
D3DSTATUS_CLIPUNIONGEN0 through D3DSTATUS_CLIPUNIONGEN5
D3DCLIP_GEN0 로부터 D3DCLIP_GEN5 와 같다.
D3DSTATUS_CLIPUNIONLEFT
D3DCLIP_LEFT 와 같다.
D3DSTATUS_CLIPUNIONRIGHT
D3DCLIP_RIGHT 와 같다.
D3DSTATUS_CLIPUNIONTOP
D3DCLIP_TOP 와 같다.

기본 클리핑 플래그

D3DCLIP_BACK
모든 버텍스를절두체의 뒷면에서 클리핑 한다.
D3DCLIP_BOTTOM
모든 버텍스를 절두체의 저면에서 클리핑 한다.
D3DCLIP_FRONT
모든 버텍스를 절두체의 전면에서 클리핑 한다.
D3DCLIP_LEFT
모든 버텍스를 절두체의 좌측면에서 클리핑 한다.
D3DCLIP_RIGHT
모든 버텍스를 절두체의 우측면에서 클리핑 한다.
D3DCLIP_TOP
모든 버텍스를 절두체의 표면에서 클리핑 한다.
D3DCLIP_GEN0 through D3DCLIP_GEN5
어플리케이션 정의 클립면.
minx,maxx,miny,maxy,minz,maxz
현재의 클립 영역의 X, Y, Z 의 범위.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

IDirect3DDevice7::GetClipStatus ,IDirect3DDevice7::SetClipStatus


D3DCOLORVALUE

D3DCOLORVALUE 구조체는,D3DMATERIAL7 구조체의 컬러의 값을 기술한다.

typedef struct _D3DCOLORVALUE {
    union {
        D3DVALUE r;
        D3DVALUE dvR;
    };
    union {
        D3DVALUE g;
        D3DVALUE dvG;
    };
    union {
        D3DVALUE b;
        D3DVALUE dvB;
    };
    union {
        D3DVALUE a;
        D3DVALUE dvA;
    };
} D3DCOLORVALUE;

멤버

dvR,dvG,dvB, 및 dvA
색성분의 적, 록, 청, 및 알파를 지정하는 D3DVALUE 형의 값. 일반적으로 이러한 값은 0 에서 1 까지의 값으로, 0 은 흑이다.

주의

특수한 이펙트를 내기 위해서(때문에), 이 구조체의 멤버를 0 에서 1 의 범위외의 값으로 설정할 수가 있다. 1 보다 큰 값은, 신을 조사해 흘리는 것 같은 강한 빛을 낳는다. 마이너스의 값은 어두운 빛을 낳아, 실제로는 빛을 장면으로부터 제외해 버린다. 상세한 것에 대하여는, 「컬러 라이팅」을 참조할것.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


D3DDEVICEDESC7

D3DDEVICEDESC7 구조체에는, 현재의 디바이스의 정보가 포함된다. 이 구조체는,IDirect3DDevice7::GetCaps 등의 메소드로 현재의 디바이스를 문의하기 위해서(때문에) 사용된다.

이 구조체는 IDirect3DDevice3 보다 새로운 모든 디바이스 인터페이스로 D3DDEVICEDESC 구조체에 대신해 사용된다.

typedef struct _D3DDeviceDesc7 {
    DWORD        dwDevCaps;
    D3DPRIMCAPS  dpcLineCaps;
    D3DPRIMCAPS  dpcTriCaps;
    DWORD        dwDeviceRenderBitDepth;
    DWORD        dwDeviceZBufferBitDepth;
    DWORD        dwMinTextureWidth, dwMinTextureHeight;
    DWORD        dwMaxTextureWidth, dwMaxTextureHeight;
    DWORD        dwMaxTextureRepeat;
    DWORD        dwMaxTextureAspectRatio;
    DWORD        dwMaxAnisotropy;
    D3DVALUE     dvGuardBandLeft;
    D3DVALUE     dvGuardBandTop;
    D3DVALUE     dvGuardBandRight;
    D3DVALUE     dvGuardBandBottom;
    D3DVALUE     dvExtentsAdjust;
    DWORD        dwStencilCaps;
    DWORD        dwFVFCaps;
    DWORD        dwTextureOpCaps;
    WORD         wMaxTextureBlendStages;
    WORD         wMaxSimultaneousTextures;
    DWORD        dwMaxActiveLights;
    D3DVALUE     dvMaxVertexW;
    GUID         deviceGUID;
    WORD         wMaxUserClipPlanes;
    WORD         wMaxVertexBlendMatrices;
    DWORD        dwVertexProcessingCaps;
    DWORD        dwReserved1;
    DWORD        dwReserved2;
    DWORD        dwReserved3;
    DWORD        dwReserved4;
} D3DDEVICEDESC7, *LPD3DDEVICEDESC7;

멤버

dwDevCaps
디바이스의 능력을 식별하는 플래그.
D3DDEVCAPS_CANBLTSYSTONONLOCAL
디바이스는, 시스템 메모리 텍스쳐로부터 비로컬 비디오 메모리 텍스쳐에의 블리트를 지원 한다.

이 플래그는 DirectX 7.0 으로 도입되었다.

D3DDEVCAPS_CANRENDERAFTERFLIP
디바이스는 페이지 플립의 다음에, 렌더링 커멘드를 기다릴 수도 있다. 이 플래그는 어플리케이션 동작을 바꾸는 것은 아니다. 단지 디바이스가 비교적 고속으로 있는 것을 나타내는 것이다.

이 플래그는 DirectX 5.0 으로 도입되었다.

D3DDEVCAPS_DRAWPRIMTLVERTEX
디바이스는, DrawPrimitive 대응 하드웨어 추상 계층 (HAL)을 export 한다.

이 플래그는 DirectX 5.0 으로 도입되었다.

D3DDEVCAPS_EXECUTESYSTEMMEMORY
디바이스는, 시스템 메모리로부터실행 버퍼를 사용할 수 있다.
D3DDEVCAPS_EXECUTEVIDEOMEMORY
디바이스는, 비디오 메모리로부터실행 버퍼를 사용할 수 있다.
D3DDEVCAPS_FLOATTLVERTEX
트랜스 폼 후의 버텍스 데이터를 부동 소수점으로써 취득.
D3DDEVCAPS_HWRASTERIZATION
디바이스에는, 장면의 라스터화용의 하드웨어 가속화가 있다.
D3DDEVCAPS_HWTRANSFORMANDLIGHT
디바이스는, 하드웨어로 트랜스 폼 & 라이팅을 지원 한다.

이 플래그는 DirectX 7.0 으로 도입되었다.

D3DDEVCAPS_SEPARATETEXTUREMEMORIES
디바이스는, 스테이지 마다 다른 텍스쳐 메모리 풀을 사용한다. 텍스쳐는 그 생성시에,DDSURFACEDESC2 구조체의 dwTextureStage 멤버를 적절한 스테이지 식별자로 설정하는 것으로써, 명시적으로 텍스쳐 스테이지에 할당하지 않으면 안 된다.
D3DDEVCAPS_SORTDECREASINGZ
깊이의 감소 방향으로 소트 된 데이터가 필요.
D3DDEVCAPS_SORTEXACT
정밀하게 소트 된 데이터가 필요.
D3DDEVCAPS_SORTINCREASINGZ
깊이의 증가 방향으로 소트 된 데이터가 필요.
D3DDEVCAPS_TEXTURENONLOCALVIDMEM
디바이스는, 비로컬 비디오 (AGP) 메모리로부터 텍스쳐를 취득할 수 있다.

이 플래그는 DirectX 5.0 으로 도입되었다. AGP 메모리의 상세한 것에 대하여는, DirectDraw 문서의 「비로컬 비디오 메모리 표면의 사용」을 참조할것.

D3DDEVCAPS_TEXTURESYSTEMMEMORY
시스템 메모리로부터 텍스쳐를 취득 가능.
D3DDEVCAPS_TEXTUREVIDEOMEMORY
디바이스 메모리로부터 텍스쳐를 취득 가능.
D3DDEVCAPS_TLVERTEXSYSTEMMEMORY
트랜스 폼이 끝난 라이팅 끝난 버텍스용으로, 시스템 메모리를 버퍼에 사용 가능.
D3DDEVCAPS_TLVERTEXVIDEOMEMORY
트랜스 폼이 끝난 라이팅 끝난 버텍스용으로, 비디오 메모리를 버퍼에 사용 가능.
dpcLineCaps 및 dpcTriCaps
선의 드로잉(Drawing)나 삼각형 프리미티브의 디바이스의 지원 정보를 정의하는 D3DPRIMCAPS 구조체.
dwDeviceRenderBitDepth
디바이스의 렌더링 비트 깊이. 이 멤버에는, DirectDraw 비트 깊이 정수 DDBD_8, DDBD_16, DDBD_24, 또는 DDBD_32 의 언젠가 또는 복수를 지정할 수 있다.
dwDeviceZBufferBitDepth
디바이스의 깊이 버퍼의 비트 깊이. 이 멤버에는, DirectDraw 비트 깊이 정수 DDBD_8, DDBD_16, DDBD_24, 또는 DDBD_32 의 언젠가 또는 복수를 지정할 수 있다.
dwMinTextureWidth,dwMinTextureHeight
이 디바이스의 텍스쳐의 최소의 폭과 높이.
dwMaxTextureWidth,dwMaxTextureHeight
이 디바이스의 텍스쳐의 최대의 폭과 높이.
dwMaxTextureRepeat
정규화한 후의 텍스쳐 인덱스의 정수 비트의 전범위. D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE 비트가 설정되어 있는 경우, 디바이스는, 텍스쳐 addressing mode가 적용될 때까지 텍스쳐 사이즈에 의한 스케일링을 실시하지 않는다. 이것이 설정되어 있지 않은 경우는, 디바이스는 텍스쳐 사이즈 (최대 상세 레벨)에 의한 텍스쳐 인덱스의 스케일링을 실행하고 나서 보간을 실시한다.
dwMaxTextureAspectRatio
하드웨어에 의해 지원 되는, 텍스쳐의 최대 어스펙트비(가로세로 비율). 보통은 2 의 거듭제곱.
dwMaxAnisotropy
D3DTSS_MAXANISOTROPY 텍스쳐 스테이지 스테이트의 최대 유효값.
dvGuardBandLeft,dvGuardBandTop,dvGuardBandRight 및 dvGuardBandBottom
가이드 밴드 클리핑 영역의 화면 공간 좌표. 이 직사각형내 또한 뷰포트 직사각형의 외측에 있는 좌표는 자동적으로 클리핑 된다.
dvExtentsAdjust
직사각형의 외변을 에일리어징 제거 커널에 적합시키기 위한 픽셀수.
dwStencilCaps
지원 되고 있는 스텐실 버퍼 조작을 지정하는 플래그. 스텐실 조작은 3 종류의 스텐실 버퍼 조작 렌더링 스테이트 (D3DRENDERSTATE_STENCILFAIL, D3DRENDERSTATE_STENCILPASS, D3DRENDERSTATE_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 처리를 지원 한다.
dwFVFCaps
유연한 버텍스 포맷 능력
D3DFVFCAPS_DONOTSTRIPELEMENTS
버텍스 요소는 삭제하지 않는 것이 좋다. 즉, 버텍스 포맷이 현재의 렌더링 스테이트에서 사용되지 않는 요소를 포함하고 있어도, 버텍스를 재차 생성할 필요는 없다. 이 능력 플래그가 지정되어 있지 않은 경우, 버텍스 포맷화등 불필요한 요소를 삭제 하면, 퍼포먼스가 향상한다.
D3DFVFCAPS_TEXCOORDCOUNTMASK
dwFVFCaps 의 하위 WORD 를 마스크 한다. 이 비트는,WORD 데이터형에 캐스트 되어 디바이스가 복수의 텍스쳐 블렌딩에 동시에 사용할 수 있는 텍스쳐 좌표 세트의 총수를 나타낸다(어느 버텍스에 대해서도 최대 8 개의 텍스쳐 좌표 세트를 사용할 수 있지만, 디바이스에서는 지정된 개수의 텍스쳐 좌표 세트만 블렌딩 한다).
dwTextureOpCaps
이 디바이스가 지원 하는 텍스쳐 조작을 기술하는 플래그의 편성. 다음의 플래그가 정의된다.
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_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_PREMODULATE
D3DTOP_PREMODULATE 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_SELECTARG1
D3DTOP_SELECTARG1 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_SELECTARG2
D3DTOP_SELECTARG2 텍스쳐 블렌딩 처리가 지원 된다.
D3DTEXOPCAPS_SUBTRACT
D3DTOP_SUBTRACT 텍스쳐 블렌딩 처리가 지원 된다.
wMaxTextureBlendStages
지원 되는 텍스쳐 블렌딩 스테이지의 최대수.
wMaxSimultaneousTextures
텍스쳐 블렌딩 스테이지에 동시에 바인드 할 수 있는 텍스쳐의 최대수. 「주의」를 참조할것.
dwMaxActiveLights
동시에 액티브하게 할 수 있는 라이트의 최대수.
dvMaxVertexW
디바이스가 지원 하는 최대 W 베이스 깊이값.
deviceGUID
디바이스의 글로벌 유니크 식별자 (GUI). IID_IDirect3DHALDevice, IID_IDirect3DTnLHalDevice, 또는 IID_IDirect3DRGBDevice 의 언젠가.
wMaxUserClipPlanes
지원 되는 유저 정의 클립면의 최대수. 이 멤버는 0 으로부터 D3DMAXUSERCLIPPLANES 까지의 범위가 된다.

유저 정의 클립면의 조작에는,IDirect3DDevice7::GetClipPlane 및 IDirect3DDevice7::SetClipPlane 메소드를 사용한다.

wMaxVertexBlendMatrices
복수의 행렬에 의한 버텍스 블렌딩을 실행할 때에 디바이스가 적용하는 배열의 최대수.
dwVertexProcessingCaps
버텍스의 처리 능력.
D3DVTXPCAPS_TEXGEN
디바이스는 텍스쳐 좌표를 생성할 수 있다.
D3DVTXPCAPS_MATERIALSOURCE7
디바이스는 선택 가능한 버텍스색소스를 지원 한다. 상세한 것에 대하여는, 「라이트의 색의 종류와 소스」를 참조할것.
D3DVTXPCAPS_VERTEXFOG
디바이스는 버텍스 포그(안개:fog)를 지원 한다.
D3DVTXPCAPS_DIRECTIONALLIGHTS
디바이스는 디렉셔널 라이트를 지원 한다.
D3DVTXPCAPS_POSITIONALLIGHTS
디바이스는 국부 라이트 (포인트 라이트, spotlight등)를 지원 한다.
D3DVTXPCAPS_LOCALVIEWER
디바이스는 로카르뷰아를 지원 한다.
dwReserved1 로부터 dwReserved4
예약이 끝난 상태.

주의

wMaxTextureBlendStages 및 wMaxSimultaneousTextures 멤버는 유사하고 있는 것처럼 생각되지만, 서로 다른 정보를 포함하고 있다. wMaxTextureBlendStages 멤버는, 현재의 디바이스로 지원 되는 텍스쳐 블렌딩 스테이지의 총수를 나타낸다. wMaxSimultaneousTextures 멤버는,IDirect3DDevice7::SetTexture 메소드에 의해 이러한 스테이지중 몇개의 스테이지에서 텍스쳐를 바인드 할 수 있는지를 나타낸다.

드라이버에서는, 이 구조체에 값을 설정 하면, 능력의 취득에 사용하는 인터페이스 (IDirect3DDevice7 등)가 실행 버퍼를 지원 하고 있지 않아도, 실행 버퍼 능력의 값을 설정할 수 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3dcaps.h 로 선언.

참조

D3DPRIMCAPS


D3DDEVINFO_TEXTUREMANAGER

D3DDEVINFO_TEXTUREMANAGER 구조체는, 텍스쳐 매니저의 현재의 스테이트에 대한 정보를 저장 한다. 이 구조체는 IDirect3DDevice7::GetInfo 메소드로 사용된다.

typedef struct _D3DDEVINFO_TEXTUREMANAGER {
    BOOL    bThrashing;
    DWORD   dwNumEvicts;
    DWORD   dwNumVidCreates;
    DWORD   dwNumTexturesUsed;
    DWORD   dwNumUsedTexInVid;
    DWORD   dwWorkingSet;
    DWORD   dwWorkingSetBytes;
    DWORD   dwTotalManaged;
    DWORD   dwTotalBytes;
    DWORD   dwLastPri;
} D3DDEVINFO_TEXTUREMANAGER, *LPD3DDEVINFO_TEXTUREMANAGER;

멤버

bThrashing
쓰레싱 스테이트. 마지막 프레임으로 쓰레싱이 발생했을 경우는 TRUE, 그렇지 않은 경우는 FALSE.
dwNumEvicts
마지막 프레임으로 삭제된 텍스쳐의 개수.
dwNumVidCreates
마지막 프레임으로 비디오 메모리에 생성 된 텍스쳐의 개수.
dwNumTexturesUsed
마지막 프레임으로 사용된 텍스쳐의 총수.
dwNumUsedTexInVid
마지막 프레임으로 사용된 비디오 메모리 텍스쳐의 개수.
dwWorkingSet
비디오 메모리에 현재 존재하는 텍스쳐의 개수.
dwWorkingSetBytes
비디오 메모리에 존재하는 텍스쳐에 의해 현재 할당할 수 있고 있는 바이트수.
dwTotalManaged
관리하의 텍스쳐의 총수.
dwTotalBytes
관리하의 텍스쳐에 할당할 수 있고 있는 총바이트수.
dwLastPri
마지막에 삭제된 텍스쳐의 우선 순위.

주의

비디오 메모리 (로컬 또는 비로컬)에 존재하는, 마지막 프레임으로 사용된 텍스쳐의 비율을 요구하려면 ,dwNumUsedTexInVid 및 dwNumTexturesUsed 의 값을 사용한다. 이하에 나타내는 코드는, 이 계산방법을 나타낸다.

// 이 예에서는, d3dtminfo 변수는
// IDirect3DDevice7::GetInfo 의 호출에 의해 저장 된 D3DDEVINFO_TEXTUREMANAGER 구조체이다.

DWORD dwHitRate;

// 비디오 메모리내에서 사용된 텍스쳐의 비율을 취득한다.
dwHitRate = (d3dtminfo.dwNumUsedTexInVid * 100) / d3dtminfo.dwNumTexturesUsed;

참조

IDirect3DDevice7::GetInfo


D3DDEVINFO_TEXTURING

D3DDEVINFO_TEXTURING 구조체는, 어플리케이션의 텍스쳐 처리 액티버티에 대한 정보를 저장 한다. 이 구조체는 IDirect3DDevice7::GetInfo 메소드로 사용된다.

typedef struct _D3DDEVINFO_TEXTURING {
    DWORD   dwNumLoads;
    DWORD   dwApproxBytesLoaded;
    DWORD   dwNumPreLoads;
    DWORD   dwNumSet;
    DWORD   dwNumCreates;
    DWORD   dwNumDestroys;
    DWORD   dwNumSetPriorities;
    DWORD   dwNumSetLODs;
    DWORD   dwNumLocks;
    DWORD   dwNumGetDCs;
} D3DDEVINFO_TEXTURING, *LPD3DDEVINFO_TEXTURING;

멤버

dwNumLoads
IDirect3DDevice7::Load 메소드의 호출에 의해 텍스쳐가 로드 된 회수.
dwApproxBytesLoaded
IDirect3DDevice7::Load 메소드의 호출에 의해 로드 된 대략의 바이트수.
dwNumPreLoads
IDirect3DDevice7::PreLoad 메소드의 호출에 의해 관리하의 텍스쳐가 명시적으로 로드 된 회수.
dwNumSet
IDirect3DDevice7::SetTexture 메소드의 호출에 의해 텍스쳐가 텍스쳐 블렌딩 스테이지로 설정된 회수.
dwNumCreates
어플리케이션에 의해 생성 된 텍스쳐 표면의 개수.
dwNumDestroys
어플리케이션에 의해 파기 (릴리즈)된 텍스쳐의 개수.
dwNumSetPriorities
IDirectDrawSurface7::SetPriority 메소드의 호출에 의해 텍스쳐 관리 우선 순위가 설정된 회수.
dwNumSetLODs
IDirectDrawSurface7::SetLOD 메소드의 호출에 의해 밉맵의 최대 상세 레벨이 설정된 회수.
dwNumLocks
IDirectDrawSurface7::Lock 메소드의 호출에 의해 텍스쳐 표면이 락 된 회수.
dwNumGetDCs
IDirectDrawSurface7::GetDC 메소드의 호출에 의해 텍스쳐 표면의 디바이스 콘텍스트가 취득된 회수.

참조

IDirect3DDevice7::GetInfo


D3DDP_PTRSTRIDE

D3DDP_PTRSTRIDE 구조체는, 유연한 버텍스 포맷 컴퍼넌트 배열의 주소와 배열중의 다음의 요소에의 보폭을 포함한다. 이 구조체는 D3DDRAWPRIMITIVESTRIDEDDATA 구조체에 포함된다.

typedef struct _D3DDP_PTRSTRIDE {
    LPVOID lpvData;
    DWORD  dwStride;
} D3DDP_PTRSTRIDE;

멤버

lpvData
데이터 배열의 주소.
dwStride
배열의 요소간의 메모리 보폭.

주의

이 구조체는, (D3DLVERTEX 구조체 등) 혼성 버텍스 포맷, 또는 명확하게 분리된 버텍스 성분 배열로 사용할 수 있다. 혼성 버텍스 포맷에서는,lpvData 는 특정의 컴퍼넌트를 포인트 해,dwStride 는 혼성 형식의 보폭을 바이트 단위로 나타낸다. 버텍스 성분을 1 개만 포함한 배열의 경우,dwStride 는 배열의 각 요소의 보폭이 된다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 6.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

D3DDRAWPRIMITIVESTRIDEDDATA ,보폭 버텍스 포맷


D3DDRAWPRIMITIVESTRIDEDDATA

D3DDRAWPRIMITIVESTRIDEDDATA 구조체는, 유연한 버텍스 포맷 컴퍼넌트를 포함한다.

typedef struct D3DDRAWPRIMITIVESTRIDEDDATA  {
    D3DDP_PTRSTRIDE position;
    D3DDP_PTRSTRIDE normal;
    D3DDP_PTRSTRIDE diffuse;
    D3DDP_PTRSTRIDE specular;
    D3DDP_PTRSTRIDE textureCoords[D3DDP_MAXTEXCOORD];
} D3DDRAWPRIMITIVESTRIDEDDATA , *LPD3DDRAWPRIMITIVESTRIDEDDATA;

멤버

position 및 normal
D3DDP_PTRSTRIDE 구조체. 버텍스의 집합의 위치 좌표 벡터 및 법선 벡터의 배열을 포인트 한다 ( 각 벡터는 3 요소로 구성되는 부동 소수점의 배열).
diffuse 및 specular
D3DDP_PTRSTRIDE 구조체. 버텍스 집합의 디 푸즈색 및 스펙큐러 색정보를 가리킨다. 각각의 색성분은 8-8-8-8 RGBA 값이다.
textureCoords
8 요소로 구성되는,D3DDP_PTRSTRIDE 구조체의 배열. 배열의 각각의 요소는, 버텍스 집합의 텍스쳐 좌표 배열이다. 지정된 텍스쳐 스테이지에 대해서 어느 텍스쳐 좌표 배열을 사용할까는, D3DTSS_TEXCOORDINDEX 스테이지 스테이트값으로 IDirect3DDevice7::SetTextureStageState 메소드를 호출해 결정한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 6.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

D3DDP_PTRSTRIDE ,보폭 버텍스 포맷,버텍스 포맷


D3DLIGHT7

D3DLIGHT7 구조체는, 라이트 프로퍼티세트를 정의한다. 이 구조체는 IDirect3DDevice7::GetLight 및 IDirect3DDevice7::SetLight 메소드로 사용된다.

typedef struct _D3DLIGHT7 {
    D3DLIGHTTYPE    dltType;
    D3DCOLORVALUE   dcvDiffuse;
    D3DCOLORVALUE   dcvSpecular;
    D3DCOLORVALUE   dcvAmbient;
    D3DVECTOR       dvPosition;
    D3DVECTOR       dvDirection;
    D3DVALUE        dvRange;
    D3DVALUE        dvFalloff;
    D3DVALUE        dvAttenuation0;
    D3DVALUE        dvAttenuation1;
    D3DVALUE        dvAttenuation2;
    D3DVALUE        dvTheta;
    D3DVALUE        dvPhi;
} D3DLIGHT7, *LPD3DLIGHT7;

멤버

dltType
광원의 형태. 이 값은 D3DLIGHTTYPE 열거형의 멤버의 언젠가이다.
dcvDiffuse
광원이 방출하는 디 푸즈색. 이 멤버는 D3DCOLORVALUE 구조체이다.
dcvSpecular
광원이 방출하는 스펙큐러색. 이 멤버는 D3DCOLORVALUE 구조체이다.
dcvAmbient
광원이 방출하는 앰비언트색. 이 멤버는 D3DCOLORVALUE 구조체이다.
dvPosition
월드 공간에서의 광원의 위치 좌표. 이 멤버는, 디렉셔널 라이트에 있어 의미가 없고, 이 케이스에서는 무시된다.
dvDirection
월드 공간에서 빛이 가리킬 방향. 이 멤버는, 디렉셔널 라이트 및 spotlight의 경우에게만 의미를 가진다. 이 벡터는 정규화할 필요는 없지만, 제로가 아닌 길이를 가지지 않으면 안 된다.
dvRange
광원의 유효 거리. 이 멤버의 최대 허용값은 D3DLIGHT_RANGE_MAX 로, FLT_MAX 의 제곱근으로서 정의된다. 이 멤버는 디렉셔널 라이트에게는 영향을 주지 않는다.
dvFalloff
spotlight의 내부 콘 (dvTheta 로 지정되는 각도)과 외부 콘의 외측 엣지 (dvPhi 로 지정되는 각도)와의 사이에 휘도(Luminance)가 폴 오프 한다. 이 기능은, DirectX 5.0 에는 이행되어 있지 않다. dvFalloff 의 값에 의한 spotlight의 변화의 상세한 것에 대하여는, 「spotlight 폴 오프 모델」을 참조할것.

라이팅에 대한 폴 오프의 영향은 미묘하다. 게다가 폴 오프 곡선을 그리면(자) 다소의 성능 위에의 로스를 입는다. 이러한 이유에 의해, 많은 개발자는 이 값을 1.0 에 세트 한다.

dvAttenuation0,dvAttenuation1, 및 dvAttenuation2
빛의 휘도(Luminance)가 거리에 의해 어떻게 변화하는지를 지정하는 값 (디렉셔널 라이트는 감쇠하지 않는다). 이러한 멤버는 감쇠 정수를 나타낸다. 이러한 감쇠값에 의한 빛의 변화의 상세한 것에 대하여는, 「거리의 증가에 의한 라이트의 감쇠」를 참조할것. 이러한 멤버에 유효한 값의 범위는 0.0 으로부터 무한대이다.
dvTheta
spotlight의 내부 콘, 즉 충분히 빛으로 비추어지고 있는 spotlight 콘의 각도를 라디안 단위로 나타낸다. 이 값은, 0 으로부터 dvPhi 에 의한 지정값의 범위에 없으면 안 된다.
dvPhi
spotlight의 밖원추의 외측의 엣지를 정의하는 각도를 라디안 단위로 나타낸다. 이 원추의 외측에 있는 점은 spotlight로 라이팅 되지 않는다. 이 값은 0 으로부터 pi 의 범위에 없으면 안 된다.

주의

DirectX 7.0 으로 도입된 이 구조체는, 구버젼의 DirectX 로 사용된 D3DLIGHT2 및 D3DLIGHT 구조체에 대신해 사용된다.

이 구조체가 D3DLIGHT2 구조체와 다른 것은, 라이트 디 푸즈색, 스펙큐러색, 및 앰비언트색을 각각에 멤버로 지정하는 점이다. 각 컬러값은, Direct3D 직접 모드의 라이팅 모듈로 장면의 라이팅을 결정할 때에 사용된다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3dtypes.h 로 선언.

참조

IDirect3DDevice7::GetLight ,IDirect3DDevice7::SetLight ,D3DLIGHTTYPE ,라이팅과 머트리얼


D3DLINEPATTERN

D3DLINEPATTERN 구조체는, 직선 패턴을 나타낸다. 이러한 값은,D3DRENDERSTATETYPE 열거형의 D3DRENDERSTATE_LINEPATTERN 렌더링 스테이트에 의해 사용된다.

typedef struct _D3DLINEPATTERN {
    WORD wRepeatFactor;
    WORD wLinePattern;
} D3DLINEPATTERN;

멤버

wRepeatFactor
wLinePattern 멤버로 지정하는 1 및 0 의 연속을 반복하는 회수. 이것에 의해, 어플리케이션에서는 선패턴을 신축(스트레치) 할 수 있다.
wLinePattern
선패턴을 지정하는 비트. 예를 들어, 이하의 값은, 닷 라인을 생성한다. 1100110011001100.

주의

선패턴은 선의 그리는 방법을 지정한다. 선패턴은, 기점의 위치에 관계없이 항상 같다 (이것은 점묘와는 다르다. 점묘는 오브젝트의 렌더링 방법, 즉 투과성의 표현 방법으로 영향을 준다).

선패턴은, 선에 따라, 온/오프 하는 픽셀의 16 픽셀의 패턴을 지정한다. wRepeatFactor 멤버로 wLinePattern 에 넣을 때의 픽셀의 반복수를 지정한다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 및 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


D3DLVERTEX

D3DLVERTEX 구조체는, 「트랜스폼 되지 않은 라이팅 끝난 버텍스」 (색첨부의모델 좌표)을 정의한다. Direct3D 로 버텍스 트랜스 폼을 처리하는 경우는, 이 구조체를 사용할 필요가 있다. 이 구조체는, 소프트웨어 라이팅이 설정하는 데이터와 색만을 저장 한다.

typedef struct _D3DLVERTEX {
    union {
        D3DVALUE x;
        D3DVALUE dvX;
    };
    union {
        D3DVALUE y;
        D3DVALUE dvY;
    };
    union {
        D3DVALUE z;
        D3DVALUE dvZ;
    };
    DWORD        dwReserved;
    union {
        D3DCOLOR color;
        D3DCOLOR dcColor;
    };
    union {
        D3DCOLOR specular;
        D3DCOLOR dcSpecular;
    };
    union {
        D3DVALUE tu;
        D3DVALUE dvTU;
    };
    union {
        D3DVALUE tv;
        D3DVALUE dvTV;
    };
} D3DLVERTEX, *LPD3DLVERTEX;

멤버

dvX,dvY 및 dvZ
버텍스의 모델 좌표를 지정하는 D3DVALUE 형의 값.
dwReserved
예약이 끝난 상태. 0 으로 설정한다.
dcColor 및 dcSpecular
버텍스의 색 및 스펙큐러 성분을 지정하는 D3DCOLOR 형의 값.
dvTU 및 dvTV
버텍스의텍스쳐 좌표를 지정하는 D3DVALUE 형의 값.

주의

D3DRENDERSTATE_SPECULARENABLE 가 TRUE 의 경우, 텍스쳐 cascade와 알파 블렌딩의 사이, 베이스 컬러에 스펙큐러 성분이 추가된다. 다만, DirectX 7.0 에서는 D3DTA_SPECULAR 플래그를 설정 하면, 텍스쳐색의 처리중에, 적용하는 스펙큐러 성분을 할당할 수가 있다. 상세한 것에 대하여는, 「텍스쳐 인수 플래그」를 참조할것.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

D3DTLVERTEX ,D3DVERTEX


D3DMATERIAL7

D3DMATERIAL7 구조체는,IDirect3DDevice7::GetMaterial 및 IDirect3DDevice7::SetMaterial 메소드의 호출의 머트리얼 프로퍼티를 지정한다.

typedef struct _D3DMATERIAL7 {
    union {
        D3DCOLORVALUE   diffuse;
        D3DCOLORVALUE   dcvDiffuse;
    };
    union {
        D3DCOLORVALUE   ambient;
        D3DCOLORVALUE   dcvAmbient;
    };
    union {
        D3DCOLORVALUE   specular;
        D3DCOLORVALUE   dcvSpecular;
    };
    union {
        D3DCOLORVALUE   emissive;
        D3DCOLORVALUE   dcvEmissive;
    };
    union {
        D3DVALUE        power;
        D3DVALUE        dvPower;
    };
} D3DMATERIAL7, *LPD3DMATERIAL7;

멤버

dcvDiffuse,dcvAmbient,dcvSpecular, 및 dcvEmissive
각각, 머트리얼의 디 푸즈색, 앰비언트색, 스펙큐러색, 에미션(emission)색을 지정하는 값. 이러한 값은 D3DCOLORVALUE 구조체이다.
dvPower
스펙큐러 하이라이트의 선명도를 지정하는 D3DVALUE 형의 값. 머트리얼의 스펙큐러 하이라이트를 오프로 하려면 , 이 멤버를 0 으로 설정한다. 스펙큐러색성분을 0 으로 설정하는 것 만으로는 불충분하다.

주의

DirectX 7.0 으로 도입된 이 구조체는, 구버젼의 DirectX 로 사용된 D3DMATERIAL 구조체에 대신해 사용된다.

이 구조체가 종래의 D3DMATERIAL 구조체와 다른 것은, 텍스쳐 핸들 (텍스쳐 처리된 뷰포트 백그라운드) 또는 종래의 램프 소프트웨어 디바이스의 램프 사이즈를 지원 하지 않는 점이다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3dtypes.h 로 선언.

참조

IDirect3DDevice7::GetMaterial ,IDirect3DDevice7::SetMaterial ,라이팅과 머트리얼


D3DMATRIX

D3DMATRIX 구조체는,IDirect3DDevice7::MultiplyTransform ,IDirect3DDevice7::GetTransform ,IDirect3DDevice7::SetTransform 등의 메소드의 행렬을 기술한다.

C++ 프로그래머는, 외모 ("()") 연산자를 저장 하는 이 구조체의 확장판을 사용할 수가 있다. 상세한 것에 대하여는, 「D3DMATRIX (D3D_OVERLOADS) 」를 참조할것.

typedef struct _D3DMATRIX {
    D3DVALUE _11, _12, _13, _14;
    D3DVALUE _21, _22, _23, _24;
    D3DVALUE _31, _32, _33, _34;
    D3DVALUE _41, _42, _43, _44;
} D3DMATRIX, *LPD3DMATRIX;

주의

Direct3D 에서는, 투영 행렬의 _34 요소는 부로 할 수 없다. 여기서 부의 값을 사용할 필요가 있는 경우는, 대신에 투영 행렬 전체를 -1 로 기준화한다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

IDirect3DDevice7::MultiplyTransform ,IDirect3DDevice7::GetTransform ,IDirect3DDevice7::SetTransform


D3DPRIMCAPS

D3DPRIMCAPS 구조체는, 각각의 프리미티브형의 능력을 정의한다. 디바이스의 생성시나 디바이스의 능력을 취득할 경우에 사용된다. 이 구조체는,D3DDEVICEDESC7 구조체의 일부의 멤버를 정의한다.

typedef struct _D3DPrimCaps {
    DWORD dwSize;               // 구조체의 사이즈.
    DWORD dwMiscCaps;           // 그 외의 능력.
    DWORD dwRasterCaps;         // 라스터 능력.
    DWORD dwZCmpCaps;           // Z 비교 능력.
    DWORD dwSrcBlendCaps;       // 소스 블렌딩 능력.
    DWORD dwDestBlendCaps;      // 목적지 블렌딩 능력.
    DWORD dwAlphaCmpCaps;       // 알파 테스트 비교 능력.
    DWORD dwShadeCaps;          // 쉐이딩 능력.
    DWORD dwTextureCaps;        // 텍스쳐 능력.
    DWORD dwTextureFilterCaps;  // 텍스쳐 필터링 능력.
    DWORD dwTextureBlendCaps;   // 텍스쳐 블렌딩 능력.
    DWORD dwTextureAddressCaps; // 텍스쳐 애드레싱 능력.
    DWORD dwStippleWidth;       // 점묘의 폭.
    DWORD dwStippleHeight;      // 점묘의 높이.
} D3DPRIMCAPS, *LPD3DPRIMCAPS;

멤버

dwSize
이 구조체의 바이트 단위의 사이즈. 이 멤버는 구조체가 사용되기 전에 초기화해야 한다.
dwMiscCaps
이 프리미티브의 총체적인 능력. 이 멤버는, 다음의 값을 1 개 이상 설정할 수 있다.
D3DPMISCCAPS_CONFORMANT
디바이스는, OpenGL 표준에 준하고 있다.
D3DPMISCCAPS_CULLCCW
드라이버는, D3DRENDERSTATE_CULLMODE 스테이트를 사용해 반시계회전의 컬링(Culling)를 지원 한다 (이것은 삼각형 원시적으로 마셔 적용된다). D3DCULL 열거형의 D3DCULL_CCW 멤버에 대응한다.
D3DPMISCCAPS_CULLCW
드라이버는, D3DRENDERSTATE_CULLMODE 스테이트를 사용해 시계회전의 컬링(Culling) 지원 한다 (이것은 삼각형 원시적으로 마셔 적용된다). D3DCULL 열거형의 D3DCULL_CCW 멤버에 대응한다.
D3DPMISCCAPS_CULLNONE
드라이버는, 선택하고 있는 삼각형을 실행할 수 없다. D3DCULL 열거형의 D3DCULL_NONE 멤버에 대응한다.
D3DPMISCCAPS_LINEPATTERNREP
드라이버는,D3DLINEPATTERN 구조체의 wRepeatFactor 멤버로 1 이외의 값을 처리할 수 있다 (이것은 선묘화 원시적으로 마셔 적용된다).
D3DPMISCCAPS_MASKPLANES
디바이스는, 색의 비트 마스크를 실행할 수 있다.
D3DPMISCCAPS_MASKZ
디바이스는, 픽셀 조작의 깊이 버퍼 변경을 유효하게 하거나 무효로 하거나 할 수 있다.
dwRasterCaps
라스터 드로잉(Drawing)의 능력 정보. 이 멤버는, 다음의 값을 1 개 이상 설정할 수 있다.
D3DPRASTERCAPS_ANISOTROPY
디바이스는 비등방성 필터링을 지원 한다. 상세한 것에 대하여는,D3DRENDERSTATETYPE 구조체의 「D3DRENDERSTATE_ANISOTROPY 」를 참조할것.

이 플래그는 DirectX 5.0 으로 도입되었다.

D3DPRASTERCAPS_ANTIALIASEDGES
디바이스는, 오브젝트의 윤곽선이 볼록한 모양이 되는 것 같은 에일리어징 제거선을 만들 수가 있다. 상세한 것에 대하여는,D3DRENDERSTATETYPE 구조체의 「D3DRENDERSTATE_EDGEANTIALIAS 」를 참조할것.

이 플래그는 DirectX 5.0 으로 도입되었다.

D3DPRASTERCAPS_ANTIALIASSORTDEPENDENT
디바이스는, 다각형의 소트순서 (후방에서 전방, 또는 전방에서 후방)에 의존하는 anti-aliasing를 지원 한다. 어플리케이션은, anti-aliasing가 생기는 것에 갖추어 올바른 순서로 다각형을 작도 해야 한다. 상세한 것에 대하여는, 「D3DANTIALIASMODE 」열거형을 참조할것.

이 플래그는 DirectX 5.0 으로 도입되었다.

D3DPRASTERCAPS_ANTIALIASSORTINDEPENDENT
디바이스는, 다각형의 소트순서에 의하지 않는 anti-aliasing를 지원 한다. 상세한 것에 대하여는, 「D3DANTIALIASMODE 」열거형을 참조할것.

이 플래그는 DirectX 5.0 으로 도입되었다.

D3DPRASTERCAPS_DITHER
디바이스는, 색의 재현력을 자주(잘) 하기 위해서 dither 표시할 수 있다.
D3DPRASTERCAPS_FOGRANGE
디바이스는 범위 준거의 포그(안개:fog)를 지원 한다. 범위 준거의 포그(안개:fog)에서는, 장면에 있어서의 오브젝트의 깊이 (z 좌표)는 아니고, 오브젝트의 뷰아로부터의 거리로 포그(안개:fog) 이펙트를 계산한다. 상세한 것에 대하여는, 「범위 베이스의 포그(안개:fog)」를 참조할것.

이 플래그는 DirectX 5.0 으로 도입되었다.

D3DPRASTERCAPS_FOGTABLE
디바이스는, 픽셀의 깊이를 가리키는 포그(안개:fog)값을 트랜스 폼 하는 취득 테이블과 조합해, 포그(안개:fog)값을 산출한다.
D3DPRASTERCAPS_FOGVERTEX
디바이스는 라이팅 처리동안 포그(안개:fog)값을 계산해,D3DTLVERTEX 구조체의 specular 멤버로 주어진 D3DCOLOR 값의 알파 성분중의 값에 옮겨놓아 라스터의 사이 포그(안개:fog)값을 보간 한다.
D3DPRASTERCAPS_MIPMAPLODBIAS
디바이스는 상세 레벨 (LOD) 바이어스 조정을 지원 한다. 이러한 바이어스 조정으로, 어플리케이션이 밉맵을 보통보다 깨끗이또는 그다지 날카롭지 않게 보이게 할 수가 있게 된다. 밉맵의 LOD 바이어스의 상세한 것에 대하여는, 「D3DRENDERSTATE_MIPMAPLODBIAS 」를 참조할것.
D3DPRASTERCAPS_PAT
드라이버는, 패턴 드로잉(Drawing)를 처리할 수 있다. (D3DRENDERSTATE_LINEPATTERN 나 D3DRENDERSTATE_STIPPLEPATTERN 렌더링 스테이트의 1 개에서의 선묘나 전부 칠해) 프리미티브용으로 조회된다.
D3DPRASTERCAPS_ROP2
디바이스는, R2_COPYPEN 이외의 라스터화를 지원 할 수 있다.
D3DPRASTERCAPS_STIPPLE
디바이스는, 반투명을 시뮬레이트 하는 다각형을 점묘 할 수 있다.
D3DPRASTERCAPS_SUBPIXEL
디바이스는, 제일 가까운 정수형의 픽셀 좌표가 아니고, Z, 색, 텍스쳐의 데이터의 서브 픽셀 배치로 처리한다. 이것은, Z 의 bleed선을 피하는 것을 돕는다 (색의 지터와 픽셀의 텍스쳐값도). 유효 및 무효에 대응하는 스테이트는 없고, 디바이스는 서브 픽셀 배치를 실행할까 하지 않는가의 언젠가이다. 이 비트는, 보다 고품질인 렌더링의 결정을 위해서(때문에) 존재한다.
D3DPRASTERCAPS_SUBPIXELX
디바이스는, X 축으로 따른 서브 픽셀 배치이며, 정수형의 Y 축의 주사선을 쌓아올린 것이다. 서브 픽셀 배치에 대한 자세한 것은, D3DPRASTERCAPS_SUBPIXEL를 참조할것.
D3DPRASTERCAPS_TRANSLUCENTSORTINDEPENDENT
디바이스는, 다각형의 소트순서에 의존하지 않는 반투명 표시를 지원 한다. 상세한 것에 대하여는, 「D3DRENDERSTATE_TRANSLUCENTSORTINDEPENDENT 」를 참조할것.
D3DPRASTERCAPS_WBUFFER
디바이스는 W 를 사용하는 깊이 버퍼링을 지원 한다. 상세한 것에 대하여는, 「깊이 버퍼」를 참조할것.
D3DPRASTERCAPS_WFOG
디바이스는 w 준거의 포그(안개:fog)를 지원 한다. W 베이스의 포그(안개:fog)는, 퍼스펙티브 투영 행렬이 지정되었을 경우에 사용되지만, 아핀 투영에서는 현재에도 Z 베이스의 포그(안개:fog)가 사용된다. [3][4] 요소에 제로 이외의 값이 있는 투영 행렬이 퍼스펙티브 투영 행렬이라고 보여진다.
D3DPRASTERCAPS_XOR
디바이스는 배타적 논리합 처리 (XOR)를 지원 한다. 이 플래그는 아니고 D3DPRIM_RASTER_ROP2 를 설정하는 경우는,배타적 논리합처리가 지원 되고 있을 필요가 있다.
D3DPRASTERCAPS_ZBIAS
디바이스는 z 바이어스값을 지원 한다. 이것들은 평면을 공유하는 다각형을 다른 것에 보이도록, 다각형에 할당할 수 있었던 정수값이다. 상세한 것에 대하여는,D3DRENDERSTATETYPE 열거형의 「D3DRENDERSTATE_ZBIAS 」를 참조할것.

이 플래그는 DirectX 5.0 으로 도입되었다.

D3DPRASTERCAPS_ZBUFFERLESSHSR
디바이스는, 숨고 표면의 제거 (HRS)를 실행 가능하고, 이 때, 다각형의 소트나, 깊이 버퍼의 할당을 필요로 하지 않는다. 이것에 의해, 보다 많은 비디오 메모리를 텍스쳐용으로 사용할 수 있다. 숨고 표면 제거에 사용하는 메소드는 하드웨어의 기능에 의존해, 어플리케이션 투과이다.

Z 버퍼 없음의 HRS 가 실행되는 것은, 깊이 버퍼가 렌더링 타겟 표면에 Attach 되지 않고, 한편 깊이 버퍼의 비교 테스트가 유효하게 되어 있는 경우 (즉,D3DRENDERSTATE_ZENABLE 열거 정수에 관련지을 수 있었던 스테이트값이 TRUE 로 설정되어 있는 경우)이다.

D3DPRASTERCAPS_ZFOG
디바이스는 W 베이스의 포그(안개:fog)를 지원 한다.

이 플래그는 DirectX 7.0 으로 도입되었다.

D3DPRASTERCAPS_ZTEST
디바이스는 Z 테스트 처리를 실행할 수 있다. 이것은, 효과적으로 프리미티브를 렌더링 해, Z 픽셀이 렌더링 되었는지 어떠했는지를 나타낸다.
dwZCmpCaps
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 테스트를 통한다.
dwSrcBlendCaps
소스 블렌딩 능력. 이 멤버에는, 이하의 값의 언젠가 또는 복수를 설정할 수 있다 (소스 및 목적지의 RGBA 값은 첨자의 s 및 d. 그리고 나타난다).
D3DPBLENDCAPS_BOTHINVSRCALPHA
소스 블렌딩 계수는, (1-As, 1-As, 1-As, 1-As). 목적지 블렌딩 계수는, (As, As, As, As). 목적지 혼합절은, 무효가 된다.
D3DPBLENDCAPS_BOTHSRCALPHA
드라이버는 D3DBLEND_BOTHSRCALPHA 블렌딩 모드를 지원 한다 (이 블렌딩 모드는 DirectX 6.0 이후에서는 폐지되고 있다. 상세한 것에 대하여는, 「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).
dwDestBlendCaps
목적지 블렌딩 능력. 이 멤버는,dwSrcBlendCaps 멤버로 정의된 능력 정보와 같다.
dwAlphaCmpCaps
알파 테스트 비교 능력. 이 멤버는,dwZCmpCaps 멤버로 정의된 능력 플래그를 포함한다. 이 멤버가 D3DPCMPCAPS_ALWAYS 능력만, 또는 D3DPCMPCAPS_NEVER 능력밖에 가지고 있지 않은 경우, 드라이버는 알파 테스트를 지원 하지 않는다. 그 이외의 경우, 이 플래그에 의해, 알파 테스트를 지원 하는 각각의 비교를 지정한다.
dwShadeCaps
쉐이딩 처리 능력. 일반적으로, 디바이스가 (D3DOP_TRIANGLE 등) 지정된 커멘드를 지원 하고 있는 경우, 그 디바이스는 D3DSHADE_FLAT 모드 (D3DSHADEMODE 열거형으로 지정된다)를 지원 하면 보여진다. 이 플래그는, 디바이스가 gouraud shading 및 폰 쉐이딩을 지원 할지 어떨지, 및 3 개의 컬러 생성 모드에 대해서 각각알파 성분이 지원 될지 어떨지를 지정한다. 알파 성분이 주어진 모드로 지원 되지 않는 경우, 그 모드로 생성된 색의 알파값은 반드시 255 가 된다. 이 수치가, 알파의 최대치 (알파가 최강)이다. 폰 쉐이딩은, 현재 지원되어 있지 않다.

흑백 쉐이딩 모드에서는, 스펙큐러 성분의 파랑 채널이 흰색의 휘도(Luminance)으로서 해석된다 (이것은 D3DRENDERSTATE_MONOENABLE 렌더링 스테이트에서 제어된다).

삼각형의 색, 스펙큐러 하이라이트, 포그(안개:fog), 및 알파 성분에는, 각각 능력 플래그가 있어, 어플리케이션은, 그 플래그를 사용해, 디바이스 드라이버가 그것들을 어떻게 이행 하고 있을까를 알 수 있다. 이 플래그는, 쉐이딩 모드, 색모델, 또는 컬러의 알파 성분이 블렌딩 될까 점묘 될까에 의해 변경된다. 상세한 것에 대하여는, 「3D 프리미티브」를 참조할것.

이 멤버는, 다음의 값을 1 개 이상 설정할 수 있다.

D3DPSHADECAPS_ALPHAFLATBLEND
디바이스는, 플랫 블렌딩 및 점묘 된 투과성에 대해서 각각 알파 성분을 지원 할 수 있다 (D3DSHADEMODE 열거형의 D3DSHADE_FLAT 스테이트). 이러한 모드에서는, 프리미티브의알파 성분은, 프리미티브의 최초의 버텍스의 컬러의 일부로서 주어진다.
D3DPSHADECAPS_ALPHAFLATSTIPPLED
디바이스는, 플랫 블렌딩 및 점묘 된 투과성에 대해서 각각 알파 성분을 지원 할 수 있다 (D3DSHADEMODE 열거형의 D3DSHADE_FLAT 스테이트). 이러한 모드에서는, 프리미티브의알파 성분은, 프리미티브의 최초의 버텍스의 컬러의 일부로서 주어진다.
D3DPSHADECAPS_ALPHAGOURAUDBLEND
디바이스는, 투과적으로 각각 혼합이나 점묘 된 굿 로 (D3DSHADEMODE 열거형의 D3DSHADE_GOURAUD 스테이트)의 알파 성분을 지원 할 수 있다. 이러한 모드에서는, 프리미티브의 알파 성분은 버텍스로써 주어져 다른 색성분과 함께 면을 따라 보간 된다.
D3DPSHADECAPS_ALPHAGOURAUDSTIPPLED
디바이스는, 투과적으로 각각 혼합이나 점묘 된 굿 로 (D3DSHADEMODE 열거형의 D3DSHADE_GOURAUD 스테이트)의 알파 성분을 지원 할 수 있다. 이러한 모드에서는, 프리미티브의 알파 성분은 버텍스로써 주어져 다른 색성분과 함께 면을 따라 보간 된다.
D3DPSHADECAPS_ALPHAPHONGBLEND
디바이스는, 투과적으로 각각 혼합이나 점묘 된 폰 (D3DSHADEMODE 열거형의 D3DSHADE_PHONG)의 알파 성분을 지원 할 수 있다. 이러한 모드로, 버텍스 파라미터는 적, 초록, 파랑의 색성분의 광원 이펙트를 적용해, 픽셀 단위에 재평가된다. 폰 쉐이딩은, 현재 지원되어 있지 않다.
D3DPSHADECAPS_ALPHAPHONGSTIPPLED
디바이스는, 투과적으로 각각 혼합이나 점묘 된 폰 (D3DSHADEMODE 열거형의 D3DSHADE_PHONG 스테이트)의 알파 성분을 지원 할 수 있다. 이러한 모드로, 버텍스 파라미터는 적, 초록, 파랑의 색성분의 광원 이펙트를 적용해, 픽셀 단위에 재평가된다. 폰 쉐이딩은, 현재 지원되어 있지 않다.
D3DPSHADECAPS_COLORFLATMONO
디바이스는,D3DCOLOR_MONO 및 D3DCOLOR_RGB 색모델의 각각 두어, 컬러 flat shading를 지원 할 수 있다. 이러한 모드에서는, 프리미티브에 대한 색성분은 프리미티브의 최초의 버텍스의 색의 일부로서 주어진다. 흑백 라이팅 모델에서는, 컬러의 파랑 성분만 보간 되어 RGB 라이팅 모델에서는 적, 초록, 및 파랑 성분이 보간 된다.
D3DPSHADECAPS_COLORFLATRGB
디바이스는,D3DCOLOR_MONO 및 D3DCOLOR_RGB 색모델의 각각 두어, 컬러 flat shading를 지원 할 수 있다. 이러한 모드에서는, 프리미티브에 대한 색성분은 프리미티브의 최초의 버텍스의 색의 일부로서 주어진다. 흑백 라이팅 모델에서는, 컬러의 파랑 성분만 보간 되어 RGB 라이팅 모델에서는 적, 초록, 및 파랑 성분이 보간 된다.
D3DPSHADECAPS_COLORGOURAUDMONO
디바이스는,D3DCOLOR_MONO 와 D3DCOLOR_RGB 색모델의 각각 붙어, 컬러 gouraud shading를 지원 할 수 있다. 이러한 모드에서는, 프리미티브에 대한 색성분은 버텍스로써 주어져 다른 색성분과 함께 면을 따라 보간 된다. 흑백 라이팅 모델에서는, 컬러의 파랑 성분만 보간 되어 RGB 라이팅 모델에서는 적, 초록, 및 파랑 성분이 보간 된다.
D3DPSHADECAPS_COLORGOURAUDRGB
디바이스는,D3DCOLOR_MONO 와 D3DCOLOR_RGB 색모델의 각각 붙어, 컬러 gouraud shading를 지원 할 수 있다. 이러한 모드에서는, 프리미티브에 대한 색성분은 버텍스로써 주어져 다른 색성분과 함께 면을 따라 보간 된다. 흑백 라이팅 모델에서는, 컬러의 파랑 성분만 보간 되어 RGB 라이팅 모델에서는 적, 초록, 및 파랑 성분이 보간 된다.
D3DPSHADECAPS_COLORPHONGMONO
디바이스는,D3DCOLOR_MONO 와 D3DCOLOR_RGB 색모델의 각각 붙어, 컬러 폰 쉐이딩을 지원 할 수 있다. 이러한 모드에서는, 버텍스 파라미터는 픽셀 단위에 재평가된다. 광원 이펙트는, RGB 모델의 경우는 적, 초록, 파랑 성분에 적용되어 흑백 모델의 경우는 파랑 성분에게만 적용된다. 폰 쉐이딩은, 현재 지원되어 있지 않다.
D3DPSHADECAPS_COLORPHONGRGB
디바이스는,D3DCOLOR_MONO 와 D3DCOLOR_RGB 색모델의 각각 붙어, 컬러 폰 쉐이딩을 지원 할 수 있다. 이러한 모드에서는, 버텍스 파라미터는 픽셀 단위에 재평가된다. 광원 이펙트는, RGB 모델의 경우는 적, 초록, 파랑 성분에 적용되어 흑백 모델의 경우는 파랑 성분에게만 적용된다. 폰 쉐이딩은, 현재 지원되어 있지 않다.
D3DPSHADECAPS_FOGFLAT
디바이스는, 플랫, 굿 로, 폰 쉐이딩 모드로 포그(안개:fog)를 지원 할 수 있다. 폰 쉐이딩은, 현재 지원되어 있지 않다.
D3DPSHADECAPS_FOGGOURAUD
디바이스는, 플랫, 굿 로, 폰 쉐이딩 모드로 포그(안개:fog)를 지원 할 수 있다. 폰 쉐이딩은, 현재 지원되어 있지 않다.
D3DPSHADECAPS_FOGPHONG
디바이스는, 플랫, 굿 로, 폰 쉐이딩 모드로 포그(안개:fog)를 지원 할 수 있다. 폰 쉐이딩은, 현재 지원되어 있지 않다.
D3DPSHADECAPS_SPECULARFLATMONO
디바이스는,D3DCOLOR_MONO 와 D3DCOLOR_RGB 색모델의 flat shading의 스펙큐러 하이라이트를 지원 할 수 있다.
D3DPSHADECAPS_SPECULARFLATRGB
디바이스는,D3DCOLOR_MONO 와 D3DCOLOR_RGB 색모델의 flat shading의 스펙큐러 하이라이트를 지원 할 수 있다.
D3DPSHADECAPS_SPECULARGOURAUDMONO
디바이스는,D3DCOLOR_MONO 및 D3DCOLOR_RGB 색모델의 gouraud shading의 스펙큐러 하이라이트를 지원 할 수 있다.
D3DPSHADECAPS_SPECULARGOURAUDRGB
디바이스는,D3DCOLOR_MONO 및 D3DCOLOR_RGB 색모델의 gouraud shading의 스펙큐러 하이라이트를 지원 할 수 있다.
D3DPSHADECAPS_SPECULARPHONGMONO
디바이스는,D3DCOLOR_MONO 및 D3DCOLOR_RGB 색모델의 폰 쉐이딩의 스펙큐러 하이라이트를 지원 할 수 있다. 폰 쉐이딩은, 현재 지원되어 있지 않다.
D3DPSHADECAPS_SPECULARPHONGRGB
디바이스는,D3DCOLOR_MONO 와 D3DCOLOR_RGB 색모델의 폰 쉐이딩의 스펙큐러 하이라이트를 지원 할 수 있다. 폰 쉐이딩은, 현재 지원되어 있지 않다.
dwTextureCaps
혼합 텍스쳐 맵핑 능력. 이 멤버는, 다음의 값을 1 개 이상 설정할 수 있다.
D3DPTEXTURECAPS_ALPHA
D3DTBLEND_DECAL 과 D3DTBLEND_MODULATE 텍스쳐 필터 모드의 RGBA 텍스쳐를 지원 한다. 이 능력이 설정되어 있지 않은 경우는, RGB 텍스쳐만 이러한 모드로 지원 된다. 이 플래그의 설정을 무시 하면, 알파는 사용 가능한 D3DTBLEND_DECALMASK, D3DTBLEND_DECALALPHA, D3DTBLEND_MODULATE_ALPHA 필터 모드로 지원 된다.
D3DPTEXTURECAPS_ALPHAPALETTE
팔레트에 알파 정보를 포함한팔레트화 텍스쳐 표면을 지원 한다 (DDCAPS 구조체의 「DDPCAPS_ALPHA」를 참조할것).
D3DPTEXTURECAPS_BORDER
D3DPTADDRESSCAPS_BORDER 가 대신해 사용된다.
D3DPTEXTURECAPS_COLORKEYBLEND
디바이스는,D3DRENDERSTATE_COLORKEYBLENDENABLE 렌더링 스테이트를 사용해 알파 블렌딩 컬러 키잉을 지원 한다.
D3DPTEXTURECAPS_CUBEMAP
큐브 환경 맵을 지원 한다. 이 능력 플래그는 DirectX 7.0 으로 도입되었다.
D3DPTEXTURECAPS_NONPOW2CONDITIONAL
경우에 따라서는, 크기가 2 의 거듭제곱이 아닌 텍스쳐의 사용을 지원 한다. 이하의 조건을 모두 채우는 경우, 이 능력을 공개하는 디바이스에서는 이러한 텍스쳐를 사용할 수 있다.
  • 텍스쳐 스테이지의 텍스쳐 addressing mode가 D3DTADDRESS_CLAMP 로 설정되어 있다.
  • 텍스쳐 스테이지의 텍스쳐 랩핑이 무효가 되어 있다 (D3DRENDERSTATE_WRAPn 를 0 으로 설정).
  • MIP Mapping가 사용되어 있지 않다 (밉맵화 텍스쳐의 크기는 2 의 거듭제곱이 아니면 안된다).
D3DPTEXTURECAPS_PERSPECTIVE
퍼스펙티브 보정이 지원 된다.
D3DPTEXTURECAPS_POW2
밉맵화되어 있지 않은 모든 텍스쳐의 폭 및 높이는 2 의 거듭제곱으로 지정할 필요가 있다 (밉맵화 텍스쳐는, 항상 2 의 거듭제곱의 크기가 아니면 안된다).
D3DPTEXTURECAPS_PROJECTED
D3DTTFF_PROJECTED 텍스쳐 트랜스 폼 포그(안개:fog)를 지원 한다. 이 능력이 적용되고 있는 경우, 디바이스는 트랜스 폼이 끝난 텍스쳐 좌표를 마지막 텍스쳐 좌표로 분할한다.
D3DPTEXTURECAPS_SQUAREONLY
텍스쳐는, 모두 정방형이 아니면 안된다.
D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE
텍스쳐 인덱스는, 보간 실행전에는, 텍스쳐 사이즈에 맞추어 스케일링 되지 않는다.

이 플래그는 DirectX 7.0 으로 도입되었다.

D3DPTEXTURECAPS_TRANSPARENCY
텍스쳐 투과성이 지원 된다 (현재의 투과색이 아닌 이러한 텍셀만 드로잉(Drawing) 된다).
dwTextureFilterCaps
텍스쳐 필터링 능력. 일반적인 텍스쳐 필터링 플래그는, 어느 텍스쳐 필터링 모드를 지원 하는지를 나타내,D3DTSS_MAGFILTER ,D3DTSS_MINFILTER , 또는 D3DTSS_MIPFILTER 텍스쳐 스테이지 스테이트로 설정된다. 스테이지 단위의 필터링 능력은,IDirect3DDevice7 인터페이스로 멀티 텍스쳐 블렌딩을 실행할 때에 텍스쳐 스테이지에서 지원 하는 필터링 모드를 나타낸다. 이 멤버는, 다음에 나타내는 일반, 및 스테이지 단위 필터링 플래그를 임의에 조합한 것이다.

일반적인 텍스쳐 필터링 플래그

D3DPTFILTERCAPS_LINEAR
바이리니아피르타링. 가장 가까운 좌표를 가지는 텍셀을 선택한 후, 4 개의 주변 텍셀을 사용해 중량감 첨부 평균을 산출해, 최종적인 색을 결정한다. 이것은, 확대와 축소의 양쪽 모두로 사용된다. 확대 또는 축소중 한쪽이 지원 되고 있는 경우는, 그 양쪽 모두가 지원 되고 있을 필요가 있다.
D3DPTFILTERCAPS_LINEARMIPLINEAR
밉맵간의 트라이 리니어 보간. 바이리니아피르타링을 2 개의 최근접밉맵간에 실행한 후, 2 색의 사이를 선형적으로 보간 해 최종적인 색을 결정한다.
D3DPTFILTERCAPS_LINEARMIPNEAREST
2 개의 포인트 샘플 밉맵의 사이의 선형 보간. 2 개(살)의 가장 가까운 밉맵 레벨로부터 최근접텍셀을 선택한 후, 그 2 개의 텍셀간에 선형 보간을 실행한다.
D3DPTFILTERCAPS_MIPLINEAR
바이리니아피르타링을 결과에 적용하는, 최근접MIP Mapping. 가장 가까운 좌표를 가지는 적절한 밉맵으로부터 텍셀을 선택한 후, 4 개의 주변 텍셀을 사용해 중량감 첨부 평균을 산출해, 최종적인 색을 결정한다.
D3DPTFILTERCAPS_MIPNEAREST
최근접MIP Mapping. 목적의 픽셀값에 가장 가까운 좌표를 가지는 적절한 밉맵으로부터 텍셀을 선택한다.
D3DPTFILTERCAPS_NEAREST
포인트 샘플링. 희망의 픽셀값에 가장 가까운 좌표를 가지는 텍셀을 사용한다. 이것은, 확대와 축소의 양쪽 모두로 사용된다. 확대 또는 축소중 한쪽이 지원 되고 있는 경우는, 그 양쪽 모두가 지원 되고 있을 필요가 있다.

스테이지 단위 텍스쳐 필터링 플래그

D3DPTFILTERCAPS_MAGFAFLATCUBIC
디바이스는, 스테이지 단위에서의 텍스쳐 확대를 위해 평면 큐브 필터링을 지원 한다. 평면 큐브 확대 필터는,D3DTEXTUREMAGFILTER 열거형의 멤버 D3DTFG_FLATCUBIC 로 나타내진다.
D3DPTFILTERCAPS_MAGFANISOTROPIC
디바이스는, 스테이지 단위에서의 텍스쳐 확대를 위해, 비등방성 필터링을 지원 한다. 비등방성 확대 필터는,D3DTEXTUREMAGFILTER 열거형의 멤버 D3DTFG_ANISOTROPIC 로 나타내진다.
D3DPTFILTERCAPS_MAGFGAUSSIANCUBIC
디바이스는, 스테이지 단위에서의 텍스쳐 확대를 위해, Gauss 큐브 필터링을 지원 한다. Gauss 큐브 확대 필터는,D3DTEXTUREMAGFILTER 열거형의 멤버 D3DTFG_GAUSSIANCUBIC 로 나타내진다.
D3DPTFILTERCAPS_MAGFLINEAR
디바이스는, 스테이지 단위에서의 텍스쳐 확대를 위해, 바이리니아 보간 필터링을 지원 한다. 바이리니아 보간 확대 필터는,D3DTEXTUREMAGFILTER 열거형의 멤버 D3DTFG_LINEAR 로 나타내진다.
D3DPTFILTERCAPS_MAGFPOINT
디바이스는, 스테이지 단위에서의 텍스쳐 확대를 위해, 포인트 샘플 필터링을 지원 한다. 포인트 샘플 확대 필터는,D3DTEXTUREMAGFILTER 열거형의 멤버 D3DTFG_POINT 로 나타내진다.
D3DPTFILTERCAPS_MINFANISOTROPIC
디바이스는, 스테이지 단위에서의 텍스쳐 축소를 위해, 비등방성 필터링을 지원 한다. 비등방성 축소 필터는,D3DTEXTUREMINFILTER 열거형의 D3DTFN_ANISOTROPIC 멤버로 나타내진다.
D3DPTFILTERCAPS_MINFLINEAR
디바이스는, 스테이지 단위에서의 텍스쳐 축소를 위해, 바이리니아 보간 필터링을 지원 한다. 바이리니아 보간 축소 필터는,D3DTEXTUREMINFILTER 열거형의 멤버 D3DTFN_LINEAR 로 나타내진다.
D3DPTFILTERCAPS_MINFPOINT
디바이스는, 스테이지 단위에서의 텍스쳐 축소를 위해, 포인트 샘플 필터링을 지원 한다. 포인트 샘플 축소 필터는,D3DTEXTUREMINFILTER 열거형의 멤버 D3DTFN_POINT 로 나타내진다.
D3DPTFILTERCAPS_MIPFLINEAR
디바이스는, 스테이지 단위에서의 밉맵이기 때문에, 트라이 리니어 보간 필터링을 지원 한다. 트라이 리니어 보간 밉맵 필터는,D3DTEXTUREMIPFILTER 열거형의 멤버 D3DTFP_LINEAR 로 나타내진다.
D3DPTFILTERCAPS_MIPFPOINT
디바이스는, 스테이지 단위에서의 밉맵이기 때문에, 포인트 샘플 필터링을 지원 한다. 포인트 샘플 밉맵 필터는,D3DTEXTUREMIPFILTER 열거형의 멤버 D3DTFP_POINT 로 나타내진다.
dwTextureBlendCaps
사용하지 않는다.

구릴리스의 DirectX 에서는, 이 멤버에, 현재는 폐지되고 있는 D3DRENDERSTATE_TEXTUREMAPBLEND 렌더링 스테이트에 의한 디바이스의 텍스쳐 블렌딩 적용 능력에 대한 정보가 저장 되었다. DirectX 7.0 디바이스의 텍스쳐 블렌딩 능력에 대한 정보는,D3DDEVICEDESC7 구조체의 dwTextureOpCaps 멤버로 공개되고 있다.

dwTextureAddressCaps
텍스쳐의 주소 능력. 이 멤버는, 다음의 값을 1 개 이상 설정할 수 있다.
D3DPTADDRESSCAPS_BORDER
디바이스는,D3DRENDERSTATE_BORDERCOLOR 텍스쳐 스테이지 스테이트에서 지정되는 경계색을 [0.0, 1.0] 범위외의 좌표로 설정할 수 있다.
D3DPTADDRESSCAPS_CLAMP
디바이스는, 텍스쳐의 고정이 가능하다.
D3DPTADDRESSCAPS_INDEPENDENTUV
디바이스는, 텍스쳐의 U 좌표와 V 좌표의 텍스쳐 addressing mode를 분리할 수 있다. 이 능력은,D3DTSS_ADDRESSU 및 D3DTSS_ADDRESSV 렌더링 스테이트값에 대응한다.

이 플래그는 DirectX 5.0 으로 도입되었다.

D3DPTADDRESSCAPS_MIRROR
디바이스는, 텍스쳐의 반전이 가능하다.
D3DPTADDRESSCAPS_WRAP
디바이스는, 텍스쳐가 붙이고가 가능하다.
dwStippleWidth 및 dwStippleHeight
지원 된 점묘의 최대폭과 높이 (최고 32×32 까지).

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dcaps.h 로 선언.


D3DRECT

D3DRECT 구조체는, 직사각형의 정의이다.

typedef struct _D3DRECT {
    union {
        LONG x1;
        LONG lX1;
    };
    union {
        LONG y1;
        LONG lY1;
    };
    union {
        LONG x2;
        LONG lX2;
    };
    union {
        LONG y2;
        LONG lY2;
    };
} D3DRECT, *LPD3DRECT;

멤버

lX1 및 lY1
직사각형의 좌상구석의 좌표.
lX2 및 lY2
직사각형의 우하구석의 좌표.

동작환경

Windows NT/2000 : Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

IDirect3DDevice7::Clear


D3DTLVERTEX

D3DTLVERTEX 구조체는, 「트랜스 폼이 끝난 라이팅 끝난 버텍스」 (컬러를 가지는 화면 좌표)을 정의한다.

typedef struct _D3DTLVERTEX {
    union {
        D3DVALUE sx;
        D3DVALUE dvSX;
    };
    union {
        D3DVALUE sy;
        D3DVALUE dvSY;
    };
    union {
        D3DVALUE sz;
        D3DVALUE dvSZ;
    };
    union {
        D3DVALUE rhw;
        D3DVALUE dvRHW;
    };
    union {
        D3DCOLOR color;
        D3DCOLOR dcColor;
    };
    union {
        D3DCOLOR specular;
        D3DCOLOR dcSpecular;
    };
    union {
        D3DVALUE tu;
        D3DVALUE dvTU;
    };
    union {
        D3DVALUE tv;
        D3DVALUE dvTV;
    };
} D3DTLVERTEX, *LPD3DTLVERTEX;

파라미터

dvSX,dvSY, 및 dvSZ
화면 좌표의 버텍스를 기술하는 D3DVALUE 형의 값. 표시되는 z 값의 범위내에 버텍스를 두기 위해서(때문에)는,dvSZ 가 취할 수 있는 최대치는 0.99999 까지이다.
dvRHW
D3DVALUE 형의 값으로, 동차 좌표 (x, y, z, w)의 동차 w 의 역수이다. 이 값은, 원점으로부터 오브젝트까지의 z 축으로 따른 거리로 1 을 나눗셈 한 값에 자주 일치한다.
dcColor 및 dcSpecular
버텍스의 색 및 스펙큐러 성분을 기술하는 D3DCOLOR 형의 값.
dvTU 및 dvTV
버텍스의텍스쳐 좌표를 기술하는 D3DVALUE 형의 값.

주의

Direct3D 는, 현재의 뷰포트 파라미터 (D3DVIEWPORT7 구조체의 dwX,dwY,dwWidth, 및 dwHeight 멤버)를 사용해 D3DTLVERTEX 버텍스를 클리핑 한다. 시스템은 z 좌표를 항상 [0, 1] 에 클리핑 한다. 이러한 버텍스를 클리핑 하지 않게 하려면 , 렌더링 메소드를 호출하면나무에 D3DDP_DONOTCLIP 플래그를 사용한다.

D3DRENDERSTATE_SPECULARENABLE 가 TRUE 의 경우, 텍스쳐 cascade와 알파 블렌딩의 사이, 베이스 컬러에 스펙큐러 성분이 추가된다. 다만, DirectX 7.0 에서는 D3DTA_SPECULAR 플래그를 설정 하면, 텍스쳐색의 처리중에, 적용하는 스펙큐러 성분을 할당할 수가 있다. 상세한 것에 대하여는, 「텍스쳐 인수 플래그」를 참조할것.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

D3DLVERTEX ,D3DVERTEX


D3DVECTOR

D3DVECTOR 구조체는, 많은 Direct3D 와 Direct3DRM 메소드와 구조체의 벡터를 정의한다.

typedef struct _D3DVECTOR {
    union {
        D3DVALUE x;
        D3DVALUE dvX;
    };
    union {
        D3DVALUE y;
        D3DVALUE dvY;
    };
    union {
        D3DVALUE z;
        D3DVALUE dvZ;
    };
} D3DVECTOR, *LPD3DVECTOR;

멤버

dvX,dvY, 및 dvZ
벡터를 지정하는 D3DVALUE 형의 값.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


D3DVERTEX

D3DVERTEX 구조체는, 「트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스」를 정의한다 (법선 방향 벡터를 가지는모델 좌표).

typedef struct _D3DVERTEX {
    union {
        D3DVALUE x;
        D3DVALUE dvX;
    };
    union {
        D3DVALUE y;
        D3DVALUE dvY;
    };
    union {
        D3DVALUE z;
        D3DVALUE dvZ;
    };
    union {
        D3DVALUE nx;
        D3DVALUE dvNX;
    };
    union {
        D3DVALUE ny;
        D3DVALUE dvNY;
    };
    union {
        D3DVALUE nz;
        D3DVALUE dvNZ;
    };
    union {
        D3DVALUE tu;
        D3DVALUE dvTU;
    };
    union {
        D3DVALUE tv;
        D3DVALUE dvTV;
    };
} D3DVERTEX, *LPD3DVERTEX;

멤버

dvX,dvY, 및 dvZ
버텍스의 동차 좌표를 지정하는 D3DVALUE 형의 값.
dvNX,dvNY, 및 dvNZ
정규 좌표로 버텍스를 지정하는 D3DVALUE 형의 값.
dvTU 및 dvTV
버텍스의텍스쳐 좌표를 지정하는 D3DVALUE 형의 값.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

D3DLVERTEX ,D3DTLVERTEX ,D3DVALUE


D3DVERTEXBUFFERDESC

D3DVERTEXBUFFERDESC 구조체는, 버텍스 버퍼 오브젝트의 프로퍼티를 기술한다. 이 구조체는 IDirect3D7::CreateVertexBuffer 및 IDirect3DVertexBuffer7::GetVertexBufferDesc 메소드로 사용된다.

typedef struct _D3DVERTEXBUFFERDESC {
    DWORD dwSize;
    DWORD dwCaps;
    DWORD dwFVF;
    DWORD dwNumVertices;
} D3DVERTEXBUFFERDESC, *LPD3DVERTEXBUFFERDESC;

멤버

dwSize
이 구조체의 바이트 단위의 사이즈. 이 멤버는 구조체가 사용되기 전에 초기화해야 한다.
dwCaps
버텍스 버퍼를 기술해, 그 버텍스 버퍼가 최적화된 버텍스 데이터를 보관 유지할 수 있을지 어떨지를 나타내는 능력 플래그. 이 파라미터는, 이하에 나타내는 플래그의 임의의 편성으로 만들어진다.
(없음)
버텍스 버퍼는, 드라이버가 효율적인 리드 동작을 실행하기 위해서 선택한 메모리이면, 어느 메모리에 생성 해도 괜찮다.
D3DVBCAPS_DONOTCLIP
버텍스 버퍼는 클리핑 정보를 보관 유지할 수 없다.
D3DVBCAPS_OPTIMIZED
버텍스 버퍼는, 최적화된 버텍스 데이터를 보관 유지할 수 있다 (이 플래그는, 새로운 버텍스 버퍼의 생성시에는 사용되지 않는다).
D3DVBCAPS_SYSTEMMEMORY
버텍스 버퍼는, 시스템 메모리에 생성 해야 한다. 이 능력은, 소프트웨어 디바이스 (MMX 또는 RGB 디바이스) 또는 HAL 디바이스 (IID_IDirect3DHALDevice)를 사용해 버텍스 버퍼를 렌더링 하는 경우에 사용한다.
D3DVBCAPS_WRITEONLY
버텍스 버퍼에의 쓰기 조작 밖에 실행할 수 없는 것을 시스템에 알린다. 이 플래그를 사용하는 것으로써, 드라이버는 최적인 메모리 영역을 선택해 효율적으로 쓰기 조작이나 렌더링을 실행한다. 이 능력을 이용해 생성 한 버텍스 버퍼로부터 읽기를 실시하려고 하면, 퍼포먼스가 저하하는 일이 있다.
dwFVF
버퍼내의 버텍스의 버텍스 포맷을 기술하는유연한 버텍스 포맷 플래그의 편성.
dwNumVertices
이 버텍스 버퍼를 보관 유지할 수 있는 버텍스의 수의 최대치. 허용 되는 최대 버텍스수는 D3DMAXNUMVERTICES (0xFFFF)이다.

주의

소프트웨어 디바이스 (MMX 및 RGB 디바이스)는, 로컬 또는 비로컬일지 어떨지에 관계없이, 비디오 메모리로부터 버텍스 버퍼를 렌더링 할 수 없다. 소프트웨어 디바이스를 사용해 버텍스 버퍼를 렌더링 하려면 , 버텍스 버퍼가 시스템 메모리에 존재해야 한다. 하드웨어 디바이스는, 시스템 메모리 또는 비디오 메모리의 어느 쪽의 버텍스 버퍼로부터에서도, 렌더링 할 수가 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 6.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

버텍스 버퍼의 기술,버텍스 버퍼


D3DVIEWPORT7

D3DVIEWPORT7 구조체는, 3D 볼륨이 투영 되는 렌더링 타겟 표면의 윈도우의 크기를 정의한다. 이 구조체는 IDirect3DDevice7::GetViewport 및 IDirect3DDevice7::SetViewport 메소드로 사용된다.

typedef struct _D3DVIEWPORT7{
    DWORD       dwX;
    DWORD       dwY;
    DWORD       dwWidth;
    DWORD       dwHeight;
    D3DVALUE    dvMinZ;
    D3DVALUE    dvMaxZ;
} D3DVIEWPORT7, *LPD3DVIEWPORT7

멤버

dwX 및 dwY
렌더링 타겟 표면 위에의 뷰포트의 좌상구석을 나타내는 픽셀 좌표. 표면의 서브 세트에 렌더링 하므로 없으면, 이러한 멤버는 0 으로 설정할 수 있다.
dwWidth 및 dwHeight
렌더링의 대상이 되는 표면 위에의 뷰포트의 크기를 픽셀 단위로 나타낸다. 표면의 서브 세트로 한정해 렌더링 하므로 없으면, 이러한 멤버에는 렌더링 타겟 표면의 크기를 세트 한다.
dvMinZ 및 dvMaxZ
장면을 렌더링 하는 깊이 범위를 기술하는 D3DVALUE 형의 값 대부분의 어플리케이션에서는, 이러한 값을 각각 0.0 및 1.0 으로 설정한다. 이러한 멤버의 값의 해석은, 종래의 D3DVIEWPORT2 구조체로 대응하는 멤버의 경우와는 완전히 다르다. DirectX 7.0 에서는, 투영 행렬의 적용 후에 클리핑을 한다. 상세한 것에 대하여는, 「클리핑 볼륨」 및 「투영 트랜스 폼」을 참조할것.

주의

DirectX 7.0 으로 도입된 이 구조체는, 구버젼의 DirectX 로 사용된 D3DVIEWPORT2 및 D3DVIEWPORT 구조체에 대신해 사용된다.

dwX, dwY, dwWidth 및 dwHeight 멤버는, 렌더링의 대상이 되는 표면 위에의 뷰포트의 위치와 크기를 기술한다. 보통, 어플리케이션은 대상이 되는 표면 전체의 렌더링을 실행하므로, 640 x 480 의 표면으로 렌더링을 실시하는 경우에는, 이러한 멤버는 각각 0, 0, 640, 480 의 값을 취한다. 일반적으로,dvMinZ 및 dvMaxZ 는 0.0 및 1.0 으로 설정되지만, 다른 값을 설정해 특수 이펙트를 낼 수도 있다. 예를 들어, 양쪽 모두의 값을 0.0 으로 설정 하면, 장면의 foreground에 오브젝트가 렌더링 된다. 또, 양쪽 모두의 값을 1.0 으로 설정 하면, 오브젝트가 백그라운드에 렌더링 된다.

디바이스의 뷰포트 파라미터가 변경되면(자) (IDirect3DDevice7::SetViewport 메소드의 호출에 의해), 드라이버는 새로운 트랜스 폼 배열을 생성 한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3dtypes.h 로 선언.

참조

D3DVALUE ,IDirect3DDevice7::GetViewport ,IDirect3DDevice7::SetViewport ,클리핑 볼륨,뷰포트와 클리핑


폐지된 구조체

이하의 구조체는 폐지되고 있다. 폐지된 구조체가 제공하고 있던 기능성은, 현재는 IDirect3DDevice7 인터페이스 및 거기에 관련하는 구조체에 포함되어 있다. 이러한 관련성을 이하에 정리한다.

D3DDEVICEDESC
IDirect3DDevice7::GetCaps 메소드로 사용되는 D3DDEVICEDESC7 구조체가 대신해 사용된다.
D3DHVERTEX
지원 되지 않는다.
D3DFINDDEVICESEARCH 및 D3DFINDDEVICERESULT
폐지되고 있다.
D3DLIGHT 및 D3DLIGHT2
IDirect3DDevice7::GetLight 및 IDirect3DDevice7::SetLight 메소드로 사용되는 D3DLIGHT7 구조체가 대신해 사용된다.
D3DLIGHTDATA
지원 되지 않는다.
D3DLIGHTINGELEMENT
지원 되지 않는다.
D3DMATERIAL
IDirect3DDevice7::GetMaterial 및 IDirect3DDevice7::SetMaterial 메소드로 사용되는 D3DMATERIAL7 구조체가 대신해 사용된다.
D3DSTATE
지원 되지 않는다.
D3DSTATS
지원 되지 않는다.
D3DTRANSFORMCAPS
지원 되지 않는다.
D3DTRANSFORMDATA
지원 되지 않는다.
D3DVIEWPORT 및 D3DVIEWPORT2
IDirect3DDevice7::GetViewport 및 IDirect3DDevice7::SetViewport 메소드로 사용되는 D3DVIEWPORT7 구조체가 대신해 사용된다.

실행 버퍼 렌더링, 및 이하의 관련하는 구조체는, DirectX 7.0 에서는 폐지되고 있다고 본다. 이러한 구조체의 상세한 것에 대하여는, 구릴리스의 DirectX 의 문서를 참조할것.

  • D3DBRANCH
  • D3DEXECUTEBUFFERDESC
  • D3DEXECUTEDATA
  • D3DINSTRUCTION
  • D3DLINE
  • D3DMATRIXLOAD
  • D3DMATRIXMULTIPLY
  • D3DPICKRECORD
  • D3DPOINT
  • D3DPROCESSVERTICES
  • D3DSPAN
  • D3DSTATUS
  • D3DTEXTURELOAD
  • D3DTRIANGLE


열거형

여기에서는, Direct3D 직접 모드로 사용되는 이하의 열거형에 대해 설명한다.

  • D3DANTIALIASMODE
  • D3DBLEND
  • D3DCMPFUNC
  • D3DCULL
  • D3DFILLMODE
  • D3DFOGMODE
  • D3DLIGHTTYPE
  • D3DMATERIALCOLORSOURCE
  • D3DPRIMITIVETYPE
  • D3DRENDERSTATETYPE
  • D3DSHADEMODE
  • D3DSTATEBLOCKTYPE
  • D3DSTENCILOP
  • D3DTEXTUREADDRESS
  • D3DTEXTUREMAGFILTER
  • D3DTEXTUREMINFILTER
  • D3DTEXTUREMIPFILTER
  • D3DTEXTUREOP
  • D3DTEXTURESTAGESTATETYPE
  • D3DTEXTURETRANSFORMFLAGS
  • D3DTRANSFORMSTATETYPE
  • D3DVERTEXBLENDFLAGS
  • D3DVERTEXTYPE
  • D3DZBUFFERTYPE


D3DANTIALIASMODE

D3DANTIALIASMODE 열거형은,D3DRENDERSTATETYPE 열거형의 D3DRENDERSTATE_ANTIALIAS 값에 대해서 지원 되는 anti-aliasing 모드를 정의한다. 이러한 값은, 풀 신 anti-aliasing에 대한 설정값만 정의한다 (상세한 것에 대하여는, 「anti-aliasing」를 참조할것).

typedef enum _D3DANTIALIASMODE {
    D3DANTIALIAS_NONE          = 0,
    D3DANTIALIAS_SORTDEPENDENT = 1,
    D3DANTIALIAS_SORTINDEPENDENT = 2
    D3DANTIALIAS_FORCE_DWORD     = 0x7fffffff,
} D3DANTIALIASMODE;
D3DANTIALIAS_NONE
anti-aliasing는 실행되지 않는다. 이것이 디폴트 설정이다.
D3DANTIALIAS_SORTDEPENDENT
anti-aliasing는, 다각형의 소트순서 (후방에서 전방, 또는 전방에서 후방)에 따라 행해진다. 어플리케이션은, anti-aliasing가 생기는 것에 갖추어 올바른 순서로 다각형을 작도 해야 한다.
D3DANTIALIAS_SORTINDEPENDENT
anti-aliasing는, 다각형의 소트순서에 의존하지 않는다.
D3DANTIALIAS_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


D3DBLEND

D3DBLEND 열거형은,D3DRENDERSTATETYPE 열거형의 3DRENDERSTATE_DESTBLEND 값에 대해서 지원 되는블렌딩 모드를 정의한다. 이하의 멤버의 설명에서는, 소스 및 데스티네이션의 RGBA 값은 첨자 s 및 d 에 의해 나타난다.

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
폐지되고 있다. DirectX 6.0 및 그 이후로는, 소스 및 목적지의 블렌딩 계수에 D3DBLEND_SRCALPHA 과 D3DBLEND_INVSRCALPHA 를 각각 다른 호출로 설정하는 것으로써, 같은 효과를 얻을 수 있다.
D3DBLEND_BOTHINVSRCALPHA
소스의 블렌딩 계수는 (1-As, 1-As, 1-As, 1-As)으로, 목적지의 블렌딩 계수는 (As, As, As, As)이다. 목적지의 블렌딩의 선택은 무효가 된다. 이 블렌딩 모드는,D3DRENDERSTATE_SRCBLEND 렌더링 스테이트에서만 지원 된다.
D3DBLEND_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


D3DCMPFUNC

D3DCMPFUNC 열거형은,D3DRENDERSTATE_ZFUNC ,D3DRENDERSTATE_ALPHAFUNC , 및 D3DRENDERSTATE_STENCILFUNC 렌더링 스테이트에 대해서 지원 되는 비교 함수를 정의한다.

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 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


D3DCULL

D3DCULL 열거형은,D3DRENDERSTATE_CULLMODE 렌더링 스테이트에서 사용되는 컬링(Culling) 모드를 정의한다. 지오메트리에 렌더링 하면나무의 면의 컬링(Culling) 방법을 정의한다.

typedef enum _D3DCULL {
    D3DCULL_NONE = 1,
    D3DCULL_CW   = 2,
    D3DCULL_CCW  = 3,
    D3DCULL_FORCE_DWORD   = 0x7fffffff,
} D3DCULL;
D3DCULL_NONE
컬링(Culling)는 하지 않는다.
D3DCULL_CW
우회전으로 잘라낸다.
D3DCULL_CCW
왼쪽 회전에 잘라낸다.
D3DCULL_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

D3DPRIMCAPS ,D3DRENDERSTATETYPE


D3DFILLMODE

D3DFILLMODE 열거형은, 전부 칠해 모드를 지정하는 정수를 설정한다. 이러한 값은,D3DRENDERSTATETYPE 열거형의 D3DRENDERSTATE_FILLMODE 렌더링 스테이트에서 사용된다.

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 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


D3DFOGMODE

D3DFOGMODE 열거형은, 포그(안개:fog) 모드를 지정하는 정수를 설정한다. 이러한 값은,D3DRENDERSTATETYPE 열거형의 D3DRENDERSTATE_FOGTABLEMODE 및 D3DRENDERSTATE_FOGVERTEXMODE 렌더링 스테이트에서 사용된다.

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 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

흑백 (램프) 라이팅 모드에서는, 포그(안개:fog)는 그 색이 흑의 경우에 한정해 정상적으로 기능한다 (라이트가 존재하지 않는 경우는 모든 포그(안개:fog) 컬러가 기능한다. 이 경우, 모든 포그(안개:fog) 컬러가 사실상흑이니까이다).

상세한 것에 대하여는, 「포그(안개:fog)」를 참조할것.

주 : 포그(안개:fog)는, 투명도를 나타내는 기준이다. 이 경우, 포그(안개:fog)의 값이 작을 정도(수록), 오브젝트가 안보이게 된다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


D3DLIGHTTYPE

D3DLIGHTTYPE 열거형은, 광원형을 정의한다. 이 열거형은 D3DLIGHT7 구조체로 사용된다.

typedef enum _D3DLIGHTTYPE {
    D3DLIGHT_POINT         = 1,
    D3DLIGHT_SPOT          = 2,
    D3DLIGHT_DIRECTIONAL   = 3,
    D3DLIGHT_FORCE_DWORD   = 0x7fffffff,
} D3DLIGHTTYPE;
D3DLIGHT_POINT
광원은 점이다. 빛은 공간내의 점을 가져, 전방향으로 빛을 에미션(emission) 한다.
D3DLIGHT_SPOT
라이트는spotlight이다. 이 라이트는, 조사가 콘내에 제한되는 점을 제외해서는, 포인트 라이트로 유사한다. 이 라이트 타입에는, 방향, 및 콘의 형상을 결정하는 그 외의 파라미터가 몇개인가 있다. 이러한 파라미터에 대해서는, 「D3DLIGHT7 」구조체를 참조할것.
D3DLIGHT_DIRECTIONAL
라이트는디렉셔널 라이트이다. 이것은 무한대의 거리로 점광원을 이용하는 것에 동일하다.
D3DLIGHT_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

디렉셔널 라이트는 포인트 라이트보다 처리는 다소 빠르지만, 결과에 대해서는 포인트 라이트가 위이다. spotlight는 재미있는 시각 이펙트를 내지만, 계산 카미타카값이다.

패러럴 포인트 라이트는 DirectX 7.0 이후에서는 지원 되지 않는다. 따라서, 이 열거형은 종래의 D3DLIGHT_PARALLELPOINT 멤버를 포함하지 않았다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


D3DMATERIALCOLORSOURCE

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 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

이 열거가 정의하는 값은, 이하의 렌더링 스테이트에서 사용된다.

  • D3DRENDERSTATE_DIFFUSEMATERIALSOURCE
  • D3DRENDERSTATE_SPECULARMATERIALSOURCE
  • D3DRENDERSTATE_AMBIENTMATERIALSOURCE
  • D3DRENDERSTATE_EMISSIVEMATERIALSOURCE

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3dtypes.h 로 선언.


D3DPRIMITIVETYPE

D3DPRIMITIVETYPE 열거형은, DrawPrimitive 메소드가 지원 하는 프리미티브를 열거한다. 이 형태는 DirectX 5.0 으로 도입되었다.

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 버텍스의 그룹은 개별적으로 삼각형을 정의한다. 이 프리미티브 타입을 사용하는 호출은, 카운트가 3 보다 작은지, 3 의 배수가 아닌 경우는 실패한다.

이면의 선택은, 현재의 와인딘그순서 렌더링 스테이트에 의해 영향을 받는다.

D3DPT_TRIANGLESTRIP
버텍스를 삼각형의 전개도로서 렌더링 한다. 이 프리미티브 타입을 사용하는 호출은, 카운트가 3 보다 작은 경우는 실패한다. 뒷면 컬링(Culling) 플래그는, 짝수 번호의 삼각형으로 자동적으로 반전한다.
D3DPT_TRIANGLEFAN
버텍스를 삼각형의 선형으로서 렌더링 한다. 이 프리미티브 타입을 사용하는 호출은, 카운트가 3 보다 작은 경우는 실패한다.
D3DPT_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

삼각형 스트립 또는 삼각형 팬을 사용하는 (분)편이, 삼각형 리스트를 사용하는 것보다 효율이 좋다. 상세한 것에 대하여는, 「삼각형 스트립」 및 「삼각형 팬」을 참조할것.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

IDirect3DDevice7::DrawIndexedPrimitive ,IDirect3DDevice7::DrawIndexedPrimitiveStrided ,IDirect3DDevice7::DrawIndexedPrimitiveVB ,IDirect3DDevice7::DrawPrimitive ,IDirect3DDevice7::DrawPrimitiveStrided ,IDirect3DDevice7::DrawPrimitiveVB ,프리미티브의 종류


D3DRENDERSTATETYPE

D3DRENDERSTATETYPE 열거형은,IDirect3DDevice7::SetRenderState 및 IDirect3DDevice7::GetRenderState 메소드에 의해 설정 및 취득되는 렌더링 스테이트를 정의한다.

typedef enum _D3DRENDERSTATETYPE {
    D3DRENDERSTATE_ANTIALIAS          = 2,    // anti-aliasing 모드.
    D3DRENDERSTATE_TEXTUREPERSPECTIVE = 4,    // 퍼스펙티브 보정.
    D3DRENDERSTATE_ZENABLE            = 7,    // Z 테스트를 유효하게 한다.
    D3DRENDERSTATE_FILLMODE           = 8,    // 전부 칠해 모드.
    D3DRENDERSTATE_SHADEMODE          = 9,    // 쉐이딩 모드.
    D3DRENDERSTATE_LINEPATTERN        = 10,   // 직선 패턴.
    D3DRENDERSTATE_ZWRITEENABLE       = 14,   // Z 쓰기를 유효하게 한다.
    D3DRENDERSTATE_ALPHATESTENABLE    = 15,   // 알파 테스트를 유효하게 한다.
    D3DRENDERSTATE_LASTPIXEL          = 16,   // 마지막 픽셀을 직선으로 그린다.
    D3DRENDERSTATE_SRCBLEND           = 19,   // 소스의 블렌딩 계수.
    D3DRENDERSTATE_DESTBLEND          = 20,   // 목적지의 블렌딩 계수.
    D3DRENDERSTATE_CULLMODE           = 22,   // 뒷면 컬링(Culling) 모드.
    D3DRENDERSTATE_ZFUNC              = 23,   // Z 비교 기능.
    D3DRENDERSTATE_ALPHAREF           = 24,   // 참조 알파값.
    D3DRENDERSTATE_ALPHAFUNC          = 25,   // 알파 비교 기능.
    D3DRENDERSTATE_DITHERENABLE       = 26,   // 디저링을 유효하게 한다.
    D3DRENDERSTATE_ALPHABLENDENABLE   = 27,   // 알파 블렌딩을 유효하게 한다.
    D3DRENDERSTATE_FOGENABLE          = 28,   // 포그(안개:fog)를 유효하게 한다.
    D3DRENDERSTATE_SPECULARENABLE     = 29,   // 스펙큐러 하이라이트를 유효하게 한다.
    D3DRENDERSTATE_ZVISIBLE           = 30,   // Z 체크를 유효하게 한다.
    D3DRENDERSTATE_STIPPLEDALPHA      = 33,   //점묘 알파를 유효하게 한다.
    D3DRENDERSTATE_FOGCOLOR           = 34,   // 포그(안개:fog) 컬러.
    D3DRENDERSTATE_FOGTABLEMODE       = 35,   // 포그(안개:fog) 모드.
    D3DRENDERSTATE_FOGTABLESTART      = 36,   // 포그(안개:fog) 테이블 시작 (D3DRENDERSTATE_FOGSTART 와 같다).
    D3DRENDERSTATE_FOGTABLEEND        = 37,   // 포그(안개:fog) 테이블 종료 (D3DRENDERSTATE_FOGEND 와 같다).
    D3DRENDERSTATE_FOGTABLEDENSITY    = 38,   // 포그(안개:fog) 테이블 밀도 (D3DRENDERSTATE_FOGDENSITY 와 같다).
    D3DRENDERSTATE_FOGSTART           = 36,   // 포그(안개:fog) 시작 (버텍스와 픽셀 포그(안개:fog)에 대해서).
    D3DRENDERSTATE_FOGEND             = 37,   // 포그(안개:fog) 종료 (버텍스와 픽셀 포그(안개:fog)에 대해서).
    D3DRENDERSTATE_FOGDENSITY         = 38,   // 포그(안개:fog) 밀도 (버텍스와 픽셀 포그(안개:fog)에 대해서).
    D3DRENDERSTATE_EDGEANTIALIAS      = 40,   // 에일리어징 제거 엣지.
    D3DRENDERSTATE_COLORKEYENABLE     = 41,   // 컬러 키 투과를 유효하게 한다.
    D3DRENDERSTATE_ZBIAS              = 47,   // Z 바이어스.
    D3DRENDERSTATE_RANGEFOGENABLE     = 48,   // 범위 베이스의 포그(안개:fog)를 유효하게 한다.
    D3DRENDERSTATE_STENCILENABLE      = 52,   // 스텐실 처리를 유효 또는 무효로 한다.
    D3DRENDERSTATE_STENCILFAIL        = 53,   // 스텐실 처리.
    D3DRENDERSTATE_STENCILZFAIL       = 54,   // 스텐실 처리.
    D3DRENDERSTATE_STENCILPASS        = 55,   // 스텐실 처리.
    D3DRENDERSTATE_STENCILFUNC        = 56,   // 스텐실 비교 함수.
    D3DRENDERSTATE_STENCILREF         = 57,   // 스텐실 테스트의 참조값.
    D3DRENDERSTATE_STENCILMASK        = 58,   // 스텐실 테스트로 사용되는 마스크값.
    D3DRENDERSTATE_STENCILWRITEMASK   = 59,   // 스텐실 버퍼 쓰기 마스크.
    D3DRENDERSTATE_TEXTUREFACTOR      = 60,   // 텍스쳐 계수.
    D3DRENDERSTATE_WRAP0              = 128,  // 1 번째의 텍스쳐 좌표 세트의 랩 플래그.
       // 여기에서는 1 에서 6 의 랩 렌더링 스테이트는 생략.
    D3DRENDERSTATE_WRAP7              = 135,  // 마지막 텍스쳐 좌표 세트의 랩 플래그.
    D3DRENDERSTATE_CLIPPING            = 136, // 프리미티브의 클리핑을 유효 또는 무효로 한다.
    D3DRENDERSTATE_LIGHTING            = 137, // 라이팅을 유효 또는 무효로 한다.
    D3DRENDERSTATE_EXTENTS             = 138, // 스크린 범위의 갱신을 유효 또는 무효로 한다.
    D3DRENDERSTATE_AMBIENT             = 139, // 장면의 앰비언트색.
    D3DRENDERSTATE_FOGVERTEXMODE       = 140, // 버텍스 포그(안개:fog)의 포그(안개:fog) 모드.
    D3DRENDERSTATE_COLORVERTEX         = 141, // 버텍스 단위의 색을 유효 또는 무효로 한다.
    D3DRENDERSTATE_LOCALVIEWER         = 142, // 퍼스펙티브 스펙큐러 하이라이트를 유효 또는 무효로 한다.
    D3DRENDERSTATE_NORMALIZENORMALS    = 143, // 버텍스 법선의 자동 정규화를 유효하게 한다.
    D3DRENDERSTATE_COLORKEYBLENDENABLE = 144, // 알파 블렌딩 컬러 키를 유효 또는 무효로 한다.
    D3DRENDERSTATE_DIFFUSEMATERIALSOURCE  = 145, // 버텍스 단위의 디 푸즈색의 위치.
    D3DRENDERSTATE_SPECULARMATERIALSOURCE = 146, // 버텍스 단위의 스펙큐러색의 위치.
    D3DRENDERSTATE_AMBIENTMATERIALSOURCE  = 147, // 버텍스 단위의 앰비언트색의 위치.
    D3DRENDERSTATE_EMISSIVEMATERIALSOURCE = 148, // 버텍스 단위의 에미션(emission)색의 위치.
    D3DRENDERSTATE_VERTEXBLEND              = 151, // 복수의 행렬에 의한 버텍스 블렌딩 모드.
    D3DRENDERSTATE_CLIPPLANEENABLE          = 152, // 1 개(살) 또는 복수의 유저 정의 크리피프면을 유효하게 한다
    D3DRENDERSTATE_FORCE_DWORD        = 0x7fffffff,
} D3DRENDERSTATETYPE;
D3DRENDERSTATE_ANTIALIAS
희망의 타입의 풀 신 anti-aliasing을 지정하는 D3DANTIALIASMODE 열거형의 멤버의 언젠가. 디폴트값은, D3DANTIALIAS_NONE 이다. 상세한 것에 대하여는, 「풀 신 anti-aliasing」 및 「anti-aliasing 스테이트」를 참조할것.

풀 신 anti-aliasing은, D3DPRASTERCAPS_ANTIALIASSORTINDEPENDENT 또는 D3DPRASTERCAPS_ANTIALIASSORTDEPENDENT 능력을 나타내는 디바이스에 한정해, 유효하게 할 수가 있다.

D3DRENDERSTATE_TEXTUREPERSPECTIVE
TRUE 를 설정 하면, 퍼스펙티브 보정 텍스쳐 맵핑이 유효하게 된다 ( 「퍼스펙티브 보정」을 참조할것). 디폴트값은 TRUE 이다. IDirect3DDvice3 보다 전의 인터페이스에서는, 디폴트값은 FALSE 이다. 상세한 것에 대하여는, 「텍스쳐 퍼스펙티브 스테이트」를 참조할것.
D3DRENDERSTATE_ZENABLE
D3DZBUFFERTYPE 열거형의 멤버의 1 개로서의 깊이 버퍼 스테이트. Z 버퍼링을 유효하게 하려면 D3DZB_TRUE, w 버퍼링을 유효하게 하려면 D3DZB_USEW, 깊이 버퍼링을 무효로 하려면 D3DZB_FALSE 를, 각각 설정한다.

렌더링의 대상이 되는 표면에 깊이 버퍼가 Attach 되고 있는 경우, 이 렌더링 스테이트의 디폴트값은 D3DZB_TRUE 이며, 그 이외의 경우는 D3DZB_FALSE 이다.

D3DRENDERSTATE_FILLMODE
D3DFILLMODE 열거형의 멤버의 언젠가 또는 복수. 디폴트값은 D3DFILL_SOLID 이다.
D3DRENDERSTATE_SHADEMODE
D3DSHADEMODE 열거형의 멤버의 언젠가 또는 복수. 디폴트값은 D3DSHADE_GOURAUD 이다.
D3DRENDERSTATE_LINEPATTERN
D3DLINEPATTERN 구조체. 디폴트값은 wRepeatPattern 가 0 으로,wLinePattern 가 0 이다.
D3DRENDERSTATE_ZWRITEENABLE
깊이 버퍼에의 쓰기를 유효하게 하려면 TRUE 로 설정한다. 디폴트값은 TRUE 이다. 어플리케이션은 이 멤버를 이용하는 것으로써, 시스템이 새로운 깊이값으로 깊이 버퍼를 갱신해 버리는 것을 막을 수가 있다. FALSE 의 경우, 렌더링 스테이트 D3DRENDERSTATE_ZFUNC (깊이 버퍼링을 하고 있으면(자) 가정)에 따라 깊이 비교가 실행되지만, 깊이값은 버퍼에 기입해지지 않다.
D3DRENDERSTATE_ALPHATESTENABLE
알파 테스트를 가능하게 하려면 , TRUE. 디폴트값은 FALSE 이다. 이 멤버를 사용 하면, 알파값에 근거해 픽셀을 받는지 거부할까를 판단하는 테스트를 오프로 할 수 있다.

들어 오는 알파값은, D3DRENDERSTATE_ALPHAFUNC 렌더링 스테이트에 의해 제공되는 비교 함수를 이용해 참조 알파값이라고 비교된다. 이 모드가 가능하게 되면(자), 테스트가 성공했을 경우에 한정해, 알파 블렌딩이 일어난다.

D3DRENDERSTATE_LASTPIXEL
직선이나 삼각형의 마지막 픽셀을 드로잉(Drawing) 가능으로 하려면 , FALSE 로 설정한다. 디폴트값은 TRUE 이다.
D3DRENDERSTATE_SRCBLEND
D3DBLEND 열거형의 멤버의 언젠가. 디폴트값은 D3DBLEND_ONE 이다.
D3DRENDERSTATE_DESTBLEND
D3DBLEND 열거형의 멤버의 1 개. 디폴트값은 D3DBLEND_ZERO 이다.
D3DRENDERSTATE_CULLMODE
뒷면을 향하는 삼각형을 잘라낼 필요가 생겼을 경우에, 그방법을 지정한다. D3DCULL 열거형의 멤버의 어느쪽이든을 설정할 수 있다. 디폴트값은 D3DCULL_CCW 이다.
D3DRENDERSTATE_ZFUNC
D3DCMPFUNC 열거형의 멤버의 언젠가. 디폴트값은 D3DCMP_LESSEQUAL 이다. 이 멤버는, 어플리케이션에카메라로부터의 거리를 기준으로 하는 픽셀의 수취나 받아 거부를 허가한다.

픽셀의 깊이값을 깊이 버퍼의 값과 비교한다. 픽셀의 깊이값이 비교 함수로 허가되었을 경우에 픽셀이 기입해진다.

깊이값이 깊이 버퍼에 기입해지는 것은, 렌더링 스테이트가 TRUE 의 경우 뿐이다.

이 깊이 테스트에 실패한 (분)편이, 소프트웨어에 의한 라스터화나 많은 하드웨어 가속기의 처리는 빨라진다. 이것은, 픽셀의 렌더링 처리를 실시하지 않는 경우에는, 텍스쳐를 필터 처리하거나 변조하거나 할 필요가 없어지기 때문에 있다.

D3DRENDERSTATE_ALPHAREF
알파 테스트가 유효하게 설정되어 있는 경우에, 픽셀을 테스트하기 위한 기준 알파값을 지정하는 값. 이것은,DWORD 렌더링 스테이트값의 하위 8 비트에 해당하는 8 비트값이다. 값은 0x00000000 에서 0x000000FF 의 범위내이다.
D3DRENDERSTATE_ALPHAFUNC
D3DCMPFUNC 열거형의 멤버의 언젠가. 디폴트값은, D3DCMP_ALWAYS 이다. 이 멤버는, 어플리케이션에 알파값을 기준으로 하는 픽셀의 수취나 받아 거부를 허가한다.
D3DRENDERSTATE_DITHERENABLE
TRUE 때, 디저링을 가능으로 한다. 디폴트값은 FALSE 이다.
D3DRENDERSTATE_ALPHABLENDENABLE
알파 블렌드에 의한 투명화를 유효하게 하는 경우, TRUE 에 세트 한다. 디폴트값은 FALSE 이다. 이 멤버는 종래의 D3DRENDERSTATE_BLENDENABLE 렌더링 스테이트에 대신해 사용된다. 상세한 것에 대하여는, 「주의」를 참조할것.

DirectX 5.0 이전으로는, 이 렌더링 스테이트를 이용해, 소프트웨어 래스터라이저는 컬러 키 검색과 알파 블렌딩의 변환을 실시하고 있었다. 현재는 D3DRENDERSTATE_COLORKEYENABLE 렌더링 스테이트를 사용해, 컬러 키잉을 바꾼다 (하드웨어는, 알파 블렌딩의 변환에게만, D3DRENDERSTATE_BLENDENABLE 렌더링 스테이트를 사용해 왔다).

알파 블렌딩의 타입은 D3DRENDERSTATE_SRCBLEND 와 D3DRENDERSTATE_DESTBLEND 렌더링 스테이트에 의해 결정된다. D3DRENDERSTATE_COLORKEYENABLE 과 함께 D3DRENDERSTATE_ALPHABLENDENABLE 를 사용하면, 알파 블렌딩의 미묘한 컨트롤이 가능하게 된다.

D3DRENDERSTATE_ALPHABLENDENABLE 는,D3DTEXTUREBLEND 열거형에 의해 지정되는 텍스쳐 블렌딩 모드에는 영향을 주지 않는다. 텍스쳐 블렌딩은, 논리적이게는 픽셀 파이프라인의 D3DRENDERSTATE_ALPHABLENDENABLE 부분에서(보다) 훨씬 전에 행해진다. 양자가 서로 관련하는 것은,D3DTEXTUREBLEND 국면 후의 다각형에 남는 알파 부분이, D3DRENDERSTATE_ALPHABLENDENABLE 국면으로 frame buffer의 내용과의 상호작용을 제어하기 위해서 사용되는 일이 있는 것만으로 있다.

어플리케이션은,D3DDEVICEDESC7 구조체의 3DDEVCAPS_DRAWPRIMTLVERTEX 플래그를 조사해, 이 렌더링 스테이트가 지원 되고 있는지 어떤지를 체크해야 한다.

D3DRENDERSTATE_FOGENABLE
TRUE 는 포그(안개:fog) 블렌딩을 가능하게 한다. 디폴트값은 FALSE 이다. 상세한 것에 대하여는, 「포그(안개:fog) 블렌딩」 및 「포그(안개:fog)」를 참조할것.
D3DRENDERSTATE_SPECULARENABLE
TRUE 는 스펙큐러 하이라이트를 가능하게 한다. 디폴트값은 FALSE 이다. IDirect3DDevice3 보다 전의 인터페이스에서는, 디폴트값은 TRUE 이다.

스펙큐러 하이라이트는, 빛이 맞고 있는 오브젝트의 각 버텍스가 그 오브젝트의 원점에 있는것 같이 산출된다. 이것은, 오브젝트가 원점의 주위로 모델화 되어 광원과 오브젝트간의 거리가 비교적으로 큰 경우에 한정해, 예측값을 준다.

이 멤버가 TRUE 로 설정되어 있는 경우, 텍스쳐 cascade와 알파 블렌딩의 사이에 베이스 컬러에 스펙큐러색이 추가된다.

D3DRENDERSTATE_ZVISIBLE
지원 되지 않는다.
D3DRENDERSTATE_STIPPLEDALPHA
TRUE 때, 점묘 알파를 가능으로 한다. 디폴트값은 FALSE 이다.

현재의 소프트웨어 래스터라이저는, 이 렌더링 스테이트를 무시한다. 현재의 하드웨어가 이 렌더링 스테이트를 지원 할지 어떨지를 조사하려면 ,D3DPRIMCAPS 구조체의 D3DPSHADECAPS_ALPHAFLATSTIPPLED 플래그를 사용한다.

D3DRENDERSTATE_FOGCOLOR
D3DCOLOR 형의 값. 디폴트값은 0 이다. 상세한 것에 대하여는, 「포그(안개:fog) 컬러」를 참조할것.
D3DRENDERSTATE_FOGTABLEMODE
픽셀 포그(안개:fog)에 사용되는 포그(안개:fog)식. D3DFOGMODE 열거형의 멤버의 어느쪽이든을 설정한다. 디폴트값은 D3DFOG_NONE 이다. 상세한 것에 대하여는, 「픽셀 포그(안개:fog)」를 참조할것.
D3DRENDERSTATE_FOGTABLESTART
D3DRENDERSTATE_FOGSTART 에 맵핑 한다.
D3DRENDERSTATE_FOGTABLEEND
D3DRENDERSTATE_FOGEND 에 맵핑 한다.
D3DRENDERSTATE_FOGTABLEDENSITY
이 렌더링 스테이트는 D3DRENDERSTATE_FOGDENSITY 렌더링 스테이트에 맵핑 한다.
D3DRENDERSTATE_FOGSTART
선형 포그(안개:fog) 모드에 있어서의, 픽셀 또는 버텍스 포그(안개:fog) 이펙트의 시작 깊이. 버텍스 포그(안개:fog)의 경우, 깊이는 월드 공간에서 지정된다. 픽셀 포그(안개:fog)의 경우는, 디바이스 공간 [0.0, 1.0] 또는 월드 공간의 어느쪽이든으로 지정된다. 픽셀 포그(안개:fog)에서는, 포그(안개:fog) 계산에 Z 가 사용되는 경우는 이러한 값은 디바이스 공간에 있어, 눈과의 상대 포그(안개:fog) (W 포그(안개:fog))가 사용되는 경우는 월드 공간에 있다. 상세한 것에 대하여는, 「포그(안개:fog) 파라미터」 및 「시점으로부터의 상대 깊이대 Z 베이스의 깊이」를 참조할것.

이 렌더링 스테이트의 값은 부동 소수점값이다. IDirect3DDevice7::SetRenderState 및 IDirect3DDevice7::SetRenderState 는 DWORD 값을 사용하기 위해(때문에), 다음의 코드에 나타내도록(듯이), 어플리케이션에서는 값을 저장 한 변수를 캐스트 해야 한다.

lpd3dDevice->SetRenderState( D3DRENDERSTATE_FOGSTART, *((LPDWORD) (&fFogStart)) );
D3DRENDERSTATE_FOGEND
선형 포그(안개:fog) 모드에 있어서의, 픽셀 또는 버텍스 포그(안개:fog) 이펙트의 종료 깊이. 버텍스 포그(안개:fog)의 경우, 깊이는 월드 공간에서 지정된다. 픽셀 포그(안개:fog)의 경우는, 디바이스 공간 [0.0, 1.0] 또는 월드 공간의 어느쪽이든으로 지정된다. 픽셀 포그(안개:fog)에서는, 포그(안개:fog) 계산에 Z 가 사용되는 경우는 이러한 값은 디바이스 공간에 있어, 눈과의 상대 포그(안개:fog) (W 포그(안개:fog))가 사용되는 경우는 월드 공간에 있다. 상세한 것에 대하여는, 「포그(안개:fog) 파라미터」 및 「시점으로부터의 상대 깊이대 Z 베이스의 깊이」를 참조할것.

이 렌더링 스테이트의 값은 부동 소수점값이다. IDirect3DDevice7::SetRenderState 및 IDirect3DDevice7::SetRenderState 는 DWORD 값을 사용하기 위해(때문에), 다음의 코드에 나타내도록(듯이), 어플리케이션에서는 값을 저장 한 변수를 캐스트 해야 한다.

lpd3dDevice->SetRenderState( D3DRENDERSTATE_FOGDENSITY, *((LPDWORD) (&fFogDensity)) );
D3DRENDERSTATE_FOGDENSITY
지수 포그(안개:fog) 모드 (D3DFOG_EXP 및 D3DFOG_EXP2)로 사용하는 픽셀 또는 버텍스 포그(안개:fog)의 포그(안개:fog) 밀도. 유효한 밀도는 0.0 에서 1.0 의 범위내이다. 디폴트값은 1,0 이다. 상세한 것에 대하여는 「포그(안개:fog) 파라미터」를 참조할것.

이 렌더링 스테이트의 값은 부동 소수점값이다. IDirect3DDevice7::SetRenderState 및 IDirect3DDevice7::SetRenderState 는 DWORD 값을 사용하기 위해(때문에), 다음의 코드에 나타내도록(듯이), 어플리케이션에서는 값을 저장 한 변수를 캐스트 해야 한다.

lpd3dDevice->SetRenderState( D3DRENDERSTATE_FOGDENSITY, *((LPDWORD) (&fFogDensity)) );
D3DRENDERSTATE_EDGEANTIALIAS
TRUE 는, 오브젝트의 철면의 윤곽을 형성하는 선을 에일리어징 제거 한다. 디폴트값은 FALSE 이다. 상세한 것에 대하여는, 「엣지 anti-aliasing」 및 「anti-aliasing 스테이트」를 참조할것. TRUE 의 경우, 렌더링의 대상이 되는 것은 선만으로, 장면내의 다각형의 외측 엣지로 한정된다. 이 렌더링 스테이트가 설정되어 있어, 삼각형 또는 점이 드로잉(Drawing) 되면(자), 그 동작은 부정이다. anti-aliasing는, 인접 픽셀의 값의 평균치를 취하는 것에 의해 실행된다. anti-aliasing를 실시하는 것은 최선의 방식은 아니지만, 효율적이다. 이런 종류의 조작을 지원 하는 하드웨어는 보급하고 있다.

엣지 anti-aliasing은, D3DPRASTERCAPS_ANTIALIASEDGES 능력을 나타내는 디바이스에 한정해, 유효하게 할 수가 있다.

D3DRENDERSTATE_COLORKEYENABLE
TRUE 는, 컬러 키 투과를 가능하게 한다. 디폴트값은 FALSE 이다. 이 렌더링 스테이트를 D3DRENDERSTATE_ALPHABLENDENABLE 로 사용 하면, 블렌딩의 미조정이 가능하게 된다.

어플리케이션에서는 D3DDEVICEDESC7 구조체의 D3DDEVCAPS_DRAWPRIMTLVERTEX 플래그를 조사해, 이 렌더링 스테이트가 지원 되고 있는지 어떤지를 체크한다.

컬러 키 투과가 유효한 경우, DDSD_CKSRCBLT 플래그로 생성 된 텍스쳐 표면만 영향을 받는다. DDSD_CKSRCBLT 플래그로 생성되어 있지 않은 표면은, 컬러 키 투과의 이펙트를 나타낸다.

D3DRENDERSTATE_ZBIAS
물리적으로는 동일 얼굴에 있는 다각형이 따로 따로 존재하도록(듯이) 보이게 하는, 0 에서 16 까지의 범위의 정수값. Z 바이어스값이 높은 다각형은, Z 바이어스값이 낮은 다각형보다 앞에 표시되기 (위해)때문에, 드로잉(Drawing) 순서를 결정하는 소트를 실행할 필요는 없다. 예를 들어, 값 1 을 가지는 다각형은, 값 0 의 다각형보다 앞으로 보인다. 디폴트값은 0 이다. 상세한 것에 대하여는, 「깊이 버퍼의 사용」을 참조할것.
D3DRENDERSTATE_RANGEFOGENABLE
TRUE 를 설정 하면, 범위 베이스의 버텍스 포그(안개:fog)가 유효하게 된다 (디폴트값은 FALSE. 이 경우는 깊이에 근거하는 포그(안개:fog)가 사용된다). 범위 준거의 포그(안개:fog)에서는, 장면에 있어서의 오브젝트의 깊이 (z 좌표)는 아니고, 오브젝트의 뷰아로부터의 거리로 포그(안개:fog) 이펙트를 계산한다. 범위 준거의 포그(안개:fog)에서는, 보통 모든 포그(안개:fog) 계산 메소드가 움직이지만, 계산에 깊이가 아니게 범위를 사용하는 점만이 다르다.

범위는 포그(안개:fog) 계산에 사용하는데 올바른 요소이지만, 범위가 계산 카미타카값이 되는 한편, 깊이는 보통 계산이 끝난 상태이므로, 대표해 깊이가 넓게 사용된다. 깊이를 사용해 포그(안개:fog)를 계산 하면, 주변 오브젝트의 포그(안개:fog) 이펙트가 시점의 이동과 함께 변화 하면 말하는 바람직하지 않은 영향이 나온다. 이 경우, 깊이는 변화하지만 범위는 일정한 까지 있다.

이 렌더링 스테이트는 D3DVERTEX 버텍스 에 대해서만 작용한다. D3DLVERTEX 또는 D3DTLVERTEX 버텍스를 지정하는 경우, RGBF 포그(안개:fog)값의 F (포그(안개:fog)) 요소가 범위에 대해 보정이 끝난 상태가 아니면 안된다.

현재로서는, 픽셀 단위에서의 범위 베이스의 포그(안개:fog)를 지원 하는 하드웨어는 존재하지 않기 때문에, 범위 보정은 버텍스 포그(안개:fog)에서만 행해진다. 상세한 것에 대하여는, 「범위 베이스의 포그(안개:fog)」 및 「버텍스 포그(안개:fog)」를 참조할것.

D3DRENDERSTATE_STENCILENABLE
TRUE 의 경우는 스텐실 조작이 가능하게 되어, FALSE 에서는 무효가 된다. 디폴트값은 FALSE 이다. 상세한 것에 대하여는, 「스텐실 버퍼」를 참조할것.
D3DRENDERSTATE_STENCILFAIL
스텐실 테스트에 실패했을 때에 실행하는 스텐실 조작. 이것에는 D3DSTENCILOP 열거형의 멤버의 어느쪽이든을 설정할 수 있다. 디폴트값은 D3DSTENCILOP_KEEP 이다. 상세한 것에 대하여는, 「스텐실 버퍼」를 참조할것.
D3DRENDERSTATE_STENCILZFAIL
스텐실 테스트에 패스해, 깊이 테스트 (Z 테스트)에 실패했을 경우에 실행하는 스텐실 조작. 이것에는 D3DSTENCILOP 열거형의 멤버의 어느쪽이든을 설정할 수 있다. 디폴트값은 D3DSTENCILOP_KEEP 이다. 상세한 것에 대하여는, 「스텐실 버퍼」를 참조할것.
D3DRENDERSTATE_STENCILPASS
스텐실 테스트 및 깊이 (Z) 테스트의 양쪽 모두에 패스했을 경우에 실행하는 스텐실 조작. 이것에는 D3DSTENCILOP 열거형의 멤버의 어느쪽이든을 설정할 수 있다. 디폴트값은 D3DSTENCILOP_KEEP 이다. 상세한 것에 대하여는, 「스텐실 버퍼」를 참조할것.
D3DRENDERSTATE_STENCILFUNC
스텐실 테스트를 위한 비교 함수. 이것에는 D3DCMPFUNC 열거형의 멤버의 어느쪽이든을 설정할 수 있다. 디폴트값은 D3DCMP_ALWAYS 이다.

비교 함수는, 스텐실 버퍼의 요소를 기준치와 비교하기 위해서(때문에) 사용된다. 이 비교는, 기준치의 비트와 스텐실 마스크 (D3DRENDERSTATE_STENCILMASK 렌더링 스테이트에 의해 설정)로 설정된 스텐실 버퍼 요소에게만 적용된다. TRUE 의 경우, 스텐실 테스트에 패스한다.

D3DRENDERSTATE_STENCILREF
스텐실 테스트를 위한 정수 기준치. 디폴트값은 0 이다.
D3DRENDERSTATE_STENCILMASK
기준치와 각각의 스텐실 버퍼 요소에 적용해, 스텐실 테스트를 위한 유효 비트를 결정하는 마스크. 디폴트 마스크는 0xFFFFFFFF 이다.
D3DRENDERSTATE_STENCILWRITEMASK
스텐실 버퍼에 기입하는 값에 적용하는 쓰기 마스크. 디폴트 마스크는 0xFFFFFFFF 이다.
D3DRENDERSTATE_TEXTUREFACTOR
D3DTA_TFACTOR 텍스쳐 블렌딩 인수, 또는 D3DTOP_BLENDFACTORALPHA 텍스쳐 블렌딩 조작을 이용한 멀티 텍스쳐 블렌딩으로 사용되는 색. 관련하는 값은 D3DCOLOR 변수이다.
D3DRENDERSTATE_WRAP0 으로부터 D3DRENDERSTATE_WRAP7
복수의 텍스쳐 좌표 세트에 대한 텍스쳐 랩핑 동작. 이러한 렌더링 스테이트의 유효값으로서 D3DWRAPCOORD_0, D3DWRAPCOORD_1, D3DWRAPCOORD_2, 및 D3DWRAPCOORD_3 플래그를 조합할 수가 있다. 이러한 값을 설정 하면, 지정된 텍스쳐에 대해서 1, 2, 3, 및 4 차원 방향 (s, t, r, 및 q 방향으로 불리는 경우도 있다)의 랩핑이 실행된다. 이러한 렌더링 스테이트의 디폴트값은 0 이다 (전방향의 랩핑이 무효). 상세한 것에 대하여는, 「텍스쳐 랩핑」을 참조할것.
D3DRENDERSTATE_CLIPPING
TRUE 를 설정 하면, Direct3D 에 의한 프리미티브의 클리핑이 유효하게 된다. FALSE 를 설정 하면 무효가 된다. 디폴트값은 TRUE 이다.
D3DRENDERSTATE_LIGHTING
TRUE 를 설정 하면, Direct3D 의 라이팅이 유효하게 된다. FALSE 를 설정 하면 무효가 된다. 디폴트값은 TRUE 이다. 버텍스 법선을 포함한 버텍스만 올바르게 라이트가 댈 수 있어 법선을 포함하지 않는 버텍스에서는 모든 라이팅 계산으로 0 의 내적이 사용된다.
D3DRENDERSTATE_EXTENTS
TRUE 를 설정 하면, 렌더링이 호출할 것에 스크린 범위가 갱신된다. FALSE 를 설정 하면, 스크린 범위의 갱신이 무효가 된다. 디폴트값은 FALSE 이다.
D3DRENDERSTATE_AMBIENT
앰비언트 라이트의 색. 이 값은 D3DCOLOR 형이다. 디폴트값은 0 이다. 이 렌더링 스테이트는, 종래의 D3DLIGHTSTATE_AMBIENT 라이트 스테이트에 유사한다.
D3DRENDERSTATE_FOGVERTEXMODE
버텍스 포그(안개:fog)용의 포그(안개:fog)식. D3DFOGMODE 열거형의 멤버의 어느쪽이든을 설정한다. 디폴트값은 D3DFOG_NONE 이다. 상세한 것에 대하여는, 「버텍스 포그(안개:fog)」를 참조할것. 이 렌더링 스테이트는, 종래의 D3DLIGHTSTATE_FOGVERTEXMODE 라이팅 스테이트에 유사한다.
D3DRENDERSTATE_COLORVERTEX
TRUE 를 설정 하면, 버텍스 단위의 색이 유효하게 된다. FALSE 를 설정 하면 무효가 된다. 디폴트값은 TRUE 이다. 버텍스 단위의 색을 유효하게 하면, 각각의 버텍스에 정의된 색이 라이팅 계산에 포함되게 된다. 이 렌더링 스테이트는, 종래의 D3DLIGHTSTATE_COLORVERTEX 라이팅 스테이트에 유사한다.

상세한 것에 대하여는, 이하의 렌더링 스테이트를 참조할것.

  • D3DRENDERSTATE_DIFFUSEMATERIALSOURCE
  • D3DRENDERSTATE_SPECULARMATERIALSOURCE
  • D3DRENDERSTATE_AMBIENTMATERIALSOURCE
  • D3DRENDERSTATE_EMISSIVEMATERIALSOURCE
D3DRENDERSTATE_LOCALVIEWER
TRUE 를 설정 하면, 카메라와의 상대 각도에 의존한 스펙큐러 하이라이트가 유효하게 된다. FALSE 를 설정 하면, 직행 스펙큐러 하이라이트가 사용된다. 디폴트값은 TRUE 이다. 정사영을 사용하는 어플리케이션에서는 FALSE 로 지정하는 것.
D3DRENDERSTATE_NORMALIZENORMALS
TRUE 를 설정 하면, 버텍스 법선의 자동 정규화가 유효하게 된다. FALSE 를 설정 하면 무효가 된다. 디폴트값은 FALSE 이다. 이 기능을 유효하게 하면, 버텍스가 카메라 공간에 트랜스 폼 된 다음에 버텍스 법선이 정규화되지만, 계산 부하가 크다.
D3DRENDERSTATE_COLORKEYBLENDENABLE
TRUE 를 설정 하면, 알파 블렌딩 컬러 키잉이 유효하게 된다. FALSE 를 설정 하면 무효가 된다. 알파 블렌딩 컬러 키 모드는, 일치하는 텍스쳐 샘플의 알파 및 컬러를 0 으로 설정한다. 어플리케이션에서는, 알파 테스트 및 알파 블렌딩 모드를 설정해, 필요한 파기 및 알파 블렌딩 결과의 양쪽 모두, 또는 그 어느쪽이든을 실시할 필요가 있다.
D3DRENDERSTATE_DIFFUSEMATERIALSOURCE
라이팅 계산에 사용되는 디 푸즈색의 소스. 유효값은 D3DMATERIALCOLORSOURCE 열거형의 멤버이다. 디폴트값은 D3DMCS_COLOR1. 이 렌더링 스테이트의 값이 사용되는 것은, D3DRENDERSTATE_COLORVERTEX 렌더링 스테이트가 TRUE 로 설정되어 있는 경우뿐이다.
D3DRENDERSTATE_SPECULARMATERIALSOURCE
라이팅 계산에 사용되는 스펙큐러색의 소스. 유효값은 D3DMATERIALCOLORSOURCE 열거형의 멤버이다. 디폴트값은 D3DMCS_COLOR2.
D3DRENDERSTATE_AMBIENTMATERIALSOURCE
라이팅 계산에 사용되는 앰비언트색의 소스. 유효값은 D3DMATERIALCOLORSOURCE 열거형의 멤버이다. 디폴트값은 D3DMCS_COLOR2.
D3DRENDERSTATE_EMISSIVEMATERIALSOURCE
라이팅 계산에 사용되는 에미션(emission)색의 소스. 유효값은 D3DMATERIALCOLORSOURCE 열거형의 멤버이다. 디폴트값은 D3DMCS_MATERIAL.
D3DRENDERSTATE_VERTEXBLEND
지오메트리가 있는 경우, 지오메트리 블렌딩을 실행하기 위해서 사용하는 행렬의 개수. 유효값은 D3DVERTEXBLENDFLAGS 열거형의 멤버이다. 디폴트값은 D3DVBLEND_DISABLE. 상세한 것에 대하여는, 「지오메트리 블렌딩」을 참조할것.
D3DRENDERSTATE_CLIPPLANEENABLE
유저 정의 클립면을 유효 또는 무효로 한다. 유효값은, 각 비트의 스테이터스 (설정의 유무)에 의해 대응하는 유저 정의 클립면의 기동 스테이트를 바꾸는, 임의의 DWORD 이다. 최하정도 비트 (비트 0)는 인덱스 0 의 최초의 클립면을 제어해, 후속 비트는 그것보다 상위의 인덱스의 클립면의 기동을 제어한다. 비트가 설정되어 있는 경우, 장면의 렌더링중에 적절한 클립면이 적용된다. 디폴트값은 0 이다.

클립면을 간단하게 유효하게 할 수 있도록(듯이), D3dtypes.h 헤더 파일에는 D3DCLIPPLANEn 매크로가 선언되고 있다.

D3DRENDERSTATE_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

D3DRENDERSTATE_BLENDENABLE 멤버는 D3DRENDERSTATE_ALPHABLENDENABLE 멤버로 옮겨지고 있다. 의미가 보다 명료하게 되도록(듯이) 이름도 변경되고 있다. 이전의 어플리케이션과의 호환성을 유지하기 위해서, D3DRENDERSTATE_ALPHABLENDENABLE 에 대응하는 것으로서 D3DRENDERSTATE_BLENDENABLE 정수가 선언되고 있다.

#define D3DRENDERSTATE_BLENDENABLE  D3DRENDERSTATE_ALPHABLENDENABLE

Direct3D 는, 어플리케이션에서의 편의를 고려해, (D3DRENDERSTATE_WRAPn 스테이트값의 1 개를 명시적으로 사용하는 대신에) D3DRENDERSTATE_WRAPBIAS 정수를 정의해, 텍스쳐 좌표 세트의 제로 시점 정수값에 근거해, 텍스쳐 랩핑을 유효하게 하거나 무효로 하거나 한다. 다음의 예의 같게, D3DRENDERSTATE_WRAPBIAS 값을 텍스쳐 좌표 세트의 제로 시점 인덱스에 덧셈 해, 그 인덱스에 대응하는 D3DRENDERSTATE_WRAPn 값을 계산한다.

// 변수 dwIndex 의 인덱스에 대응하는 텍스쳐 좌표 세트를
// 사용하는 텍스쳐에 대해서, U/V 랩핑을 유효하게 한다.
HRESULT hr = lpD3DDevice->SetRenderState(
    dwIndex + D3DRENDERSTATE_WRAPBIAS,
    D3DWRAP_0 | D3DWRAP1);

// dwIndex가 3 의 경우, 덧셈의 결과의 값은,
// D3DRENDERSTATE_WRAP3 (131)에 동일해진다.

D3dtypes.h 내의 D3DRENDERSTATETYPE 의 선언에는, DirectX 7.0 인터페이스로 지원 되지 않는 종래의 렌더링 스테이트가 포함되어 있다. 상세한 것에 대하여는, 「폐지된 렌더링 스테이트」를 참조할것.

    D3DRENDERSTATE_TEXTUREHANDLE      = 1,    // 텍스쳐 핸들.
    D3DRENDERSTATE_TEXTUREADDRESS     = 3,    // 텍스쳐 주소.
    D3DRENDERSTATE_WRAPU              = 5,    // u 방향의 랩.
    D3DRENDERSTATE_WRAPV              = 6,    // v 방향의 랩.
    D3DRENDERSTATE_MONOENABLE         = 11,   // 물건 렌더링이 유효.
    D3DRENDERSTATE_ROP2               = 12,   // 라스터화.
    D3DRENDERSTATE_PLANEMASK          = 13,   // 물리적 평면 마스크.
    D3DRENDERSTATE_TEXTUREMAG         = 17,   // 옮겨놓을 수 있고 있다.
    D3DRENDERSTATE_TEXTUREMIN         = 18,   // 옮겨놓을 수 있고 있다.
    D3DRENDERSTATE_TEXTUREMAPBLEND    = 21,   // 맵의 블렌딩 모드.
    D3DRENDERSTATE_SUBPIXEL           = 31,   // 서브 픽셀 보정이 유효.
    D3DRENDERSTATE_SUBPIXELX          = 32,   // x 서브 픽셀 보정이 유효.
    D3DRENDERSTATE_STIPPLEENABLE      = 39,   // 점묘가 유효.
    D3DRENDERSTATE_BORDERCOLOR        = 43,   // 경계색.
    D3DRENDERSTATE_TEXTUREADDRESSU    = 44,   // u 텍스쳐 addressing mode.
    D3DRENDERSTATE_TEXTUREADDRESSV    = 45,   // v 텍스쳐 addressing mode.
    D3DRENDERSTATE_MIPMAPLODBIAS      = 46,   // 밉맵 LOD 바이어스.
    D3DRENDERSTATE_ANISOTROPY         = 49,   // 최대 비등방성.
    D3DRENDERSTATE_FLUSHBATCH         = 50,   // DP 배치처리의 명시적 플래시 (DX5 마셔).
    D3DRENDERSTATE_TRANSLUCENTSORTINDEPENDENT=51, / /소트비의존형 투명성이 유효.
    D3DRENDERSTATE_STIPPLEPATTERN00   = 64,   // 점묘 패턴의 최초의 선.
       // 여기에서는, 점묘 패턴의 01 에서 30 까지를 생략.
    D3DRENDERSTATE_STIPPLEPATTERN31   = 95,   // 점묘 패턴의 마지막 선.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

IDirect3DDevice7::SetRenderState ,IDirect3DDevice7::GetRenderState ,렌더링 스테이트


D3DSHADEMODE

D3DSHADEMODE 열거형은,D3DRENDERSTATETYPE 열거형의 D3DRENDERSTATE_SHADEMODE 렌더링 스테이트용으로, 지원 되는 쉐이딩 모드를 지정한다.

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 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

D3DRENDERSTATETYPE


D3DSTATEBLOCKTYPE

D3DSTATEBLOCK 열거형은,IDirect3DDevice7::CreateStateBlock 메소드로 사용하는, 디바이스 스테이트의 논리 그룹을 정의한다.

typedef enum _D3DSTATEBLOCKTYPE{
    D3DSBT_ALL           = 1,
    D3DSBT_PIXELSTATE    = 2,
    D3DSBT_VERTEXSTATE   = 3,
    D3DSBT_FORCE_DWORD   = 0xffffffff
} D3DSTATEBLOCKTYPE;
D3DSBT_ALL
모든 디바이스 스테이트를 수중에 넣는다.
D3DSBT_PIXELSTATE
픽셀 관련의 디바이스 스테이트만 수중에 넣는다.
D3DSBT_VERTEXSTATE
버텍스 관련의 디바이스 스테이트만 수중에 넣는다.
D3DSBT_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

D3DSBT_PIXELSTATE 및 D3DSBT_VERTEXSTATE 값은, 다른 논리 그룹의 디바이스 스테이트를 각각 식별하지만, 스테이트에 따라서는 양쪽 모두의 그룹에 공통되는 것도 있다. 각 그룹에서 정의되는 스테이트의 상세한 것에 대하여는, 「사전 정의하는 스테이트 블록의 생성」을 참조할것.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3dtypes.h 로 선언.

참조

IDirect3DDevice7::CreateStateBlock


D3DSTENCILOP

D3DSTENCILOP 열거형은,D3DRENDERSTATE_STENCILFAIL ,D3DRENDERSTATE_STENCILZFAIL , 및 D3DRENDERSTATE_STENCILPASS 렌더링 스테이트의 스텐실 처리를 기술한다.

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 는 스텐실 버퍼의 비트 깊이.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 6.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

D3DRENDERSTATETYPE ,스텐실 버퍼


D3DTEXTUREADDRESS

D3DTEXTUREADDRESS 열거형은,D3DTSS_ADDRESS ,D3DTSS_ADDRESSU , 및 D3DTSS_ADDRESSV 텍스쳐 스테이지 스테이트에서 텍스쳐 addressing mode를 설정할 때에 지원 되는 모드를 기술한다.

typedef enum _D3DTEXTUREADDRESS {
    D3DTADDRESS_WRAP         = 1,
    D3DTADDRESS_MIRROR       = 2,
    D3DTADDRESS_CLAMP        = 3,
    D3DTADDRESS_BORDER       = 4,
    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] 의 범위외에 있는 텍스쳐 좌표는 경계색으로 설정된다. 이것은 D3DRENDERSTATETYPE 열거형의 D3DRENDERSTATE_BORDERCOLOR 에 대응하는 새로운 렌더링 스테이트이다.
D3DTADDRESS_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

D3DRENDERSTATE_WRAPU 및 D3DRENDERSTATE_WRAPV 렌더링 스테이트의 사용의 상세한 것에 대하여는, 「텍스쳐」를 참조할것.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

D3DRENDERSTATETYPE


D3DTEXTUREMAGFILTER

D3DTEXTUREMAGFILTER 열거형은, 텍스쳐 스테이지의 텍스쳐 확대 필터 모드를 정의한다.

typedef enum _D3DTEXTUREMAGFILTER {
    D3DTFG_POINT        = 1,
    D3DTFG_LINEAR       = 2,
    D3DTFG_FLATCUBIC    = 3,
    D3DTFG_GAUSSIANCUBIC= 4,
    D3DTFG_ANISOTROPIC  = 5,
    D3DTFG_FORCE_DWORD  = 0x7fffffff,
} D3DTEXTUREMAGFILTER;
D3DTFG_POINT
점필터링. 희망의 픽셀값에 가장 가까운 좌표를 가지는 텍셀을 사용한다.
D3DTFG_LINEAR
바이리니아 보간 필터링. 희망의 픽셀을 둘러싸는 2 x 2 영역의 텍셀의 중량감 첨부 평균을 사용한다.
D3DTFG_FLATCUBIC
현재 지원되어 있지 않다. 사용 불가.
D3DTFG_GAUSSIANCUBIC
현재 지원되어 있지 않다. 사용 불가.
D3DTFG_ANISOTROPIC
비등방성 텍스쳐 필터링. 텍스쳐 다각형과 스크린 평면간의 각도의 상위에 의해 일어나는 일그러짐을 보정한다.
D3DTFG_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

텍스쳐 스테이지의 확대 필터를 설정하려면 ,IDirect3DDevice7::SetTextureStageState 메소드를 호출해, 제 2 파라미터로서 D3DTSS_MAGFILTER 값을 지정해, 제 3 파라미터로서 이 열거의 멤버의 어느쪽이든을 지정한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 6.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

D3DTEXTUREMINFILTER ,D3DTEXTUREMIPFILTER ,텍스쳐 필터링


D3DTEXTUREMINFILTER

D3DTEXTUREMINFILTER 열거형은, 텍스쳐 스테이지의 텍스쳐 축소 필터 모드를 정의한다.

typedef enum _D3DTEXTUREMINFILTER {
    D3DTFN_POINT        = 1,
    D3DTFN_LINEAR       = 2,
    D3DTFN_ANISOTROPIC  = 3,
    D3DTFN_FORCE_DWORD  = 0x7fffffff,
} D3DTEXTUREMINFILTER;
D3DTFN_POINT
점필터링. 희망의 픽셀값에 가장 가까운 좌표를 가지는 텍셀을 사용한다.
D3DTFN_LINEAR
바이리니아 보간 필터링. 희망의 픽셀을 둘러싸는 2 x 2 영역의 텍셀의 중량감 첨부 평균을 사용한다.
D3DTFN_ANISOTROPIC
비등방성 텍스쳐 필터링. 텍스쳐 다각형과 스크린 평면간의 각도의 상위에 의해 일어나는 일그러짐을 보정한다.
D3DTFN_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

텍스쳐 스테이지의 확대 필터를 설정하려면 ,IDirect3DDevice7::SetTextureStageState 메소드를 호출해, 제 2 파라미터로서 D3DTSS_MINFILTER 값을 지정해, 제 3 파라미터로서 이 열거의 멤버의 어느쪽이든을 지정한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 6.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

D3DTEXTUREMAGFILTER ,D3DTEXTUREMIPFILTER ,텍스쳐 필터링


D3DTEXTUREMIPFILTER

D3DTEXTUREMIPFILTER 열거형은, 텍스쳐 스테이지의 텍스쳐 밉맵 필터 모드를 정의한다.

typedef enum _D3DTEXTUREMIPFILTER {
    D3DTFP_NONE         = 1,
    D3DTFP_POINT        = 2,
    D3DTFP_LINEAR       = 3,
    D3DTFP_FORCE_DWORD  = 0x7fffffff,
} D3DTEXTUREMIPFILTER;
D3DTFP_NONE
밉맵 처리를 무효로 한다. 래스터라이저는 대신에 확대 필터를 사용한다.
D3DTFP_POINT
최근점밉맵 필터. 래스터라이저는 가장 가까운 밉맵 텍스쳐의 텍셀로부터의 색을 사용한다.
D3DTFP_LINEAR
트라이 리니어 밉맵 보간. 래스터라이저는, 가장 가까운 밉맵 텍스쳐 2 점으로부터의 텍셀을 사용해 픽셀색을 선형 보간 한다.
D3DTFP_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

텍스쳐 스테이지의 확대 필터를 설정하려면 ,IDirect3DDevice7::SetTextureStageState 메소드를 호출해, 제 2 파라미터로서 D3DTSS_MIPFILTER 값을 지정해, 제 3 파라미터로서 이 열거의 멤버의 어느쪽이든을 지정한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 6.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

D3DTEXTUREMAGFILTER ,D3DTEXTUREMIPFILTER ,텍스쳐 필터링


D3DTEXTUREOP

D3DTEXTUREOP 열거형은, 스테이지 단위에서의 텍스쳐 블렌딩 조작을 정의한다. 이 열거형의 멤버는, D3DTSS_COLOROP 또는 D3DTSS_ALPHAOP 값으로 IDirect3DDevice7::SetTextureStageState 메소드를 호출해 색처리 또는 알파 처리를 설정할 때에 사용된다.

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_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_BLENDDIFFUSEALPHA), 이 스테이지의 텍스쳐로부터의 알파 (D3DTOP_BLENDTEXTUREALPHA),D3DRENDERSTATE_TEXTUREFACTOR 렌더링 스테이트에서 설정되는 스칼라-알파 (D3DTOP_BLENDFACTORALPHA), 또는 전의 텍스쳐 스테이지로부터의 알파 (D3DTOP_BLENDCURRENTALPHA)를 사용해, 이 스테이지의 선형 블렌딩을 실시한다.

D3DTOP_BLENDTEXTUREALPHA
각 버텍스로부터의 보간 알파 (D3DTOP_BLENDDIFFUSEALPHA), 이 스테이지의 텍스쳐로부터의 알파 (D3DTOP_BLENDTEXTUREALPHA),D3DRENDERSTATE_TEXTUREFACTOR 렌더링 스테이트에서 설정되는 스칼라-알파 (D3DTOP_BLENDFACTORALPHA), 또는 전의 텍스쳐 스테이지로부터의 알파 (D3DTOP_BLENDCURRENTALPHA)를 사용해, 이 스테이지의 선형 블렌딩을 실시한다.

D3DTOP_BLENDFACTORALPHA
각 버텍스로부터의 보간 알파 (D3DTOP_BLENDDIFFUSEALPHA), 이 스테이지의 텍스쳐로부터의 알파 (D3DTOP_BLENDTEXTUREALPHA),D3DRENDERSTATE_TEXTUREFACTOR 렌더링 스테이트에서 설정되는 스칼라-알파 (D3DTOP_BLENDFACTORALPHA), 또는 전의 텍스쳐 스테이지로부터의 알파 (D3DTOP_BLENDCURRENTALPHA)를 사용해, 이 스테이지의 선형 블렌딩을 실시한다.

D3DTOP_BLENDCURRENTALPHA
각 버텍스로부터의 보간 알파 (D3DTOP_BLENDDIFFUSEALPHA), 이 스테이지의 텍스쳐로부터의 알파 (D3DTOP_BLENDTEXTUREALPHA),D3DRENDERSTATE_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
다음의 텍스쳐 스테이지의 환경 맵 (휘도(Luminance) 없음)에 의한, 픽셀 단위의 범프 맵핑을 실행한다. 이 조작은, 색조작 (D3DTSS_COLOROP)에서만 지원 된다.
D3DTOP_BUMPENVMAPLUMINANCE
다음의 텍스쳐 스테이지의 환경 맵 (휘도(Luminance) 있어)에 의한, 픽셀 단위의 범프 맵핑을 실행한다. 이 조작은, 색조작 (D3DTSS_COLOROP)에서만 지원 된다.
D3DTOP_DOTPRODUCT3
각 인수의 요소를 (부호부 요소로서) 변조해 적을 덧셈 해, 얻을 수 있던 합계값을 모든 색채널에, 알파를 포함해 복제한다. 이 조작이 지원 되는 것은 색조작과 알파 조작에 대해서이다.

그 외의 멤버
D3DTOP_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

위에의식에서는, SRGBA 는 텍스쳐 조작으로 생성 되는 RGBA 색,Arg1 및 Arg2 는 텍스쳐 인수의 완전 RGBA 색이다. 인수의 각각의 요소는, 첨자를 붙여 표기된다. 예를 들어, 인수 1 의 알파 요소는 Arg1A 로서 나타내진다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 6.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

IDirect3DDevice7::GetTextureStageState ,IDirect3DDevice7::SetTextureStageState ,D3DTEXTURESTAGESTATETYPE


D3DTEXTURESTAGESTATETYPE

D3DTEXTURESTAGESTATETYPE 열거형은 텍스쳐 스테이지 스테이트를 정의한다. 이 열거형의 멤버는, 텍스쳐 스테이트값을 취득 및 설정하기 위해서 IDirect3DDevice7::GetTextureStageState 및 IDirect3DDevice7::SetTextureStageState 메소드로 사용한다.

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_ADDRESS        = 12,
    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_FORCE_DWORD   = 0x7fffffff,
} D3DTEXTURESTAGESTATETYPE;
D3DTSS_COLOROP
텍스쳐 스테이지 스테이트는 텍스쳐색의 혼합 조작이며,D3DTEXTUREOP 열거형의 멤버에 의해 식별된다. 최초의 텍스쳐 스테이지 (스테이지 0)의 디폴트값은 D3DTOP_MODULATE 이며, 그 이외의 모든 스테이지의 디폴트값은 D3DTOP_DISABLE 이다.
D3DTSS_COLORARG1
텍스쳐 스테이지 스테이트는, 그 스테이지에 대한 최초의 색인수이며,텍스쳐 인수 플래그에 의해 식별된다. 디폴트 인수는 D3DTA_TEXTURE 이다.
D3DTSS_COLORARG2
텍스쳐 스테이지 스테이트는, 그 스테이지에 대한 2 번째의 색인수이며,텍스쳐 인수 플래그에 의해 식별된다. 디폴트 인수는 D3DTA_CURRENT 이다.
D3DTSS_ALPHAOP
텍스쳐 스테이지 스테이트는, 텍스쳐 알파 블렌딩 처리이며,D3DTEXTUREOP 열거형의 멤버에 의해 식별된다. 최초의 텍스쳐 스테이지 (스테이지 0)의 디폴트값은 D3DTOP_SELECTARG1 이며, 그 이외의 모든 스테이지의 디폴트값은 D3DTOP_DISABLE 이다.

DirectX 6.0 에서는, 이 스테이지에 있어서의 디폴트의 동작은, 텍스쳐 처리로서 기술되지 않는다. 그 대신해, 알파 블렌딩의 동작은, D3DRENDERSTATE_TEXTUREMAPBLEND 렌더링 스테이트의 동작을 D3DTBLEND_MODULATE 의 값과 일치시킨다.

D3DTSS_ALPHAARG1
텍스쳐 스테이지 스테이트는, 그 스테이지에 대한 최초의 알파 인수이며,텍스쳐 인수 플래그에 의해 식별된다. 디폴트의 인수는 D3DTA_TEXTURE 이다. 스테이지에 텍스쳐가 설정되어 있지 않은 경우는 D3DTA_DIFFUSE 가 디폴트의 인수가 된다.
D3DTSS_ALPHAARG2
텍스쳐 스테이지 스테이트는, 스테이지의 2 번째의 알파 인수이며,텍스쳐 인수 플래그에 의해 식별된다. 디폴트 인수는 D3DTA_CURRENT 이다.
D3DTSS_BUMPENVMAT00
텍스쳐 스테이지 스테이트는, 범프 맵핑 행렬의 [0][0] 계수에 대한 D3DVALUE 이다. 디폴트값은 0 이다.
D3DTSS_BUMPENVMAT01
텍스쳐 스테이지 스테이트는, 범프 맵핑 행렬의 [0][1] 계수에 대한 D3DVALUE 이다. 디폴트값은 0 이다.
D3DTSS_BUMPENVMAT10
텍스쳐 스테이지 스테이트는, 범프 맵핑 행렬의 [1][0] 계수에 대한 D3DVALUE 이다. 디폴트값은 0 이다.
D3DTSS_BUMPENVMAT11
텍스쳐 스테이지 스테이트는, 범프 맵핑 행렬의 [1][1] 계수에 대한 D3DVALUE 이다. 디폴트값은 0 이다.
D3DTSS_TEXCOORDINDEX
이 텍스쳐 스테이지에서 사용하기 위해서 설정된 텍스쳐 좌표 인덱스. 디폴트의 인덱스는 0. 이 스테이트에는, 텍스쳐 스테이지에서 사용하는, 각 버텍스의 좌표 세트의 제로 베이스 인덱스를 설정한다 (버텍스 1 개에 대해서 최대 8 조까지의 텍스쳐 좌표를 설정할 수 있다). 버텍스가, 지정된 인덱스의 텍스쳐 좌표 세트를 포함하지 않은 경우는, u 및 v 좌표 (0,0)가 디폴트로 사용된다.

또, 어플리케이션에서는, (설정되는 인덱스와의논리합으로서) 이하의 플래그의 어느쪽이든을 설정해, 텍스쳐 트랜스 폼용의 입력 텍스쳐 좌표를 자동적으로 생성하도록(듯이) Direct3D 에 요구할 수 있다. 제로 로 분해하는 D3DTSS_TCI_PASSTHRU 를 제외해, 설정되는 인덱스와 이하의 플래그의 어느쪽이든을 사용 하면, 텍스쳐 랩핑 모드의 결정에 인덱스가 엄밀하게 사용된다. 이 플래그는 환경 맵핑을 실시하는 경우에는 특히 유효하다.

D3DTSS_TCI_PASSTHRU
버텍스 포맷내의 지정된 텍스쳐 좌표를 사용한다. 이 값은 제로 로 분해한다.
D3DTSS_TCI_CAMERASPACENORMAL
이 스테이지의 텍스쳐 트랜스 폼의 입력 텍스쳐 좌표로서 카메라 공간에 트랜스 폼 된 버텍스 법선을 사용한다.
D3DTSS_TCI_CAMERASPACEPOSITION
이 스테이지의 텍스쳐 트랜스 폼의 입력 텍스쳐 좌표로서 카메라 공간에 트랜스 폼 된 버텍스 위치 좌표를 사용한다.
D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR
이 스테이지의 텍스쳐 트랜스 폼의 입력 텍스쳐 좌표로서 카메라 공간에 트랜스 폼 된 반사 벡터를 사용한다. 반사 벡터는 입력 버텍스 위치 좌표와 법선 벡터로부터 계산된다.
D3DTSS_ADDRESS
D3DTEXTUREADDRESS 열거형의 멤버. u 좌표와 v 좌표의 양쪽 모두로 사용하는 텍스쳐 애드레싱 방법을 선택한다. 디폴트값은 D3DTADDRESS_WRAP 이다.
D3DTSS_ADDRESSU
D3DTEXTUREADDRESS 열거형의 멤버. u 좌표로 사용하는 텍스쳐 애드레싱 방법을 선택한다. 디폴트값은 D3DTADDRESS_WRAP 이다.
D3DTSS_ADDRESSV
D3DTEXTUREADDRESS 열거형의 멤버. v 좌표로 사용하는 텍스쳐 애드레싱 방법을 선택한다. 디폴트값은 D3DTADDRESS_WRAP 이다.
D3DTSS_BORDERCOLOR
[0.0, 1.0] 의 범위의 밖에 있는 텍스쳐 좌표의 라스터화를 실행할 경우에 사용하는 색을 기술하는 D3DCOLOR 값. 디폴트색은 0x00000000 이다.
D3DTSS_MAGFILTER
텍스쳐를 원시적으로 렌더링 할 경우에 사용하는 텍스쳐 확대 필터를 나타내는 D3DTEXTUREMAGFILTER 열거형의 멤버. 디폴트값은 D3DTFG_POINT 이다.
D3DTSS_MINFILTER
D3DTEXTUREMINFILTER 열거형의 멤버로, 텍스쳐를 프리미티브상에 렌더링 할 경우에 사용하는 텍스쳐 확대 필터를 나타낸다. 디폴트값은 D3DTFN_POINT 이다.
D3DTSS_MIPFILTER
텍스쳐를 원시적으로 렌더링 할 경우에 사용하는 텍스쳐 확대 필터를 나타내는 D3DTEXTUREMIPFILTER 열거형의 멤버. 디폴트값은 D3DTFP_NONE 이다.
D3DTSS_MIPMAPLODBIAS
밉맵 상세 바이어스의 레벨. 이것을 이용 하면, 텍스쳐에 질량감을 주거나 희미해진 느낌을 줄 수가 있다. 디폴트는 0. 이 스테이지의 값은 부동 소수점값이다. IDirect3DDevice7::SetTextureStageState 및 IDirect3DDevice7::GetTextureStageState 는 DWORD 값을 사용하기 위해(때문에), 이하의 코드예로 가리키도록(듯이), 값을 저장 한 변수를 캐스트 해야 한다.
lpd3dDevice->SetTextureStageState( D3DTSS_MIPMAPLODBIAS, *((LPDWORD) (&fBias)) );
D3DTSS_MAXMIPLEVEL
어플리케이션으로 허용 하는 최대 밉맵 상세 레벨 밉맵 체인의 선두를 시점으로 하는 인덱스로서 표현된다 (낮은 값이, 밉맵 체인내의 비싼 상세 레벨을 나타낸다). 제로가 디폴트값으로, 전레벨이 사용 가능한 것을 나타낸다. 제로 이외의 값은, 지정된 인덱스보다 높은 상세 레벨의 밉맵을 표시하지 않는 것을 나타낸다.
D3DTSS_MAXANISOTROPY
비등방성 레벨의 최대치. 디폴트값은 1 이다.
D3DTSS_BUMPENVLSCALE
범프 맵 휘도(Luminance)에 사용하는 D3DVALUE 스케일. 디폴트값은 0 이다.
D3DTSS_BUMPENVLOFFSET
범프 맵 휘도(Luminance)의 D3DVALUE 오프셋(offset). 디폴트값은 0 이다.
D3DTSS_TEXTURETRANSFORMFLAGS
텍스쳐 스테이지의 텍스쳐 좌표의 트랜스 폼을 제어하는 D3DTEXTURETRANSFORMFLAGS 열거형의 멤버. 디폴트는 D3DTTFF_DISABLE 이다.
D3DTSS_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

D3DTSS_BUMPENVMAT00, D3DTSS_BUMPENVMAT01, D3DTSS_BUMPENVMAT10, 및 D3DTSS_BUMPENVMAT11 범프 맵핑 행렬 계수의 유효 범위는,-8. 0 이상 8.0 미만이다. 이 범위는, 수학적으로는 [-8. 0,8.0)과 표기한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 6.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


D3DTEXTURETRANSFORMFLAGS

D3DTEXTURETRANSFORMFLAGS 열거형은,D3DTSS_TEXTURETRANSFORMFLAGS 텍스쳐 스테이지 스테이트에서 사용되는 값을 정의한다.

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 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 :DirectX 7.0 이 필요.
헤더 : d3dtypes.h 로 선언.

참조

D3DTSS_TEXTURETRANSFORMFLAGS ,텍스쳐 좌표 트랜스 폼


D3DTRANSFORMSTATETYPE

D3DTRANSFORMSTATETYPE 열거형은,IDirect3DDevice7::GetTransform 및 IDirect3DDevice7::SetTransform 메소드로 사용되는 트랜스 폼 스테이트값을 기술한다.

typedef enum _D3DTRANSFORMSTATETYPE {
    D3DTRANSFORMSTATE_WORLD        = 1,
    D3DTRANSFORMSTATE_VIEW         = 2,
    D3DTRANSFORMSTATE_PROJECTION   = 3,
    D3DTRANSFORMSTATE_WORLD1       = 4,
    D3DTRANSFORMSTATE_WORLD2       = 5,
    D3DTRANSFORMSTATE_WORLD3       = 6,
    D3DTRANSFORMSTATE_TEXTURE0     = 16,
    D3DTRANSFORMSTATE_TEXTURE1     = 17,
    D3DTRANSFORMSTATE_TEXTURE2     = 18,
    D3DTRANSFORMSTATE_TEXTURE3     = 19,
    D3DTRANSFORMSTATE_TEXTURE4     = 20,
    D3DTRANSFORMSTATE_TEXTURE5     = 21,
    D3DTRANSFORMSTATE_TEXTURE6     = 22,
    D3DTRANSFORMSTATE_TEXTURE7     = 23,
    D3DTRANSFORMSTATE_FORCE_DWORD  = 0x7fffffff,
} D3DTRANSFORMSTATETYPE;
D3DTRANSFORMSTATE_WORLD
월드 트랜스 폼 행렬로서 설정되는 트랜스 폼 행렬을 식별한다. 디폴트값은 NULL 이다 (단위행렬).
D3DTRANSFORMSTATE_WORLD1
버텍스 포맷으로 지정된 대응하는 행렬 및 블렌딩 (베타) 가중값을 이용하는 버텍스 블렌딩에 사용된다, 이후의 트랜스 폼 행렬을 식별한다.
D3DTRANSFORMSTATE_WORLD2
버텍스 포맷으로 지정된 대응하는 행렬 및 블렌딩 (베타) 가중값을 이용하는 버텍스 블렌딩에 사용된다, 이후의 트랜스 폼 행렬을 식별한다.
D3DTRANSFORMSTATE_WORLD3
버텍스 포맷으로 지정된 대응하는 행렬 및 블렌딩 (베타) 가중값을 이용하는 버텍스 블렌딩에 사용된다, 이후의 트랜스 폼 행렬을 식별한다.
D3DTRANSFORMSTATE_VIEW
뷰 트랜스 폼 행렬로서 설정되는 트랜스 폼 행렬을 식별한다. 디폴트값은 NULL 이다 (단위행렬).
D3DTRANSFORMSTATE_PROJECTION
투영 트랜스 폼 행렬로서 설정되는 트랜스 폼 행렬을 식별한다. 디폴트값은 NULL 이다 (단위행렬).
D3DTRANSFORMSTATE_TEXTURE0 through D3DTRANSFORMSTATE_TEXTURE7
지정된 텍스쳐 스테이지로 설정되는 트랜스 폼 행렬을 식별한다.
D3DTRANSFORMSTATE_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

IDirect3DDevice7::GetTransform ,IDirect3DDevice7::SetTransform


D3DVERTEXBLENDFLAGS

D3DVERTEXBLENDFLAGS 열거형은, 복수의 행렬에 의한 버텍스 블렌딩 시에 적용되는 수치 또는 행렬을 제어하기 위한 플래그를 정의한다. 이 형태의 멤버는,D3DRENDERSTATE_VERTEXBLEND 렌더링 스테이트에서 사용된다.

typedef enum _D3DVERTEXBLENDFLAGS {
    D3DVBLEND_DISABLE  = 0,
    D3DVBLEND_1WEIGHT  = 1,
    D3DVBLEND_2WEIGHTS = 2,
    D3DVBLEND_3WEIGHTS = 3,
} D3DVERTEXBLENDFLAGS;

멤버

D3DVBLEND_DISABLE
버텍스 블렌딩을 무효로 한다. D3DTRANSFORMSTATE_WORLD 트랜스 폼 스테이트에 의해 지정되는 월드 배열만 적용한다.
D3DVBLEND_1WEIGHT
D3DTRANSFORMSTATE_WORLD 및 D3DTRANSFORMSTATE_WORLD1 트랜스 폼 스테이트에 의해 설정되는 2 개의 행렬간에서의 버텍스 블렌딩을 유효하게 한다.
D3DVBLEND_2WEIGHTS
D3DTRANSFORMSTATE_WORLD, D3DTRANSFORMSTATE_WORLD1, 및 D3DTRANSFORMSTATE_WORLD2 트랜스 폼 스테이트에 의해 설정되는 3 개의 행렬간에 버텍스 블렌딩을 유효하게 한다.
D3DVBLEND_3WEIGHTS
D3DTRANSFORMSTATE_WORLD, D3DTRANSFORMSTATE_WORLD1, D3DTRANSFORMSTATE_WORLD2, 및 D3DTRANSFORMSTATE_WORLD3 트랜스 폼 스테이트에 의해 설정되는 4 개의 행렬간에 버텍스 블렌딩을 유효하게 한다.

주의

지오메트리 블렌딩 (복수의 행렬에 의한 버텍스 블렌딩)에서는, 각 버텍스의 블렌딩 (베타) 가중값을 가지는 버텍스 포맷을 사용해야 한다.

참조

D3DRENDERSTATETYPE ,D3DTRANSFORMSTATETYPE ,IDirect3DDevice7::SetTransform ,지오메트리 블렌딩


D3DVERTEXTYPE

D3DVERTEXTYPE 열거형은, 종래의 IDirect3DDevice3,IDirect3DDevice2, 및 IDirect3DDevice 인터페이스가 지원 하고 있던 버텍스 타입을 일람 한다. 어플리케이션으로 IDirect3DDevice7 등의 IDirect3DDevice3 보다 새로운 인터페이스를 사용하는 경우,유연한 버텍스 포맷 플래그가 D3DVERTEXTYPE 열거형에 대신해 사용된다.

typedef enum _D3DVERTEXTYPE {
    D3DVT_VERTEX       = 1,
    D3DVT_LVERTEX      = 2,
    D3DVT_TLVERTEX     = 3
    D3DVT_FORCE_DWORD  = 0x7fffffff,
} D3DVERTEXTYPE;
D3DVT_VERTEX
배열내의 버텍스는 모두 D3DVERTEX 형이다. 이것을 설정 하면, 원시적이게는 렌더링 시에 트랜스 폼, 라이팅, 및 클리핑이 적용된다.
D3DVT_LVERTEX
배열내의 버텍스는 모두 D3DLVERTEX 형이다. 이 옵션을 사용했을 경우, 원시적이게는 렌더링 시에 트랜스 폼이 적용된다.
D3DVT_TLVERTEX
배열내의 버텍스는 모두 D3DTLVERTEX 형이다. 라스터화는 이 데이터에게만 적용된다.
D3DVT_FORCE_DWORD
이 열거형을 강제적으로 32 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

버텍스 포맷


D3DZBUFFERTYPE

D3DZBUFFERTYPE 열거형은,D3DRENDERSTATE_ZENABLE 렌더링 스테이트에서 사용하는 깊이 버퍼 형식을 기술한다.

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 비트 사이즈에 컴파일 한다. 이 값은 사용되어 있지 않다.

주의

D3DZB_FALSE 와 D3DZB_TRUE 값은, 이전 D3DRENDERSTATE_ZENABLE 로 사용되고 있던 TRUE, FALSE 매크로와 바꿔 넣고 가능하다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 6.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

IDirect3DDevice7::SetRenderState ,깊이 버퍼


폐지된 열거형

이하의 열거형은 폐지되고 있다. 이러한 열거형의 상세한 것에 대하여는, 구릴리스의 DirectX 의 문서를 참조할것.

  • D3DOPCODE
  • D3DLIGHTSTATETYPE
  • D3DTEXTUREBLEND
  • D3DTEXTUREFILTER


폐지된 렌더링 스테이트

d3dtypes.h 에 선언되는 D3DRENDERSTATETYPE 열거형에는 다수의 렌더링 스테이트가 포함되어 있지만, 그 많게는 DirectX 7.0 릴리스에서는 폐지되고 있다. 이러한 렌더링 스테이트는, DirectX 7.0 인터페이스에서는 지원 되지 않고, 기존의 어플리케이션과의 후방 호환성을 유지하기 위해서 마셔 선언되고 있다. 이러한 렌더링 스테이트를 IDirect3DDevice7 인터페이스로 사용하려고 하면(자) 실패해,DDERR_INVALIDPARAMS 가 돌려주어진다. 종래의 인터페이스로 사용되고 있던 렌더링 스테이트의 사용에 대해서는, 종래의 Direct SDK 로 설명되고 있다.

  • D3DRENDERSTATE_ANISOTROPY
  • D3DRENDERSTATE_BORDERCOLOR
  • D3DRENDERSTATE_FLUSHBATCH
  • D3DRENDERSTATE_MIPMAPLODBIAS
  • D3DRENDERSTATE_MONOENABLE
  • D3DRENDERSTATE_PLANEMASK
  • D3DRENDERSTATE_ROP2
  • D3DRENDERSTATE_STIPPLEENABLE
  • D3DRENDERSTATE_STIPPLEPATTERN00 으로부터 D3DRENDERSTATE_STIPPLEPATTERN31
  • D3DRENDERSTATE_SUBPIXEL
  • D3DRENDERSTATE_SUBPIXELX
  • D3DRENDERSTATE_TEXTUREADDRESS
  • D3DRENDERSTATE_TEXTUREADDRESSU
  • D3DRENDERSTATE_TEXTUREADDRESSV
  • D3DRENDERSTATE_TEXTUREHANDLE
  • D3DRENDERSTATE_TEXTUREMAG
  • D3DRENDERSTATE_TEXTUREMAPBLEND
  • D3DRENDERSTATE_TEXTUREMIN
  • D3DRENDERSTATE_TRANSLUCENTSORTINDEPENDENT
  • D3DRENDERSTATE_WRAPU
  • D3DRENDERSTATE_WRAPV


그 외의 형태

여기에서는, 구조체에서도 열거형도 아닌, 이하의 Direct3D 직접 모드의 형태를 설명한다.

  • D3DCOLOR
  • D3DFIXED
  • D3DVALUE


D3DCOLOR

D3DCOLOR 형은, 기본적인 Direct3D 의 색형이다.

typedef DWORD D3DCOLOR, D3DCOLOR, *LPD3DCOLOR;

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.

참조

D3DRGB ,D3DRGBA


D3DFIXED

D3DFIXED 형은 16:16 고정 소수점값을 표현하기 위해서 사용된다.

typedef LONG D3DFIXED;

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 5.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


D3DVALUE

D3DVALUE 형은, 기본적인 Direct3D 의 분수 데이터형이다.

typedef float D3DVALUE, *LPD3DVALUE;

동작환경

Windows NT/2000 :Windows NT 4.0 SP3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 2.0 이후가 필요.
헤더 : d3dtypes.h 로 선언.


유연한 버텍스 포맷 플래그

Direct3D 직접 모드는 플래그의 값을 사용해, DrawPrimitive 준거의 렌더링으로 사용하는 버텍스 포맷을 표현한다. d3dtypes.h 헤더 파일은, 이하에 나타내도록(듯이), 버텍스 포맷을 명시적으로 기술하는 플래그를 선언한다. 또, 이러한 플래그의 일반적인 조합하고로서의 기능을 가지는 헬퍼-매크로를 제공한다. 상세한 것에 대하여는, 「버텍스 포맷에 대하며」를 참조할것.

유연한 버텍스 포맷 (FVF) 플래그
D3DFVF_DIFFUSE
버텍스 포맷이 디 푸즈색성분을 포함한다.
D3DFVF_NORMAL
버텍스 포맷이 버텍스 법선 벡터를 포함한다. 이 플래그를, D3DFVF_XYZRHW 와 함께 사용할 수 없다.
D3DFVF_SPECULAR
버텍스 포맷이 스펙큐러색성분을 포함한다.
D3DFVF_XYZ
버텍스 포맷이 트랜스폼 되지 않은 버텍스의 위치 좌표를 포함한다. 이 플래그를, D3DFVF_XYZRHW 와 함께 사용할 수 없다. 이 플래그를 사용하는 경우는, 동시에 버텍스 법선과 버텍스색성분 (D3DFVF_DIFFUSE 또는 D3DFVF_SPECULAR)을 지정하는지, 또는 적어도 1 세트의 텍스쳐 좌표 (D3DFVF_TEX1 로부터 D3DFVF_TEX8)를 포함할 필요가 있다.
D3DFVF_XYZRHW
버텍스 포맷이, 트랜스 폼 된 버텍스의 위치 좌표를 포함한다. 이 플래그를 D3DFVF_XYZ 또는 D3DFVF_NORMAL 플래그와 동시에 사용할 수 없다. 이 플래그를 사용하는 경우는, 동시에 버텍스색성분 (D3DFVF_DIFFUSE 또는 D3DFVF_SPECULAR)을 지정하는지, 또는 적어도 1 세트의 텍스쳐 좌표 (D3DFVF_TEX1 로부터 D3DFVF_TEX8)를 포함할 필요가 있다.
D3DFVF_XYZB1 로부터 D3DFVF_XYZB5
버텍스 포맷은, 위치 좌표 데이터, 및 복수의 행렬에 의한 버텍스 블렌딩 처리용의 가중 (베타) 값의 대응수를 포함한다. 현재, Direct3D 에서는 최대 3 개의 가중값 ( 및 4 개의 블렌딩 행렬)으로 블렌딩이 가능하다.
텍스쳐 관련 FVF 플래그
D3DFVF_TEX0 로부터 D3DFVF_TEX8
이 버텍스에 대응하는 텍스쳐 좌표 세트의 번호. 이러한 플래그에 대응하는 숫자는 연속 번호로 되어 있지 않다.
D3DFVF_TEXTUREFORMAT1 로부터 D3DFVF_TEXTUREFORMAT4
텍스쳐 좌표 세트를 정의하는 값의 번호. D3DFVF_TEXTUREFORMAT1 는 1 차원 좌표를 나타내, D3DFVF_TEXTUREFORMAT2 는 2 차원 좌표를 나타내, 라고 하는 순으로 이하 계속된다. 이 플래그가 단독으로 사용되는 것은 보기 드물어,D3DFVF_TEXCOORDSIZEn 매크로와 함께 사용된다.
헬퍼-매크로
D3DFVF_LVERTEX
버텍스 포맷은 D3DLVERTEX 버텍스 타입에 대응한다.
D3DFVF_TLVERTEX
버텍스 포맷은 D3DTLVERTEX 버텍스 타입에 대응한다.
D3DFVF_VERTEX
버텍스 포맷은 D3DVERTEX 버텍스 타입에 대응한다.
마스크값
D3DFVF_POSITION_MASK
위치 좌표 비트를 추출하는 마스크.
D3DFVF_RESERVED0 and D3DFVF_RESERVED2
유연한 버텍스 포맷의 예약 비트를 추출하기 위한 마스크값. 사용 불가.
D3DFVF_RESERVED1,
이 비트는, 시스템이 D3DLVERTEX 처리를 에뮬레이트 하는 것을 나타내기 위해서(때문에) 예약되고 있다. 이 플래그를 사용하는 경우는, D3DFVF_XYZ, D3DFVF_DIFFUSE, D3DFVF_SPECULAR, 및 D3DFVF_TEX1 플래그도 동시에 사용해야 한다. 이것은,D3DFVF_LVERTEX 헬퍼-매크로를 사용하는 것과 실질적으로 같다.
D3DFVF_TEXCOUNT_MASK
텍스쳐 flag bit를 추출하기 위한 마스크값.
그 외
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 );

참조

버텍스 포맷에 대해,지오메트리 블렌딩


텍스쳐 인수 플래그

디바이스에 대응하는 각각의 텍스쳐 스테이지는 2 개의 텍스쳐 인수를 가질 수가 있어 이러한 인수는 텍스쳐의 색과 알파 채널에 영향을 준다. 텍스쳐 인수를 취득 또는 설정하려면 ,IDirect3DDevice7::SetTextureStageState 또는 IDirect3DDevice7::GetTextureStageState 메소드를 호출해,D3DTEXTURESTAGESTATETYPE 열거형의 D3DTSS_COLORARG1, D3DTSS_COLORARG2, D3DTSS_ALPHAARG1, 또는 D3DTSS_ALPHAARG2 멤버를 지정한다.

다음에 나타내는 플래그 (인수와 수정자에게 정리하고 있다)를 텍스쳐 스테이지의 색과 알파 인수와 함께 사용할 수가 있다. 인수 플래그와 수정자를 조합할 수 있지만, 2 개의 인수 플래그를 조합할 수 없다.

인수 플래그
D3DTA_CURRENT
텍스쳐 인수는 전의 블렌딩 스테이지의 결과이다. 최초의 텍스쳐 스테이지 (스테이지 0)의 경우, 이 인수는 D3DTA_DIFFUSE 와 동등하다. 전의 블렌딩 스테이지가 범프 맵 텍스쳐 (D3DTOP_BUMPENVMAP 처리)를 사용하고 있는 경우, 범프 맵 텍스쳐의 전의 스테이지로부터 텍스쳐가 선택된다 (s 가 현재의 텍스쳐 스테이지를 나타내,s – 1 에 범프 맵 텍스쳐가 있는 경우, 이 인수는 텍스쳐 스테이지 s – 2 로부터의 결과 출력이 된다).
D3DTA_DIFFUSE
텍스쳐 인수는, gouraud shading 처리중에 버텍스 성분으로부터 보간 해 얻을 수 있던 디 푸즈색이다. 버텍스가 디 푸즈색을 포함하지 않는 경우의 디폴트색은 0xFFFFFFFF 이다.
D3DTA_SELECTMASK
모든 인수에 대응하는 마스크값. 텍스쳐 인수의 설정에는 사용하지 않는다.
D3DTA_TEXTURE
텍스쳐 인수는, 이 텍스쳐 스테이지의 텍스쳐색이다. 이것이 유효한 것은, 스테이지의 최초의 색과 알파 인수 에 대해서만이다 (D3DTEXTURESTAGESTATETYPE 의 3DTSS_COLORARG1 멤버와 3DTSS_ALPHAARG1 멤버).
D3DTA_TFACTOR
텍스쳐 인수는,D3DRENDERSTATE_TEXTUREFACTOR 렌더링 스테이트를 사용해 전회 IDirect3DDevice7::SetRenderState 을 호출했을 때의 텍스쳐 계수 세트이다.
D3DTA_SPECULAR
텍스쳐 인수는, gouraud shading 처리중에 버텍스 성분으로부터 보간 된 스펙큐러색이다. 버텍스가 스펙큐러색을 포함하지 않은 경우, 디폴트색은 0xFFFFFFFF 이다.
수정자 플래그
D3DTA_ALPHAREPLICATE
조작이 완료하기 전에, 알파 정보를 모든 색채널에 카피한다.
D3DTA_COMPLEMENT
인수의 역수를 취한다. 예를 들어, 인수의 결과가 변수 x 라면, 그 값은 1.0 - x 가 된다.


반환값

에러는, 부의 값으로 나타내지므로, 조합할 수가 없다. 이 표는, 모든 Direct3D 직접 모드 메소드가 돌려줄 수 있는 값을 집계한 것이다. 각 메소드가 돌려주는 값의 일람에 대해서는, 각 메소드에 대한 설명을 참조할것.

D3D_OK
에러는 발생하고 있지 않다.
D3DERR_BADMAJORVERSION
요구한 서비스는 이 주요 버젼의 DirectX 에서는 사용할 수 없다 (주요 버젼과는 DirectX 6.0 등의 주요 릴리스이다).
D3DERR_BADMINORVERSION
요구한 서비스는 이 주요 버젼의 DirectX 로 사용 가능하지만, 이 마이너 버젼에서는 사용할 수 없다. Microsoft 로부터 최신의 컴퍼넌트 런타임을 입수하는 것 (마이너 버젼과는 Direct 6.1 등의 세컨드리 릴리스이다).
D3DERR_COLORKEYATTACHED
어플리케이션이 투과용 컬러 키를 사용하는 표면으로 텍스쳐를 생성 하려고 했다.
D3DERR_CONFLICTINGTEXTUREFILTER
현재의 텍스쳐 필터는 함께 사용할 수 없다.
D3DERR_CONFLICTINGTEXTUREPALETTE
현재의 텍스쳐는 동시에 사용할 수 없다. 일반적으로 멀티 텍스쳐 디바이스에 대해, 동시에 유효하게 된 팔레트화 텍스쳐로 같은 팔레트를 공유할 필요가 있는 경우에 발생한다.
D3DERR_CONFLICTINGRENDERSTATE
현재 설정되어 있는 렌더링 스테이트는 함께 사용할 수 없다.
D3DERR_DEVICEAGGREGATED
IDirect3DDevice7::SetRenderTarget 메소드가, 렌더링 타겟 표면으로부터 취득된 디바이스로 불려 갔다.
D3DERR_EXECUTE_CLIPPED_FAILED
실행중에 실행 버퍼를 클리핑 할 수 없었다.
D3DERR_EXECUTE_CREATE_FAILED
실행 버퍼를 생성 할 수 없었다. 일반적으로 실행 버퍼에 할당하는 메모리가 부족한 경우에 발생한다.
D3DERR_EXECUTE_DESTROY_FAILED
실행 버퍼용의 메모리의 할당을 해제할 수 없었다.
D3DERR_EXECUTE_FAILED
실행 버퍼의 내용이 무효이기 (위해)때문에 실행할 수 없다.
D3DERR_EXECUTE_LOCK_FAILED
실행 버퍼를 잠글 수 없었다.
D3DERR_EXECUTE_LOCKED
실행 버퍼가 락 되고 있기 (위해)때문에, 어플리케이션으로부터 요구한 처리를 완료할 수 없었다.
D3DERR_EXECUTE_NOT_LOCKED
실행 버퍼는 현재 락되어 있지 않기 때문에, 실행 버퍼를 락 해제할 수 없었다.
D3DERR_EXECUTE_UNLOCK_FAILED
실행 버퍼를 락 해제할 수 없었다.
D3DERR_INBEGIN
장면의 렌더링중이기 (위해)때문에, 요구된 처리를 실행할 수 없다. 장면이 완료하고 나서 IDirect3DDevice7::EndScene 메소드를 호출한 후, 재차 시험해 본다.
D3DERR_INBEGINSTATEBLOCK
스테이트 블록의 기록중이기 (위해)때문에, 처리를 실행할 수 없다. IDirect3DDevice7::EndStateBlock 메소드를 호출해 레코딩을 완료한 후, 재차 시험해 본다.
D3DERR_INITFAILED
새로운 디바이스를 초기화할 수 없었기 (위해)때문에, 렌더링 디바이스를 생성 할 수 없었다.
D3DERR_INVALID_DEVICE
요구된 디바이스의 종류가 유효하지 않다.
D3DERR_INVALIDCURRENTVIEWPORT
현재 선택되고 있는 뷰포트가 유효하지 않다.
D3DERR_INVALIDMATRIX
현재 설정되어 있는 월드 행렬, 뷰 행렬, 또는 투영 행렬의 편성이 무효이기 (위해)때문에 (행렬을 조합한 결과, 행렬식이 0 이 된다), 요구된 처리를 실행할 수 없었다.
D3DERR_INVALIDPALETTE
표면에 관련지을 수 있고 있는 팔레트가 무효이다.
D3DERR_INVALIDPRIMITIVETYPE
어플리케이션으로 지정한 프리미티브의 종류가 무효이다.
D3DERR_INVALIDRAMPTEXTURE
램프 모드가 사용되어 현재의 머트리얼의 텍스쳐 핸들은, 렌더링 스테이트로서 설정된 현재의 텍스쳐 핸들에 적합하지 않는다.
D3DERR_INVALIDSTATEBLOCK
스테이트 블록 핸들이 무효이다.
D3DERR_INVALIDVERTEXFORMAT
어플리케이션으로 지정한유연한 버텍스 포맷 플래그의 편성이 유효하지 않다.
D3DERR_INVALIDVERTEXTYPE
어플리케이션으로 지정한 버텍스의 종류가 무효이다.
D3DERR_LIGHT_SET_FAILED
라이팅오브제크에의 라이팅 파라미터의 설정이 실패했다.
D3DERR_LIGHTHASVIEWPORT
라이팅 오브젝트가 다른 뷰포트에 관련지을 수 있고 있기 (위해)때문에, 요구된 처리가 실패했다.
D3DERR_LIGHTNOTINTHISVIEWPORT
라이팅 오브젝트가 이 뷰포트에 관련지을 수 있지 않기 때문에, 요구된 처리가 실패했다.
D3DERR_MATERIAL_CREATE_FAILED
머트리얼을 생성 할 수 없었다. 일반적으로 머트리얼에 할당하는 메모리가 부족한 경우에 발생한다.
D3DERR_MATERIAL_DESTROY_FAILED
머트리얼용의 메모리의 할당을 해제할 수 없었다.
D3DERR_MATERIAL_GETDATA_FAILED
머트리얼 파라미터를 취득할 수 없었다.
D3DERR_MATERIAL_SETDATA_FAILED
머트리얼 파라미터를 설정할 수 없었다.
D3DERR_MATRIX_CREATE_FAILED
행렬을 생성 할 수 없었다. 행렬에 할당하는 메모리가 부족한 경우에 발생한다.
D3DERR_MATRIX_DESTROY_FAILED
행렬용의 메모리의 할당을 해제할 수 없었다.
D3DERR_MATRIX_GETDATA_FAILED
행렬 데이터를 취득할 수 없었다. 행렬이 현재의 디바이스로 생성되어 있지 않은 경우에 발생한다.
D3DERR_MATRIX_SETDATA_FAILED
행렬 데이터를 설정할 수 없었다. 행렬이 현재의 디바이스로 생성되어 있지 않은 경우에 발생한다.
D3DERR_NOCURRENTVIEWPORT
뷰포트 파라미터가 설정되어 있지 않기 때문에 취득할 수 없었다.
D3DERR_NOTINBEGIN
장면의 렌더링이 시작 하고 있지 않기 때문에, 요구된 렌더링 처리를 완료할 수 없었다. IDirect3DDevice7::BeginScene 을 호출해 렌더링을 시작 해, 재차 시험해 본다.
D3DERR_NOTINBEGINSTATEBLOCK
요구된 처리는 스테이트 블록의 기록중에게만 유효하기 때문에, 그 처리를 완료할 수 없었다. IDirect3DDevice7::BeginStateBlock 메소드를 호출해 재차 시험해 본다.
D3DERR_NOVIEWPORTS
현재 디바이스에는 뷰포트를 관련지을 수 있지 않기 때문에, 요구된 처리가 실패했다.
D3DERR_SCENE_BEGIN_FAILED
장면의 렌더링이 시작 할 수 없었다.
D3DERR_SCENE_END_FAILED
장면의 렌더링을 완료할 수 없었다.
D3DERR_SCENE_IN_SCENE
IDirect3DDevice7::EndScene 메소드의 호출에 의해 전회의 장면이 완료하고 있지 않기 때문에, 장면의 렌더링이 시작 할 수 없었다.
D3DERR_SCENE_NOT_IN_SCENE
전의 IDirect3DDevice7::BeginScene 메소드의 호출에 의해 장면이 시작 하고 있지 않기 때문에, 장면의 렌더링을 완료할 수 없었다.
D3DERR_SETVIEWPORTDATA_FAILED
뷰포트 파라미터를 설정할 수 없었다.
D3DERR_STENCILBUFFER_NOTPRESENT
렌더링 타겟 표면에 스텐실 버퍼가 Attach 하고 있지 않기 때문에, 요구된 스텐실 버퍼 처리를 완료할 수 없었다.
D3DERR_SURFACENOTINVIDMEM
렌더링 타겟 표면이 비디오 메모리내에 발견되지 않기 때문에, 디바이스를 생성 할 수 없었다 (하드웨어 가속화 디바이스에는, 비디오 메모리내의 렌더링 타겟 표면이 필요하다).
D3DERR_TEXTURE_BADSIZE
현재의 텍스쳐의 크기가 무효이다. 2 의 거듭제곱의 크기를 가지는 텍스쳐가 필요한 디바이스로, 그 이외의 크기의 텍스쳐를 사용하려고 했을 경우에 발생한다.
D3DERR_TEXTURE_CREATE_FAILED
드라이버로부터 텍스쳐의 텍스쳐 핸들을 취득할 수 없었다.
D3DERR_TEXTURE_DESTROY_FAILED
디바이스가 텍스쳐 메모리의 할당을 해제할 수 없었다.
D3DERR_TEXTURE_GETSURF_FAILED
텍스쳐 생성에 사용하는 DirectDraw 표면을 취득할 수 없었다.
D3DERR_TEXTURE_LOAD_FAILED
텍스쳐를 로드할 수 없었다.
D3DERR_TEXTURE_LOCK_FAILED
텍스쳐를 잠글 수 없었다.
D3DERR_TEXTURE_LOCKED
텍스쳐 표면이 현재 락 되고 있기 (위해)때문에, 요구된 처리를 완료할 수 없었다.
D3DERR_TEXTURE_NO_SUPPORT
디바이스가 텍스쳐 맵핑을 지원 하고 있지 않다.
D3DERR_TEXTURE_NOT_LOCKED
텍스쳐 표면이 락되어 있지 않기 때문에, 요구된 처리를 완료할 수 없었다.
D3DERR_TEXTURE_SWAP_FAILED
텍스쳐 핸들을 스왑 할 수 없었다.
D3DERR_TEXTURE_UNLOCK_FAILED
텍스쳐 표면을 락 해제할 수 없었다.
D3DERR_TOOMANYOPERATIONS
어플리케이션으로, 디바이스 지원 이상의 텍스쳐 필터링 처리를 요구하고 있다.
D3DERR_TOOMANYPRIMITIVES
디바이스는, 1 회만의 수수에서는 지정된 개수의 프리미티브를 렌더링 할 수 없다.
D3DERR_UNSUPPORTEDALPHAARG
알파 채널로 지정된 텍스쳐 블렌딩 인수 가운데, 디바이스로 지원 하고 있지 않는 인수가 있다.
D3DERR_UNSUPPORTEDALPHAOPERATION
알파 채널로 지정된 텍스쳐 블렌딩 처리 가운데, 디바이스로 지원 하고 있지 않는 처리가 있다.
D3DERR_UNSUPPORTEDCOLORARG
컬러값으로 지정된 텍스쳐 블렌딩 인수 가운데, 디바이스로 지원 하고 있지 않는 인수가 있다.
D3DERR_UNSUPPORTEDCOLOROPERATION
컬러값으로 지정된 텍스쳐 블렌딩 처리 가운데, 디바이스로 지원 하고 있지 않는 처리가 있다.
D3DERR_UNSUPPORTEDFACTORVALUE
지정된 텍스쳐 계수값이 디바이스로 지원되어 있지 않다.
D3DERR_UNSUPPORTEDTEXTUREFILTER
지정된 텍스쳐 필터가 디바이스로 지원되어 있지 않다.
D3DERR_VBUF_CREATE_FAILED
버텍스 버퍼를 생성 할 수 없었다. 버텍스 버퍼를 할당하는데 충분한 메모리가 없는 경우에 발생한다.
D3DERR_VERTEXBUFFERLOCKED
버텍스 버퍼가 락 되고 있기 (위해)때문에, 요구된 처리를 완료할 수 없었다.
D3DERR_VERTEXBUFFEROPTIMIZED
버텍스 버퍼가 최적화되고 있기 (위해)때문에, 요구된 처리를 완료할 수 없었다 (최적화된 버텍스 버퍼의 내용은, 드라이버 고유해 Private라고 보여진다).
D3DERR_VERTEXBUFFERUNLOCKFAILED
버텍스 버퍼 메모리가 오버런 했기 때문에, 버텍스 버퍼를 락 해제할 수 없었다. 어플리케이션으로 버텍스 버퍼의 사이즈 이상의 쓰기를 실행하지 않게 주의 해야 한다.
D3DERR_VIEWPORTDATANOTSET
뷰포트 파라미터가 미설정이기 (위해)때문에, 요구된 처리를 완료할 수 없었다. IDirect3DDevice7::SetViewport 메소드를 호출해 뷰포트 파라미터를 설정해, 재차 시험해 본다.
D3DERR_VIEWPORTHASNODEVICE
이 값은 IDirect3DDevice3 및 그 이전의 인터페이스에서만 사용된다. IDirect3DDevice7 인터페이스에서는, 이 에러값은 사용되지 않는다.

뷰포트를 디바이스에 관련지을 수 있지 않기 때문에, 요구된 처리를 완료할 수 없었다. IDirect3DDevice3::AddViewport 메소드를 호출해 뷰포트를 렌더링 디바이스에 관련지어, 재차 시험해 본다.

D3DERR_WRONGTEXTUREFORMAT
텍스쳐 표면의 픽셀 포맷이 유효하지 않다.
D3DERR_ZBUFF_NEEDS_SYSTEMMEMORY
지정된 디바이스에서는 시스템 메모리의 깊이 버퍼 표면이 필요하기 때문에, 요구된 처리를 완료할 수 없었다 (소프트웨어 렌더링 디바이스에서는, 시스템 메모리의 깊이 버퍼가 필요하다).
D3DERR_ZBUFF_NEEDS_VIDEOMEMORY
지정된 디바이스에서는 비디오 메모리의 깊이 버퍼 표면이 필요하기 때문에, 요구된 처리를 완료할 수 없었다 (하드웨어 가속화 디바이스에서는, 비디오 메모리의 깊이 버퍼가 필요하다).
D3DERR_ZBUFFER_NOTPRESENT
렌더링 타겟 표면에 Attach 된 깊이 버퍼가 없기 때문에, 요구된 처리를 완료할 수 없었다.


Direct3D 직접 모드 Visual Basic 레퍼런스

여기에서는, Direct3D® 직접 모드가 제공하는 API 요소의 레퍼런스 정보를 기술한다. 레퍼런스 정보는 이하의 카테고리로 분류된다.

  • 클래스
  • 형
  • 열거
  • 유연한 버텍스 포맷 플래그
  • 텍스쳐 인수 플래그
  • 에러 코드


클래스

여기에서는, Direct3D 직접 모드가 제공하는 클래스의 레퍼런스를 기술한다. 이하의 클래스에 도착해 설명한다.

  • Direct3D7
  • Direct3DDevice7
  • Direct3DEnumDevices
  • Direct3DEnumPixelFormats
  • Direct3DVertexBuffer7


Direct3D7

어플리케이션은,Direct3D7 클래스의 메소드를 사용해, Direct3D 오브젝트를 생성 해, 오브젝트의 환경을 셋업 한다. 또,Direct3D7 클래스를 사용해, 버텍스 버퍼를 생성 하거나 텍스쳐 맵이나 깊이 버퍼 포맷을 열거할 수가 있다. 여기에서는, Direct3D7 클래스의 메소드의 레퍼런스를 제공한다.

Direct3D7 클래스는,DirectDraw7 오브젝트로부터 GetDirect3D 메소드를 호출하는 것으로 취득된다.

Direct3D7 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

생성 | CreateDevice
 | CreateVertexBuffer
열거 | GetDevicesEnum
 | GetEnumZBufferFormats
그 외 | EvictManagedTextures
 | GetDirectDraw

참조

Direct3D 에의 액세스,Direct3D 와 DirectDraw


Direct3D7.CreateDevice

Direct3D7.CreateDevice 메소드는, DrawPrimitive 메소드로 사용하기 위해서, Direct3D 디바이스를 생성한다.

object. CreateDevice( _
    guid As String, _
    surf As DirectDrawSurface7) As Direct3DDevice7

파라미터

object
Direct3D7 오브젝트를 나타내는오브젝트식.
guid
신규 디바이스의 GUID. 이 값은, 열거된 GUID 캐릭터 라인,"IID_Direct3DHALDevice" 또는 "IID_Direct3DRGBDevice" 캐릭터 라인 정수로 할 수 있다. 이 메소드는, 테스트 또는 기능 데먼스트레이션용의 기준 디바이스를 생성 하는 "IID_Direct3DRefDevice" 도 받는다.
surf
디바이스의 렌더링 타겟이 되는 DirectDrawSurface 오브젝트용의 DirectDrawSurface7 오브젝트. DDSCAPS_3DDEVICE 능력을 이용해 표면은 3D 디바이스로서 생성되었다.

반환값

메소드가 성공하면(자),Direct3DDevice7 오브젝트에의 참조를 돌려준다.

에러 코드

메소드가 실패 하면 에러가 발생해, 파라미터중 한쪽이 무효의 경우는,Err.Number 에 DDERR_INVALIDPARAMS 가 설정된다.

주의

지정된 Direct3D7 오브젝트에 의해 생성 된 렌더링 디바이스는 모두, 같은 물리 리소스를 공유한다. 복수의 렌더링 디바이스로 같은 하드웨어를 공유하므로, 단일의 Direct3D7 오브젝트로부터 복수의 렌더링 디바이스를 생성 할 수 있지만, 퍼포먼스가 큰폭으로 저하한다.

Direct3D7.CreateDevice 를 호출하면, DirectDraw 표면 오브젝트와는 별개의 디바이스 오브젝트를 생성 할 수 있다. 이 디바이스는, DirectDraw 표면을 렌더링 타겟으로서 사용한다.

참조

Direct3DDevice7 ,Direct3D 디바이스의 생성,Direct3D 디바이스


Direct3D7.CreateVertexBuffer

Direct3D7.CreateVertexBuffer 메소드는, 버텍스 버퍼 오브젝트를 생성 한다.

object. CreateVertexBuffer( _
    desc As D3DVERTEXBUFFERDESC, _
    flags As CONST_D3DDPFLAGS) As Direct3DVertexBuffer7

파라미터

object
Direct3D7 오브젝트를 나타내는오브젝트식.
desc
버텍스 버퍼가 포함한 버텍스의 포맷과 수를 기술하는 D3DVERTEXBUFFERDESC 형.
flags
CONST_D3DDPFLAGS 열거의 정수의 1 개 (클리핑값을 나타내는유연한 버텍스 포맷 플래그). 이 파라미터값을 0 으로 설정해 트랜스폼 되지 않은 버텍스 또는 트랜스 폼제버텍스의 클리핑 정보를 포함할 수 있는 버텍스 버퍼를 생성 하거나 D3DDP_DONOTCLIP 플래그를 사용해 트랜스 폼제버텍스를 포함하지만 클리핑 정보는 저장 하지 않는 버텍스 버퍼를 생성 한다.

반환값

메소드가 성공하면(자),Direct3DVertexBuffer7 오브젝트에의 참조를 돌려준다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

D3DERR_INVALIDVERTEXFORMAT
D3DERR_VBUF_CREATE_FAILED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

참조

Direct3DVertexBuffer7 ,버텍스 버퍼


Direct3D7.EvictManagedTextures

Direct3D7.EvictManagedTextures 메소드는, 관리하의 모든 텍스쳐를 로컬 혹은 비로컬 비디오 메모리로부터 삭제한다.

object. EvictManagedTextures()

파라미터

object
Direct3D7 오브젝트를 나타내는오브젝트식.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 가 설정된다.

주의

이 메소드에 의해, Direct3D 는, DDSCAPS2_TEXTUREMANAGE 또는 DDSCAPS2_D3DTEXTUREMANAGE 플래그와 함께 생성 된 임의의 텍스쳐 표면을, 로컬 혹은 비로컬 비디오 메모리로부터 삭제한다.

참조

자동 텍스쳐 관리


Direct3D7.GetDevicesEnum

Direct3D7.GetDevicesEnum 메소드는,Direct3DEnumDevices 오브젝트를 생성 한다.

object. GetDevicesEnum() As Direct3DEnumDevices

파라미터

object
Direct3D7 오브젝트를 나타내는오브젝트식.

반환값

메소드가 성공하면(자),Direct3DEnumDevices 오브젝트를 돌려준다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


Direct3D7.GetDirectDraw

Direct3D7.GetDirectDraw 메소드는, Direct3D 오브젝트에 관련지을 수 있었던 DirectDraw7 오브젝트를 취득한다.

object. GetDirectDraw() As DirectDraw7

파라미터

object
Direct3D7 오브젝트를 나타내는오브젝트식.

반환값

메소드가 성공하면(자),DirectDraw7 오브젝트에의 참조를 돌려준다.

Error Codes

메소드가 실패한 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DDERR_INVALIDOBJECT
DDERR_OUTOFMEMORY

트래핑 에러에 대해서는, 「Visual Basic 에러 트래핑」을 참조할것.


Direct3D7.GetEnumZBufferFormats

Direct3D7.GetEnumZBufferFormats 메소드는,Direct3DEnumPixelFormats 오브젝트를 생성 한다.

object. GetEnumZBufferFormats( _
    guid As String) As Direct3DEnumPixelFormats

파라미터

object
Direct3D7 오브젝트를 나타내는오브젝트식.
guid
그 깊이 버퍼 포맷이 열거되는 디바이스의 글로벌 유니크 식별자.

반환값

메소드가 성공하면(자),Direct3DEnumPixelFormats 오브젝트에의 참조를 돌려준다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY

트래핑 에러에 대해서는, 「Visual Basic 에러 트래핑」을 참조할것.


Direct3DDevice7

Direct3DDevice7 클래스는, 어플리케이션이 DrawPrimitive 에 의한 렌더링을 실행하기 위한 메소드를 제공한다. 디바이스를 생성 하려면 ,Direct3D7.CreateDevice 메소드를 호출한다.

개요에 대해서는, 「Direct3D 디바이스」 및 「DrawPrimitive 메소드」를 참조할것.

Direct3DDevice7 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

정보 | GetCaps
 | GetDirect3D
 | GetInfo
 | GetDeviceGuid
디바이스 스테이트 | ApplyStateBlock
 | BeginStateBlock
 | CaptureStateBlock
 | CreateStateBlock
 | DeleteStateBlock
 | EndStateBlock
 | GetClipStatus
 | GetRenderState
 | GetRenderStateSingle
 | GetRenderTarget
 | GetTransform
 | SetClipStatus
 | SetRenderState
 | SetRenderStateSingle
 | SetRenderTarget
 | SetTransform
라이팅과 머트리얼 | GetMaterial
 | GetLight
 | GetLightEnable
 | LightEnable
 | SetMaterial
 | SetLight
그 외 | ComputeSphereVisibility
 | MultiplyTransform
렌더링 | DrawIndexedPrimitive
 | DrawIndexedPrimitiveVB
 | DrawPrimitive
 | DrawPrimitiveVB
장면 | BeginScene
 | EndScene
텍스쳐 | GetTexture
 | GetTextureFormatsEnum
 | GetTextureStageState
 | GetTextureStageStateSingle
 | Load
 | PreLoad
 | SetTexture
 | SetTextureStageState
 | SetTextureStageStateSingle
 | ValidateDevice
유저 정의 클립면 | GetClipPlane
 | SetClipPlane
뷰포트 | Clear
 | GetViewport
 | SetViewport

이 클래스에는, 유연한 버텍스 포맷, 버텍스 버퍼, 및 가시성 계산을 지원 하는 메소드도 포함된다.

참조

Direct3D 디바이스,렌더링


Direct3DDevice7.ApplyStateBlock

Direct3DDevice7.ApplyStateBlock 메소드는, 기존의 디바이스 스테이트 블록을 렌더링 디바이스에 적용한다.

object. ApplyStateBlock( _
    blockHandle As Long)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
blockHandle
적용되는 디바이스 스테이트 블록의 핸들. Direct3DDevice7.EndStateBlock 메소드에 의해 돌려주어진다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 DDERR_INVALIDPARAMS 가 설정되어blockHandle 파라미터가 무효인지, 매크로의 기록중인지를 나타낸다.

주의

어플리케이션이 다른 블록을 기록하고 있는 동안은, 디바이스 스테이트 블록을 적용할 수 없다.

이 메소드는 Direct3DDevice7 인터페이스와 함께 도입되었다.

렌더링 디바이스의 스테이트에 영향을 주는 모든 처리 같이, 장면의 렌더링시, 즉 Direct3DDevice7.BeginScene 메소드를 호출하고 나서 Direct3DDevice7.EndScene 메소드를 호출하기 전에, 스테이트 블록을 적용하는 것을 권한다.

참조

Direct3DDevice7.BeginStateBlock ,Direct3DDevice7.CaptureStateBlock ,Direct3DDevice7.CreateStateBlock ,Direct3DDevice7.DeleteStateBlock ,Direct3DDevice7.EndStateBlock ,스테이트 블록


Direct3DDevice7.BeginScene

Direct3DDevice7.BeginScene 메소드는 장면을 시작 한다. 어플리케이션은, 렌더링을 실행하기 전에 이 메소드를 호출하지 않으면 안 된다. 또, 렌더링이 완료해, 재차 Direct3DDevice7.BeginScene 를 호출하기 전에는,Direct3DDevice7.EndScene 를 호출하지 않으면 안 된다.

object. BeginScene()

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 가 설정된다.

주의

BeginScene 메소드가 실패 하면, 디바이스는 장면을 시작 할 수 없기 때문에,Direct3DDevice7.EndScene 메소드를 호출할 필요는 없다. BeginScene 가 실패했을 경우는, 그 후에 Direct3DDevice7.EndScene 메소드를 호출하면 실패한다.

참조

Direct3DDevice7.EndScene


Direct3DDevice7.BeginStateBlock

Direct3DDevice7.BeginStateBlock 메소드는, Direct3D 에 디바이스 스테이트 블록의 기록을 시작 하도록 지시한다.

object. BeginStateBlock()

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

주의

어플리케이션은, 이 메소드를 호출하기 전에,Direct3DDevice7.ValidateDevice 메소드를 호출해, 기록된 모든 스테이트가 유효한가 어떤가를 확인할 수가 있다.

스테이트 블록 (Direct3DDevice7.BeginStateBlock 를 호출하고 나서 Direct3DDevice7.EndStateBlock 를 호출할 때까지 )에는, 다음의 메소드를 기록할 수 있다.

  • Direct3DDevice7.LightEnable
  • Direct3DDevice7.SetClipPlane
  • Direct3DDevice7.SetLight
  • Direct3DDevice7.SetMaterial
  • Direct3DDevice7.SetRenderState
  • Direct3DDevice7.SetTexture
  • Direct3DDevice7.SetTextureStageState
  • Direct3DDevice7.SetTransform
  • Direct3DDevice7.SetViewport

스테이트 블록에서의 스테이트 변화의 순서는 보증되지 않는다. 스테이트 세트로 같은 스테이트를 몇번이나 지정했을 경우, 마지막 값이 사용된다.

참조

Direct3DDevice7.EndStateBlock ,Direct3DDevice7.CaptureStateBlock ,Direct3DDevice7.CreateStateBlock ,Direct3DDevice7.DeleteStateBlock ,Direct3DDevice7.ApplyStateBlock ,스테이트 블록


Direct3DDevice7.CaptureStateBlock

Direct3DDevice7.CaptureStateBlock 메소드는, 기존의 스테이트 블록의 값을, 현재 그 디바이스로 설정되어 있는 값에 갱신한다.

object. CaptureStateBlock( _
    blockHandle As Long)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
blockHandle
현재의 디바이스 스테이트를 캡춰 하는 스테이트 블록의 핸들.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

D3DERR_INBEGINSTATEBLOCK
D3DERR_INOVERLAYSTATEBLOCK

주의

이 메소드는, 기존의 스테이트 블록에, 갱신된 스테이트의 값을 캡춰 한다. 디바이스의 스테이트 전체를 캡춰 하는 것은 아니다. 상세한 것에 대하여는, 「스테이트 블록의 취득」을 참조할것.

참조

Direct3DDevice7.ApplyStateBlock ,Direct3DDevice7.BeginStateBlock ,Direct3DDevice7.CreateStateBlock ,Direct3DDevice7.EndStateBlock ,Direct3DDevice7.DeleteStateBlock ,스테이트 블록


Direct3DDevice7.CreateStateBlock

Direct3DDevice7.CreateStateBlock 메소드는, 모든 디바이스 스테이트, 버텍스 관련 스테이트, 픽셀 관련 스테이트의 현재의 값을 포함한 새로운 스테이트 블록을 생성 한다.

object. CreateStateBlock( _
  d3dsbType As CONST_D3DSTATEBLOCKTYPE, _
  blockHandle As Long)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
d3dsbType
메소드에 의해 캡춰 되는 스테이트 데이터의 형태. CONST_D3DSTATEBLOCKTYPE 열거로 정의된 값의 1 개로 할 수 있다.
blockHandle
메소드가 성공했을 경우의 스테이트 블록 핸들을 포함한 변수.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

D3DERR_INBEGINSTATEBLOCK
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

주의

버텍스 관련 스테이트란, 보통 시스템이 버텍스를 처리하는 방법에 관한 스테이트를 가리킨다. 픽셀 관련 스테이트란, 보통 시스템이 라스터화시에 픽셀 또는 깊이 버퍼 데이터를 처리하는 방법에 관한 스테이트를 가리킨다. 일부의 스테이트는 양쪽 모두의 그룹에 속한다. 각 그룹의 스테이트에 대해서는, 「사전 정의하는 스테이트 블록의 생성」을 참조할것.

참조

Direct3DDevice7.ApplyStateBlock ,Direct3DDevice7.BeginStateBlock ,Direct3DDevice7.CaptureStateBlock ,Direct3DDevice7.EndStateBlock ,Direct3DDevice7.DeleteStateBlock ,스테이트 블록


Direct3DDevice7.Clear

Direct3DDevice7.Clear 메소드는, 뷰포트 (혹은 뷰포트내의 직사각형세트)를 클리어 해 특정의 RGBA 색으로 하거나 깊이 버퍼를 클리어 하거나 스텐실 버퍼를 삭제하거나 한다.

object. Clear( _
    count As Long, _
    recs() As D3DRECT, _
    flags As CONST_D3DCLEARFLAGS, _
    color As Long, _
    z As Single, _
    stencil As Long)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
count
recs 의 배열에 있는 직사각형의 수.
recs()
클리어 하는 직사각형을 기술하는 D3DRECT 형의 배열. 직사각형을 렌더링 타겟의 치수로 설정 하면, 표면 전체가 클리어 된다. 각 직사각형은, 렌더링 타겟 표면 위에의점에 대응하는 화면 좌표를 사용한다. 좌표는 뷰포트의 직사각형의 경계에서 클립 된다.
flags
클리어 하는 표면을 나타내는 플래그. 이 파라미터는, 다음의 플래그의 임의의 편성을 취할 수가 있지만, 플래그를 최저 1 개(살)은 사용하지 않으면 안 된다.
D3DCLEAR_TARGET
렌더링 타겟을 클리어 해,color 파라미터의 색으로 한다.
D3DCLEAR_STENCIL
스텐실 버퍼를 클리어 해,stencil 파라미터의 값으로 한다.
D3DCLEAR_ZBUFFER
깊이 버퍼를 클리어 해,z 파라미터의 값으로 한다.
color
렌더링 타겟 표면을 클리어 하는데 사용하는, RGBA 컬러값. DirectX7.CreateColorRGBA 메소드를 호출해 적절한 값을 생성 할 수가 있다.
z
이 메소드가 깊이 버퍼에 보존하는 새로운 z 값. 이 파라미터에는, 0.0 에서 1.0 까지의 값 (양단의 값을 포함한다)을 사용할 수 있다 (z 또는 w 깊이 버퍼의 경우). 0.0 은 뷰아에 가장 가까운 거리, 1.0 은 가장 먼 거리를 나타낸다.
stencil
각 스텐실 버퍼의 엔트리에 보존하는 정수값. 이 파라미터에는 0 에서 2n-1 까지의 값 (양단의 값을 포함한다)을 사용할 수 있다. n 는, 스텐실 버퍼의 비트 깊이이다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

D3DERR_STENCILBUFFER_NOTPRESENT
D3DERR_VIEWPORTHASNODEVICE
D3DERR_ZBUFFER_NOTPRESENT
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는, 렌더링 타겟으로 깊이 버퍼가 Attach되어 있지 않을 때에 D3DCLEAR_ZBUFFER 또는 D3DCLEAR_STENCIL 플래그를 지정 하면 실패한다. 또, 깊이 버퍼의 포맷에 스텐실 버퍼의 정보가 포함되지 않을 때에, D3DCLEAR_STENCIL 플래그를 지정 하면 실패한다.


Direct3DDevice7.ComputeSphereVisibility

Direct3DDevice7.ComputeSphereVisibility 메소드는, 이 디바이스의 현재의 뷰포트내에 있어서의 구(공)의 가시성 (완전, 일부, 불가시)을 계산한다.

object. ComputeSphereVisibility( _
    center As D3DVECTOR, _
    radius As Single) As Long

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
center
월드 공간 좌표로, 구(공)의 중심점을 기술하는 D3DVECTOR 형의 배열.
radius
구(공)의 반경.

반환값

메소드가 성공하면(자),CONST_D3DCLIPFLAGS 열거의 플래그의 편성을 돌려준다. 이것에 의해, 디바이스의 현재의 뷰포트내에 있어서의 구(공)의 가시성을 나타낸다. 반환값이 0 ("안쪽" 플래그의 편성)의 경우, 그 구(공)의 가시성은 완전하게 된다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

트래핑 에러에 대해서는, 「Visual Basic 에러 트래핑」을 참조할것.

주의

구(공)의 가시성은, 월드, 뷰, 및 투영의 합성 행렬의 역행열을 사용해 절두체를 모델 공간에 역트랜스 폼 하는 것으로써 계산한다. 만약 이 합성 행렬이 역행열에 트랜스 폼 할 수 없을 때 (행렬식이 제로 때)는, 메소드는 실패해,DDERR_GENERIC 를 돌려준다.


Direct3DDevice7.DeleteStateBlock

Direct3DDevice7.DeleteStateBlock 메소드는, 이전에 기록된 디바이스 스테이트 블록을 삭제한다.

object. DeleteStateBlock( _
  blockHandle As Long)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
blockHandle
삭제하는 디바이스 스테이트 블록 (Direct3DDevice7.EndStateBlock 메소드에 의해 돌려주어진 디바이스 스테이트 블록)의 핸들.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 DDERR_INVALIDPARAMS 가 설정되어,blockHandle 파라미터가 무효인지, 매크로의 기록중인지를 나타낸다.

주의

다른 디바이스 스테이트 블록의 기록중은, 디바이스 스테이트 블록을 삭제할 수 없다.

참조

Direct3DDevice7.BeginStateBlock ,Direct3DDevice7.CaptureStateBlock ,Direct3DDevice7.CreateStateBlock ,Direct3DDevice7.EndStateBlock ,Direct3DDevice7.ApplyStateBlock ,스테이트 블록


Direct3DDevice7.DrawIndexedPrimitive

Direct3DDevice7.DrawIndexedPrimitive 메소드는, 버텍스의 배열에의 인덱스에 근거해, 지정된 지오메트리 프리미티브를 렌더링 한다.

object. DrawIndexedPrimitive( _
    d3Dpt As CONST_D3DPRIMITIVETYPE, _
    d3dfvf As CONST_D3DFVFFLAGS, _
    vertices As Any, _
    vertexCount As Long, _
    indices() As Integer, _
    IndicesCount As Long, _
    flags As CONST_D3DDPFLAGS)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
d3Dpt
이 커멘드에 의해 렌더링 되는 프리미티브의 형태. 이것은,CONST_D3DPRIMITIVETYPE 열거의 정수의 1 개가 아니면 안된다.

CONST_D3DPRIMITIVETYPE 의 D3DPT_POINTLIST 멤버에는, 인덱스가 없는 것에 주의한다.

d3dfvf
사용하는 버텍스 포맷을 기술하는CONST_D3DFVFFLAGS 열거의유연한 버텍스 포맷 플래그의 편성.
vertices
프리미티브 순서로 사용하는 버텍스 배열의 최초의 요소.
vertexCount
vertices 배열의 버텍스수를 정의한다.

이 파라미터는,Direct3DDevice7.DrawPrimitive 메소드에 있어서의 vertexCount 파라미터와는 다른 사용법을 하시는 것에 주의한다. Direct3DDevice7.DrawPrimitive 메소드에서는,vertexCount 파라미터는 드로잉(Drawing) 해야 할 버텍스수를 주지만, 이 메소드는 vertices 파라미터가 가리키는 배열의 합계 버텍스수를 준다. Direct3DDevice7.DrawIndexedPrimitive 메소드를 호출하면나무에는,IndicesCount 파라미터로 드로잉(Drawing) 해야 할 버텍스수를 지정한다.

indices()
렌더링 하는 지오메트리를 생성 할 경우에, 지정한 버텍스 리스트에의 인덱스부에 사용되는 배열. 이 배열의 값에 의해, 0 으로부터 dwNumVertices – 1 의 범위에서 버텍스에 인덱스를 붙이지 않으면 안 된다.
IndicesCount
지오메트리를 생성 하는데 준비하는 인덱스수를 지정한다. 허가된 인덱스의 최대수는 65535 (&HFFFF).
flags
프리미티브의 드로잉(Drawing) 방법을 정의하는 CONST_D3DDPFLAGS 의 정수의 1 개.

에러 코드

메소드가 실패 하면, 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
DDERR_WASSTILLDRAWING
DDERR_INVALIDPARAMS

트래핑 에러에 대해서는, 「Visual Basic 에러 트래핑」을 참조할것.

주의

렌더링 하는 버텍스의 포맷은, 지정한 버텍스 포맷과 일치해야 한다. 퍼포먼스 위에의 이유로부터, Direct3D 는, 버텍스의 사이즈와 보폭이, 지정된 유연한 버텍스 포맷과 일치할지 어떨지를 확인하지 않는다. 이것들이 일치하지 않는 경우, 메모리에 장해가 발생할 가능성이 있다.

버텍스 버퍼로부터 렌더링 하는 경우에는, 이 메소드 대신에, 버텍스 버퍼 메소드를 사용한다.

DirectX 의 현재의 버젼에서는,Direct3DDevice7.DrawIndexedPrimitive 는 때때로, 엄밀하게 필요하게 되는 것보다도 큰 갱신 직사각형을 생성하는 일이 있다. 다수의 버텍스수를 처리할 경우에는, 이것은 어플리케이션의 퍼포먼스에 악영향을 준다. D3DTLVERTEX 버텍스를 사용하는 경우, 시스템이 필요 이상의 버텍스를 처리할 경우에는, D3DDP_DONOTCLIP 와 D3DDP_DONOTUPDATEEXTENTS 플래그를 사용해 이 문제를 해결해야 하는 것이다.

참조

Direct3DDevice7.DrawPrimitive ,Direct3DDevice7.DrawPrimitiveVB ,Direct3DDevice7.DrawIndexedPrimitiveVB


Direct3DDevice7.DrawIndexedPrimitiveVB

Direct3DDevice7.DrawIndexedPrimitiveVB 메소드는, 버텍스 버퍼내의 버텍스 배열에의 인덱스에 근거해, 지오메트리 프리미티브를 렌더링 한다.

object. DrawIndexedPrimitiveVB( _
    d3Dpt As CONST_D3DPRIMITIVETYPE, _
    vertexBuffer As Direct3DVertexBuffer7, _
    StartVertex As Long, _
    NumVertices As Long, _
    indexArray() As Integer, _
    indexcount As Long, _
    flags As CONST_D3DDPFLAGS)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
d3Dpt
이 커멘드에 의해 렌더링 되는 프리미티브의 형태. 이것은,CONST_D3DPRIMITIVETYPE 열거의 정수의 1 개가 아니면 안된다.

CONST_D3DPRIMITIVETYPE 의 D3DPT_POINTLIST 멤버에는, 인덱스가 없는 것에 주의한다.

vertexBuffer
버텍스의 배열을 포함한 버텍스 버퍼에 대한 Direct3DVertexBuffer7 오브젝트. 버텍스는, 트랜스 폼 되고 있지 않아도, 최적화되고 있지 않아도 좋다.
StartVertex
렌더링 되는 버텍스 버퍼내의 최초의 버텍스의 인덱스.
NumVertices
렌더링 되는 버텍스 버퍼내의 버텍스 총수.
indexArray()
버텍스 버퍼내의 버텍스에의 인덱스부에 사용되는 배열. 이 배열의 값에 의해,StartVertex 로부터 StartVertex + NumVertices – 1 의 범위에서 버텍스에 인덱스를 붙이지 않으면 안 된다.
indexcount
indexArray() 배열내의 인덱스수. 허가된 인덱스의 최대수는 65535 (＆HFFFF).
flags
프리미티브의 드로잉(Drawing) 방법을 정의하는 CONST_D3DDPFLAGS 열거의 정수의 1 개.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
D3DERR_VERTEXBUFFERLOCKED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_WASSTILLDRAWING

트래핑 에러에 대해서는, 「Visual Basic 에러 트래핑」을 참조할것.

주의

렌더링 하는 버텍스의 포맷은, 지정한 버텍스 포맷과 일치해야 한다. 퍼포먼스 위에의 이유로부터, Direct3D 는, 버텍스의 사이즈와 보폭이, 지정된 유연한 버텍스 포맷과 일치할지 어떨지를 확인하지 않는다. 이것들이 일치하지 않는 경우, 메모리에 장해가 발생할 가능성이 있다.

버텍스 버퍼로부터 렌더링 하는 경우는, 버텍스 버퍼 메소드를 사용해야 한다.

레퍼런스 래스터라이저를 제외해, 소프트웨어 디바이스는, 로컬일까 비로컬일까에 관계없이, 비디오 메모리의 버텍스 버퍼로부터 렌더링 할 수 없다. 소프트웨어 디바이스를 사용해 버텍스 버퍼를 렌더링 하려면 , 버텍스 버퍼가 시스템 메모리에 존재해야 한다. 하드웨어 디바이스는, 시스템 메모리 또는 비디오 메모리의 어느 쪽의 버텍스 버퍼로부터에서도, 렌더링 할 수가 있다.

버텍스 버퍼가 락 되고 있을 때는 렌더링 할 수 없다. 락 된 버텍스 버퍼를 사용해 Direct3DDevice7.DrawIndexedPrimitiveVB 또는 Direct3DDevice7.DrawPrimitiveVB 메소드를 호출하려고 하면 실패해,D3DERR_VERTEXBUFFERLOCKED 를 돌려준다.

참조

Direct3DDevice7.DrawPrimitive ,Direct3DDevice7.DrawPrimitiveVB ,Direct3DDevice7.DrawIndexedPrimitive


Direct3DDevice7.DrawPrimitive

Direct3DDevice7.DrawPrimitive 메소드는, 지정의 형태의 지오메트리 프리미티브의 순서로서 버텍스의 지정의 배열을 렌더링 한다.

object. DrawPrimitive( _
    d3Dpt As CONST_D3DPRIMITIVETYPE, _
    d3dfvf As CONST_D3DFVFFLAGS, _
    vertices As Any, _
    vertexCount As Long, _
    flags As CONST_D3DDPFLAGS)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
d3Dpt
이 커멘드에 의해 렌더링 되는 프리미티브의 형태. 이것은,CONST_D3DPRIMITIVETYPE 열거의 정수의 1 개가 아니면 안된다.

CONST_D3DPRIMITIVETYPE 의 D3DPT_POINTLIST 멤버에는, 인덱스가 없는 것에 주의한다.

d3dfvf
사용하는 버텍스 포맷을 기술하는 CONST_D3DFVFFLAGS 열거의유연한 버텍스 포맷 플래그의 편성.
vertices
프리미티브 순서로 사용하는 버텍스 배열의 최초의 요소.
vertexCount
버텍스 배열내의 버텍스수를 정의한다. 허가된 버텍스의 최대수는, 65535 (&HFFFF).
flags
프리미티브의 드로잉(Drawing) 방법을 정의하는 CONST_D3DDPFLAGS 열거의 정수의 1 개.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
DDERR_WASSTILLDRAWING
DDERR_INVALIDPARAMS

트래핑 에러에 대해서는, 「Visual Basic 에러 트래핑」을 참조할것.

주의

버텍스 버퍼로부터 렌더링 하는 경우에는, 이 메소드 대신에 버텍스 버퍼 메소드를 사용한다.

렌더링 하는 버텍스의 포맷은, 지정한 버텍스 포맷과 일치해야 한다. 퍼포먼스 위에의 이유로부터, Direct3D 는, 버텍스의 사이즈와 보폭이, 지정된 유연한 버텍스 포맷과 일치할지 어떨지를 확인하지 않는다. 이것들이 일치하지 않는 경우, 메모리에 장해가 발생할 가능성이 있다.

참조

Direct3DDevice7.DrawPrimitiveVB ,Direct3DDevice7.DrawIndexedPrimitive ,Direct3DDevice7.DrawIndexedPrimitiveVB


Direct3DDevice7.DrawPrimitiveVB

Direct3DDevice7.DrawPrimitiveVB 메소드는, 지오메트리 프리미티브의 순서로서 버텍스 버퍼내의 버텍스의 배열을 렌더링 한다.

object. DrawPrimitiveVB( _
    d3dpt As CONST_D3DPRIMITIVETYPE, _
    vertexBuffer As Direct3DVertexBuffer7, _
    startVertex As Long, _
    numVertices As Long, _
    flags As CONST_D3DDPFLAGS)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
d3dpt
이 커멘드에 의해 렌더링 되는 프리미티브의 형태. 이것은,CONST_D3DPRIMITIVETYPE 열거의 정수의 1 개가 아니면 안된다.

CONST_D3DPRIMITIVETYPE 의 D3DPT_POINTLIST 멤버에는, 인덱스가 없는 것에 주의한다.

vertexBuffer
버텍스의 배열을 포함한 버텍스 버퍼에 대한 Direct3DVertexBuffer7 오브젝트. 버텍스는, 트랜스 폼 되고 있지 않아도, 최적화되고 있지 않아도 좋다.
startVertex
프리미티브중의 최초의 버텍스의 인덱스값. 최대 가능 시점 인덱스는 65535 (&HFFFF).
numVertices
렌더링 하는 버텍스수. 허가된 버텍스의 최대수는, 65535 (＆HFFFF).
flags
프리미티브의 드로잉(Drawing) 방법을 정의하는 CONST_D3DDPFLAGS 열거의 정수의 1 개.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
D3DERR_VERTEXBUFFERLOCKED
DDERR_WASSTILLDRAWING
DDERR_INVALIDPARAMS

트래핑 에러에 대해서는, 「Visual Basic 에러 트래핑」을 참조할것.

주의

렌더링 하는 버텍스의 포맷은, 지정한 버텍스 포맷과 일치해야 한다. 퍼포먼스 위에의 이유로부터, Direct3D 는, 버텍스의 사이즈와 보폭이, 지정된 유연한 버텍스 포맷과 일치할지 어떨지를 확인하지 않는다. 이것들이 일치하지 않는 경우, 메모리에 장해가 발생할 가능성이 있다.

버텍스 버퍼로부터 렌더링 하는 경우에는, 버텍스 버퍼 메소드를 사용해야 한다.

레퍼런스 래스터라이저를 제외해, 소프트웨어 디바이스는 비디오 메모리 (로컬 또는 비로컬)의 버텍스 버퍼로부터 렌더링 할 수 없다. 소프트웨어 디바이스를 사용해 버텍스 버퍼를 렌더링 하려면 , 버텍스 버퍼가 시스템 메모리에 존재해야 한다. 하드웨어 디바이스는, 시스템 메모리 또는 비디오 메모리의 어느 쪽의 버텍스 버퍼로부터에서도, 렌더링 할 수가 있다.

버텍스 버퍼가 락 되고 있을 때는 렌더링 할 수 없다. 락 된 버텍스 버퍼를 사용해 Direct3DDevice7.DrawIndexedPrimitiveVB 또는 Direct3DDevice7.DrawPrimitiveVB 메소드를 호출하려고 하면 실패해,D3DERR_VERTEXBUFFERLOCKED 를 돌려준다.

참조

Direct3DDevice7.DrawPrimitive ,Direct3DDevice7.DrawIndexedPrimitive ,Direct3DDevice7.DrawIndexedPrimitiveVB


Direct3DDevice7.EndScene

Direct3DDevice7.EndScene 메소드는,Direct3DDevice7.BeginScene 메소드에 의해 시작 된 장면을 종료한다.

object. EndScene()

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 가 설정된다.

주의

이 메소드가 성공하면(자), 장면이 렌더링 되어 디바이스 표면이 렌더링 된 장면을 보관 유지한다.

장면의 렌더링이 시작 된 다음에, 다음의 장면의 렌더링을 시작 하기 위해서 Direct3DDevice7.BeginScene 메소드를 호출하기 전에, 이 메소드를 호출하지 않으면 안 된다 (BeginScene 메소드가 실패했을 경우, 장면은 시작 되지 않기 때문에, 이 메소드를 호출할 필요는 없다).

참조

Direct3DDevice7.BeginScene


Direct3DDevice7.EndStateBlock

Direct3DDevice7.EndStateBlock 메소드는, 디바이스 스테이트 블록의 기록을 중지해, 블록 핸들을 취득하도록(듯이) Direct3D 에 지시한다.

object. EndStateBlock( _
    blockHandle As Long)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
blockHandle
완성한 디바이스 스테이트 블록의 핸들을 포함한 변수. 이 값은,Direct3DDevice7.ApplyStateBlock 및 Direct3DDevice7.DeleteStateBlock 메소드로 사용된다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 DDERR_INVALIDPARAMS 가 설정되어blockHandle 파라미터가 무효인지,Direct3DDevice7.BeginStateBlock 메소드가 불려 가지 않은 것을 나타낸다.

참조

Direct3DDevice7.ApplyStateBlock ,Direct3DDevice7.BeginStateBlock ,ct3DDevice7.CaptureStateBlock ,Direct3DDevice7.CreateStateBlock ,Direct3DDevice7.DeleteStateBlock ,스테이트 블록


Direct3DDevice7.GetCaps

Direct3DDevice7.GetCaps 메소드는, Direct3D 디바이스의 능력을 취득한다.

object. GetCaps( _
    desc As D3DDEVICEDESC7)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
desc
디바이스의 하드웨어 성능을 저장 하는 D3DDEVICEDESC7 형.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

트래핑 에러에 대해서는, 「Visual Basic 에러 트래핑」을 참조할것.

주의

이 메소드는, 디스플레이 디바이스의 능력을 취득하지 않는다. 이 정보를 취득하려면 ,DirectDraw7.GetCaps 메소드를 사용한다.


Direct3DDevice7.GetClipPlane

Direct3DDevice7.GetClipPlane 메소드는, 디바이스의 유저 정의 클립면의 계수를 취득한다.

object. GetClipPlane( _
  Index As Long, _
  a As Single, _
  b As Single, _
  c As Single, _
  d As Single)

파라미터

Index
평면식 계수를 취득하는 클립면의 인덱스.
a, b, c, and d
클립면의 계수를 나타내는 값. 일반적인 평면식에서 나타난다. 「주의」를 참조할것.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 DDERR_INVALIDPARAMS 가 설정된다. 이 에러는,Index 의 값이, 디바이스로 지원 되는 최대 클립면인덱스수를 넘는 것을 나타낸다.

주의

이 메소드에서는, 일반적인 평면식에서 계수를 돌려준다. Ax + By + Cz + D = 0 이 되도록(듯이),a,b,c, 및 d 의 값이 일반적인 평면식에 대입된다. Ax + By + Cz + Dw >= 0 의 경우, 동일한 좌표 (x,y,z,w)를 가지는 점이, 평면의 반의 공간에서 가시가 된다. 클립 얼굴 또는 배후에 있는 점은, 장면으로부터 클립 된다.

이 메소드로 사용되는 평면식은 월드 공간에 있어,Direct3DDevice7.SetClipPlane 메소드에 의해 설정된다.

참조

Direct3DDevice7.SetClipPlane ,D3DRENDERSTATE_CLIPPLANEENABLE ,유저 정의 클립면


Direct3DDevice7.GetClipStatus

Direct3DDevice7.GetClipStatus 메소드는, 현재의 클립 스테이터스를 취득한다.

object. GetClipStatus(clipStatus As D3DCLIPSTATUS)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
clipStatus
현재의 클립 스테이터스를 기술하는 D3DCLIPSTATUS 형.

에러 코드

메소드가 실패 하면 에러가 발생해, 파라미터중 한쪽이 무효의 경우는 Err.Number 에 DDERR_INVALIDPARAMS 가 설정된다.

참조

Direct3DDevice7.SetClipStatus


Direct3DDevice7.GetDeviceGuid

Direct3DDevice7.GetDeviceGuid 메소드는, 디바이스의 글로벌 유니크 식별자 (GUID)를 String 형으로 취득한다.

object. GetDeviceGuid() As String

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.

반환값

디바이스의 GUID 를 String 형으로 돌려준다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 가 설정된다.

참조

Direct3D 디바이스의 종류


Direct3DDevice7.GetDirect3D

Direct3DDevice7.GetDirect3D 메소드는, 이 디바이스의 Direct3D 오브젝트를 취득한다.

object. GetDirect3D() As Direct3D7

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.

반환값

메소드가 성공하면(자),Direct3D7 오브젝트에의 참조를 돌려준다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 가 설정된다.


Direct3DDevice7.GetInfo

Direct3DDevice7.GetInfo 메소드는, 렌더링 디바이스에 관한 정보를 취득한다. Direct3D 또는 기초가 되는 디바이스 드라이버에 관한 정보를 취득할 수 있다.

object. GetInfo( _
    lDevInfoID As CONST_D3DDEVINFOID, _
    DevInfoType As Any, _
    lSize As Long)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
lDevInfoID
DevInfoType 파라미터의 데이터형을 나타내는 CONST_D3DDEVINFOID 열거의 플래그.
DevInfoType
메소드가 성공했을 경우에, 지정된 디바이스의 정보를 포함한 변수. 이 변수의 데이터형과 데이터의 해석 방법에 대해서는,lDevInfoID 의 플래그에 의해 정해진다.
lSize
DevInfoType 로 나타나는 형태의 사이즈 (바이트수). Visual Basic 함수 Len 에 의해 돌려주어진다 .

반환값

없음.

에러 코드

메소드가 실패 하면, S_FALSE 를 돌려주어, 그 디바이스가 정보의 조회를 지원 하고 있지 않는 것을 나타내는지, 다음의 몇개의 에러 코드를 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드를 사용해, 이 SDK 의 문서에는 기재되지 않은 특정의 정보형, 및 대응하는 구조체를 드라이버를 선언할 수 있다.

이 메소드는 동기적으로 실행되므로, 저속 실행시에는 어플리케이션의 퍼포먼스가 저하하는 경우가 있다. 장면의 렌더링시 (Direct3DDevice7.BeginScene 를 호출하고 나서 Direct3DDevice7.EndScene 를 호출할 때까지 )는 이 메소드를 호출해서는 안 된다.

이 메소드는, 제품 개발시에 (DirectX 의 디버그 버젼으로) 퍼포먼스의 추적과 디버그를 위해서(때문에) 사용한다. 이 메소드는, 디바이스 데이터를 취득하는 일 없이 성공하는 경우가 있다. 호스트 시스템에 DirectX 런타임의 리테일 버젼이 인스톨 되고 있는 경우에 이러한 상황이 발생한다.

참조

D3DDEVINFO_TEXTUREMANAGER


Direct3DDevice7.GetLight

Direct3DDevice7.GetLight 메소드는, 이 디바이스로 사용되는 라이트 프로퍼티를 취득한다.

object. GetLight( _
    LightIndex As Long, _
    Light As D3DLIGHT7)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
LightIndex
취득되는 라이트 프로퍼티의 제로 베이스의 인덱스.
Light
취득되는 라이팅 파라미터를 저장 하는 D3DLIGHT7 형.

에러 코드

메소드가 실패 하면 에러가 발생해, 파라미터중 한쪽이 무효의 경우는 Err.Number 에 DDERR_INVALIDPARAMS 가 설정된다.

참조

Direct3DDevice7.SetLight ,Direct3DDevice7.GetLightEnable ,Direct3DDevice7.LightEnable ,머트리얼


Direct3DDevice7.GetLightEnable

Direct3DDevice7.GetLightEnable 메소드는, 라이트 상태 (유효 또는 무효)를 취득한다.

object. GetLightEnable( _
    LightIndex As Long) As Boolean

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
LightIndex
이 메소드의 대상이 되는 라이팅 파라미터의 제로 베이스의 인덱스.

반환값

메소드가 성공하면(자), 라이트 상태를 나타내는 값을 돌려준다. 지정된 라이트가 유효의 경우는 TRUE, 무효의 경우는 FALSE 를 돌려준다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 에러 코드가 설정된다. 설정되는 에러 코드의 리스트에 대해서는, Direct3D 직접 모드의 「에러 코드」를 참조할것.

참조

Direct3DDevice7.GetLight ,Direct3DDevice7.LightEnable ,Direct3DDevice7.SetLight ,라이팅과 머트리얼


Direct3DDevice7.GetMaterial

Direct3DDevice7.GetMaterial 메소드는, 디바이스의 현재의 머트리얼 프로퍼티를 취득한다.

object. GetMaterial(  _
    Material As D3DMATERIAL7)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
Material
현재의 머트리얼 프로퍼티를 저장 하는 D3DMATERIAL7 형.

에러 코드

메소드가 실패하는 에러가 발생해,Err.Number 에 DDERR_INVALIDPARAMS 가 설정되어Material 파라미터가 무효라는 점을 나타낸다.

참조

Direct3DDevice7.SetMaterial ,라이팅과 머트리얼


Direct3DDevice7.GetRenderState

Direct3DDevice7.GetRenderState 메소드는, 디바이스의 렌더링 스테이트값을 취득한다.

object. GetRenderState( _
    state As CONST_D3DRENDERSTATETYPE) As Long

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
state
조사 대상의 디바이스 스테이트 변수. 이 파라미터는,CONST_D3DRENDERSTATETYPE 열거의 임의의 정수로 할 수 있다.

반환값

메소드가 성공하면(자), 지정된 렌더링 스테이트의 현재의 값을 돌려준다.

에러 코드

메소드가 실패 하면 에러가 발생해, 파라미터중 한쪽이 무효의 경우는 Err.Number 에 DDERR_INVALIDPARAMS 가 설정된다.

참조

Direct3DDevice7.SetRenderState


Direct3DDevice7.GetRenderStateSingle

Direct3DDevice7.GetRenderStateSingle 메소드는, 디바이스의 렌더링 스테이트값을 취득한다.

object. GetRenderStateSingle( _
    state As CONST_D3DRENDERSTATESINGLE) As Single

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
state
조사 대상의 디바이스 스테이트 변수. 이 파라미터는,CONST_D3DRENDERSTATESINGLE 열거의 임의의 정수로 할 수 있다.

반환값

메소드가 성공하면(자), 지정된 렌더링 스테이트의 현재의 값을 돌려준다.

에러 코드

메소드가 실패 하면 에러가 발생해, 파라미터중 한쪽이 무효의 경우는 Err.Number 에 DDERR_INVALIDPARAMS 가 설정된다.

참조

Direct3DDevice7.SetRenderState ,Direct3DDevice7.SetRenderStateSingle


Direct3DDevice7.GetRenderTarget

Direct3DDevice7.GetRenderTarget 메소드는, 렌더링 타겟으로서 사용되고 있는 DirectDrawSurface7 오브젝트를 취득한다.

object. GetRenderTarget() As DirectDrawSurface7

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.

반환값

메소드가 성공하면(자), 렌더링 타겟 표면 (DirectDrawSurface7 오브젝트)에의 참조를 돌려준다.

에러 코드

메소드가 실패 하면 에러가 발생해, 파라미터중 한쪽이 무효의 경우는 Err.Number 에 DDERR_INVALIDPARAMS 가 설정된다.

참조

Direct3DDevice7.SetRenderTarget


Direct3DDevice7.GetTexture

Direct3DDevice7.GetTexture 메소드는, 디바이스의, 지정의 스테이지에 할당할 수 있었던 텍스쳐를 취득한다.

object. GetTexture(stage As Long) As DirectDrawSurface7

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
stage
취득하는 텍스쳐의 스테이지 식별자. 스테이지 식별자는 제로를 베이스로 한다. 현재, 디바이스는 8 세트까지의 텍스쳐를 가질 수가 있으므로,stage 에 용서되는 최대치는 7 이다.

반환값

메소드가 성공하면(자), 지정된 텍스쳐의 DirectDrawSurface7 오브젝트를 돌려준다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

트래핑 에러에 대해서는, 「Visual Basic 에러 트래핑」을 참조할것.

참조

Direct3DDevice7.SetTexture ,Direct3DDevice7.GetTextureStageState ,Direct3DDevice7.SetTextureStageState ,텍스쳐


Direct3DDevice7.GetTextureFormatsEnum

Direct3DDevice7.GetTextureFormatsEnum 메소드는,Direct3DEnumPixelFormats 오브젝트를 취득한다.

object. GetTextureFormatsEnum() As Direct3DEnumPixelFormats

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.

반환값

메소드가 성공하면(자),Direct3DEnumPixelFormats 오브젝트에의 참조를 돌려준다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

트래핑 에러에 대해서는, 「Visual Basic 에러 트래핑」을 참조할것.

주의

디바이스가 그 텍스쳐로 지원 하는 픽셀 포맷의 정보를 취득하려면 ,Direct3DEnumPixelFormats 오브젝트의 메소드를 사용한다.


Direct3DDevice7.GetTextureStageState

Direct3DDevice7.GetTextureStageState 메소드는, 현재 할당할 수 있고 있는 텍스쳐 스테이트값을 취득한다.

object. GetTextureStageState( _
    stage As Long, _
    state As CONST_D3DTEXTURESTAGESTATETYPE) As Long

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
stage
스테이트를 취득하는 텍스쳐의 스테이지 식별자. 스테이지 식별자는 제로를 베이스로 한다. 현재, 디바이스는 8 세트까지의 텍스쳐를 가질 수가 있으므로, stage 에 용서되는 최대치는 7 이다.
state
취득되는 텍스쳐의 스테이트. 이 파라미터는,CONST_D3DTEXTURESTAGESTATETYPE 열거의 임의의 정수로 할 수 있다.

반환값

메소드가 성공하면(자), 스테이트값을 돌려준다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

트래핑 에러에 대해서는, 「Visual Basic 에러 트래핑」을 참조할것.

참조

Direct3DDevice7.SetTextureStageState ,Direct3DDevice7.GetTexture ,Direct3DDevice7.SetTexture ,텍스쳐


Direct3DDevice7.GetTextureStageStateSingle

Direct3DDevice7.GetTextureStageStateSingle 메소드는, 현재 할당할 수 있고 있는 텍스쳐의 스테이트값을, Single 형으로 취득한다.

object. GetTextureStageStateSingle( _
    stage As Long, _
    state As CONST_D3DTEXTURESTAGESINGLE) As Single

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
stage
스테이트를 취득하는 텍스쳐의 스테이지 식별자. 스테이지 식별자는 제로를 베이스로 한다. 현재, 디바이스는 8 세트까지의 텍스쳐를 가질 수가 있으므로,stage 에 용서되는 최대치는 7 이다.
state
취득되는 텍스쳐의 스테이트. 이 파라미터는,CONST_D3DTEXTURESTAGESINGLE 열거의 임의의 정수로 할 수 있다.

반환값

메소드가 성공하면(자), 스테이트값을 돌려준다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

트래핑 에러에 대해서는, 「Visual Basic 에러 트래핑」을 참조할것.

참조

Direct3DDevice7.SetTextureStageState ,Direct3DDevice7.SetTextureStageStateSingle ,Direct3DDevice7.GetTexture ,Direct3DDevice7.SetTexture ,텍스쳐


Direct3DDevice7.GetTransform

Direct3DDevice7.GetTransform 메소드는, 트랜스 폼 스테이트를 기술하는 행렬을 취득한다.

object. GetTransform( _
    transformType As CONST_D3DTRANSFORMSTATETYPE, _
    matrix As D3DMATRIX)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
transformType
변경 대상의 디바이스 스테이트 변수. 이 파라미터는,CONST_D3DTRANSFORMSTATETYPE 열거의 임의의 정수로 할 수 있다.
matrix
트랜스 폼을 기술하는 D3DMATRIX 형.

에러 코드

메소드가 실패 하면 에러가 발생해, 파라미터중 한쪽이 무효의 경우는 Err.Number 에 DDERR_INVALIDPARAMS 가 설정된다.

참조

Direct3DDevice7.SetTransform


Direct3DDevice7.GetViewport

Direct3DDevice7.GetViewport 메소드는, 디바이스에 현재 설정되어 있는 뷰포트 파라미터를 취득한다.

object. GetViewport( _
    Viewport As D3DVIEWPORT7)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
Viewport
메소드가 생성 했을 경우에, 현재의 뷰포트 파라미터를 저장 하는 D3DVIEWPORT7 형.

반환값

메소드가 실패 하면 에러가 발생해,Viewport 파라미터가 무효의 경우는 Err.Number 에 DDERR_INVALIDPARAMS 가 설정된다.

참조

Direct3DDevice7.SetViewport


Direct3DDevice7.LightEnable

Direct3DDevice7.LightEnable 메소드는, 디바이스의 라이팅 파라미터를 유효 또는 무효로 한다.

object. LightEnable( _
    LightIndex As Long, _
    bEnable As Boolean)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
LightIndex
이 메소드의 대상이 되는 라이팅 파라미터의 제로 베이스의 인덱스.
bEnable
라이팅 파라미터가 유효한가 무효인지를 나타내는 값. 제로 이외의 값으로 설정 하면, 지정된 인덱스에 있는 파라미터의 라이팅이 유효하게 되어, 제로로 설정 하면 무효가 된다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 에러 코드가 설정된다. Direct3D 직접 모드의 에러 코드와 그 설명에 대해서는, 「에러 코드」를 참조할것.

주의

LightIndex 의 값을, 디바이스로 현재 할당할 수 있고 있는 라이트 프로퍼티의 범위외의 값으로 했을 경우,LightEnable 메소드에 의해 다음의 프로퍼티의 광원이 생성 되어 유효 스테이트가 Enable 로 지정한 값으로 설정된다.

멤버 | 디폴트
dltType | D3DLIGHT_DIRECTIONAL
dcvDiffuse | (R:1, G:1, B:1, A:0)
dcvSpecular | (R:0, G:0, B:0, A:0)
dcvAmbient | (R:0, G:0, B:0, A:0)
dvPosition | (0, 0, 0)
dvDirection | (0, 0, 1)
dvRange | 0
dvFalloff | 0
dvAttenuation0 | 0
dvAttenuation1 | 0
dvAttenuation2 | 0
dvTheta | 0
dvPhi | 0

참조

Direct3DDevice7.GetLight ,Direct3DDevice7.GetLightEnable ,Direct3DDevice7.SetLight ,라이팅과 머트리얼


Direct3DDevice7.Load

Direct3DDevice7.Load 메소드는, 전송원텍스쳐의 직사각형 영역을, 목적지 텍스쳐의 지정된 점, 또는 큐브 환경 맵내의 면에 로드한다.

object. Load( _
    DestTex As DirectDrawSurface7, _
    xDest As Long, _
    yDest As Long, _
    SrcTex  As DirectDrawSurface7, _
    rcSrcRect As RECT, _
    flags As Long)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
DestTex
전송원텍스쳐로부터 이미지 데이터를 받는 DirectDrawSurface7 클래스. 큐브 환경 맵이나 밉맵등의 복합 텍스쳐 표면에서는, 최상정도 표면이 아니면 안된다.
xDest and yDest
이 메소드에 의해 이미지 데이터가 로드 되는 목적지 텍스쳐 위에의점의 x 좌표와 y 좌표.
SrcTex
로드 되는 이미지 데이터를 저장 하는 DirectDrawSurface7 클래스. 큐브 환경 맵이나 밉맵등의 복합 텍스쳐 표면에서는, 최상정도 표면이 아니면 안된다.
rcSrcRect
이 메소드에 의해 로드 되는 전송원텍스쳐의 영역을 기술하는 RECT 형의 주소. 전송원의 직사각형이 전송원텍스쳐 전체를 커버하는 경우, 또는 이 메소드를 사용해, 관리하의 텍스쳐를 명시적으로 로드하는 경우, 이 파라미터를 Nothing 로 설정한다.
flags
큐브 환경 맵으로, 이미지 데이터를 받는 목적지 텍스쳐의 면을 나타내는 값. 이 파라미터는, 이하에 나타내는 플래그의 임의의 편성으로 만들어진다.
0
목적지 텍스쳐가 관리하의 텍스쳐의 경우에 필요.
DDSCAPS2_CUBEMAP_ALLFACES
전송원텍스쳐에 있는 이미지 데이가 모든 면에 로드 된다.
DDSCAPS2_CUBEMAP_NEGATIVEX, DDSCAPS2_CUBEMAP_NEGATIVEY, 또는 DDSCAPS2_CUBEMAP_NEGATIVEZ
부의 x, y, z 면이 이미지 데이터를 받는다.
DDSCAPS2_CUBEMAP_POSITIVEX, DDSCAPS2_CUBEMAP_POSITIVEY, or DDSCAPS2_CUBEMAP_POSITIVEZ
정의 x, y, z 면이 이미지 데이터를 받는다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

목적지 텍스쳐는, 그 텍스쳐를 생성 한 렌더링 디바이스 뿐만이 아니라, 임의의 렌더링 디바이스로 사용할 수 있다. 하드웨어 디바이스에서는, 로드 처리는 하드웨어 가속화가 된다.

비트 처리의 경우, 이 메소드를 호출해 텍스쳐를 비디오 메모리에 로드하는 (분)편이 바람직하다.

이 메소드는, 모든 레벨의 밉맵, 큐브 맵면, 팔레트 및 컬러 키를 전송원텍스쳐로부터 목적지 텍스쳐에 카피한다.

이 메소드를 사용해 밉맵을 로드하는 경우, 이하의 점에 주의한다.

  • 목적지 텍스쳐 표면을, 전송원텍스쳐에 포함되는 밉레벨의 서브 세트로 할 수 있다. 이 경우, 양쪽 모두의 텍스쳐에 공통의 밉레벨만이 카피된다. 이것은, 텍스쳐 LOD 를 이행 할 때에 유효하다. 2 밉레벨만의 비디오 메모리 텍스쳐를 생성 해, 이 메소드를 사용해, 모든 밉레벨로 구성된 전송원텍스쳐로부터 이러한 레벨을 카피할 수가 있다.
  • 전송원 및 목적지 표면 포인터는, 최상정도 표면을 가리키지 않으면 안 된다.
  • 밉맵의 서브 직사각형을 로드하는 경우, 서브 직사각형은 밉맵 체인의 최상정도 표면에 적용되어 하위 밉레벨 마다 2 개(살)로 분할된다.


Direct3DDevice7.MultiplyTransform

Direct3DDevice7.MultiplyTransform 메소드는, 디바이스의 월드, 뷰, 투영 행렬에, 지정된 행렬을 곱셈한다. 곱셈의 순서는,matrix 걸치는 dstTransformStateType 이다.

object. MultiplyTransform( _
    dstTransformStateType As CONST_D3DTRANSFORMSTATETYPE, _
    matrix As D3DMATRIX)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
dstTransformStateType
수정하는 디바이스 행렬을 나타낸다. 이 파라미터는,CONST_D3DTRANSFORMSTATETYPE 열거의 임의의 정수로 할 수 있다. 가장 일반적인 설정은 D3DTRANSFORMSTATE_WORLD 로, 월드 행렬을 변경하지만, 필요하면, 뷰 행렬이나 투영 행렬을 변경하도록(듯이) 지정할 수도 있다.
matrix
현재의 트랜스 폼을 수정하는 D3DMATRIX 형.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 가 설정된다. 이 메소드는, 인수중 한쪽이 무효인 경우에는,DDERR_INVALIDPARAMS 를 돌려준다.

주의

어플리케이션이, 트랜스 폼의 계층을 진이나 테 동작하기 위해서,MultiplyTransform 메소드를 사용하는 일도 생각할 수 있다. 예를 들어, 팔을 나타내는 지오메트리와 트랜스 폼은, 이하의 계층에서 구성하는 일도 있다.

shoulder_transformation
    upper_arm geometry
    elbow transformation
        lower_arm geometry
        wrist transformation
            hand geometry

어플리케이션은, 이 계층을 렌더링 하는데, 이하의 일련의 호출을 사용해도 괜찮다 (이 의사 코드에서는, 모든 파라미터는 가리키지 않았다).

Direct3DDevice7.SetTransform(D3DTRANSFORMSTATE_WORLD,
    shoulder_transform)
Direct3DDevice7.DrawPrimitive(upper_arm)
Direct3DDevice7.MultiplyTransform(D3DTRANSFORMSTATE_WORLD,
    elbow_transform)
Direct3DDevice7.DrawPrimitive(lower_arm)
Direct3DDevice7.MultiplyTransform(D3DTRANSFORMSTATE_WORLD,
    wrist_transform)
Direct3DDevice7.DrawPrimitive(hand)

참조

Direct3DDevice7.DrawPrimitive ,Direct3DDevice7.SetTransform


Direct3DDevice7.PreLoad

Direct3DDevice7.Preload 메소드는, 관리하의 텍스쳐를 비디오 메모리에 로드하도록(듯이) Direct3D 텍스쳐 매니저에 지시한다.

object. PreLoad( _
  Texture As DirectDrawSurface7)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
Texture
메모리에 로드 되는 DirectDrawSurface7 오브젝트에의 참조.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드를 사용 하면, 관리하의 테키스체가 강제적으로 비디오 메모리에 로드 되므로, 충분한 비디오 메모리가 없는 경우, 시스템은 메모리를 확보하기 위해서 다른 텍스쳐를 삭제하고 나서, 지정된 텍스쳐를 로드한다. 로드하는 텍스쳐는, 관리하의 텍스쳐 (DDSCAPS2_TEXTUREMANAGE 또는 DDSCAPS2_D3DTEXTUREMANAGE 플래그에 의해 생성 된 텍스쳐)가 아니면 안된다. 이러한 조건이 채워지지 않은 경우는, 메소드가 실패해,DDERR_INVALIDPARAMS 를 돌려준다.

참조

자동 텍스쳐 관리


Direct3DDevice7.SetClipPlane

Direct3DDevice7.SetClipPlane 메소드는, 디바이스의 유저 정의 클립면의 계수를 설정한다.

object. SetClipPlane( _
  Index As Long, _
  a As Single, _
  b As Single, _
  c As Single, _
  d As Single)

파라미터

Index
평면식 계수를 취득하는 클립면의 인덱스.
a, b, c, and d
클립면의 계수를 일반적인 평면식에서 나타내는 값. 「주의」를 참조할것.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 DDERR_INVALIDPARAMS 가 설정된다. 이 에러는,Index 의 값이, 그 디바이스로 지원 되는 최대 클립면인덱스수를 넘는 것을 나타낸다.

주의

이 메소드에서는, 일반적인 평면식에서 계수를 돌려준다. Ax + By + Cz + D = 0 이 되도록(듯이),a,b,c, 및 d 의 값이 일반적인 평면식에 대입된다. Ax + By + Cz + Dw >= 0 의 경우, 동일한 좌표 (x,y,z,w)를 가지는 점이, 평면의 반의 공간에서 가시가 된다. 클립 얼굴 또는 배후에 있는 점은, 장면으로부터 클립 된다.

이 메소드로 사용되는 평면식은 월드 공간에 있다.

이 메소드는, 설정되어 있는 클립면을 유효하게 하는 것은 아니다. 클립면을 유효하게 하려면 ,D3DRENDERSTATE_CLIPPLANEENABLE 렌더링 스테이트를 사용한다.

참조

Direct3DDevice7.GetClipPlane ,D3DRENDERSTATE_CLIPPLANEENABLE ,유저 정의 클립면


Direct3DDevice7.SetClipStatus

Direct3DDevice7.SetClipStatus 메소드는, 현재의 클립 스테이터스를 설정한다.

object. SetClipStatus(clipStatus As D3DCLIPSTATUS)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
clipStatus
클립 스테이터스의 새로운 설정값을 기술하는 D3DCLIPSTATUS 형.

에러 코드

메소드가 실패 하면 에러가 발생해,clipStatus 파라미터가 무효의 경우는 Err.Number 에 DDERR_INVALIDPARAMS 가 설정된다.

트래핑 에러에 대해서는, 「Visual Basic 에러 트래핑」을 참조할것.

참조

Direct3DDevice7.GetClipStatus


Direct3DDevice7.SetLight

Direct3DDevice7.SetLight 메소드는, 디바이스에 라이팅 파라미터를 할당한다.

object. SetLight( _
    LightIndex As Long, _
    Light As D3DLIGHT7)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
LightIndex
설정되는 라이팅 파라미터의 0 으로부터 시작되는 인덱스. 이 인덱스에 이미 라이트 프로퍼티가 존재하는 경우, 새로운 프로퍼티가 덧쓰기된다.
Light
설정되는 라이팅 파라미터를 저장 하는 D3DLIGHT7 형.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

참조

Direct3DDevice7.GetLight ,Direct3DDevice7.GetLightEnable ,Direct3DDevice7.LightEnable ,라이팅과 머트리얼


Direct3DDevice7.SetMaterial

Direct3DDevice7.SetMaterial 메소드는, 디바이스의 머트리얼 프로퍼티를 설정한다.

object. SetMaterial( _
  mat As D3DMATERIAL7)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
mat
설정되는 머트리얼 프로퍼티를 기술하는 D3DMATERIAL7 형.

에러 코드

메소드가 성공하면(자), D3D_OK 를 돌려준다.

메소드가 실패 하면, 에러를 돌려준다. mat 파라미터가 무효의 경우, 메소드는 DDERR_INVALIDPARAMS 를 돌려준다.

참조

Direct3DDevice7.GetMaterial


Direct3DDevice7.SetRenderState

Direct3DDevice7.SetRenderState 메소드는, 디바이스의 렌더링 스테이트에 Long 형의 값을 설정한다.

object. SetRenderState( _
    state As CONST_D3DRENDERSTATETYPE, _
    renderstate As Long)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
state
변경 대상의 디바이스 스테이트 변수. 이 파라미터는,CONST_D3DRENDERSTATETYPE 열거의 임의의 정수로 할 수 있다.
renderstate
새로운 렌더링 스테이트값. 이 파라미터의 의미는 state 로 지정한 값에 의한다. 예를 들어,state 가 D3DRENDERSTATE_SHADEMODE 인 경우에는, 이 제 2 파라미터는,CONST_D3DSHADEMODE 열거의 정수의 1 개가 된다.

에러 코드

메소드가 실패 하면 에러가 발생해, 파라미터중 한쪽이 무효의 경우는 Err.Number 에 DDERR_INVALIDPARAMS 가 설정된다.

참조

Direct3DDevice7.GetRenderState ,Direct3DDevice7.SetTransform


Direct3DDevice7.SetRenderStateSingle

Direct3DDevice7.SetRenderStateSingle 메소드는, 디바이스의 렌더링 스테이트에 Single 형의 값을 설정한다.

object. SetRenderStateSingle( _
    state As CONST_D3DRENDERSTATESINGLE, _
    renderstate As Single)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
state
변경 대상의 디바이스 스테이트 변수. 이 파라미터는,CONST_D3DRENDERSTATESINGLE 열거의 임의의 정수로 할 수 있다.
renderstate
새로운 렌더링 스테이트값. 이 파라미터의 의미는 state 로 지정한 값에 의한다. 예를 들어,state 가 D3DRENDERSTATE_SHADEMODE 인 경우에는, 이 제 2 파라미터는,CONST_D3DSHADEMODE 열거의 정수의 1 개가 된다.

에러 코드

메소드가 실패 하면 에러가 발생해, 파라미터중 한쪽이 무효의 경우는,Err.Number 에 DDERR_INVALIDPARAMS 가 설정된다.

참조

Direct3DDevice7.GetRenderState ,Direct3DDevice7.GetRenderStateSingle ,Direct3DDevice7.SetTransform


Direct3DDevice7.SetRenderTarget

Direct3DDevice7.SetRenderTarget 메소드는, 렌더링 타겟으로서 새로운 DirectDraw 표면의 방향으로, 렌더링 출력을 간단하게 지정하는 것을 어플리케이션에 허락한다.

object. SetRenderTarget(surface As DirectDrawSurface7)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
surface
이미 생성 되고 있는, 새로운 렌더링 타겟이 되는 표면 오브젝트에 대한 DirectDrawSurface7 오브젝트.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE

트래핑 에러에 대해서는, 「Visual Basic 에러 트래핑」을 참조할것.

주의

능력은, 렌더링 타겟 표면의 프로퍼티의 변화에 따라서는 변함없다. Direct3D HAL 및 소프트웨어 래스터라이저 모두, 어플리케이션에 능력을 나타낼 기회는 한 번 뿐이다. 시스템은, 목적의 표면의 포맷에 의해 다른 능력세트를 제시할 수 없다.

새로운 렌더링 타겟으로 깊이 버퍼가 Attach 되고 있는 경우, 문맥의 낡은 z 버퍼를 옮겨놓을 수 있다. 그 이외의 경우는, 낡은 z 버퍼의 Attach가 해제되어 z 버퍼링이 무효가 된다.

복수의 깊이 버퍼가 렌더링 타겟으로 Attach 되고 있으면(자), 이 함수는 실패한다.

참조

Direct3DDevice7.GetRenderTarget


Direct3DDevice7.SetTexture

Direct3DDevice7.SetTexture 메소드는, 디바이스의 지정된 스테이지에 텍스쳐를 할당한다.

object. SetTexture( _
    stage As Long, _
    texture As DirectDrawSurface7)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
stage
텍스쳐를 설정하는 스테이지 식별자. 스테이지 식별자는 제로를 베이스로 한다. 현재, 디바이스는 8 세트까지의 텍스쳐를 가질 수가 있으므로,stage 에 용서되는 최대치는 7 이다.
texture
설정되는 텍스쳐의 DirectDrawSurface7 오브젝트. 큐브 환경 맵등의 복합 텍스쳐에서는, 최상정도 표면이 아니면 안된다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

트래핑 에러에 대해서는, 「Visual Basic 에러 트래핑」을 참조할것.

주의

텍스쳐가 불필요하게 되었을 경우, 해당하는 스테이지의 텍스쳐를 Nothing 로 설정할 필요가 있다. 이 처리를 실시하지 않으면 어플리케이션의 종료시에, 그 표면의 메모리가 없어진다.

소프트웨어 디바이스는, 1 개의 텍스쳐를 한 번에 복수의 텍스쳐 스테이지에 할당하는 것은 지원 하고 있지 않다.

참조

Direct3DDevice7.GetTexture ,Direct3DDevice7.GetTextureStageState ,Direct3DDevice7.SetTextureStageState ,텍스쳐


Direct3DDevice7.SetTextureStageState

Direct3DDevice7.SetTextureStageState 메소드는, 현재 할당할 수 있고 있는 텍스쳐의 스테이트값을 설정한다.

object. SetTextureStageState( _
    stage As Long, _
    state As CONST_D3DTEXTURESTAGESTATETYPE, _
    value As Long)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
stage
스테이트값을 설정하는 텍스쳐의 스테이지 식별자. 스테이지 식별자는 제로를 베이스로 한다. 현재, 디바이스는 8 세트까지의 텍스쳐를 가질 수가 있으므로,stage 에 용서되는 최대치는 7 이다.
state
설정하는 텍스쳐 스테이트. 이 파라미터는,CONST_D3DTEXTURESTAGESTATETYPE 열거의 임의의 정수로 할 수 있다.
value
설정하는 스테이트값. 이 값의 의미는 state 파라미터로 정해진다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

종래의 텍스쳐 관련 렌더링 스테이트를 설정하려면 , 이 메소드를 사용해 텍스쳐 스테이트를 설정할 필요가 있다. 상세한 것에 대하여는, 「렌더링 스테이트에 대하며」를 참조할것.

참조

Direct3DDevice7.GetTextureStageState ,Direct3DDevice7.GetTexture ,Direct3DDevice7.SetTexture ,텍스쳐


Direct3DDevice7.SetTextureStageStateSingle

Direct3DDevice7.SetTextureStageStateSingle 메소드는, 현재 할당할 수 있고 있는 텍스쳐의 스테이트값을 설정한다.

object. SetTextureStageStateSingle( _
    stage As Long, _
    state As CONST_D3DTEXTURESTAGESINGLE, _
    value As Single)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
stage
스테이트값을 설정하는 텍스쳐의 스테이지 식별자. 스테이지 식별자는 제로를 베이스로 한다. 현재, 디바이스는 8 세트까지의 텍스쳐를 가질 수가 있으므로,stage 에 용서되는 최대치는 7 이다.
state
설정하는 텍스쳐 스테이트. 이 파라미터는,CONST_D3DTEXTURESTAGESINGLE 열거의 임의의 정수로 할 수 있다.
value
설정하는 스테이트값. 이 값의 의미는 state 파라미터로 정해진다.

Error Codes

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

종래의 텍스쳐 관련 렌더링 스테이트를 설정하려면 , 이 메소드를 사용해 텍스쳐 스테이트를 설정할 필요가 있다. 상세한 것에 대하여는, 「렌더링 스테이트에 대하며」를 참조할것.

참조

Direct3DDevice7.GetTextureStageStateSingle ,Direct3DDevice7.GetTextureStageState ,Direct3DDevice7.GetTexture ,Direct3DDevice7.SetTexture ,텍스쳐


Direct3DDevice7.SetTransform

Direct3DDevice7.SetTransform 메소드는, 디바이스의 단일의 트랜스 폼 관련 스테이트를 설정한다.

object. SetTransform( _
    transformType As CONST_D3DTRANSFORMSTATETYPE, _
    matrix As D3DMATRIX)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
transformType
변경 대상의 디바이스 스테이트 변수. 이 파라미터는,CONST_D3DTRANSFORMSTATETYPE 열거의 임의의 정수로 할 수 있다.
matrix
현재의 정보를 수정하는 D3DMATRIX 형.

에러 코드

메소드가 실패 하면 에러가 발생해, 파라미터중 한쪽이 무효의 경우는 Err.Number 에 DDERR_INVALIDPARAMS 가 설정된다.

트래핑 에러에 대해서는, 「Visual Basic 에러 트래핑」을 참조할것.

참조

Direct3DDevice7.GetTransform ,Direct3DDevice7.SetRenderState


Direct3DDevice7.SetViewport

Direct3DDevice7.SetViewport 메소드는, 디바이스의 뷰포트 파라미터를 설정한다.

object. SetViewport( _
    viewport As D3DVIEWPORT7)

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.
viewport
설정된 뷰포트 파라미터를 저장 하는 D3DVIEWPORT7 형.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 DDERR_INVALIDPARAMS 가 설정되어,viewport 파라미터가 무효라는 점을 나타낸다.

주의

D3DVIEWPORT7 형에 저장 된 viewport 파라미터가, 렌더링 타겟 표면내에 존재하지 않는 영역을 나타내는 경우, 이 메소드는 실패해,DDERR_INVALIDPARAMS 를 돌려준다.

참조

Direct3DDevice7.GetViewport


Direct3DDevice7.ValidateDevice

Direct3DDevice7.ValidateDevice 메소드는, 현재 설정되어 있는 텍스쳐의 블렌딩 조작과 파라미터에 대해, 디바이스가 1 회의 처리로 렌더링 할 수 있는 능력을 보고한다.

object. ValidateDevice() As Long

파라미터

object
Direct3DDevice7 오브젝트를 나타내는오브젝트식.

반환값

메소드가 성공하면(자), 멀티 패스 렌더링에 의해 렌더링을 완료하기 위해서 필요한 회수를 돌려준다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
D3DERR_CONFLICTINGTEXTUREFILTER
D3DERR_TOOMANYOPERATIONS
D3DERR_UNSUPPORTEDALPHAARG
D3DERR_UNSUPPORTEDALPHAOPERATION
D3DERR_UNSUPPORTEDCOLORARG
D3DERR_UNSUPPORTEDCOLOROPERATION
D3DERR_UNSUPPORTEDFACTORVALUE
D3DERR_UNSUPPORTEDTEXTUREFILTER
D3DERR_WRONGTEXTUREFORMAT

주의

현재의 하드웨어가, 반드시 조작과 인수의 가능한 모든 편성을 이행 하고 있을 필요는 없다. 특정의 블렌딩 조작이 주어진 파라미터로 완성될지 어떨지는, 필요한 블렌딩 조작을 설정해,ValidateDevice 메소드를 호출하는 것으로 확인할 수 있다.

ValidateDevice 메소드는, 현재 설정되어 있는 렌더링 스테이트, 텍스쳐, 텍스쳐 스테이지의 스테이트를 사용해, 불려 간 시점에서의 확인을 행한다. 이 호출의 후에 이러한 요소로 변경이 있으면(자), 지금까지의 확인 결과는 무효가 되므로, 장면의 렌더링을 하기 전에 이 메소드를 재차 호출하지 않으면 안 된다.

디 푸즈 반복값의 사용은, 인수라고 해도 조작이라고 해도 (D3DTA_DIFFUSE 또는 D3DTOP_BLENDDIFFUSEALPHA ), 현재의 하드웨어에서는 보기 드물게 밖에 지원되어 있지 않다. 대부분의 하드웨어에서는, 직전의 텍스쳐 조작 스테이지에 있어서의 컬러 데이터의 반복값을 도입하고 있는 정도이다.

각 스테이지의 텍스쳐 (D3DTA_TEXTURE )는, 가능한 한, 제 2 인수는 아니고 제 1 인수로서 지정한다.

많은 카드는, 임의의 텍스쳐의 스테이지에 있어서의 디 푸즈값이나 스칼라-값의 사용은 지원 하고 있지 않다. 이것들은 최초인가 마지막 텍스쳐의 블렌딩 스테이지에서만 사용할 수 있는 것이 많다.

실제로는 많은 카드는, 알파값을 색채널에 복제하거나 입력을 반전하는 이상가 할 수 있는 것 같은, 최초의 텍스쳐와 관련지을 수 있었던 블렌딩 유니트를 가지고 있지 않다. 그 때문에, 어플리케이션에서는, 할 수 있으면 2 번째의 텍스쳐 스테이지만을 사용하는 것이 필요하게 될지도 모른다. 이러한 하드웨어에서는, 최초의 유니트는 디폴트 스테이트에 있으면(자) 가정되어D3DTOP_SELECTARG1 연산의 제 1 색인수는 D3DTA_TEXTURE 로 설정된다.

색조작에 비해 보다 복잡해 실질적으로도 다른, 출력된 알파값에 대한 조작을 지원 하는 하드웨어는, 한층 더 적다.

몇개의 하드웨어는,D3DTA_TFACTOR 와 D3DTA_DIFFUSE 의 동시 사용을 지원 하지 않는다.

또 많은 카드는, 멀티 텍스쳐와 밉맵 트라이 리니어 필터링의 동시 사용은 지원 하지 않는다. 멀티 텍스쳐의 블렌딩 조작 중(안)에서 텍스쳐를 트라이 리니어 필터링 하는 요구가 있어, 확인이 실패했을 경우는, 트라이 리니어 필터링을 그만두어 재차 확인을 실시한다. 이러한 케이스에서는, 대신에 여러 차례의 렌더링을 하는 것이 최선일 것이다.

참조

Direct3DDevice7.GetTextureStageState ,Direct3DDevice7.SetTextureStageState


Direct3DEnumDevices

어플리케이션은,Direct3DEnumDevices 클래스의 메소드를 사용해, 시스템에 존재하는 Direct3D 디바이스의 정보를 취득한다. Direct3DEnumDevices 클래스는,Direct3D7.GetDevicesEnum 메소드에 의해 취득된다.

Direct3DEnumDevices 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

디바이스의 수 | GetCount
디바이스 정보 | GetDescription
 | GetGuid
 | GetDesc
 | GetName


Direct3DEnumDevices.GetCount

Direct3DEnumDevices.GetCount 메소드는, 시스템에 인스톨 되고 있는 Direct3D 디바이스의 수를 돌려준다.

object. GetCount() As Long

파라미터

object
Direct3DEnumDevices 오브젝트를 나타내는오브젝트식.

반환값

메소드가 성공하면(자), 시스템에 인스톨 되고 있는 Direct3D 디바이스의 수를 돌려준다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 가 설정된다.


Direct3DEnumDevices.GetDesc

Direct3DEnumDevices.GetDesc 메소드는, 요구된 Direct3D 디바이스의 능력을 돌려준다.

object. GetDesc(index As Long, hwDesc As D3DDEVICEDESC7)

파라미터

object
Direct3DEnumDevices 오브젝트를 나타내는오브젝트식.
index
시스템에 복수의 Direct3D 디바이스가 있는 경우, 이 파라미터에 의해 디바이스를 식별한다.
hwDesc
Direct3D 디바이스의 하드웨어 능력을 저장 하는 D3DDEVICEDESC7 형.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 가 설정된다.


Direct3DEnumDevices.GetDescription

Direct3DEnumDevices.GetDescription 메소드는, 요구된 Direct3D 디바이스의 간단한 설명을 돌려준다.

object. GetDescription(index As Long) As String

파라미터

object
Direct3DEnumDevices 오브젝트를 나타내는오브젝트식.
index
열거된 디바이스의 인덱스. 이 값은, 1 으로부터 Direct3DEnumDevices.GetCount 메소드에 의해 돌려주어지는 값의 범위가 된다.

반환값

메소드가 성공하면(자), 열거된 디바이스의 간단한 설명을 돌려준다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 가 설정된다. 설정되는 에러 코드의 리스트에 대해서는, Direct3D 직접 모드의 「에러 코드」를 참조할것.


Direct3DEnumDevices.GetGuid

Direct3DEnumDevices.GetDescription 메소드는, 요구된 Direct3D 디바이스의 글로벌 유니크 식별자 (GUID)를 돌려준다.

object. GetGuid(index As Long) As String

파라미터

object
Direct3DEnumDevices 오브젝트를 나타내는오브젝트식.
index
열거된 디바이스의 인덱스. 이 값은, 1 으로부터 Direct3DEnumDevices.GetCount 메소드에 의해 돌려주어지는 값의 범위가 된다.

반환값

메소드가 성공하면(자), 열거된 디바이스의 글로벌 유니크 식별자를 나타내는 캐릭터 라인 라벨,"IID_IDirect3DHALDevice","IID_IDirect3DTnLHalDevice", 또는 "IID_IDirect3DRGBDevice" 를 돌려준다. 이 값은, 연속하는 Direct3D7.CreateDevice 메소드의 호출에 의해 디바이스를 생성 할 때에 사용된다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 가 설정된다. 설정되는 에러 코드의 리스트에 대해서는, Direct3D 직접 모드의 「에러 코드」를 참조할것.


Direct3DEnumDevices.GetName

Direct3DEnumDevices.GetName 메소드는, 요구된 Direct3D device 디바이스의 이름을 돌려준다.

object. GetName(index As Long) As String

파라미터

object
Direct3DEnumDevices 오브젝트를 나타내는오브젝트식.
index
열거된 디바이스의 인덱스. 이 값은, 1 으로부터 Direct3DEnumDevices.GetCount 메소드에 의해 돌려주어지는 값의 범위가 된다.

반환값

메소드가 성공하면(자), 디바이스의 이름을 돌려준다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 가 설정된다. 설정되는 에러 코드의 리스트에 대해서는, 「Direct3D 직접 모드의 에러 코드」를 참조할것.


Direct3DEnumPixelFormats

어플리케이션은,Direct3DEnumPixelFormats 클래스의 메소드를 사용해, 렌더링 디바이스로 지원 되는 픽셀 포맷에 관한 정보를 취득한다. Direct3DEnumPixelFormats 클래스는,Direct3DDevice7.GetTextureFormatsEnum 및 Direct3D7.GetEnumZBufferFormats 메소드에 의해 취득된다.

이 클래스에는, 다음의 2 개의 메소드가 있다.

  • GetCount
  • GetItem


Direct3DEnumPixelFormats.GetCount

Direct3DEnumPixelFormats.GetCount 메소드는, Direct3D 디바이스로 지원 되는 픽셀 포맷의 수를 돌려준다.

object. GetCount() As Long

파라미터

object
Direct3DEnumPixelFormats 오브젝트를 나타내는오브젝트식.

반환값

메소드가 성공하면(자), 지원 되는 픽셀 포맷의 수를 돌려준다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 가 설정된다.


Direct3DEnumPixelFormats.GetItem

Direct3DEnumPixelFormats.GetItem 메소드는, 지정된 픽셀 포맷의 설명을 돌려준다.

object. GetItem(index As Long, _
    pixelFormat As DDPIXELFORMAT)

파라미터

object
Direct3DEnumPixelFormats 오브젝트를 나타내는오브젝트식.
index
설명을 취득하는 픽셀 포맷.
pixelFormat
열거된 픽셀 포맷을 기술하는 DDPIXELFORMAT 형.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 가 설정된다.


Direct3DVertexBuffer7

어플리케이션은,Direct3DVertexBuffer7 클래스의 메소드를 사용해,Direct3DDevice7.DrawPrimitiveVB 및 Direct3DDevice7.DrawIndexedPrimitiveVB 렌더링 메소드로 이용하는 버텍스의 집합을 조작한다. 여기에서는, 이 클래스의 메소드의 레퍼런스를 제공한다. 개요에 대해서는, 「버텍스 버퍼」를 참조할것.

Direct3DVertexBuffer7 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

정보 | GetVertexBufferDesc
버텍스 데이터 | GetVertices
 | Lock
 | Optimize
 | ProcessVertices
 | SetVertices
 | Unlock

참조

버텍스 버퍼


Direct3DVertexBuffer7.GetVertexBufferDesc

Direct3DVertexBuffer7.GetVertexBufferDesc 메소드는, 버텍스 버퍼의 기술을 취득한다.

object. GetVertexBufferDesc(desc As D3DVERTEXBUFFERDESC)

파라미터

object
Direct3DVertexBuffer7 오브젝트를 나타내는오브젝트식.
desc
버텍스 버퍼의 기술이 저장 되는 D3DVERTEXBUFFERDESC 형.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 DDERR_INVALIDPARAMS 또는 다른 에러 코드가 설정된다.


Direct3DVertexBuffer7.GetVertices

Direct3DVertexBuffer7.GetVertices 메소드는, 버텍스 버퍼내의 버텍스를 돌려준다.

object. GetVertices(startIndex As Long, _
    count As Long, _
    verts As Any)

파라미터

object
Direct3DVertexBuffer7 오브젝트를 나타내는오브젝트식.
startIndex
버텍스 버퍼내에서 버텍스가 취득되는 시작 인덱스.
count
처리되는 버텍스수.
verts
취득된 버텍스가 저장 되는 배열의 최초의 요소.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 가 설정된다.


Direct3DVertexBuffer7.Lock

Direct3DVertexBuffer7.Lock 메소드는, 버텍스 버퍼를 잠근다.

object. Lock(flags As CONST_DDLOCKFLAGS)

파라미터

object
Direct3DVertexBuffer7 오브젝트를 나타내는오브젝트식.
flags
버텍스 버퍼 메모리의 락 방법을 나타내는,CONST_DDLOCKFLAGS 열거의 다음의 정수의 1 개.
DDLOCK_NOSYSLOCK
가능하면, Win16Mutex (Win16Lock 라고도 말한다)는 이용하지 않는다.
DDLOCK_READONLY
락 된 메모리는 읽어내기 전용인 것을 나타낸다.
DDLOCK_WAIT
락을 즉석에서 할 수 없는 경우, 메소드는 잠글 수 없을지, 혹은, 다른 에러가 생길 때까지 리트라이 한다.
DDLOCK_WRITEONLY
락 된 메모리는 쓰기 전용인 것을 나타낸다.
DDLOCK_DISCARDCONTENTS
Direct3D 버텍스 버퍼의 락만으로 사용한다. 락중에 버텍스 버퍼의 내용이 보증되지 않는 것을 나타낸다. 이것에 의해, Direct3D 또는 드라이버가, 다른 메모리 영역을 버텍스 버퍼로서 공급할 수 있다. 버텍스 버퍼의 내용을 클리어 하고 싶은 경우나, 새로운 데이터를 저장 하는 경우에 유효하다.
DDLOCK_NOOVERWRITE
Direct3D 버텍스 버퍼만으로 사용한다. 락중에, 프레임 (또는 이 플래그가 없는 마지막 락)의 초가 수정되고 나서, 버텍스 버퍼의 DrawPrimitive 호출로 버텍스가 참조되어 있지 않은 것을 나타낸다. 버텍스 버퍼에 데이터를 추가할 뿐(만큼)의 경우에 유효하다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

D3DERR_VERTEXBUFFEROPTIMIZED
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACEBUSY
DDERR_SURFACELOST

트래핑 에러에 대해서는, 「Visual Basic 에러 트래핑」을 참조할것.

주의

버텍스 버퍼가 락 되고 있을 때, 버퍼내의 데이터를 조작하려면 ,Direct3DVertexBuffer7.GetVertices 및 Direct3DVertexBuffer7.SetVertices 메소드를 사용한다. 버텍스 버퍼의 락 후, 대응하는 Direct3DVertexBuffer7.Unlock 를 호출할 때까지, 이 메모리에 액세스 할 수가 있다.

버텍스 버퍼가 락 되고 있을 때는 렌더링 할 수 없다. 락 된 버텍스 버퍼를 사용해 Direct3DDevice7.DrawIndexedPrimitiveVB 또는 Direct3DDevice7.DrawPrimitiveVB 메소드를 호출하려고 하면 실패해,D3DERR_VERTEXBUFFERLOCKED 를 돌려준다.

이 메소드는,Direct3DVertexBuffer7.Unlock 메소드를 호출할 때까지, Win16Mutex 를 hold 시키는 것이 자주 있다. GUI 디버거는, Win16Mutex 가 hold 되고 있는 동안은 동작하지 않는다.

참조

Direct3DVertexBuffer7.Unlock ,버텍스 버퍼의 내용에의 액세스


Direct3DVertexBuffer7.Optimize

Direct3DVertexBuffer7.Optimize 메소드는, 최적화되어 있지 않은 버텍스 버퍼가 최적화된 버텍스 버퍼에 트랜스 폼 한다.

object. Optimize(dev As Direct3DDevice7)

파라미터

object
Direct3DVertexBuffer7 오브젝트를 나타내는오브젝트식.
dev
버텍스 버퍼를 최적화하는 디바이스의 Direct3DDevice7 오브젝트.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

D3DERR_VERTEXBUFFEROPTIMIZED
D3DERR_VERTEXBUFFERLOCKED
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

트래핑 에러에 대해서는, 「Visual Basic 에러 트래핑」을 참조할것.

참조

버텍스 버퍼의 최적화,버텍스 버퍼


Direct3DVertexBuffer7.ProcessVertices

Direct3DVertexBuffer7.ProcessVertices 메소드는, 트랜스 폼되어 있지 않은 버텍스를 처리해, 트랜스 폼 끝나 또는 최적화된 버텍스 버퍼에 넣는다.

object. ProcessVertices( _
    vertexOp As CONST_D3DVOPFLAGS, _
    destIndex As Long, _
    count As Long, _
    srcBuffer As Direct3DVertexBuffer7, _
    srcIndex As Long, _
    dev As Direct3DDevice7, _
    flags As CONST_D3DPROCESSVERTICESFLAGS)

파라미터

object
Direct3DVertexBuffer7 오브젝트를 나타내는오브젝트식.
vertexOp
원의 버퍼로부터 전송 된 버텍스를 메소드가 처리하는 방법을 정의하는 플래그. CONST_D3DVOPFLAGS 열거의 정수의 임의의 편성을 지정할 수가 있다.
destIndex
처리한 후, 버텍스를 두는 앞의 버텍스 버퍼 (이 버퍼)에의 인덱스.
count
원의 버퍼에 있는, 처리하는 버텍스의 수.
srcBuffer
원의 버텍스 버퍼의 Direct3DVertexBuffer7 오브젝트.
srcIndex
원의 버텍스 버퍼에 있는, 처리하는 버텍스 가운데, 최초의 버텍스의 인덱스
dev
버텍스를 트랜스 폼 하는데 사용하는 디바이스의 Direct3DDevice7 오브젝트.
flags
처리 옵션. 이 파라미터는,CONST_D3DPROCESSVERTICESFLAGS 열거의 멤버의 1 개로 설정한다.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

D3DERR_INVALIDVERTEXFORMAT
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACEBUSY
DDERR_SURFACELOST

트래핑 에러에 대해서는, 「Visual Basic 에러 트래핑」을 참조할것.

주의

vertexOp 파라미터에는, 항상 D3DVOP_TRANSFORMED 플래그를 포함하는 것. 이 플래그를 포함하지 않으면 메소드는 실패해,DDERR_INVALIDPARAMS 를 돌려준다.

참조

버텍스의 처리,버텍스 버퍼


Direct3DVertexBuffer7.SetVertices

Direct3DVertexBuffer7.SetVertices 메소드는, 락 된 버텍스 버퍼내의 버텍스를 설정한다.

object. SetVertices(startIndex As Long, _
    count As Long, _
    verts As Any)

파라미터

object
Direct3DVertexBuffer7 오브젝트를 나타내는오브젝트식.
startIndex
버텍스를 설정하는 버텍스 버퍼내의 제로 베이스의 인덱스.
count
verts 배열에 포함되는 버텍스의 수.
verts
버텍스 데이터를 저장 하는 버퍼의 최초의 요소.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 에러 코드가 설정된다. Direct3D 직접 모드의 에러 코드와 그 설명에 대해서는, 「에러 코드」를 참조할것.

주의

버텍스 버퍼내의 버텍스를 조작하기 전에,Direct3DVertexBuffer7.Lock 메소드를 호출해 버텍스 버퍼를 잠그지 않으면 안 된다.

참조

Direct3DVertexBuffer7.GetVertices ,Direct3DVertexBuffer7.Lock


Direct3DVertexBuffer7.Unlock

Direct3DVertexBuffer7.Unlock 메소드는, 버텍스 버퍼의 락을 해제한다.

object. Unlock()

파라미터

object
Direct3DVertexBuffer7 오브젝트를 나타내는오브젝트식.

에러 코드

메소드가 실패 하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACEBUSY
DDERR_SURFACELOST

트래핑 에러에 대해서는, 「Visual Basic 에러 트래핑」을 참조할것.

참조

Direct3DVertexBuffer7.Lock ,버텍스 버퍼의 내용에의 액세스


형

여기에서는, Direct3D 직접 모드로 사용하는 이하의 형태에 대해 설명한다.

  • D3DCLIPSTATUS
  • D3DCOLORVALUE
  • D3DDEVICEDESC7
  • D3DDEVINFO_TEXTUREMANAGER
  • D3DDEVINFO_TEXTURING
  • D3DLIGHT7
  • D3DLINEPATTERN
  • D3DLVERTEX
  • D3DMATERIAL7
  • D3DMATRIX
  • D3DPRIMCAPS
  • D3DRECT
  • D3DTLVERTEX
  • D3DVECTOR
  • D3DVERTEX
  • D3DVERTEXBUFFERDESC
  • D3DVIEWPORT2


D3DCLIPSTATUS

D3DCLIPSTATUS 형은, 현재의 클립 스테이터스 및 클립 영역의 extent를 기술한다.

Type D3DCLIPSTATUS
    lFlags As Long
    lStatus As Long
    maxx As Single
    maxy As Single
    maxz As Single
    minx As Single
    miny As Single
    minz As Single
End Type

멤버

lFlags
이 형태가 2D 영역, 3D 영역, 또는 클립 스테이터스를 기술할지 어떨지를 나타내는 플래그. 이 멤버는,CONST_D3DCLIPSTATUSFLAGS 열거의 이하의 플래그의 편성으로 할 수 있다.
D3DCLIPSTATUS_STATUS
형태는 현재의 클립 스테이터스를 기술한다.
D3DCLIPSTATUS_EXTENTS2
형태는 현재의 2D 영역을 기술한다. 이 플래그는 D3DCLIPSTATUS_EXTENTS3 과 조합할 수 없다.
D3DCLIPSTATUS_EXTENTS3
현재는 이행되어 있지 않다.
lStatus
현재의 클립 스테이터스를 기술한다. 이 멤버는,CONST_D3DCLIPFLAGS 열거의 다음의 정수의 1 개 이상으로 할 수 있다.

편성과 일반 플래그

D3DSTATUS_CLIPINTERSECTIONALL
모든 CLIPINTERSECTION 플래그의 편성.
D3DSTATUS_CLIPUNIONALL
모든 CLIPUNION 플래그의 편성.
D3DSTATUS_DEFAULT
D3DSTATUS_CLIPINTERSECTIONALL 와 D3DSTATUS_ZNOTVISIBLE 플래그의 편성. 이 값이, 디폴트이다.
D3DSTATUS_ZNOTVISIBLE
렌더링 된 프리미티브가 불가시인 것을 나타낸다. 이 플래그는, z 체크를 사용하는 렌더링이 유효화 된 시점에서, 시스템에 의해 세트, 또는 클리어 된다 (D3DRENDERSTATE_ZVISIBLE 참조).

클립 교차 플래그

D3DSTATUS_CLIPINTERSECTIONBACK
절두체의후방 클립면과 비교해, 버텍스의 클리핑 플래그의 논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONBOTTOM
절두체아래와 비교해, 버텍스의 클리핑 플래그의 논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONFRONT
절두체의전방 클립면과 비교해, 버텍스의 클리핑 플래그의 논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONGEN0 through D3DSTATUS_CLIPINTERSECTIONGEN5
어플리케이션 정의의 클립면의 클리핑 플래그의 논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONLEFT
절두체의 좌측면과 비교해, 버텍스의 클리핑 플래그의 논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONRIGHT
절두체의 우측면과 비교해, 버텍스의 클리핑 플래그의 논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONTOP
절두체 위와 비교해, 버텍스의 클리핑 플래그의 논리츠무를 잡는다.

클립 결합 플래그

D3DSTATUS_CLIPUNIONBACK
D3DCLIP_BACK 와 같다.
D3DSTATUS_CLIPUNIONBOTTOM
D3DCLIP_BOTTOM 와 같다.
D3DSTATUS_CLIPUNIONFRONT
D3DCLIP_FRONT 와 같다.
D3DSTATUS_CLIPUNIONGEN0 through D3DSTATUS_CLIPUNIONGEN5
D3DCLIP_GEN0 로부터 D3DCLIP_GEN5 와 같다.
D3DSTATUS_CLIPUNIONLEFT
D3DCLIP_LEFT 와 같다.
D3DSTATUS_CLIPUNIONRIGHT
D3DCLIP_RIGHT 와 같다.
D3DSTATUS_CLIPUNIONTOP
D3DCLIP_TOP 와 같다.

기본 클리핑 플래그

D3DCLIP_BACK
모든 버텍스를절두체의 뒷면에서 클리핑 한다.
D3DCLIP_BOTTOM
모든 버텍스를 절두체의 저면에서 클리핑 한다.
D3DCLIP_FRONT
모든 버텍스를 절두체의 전면에서 클리핑 한다.
D3DCLIP_LEFT
모든 버텍스를 절두체의 좌측면에서 클리핑 한다.
D3DCLIP_RIGHT
모든 버텍스를 절두체의 우측면에서 클리핑 한다.
D3DCLIP_TOP
모든 버텍스를 절두체의 표면에서 클리핑 한다.
D3DCLIP_GEN0 through D3DCLIP_GEN5
어플리케이션 정의의 클립면.
maxx, minx, maxy, miny, maxz, minz
현재의 클립 영역의 X, Y, Z 의 범위.

참조

Direct3DDevice7.GetClipStatus ,Direct3DDevice7.SetClipStatus


D3DCOLORVALUE

D3DCOLORVALUE 형은,D3DLIGHT7 와 D3DMATERIAL7 형의 컬러값을 기술한다.

Type D3DCOLORVALUE
    a As Single
    b As Single
    g As Single
    r As Single
End Type

멤버

a,b,g 및 r
색의 적 (red), 록 (green), 청 (blue), 및 알파 (alpha)의 요소를 나타내는 값. 이러한 값은 일반적으로 0 에서 1 의 범위에 분포해, 0 은 흑이다.

주의

무엇인가 바뀐 이펙트를 포함시키기 위해서(때문에), 이 형태의 멤버의 값을 0 에서 1 의 범위의 밖으로 설정할 수도 있다. 1 보다 큰 값은, 신을 조사해 흘리는 것 같은 강한 빛을 낳는다. 마이너스의 값은 어두운 빛을 낳아, 실제로는 빛을 장면으로부터 제외해 버린다. 상세한 것에 대하여는, 「컬러 라이팅」을 참조.


D3DDEVICEDESC7

D3DDEVICEDESC7 형에는, 현재의 디바이스에 관한 설명이 저장 된다. 이 형태는,Direct3DDevice7.GetCaps 등의 메소드로 현재의 디바이스를 조회하기 위해서 사용된다.

Type D3DDeviceDesc7
    dpcLineCaps As D3DPRIMCAPS
    dpcTriCaps As D3DPRIMCAPS
    dvExtentsAdjust As Single
    dvGuardBandBottom As Single
    dvGuardBandLeft As Single
    dvGuardBandRight As Single
    dvGuardBandTop As Single
    dvMaxVertexW As Single
    lDevCaps As CONST_D3DDEVICEDESCCAPS
    lDeviceRenderBitDepth As Long
    lDeviceZBufferBitDepth As Long
    lFVFCaps As CONST_D3DFVFCAPSFLAGS
    lMaxActiveLights As Long
    lMaxAnisotropy As Long
    lMaxTextureAspectRatio As Long
    lMaxTextureHeight As Long
    lMaxTextureRepeat As Long
    lMaxTextureWidth As Long
    lMinTextureHeight As Long
    lMinTextureWidth As Long
    lStencilCaps As CONST_D3DSTENCILCAPSFLAGS
    lTextureOpCaps As CONST_D3DTEXOPCAPSFLAGS
    lVertexProcessingCaps As CONST_D3DVTXPCAPS
    nMaxSimultaneousTextures As Integer
    nMaxTextureBlendStages As Integer
    nMaxUserClipPlanes As Integer
    nMaxVertexBlendMatrices As Integer
End Type

멤버

dpcLineCaps 및 dpcTriCaps
선이나 삼각형을 드로잉(Drawing) 하기 위한(해), 디바이스의 지원 정보를 정의하는 D3DPRIMCAPS 형.
dvExtentsAdjust
직사각형의 외변을 에일리어징 제거 커널에 적합시키기 위한 픽셀수.
dvGuardBandBottom,dvGuardBandLeft,dvGuardBandTop 및 dvGuardBandRight
가이드 밴드 클리핑 영역의 화면 공간 좌표. 이 좌표로 지정되는 직사각형내에 있어, 한편, 뷰포트를 나타내는 직사각형의 외측에 위치하는 좌표는 클리핑 된다.
dvMaxVertexW
디바이스가 지원 하는 W 준거 깊이의 최대치.
lDevCaps
디바이스의 능력을 나타내는 CONST_D3DDEVICEDESCCAPS 열거의 정수의 1 개.
lDeviceRenderBitDepth
디바이스의 렌더링 비트 깊이. CONST_DDBITDEPTHFLAGS 열거의 다음의 정수 DDBD_8, DDBD_16, DDBD_24, DDBD_32 가운데, 1 개 이상을 설정할 수 있다.
lDeviceZBufferBitDepth
디바이스의 깊이 버퍼 비트 깊이. CONST_DDBITDEPTHFLAGS 열거의 다음의 정수 DDBD_8, DDBD_16, DDBD_24, DDBD_32 가운데, 1 개 이상을 설정할 수 있다.
lFVFCaps
이 디바이스에 의해 지원 되는 버텍스 포맷을 나타내는 CONST_D3DFVFCAPSFLAGS 의 정수의 편성.
lMaxActiveLights
동시에 액티브하게 할 수가 있는 라이트의 최대수.
lMaxAnisotropy
D3DTSS_MAXANISOTROPY 텍스쳐 스테이지 스테이트의 최대 유효값.
lMaxTextureAspectRatio
하드웨어가 지원 하는 텍스쳐의 최대 어스펙트비(가로세로 비율). 보통은 2 말하고 나무승의 값을 취한다.
lMaxTextureWidth,lMaxTextureHeight
이 디바이스의 텍스쳐의 최대의 폭과 높이.
lMaxTextureRepeat
정규화된 후의 텍스쳐 인덱스의 정수부 (소수점 이하를 포함하지 않는다) 비트의 전범위. D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE 플래그가 세트 되면(자), 텍스쳐 주소 모드가 적용될 때까지, 디바이스는 텍스쳐 사이즈에 맞추어 텍스쳐 인덱스의 스케일링을 실시하는 것을 연기한다. 이 비트가 세트 되지 않는 경우는, 디바이스는 보간의 전에, 텍스쳐 사이즈 (상세 레벨 최대치)에 따라 텍스쳐 인덱스의 스케일링을 실행한다.
lMinTextureWidth,lMinTextureHeight
이 디바이스의 텍스쳐의 최소의 폭과 높이.
lStencilCaps
지원 되는 스텐실 버퍼 조작을 나타내는 CONST_D3DSTENCILCAPSFLAGS 열거의 정수. 스텐실 조작은 3 종류의 스텐실 버퍼 조작 렌더링 스테이트 (D3DRENDERSTATE_STENCILFAIL, D3DRENDERSTATE_STENCILPASS, D3DRENDERSTATE_STENCILFAILZFAIL)에 대해서는, 모두 유효하다라고 보인다.
lTextureOpCaps
디바이스에 의해 지원 되는 텍스쳐 조작을 기술하는 CONST_D3DTEXOPCAPSFLAGS 열거의 정수의 편성.
lVertexProcessingCaps
버텍스의 처리 능력을 나타내는 CONST_D3DVTXPCAPS 열거의 정수의 편성.
nMaxSimultaneousTextures
디바이스의 텍스쳐 블렌딩 스테이지에 동시에 바인드 가능한 텍스쳐의 최대수. 「주의」를 참조할것.
nMaxTextureBlendStages
디바이스가 지원 하는 텍스쳐 블렌딩 스테이지의 최대수.
nMaxUserClipPlanes
지원 되는 유저 정의 클립면의 최대수. 0 에서 31 의 범위가 된다.

유저 정의 클립면은,Direct3DDevice7.GetClipPlane 및 Direct3DDevice7.SetClipPlane 메소드를 사용해 조작된다.

nMaxVertexBlendMatrices
지오메트리 블렌딩의 실행시에 디바이스가 적용 가능한 행렬의 최대수.

주의

멤버 wMaxTextureBlendStages 와 wMaxSimultaneousTextures 는 언뜻 보았는데 매우 자주(잘) 비슷하지만, 포함하고 있는 정보는 다르다. 멤버 wMaxTextureBlendStages 가 현재의 디바이스가 지원 하는 텍스쳐 블렌딩 스테이지의 총수를 나타내는데 대해, 멤버 wMaxSimultaneousTextures 는, 이러한 스테이지중 몇개가 Direct3DDevice7.SetTexture 메소드를 사용해 텍스쳐를 바인드 할 수 있는지를 나타낸다.

참조

CONST_D3DCOLORMODEL ,D3DPRIMCAPS


D3DDEVINFO_TEXTUREMANAGER

텍스쳐 매니저의 현재의 스테이트에 관한 정보를 저장 하는 D3DDEVINFO_TEXTUREMANAGER 형. 이 형태는,Direct3DDevice7.GetInfo 메소드로 사용된다.

Type D3DDEVINFO_TEXTUREMANAGER
    bThrashing As Boolean
    lLastPri As Long
    lNumEvicts As Long
    lNumTexturesUsed As Long
    lNumUsedTexInVid As Long
    lNumVidCreates As Long
    lTotalBytes As Long
    lTotalManaged As Long
    lWorkingSet As Long
    lWorkingSetBytes As Long
End Type

멤버

bThrashing
쓰레싱 상태. 마지막 프레임으로 쓰레싱이 발생했을 경우는 TRUE, 발생하지 않았던 경우는 FALSE 가 된다.
lLastPri
마지막에 삭제하는 텍스쳐의 우선 순위.
lNumEvicts
마지막 프레임으로 삭제된 텍스쳐의 수.
lNumTexturesUsed
마지막 프레임으로 사용된 텍스쳐의 총수.
lNumUsedTexInVid
마지막 프레임으로 사용 될 수 있던 비디오 메모리 텍스쳐의 수.
lNumVidCreates
마지막 프레임으로 비디오 메모리에 생성 된 텍스쳐의 수.
lTotalBytes
관리하의 텍스쳐에 할당할 수 있었던 총바이트수.
lTotalManaged
관리하의 텍스쳐의 총수.
lWorkingSet
비디오 메모리에 현재 존재하는 텍스쳐의 수.
lWorkingSetBytes
비디오 메모리에 존재하는 텍스쳐에 현재 할당할 수 있고 있는 바이트수.

주의

lNumUsedTexInVid 및 lNumTexturesUsed 의 값을 사용해, 마지막 프레임으로 비디오 메모리 (로컬 또는 비로컬)에 존재하는 텍스쳐가 사용된 비율 (퍼센트)을 확인할 수 있다. 다음의 코드는, 이 비율의 계산방법을 나타낸다.

'이 예에서는, d3dtminfo 변수는, Direct3DDevice7.GetInfo 메소드에 의해 파묻힌다
' D3DDEVINFO_TEXTUREMANAGER 구조체가 된다.
Dim lHitRate As Long

'비디오 메모리에 존재하는 텍스쳐가 사용된 퍼센트를 취득한다.
lHitRate = (d3dtminfo.lNumUsedTexInVid * 100) / d3dtminfo.lNumTexturesUsed

참조

Direct3DDevice7.GetInfo


D3DDEVINFO_TEXTURING

D3DDEVINFO_TEXTURING 형은, 어플리케이션의 텍스쳐링 액티버티에 관한 정보를 저장 한다. 이 형태는,Direct3DDevice7.GetInfo 메소드로 사용된다.

Type D3DDEVINFO_TEXTURING
  lApproxBytesLoaded As Long
  lNumCreates As Long
  lNumDestroys As Long
  lNumGetDCs As Long
  lNumLoads As Long
  lNumLocks As Long
  lNumPreLoads As Long
  lNumSet As Long
  lNumSetLODs As Long
  lNumSetPriorities As Long
End Type

멤버

lApproxBytesLoaded
Direct3DDevice7.Load 메소드에 의해 로드 되는 바이트수 (개수).
lNumCreates
어플리케이션에 의해 생성 되는 텍스쳐의 수.
lNumDestroys
어플리케이션에 의해 파기 (릴리즈)되는 텍스쳐의 수.
lNumGetDCs
DirectDrawSurface7.GetDC 메소드에 의해 텍스쳐 표면의 디바이스 콘텍스트가 취득된 회수.
lNumLoads
Direct3DDevice7.Load 메소드에 의해 텍스쳐가 로드 된 회수.
lNumLocks
DirectDrawSurface7.Lock 메소드에 의해 텍스쳐 표면이 락 된 회수.
lNumPreLoads
Direct3DDevice7.PreLoad 메소드에 의해 관리하의 텍스쳐가 명시적으로 로드 된 회수.
lNumSet
Direct3DDevice7.SetTexture 메소드에 의해 텍스쳐 블렌딩 스테이지에 텍스쳐가 설정된 회수.
lNumSetLODs
DirectDrawSurface7.SetLOD 메소드에 의해 최대 밉맵 상세 레벨이 설정된 회수.
lNumSetPriorities
DirectDrawSurface7.SetPriority 메소드에 의해 텍스쳐 관리 우선 순위가 설정된 회수.

참조

Direct3DDevice7.GetInfo


D3DLIGHT7

D3DLIGHT7 형은,Direct3DDevice7.SetLight 및 Direct3DDevice7.GetLight 등의 메소드를 호출하기 위한, 광원형을 결정한다.

Type D3DLIGHT7
    ambient As D3DCOLORVALUE
    attenuation0 As Single
    attenuation1 As Single
    attenuation2 As Single
    diffuse As D3DCOLORVALUE
    direction As D3DVECTOR
    dltType As CONST_D3DLIGHTTYPE
    falloff As Single
    phi As Single
    position As D3DVECTOR
    range As Single
    specular As D3DCOLORVALUE
    theta As Single
End Type

멤버

ambient
빛에 의해 방사되는 앰비언트색. 이 멤버는,D3DCOLORVALUE 형이다.
attenuation0,attenuation1 및 attenuation2
거리에 의한 빛의 휘도(Luminance)의 변화를 지정하는 값 (디렉셔널 라이트는 감쇠에는 영향을 받지 않는다). 이러한 감쇠 계수에 의해 빛이 어떻게 영향을 받을까에 대해서는, 「거리의 증가에 의한 라이트의 감쇠」를 참조할것. 이러한 멤버의 유효값은, 0.0 이상이다.
diffuse
빛에 의해 방사되는 디퓨즈색. 이 멤버는,D3DCOLORVALUE 형이다.
direction
월드 공간에서의 광원의 범위. 이 멤버는, 디렉셔널 라이트 및 spotlight의 경우에게만 의미를 가진다. 이 벡터는 정규화할 필요는 없지만, 제로가 아닌 길이를 가지지 않으면 안 된다.
dltType
광원의 형태. 이 값은, 다음의 CONST_D3DLIGHTTYPE 열거의 멤버의 1 개가 된다.
falloff
spotlight중원추 (theta 멤버로 지정되는 각도)와 밖원추의 외측선 (phi 멤버로 지정되는 각도)의 사이에 휘도(Luminance)가 감소한다. spotlight가 falloff 의 값에 의해 어떻게 영향을 받을까에 대한 자세한 것은, 「spotlight 폴 오프 모델」을 참조할것.

라이팅에 대한 폴 오프의 영향은 미묘하다. 게다가 폴 오프 곡선을 그리면(자) 다소의 성능 위에의 로스를 입는다. 이러한 이유에 의해, 많은 개발자는 이 값을 0 에 세트 한다.

phi
spotlight의 밖원추의 외측의 엣지를 정의하는 각도를 라디안 단위로 나타낸다. 이 원추의 외측에 있는 점은 spotlight로 라이팅 되지 않는다. 이 값은 0 으로부터 pi 의 범위에 없으면 안 된다.
position
월드 공간에서의 광원의 위치. 이 멤버는, 디렉셔널 라이트에 있어 의미가 없고, 이 케이스에서는 무시된다.
range
광원의 유효 거리. 이 멤버의 최대 허용값은 D3DLIGHT_RANGE_MAX 로, FLT_MAX 의 제곱근으로서 정의된다. 이 멤버는 디렉셔널 라이트에게는 영향을 주지 않는다.
specular
빛에 의해 방사되는 스펙큐러색. 이 멤버는,D3DCOLORVALUE 형이다.
theta
spotlight중원추를 라디안 단위로 나타낸다. 즉, spotlight가 명료하게 비추는 원추이다. 이 값은 0 으로부터,phi 멤버로 지정되는 값의 범위에 없으면 안 된다.

주의

라이팅에 관한 자세한 정보에 대해서는, 「라이트」를 참조할것.


D3DLINEPATTERN

D3DLINEPATTERN 형은, 직선 패턴을 나타낸다. 이러한 값은,CONST_D3DRENDERSTATETYPE 열거에서의 D3DRENDERSTATE_LINEPATTERN 렌더링 스테이트에 의해 사용된다.

Type D3DLINEPATTERN
    linePattern Long
    repeatFactor As Long
End Type

멤버

linePattern
라인 패턴을 지정하는 비트. 예를 들어, 값 1100110011001100 은, 닷 라인을 생성한다. 1100110011001100.
repeatFactor
linePattern 멤버로 지정되고 있는 1 의 연속과 0 의 연속을 반복하는 회수. 이 반복 팩터는, 어플리케이션에 라인 패턴을 「늘린다」일을 가능하게 한다.

주의

선패턴은 선의 그리는 방법을 지정한다. 선패턴은 그려내는 시점의 위치에 관계없이 항상 같다 (이것은 오브젝트를 어떻게 렌더링 하는지, 즉 어떻게 투명도를 모의 할까에 영향을 주는 점묘와 다른 점이다).

선패턴은, 선에 따라, 온/오프 하는 픽셀의 16 픽셀의 패턴을 지정한다. repeatFactor 멤버로 linePattern 에 넣을 때의 픽셀의 반복수를 지정한다.


D3DLVERTEX

D3DLVERTEX 형은, 「트랜스폼 되지 않은 라이팅 끝난 버텍스」 (색첨부의모델 좌표)을 정의한다. 어플리케이션은, Direct3D 가 버텍스 트랜스 폼을 처리하는 경우, 이 형태를 사용할 필요가 있다. 이 형태는, 소프트웨어 라이트가 설정하는 데이터와 색만을 저장 한다.

Type D3DLVERTEX
    color As Long
    specular As Long
    tu As Single
    tv As Single
    x As Single
    y As Single
    z As Single
End Type

멤버

color 및 specular
버텍스의 색과 스펙큐러 성분을 지정하는 값.
tu 및 tv
버텍스의텍스쳐 좌표 를 지정하는 값.
x,y 및 z
버텍스의 모델 좌표를 지정하는 값.

주의

D3DRENDERSTATE_SPECULARENABLE 가 TRUE 의 경우, 텍스쳐 cascade 후, 알파 블렌딩전에, 베이스 컬러에 스펙큐러 성분이 추가된다. 다만, DirectX 7.0 에서는, D3DTA_SPECULAR 플래그를 세트 하는 것으로써, 텍스쳐색의 처리시에 적용하는 스펙큐러 성분을 할당할 수가 있다. 한층 더 상세한 정보에 대해서는, 「텍스쳐 인수 플래그」를 참조할것.

참조

D3DTLVERTEX ,D3DVERTEX


D3DMATERIAL7

D3DMATERIAL7 형은,Direct3DDevice7.GetMaterial 및 Direct3DDevice7.SetMaterial 메소드의 호출로, 머트리얼 프로퍼티를 지정한다.

Type D3DMATERIAL7
    ambient As D3DCOLORVALUE
    diffuse As D3DCOLORVALUE
    emissive As D3DCOLORVALUE
    power As Single
    specular As D3DCOLORVALUE
End Type

멤버

ambient,diffuse,emissive 및 specular
각각, 머트리얼의 앰비언트색, 디퓨즈색, 에미션(emission)색, 스펙큐러색을 지정하는 값. 이러한 값은,D3DCOLORVALUE 형이다.
power
스펙큐러 하이라이트의 선명도를 지정하는 값.

주의

머트리얼을 위한 스펙큐러 하이라이트를 멈추려면 ,Power 멤버를 0 에 세트 한다. 스펙큐러색성분의 설정을 0 으로 하는 것 만으로는 충분하지 않다.

참조

Direct3DDevice7.GetMaterial ,Direct3DDevice7.SetMaterial


D3DMATRIX

D3DMATRIX 형은,Direct3DDevice7.MultiplyTransform ,Direct3DDevice7.GetTransform , 및 Direct3DDevice7.SetTransform 등이 같은 메소드를 위한 행렬을 나타낸다.

Type D3DMATRIX
    rc11 As Single
    rc12 As Single
    rc13 As Single
    rc14 As Single
    rc21 As Single
    rc22 As Single
    rc23 As Single
    rc24 As Single
    rc31 As Single
    rc32 As Single
    rc33 As Single
    rc34 As Single
    rc41 As Single
    rc42 As Single
    rc43 As Single
    rc44 As Single
End Type

주의

Direct3D 에서는, 투영 행렬의 rc34 요소는 부로 할 수 없다. 유저의 어플리케이션이, 그 위치에서 부의 값을 사용할 필요가 있는 경우에는, 대신에 투영 행렬 전체를 -1 로 기준화할 필요가 있다.

참조

Direct3DDevice7.MultiplyTransform ,Direct3DDevice7.GetTransform ,Direct3DDevice7.SetTransform


D3DPRIMCAPS

D3DPRIMCAPS 형은, 각각의 프리미티브형의 능력을 정의한다. 디바이스의 생성시나 디바이스의 능력을 취득할 경우에 사용된다. 이 형태는,D3DDEVICEDESC7 형안의 몇개의 멤버를 정의한다.

Type D3DPrimCaps
    lAlphaCmpCaps As CONST_D3DCAPSCMP
    lDestBlendCaps As CONST_D3DCAPSBLEND
    lMiscCaps As CONST_D3DCAPSMISC
    lRasterCaps As CONST_D3DCAPSRASTER
    lReserved1 As Long
    lShadeCaps As CONST_D3DCAPSSHADE
    lSrcBlendCaps As CONST_D3DCAPSBLEND
    lStippleHeight As Long
    lStippleWidth As Long
    lTextureAddressCaps As CONST_D3DCAPSTEXTUREADDRESS
    lTextureCaps As CONST_D3DCAPSTEXTURE
    lTextureFilterCaps As CONST_D3DCAPSTEXTUREFILTER
    lZCmpCaps As CONST_D3DCAPSCMP
End Type

멤버

lAlphaCmpCaps
드라이버가 실행 가능한 알파 테스트 비교 함수. 이 멤버가 D3DPCMPCAPS_ALWAYS 능력만, 또는 D3DPCMPCAPS_NEVER 능력밖에 가지고 있지 않은 경우, 드라이버는 알파 테스트를 지원 하지 않는다. 그 이외의 경우, 이 플래그에 의해, 알파 테스트를 지원 하는 각각의 비교를 지정한다. 이 멤버는,CONST_D3DCAPSCMP 열거의 정수의 1 개 이상으로 할 수 있다.
lDestBlendCaps
목적지 블렌딩 능력을 기술하는 CONST_D3DCAPSBLEND 열거의 값의 편성.
lMiscCaps
이 프리미티브의 총체적인 능력. 이 멤버는,CONST_D3DCAPSMISC 열거의 값의 1 개 이상으로 할 수 있다.
lRasterCaps
라스터 드로잉(Drawing)의 능력 정보. 이 멤버는,CONST_D3DCAPSRASTER 열거의 정수의 1 개 이상으로 할 수 있다.
lReserved1
예약이 끝난 상태. 사용 불가.
lShadeCaps
디바이스를 실행할 수 있는 쉐이딩 처리. 일반적으로, 디바이스가 주어진 커멘드 (D3DOP_TRIANGLE 와 같은)를 실행할 수 있는 경우는, D3DSHADE_FLAT 모드 (CONST_D3DSHADEMODE 열거형으로 지정되는 것 같은)를 지원 한다. 이 플래그는, gouraud shading와 폰 쉐이딩을 지원 하는 드라이버나, 3 개의 컬러 생성 모드에 각각 지원 되는알파색을 지정한다. 알파 성분이 주어진 모드로 지원 되지 않는 경우, 그 모드로 생성된 색의 알파값은 반드시 255 가 된다. 이 수치가, 알파의 최대치 (알파가 최강)이다.

삼각형의 색, 스펙큐러 하이라이트, 포그(안개:fog), 및 알파 성분에는, 각각 능력 플래그가 있어, 어플리케이션은, 그 플래그를 사용해, 디바이스 드라이버가 그것들을 어떻게 이행 하고 있을까를 알 수 있다. 이 플래그는, 쉐이딩 모드, 컬러 모델, 혹은 색의 알파 성분이 혼합될지도 깔고는 점묘 될까에 의해 변경된다. 상세한 것에 대하여는, 「3D 프리미티브」를 참조할것.

이 멤버는,CONST_D3DCAPSSHADE 열거의 정수의 1 개 이상으로 할 수 있다.

lSrcBlendCaps
전송원블렌딩 능력. 이 멤버는, 목적지 블렌딩 능력을 기술하는 CONST_D3DCAPSBLEND 열거의 값의 편성으로 할 수 있다.
lStippleWidth 및 lStippleHeight
지원 된 점묘의 최대폭과 높이 (최고 32 × 32 까지).
lTextureAddressCaps
텍스쳐의 주소 능력. 이 멤버는,CONST_D3DCAPSTEXTUREADDRESS 열거의 정수의 1 개 이상으로 할 수 있다.
lTextureCaps
혼합 텍스쳐 맵핑 능력. 이 멤버는,CONST_D3DCAPSTEXTURE 열거의 정수의 1 개 이상으로 할 수 있다.
lTextureFilterCaps
텍스쳐 맵의 필터링 능력. 일반 텍스쳐 필터링 플래그는,D3DTSS_MAGFILTER ,D3DTSS_MINFILTER , 또는 D3DTSS_MIPFILTER 텍스쳐 스테이지 스테이트에 대해서, 어느 텍스쳐 필터링 모드가 지원 되어 설정 가능한가를 반영한다. 이 멤버는,CONST_D3DCAPSTEXTUREFILTER 열거의 일반 및 스테이지 단위 텍스쳐 필터링 정수의 임의의 편성으로 할 수 있다.
lZCmpCaps
드라이버가 실행 가능한 함수를 비교하는 Z 버퍼. 이 멤버는,lAlphaCmpCaps 멤버로 정의된 CONST_D3DCAPSCMP 와 같은 정수를 포함할 수가 있다.


D3DRECT

D3DRECT 형은, 직사각형의 정의이다.

Type D3DRECT {
    x1 As Long
    x2 As Long
    y1 As Long
    y2 As Long
End Type

멤버

x1 및 y1
직사각형의 좌상구석의 좌표.
x2 및 y2
직사각형의 우하구석의 좌표.

참조

Direct3DDevice7.Clear


D3DTLVERTEX

D3DTLVERTEX 형은, 「트랜스 폼이 끝난 라이팅 끝난 버텍스」 (색정보첨부 화면 좌표)을 정의한다.

Type D3DTLVERTEX
    color As Long
    rhw As Single
    specular As Long
    sx As Single
    sy As Single
    sz As Single
    tu As Single
    tv As Single
End Type

멤버

color 및 specular
버텍스의 색 및 스펙큐러 성분을 기술하는 값.
rhw
동차 좌표 (x, y, z, w)의 동차 w 의 역수. 이 값은, 원점으로부터 오브젝트까지의 z 축으로 따른 거리로 1 을 나눗셈 한 값에 자주 일치한다.
sx,sy 및 sz
버텍스를 화면 좌표로 가리키는 값. 표시되는 z 값의 범위내에 버텍스를 두기 위해서(때문에)는,SZ 가 취할 수 있는 최대치는 1,0 까지이다.
tu 및 tv
버텍스의텍스쳐 좌표를 나타내는 값.

주의

D3DRENDERSTATE_SPECULARENABLE 가 True 의 경우, 텍스쳐 cascade 후, 알파 블렌딩전에, 베이스 컬러에 스펙큐러 성분이 추가된다. 다만, DirectX 7.0 에서는, D3DTA_SPECULAR 플래그를 세트 하는 것으로써, 텍스쳐색처리시에 적용하는 스펙큐러 성분을 할당할 수가 있다. 상세한 것에 대하여는, 「텍스쳐 인수 플래그」를 참조할것.

참조

D3DLVERTEX ,D3DVERTEX


D3DVECTOR

D3DVECTOR 형은, 많은 Direct3D 메소드와 타입의 벡터를 정의한다.

Type D3DVECTOR
    x As Single
    y As Single
    z As Single
End Type

멤버

x,y 및 z
벡터를 지정하는 값.

참조

D3DLIGHT7


D3DVERTEX

D3DVERTEX 형은, 「트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스」를 정의한다 (정규 방향 벡터에서의모델 좌표).

Type D3DVERTEX
    nx As Single
    ny As Single
    nz As Single
    tu As Single
    tv As Single
    x As Single
    y As Single
    z As Single
End Type

멤버

x,y 및 z
버텍스의 동차 좌표를 지정하는 값.
nx,ny 및 nz
버텍스의 정규 좌표를 지정하는 값.
tu 및 tv
버텍스의텍스쳐 좌표를 지정하는 값.

참조

D3DLVERTEX ,D3DTLVERTEX


D3DVERTEXBUFFERDESC

D3DVERTEXBUFFERDESC 형은, 버텍스 버퍼 오브젝트의 프로퍼티를 기술한다. 이 형태는,Direct3D7.CreateVertexBuffer 및 Direct3DVertexBuffer7.GetVertexBufferDesc 메소드로 사용된다.

Type D3DVERTEXBUFFERDESC
    lCaps As CONST_D3DVBCAPSFLAGS
    lFVF As CONST_D3DFVFFLAGS
    lNumVertices As Long
End Type

멤버

lCaps
버텍스 버퍼를 기술해, 그 버텍스 버퍼가 최적화된 버텍스 데이터를 보관 유지할 수 있을지 어떨지를 나타내는 능력 플래그. 이 파라미터는,CONST_D3DVBCAPSFLAGS 열거의 정수의 임의의 편성으로 할 수 있다.
lFVF
이 버퍼내의 버텍스의 버텍스 포맷을 기술하는 CONST_D3DFVFFLAGS 열거의 정수의 편성.
lNumVertices
이 버텍스 버퍼를 보관 유지할 수 있는 버텍스의 수의 최대치.

주의

소프트웨어 디바이스 (MMX 디바이스 및 RGB 디바이스)는, 로컬일까 비로컬일까에 관계없이, 비디오 메모리의 버텍스 버퍼로부터 렌더링 할 수 없다. 소프트웨어 디바이스를 사용해 버텍스 버퍼를 렌더링 하려면 , 버텍스 버퍼가 시스템 메모리에 존재해야 한다. 하드웨어 디바이스는, 시스템 메모리 또는 비디오 메모리의 어느 쪽의 버텍스 버퍼로부터에서도, 렌더링 할 수가 있다.

참조

버텍스 버퍼의 기술,버텍스 버퍼


D3DVIEWPORT7

D3DVIEWPORT7 형은, 3D 볼륨이 투영 하는, 렌더링 타겟 표면의 윈도우 사이즈를 정의한다. 이 형태는,Direct3DDevice7.GetViewport 및 Direct3DDevice7.SetViewport 메소드로 사용된다.

Type D3DVIEWPORT7
    lHeight As Long
    lWidth As Long
    lX As Long
    lY As Long
    maxz As Single
    minz As Single
End Type

멤버

lHeight 및 lWidth
렌더링의 대상이 되는 표면 위에의 뷰포트의 크기를 픽셀 단위로 나타낸다. 표면의 서브 세트로 한정해 렌더링 하므로 없으면, 이러한 멤버에는 렌더링의 대상 표면의 크기를 세트 한다.
lX 및 lY
렌더링의 대상이 되는 표면 위에의 뷰포트의 좌상구석을 나타내는 픽셀 좌표. 표면의 서브 세트에 렌더링 하므로 없으면, 이러한 멤버는, 제로에 세트 해도 좋다.
minz 및 maxz
장면을 렌더링 하는 깊이의 범위를 나타내는 값 (DirectX 7.0 에서는, 투영 행렬의 값에 의해 깊이 베이스의 클리핑을 실시하므로 주의한다). 대부분의 어플리케이션에서는, 이러한 값을 0.0 으로 1.0 으로 설정하지만, 양쪽 모두 0.0 으로 설정해, 장면의 전면에서 오브젝트를 렌더링 할 수도 있다. DirectX 7.0 에서는, 투영 행렬을 적용한 다음에 클리핑을 한다. 상세한 것에 대하여는, 「클리핑 볼륨」과「투영 트랜스 폼」을 참조할것.

주의

lX,lY,lWidth 및 lHeight 멤버는, 렌더링의 대상이 되는 표면 위에의 뷰포트의 위치와 크기를 기술한다. 보통, 어플리케이션은 대상이 되는 표면 전체의 렌더링을 실행하므로, 640Χ480 의 표면으로 렌더링을 실시하는 경우에는, 이러한 멤버는 각각 0, 0, 640, 480 의 값을 취한다. minz 와 maxz 는 보통 0.0 으로 1.0 으로 설정되지만, 그 이외의 값으로 설정해 특수한 이펙트를 생성할 수도 있다. 예를 들어, 이러한 값을 양쪽 모두 0.0 으로 설정 하면, 장면의 전면에서 오브젝트가 렌더링 되어 양쪽 모두 1.0 으로 설정 하면, 뒷면에서 렌더링 된다.

Direct3DDevice7.SetViewport 메소드에 의해 디바이스의 뷰포트 파라미터를 변경했을 경우, 드라이버는 새로운 트랜스 폼 행렬을 생성 한다.

참조

Direct3DDevice7.GetViewport ,Direct3DDevice7.SetViewport ,클리핑 볼륨,뷰포트와 클리핑


열거

여기에서는, Direct3D 직접 모드로 사용되는 이하의 열거에 대해 설명한다.

  • CONST_D3D
  • CONST_D3DANTIALIASMODE
  • CONST_D3DBLEND
  • CONST_D3DCAPSBLEND
  • CONST_D3DCAPSCMP
  • CONST_D3DCAPSMISC
  • CONST_D3DCAPSRASTER
  • CONST_D3DCAPSSHADE
  • CONST_D3DCAPSTEXTURE
  • CONST_D3DCAPSTEXTUREADDRESS
  • CONST_D3DCAPSTEXTUREFILTER
  • CONST_D3DCLEARFLAGS
  • CONST_D3DCLIPFLAGS
  • CONST_D3DCLIPPLANEFLAGS
  • CONST_D3DCLIPSTATUSFLAGS
  • CONST_D3DCMPFUNC
  • CONST_D3DCOLORMODEL
  • CONST_D3DCULL
  • CONST_D3DDEVICEDESCCAPS
  • CONST_D3DDEVICEDESCFLAGS
  • CONST_D3DDEVINFOID
  • CONST_D3DDPFLAGS
  • CONST_D3DFILLMODE
  • CONST_D3DFOGMODE
  • CONST_D3DFVFCAPSFLAGS
  • CONST_D3DFVFFLAGS
  • CONST_D3DIMERR
  • CONST_D3DLIGHTTYPE
  • CONST_D3DMATERIALCOLORSOURCE
  • CONST_D3DPRIMITIVETYPE
  • CONST_D3DPROCESSVERTICESFLAGS
  • CONST_D3DRENDERSTATESINGLE
  • CONST_D3DRENDERSTATETYPE
  • CONST_D3DSHADEMODE
  • CONST_D3DSTATEBLOCKTYPE
  • CONST_D3DSTENCILCAPSFLAGS
  • CONST_D3DSTENCILOP
  • CONST_D3DTAFLAGS
  • CONST_D3DTEXCOORDINDEXFLAGS
  • CONST_D3DTEXOPCAPSFLAGS
  • CONST_D3DTEXTUREADDRESS
  • CONST_D3DTEXTUREMAGFILTER
  • CONST_D3DTEXTUREMINFILTER
  • CONST_D3DTEXTUREMIPFILTER
  • CONST_D3DTEXTUREOP
  • CONST_D3DTEXTURESTAGESINGLE
  • CONST_D3DTEXTURESTAGESTATETYPE
  • CONST_D3DTEXTURETRANSFORMFLAGS
  • CONST_D3DTRANSFORMSTATETYPE
  • CONST_D3DVBCAPSFLAGS
  • CONST_D3DVERTEXBLENDFLAGS
  • CONST_D3DVOPFLAGS
  • CONST_D3DVTXPCAPS
  • CONST_D3DZBUFFERTYPE


CONST_D3D

CONST_D3D 열거는, 다양한 정수를 정의한다.

Enum CONST_D3D
    D3DDP_MAXTEXCOORD =8
    D3DRENDERSTATE_WRAPBIAS = 128
    D3DWRAPCOORD_0 = 1
    D3DWRAPCOORD_1 = 2
    D3DWRAPCOORD_2 = 4
    D3DWRAPCOORD_3 = 8
End Enum
D3DDP_MAXTEXCOORD
버텍스에 사용 가능한 텍스쳐 좌표의 최대치.
D3DRENDERSTATE_WRAPBIAS
텍스쳐 스테이지의 제로 베이스의 인덱스에 추가해,Direct3DDevice7.SetRenderState 및 Direct3DDevice7.SetRenderState 메소드로 사용하기 위해서 유효한 D3DRENDERSTATE_WRAPn 값을 생성하는 값.
D3DWRAPCOORD_0 through D3DWRAPCOORD_3
지정된 텍스쳐의 제일, 제2, 제3, 제4 넓이의 방향 (s, t, r, q 방향이라고도 말한다)으로 랩 한다. 이러한 값은,D3DRENDERSTATE_WRAP0 으로부터 D3DRENDERSTATE_WRAP7 렌더링 스테이트에서 사용한다.


CONST_D3DANTIALIASMODE

CONST_D3DANTIALIASMODE 열거는,CONST_D3DRENDERSTATETYPE 열거의 D3DRENDERSTATE_ANTIALIAS 값에 대해서, 지원 되고 있는 anti-aliasing 모드를 정의한다. 이러한 값은, 프리미티브의 엣지 anti-aliasing에 대한 설정값을 정의한다 (상세한 것에 대하여는, 「anti-aliasing」를 참조할것).

Enum CONST_D3DANTIALIASMODE
    D3DANTIALIAS_NONE          = 0
    D3DANTIALIAS_SORTDEPENDENT = 1
    D3DANTIALIAS_SORTINDEPENDENT = 2
End Enum
D3DANTIALIAS_NONE
anti-aliasing는 실행되지 않는다. 이것이 디폴트 설정이다.
D3DANTIALIAS_SORTDEPENDENT
anti-aliasing는, 다각형의 소트순서 (후방에서 전방, 혹은 전방에서 후방)에 의존한다. 어플리케이션은, anti-aliasing가 생기는 것에 갖추어 올바른 순서로 다각형을 작도 해야 한다.
D3DANTIALIAS_SORTINDEPENDENT
anti-aliasing는, 다각형의 소트순서에 의존하지 않는다.


CONST_D3DBLEND

CONST_D3DBLEND 열거는,CONST_D3DRENDERSTATETYPE 열거의 D3DRENDERSTATE_DESTBLEND 값에 대해서, 지원 되고 있는블렌딩 모드를 정의한다. 이하의 멤버의 설명에서는, 소스와 데스티네이션의 RGBA 값은, 첨자의 s 및 d 에 의해 나타난다.

Enum CONST_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
End Enum
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
지원되어 있지 않다.
D3DBLEND_BOTHINVSRCALPHA
소스 블렌딩 계수는, (1-As, 1-As, 1-As, 1-As). 목적지 블렌딩 계수는, (As, As, As, As). 목적지 혼합절은, 무효가 된다.

주의

DirectX 6.0 이후의 Direct3D 에서는, D3DBLEND_BOTHSRCALPHA 는 지원되어 있지 않다. D3DBLEND_SRCALPHA 과 D3DBLEND_INVSRCALPHA 를 개별적으로 설정할 필요가 있다.


CONST_D3DCAPSBLEND

CONST_D3DCAPSBLEND 열거는, 디바이스의 블렌딩 능력을 정의한다. 이러한 값은,D3DPRIMCAPS 형의 lSrcBlendCaps 및 lDestBlendCaps 멤버로 사용된다.

Enum CONST_D3DCAPSBLEND
    D3DPBLENDCAPS_BOTHINVSRCALPHA =4096
    D3DPBLENDCAPS_BOTHSRCALPHA =2048
    D3DPBLENDCAPS_DESTALPHA =64
    D3DPBLENDCAPS_DESTCOLOR =256
    D3DPBLENDCAPS_INVDESTALPHA =128
    D3DPBLENDCAPS_INVDESTCOLOR =512
    D3DPBLENDCAPS_INVSRCALPHA =32
    D3DPBLENDCAPS_INVSRCCOLOR =8
    D3DPBLENDCAPS_ONE =2
    D3DPBLENDCAPS_SRCALPHA =16
    D3DPBLENDCAPS_SRCALPHASAT =1024
    D3DPBLENDCAPS_SRCCOLOR =4
    D3DPBLENDCAPS_ZERO =1
End Enum
D3DPBLENDCAPS_BOTHINVSRCALPHA
소스 블렌딩 계수 (1-As, 1-As, 1-As, 1-As)와 목적지 블렌딩 계수 (As, As, As, As). 목적지 혼합절은, 무효가 된다.
D3DPBLENDCAPS_BOTHSRCALPHA
소스 블렌딩 계수는, (As, As, As, As). 목적지 블렌딩 계수는, (1-As, 1-As, 1-As, 1-As). 목적지 혼합절은, 무효가 된다.
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).


CONST_D3DCAPSCMP

CONST_D3DCAPSCMP 열거는, 깊이 버퍼 비교와 알파 실험의 비교 능력을 정의한다. 이러한 플래그는,D3DPRIMCAPS 형의 lZCmpCaps 및 lAlphaCmpCaps 멤버로 사용된다.

Enum CONST_D3DCAPSCMP
    D3DPCMPCAPS_ALWAYS = 128
    D3DPCMPCAPS_EQUAL = 4
    D3DPCMPCAPS_GREATER = 16
    D3DPCMPCAPS_GREATEREQUAL = 64
    D3DPCMPCAPS_LESS = 2
    D3DPCMPCAPS_LESSEQUAL = 8
    D3DPCMPCAPS_NEVER = 1
    D3DPCMPCAPS_NOTEQUAL = 32
End Enum
D3DPCMPCAPS_ALWAYS
항상 비교를 통한다.
D3DPCMPCAPS_EQUAL
신규의 값이 현재의 값과 동일한 경우, 비교를 통한다.
D3DPCMPCAPS_GREATER
신규의 값이 현재의 값보다 큰 경우, 비교를 통한다.
D3DPCMPCAPS_GREATEREQUAL
신규의 값이 현재의 값보다 큰가 동일한 경우, 비교를 통한다.
D3DPCMPCAPS_LESS
신규의 값이 현재의 값보다 작은 경우, 비교를 통한다.
D3DPCMPCAPS_LESSEQUAL
신규의 값이 현재의 값보다 작은가 동일한 경우, 비교를 통한다.
D3DPCMPCAPS_NEVER
항상 비교는 실패한다.
D3DPCMPCAPS_NOTEQUAL
신규의 값이 현재의 값과 다른 경우, 비교를 통한다.


CONST_D3DCAPSMISC

CONST_D3DCAPSMISC 열거는,D3DPRIMCAPS 형의 lMiscCaps 멤버로 사용되는 능력 플래그를 정의한다.

Enum CONST_D3DCAPSMISC
    D3DPMISCCAPS_CONFORMANT = 8
    D3DPMISCCAPS_CULLCCW = 64
    D3DPMISCCAPS_CULLCW = 32
    D3DPMISCCAPS_CULLNONE = 16
    D3DPMISCCAPS_LINEPATTERNREP = 4
    D3DPMISCCAPS_MASKPLANES = 1
    D3DPMISCCAPS_MASKZ = 2
End Enum
D3DPMISCCAPS_CONFORMANT
디바이스는, OpenGL 표준에 준하고 있다.
D3DPMISCCAPS_CULLCCW
드라이버는, D3DRENDERSTATE_CULLMODE 스테이트에서 선택한 왼쪽 회전을 지원 한다 (삼각형의 프리미티브의 경우만). CONST_D3DCULL 열거의 D3DCULL_CCW 정수에 대응한다.
D3DPMISCCAPS_CULLCW
디바이스는, D3DRENDERSTATE_CULLMODE 스테이트에서 선택한 우회전의 삼각형을 지원 한다 (삼각형의 프리미티브의 경우만). CONST_D3DCULL 열거의 D3DCULL_CW 정수에 대응한다.
D3DPMISCCAPS_CULLNONE
디바이스는, 선택하고 있는 삼각형을 실행할 수 없다. CONST_D3DCULL 열거의 D3DCULL_NONE 정수에 대응한다.
D3DPMISCCAPS_LINEPATTERNREP
사용하지 않는다.
D3DPMISCCAPS_MASKPLANES
디바이스는, 색의 비트 마스크를 실행할 수 있다.
D3DPMISCCAPS_MASKZ
디바이스는, 픽셀 조작의 깊이 버퍼 변경을 유효하게 하거나 무효로 하거나 할 수 있다.


CONST_D3DCAPSRASTER

CONST_D3DCAPSRASTER 열거는,D3DPRIMCAPS 형의 lRasterCaps 멤버로 사용되는 능력 플래그를 정의한다.

Enum CONST_D3DCAPSRASTER
    D3DPRASTERCAPS_ANISOTROPY = 131072
    D3DPRASTERCAPS_ANTIALIASEDGES = 4096
    D3DPRASTERCAPS_ANTIALIASSORTDEPENDENT = 1024
    D3DPRASTERCAPS_DITHER= 1
    D3DPRASTERCAPS_FOGRANGE = 65536
    D3DPRASTERCAPS_FOGTABLE = 256
    D3DPRASTERCAPS_FOGVERTEX = 128
    D3DPRASTERCAPS_MIPMAPLODBIAS = 8192
    D3DPRASTERCAPS_PAT = 8
    D3DPRASTERCAPS_ROP2 = 2
    D3DPRASTERCAPS_STIPPLE = 512
    D3DPRASTERCAPS_SUBPIXEL= 32
    D3DPRASTERCAPS_SUBPIXELX = 64
    D3DPRASTERCAPS_XOR = 4
    D3DPRASTERCAPS_ZBIAS = 16384
    D3DPRASTERCAPS_ZBUFFERLESSHSR = 32768
    D3DPRASTERCAPS_ZTEST = 16
End Enum
D3DPRASTERCAPS_ANISOTROPY
디바이스는 비등방성 (anisotropic) 필터링을 지원 한다.
D3DPRASTERCAPS_ANTIALIASEDGES
디바이스는, 오브젝트의 윤곽선이 볼록한 모양이 되는 것 같은 에일리어징 제거선을 만들 수가 있다.
D3DPRASTERCAPS_ANTIALIASSORTDEPENDENT
디바이스는, 다각형의 소트순서 (후방에서 전방, 또는 전방에서 후방)에 의존하는 anti-aliasing를 지원 한다. 어플리케이션은, anti-aliasing가 생기는 것에 갖추어 올바른 순서로 다각형을 작도 해야 한다. 상세한 것에 대하여는,CONST_D3DANTIALIASMODE 열거의 항을 참조할것.
D3DPRASTERCAPS_ANTIALIASSORTINDEPENDENT
디바이스는, 다각형의 소트순서에 의하지 않는 anti-aliasing를 지원 한다. 상세한 것에 대하여는,CONST_D3DANTIALIASMODE 열거의 항을 참조할것.
D3DPRASTERCAPS_DITHER
디바이스는, 색의 재현력을 자주(잘) 하기 위해서 dither 표시할 수 있다.
D3DPRASTERCAPS_FOGRANGE
디바이스는 범위 베이스의 포그(안개:fog)를 지원 한다. 범위 베이스의 포그(안개:fog)에서는, 장면에 있어서의 오브젝트의 깊이 (z 좌표)는 아니고, 오브젝트의 뷰아로부터의 거리로 포그(안개:fog) 이펙트를 계산한다. 상세한 것에 대하여는, 「범위 베이스의 포그(안개:fog)」를 참조할것.
D3DPRASTERCAPS_FOGTABLE
디바이스는, 픽셀의 깊이를 가리키는 포그(안개:fog)값을 트랜스 폼 하는 취득 테이블과 조합해, 포그(안개:fog)값을 산출한다.
D3DPRASTERCAPS_FOGVERTEX
디바이스는 라이팅 처리동안 포그(안개:fog)값을 계산해,D3DTLVERTEX 형의 specular 멤버로 주어진 값의 알파 성분중의 값에 옮겨놓아 라스터의 사이 포그(안개:fog)값을 보간 한다.
D3DPRASTERCAPS_MIPMAPLODBIAS
디바이스는 상세 레벨 (LOD) 바이어스 조정을 지원 한다. 이러한 바이어스 조정으로, 어플리케이션이 밉맵을 보통보다 깨끗이 어떤 있고는 그다지 날카롭지 않게 보이게 할 수가 있게 된다. 밉맵에서의 LOD 바이어스의 상세한 것에 대하여는,D3DTSS_MIPMAPLODBIAS 를 참조할것.
D3DPRASTERCAPS_PAT
드라이버는, 프리미티브용으로 조회되는 패턴 드로잉(Drawing)를 처리할 수 있다.
D3DPRASTERCAPS_ROP2
디바이스는, R2_COPYPEN 이외의 라스터화를 지원 할 수 있다.
D3DPRASTERCAPS_STIPPLE
디바이스는, 반투명을 시뮬레이트 하는 다각형을 점묘 할 수 있다.
D3DPRASTERCAPS_SUBPIXEL
디바이스는, 제일 가까운 정수형의 픽셀 좌표가 아니고, Z, 색, 텍스쳐의 데이터의 서브 픽셀 배치로 처리한다. 이것은, Z 의 bleed선을 피하는 것을 돕는다 (색의 지터와 픽셀의 텍스쳐값도). 이것들은, 유효로 하거나 무효로 하거나 할 수 없다 (디바이스는, 서브 픽셀 배치를 실행하거나 하지 않거나 한다). 이 비트는, 렌더링의 질을 결정할 수 있는 Direct3D 클라이언트에 제공된다.
D3DPRASTERCAPS_SUBPIXELX
디바이스는, X 축으로 따른 서브 픽셀 배치이며, 정수형의 Y 축의 주사선을 쌓아올린 것이다.
D3DPRASTERCAPS_WBUFFER
디바이스는 w 준거의 깊이 버퍼링을 지원 한다. 상세한 것에 대하여는, 「깊이 버퍼」를 참조할것.
D3DPRASTERCAPS_WFOG
디바이스는 w 준거의 포그(안개:fog)를 지원 한다. w 준거의 포그(안개:fog)는 퍼스펙티브 투영 행렬이 지정되었을 경우에 사용되지만, 아핀 투영에서는 현재에도 z 준거 포그(안개:fog)를 사용한다. 시스템은,[3][4] 요소가 제로 이외의 값을 가지는 투영 행렬을 퍼스펙티브 투영 행렬이라고 간주한다.
D3DPRASTERCAPS_XOR
디바이스는, 배타적 논리합 (XOR) GDI 라스터화를 지원 한다. 이 플래그가 설정되지 않고, D3DPRIM_RASTER_ROP2 가 설정되어 있는 경우는, 배타적 논리합 처리가 지원되어 있지 않으면 안 된다.
D3DPRASTERCAPS_ZBIAS
디바이스는 z 바이어스값을 지원 한다. 이것들은 평면을 공유하는 다각형을 다른 것에 보이도록, 다각형에 할당할 수 있었던 정수값이다. 상세한 것에 대하여는,CONST_D3DRENDERSTATETYPE 열거의 「D3DRENDERSTATE_ZBIAS 」를 참조.
D3DPRASTERCAPS_ZBUFFERLESSHSR
디바이스는, 숨고 표면의 제거 (HRS)를 실행 가능하고, 이 때, 다각형의 소트나, 깊이 버퍼의 할당을 필요로 하지 않는다. 이것에 의해, 보다 많은 비디오 메모리를 텍스쳐용으로 사용할 수 있다. 숨고 표면 제거에 사용하는 메소드는 하드웨어의 기능에 의존해, 어플리케이션 투과이다.

Z 버퍼 없음의 HRS 가 실행되는 것은, 렌더링의 대상이 되는 표면에 깊이 버퍼가 Attach 되지 않고, 한편, 깊이 버퍼의 비교 테스트가 유효화 되고 있는 경우 (즉,D3DRENDERSTATE_ZENABLE 열거 정수에 부수 하는 스테이트값이 TRUE 에 세트 되고 있는 경우)이다.

D3DPRASTERCAPS_ZTEST
디바이스는 Z 테스트 처리를 실행할 수 있다. 이것은, 효과적으로 프리미티브를 렌더링 해, 렌더링 된 어떠한 Z 픽셀에서도 표시한다.


CONST_D3DCAPSSHADE

CONST_D3DCAPSSHADE 열거는,D3DPRIMCAPS 형의 lShadeCaps 멤버로 사용되는 다각형 쉐이딩 능력 플래그를 정의한다.

Enum CONST_D3DCAPSSHADE
    D3DPSHADECAPS_ALPHAFLATBLEND = 4096
    D3DPSHADECAPS_ALPHAFLATSTIPPLED = 8192
    D3DPSHADECAPS_ALPHAGOURAUDBLEND = 16384
    D3DPSHADECAPS_ALPHAGOURAUDSTIPPLED = 32768
    D3DPSHADECAPS_ALPHAPHONGBLEND = 65536
    D3DPSHADECAPS_ALPHAPHONGSTIPPLED = 131072
    D3DPSHADECAPS_COLORFLATMONO = 1
    D3DPSHADECAPS_COLORFLATRGB = 2
    D3DPSHADECAPS_COLORGOURAUDMONO = 4
    D3DPSHADECAPS_COLORGOURAUDRGB = 8
    D3DPSHADECAPS_COLORPHONGMONO = 16
    D3DPSHADECAPS_COLORPHONGRGB = 32
    D3DPSHADECAPS_FOGFLAT = 262144
    D3DPSHADECAPS_FOGGOURAUD = 524288
    D3DPSHADECAPS_FOGPHONG = 1048576
    D3DPSHADECAPS_SPECULARFLATMONO = 64
    D3DPSHADECAPS_SPECULARFLATRGB = 128
    D3DPSHADECAPS_SPECULARGOURAUDMONO = 256
    D3DPSHADECAPS_SPECULARGOURAUDRGB = 512
    D3DPSHADECAPS_SPECULARPHONGMONO = 1024
    D3DPSHADECAPS_SPECULARPHONGRGB = 2048
End Enum
D3DPSHADECAPS_ALPHAFLATBLEND
디바이스는, 투과적으로 각각 혼합이나 점묘 된 플랫 (CONST_D3DSHADEMODE 열거의 D3DSHADE_FLAT 스테이트)의 알파 성분을 지원 할 수 있다. 이러한 모드로, 1 개의 요소를 위한알파색성분은, 요소의 최초의 버텍스의 색의 일부분으로서 주어진다.
D3DPSHADECAPS_ALPHAFLATSTIPPLED
디바이스는, 투과적으로 각각 혼합이나 점묘 된 플랫 (CONST_D3DSHADEMODE 열거의 D3DSHADE_FLAT 스테이트)의 알파 성분을 지원 할 수 있다. 이러한 모드로, 1 개의 요소를 위한알파색성분은, 요소의 최초의 버텍스의 색의 일부분으로서 주어진다.
D3DPSHADECAPS_ALPHAGOURAUDBLEND
디바이스는, 투과적으로 각각 혼합이나 점묘 된 굿 로 (CONST_D3DSHADEMODE 열거의 D3DSHADE_GOURAUD 스테이트)의 알파 성분을 지원 할 수 있다. 이러한 모드에서는,알파색성분은 버텍스에게 줄 수 있어 다른 색성분과 함께 보간 된다.
D3DPSHADECAPS_ALPHAGOURAUDSTIPPLED
디바이스는, 투과적으로 각각 혼합이나 점묘 된 굿 로 (CONST_D3DSHADEMODE 열거의 D3DSHADE_GOURAUD 스테이트)의 알파 성분을 지원 할 수 있다. 이러한 모드에서는,알파색성분은 버텍스에게 줄 수 있어 다른 색성분과 함께 보간 된다.
D3DPSHADECAPS_ALPHAPHONGBLEND
디바이스는, 투과적으로 각각 혼합이나 점묘 된 폰 (CONST_D3DSHADEMODE 열거의 D3DSHADE_PHONG 스테이트)의 알파 성분을 지원 할 수 있다. 이러한 모드로, 버텍스 파라미터는 적, 초록, 파랑의 색성분의 광원 이펙트를 적용해, 픽셀 단위에 재평가된다. 폰 쉐이딩은, 현재 지원되어 있지 않다.
D3DPSHADECAPS_ALPHAPHONGSTIPPLED
디바이스는, 투과적으로 각각 혼합이나 점묘 된 폰 (CONST_D3DSHADEMODE 열거의 D3DSHADE_PHONG 스테이트)의 알파 성분을 지원 할 수 있다. 이러한 모드로, 버텍스 파라미터는 적, 초록, 파랑의 색성분의 광원 이펙트를 적용해, 픽셀 단위에 재평가된다. 폰 쉐이딩은, 현재 지원되어 있지 않다.
D3DPSHADECAPS_COLORFLATMONO
디바이스는,D3DCOLOR_MONO 와 D3DCOLOR_RGB 색모델의 각각 붙어, 물이 들어 flat shading를 지원 할 수 있다. 이러한 모드에서는, 프리미티브에 대한 색성분은 프리미티브의 최초의 버텍스의 색의 일부로서 주어진다. 흑백 라이팅 모드로 보간 되는 색성분은 파랑 뿐이어서, RGB 라이팅 모드에서는, 적, 록, 청의 각 색성분이 보간 된다.
D3DPSHADECAPS_COLORFLATRGB
디바이스는,D3DCOLOR_MONO 와 D3DCOLOR_RGB 색모델의 각각 붙어, 물이 들어 flat shading를 지원 할 수 있다. 이러한 모드에서는, 프리미티브에 대한 색성분은 프리미티브의 최초의 버텍스의 색의 일부로서 주어진다. 흑백 라이팅 모드로 보간 되는 색성분은 파랑 뿐이어서, RGB 라이팅 모드에서는, 적, 록, 청의 각 색성분이 보간 된다.
D3DPSHADECAPS_COLORGOURAUDMONO
디바이스는,D3DCOLOR_MONO 와 D3DCOLOR_RGB 색모델의 각각 붙어, 물이 들어 gouraud shading를 지원 할 수 있다. 이러한 모드에서는, 프리미티브에 대한 색성분은 버텍스로써 주어져 다른 색성분과 함께 면을 따라 보간 된다. 흑백 라이팅 모드로 보간 되는 색성분은 파랑 뿐이어서, RGB 라이팅 모드에서는, 적, 록, 청의 각 색성분이 보간 된다.
D3DPSHADECAPS_COLORGOURAUDRGB
디바이스는,D3DCOLOR_MONO 와 D3DCOLOR_RGB 색모델의 각각 붙어, 물이 들어 gouraud shading를 지원 할 수 있다. 이러한 모드에서는, 프리미티브에 대한 색성분은 버텍스로써 주어져 다른 색성분과 함께 면을 따라 보간 된다. 흑백 라이팅 모드로 보간 되는 색성분은 파랑 뿐이어서, RGB 라이팅 모드에서는, 적, 록, 청의 각 색성분이 보간 된다.
D3DPSHADECAPS_COLORPHONGMONO
디바이스는,D3DCOLOR_MONO 와 D3DCOLOR_RGB 색모델의 각각 붙어, 물이 들어 폰 쉐이딩을 지원 할 수 있다. 이러한 모드에서는, 버텍스 파라미터는 픽셀 단위에 재평가된다. 광원 이펙트는, RGB 모드의 적, 초록, 파랑의 색성분으로 적용된다. 폰 쉐이딩은, 현재 지원되어 있지 않다.
D3DPSHADECAPS_COLORPHONGRGB
디바이스는,D3DCOLOR_MONO 와 D3DCOLOR_RGB 색모델의 각각 붙어, 물이 들어 폰 쉐이딩을 지원 할 수 있다. 이러한 모드에서는, 버텍스 파라미터는 픽셀 단위에 재평가된다. 광원 이펙트는, RGB 모드의 적, 초록, 파랑의 색성분으로 적용된다. 폰 쉐이딩은, 현재 지원되어 있지 않다.
D3DPSHADECAPS_FOGFLAT
디바이스는, 플랫, 굿 로, 폰 모드로 포그(안개:fog)를 지원 할 수 있다. 폰 쉐이딩은, 현재 지원되어 있지 않다.
D3DPSHADECAPS_FOGGOURAUD
디바이스는, 플랫, 굿 로, 폰 모드로 포그(안개:fog)를 지원 할 수 있다. 폰 쉐이딩은, 현재 지원되어 있지 않다.
D3DPSHADECAPS_FOGPHONG
디바이스는, 플랫, 굿 로, 폰 모드로 포그(안개:fog)를 지원 할 수 있다. 폰 쉐이딩은, 현재 지원되어 있지 않다.
D3DPSHADECAPS_SPECULARFLATMONO
디바이스는,D3DCOLOR_MONO 와 D3DCOLOR_RGB 색모델의 flat shading의 스펙큐러 하이라이트를 지원 할 수 있다.
D3DPSHADECAPS_SPECULARFLATRGB
디바이스는,D3DCOLOR_MONO 와 D3DCOLOR_RGB 색모델의 flat shading의 스펙큐러 하이라이트를 지원 할 수 있다.
D3DPSHADECAPS_SPECULARGOURAUDMONO
디바이스는,D3DCOLOR_MONO 와 D3DCOLOR_RGB 색모델의 gouraud shading의 스펙큐러 하이라이트를 지원 할 수 있다.
D3DPSHADECAPS_SPECULARGOURAUDRGB
디바이스는,D3DCOLOR_MONO 와 D3DCOLOR_RGB 색모델의 gouraud shading의 스펙큐러 하이라이트를 지원 할 수 있다.
D3DPSHADECAPS_SPECULARPHONGMONO
디바이스는,D3DCOLOR_MONO 와 D3DCOLOR_RGB 색모델의 폰 쉐이딩의 스펙큐러 하이라이트를 지원 할 수 있다. 폰 쉐이딩은, 현재 지원되어 있지 않다.
D3DPSHADECAPS_SPECULARPHONGRGB
디바이스는,D3DCOLOR_MONO 와 D3DCOLOR_RGB 색모델의 폰 쉐이딩의 스펙큐러 하이라이트를 지원 할 수 있다. 폰 쉐이딩은, 현재 지원되어 있지 않다.


CONST_D3DCAPSTEXTURE

CONST_D3DCAPSTEXTURE 열거는,D3DPRIMCAPS 형의 lTextureCaps 멤버로 사용되는 텍스쳐링 능력 플래그를 정의한다.

Enum CONST_D3DCAPSTEXTURE {
    D3DPTEXTURECAPS_ALPHA = 4
    D3DPTEXTURECAPS_BORDER = 16
    D3DPTEXTURECAPS_COLORKEYBLEND = 4096
    D3DPTEXTURECAPS_CUBEMAP = 1024
    D3DPTEXTURECAPS_NONPOW2CONDITIONAL = 256
    D3DPTEXTURECAPS_PERSPECTIVE = 1
    D3DPTEXTURECAPS_POW2 = 2
    D3DPTEXTURECAPS_SQUAREONLY = 32
    D3DPTEXTURECAPS_TRANSPARENCY = 8
End Enum
D3DPTEXTURECAPS_ALPHA
D3DTEX_DECAL 과 D3DTEX_MODULATE 텍스쳐 필터 모드의 RGBA 텍스쳐를 지원 한다. 이 능력이 설정되어 있지 않은 경우, RGB 텍스쳐만이, 이러한 모드로 지원 된다. 이 플래그의 설정을 무시 하면, 알파는 사용 가능한 D3DEX_DECAL_MASK, D3DTEX_DECAL_ALPHA, D3DEX_MODULATE_ALPHA 필터 모드로 지원 된다.
D3DPTEXTURECAPS_ALPHAPALETTE
팔레트가 알파 정보를 포함한팔레트화 텍스쳐 표면을 지원 한다 (DDCAPS 형의 DDPCAPS_ALPHA를 참조).
D3DPTEXTURECAPS_COLORKEYBLEND
디바이스는,D3DRENDERSTATE_COLORKEYBLENDENABLE 렌더링 스테이트의 사용에 의해, 컬러 키의 알파 블렌딩을 지원 한다.
D3DPTEXTURECAPS_CUBEMAP
큐브 환경 맵을 지원 한다.
D3DPTEXTURECAPS_BORDER
D3DPTADDRESSCAPS_BORDER 로 옮겨졌다.
D3DPTEXTURECAPS_PERSPECTIVE
퍼스펙티브 보정이 지원 된다.
D3DPTEXTURECAPS_PROJECTED
D3DTTFF_PROJECTED 텍스쳐 트랜스 폼 플래그를 지원 한다. 적용되면(자), 디바이스는 트랜스 폼 된 텍스쳐 좌표를 마지막 텍스쳐 좌표로 나눗셈 한다.
D3DPTEXTURECAPS_NONPOW2CONDITIONAL
2 말하고 나무승이 아닌 크기의 텍스쳐를 조건부로 지원 한다. 이 능력을 가지는 디바이스는, 다음의 조건을 모두 채우는 경우에, 이러한 텍스쳐를 사용할 수 있다.
  • 텍스쳐 스테이지의 텍스쳐 addressing mode가 D3DTADDRESS_CLAMP 에 세트 되고 있다.
  • 텍스쳐 스테이지에 대한 텍스쳐 랩핑이 무효가 되어 있다 (D3DRENDERSTATE_WRAPn 가 제로로 설정되어 있다).
  • 밉맵을 사용하고 있지 않다 (밉맵 텍스쳐는, 2 말하고 나무승의 크기가 아니면 안된다).
D3DPTEXTURECAPS_POW2
이 플래그가 세트 되었을 경우, 밉맵이 아닌 텍스쳐는 모두, 2 말하고 나무승으로 지정된 폭과 높이를 가지지 않으면 안 된다 (밉맵 텍스쳐는 모두, 2 말하고 나무승의 크기가 아니면 안되는 것에 주의한다).
D3DPTEXTURECAPS_SQUAREONLY
텍스쳐는, 모두 정방형이 아니면 안된다.
D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE
텍스쳐 인덱스는, 보간 실행전에는, 텍스쳐 사이즈에 맞추어 스케일링 되지 않는다.
D3DPTEXTURECAPS_TRANSPARENCY
Texture transparency is supported. 투과 텍스쳐가 지원 된다 (현재의 투과색이 아닌 이러한 텍셀만 드로잉(Drawing) 된다).


CONST_D3DCAPSTEXTUREADDRESS

CONST_D3DCAPSTEXTUREADDRESS 열거는,D3DPRIMCAPS 형의 lTextureAddressCaps 멤버로 사용되는 텍스쳐 애드레싱 능력 플래그를 정의한다.

Enum CONST_D3DCAPSTEXTUREADDRESS
    D3DPTADDRESSCAPS_BORDER = 8
    D3DPTADDRESSCAPS_CLAMP = 4
    D3DPTADDRESSCAPS_INDEPENDENTUV = 16
    D3DPTADDRESSCAPS_MIRROR = 2
    D3DPTADDRESSCAPS_WRAP = 1
End Enum
D3DPTADDRESSCAPS_BORDER
디바이스는,D3DTSS_BORDERCOLOR 텍스쳐 스테이지 스테이트의 지정에 따라,[0.0, 1.0] 범위외의 좌표에 경계색을 설정하는 것을 지원 한다. 이 성능은,D3DTADDRESS_BORDER 텍스쳐 addressing mode에 대응한다.
D3DPTADDRESSCAPS_CLAMP
디바이스는, 텍스쳐의 고정이 가능하다.
D3DPTADDRESSCAPS_INDEPENDENTUV
디바이스는, 텍스쳐의 U 좌표와 V 좌표의 텍스쳐 addressing mode를 분리할 수 있다. 이 성능은,D3DTSS_ADDRESSU 및 D3DTSS_ADDRESSV 렌더링 스테이트값에 대응한다.
D3DPTADDRESSCAPS_MIRROR
디바이스는, 텍스쳐의 반전이 가능하다.
D3DPTADDRESSCAPS_WRAP
디바이스는, 텍스쳐가 붙이고가 가능하다.


CONST_D3DCAPSTEXTUREFILTER

CONST_D3DCAPSTEXTUREFILTER 열거는,D3DPRIMCAPS 형의 lTextureFilterCaps 로 사용되는 텍스쳐 필터링 능력 플래그를 정의한다.

Enum CONST_D3DCAPSTEXTUREFILTER
    D3DPTFILTERCAPS_LINEAR = 2
    D3DPTFILTERCAPS_LINEARMIPLINEAR = 32
    D3DPTFILTERCAPS_LINEARMIPNEAREST = 16
    D3DPTFILTERCAPS_MAGFAFLATCUBIC = 134217728
    D3DPTFILTERCAPS_MAGFANISOTROPIC = 67108864
    D3DPTFILTERCAPS_MAGFGAUSSIANCUBIC =  268435456
    D3DPTFILTERCAPS_MAGFLINEAR = 16777216
    D3DPTFILTERCAPS_MAGFPOINT = 8388608
    D3DPTFILTERCAPS_MINFANISOTROPIC = 1024
    D3DPTFILTERCAPS_MINFLINEAR = 512
    D3DPTFILTERCAPS_MINFPOINT = 256
    D3DPTFILTERCAPS_MIPFLINEAR = 131072
    D3DPTFILTERCAPS_MIPFPOINT = 65536
    D3DPTFILTERCAPS_MIPLINEAR = 8
    D3DPTFILTERCAPS_MIPNEAREST = 4
    D3DPTFILTERCAPS_NEAREST = 1
End Enum

일반 텍스쳐 필터링 플래그

D3DPTFILTERCAPS_LINEAR
바이리니아피르타링. 가장 가까운 좌표를 가지는 텍셀을 선택한 후, 4 개의 주변 텍셀을 사용해 중량감 첨부 평균을 산출해, 최종적인 색을 결정한다. 이것은, 확대와 축소의 양쪽 모두로 사용된다. 확대나 축소가 지원 되고 있을 때는, 양쪽 모두가 지원되어 있지 않으면 안 된다.
D3DPTFILTERCAPS_LINEARMIPLINEAR
밉맵간의 트라이 리니어 보간. 바이리니아피르타링을 2 개의 최근접밉맵간에 실행한 후, 2 색의 사이를 선형적으로 보간 해 최종적인 색을 결정한다.
D3DPTFILTERCAPS_LINEARMIPNEAREST
샘플링 된 밉맵의 2 점간의 선형 보간. 2 개(살)의 가장 가까운 밉맵 레벨로부터 최근접텍셀을 선택한 후, 그 2 개의 텍셀간에 선형 보간을 실행한다.
D3DPTFILTERCAPS_MIPLINEAR
바이리니아피르타링을 결과에 적용하는, 최근접MIP Mapping. 가장 가까운 좌표를 가지는 적절한 밉맵으로부터 텍셀을 선택한 후, 4 개의 주변 텍셀을 사용해 중량감 첨부 평균을 산출해, 최종적인 색을 결정한다.
D3DPTFILTERCAPS_MIPNEAREST
최근접MIP Mapping. 목적의 픽셀값에 가장 가까운 좌표를 가지는 적절한 밉맵으로부터 텍셀을 선택한다.
D3DPTFILTERCAPS_NEAREST
포인트 샘플링. 희망의 픽셀값에 가장 가까운 좌표를 가지는 텍셀을 사용한다. 이것은, 확대와 축소의 양쪽 모두로 사용된다. 확대나 축소가 지원 되고 있을 때는, 양쪽 모두가 지원되어 있지 않으면 안 된다.

스테이지 단위 텍스쳐 필터링 플래그

D3DPTFILTERCAPS_MAGFAFLATCUBIC
디바이스는, 스테이지 단위에서의 텍스쳐 확대를 위해 평면 큐브 필터링을 지원 한다. 평면 큐브 확대 필터는,CONST_D3DTEXTUREMAGFILTER 열거의 멤버 D3DTFG_FLATCUBIC 로 나타내진다.
D3DPTFILTERCAPS_MAGFANISOTROPIC
디바이스는, 스테이지 단위에서의 텍스쳐 확대를 위해, 비등방성 필터링을 지원 한다. 비등방성 확대 필터는,CONST_D3DTEXTUREMAGFILTER 열거의 멤버 D3DTFG_ANISOTROPIC 로 나타내진다.
D3DPTFILTERCAPS_MAGFGAUSSIANCUBIC
디바이스는, 스테이지 단위에서의 텍스쳐 확대를 위해, Gauss 큐브 필터링을 지원 한다. Gauss 큐브 확대 필터는,CONST_D3DTEXTUREMAGFILTER 열거의 멤버 D3DTFG_GAUSSIANCUBIC 로 나타내진다.
D3DPTFILTERCAPS_MAGFLINEAR
디바이스는, 스테이지 단위에서의 텍스쳐 확대를 위해, 바이리니아 보간 필터링을 지원 한다. 바이리니아 보간 확대 필터는,CONST_D3DTEXTUREMAGFILTER 열거의 멤버 D3DTFG_LINEAR 로 나타내진다.
D3DPTFILTERCAPS_MAGFPOINT
디바이스는, 스테이지 단위에서의 텍스쳐 확대를 위해, 포인트 샘플 필터링을 지원 한다. 포인트 샘플 확대 필터는,CONST_D3DTEXTUREMAGFILTER 열거의 멤버 D3DTFG_POINT 로 나타내진다.
D3DPTFILTERCAPS_MINFANISOTROPIC
디바이스는, 스테이지 단위에서의 텍스쳐 축소를 위해, 비등방성 필터링을 지원 한다. 비등방성 축소 필터는,CONST_D3DTEXTUREMINFILTER 열거의 멤버 D3DTFN_ANISOTROPIC 로 나타내진다.
D3DPTFILTERCAPS_MINFLINEAR
디바이스는, 스테이지 단위에서의 텍스쳐 축소를 위해, 바이리니아 보간 필터링을 지원 한다. 바이리니아 보간 축소 필터는,CONST_D3DTEXTUREMINFILTER 열거의 멤버 D3DTFN_LINEAR 로 나타내진다.
D3DPTFILTERCAPS_MINFPOINT
디바이스는, 스테이지 단위에서의 텍스쳐 축소를 위해, 포인트 샘플 필터링을 지원 한다. 포인트 샘플 축소 필터는,CONST_D3DTEXTUREMINFILTER 열거의 멤버 D3DTFN_POINT 로 나타내진다.
D3DPTFILTERCAPS_MIPFLINEAR
디바이스는, 스테이지 단위에서의 밉맵이기 때문에, 트라이 리니어 보간 필터링을 지원 한다. 트라이 리니어 보간 밉맵 필터는,CONST_D3DTEXTUREMIPFILTER 열거의 멤버 D3DTFP_LINEAR 로 나타내진다.
D3DPTFILTERCAPS_MIPFPOINT
디바이스는, 스테이지 단위에서의 밉맵이기 때문에, 포인트 샘플 필터링을 지원 한다. 포인트 샘플 밉맵 필터는,CONST_D3DTEXTUREMIPFILTER 열거의 멤버 D3DTFP_POINT 로 나타내진다.


CONST_D3DCLEARFLAGS

CONST_D3DCLEARFLAGS 열거는,Direct3DDevice7.Clear 메소드의 동작을 결정하는 플래그를 정의한다.

Enum CONST_D3DCLEARFLAGS
    D3DCLEAR_ALL = 7
    D3DCLEAR_STENCIL = 4
    D3DCLEAR_TARGET = 1
    D3DCLEAR_ZBUFFER = 2
End Enum
D3DCLEAR_ALL
렌더링 타겟, 스텐실 버퍼, 및 깊이 버퍼 표면을 클리어 한다.
D3DCLEAR_STENCIL
스텐실 버퍼를 클리어 해,stencil 파라미터의 값으로 한다.
D3DCLEAR_TARGET
렌더링 타겟을 클리어 해,color 파라미터의 색으로 한다.
D3DCLEAR_ZBUFFER
깊이 버퍼를 클리어 해,z 파라미터의 값으로 한다.


CONST_D3DCLIPFLAGS

CONST_D3DCLIPFLAGS 열거는,Direct3DDevice7.ComputeSphereVisibility 메소드에 의해 돌려주어지는 클리핑 플래그를 정의한다.

Enum CONST_D3DCLIPFLAGS
    D3DSTATUS_CLIPINTERSECTIONALL = 17891328
    D3DSTATUS_CLIPUNIONALL = 17891328
    D3DSTATUS_DEFAULT = 34668544
    D3DSTATUS_ZNOTVISIBLE = 16777216
    D3DSTATUS_CLIPINTERSECTIONBACK = 131072
    D3DSTATUS_CLIPINTERSECTIONBOTTOM = 32768
    D3DSTATUS_CLIPINTERSECTIONFRONT = 65536
    D3DSTATUS_CLIPINTERSECTIONGEN0 = 262144
    ' D3DSTATUS_CLIPINTERSECTIONGEN1 to D3DSTATUS_CLIPINTERSECTIONGEN4
    ' omitted here for brevity.
    D3DSTATUS_CLIPINTERSECTIONGEN5 = 8388608
    D3DSTATUS_CLIPINTERSECTIONLEFT = 4096
    D3DSTATUS_CLIPINTERSECTIONRIGHT = 8192
    D3DSTATUS_CLIPINTERSECTIONTOP = 16384
    D3DSTATUS_CLIPUNIONBACK = 32
    D3DSTATUS_CLIPUNIONBOTTOM = 8
    D3DSTATUS_CLIPUNIONFRONT = 16
    D3DSTATUS_CLIPUNIONGEN0 = 64
    ' D3DSTATUS_CLIPUNIONGEN1 to D3DSTATUS_CLIPUNIONGEN4
    ' omitted here for brevity.
    D3DSTATUS_CLIPUNIONGEN5 = 2048
    D3DSTATUS_CLIPUNIONLEFT = 1
    D3DSTATUS_CLIPUNIONRIGHT = 2
    D3DSTATUS_CLIPUNIONTOP = 4
    D3DCLIP_BACK = 32
    D3DCLIP_BOTTOM = 8
    D3DCLIP_FRONT = 16
    D3DCLIP_GEN0 = 64
    ' D3DCLIP_GEN1 to D3DCLIP_GEN4 omitted here for brevity.
    D3DCLIP_GEN5 = 2048
    D3DCLIP_LEFT = 1
    D3DCLIP_RIGHT = 2
    D3DCLIP_TOP = 4
End Enum

편성과 일반 플래그

D3DSTATUS_CLIPINTERSECTIONALL
모든 CLIPINTERSECTION 플래그의 편성.
D3DSTATUS_CLIPUNIONALL
모든 CLIPUNION 플래그의 편성.
D3DSTATUS_DEFAULT
D3DSTATUS_CLIPINTERSECTIONALL 와 D3DSTATUS_ZNOTVISIBLE 플래그의 편성. 이 값이, 디폴트이다.
D3DSTATUS_ZNOTVISIBLE
렌더링 된 프리미티브가 불가시인 것을 나타낸다. 이 플래그는, z 체크를 사용하는 렌더링이 유효화 된 시점에서, 시스템에 의해 세트, 또는 클리어 된다 (D3DRENDERSTATE_ZVISIBLE 참조).

클립 교차 플래그

D3DSTATUS_CLIPINTERSECTIONBACK
절두체의후방 클립면의 버텍스의 클리핑 플래그의 논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONBOTTOM
절두체아래의 버텍스의 클리핑 플래그의 논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONFRONT
절두체의전방 클립면의 버텍스의 클리핑 플래그의 논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONGEN0 through D3DSTATUS_CLIPINTERSECTIONGEN5
어플리케이션 정의의 클립면의 클리핑 플래그의 논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONLEFT
절두체의 좌측의 버텍스의 클리핑 플래그의 논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONRIGHT
절두체의 우측의 버텍스의 클리핑 플래그의 논리츠무를 잡는다.
D3DSTATUS_CLIPINTERSECTIONTOP
절두체의 위에의 버텍스의 클리핑 플래그의 논리츠무를 잡는다.

클립 결합 플래그

D3DSTATUS_CLIPUNIONBACK
D3DCLIP_BACK 와 같다.
D3DSTATUS_CLIPUNIONBOTTOM
D3DCLIP_BOTTOM 와 같다.
D3DSTATUS_CLIPUNIONFRONT
D3DCLIP_FRONT 와 같다.
D3DSTATUS_CLIPUNIONGEN0 through D3DSTATUS_CLIPUNIONGEN5
D3DCLIP_GEN0 로부터 D3DCLIP_GEN5 와 같다.
D3DSTATUS_CLIPUNIONLEFT
D3DCLIP_LEFT 와 같다.
D3DSTATUS_CLIPUNIONRIGHT
D3DCLIP_RIGHT 와 같다.
D3DSTATUS_CLIPUNIONTOP
D3DCLIP_TOP 와 같다.

기본 클리핑 플래그

D3DCLIP_BACK
모든 버텍스를절두체의 뒷면에서 클리핑 한다.
D3DCLIP_BOTTOM
모든 버텍스를절두체의 저면에서 클리핑 한다.
D3DCLIP_FRONT
모든 버텍스를절두체의 전면에서 클리핑 한다.
D3DCLIP_LEFT
모든 버텍스를절두체의 좌측면에서 클리핑 한다.
D3DCLIP_RIGHT
모든 버텍스를절두체의 우측면에서 클리핑 한다.
D3DCLIP_TOP
모든 버텍스를절두체의 표면에서 클리핑 한다.
D3DCLIP_GEN0 through D3DCLIP_GEN5
모든 버텍스를 대응하는 어플리케이션 정의 클립면에서 클리핑 한다.


CONST_D3DCLIPPLANEFLAGS

CONST_D3DCLIPPLANEFLAGS 열거는,D3DRENDERSTATE_CLIPPLANEENABLE 렌더링 스테이트에서 사용되는 플래그를 정의한다.

Type CONST_D3DCLIPPLANEFLAGS
    D3DCPF_DISABLEALL = 0
    D3DCPF_ENABLEPLANE0 = 1
    '
    ' D3DCPF_ENABLEPLANE1 to D3DCPF_ENABLEPLANE30 ommitted here.
    '
    D3DCPF_ENABLEPLANE31 = -2147483648
End Type
D3DCPF_DISABLEALL
모든 클립면을 무효로 한다. 이 플래그를 다른 플래그와 조합해 사용할 수 없다.
D3DCPF_ENABLEPLANE0 through D3DCPF_ENABLEPLANE31
대응하는 인덱스에 있는 클립면을 유효하게 한다. 이 값을 조합해, 복수의 클립면을 같게 유효하게 할 수가 있다.

참조

CONST_D3DRENDERSTATETYPE


CONST_D3DCLIPSTATUSFLAGS

CONST_D3DCLIPSTATUSFLAGS 열거는,D3DCLIPSTATUS 형으로 사용되는 플래그를 정의한다.

Enum CONST_D3DCLIPSTATUSFLAGS
    D3DCLIPSTATUS_EXTENTS2 = 2
    D3DCLIPSTATUS_EXTENTS3 = 4
    D3DCLIPSTATUS_STATUS = 1
End Enum
D3DCLIPSTATUS_EXTENTS2
형태는 현재의 2D 영역을 기술한다. 이 플래그는 D3DCLIPSTATUS_EXTENTS3 와 조합할 수 없다.
D3DCLIPSTATUS_EXTENTS3
현재는 이행되어 있지 않다.
D3DCLIPSTATUS_STATUS
형태는 현재의 클립 스테이터스를 기술한다.


CONST_D3DCMPFUNC

CONST_D3DCMPFUNC 열거는,D3DRENDERSTATE_ZFUNC ,D3DRENDERSTATE_ALPHAFUNC , 및 D3DRENDERSTATE_STENCILFUNC 렌더링 스테이트를 위해서(때문에) 지원 되는 비교 함수를 정의한다.

Enum CONST_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
End Enum
D3DCMP_NEVER
항상 테스트는 실패한다.
D3DCMP_LESS
새로운 픽셀값이, 현재의 픽셀값보다 작을 때에 응한다.
D3DCMP_EQUAL
새로운 픽셀값이, 현재의 픽셀값과 동일할 때에 응한다.
D3DCMP_LESSEQUAL
새로운 픽셀값이, 현재의 픽셀값이하 때에 응한다.
D3DCMP_GREATER
새로운 픽셀값이, 현재의 픽셀값보다 클 때에 응한다.
D3DCMP_NOTEQUAL
새로운 픽셀값이, 현재의 픽셀값과 동일하지 않을 때에 응한다.
D3DCMP_GREATEREQUAL
새로운 픽셀값이, 현재의 픽셀값이상 때에 응한다.
D3DCMP_ALWAYS
항상 테스트는 패스한다.


CONST_D3DCOLORMODEL

CONST_D3DCOLORMODEL 열거는, 시스템이 동작하는 컬러 모델을 정의하는데 사용된다. 드라이버는 어느 쪽인가의 플래그, 또는 양쪽 모두의 플래그를,D3DDEVICEDESC7 형의 CONST_COLORMODEL 멤버를 사용해 가리킬 수가 있다.

Enum CONST_D3DCOLORMODEL
    D3DCOLOR_MONO = 1
    D3DCOLOR_RGB = 2
End Enum
D3DCOLOR_MONO
흑백 모델 (램프 모델)을 사용한다. 이 모델로, 버텍스색의 파랑의 값은, 버텍스의 휘도(Luminance)를 정의하기 위해서 사용된다.
D3DCOLOR_RGB
완전한 RGB 모델을 사용한다


CONST_D3DCULL

CONST_D3DCULL 열거는,D3DRENDERSTATE_CULLMODE 렌더링 스테이트를 위해서(때문에) 지원 되는 컬링(Culling) 모드를 정의한다. 지오메트리에 렌더링 하면나무의 면의 컬링(Culling) 방법을 정의한다.

Enum CONST_D3DCULL
    D3DCULL_NONE = 1
    D3DCULL_CW   = 2
    D3DCULL_CCW  = 3
End Enum
D3DCULL_NONE
컬링(Culling)는 하지 않는다.
D3DCULL_CW
우회전으로 컬링(Culling) 한다.
D3DCULL_CCW
왼쪽 돌아에 컬링(Culling) 한다.

참조

D3DPRIMCAPS ,CONST_D3DRENDERSTATETYPE


CONST_D3DDEVICEDESCCAPS

CONST_D3DDEVICEDESCCAPS 열거는,D3DDEVICEDESC7 형의 lDevCaps 멤버로 사용되는 디바이스 능력 플래그를 정의한다.

Enum CONST_D3DDEVICEDESCCAPS
    D3DDEVCAPS_CANBLTSYSTONONLOCAL = 131072
    D3DDEVCAPS_CANRENDERAFTERFLIP = 2048
    D3DDEVCAPS_DRAWPRIMTLVERTEX = 1024
    D3DDEVCAPS_FLOATTLVERTEX = 1
    D3DDEVCAPS_HWRASTERIZATION = 524288
    D3DDEVCAPS_HWTRANSFORMANDLIGHT = 65536
    D3DDEVCAPS_SEPARATETEXTUREMEMORIES = 16384
    D3DDEVCAPS_SORTDECREASINGZ = 4
    D3DDEVCAPS_SORTEXACT = 8
    D3DDEVCAPS_SORTINCREASINGZ = 2
    D3DDEVCAPS_TEXTURENONLOCALVIDMEM = 4096
    D3DDEVCAPS_TEXTURESYSTEMMEMORY = 256
    D3DDEVCAPS_TEXTUREVIDEOMEMORY = 512
    D3DDEVCAPS_TLVERTEXSYSTEMMEMORY = 64
    D3DDEVCAPS_TLVERTEXVIDEOMEMORY = 128
End Enum
D3DDEVCAPS_CANBLTSYSTONONLOCAL
디바이스는, 시스템 메모리 텍스쳐로부터 비로컬 비디오 메모리 텍스쳐에의 블리트를 지원 한다.
D3DDEVCAPS_CANRENDERAFTERFLIP
디바이스는 페이지 플립의 다음에, 렌더링 커멘드를 기다릴 수도 있다. 어플리케이션은 이 플래그가 세트 되어도, 그 동작을 바꾸어서는 안된다. 이 능력은, 단지 디바이스가 상대적으로 빠른 일을 의미할 뿐이다.
D3DDEVCAPS_DRAWPRIMTLVERTEX
디바이스는, DrawPrimitive 아웨아 HAL 를 export 한다.
D3DDEVCAPS_FLOATTLVERTEX
디바이스는, 트랜스 폼 후의 버텍스 데이터를 부동 소수점으로써 취득한다.
D3DDEVCAPS_HWRASTERIZATION
디바이스에, 장면의 라스터화용의 하드웨어 가속화 기능이 있다.
D3DDEVCAPS_HWTRANSFORMANDLIGHT
디바이스는, 하드웨어에서의 트랜스 폼 & 라이팅을 지원 한다.
D3DDEVCAPS_SEPARATETEXTUREMEMORIES
디바이스는, 스테이지 마다 다른 텍스쳐 메모리 풀을 사용한다. 텍스쳐는, 생성시에,DDSURFACEDESC2 형의 lTextureStage 멤버에 적절한 스테이지 식별자를 설정해, 명시적으로 텍스쳐 스테이지에 할당해 두지 않으면 안 된다.
D3DDEVCAPS_SORTDECREASINGZ
깊이의 감소 방향으로 소트 된 데이터가 필요.
D3DDEVCAPS_SORTEXACT
정밀하게 소트 된 데이터가 필요.
D3DDEVCAPS_SORTINCREASINGZ
깊이의 증가 방향으로 소트 된 데이터가 필요.
D3DDEVCAPS_TEXTURENONLOCALVIDMEM
디바이스는, 비로컬 비디오 (AGP) 메모리를 취득할 수 있다. AGP 메모리의 자세한 것은, DirectDraw 문서의 「비로컬 비디오 메모리 표면의 사용」을 참조할것.
D3DDEVCAPS_TEXTURESYSTEMMEMORY
시스템 메모리로부터 텍스쳐를 취득 가능.
D3DDEVCAPS_TEXTUREVIDEOMEMORY
디바이스 메모리로부터 텍스쳐를 취득 가능.
D3DDEVCAPS_TLVERTEXSYSTEMMEMORY
트랜스 폼이 끝난 라이팅 끝난 버텍스용으로, 시스템 메모리를 버퍼에 사용 가능.
D3DDEVCAPS_TLVERTEXVIDEOMEMORY
트랜스 폼이 끝난 라이팅 끝난 버텍스용으로, 비디오 메모리를 버퍼에 사용 가능.


CONST_D3DDEVICEDESCFLAGS

CONST_D3DDEVICEDESCFLAGS 열거는,D3DDEVICEDESC7 형의 lFlags 멤버로 사용되는 플래그를 정의한다.

Enum CONST_D3DDEVICEDESCFLAGS
    D3DDD_BCLIPPING = 16
    D3DDD_DEVCAPS = 2
    D3DDD_DEVICERENDERBITDEPTH = 128
    D3DDD_DEVICEZBUFFERBITDEPTH = 256
    D3DDD_LIGHTINGCAPS = 8
    D3DDD_LINECAPS = 32
    D3DDD_MAXBUFFERSIZE = 512
    D3DDD_MAXVERTEXCOUNT = 1024
    D3DDD_TRANSFORMCAPS = 4
    D3DDD_TRICAPS = 64
End Enum
D3DDD_BCLIPPING
D3DDEVICEDESC7 형의 lClipping 멤버가 유효.
D3DDD_DEVCAPS
D3DDEVICEDESC7 형의 lDevCaps 멤버가 유효.
D3DDD_DEVICERENDERBITDEPTH
D3DDEVICEDESC7 형의 lDeviceRenderBitDepth 멤버가 유효.
D3DDD_DEVICEZBUFFERBITDEPTH
D3DDEVICEDESC7 형의 lDeviceZBufferBitDepth 멤버가 유효.
D3DDD_LIGHTINGCAPS
D3DDEVICEDESC7 형의 dlcLightingCaps 멤버가 유효.
D3DDD_LINECAPS
D3DDEVICEDESC7 형의 dpcLineCaps 멤버가 유효.
D3DDD_MAXBUFFERSIZE
D3DDEVICEDESC7 형의 lMaxBufferSize 멤버가 유효.
D3DDD_MAXVERTEXCOUNT
D3DDEVICEDESC7 형의 lMaxVertexCount 멤버가 유효.
D3DDD_TRANSFORMCAPS
D3DDEVICEDESC7 형의 lTransformCaps 멤버가 유효.
D3DDD_TRICAPS
D3DDEVICEDESC7 형의 dpcTriCaps 멤버가 유효.


CONST_D3DDEVINFOID

CONST_D3DDEVINFOID 열거는,Direct3DDevice7.GetInfo 메소드로 사용되는 플래그를 정의한다.

Enum CONST_D3DDEVINFOID
    D3DDEVINFOID_D3DTEXTUREMANAGER = 2
    D3DDEVINFOID_TEXTUREMANAGER = 1
    D3DDEVINFOID_TEXTURING = 3
End Enum
D3DDEVINFOID_D3DTEXTUREMANAGER
GetInfo 메소드의 DevInfoType 파라미터에 있는 형태는, Direct3D 에 의해 실행되는 텍스쳐 관리의 정보를 저장 하는 D3DDEVINFO_TEXTUREMANAGER 형이다.
D3DDEVINFOID_TEXTUREMANAGER
GetInfo 메소드의 DevInfoType 파라미터에 있는 형태는, 드라이버에 의해 실행되는 텍스쳐 관리의 정보를 저장 하는 D3DDEVINFO_TEXTUREMANAGER 형이다. 드라이버가 텍스쳐를 관리하지 않는 경우, Direct3D 에 의해 실행되는 텍스쳐 관리의 정보가 취득된다.
D3DDEVINFOID_TEXTURING
GetInfo 메소드의 DevInfoType 파라미터에 있는 형태는, 어플리케이션의 텍스쳐링 액티버티의 정보를 저장 하는 D3DDEVINFO_TEXTURING 형이다.

참조

Direct3DDevice7.GetInfo


CONST_D3DDPFLAGS

CONST_D3DDPFLAGS 열거는, Direct3D 의 렌더링 메소드의 동작을 결정하는 플래그를 정의한다. 이러한 플래그는,Direct3DDevice7.DrawPrimitive ,Direct3DDevice7.DrawIndexedPrimitive ,Direct3DDevice7.DrawPrimitiveVB , 및 Direct3DDevice7.DrawIndexedPrimitiveVB 로 사용된다.

Enum CONST_D3DDPFLAGS
    D3DDP_DEFAULT = 0
    D3DDP_WAIT = 1
End Enum
D3DDP_DEFAULT
보통의 렌더링을 실시한다 (다각형이 카드로 보내지자마자 돌아간다).
D3DDP_WAIT
메소드는, 다각형이 카드로 보내지자마자 돌아가는 것이 아니라, 렌더링이 끝날 때까지 기다린다. (장면 캡춰 카드로는, 카드로부터의 응답이 있는 대로, 메소드는 돌아간다). 이 플래그는 디버그에 자주(잘) 사용된다. 어플리케이션은, 장면을 먼저 진행하기 전에 확실히 갱신해 두기 위해서(때문에)도, 이 플래그를 사용해서는 안된다.


CONST_D3DFILLMODE

CONST_D3DFILLMODE 열거는, 전부 칠해 모드를 지정하는 정수를 설정한다. 이러한 값은,CONST_D3DRENDERSTATETYPE 열거의 CONST_D3DFILLMODE 렌더링 스테이트를 위해서(때문에) 사용된다.

Enum CONST_D3DFILLMODE
    D3DFILL_POINT     = 1
    D3DFILL_WIREFRAME = 2
    D3DFILL_SOLID     = 3
End Enum
D3DFILL_POINT
점으로써 전부 칠한다.
D3DFILL_WIREFRAME
와이어 프레임으로 전부 칠한다. 이 전부 칠해 모드는, DrawPrimitive 메소드 사용시, 클립 된 원시적인 것은 동작하지 않는다.
D3DFILL_SOLID
면에서 전부 칠한다.


CONST_D3DFOGMODE

CONST_D3DFOGMODE 열거는, 포그(안개:fog) 모드를 지정하는 정수를 설정한다. 이러한 값은,CONST_D3DRENDERSTATETYPE 열거의 D3DRENDERSTATE_FOGTABLEMODE 및 D3DRENDERSTATE_FOGVERTEXMODE 렌더링 스테이트에서 사용된다.

Enum CONST_D3DFOGMODE
    D3DFOG_NONE   = 0
    D3DFOG_EXP    = 1
    D3DFOG_EXP2   = 2
    D3DFOG_LINEAR = 3
End Enum
D3DFOG_NONE
포그(안개:fog) 이펙트는 없다.
D3DFOG_EXP
다음의 방정식의 지수로, 포그(안개:fog) 이펙트가 늘어난다.

D3DFOG_EXP2
다음의 방정식의 지수의 2 승으로, 포그(안개:fog) 이펙트가 늘어난다.

D3DFOG_LINEAR
다음의 방정식의 시점과 종점의 사이에 선형에, 포그(안개:fog) 이펙트가 늘어난다.

이것은, 현재 지원 되고 있는 유일한 포그(안개:fog) 모드이다.

주의

흑백 (램프) 라이팅 모드에서는, 포그(안개:fog)는 그 색이 흑의 경우에 한정해 정상적으로 기능한다 (라이트가 존재하지 않는 경우에는, 모든 포그(안개:fog) 컬러가 기능한다. 그 경우에는, 모든 포그(안개:fog) 컬러가 실제상은 흑이니까이다).

포그(안개:fog)의 상세한 것에 대하여는, 「포그(안개:fog)」를 참조할것.

주 : 포그(안개:fog)는, 투명도를 나타내는 기준이다. 이 경우, 포그(안개:fog)의 값이 작을 정도(수록), 오브젝트가 안보이게 된다.


CONST_D3DFVFCAPSFLAGS

CONST_D3DFVFCAPSFLAGS 열거는,D3DDEVICEDESC7 형의 lFVFCaps 멤버로 사용되는 값을 정의한다.

Enum CONST_D3DFVFCAPSFLAGS
    D3DFVFCAPS_DONOTSTRIPELEMENTS = 524288
    D3DFVFCAPS_TEXCOORDCOUNTMASK = 65535
End Enum
D3DFVFCAPS_DONOTSTRIPELEMENTS
디바이스는, 버텍스 요소의 스트립을 요구하지 않는다. 즉, 버텍스 포맷이, 현재의 렌더링 스테이트에서 사용되지 않는 요소를 저장 하고 있어도, 버텍스를 재생성할 필요는 없다. 이 능력 플래그가 존재하지 않는 경우, 버텍스 포맷화등 불필요한 요소를 삭제 하면, 퍼포먼스가 향상한다.
D3DFVFCAPS_TEXCOORDCOUNTMASK
D3DDEVICEDESC7 형의 lFVFCaps 멤버의 하위 16 비트를 마스크 하는데 사용한다. 결과를 정수형의 변수로 설정해, 디바이스가 복수의 텍스쳐 블렌딩으로 동시에 사용할 수 있는 텍스쳐 좌표 세트의 총수를 계산한다 (1 개의 버텍스에 최대 8 개의 버텍스 좌표 세트를 사용할 수 있지만, 디바이스는 블렌딩으로 지정된 수의 텍스쳐 좌표 세트 밖에 사용할 수 없다).

주의

이하의 Visual Basic 코드에서는,lFVFCaps 멤버의 하위 16 비트를 마스크 해, 디바이스가 복수의 텍스쳐 블렌딩으로 동시에 사용할 수 있는 텍스쳐 좌표 세트의 총수를 지정한다.

Dim HALdesc As D3DDEVICEDESC7, HELdesc As D3DDEVICEDESC7
Dim iTexCoords As Integer

' d3ddevice 변수는, 유효한 Direct3DDevice3 오브젝트에의
'참조라고 보여진다.
Call d3ddevice.GetCaps(HALDesc, HELDesc)

'하위 16 비트를 마스크 해 정수형 변수로 설정한다.
iTexCoords = (HALDesc.lFVFCaps And D3DFVFCAPS_TEXCOORDCOUNTMASK)


CONST_D3DFVFFLAGS

CONST_D3DFVFFLAGS 열거는, DrawPrimitive 렌더링 메소드로 사용되는 유연한 버텍스 포맷 플래그를 정의한다. 상세한 것에 대하여는, 「유연한 버텍스 포맷 플래그」를 참조할것.


CONST_D3DIMERR

CONST_D3DIMERR 열거는, 시스템에 의해 기동되는 에러 코드로, 불필요한 것을 정의한다. 이러한 에러 코드에 대해서는, 「에러 코드」를 참조할것.


CONST_D3DLIGHTTYPE

CONST_D3DLIGHTTYPE 열거는, 광원의 형태를 나타내는 플래그를 정의한다. 이러한 플래그는,D3DLIGHT7 형의 lType 멤버로 사용된다.

Enum CONST_D3DLIGHTTYPE
    D3DLIGHT_DIRECTIONAL = 3
    D3DLIGHT_POINT = 1
    D3DLIGHT_SPOT = 2
End Enum
D3DLIGHT_DIRECTIONAL
광원은디렉셔널이다. 이것은 무한대의 거리로 점광원을 이용하는 것에 동일하다.
D3DLIGHT_POINT
광원은 점이다. 빛은 공간내의 점을 가져, 전방향으로 빛을 방사한다.
D3DLIGHT_SPOT
광원은 spotlight이다. 이 빛은, 조사가 원추내에 제한되고 있는 이외는 광점을 닮아 있다. 이 광원의 형태는 방향, 및 그 외의 원추의 형태를 결정하는 몇 개의 파라미터를 가진다. 이러한 파라미터에 대해서는,D3DLIGHT7 형을 참조할것.


CONST_D3DMATERIALCOLORSOURCE

CONST_D3DMATERIALCOLORSOURCE 열거는, 라이팅 계산에 사용하는 색 또는 색성분의 위치를 정의한다.

Enum CONST_D3DMATERIALCOLORSOURCE
    D3DMCS_MATERIAL    = 0
    D3DMCS_COLOR1      = 1
    D3DMCS_COLOR2      = 2
End Enum
D3DMCS_MATERIAL
현재의 머트리얼의 색을 사용한다.
D3DMCS_COLOR1
디 푸즈 버텍스색을 사용한다.
D3DMCS_COLOR2
스펙큐러 버텍스색을 사용한다.

주의

이 열거로 정의된 값은,D3DRENDERSTATE_DIFFUSEMATERIALSOURCE ,D3DRENDERSTATE_SPECULARMATERIALSOURCE ,D3DRENDERSTATE_AMBIENTMATERIALSOURCE , 및 D3DRENDERSTATE_EMISSIVEMATERIALSOURCE 렌더링 스테이트에서 사용된다.


CONST_D3DPRIMITIVETYPE

CONST_D3DPRIMITIVETYPE 열거는, DrawPrimitive 메소드로 지원 되는 프리미티브를 열거한다.

Enum CONST_D3DPRIMITIVETYPE
    D3DPT_POINTLIST     = 1
    D3DPT_LINELIST      = 2
    D3DPT_LINESTRIP     = 3
    D3DPT_TRIANGLELIST  = 4
    D3DPT_TRIANGLESTRIP = 5
    D3DPT_TRIANGLEFAN   = 6
End Enum
D3DPT_POINTLIST
버텍스를 별개의 점의 집적으로서 렌더링 한다.
D3DPT_LINELIST
별개의 선분의 리스트로서 버텍스를 렌더링 한다. 이 프리미티브형을 사용하는 호출은, 카운트가 2 보다 작은지, 홀수의 경우에 실패에 끝난다.
D3DPT_LINESTRIP
버텍스를 단일의 polyline로서 렌더링 한다. 이 프리미티브형을 사용하는 호출은, 카운트가 2 보다 작은 경우에 실패에 끝난다.
D3DPT_TRIANGLELIST
별개의 삼각형의 연속으로서 지정의 버텍스를 렌더링 한다. 각 3 버텍스의 그룹이 별개의 삼각형을 정의한다. 이 프리미티브형을 사용하는 호출은, 카운트가 3 보다 작은 경우, 혹은 3 으로 나뉘어 떨어지지 않는 경우에 실패에 끝난다.

이면의 선택은, 현재의 와인딘그순서 렌더링 스테이트에 의해 영향을 받는다.

D3DPT_TRIANGLESTRIP
버텍스를 삼각형 스트립으로서 렌더링 한다. 이 프리미티브형을 사용하는 호출은, 카운트가 3 보다 작은 경우에 실패에 끝난다. 이면 삭제 플래그는 자동적으로, 짝수차례의 삼각형상에서 반전한다.
D3DPT_TRIANGLEFAN
버텍스를 삼각형 팬으로서 렌더링 한다. 이 프리미티브형을 사용하는 호출은, 카운트가 3 보다 작은 경우에 실패에 끝난다.

주의

별개의 삼각형의 연속보다 (중복 하는 버텍스의 수를 줄일 수 있으므로) 삼각형 스트립이나 선형을 사용한 (분)편이 효율이 좋은 일이 많다. 삼각형 스트립이나 선형의 정의에 관한 개요와 자세한 정보에 대해서는, 「삼각형 스트립」과「삼각형 팬」을 참조할것.

참조

Direct3DDevice7.DrawIndexedPrimitive ,Direct3DDevice7.DrawPrimitive ,프리미티브의 종류


CONST_D3DPROCESSVERTICESFLAGS

CONST_D3DPROCESSVERTICESFLAGS 열거는,Direct3DVertexBuffer7.ProcessVertices 메소드로 사용되는 플래그를 정의한다.

Enum CONST_D3DPROCESSVERTICESFLAGS
    D3DPV_DEFAULT = 0
    D3DPV_DONOTCOPYDATA = 1
End Enum
D3DPV_DEFAULT
현재의 버텍스 조작을 사용해 표준의 버텍스의 처리를 실시한다.
D3DPV_DONOTCOPYDATA
현재의 버텍스의 처리에 의해 영향을 받는 버텍스 데이터만을 목적지 버퍼에 넣는다.

참조

Direct3DVertexBuffer7.ProcessVertices ,버텍스의 처리


CONST_D3DRENDERSTATESINGLE

CONST_D3DRENDERSTATESINGLE 열거는,Direct3DDevice7.SetRenderStateSingle 과 Direct3DDevice7.GetRenderStateSingle 메소드에 의해 설정 및 취득되는 디바이스 렌더링 스테이트를 정의한다.

Type CONST_D3DRENDERSTATESINGLE
    D3DRENDERSTATE_FOGDENSITY = 38
    D3DRENDERSTATE_FOGEND     = 37
    D3DRENDERSTATE_FOGSTART   = 36
End Type
D3DRENDERSTATE_FOGDENSITY
지수 포그(안개:fog) 모드 (D3DFOG_EXP 와 D3DFOG_EXP2)로 사용하는 픽셀 포그(안개:fog)를 위한 포그(안개:fog) 밀도. 밀도의 유효한 값은 0.0 에서 1.0 의 범위내이다. 디폴트값은 1,0 이다. 상세한 것에 대하여는, 「포그(안개:fog) 파라미터」를 참조할것.
D3DRENDERSTATE_FOGEND
선형 포그(안개:fog) 모드로, 픽셀 포그(안개:fog) 이펙트가 시작 하는 깊이와 종료하는 깊이. 깊이는, 버텍스 포그(안개:fog)의 경우는 월드 공간에서, 픽셀 포그(안개:fog)의 경우는 디바이스 공간 [0.0, 1.0] 또는 월드 공간의 어느쪽이든으로 지정한다. 픽셀 포그(안개:fog)의 경우, 시스템이 포그(안개:fog) 계산에 z 를 사용할때에는 디바이스 공간에서, 눈으로부터 상대적인 포그(안개:fog) (w 포그(안개:fog))를 사용할때에는 월드 공간에서 지정한다. 상세한 것에 대하여는, 「포그(안개:fog) 파라미터」와「시점으로부터의 상대 깊이대 Z 베이스의 깊이」를 참조할것.

이러한 렌더링 스테이트에 의해, 카메라에 가까운 위치의 포그(안개:fog) 이펙트를 제외하는 것이 가능하게 된다. 예를 들어, 시작 깊이에 0.3 을 설정 하면, 0.0 에서 0.299 의 범위의 깊이에 대한 포그(안개:fog) 이펙트가 제외되어 종료 깊이에 0.7 을 설정 하면, 0.701 에서 1.0 의 범위의 깊이에 대한 포그(안개:fog) 이펙트가 제외된다.

D3DRENDERSTATE_FOGSTART
선형 포그(안개:fog) 모드로, 픽셀 포그(안개:fog) 이펙트가 시작 하는 깊이와 종료하는 깊이. 깊이는, 버텍스 포그(안개:fog)의 경우는 월드 공간에서, 픽셀 포그(안개:fog)의 경우는 디바이스 공간 [0.0, 1.0] 또는 월드 공간의 어느쪽이든으로 지정한다. 픽셀 포그(안개:fog)의 경우, 시스템이 포그(안개:fog) 계산에 z 를 사용할때에는 디바이스 공간에서, 눈으로부터 상대적인 포그(안개:fog) (w 포그(안개:fog))를 사용할때에는 월드 공간에서 지정한다. 상세한 것에 대하여는, 「포그(안개:fog) 파라미터」와「시점으로부터의 상대 깊이대 Z 베이스의 깊이」를 참조할것.

이러한 렌더링 스테이트에 의해, 카메라에 가까운 위치의 포그(안개:fog) 이펙트를 제외하는 것이 가능하게 된다. 예를 들어, 시작 깊이에 0.3을 설정 하면, 0.0 에서 0.299 의 범위의 깊이에 대한 포그(안개:fog) 이펙트가 제외되어 종료 깊이에 0.7 을 설정 하면, 0.701 에서 1.0 의 범위의 깊이에 대한 포그(안개:fog) 이펙트가 제외된다.

참조

Direct3DDevice7.SetRenderStateSingle ,Direct3DDevice7.GetRenderStateSingle


CONST_D3DRENDERSTATETYPE

CONST_D3DRENDERSTATETYPE 열거는,Direct3DDevice7.SetRenderState 과 Direct3DDevice7.GetRenderState 메소드로 설정 및 취득되는 디바이스 렌더링 스테이트를 정의한다.

Enum CONST_D3DRENDERSTATETYPE
    D3DRENDERSTATE_ALPHABLENDENABLE      = 27
    D3DRENDERSTATE_ALPHAFUNC             = 25
    D3DRENDERSTATE_ALPHAREF              = 24
    D3DRENDERSTATE_ALPHATESTENABLE       = 15
    D3DRENDERSTATE_AMBIENT               = 139
    D3DRENDERSTATE_AMBIENTMATERIALSOURCE = 147
    D3DRENDERSTATE_ANTIALIAS             = 2
    D3DRENDERSTATE_CLIPPING              = 136
    D3DRENDERSTATE_CLIPPLANEENABLE       = 152
    D3DRENDERSTATE_COLORKEYBLENDENABLE   = 144
    D3DRENDERSTATE_COLORKEYENABLE        = 41
    D3DRENDERSTATE_COLORVERTEX           = 141
    D3DRENDERSTATE_CULLMODE              = 22
    D3DRENDERSTATE_DESTBLEND             = 20
    D3DRENDERSTATE_DIFFUSEMATERIALSOURCE = 145
    D3DRENDERSTATE_DITHERENABLE          = 26
    D3DRENDERSTATE_EDGEANTIALIAS         = 40
    D3DRENDERSTATE_EMISSIVEMATERIALSOURCE= 148
    D3DRENDERSTATE_EXTENTS            = 138
    D3DRENDERSTATE_FILLMODE           = 8
    D3DRENDERSTATE_FOGCOLOR           = 34
    D3DRENDERSTATE_FOGENABLE          = 28
    D3DRENDERSTATE_FOGTABLEMODE       = 35
    D3DRENDERSTATE_FOGVERTEXMODE      = 140
    D3DRENDERSTATE_LASTPIXEL          = 16
    D3DRENDERSTATE_LIGHTING           = 137
    D3DRENDERSTATE_LINEPATTERN        = 10
    D3DRENDERSTATE_LOCALVIEWER        = 142
    D3DRENDERSTATE_NORMALIZENORMALS   = 143
    D3DRENDERSTATE_RANGEFOGENABLE     = 48
    D3DRENDERSTATE_SHADEMODE          = 9
    D3DRENDERSTATE_SPECULARENABLE     = 29
    D3DRENDERSTATE_SPECULARMATERIALSOURCE = 146
    D3DRENDERSTATE_SRCBLEND           = 19
    D3DRENDERSTATE_STENCILENABLE      = 52
    D3DRENDERSTATE_STENCILFAIL        = 53
    D3DRENDERSTATE_STENCILFUNC        = 56
    D3DRENDERSTATE_STENCILMASK        = 58
    D3DRENDERSTATE_STENCILPASS        = 55
    D3DRENDERSTATE_STENCILREF         = 57
    D3DRENDERSTATE_STENCILWRITEMASK   = 59
    D3DRENDERSTATE_STENCILZFAIL       = 54
    D3DRENDERSTATE_STIPPLEDALPHA      = 33
    D3DRENDERSTATE_TEXTUREFACTOR      = 60
    D3DRENDERSTATE_TEXTUREPERSPECTIVE = 4
    D3DRENDERSTATE_VERTEXBLEND        = 151
    D3DRENDERSTATE_WRAP0              = 128
    ' Wrap render states 1 through 6 omitted here.
    D3DRENDERSTATE_WRAP7              = 135
    D3DRENDERSTATE_ZBIAS              = 47
    D3DRENDERSTATE_ZENABLE            = 7
    D3DRENDERSTATE_ZFUNC              = 23
    D3DRENDERSTATE_ZVISIBLE           = 30
    D3DRENDERSTATE_ZWRITEENABLE       = 14
End Type
D3DRENDERSTATE_ALPHABLENDENABLE
알파 블렌드에 의한 투명화를 유효하게 하는 경우, TRUE 에 세트 한다. 디폴트값은 FALSE 이다. 낡은 D3DRENDERSTATE_BLENDENABLE 렌더링 스테이트는, 이 멤버에 의해 옮겨놓을 수 있었다. 자세한 것은 주의를 참조.

D3DRENDERSTATE_COLORKEYENABLE 렌더링 스테이트를 이용해, 컬러 키 검색의 변환을 실행할 수 있다 (하드웨어 래스터라이저는 언제나 D3DRENDERSTATE_BLENDENABLE 렌더링 스테이트를 알파 블렌딩 변환 전용에 사용해 왔다).

알파 블렌딩의 타입은 D3DRENDERSTATE_SRCBLEND 와 D3DRENDERSTATE_DESTBLEND 렌더링 스테이트에 의해 결정된다. D3DRENDERSTATE_COLORKEYENABLE 과 함께 D3DRENDERSTATE_ALPHABLENDENABLE 를사용하면, 알파 블렌딩의 미묘한 컨트롤이 가능하게 된다.

어플리케이션은,D3DDEVICEDESC7 형의 3DDEVCAPS_DRAWPRIMTLVERTEX 플래그를 조사해, 이 렌더링 스테이트가 지원 되고 있는지 어떤지를 체크해야 한다.

D3DRENDERSTATE_ALPHAFUNC
CONST_D3DCMPFUNC 열거의 정수의 1 개. 디폴트값은 D3DCMP_ALWAYS 이다. 이 멤버는, 어플리케이션에 알파값을 기준으로 하는 픽셀의 수취나 받아 거부를 허가한다.
D3DRENDERSTATE_ALPHAREF
알파 테스트가 유효하게 설정되어 있는 경우에, 픽셀을 테스트하기 위한 기준 알파값을 지정하는 값. 이 값은, 0 에서 1 의 범위의 16:16 고정 소수점값으로 할 수 있다 (1,0 은 0x00010000 로 나타내진다). 디폴트값은 0,0 이다.
D3DRENDERSTATE_ALPHATESTENABLE
알파 테스트를 가능하게 하려면 , TRUE. 디폴트값은 FALSE 이다. 이 멤버는, 어플리케이션에, 알파값을 기준으로 한 픽셀의 수취나 받아 거부를 실시하는 테스트의 정지를 허가한다.

들어 오는 알파값은, D3DRENDERSTATE_ALPHAFUNC 렌더링 스테이트에 의해 제공되는 비교 함수를 이용해 참조 알파값이라고 비교된다. 이 모드가 가능하게 되면(자), 테스트가 성공했을 경우에 한정해, 알파 블렌딩이 일어난다.

D3DRENDERSTATE_AMBIENT
앰비언트 라이트의 색. 디폴트값은 0 이다. 이 렌더링 스테이트는, 종래의 D3DLIGHTSTATE_AMBIENT 라이팅 스테이트를 닮아 있다.
D3DRENDERSTATE_AMBIENTMATERIALSOURCE
라이팅 계산에 사용하는 앰비언트색의 소스. 유효한 값은,CONST_D3DMATERIALCOLORSOURCE 열거의 멤버. 디폴트값은 D3DMCS_COLOR2 이다.
D3DRENDERSTATE_ANTIALIAS
풀 신 anti-aliasing의 요구된 형태를 지정하는 CONST_D3DANTIALIASMODE 열거의 멤버의 1 개. 디폴트값은 D3DANTIALIAS_NONE 이다. 상세한 것에 대하여는, 「풀 신 anti-aliasing」와「anti-aliasing 스테이트」를 참조할것.

풀 신 anti-aliasing은, D3DPRASTERCAPS_ANTIALIASSORTINDEPENDENT 또는 D3DPRASTERCAPS_ANTIALIASSORTDEPENDENT 능력을 나타내는 디바이스에 한정해, 유효하게 할 수가 있다.

D3DRENDERSTATE_CLIPPING
Direct3D 에 의한 프리미티브의 클리핑을 가능하게 하는 경우는 제로 이외의 값, 불가로 하는 경우는 제로로 설정한다. 디폴트값은 제로 이외의 값이다.
D3DRENDERSTATE_CLIPPLANEENABLE
유저 정의의 클립면을 사용 가능 또는 불가로 한다. 유효한 값은,CONST_D3DCLIPPLANEFLAGS 열거의 값의 편성. 지정된 열거의 값에 대응하는 클립면이 사용 가능하게 된다. 디폴트의 값은 D3DCPF_DISABLEALL 이다.
D3DRENDERSTATE_COLORKEYBLENDENABLE
알파 블렌드에 의한 컬러 키잉을 가능하게 하는 경우는 제로 이외의 값에, 불가로 하는 경우는 제로로 설정한다. 알파 블렌드에 의한 컬러 키 모드에서는, 적합하는 텍스쳐 샘플의 알파와 색을 제로로 설정한다. 어플리케이션으로, 희망 그대로의 파기 또는 알파 블렌드 결과를 얻기 위해서(때문에)는, 알파 테스트와 알파 블렌드 모드를 설정할 필요가 있다.
D3DRENDERSTATE_COLORKEYENABLE
TRUE 는, 컬러 키 투과를 가능하게 한다. 디폴트값은 FALSE 이다. D3DRENDERSTATE_ALPHABLENDENABLE 와 함께 이 렌더링 스테이트를 사용해, 미세한 블렌딩 제어를 거두어 들일 수가 있다.

어플리케이션은,3DDEVICEDESC7 형의 D3DDEVCAPS_DRAWPRIMTLVERTEX 플래그를 조사해, 이 렌더링 스테이트가 지원 되고 있는지 어떤지를 체크할 필요가 있다.

컬러 키 투과가 유효의 경우, DDSD_CKSRCBLT 플래그에 의해 생성 된 텍스쳐 표면만이 영향을 받는다. DDSD_CKSRCBLT 플래그없이 생성 된 표면에는, 컬러 키 투과 이펙트가 나타난다.

D3DRENDERSTATE_COLORVERTEX
버텍스 단위 컬러를 유효하게 하려면 제로 이외의 값에, 무효로 하려면 제로로 설정한다. 디폴트값은 제로 이외의 값이다. 버텍스 단위 컬러를 사용 하면, 각 버텍스에 정의된 컬러를 라이팅 계산으로 사용할 수가 있다.

참조 「D3DRENDERSTATE_DIFFUSEMATERIALSOURCE 」, 「D3DRENDERSTATE_SPECULARMATERIALSOURCE 」, 「D3DRENDERSTATE_AMBIENTMATERIALSOURCE 」, 및 「D3DRENDERSTATE_EMISSIVEMATERIALSOURCE 」

D3DRENDERSTATE_CULLMODE
뒷면을 향하는 삼각형을 잘라낼 필요가 생겼을 경우에, 그방법을 지정한다. 이 값은,CONST_D3DCULL 열거의 정수의 1 개로 설정할 수 있다. 디폴트값은 D3DCULL_CCW 이다.
D3DRENDERSTATE_DESTBLEND
CONST_D3DBLEND 열거의 정수의 1 개. 디폴트값은 D3DBLEND_ZERO 이다.
D3DRENDERSTATE_DIFFUSEMATERIALSOURCE
라이팅 계산으로 사용하는 디퓨즈색의 소스. 유효한 값은,CONST_D3DMATERIALCOLORSOURCE 열거의 멤버. 디폴트값은 D3DMCS_COLOR1 이다. 이 렌더링 스테이트의 값은, D3DRENDERSTATE_COLORVERTEX 렌더링 스테이트가 제로 이외의 값으로 설정되어 있는 경우만 사용된다.
D3DRENDERSTATE_DITHERENABLE
TRUE 때, 디저링을 가능으로 한다. 디폴트값은 FALSE 이다.
D3DRENDERSTATE_EDGEANTIALIAS
TRUE 는, 오브젝트의 철면의 윤곽을 형성하는 선을 에일리어징 제거 한다. 디폴트값은 FALSE 이다. 상세한 것에 대하여는, 「엣지 anti-aliasing」와「anti-aliasing 스테이트」를 참조할것. TRUE 로 설정했을 경우, 어플리케이션은, 직선만을 렌더링 해야 하는 것이다. 또, 렌더링의 대상은, 장면내의 다각형의 외변으로 한정한다. 이 렌더링 스테이트가 설정되어 있어, 삼각형 또는 점이 드로잉(Drawing) 되면(자), 그 동작은 부정이다. anti-aliasing는, 단지, 인접하는 픽셀값의 평균치를 취하는 것에 의해 실행된다. anti-aliasing를 실시하는 것은 최선의 방식은 아니지만, 효율적이다. 이런 종류의 조작을 지원 하는 하드웨어는 보급하고 있다.

엣지 anti-aliasing은, D3DPRASTERCAPS_ANTIALIASEDGES 능력을 나타내는 디바이스에 한정해, 유효하게 할 수가 있다.

D3DRENDERSTATE_EMISSIVEMATERIALSOURCE
라이팅 계산으로 사용하는 에미션(emission)색의 소스. 유효한 값은,CONST_D3DMATERIALCOLORSOURCE 열거의 멤버. 디폴트값은 D3DMCS_MATERIAL 이다.
D3DRENDERSTATE_EXTENTS
렌더링 호출할 것에 스크린 범위를 갱신하는 경우는 제로 이외의 값에, 갱신하지 않는 경우는 제로로 설정한다. 디폴트값은 제로이다.
D3DRENDERSTATE_FILLMODE
CONST_D3DFILLMODE 열거의 1 개 이상의 정수. 디폴트값은 D3DFILL_SOLID 이다.
D3DRENDERSTATE_FOGCOLOR
DirectX7.CreateColorRGB 메소드에 의해 돌려주어지는, RGB 색을 나타내는 Long 형의 값. 디폴트값은 0 이다. 상세한 것에 대하여는, 「포그(안개:fog) 컬러」를 참조할것.
D3DRENDERSTATE_FOGENABLE
TRUE 는 포그(안개:fog) 블렌딩을 가능하게 한다. 디폴트값은 FALSE 이다. 상세한 것에 대하여는, 「포그(안개:fog) 블렌딩」과「포그(안개:fog)」를 참조할것.

이러한 렌더링 스테이트에 의해, 카메라에 가까운 위치의 포그(안개:fog) 이펙트를 제외하는 것이 가능하게 된다. 예를 들어, 시작 깊이에 0.3 을 설정 하면, 0.0 에서 0.299 의 범위의 깊이에 대한 포그(안개:fog) 이펙트가 제외되어 종료 깊이에 0.7 을 설정 하면, 0.701 에서 1.0 의 범위의 깊이에 대한 포그(안개:fog) 이펙트가 제외된다.

D3DRENDERSTATE_FOGTABLEMODE
픽셀 포그(안개:fog)에 사용되는 포그(안개:fog)식. CONST_D3DFOGMODE 열거의 정수의 1 개로 설정한다. 디폴트값은 D3DFOG_NONE 이다. 상세한 것에 대하여는, 「픽셀 포그(안개:fog)」를 참조할것.
D3DRENDERSTATE_FOGVERTEXMODE
픽셀 포그(안개:fog)에 사용되는 포그(안개:fog)식. CONST_D3DFOGMODE 열거의 멤버의 1 개로 설정한다. 디폴트값은 D3DFOG_NONE 이다. 상세한 것에 대하여는, 「버텍스 포그(안개:fog)」를 참조할것.
D3DRENDERSTATE_LASTPIXEL
직선이나 삼각형의 마지막 픽셀을 드로잉(Drawing) 가능으로 하려면 , FALSE 로 설정한다. 디폴트값은 TRUE 이다.
D3DRENDERSTATE_LIGHTING
Direct3D 의 라이팅을 유효하게 하는 경우는 제로 이외의 값에, 무효로 하는 경우는 제로로 설정한다. 디폴트값은 제로 이외의 값이다. 버텍스 법선을 포함한 버텍스만이 올바르게 비추어져 법선을 포함하지 않는 버텍스는 라이팅 계산으로 0 의 내적을 사용한다.
D3DRENDERSTATE_LINEPATTERN
라인 패턴. D3DLINEPATTERN 형에 의해 유효한 값을 정의한다. D3DLINEPATTERN 의 멤버의 디폴트값은,repeatPattern 및 linePattern 함께 0 이다.
D3DRENDERSTATE_LOCALVIEWER
카메라와의 상대 각도에 의존한 스펙큐러 하이라이트를 유효하게 하는 경우는 제로 이외의 값에, 정스펙큐러 하이라이트를 사용하는 경우는 제로로 설정한다. 디폴트값은 제로로, 카메라와의 상대 각도에 의존한 스펙큐러 하이라이트를 사용한다. 정사영을 사용하는 어플리케이션에서는 제로로 설정할 필요가 있다.
D3DRENDERSTATE_NORMALIZENORMALS
버텍스 법선의 자동 정규화를 유효하게 하는 경우에는 제로 이외의 값에, 무효로 하는 경우는 제로로 설정한다. 디폴트값은 제로이다. 이 기능을 유효하게 하면, 버텍스 법선을 카메라 공간에 트랜스 폼 한 다음에, 버텍스 법선을 자동적으로 정규화할 수 있다.
D3DRENDERSTATE_RANGEFOGENABLE
범위 준거의 버텍스 포그(안개:fog)를 유효하게 하려면 TRUE 로 설정한다 (디폴트값은 FALSE 로, 깊이 준거의 포그(안개:fog)를 사용한다). 범위 베이스의 포그(안개:fog)에서는, 장면에 있어서의 오브젝트의 깊이 (z 좌표)는 아니고, 오브젝트의 뷰아로부터의 거리로 포그(안개:fog) 이펙트를 계산한다. 범위 베이스의 포그(안개:fog)에서는, 보통 모든 포그(안개:fog) 계산 메소드가 움직이지만, 계산에 깊이가 아니게 범위를 사용하는 점만이 다르다.

범위는 포그(안개:fog) 계산에 사용하는데 올바른 요소이지만, 범위가 계산 카미타카값이 되는 한편, 깊이는 보통 계산이 끝난 상태이므로, 대표해 깊이가 넓게 사용된다. 포그(안개:fog) 계산에 깊이를 사용하면(자), 주변의 오브젝트의 포그(안개:fog)의 모습이 눈의 회전과 함께 변화 하면 말하는 바람직하지 않은 영향이 나온다. 이 케이스에서는, 깊이는 바뀌지만 범위는 일정한 까지 있다.

이 렌더링 스테이트는 D3DVERTEX 버텍스만으로 기능한다. D3DLVERTEX 또는 D3DTLVERTEX 버텍스를 지정 하면, RGBF 포그(안개:fog)값의 F (포그(안개:fog)) 요소는, 범위에 관해서 항상 수정되지 않으면 안 된다.

현재 픽셀 단위에서의 범위 베이스의 포그(안개:fog)를 지원 하는 하드웨어는 없기 때문에, 범위의 수정은 버텍스 포그(안개:fog)에게만 제공된다. 상세한 것에 대하여는, 「범위 베이스의 포그(안개:fog)」와「버텍스 포그(안개:fog)」를 참조할것.

D3DRENDERSTATE_SHADEMODE
D3DSHADEMODE 열거의 멤버의 1 개 이상의 값. 디폴트값은 D3DSHADE_GOURAUD 이다.
D3DRENDERSTATE_SPECULARENABLE
TRUE 는 스펙큐러 하이라이트를 가능하게 한다. 디폴트값은 TRUE 이다.

스펙큐러 하이라이트는, 빛이 맞고 있는 오브젝트의 각 버텍스가 그 오브젝트의 원점에 있는것 같이 산출된다. 이것은, 오브젝트가 원점의 주위로 모델화 되어 광원과 오브젝트간의 거리가 비교적으로 큰 경우에 한정해, 예측값을 준다.

이 멤버를 TRUE 로 설정 하면, 텍스쳐 cascade 후, 알파 블렌딩전에, 베이스 컬러에 스펙큐러색이 추가된다.

D3DRENDERSTATE_SPECULARMATERIALSOURCE
라이팅 계산으로 사용하는 스펙큐러색의 소스. 유효한 값은,CONST_D3DMATERIALCOLORSOURCE 열거의 멤버. 디폴트값은 D3DMCS_COLOR2 이다.
D3DRENDERSTATE_SRCBLEND
CONST_D3DBLEND 열거의 정수의 1 개. 디폴트값은 D3DBLEND_ONE 이다.
D3DRENDERSTATE_STENCILENABLE
TRUE 의 경우는 스텐실 조작이 가능하게 되어, FALSE 에서는 무효가 된다. 디폴트값은 FALSE 이다. 상세한 것에 대하여는, 「스텐실 버퍼」를 참조할것.
D3DRENDERSTATE_STENCILFAIL
스텐실 테스트에 실패했을 때에 실행하는 스텐실 조작. CONST_D3DSTENCILOP 열거의 정수의 1 개로 할 수 있다. 디폴트값은 D3DSTENCILOP_KEEP 이다. 상세한 것에 대하여는, 「스텐실 버퍼」를 참조할것.
D3DRENDERSTATE_STENCILFUNC
스텐실 테스트를 위한 비교 함수. CONST_D3DCMPFUNC 열거의 정수의 1 개로 할 수 있다. 디폴트값은 D3DCMP_ALWAYS 이다.

비교 함수는, 스텐실 버퍼의 요소를 기준치와 비교하기 위해서(때문에) 사용된다. 이 비교는, 기준치의 비트와 스텐실 마스크 (D3DRENDERSTATE_STENCILMASK 렌더링 스테이트에 의해 설정)로 설정된 스텐실 버퍼 요소에게만 적용된다. 비교의 결과가 진이면, 스텐실 테스트는 성공이다.

D3DRENDERSTATE_STENCILMASK
기준치와 각각의 스텐실 버퍼 요소에 적용해, 스텐실 테스트를 위한 유효 비트를 결정하는 마스크. 디폴트 마스크는 0xFFFFFFFF 이다.
D3DRENDERSTATE_STENCILPASS
스텐실 테스트와 깊이 테스트 (z 테스트)의 양쪽 모두에 성공했을 경우에 실행하는 스텐실 조작. CONST_D3DSTENCILOP 열거의 정수의 1 개로 할 수 있다. 디폴트값은 D3DSTENCILOP_KEEP 이다. 상세한 것에 대하여는, 「스텐실 버퍼」를 참조할것.
D3DRENDERSTATE_STENCILREF
스텐실 테스트를 위한 정수 기준치. 디폴트값은 0 이다.
D3DRENDERSTATE_STENCILWRITEMASK
스텐실 버퍼에 기입하는 값에 적용하는 쓰기 마스크. 디폴트 마스크는 0xFFFFFFFF 이다.
D3DRENDERSTATE_STENCILZFAIL
스텐실 테스트에 성공해, 깊이 테스트 (z 테스트)에 실패했을 경우에 실행하는 스텐실 조작. CONST_D3DSTENCILOP 열거의 정수의 1 개로 할 수 있다. 디폴트값은 D3DSTENCILOP_KEEP 이다. 상세한 것에 대하여는, 「스텐실 버퍼」를 참조할것.
D3DRENDERSTATE_STIPPLEDALPHA
TRUE 때, 점묘 알파를 가능으로 한다. 디폴트값은 FALSE 이다.

현재의 소프트웨어 래스터라이저는, 이 렌더링 스테이트를 무시한다. 현재의 하드웨어가 이 렌더링 스테이트를 지원 할지 어떨지를 조사하려면 ,D3DPRIMCAPS 형의 D3DPSHADECAPS_ALPHAFLATSTIPPLED 플래그를 사용한다.

D3DRENDERSTATE_TEXTUREFACTOR
D3DTA_TFACTOR 텍스쳐 블렌딩 인수, 또는 D3DTOP_BLENDFACTORALPHA 텍스쳐 블렌딩 조작을 이용한 멀티 텍스쳐 블렌딩으로 사용되는 색.
D3DRENDERSTATE_TEXTUREPERSPECTIVE
TRUE 때, 퍼스펙티브 보정 맵핑을 가능으로 한다 (퍼스펙티브 보정」을 참조할것). 디폴트값은 TRUE 이다. 상세한 것에 대하여는, 「텍스쳐 퍼스펙티브 스테이트」를 참조할것.
D3DRENDERSTATE_VERTEXBLEND
지오메트리 블렌딩에 사용되는 행렬의 수. 유효한 값은,CONST_D3DVERTEXBLENDFLAGS 열거의 멤버. 디폴트값은 D3DVBLEND_DISABLE 이다. 상세한 것에 대하여는, 「지오메트리 블렌딩」을 참조할것.
D3DRENDERSTATE_WRAP0 through D3DRENDERSTATE_WRAP7
복수의 텍스쳐 좌표 세트를 사용할 때의 텍스쳐 랩핑 동작을 지정한다. 이러한 렌더링 스테이트의 유효한 값은,CONST_D3D 열거의 D3DWRAPCOORD_0, D3DWRAPCOORD_1, D3DWRAPCOORD_2, 및 D3DWRAPCOORD_3 플래그의 임의의 편성 이것에 의해, 지정된 텍스쳐의 제일, 제2, 제3, 제4 넓이의 방향 (s, t, r, q 방향이라고도 말한다)으로 랩 한다. 디폴트값은 0 (모든 방향으로 랩핑 무효)이다. 상세한 것에 대하여는, 「텍스쳐 랩핑」을 참조할것.
D3DRENDERSTATE_ZBIAS
0 에서 16 까지의 범위의 정수값이며, 물리적으로 동일한 면에 있는 다각형이 분리해 보이도록(듯이) 한다. 드로잉(Drawing) 순서의 sorting를 실시하지 않아도, 높은 Z 바이어스값을 가지는 다각형은, 낮은 값을 가지는 다각형보다 앞으로 보인다. 예를 들어, 값 1 을 가지는 다각형은, 값 0 의 다각형보다 앞으로 보인다. 디폴트값은 제로이다. 상세한 것에 대하여는, 「깊이 버퍼의 사용」을 참조할것.
D3DRENDERSTATE_ZENABLE
깊이 버퍼링 스테이트. CONST_D3DZBUFFERTYPE 열거의 정수의 1 개. z 버퍼링을 유효하게 하려면 D3DZB_TRUE, w 버퍼링을 유효하게 하려면 D3DZB_USEW, 깊이 버퍼링을 무효로 하려면 D3DZB_FALSE를, 각각 설정한다.

렌더링의 대상이 되는 표면에 깊이 버퍼가 Attach 되고 있는 경우, 이 렌더링 스테이트의 디폴트값은 D3DZB_TRUE 이며, 그 이외의 경우는 D3DZB_FALSE 이다.

D3DRENDERSTATE_ZFUNC
CONST_D3DCMPFUNC 열거의 정수의 1 개. 디폴트값은 D3DCMP_LESSEQUAL 이다. 이 멤버는, 어플리케이션에카메라로부터의 거리를 기준으로 하는 픽셀의 수취나 받아 거부를 허가한다.

픽셀의 깊이값을 깊이 버퍼의 값과 비교한다. 픽셀의 깊이값이 비교 함수로 허가되었을 경우에 픽셀이 기입해진다.

깊이값이 깊이 버퍼에 기입해지는 것은, 렌더링 스테이트 D3DRENDERSTATE_ZWRITEENABLE 가 TRUE 의 경우 뿐이다.

이 깊이 테스트에 실패한 (분)편이, 소프트웨어에 의한 라스터화나 많은 하드웨어 가속기의 처리는 빨라진다. 이것은, 픽셀의 렌더링 처리를 실시하지 않는 경우에는, 텍스쳐를 필터 처리하거나 변조하거나 할 필요가 없어지기 때문에 있다.

D3DRENDERSTATE_ZVISIBLE
사용하지 않는다.
D3DRENDERSTATE_ZWRITEENABLE
깊이 버퍼에의 쓰기를 유효하게 하려면 TRUE 로 설정한다. 디폴트값은 TRUE 이다. 어플리케이션은 이 멤버를 이용하는 것으로써, 시스템이 새로운 깊이값으로 깊이 버퍼를 갱신해 버리는 것을 막을 수가 있다. 이 스테이트를 FALSE 로 설정 하면, 렌더링 스테이트 D3DRENDERSTATE_ZFUNC (깊이의 버퍼링을 하고 있으면(자) 가정)에 따라 깊이 비교는 실행되지만, 깊이값이 버퍼에 기입해질 것은 없다.

주의

Direct3D 는, 어플리케이션에서의 편의를 고려해, (D3DRENDERSTATE_WRAPn 스테이트값의 1 개를 명시적으로 사용하는 대신에) D3DRENDERSTATE_WRAPBIAS 정수를 정의해, 텍스쳐 좌표 세트의 제로 시점 정수값에 근거해, 텍스쳐 랩핑을 유효하게 하거나 무효로 하거나 한다. 다음의 예의 같게, D3DRENDERSTATE_WRAPBIAS 값을 텍스쳐 좌표 세트의 제로 베이스 인덱스에 덧셈 해, 그 인덱스에 대응하는 D3DRENDERSTATE_WRAPn 값을 계산한다.

On Local Error Resume Next

'변수 lIndex 의 인덱스에 대응하는 텍스쳐 좌표 세트를
'사용하는 텍스쳐에 대해서, U/V 랩핑을 유효하게 한다.
Call d3dDevice.SetRenderState( _
lIndex + D3DRENDERSTATE_WRAPBIAS, _
D3DWRAPCOORD_0 Or D3DWRAPCOORD_1)

' lIndex가 3 의 경우, 덧셈의 결과의 값은,
' D3DRENDERSTATE_WRAP3 (131)에 동일해진다.
If Err.Number <> DD_OK Then
'에러 처리 코드
End If


CONST_D3DSHADEMODE

CONST_D3DSHADEMODE 열거는,CONST_D3DRENDERSTATETYPE 열거의 D3DRENDERSTATE_SHADEMODE 렌더링 스테이트용으로, 지원 되는 쉐이딩 모드를 지정한다.

Enum CONST_D3DSHADEMODE
    D3DSHADE_FLAT         = 1
    D3DSHADE_GOURAUD      = 2
    D3DSHADE_PHONG        = 3
End Enum
D3DSHADE_FLAT
flat shading 모드. 삼각형의 최초의 버텍스의 색이, 표면의 색을 결정하기 위해서(때문에) 사용된다. 이 색은 삼각형 전체에 대해서 일정한다. 즉 보간 되지 않는다.
D3DSHADE_GOURAUD
gouraud shading 모드. 표면의 색은, 삼각형의 3 개의 버텍스간으로, 선형 보간에 의해 결정된다.
D3DSHADE_PHONG
폰 쉐이딩 모드. 이 모드는, 현재 지원되어 있지 않다.

참조

CONST_D3DRENDERSTATETYPE


CONST_D3DSTATEBLOCKTYPE

CONST_D3DSTATEBLOCK 열거형은,Direct3DDevice7.CreateStateBlock 메소드로 사용하기 위해서, 디바이스 스테이트의 논리 그룹을 정의한다.

Type D3DSTATEBLOCKTYPE
    D3DSBT_ALL = 1
    D3DSBT_PIXELSTATE = 2
    D3DSBT_VERTEXSTATE = 3
End Type
D3DSBT_ALL
모든 디바이스 스테이트를 캡춰 한다.
D3DSBT_PIXELSTATE
픽셀 관련의 디바이스 스테이트만을 캡춰 한다.
D3DSBT_VERTEXSTATE
버텍스 관련의 디바이스 스테이트만을 캡춰 한다.

주의

D3DSBT_PIXELSTATE 와 D3DSBT_VERTEXSTATE 의 양쪽 모두에 속하는 디바이스 스테이트도 있지만, 이러한 값은 다른 논리 그룹을 나타낸다. 각 그룹에 속하는 스테이트에 대해서는, 「사전 정의하는 스테이트 블록의 생성」을 참조할것.

참조

Direct3DDevice7.CreateStateBlock


CONST_D3DSTENCILCAPSFLAGS

CONST_D3DSTENCILCAPSFLAGS 열거는,D3DDEVICEDESC7 형의 lStencilCaps 멤버로 사용되는 스텐실 버퍼 능력 플래그를 정의한다.

Enum CONST_D3DSTENCILCAPSFLAGS
    D3DSTENCILCAPS_DECR = 128
    D3DSTENCILCAPS_DECRSAT = 16
    D3DSTENCILCAPS_INCR = 64
    D3DSTENCILCAPS_INCRSAT = 8
    D3DSTENCILCAPS_INVERT = 32
    D3DSTENCILCAPS_KEEP = 1
    D3DSTENCILCAPS_REPLACE = 4
    D3DSTENCILCAPS_ZERO = 2
End Enum
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 스텐실 버퍼 조작을 지원 한다.


CONST_D3DSTENCILOP

D3DSTENCILOP 열거형은,D3DRENDERSTATE_STENCILFAIL ,D3DRENDERSTATE_STENCILZFAIL , 및 D3DRENDERSTATE_STENCILPASS 렌더링 스테이트를 위한 스텐실 조작을 정의한다.

Enum CONST_D3DSTENCILOP
    D3DSTENCILOP_DECR = 8
    D3DSTENCILOP_DECRSAT = 5
    D3DSTENCILOP_INCR = 7
    D3DSTENCILOP_INCRSAT = 4
    D3DSTENCILOP_INVERT = 6
    D3DSTENCILOP_KEEP = 1
    D3DSTENCILOP_REPLACE = 3
    D3DSTENCILOP_ZERO = 2
End Enum
D3DSTENCILOP_DECR
스텐실 버퍼내의 항목의 값을 감소시켜, 새로운 값이 제로 미만이 되었을 경우는 랩핑 해 최대치에 돌아온다.
D3DSTENCILOP_DECRSAT
스텐실 버퍼내의 항목의 값을, 제로에 이를 때까지 감소시킨다.
D3DSTENCILOP_INCRSAT
스텐실 버퍼내의 항목의 값을, 최대치에 이를 때까지 증가시킨다. 스텐실 버퍼의 최대치에 관해서는, 「주의」를 참조할것.
D3DSTENCILOP_INVERT
스텐실 버퍼내의 항목의 비트를 반전한다.
D3DSTENCILOP_INCR
스텐실 버퍼내의 항목의 값을 증가시켜, 최대치를 초과했을 경우는 랩핑 해 제로에 돌아온다. 스텐실 버퍼의 최대치에 관해서는, 「주의」를 참조할것.
D3DSTENCILOP_KEEP
스텐실 버퍼내의 항목을 갱신하지 않는다. 이것이 디폴트값이다.
D3DSTENCILOP_REPLACE
스텐실 버퍼내의 항목을 기준치로 옮겨놓는다.
D3DSTENCILOP_ZERO
스텐실 버퍼내의 항목을 제로로 설정한다.

주의

스텐실 버퍼 항목은 0 에서 2n -1 까지의 범위의 정수값을 취한다. 여기서,n 는 스텐실 버퍼의 비트 깊이이다.

참조

CONST_D3DRENDERSTATETYPE ,스텐실 버퍼


CONST_D3DTAFLAGS

CONST_D3DTAFLAGS 열거는, 텍스쳐 블렌딩 스테이지를 정의하기 위해서 사용되는 텍스쳐 인수 플래그를 지정한다. 상세한 것에 대하여는, 「텍스쳐 인수 플래그」를 참조할것.


CONST_D3DTEXCOORDINDEXFLAGS

CONST_D3DTEXCOORDINDEXFLAGS 열거는,D3DTSS_TEXCOORDINDEX 텍스쳐 스테이지 스테이트에서 설정된 인덱스값과 조합해 사용되는 값을 정의한다.

Type CONST_D3DTEXCOORDINDEXFLAGS
    D3DTSS_TCI_CAMERASPACENORMAL = 65536
    D3DTSS_TCI_CAMERASPACEPOSITION = 131072
    D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR = 196608
    D3DTSS_TCI_PASSTHRU = 0
End Type
D3DTSS_TCI_CAMERASPACENORMAL
이 스테이지의 텍스쳐 트랜스 폼으로, 입력 텍스쳐 좌표로서 카메라 공간에 트랜스 폼 된 버텍스 법선을 사용한다.
D3DTSS_TCI_CAMERASPACEPOSITION
이 스테이지의 텍스쳐 트랜스 폼으로, 입력 텍스쳐 좌표로서 카메라 공간에 트랜스 폼 된 버텍스 위치 좌표를 사용한다.
D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR
이 스테이지의 텍스쳐 트랜스 폼으로, 입력 텍스쳐 좌표로서 카메라 공간에 트랜스 폼 된 반사 벡터를 사용한다. 반사 벡터는, 입력 버텍스 위치 좌표와 버텍스 법선에 의해 계산된다.
D3DTSS_TCI_PASSTHRU
벡터 포맷에 포함되는 지정된 텍스쳐 좌표를 사용한다.

주의

이 열거의 값 (0 이 되는 D3DTSS_TCI_PASSTHRU 를 제외한다)은, 시스템이 D3DTSS_TEXCOORDINDEX 로 설정된 인덱스값을 어떻게 사용할까에 따라서 다르다. 보통, D3DTSS_TEXCOORDINDEX 로 설정된 값은, 텍스쳐의 주소 지정에 사용되는 텍스쳐 좌표를 제어한다. 다만, D3DTSS_TCI_CAMERASPACENORMAL, D3DTSS_TCI_CAMERASPACEPOSITION, 또는 D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR 값 (설정된 인덱스와의 논리 화)이 있는 경우, 시스템은 이 인덱스를 텍스쳐 랩핑 모드의 지정인 만큼 사용한다.

이 열거의 값은, 환경 맵핑의 텍스쳐 좌표를 자동 생성하는 어플리케이션으로 유효하다.

참조

텍스쳐 좌표의 자동 생성의 구성


CONST_D3DTEXOPCAPSFLAGS

CONST_D3DTEXOPCAPSFLAGS 열거는,D3DDEVICEDESC7 형의 lTextureOpCaps 멤버로 사용되는 텍스쳐 블렌딩 조작 능력을 정의한다.

Enum CONST_D3DTEXOPCAPSFLAGS
    D3DTEXOPCAPS_ADD = 64
    D3DTEXOPCAPS_ADDSIGNED = 128
    D3DTEXOPCAPS_ADDSIGNED2X = 256
    D3DTEXOPCAPS_ADDSMOOTH = 1024
    D3DTEXOPCAPS_BLENDCURRENTALPHA = 32768
    D3DTEXOPCAPS_BLENDDIFFUSEALPHA = 2048
    D3DTEXOPCAPS_BLENDFACTORALPHA = 8192
    D3DTEXOPCAPS_BLENDTEXTUREALPHA = 4096
    D3DTEXOPCAPS_BLENDTEXTUREALPHAPM = 16384
    D3DTEXOPCAPS_BUMPENVMAP = 2097152
    D3DTEXOPCAPS_BUMPENVMAPLUMINANCE = 4194304
    D3DTEXOPCAPS_DISABLE = 1
    D3DTEXOPCAPS_DOTPRODUCT3 = 8388608
    D3DTEXOPCAPS_MODULATE = 8
    D3DTEXOPCAPS_MODULATE2X = 16
    D3DTEXOPCAPS_MODULATE4X = 32
    D3DTEXOPCAPS_MODULATEALPHA_ADDCOLOR = 131072
    D3DTEXOPCAPS_MODULATECOLOR_ADDALPHA = 262144
    D3DTEXOPCAPS_MODULATEINVALPHA_ADDCOLOR = 524288
    D3DTEXOPCAPS_MODULATEINVCOLOR_ADDALPHA = 1048576
    D3DTEXOPCAPS_PREMODULATE = 65536
    D3DTEXOPCAPS_SELECTARG1 = 2
    D3DTEXOPCAPS_SELECTARG2 = 4
    D3DTEXOPCAPS_SUBTRACT = 512
End Enum
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_MODULATE
디바이스는 D3DTOP_MODULATE 텍스쳐 블렌딩 조작을 지원 한다.
D3DTEXOPCAPS_MODULATE2X
디바이스는 D3DTOP_MODULATE2X 텍스쳐 블렌딩 조작을 지원 한다.
D3DTEXOPCAPS_MODULATE4X
디바이스는 D3DTOP_MODULATE4X 텍스쳐 블렌딩 조작을 지원 한다.
D3DTEXOPCAPS_MODULATEALPHA_ADDCOLOR
디바이스는 D3DTOP_MODULATEALPHA_ADDCOLOR 텍스쳐 블렌딩 조작을 지원 한다.
D3DTEXOPCAPS_MODULATECOLOR_ADDALPHA
디바이스는 D3DTOP_MODULATEALPHA_ADDCOLOR 텍스쳐 블렌딩 조작을 지원 한다.
D3DTEXOPCAPS_MODULATEINVALPHA_ADDCOLOR
디바이스는 D3DTOP_MODULATEINVALPHA_ADDCOLOR 텍스쳐 블렌딩 조작을 지원 한다.
D3DTEXOPCAPS_MODULATEINVCOLOR_ADDALPHA
디바이스는 D3DTOP_MODULATEINVCOLOR_ADDALPHA 텍스쳐 블렌딩 조작을 지원 한다.
D3DTEXOPCAPS_PREMODULATE
디바이스는 D3DTOP_PREMODULATE 텍스쳐 블렌딩 조작을 지원 한다.
D3DTEXOPCAPS_SELECTARG1
디바이스는 D3DTOP_SELECTARG1 텍스쳐 블렌딩 조작을 지원 한다.
D3DTEXOPCAPS_SELECTARG2
디바이스는 D3DTOP_SELECTARG2 텍스쳐 블렌딩 조작을 지원 한다.
D3DTEXOPCAPS_SUBTRACT
디바이스는 D3DTOP_SUBTRACT 텍스쳐 블렌딩 조작을 지원 한다.


CONST_D3DTEXTUREADDRESS

CONST_D3DTEXTUREADDRESS 열거는,D3DTSS_ADDRESS ,D3DTSS_ADDRESSU , 및 D3DTSS_ADDRESSV 텍스쳐 스테이지 스테이트에서 텍스쳐 addressing mode를 설정할 때에, 지원 되는 모드를 기술한다.

Enum CONST_D3DTEXTUREADDRESS
    D3DTADDRESS_WRAP         = 1
    D3DTADDRESS_MIRROR       = 2
    D3DTADDRESS_CLAMP        = 3
    D3DTADDRESS_BORDER       = 4
End Enum
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] 의 외측의 텍스쳐 좌표가,CONST_D3DTEXTURESTAGESTATETYPE 열거의 D3DTSS_BORDERCOLOR 텍스쳐 스테이지 스테이트에서 설정된 경계색으로 그려진다.

참조

CONST_D3DTEXTURESTAGESTATETYPE


CONST_D3DTEXTUREMAGFILTER

CONST_D3DTEXTUREMAGFILTER 열거는, 텍스쳐 스테이지의 텍스쳐 확대 필터링 모드를 정의한다.

Enum CONST_D3DTEXTUREMAGFILTER
    D3DTFG_POINT        = 1
    D3DTFG_LINEAR       = 2
    D3DTFG_FLATCUBIC    = 3
    D3DTFG_GAUSSIANCUBIC= 4
    D3DTFG_ANISOTROPIC  = 5
End Enum
D3DTFG_POINT
점필터링. 희망의 픽셀값에 가장 가까운 좌표를 가지는 텍셀을 사용한다.
D3DTFG_LINEAR
바이리니아 보간 필터링. 희망의 픽셀을 둘러싸는 2 Χ 2 영역의 텍셀의 중량감 첨부 평균을 사용한다.
D3DTFG_FLATCUBIC
현재 지원되어 있지 않다. 사용 불가.
D3DTFG_GAUSSIANCUBIC
현재 지원되어 있지 않다. 사용 불가.
D3DTFG_ANISOTROPIC
비등방성 텍스쳐 필터링. 텍스쳐 다각형과 스크린 평면간의 각도의 상위에 의해 일어나는 일그러짐을 보정한다.

주의

텍스쳐 스테이지의 확대 필터를 설정할 때는,D3DTSS_MAGFILTER 값을 제 2 파라미터로 해, 이 열거의 멤버의 1 개를 제 3 파라미터로서 Direct3DDevice7.SetTextureStageState 메소드를 호출한다.

참조

CONST_D3DTEXTUREMINFILTER ,CONST_D3DTEXTUREMIPFILTER ,텍스쳐 필터링


CONST_D3DTEXTUREMINFILTER

CONST_D3DTEXTUREMINFILTER 열거는, 텍스쳐 스테이지의 텍스쳐 축소 필터링 모드를 정의한다.

Enum CONST_D3DTEXTUREMINFILTER
    D3DTFN_POINT        = 1
    D3DTFN_LINEAR       = 2
    D3DTFN_ANISOTROPIC  = 3
End Enum
D3DTFN_POINT
점필터링. 희망의 픽셀값에 가장 가까운 좌표를 가지는 텍셀을 사용한다.
D3DTFN_LINEAR
바이리니아 보간 필터링. 희망의 픽셀을 둘러싸는 2 × 2 영역의 텍셀의 중량감 첨부 평균을 사용한다.
D3DTFN_ANISOTROPIC
비등방성 텍스쳐 필터링. 텍스쳐 다각형과 스크린 평면간의 각도의 상위에 의해 일어나는 일그러짐을 보정한다.

주의

텍스쳐 스테이지의 확대 필터를 설정 하면나무는,D3DTSS_MINFILTER 값을 제 2 파라미터로 해, 이 열거의 멤버의 1 개를 제 3 파라미터로서 Direct3DDevice7.SetTextureStageState 메소드를 호출한다.

참조

CONST_D3DTEXTUREMAGFILTER ,CONST_D3DTEXTUREMIPFILTER ,텍스쳐 필터링


CONST_D3DTEXTUREMIPFILTER

CONST_D3DTEXTUREMIPFILTER 열거는, 텍스쳐 스테이지의 텍스쳐 밉맵 필터링 모드를 정의한다.

Enum CONST_D3DTEXTUREMIPFILTER
    D3DTFP_NONE         = 1
    D3DTFP_POINT        = 2
    D3DTFP_LINEAR       = 3
End Enum
D3DTFP_NONE
밉맵 처리를 무효로 한다. 래스터라이저는 대신에 확대 필터를 사용한다.
D3DTFP_POINT
최근점밉맵 필터. 래스터라이저는 가장 가까운 밉맵 텍스쳐의 텍셀로부터의 색을 사용한다.
D3DTFP_LINEAR
트라이 리니어 밉맵 보간. 래스터라이저는, 가장 가까운 밉맵 텍스쳐 2 점으로부터의 텍셀을 사용해 픽셀색을 선형 보간 한다.

주의

텍스쳐 스테이지의 확대 필터를 설정할 때는,D3DTSS_MIPFILTER 값을 제 2 파라미터로 해, 이 열거의 멤버의 1 개를 제 3 파라미터로서 Direct3DDevice7.SetTextureStageState 메소드를 호출한다.

참조

CONST_D3DTEXTUREMAGFILTER ,CONST_D3DTEXTUREMIPFILTER ,텍스쳐 필터링


CONST_D3DTEXTUREOP

CONST_D3DTEXTUREOP 열거는, 스테이지 단위 텍스쳐 블렌딩 조작을 정의한다. 이 형태의 정수는, D3DTSS_COLOROP 또는 D3DTSS_ALPHAOP 값을 사용해 Direct3DDevice7.SetTextureStageState 메소드를 호출해, 색조작이나 알파 조작을 설정할 경우에 사용된다.

Enum CONST_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
End Enum
제어 정수
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 인수를 덧셈 해, 다음에, 제 1 인수와 제 2 인수의 적을 합계값으로부터 뺄셈 한다.

선형 알파 블렌딩 정수
D3DTOP_BLENDDIFFUSEALPHA
각 버텍스로부터의 보간 알파 (D3DTOP_BLENDDIFFUSEALPHA), 이 스테이지의 텍스쳐로부터의 알파 (D3DTOP_BLENDTEXTUREALPHA),D3DRENDERSTATE_TEXTUREFACTOR 렌더링 스테이트에서 설정되는 스칼라-알파 (D3DTOP_BLENDFACTORALPHA), 또는 전의 텍스쳐 스테이지로부터의 알파 (D3DTOP_BLENDCURRENTALPHA)를 사용해, 이 스테이지의 선형 블렌딩을 실시한다.

D3DTOP_BLENDTEXTUREALPHA
각 버텍스로부터의 보간 알파 (D3DTOP_BLENDDIFFUSEALPHA), 이 스테이지의 텍스쳐로부터의 알파 (D3DTOP_BLENDTEXTUREALPHA),D3DRENDERSTATE_TEXTUREFACTOR 렌더링 스테이트에서 설정되는 스칼라-알파 (D3DTOP_BLENDFACTORALPHA), 또는 전의 텍스쳐 스테이지로부터의 알파 (D3DTOP_BLENDCURRENTALPHA)를 사용해, 이 스테이지의 선형 블렌딩을 실시한다.

D3DTOP_BLENDFACTORALPHA
각 버텍스로부터의 보간 알파 (D3DTOP_BLENDDIFFUSEALPHA), 이 스테이지의 텍스쳐로부터의 알파 (D3DTOP_BLENDTEXTUREALPHA),D3DRENDERSTATE_TEXTUREFACTOR 렌더링 스테이트에서 설정되는 스칼라-알파 (D3DTOP_BLENDFACTORALPHA), 또는 전의 텍스쳐 스테이지로부터의 알파 (D3DTOP_BLENDCURRENTALPHA)를 사용해, 이 스테이지의 선형 블렌딩을 실시한다.

D3DTOP_BLENDCURRENTALPHA
각 버텍스로부터의 보간 알파 (D3DTOP_BLENDDIFFUSEALPHA), 이 스테이지의 텍스쳐로부터의 알파 (D3DTOP_BLENDTEXTUREALPHA),D3DRENDERSTATE_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
다음의 텍스쳐 스테이지의 환경 맵 (휘도(Luminance) 없음)을 사용해, 픽셀 단위로 범프 맵핑을 실행한다.
D3DTOP_BUMPENVMAPLUMINANCE
다음의 텍스쳐 스테이지의 환경 맵 (휘도(Luminance) 있어)을 사용해, 픽셀 단위로 범프 맵핑을 실행한다.
D3DTOP_DOTPRODUCT3
각 인수의 요소를 (부호부 요소로서) 변조해 적을 덧셈 해, 얻을 수 있던 합계값을 모든 색채널에, 알파를 포함해 복제한다. 이 조작은, 색조작 (D3DTSS_COLOROP)에서만 지원 된다.

주의

위의식에 대해, SRGBA 는 텍스쳐 조작으로 생성 되는 RGBA 색이며,Arg1 와 Arg2 는 텍스쳐 인수의 완전한 RGBA 색이다. 인수의 각각의 요소는, 첨자를 붙여 표기된다. 예를 들어, 인수 1 의 알파 요소는,Arg1A 라고 표현된다.

참조

Direct3DDevice7.GetTextureStageState ,Direct3DDevice7.SetTextureStageState ,CONST_D3DTEXTURESTAGESTATETYPE


CONST_D3DTEXTURESTAGESINGLE

CONST_D3DTEXTURESTAGESINGLE 열거는, Single 형의 값을 받아들이는 텍스쳐 스테이지 스테이트를 정의한다. 이 열거의 정수는, 텍스쳐 스테이트값을 취득 및 설정하는 Direct3DDevice7.GetTextureStageStateSingle 메소드와 Direct3DDevice7.SetTextureStageStateSingle 메소드로 사용된다.

Enum CONST_D3DTEXTURESTAGESINGLE
    D3DTSS_BUMPENVLOFFSET = 23
    D3DTSS_BUMPENVLSCALE  = 22
    D3DTSS_BUMPENVMAT00   = 7
    D3DTSS_BUMPENVMAT01   = 8
    D3DTSS_BUMPENVMAT10   = 9
    D3DTSS_BUMPENVMAT11   = 10
    D3DTSS_MIPMAPLODBIAS  = 19
End Enum
D3DTSS_BUMPENVMAT00
텍스쳐 스테이지 스테이트는, 범프 맵핑 행렬의 [0][0] 계수에 대한 값이다. 디폴트값은 0 이다.
D3DTSS_BUMPENVMAT01
텍스쳐 스테이지 스테이트는, 범프 맵핑 행렬의 [0][1] 계수에 대한 값이다. 디폴트값은 0 이다.
D3DTSS_BUMPENVMAT10
텍스쳐 스테이지 스테이트는, 범프 맵핑 행렬의 [1][0] 계수에 대한 값이다. 디폴트값은 0 이다.
D3DTSS_BUMPENVMAT11
텍스쳐 스테이지 스테이트는, 범프 맵핑 행렬의 [1][1] 계수에 대한 값이다. 디폴트값은 0 이다.
D3DTSS_BUMPENVLSCALE
범프 맵 휘도(Luminance)용으로 스케일 한다. 디폴트값은 0 이다.
D3DTSS_BUMPENVLOFFSET
범프 맵 휘도(Luminance)용으로 오프셋(offset) 한다. 디폴트값은 0 이다.
D3DTSS_MIPMAPLODBIAS
밉맵 상세 바이어스의 레벨. 이것을 이용 하면, 텍스쳐에 질량감을 주거나 희미해진 느낌을 줄 수가 있다. 디폴트값은 0 이다.

주의

범프 맵핑 행렬 계수 D3DTSS_BUMPENVMAT00, D3DTSS_BUMPENVMAT01, D3DTSS_BUMPENVMAT10, 및 D3DTSS_BUMPENVMAT11 가 취할 수 있는 유효한 값의 범위는,-8. 0 이상 8.0 미만이다. 이 범위를 수학적으로는 [-8. 0,8.0] 으로 표기한다.

참조

Direct3DDevice7.GetTextureStageStateSingle ,Direct3DDevice7.SetTextureStageStateSingle


CONST_D3DTEXTURESTAGESTATETYPE

CONST_D3DTEXTURESTAGESTATETYPE 열거는, 텍스쳐 스테이지 스테이트를 정의한다. 이 열거의 정수는, 텍스쳐 스테이트값을 취득 및 설정하는 Direct3DDevice7.GetTextureStageState 메소드와 Direct3DDevice7.SetTextureStageState 메소드로 사용된다.

Enum CONST_D3DTEXTURESTAGESTATETYPE
    D3DTSS_ADDRESS        = 12
    D3DTSS_ADDRESSU       = 13
    D3DTSS_ADDRESSV       = 14
    D3DTSS_ALPHAARG1      = 5
    D3DTSS_ALPHAARG2      = 6
    D3DTSS_ALPHAOP        = 4
    D3DTSS_BORDERCOLOR    = 15
    D3DTSS_COLORARG1      = 2
    D3DTSS_COLORARG2      = 3
    D3DTSS_COLOROP        = 1
    D3DTSS_MAGFILTER      = 16
    D3DTSS_MAXANISOTROPY  = 21
    D3DTSS_MAXMIPLEVEL    = 20
    D3DTSS_MINFILTER      = 17
    D3DTSS_MIPFILTER      = 18
    D3DTSS_TEXCOORDINDEX  = 11
    D3DTSS_TEXTURETRANSFORMFLAGS = 24
End Enum
D3DTSS_ADDRESS
CONST_D3DTEXTUREADDRESS 열거의 멤버. u 좌표와 v 좌표의 양쪽 모두로 사용하는 텍스쳐 애드레싱 방법을 선택한다. 디폴트값은 D3DTADDRESS_WRAP 이다.
D3DTSS_ADDRESSU
CONST_D3DTEXTUREADDRESS 열거의 멤버. u 좌표로 사용하는 텍스쳐 애드레싱 방법을 선택한다. 디폴트값은 D3DTADDRESS_WRAP 이다.
D3DTSS_ADDRESSV
CONST_D3DTEXTUREADDRESS 열거의 멤버. v 좌표로 사용하는 텍스쳐 애드레싱 방법을 선택한다. 디폴트값은 D3DTADDRESS_WRAP 이다.
D3DTSS_ALPHAARG1
텍스쳐 스테이지 스테이트는, 그 스테이지에 대한 최초의 알파 인수이며,텍스쳐 인수 플래그에 의해 식별된다. 디폴트 인수는 D3DTA_TEXTURE 이다. 해당 스테이지에 텍스쳐가 설정되어 있지 않은 경우의 디폴트 인수는 D3DTA_DIFFUSE 이다.
D3DTSS_ALPHAARG2
텍스쳐 스테이지 스테이트는, 그 스테이지에 대한 2 번째의 알파 인수이며,텍스쳐 인수 플래그에 의해 식별된다. 디폴트 인수는 D3DTA_CURRENT 이다.
D3DTSS_ALPHAOP
텍스쳐 스테이지 스테이트는, 텍스쳐 알파 블렌딩 조작이며,CONST_D3DTEXTUREOP 열거의 정수의 1 개에 의해 식별되는 최초의 텍스쳐 스테이지 (스테이지 제로)의 디폴트값은 D3DTOP_SELECTARG1, 그 이외의 모든 스테이지의 디폴트값은 D3DTOP_DISABLE 이다.
D3DTSS_BORDERCOLOR
[0.0, 1.0] 의 범위의 밖에 있는 텍스쳐 좌표의 라스터화를 실행할 경우에 사용하는 색을 기술하는 값. 디폴트색은 0x00000000 이다.
D3DTSS_COLORARG1
텍스쳐 스테이지 스테이트는, 그 스테이지에 대한 최초의 색인수이며,텍스쳐 인수 플래그에 의해 식별된다. 디폴트 인수는 D3DTA_TEXTURE 이다.
D3DTSS_COLORARG2
텍스쳐 스테이지 스테이트는, 그 스테이지에 대한 2 번째의 색인수이며,텍스쳐 인수 플래그에 의해 식별된다. 디폴트 인수는 D3DTA_CURRENT 이다.
D3DTSS_COLOROP
텍스쳐 스테이지 스테이트는, 텍스쳐색블렌딩 조작이며,CONST_D3DTEXTUREOP 열거의 정수의 1 개에 의해 식별된다. 최초의 텍스쳐 스테이지 (스테이지 제로)의 디폴트값은 D3DTOP_MODULATE, 그 이외의 모든 스테이지의 디폴트값은 D3DTOP_DISABLE 이다.
D3DTSS_MAGFILTER
텍스쳐를 원시적으로 렌더링 할 경우에 사용되는 텍스쳐 확대 필터를 나타내는 CONST_D3DTEXTUREMAGFILTER 열거의 멤버. 디폴트값은 D3DTFG_POINT 이다.
D3DTSS_MAXANISOTROPY
비등방성 레벨의 최대치. 디폴트값은 1 이다.
D3DTSS_MAXMIPLEVEL
어플리케이션이 사용 가능한 최대 상세 레벨 밉맵. 제로가 디폴트값으로, 전레벨이 사용 가능한 것을 나타낸다.
D3DTSS_MINFILTER
텍스쳐를 원시적으로 렌더링 할 경우에 사용되는 텍스쳐 확대 필터를 나타내는 CONST_D3DTEXTUREMINFILTER 열거의 멤버. 디폴트값은 D3DTFN_POINT 이다.
D3DTSS_MIPFILTER
텍스쳐를 원시적으로 렌더링 할 경우에 사용되는 텍스쳐 확대 필터를 나타내는 CONST_D3DTEXTUREMIPFILTER 열거의 멤버. 디폴트값은 D3DTFP_NONE 이다.
D3DTSS_TEXCOORDINDEX
이 텍스쳐 스테이지에서 사용하기 위해서 설정된 텍스쳐 좌표 인덱스. 디폴트 인덱스는 0 이다. 이 스테이트는, 텍스쳐 스테이지가 사용하는, 각 버텍스에 대한 텍스쳐 세트의, 제로 베이스의 인덱스로 설정한다 (버텍스 1 개에 대해서 최대 8 세트까지의 텍스쳐 좌표를 설정할 수 있다). 버텍스가, 지정된 인덱스의 텍스쳐 좌표 세트를 가지지 않는 경우는, 시스템은 디폴트로서 u, v 좌표 (0,0)를 사용한다.

이 스테이트로 지정한 인덱스에 CONST_D3DTEXCOORDINDEXFLAGS 열거의 플래그를 짜넣어, 시스템이 인덱스값을 해석하는 방법을 변경할 수가 있다. 상세한 것에 대하여는, 「텍스쳐 좌표의 자동 생성의 구성」을 참조할것.

D3DTSS_TEXTURETRANSFORMFLAGS
이 텍스쳐 스테이지의 텍스쳐 좌표의 트랜스 폼을 제어하는 CONST_D3DTEXTURETRANSFORMFLAGS 열거의 멤버. 디폴트값은 D3DTTFF_DISABLE 이다.


CONST_D3DTEXTURETRANSFORMFLAGS

CONST_D3DTEXTURETRANSFORMFLAGS 열거는,D3DTSS_TEXTURETRANSFORMFLAGS 텍스쳐 스테이지 스테이트에서 사용된다.

Type CONST_D3DTEXTURETRANSFORMFLAGS
    D3DTTFF_COUNT1          = 1
    D3DTTFF_COUNT2          = 2
    D3DTTFF_COUNT3          = 3
    D3DTTFF_COUNT4          = 4
    D3DTTFF_DISABLE         = 0
    D3DTTFF_PROJECTED       = 256
End Type
D3DTTFF_COUNT1
래스터라이저는, 텍스쳐 좌표를 1D 좌표라고 본다.
D3DTTFF_COUNT2
래스터라이저는, 텍스쳐 좌표를 2D 좌표라고 본다.
D3DTTFF_COUNT3
래스터라이저는, 텍스쳐 좌표를 3D 좌표라고 본다.
D3DTTFF_COUNT4
래스터라이저는, 텍스쳐 좌표를 4D 좌표를 본다.
D3DTTFF_DISABLE
텍스쳐 좌표가 직접 래스터라이저에게 건네진다.
D3DTTFF_PROJECTED
텍스쳐 좌표를 래스터라이저에 건네주기 전에, 항상 마지막 요소로 나눗셈 한다. 예를 들어, D3DTTFF_COUNT3 플래그로 이 플래그가 지정되고 있는 경우, 텍스쳐 좌표가 래스터라이저에게 건네지기 전에, 1 번째와 2 번째의 텍스쳐 좌표가 3 번째의 텍스쳐 좌표에 의해 나눗셈 된다.

참조

D3DTSS_TEXTURETRANSFORMFLAGS


CONST_D3DTRANSFORMSTATETYPE

CONST_D3DTRANSFORMSTATETYPE 열거는, 트랜스 폼 스테이트를 기술하는 값을 정의한다.

Enum CONST_D3DTRANSFORMSTATETYPE
    D3DTRANSFORMSTATE_WORLD        = 1
    D3DTRANSFORMSTATE_WORLD1       = 4,
    D3DTRANSFORMSTATE_WORLD2       = 5,
    D3DTRANSFORMSTATE_WORLD3       = 6,
    D3DTRANSFORMSTATE_VIEW         = 2
    D3DTRANSFORMSTATE_PROJECTION   = 3
    D3DTRANSFORMSTATE_TEXTURE0     = 16
    D3DTRANSFORMSTATE_TEXTURE1     = 17
    D3DTRANSFORMSTATE_TEXTURE2     = 18
    D3DTRANSFORMSTATE_TEXTURE3     = 19
    D3DTRANSFORMSTATE_TEXTURE4     = 20
    D3DTRANSFORMSTATE_TEXTURE5     = 21
    D3DTRANSFORMSTATE_TEXTURE6     = 22
    D3DTRANSFORMSTATE_TEXTURE7     = 23
End Enum
D3DTRANSFORMSTATE_WORLD
트랜스 폼 하는 월드, 뷰, 투영의 행렬을 정의한다. 디폴트값은 Nothing 이다 (동일한 행렬).
D3DTRANSFORMSTATE_VIEW
트랜스 폼 하는 월드, 뷰, 투영의 행렬을 정의한다. 디폴트값은 Nothing 이다 (동일한 행렬).
D3DTRANSFORMSTATE_PROJECTION
트랜스 폼 하는 월드, 뷰, 투영의 행렬을 정의한다. 디폴트값은 Nothing 이다 (동일한 행렬).
D3DTRANSFORMSTATE_WORLD1
버텍스 포맷으로 지정된 행렬과 블렌딩의 중량감 (베타) 값을 사용해 버텍스를 블렌드 하는, 후속의 트랜스 폼 행렬을 식별한다.
D3DTRANSFORMSTATE_WORLD2
버텍스 포맷으로 지정된 행렬과 블렌딩의 중량감 (베타) 값을 사용해 버텍스를 블렌드 하는, 후속의 트랜스 폼 행렬을 식별한다.
D3DTRANSFORMSTATE_WORLD3
버텍스 포맷으로 지정된 행렬과 블렌딩의 중량감 (베타) 값을 사용해 버텍스를 블렌드 하는, 후속의 트랜스 폼 행렬을 식별한다.
D3DTRANSFORMSTATE_TEXTURE0 through D3DTRANSFORMSTATE_TEXTURE7
지정된 텍스쳐 스테이지로 설정되어 있는 트랜스 폼 행렬을 식별한다.

참조

CONST_D3DRENDERSTATETYPE ,지오메트리 블렌딩


CONST_D3DVBCAPSFLAGS

CONST_D3DVBCAPSFLAGS 열거는,D3DVERTEXBUFFERDESC 형의 lCaps 멤버로 사용되는 버텍스 버퍼 능력 플래그를 정의한다.

Enum CONST_D3DVBCAPSFLAGS
    D3DVBCAPS_DEFAULT = 0
    D3DVBCAPS_DONOTCLIP = 1
    D3DVBCAPS_OPTIMIZED = 2147483648
    D3DVBCAPS_SYSTEMMEMORY = 2048
    D3DVBCAPS_WRITEONLY = 65536
End Enum
D3DVBCAPS_DEFAULT
버텍스 버퍼는, 드라이버가 효율적인 리드 동작을 실행하기 위해서 선택한 메모리이면, 어느 메모리에 생성 해도 괜찮다.
D3DVBCAPS_DONOTCLIP
버텍스 버퍼는, 클리핑 정보를 보관 유지할 수 없다.
D3DVBCAPS_OPTIMIZED
버텍스 버퍼는, 최적화된 버텍스 데이터를 보관 유지한다 (이 플래그는, 새로운 버텍스 버퍼의 생성시에는 사용되지 않는다)
D3DVBCAPS_SYSTEMMEMORY
버텍스 버퍼는, 시스템 메모리에 생성 해야 한다. 소프트웨어 디바이스 (MMX 또는 RGB 디바이스)나 HAL 디바이스 (IID_IDirect3DHALDevice)를 사용해 렌더링 되는 버텍스 버퍼에는, 이 플래그를 사용한다.
D3DVBCAPS_WRITEONLY
어플리케이션이 버텍스 버퍼에 대해서 쓰기만 실시하는 것을, 시스템에 나타낸다. 이 플래그를 사용하는 것으로써, 드라이버는 최적인 메모리 영역을 선택해 효율적으로 쓰기 조작이나 렌더링을 실행한다. 이 능력을 이용해 생성 한 버텍스 버퍼로부터 읽기를 실시하려고 하면, 퍼포먼스가 저하하는 일이 있다.


CONST_D3DVERTEXBLENDFLAGS

CONST_D3DVERTEXBLENDFLAGS 열거는, 지오메트리 블렌딩시에 적용되는 행렬수를 제어하는 플래그를 정의한다. 이 열거의 멤버는,D3DRENDERSTATE_VERTEXBLEND 렌더링 스테이트에서 사용된다.

Enum CONST_D3DVERTEXBLENDFLAGS
    D3DVBLEND_1WEIGHT = 1
    D3DVBLEND_2WEIGHTS = 2
    D3DVBLEND_3WEIGHTS = 3
    D3DVBLEND_DISABLE = 0
End Enum
D3DVBLEND_1WEIGHT
D3DTRANSFORMSTATE_WORLD 와 D3DTRANSFORMSTATE_WORLD1 트랜스 폼 스테이트에서 설정된 2 개의 행렬간에서의 버텍스 블렌딩이 가능.
D3DVBLEND_2WEIGHTS
D3DTRANSFORMSTATE_WORLD ,D3DTRANSFORMSTATE_WORLD1 , 및 D3DTRANSFORMSTATE_WORLD2 트랜스 폼 스테이트에서 설정된 3 개의 행렬간에서의 버텍스 블렌딩이 가능.
D3DVBLEND_3WEIGHTS
D3DTRANSFORMSTATE_WORLD ,D3DTRANSFORMSTATE_WORLD1 ,D3DTRANSFORMSTATE_WORLD2 , 및 D3DTRANSFORMSTATE_WORLD3 트랜스 폼 스테이트에서 설정된 4 개의 행렬간에서의 버텍스 블렌딩이 가능.
D3DVBLEND_DISABLE
버텍스 블렌딩은 사용할 수 없다. D3DTRANSFORMSTATE_WORLD 트랜스 폼 스테이트에서 지정된 월드 행렬인 만큼 사용한다.

주의

지오메트리 블렌딩 (복수의 행렬에 의한 버텍스 블렌딩)에서는, 각 버텍스의 블렌딩의 중량감 (베타) 값을 포함한 버텍스 포맷을 사용할 필요가 있다.

참조

CONST_D3DRENDERSTATETYPE ,CONST_D3DTRANSFORMSTATETYPE ,Direct3DDevice7.SetTransform ,지오메트리 블렌딩


CONST_D3DVOPFLAGS

CONST_D3DVOPFLAGS 열거는,Direct3DVertexBuffer7.ProcessVertices 메소드의 vertexOp 파라미터로 사용되는 버텍스 조작 플래그를 정의한다.

Enum CONST_D3DVOPFLAGS
    D3DVOP_CLIP      = 2
    D3DVOP_EXTENTS   = 4
    D3DVOP_LIGHT     = 1024
    D3DVOP_TRANSFORM = 1
End Enum
D3DVOP_CLIP
버텍스를 트랜스 폼 해, 절두체의 외측에 나오는 모든 버텍스를 클립 한다. 이 플래그는, (예를 들어 D3DDP_DONOTCLIP 플래그로 만들어진 것 같은) 클리핑 정보를 포함하지 않는 버텍스 버퍼에 사용해서는 안 된다.
D3DVOP_EXTENTS
버텍스를 트랜스 폼 해, 버텍스가 렌더링 되면(자), 스크린 직사각형의 범위를 갱신한다. 이 플래그를 사용 하면 퍼포먼스가 향상할 가능성이 있지만,Direct3DDevice7.GetClipStatus 로 돌려주어지는 범위에 대해서, 이 호출로 렌더링 된 데이터를 고려한 갱신을 하지 않게 된다.
D3DVOP_LIGHT
버텍스를 라이팅 한다.
D3DVOP_TRANSFORM
월드 행렬, 뷰 행렬, 투영 행렬을 사용해 버텍스를 트랜스 폼 한다. 이 플래그는 항상 설정할 필요가 있다.


CONST_D3DVTXPCAPS

CONST_D3DVTXPCAPS 열거는, 디바이스가 D3DDEVICEDESC7 형의 lVertexProcessingCaps 멤버로 공개하는 버텍스의 처리 능력을 나타내는 플래그를 정의한다.

Type CONST_D3DVTXPCAPS
    D3DVTXPCAPS_DIRECTIONALLIGHTS = 8
    D3DVTXPCAPS_MATERIALSOURCE7 = 2
    D3DVTXPCAPS_NONLOCALVIEWER = 32
    D3DVTXPCAPS_POSITIONALLIGHTS = 16
    D3DVTXPCAPS_TEXGEN = 1
    D3DVTXPCAPS_VERTEXFOG = 4
End Type
D3DVTXPCAPS_DIRECTIONALLIGHTS
디바이스는 디렉셔널 라이트를 지원 한다.
D3DVTXPCAPS_MATERIALSOURCE7
디바이스는 선택 가능한 버텍스색소스를 지원 한다. 상세한 것에 대하여는, 「라이트의 색의 종류와 소스」를 참조할것.
D3DVTXPCAPS_NONLOCALVIEWER
디바이스는 정스펙큐러 하이라이트를 지원 한다. 이 기능은,D3DRENDERSTATE_LOCALVIEWER 렌더링 스테이트를 FALSE 로 설정하는 것에 의해 사용할 수 있다.
D3DVTXPCAPS_POSITIONALLIGHTS
디바이스는 국부 라이트 (포인트 라이트나 spotlight등)를 지원 한다.
D3DVTXPCAPS_TEXGEN
디바이스는 텍스쳐 좌표를 생성할 수 있다.
D3DVTXPCAPS_VERTEXFOG
디바이스는 버텍스 포그(안개:fog)를 지원 한다.

참조

D3DDEVICEDESC7


CONST_D3DZBUFFERTYPE

CONST_D3DZBUFFERTYPE 열거는,D3DRENDERSTATE_ZENABLE 렌더링 스테이트에서 사용하는 깊이 버퍼 포맷을 기술한다.

Enum CONST_D3DZBUFFERTYPE
    D3DZB_FALSE        = 0
    D3DZB_TRUE         = 1
    D3DZB_USEW         = 2
End Enum
D3DZB_FALSE
깊이 버퍼의 사용을 무효로 한다.
D3DZB_TRUE
z 버퍼의 사용을 가능하게 한다.
D3DZB_USEW
w 버퍼의 사용을 가능하게 한다.

주의

D3DZB_FALSE 와 D3DZB_TRUE 값은, 이전 D3DRENDERSTATE_ZENABLE 로 사용되고 있던 TRUE, FALSE 매크로와 바꿔 넣고 가능하다.

참조

Direct3DDevice7.SetRenderState ,깊이 버퍼


유연한 버텍스 포맷 플래그

Direct3D 직접 모드는 플래그의 값을 사용해, DrawPrimitive 준거의 렌더링으로 사용하는 버텍스 포맷을 표현한다. CONST_D3DFVFFLAGS 열거에는, 다음에 열기하는 플래그가 정의되고 있어 이것에 의해 버텍스 포맷을 명시적으로 기술할 수 있다. 또, 이 열거는, 이러한 플래그의 자주(잘) 사용되는 편성을 헬퍼-매크로로서 제공하고 있다. 상세한 것에 대하여는, 「버텍스 포맷에 대하며」를 참조할것.

유연한 버텍스 포맷 (FVF) 플래그
D3DFVF_DIFFUSE
버텍스 포맷이 디퓨즈색성분을 포함한다.
D3DFVF_LVERTEX
버텍스 포맷은 D3DLVERTEX 버텍스 타입에 대응한다.
D3DFVF_NORMAL
버텍스 포맷이 버텍스 법선 벡터를 포함한다. 이 플래그를, D3DFVF_XYZRHW 와 함께 사용할 수 없다.
D3DFVF_SPECULAR
버텍스 포맷이 스펙큐러색성분을 포함한다.
D3DFVF_TLVERTEX
버텍스 포맷은 D3DTLVERTEX 버텍스 타입에 대응한다.
D3DFVF_VERTEX
버텍스 포맷은 D3DVERTEX 버텍스 타입에 대응한다.
D3DFVF_XYZ
버텍스 포맷이 트랜스폼 되지 않은 버텍스의 위치 좌표를 포함한다. 이 플래그를, D3DFVF_XYZRHW 와 함께 사용할 수 없다. 이 플래그를 사용하는 경우는, 동시에 버텍스 법선과 버텍스색성분 (D3DFVF_DIFFUSE 또는 D3DFVF_SPECULAR)을 지정하는지, 또는, 적어도 1 세트의 텍스쳐 좌표 (D3DFVF_TEX1 로부터 D3DFVF_TEX8)를 포함할 필요가 있다.
D3DFVF_XYZRHW
버텍스 포맷이, 트랜스 폼 된 버텍스의 위치 좌표를 포함한다. 이 플래그를 D3DFVF_XYZ 또는 D3DFVF_NORMAL 플래그와 동시에 사용할 수 없다. 이 플래그를 사용하는 경우는, 동시에 버텍스색성분 (D3DFVF_DIFFUSE 또는 D3DFVF_SPECULAR)을 지정하는지, 또는, 적어도 1 세트의 텍스쳐 좌표 (D3DFVF_TEX1 로부터 D3DFVF_TEX8)를 포함할 필요가 있다.
D3DFVF_XYZB1 로부터 D3DFVF_XYZB5
버텍스 포맷이, 위치 좌표 데이터와 복수의 행렬에 의한 버텍스 블렌딩 조작으로 사용하는 중량감 (베타) 값의 수를 포함한다. 현재, Direct3D 는 최고 3 개의 중량감값 (와 4 개의 블렌딩 행렬)을 사용해 블렌드를 실시할 수가 있다.
텍스쳐 관련 FVF 플래그
D3DFVF_TEX0 through D3DFVF_TEX8
이 버텍스에 대응하는 텍스쳐 좌표 세트의 번호. 이러한 플래그에 대응하는 숫자는 연속 번호로 되어 있지 않다.

참조

버텍스 포맷에 대해,지오메트리 블렌딩


텍스쳐 인수 플래그

디바이스에 대응하는 각각의 텍스쳐 스테이지는 2 개의 텍스쳐 인수를 가질 수가 있어 이러한 인수는 텍스쳐의 색과 알파 채널에 영향을 준다. 텍스쳐 인수를 설정 및 취득하려면 , 각각 Direct3DDevice7.SetTextureStageState 메소드와 Direct3DDevice7.GetTextureStageState 메소드를 호출해,CONST_D3DTEXTURESTAGESTATETYPE 열거의 D3DTSS_COLORARG1, D3DTSS_COLORARG2, D3DTSS_ALPHAARG1 또는 D3DTSS_ALPHAARG2 정수를 지정한다.

다음에 나타내는 플래그 (인수와 수정자에게 정리하고 있다)를 텍스쳐 스테이지의 색과 알파 인수와 함께 사용할 수가 있다. 인수 플래그와 수정자를 조합할 수 있지만, 2 개의 인수 플래그를 조합할 수 없다.

인수 플래그
D3DTA_CURRENT
텍스쳐 인수는 전의 블렌딩 스테이지의 결과이다. 최초의 텍스쳐 스테이지 (스테이지 제로)에서는, 이 인수는 디폴트값 D3DTA_DIFFUSE 를 취한다. 전의 블렌딩 스테이지에서 범프 맵 텍스쳐 (D3DTOP_BUMPENVMAP 조작)를 사용하는 경우, 시스템은 범프 맵 텍스쳐의 전의 스테이지로부터 텍스쳐를 선택한다(현재의 텍스쳐 스테이지를 s 와 하면,s – 1 에 범프 맵 텍스쳐가 포함되어 이 인수가 텍스쳐 스테이지 s – 2 의 출력이 된다).
D3DTA_DIFFUSE
텍스쳐 인수는, gouraud shading 처리중에 버텍스 성분으로부터 보간 해 얻을 수 있던 디퓨즈색이다. 버텍스가 디퓨즈색을 포함하지 않는 경우의 디폴트색은 0xFFFFFFFF 이다.
D3DTA_SELECTMASK
모든 인수에 대응하는 마스크값. 텍스쳐 인수의 설정에는 사용하지 않는다.
D3DTA_SPECULAR
텍스쳐 인수는, gouraud shading 처리중에 버텍스 성분으로부터 보간 해 얻을 수 있던 디퓨즈색이다. 버텍스가 스펙큐러색을 포함하지 않는 경우의 디폴트색은 0xFFFFFFFF 이다.
D3DTA_TEXTURE
텍스쳐 인수는, 이 텍스쳐 스테이지의 텍스쳐색이다. 이것이 유효한 것은, 스테이지의 최초의 색과 알파 인수 에 대해서만이다 (CONST_D3DTEXTURESTAGESTATETYPE 의 D3DTSS_COLORARG1 멤버와 D3DTSS_ALPHAARG1 정수). 이 블렌딩 인수를 사용하는 스테이지에 텍스쳐가 설정되어 있지 않은 경우, 시스템은 디폴트로 컬러값 R, G, B 와 알파를 각각 1.0 으로 설정한다.
D3DTA_TFACTOR
텍스쳐 인수는, 전회 D3DRENDERSTATE_TEXTUREFACTOR 렌더링 스테이트값을 사용해 Direct3DDevice7.SetRenderState 를 호출했을 때의 텍스쳐 팩터 세트이다.
수정자 플래그
D3DTA_ALPHAREPLICATE
조작이 완료하기 전에, 알파 정보를 모든 색채널에 카피한다.
D3DTA_COMPLEMENT
인수의 역수를 취한다. 예를 들어, 인수의 결과가 변수 x 라면, 그 값은 1.0 - x 가 된다.


에러 코드

CONST_D3DIMERR 열거로 정의되는 에러 코드는, 부의 값으로 나타내져 조합해 사용할 수 없다. 이 표는, 모든 Direct3D 직접 모드 메소드를 생성할 수 있는 에러 코드를 집계한 것이다. 각 메소드가 돌려줄 수 있는 값의 일람에 대해서는, 메소드의 각각의 기술을 참조할것.

D3D_OK
에러는 발생하고 있지 않다.
D3DERR_BADMAJORVERSION
요구된 서비스는, DirectX 의 이 메이저 버젼에서는 사용할 수 없다 ( 「메이저 버젼」이란, DirectX 6.0 등의 일차 릴리스를 가리킨다).
D3DERR_BADMINORVERSION
요구된 서비스는, DirectX 의 이 메이저 버젼에서는 사용할 수 있지만, 이 마이너 버젼에서는 사용할 수 없다. 최신 버젼의 런타임 컴퍼넌트는 Microsoft 로부터 입수할 수 있다 ( 「마이너 버젼」이란, DirectX 6.1 등의 2차 릴리스를 가리킨다).
D3DERR_COLORKEYATTACHED
투과성을 위한 컬러 키를 사용하는 표면으로 텍스쳐를 생성 하려고 했다.
D3DERR_CONFLICTINGTEXTUREFILTER
현재의 텍스쳐 필터를 동시에 사용할 수 없다.
D3DERR_CONFLICTINGTEXTUREPALETTE
현재의 텍스쳐를 동시에 사용할 수 없다. 보통, 멀티 텍스쳐 디바이스로, 유효한 모든 팔레트화 텍스쳐로 같은 팔레트를 공유하려고 하는 곳의 에러가 발생한다.
D3DERR_CONFLICTINGRENDERSTATE
현재 설정되어 있는 렌더링 스테이트를 동시에 사용할 수 없다.
D3DERR_DEVICEAGGREGATED
렌더링 타겟 표면으로부터 취득된 디바이스로 Direct3DDevice7.SetRenderTarget 메소드가 불려 갔다.
D3DERR_INITFAILED
새로운 디바이스를 초기화할 수 없었기 (위해)때문에, 렌더링 디바이스를 생성 할 수 없었다.
D3DERR_INBEGIN
장면의 렌더링시에 요구된 조작을 완료할 수 없었다. 장면이 완료해,Direct3DDevice7.EndScene 메소드 (또는 동등의 기능을 가지는 메소드)를 호출하고 나서 재시행하는 것.
D3DERR_INBEGINSTATEBLOCK
스테이트 블록에의 스테이트 기록시에 조작을 완료할 수 없었다. Direct3DDevice7.EndStateBlock 메소드를 호출해 재시행해, 기록을 완료하는 것.
D3DERR_INOVERLAYSTATEBLOCK
스테이트 블록의 오버레이시에 조작을 완료할 수 없었다. 스테이트 블록의 오버레이를 삭제하고 나서 재시행하는 것.
D3DERR_INVALID_DEVICE
요구된 디바이스의 타입이 무효이다.
D3DERR_INVALIDCURRENTVIEWPORT
현재 선택되고 있는 뷰포트가 무효이다.
D3DERR_INVALIDMATRIX
현재 설정되어 있는 월드, 뷰, 및 투영 행렬의 편성이 무효이기 때문에 (이 편성에서는 행렬식이 제로가 된다), 요구된 조작을 완료할 수 없었다.
D3DERR_INVALIDPALETTE
표면에 관련지을 수 있었던 표면이 무효이다.
D3DERR_INVALIDPRIMITIVETYPE
어플리케이션에 의해 지정된 프리미티브가 무효이다.
D3DERR_INVALIDRAMPTEXTURE
램프 모드가 사용되어 현재의 머트리얼의 텍스쳐 핸들은, 렌더링 스테이트로서 설정된 현재의 텍스쳐 핸들에 적합하지 않는다.
D3DERR_INVALIDSTATEBLOCK
스테이트 블록 핸들이 무효이다.
D3DERR_INVALIDVERTEXFORMAT
어플리케이션에 의해 지정된유연한 버텍스 포맷 플래그의 편성이 무효이다.
D3DERR_INVALIDVERTEXTYPE
어플리케이션에 의해 지정된 버텍스의 타입이 무효이다.
D3DERR_LIGHT_SET_FAILED
라이팅 오브젝트의 라이팅 파라미터를 설정하려고 했지만 실패했다.
D3DERR_LIGHTHASVIEWPORT
라이팅 오브젝트가 다른 뷰포트에 관련지을 수 있고 있기 (위해)때문에, 요구된 조작이 실패했다.
D3DERR_LIGHTNOTINTHISVIEWPORT
라이팅 오브젝트가 이 뷰포트에 관련지을 수 있지 않기 때문에, 요구된 조작이 실패했다.
D3DERR_MATERIAL_CREATE_FAILED
머트리얼을 생성 할 수 없었다. 보통, 머트리얼에 할당하고 가능한 메모리가 없는 경우에 이 에러가 발생한다.
D3DERR_MATERIAL_DESTROY_FAILED
머트리얼에 대한 메모리의 할당을 삭제할 수 없었다.
D3DERR_MATERIAL_GETDATA_FAILED
머트리얼 파라미터를 취득할 수 없었다.
D3DERR_MATERIAL_SETDATA_FAILED
머트리얼 파라미터를 설정할 수 없었다.
D3DERR_MATRIX_CREATE_FAILED
행렬을 생성 할 수 없었다. 행렬에 할당하고 가능한 메모리가 없을 가능성이 있다.
D3DERR_MATRIX_DESTROY_FAILED
행렬에 대한 메모리의 할당을 삭제할 수 없었다.
D3DERR_MATRIX_GETDATA_FAILED
행렬 데이터를 취득할 수 없었다. 행렬이 현재의 디바이스에 의해 생성되어 있지 않을 가능성이 있다.
D3DERR_MATRIX_SETDATA_FAILED
행렬 데이터를 설정할 수 없었다. 행렬이 현재의 디바이스에 의해 생성되어 있지 않을 가능성이 있다.
D3DERR_NOCURRENTVIEWPORT
뷰포트 파라미터가 설정되어 있지 않기 때문에 취득할 수 없었다.
D3DERR_NOTINBEGIN
장면의 렌더링이 시작되어 있지 않기 때문에, 요구된 렌더링 조작을 완료할 수 없었다. Direct3DDevice7.BeginScene 를 호출해 렌더링을 시작 하고 나서 재시행하는 것.
D3DERR_NOTINBEGINSTATEBLOCK
요구된 조작은 스테이트 블록의 기록중만 유효해서, 조작을 완료할 수 없었다. Direct3DDevice7.BeginStateBlock 메소드를 호출해 재시행하는 것.
D3DERR_NOVIEWPORTS
디바이스에 관련지을 수 있었던 뷰포트가 없기 때문에, 요구된 조작이 실패했다.
D3DERR_SCENE_BEGIN_FAILED
장면의 렌더링을 시작 할 수 없었다.
D3DERR_SCENE_END_FAILED
장면의 렌더링을 완료할 수 없었다.
D3DERR_SCENE_IN_SCENE
전의 장면이 Direct3DDevice7.EndScene 메소드에 의해 완료되어 있지 않기 때문에, 장면의 렌더링을 시작 할 수 없었다.
D3DERR_SCENE_NOT_IN_SCENE
Direct3DDevice7.BeginScene 메소드에 의해 장면이 시작되어 있지 않기 때문에, 장면의 렌더링을 완료할 수 없었다.
D3DERR_SETVIEWPORTDATA_FAILED
뷰포트 파라미터를 설정할 수 없었다.
D3DERR_STENCILBUFFER_NOTPRESENT
렌더링 타겟 표면에 Attach 된 스텐실 버퍼가 없기 때문에, 요구된 스텐실 버퍼 조작을 완료할 수 없었다.
D3DERR_SURFACENOTINVIDMEM
렌더링 타겟 표면이 비디오 메모리에 존재하지 않기 때문에, 디바이스를 생성 할 수 없었다 (하드웨어 가속화 디바이스에서는 비디오 메모리에 렌더링 타겟 표면이 존재해야 한다).
D3DERR_TEXTURE_BADSIZE
현재의 텍스쳐의 사이즈가 무효이다. 2 말하고 나무승의 크기의 텍스쳐가 필요한 디바이스로, 2 말하고 나무승이 아닌 크기의 텍스쳐를 사용하려고 하면(자), 이 에러가 발생할 가능성이 있다.
D3DERR_TEXTURE_CREATE_FAILED
텍스쳐에 대한 텍스쳐 핸들을 드라이버로부터 취득할 수 없었다.
D3DERR_TEXTURE_DESTROY_FAILED
디바이스가 텍스쳐에 대한 메모리의 할당을 삭제할 수 없었다.
D3DERR_TEXTURE_GETSURF_FAILED
텍스쳐의 생성에 사용하는 DirectDraw 표면을 취득할 수 없었다.
D3DERR_TEXTURE_LOAD_FAILED
텍스쳐를 로드할 수 없었다.
D3DERR_TEXTURE_LOCK_FAILED
텍스쳐를 잠글 수 없었다.
D3DERR_TEXTURE_LOCKED
텍스쳐 표면이 현재 락 되고 있기 (위해)때문에, 요구된 조작을 완료할 수 없었다.
D3DERR_TEXTURE_NO_SUPPORT
이 디바이스는 텍스쳐 맵핑을 지원 하고 있지 않다.
D3DERR_TEXTURE_NOT_LOCKED
텍스쳐 표면이 락되어 있지 않기 때문에, 요구된 조작을 완료할 수 없었다.
D3DERR_TEXTURE_SWAP_FAILED
텍스쳐 핸들을 스왑 할 수 없었다.
D3DERR_TEXTURE_UNLOCK_FAILED
텍스쳐 표면의 락을 해제할 수 없었다.
D3DERR_TOOMANYOPERATIONS
디바이스가 지원 하고 있는 수보다 많은 텍스쳐 필터링 조작을 어플리케이션이 요구하고 있다.
D3DERR_TOOMANYPRIMITIVES
이 디바이스에서는, 요구된 양의 프리미티브를 단일 패스로 렌더링 할 수 없다.
D3DERR_UNSUPPORTEDALPHAARG
지정된 알파 채널의 텍스쳐 블렌딩 인수의 어느쪽이든을 디바이스가 지원 하고 있지 않다.
D3DERR_UNSUPPORTEDALPHAOPERATION
지정된 알파 채널의 텍스쳐 블렌딩 조작의 어느쪽이든을 디바이스가 지원 하고 있지 않다.
D3DERR_UNSUPPORTEDCOLORARG
지정된 컬러값의 텍스쳐 블렌딩 인수의 어느쪽이든을 디바이스가 지원 하고 있지 않다.
D3DERR_UNSUPPORTEDCOLOROPERATION
지정된 컬러값의 텍스쳐 블렌딩 조작의 어느쪽이든을 디바이스가 지원 하고 있지 않다.
D3DERR_UNSUPPORTEDFACTORVALUE
지정된 텍스쳐 계수값을 디바이스가 지원 하고 있지 않다.
D3DERR_UNSUPPORTEDTEXTUREFILTER
지정된 텍스쳐 필터를 디바이스가 지원 하고 있지 않다.
D3DERR_VBUF_CREATE_FAILED
버텍스 버퍼를 생성 할 수 없었다. 버텍스 버퍼에 할당하는 충분한 메모리가 없을 가능성이 있다.
D3DERR_VERTEXBUFFERLOCKED
버텍스 버퍼가 락 되고 있기 (위해)때문에, 요구된 조작을 완료할 수 없었다.
D3DERR_VERTEXBUFFEROPTIMIZED
버텍스 버퍼가 최적화되어 있지 않기 때문에, 요구된 조작을 완료할 수 없었다 (최적화된 버텍스 버퍼의 내용은 드라이버 고유해, Private라고 보여진다).
D3DERR_VERTEXBUFFERUNLOCKFAILED
버텍스 버퍼의 메모리가 오버 런 했으므로, 버텍스 버퍼의 락을 해제할 수 없었다. 버텍스 버퍼의 사이즈를 넘는 쓰기를 실시하지 않은지 어떤지 확인하는 것.
D3DERR_VIEWPORTDATANOTSET
뷰포트 파라미터가 설정되어 있지 않기 때문에, 요구된 조작을 완료할 수 없었다. Direct3DDevice7.SetViewport 메소드를 호출해 뷰포트 파라미터를 설정하고 나서 재시행하는 것.
D3DERR_VIEWPORTHASNODEVICE
뷰포트를 디바이스에 관련지을 수 있지 않기 때문에, 요구된 조작을 완료할 수 없었다.
D3DERR_WRONGTEXTUREFORMAT
텍스쳐 표면의 픽셀 포맷이 무효이다.
D3DERR_ZBUFF_NEEDS_SYSTEMMEMORY
지정된 디바이스에서는 시스템 메모리에 깊이 버퍼 표면이 존재해야 하기 때문에, 요구된 조작을 완료할 수 없었다 (소프트웨어 렌더링 디바이스에서는 시스템 메모리에 깊이 버퍼가 존재해야 한다).
D3DERR_ZBUFF_NEEDS_VIDEOMEMORY
지정된 디바이스에서는 비디오 메모리에 깊이 버퍼 표면이 존재해야 하기 때문에, 요구된 조작을 완료할 수 없었다 (하드웨어 가속화 디바이스에서는 비디오 메모리에 깊이 버퍼가 존재해야 한다).
D3DERR_ZBUFFER_NOTPRESENT
렌더링 타겟 표면에 깊이 버퍼가 Attach되어 있지 않기 때문에, 요구된 조작을 완료할 수 없었다.


Direct3D 직접 모드의 툴과 샘플

여기에서는, Microsoft® DirectX® SDK 의 샘플 어플리케이션에 대해 설명한다. 이 샘플 어플리케이션의 목적은, Microsoft® Direct3D® 직접 모드의 사용 방법을 시 것이다. 설명하는 내용은 이하대로이다.

  • Direct3D 직접 모드 툴
  • Direct3D 직접 모드 C++ 샘플
  • Direct3D 직접 모드 Visual Basic 샘플


Direct3D 직접 모드 툴

여기에서는, DirectX Software Development Kit (SDK)로 제공되는 이하의 툴에 대해 설명한다.

  • MFCTex 툴


MFCTex 툴

설명

MFCTex 란, 멀티 텍스쳐 블렌딩을 적용하기 전에 프리뷰 할 수 있는 인터랙티브 툴이다. 이 툴에 의해, 희망의 이펙트를 얻기 위해서(때문에) 필요한 코드를 생성할 수도 있다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\Mfctex

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\Mfctex.exe

유저즈 가이드

비트 맵을 3 개까지 선택해, 텍스트 박스와 드롭 다운 리스트를 사용해 파라미터를 변경한다. 2 개(살) 밖에 사용하지 않는 경우는,Texture File 텍스트 박스의 1 개를 공백으로 해 둔다.

어플리케이션으로 사용하는 이펙트를 얻을 수 있으면(자),View Code 를 클릭해,Direct3D Texture Stage Code 다이알로그 박스로부터 모든 텍스트를 카피한다.

변경 가능한 파라미터의 상세한 것에 대하여는, 「멀티 텍스쳐 블렌딩」을 참조할것.


Direct3D 직접 모드 C++ 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

여기에서는, DirectX SDK 로 제공되는 샘플 어플리케이션에 대해 설명한다. 여기서 설명되는 어플리케이션의 주된 목적은, Direct3D 직접 모드의 사용 방법을 나타내는 것이다. 다음의 샘플에 대해 설명한다.

  • Bend 샘플
  • Billboard 샘플
  • Boids 샘플
  • BumpEarth 샘플
  • BumpWaves 샘플
  • ClipMirror 샘플
  • Compress 샘플
  • D3DFrame 라이브러리
  • Dolphin 샘플
  • EnumTex 샘플
  • EnvCube 샘플
  • Filter 샘플
  • Fireworks 샘플
  • Flare 샘플
  • LightMap 샘플
  • Lights 샘플
  • MFCFog 샘플
  • MipMap 샘플
  • MTexture 샘플
  • ScreenSaver 샘플
  • ShadowVol 샘플
  • ShadowVol2 샘플
  • Spheremap 샘플
  • StencilDepth 샘플
  • StencilMirror 샘플
  • VBuffer 샘플
  • VideoTex 샘플
  • WBuffer 샘플
  • XFile 샘플

주 : 샘플 프로그램의 대부분은, 도구모음이 없는 공통 인터페이스 (D3DFrame 라이브러리 에 있다)를 사용하고 있다. 보통의 Microsoft Windows® 기능 (최소화, 최대화, restore, 사이즈 변경, 닫는다)에 가세해, 이 인터페이스는, 다음의 커멘드를 지원 하고 있다.

키 / 입력 | 커멘드
Esc | Quit
F1 | Help/About 다이알로그 박스 (이러한 키 입력을 표시)
F2 | 디바이스 옵션
Alt + Enter | 풀 스크린과 윈도우 모드를 바꾸는 「
오른쪽 mouse button | 옵션 pop-up menu를 표시

디바이스 옵션 다이알로그 박스를 사용해, 실행시에, 드라이버, Direct3D 디바이스, 디스플레이 모드 (풀 스크린만)를 변경할 수 있다. 모든 디바이스가, 모든 디스플레이 깊이의 윈도우 렌더링을 지원 하고 있는 것은 아니다. 3D 하드웨어의 비디오 메모리에는 한계가 있어, 어느 디스플레이 모드와 윈도우 사이즈를 사용 하면, 용량을 넘어 버리는 일이 있다. 어느 쪽의 경우에서도, 샘플은 메세지를 표시해, 소프트웨어 래스터라이저에 디폴트 설정한다.

DirectX 샘플에는 Microsoft® Visual C++® 프로젝트 워크 스페이스 파일이 포함되어 있지만, 샘플이 올바르고 컴파일 되도록, 개발 환경에서 다른 설정을 확인할 필요가 생기는 경우도 있다. 상세한 것에 대하여는, 「DirectX 의 샘플 및 그 외의 DirectX 어플리케이션의 컴파일」을 참조할것.

See Also

「Direct3D 직접 모드의 C/C++ 튜토리얼 」을 참조할것.


Bend 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

Bend 샘플에서는, 표면 스키닝으로 불리는 기법을 나타낸다. 3D 오브젝트가 표시되어 y 축의 주위를 회전해, 구부러지는 것처럼 보인다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\Bend

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\Bend.exe

유저즈 가이드

이용 가능한 커멘드를 조사하려면 , F1 키를 누르는지, 메뉴로부터 선택한다.

프로그래밍 위에의 주의

이 샘플은, 오브젝트의 2 개의 정적 카피를 사용해 표면 스키닝 이펙트를 내고 있다. 2 개의 카피중 1 개(살)은, 어느 축을 중심으로 회전하고 있다. 각 프레임으로 2 개의 오브젝트의 버텍스는 머지 되어 제３ 오브젝트에 블렌드 된다. 샘플 프로그램은, 버텍스의 제３ 세트로부터 이끌린 오브젝트를 표시한다.

이 샘플은, Direct3D 샘플 프레임워크(framework)를 사용해 빌드 되었다.


Billboard 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

Billboard 샘플에서는, 빌보딩 기법을 나타낸다. 빌보딩이란, 2D 스프라이트를 3D 에 보이는 방법이다. 이 기법은, 연, 운, 수증기의 궤적, 에너지 blast 등에 사용할 수도 있다. 상세한 것에 대하여는, 「공통의 테크놀러지와 특수 효과」를 참조할것.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\Billboard

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\Billboard.exe

유저즈 가이드

이용 가능한 커멘드를 조사하려면 , F1 키를 누르는지, 메뉴로부터 선택한다.

프로그래밍 위에의 주의

이 샘플은, 나무가 있는 초원을 표시한다. 나무들은 3D 오브젝트와 같이 보인다. 그러나, 이것들은, 실제로는 2D 텍스쳐 비트 맵으로, 안보이는 직사각형 다각형에 블렌드 되고 있다.

샘플 프로그램을 실행 하면, 시점이 변화한다. 시점이 변화할 때마다, 나무들이 드로잉(Drawing) 되는 모든 빌보드 다각형은 회전해, 뷰아의 분을 향한다. 다음에, 프로그램은, 나무들의 이미지를 빌보드 다각형에 블렌드 한다. 나무들은, 모든 각도로부터 볼 수가 있기 (위해)때문에, 3D 인것 같이 보인다. 다만, 자세하게 조사하면(자), 나무들은 모든 각도로부터 완전히 같게 보이는 것을 알 수 있다. 많은 어플리케이션으로, 유저가 이 작은 결점을 눈치챌 것은 없다.

그림자도, 2D 텍스쳐이다.

이 샘플은, Direct3D 샘플 프레임워크(framework)를 사용해 빌드 되었다.


Boids 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

Boids 샘플은, Direct3D 어플리케이션을 기술하는 방법을 나타낸다. 이 샘플에서는, 후록킹아르고리즘을 사용해, 단순한 배경 위에서 3D 오브젝트의 그룹을 움직인다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\Boids

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\Boids.exe

유저즈 가이드

이용 가능한 커멘드를 조사하려면 , F1 키를 누르는지, 메뉴로부터 선택한다.

프로그래밍 위에의 주의

Boids 샘플은, 3D 환경을 생성 해, 그 중에 오브젝트의 그룹을 애니메이션하기 위한 기본을 나타낸다.


BumpEarth 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

BumpEarth 샘플에서는, Direct3D 의 범프 맵핑 능력을 나타낸다. 범프 맵핑이란, 엉성한 표면의 외관을 렌더링 할 때에 사용되는 텍스쳐 블렌딩 기법이다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\BumpEarth

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\BumpEarth.exe

유저즈 가이드

이용 가능한 커멘드를 조사하려면 , F1 키를 누르는지, 메뉴로부터 선택한다.

그래픽스 하드웨어가 범프 맵핑을 지원 하지 않는 경우, 이 샘플을 실행하려고 하면(자), Direct3D 는 범프 맵핑이 지원되어 있지 않은 것을 고하는 메세지를 표시한다. 이 문제를 해결하려면 , (SDK 루트)) \Samples\Multimedia\D3dim\Bin\Enablerefrast.reg 를 실행해, 레퍼런스 래스터라이저를 유효하게 한다.

프로그래밍 위에의 주의

범프 맵핑은 고도의 멀티 텍스쳐 블렌딩 기법으로, 요철의 표면의 외관을 렌더링 하는데 사용된다. 범프 맵 자체는 텍스쳐로, 보정을 위한 데이터를 보존하고 있다.

이 샘플 프로그램에 대해, 세계 지도는 텍스쳐이다. 맵 텍스쳐와 범프 맵 텍스쳐가 샘플에 의해 구(공)에 블렌드 되어 고해상도의 지형도를 얻을 수 있다.

상세한 것에 대하여는, 「범프 맵핑」과「BumpWaves 샘플」을 참조할것.

이 샘플은, Direct3D 샘플 프레임워크(framework)를 사용해 빌드 되었다.


BumpWaves 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

BumpWaves 샘플에서는, 범프 맵핑을 사용해 물결의 반사를 시뮬레이트 한다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\BumpWaves

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\BumpWaves.exe

유저즈 가이드

이용 가능한 커멘드를 조사하려면 , F1 키를 누르는지, 메뉴로부터 선택한다.

그래픽스 하드웨어가 범프 맵핑을 지원 하지 않는 경우, 이 프로그램을 실행하려고 하면(자), Direct3D 는 범프 맵핑이 지원되어 있지 않은 것을 고하는 메세지를 표시한다. 이 문제를 해결하려면 , 레퍼런스 래스터라이저를 유효하게 한다. 레퍼런스 래스터라이저를 유효하게 하려면 , (SDK 루트) \Samples\Multimedia\D3dim\Bin\Enablerefrast.reg 를 실행한다.

프로그래밍 위에의 주의

상세한 것에 대하여는, 「범프 맵핑」과「BumpEarth 샘플」을 참조할것.

이 샘플은, Direct3D 샘플 프레임워크(framework)를 사용해 빌드 되었다.


ClipMirror 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는,Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

ClipMirror 샘플에서는, 클립면을 사용해 평면 밀러를 이행 하는 방법을 나타낸다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\ClipMirror

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\ClipMirror.exe

유저즈 가이드

이용 가능한 커멘드를 조사하려면 , F1 키를 누르는지, 메뉴로부터 선택한다.

프로그래밍 위에의 주의

장면은 밀러로 반사되어 2 번째의 패스로 렌더링 된다. 반사된 지오메트리가 밀러의 경계내에게만 표시되도록(듯이), 밀러의 모퉁이와 카메라의 시점을 사용해, 클립면의 커스텀 세트를 정의한다.


Compress 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

Compress 샘플에서는, DDS 파일 형식이 압축된 텍스쳐 표면에 로드하는 방법을 나타낸다. DDS 텍스쳐는, DirectX SDK 의 DirectDraw 툴에 포함되어 있는 DxTex 프로그램을 사용해 생성 할 수 있다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\Compress

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\Compress.exe

유저즈 가이드

이용 가능한 커멘드를 조사하려면 , F1 키를 누르는지, 메뉴로부터 선택한다.

프로그래밍 위에의 주의

파일 포맷이 DDS 로 불리는 것은, 정보를 DirectDrawSurface 에 캡슐화하기 때문이다. 데이터는, 일치하는 포맷의 표면에 직접 읽어들일 수 있다.

ReadDDSTexture 함수는, DDS 표면이, 파일로부터 어떻게 읽히는지를 나타낸다.

DDS 파일의 포맷은, 다음과 같다.

DWORD dwMagic | (0 x20534444, 또는 "DDS ")
DDSURFACEDESC2 ddsd | 표면의 포맷에 관한 정보
BYTE bData1[] | 주표면의 데이터
[BYTE bData2[] | 추가 표면의 데이터가 있으면, 계속된다

이 포맷은 읽고 쓰기가 간단해, DXTn 압축 뿐만이 아니라, 알파나 마르치밉레벨등의 기능도 지원 한다. DXTn 압축을 사용하는 경우, 5 개의 압축 타입의 어떤 것인가가 된다. 「압축한 텍스쳐 표면」을 참조할것.

텍스쳐가 읽힌 후, 렌더러-가 지원 하는 픽셀 포맷을 선택할 필요가 있다. 샘플에서는, 지원 되고 있는 픽셀 포맷이 열거되어 연결 리스트에 저장 된다. 픽셀 포맷을 수집하고 나서,FindBestPixelFormatMatch 함수를 사용해, 가장 적합하는 픽셀 포맷을 리스트로부터 찾는다.

레퍼런스 래스터라이저 등, 일부의 Direct3D 디바이스나 일부의 하드웨어 디바이스에서는, 압축 텍스쳐를 직접 렌더링 할 수 있다. 이것을 직접 지원 하지 않는 렌더러-에서는, 압축 표면을 비압축 표면에 블리트 할 필요가 있다. 함수 BltToUncompressedSurface 는, 이 방법을 나타내고 있다.


D3DFrame 라이브러리

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조한다.

[C++]

설명

D3D 프레임워크(framework)란, Direct3D 직접 모드 샘플을 생성 하기 위해서 사용된 C++ 클래스의 집합이며, Direct3D API 의 일부에서는 없다. 프레임워크(framework)를 생성 및 사용한 것은, Direct3D 샘플의 일관성과 명료성을 유지하기 때문에 있다. 프레임워크(framework) 클래스의 사용에 대해서는, 어플리케이션에 의해, 적절한 경우와 그렇지 않은 경우가 있다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\D3DFrame

실행 가능 파일 :없음.

유저즈 가이드

D3DFrame 는, 스태틱 라이브러리로서 컴파일 한다. 이 라이브러리는, 다른 Direct3D 직접 모드 샘플을 빌드 하기 위해서 사용한다.

프로그래밍 위에의 주의

프레임워크(framework)는, DirectDraw 드라이버, Direct3D 디바이스, 및 각 디바이스로 이용 가능한 디스플레이 모드를 열거하는 클래스로부터 구성된다. 샘플은, 이러한 클래스를 사용해, Direct3D 를 초기화해 실행한다. 또, 이러한 클래스는, 유저 인터페이스를 샘플 전체에 일관해 제공한다. 게다가 프레임워크(framework)에는, 텍스쳐의 로드나 관리를 실행하는 클래스의 집합이 포함된다.

Direct3D 프레임워크(framework)에는, 디버그, Direct3D 오브젝트의 조작, 및 Direct3D 프로그래밍에 공통의 수학적 연산을 실행하기 위한 많은 매크로나 함수도 포함되어 있다.


Dolphin 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

Dolphin 샘플은, 애니메이션 된 모델과 텍스쳐를 사용하는 단순한 3D 어플리케이션이다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\Dolphin

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\Dophin.exe

유저즈 가이드

이용 가능한 커멘드를 조사하려면 , F1 키를 누르는지, 메뉴로부터 선택한다.

프로그래밍 위에의 주의

돌고래를 3 개의 메쉬로서 로드해, 선형 보간 해 최종적인 메쉬를 생성 한다.


EnumTex 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

EnumTex 샘플에서는, 텍스쳐 포맷의 열거 방법중에서, 추천 되는 방법을 나타낸다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\Dolphin

실행 가능 파일 :없음

유저즈 가이드

이 샘플에서는, 눈에 보이는 처리는 실행되지 않기 때문에, SDK 에는 실행 가능 파일은 포함되지 않는다.

프로그래밍 위에의 주의

새로운 텍스쳐 포맷을 사용할 때에, 어플리케이션과의 호환성을 유지할 수 있도록(듯이), 텍스쳐를 정확하게 열거하는 것이 중요하다. 이 샘플 코드에서는, 그 열거 방법을 나타낸다.


EnvCube 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

이 샘플에서는, 큐브 맵핑의 이행 방법을 나타낸다. 큐브 맵핑이란, DirectX 7.0 으로 이행 된 새로운 환경 맵핑 기법이다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\EnvCube

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\EnvCube.exe

유저즈 가이드

이용 가능한 커멘드를 조사하려면 , F1 키를 누르는지, 메뉴로부터 선택한다.

프로그래밍 위에의 주의

큐브 맵과는, 장면을 6 살의 직행 방향으로 렌더링 해 생성 된, 특수한 텍스쳐 표면이다. 큐브 맵은, 종래의 환경 맵핑 이펙트에 사용된다.


Filter 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

Filter 샘플에서는, Direct3D 가 지원 하는 텍스쳐 필터링 기법을 나타낸다. Direct3D 텍스쳐 필터링 기법에 의해, 어플리케이션은 렌더링 된 프리미티브의 외관에, 보다 한층 더 리얼리티를 더할 수가 있다. 상세한 것에 대하여는, 「텍스쳐 필터링」을 참조할것.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\Filter

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\Filter.exe

유저즈 가이드

샘플을 기동 하면, 텍스쳐 첨부의 2 개의 직사각형 프리미티브가 표시된다.

F1 키를 누르면(자) [About] 다이알로그 박스에 표시되는 보통의 커멘드에 가세해, 이 프로그램에는 메인 메뉴가 있다.

[File] 메뉴에서는, 프로그램의 일시정지와 재개, Direct3D 디바이스의 변경, 프로그램의 종료를 선택할 수 있다. 어플리케이션의 일시정지와 재개는, Enter 키를 누르는 것에 의해도 실시할 수 있다.

[Left Pane] 메뉴는, 샘플이 스크린의 좌측에서 3D 프리미티브의 확대 축소를 실시하는데 사용하는, 텍스쳐 필터링 방법을 제어한다. 또, 엣지 anti-aliasing나 비등방성 텍스쳐 필터링의 옵션도 있다. 이러한 옵션의 이펙트를 보려면 , 소프트웨어 레퍼런스 래스터라이저를 유효하게 할 필요가 있다. 레퍼런스 래스터라이저를 유효하게 하려면 , (SDK 루트) \Samples\Multimedia\D3dim\Bin\Enablerefrast.reg 를 실행한다.

[Right Pane] 메뉴에 의해, 샘플이 스크린의 우측에서 프리미티브의 렌더링을 실시할 때, 확대 축소에 사용하는 필터링 방법을 설정할 수 있다.

프로그래밍 위에의 주의

이 샘플은, 최근점샘플링, 선형 필터링 및 비등방성 텍스쳐 필터링을 나타내, 비등방성의 유효화와 무효화의 방법을 나타내고 있다. 게다가 엣지 anti-aliasing를 유효하게 하는 방법도 가리키고 있다.


Fireworks 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

Fireworks 샘플은, 불꽃의 폭발을 시뮬레이트 하는 입자의 시스템을 이행 하고 있다. 입자는, 게임에서, 연기나 불꽃, 폭발등의 이펙트를 내기 위해서(때문에) 자주(잘) 사용된다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\Fireworks

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\Fireworks.exe

유저즈 가이드

이용 가능한 커멘드를 조사하려면 , F1 키를 누르는지, 메뉴로부터 선택한다.

프로그래밍 위에의 주의

불꽃의 폭발은, 입자의 시스템에 의해 시뮬레이트 되고 있다. 입자는, 부분적으로 투명한 구(공)의 텍스쳐 맵을 사용해 렌더링 되고 있다. 입자의 위치와 색은 파라미터화 된 (분)편 정도식에 의해 정해져, 프레임 마다 갱신된다.


Flare 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

Flare 샘플에서는, 알파 블렌딩을 사용해 렌즈 플레어 이펙트를 생성 하는 방법을 나타낸다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\Flare

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\Flare.exe

유저즈 가이드

이용 가능한 커멘드를 조사하려면 , F1 키를 누르는지, 메뉴로부터 선택한다.

프로그래밍 위에의 주의

이 샘플에서는, 렌즈 플레어는 각 플레어의 위치를 결정하는 수학 함수에 의해 시뮬레이트 되고 있다. 플레어는 추가 알파 블렌딩을 사용하는 것으로 렌더링 되어 불꽃의 이펙트를 얻기 위해서(때문에) 애니메이션 된다.


LightMap 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

이 샘플에서는, 복잡한 라이팅 이펙트를 얻기 위한 멀티 텍스쳐링 및 멀티 패스 기법의 사용 방법을 나타낸다. 방안에 흔들리고 움직이는 라이트가 있어, 움직일 때마다 동적으로 벽이나 천정을 비춘다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\LightMap

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\Lightmap.exe

유저즈 가이드

[Options] 메뉴로, 멀티 패스 또는 멀티 텍스쳐 블렌딩을 선택한다. 하드웨어가 지원 하고 있지 않으면, 멀티 텍스쳐 블렌딩은 이용할 수 없다.

그 밖에 이용 가능한 커멘드를 조사하려면 , F1 키를 누르는지, 메뉴로부터 선택한다.

프로그래밍 위에의 주의

이 샘플에 「진정한」라이팅은 존재하지 않고, 모두 라이트 맵으로 행해진다. 라이트 맵은, 실제의 라이팅보다 훨씬 빠르기 때문에, 게임에 활발히 사용되고 있다. 게다가 실제의 라이팅의 경우, 버텍스만으로 계산하기 위해(때문에), 고도의 테셀레이션이 필요하다.


Lights 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

Lights 샘플에서는, 다양한 타입의 Direct3D 의 라이팅의 점등 방법과 이동 방법을 나타낸다. 라이팅은 장면을 비추면서 그 주위를 날아, 몇 초 마다 새로운 라이트 타입에 바뀐다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\Lights

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\Lights.exe

유저즈 가이드

이용 가능한 커멘드를 조사하려면 , F1 키를 누르는지, 메뉴로부터 선택한다.

프로그래밍 위에의 주의

이 샘플은, 이용 가능한 종류의 라이트 각각 대해,라이트 프로퍼티를 셋업 하는 방법을 나타낸다. 또, 프레임 마다 라이트의 위치를 동적으로 결정하는 방법도 가리킨다.


MFCFog 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

MFCFog 샘플에서는, 포그(안개:fog)를 유효하게 한 지형 위를 비행해, 다양한 포그(안개:fog) 파라미터의 이펙트를 확인한다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\MFCFog

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\Mfcfog.exe

유저즈 가이드

파라미터를 변경하려면 , 컨트롤을 사용한다. 파라미터의 상세한 것에 대하여는, 「포그(안개:fog)」를 참조할것. 이펙트는, 풀 스크린 모드로 가장 현저하게 된다.

프로그래밍 위에의 주의

지형을 사용하는 게임에서는, 보통 포그(안개:fog)를 사용해, 멀리 있는 오브젝트의 렌더링을 실시하지 않아도 살도록(듯이) 한다.


MipMap 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

이 샘플에서는, z 축으로 따라 전후에 움직이는 2 개의 벽돌의 벽을 나타낸다. 한편의 벽은 MIP Mapping를 사용해, 한편의 벽은 사용하고 있지 않기 때문에, MIP Mapping의 이점을 늘어놓아 비교할 수가 있다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\MipMap

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\Mipmap.exe

유저즈 가이드

이용 가능한 커멘드를 조사하려면 , F1 키를 누르는지, 메뉴로부터 선택한다.

프로그래밍 위에의 주의

이 샘플은 D3DFrame 의 텍스쳐 코드를 사용하고 있지 않다. 그러나, MIP Mapping 된 텍스쳐의 로드나 구축에 필요한 이행을 모두 가리키고 있다.


MTexture 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

MTexture 샘플에서는, 멀티 텍스쳐링의 사용 방법을 나타낸다. 장면은, 베이스 텍스쳐와 spotlight 텍스쳐를 가지는 복수의 벽이 있는 방으로 구성되어 각각이 다른 편성의 텍스쳐 좌표를 사용하고 있다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\MTexture

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\Mtexture.exe

유저즈 가이드

Press 이용 가능한 커멘드를 조사하려면 , F1 키를 누르는지, 메뉴로부터 선택한다.

프로그래밍 위에의 주의

이 샘플은,IDirect3DDevice7::SetTextureStageState 메소드를 사용한 멀티 텍스쳐 스테이지의 프로그래밍 방법을 나타내고 있다. 이 메소드를 사용해, 수십의 이펙트를 얻을 수 있다. 이 샘플에서는, 그 중의 1 개(살), 흑백 라이트 맵핑을 나타내고 있지만, 이것은 현재, 게임에서 매우 넓게 사용되고 있다.


ScreenSaver 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

ScreenSaver 샘플에서는, Direct3D 스크린 세이버의 생성 방법을 나타낸다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\ScreenSaver

실행 가능 파일 :없음

유저즈 가이드

코드를 컴파일 하면, D3DBend.scr 파일이 출력된다. 이 출력 파일을 더블 클릭 하면, 스크린 세이버가 표시된다. Windows 의 [화면의 프로퍼티] 다이알로그 박스로 이 스크린 세이버를 사용할 수 있도록(듯이) 하려면 , \Windows\System 디렉토리에 카피한다.

프로그래밍 위에의 주의

기동 코드는 Scrnsave.lib 에 있다.

스크린 세이버의 컴파일에 대해서는, 「Platform SDK User Interface Services」의 「Screen Saver Library」를 참조할것.


ShadowVol 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

ShadowVol 샘플에서는, 그림자 볼륨을 이행 하기 위해서 스텐실 버퍼를 생성 및 사용하는 방법을 나타낸다. 그림자 볼륨을 사용하는 것으로, 임의의 형태의 오브젝트의 그림자를, 다른 임의의 형태의 오브젝트에 캐스트 할 수가 있다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\ShadowVol

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Shadowvol.exe

유저즈 가이드

이 샘플은, 스텐실 버퍼를 지원 하는 디바이스에서만 실행할 수 있다.

이용 가능한 커멘드를 조사하려면 , F1 키를 누르는지, 메뉴로부터 선택한다.

프로그래밍 위에의 주의

그림자 볼륨은, 꽤 고도의 기법이다.

그림자 볼륨을 생성 하려면

  1. 그림자 볼륨을 포함 하는 다각형의 면의 집합을 구축한다.
  2. 다음에, 스텐실 버퍼를 사용해, 그림자 볼륨의 전면을 렌더링 한다.
  3. 계속되어, 스텐실 버퍼를 셋업 해, 이면의 렌더링을 실시하지만, 이 때, 스텐실 버퍼로부터 값을 공제한다. 이 후, 스텐실 버퍼에는 캐스트 된 그림자의 마스크가 포함된다.
  4. 스텐실 버퍼를 마스크로서 사용해, 큰 회색 또는 흑의 직사각형을 드로잉(Drawing) 하면, frame buffer는 그림자에 의해 갱신된다.


ShadowVol2 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

ShadowVol2 샘플에서는, 그림자 볼륨을 이행 하기 위해서 스텐실 버퍼의 생성 및 사용 방법을 나타낸다. 그림자 볼륨은, 임의의 복잡한 오브젝트에 그림자를 캐스트 하기 위해서 사용한다. 이것은,ShadowVol 샘플의 확장판이다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\ShadowVol2

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\Shadowvol2.exe

유저즈 가이드

이 샘플은, 스텐실 버퍼를 지원 하는 디바이스에서만 실행된다.

이용 가능한 커멘드를 조사하려면 , F1 키를 누르는지, 메뉴로부터 선택한다.

[Shadow Modes] 메뉴에서는, 다음의 옵션을 사용할 수 있다.

  • [Draw Shadows] : 그림자의 렌더링을 유효하게 하려면 , 이 옵션을 체크한다.
  • [Show Shadow Volumes] : 그림자 대신에, 그림자를 계산하기 위한 그림자 볼륨을 드로잉(Drawing) 한다.
  • [Draw Shadow Volume Caps] : 이것을 온으로 하면(자), 그림자 볼륨의 마지막 표면이 드로잉(Drawing) 된다.
  • [1 Bit Stencil Mode] : 1 비트의 스텐실 버퍼만을 사용하는, 다른 알고리즘을 사용한다. 이 때, 그림자가 겹치지 않게 한다. 디바이스가 1 비트의 스텐실만을 지원 하는 경우, 이 모드를 오프로 하는 것은 할 수 없다.
  • [Z Order Shadow Vols] : 1 비트 모드에 대해서는, 그림자 볼륨은 전부터 뒤로 렌더링 할 필요가 있다. 그 때문에, 이 옵션이 체크되어 있지 않으면 렌더링이 부정확하게 되는 일이 있다.

프로그래밍 위에의 주의

그림자 볼륨은, 임의의 비평면 표면에 그림자를 캐스트 하는 기법이다. 이 이펙트는, 광원과 그림자를 캐스트 하는 오브젝트에 관해서 그림자 볼륨을 구축하는 것으로 얻을 수 있다. 이 샘플에서는, 광원은 평면상의 점의 주위를 회전하는 디렉셔널 라이트이다. 그림자 볼륨은, 그림자를 캐스트 하는 오브젝트의 버텍스를 라이트에 대해 수직인 평면상에 캐스트 해 계산한다. 평면에 있어서의 이러한 점의 2D 철폐포를 찾아내 그 2D 폐포를 빛의 방향으로 밀어 내 3D 의 그림자 볼륨을 형성한다. 그림자 볼륨은, 그림자에 들어가는 모든 지오메트리를 커버하는 정도까지 먼 곳까지 늘어날 필요가 있다. 이 특별한 그림자 볼륨의 계산을 실시하려면 , 그림자를 캐스트 하는 오브젝트가 볼록한 모양 오브젝트가 아니면 안된다.

렌더링은 다음과 같이 실시한다.

  1. 보통으로 지오메트리의 렌더링을 실시한다.
  2. z 버퍼 또는 색버퍼에 기입하는 일 없이 그림자 볼륨의 렌더링을 실시한다.

    여기에서는 알파 블렌딩을 사용해, 색버퍼에의 쓰기를 피하고 있다. 그림자 볼륨이 표시되는 장소는 모두, 스텐실 버퍼에 마크 한다.

  3. 다음에, 카르오다를 역전해, 그림자 볼륨의 이면을 렌더링 한다. 이번은, 스텐실 버퍼의, 커버된 픽셀의 마크를 모두 해제한다.

    이러한 픽셀은 z 테스트를 패스하고 있어, 따라, 그림자 볼륨의 배후에서 보인다. 즉, 그림자가 되지 않는다. 마크 된 채로 남아 있는 픽셀은, 그림자 볼륨의 전면 경계와 이면 경계의 안쪽에 있다. 즉, 그림자가 된다.

  4. 이러한 픽셀은, 뷰포트를 커버하는 큰 검은 직사각형에 블렌드 되어 그림자를 생성한다.


Spheremap 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

이 샘플은, 3D 오브젝트를 로드해, 구(공) 맵을 사용해 렌더링 한다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\Spheremap

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\Spheremap.exe

유저즈 가이드

이용 가능한 커멘드를 조사하려면 , F1 키를 누르는지, 메뉴로부터 선택한다.

프로그래밍 위에의 주의

구(공) 맵 자체는, 특별한, 미리 구축된 텍스쳐 맵으로, 환경의 180 번 뷰를 포함한다. 프레임의 렌더링을 실시하기 전에, 오브젝트의 법선을 사용해, 오브젝트의 각 버텍스의 텍스쳐 좌표를 계산한다. 렌더링 하면, 오브젝트가 환경을 반사하고 있는 것처럼 보인다.


StencilDepth 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

StencilDepth 샘플에서는, 스텐실 버퍼를 사용해 장면의 깊이 구조를 시각화하는 방법을 나타낸다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\StencilDepth

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\StencilDepth.exe

유저즈 가이드

이용 가능한 커멘드를 조사하려면 F1 키를 누르는지, 메뉴로부터 선택한다.


StencilMirror 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

StencilMirror 샘플에서는, 스텐실 버퍼를 사용해, 장면내에서 임의의 형태의 평면 밀러를 이행 하는 방법을 나타낸다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\StencilMirror

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\StencilMirror.exe

유저즈 가이드

이용 가능한 커멘드를 조사하려면 , F1 키를 누르는지, 메뉴로부터 선택한다.


VBuffer 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

이 샘플에서는, 버텍스 버퍼의 사용 방법을 나타낸다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\VBuffer

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\VBuffer.exe

유저즈 가이드

이용 가능한 커멘드를 조사하려면 , F1 키를 누르는지, 메뉴로부터 선택한다.

프로그래밍 위에의 주의

버텍스 버퍼가 도입되기 전은, 지오메트리의 렌더링을 실시하는데,DrawPrimitive 함수에 건네주는 버텍스의 배열을 사용하고 있었다. 버텍스 버퍼는 편리한 것은 않지만, 개별적으로 생성, 락, 필, 락 해제를 실시하고 나서, 새로운 DrawPrimitiveVB 함수로 렌더링을 실시할 필요가 있다.


VideoTex 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

VideoTex 샘플에서는, 텍스쳐 맵으로서 . avi 파일을 사용하는 방법을 나타낸다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\VideoTex

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\Videotex.exe

유저즈 가이드

일반적인 커멘드의 리스트를 조사하려면 , F1 키를 누르는지, 메뉴로부터 선택한다.

프로그래밍 위에의 주의

이 프로그램은, 각면에 맵핑 된다 . avi 텍스쳐를 가지는 입방체를 드로잉(Drawing) 한다. 텍스쳐의 표면은, DDSCAPS2_HINTDYNAMIC 플래그를 사용해야 한다.


WBuffer 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

WBuffer 샘플에서는, w 버퍼링의 사용 방법을 나타낸다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\WBuffer

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\WBuffer.exe

유저즈 가이드

보통의 커멘드 일람을 참조하려면 , F1 키를 누르는지, 메뉴로부터 선택한다. 그 밖에, W (지원 되고 있으면, w 버퍼링), Z (z 버퍼링), 또는 N (버퍼링 없음)를 눌러, 버퍼링의 메카니즘을 변경할 수가 있다. z 버퍼링을 사용할때에 표시되는 아티팩트에 주의 해야 한다.

프로그래밍 위에의 주의

w 버퍼링은, z 버퍼링에 대신하는 깊이 버퍼링으로, z 버퍼링으로 부자연스러운 효과가 생성되는 경우에 사용한다. w 버퍼링은, 깊이 버퍼를 양자화할 때가 뛰어난 기능을 한다.


XFile 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 샘플」을 참조할것.

[C++]

설명

이 샘플에서는,. x 파일을 로드 및 렌더링 하는 방법을 나타낸다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Src\XFile

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\D3dim\Bin\XFile.exe

유저즈 가이드

이 샘플을 실행 하면,[Open File] 다이알로그 박스가 표시된다. D3DIM 샘플 디렉토리의 미디어 폴더에, 몇개의 . x 파일이 있다. 디렉토리내에 같은 이름의 . bmp 파일이 있는 경우, 그 bmp 가 자동적으로 오브젝트의 텍스쳐로서 사용된다.

이용 가능한 커멘드를 조사하려면 , F1 키를 누른다. 또,[File] 메뉴로부터 다른 파일을 로드할 수가 있다.

프로그래밍 위에의 주의

오브젝트를 로드하면(자) 텍스쳐가 상하 거꾸로 표시되는 일이 있지만, 이것은, 오브젝트가 텍스쳐를 로드하는 방법으로 기인한다. Direct3D 의 이전의 버젼에서는, 비트 맵을 상하 거꾸로 로드하고 있었기 때문에, 몇개의 . x 파일에서는, 작자가 좌표를 반대로 해 대처하고 있었다.


Direct3D 직접 모드 Visual Basic 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드 C++ 샘플」을 참조할것.

[Visual Basic]

여기에서는, DirectX® SDK 의 샘플 어플리케이션에 대해 설명한다. 여기서 설명하는 어플리케이션의 주된 목적은, Direct3D® 컴퍼넌트를 직접 모드로 사용하는 방법을 나타내는 것이다. 다음의 샘플 프로그램에 대해 설명한다.

  • Billboard 샘플
  • Fireworks 샘플
  • IMControl 샘플
  • MipMap 샘플
  • PPlane 샘플
  • Tunnel 샘플
  • VBuffer 샘플
  • XFile 샘플

샘플 프로그램의 상당수는, IMControl 커스텀 콘트롤을 공통의 렌더링 캔버스로서 사용한다. 이 컨트롤에서는, F5 키로 디바이스 옵션 다이알로그 박스를 호출한다. 이 다이알로그 박스를 사용해, 실행시에, 드라이버, Direct3D 디바이스, 디스플레이 모드 (풀 스크린만)를 변경할 수 있다.

「Direct3D 직접 모드 Visual Basic 튜토리얼 」을 참조할것.


Billboard 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드 C++ 샘플」을 참조할것.

[Visual Basic]

설명

이 샘플에서는, 빌보딩 기법을 나타낸다. 빌보딩이란, 2D 스프라이트를 3D 에 보이는 방법이다. 이 기법은, 연, 운, 수증기의 궤적, 에너지 blast 등에 사용할 수도 있다. 상세한 것에 대하여는, 「공통의 테크놀러지와 특수 효과」를 참조할것.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\D3dim\Src\Billboard

실효 가능 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\D3dim\Bin\VB_Billboard.exe

유저즈 가이드

디바이스 또는 디스플레이 모드를 변경하려면 , F5 키를 누른다.

프로그래밍 위에의 주의

이 샘플은, 나무가 있는 초원을 표시한다. 나무들은 3D 오브젝트와 같이 보인다. 그러나, 이것들은, 실제로는 2D 텍스쳐 비트 맵으로, 안보이는 직사각형 다각형에 블렌드 되고 있다.

샘플 프로그램을 실행 하면, 시점이 변화한다. 시점이 변화할 때마다, 나무들이 드로잉(Drawing) 되는 빌보드 다각형은 모두 회전해, 뷰아의 분을 향한다. 다음에, 프로그램은, 나무들의 이미지를 빌보드 다각형에 블렌드 한다. 나무들을 모든 각도로부터 볼 수가 있기 (위해)때문에, 3D 인것 같이 보인다. 다만, 자세하게 조사하면(자), 나무들은 모든 각도로부터 완전히 같게 보이는 것을 알 수 있다. 많은 어플리케이션으로, 유저가 이 작은 결점을 눈치챌 것은 없다.

그림자도, 2D 텍스쳐이다.


Fireworks 샘플

[C++]

이 눈에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드 C++ 샘플」을 참조할것.

[Visual Basic]

설명

이 샘플에서는, 3D 입자를 사용해 불꽃의 폭발을 시뮬레이트 한다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\D3dim\Src\Fireworks

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\D3dim\Bin\VB_Fireworks.exe

유저즈 가이드

디바이스 또는 디스플레이를 변경하려면 , F5 키를 누른다.

프로그래밍 위에의 주의

Fireworks 샘플에서는, Direct3D 직접 모드 텍스쳐와 알파 블렌딩을 사용하는 간단한 입자 시스템을 나타낸다. 각 입자는, 부분적으로 투명한 구슬의 텍스쳐 맵으로서 렌더링 되고 있다.


IMControl 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드 C++ 샘플」을 참조할것.

[Visual Basic]

설명

이 샘플은, 3D 신을 렌더링 하는 어플리케이션으로 사용할 수 있는 컨트롤로, 많은 Visual Basic Direct3D 샘플로 사용되고 있다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\D3dim\Src\Imcontrol

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\D3dim\Bin\Imcontrol.exe

유저즈 가이드

Imcontrol.ocx 를 3D 어플리케이션에 통합하는 방법에 대해서는, 「Billboard 샘플」을 참조할것. 다른 많은 샘플에서도 이 컨트롤을 사용한다.

프로그래밍 위에의 주의

이 컨트롤은, 풀 스크린 및 윈도우 모드로 DirectDraw 와 Direct3D 의 초기화를 처리해, F5 키에 의해 디바이스나 구성을 변경하는 다이알로그 박스를 표시할 수 있도록(듯이) 한다.


MipMap 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드 C++ 샘플」을 참조할것.

[Visual Basic]

설명

MipMap 샘플은, 밉맵 텍스쳐를 나타낸다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\D3dim\Src\Mipmap

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\D3dim\Bin\VB_MipMap.exe

유저즈 가이드

디바이스 또는 디스플레이 모드를 변경하려면 , F5 키를 누른다.

프로그래밍 위에의 주의

이 샘플에서는, 2 조의 다각형을 비교한다. 1 조째에는 단일의 고정 텍스쳐가 적용되어 이제(벌써) 1 조는 일련의 밉맵 텍스쳐를 사용한다.


PPlane 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드 C++ 샘플」을 참조할것.

[Visual Basic]

설명

PPlane 샘플은, 종이 비행기를 평면상으로 애니메이션 한다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\D3dim\Src\PPlane

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\D3dim\Bin\VB_pplanes.exe

유저즈 가이드

디바이스 또는 디스플레이 모드를 변경하려면 , F5 키를 누른다.


Tunnel 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드 C++ 샘플」을 참조할것.

[Visual Basic]

설명

Tunnel 샘플은, 터널내의 항행을 시뮬레이트 한다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\D3dim\Src\Tunnel

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\D3dim\Bin\VB_tunnel.exe

유저즈 가이드

디바이스 또는 디스플레이 모드를 변경하려면 , F5 키를 누른다.


VBuffer 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드 C++ 샘플」을 참조할것.

[Visual Basic]

설명

이 샘플에서는, 버텍스 버퍼의 사용 방법을 나타낸다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\D3dim\Src\VBuffer

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\D3dim\Bin\VB_vertexBuffer.exe

유저즈 가이드

디바이스 또는 디스플레이 모드를 변경하려면 , F5 키를 누른다.

프로그래밍 위에의 주의

버텍스 버퍼가 도입되기 전은, 지오메트리의 렌더링을 실시하는데,DrawPrimitive 호출에 건네주는 버텍스의 배열을 사용하고 있었다. 버텍스 버퍼는 편리하지만, 개별적으로 생성, 락, 필, 락 해제를 실시하고 나서, 새로운 DrawPrimitiveVB 호출로 렌더링을 실시할 필요가 있다.


XFile 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드 C++ 샘플」을 참조할것.

[Visual Basic]

설명

XFile 샘플은 DirectX 포맷에 있는 3D 이미지용의 뷰아이다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\D3dim\Src\XFile

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\D3dim\Bin\VB_XFile.exe

유저즈 가이드

파일을 로드하려면 ,[File] 메뉴로부터 [Open] 를 선택한다. (SDK 루트)\Samples\Multimedia\VBSamples\D3DRM\media 폴더에는 몇개의 샘플 x 파일이 있다. 이미지를 회전하려면 , 윈도우내에서 마우스를 드러그 한다. 이미지를 회전 (스핀)하려면 , 마우스를 드러그 해 놓는지, 커서 키를 누른다. 이미지를 접근하거나 멀리하려면 , 플러스 키와 마이너스 키를 사용한다. 오브젝트의 외관을 변경하려면 ,[Fill Options] 메뉴와 [Shade Options] 메뉴를 사용한다.

프로그래밍 위에의 주의

파일을 로드하기 위한 주된 기능은, XFileClass 로 제공된다. XFileClass 는, Direct3D 보관 유지 모드를 사용한다.


Direct3DX 유틸리티 라이브러리 [C++]

Direct3DX 유틸리티 라이브러리는, DirectX® 의 3 차원 (3D) 그래픽 컴퍼넌트의 일부이다. Direct3DX 유틸리티 라이브러리에 관한 정보에 대해, 이하의 주제로 나누어 설명한다.

  • Direct3DX 유틸리티 라이브러리에 도착해
  • Direct3DX 유틸리티 라이브러리를 사용하는 이유
  • Direct3DX 유틸리티 라이브러리 아키텍쳐
  • Direct3DX 유틸리티 라이브러리의 요점
  • Direct3DX 유틸리티 라이브러리 레퍼런스
  • Direct3DX 유틸리티 라이브러리 샘플


Direct3DX 유틸리티 라이브러리에 도착해

Direct3DX 유틸리티 라이브러리의 어플리케이션 프로그래밍 인터페이스 (API)는, COM 를 기본으로 하고 있어, DirectX 7.0 의 Direct3D® 컴퍼넌트와 DirectDraw® 컴퍼넌트의 최상정도에 있는 헬퍼-층이다. 이것은, 어플리케이션이 정적으로 링크 가능한 헤더 파일 세트와 라이브러리 (d3dx.lib 또는 d3dxd.lib)로서 설계되고 있다.

어플리케이션으로 Direct3DX 유틸리티 라이브러리에 의해 제공되는 기능을 이용하려면 , d3dx.lib 를 링크할 필요가 있다. 그러나, 디버그 어플리케이션의 경우는, 라이브러리의 디버그 버젼 d3dxd.lib 를 링크 하면이야 있고. 이 debug 버젼은, 파라미터나 데이터 구조체의 유효성을 검사해, 디버그 에러 메세지를 출력한다. 에러가 발생 하면, 디버그 출력은 문제점에 도착해보다 상세한 설명을 제공한다. 디버그 라이브러리의 실행 속도는 소매 버젼의 라이브러리 (d3dx.lib)보다 늦지만, 어플리케이션을 디버그 하려면 매우 편리하다.

Direct3DX 유틸리티 라이브러리는, 3D 그래픽 개발자의 태스크 중(안)에서 공통되는 것을 간이화 한 헬퍼-함수를 제공하고 있다. 이 유틸리티 라이브러리는 Direct3D 직접 모드에 부속되어 있으므로, 이것을 사용하려면 Direct3D 직접 모드의 주요 부분을 이해하고 있는 것이 필요하다.

유틸리티 라이브러리는, Direct3D 직접 모드를 신속하고 유효하게 사용하고 싶은 개발자를 위해서(때문에) 설계되었다. 지루한 태스크를 일부 없애, 쇼트 컷의 툴 킷을 제공하는 것으로, 개발자가 어플리케이션이나 게임의 개발 그 자체에 곧바로 집중할 수 있도록(듯이) 하고 있다.

Direct3DX 유틸리티 라이브러리는, 디바이스 설정의 열거, 디바이스의 셋업, 풀 스크린 모드와 윈도우 모드 공통의 실행, 사이즈 변경 처리의 실행, 벡터나 행렬의 연산의 계산, 및 이미지 파일 로드 처리나 텍스쳐 생성 처리의 간이화의 헬퍼-기능을 제공하고 있다. 또, 간단한 형상, 스프라이트, 큐브 맵을 드로잉(Drawing)하기 위한 함수도 제공하고 있다. 다만, Direct3DX 는 신 계층을 제공하고 있지 않기도 하고, 또는 X 파일을 지원 하고 있지 않다.

유틸리티 라이브러리에서는, 적어도 유저의 시스템에 DirectX 7.0 이 인스톨 되고 있는 것이 필요하다. Direct3DX 유틸리티 라이브러리는, 복수의 모니터 설정을 지원 하고 있다. 다만, Direct3DX 오브젝트는 multi-thread에 대해서는 보증되어 있지 않다. multi-thread화 어플리케이션은, Direct3DX 오브젝트에 액세스 하려면 , 그 자체의 락과 동기 프리미티브를 추가할 필요가 있다.

D3DX_DEFAULT 는 사전에 정의된 값이며, Direct3DX 어플리케이션 프로그래밍 인터페이스 (API)의 파라미터, 또는 열거 함수나 핸들인 멤버 함수의 파라미터로서 사용할 수 있다. 레퍼런스의 마디로, D3DX_DEFAULT 를 사용할 수 있는 장소나, 각 상황에서의 해석 방법에 대해 가리킨다.

D3DX_DEFAULT_FLOAT 는 D3DX_DEFAULT 를 닮아 있지만, 이것은 부동 소수점 파라미터로 사용한다.


Direct3DX 유틸리티 라이브러리를 사용하는 이유

3D 렌더링의 퍼포먼스를 자주(잘) 하기 위해서 Direct3D 직접 모드를 사용하는 경우, Direct3DX 유틸리티 라이브러리를 사용하면 즉석에서 거기에 착수할 수가 있다. 개발자가, 그 태스크 중(안)에서도 퍼포먼스 관계나 어플리케이션 특유의 태스크에 집중하고 싶을 때, 유틸리티 라이브러리를 이용하면 생산성이 향상한다. Direct3DX 유틸리티 라이브러리를 사용하면, 다음의 태스크가 간이화 된다.

  • DirectDraw 오브젝트와 Direct3D 디바이스의 셋업.
  • 간단한 지오메트리 도형의 드로잉(Drawing).
  • 텍스쳐에 대한 하드웨어의 독립성의 실현.
  • 복수 표면 포맷의 컬러 변환의 제공.
  • 텍스쳐 파일 (BMP, TGA, DDS)의 로드.
  • 환경 맵용의 큐브 맵 텍스쳐의 생성.
  • 스프라이트 기능 (회전, 알파, 스케일링, 일그러짐)의 지원.
  • 공통의 3D 산술 연산의 실행.

그 때문에, Direct3D 직접 모드를 기본으로 한 태스크 엔진이 있는 경우에, 몇개의 헬퍼-기능을 추가해야 할 때, Direct3DX 유틸리티 라이브러리가 실용적인 선택사항이 된다.

일반적으로, 유틸리티 라이브러리의 각 컴퍼넌트는 재이용 가능, 또 호환 가능한 것 같게 설계되고 있다. 예를 들어, Direct3DX 유틸리티 라이브러리에서 생성 된 오브젝트 뿐만이 아니라, 임의의 Direct3DDevice 오브젝트나 DirectDrawSurface 오브젝트에서도 스프라이트를 사용할 수 있다. 똑같이, Direct3DX 유틸리티 라이브러리에 의해 제공되고 있는 그 외의 기능을 사용하지 않아도, 산술 함수나 형상 생성 어플리케이션 프로그래밍 인터페이스 (API)를 사용할 수 있다.

마지막으로, Direct3D 이외의 그래픽 API 를 기본으로 한 어플리케이션이나 게임을 포팅 하는 경우는, Direct3DX 유틸리티 라이브러리에서 제공되고 있는 기능을 사용하면보다 간단하게 이행 할 수 있다.


Direct3DX 유틸리티 라이브러리 아키텍쳐

여기에서는, Direct3DX 유틸리티 라이브러리의 구조체에 대해 고도의 정보를 제공한다. 설명하는 주제는 다음과 같다.

  • Direct3DX 유틸리티 라이브러리 아키텍쳐의 개요
  • Direct3DX 유틸리티 라이브러리의 인터페이스와 오브젝트 타입


Direct3DX 유틸리티 라이브러리 아키텍쳐의 개요

Direct3DX 유틸리티 라이브러리는, DirectX 7.0 의 Direct3D 컴퍼넌트와 DirectDraw 컴퍼넌트의 최상정도에 있는 헬퍼-층이다. 이것은, 초기화, 텍스쳐 맵, 스프라이트등의 기능으로 구성되어 있어 대부분은 각각 서로 독립하고 있다.

유틸리티 라이브러리의 기능을 잇는 어플리케이션 프로그래밍 인터페이스 (API)는, 초기화 함수의 D3DXInitialize 함수와 D3DXUninitialize 함수 뿐이다.

차도에, Direct3DX 유틸리티 라이브러리와 Direct3D 나 DirectDraw 와의 관계를 나타낸다.

주 : D3DXInitialize 는, Direct3DX 유틸리티 라이브러리 API 를 사용하기 전에 호출할 필요가 있다. 또, 어플리케이션을 종료하기 전에 D3DXUninitialize 를 호출해, Direct3DX 에 의해 할당할 수 있었던 리소스를 릴리즈 할 필요가 있다.


Direct3DX 유틸리티 라이브러리의 인터페이스와 오브젝트 타입

Direct3DX 유틸리티 라이브러리는, 다음의 COM 인터페이스를 정의하고 있다.

ID3DXContext | 상태 설정, 텍스쳐 생성, 표시 갱신으로 사용되는 루트 인터페이스.
ID3DXMatrixStack | 신 계층의 이행시에 사용되는 헬퍼-인터페이스.
ID3DXSimpleShape | 드로잉(Drawing) 프리미티브 베이스의 렌더링으로 사용되는 버텍스 버퍼 인터페이스.

Direct3DX 유틸리티 라이브러리에서 가장 기본이 되는 오브젝트는, D3DXDevice 오브젝트이다. 이 오브젝트는, (D3DXContext 오브젝트나 D3DXMatrixStack 오브젝트와 달리) 생성 하지 못하고, 인터페이스도 없다. 이것은, 다만 시스템으로 사용 가능한 Direct3DX 디바이스 리스트에의 인덱스로서 참조되는 것만으로 있다. D3DXDevice 오브젝트는, 렌더링 하는 드라이버와 그 드라이버의 능력을 나타내고 있다.

상세한 것에 대하여는, 「Direct3DX 디바이스」를 참조할것.

ID3DXContext 인터페이스는, D3DXContext 오브젝트를 나타내고 있다. 각 D3DXDevice 오브젝트에 복수의 D3DXContext 오브젝트를 생성 할 수 있다.

D3DXDevice 오브젝트는, 다음의 오브젝트를 캡슐화한다.

  • DirectDraw 오브젝트
  • Direct3D 오브젝트
  • Direct3DDevice 오브젝트
  • 렌더링에 필요한 클립퍼나 표면등이 다양한 Direct3D 오브젝트와 DirectDraw 오브젝트.

D3DXContext 오브젝트를 생성 하면, 게임이나 어플리케이션의 전의 오브젝트가 모두 생성 된다. 이러한 캡슐화된 오브젝트를 각각 이행 하는 인터페이스에의 포인터를 문맥 오브젝트로부터 취득하려면 , 다음의 메소드를 호출한다.

  • ID3DXContext::GetDD
  • ID3DXContext::GetD3D
  • ID3DXContext::GetD3DDevice

D3DXContext 오브젝트는, 특정의 D3DXDevice 오브젝트의 렌더링 문맥으로서 볼 수가 있다.

ID3DXMatrixStack 인터페이스는, D3DXMatrixStack 오브젝트를 나타내고 있다. D3DXMatrixStack 는, 변환 계층을 조작할 수 있도록(듯이) 행렬 스택을 이행 하는 행렬 스택 오브젝트이다. ID3DXMatrixStack 인터페이스는, 이 오브젝트를 완전하게 정의하고 있다.

ID3DXSimpleShape 인터페이스는, 형상 오브젝트의 모두로 사용할 수 있다.

  • D3DXBox
  • D3DXCylinder
  • D3DXPolygon
  • D3DXSphere
  • D3DXTeapot
  • D3DXTorus

Direct3DX 에 의해 제공되고 있는 형상 오브젝트에 대해서는, 다음의 주제를 참조할것.

  • 형상 드로잉(Drawing) 함수
  • 간단한 지오메트리 도형

형상 오브젝트에는, 형상을 정의하는 형상 데이터 (버텍스나 인덱스의 정보)가 저장 되고 있다. ID3DXSimpleShape 인터페이스를 사용하는 것으로, 형상을 드로잉(Drawing) 하거나 형상 오브젝트로부터 버텍스나 인덱스의 정보를 직접 취득할 수가 있다.


Direct3DX 유틸리티 라이브러리의 요점

Direct3DX 유틸리티 라이브러리는, 오브젝트를 생성, 캡슐화, 조작하는 어플리케이션 프로그래밍 인터페이스 (API) 요소에 의해 구성되어 있다.

여기에서는, Direct3DX 유틸리티 라이브러리의 MYRIAD 컴퍼넌트에 대한 기술 정보를 나타낸다. 설명하는 주제는 다음과 같다.

  • Direct3DX 및 Direct3D
  • Direct3DX 문맥
  • Direct3DX 디바이스
  • Direct3DX 행렬 스택
  • 하드웨어 액셀러레이트 레벨
  • 스프라이트의 지원
  • 텍스쳐 맵의 지원
  • 간단한 지오메트리 도형
  • 3D 산술의 지원

일반적으로, Direct3DX 유틸리티 라이브러리를 구성하는 헬퍼-컴퍼넌트 (스프라이트의 지원, 텍스쳐 맵의 지원, 간단한 지오메트리 도형, 및 3D 산술의 지원)는, 서로 독립하고 있다. 이것에 의해, 특정의 서브 컴퍼넌트의 커스텀 버젼을 이행 하지 않아도, 필요한 기능만을 간단하게 이용할 수 있다.


Direct3DX 및 Direct3D

Direct3DX 인터페이스와 기저의 Direct3D 인터페이스에는, 밀접한 관계가 있다.

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

  • Direct3DX 를 사용해 Direct3D 와 DirectDraw 를 초기화한다
  • Direct3DX 를 사용해 Direct3D 와 DirectDraw 에 액세스 한다

DirectDraw 와 Direct3D 간의 밀접한 관계의 배경에 대해서는, 「Direct3D 와 DirectDraw 」를 참조할것.


Direct3DX 를 사용해 Direct3D 와 DirectDraw 를 초기화한다

Direct3DX 유틸리티 라이브러리에서는, Direct3D 와 DirectDraw 를 초기화할 수 있다.

Direct3D 는, COM 오브젝트와 COM 인터페이스에 의해 이행 된다. Direct3D 인터페이스는, 디스플레이 디바이스를 나타내는 DirectDraw 오브젝트에의 인터페이스이다. 어플리케이션의 DirectDraw 오브젝트와 Direct3DDevice 오브젝트는, 문맥 오브젝트를 생성 하는 것으로 Direct3DX 에 의해 1 스텝에서 생성 된다.

    if(FAILED(hr = D3DXCreateContextEx(D3DX_DEFAULT, 0, g_hwnd, NULL, D3DX_DEFAULT, 0,
        D3DX_DEFAULT, 0, 1, D3DX_DEFAULT, D3DX_DEFAULT, D3DX_DEFAULT, &g_pd3dx)))
    {
        return hr;
    }

샘플 코드가 가리키도록(듯이),D3DXCreateContextEx 함수는 ID3DXContext 인터페이스에의 포인터의 주소를 돌려준다. 다만,D3DXCreateContext 함수도 ID3DXContext 인터페이스에의 포인터의 주소를 돌려준다. D3DXCreateContext 함수와 D3DXCreateContextEx 함수의 차이에 대해서는, 레퍼런스 페이지를 참조할것.

문맥이나, 문맥에 의한 Direct3D 오브젝트나 DirectDraw 오브젝트의 랩핑 방법에 대해서는, 「Direct3DX 문맥」을 참조할것.

Direct3DX 에서는, 그 밖에도 편리해, 또 시간을 절약할 수 있는 초기화 기능을 제공하고 있다. 이 방법에서는, 시스템내의 다양한 디바이스의 능력이 열거된다. 디바이스나 Direct3DX 에 고유의 디바이스 열거에 대해서는, 「Direct3DX 디바이스」를 참조할것.


Direct3DX 를 사용해 Direct3D 와 DirectDraw 에 액세스 한다

문맥 오브젝트를 취득하면, 캡슐화된 오브젝트에 액세스 할 수 있다.

IDirect3DDevice7 인터페이스에의 포인터를 취득하려면 ,ID3DXContext::GetD3DDevice 메소드를 사용한다.

    m_pd3dDevice = g_pd3dx->GetD3DDevice();
    if (m_pd3dDevice == NULL)
        return E_FAIL;

IDirect3D7 인터페이스에의 포인터를 취득하려면 ,ID3DXContext::GetD3D 메소드를 사용한다.

    m_pd3d = g_pd3dx->GetD3D();
    if (m_pd3d == NULL)
        return E_FAIL;

IDirectDraw7 인터페이스에의 포인터를 취득하려면 ,ID3DXContext::GetDD 메소드를 사용한다.

    m_pdd = g_pd3dx->GetDD();
    if (m_pdd == NULL)
        return E_FAIL;

이와 같이 취득한 인터페이스는, 어플리케이션으로 사용할 수 있다. 예를 들어, 다음의 코드에서는 취득한 IDirect3DDevice7 인터페이스에의 포인터 m_pd3dDevice 를 사용해, 디저링, 스펙큐러 이펙트, 라이팅, z 버퍼 사용을 유효하게 하고 있다.

    hr = m_pd3dDevice->SetRenderState(D3DRENDERSTATE_DITHERENABLE, TRUE);

    hr = m_pd3dDevice->SetRenderState(D3DRENDERSTATE_SPECULARENABLE, TRUE);

    hr = m_pd3dDevice->SetRenderState(D3DRENDERSTATE_LIGHTING, TRUE);

    hr = m_pd3dDevice->SetRenderState(D3DRENDERSTATE_ZENABLE, TRUE);


Direct3DX 문맥

Direct3DX 문맥 오브젝트와 그 사용법에 대해서는, 다음의 주제를 참조할것.

  • Direct3DX 문맥 오브젝트란?
  • Direct3DX 를 사용해 표면을 클리어 한다
  • Direct3DX 를 사용해 장면을 갱신한다


Direct3DX 문맥 오브젝트란?

Direct3DX 문맥 오브젝트는, 디스플레이 디바이스로 렌더링 할 경우에 필요한 다양한 Direct3D 오브젝트나 DirectDraw 오브젝트를 모두 캡슐화한 COM 오브젝트이다. 이것은, 다음의 메소드의 어느쪽이든을 사용해 생성 한다.

  • D3DXCreateContext
  • D3DXCreateContextEx

문맥 오브젝트를 생성 하면, Direct3D 와 DirectDraw 를 초기화하기 위해서 DirectX 어플리케이션으로 필요한 태스크가 줄어든다. 문맥 오브젝트를 한 번 생성 하면, Direct3DDevice 오브젝트나 DirectDrawSurface 오브젝트등이 다양한 Direct3D 오브젝트나 DirectDraw 오브젝트를 이 문맥 오브젝트로부터 간접적으로 취득할 수 있다.

문맥 오브젝트에서는, 캡슐화 버퍼의 플립핑 (블리트)도 가능하고,ID3DXContext::UpdateFrame 메소드로부터의 멀티 버퍼 렌더링을 지원 하고 있다.

ID3DXContext::DrawDebugText 메소드나 ID3DXContext::Resize 메소드도, DirectX 어플리케이션에 공통의 태스크를 간이화 한다.

또,ID3DXContext 인터페이스는 다양한 렌더링 관련 버퍼를 클리어 하는 메소드를 제공하고 있다. 특정의 메소드의 상세한 것에 대하여는, 「ID3DXContext 」를 참조할것.


Direct3DX 를 사용해 표면을 클리어 한다

많은 C++ 어플리케이션은, 새로운 각 프레임을 렌더링 하기 전에 깊이 버퍼를 클리어 한다. ID3DXContext::Clear 메소드를 사용하면, Direct3DX 유틸리티 라이브러리에서 깊이 버퍼를 명시적으로 클리어 할 수 있다.

    hr = g_pD3DX->Clear(D3DCLEAR_TARGET|D3DCLEAR_ZBUFFER);
    if (FAILED(hr))
        return hr;

Clear 메소드를 사용하면, 클리어 하는 표면을 지정할 수 있다. 이 코드에서는, 렌더링 타겟과 깊이 버퍼의 양쪽 모두가 클리어 된다.


Direct3DX 를 사용해 장면을 갱신한다

Direct3DX 유틸리티 라이브러리에서는, 페이지 플립핑 또는 블리트 기능의 어느쪽이든을 사용해 장면의 프레임을 갱신한다.

    hr = g_pD3DX->UpdateFrame(D3DX_UPDATE_NOVSYNC);

이 코드에서는,ID3DXContext::UpdateFrame 메소드를 사용해, D3DX_UPDATE_NOVSYNC 플래그를 설정해 프레임을 갱신하고 있다. 그 결과, 이 호출에서는, 드라이버가 풀 스크린 모드로 수직 동기 (vsync)를 기다리지 않으면 플립핑 할 수 없는 경우는 브릿드를 사용하도록(듯이) 지정된다.


Direct3DX 디바이스

Direct3DX 디바이스에 대해, 다음의 주제로 설명한다.

  • Direct3DX 디바이스란?
  • Direct3DX 디바이스의 열거
  • Direct3DX 디바이스의 문의


Direct3DX 디바이스란?

Direct3DX 디바이스는, Direct3D 디바이스에 의해 제공되고 있는 기능에 근거해 확장되고 있다. Direct3DX 유틸리티 라이브러리는, DirectDraw 오브젝트와 Direct3DDevice 오브젝트의 기능을 캡슐화하는 디바이스 구성의 D3DXDevice 오브젝트를 정의해 이행 한다. 이 설계에 의해, 개발자에게는 편의성과 유연성이 제공된다.

예를 들어, 시스템에 1 개의 Direct3D 대응 그래픽 어댑터가 있는 경우, 그 시스템에는 D3DXDevice 오브젝트가 최대로 4 개 있을 가능성이 있다.

  • 프라이머리 디스플레이 디바이스의 DirectDraw + Direct3DRGBDevice
  • 프라이머리 디스플레이 디바이스의 DirectDraw + Direct3DHALDevice
  • 프라이머리 디스플레이 디바이스의 DirectDraw + Direct3DTnLHALDevice (어댑터가 TnL Hal 를 지원 하고 있는 경우)
  • 프라이머리 디스플레이 디바이스의 DirectDraw + Direct3DreferenceDevice

또, 시스템에 3D accelerator card가 있는 경우, 그 시스템에는 D3DXDevice 오브젝트가 최대로 5 개 있을 가능성이 있다.

Direct3DX 는, 복수의 모니터 설정도 지원 하고 있다. 그 때문에, 시스템에 2 개의 그래픽 어댑터가 있는 경우, 그 시스템에는 D3DXDevice 오브젝트가 최대로 8 개 있을 가능성이 있다.

  • 프라이머리 디스플레이 디바이스의 DirectDraw + Direct3DRGBDevice
  • 프라이머리 디스플레이 디바이스의 DirectDraw + Direct3DHALDevice
  • 프라이머리 디스플레이 디바이스의 DirectDraw + Direct3DTnLHALDevice (어댑터가 TnL Hal 를 지원 하고 있는 경우)
  • 프라이머리 디스플레이 디바이스의 DirectDraw + Direct3DReferenceDevice
  • 세컨드리 디스플레이 디바이스의 DirectDraw + Direct3DRGBDevice
  • 세컨드리 디스플레이 디바이스의 DirectDraw + Direct3DRGBDevice
  • 세컨드리 디스플레이 디바이스의 DirectDraw + Direct3DTnLHALDevice (어댑터가 TnL Hal 를 지원 하고 있는 경우)
  • 세컨드리 디스플레이 디바이스의 DirectDraw + Direct3DReferenceDevice

Direct3D 디바이스의 일반 정보에 대해서는, 「Direct3D 디바이스」를 참조할것.


Direct3DX 디바이스의 열거

특정의 디스플레이 디바이스를 구성해 있는 컴퍼넌트나, 시스템의 디바이스를 열거하기 위해서 Direct3DX 유틸리티 라이브러리에 의해 제공되고 있는 기능에 대해 자세하게 설명한다.

Direct3D 어플리케이션이 Direct3DX 유틸리티 라이브러리를 사용하기 위한 그래픽 설정 (디스플레이 디바이스)은, 다음의 컴퍼넌트에 의해 구성되어 있다.

  • 디스플레이 모니터
  • 2D 그래픽 디바이스
  • 3D 그래픽 디바이스

이러한 컴퍼넌트가 있으면, 광범위의 디스플레이 옵션을 특정의 시스템으로 사용할 수 있다. 예를 들어, 어느 시스템으로 복수의 모니터를 사용할 수 있다. 2D 그래픽 디바이스는, 비디오 액셀러레이트를 사용하는 일도, 사용하지 않는 것도 가능하다. 3D 그래픽 디바이스는 필요한 수만큼 RAMP, RGB, REFERENCE, HW, 또는 TL HW 디바이스를 사용할 수 있다.

디바이스 타입의 상세한 것에 대하여는, Direct3D 직접 모드의 문서의 「Direct3D 디바이스의 종류」를 참조할것.

대부분의 경우, 디스플레이 옵션의 편성이 모두 시스템으로 지원 되는 것은 아니다. 일반적으로, 3D 카드는 특정의 모니터에 접속된다. 또, 2D 엔진의 에뮬레이션을 선택 하면, 3D 엔진의 하드웨어를 선택할 수 없게 된다. 이러한 경합을 해결해, 유효한 하드웨어 설정을 판정하려면 , 어플리케이션으로 시스템의 디바이스를 열거할 필요가 있다.

예로서 시스템 위에의 DirectDraw 디바이스의 수를 판정해, DirectDraw 디바이스 마다 그 최상정도 하드웨어 액셀러레이트를 선택하는 코드를 나타낸다. 결과적으로, 선택한 디바이스에 대응하는 디바이스 리스트에의 인덱스 리스트가 돌려주어진다.

    dwNumDevices = D3DXGetDeviceCount();

    hr = D3DXGetDeviceDescription( 0, &pDeviceList[0] );

    GUID guidLastUniqueDeviceId = pDeviceList[0]. ddDeviceID;
    cNumDDObjs = 1;
    indexOfChosenD3DXDevices[0] = 0; // start by picking the first device

    for( i = 1; i < dwNumDevices; i++ )
    {
        hr = D3DXGetDeviceDescription( i, &pDeviceList[i] );

        if( pDeviceList[i]. ddDeviceID ! = guidLastUniqueDeviceId )
        {
            guidLastUniqueDeviceId = pDeviceList[i]. ddDeviceID;
            cNumDDObjs++;
            indexOfChosenD3DXDevices[cNumDDObjs-1] = i;
        }
        else
        {
            int currIndex = indexOfChosenD3DXDevices[cNumDDObjs-1];
            if( pDeviceList[i]. hwLevel > pDeviceList[currIndex]. hwLevel )
            {
                indexOfChosenD3DXDevices[cNumDDObjs-1] = i;
            }
        }
    }

이 예에서는,D3DXGetDeviceCount 함수를 사용해 시스템으로 열거 가능한 디바이스의 수를 취득하고 있다. 또,D3DXGetDeviceDescription 함수를 사용해, 열거된 디바이스의 기술을 취득해, 그 인덱스값에 의해 디바이스를 식별하고 있다.

주 : Direct3DX 유틸리티 라이브러리를 사용하는 경우는, 적절한 디폴트값이 Direct3DX 문맥 오브젝트에 짜넣어지므로, 어플리케이션으로부터 디바이스를 열거할 필요는 없다.

D3DXCreateContext 함수와 D3DXCreateContextEx 함수의 양자에게는, 디폴트 디바이스를 생성하기 위한 파라미터가 있다. 그러나, 고도의 게임이나 어플리케이션에서는, 유저가 지금까지 사용한 것이 있는 그래픽을 커스터마이즈 할 수 있도록(듯이), 모든 디바이스를 열거한다.


Direct3DX 디바이스의 문의

Direct3DX 유틸리티 라이브러리 함수를 사용해 디바이스로 실행 가능한 비디오 모드 쿼리와 표면 포맷 쿼리에 대해 설명한다.

다음의 메소드를 사용하면, 특정의 디바이스로 지원 되고 있는 다양한 비디오 모드를 문의할 수가 있다.

  • D3DXGetCurrentVideoMode
  • D3DXGetMaxNumVideoModes
  • D3DXGetVideoMode

다음의 코드는, 어느 디바이스로 지원 되고 있는 비디오 모드를 차례로 참조한다.

    dwNumVidModes = D3DXGetMaxNumVideoModes( D3DX_DEFAULT,
                                             D3DX_GVM_REFRESHRATE );
    D3DX_VIDMODEDESC VidMode;

    for( i = 0; i<dwNumVidModes; i++ )
    {
        hr = D3DXGetVideoMode( D3DX_DEFAULT, D3DX_GVM_REFRESHRATE, i,
                               &VidMode );
    }

이 예에서는, D3DX_GVM_REFRESHRATE 플래그를 사용해, 디스플레이 디바이스에 의해 지정되고 있는 refresh rate를 취득한다.

현재의 비디오 모드의 설정값을 취득하는 경우는, 다음의 코드를 사용한다.

    D3DX_VIDMODEDESC CurrVidMode;
    D3DXGetCurrentVideoMode( D3DX_DEFAULT, &CurrVidMode );

D3DXGetDeviceCaps 함수를 사용하면, Direct3DX 디바이스의 능력을 문의할 수가 있다. D3DXGetDeviceCaps 함수로부터는, DirectDraw 표면의 능력과 함께 Direct3D 디바이스의 능력이 돌려주어진다. 또, 많은 비디오 카드에는 비디오 모드를 기본으로 다양한 능력이 있으므로,D3DXGetDeviceCaps 함수에서는 입력 파라미터로서 D3DX_VIDMODEDESC 구조체를 사용한다.

다음의 코드에서는, 디바이스의 능력을 취득한다.

    DDCAPS DDHELCaps;
    DDCAPS DDHALCaps;
    D3DDEVICEDESC7 D3DCaps;
    hr = D3DXGetDeviceCaps( D3DX_DEFAULT,
                            NULL,
                            &D3DCaps,
                            &DDHALCaps,
                            &DDHELCaps );

또, 다양한 표면 클래스의 Direct3DX 디바이스에 의해 지원 되고 있는 기존의 표면 포맷에 관한 정보를 요구할 수 있다.

  • 기존의 표면 포맷에 대해서는,D3DX_SURFACECLASS 에 의해 열거되는 타입을 참조할것.
  • Direct3DX 에 의해 지원 되고 있는 다양한 표면 포맷에 대해서는,D3DX_SURFACEFORMAT 에 의해 열거되는 타입을 참조할것.

다음의 메소드를 사용하면, Direct3DX 디바이스의 지원 표면 포맷을 문의할 수가 있다.

  • D3DXGetMaxSurfaceFormats
  • D3DXGetSurfaceFormat

다음의 코드는, 어느 디바이스로 지원 되고 있는 표면 포맷을 차례로 참조한다.

    DWORD dwNumSurfaceFormats =
    D3DXGetMaxSurfaceFormats( D3DX_DEFAULT, NULL, D3DX_SC_COLORTEXTURE);

    D3DX_SURFACEFORMAT SurfaceFormat;
    for( i=0; i<dwNumSurfaceFormats; i++ )
    {
        hr = D3DXGetSurfaceFormat( D3DX_DEFAULT, NULL, D3DX_SC_COLORTEXTURE,
                                   i, &SurfaceFormat );
    }

이 예에서는, D3DX_SC_COLORTEXTURE 플래그를 사용해, 색정보가 있어, 또 텍스쳐 맵으로 사용할 수 있는 표면을 모두 지정하고 있다.


Direct3DX 행렬 스택

Direct3DX 유틸리티 라이브러리에서는, COM 오브젝트로부터 행렬 스택을 조작한다.

여기에서는, 다음의 토픽에 대해 설명한다.

  • 행렬 스택이란?
  • 신 계층의 이행


행렬 스택이란?

Direct3DX 유틸리티 라이브러리는,ID3DXMatrixStack 인터페이스를 제공하고 있다. 이것은, 행렬 스택에 대해서 행렬을 푸쉬 하거나 팝하기 위한 기능이다. 행렬 스택을 이행 하면, 변환 계층을 더듬으면서 행렬을 효율적으로 추적할 수 있다.

Direct3DX 유틸리티 라이브러리는, 행렬 스택을 사용해 변환 조작을 행렬로서 보존한다. ID3DXMatrixStack 인터페이스의 다양한 메소드에서는, 현재의 행렬이나, 스택의 맨 위에 있는 행렬을 사용한다. 현재의 행렬을 클리어 하려면 ,ID3DXMatrixStack::LoadIdentity 메소드를 사용한다. 현재의 트랜스 폼 행렬로서 로드하는 특정의 행렬을 명시적으로 지정할 필요가 있는 경우는,ID3DXMatrixStack::LoadMatrix 메소드를 사용한다. 현재의 행렬을 지정한 행렬에 의해 곱셈하려면 ,ID3DXMatrixStack::MultMatrix 메소드 또는 ID3DXMatrixStack::MultMatrixLocal 메소드의 어느쪽이든을 호출한다.

ID3DXMatrixStack::Pop 메소드를 사용하면 전의 트랜스 폼 행렬에 돌아오는 것이 가능하고, 또ID3DXMatrixStack::Push 메소드를 사용하면 트랜스 폼 행렬을 스택에 추가할 수 있다.

행렬 스택의 개별의 행렬은, Direct3DX 유틸리티 라이브러리의 D3DXMATRIX 구조체에 의해 정의된 4 × 4 동차 행렬로서 나타내진다.


신 계층의 이행

행렬 스택을 사용하면, 계층 모델의 구축이 용이하게 되므로, 보다 단순한 일련의 오브젝트로부터 복잡한 오브젝트를 구축할 수 있다.

신 (또는 변환) 계층은, 보통 트리 데이터 구조에 의해 나타내진다. 트리 데이터 구조의 각 노드에, 행렬이 1 개씩 저장 되고 있다. 특정의 행렬은, 노드의 부모로부터 아이에게로의 좌표계에 있어서의 변화를 나타내고 있다. 예를 들어, 인간의 팔을 모델링 하는 경우는, 다음의 계층을 이행 한다.

이 계층에서, Body 행렬은 신체를 월드에 배치한다. UpperArm 행렬에는 어깨의 회전, LowerArm 행렬에는 팔꿈치의 회전, 그리고 Hand 행렬에는 손목의 회전이 저장 된다. 월드에 대한 손의 상대적 위치를 판정하려면 , 다만 Body 로부터 Hand 까지의 행렬을 모두 곱셈하는 것만으로 좋다.

이 계층은, 각 노드에 아이 노드가 1 개씩 밖에 없고, 매우 단순하다. 손을 좀 더 세세하게 모델링 하는 경우는, 5 개의 손가락을 추가한다. 각각의 손가락은, Hand 의 자식으로 계층에 추가할 수 있다.

여기서, 장면을 드로잉(Drawing) 하기 위해서 깊이 우선 순서 (1 살의 패스를 할 수 있는 한 깊은 노드까지 더듬어, 그리고 다른 분기처를 더듬는다)로 팔의 형상 전체를 더듬는 경우는, 부분화된 렌더링의 순서를 실행한다. 예를 들어, 손과 손가락을 렌더링 하려면 , 다음의 패턴을 이행 한다.

  1. 행렬 스택에 Hand 행렬을 푸쉬 한다.
  2. 손을 드로잉(Drawing) 한다.
  3. 행렬 스택에 Finger 1 행렬을 푸쉬 한다.
  4. 제 1 손가락을 드로잉(Drawing) 한다.
  5. Finger 1 행렬을 스택으로부터 팝 한다.
  6. 행렬 스택에 Finger 2 행렬을 푸쉬 한다.
  7. 제 2 손가락을 드로잉(Drawing) 한다.
  8. Finger 2 행렬을 스택으로부터 팝 한다.
  9. 행렬 스택에 Finger 3 행렬을 푸쉬 한다. 이와 같이, 모든 손가락을 렌더링 할 때까지 처리를 계속한다.

손가락의 렌더링이 완료하면(자), Hand 행렬을 스택으로부터 팝 한다.

예로서 이 기본 처리의 코드를 나타낸다. 트리 데이터 구조의 깊이 우선 검색시에 노드가 출현하면(자), 그 행렬을 행렬 스택의 맨 위에 푸쉬 한다.

MatrixStack->Push();
MatrixStack->MultMatrix(pNode->matrix);

노드의 조작이 종료하면(자), 그 행렬을 행렬 스택의 맨 위로부터 팝 한다.

MatrixStack->Pop();

이와 같이, 행렬 스택의 맨 위의 행렬이 항상 현재 노드의 월드 트랜스 폼을 나타내고 있다. 그 때문에, 각 노드를 드로잉(Drawing) 하기 전에, Direct3D 행렬을 설정할 필요가 있다.

pD3DDevice->SetTransform(D3DTRANSFORMSTATE_WORLD, *MatrixStack->GetTop());

Direct3DX 행렬 스택으로 실행 가능한 특정의 메소드의 상세한 것에 대하여는, 「ID3DXMatrixStack 」를 참조할것.


하드웨어 액셀러레이트 레벨

여기에서는, Direct3DX 유틸리티 라이브러리에 도착해 하드웨어 액셀러레이트 레벨의 개념을 소개해, 일반적인 사용법을 몇개인가 설명한다.

  • 하드웨어 액셀러레이트 레벨에 대해
  • 하드웨어 액셀러레이트 레벨의 테스트

하드웨어 액셀러레이트 레벨의 레퍼런스 리스트에 대해서는, 「하드웨어 액셀러레이트 레벨 정수」를 참조할것.


하드웨어 액셀러레이트 레벨에 대해

Direct3DX 하드웨어 액셀러레이트 레벨 정수는, 실제의 디바이스 인덱스가 필요한 경우에 사용 가능한 사전에 정의된 인덱스이다. 예를 들어, 하드웨어 액셀러레이트 레벨 정수는,ID3DXContext::GetDeviceIndex 메소드로 사용할 수 있다. 각 정수는, 하드웨어 액셀러레이트의 다양한 레벨을 나타내고 있다.

하드웨어 액셀러레이트 레벨 정수는, 글로벌인 D3DXGetDeviceDescription 함수에 의해 취득되는 명시적인 디바이스 인덱스 대신에 사용한다.

DirectDraw 프라이머리 디바이스 위에의 Direct3DX 디바이스의 어느 쪽인가에 요구된 하드웨어 액셀러레이트 레벨이 지원 되고 있는 경우는, 그것이 사용된다. 지원되어 있지 않은 경우는, Direct3DX 로 검색해 최초로 일치한 디바이스가 사용된다. 물론, 특정의 시스템으로 하드웨어 액셀러레이트 레벨 정수의 머지않아에 대해서도, 일치한 디바이스가 존재하지 않을 가능성도 있다. 이러한 값을 Direct3DX API 에 건네주어도, 다만 API 로 장해가 발생해, 일치하지 않으면 접수 불가인 것이 보고되는 것만으로 있다.

하드웨어 액셀러레이트 레벨 정수를 디바이스 인덱스로서 사용해도 괜찮은 것은, 하드웨어 액셀러레이트의 특정의 레벨이 어플리케이션에 의해 요구되었을 경우에, 컴퓨터상에 복수의 디바이스가 있어 그 어떤 것을 사용해도 상관없을 때 뿐이다.


하드웨어 액셀러레이트 레벨의 테스트

어플리케이션안에는, 다양한 하드웨어 액셀러레이트 레벨에 대해서 특정의 디바이스를 테스트해야 하는 것도 있다.

DescribeDevice( DWORD index )
{
    D3DX_DEVICEDESC devDesc;

    hr = D3DXGetDeviceDescription( index, &devDesc );

    if (D3DX_HWLEVEL_2D == devDesc.hwLevel)
    {
        // 무엇인가 처리를 실시한다.
    }
    else if (D3DX_HWLEVEL_RASTER == devDesc.hwLevel)
    {
        // 무엇인가 처리를 실시한다.
    }
    else if (D3DX_HWLEVEL_REFERENCE == devDesc.hwLevel)
    {
        // 무엇인가 처리를 실시한다.
    }
    else if (D3DX_HWLEVEL_TL == devDesc.hwLevel)
    {
        // 무엇인가 처리를 실시한다.
    }
    else    // D3DX_DEFAULT == devDesc.hwLevel
        // 무엇인가 처리를 실시한다.

이 코드에서는, 디바이스 인덱스를 사용해, 그 디바이스에 대해 기술한 하드웨어 액셀러레이트 플래그를 검색하고 있다.


스프라이트의 지원

Direct3DX 유틸리티 라이브러리에 의해 제공되고 있는 스프라이트 헬퍼-의 어플리케이션 프로그래밍 인터페이스 (API)를 사용하면, 3D 하드웨어를 사용해 2D 스타일의 스프라이트를 렌더링 할 수 있다. 스프라이트 렌더링은 3D 하드웨어용으로 설계되고 있으므로, 퍼포먼스면으로부터 소프트웨어 에뮬레이션으로 사용하는 것은 추천하지 않는다.

스프라이트는, 그 아래의 배경 이미지를 방해 하는 일 없이 조작 가능한 오브젝트이다. Direct3DX 유틸리티 라이브러리의 용어에서는, 스프라이트는 렌더링 타겟으로 전송 가능한 2D 이미지로서 대략적으로 정의된다.

여기에서는, 스프라이트에서의 조작에 Direct3DX 유틸리티 라이브러리를 사용할때에 어플리케이션으로 실행되는 공통의 태스크에 대해 설명한다.

  • 스프라이트를 드로잉(Drawing)하기 위한 준비
  • 단순한 스프라이트의 드로잉(Drawing)
  • 트랜스 폼 된 스프라이트의 드로잉(Drawing)

Direct3DX 유틸리티 라이브러리에 의해 제공되고 있는 스프라이트 기능의 상세한 것에 대하여는, 「스프라이트 헬퍼-함수」를 참조할것.


스프라이트를 드로잉(Drawing)하기 위한 준비

여기에서는, Direct3DX 유틸리티 라이브러리를 사용해 스프라이트를 드로잉(Drawing) 하기 전에 필요한 준비에 대해, 자세하게 설명한다.

렌더링 타겟으로 스프라이트를 전송 하기 전에, 적절한 메소드를 호출해, 장면을 시작 해, 렌더링 타겟을 클리어 한다.

    hr = m_pd3dDevice->BeginScene();

    hr = m_pd3dx->Clear(D3DCLEAR_TARGET|D3DCLEAR_ZBUFFER);

스프라이트를 렌더링 하기 위해서,D3DXPrepareDeviceForSprite 함수를 호출해 래스터라이저를 초기화한다. 일반적으로, 이 함수는 렌더링 하는 모든 스프라이트에 대해서 한 번 호출하는 것만으로 좋다. 다만, 렌더링 상태가 D3DXDrawSpriteSimple 호출의 범위외에서 변경되는 경우는,D3DXPrepareDeviceForSprite 를 재차 호출할 필요가 있다.

    ::D3DXPrepareDeviceForSprite(m_pd3dDevice);

소스 텍스쳐 위에의 어디에 스프라이트를 표시하는지를 정의하는 RECT 구조체를 셋업 한다.

    RECT srcRect;

스프라이트를 사용하는 경우, 이미지는 픽쳐의 그리드로부터 구성되는 일이 자주 있다. 이 경우, 소스의 RECT 구조체는 프레임 마다 다른 소직사각형이 된다. 예를 들어, 픽쳐의 그리드가 10 열과 6 행으로 한다. x 좌표를 판정하려면 m_currentFrame % 10 (다만,m_currentFrame 는 현재 프레임)을 계산한다. y 좌표를 판정하려면 m_currentFrame / 10 을 계산한다.

    int iX = (m_currentFrame % 10);
    int iY = (m_currentFrame / 10);

각 프레임은 64 픽셀×64 픽셀의 셀에 단락지어진다.

    srcRect.left = iX * 64;
    srcRect.top  = iY * 64;

소스의 RECT 구조체의 각 서브 프레임은, 폭이 64 픽셀로, 높이가 48 픽셀이다.

    srcRect.right  = srcRect.left + 64;
    srcRect.bottom = srcRect.top  + 48;

여기서, 현재 뷰포트를 취득한다.

    D3DVIEWPORT7 viewport;
    hr = m_pd3dDevice->GetViewport(&viewport);

다음에, 이 뷰포트를 RECT 구조체로 변환한다.

    RECT rectViewport;
    rectViewport.left   = viewport.dwX;
    rectViewport.top    = viewport.dwY;
    rectViewport.right  = viewport.dwX + viewport.dwWidth;
    rectViewport.bottom = viewport.dwY + viewport.dwHeight;

비회전 렌더링 타겟을 뷰포트의 중심으로 한다.

    D3DXVECTOR3 pointDest;
    pointDest.x = (float) viewport.dwX + (float) viewport.dwWidth  / 2.0f;
    pointDest.y = (float) viewport.dwY + (float) viewport.dwHeight / 2.0f;

이 시점에서, Direct3DX 유틸리티 라이브러리에 의해 제공되고 있는 스프라이트 드로잉(Drawing) 함수의 어느쪽이든을 호출하면, 스프라이트를 드로잉(Drawing) 할 수 있다.

  • D3DXDrawSpriteSimple
  • D3DXDrawSpriteTransform
  • D3DXDrawSprite3D

스프라이트의 드로잉(Drawing) 방법에 대해서는, 「단순한 스프라이트의 드로잉(Drawing)」 및 「트랜스 폼 된 스프라이트의 드로잉(Drawing)」를 참조할것.

스프라이트를 드로잉(Drawing) 한 후, 적절한 메소드를 호출해 장면을 종료해, 프레임을 갱신하는 것.

    hr = m_pd3dDevice->EndScene();

    hr = m_pd3dx->UpdateFrame(D3DX_DEFAULT);


단순한 스프라이트의 드로잉(Drawing)

단순한 스프라이트를 드로잉(Drawing) 할 경우에 Direct3DX 유틸리티 라이브러리가 어떻게 도움이 되는지를 나타낸다.

다음의 코드는, 단순한 스프라이트를 드로잉(Drawing) 한다.

    hr = ::D3DXDrawSpriteSimple(
            m_ptex,                     // 텍스쳐
            m_pd3dDevice,               // 3D 디바이스
            &pointDest,                 // 목적지의 점 (중심)
            (float) m_dwAlpha/255. 0f,    // 알파
            m_fScaleCurrent,            // 스케일
            m_fRotationCurrent,         // 회전
            NULL,                       // 오프셋(offset)
            &srcRect                    // 소스의 소직사각형
            );

이 코드에서는,D3DXDrawSpriteSimple 함수에 의한 스프라이트의 드로잉(Drawing) 방법을 나타내고 있다. 이 함수에서는, 스케일링, 회전, 알파 블렌딩, 모니터링, 배치의 기능이 지원 되고 있다. 셔링이나 퍼스펙티브등 보다 넓은 범위의 이펙트에 대해서는,D3DXDrawSpriteTransform 함수를 사용하는 것.


트랜스 폼 된 스프라이트의 드로잉(Drawing)

여기에서는, Direct3DX 유틸리티 라이브러리를 사용해, 트랜스 폼 된 스프라이트를 드로잉(Drawing) 하는 방법에 대해 자세하게 설명한다.

다음의 코드에서는, 스케일링에 의해 트랜스 폼 된 스프라이트를 구축해, 드로잉(Drawing) 한다.

    D3DXMATRIX matScale;
    D3DXMatrixScaling(&matScale, m_fScaleCurrent, m_fScaleCurrent, 1);

    D3DXMATRIX matTransform;
    D3DXBuildSpriteTransform(&matTransform, &rectViewport, m_fRotationCurrent);

    D3DXMATRIX mat;
    mat = matScale * matTransform;

    hr = ::D3DXDrawSpriteTransform(
            m_ptex,         // 텍스쳐
            m_pd3dDevice,   // 3D 디바이스
            &mat,           // 행렬
            (BYTE) m_dwAlpha,// 알파
            &srcRect        // 소스의 소직사각형
            );

다음의 코드에서는, 회전, 평행이동, 및 스케일링에 의해 트랜스 폼 된 스프라이트를 구축해, 드로잉(Drawing) 한다.

    D3DXMATRIX matScaleToSize;
    D3DXMatrixScaling(&matScaleToSize, 64, 48, 1);

    D3DXMATRIX matRotate;
    D3DXMatrixRotationZ(&matRotate, m_fRotationCurrent);

    D3DXMATRIX matTranslate;
    D3DXMatrixTranslation(&matTranslate, (float) pointDest.x, (float) pointDest.y, 0);

    D3DXMATRIX matScale;
    D3DXMatrixScaling(&matScale, m_fScaleCurrent, m_fScaleCurrent, 1);

    D3DXMATRIX mat;
    mat = matScaleToSize * matRotate * matScale * matTranslate;

    hr = ::D3DXDrawSpriteTransform(
           m_ptex,         // 텍스쳐
           m_pd3dDevice,   // 3D 디바이스
           &mat,           // 행렬
           (BYTE) m_dwAlpha,// 알파
           &srcRect        // 소스의 소직사각형
           );


텍스쳐 맵의 지원

여기에서는, Direct3DX 유틸리티 라이브러리에 의해 제공되고 있는 텍스쳐 맵의 지원에 대해 설명한다.

  • Direct3DX 텍스쳐의 이해
  • 텍스쳐 파일의 이해
  • 텍스쳐의 생성
  • 텍스쳐의 로드
  • 큐브 맵 텍스쳐의 생성
  • 밉맵의 생성
  • 필터링 옵션의 이해

Direct3DX 유틸리티 라이브러리에 의해 제공되고 있는 텍스쳐 맵 기능의 상세한 것에 대하여는, 「텍스쳐 함수」를 참조할것.


Direct3DX 텍스쳐의 이해

Direct3DX 유틸리티 라이브러리는, 할 수 있는 한 높은 하드웨어로부터의 독립성을 실현하기 위해서(때문에), 광범위의 텍스쳐 맵 기능을 제공하고 있다. Direct3DX 는, 선택된 디바이스의 능력을 자동적으로 검색해, 그 디바이스와 호환성이 있는 텍스쳐를 구축한다.

텍스쳐는, 시스템 위에의 3D 하드웨어로 사용하기 위해서 특별히 생성 된 DirectDrawSurface 오브젝트이다. Direct3DX 유틸리티 라이브러리를 사용해 텍스쳐를 생성 하면, 그 텍스쳐는 하드웨어로 우선 지원 된다.

Direct3DX 유틸리티 라이브러리의 텍스쳐 맵 기능을 사용하면, 다음의 조작이 가능하게 된다.

  • 텍스쳐 포맷의 변환.
  • 큐브 맵 텍스쳐의 생성.
  • 텍스쳐의 생성, 파일로부터의 로드.
  • 텍스쳐의 생성.
  • 밉맵의 생성.
  • 필터링.
  • 표면으로부터의 텍스쳐의 로드.

D3DX_SURFACEFORMAT 표준 텍스쳐 타입의 어느쪽이든으로 텍스쳐를 생성 했을 경우, Direct3DX 유틸리티 라이브러리를 사용하면 그 외 모든 표준 텍스쳐 타입으로 변환할 수 있다. 표준 텍스쳐 타입에는, 16 비트와 32 비트의 ARGB, 풀 세트의 RGB 타입, 몇개의 압축 포맷등이 포함된다.


텍스쳐 파일의 이해

Direct3DX 유틸리티 라이브러리를 사용하면, BMP, DIB, TGA, 및 DDS 의 파일 포맷화등 텍스쳐를 로드할 수 있다. 텍스쳐는 로드 되고 나서, 현재 래스터라이저의 제약에 맞은 사이즈와 포맷에 변환된다. 이와 같이, Direct3DX 유틸리티 라이브러리를 사용하면 텍스쳐를 간단하게 생성, 조작할 수 있다.

텍스쳐 생성 함수로부터 돌려주어지는 IDirectDrawSurface7 인터페이스에의 포인터는,IDirect3DDevice7::SetTexture 메소드로 직접 사용할 수 있다.

이미지의 사이즈를 변경할 필요가 있는 경우, 그 이미지는 바이리니아피르타링에 의해 표면 전체를 가리도록(듯이) 늘려진다.

발생할 가능성이 있는 사이즈 변경 에러를 회피하기 위해서 256×256 (또는 그것 이하)의 평방의 텍스쳐를 2 개 사용하는 것을 추천한다. Direct3DX 가 현재 하드웨어로 조작하기 위해서 특정의 텍스쳐를 변경할 필요가 있을지 어떨지는,D3DXCheckTextureRequirements 함수를 사용하고 판단한다.

사이즈나 포맷의 변경이 필요한 경우, 퍼포먼스가 저하할 가능성이 있다. 광범위의 하드웨어 플랫폼에서 이미지의 품질을 최대한으로 유지하기 위해서(때문에)는, 24 비트의 RGB 또는 32 비트의 ARGB 를 사용한다.


텍스쳐의 생성

Direct3DX 유틸리티 라이브러리를 사용 하면,D3DXCreateTexture 함수에 의해 텍스쳐를 「하늘의」텍스쳐로서 생성 할 수 있다 ( 각 픽셀은 0 값에 의해 초기화된다).

또, BMP, DIB, TGA, 및 DDS 파일 포맷의 로드를 지원 한 D3DXCreateTextureFromFile 함수를 사용하면 1 회의 호출로 텍스쳐를 로드해, 생성 할 수도 있다.

예를 들어, 다음의 호출에서는 비트 맵 파일 (texture.bmp)이 로드 된다.

    IDirectDrawSurface7 *m_ptex;
    m_pd3dDevice = m_pd3dx->GetD3DDevice();

    hr = D3DXCreateTextureFromFile(
            m_pd3dDevice,
            NULL,                   // dwFlags
            NULL,                   // 자동 설정폭
            NULL,                   // 자동 설정 높이
            NULL,                   // 자동 설정 표면 타입
            NULL,                   // Palette 에의 포인터
            &m_ptex,                // 돌려주어지는 텍스쳐에의 포인터
            NULL,                   // 돌려주어지는 밉맵수
            "texture.bmp",          // 텍스쳐의 파일명
            D3DX_FT_DEFAULT);       // 디폴트의 스케일링

다만,D3DXCreateTextureFromFile 함수에 의해 생성 된 표면은, rasterize 디바이스의 요건에 맞추기 위해서(때문에) 사이즈나 포맷이 변경되고 있다. 결과적으로, 이와 같이 생성 된 표면에서는, 높이, 폭, 밉맵 레벨, 그리고 표면의 픽셀 포맷조차 디바이스 마다 다를 가능성이 있으므로,IDirectDrawSurface7::Lock 를 호출하는 것은 추천하지 않는다.

D3DXCreateTexture 함수나 D3DXCreateTextureFromFile 함수에 의해 생성 된 표면에 픽셀을 전송 하면나무는,D3DXLoadTextureFromSurface 함수나 D3DXLoadTextureFromFile 함수를 사용하는 것을 추천한다. 이러한 함수는, 다양한 포맷을 모두 처리해, 적절한 재샘플링 조작을 실행하도록(듯이) 설계되고 있다.


텍스쳐의 로드

D3DXLoadTextureFromSurface 함수와 D3DXLoadTextureFromFile 함수는, 기존의 텍스쳐를 새로운 데이터에 의해 갱신하기 위한 파라미터가 있다. 예를 들어, 다음의 코드는 D3DXLoadTextureFromFile 함수 호출에 의해 텍스쳐를 로드한다.

    hr = D3DXLoadTextureFromFile(
        m_pD3DDev,
        pFace,                      // 로드처
        D3DX_DEFAULT,               // 모든 밉레벨
        pszTex,                     // 로드원
        NULL,                       // 로드원전체
        NULL,                       // 로드처 전체
        D3DX_FT_DEFAULT);

RECT 구조체 파라미터를 사용하는 경우 (예를 들어, 로드처 직사각형의 일부 또는 로드원직사각형의 일부만을 갱신하고 싶은 경우), Direct3DX 유틸리티 라이브러리에 의해 제공되고 있는 시나리오의 헬퍼-기능을 사용하면, 로드원직사각형이나 로드처 직사각형의 사이즈가 래스터라이저의 제약에 의해 변경될 것은 없다.

Direct3DX 는 RECT 구조체를 자동적으로 해석해 임의의 사이즈 변경을 실시하므로, 어플리케이션에서는 전혀 텍스쳐를 사이즈 변경하고 있지 않게 RECT 구조체를 셋업 하면이야 있고. 어플리케이션은, 이 간단한 방법에 의해 Direct3DX 에서의 사이즈 변경 처리를 무시할 수 있다. 다만, Direct3DX 를 사용하지 않고 표면을 생성 하는 경우는,RECT 구조체가 그 표면의 열매 픽셀 사이즈에 대응하고 있지 않으면 안 된다.


큐브 맵 텍스쳐의 생성

큐브 맵 텍스쳐의 생성 처리는, 보통의 텍스쳐의 생성 처리와 닮아 있다. 다만, 보통의 텍스쳐 속성 외에, 큐브 맵의 어느 표면을 생성 하는지를 지정할 수 있다.

다음의 코드에서는,D3DXCreateCubeMapTexture 함수를 사용해 큐브 맵 텍스쳐를 생성 한다.

    DWORD w = 256, h = 256;
    D3DX_SURFACEFORMAT sf = D3DX_SF_A8R8G8B8;

    hr = D3DXCreateCubeMapTexture(
                    m_pD3DDev,
                    0,                              // 플래그
                    DDSCAPS2_CUBEMAP_ALLFACES,      // 표면
                    0,                              // 하늘의 표면의 색
                    &w,                             // 폭
                    &h,                             // 높이
                    &sf,                            // 표면 포맷
                    NULL,                           // 팔레트
                    &m_pEnvTex,                     // 결과의 표면
                    NULL);                          // 밉맵 레벨수

여기서, 큐브 맵의 표면을 로드한다.

    DDSCAPS2 ddsCaps;
    ZeroMemory(&ddsCaps, sizeof(ddsCaps));
    for (i = 0; i < 6; i++)
    {
        DWORD FacesArray[] =
        {
            DDSCAPS2_CUBEMAP_POSITIVEX,
            DDSCAPS2_CUBEMAP_NEGATIVEX,
            DDSCAPS2_CUBEMAP_POSITIVEY,
            DDSCAPS2_CUBEMAP_NEGATIVEY,
            DDSCAPS2_CUBEMAP_POSITIVEZ,
            DDSCAPS2_CUBEMAP_NEGATIVEZ
        };

큐브 맵의 각 표면에 파일 인덱스를 맵핑 한다.

        DWORD FileIndex[] =
        {
            2, 0, 5, 4, 1, 3
        };

다음의 코드를 사용해, 올바른 표면을 검색한다.

        LPDIRECTDRAWSURFACE7 pFace;
        if (i ! = 0)
        {
            ddsCaps.dwCaps2 = FacesArray[i];
            if (FAILED(hr = m_pEnvTex->GetAttachedSurface(&ddsCaps, &pFace)))
                return hr;
        }

마지막으로, 특별한 케이스인 0 표면의 큐브 맵을 보정할 필요가 있다. 0 표면의 큐브 맵은, 최상정도의 환경 맵과 같다.

        else
        {
            pFace = m_pEnvTex;
            pFace->AddRef();
        }

디폴트에서는, 큐브 맵의 6 표면 모든 것이 생성 된다. 또, 하늘의 표면으로 사용하는 색을 지정할 수도 있다. 이것에 의해, 큐브 맵의 표면의 몇개인가가 1 개의 색으로 적절히 나타내질 때는 메모리를 절약할 수 있다. 예를 들어, 큐브 맵 세트를 사용해 고속도로의 조명으로부터 자동차의 보닛에 대한 반사를 시뮬레이트 하는 경우, 필요한 것은 POSITIVE_Y 표면 뿐이다. 나머지의 표면은, 흑색으로 생성 할 수 있다.


밉맵의 생성

디폴트로, Direct3DX 유틸리티 라이브러리에 의해 제공되고 있는 텍스쳐 생성 메소드는, 래스터라이저가 밉맵을 지원 하고 있는 한 텍스쳐의 밉맵을 생성한다. 다만, D3DX_TEXTURE_NOMIPMAP 플래그를 사용하면 밉맵의 생성을 무효로 할 수 있다.

다음의 코드는, D3DX_TEXTURE_NOMIPMAP 플래그를 설정해, 밉맵을 지원 하지 않는 텍스쳐를 생성 한다.

    DWORD flags = D3DX_TEXTURE_NOMIPMAP;
    pFlags = &flags;

    hr = D3DXCreateTexture(
            pd3dDevice,         // 건네받는 d3ddevice
            pFlags,             // 옵션의 로드
            pWidth,             // 폭
            pHeight,            // 높이
            pTmpPixelFormat,    // 목적의 픽셀 포맷
            NULL,               // 팔레트
            &pSurf,             // 돌려주어지는 표면
            pNumMipMaps);       // 밉맵 레벨수

다음의 코드는, 생성 된 텍스쳐에 대해, 밉맵이 지원 되고 있는지 어떤지를 문의한다.

    DDCAPS ddcaps;
    ZeroMemory(&ddcaps, sizeof(ddcaps));
    ddcaps.dwSize = sizeof(ddcaps);

    hr = pDD->GetCaps(&ddcaps, NULL);
    if (SUCCEEDED(hr))
    {
    // 밉맵이 지원 되고 있는지 어떤지를 체크한다.
        if (! (*pFlags & D3DX_TEXTURE_NOMIPMAP))
        {
            if (! (ddcaps.ddsCaps.dwCaps & DDSCAPS_MIPMAP))
            {
                // 밉맵을 무효로 한다.
                *pFlags |= D3DX_TEXTURE_NOMIPMAP;
            }
        }
    }

D3DXLoadTextureFromSurface 함수와 D3DXLoadTextureFromFile 함수를 사용하면, 갱신하고 싶은 특정의 밉맵 레벨을 지정할 수 있다. 밉맵 레벨로서 D3DX_DEFAULT 를 지정 하면, 최상정도의 레벨이 갱신되므로, 그 외의 밉맵 레벨은 거기에 맞추어 자동적으로 갱신된다.

밉맵의 개별의 레벨을 세세하게 갱신 습기차면 안 되는 어플리케이션에서는, 명시적인 밉맵 레벨을 Direct3DX 텍스쳐 로드 메소드에 건네준다. 또,IDirectDrawSurface7::Blt 메소드나 IDirectDrawSurface7::Lock 메소드를 직접 사용해 표면을 수정하는 어플리케이션은, 필요에 따라서 밉맵 레벨을 갱신한다.


필터링 옵션의 이해

Direct3DX 유틸리티 라이브러리는, 바이리니아피르타링 (D3DX_FT_LINEAR)과 포인트 샘플링 필터링 (D3DX_FT_POINT)의 2 종류의 필터링을 지원 하고 있다. 보다 품질의 높은 사이즈 변경이나 밉맵 생성이 필요한 경우는, 바이리니아피르타링 (D3DX_FT_LINEAR)을 선택한다. 보다 고속의 처리가 필요한 경우는, 포인트 샘플링 필터링 (D3DX_FT_POINT)을 선택한다.

주 : 몇개의 특별한 케이스에서는, 내부에 텍스트가 있는 이미지로 희미해지지 않게 하기 위해서, 포인트 샘플링을 사용해 밉맵화를 무효로 하면(자) 좋다.


간단한 지오메트리 도형

형상 드로잉(Drawing) 함수의 어느쪽이든을 사용해 형태를 생성 했을 경우,ID3DXSimpleShape COM 인터페이스에의 포인터 주소가 파라미터로 돌려주어진다. 이 인터페이스를 사용하면, 버텍스 정보 (버텍스 버퍼에 저장)나 인덱스 정보를 취득할 수 있다.

  • ID3DXSimpleShape::GetIndices
  • ID3DXSimpleShape::GetVB

형상을 드로잉(Drawing) 하려면 ,ID3DXSimpleShape 인터페이스로 ID3DXSimpleShape::Draw 메소드를 호출한다.

Direct3DX 유틸리티 라이브러리에 의해 제공되고 있는 3D 형상 드로잉(Drawing) 어플리케이션 프로그래밍 인터페이스 (API)를 사용하면, 다음의 간단한 지오메트리 도형을 드로잉(Drawing) 할 수 있다.

  • 입방체
  • 원기둥(실린더)/원추
  • 원환체
  • N 각형 다각형
  • 구(공)체
  • 티폿(주전자)

형상을 생성 하기 전에, 텍스쳐 좌표의 수를 지정할 수 있다. 그렇다면, Direct3DX 에 의해 버텍스 버퍼에 적절한 영역을 할당할 수 있다.

상세한 것에 대하여는, 「형상 드로잉(Drawing) 함수」를 참조할것.


3D 산술의 지원

Direct3DX 유틸리티 라이브러리의 산술 함수에서는, 3D 그래픽으로 일반적으로 사용되는 산술 연산이 모두 지원 되고 있다. C++ 프로그래머는, 일반적인 3D 데이터 타입에 대해 확장 가능해, 또 유연성이 있는 템플릿 클래스를 사용할 수 있다.

다음의 클래스가 이행 되고 있다.

  • D3DXCOLOR
  • D3DXMATRIX
  • D3DXPLANE
  • D3DXQUATERNION
  • D3DXVECTOR2
  • D3DXVECTOR3
  • D3DXVECTOR4

주 : 이 데이터 타입은, C++ 에서는 클래스이며, C 에서는 구조체이다.

상세한 것에 대하여는, 「산술 함수」 및 「C++ 고유의 기능」을 참조할것.


Direct3DX 유틸리티 라이브러리 레퍼런스

여기에서는, Direct3DX 유틸리티 라이브러리가 제공하는 어플리케이션 프로그래밍 인터페이스 (API) 요소의 레퍼런스 정보를 기술한다. 레퍼런스 정보는, 다음의 카테고리로 분류된다.

  • 인터페이스
  • 함수
  • 매크로
  • 구조체
  • C++ 고유의 기능
  • 열거형
  • 하드웨어 액셀러레이트 레벨 정수
  • 반환값


인터페이스

여기에서는, Direct3DX 유틸리티 라이브러리가 제공하는 COM 인터페이스의 레퍼런스 정보를 기술한다. Direct3DX 에 의해 제시되고 있는 인터페이스는, 다음과 같다.

  • ID3DXContext
  • ID3DXMatrixStack
  • ID3DXSimpleShape


ID3DXContext

어플리케이션은,ID3DXContext 인터페이스의 각 메소드를 사용해, 장면을 렌더링 하기 위해서 필요한 다양한 Direct3D 오브젝트나 DirectDraw 오브젝트를 모두 캡슐화한다. 여기에서는, 이 인터페이스의 메소드의 레퍼런스를 기술한다.

ID3DXContext 인터페이스는,D3DXCreateContext 함수 또는 D3DXCreateContextEx 함수를 호출해 취득한다.

ID3DXContext 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

버퍼 관리 | GetBackBuffer
 | GetBufferSize
 | GetNumBackBuffers
 | GetPrimary
 | GetZBuffer
 | Resize
정보 | GetDD
 | GetD3D
 | GetD3DDevice
그 외 | GetCreationFlags
 | GetDeviceIndex
 | GetNumBits
 | GetRefreshRate
 | UpdateFrame
 | DrawDebugText
표면 관리 | RestoreSurfaces
뷰포트 | Clear
 | SetClearColor
 | SetClearDepth
 | SetClearStencil
윈도우 관리 | GetFocusWindow
 | GetWindow

ID3DXContext 인터페이스는, 모든 COM 인터페이스와 같이,IUnknown 인터페이스의 메소드를 계승하고 있다. IUnknown 인터페이스에서는, 다음의 3 개의 메소드가 지원 되고 있다.

IUnknown | AddRef
 | QueryInterface
 | Release

PD3DXCONTEXT 형은,ID3DXContext 인터페이스에의 포인터로서 정의되고 있다.

typedef struct ID3DXContext *PD3DXCONTEXT;

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


ID3DXContext::Clear

ID3DXContext::Clear 메소드는, 현재 뷰포트의 지정된 표면을 클리어 한다.

HRESULT Clear(
  DWORD ClearFlags
);

파라미터

ClearFlags
클리어 하는 표면을 나타내는 플래그. 이 파라미터는, 다음의 파라미터의 몇개인가를 조합해 지정할 수 있지만, 반드시 1 개(살)은 지정할 필요가 있다.
D3DCLEAR_TARGET
렌더링 타겟을 클리어 한다.
D3DCLEAR_STENCIL
스텐실 버퍼를 클리어 한다.
D3DCLEAR_ZBUFFER
깊이 버퍼를 클리어 한다.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DERR_STENCILBUFFER_NOTPRESENT
D3DERR_VIEWPORTHASNODEVICE
D3DERR_ZBUFFER_NOTPRESENT
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

렌더링 타겟으로 깊이 버퍼가 Attach되어 있지 않은 경우, D3DCLEAR_ZBUFFER 플래그 또는 D3DCLEAR_STENCIL 플래그를 지정 하면, 이 메소드는 실패한다. 같이 깊이 버퍼 포맷에 스텐실 버퍼 정보가 저장되어 있지 않은 경우에 D3DCLEAR_STENCIL 플래그를 지정 하면, 이 메소드는 실패한다.

이 메소드는, 현재 뷰포트에 대해서 클리어를 실시한다. ID3DXContext::SetClearColor 메소드에는 뷰포트를 클리어 해 설정하는 색을,ID3DXContext::SetClearDepth 메소드에는 깊이 버퍼를 클리어 해 설정하는 값을,ID3DXContext::SetClearStencil 메소드에는 스텐실 버퍼를 클리어 해 설정하는 값을 지정한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXContext::SetClearColor ,ID3DXContext::SetClearDepth ,ID3DXContext::SetClearStencil


ID3DXContext::DrawDebugText

ID3DXContext::DrawDebugText 메소드는, NULL 로 끝나는 캐릭터 라인을 렌더링 버퍼에 드로잉(Drawing) 한다.

HRESULT DrawDebugText(
  float topLeftX,
  float topLeftY,
  D3DCOLOR color,
  LPSTR pString
);

파라미터

topLeftX
렌더링 타겟으로 드로잉(Drawing) 하는 캐릭터 라인의 맨 왼쪽 위쪽의 x 좌표.
topLeftY
렌더링 타겟으로 드로잉(Drawing) 하는 캐릭터 라인의 맨 왼쪽 위쪽의 y 좌표.
color
렌더링 타겟으로 드로잉(Drawing) 하는 캐릭터 라인의 색을 지정하는 D3DCOLOR 형.
pString
렌더링 타겟으로 드로잉(Drawing) 하는 NULL 로 끝나는 캐릭터 라인에의 포인터.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DXERR_NULLPOINTER
D3DXERR_FAILEDDRAWTEXT
DDERR_DCALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

주의

이 메소드는, 개발시의 디버그나 정보수집을 위해서(때문에) 제공하고 있다.

이 메소드의 좌표 파라미터나 컬러 (color) 파라미터의 범위는, 각각 0.0~1.0 이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


ID3DXContext::GetBackBuffer

ID3DXContext::GetBackBuffer 메소드는, 문맥 버퍼에 의해 캡슐화된 백 버퍼를 취득한다.

LPDIRECTDRAWSURFACE7 GetBackBuffer(
  DWORD dwWhich
);

파라미터

dwWhich
돌려주어지는 백 버퍼 오브젝트의 인덱스.

반환값

성공하면,IDirectDrawSurface7 인터페이스에의 포인터를 돌려준다.

실패하면, NULL 를 돌려준다.

주의

문맥 오브젝트에 의해 캡슐화된 버퍼에서는 참조 회수가 보관 유지되고 있으므로 주의 해야 한다. 그 때문에, 어플리케이션 종료전이나 사이즈 변경시에, 어플리케이션으로 버퍼를 릴리즈 할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXContext::GetBufferSize ,ID3DXContext::GetNumBackBuffers ,ID3DXContext::Resize


ID3DXContext::GetBufferSize

ID3DXContext::GetBufferSize 메소드는, 문맥 오브젝트에 의해 캡슐화된 현재 버퍼의 사이즈를 돌려준다.

HRESULT GetBufferSize(
  LPDWORD width,
  LPDWORD height
);

파라미터

width
이 메소드가 돌아온 후, 이 파라미터는 버퍼의 폭 (픽셀 단위)이 저장 된 DWORD 값을 포인트 하고 있다.
height
이 메소드가 돌아온 후, 이 파라미터는 버퍼의 높이 (픽셀 단위)가 저장 된 DWORD 값을 포인트 하고 있다.

반환값

S_OK 를 돌려준다.

주의

문맥 오브젝트에 의해 캡슐화된 버퍼에서는 참조 회수가 보관 유지되고 있으므로 주의 해야 한다. 그 때문에, 어플리케이션 종료전이나 사이즈 변경시에, 어플리케이션으로 버퍼를 릴리즈 할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXContext::GetPrimary ,ID3DXContext::Resize


ID3DXContext::GetCreationFlags

ID3DXContext::GetCreationFlags 메소드는, 이 문맥 오브젝트를 생성 할 경우에 사용하는 플래그를 취득한다.

DWORD GetCreationFlags();

파라미터

없음.

반환값

문맥 오브젝트를 생성 할 경우에 사용하는 플래그를 나타내는 DWORD 값을 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXCreateContext ,D3DXCreateContextEx


ID3DXContext::GetD3D

ID3DXContext::GetD3D 메소드는,IDirect3D7 인터페이스에의 포인터를 취득한다.

LPDIRECT3D7 GetD3D();

파라미터

없음.

반환값

성공하면,IDirect3D7 인터페이스에의 포인터를 돌려준다.

실패하면, NULL 를 돌려준다.

주의

어플리케이션은, 이 메소드에 의해 돌려주어진 IDirect3D7 인터페이스를 사용해 Direct3D 함수를 호출한다.

문맥 오브젝트에 의해 캡슐화된 Direct3D 오브젝트에서는 참조 회수가 보관 유지되고 있으므로 주의 해야 한다. 그 때문에, 어플리케이션으로 필요없게 되면(자), 어플리케이션으로 IDirect3D7 인터페이스를 릴리즈 할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


ID3DXContext::GetD3DDevice

ID3DXContext::GetD3DDevice 메소드는,IDirect3DDevice7 인터페이스에의 포인터를 취득한다.

LPDIRECT3DDEVICE7 GetD3DDevice();

파라미터

없음.

반환값

성공하면,IDirect3DDevice7 인터페이스에의 포인터를 돌려준다.

실패하면, NULL 를 돌려준다.

주의

어플리케이션은, 이 메소드에 의해 돌려주어진 IDirect3DDevice7 인터페이스를 사용해 Direct3DDevice 메소드를 호출한다.

문맥 오브젝트에 의해 캡슐화된 Direct3DDevice 오브젝트에서는 참조 회수가 보관 유지되고 있으므로 주의 해야 한다. 그 때문에, 어플리케이션으로 필요없게 되면(자), 어플리케이션으로 IDirect3DDevice7 인터페이스를 릴리즈 할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


ID3DXContext::GetDD

ID3DXContext::GetDD 메소드는,IDirectDraw7 인터페이스에의 포인터를 취득한다.

LPDIRECTDRAW7 GetDD();

파라미터

없음.

반환값

성공하면,IDirectDraw7 인터페이스에의 포인터를 돌려준다.

실패하면, NULL 를 돌려준다.

주의

어플리케이션은, 이 메소드에 의해 돌려주어진 IDirectDraw7 인터페이스를 사용해 DirectDraw 메소드를 호출한다.

문맥 오브젝트에 의해 캡슐화된 DirectDraw 오브젝트에서는 참조 회수가 보관 유지되고 있으므로 주의 해야 한다. 그 때문에, 어플리케이션으로 필요없게 되면(자), 어플리케이션으로 IDirectDraw7 인터페이스를 릴리즈 할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


ID3DXContext::GetDeviceIndex

ID3DXContext::GetDeviceIndex 메소드는, 디바이스의 하드웨어 레벨의 인덱스를 돌려준다.

HRESULT GetDeviceIndex(
  LPDWORD pIndex,
  LPDWORD hwLevel
);

파라미터

pIndex
이 메소드가 돌아온 후, 파라미터는 지정한 디바이스의 인덱스와 일치한 DWORD 값을 포인트 하고 있다.
hwLevel
이 메소드가 돌아온 후, 파라미터는 사전에 정의한 하드웨어 액셀러레이트 레벨 정수의 어느쪽이든일치한 DWORD 값을 포인트 하고 있다. 「주의」를 참조할것.

반환값

S_OK 를 돌려준다.

주의

실제의 디바이스 인덱스가 필요한 경우, 사전에 정의된 하드웨어 액셀러레이트 레벨 정수를 사용할 수 있다. 그것들은, Direct3DX 에 의해 실제의 인덱스값에 변환된다. 정의가 끝난 하드웨어 레벨은, 액셀러레이트의 다양한 레벨에 액세스 할 수 있는 간단하고 편리한 방법이다. 이 정수 리스트에 대해서는, 이하를 참조할것.

D3DX_HWLEVEL_REFERENCE
D3DX_HWLEVEL_2D
D3DX_HWLEVEL_RASTER
D3DX_HWLEVEL_TL
D3DX_DEFAULT

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXContext::GetD3DDevice


ID3DXContext::GetFocusWindow

ID3DXContext::GetFocusWindow 메소드는, 관련지을 수 있었던 포커스 윈도우에의 핸들을 취득한다.

HWND GetFocusWindow();

파라미터

없음.

반환값

관련지을 수 있었던 포커스 윈도우에의 핸들 (HWND)을 돌려준다.

주의

포커스 윈도우란, 현재 키보드 입력을 받아들이고 있는 윈도우이다. 이것은, 항상 액티브 윈도우, 액티브 윈도우의 자손, 또는 NULL 의 언젠가이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXContext::GetWindow


ID3DXContext::GetNumBackBuffers

ID3DXContext::GetNumBackBuffers 메소드는, 문맥 오브젝트에 의해 캡슐화된 백 버퍼의 수를 돌려준다.

DWORD GetNumBackBuffers();

파라미터

없음.

반환값

백 버퍼의 수를 나타내는 DWORD 값을 돌려준다.

주의

문맥 오브젝트에 의해 캡슐화된 버퍼에서는 참조 회수가 보관 유지되고 있으므로 주의 해야 한다. 그 때문에, 어플리케이션 종료전이나 사이즈 변경시에, 어플리케이션으로 버퍼를 릴리즈 할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXContext::GetBackBuffer ,ID3DXContext::Resize


ID3DXContext::GetNumBits

ID3DXContext::GetNumBits 메소드는, 문맥 오브젝트에 의해 캡슐화된 DirectDrawSurface 오브젝트의 픽셀 포맷을 기술한 값을 돌려준다.

HRESULT GetNumBits(
  LPDWORD colorBits,
  LPDWORD depthBits,
  LPDWORD alphaBits,
  LPDWORD stencilBits
);

파라미터

colorBits
현재 디스플레이 모드의 색깊이에의 포인터.
depthBits
z 버퍼의 비트 깊이에의 포인터.
alphaBits
알파 버퍼의 비트 깊이에의 포인터.
stencilBits
스텐실 버퍼의 비트 깊이에의 포인터.

반환값

S_OK 를 돌려준다.

주의

stencilBits 파라미터는, 스텐실 정보의 z 버퍼의 각 픽셀에 의해 확보되는 비트의 수를 지정한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXContext::GetZBuffer


ID3DXContext::GetPrimary

ID3DXContext::GetPrimary 메소드는, 문맥 오브젝트에 의해 캡슐화된 프런트 버퍼를 돌려준다.

LPDIRECTDRAWSURFACE7 GetPrimary();

파라미터

없음.

반환값

성공하면,IDirectDrawSurface7 인터페이스에의 포인터를 돌려준다.

실패하면, NULL 를 돌려준다.

주의

문맥 오브젝트에 의해 캡슐화된 버퍼에서는 참조 회수가 보관 유지되고 있으므로 주의 해야 한다. 그 때문에, 어플리케이션 종료전이나 사이즈 변경시에, 어플리케이션으로 버퍼를 릴리즈 할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXContext::GetBufferSize ,ID3DXContext::Resize


ID3DXContext::GetRefreshRate

ID3DXContext::GetRefreshRate 메소드는, refresh rate를 돌려준다.

DWORD GetRefreshRate();

파라미터

없음.

반환값

현재 디스플레이 모드의 refresh rate를 나타내는 DWORD 값을 돌려준다.

주의

refresh rate의 값이 0 이면, 어댑터 장해를 나타낸다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


ID3DXContext::GetWindow

ID3DXContext::GetWindow 메소드는, 관련지을 수 있었던 윈도우에의 핸들을 취득한다.

HWND GetWindow();

파라미터

없음.

반환값

관련지을 수 있었던 윈도우에의 핸들 (HWND)을 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXContext::GetFocusWindow


ID3DXContext::GetZBuffer

ID3DXContext::GetZBuffer 메소드는, 문맥 오브젝트에 의해 캡슐화된 z 버퍼를 돌려준다.

LPDIRECTDRAWSURFACE7 GetZBuffer();

파라미터

없음.

반환값

IDirectDrawSurface7 인터페이스에의 포인터를 돌려준다.

실패하면, NULL 를 돌려준다.

주의

문맥 오브젝트에 의해 캡슐화된 버퍼에서는 참조 회수가 보관 유지되고 있으므로 주의 해야 한다. 그 때문에, 어플리케이션 종료전이나 사이즈 변경시에, 어플리케이션으로 버퍼를 릴리즈 할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXContext::GetBufferSize ,ID3DXContext::Resize


ID3DXContext::Resize

ID3DXContext::Resize 메소드는, 문맥 오브젝트에 의해 캡슐화된 버퍼의 넓이를 변경한다.

HRESULT Resize(
  DWORD width,
  DWORD height
);

파라미터

width
버퍼의 새로운 폭.
height
버퍼의 새로운 높이.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DXERR_CANNOTRESIZEFULLSCREEN
D3DXERR_INVALIDPARAMETER
DDERR_GENERIC
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDSURFACETYPE
DDERR_NOALPHAHW
DDERR_NOCOOPERATIVELEVELSET
DDERR_NODIRECTDRAWHW
DDERR_NOEMULATION
DDERR_NOEXCLUSIVEMODE
DDERR_NOFLIPHW
DDERR_NOMIPMAPHW
DDERR_NOOVERLAYHW
DDERR_NOPALETTEATTACHED
DDERR_NOPALETTEHW
DDERR_NOT8BITCOLOR
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_UNSUPPORTEDMODE

주의

문맥 오브젝트에 의해 캡슐화된 버퍼에서는 참조 회수가 보관 유지되고 있으므로 주의 해야 한다. 그 때문에, 어플리케이션 종료전이나 사이즈 변경시에, 어플리케이션으로 버퍼를 릴리즈 할 필요가 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXContext::GetBufferSize


ID3DXContext::RestoreSurfaces

ID3DXContext::RestoreSurfaces 메소드는, 데이터가 상실했을 경우에 표면을 restore 한다.

HRESULT RestoreSurfaces();

파라미터

없음.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

DDERR_GENERIC
DDERR_IMPLICITLYCREATED
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_OUTOFMEMORY
DDERR_UNSUPPORTED
DDERR_WRONGMODE

주의

이 메소드는, 프라이머리 (프런트 버퍼) 표면, 백 버퍼 표면, z 버퍼 표면을 restore 한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

IDirectDrawSurface7::Restore


ID3DXContext::SetClearColor

ID3DXContext::SetClearColor 메소드는, 렌더링 타겟의 표면을 클리어 해 설정하는 색을 설정한다.

HRESULT SetClearColor(
  D3DCOLOR color
);

파라미터

color
렌더링 타겟의 표면을 클리어 해 설정하는 값을 나타내는 D3DCOLOR 형. 디폴트값은, 0 이다.

반환값

S_OK 를 돌려준다.

주의

이 메소드로 색을 지정 하면 와, 다음과 같이 D3DRGBA 매크로를 사용할 수 있다.

    hr = m_pD3DX->SetClearColor(D3DRGBA(0.5f, 0.0f, 0.0f, 0));

이 메소드로 렌더링 타겟 표면의 색을 설정한 후,ID3DXContext::Clear 메소드를 호출하면 뷰포트를 이 색에 클리어 할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXContext::Clear ,ID3DXContext::SetClearDepth ,ID3DXContext::SetClearStencil


ID3DXContext::SetClearDepth

ID3DXContext::SetClearDepth 메소드는, 깊이 버퍼 표면을 클리어 해 설정하는 값을 설정한다.

HRESULT SetClearDepth(
  float z
);

파라미터

z
깊이 버퍼에 저장 되는 새로운 z 값. 이 파라미터의 범위는 0.0 이상 1.0 이하이다 (z 베이스 또는 w 베이스의 깊이 버퍼). 값이 0.0 이면 뷰아에의 거리가 가장 근처, 1.0 이면 가장 멀다. 디폴트값은, 1.0f 이다.

반환값

S_OK 를 돌려준다.

주의

이 메소드에 의해 깊이 버퍼에 저장 되는 z 값을 설정한 후,ID3DXContext::Clear 메소드를 호출하면, 깊이 버퍼 표면을 이 값에 클리어 할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXContext::Clear ,ID3DXContext::SetClearColor ,ID3DXContext::SetClearStencil


ID3DXContext::SetClearStencil

ID3DXContext::SetClearStencil 메소드는, 스텐실 버퍼 표면을 클리어 해 설정하는 값을 설정한다.

HRESULT SetClearStencil(
  DWORD dwClearValue
);

파라미터

dwClearValue
각 스텐실 버퍼 엔트리에 저장 하는 DWORD 값. 이 파라미터의 범위는, 0 이상 2n-1 이하이다. 다만,n 는 스텐실 버퍼의 비트 깊이이다. 디폴트값은, 0 이다.

반환값

S_OK 를 돌려준다.

주의

이 메소드에 의해 스텐실값을 설정한 후,ID3DXContext::Clear 메소드를 호출하면, 스텐실 버퍼 표면을 이 값에 클리어 할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXContext::Clear ,ID3DXContext::SetClearColor ,ID3DXContext::SetClearDepth


ID3DXContext::UpdateFrame

ID3DXContext::UpdateFrame 메소드는, 페이지 플립핑 또는 블리트의 어느 쪽인가에보다 프레임을 갱신한다.

HRESULT UpdateFrame(
  DWORD flags
);

파라미터

flags
프레임 갱신 옵션을 지정하는 플래그. 「주의」를 참조할것.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

DDERR_DCALREADYCREATED
DDERR_GENERIC
DDERR_IMPLICITLYCREATED
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_INVALIDSURFACETYPE
DDERR_NOALPHAHW
DDERR_NOBLTHW
DDERR_NOCLIPLIST
DDERR_NODDROPSHW
DDERR_NOEXCLUSIVEMODE
DDERR_NOFLIPHW
DDERR_NOTFLIPPABLE
DDERR_NOMIRRORHW
DDERR_NORASTEROPHW
DDERR_NOROTATIONHW
DDERR_NOSTRETCHHW
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING
DDERR_WRONGMODE

주의

flags 파라미터로 D3DX_UPDATE_NOVSYNC 플래그가 설정되어 있는 경우에, 풀 스크린 모드로 수직 동기 (vsync)를 기다리지 않으면 드라이버로 플립핑 할 수 없을 때, 블리트가 사용된다.

상세한 것에 대하여는,플립핑 표면을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

IDirectDrawSurface7::Blt ,IDirectDrawSurface7::Flip


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

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


ID3DXMatrixStack::GetTop

ID3DXMatrixStack::GetTop 메소드는, 스택의 맨 위에 있는 현재의 행렬을 돌려준다.

D3DXMATRIX* GetTop();

파라미터

없음.

반환값

현재의 행렬을 나타내는 D3DXMATRIX 구조체에의 포인터를 돌려준다.

주의

이 메소드에 의해 돌려주어지는 D3DXMATRIX 포인터는, 그 이후의 스택 조작에서도 유효하다라고는 보증되어 있지 않다.

이 메소드는, 스택의 맨 위로부터 현재의 행렬을 삭제하지 않고, 다만 돌려주는 것만으로 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXMatrixStack::Pop ,ID3DXMatrixStack::Push


ID3DXMatrixStack::LoadIdentity

ID3DXMatrixStack::LoadIdentity 메소드는, 현재의 행렬에 단위행렬을 로드한다.

HRESULT LoadIdentity();

파라미터

없음.

반환값

S_OK 를 돌려준다.

주의

단위행렬은,[1,1][2,2][3,3][4,4] 계수에 1.0 이 설정되어 있는 것 제외해, 모든 계수가 0.0 의 행렬이다. 단위행렬은, 버텍스에 적용되어도 그것들이 변경되지 않는다고 하는 점으로써 특별하다. 단위행렬은, 버텍스값을 변경해 회전, 평행이동, 및 4 × 4 행렬로 표현할 수 있는 그 외의 변환을 실시하는 행렬의 기점으로서 사용된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXMatrixStack::LoadMatrix


ID3DXMatrixStack::LoadMatrix

ID3DXMatrixStack::LoadMatrix 메소드는, 현재의 행렬로 지정된 행렬을 로드한다.

HRESULT LoadMatrix(
  const D3DXMATRIX* pMat
);

파라미터

pMat
현재의 행렬에 로드 되는 D3DXMATRIX 구조체에의 포인터.

반환값

성공하면 S_OK 를 돌려주어, 실패하면 D3DXERR_NULLPOINTER 를 돌려준다.

주의

이 메소드는, 스택에 항목을 추가하는 것이 아니라, 현재의 행렬이 지정된 행렬에 옮겨놓는다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXMatrixStack::LoadIdentity


ID3DXMatrixStack::MultMatrix

ID3DXMatrixStack::MultMatrix 메소드는, 현재의 행렬과 지정된 행렬의 적을 산출한다.

HRESULT MultMatrix(
  const D3DXMATRIX* pMat
);

파라미터

pMat
현재의 행렬에 적산하는 D3DXMATRIX 구조체에의 포인터.

반환값

성공하면 S_OK 를 돌려주어, 실패하면 D3DXERR_NULLPOINTER 를 돌려준다.

주의

이 메소드는, 현재의 행렬로 지정된 행렬을 적산한다 (변환은 현재의 월드 원점을 중심으로서 행해진다).

    m_stack[m_currentPos] = m_stack[m_currentPos] * *pMat;

이 메소드는, 스택에 항목을 추가하는 것이 아니라, 현재의 행렬을, 현재의 행렬과 지정된 행렬의 적산에 옮겨놓는다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXMatrixStack::MultMatrixLocal


ID3DXMatrixStack::MultMatrixLocal

ID3DXMatrixStack::MultMatrixLocal 메소드는, 지정된 행렬과 현재의 행렬의 적을 산출한다.

HRESULT MultMatrixLocal(
  const D3DXMATRIX* pMat
);

파라미터

pMat
현재의 행렬과 적산하는 D3DXMATRIX 구조체에의 포인터.

반환값

성공하면 S_OK 를 돌려주어, 실패하면 D3DXERR_NULLPOINTER 를 돌려준다.

주의

이 메소드는, 지정된 행렬에 현재의 행렬을 적산한다 (변환은 오브젝트의 로컬 원점을 중심으로서 행해진다).

    m_stack[m_currentPos] = *pMat * m_stack[m_currentPos];

이 메소드는, 스택에 항목을 추가하는 것이 아니라, 현재의 행렬을, 지정된 행렬과 현재의 행렬의 적산에 옮겨놓는다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXMatrixStack::MultMatrix


ID3DXMatrixStack::Pop

ID3DXMatrixStack::Pop 메소드는, 스택의 맨 위로부터 현재의 행렬을 삭제한다.

HRESULT Pop();

파라미터

없음.

반환값

S_OK 를 돌려준다.

주의

이 메소드는, 스택의 맨 위로부터 현재의 행렬을 삭제해, 행렬을 스택의 맨 위에 진행해, 스택의 항목 카운트를 1 만 줄인다. 스택의 현재의 항목 카운트가 0 의 경우, 이 메소드는 아무것도 처리를 실시하지 않고 돌아온다. 스택의 현재의 항목 카운트가 1 의 경우, 이 메소드는 스택을 비운다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXMatrixStack::GetTop ,ID3DXMatrixStack::Push


ID3DXMatrixStack::Push

ID3DXMatrixStack::Push 메소드는, 행렬을 스택에 추가한다.

HRESULT Push();

파라미터

없음.

반환값

성공하면 S_OK 를 돌려주어, 실패하면 D3DXERR_NOMEMORY 을 돌려준다.

주의

이 메소드는, 현재의 행렬을 복사해, 스택의 항목 카운트를 1 만 늘린다. 항목이 좀 더 추가되면(자), 스택은 동적으로 확대된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXMatrixStack::GetTop ,ID3DXMatrixStack::Pop


ID3DXMatrixStack::RotateAxis

ID3DXMatrixStack::RotateAxis 메소드는, 현재의 행렬과 산출된 회전 행렬의 적을 산출한다.

HRESULT RotateAxis(
  const D3DXVECTOR3* pV,
  float angle
);

파라미터

pV
축의 각도를 지정하는 D3DXVECTOR3 구조체에의 포인터.
angle
회전 각도 (라디안 단위). 각도는, 회전축으로부터 원점으로 향해 시계회전에 계측 된다.

반환값

성공하면 S_OK 를 돌려주어, 실패하면 D3DXERR_NULLPOINTER 를 돌려준다.

주의

이 메소드는, 현재의 행렬에 산출된 회전 행렬을 적산한다. 이것은, 지정한 축으로 대해 반시계회전으로 지정한 모퉁이만 회전시킨다 (회전은, 현재의 월드 원점을 중심으로서 행해진다).

    D3DXMATRIX tmp;

    D3DXMatrixRotationAxis( &tmp, pV, angle );
    m_stack[m_currentPos] = m_stack[m_currentPos] * tmp;

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXMatrixStack::RotateAxisLocal ,ID3DXMatrixStack::RotateYawPitchRoll ,ID3DXMatrixStack::RotateYawPitchRollLocal


ID3DXMatrixStack::RotateAxisLocal

ID3DXMatrixStack::RotateAxisLocal 메소드는, 산출된 회전 행렬과 현재의 행렬의 적을 산출한다.

HRESULT RotateAxisLocal(
  const D3DXVECTOR3* pV,
  float angle
);

파라미터

pV
축의 각도를 지정하는 D3DXVECTOR3 구조체에의 포인터.
angle
회전 각도 (라디안 단위). 각도는, 회전축으로부터 원점으로 향해 시계회전에 계측 된다.

반환값

성공하면 S_OK 를 돌려주어, 실패하면 D3DXERR_NULLPOINTER 를 돌려준다.

주의

이 메소드는, 산출된 회전 행렬에 현재의 행렬을 적산한다. 이것은, 지정한 축으로 대해 반시계회전으로 지정한 모퉁이만 회전시킨다 (회전은, 오브젝트의 로컬 원점을 중심으로서 행해진다).

    D3DXMATRIX tmp;

    D3DXMatrixRotationAxis( &tmp, pV, angle );
    m_stack[m_currentPos] = tmp * m_stack[m_currentPos];

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXMatrixStack::RotateAxis ,ID3DXMatrixStack::RotateYawPitchRoll ,ID3DXMatrixStack::RotateYawPitchRollLocal


ID3DXMatrixStack::RotateYawPitchRoll

ID3DXMatrixStack::RotateYawPitchRoll 메소드는, 현재의 행렬과 산출된 회전 행렬 (지정된 편흔들림각, 경사각, 및 회전각에 의해 구성된다)의 적을 산출한다.

HRESULT RotateYawPitchRoll(
  float yaw,
  float pitch,
  float roll
);

파라미터

yaw
y 축의 편흔들림각 (라디안 단위).
pitch
x 축의 경사각 (라디안 단위).
roll
z 축의 회전각 (라디안 단위).

반환값

S_OK 를 돌려준다.

주의

이 메소드는, 현재의 행렬에 산출된 회전 행렬을 적산한다. 모든 각도는 반시계회전이며, 회전은 현재의 월드 원점을 중심으로서 행해진다.

    D3DXMATRIX tmp;

    D3DXMatrixRotationYawPitchRoll( &tmp, yaw, pitch, roll );
    m_stack[m_currentPos] = m_stack[m_currentPos] * tmp;

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXMatrixStack::RotateAxis ,ID3DXMatrixStack::RotateAxisLocal ,ID3DXMatrixStack::RotateYawPitchRollLocal


ID3DXMatrixStack::RotateYawPitchRollLocal

ID3DXMatrixStack::RotateYawPitchRollLocal 메소드는, 산출된 회전 행렬 (지정된 편흔들림각, 경사각, 및 회전각으로부터 구성된다)과 현재의 행렬의 적을 산출한다.

HRESULT RotateYawPitchRollLocal(
  float yaw,
  float pitch,
  float roll
);

파라미터

yaw
y 축의 편흔들림각 (라디안 단위).
pitch
x 축의 경사각 (라디안 단위).
roll
z 축의 회전각 (라디안 단위).

반환값

S_OK 를 돌려준다.

주의

이 메소드는, 산출된 회전 행렬에 현재의 행렬을 적산한다. 모든 각도는 반시계회전이며, 회전은 오브젝트의 로컬 원점을 중심으로서 행해진다.

    D3DXMATRIX tmp;

    D3DXMatrixRotationYawPitchRoll( &tmp, yaw, pitch, roll );
    m_stack[m_currentPos] = tmp * m_stack[m_currentPos];

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXMatrixStack::RotateAxis ,ID3DXMatrixStack::RotateAxisLocal ,ID3DXMatrixStack::RotateYawPitchRoll


ID3DXMatrixStack::Scale

ID3DXMatrixStack::Scale 메소드는, 현재의 행렬과 산출된 스케일 행렬 (지정된 점 (x, y, z)으로부터 구성된다)의 적을 산출한다.

HRESULT Scale(
  float x,
  float y,
  float z
);

파라미터

x
x 방향의 스케일링 컴퍼넌트.
y
y 방향의 스케일링 컴퍼넌트.
z
z 방향의 스케일링 컴퍼넌트.

반환값

S_OK 를 돌려준다.

주의

이 메소드는, 현재의 행렬에 산출된 스케일 행렬을 적산한다 (변환은 현재의 월드 원점을 중심으로서 행해진다).

    D3DXMATRIX tmp;

    D3DXMatrixScaling( &tmp, x, y, z );
    m_stack[m_currentPos] = m_stack[m_currentPos] * tmp;

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXMatrixStack::ScaleLocal


ID3DXMatrixStack::ScaleLocal

ID3DXMatrixStack::ScaleLocal 메소드는, 산출된 스케일 행렬 (지정된 점 (x, y, z)으로부터 구성된다)과 현재의 행렬의 적을 산출한다.

HRESULT Scale(
  float x,
  float y,
  float z
);

파라미터

x
x 방향의 스케일링 컴퍼넌트.
y
y 방향의 스케일링 컴퍼넌트.
z
z 방향의 스케일링 컴퍼넌트.

반환값

S_OK 를 돌려준다.

주의

이 메소드는, 산출된 스케일 행렬에 현재의 행렬을 적산한다 (변환은 오브젝트의 로컬 원점을 중심으로서 행해진다).

    D3DXMATRIX tmp;

    D3DXMatrixScaling( &tmp, x, y, z );
    m_stack[m_currentPos] = tmp * m_stack[m_currentPos];

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXMatrixStack::Scale


ID3DXMatrixStack::Translate

The ID3DXMatrixStack::Translate 메소드는, 현재의 행렬과 산출된 평행이동 행렬 (지정된 계수 (x, y, z)에 의해 결정된다)의 적을 산출한다.

HRESULT Translate(
  float x,
  float y,
  float z
);

파라미터

x
x 방향의 평행이동 계수.
y
y 방향의 평행이동 계수.
z
z 방향의 평행이동 계수.

반환값

S_OK 를 돌려준다.

주의

이 메소드는, 현재의 행렬에 산출된 평행이동 행렬을 적산한다 (변환은, 현재의 월드 원점을 중심으로서 행해진다).

    D3DXMATRIX tmp;

    D3DXMatrixTranslation( &tmp, x, y, z );
    m_stack[m_currentPos] = m_stack[m_currentPos] * tmp;

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXMatrixStack::TranslateLocal


ID3DXMatrixStack::TranslateLocal

ID3DXMatrixStack::TranslateLocal 메소드는, 산출된 평행이동 행렬 (지정된 계수 (x, y, z)에 의해 결정된다)와 현재의 행렬의 적을 산출한다.

HRESULT TranslateLocal(
  float x,
  float y,
  float z
);

파라미터

x
x 방향의 평행이동 계수.
y
y 방향의 평행이동 계수.
z
z 방향의 평행이동 계수.

반환값

S_OK 를 돌려준다.

주의

이 메소드는, 산출된 평행이동 행렬에 현재의 행렬을 적산한다 (변환은, 오브젝트의 로컬 원점을 중심으로서 행해진다).

    D3DXMATRIX tmp;

    D3DXMatrixTranslation( &tmp, x, y, z );
    m_stack[m_currentPos] = tmp * m_stack[m_currentPos];

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

ID3DXMatrixStack::Translate


ID3DXSimpleShape

ID3DXSimpleShape 인터페이스는, 다음의 글로벌 함수의 어느 쪽인가에보다 형태를 드로잉(Drawing) 하는 것으로써 취득된다.

  • D3DXCreateBox
  • D3DXCreateCylinder
  • D3DXCreatePolygon
  • D3DXCreateSphere
  • D3DXCreateTeapot
  • D3DXCreateTorus

ID3DXSimpleShape 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

정보 | GetIndices
 | GetVB
렌더링 | Draw

ID3DXSimpleShape 인터페이스는, 모든 COM 인터페이스와 같이,IUnknown 인터페이스의 메소드를 계승하고 있다. IUnknown 인터페이스에서는, 다음의 3 개의 메소드가 지원 되고 있다.

Iunknown | AddRef
 | QueryInterface
 | Release

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxshapes.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


ID3DXSimpleShape::Draw

ID3DXSimpleShape::Draw 메소드는, 형상 오브젝트를 드로잉(Drawing) 할 경우에 사용한다.

HRESULT Draw();

파라미터

없음.

반환값

성공하면, D3D_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DXERR_NULLPOINTER
D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDVERTEXTYPE
D3DERR_VERTEXBUFFERLOCKED
DDERR_INVALIDPARAMS
DDERR_WASSTILLDRAWING

주의

이 함수는, 형상 드로잉(Drawing) 함수의 어느 쪽인가에보다 생성된 버텍스 버퍼를 드로잉(Drawing) 할 경우에 사용한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxshapes.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

IDirect3DDevice7::DrawIndexedPrimitive ,IDirect3DDevice7::DrawPrimitive


ID3DXSimpleShape::GetIndices

ID3DXSimpleShape::GetIndices 메소드는, 형상 오브젝트로부터 인덱스 정보를 취득할 경우에 사용한다.

DWORD GetIndices(
  LPWORD* ppIndices
);

파라미터

ppIndices
메소드가 돌아온 후, 이 파라미터는 인덱스 리스트에의 포인터의 주소를 보관 유지하고 있다.

반환값

인덱스 리스트의 인덱스수를 돌려준다.

주의

IDirect3DDevice7::DrawIndexedPrimitiveVB 메소드에 의해 드로잉(Drawing) 된 형태에게만 인덱스 리스트가 있다. 형태가 IDirect3DDevice7::DrawPrimitiveVB 메소드에 의해 드로잉(Drawing) 되고 있는 경우, 이 메소드는 0 을 돌려주어,ppIndices 에는 NULL 를 설정한다. D3DXCreateBox ,D3DXCreateCylinder ,D3DXCreatePolygon ,D3DXCreateSphere 함수는 인덱스 리스트를 사용하지 않지만,D3DXCreateTeapot 함수와 D3DXCreateTorus 함수는 인덱스 리스트를 사용한다.

인덱스 리스트의 값은, 렌더링 하는 지오메트리 도형을 생성 하는 경우에, 버텍스 리스트에 인덱스를 설정 하면나무 사용한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxshapes.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

IDirect3DDevice7::DrawIndexedPrimitive


ID3DXSimpleShape::GetVB

ID3DXSimpleShape::GetVB 메소드는, 형상 오브젝트로부터 버텍스 정보를 취득할 경우에 사용한다.

LPDIRECT3DVERTEXBUFFER7 GetVB();

파라미터

없음.

반환값

IDirect3DVertexBuffer7 인터페이스에의 포인터를 돌려준다.

주의

이 메소드를 사용 하면 버텍스 버퍼의 참조 회수가 증가하므로, 종료시에 돌려주어진 버텍스 버퍼에 대해서 Release 를 호출하는 것.

형상 드로잉(Drawing) 메소드의 어느쪽이든을 사용해 형태를 드로잉(Drawing) 하면 와, 텍스쳐 좌표의 수를 지정할 수 있다. 지정 하면, Direct3DX 에 의해 버텍스 버퍼에 적절한 영역을 할당할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxshapes.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

버텍스 버퍼


함수

여기에서는, Direct3DX 유틸리티 라이브러리에서 사용되는 함수에의 링크를 나타낸다.

  • 범용 함수
  • 산술 함수
  • 형상 드로잉(Drawing) 함수
  • 스프라이트 헬퍼-함수
  • 텍스쳐 함수


범용 함수

Direct3DX 유틸리티 라이브러리에 의해 제공되고 있는 범용 함수를 사용하면, 디바이스, 비디오 모드, 및 표면 포맷의 문의, Direct3DX 의 셋업이나 슛다운, 문맥의 생성, 표면이나 픽셀 포맷의 생성등이 많은 기본 기능을 실행할 수 있다.

범용 함수는, 이하의 그룹에 정리할 수가 있다.

생성 | D3DXCreateContext
 | D3DXCreateContextEx
디바이스 | D3DXGetDeviceCaps
 | D3DXGetDeviceCount
 | D3DXGetDeviceDescription
초기화 | D3DXInitialize
 | D3DXUninitialize
그 외 | D3DXGetErrorString
모드 | D3DXGetCurrentVideoMode
 | D3DXGetMaxNumVideoModes
 | D3DXGetVideoMode
표면 | D3DXGetMaxSurfaceFormats
 | D3DXGetSurfaceFormat
 | D3DXMakeDDPixelFormat
 | D3DXMakeSurfaceFormat


D3DXCreateContext

D3DXCreateContext 함수는, 지정된 디바이스를 초기화한다.

HRESULT D3DXCreateContext(
  DWORD deviceIndex,
  DWORD flags,
  HWND hwnd,
  DWORD width,
  DWORD height,
  LPD3DXCONTEXT* ppCtx
);

파라미터

deviceIndex
디바이스를 지정하는 인덱스값. 이 파라미터에 D3DX_DEFAULT 를 지정 하면, 프라이머리 표면에 관계가 있는 액셀러레이트 레벨의 최고 레벨에 의해 디바이스가 초기화된다. 지정 가능한 모든 값의 리스트에 대해서는, 「하드웨어 액셀러레이트 레벨 정수」를 참조할것.
flags
유효한 플래그는, D3DX_CONTEXT_FULLSCREEN 와 D3DX_CONTEXT_OFFSCREEN 이다. 이러한 플래그를 양쪽 모두 지정할 수 없다. 플래그를 지정하지 않는 경우, 문맥에 의해 디폴트의 윈도우 모드가 적용된다.
hwnd
디바이스 윈도우. 「주의」를 참조할것.
width
윈도우의 폭 (픽셀 단위) 또는 D3DX_DEFAULT. 「주의」를 참조할것.
height
윈도우의 높이 (픽셀 단위) 또는 D3DX_DEFAULT. 「주의」를 참조할것.
ppCtx
선택한 디바이스로 렌더링 할 경우에 사용하는 문맥 오브젝트에의 포인터의 주소.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INITFAILED
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMEMORY
D3DXERR_NOZBUFFER
D3DXERR_NOZBUFFERAVAILABLE
D3DXERR_NULLPOINTER
DDERR_CANNOTATTACHSURFACE
DDERR_GENERIC
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDSURFACETYPE
DDERR_NOALPHAHW
DDERR_NOCLIPPERATTACHED
DDERR_NOCOOPERATIVELEVELSET
DDERR_NODIRECTDRAWHW
DDERR_NOEMULATION
DDERR_NOEXCLUSIVEMODE
DDERR_NOFLIPHW
DDERR_NOMIPMAPHW
DDERR_NOOVERLAYHW
DDERR_NOPALETTEATTACHED
DDERR_NOPALETTEHW
DDERR_NOT8BITCOLOR
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_SURFACEALREADYATTACHED
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_UNSUPPORTEDMODE
DDERR_WASSTILLDRAWING

주의

어플리케이션이 윈도우 모드로 동작하고 있는 경우, hwnd 는 유효한 윈도우가 아니면 안된다 (NULL 또는 D3DX_DEFAULT 는 지정할 수 없다). 또,width 또는 height 중 한쪽이 D3DX_DEFAULT 의 경우, 양쪽 모두의 값에 hwnd 클라이언트 영역의 넓이의디폴트값이 설정된다.

어플리케이션이 풀 스크린 모드로 동작하고 있는 경우, hwnd 는 유효한 윈도우가 아니면 안된다 (NULL 또는 D3DX_DEFAULT 는 지정할 수 없다). 또,width 또는 height 중 한쪽이 D3DX_DEFAULT 의 경우, 디폴트값으로서 width 에는 640 픽셀이,height 에는 480 픽셀이 설정된다.

어플리케이션이 오프 스크린 모드로 동작하고 있는 경우, hwnd 는 NULL 또는 D3DX_DEFAULT 가 아니면 안된다. width 또는 height 중 한쪽이 D3DX_DEFAULT 의 경우는, 에러가 돌려주어진다.

D3DXCreateContext 함수는, 사용 가능한 Direct3DX 초기화 함수 중(안)에서 가장 간단한 것이다. 파라미터는,D3DXCreateContextEx 함수의 파라미터의 조합 서브 세트와 같이 처리된다. D3DXCreateContext 함수에 없는 D3DXCreateContextEx 파라미터는, D3DX_DEFAULT 로서 처리된다.

메모 D3DXCreateContext 함수로 생성 되는 문맥에서는, 멀티 모니터 시스템이 지원되어 있지 않다. 멀티 모니터의 지원에 대해서는,D3DXCreateContextEx 함수를 참조할것.

모든 함수에 대해,D3DXCreateContext 가 장해 발생시에 안전이라고 생각해서는 안 된다. 지원 되고 있는 디바이스의 능력은, 파라미터값을 선택하기 위한 가이드로서 사용하는 것. 파라미터의 편성안에는, 잘 동작하지 않는 것이 반드시 존재한다.

D3DXCreateContext 함수에 의해 셋업 되는 디폴트 투영 행렬은, pi/2 라디안의 시역 (fov)에서의 왼손 좌표계 퍼스펙티브 투영이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXCreateContextEx


D3DXCreateContextEx

D3DXCreateContextEx 함수는, 지정한 디바이스를 초기화한다. 다만, 이것은 D3DXCreateContext 함수에 의해도 고도의 초기화 함수이다.

HRESULT D3DXCreateContextEx(
  DWORD deviceIndex,
  DWORD flags,
  HWND hwnd,
  HWND hwndFocus,
  DWORD numColorBits,
  DWORD numAlphaBits,
  DWORD numDepthbits,
  DWORD numStencilBits,
  DWORD numBackBuffers,
  DWORD width,
  DWORD height,
  DWORD refreshRate,
  LPD3DXCONTEXT* ppCtx
);

파라미터

deviceIndex
디바이스를 지정하는 인덱스값. 이 파라미터에 D3DX_DEFAULT 를 지정 하면, 프라이머리 표면에 관계가 있는 액셀러레이트 레벨의 최고 레벨에 의해 디바이스가 초기화된다. 지정 가능한 모든 값의 리스트에 대해서는,하드웨어 액셀러레이트 레벨 정수」를 참조할것.
flags
유효한 플래그는, D3DX_CONTEXT_FULLSCREEN 와 D3DX_CONTEXT_OFFSCREEN 이다. 이러한 플래그를 양쪽 모두 지정할 수 없다. 플래그를 지정하지 않는 경우, 문맥에 의해 디폴트의 윈도우 모드가 적용된다.
hwnd
디바이스 윈도우. 「주의」를 참조할것.
hwndFocus
「주의」를 참조할것. 디바이스 윈도우로부터 키보드 메세지를 받아들이는 윈도우. 디바이스 윈도우는, 포커스 윈도우의 자식 윈도우이다. 이 파라미터는, 멀티 모니터 어플리케이션으로 유용하다.
numColorBits
컬러 비트수. 윈도우 모드로 D3DX_DEFAULT 를 지정 하면, 현재 데스크탑의 색깊이가 선택된다. 풀 스크린 모드의 경우, D3DX_DEFAULT 를 선택 하면, 16 비트 컬러가 사용된다.
numAlphaBits
알파 채널에 확보되고 있는 비트수. D3DX_DEFAULT 를 지정 하면, 0 이 선택된다.
numDepthbits
깊이 버퍼에 확보되고 있는 비트수. D3DX_DEFAULT 를 지정 하면, 사용 가능한 깊이 비트수 중(안)에서 가장 높은 값이 선택된다. 「주의」를 참조할것.
numStencilBits
스텐실 버퍼에 확보되고 있는 비트수. D3DX_DEFAULT 를 지정 하면, 사용 가능한 스텐실 비트수 중(안)에서 가장 높은 값이 선택된다. 「주의」를 참조할것.
numBackBuffers
백 버퍼수, 또는 D3DX_DEFAULT. 「주의」를 참조할것.
width
윈도우의 폭 (픽셀 단위), 또는 D3DX_DEFAULT. 「주의」를 참조할것.
height
윈도우의 높이 (픽셀 단위), 또는 D3DX_DEFAULT. 「주의」를 참조할것.
refreshRate
refresh rate. 윈도우 모드와 오프 스크린 모드의 경우, 이 파라미터는 무시된다. D3DX_DEFAULT 는, DirectDraw 에 어플리케이션에 맞은 값을 선택시키는 것을 의미하고 있다.
ppCtx
선택한 디바이스의 렌더링으로 사용하는 문맥 오브젝트에의 포인터의 주소.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INITFAILED
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMEMORY
D3DXERR_NOZBUFFER
D3DXERR_NOZBUFFERAVAILABLE
D3DXERR_NULLPOINTER
DDERR_CANNOTATTACHSURFACE
DDERR_GENERIC
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDSURFACETYPE
DDERR_NOALPHAHW
DDERR_NOCLIPPERATTACHED
DDERR_NOCOOPERATIVELEVELSET
DDERR_NODIRECTDRAWHW
DDERR_NOEMULATION
DDERR_NOEXCLUSIVEMODE
DDERR_NOFLIPHW
DDERR_NOMIPMAPHW
DDERR_NOOVERLAYHW
DDERR_NOPALETTEATTACHED
DDERR_NOPALETTEHW
DDERR_NOT8BITCOLOR
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_SURFACEALREADYATTACHED
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_UNSUPPORTEDMODE
DDERR_WASSTILLDRAWING

주의

어플리케이션이 윈도우 모드로 동작하고 있는 경우, hwnd 는 유효한 윈도우가 아니면 안된다. hwndFocus 파라미터는, NULL 또는 D3DX_DEFAULT 가 아니면 안된다. 또,width 또는 height 파라미터중 한쪽이 D3DX_DEFAULT 의 경우, 양쪽 모두의 값에 hwnd 클라이언트 영역의 넓이의 디폴트값이 설정된다. numBackBuffers 에 D3DX_DEFAULT 를 지정 하면, 1 이 사용된다. 그 때문에 백 버퍼를 1 개 지정할 필요가 있다.

어플리케이션이 풀 스크린 모드로 동작하고 있는 경우, hwnd 또는 hwndFocus 중 한쪽이 유효한 윈도우가 아니면 안된다 (양쪽 모두에 NULL 또는 D3DX_DEFAULT 를 지정할 수 없다). hwnd 가 NULL 또는 D3DX_DEFAULT 의 경우, 디폴트 디바이스 윈도우가 hwndFocus 의 자식 윈도우로서 생성 된다. 또,width 또는 height 중 한쪽이 D3DX_DEFAULT 의 경우, 디폴트값으로서 width 에는 640 픽셀이,height 에는 480 픽셀이 설정된다. numBackBuffers 에 D3DX_DEFAULT 를 지정 하면, 1 이 사용된다. 그 때문에 백 버퍼를 1 개 지정할 필요가 있다.

어플리케이션이 오프 스크린 모드로 동작하고 있는 경우, hwnd 와 hwndFocus 는 NULL 또는 D3DX_DEFAULT 가 아니면 안된다. width 또는 height 중 한쪽이 D3DX_DEFAULT 의 경우는, 에러가 돌려주어진다. numBackBuffers 에 D3DX_DEFAULT 를 지정 하면, 0 이 사용된다. 그 때문에, 추가의 백 버퍼를 지정이 아니다.

numDepthBits 파라미터와 numStencilBits 파라미터가 양쪽 모두 D3DX_DEFAULT 의 경우, Direct3DX 는 우선 사용 가능한 스텐실 비트수의 최고치를 선택한다. 다음에, 선택한 스텐실 비트에 대해, 사용 가능한 깊이 비트수의 최고치를 선택한다. numStencilBits 파라미터 또는 numDepthBits 파라미터의 어느쪽이든만이 D3DX_DEFAULT 의 경우, 그 디폴트 패러미터로 사용 가능한 비트수의 최고치가, 고정 파라미터로 요구된 비트수를 지원 한 포맷화등 선택된다.

모든 함수에 대해,D3DXCreateContextEx 가 장해 발생시에 안전이라고 생각해서는 안 된다. 지원 되고 있는 디바이스의 능력은, 파라미터값을 선택하기 위한 가이드로서 사용하는 것. 파라미터의 편성안에는, 잘 동작하지 않는 것이 반드시 존재한다.

D3DXCreateContextEx 함수에 의해 셋업 되는 디폴트 투영 행렬은, pi/2 라디안의 시역 (fov)에서의 왼손 좌표계 퍼스펙티브 투영이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXCreateContext


D3DXGetCurrentVideoMode

D3DXGetCurrentVideoMode 함수는, 지정된 디바이스의 현재 비디오 모드를 취득한다.

HRESULT D3DXGetCurrentVideoMode(
  DWORD deviceIndex,
  D3DX_VIDMODEDESC* pVidMode
);

파라미터

deviceIndex
디바이스를 지정하는 인덱스값. 이 파라미터에 D3DX_DEFAULT 를 지정 하면, 프라이머리 표면에 관계가 있는 최고의 액셀러레이트 레벨에 근거해 디바이스가 지정된다.
pVidMode
현재 디스플레이 모드의 기술이 돌려주어지는 D3DX_VIDMODEDESC 구조체에의 포인터.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INITFAILED
D3DXERR_INVALIDD3DXDEVICEINDEX
D3DXERR_NULLPOINTER

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXGetMaxNumVideoModes ,D3DXGetVideoMode


D3DXGetDeviceCaps

D3DXGetDeviceCaps 함수는, 디스플레이 모드로 디바이스의 모든 능력을 표시한다.

HRESULT D3DXGetDeviceCaps(
  DWORD deviceIndex,
  D3DX_VIDMODEDESC* pVidMode,
  D3DDEVICEDESC7* pD3DCaps,
  DDCAPS* pDDHALCaps,
  DDCAPS* pDDHELCaps
);

파라미터

deviceIndex
디바이스를 지정하는 인덱스값. 이 파라미터에 D3DX_DEFAULT 를 지정 하면, 프라이머리 표면에 관계가 있는 최고의 액셀러레이트 레벨에 근거해 디바이스가 지정된다.
pVidMode
디스플레이 모드를 기술한 D3DX_VIDMODEDESC 구조체에의 포인터. 이 파라미터가 NULL 의 경우, Direct3DX 는 디바이스의 현재 디스플레이 모드에서의 능력을 돌려준다.
pD3DCaps
선택한 디바이스의 Direct3D 능력을 기술한 D3DDEVICEDESC7 구조체에의 포인터. NULL 를 지정 하면, 이 파라미터는 무시된다.
pDDHALCaps
DirectDraw 하드웨어 추상 계층 (HAL) 능력을 기술한 DDCAPS 구조체에의 포인터. NULL 를 지정 하면, 이 파라미터는 무시된다.
pDDHELCaps
DirectDraw 하드웨어 에뮬레이션 계층 (HEL) 능력을 기술한 DDCAPS 구조체에의 포인터. NULL 를 지정 하면, 이 파라미터는 무시된다.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DXERR_CAPSNOTSUPPORTED
D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_FAILEDGETCAPS
D3DXERR_INITFAILED
D3DXERR_INVALIDD3DXDEVICEINDEX

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXGetDeviceCount ,D3DXGetDeviceDescription


D3DXGetDeviceCount

D3DXGetDeviceCount 함수는, 사용 가능한 Direct3DX 디바이스의 최대수를 돌려준다.

DWORD D3DXGetDeviceCount();

파라미터

없음.

반환값

사용 가능한 Direct3DX 디바이스의 최대수.

주의

에러가 있는 경우, 이 함수는 0 을 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXGetDeviceCaps ,D3DXGetDeviceDescription


D3DXGetDeviceDescription

D3DXGetDeviceDescription 함수는, 지정한 디바이스의 기술을 취득한다.

HRESULT D3DXGetDeviceDescription(
  DWORD deviceIndex,
  D3DX_DEVICEDESC* pd3dxDeviceDesc
);

파라미터

deviceIndex
디바이스를 지정하는 인덱스값. 디바이스의 인덱스는, 0 으로부터 시작된다. 이 파라미터로 D3DX_DEFAULT 를 지정 하면, 프라이머리 표면에 관계가 있는 최고의 액셀러레이트 레벨에 근거해 디바이스가 지정된다.
pd3dxDeviceDesc
지정된 디바이스의 능력이 설정된 D3DX_DEVICEDESC 구조체에의 포인터.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INITFAILED
D3DXERR_INVALIDD3DXDEVICEINDEX
D3DXERR_NULLPOINTER

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXGetDeviceCaps ,D3DXGetDeviceCount


D3DXGetErrorString

D3DXGetErrorString 함수는,HRESULT 가 설정된 에러 캐릭터 라인을 인쇄한다.

void D3DXGetErrorString(
  HRESULT hr,
  DWORD strLength,
  LPSTR pStr
);

파라미터

hr
해독하는 HRESULT 에러 코드.
strLength
건네받는 캐릭터 라인의 길이.
pStr
캐릭터 라인의 출력. 다만, 건네받는 캐릭터 라인은,strLength 파라미터로 지정된 적절한 길이가 아니면 안된다.

반환값

없음.

주의

D3DXGetErrorString 함수는, Win32, DirectX 6.0, 및 Direct3DX 의 에러 메세지를 인쇄한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXGetMaxNumVideoModes

D3DXGetMaxNumVideoModes 함수는, 비디오 모드의 최대수를 돌려준다.

DWORD D3DXGetMaxNumVideoModes(
  DWORD deviceIndex,
  DWORD flags
);

파라미터

deviceIndex
디바이스를 지정하는 인덱스값. 이 파라미터에 D3DX_DEFAULT 를 지정 하면, 프라이머리 표면에 관계가 있는 최고의 액셀러레이트 레벨에 근거해 디바이스가 지정된다.
flags
이 파라미터에 의해 D3DX_GVM_REFRESHRATE 플래그가 설정되지 않는 이상 refresh rate는 무시된다. refresh rate를 무시시키고 싶은 경우, 이 파라미터에 0 을 설정한다.

반환값

성공하면, 비디오 모드의 최대수를 돌려준다.

실패하면, 0 을 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXGetCurrentVideoMode ,D3DXGetVideoMode


D3DXGetMaxSurfaceFormats

D3DXGetMaxSurfaceFormats 함수는, 지정한 비디오 모드로 디바이스에 의해 지원 되고 있는 표면 포맷의 최대수를 돌려준다.

DWORD D3DXGetMaxSurfaceFormats(
  DWORD deviceIndex,
  D3DX_VIDMODEDESC* pDesc,
  DWORD surfClassFlags
);

파라미터

deviceIndex
디바이스를 지정하는 인덱스값. 이 파라미터에 D3DX_DEFAULT 를 지정 하면, 프라이머리 표면에 관계가 있는 최고의 액셀러레이트 레벨에 근거해 디바이스가 지정된다.
pDesc
지원 되고 있는 표면 포맷이 요구되었을 때의 디스플레이 모드를 기술한 D3DX_VIDMODEDESC 구조체에의 포인터. 이 파라미터가 NULL 의 경우, 현재 디스플레이 모드라고 보여진다.
surfClassFlags
지원 된 포맷이 요구되고 있는 표면 클래스를 나타내는 D3DX_SURFACECLASS 열거형의 멤버.

반환값

성공하면, 지정한 비디오 모드로 디바이스에 의해 지원 되고 있는 표면 포맷의 최대수를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INITFAILED
D3DXERR_INVALIDD3DXDEVICEINDEX

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXGetSurfaceFormat


D3DXGetSurfaceFormat

D3DXGetSurfaceFormat 함수는, 이 디바이스로 지원 되고 있는 표면 포맷의 어느쪽이든을 기술한다.

HRESULT D3DXGetSurfaceFormat(
  DWORD deviceIndex,
  D3DX_VIDMODEDESC* pDesc,
  DWORD surfClassFlags,
  DWORD surfaceIndex,
  D3DX_SURFACEFORMAT* pFormat
);

파라미터

deviceIndex
디바이스를 지정하는 인덱스값. 이 파라미터에 D3DX_DEFAULT 를 지정 하면, 프라이머리 표면에 관계가 있는 최고의 액셀러레이트 레벨에 근거해 디바이스가 지정된다.
pDesc
지원 되고 있는 표면 포맷이 요구되었을 때의 디스플레이 모드를 기술한 D3DX_VIDMODEDESC 구조체에의 포인터. 이 파라미터가 NULL 의 경우, 현재 디스플레이 모드라고 보여진다.
surfClassFlags
지원 된 포맷이 요구되고 있는 표면 클래스를 나타내는 D3DX_SURFACECLASS 열거형의 멤버.
surfaceIndex
취득하는 표면 포맷을 나타내는 DWORD 값. 인덱스는, 0 으로 시작된다.
pFormat
D3DX_SURFACEFORMAT 열거형의 멤버 (돌려주어진 표면 포맷)에의 포인터.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INITFAILED
D3DXERR_INVALIDD3DXDEVICEINDEX
D3DXERR_INVALIDPARAMETER
D3DXERR_NULLPOINTER

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXGetMaxSurfaceFormats


D3DXGetVideoMode

D3DXGetVideoMode 함수는, 이 디바이스의 특정의 비디오 모드를 기술한다.

HRESULT D3DXGetVideoMode(
  DWORD deviceIndex,
  DWORD flags,
  DWORD modeIndex,
  D3DX_VIDMODEDESC* pModeList
);

파라미터

deviceIndex
디바이스를 지정하는 인덱스값. 이 파라미터에 D3DX_DEFAULT 를 지정 하면, 프라이머리 표면에 관계가 있는 최고의 액셀러레이트 레벨에 근거해 디바이스가 지정된다.
flags
이 파라미터로 D3DX_GVM_REFRESHRATE 가 설정되어 있지 않은 한, refresh rate는 무시된다. refresh rate를 무시시키고 싶은 경우, 이 파라미터에 0 을 설정한다.
modeIndex
디바이스를 지정하는 DWORD 값. 인덱스는, 0 으로 시작된다.
pModeList
디바이스의 디스플레이 모드의 기술에 의해 돌려주어지는 D3DX_VIDMODEDESC 구조체에의 포인터.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INITFAILED
D3DXERR_INVALIDD3DXDEVICEINDEX
D3DXERR_INVALIDPARAMETER
D3DXERR_NULLPOINTER

주의

D3DXGetVideoMode 함수에 의해 실행되는 쿼리는, 디스플레이 어댑터로부터 DirectX 에 그 지원 내용을 알리기 위한 모드 리스트를 지정하는 것만으로 있다. 리스트의 모든 비디오 모드에 대해 D3DXCreateContext 함수나 D3DXCreateContextEx 함수가 잘 기능 하면은 보증되어 있지 않다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXGetMaxNumVideoModes ,D3DXGetMaxNumVideoModes


D3DXInitialize

D3DXInitialize 함수는, Direct3DX 를 초기화한다.

HRESULT D3DXInitialize();

파라미터

없음.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DXERR_NOMEMORY
D3DXERR_STARTUPFAILED

주의

D3DXInitialize 함수는, Direct3DX 어플리케이션에 의해 최초로 불려 간다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXUninitialize


D3DXMakeDDPixelFormat

D3DXMakeDDPixelFormat 함수는, 요구된 Direct3DX 표면 포맷에 근거해 DDPIXELFORMAT 구조체를 돌려준다.

HRESULT D3DXMakeDDPixelFormat(
  D3DX_SURFACEFORMAT d3dxFormat,
  DDPIXELFORMAT* pddpf
);

파라미터

d3dxFormat
D3DX_SURFACEFORMAT 열거형의 멤버 (표면 포맷)에의 포인터.
pddpf
지정된 표면 포맷과 일치하는 픽셀 포맷을 기술해 돌려주는 DDPIXELFORMAT 구조체에의 포인터.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DXERR_NULLPOINTER
D3DXERR_INVALIDPARAMETER

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMakeSurfaceFormat


D3DXMakeSurfaceFormat

D3DXMakeSurfaceFormat 함수는, 지정된 DDPIXELFORMAT 구조체에 대응하는 표면 포맷을 판정한다.

D3DX_SURFACEFORMAT D3DXMakeSurfaceFormat(
  DDPIXELFORMAT* pddpf
);

파라미터

pddpf
DDPIXELFORMAT 구조체에의 포인터.

반환값

pddpf 파라미터에 대응하는 D3DX_SURFACEFORMAT 열거형의 멤버.

주의

pddpf 파라미터가 NULL 의 경우, 또는 그것이 미확인 픽셀 포맷의 경우,D3DXMakeSurfaceFormat 함수는 D3DX_SF_UNKNOWN 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMakeDDPixelFormat


D3DXUninitialize

D3DXUninitialize 함수는, Direct3DX 로 사용된 리소스를 릴리즈 한다.

HRESULT D3DXUninitialize();

파라미터

없음.

반환값

성공하면, S_OK 를 돌려준다. 실패하면,D3DXERR_D3DXNOTSTARTEDYET 를 돌려준다.

주의

D3DXUninitialize 함수는, Direct3DX 어플리케이션에 의해 마지막에 불려 간다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXInitialize


산술 함수

Direct3DX 유틸리티 라이브러리에 의해 제공되고 있는 산술 라이브러리에는, 기본적인 산술 연산과 복잡한 3D 산술 연산의 양쪽 모두를 계산하는 함수가 있다.

3D 산술 어플리케이션 함수는, 이하의 그룹에 정리할 수가 있다.

컬러 | D3DXColorAdd
 | D3DXColorAdjustContrast
 | D3DXColorAdjustSaturation
 | D3DXColorLerp
 | D3DXColorModulate
 | D3DXColorNegative
 | D3DXColorScale
 | D3DXColorSubtract
생성 | D3DXCreateMatrixStack
평면 | D3DXPlaneDot
 | D3DXPlaneDotCoord
 | D3DXPlaneDotNormal
 | D3DXPlaneIntersectLine
 | D3DXPlaneFromPointNormal
 | D3DXPlaneFromPoints
 | D3DXPlaneTransform
쿼터니온 | D3DXQuaternionBaryCentric
 | D3DXQuaternionConjugate
 | D3DXQuaternionDot
 | D3DXQuaternionExp
 | D3DXQuaternionIdentity
 | D3DXQuaternionInverse
 | D3DXQuaternionIsIdentity
 | D3DXQuaternionLength
 | D3DXQuaternionLengthSq
 | D3DXQuaternionLn
 | D3DXQuaternionMultiply
 | D3DXQuaternionNormalize
 | D3DXQuaternionRotationAxis
 | D3DXQuaternionRotationMatrix
 | D3DXQuaternionRotationYawPitchRoll
 | D3DXQuaternionSlerp
 | D3DXQuaternionSquad
 | D3DXQuaternionToAxisAngle
2D 벡터 | D3DXVec2Add
 | D3DXVec2BaryCentric
 | D3DXVec2CCW
 | D3DXVec2Dot
 | D3DXVec2Hermite
 | D3DXVec2Length
 | D3DXVec2LengthSq
 | D3DXVec2Lerp
 | D3DXVec2Maximize
 | D3DXVec2Minimize
 | D3DXVec2Normalize
 | D3DXVec2Scale
 | D3DXVec2Subtract
 | D3DXVec2Transform
 | D3DXVec2TransformCoord
 | D3DXVec2TransformNormal
3D 벡터 | D3DXVec3Add
 | D3DXVec3BaryCentric
 | D3DXVec3Cross
 | D3DXVec3Dot
 | D3DXVec3Hermite
 | D3DXVec3Length
 | D3DXVec3LengthSq
 | D3DXVec3Lerp
 | D3DXVec3Maximize
 | D3DXVec3Minimize
 | D3DXVec3Normalize
 | D3DXVec3Scale
 | D3DXVec3Subtract
 | D3DXVec3Transform
 | D3DXVec3TransformCoord
 | D3DXVec3TransformNormal
4D 행렬 | D3DXMatrixAffineTransformation
 | D3DXMatrixfDeterminant
 | D3DXMatrixIdentity
 | D3DXMatrixInverse
 | D3DXMatrixIsIdentity
 | D3DXMatrixLookAt
 | D3DXMatrixLookAtLH
 | D3DXMatrixMultiply
 | D3DXMatrixOrtho
 | D3DXMatrixOrthoLH
 | D3DXMatrixOrthoOffCenter
 | D3DXMatrixOrthoOffCenterLH
 | D3DXMatrixPerspective
 | D3DXMatrixPerspectiveLH
 | D3DXMatrixPerspectiveFov
 | D3DXMatrixPerspectiveFovLH
 | D3DXMatrixPerspectiveOffCenter
 | D3DXMatrixPerspectiveOffCenterLH
 | D3DXMatrixReflect
 | D3DXMatrixRotationAxis
 | D3DXMatrixRotationQuaternion
 | D3DXMatrixRotationX
 | D3DXMatrixRotationY
 | D3DXMatrixRotationYawPitchRoll
 | D3DXMatrixRotationZ
 | D3DXMatrixScaling
 | D3DXMatrixShadow
 | D3DXMatrixTransformation
 | D3DXMatrixTranslation
 | D3DXMatrixTranspose
4D 벡터 | D3DXVec4Add
 | D3DXVec4BaryCentric
 | D3DXVec4Cross
 | D3DXVec4Dot
 | D3DXVec4Hermite
 | D3DXVec4Length
 | D3DXVec4LengthSq
 | D3DXVec4Lerp
 | D3DXVec4Maximize
 | D3DXVec4Minimize
 | D3DXVec4Normalize
 | D3DXVec4Scale
 | D3DXVec4Subtract
 | D3DXVec4Transform

메모 모든 산술 함수는, 입력 파라미터와 출력 파라미터의 양쪽 모두로 같은 오브젝트를 사용할 수 있다. 또, 출력 파라미터는 보통 반환값으로서 돌려주어지므로, 어느 산술 함수의 출력을 다른 산술 함수의 파라미터로서 사용할 수 있다.


D3DXColorAdd

D3DXColorAdd 함수는, 2 개의 컬러값을 덧셈 해, 새로운 컬러값을 생성 한다.

D3DXCOLOR* D3DXColorAdd(
  D3DXCOLOR* pOut,
  const D3DXCOLOR* pC1,
  const D3DXCOLOR* pC2
);

파라미터

pOut
연산 결과인 D3DXCOLOR 구조체에의 포인터.
pC1
소스의 D3DXCOLOR 구조체에의 포인터.
pC2
소스의 D3DXCOLOR 구조체에의 포인터.

반환값

2 개의 컬러값의 합계인 D3DXCOLOR 구조체에의 포인터를 돌려준다.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXColorAdd 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXColorModulate ,D3DXColorSubtract


D3DXColorAdjustContrast

D3DXColorAdjustContrast 함수는, 지정한 색의 콘트라스트값을 조정한다.

D3DXCOLOR* D3DXColorAdjustContrast(
  D3DXCOLOR* pOut,
  D3DXCOLOR* pC,
  float c
);

파라미터

pOut
연산 결과인 D3DXCOLOR 구조체에의 포인터.
pC
소스의 D3DXCOLOR 구조체에의 포인터.
c
콘트라스트값. 이 파라미터는,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 보다 큰 경우, 콘트라스트는 커진다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXColorAdjustSaturation


D3DXColorAdjustSaturation

D3DXColorAdjustSaturation 함수는, 지정된 색의 포화값을 조정한다.

D3DXCOLOR* D3DXColorAdjustSaturation(
  D3DXCOLOR* pOut,
  D3DXCOLOR* pC,
  float s
);

파라미터

pOut
연산 결과인 D3DXCOLOR 구조체에의 포인터.
pC
소스의 D3DXCOLOR 구조체에의 포인터.
s
포화값. 이 파라미터는, 그레이 스케일에 변환된 색과 오리지날 컬러 pC 의 사이에 선형 보간 한다. s 값에 제한값은 없다. s 가 0 의 경우, 돌려주어지는 색은 그레이 스케일의 색이다. s 가 1 의 경우, 돌려주어지는 색은 오리지날 컬러이다.

반환값

함수는, 포화 조정 결과의 D3DXCOLOR 구조체에의 포인터를 돌려준다.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXColorAdjustSaturation 함수를 다른 함수의 파라미터로서 사용할 수 있다.

이 함수는, 미포화 컬러와 지정 컬러의 사이에 D3DXCOLOR 구조체의 적 (red), 초록 (green), 파랑 (blue)의 색성분을 보간 한다.

    // 휘도(Luminance)에 대한 각 성분의 계수의 적절한 값.
    // 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 로서 산출된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXColorAdjustContrast


D3DXColorLerp

D3DXColorLerp 함수는, 선형 보간을 사용해, 컬러값을 생성 한다.

D3DXCOLOR* D3DXColorLerp(
  D3DXCOLOR* pOut,
  const D3DXCOLOR* pC1,
  const D3DXCOLOR* pC2,
  float s
);

파라미터

pOut
연산 결과인 D3DXCOLOR 구조체에의 포인터.
pC1
소스의 D3DXCOLOR 구조체에의 포인터.
pC2
소스의 D3DXCOLOR 구조체에의 포인터.
s
이 파라미터는,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 가 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXColorModulate ,D3DXColorNegative ,D3DXColorScale


D3DXColorModulate

D3DXColorModulate 함수는, 지정된 2 개의 색을 혼합한다.

D3DXCOLOR* D3DXColorModulate(
  D3DXCOLOR* pOut,
  const D3DXCOLOR* pC1,
  const D3DXCOLOR* pC2
);

파라미터

pOut
연산 결과인 D3DXCOLOR 구조체에의 포인터.
pC1
소스의 D3DXCOLOR 구조체에의 포인터.
pC2
소스의 D3DXCOLOR 구조체에의 포인터.

반환값

함수는, 혼합 결과인 D3DXCOLOR 구조체에의 포인터를 돌려준다.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXColorModulate 함수를 다른 함수의 파라미터로서 사용할 수 있다.

이 함수는, 조합색성분을 적산하는 것으로, 지정된 2 개의 색을 혼합한다.

    pOut->r = pC1->r * pC2->r;

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXColorLerp ,D3DXColorNegative ,D3DXColorScale


D3DXColorNegative

D3DXColorNegative 함수는, 지정된 컬러값의 부의 색을 생성 한다.

D3DXCOLOR* D3DXColorNegative(
  D3DXCOLOR* pOut,
  const D3DXCOLOR* pC
);

파라미터

pOut
연산 결과인 D3DXCOLOR 구조체에의 포인터.
pC
소스의 D3DXCOLOR 구조체에의 포인터.

반환값

함수는, 지정된 컬러값의 부의 색인 D3DXCOLOR 구조체에의 포인터를 돌려준다.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXColorNegative 함수를 다른 함수의 파라미터로서 사용할 수 있다.

이 함수는, 지정된 D3DXCOLOR 구조체의 색성분으로부터 1.0 을 나눗셈 하는 것으로 부의 컬러값을 돌려준다.

    pOut->r = 1.0f - pC->r;

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXColorLerp ,D3DXColorModulate ,D3DXColorScale


D3DXColorScale

D3DXColorScale 함수는, 컬러값을 스케일링 한다.

D3DXCOLOR* D3DXColorScale(
  D3DXCOLOR* pOut,
  const D3DXCOLOR* pC,
  float s
);

파라미터

pOut
연산 결과인 D3DXCOLOR 구조체에의 포인터.
pC
소스의 D3DXCOLOR 구조체에의 포인터.
s
스케일링 계수. 색을 4D 벡터와 같이 처리해, 그것을 스케일링 한다. s 값에 제한값은 없다. s 가 1 의 경우, 돌려주어지는 색은 오리지날 컬러이다.

반환값

함수는, 스케일링 된 컬러값인 D3DXCOLOR 구조체에의 포인터를 돌려준다.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXColorScale 함수를 다른 함수의 파라미터로서 사용할 수 있다.

이 함수는, 지정된 D3DXCOLOR 구조체의 색성분으로 지정된 스케일링 계수를 적산하는 것으로, 스케일링 한 컬러값을 산출한다.

    pOut->r = pC->r * s;

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXColorLerp ,D3DXColorModulate ,D3DXColorNegative


D3DXColorSubtract

D3DXColorSubtract 함수는, 2 개의 컬러값을 뺄셈 해, 새로운 컬러값을 생성 한다.

D3DXCOLOR* D3DXColorSubtract(
  D3DXCOLOR* pOut,
  const D3DXCOLOR* pC1,
  const D3DXCOLOR* pC2
);

파라미터

pOut
연산 결과인 D3DXCOLOR 구조체에의 포인터.
pC1
소스의 D3DXCOLOR 구조체에의 포인터.
pC2
소스의 D3DXCOLOR 구조체에의 포인터.

반환값

이 함수는, 2 개의 컬러값의 차분인 D3DXCOLOR 구조체에의 포인터를 돌려준다.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXColorSubtract 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXColorAdd


D3DXCreateMatrixStack

D3DXCreateMatrixStack 함수는,ID3DXMatrixStack 인터페이스의 인스턴스를 생성 한다.

HRESULT D3DXCreateMatrixStack(
  DWORD flags,
  ID3DXMatrixStack** ppStack
);

파라미터

flags
이행되어 있지 않다. 0 을 지정하는 것.
ppStack
함수가 성공했을 경우는,ID3DXMatrixStack 인터페이스 포인터가 설정되는 포인터의 주소.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXMatrixAffineTransformation

D3DXMatrixAffineTransformation 함수는, 아핀트란스포무 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixAffineTransformation(
  D3DXMATRIX* pOut,
  float scaling,
  const D3DXVECTOR3* pRotationCenter,
  const D3DXQUATERNION* pRotation,
  const D3DXVECTOR3* pTranslation
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
scaling
스케일링 계수
pRotationCenter
회전의 중심을 식별하는 점인 D3DXVECTOR3 구조체에의 포인터. 이 인수가 NULL 의 경우, 그것은 단위원으로서 처리된다.
pRotation
회전 처리를 지정하는 D3DXQUATERNION 구조체에의 포인터. 이 인수가 NULL 의 경우, 그것은 단위원으로서 처리된다.
pTranslation
변환 방법을 나타낸 D3DXVECTOR3 구조체에의 포인터. 이 인수가 NULL 의 경우, 그것은 단위원으로서 처리된다.

반환값

아핀트란스포무 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

D3DXMatrixAffineTransformation 함수는, Ms * Mrc-1 * Mr * Mrc * Mt 식에 의해 아핀트란스포무 행렬을 산출한다. 여기서, Ms 는 스케일 행렬, Mrc 는 회전 행렬의 중심, Mr 는 회전 행렬, Mt 는 트랜스 폼 행렬이다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixAffineTransformation 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXMatrixfDeterminant

D3DXMatrixfDeterminant 함수는, 지정된 행렬의 행렬식을 돌려준다.

float D3DXMatrixfDeterminant(
  const D3DXMATRIX* pM
);

파라미터

pM
소스의 D3DXMATRIX 구조체에의 포인터.

반환값

행렬의 값, 행렬식.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXMatrixIdentity

D3DXMatrixIdentity 함수는, 단위행렬을 생성 한다.

D3DXMATRIX* D3DXMatrixIdentity(
  D3DXMATRIX* pOut
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.

반환값

단위행렬인 D3DXMATRIX 구조체에의 포인터.

주의

단위행렬은,[1,1][2,2][3,3][4,4] 계수에 1 이 설정되어 있는 것 제외해, 모든 계수가 0 의 행렬이다. 단위행렬은, 버텍스에 적용되어도 그것들이 변경되지 않는다고 하는 점으로써 특별하다. 단위행렬은, 버텍스값을 변경해 회전, 평행이동, 및 4 × 4 행렬로 표현할 수 있는 그 외의 변환을 실시하는 행렬의 기점으로서 사용된다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixIdentity 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixIsIdentity


D3DXMatrixInverse

D3DXMatrixInverse 함수는, 지정된 행렬의 역원을 산출한다.

D3DXMATRIX* D3DXMatrixInverse(
  D3DXMATRIX* pOut,
  float* pfDeterminant,
  const D3DXMATRIX* pM
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
pfDeterminant
이 함수가 돌아온 후, 이 파라미터는 지정된 행렬 pM 의 행렬값인 float 값을 포인트 하고 있다.
pM
소스의 D3DXMATRIX 구조체에의 포인터.

반환값

지정된 행렬의 역원인 D3DXMATRIX 구조체에의 포인터.

주의

행렬의 역변환이 실패 하면,D3DXMatrixInverse 함수로부터 NULL 가 돌려주어진다. 다만,pfDeterminant 파라미터가 NULL 이외의 경우는 pM 의 행렬값이 돌려주어진다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixInverse 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXMatrixIsIdentity

D3DXMatrixIsIdentity 함수는, 지정된 행렬이 단위행렬일지 어떨지를 판정한다.

BOOL D3DXMatrixIsIdentity(
  const D3DXMATRIX* pM
);

파라미터

pM
단위행렬일지 어떨지를 판정하는 D3DXMATRIX 구조체에의 포인터.

반환값

지정된 행렬이 단위행렬인 경우, 이 함수는 TRUE 를 돌려준다. 그 이외의 경우는, FALSE 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixIdentity


D3DXMatrixLookAt

D3DXMatrixLookAt 함수는, 오른손 좌표계목시 행렬 (right-handed, look-at matrix)을 구축한다.

D3DXMATRIX* D3DXMatrixLookAt(
  D3DXMATRIX* pOut,
  const D3DXVECTOR3* pEye,
  const D3DXVECTOR3* pAt,
  const D3DXVECTOR3* pUp
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
pEye
시점을 정의한 D3DXVECTOR3 구조체에의 포인터. 이 값은, 평행이동시에 사용된다.
pAt
카메라의 목시 대상을 정의한 D3DXVECTOR3 구조체에의 포인터.
pUp
현재 월드의 윗쪽, 일반적으로는 [0, 1, 0] 을 정의한 D3DXVECTOR3 구조체에의 포인터.

반환값

오른손 좌표계목시 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixLookAt 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixLookAtLH


D3DXMatrixLookAtLH

D3DXMatrixLookAtLH 함수는, 왼손 좌표계목시 행렬 (left-handed, look-at matrix)을 구축한다.

D3DXMATRIX* D3DXMatrixLookAtLH(
  D3DXMATRIX* pOut,
  const D3DXVECTOR3* pEye,
  const D3DXVECTOR3* pAt,
  const D3DXVECTOR3* pUp
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
pEye
시점을 정의한 D3DXVECTOR3 구조체에의 포인터. 이 값은, 평행이동시에 사용된다.
pAt
카메라의 목시 대상을 정의한 D3DXVECTOR3 구조체에의 포인터.
pUp
현재 월드의 윗쪽 (높이), 일반적으로는 [0, 1, 0] 을 정의한 D3DXVECTOR3 구조체에의 포인터.

반환값

왼손 좌표계목시 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixLookAtLH 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixLookAt


D3DXMatrixMultiply

D3DXMatrixMultiply 함수는, 지정된 2 개의 행렬의 적을 산출한다.

D3DXMATRIX* D3DXMatrixMultiply(
  D3DXMATRIX* pOut,
  const D3DXMATRIX* pM1,
  const D3DXMATRIX* pM2
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
pM1
소스의 D3DXMATRIX 구조체에의 포인터.
pM2
소스의 D3DXMATRIX 구조체에의 포인터.

반환값

2 개의 행렬의 적인 D3DXMATRIX 구조체에의 포인터.

주의

결과는, 변환 M1 후의 변환 M2 의 결과를 나타낸다 (Out = M1 * M2).

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixMultiply 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXQuaternionMultiply


D3DXMatrixOrtho

D3DXMatrixOrtho 함수는, 오른손 좌표계 정사영 (정규 직교변환) 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixOrtho(
  D3DXMATRIX* pOut,
  float w,
  float h,
  float zn,
  float zf
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
w
뷰 볼륨의 폭.
h
뷰 볼륨의 높이.
zn
뷰 볼륨의 최소 z 값.
zf
뷰 볼륨의 최대 z 값.

반환값

오른손 좌표계 정사영 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

직행 행렬이란, 행렬의 역변환이 행렬의 전조와 등가인 역변환 가능한 행렬이다.

D3DXMatrixOrtho 함수의 파라미터는 모두, 카메라 공간에서의 거리이다. 파라미터는, 뷰 볼륨의 넓이를 기술하고 있다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixOrtho 함수를 다른 함수의 파라미터로서 사용할 수 있다.

D3DXCreateContext 함수와 D3DXCreateContextEx 함수에 의해 셋업 된 디폴트의 투영 행렬은, pi/2 라디안의 시역 (fov)에서의 왼손 좌표계 퍼스펙티브 투영이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixOrthoLH ,D3DXMatrixOrthoOffCenter ,D3DXMatrixOrthoOffCenterLH


D3DXMatrixOrthoLH

D3DXMatrixOrthoLH 함수는, 왼손 좌표계 정사영 (정규 직교변환) 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixOrthoLH(
  D3DXMATRIX* pOut,
  float w,
  float h,
  float zn,
  float zf
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
w
뷰 볼륨의 폭.
h
뷰 볼륨의 높이.
zn
뷰 볼륨의 최소 z 값.
zf
뷰 볼륨의 최대 z 값.

반환값

왼손 좌표계 정사영 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

직행 행렬이란, 행렬의 역변환이 행렬의 전조와 등가인 역변환 가능한 행렬이다.

D3DXMatrixOrthoLH 함수의 파라미터는 모두, 카메라 공간에서의 거리이다. 파라미터는, 뷰 볼륨의 넓이를 기술하고 있다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixOrthoLH 함수를 다른 함수의 파라미터로서 사용할 수 있다.

D3DXCreateContext 함수와 D3DXCreateContextEx 함수에 의해 셋업 된 디폴트의 투영 행렬은, pi/2 라디안의 시역 (fov)에서의 왼손 좌표계 퍼스펙티브 투영이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixOrtho ,D3DXMatrixOrthoOffCenter ,D3DXMatrixOrthoOffCenterLH


D3DXMatrixOrthoOffCenter

D3DXMatrixOrthoOffCenter 함수는, 커스터마이즈 된 오른손 좌표계 정사영 (정규 직교변환) 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixOrthoOffCenter(
  D3DXMATRIX* pOut,
  float l,
  float r,
  float t,
  float b,
  float zn,
  float zf
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
l
뷰 볼륨의 최소 x 값.
r
뷰 볼륨의 최대 x 값.
t
뷰 볼륨의 최소 y 값.
b
뷰 볼륨의 최대 y 값.
zn
뷰 볼륨의 최소 z 값.
zf
뷰 볼륨의 최대 z 값.

반환값

오른손 좌표계 정사영 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

직행 행렬이란, 행렬의 역변환이 행렬의 전조와 등가인 역변환 가능한 행렬이다.

D3DXMatrixOrtho 함수는,D3DXMatrixOrthoOffCenter 함수를 사용해 같은 투영을 생성하기 위한 D3DXMatrixOrthoOffCenter 함수의 특별한 케이스이다. l = -w/2,r = w/2,b = -h/2,t = h/2 라고 하는 값을 사용하는 것.

D3DXMatrixOrthoOffCenter 함수의 파라미터는 모두, 카메라 공간에서의 거리이다. 파라미터는, 뷰 볼륨의 넓이를 기술하고 있다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixOrthoOffCenter 함수를 다른 함수의 파라미터로서 사용할 수 있다.

D3DXCreateContext 함수와 D3DXCreateContextEx 함수에 의해 셋업 된 디폴트의 투영 행렬은, pi/2 라디안의 시역 (fov)에서의 왼손 좌표계 퍼스펙티브 투영이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixOrtho ,D3DXMatrixOrthoLH ,D3DXMatrixOrthoOffCenterLH


D3DXMatrixOrthoOffCenterLH

D3DXMatrixOrthoOffCenterLH 함수는, 커스터마이즈 된 왼손 좌표계 정사영 (정규 직교변환) 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixOrthoOffCenterLH(
  D3DXMATRIX* pOut,
  float l,
  float r,
  float t,
  float b,
  float zn,
  float zf
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
l
뷰 볼륨의 최소 x 값.
r
뷰 볼륨의 최대 x 값.
t
뷰 볼륨의 최소 y 값.
b
뷰 볼륨의 최대 y 값.
zn
뷰 볼륨의 최소 z 값.
zf
뷰 볼륨의 최대 z 값.

반환값

왼손 좌표계 정사영 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

직행 행렬이란, 행렬의 역변환이 행렬의 전조와 등가인 역변환 가능한 행렬이다.

D3DXMatrixOrthoLH 함수는,D3DXMatrixOrthoOffCenterLH 함수를 사용해 같은 투영을 생성하기 위한 D3DXMatrixOrthoOffCenterLH 함수의 특별한 케이스이다. l = -w/2,r = w/2,b = -h/2,t = h/2 라고 하는 값을 사용하는 것.

D3DXMatrixOrthoOffCenterLH 함수의 파라미터는 모두, 카메라 공간에서의 거리이다. 파라미터는, 뷰 볼륨의 넓이를 기술하고 있다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixOrthoOffCenterLH 함수를 다른 함수의 파라미터로서 사용할 수 있다.

D3DXCreateContext 함수와 D3DXCreateContextEx 함수에 의해 셋업 된 디폴트의 투영 행렬은, pi/2 라디안의 시역 (fov)에서의 왼손 좌표계 퍼스펙티브 투영이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixOrtho ,D3DXMatrixOrthoLH ,D3DXMatrixOrthoOffCenter


D3DXMatrixPerspective

D3DXMatrixPerspective 함수는, 오른손 좌표계 퍼스펙티브 투영 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixPerspective(
  D3DXMATRIX* pOut,
  float w,
  float h,
  float zn,
  float zf
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
w
가까이의 뷰 평면에서의 뷰 볼륨의 폭.
h
가까이의 뷰 평면에서의 뷰 볼륨의 높이.
zn
가까이의 뷰 평면의 z 값.
zf
먼 뷰 평면의 z 값.

반환값

오른손 좌표계 퍼스펙티브 투영 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

D3DXMatrixPerspective 함수의 파라미터는 모두, 카메라 공간에서의 거리이다. 파라미터는, 뷰 볼륨의 넓이를 기술하고 있다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixPerspective 함수를 다른 함수의 파라미터로서 사용할 수 있다.

D3DXCreateContext 함수와 D3DXCreateContextEx 함수에 의해 셋업 된 디폴트의 투영 행렬은, pi/2 라디안의 시역 (fov)에서의 왼손 좌표계 퍼스펙티브 투영이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixPerspectiveLH ,D3DXMatrixPerspectiveFov ,D3DXMatrixPerspectiveFovLH ,D3DXMatrixPerspectiveOffCenter ,D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveFov

D3DXMatrixPerspectiveFov 함수는, 지정된 시야에 근거해 오른손 좌표계 퍼스펙티브 투영 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixPerspectiveFov(
  D3DXMATRIX* pOut,
  float fovy,
  float aspect,
  float zn,
  float zf
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
fovy
시야 (라디안 단위).
aspect
어스펙트비(가로세로 비율).
zn
가까이의 뷰 평면의 z 값.
zf
먼 뷰 평면의 z 값.

반환값

오른손 좌표계 퍼스펙티브 투영 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixPerspectiveFov 함수를 다른 함수의 파라미터로서 사용할 수 있다.

D3DXCreateContext 함수와 D3DXCreateContextEx 함수에 의해 셋업 된 디폴트의 투영 행렬은, pi/2 라디안의 시역 (fov)에서의 왼손 좌표계 퍼스펙티브 투영이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixPerspective ,D3DXMatrixPerspectiveLH ,D3DXMatrixPerspectiveFovLH ,D3DXMatrixPerspectiveOffCenter ,D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveFovLH

D3DXMatrixPerspectiveFovLH 함수는, 지정된 시야에 근거해 왼손 좌표계 퍼스펙티브 투영 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixPerspectiveFovLH(
  D3DXMATRIX* pOut,
  float fovy,
  float aspect,
  float zn,
  float zf
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
fovy
시야 (라디안 단위).
aspect
어스펙트비(가로세로 비율).
zn
가까이의 뷰 평면의 z 값.
zf
먼 뷰 평면의 z 값.

반환값

왼손 좌표계 퍼스펙티브 투영 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixPerspectiveFovLH 함수를 다른 함수의 파라미터로서 사용할 수 있다.

D3DXCreateContext 함수와 D3DXCreateContextEx 함수에 의해 셋업 된 디폴트의 투영 행렬은, pi/2 라디안의 시역 (fov)에서의 왼손 좌표계 퍼스펙티브 투영이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixPerspective ,D3DXMatrixPerspectiveLH ,D3DXMatrixPerspectiveFov ,D3DXMatrixPerspectiveOffCenter ,D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveLH

D3DXMatrixPerspectiveLH 함수는, 왼손 좌표계 퍼스펙티브 투영 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixPerspectiveLH(
  D3DXMATRIX* pOut,
  float w,
  float h,
  float zn,
  float zf
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
w
가까이의 뷰 평면에서의 뷰 볼륨의 폭.
h
가까이의 뷰 평면에서의 뷰 볼륨의 높이.
zn
가까이의 뷰 평면의 z 값.
zf
먼 뷰 평면의 z 값.

반환값

왼손 좌표계 퍼스펙티브 투영 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

D3DXMatrixPerspectiveLH 함수의 파라미터는 모두, 카메라 공간에서의 거리이다. 파라미터는, 뷰 볼륨의 넓이를 기술하고 있다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixPerspectiveLH 함수를 다른 함수의 파라미터로서 사용할 수 있다.

D3DXCreateContext 함수와 D3DXCreateContextEx 함수에 의해 셋업 된 디폴트의 투영 행렬은, pi/2 라디안의 시역 (fov)에서의 왼손 좌표계 퍼스펙티브 투영이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixPerspective ,D3DXMatrixPerspectiveFov ,D3DXMatrixPerspectiveFovLH ,D3DXMatrixPerspectiveOffCenter ,D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveOffCenter

D3DXMatrixPerspectiveOffCenter 함수는, 커스터마이즈 된 오른손 좌표계 퍼스펙티브 투영 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixPerspectiveOffCenter(
  D3DXMATRIX* pOut,
  float l,
  float r,
  float t,
  float b,
  float zn,
  float zf
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
l
가까이의 뷰 평면의 x 값.
r
먼 뷰 평면의 x 값.
t
가까이의 뷰 평면의 y 값.
b
먼 뷰 평면의 y 값.
zn
가까이의 뷰 평면의 z 값.
zf
먼 뷰 평면의 z 값.

반환값

오른손 좌표계 퍼스펙티브 투영 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

D3DXMatrixPerspectiveOffCenter 함수의 파라미터는 모두, 카메라 공간에서의 거리이다. 파라미터는, 뷰 볼륨의 넓이를 기술하고 있다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixPerspectiveOffCenter 함수를 다른 함수의 파라미터로서 사용할 수 있다.

D3DXCreateContext 함수와 D3DXCreateContextEx 함수에 의해 셋업 된 디폴트의 투영 행렬은, pi/2 라디안의 시역 (fov)에서의 왼손 좌표계 퍼스펙티브 투영이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixPerspective ,D3DXMatrixPerspectiveLH ,D3DXMatrixPerspectiveFov ,D3DXMatrixPerspectiveFovLH ,D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveOffCenterLH

D3DXMatrixPerspectiveOffCenterLH 함수는, 커스터마이즈 된 왼손 좌표계 퍼스펙티브 투영 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixPerspectiveOffCenterLH(
  D3DXMATRIX* pOut,
  float l,
  float r,
  float t,
  float b,
  float zn,
  float zf
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
l
가까이의 뷰 평면의 x 값.
r
먼 뷰 평면의 x 값.
t
가까이의 뷰 평면의 y 값.
b
먼 뷰 평면의 y 값.
zn
가까이의 뷰 평면의 z 값.
zf
먼 뷰 평면의 z 값.

반환값

왼손 좌표계 퍼스펙티브 투영 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

D3DXMatrixPerspectiveOffCenterLH 함수의 파라미터는 모두, 카메라 공간에서의 거리이다. 파라미터는, 뷰 볼륨의 넓이를 기술하고 있다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixPerspectiveOffCenterLH 함수를 다른 함수의 파라미터로서 사용할 수 있다.

D3DXCreateContext 함수와 D3DXCreateContextEx 함수에 의해 셋업 된 디폴트의 투영 행렬은, pi/2 라디안의 시역 (fov)에서의 왼손 좌표계 퍼스펙티브 투영이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixPerspective ,D3DXMatrixPerspectiveLH ,D3DXMatrixPerspectiveFov ,D3DXMatrixPerspectiveFovLH ,D3DXMatrixPerspectiveOffCenter


D3DXMatrixReflect

D3DXMatrixReflect 함수는, 평면의 좌표계를 반영한 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixReflect(
  D3DXMATRIX* pOut,
  const D3DXPLANE* pPlane
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
pPlane
소스의 D3DXPLANE 구조체에의 포인터.

반환값

지정된 평면의 좌표계를 반영한 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixReflect 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXMatrixRotationAxis

D3DXMatrixRotationAxis 함수는, 임의의 축을 회전축으로서 회전한 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixRotationAxis(
  D3DXMATRIX* pOut,
  const D3DXVECTOR3* pV,
  float angle
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
pV
축의 각도를 식별하는 D3DXVECTOR3 구조체에의 포인터.
angle
회전의 각도 (라디안 단위). 각도는, 회전축으로부터 원점으로 향해 시계회전에 계측 된다.

반환값

지정된 축을 회전축으로서 회전한 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixRotationAxis 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixRotationQuaternion ,D3DXMatrixRotationX ,D3DXMatrixRotationY ,D3DXMatrixRotationYawPitchRoll ,D3DXMatrixRotationZ


D3DXMatrixRotationQuaternion

D3DXMatrixRotationQuaternion 함수는, 쿼터니온으로부터 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixRotationQuaternion(
  D3DXMATRIX* pOut,
  const D3DXQUATERNION* pQ
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
pQ
소스의 D3DXQUATERNION 구조체에의 포인터.

반환값

지정된 쿼터니온으로부터 구축된 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixRotationQuaternion 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixRotationAxis ,D3DXMatrixRotationX ,D3DXMatrixRotationY ,D3DXMatrixRotationYawPitchRoll ,D3DXMatrixRotationZ


D3DXMatrixRotationX

D3DXMatrixRotationX 함수는, x 축을 회전축으로서 회전한 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixRotationX(
  D3DXMATRIX* pOut,
  float angle
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
angle
회전 각도 (라디안 단위). 각도는, 회전축으로부터 원점으로 향해 시계회전에 계측 된다.

반환값

x 축을 회전축으로서 회전한 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixRotationX 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixRotationAxis ,D3DXMatrixRotationQuaternion ,D3DXMatrixRotationY ,D3DXMatrixRotationYawPitchRoll ,D3DXMatrixRotationZ


D3DXMatrixRotationY

D3DXMatrixRotationY 함수는, y 축을 회전축으로서 회전한 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixRotationY(
  D3DXMATRIX* pOut,
  float angle
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
angle
회전 각도 (라디안 단위). 각도는, 회전축으로부터 원점으로 향해 시계회전에 계측 된다.

반환값

y 축을 회전축으로서 회전한 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixRotationY 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixRotationAxis ,D3DXMatrixRotationQuaternion ,D3DXMatrixRotationX ,D3DXMatrixRotationYawPitchRoll ,D3DXMatrixRotationZ


D3DXMatrixRotationYawPitchRoll

D3DXMatrixRotationYawPitchRoll 함수는, 지정된 편흔들림각, 경사각, 및 회전각에 의해 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixRotationYawPitchRoll(
  D3DXMATRIX* pOut,
  float yaw,
  float pitch,
  float roll,
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
yaw
y 축의 편흔들림각 (라디안 단위).
pitch
x 축의 경사각 (라디안 단위).
roll
z 축의 회전각 (라디안 단위).

반환값

지정된 편흔들림각, 경사각, 및 회전각을 가지는 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixRotationYawPitchRoll 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixRotationAxis ,D3DXMatrixRotationQuaternion ,D3DXMatrixRotationX ,D3DXMatrixRotationY ,D3DXMatrixRotationZ


D3DXMatrixRotationZ

D3DXMatrixRotationZ 함수는, z 축을 회전축으로서 회전한 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixRotationZ(
  D3DXMATRIX* pOut,
  float angle
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
angle
회전 각도 (라디안 단위). 각도는, 회전축으로부터 원점으로 향해 시계회전에 계측 된다.

반환값

z 축을 회전축으로서 회전한 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixRotationZ 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixRotationAxis ,D3DXMatrixRotationQuaternion ,D3DXMatrixRotationX ,D3DXMatrixRotationY ,D3DXMatrixRotationYawPitchRoll


D3DXMatrixScaling

D3DXMatrixScaling 함수는, x 축, y 축, z 축으로 따라 스케일링 한 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixScaling(
  D3DXMATRIX* pOut,
  float sx,
  float sy,
  float sz,
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
sx
x 축으로 따라 적용되는 스케일링 계수.
sy
y 축으로 따라 적용되는 스케일링 계수.
sz
z 축으로 따라 적용되는 스케일링 계수.

반환값

스케일링 된 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixScaling 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXMatrixShadow

D3DXMatrixShadow 함수는, 도형을 평면으로 변환하는 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixShadow(
  D3DXMATRIX* pOut,
  const D3DXVECTOR4* pLight,
  const D3DXPLANE* pPlane
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
pLight
라이트의 위치를 기술한 D3DXVECTOR4 구조체에의 포인터.
pPlane
소스의 D3DXPLANE 구조체에의 포인터.

반환값

도형을 평면으로 변환하는 D3DXMATRIX 구조체에의 포인터.

주의

D3DXMatrixShadow 함수는, 라이트로부터 그림자를 변환하도록(듯이), 도형을 평면으로 변환한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixShadow 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXMatrixTransformation

D3DXMatrixTransformation 함수는, 트랜스 폼 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixTransformation(
  D3DXMATRIX* pOut,
  const D3DXVECTOR3* pScalingCenter,
  const D3DXQUATERNION* pScalingRotation,
  const D3DXVECTOR3* pScaling,
  const D3DXVECTOR3* pRotationCenter,
  const D3DXQUATERNION* pRotation,
  const D3DXVECTOR3* pTranslation,
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
pScalingCenter
스케일링의 중심을 식별하는 D3DXVECTOR3 구조체에의 포인터. 이 인수가 NULL 의 경우, 그것은 단위원으로서 처리된다.
pScalingRotation
스케일링 회전을 지정하는 D3DXQUATERNION 구조체에의 포인터. 이 인수가 NULL 의 경우, 이것은 단위원으로서 처리된다.
pScaling
스케일링 벡터인 D3DXVECTOR3 구조체에의 포인터. 이 인수가 NULL 의 경우, 그것은 단위원으로서 처리된다.
pRotationCenter
회전의 중심을 식별하는 D3DXVECTOR3 구조체에의 포인터. 이 인수가 NULL 의 경우, 그것은 단위원으로서 처리된다.
pRotation
회전을 지정하는 D3DXQUATERNION 구조체에의 포인터. 이 인수가 NULL 의 경우, 그것은 단위원으로서 처리된다.
pTranslation
평행이동을 나타내는 D3DXVECTOR3 구조체에의 포인터. 이 인수가 NULL 의 경우, 그것은 단위원으로서 처리된다.

반환값

트랜스 폼 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

D3DXMatrixTransformation 함수는, Msc-1 * Msr-1 * Ms * Msr * Msc * Mrc-1 * Mr * Mrc * Mt 식에 의해 트랜스 폼 행렬을 계산한다. 다만, Msc 는 중심의 스케일링 행렬, Msr 는 스케일링 회전 행렬, Ms 는 스케일링 행렬, Mrc 는 회전 행렬의 중심, Mr 는 회전 행렬, Mt 는 평행이동 행렬이다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixTransformation 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixAffineTransformation


D3DXMatrixTranslation

D3DXMatrixTranslation 함수는, 지정된 오프셋(offset)를 사용해 행렬을 구축한다.

D3DXMATRIX* D3DXMatrixTranslation(
  D3DXMATRIX* pOut,
  float x,
  float y,
  float z,
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
x
x 좌표의 오프셋(offset).
y
y 좌표의 오프셋(offset).
z
z 좌표의 오프셋(offset).

반환값

변환된 행렬인 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixTranslation 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXMatrixTranspose

D3DXMatrixTranspose 함수는, 지정된 행렬의 전조행렬을 돌려준다.

D3DXMATRIX* D3DXMatrixTranspose(
  D3DXMATRIX* pOut,
  const D3DXMATRIX* pM
);

파라미터

pOut
연산 결과인 D3DXMATRIX 구조체에의 포인터.
pM
소스의 D3DXMATRIX 구조체에의 포인터.

반환값

지정된 행렬의 전조행렬인 D3DXMATRIX 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXMatrixTranspose 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXPlaneDot

D3DXPlaneDot 함수는, 평면과 4D 벡터의 내적을 산출한다.

float D3DXPlaneDot(
  const D3DXPLANE* pP,
  const D3DXVECTOR4* pV
);

파라미터

pP
소스의 D3DXPLANE 구조체에의 포인터.
pV
D3DXVECTOR4 구조체에의 포인터.

반환값

지정된 평면과 4D 벡터의 내적.

주의

평면 (a, b, c, d)과 4D 벡터 (x, y, z, w)를 지정했을 경우, 이 함수의 반환값은 a*x + b*y + c*z + d*w 가 된다. D3DXPlaneDot 함수는, 평면과 동차 좌표의 관계를 판단할 때 유용하다. 예를 들어, 이 함수를 사용하면, 특정의 좌표가 특정의 평면상에 있을지 어떨지, 또는 특정의 좌표가 특정의 평면의 어느 쪽 측에 있을까를 판단할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXPlaneDotCoord ,D3DXPlaneDotNormal


D3DXPlaneDotCoord

D3DXPlaneDotCoord 함수는, 평면과 3D 벡터의 내적을 산출한다. 벡터의 w 파라미터는, 1 이다고 보여진다.

float D3DXPlaneDotCoord(
  const D3DXPLANE* pP,
  const D3DXVECTOR3* pV
);

파라미터

pP
소스의 D3DXPLANE 구조체에의 포인터.
pV
소스의 D3DXVECTOR3 구조체에의 포인터.

반환값

지정된 평면과 3D 벡터의 내적.

주의

평면 (a, b, c, d)과 3D 벡터 (x, y, z)를 지정했을 경우, 이 함수의 반환값은 a*x + b*y + c*z + d*1 가 된다. D3DXPlaneDotCoord 함수는, 평면과 3D 공간의 좌표의 관계를 판단할 때 유용하다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXPlaneDot ,D3DXPlaneDotNormal


D3DXPlaneDotNormal

D3DXPlaneDotNormal 함수는, 평면과 3D 벡터의 내적을 산출한다. 벡터의 w 파라미터는, 0 이다고 보여진다.

float D3DXPlaneDotNormal(
  const D3DXPLANE* pP,
  const D3DXVECTOR3* pV
);

파라미터

pP
소스의 D3DXPLANE 구조체에의 포인터.
pV
소스의 D3DXVECTOR3 구조체에의 포인터.

반환값

지정된 평면과 3D 벡터의 내적.

주의

평면 (a, b, c, d)과 3D 벡터 (x, y, z)를 지정했을 경우, 이 함수의 반환값은 a*x + b*y + c*z + d*0 가 된다. D3DXPlaneDotNormal 함수는, 평면의 법선과 다른 평면의 각도를 판단할 때 유용하다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXPlaneDot ,D3DXPlaneDotCoord


D3DXPlaneFromPointNormal

D3DXPlaneFromPointNormal 함수는, 점과 법선으로부터 평면을 구축한다.

D3DXPLANE* D3DXPlaneFromPointNormal(
  D3DXPLANE* pOut,
  const D3DXVECTOR3* pPoint,
  const D3DXVECTOR3* pNormal
);

파라미터

pOut
처리 결과인 D3DXPLANE 구조체에의 포인터.
pPoint
D3DXVECTOR3 구조체에의 포인터. 이것은, 평면을 구축할 경우에 사용하는 점이다.
pNormal
D3DXVECTOR3 구조체에의 포인터. 이것은, 평면을 구축할 경우에 사용하는 법선이다.

반환값

지정된 점과 법선으로부터 구축한 D3DXPLANE 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXPlaneFromPointNormal 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXPlaneFromPoints


D3DXPlaneFromPoints

D3DXPlaneFromPoints 함수는, 3 점으로부터 평면을 구축한다.

D3DXPLANE* D3DXPlaneFromPoints(
  D3DXPLANE* pOut,
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pV2,
  const D3DXVECTOR3* pV3
);

파라미터

pOut
처리 결과인 D3DXPLANE 구조체에의 포인터.
pV1
D3DXVECTOR3 구조체에의 포인터. 이것은, 평면을 구축할 경우에 사용하는 점의 1 개이다.
pV2
D3DXVECTOR3 구조체에의 포인터. 이것은, 평면을 구축할 경우에 사용하는 점의 1 개이다.
pV3
D3DXVECTOR3 구조체에의 포인터. 이것은, 평면을 구축할 경우에 사용하는 점의 1 개이다.

반환값

지정된 점으로부터 구축한 D3DXPLANE 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXPlaneFromPoints 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXPlaneFromPointNormal


D3DXPlaneIntersectLine

D3DXPlaneIntersectLine 함수는, 평면과 직선의 교선을 찾아낸다.

D3DXVECTOR3* D3DXPlaneIntersectLine(
  D3DXVECTOR3* pOut,
  const D3DXPLANE* pP,
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pV2
);

파라미터

pOut
지정된 평면과 직접적인 교선을 식별하는 D3DXVECTOR3 구조체에의 포인터.
pP
소스의 D3DXPLANE 구조체에의 포인터.
pV1
기점을 정의한 소스의 D3DXVECTOR3 구조체에의 포인터.
pV2
종점을 정의한 소스의 D3DXVECTOR3 구조체에의 포인터.

반환값

지정된 평면과 직선의 교선인 D3DXVECTOR3 구조체에의 포인터.

주의

직선이 평면에 대해서 평행의 경우, NULL 가 돌려주어진다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXPlaneIntersectLine 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXPlaneTransform

D3DXPlaneTransform 함수는, 지정된 행렬에 의해 평면을 변환한다.

D3DXPLANE* D3DXPlaneTransform(
  D3DXPLANE* pOut,
  const D3DXPLANE* pP,
  const D3DXMATRIX* pM
);

파라미터

pOut
처리 결과인 D3DXPLANE 구조체에의 포인터.
pP
소스의 D3DXPLANE 구조체에의 포인터.
pM
소스의 D3DMATRIX 구조체에의 포인터.

반환값

변환된 평면을 나타내는 D3DXPLANE 구조체에의 포인터.

주의

행렬 pM 는, 아핀 변환이 아니면 안된다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXPlaneTransform 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXQuaternionBaryCentric

D3DXQuaternionBaryCentric 함수는, 중심 좌표의 쿼터니온을 돌려준다.

D3DXQUATERNION* D3DXQuaternionBaryCentric(
  D3DXQUATERNION* pOut,
  const D3DXQUATERNION* pQ1,
  const D3DXQUATERNION* pQ2,
  const D3DXQUATERNION* pQ3,
  const D3DXQUATERNION* pQ4,
  float f,
  float g
);

파라미터

pOut
연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pQ1
소스의 D3DXQUATERNION 구조체에의 포인터.
pQ2
소스의 D3DXQUATERNION 구조체에의 포인터.
pQ3
소스의 D3DXQUATERNION 구조체에의 포인터.
pQ4
소스의 D3DXQUATERNION 구조체에의 포인터.
f
가중 계수. 「주의」를 참조할것.
g
가중 계수. 「주의」를 참조할것.

반환값

중심 좌표의 D3DXQUATERNION 구조체에의 포인터.

주의

중심 좌표를 계산하기 위해서,D3DXQuaternionBaryCentric 함수는 Slerp(Slerp(Q1, Q2, f+g), Slerp(Q1, Q3, f+g), g/(f+g))라고 하는 일련의 구(공) 선형 보간을 실시한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionBaryCentric 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXQuaternionConjugate

D3DXQuaternionConjugate 함수는, 지정된 쿼터니온의 공역을 돌려준다.

D3DXQUATERNION* D3DXQuaternionConjugate(
  D3DXQUATERNION* pOut,
  const D3DXQUATERNION* pQ
);

파라미터

pOut
연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pQ
소스의 D3DXQUATERNION 구조체에의 포인터.

반환값

지정된 쿼터니온의 공역인 D3DXQUATERNION 구조체에의 포인터.

주의

쿼터니온 (x, y, z, w)이 지정되었을 경우,D3DXQuaternionConjugate 함수는 쿼터니온 (-x, -y, -z, w)을 돌려준다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionConjugate 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXQuaternionInverse


D3DXQuaternionDot

D3DXQuaternionDot 함수는, 2 개의 쿼터니온의 내적을 돌려준다.

float D3DXQuaternionDot(
  D3DXQUATERNION* pQ1,
  const D3DXQUATERNION* pQ2
);

파라미터

pQ1
소스의 D3DXQUATERNION 구조체에의 포인터.
pQ2
소스의 D3DXQUATERNION 구조체에의 포인터.

반환값

2 개의 쿼터니온의 내적.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXQuaternionExp

D3DXQuaternionExp 함수는, 지수함수를 계산한다.

D3DXQUATERNION* D3DXQuaternionExp(
  D3DXQUATERNION* pOut,
  const D3DXQUATERNION* pQ
);

파라미터

pOut
연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pQ
소스의 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 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXQuaternionLn ,D3DXQuaternionSquad


D3DXQuaternionIdentity

D3DXQuaternionIdentity 함수는, 단위 쿼터니온을 돌려준다.

D3DXQUATERNION* D3DXQuaternionIdentity(
  D3DXQUATERNION* pOut
);

파라미터

pOut
연산 결과인 D3DXQUATERNION 구조체에의 포인터.

반환값

단위 쿼터니온인 D3DXQUATERNION 구조체에의 포인터.

주의

쿼터니온 (x, y, z, w)을 지정했을 경우,D3DXQuaternionIdentity 함수는 쿼터니온 (0, 0, 0, 1)을 돌려준다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionIdentity 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXQuaternionIsIdentity


D3DXQuaternionInverse

D3DXQuaternionInverse 함수는, 지정된 쿼터니온을 모두 부려, 재정규화한다.

D3DXQUATERNION* D3DXQuaternionInverse(
  D3DXQUATERNION* pOut,
  const D3DXQUATERNION* pQ
);

파라미터

pOut
연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pQ
소스의 D3DXQUATERNION 구조체에의 포인터.

반환값

지정된 쿼터니온의 역쿼터니온인 D3DXQUATERNION 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionInverse 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXQuaternionConjugate ,D3DXQuaternionNormalize


D3DXQuaternionIsIdentity

D3DXQuaternionIsIdentity 함수는, 지정된 쿼터니온이 단위 쿼터니온일지 어떨지를 판단한다.

BOOL D3DXQuaternionIsIdentity(
  const D3DXQUATERNION* pQ
);

파라미터

pQ
단위 쿼터니온일지 어떨지를 판정하는 D3DXQUATERNION 구조체에의 포인터.

반환값

지정된 쿼터니온이 단위 쿼터니온의 경우, 이 함수는 TRUE 를 돌려준다. 그 이외의 경우는, FALSE 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXQuaternionIdentity


D3DXQuaternionLength

D3DXQuaternionLength 함수는, 지정된 쿼터니온의 길이를 돌려준다.

float D3DXQuaternionLength(
  const D3DXQUATERNION* pQ
);

파라미터

pQ
소스의 D3DXQUATERNION 구조체에의 포인터.

반환값

쿼터니온의 길이.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXQuaternionLengthSq


D3DXQuaternionLengthSq

D3DXQuaternionLengthSq 함수는, 지정된 쿼터니온의 길이의 2 승을 돌려준다.

float D3DXQuaternionLengthSq(
  const D3DXQUATERNION* pQ
);

파라미터

pQ
소스의 D3DXQUATERNION 구조체에의 포인터.

반환값

쿼터니온의 길이의 2 승.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXQuaternionLength


D3DXQuaternionLn

D3DXQuaternionLn 함수는, 자연대수를 계산한다.

D3DXQUATERNION* D3DXQuaternionLn(
  D3DXQUATERNION* pOut,
  const D3DXQUATERNION* pQ
);

파라미터

pOut
연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pQ
소스의 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 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXQuaternionExp ,D3DXQuaternionSquad


D3DXQuaternionMultiply

D3DXQuaternionMultiply 함수는, 2 개의 쿼터니온을 적산한다.

D3DXQUATERNION* D3DXQuaternionMultiply(
  D3DXQUATERNION* pOut,
  const D3DXQUATERNION* pQ1,
  const D3DXQUATERNION* pQ2
);

파라미터

pOut
연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pQ1
소스의 D3DXQUATERNION 구조체에의 포인터.
pQ2
소스의 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 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXMatrixMultiply


D3DXQuaternionNormalize

D3DXQuaternionNormalize 함수는, 지정된 쿼터니온의 법선을 돌려준다.

D3DXQUATERNION* D3DXQuaternionNormalize(
  D3DXQUATERNION* pOut,
  const D3DXQUATERNION* pQ
);

파라미터

pOut
연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pQ
소스의 D3DXQUATERNION 구조체에의 포인터.

반환값

지정된 쿼터니온의 법선인 D3DXQUATERNION 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionNormalize 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXQuaternionInverse


D3DXQuaternionRotationAxis

D3DXQuaternionRotationAxis 함수는, 임의의 축을 회전축으로서 지정된 쿼터니온을 회전한다.

D3DXQUATERNION* D3DXQuaternionRotationAxis(
  D3DXQUATERNION* pOut,
  const D3DXVECTOR3* pV,
  float angle
);

파라미터

pOut
연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pV
축의 각도를 식별하는 D3DXVECTOR3 구조체에의 포인터.
angle
회전의 각도 (라디안 단위). 각도는, 회전축으로부터 원점으로 향해 시계회전에 계측 된다.

반환값

지정된 축을 회전축으로서 회전한 D3DXQUATERNION 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionRotationAxis 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 을 사용.

참조

D3DXQuaternionRotationMatrix ,D3DXQuaternionRotationYawPitchRoll


D3DXQuaternionRotationMatrix

D3DXQuaternionRotationMatrix 함수는, 회전 행렬로부터 쿼터니온을 구축한다.

D3DXQUATERNION* D3DXQuaternionRotationMatrix(
  D3DXQUATERNION* pOut,
  const D3DXMATRIX* pM
);

파라미터

pOut
연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pM
소스의 D3DXMATRIX 구조체에의 포인터.

반환값

지정된 회전 행렬로부터 구축된 D3DXQUATERNION 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionRotationMatrix 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXQuaternionRotationAxis ,D3DXQuaternionRotationYawPitchRoll


D3DXQuaternionRotationYawPitchRoll

D3DXQuaternionRotationYawPitchRoll 함수는, 지정된 편흔들림각, 경사각, 및 회전각에 의해 쿼터니온을 구축한다.

D3DXQUATERNION* D3DXQuaternionRotationYawPitchRoll(
  D3DXQUATERNION* pOut,
  float yaw,
  float pitch,
  float roll
);

파라미터

pOut
연산 결과인 D3DXQUATERNION 구조체에의 포인터.
yaw
y 축의 편흔들림각 (라디안 단위).
pitch
x 축의 경사각 (라디안 단위).
roll
z 축의 회전각 (라디안 단위).

반환값

편흔들림각, 경사각, 및 회전각을 가지는 D3DXQUATERNION 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionRotationYawPitchRoll 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXQuaternionRotationAxis ,D3DXQuaternionRotationMatrix


D3DXQuaternionSlerp

D3DXQuaternionSlerp 함수는, 구(공) 선형 보간을 사용해 2 개의 쿼터니온간을 보간 한다.

D3DXQUATERNION* D3DXQuaternionSlerp(
  D3DXQUATERNION* pOut,
  const D3DXQUATERNION* pQ1,
  const D3DXQUATERNION* pQ2,
  float t
);

파라미터

pOut
연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pQ1
소스의 D3DXQUATERNION 구조체에의 포인터.
pQ2
소스의 D3DXQUATERNION 구조체에의 포인터.
t
이 값은, 지정된 2 개의 쿼터니온간을 보간 하는 범위를 지정한다.

반환값

보간 결과인 D3DXQUATERNION 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionSlerp 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXQuaternionSquad

D3DXQuaternionSquad 함수는, 구(공) 사각형 보간을 사용해, 쿼터니온간을 보간 한다.

D3DXQUATERNION* D3DXQuaternionSquad(
  D3DXQUATERNION* pOut,
  const D3DXQUATERNION* pQ1,
  const D3DXQUATERNION* pQ2,
  const D3DXQUATERNION* pQ3,
  const D3DXQUATERNION* pQ4,
  float t
);

파라미터

pOut
연산 결과인 D3DXQUATERNION 구조체에의 포인터.
pQ1
소스의 D3DXQUATERNION 구조체에의 포인터.
pQ2
소스의 D3DXQUATERNION 구조체에의 포인터.
pQ3
소스의 D3DXQUATERNION 구조체에의 포인터.
pQ4
소스의 D3DXQUATERNION 구조체에의 포인터.
t
이 파라미터는, 쿼터니온간을 보간 하는 범위를 지정한다.

반환값

구(공) 사각형 보간의 결과인 D3DXQUATERNION 구조체에의 포인터.

주의

함수는, Slerp(Slerp(Q1, Q4, t), Slerp(Q2, Q3, t), 2t(1-t))의 일련의 구(공) 선형 보간 연산을 사용한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXQuaternionSquad 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXQuaternionExp ,D3DXQuaternionLn


D3DXQuaternionToAxisAngle

D3DXQuaternionToAxisAngle 함수는, 쿼터니온의 축과 회전 각도를 계산한다.

void D3DXQuaternionToAxisAngle(
  const D3DXQUATERNION* pQ,
  D3DXVECTOR3* pAxis,
  float* pAngle
);

파라미터

pQ
소스의 D3DXQUATERNION 구조체에의 포인터.
pAxis
이 함수가 돌아오면(자), 이 파라미터는 쿼터니온의 축을 식별하는 D3DXVECTOR3 구조체를 포인트 하고 있다.
pAngle
이 함수가 돌아오면(자), 이 파라미터는 쿼터니온의 회전 각도 (라디안 단위)를 식별하는 float 값을 포인트 하고 있다.

반환값

없음.

주의

이 함수는, 단위 쿼터니온이 건네받는 것과 가정하고 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXVec2Add

D3DXVec2Add 함수는, 2 개의 2D 벡터를 덧셈 한다.

D3DXVECTOR2* D3DXVec2Add(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV1,
  const D3DXVECTOR2* pV2
);

파라미터

pOut
연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV1
소스의 D3DXVECTOR2 구조체에의 포인터.
pV2
소스의 D3DXVECTOR2 구조체에의 포인터.

반환값

지정된 2 개의 벡터의 합계인 D3DXVECTOR2 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2Add 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec2Subtract ,D3DXVec2Scale


D3DXVec2BaryCentric

D3DXVec2BaryCentric 함수는, 지정된 2D 벡터를 사용해 중심 좌표의 점을 돌려준다.

D3DXVECTOR2* D3DXVec2BaryCentric(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV1,
  const D3DXVECTOR2* pV2,
  D3DXVECTOR2* pV3,
  float f,
  float g
);

파라미터

pOut
연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV1
소스의 D3DXVECTOR2 구조체에의 포인터.
pV2
소스의 D3DXVECTOR2 구조체에의 포인터.
pV3
소스의 D3DXVECTOR2 구조체에의 포인터.
f
가중 계수. 「주의」를 참조할것.
g
가중 계수. 「주의」를 참조할것.

반환값

중심 좌표의 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 상에 있다.
  • If (f>=0 && g>=0 && 1-f-g==0)의 경우, 점은 직선 V2V3 상에 있다.

중심 좌표는, 일반적인 좌표의 형식이다. 여기서 중심 좌표를 사용할때는, 단지 좌표계의 변경을 나타내고 있다. 데카르트 좌표로 진정한 것은, 중심 좌표에서도 진이다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2BaryCentric 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXVec2CCW

D3DXVec2CCW 함수는, 2 개의 2D 벡터의 외적을 산출해 z 컴퍼넌트를 돌려준다.

float D3DXVec2CCW(
  const D3DXVECTOR2* pV1,
  const D3DXVECTOR2* pV2
);

파라미터

pV1
소스의 D3DXVECTOR2 구조체에의 포인터.
pV2
소스의 D3DXVECTOR2 구조체에의 포인터.

반환값

z 컴퍼넌트.

주의

이 함수는, ((x1, y1, 0) cross (x2, y2, 0)); 식 또는 다음의 코드에 근거해 외적을 산출하는 것으로, z 컴퍼넌트를 판정한다.

pV1->x * pV2->y - pV1->y * pV2->x

z 컴퍼넌트의 값이 정의 경우, V2 는 V1 에 대해서 반시계회전이다. 이 정보는, 뒷면의 컬링(Culling)로 도움이 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec2Dot


D3DXVec2Dot

D3DXVec2Dot 함수는, 2 개의 2D 벡터의 내적을 산출한다.

float D3DXVec2Dot(
  const D3DXVECTOR2* pV1,
  const D3DXVECTOR2* pV2
);

파라미터

pV1
소스의 D3DXVECTOR2 구조체에의 포인터.
pV2
소스의 D3DXVECTOR2 구조체에의 포인터.

반환값

내적.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec2CCW


D3DXVec2Hermite

D3DXVec2Hermite 함수는, 지정된 2D 벡터를 사용해 엘 미트의 스플라인 보간을 실행한다.

D3DXVECTOR2* D3DXVec2Hermite(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV1,
  const D3DXVECTOR2* pT1,
  const D3DXVECTOR2* pV2,
  const D3DXVECTOR2* pT2,
  float s
);

파라미터

pOut
연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV1
위치 벡터의 소스 D3DXVECTOR2 구조체에의 포인터.
pT1
접선 벡터의 소스 D3DXVECTOR2 구조체에의 포인터.
pV2
위치 벡터의 소스 D3DXVECTOR2 구조체에의 포인터.
pT2
접선 벡터의 소스 D3DXVECTOR2 구조체에의 포인터.
s
가중 계수. 「주의」를 참조할것.

반환값

엘 미트의 스플라인 보간의 결과인 D3DXVECTOR2 구조체에의 포인터.

주의

D3DXVec2Hermite 함수는, 엘 미트의 스플라인 보간을 사용해 (positionA, tangentA)로부터 (positionB, tangentB)에 보간 한다. 이 함수는, 위치 V1 와 접선 T1 의 사이 (s 가 0 의 경우)와 위치 V2 와 접선 T2 의 사이 (s 가 1 의 경우)를 보간 한다.

엘 미트의 스플라인은, 곡선이 모든 제어점을 통과하므로, 애니메이션을 제어하는 경우에 유용하다. 또, 위치나 접선이 세그먼트(segment)의 종점에서 명시적으로 지정되고 있으므로, 기점과 접선이 최종 세그먼트(segment)의 종점의 값에 일치하도록(듯이) 하고 있는 한, C2 연속 곡선을 간단하게 생성 할 수 있다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2Hermite 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXVec2Length

D3DXVec2Length 함수는, 지정된 2D 벡터의 길이를 돌려준다.

float D3DXVec2Length(
  const D3DXVECTOR2* pV
);

파라미터

pV
소스의 D3DXVECTOR2 구조체에의 포인터.

반환값

벡터의 길이.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec2LengthSq


D3DXVec2LengthSq

D3DXVec2LengthSq 함수는, 지정된 2D 벡터의 길이의 2 승을 돌려준다.

float D3DXVec2LengthSq(
  const D3DXVECTOR2* pV
);

파라미터

pV
소스의 D3DXVECTOR2 구조체에의 포인터.

반환값

벡터의 길이의 2 승.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec2Length


D3DXVec2Lerp

D3DXVec2Lerp 함수는, 2 개의 2D 벡터간에 선형 보간을 실행한다.

D3DXVECTOR2* D3DXVec2Lerp(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV1,
  const D3DXVECTOR2* pV2,
  float s
);

파라미터

pOut
연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV1
소스의 D3DXVECTOR2 구조체에의 포인터.
pV2
소스의 D3DXVECTOR2 구조체에의 포인터.
s
이 값은, 지정된 2 개의 벡터간을 선형 보간 한다.

반환값

선형 보간의 결과인 D3DXVECTOR2 구조체에의 포인터.

주의

이 함수는, V1 + s(V2-V1) 식을 기본으로 선형 보간을 실행한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2Lerp 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXVec2Maximize

D3DXVec2Maximize 함수는, 지정된 2 개의 2D 벡터의 최대의 컴퍼넌트로부터 생성 한 2D 벡터를 돌려준다.

D3DXVECTOR2* D3DXVec2Maximize(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV1,
  const D3DXVECTOR2* pV2
);

파라미터

pOut
연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV1
소스의 D3DXVECTOR2 구조체에의 포인터.
pV2
소스의 D3DXVECTOR2 구조체에의 포인터.

반환값

지정된 2 개의 벡터의 최대의 컴퍼넌트로부터 생성 한 D3DXVECTOR2 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2Maximize 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec2Minimize


D3DXVec2Minimize

D3DXVec2Minimize 함수는, 지정된 2 개의 2D 벡터의 최소의 컴퍼넌트로부터 생성 한 2D 벡터를 돌려준다.

D3DXVECTOR2* D3DXVec2Minimize(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV1,
  const D3DXVECTOR2* pV2
);

파라미터

pOut
연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV1
소스의 D3DXVECTOR2 구조체에의 포인터.
pV2
소스의 D3DXVECTOR2 구조체에의 포인터.

반환값

지정된 2 개의 벡터의 최소의 컴퍼넌트로부터 생성 한 D3DXVECTOR2 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2Minimize 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec2Maximize


D3DXVec2Normalize

D3DXVec2Normalize 함수는, 지정된 2D 벡터를 정규화한 벡터를 돌려준다.

D3DXVECTOR2* D3DXVec2Normalize(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV
);

파라미터

pOut
연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV
소스의 D3DXVECTOR2 구조체에의 포인터.

반환값

지정된 벡터를 정규화한 D3DXVECTOR2 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2Normalize 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXVec2Scale

D3DXVec2Scale 함수는, 지정된 2D 벡터를 스케일링 한다.

D3DXVECTOR2* D3DXVec2Scale(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV,
  float s
);

파라미터

pOut
연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV
소스의 D3DXVECTOR2 구조체에의 포인터.
s
스케일링값.

반환값

스케일링 된 벡터인 D3DXVECTOR2 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2Scale 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec2Add ,D3DXVec2Subtract


D3DXVec2Subtract

D3DXVec2Subtract 함수는, 2 개의 2D 벡터를 뺄셈 한다.

D3DXVECTOR2* D3DXVec2Subtract(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV1,
  const D3DXVECTOR2* pV2
);

파라미터

pOut
연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV1
소스의 D3DXVECTOR2 구조체에의 포인터.
pV2
소스의 D3DXVECTOR2 구조체에의 포인터.

반환값

2 개의 벡터의 차분인 D3DXVECTOR2 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2Subtract 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec2Add ,D3DXVec2Scale


D3DXVec2Transform

D3DXVec2Transform 함수는, 지정된 행렬에 의해 2D 벡터를 변환한다.

D3DXVECTOR4* D3DXVec2Transform(
  D3DXVECTOR4** pOut,
  const D3DXVECTOR2* pV,
  const D3DXMATRIX* pM
);

파라미터

pOut
연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV
소스의 D3DXVECTOR2 구조체에의 포인터.
pM
소스의 D3DXMATRIX 구조체에의 포인터.

반환값

변환된 벡터의 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수는, 지정된 벡터 pV (x, y, 0, 1)가 지정된 행렬 pM 에 의해 변환한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2Transform 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec2TransformCoord ,D3DXVec2TransformNormal


D3DXVec2TransformCoord

D3DXVec2TransformCoord 함수는, 지정된 행렬에 의해 2D 벡터를 변환해, 그 결과를 w = 1 에 투영 한다.

D3DXVECTOR2* D3DXVec2TransformCoord(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV,
  const D3DXMATRIX* pM
);

파라미터

pOut
연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV
소스의 D3DXVECTOR2 구조체에의 포인터.
pM
소스의 D3DXMATRIX 구조체에의 포인터.

반환값

변환된 벡터인 D3DXVECTOR2 구조체에의 포인터.

주의

이 함수는, 지정된 벡터 pV (x, y, 0, 1)가 지정된 행렬에 의해 pM 변환해, 그 결과를 w=1 에 투영 한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2TransformCoord 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec2Transform ,D3DXVec2TransformNormal


D3DXVec2TransformNormal

D3DXVec2TransformNormal 함수는, 지정된 행렬에 의해 2D 벡터 법선을 변환한다.

D3DXVECTOR2* D3DXVec2TransformNormal(
  D3DXVECTOR2* pOut,
  const D3DXVECTOR2* pV,
  const D3DXMATRIX* pM
);

파라미터

pOut
연산 결과인 D3DXVECTOR2 구조체에의 포인터.
pV
소스의 D3DXVECTOR2 구조체에의 포인터.
pM
소스의 D3DXMATRIX 구조체에의 포인터.

반환값

변환된 벡터인 D3DXVECTOR2 구조체에의 포인터.

주의

이 함수는, 지정된 벡터 pV 의 벡터 법선 (x, y, 0, 0)이 지정된 행렬 pM 에 의해 변환한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec2TransformNormal 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec2Transform ,D3DXVec2TransformCoord


D3DXVec3Add

D3DXVec3Add 함수는, 2 개의 3D 벡터를 추가한다.

D3DXVECTOR3* D3DXVec3Add(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pV2
);

파라미터

pOut
연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV1
소스의 D3DXVECTOR3 구조체에의 포인터.
pV2
소스의 D3DXVECTOR3 구조체에의 포인터.

반환값

지정된 2 개의 3D 벡터의 합계인 D3DXVECTOR3 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3Add 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec3Subtract ,D3DXVec3Scale


D3DXVec3BaryCentric

D3DXVec3BaryCentric 함수는, 지정된 3D 벡터를 사용해 중심 좌표의 점을 돌려준다.

D3DXVECTOR3* D3DXVec3BaryCentric(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pV2,
  D3DXVECTOR3* pV3,
  float f,
  float g
);

파라미터

pOut
연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV1
소스의 D3DXVECTOR3 구조체에의 포인터.
pV2
소스의 D3DXVECTOR3 구조체에의 포인터.
pV3
소스의 D3DXVECTOR3 구조체에의 포인터.
f
가중 계수. 「주의」를 참조할것.
g
가중 계수. 「주의」를 참조할것.

반환값

중심 좌표의 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 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXVec3Cross

D3DXVec3Cross 함수는, 2 개의 3D 벡터의 외적을 산출한다.

D3DXVECTOR3* D3DXVec3Cross(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pV2
);

파라미터

pOut
연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV1
소스의 D3DXVECTOR3 구조체에의 포인터.
pV2
소스의 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 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec3Dot


D3DXVec3Dot

D3DXVec3Dot 함수는, 2 개의 3D 벡터의 내적을 산출한다.

float D3DXVec3Dot(
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pV2
);

파라미터

pV1
소스의 D3DXVECTOR3 구조체에의 포인터.
pV2
소스의 D3DXVECTOR3 구조체에의 포인터.

반환값

내적.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec3Cross


D3DXVec3Hermite

D3DXVec3Hermite 함수는, 지정된 3D 벡터를 사용해 엘 미트의 스플라인 보간을 실행한다.

D3DXVECTOR3* D3DXVec3Hermite(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pT1,
  const D3DXVECTOR3* pV2,
  const D3DXVECTOR3* pT2,
  float s
);

파라미터

pOut
연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV1
위치 벡터의 소스 D3DXVECTOR4 구조체에의 포인터.
pT1
접선 벡터의 소스 D3DXVECTOR4 구조체에의 포인터.
pV2
위치 벡터의 소스 D3DXVECTOR4 구조체에의 포인터.
pT2
접선 벡터의 소스 D3DXVECTOR4 구조체에의 포인터.
s
가중 계수. 「주의」를 참조할것.

반환값

엘 미트의 스플라인 보간의 결과인 D3DXVECTOR3 구조체에의 포인터.

주의

D3DXVec3Hermite 함수는, 엘 미트의 스플라인 보간을 사용해 (positionA, tangentA)로부터 (positionB, tangentB)에 보간 한다. 이 함수는, 위치 V1 와 접선 T1 의 사이 (s 가 0 의 경우)와 위치 V2 와 접선 T2 의 사이 (s 가 1 의 경우)를 보간 한다.

엘 미트의 스플라인은, 곡선이 모든 제어점을 통과하므로, 애니메이션을 제어하는 경우에 유용하다. 또, 위치나 접선이 세그먼트(segment)의 종점에서 명시적으로 지정되고 있으므로, 기점과 접선이 최종 세그먼트(segment)의 종점의 값에 일치하도록(듯이) 하고 있는 한, C2 연속 곡선을 간단하게 생성 할 수 있다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3Hermite 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXVec3Length

D3DXVec3Length 함수는, 지정된 3D 벡터의 길이를 돌려준다.

float D3DXVec3Length(
  const D3DXVECTOR3* pV
);

파라미터

pV
소스의 D3DXVECTOR3 구조체에의 포인터.

반환값

벡터의 길이.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec3LengthSq


D3DXVec3LengthSq

D3DXVec3LengthSq 함수는, 지정된 3D 벡터의 길이의 2 승을 돌려준다.

float D3DXVec3LengthSq(
  const D3DXVECTOR3* pV
);

파라미터

pV
소스의 D3DXVECTOR3 구조체에의 포인터.

반환값

벡터의 길이의 2 승.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec3Length


D3DXVec3Lerp

D3DXVec3Lerp 함수는, 2 개의 3D 벡터간에 선형 보간을 실행한다.

D3DXVECTOR3* D3DXVec3Lerp(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pV2,
  float s
);

파라미터

pOut
연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV1
소스의 D3DXVECTOR3 구조체에의 포인터.
pV2
소스의 D3DXVECTOR3 구조체에의 포인터.
s
이 값은, 지정된 2 개의 벡터간을 선형 보간 한다.

반환값

선형 보간의 결과인 D3DXVECTOR3 구조체에의 포인터.

주의

이 함수는, V1 + s(V2-V1) 식에 근거해 선형 보간을 실행한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3Lerp 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXVec3Maximize

D3DXVec3Maximize 함수는, 지정된 2 개의 3D 벡터의 최대의 컴퍼넌트로부터 생성 한 3D 벡터를 돌려준다.

D3DXVECTOR3* D3DXVec3Maximize(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pV2
);

파라미터

pOut
연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV1
소스의 D3DXVECTOR3 구조체에의 포인터.
pV2
소스의 D3DXVECTOR3 구조체에의 포인터.

반환값

지정된 2 개의 벡터의 최대의 컴퍼넌트로부터 생성 된 D3DXVECTOR3 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3Maximize 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec3Minimize


D3DXVec3Minimize

D3DXVec3Minimize 함수는, 지정된 2 개의 3D 벡터의 최소 컴퍼넌트로부터 생성 한 3D 벡터를 돌려준다.

D3DXVECTOR3* D3DXVec3Minimize(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pV2
);

파라미터

pOut
연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV1
소스의 D3DXVECTOR3 구조체에의 포인터.
pV2
소스의 D3DXVECTOR3 구조체에의 포인터.

반환값

지정된 2 개의 벡터의 최소 컴퍼넌트로부터 생성 된 D3DXVECTOR3 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3Minimize 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec3Maximize


D3DXVec3Normalize

D3DXVec3Normalize 함수는, 지정된 3D 벡터를 정규화한 벡터를 돌려준다.

D3DXVECTOR3* D3DXVec3Normalize(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV
);

파라미터

pOut
연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV
소스의 D3DXVECTOR3 구조체에의 포인터.

반환값

지정된 벡터를 정규화한 D3DXVECTOR3 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3Normalize 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXVec3Scale

D3DXVec3Scale 함수는, 지정된 3D 벡터를 스케일링 한다.

D3DXVECTOR3* D3DXVec3Scale(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV,
  float s
);

파라미터

pOut
연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV
소스의 D3DXVECTOR3 구조체에의 포인터.
s
스케일링값.

반환값

스케일링 된 벡터인 D3DXVECTOR3 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3Scale 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec3Add ,D3DXVec3Subtract


D3DXVec3Subtract

D3DXVec3Subtract 함수는, 2 개의 3D 벡터를 뺄셈 한다.

D3DXVECTOR3* D3DXVec3Subtract(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV1,
  const D3DXVECTOR3* pV2
);

파라미터

pOut
연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV1
소스의 D3DXVECTOR3 구조체에의 포인터.
pV2
소스의 D3DXVECTOR3 구조체에의 포인터.

반환값

2 개의 벡터의 차분인 D3DXVECTOR3 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3Subtract 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec3Add ,D3DXVec3Scale


D3DXVec3Transform

D3DXVec3Transform 함수는, 지정된 행렬에 의해 3D 벡터를 변환한다.

D3DXVECTOR4* D3DXVec3Transform(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR3* pV,
  const D3DXMATRIX* pM
);

파라미터

pOut
연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV
소스의 D3DXVECTOR3 구조체에의 포인터.
pM
소스의 D3DXMATRIX 구조체에의 포인터.

반환값

변환된 벡터의 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수는, 지정된 벡터 pV (x, y, z, 1)가 지정된 행렬 pM 에 의해 변환한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3Transform 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec3TransformCoord ,D3DXVec3TransformNormal


D3DXVec3TransformCoord

D3DXVec3TransformCoord 함수는, 지정된 행렬에 의해 3D 벡터를 변환해, 그 결과를 w = 1 에 투영 한다.

D3DXVECTOR3* D3DXVec3TransformCoord(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV,
  const D3DXMATRIX* pM
);

파라미터

pOut
연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV
소스의 D3DXVECTOR3 구조체에의 포인터.
pM
소스의 D3DXMATRIX 구조체에의 포인터.

반환값

변환된 벡터인 D3DXVECTOR3 구조체에의 포인터.

주의

이 함수는, 지정된 벡터 pV (x, y, z, 1)가 지정된 행렬에 의해 pM 변환해, 그 결과를 w=1 에 투영 한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3TransformCoord 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec3Transform ,D3DXVec3TransformNormal


D3DXVec3TransformNormal

D3DXVec3TransformNormal 함수는, 지정된 행렬에 의해 3D 벡터 법선을 변환한다.

D3DXVECTOR3* D3DXVec3TransformNormal(
  D3DXVECTOR3* pOut,
  const D3DXVECTOR3* pV,
  const D3DXMATRIX* pM
);

파라미터

pOut
연산 결과인 D3DXVECTOR3 구조체에의 포인터.
pV
소스의 D3DXVECTOR3 구조체에의 포인터.
pM
소스의 D3DXMATRIX 구조체에의 포인터.

반환값

변환된 벡터인 D3DXVECTOR3 구조체에의 포인터.

주의

이 함수는, 지정된 벡터 pV 의 벡터 법선 (x, y, z, 0)이 지정된 행렬 pM 에 의해 변환한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec3TransformNormal 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXVec4Add

D3DXVec4Add 함수는, 2 개의 4D 벡터를 덧셈 한다.

D3DXVECTOR4* D3DXVec4Add(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV1,
  const D3DXVECTOR4* pV2
);

파라미터

pOut
연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV1
소스의 D3DXVECTOR4 구조체에의 포인터.
pV2
소스의 D3DXVECTOR4 구조체에의 포인터.

반환값

지정된 2 개의 벡터의 합계인 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec4Add 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec4Subtract ,D3DXVec4Scale


D3DXVec4BaryCentric

D3DXVec4BaryCentric 함수는, 지정된 4D 벡터를 사용해 중심 좌표의 점을 돌려준다.

D3DXVECTOR4* D3DXVec4BaryCentric(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV1,
  const D3DXVECTOR4* pV2,
  const D3DXVECTOR4* pV3,
  float f,
  float g
);

파라미터

pOut
연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV1
소스의 D3DXVECTOR4 구조체에의 포인터.
pV2
소스의 D3DXVECTOR4 구조체에의 포인터.
pV3
소스의 D3DXVECTOR4 구조체에의 포인터.
f
가중 계수. 「주의」를 참조할것.
g
가중 계수. 「주의」를 참조할것.

반환값

중심 좌표의 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 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXVec4Cross

D3DXVec4Cross 함수는, 4D 로 외적을 산출한다.

D3DXVECTOR4* D3DXVec4Cross(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV1,
  const D3DXVECTOR4* pV2,
  const D3DXVECTOR4* pV3
);

파라미터

pOut
연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV1
소스의 D3DXVECTOR4 구조체에의 포인터.
pV2
소스의 D3DXVECTOR4 구조체에의 포인터.
pV3
소스의 D3DXVECTOR4 구조체에의 포인터.

반환값

외적인 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec4Cross 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec4Dot


D3DXVec4Dot

D3DXVec4Dot 함수는, 2개의 4D 벡터의 내적을 산출한다.

float D3DXVec4Dot(
  const D3DXVECTOR4* pV1,
  const D3DXVECTOR4* pV2
);

파라미터

pV1
소스의 D3DXVECTOR4 구조체에의 포인터.
pV2
소스의 D3DXVECTOR4 구조체에의 포인터.

반환값

내적.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec4Cross


D3DXVec4Hermite

D3DXVec4Hermite 함수는, 지정된 4D 벡터를 사용해, 엘 미트의 스플라인 보간을 실행한다.

D3DXVECTOR4* D3DXVec4Hermite(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV1,
  const D3DXVECTOR4* pT1,
  const D3DXVECTOR4* pV2,
  const D3DXVECTOR4* pT2,
  float s
);

파라미터

pOut
연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV1
위치 벡터의 소스 D3DXVECTOR4 구조체에의 포인터.
pT1
접선 벡터의 소스 D3DXVECTOR4 구조체에의 포인터.
pV2
위치 벡터의 소스 D3DXVECTOR4 구조체에의 포인터.
pT2
접선 벡터의 소스 D3DXVECTOR4 구조체에의 포인터.
s
가중 계수. 「주의」를 참조할것.

반환값

엘 미트의 스플라인 보간의 결과인 D3DXVECTOR4 구조체에의 포인터.

주의

D3DXVec4Hermite 함수는, 엘 미트의 스플라인 보간을 사용해 (positionA, tangentA)로부터 (positionB, tangentB)에 보간 한다. 이 함수는, 위치 V1 와 접선 T1 의 사이 (s 가 0 의 경우)와 위치 V2 와 접선 T2 의 사이 (s 가 1 의 경우)를 보간 한다.

엘 미트의 스플라인은, 곡선이 모든 제어점을 통과하므로, 애니메이션을 제어하는 경우에 유용하다. 또, 위치나 접선이 세그먼트(segment)의 종점에서 명시적으로 지정되고 있으므로, 기점과 접선이 최종 세그먼트(segment)의 종점의 값에 일치하도록(듯이) 하고 있는 한, C2 연속 곡선을 간단하게 생성 할 수 있다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec4Hermite 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXVec4Length

D3DXVec4Length 함수는, 지정된 4D 벡터의 길이를 돌려준다.

float D3DXVec4Length(
  const D3DXVECTOR4* pV
);

파라미터

pV
소스의 D3DXVECTOR4 구조체에의 포인터.

반환값

벡터의 길이.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec4LengthSq


D3DXVec4LengthSq

D3DXVec4LengthSq 함수는, 지정된 4D 벡터의 길이의 2 승을 돌려준다.

float D3DXVec4LengthSq(
  const D3DXVECTOR4* pV
);

파라미터

pV
소스의 D3DXVECTOR4 구조체에의 포인터.

반환값

벡터의 길이의 2 승.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec4Length


D3DXVec4Lerp

D3DXVec4Lerp 함수는, 2 개의 4D 벡터간을 선형 보간 한다.

D3DXVECTOR4* D3DXVec4Lerp(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV1,
  const D3DXVECTOR4* pV2,
  float s
);

파라미터

pOut
연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV1
소스의 D3DXVECTOR4 구조체에의 포인터.
pV2
소스의 D3DXVECTOR4 구조체에의 포인터.
s
이 값은, 지정된 2 개의 벡터간을 선형 보간 한다.

반환값

선형 보간의 결과인 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수는, V1 + s(V2-V1) 식을 기본으로 선형 보간을 실행한다.

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec4Lerp 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXVec4Maximize

D3DXVec4Maximize 함수는, 지정된 2 개의 4D 벡터의 최대의 컴퍼넌트로부터 생성 한 4D 벡터를 돌려준다.

D3DXVECTOR4* D3DXVec4Maximize(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV1,
  const D3DXVECTOR4* pV2
);

파라미터

pOut
연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV1
소스의 D3DXVECTOR4 구조체에의 포인터.
pV2
소스의 D3DXVECTOR4 구조체에의 포인터.

반환값

지정된 2 개의 벡터의 최대의 컴퍼넌트로부터 생성 한 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec4Maximize 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec4Minimize


D3DXVec4Minimize

D3DXVec4Minimize 함수는, 지정된 2 개의 4D 벡터의 최소의 컴퍼넌트로부터 생성 한 4D 벡터를 돌려준다.

D3DXVECTOR4* D3DXVec4Minimize(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV1,
  const D3DXVECTOR4* pV2
);

파라미터

pOut
연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV1
소스의 D3DXVECTOR4 구조체에의 포인터.
pV2
소스의 D3DXVECTOR4 구조체에의 포인터.

반환값

지정된 2 개의 벡터의 최소의 컴퍼넌트로부터 생성 한 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec4Minimize 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec4Maximize


D3DXVec4Normalize

D3DXVec4Normalize 함수는, 지정된 4D 벡터를 정규화한 벡터를 돌려준다.

D3DXVECTOR4* D3DXVec4Normalize(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV
);

파라미터

pOut
연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV
소스의 D3DXVECTOR4 구조체에의 포인터.

반환값

지정된 벡터를 정규화한 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec4Normalize 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXVec4Scale

D3DXVec4Scale 함수는, 지정된 4D 벡터를 스케일링 한다.

D3DXVECTOR4* D3DXVec4Scale(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV,
  float s
);

파라미터

pOut
연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV
소스의 D3DXVECTOR4 구조체에의 포인터.
s
스케일링값.

반환값

스케일링 된 벡터인 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec4Scale 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec4Add ,D3DXVec4Subtract


D3DXVec4Subtract

D3DXVec4Subtract 함수는, 2 개의 4D 벡터를 뺄셈 한다.

D3DXVECTOR4* D3DXVec4Subtract(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV1,
  const D3DXVECTOR4* pV2
);

파라미터

pOut
연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV1
소스의 D3DXVECTOR4 구조체에의 포인터.
pV2
소스의 D3DXVECTOR4 구조체에의 포인터.

반환값

2 개의 벡터의 차분인 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec4Subtract 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXVec3Add ,D3DXVec3Scale


D3DXVec4Transform

D3DXVec4Transform 함수는, 지정된 행렬에 의해 4D 벡터를 변환한다.

D3DXVECTOR4* D3DXVec4Transform(
  D3DXVECTOR4* pOut,
  const D3DXVECTOR4* pV,
  const D3DXMATRIX* pM
);

파라미터

pOut
연산 결과인 D3DXVECTOR4 구조체에의 포인터.
pV
소스의 D3DXVECTOR4 구조체에의 포인터.
pM
소스의 D3DXMATRIX 구조체에의 포인터.

반환값

변환된 4D 벡터의 D3DXVECTOR4 구조체에의 포인터.

주의

이 함수의 반환값은, pOut 파라미터의 반환값과 같다. 이와 같이,D3DXVec4Transform 함수를 다른 함수의 파라미터로서 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


형상 드로잉(Drawing) 함수

Direct3DX 유틸리티 라이브러리에 의해 제공되고 있는 3D 형상 드로잉(Drawing) 어플리케이션 프로그래밍 인터페이스 (API)에서는, 간단한 도형의 형태를 드로잉(Drawing)하기 위한 함수가 제공되고 있다.

여기에서는, 다음의 Direct3DX 글로벌 함수에 대해 설명한다.

  • D3DXCreateBox
  • D3DXCreateCylinder
  • D3DXCreatePolygon
  • D3DXCreateSphere
  • D3DXCreateTeapot
  • D3DXCreateTorus

모든 형태는, 버텍스 버퍼로서 돌려주어진다. 형태가 버텍스 버퍼이므로, 유연한 버텍스 포맷 타입은, 버텍스 버퍼 자체를 문의하는 것으로 찾아낼 수가 있다. 각 버텍스 버퍼에는 버텍스가 설정되어 있어 그것들은 모두 프리미티브를 삼각형 리스트로서 드로잉(Drawing) 할 경우에 사용할 수 있다.

상세한 것에 대하여는, 「유연한 버텍스 포맷 플래그」를 참조할것.


D3DXCreateBox

D3DXCreateBox 함수는, 지정된 넓이의 박스 (입방체)를 생성 한다.

HRESULT D3DXCreateBox(
  LPDIRECT3DDEVICE7 pDevice,
  float width,
  float height,
  float depth,
  DWORD numTexCoords,
  ID3DXSimpleShape** ppShape
);

파라미터

pDevice
디바이스의 IDirect3DDevice7 인터페이스에의 포인터.
width
x 축방향의 박스의 폭.
height
y 축방향의 박스의 높이.
depth
z 축방향의 박스의 깊이.
numTexCoords
출력 버텍스 버퍼의 목적의 텍스쳐 좌표수. 디폴트값은 1 이다. 이 파라미터에는,D3DX_DEFAULT 를 입력 가능하다.
ppShape
출력 버텍스 버퍼의 ID3DXSimpleShape 인터페이스에의 포인터의 주소.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

CLASS_E_NOAGGREGATION
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDVERTEXFORMAT
D3DERR_INVALIDVERTEXTYPE
D3DERR_VBUF_CREATE_FAILED
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_WASSTILLDRAWING

주의

이 함수는, 다음에 어플리케이션에 의해 드로잉(Drawing) 하거나 조작할 경우에 사용할 수 있는 버텍스 버퍼를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxshapes.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXCreateCylinder ,D3DXCreatePolygon ,D3DXCreateSphere ,D3DXCreateTeapot ,D3DXCreateTorus


D3DXCreateCylinder

D3DXCreateCylinder 함수는, 지정된 넓이의 원기둥(실린더)를 생성 한다.

HRESULT D3DXCreateCylinder(
  LPDIRECT3DDEVICE7 pDevice,
  float baseRadius,
  float topRadius,
  float height,
  DWORD numSlices,
  DWORD numStacks,
  DWORD numTexCoords,
  ID3DXSimpleShape** ppShape
);

파라미터

pDevice
디바이스의 IDirect3DDevice7 인터페이스에의 포인터.
baseRadius
원기둥(실린더)의 저면의 반경. 디폴트값은, 1.0f 이다. 이 파라미터는, 0.0f 이상이 아니면 안된다.
topRadius
원기둥(실린더)의 표면의 반경. 디폴트값은, 1.0f 이다. 이 파라미터는, 0.0f 이상이 아니면 안된다.
height
원기둥(실린더)의 높이. 디폴트값은, 1.0f 이다. 이 파라미터는, 0.0f 이상이 아니면 안된다.
numSlices
주축을 회전축으로 한 슬라이스의 수. 디폴트값은 8 이다. 이 파라미터에는, D3DX_DEFAULT 를 입력 가능하다.
numStacks
주축에 따른 스택수. 디폴트값은 8 이다. 이 파라미터에는, D3DX_DEFAULT 를 입력 가능하다.
numTexCoords
출력 버텍스 버퍼의 목적의 텍스쳐 좌표수. 디폴트값은 1 이다. 이 파라미터에는, D3DX_DEFAULT 를 입력 가능하다.
ppShape
출력 버텍스 버퍼의 ID3DXSimpleShape 인터페이스에의 포인터의 주소.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

CLASS_E_NOAGGREGATION
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDVERTEXFORMAT
D3DERR_INVALIDVERTEXTYPE
D3DERR_VBUF_CREATE_FAILED
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_WASSTILLDRAWING

주의

이 함수는, 다음에 어플리케이션에 의해 드로잉(Drawing) 하거나 조작할 경우에 사용할 수 있는 버텍스 버퍼를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxshapes.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXCreateBox ,D3DXCreatePolygon ,D3DXCreateSphere ,D3DXCreateTeapot ,D3DXCreateTorus


D3DXCreatePolygon

D3DXCreatePolygon 함수는, n 옆의 다각형을 생성 한다.

HRESULT D3DXCreatePolygon(
  LPDIRECT3DDEVICE7 pDevice,
  float sideSize,
  DWORD numSides,
  DWORD numTexCoords,
  ID3DXSimpleShape** ppShape
);

파라미터

pDevice
디바이스의 IDirect3DDevice7 인터페이스에의 포인터.
sideSize
옆의 길이.
numSides
옆의 수.
numTexCoords
출력 버텍스 버퍼의 목적의 텍스쳐 좌표수. 디폴트값은 1 이다. 이 파라미터에는, D3DX_DEFAULT 를 입력 가능하다.
ppShape
출력 버텍스 버퍼의 ID3DXSimpleShape 인터페이스에의 포인터의 주소.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

CLASS_E_NOAGGREGATION
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDVERTEXFORMAT
D3DERR_INVALIDVERTEXTYPE
D3DERR_VBUF_CREATE_FAILED
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_WASSTILLDRAWING

주의

이 함수는, 다음에 어플리케이션에 의해 드로잉(Drawing) 하거나 조작할 경우에 사용할 수 있는 버텍스 버퍼를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxshapes.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXCreateBox ,D3DXCreateCylinder ,D3DXCreateSphere ,D3DXCreateTeapot ,D3DXCreateTorus


D3DXCreateSphere

D3DXCreateSphere 함수는, 지정된 넓이의 구(공)을 생성 한다.

HRESULT D3DXCreateSphere(
  LPDIRECT3DDEVICE7 pDevice,
  float radius,
  DWORD numSlices,
  DWORD numStacks,
  DWORD numTexCoords,
  ID3DXSimpleShape** ppShape
);

파라미터

pDevice
디바이스의 IDirect3DDevice7 인터페이스에의 포인터.
radius
구(공)의 반경. 디폴트값은, 1.0f 이다. 이 파라미터는, 0.0f 이상이 아니면 안된다.
numSlices
주축을 회전축으로 한 슬라이스의 수. 디폴트값은 8 이다. 이 파라미터에는, D3DX_DEFAULT 를 입력 가능하다.
numStacks
주축에 따른 스택수. 디폴트값은 8 이다. 이 파라미터에는, D3DX_DEFAULT 를 입력 가능하다.
numTexCoords
출력 버텍스 버퍼의 목적의 텍스쳐 좌표수. 디폴트값은 1 이다. 이 파라미터에는, D3DX_DEFAULT 를 입력 가능하다.
ppShape
출력 버텍스 버퍼의 ID3DXSimpleShape 인터페이스에의 포인터의 주소.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

CLASS_E_NOAGGREGATION
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDVERTEXFORMAT
D3DERR_INVALIDVERTEXTYPE
D3DERR_VBUF_CREATE_FAILED
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_WASSTILLDRAWING

주의

이 함수는, 다음에 어플리케이션에 의해 드로잉(Drawing) 하거나 조작할 경우에 사용할 수 있는 버텍스 버퍼를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxshapes.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXCreateBox ,D3DXCreateCylinder ,D3DXCreatePolygon ,D3DXCreateTeapot ,D3DXCreateTorus


D3DXCreateTeapot

D3DXCreateTeapot 함수는, 티폿(주전자)를 생성 한다.

HRESULT D3DXCreateTeapot(
  LPDIRECT3DDEVICE7 pDevice,
  DWORD numTexCoords,
  ID3DXSimpleShape** ppShape
);

파라미터

pDevice
디바이스의 IDirect3DDevice7 인터페이스에의 포인터.
numTexCoords
출력 버텍스 버퍼의 목적의 텍스쳐 좌표수. 디폴트값은 1 이다. 이 파라미터에는, D3DX_DEFAULT 를 입력 가능하다.
ppShape
출력 버텍스 버퍼의 ID3DXSimpleShape 인터페이스에의 포인터의 주소.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

CLASS_E_NOAGGREGATION
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDVERTEXFORMAT
D3DERR_INVALIDVERTEXTYPE
D3DERR_VBUF_CREATE_FAILED
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_WASSTILLDRAWING

주의

이 함수는, 다음에 어플리케이션에 의해 드로잉(Drawing) 하거나 조작할 경우에 사용할 수 있는 버텍스 버퍼를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxshapes.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXCreateBox ,D3DXCreateCylinder ,D3DXCreatePolygon ,D3DXCreateSphere ,D3DXCreateTorus


D3DXCreateTorus

D3DXCreateTorus 함수는, 지정된 넓이의 원환체를 생성 한다.

HRESULT D3DXCreateTorus(
  LPDIRECT3DDEVICE7 pDevice,
  float innerRadius,
  float outerRadius,
  DWORD numSides,
  DWORD numRings,
  DWORD numTexCoords,
  ID3DXSimpleShape** ppShape
);

파라미터

pDevice
디바이스의 IDirect3DDevice7 인터페이스에의 포인터.
innerRadius
원환체의 내부의 반경. 디폴트값은, 1.0f 이다. 이 파라미터는, 0.0f 이상이 아니면 안된다.
outerRadius
원환체의 외부의 반경. 디폴트값은, 1.0f 이다. 이 파라미터는, 0.0f 이상이 아니면 안된다.
numSides
횡단면의 옆의 수. 디폴트값은 8 이다. 이 파라미터에는, D3DX_DEFAULT 를 입력 가능하다.
numRings
원환체를 구성하는 환의 수. 디폴트값은 8 이다. 이 파라미터에는, D3DX_DEFAULT 를 입력 가능하다.
numTexCoords
출력 버텍스 버퍼의 목적의 텍스쳐 좌표수. 디폴트값은 1 이다. 이 파라미터에는, D3DX_DEFAULT 를 입력 가능하다.
ppShape
출력 버텍스 버퍼의 ID3DXSimpleShape 인터페이스에의 포인터의 주소.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

CLASS_E_NOAGGREGATION
D3DERR_INVALIDPRIMITIVETYPE
D3DERR_INVALIDRAMPTEXTURE
D3DERR_INVALIDVERTEXFORMAT
D3DERR_INVALIDVERTEXTYPE
D3DERR_VBUF_CREATE_FAILED
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_WASSTILLDRAWING

주의

D3DXCreateTorus 메소드는, 중심이 (0, 0, 0)로 축이 z 축방향의 도너츠형의 도형 (원환체)을 드로잉(Drawing) 한다. 이 원환체의 내부의 반경은 횡단면의 반경 (작은 (분)편의 반경), 외부의 반경은 중앙의 구멍의 반경이다.

이 함수는, 다음에 어플리케이션에 의해 드로잉(Drawing) 하거나 조작할 경우에 사용할 수 있는 버텍스 버퍼를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxshapes.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXCreateBox ,D3DXCreateCylinder ,D3DXCreatePolygon ,D3DXCreateSphere ,D3DXCreateTeapot


스프라이트 헬퍼-함수

Direct3DX 유틸리티 라이브러리에 의해 제공되고 있는 스프라이트 헬퍼-의 어플리케이션 프로그래밍 인터페이스 (API)는, 스프라이트 렌더링을 실시하는 함수를 제공하고 있다.

여기에서는, 다음의 Direct3DX 글로벌 함수에 대해 설명한다.

  • D3DXBuildSpriteTransform
  • D3DXDrawSpriteSimple
  • D3DXDrawSpriteTransform
  • D3DXDrawSprite3D
  • D3DXPrepareDeviceForSprite

메모 C++ 프로그래머는 Direct3DX 스프라이트 라이브러리의 디폴트값을 사용할 수 있다. 상세한 것에 대하여는, 각 함수의 설명을 참조할것.


D3DXBuildSpriteTransform

D3DXBuildSpriteTransform 함수는,-0. 5 로부터 +0. 5 까지의 중축을 가지는 직사각형으로부터, 화면의 특정의 RECT 구조체에의 변환에 대응하는 행렬을 생성 한다. 또, 그 RECT 구조체에 대해서 회전의 각도도 지정할 수 있다.

void D3DXBuildSpriteTransform(
  D3DXMATRIX* pMatrixTransform,
  const RECT* prectDest,
  float angleRad = 0.0f,
  const D3DXVECTOR2* pOffset
);

파라미터

pMatrixTransform
결과 행렬인 D3DXMATRIX 구조체에의 포인터. 이 행렬은,prectDest 파라미터,angleRad 파라미터,pOffset 파라미터에 의해 지정된 변환에 대응한 새로운 값이 설정되어 돌려주어진다.
prectDest
스프라이트의 타겟 직사각형에의 포인터로, 화면 좌표에서의 스프라이트의 위치를 나타낸다. 스프라이트는, 이 RECT 구조체를 둘러싸도록(듯이) 넓힐 수 있다.
angleRad
RECT 의 중심을 중심으로 한 회전의 각도로, 스프라이트의 회전 각도를 나타낸다. 회전은, 스프라이트의 중심을 중심으로서 적용된다. 그것은, 반시계회전에 라디안 단위로 지정한다. 도수로부터 라디안에 변환하는 방법에 대해서는, 「D3DXToRadian 」를 참조할것.
pOffset
회전의 중심으로서 사용하는 소스 RECT 의 중심으로부터의 오프셋(offset)를 정의한 D3DXVECTOR2 구조체에의 포인터. 이 파라미터는, 회전으로 스프라이트의 중심으로서 처리되는 스프라이트의 중심점으로부터의 오프셋(offset)를 나타낸다. 디폴트에 의해, NULL 값은 (0, 0) 벡터와 등가가 된다.

반환값

없음.

주의

D3DXBuildSpriteTransform 함수는,D3DXDrawSpriteTransform 함수를 사용하기 위한 헬퍼-함수로서 제공되고 있다.

다만, C 프로그래머는 angleRad 파라미터에 디폴트값을 지정할 수 없기 때문에 주의 해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxsprite.h 로 선언.
라이브러리 : d3dx.lib 을 사용.


D3DXDrawSpriteSimple

D3DXDrawSpriteSimple 함수는, 스프라이트를 Direct3D 디바이스에 렌더링 한다. 이 함수는,IDirect3DDevice7::BeginScene 함수를 호출한 다음에,IDirect3DDevice7::EndScene 함수를 호출하기 전에 호출할 필요가 있다.

HRESULT D3DXDrawSpriteSimple(
  LPDIRECTDRAWSURFACE7 pd3dTexture,
  LPDIRECT3DDEVICE7 pd3dDevice,
  const D3DXVECTOR3* ppointDest,
  float alpha = 1.0f,
  float scale = 1.0f,
  float angleRad = 0.0f,
  const D3DXVECTOR2* pOffset = NULL,
  const RECT *pSourceRect = NULL
);

파라미터

pd3dTexture
스프라이트의 소스 이미지로서 사용하는 표면을 나타내, 텍스쳐가 저장 되고 있는 표면의 IDirectDrawSurface7 인터페이스에의 포인터. 이것이 NULL 의 경우, 어플리케이션이 텍스쳐 스테이지 0 에 대해서 IDirect3DDevice7::SetTexture 를 이미 호출하고 있다고 보여진다.
pd3dDevice
IDirect3DDevice7 인터페이스에의 포인터. 스프라이트는, 이 디바이스에 대해서 렌더링 된다. 렌더링 상태는 이 디바이스에 대해서 셋업 되고 있다고 보여진다 ( 「D3DXPrepareDeviceForSprite 」를 참조할것).
ppointDest
D3DXVECTOR3 구조체에의 포인터. 스프라이트의 주시점. 이 벡터는, 스프라이트의 중심을 렌더링 하는 위치를 화면 좌표로 가리킨다. 벡터의 각 컴퍼넌트는, 스크린 공간내에 없으면 안 된다. 일반적으로, 벡터의 z 컴퍼넌트는 0 으로 설정된다. 그러나, z 버퍼를 사용하고 있는 어플리케이션은, 배경으로부터 전경에 렌더링 하지 않고, 임의의 값을 지정할 수가 있다.
alpha
스프라이트의 불투명도를 나타내, 스프라이트에 적용되는 알파값. 1.0 은 전체적으로 불투명하고, 0.0 은 전체적으로 투명한 것을 의미한다. 다만, 알파를 사용하는 경우는, 아티팩트 (인공물)가 렌더링 되지 않게 하기 위해서, 배경으로부터 전경에 렌더링 하는 것. 이 알파값은, 텍스쳐 이미지내에 존재하는 알파 (존재하는 경우)와 조합할 수 있다.
scale
렌더링 하는 이미지의 사이즈를 지정해, 소스 RECT 에 적용하는 한님의 스케일. 디폴트값은 1.0 이며, 스프라이트를 소스와 같은 폭과 높이로 렌더링 한다.
angleRad
RECT 의 중심을 중심으로 한 회전의 각도로, 스프라이트의 회전 각도를 나타낸다. 회전은, 스프라이트의 중심을 중심으로서 적용된다. 그것은, 반시계회전에 라디안 단위로 지정한다. 도수로부터 라디안에 변환하는 방법에 대해서는, 「D3DXToRadian 」를 참조할것.
pOffset
회전의 중심으로서 사용하는 소스 RECT 의 중심으로부터의 오프셋(offset)를 정의한 D3DXVECTOR2 구조체에의 포인터. 이 파라미터는,ppointDest 파라미터와 angleRad 파라미터로 스프라이트의 중심으로서 처리되는 스프라이트의 중심점으로부터의 오프셋(offset)를 나타낸다.
pSourceRect
소스 텍스쳐 중(안)에서 스프라이트에 사용하는 부분을 나타내는 RECT 구조체에의 포인터. 이 파라미터가 NULL 의 경우, 소스 이미지 전체가 스프라이트로 사용된다. 한편, 대신에 소스 이미지의 소직사각형을 지정할 수 있다. 소스 텍스쳐가 Direct3DX 를 사용해 생성 되고 있는 경우,RECT 구조체는 오리지날 이미지의 좌표로 지정한다. 그 때문에, Direct3D 현재 디바이스로 이미지가 기능하도록(듯이) Direct3DX 에 의해 행해진 신장이나 스케일링은 필요없다. 또, 미러링에 대해서는, 이 RECT 구조체의 left, top 파라미터와 right, bottom 파라미터를 바꿔 넣는 것만으로 간단하게 지정할 수 있다.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

C 프로그래머는,alpha,scale,angleRad,pOffset, 및 pSourceRect 파라미터로 디폴트값을 사용이 아니다.

D3DXDrawSpriteSimple 함수는, 소스 이미지를 3D 렌더링 디바이스에 브릿드 한다. 이 함수는,pd3dTexture 파라미터가 NULL 이외의 경우, 최초의 렌더링 스테이지에서 그 파라미터를 지정해 IDirect3DDevice7::SetTexture 를 호출하는 것만으로 있다.

이 함수는, 스케일링, 회전, 알파 블렌딩, 미러링, 및 배치를 지원 하고 있다. 셔링이나 원근법등 보다 넓은 범위의 이펙트에 대해서는,D3DXDrawSpriteTransform 함수를 사용하는 것.

이 함수는,D3DXPrepareDeviceForSprite 가 디바이스로 불려 간, 또는 호출해 원의 어플리케이션이 다른 방법으로 렌더링 상태를 적절히 준비했다고 가정하고 있다.

회전 각도는, 라디안 단위로 지정된다. 회전도 스케일링도, 스프라이트의 중심을 중심으로서 적용된다. 이 경우, 스프라이트의 중심은, 스프라이트의 폭과 높이의 반에, 오프셋(offset) 파라미터를 더한 것이 된다. 스프라이트의 중심을 이미지의 중심과는 다른 것으로 하고 싶은 경우, 오프셋(offset) 파라미터를 사용한다.

렌더링처의 점은, 스프라이트의 중심을 두는 위치를 나타낸다. 2D 렌더링과 3D 렌더링을 혼합하는 것 같은 상급 유저는, 그러한 좌표가 완전하게 변환되고 있다고 보여지는 것을 기억해 두는 것 (즉, 스크린 공간에서,ppointDest 파라미터의 z 컴퍼넌트를 적절히 설정할 필요가 있다). 일반적으로, 상급 유저는 좀 더 제어하기 위해(때문에), 대신에 D3DXDrawSprite3D 함수를 사용한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxsprite.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXDrawSpriteTransform ,D3DXDrawSprite3D ,D3DXPrepareDeviceForSprite


D3DXDrawSpriteTransform

D3DXDrawSpriteTransform 함수는, 지정 행렬에 의해 변환된 스프라이트를 렌더링하기 위한 메카니즘을 제공하고 있다. 이 함수는,IDirect3DDevice7::BeginScene 함수를 호출한 다음에,IDirect3DDevice7::EndScene 함수를 호출하기 전에 호출할 필요가 있다.

HRESULT D3DXDrawSpriteTransform(
  LPDIRECTDRAWSURFACE7 pd3dTexture,
  LPDIRECT3DDEVICE7 pd3dDevice,
  const D3DXMATRIX* pMatrixTransform,
  float alpha = 1.0f,
  const RECT* pSourceRect = NULL
);

파라미터

pd3dTexture
스프라이트의 소스 이미지로서 사용하는 표면을 나타내, 텍스쳐가 저장 되고 있는 표면의 IDirectDrawSurface7 인터페이스에의 포인터. 이것이 NULL 의 경우, 어플리케이션이 텍스쳐 스테이지 0 에 대해서 IDirect3DDevice7::SetTexture 를 이미 호출하고 있다고 보여진다.
pd3dDevice
Direct3D 렌더링 디바이스의 IDirect3DDevice7 인터페이스에의 포인터. 렌더링 상태가 셋업 되고 있다고 보여진다. 상세한 것에 대하여는, 「D3DXPrepareDeviceForSprite 」를 참조할것.
pMatrixTransform
디폴트의 -. 5 로부터 +. 5 까지의 직사각형에 적용되는 변환을 지정한 4 x 4 행렬의 D3DXMATRIX 구조체에의 포인터. 이 행렬은, 스프라이트를 스크린 공간으로 변환한다. 디폴트로, 스프라이트는 (-0. 5, -0. 5)로부터 (+0. 5, +0. 5)까지 놓여져 있다. 간단하게 회전할 수 있도록(듯이) 중심은 원점에 맞출 수 있어 또 스케일링 하기 쉽게 폭과 높이는 1 으로 되어 있다.
alpha
스프라이트에 적용되는 알파값. 1.0 은 전체적으로 불투명하고, 0.0 은 전체적으로 투명한 것을 의미한다. 다만, 알파를 사용하는 경우는, 아티팩트 (인공물)가 렌더링 되지 않게 하기 위해서, 배경으로부터 전경에 렌더링 하는 것. 또, 반투명의 오브젝트가 교차하지 않게 하는 것. 이 알파값은, 텍스쳐 이미지내에 존재하는 알파 (존재하는 경우)와 조합할 수 있다.
pSourceRect
소스 텍스쳐 중(안)에서 스프라이트에 사용하는 부분을 나타내는 RECT 구조체에의 포인터. 이 파라미터가 NULL 의 경우, 소스 이미지 전체가 스프라이트로 사용된다. 한편, 대신에 소스 이미지의 소직사각형을 지정할 수 있다. 소스 텍스쳐가 Direct3DX 를 사용해 생성 되고 있는 경우,RECT 구조체는 오리지날 이미지의 좌표로 지정한다. 그 때문에, Direct3D 현재 디바이스로 이미지가 기능하도록(듯이) Direct3DX 에 의해 행해진 신장이나 스케일링은 필요없다. 또, X 와 Y 의 미러링에 대해서는, 이 RECT 구조체의 left, top 파라미터와 right, bottom 파라미터를 바꿔 넣는 것만으로 간단하게 지정할 수 있다.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

C 프로그래머는,alpha 파라미터와 pSourceRect 파라미터로 디폴트값을 사용할 수 없다.

이 D3DXDrawSpriteTransform 함수는, 행렬로 지정 가능한 이펙트, 알파 블렌딩, 소직사각형의 선택 기능 (소스의 소직사각형의 값이 NULL 때는, 텍스쳐 전체가 사용되는 것을 의미한다)을 지원 하고 있다. 스프라이트를 종합적으로 제어하려면 ,D3DXDrawSprite3D 함수를 사용한다.

이 함수는, 4 x 4 행렬을 지정해, 디폴트의 RECT 구조체의 점을 변환해 (left=-. 5, top=-. 5, right=+. 5, bottom=+. 5), 소스 이미지를 Direct3D 렌더링 디바이스로 변환한다. 이 디폴트의 RECT 구조체는, 간단하게 회전할 수 있도록(듯이) 중심이 원점에 맞출 수 있고 있다. 또, 이러한 넓이는, 스케일링 하기 쉽게 폭과 높이를 1 으로 해 생성 되고 있다.

이 함수는,pd3dTexture 파라미터가 NULL 이외의 경우, 최초의 렌더링 스테이지에서 그 파라미터를 지정해 IDirect3DDevice7::SetTexture 를 호출하는 것만으로 있다. 이 함수는,D3DXPrepareDeviceForSprite 가 디바이스로 불려 간, 또는 호출해 원의 어플리케이션이 다른 방법으로 렌더링 상태를 적절히 준비했다고 가정하고 있다.

이 함수는, 변환된 점의 w 값 (동차 좌표)이 1 이외의 경우, 그것을 역변환해, 그 값을 Direct3D 에 D3DTLVERTEX 구조체의 rhw 필드로서 건네주므로 주의 해야 한다. w 값이 0 의 경우,rhw 로서 1 을 사용한다.

행렬이 (0, 0, 0, 1) 원점을 중심으로 하는 단위 정방형에 적용되면(자), 이러한 좌표는 스크린 공간에 완전하게 변환되고 있는 것이라고 보여진다. 상급 유저에게는,z 요소와 w 요소를 D3DTLVERTEX 구조체로 Direct3D 직접 모드에 건네주는 것을 추천한다. w 요소는,rhw 요소에 변환된다. w 값이 0 때,rhw 값은 1 이 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxsprite.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXBuildSpriteTransform


D3DXDrawSprite3D

4 점을 지정 하면,D3DXDrawSprite3D 함수는 이러한 점을 내포 하는 스프라이트를 드로잉(Drawing) 한다. 이러한 점은, 화면 좌표로 지정한다. 이 함수는,IDirect3DDevice7::BeginScene 함수를 호출한 다음에,IDirect3DDevice7::EndScene 함수를 호출하기 전에 호출할 필요가 있다.

HRESULT D3DXDrawSprite3D(
  LPDIRECTDRAWSURFACE7 pd3dTexture,
  LPDIRECT3DDEVICE7 pd3dDevice,
  const D3DXVECTOR4 quad[4],
  float alpha = 1.0f,
  const RECT* pSourceRect = NULL,
);

파라미터

pd3dTexture
스프라이트의 소스 이미지로서 사용하는 표면을 나타내, 텍스쳐가 저장 되고 있는 표면의 IDirectDrawSurface7 인터페이스에의 포인터. 이것이 NULL 의 경우, 어플리케이션이 텍스쳐 스테이지 0 에 대해서 IDirect3DDevice7::SetTexture 를 이미 호출하고 있다고 보여진다.
pd3dDevice
Direct3D 렌더링 디바이스의 IDirect3DDevice7 인터페이스에의 포인터. 렌더링 상태가 셋업 되고 있다고 보여진다. 상세한 것에 대하여는, 「D3DXPrepareDeviceForSprite 」를 참조할것.
quad
화면 좌표의 4 점의 배열을 좌상, 우상, 우하, 좌하의 순서로 나타낸 D3DXVECTOR4 구조체의 배열. 이 함수는, 이러한 벡터에 w 값이 포함되어 있는 경우, 그 값을 반대로 해,rhw 값으로서 건네준다 (역동차 좌표). IDirect3DDevice7::DrawPrimitive 메소드에 건네주는 D3DTLVERTEX 의 z 좌표와 rhw 좌표는, z 좌표와 w 좌표가 사용된다.
alpha
스프라이트에 적용되는 알파값. 1.0 은 전체적으로 불투명하고, 0.0 은 전체적으로 투명한 것을 의미한다. 다만, 알파를 사용하는 경우는, 아티팩트 (인공물)가 렌더링 되지 않게 하기 위해서, 배경으로부터 전경에 렌더링 하는 것. 또, 반투명의 오브젝트가 교차하지 않게 하는 것. 이 알파값은, 텍스쳐 이미지내에 존재하는 알파 (존재하는 경우)와 조합할 수 있다.
pSourceRect
소스 텍스쳐 중(안)에서 스프라이트에 사용하는 부분을 나타내는 RECT 구조체에의 포인터. 이 파라미터가 NULL 의 경우, 소스 이미지 전체가 스프라이트로 사용된다. 한편, 대신에 소스 이미지의 소직사각형을 지정할 수 있다. 소스 텍스쳐가 Direct3DX 를 사용해 생성 되고 있는 경우,RECT 구조체는 오리지날 이미지의 좌표로 지정한다. 그 때문에, Direct3D 현재 디바이스로 이미지가 기능하도록(듯이) Direct3DX 에 의해 행해진 신장이나 스케일링은 필요없다. 또, X 와 Y 의 미러링에 대해서는, 이 RECT 구조체의 left, top 파라미터와 right, bottom 파라미터를 바꿔 넣는 것만으로 간단하게 지정할 수 있다.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

C 프로그래머는,alpha 파라미터와 pSourceRect 파라미터로 디폴트값을 사용할 수 없다.

D3DXDrawSprite3D 함수를, 비버텍스 삼각형으로 사용하는 것은 추천하지 않는다.

이 함수는, 텍스쳐를 3D 다각 사각형에 렌더링 한다. 사각형 ABCD 를 2 개의 삼각형 ABC 와 ACD 에 분할해,IDirect3DDevice7::DrawPrimitive 메소드를 호출해 렌더링 한다.

고도의 어플리케이션에서 좀 더 풍부한 제어 기능이 필요한 경우에는,IDirect3DDevice7::DrawPrimitive 메소드를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxsprite.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXPrepareDeviceForSprite

D3DXPrepareDeviceForSprite 함수는, 디바이스를 다른 스프라이트 헬퍼-함수로 사용할 수 있는 대로 준비하기 위해(때문에), 다수의 렌더링 상태를 설정한다. 특히, 알파 블렌딩과 쌍일차 필터링을 셋업 한다. 파라미터는, z 버퍼를 유효하게 할지 어떨지를 제어한다.

HRESULT D3DXPrepareDeviceForSprite(
  LPDIRECT3DDEVICE7 pd3dDevice,
  BOOL ZEnable = FALSE
);

파라미터

pd3dDevice
Direct3DX 스프라이트 서비스로 사용하기 위해서 준비하는 Direct3D 디바이스의 IDirect3DDevice7 인터페이스에의 포인터.
ZEnable
스프라이트에 의해 z 버퍼 표면을 체크해, 그것을 렌더링의 일부로서 갱신할지 어떨지를 나타내는 플래그. 보통의 어플리케이션으로 스프라이트는 배경으로부터 전경으로 렌더링 되므로, 디폴트값은 FALSE 이다. 2D 로 3D 를 혼합하는 것 같은 고도의 어플리케이션으로, 이 값을 TRUE 로 설정한다. ZEnable 가 FALSE 의 경우, 또는 알파 블렌딩을 사용하고 있는 경우, 스프라이트는 배경으로부터 전경으로 렌더링 할 필요가 있다.

반환값

성공하면, S_OK 를 돌려준다. 실패하면,D3DXERR_NULLPOINTER 를 돌려준다.

주의

C 프로그래머는,ZEnable 파라미터로 디폴트값을 사용할 수 없다.

이 함수를 호출해,D3DXDrawSpriteSimple 함수와 D3DXDrawSprite3D 함수가 적절히 기능하기 위해서 필요한 모든 렌더링 상태를 셋업 한다. 다만 상급 유저는, 디바이스에 셋업 된 렌더링 상태와 텍스쳐 상태를 D3DXDrawSpriteSimple 함수와 D3DXDrawSprite3D 함수로 사용하는 경우에, 이 함수를 호출하지 않는 것도 있다.

메모 D3DXPrepareDeviceForSprite 함수는, 렌더링 상태를 수정하지만, 프레임 마다 빈번하게 불려 가면(자) 3D 하드웨어의 퍼포먼스에 악영향을 줄 가능성이 있다. 렌더링 상태가 (D3DXDrawSpriteSimple 함수나 D3DXDrawSprite3D 함수를 호출하는 이외 방법으로) 변경되었을 경우,D3DXDrawSpriteSimple 함수나 D3DXDrawSprite3D 함수를 호출하기 전에 이 함수를 재차 호출할 필요가 있다.

D3DXPrepareDeviceForSprite 함수는, 렌더링의 최초의 텍스쳐 스테이지를 수정해, 디바이스 전체의 렌더링 상태를 몇개인가 수정한다. 다음에, 그 리스트를 나타낸다.

    SetTextureStageState(0, D3DTSS_COLORARG1,         D3DTA_TEXTURE);
    SetTextureStageState(0, D3DTSS_COLOROP,           D3DTOP_SELECTARG1);
    SetTextureStageState(0, D3DTSS_ALPHAARG1,         D3DTA_TEXTURE);
    SetTextureStageState(0, D3DTSS_ALPHAARG2,         D3DTA_DIFFUSE);
    SetTextureStageState(0, D3DTSS_ALPHAOP,           D3DTOP_MODULATE);
    SetTextureStageState(0, D3DTSS_MINFILTER,         D3DTFN_LINEAR);
    SetTextureStageState(0, D3DTSS_MAGFILTER,         D3DTFG_LINEAR);

    SetRenderState(D3DRENDERSTATE_SRCBLEND,           D3DBLEND_SRCALPHA);
    SetRenderState(D3DRENDERSTATE_DESTBLEND,          D3DBLEND_INVSRCALPHA);
    SetRenderState(D3DRENDERSTATE_ALPHABLENDENABLE,   TRUE);

ZEnable 파라미터의 값에 근거해, 다음중 한쪽이 불려 간다.

    SetRenderState(D3DRENDERSTATE_ZENABLE,            FALSE);

또는

    SetRenderState(D3DRENDERSTATE_ZENABLE,            TRUE);

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxsprite.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


텍스쳐 함수

Direct3DX 유틸리티 라이브러리에 의해 제공되고 있는 텍스쳐 처리 어플리케이션 프로그래밍 인터페이스 (API)에서는, 텍스쳐 포맷의 변환, 텍스쳐의 생성과 로드, 텍스쳐의 필터링, 밉맵의 생성을 행하기 위한 함수가 제공되고 있다.

텍스쳐 처리 API 의 함수는, 이하의 그룹에 정리할 수가 있다.

생성 | D3DXCreateCubeMapTexture
 | D3DXCreateTexture
 | D3DXCreateTextureFromFile
로드 | D3DXLoadTextureFromFile
 | D3DXLoadTextureFromMemory
 | D3DXLoadTextureFromSurface
그 외 | D3DXCheckTextureRequirements


D3DXCheckTextureRequirements

D3DXCheckTextureRequirements 함수는, 텍스쳐 생성에 관한 정보를 돌려준다. 이 함수를 사용하면, Direct3DDevice 현재 디바이스로 기능하고 있는 가장 가까운 표면 타입을 간단하게 판정할 수 있다. 이상의 텍스쳐의 포맷, 폭, 높이, 및 밉맵 플래그를 지정 하면, 선택한 디바이스로 기능하고 있는 가장 가까운 표면 타입이 돌려주어진다.

HRESULT D3DXCheckTextureRequirements(
  LPDIRECT3DDEVICE7 pd3dDevice,
  LPDWORD pFlags,
  LPDWORD pWidth,
  LPDWORD pHeight,
  D3DX_SURFACEFORMAT* pPixelFormat,
);

파라미터

pd3dDevice
텍스쳐에 관련지을 수 있고 있는 Direct3D 디바이스의 IDirect3DDevice7 인터페이스에의 포인터.
pFlags
DWORD 값에의 포인터. 밉맵을 생성하지 않는 경우, 이 파라미터에 의해 D3DX_TEXTURE_NOMIPMAP 플래그를 지정한다. 이 값에, NULL 를 지정하는 일도 가능하다. 밉맵 생성이 지원되어 있지 않은 경우는, D3DX_TEXTURE_NOMIPMAP 플래그가 돌려주어진다.
pWidth
폭을 나타내는 DWORD 값에의 포인터 (픽셀 단위). 0 또는 D3DX_DEFAULT 를 지정했을 경우, 폭은 파일로부터 취득된다. 이 파라미터는, 보정된 폭을 돌려준다.
pHeight
높이를 나타내는 DWORD 값에의 포인터 (픽셀 단위). 0 또는 D3DX_DEFAULT 를 지정했을 경우, 높이는 파일로부터 취득된다. 이 파라미터는, 보정된 높이를 돌려준다.
pPixelFormat
D3DX_SURFACEFORMAT 열거형의 멤버에의 포인터. 이 파라미터의 입력값은, 적절한 텍스쳐 포맷이다. 반환값은, 하드웨어로 지원 되고 있는 가장 가까운 텍스쳐 포맷이다.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DXERR_INVALIDPARAMETER
D3DXERR_NOMATCHFOUND
D3DXERR_NULLPOINTER

주의

이 함수는,D3DXCreateTexture 함수,D3DXCreateTextureFromFile 함수, 및 D3DXCreateCubeMapTexture 함수로 필요한 사이즈 변경이나 포맷 변환을 판정할 경우에 도움이 된다. 대부분의 경우, 이 순서를 실행하지 않아도 생성 함수를 직접 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.


D3DXCreateCubeMapTexture

D3DXCreateCubeMapTexture 함수는, 공백의 큐브 맵 텍스쳐를 생성 한다.

HRESULT D3DXCreateCubeMapTexture(
  LPDIRECT3DDEVICE7 pd3dDevice,
  LPDWORD pFlags,
  DWORD cubefaces,
  D3DCOLOR colorEmptyFaces,
  LPDWORD pWidth,
  LPDWORD pHeight,
  D3DX_SURFACEFORMAT* pPixelFormat,
  LPDIRECTDRAWPALETTE pDDPal,
  LPDIRECTDRAWSURFACE7* ppDDSurf,
  LPDWORD pNumMipMaps
);

파라미터

pd3dDevice
텍스쳐에 관련지을 수 있고 있는 Direct3D 디바이스의 IDirect3DDevice7 인터페이스에의 포인터.
pFlags
DWORD 값에의 포인터. 밉맵을 생성하지 않는 경우, 이 파라미터에 의해 D3DX_TEXTURE_NOMIPMAP 플래그를 지정한다. 이 값에, NULL 를 지정하는 일도 가능하다. 밉맵 생성이 지원되어 있지 않은 경우는, D3DX_TEXTURE_NOMIPMAP 플래그가 돌려주어진다.
cubefaces
이 파라미터에는, 생성하는 큐브 맵의 표면을 지정할 수 있다. 상세한 것에 대하여는, 「주의」를 참조할것.
colorEmptyFaces
이 파라미터의 D3DCOLOR 형에는, 큐브 맵으로 불명의 표면 (cubefaces 파라미터로 지정되지 않았던 표면)의 위치를 확보하기 위해서 1 개의 A8R8G8B8 컬러를 지정할 수 있다.
pWidth
폭을 나타내는 DWORD 값에의 포인터 (픽셀 단위). 0 또는 D3DX_DEFAULT 를 지정했을 경우, 폭은 파일로부터 취득된다. 이 파라미터는, 보정된 폭을 돌려준다.
pHeight
높이를 나타내는 DWORD 값에의 포인터 (픽셀 단위). 0 또는 D3DX_DEFAULT 를 지정했을 경우, 높이는 파일로부터 취득된다. 이 파라미터는, 보정된 높이를 돌려준다.
pPixelFormat
표면 포맷을 나타내는 D3DX_SURFACEFORMAT 열거형의 멤버에의 포인터. 이 파라미터에는, D3DX_DEFAULT 를 입력할 수 없다. 이 파라미터에서는, 사용되고 있는 표면 포맷이 돌려주어진다.
pDDPal
팔레트화 표면으로 설정되어 있는 (존재하는 경우) DirectDraw 팔레트의 IDirectDrawPalette 인터페이스에의 포인터. 이것은, 비팔레트화 표면의 경우, 설정되어 있어도 무시된다. 그 때문에, 결과 표면이 8 비트의 팔레트화 표면의 경우는, 사용하는 팔레트를 지정할 수 있다.
ppDDSurf
지정 내용이나 현재 하드웨어에 일치해, 생성 된 텍스쳐의 DirectDrawSurface 오브젝트에의 포인터의 주소.
pNumMipMaps
DWORD 값에의 포인터. 큐브 맵의 특정의 표면에 대해서 생성된 밉맵의 수.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DERR_TEXTURE_NO_SUPPORT
D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMATCHFOUND
D3DXERR_NULLPOINTER
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_NOALPHAHW
DDERR_NOCOOPERATIVELEVELSET
DDERR_NODIRECTDRAWHW
DDERR_NOEMULATION
DDERR_NOEXCLUSIVEMODE
DDERR_NOFLIPHW
DDERR_NOMIPMAPHW
DDERR_NOOVERLAYHW
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_UNSUPPORTEDMODE

주의

큐브 맵은, 최대로 6 표면을 가진다. 또, 불명의 표면으로 사용하는 색을 1 개 지정할 수 있다. 반사의 착시나 굴절을 생성 하기 위해서 큐브 맵을 사용하는 방법의 상세한 것에 대하여는, Direct3D 직접 모드의 문서를 참조할것.

cubefaces 파라미터에 D3DX_DEFAULT, 0, DDSCAPS2_CUBEMAP_ALLFACES 를 지정했을 경우는, 큐브 맵의 6 표면 모든 것을 생성 하도록(듯이) 지시받는다. DDSCAPS2_CUBEMAP_POSITIVEX, DDSCAPS2_CUBEMAP_NEGATIVEX, DDSCAPS2_CUBEMAP_POSITIVEY, DDSCAPS2_CUBEMAP_NEGATIVEY, DDSCAPS2_CUBEMAP_POSITIVEZ, 또는 DDSCAPS2_CUBEMAP_NEGATIVEZ 는, 임의에 조합해 지정할 수 있다.

pFlags 파라미터가 밉맵을 생성 하지 않게 특히 설정되어 있지 않은 한, 최저 레벨 사이즈의 1x1 에 이를 때까지 밉맵은 생성된다.

밉맵의 상세한 것에 대하여는,밉맵에 의한 텍스쳐 필터링 을 참조할것.

폭, 높이, 픽셀 포맷은, 사용 가능한 하드웨어에 근거해 바뀐다. 예를 들어, 밉맵 넓이는 2 의 거듭제곱이 아니면 안되어, 또 폭은 정방형 텍스쳐의 높이로 동일하지 않으면 안 된다. 게다가 지정된 픽셀 포맷을 사용할 수 없는 경우, 최적으로 적합된다.

이 함수는, 사이즈와 픽셀 포맷을 현재 디바이스의 요건에 맞추어 조정한 표면을 생성 한다. 이 표면은, 텍스쳐 관리의 마크를 붙일 수 있었던 시스템 메모리이다. 상세한 것에 대하여는, Direct3D 직접 모드의 문서를 참조할것.

생성 된 표면은, 폭파라미터와 높이 파라미터에 의해 지정된 표면보다 크기도 하고, 작거나 한다. 선택된 픽셀 포맷이, 건네받은 포맷이 아닌 경우도 있다. 그러나, 실제의 폭, 높이, 픽셀 포맷에 주위를 기울이지 않으면 안 되는 것은, 이 함수에 의해 돌려주어진 표면에 직접 액세스 하는 경우 뿐이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXCreateTexture


D3DXCreateTexture

D3DXCreateTexture 함수는, 하늘의 텍스쳐 오브젝트를 생성 한다.

HRESULT D3DXCreateTexture(
  LPDIRECT3DDEVICE7 pd3dDevice,
  LPDWORD pFlags,
  LPDWORD pWidth,
  LPDWORD pHeight,
  D3DX_SURFACEFORMAT* pPixelFormat,
  LPDIRECTDRAWPALETTE pDDPal,
  LPDIRECTDRAWSURFACE7* ppDDSurf,
  LPDWORD pNumMipMaps
);

파라미터

pd3dDevice
텍스쳐에 관련지을 수 있고 있는 Direct3D 디바이스의 IDirect3DDevice7 인터페이스.
pFlags
DWORD 값에의 포인터. 밉맵을 생성하지 않는 경우, 이 파라미터에 의해 D3DX_TEXTURE_NOMIPMAP 플래그를 지정한다. 이 값에, NULL 를 지정하는 일도 가능하다. 밉맵 생성이 지원되어 있지 않은 경우는, D3DX_TEXTURE_NOMIPMAP 플래그가 돌려주어진다.
pWidth
폭을 나타내는 DWORD 값에의 포인터 (픽셀 단위). 이 파라미터는, 보정된 폭을 돌려준다.
pHeight
높이를 나타내는 DWORD 값에의 포인터 (픽셀 단위). 이 파라미터는, 보정된 높이를 돌려준다.
pPixelFormat
D3DX_SURFACEFORMAT 열거형의 멤버에의 포인터. 이 파라미터에서는, D3DX_DEFAULT 는 유효하지 않다. 이 파라미터의 입력값은, 적절한 텍스쳐 포맷이다. 반환값은, 하드웨어로 지원 되고 있는 가장 가까운 텍스쳐 포맷이다.
pDDPal
팔레트화 표면으로 설정되어 있는 (존재하는 경우) DirectDraw 팔레트의 IDirectDrawPalette 인터페이스에의 포인터. 이것은, 비팔레트화 표면의 경우, 설정되어 있어도 무시된다. 그 때문에, 결과 표면이 8 비트의 팔레트화 표면의 경우는, 사용하는 팔레트를 지정할 수 있다.
ppDDSurf
지정 내용이나 현재 하드웨어에 일치해, 생성 된 텍스쳐의 DirectDrawSurface 오브젝트에의 포인터의 주소.
pNumMipMaps
DWORD 값에의 포인터. 큐브 맵의 특정의 표면에 대해서 생성된 밉맵의 수.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMATCHFOUND
D3DXERR_NULLPOINTER
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_NOALPHAHW
DDERR_NOCOOPERATIVELEVELSET
DDERR_NODIRECTDRAWHW
DDERR_NOEMULATION
DDERR_NOEXCLUSIVEMODE
DDERR_NOFLIPHW
DDERR_NOMIPMAPHW
DDERR_NOOVERLAYHW
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_UNSUPPORTEDMODE

주의

pFlags 파라미터가 밉맵을 생성 하지 않게 특히 설정되어 있지 않은 한, 최저 레벨 사이즈의 1 x 1 에 이를 때까지 밉맵은 생성된다.

밉맵의 상세한 것에 대하여는, 「밉맵에 의한 텍스쳐 필터링」을 참조할것.

폭, 높이, 픽셀 포맷은, 사용 가능한 하드웨어에 근거해 바뀐다. 예를 들어, 밉맵 넓이는 2 의 거듭제곱이 아니면 안되어, 또 폭은 정방형 텍스쳐의 높이로 동일하지 않으면 안 된다. 게다가 지정된 픽셀 포맷을 사용할 수 없는 경우, 최적으로 적합된다.

이 함수는, 사이즈와 픽셀 포맷을 현재 디바이스의 요건에 맞추어 조정한 표면을 생성 한다. 이 표면은, 텍스쳐 관리의 마크를 붙일 수 있었던 시스템 메모리이다. 상세한 것에 대하여는, Direct3D 직접 모드의 문서를 참조할것.

생성 된 표면은, 폭파라미터와 높이 파라미터에 의해 지정된 표면보다 크기도 하고, 작거나 한다. 선택된 픽셀 포맷이, 건네받은 포맷이 아닌 경우도 있다. 그러나, 실제의 폭, 높이, 픽셀 포맷에 주위를 기울이지 않으면 안 되는 것은, 이 함수에 의해 돌려주어진 표면에 직접 액세스 하는 경우 뿐이다 (다만, 표면의 프로퍼티는 디바이스 마다 다르므로, 직접 액세스 하는 것은 추천하지 않는다).

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXCreateCubeMapTexture


D3DXCreateTextureFromFile

D3DXCreateTextureFromFile 함수는, 스탠드얼론 파일 또는 리소스로부터 텍스쳐 오브젝트를 생성 한다.

HRESULT D3DXCreateTextureFromFile(
  LPDIRECT3DDEVICE7 pd3dDevice,
  LPDWORD pFlags,
  LPDWORD pWidth,
  LPDWORD pHeight,
  D3DX_SURFACEFORMAT* pPixelFormat,
  LPDIRECTDRAWPALETTE pDDPal,
  LPDIRECTDRAWSURFACE7* ppDDSurf,
  LPDWORD pNumMipMaps,
  LPSTR pSrcName,
  D3DX_FILTERTYPE filterType
);

파라미터

pd3dDevice
텍스쳐에 관련지을 수 있었던 Direct3D 디바이스의 IDirect3DDevice7 인터페이스.
pFlags
DWORD 값에의 포인터. 밉맵을 생성하지 않는 경우, 이 파라미터에 의해 D3DX_TEXTURE_NOMIPMAP 플래그를 지정한다. 이 값에, NULL 를 지정하는 일도 가능하다. 밉맵 생성이 지원되어 있지 않은 경우는, D3DX_TEXTURE_NOMIPMAP 플래그가 돌려주어진다.
pWidth
폭을 나타내는 DWORD 값에의 포인터 (픽셀 단위). 0 또는 D3DX_DEFAULT 를 지정했을 경우, 폭은 파일로부터 취득된다. 이 파라미터는, 보정된 폭을 돌려준다.
pHeight
높이를 나타내는 DWORD 값에의 포인터 (픽셀 단위). 0 또는 D3DX_DEFAULT 를 지정했을 경우, 높이는 파일로부터 취득된다. 이 파라미터는, 보정된 높이를 돌려준다.
pPixelFormat
D3DX_SURFACEFORMAT 열거형의 멤버에의 포인터. 이 파라미터에서는, D3DX_DEFAULT 는 유효하지 않다. 이 파라미터의 입력값은, 적절한 텍스쳐 포맷이다. 반환값은, 하드웨어로 지원 되고 있는 가장 가까운 텍스쳐 포맷이다. D3DX_SF_UNKNOWN 를 지정 하면, 비트 맵에 가장 가까운 픽셀 포맷이 선택된다.
pDDPal
팔레트화 표면으로 설정되어 있는 (존재하는 경우) DirectDraw 팔레트의 IDirectDrawPalette 인터페이스에의 포인터. 이것은, 비팔레트화 표면의 경우, 설정되어 있어도 무시된다.
ppDDSurf
지정 내용이나 현재 하드웨어에 일치해, 생성 된 텍스쳐의 DirectDrawSurface 오브젝트에의 포인터의 주소.
pNumMipMaps
DWORD 값에의 포인터. 생성된 밉맵의 수.
pSrcName
파일명 캐릭터 라인에의 포인터. BMP, DIB, DDS 의 파일 타입이 지원 되고 있다. 상세한 것에 대하여는, 「주의」를 참조할것.
filterType
사이즈의 변경이나 밉맵의 생성이 필요한 때에 사용하는 필터링 함수를 나타내는 D3DX_FILTERTYPE 열거형의 멤버.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, NULL 또는 다음의 몇개의 값을 돌려준다.

D3DERR_TEXTURE_NO_SUPPORT
D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INVALIDFILEFORMAT
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMATCHFOUND
D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER
D3DXERR_UNSUPPORTEDFILEFORMAT
DDERR_DCALREADYCREATED
DDERR_GENERIC
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDRECT
DDERR_INVALIDSURFACETYPE
DDERR_NOALPHAHW
DDERR_NOCOOPERATIVELEVELSET
DDERR_NODIRECTDRAWHW
DDERR_NOEMULATION
DDERR_NOEXCLUSIVEMODE
DDERR_NOFLIPHW
DDERR_NOMIPMAPHW
DDERR_NOOVERLAYHW
DDERR_NOTFOUND
DDERR_NOTLOCKED
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_UNSUPPORTEDMODE
DDERR_WASSTILLDRAWING

주의

실행 가능 파일의 리소스 부분에서 지원 되고 있는 것은, BMP 파일과 DIB 파일 뿐이다.

pSrcName 파라미터로, 16 bpp, 24 bpp, 32bpp 의 정의 컬러와 8bpp 의 팔레트화의 경우는 TGA 가 지원 되고 있다. 또, 8bpp 로 16bpp 의 그레이 스케일도 지원 되고 있다. 전의 TGA 포맷인 RLE 버젼도 지원 되고 있다. 다만 TGA 파일에서는, 컬러 키화한 알파나 좌방 곱셈 된 알파는 현재 지원되어 있지 않다.

pSrcName 파라미터에 수치 ID 를 지정했을 경우,D3DXLoadTextureFromFile 함수에 실행 가능 파일의 리소스로부터 비트 맵 이미지를 로드하도록(듯이) 지시받는다. 그 이외의 경우,pSrcName 는 파일명이다고 보여진다. 다만,D3DXCreateTextureFromFile 함수에서는 캐릭터 라인 포인터가 파일명으로서 다루어지므로, 캐릭터 라인의 리소스명은 사용할 수 없다.

pFlags 파라미터가 밉맵을 생성 하지 않게 특히 설정되어 있지 않은 한, 최저 레벨 사이즈의 1 x 1 에 이를 때까지 밉맵은 생성된다.

밉맵의 상세한 것에 대하여는, 「밉맵에 의한 텍스쳐 필터링」을 참조할것.

폭, 높이, 픽셀 포맷은, 사용 가능한 하드웨어에 근거해 바뀐다. 예를 들어, 밉맵 넓이는 2 의 거듭제곱이 아니면 안되어, 또 폭은 정방형 텍스쳐의 높이로 동일하지 않으면 안 된다. 게다가 지정된 픽셀 포맷을 사용할 수 없는 경우, 최적으로 적합된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXLoadTextureFromFile


D3DXLoadTextureFromFile

D3DXLoadTextureFromFile 함수는, 텍스쳐를 파일로부터 밉맵 레벨에 로드해, 필요한 컬러 변환이나 재스케일링을 실행한다.

HRESULT D3DXLoadTextureFromFile(
  LPDIRECT3DDEVICE7 pd3dDevice,
  LPDIRECTDRAWSURFACE7 pTexture,
  DWORD mipMapLevel,
  LPSTR pSrcName,
  RECT* pSrcRect,
  RECT* pDestRect,
  D3DX_FILTERTYPE filterType
);

파라미터

pd3dDevice
텍스쳐에 관련지을 수 있고 있는 Direct3D 디바이스의 IDirect3DDevice7 인터페이스에의 포인터.
pTexture
D3DXCreateTextureFromFile 함수 또는 D3DXCreateTexture 함수의 어느 쪽인가에보다 생성 된 DirectDrawSurface 에의 포인터. 이 파라미터는, 텍스쳐 표면 오브젝트를 포인트 한다.
mipMapLevel
밉맵 레벨을 나타낸다. 「주의」를 참조할것.
pSrcName
파일명 캐릭터 라인에의 포인터. BMP, DIB, DDS 의 파일 타입이 지원 되고 있다. 상세한 것에 대하여는, 「주의」를 참조할것.
pSrcRect
로드원의 직사각형을 식별하는 RECT 구조체에의 포인터. 이 파라미터에 NULL 를 지정했을 경우는, 표면 전체가 사용된다.
pDestRect
로드처의 직사각형을 식별하는 RECT 구조체에의 포인터. 이 파라미터에 NULL 를 지정했을 경우는, 표면 전체가 사용된다.
filterType
밉맵 생성시에 사용되는 필터를 나타내는 D3DX_FILTERTYPE 열거형의 멤버.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, NULL 또는 다음의 몇개의 값을 돌려준다.

D3DERR_TEXTURE_NO_SUPPORT
D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INVALIDFILEFORMAT
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMATCHFOUND
D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER
D3DXERR_UNSUPPORTEDFILEFORMAT
DDERR_DCALREADYCREATED
DDERR_GENERIC
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDRECT
DDERR_INVALIDSURFACETYPE
DDERR_NOALPHAHW
DDERR_NOCOOPERATIVELEVELSET
DDERR_NODIRECTDRAWHW
DDERR_NOEMULATION
DDERR_NOEXCLUSIVEMODE
DDERR_NOFLIPHW
DDERR_NOMIPMAPHW
DDERR_NOOVERLAYHW
DDERR_NOTFOUND
DDERR_NOTLOCKED
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_UNSUPPORTEDMODE
DDERR_WASSTILLDRAWING

주의

이 함수는, 파일로부터 표면에 픽셀을 카피하기 위한 메카니즘을 제공한다.

다음에,mipMapLevel 파라미터로 고려해야 할 일을 나타낸다.

  • 지정한 밉맵 레벨이 존재하지 않는 경우, 에러가 돌려주어진다.
  • D3DX_DEFAULT 가 지정되고 있는 경우에, 동수의 밉맵 레벨이 존재 하면 와, 모든 로드원밉맵 레벨이 로드 된다.
  • 밉맵 레벨이 로드원파일에는 있어, 로드처 표면에 없는 경우, 최상정도 레벨이 사용된다.
  • 밉맵 레벨이 로드처 표면에는 있어, 로드원파일에 없는 경우, 확대를 한다.
  • 로드원파일과 로드처 표면의 밉맵 레벨의 수가 동일하지 않은 경우, 확대를 한다.

pSrcName 파라미터로, 16 bpp, 24 bpp, 32bpp 의 정의 컬러와 8bpp 의 팔레트화의 경우는 TGA 가 지원 되고 있다. 또, 8bpp 로 16bpp 의 그레이 스케일도 지원 되고 있다. 전의 TGA 포맷인 RLE 버젼도 지원 되고 있다. 다만 TGA 파일에서는, 컬러 키화한 알파나 좌방 곱셈 된 알파는 현재 지원되어 있지 않다.

로드처 표면이 Direct3DX 에 의해 생성 되었을 경우,RECT 구조체는 그 표면의 오리지날 좌표로 지정된다.

이 함수는,D3DX_SURFACEFORMAT 구조체에 의해 기술 가능한 모든 표면 포맷에 대해, 컬러 변환의 전범위를 지원 하고 있다. 또, 필터링 한 재스케일링을 이행 하거나 밉맵을 자동 갱신한다.

pDestRect 를 오리지날 이미지의 공간으로 설정하면, 어플리케이션은 D3DXCreateTexture 함수 중(안)에서 표면이 어떻게 사이즈 변경되어도 걱정 하지 않아도 되다. 예를 들어, 이미지가 100 x 150 픽셀의 경우, 구성이 다르면 128 x 256 이 되거나 256 x 256 이 된다. 어느 쪽의 경우도, 제 2 상한을 갱신할 경우에 사용하는 RECT 구조체는 사이즈 변경을 하지 않을 때와 같이 (0, 0, 50, 75)된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXCreateTextureFromFile ,D3DXLoadTextureFromMemory ,D3DXLoadTextureFromSurface


D3DXLoadTextureFromMemory

D3DXLoadTextureFromMemory 함수는, 밉맵 레벨을 메모리로부터 로드해, 필요한 컬러 변환을 실행한다.

HRESULT D3DXLoadTextureFromMemory(
  LPDIRECT3DDEVICE7 pd3dDevice,
  LPDIRECTDRAWSURFACE7 pTexture,
  DWORD mipMapLevel,
  LPVOID pMemory,
  LPDIRECTDRAWPALETTE pDDPal,
  D3DX_SURFACEFORMAT srcPixelFormat,
  DWORD srcPitch,
  RECT* pDestRect,
  D3DX_FILTERTYPE filterType
);

파라미터

pd3dDevice
텍스쳐에 관련지을 수 있고 있는 Direct3D 디바이스의 IDirect3DDevice7 인터페이스에의 포인터.
pTexture
D3DXCreateTextureFromFile 함수 또는 D3DXCreateTexture 함수의 어느 쪽인가에보다 생성 된 DirectDrawSurface 에의 포인터. 이 파라미터는, 텍스쳐 표면 오브젝트를 포인트 한다.
mipMapLevel
밉맵 레벨을 나타낸다. 「주의」를 참조할것.
pMemory
텍스쳐의 로드원메모리에의 포인터.
pDDPal
메모리로 팔레트화가 지원 되고 있는 경우, 어플리케이션으로부터 옵션으로 건네받는 DirectDraw 팔레트의 IDirectDrawPalette 인터페이스에의 포인터.
srcPixelFormat
로드원의 픽셀 포맷을 나타내는 D3DX_SURFACEFORMAT 열거형의 멤버에의 포인터.
srcPitch
메모리의 피치 또는 D3DX_DEFAULT. 이 파라미터는,srcPixelFormat 파라미터가 기본으로 되어 있다.
pDestRect
로드처 직사각형을 식별하는 RECT 구조체에의 포인터. 이 파라미터에 NULL 를 지정했을 경우는, 표면 전체가 사용된다.
filterType
밉맵 생성시에 사용되는 필터를 나타내는 D3DX_FILTERTYPE 열거형의 멤버.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND
DDERR_SURFACELOST
DDERR_UNSUPPORTED

주의

이 함수는, 메모리로부터 표면에 몇개의 픽셀을 카피하기 위한 메카니즘을 제공한다.

로드처 표면이 Direct3DX 에 의해 생성 되었을 경우,RECT 구조체는 그 표면의 오리지날 좌표로 지정된다.

다음에,mipMapLevel 파라미터로 고려해야 할 일을 나타낸다.

  • 지정한 밉맵 레벨이 존재하지 않는 경우, 에러가 돌려주어진다.
  • D3DX_DEFAULT 가 지정되고 있는 경우에, 동수의 밉맵 레벨이 존재 하면 와, 모든 로드원밉맵 레벨이 로드 된다.
  • 밉맵 레벨이 로드원메모리에는 있어, 로드처 표면에 없는 경우, 최상정도 레벨이 사용된다.
  • 밉맵 레벨이 로드처 표면에는 있어, 로드원메모리에 없는 경우, 확대를 한다.
  • 로드원메모리와 로드처 표면의 밉맵 레벨의 수가 동일하지 않은 경우, 확대를 한다.

이 함수는, 로드원메모리가 모두 로드 되고 있는 것과 가정하고 있다.

이 함수는,D3DX_SURFACEFORMAT 구조체에 의해 기술 가능한 모든 표면 포맷에 대해, 컬러 변환의 전범위를 지원 하고 있다. 또, 필터링 한 재스케일링을 이행 하거나 밉맵을 자동 갱신한다.

pDestRect 를 오리지날 이미지의 공간으로 설정하면, 어플리케이션은 D3DXCreateTexture 함수 중(안)에서 표면이 어떻게 사이즈 변경되어도 걱정 하지 않아도 되다. 예를 들어, 이미지가 100 x 150 픽셀의 경우, 구성이 다르면 128 x 256 이 되거나 256 x 256 이 된다. 어느 쪽의 경우도, 제 2 상한을 갱신할 경우에 사용하는 RECT 구조체는 사이즈 변경을 하지 않을 때와 같이 (0, 0, 50, 75)된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXLoadTextureFromFile ,D3DXLoadTextureFromSurface


D3DXLoadTextureFromSurface

D3DXLoadTextureFromSurface 함수는, 텍스쳐를 DirectDrawSurface 로부터 밉맵 레벨에 로드해, 필요한 컬러 변환을 실행한다.

HRESULT D3DXLoadTextureFromSurface(
  LPDIRECT3DDEVICE7 pd3dDevice,
  LPDIRECTDRAWSURFACE7 pTexture,
  DWORD mipMapLevel,
  LPDIRECTDRAWSURFACE7 pSurfaceSrc,
  RECT* pSrcRect,
  RECT* pDestRect,
  D3DX_FILTERTYPE filterType
);

파라미터

pd3dDevice
텍스쳐에 관련지을 수 있고 있는 Direct3D 디바이스의 IDirect3DDevice7 인터페이스에의 포인터.
pTexture
D3DXCreateTextureFromFile 함수 또는 D3DXCreateTexture 함수의 어느 쪽인가에보다 생성 된 DirectDrawSurface 에의 포인터. 이 파라미터는, 텍스쳐 표면 오브젝트를 포인트 한다.
mipMapLevel
밉맵 레벨을 나타낸다. 「주의」를 참조할것.
pSurfaceSrc
로드원표면의 IDirectDrawSurface7 인터페이스에의 포인터. 로드원픽셀이 저장 된 표면 오브젝트.
pSrcRect
로드원직사각형을 식별하는 RECT 구조체에의 포인터. 이 파라미터에 NULL 를 지정했을 경우는, 표면 전체가 사용된다.
pDestRect
로드처 직사각형을 식별하는 RECT 구조체에의 포인터. 이 파라미터에 NULL 를 지정했을 경우는, 표면 전체가 사용된다.
filterType
사이즈 변경이나 밉맵 생성이 필요한 때에 사용되는 필터 함수를 나타내는 D3DX_FILTERTYPE 열거형의 멤버.

반환값

성공하면, S_OK 를 돌려준다.

실패하면, 다음 몇개의 값을 돌려준다.

D3DXERR_D3DXNOTSTARTEDYET
D3DXERR_INVALIDPARAMETER
D3DXERR_NOMEMORY
D3DXERR_NULLPOINTER
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND
DDERR_SURFACELOST
DDERR_UNSUPPORTED

주의

이 함수는, 어느 표면으로부터 다른 표면에 카피하기 위한 메카니즘을 제공한다.

다음에,mipMapLevel 파라미터로 고려해야 할 일을 나타낸다.

  • 지정한 밉맵 레벨이 존재하지 않는 경우, 에러가 돌려주어진다.
  • D3DX_DEFAULT 가 지정되고 있는 경우에, 동수의 밉맵 레벨이 존재 하면 와, 모든 로드원밉맵 레벨이 로드 된다.
  • 밉맵 레벨이 로드원표면에는 있어, 로드처 표면에 없는 경우, 최상정도 레벨이 사용된다.
  • 밉맵 레벨이 로드처 표면에는 있어, 로드원표면에 없는 경우, 확대를 한다.
  • 로드원표면과 로드처 표면의 밉맵 레벨의 수가 동일하지 않은 경우, 확대를 한다.

로드원표면이나 로드처 표면이 Direct3DX 에 의해 생성 되었을 경우,RECT 구조체는 그 표면의 오리지날 좌표로 지정된다.

이 함수는,D3DX_SURFACEFORMAT 구조체에 의해 기술 가능한 모든 표면 포맷에 대해, 컬러 변환의 전범위를 지원 하고 있다. 또, 필터링 한 재스케일링을 이행 하거나 밉맵을 자동 갱신한다.

pDestRect 를 오리지날 이미지의 공간으로 설정하면, 어플리케이션은 D3DXCreateTexture 함수 중(안)에서 표면이 어떻게 사이즈 변경되어도 걱정 하지 않아도 되다. 예를 들어, 이미지가 100 x 150 픽셀의 경우, 구성이 다르면 128 x 256 이 되거나 256 x 256 이 된다. 어느 쪽의 경우도, 제 2 상한을 갱신할 경우에 사용하는 RECT 구조체는 사이즈 변경을 하지 않을 때와 같이 (0, 0, 50, 75)된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.
라이브러리 : d3dx.lib 를 사용.

참조

D3DXLoadTextureFromFile ,D3DXLoadTextureFromMemory


매크로

여기에서는, Direct3DX 유틸리티 라이브러리가 제공하는 매크로의 레퍼런스 정보를 기술한다.

  • D3DXToDegree
  • D3DXToRadian


D3DXToDegree

D3DXToDegree 매크로는, 라디안을 도수로 변환한다.

D3DXToDegree( radian ) ((radian) * (180.0f / D3DX_PI))

파라미터

radian
도수로 변환하는 값 (라디안 단위).

반환값

매크로는, 라디안값을 도수로 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.

참조

D3DXToRadian


D3DXToRadian

D3DXToRadian 매크로는, 도수를 라디안으로 변환한다.

D3DXToRadian( degree ) ((degree) * (D3DX_PI / 180.0f))

파라미터

degree
라디안으로 변환하는 값 (도수).

반환값

매크로는, 도수값을 라디안 단위로 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.

참조

D3DXToDegree


구조체

여기에서는, Direct3DX 유틸리티 라이브러리에서 사용되는 이하의 구조체에 대해 기술한다.

  • D3DX_DEVICEDESC
  • D3DX_VIDMODEDESC
  • D3DXCOLOR
  • D3DXMATRIX
  • D3DXPLANE
  • D3DXQUATERNION
  • D3DXVECTOR2
  • D3DXVECTOR3
  • D3DXVECTOR4


D3DX_DEVICEDESC

D3DX_DEVICEDESC 구조체는, 3D 로 렌더링 할 수 있는 디바이스를 기술한다.

typedef struct _D3DX_DEVICEDESC {
  DWORD       deviceIndex;
  DWORD       hwLevel;
  GUID        ddGuid;
  GUID        d3dDeviceGuid;
  GUID        ddDeviceID;
  char        driverDesc[D3DX_DRIVERDESC_LENGTH];
  HMONITOR    monitor;
  BOOL        onPrimary;
} D3DX_DEVICEDESC;

멤버

deviceIndex
디바이스의 일의의 번호 (DWORD).
hwLevel
관계가 있는 액셀러레이트 레벨. 이것은, 사전에 정의된 디바이스 인덱스의 1 개이며, 정보 제공 (을) 위해서만 이 구조체에 준비되어 있다. 시스템에 디바이스가 다수 있을 때는, 같은 hwLevel 가 된다. D3DX 유틸리티 라이브러리에서 특정의 디바이스를 참조하려면 , 대신에 deviceIndex 멤버의 값을 사용한다.
ddGuid
DirectDraw 글로벌 유니크 식별자 (GUID).
d3dDeviceGuid
Direct3DDevice 의 GUID.
ddDeviceID
IDirectDraw7::GetDeviceIdentifier 의 GUID. 이 GUID 는, 특정 비디오 카드의 특정 드라이버 버젼에 대해서 일의이다.
driverDesc
드라이버를 기술한 캐릭터 라인. 가능한 최대 캐릭터 라인장은 256 문자이다.
monitor
이 디바이스에 의해 사용되는 비디오 모니터의 핸들 (멀티 모니터 특유). 멀티 모니터 시스템으로 복수의 모니터를 사용하는 디바이스에서는, 이 필드에 다양한 값이 보고된다. 그 때문에 멀티 모니터 시스템에 대해 테스트 하면 와, 어플리케이션은 Direct3DX 디바이스 리스트의 복수의 모니터 핸들을 검색한다.
onPrimary
디바이스가 프라이머리 모니터상에 있을지 어떨지를 나타낸다 (멀티 모니터 특유).

주의

다음의 스테이트먼트는,driverDesc 문자 배열 파라미터로 사용되는 정수를 정의한다.

#define D3DX_DRIVERDESC_LENGTH    256

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.


D3DX_VIDMODEDESC

D3DX_VIDMODEDESC 구조체는, 디스플레이 모드를 기술한다.

typedef struct  _D3DX_VIDMODEDESC {
  DWORD width;
  DWORD height;
  DWORD bpp;
  DWORD refreshRate;
} D3DX_VIDMODEDESC;

멤버

width
화면의 폭.
height
화면의 높이.
bpp
픽셀 근처의 비트수.
refreshRate
refresh rate.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.


D3DXCOLOR

D3DX_DEVICEDESC 구조체는, 컬러값을 기술한다.

typedef struct D3DXCOLOR {
  FLOAT r, g, b, a;
} D3DXCOLOR;

멤버

r
색의 빨강 성분.
g
색의 초록 성분.
b
색의 파랑 성분.
a
색의 알파 성분.

주의

C++ 프로그래머는, 연산자의 overload 기능이나 형태 변환 기능을 이용할 수 있다. D3DXCOLOR 구조체를 C++ 로 이행 하면, overload 된 constructor　 　 이나 overload 된 대입 연산자, 단항 연산자, 및 2 항연산자 (등가 연산자를 포함한다)가 이행 된다. 상세한 것에 대하여는, 「C++ 고유의 기능」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.

참조

D3DXColorNegative ,D3DXColorAdd ,D3DXColorSubtract ,D3DXColorScale ,D3DXColorModulate ,D3DXColorLerp


D3DXMATRIX

D3DXMATRIX 구조체는, 행렬을 기술한다.

typedef struct D3DXMATRIX {
  union
  {
    float m[4][4];
  };
} D3DXMATRIX;

주의

Direct3DX 로 투영 행렬의 m23 요소에는, 부의 값을 설정할 수 없다. 어플리케이션은, 이 요소로 부의 값을 사용해야 하는 경우, 그 대신에 투영 행렬 전체를 –1 에 의해 스케일링 한다.

C++ 프로그래머는, 연산자의 overload 기능이나 형태 변환 기능을 이용할 수 있다. D3DXMATRIX 구조체를 C++ 로 이행 하면, overload 된 constructor　 　 이나 overload 된 대입 연산자, 단항 연산자, 및 2 항연산자 (등가 연산자를 포함한다)가 이행 된다. 상세한 것에 대하여는, 「C++ 고유의 기능」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.

참조

D3DXMatrixIdentity ,D3DXMatrixIsIdentity ,D3DXMatrixfDeterminant ,D3DXMatrixMultiply ,D3DXMatrixTranspose ,D3DXMatrixInverse ,D3DXMatrixScaling ,D3DXMatrixTranslation ,D3DXMatrixRotationX ,D3DXMatrixRotationY ,D3DXMatrixRotationZ ,D3DXMatrixRotationAxis ,D3DXMatrixRotationQuaternion ,D3DXMatrixRotationYawPitchRoll ,D3DXMatrixTransformation ,D3DXMatrixAffineTransformation ,D3DXMatrixLookAt ,D3DXMatrixPerspective ,D3DXMatrixPerspectiveFov ,D3DXMatrixPerspectiveOffCenter ,D3DXMatrixOrtho ,D3DXMatrixOrthoOffCenter ,D3DXMatrixShadow ,D3DXMatrixReflect


D3DXPLANE

D3DXPLANE 구조체는, 평면을 기술한다.

typedef struct D3DXPLANE {
  float a, b, c, d;
} D3DXPLANE;

멤버

a
일반 평면식의 클립면의 a 계수. 「주의」를 참조할것.
b
일반 평면식의 클립면의 b 계수. 「주의」를 참조할것.
c
일반 평면식의 클립면의 c 계수. 「주의」를 참조할것.
d
일반 평면식의 클립면의 d 계수. 「주의」를 참조할것.

주의

D3DXPLANE 구조체의 멤버는, 일반 평면식의 형식을 취한다. 멤버는, ax + by + cz + dw = 0 이라고 하는 일반 평면식에 적합한다.

C++ 프로그래머는, 연산자의 overload 기능이나 형태 변환 기능을 이용할 수 있다. D3DXPLANE 구조체를 C++ 로 이행 하면, overload 된 constructor　 　 이나 overload 된 단항 연산자나 2 항연산자가 이행 된다. 상세한 것에 대하여는, 「C++ 고유의 기능」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.

참조

D3DXPlaneDot ,D3DXPlaneDotCoord ,D3DXPlaneDotNormal ,D3DXPlaneIntersectLine ,D3DXPlaneFromPointNormal ,D3DXPlaneFromPoints ,D3DXPlaneTransform


D3DXQUATERNION

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++ 고유의 기능」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.

참조

D3DXPlaneDot ,D3DXPlaneDotCoord ,D3DXPlaneDotNormal ,D3DXPlaneIntersectLine ,D3DXPlaneFromPointNormal ,D3DXPlaneFromPoints ,D3DXPlaneTransform


D3DXVECTOR2

D3DXVECTOR2 구조체는, 2 차원 (2D) 공간의 벡터를 기술한다.

typedef struct D3DXVECTOR2 {
  float x, y;
} D3DXVECTOR2;

멤버

x
x 컴퍼넌트.
y
y 컴퍼넌트.

주의

C++ 프로그래머는, 연산자의 overload 기능이나 형태 변환 기능을 이용할 수 있다. D3DXVECTOR2 구조체를 C++ 로 이행 하면, overload 된 constructor　 　 이나 overload 된 대입 연산자, 단항 연산자, 및 2 항연산자 (등가 연산자를 포함한다)가 이행 된다. 상세한 것에 대하여는, 「C++ 고유의 기능」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.

참조

D3DXVec2Length ,D3DXVec2LengthSq ,D3DXVec2Dot ,D3DXVec2CCW ,D3DXVec2Add ,D3DXVec2Subtract ,D3DXVec2Minimize ,D3DXVec2Maximize ,D3DXVec2Scale ,D3DXVec2Lerp ,D3DXVec2Normalize ,D3DXVec2Hermite ,D3DXVec2Hermite ,D3DXVec2Transform ,D3DXVec2TransformCoord ,D3DXVec2TransformNormal


D3DXVECTOR3

D3DXVECTOR3 구조체는, 3 차원 (3D) 공간의 벡터를 기술한다.

typedef struct D3DXVECTOR3 {
  float x, y, z;
} D3DXVECTOR3;

멤버

x
x 컴퍼넌트.
y
y 컴퍼넌트.
z
z 컴퍼넌트.

주의

C++ 프로그래머는, 연산자의 overload 기능이나 형태 변환 기능을 이용할 수 있다. D3DXVECTOR3 구조체를 C++ 로 이행 하면, overload 된 constructor　 　 이나 overload 된 대입 연산자, 단항 연산자, 및 2 항연산자 (등가 연산자를 포함한다)가 이행 된다. 상세한 것에 대하여는, 「C++ 고유의 기능」을 참조할것.

D3DXVec3Length ,D3DXVec3LengthSq ,D3DXVec3Dot ,D3DXVec3Cross ,D3DXVec3Add ,D3DXVec3Subtract ,D3DXVec3Minimize ,D3DXVec3Maximize ,D3DXVec3Scale ,D3DXVec3Lerp ,D3DXVec3Normalize ,D3DXVec3Hermite ,D3DXVec3BaryCentric ,D3DXVec3Transform ,D3DXVec3TransformCoord ,D3DXVec3TransformNormal

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.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++ 고유의 기능」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxmath.h 로 선언.

참조

D3DXVec4Length ,D3DXVec4LengthSq ,D3DXVec4Dot ,D3DXVec4Add ,D3DXVec4Subtract ,D3DXVec4Minimize ,D3DXVec4Maximize ,D3DXVec4Scale ,D3DXVec4Lerp ,D3DXVec4Cross ,D3DXVec4Normalize ,D3DXVec4Hermite ,D3DXVec4BaryCentric ,D3DXVec4Transform


C++ 고유의 기능

C++ 프로그래머는, Direct3DX 유틸리티 라이브러리에 의해 제공되고 있는 constructor　 　 의 overload 기능, 연산자의 overload 기능, 형태 변환의 확장 기능을 이용할 수 있다. 다음의 구조체에는, 확장 기능이 이행 되고 있다.

  • D3DXCOLOR 확장 기능
  • D3DXMATRIX 확장 기능
  • D3DXPLANE 확장 기능
  • D3DXQUATERNION 확장 기능
  • D3DXVECTOR2 확장 기능
  • D3DXVECTOR3 확장 기능
  • D3DXVECTOR4 확장 기능


D3DXCOLOR 확장 기능

D3DX_DEVICEDESC 는, 다음의 연산자 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;

// 대입 연산자
  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


D3DXMATRIX 확장 기능

D3DXMATRIX 구조체는, 다음의 연산자 overload와 형태 변환을 제공하고 있다.

#ifdef __cplusplus
public:
  D3DXMATRIX() {};
  D3DXMATRIX( const float * );
  D3DXMATRIX( const D3DMATRIX& );
  D3DXMATRIX( float m00, float m01, float m02, float m03,
              float m10, float m11, float m12, float m13,
              float m20, float m21, float m22, float m23,
              float m30, float m31, float m32, float m33 );

  // 액세스 허가
  float& operator () ( UINT iRow, UINT iCol );
  float  operator () ( UINT iRow, UINT iCol ) const;

  // 연산자의 형태 변환
  operator float* ();
  operator const float* () const;

  operator D3DMATRIX* ();
  operator const D3DMATRIX* () 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;

#endif //__cplusplus

  union
  {
    float m[4][4];
#ifdef __cplusplus
    struct
    {
      float m00, m01, m02, m03;
      float m10, m11, m12, m13;
      float m20, m21, m22, m23;
      float m30, m31, m32, m33;
    };
#endif //__cplusplus


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


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


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


D3DXVECTOR3 확장 기능

D3DXVECTOR3 구조체는, 다음의 연산자 overload와 형태 변환을 제공하고 있다.

#ifdef __cplusplus
public:
  D3DXVECTOR3() {};
  D3DXVECTOR3( const float * );
  D3DXVECTOR3( const D3DVECTOR& );
  D3DXVECTOR3( float x, float y, float z );

  // 변환
  operator float* ();
  operator const float* () const;

  operator D3DVECTOR* ();
  operator const D3DVECTOR* () 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;

public:
#endif //__cplusplus


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


열거형

여기에서는, Direct3DX 유틸리티 라이브러리에서 사용되고 있는 다음의 열거형에 대해 기술한다.

  • D3DX_FILTERTYPE
  • D3DX_SURFACECLASS
  • D3DX_SURFACEFORMAT


D3DX_FILTERTYPE

D3DX_FILTERTYPE 열거형은, Direct3DX 텍스쳐 함수의 필터링 타입을 정의한다.

typedef enum _D3DX_FILTERTYPE {
  D3DX_FT_POINT    = 0x01,
  D3DX_FT_LINEAR   = 0x02,
  D3DX_FT_DEFAULT  = D3DX_DEFAULT
} D3DX_FILTERTYPE;
D3DX_FT_POINT
점샘플링만. 필터링은 실시하지 않는다.
D3DX_FT_LINEAR
바이리니아피르타링.
D3DX_FT_DEFAULT
디폴트의 필터링 타입.

주의

D3DX_FILTERTYPE 열거형의 멤버는, 밉맵 생성시의 다양한 필터링 타입이다.

Direct3DX 에서는, 바이리니아 (D3DX_FT_LINEAR)와 점샘플링 (D3DX_FT_POINT)의 2 종류의 필터링을 지원 하고 있다. 사이즈 변경이나 밉맵 생성으로 보다 높은 품질을 요구한다면, 바이리니아피르타링을 선택한다. 보다 빠른 처리 속도를 요구한다면, D3DX_FT_POINT 를 선택한다.

메모 몇개의 특별한 케이스에서는, 내부에 텍스트가 있는 이미지로 희미해지지 않게 하기 위해서, 점샘플링과 밉맵화의 무효를 실시하면 좋다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.

참조

D3DXLoadTextureFromMemory ,D3DXLoadTextureFromSurface


D3DX_SURFACECLASS

D3DX_SURFACECLASS 열거형은, 기존의 유저가 정보를 취득한 표면 클래스를 정의한다.

typedef enum _D3DX_SURFACECLASS {
  D3DX_SC_DEPTHBUFFER       = 0x01,
  D3DX_SC_STENCILBUFFER     = 0x02,
  D3DX_SC_COLORTEXTURE      = 0x04,
  D3DX_SC_BUMPMAP           = 0x08,
  D3DX_SC_LUMINANCEMAP      = 0x10,
  D3DX_SC_COLORRENDERTGT    = 0x20
} D3DX_SURFACECLASS;
D3DX_SC_DEPTHBUFFER
DDPF_ZPIXELS 플래그 또는 DDPF_ZBUFFER 플래그를 설정하는 모든 ddpf.
D3DX_SC_STENCILBUFFER
DDPF_STENCILBUFFER 플래그를 설정하는 모든 ddpf.
D3DX_SC_COLORTEXTURE
내부에 색정보를 가지고 있어 텍스쳐 처리로 사용 가능한 모든 표면.
D3DX_SC_BUMPMAP
DDPF_BUMPLUMINANCE 플래그 또는 DDPF_BUMPDUDV 플래그를 설정하는 모든 ddpf.
D3DX_SC_LUMINANCEMAP
DDPF_BUMPLUMINANCE 플래그 또는 DDPF_LUMINANCE 플래그를 설정하는 모든 ddpf.
D3DX_SC_COLORRENDERTGT
색정보를 가지고 있어 렌더링 타겟으로서 사용 가능한 모든 표면.

주의

디바이스에 의해 다양한 표면 클래스에 지원 되고 있는 다양한 표면 포맷을 문의할 수가 있다.

D3DX_SURFACECLASS 열거형의 멤버는, 사용법으로 응해 분류된 2 차원 (2D) 표면의 다양한 타입이다. 다만, 그러한 숫자는 중복 하고 있다. 예를 들어, D3DX_SC_STENCILBUFFER 와 D3DX_SC_DEPTHBUFFER 는 중복 하고 있다 (DirectX 7.0 의 이행에서는, 스텐실 비트와 깊이 비트는 같은 픽셀 포맷에 속하기 (위해)때문에).

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.

참조

D3DXGetMaxSurfaceFormats ,D3DXGetSurfaceFormat


D3DX_SURFACEFORMAT

D3DX_SURFACEFORMAT 열거형은, 열거 가능한 다양한 타입의 표면 포맷을 정의하고 있다. 다음에, 모든 Direct3DX 표면 클래스를 나타낸다.

typedef enum _D3DX_SURFACEFORMAT {
  D3DX_SF_UNKNOWN    = 0,
  D3DX_SF_R8G8B8     = 1,
  D3DX_SF_A8R8G8B8   = 2,
  D3DX_SF_X8R8G8B8   = 3,
  D3DX_SF_R5G6B5     = 4,
  D3DX_SF_R5G5B5     = 5,
  D3DX_SF_PALETTE4   = 6,
  D3DX_SF_PALETTE8   = 7,
  D3DX_SF_A1R5G5B5   = 8,
  D3DX_SF_X4R4G4B4   = 9,
  D3DX_SF_A4R4G4B4   =10,
  D3DX_SF_L8         =11,
  D3DX_SF_A8L8       =12,
  D3DX_SF_U8V8       =13,
  D3DX_SF_U5V5L6     =14,
  D3DX_SF_U8V8L8     =15,
  D3DX_SF_UYVY       =16,
  D3DX_SF_YUY2       =17,
  D3DX_SF_DXT1       =18,
  D3DX_SF_DXT3       =19,
  D3DX_SF_DXT5       =20,
  D3DX_SF_R3G3B2     =21,
  D3DX_SF_A8         =22,
  D3DX_SF_TEXTUREMAX =23,

  D3DX_SF_Z16S0      =256,
  D3DX_SF_Z32S0      =257,
  D3DX_SF_Z15S1      =258,
  D3DX_SF_Z24S8      =259,
  D3DX_SF_S1Z15      =260,
  D3DX_SF_S8Z24      =261,
  D3DX_SF_DEPTHMAX   =262,

  D3DX_SF_FORCEMAX  = (DWORD)(-1)
} D3DX_SURFACEFORMAT;
D3DX_SF_UNKNOWN
표면 포맷은 불명하다.
D3DX_SF_R8G8B8
24 비트의 RGB 픽셀 포맷.
D3DX_SF_A8R8G8B8
32 비트의 알파가 있는 ARGB 픽셀 포맷.
D3DX_SF_X8R8G8B8
32 비트의 RGB 픽셀 포맷. 다만, 색 마다 8 비트가 확보되고 있다.
D3DX_SF_R5G6B5
16 비트의 RGB 픽셀 포맷.
D3DX_SF_R5G5B5
16 비트의 픽셀 포맷. 다만, 색에 5 비트가, 투명도에 1 비트가 확보되고 있다.
D3DX_SF_PALETTE4
표면은, 4 비트의 인덱스 첨부 컬러이다.
D3DX_SF_PALETTE8
표면은, 8 비트의 인덱스 첨부 컬러이다.
D3DX_SF_A1R5G5B5
16 비트의 픽셀 포맷. 다만, 색에 5 비트가, 알파 (투명한 텍셀)에 1 비트가 확보되고 있다.
D3DX_SF_X4R4G4B4
16 비트의 RGB 픽셀 포맷. 다만, 색 마다 4 비트가 확보되고 있다.
D3DX_SF_A4R4G4B4
16 비트의 ARGB 픽셀 포맷.
D3DX_SF_L8
8 비트의 휘도(Luminance)만.
D3DX_SF_A8L8
16 비트의 알파 휘도(Luminance).
D3DX_SF_U8V8
16 비트의 범프 맵 포맷.
D3DX_SF_U5V5L6
16 비트의 휘도(Luminance)가 있는 범프 맵 포맷.
D3DX_SF_U8V8L8
24 비트의 휘도(Luminance)가 있는 범프 맵 포맷.
D3DX_SF_UYVY
UYVY 포맷 (PC98 준거).
D3DX_SF_YUY2
YUY2 포맷 (PC98 준거).
D3DX_SF_DXT1
S3 텍스쳐의 압축 방법 1.
D3DX_SF_DXT3
S3 텍스쳐의 압축 방법 3.
D3DX_SF_DXT5
S3 텍스쳐의 압축 방법 5.
D3DX_SF_R3G3B2
8 비트의 RGB 텍스쳐 포맷.
D3DX_SF_A8
8 비트의 알파만.
D3DX_SF_TEXTUREMAX
마지막 텍스쳐 포맷.
D3DX_SF_Z16S0
16 비트의 z 버퍼의 비트 깊이.
D3DX_SF_Z32S0
32 비트의 z 버퍼의 비트 깊이.
D3DX_SF_Z15S1
16 비트의 깊이 버퍼 포맷. 스텐실 버퍼에 1 비트가 확보되고 있다.
D3DX_SF_Z24S8
32 비트의 깊이 버퍼. 스텐실 버퍼에 8 비트가 확보되고 있다.
D3DX_SF_S1Z15
16 비트의 깊이 버퍼. 스텐실 버퍼에 1 비트가 확보되고 있다 (LSB).
D3DX_SF_S8Z24
32 비트의 깊이 버퍼. 스텐실 버퍼에 8 비트가 확보되고 있다 (LSB).
D3DX_SF_DEPTHMAX
최대 깊이 버퍼의 픽셀 포맷.
D3DX_SF_FORCEMAX
최대치를 강제 적용.

주의

Direct3DX 에는 DDPIXELFORMAT 는 없기 때문에 주의 해야 한다. 대신에,D3DX_SURFACEFORMAT 열거값이 픽셀 포맷을 나타낸다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이상이 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
버젼 : DirectX 7.0 이 필요.
헤더 : d3dxcore.h 로 선언.

참조

D3DXGetMaxSurfaceFormats ,D3DXGetSurfaceFormat


하드웨어 액셀러레이트 레벨 정수

Direct3DX 하드웨어 액셀러레이트 레벨 정수는, 사전에 정의된 하드웨어 액셀러레이트 레벨을 나타내, 디바이스 인덱스 (DWORD)가 필요한 장소에서 디폴트값으로서 사용할 수 있다. 이하에, Direct3DX 유틸리티 라이브러리에 의해 제공 떠날 수 있어 모든 하드웨어 액셀러레이트 레벨 정수를 나타낸다.

D3DX_DEFAULT
프라이머리 DirectDraw 디바이스로 사용 가능한 최고의 액셀러레이트 레벨.
D3DX_HWLEVEL_RASTER
rasterize 액셀러레이트. 대부분의 경우, 이것이 가장 유용한 레벨이 된다.
D3DX_HWLEVEL_REFERENCE
레퍼런스 이행. 이것은, 최저의 액셀러레이트 레벨이다.
D3DX_HWLEVEL_TL
변환과 라이팅의 액셀러레이트.
D3DX_HWLEVEL_2D
2D 액셀러레이트만. 이 레벨을 지정 하면, RGB 래스터라이저가 이행 된다.


반환값

에러는, 32 비트의 값으로 나타내진다. 이하에, Direct3DX 의 메소드나 함수로부터 돌려주어지는 값을 나타낸다. 각 메소드나 함수로부터 돌려주어지는 값에 대해서는, 각각의 설명을 참조할것.

D3DXERR_BADD3DXCONTEXT
Direct3DX 문맥이 무효이기 (위해)때문에, 요구된 처리가 실패했다.
D3DXERR_BITBLTFAILED
BitBlt 메소드의 호출이 실패했다.
D3DXERR_CANNOTRESIZEFULLSCREEN
풀 스크린 모드로 사이즈 변경은 행해지지 않기 때문에, 요구된 처리가 실패했다.
D3DXERR_CANNOTRESIZENONWINDOWED
윈도우화되어 있지 않은 문맥에서는 사이즈 변경은 행해지지 않기 때문에, 요구된 처리가 실패했다.
D3DXERR_CAPSNOTSUPPORTED
요구된 디바이스 능력이 지원되어 있지 않다.
D3DXERR_COLORDEPTHTOOLOW
Direct3DX 는 16 비트 이상의 색깊이 밖에 지원 하고 있지 않기 때문에, 요구된 처리가 실패했다.
D3DXERR_COULDNTUPDATECAPS
디스플레이 모드 변경 후, 능력 데이타베이스의 갱신이 실패했다.
D3DXERR_D3DXNOTSTARTEDYET
Direct3DX 가 초기화되어 있지 않았기 (위해)때문에, 요구된 처리가 실패했다. D3DXInitialize 함수를 호출해, 한번 더 시도하는 것으로, Direct3DX 를 초기화한다.
D3DXERR_ENUMFORMATSFAILED
표면 포맷의 열거시에 에러가 발생했다.
D3DXERR_FAILEDDRAWTEXT
텍스트는, 표면에의 렌더링에 실패했다.
D3DXERR_FAILEDGETCAPS
디바이스의 능력을 취득할 수 없었다.
D3DXERR_FAILEDQUATSLERP
2 개의 쿼터니온간의 스라프 (slerping) 처리가 실패했다.
D3DXERR_FRONTBUFFERALREADYEXISTS
프런트 버퍼가 이미 존재하고 있었기 때문에, 요구된 처리가 실패했다.
D3DXERR_FULLSCREENPRIMARYEXISTS
어플리케이션이 프라이머리 표면을 풀 스크린 모드로 사용하고 있기 (위해)때문에, 요구된 처리가 실패했다.
D3DXERR_GETDCFAILED
디바이스 정보를 취득할 수 없었다.
D3DXERR_IFLERROR
이미지 파일의 로드 라이브러리에서 에러가 발생했다.
D3DXERR_INITFAILED
Direct3DX 는, 그 자체의 초기화에 실패했다.
D3DXERR_INVALIDD3DXDEVICEINDEX
건네받은 디바이스 인덱스가 무효였기 때문에, 요구된 처리가 실패했다.
D3DXERR_INVALIDFILEFORMAT
파일 포맷이 무효이다.
D3DXERR_INVALIDMODE
디스플레이 모드가 무효이기 (위해)때문에, 요구된 처리가 실패했다.
D3DXERR_INVALIDPARAMETER
파라미터의 언젠가, 또는 몇개인가가 무효이기 (위해)때문에, 요구된 처리가 실패했다.
D3DXERR_MIPLEVELABSENT
이 표면에 그러한 밉맵 레벨이 없기 때문에, 요구된 처리가 실패했다.
D3DXERR_NOBACKBUFFERAVAILABLE
백 버퍼 표면이 생성되어 있지 않기 때문에, 요구된 처리가 실패했다.
D3DXERR_NODIRECTDRAWAVAILABLE
요구된 처리는, DirectDraw 오브젝트가 생성되어 있지 않기 때문에 실패했다.
D3DXERR_NODIRECT3DAVAILABLE
요구된 처리는, Direct3D 오브젝트가 생성되어 있지 않기 때문에 실패했다.
D3DXERR_NODIRECT3DDEVICEAVAILABLE
요구된 처리는, Direct3D 디바이스가 생성되어 있지 않기 때문에 실패했다.
D3DXERR_NOMATCHFOUND
적절히 일치하는 것이 발견되지 않았다.
D3DXERR_NOMEMORY
시스템으로 메모리 부족을 위해, 요구된 처리가 실패했다.
D3DXERR_NOPRIMARYAVAILABLE
프라이머리 표면이 생성되어 있지 않기 때문에, 요구된 처리가 실패했다.
D3DXERR_NOTEXTURE
이 텍스쳐를 백업 하는 표면이 없기 때문에, 요구된 처리가 실패했다.
D3DXERR_NOTINITIALIZED
Direct3DX 가 초기화되어 있지 않기 때문에, 요구된 처리가 실패했다.
D3DXERR_NOZBUFFER
z 버퍼 표면이 생성 되지 않았다.
D3DXERR_NOZBUFFERAVAILABLE
z 버퍼 표면이 생성되어 있지 않기 때문에, 요구된 처리가 실패했다.
D3DXERR_NULLPOINTER
파라미터로서 NULL 포인터가 건네받았기 때문에, 요구된 처리가 실패했다.
D3DXERR_STARTUPFAILED
Direct3DX 는 기동에 실패했다.
D3DXERR_SURFACENOTPALETTED
표면이 팔레트화되어 있지 않기 때문에, 요구된 처리가 실패했다.
D3DXERR_UNSUPPORTEDFILEFORMAT
이미지 파일 포맷이 미확인이기 때문에, 요구된 처리가 실패했다.


Direct3DX 유틸리티 라이브러리 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에는, Direct3DX 유틸리티 라이브러리에 대한 지원은 포함되지 않았다.

[C++]

여기에서는, DirectX SDK 에 포함되어 있는 이하의 샘플 어플리케이션에 대해 간단하게 설명한다. 이러한 샘플은, 주로 Direct3DX 유틸리티 라이브러리의 사용법을 나타내기 위한 것이다.

  • EnvMap 샘플
  • Gravity 샘플
  • Particle 샘플
  • Sprite 샘플
  • Tentacle 샘플
  • TrivFS 샘플
  • TrivWin 샘플

DirectX 의 샘플에는 Microsoft® Visual C++® 의 프로젝트 워크 스페이스 파일이 포함되어 있지만, 이러한 샘플을 올바르게 컴파일 하려면 , 개발 환경외의 설정을 확인해야 하는 경우가 있다. 상세한 것에 대하여는, 「DirectX 의 샘플 및 그 외의 DirectX 어플리케이션의 컴파일」을 참조할것.

모든 Direct3DX 샘플은, C 및 C++ 개발자에게 배려해 기술되고 있다.


EnvMap 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에는, Direct3DX 유틸리티 라이브러리에 대한 지원은 포함되지 않았다.

[C++]

설명

EnvMap 샘플은, 큐브 환경 맵을 나타내고 있다.

패스

소스 : (SDK 루트)\Samples\Multimedia\D3dx\Src\EnvMap

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\D3dx\Bin\EnvMap.exe

유저즈 가이드

유저 입력은 불필요하다.

프로그래밍 위에의 주의

이 샘플은, 큐브내에 반사구(공)체를 드로잉(Drawing) 하는 것으로써, 반사 이펙트를 생성 하는 방법을 나타내고 있다. 큐브 맵은, 6 개의 직교 방향내에서 장면을 렌더링 하는 것에 의해 생성 되는, 특별한 텍스쳐의 표면이다. 전통적인 환경 맵 이펙트가 사용되고 있다.

이 샘플에서는, Direct3DX 유틸리티 라이브러리의 헬퍼-클래스를 사용하고 있다.


Gravity 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에는, Direct3DX 유틸리티 라이브러리에 대한 지원은 포함되지 않았다.

[C++]

설명

Gravity 샘플은, 우주의 중심으로 소용돌이치는 입자의 무리를 표시한다.

패스

소스 : (SDK 루트)\Samples\Multimedia\D3dx\Src\Gravity

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\D3dx\Bin\Gravity.exe

유저즈 가이드

유저 입력은 불필요하다.

프로그래밍 위에의 주의

이 샘플은, 3-D 환경을 생성 해, 그 중에 오브젝트의 그룹을 애니메이션화하는 방법의 기본을 나타내고 있다. 여기에서는, 다양한 라이팅 이펙트를 사용하고 있다. 이 샘플은 또, 형상 생성용의 메소드와 Direct3DX 의 행렬 스택의 사용법을 나타내고 있다.

이 샘플에서는, Direct3DX 유틸리티 라이브러리의 헬퍼-클래스를 사용하고 있다.


Particle 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에는, Direct3DX 유틸리티 라이브러리에 대한 지원은 포함되지 않았다.

[C++]

설명

Particle 샘플은, 빌보드 이펙트의 사용법을 나타내고 있다.

패스

소스 : (SDK 루트)\Samples\Multimedia\D3dx\Src\Particle

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\D3dx\Bin\Particle.exe

유저즈 가이드

이하의 키를 사용해, 표시를 제어한다. NumLock 를 유효하게 해 둘 필요가 있다.

이동 | W,S
슬라이드 | 방향 키
회전 | 숫자 패드의 4,6
피치 | 숫자 패드의 2,8
색의 변경 | Space
지면의 변환 | G
반사의 변환 | R
장소의 변환 | Enter
일시정지 | Pause
종료 | Esc

프로그래밍 위에의 주의

표시되는 각 입자는, 실제로는 텍스쳐 맵이 적용된 빌보드면이다. 라이팅 이펙트와 지면 위에의 반사가 이행 되고 있다.

이 샘플에서는, Direct3DX 유틸리티 라이브러리의 헬퍼-클래스를 사용하고 있다.


Sprite 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에는, Direct3DX 유틸리티 라이브러리에 대한 지원은 포함되지 않았다.

[C++]

설명

Sprite 샘플은, 3-D 엔진을 사용해 고전적인 2-D 스프라이트 조작을 실행하는 방법을 나타내고 있다.

패스

소스 : (SDK 루트)\Samples\Multimedia\D3dx\Src\Sprite

실행 가능 파일: (SDK 루트)\Samples\Multimedia\D3dx\Bin\Sprite.exe

유저즈 가이드

유저 입력은 불필요하다.

프로그래밍 위에의 주의

이 샘플에서는, Direct3DX 유틸리티 라이브러리의 헬퍼-클래스를 사용하고 있다.


Tentacle 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에는, Direct3DX 유틸리티 라이브러리에 대한 지원은 포함되지 않았다.

[C++]

설명

Tentacle 샘플을 사용 하면, 3-D 환경을 대화형으로 조작할 수가 있다.

패스

소스 : (SDK 루트)\Samples\Multimedia\D3dx\Src\Tentacle

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\D3dx\Bin\Tentacle.exe

유저즈 가이드

키보드에 의한 제어 (NumLock 를 유효하게 해 두는 것)

이동 | W,S
슬라이드 | 방향 키
회전 | 숫자 패드의 4,6
피치 | 숫자 패드의 2,8
롤 | 숫자 패드의 7,9
와이어 프레임의 변환 | F2
종료 | Esc

마우스에 의한 제어

왼팔의 회전 | 왼쪽 버튼
오른 팔의 회전 | 오른쪽 버튼
토대의 회전 | 왼쪽 버튼 + 오른쪽 버튼
왼팔의 스핀 | Shift + 왼쪽 버튼
오른 팔의 스핀 | Shift + 오른쪽 버튼
토대의 스핀 | Shift + 왼쪽 버튼 + 오른쪽 버튼
좌지의 신축(스트레치) | Ctrl + 왼쪽 버튼
우지의 신축(스트레치) | Ctrl + 오른쪽 버튼

프로그래밍 위에의 주의

이 프로그램은, DirectX 7.0 의 새로운 기능인 버텍스 블렌딩 및 유저 클립면을 나타내고 있다. 또, 반사 이펙트와 렌즈 플레어를 표시한다.

이 샘플에서는, Direct3DX 유틸리티 라이브러리의 헬퍼-클래스를 사용하고 있다.


TrivFS 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에는, Direct3DX 유틸리티 라이브러리에 대한 지원은 포함되지 않았다.

[C++]

설명

TrivFS 샘플은, 삼각형을 y 축상에서 회전한다.

패스

소스 : (SDK 루트)\Samples\Multimedia\D3dx\Src\TrivFS

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\D3dx\Bin\TrivFS.exe

유저즈 가이드

유저 입력은 불필요하다.

프로그래밍 위에의 주의

이 샘플은, Direct3DX 유틸리티 라이브러리를 사용해, 풀 스크린의 어플리케이션을 초기화하는 방법을 나타내고 있다.


TrivWin 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에는, Direct3DX 유틸리티 라이브러리에 대한 지원은 포함되지 않았다.

[C++]

설명

TrivWin 샘플은, 삼각형을 y 축상에서 회전한다.

패스

소스 : (SDK 루트)\Samples\Multimedia\D3dx\Src\TrivWin

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\D3dx\Bin\TrivWin.exe

유저즈 가이드

유저 입력은 불필요하다.

프로그래밍 위에의 주의

이 샘플은, Direct3DX 유틸리티 라이브러리를 사용해, 윈도우화 된 어플리케이션을 초기화하는 방법을 나타내고 있다.

이 샘플에서는, Direct3DX 유틸리티 라이브러리의 헬퍼-클래스를 사용하고 있다.


Direct3D 보관 유지 모드의 문서

Direct3D 보관 유지 모드 버젼 6.0 으로 그 문서는, 이 SDK 에 포함되어 있다. Direct3D 보관 유지 모드의 향후의 버전 업은 예정되지 않았다.

Direct3D 보관 유지 모드는 DirectX Foundation 의 일부에서는 없지만, C, C++, 및 Visual Basic 로 기술한 어플리케이션으로, Direct3D 보관 유지 모드의 기능과 서비스를 사용할 수가 있다. Direct3D 보관 유지 모드 API 의 문서는, 이 SDK 에 포함되어 있다. 상세한 것에 대하여는, 「Direct3D 보관 유지 모드의 소개」를 참조할것.

주 : Direct3D 보관 유지 모드의 문서에는, C 및 C++ 개발자를 위한 완전한 개요와 레퍼런스, 및 Visual Basic 개발자를 위한 새로운 레퍼런스 머트리얼이 포함되어 있다.


DirectDraw

여기에서는, DirectX® 어플리케이션 프로그래밍 인터페이스 (API)의 DirectDraw® 컴퍼넌트에 대해 기술한다. 이하의 토픽에 대해 설명한다.

  • DirectDraw 에 대해
  • DirectDraw 를 사용하는 이유
  • 그래픽스의 기본 개념의 이해
  • DirectDraw 아키텍쳐
  • DirectDraw 의 요점
  • DirectDraw 튜토리얼
  • DirectDraw 레퍼런스
  • DirectDraw 의 툴과 샘플


DirectDraw 에 대해

DirectDraw® 는, DirectX® 어플리케이션 프로그래밍 인터페이스 (API)의 컴퍼넌트이며, 디스플레이 메모리,하드웨어 블리트 (블록 전송), 하드웨어 오버레이의 지원, 및플립핑 표면의 지원등의 직접 조작을 가능하게 한다. DirectDraw 는, 기존의 Microsoft® Windows® 베이스의 어플리케이션이나 디바이스 드라이버와의 호환성을 유지하면서, 이러한 기능을 제공한다.

DirectDraw 는, Windows 그래픽스 디바이스 인터페이스 (GDI)와의 호환성을 유지하면서도, 어디까지나 디스플레이 디바이스에의 직접 액세스를 제공하는 소프트웨어 인터페이스이며, 그래픽스용의 상위 레벨의 어플리케이션 프로그래밍 인터페이스 (API)는 아니다. 3 차원 (3D)의 그래픽스 패키지나 디지털 비디오 코덱을 이용한 게임이나 Windows 서브 시스템의 소프트웨어에 대해서, 디바이스에 의존하지 않는 특정의 디스플레이 디바이스 기능에의 액세스를 실현하는 것이다.

DirectDraw 는, 다양한 디스플레이 하드웨어로 동작한다. 그 범위는, 단순한 SVGA 모니터로부터, 클리핑,신축(스트레치), 및 비 RGB 색포맷을 지원 하는 최신의 하드웨어에까지 도달한다. DirectDraw 의 인터페이스는, 기초가 되는 하드웨어의 능력을 인식해, 지원 된 모든 하드웨어 가속화를 사용할 수 있도록(듯이) 설계되고 있다. 하드웨어가 이행 하고 있지 않는 기능은, DirectX 로 에뮬레이트 할 수가 있다.

DirectDraw 는, 디바이스에 의존한 디스플레이 메모리에의 액세스를, 디바이스에 의존하지 않는 방법으로 제공한다. DirectDraw 가 디스플레이 메모리를 관리한다. 어플리케이션은, 하드웨어 이행에 관한 표준적 없는 구두인가의 기본적 디바이스 종속성 (예를 들어 RGB, YUV 의 컬러 포맷, 라스터 라인간의피치등)을 인식하는 것만으로 좋다. 블리트를 사용하거나 팔레트 레지스터를 조작하기 위해서, 특별한 프로시저를 호출할 필요는 없다. DirectDraw 를 사용하면(자), 다른 타입의 디스플레이 하드웨어가 가지는 블리트나, 컬러 압축의 복원 능력을 풀로 꺼내면서, 게다가 하드웨어의 특정의 부분에 의존하는 일 없이, 디스플레이 메모리를 용이하게 조작할 수가 있다.

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


DirectDraw 를 사용하는 이유

DirectDraw 컴퍼넌트는, Windows 그래픽스 프로그래머에게 많은 강력한 기능을 제공한다.

  • DirectDraw 의하드웨어 추상 계층 (HAL) 은, 디스플레이 하드웨어나 비디오 메모리를 직접 동작시키기 위해서(때문에), 일관성이 있는 인터페이스를 제공한다. 이것을 이용해, 시스템 하드웨어로부터 최대의 퍼포먼스를 얻을 수 있다.
  • DirectDraw 에서는, 가능한 한, 비디오 하드웨어의 기능을 사용해, 그 능력을 발휘시킨다. 예를 들어, 비디오 카드가 하드웨어 블리트를 지원 하는 경우, DirectDraw 는 비디오 카드에 블리트를 맡기는 것으로, 크게 퍼포먼스를 향상시킨다. 게다가 DirectDraw 에서는 하드웨어 에뮬레이션 계층 (HEL)을 제공해, 하드웨어에 이행되어 있지 않은 기능을 지원 한다.
  • DirectDraw 는 Windows 시스템의 제공하는 32 비트 메모리 주소 지정이나 플랫 메모리 모델의 이점을 받게 된다. DirectDraw 는, 비디오나 시스템의 메모리를 작은 세그먼트(segment)로서가 아니고, 스토리지의 큰 블록으로서 제시한다. 세그먼트(segment) (오프셋(offset)의 주소 지정)를 사용했던 적이 있으면, 이“플랫”메모리 모델의 이해는 간단하다.
  • DirectDraw 는, 풀 스크린 어플리케이션에서의 복수백 버퍼에 의한페이지 플립핑의 실현을 용이하게 한다. 상세한 것에 대하여는, 「페이지 플립핑과 백 버퍼링」을 참조할것.
  • 윈도우 또는 풀 스크린 어플리케이션에서의 클리핑의 지원.
  • 3D 에서의 Z 버퍼의 지원.
  • Z 오더링 첨부의 하드웨어 지원 오버레이의 지원.
  • 이미지신축(스트레치) 하드웨어에의 액세스.
  • 표준 및 개량형 디스플레이 디바이스 메모리 영역에의 동시 액세스.
  • 그 외의 기능으로서 커스텀, 동적 팔레트, 배타적 하드웨어 액세스, 및 해상도의 변환등이 있다.

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


그래픽스의 기본 개념의 이해

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

여기서의 내용을 이해하는데, 그래픽스의 전문가일 필요는 없다. 그래픽스의 기본 개념을 이해하고 있는 것 있으면, 게다가 자세하게 설명하고 있는 「DirectDraw 의 요점」에 직접 진행되어도 괜찮다. C 나 C++, 또는 Visual Basic 의 Windows 프로그래밍의 지식이 있으면, 여기서의 내용은 그다지 이해가 곤란하지 않다. 이하의 주제를 다 읽으면, 기본적인 DirectDraw 그래픽스 프로그래밍의 개념을 충분히 이해할 수가 있다.

다음의 항목에 대해 기술한다.

  • 디바이스에 의존하지 않는 비트 맵
  • 드로잉(Drawing) 표면
  • 블리트
  • 페이지 플립핑과 백 버퍼링
  • 직사각형에 대해


디바이스에 의존하지 않는 비트 맵

Windows 그리고 DirectX 는, 네이티브인 그래픽스 파일 포맷으로서 디바이스에 의존하지 않는 비트 맵 (DIB)을 사용한다. DIB 란, 이미지의 넓이, 그것이 사용하는 색 가지수, 그러한 색을 기술하는 값, 및 각각의 픽셀을 기술하는 데이터등의 정보를 포함한 파일이다. 또한 DIB 에는, 파일 압축, 유의 컬러 (모든 색이 사용되지 않는 경우), 및 이미지의 물리적 넓이 (인쇄되는 경우)라고 한, 그다지 사용되지 않는 파라미터도 있다. 보통, DIB 파일의 확장자(extension)는 ". bmp" 이지만,". dib" 의 경우도 있다.

[C++]

DIB 는 Windows 프로그래밍으로 넓게 보급되어 있기 (위해)때문에, 플랫폼 SDK 에는, DirectX 로 이용할 수 있는 많은 함수가 포함되어 있다. 다음의 예는, Win32® 함수와 DirectX 함수를 조합해 DirectX 표면에 DIB 를 로드하는 어플리케이션 정의의 함수이다. 이것은, 플랫폼 SDK 의 DirectX API 내의 Ddutil.cpp 파일에 포함되어 있다.

extern "C" IDirectDrawSurface * DDLoadBitmap(IDirectDraw *pdd,
    LPCSTR szBitmap, int dx, int dy)
{
    HBITMAP             hbm;
    BITMAP              bm;
    DDSURFACEDESC       ddsd;
    IDirectDrawSurface *pdds;

    //
    //  여기가 Win32 부분.
    //  비트 맵을 리소스로서 로드한다.
    //  실패 하면, 파일로서 로드한다.
   //
    hbm = (HBITMAP) LoadImage(
            GetModuleHandle(NULL), szBitmap,
            IMAGE_BITMAP, dx, dy, LR_CREATEDIBSECTION);

    if (hbm == NULL)
        hbm = (HBITMAP) LoadImage(
                NULL, szBitmap, IMAGE_BITMAP, dx, dy,
                LR_LOADFROMFILE|LR_CREATEDIBSECTION);

    if (hbm == NULL)
        return NULL;

    //
    // 비트 맵의 사이즈를 취득한다.
    //
    GetObject(hbm, sizeof(bm), &bm);

    //
    // 여기서, DirectX 함수의 호출하러 돌아온다.
    // 이 비트 맵의 DirectDrawSurface 를 생성 한다.
    //
    ZeroMemory(&ddsd, sizeof(ddsd));
    ddsd.dwSize = sizeof(ddsd);
    ddsd.dwFlags = DDSD_CAPS | DDSD_HEIGHT |DDSD_WIDTH;
    ddsd.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN;
    ddsd.dwWidth = bm.bmWidth;
    ddsd.dwHeight = bm.bmHeight;

    if (pdd->CreateSurface(&ddsd, &pdds, NULL) ! = DD_OK)
        return NULL;

    DDCopyBitmap(pdds, hbm, 0, 0, 0, 0);

    DeleteObject(hbm);

    return pdds;
}

DIB 파일의 상세한 것에 대하여는, 플랫폼 SDK 를 참조할것.

[C++, Visual Basic]


드로잉(Drawing) 표면

드로잉(Drawing) 표면은, 스크린상에 이미지 (정확하게는 비트 맵)로서 표시되는 비디오 데이터를 받는다. 많은 Windows 프로그램은,GetDC (GetDC 는, 디바이스 콘텍스트 (DC)의 취득을 나타낸다)등의 Win32 함수를 사용해 드로잉(Drawing) 표면에 액세스 해, 디바이스 콘텍스트를 취득하는 것으로, 스크린상에 드로잉(Drawing)를 실시하고 있다. 그러나, Win32 그래픽스 함수는, 그래픽스 디바이스 인터페이스 (GDI)로부터 제공되고 있다. GDI 는, 표준의 Windows 어플리케이션이 스크린상에 드로잉(Drawing) 하기 위해서 사용하는 추상 계층을 제공하는 시스템 컴퍼넌트이다.

GDI 의 디메리트는, 워드프로세서나 표계산 어플리케이션 등 비지니스 어플리케이션에서의 이용을 목적으로 해 설계되고 있는 점이며, 하이 퍼포먼스 멀티미디어 소프트웨어로서 설계되고 있는 것은 아닌 것에 있다. GDI 에서는, 비디오 메모리는 아니고 시스템 메모리의 비디오 버퍼에 액세스 해, 비디오 카드가 가지고 있는 기능을 이용할 것도 없다. 즉, GDI 는, 많은 비지니스 어플리케이션에서는 그 위력을 발휘하지만, 멀티미디어 소프트나 게임 소프트에 대해서는, 그 퍼포먼스가 매우 저하한다.

이것에 대해서 DirectDraw 는, 실제의 비디오 메모리를 나타내는 드로잉(Drawing) 표면을 제공하고 있다. 이 때문에, DirectDraw 를 사용해 비디오 카드 위에의 메모리에 직접 기입할 수가 있어 그래픽스 루틴을 고속화할 수 있다. 이러한 표면은 연속한 메모리의 블록으로서 나타내져 거기서의 주소 지정이 용이하게 된다.

상세한 것에 대하여는, 「표면」을 참조할것.


블리트

blit 는 "bit block transfer" 의 약기이며, 메모리가 있는 장소로부터 다른 장소에 데이터의 블록을 전송 하는 프로세스이다. 그래픽스 프로그래머는 블리트를 사용해, 메모리중이 있는 장소로부터 다른 장소에 그래픽스를 전송 한다. 블리트는, 다음에 설명하는 스프라이트 애니메이션을 실행하기 위해(때문에) 이용되는 일도 있다.

DirectDraw 의 블리트의 상세한 것에 대하여는, 「표면에의 블리트」를 참조할것.


페이지 플립핑과 백 버퍼링

페이지 플립핑은, 멀티미디어나 애니메이션, 게임등의 소프트웨어로 주요가 된다. 소프트웨어 페이지 플립핑은, 애니메이션을 종이의 다발로 실시하는 방법을 닮아 있다. 각 페이지 마다, 애니메이션 작가는 인물을 조금 변화시켜, 프레임을 빨리 플립 시키면(자) 그 그림은 애니메이션과 같이 보인다.

소프트웨어에서의 페이지 플립핑은, 이 프로세스와 자주(잘) 비슷하다. 최초로, 애니메이션 작가의 종이를 다음의 페이지에 플립 하도록(듯이), 스크린에“플립”하는 일련의 DirectDraw 표면을 셋업 한다. 최초의 표면은프라이머리 표면으로 불려 거기에 계속되는 표면은백 버퍼로 불린다. 최초로 어플리케이션은 백 버퍼에 쓰기, 다음에 백 버퍼가 스크린상에 나타나도록(듯이) 프라이머리 표면을 플립 시킨다. 시스템이 이미지를 표시하고 있는 동안, 소프트웨어는 다시 백 버퍼에 기입한다. 이 프로세스는 애니메이션의 사이 계속되어, 재빠르게 효율적으로 이미지를 애니메이션 시킨다.

DirectDraw 는, 비교적 단순한 더블 버퍼 스킴 (1 개의 백 버퍼를 가지는 프라이머리 표면)으로부터, 추가의 백 버퍼를 부가했던 것보다 고도의 스킴까지,페이지 플립핑 스킴의 셋업을 용이하게 한다. 상세한 것에 대하여는, 「DirectDraw 튜토리얼」 및 「플립핑 표면」을 참조할것.


직사각형에 대해

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

[C++]

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

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

Visual Basic 에 있어서의 RECT 형의 정의를 이하에 나타낸다.

Type RECT
    Left As Long     '이것은, 좌상의 모퉁이의 x 좌표.
    Top As Long      '이것은, 좌상의 모퉁이의 y 좌표.
    Right As Long    '이것은, 우하의 모퉁이의 x 좌표.
    Bottom As Long   '이것은, 우하의 모퉁이의 y 좌표.
End Type

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

효율, 일관성, 편리한 사용등을 (위해)때문에에, 모든 DirectDraw 블리트 함수는 직사각형 범위를 사용한다. 그러나, 투과형 블리트를 사용하는 것으로써, 비직사각형의 블리트도 실시할 수 있다. 상세한 것에 대하여는, 「투과형 블리트」를 참조할것.


DirectDraw 아키텍쳐

여기에서는, DirectDraw 컴퍼넌트와 그 외의 DirectX 컴퍼넌트간의 관계, operating system, 및 시스템 하드웨어에 대해 설명한다. 다음의 항목에 대해 기술한다.

  • DirectDraw 아키텍쳐의 개요
  • DirectDraw 오브젝트 타입
  • 하드웨어 추상 계층 (HAL)
  • 소프트웨어 에뮬레이션
  • 시스템의 통합


DirectDraw 아키텍쳐의 개요

멀티미디어 소프트웨어는, 하이 퍼포먼스인 그래픽스를 요구한다. Microsoft 는, DirectDraw 에 의해 디바이스의 독립성을 유지하면서, GDI 를 사용하는 경우보다 아득하게 하이레벨의 효율과 스피드를 가지는 그래픽스 중시의 Windows 어플리케이션을 개발할 수 있도록(듯이) 한다. DirectDraw 에서는, 이하에 주는 것 같은 주요 태스크를 실행하기 위한 툴을 제공한다.

  • 복수의 디스플레이 표면의 조작
  • 비디오 메모리에의 직접 액세스
  • 페이지 플립핑
  • 백 버퍼링
  • 팔레트의 관리
  • 클리핑

게다가 DirectDraw 에 의해 실행시에 디스플레이 하드웨어의 능력을 조회할 수가 있게 되어, 호스트 컴퓨터의 하드웨어 능력에 있어서의 최적인 퍼포먼스를 제공한다.

다른 DirectX 컴퍼넌트와 같이, DirectDraw 는 가능한 한하드웨어를 최대한 이용하려고 한다. 또, 하드웨어 지원을 이용할 수 없는 경우, 대부분의 기능의 소프트웨어 에뮬레이션을 제공한다. 디바이스의 독립성은, 하드웨어 추상 계층 (HAL)을 이용하는 것으로써 가능해진다. HAL 의 상세한 것에 대하여는, 「하드웨어 추상 계층 (HAL)」를 참조할것.

[C++]

DirectDraw 컴퍼넌트는, COM 베이스의 인터페이스로부터 서비스를 제공한다. 최신의 인터페이스는,IDirectDraw7 ,IDirectDrawSurface7 ,IDirectDrawPalette ,IDirectDrawClipper , 및 IDirectDrawVideoPort 이다. 이러한 인터페이스 외에, DirectDraw 는 종래의 버젼 모든 것을 지원 하고 있다. DirectDraw 컴퍼넌트에는,IDirectDraw3,IDirectDraw5, 또는 IDirectDraw6 인터페이스라고 하는 버젼은 없다 (IDirectDraw2 로부터 IDirectDraw4, 및 IDirectDraw4 로부터 IDirectDraw7 에 인터페이스 버젼은 스킵 했다).

플랫폼 SDK 의 DirectX API 로 어플리케이션을 생성 하기 위해서 이해해야 할 COM 개념에 대해서는, 「컴퍼넌트 오브젝트 모델」을 참조할것.

DirectDraw 오브젝트는 디스플레이 어댑터를 나타내,IDirectDraw,IDirectDraw2,IDirectDraw4, 및 IDirectDraw7 인터페이스로부터 그 메소드를 공개한다. 대부분의 경우,DirectDrawCreateEx 함수를 사용해 최신의 DirectDraw 오브젝트를 생성 하지만,CoCreateInstance COM 함수를 사용해 생성 할 수도 있다. 상세한 것에 대하여는, 「CoCreateInstance 를 이용한 DirectDraw 오브젝트의 생성」을 참조할것.

DirectDraw 오브젝트를 생성 한 후,IDirectDraw7::CreateSurface 메소드를 호출해, 그 오브젝트의 표면을 생성 할 수가 있다. 표면은 디스플레이 하드웨어 위에의 메모리를 나타내지만, 비디오 메모리와 시스템 메모리의 어느 것에도 존재할 수가 있다. DirectDraw 는, 다른 인터페이스로부터, 팔레트, 클리핑 (윈도우 어플리케이션으로 자주(잘) 이용한다), 및 비디오 포트에 있어서의 지원을 확장한다.

[Visual Basic]

DirectDraw 컴퍼넌트는, DirectX for Visual Basic 타입 라이브러리의 클래스로부터 서비스를 제공한다. 최신 버젼에서는, 이러한 클래스로서DirectDraw7 ,DirectDrawSurface7 ,DirectDrawPalette ,DirectDrawClipper 가 있다.

또, 타입 라이브러리에 의해, 드라이버, 모드 및 표면의 열거에 사용되는 오브젝트도 제공한다. 이러한 오브젝트로서는,DirectDrawEnum ,DirectDrawEnumModes , 및 DirectDrawEnumSurfaces 가 있다.

DirectDraw7 클래스로부터 생성 된 DirectDraw 오브젝트는, 디스플레이 어댑터를 나타낸다. 이 오브젝트를 생성 하려면 , 글로벌 DirectX7 오브젝트의 DirectDrawCreate 메소드를 사용한다.

DirectDraw 오브젝트를 생성 한 후,DirectDraw7.CreateSurface 메소드를 호출해, 그 오브젝트의 표면을 생성 할 수가 있다. 표면은 디스플레이 하드웨어 위에의 메모리를 나타내지만, 비디오 메모리와 시스템 메모리의 어느 것에도 존재할 수가 있다. DirectDraw 는, 다른 인터페이스로부터, 팔레트 및 클리핑 (윈도우 어플리케이션으로 자주(잘) 이용한다)에 있어서의 지원을 확장한다.


DirectDraw 오브젝트 타입

DirectDraw 는, 모두 작용하는 몇개의 오브젝트로 구성된다고 생각된다. 여기에서는, 오브젝트 타입 마다, DirectDraw 컴퍼넌트를 이용하는 경우에 사용하는 오브젝트에 대해 간단하게 설명한다. 상세한 것에 대하여는, 「DirectDraw 의 요점」을 참조할것.

[C++]

DirectDraw 컴퍼넌트는, 이하의 오브젝트를 사용한다.

DirectDraw 오브젝트
DirectDraw 오브젝트는, 모든 DirectDraw 어플리케이션의 핵심이 되는 것이다. 생성 하는 최초의 오브젝트이며, 관련하는 다른 모든 오브젝트를 생성 하기 위해서 사용하기 때문이다. DirectDraw 오브젝트를 생성 하려면 ,DirectDrawCreateEX 함수를 호출한다. DirectDraw 오브젝트는,IDirectDraw,IDirectDraw2,IDirectDraw4, 및 IDirectDraw7 인터페이스로부터 그 기능을 공개한다. 상세한 것에 대하여는, 「DirectDraw 오브젝트」를 참조할것.
DirectDrawSurface 오브젝트
DirectDrawSurface 오브젝트 (단지 "표면" 이라고도 불린다)는, 메모리중이 있는 영역을 나타낸다. 그 영역에는, 이미지로서 모니터상에 표시하는지, 또는 다른 표면에 전송 하는 데이터가 보관 유지되고 있다. 표면을 생성 하려면 , 대부분 DirectDraw 오브젝트의 IDirectDraw7::CreateSurface 메소드를 호출한다. 생성 한 표면은, 그 오브젝트와 관련지을 수 있다. DirectDrawSurface 오브젝트는,IDirectDrawSurface,IDirectDrawSurface2,IDirectDrawSurface3,IDirectDrawSurface4, 및 IDirectDrawSurface7 인터페이스로부터 그 기능을 공개한다. 상세한 것에 대하여는, 「표면」을 참조할것.
DirectDrawPalette 오브젝트
DirectDrawPalette 오브젝트 (단지“팔레트”라고도 불린다)는, 표면과 함께 사용하는 16 없고 256 컬러 인덱스 첨부 팔레트를 나타낸다. 이 오브젝트에는, 표면내의 값과 관련지을 수 있었던 컬러를 기술하는 일련의 인덱스 RGB 셋잇단음표가 포함되어 있다. 8 비트 이상의 픽셀 포맷 깊이를 사용하는 표면과 함께 팔레트를 사용할 수 없다. DirectDrawPalette 오브젝트를 생성 하려면 ,IDirectDraw7::CreatePalette 메소드를 호출한다. DirectDrawPalette 오브젝트는,IDirectDrawPalette 인터페이스로부터 그 기능을 공개한다. 상세한 것에 대하여는, 「팔레트」를 참조할것.
DirectDrawClipper 오브젝트
DirectDrawClipper 오브젝트 (단지 “클립퍼”라고도 불린다)는, 표면이 있는 부분이나 표면의 경계를 넘어 블리트를 하는 것을 저지한다. 클립퍼를 생성 하려면 ,IDirectDraw7::CreateClipper 메소드를 호출한다. DirectDrawClipper 오브젝트는,IDirectDrawClipper 인터페이스로부터 그 기능을 공개한다. 상세한 것에 대하여는, 「클립퍼」를 참조할것.
DirectDrawVideoPort 오브젝트
DirectDrawVideoPort 오브젝트는, 몇개의 시스템에 존재하는 비디오 포트 하드웨어를 나타낸다. 이 하드웨어에 의해, CPU 에 액세스 하거나 PCI 버스를 사용하지 않고 frame buffer에 직접 액세스 할 수가 있다. DirectDrawVideoPort 오브젝트를 생성 하려면 , IID_IDDVideoPortContainer 참조 식별자를 지정해 DirectDraw 오브젝트의 QueryInterface 메소드를 호출한다. DirectDrawVideoPort 오브젝트는,IDDVideoPortContainer 및 IDirectDrawVideoPort 인터페이스로부터 그 기능을 공개한다. 상세한 것에 대하여는, 「비디오 포트」를 참조할것.
[Visual Basic]

DirectDraw 컴퍼넌트는, 이하의 오브젝트를 사용한다.

DirectDraw 오브젝트
DirectDraw 오브젝트는, 모든 DirectDraw 어플리케이션의 핵심이 되는 것이다. 생성 하는 최초의 오브젝트이며, 관련하는 다른 모든 오브젝트를 생성 하기 위해서 사용하기 때문이다. DirectDraw 오브젝트를 생성 하려면 ,DirectX7.DirectDrawCreate 메소드를 호출한다. DirectDraw 는,DirectDraw7 오브젝트의 메소드로부터 그 기능을 공개한다. 상세한 것에 대하여는, 「DirectDraw 오브젝트」를 참조할것.
DirectDrawSurface 오브젝트
DirectDrawSurface 오브젝트 (단지 "표면" 이라고도 불린다)는, 메모리중이 있는 영역을 나타낸다. 그 영역에는, 이미지로서 모니터상에 표시하는지, 또는 다른 표면에 전송 하는 데이터가 보관 유지되고 있다. 표면을 생성 하려면 , 대부분 DirectDraw 오브젝트의 DirectDraw7.CreateSurface 메소드를 호출한다. 생성 한 표면은, 그 오브젝트와 관련지을 수 있다. DirectDrawSurface 오브젝트는,DirectDrawSurface7 오브젝트의 메소드로부터 그 기능을 공개한다. 상세한 것에 대하여는, 「표면」을 참조할것.
DirectDrawPalette 오브젝트
DirectDrawPalette 오브젝트 (단지“팔레트”라고도 불린다)는, 표면과 함께 사용하는 16 없고 256 컬러 인덱스 첨부 팔레트를 나타낸다. 이 오브젝트에는, 표면내의 값과 관련지을 수 있었던 컬러를 기술하는 일련의 인덱스 RGB 셋잇단음표가 포함되어 있다. 8 비트 이상의 픽셀 포맷 깊이를 사용하는 표면과 함께 팔레트를 사용할 수 없다. DirectDrawPalette 오브젝트를 생성 하려면 ,DirectDraw7.CreatePalette 메소드를 호출한다. DirectDrawPalette 오브젝트는,DirectDrawPalette 인터페이스로부터 그 기능을 공개한다. 상세한 것에 대하여는, 「팔레트」를 참조할것.
DirectDrawClipper 오브젝트
DirectDrawClipper 오브젝트 (단지“클립퍼”라고도 불린다)는, 표면이 있는 부분이나 표면의 경계를 넘어 블리트를 하는 것을 저지한다. 클립퍼를 생성 하려면 ,DirectDraw7.CreateClipper 메소드를 호출한다. DirectDrawClipper 오브젝트는,DirectDrawClipper 인터페이스로부터 그 기능을 공개한다. 상세한 것에 대하여는, 「클립퍼」를 참조할것.


하드웨어 추상 계층 (HAL)

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

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


소프트웨어 에뮬레이션

하드웨어가 하드웨어 추상 계층 (HAL)을 통해 있는 기능을 지원 하지 않는 경우, DirectDraw 는 그것을 에뮬레이트 하려고 한다. 이 에뮬레이트 된 기능은, 하드웨어 에뮬레이션 계층 (HEL)으로부터 제공된다. HAL 와 같게, HEL 는 그 능력을 DirectDraw 에 제공한다. 또 HAL 같이, 어플리케이션은 결코 직접 HEL 에 작용하지 않는다. 그 결과, 어느 기능이 하드웨어에 의하는지, 또는 HEL 로부터 지원 될지 어떨지에 관련되어 없고, 거의 모든 주요 기능이 투과형 지원이 된다.

소프트웨어 에뮬레이션은, 분명하게 하드웨어 기능이 제공하는 퍼포먼스에는 미치지 않다. C++ 의 IDirectDraw7::GetCaps 메소드 또는 Visual Basic 의 DirectDraw7.GetCaps 메소드를 사용해, 하드웨어의 지원 하는 기능을 조회할 수가 있다. 어플리케이션의 초기설정시에 이러한 능력을 조사하면(자), 어플리케이션 파라미터를 조정할 수가 있어 하드웨어 퍼포먼스의 다양한 레벨에 최적인 퍼포먼스를 제공할 수 있다.

하드웨어에 의해 지원 된 기능과 에뮬레이션의 조합해에 따라서는, 에뮬레이션만의 경우보다 퍼포먼스가 떨어지는 경우가 있다. 예를 들어, 디스플레이 디바이스 드라이버가 DirectDraw 를 지원 해, 신축(스트레치) 블리트를 지원 하지 않는 경우, 비디오 메모리 표면으로부터 신축(스트레치) 블리트를 실시하면, 현저한 퍼포먼스의 저하가 보여진다. 이 퍼포먼스의 저하가 생기는 것은, 비디오 메모리가 시스템 메모리보다 늦은 경우가 많아, 비디오 메모리 표면에 액세스 할 경우에 CPU 가 기다리게 되기 때문이다. 어플리케이션이 하드웨어로 지원 하지 않는 기능을 사용할 때는, 시스템 메모리에 표면을 생성 하는 것이 좋은 경우가 있다. 이것에 의해, CPU 가 비디오 메모리에 액세스 할 경우에 생기는 퍼포먼스의 저하를 피할 수가 있다.

상세한 것에 대하여는, 「하드웨어 추상 계층 (HAL)」를 참조할것.


시스템의 통합

이하에 나타내는 그림은, 그래픽스 디바이스 인터페이스 (GDI), 하드웨어 추상 계층 (HAL), 하드웨어 에뮬레이션 계층 (HEL), 및 하드웨어와 DirectDraw 와의 관계이다.

이와 같이, DirectDraw 오브젝트는 GDI 와 함께 존재한다. 어느쪽이나, 디바이스 의존의 추상 계층으로부터 하드웨어에 직접 액세스 할 수가 있다. GDI 과는 달리, DirectDraw 는 할 수 있는 한, 항상 특별한 하드웨어 기능을 이용하려고 한다. 하드웨어가, 어느 기능을 지원 하지 않는 경우, DirectDraw 는 HEL 를 사용해 그 기능을 에뮬레이트 하려고 한다. DirectDraw 는, 디바이스 콘텍스트의 형태로 표면 메모리를 제공할 수 있으므로, 표면 오브젝트와 함께 작용하기 위한 GDI 함수를 사용할 수 있다.


DirectDraw 의 요점

여기에서는, DirectX® 의 DirectDraw® 컴퍼넌트의 일반적인 설명이 제공되고 있다. 이하의 항목에 대해 기술한다.

  • 협조 레벨
  • 디스플레이 모드
  • DirectDraw 오브젝트
  • 표면
  • 팔레트
  • 클립퍼
  • 멀티 모니터 시스템
  • DirectDraw 의 고도의 주제


협조 레벨

여기에서는, 협조 레벨의 개요와 일반적인 사용 상황에 대해 설명한다. 이하의 항목에 대해 기술한다.

  • 협조 레벨에 대해
  • 협조 레벨의 테스트


협조 레벨에 대해

협조 레벨은, DirectDraw 가 어떻게 디스플레이와 상호작용 해, 디스플레이에 영향을 주는 이벤트에 대해서 어떻게 반응하는지를 기술한다. DirectDraw 의 협조 레벨을 설정하려면 , C++ 의 IDirectDraw7::SetCooperativeLevel 메소드 또는 Visual Basic 의 DirectDraw7.SetCooperativeLevel 메소드를 사용한다. 대부분의 어플리케이션에서는 DirectDraw 의 협조 레벨을 사용해, 디스플레이에 배타 액세스를 실시하는 풀 스크린 프로그램으로서 실행하는지, 또는 윈도우 어플리케이션으로서 실행할까를 결정한다. 다만, DirectDraw 의 협조 레벨에는, 다음과 같은 이펙트도 있다.

  • DirectDraw 가 모드 X 해상도를 이용할 수 있도록(듯이) 한다. 상세한 것에 대하여는, 「모드 X 모드와 모드 13 디스플레이 모드」를 참조할것.
  • 유저가,CTRL + ALT + DEL (배타 모드만)를 눌렀을 경우, DirectDraw 가 디스플레이의 배타 컨트롤을 릴리즈 하거나 리부트하거나 하는 것을 저지한다.
  • 기동 이벤트에 응해, DirectDraw 가 어플리케이션을 최소화 또는 최대화할 수 있도록(듯이) 한다.

표준 협조 레벨은, DirectDraw 어플리케이션이 윈도우 어플리케이션으로서 동작하는 것을 나타낸다. 이 협조 레벨에서는,프라이머리 표면의 팔레트를 변경하거나페이지 플립핑을 실행할 수 없다.

어플리케이션은, 복수의 윈도우로 DirectDraw 를 사용할 수가 있으므로, 어플리케이션이 DDSCL_NORMAL 모드를 요구하고 있는 경우,IDirectDraw7::SetCooperativeLevel 및 DirectDraw7.SetCooperativeLevel 에는 윈도우 핸들을 지정할 필요는 없다. C++ 에서는 윈도우 핸들에 NULL 를, Visual Basic 에서는 Nothing 를 건네주는 것으로, 보통의 Windows 모드로 모든 윈도우를 동시에 사용할 수가 있다.

풀 스크린 또한 배타 협조 레벨에서는, 하드웨어를 최대한 이용할 수 있다. 이 모드에서는, 커스텀 팔레트나 동적 팔레트의 설정, 디스플레이 해상도의 변경, 및 페이지 플립핑의 실현을 할 수 있다. 배타 (풀 스크린) 모드에서는, 다른 어플리케이션이 표면을 할당하는 것을 막을 필요가 없고, DirectDraw 나 GDI 를 사용하는 일도 배제하지 않아 좋다. 다만, 배타 모드에서는, 배타 액세스를 가지는 현재의 어플리케이션 이외의 어플리케이션이 디스플레이 모드나 팔레트를 변경하는 것을 막는다.

DirectDraw 는, 필요한 SetCooperativeLevel 메소드로부터 등록된 윈도우 핸들에 WM_ACTIVATEAPP 메세지를 보내면서, 풀 스크린 (배타 모드의 어플리케이션)에 대한 윈도우 기동 이벤트의 컨트롤을 취득한다. DirectDraw 는, 기동 이벤트를 최상정도 윈도우인 만큼 보낸다. 어플리케이션이 기동 이벤트 메세지를 요구하는 자식 윈도우를 생성 하는 경우, 생성자의 책임으로 자식 윈도우를 서브 클래스화한다.

SetCooperativeLevel 는, 프로세스와 윈도우 핸들간의 결합을 보관 유지한다. 프로세스로 SetCooperativeLevel 를 호출하면, 그 프로세스와 윈도우간에 결합을 할 수 있다. 같은 프로세스내에서 다른 제로 이외의 윈도우 핸들을 주어 다시 호출하면,DDERR_HWNDALREADYSET 에러값이 돌려주어진다. 어플리케이션에 따라서는, DirectSound® 가 DirectDraw 와 다른 윈도우 핸들을 지정했을 때에 이 에러를 받는 일이 있다. 어느쪽이나, 동일한 최상정도 어플리케이션의 윈도우 핸들을 지정해야 한다.

[C++]

주 : Microsoft Foundation Classes (MFC)를 사용하고 있는 개발자는,SetCooperativeLevel 메소드에게 줄 수 있는 윈도우 핸들이, 그 어플리케이션의 최상정도 윈도우 (자식 윈도우로부터 파생한 윈도우는 아니다)를 식별하지 않으면 안 되는 것에 주의한다. MFC 어플리케이션의 최상정도 윈도우 핸들을 취득하려면 , 이하의 코드를 사용할 수 있다.

    HWND hwndTop = AfxGetMainWnd() ->GetSafeHwnd();

「멀티 모니터 시스템」도 참조할것.

[C++, Visual Basic]


협조 레벨의 테스트

개발자는, 어플리케이션으로 사용하는 표면을 restore 하거나 재생성 해야 할것을 통지하기 위해서, WM_ACTIVATEAPP 이나 WM_DISPLAYCHANGE 등의 메세지를 사용하는 일이 있다. 이러한 경우, 어플리케이션에서는 불필요한 때에 액션을 취득해, 필요한 때에는 액션을 취득하지 않는다. C++ 의IDirectDraw7::TestCooperativeLevel 메소드 또는 Visual Basic 의DirectDraw7.TestCooperativeLevel 메소드에 의해, 어플리케이션은 DirectDraw 오브젝트의 협조 레벨에 있어서의 상세 정보를 취득할 수 있어 아무 일도 없게 실행을 계속되는 적절한 스텝을 취득할 수 있다.

어플리케이션이 표면을 restore 성과 (이미 restore를 하지 않은 경우), 실행을 계속되면(자),TestCooperativeLevel 메소드는 DD_OK 를 돌려주어 성공한다. 또, 실패의 코드는, 어플리케이션으로 사용하는 협조 레벨과는 달라 판단된다.

풀 스크린 어플리케이션

배타적인 디바이스 액세스를 잃는 경우 (예를 들어, 유저가 ALT + TAB 를 눌러 현재의 어플리케이션을 바꾸는 경우), 풀 스크린 어플리케이션은 DDERR_NOEXCLUSIVEMODE 반환값을 받는다. 이 경우, 어플리케이션은, 메소드가 DD_OK (배타 모드가 돌려주어진 것을 의미한다)를 돌려줄 때만 종료하는 루프내의 TestCooperativeLevel 를 호출한다. 어플리케이션에서는, 루프내의 불필요한 사이클을 저지하기 위해서 CPU 를 제어하지 않는다. 이 때문에, Windows 에서는,WaitMessage 나 Sleep Win32 함수라고 하는 함수를 지원 한다.

모든 기존의 표면은,IDirectDrawSurface7::Restore , C++ 의 IDirectDraw7::RestoreAllSurfaces 메소드 또는 Visual Basic 의 DirectDrawSurface7.Restore 메소드를 호출하는 것으로 restore 되어 표면이 표시되기 전에 컨텐츠가 재로드 되지 않으면 안 된다.

윈도우 어플리케이션

윈도우 어플리케이션 이외의 어플리케이션으로 배타적인 디바이스 액세스를 취득하고 있는 경우, 윈도우 어플리케이션 (표준 협조 레벨을 사용하고 있다)은,DDERR_EXCLUSIVEMODEALREADYSET 를 받는다. 이 경우, 배타 액세스가 있는 어플리케이션이 그 액세스를 잃을 때까지, 액션은 취득되지 않는다. 이 상황은, 풀 스크린 어플리케이션의 경우 와 유사하다. 윈도우 어플리케이션은,TestCooperativeLevel 가 표면의 restore나 재로드의 앞에 DD_OK 를 돌려줄 때까지, 루프 한다. 전술한 것처럼, 이 어플리케이션과 같은 루프에서는, 루프중에 CPU 의 제어를 주기적으로 실시하지 않고, 불필요한 CPU 사이클의 사용을 피해야 하는 것이다.

디스플레이 모드가 변경되면(자),TestCooperativeLevel 메소드는 DDERR_WRONGMODE 를 윈도우 어플리케이션에 돌려준다. 이 경우, 이 어플리케이션에서는, 실행을 계속하기 전에 모든 표면을 파기해 재생성 하지 않으면 안 된다.


디스플레이 모드

여기에서는, DirectDraw 디스플레이 모드의 일반적인 설명을 한다. 다음의 항목에 대해 기술한다.

  • 디스플레이 모드에 대해
  • 지원 되는 디스플레이의 결정
  • 디스플레이 모드의 설정
  • 디스플레이 모드의 restore
  • 모드 X 모드와 모드 13 디스플레이 모드
  • 고해상도와 트루 컬러 비트 깊이의 지원


디스플레이 모드에 대해

디스플레이 모드란, 디스플레이 하드웨어가 프라이머리 표면으로부터 모니터에 보내는, 그래픽스의 넓이나 비트 깊이를 기술하는 하드웨어 설정이다. 디스플레이 모드는, 그것을 정의하는 특성, 즉 폭, 높이, 및 비트 깊이로 기술된다. 예를 들어, 대부분의 디스플레이 어댑터는, 폭이 640 픽셀로 높이가 480 픽셀의 그래픽스를 표시할 수 있다. 여기서, 각 픽셀은 8 비트의 데이터이다. 이 디스플레이 모드는, 640 × 480 × 8 으로 약기할 수가 있다. 디스플레이 모드의 넓이가 커지는지, 비트 깊이가 증가 하면, 한층 더 디스플레이 메모리가 필요하다.

디스플레이 모드에는, 팔레트화와 비팔레트화의 2 개의 타입이 있다. 팔레트화 디스플레이 모드에서는, 각각의 픽셀을 관련지을 수 있었던 팔레트에의 인덱스를 나타내는 값이 된다. 디스플레이 모드의 비트 깊이는, 팔레트에 넣는 색 가지수를 결정한다. 예를 들어, 8 비트의 팔레트화 디스플레이 모드에서는, 각 픽셀이 0 에서 255 의 값이 된다. 이러한 모드에서는, 팔레트에는 256 의 엔트리를 포함할 수가 있다.

비팔레트화 디스플레이 모드는, 이름으로부터 알도록(듯이) 팔레트를 사용하지 않는다. 비팔레트화 디스플레이 모드의 비트 깊이는, 픽셀을 기술하기 위해서 사용되는 전비트수를 나타낸다.

프라이머리 표면 및 프라이머리 플립핑 체인의 임의의 표면은, 디스플레이 모드의 넓이, 비트 깊이, 및 픽셀 포맷에 적합한다. 상세한 것에 대하여는, 「픽셀 포맷」을 참조할것.


지원 되는 디스플레이의 결정

[C++]

디스플레이 하드웨어에는 수많은 종류가 있기 (위해)때문에, 모든 디바이스가 모든 디스플레이 모드를 지원 할 것은 없다. 주어진 시스템으로 지원 되는 디스플레이 모드를 결정하려면 ,IDirectDraw7::EnumDisplayModes 메소드를 호출한다. 해당하는 값이나 플래그를 설정 하면,EnumDisplayModes 메소드는 지원 되는 모든 디스플레이 모드를 열거하는지, 지정한 각각의 디스플레이 모드가 지원 되고 있는 것을 확인한다. 이 메소드의 최초의 파라미터 dwFlags 는, 메소드에 대한 추가 옵션을 관리한다. 대부분의 경우,dwFlags 를 0 으로 설정해 추가 옵션을 무시한다. 2 번째의 파라미터 lpDDSurfaceDesc 는, 확인해야 할 주어진 디스플레이 모드를 기술하는 DDSURFACEDESC2 구조체의 주소이다. 보통, 이 파라미터를 NULL 로 설정해, 모든 모드의 열거를 요구한다. 3 번째의 파라미터 lpContext 는, DirectDraw 가 콜백 함수에 건네주는 포인터이다. 콜백 함수에 추가 데이터가 필요하지 않은 경우는, 이 파라미터를 NULL 로 설정한다. 마지막으로,lpEnumModesCallback 파라미터를, 지원 된 모드 마다 DirectDraw 가 호출하는 콜백 함수의 주소로 설정한다.

EnumDisplayModes 을 호출하면나무에게 주는 콜백 함수는,EnumModesCallback 함수의 prototype와 적합해야 한다. 하드웨어가 지원 하는 각 디스플레이 모드로, DirectDraw 는 2 개의 파라미터를 건네주어 콜백 함수를 호출한다. 최초의 파라미터는, 지원 되는 1 개의 디스플레이 모드를 기술하는 DDSURFACEDESC2 구조체의 주소이다. 2 번째의 파라미터는, 만약 있으면,EnumDisplayModes 를 호출하면나무로 지정한 어플리케이션 정의의 데이터의 주소로 한다.

DDSURFACEDESC2 구조체의 값을 조사해, 그것이 기술하는 디스플레이 모드를 결정한다. 주요한 구조체의 멤버는,dwWidth,dwHeight, 및 ddpfPixelFormat 멤버이다. dwWidth 와 dwHeight 멤버는, 디스플레이 모드의 넓이를 기술한다. ddpfPixelFormat 멤버는, 모드의 비트 깊이에 관한 정보를 포함한 DDPIXELFORMAT 구조체이다.

DDPIXELFORMAT 구조체는, 모드의 비트 깊이를 기술하는 정보를 전달해, 디스플레이 모드가 팔레트를 사용하고 있을지 어떨지를 전한다. dwFlags 멤버에 DDPF_PALETTEINDEXED1, DDPF_PALETTEINDEXED2, DDPF_PALETTEINDEXED4, 또는 DDPF_PALETTEINDEXED8 플래그가 있으면(자), 디스플레이 모드의 비트 깊이는 1, 2, 4, 또는 8 비트가 되어, 각 픽셀은 관련지을 수 있었던 팔레트에의 인덱스가 된다. dwFlags 가 DDPF_RGB 라면, 디스플레이 모드는 비팔레트화가 되어, 그 비트 깊이는 DDPIXELFORMAT 구조체의 dwRGBBitCount 멤버에게 줄 수 있다.

[Visual Basic]

디스플레이 하드웨어에는 수많은 종류가 있기 (위해)때문에, 모든 디바이스가 모든 디스플레이 모드를 지원 할 것은 없다. 주어진 시스템으로 지원 되는 디스플레이 모드를 결정하려면 ,DirectDraw7.GetDisplayModesEnum 메소드를 호출한다. 이 메소드는, 지원 되는 디스플레이 모드의 열거를 취득하는데 사용되는 DirectDrawEnumModes 오브젝트를 돌려준다. 해당하는 값이나 플래그를 설정 하면,GetDisplayModesEnum 메소드는,DirectDrawEnumModes 오브젝트에 지원 되는 모든 디스플레이 모드의 리스트를 묻는지, 또는 지정한 각각의 디스플레이 모드가 지원 되고 있는 것을 확인한다. 이 메소드의 최초의 파라미터 flags 는, 메소드에 대한 추가 옵션을 관리한다. 대부분의 경우,flags 를 DDEDM_DEFAULT 로 설정해 추가 옵션을 무시한다. 2 번째의 파라미터 ddsd 는, 확인해야 할 주어진 디스플레이 모드를 기술하는 DDSURFACEDESC2 형의 주소이다. 보통, 이 파라미터를 Nothing 로 설정해, 모든 모드의 열거를 요구한다.

GetDisplayModesEnum 메소드에 의해 DirectDrawEnumModes 오브젝트가 돌려주어지면(자),DirectDrawEnumModes.GetCount 메소드를 호출해, 지원 되는 디스플레이 모드로 사용 가능한 모드의 수를 확인할 수 있다. 다음에,DirectDrawEnumModes.GetItem 를 호출해,DirectDrawEnumModes 오브젝트에 포함되는 디스플레이 모드의 리스트로부터 각각의 디스플레이 모드의 설명을 취득한다.

GetItem 메소드에 의해 취득된 DDSURFACEDESC2 형의 값을 조사해, 그것이 기술하는 디스플레이 모드를 결정한다. 주요한 타입의 멤버는,lWidth,lHeight, 및 ddpfPixelFormat 멤버이다. lWidth 와 lHeight 멤버는, 디스플레이 모드의 넓이를 기술한다. ddpfPixelFormat 멤버는, 모드의 비트 깊이에 관한 정보를 포함한 DDPIXELFORMAT 형이다.

DDPIXELFORMAT 형은, 모드의 비트 깊이를 기술하는 정보를 전달해, 디스플레이 모드가 팔레트를 사용하고 있을지 어떨지를 전한다. lFlags 멤버에 DDPF_PALETTEINDEXED1, DDPF_PALETTEINDEXED2, DDPF_PALETTEINDEXED4, 또는 DDPF_PALETTEINDEXED8 플래그가 있으면(자), 디스플레이 모드의 비트 깊이는 1, 2, 4, 또는 8 비트가 되어, 각 픽셀은 관련지을 수 있었던 팔레트에의 인덱스가 된다. lFlags 가 DDPF_RGB 라면, 디스플레이 모드는 비팔레트화가 되어, 그 비트 깊이는 DDPIXELFORMAT 형의 lRGBBitCount 멤버에게 줄 수 있다.


디스플레이 모드의 설정

디스플레이 모드를 설정하려면 , C++ 의 IDirectDraw7::SetDisplayMode 메소드 또는 Visual Basic 의 DirectDraw7.SetDisplayMode 메소드를 사용한다. SetDisplayMode 메소드는, 설정하는 모드의 넓이, 비트 깊이, 및 refresh rate를 기술하는 4 개의 파라미터를 받는다. 이 메소드에서는, 5 번째의 파라미터를 이용해, 주어진 모드에 대한 특별한 옵션을 나타낸다. 현재, 옵션은 모드 13 으로 모드 X 320 × 200 × 8 디스플레이 모드를 구별하기 위해(때문에)인 만큼 사용되고 있다.

[C++]

바람직한 디스플레이 모드의 비트 깊이를 지정할 수 있지만, 그 비트 깊이에 대해서 사용하는 디스플레이 하드웨어의 픽셀 포맷을 지정할 수 없다. 현재의 비트 깊이에 대해서 사용하는 디스플레이 하드웨어의 RGB 비트 마스크를 결정하려면 , 디스플레이 모드를 설정하고 나서 IDirectDraw7::GetDisplayMode 를 호출한다. 현재의 디스플레이 모드가 팔레트화가 아니면, 정확한 적, 초록, 및 파랑의 비트를 결정하기 위해서(때문에),DDPIXELFORMAT 의 dwRBitMask,dwGBitMask, 및 dwBBitMask 멤버의 마스크값을 조사할 수가 있다. 상세한 것에 대하여는, 「픽셀 포맷 마스크」를 참조할것.

1 매의 디스플레이 카드를 모두 공유하고 있는 한, 1 개(살) 이상의 어플리케이션으로 모드를 변경할 수 있다. 디스플레이 모드의 비트 깊이는, DirectDraw 오브젝트에의 배타 액세스를 취득할 수 있었을 경우에만, 어플리케이션으로부터 변경할 수 있다. 모드가 변경되면(자), 모든 DirectDrawSurface 오브젝트는 표면 메모리를 잃어 조작 불능이 된다. 표면의 메모리는,IDirectDrawSurface7::Restore 메소드를 사용하는 것으로 재할인 맞히고 하지 않으면 안 된다.

DirectDraw 의 배타 (풀 스크린) 모드에서는, 다른 어플리케이션이 DirectDrawSurface 오브젝트를 할당할 수 있거나 DirectDraw 나 GDI 기능도 이용 가능해진다. 다만, 배타 모드 이외의 어플리케이션이 디스플레이 모드나 팔레트를 변경할 수 없다.

주 : 어플리케이션 윈도우를 생성 한 thread로부터는,IDirectDraw7::SetDisplayMod 메소드만을 호출할 수 있다. 단일의 thread화 된 어플리케이션 (대부분은 그렇다)에 대해서는, 이 제한은 문제가 되지 않는다.

[Visual Basic]

바람직한 디스플레이 모드의 비트 깊이를 지정할 수 있지만, 그 비트 깊이에 대해서 사용하는 디스플레이 하드웨어의 픽셀 포맷을 지정할 수 없다. 현재의 비트 깊이에 대해서 사용하는 디스플레이 하드웨어의 RGB 비트 마스크를 결정하려면 , 디스플레이 모드를 설정하고 나서 DirectDraw7.GetDisplayMode 를 호출한다. 현재의 디스플레이 모드가 팔레트화가 아니면, 정확한 적, 초록, 및 파랑의 비트를 결정하기 위해서(때문에),DDPIXELFORMAT 의 lRBitMask,lGBitMask, 및 lBBitMask 멤버의 마스크값을 조사할 수가 있다. 상세한 것에 대하여는, 「픽셀 포맷 마스크」를 참조할것.

1 매의 디스플레이 카드를 모두 공유하고 있는 한, 1 개(살) 이상의 어플리케이션으로 모드를 변경할 수 있다. 디스플레이 모드의 비트 깊이는, DirectDraw 오브젝트에의 배타 액세스를 취득할 수 있었을 경우에만, 어플리케이션으로부터 변경할 수 있다. 모드가 변경되면(자), 모든 DirectDrawSurface 오브젝트는 표면 메모리를 잃어 조작 불능이 된다. 표면의 메모리는,DirectDrawSurface7.Restore 메소드를 사용하는 것으로 재할인 맞히고 하지 않으면 안 된다.

DirectDraw 의 배타 (풀 스크린) 모드에서는, 다른 어플리케이션이 DirectDrawSurface 오브젝트를 할당할 수 있거나 DirectDraw 나 GDI 기능도 이용 가능해진다. 다만, 배타 모드 이외의 어플리케이션이 디스플레이 모드나 팔레트를 변경할 수 없다.


디스플레이 모드의 restore

[C++]

IDirectDraw7::RestoreDisplayMode 메소드를 호출해, 디스플레이 하드웨어를 원의 모드에 명시적으로 restore 할 수가 있다. 디스플레이 모드가 IDirectDraw7::SetDisplayMode 를 호출하는 것으로 설정되어 또 어플리케이션이 배타 협조 레벨일 때, 원의 디스플레이 모드는 어플리케이션의 협조 레벨이 보통에 되돌려질 때 자동적으로 리셋 된다 (이 기능은 최초로 IDirectDraw2 인터페이스에 제공되어 그 인터페이스의 신버젼 모두에게 제공된다).

IDirectDraw 인터페이스를 사용하고 있을 때는,RestoreDisplayMode 메소드를 사용해 항상 디스플레이 모드를 명시적으로 restore 하지 않으면 안 된다.

[Visual Basic]

DirectDraw7.RestoreDisplayMode 메소드를 호출해, 디스플레이 하드웨어를 원의 모드에 명시적으로 restore 할 수가 있다. 디스플레이 모드가 DirectDraw7.SetDisplayMode 를 호출하는 것으로 설정되어 또 어플리케이션이 배타 협조 레벨일 때, 원의 디스플레이 모드는 어플리케이션의 협조 레벨이 보통에 되돌려질 때 자동적으로 리셋 된다.


모드 X 모드와 모드 13 디스플레이 모드

DirectDraw 는, 모드 13 모드 및 모드 X 디스플레이 모드를 지원 한다. 모드 13 은 선형 플립핑을 하지 못하고, 320 × 200 으로 픽셀 근처 8 비트의 팔레트화 모드이다. 이 모드는, 16 진 BIOS 모드 번호 13 으로 널리 알려지고 있다. 13. 상세한 것에 대하여는, 「모드 13 지원」을 참조할것. 모드 X 는, 표준 VGA 모드 13 으로부터 파생한 하이브리드(hybrid) 디스플레이 모드이다. 이 모드에서는, VGA 디스플레이 어댑터의 EGA 멀티 비디오면시스템에 의해, 256 KB 까지의 디스플레이 메모리를 사용할 수 있다 (모드 13 에서는 64 KB 까지).

DirectDraw 는 모든 디스플레이 카드에 대해서, 2 개의 모드 X 모드 (320×200×8 으로 320×240×8)를 제공한다. 또, 선형저해상도 모드를 지원 하는 카드도 있다. 선형저해상도 모드에서는프라이머리 표면을 잠그어, 직접 액세스 할 수 있다. 모드 X 모드에서는 프라이머리 표면에 직접 액세스 할 수 없다.

[C++]

모드 X 모드는,IDirectDraw7::SetCooperativeLevel 메소드를 호출하면나무에, 어플리케이션이 DDSCL_ALLOWMODEX, DDSCL_FULLSCREEN, 및 DDSCL_EXCLUSIVE 플래그를 사용하는 경우에만 이용할 수가 있다. DDSCL_ALLOWMODEX 가 지정되어 있지 않은 경우,IDirectDraw7::EnumDisplayModes 메소드는 모드 X 모드를 열거하지 않고, 또 모드 X 모드가 요구되면(자) IDirectDraw7::SetDisplayMode 메소드는 실패한다.

Windows 95 및 Windows NT/Windows 2000 은,모드 X 모드를 최적으로 지원 하지 않는다. 따라서, 어플리케이션이 모드 X 모드의 경우,프라이머리 표면을 잠그거나 블리트하기 위한 IDirectDrawSurface7::Lock 나 IDirectDrawSurface7::Blt 메소드를 사용할 수 없다. 또 프라이머리 표면으로 IDirectDrawSurface7::GetDC 메소드를 사용하는 일도, 스크린 DC 로 GDI 를 사용하는 일도 할 수 없다. 모드 X 모드는,DDSCAPS2 구조체의 DDSCAPS_MODEX 플래그로 나타난다. 이 구조체는,IDirectDrawSurface7::GetCaps 및 IDirectDraw7::EnumDisplayModes 메소드로 돌려주어지는 DDSURFACEDESC2 구조체의 일부이다.

[Visual Basic]

모드 X 모드는,DirectDraw7.SetCooperativeLevel 메소드를 호출하면나무에, 어플리케이션이 DDSCL_ALLOWMODEX, DDSCL_FULLSCREEN, 및 DDSCL_EXCLUSIVE 플래그를 사용하는 경우에만 이용할 수가 있다. 협조 레벨의 설정시에 DSCL_ALLOWMODEX 가 지정되어 있지 않은 경우,DirectDraw7.GetDisplayModesEnum 메소드는 모드 X 모드를 열거하지 않고, 모드 X 모드가 요구되면(자) DirectDraw7.SetDisplayMode 메소드는 실패한다.

Windows 95 및 Windows NT/Windows 2000 은,모드 X 모드를 최적으로 지원 하지 않는다. 따라서, 어플리케이션이 모드 X 모드의 경우,프라이머리 표면을 잠그거나 프라이머리 표면에 블리트 전송하기 위한 DirectDrawSurface7.Lock 나 DirectDrawSurface7.Blt 메소드를 사용할 수 없다. 또 프라이머리 표면으로 DirectDrawSurface7.GetDC 메소드를 사용하는 일도, 스크린 DC 로 GDI 를 사용하는 일도 할 수 없다. 모드 X 모드는,DDSCAPS2 형의 DDSCAPS_MODEX 플래그로 나타난다. 이 형태는,DirectDrawSurface7.GetCaps 및 DirectDrawEnumModes 메소드로 돌려주어지는 DDSURFACEDESC2 형의 일부이다.


고해상도와 트루 컬러 비트 깊이의 지원

DirectDraw 는, 디스플레이 디바이스 드라이버로 지원 하는 모든 스크린 해상도와 비트 깊이를 지원 한다. DirectDraw 에 의해, 어플리케이션은, 컴퓨터의 디스플레이 드라이버가 지원 하는 어느 모드에도 변경할 수 있게 된다. 이것에는, 지원 되고 있는 24-bpp 로 32-bpp 의 (트루 컬러) 모드 모든 것이 포함된다.

또, DirectDraw 는, 트루 컬러 표면의 HEL 블리트도 지원 한다. 디스플레이 디바이스가 이러한 해상도로 블리트를 지원 하는 경우는, 디스플레이 메모리간의 블리트에하드웨어 블리트가 사용되어 그 이외의 경우는 HEL 가 사용된다.

[C++]

DirectDraw 는, 인스톨 된 모니터의 디스플레이 제한으로 대응한 디스플레이 모드의 리스트를 체크한다. DirectDraw 가 요구된 모드를 유저의 모니터로 표시할 수 없으면 결정하는 경우,IDirectDraw7::SetDisplayMode 메소드의 호출은 실패한다. 또,IDirectDraw7::EnumDisplayModes 메소드를 호출했을 때에 열거되는 것은, 인스톨 된 모니터가 지원 하는 모드 뿐이다.

[Visual Basic]

DirectDraw 는, 인스톨 된 모니터의 디스플레이 제한으로 대응한 디스플레이 모드의 리스트를 체크한다. DirectDraw 가 요구된 모드를 유저의 모니터로 표시할 수 없으면 결정하는 경우,DirectDraw7.SetDisplayMode 메소드의 호출은 실패한다. 또,DirectDraw7.GetDisplayModesEnum 메소드를 호출했을 때에 열거되는 것은, 인스톨 된 모니터가 지원 하는 모드 뿐이다.


DirectDraw 오브젝트

여기에서는, DirectDraw 오브젝트에 대해, 및 IDirectDraw,IDirectDraw2,IDirectDraw4, 또는 IDirectDraw7 인터페이스로부터 오브젝트를 조작하는 방법에 대해 설명한다. 다음의 항목에 대해 기술한다.

  • DirectDraw 오브젝트란?
  • IDirectDraw7 에서의 신기능
  • 친오브젝트와 아이 오브젝트의 유효기간
  • 프로세스마다의 복수의 DirectDraw 오브젝트
  • CoCreateInstance 를 이용한 DirectDraw 오브젝트의 생성


DirectDraw 오브젝트란?

[C++]

DirectDraw 오브젝트는, 모든 DirectDraw 어플리케이션의 중심이며, 또 Direct3D® 어플리케이션으로 빠뜨리는 일을 할 수 없는 부분이기도 하다. DirectDraw 오브젝트는 생성 하는 최초의 오브젝트이며, 이 오브젝트로부터 관련하는 다른 모든 오브젝트가 생성 된다. DirectX 7.0 에서는, 최신 버젼의 DirectDraw 오브젝트를 생성 하기 위해서 새로운 메소드가 도입되었다. DirectDrawCreateEx 함수는, 최신의 Direct3D 인터페이스를 공개하는 DirectDraw 오브젝트를 생성 한다. 이전의 버젼에서는,DirectDrawCreate 함수를 호출해 DirectDraw 오브젝트를 생성 한다. 이 함수는,IDirectDraw 인터페이스를 돌려준다. 다른 버젼의 인터페이스 (IDirectDraw7 등)로 새로운 기능을 이용하고 싶은 경우는, 그것을 실행할 수 있을지 어떨지를 조회할 수가 있다 ( 「IDirectDraw7 인터페이스의 취득」을 참조할것). DirectX 7.0 에서는,DirectDrawCreate 를 사용해 DirectDraw 오브젝트를 생성 한 다음에,IDirectDraw7 인터페이스를 조회할 수도 있지만, Direct3D 의 신기능은 지원 하지 않는다. Direct3D 의 신기능을 사용하려면 ,DirectDrawCreateEx 함수를 사용해 IDirectDraw7 인터페이스를 취득해야 한다. 복수의 DirectDraw 오브젝트를 생성 할 수 있는 (시스템에 인스톨 된 각 디스플레이 디바이스에 대해서 1 개) 일로 주의한다.

[Visual Basic]

DirectDraw 오브젝트는, 모든 DirectDraw 어플리케이션의 중심이며, 또 Direct3D® 어플리케이션으로 빠뜨리는 일을 할 수 없는 부분이기도 하다. DirectDraw 오브젝트는 생성 하는 최초의 오브젝트이며, 이 오브젝트로부터 관련하는 다른 모든 오브젝트가 생성 된다. Visual Basic 에서는,DirectX7.DirectDrawCreate 메소드를 호출해, 최신 버젼의 Direct3D 인터페이스를 공개하는 DirectDraw7 오브젝트를 생성 한다.

DirectDraw 오브젝트는, 디스플레이 디바이스를 나타낸다. 또, 오브젝트의 생성 된 디스플레이 디바이스가, 하드웨어 가속화를 지원 하는 경우, 그것을 이용한다. 각각의 고유의 DirectDraw 오브젝트는, 디스플레이 디바이스를 조작하거나 생성 하는 오브젝트에 의존하는 (또는,"접속한다") 표면 팔레트, 및 클립퍼등의 오브젝트를 생성 할 수 있다. 예를 들어, 표면을 생성 하려면 , C++ 의 IDirectDraw7::CreateSurface 메소드 또는 Visual Basic 의 DirectDraw7.CreateSurface 메소드를 호출한다. 혹은, 표면에 적용하는 팔레트 오브젝트가 필요한 경우는, C++ 의 IDirectDraw7::CreatePalette 메소드 또는 Visual Basic 의DirectDraw7.CreatePalette 메소드를 호출한다. 게다가IDirectDraw7 인터페이스와 DirectDraw7 오브젝트는 클립퍼 오브젝트를 생성 하는 동일한 메소드를 공개한다.

DirectDraw 오브젝트에 관해서, 동시에 2 개(살) 이상의 인스턴스를 생성 할 수 있다. 가장 단순한 예로서는, Windows 95 또는 Windows NT 4.0 이전의 시스템상에서 2 개의 모니터를 사용하는 경우가 있다. 이러한 operating system 자체는, 듀얼 모니터를 지원 하지 않지만, 디스플레이 디바이스 각각 DirectDraw HAL 를 기술할 수가 있다. Windows 와 GDI 가 인식하는 디스플레이 디바이스는, 디폴트의 DirectDraw 오브젝트의 인스턴스를 생성 할 경우에 이용되는 것이다. 그렇지 않은 디바이스는, 제 2 의 디스플레이 디바이스의 글로벌 유니크 식별자 (GUID)를 사용해 생성 된, 독립한 이제(벌써) 1 개의 DirectDraw 오브젝트에 의해 주소 지정된다. 이 GUID 는, C++ 의 DirectDrawEnumerate 함수 또는 Visual Basic 의 DirectDrawEnum.GetGuid 메소드를 사용해 취득할 수 있다.

DirectDraw 오브젝트는 생성 한 모든 오브젝트를 관리해, 디폴트의 팔레트 (프라이머리 표면 이 8 비트마다의 픽셀 모드의 경우), 디폴트 컬러 키, 및 하드웨어 디스플레이 모드를 제어한다. 그리고, 어느 리소스가 할당이 끝난 상태로, 어느 리소스가 사용 가능한가를 조사한다.


IDirectDraw7 에서의 신기능

[C++]

여기에서는,IDirectDraw7 인터페이스의 제공하는 새로운 기능에 대해 자세하게 설명해, 지금까지 이용되어 온 IDirectDraw4 와의 동작의 차이에 대해 설명한다 (IDirectDraw5 및 IDirectDraw6 인터페이스라고 하는 버젼은 없기 때문에,IDirectDraw4 가 IDirectDraw7 의 직전의 버젼이 된다). 다음의 항목에 대해 기술한다.

  • IDirectDraw7 의 신기능
  • IDirectDraw7 인터페이스의 취득

IDirectDraw7 인터페이스와 이전의 버젼의 가장 큰 차이는, Direct3D 와의 밀접한 통합이다. DirectX 의 종래의 버젼에서는,IDirect3DTexture 인터페이스에 의해 텍스쳐를 생성 했지만, DirectX 7.0 에서는,IDirectDrawSurface7 인터페이스에, 이하에 나타내는 것 같은 텍스쳐 관리 메소드가 짜넣어졌다.

  • IDirectDrawSurface7::SetPriority
  • IDirectDrawSurface7::GetPriority
  • IDirectDrawSurface7::SetLOD
  • IDirectDrawSurface7::GetLOD

그 외, 스테레오 플립핑 표면, refresh rate의 열거, 및 큐브 환경 맵의 지원등도 추가되었다.

[C++, Visual Basic]


IDirectDraw7 의 신기능

[C++]

DirectX 7.0 의 IDirectDraw7 인터페이스에 추가된 새로운 메소드는 없지만,IDirectDraw7 와 Direct3D 의 통합이 강화되고 있다. IDirectDraw7 오브젝트는 IDirect3D 인터페이스에 대한 QueryInterface 를 지원 하고 있지만, 동레벨의 인터페이스에 대해서 밖에 QueryInterface 를 호출할 수 없다. 즉, DirectDraw 오브젝트로부터 IDirect3D7 를 취득하면(자), 그 오브젝트로부터 그 이전의 Direct3D 인터페이스를 취득할 수 없다. 같이 DirectDraw 오브젝트로부터 이전의 Direct3D 인터페이스를 취득하면(자), 그 오브젝트로부터 IDirect3D7 를 취득할 수 없다.

게다가IDirectDraw7 에 의해 생성 된 표면으로, Direct3D 관련의 QueryInterface 호출을 실시할 수 없다 (이러한 호출을 실시하면 E_NOINTERFACE 가 돌려주어진다). 어플리케이션은,IDirectDraw4 이전의 버젼에 의해 생성 된 표면으로부터 마셔 IDirect3DTexture 인터페이스를 취득할 수 있다.

이상과 같은 이유로부터, 종래의 Direct3D 인터페이스를 사용하는 경우는 DirectDraw 7.0 인터페이스는 사용할 수 없고, DirectX 7.0 Direct3D 인터페이스를 사용하는 경우에는 DirectX 7.0 DirectDraw 인터페이스를 사용할 필요가 있다.

이번 버젼에서는,IDirectDraw7 인터페이스를 취득하기 위한 새로운 DirectDraw 오브젝트 생성 함수,DirectDrawCreateEx 가 추가되었다. 상세한 것에 대하여는, 다음의 「IDirectDraw7 인터페이스의 취득」으로 설명한다.

[C++, Visual Basic]


IDirectDraw7 인터페이스의 취득

[C++]

DirectX 7.0 에서는,IDirectDraw7 인터페이스를 생성하기 위한 새로운 함수,DirectDrawCreateEx 가 도입되었다. DirectDraw 및 Direct3D 의 신기능을 지원 하는 최신 버젼의 DirectDraw 오브젝트를 생성 하려면 , 이 함수를 사용해야 한다. IDirectDraw7 인터페이스는,IDirectDraw4 인터페이스로 옮겨진다. 이 새로운 인터페이스를 취득하려면 , 다음의 C++ 의 예에 나타내도록(듯이) DirectDrawCreateEx 함수를 사용한다.

// DirectDraw 를 초기화한다.

LPDIRECTDRAW7 lpDD7;
HRESULT hr;
if (FAILED(hr = DirectDrawCreateEx(NULL, (VOID**) &lpDD7, IID_IDirectDraw7, NULL)))
    return FALSE;

if (FAILED(hr = lpDD7->SetCooperativeLevel(NULL, DDSCL_NORMAL)))
    return FALSE;

IDirectDraw7 인터페이스를 취득한 후, 그 메소드를 호출해, 신기능, 퍼포먼스의 개선, 및 다른 동작을 활용한다. 새로운 인터페이스의 릴리스와 함께, 종래의 메소드가 몇개인가 변경된다. 그 때문에, 인터페이스 메소드의 신구 버젼 (예를 들어 IDirectDraw4 와 IDirectDraw7)을 혼용 하면, 예측 불가능한 결과가 생긴다.

[Visual Basic]

Visual Basic 에서는,DirectX7.DirectDrawCreate 메소드에 의해 DirectDraw 오브젝트를 취득한다.


친오브젝트와 아이 오브젝트의 유효기간

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

DirectDraw 프로그래밍으로 사용하는 모든 오브젝트 (DirectDraw 오브젝트, 표면 팔레트, 클립퍼등)는, 어플리케이션과 같은 다른 오브젝트가 그것을 필요로 하는 한, 메모리내에 존재하는 것만으로 있다. 오브젝트의 유효기간이란, 오브젝트가 메모리에 생성 되어 배치된 순간부터, 오브젝트가 릴리즈 된 후에 메모리로부터 삭제될 때까지의 시간이다. 모든 DirectX 컴퍼넌트에 따르는 컴퍼넌트 오브젝트 모델 (COM)에서는, 1 개의 오브젝트가 서비스를 필요로 하는 다른 오브젝트의 수를 계속 하는 것 를 지시한다. 이 수는 참조 카운트로 불려 오브젝트의 유효기간을 결정한다. 또, COM 에서는,IUnknown::AddRef 및 IUnknown::Release 메소드를 사용해 오브젝트를 조사해 어플리케이션이 참조 카운트를 명시적으로 관리할 수가 있다. COM 의 규칙에 따라, 이러한 메소드를 사용해 확인하는 것.

오브젝트에 대한 참조 카운트를 관리하려면 , 누구나가 IUnknown 메소드를 사용할 수 있다. 또, DirectDraw 오브젝트는 내부에서 참조 카운트를 사용한다. IDirectDraw7 (IDirectDraw2 나 IDirectDraw 와 대조에) 인터페이스를 사용해, 표면과 같은 "아이" 오브젝트를 생성 하는 경우, 아이는 "부모" 의 DirectDraw 오브젝트의 IUnknown::AddRef 메소드를 사용해, 부모의 참조 카운트를 인크리먼트(increment) 한다.

어플리케이션으로 오브젝트가 필요없게 되면(자), 참조 카운트를 감소 하는 Release 메소드를 호출한다. 참조 카운트가 제로가 되면(자), 그 오브젝트는 메모리로부터 삭제된다. 아이 오브젝트의 참조 카운트가 제로가 되면(자), 부모의 IUnknown::Release 메소드를 호출해, 부모의 서비스를 필요로 하는 오브젝트가 적어도 1 개 있는 것을 나타낸다.

IDirectDraw7::CreateSurface 의 호출로 생성 하는 플립핑 체인의 백 버퍼 표면과 같이 은근히 할당할 수 있었던 오브젝트에서는, 그 오브젝트의 부모의 DirectDrawSurface 오브젝트가 릴리즈 되면(자), 자동적으로 할당이 삭제된다. 또, 어플리케이션 윈도우를 생성 하는 thread로부터, DirectDraw 오브젝트만을 릴리즈 할 수 있다. 단일의 thread화 된 어플리케이션에 대해서, 이 제한은 1 개의 thread만이 존재하도록(듯이) 분명하게 적용되지 않는다. 어플리케이션으로, Attach 상태의 DirectDrawClipper 오브젝트를 사용하는 2 개의 표면 (CreateSurface 의 호출로 생성 되었다)의 프라이머리 플립핑 체인을 생성 했을 경우, 이러한 오브젝트를 확실히 릴리즈 하는 코드는 이하와 같이 된다.

// 이 예에서는, g_lpDDraw, g_lpDDSurface, 및
// g_lpDDClip 가 오브젝트에 대한 유효한 포인터가 된다.
void ReleaseDDrawObjects(void)
{
// DirectDraw 오브젝트 포인터가 유효한 경우,
// 그 오브젝트와 포인터는 안전하게 릴리즈 된다.
    if(g_lpDDraw)
    {
// DirectDraw 오브젝트를 릴리즈 한다 (자식이 IDirectDraw2
// (이)나 IDirectDraw 로부터 생성 되었을 경우, 이 호출은
// 안전하다고는 안 된다. 이 경우의 상세 정보는,
// 이하에 나타내는 메모를 참조할것).
        g_lpDDraw->Release(), g_lpDDraw = NULL;

// 여기에서는, 표면에 할당할 수 있는 클립퍼를 릴리즈 한다
        if(g_lpDDClip)
            g_lpDDClip->Release(), g_lpDDClip = NULL;

// 여기에서는, 프라이머리 플립핑 체인을 릴리즈 한다. 플립핑 체인 표면이
//  CreateSurface 의 호출로 생성 되었기 때문에,
// 이것은 유일 유효가 되는 것에
// 주의한다. 그 표면이 명시적으로 생성 되어
// Attach 된다면, 릴리즈도 명시적으로
// 되지 않으면 안 된다.
        if(g_lpDDSurface)
            g_lpDDSurface->Release(), g_lpDDSurface = NULL;
    }
}

주 : DirectDraw 인터페이스의 이전의 버젼 (정확하게는,IDirectDraw2 와 IDirectDraw)은, 대부분의 최신의 인터페이스와는 다른 동작을 한다. 이전의 인터페이스를 사용하고 있는 경우, 친자체가 릴리즈 되면(자), DirectDraw 는 자동적으로 모든 아이 오브젝트를 릴리즈 한다. 그 때문에, 이러한 낡은 인터페이스를 사용하는 경우는, 오브젝트를 릴리즈 하는 순서가 중요하게 된다. 이 경우, DirectDraw 오브젝트 자체를 릴리즈 하기 (또는, 클린 업 하는 부모에 의해, 그 오브젝트 모든 것을 릴리즈 하지 않는다) 전에, DirectDraw 오브젝트의 아이를 릴리즈 하지 않으면 안 된다. DirectDraw 오브젝트는 아이 오브젝트를 릴리즈 하므로, 아이를 릴리즈 하기 전에 부모를 릴리즈 해 버리면(자), 친오브젝트가 아이 오브젝트를 릴리즈 했을 때에 무효가 된 포인터를 참조할 수 없게 되어, 메모리에 장해를 받기 쉬워진다.

오브젝트가 필요없게 되면(자), 낡은 어플리케이션은 아이 오브젝트의 자동 릴리즈에 의지해, 몇개의 오브젝트를 올바르고 릴리즈 할 수 없게 되는 경우가 있다. 이 경우, 이 습관이 모든 악영향을 일으키는 것은 아니지만,IDirectDraw7 인터페이스를 사용할 때는 메모리 누수의 원인이 되는 일이 있다.


프로세스마다의 복수의 DirectDraw 오브젝트

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

DirectDraw 에서는, 프로세스는 필요한 회수만 DirectDrawCreate 함수를 호출할 수가 있다. 호출할 것에, 고유가 다른 DirectDraw 오브젝트에의 고유가 다른 인터페이스가 돌려주어진다. 각각의 DirectDraw 오브젝트는 요구 대로에 사용할 수가 있어 오브젝트간에는 종속성이 없다. 확실히, 각각의 오브젝트는, 고유의 프로세스로부터 생성 되었는지와 같이 동작하는 것이다.

DirectDraw 오브젝트는, 서로 독립하고 있다. 생성 된 DirectDrawSurface, DirectDrawPalette, DirectDrawClipper 의 각 오브젝트는, 다른 DirectDraw 오브젝트와 함께 사용할 수 없다. 이러한 오브젝트는, DirectDraw 오브젝트가 파기될 때 자동적으로 릴리즈 되는 경우가 있기 때문이다. 다른 DirectDraw 오브젝트와 함께 사용했을 경우, 친오브젝트가 파기되면(자) 기능이 정지해 버릴 가능성이 있어, 그 외의 DirectDraw 오브젝트에 오동작이 생긴다.

DirectDrawCreateClipper 함수에 의해 생성 된 DirectDrawClipper 오브젝트는, 예외이다. 이 오브젝트는, 모든 DirectDraw 오브젝트로부터 독립해, 1 개(살) 이상의 DirectDraw 오브젝트와 함께 사용할 수가 있다.


CoCreateInstance 를 이용한 DirectDraw 오브젝트의 생성

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

DirectDrawCreate 함수는 아니고,CoCreateInstance 함수와 IDirectDraw7::Initialize 메소드를 사용해 DirectDraw 오브젝트를 생성 할 수가 있다. 이하에 DirectDraw 오브젝트를 사용하는 순서를 나타낸다.

  1. 어플리케이션의 시작시에 NULL 를 지정해 CoInitialize 를 호출해, COM 를 초기화한다.
    if (FAILED(CoInitialize(NULL)))
    return FALSE;
  2. CoCreateInstance 와 IDirectDraw7::Initialize 메소드를 사용해 DirectDraw 오브젝트를 생성 한다.
    ddrval = CoCreateInstance(&CLSID_DirectDraw,
    NULL, CLSCTX_ALL, &IID_IDirectDraw7, &lpdd);
if(! FAILED(ddrval))
    ddrval = IDirectDraw7_Initialize(lpdd, NULL);

    이 CoCreateInstance 의 호출에서는, 최초의 파라미터 CLSID_DirectDraw 가, DirectDraw 드라이버 오브젝트 클래스의 식별자이다. IID_IDirectDraw7 파라미터는, 생성 하는 특정의 DirectDraw 인터페이스를 식별한다. 또,lpdd 파라미터는 취득된 DirectDraw 오브젝트에의 포인터이다. 호출이 성공하면(자), 이 함수는 초기화되어 있지 않은 오브젝트를 돌려준다.

  3. DirectDraw 오브젝트를 사용하기 전에,IDirectDraw7::Initialize 를 호출하지 않으면 안 된다. 이 메소드는,DirectDrawCreate 함수가 일반적으로 사용하는 드라이버 GUID 파라미터 (이 경우 NULL)를 취득한다. DirectDraw 오브젝트의 초기화 후는,DirectDrawCreate 함수를 사용해 생성 했을 경우와 같게 사용 및 릴리즈 할 수가 있다. DirectDraw 오브젝트에 관련지을 수 있었던 메소드의 1 개를 사용하기 전에, 초기화 메소드를 호출하지 않으면DDERR_NOTINITIALIZED 에러가 발생한다.

어플리케이션을 종료하기 전에,CoUninitialize 함수로 COM 라이브러리를 닫는 것.

CoUninitialize () ;


표면

여기에서는, DirectDrawSurface 오브젝트에 대해 설명한다. 다음의 항목에 대해 기술한다.

  • 표면의 기본 개념
  • 표면의 생성
  • 플립핑 표면
  • 표면에의 블리트
  • 표면의 소실과 restore
  • 표면의 COM 참조 카운트 의미들
  • 표면의 열거
  • 표면 특성의 갱신
  • 표면 메모리에의 직접 액세스
  • 감마 컨트롤과 컬러 컨트롤
  • 오버레이 표면
  • 압축한 텍스쳐 표면
  • Private 표면 데이터
  • 표면 고유치
  • 비로컬 비디오 메모리 표면의 사용
  • 표면 문맥과 디바이스 콘텍스트


표면의 기본 개념

여기에서는, DirectDrawSurface 오브젝트에 관련하는 개념에 대해 설명한다. 다음의 항목에 대해 기술한다.

  • 표면이란?
  • 표면 인터페이스
  • 폭과 피치
  • 컬러 키잉
  • 픽셀 포맷


표면이란?

표면 또는 DirectDrawSurface 오브젝트는, 디스플레이 메모리의 선형 영역을 나타낸다. 보통, 표면은 디스플레이 카드의 디스플레이 메모리에 상주하고 있지만, 시스템 메모리에 존재할 수도 있다. DirectDrawSurface 오브젝트 생성의 과정에서 특별히 지시받지 않는 한, DirectDraw 오브젝트는, 요구되는 능력으로 최고의 퍼포먼스를 얻을 수 있는 장소에 DirectDrawSurface 오브젝트를 둔다. DirectDrawSurface 오브젝트는, 디스플레이 카드 위에의 특화된 프로세서를 유효하게 이용할 수 있어 시스템 CPU 와 병행해 태스크를 실행한다.

[C++]

IDirectDraw7::CreateSurface 메소드를 사용 하면, 1 개의 표면 오브젝트,복합 표면 플립핑 체인, 혹은 3 차원 표면을 생성 할 수가 있다. CreateSurface 메소드는 요구된 표면 또는 플립핑 체인을 생성 해,프라이머리 표면의 IDirectDrawSurface7 인터페이스에의 포인터를 취득한다. 이 인터페이스로부터, 오브젝트는 그 기능을 공개한다.

IDirectDrawSurface7 인터페이스에 의해,IDirectDrawSurface7::BltFast 등의 블리트 메소드로부터 메모리에 간접적으로 액세스 할 수 있다. 표면 오브젝트는, GDI 함수로 사용할 수 있는 디스플레이에의 디바이스 콘텍스트를 제공할 수 있다. 게다가IDirectDrawSurface7 메소드를 사용하면(자), 디스플레이 메모리에 직접 액세스 할 수가 있다. 예를 들어,IDirectDrawSurface7::Lock 메소드를 사용해 디스플레이 메모리를 잠그어, 그 표면에 대응하는 주소를 취득할 수가 있다. 디스플레이 메모리의 주소는, 표시되는 frame buffer 메모리 (프라이머리 표면)나, 비표시의 버퍼 (오프 스크린, 또는오버레이 표면)를 가리키거나 하는 일도 있다. 보통, 비표시의 버퍼는 디스플레이 메모리에 상주하지만, 하드웨어 제한에 의해 요구되거나 DirectDraw 가 소프트웨어의 에뮬레이션을 실시하거나 하는 경우, 시스템 메모리에 생성 되는 일도 있다. 게다가IDirectDrawSurface7 인터페이스는, 팔레트의 설정이나 취득에 사용하거나 혹은 플립핑 체인이나 오버레이등의 특정의 타입이나 표면과 함께 작용하거나 하기 위해서 사용하는 다른 메소드를 확장한다.

[Visual Basic]

DirectDraw7.CreateSurface 메소드를 사용 하면, 1 개의 표면 오브젝트,복합 표면 플립핑 체인, 혹은 3 차원 표면을 생성 할 수가 있다. CreateSurface 메소드는 요구된 표면 또는 플립핑 체인을 생성 해,프라이머리 표면의 IDirectDrawSurface7 인터페이스에의 포인터를 취득한다. 이 인터페이스로부터, 오브젝트는 그 기능을 공개한다.

DirectDrawSurface7 오브젝트에 의해,DirectDrawSurface7.BltFast 등의 블리트 메소드로부터 메모리에 간접적으로 액세스 할 수 있다. 표면 오브젝트는, GDI 함수로 사용할 수 있는 디스플레이에의 디바이스 콘텍스트를 제공할 수 있다. 게다가DirectDrawSurface7 메소드를 사용하면(자), 디스플레이 메모리에 직접 액세스 할 수가 있다. 예를 들어,DirectDrawSurface7.Lock 메소드를 사용해 디스플레이 메모리를 잠그어, 그 표면을 취득할 수 있다. 디스플레이 메모리는, 표시되는 frame buffer 메모리 (프라이머리 표면)나, 비표시의 버퍼 (오프 스크린, 또는오버레이 표면)가 될 수도 있다. 보통, 비표시의 버퍼는 디스플레이 메모리에 상주하지만, 하드웨어 제한에 의해 요구되거나 DirectDraw 가 소프트웨어의 에뮬레이션을 실시하거나 하는 경우, 시스템 메모리에 생성 되는 일도 있다. 게다가IDirectDrawSurface7 인터페이스는, 팔레트의 설정이나 취득에 사용하거나 혹은 플립핑 체인이나 오버레이등의 특정의 타입이나 표면과 함께 작용하거나 하기 위해서 사용하는 다른 메소드를 확장한다.

다음에 나타내는 그림으로부터, 모든 표면은 DirectDraw 오브젝트에 의해 생성 되어 팔레트와 밀접하게 관련해 이용되는 일도 있는 것을 알 수 있다. 각각의 표면 오브젝트에 팔레트를 할당할 수 있지만, 팔레트는 깊이가 8 비트 이하의 픽셀 포맷을 사용하는 프라이머리 표면 이외에서는 요구되지 않는다.


표면 인터페이스

[C++]

DirectDrawSurface 오브젝트는,IDirectDrawSurface,IDirectDrawSurface2,IDirectDrawSurface3,IDirectDrawSurface4, 및 IDirectDrawSurface7 인터페이스로부터 그 기능을 공개한다. 각각의 새로운 인터페이스 버젼에서는, 이전의 버젼과 같은 유틸리티 뿐만이 아니라, 새로운 메소드로부터 이용할 수 있는 추가 옵션을 제공한다.

IDirectDraw7::CreateSurface 메소드 (또는,IDirectDraw7 로부터 외 생성 메소드)를 호출해 표면을 생성 하는 경우, 표면의 IDirectDrawSurface7 인터페이스에의 포인터를 받는다. 이 동작은 DirectX 의 이전의 버젼과는 다르다. IDirectDraw7 인터페이스의 도입전은,CreateSurface 메소드가 표면의 IDirectDrawSurface 인터페이스에 포인터를 제공하고 있었다. 새로운 버젼의 인터페이스로부터 제공되는 신기능을 이용하려면 , 새로운 버젼을 쿼리-하지 않으면 안 된다. IDirectDraw7 는 이 경우에는 사용할 수 없지만, 선택한다면 인터페이스로 제공되기 이전의 버젼을 참조할 수 있다.

[Visual Basic]

DirectDrawSurface 오브젝트는,DirectDrawSurface7 클래스로부터 생성 된다. DirectDraw7.CreateSurface 메소드를 호출하면, DirectDrawSurface 오브젝트가 돌려주어진다.


폭과 피치

폭과피치라고 하는 단어로부터 어느 정도 상상할 수 있지만, 매우 중요한 (그리고, 분명한 차이) 의미가 있다. 그 때문에, 각각의 의미와 DirectDraw 가 폭과 피치를 기술하기 위해서 사용하는 값의 판단 방법을 이해하지 않으면 안 된다.

[C++]

DirectDraw 에서는,DDSURFACEDESC2 구조체를 사용해 표면을 기술하는 정보를 전달한다. 그 밖에도, 이 넓이의 메모리내에서의 표시 방법과 같게, 이 구조체는 표면의 넓이의 정보를 포함하기 위해서(때문에) 정의된다. 이 구조체에서는 dwHeight 멤버와 dwWidth 멤버를 사용해, 표면의 논리적인 넓이를 기술한다. 이 2 개의 멤버는 픽셀 단위로 측정된다. 그 때문에, 640 × 480 의 표면에 대한 dwHeight 값과 dwWidth 값은, 8 비트의 팔레트화 표면이나 24 비트의 RGB 표면에 관계없이 같게 된다.

DDSURFACEDESC2 구조체에는, 표면이 lPitch 멤버로부터 어떻게 메모리내에 표시되는가 하는 정보가 포함된다. lPitch 멤버의 값은, 표면의 메모리 피치 (또는,보폭으로 불린다)를 기술한다. 피치는, 2 개의 메모리 주소간 (있는 비트 맵 라인의 시점과 다음의 비트 맵 라인의 시점)의 거리이며, 단위는 바이트이다. 피치는 픽셀은 아니고 바이트 단위로 측정되기 위해서(때문에), 640 × 480 × 8 의 표면은, 다른 픽셀 포맷의 같은 넓이의 표면보다 매우 다른 피치의 값을 가진다. 게다가 피치의 값은 DirectDraw 가 캐쉬로서 확보되는 바이트를 반영하는 일도 있으므로, 단지 피치를 픽셀 마다 바이트수를 건 폭이라고 가정할 수 없다. 다음의 그림으로, 폭과 피치에 있어서의 차이를 설명한다.

[Visual Basic]

DirectDraw 에서는,DDSURFACEDESC2 형을 사용해 표면을 기술하는 정보를 전달한다. 그 밖에도, 이 넓이의 메모리내에서의 표시 방법과 같게, 이 구조체는 표면의 넓이의 정보를 포함하기 위해서(때문에) 정의된다. 이 구조체에서는 lHeight 멤버와 Width 멤버를 사용해, 표면의 논리적인 넓이를 기술한다. 이 2 개의 멤버는 픽셀 단위로 측정된다. 그 때문에, 640 × 480 의 표면에 대한 lHeight 값과 lWidth 값은, 8 비트의 팔레트화 표면이나 24 비트의 RGB 표면에 관계없이 같게 된다.

DDSURFACEDESC2 형에는, 표면이 lPitch 멤버로부터 어떻게 메모리내에 표시되는가 하는 정보가 포함된다. lPitch 멤버의 값은, 표면의 메모리 피치 (또는,보폭 으로 불린다)를 기술한다. 피치는, 2 개의 메모리 주소간 (있는 비트 맵 라인의 시점과 다음의 비트 맵 라인의 시점)의 거리이며, 단위는 바이트이다. 피치는 픽셀은 아니고 바이트 단위로 측정되기 위해서(때문에), 640 × 480 × 8 의 표면은, 다른 픽셀 포맷의 같은 넓이의 표면보다 매우 다른 피치의 값을 가진다. 게다가 피치의 값은 DirectDraw 가 캐쉬로서 확보되는 바이트를 반영하는 일도 있으므로, 단지 피치를 픽셀 마다 바이트수를 건 폭이라고 가정할 수 없다. 다음의 그림으로, 폭과 피치에 있어서의 차이를 설명한다.

위의도에서는,프런트 버퍼와백 버퍼는 어느쪽이나 640 × 480 × 8 으로, 캐쉬는 384 × 480 × 8 이다.

[C++]

표면 메모리에 직접 액세스 하는 경우, 피치의 값이 도움이 된다. 예를 들어,IDirectDrawSurface7::Lock 메소드를 호출한 후에, 관련지을 수 있었던 DDSURFACEDESC2 구조체의 lpSurface 멤버에는, 그 표면의 락 된 영역의 좌상 픽셀의 주소가 포함되어lPitch 멤버는 표면 피치가 된다. 픽셀마다의 바이트수에 의해, 표면 포인터를 인크리먼트(increment) 하거나 감소 하는 것으로, 좌우에 픽셀을 액세스 할 수 있다. 또, 피치의 값을 현재의 표면 포인터에 추가하거나 혹은 그 포인터로부터 줄이거나 하면, 상하로 이동할 수 있다.

표면에 직접 액세스 하는 경우, 표면의 넓이에 대해서 할당할 수 있었던 메모리의 범위내에 두는 것으로, 캐쉬에 대해서 확보된 모든 메모리의 밖에 두는 것에 주의한다. 게다가 표면의 포인터만을 잠그는 경우, 표면을 잠글 때 지정하는 직사각형의 범위내에 두지 않으면 안 된다. 이것에 따르지 않다고 예측 불가능한 결과가 생긴다. 표면 메모리에 직접 렌더링 하는 경우, 항상 Lock 메소드 (또는,IDirectDrawSurface7::GetDC 메소드)로부터 돌려주어지는 피치를 사용한다. 단지, 디스플레이 모드에 근거하는 피치를 가정해 사용해서는 안 된다. 다른 원인에 의해 정상적으로 동작하지 않게 된 몇개의 디스플레이 어댑터상에서 어플리케이션이 동작하는 경우, 문제가 생길 가능성이 있다.

[Visual Basic]

표면 메모리에 직접 액세스 하는 경우, 피치의 값이 도움이 된다. 예를 들어,DirectDrawSurface7.Lock 메소드를 호출하면,lPitch 멤버는 표면 피치가 된다. 픽셀마다의 바이트수에 의해, 표면 포인터를 인크리먼트(increment) 하거나 감소 하는 것으로, 좌우에 픽셀을 액세스 할 수 있다. 또, 피치의 값을 현재의 표면 포인터에 추가하거나 혹은 그 포인터로부터 줄이거나 하면, 상하로 이동할 수 있다.

표면에 직접 액세스 하는 경우, 표면의 넓이에 대해서 할당할 수 있었던 메모리의 범위내에 두는 것으로, 캐쉬에 대해서 확보된 모든 메모리의 밖에 두는 것에 주의한다. 게다가 표면의 포인터만을 잠그는 경우, 표면을 잠글 때 지정하는 직사각형의 범위내에 두지 않으면 안 된다. 이것에 따르지 않다고 예측 불가능한 결과가 생긴다. 표면 메모리에 직접 렌더링 하는 경우,Lock 멤버 (또는 DirectDrawSurface7.GetDC 메소드)에 의해 돌려주어진 피치를 항상 사용한다. 단지, 디스플레이 모드에 근거하는 피치를 가정해 사용해서는 안 된다. 다른 원인에 의해 정상적으로 동작하지 않게 된 몇개의 디스플레이 어댑터상에서 어플리케이션이 동작하는 경우, 문제가 생길 가능성이 있다.

상세한 것에 대하여는, 「표면 메모리에의 직접 액세스」를 참조할것.


컬러 키잉

DirectDraw 는, 블리트 및 오버레이 표면의 전송원, 목적지컬러 키잉을 지원 한다. 컬러 키에 의해, 어느 이미지를 다른 표면의 상부에 선택적으로 표시할 수 있기 (위해)때문에, 어느 픽셀만을 전방의 직사각형으로부터 표시하거나 후방의 직사각형에 over-write 할 수 있다.

[C++]

IDirectDrawSurface7::SetColorKey 메소드를 호출하는 것으로, 단일의 컬러 키 또는 전송원이나 목적지 컬러 키잉의 색역을 줄 수가 있다.

[Visual Basic]

DirectDrawSurface7.SetColorKey 메소드를 호출하는 것으로, 단일의 컬러 키 또는 전송원이나 목적지 컬러 키의 색역을 줄 수가 있다.

컬러 키잉의 상세한 것에 대하여는, 다음의 항목을 참조할것.

  • 오버레이 컬러 키
  • 투과형 블리트


픽셀 포맷

[C++]

픽셀 포맷은, 표면 메모리중의 각 픽셀의 데이터를 어떻게 판단하는지를 지시한다. DirectDraw 는 DDPIXELFORMAT 구조체를 이용해, 여러가지 픽셀 포맷을 기술한다. DDPIXELFORMAT 에는, 픽셀 포맷의 특징을 기술하는 멤버가 포함된다. 다음에 이 특징에 대해 가리킨다.

  • 팔레트화 또는 비팔레트화 픽셀 포맷
  • 비팔레트화의 경우, 픽셀 포맷은 RGB 일까 YUV 일까
  • 비트 깊이
  • 픽셀 포맷의 컴퍼넌트에 대한 비트 마스크

기존의 표면의 픽셀 포맷에 관한 정보를 취득하려면 ,IDirectDrawSurface7::GetPixelFormat 메소드를 호출한다.

[Visual Basic]

픽셀 포맷은, 표면 메모리중의 각 픽셀의 데이터를 어떻게 판단하는지를 지시한다. DirectDraw 는 DDPIXELFORMAT 형을 이용해, 여러가지 픽셀 포맷을 기술한다. DDPIXELFORMAT 에는, 픽셀 포맷의 특징을 기술하는 멤버가 포함된다. 다음에 이 특징에 대해 가리킨다.

  • 팔레트화 또는 비팔레트화 픽셀 포맷
  • 비팔레트화의 경우, 픽셀 포맷은 RGB 일까 YUV 일까
  • 비트 깊이
  • 픽셀 포맷의 컴퍼넌트에 대한 비트 마스크

기존의 표면의 픽셀 포맷에 관한 정보를 취득하려면 ,DirectDrawSurface7.GetPixelFormat 메소드를 호출한다.


표면의 생성

DirectDrawSurface 오브젝트는 표면을 나타낸다. 보통, 표면은 디스플레이 메모리에 상주하지만, 디스플레이 메모리가 만배이거나 명시적으로 요구되는 경우에는, 시스템 메모리에 존재시킬 수가 있다.

[C++]

1 개의 표면을 생성 하거나 동시에 복수의 표면 (복합 표면)을 생성 하려면 ,IDirectDraw7::CreateSurface 메소드를 사용한다. CreateSurface 를 호출하는 경우, 표면의 넓이를 지정한다. 이 넓이에서는, 표면이 단일 표면일까 복합 표면인지, 및 픽셀 포맷 (표면이 인덱스 팔레트를 사용하지 않는 경우)을 나타낸다. 이것들 모든 특성은 DDSURFACEDESC2 구조체에 포함되어 있어 그 주소는 호출해 때에 보낸다. 하드웨어가 요구된 능력을 지원 할 수 없기도 하고, 그 리소스가 사전에 다른 DirectDrawSurface 오브젝트에 할당할 수 있고 있는 경우, 그 호출은 실패한다.

[Visual Basic]

1 개의 표면을 생성 하거나 동시에 복수의 표면 (복합 표면)을 생성 하려면 ,DirectDraw7.CreateSurface 메소드를 사용한다. CreateSurface 를 호출하는 경우, 표면의 넓이를 지정한다. 이 넓이에서는, 표면이 단일 표면일까 복합 표면인지, 및 픽셀 포맷 (표면이 인덱스 팔레트를 사용하지 않는 경우)을 나타낸다. 이것들 모든 특성은 DDSURFACEDESC2 형에 포함되어 있어 그 주소는 호출해 때에 보낸다. 하드웨어가 요구된 능력을 지원 할 수 없기도 하고, 그 리소스가 사전에 다른 DirectDrawSurface 오브젝트에 할당할 수 있고 있는 경우, 그 호출은 실패한다.

단일 표면 또는 복합 표면의 생성은, 몇 줄기의 코드로 해결되는 간단한 태스크이다. 표면을 생성 하기 위해서 필요한 몇개의 일반적인 상황 (또는, 일반적이지 않은 상황)을 나타낸다. 이하의 상황에 대해 설명한다.

  • 프라이머리 표면의 생성
  • 오프 스크린 표면의 생성
  • 복합 표면과 플립핑 체인의 생성
  • 와이드 표면의 생성
  • 클라이언트 메모리 표면의 생성
[C++]

클라이언트 메모리 표면 이외의 모든 표면에 있어서의 디폴트에서는, DirectDraw 는 로컬 비디오 메모리에 표면을 생성 하려고 한다. 표면을 보관 유지하기 위해서 이용할 수 있는 로컬 비디오 메모리가 충분하지 않으면, DirectDraw 는 비로컬 비디오 메모리 (AGP 를 장비 한 시스템)를 이용하려고 한다. 그리고, 다른 모든 메모리 타입을 이용할 수 없으면, 시스템 메모리에 의지하려고 한다. 표면을 있는 타입의 메모리에 생성 하도록(듯이) 명시적으로 요구하려면 ,IDirectDraw7::CreateSurface 를 호출하면나무에 해당하는 플래그를 관련지을 수 있었던 DDSCAPS2 구조체에 포함한다.

[Visual Basic]

클라이언트 메모리 표면 이외의 모든 표면에 있어서의 디폴트에서는, DirectDraw 는 로컬 비디오 메모리에 표면을 생성 하려고 한다. 표면을 보관 유지하기 위해서 이용할 수 있는 로컬 비디오 메모리가 충분하지 않으면, DirectDraw 는 비로컬 비디오 메모리 (AGP 를 장비 한 시스템)를 이용하려고 한다. 그리고, 다른 모든 메모리 타입을 이용할 수 없으면, 시스템 메모리에 의지하려고 한다. 표면을 있는 타입의 메모리에 생성 하도록(듯이) 명시적으로 요구하려면 ,DirectDraw7.CreateSurface 를 호출하면나무에 해당하는 플래그를 관련지을 수 있었던 DDSCAPS2 형에 포함한다.


프라이머리 표면의 생성

프라이머리 표면 이란, 현재 모니터에 표시되고 있는 표면이며, DDSCAPS_PRIMARYSURFACE 플래그로 식별할 수가 있다. 각각의 DirectDraw 오브젝트에 대해서 프라이머리 표면은 1 개 밖에 존재하지 않는다.

프라이머리 표면을 생성 하는 경우, 넓이 및 픽셀 포맷은, 현재의 디스플레이 모드에 은근히 적합하는 것을 생각해 내는 것. 따라서, 이것은 표면의 넓이나 픽셀 포맷을 선언할 필요가 없는 경우의 1 개이다. 즉, 이러한 값을 지정 하면, 그 정보가 현재의 디스플레이 모드와 적합하고 있고 해도, 호출은 실패해,DDERR_INVALIDPARAMS 를 돌려준다.

[C++]

다음의 예에서는, 프라이머리 표면의 생성에 관계하는 DDSURFACEDESC2 구조체의 멤버를 어떻게 준비할까에 임해서 가리킨다.

DDSURFACEDESC2 ddsd;
ddsd.dwSize = sizeof(ddsd);

// 어느 멤버가 유효한가 DirectDraw 에게 전한다.
ddsd.dwFlags = DDSD_CAPS;

// 프라이머리 표면을 요구한다.
ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE;

프라이머리 표면을 생성 하면,IDirectDrawSurface7::GetSurfaceDesc 메소드를 호출해 넓이나 픽셀 포맷에 대한 정보를 취득할 수가 있다.

[Visual Basic]

다음의 예에서는, 프라이머리 표면의 생성에 관계하는 DDSURFACEDESC2 형의 멤버를 어떻게 준비할까에 임해서 가리킨다.

Dim ddsd As DDSURFACEDESC2

'어느 멤버가 유효한가 DirectDraw 에게 전한다.
ddsd.lFlags = DDSD_CAPS

'프라이머리 표면을 요구한다.
ddsd.ddsCaps.lCaps = DDSCAPS_PRIMARYSURFACE

프라이머리 표면을 생성 하면,DirectDrawSurface7.GetSurfaceDesc 메소드를 호출해 넓이나 픽셀 포맷에 대한 정보를 취득할 수가 있다.

「디스플레이 모드」도 참조할것.


오프 스크린 표면의 생성

[C++]

오프 스크린 표면은, 다음에 프라이머리 표면 혹은 백 버퍼에 블리트 되는 비트 맵을 캐쉬하기 위해서 사용되는 일이 있다. DDSD_WIDTH 및 DDSD_HEIGHT 플래그를 설정해, 대응하는 값을 dwWidth 및 dwHeight 멤버에게 주는 것으로, 오프 스크린 표면의 넓이를 선언한다. 게다가 부수 하는 DDSCAPS2 구조체에 DDSCAPS_OFFSCREENPLAIN 플래그를 설정하지 않으면 안 된다.

디폴트에서는, DirectDraw 는 디스플레이 메모리에 표면을 생성 하려고 한다. 잘 되지 않으면, 시스템 메모리에 표면을 생성 한다. DDSCAPS2 구조체의 dwCaps 멤버에 DDSCAPS_SYSTEMMEMORY 또는 DDSCAPS_VIDEOMEMORY 플래그를 설정하는 것으로, 명시적으로 디스플레이 메모리 또는 시스템 메모리를 선택할 수 있다. 지정된 위치에 표면을 생성 할 수 없는 경우, 메소드는 에러를 돌려주어 실패한다.

다음에 나타내는 예는, 간단한 오프 스크린 표면의 생성의 방법을 나타낸다.

DDSURFACEDESC2 ddsd;
ddsd.dwSize = sizeof(ddsd);

// 어느 멤버가 유효한가 DirectDraw 에게 전한다.
ddsd.dwFlags = DDSD_CAPS | DDSD_HEIGHT | DDSD_WIDTH;

// 간단한 오프 스크린 표면을 요구한다.
// 사이즈는 100 × 100 픽셀이다.
//
// (생성 하는 오프 스크린 표면이
// 프라이머리 표면의 픽셀 포맷에
// 적합 하면 가정한다. )
ddsd.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN;
ddsd.dwHeight = 100;
ddsd.dwWidth = 100;

또, 픽셀 포맷이 프라이머리 표면의 픽셀 포맷과 다른 표면도 생성 할 수 있다. 다만, 이 경우에는, 시스템 메모리의 사용이 제한된다고 하는 약점이 있다. 다음에 나타내는 코드에서는, 8 비트 팔레트화 표면 (현재의 디스플레이 모드가 픽셀 마다 8 비트 이외이라고 가정한다)을 생성 하기 위해서,DDSURFACEDESC2 구조체 멤버를 준비하는 방법에 대해 가리킨다.

ZeroMemory(&ddsd, sizeof(ddsd));
ddsd.dwSize  = sizeof(ddsd);
ddsd.dwFlags = DDSD_CAPS | DDSD_HEIGHT | DDSD_WIDTH | DDSD_PIXELFORMAT;
ddsd.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN | DDSCAPS_SYSTEMMEMORY;
ddsd.dwHeight = 100;
ddsd.dwWidth  = 100;
ddsd.ddpfPixelFormat.dwSize  = sizeof(DDPIXELFORMAT);
ddsd.ddpfPixelFormat.dwFlags = DDPF_RGB | DDPF_PALETTEINDEXED8;

// 8 비트 표면에 대한 비트 깊이를 설정하지만,
// 모든 RGB 마스크값을 지정해서는 안 된다. 팔레트화 표면에 대해서,
// 마스크값은 0 이 아니면 안된다.
ddsd.ddpfPixelFormat.dwRGBBitCount = 8;
[Visual Basic]

오프 스크린 표면은, 다음에 프라이머리 표면 혹은 백 버퍼에 블리트 되는 비트 맵을 캐쉬하기 위해서 사용되는 일이 있다. DDSD_WIDTH 및 DDSD_HEIGHT 플래그를 설정해, 대응하는 값을 IWidth 및 IHeight 멤버에게 주는 것으로, 오프 스크린 표면의 넓이를 선언한다. 게다가 부수 하는 DDSCAPS2 형에 DDSCAPS_OFFSCREENPLAIN 플래그를 설정하지 않으면 안 된다.

디폴트에서는, DirectDraw 는 디스플레이 메모리에 표면을 생성 하려고 한다. 잘 되지 않으면, 시스템 메모리에 표면을 생성 한다. DDSCAPS2 형의 lCaps 멤버에 DDSCAPS_SYSTEMMEMORY 또는 DDSCAPS_VIDEOMEMORY 플래그를 설정하는 것으로, 명시적으로 디스플레이 메모리 또는 시스템 메모리를 선택할 수 있다. 지정된 위치에 표면을 생성 할 수 없는 경우, 메소드는 에러를 돌려주어 실패한다.

다음에 나타내는 예는, 간단한 오프 스크린 표면의 생성의 방법을 나타낸다.

Dim ddsd As DDSURFACEDESC2

'어느 멤버가 유효한가 DirectDraw 에게 전한다.
ddsd.lFlags = DDSD_CAPS Or DDSD_HEIGHT Or DDSD_WIDTH

'간단한 오프 스크린 표면을 요구한다.
'사이즈는 100 × 100 픽셀이다.
'
' (생성 하는 오프 스크린 표면이
'프라이머리 표면의 픽셀 포맷에
'적합 하면 가정한다.
ddsd.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN
ddsd.lHeight = 100
ddsd.lWidth = 100

또, 픽셀 포맷이 프라이머리 표면의 픽셀 포맷과 다른 표면도 생성 할 수 있다. 다만, 이 경우에는, 시스템 메모리의 사용이 제한된다고 하는 약점이 있다. 다음에 나타내는 코드에서는, 8 비트 팔레트화 표면 (현재의 디스플레이 모드가 픽셀 마다 8 비트 이외이라고 가정한다)을 생성 하기 위해서,DDSURFACEDESC2 형의 멤버를 준비하는 방법에 대해 가리킨다.

ddsd.lFlags = DDSD_CAPS Or DDSD_HEIGHT Or DDSD_WIDTH Or DDSD_PIXELFORMAT
ddsd.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN Or DDSCAPS_SYSTEMMEMORY
ddsd.lHeight = 100
ddsd.lWidth = 100
ddsd.ddpfPixelFormat.lFlags = DDPF_RGB Or DDPF_PALETTEINDEXED8

' 8 비트 표면에 대한 비트 깊이를 설정하지만,
'모든 RGB 마스크값을 지정해서는 안 된다. 팔레트화 표면에 대해서,
'마스크값은 0 이 아니면 안된다.
ddsd.ddpfPixelFormat.lRGBBitCount = 8

DirectX 의 이전의 버젼에서는, 오프 스크린 표면의 최대폭은 프라이머리 표면의 폭에 제한되고 있었다. DirectX 5.0 에서는, 디스플레이 하드웨어를 지원 할 수 있다면, 필요한 만큼 넓은 표면을 생성 할 수가 있다. 다만, 폭의 넓은 오프 스크린 표면을 선언하는 경우에는 주의가 필요하다. 비디오 카드 메모리가 요구된 넓이의 표면을 보관 유지할 수 없는 경우, 표면은 시스템 메모리에 생성 된다. 명시적으로 비디오 메모리를 선택해, 하드웨어가 그것을 지원 할 수 없는 경우, 그 호출은 실패한다. 상세한 것에 대하여는, 「와이드 표면의 생성」을 참조할것.


복합 표면과 플립핑 체인의 생성

[C++]

또,복합 표면을 생성 할 수도 있다. 복합 표면은,IDirectDraw7::CreateSurface 메소드의 호출로 생성 된 표면의 집합이다. CreateSurface 를 호출하면나무에 DDSCAPS_COMPLEX 플래그를 설정 하면, DirectDraw 는 명시적으로 지정된 표면 이외에, 은근히 1 개(살) 이상의 표면을 생성 한다. 복합 표면은, 단일 표면과 같게 관리할 수가 있다. 즉,IDirectDraw::Release 메소드의 호출로 모든 표면을 릴리즈 할 수가 있어 또,IDirectDrawSurface7::Restore 메소드의 호출로 모든 표면을 restore 할 수가 있다. 다만, 은근히 생성 된 표면의 Attach는 해제할 수 없다. 상세한 것에 대하여는, 「IDirectDrawSurface7::DeleteAttachedSurface」를 참조할것.

[Visual Basic]

또,복합 표면을 생성 할 수도 있다. 복합 표면은,DirectDraw7.CreateSurface 메소드의 호출로 생성 된 표면의 집합이다. CreateSurface 를 호출하면나무에 DDSCAPS_COMPLEX 플래그를 설정 하면, DirectDraw 는 명시적으로 지정된 표면 이외에, 은근히 1 개(살) 이상의 표면을 생성 한다. 복합 표면은, 단일 표면과 같게 관리할 수가 있다. 즉,DirectDrawSurface7.Restore 메소드의 호출로 모든 표면을 restore 할 수 있다. 다만, 은근히 생성 된 표면의 Attach는 해제할 수 없다. 상세한 것에 대하여는, 「DirectDrawSurface7.DeleteAttachedSurface 」를 참조할것.

생성 가능한 가장 유용한 복합 표면의 1 개는,플립핑 체인이다. 보통, 플립핑 체인은프라이머리 표면, 및 1 개(살) 이상의백 버퍼로부터 된다. DDSCAPS_FLIP 플래그는, 표면이 플립핑 체인의 일부인 것을 나타낸다. 이 방법으로 플립핑 체인을 생성 하려면 , DDSCAPS_COMPLEX 플래그도 설정하지 않으면 안 된다.

[C++]

다음의 예에서는, 프라이머리 표면 플립핑 체인의 생성 방법을 나타낸다.

DDSURFACEDESC2 ddsd2;
ddsd2.dwSize = sizeof(ddsd2);

// 어느 멤버가 유효한가 DirectDraw 에게 전한다.
ddsd2.dwFlags = DDSD_CAPS | DDSD_BACKBUFFERCOUNT;

// 1 개의 백 버퍼와 함께,
// 프라이머리 표면을 요구한다.
ddsd2.ddsCaps.dwCaps = DDSCAPS_COMPLEX | DDSCAPS_FLIP |
DDSCAPS_PRIMARYSURFACE;
ddsd2.dwBackBufferCount = 1;

위의예는, 더블 버퍼 플립핑 환경을 구축하는 것이다. 즉,IDirectDrawSurface7::Flip 메소드를 호출하면, 프라이머리 표면과 백 버퍼의 표면 메모리가 교환된다. DDSURFACEDESC2 구조체의 dwBackBufferCount 멤버의 값에 2 를 지정 하면, 2 개의 백 버퍼가 생성 된다. 또,Flip 를 호출할 때 마다 표면이 순환 패턴으로 순환해, 트리플 버퍼 플립핑 환경을 제공한다. 상세한 것에 대하여는, 「플립핑 표면」을 참조할것.

[Visual Basic]

다음의 예에서는, 프라이머리 표면 플립핑 체인의 생성 방법을 나타낸다.

Dim ddsd2 As DDSURFACEDESC2

'어느 멤버가 유효한가 DirectDraw 에게 전한다.
ddsd2.lFlags = DDSD_CAPS Or DDSD_BACKBUFFERCOUNT

' 1 개의 백 버퍼와 함께,
'프라이머리 표면을 요구한다.
ddsd2.ddsCaps.lCaps = DDSCAPS_COMPLEX Or DDSCAPS_FLIP Or _
DDSCAPS_PRIMARYSURFACE;
ddsd2.lBackBufferCount = 1

위의예는, 더블 버퍼 플립핑 환경을 구축하는 것이다. 즉,DirectDrawSurface7.Flip 메소드를 호출하면, 프라이머리 표면과 백 버퍼의 표면 메모리가 교환된다. DDSURFACEDESC2 형의 IBackBufferCount 멤버의 값에 2 를 지정 하면, 2 개의 백 버퍼가 생성 된다. 또,Flip 를 호출할 때 마다 표면이 순환 패턴으로 순환해, 트리플 버퍼 플립핑 환경을 제공한다. 상세한 것에 대하여는, 「플립핑 표면」을 참조할것.

주 : 3D 렌더링 타겟으로서 사용되는 표면으로부터 완성되는 플립핑 체인을 생성 하려면 , DDSCAPS_COMPLEX 및 DDSCAPS_FLIP 플래그 외에, 표면 기술의 DDSCAPS_3DDEVICE 능력 플래그를 반드시 포함하는 것.

[C++]

IDirectDraw3 이전의 인터페이스에서의 CreateSurface 메소드와는 달라, 깊이 버퍼에 Attach 된 렌더링 타겟 표면의 플립핑 체인을 생성 하기 위해서,IDirectDraw7::CreateSurface 를 사용할 수 없다. IDirectDraw7::CreateSurface 메소드가 받는 DDSURFACEDESC2 구조체에, 깊이 버퍼 비트 깊이를 지정하는 필드를 포함할 수 없다. 이 때문에, 어플리케이션에서는 명시적으로 깊이 버퍼 표면을 생성 해, 그 표면을 백 버퍼 렌더 링 타겟으로 Attach 하지 않으면 안 된다. 상세한 것에 대하여는, Direct3D 직접 모드의 「깊이 버퍼」를 참조할것.


와이드 표면의 생성

DirectDraw 에 의해, 프라이머리 표면보다 폭의 넓은 오프 스크린 표면을 비디오 메모리에 생성 할 수 있다. 이것이 가능한 것은, 디스플레이 디바이스가 와이드 표면을 지원 하면나무 뿐이다.

[C++]

와이드 표면이 지원 되고 있는지 어떤지를 조사하려면 ,IDirectDraw7::GetCaps 를 호출하고 나서, 그 때에 함께 보낸 최초의 DDCAPS 구조체의 dwCaps2 멤버에 DDCAPS2_WIDESURFACES 플래그가 있을지 어떨지를 찾는다. 이 플래그가 있으면(자), 프라이머리 표면보다 폭의 넓은 비디오 메모리 오프 스크린 표면을 생성 할 수가 있다.

DDCAPS2_WIDESURFACES 플래그가 존재하지 않을 때에, 비디오 메모리에 와이드 표면을 생성 하려고 하면(자), 실패해 DDERR_INVALIDPARAMS 를 돌려준다. 비록 그 드라이버가 DDCAPS2_WIDESURFACES 플래그를 분명히 했다고 해도, 극단적으로 큰 표면을 생성 하려고 하면(자), 실패할 가능성이 있는 것에 주의 해야 한다.

항상, 와이드 표면은 시스템 메모리 표면, 비디오 포트 표면, 및 실행 버퍼로 지원 된다.

[Visual Basic]

와이드 표면이 지원 되고 있는지 어떤지를 조사하려면 ,DirectDraw7.GetCaps 를 호출하고 나서, 그 때에 함께 보낸 최초의 DDCAPS 형의 Caps2 멤버에 DDCAPS2_WIDESURFACES 플래그가 있을지 어떨지를 찾는다. 이 플래그가 있으면(자), 프라이머리 표면보다 폭의 넓은 비디오 메모리 오프 스크린 표면을 생성 할 수가 있다.

DDCAPS2_WIDESURFACES 플래그가 존재하지 않을 때에, 비디오 메모리에 와이드 표면을 생성 하려고 하면(자), 실패해 DDERR_INVALIDPARAMS 를 돌려준다. 비록 그 드라이버가 DDCAPS2_WIDESURFACES 플래그를 분명히 했다고 해도, 극단적으로 큰 표면을 생성 하려고 하면(자), 실패할 가능성이 있는 것에 주의 해야 한다.

와이드 표면은, 항상 시스템 메모리 표면으로 지원 된다.


클라이언트 메모리 표면의 생성

클라이언트 메모리 표면은, 간단한 DirectDrawSurface 오브젝트이며, 이미지 데이터를 보관 유지하기 위해서 어플리케이션을 이전에 할당할 수 있었던 시스템 메모리를 사용한다. 이러한 표면을 생성 하는 것은 일반적이지 않지만, 생성 하는 것은 간단하다. 기존의 메모리 버퍼 위에의 DirectDraw 표면 기능을 사용할 필요가 있는 어플리케이션에서는 도움이 된다.

[C++]

표면의 생성시에, DirectDraw 에서는 표면의 픽셀 포맷과 같게, 표면의 넓이 (픽셀 단위)와 표면의 피치 (바이트 단위)에 대한 정보가 필요하다. 다만, 클라이언트 메모리에 관한 이 정보는, 생성 되는 표면을 DirectDraw 에게 전하지 않는 다른 타입의 표면에 있어서의 생성과는 달라, 이미 표면을 생성 하고 있는 것을 DirectDraw 에게 전한다. IDirectDraw7::CreateSurface 메소드에 건네주는 DDSURFACEDESC2 구조체에, 할당할 수 있었던 버퍼의 메모리 주소를 더하는 특성을 설정할 수 있다.

클라이언트 메모리 표면은, 일반적인 시스템 메모리 표면과 같이 동작한다. 다만 예외로서 DirectDraw 는 필요가 없어진 표면 메모리를 릴리즈 하려고는 하지 않는다. 메모리를 할당할 수 있었던 클라이언트의 릴리즈는, 어플리케이션이 실시한다.

다음의 예에서는, 메모리를 할당하는 경우에 대해 설명해, 64 × 64 픽셀의 24 비트 RGB 표면에 대한 DirectDrawSurface 오브젝트를 생성 한다.

// 이 예에서는, g_lpDD4 가 유효한 IDirectDraw7 인터페이스 포인터가 된다.

#define WIDTH  64 // 픽셀 단위.
#define HEIGHT 64
#define DEPTH  3  // 바이트 단위 (3 바이트 ==24 비트 ).

    HRESULT hr;
    LPVOID  lpSurface  = NULL;
    HLOCAL  hMemHandle = NULL;
    DDSURFACEDESC2 ddsd2;
    LPDIRECTDRAWSURFACE7 lpDDS;

    // 64 × 64 의 메모리를 할당한다 (픽셀 버퍼 마다 24 비트).
    // 버퍼가 불필요하게 되면(자), 어플리케이션에 의해
    //           이 버퍼가 릴리즈 된다.
    if (lpSurface = malloc((size_t) WIDTH*HEIGHT*DEPTH))
        ZeroMemory(lpSurface, (DWORD) WIDTH*HEIGHT*DEPTH);
    else
        return DDERR_OUTOFMEMORY;

    // 표면의 기술을 초기화한다.
    ZeroMemory(&ddsd2, sizeof(DDSURFACEDESC2));
    ZeroMemory(&ddsd2.ddpfPixelFormat, sizeof(DDPIXELFORMAT));
    ddsd2.dwSize = sizeof(ddsd2);
    ddsd2.dwFlags = DDSD_WIDTH | DDSD_HEIGHT | DDSD_LPSURFACE |
                    DDSD_PITCH | DDSD_PIXELFORMAT | DDSD_CAPS;
    ddsd2.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN |
                           DDSCAPS_SYSTEMMEMORY;
    ddsd2.dwWidth = WIDTH;
    ddsd2.dwHeight= HEIGHT;
    ddsd2.lPitch  = (LONG) DEPTH * WIDTH;
    ddsd2.lpSurface = lpSurface;

    // 픽셀 포맷을 24 비트 RGB (8-8-8)에 셋업 한다.
    ddsd2.ddpfPixelFormat.dwSize = sizeof(DDPIXELFORMAT);
    ddsd2.ddpfPixelFormat.dwFlags= DDPF_RGB;
    ddsd2.ddpfPixelFormat.dwRGBBitCount = (DWORD) DEPTH*8;
    ddsd2.ddpfPixelFormat.dwRBitMask    = 0x00FF0000;
    ddsd2.ddpfPixelFormat.dwGBitMask    = 0x0000FF00;
    ddsd2.ddpfPixelFormat.dwBBitMask    = 0x000000FF;

    // 표면을 생성 한다.
    hr = g_lpDD->CreateSurface(&ddsd2, &lpDDS, NULL);
    return hr;
[Visual Basic]

표면의 생성시에, DirectDraw 에서는 표면의 픽셀 포맷과 같게, 표면의 넓이 (픽셀 단위)와 표면의 피치 (바이트 단위)에 대한 정보가 필요하다. 다만, 클라이언트 메모리에 관한 이 정보는, 생성 되는 표면을 DirectDraw 에게 전하지 않는 다른 타입의 표면에 있어서의 생성과는 달라, 이미 표면을 생성 하고 있는 것을 DirectDraw 에게 전한다. DirectDraw7.CreateSurface 메소드에 건네주는 DDSURFACEDESC2 형에, 할당할 수 있었던 버퍼의 메모리 주소를 더하는 특성을 설정할 수 있다.

클라이언트 메모리 표면은, 일반적인 시스템 메모리 표면과 같이 동작한다. 다만 예외로서 DirectDraw 는 필요가 없어진 표면 메모리를 릴리즈 하려고는 하지 않는다. 메모리를 할당할 수 있었던 클라이언트의 릴리즈는, 어플리케이션이 실시한다.

다음의 예에서는, 메모리를 할당하는 경우에 대해 설명해, 64 × 64 픽셀의 24 비트 RGB 표면에 대한 DirectDrawSurface 를 생성 한다.

'이 예에서는, dd 가 유효한 DirectDraw7 오브젝트가 된다.

Const cWIDTH = 64 '픽셀 단위
Const cHEIGHT = 64
Const cDEPTH = 3 '바이트 단위 (3 바이트 = 24 비트)

Dim ddsd2 As DDSURFACEDESC2
Dim dds As DirectDrawSurface7
Private Sub Form_Load()

'표면의 기술을 초기화한다.
With ddsd2
. lFlags = DDSD_WIDTH Or DDSD_HEIGHT Or DDSD_PITCH Or DDSD_PIXELFORMAT Or DDSD_CAPS
. ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN Or DDSCAPS_SYSTEMMEMORY
. lWidth = cWIDTH
. lHeight = cHEIGHT
. lPitch = cDEPTH * cWIDTH
'픽셀 포맷을 24 비트 RGB (8-8-8)에 셋업 한다.
With . ddpfPixelFormat
. lFlags = DDPF_RGB
. lRGBBitCount = cDEPTH * 8
. lRBitMask = &HFF0000
. lGBitMask = &HFF00&
. lBBitMask = &HFF&
End With
End With

'표면을 생성 한다.
Set dds = dd.CreateSurface(ddsd2)

End Sub


플립핑 표면

DirectDraw 의 모든 표면은,플립핑 표면으로서 구축된다. 플립핑 표면이란,프런트 버퍼와백 버퍼간에 스왑 할 수 있는 메모리의 일부에 지나지 않는다 (보통, 이 원가요소는플립핑 체인으로 불린다. ) 대부분의 경우, 프런트 버퍼는프라이머리 표면이지만, 반드시 그런 필요는 없다.

[C++]

일반적으로,IDirectDrawSurface7::Flip 메소드를 이용해 표면 플립핑 처리를 요구하는 경우, 프라이머리 표면과 백 버퍼에 대한 표면 메모리에의 포인터는 스왑 된다. 플립핑은, 표면 메모리를 카피하는 것은 아니고, 메모리를 참조하기 위해서 디스플레이 디바이스의 사용하는 포인터를 바꾸는 것으로 실행된다 (DirectDraw 가 플립핑을 에뮬레이트 하고 있을 때는 예외이다. 이 경우는, 단지 표면을 카피한다. 백 버퍼가 디스플레이 메모리에 적합하지 않는 경우나, 하드웨어가 DirectDraw 를 지원 하지 않는 경우, DirectDraw 는 플립핑 처리를 에뮬레이트 한다). 플립핑 체인에 프라이머리 표면과 1 개 이상의 백 버퍼가 있는 경우, 다음의 그림에 나타내도록(듯이), 포인터는 순환적 패턴으로 교체된다.

[Visual Basic]

일반적으로,DirectDrawSurface7.Flip 메소드를 이용해 표면 플립핑 처리를 요구하는 경우, 프라이머리 표면과 백 버퍼에 대한 표면 메모리는 스왑 된다. 플립핑은, 표면 메모리를 카피하는 것은 아니고, 메모리를 참조하기 위해서 디스플레이 디바이스의 사용하는 표면을 바꾸는 것으로 실행된다 (DirectDraw 가 플립핑을 에뮬레이트 하고 있을 때는 예외이다. 이 경우는, 단지 표면을 카피한다. 백 버퍼가 디스플레이 메모리에 적합하지 않는 경우나, 하드웨어가 DirectDraw 를 지원 하지 않는 경우, DirectDraw 는 플립핑 처리를 에뮬레이트 한다). 플립핑 체인에 프라이머리 표면과 1 개 이상의 백 버퍼가 있는 경우, 다음의 그림에 나타내도록(듯이), 표면은 순환적 패턴으로 교체된다.

DirectDraw 오브젝트에 Attach 되고 있지만, 플립핑 체인의 일부에서는 없는 다른 표면은,Flip 메소드가 불려 가도 영향을 받지 않는다.

[C++]

DirectDraw 는, 오브젝트 자체를 스왑 하는 것이 아니라, DirectDrawSurface 오브젝트내의 표면 메모리 포인터를 스왑 하는 것으로, 표면의 플립핑을 실시하는 것을 생각해 내는 것. 이 때문에, 항상 같은 DirectDrawSurface 오브젝트 (즉 플립핑 체인을 생성 했을 때에 백 버퍼인 DirectDrawSurface 오브젝트)를 사용해, 임의의 타입의 플립핑 스킴으로 백 버퍼에 블리트 한다. 반대로, 항상 프런트 표면의 Flip 메소드를 호출해, 플립핑 처리를 실행한다.

프라이머리 표면 플립핑 체인이나 표시되는 오버레이 표면 플립핑 체인등의 표시되는 표면과 함께 작용하는 경우, DDFLIP_WAIT 플래그가 포함되지 않으면 Flip 메소드는 비동기가 된다. 이러한 표시되는 표면에서는, 하드웨어로 실제의 플립핑 처리가 생기기 전에,Flip 메소드가 돌아올 가능성이 있다 (하드웨어는 다음의 수직 리프레쉬가 일어날 때까지, 플립핑을 실시하지 않기 때문이다). 실제의 플립핑 처리가 보류중에,IDirectDrawSurface7::Lock ,IDirectDrawSurface7::Blt ,IDirectDrawSurface7::BltFast , 또는 IDirectDrawSurface7::GetDC 메소드를 호출해, 현재 표시되고 있는 표면의 배후의 백 버퍼를 잠그거나 블리트 할 수 없다. 플립핑 처리가 보류중에 이러한 메소드를 호출하려고 하면, 실패해 DDERR_WASSTILLDRAWING 를 돌려준다. 다만, 트리플 버퍼 스킴을 사용하고 있는 경우, 마지막 버퍼는 이용 가능인 채이다.

[Visual Basic]

DirectDraw 는, 오브젝트 자체를 스왑 하는 것이 아니라, DirectDrawSurface 오브젝트내의 표면 메모리를 스왑 하는 것으로, 표면의 플립핑을 실시하는 것을 생각해 내는 것. 이 때문에, 항상 같은 DirectDrawSurface 오브젝트 (즉 플립핑 체인을 생성 했을 때에 백 버퍼인 DirectDrawSurface 오브젝트)를 사용해, 임의의 타입의 플립핑 스킴으로 백 버퍼에 블리트 한다. 반대로, 항상 프런트 표면의 Flip 메소드를 호출해, 플립핑 처리를 실행한다.

프라이머리 표면 플립핑 체인이나 표시되는 오버레이 표면 플립핑 체인등의 표시되는 표면과 함께 작용하는 경우, DDFLIP_WAIT 플래그가 포함되지 않으면 Flip 메소드는 비동기가 된다. 이러한 표시되는 표면에서는, 하드웨어로 실제의 플립핑 처리가 생기기 전에,Flip 메소드가 돌아올 가능성이 있다 (하드웨어는 다음의 수직 리프레쉬가 일어날 때까지, 플립핑을 실시하지 않기 때문이다). 실제의 플립핑 처리가 보류중에,DirectDrawSurface7.Lock ,DirectDrawSurface7.Blt ,DirectDrawSurface7.BltColorFill ,DirectDrawSurface7.BltFast ,DirectDrawSurface7.BltFx ,DirectDrawSurface7.BltToDC 또는 DirectDrawSurface7.GetDC 메소드를 호출해, 현재 표시되고 있는 표면의 배후의 백 버퍼를 잠그거나 블리트 할 수 없다. 플립핑 처리가 보류중에 이러한 메소드를 호출하려고 하면, 실패해 DDERR_WASSTILLDRAWING 를 돌려준다. 다만, 트리플 버퍼 스킴을 사용하고 있는 경우, 마지막 버퍼는 이용 가능인 채이다.


표면에의 블리트

여기에서는, 어느 DirectDraw 표면으로부터 외에, 또는 표면이 있는 부분으로부터 외에 픽셀을 카피하는 것에 대하여 설명한다.

이하의 항목에 대해 기술한다.

  • 블리트에 대해
  • BltFast 에 의한 블리트
  • Blt 에 의한 블리트
  • 블리트의 타이밍
  • 투과형 블리트
  • 컬러 필
  • 멀티 윈도우에의 블리트


블리트에 대해

[C++]

이미지를 DirectDraw 표면에 카피하려면 ,IDirectDrawSurface7::Blt 와 IDirectDrawSurface7::BltFast 의 2 개의 메소드를 사용할 수 있다 (IDirectDrawSurface7::BltBatch 메소드는, DirectX 의 이 버젼에서는 이행되어 있지 않다). 이러한 메소드는 목적지 표면으로 불려 가 파라미터로서 전송원표면을 받는다. 목적지 및 전송원표면은 1 개 한편 같은 표면인 일도 가능하다. DirectDraw 에서는, over-write의 전에 모든 전송원픽셀을 보관 유지하기 위해(때문에), 오버랩의 걱정은 없다.

이행 된 2 개의 메소드에서는,Blt 가 보다 유연성이 풍부해,BltFast 가 보다 빠르다. 다만 이것은, 하드웨어 블리트가 없는 경우에 한정한다. 하드웨어의 블리트 능력을 결정하려면 ,IDirectDraw7::GetCaps 메소드의 lpDDDriverCaps 파라미터가 취득하는 DDCAPS 구조체를 사용한다. dwCaps 멤버에 DDCAPS_BLT 가 있는 경우, 하드웨어에는 적어도 최저의 블리트 능력이 있다.

[Visual Basic]

이미지를 DirectDraw 표면에 카피하려면 ,DirectDrawSurface7.Blt ,DirectDrawSurface7.BltColorFill ,DirectDrawSurface7.BltFast ,DirectDrawSurface7.BltFx 및 DirectDrawSurface7.BltToDC 의 5 개의 메소드를 사용할 수 있다. 이러한 메소드는 목적지 표면으로 불려 가 파라미터로서 전송원표면을 받는다. 목적지 및 전송원표면은 1 개 한편 같은 표면인 일도 가능하다. DirectDraw 에서는, over-write의 전에 모든 전송원픽셀을 보관 유지하기 위해(때문에), 오버랩의 걱정은 없다.

이행 된 2 개의 메소드에서는,Blt 가 보다 유연성이 풍부해,BltFast 가 보다 빠르다. 다만 이것은, 하드웨어 블리트가 없는 경우에 한정한다. 하드웨어의 블리트 능력을 결정하려면 ,DirectDraw7.GetCaps 메소드의 hwCaps 파라미터가 취득하는 DDCAPS 형을 사용한다. lCaps 멤버에 DDCAPS_BLT 가 있는 경우, 하드웨어에는 적어도 최저의 블리트 능력이 있다.


BltFast 에 의한 블리트

[C++]

IDirectDrawSurface7::BltFast 를 사용하는 경우, 카피되는 픽셀 (또는, 표면 모든 것을 지정하는 NULL) 및 목적지 표면의 x 좌표와 y 좌표로부터, 전송원표면의 유효한 직사각형을 줄 수가 있다. 전송원직사각형은 목적지 표면의 좌상구석에 적합할 수 없으면 안 되는지, 또는 호출이 DDERR_INVALIDRECT 의 반환값으로 실패한다. BltFast 는, Attach 상태의 클립퍼가 있는 표면에서는 사용할 수 없다.

BltFast 를 사용하는 경우, 신축(스트레치), 미러링, 또는 다른 이펙트는 실행할 수 없다.

BltFast 의 예

다음의 예에서는, 오프 스크린 표면 (lpDDSOffOne)으로부터의 픽셀을 프라이머리 표면 (lpDDSPrimary)에 카피한다. 플래그는, 블리트가 릴리즈 되자마자 연산의 발생을 확보해, 전송원이미지의 투과형 픽셀은 카피되지 않는다 (이러한 플래그의 의미에 대해서는, 「블리트의 타이밍」 및 「투과형 블리트」를 참조할것).

lpDDSPrimary->BltFast(
        100, 200,    // 목적지의 좌상 xy
        lpDDSOffOne, // 전송원표면
        NULL,        // 전송원직사각형 = 표면 전체
        DDBLTFAST_WAIT | DDBLTFAST_SRCCOLORKEY );
[Visual Basic]

DirectDrawSurface7.BltFast 를 사용하는 경우, 전송원표면의 유효한 직사각형을 주고 (또는 표면 모든 것을 의미하는 하늘의 RECT 형을 지정한다), 및 목적지 표면의 x 좌표와 y 좌표로부터 카피할 수가 있다. 전송원직사각형은 목적지 표면의 좌상구석에 적합할 수 없으면 안 된다. 아주 없으면, 호출이 DDERR_INVALIDRECT 의 반환값으로 실패한다. BltFast 는, Attach 상태의 클립퍼가 있는 표면에서는 사용할 수 없다.

BltFast 를 사용하는 경우, 신축(스트레치), 미러링, 또는 다른 이펙트는 실행할 수 없다.

BltFast 의 예

다음의 예에서는, 오프 스크린 표면 (DDSOffOne)으로부터의 픽셀을 프라이머리 표면 (DDSPrimary)에 카피한다. 플래그는, 블리트가 릴리즈 되자마자 연산의 발생을 확보해, 전송원이미지의 키로 뽑아진 픽셀은 카피되지 않는다 (이러한 플래그의 의미에 대해서는, 「블리트의 타이밍」 및 「투과형 블리트」를 참조할것).

DDSPrimary.BltFast 100, 200, DDSOffOne, SrcRect, DDBLTFAST_WAIT Or DDBLTFAST_SRCCOLORKEY


Blt 에 의한 블리트

[C++]

IDirectDrawSurface7::Blt 메소드를 사용하는 경우, 전송원표면 (또는, 표면 모든 것을 지정하는 NULL)의 유효한 직사각형, 및 카피되는 전송원이미지에의 목적지 표면의 직사각형을 준다 (NULL 는, 표면 모든 것을 커버하는 것을 의미한다). 클립퍼가 목적지 표면에 Attach 되는 경우, 목적지 직사각형의 경계는 표면의 외측에 배치할 수 있어 클리핑이 실행된다. 클립퍼가 없는 경우는, 목적지 직사각형이 표면의 안쪽에 완전하게 배치되는지, 다른 메소드가 DDERR_INVALIDRECT 로 실패한다 (클리핑의 상세한 것에 대하여는, 「클립퍼」를 참조할것).

스케일링

Blt 메소드는, 전송원이미지의 사이즈를 목적지 직사각형과 적합하도록(듯이) 자동적으로 재스케일링 한다. 사이즈의 재스케일링을 하고 싶지 않은 경우는, 최선의 퍼포먼스를 위해서(때문에), 전송원 및 목적지 직사각형이 정확하게 같은 사이즈인 것을 확인하는지,IDirectDrawSurface7:BltFast 를 사용한다 ( 「BltFast 에 의한 블리트」를 참조할것).

스케일링에 대한 하드웨어 가속기는, 디바이스에 대한 DDCAPS 구조체의 dwFXCaps 멤버의 DDFXCAPS_BLT* 플래그에 의존한다. 예를 들어, 디바이스에 DDFXCAPS_BLTSTRETCHX 는 아니고 DDFXCAPS_BLTSTRETCHXN 능력이 있는 경우, 전송원직사각형의 x 축이 정수배 때는 어시스트 할 수 있지만, 정수배 이외의 (임의의) 스케일링이 되고 있을 때는 어시스트 할 수 없다.

또, 디바이스에서는, 픽셀의 단순한 곱셈이나 삭제보다, 보간에 의해 스케일링을 실시하는 산술 스케일링을 지원 하는 경우가 있다. 예를 들어, 축이 1/3 증가하는 경우, 픽셀은 다시 발라 그 축의 1/3 픽셀마다의 증가에 의해 생성되는 원의 이미지에 의해 가까운 근사치가 주어진다.

어플리케이션은,Blt 에게 건네지는 DDBLTFX 구조체의 dwDDFX 멤버에 있는 DDBLTFX_ARITHSTRETCHY 플래그의 설정 이외는, 드라이버에 의한 스케일링의 타입을 제어할 수 없다. 이 플래그는, y 축으로 산술 신축(스트레치)를 실시하는 것을 요구한다. DirectDraw API 에서는, x 축의 산술 확대와 산술 축소는 현재 지원 하고 있지 않지만, 드라이버는 디폴트로 이것들을 실행할 수 있다.

다른 이펙트

Blt 를 사용할 때, 스케일링 이외의 특정의 이펙트를 필요로 하지 않는 경우는,lpDDBltFx 파라미터로서 NULL 를 건네줄 수가 있다. 그 이외는,DDBLTFX 구조체로 지정되는 여러가지 이펙트를 선택할 수 있다. 또 동시에, HEL 가컬러 필과 미러링을 지원 하므로, 이것들은 항상 이용할 수 있다. 다른 대부분의 이펙트는 하드웨어 지원에 의한다.

HEL 의 이펙트 능력을 모두 보려면 , DirectX SDK 로 제공되는 DDraw Caps 유틸리티를 실행해, HEL 메뉴로부터 HEL FX Caps 를 선택한다. 여러가지 플래그의 설명은, 「DDCAPS 」를 참조할것. 또,IDirectDraw7::GetCaps 메소드를 사용해, 각자의 어플리케이션에 있어서의 HEL 능력도 체크할 수 있다.

IDirectDrawSurface7::Blt 메소드에게 건네지는 DDBLTFX 구조체에 있는 멤버의 1 개의 값을 요구하는 이펙트를 지정하는 경우, 구조체의 멤버가 유효한 것을 나타내는 적절한 플래그도 dwFlags 파라미터에 포함하지 않으면 안 된다.

DDBLTFX 의 dwFlags 멤버에 있어서의 플래그의 설정만을 요구하는 이펙트도 있다. 이 중의 1 개(살)은 DDBLTFX_NOTEARING 이다. 이 플래그는, 애니메이션 된 이미지를 프런트 버퍼에 직접 블리트 할 경우에 사용할 수 있기 (위해)때문에, 블리트는 스크린 리프레쉬 및 티어링의 가능성과 동시에 발생할 수 있다. 또, 미러링과 회전도 플래그를 사용해 설정된다.

블리트 이펙트에는,BitBlt 와 같은 GDI 함수로 사용되는 일반적인 라스터 처리 (ROP)가 포함된다. HEL 가 지원 하는 ROP 는 SRCCOPY (디폴트), BLACKNESS, 및 WHITENESS 뿐이다. 다른 ROP 를 지원 하는 하드웨어는, 드라이버에 대한 DDCAPS 구조체로 시험할 수가 있다. Blt 메소드와 함께 표준적인 모든 ROP 를 사용하고 싶은 경우는,DDBLTFX 구조체의 dwROP 멤버의 ROP 에 플래그를 세운다.

DDBLTFX 구조체의 dwDDROP 멤버는, ROP 의 특징을 DirectDraw 로 지정하기 위해서(때문에) 있다. 그러나, 현시점에서 정의되고 있는 ROP 는 없다.

알파값과 Z 값

DirectDraw 블리트에서는, 불투명도와 깊이값을 현시점에서는 지원 하고 있지 않다. 알파값이 픽셀 포맷에 저장 되는 경우, 알파값은 목적지 직사각형의 모든 알파값에 단지 over-write 한다. 알파 버퍼와 Z 버퍼로부터의 값은 무시된다. 알파 채널 과 Z 버퍼 ("dwAlpha" 와 "dwZ" 로 시작되는 이름의 멤버)로 실시하는 DDBLTFX 구조체의 멤버, 및 Blt 에 대응하는 플래그는 사용되지 않는다. 그리고,DDBLTFX 구조체의 dwDDFX 멤버의 DDBLTFX_ZBUFFERBASEDEST 및 DDBLTFX_ZBUFFERRANGE 플래그에 제공한다.

현시점에서는, Z 버퍼는 Direct3D 어플리케이션으로 밖에 사용되지 않지만,IDirectDrawSurface7::Blt 를 사용해 DDBLT_DEPTHFILL 플래그를 설정하는 것으로써, Z 버퍼 표면의 깊이값을 설정할 수 있다. 상세한 것에 대하여는, Direct3D 직접 모드의 「깊이 버퍼의 클리어」를 참조할것.

Direct3D 의 알파 채널 및 Z 버퍼의 사용에 대해서는, 다음의 항목을 참조할것.

  • 알파 블렌딩 스테이트
  • 깊이 버퍼란

Blt 의 예

다음에 나타내는 예에서는,lpDDS 가 유효한 IDirectDrawSurface7 포인터이라고 가정해, 왼쪽에서 오른쪽으로 직사각형을 미러링 하는 것으로써 표면내에 좌우 대칭의 이미지를 생성 한다.

RECT     rcSource, rcDest;
DDBLTFX  ddbltfx;

ZeroMemory(&ddbltfx, sizeof(ddbltfx));
ddbltfx.dwSize = sizeof(ddbltfx);
ddbltfx.dwDDFX = DDBLTFX_MIRRORLEFTRIGHT;

rcSource.top = 0; rcSource.left = 0;
rcSource.bottom = 100; rcSource.right = 200;
rcDest.top = 0; rcDest.left = 201;
rcDest.bottom = 100; rcDest.right = 401;

HRESULT hr = lpDDS->Blt(&rcDest,
                        lpDDS,
                        &rcSource,
                        DDBLT_WAIT | DDBLT_DDFX,
                        &ddbltfx);
[Visual Basic]

DirectDrawSurface7.Blt 메소드를 사용하는 경우, 전송원표면 (또는 표면 모든 것을 지정하는 하늘의 RECT)의 유효한 직사각형, 및 카피되는 전송원이미지에의 목적지 표면의 직사각형을 줄 수가 있다 (하늘의 RECT 는, 표면 모든 것을 커버하는 것을 의미한다). 클립퍼가 목적지 표면에 Attach 되는 경우, 목적지 직사각형의 경계는 표면의 외측에 배치할 수 있어 클리핑이 실행된다. 클립퍼가 없는 경우는, 목적지 직사각형이 표면의 안쪽에 완전하게 배치되는지, 다른 메소드가 DDERR_INVALIDRECT 로 실패한다. (클리핑에 대해서는, 「클립퍼」를 참조할것).

스케일링

Blt 메소드는, 전송원이미지의 사이즈를 목적지 직사각형과 적합하도록(듯이) 자동적으로 재스케일링 한다. 사이즈의 재스케일링을 하고 싶지 않은 경우는, 최선의 퍼포먼스를 위해서(때문에), 전송원 및 목적지 직사각형이 정확하게 같은 사이즈인 것을 확인하는지,DirectDrawSurface7.BltFast 를 사용한다 ( 「BltFast 에 의한 블리트」를 참조할것).

스케일링에 대한 하드웨어 가속기는, 디바이스에 대한 DDCAPS 형의 lFXCaps 멤버의 DDFXCAPS_BLT* 플래그에 의존한다. 예를 들어, 디바이스에 DDFXCAPS_BLTSTRETCHX 는 아니고 DDFXCAPS_BLTSTRETCHXN 능력이 있는 경우, 전송원직사각형의 x 축이 정수배 때는 어시스트 할 수 있지만, 정수배 이외의 (임의의) 스케일링이 되고 있을 때는 어시스트 할 수 없다.

또, 디바이스에서는, 픽셀의 단순한 곱셈이나 삭제보다, 보간에 의해 스케일링을 실시하는 산술 스케일링을 지원 하는 경우가 있다. 예를 들어, 축이 1/3 배에 증가하는 경우, 픽셀은 다시 발라 그 축의 1/3 픽셀마다의 증가에 의해 생성되는 원의 이미지에 의해 가까운 근사치가 주어진다.

어플리케이션은,Blt 에게 건네지는 DDBLTFX 형의 lDDFX 멤버에 있는 DDBLTFX_ARITHSTRETCHY 플래그의 설정 이외는, 드라이버에 의한 스케일링의 타입을 제어할 수 없다. 이 플래그는, y 축으로 산술 신축(스트레치)를 실시하는 것을 요구한다. DirectDraw API 에서는, x 축의 산술 확대와 산술 축소는 현재 지원 하고 있지 않지만, 드라이버는 디폴트로 이것들을 실행할 수 있다.

다른 이펙트

스케일링 이외의 특정의 이펙트를 필요로 하지 않는 경우는,DirectDrawSurface7.BltFx 메소드를 사용한다. 이 메소드에서는,DDBLTFX 형으로 지정되는 여러가지 이펙트를 선택할 수 있다. 또 동시에, HEL 가컬러 필과 미러링을 지원 하므로, 이것들은 항상 이용할 수 있다. 다른 대부분의 이펙트는 하드웨어 지원에 의한다.

HEL 의 이펙트 능력을 모두 보려면 , DirectX SDK 로 제공되는 Ddraw Caps 유틸리티를 실행해, HEL 메뉴로부터 HEL FX Caps 를 선택한다. 여러가지 플래그의 설명은, 「DDCAPS 」를 참조할것. 또,DirectDraw7.GetCaps 메소드를 사용해, 각자의 어플리케이션에 있어서의 HEL 능력도 체크할 수 있다.

DirectDrawSurface7.BltFx 메소드에게 건네지는 DDBLTFX 형에 있는 멤버의 1 개의 값을 요구하는 이펙트를 지정하는 경우, 형태의 멤버가 유효한 것을 나타내는 적절한 플래그도 flags 파라미터에 포함하지 않으면 안 된다.

DDBLTFX 의 IDDFX 멤버에 있어서의 플래그의 설정만을 요구하는 이펙트도 있다. 이 중의 1 개(살)은 DDBLTFX_NOTEARING 이다. 이 플래그는, 애니메이션 된 이미지를 프런트 버퍼에 직접 블리트 할 경우에 사용할 수 있기 (위해)때문에, 블리트는 스크린 리프레쉬 및 티어링의 가능성과 동시에 발생할 수 있다. 또, 미러링과 회전도 플래그를 사용해 설정된다.

블리트 이펙트에는,BitBlt 와 같은 GDI 함수로 사용되는 일반적인 라스터 처리 (ROP)가 포함된다. HEL 가 지원 하는 ROP 는 SRCCOPY (디폴트), BLACKNESS, 및 WHITENESS 뿐이다. 다른 ROP 를 지원 하는 하드웨어는, 드라이버에 대한 DDCAPS 형으로 시험할 수가 있다. Blt 메소드와 함께 표준적인 모든 ROP 를 사용하고 싶은 경우는,DDBLTFX 형의 IROP 멤버의 ROP 에 플래그를 세운다.

DDBLTFX 형의 IDDROP 멤버는, ROP 의 특징을 DirectDraw 로 지정하기 위해서(때문에) 있다. 그러나, 현시점에서 정의되고 있는 ROP 는 없다.

알파값과 Z 값

DirectDraw 블리트에서는, 불투명도와 깊이값을 현시점에서는 지원 하고 있지 않다. 알파값이 픽셀 포맷에 저장 되는 경우, 알파값은 목적지 직사각형의 모든 알파값에 단지 over-write 한다. 알파 버퍼와 Z 버퍼로부터의 값은 무시된다. 알파 채널과 Z 버퍼 ("lAlpha" 와 "lZ" 로 시작되는 이름의 멤버)로 실시하는 DDBLTFX 형의 멤버, 및 Blt 에 대응하는 플래그는 사용되지 않는다. 그리고,DDBLTFX 형의 lDDFX 멤버의 DDBLTFX_ZBUFFERBASEDEST 및 DDBLTFX_ZBUFFERRANGE 플래그에 제공한다.

현시점에서는, Z 버퍼는 Direct3D 어플리케이션으로 밖에 사용되지 않지만,IDirectDrawSurface7.Blt 를 사용해 DDBLT_DEPTHFILL 플래그를 설정하는 것으로써, Z 버퍼 표면의 깊이값을 설정할 수 있다. 상세한 것에 대하여는, Direct3D 직접 모드의 「깊이 버퍼의 클리어」를 참조할것.

Direct3D 의 알파 채널 및 Z 버퍼의 사용에 대해서는, 다음의 항목을 참조할것.

  • 알파 블렌딩 스테이트
  • 깊이 버퍼란

Blt 의 예

다음에 나타내는 예에서는,DDS 가 유효한 DirectDrawSurface7 오브젝트이라고 가정해, 왼쪽에서 오른쪽으로 직사각형을 미러링 하는 것으로써 표면내에 좌우 대칭의 이미지를 생성 한다.

rcSource As RECT
rcDest As RECT
ddbltfx As ddbltfx

ddbltfx.lDDFX = DDBLTFX_MIRRORLEFTRIGHT

rcSource.Top = 0
rcSource.Left = 0
rcSource.Bottom = 100
rcSource.Right = 200
rcDest.Top = 0
rcDest.Left = 201
rcDest.Bottom = 100
rcDest.Right = 401

dds.BltFx rcDest, dds, rcSource, DDBLT_WAIT Or DDBLT_DDFX, ddbltfx


블리트의 타이밍

[C++]

IDirectDrawSurface7::Blt 또는 IDirectDrawSurface7::BltFast 를 사용해 픽셀을 표면에 카피하는 경우, 하드웨어 블리트가 커멘드를 받을 준비가 되어 있지 않기 위해(때문에), 메소드가 DDERR_WASSTILLDRAWING 로 실패하는 경우가 있다.

블리트가 정상적으로 종료하는 것을 기다리는 동안에 실시해야 할 급한 태스크가 없다면,Blt 의 dwFlags 파라미터에 DDBLT_WAIT 플래그를 지정하거나BltFast 에 대해서 동치의 DDBLTFAST_WAIT 플래그를 지정할 수 있다. 이 플러그는, 블리트가 끝날 때까지 (또는, DDERR_WASSTILLDRAWING 이외의 에러가 생길 때까지) 어플리케이션은 대기 상태가 된다.

Blt 는 다른 플래그 (DDBLT_ASYNC)도 사용할 수 있다. 이 플래그는, 하드웨어의 FIFO (퍼스트 인, 퍼스트 아웃) 기다리는 행렬 능력을 이용해, 어플리케이션은 대기 상태가 되지 않는다.

[Visual Basic]

DirectDrawSurface7.Blt ,DirectDrawSurface7.BltColorFill ,DirectDrawSurface7.BltFast ,DirectDrawSurface7.BltFx 또는 DirectDrawSurface7.BltToDC 의 어느쪽이든을 사용해 픽셀을 표면에 카피하는 경우, 하드웨어 블리트가 커멘드를 받을 준비가 되어 있지 않기 위해(때문에), 메소드가 DDERR_WASSTILLDRAWING 로 실패하는 경우가 있다.

블리트가 정상적으로 종료하는 것을 기다리는 동안에 실시해야 할 급한 태스크가 없다면,Blt 의 dwFlags 파라미터에 DDBLT_WAIT 플래그를 지정하거나BltFast 에 대해서 동치의 DDBLTFAST_WAIT 플래그를 지정할 수 있다. 이 플러그는, 블리트가 끝날 때까지 (또는, DDERR_WASSTILLDRAWING 이외의 에러가 생길 때까지) 어플리케이션은 대기 상태가 된다.

Blt 는 다른 플래그 (DDBLT_ASYNC)도 사용할 수 있다. 이 플래그는, 하드웨어의 FIFO (퍼스트 인, 퍼스트 아웃) 기다리는 행렬 능력을 이용해, 어플리케이션은 대기 상태가 되지 않는다.


투과형 블리트

여기에서는, 직사각형 이미지의 일부를 선택적으로 카피하는 블리트의 사용과 전송원 및 목적지컬러 키의 사용의 이론과 실천에 대해 가리킨다.

이론에는 다음의 항목이 포함된다.

  • 투과형 블리트란?

DirectDraw 의 투과형 블리트의 실행에 있어서의 정보에 대해서는, 다음의 항목을 참조할것.

  • 컬러 키 포맷
  • 컬러 키의 설정
  • 컬러 키에 의한 블리트


컬러 필

[C++]

단색으로 표면 전체 또는 일부를 묻으려면 , DDBLT_COLORFILL 플래그와 함께 IDirectDrawSurface7::Blt 메소드를 사용한다. 이 기술에 의해, 재빠르게 영역을 소거하거나 고정색의 백그라운드를 드로잉(Drawing) 할 수 있다.

다음에 나타내는 예에서는, 픽셀 포맷화등 파랑의 수치를 취득한 후에, 청색으로 표면 전체를 묻는다.

/* lpDDS 가 IDirectDrawSurface7 인터페이스에의
유효한 값이라고 가정한다.  */

HRESULT ddrval;
DDPIXELFORMAT ddpf;

ddpf.dwSize = sizeof(ddpf);
if (SUCCEEDED(lpDSS->GetPixelFormat(&ddpf))
{
    DDBLTFX ddbltfx;

    ddbltfx.dwSize = sizeof(ddbltfx);
    ddbltfx.dwFillColor = ddpf.dwBBitMask; // 순수한 파랑.

    ddrval = lpDDS->Blt(
        NULL,        // 목적지는 표면 전체.
        NULL,        // 전송원표면 없음.
        NULL,        // 전송원직사각형 없음.
        DDBLT_COLORFILL, &ddbltfx);

    switch(ddrval)
    {
        case DDERR_WASSTILLDRAWING:
            .
            .
            .
        case DDERR_SURFACELOST:
            .
            .
            .
        case DD_OK:
            .
            .
            .
        default:
    }
}
[Visual Basic]

단색으로 표면 전체 또는 일부를 묻으려면 ,DirectDrawSurface7.BltColorFill 메소드를 사용한다. 이 기술에 의해, 재빠르게 영역을 소거하거나 고정색의 백그라운드를 드로잉(Drawing) 할 수 있다.


멀티 윈도우에의 블리트

DirectDraw 오브젝트 및 DirectDrawClipper 오브젝트를 사용 하면, 표준 협조 레벨로 실행하는 어플리케이션에 의해 생성 되는 멀티 윈도우에 블리트 할 수 있다. 상세한 것에 대하여는, 「멀티 윈도우에서의 클립퍼의 사용」을 참조할것.

서로의 프라이머리 표면에 블리트 하는 복수의 DirectDraw 오브젝트를 생성 하는 것은, 권유받지 않는다.


표면의 소실과 restore

표면 메모리의 부분을 나타내는 DirectDrawSurface 오브젝트가, 반드시 릴리즈 될 필요가 없음에도 불구하고, DirectDrawSurface 오브젝트에 관련지을 수 있었던 표면 메모리가 릴리즈 되는 일이 있다. DirectDrawSurface 오브젝트가 표면 메모리를 소실했을 경우, 많은 메소드에서는 DDERR_SURFACELOST 를 돌려주어 다른 액션을 실행하지 않는다.

[C++]

디스플레이 모드가 변경되거나 다른 어플리케이션이 디스플레이 카드에의 배타 액세스를 받아, 그 디스플레이 카드에 할당할 수 있었던 표면 메모리를 모두 릴리즈 했을 경우, 표면은 소실한다. IDirectDrawSurface7::Restore 메소드는, 소실한 표면을 재생성 해, DirectDrawSurface 오브젝트에 재접속한다. 어플리케이션으로 1 개 이상의 표면을 사용하는 경우,IDirectDraw7::RestoreAllSurfaces 메소드를 호출하는 것으로, 한 번에 모든 표면을 restore 할 수 있다.

[Visual Basic]

디스플레이 모드가 변경되거나 다른 어플리케이션이 디스플레이 카드에의 배타 액세스를 받아, 그 디스플레이 카드에 할당할 수 있었던 표면 메모리를 모두 릴리즈 했을 경우, 표면은 소실한다. DirectDrawSurface7.Restore 메소드는, 소실한 표면을 재생성 해, DirectDrawSurface 오브젝트에 재접속한다. 어플리케이션으로 1 개 이상의 표면을 사용하는 경우,DirectDraw7.RestoreAllSurfaces 메소드를 호출하는 것으로, 한 번에 모든 표면을 restore 할 수 있다.

표면의 restore에서는, 소실하기 전의 표면에 존재할 가능성이 있는 비트 맵을 재로드하지 않는다. 이전 으로 유지한 그래픽스는, 완전하게 복구 이루어 없으면 안 된다.


표면의 COM 참조 카운트 의미들

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

COM 에 준거 하면 말하는 것은, DirectDraw 가 참조 카운트를 사용해 오브젝트의 유효기간을 관리하기 위한 일정한 규칙에 따르는 것을 의미한다. COM 의 개념에 대해서는, COM 의 문서를 참조할것. DirectDraw 관련의 설명에 대해서는, 「친오브젝트와 아이 오브젝트의 유효기간」을 참조할것.

COM 의 규칙에 의하면, 인터페이스 포인터를 다른 변수로 설정하거나 다른 오브젝트에 건네주는 것에 의해 카피했을 경우, 그 오브젝트에 대한 다른 참조가 되므로, 변경을 반영시키려면 , 그 인터페이스의 IUnknown::AddRef 메소드를 호출하지 않으면 안 된다. DirectDraw 오브젝트를 조작하려면 , COM 의 참조 카운트 규칙에 따를 뿐만 아니라, DirectDraw 가 참조 카운트를 내부에서 갱신하는 구조를 이해해 둘 필요가 있다. 클립퍼나 팔레트 관련의 메소드는 그러한 오브젝트의 참조 카운트만을 변경하지만, 일부의 DirectDraw 메소드는 관련하는 표면의 참조 카운트도 변경한다 (복합 표면 플립핑 체인 관련의 메소드의 상당수는 이것에 해당한다). 이러한 구조를 이해해 두면(자), 어플리케이션의 안정성이 향상해, 메모리 누수를 방지할 수가 있다. 여기에서는, 다음의 항목에 대해 기술한다.

  • 참조 카운트의 증감
  • 복합 표면의 참조 카운트
  • 표면의 릴리즈

주 : DirectDraw 오브젝트의 참조 카운트에 대해서는, 이 주제로 설명하는 메소드등과의 관계 외에도, 몇개인가 주의하지 않으면 안 되는 것이 있다. 상세한 것에 대하여는, 「DirectDraw 오브젝트」의 「친오브젝트와 아이 오브젝트의 유효기간」을 참조할것.


참조 카운트의 증감

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

몇개의 DirectDraw 메소드는 표면의 참조 카운트를 변경하지만, 표면에 관련지을 수 있던 다른 오브젝트에 영향을 주는 메소드도 있다. 여기에서는 전자를 「표면만 변경」, 후자를 「크로스 오브젝트 변경」이라고 말한다.

표면만 변경
「표면만 변경」의 경우, 그 이름의 나타내는 대로, 표면 오브젝트의 참조 카운트만이 변경된다. 예를 들어,IDirectDraw7::EnumSurfaces 메소드를 사용해, 특정의 조건을 채우는 현재의 표면을 열거했을 경우, 메소드가 지정된 콜백 함수를 기동 하면,IDirectDrawSurface7 인터페이스에의 포인터가 건네받지만, 어플리케이션이 포인터를 받기 전에, 그 오브젝트의 참조 카운트가 인크리먼트(increment) 된다. 따라서, 오브젝트의 처리가 완료하면(자), 그 오브젝트를 릴리즈 해야 한다. 보통, 콜백 루틴의 끝에 릴리즈 하는지, 그 오브젝트를 보관 유지할 필요가 있는 경우에는 다음에 릴리즈 한다.

그 외, 플립핑 체인등의 복합 표면에서도, 표면만 변경이 적용된다. 복합 표면은 표면의 집합이지만, 대부분의 경우 DirectDraw 에서는 단일의 오브젝트로서 다루어지므로, 참조 카운트의 취급에는 주의를 필요로 한다. 즉,IDirectDrawSurface7::GetAttachedSurface 및 IDirectDrawSurface7::AddAttachedSurface 메소드는 표면의 참조 카운트를 인크리먼트(increment) 해,IDirectDrawSurface7::DeleteAttachedSurface 메소드는 감소 한다. 이러한 메소드에 의해, 현재의 표면에 Attach 되고 있는 표면의 참조 카운트가 변경될 것은 없다. 상세한 것에 대하여는, 이러한 메소드의 레퍼런스와 「복합 표면의 참조 카운트」를 참조할것.

크로스 오브젝트 변경
「크로스 오브젝트 변경」은, 클립퍼나 팔레트 등, 그 표면에 대한 태스크를 실행하는 다른 오브젝트와 표면을 관련지을 수 있고 있는 경우에 적용된다.

IDirectDrawSurface7::SetClipper 이나 IDirectDrawSurface7::SetPalette 메소드는, Attach 되고 있는 오브젝트의 참조 카운트를 인크리먼트(increment) 한다. 오브젝트가 Attach 되면(자), 표면이 그러한 오브젝트를 관리하지만, 표면이 릴리즈 되면(자), Attach 된 오브젝트도 자동적으로 릴리즈 된다 (이 때문에, 어플리케이션에 따라서는, 이러한 호출이 성공하고 나서 오브젝트를 릴리즈 한다. 이것은 확실하고 유효한 방법이다).

클립퍼나 팔레트가 표면에 Attach 되면(자),IDirectDrawSurface7::GetClipper 이나 IDirectDrawSurface7::GetPalette 메소드를 호출해, 그것들을 재차 취득할 수가 있다. 이러한 메소드는 인터페이스 포인터의 카피를 돌려주므로, 취득된 오브젝트의 참조 카운트가 은근히 인크리먼트(increment) 된다. 인터페이스의 처리가 완료하면(자), 잊지 않고 그 인터페이스를 릴리즈 해야 한다. 오브젝트가 Attach 된 표면이, 그 오브젝트에 대한 참조를 보관 유지하고 있는 한, 인터페이스가 가리키는 오브젝트가 릴리즈 되지 않는다.


복합 표면의 참조 카운트

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

플립핑 체인등의 복합 표면의 조작에 사용하는 메소드는 모두, 표면 인터페이스 포인터를 사용하므로, 표면의 참조 카운트에 영향을 준다. 복합 표면은, 실제로는 단일 표면의 집합이므로, 참조 카운트의 처리에는 몇개의 주의가 필요하다. 우선,IDirectDrawSurface7::GetAttachedSurface 메소드는, 현재의 표면에 Attach 된 표면에의 표면 인터페이스를 돌려준다. 취득되는 인터페이스의 참조 카운트를 인크리먼트(increment) 하고 나서 인터페이스를 돌려주므로, 불필요하게 되었을 경우에는 그 인터페이스를 릴리즈 할 필요가 있다. IDirectDrawSurface7::AddAttachedSurface 메소드는, 새로운 표면을 현재의 표면에 Attach 한다. 또,AddAttachedSurface 메소드는, Attach 된 표면의 카운트를 인크리먼트(increment) 한다. 체인으로부터 표면을 삭제해, 은근히 그 참조 카운트를 감소 하려면 ,IDirectDrawSurface7::DeleteAttachedSurface 메소드를 사용한다.

이러한 메소드로 주의하지 않으면 안 되는 것은, 복합 표면을 구성하는 다른 오브젝트의 참조 카운트는 변경되지 않는 것이다. GetAttachedSurface 메소드는, 취득하는 표면의 참조 카운트를 인크리먼트(increment) 하는 것만으로, 그 표면이 Attach 된 표면의 카운트에는 영향을 주지 않는다 (IUnknown::AddRef 메소드를 은근히 호출하는 경우도 마찬가지이다). 따라서, 복합 표면에서는, 종속 표면의 참조 카운트가 제로가 되기 전에, 프라이머리 표면의 참조 카운트가 제로가 된다. 프라이머리 표면의 참조 카운트가 제로가 되면(자), 그 표면에 Attach 된 다른 표면은, 참조 카운트의 현재의 값에 관계없이 릴리즈 된다 (나무가지를 자르면(자) 키마타체가 넘어지는 것과 닮아 있다. 이 경우, 프라이머리 표면이 간이다). 프라이머리 표면의 할당이 삭제된 다음에 종속 표면에 액세스 하려고 하면(자), 메모리에 장해가 발생한다.

이러한 문제가 발생하는 것을 막기 위해, 프라이머리 표면을 릴리즈 하기 전에, 모든 종속 표면을 릴리즈 할 필요가 있다. 어플리케이션이 보관 유지하고 있는 참조를 추적해, 프라이머리 표면에의 참조가 보관 유지되고 있는 것을 확인하고 나서, 종속 표면에 액세스 할 방법이 확실하다.


표면의 릴리즈

[C++]

모든 COM 인터페이스와 같이, 필요가 없어진 표면은 IDirectDrawSurface7::Release 메소드를 호출해 릴리즈 하지 않으면 안 된다.

개별적으로 생성 하는 각각의 표면은, 명시적으로 릴리즈 할 필요가 있다. 다만, 플립핑 체인과 같이,IDirectDraw7::CreateSurface 의 호출로 은근히 복수의 표면을 생성 했을 경우는, 그 프런트 버퍼를 릴리즈 하는 것만으로 좋다. 이 경우, 백 버퍼 표면을 가리키는 포인터는 은근히 릴리즈 되어 그 릴리즈 이후는 사용할 수 있지 않게 된다.

백 버퍼 표면을 은근히 릴리즈 했을 경우, 체인내외의 표면의 참조 카운트는 변경되지 않는다.

[Visual Basic]

필요가 없어진 표면은, Nothing 로 설정하는 것에 의해 릴리즈 해야 한다.

개별적으로 생성 하는 각각의 표면은, 명시적으로 릴리즈 할 필요가 있다. 다만, 플립핑 체인과 같이,IDirectDraw7::CreateSurface 의 호출로 은근히 복수의 표면을 생성 했을 경우는, 그 프런트 버퍼를 릴리즈 하는 것만으로 좋다. 이 경우, 백 버퍼 표면은 은근히 릴리즈 되어 이후 사용할 수 있지 않게 된다.


표면의 열거

[C++]

IDirectDraw7::EnumSurfaces 메소드를 호출하는 것으로, DirectDraw 는 다양한 방법으로 표면을 열거할 수 있다. EnumSurfaces 메소드에 의해, 제공된 표면의 기술에 적합 또는 부적당합인 표면을 검색할 수가 있다. DirectDraw 는, 각각의 열거된 표면에 대해서 호출하는 EnumSurfacesCallback 를 호출한다.

검색에는 2 개의 일반적인 방법이 있다. DirectDraw 오브젝트가 이미 생성 하고 있는 표면을 검색하는 방법, 및 DirectDraw 오브젝트가 그 때 (표면의 기술과 이용 가능한 메모리를 줄 때)에 생성 할 수 있는 표면을 검색하는 방법이다. 메소드의 dwFlags 파라미터의 편성 플래그에 의해, 검색 타입을 지정할 수 있다.

기존 표면의 열거 이것은 열거의 가장 일반적인 타입이다. dwFlags 파라미터로, DDENUMSURFACES_DOESEXIST 검색 타입 플래그와 편성 플래그의 1 개 (DDENUMSURFACES_MATCH, DDENUMSURFACES_NOMATCH, 또는 DDENUMSURFACES_ALL) 의 편성을 지정하는 EnumSurfaces 를 호출하면, 기존 표면을 열거할 수 있다. 기존 표면을 모두 열거하고 있는 경우,lpDDSD 파라미터를 NULL 로 설정할 수 있다. 또는, 그 파라미터를 검색하는 표면을 기술하기 위해서 초기화된 DDSURFACEDESC2 구조체의 주소에도 설정할 수 있다. 3 번째의 파라미터 (lpContext)는, 4 번째의 파라미터 (lpEnumSurfacesCallback)로 지정하는 열거 함수에 건네주는 주소로 설정한다.

다음의 코드에서는, 이 호출이 DirectDraw 오브젝트의 기존 표면을 모두 열거하는 경우를 설명한다.

HRESULT ddrval;
  ddrval = lpDD->EnumSurfaces(DDENUMSURFACES_DOESEXIST |
                              DDENUMSURFACES_ALL, NULL, NULL,
                              EnumCallback);
  if (FAILED(ddrval))
      return FALSE;

특정의 기술에 적합하는 기존 표면을 검색하는 경우, DirectDraw 에서는 제공된 표면을 기술하는 각각의 멤버와 기존 표면의 각각의 멤버를 비교해 적합을 결정한다. 완전하게 적합한 것만이 열거된다. DirectDraw 에서는, 열거된 표면의 참조 카운트를 인크리먼트(increment) 하므로, 참조 카운트를 사용하지 않는 경우 (또는, 처리하는 경우)는, 표면의 릴리즈를 확인하는 것.

이용 가능한 표면의 열거 이 타입의 열거는, 기존 표면의 열거보다 일반적이지 않다. 그러나, 표면을 생성 하려고 하기 전에 지원 되는 경우의 결정에는 유용하다. 이 검색을 실행하려면 ,IDirectDraw7::EnumSurfaces 을 호출하면나무에, DDENUMSURFACES_CANBECREATED 와 DDENUMSURFACES_MATCH 플래그를 조합한다 (다른 플래그의 편성에서는 무효가 된다). 호출해에 사용하는 DDSURFACEDESC2 구조체는, DirectDraw 로 사용하는 표면 특성의 정보를 포함하기 위해서(때문에) 초기화하지 않으면 안 된다.

특별한 픽셀 포맷을 사용하는 표면을 열거하려면 ,DDSURFACEDESC2 구조체의 dwFlags 멤버에 DDSD_PIXELFORMAT 플래그를 포함한다. 게다가 표면을 기술하는 DDPIXELFORMAT 구조체를 초기화해, 그 dwFlags 멤버가 요구되는 픽셀 포맷 플래그 (DDPF_RGB, DDPF_YUV, 또는 양쪽 모두)를 포함하기 위해서(때문에) 설정한다. 다른 픽셀 포맷값은 설정 하지 않아도 되다.

DDSURFACEDESC2 구조체에 DDSD_HEIGHT 플래그와 DDSD_WIDTH 플래그를 포함한 경우,dwHeight 와 dwWidth 멤버로 요구되는 넓이를 지정할 수 있다. 이러한 플래그를 포함하지 않는 경우는, DirectDraw 가 프라이머리 표면의 넓이를 사용한다.

다음의 코드에서는, 이 호출이 96 × 96 의 RGB 나 YUV 표면에 대한 유효한 표면 특성의 모든 것을 열거하는 경우를 설명한다.

    DDSURFACEDESC2 ddsd;
    HRESULT        ddrval;
    ZeroMemory(&ddsd, sizeof(ddsd));

    ddsd.dwSize  = sizeof(ddsd);
    ddsd.dwFlags = DDSD_CAPS | DDSD_PIXELFORMAT |
                   DDSD_HEIGHT | DDSD_WIDTH;
    ddsd.ddpfPixelFormat.dwFlags = DDPF_YUV | DDPF_RGB;
    ddsd.dwHeight = 96;
    ddsd.dwWidth  = 96;

    ddrval = lpDD->EnumSurfaces(
                     DDENUMSURFACES_CANBECREATED | DDENUMSURFACES_MATCH,
                     &ddsd, NULL, EnumCallback);
    if (ddrval ! = DD_OK)
        return FALSE;

DirectDraw 가 이용 가능한 표면을 열거하는 경우, 실제로는, 요구된 특성을 가지는 일시적인 표면을 생성 하려고 한다. 그 생성이 성공하면(자), 다음에 DirectDraw 는 작용되는 특성인 만큼 제공되는 EnumSurfacesCallback 함수를 호출한다. 즉, 일시적인 표면에의 포인터에는, 콜백 함수를 제공하지 않는다. 표면이 열거되지 않는 경우에, 표면이 지원되어 있지 않으면 가정할 것은 없다. DirectDraw 가 일시적인 표면을 생성 하려고 해, 호출하면나무에의 메모리 제약을 위해서(때문에) 실패한 가능성도 있다. 이 때문에, 드라이버가 실제로 표면을 지원 하고 있어도, 이러한 특성이 열거되지 않는 것이다.

[Visual Basic]

DirectDraw7.GetSurfacesEnum 메소드를 호출하는 것으로, DirectDraw 는 다양한 방법으로 표면을 열거할 수 있다. GetSurfacesEnum 메소드에 의해, 제공된 표면의 기술에 적합 또는 부적당합인 표면을 검색할 수가 있다. 이 메소드는, 각각의 표면 기술을 조회하는 DirectDrawEnumSurfaces 오브젝트를 생성 한다.

검색에는 2 개의 일반적인 방법이 있다. DirectDraw 오브젝트가 이미 생성 하고 있는 표면을 검색하는 방법, 및 DirectDraw 오브젝트가 그 때 (표면의 기술과 이용 가능한 메모리를 줄 때)에 생성 할 수 있는 표면을 검색하는 방법이다. 메소드의 flags 파라미터의 편성 플래그에 의해, 검색 타입을 지정할 수 있다.

기존 표면의 열거 이것은 열거의 가장 일반적인 타입이다. flags 파라미터로, DDENUMSURFACES_DOESEXIST 검색 타입 플래그와 편성 플래그의 1 개 (DDENUMSURFACES_MATCH, DDENUMSURFACES_NOMATCH, 또는 DDENUMSURFACES_ALL) 의 편성을 지정하는 GetSurfacesEnum 를 호출하면, 기존 표면을 열거할 수 있다. 기존 표면을 모두 열거하고 있는 경우,desc 파라미터를 Nothing 로 설정할 수 있다. 또는, 그 파라미터를 검색하는 표면을 기술하기 위해서 초기화된 DDSURFACEDESC2 형의 주소에도 설정할 수 있다.

다음의 코드에서는, 이 호출이 DirectDraw 오브젝트의 기존 표면을 모두 열거하는 경우를 설명한다. 여기에서는, dd 가 유효한 DirectDraw7 오브젝트, ddEnumSurfaces 이 유효한 DirectDrawEnumSurfaces 오브젝트로 한다.

Set ddEnumSurfaces = dd.GetSurfacesEnum(DDENUMSURFACES_DOESEXIST Or _
DDENUMSURFACES_ALL, ddsd2)

특정의 기술에 적합하는 기존 표면을 검색하는 경우, DirectDraw 에서는 제공된 표면을 기술하는 각각의 멤버와 기존 표면의 각각의 멤버를 비교해 적합을 결정한다. 완전하게 적합한 것만이 DirectDrawEnumSurfaces 오브젝트에 파묻힌다.

이용 가능한 표면의 열거 이 타입의 열거는, 기존 표면의 열거보다 일반적이지 않다. 그러나, 표면을 생성 하려고 하기 전에 지원 되는 경우의 결정에는 유용하다. 이 검색을 실행하려면 ,DirectDraw7.GetSurfacesEnum 를 호출하면나무에, DDENUMSURFACES_CANBECREATED 와 DDENUMSURFACES_MATCH 플래그를 조합한다 (다른 플래그의 편성에서는 무효가 된다). 호출해에 사용하는 DDSURFACEDESC2 형은, DirectDraw 로 사용하는 표면 특성의 정보를 포함하기 위해서(때문에) 초기화하지 않으면 안 된다.

특별한 픽셀 포맷을 사용하는 표면을 열거하려면 ,DDSURFACEDESC2 형의 lFlags 멤버에 DDSD_PIXELFORMAT 플래그를 포함한다. 게다가 표면을 기술하는 DDPIXELFORMAT 형을 초기화해, 그 lFlags 멤버가 요구되는 픽셀 포맷 플래그 (DDPF_RGB, DDPF_YUV, 또는 양쪽 모두)를 포함하기 위해서(때문에) 설정한다. 다른 픽셀 포맷값은 설정 하지 않아도 되다.

DDSURFACEDESC2 형에 DDSD_HEIGHT 플래그와 DDSD_WIDTH 플래그를 포함한 경우,lHeight 와 lWidth 멤버로 요구되는 넓이를 지정할 수 있다. 이러한 플래그를 포함하지 않는 경우는, DirectDraw 가 프라이머리 표면의 넓이를 사용한다.

다음의 코드에서는, 이 호출이 96 × 96 의 RGB 나 YUV 표면에 대한 유효한 표면 특성의 모든 것을 열거하는 경우를 설명한다.

Dim ddsd As DDSURFACEDESC2

ddsd.lFlags = DDSD_CAPS Or DDSD_PIXELFORMAT Or
DDSD_HEIGHT Or DDSD_WIDTH
ddsd.ddpfPixelFormat.lFlags = DDPF_YUV Or DDPF_RGB
ddsd.lHeight = 96
ddsd.lWidth  = 96

Set ddEnumSurfaces = dd.GetSurfacesEnum(DDENUMSURFACES_CANBECREATED Or _
DDENUMSURFACES_MATCH, ddsd)

DirectDraw 가 이용 가능한 표면을 열거하는 경우, 실제로는, 요구된 특성을 가지는 일시적인 표면을 생성 하려고 한다. 그 생성이 성공하면(자), 다음에 DirectDraw 는 DirectDrawEnumSurfaces 오브젝트에 작용되는 특성만을 묻는다. 표면이 열거되지 않는 경우에, 표면이 지원되어 있지 않으면 가정할 것은 없다. DirectDraw 가 일시적인 표면을 생성 하려고 해, 호출하면나무에의 메모리 제약을 위해서(때문에) 실패한 가능성도 있다. 이 때문에, 드라이버가 실제로 표면을 지원 하고 있어도, 이러한 특성이 열거되지 않는 것이다.


표면 특성의 갱신

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

기존 표면의 특성을 갱신하려면 ,IDirectDrawSurface7::SetSurfaceDesc 메소드를 사용한다. 이 메소드를 사용하면(자), DirectDrawSurface 오브젝트의 표면 메모리의 픽셀 포맷이나 위치를, 어플리케이션이 명시적으로 할당한 시스템 메모리로 변경할 수 있다. 이 기능에 의해, 표면은 카피하지 않고 , 이전에 할당한 버퍼의 데이터를 사용할 수 있게 된다. 새로운 표면 메모리는 클라이언트 어플리케이션으로 할당할 수 있다. 이 경우, 클라이언트 어플리케이션으로 그 할당을 삭제하지 않으면 안 된다.

IDirectDrawSurface7::SetSurfaceDesc 메소드를 호출하는 경우,lpddsd 파라미터는, 새로운 표면 메모리와 그 메모리에의 포인터를 기술하는 DDSURFACEDESC2 구조체의 주소로 하지 않으면 안 된다. 이 구조체 중(안)에서는, 표면 메모리, 넓이,피치, 및 픽셀 포맷의 위치의 유효 멤버를 반영하는 dwFlags 멤버를 설정 가능한 한이다. 따라서,dwFlags 에는, 유효한 구조체 멤버를 나타내기 위해서(때문에) 설정하는 DDSD_WIDTH, DDSD_HEIGHT, DDSD_PITCH, DDSD_LPSURFACE, 및 DDSD_PIXELFORMAT 플래그의 편성 밖에 가질 수 없다.

구조체에 값을 설정하기 전에, 표면을 보관 유지하기 위한 메모리를 할당하지 않으면 안 된다. 이 때, 할당하는 메모리의 사이즈가 중요해진다. 표면의폭이나 높이를 적응하기 위한 충분한 메모리를 할당할 뿐만 아니라,QWORD (8 바이트)의 배수인 표면 피치의 장소를 잡기 위해서(때문에)도 충분한 것이 아니면 안된다. 피치는 픽셀 단위는 아니고 바이트 단위인 것을 생각해 내는 것.

구조체에 표면의 값을 설정하는 경우,lpSurface 멤버는 할당하는 메모리에의 포인터이며,dwHeight 및 dwWidth 멤버에는, 표면의 넓이를 픽셀 단위로 기술한다. 표면의 넓이를 지정 하면나무는, 표면 피치도 반영시키기 위해서(때문에) lPitch 멤버를 묻지 않으면 안 된다. 피치는 QWORD 의 배수가 아니면 안 된다. 같이 피치를 지정 하면나무는, 폭의 값도 지정할 필요가 있다. 마지막으로,ddpfPixelFormat 멤버는, 표면의 픽셀 포맷을 기술한다. lpSurface 멤버 이외로 이러한 멤버에 값을 지정하지 않으면 메소드는 현재의 표면으로부터 사용하고 있는 값을 디폴트로서 사용한다.

IDirectDrawSurface7::SetSurfaceDesc 를 사용할 때에, 주의해야 할 제한이 있다. 그 제한의 몇개인가는 상식적인 것이다. 예를 들어,DDSURFACEDESC2 구조체의 lpSurface 멤버는, 시스템 메모리에의 유효한 포인터가 아니면 안 된다 (현시점에서는, 메소드는 비디오 메모리 포인터를 지원 하고 있지 않다). 또,dwWidth 및 dwHeight 멤버는, 제로가 아닌 값이 아니면 안 된다. 마지막으로, 프라이머리 표면이나 최초의 플립핑 체인의 표면을 재할인 맞히고 할 수 없다.

복수의 DirectDrawSurface 오브젝트에 동일 메모리를 설정할 수 있다. 그러나, 표면 오브젝트를 메모리에 할당할 수 있고 있는 동안에, 그 메모리의 할당을 삭제하지 않게 주의할 필요가 있다.

SetSurfaceDesc 메소드를 올바르게 사용하지 않다고 예측 불가능한 결과를 일으키는 경우가 있다. DirectDrawSurface 오브젝트에서는, 이 오브젝트로 할당하지 않은 표면 메모리의 할당은 삭제하지 않는다. 따라서, 표면 메모리가 필요하지 않게 되었을 경우, 프로그래머가 할당을 삭제한다. 다만,SetSurfaceDesc 가 불려 갔을 경우, DirectDraw 는 표면의 생성시에 은근히 할당한 원의 표면 메모리를 릴리즈 한다.


표면 메모리에의 직접 액세스

[C++]

frame buffer 또는 오프 스크린 표면 메모리에 직접 액세스 하려면 ,IDirectDrawSurface7::Lock 메소드를 사용한다. 이 메소드를 호출하는 경우,lpDestRect 파라미터는, 직접 액세스 하려고 하는 표면 위에의 직사각형을 기술하는 RECT 구조체에의 포인터로 한다. 표면 전체를 잠그려면 ,lpDestRect 를 NULL 로 설정한다. 또, 표면의 일부만을 커버하는 RECT 를 지정할 수도 있다. 2 개의 직사각형이 겹치지 않으면, 2 개의 thread 또는 2 개의 프로세스는, 표면의 복수의 직사각형을 동시에 잠글 수가 있다.

Lock 메소드에서는, 표면 메모리에 올바르고 액세스 하기 위해서 필요한 모든 정보를,DDSURFACEDESC2 구조체에 묻는다. 이 구조체에는,피치 (또는 보폭) 및 표면의 픽셀 포맷 (프라이머리 표면 의 픽셀 포맷과 다른 경우)에 관한 정보가 포함되어 있다. 표면 메모리에의 액세스가 종료 하면,IDirectDrawSurface7::Unlock 메소드를 호출해, 락을 해제한다.

표면을 잠그고 있는 동안, 그 컨텐츠를 직접 조작할 수가 있다. 표면 메모리를 직접 렌더링 하면나무의 일반적인 문제를 피하기 위한 힌트를, 이하의 리스트로 가리킨다.

  • 일정한 디스플레이 피치를 가정하지 않는다. 항상,IDirectDrawSurface4::Lock 메소드가 돌려주는 피치 정보를 조사하는 것. 이 피치는, 표면 메모리의 위치, 디스플레이 카드의 타입, 혹은 DirectDraw 드라이버의 버젼이라고 한 다양한 이유에 의해 변화한다. 상세한 것에 대하여는, 「폭과 피치」를 참조할것.
  • 락이 해제된 표면에의 블리트를 확인한다. 락 된 표면으로 DirectDraw 블리트 메소드를 호출하면, 실패해 DDERR_SURFACEBUSY 또는 DDERR_LOCKEDSURFACES 를 돌려준다. 같이 디스플레이 메모리에 존재하는 락 된 표면으로 GDI 블리트 함수를 호출하면, 에러값을 돌려주지 않고 실패한다.
  • 표면이 락 되고 있는 동안, 어플리케이션의 액티버티는 제한된다. 표면이 락 되고 있는 동안, DirectDraw 가 Win16Mutex (Win16Lock 라고도 한다)를 보관 유지하고 있는 경우가 있으므로, 안전하게 표면 메모리에 액세스 할 수 있다. Win16Mutex 는,IDirectDrawSurface7::Lock 와 IDirectDrawSurface7::Unlock 의 호출동안에 Windows 를 슛다운 해, GDI 및 USER 동적 링크 라이브러리에의 액세스를 순서대로화한다. IDirectDrawSurface7::GetDC 메소드는 은근히 Lock 를 호출해,IDirectDrawSurface7::ReleaseDC 메소드는 은근히 Unlock 를 호출한다.
  • 디스플레이 메모리에 대해서 연속하는 데이터를 항상 카피한다 (Windows 95 및 Windows 98 에서는 페이지 폴트 핸들러 Vflatd. 386 을 사용해, 반크스잇치메모리를 사용한 디스플레이 카드에 대한 가상 플랫 frame buffer를 이행 한다. 이 핸들러에 의해, 이러한 디스플레이 디바이스는 DirectDraw 에 연속한 frame buffer를 건네줄 수가 있다. 디스플레이 메모리에 대해서 불연속의 데이터를 카피 하면, 카피가 메모리 뱅크에 스팬 하는 경우에, 시스템이 일시정지를 일으킬 가능성이 있다).

Lock 메소드의 호출시에 DDLOCK_NOSYSLOCK 플래그를 포함하지 않는 이상 보통은 표면을 잠그면(자), DirectDraw 는 Win16Mutex 를 취득하게 된다. Win16Mutex 의 사이, Windows 를 포함한 모든 어플리케이션은 실행을 중지한다. Win16Mutex 가 어플리케이션의 실행을 정지하므로, 락중은 표준 디버거를 사용할 수 없다. 다만, 커널 디버거는 이전도 사용할 수가 있다. DirectDraw 에서는, 프라이머리 표면을 잠글 때는 항상 Win16Mutex 를 취득한다.

IDirectDrawSurface7::Lock 를 호출했을 때에 블리트중이면, 락을 취득할 수 없기 때문에, 이 메소드는 즉시 에러를 돌려준다. 이 에러를 회피하려면 , 락이 성공해 취득될 때까지 메소드를 기다리게 하는 DDLOCK_WAIT 플래그를 사용한다.

프라이머리 표면의 부분 락은, 소프트웨어 커서의 표시와 충돌한다. 커서가 락 된 직사각형을 횡단하는 경우, 커서는 락의 계속 시간의 사이 숨겨진다. 커서가 직사각형을 횡단하지 않는 경우, 락의 계속 시간의 사이 굳어진다. 표면 전체가 락 되고 있으면(자), 이러한 이펙트의 어느쪽이나 발생하지 않는다.

[Visual Basic]

frame buffer 또는 오프 스크린 표면 메모리에 직접 액세스 하려면 ,DirectDrawSurface7.Lock 메소드를 사용한다. 이 메소드를 호출하는 경우,r 파라미터는, 직접 액세스 하려고 하는 표면 위에의 직사각형을 기술하는 RECT 형으로 한다. 표면 전체를 잠그려면 , 하늘의 RECT 를 건네준다. 또, 표면의 일부만을 커버하는 RECT 를 지정할 수도 있다.

Lock 메소드에서는, 표면 메모리에 올바르고 액세스 하기 위해서 필요한 모든 정보를,DDSURFACEDESC2 형에 묻는다. 이 형태에는,피치 (또는 보폭) 및 표면의 픽셀 포맷 (프라이머리 표면 의 픽셀 포맷과 다른 경우)에 관한 정보가 포함되어 있다. 표면 메모리에의 액세스가 종료 하면,DirectDrawSurface7.Unlock 메소드를 호출해, 락을 해제한다.

표면을 잠그고 있는 동안, 그 컨텐츠를 직접 조작할 수가 있다. 표면 메모리를 직접 렌더링 하면나무의 일반적인 문제를 피하기 위한 힌트를, 이하의 리스트로 가리킨다.

  • 일정한 디스플레이 피치를 가정하지 않는다. 항상,DirectDrawSurface7.Lock 메소드가 돌려주는 피치 정보를 조사하는 것. 이 피치는, 표면 메모리의 위치, 디스플레이 카드의 타입, 혹은 DirectDraw 드라이버의 버젼이라고 한 다양한 이유에 의해 변화한다. 상세한 것에 대하여는, 「폭과 피치」를 참조할것.
  • 락이 해제된 표면에의 블리트를 확인한다. 락 된 표면으로 DirectDraw 블리트 메소드를 호출하면, 실패해 DDERR_SURFACEBUSY 또는 DDERR_LOCKEDSURFACES 를 돌려준다. 같이 디스플레이 메모리에 존재하는 락 된 표면으로 GDI 블리트 함수를 호출하면, 에러값을 돌려주지 않고 실패한다.
  • 표면이 락 되고 있는 동안, 어플리케이션의 액티버티는 제한된다. 표면이 락 되고 있는 동안, DirectDraw 가 Win16Mutex (Win16Lock 라고도 한다)를 보관 유지하고 있는 경우가 있으므로, 안전하게 표면 메모리에 액세스 할 수 있다. Win16Mutex 는,DirectDrawSurface7.Lock 와 DirectDrawSurface7.Unlock 의 호출동안에 Windows 를 슛다운 해, GDI 및 USER 동적 링크 라이브러리에의 액세스를 순서대로화한다. DirectDrawSurface7.GetDC 메소드는 은근히 Lock 를 호출해,DirectDrawSurface7.ReleaseDC 메소드는 은근히 Unlock 를 호출한다.
  • 디스플레이 메모리에 대해서 연속하는 데이터를 항상 카피한다 (Windows 95 및 Windows 98 에서는 페이지 폴트 핸들러 Vflatd. 386 을 사용해, 반크스잇치메모리를 사용한 디스플레이 카드에 대한 가상 플랫 frame buffer를 이행 한다. 이 핸들러에 의해, 이러한 디스플레이 디바이스는 DirectDraw 에 연속한 frame buffer를 건네줄 수가 있다. 디스플레이 메모리에 대해서 불연속의 데이터를 카피 하면, 카피가 메모리 뱅크에 스팬 하는 경우에, 시스템이 일시정지를 일으킬 가능성이 있다).

Lock 메소드의 호출시에 DDLOCK_NOSYSLOCK 플래그를 포함하지 않는 이상 보통은 표면을 잠그면(자), DirectDraw 는 Win16Mutex 를 취득하게 된다. Win16Mutex 의 사이, Windows 를 포함한 모든 어플리케이션은 실행을 중지한다. Win16Mutex 가 어플리케이션의 실행을 정지하므로, 락중은 표준 디버거를 사용할 수 없다. 다만, 커널 디버거는 이전도 사용할 수가 있다. DirectDraw 에서는, 프라이머리 표면을 잠글 때는 항상 Win16Mutex 를 취득한다.

DirectDrawSurface7.Lock 를 호출했을 때에 블리트중이면, 락을 취득할 수 없기 때문에, 이 메소드는 즉시 에러를 돌려준다. 이 에러를 회피하려면 , 락이 성공해 취득될 때까지 메소드를 기다리게 하는 DDLOCK_WAIT 플래그를 사용한다.

프라이머리 표면의 부분 락은, 소프트웨어 커서의 표시와 충돌한다. 커서가 락 된 직사각형을 횡단하는 경우, 커서는 락의 계속 시간의 사이 숨겨진다. 커서가 직사각형을 횡단하지 않는 경우, 락의 계속 시간의 사이 굳어진다. 표면 전체가 락 되고 있으면(자), 이러한 이펙트의 어느쪽이나 발생하지 않는다.


감마 컨트롤과 컬러 컨트롤

여기에서는, DirectDrawSurface 오브젝트로 사용되는 감마 컨트롤과 컬러 컨트롤 인터페이스에 대해 설명한다. 이하의 항목에 대해 기술한다.

  • 감마 컨트롤과 컬러 컨트롤이란?
  • 감마 컨트롤의 사용
  • 컬러 컨트롤의 사용
[C++]

주 ： 단일의 표면으로 IDirectDrawGammaControl 과 IDirectDrawColorControl 인터페이스의 양쪽 모두를 사용해서는 안 된다. 동시에 사용해 버리면(자), 이러한 이펙트 를 얻을 수 없게 된다.

[Visual Basic]

주 ： 단일의 표면으로 DirectDrawGammaControl 과 DirectDrawColorControl 인터페이스의 양쪽 모두를 사용해서는 안 된다. 동시에 사용해 버리면(자), 이러한 이펙트 를 얻을 수 없게 된다.


감마 컨트롤과 컬러 컨트롤이란?

[C++]

감마 컨트롤과 컬러 컨트롤로부터, 표면 자체의 컨텐츠에 영향을 주는 일 없이, DirectDrawSurface 오브젝트로 시스템이 표면의 컨텐츠를 표시하는 방법을 변경할 수 있다. 이러한 컨트롤은, DirectDraw 가 스크린상에서 렌더링 되기 전에 표면을 남기는 것과 같이, 데이터에 적용하는 매우 단순한 필터라고 생각된다. 표면 오브젝트는, 표면의 컨텐츠가 필터 되는 것을 조절하기 위해서 메소드를 공개하는 IDirectDrawGammaControl , 및 IDirectDrawColorControl 인터페이스를 실현한다. 어느 쪽인가의 인터페이스에의 포인터를 취득하려면 ,IID_IDirectDrawGammaControl, 혹은 IID_IDirectDrawColorContro 참조 식별자를 지정하는 타겟 인터페이스의 IUnknown::QueryInterface 메소드를 사용한다.

IDirectDrawGammaControl 인터페이스에 의해 나타내진 감마 컨트롤은, 시스템이 표시하는 실제의 레벨에 표면 특유의 적, 초록, 및 파랑의 레벨 맵을 동적으로 변경할 수 있다. 감마 레벨을 설정하는 것으로, 이펙트를 붙이는 frame buffer에 새로운 이미지를 블리트 하지 않고 , 유저의 스크린에 플래시 컬러 (유저의 특징을 낼 때의 빨강, 새로운 항목을 취득 하면나무의 초록등)를 적용할 수 있다. 혹은, 컬러 레벨을 조절해, frame buffer의 이미지에 컬러 바이어스를 적용할 수 있다. 이 인터페이스는 컬러 컨트롤 인터페이스와 닮아 있지만, 매우 사용하기 쉽기 때문에, 게임 어플리케이션으로 선택 하면이야 있고. 상세한 것에 대하여는, 「감마 컨트롤의 사용」을 참조할것.

IDirectDrawColorControl 인터페이스에 의해, 텔레비젼으로 볼 수 있는 컬러 컨트롤과 같은 표면의 색을 제어할 수 있다. IDirectDrawColorControl 와 텔레비젼 위에의 실제의 제어간에 있어서의 유사는 실수는 아니다. 즉, 이 인터페이스는, 브로드캐스트 비디오를 오버레이 표면내에서 보기 위해서(때문에) 조절하려면 매우 적합하기 (위해)때문에, 색이상으로 유사한 컨트롤을 제공하지 않으면 안 되는 것을 의미한다. 컬러 컨트롤을 사용 하면, 유저는 색상, 포화, 콘트라스트등의 비디오 특성을 변경할 수 있다. 상세한 것에 대하여는, 「컬러 컨트롤의 사용」을 참조할것.

[Visual Basic]

감마 컨트롤과 컬러 컨트롤로부터, 표면 자체의 컨텐츠에 영향을 주는 일 없이, DirectDrawSurface 오브젝트로 시스템이 표면의 컨텐츠를 표시하는 방법을 변경할 수 있다. 이러한 컨트롤은, DirectDraw 가 스크린상에서 렌더링 되기 전에 표면을 남기는 것과 같이, 데이터에 적용하는 매우 단순한 필터라고 생각된다. DirectDrawGammaControl 및 DirectDrawColorControl 오브젝트는, 표면의 컨텐츠가 필터 되는 것을 조절하기 위한 메소드를 제공한다. 이러한 오브젝트는, 타겟 표면의 DirectDrawSurface7.GetDirectDrawColorControl 및 DirectDrawSurface7.GetDirectDrawGammaControl 메소드를 사용해 생성 할 수 있다.

DirectDrawGammaControl 클래스에 의해 나타내진 감마 컨트롤은, 시스템이 표시하는 실제의 레벨에 표면 특유의 적, 초록, 및 파랑의 레벨 맵을 동적으로 변경할 수 있다. 감마 레벨을 설정하는 것으로, 이펙트를 붙이는 frame buffer에 새로운 이미지를 블리트 하지 않고 , 유저의 스크린에 플래시 컬러 (유저의 특징을 낼 때의 빨강, 새로운 항목을 취득 하면나무의 초록등)를 적용할 수 있다. 혹은, 컬러 레벨을 조절해, frame buffer의 이미지에 컬러 바이어스를 적용할 수 있다. 이 인터페이스는 컬러 컨트롤 인터페이스와 닮아 있지만, 매우 사용하기 쉽기 때문에, 게임 어플리케이션으로 선택 하면이야 있고. 상세한 것에 대하여는, 「감마 컨트롤의 사용」을 참조할것.

DirectDrawColorControl 인터페이스에 의해, 텔레비젼으로 볼 수 있는 컬러 컨트롤과 같은 표면의 색을 제어할 수 있다. DirectDrawColorControl 와 텔레비젼 위에의 실제의 제어간에 있어서의 유사는 실수는 아니다. 즉, 이 인터페이스는, TV 로 방영된 비디오를 오버레이 표면내에서 보기 위해서(때문에) 조정하려면 매우 적합하기 (위해)때문에, 색이상으로 유사한 컨트롤을 제공하지 않으면 안 되는 것을 의미한다. 컬러 컨트롤을 사용 하면, 유저는 색상, 포화, 콘트라스트등의 비디오 특성을 변경할 수 있다. 상세한 것에 대하여는, 「컬러 컨트롤의 사용」을 참조할것.


감마 컨트롤의 사용

[C++]

IID_IDirectDrawGammaControl 참조 식별자로 표면을 조회하는 것으로써 취득하는 IDirectDrawGammaControl 인터페이스에서는, 디스플레이에 대한 디지털-아날로그 컨버터 (DAC)에 픽셀이 보내지기 전에, 표면으로부터 픽셀의 적, 초록, 및 파랑의 색성분에 영향을 주는 램프 레벨을 조작할 수 있다. 모든 표면 타입에서는 IDirectDrawGammaControl 인터페이스를 지원 하지만, 프라이머리 표면 위에의 감마를 조절 가능한 한이다. 프라이머리 표면 이외의 표면 위에의 IDirectDrawGammaControl::GetGammaRamp 또는 IDirectDrawGammaControl::SetGammaRamp 를 호출하려고 하면 실패한다.

여기에서는, 램프 레벨의 일반적인 개념과IDirectDrawGammaControl 의 메소드로부터 이러한 레벨과 함께 작용하는 정보에 대해 설명한다. 이하의 항목에 대해 기술한다.

[Visual Basic]

DirectDrawSurface7.GetDirectDrawGammaControl 를 호출하는 것에 의해 취득하는 DirectDrawGammaControl 오브젝트에서는, 디스플레이에 대한 디지털-아날로그 컨버터 (DAC)에 픽셀이 보내지기 전에, 표면으로부터 픽셀의 적, 초록, 및 파랑의 색성분에 영향을 주는 램프 레벨을 조작할 수 있다. 모든 표면 타입에서는 DirectDrawGammaControl 오브젝트를 지원 하지만, 프라이머리 표면 위에의 감마를 조절 가능한 한이다. 프라이머리 표면 이외의 표면 위에의 DirectDrawGammaControl.GetGammaRamp 또는 DirectDrawGammaControl.SetGammaRamp 를 호출하려고 하면 실패한다.

여기에서는, 램프 레벨의 일반적인 개념과DirectDrawGammaControl 의 메소드로부터 이러한 레벨과 함께 작용하는 정보에 대해 설명한다. 이하의 항목에 대해 기술한다.

  • 감마 램프 레벨에 대해
  • 감마 램프 지원의 검출
  • 감마 램프 레벨의 설정과 취득


컬러 컨트롤의 사용

[C++]

IDirectDrawColorControl 인터페이스로부터, 표면의 컬러 컨트롤을 설정해 취득할 수 있다. 이 인터페이스는,IID_IDirectDrawColorControl 참조 식별자를 사용해 DirectDrawSurface 오브젝트를 조회하는 것으로써 검색할 수 있다.

컬러 컨트롤의 정보는 DDCOLORCONTROL 구조체로 나타내진다. 이 구조체는, 그 인터페이스의 2 개의 메소드 (IDirectDrawColorControl::SetColorControls 및 IDirectDrawColorControl::GetColorControls )와 함께 사용된다. 최초의 구조체 멤버 (dwSize)는, 그것을 사용하기 전에 구조체의 사이즈를 바이트 단위로 설정하지 않으면 안 된다. 다음의 멤버 (dwFlags)를 사용하려면 , 컬러 컨트롤을 설정 또는 취득하고 있을지 어떨지에 의한다. 새로운 컬러 컨트롤을 설정해 있는 경우,dwFlags 를 해당하는 플래그의 조합해로 설정해, 설정한 유효 데이터를 포함한 다른 구조체 멤버의 어떤 것인지를 나타낸다. 다만, 컬러 컨트롤을 취득하고 있는 경우는, 그것을 사용하기 전에 dwFlags 를 설정 하지 않아도 되다. 이 멤버에는,IDirectDrawColorControl::GetColorControls 메소드가 돌아온 후에, 어느 멤버가 유효가 될까를 전하는 플래그를 포함하기 때문이다.

나머지의 DDCOLORCONTROL 구조체 멤버에는, 휘도(Luminance), 콘트라스트, 색상, 포화, 선명도, 감마, 및 사용하는 색인가 어떤가를 기술하는 값이 포함된다. 이 구조체에는, 감마 수정에 대한 정보가 있는 것에 주의한다. 이것은 상대적인 휘도(Luminance)에 영향을 주는 단일의 감마값이며,IDirectDrawGammaControl 인터페이스로부터 제공되는 감마 조절 기능과 구별하는 것.

[Visual Basic]

DirectDrawColorControl 오브젝트로부터, 표면의 컬러 컨트롤을 설정해 취득할 수 있다. 이 오브젝트는,DirectDrawSurface7.GetDirectDrawColorControl 를 호출하는 것으로 취득할 수 있다.

컬러 컨트롤의 정보는,DDCOLORCONTROL 형으로 나타내진다. 이 형태는, 그 오브젝트의 2 개의 메소드 (DirectDrawColorControl.SetColorControls 및 DirectDrawColorControl.GetColorControls )와 함께 사용된다.

나머지의 DDCOLORCONTROL 형 멤버에는, 휘도(Luminance), 콘트라스트, 색상, 포화, 선명도, 감마, 및 사용하는 색인가 어떤가를 기술하는 값이 포함된다. 이 형태에는, 감마 수정에 대한 정보가 있는 것에 주의한다. 이것은 상대적인 휘도(Luminance)에 영향을 주는 단일의 감마값이며,DirectDrawGammaControl 인터페이스로부터 제공되는 감마 조절 기능과 구별하는 것.


오버레이 표면

여기에서는, DirectDraw 오버레이 표면의 지원에 대해 설명한다. 다음의 항목에 대해 기술한다.

  • 오버레이 표면의 개요
  • 주요한 DDCAPS 멤버와 플래그
  • 전송원직사각형과 목적지 직사각형
  • 경계와 사이즈아라이먼트
  • 최소 및 최대 신축(스트레치) 계수
  • 오버레이 컬러 키
  • 오버레이 표면의 배치
  • 오버레이 표면의 생성
  • 오버레이 Z 오더
  • 플립핑 오버레이 표면
[C++]

오버레이 표면의 실현에 대해서는, 「튜토리얼 6:오버레이 표면의 사용」을 참조할것.

[C++, Visual Basic]


오버레이 표면의 개요

단지 오버레이로 불리는 오버레이 표면은, 하드웨어에 의해 지원 된 특수한 능력을 가지는 표면이다. 오버레이 표면은, 프라이머리 표면에 블리트 하거나 프라이머리 표면의 컨텐츠를 변경하지 않고 , 라이브 비디오나 녹화 비디오, 혹은 정지 비트 맵을 프라이머리 표면상에 표시하기 위해서 자주(잘) 사용된다. 오버레이 표면의 지원은, 하드웨어만으로 제공된다. DirectDraw 는, 디스플레이 디바이스 드라이버가 보고하는 임의의 능력을 지원 한다. DirectDraw 는, 오버레이 표면을 에뮬레이트 하지 않는다.

오버레이 표면은, 드로잉(Drawing) 하거나 모니터의 전에 배치하는 투명한 플라스틱편을 닮아 있다. 오버레이가 모니터의 전에 있으면(자), 오버레이와 프라이머리 표면의 컨텐츠를 모두 볼 수가 있다. 오버레이를 삭제해도, 프라이머리 표면의 컨텐츠는 변함없다. 실제, 오버레이의 기구는, 투명한 플라스틱과 매우 자주(잘) 닮은 동작이다. 오버레이 표면을 표시 하면, 그것을 어디에 어떻게 표시할까를 디바이스 드라이버에게 전하고 있게 된다. 디스플레이 디바이스가 모니터에 주사선을 그리고 있는 동안, 프라이머리 표면의 각 픽셀의 위치를 조사해, 그 위치에서 오버레이를 표시해야할 것인가 제발을 조사한다. 표시 하면나무는, 디스플레이 디바이스가, 대응하는 픽셀을 오버레이 표면의 데이터로 옮겨놓는다. 다음에 이 그림을 나타낸다.

디스플레이 어댑터는 이 방법을 사용해, 모니터상에 프라이머리 표면과 오버레이의 합성화를 생성 해, 어느 쪽의 표면의 컨텐츠를 변경하는 일 없이, 투과성과 신축(스트레치) 이펙트를 제공한다. 합성된 표면은 비디오 스트림에 삽입되어 모니터에 직접 보내진다. 이 고속 처리와 픽셀 치환은 하드웨어 레벨로 처리되기 (위해)때문에, 오버레이를 표시할 경우에 현저한 퍼포먼스의 저하는 볼 수 없다. 게다가 이 방법은, 다른 피르세르포맛트가 있는 프라이머리 표면과 오버레이 표면을 연결고리 없게 합성할 수도 있다.

[C++]

오버레이 표면을 생성 하려면 , 관련지을 수 있었던 DDSCAPS2 구조체에 DDSCAPS_OVERLAY 플래그를 지정해,IDirectDraw7::CreateSurface 메소드를 호출한다. 오버레이 표면은 비디오 메모리인 만큼 생성 할 수가 있기 (위해)때문에, DDSCAPS_VIDEOMEMORY 플래그도 포함하지 않으면 안 된다. 다른 타입의 표면과 같이, 해당하는 플래그를 포함하는 것으로, 단일 오버레이 또는 복수의 오버레이 표면으로부터 되는 플립핑 체인을 생성 할 수가 있다.

[Visual Basic]

오버레이 표면을 생성 하려면 , 관련지을 수 있었던 DDSCAPS2 형에 DDSCAPS_OVERLAY 플래그를 지정해,DirectDraw7.CreateSurface 메소드를 호출한다. 오버레이 표면은 비디오 메모리인 만큼 생성 할 수가 있기 (위해)때문에, DDSCAPS_VIDEOMEMORY 플래그도 포함하지 않으면 안 된다. 다른 타입의 표면과 같이, 해당하는 플래그를 포함하는 것으로, 단일 오버레이 또는 복수의 오버레이 표면으로부터 되는 플립핑 체인을 생성 할 수가 있다.


주요한 DDCAPS 멤버와 플래그

[C++]

지원 된 오버레이 기능에 대한 정보를 취득하려면 ,IDirectDraw7::GetCaps 메소드를 호출한다. 이 메소드는, 모든 기능을 기술하고 있는 정보를 DDCAPS 구조체에 묻는다.

하드웨어 기능을 보고하는 경우, 디바이스 드라이버는 dwCaps 구조체의 멤버에 플래그를 설정해, 언제 주어진 타입의 제한이 하드웨어에 의해 강제당하는지를 나타낸다. 드라이버의 능력을 취득하고 나서, 어느 제한이 적용하는지를 dwCaps 멤버의 플래그로 조사한다. DDCAPS 구조체에는, 오버레이 표면에 대한 하드웨어 제한을 기술한 정보를 전달하는 9 개의 멤버가 있다. 이하의 겉(표)는, 오버레이에 관련한 멤버와 대응하는 플래그를 나타낸다.

멤버 | 플래그
dwMaxVisibleOverlays | 이 멤버는 항상 유효
dwCurrVisibleOverlays | 이 멤버는 항상 유효
dwAlignBoundarySrc | DDCAPS_ALIGNBOUNDARYSRC
dwAlignSizeSrc | DDCAPS_ALIGNSIZESRC
dwAlignBoundaryDest | DDCAPS_ALIGNBOUNDARYDEST
dwAlignSizeDest | DDCAPS_ALIGNSIZEDEST
dwAlignStrideAlign | DDCAPS_ALIGNSTRIDE
dwMinOverlayStretch | DDCAPS_OVERLAYSTRETCH
dwMaxOverlayStretch | DDCAPS_OVERLAYSTRETCH

dwMaxVisibleOverlays 및 dwCurrVisibleOverlays 멤버는, 하드웨어가 표시할 수 있는 오버레이의 최대수, 및 그 중에 현재 표시 상태에 있는 수에 대한 정보를 전달한다.

게다가 하드웨어는 dwAlignBoundarySrc,dwAlignSizeSrc,dwAlignBoundaryDest,dwAlignSizeDest, 및 dwAlignStrideAlign 멤버에 있는 직사각형의 위치나 사이즈아라이먼트의 제한을 보고한다. 이러한 멤버의 값은, 오버레이 표면을 표시할 경우에, 전송원 및 목적지 직사각형의 사이즈나 위치를 어떻게 하는지를 지시한다. 상세한 것에 대하여는, 「전송원직사각형과 목적지 직사각형」 및 「경계와 사이즈아라이먼트」를 참조할것.

또, 하드웨어는 dwMinOverlayStretch 및 dwMaxOverlayStretch 멤버의 신축(스트레치) 계수를 보고한다. 상세한 것에 대하여는, 「최소 및 최대 신축(스트레치) 계수」를 참조할것.

[Visual Basic]

지원 된 오버레이 기능에 대한 정보를 취득하려면 ,DirectDraw7.GetCaps 메소드를 호출한다. 이 메소드는, 모든 기능을 기술하고 있는 정보를 DDCAPS 형에 묻는다.

하드웨어 기능을 보고하는 경우, 디바이스 드라이버는 lCaps 구조체의 멤버에 플래그를 설정해, 언제 주어진 타입의 제한이 하드웨어에 의해 강제당하는지를 나타낸다. 드라이버의 능력을 취득하고 나서, 어느 제한이 적용하는지를 lCaps 멤버의 플래그로 조사한다. DDCAPS 형에는, 오버레이 표면에 대한 하드웨어 제한을 기술한 정보를 전달하는 9 개의 멤버가 있다. 이하의 겉(표)는, 오버레이에 관련한 멤버와 대응하는 플래그를 나타낸다.

멤버 | 플래그
lMaxVisibleOverlays | 이 멤버는 항상 유효
lCurrVisibleOverlays | 이 멤버는 항상 유효
lAlignBoundarySrc | DDCAPS_ALIGNBOUNDARYSRC
lAlignSizeSrc | DDCAPS_ALIGNSIZESRC
lAlignBoundaryDest | DDCAPS_ALIGNBOUNDARYDEST
lAlignSizeDest | DDCAPS_ALIGNSIZEDEST
lAlignStrideAlign | DDCAPS_ALIGNSTRIDE
lMinOverlayStretch | DDCAPS_OVERLAYSTRETCH
lMaxOverlayStretch | DDCAPS_OVERLAYSTRETCH

lMaxVisibleOverlays 및 lCurrVisibleOverlays 멤버는, 하드웨어가 표시할 수 있는 오버레이의 최대수, 및 그 중에 현재 표시 상태에 있는 수에 대한 정보를 전달한다.

게다가 하드웨어는 lAlignBoundarySrc,lAlignSizeSrc,lAlignBoundaryDest,lAlignSizeDest, 및 lAlignStrideAlign 멤버에 있는 직사각형의 위치나 사이즈아라이먼트의 제한을 보고한다. 이러한 멤버의 값은, 오버레이 표면을 표시할 경우에, 전송원 및 목적지 직사각형의 사이즈나 위치를 어떻게 하는지를 지시한다. 상세한 것에 대하여는, 「전송원직사각형과 목적지 직사각형」 및 「경계와 사이즈아라이먼트」를 참조할것.

또, 하드웨어는 lMinOverlayStretch 및 lMaxOverlayStretch 멤버의 신축(스트레치) 계수를 보고한다. 상세한 것에 대하여는, 「최소 및 최대 신축(스트레치) 계수」를 참조할것.


전송원직사각형과 목적지 직사각형

[C++]

오버레이 표면을 표시하려면 ,dwFlags 파라미터에 DDOVER_SHOW 플래그를 지정해, 오버레이 표면의 IDirectDrawSurface7::UpdateOverlay 메소드를 호출한다. 이 메소드에서는,lpSrcRect 및 lpDestRect 파라미터에 전송원직사각형과 목적지 직사각형을 지정한다. 전송원직사각형은, 프라이머리 표면으로 표시 상태의 오버레이 표면 위에의 직사각형을 기술한다. 메소드가 표면 모든 것을 사용하도록(듯이) 요구하려면 ,lpSrcRect 파라미터를 NULL 로 설정한다. 목적지 직사각형은, 오버레이 표면이 표시되는 프라이머리 표면 부분을 기술한다.

[Visual Basic]

오버레이 표면을 표시하려면 ,flags 파라미터에 DDOVER_SHOW 플래그를 지정해,DirectDrawSurface7.UpdateOverlay 메소드를 호출한다. 이 메소드에서는,RECT 및 rectD 파라미터에 전송원직사각형과 목적지 직사각형을 지정한다. 전송원직사각형은, 프라이머리 표면으로 표시 상태의 오버레이 표면 위에의 직사각형을 기술한다. 메소드가 표면 모든 것을 사용하도록(듯이) 요구하려면 ,RECT 파라미터에 하늘의 RECT 를 건네준다. 목적지 직사각형은, 오버레이 표면이 표시되는 프라이머리 표면 부분을 기술한다.

게다가DirectDrawSurface7.UpdateOverlayFx 메소드를 호출하는 것으로, 오버레이에 이펙트를 추가할 수가 있다. ddoverfx 파라미터로 설정된 오버레이 이펙트를 사용하려면 ,flags 파라미터에 DDOVER_DDFX 플래그를 설정해야 한다.

전송원직사각형과 목적지 직사각형은, 동일 사이즈일 필요는 없다. 목적지 직사각형을 전송원직사각형보다 작고 또는 크게 지정할 수도 있어 하드웨어에서는 표시할 경우에 적절히 오버레이를 수축하거나 신축(스트레치) 하거나 한다.

오버레이 표면을 표시하려면 , 양직사각형의 사이즈나 위치를 조정해야 하는 것이 있다. 조정이 필요한가 어떤가는, 디바이스 드라이버의 제한에 의한다. 상세한 것에 대하여는, 「경계와 사이즈아라이먼트」 및 「최소 및 최대 신축(스트레치) 계수」를 참조할것.


경계와 사이즈아라이먼트

[C++]

다양한 하드웨어의 제한에 의해, 디바이스 드라이버에 따라서는, 오버레이 표면을 표시하기 위해서 사용하는 전송원 및 목적지 직사각형의 위치나 사이즈에 제한을 받는 경우가 있다. 디바이스에 대해서 어느 제한이 들어맞을까를 알려면 ,IDirectDraw7::GetCaps 메소드를 호출하고 나서,DDCAPS 구조체의 dwCaps 멤버에 오버레이 관련의 플래그를 조사한다. 다음 표로 경계와 사이즈아라이먼트에 특유인 멤버와 플래그를 나타낸다.

카테고리 | 플래그 | 멤버
경계 (위치) 제한 | DDCAPS_ALIGNBOUNDARYSRC | dwAlignBoundarySrc
 | DDCAPS_ALIGNBOUNDARYDEST | dwAlignBoundaryDest
사이즈 제한 | DDCAPS_ALIGNSIZESRC | dwAlignSizeSrc
 | DDCAPS_ALIGNSIZEDEST | dwAlignSizeDest

제한에는, 경계 제한과 사이즈 제한의 2 개의 타입이 있다. 양타입의 제한과도 픽셀 (바이트는 아니다)로 나타내져 전송원 및 목적지 직사각형에 적용할 수가 있다. 또, 이러한 제한은, 오버레이나 프라이머리 표면의 픽셀 포맷에 의해 다양하다.

경계 제한은, 전송원 및 목적지 직사각형을 어디에 배치할 수 있을까에 영향을 준다. dwAlignBoundarySrc 및 dwAlignBoundaryDest 멤버의 값은, 대응하는 직사각형의 맨 왼쪽 위쪽의 아라이먼트를 전한다. 직사각형의 맨 왼쪽 위쪽의 x 좌표 (RECT 구조체의 left 멤버)는, 보고된 값의 배수가 아니면 안된다.

사이즈 제한은, 전송원 및 목적지 직사각형의 유효한 폭에 영향을 준다. dwAlignSizeSrc 및 dwAlignSizeDest 멤버의 값은, 대응하는 직사각형의 폭의 아라이먼트를 픽셀 단위로 전한다. 직사각형은, 보고된 값의 배수의 픽셀폭을 가지지 않으면 안 된다. 요구된 최소의 신축(스트레치) 계수에 따르기 위해서(때문에) 직사각형을 신축(스트레치) 하는 경우, 항상 신축(스트레치) 된 직사각형의 사이즈가 더 연속되어 있지 않으면 안 된다. 직사각형을 신축(스트레치) 한 후, 최소 신축(스트레치) 계수를 보관 유지하기 위해서는, 폭의 아라이먼트를 잘라 버리는 것이 아니라 끝맺는다. 상세한 것에 대하여는, 「최소 및 최대 신축(스트레치) 계수」를 참조할것.

[Visual Basic]

다양한 하드웨어의 제한에 의해, 디바이스 드라이버에 따라서는, 오버레이 표면을 표시하기 위해서 사용하는 전송원 및 목적지 직사각형의 위치나 사이즈에 제한을 받는 경우가 있다. 디바이스에 대해서 어느 제한이 들어맞을까를 알려면 ,DirectDraw7.GetCaps 메소드를 호출하고 나서,DDCAPS 형의 lCaps 멤버에 오버레이 관련의 플래그를 조사한다. 다음 표로 경계와 사이즈아라이먼트에 특유인 멤버와 플래그를 나타낸다.

카테고리 | 플래그 | 멤버
경계 (위치) 제한 | DDCAPS_ALIGNBOUNDARYSRC | lAlignBoundarySrc
 | DDCAPS_ALIGNBOUNDARYDEST | lAlignBoundaryDest
사이즈 제한 | DDCAPS_ALIGNSIZESRC | lAlignSizeSrc
 | DDCAPS_ALIGNSIZEDEST | lAlignSizeDest

제한에는, 경계 제한과 사이즈 제한의 2 개의 타입이 있다. 양타입의 제한과도 픽셀 (바이트는 아니다)로 나타내져 전송원 및 목적지 직사각형에 적용할 수가 있다. 또, 이러한 제한은, 오버레이나 프라이머리 표면의 픽셀 포맷에 의해 다양하다.

경계 제한은, 전송원 및 목적지 직사각형을 어디에 배치할 수 있을까에 영향을 준다. lAlignBoundarySrc 및 lAlignBoundaryDest 멤버의 값은, 대응하는 직사각형의 맨 왼쪽 위쪽의 아라이먼트를 전한다. 직사각형의 맨 왼쪽 위쪽의 x 좌표 (RECT 형의 left 멤버)는, 보고된 값의 배수가 아니면 안된다.

사이즈 제한은, 전송원 및 목적지 직사각형의 유효한 폭에 영향을 준다. lAlignSizeSrc 및 lAlignSizeDest 멤버의 값은, 대응하는 직사각형의 폭의 아라이먼트를 픽셀 단위로 전한다. 직사각형은, 보고된 값의 배수의 픽셀폭을 가지지 않으면 안 된다. 요구된 최소의 신축(스트레치) 계수에 따르기 위해서(때문에) 직사각형을 신축(스트레치) 하는 경우, 항상 신축(스트레치) 된 직사각형의 사이즈가 더 연속되어 있지 않으면 안 된다. 직사각형을 신축(스트레치) 한 후, 최소 신축(스트레치) 계수를 보관 유지하기 위해서는, 폭의 아라이먼트를 잘라 버리는 것이 아니라 끝맺는다. 상세한 것에 대하여는, 「최소 및 최대 신축(스트레치) 계수」를 참조할것.


최소 및 최대 신축(스트레치) 계수

[C++]

하드웨어의 제한에 의해, 디바이스에 따라서는, 대응하는 전송원직사각형과 비교해 목적지 직사각형의 폭이 제한을 받는 경우가 있다. DirectDraw 는, 이러한 제한을 신축(스트레치) 계수로서 전한다. 신축(스트레치) 계수란, 전송원직사각형과 목적지 직사각형의 폭의 비율이다. 드라이버가 신축(스트레치) 계수에 대한 정보를 제공하는 경우,IDirectDraw7::GetCaps 메소드를 호출한 후, 드라이버는 DDCAPS 구조체에 DDCAPS_OVERLAYSTRETCH 플래그를 설정한다. 신축(스트레치) 계수는 1000 을 걸어 보고되기 (위해)때문에, 1300 의 값은 실제로는 1.3 을 의미하는 것에 주의한다 (750 은 0.75 가 된다).

[Visual Basic]

하드웨어의 제한에 의해, 디바이스에 따라서는, 대응하는 전송원직사각형과 비교해 목적지 직사각형의 폭이 제한을 받는 경우가 있다. DirectDraw 는, 이러한 제한을 신축(스트레치) 계수로서 전한다. 신축(스트레치) 계수란, 전송원직사각형과 목적지 직사각형의 폭의 비율이다. 드라이버가 신축(스트레치) 계수에 대한 정보를 제공하는 경우,DirectDraw7.GetCaps 메소드를 호출한 후, 드라이버는 DDCAPS 형에 DDCAPS_OVERLAYSTRETCH 플래그를 설정한다. 신축(스트레치) 계수는 1000 을 걸어 보고되기 (위해)때문에, 1300 의 값은 실제로는 1.3 을 의미하는 것에 주의한다 (750 은 0.75 가 된다).

오버레이 목적지 직사각형의 신축(스트레치)나 수축에 제한을 받지 않는 디바이스에서는, 최소 및 최대 신축(스트레치) 계수 0 을 보고하는 경우가 있다.

최소 신축(스트레치) 계수는, 목적지 직사각형이 전송원직사각형과 비교해 어느 정도폭이 넓지 않으면 안 되는지, 또는 좁지 않으면 안 될까를 전한다. 최소 신축(스트레치) 계수가 1000 보다 크면, 그 비율만 목적지 직사각형의 폭을 넓히지 않으면 안 된다. 예를 들어, 드라이버가 1300 을 보고하면(자), 목적지 직사각형의 폭이 전송원직사각형의 폭의 적어도 1.3 배가 되도록(듯이) 해야 한다. 같이 최소 신축(스트레치) 계수가 1000 보다 작으면, 목적지 직사각형은 전송원직사각형보다 그 비율만 작아질 가능성이 있는 것을 나타낸다.

최대 신축(스트레치) 계수는, 목적지 직사각형의 폭을 신축(스트레치) 할 수 있는 최대 비율을 전한다. 예를 들어, 최대 신축(스트레치) 계수가 2000 의 경우, 목적지 직사각형은 전송원직사각형의 2 배까지 (2 배를 넘지 않는다)의 폭을 지정할 수가 있다. 최대 신축(스트레치) 계수가 1000 보다 작은 경우, 오버레이를 표시하기 위해서 목적지 직사각형의 폭을 그 비율만 수축해야 한다.

신축(스트레치) 한 후, 목적지 직사각형은 디바이스의 요구하는 사이즈아라이먼트 제한에 따를 필요가 있다. 이 때문에, 사이즈아라이먼트 하기 전에 목적지 직사각형을 신축(스트레치) 하면이야 있고. 상세한 것에 대하여는, 「경계와 사이즈아라이먼트」를 참조할것.

하드웨어에서는, 목적지 직사각형의 높이를 조정하지 않아도 괜찮다. 어스펙트비(가로세로 비율)을 보관 유지하기 위해(때문에), 네가티브인 결과를 일으키는 일 없이 목적지 직사각형의 높이를 늘릴 수가 있다.


오버레이 컬러 키

[C++]

다른 타입의 표면과 같이, 오버레이 표면은, 표면간의 투과형 블리트 처리를 제어하기 위한 전송원 및 목적지 컬러 키를 사용한다. 오버레이 표면은 블리트로 표시되지 않기 때문에,IDirectDrawSurface7::UpdateOverlay 메소드를 호출하면나무에, 프라이머리 표면상에의 오버레이 표면 표시 방법을 제어하려면 , 다른 방법이 필요하다. 이것은, 오버레이 컬러 키에 의해 파묻힌다. 오버레이 컬러 키에는, 그 블리트 관련의 대응하는 컬러 키와 같이,IDirectDrawSurface7::SetColorKey 메소드를 호출해 설정하는 전송원의 버젼과 목적지의 버젼이 있다 (상세한 것에 대하여는, 「컬러 키의 설정」을 참조할것). 전송원 또는 목적지 오버레이 컬러 키를 설정하려면 , DDCKEY_SRCOVERLAY 또는 DDCKEY_DESTOVERLAY 플래그를 사용한다. 오버레이 표면은, 블리트와 오버레이 컬러 키의 양쪽 모두를 사용해, 블리트 처리와 오버레이 표시 처리를 적절히 제어할 수가 있다. 2 개의 타입의 컬러 키는, 서로 서로 모순될 것은 없다.

IDirectDrawSurface7::UpdateOverlay 메소드는, 전송원오버레이 컬러 키를 이용해, 프라이머리 표면의 컨텐츠가 보이도록(듯이), 오버레이 표면의 어느 픽셀이 투명해야 한가를 결정한다. 같이 이 메소드는 목적지 오버레이 컬러 키를 이용해, 표시할 경우에 오버레이 표면에 의해 은폐 되는 프라이머리 표면 부분을 결정한다. 이 결과적으로 생기는 비주얼 이펙트는, 블리트 관련의 컬러 키에 의해 생성 되는 이펙트와 같다.

[Visual Basic]

다른 타입의 표면과 같이, 오버레이 표면은, 표면간의 투과형 블리트 처리를 제어하기 위한 전송원 및 목적지 컬러 키를 사용한다. 오버레이 표면은 블리트로 표시되지 않기 때문에,DirectDrawSurface7.UpdateOverlay 메소드를 호출하면나무에, 프라이머리 표면상에의 오버레이 표면 표시 방법을 제어하려면 , 다른 방법이 필요하다. 이것은, 오버레이 컬러 키에 의해 파묻힌다. 오버레이 컬러 키는, 그 블리트 관련의 대응하는 컬러 키와 같이,DirectDrawSurface7.SetColorKey 메소드를 호출해 설정하는 전송원의 버젼과 목적지의 버젼이 있다 (상세한 것에 대하여는, 「컬러 키의 설정」을 참조할것). 전송원 또는 목적지 오버레이 컬러 키를 설정하려면 , DDCKEY_SRCOVERLAY 또는 DDCKEY_DESTOVERLAY 플래그를 사용한다. 오버레이 표면은, 블리트와 오버레이 컬러 키의 양쪽 모두를 사용해, 블리트 처리와 오버레이 표시 처리를 적절히 제어할 수가 있다. 2 개의 타입의 컬러 키는, 서로 서로 모순될 것은 없다.

DirectDrawSurface7.UpdateOverlay 메소드는, 전송원오버레이 컬러 키를 이용해, 프라이머리 표면의 컨텐츠가 보이도록(듯이), 오버레이 표면의 어느 픽셀이 투명해야 한가를 결정한다. 같이 이 메소드는 목적지 오버레이 컬러 키를 이용해, 표시할 경우에 오버레이 표면에 의해 은폐 되는 프라이머리 표면 부분을 결정한다. 이 결과적으로 생기는 비주얼 이펙트는, 블리트 관련의 컬러 키에 의해 생성 되는 이펙트와 같다.


오버레이 표면의 배치

[C++]

IDirectDrawSurface7::UpdateOverlay 메소드를 호출해 최초로 오버레이를 표시한 후,IDirectDrawSurface7::SetOverlayPosition 메소드를 호출해 목적지 직사각형을 갱신할 수가 있다.

지정한 위치가 하드웨어에 의해 강제당하는 경계 아라이먼트 제한에 따르고 있는 것을 확인한다. 상세한 것에 대하여는, 「경계와 사이즈아라이먼트」를 참조할것. 또,SetOverlayPosition 는 클리핑을 실시하지 않는 것을 생각해 내는 것. 따라서, 오버레이가 타겟 표면의 인연을 초과할 가능성이 있는 좌표를 사용 하면, 메소드는 실패해 DDERR_INVALIDPOSITION 을 돌려준다.

[Visual Basic]

DirectDrawSurface7.UpdateOverlay 메소드를 호출해 최초로 오버레이를 표시한 후,DirectDrawSurface7.SetOverlayPosition 메소드를 호출해 목적지 직사각형을 갱신할 수가 있다.

지정한 위치가 하드웨어에 의해 강제당하는 경계 아라이먼트 제한에 따르고 있는 것을 확인한다. 상세한 것에 대하여는, 「경계와 사이즈아라이먼트」를 참조할것. 또,SetOverlayPosition 는 클리핑을 실시하지 않는 것을 생각해 내는 것. 따라서, 오버레이가 타겟 표면의 인연을 초과할 가능성이 있는 좌표를 사용 하면, 메소드는 실패해 DDERR_INVALIDPOSITION 을 돌려준다.


오버레이 표면의 생성

[C++]

모든 표면과 같이,IDirectDraw7::CreateSurface 메소드를 호출해 오버레이 표면을 생성 할 수 있다. 오버레이를 생성 하려면 , 관련부 DDSCAPS2 구조체에 DDSCAPS_OVERLAY 플래그를 포함한다.

오버레이의 지원은, 디스플레이 디바이스에 의해 실로 다양하다. 그 때문에, 주어진 픽셀 포맷이 대부분의 드라이버로 지원 되는지 어떤지의 보증은 없다. 따라서, 다양한 픽셀 포맷을 처리할 준비를 해 두지 않으면 안 된다. 드라이버로 지원 하는 비 RGB 포맷에 대한 정보는,IDirectDraw7::GetFourCCCodes 메소드 호출해 요구할 수가 있다.

[Visual Basic]

모든 표면과 같이,DirectDraw7.CreateSurface 메소드를 호출해 오버레이 표면을 생성 할 수 있다. 오버레이를 생성 하려면 , 관련부 DDSCAPS2 형에 DDSCAPS_OVERLAY 플래그를 포함한다.

오버레이의 지원은, 디스플레이 디바이스에 의해 실로 다양하다. 그 때문에, 주어진 픽셀 포맷이 대부분의 드라이버로 지원 되는지 어떤지의 보증은 없다. 따라서, 다양한 픽셀 포맷을 처리할 준비를 해 두지 않으면 안 된다. 드라이버로 지원 하는 비 RGB 포맷에 대한 정보는,DirectDraw7.GetFourCCCodes 메소드 호출해 요구할 수가 있다.

오버레이 표면을 생성 하려고 하는 경우, 최적인 픽셀 포맷으로 표면을 생성 하도록(듯이) 해, 주어진 픽셀 포맷이 지원되어 있지 않은 경우는, 다른 픽셀 포맷으로 한다.

오버레이 표면 플립핑 체인을 생성 할 수 있다. 상세한 것에 대하여는, 「복합 표면과 플립핑 체인의 생성」을 참조할것.


오버레이 Z 오더

[C++]

오버레이 표면은, 다른 스크린 컴퍼넌트 모든 상위에 위치하는 것과 가정되고 있다. 그러나, 복수의 오버레이 표면을 표시하는 경우, 이러한 오버레이를 비주얼에 정돈하는 어떠한 방법이 필요하게 된다. DirectDraw 에서는오버레이 Z 오더를 지원 해, 오버레이가 서로 클립 하는 순서를 관리한다. Z 오더의 값은, 프라이머리 표면으로부터 보는 사람까지의 개념 거리를 나타낸다. 그 값은, 프라이머리 표면의 곧 위에의 0 으로부터, 보는 사람의 가능한 한 근처에 있는 40 억까지의 범위가 된다. 어떠한 오버레이에서도, 동일한 Z 오더를 공용할 수 없다. Z 오더의 값을 설정하려면 ,IDirectDrawSurface7::UpdateOverlayZOrder 메소드를 호출한다.

목적지 컬러 키는,프라이머리 표면의 비트인 만큼 영향을 받아 다른 오버레이에 차단해진 오버레이에는 영향을 받지 않는다. 전송원컬러 키는,Z 오더가 오버레이에 대해서 지정되고 있는지 어떤지에 관련되어 없고 거기서 작용한다.

지정된 Z 오더가 없는 오버레이는, Z 오더가 0 이다고 보인다. 지정된 Z 오더가 없는 오버레이는, 프리이마리서페스 위에의 같은 영역에 오버레이 하면, 예측 불가능한 동작이 생긴다.

DirectDraw 오브젝트는, 다른 어플리케이션에 의해 표시된 오버레이의 Z 오더를 조사하지 않는다.

주 ： WM_KILLFOCUS 메세지에 대한 응답으로 UpdateOverlayZOrder 를 호출하는 것으로, 복수의 오버레이 표면에 있어서의 이전의 클리핑을 확보할 수 있다. 이 메세지를 받아들이는 경우, DDOVERZ_SENDTOBACK 로 설정하는 dwFlags 파라미터로 UpdateOverlayZOrder 메소드를 호출해, 오버레이 표면을 마지막 Z 오더 위치로 설정한다.

[Visual Basic]

오버레이 표면은, 다른 스크린 컴퍼넌트 모든 상위에 위치하는 것과 가정되고 있다. 그러나, 복수의 오버레이 표면을 표시하는 경우, 이러한 오버레이를 비주얼에 정돈하는 어떠한 방법이 필요하게 된다. DirectDraw 에서는오버레이 Z 오더를 지원 해, 오버레이가 서로 클립 하는 순서를 관리한다. Z 오더의 값은, 프라이머리 표면으로부터 보는 사람까지의 개념 거리를 나타낸다. 그 값은, 프라이머리 표면의 곧 위에의 0 으로부터, 보는 사람의 가능한 한 근처에 있는 40 억까지의 범위가 된다. 어떠한 오버레이에서도, 동일한 Z 오더를 공용할 수 없다. Z 오더의 값을 설정하려면 ,DirectDrawSurface7.UpdateOverlayZOrder 메소드를 호출한다.

목적지 컬러 키는,프라이머리 표면의 비트인 만큼 영향을 받아 다른 오버레이에 차단해진 오버레이에는 영향을 받지 않는다. 전송원컬러 키는,Z 오더가 오버레이에 대해서 지정되고 있는지 어떤지에 관련되어 없고 거기서 작용한다.

지정된 Z 오더가 없는 오버레이는, Z 오더가 0 이다고 보인다. 지정된 Z 오더가 없는 오버레이는, 프리이마리서페스 위에의 같은 영역에 오버레이 하면, 예측 불가능한 동작이 생긴다.

DirectDraw 오브젝트는, 다른 어플리케이션에 의해 표시된 오버레이의 Z 오더를 조사하지 않는다.

주 ： WM_KILLFOCUS 메세지에 대한 응답으로 UpdateOverlayZOrder 를 호출하는 것으로, 복수의 오버레이 표면에 있어서의 이전의 클리핑을 확보할 수 있다. 이 메세지를 받아들이는 경우, DDOVERZ_SENDTOBACK 로 설정하는 dwFlags 파라미터로 UpdateOverlayZOrder 메소드를 호출해, 오버레이 표면을 마지막 Z 오더 위치로 설정한다.


플립핑 오버레이 표면

[C++]

다른 타입의 표면과 같게, 오버레이 플립핑 체인을 생성 할 수 있다. 오버레이 플립핑 체인을 생성 한 후,IDirectDrawSurface7::Flip 메소드를 호출해 플립핑을 실시한다. 상세한 것에 대하여는, 「플립핑 표면」을 참조할것.

오버레이 표면 첨부의 비디오를 표시하는 소프트웨어 디코더는, DDFLIP_ODD 나 DDFLIP_EVEN 플래그를 사용해, 인공적인 움직임을 줄이는 기능의 Flip 메소드를 호출한다. 드라이버가 기우플립핑을 지원 하면 와, 드라이버 능력을 취득한 다음에,DDCAPS 구조체에 DDCAPS2_CANFLIPODDEVEN 플래그가 설정된다. 그 플래그가 설정되는 경우,IDirectDrawSurface7::UpdateOverlay 메소드를 호출하면나무에 DDOVER_BOB 플래그를 사용 하면, 인공적인 움직임을 최소화하기 위해서 "Bob" 알고리즘을 사용하도록(듯이) 드라이버로 지정할 수 있다. 그 후, DDFLIP_ODD 또는 DDFLIP_EVEN 플래그를 지정해 Flip 를 호출하는 경우, 드라이버는 지터 링 이상을 보정하기 위해서 자동적으로 오버레이 전송원직사각형을 조정한다.

[Visual Basic]

다른 타입의 표면과 같게, 오버레이 플립핑 체인을 생성 할 수 있다. 오버레이 플립핑 체인을 생성 한 후,DirectDrawSurface7.Flip 메소드를 호출해 플립핑을 실시한다. 상세한 것에 대하여는, 「플립핑 표면」을 참조할것.

오버레이 표면 첨부의 비디오를 표시하는 소프트웨어 디코더는, DDFLIP_ODD 나 DDFLIP_EVEN 플래그를 사용해, 인공적인 움직임을 줄이는 기능의 Flip 메소드를 호출한다. 드라이버가 기우플립핑을 지원 하면 와, 드라이버 능력을 취득한 다음에,DDCAPS 형에 DDCAPS2_CANFLIPODDEVEN 플래그가 설정된다. 그 플래그가 설정되는 경우,DirectDrawSurface7.UpdateOverlay 메소드를 호출하면나무에 DDOVER_BOB 플래그를 사용 하면, 인공적인 움직임을 최소화하기 위해서 "Bob" 알고리즘을 사용하도록(듯이) 드라이버로 지정할 수 있다. 그 후, DDFLIP_ODD 또는 DDFLIP_EVEN 플래그를 지정해 Flip 를 호출하는 경우, 드라이버는 지터 링 이상을 보정하기 위해서 자동적으로 오버레이 전송원직사각형을 조정한다.

하드웨어 능력을 취득할 경우에, 드라이버가 DDCAPS2_CANFLIPODDEVEN 플래그를 설정하고 있지 않는 경우, DDOVER_BOB 플래그를 지정한 UpdateOverlay 는 실패한다.

Bob 알고리즘에 대해서는, 「공통의 비디오의 문제의 회피 방법」을 참조할것.


압축한 텍스쳐 표면

[C++]

표면에는, 3D 오브젝트의 텍스쳐링에 대해서 사용하는 비트 맵을 포함할 수가 있다. 표면을 생성 하는 경우는,DDSCAPS 구조체의 dwFlags 멤버에 DDSCAPS_TEXTURE 플래그를 지정하지 않으면 안 된다.

[Visual Basic]

표면에는, 3D 오브젝트의 텍스쳐링에 대해서 사용하는 비트 맵을 포함할 수가 있다. 표면을 생성 하는 경우는,DDSCAPS2 형의 lCaps 멤버에 DDSCAPS_TEXTURE 플래그를 지정하지 않으면 안 된다.

Direct3D 직접 모드에 있어서의 텍스쳐링의 사용에 대해서는, Direct3D 직접 모드의 「텍스쳐」를 참조할것.

텍스쳐에 의해 소비되는 메모리 용량을 삭제하기 위해서, DirectDraw 에서는 텍스쳐 표면의 압축을 지원 한다.

몇개의 Direct3D 디바이스는, 압축한 텍스쳐 표면을 네이티브에 지원 한다. 이러한 디바이스로 압축한 표면을 생성 해, 그 디바이스에 데이터를 로드해 버리면, 다른 텍스쳐 표면과 같게 Direct3D 로 표면을 사용할 수 있다. 텍스쳐가 3D 표면 오브젝트에 맵 되는 경우, Direct3D 는 압축의 복원을 처리한다.

다른 디바이스에서는, 압축한 텍스쳐 표면을 최초부터 지원 하지 않는다. 이러한 디바이스를 사용 하면, 압축한 표면을 사용해, 디스크 위에의 텍스쳐나 현재 사용중의 메모리 이외에 로드 되는 텍스쳐를 표현할 경우에 도움이 되는 것에 눈치챌 것이다. Direct3D 에 텍스쳐를 주기 전에, DirectDraw 를 사용해 압축한 텍스쳐를 압축하고 있지 않는 포맷으로 변환할 수 있다.

DirectDraw 의 텍스쳐 압축에 대해서는, 다음의 항목을 참조할것.

  • 압축한 텍스쳐의 생성
  • 압축한 텍스쳐의 복원
  • 압축한 텍스쳐에의 블리트에 있어서의 투과성
  • 압축한 텍스쳐 포맷

Direct3D 직접 모드로 압축한 텍스쳐의 사용에 대해서는, Direct3D 직접 모드의 「텍스쳐 압축」을 참조할것.


압축한 텍스쳐의 생성

[C++]

표면의 생성시에 DDSURFACEDESC2 구조체에 압축한 텍스쳐 표면을 기술하려면 , 다음에 나타내는 스텝을 실시하는 것.

  • 모든 텍스쳐와 같게,DDSCAPS 구조체의 dwFlags 멤버에 DDSCAPS_TEXTURE 플래그를 지정한다.
  • DDPIXELFORMAT 구조체의 dwFourCC 멤버를 다음에 기술되는 DXT 코드의 1 개로 설정한다.
  • DDPIXELFORMAT 의 dwFlags 멤버에 DDPF_FOURCC 를 포함한다. DDPF_RGB 플래그를 설정해선 안 된다.
  • 4 의 배수의 픽셀의 폭과 높이를 지정한다.

이미지 데이터를 압축한 텍스쳐 표면에 로드하려면 , 2 방법의 방법이 있다.

  • 일반적인 RGB 또는 ARGB 표면을 생성 해, 그 표면에 일반적인 비트 맵을 로드한다. 그리고,IDirectDrawSurface7::Blt 또는 IDirectDrawSurface7::BltFast 를 사용해, 압축하고 있지 않는 표면으로부터 압축한 표면에 블리트 한다. DirectDraw 가 압축을 실시한다.
  • 파일로부터 압축한 데이터를 로드해, 표면 메모리에 그 데이터를 직접 카피한다 ( 「표면 메모리에의 직접 액세스」를 참조할것). SDK 로 제공되는 DirectX Texture 툴 (Dxtex.exe)을 사용 하면, 압축한 텍스쳐 (DDS) 파일의 생성과 변환을 실시할 수 있다. 또, 각자의 DDS 파일을 생성 할 수 있거나 압축한 표면으로부터 데이터를 카피하는지, 각자의 루틴을 사용해 일반적인 비트 맵 데이터를 압축한 포맷의 1 개로 변환할 수 있다.

주 ： 압축한 표면으로 IDirectDrawSurface7::Lock 또는 IDirectDrawSurface7::GetSurfaceDesc 를 호출하는 경우, DDSD_LINEARSIZE 플래그가 DDSURFACEDESC 구조체의 dwFlags 멤버로 설정되어 있어dwLinearSize 멤버에 압축한 표면 데이터를 포함하기 위해서(때문에) 할당할 수 있었던 바이트수가 포함되지 않으면 안 된다. dwLinearSize 파라미터는 lPitch 파라미터와의 공용체이므로, 이러한 파라미터는 DDSD_LINEARSIZE 및 DDSD_PITCH 플래그와 같이 서로 배타가 된다.

[Visual Basic]

표면의 생성시에 DDSURFACEDESC2 형에 압축한 텍스쳐 표면을 기술하려면 , 다음에 나타내는 스텝을 실시하는 것.

  • 모든 텍스쳐와 같게,DDSCAPS2 형의 lCaps 멤버에 DDSCAPS_TEXTURE 플래그를 지정한다.
  • DDPIXELFORMAT 형의 lFourCC 멤버를 다음에 기술되는 DXT 코드의 1 개로 설정한다.
  • DDPIXELFORMAT 의 lFlags 멤버에 DDPF_FOURCC 를 포함한다. DDPF_RGB 플래그를 설정해선 안 된다.
  • 4 의 배수의 픽셀의 폭과 높이를 지정한다.

이미지 데이터를 압축한 텍스쳐 표면에 로드하려면 , 2 방법의 방법이 있다.

  • 일반적인 RGB 또는 ARGB 표면을 생성 해, 그 표면에 일반적인 비트 맵을 로드한다. 그리고,DirectDrawSurface7.Blt 또는 DirectDrawSurface7.BltFast 를 사용해, 압축하고 있지 않는 표면으로부터 압축한 표면에 블리트 한다. DirectDraw 가 압축을 실시한다.
  • 파일로부터 압축한 데이터를 로드해, 표면 메모리에 그 데이터를 직접 카피한다 ( 「표면 메모리에의 직접 액세스」를 참조할것). SDK 로 제공되는 DirectX Texture 툴 (Dxtex.exe)을 사용 하면, 압축한 텍스쳐 (DDS) 파일의 생성과 변환을 실시할 수 있다. 또, 각자의 DDS 파일을 생성 할 수 있거나 압축한 표면으로부터 데이터를 카피하는지, 각자의 루틴을 사용해 일반적인 비트 맵 데이터를 압축한 포맷의 1 개로 변환할 수 있다.

주 : 압축한 표면으로 DirectDrawSurface7.Lock 또는 DirectDrawSurface7.GetSurfaceDesc 를 호출하는 경우, DDSD_LINEARSIZE 플래그가 DDSURFACEDESC2 형의 lFlags 멤버로 설정되어 있어lLinearSize 멤버에 압축된 표면 데이터를 포함하기 위해서(때문에) 할당할 수 있었던 바이트수가 포함되지 않으면 안 된다. lLinearSize 파라미터는 lPitch 파라미터와의 공용체이므로, 이러한 파라미터는 DDSD_LINEARSIZE 및 DDSD_PITCH 플래그와 같이 서로 배타가 된다.

이 이점은, 어플리케이션 자체로 특정의 포맷에 대한 표면의 특정의 폭과 높이에 필요한 스토리지 용량을 계산하지 않고 , 압축한 표면의 컨텐츠를 파일에 카피할 수 있는 것에 있다.

압축한 텍스쳐의 5 개의 타입을 이하의 겉(표)에 나타낸다. 데이터가 저장 되는 방법 (각자 압축 루틴을 기술하는 경우인 만큼 필요하다)의 상세한 것에 대하여는, 「압축한 텍스쳐 포맷」을 참조할것.

FOURCC | 설명 | 알파값사전 곱셈이 끝난?
DXT1 | 불투명/1 비트 알파 | n/a
DXT2 | 명시적인 알파 | Yes
DXT3 | 명시적인 알파 | No
DXT4 | 보간 한 알파 | Yes
DXT5 | 보간 한 알파 | No

주 ： 값사전 곱셈이 끝난 상태가 아닌 포맷화등값사전 곱셈 끝난 포맷에 블리트 하는 경우, DirectDraw 는 알파값을 기본으로 색을 스케일 한다. 값사전 곱셈 끝난 퍼 매트로부터 값사전 곱셈이 끝난 상태가 아닌 포맷에의 블리트는 지원 되지 않는다. 값사전 곱셈 끝난 알파 전송원으로부터 값사전 곱셈이 끝난 상태가 아닌 알파 목적지에의 블리트를 시험하면(자), 메소드가 DDERR_INVALIDPARAMS 를 돌려주는 값사전 곱셈 끝난 알파 전송원으로부터 알파가 없는 목적지에 블리트 하면, 알파에서 스케일 되는 전송원색성분은과 같이 카피된다.


압축한 텍스쳐의 복원

텍스쳐 표면의 압축과 같이, 압축한 텍스쳐의 복원은 DirectDraw 블리트 서비스로부터 실시할 수 있다. HEL 가 시스템 메모리간의 압축을 복원하는 블리트를 실시하기 (위해)때문에, 이것들은 항상 지원 된다. 같이 HEL 에서는 관리하의 텍스쳐의 블리트를 항상 실행한다 (DDSCAPS2_TEXTUREMANAGE 능력). 이외의 상황에는, 다음의 단락으로 가리키는 제한이 있다.

목적지 표면에 DDSCAPS_OFFSCREENPLAIN 능력이 있으면, 드라이버가 비디오 메모리 표면의 생성을 지원 해, 압축한 비디오 메모리 표면으로부터 압축하고 있지 않는 비디오나 시스템 메모리 표면에의 블리트에 있어서의 압축의 복원을 실시한다.

압축한 시스템 메모리 표면으로부터 압축하고 있지 않는 비디오 메모리 표면에의 블리트는 많은 경우 지원 되지 않고, 드라이버가 압축한 텍스쳐를 지원 하는 경우에서도 지원 되지 않는다. 이것은, 압축한 시스템 메모리 표면의 압축의 복원과 비디오 메모리 표면에의 컨텐츠의 이동이 불가능한 것을 나타내고 있는 것은 아니다. 단지, 추가의 스텝을 필요로 하는 것만으로 있다.

비디오 메모리에의 시스템 메모리 표면의 압축의 복원

  1. 필요한 넓이와 픽셀 포맷의 시스템 메모리에, 압축하고 있지 않는 오프 스크린 프레인 표면을 생성 한다.
  2. 압축한 시스템 메모리 표면으로부터 압축하고 있지 않는 시스템 메모리 표면에 블리트 한다 (이 경우, DirectDraw HEL 가 압축의 복원을 실행한다).
  3. 압축하고 있지 않는 표면으로부터 압축하고 있지 않는 비디오 메모리 표면에 블리트 한다.


압축한 텍스쳐에의 블리트에 있어서의 투과성

DirectDraw 에서는, 프레인 RGB 표면으로부터 알파 첨부의 압축한 텍스쳐를 생성 하는 특별한 트릭을 제공한다. 전송원컬러 키가 전송원 RGB 표면으로 제공되는 경우, DirectDraw 는 목적지의 색의 전픽셀에 0 의 알파값을 할당한다. DXT1 텍스쳐는 픽셀 마다 1 비트의 알파 정보만을 소유하기 위해(때문에), 이 기술은 DXT1 텍스쳐의 생성에 특별히 도움이 된다.

주 ： 이 기술을 제어하기 위해서 플래그는 필요없다. 압축한 텍스쳐에 모든 투과성의 필요가 없는 경우는, 전송원표면에 전송원컬러 키를 설정하지 않는 것.


압축한 텍스쳐 포맷

여기에서는, 압축한 텍스쳐 포맷의 내부 조직에 대해 설명한다. 압축한 텍스쳐를 사용하는 경우, DirectDraw 가 압축한 텍스쳐간의 변환을 처리하기 위해(때문에), 이러한 정보를 자세하게 알 필요는 없다. 그러나, 압축한 표면 데이터를 직접 처리하는 경우는, 이 정보가 도움이 될 것이다.

DirectDraw 에서는, 텍스쳐 맵을 4 × 4 의 텍셀 블록에 분할하기 위해서 압축 포맷을 사용한다. 텍스쳐에 투과성이 포함되지 않는 경우 (불투명), 또는 투과성이 1 비트 알파에서 지정되는 경우, 8 바이트 블록이 텍스쳐 맵 블록을 나타낸다. 텍스쳐 맵에 투과형 텍셀이 포함되지 않는 경우, 알파 채널을 사용해 16 바이트 블록이 텍스쳐 맵 블록을 나타낸다.

이 2 개의 포맷에 대해서는, 다음의 섹션으로 설명한다.

  • 불투명과 1 비트 알파 텍스쳐
  • 알파 채널에 의한 텍스쳐

주 ： 모든 단일의 텍스쳐에서는, 16 텍셀의 그룹 마다 64 비트 또는 128 비트로서 저장 되는 데이터를 지정하지 않으면 안 된다. 64 비트 블록 (즉, 포맷 DXT1)이 텍스쳐용으로 사용되는 경우, 몇개의 텍스쳐의 블록 마다 불투명과 1 비트 알파 포맷을 조합할 수가 있다. 즉, 색 0 으로 색 1 의 부호 없음 정수의 크기의 비교는, 16 텍셀의 각 블록 마다 실행된다.

128 비트 블록을 사용하는 경우, 텍스쳐 전체에 알파 채널을 명시적 (포맷 DXT2 또는 DXT3) 또는 보간 한 모드 (포맷 DXT4 또는 DXT5)로 지정하지 않으면 안 된다. 색도 같이 보간 한 모드가 8 의 보간 한 알파인가, 블록을 기본으로 사용되는 6 의 보간 한 알파 모드의 어느 쪽인지를 선택되는 것에 주의 해야 한다. 게다가 알파 0 으로 알파 1 의 크기의 비교는, 블록 마다 행해진다.


Private 표면 데이터

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

표면과 함께 모든 종류의 어플리케이션 고유 데이터를 저장 할 수 있다. 예를 들어, 게임의 맵을 나타내는 표면에는, 지역 정보를 포함한 경우가 있다.

표면에서는, 1 개(살) 이상의 Private 데이터 버퍼를 소유할 수 있다. 각 버퍼는, 표면에 데이터를 Attach 할 때로 지정하는 GUID 로 식별된다.

Private 표면 데이터를 저장 하려면 ,IDirectDrawSurface7::SetPrivateData 메소드를 사용한다. 이 메소드는, 전송원버퍼, 데이터의 사이즈, 데이터용으로 어플리케이션으로 정의한 GUID 에의 포인터를 건네준다. 수의에, 전송원데이터는 COM 오브젝트의 폼에 존재할 수 있다. 이 경우, 오브젝트의 lUnknown 인터페이스 포인터에 포인터를 건네주어, DDSPD_IUNKNOWNPOINTER 플래그를 설정한다. 다른 플래그 (DDSPD_VOLATILE)는, 표면의 컨텐츠를 변경하지 않는 한 유효한 표면에 데이터가 Attach 되고 있는 것을 나타낸다 (상세한 것에 대하여는, 「표면 고유치」를 참조할것).

SetPrivateData 는 데이터에 대해서 내부 버퍼를 할당해 데이터를 카피한다. 그 후로, 전송원버퍼 또는 오브젝트를 안전하게 릴리즈 할 수 있다. 내부 버퍼 또는 인터페이스 참조는,IDirectDrawSurface7::FreePrivateData 의 호출시에 릴리즈 된다. 표면이 릴리즈 되면(자), 이 처리는 자동적으로 발생한다.

표면에 대한 Private 데이터를 취득하려면 , 정확한 사이즈의 버퍼를 할당해SetPrivateData 로 데이터에 할당할 수 있었던 GUID 를 건네주는 IDirectDrawSurface7::GetPrivateData 메소드를 호출하지 않으면 안 된다. 이 버퍼를 사용하는 모든 동적 메모리의 릴리즈에 대해서는, 각자 책임을 가진다. 데이터가 COM 오브젝트의 경우, 이 메소드는 Iunknown 포인터를 취득한다.

할당하는 버퍼의 사이즈를 모르는 경우, 최초로 *lpcbBufferSize 에 제로를 넣어 GetPrivateData 를 호출한다. 이 메소드가 DDERR_MOREDATA 로 실패했을 경우,*lpcbBufferSize 에 필요한 바이트수를 돌려준다.


표면 고유치

[C++]

표면의 고유치에 의해, 표면이 변경했는지 어떠했는지를 결정할 수 있다. DirectDraw 가 표면을 생성 하는 경우, DirectDraw 에서는 IDirectDrawSurface7::GetUniquenessValue 메소드를 사용해 취득해 저장 할 수 있는 고유치를 할당한다. 그리고, 표면이 변경했는지 어떠했는지를 결정할 때는 항상, 이 메소드를 다시 호출해, 낡은 값에 대해서 새로운 값을 비교한다. 값이 다른 경우, 표면은 변경하고 있다.

GetUniquenessValue 에 의해 돌려주어지는 진정한 값이 0 이 아닌 한, 값은 부적절이 된다. DirectDraw 가 표면이 제어 이상의 프로세스로 변경되었던 것에 눈치채면(자), 표면에 이 값을 할당한다. GetUniquenessValue 가 0 을 돌려주면(자), 단지 표면 상태를 미확정이지만 안다.

표면의 고유치를 변경하기 위해서, 어플리케이션은 IDirectDrawSurface7::ChangeUniquenessValue 메소드를 사용할 수 있다. 예를 들어, 표면 자체를 변경하지 않고 표면의 고유치를 변경하는 어플리케이션 또는 컴퍼넌트로부터 이 메소드가 불려 가 변경의 다른 몇개의 프로세스에 통지한다. 그러나, 대부분의 어플리케이션에서는 고유치의 변경의 필요는 없다.

[Visual Basic]

표면의 고유치에 의해, 표면이 변경했는지 어떠했는지를 결정할 수 있다. DirectDraw 가 표면을 생성 하는 경우, DirectDraw 에서는 DirectDrawSurface7.GetUniquenessValue 메소드를 사용해 취득해 저장 할 수 있는 고유치를 할당한다. 그리고, 표면이 변경했는지 어떠했는지를 결정할 때는 항상, 이 메소드를 다시 호출해, 낡은 값에 대해서 새로운 값을 비교한다. 값이 다른 경우, 표면은 변경하고 있다.

GetUniquenessValue 에 의해 돌려주어지는 진정한 값이 0 이 아닌 한, 값은 부적절이 된다. DirectDraw 가 표면이 제어 이상의 프로세스로 변경되었던 것에 눈치채면(자), 표면에 이 값을 할당한다. GetUniquenessValue 가 0 을 돌려주면(자), 단지 표면 상태를 미확정이지만 안다.

표면의 고유치를 변경하기 위해서, 어플리케이션은 DirectDrawSurface7.ChangeUniquenessValue 메소드를 사용할 수 있다. 예를 들어, 표면 자체를 변경하지 않고 표면의 고유치를 변경하는 어플리케이션 또는 컴퍼넌트로부터 이 메소드가 불려 가 변경의 다른 몇개의 프로세스에 통지한다. 그러나, 대부분의 어플리케이션에서는 고유치의 변경의 필요는 없다.


비로컬 비디오 메모리 표면의 사용

DirectDraw 는, 비로컬 비디오 메모리로 표면을 생성 하기 위해서 AGP (Advanced Graphics Port) 아키텍쳐를 지원 한다. AGP 를 장비 한 시스템에서는, 로컬 비디오 메모리가 만배인 경우나 비로컬 비디오 메모리가 명시적으로 요구되고 있는 경우에, 장비 되고 있는 AGP 의 이행 타입에 의해, DirectDraw 는 비로컬 비디오 메모리를 사용한다.

[C++]

현시점에서는,"실행 모델" 및 "DMA 모델 " 로서 알려져 있는 2 개의 AGP 아키텍쳐 이행이 있다. 실행 모델의 이행에서는, 디스플레이 디바이스는 비로컬 비디오 메모리 표면과 로컬 비디오 메모리 표면으로 동일한 기능을 지원 한다. 그 결과, 하드웨어 능력을 취득하기 위해서 IDirectDraw7::GetCaps 메소드를 호출하면,DDCAPS 구조체의 dwNLVBCaps,dwNLVBCaps2,dwNLVBCKeyCaps,dwNLVBFXCaps, 및 dwNLVBRops 멤버에 있는 블리트 관련의 플래그는, 로컬 비디오 메모리의 경우와 동일하게 된다. 실행 모델에서는, 로컬 비디오 메모리가 만배가 되면(자), 호출로 특히 지정이 없는 한, DirectDraw 는 자동적으로 비로컬 비디오 메모리에 의지하려고 한다.

DMA 모델의 이행에서는, 비로컬 비디오 메모리 표면으로부터의 블리트나 텍스쳐링의 지원이 제한된다. 디스플레이 디바이스가 DMA 모델을 사용하는 경우, 디바이스 능력을 취득할 경우에 dwCaps2 멤버에 DDCAPS2_NONLOCALVIDMEMCAPS 플래그가 설정된다. DMA 모델에서는,DDCAPS 구조체의 dwNLVBCaps,dwNLVBCaps2,dwNLVBCKeyCaps,dwNLVBFXCaps, 및 dwNLVBRops 멤버에 포함되는 블리트 관련의 플래그는, 지원 하는 기능을 기술한다. DMA 모델에서는, 로컬 비디오 메모리가 만배 때에, 호출이 명시적으로 로컬 비디오 메모리를 요구하지 않는 한, DirectDraw 는 자동적으로 텍스쳐 표면인 만큼 대해 비로컬 비디오 메모리에 의지한다. 이러한 방법으로 처리되는 것은 텍스쳐 표면 뿐이다. 그 외의 타입의 표면은 모두, 호출이 명시적으로 비로컬 메모리를 요구하지 않는 한, 비로컬 비디오 메모리에 생성 할 수 없다.

DMA 모델의 이행에서는, 비로컬 비디오 메모리 표면으로부터의 텍스쳐링에 대한 지원은 다양하다. 드라이버가 비로컬 비디오 메모리 표면으로부터의 텍스쳐링을 지원 하는 경우,IDirect3DDevice7::GetCaps 메소드를 호출해 3D 드라이버 능력을 취득할 경우에, D3DDEVCAPS_TEXTURENONLOCALVIDMEM 플래그가 설정된다.

[Visual Basic]

현시점에서는,"실행 모델" 및 "DMA 모델 " 로서 알려져 있는 2 개의 AGP 아키텍쳐 이행이 있다. 실행 모델의 이행에서는, 디스플레이 디바이스는 비로컬 비디오 메모리 표면과 로컬 비디오 메모리 표면으로 동일한 기능을 지원 한다. 그 결과, 하드웨어 능력을 취득하기 위해서 DirectDraw7.GetCaps 메소드를 호출하면,DDCAPS 형의 lNLVBCaps,lNLVBCaps2,lNLVBCKeyCaps,lNLVBFXCaps 및 lNLVBRops 멤버에 있는 블리트 관련의 플래그는, 로컬 비디오 메모리의 경우와 동일하게 된다. 실행 모델에서는, 로컬 비디오 메모리가 만배가 되면(자), 호출로 특히 지정이 없는 한, DirectDraw 는 자동적으로 비로컬 비디오 메모리에 의지하려고 한다.

DMA 모델의 이행에서는, 비로컬 비디오 메모리 표면으로부터의 블리트나 텍스쳐링의 지원이 제한된다. 디스플레이 디바이스가 DMA 모델을 사용하는 경우, 디바이스 능력을 취득할 경우에 lCaps2 멤버에 DDCAPS2_NONLOCALVIDMEMCAPS 플래그가 설정된다. DMA 모델에서는,DDCAPS 형의 lNLVBCaps,lNLVBCaps2,lNLVBCKeyCaps,lNLVBFXCaps, 및 lNLVBRops 멤버에 포함되는 블리트 관련의 플래그는, 지원 하는 기능을 기술한다. DMA 모델에서는, 로컬 비디오 메모리가 만배 때에, 호출이 명시적으로 로컬 비디오 메모리를 요구하지 않는 한, DirectDraw 는 자동적으로 텍스쳐 표면인 만큼 대해 비로컬 비디오 메모리에 의지한다. 이러한 방법으로 처리되는 것은 텍스쳐 표면 뿐이다. 그 외의 타입의 표면은 모두, 호출이 명시적으로 비로컬 메모리를 요구하지 않는 한, 비로컬 비디오 메모리에 생성 할 수 없다.

DMA 모델의 이행에서는, 비로컬 비디오 메모리 표면으로부터의 텍스쳐링에 대한 지원은 다양하다. 드라이버가 비로컬 비디오 메모리 표면으로부터의 텍스쳐링을 지원 하는 경우,Direct3DDevice7.GetCaps 메소드를 호출해 3D 드라이버 능력을 취득할 경우에, D3DDEVCAPS_TEXTURENONLOCALVIDMEM 플래그가 설정된다.


표면 문맥과 디바이스 콘텍스트

DirectDraw 와 GDI 서비스를 혼합해 DirectDraw 표면의 문맥을 처리하는 것이, 도움이 되는 경우가 있다. DirectDraw 는, 디바이스 콘텍스트로부터 DirectDraw 표면에 액세스 할 수 있어 그 표면의 디바이스 콘텍스트를 주는 표면을 취득할 수 있는 메소드를 제공한다. 여기에서는, 다음의 항목으로 이러한 기능을 자세하게 설명한다.

  • 표면에 대한 디바이스 콘텍스트의 취득
  • 디바이스 콘텍스트에 의한 표면의 검출


표면에 대한 디바이스 콘텍스트의 취득

[C++]

GDI 함수에 의해 DirectDraw 표면 오브젝트의 컨텐츠를 변경하는 경우, GDI 호환의 디바이스 콘텍스트 핸들을 취득하지 않으면 안 된다. 이것은,DrawText Win32 함수를 호출해 DirectDraw 표면의 텍스트를 표시하는 경우에 도움이 된다. 이 함수는, 파라미터로서 디바이스 콘텍스트에 대한 핸들을 받는다. 표면에 대한 IDirectDrawSurface7::GetDC 메소드를 호출하는 것으로, 그 표면에 대한 GDI 호환의 디바이스 콘텍스트를 취득할 수 있다. 다음의 예로 이 방법을 나타낸다.

// 이 예에서는, lpDDS4 변수가 IDirectDrawSurface7
// 인터페이스에 대한 유효한 포인터가 된다.

  HDC     hdc;
  HRESULT HR;

  hr = lpDDS7->GetDC(&hdc);
  if(FAILED(hr))
      return hr;

// 여기서, DrawText 나 몇개의 다른 GDI 함수를
// 호출한다.

  lpDDS7->ReleaseDC(hdc);

표면의 디바이스 콘텍스트가 필요없게 되었을 때에,IDirectDrawSurface7::ReleaseDC 메소드를 호출하고 있는 것에 주의한다. IDirectDrawSurface7::GetDC 메소드에서는, 표면을 잠그기 위해서(때문에) IDirectDrawSurface7::Lock 메소드의 내부 버젼이 필요하므로, 이 스텝이 요구된다. IDirectDrawSurface7::ReleaseDC 메소드가 불려 갈 때까지, 그 표면은 락 된채로 있다.

[Visual Basic]

GDI 함수에 의해 DirectDraw 표면 오브젝트의 컨텐츠를 변경하는 경우, GDI 호환의 디바이스 콘텍스트 핸들을 취득하지 않으면 안 된다. 표면에 대한 DirectDrawSurface7.GetDC 메소드를 호출하는 것으로, 그 표면에 대한 GDI 호환의 디바이스 콘텍스트를 취득할 수 있다.

표면의 디바이스 콘텍스트가 필요없게 되었을 때에,DirectDrawSurface7.ReleaseDC 메소드를 호출하고 있는 것에 주의한다. DirectDrawSurface7.GetDC 메소드에서는, 표면을 잠그기 위해서(때문에) DirectDrawSurface7.Lock 메소드의 내부 버젼이 필요하므로, 이 스텝이 요구된다. DirectDrawSurface7.ReleaseDC 메소드가 불려 갈 때까지, 그 표면은 락 된채로 있다.


디바이스 콘텍스트에 의한 표면의 검출

[C++]

IDirectDraw7::GetSurfaceFromDC 메소드를 호출하는 것으로, 표면에 대한 디바이스 콘텍스트로부터 표면의 IDirectDrawSurface7 인터페이스에의 포인터를 취득할 수 있다. 이 기능은, 컴퍼넌트 어플리케이션이나 ActiveX® 컨트롤로 매우 도움이 된다. 이 경우, 실행시에 드로잉(Drawing)하기 위한 디바이스 콘텍스트를 일반적으로 주어지지만,IDirectDrawSurface7 인터페이스로 밝혀지는 기능을 이용할 수가 있다.

디바이스 콘텍스트는, DirectDraw 오브젝트와 관계가 없는 메모리를 식별할 가능성이 있다. 또, 디바이스 콘텍스트는, 다른 DirectDraw 오브젝트 모두에 대한 표면을 식별할 가능성도 있다. 후자의 경우는, 복수의 모니터를 사용하는 시스템으로 발생하기 쉽다. 디바이스 콘텍스트가 DirectDraw 오브젝트로 생성 하지 않았던 표면을 식별하지 않는 경우, 메소드는 DDERR_NOTFOUND 을 돌려주어 실패한다.

다음의 샘플 코드로, 매우 간단한 경우를 설명한다.

// 이 예에서는, hdc 변수가 비디오 메모리 디바이스 콘텍스트에
// 대하는 유효한 핸들이 된다.
// lpDD 변수는, 유효한 IDirectDraw7 인터페이스 포인터이다.

LPDIRECTDRAWSURFACE7 lpDDS;
HRESULT hr;

hr = lpDD->GetSurfaceFromDC(hdc, &lpDDS);
if(SUCCEEDED(hr)) {
// 이 표면의 인터페이스를 사용한다.
}
else if(DDERR_NOTFOUND == hr) {
    OutputDebugString("HDC not from this DirectDraw surface\n");
 }
[Visual Basic]

DirectDraw7.GetSurfaceFromDC 메소드를 호출하는 것으로, 표면에 대한 디바이스 콘텍스트로부터 표면의 DirectDrawSurface7 오브젝트를 취득할 수 있다. 이 기능은, 컴퍼넌트 어플리케이션이나 ActiveX® 컨트롤로 매우 도움이 된다. 이 경우, 실행시에 드로잉(Drawing)하기 위한 디바이스 콘텍스트를 일반적으로 주어지지만,DirectDrawSurface7 오브젝트로 밝혀지는 기능을 이용할 수가 있다.

디바이스 콘텍스트는, DirectDraw 오브젝트와 관계가 없는 메모리를 식별할 가능성이 있다. 또, 디바이스 콘텍스트는, 다른 DirectDraw 오브젝트 모두에 대한 표면을 식별할 가능성도 있다. 디바이스 콘텍스트가 DirectDraw 오브젝트로 생성 하지 않았던 표면을 식별하지 않는 경우, 메소드는 DDERR_NOTFOUND 을 돌려주어 실패한다.

다음의 샘플 코드로, 매우 간단한 경우를 설명한다.

'이 예에서는, hdc 변수가 비디오 메모리 디바이스 콘텍스트에
'대하는 유효한 핸들이 된다.
' DD 변수는 유효한 DirectDraw7 오브젝트이다.

Dim dds As DirectDrawSurface7

Set dds = dd.GetSurfaceFromDC(hDC)

If Err.Number = DDERR_NOTFOUND Then
MsgBox "hDC not from this DirectDraw surface"
End If


팔레트

여기에서는, DirectDrawPalette 오브젝트에 대해 설명한다. 다음의 항목에 대해 기술한다.

  • 팔레트란?
  • 팔레트 타입
  • 비프라이머리 표면에서의 팔레트의 설정
  • 팔레트의 공유
  • 팔레트 애니메이션


팔레트란?

팔레트화 표면은, 의미가 있는 표시를 하기 위해서 팔레트를 필요로 한다. 팔레트화 표면은 컬러 인덱스 첨부 표면이라고도 불려 각각의 번호가 픽셀을 나타내는 번호의 집합이 된다. 번호의 값은, 각각의 픽셀을 표시할 경우에 어느 색을 사용해야할 것인가를 DirectDraw 에게 전하는컬러 테이블 에의 인덱스이다. 단지 팔레트라고도 불리는 DirectDrawPalette 오브젝트는, 컬러 테이블을 간단하게 제어하는 수단을 제공한다. 16 비트 이상의 픽셀 포맷을 사용하는 표면은, 팔레트를 사용하지 않는다.

DirectDrawPalette 오브젝트는, 인덱스 첨부 컬러 테이블을 나타낸다. 이 컬러 테이블에는, 컬러 인덱스 첨부 표면으로 이용하는 2, 4, 16, 또는 256 의 엔트리가 있다. 팔레트의 각각의 엔트리는, 표면내에서 픽셀을 표시할 경우에 사용하는 색을 기술하는 RGB 셋잇단음표이다. 컬러 테이블에는, 사용하는 색을 나타내는 16 비트, 또는 24 비트 RGB 셋잇단음표가 포함되어 있다. 16 색팔레트에서는, 테이블에 다른 256 색팔레트에의 인덱스를 포함할 수도 있다. 텍스쳐,오프 스크린 표면, 및오버레이 표면에 대해서 팔레트가 지원 되고 있어 모두프라이머리 표면과 같은 팔레트일 필요는 없다.

[C++]

IDirectDraw7::CreatePalette 를 호출하는 것으로, 팔레트를 생성 할 수 있다. 이 메소드는, 팔레트 오브젝트의 IDirectDrawPalette 인터페이스에의 포인터를 취득한다. 이 인터페이스의 메소드를 사용해, 팔레트 엔트리의 조작, 오브젝트의 능력에 관한 정보의 취득, 또는 오브젝트의 초기화를 할 수 있다 (CoCreateInstance COM 함수를 사용해 오브젝트를 생성 했을 경우).

표면의 IDirectDrawSurface7::SetPalette 메소드를 호출하는 것으로, 표면에 팔레트를 적용할 수 있다. 1 개의 팔레트를 복수의 표면에 적용할 수가 있다.

DirectDrawPalette 오브젝트는, 8 비트 팔레트의 엔트리 0, 및 엔트리 255 를 취득한다. 다만, DDPCAPS_ALLOW256 플래그를 지정해, 이러한 엔트리를 이용하는 것을 요구하지 않는 경우에 한한다.

팔레트 엔트리를 취득하려면 ,IDirectDrawPalette::GetEntries 메소드를 사용한다. 엔트리를 변경하려면 ,IDirectDrawPalette::SetEntries 메소드를 사용한다.

SDK 의 Ddutil.cpp 소스 파일에는, 팔레트와 함께 작용하기 위해서 어플리케이션으로 정의된 편리한 함수가 포함되어 있다. 상세한 것에 대하여는, 소스 파일의 DDLoadPalette 함수를 참조할것.

[Visual Basic]

DirectDraw7.CreatePalette 메소드를 호출하는 것으로, 팔레트를 생성 할 수 있다. 이 메소드는,DirectDrawPalette 오브젝트를 돌려준다. 이 오브젝트의 메소드를 사용해, 팔레트 엔트리의 조작 및 오브젝트의 능력에 관한 정보의 취득을 할 수 있다.

표면의 DirectDrawSurface7.SetPalette 메소드를 호출하는 것으로, 표면에 팔레트를 추가할 수 있다. 1 개의 팔레트를 복수의 표면에 적용할 수가 있다.

DirectDrawPalette 오브젝트는, 8 비트 팔레트의 엔트리 0, 및 엔트리 255 를 취득한다. 다만, DDPCAPS_ALLOW256 플래그를 지정해, 이러한 엔트리를 이용하는 것을 요구하지 않는 경우에 한한다.

팔레트 엔트리를 취득하려면 ,DirectDrawPalette.GetEntries 메소드를 사용한다. 엔트리를 변경하려면 ,DirectDrawPalette.SetEntries 메소드를 사용한다.


팔레트 타입

DirectDraw 는, 1 비트 (2 엔트리), 2 비트 (4 엔트리), 4 비트 (16 엔트리), 및 8 비트 (256 엔트리) 팔레트를 지원 한다. 팔레트는, 픽셀 포맷이 적합하는 표면인 만큼 Attach 할 수가 있다. 예를 들어, DDPCAPS_1BIT 플래그를 지정해 생성 된 2 엔트리 팔레트는, DDPF_PALETTEINDEXED1 플래그를 지정해 생성 된 1 비트 표면인 만큼 Attach 할 수가 있다.

게다가인덱스 팔레트 로 불리는 컬러 테이블을 전혀 포함하지 않는 팔레트도 생성 할 수 있다. 인덱스 팔레트에는, 컬러 테이블 대신에, 다른 팔레트의 컬러 테이블에 있어서의 위치를 나타내는 인덱스값이 포함된다.

[C++]

인덱스 팔레트를 생성 하려면 ,IDirectDraw7::CreatePalette 메소드를 호출하면나무에, DDPCAPS_8BITENTRIES 플래그를 지정한다. 예를 들어, 4 비트의 인덱스 팔레트를 생성 하려면 , DDPCAPS_4BIT 및 DDPCAPS_8BITENTRIES 의 양쪽 모두의 플래그를 지정한다. 또, 인덱스 팔레트를 생성 하는 경우,PALTTEENTRY 구조체의 배열에의 포인터보다, 바이트 배열에의 포인터를 건네준다. IDirectDraw7::CreatePalette 메소드를 사용하는 경우는,LPPALETTEENTRY 형에 바이트의 배열에의 포인터를 캐스트 해야 한다.

블리트 처리중에, DirectDraw 는 인덱스 팔레트 엔트리를 역참조하지 않는 것에 주의 해야 한다.

[Visual Basic]

인덱스 팔레트를 생성 하려면 ,DirectDraw7.CreatePalette 메소드를 호출하면나무에, DDPCAPS_8BITENTRIES 플래그를 지정한다. 예를 들어, 4 비트의 인덱스 팔레트를 생성 하려면 , DDPCAPS_4BIT 및 DDPCAPS_8BITENTRIES 의 양쪽 모두의 플래그를 지정한다. 또, 인덱스 팔레트를 생성 하는 경우,PALETTEENTRY 형의 배열보다, 바이트 배열을 건네준다.


비프라이머리 표면에서의 팔레트의 설정

팔레트는, 모든 팔레트화 표면 (프라이머리,백 버퍼, 오프 스크린 프레인, 텍스쳐 맵)에 Attach 할 수가 있지만, 시스템 팔레트에 영향을 주는 것은,프라이머리 표면 에 Attach 된 팔레트 뿐이다. 주의해야 할 중요한 점은, DirectDraw 블리트가 색변환을 실행하지 않는다고 하는 것이다. 즉, 블리트의 전송원 혹은 목적지 표면에 Attach 된 모든 팔레트가, 무시되는 것이다.

비프라이머리 표면 팔레트는, Direct3D 어플리케이션에 의한 사용을 목적으로 하고 있다.


팔레트의 공유

[C++]

팔레트는, 복수의 표면간에 공유할 수가 있다. 동일한 팔레트를 플립핑 체인의프런트 버퍼와백 버퍼로 설정하거나 복수의 텍스쳐 표면간에 공유할 수가 있다. 어플리케이션이 IDirectDrawSurface7::SetPalette 메소드를 사용해 표면에 팔레트를 Attach 하면, 그 표면은 팔레트의참조 카운트를 인크리먼트(increment) 한다. 참조 카운트가 0 이 되면(자), 표면은 Attach 상태의 팔레트의 참조 카운트를 감소 한다. 게다가 팔레트 인터페이스 포인터를 NULL 로 해 IDirectDrawSurface7::SetPalette 를 사용하는 것으로, 표면으로부터 팔레트의 Attach를 해제하는 경우, 표면 팔레트의 참조 카운트는 감소 된다.

주 ： 같은 팔레트의 동일 표면상에서 IDirectDrawSurface7::SetPalette 를 몇회인가 계속해 호출하는 경우, 그 팔레트의 참조 카운트는 1 회 밖에 인크리먼트(increment) 되지 않는다. 반복의 호출은, 팔레트의 참조 카운트에 영향을 주지 않기 때문에이다.

[Visual Basic]

팔레트는, 복수의 표면간에 공유할 수가 있다. 동일한 팔레트를 플립핑 체인의프런트 버퍼와백 버퍼로 설정하거나 복수의 텍스쳐 표면간에 공유할 수가 있다.


팔레트 애니메이션

팔레트 애니메이션이란, 표면을 표시했을 때에, 그 자체의 외관을 변경하기 위해서 표면의 팔레트를 수정하는 프로세스를 가리킨다. 반복 팔레트를 변경하는 것으로써, 실제로 표면의 컨텐츠를 변경하지 않아도, 표면이 변경한 것처럼 보이게 할 수가 있다. 이 때문에, 팔레트 애니메이션에서는, 컨텐츠를 바꾸지 않고 매우 몇 안 되는 오버헤드로, 표면의 외관을 수정하는 수단을 제공한다.

간단하게 팔레트 애니메이션을 실현하려면 , 이하의 2 개의 방법이 있다.

  • 단일 팔레트내에서의 팔레트 엔트리의 수정
  • 복수 팔레트간의 변환
[C++]

최초의 방법을 사용하는 경우, 애니메이션 하려고 하는 색에 대응하는 개별의 팔레트 엔트리를 변경해, 그리고 IDirectDrawPalette::SetEntries 메소드를 1 회 호출해 엔트리를 리셋 한다.

2 번째의 방법은, 2 개(살) 이상의 DirectDrawPalette 오브젝트가 필요하게 된다. 이 방법을 사용하는 경우,IDirectDrawSurface7::SetPalette 메소드를 호출해, 표면 오브젝트 마다 1 개의 팔레트 오브젝트를 Attach 하면서, 애니메이션을 실행한다.

어느 쪽의 방법도 하드웨어 의존은 아니기 때문에, 어플리케이션에 최적으로 기능 하면 생각되는 (분)편을 선택 하면 좋다.

특정의 정보나 팔레트 애니메이션의 실현예에 대해서는, 「튜토리얼 5 : 팔레트의 동적 변경」을 참조할것.

[Visual Basic]

최초의 방법을 사용하는 경우, 애니메이션 하려고 하는 색에 대응하는 개별의 팔레트 엔트리를 변경해, 그리고 DirectDrawPalette.SetEntries 메소드를 1 회 호출해 엔트리를 리셋 한다.

2 번째의 방법은, 2 개(살) 이상의 DirectDrawPalette 오브젝트가 필요하게 된다. 이 방법을 사용하는 경우,DirectDrawSurface7.SetPalette 메소드를 호출해, 표면 오브젝트 마다 1 개의 팔레트 오브젝트를 Attach 하면서, 애니메이션을 실행한다.

어느 쪽의 방법도 하드웨어 의존은 아니기 때문에, 어플리케이션에 최적으로 기능 하면 생각되는 (분)편을 선택 하면 좋다.


클립퍼

여기에서는, DirectDrawClipper 오브젝트에 대해 설명한다. 다음의 항목에 대해 기술한다.

  • 클립퍼란?
  • 클립 리스트
  • DirectDrawClipper 오브젝트의 공유
  • 비의존의 DirectDrawClipper 오브젝트
  • CoCreateInstance 를 이용한 DirectDrawClipper 오브젝트의 생성
  • 시스템 커서에서의 클립퍼의 사용
  • 멀티 윈도우에서의 클립퍼의 사용


클립퍼란?

클립퍼혹은 DirectDrawClipper 오브젝트에 의해, 경계 직사각형 또는 몇개의 경계 직사각형의 리스트로 나타나는, 표면의 선택한 부분을 블리트 할 수가 있다 ( 「클립 리스트」를 참조할것).

클립퍼의 일반적인 사용은, 스크린 또는 윈도우의 경계를 정의하는 것이다. 예를 들어, 스프라이트가 스크린의 인연으로부터 들어 오는 것 같은 표시에 대해 생각해 본다. 스프라이트가 스크린상에 돌연 나타나는 것이 아니라, 매끄럽게 (인연으로부터) 보여 오도록(듯이) 한다. 클립퍼 오브젝트가 없으면 DirectDraw 에 의해 전스프라이트를 블리트 할 수 없다. 이것은, 스프라이트의 일부가 목적지 표면의 외측에 배치되는 경우가 있기 때문에 있다. 목적지 표면 버퍼에 스프라이트의 픽셀값을 연속해 카피하는 것은, 잘못한 표시나 메모리 액세스 장해의 원인이 되는 일이 있다. 클립 리스트로서의 스크린 직사각형이 있는 클립퍼에 의해, DirectDraw 는 블리트를 실행하는 것 같은 스트라이프의 트림 방법을 알 수 있어, 가시 부분만큼이 카피된다.

다음의 그림으로 이 타입의 클리핑을 나타낸다.

또, 클립퍼 오브젝트를 사용하면(자), 목적지 표면내가 있는 영역을 쓰기 가능으로서 지정할 수 있다. DirectDraw 는, 지정한 클리핑 직사각형의 밖에 있는 픽셀을 보호하면서, 이러한 영역의 블리트 처리를 클립 한다.

다음의 그림으로 이 클립퍼의 사용에 대해 가리킨다.


클립 리스트

[C++]

클립 리스트는, 픽셀 좌표마다의 1 개 이상의 RECT 구조체로부터 완성된다. DirectDraw 는, 모든 표면에 Attach 되는 DirectDrawClipper 오브젝트를 사용해 클립 리스트를 관리한다.

IDirectDrawSurface7::Blt 메소드는, 클립 리스트의 직사각형인 만큼 데이터를 카피한다. 예를 들어, 표면의 우상의 부분이 클립 리스트의 직사각형에 의해 배제되어 어플리케이션이 클립 된 표면의 전영역에 블리트 했을 경우, DirectDraw 는 2 개의 블리트를 효과적으로 실행한다. 다음에 나타내는 그림과 같이, 1 개(살)은 표면의 맨 왼쪽 위쪽, 이제(벌써) 1 개(살)은 표면의 하반신이다.

[Visual Basic]

클립 리스트는, 픽셀 좌표마다의 1 개 이상의 RECT 형으로부터 완성된다. DirectDraw 는, 모든 표면에 Attach 되는 DirectDrawClipper 오브젝트를 사용해 클립 리스트를 관리한다.

DirectDrawSurface7.Blt 메소드는, 클립 리스트의 직사각형인 만큼 데이터를 카피한다. 예를 들어, 표면의 우상의 부분이 클립 리스트의 직사각형에 의해 배제되어 어플리케이션이 클립 된 표면의 전영역에 블리트 했을 경우, DirectDraw 는 2 개의 블리트를 효과적으로 실행한다. 다음에 나타내는 그림과 같이, 1 개(살)은 표면의 맨 왼쪽 위쪽, 이제(벌써) 1 개(살)은 표면의 하반신이다.

표면의 클립 리스트는 수동으로 관리할 수 있다. 또는,프라이머리 표면 에 대해서는 DirectDraw 가 자동적으로 클립 리스트를 관리한다.

[C++]

클립 리스트를 각자 관리하려면 ,RGNDATA 구조체의 폼에 직사각형의 리스트를 생성 해, 이것을 IDirectDrawClipper::SetClipList 메소드에 건네준다.

프라이머리 표면에 대한 클립 리스트를 DirectDraw 로 관리하려면 , 타겟 윈도우의 핸들을 지정하는 IDirectDrawClipper::SetHWnd 메소드를 호출해, 윈도우 (풀 스크린 윈도우에서도)에 클립퍼를 Attach 한다. 이것보다, 클리핑 영역을 윈도우의 클라이언트 영역으로 설정할 수 있어 윈도우의 사이즈 변경이나 커버의 유무에 의해 클립 리스트가 자동적으로 갱신된 것을 확인할 수 있다.

[Visual Basic]

클립 리스트를 각자 관리하려면 ,RECT 형의 배열의 폼에 직사각형의 리스트를 생성 해,DirectDrawClipper.SetClipList 메소드에 건네준다.

프라이머리 표면에 대한 클립 리스트를 DirectDraw 로 관리하려면 , 타겟 윈도우의 핸들을 지정하는 DirectDrawClipper.SetHWnd 메소드를 호출해, 윈도우 (풀 스크린 윈도우에서도)에 클립퍼를 Attach 한다. 이것보다, 클리핑 영역을 윈도우의 클라이언트 영역으로 설정할 수 있어 윈도우의 사이즈 변경이나 커버의 유무에 의해 클립 리스트가 자동적으로 갱신된 것을 확인할 수 있다.

윈도우 핸들을 이용해 클립퍼를 설정하는 경우, 추가의 직사각형을 설정할 수 없다.

오버레이 하드웨어가 클리핑을 지원 해, 한편목적지 컬러 키잉 이 액티브하지 않은 경우에만, 오버레이 표면에 대한 클리핑이 지원 된다.


DirectDrawClipper 오브젝트의 공유

[C++]

DirectDrawClipper 오브젝트는, 복수의 표면간에 공유할 수가 있다. 예를 들어, 플립핑 체인의프런트 버퍼 및백 버퍼의 양쪽 모두에, 동일한 DirectDrawClipper 오브젝트를 설정할 수가 있다. 어플리케이션이 IDirectDrawSurface7::SetClipper 메소드를 사용해 표면에 DirectDrawClipper 오브젝트를 Attach 하면, 표면은 그 오브젝트의참조 카운트 를 인크리먼트(increment) 한다. 표면의 참조 카운트가 0 이 되면(자), 표면은 Attach 상태의 DirectDrawClipper 오브젝트의 참조 카운트를 감소 한다. 게다가 클립퍼 인터페이스 포인터를 NULL 로 해 IDirectDrawSurface7::SetClipper 를 호출하는 것으로, DirectDrawClipper 오브젝트가 표면으로부터 Attach를 해제하는 경우, 표면의 DirectDrawClipper 오브젝트의 참조 카운트는 감소 된다.

주 ： 동일한 표면상에서 동일한 DirectDrawClipper 오브젝트에 대해서 IDirectDrawSurface7::SetClipper 를 몇번이나 계속해 호출하는 경우, 그 오브젝트의 참조 카운트는 1 회만 인크리먼트(increment) 된다. 반복의 호출은, 오브젝트의 참조 카운트에 영향을 주지 않기 때문에이다.

[Visual Basic]

DirectDrawClipper 오브젝트는, 복수의 표면간에 공유할 수가 있다. 예를 들어, 플립핑 체인의프런트 버퍼 및백 버퍼의 양쪽 모두에, 동일한 DirectDrawClipper 오브젝트를 설정할 수가 있다. 어플리케이션이 DirectDrawSurface7.SetClipper 메소드를 사용해 표면에 DirectDrawClipper 오브젝트를 Attach 하면, 표면은 그 오브젝트의참조 카운트 를 인크리먼트(increment) 한다.


비의존의 DirectDrawClipper 오브젝트

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

모든 특정의 DirectDraw 오브젝트에도 직접 소유되지 않는 DirectDrawClipper 오브젝트를 생성 할 수가 있다. 이러한 DirectDrawClipper 오브젝트는, 복수의 DirectDraw 오브젝트로 공유할 수 있다. 드라이버비의존의 DirectDrawClipper 오브젝트는, 새로운 DirectDrawCreateClipper 함수를 사용해 생성 한다. 어플리케이션은, DirectDraw 오브젝트를 생성 하기 전에, 이 함수를 호출할 수가 있다.

DirectDraw 오브젝트에서는 이러한 DirectDrawClipper 오브젝트를 소유하지 않기 때문에, 어플리케이션의 오브젝트가 릴리즈 되어도 자동적으로는 릴리즈 되지 않는다. 어플리케이션으로 명시적으로 이러한 DirectDrawClipper 오브젝트를 릴리즈 하지 않는 경우, DirectDraw 가 어플리케이션의 종료시에 이러한 오브젝트를 릴리즈 한다.

IDirectDraw7::CreateClipper 메소드를 사용해 DirectDrawClipper 오브젝트를 생성 할 수도 있다. 이러한 DirectDrawClipper 오브젝트는, 이러한 오브젝트를 생성 한 DirectDraw 오브젝트가 릴리즈 되었을 때에, 자동적으로 릴리즈 된다.


CoCreateInstance 를 이용한 DirectDrawClipper 오브젝트의 생성

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

DirectDrawClipper 오브젝트는, COM 준거의 클래스 팩토리를 완전하게 지원 한다. 게다가 표준적인 DirectDrawCreateClipper 함수와 IDirectDraw7::CreateClipper 메소드를 사용하는 것으로, 클래스 팩토리를 취득하는 CoGetClassObject 함수를 호출하고 나서 CoCreateInstance 함수를 호출하든가, 혹은 직접 CoCreateInstance 를 호출하는 것으로, DirectDrawClipper 오브젝트를 생성 할 수 있다. 다음의 예로,CoCreateInstance 와 IDirectDrawClipper::Initialize 메소드를 사용해 DirectDrawClipper 오브젝트를 생성 하는 방법을 나타낸다.

ddrval = CoCreateInstance(&CLSID_DirectDrawClipper,
    NULL, CLSCTX_ALL, &IID_IDirectDrawClipper, &lpClipper);
if (! FAILED(ddrval))
    ddrval = IDirectDrawClipper_Initialize(lpClipper,
        lpDD, 0UL);

CoCreateInstance 의 호출에서는, 최초의 파라미터 CLSID_DirectDrawClipper 가 DirectDrawClipper 오브젝트 클래스의 클래스 식별자가 된다. IID_IDirectDrawClipper 파라미터는 현재 지원 되고 있는 인터페이스를 식별해,lpClipper 파라미터는 취득된 DirectDrawClipper 오브젝트에의 포인터를 가리킨다.

어플리케이션은,IDirectDrawClipper::Initialize 메소드를 사용해 클래스 팩토리 기구에 의해 생성 된 DirectDrawClipper 오브젝트를, 그것을 사용할 수 있게 되기 전에 초기화하지 않으면 안 된다. 0UL 의 값은 dwFlags 파라미터이며, 이 경우에는 플래그가 현재 지원되어 있지 않기 때문에, 그 값은 0 이 된다. 여기서 가리킨 예에서는,lpDD 는 DirectDrawClipper 오브젝트를 소유하는 DirectDraw 오브젝트이다. 다만, 대신에 NULL 를 지정했을 경우는, 독립한 DirectDrawClipper 오브젝트가 생성 된다 (이것은,DirectDrawCreateClipper 함수를 사용해 DirectDrawClipper 오브젝트를 생성 했을 경우와 같다).

어플리케이션을 종료하기 전에,CoUninitialize 함수로 COM 라이브러리를 닫는 것.


시스템 커서에서의 클립퍼의 사용

DirectDraw 어플리케이션에서는, 유저가 마우스를 사용해 안내할 수 있는 방법을 제공하지 않으면 안 되는 경우가 있다. 페이지 플립핑을 사용하는 풀 스크린 배타 모드의 어플리케이션에서는, 유일, 수동으로 마우스 커서를 실현하는 방법이 있다. 즉, DirectInput® 또는 Windows 마우스 메세지에 응답하는 것으로써, 디바이스로부터 취득되는 데이터에 근거해 스프라이트를 이동하는 방법이다. 다만, 페이지 플립핑을 사용하지 않는 모든 어플리케이션에서는, 여전히 시스템의 마우스 커서 지원을 사용할 수 있다.

시스템 마우스 커서를 사용하는 경우, 프라이머리 표면의 일부에 블리트를 실시하면, 그래픽스의 이상하게 골치를 썩이는 일이 있다. 이 이상은, 시스템으로 남겨졌는지와 같이 보이는 마우스 커서의 일부로서 나타난다.

[C++]

DirectDrawClipper 오브젝트는, 블리트 처리중에 마우스 커서의 이미지가 " 방해가 되는 " 일을 저지하는 것으로, 이러한 이상이 나타나지 않게 할 수 있다. 이것은 비교적 간단하게 실현될 수 있다. 그 때문에(위해)는,IDirectDraw7::CreateClipper 메소드를 호출해, DirectDrawClipper 오브젝트를 생성 한다. 그리고,IDirectDrawClipper::SetHWnd 메소드를 이용해, 클립퍼에 어플리케이션의 윈도우 핸들을 할당한다. 클립퍼가 Attach 되면(자),IDirectDrawSurface7::Blt 메소드를 이용해 프라이머리 표면으로 실행하는 반복의 블리트에서는, 이상이 나타나지 않게 된다.

IDirectDrawSurface7::BltFast 메소드, 그리고,IDirectDrawSurface,IDirectDrawSurface2, 및 IDirectDrawSurface3 인터페이스에 대응하는 메소드는, 클립퍼의 Attach 상태의 표면에 작용하지 않는 것에 주의한다.

[Visual Basic]

DirectDrawClipper 오브젝트는, 블리트 처리중에 마우스 커서의 이미지가 " 방해가 되는 " 일을 저지하는 것으로, 이러한 이상이 나타나지 않게 할 수 있다. 이것은 비교적 간단하게 실현될 수 있다. 그 때문에(위해)는,DirectDraw7.CreateClipper 메소드를 호출해, DirectDrawClipper 오브젝트를 생성 한다. 그리고,DirectDrawClipper.SetHWnd 메소드를 이용해, 클립퍼에 어플리케이션의 윈도우 핸들을 할당한다. 클립퍼가 Attach 되면(자),DirectDrawSurface7.Blt 메소드를 이용해 프라이머리 표면으로 실행하는 반복의 블리트에서는, 이상이 나타나지 않게 된다.


멀티 윈도우에서의 클립퍼의 사용

DirectDrawClipper 오브젝트를 사용해, 표준 협조 레벨로 실행하는 어플리케이션에 의해 생성 된 복수의 윈도우에 블리트 할 수가 있다.

[C++]

이 때문에는, 프라이머리 표면 첨부의 1 개의 DirectDraw 오브젝트를 생성 한다. 그 후, DirectDrawClipper 오브젝트를 생성 해,IDirectDrawSurface7::SetClipper 메소드를 호출해 프라이머리 표면에 할당한다. 윈도우의 클라이언트 영역만을 블리트 하려면 , 프라이머리 표면에 블리트 하기 전에,IDirectDrawClipper::SetHWnd 메소드를 호출해 윈도우의 클라이언트 영역에 클립퍼를 설정한다. 다른 윈도우의 클라이언트 영역에 블리트 하지 않으면 안 될 때는, 항상 새로운 타겟 윈도우 핸들을 이용해 IDirectDrawClipper::SetHWnd 메소드를 재차 호출한다.

[Visual Basic]

이 때문에는, 프라이머리 표면 첨부의 1 개의 DirectDraw 오브젝트를 생성 한다. 그 후, DirectDrawClipper 오브젝트를 생성 해,DirectDrawSurface7.SetClipper 메소드를 호출해 프라이머리 표면에 할당한다. 윈도우의 클라이언트 영역만을 블리트 하려면 , 프라이머리 표면을 블리트 하기 전에,DirectDrawClipper.SetHWnd 메소드를 호출해 윈도우의 클라이언트 영역에 클립퍼를 설정한다. 다른 윈도우의 클라이언트 영역에 블리트 하지 않으면 안 될 때는, 항상 새로운 타겟 윈도우 핸들을 이용해 DirectDrawClipper.SetHWnd 메소드를 재차 호출한다.

서로의 프라이머리 표면에 블리트 하는 복수의 DirectDraw 오브젝트를 생성 하는 것은, 권유받지 않는다. 전술의 기술로, 1 개의 DirectDraw 오브젝트로 복수의 클라이언트 영역에 블리트 하는 효율적으로 확실한 방법을 제공한다.


멀티 모니터 시스템

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

Windows 98 으로 Windows NT 2000 에서는, 1 개의 시스템상에서 복수의 디스플레이 디바이스와 모니터를 지원 한다. 멀티 모니터 아키텍쳐 (보통은 "MultiMon" 로 불린다)는, 2 개(살) 이상의 디스플레이 디바이스와 모니터로부터 디스플레이 영역을 사용하는 operating system를 가능하게 해, 단일의 논리적인 데스크탑을 생성 한다. 예를 들어, 2 개의 모니터의 MultiMon 시스템에서는, 유저가 어느 쪽인가의 모니터상에 어플리케이션을 표시할 수 있거나 1 개의 모니터로부터 이제(벌써) 1 개의 모니터에 윈도우를 드러그 할 수도 있다. DirectDraw 에서는 이 아키텍쳐를 지원 해, 어플리케이션은 MultiMon 시스템을 이용한 복수의 디스플레이 디바이스 위에의 하드웨어에 직접 액세스 할 수 있다.

주 ： 붉나무 바이스상에서 생성 되거나 프라이머리 표면에 직접 렌더링 되지 않는 이상 풀 스크린이 아닌 DirectDraw 어플리케이션은 MultiMon 와 함께 자동적으로 기능해, 유저는 있는 모니터로부터 다른 모니터에 윈도우를 드러그 할 수 있다. 다만, 윈도우가 완전하게 프라이머리 디스플레이내에 있는 경우만, DirectDraw 는 하드웨어 가속기를 이용한다. DirectDraw 의 윈도우 어플리케이션에서는, 각 모니터에 대해서 다른 DirectDraw 오브젝트와 표면을 유지해, MultiMon 에 대해서 개별적으로 설계하는 것을 권한다. 상세한 것에 대하여는, 「MultiMon 시스템의 디바이스와 가속기」를 참조할것.

여기에서는, 멀티 모니터를 지원 하는 시스템상에서의 DirectDraw 의 사용에 대해 설명한다. 다음의 항목에 대해 기술한다.

  • MultiMon 시스템에 있어서의 디바이스의 열거
  • 멀티 모니터의 DirectDraw 오브젝트
  • 포커스 윈도우와 디바이스 윈도우
  • MultiMon 시스템의 디바이스와 가속기
  • MultiMon 에 의한 풀 스크린 DirectDraw 어플리케이션의 디버그

DirectX SDK 에 있는 Multimon.h 헤더 파일에 의해, Windows 98 의 멀티 모니터 함수를 기술한 코드가, MultiMon 를 지원 하지 않는 operating system상에서 컴파일 및 실행할 수 있다.

다음의 샘플 어플리케이션에서는, DirectDraw 의 MultiMon 의 이행에 대해 설명한다.

  • Multimon 샘플


MultiMon 시스템에 있어서의 디바이스의 열거

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

DirectDrawEnumerateEx 함수를 사용 하면, 멀티 모니터를 이용한 시스템 위에의 디바이스를 열거할 수 있다. 멀티 모니터는, 열거되어야 할 DirectDraw 디바이스의 타입을 결정하는 플래그를 지정한다. 이 함수에서는, 열거된 디바이스 마다 어플리케이션 정의된 DDEnumCallbackEx 함수를 호출한다.

DirectDrawEnumerateEx 함수는, Windows 98, 및 Windows NT 2000 으로 그 이후의 operating system로 지원 된다. 또, DirectX 6.0 이후의 버젼으로 컴파일 된 어플리케이션은, Ddraw.lib 로 이용할 수 있다. 함수에 정적으로 링크하는 어플리케이션은 항상 DirectX 6.0 이후의 버젼으로 실행해, 항상 Windows 98 및 Windows NT 2000 이후의 DirectX 의 모든 버젼으로 실행한다. Windows 95 의 DirectX 의 이전의 버젼으로 실행하는 경우, 이러한 어플리케이션은 실패한다.

어플리케이션에 DirectX 5.0 이전의 버젼의 실행이 필요한 경우,DirectDrawEnumerateEx 가 이용 가능하면 참조를 위해서(때문에) GetProcAddress 를 사용해야 한다. 다음에 이 방법에 대한 예를 나타낸다.

    HINSTANCE h = LoadLibrary("ddraw.dll");

// ddraw.dll 가 검색 패스에 존재하지 않는 경우,
// 아마 DirectX 는 인스톨 되지 않기 때문에, 실패한다.
    if (! h)
        return FALSE;

// 취득하는 함수의 버젼을 모르면 안 된다
// 일로 주의한다 (다음에 나타내는 텍스트를 참조).
// 이 예에서는, ANSI 버젼을 사용한다.
    LPDIRECTDRAWENUMERATEEX lpDDEnumEx;
    lpDDEnumEx = (LPDIRECTDRAWENUMERATEEX) GetProcAddress(h,"DirectDrawEnumerateExA");

// 함수가 있는 경우, 그 함수를 호출해,
// 데스크탑에 Attach 되는 모든 디스플레이 디바이스와
// 비디스플레이 DirectDraw 디바이스를 열거한다.
    if (lpDDEnumEx)
        lpDDEnumEx(Callback, NULL,
            DDENUM_ATTACHEDSECONDARYDEVICES |
            DDENUM_NONDISPLAYDEVICES
            );
    else
    {
        /*
* DirectDraw 의 낡은 버젼으로 실행할 필요가 있다.
* 따라서 MultiMon 는 지원 되지 않는다. Fall back on
* 단일의 모니터 시스템 위에의 표준적인 디바이스를 열거하려면 ,
* DirectDrawEnumerate 에 의지한다.
         */
        DirectDrawEnumerate(OldCallback, NULL);

/* OldCallback 함수를 DDEnumCallbackEx 에 대한다
* 래퍼와 하면 편리한 것으로 주의한다.
         *
* 이러한 함수는 다음과 같이 한다.
* BOOL FAR PASCAL OldCallback (GUID FAR *lpGUID,
*        LPSTR pDesc,
*        LPSTR pName,
*        LPVOID pContext)
         *    {
*   return Callback (lpGUID, pDesc, pName, pContext, NULL) ;
         *    }
         */
    }

// LoadLibrary ()의 호출로 라이브러리가 로드 되고 경우,
// 그 라이브러리를 활용하려면 ,// FreeLibrary ()를 사용하지 않으면 안 된다.
    FreeLibrary(h);

위의예에서는, 실행시나 로드시에 Ddraw.dll 에 링크하는 어플리케이션 대해 작용한다.

DirectDrawEnumerateEx 함수의 ANSI, 또는 Unicode 버젼의 어느 쪽인가의 주소를 취득하지 않으면 안 되는 것에 주의한다. 이 함수는, 어플리케이션으로 사용하는 캐릭터 라인형에 의존한다. 대응하는 콜백 함수를 선언하는 경우, 캐릭터 라인의 파라미터에 대한 LPTSTR 데이터형을 사용한다. _UNICODE 심볼이나 ANSI 캐릭터 라인의 어느 쪽인지를 선언하는 경우,LPTSTR 데이터형은 Unicode 캐릭터 라인을 사용하기 위해서 컴파일 한다. LPTSTR 데이터형을 사용하는 것으로써, 어플리케이션으로 사용하는 캐릭터 라인형에 관계없이, 그 함수는 정확하게 컴파일 해야 한다.


멀티 모니터의 DirectDraw 오브젝트

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

눌이나 디폴트의 디스플레이 드라이버에 대해서 기술된 DirectDraw 의 윈도우 어플리케이션은, MultiMon 상에서 기능한다. 그러나, MultiMon 를 위해서(때문에) 최적화되는 어플리케이션에서는, 열거 콜백에 돌려주어지는 GUID 를 사용해, 각 디바이스에 대해서 다른 DirectDraw 오브젝트를 생성 한다 ( 「MultiMon 시스템에 있어서의 디바이스의 열거」를 참조할것).

DirectDraw 오브젝트의 생성시에 어플리케이션으로 GUID 를 지정했는지 NULL 를 지정했는지를 따라, MultiMon 의 동작이 바뀌는 경우가 있다. 가장 알기 쉬운 예로서는, 어플리케이션으로 NULL 를 지정했을 경우, DirectDraw 는 항상 커서를 프라이머리 모니터에 클립 한다.

MultiMon 시스템상에서 협조 레벨을 여러 차례 설정하는 것은 피하는 것. 풀 스크린으로부터 일반적인 모드로 전환하지 않으면 안 되는 경우는, 새로운 DirectDraw 오브젝트를 생성 하는 것이 최선이다.

ALT + TAB 키에 어플리케이션을 응답시키려면 , 어플리케이션이 디폴트의 윈도우 프로시저를 사용하지 않게 한다. 이 기능을 이용하려면 , SETFOCUS 메세지를 받아들일 때마다, 디바이스 윈도우가 포커스를 부모 윈도우로 변경해야 한다.

전 DirectDraw 오브젝트는 동시에 릴리즈 하는 것을 권한다. 세컨드리 디바이스나 복수의 디바이스만을 릴리즈 하는 경우, 프라이머리 디바이스는 원의 데스크탑 모드에 돌아오지만, 태스크바만은 재드로잉(Drawing) 되어 DirectDraw 의 프라이머리 표면은 존재한채로 있다. DirectDraw 오브젝트의 릴리즈 및 그 오브젝트의 재생성을 최초로 실시하지 말고, 이 표면에 드로잉(Drawing) 할 수 없다.


포커스 윈도우와 디바이스 윈도우

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

풀 스크린 배타 모드로 1 개 또는 그 이상의 모니터를 사용하는 각 DirectDraw 어플리케이션에는, 키보드 입력을 받는 윈도우가 되는 단일의포커스 윈도우가 필요하다.

풀 스크린 DirectDraw 표면을 보관 유지하는 각 디바이스는, DirectDraw 오브젝트와디바이스 윈도우에 의해 나타내지지 않으면 안 된다. 디바이스 윈도우는, 윈도우에 적합하도록(듯이) 사이즈 변경되어 다른 모든 윈도우상에 배치되는 윈도우이다.

단일의 모니터 어플리케이션에는, 디바이스와 포커스 윈도우간의 구별은 없다. 이것들은 1 개 한편 같다. 다만, 멀티 모니터 어플리케이션에는 각 모니터용의 디바이스 윈도우를 설정할 필요가 있어, 각 DirectDraw 오브젝트에 어플리케이션의 포커스 윈도우를 통지시키지 않으면 안 된다. 또, 포커스 윈도우는, 1 개의 모니터에 대한 디바이스 윈도우라고 해도 도움이 된다. 다른 디바이스 윈도우는 포커스 윈도우의 아이가 되기 (위해)때문에, 유저가 자식 윈도우의 1 개를 클릭하는 경우, 어플리케이션은 최소화하지 않는다.

주 : MultiMon 어플리케이션으로 복수의 배타 윈도우를 생성 하는 경우, 입력초점 윈도우를 디바이스의 부모 윈도우로서 지정할 필요가 있다. 그렇게 하지 않으면 어플리케이션은 적절한 입력을 취득할 수 없다.

참조

  • 포커스 윈도우의 설정
  • 디바이스 윈도우의 설정


포커스 윈도우의 설정

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

포커스 윈도우를 설정하려면 , 각 DirectDraw 오브젝트에 대해서 IDirectDraw7::SetCooperativeLevel 메소드를 호출한다. 윈도우 핸들 (보통의 어플리케이션 윈도우 핸들)에 건네주어, 다음에 나타내도록(듯이) DDSCL_SETFOCUSWINDOW 플래그를 설정한다.

/* lpDD 가 유효한 IDirectDraw 인터페이스 포인터이며,
hWnd 가 유효한 윈도우 핸들이라고 가정한다.  */

HRESULT ddrval = lpDD->SetCooperativeLevel( hWnd,
        DDSCL_SETFOCUSWINDOW );

포커스 윈도우는, 모든 디바이스에 대해서 같지 않으면 안 된다.


디바이스 윈도우의 설정

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

디바이스 윈도우를 설정하려면 ,2 방법의 방법이 있다.

  • 각자 윈도우를 생성 해, 그 핸들을 모니터를 나타내는 DirectDraw 오브젝트의 IDirectDraw7::SetCooperativeLevel 메소드에 DDSCL_SETDEVICEWINDOW, DDSCL_FULLSCREEN, 및 DDSCL_EXCLUSIVE 플래그를 설정해 건네준다. 이것은 풀 스크린 윈도우를 생성 해, 모니터에 대한 디바이스 윈도우로서 설정한다. 어플리케이션은 윈도우에 대한 마우스 메세지를 받아들인다. 윈도우의 파기는 적절한 때에 각자 실시한다. SetCooperativeLevel 에 건네주는 윈도우는, 포커스 윈도우 (같은 디바이스 위에의 경우인 만큼 가능), 또는 포커스 윈도우의 아이로 해야 한다.
  • DirectDraw 가 윈도우를 생성 한다. 포커스 윈도우 핸들을 SetCooperativeLevel 에 건네주어, DDSCL_CREATEDEVICEWINDOW, DDSCL_FULLSCREEN, 및 DDSCL_EXCLUSIVE 플래그를 설정한다. DirectDraw 에서는, 포커스 윈도우의 아이가 되는 디폴트의 디바이스 윈도우를 생성 한다. DirectDraw 에서는 이 윈도우를 관리해, 적절한 때에 파기한다. 어플리케이션에서는, 윈도우의 모든 마우스 메세지를 납득할 수 없다.

다음의 예에서는,lpDD 가 나타내는 DirectDraw 오브젝트에 대한 기존의 디바이스 윈도우를 설정한다.

/* lpDD 가 유효한 IDirectDraw 인터페이스 포인터이며,
hWnd 가 적절한 디바이스 윈도우에의 핸들이라고 가정한다.  */

HRESULT hr = lpDD->SetCooperativeLevel( hWnd,
        DDSCL_SETDEVICEWINDOW | DDSCL_EXCLUSIVE | DDSCL_FULLSCREEN );

다음의 예에서는, DirectDraw 가 생성 한 디폴트의 디바이스 윈도우를 설정한다. 이 경우,hWnd 는 기존의 포커스 윈도우에의 핸들이 된다.

HRESULT hr = lpDD->SetCooperativeLevel( hWnd,
        DDSCL_CREATEDEVICEWINDOW | DDSCL_EXCLUSIVE | DDSCL_FULLSCREEN );

포커스 윈도우는 디바이스 윈도우는 아니지만,SetCooperativeLevel 의 호출로 포커스 윈도우와 디바이스 윈도우의 양쪽 모두로서 윈도우를 설정할 수 없다. 최초로 포커스 윈도우로서 설정하고 나서, 디바이스 윈도우로서 설정한다. 다만, 같은 디바이스 위에의 포커스 윈도우와 디폴트의 디바이스 윈도우는,SetCooperativeLevel 의 호출로 설정할 수 있다. 다음의 예로 이 방법에 대해 가리킨다.

HRESULT hr = lpDD->SetCooperativeLevel(
        hwndFocus,
        DDSCL_SETFOCUSWINDOW | DDSCL_FULLSCREEN |
        DDSCL_EXCLUSIVE | DDSCL_CREATEDEVICEWINDOW);

이 예에서는, 기존의 윈도우 (아마 어플리케이션 윈도우)가 포커스 윈도우로서 설정되어 DirectDraw 가 디폴트의 디바이스 윈도우를 생성 한다.


MultiMon 시스템의 디바이스와 가속기

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

풀 스크린 배타 모드의 DirectDraw 오브젝트는, 프라이머리 디바이스 또는 세컨드리 디바이스상에서 실행할지 어떨지에 관계없이, 하드웨어 가속기를 이용한다. 다만, 디스플레이 디바이스 전역으로 그래픽스 연산을 스팬 하기 위해서, 빌트인 지원을 사용할 수 없다. 적절한 디바이스로 연산을 실행하는 것은, 어플리케이션으로 실시한다.

표준 협조 레벨이 설정되면(자), 윈도우가 프라이머리 디바이스의 전디스플레이 영역내의 경우만, DirectDraw 는 하드웨어 가속기를 사용한다. 윈도우가 2 개 이상의 모니터에 불규칙하게 퍼지는 경우, 모든 블리트가 열거되어 퍼포먼스가 꽤 저하한다. 하드웨어 버퍼에서는 다른 하드웨어가 제어하는 디스플레이 표면에 블리트 할 수 없기 때문에, 이것은 어쩔 수 없는 것이다.

붉나무 바이스에 대해서 DirectDraw 오브젝트를 생성 하는 한, NULL 가 lpGUID 파라미터로서 DirectDrawCreate 에게 건네진다. DirectDraw 에서는, 배치될지 어떨지에 관계없이 전윈도우에 블리트 한다. 다만, 디바이스가 실제의 GUID 로 생성 되는 경우 (클립퍼를 사용하는 경우), 프라이머리 표면의 인연에 교차하는 블리트 연산은 클립 되거나DDERR_INVALIDRECT 를 돌려주어 실패한다.

주 ： MultiMon 어플리케이션의 윈도우에 블리트 하고 있는 경우, 세컨드리 모니터의 논리적인 위치가 프라이머리 모니터의 좌측이 되면(자), 부의 좌표가 유효가 된다.

윈도우 MultiMon 어플리케이션의 퍼포먼스를 향상시키려면 , 각 디바이스에 대한 DirectDraw 를 생성 해, 각 디바이스에 병행해 오프 스크린 표면을 유지해, 각 디바이스에 상주하는 윈도우의 일부의 트랙을 유지해, 각 디바이스에 다른 블리트를 실행해야 한다.


MultiMon 에 의한 풀 스크린 DirectDraw 어플리케이션의 디버그

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

풀 스크린 DirectDraw 어플리케이션의 디버그중의 코드로부터 스텝 하는 리모트 디버그는 아니고, 멀티 모니터 시스템을 사용할 수 있다.

DirectDraw 출력을 위해서(때문에), 개발 환경과 세컨드리 모니터에 대한 프라이머리 모니터를 사용해야 한다. 또, Control Panel 의 DirectX 프로퍼티 시트로부터 설정하는 레지스트리도 변경할 수 있다. DirectDraw 페이지에서는,Advanced Settings 를 클릭해,Enable Multi-Monitor Debugging 체크 박스를 선택한다. 이 설정에 의해, DirectDraw 는 어플리케이션이 포커스를 잃었을 때에 최소화되는 것을 회피할 수 있다.

Windows 98 에서는, 표면의 락시에 코드로부터 스텝 할 수 없다. 상세한 것에 대하여는, 「표면 메모리에의 직접 액세스」를 참조할것.


DirectDraw 의 고도의 주제

여기에서는, DirectDraw 의 고도의 주제를 설명해, DirectDraw 의 개요를 보충한다. 다음의 항목에 대해 기술한다.

  • 모드 13 지원
  • DMA 지원의 이용
  • 윈도우 모드에서의 DirectDraw 팔레트의 사용
  • 비디오 포트
  • refresh rate의 열거
  • 플립핑과 블리트 상태 취득
  • 디스플레이 하드웨어 능력의 결정
  • 디스플레이 메모리에서의 비트 맵의 저장
  • 트리플 버퍼링
  • DirectDraw 어플리케이션과 윈도우 스타일
  • frame buffer의 색공간(color space)에의 트루 RGB 색의 적합
  • 풀 스크린 모드에서의 윈도우의 표시


모드 13 지원

여기에서는, DirectDraw 모드 13 그래픽스 모드 지원에 대해 설명한다. 다음의 항목에 대해 기술한다.

  • 모드 13 에 대해
  • 모드 13 의 설정
  • 모드 13 으로 표면 능력
  • 모드 13 의 사용


모드 13 에 대해

DirectDraw 는, 모드 13 (16 진 BIOS 모드 번호)의 이름으로 널리 알려지는 선형 플립핑 불능인 320 × 200 × 8 비트/픽셀 팔레트화 모드에의 액세스를 지원 한다. DirectDraw 는, 이 모드를 모드 X 모드와 같게 취급하지만, 모드 13 의 물리적 특징에 의해 부과되는 중요한 차이도 있다.


모드 13 의 설정

[C++]

모드 13 에는, 모드 X 와 같은 열거나 모드 설정 동작이 있다. DirectDraw 는, DDSCL_ALLOWMODEX 플래그가 IDirectDraw7::SetCooperativeLevel 메소드에게 건네졌을 경우에 한해, 모드 13 을 열거한다.

다른 모든 모드와 같게 모드 13 디스플레이 모드는 열거되지만,IDirectDraw7::EnumDisplayModes 를 호출하기 전에 표면 능력을 조사한다. 이것을 실시하려면 ,IDirectDraw7::GetCaps 를 호출해, 메소드가 돌아온 후에 DDSCAPS2 구조체의 DDSCAPS_STANDARDVGAMODE 플래그를 조사한다. 이 플래그가 존재하지 않으면, 모드 13 이 지원되어 있지 않다고 하는 것이어, DDEDM_STANDARDVGAMODES 플래그로 열거하려고 하는 것은 실패해,DDERR_INVALIDPARAMS 가 돌려주어진다.

현재,EnumDisplayModes 메소드는 새로운 열거 플래그 DDEDM_STANDARDVGAMODES 를 지원 한다. 이것에 의해, DirectDraw 는 320 × 200 × 8 모드 X 모드 외에 모드 13 을 열거할 수 있게 된다. 새로운 IDirectDraw7::SetDisplayMode 의 플래그로서 DDSDM_STANDARDVGAMODE 가 있어, 모드 13 을 320 × 200 × 8 모드 X 와 구별하기 위해서 건네주지 않으면 안 된다.

[Visual Basic]

모드 13 에는, 모드 X 와 같은 열거나 모드 설정 동작이 있다. DirectDraw 는, DDSCL_ALLOWMODEX 플래그가 DirectDraw7.SetCooperativeLevel 메소드에게 건네졌을 경우에 한해, 모드 13 을 열거한다.

다른 모든 모드와 같게 모드 13 디스플레이 모드는 열거되지만,DirectDraw7.GetDisplayModesEnum 를 호출하기 전에 표면 능력을 조사한다. 이것을 실시하려면 ,DirectDraw7.GetCaps 를 호출해, 메소드가 돌아온 후에 DDSCAPS2 형의 DDSCAPS_STANDARDVGAMODE 플래그를 조사한다. 이 플래그가 존재하지 않으면, 모드 13 이 지원되어 있지 않다고 하는 것이어, DDEDM_STANDARDVGAMODES 플래그로 열거하려고 하는 것은 실패해,DDERR_INVALIDPARAMS 가 돌려주어진다.

현재,GetDisplayModesEnum 메소드는 새로운 열거 플래그 DDEDM_STANDARDVGAMODES 를 지원 한다. 이것에 의해, DirectDraw 는 320 × 200 × 8 모드 X 모드 외에 모드 13 을 열거할 수 있게 된다. 새로운 DirectDraw7.SetDisplayMode 의 플래그로서 DDSDM_STANDARDVGAMODE 가 있어, 모드 13 을 320 × 200 × 8 모드 X 와 구별하기 위해서 건네주지 않으면 안 된다.

비디오 카드에 따라서는, 선형 가속기 320 × 200 × 8 모드가 제공되고 있는 것에 주의한다. 그러한 카드로는, DirectDraw 가 모드 13 을 열거하지 않고 , 대신으로서 선형 모드를 열거한다. 이 경우,SetDisplayMode 에 DDSDM_STANDARDVGAMODE 플래그를 건네주어 모드 13 을 설정 하면, 이 메소드는 성공하지만, 선형 모드가 사용되게 된다. 이것은, 선형저해상도 모드가 모드 X 모드를 오버라이드(override) 하는 방법으로 유사한다.


모드 13 으로 표면 능력

[C++]

DirectDraw 가 어플리케이션의 EnumModesCallback 콜백 함수를 호출하면, 관련하는 DDSURFACEDESC 나 DDSURFACEDESC2 구조체의 ddsCaps 멤버에는, 열거되고 있는 모드를 반영하는 플래그가 포함된다. 모드 X 에 대해서는 DDSCAPS_MODEX, 모드 13 에 대해서는 DDSCAPS_STANDARDVGAMODE 가 된다. 이러한 플래그는, 서로 배타이다. 이것들 비트가 양쪽 모두 설정되지 않은 경우는, 모드는 선형 가속기 모드라는 것이 된다. 이것은,IDirectDraw7::GetDisplayMode 메소드로부터 취득된 플래그에도 들어맞는다.

[Visual Basic]

DirectDraw 가 어플리케이션의 DirectDraw7.GetDisplayModesEnum 메소드를 호출하면, 관련하는 DDSURFACEDESC2 형의 ddsCaps 멤버에는, 열거되고 있는 모드를 반영하는 플래그가 포함된다. 모드 X 에 대해서는 DDSCAPS_MODEX, 모드 13 에 대해서는 DDSCAPS_STANDARDVGAMODE 가 된다. 이러한 플래그는, 서로 배타이다. 이것들 비트가 양쪽 모두 설정되지 않은 경우는, 모드는 선형 가속기 모드라는 것이 된다. 이것은,DirectDraw7.GetDisplayMode 메소드로부터 취득된 플래그에도 들어맞는다.


모드 13 의 사용

[C++]

모드 X 모드와는 달라 모드 13 은 선형 모드이므로, DirectDraw 는 어플리케이션에 frame buffer에의 직접 액세스를 줄 수가 있다. IDirectDrawSurface7::Lock ,IDirectDrawSurface7::Blt , 및 IDirectDrawSurface7::BltFast 메소드를 호출해, 프라이머리 표면에의 직접 액세스를 취득한다.

모드 13 을 사용 하면, DirectDraw 는, 프라이머리 표면에의 백 버퍼의 컨텐츠에 있어서의 직접 카피로서 실현되는 에뮬레이트 한 IDirectDrawSurface7::Flip 를 지원 한다. Blt 또는 BltFast 를 사용하는 것으로, 프라이머리 표면에 백 버퍼의 모두, 또는 일부를 카피하는 것으로써, 스스로 이것을 에뮬레이트 할 수 있다.

[Visual Basic]

모드 X 모드와는 달라 모드 13 은 선형 모드이므로, DirectDraw 는 어플리케이션에 frame buffer에의 직접 액세스를 줄 수가 있다. DirectDrawSurface7.Lock ,DirectDrawSurface7.Blt , 및 DirectDrawSurface7.BltFast 메소드를 호출해, 프라이머리 표면에의 직접 액세스를 취득한다.

모드 13 을 사용 하면, DirectDraw 는, 프라이머리 표면에의 백 버퍼의 컨텐츠에 있어서의 직접 카피로서 실현되는 에뮬레이트 한 DirectDrawSurface7.Flip 를 지원 한다. Blt 또는 BltFast 를 사용하는 것으로, 프라이머리 표면에 백 버퍼의 모두, 또는 일부를 카피하는 것으로써, 스스로 이것을 에뮬레이트 할 수 있다.

[C++]

Lock 및 모드 13 에 관해서, 1 개(살) 경고 해야 할것이 있다. DirectDraw 는, 모드 13VGA frame buffer에의 직접 선형 액세스를 가능하게 하지만, 버퍼가 항상 주소 0xA0000 에 있다고 하여는 안 된다. DirectDraw 가, 0xA0000 가 아닌 frame buffer에의 별명의 가상 메모리 포인터를 돌려주는 것이 있기 때문이다. 같이 모드 13 표면의피치가 320 이다고 하여는 안 된다. 가속기 320 × 200 × 8 모드를 지원 하는 디스플레이 카드에서는, 다른 피치를 자주(잘) 사용하기 때문이다.

[Visual Basic]

Lock 및 모드 13 에 관해서, 1 개(살) 경고 해야 할것이 있다. 모드 13 표면의피치가 320 이다고 하여는 안 된다. 가속기 320 × 200 × 8 모드를 지원 하는 디스플레이 카드에서는, 다른 피치를 자주(잘) 사용하기 때문이다.


스테레오 뷰

이하의 주제에서는, DirectX 7.0 으로 지원 되는 스테레오 뷰에 대해 설명한다.

  • 스테레오 뷰에 대해
  • 스테레오 뷰 디스플레이 디바이스에 대해
  • 지원 되는 스테레오 뷰 모드의 결정
  • 스테레오 뷰의 이행

스테레오 뷰는, 풀 스크린 배타 모드에서만 지원 된다. 윈도우에서는 스테레오 모드는 지원 되지 않는다.

상세한 것에 대하여는, 「디스플레이 모드」와「표면」을 참조할것.


스테레오 뷰에 대해

스테레오 뷰, 혹은 입체 표시에서는, 조금 다른 각도로 파악된 2 살의 장면 이미지를 표시하는 것으로써, 3D 이펙트를 생성한다. 2D 표시로 스테레오 뷰를 실현하려면 , 좌안과 우안에 다른 이미지를 할당해 처리한다. 스테레오 뷰를 실현하는 가장 일반적인 방법은, 왼쪽의 이미지와 오른쪽의 이미지를 다중화하는 방법이다. 이 방법에서는, 왼쪽의 이미지와 오른쪽의 이미지를 고속으로 교대로 표시한다. 적절한 이펙트를 생성하려면 , 한편의 눈의 뷰를 표시하고 있는 동안은, 이제 한편의 눈의 뷰를 표시하지 않게 한다.

스테레오 뷰 기능을 이용하려면 , 어플리케이션이 스테레오 뷰를 지원 해, 하드웨어에 스테레오 데이터를 송신할 수 있는 어플리케이션 프로그래밍 인터페이스 (API)를 사용해야 한다. DirectDraw 에서는, 2 개의 표면을 1 개의 스테레오 페어의 이미지로서 생성 해, 관리한다. 또, 그래픽 칩이나 그래픽 카드의 메이커로부터, 사용 가능한 하드웨어나 스테레오 대응 드라이버가 제공되어 있지 않으면 안 된다. 스테레오 디스플레이 메이커의 제공하는 스테레오 디스플레이 디바이스도 필요하다.

스테레오 디스플레이 디바이스에는, 단순한 빨강과 파랑의 평면 렌즈, 액정 디스플레이 (LCD) 셔터 렌즈, 및 복잡한 자동 스테레오 그래픽스 디스플레이 등, 다양한 종류가 있다. 필요한 하드웨어 및 소프트웨어 컴퍼넌트는 디바이스에 따라서 다르므로, 단일의 스테레오 뷰 솔루션을 지원 하는 것은 곤란하다. 이 때문에, DirectDraw 에서는, 디스플레이 디바이스 준거의 그래픽스 디스플레이 드라이버를 사용해 스테레오 뷰를 이행 해야 한다.

스테레오 디스플레이 디바이스에는, 대응하는 그래픽 카드가 필요하다. 그래픽 카드의 드라이버는, 디바이스 고유의 메모리 레이아웃이나 스캔 조건을 처리할 수 없으면 안 된다. 스캔 조건에는, 디스플레이와의 동기가 포함된다. 예를 들어, 셔터 렌즈에서는, 왼쪽의 셔터가 열려 있을 때는 왼쪽의 이미지를, 오른쪽의 셔터가 열려 있을 때는 오른쪽의 이미지를 표시한다.


스테레오 뷰 디스플레이 디바이스에 대해

DirectDraw 는, 능동 및 수동 3D 스테레오 뷰 디스플레이 디바이스의 양쪽 모두를 지원 한다. 이하의 주제에서는, DirectDraw 가 능동 및 수동 디스플레이 디바이스를 어떻게 처리할까에 임해서 설명한다.

  • 능동 디스플레이 디바이스
  • 수동 디스플레이 디바이스


지원 되는 스테레오 뷰 모드의 결정

[C++]

하드웨어가 스테레오 뷰를 지원 할지 어떨지는, DDCAPS2_STEREO 플래그에 의해 조사할 수가 있다. 이 플래그는, DirectDraw 오브젝트에 의해 공개되는 하드웨어 능력을 나타내는 DDCAPS 구조체의 dwCaps2 멤버로 설정된다. 현재의 디스플레이 모드가, 스테레오 뷰를 지원 하는 디스플레이 모드가 아닌 경우도 있으므로 주의 해야 한다.

특정의 디스플레이 모드로 스테레오 뷰를 지원 할지 어떨지를 확인하려면 ,IDirectDraw7::EnumDisplayModes 메소드를 사용해 지원 되는 디스플레이 모드를 열거한다. 하드웨어에 의해 지원 되는 각 디스플레이 모드에 대해서, DirectDraw 는 EnumModesCallback prototype와 조합하는 콜백 함수를 호출한다. 이 콜백 함수의 최초의 인수는, 지원 되는 디스플레이 모드의 1 개를 나타내는 DDSURFACEDESC2 구조체의 주소이다. DDSURFACEDESC2 구조체의 ddsCaps 멤버의 dwCaps2 필드에, DDSCAPS2_STEREOSURFACELEFT 플래그가 설정되어 있는지 어떤지를 조사한다. 이 플래그가 설정되어 있으면(자), 그 디스플레이 모드는 스테레오 뷰를 지원 한다.

IDirectDraw7::GetDisplayMode 메소드를 사용해 현재의 디스플레이 모드를 취득해, 돌려주어진 DDSURFACEDESC2 구조체의 스테레오 뷰 능력을 조사할 수도 있다.

[Visual Basic]

하드웨어가 스테레오 뷰를 지원 하고 있을지 어떨지를 확인하려면 , DDCAPS2_STEREO 플래그를 조사한다. 이 플래그는, DirectDraw 오브젝트에 의해 공개되는 하드웨어 능력을 나타내는 DDCAPS 형의 lNLVBCaps2 멤버로 설정된다. DDCAPS2_STEREO 플래그는,CONST_DDCAPS2FLAGS 열거의 멤버이다. 현재의 디스플레이 모드가, 스테레오 뷰를 지원 하는 디스플레이 모드가 아닌 경우도 있으므로 주의 해야 한다.

특정의 디스플레이 모드로 스테레오 뷰를 지원 할지 어떨지를 확인하려면 ,DirectDraw7.GetDisplayModesEnum 메소드를 사용해 지원 되는 디스플레이 모드를 열거한다. method. 이 메소드는,DirectDrawEnumModes 오브젝트를 돌려준다. 지원 되는 디스플레이 모드를 기술하는 DDSURFACEDESC2 형을 취득하려면 ,DirectDrawEnumModes.GetItem 메소드를 호출한다. DDSURFACEDESC2 형의 ddsCaps 멤버의 lCaps2 필드에, DDSCAPS2_STEREOSURFACELEFT 플래그가 설정되어 있는지 어떤지를 조사한다. 이 플래그가 세트 되고 있으면(자), 그 디스플레이 모드는 스테레오 뷰를 지원 한다.

DirectDraw7.GetDisplayMode 메소드를 사용해 현재의 디스플레이 모드를 취득해, 돌려주어진 DDSURFACEDESC2 형의 스테레오 뷰 능력을 조사할 수도 있다.

디스플레이 모드의 열거에 대해서는, 「지원 되는 디스플레이의 결정」을 참조할것.


스테레오 뷰의 이행

DirectDraw 를 초기화해 디스플레이 모드를 열거해, 스테레오 뷰가 지원 되고 있는 것을 확인하면(자), DirectDraw 의 스테레오 뷰 지원을 이용할 수 있다. 최초로, 스테레오 뷰 플립핑 체인에 대해서 표면을 선언할 필요가 있다.

[C++]
LPDIRECTDRAWSURFACE7 pFrontBuffer;
LPDIRECTDRAWSURFACE7 pBackBuffer;
LPDIRECTDRAWSURFACE7 pBackBufferLeft;

다음에, 스테레오 뷰를 지원 하는 표면을 기술하는 DDSURFACEDESC2 구조체를 준비한다.

DDSURFACEDESC2 ddsd2 = {sizeof(ddsd2)};

ddsd2.dwFlags = DDSDS_CAPS|DDSD_BACKBUFFERCOUNT;
ddsd2.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE|
                       DDSCAPS_3DDEVICE;
ddsd2.dwBackBufferCount =1;
ddsd2.ddsCaps.dwCaps2 = DDSCAPS2_STEREOSURFACELEFT;
ddsd2.ddsCaps.dwCaps3 = ddsd2.ddsCaps.dwCaps4 =0;

DDSCAPS_PRIMARYSURFACE 플래그가 지정되어 있지 않으면 표면의 기술로 DDSCAPS2_STEREOSURFACELEFT 를 지정할 수 없다. 이것은, 어플리케이션이 다른 표면으로 스테레오 플립핑 체인을 생성 해,IDirectDrawSurface7::AddAttachedSurface 메소드를 호출해 Attach 하는 것을 막기 때문에 있다. DDSCAPS2_STEREOSURFACELEFT 가 능력 플래그로서 지정되고 있는 경우, 프라이머리 체인의 각 버퍼에 2 개의 표면이 생성 된다. 예를 들어,dwBackBufferCount = N 의 경우, 2 * (N+1) 표면이 생성 된다. 이러한 표면의 한편에는 DDSCAPS2_STEREOSURFACELEFT 능력 플래그가 설정되어 이제 한편에는 설정되지 않는다.

[Visual Basic]
Dim ddsFrontBuffer As DirectDrawSurface7
Dim ddsBackBuffer As DirectDrawSurface7
Dim ddsBackBufferLeft As DirectDrawSurface7

다음에, 스테레오 뷰를 지원 하는 표면을 기술하는 DDSURFACEDESC2 형을 준비한다.

Dim ddsd2 As DDSURFACEDESC2

ddsd2.lFlags = DDSD_CAPS Or DDSD_BACKBUFFERCOUNT
ddsd2.ddsCaps.lCaps = DDSCAPS_PRIMARYSURFACE Or DDSCAPS_3DDEVICE
ddsd2.lBackBufferCount = 1
ddsd2.ddsCaps.lCaps2 = DDSCAPS2_STEREOSURFACELEFT
ddsd2.ddsCaps.lCaps3 = ddsd2.ddsCaps.lCaps4 = 0

DDSCAPS_PRIMARYSURFACE 플래그가 지정되어 있지 않으면 표면의 기술로 DDSCAPS2_STEREOSURFACELEFT 를 지정할 수 없다. 이것은, 어플리케이션이 다른 표면으로 스테레오 플립핑 체인을 생성 해,DirectDrawSurface7.AddAttachedSurface 메소드를 호출해 Attach 하는 것을 막기 때문에 있다. DDSCAPS2_STEREOSURFACELEFT 가 능력 플래그로서 지정되고 있는 경우, 프라이머리 체인의 각 버퍼에 2 개의 표면이 생성 된다. 예를 들어,lBackBufferCount = N 의 경우, 2 * (N+1) 표면이 생성 된다. 이러한 표면의 한편에는 DDSCAPS2_STEREOSURFACELEFT 능력 플래그가 설정되어 이제 한편에는 설정되지 않는다.

표면은, 다음의 그림에 나타내도록(듯이) 해 Attach 되어 라벨을 붙일 수 있다.

어플리케이션이 DDSCAPS_3DDEVICE 를 지정 하면, 이 능력 플래그는 체인내의 모든 표면에 카피되므로 주의 해야 한다.

[C++]

여기서, 프라이머리 표면을 생성 한다.

pDD7->CreateSurface(&ddsd2, &pFrontBuffer, NULL);

ddsd2.ddsCaps.dwCaps = DDSCAPS_BACKBUFFER;
pFrontBuffer->GetAttachedSurface(&ddsd2.ddsCaps, &pBackBuffer);

ddsd2.ddsCaps.dwCaps = 0;
ddsd2.ddsCaps.dwCaps2 = DDSCAPS2_STEREOSURFACELEFT;
pBackBuffer->GetAttachedSurface(&ddsd2.ddsCaps, &pBackBufferLeft);

위의 코드에서는,IDirectDrawSurface7::GetAttachedSurface 메소드에 의해, 스테레오 뷰 플립핑 체인에 Attach 된 표면을 취득한다.

while(running)
{
RenderRightImage(pBackBuffer);
RenderLeftImage(pBackBufferLeft);

pFrontBuffer->Flip(NULL, DDFLIP_WAIT|DDFLIP_STEREO);
}

위의 코드에서는, 어플리케이션 정의 함수 RenderRightImage 및 RenderLeftImage 에 의해, 스테레오 이미지를 렌더링 한다.

DDFLIP_STEREO 플래그가 IDirectDrawSurface7::Flip 메소드에게 건네지면(자), 2 개의 표면이 드라이버에게 건네진다. 이러한 표면이, 새로운 스테레오 페어가 된다. DirectDraw 는, DDSCAPS2_STEREOSURFACELEFT 표면이 Attach 된 표면에서만 이 플래그를 사용할 수 있다.

[Visual Basic]

여기서, 프라이머리 표면을 생성 한다.

Set ddsFrontBuffer = dd.CreateSurface(ddsd2)

ddsd2.ddsCaps.lCaps = DDSCAPS_BACKBUFFER
Set ddsBackBuffer = ddsFrontBuffer.GetAttachedSurface(ddsd2.ddsCaps)

ddsd2.ddsCaps.lCaps = 0
ddsd2.ddsCaps.lCaps2 = DDSCAPS2_STEREOSURFACELEFT
Set ddsBackBufferLeft = ddsBackBuffer.GetAttachedSurface(ddsd2.ddsCaps)

위의 코드에서는,DirectDrawSurface7.GetAttachedSurface 메소드를 사용해, 스테레오 뷰 플립핑 체인에 Attach 된 표면을 취득한다.

Do While g_bRunning

RenderRightImage ddsBackBuffer      ' 오른쪽의 이미지를 렌더링 한다.
RenderLeftImage ddsBackBufferLeft   '왼쪽의 이미지를 렌더링 한다.

ddsFrontBuffer.Flip Nothing, DDFLIP_WAIT Or DDFLIP_STEREO

Loop

위의 코드에서는, 어플리케이션 정의 함수 RenderRightImage 와 RenderLeftImage 에 의해, 스테레오 이미지를 렌더링 한다.

DDFLIP_STEREO 플래그가 DirectDrawSurface7.Flip 메소드에게 건네지면(자), 2 개의 표면이 드라이버에게 건네진다. 이러한 표면이, 새로운 스테레오 페어가 된다. DirectDraw 는, DDSCAPS2_STEREOSURFACELEFT 표면이 Attach 된 표면에서만 이 플래그를 사용할 수 있다.

DDFLIP_STEREO 플래그가 Flip 메소드에게 건네지지 않았던 경우, 드라이버에 대한 표면 플립핑 호출에 의해 1 개의 표면만이 지정된다. 이것에 의해, 스테레오 뷰는 필요없는 것을 드라이버에 나타낸다.

플립핑 체인의 상세한 것에 대하여는, 「플립핑 표면」의 개요의 주제를 참조할것.


DMA 지원의 이용

여기에서는, 특정의 태스크로 퍼포먼스를 향상시키기 위해서(때문에), 직접 메모리 액세스 (DMA)를 지원 하는 디바이스의 이용 방법에 대해 설명한다. 다음의 항목에 대해 기술한다.

  • DMA 디바이스 지원에 대해
  • DMA 지원의 테스트
  • DMA 의 일반적 시나리오
  • DMA 의 사용


DMA 디바이스 지원에 대해

시스템 메모리 표면으로, 블리트 처리 (또는 다른 처리)를 실행할 수 있는 디스플레이 디바이스도 있다. 이러한 처리는, 보통, 직접 메모리 액세스 (DMA) 처리로 불린다. DMA 지원을 이용 하면, 어느 처리의 편성을 가속기 할 수 있다. 예를 들어, 이러한 디바이스에서는, 다음의 프레임을 준비하기 위해서 프로세스를 사용하고 있는 동안, 시스템 메모리로부터 비디오 메모리에의 블리트를 실행할 수 있다. 이러한 기능을 사용하려면 , 어느 응답이 필요하다. 여기에서는, 이러한 태스크에 대해 자세하게 설명한다.


DMA 지원의 테스트

[C++]

DMA 처리를 사용하기 전에, 디바이스에 대한 DMA 지원을 테스트할 필요가 있다. 디바이스가 DMA 를 지원 하고 있는 경우, 어느 정도의 지원이 제공되는지를 조사한다. 우선,IDirectDraw7::GetCaps 메소드를 호출해 드라이버 능력을 취득한다. 다음에, 관련지을 수 있었던 DDCAPS 구조체의 dwCaps 멤버에 DDCAPS_CANBLTSYSMEM 플래그가 있을지 어떨지를 조사한다. 이 플래그가 설정되어 있으면, 디바이스가 DMA 를 지원 하고 있게 된다.

보통, DMA 가 지원 되는 것을 알 수 있으면(자), 드라이버가 DMA 를 어느 정도 지원 하는지도 조사하지 않으면 안 된다. 그 때문에(위해)는, 시스템으로부터 비디오, 비디오로부터 시스템, 및 시스템으로부터 시스템에의 블리트 처리에 대한 정보를 가지는 구조체의 다른 멤버를 조사한다. 이러한 능력은, 블리트와 그 능력 타입에 의해 이름이 붙여진 12 의 DDCAPS 구조체 멤버로 제공된다. 다음 표로 이러한 신멤버를 나타낸다.

시스템으로부터 비디오 | 비디오로부터 시스템 | 시스템으로부터 시스템
dwSVBCaps | dwVSBCaps | dwSSBCaps
dwSVBCKeyCaps | dwVSBCKeyCaps | dwSSBCKeyCaps
dwSVBFXCaps | dwVSBFXCaps | dwSSBFXCaps
dwSVBRops | dwVSBRops | dwSSBRops

예를 들어, 시스템으로부터 비디오에의 블리트 능력 플래그는,dwSVBCaps,dwSVBCKeyCaps,dwSVBFXCaps, 및 dwSVBRops 멤버에 의해 제공된다. 같이 비디오로부터 시스템에의 블리트 능력은 "dwVSB" 로 시작되는 이름의 멤버에 있어, 시스템으로부터 시스템에의 블리트 능력은 "dwSSB" 멤버에 있다. 이러한 멤버의 플래그를 조사하면(자), 블리트 카테고리에 대한 하드웨어 지원의 레벨을 결정할 수 있다.

이러한 멤버에 있는 플래그는,dwCaps,dwCKeyCaps, 및 dwFXCaps 멤버의 블리트 타입을 고려한 이러한 멤버에 포함되는 블리트 관련 플래그 와 유사한다. 예를 들어,dwSVBCaps 멤버에는,dwCaps 멤버로 조사한 플래그와 같은 플래그로 지정된 일반적인 블리트 능력이 포함된다. 같이dwSVBRops,dwVSBRops, 및 dwSSBRops 멤버에 있는 라스터 처리값은, 주어진 타입의 블리트 처리에 의해 지원 되는 라스터 처리에 대한 정보를 제공한다.

이러한 멤버에 있어서의 주요 기능의 1 개는, 비동기 DMA 블리트 처리를 지원 한다. 드라이버가 표면간의 비동기 DMA 블리트를 지원 하는 경우,dwSVBCaps,dwVSBCaps, 또는 dwSSBCaps 멤버에 DDCAPS_BLTQUEUE 플래그가 설정된다 (보통, 시스템 메모리로부터 비디오 메모리 표면에 대한 최선의 지원이 된다). 이 플래그가 이러한 멤버에 없으면 드라이버에서는 비동기 DMA 블리트 처리를 지원 하지 않는다.

[Visual Basic]

DMA 처리를 사용하기 전에, 디바이스에 대한 DMA 지원을 테스트할 필요가 있다. 디바이스가 DMA 를 지원 하고 있는 경우, 어느 정도의 지원이 제공되는지를 조사한다. 우선,DirectDraw7.GetCaps 메소드를 호출해 드라이버 능력을 취득한다. 다음에, 관련지을 수 있었던 DDCAPS 형의 lCaps 멤버에 DDCAPS_CANBLTSYSMEM 플래그가 있을지 어떨지를 조사한다. 이 플래그가 설정되어 있으면, 디바이스가 DMA 를 지원 하고 있게 된다.

보통, DMA 가 지원 되는 것을 알 수 있으면(자), 드라이버가 DMA 를 어느 정도 지원 하는지도 조사하지 않으면 안 된다. 그 때문에(위해)는, 시스템 컬러 비디오, 비디오로부터 시스템, 및 시스템 컬러 시스템에의 블리트 처리에 대한 정보를 가지는 구조체의 다른 멤버를 조사한다. 이러한 능력은, 블리트와 그 능력 타입에 의해 이름이 붙여진 12 의 DDCAPS 구조체 멤버로 제공된다. 다음 표로 이러한 신멤버를 나타낸다.

시스템으로부터 비디오 | 비디오로부터 시스템 | 시스템으로부터 시스템
lSVBCaps | lVSBCaps | lSSBCaps
lSVBCKeyCaps | lVSBCKeyCaps | lSSBCKeyCaps
lSVBFXCaps | lVSBFXCaps | lSSBFXCaps
lSVBRops | lVSBRops | lSSBRops

예를 들어, 시스템으로부터 비디오에의 블리트 능력 플래그는,lSVBCaps,lSVBCKeyCaps,lSVBFXCaps 및 lSVBRops 멤버에 의해 제공된다. 같이 비디오로부터 시스템에의 블리트 능력은 "lVSB" 로 시작되는 이름의 멤버에 있어, 시스템으로부터 시스템에의 블리트 능력은 "lSSB" 멤버에 있다. 이러한 멤버의 플래그를 조사하면(자), 블리트 카테고리에 대한 하드웨어 지원의 레벨을 결정할 수 있다.

이러한 멤버에 있는 플래그는,lCaps,lCKeyCaps, 및 lFXCaps 멤버의 블리트 타입을 고려한 이러한 멤버에 포함되는 블리트 관련 플래그 와 유사한다. 예를 들어,lSVBCaps 멤버에는,lCaps 멤버로 조사한 플래그와 같은 플래그로 지정된 일반적인 블리트 능력이 포함된다. 같이lSVBRops,lVSBRops, 및 lSSBRops 멤버에 있는 라스터 처리값은, 주어진 타입의 블리트 처리에 의해 지원 되는 라스터 처리에 대한 정보를 제공한다.

이러한 멤버에 있어서의 주요 기능의 1 개는, 비동기 DMA 블리트 처리를 지원 한다. 드라이버가 표면간의 비동기 DMA 블리트를 지원 하는 경우,lSVBCaps,lVSBCaps, 또는 lSSBCaps 멤버에 DDCAPS_BLTQUEUE 플래그가 설정된다 (보통, 시스템 메모리로부터 비디오 메모리 표면에 대한 최선의 지원이 된다). 이 플래그가 이러한 멤버에 없으면 드라이버에서는 비동기 DMA 블리트 처리를 지원 하지 않는다.


DMA 의 일반적 시나리오

SRCCOPY 라스터 처리를 이용하는 시스템 메모리로부터 비디오 메모리에의 전송은, 하드웨어로 지원 하는 블리트 처리의 전형적인 타입이다 (플랫폼 SDK 로 설명하는 SRCCOPY 라스터 처리에 의해, 전송원직사각형내의 데이터가 목적지 직사각형에 직접 카피할 수 있다). 이러한 처리에 있어서의 보통의 이용에서는, 다음의 처리의 준비로서 시스템 메모리 표면의 큰 집합으로부터 비디오 메모리 표면에 텍스쳐를 이동한다. 시스템으로부터 비디오에의 DMA 전송은, 프로세서 컨트롤 전송 (예를 들어, HEL 블리트)과 거의 같은 속도이지만, 호스트 프로세서와 병행에 동작할 수 있으므로 매우 도움이 된다.


DMA 의 사용

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

하드웨어 전송에서는, 어플리케이션으로 자주(잘) 사용하는 가상 주소는 아니고 물리 메모리 주소를 사용한다. 디바이스 드라이버에 따라서는, 표면의 물리 메모리 주소를 요구하는 일이 있다. 이 기구는,IDirectDrawSurface7::PageLock 메소드로 실현된다. 디바이스 드라이버가 페이지 락을 요구하지 않는 경우,IDirectDraw7::GetCaps 메소드를 호출해 하드웨어 능력을 취득할 경우에 DDCAPS2_NOPAGELOCKREQUIRED 플래그가 설정된다.

표면을 페이지 잠그는 것으로, 시스템이 표면의 물리 메모리가 다른 목적으로 사용되는 것을 저지할 수 있다. 또, 표면의 물리 주소가, 대응하는 IDirectDrawSurface7::PageUnlock 가 불려 갈 때까지 일정에 유지되는 일도 보증된다. 디바이스 드라이버가 페이지 락을 요구하는 경우, DirectDraw 에서는, 어플리케이션이 페이지 잠그고 있는 시스템 메모리 표면상에서만 비동기의 DMA 처리를 인정한다. 이러한 상황으로,IDirectDrawSurface7::PageLock 를 호출하지 않는 경우, DirectDraw 는 소프트웨어 에뮬레이션을 사용해 전송을 실시한다. 대용량의 시스템 메모리를 잠그면(자), Windows 의 동작이 늦어지는 것에 주의한다. 따라서, 풀 스크린의 배타 모드 어플리케이션만으로, 대용량의 시스템 메모리에 대한 IDirectDrawSurface7::PageLock 를 사용해, 이러한 어플리케이션이 최소화되었을 경우에, 그 표면의 락을 해제하는 것을 유의하는 것이 강하게 바람직한다. 물론, 어플리케이션이 restore 되면(자), 시스템 메모리 표면을 다시 페이지 잠그지 않으면 안 된다.

페이지 락의 관리는, 그 모든 것을 어플리케이션 개발자의 책임으로 실시한다. DirectDraw 에서는, 표면을 페이지 잠그거나 페이지 락을 해제하거나 할 것은 없다. 즉, 개발자 자신이, 시스템 퍼포먼스를 저하시키는 일 없이, 어느 정도의 메모리를 안전하게 페이지 잠글 수 있을까를 결정하지 않으면 안 된다.


윈도우 모드에서의 DirectDraw 팔레트의 사용

[C++]

IDirectDrawPalette 인터페이스 메소드는, 디스플레이가 배타 (풀 스크린) 모드인 경우에, 하드웨어에 직접 기입한다. 다만, 디스플레이가 비배타 (윈도우) 모드인 경우는,IDirectDrawPalette 인터페이스 메소드가 GDI 팔레트 조작 함수를 호출해, 다른 윈도우 어플리케이션과 협조해 작용한다.

[Visual Basic]

DirectDrawPalette 클래스 메소드는, 디스플레이가 배타 (풀 스크린) 모드인 경우에, 하드웨어에 직접 기입한다. 다만, 디스플레이가 비배타 (윈도우) 모드인 경우는,IDirectDrawPalette 클래스 메소드가 GDI 팔레트 조작 함수를 호출해, 다른 윈도우 어플리케이션과 협조해 작용한다.

데스크탑이 8 비트의 팔레트화 모드로, 생성자가프라이머리 표면이나 일반적인 윈도우의 생성 경험이 있는 것을 상정해, 다음의 항목에 대해 기술한다.

  • 윈도우 모드에서의 팔레트 엔트리의 설정
  • 윈도우 모드에서의 팔레트의 생성
  • 윈도우 모드에서의 팔레트 엔트리의 설정


윈도우 모드에서의 팔레트 엔트리의 설정

[C++]

풀 스크린 배타 모드 어플리케이션과는 달라, 윈도우 어플리케이션은 다른 어플리케이션과 데스크탑 팔레트를 공유할 필요가 있다. 이 때문에, 어느 팔레트 엔트리를 안전하게 수정할 수 있어 어떻게 그것들을 수정하는지에 임해서, 몇개의 제한이 있다. DirectDrawPalette 오브젝트나 GDI 에 작용하는 경우에 사용하는 PALETTEENTRY 구조체에는, 시스템이 PALETTEENTRY 구조체를 어떻게 판단해야할 것인가에 임해서 기술한 정보를 전달하는 peFlags 멤버가 포함된다.

peFlags 멤버는, 다음에 설명하는 3 개의 타입의 팔레트 엔트리를 기술한다.

[Visual Basic]

풀 스크린 배타 모드 어플리케이션과는 달라, 윈도우 어플리케이션은 다른 어플리케이션과 데스크탑 팔레트를 공유할 필요가 있다. 이 때문에, 어느 팔레트 엔트리를 안전하게 수정할 수 있어 어떻게 그것들을 수정하는지에 임해서, 몇개의 제한이 있다. DirectDrawPalette 오브젝트나 GDI 에 작용하는 경우에 사용하는 PALETTEENTRY 형에는, 시스템이 PALETTEENTRY 형을 어떻게 판단해야할 것인가에 임해서 기술한 정보를 전달하는 flags 멤버가 포함된다.

flags 멤버는, 다음에 설명하는 3 개의 타입의 팔레트 엔트리를 기술한다.

  • Windows 스태틱 엔트리
  • 애니메이션 엔트리
  • 비애니메이션 엔트리

Windows 스태틱 엔트리

보통 모드에서는, Windows 는 시스템 컬러로서 0 에서 9, 및 246 에서 255 까지의 팔레트 엔트리를 확보하고 있어, 도구모음, 메뉴 텍스트, 및 윈도우의 경계등을 표시하기 위해서 이러한 시스템 컬러를 사용한다. 어플리케이션의 외관을 일정에 유지해, 다른 어플리케이션의 외관을 해칠리가 없게, 프라이머리 표면으로 설정한 팔레트의 이러한 엔트리를 보호할 필요가 있다. 개발자가,GetSystemPaletteEntries Win32® 함수를 호출해 시스템 팔레트 엔트리를 취득해, 동일한 엔트리를 커스텀 팔레트에 명시적으로 설정한 후, 그것을 프라이머리 표면에 할당하는 경우가 있다. 커스텀 팔레트로 시스템 팔레트 엔트리를 복제했던 바로 직후라면 작용하지만, 유저가 데스크탑 컬러 스킴을 변경 하면 무효가 된다.

유저가 컬러 스킴을 변경할 경우에, 팔레트가 손상되지 않게 하려면 , 컬러값을 지정하는 것이 아니라, 시스템 팔레트에의 참조를 제공하는 것으로 해당하는 엔트리를 보호한다. 이와 같이 해, 주어진 엔트리에 대해서 시스템이 어느 색을 사용하고 있어도, 팔레트는 항상 적합해, 갱신할 필요는 없다. peFlags 멤버로 사용하는 PC_EXPLICIT 플래그에 의해, 시스템 팔레트 엔트리를 직접 참조할것이 생긴다. 이 플래그를 사용하는 경우, 시스템은 구조체의 다른 멤버에 색정보가 있는 것을 가정하지 않는다. PC_EXPLICIT 를 사용하는 경우,peRed 멤버에 바람직한 시스템 팔레트 인덱스를 설정해, 다른 색을 제로로 한다.

[C++]

예를 들어, 팔레트의 적절한 엔트리가 항상 시스템의 컬러 스킴에 적합하도록(듯이) 하려면 , 이하의 코드를 사용한다.

// 최초와 마지막 10 엔트리를 // 시스템 팔레트에 적합하도록(듯이) 설정한다.
PALETTEENTRY pe[256];
ZeroMemory(pe, sizeof(pe));
for(int i=0;i<10;i++){
    pe[i]. peFlags  = pe[i+246]. peFlags = PC_EXPLICIT;
    pe[i]. peRed = i;
    pe[i+246]. peRed = i+246;
}

SetSystemPaletteUse Win32 함수를 호출해, Windows 가 최초와 마지막 팔레트 엔트리 (0 으로 255) 밖에 사용할 수 없게 할 수도 있다. 이 경우,PALETTEENTRY 구조체의 0 으로 255 의 엔트리만을 PC_EXPLICIT 로 설정한다.

애니메이션 엔트리

대응하는 PALETTEENTRY 구조체에 PC_RESERVED 플래그를 사용하는 것으로, 애니메이션 하는 팔레트 엔트리를 지정할 수 있다. Windows 에서는, 타어플리케이션이 논리 팔레트 엔트리를 물리 팔레트 엔트리에 맵 시키지 않다. 이 때문에, 어플리케이션이 팔레트를 애니메이션 할 경우에, 다른 어플리케이션이 그 색을 바탕으로 되돌리지 않게 할 수 있다.

비애니메이션 엔트리

대응하는 PALETTEENTRY 구조체에 PC_NOCOLLAPSE 플래그를 사용하는 것으로, 애니메이션 하지 않는 보통의 팔레트 엔트리를 지정할 수 있다. PC_NOCOLLAPSE 플래그는, 다른 할당하고 끝난 물리 팔레트 엔트리를 그 엔트리로 옮겨놓지 않게 Windows 에게 전한다.

[Visual Basic]

SetSystemPaletteUse Win32 함수를 호출해, Windows 가 최초와 마지막 팔레트 엔트리 (0 으로 255) 밖에 사용할 수 없게 할 수도 있다. 이 경우,PALETTEENTRY 형의 0 으로 255 의 엔트리만을 PC_EXPLICIT 로 설정한다.

애니메이션 엔트리

대응하는 PALETTEENTRY 형에 PC_RESERVED 플래그를 사용하는 것으로, 애니메이션 하는 팔레트 엔트리를 지정할 수 있다. Windows 에서는, 타어플리케이션이 논리 팔레트 엔트리를 물리 팔레트 엔트리에 맵 시키지 않다. 이 때문에, 어플리케이션이 팔레트를 애니메이션 할 경우에, 다른 어플리케이션이 그 색을 바탕으로 되돌리지 않게 할 수 있다.

비애니메이션 엔트리

대응하는 PALETTEENTRY 형에 PC_NOCOLLAPSE 플래그를 사용하는 것으로, 애니메이션 하지 않는 보통의 팔레트 엔트리를 지정할 수 있다. PC_NOCOLLAPSE 플래그는, 다른 할당하고 끝난 물리 팔레트 엔트리를 그 엔트리로 옮겨놓지 않게 Windows 에게 전한다.


윈도우 모드에서의 팔레트의 생성

[C++]

다음의 예로, 비배타 (윈도우) 모드로 DirectDraw 팔레트를 어떻게 생성 하는지를 나타낸다. 팔레트를 올바르게 작용시키기 위해서(때문에),IDirectDraw7::CreatePalette 메소드에 건네준 PALETTEENTRY 구조체의 256 엔트리의 각각을 셋업 하는 것이 극히 중요해진다.

LPDIRECTDRAW7        lpDD; // 초기화되고 있으면(자) 가정한다.
PALETTEENTRY         pPaletteEntry[256];
int                  index;
HRESULT              ddrval;
LPDIRECTDRAWPALETTE2 lpDDPal;

// Windows 스태틱 엔트리를 설정한다.
for (index = 0; index < 10 ; index++)
{
    // 최초의 10 스태틱 엔트리
    pPaletteEntry[index]. peFlags = PC_EXPLICIT;
    pPaletteEntry[index]. peRed = index;
    pPaletteEntry[index]. peGreen = 0;
    pPaletteEntry[index]. peBlue = 0;

    // 마지막 10 스태틱 엔트리
    pPaletteEntry[index+246]. peFlags = PC_EXPLICIT;
    pPaletteEntry[index+246]. peRed = index+246;
    pPaletteEntry[index+246]. peGreen = 0;
    pPaletteEntry[index+246]. peBlue = 0;
}

// 여기서, Private 엔트리를 셋업 한다. 이 예에서는,
// 이용 가능한 최초의 16 엔트리가 애니메이션 된다.
for (index = 10; index < 26; index ++)
{
    pPaletteEntry[index]. peFlags = PC_NOCOLLAPSE|PC_RESERVED;
    pPaletteEntry[index]. peRed = 255;
    pPaletteEntry[index]. peGreen = 64;
    pPaletteEntry[index]. peBlue = 32;
}

// 여기서 나머지의 엔트리 (애니메이션 하지 않는 엔트리)를 셋업 한다.
for (; index < 246; index ++) // 전의 루프로 인덱스가 설정된다.
{
    pPaletteEntry[index]. peFlags = PC_NOCOLLAPSE;
    pPaletteEntry[index]. peRed = 25;
    pPaletteEntry[index]. peGreen = 6;
    pPaletteEntry[index]. peBlue = 63;
}

// 모든 256 엔트리를 묻는다. 팔레트를 생성 한다.
ddrval = lpDD->CreatePalette(DDPCAPS_8BIT, pPaletteEntry,
    &lpDDPal, NULL);
[Visual Basic]

다음의 예로, 비배타 (윈도우) 모드로 DirectDraw 팔레트를 어떻게 생성 하는지를 나타낸다. 팔레트를 올바르게 작용시키기 위해서(때문에),DirectDraw7.CreatePalette 메소드에 건네준 PALETTEENTRY 형의 256 의 엔트리의 각각을 셋업 하는 것이 극히 중요해진다.

Dim pPaletteEntry(255) As PALETTEENTRY
Dim index As Long
Dim ddpal As DirectDrawPalette

' Windows 스태틱 엔트리를 설정한다.
For index = 0 To 9
'최초의 10 스태틱 엔트리
        pPaletteEntry(index). flags = PC_EXPLICIT
        pPaletteEntry(index). red = index
        pPaletteEntry(index). green = 0
        pPaletteEntry(index). blue = 0

'마지막 10 스태틱 엔트리
pPaletteEntry(index + 246). flags = PC_EXPLICIT
pPaletteEntry(index + 246). red = index + 246
pPaletteEntry(index + 246). green = 0
pPaletteEntry(index + 246). blue = 0
Next

'여기서, Private 엔트리를 셋업 한다. 이 예에서는,
'이용 가능한 최초의 16 엔트리가 애니메이션 된다.
    For index = 10 To 25
        pPaletteEntry(index). flags = PC_NOCOLLAPSE Or PC_RESERVED
        pPaletteEntry(index). red = 255
        pPaletteEntry(index). green = 64
        pPaletteEntry(index). blue = 32
    Next

'여기서 나머지의 엔트리 (애니메이션 하지 않는 엔트리)를 '셋업 한다.
    For index = 26 To 246
        pPaletteEntry(index). flags = PC_NOCOLLAPSE
        pPaletteEntry(index). red = 25
        pPaletteEntry(index). green = 6
        pPaletteEntry(index). blue = 63
    Next

'모든 256 엔트리를 묻는다. 팔레트를 생성 한다.
Set ddpal = dd.CreatePalette(DDPCAPS_8BIT, pPaletteEntry())


윈도우 모드에서의 팔레트 엔트리의 설정

[C++]

IDirectDraw7::CreatePalette 메소드로 사용되는 PALETTEENTRY 구조체에 적용되는 규칙은,IDirectDrawPalette::SetEntries 메소드에도 적용된다. 일반적으로,PALETTEENTRY 구조체의 배열은 개발자 자신으로 유지하기 위해(때문에), 재구축의 필요는 없다. 재구축이 필요한 경우는, 배열을 수정한 후, 팔레트의 갱신시에 IDirectDrawPalette::SetEntries 를 호출할 수도 있다.

많은 경우, 비배타 (윈도우) 모드로 모든 Windows 스태틱 엔트리를 설정해서는 안된다. 이 모드로 설정해 버리면(자), 예측 불가능한 결과가 생긴다. 유일한 예외는, 256 엔트리를 리셋 하는 경우이다.

보통, 팔레트 애니메이션에서는,PALETTEENTRY 배열의 작은 서브 세트만을 변경한다. 그러한 엔트리만을 IDirectDrawPalette::SetEntries 에 건네주는 것이다. 이러한 작은 서브 세트를 리셋 하는 경우는, PC_NOCOLLAPSE 와 PC_RESERVED 플래그로 기술된 엔트리만을 리셋 하지 않으면 안 된다. 다른 엔트리를 애니메이션 하려고 한다고 예측 불가능한 결과가 생긴다.

다음의 예에서는, 비배타 모드의 팔레트 애니메이션을 설명한다.

LPDIRECTDRAW        lpDD;        // 이미 초기화되고 있다.
PALETTEENTRY pPaletteEntry[256]; // 이미 초기화되고 있다.
LPDIRECTDRAWPALETTE lpDDPal;     // 이미 초기화되고 있다.
int                 index;
HRESULT             ddrval;
PALETTEENTRY        temp;

// 몇개의 엔트리를 애니메이션 한다. 이용 가능한 최초의 16 의
// 엔트리를 순환시킨다. 이것에 의해 애니메이션 된다.
temp = pPaletteEntry[10];
for (index = 10; index < 25; index ++)
{
    pPaletteEntry[index] = pPaletteEntry[index+1];
}
pPaletteEntry[25] = temp;

// 값을 설정한다. 팔레트 엔트리 구조체 전체에의 포인터
// (은)는 아니고, 변경된 엔트리만에의 포인터를 건네준다.
ddrval = lpDDPal->SetEntries(
    0,                      // 플래그는 제로가 아니면 안 된다.
    10,                     // 최초의 엔트리.
    16,                     // 엔트리수.
    & (pPaletteEntry[10])); // 데이터를 취득하는 장소.
[Visual Basic]

DirectDraw7.CreatePalette 메소드로 사용되는 PALETTEENTRY 형에 적용되는 규칙은,DirectDrawPalette.SetEntries 메소드에도 적용된다. 일반적으로,PALETTEENTRY 형의 배열은 개발자 자신으로 유지하기 위해(때문에), 재구축의 필요는 없다. 재구축이 필요한 경우는, 배열을 수정한 후, 팔레트의 갱신시에 DirectDrawPalette.SetEntries 를 호출할 수도 있다.

많은 경우, 비배타 (윈도우) 모드로 모든 Windows 스태틱 엔트리를 설정해서는 안된다. 이 모드로 설정해 버리면(자), 예측 불가능한 결과가 생긴다. 유일한 예외는, 256 엔트리를 리셋 하는 경우이다.

보통, 팔레트 애니메이션에서는,PALETTEENTRY 배열의 작은 서브 세트만을 변경한다. 그러한 엔트리만을 DirectDrawPalette.SetEntries 에 건네주는 것이다. 이러한 작은 서브 세트를 리셋 하는 경우는, PC_NOCOLLAPSE 와 PC_RESERVED 플래그로 기술된 엔트리만을 리셋 해야 한다. 다른 엔트리를 애니메이션 하려고 한다고 예측 불가능한 결과가 생긴다.


비디오 포트

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic for DirectX 7.0 에서는 비디오 포트를 지원 하고 있지 않다.

[C++]

DirectDraw 비디오 포트 확장 기능은, 하위 레벨의 프로그래밍 인터페이스이며, 주류의 멀티미디어 프로그래머전용은 아니다. 타겟이 되는 고객은, Microsoft DirectShow 와 같은 제품을 생성 하는 영상 소프트 업계이다. 독자적인 소프트웨어에 비디오 재생 기능을 붙이고 싶다고 생각하는 개발자도, 비디오 포트 확장 기능을 이용할 수 있다. 그러나, 대부분의 소프트웨어에 대해서는, DirectShow 가 제공하는 것 같은 하이레벨의 프로그래밍 인터페이스가 보다 사용하기 쉽다.

여기에서는, DirectDrawVideoPort 오브젝트에 대해 설명한다. 다음의 항목에 대해 기술한다.

  • 비디오 포트란?
  • 비디오 포트 기술의 개요
  • DirectDraw 비디오 포트 확장 기능에 대해
  • 비디오 프레임과 필드
  • HREF, VREF, 및 connection
  • 수직귀선소각 간격 데이터
  • 자동 플립핑
  • 공통의 비디오의 문제의 회피 방법
  • 하프 라인에 의해 일으켜지는 문제의 해결
  • 하드웨어 기능의 이용


비디오 포트란?

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic for DirectX 7.0 에서는 비디오 포트를 지원 하고 있지 않다.

[C++]

DirectDrawVideoPort 오브젝트는, 디스플레이 어댑터의 종류에 의해 탑재되는 비디오 포트 하드웨어를 나타낸다. 일반적으로, 비디오 포트 오브젝트는, 비디오 포트 하드웨어가 비디오 디코더로부터 받는 비디오 신호를, 어떠한 방법으로 frame buffer에 직접 적용하는지를 제어한다.

복수의 비디오 채널은, 필요한 수만큼 DirectDrawVideoPort 오브젝트를 생성 하는 것으로써 제어된다. 각각의 채널을 개별적으로 열거하거나 구성할 수 있으므로, 각각의 채널에 대한 비디오 하드웨어는 동일한 필요는 없다.

상세한 것에 대하여는, 「비디오 포트 기술의 개요」를 참조할것.


비디오 포트 기술의 개요

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic for DirectX 7.0 에서는 비디오 포트를 지원 하고 있지 않다.

[C++]

비디오 포트는 디스플레이 디바이스 위에의 하드웨어이며, CPU 나 PCI 버스를 우회도로 해, frame buffer내의 표면에 직접 액세스 할 수 있다. 직접 frame buffer 액세스는, CPU 에 현저한 부담을 주는 일 없이, 라이브 비디오 또는 녹음 비디오를 효율적으로 재생할 수 있다. 표면내에 접어들어 버리면, 이미지를 오버레이로서 표시하거나 Direct3D 텍스쳐로서 사용하거나 캡춰나 다른 프로세스로부터 CPU 에 액세스 할 수 있다. 다음에 이 기술을 구성하는 컴퍼넌트나 그 컴퍼넌트의 동작 방법에 대한 일반론을 설명한다.

데이터 플로우

비디오 포트의 장비 되고 있는 머신에서는, 비디오 스트림의 데이터가, 비디오 디코더나 비디오 포트를 통해 비디오 소스로부터 frame buffer에 직접 플로우 한다. 보통, 이러한 컴퍼넌트는, 디스플레이 어댑터상에 모두 존재하지만, 물리적으로 서로 접속된 개별의 하드웨어 컴퍼넌트상에 분산할 수도 있다. 다음의 그림으로 이 데이터 플로우의 예를 나타낸다.

비디오 소스

비디오 포트 기술에서는, 비디오 소스는 엄밀하게 하드웨어 비디오 입력 디바이스여, 줌 비디오 포트, MPEG 코덱, 혹은 그 외의 하드웨어 소스 등이다. 이러한 소스는, 비디오 디코더에의 물리적인 connection에 의해, NTSC, PAL, 및 SECAM 를 포함한 다양한 포맷으로 신호를 브로드캐스트 한다.

비디오 디코더

비디오 디코더도 또, 하드웨어 컴퍼넌트이다. 비디오 디코더는 비디오 소스에 의해 제공되는 정보를 해독해, 통일 규격의 접속 포맷으로 그것을 비디오 포트에 보낸다. 디코더는 비디오 포트에의 물리적인 connection를 소유해, 스트림 클래스 미니 드라이버로부터 그 서비스를 공개한다. 디코더는 비디오 포트에 비디오 데이터, 비디오 클럭, 및 동기 정보를 보내지 않으면 안 된다.

비디오 포트

데이터 플로우 패스의 다른 컴퍼넌트와 같이, 비디오 포트는 하드웨어의 1 개이다. 비디오 포트는 디스플레이 어댑터의 VGA 팁상에 존재해, frame buffer에 직접 액세스 할 수 있다. 디코더로부터 보내지는 정보를 받아, 그것을 처리하고 나서, 표시하는 frame buffer에 배치한다. 처리중에, 비디오 포트는 스케일링, 수축, 컬러 컨트롤, 크로핑등의 서비스를 제공하는 이미지 데이터를 처리할 수 있다.

frame buffer

frame buffer는, 비디오 포트로부터 제공되는 비디오 데이터를 받는다. 그 데이터를 받아 버리면, 어플리케이션은 이미지 데이터를 프로그램에 근거해 조작하거나 다른 위치에 블리트 하거나 또 오버레이를 이용해 디스플레이상에 표시할 수 있다 (빈번하게 사용된다).


DirectDraw 비디오 포트 확장 기능에 대해

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic for DirectX 7.0 에서는 비디오 포트를 지원 하고 있지 않다.

[C++]

DirectDraw 는, DirectDrawVideoPort 오브젝트를 포함하기 위해서(때문에) 확장되었다. 이 오브젝트는 비디오 포트 기술을 이용해,IDDVideoPortContainer 및 IDirectDrawVideoPort 인터페이스로부터 서비스를 제공한다.

DirectDrawVideoPort 오브젝트는 비디오 디코더를 제어하지 않는다. 그것은, DirectDraw 가 비디오 소스를 제어하는 것이 아니라, 비디오 디코더 자체의 서비스를 제공하기 때문이다. 즉, 비디오 포트의 범위를 넘고 있는 것이다. 오히려, DirectDrawVideoPort 오브젝트는, 비디오 포트 자체를 나타낸다. 이 오브젝트는, 이미지의 변경, 플립핑의 실행, 혹은 다른 서비스의 실행에 있어서의 인터페이스 메소드로부터 설정되는 파라미터를 사용하는 것으로써, 들어 오는 신호를 모니터 하거나 frame buffer에 이미지 데이터를 건네주거나 한다.

IDirectDraw7::QueryInterface 메소드를 호출하는 것으로 취득할 수 있는 IDDVideoPortContainer 인터페이스는, 그 능력에 대한 하드웨어를 조회하거나 비디오 포트 오브젝트를 생성하기 위한 메소드를 제공한다. 비디오 포트 오브젝트를 생성 하려면 ,IDDVideoPortContainer::CreateVideoPort 메소드를 호출한다. 비디오 포트 오브젝트는,IDirectDrawVideoPort 인터페이스로부터 그 기능을 분명히 해, 비디오 포트 하드웨어 자체를 조작할 수 있도록(듯이) 한다. 이러한 인터페이스를 사용하는 것으로, 비디오 포트의 능력을 조사하거나 이미지 데이터를 받는 오버레이 표면을 지정하거나 비디오의 재생을 시작/정지하거나 크로핑, 컬러 컨트롤, 스케일링, 수축등의 이펙트를 이미지 데이터에 붙이기 위해서(때문에) 처리하는 하드웨어 파라미터를 설정할 수 있다.

DirectDraw 비디오 포트 확장 기능은, 복수의 DirectDrawVideoPort 오브젝트를 생성 하는 것으로써, 동일 머신상에 복수의 비디오 포트를 제공한다. 동일 머신 위에의 복수의 비디오 포트가 같은 필요는 없다. 즉, 각각의 포트는 하드웨어의 차이의 유무에 관계없이, 개별적으로 열거되어 따로 따로 구성된다.

DirectX 의 일반적인 생각에 따르는 이 기술에 의해, 프로그래머는 하드웨어 기능에 하위 레벨의 액세스를 실시할 때, 이러한 기능을 특정의 하드웨어 이행의 상세로부터 분리할 수 있다. 하이레벨의 API 는 아니다.


비디오 프레임과 필드

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic for DirectX 7.0 에서는 비디오 포트를 지원 하고 있지 않다.

[C++]

비디오는, 인터 레이스 방식에서도 비인터 레이스 방식에서도 가능하다. 비디오 신호가 인터 레이스 방식인 경우, 각각의비디오 프레임 은 이미지 데이터의 2 개의필드 로부터 된다. 각 필드는, 메이지의 최초 또는 2 번째의 주사선으로부터 시작되는 1 행 간격의 주사선의 집합이다. 홀수 필드 (또는, 필드 1)로 불리는 최초의 필드에는, 최초의 주사선과 이미지의 마지막까지의 1 행 간격의 주사선에 대한 데이터가 포함된다. 같이짝수 필드 (또는, 필드 2)에는, 2 번째의 주사선으로부터 시작되는 1 행 간격의 주사선에 대한 데이터가 포함된다. 필드의 "짝수" 또는 "홀수" 는,필드극성으로 불린다.

비디오가 비인터 레이스 방식인 경우, 각각의 필드에는 프레임의 주사선 모든 것이 포함된다. 일반적으로, 비디오 신호는, 매초 30 프레임의 속도로 보내진다. 인터 레이스 방식 비디오의 경우, 이것은 매초 60 필드의 속도로 보내진다.

프레임을 구성하는 필드는, 시간에 같은 순간을 반영할 필요는 없다. 예를 들어, 그 프레임이 1/30 초에 단락지어지는 경우, 1 개의 프레임에 있어서의 2 개의 필드는 1/60 초에 단락지어지고 있게 된다. 텔레비젼에서는 각각의 필드를 개별적으로 표시하기 위해(때문에), 2 개의 필드가 동시에 보일 것은 없고, 필드간의 상위가 움직임에 대한 일루젼을 일으킨다.


HREF, VREF, 및 connection

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic for DirectX 7.0 에서는 비디오 포트를 지원 하고 있지 않다.

[C++]

모니터 또는 다른 디스플레이 디바이스가 이미지를 표시하고 있는 경우, 일반적으로 왼쪽에서 오른쪽, 위에서 밑으로 이미지를 생성 해, 스크린을 하부에 스캔 한다 (1 개의 이미지를 생성 하는데, 디바이스가 스크린의 하부에 2 개씩 스캔 하는 일도 있다. 이 타입의 디스플레이는, 인터 레이스 방식 디스플레이로 불린다). 비디오 스트림에는, 새로운 라인 또는 새로운 스크린을 드로잉(Drawing) 하면나무를 디스플레이 디바이스에 지시하는 신호가 포함된다.

hsync 및 vsync 라고도 불리는 HREF 및 VREF 는, 디스플레이 디바이스에 무엇을 언제 실시할까를 알리는 비디오 스트림내의 신호이다. HREF 는 새로운 라인을 드로잉(Drawing) 하는 것을 알려 VREF 는 새로운 스크린을 드로잉(Drawing) 하는 것을 알린다.

예를 들어, 세계 최소의 모니터용 비디오 신호를 취급하고 있다고 한다. 모니터에는 4 주사선 밖에 없다 (물론, 이것은 완전히 현실적이지 않지만, 취급이 간단하게 된다). 오실로스코프(oscilloscope)에서는, HREF 및 VREF 신호가 다음의 그림에 나타내게 되는 것이라고 생각된다.

위의도로, HREF 및 VREF 신호는 모두 "액티브 하이" 이다. 이것은, 이러한 신호가 강조 상태 (파형이 상승 하면나무) 때에, 액티브하게 된다고 생각된다. 이러한 신호에 대한 표준은 존재하지 않는다. 파형이 하강하는 장소 ("로" 상태)에서 액티브한 HREF 또는 VREF 의 신호를 보내는 경우가 있다. 또, 한편이 액티브 하이로 이제(벌써) 한편이 액티브 로인 일도 있다. 위의도는 상상 위에의예에 지나지 않지만, 각각의 VREF 에 대해서 다수의 HREF 신호가 존재하는 것에 주의한다. 그 이유는, 각각의 새로운 스크린에 대해서 몇개의 주사선이 존재하기 때문이다. 물론, 실제의 브로드캐스트에 대한 실제의 비디오 신호에서는, 1 개의 VREF 에 대해서 수백의 HREF 가 존재한다.

HREF 신호, VREF 신호, 및 비디오 데이터는, 물리 데이터 라인을 건너 디코더로부터 비디오 포트까지 전달된다. 많은 경우, 비디오 데이터용으로 몇개의 라인이 확보되고 있어 다른 라인도 HREF 신호나 VREF 신호를 전달하기 위한 전용으로서 사용되고 있다. 다만, 이러한 데이터 라인의 사용에 대한 표준은 없다.

connection는, 비디오 포트나 디코더가 이러한 데이터 라인의 사용을 정의하기 위해서 사용하는 프로토콜이다. 비디오 포트나 비디오 디코더는, 다양한 connection를 지원 한다. DirectDraw 비디오 포트 확장 기능은, GUID (globally-unique identifier)를 사용해 각각의 connection 타입을 식별한다. IDDVideoPortContainer::GetVideoPortConnectInfo 메소드를 호출하는 것으로, 비디오 포트가 지원 하는 connection를 조회할 수 있다. IDDVideoPortContainer::CreateVideoPort 메소드를 호출하는 것으로, 주어진 connection를 지원 하는 DirectDrawVideoPort 오브젝트를 생성 할 수 있다.

비디오 디코더는 DirectDraw 비디오 포트 확장 기능의 범위외이며, 그 자체의 인터페이스로부터 지원 되는 connection를 공개하는 것을 잊어서는 안된다. 비디오 포트가 지원 하는 connection를 열거해, 그 결과를 디코더의 지원 하는 connection와 비교하는 것으로, 양쪽 모두의 컴퍼넌트로 이해할 수 있는 공통 connection (혹은,"말")를 결정할 수가 있다.


수직귀선소각 간격 데이터

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic for DirectX 7.0 에서는 비디오 포트를 지원 하고 있지 않다.

[C++]

브로드캐스트 비디오에서는, 비디오 프레임간에 짧은 시간이 있다. 이전에, 디스플레이 디바이스는 다음의 프레임을 위해서(때문에) 디스플레이를 리프레쉬 한다. 이 시간은, 수직귀선소각 간격 (VBI)으로 불린다. 브로드캐스트 비디오는 VBI 의 사이에 아무것도 하지 않는 것이 아니고, 비디오 프레임에 있어서의 최초의 21 주사선의 데이터를 encode 해, VBI 의 사이에 이러한 주사선을 보낸다. 이 데이터는 자막 방송 (문자방송의 일종)이나 타임 스탬프의 기록에 이용되는 일이 있지만, 다른 목적으로 사용할 수도 있다.

DirectDraw 비디오 포트 확장 기능에 의해, VBI 로 포함되는 데이터를 표면에 보내거나 VBI 데이터의 스케일링을 우회도로 하거나 플립핑 체인의 VBI 표면간에 자동적으로 플립 할 수가 있다. 데이터가 표면에 들어가 버리면, 필요에 따라서 표면의 메모리에 직접 액세스 할 수 있다.

상세한 것에 대하여는, 「자동 플립핑」을 참조할것.


자동 플립핑

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic for DirectX 7.0 에서는 비디오 포트를 지원 하고 있지 않다.

[C++]

프레임간에 스크린을 리프레쉬 할 경우에티어링 이미지의 발생을 피하기 (위해)때문에, DirectDrawVideoPort 오브젝트는 VREF 신호에 응해, 그 타겟 오버레이 표면을 자동적으로 플립 할 수가 있다. 이 서비스를 이용하려면 ,IDirectDrawVideoPort::SetTargetSurface 메소드로 비디오 포트 오브젝트로 설정하는 타겟 표면이, 오버레이 표면의 플립핑 체인에 있어서의 최초의 표면으로 울 수 있는 구라고는 안 된다. 그 후, 비디오 순서를 재생하려면 , 관련지을 수 있었던 DDVIDEOPORTINFO 구조체의 dwVPFlags 멤버에 DDVP_AUTOFLIP 플래그를 지정해,IDirectDrawVideoPort::StartVideo 메소드를 호출한다. 비데오포트브제크트는, 각각의 VREF 신호의 수취에 대해서 플립핑 체인의 다음의 표면에 플립 한다. 비디오 포트가 인타리빙피르드인 경우, 2 개의 VREF 신호를 받을 때 마다 1 회 플립 한다.

자동 플립핑을 사용해, 개별의 자동 플립 표면에 VBI 데이터를 보내는 경우, 표준 비디오 표면의 경우와 같은 수의 VBI 표면을 준비해야 한다.


공통의 비디오의 문제의 회피 방법

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic for DirectX 7.0 에서는 비디오 포트를 지원 하고 있지 않다.

[C++]

텔레비젼 이외의 디스플레이 디바이스로, 브로드캐스트 비디오를 표시하는 경우, 특유의 문제가 몇개인가 생긴다. 여기에서는, 몇개의 일반적인 문제에 대해 간단하게 접해 계속되어 DirectDraw 비디오 포트 확장 기능이 이러한 문제를 어떻게 해결하려고 하고 있을까에 임해서 설명한다.

NTSC 인터 레이스 방식 디스플레이와 인터리브 메모리

NTSC 신호는, 매초 약 30 프레임, 또는 60 필드의 속도로 브로드캐스트 한다. 프레임과 같이, NTSC 신호의 필드는 프레임내의 다른 필드와는 독립하고 있어, 다른 이미지 데이터를 포함할 수가 있다. 이 동작의 상세한 것에 대하여는, 「비디오 프레임과 필드」를 참조할것.

프레임내의 필드의 독립성에 기인하는 문제는, 2 개의 필드가 디스플레이에 대해서 인터리브 될 때 생긴다. 움직임이 많은 비디오에서는, 1 개의 프레임에 있어서의 2 개의 필드에서 서로 적합하지 않는 이미지를 포함하게 되어, 동작 이상이 생긴다.

이 동작 이상을 회피하기 위해서, 개발자는 필드의 1 개를 파기 하면 말하는 방법을 취할 수가 있다. 이 해결법에서는 이미지의 질이 약 반에 떨어지지만, 목적에 따라서는 허용 범위내이다. 이 해결법 외에 자주(잘) 빼앗기는 방법은, 표시할 때에 각각의 필드를 세로에 2 배에 늘려 개별적으로 필드를 표시하는 것이다. 이 방법에서는 이미지의 질은 좋아지지만, 필드가 y 방향으로 1 픽셀분 오프셋(offset) 되기 (위해)때문에, 애니메이션을 재생할 경우에 상하에 "지터- (부들부들 진동)" 가 생긴다.

DirectDraw 비디오 포트 확장 기능에서는, 이미지의 질을 개선하기 위해서,"Bob" 및 "Weave" 로 불리는 2 개의 것보다 고도의 기술을 사용할 수 있다. 양쪽 모두, 비디오 포트 확장 기능과 함께 사용되는 DirectDraw 오버레이 표면에 의해 지원 되고 있다.

최초의 알고리즘 Bob 는, 프레임의 각각의 필드를 개별적으로 표시하는 메소드와 매우 비슷하다. 다만, 각각의 필드에 대해서, 오버레이의 전송원직사각형은 지터-이펙트에 적응하도록(듯이) 조정된다. 실제, 전송원직사각형은, 스크린 위에의 지터-를 지우면서 필드와 함께 상하한다. 다음의 그림으로 이 프로세스를 나타낸다.

Weave 알고리즘은, 동영상을 텔레비젼으로 변환하기 위해서(때문에) 비디오 산업계에서 사용되는 일반적인 기술을 사용해, 영화의 오리지날 소재에 대해서 최선의 이미지 품질을 제공한다. Bob 과는 달리, 비디오 포트 오브젝트는 그 자체로 조립해 갈 것은 없다. 이 알고리즘을 실현하려면 , 양필드를 동시에 표시하는 디폴트 오버레이 동작과 커널 모드 비디오 전송 (Windows NT 2000 으로 Windows 98 으로 제공된다)을 조합하지 않으면 안 된다.

완전을 기하기 (위해)때문에, 여기서 알고리즘의 개략을 설명한다. 동영상은, 매초 24 프레임의 속도로 비디오가 캡춰 되고 있다. 동영상을 텔레비젼으로 변환하는 경우, 기술자는 3:2 풀다운으로 불리는 기술을 사용해, 프레임 속도를 텔레비젼 방송용으로 매초 30 프레임으로 변환한다. 이 기술에서는, 필요하게 되는 필드수로 하기 위해서(때문에), 비디오 스트림에 있어서의 4 살의 진짜의 필드 마다 1 개의 장황 필드를 삽입하고 있다.

조립하는 경우는, 이 프로세스를 반대로 실시한다. 3:2 풀다운이 사용되는 경우, 장황 필드를 삭제해 원의 동영상 프레임을 restore 한다. restore 된 프레임을 구성하는 필드는, 동작 이상을 일으키는 일 없이 메모리로 인터리브 할 수가 있다. 원의 필름내의 편집이나 릴 파손을 위해서(때문에), 장황 프레임의 패턴이 바뀌는 경우가 있다. 이러한 변화가 생길 때 모니터 해, 동작을 갱신해 새로운 패턴에 조정할 필요가 있다.

디폴트에서는, 오버레이 표면은 양필드를 동시에 표시한다. Weave 알고리즘을 사용하고 있는 경우는 잘 기능하지만, 비디오 포트가 Bob 알고리즘을 사용할 수 없게 된다. IDirectDrawSurface7::UpdateOverlay 메소드를 호출하는 것으로, 오버레이가 비디오 데이터를 처리하는 방법을 프로그램에 근거해 변경할 수 있다. 오버레이의 동작은,dwFlags 파라미터의 플래그에 의해 결정된다. DDOVER_BOB 플래그를 지정 하면, 비디오 포트는 Bob 알고리즘을 사용한다. 플래그를 지정하지 않으면, 양필드를 표시한다. 단지 양필드를 동시에 표시 하면, 비디오로 동작 이상이 생기는 것에 주의한다.


하프 라인에 의해 일으켜지는 문제의 해결

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic for DirectX 7.0 에서는 비디오 포트를 지원 하고 있지 않다.

[C++]

비디오 디코더에 따라서는,짝수 필드의 처음에 의미가 없는 데이터의 하프 라인을 출력하는 일이 있다. 이 여분의 라인이 frame buffer에 기입해지면(자), 그 결과로 생기는 이미지는 왜곡한 것처럼 보인다. 이러한 경우, frame buffer에 기입하기 전에, 비디오 포트 하드웨어에서는 이 데이터를 감지해 파기할 수가 있다.

IDDVideoPortContainer::GetVideoPortConnectInfo 메소드를 사용해 connection 정보를 취득할 때에, 비디오 포트가 이 데이터를 파기할 수 있을지 어떨지를 결정할 수 있다. 비디오 포트가 하프 라인을 파기할 수 없는 경우는, DDVPCONNECT_HALFLINE 플래그가, 지원 되는 각 connection에 관련지을 수 있었던 DDVIDEOPORTCONNECT 구조체의 dwFlags 멤버로 지정된다.

비디오 포트가 하프 라인을 파기할 수 없는 경우에, 2 개의 옵션이 준비되어 있다. 필드의 1 개를 파기하는지, 비디오 포트 오브젝트의 생성 방법이나 타겟 오버레이 표면으로 이미지를 표시하는 방법을, 얼마인가 조절해 하드웨어의 제한을 회피한다.

이 문제를 회피하는 방법을 설명한다. IDDVideoPortContainer::CreateVideoPort 메소드를 호출해 비디오 포트 오브젝트를 생성 하는 경우, 관련지을 수 있었던 DDVIDEOPORTCONNECT 구조체의 dwFlags 멤버에, DDVPCONNECT_INVERTPOLARITY 플래그를 포함한다. 이것에 의해, 비디오 포트는 비디오 스트림의필드의 극성을 반전해, 짝수 필드를 홀수 필드와 같이, 또는 홀수 필드를 짝수 필드와 같이 처리한다. 반전되어 버리면(자), 짝수 필드의 앞의 하프 라인은, 각 프레임의 최초의 주사선으로서 frame buffer에 기입해진다. 의미가 없는 데이터를 삭제하려면 , 필요한 좌표와 함께 IDirectDrawVideoPort::StartVideo 메소드를 호출하는 것으로, 이미지를 표시하기 위해서 사용되는 오버레이 표면의 전송원직사각형을 1 픽셀분만큼 아래에 이동시킨다. 이 기술을 사용하는 경우, 짝수 필드를 포함한 표면에 여분의 1 라인을 할당하지 않으면 안 되는 것에 주의한다.


하드웨어 기능의 이용

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic for DirectX 7.0 에서는 비디오 포트를 지원 하고 있지 않다.

[C++]

비디오 포트 하드웨어에 따라서는, 색조정, 이미지의 축소나 확대, VBI 데이터 처리, 필드의 스킵등이 특별한 기능을 지원 한다. HAL 는,DDVIDEOPORTCAPS 구조체로 플래그를 사용하는 것으로, 이러한 기능에 대한 정보를 제공한다. 머신의 비디오 포트 하드웨어의 능력을 취득하려면 ,IDDVideoPortContainer::EnumVideoPorts 메소드를 호출한다.

재생용의 이러한 기능을 이용하려면 ,IDirectDrawVideoPort::StartVideo 메소드를 사용한다. 이 메소드는 DDVIDEOPORTINFO 구조체를 사용해, 이미지 데이터를 frame buffer에 배치하거나 표시하기 전에, 그 데이터를 수정하기 위해서 하드웨어 기능을 요구한다. 이 구조체에 값이나 플래그를 설정하는 것으로써, 오버레이 표면과 함께 사용되는 전송원직사각형을 지정하거나 크로핑 영역을 나타내거나 하드웨어 스케일링을 요구하거나 픽셀 포맷을 설정할 수가 있다.

DirectDrawVideoPort 오브젝트는, 비디오 포트 하드웨어 서비스를 에뮬레이트 하지 않는다.


refresh rate의 열거

DirectDraw 는, 모니터로부터 확장 디스플레이 식별 데이터 (EDID)를 읽어내, refresh rate를 열거한다. EDID 가 없으면 DirectDraw 는 스테레오 뷰에 필요한 높은 refresh rate를 사용하려고 한다. DirectDraw 에 의한 스테레오 뷰의 지원에 대해서는, 「스테레오 뷰」를 참조할것.

특정의 모드의 refresh rate를 취득할 필요가 있는 경우는,IDirectDraw7::StartModeTest 및 IDirectDraw7::EvaluateMode 메소드를 사용해 그 모드를 테스트할 수 있다. StartModeTest 및 EvaluateMode 가 EDID 를 조사해, 모니터가 지원 하고 있는 모드를 확인해, 특정의 refresh rate가 유효한가 어떤가를 유저가 체크할 수 있도록(듯이) 할 수가 있다.


플립핑과 블리트 상태 취득

[C++]

IDirectDrawSurface7::Flip 메소드가 불려 가면(자),프라이머리 표면과백 버퍼가 교환된다. 다만, 이 교환은 곧바로 행해지지 않는다. 예를 들어, 전회의 플립이 종료하고 있지 않는가 성공하지 않았던 경우, 이 메소드는 DDERR_WASSTILLDRAWING 를 돌려준다. 이 SDK 에 포함되는 샘플에서는,IDirectDrawSurface7::Flip 의 호출은, DD_OK 가 돌려주어질 때까지 루프 계속 한다. 또,IDirectDrawSurface7::Flip 의 호출도 곧바로는 완료하지 않는다. 시스템으로 수직귀선소거가 생긴 후에, 플립핑이 실행된다.

DDERR_WASSTILLDRAWING 가 돌려주어지고 없어질 때까지 기다리는 어플리케이션은 효율이 나쁘다. 대신에, 플립핑이 종료했는지 어떠했는지를 결정하는 백 버퍼로 IDirectDrawSurface7::GetFlipStatus 메소드를 호출하는 어플리케이션의 함수를 생성 해야 하는 것이다.

전회의 플립핑이 종료하지 않고 , 호출로 DDERR_WASSTILLDRAWING 가 돌아가는 경우, 어플리케이션에서는 스테이터스를 다시 조사하기 전에, 다른 태스크를 실행할 수 있다. 혹은, 다음의 플립핑을 실행할 수 있다. 다음의 예로 이 개념을 설명한다.

while(lpDDSBack->GetFlipStatus(DDGFS_ISFLIPDONE) ==
    DDERR_WASSTILLDRAWING);

    // 전회의 플립핑이 종료할 때까지 기다린다. 어플리케이션은,
    // 여기서 다른 태스크를 실행할 수가 있다.

ddrval = lpDDSPrimary->Flip(NULL, 0);

블리트가 종료했는지 어떠했는지를 판단하기 위해서(때문에), 같은 방법으로 IDirectDrawSurface7::GetBltStatus 메소드를 사용할 수 있다. IDirectDrawSurface7::GetFlipStatus 와 IDirectDrawSurface7::GetBltStatus 는 곧바로 돌아가기 (위해)때문에, 어플리케이션으로 주기적으로 사용해도, 거의 속도는 저하하지 않는다.

[Visual Basic]

DirectDrawSurface7.Flip 메소드가 불려 가면(자),프라이머리 표면과백 버퍼가 교환된다. 다만, 이 교환은 곧바로 행해지지 않는다. 예를 들어, 전회의 플립이 종료하고 있지 않는가 성공하지 않았던 경우, 이 메소드는 DDERR_WASSTILLDRAWING 에러를 돌려준다.

DDERR_WASSTILLDRAWING 가 돌려주어지고 없어질 때까지 기다리는 어플리케이션은 효율이 나쁘다. 대신에, 플립핑이 종료했는지 어떠했는지를 결정하는 백 버퍼로 DirectDrawSurface7.GetFlipStatus 메소드를 호출하는 어플리케이션의 함수를 생성 해야 하는 것이다.

전회의 플립핑이 종료하지 않고 , 호출로 DDERR_WASSTILLDRAWING 가 돌아가는 경우, 어플리케이션에서는 스테이터스를 다시 조사하기 전에, 다른 태스크를 실행할 수 있다. 혹은, 다음의 플립핑을 실행할 수 있다. 다음의 예로 이 개념을 설명한다.

while(DDSBack.GetFlipStatus(DDGFS_ISFLIPDONE) =
    DDERR_WASSTILLDRAWING)

'전회의 플립핑이 종료할 때까지 기다린다. 어플리케이션은,
'여기서 다른 태스크를 실행할 수가 있다.

DDSPrimary->Flip(NOTHING, 0)

블리트가 종료했는지 어떠했는지를 판단하기 위해서(때문에), 같은 방법으로 DirectDrawSurface7.GetBltStatus 메소드를 사용할 수 있다. DirectDrawSurface7.GetFlipStatus 와 DirectDrawSurface7.GetBltStatus 는 곧바로 돌아가기 (위해)때문에, 어플리케이션으로 주기적으로 사용해도, 거의 속도는 저하하지 않는다.


디스플레이 하드웨어 능력의 결정

DirectDraw 는 유저의 하드웨어가 지원 하지 않는 DirectDraw 함수를 실행하기 위해서, 소프트웨어 에뮬레이션을 사용한다. DirectDraw 어플리케이션의 퍼포먼스를 향상시키려면 , DirectDraw 오브젝트를 생성 한 다음에, 유저의 디스플레이 하드웨어의 능력을 결정한다. 그 후, 가능하면, 이러한 능력을 이용하는 프로그램을 구축한다.

[C++]

이 능력을 결정하려면 ,IDirectDraw7::GetCaps 메소드를 사용한다. 모든 하드웨어 기능이 에뮬레이션으로 지원 되는 것은 아니다. 어느 특정의 하드웨어만으로 지원 되는 기능을 이용하려면 , 그 기능이 없는 하드웨어의 시스템에 대해서, 어떠한 대신의 수단을 제공할 준비도 필요하다.

[Visual Basic]

이 능력을 결정하려면 ,DirectDraw7.GetCaps 메소드를 사용한다. 모든 하드웨어 기능이 에뮬레이션으로 지원 되는 것은 아니다. 어느 특정의 하드웨어만으로 지원 되는 기능을 이용하려면 , 그 기능이 없는 하드웨어의 시스템에 대해서, 어떠한 대신의 수단을 제공할 준비도 필요하다.


디스플레이 메모리에서의 비트 맵의 저장

디스플레이 메모리로부터 디스플레이 메모리에의블리트는, 시스템 메모리로부터 디스플레이 메모리에의 전송보다 아득하게 효율적이다. 이 때문에, 어플리케이션으로 사용하는 것으로 올 뿐(만큼) 많은 스프라이트를 디스플레이 메모리에 저장 하는 것이 좋다.

[C++]

많은 디스플레이 어댑터 하드웨어에는,프라이머리 표면과백 버퍼 이외를 저장 하는 충분한 메모리가 있다. 디스플레이 어댑터의 메모리에 비트 맵을 저장 하는 이용 가능한 메모리 용량을 결정하려면 ,IDirectDraw7::GetAvailableVidMem 메소드를 호출한다. 이 메소드의 호출 후,lpdwTotal 파라미터에는, 전디스플레이 메모리량 (드라이버로 보관 유지하는 프라이머리 표면과 Private 캐쉬를 제외하다)이 포함된다. 그리고,lpdwFree 파라미터에는, 현재의 디스플레이 메모리의 빈 용량이 포함된다. 이 빈 용량은,lpDDSCaps2 로 구조체에 의해 지정되는 능력을 적합하는 표면에 할당할 수 있다.

[Visual Basic]

많은 디스플레이 어댑터 하드웨어에는,프라이머리 표면과백 버퍼 이외를 저장 하는 충분한 메모리가 있다. 디스플레이 어댑터의 메모리에 비트 맵을 저장 하는 이용 가능한 메모리 용량을 결정하려면 ,DirectDraw7.GetAvailableTotalMem 메소드를 호출한다. 이 메소드는,DDSCAPS2 형으로 지정된 능력과 일치하는 표면의 전디스플레이 메모리량 (드라이버로 보관 유지하는 프라이머리 표면과 Private 캐쉬를 제외하다)을 돌려준다.


트리플 버퍼링

[C++]

어느 특정의 상황, 즉 디스플레이 어댑터에 충분한 메모리가 있는 경우에는, 트리플 버퍼링에 의해, 어플리케이션의 표시 처리를 고속화할 수 있다. 트리플 버퍼링은, 1 개의프라이머리 표면과 2 개의백 버퍼를 사용한다. 다음의 예로, 트리플 버퍼링 스킴을 초기화하는 방법을 나타낸다.

// lpDDSPrimary 와 lpDDSBack 변수는, 글로벌하게 선언했다
// 초기화하고 있지 않는 LPDIRECTDRAWSURFACE4 변수이다.
//
// lpDD 변수는, IDirectDraw4 인터페이스에의 포인터이다.

DDSURFACEDESC2 ddsd;
ZeroMemory (&ddsd, sizeof(ddsd));

// 2 개의 백 버퍼와 함께 프라이머리 표면을 생성 한다.
ddsd.dwSize = sizeof(ddsd);
ddsd.dwFlags = DDSD_CAPS | DDSD_BACKBUFFERCOUNT;
ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE |
    DDSCAPS_FLIP | DDSCAPS_COMPLEX;
ddsd.dwBackBufferCount = 2;
ddrval = lpDD->CreateSurface(&ddsd, &lpDDSPrimary, NULL);

// 플립핑 체인의 생성에 성공하면(자),
// 플립핑이나 블리트에 필요한
// 표면에의 포인터를 취득한다.
if(ddrval == DD_OK)
{
// 프라이머리 (백 버퍼)에 직접 Attach 되는 // 표면을 취득한다.
    ddsd.ddsCaps.dwCaps = DDSCAPS_BACKBUFFER;
    ddrval = lpDDSPrimary->GetAttachedSurface(&ddsd.ddsCaps,
        &lpDDSBack);
    if(ddrval ! = DD_OK) ;
// 여기서 에러 메세지를 표시한다.
}

트리플 버퍼의 플립핑 체인에 있는 표면에 대해, 그 모든 것을 조사할 필요는 없다. 보관 유지하고 있지 않으면 안 되는 것은, 프라이머리 표면과 백 버퍼 표면에의 포인터 뿐이다. 프라이머리 표면에의 포인터는, 플립핑 체인의 표면을 플립 하기 위해서 필요하다. 또, 백 버퍼에의 포인터는, 블리트를 위해서(때문에) 필요하다. 상세한 것에 대하여는, 「플립핑 표면」을 참조할것.

플립핑이 종료하지 않고 ,백 버퍼의 블리트가 이미 종료하고 있는 경우, 트리플 버퍼링에 의해, 어플리케이션은 백 버퍼에 블리트 계속 할 수가 있다. 플립핑의 실행은 동기 이벤트는 아니다. 즉, 어느 플립핑에 다른 플립핑 이상이 시간을 들일 수가 있다. 이 때문에, 어플리케이션이 1 개의 백 버퍼만을 사용하는 경우,IDirectDrawSurface7::Flip 메소드가 DD_OK 를 돌려줄 때까지 기다리는 동안, 아이들링 시간이 걸릴 가능성이 있다.

[Visual Basic]

어느 특정의 상황, 즉 디스플레이 어댑터에 충분한 메모리가 있는 경우에는, 트리플 버퍼링에 의해, 어플리케이션의 표시 처리를 고속화할 수 있다. 트리플 버퍼링은, 1 개의프라이머리 표면과 2 개의백 버퍼를 사용한다. 다음의 예로, 트리플 버퍼링 스킴을 초기화하는 방법을 나타낸다.

' DDSPrimary 와 DDSBack 변수는,
'글로벌하게 선언한 DIRECTDRAWSURFACE7 변수이다.
'
' DD 변수는, DirectDraw7 오브젝트이다.

Dim ddsd As DDSURFACEDESC2

' 2 개의 백 버퍼와 함께 프라이머리 표면을 생성 한다.
ddsd.lFlags = DDSD_CAPS Or DDSD_BACKBUFFERCOUNT
ddsd.ddsCaps.lCaps = DDSCAPS_PRIMARYSURFACE Or _
DDSCAPS_FLIP Or DDSCAPS_COMPLEX
ddsd.lBackBufferCount = 2
DDSPrimary = DD.CreateSurface(ddsd)

'플립핑 체인의 생성에 성공하면(자),
'플립핑과 블리트에 필요한 표면을 취득한다.
'프라이머리 (백 버퍼)에 직접 Attach 되는 표면을 취득한다.
ddsd.ddsCaps.lCaps = DDSCAPS_BACKBUFFER
DDSBack = DDSPrimary.GetAttachedSurface(ddsd.ddsCaps)

트리플 버퍼의 플립핑 체인에 있는 표면에 대해, 그 모든 것을 조사할 필요는 없다. 보관 유지하고 있지 않으면 안 되는 것은, 프라이머리 표면과 백 버퍼 표면에의 포인터 뿐이다. 프라이머리 표면에의 포인터는, 플립핑 체인의 표면을 플립 하기 위해서 필요하다. 또, 백 버퍼에의 포인터는, 블리트를 위해서(때문에) 필요하다. 상세한 것에 대하여는, 「플립핑 표면」을 참조할것.

플립핑이 종료하지 않고 ,백 버퍼의 블리트가 이미 종료하고 있는 경우, 트리플 버퍼링에 의해, 어플리케이션은 백 버퍼에 블리트 계속 할 수가 있다. 플립핑의 실행은 동기 이벤트는 아니다. 즉, 어느 플립핑에 다른 플립핑 이상이 시간을 들일 수가 있다. 이 때문에, 어플리케이션이 1 개의 백 버퍼만을 사용하는 경우,DirectDrawSurface7.Flip 메소드가 성공할 때까지 기다리는 동안, 아이들링 시간이 걸리는 경우가 있다.


DirectDraw 어플리케이션과 윈도우 스타일

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

어플리케이션이 윈도우 모드로 DirectDraw 를 사용하는 경우, 모든 윈도우 스타일을 생성 할 수가 있다. 다만, 풀 스크린 배타 모드의 어플리케이션에서는, 예측 불가능한 동작을 일으키는 일 없이 WS_EX_TOOLWINDOW 스타일을 생성 할 수가 없다. WS_EX_TOOLWINDOW 스타일에서는, 윈도우를 DirectDraw 의 풀 스크린 배타 모드 어플리케이션으로 필요하게 되는 최상정도 윈도우로 할 수가 없다.

풀 스크린 배타 모드 어플리케이션에서는, 적절한 표시를 하기 위해서, WS_EX_TOPMOST 확장 윈도우 스타일과 WS_VISIBLE 윈도우 스타일을 사용하도록(듯이) 한다. 이러한 스타일은, 이 어플리케이션을 윈도우 Z 오더의 맨앞줄에 유지해, GDI 가 프라이머리 표면에 드로잉(Drawing) 하는 것을 저지한다.

다음의 예에서는, 풀 스크린 배타 모드 어플리케이션으로 사용하는 윈도우를 확실히 준비하는 방법을 나타낸다.

////////////////////////////////////////////////////////
// 윈도우 클래스의 등록과 윈도우의 표시
////////////////////////////////////////////////////////
BOOL WINAPI InitApp(INT nWinMode)
{
    WNDCLASSEX wcex;

    wcex.cbSize           =    sizeof(WNDCLASSEX);
    wcex.hInstance        =    g_hinst;
    wcex.lpszClassName    =    g_szWinName;
    wcex.lpfnWndProc      =    WndProc;
    wcex.style            =    CS_VREDRAW|CS_HREDRAW|CS_DBLCLKS;
    wcex.hIcon            =    LoadIcon (NULL, IDI_APPLICATION);
    wcex.hIconSm          =    LoadIcon (NULL, IDI_WINLOGO);
    wcex.hCursor          =    LoadCursor (NULL, IDC_ARROW);
    wcex.lpszMenuName     =    MAKEINTRESOURCE(IDR_APPMENU);
    wcex.cbClsExtra       =    0 ;
    wcex.cbWndExtra       =    0 ;
    wcex.hbrBackground    =    GetStockObject (NULL_BRUSH);

    RegisterClassEx(&wcex);

    g_hwndMain = CreateWindowEx(
                        WS_EX_TOPMOST,
                        g_szWinName,
                        g_szWinCaption,
                        WS_VISIBLE|WS_POPUP,
                        0,0,0,0,
                        NULL,
                        NULL,
                        g_hinst,
                        NULL);

    if(! g_hwndMain)
        return(FALSE);

    SetFocus(g_hwndMain);
    ShowWindow(g_hwndMain, nWinMode);
    UpdateWindow(g_hwndMain);

    return TRUE;
}


frame buffer의 색공간(color space)에의 트루 RGB 색의 적합

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

디스플레이 디바이스가 트루 RGB 색 (RGB 888) 모드가 아닐 때에, 어플리케이션에서는, frame buffer의 색공간(color space)에 RGB 888 을 맵 하는 방법을 찾아내는 것이 필요한 경우가 있다. 예를 들어, 16 비트 또는 24 비트 RGB 디스플레이 모드로 실행하는 어플리케이션의 경우를 생각한다. 어느 작품이 생성 되면(자), 투과형 블리트 컬러 키로서 사용하기 위해서 색이 확보된다. 설명을 위해서(때문에), 여기에서는 RGB (128,64,255)와 같은 24 비트 컬러로 한다. 어플리케이션이 16 비트 RGB 모드에서도 실행할 수 있도록(듯이) 하기 위해서, 16 비트 RGB 모드로 실행하는 경우에 사용하는 frame buffer의 색공간(color space)에 이 24 비트 컬러를 맵 하는 방법을 찾아낼 필요가 있다.

DirectDraw 에서는 컬러 매칭 서비스를 실시하지 않지만, 컬러 키가 frame buffer에 맵핑 되는 계산에 있어서의 몇개의 방법이 준비되어 있다. 이러한 방법은, 모두 꽤 복잡하다. 대부분의 경우, GDI 내장의 컬러 매칭 서비스를 DirectDraw 직접 frame buffer 액세스와 조합해 사용하는 것으로, 색의 값을 다른 색공간(color space)에 맵 하는 방법을 결정할 수 있다. 실제, 플랫폼 SDK 의 DirectX 의 예에 있는 Ddutil.cpp 소스 파일에는, 이 태스크를 실행하는 DDColorMatch 라고 하는 샘플 함수가 포함되어 있다. DDColorMatch 샘플 함수는, 이하의 주된 태스크를 실시한다.

  1. 표면의 0,0 에 있는 픽셀의 색의 값을 취득한다.
  2. 24 비트 RGB 색을 기술하는 COLORREF 구조체를 사용해, Win32 SetPixel 함수를 호출한다.
  3. DirectDraw 를 사용해 표면을 잠그어, frame buffer 메모리에의 포인터를 취득한다.
  4. frame buffer (GDI 에 의해 스텝 2 로 설정되었다)로부터 실제의 색의 값을 취득해, 표면의 락을 해제한다.
  5. SetPixel 를 사용해, 0,0 의 픽셀을 원의 색에 리셋 한다.

DDColorMatch 샘플 함수로 사용되는 프로세스는 빠르지 않다. 속도를 의도한 것은 아니기 때문에이다. 다만, 색을 다른 RGB 색공간(color space)에 맵 하는 방법을 결정하려면 신뢰성의 높은 방법이다. 상세한 것에 대하여는, Ddutil.cpp 소스 파일에 있는 DDColorMatch 의 소스 코드를 참조할것.

주 ： SetPixel GDI 함수는 입력에 대한 COLORREF 구조체를 받을 뿐(만큼)이므로, 이 기술은 RGB 888 컬러를 frame buffer의 픽셀 포맷에 적합하기 위해(때문에)인 만큼 작용한다. 어플리케이션으로 다른 픽셀 포맷의 색을 적합하지 않으면 안 되는 경우, 이 기술을 사용하거나 픽셀 포맷에 대한 프라이머리 표면을 참조하기 전에, RGB 888 에 전송 해, 수동으로 색을 적합해야 한다.


풀 스크린 모드에서의 윈도우의 표시

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

풀 스크린 모드에서는, DirectDraw 는 표시를 배타적으로 제어한다. 이 때문에, GDI 에 의해 생성 되는 다이알로그 박스나 그 외의 윈도우는 보통 표시되지 않는다. 다만, 특수한 방법을 사용하면, Windows 의 다이알로그 박스, HTML 헬프나, 어플리케이션내의 그 외의 윈도우를 표시할 수가 있다.

FSWindow 샘플에서는, 풀 스크린 어플리케이션으로 다이알로그 박스를 표시 및 갱신하는 방법이나,GDI 에 의해 표시된 다이알로그 박스와 같게 마우스나 키보드 입력을 받아들이는 방법을 나타낸다.

FSWindow 에서는, 보통의 다이얼로그 윈도우와 같게 다이알로그 박스가 생성 되어 표시된다.

hWndDlg = CreateDialog(g_hInstance,
MAKEINTRESOURCE(IDD_DIALOG_SAMPLE),
hWnd, (DLGPROC) SampleDlgProc);
ShowWindow(hWndDlg, SW_SHOWNORMAL);

물론, 이 시점에서는, 다이알로그 박스는 숨어 있는 GDI 표면에 의해 표시되어 Direct Draw 에 의해 제어되는 프라이머리 표면에는 표시되지 않는다.

하드웨어 능력에 DDCAPS2_CANRENDERWINDOWED 가 포함되는 경우, ( 「DDCAPS 」참조) 다이알로그 박스의 표시와 갱신을 용이하게 실행할 수 있다. 어플리케이션은,IDirectDraw7::FlipToGDISurface 메소드를 호출하는 것만으로, GDI 표면을 프라이머리 표면으로 할 수 있다. 그것 이후는, GDI 가 직접 프런트 버퍼에 렌더링 되므로, 다이알로그 박스에 대한 변경은 모두 자동적으로 표시된다. 어플리케이션은 백 버퍼에의 렌더링을 계속해 각 패스상에서 렌더링 루프에 의해 DirectDraw 가 백 버퍼의 내용을 프런트 버퍼에 블리트 한다. 프런트 버퍼가 어플리케이션 윈도우에 클립 되어 다이알로그 박스가 그 윈도우의 일부를 덮어 가리므로, 다이알로그 박스가 덧쓰기될 것은 없다.

이하의 코드는 FSWindow_Init 함수의 일부이다. 이것에 의해, 클립퍼를 생성 해, 어플리케이션 윈도우에 관련지어, GDI 표면을 전면에 표시한다.

if (ddObject->CreateClipper(0, &ddClipper, NULL) == DD_OK)
ddClipper->SetHWnd(0, hwndAppWindow);
ddObject->FlipToGDISurface();

다음에, FSWindow_Update 함수의 이하의 코드에 의해, 렌더링 된 백 버퍼의 컨텐츠를 클리핑 영역에 블리트 한다.

ddFrontBuffer->SetClipper(ddClipper);
ddFrontBuffer->Blt(NULL, ddBackBuffer, NULL, DDBLT_WAIT, NULL);

GDI 표면이 프라이머리 표면이므로, Windows 에 의해 마우스 커서가 표시된다 (다만, 어플리케이션이 배타 협조 레벨로 마우스에 의한 직접 입력을 사용하고 있는 경우는 제외하다).

DDCAPS2_CANRENDERWINDOWED 능력을 가지지 않는 하드웨어에서는, 풀 스크린 모드에서의 윈도우의 표시와 갱신 처리가 약간 복잡하게 된다. 이 경우, GDI 에 의해 생성 된 윈도우의 이미지를 어플리케이션이 취득해, 풀 스크린 렌더링이 실행된 다음에 백 버퍼에 블리트 한다. 그 후로, 백 버퍼 전체가 보통의 방법으로 프런트에 플립 된다.

FSWindow 샘플에서는, 컨텐츠가 정적인가 동적인가에 응해, 윈도우의 디스플레이 메모리에 액세스 하는 2 개의 방법을 나타낸다. 정적 컨텐츠의 방법이, 스크린 디바이스 콘텍스트는 아니고 메모리 디바이스 콘텍스트로부터 블리트를 실시하므로, 보다 고속으로 된다. 정보 표시용의 다이알로그 박스 등, 변경하지 않는 윈도우에는 이 방법을 사용해야 한다 (다만, 이벤트에 응답하는 비트 맵을 수동으로 갱신하지 않는 한, 버튼이 밀린 상태가 되는 것 같은 기본적인 애니메이션도 유저에게는 표시되지 않기 때문에 주의 해야 한다).

정적 컨텐츠의 경우, 윈도우의 초기화시에 FSWindow 가 CreateBMPFromWindow 함수를 호출한다. 이 함수는, 비트 맵을 생성 해, 윈도우의 컨텐츠를 그 비트 맵에 블리트 한다. 비트 맵 핸들은 글로벌 변수 hwndFSWindowBMP 에 저장 된다. 이하에 나타내도록(듯이), 프라이머리 표면을 갱신하려고 하면(자), 항상 이 비트 맵이 백 버퍼에 블리트 된다.

if (FSWindow_IsStatic)
{
hdcMemory = CreateCompatibleDC(NULL);
SelectObject(hdcMemory, hwndFSWindowBMP);
BitBlt(hdcBackBuffer, x, y, cx, cy, hdcMemory, 0, 0, SRCCOPY);
DeleteDC(hdcMemory);
}

이것에 대해, 동적 컨텐츠의 경우는 다음의 코드가 실행된다. 이 경우, 이미지가 GDI 표면 (hdcScreen 디바이스 콘텍스트로 나타내진다)으로부터 직접 백 버퍼에 블리트 된다.

BitBlt(hdcBackBuffer, x, y, cx, cy, hdcScreen, x, y, SRCCOPY);

위의 좌표는,GetWindowRect 를 호출하는 것에 의해 취득되는, GDI 표면 위에의 윈도우의 위치와 사이즈를 나타낸다.

DDCAPS2_CANRENDERWINDOWED 능력을 가지지 않는 하드웨어로 FSWindow 어플리케이션을 실행하는 경우, GDI 표면을 사용하지 않기 때문에, Windows 는 마우스 커서를 표시할 수 없다. 어플리케이션은, 커서에 관한 정보를 취득해, 플립의 직전의 백 버퍼상에 그 정보를 배치하는 것으로써, 커서를 표시한다.


DirectDraw 튜토리얼

여기에서는, DirectDraw 의 기본적인 기능을 C/C++ 또는 Visual Basic 어플리케이션에 이행 하는 방법에 대해 스텝바이스텝으로 설명하는 튜토리얼을 제공한다. 각 튜토리얼은, 이 SDK 의 \Samples\Multimedia\DDraw\Tutorials 디렉토리에서 제공되는 일련의 샘플 파일과 대응해, 코드의 흐름에 따라 설명한다. 샘플 코드를 참조하면서 튜토리얼을 읽어 진행시켜 나가는 것을 권한다.

  • DirectDraw C/C++ 튜토리얼
  • DirectDraw Visual Basic 튜토리얼


DirectDraw C/C++ 튜토리얼

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

여기에서는, 다음의 튜토리얼을 사용해, 간단한 DirectDraw 어플리케이션을 이행 하는 방법을 스텝바이스텝으로 설명한다. 각 튜토리얼은, 이 SDK 가 제공하는 DirectDraw 샘플 파일을 많이 사용하고 있다. 이러한 샘플에서는, DirectDraw 의 셋업 방법과 일반적인 태스크를 실행하기 위한 DirectDraw 메소드의 사용 방법을 소개한다.

  • 튜토리얼 1 : DirectDraw 의 기초
  • 튜토리얼 2 : 백 버퍼에의 비트 맵의 로드
  • 튜토리얼 3 : 오프 스크린 표면으로부터의 블리트
  • 튜토리얼 4 : 컬러 키와 비트 맵 애니메이션
  • 튜토리얼 5 : 팔레트의 동적 변경
  • 튜토리얼 6 : 오버레이 표면의 사용

주 ： 이러한 튜토리얼의 샘플 파일은, C++ 로 기술되고 있다. C 컴파일러를 사용하는 경우, 잘 컴파일 할 수 있도록(듯이) 파일을 적절히 변경할 필요가 있다. 적어도, 인터페이스 메소드에 vtable 및 this 포인터를 추가할 필요가 있다.


튜토리얼 1 : DirectDraw 의 기초

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

DirectDraw 를 사용하려면 , 우선 시작해에, 컴퓨터 위에의 디스플레이 어댑터를 나타내는 DirectDraw 오브젝트의 인스턴스를 생성 해야 한다. 그리고, 인터페이스 메소드를 사용해, 그 오브젝트를 조작한다. 게다가 어플리케이션을 그래픽스 표면상에 표시하려면 , DirectDrawSurface 오브젝트의 인스턴스를 1 개 이상 생성 할 필요가 있다.

이것을 설명하기 위해서, 이 SDK 에 있는 DDEx1 샘플 을 다음의 스텝에서 실행한다.

  • 스텝 1 : DirectDraw 오브젝트의 생성
  • 스텝 2 : 어플리케이션 동작의 결정
  • 스텝 3 : 디스플레이 모드의 변경
  • 스텝 4 : 플립핑 표면의 생성
  • 스텝 5 : 표면에의 쓰기
  • 스텝 6 : 표면의 플립
  • 스텝 7 : DirectDraw 오브젝트의 할당 해제

주 ： 어플리케이션으로 GUID 를 잘 이용하려면 , 다른 모든 include 문이나 define 문의 전에 INITGUID 를 정의하는지, Dxguid.lib 라이브러리에 링크할 필요가 있다. INITGUID 의 정의는, 소스 모듈중의 1 개인 만큼 한다.


스텝 1 : DirectDraw 오브젝트의 생성

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

DirectDraw 오브젝트의 인스턴스를 생성 하려면 , DDEx1 프로그램의 InitApp 샘플 함수로 나타나고 있도록(듯이), 어플리케이션으로 DirectDrawCreateEx 함수를 사용하도록(듯이) 한다. DirectDrawCreateEx 에는 4 개의 파라미터가 있다. 최초의 파라미터는, 디스플레이 디바이스를 나타내는 글로벌 유니크 식별자 (GUID)로 한다. 대부분의 경우, GUID 는 NULL 로 설정되어 DirectDraw 가 시스템의 디폴트 디스플레이 드라이버를 사용하는 것을 의미한다. 2 번째의 파라미터는, 생성 된 DirectDraw 오브젝트의 위치를 식별하는 포인터의 주소이다. 3 번째의 파라미터는,IDirectDraw7 인터페이스의 참조 식별이다. 이 파라미터는 IID_IDirectDraw7 로 설정할 필요가 있다. 4 번째의 파라미터는 항상 NULL 로 설정되어 장래의 확장 기능에 대비한다.

다음의 예에서는, DirectDraw 오브젝트의 생성 방법과 그 생성이 성공했는지 어떠했는지를 판단하는 방법을 나타낸다.

hRet = DirectDrawCreateEx(NULL, (VOID**) &g_pDD, IID_IDirectDraw7, NULL);
if(hRet == DD_OK)
{
    // g_pDD 는 유효한 DirectDraw 오브젝트이다.
}
else
{
    // DirectDraw 오브젝트는 생성 할 수 없었다.
}

다음 방향 :스텝 2 : 어플리케이션 동작의 결정


스텝 2 : 어플리케이션 동작의 결정

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

디스플레이의 해상도를 변경하기 전에, 적어도 IDirectDraw7::SetCooperativeLevel 메소드의 dwFlags 파라미터에 DDSCL_EXCLUSIVE 및 DDSCL_FULLSCREEN 플래그를 지정할 필요가 있다. 이것에 의해, 어플리케이션이 디스플레이 디바이스를 완전하게 제어할 수 있게 되어, 다른 어플리케이션이 디스플레이 어댑터를 공유할 수 없게 된다. 게다가 DDSCL_FULLSCREEN 플래그로, 어플리케이션을 배타 (풀 스크린) 모드로 설정한다. 어플리케이션은 데스크탑 전체를 커버하고 있어, 어플리케이션만이 스크린에 기입할 수가 있다. 다만, 데스크탑은 이용 가능한 그대로이다(배타 모드로 실행하는 어플리케이션의 데스크탑을 보려면 , DDEx1 를 기동해 ALT + TAB 를 누른다).

다음의 예에서는,SetCooperativeLevel 메소드의 사용 방법을 나타낸다.

HRESULT       hRet;
LPDIRECTDRAW7 g_pDD;   // 이미 DirectDrawCreateEx 에 의해 생성 되고 있다.

hRet = g_pDD->SetCooperativeLevel(hWnd, DDSCL_EXCLUSIVE | DDSCL_FULLSCREEN);
if (hRet ! = DD_OK)
{
    // 배타 모드는 성공했다.
}
else
{
    // 배타 모드는 실패했다.
    // 다만, 어플리케이션은 실행한채로 있다.
}

SetCooperativeLevel 가 DD_OK 를 돌려주지 않는 경우에서도, DDSCL_NORMAL 를 지정해 어플리케이션을 속행할 수 있다. 다만, 어플리케이션이 배타 모드가 아니면, 어플리케이션의 요구하는 퍼포먼스 능력을 실행할 수 없을 가능성이 있다. 이 경우, 속행할지 어떨지를 유저로 결정시키는 메세지를 표시하는 것이 좋을 것이다.

풀 스크린 (배타 협조 레벨)을 설정해 있는 경우, 어플리케이션의 이상종료(ABEND)를 Microsoft® Windows® 로 판단할 수 있도록(듯이), 어플리케이션의 윈도우 핸들을 SetCooperativeLevel 에 건네준다. 예를 들어, 일반 보호 (GP) 에러가 발생해, 그래픽스 디바이스 인터페이스 (GDI)가백 버퍼에 플립 되는 경우, 유저는 Windows 스크린에 돌아올 수 없게 된다. 이 에러의 발생을 회피하기 위해서, DirectDraw 는, 어플리케이션 윈도우에 보내지는 메세지를 트랩 하는 백그라운드에서 실행하는 프로세스를 제공한다. 어플리케이션이 종료할 경우에, DirectDraw 는 이러한 메세지를 사용하고 판단한다. 다만, 이 기능에는 몇개의 제한이 있다. 어플리케이션에 대한 메세지를 취득하는 윈도우 핸들을 지정할 필요가 있다. 즉, 그 밖에도 윈도우를 생성 하는 경우, 액티브한 윈도우를 지정한 것을 확인할 필요가 있다. 이것을 지정하지 않으면 GDI 로 예측 불가능한 동작이 생기거나 Alt + Tab 를 눌러도 응답이 없다고 한 문제가 생기게 된다.

다음 방향 :스텝 3 : 디스플레이 모드의 변경


스텝 3 : 디스플레이 모드의 변경

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

어플리케이션의 동작을 설정한 다음에,IDirectDraw7::SetDisplayMode 메소드를 사용해 디스플레이의 해상도를 변경할 수 있다. 다음의 예는, 디스플레이 모드를 640 에 480 에 8 bpp 로 설정하는 방법을 나타낸다.

HRESULT       hRet;
LPDIRECTDRAW7 g_pDD;   // 이미 DirectDrawCreateEx 에 의해 생성 되고 있다.

hRet = g_pDD->SetDisplayMode(640, 480, 8, 0, 0);
if (hRet ! = DD_OK)
{
// 디스플레이 모드의 변경은 성공했다.
}
else
{
// 디스플레이 모드는 변경할 수 없었다.
// 모드가 지원되어 있지 않은지, 다른 어플리케이션이
// 배타 모드가 되어 있다.
}

디스플레이 모드를 설정하는 경우, 유저의 하드웨어가 고해상도를 지원 하고 있지 않을 때에, 어플리케이션이 대부분의 디스플레이 어댑터로 지원 되는 표준 모드에 돌아올 수 있도록(듯이) 한다. 예를 들어, 어플리케이션은, 표준 백업 해상도로서 640 × 480 × 8 을 지원 하는 모든 시스템으로 실행할 수 있도록(듯이) 설계할 수 있다.

주 ： 요구되는 해상도에 디스플레이 어댑터를 설정할 수 없는 경우,IDirectDraw7::SetDisplayMode 는 DDERR_INVALIDMODE 에러를 돌려준다. 따라서, 디스플레이 모드를 설정하기 전에,IDirectDraw7::EnumDisplayModes 메소드를 사용해 유저의 디스플레이 어댑터의 능력을 결정해 두지 않으면 안 된다.

다음 방향 :스텝 4 :플립핑 표면의 생성


스텝 4 : 플립핑 표면의 생성

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

디스플레이 모드를 설정한 후, 어플리케이션을 배치하는 표면을 생성 해야 한다. DDEx1 의 예에서는,IDirectDraw7::SetCooperativeLevel 메소드를 사용해 배타 (풀 스크린) 모드를 설정한다. 이 결과, 표면간에 플립 하는 표면을 생성 할 수 있다. SetCooperativeLevel 를 사용해 DDSCL_NORMAL 에 모드를 설정했을 경우, 표면간에 블리트 하는 표면만을 생성 할 수가 있다. 플립핑 표면을 생성 하려면 , 이하의 스텝 (이 스텝에 대해서는, 다음에 설명한다)이 필요하다.

  • 스텝 4.1 : 표면 요건의 정의
  • 스텝 4.2 : 표면의 생성


스텝 5 : 표면에의 쓰기

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

프라이머리 표면과백 버퍼가 생성 되면(자),DDEx1 의 예에서는, 표준의 Windows GDI 함수를 사용해 백 버퍼 표면상에 어떠한 텍스트를 기입한다. 다음에 예를 나타낸다.

    if (g_pDDSBack->GetDC(&hdc) == DD_OK)
    {
        SetBkColor(hdc, RGB(0, 0, 255));
        SetTextColor(hdc, RGB(255, 255, 0));
        if (phase)
        {
            GetClientRect(hWnd, &rc);
            GetTextExtentPoint(hdc, szMsg, lstrlen(szMsg), &size);
            TextOut(hdc, (rc.right - size.cx) / 2, (rc.bottom - size.cy) / 2,
                    szMsg, sizeof(szMsg) - 1);
            TextOut(hdc, 0, 0, szFrontMsg, lstrlen(szFrontMsg));
            phase = 0;
        }
        else
        {
            TextOut(hdc, 0, 0, szBackMsg, lstrlen(szBackMsg));
            phase = 1;
        }
        g_pDDSBack->ReleaseDC(hdc);
    }

이 예에서는,IDirectDrawSurface7::GetDC 메소드를 사용해 디바이스 콘텍스트의 핸들을 취득해, 내부적으로 백 버퍼를 잠근다. 디바이스 콘텍스트의 핸들을 필요로 하는 Windows 함수를 사용하지 않는 경우는,IDirectDrawSurface7::Lock 및 IDirectDrawSurface7::Unlock 메소드를 사용해,백 버퍼를 잠그거나 락을 해제하거나 할 수가 있다.

다음에, 프라이머리 버퍼 메세지 또는 백 버퍼 메세지의 어느 쪽이 기입해져야할 것인가를 phase 변수로 결정한다. phase 변수가 1 의 경우는 프라이머리 버퍼 메세지가 기입해져,phase 변수가 0 으로 설정된다. phase 변수가 0 의 경우는, 백 버퍼 메세지가 기입해져,phase 변수가 1 으로 설정된다.

메세지가 백 버퍼에 기입해진 후,IDirectDrawSurface7::ReleaseDC 메소드에 의해 백 버퍼의 락이 해제된다.

표면 메모리 (표면의 전체 혹은 일부)를 잠그면(자), 어플리케이션과 시스템 블리트를 동시에 표면 메모리에 액세스 할 수 없게 된다. 이 때문에, 어플리케이션이 표면 메모리에 기입하는 동안에 발생하는 에러를 회피할 수 있다. 게다가 표면 메모리의 락이 해제될 때까지, 어플리케이션은 페이지 플립 할 수 없다.

표면이 락 된 후, 이 예에서는 표준의 Windows GDI 함수를 사용한다. 백그라운드 컬러의 설정에 SetBkColor, 백그라운드에 배치하는 텍스트의 색의 선택에 SetTextColor, 표면 위에의 텍스트와 백그라운드 컬러의 출력에 TextOut 를 사용하고 있다.

텍스트가 버퍼에 기입해진 후, 이 예에서는 IDirectDrawSurface7::ReleaseDC 메소드를 사용해, 표면의 락을 해제해 핸들을 릴리즈 한다. 어플리케이션이백 버퍼에의 쓰기를 종료 하면나무는 항상, 어플리케이션에 응해 IDirectDrawSurface7::ReleaseDC 또는 IDirectDrawSurface7::Unlock 의 어느 쪽인지를 호출하지 않으면 안 된다. 표면의 락이 해제될 때까지, 어플리케이션은 표면을 플립 할 수 없다.

주 ： IDirectDrawSurface7::Unlock 를 사용해 표면의 락이 해제되면(자), 표면 메모리에의 포인터는 무효가 된다. 표면 메모리에의 유효한 포인터를 취득하려면 , 다시 IDirectDrawSurface7::Lock 를 사용하지 않으면 안 된다.

다음 방향 :스텝 6 : 표면의 플립


스텝 6 : 표면의 플립

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

DDEx1 의 WM_TIMER 메세지는,백 버퍼 . 에의 플립에 사용된다. 표면 메모리의 락이 해제되면(자),백 버퍼를프라이머리 표면에 플립 하는 IDirectDrawSurface7::Flip 메소드를 사용할 수 있게 된다. 다음에 예를 나타낸다.

    case WM_TIMER:
        // 표면을 갱신해 플립 한다.
        if (g_bActive && TIMER_ID == wParam)
        {
            UpdateFrame(hWnd);
            while (TRUE)
            {
                hRet = g_pDDSPrimary->Flip(NULL, 0);
                if (hRet == DD_OK)
                    break;
                if (hRet == DDERR_SURFACELOST)
                {
                    hRet = g_pDDSPrimary->Restore();
                    if (hRet ! = DD_OK)
                        break;
                }
                if (hRet ! = DDERR_WASSTILLDRAWING)
                    break;
            }
        }
        break;

이 예에서는,g_pDDSPrimary 파라미터가프라이머리 표면과 거기에 관련지을 수 있었던백 버퍼를 지정한다. IDirectDrawSurface7::Flip 가 불려 가면(자), 프런트 표면과 백 표면이 교환된다 (표면에의 포인터만이 변경되어 실제로 데이터가 이동하는 것은 아니다). 플립이 성공해 DD_OK 가 돌려주어지면(자), 어플리케이션은 while 루프로부터 빠진다.

플립이 DDERR_SURFACELOST 값을 돌려주는 경우,IDirectDrawSurface7::Restore 메소드를 사용해 표면을 restore 하려고 한다. restore가 성공하면(자), 어플리케이션은 루프에 돌아와,IDirectDrawSurface7::Flip 의 호출을 다시 시도한다. restore가 실패 하면, 어플리케이션은 while 루프를 빠져, 에러를 돌려준다.

주 ： IDirectDrawSurface7::Flip 를 호출하는 경우, 플립은 곧바로 완료하지 않는다. 오히려, 시스템으로 수직귀선이 발생한 후에 플립이 계획된다. 예를 들어, 직전의 플립이 발생하고 있지 않으면,IDirectDrawSurface7::Flip 는 DDERR_WASSTILLDRAWING 를 돌려준다. 이 예에서는,IDirectDrawSurface7::Flip 의 호출은 DD_OK 를 돌려줄 때까지 루프 계속 한다.

다음 방향 :스텝 7 : DirectDraw 오브젝트의 할당 해제


스텝 7 : DirectDraw 오브젝트의 할당 해제

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

F12 키를 누르면(자), DDEx1 어플리케이션은 종료전에 WM_DESTROY 메세지를 처리한다. 이 메세지는,IUnknown::Release 호출의 모든 것을 포함한 ReleaseAllObjects 샘플 함수를 호출한다. 다음에 예를 나타낸다.

static void
ReleaseAllObjects(void)
{
    if (g_pDD ! = NULL)
    {
        if (g_pDDSPrimary ! = NULL)
        {
            g_pDDSPrimary->Release();
            g_pDDSPrimary = NULL;
        }
        g_pDD->Release();
        g_pDD = NULL;
    }
}

어플리케이션은, DirectDraw 오브젝트 (g_pDD) 및 DirectDrawSurface 오브젝트 (g_pDDSPrimary)에의 포인터가 NULL 일지 어떨지를 조사한다. 다음에, DDEx1 는 IDirectDrawSurface7::Release 메소드를 호출해, DirectDrawSurface 오브젝트의참조 카운트를 1 만 줄인다. 이것에 의해, 참조 카운트가 0 이 되므로, DirectDrawSurface 오브젝트는 할당이 해제된다. DirectDrawSurface 포인터의 값을 NULL 로 설정하는 것으로써, 이 포인터는 파기된다. 다음에, 어플리케이션은 IDirectDraw7::Release 를 호출해, DirectDraw 오브젝트의 참조 카운트를 0 까지 줄인다. 이것에 의해, DirectDraw 오브젝트의 할당을 해제한다. 이 포인터의 값을 NULL 로 설정하는 것으로써, 이 포인터도 파기된다.


튜토리얼 2 : 백 버퍼에의 비트 맵의 로드

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

이 튜토리얼 (DDEx2 )로 설명하는 샘플은, 튜토리얼 1 으로 설명한 DDEx1 샘플을 확장한 것이다. DDEx2 에는, 비트 맵 파일을백 버퍼에 로드하는 기능이 포함된다. 이하의 스텝에서 이 신기능을 설명한다.

  • 스텝 1 : 팔레트의 생성
  • 스텝 2 : 팔레트의 설정
  • 스텝 3 : 백 버퍼에의 비트 맵의 로드
  • 스텝 4 : 표면의 플립

DDEx1 와 같이, doInit 는 DDEx2 어플리케이션의 초기화 함수이다. DirectDraw 의 초기화 코드는, DDEx1 와 DDEx2 와는 조금 달라 보이지만, 본질적으로는 동일해, 다음의 섹션이 다른 것만으로 있다.

lpDDPal = DDLoadPalette(lpDD, szBackground);

if (lpDDPal == NULL)
    goto error;

ddrval = lpDDSPrimary->SetPalette(lpDDPal);

if(ddrval ! = DD_OK)
    goto error;

// 백 버퍼에 비트 맵을 로드한다.
ddrval = DDReLoadBitmap(lpDDSBack, szBackground);

if(ddrval ! = DD_OK)
    goto error;


스텝 1 : 팔레트의 생성

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

DDEx2 샘플에서는, 다음의 코드를 사용해 구조체에 팔레트를 로드한다.

lpDDPal = DDLoadPalette(lpDD, szBackground);

if (lpDDPal == NULL)
    goto error;

샘플 함수 DDLoadPalette 는, \Dxsdk\Sdk\Samples\Misc 디렉토리의 Ddutil.cpp 파일안에 있는, 공통 DirectDraw 함수의 일부이다. 이 SDK 의 대부분의 DirectDraw 샘플 파일은, 이 파일을 사용하고 있다. 이 파일에는, 파일 또는 리소스로부터 비트 맵이나 팔레트를 로드하기 위한 함수가 포함된다. 복수의 예제 파일 중(안)에서 코드의 반복을 피하기 위해서(때문에), 이러한 함수는 재이용 가능한 1 개의 파일에 정리하고 있다. 나머지의 DDExn 샘플과 함께 컴파일 하는 파일의 리스트에 Ddutil.cpp 가 있는 것을 확인하는 것.

DDEx2 에서는, DDLoadPalette 샘플 함수가 Back.bmp 파일로부터 DirectDrawPalette 오브젝트를 생성 한다. DDLoadPalette 샘플 함수에서는, 팔레트를 생성하기 위한 파일 또는 리소스가 존재할지 어떨지를 판단한다. 만약 존재하지 않으면, 디폴트의 팔레트를 생성 한다. DDEx2 에서는, 비트 맵 팔레트로부터 팔레트 정보를 꺼내,ape 포인터가 가리키는 구조체에 저장 한다.

다음에, DDEx2 는 DirectDrawPalette 오브젝트를 생성 한다. 다음에 예를 나타낸다.

pdd->CreatePalette(DDPCAPS_8BIT, ape, &ddpal, NULL);
return ddpal;

IDirectDraw7::CreatePalette 메소드가 돌아오면(자),ddpal 파라미터는, DDLoadPalette 의 호출로부터 돌려주어진 후의 DirectDrawPalette 오브젝트를 나타낸다.

ape 파라미터는 구조체에의 포인터로, 연속한 2, 4, 16, 또는 256 엔트리의 어느쪽이든을 포함한다. 엔트리의 수는,CreatePalette 메소드의 dwFlags 파라미터에 의존한다. 이 경우,dwFlags 파라미터는 DDPCAPS_8BIT 로 설정되어 이 구조체에 256 엔트리가 있는 것을 나타낸다. 각각의 엔트리는, 4 바이트 (빨강 채널, 초록 채널, 파랑 채널, 및 flag byte)로 구성된다.

다음 방향 :스텝 2 : 팔레트의 설정


스텝 2 : 팔레트의 설정

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

팔레트를 생성 한 후,IDirectDrawSurface7::SetPalette 메소드를 호출하는 것으로, DirectDrawPalette 오브젝트에의 포인터 (ddpal)를프라이머리 표면에 건네준다. 다음에 예를 나타낸다.

ddrval = lpDDSPrimary->SetPalette(lpDDPal);

if(ddrval ! = DD_OK)
    // SetPalette 는 실패했다.

IDirectDrawSurface7::SetPalette 를 호출한 후, DirectDrawPalette 오브젝트는 DirectDrawSurface 오브젝트에 관련지을 수 있다. 팔레트의 변경이 필요한 회수만, 간단하게 새로운 팔레트를 생성 해, 그 팔레트를 재설정할 수 있다 (이 튜토리얼에서는 여기서 가리키는 스텝을 취하지만, 팔레트의 변경에는 다음에 설명하는 것 같은 방법도 있다).

다음 방향 :스텝 3 : 백 버퍼에의 비트 맵의 로드


스텝 3 : 백 버퍼에의 비트 맵의 로드

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

DirectDrawPalette 오브젝트가 DirectDrawSurface 오브젝트와 관련지을 수 있으면(자), DDEx2 는 다음의 코드로 Back.bmp 비트 맵을백 버퍼에 로드한다.

// 백 버퍼에 비트 맵을 로드한다.
ddrval = DDReLoadBitmap(lpDDSBack, szBackground);

if(ddrval ! = DD_OK)
    // Load failed.

DDReLoadBitmap 는, Ddutil.cpp 에 있는 이제(벌써) 1 개의 샘플 함수이다. 이 함수는, 파일 또는 리소스로부터 비트 맵을 기존의 DirectDraw 표면에 로드한다. (표면을 생성 해 그 표면에 비트 맵을 로드하려면 , DDLoadBitmap 를 사용할 수도 있다. 상세 정보는, 「튜토리얼 5 : 팔레트의 동적 변경」을 참조할것. DDEx2 에서는,szBackground 가 가리키는 Back.bmp 파일을 lpDDSBack 가 가리키는백 버퍼에 로드한다. DDReLoadBitmap 함수는 DDCopyBitmap 함수를 호출해, 파일을 백 버퍼에 카피하고 나서, 적절한 사이즈에 신축(스트레치) 한다.

DDCopyBitmap 함수는 비트 맵을 메모리에 카피해, 비트 맵의 사이즈를 취득하기 위해서 GetObject 함수를 사용한다. 그리고, 다음에 나타내는 코드를 사용해, 비트 맵을 배치하는 백 버퍼의 사이즈를 취득한다.

// 표면의 사이즈를 얻는다
ddsd.dwSize = sizeof(ddsd);
ddsd.dwFlags = DDSD_HEIGHT | DDSD_WIDTH;
pdds->GetSurfaceDesc(&ddsd);

ddsd 값은,DDSURFACEDESC2 구조체에의 포인터이다. 이 구조체는, DirectDraw 표면의 현재의 기술을 저장 한다. 이 경우, 멤버는, DDSD_HEIGHT 와 DDSD_WIDTH 로 나타나는 표면의 높이와폭을 기술한다. IDirectDrawSurface7::GetSurfaceDesc 메소드에의 호출은, 구조체에 해당하는 값을 로드한다. DDEx2 에서는, 높이 480, 폭 640 으로 한다.

DDCopyBitmap 샘플 함수는 표면을 잠그어, StretchBlt 함수를 사용해,백 버퍼에 들어맞도록(듯이) 비트 맵을신축(스트레치) 또는 압축해 카피한다.

if ((hr = pdds->GetDC(&hdc)) == DD_OK)
{
    StretchBlt(hdc, 0, 0, ddsd.dwWidth, ddsd.dwHeight, hdcImage, x, y,
        dx, dy, SRCCOPY);
    pdds->ReleaseDC(hdc);
}

다음 방향 :스텝 4 : 표면의 플립


스텝 4 : 표면의 플립

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

DDEx2 샘플의플립핑 표면은, 표면이 소실했을 경우 (DDERR_SURFACELOST )를 제외해, DDEx1 튜토리얼 ( 「튜토리얼 1 : DirectDraw 의 기초」를 참조)의 프로세스와 본질적으로 같다. 표면이 소실했을 경우는, 표면을 restore 한 후, DDReLoadBitmap 함수를 사용해 비트 맵을백 버퍼에 재로드하지 않으면 안 된다.


튜토리얼 3 : 오프 스크린 표면으로부터의 블리트

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

튜토리얼 2 (DDEx2)의 샘플에서는, 비트 맵을 취득해백 버퍼에 두어, 다음에 백 버퍼와 프라이머리 버퍼간에 플립 한다. 이것은, 비트 맵을 표시하려면 너무 현실적인 방법은 아니다. 이 튜토리얼 (DDEx3)의 샘플에서는, 2 개의 비트 맵 (한편은 짝수 스크린용, 한편은 홀수 스크린용)이 저장 된 2 개의 오프 스크린 버퍼를 이용하는 것으로, DDEx2 의 능력을 확장한다. 오프 스크린 표면의 내용을 백 버퍼에 카피하려면 ,IDirectDrawSurface7::BltFast 메소드를 사용한다. 그리고, 버퍼를 플립 해, 다음의 오프 스크린 표면을 백 버퍼에 카피한다.

DDEx3 로 가리키는 신기능을 다음의 스텝에서 설명한다.

  • 스텝 1 : 오프 스크린 표면의 생성
  • 스텝 2 : 오프 스크린 표면에의 비트 맵의 로드
  • 스텝 3 : 백 버퍼에의 오프 스크린 표면의 블리트


스텝 1 : 오프 스크린 표면의 생성

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

다음의 코드에서는, DDEx3 의 doInit 샘플 함수를 추가해, 2 개의 오프 스크린 버퍼를 생성 한다.

// 오프 스크린 비트 맵을 생성 한다.
ddsd.dwFlags = DDSD_CAPS | DDSD_HEIGHT | DDSD_WIDTH;
ddsd.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN;
ddsd.dwHeight = 480;
ddsd.dwWidth = 640;
ddrval = lpDD->CreateSurface(&ddsd, &lpDDSOne, NULL);
if(ddrval ! = DD_OK)
{
    return initFail(hwnd);
}

// 다른 오프 스크린 비트 맵을 생성 한다.
ddrval = lpDD->CreateSurface(&ddsd, &lpDDSTwo, NULL);
if(ddrval ! = DD_OK)
{
    return initFail(hwnd);
}

dwFlags 멤버는, 어플리케이션이 DDSCAPS 구조체를 사용하는 것을 지정해, 버퍼의 높이와폭 을 설정한다. 표면은, DDSCAPS_OFFSCREEN 플래그가 DDSCAPS 구조체로 설정되는 것으로 나타나도록(듯이), 오프 스크린 프레인 버퍼가 된다. 높이와 폭은, 각각 480 으로 640 으로 DDSURFACEDESC2 구조체로 설정된다. 표면은,IDirectDraw7::CreateSurface 메소드를 사용해 생성 한다.

오프 스크린 프레인 버퍼는 양쪽 모두 같은 사이즈이므로, 세컨드 버퍼를 생성 하기 위해서는, 다른 포인터명으로 IDirectDraw7::CreateSurface 를 다시 호출하면 좋다.

또, DDSCAPS_SYSTEMMEMORY 또는 DDSCAPS_VIDEOMEMORY 의 어느 쪽인가의 능력을 DDSCAPS 구조체로 설정하는 것으로써, 오프 스크린 버퍼를 시스템 메모리 또는 디스플레이 메모리에 배치하는 것을 명시적으로 요구할 수 있다. 디스플레이 메모리에 비트 맵을 보존하는 것으로써,오프 스크린 표면과백 버퍼간의 전송 속도를 빨리 할 수가 있다. 비트 맵 애니메이션을 사용하는 경우에, 이것이 보다 중요해진다. 다만, 오프 스크린 버퍼에 DDSCAPS_VIDEOMEMORY 를 지정해, 비트 맵 전체를 보관 유지하기 위한 디스플레이 메모리가 불충분한 경우에 표면을 생성 하려고 하면(자),DDERR_OUTOFVIDEOMEMORY 에러값이 돌려주어진다.

다음 방향 :스텝 2 : 오프 스크린 표면에의 비트 맵의 로드


스텝 2 : 오프 스크린 표면에의 비트 맵의 로드

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

2 개의오프 스크린 표면이 생성 되면(자),DDEx3 는 InitSurfaces 샘플 함수를 사용해, Frntback.bmp 파일의 비트 맵을 표면에 로드한다. InitSurfaces 함수는, 양쪽 모두의 비트 맵을 로드하기 위해서(때문에), Ddutil.cpp 에 있는 DDCopyBitmap 샘플 함수를 사용한다. 다음에 예를 나타낸다.

// 비트 맵 리소스를 로드한다.
hbm = (HBITMAP) LoadImage(GetModuleHandle(NULL), szBitmap,
    IMAGE_BITMAP, 0, 0, LR_CREATEDIBSECTION);

if (hbm == NULL)
    return FALSE;

DDCopyBitmap(lpDDSOne, hbm, 0, 0,   640, 480);
DDCopyBitmap(lpDDSTwo, hbm, 0, 480, 640, 480);
DeleteObject(hbm);

return TRUE;

Microsoft® Paint 나 다른 드로잉(Drawing) 어플리케이션으로 Frntback.bmp 파일을 보면(자), 한편이 이제(벌써) 한편과 겹쳐지는 2 개의 스크린으로 비트 맵이 구성되어 있는 것을 알 수 있다. DDCopyButmap 함수는, 그 스크린이 합쳐지는 포인트로 비트 맵을 2 개로 나눈다. 게다가 최초의 비트 맵을 최초의오프 스크린 표면 (lpDDSOne)에 로드해, 2 번째의 비트 맵을 2 번째의 오프 스크린 표면 (lpDDSTwo)에 로드한다.

다음 방향 :스텝 3 : 백 버퍼에의 오프 스크린 표면의 블리트


스텝 3 : 백 버퍼에의 오프 스크린 표면의 블리트

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

WM_TIMER 메세지에는, 표면과플립핑 표면에의 쓰기에 대한 코드가 있다. DDEx3 의 경우, 다음과 같은 코드가 있어, 적당한오프 스크린 표면을 선택해 백 버퍼에 전송 한다.

rcRect.left = 0;
rcRect.top = 0;
rcRect.right = 640;
rcRect.bottom = 480;
if(phase)
{
    pdds = lpDDSTwo;
    phase = 0;
}
else
{
    pdds = lpDDSOne;
    phase = 1;
}
while(1)
{
    ddrval = lpDDSBack->BltFast(0, 0, pdds, &rcRect, FALSE);
    if(ddrval == DD_OK)
    {
        break;
    }
}

phase 변수에서는,백 버퍼에 블리트 되는 오프 스크린 표면을 결정한다. 그리고,IDirectDrawSurface7::BltFast 메소드를 호출해, 선택된 오프 스크린 표면은 맨 왼쪽 위쪽의 시점 (0,0)으로부터 백 버퍼에 블리트 한다. rcRect 파라미터는 RECT 구조체의 포인터이며, 블리트 되는 오프 스크린 표면의 맨 왼쪽 위쪽과 우하각을 정의한다. 마지막 파라미터는 FALSE (또는 0)로 설정해, 특별한 전송 플래그를 사용하지 않는 것을 나타낸다.

어플리케이션의 요구에 의해,IDirectDrawSurface7::Blt 메소드 또는 IDirectDrawSurface7::BltFast 메소드의 어느 쪽인지를 사용해, 오프 스크린 버퍼로부터 블리트 한다. 디스플레이 메모리에 있는 오프 스크린 프레인 버퍼로부터 블리트를 실행하는 경우는,IDirectDrawSurface7::BltFast 를 사용하도록(듯이) 한다. 디스플레이 어댑터 위에의하드웨어 블리트를 사용하는 시스템에서는 속도를 빨리 할 수 없다. 그러나, 블리트의 실행에 하드웨어 에뮬레이션을 사용하는 시스템에서는, 10 퍼센트 정도 빨리 된다. 이 때문에, 디스플레이 메모리로부터 디스플레이 메모리에의 블리트 하는 모든 디스플레이 처리에 대해,IDirectDrawSurface7::BltFast 를 사용해야 하는 것이다. 다만, 시스템 메모리로부터 블리트 하거나 특별한 하드웨어 플래그를 필요로 하는 경우는,IDirectDrawSurface7::Blt 를 사용하지 않으면 안 된다.

오프 스크린 표면을 백 버퍼에 로드한 후,백 버퍼와프라이머리 표면은, 상술의 튜토리얼로 가리킨 방법과 거의와 같이 플립 된다.


튜토리얼 4 : 컬러 키와 비트 맵 애니메이션

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

튜토리얼 3 (DDEx3 )의 샘플에서는,백 버퍼에 블리트 하기 전에, 비트 맵을 오프 스크린 버퍼에 배치하는 1 개(살)의 간단한 방법을 나타냈다. 이 튜토리얼 (DDEx4)의 샘플에서는, 직전의 튜토리얼로 설명한 기술을 사용해, 백그라운드와 일련의 스프라이트를오프 스크린 표면에 로드한다. 그리고,IDirectDrawSurface7::BltFast 메소드를 사용해, 오프 스크린 표면의 일부를 백 버퍼에 카피한다. 즉, 간단한 비트 맵 애니메이션을 생성한다.

DDEx4 로 사용하는 비트 맵 파일 All.bmp 는, 흑의 백그라운드에 60 회전하는 붉은 고리와 백그라운드로 구성된다. DDEx4 의 샘플에는, 회전하고 있는 고리의 스프라이트에컬러 키를 설정하는 새로운 함수를 포함한다. 그리고, 그 샘플은, 해당하는 스프라이트를 오프 스크린 표면으로부터 백 버퍼에 카피한다.

DDEx4 의 신기능을 다음의 스텝에서 설명한다.

  • 스텝 1 : 컬러 키의 설정
  • 스텝 2 : 간단한 애니메이션의 생성


스텝 1 : 컬러 키의 설정

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

다른 DirectDraw 샘플에서도, 다른 함수에 doInit 샘플 함수를 찾아낼 수가 있다. 그러나, DDEx4 의 샘플에는, 스프라이트를 위한컬러 키를 설정하는 코드가 있다. 컬러 키는, 투과성에 사용되는 색의 값을 설정한다. 시스템에하드웨어 블리트가 있는 경우, 직사각형의 모든 픽셀은 컬러 키로서 설정된 값을 제외해, 표면 위에의비직사각형 스프라이트를 생성 하면서 블리트 된다. 다음의 코드에서는, DDEx4 로 컬러 키를 설정하는 방법에 대해 가리킨다.

//  이 비트 맵 (흑)에 대한 컬러 키를 설정한다.
DDSetColorKey(lpDDSOne, RGB(0,0,0));

return TRUE;

컬러 키를 선택하려면 , DDSetColorKey 샘플 함수의 호출로 지정하고 싶은 색의 RGB 값을 설정한다. 흑의 RGB 값은, (0, 0, 0)이다. DDSetColorKey 함수는, DDColorMatch 함수를 호출한다 ( 양함수는 Ddutil.cpp 에 있다). DDColorMatch 함수는,lpDDSOne 표면에 있는 비트 맵의 것 (0, 0)으로, 픽셀의 현재의 컬러값을 저장 한다. 다음에, 주어진 RGB 값을 취득해, (0, 0)그리고 픽셀을 그 색으로 설정한다. 마지막으로, 이용 가능한 픽셀마다의 비트수로, 그 컬러값을 마스크 한다. 이 처리가 끝나면(자), 원의 색은 (0, 0)에 되돌려져 호출이 실제의 컬러 키값과 함께 DDSetColorKey 에 돌아온다. 호출이 돌아오면(자), 컬러 키값은 DDCOLORKEY 구조체의 dwColorSpaceLowValue 멤버에 배치된다. 또,dwColorSpaceHighValue 멤버에도 카피된다. 그리고,IDirectDrawSurface7::SetColorKey 를 호출하는 것으로, 컬러 키를 설정한다.

DDSetColorKey 및 DDColorMatch 의 CLR_INVALID 를 참조하고 있는 것에 깨닫았을지도 모른다. DDEx4 로 DDSetColorKey 의 호출에컬러 키로서 CLR_INVALID 를 건네주는 경우, 비트 맵의 맨 왼쪽 위쪽 (0, 0)의 픽셀이 컬러 키로서 사용된다. DDEx4 의 비트 맵이 건네받아도, (0, 0)그리고 픽셀의 색은 회색이 사고 있기 위해서(때문에) 그다지 의미는 없다. 다만, DDEx4 샘플의 컬러 키로서 (0, 0)로 픽셀을 사용하는 방법을 보고 싶으면, 드로잉(Drawing) 어플리케이션으로 All.bmp 비트 맵 파일을 열어, (0, 0)그리고 1 개의 픽셀을 흑으로 변경한다. 이 변경은 반드시 보존하는 것 (변경을 볼 수 없어지기 (위해)때문에). 다음에, DDSetColorKey 를 호출하는 DDEx4 의 행을 이하와 같이 변경한다.

DDSetColorKey(lpDDSOne, CLR_INVALID);

DDEx4 의 샘플을 재컴파일 하면, 새로운 비트 맵이 있기 위해서(때문에), 리소스 정의 파일도 재컴파일 되는 것을 확인한다 (확인하려면 , Ddex4.rc 파일에 1 개의 공간을 추가해 그것을 삭제하면 좋다). DDEx4 샘플은, 현시점에서 컬러 키로서 흑으로 설정되었다 (0, 0)로 픽셀을 사용하게 된다.

다음 방향 :스텝 2 : 간단한 애니메이션의 생성


스텝 2 : 간단한 애니메이션의 생성

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

DDEx4 의 샘플에서는 updateFrame 샘플 함수를 사용해, All.bmp 파일에 있는 붉은 고리를 사용하는 간단한 애니메이션을 생성 한다. 애니메이션은, 삼각형에 배치되어 다양한 스피드로 회전하는 3 개(살)의 붉은 고리로부터 된다. 이 샘플에서는, Win32 GetTickCount 함수를 GetTickCount 함수에의 마지막 호출로부터 경과한 밀리 세컨드와 비교해, 스프라이트를 재드로잉(Drawing) 할지 어떨지를 결정한다. 이것에 이어, 우선,IDirectDrawSurface7::BltFast 메소드를 사용해오프 스크린 표면 (lpDDSOne)으로부터백 버퍼에 백그라운드를 블리트 하고 나서, 미리 설정한컬러 키를 사용해 백 버퍼에 스프라이트를 블리트 해, 어느 픽셀을 투과형으로 할까를 결정한다. 스프라이트가 백 버퍼에 블리트 되고 나서, DDEx4 는 IDirectDrawSurface7::Flip 메소드를 호출해 백 버퍼와프라이머리 표면을 플립 한다.

오프 스크린 표면으로부터 백그라운드를 블리트 하기 위해서 IDirectDrawSurface7::BltFast 를 사용할때는, 전송의 타입을 지정하는 dwTrans 파라미터를 DDBLTFAST_NOCOLORKEY 로 설정한다. 이것은, 일반적인 블리트가 불투과성 비트로 생기는 것을 나타내고 있다. 그 후, 붉은 고리를 백 버퍼에 블리트 하면 와,dwTrans 파라미터를 DDBLTFAST_SRCCOLORKEY 로 설정한다. 이것은, 블리트가 정의된 투과성을 위한 컬러 키로 생기는 것을 나타내고 있다. 이 경우는,lpDDSOne 버퍼내이다.

이 샘플에서는, 매회, updateFrame 로부터 배경 전체가 재드로잉(Drawing) 된다. 이 샘플을 최적화하는 1 개의 방법은, 붉은 고리가 회전하고 있는 동안에, 변경하는 백그라운드의 부분만을 재드로잉(Drawing) 하는 것이다. 고리는 스프라이트 하는 직사각형의 배치나 사이즈는 변경하지 않기 때문에, DDEx4 샘플을 최적화하기 위한 간단한 수정을 할 수 있다.


튜토리얼 5 : 팔레트의 동적 변경

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

이 튜토리얼로 설명하는 샘플 (DDEx5 )은, 튜토리얼 4 로 설명한 샘플 (DDEx4)의 수정이다. DDEx5 에서는, 어플리케이션의 실행중에 팔레트 엔트리를 동적으로 변경하는 방법에 대해 가리킨다. DDEx5 의 신기능을 다음의 스텝에서 설명한다.

  • 스텝 1 : 팔레트 엔트리의 로드
  • 스텝 2 : 팔레트의 회전


스텝 1 : 팔레트 엔트리의 로드

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

DDEx5 의 다음의 코드에서는, All.bmp 파일의 후반 부분 (붉은 고리를 포함한 비트 맵 부분)의 값과 함께 팔레트 엔트리를 로드한다.

// 처음에, 모든 색을 미사용으로서 설정한다.
for(i=0; i<256; i++)
{
    torusColors[i] = 0;
}

// 표면을 잠그어, 후반 부분 (원환체 영역)을 스캔 한다.
// 발견된 모든 인덱스의 트랙을 보관 유지한다.
ddsd.dwSize = sizeof(ddsd);
while (lpDDSOne->Lock(NULL, &ddsd, 0, NULL) == DDERR_WASSTILLDRAWING)
    ;

// 원환체 프레임으로부터 검색해, 사용하는 색을 마크 한다.
for(y=480; y<480+384; y++)
{
    for(x=0; x<640; x++)
    {
        torusColors[((BYTE *) ddsd.lpSurface)[y*ddsd.lPitch+x]] = 1;
    }
}

lpDDSOne->Unlock(NULL);

torusColors 배열은, All.bmp 파일의 후반 부분에서 사용하는 팔레트의 컬러 인덱스의 인디케이터(indicator)로서 사용된다. 이것이 사용되기 전에,torusColors 배열의 모든 값을 0 에 리셋 한다. 오프 스크린 버퍼는, 컬러 인덱스값이 사용될지 어떨지를 결정하기 전에 락 된다.

torusColors 배열을, 비트 맵의 480 행 : 0 열로부터 시작 하도록(듯이) 설정한다. 배열의 컬러 인덱스값은, 비트 맵 표면이 배치되는 메모리의 위치의 데이터의 바이트로 정해진다. 이 정도치는,DDSURFACEDESC2 구조체의 lpSurface 멤버에 의해 정해진다. 이 멤버는, 비트 맵의 480 행 : 0 열 (y×lPitch + x)에 대응하는 메모리의 위치를 가리킨다. 특정의 컬러 인덱스값의 위치는, 1 으로 설정한다. y 의 값 (행)에 lPitch 값 (DDSURFACEDESC2 구조체에 있다)을 걸어, 선형 메모리에 있는 픽셀의 실제의 위치를 요구한다.

torusColors 로 설정된 컬러 인덱스값은, 다음에 팔레트내의 어느 색을 순환시킬까를 결정할 때에 사용한다. 백그라운드와 붉은 고리에는 공통되는 색이 존재하지 않기 때문에, 붉은 고리에 관련지을 수 있었던 색만을 순환시킨다. 이것이, true 일지 어떨지를 조사하려면 , 배열로부터 "*ddsd.lPitch" 를 삭제해, 프로그램을 재컴파일 해 실행할 경우에 무엇이 일어날까를 본다 (y×lPitch 를 실시하지 않으면 붉은 고리는 결코 순환하지 않고, 백그라운드를 구성하는 색에게만 인덱스가 붙어 다음에 순환한다). 폭 및피치에 대한 상세 정보는, 「폭과 피치」를 참조할것.

다음 방향 :스텝 2 : 팔레트의 회전


스텝 2 : 팔레트의 회전

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

DDEx5 의 updateFrame 샘플 함수는, 튜토리얼 4 (DDEx4)로 거의 같은 방법으로 작용한다. 최초로 백그라운드를백 버퍼에 블리트 해, 다음에 3 개의 고리를 전면에 블리트 한다. 다만, 표면을 플립 하기 전에, updateFrame 는프라이머리 표면의 팔레트를 doInit 함수로 생성 된팔레트 인덱스로부터 변경한다. 다음에 코드를 나타낸다.

// 팔레트를 변경한다.
if(lpDDPal->GetEntries(0, 0, 256, pe) ! = DD_OK)
{
    return;
}

for(i=1; i<256; i++)
{
    if(! torusColors[i])
    {
       continue;
    }
    pe[i]. peRed = (pe[i]. peRed+2) % 256;
    pe[i]. peGreen = (pe[i]. peGreen+1) % 256;
    pe[i]. peBlue = (pe[i]. peBlue+3) % 256;
}

if(lpDDPal->SetEntries(0, 0, 256, pe) ! = DD_OK)
{
    return;
}

IDirectDrawPalette::GetEntries 메소드는, 최초의 행으로 DirectDrawPalette 오브젝트로부터 팔레트값을 조회한다. pe 포인터로 가리켜지는 팔레트 엔트리값은 유효가 되기 (위해)때문에, 메소드는 DD_OK 를 돌려주어 처리를 계속한다. 이 초기화동안, 컬러 인덱스가 1 으로 설정되어 있는지 어떤지를 판단하는 torusColors 를 계속 조사한다. 1 으로 설정되어 있는 경우,pe 포인터로 가리켜지는 팔레트 엔트리의 적, 초록, 및 파랑의 값은 순환한다.

마크 된 모든 팔레트 엔트리가 순환한 후,IDirectDrawPalette::SetEntries 메소드를 호출해, DirectDrawPalette 오브젝트의 엔트리를 변경한다. 이 변경은, 프라이머리 표면으로 설정하는 팔레트가 작용 하면 곧바로 실행된다.

이것이 종료 하면, 계속되어 표면이 플립 된다.


튜토리얼 6 : 오버레이 표면의 사용

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

이 튜토리얼에서는, DirectDraw 나 하드웨어로 지원 하는 오버레이 표면을 어플리케이션으로 사용하는 방법에 대해 단계적으로 설명한다. 이 튜토리얼에서는, DirectX SDK 샘플에 있는 Mosquito 샘플 어플리케이션을 중심으로 설명한다. Mosquito 는, 오버레이 표면의 플립핑 체인을 사용해, 데스크탑상에 애니메이션 된 비트 맵을 프라이머리 표면에 블리트 하는 일 없이 표시하는 단순한 어플리케이션이다. 이 샘플은, 하드웨어 제한으로 대응하기 위해서 필요에 따라서 오버레이 표면의 특성을 조정한다.

Mosquito 샘플 어플리케이션은, 다음의 스텝에서 실행한다 (복잡한 태스크는, 서브 스텝에 분할되어 있다).

  • 스텝 1 : 프라이머리 표면의 생성
  • 스텝 2 : 하드웨어 오버레이 지원의 테스트
  • 스텝 3 : 오버레이 표면의 생성
  • 스텝 4 : 오버레이 표면의 표시
  • 스텝 5 : 오버레이 표시 위치의 갱신
  • 스텝 6 : 오버레이 표면의 은폐


스텝 1 : 프라이머리 표면의 생성

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

오버레이 표면을 사용하려면 , 최초로 DirectDraw 를 초기화해, 오버레이 표면을 표시하기 위한 프라이머리 표면을 생성 한다. Mosquito 에서는, 다음의 코드로 프라이머리 표면을 생성 한다.

    // 구조체를 초기화해, dwSize 멤버를 설정한다.
    ZeroMemory(&ddsd, sizeof(ddsd));
    ddsd.dwSize = sizeof(ddsd);

    // 플래그를 설정해, 프라이머리 표면을 생성 한다.
    ddsd.dwFlags = DDSD_CAPS;
    ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE;
    ddrval = g_lpdd->CreateSurface(&ddsd, &g_lpddsPrimary, NULL );

위의예는, 사용하는 DDSURFACEDESC2 구조체의 초기화로부터 시작된다. 다음에, 프라이머리 표면의 생성에 필요한 플래그를 설정해,IDirectDraw7::CreateSurface 메소드를 호출해 프라이머리 표면을 생성 한다. 이 호출에서는, 최초의 파라미터가, 생성 하는 표면을 기술하는 DDSURFACEDESC2 구조체에의 포인터가 된다. 2 번째의 파라미터는, 호출이 성공했을 경우의,IDirectDrawSurface7 인터페이스 포인터를 받는 변수에의 포인터가 된다. 마지막 파라미터는 NULL 로 설정해, COM 처리가 일어나지 않은 것을 나타낸다.

다음 방향 :스텝 2 : 하드웨어 오버레이 지원의 테스트


스텝 2 : 하드웨어 오버레이 지원의 테스트

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

DirectDraw 를 초기화한 후, 디바이스가 오버레이 표면을 지원 하는 것을 확인할 필요가 있다. DirectDraw 는 오버레이를 에뮬레이트 하지 않기 때문에, 하드웨어 디바이스 드라이버가 오버레이를 지원 하지 않는 경우에는 속행할 수 없다. 오버레이 지원을 테스트하려면 ,IDirectDraw7::GetCaps 메소드로 디바이스 드라이버의 능력을 취득한다. 이 호출 후, 관련하는 DDCAPS 구조체의 dwFlags 멤버로 DDCAPS_OVERLAY 플래그를 찾는다. 이 플래그가 있으면, 디스플레이 하드웨어는 오버레이를 지원 한다. 이 플래그가 없으면, 그 디바이스에서는 오버레이 표면을 이용할 수 없다.

Mosquito 샘플 어플리케이션에 있어서의 다음의 예에서는, 하드웨어 오버레이 지원의 테스트 방법에 대해 가리킨다.

BOOL AreOverlaysSupported()
{
    DDCAPS  capsDrv;
    HRESULT ddrval;

    // 드라이버 능력을 취득해, 오버레이 지원을 결정한다.
    ZeroMemory(&capsDrv, sizeof(capsDrv));
    capsDrv.dwSize = sizeof(capsDrv);

    ddrval = g_lpdd->GetCaps(&capsDrv, NULL);
    if (FAILED(ddrval))
        return FALSE;

    // 현재의 모드로, 드라이버가 오버레이를 지원 할까?
    // (현재, DirectDraw 에뮬레이션 계층은 오버레이를 지원 하고 있지 않다.
    // 하드웨어 지원이 없으면, 오버레이에 관한 API 는 실패한다.
    if (! (capsDrv.dwCaps & DDCAPS_OVERLAY))
        return FALSE;

    return TRUE;
}

위의예에서는,IDirectDraw7::GetCaps 메소드를 호출해 디바이스 드라이버 능력을 취득한다. 호출의 최초의 파라미터는, 디바이스 드라이버의 능력을 기술하는 정보로 파묻히는 DDCAPS 의 주소이다. 어플리케이션은, 에뮬레이션 능력에 관한 정보를 필요로 하지 않기 때문에, 2 번째의 파라미터는 NULL 로 설정한다.

드라이버 능력을 취득한 후, 이 예에서는, 논리 연산의 AND 처리로 dwCaps 멤버의 DDCAPS_OVERLAY 플래그의 존재를 조사한다. 플래그가 없는 경우, 이 예에서는 실패를 나타내는 FALSE 를 돌려준다. 플래그가 있는 경우는, 디바이스 드라이버가 오버레이 표면을 지원 하는 것을 나타내는 TRUE 를 돌려준다.

이 코드로, 다른 오버레이 표면이 다른 어플리케이션으로 사용되어 있지 않은 것을 확인 하면이야 있고. 그 때문에(위해)는,DDCAPS 구조체의 dwMaxVisibleOverlays 및 dwCurrentVisibleOverlays 멤버를 조사한다.

다음 방향 :스텝 3 : 오버레이 표면의 생성


스텝 3 : 오버레이 표면의 생성

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

드라이버가 오버레이 표면을 지원 하는 것을 알 수 있었으므로, 오버레이 표면을 생성 할 수 있다. 디바이스가 오버레이 표면을 지원 하는데 표준이 될 방법이 없기 때문에, 특정의 사이즈나 픽셀 포맷의 오버레이를 항상 생성 할 수 있다고는 할 수 없다. 게다가 1 번으로 오버레이 표면을 생성 할 수 있다고도 할 수 없다. 따라서, 가장 바람직한 특성을 가지는 오버레이 표면으로부터 생성하기 시작해 기능하는 오버레이 표면을 생성 할 수 있을 때까지, 구성의 특성을 떨어뜨리면서 (아마, 하드웨어 의존은 아니다) 몇번이나 생성을 시도한다.

주 ： IDirectDraw7::GetFourCCCodes 메소드를 호출하는 것으로, 드라이버가 오버레이 표면을 지원 할 것 같은 비 RGB 픽셀 포맷을 기술하는 FOURCC 코드의 리스트를 취득할 수 있다. 다만, RGB 오버레이 표면을 사용하는 경우에는, 최초로 다양한 공통 RGB 포맷으로 표면의 생성을 시도해 잘 되지 않으면 다른 포맷으로 시도하면(자) 좋다.

Mosquito 샘플에서는," 최선의 경우로부터 최악의 경우 " 라고 하는 생각에 따라 오버레이 표면을 생성 한다. Mosquito 에서는, 최초로 트리플 버퍼의 페이지 플립핑 복합 오버레이 표면의 생성을 시도한다. 그 생성에 실패했을 경우, 다음에 다른 공통 픽셀 포맷으로 구성을 시도한다. 이 경우의 코드를 다음에 나타낸다.

    ZeroMemory(&ddsdOverlay, sizeof(ddsdOverlay));
    ddsdOverlay.dwSize = sizeof(ddsdOverlay);

    ddsdOverlay.dwFlags= DDSD_CAPS | DDSD_HEIGHT | DDSD_WIDTH |
                         DDSD_BACKBUFFERCOUNT| DDSD_PIXELFORMAT;
    ddsdOverlay.ddsCaps.dwCaps = DDSCAPS_OVERLAY | DDSCAPS_FLIP |
                                 DDSCAPS_COMPLEX | DDSCAPS_VIDEOMEMORY;
    ddsdOverlay.dwWidth  =320;
    ddsdOverlay.dwHeight =240;
    ddsdOverlay.dwBackBufferCount=2;

    // 글로벌 리스트에 있는 픽셀 포맷의 1 개를 이용해,
    // 오버레이 표면의 생성을 시도한다.
    i=0;
    do{
    ddsdOverlay.ddpfPixelFormat=g_ddpfOverlayFormats[i];
       // 오버레이 표면의 생성을 시도한다.
       ddrval = g_lpdd->CreateSurface(&ddsdOverlay, &g_lpddsOverlay, NULL);
    } while( FAILED(ddrval) && (++i < NUM_OVERLAY_FORMATS) );

위의예에서는,DDSURFACEDESC2 구조체의 범위내에 플래그와 값을 설정해, 트리플 버퍼의 페이지 플립핑 복합 오버레이 표면을 반영한다. 다음에, 다양한 공통 픽셀 포맷으로 요구하는 표면을 생성 하기 위해서, 가장 바람직한 것으로부터 바람직하지 않은 픽셀 포맷의 순서에 루프를 실행한다. 표면을 생성 할 수 있으면(자), 루프는 종료한다. 표면을 생성 하는 시도가 모두 실패했을 경우, 디스플레이 하드웨어에 트리플 버퍼 스킴을 지원하기 위한 충분한 메모리가 없는지, 플립핑 오버레이 표면을 지원 하지 않을 가능성이 있다. 이 경우, 이 샘플에서는, 단일의 비플립핑 오버레이 표면을 사용하는 요구도의 낮은 구성으로 생성을 시도한다. 다음에 이 예를 나타낸다.

    // 트리플 버퍼 복합 오버레이 표면이 생성 되지 않는다
    // 경우, 단일의 비후립핑밧파이로 다시 생성을 시도한다.
    if(FAILED(ddrval))
    {
        ddsdOverlay.dwBackBufferCount=0;
        ddsdOverlay.ddsCaps.dwCaps=DDSCAPS_OVERLAY | DDSCAPS_VIDEOMEMORY;
        ddsdOverlay.dwFlags= DDSD_CAPS|DDSD_HEIGHT|DDSD_WIDTH|DDSD_PIXELFORMAT;

        // 오버레이 표면의 생성을 시도한다.
        ddrval = g_lpdd->CreateSurface(&ddsdOverlay, &g_lpddsOverlay, NULL);
        i=0;
        do{
            ddsdOverlay.ddpfPixelFormat=g_ddpfOverlayFormats[i];
            ddrval = g_lpdd->CreateSurface(&ddsdOverlay, &g_lpddsOverlay, NULL);
        } while( FAILED(ddrval) && (++i < NUM_OVERLAY_FORMATS) );

        // 오버레이 표면을 생성 할 수 없다. 실패를 돌려주어 종료한다.
        if (FAILED(ddrval))
            return FALSE;
    }

직전의 코드에서는,DDSURFACEDESC2 구조체의 플래그와 값을 리셋 해, 단일의 비플립핑 오버레이 표면을 반영한다. 표면을 생성 하기 위해서, 재차 픽셀 포맷화등 루프 한다. 생성에 성공하면(자), 루프는 종료한다. 이 경우에서도 생성 할 수 없으면, 샘플은 실패를 나타내는 FALSE 를 돌려준다.

오버레이 표면 또는 표면의 생성에 성공하면(자), 그 표면에 비트 맵을 로드해 표시를 준비할 수 있다.

다음 방향 :스텝 4 : 오버레이 표면의 표시


스텝 4 : 오버레이 표면의 표시

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

오버레이 표면을 생성 하면(자), 그것을 표시할 수 있다. 디스플레이 하드웨어에서는, 오버레이를 표시하기 위해서 사용하는 직사각형의 위치나 픽셀폭에 아라이먼트 제한을 부과하는 경우가 있다. 게다가 오버레이 표면을 잘 표시하기 위해서, 목적지 직사각형의 폭을 조정해 요구되는 최소 신축(스트레치) 계수에 맞도록(듯이) 하는 경우가 있다. Mosquito 샘플에서는, 오버레이 표면을 준비하고 나서 표시하기 위해서 다음의 태스크를 실행한다.

  • 스텝 4.1 : 최소 표시 요건의 결정
  • 스텝 4.2 : 전송원직사각형과 목적지 직사각형의 셋업
  • 스텝 4.3 : 오버레이 표면의 표시

다음 방향 :스텝 4.1 : 최소 표시 요건의 결정


스텝 5 : 오버레이 표시 위치의 갱신

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

오버레이 표면을 표시한 후, 그 밖에 아무것도 할 필요가 없을지도 모른다. 그러나, 소프트웨어에 따라서는, 오버레이 표면의 재배치가 필요하게 되는 경우도 있다. Mosquito 샘플에서는,IDirectDrawSurface7::SetOverlayPosition 메소드를 사용해 오버레이를 재배치한다. 다음에 예를 나타낸다.

// x 좌표 및 y 좌표를 설정한다.
    .
    .
    .
// x 위치에 대한 아라이먼트 제한의 유무를 조사할 필요
//  (이)가 있어, 필요하면 조절한다.
    if (g_dwOverlayXPositionAlignment)
        dwXAligned = g_nOverlayXPos - g_nOverlayXPos % g_dwOverlayXPositionAlignment;
    else
        dwXAligned = g_nOverlayXPos;

//  오버레이를 새로운 위치로 설정한다.
    ddrval = g_lpddsOverlay->SetOverlayPosition(dwXAligned, g_nOverlayYPos);
    if (ddrval == DDERR_SURFACELOST)
    {
        if (! RestoreAllSurfaces())
            return;
    }

위의예에서는, 직사각형을 연속시키는 것으로, 존재하는 목적지 직사각형의 경계 아라이먼트 제한으로 적합시킨다. 조사하는 글로벌 변수 g_dwOverlayXPositionAlignment 는, 어플리케이션이 IDirectDraw7::GetCaps 메소드를 전회 호출했을 때에,DDCAPS 구조체의 dwAlignBoundaryDest 멤버에 의해 보고된 값과 동일해지도록(듯이) 설정되어 있다 (상세 정보는, 「스텝 4.1 : 최소 표시 요건의 결정」을 참조할것). 목적지 아라이먼트 제한이 존재하는 경우, 새로운 x 좌표를 거기에 대응해 픽셀과 연속하도록(듯이) 조정한다. 이 요건이 채워지지 않은 경우는, 오버레이 표면은 표시되지 않는다.

새로운 x 좌표에 필요한 조정을 실시한 후,IDirectDrawSurface7::SetOverlayPosition 메소드를 호출해 오버레이를 재배치한다. 이 호출에서는, 최초의 파라미터가 연속한 x 좌표가 되어, 2 번째의 파라미터는 새로운 y 좌표가 된다. 이러한 값은, 오버레이의 맨 왼쪽 위쪽의 새로운 위치를 나타낸다. DirectDraw 는, 최초로 오버레이를 표시하는데 생성 한 IDirectDrawSurface7::UpdateOverlay 메소드로부터, 이미 표면의 치수를 취득하고 있기 (위해)때문에, 폭과 높이의 정보를 받지 않고, 또 필요로 하지 않는다. 1 개(살) 이상의 표면이 소실했기 때문에 호출이 실패 하면, 이 예에서는 어플리케이션으로 정의된 함수를 호출해, 없어진 표면을 restore 하고 나서, 그 비트 맵을 재로드한다.

주 ： 타겟 표면의 아래 쪽 또는 우측의 가장자리에 너무 가까운 좌표를 사용하지 않게 주의한다. IDirectDraw7::SetOverlayPosition 메소드는 클리핑을 실행하지 않는다. 즉, 오버레이가 타겟 표면의 인연을 초과할 가능성이 있는 좌표를 사용 하면, 이 메소드는 DDERR_INVALIDPOSITION 를 돌려주어 실패한다.

다음 방향 :스텝 6 : 오버레이 표면의 은폐


스텝 6 : 오버레이 표면의 은폐

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

오버레이 표면이 필요없게 되는지, 또는 단지 뷰로부터 삭제하고 싶은 경우는, 해당하는 플래그를 설정해 IDirectDrawSurface7::UpdateOverlay 메소드를 호출하면, 표면을 은폐 할 수 있다. Mosquito 에서는, 어플리케이션을 닫는 것에 갖추어 오버레이를 은폐 한다. 다음에 이 코드를 나타낸다.

void DestroyOverlay()
{
    if (g_lpddsOverlay){
// UpdateOverlay()에 DDOVER_HIDE 플래그를 사용해
// 오버레이를 디스플레이로부터 삭제한다.
        g_lpddsOverlay->UpdateOverlay(NULL, g_lpddsPrimary, NULL, DDOVER_HIDE, NULL);
        g_lpddsOverlay->Release();
        g_lpddsOverlay=NULL;
    }
}

위의예로 IDirectDrawSurface7::UpdateOverlay 를 호출하는 경우, 오버레이의 은폐에는 무관계하기 때문에, 전송원 및 목적지 직사각형은 NULL 를 지정한다. 같이 5 번째의 파라미터도, 오버레이 이펙트를 사용하지 않기 위해(때문에) NULL 로 한다. 2 번째의 파라미터는, 타겟 표면에의 포인터가 된다. 마지막으로, 오버레이가 뷰로부터 삭제되는 것을 나타내기 위해서(때문에), 4 번째의 파라미터에 DDOVER_HIDE 플래그를 사용한다.

오버레이를 은폐 한 후, 이 예에서는 IDirectDrawSurface7 인터페이스를 릴리즈 해, NULL 로 설정하는 것으로 그 글로벌 변수를 무효로 한다. Mosquito 샘플 어플리케이션에서는, 오버레이 표면은 이미 필요하지 않다. 다음에 오버레이 표면이 필요하게 되는 일이 있으면, 오버레이를 릴리즈 하지 않고 단지 은폐 해 두어, 필요에 따라서 재표시하면 좋다.


DirectDraw Visual Basic 튜토리얼

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

여기에서는, 다음의 튜토리얼을 사용해, 간단한 DirectDraw 어플리케이션을 이행 하는 방법을 스텝바이스텝으로 설명한다. 각 튜토리얼에서는, 이 SDK 가 제공하는 DirectDraw 샘플 파일을 많이 사용하고 있다. 이러한 샘플에서는, DirectDraw 의 셋업 방법과 일반적인 태스크를 실행하기 위한 DirectDraw 메소드의 사용 방법을 소개한다.

  • 튜토리얼 1 : 스크린에의 블리트
  • 튜토리얼 2 : 투과성의 사용
  • 튜토리얼 3 : 풀 스크린 기능의 사용
  • 튜토리얼 4 : 스크린의 영역에의 블리트
  • 튜토리얼 5 : DirectDraw 디바이스의 열거


튜토리얼 1 : 스크린에의 블리트

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

이 최초의 튜토리얼에서는, 비트 맵의 디스플레이 어댑터에의 블리트에 대해 설명한다. 이 블리트 (blit )란, 비트 블리트 (bit block transfer)여, 데이터의 블록을 메모리내가 있는 장소로부터 다른 장소에 전송 하는 프로세스를 가리킨다. 그래픽스 프로그래머는, 블리트를 사용해, 메모리내가 있는 장소로부터 다른 장소에 그래픽스를 전송 한다. 블리트는, 스프라이트 애니메이션의 실행에 자주(잘) 사용된다.

DirectDraw 를 사용하려면 , 우선 시작해에, 컴퓨터 위에의 디스플레이 어댑터를 나타내는 DirectDraw 오브젝트의 인스턴스를 생성 해야 한다. 그리고, 메소드를 사용해, 그 오브젝트를 조작한다. 게다가 어플리케이션을 그래픽스 표면상에 표시하려면 , DirectDrawSurface 오브젝트의 인스턴스를 1 개 이상 생성 할 필요가 있다.

이것을 나타내기 (위해)때문에, 이 SDK 에 포함되어 있는 「튜토리얼 1 : 스크린에의 블리트」의 샘플에서는, 이하의 스텝을 실행한다.

  • 스텝 1 : 폼의 생성
  • 스텝 2 : 모듈 레벨 변수의 선언
  • 스텝 3 : 변수의 초기화
  • 스텝 4 : 표면의 블리트


스텝 1 : 폼의 생성

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

튜토리얼 1 의 블리트 샘플은, 폼상에 픽쳐 박스 컨트롤을 배치한 표준의 . exe 프로젝트이다. 픽쳐 박스 컨트롤은, 폼의 좌상에 있는 픽쳐 박스의 좌상단에 배치된다. 이 픽쳐 박스는 Picture1 라고 명명되어 어플리케이션의 비트 맵 이미지를 표시한다.

다음 방향 :스텝 2 :모듈 레벨 변수의 선언


스텝 2 : 모듈 레벨 변수의 선언

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

Visual Basic 로 DirectX 어플리케이션을 코드화할 때의 최초의 스텝은,DirectX7 의 인스턴스 생성이다. 이 오브젝트에는, DirectDraw, DirectSound, Direct3D 직접 모드, Direct3D 보관 유지 모드, DirectInput, DirectPlay, DirectMusic 등, DirectX 컴퍼넌트의 스타트 오브젝트의 생성에 필요한 메소드가 모두 포함되어 있다. Direct3D 보관 유지 모드의 상세 정보는, 이 문서의 Appendix 노드에 있다.

DirectX7 클래스는, DxVBLib 타입 라이브러리의 최상정도 클래스에서, 이 클래스의 오브젝트는 다음의 문장에 의해 생성 된다.

Dim objDX As New DirectX7

튜토리얼 1 의 블리트 샘플에 기재되어 있는 모듈 레벨 변수의 선언에는, DirectDraw 오브젝트, DirectDrawSurface 오브젝트, DirectDrawClipper 오브젝트, DirectDraw 표면 기술 타입, 및 초기화 정보의 보관 유지에 사용되는 불 변수가 있다.

다음 방향 :스텝 3 : 변수의 초기화


스텝 3 : 변수의 초기화

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

Form_Load 이벤트로 불려 가는 최초의 프로시저는, init 프로시저이다. 이 프로시저는 DirectDraw 오브젝트를 생성 한다. 이것을 실행하려면 ,DirectX7 오브젝트의 DirectX7.DirectDrawCreate 메소드를 호출해, 돌려주어진 오브젝트를,DirectDraw7 클래스의 오브젝트 변수로서 선언한 DirectDraw 로 설정한다. 튜토리얼 1 의 블리트 샘플에서는, 이것을 다음의 문장으로 실행한다.

Set objDD = objDX.DirectDrawCreate("")

이 메소드는 캐릭터 라인 인수를 1 개만 필요로 해, 하늘의 캐릭터 라인을 건네주면(자) 액티브 디스플레이 드라이버를 지정한다.

다음에, DirectDraw 오브젝트의 DirectDraw7.SetCooperativeLevel 메소드를 호출해, 어플리케이션의 동작을 지정할 필요가 있다. 튜토리얼 1 의 블리트 샘플은 정규 윈도우 어플리케이션으로서 실행되어 다음의 문장에 의해 실행한다.

Call objDD.SetCooperativeLevel (Me.hwnd, DDSCL_NORMAL)

이것으로 표면 생성의 준비가 완료했다. 실제로 표면 오브젝트를 생성 하기 전에,DDSURFACEDESC2 형의 멤버를 설정해, 표면의 기술을 생성 할 필요가 있다. 이 형태의 멤버의 1 개로서 네스트형의 ddscaps 가 있다. DDSURFACEDESC2 의 lFlags 멤버를 DDSD_CAPS 로 설정하는 것으로, 이 형태에 대해 ddscaps 멤버가 유효한 것을 기술할 수가 있다. 이것은, 다음의 문장에 의해 실행된다.

ddsd1.lFlags = DDSD_CAPS

다음에, 이 형태의 기술이 프라이머리 표면용인 것을 지정한다. 이것은 다음의 문장으로 실행된다.

ddsd1.ddsCaps.lCaps = DDSCAPS_PRIMARYSURFACE

표면의 기술을 생성 하면(자), 세트 표면의 기술을 인수로서 DirectDraw 오브젝트로부터 CreateSurface 메소드를 호출해, 실제로 표면 오브젝트를 생성 한다. 튜토리얼 1 의 블리트 샘플에서는, 이것은 다음의 문장으로 실행된다.

Set objDDPrimSurf = objDD.CreateSurface(ddsd1)

다음의 표면의 생성에서도 이 표면 오브젝트 생성의 스텝을 반복하지만, 그 때는 DDSCAPS_OFFSCREENPLAIN 플래그를 세트 해, 그 표면이 오버레이, 텍스쳐, z 버퍼, 프런트 버퍼, 백 버퍼, 또는 알파 표면 이외의 오프 스크린 표면인 것을 지정한다. 이 스텝은, 평면 표면을 지정한다. 다음에,CreateSurfaceFromFile 메소드를 DirectDraw 오브젝트로부터 호출한다. 이 메소드는, 표면 오브젝트를 생성 해 비트 맵을 표면에 로드한다. 비트 맵의 위치는 FindMediaDir 프로시저로 지정한다. 이러한 스텝은, 이하의 문장으로 나타난다.

FindMediaDir "lake.bmp"

ddsd2.lFlags = DDSD_CAPS
ddsd2.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN
Set objDDSurf = objDD.CreateSurfaceFromFile("lake.bmp", ddsd2)

DirectDrawClipper 오브젝트를 생성 하려면 ,DirectDraw7.CreateClipper 메소드를 호출한다. 클립퍼, 즉 DirectDrawClipper 오브젝트를 사용해, 경계 직사각형으로 나타내지는 표면의 선택 부분에 블리트 할 수 있다. 튜토리얼 1 에서는,Picture1 픽쳐 박스 컨트롤에의 블리트에 대해 설명한다. 이것은 이하의 문장으로 실행된다.

Set ddClipper = objDD.CreateClipper(0)
ddClipper.SetHWnd Picture1.hWnd
objDDPrimSurf.SetClipper ddClipper

모든 변수와 오브젝트를 초기화하면(자),bInit 변수를 True 로 설정해 blt 서브 루틴을 호출한다.

다음 방향 :스텝 4 :표면의 블리트


스텝 4 : 표면의 블리트

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

「튜토리얼 1 : 스크린에의 블리트」의 샘플에서는, 프라이머리 표면과 로드한 비트 맵을 가지는 오프 스크린 표면을 생성 했다. 비트 맵을 스크린상에 표시하려면 , 오프 스크린 표면을 프라이머리 표면에 블리트 할 필요가 있다. DirectDraw 표면 오브젝트의 블리트 메소드는, 4 개의 인수를 취해, 블리트가 성공했는지 어떠했는지를 나타내는 Long 형을 돌려준다. 인수중 2 개(살)은, 목적지 표면과 전송원표면의 경계 직사각형을 지정하는 RECT 형이다.

전송원표면의 좌표는, 오프 스크린 표면의 기술의 lHeight 멤버와 lWidth 멤버로부터 취득한다. 목적지 직사각형을 취득하려면 , 한층 더 몇개의 스텝을 실행할 필요가 있다. 우선 시작해에, Visual Basic 는 스크린의 측정에 twip 를, DirectX 는 픽셀을 사용하기 위해(때문에), 목적지 직사각형을 설정하기 전에, Visual Basic 픽쳐 박스 컨트롤의 치수를 픽셀로 변환할 필요가 있다. 이것을 실행하려면 , 폼의 ScaleMode 프로퍼티를 Pixels 로 설정해, 픽쳐 박스의 폭과 높이를 폼의 ScaleWidth 와 ScaleHeight 에 동일하게 한다. 주 : ScaleMode 를 변경한 후도 폼의 폭과 높이의 단위는 twip 인 채이지만,ScaleWidth 와 ScaleHeight 의 단위는 픽셀이 되어 있다. 튜토리얼 1 의 블리트 샘플에서는, 이것을 이하의 문장으로 실행한다.

Picture1.Width = Me.ScaleWidth
Picture1.Height = Me.ScaleHeight

이러한 문장은 Form_Resize 이벤트내에 있어, 폼이 최초로 표시되고 사이즈 변경되었을 때에 실행된다.

게다가DirectX7.GetWindowRect 가 불려 가면(자), 목적지의 RECT 형에 정보가 파묻힌다.

마지막으로, 프라이머리 표면 오브젝트의 blt 메소드에 의해, 블리트가 실행된다.

ddrval = objDDPrimSurf.blt(r1, objDDSurf, r2, DDBLT_WAIT)

이 메소드의 결과,ddrval 에 저장 되는 Long 형이 돌려주어진다. 이 변수를 체크하면, 성공 또는 실패를 알 수 있다. 메소드의 마지막 인수는 DDBLT_WAIT 플래그이다. 이 플래그는, 블리트 기능이 Busy의 경우는 DirectDraw 에 대기하도록 지시해, 이용 가능한 상태가 되면(자) 표면을 블리트 하도록(듯이) 지시한다.


튜토리얼 2 : 투과성의 사용

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

튜토리얼 2 에서는, 투과형 블리트를 소개해, 튜토리얼 1 으로 배운 개념을 한층 더 넓혀 간다. 투과형 블리트에 의해, 스프라이트를 애니메이션 할 경우에, 직사각형 이외의 형태를 블리트 했는지와 같이 보일 수가 있다. 스프라이트 이미지는 보통은 직사각형은 아니지만, 블리트는 항상 직사각형이기 (위해)때문에, 스프라이트의 경계 직사각형내의 모든 픽셀이 데이터 전송 된다. 투과형 블리트에 의해, 스프라이트 이미지 부분 이외의 픽셀은, 목적지에 이미지가 블리트 될 때는 투과색으로서 전송 된다. 따라서, 이러한 픽셀에 의해 백그라운드 이미지 위에의 픽셀의 색이 변경될 것은 없다.

스프라이트를 생성 하는 경우, 투과색의 컬러 키로서 사용하는 임의의 색 또는 색역을 선택한다. 이 튜토리얼에서는, 스프라이트 이미지 위에의 전송원컬러 키를 사용해, 직사각형 이외의 형태를 블리트 하고 있도록(듯이) 보이게 한다.

이 튜토리얼에서의 최초의 스텝은 프라이머리 표면의 생성이며, 이 점에서는 튜토리얼 1 의 「스텝 3 : 변수의 초기화」와 같은 순서가 된다. 따라서 중복을 피하기 (위해)때문에, 이 튜토리얼에서는 백 버퍼 표면의 생성으로부터 시작한다.

투과형 블리트의 예를 나타내기 (위해)때문에, SDK 의 튜토리얼 2 에서는, 이하의 스텝을 실행한다.

  • 스텝 1 : 백 버퍼의 생성
  • 스텝 2 : 표면의 초기화
  • 스텝 3 : 프라이머리 표면에의 블리트


스텝 1 : 백 버퍼의 생성

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

튜토리얼 2 의 샘플에서는, 오프 스크린 표면을 합성 표면으로서 사용한다. 오프 스크린 표면은, 메모리내에 개념으로서 존재하는 직사각형 영역이며, 이 영역에는 보통 프라이머리 표면에 블리트 되는 비트 맵이 저장 된다. 이 백 버퍼를 사용해 호수의 이미지와 스프라이트의 이미지를 저장 해, 그 후 합성된 이미지를 스크린에 표시한다. 이 표면은, 이하의 문장으로 생성 된다.

'비표시 표면을 생성 해 드로잉(Drawing) 한다.
'이것을 시스템 메모리내의 합성 표면으로서 사용한다.

'높이와 폭을 지정하고 싶은 것을 나타낸다.
'표면의 포맷 (bits per pixel)은
'프라이머리 표면과 같다.
ddsdBackBuffer.lFlags = DDSD_CAPS Or DDSD_HEIGHT Or DDSD_WIDTH

'표시되지 않는 표면이 필요한 것과
'그 표면을 비디오 메모리는 아니고 시스템 메모리에 배치하는 것을 나타낸다.
ddsdBackBuffer.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN Or DDSCAPS_SYSTEMMEMORY

'표면의 높이와 폭을
'픽쳐 박스와 같게 되도록(듯이) 지정한다 (단위는 픽셀인 것에 주의).
ddsdBackBuffer.lWidth = Picture1.Width
ddsdBackBuffer.lHeight = Picture1.Height

'요구된 표면을 생성 한다.
Set objDDBackBuffer = objDD.CreateSurface(ddsdBackBuffer)

다음 방향 :스텝 2 : 표면의 초기화


스텝 2 : 표면의 초기화

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

이 스텝에서는, 백그라운드 이미지용과 스프라이트 이미지용의 게다가 2 개의 표면의 생성과 초기화에 대해 설명한다. 또, 스프라이트 이미지의 표면에 투과색의 컬러 키를 지정한다.

어느 쪽의 표면도 DirectDraw7.CreateSurfaceFromFile 메소드를 호출해 생성 하는 오프 스크린 표면이다. 최초로 생성 되는 objDDLakeSurf 는 백그라운드 이미지용의 표면이며, 그 폭과 높이는, 폼 위에의 Picture1 픽쳐 박스 컨트롤과 같다. 2 번째의 표면 objDDSpriteSurf 에는, 스프라이트 이미지가 포함되어 이 스프라이트 이미지는 최종적으로 백 버퍼로 백그라운드 이미지와 합성된다. 이러한 표면은 이하의 문장으로 생성 된다.

'호수의 백그라운드 이미지를 로드한다.

'오프 스크린 표면을 생성 하는 것을 나타낸다.
'오프 스크린 표면은, 메모리 (비디오 메모리 또는 시스템 메모리) 내에 있어,
'유저로부터는 안보이는 표면이다.
ddsdLake.lFlags = DDSD_CAPS Or DDSD_WIDTH Or DDSD_HEIGHT
ddsdLake.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN
ddsdLake.lWidth = Picture1.Width
ddsdLake.lHeight = Picture1.Height

'표면을 생성 해, lake.bmp 를 표면에 로드한다.
Set objDDLakeSurf = objDD.CreateSurfaceFromFile("lake.bmp", ddsdLake)

'백그라운드를 합성 표면에 카피한다.
RepaintEntireBackground

'날고 있는 개의 스프라이트 이미지를 로드한다.

ddsdSprite.lFlags = DDSD_CAPS Or DDSD_WIDTH Or DDSD_HEIGHT
ddsdSprite.lWidth = 64
ddsdSprite.lHeight = 64
ddsdSprite.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN

Set objDDSpriteSurf = objDD.CreateSurfaceFromFile("disk1.bmp", ddsdSprite)

다음에, 스프라이트 표면의 투과색컬러 키를 설정한다. 컬러 키는 DDCOLORKEY 형 변수에 의해 지정한다. 이 데이터형에는 low 와 high 의 2 개의 멤버가 있어, 모두 Long 형이다. 컬러 키로서 사용하는 값의 범위를 지정하는지, 또는 양쪽 모두의 멤버에 같은 값을 건네주면 단색을 지정할 수가 있다. 튜토리얼 2 의 샘플에서는, high 와 low 의 양쪽 모두의 멤버의 값이 0 이며, 전부 칠한 흑을 컬러 키로 하는 것을 나타낸다. 컬러 키를 표면상으로 설정하려면 ,DirectDrawSurface7.SetColorKey 메소드를 호출한다.

표면상에서 지정할 수 있는 컬러 키에는, 이하의 2 개의 종류가 있다. 전송원컬러 키는, (블리트시에) 목적지 표면에 카피되지 않는, 또는 (오버레이시에) 목적지 표면에는 표시되지 않는 색이다. 목적지 컬러 키는, (블리트시에) 목적지 표면상에서 옮겨놓을 수 있다, 또는 (오버레이시에) 목적지 표면상에서 커버되는 색이다. 튜토리얼 2 의 샘플에서는, 전송원컬러 키를 사용한다. 컬러 키의 설정에는, 이하의 스텝을 실행한다.

'스프라이트의 투과색을 설정한다.

Dim key As DDCOLORKEY

key.low = 0
key.high = 0

'스프라이트 오브젝트에 투과색을 할당한다.
'DDCKEY_SRCBLT 는, blt 의 실행시에,
'투과색은 블리트처의 표면은 아니고
'전송원의 표면에 관련지을 수 있는 것을 지정한다.
objDDSpriteSurf.SetColorKey DDCKEY_SRCBLT, key

다음 방향 : 스텝 3 : 프라이머리 표면에의 블리트


스텝 3 : 프라이머리 표면에의 블리트

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

단순한 스프라이트 애니메이션을 스크린상에 표시하려면 , 몇개의 스텝이 필요하다. 스프라이트 표면과 백그라운드 이미지가 백 버퍼에 합성되어 그 후 백 버퍼가 프라이머리 표면에 블리트 된다. 애니메이션을 생성 하려면 , 스프라이트 표면을 백 버퍼에 블리트 할 경우에, 목적지 직사각형의 위치를 계속적으로 움직인다. 튜토리얼 2 에서는, 어플리케이션의 실행중에, DoFrame 프로시저가 스프라이트 표면의 위치를 갱신해, 백그라운드 이미지를 재드로잉(Drawing) 한다. 또, 애니메이션의 매초의 프레임수 (fps)를 표시하기 위한 코드가 몇개인가 있다.

초에, 단순한 타이머 루프를 이행 해 스프라이트의 배치 각도를 계산한다.

t2 = Timer
If t1 <> 0 Then
    a = a + (t2 - t1) * 100
    If a > 360 Then a = a - 360
End If
t1 = t2

다음에, 생성 한 표면이 아직 제어 되어 있는 것을 확인한다. 디스플레이 어댑터의 제어가 다른 프리케이션으로 옮겼을 경우는 표면이 소실하는 일이 있어, 그 때는 restore 할 필요가 있다. 튜토리얼 2 의 샘플에는, DirectDraw 오브젝트의 협조 레벨을 테스트해, 표면을 restore 할 필요가 있을지 어떨지를 결정하는 단순한 함수 ExModeActive 가 포함된다. 이것을, 이하의 코드로 가리킨다.

Dim bRestore As Boolean
bRestore = False
Do Until ExModeActive
    DoEvents
    bRestore = True
Loop

DoEvents
If bRestore Then
    bRestore = False
    objDD.RestoreAllSurfaces
End If

다음에, 코드의 스몰 비트를 이행 해, 스프라이트 애니메이션의 매초의 프레임수 (fps)를 표시한다. 이것은, 어플리케이션을 효율화해, 어플리케이션에 잠복하는 장해를 발견하는데 도움이 된다.

'FPS 를 계산한다.
i = i + 1
If i = 30 Then
    tNow = Timer
    If tNow <> tLast Then
       fps = 30 / (Timer - tLast)
       tLast = Timer
       i = 0
       Me.Caption = "DD Transparency    Frames per Second =" + Format$(fps, "#. 0")
    End If
End If

다음에, 스프라이트를 배치하는 위치의 x 좌표와 y 좌표를 계산한다.

x = Cos((a / 360) * 2 * 3.141) * Picture1.Width / 8
y = Sin((a / 360) * 2 * 3.141) * Picture1.Height / 8
x = x + Picture1.Width / 2
y = y + Picture1.Height / 2

스프라이트의 직전의 위치는 RECT 형에 보관 유지되고 있기 (위해)때문에, 백그라운드 표면 중(안)에서 영향을 받은 부분만을 재드로잉(Drawing) 할 수가 있다. 이 결과, 표면 전체를 계속적으로 블리트 할 필요가 없어져, 어플리케이션의 퍼포먼스가 향상한다. 다음에, 스프라이트의 새로운 위치를 결정해, 스프라이트 표면을 백 버퍼에 블리트 한다.

'필요한 부분의 백그라운드만을 재드로잉(Drawing) 해,
'마지막 프레임으로부터 백그라운드를 없앤다.
Dim rClean As RECT
If lastX <> 0 Then
    rClean.Left = lastX
    rClean.Top = lastY
    rClean.Right = lastX + ddsdSprite.lWidth
    rClean.Bottom = lastY + ddsdSprite.lHeight
    Call objDDBackBuffer.BltFast(lastX, lastY, objDDLakeSurf, rClean, DDBLTFAST_WAIT)
End If

lastX = x
lastY = y

'스프라이트를 백 버퍼에 블리트 한다.
'그 때, 전송원의 컬러 키를 사용해,
'blt 의 완료를 기다려 이동을 시작 한다.
Dim rtemp As RECT
rtemp.Left = x
rtemp.Top = y
rtemp.Right = x + ddsdSprite.lWidth
rtemp.Bottom = y + ddsdSprite.lHeight

objDDBackBuffer.Blt rtemp, objDDSpriteSurf, rSprite, DDBLT_KEYSRC Or DDBLT_WAIT

마지막으로,DirectX7.GetWindowRect 메소드를 호출해 픽쳐 박스 컨트롤의 직사각형 좌표를 취득해,DirectDrawSurface7.Blt 메소드를 호출해 백 버퍼를 프라이머리 표면에 블리트 한다.

Call objDX.GetWindowRect(Picture1.hWnd, rPrim)

Call objDDScreen.Blt(rPrim, objDDBackBuffer, rBackBuffer, DDBLT_WAIT)


튜토리얼 3 : 풀 스크린 기능의 사용

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

여기에서는, 풀 스크린 DirectDraw 어플리케이션의 생성예를 나타낸다. 이 튜토리얼은, 「튜토리얼 2 : 투과성의 사용」이라고 거의 같이이지만, 이 튜토리얼에서는 풀 스크린내에서 실행하기 위해(때문에), 이행 내용이 조금 다르다. 이 튜토리얼에서는 주로, 프라이머리 표면에 백 버퍼를 재블리트 하는 대신에, 복합 표면과 플립핑 체인의 개념을 사용한다. 풀 스크린 어플리케이션은, 이하의 스텝에 의해 생성 된다.

  • 스텝 1 : 협조 레벨과 디스플레이 모드의 설정
  • 스텝 2 : 복합 표면의 생성
  • 스텝 3 : 표면의 초기화
  • 스텝 4 : 페이지 플립핑에 의한 디스플레이의 갱신


스텝 1 : 협조 레벨과 디스플레이 모드의 설정

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

DirectDraw 로 풀 스크린 어플리케이션을 생성 하는 최초의 스텝으로서 DirectDraw 오브젝트의 협조 레벨과 디스플레이 모드를 설정한다. 협조 레벨의 설정에 의해, 어플리케이션의 최상정도 레벨의 동작이 정해진다. 이 어플리케이션은, 프라이머리 디스플레이에 배타 액세스를 실시해, 풀 스크린으로 실행시키고 싶다. 주 : 풀 스크린 모드로 실행하려면 , 배타 액세스도 필요하다. 게다가 표준 VGA Mode 13 으로부터 파생하는 Mode X 를 사용할 수 있도록(듯이) 한다. 협조 레벨은, 이하의 호출에 의해 설정한다.

Set dd = dx.DirectDrawCreate("")
Me.Show
Call dd.SetCooperativeLevel(Me.hWnd, DDSCL_FULLSCREEN Or DDSCL_ALLOWMODEX Or DDSCL_EXCLUSIVE)

협조 레벨을 설정한 후,DirectDraw7.SetDisplayMode 메소드를 호출해, 이 어플리케이션의 디스플레이 모드를 설정한다.

dd.SetDisplayMode 640, 480, 16, 0, DDSDM_DEFAULT

최초의 2 개의 파라미터는 모드의 높이로 폭이다. 3 번째의 파라미터는 픽셀마다의 비트수 (bpp)이다. 다음의 파라미터는 refresh rate으로, 0 을 지정해 드라이버의 디폴트 refresh rate를 요구한다. 마지막 파라미터는 추가 옵션이며, DDSDM_DEFAULT 는 Mode X 를 Mode 13 으로 대용하지 않고 모드를 설정한다.

다음 방향 :스텝 2 : 복합 표면의 생성


스텝 2 : 복합 표면의 생성

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

튜토리얼 2 에서는, 오프 스크린의 백 버퍼 표면이, 백그라운드 이미지와 스프라이트 이미지의 합성 표면으로서 사용되었다. 이 튜토리얼에서는, 백 버퍼를 복합 표면의 부분으로서 사용한다. 복합 표면과는 DirectDraw7.CreateSurface 메소드에의 단일 호출에 의해 생성 되는 일련의 표면을 가리킨다. CreateSurface 를 호출할 때에 DDSCAPS_COMPLEX 플래그가 설정되어 있는 경우, DirectDraw 는, 명시적으로 지정된 표면 이외에 1 개(살) 또는 복수의 표면을 암묵중에 생성 한다.

복합 표면 중(안)에서 가장 편리하지만 1 개(살)이, flipping chain 이다. 보통, 플립핑 체인은 primary surface 와 1 개 이상의 back buffers. (으)로 구성된다. DDSCAPS_FLIP 플래그는, 표면이 플립핑 체인의 부분인 것을 나타낸다. 이 방법으로 플립핑 체인을 생성 하려면 , DDSCAPS_COMPLEX 플래그가 필요하다.

튜토리얼 2 의 샘플에서는, 이하의 문장에 의해, 백 버퍼를 1 개 가지는 플립핑 체인을 생성 한다.

ddsd1.lFlags = DDSD_CAPS Or DDSD_BACKBUFFERCOUNT
ddsd1.ddsCaps.lCaps = DDSCAPS_PRIMARYSURFACE Or DDSCAPS_FLIP Or DDSCAPS_COMPLEX
ddsd1.lBackBufferCount = 1
Set primary = dd.CreateSurface(ddsd1)

다음에,DDSCAPS2 형 변수를 생성 해, DSCAPS_BACKBUFFER 플래그를 설정해, 이것이 백 버퍼의 표면 기술인 것을 지정한다. 그리고, 생성 한 백 버퍼를 DirectDrawSurface7.GetAttachedSurface 메소드를 사용해 취득한다.

Dim caps As DDSCAPS2
caps.lCaps = DDSCAPS_BACKBUFFER
Set backbuffer = primary.GetAttachedSurface(caps)

다음 방향 :스텝 3 : 표면의 초기화


스텝 3 : 표면의 초기화

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

백그라운드 이미지와 스프라이트 이미지를 위한 오프 스크린 표면 버퍼의 초기화는, 본질적으로는스텝 2 : 와 같다. 「표면의 초기화」는, 튜토리얼 2 에 있다. 유일한 상위는, 여기에서는 백 버퍼의 표면 기술에 의해 백그라운드 표면을 생성 하는 점이다. 이것은,DirectDrawSurface7.GetSurfaceDesc 메소드를 호출하는 것으로 간단하게 취득할 수 있다. 이것은, 이하의 문장으로 나타난다.

backbuffer.GetSurfaceDesc ddsd4
ddsd2.lFlags = DDSD_CAPS Or DDSD_HEIGHT Or DDSD_WIDTH
ddsd2.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN
ddsd2.lWidth = ddsd4.lWidth
ddsd2.lHeight = ddsd4.lHeight
Set lakesurf = dd.CreateSurfaceFromFile("lake.bmp", ddsd2)

다음 방향 :스텝 4 : 페이지 플립핑에 의한 디스플레이의 갱신


스텝 4 : 페이지 플립핑에 의한 디스플레이의 갱신

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

이 스텝은, 튜토리얼 2 의 「스텝 3 : 프라이머리 표면에의 블리트」라고 거의 같이이다. 실제, 결과는 같지만, 이 튜토리얼에서는 풀 스크린으로 실행되는 점이 다르다. 그러나, 백 버퍼 전체를 프라이머리 표면에 계속적으로 재블리트 하는 대신에 백 버퍼를 플립핑 체인의 일부로서 생성 했기 때문에, 페이지 플립핑을 사용할 수 있다.

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

이 어플리케이션은, 백 버퍼에 쓰기를 실시해, 그리고 프라이머리 표면을 플립 시켜 백 버퍼를 스크린상에 표시시킨다. 시스템이 이미지를 표시하고 있는 동안에, 다시 백 버퍼에의 쓰기를 실시한다. 어플리케이션이 실행되고 있는 동안 이 처리가 계속되어 이미지를 재빠르게 효율적으로 애니메이션 할 수 있다.

백그라운드 이미지와 스프라이트를 백 버퍼에 블리트 한 후,DirectDrawSurface7.Flip 메소드를 호출해 표면을 플립 한다.

primary.Flip Nothing, DDFLIP_WAIT


튜토리얼 4 : 스크린의 영역에의 블리트

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

SDK 의 튜토리얼 4 는, 「튜토리얼 3 : 풀 스크린 기능의 사용」에 스프라이트 애니메이션을 추가한 것과 거의 같이이다. 실제, 이 2 개의 어플리케이션의 상위는, 이 튜토리얼에서는 애니메이션의 프레임이 많은 비트 맵을 사용 하면 말하는 점뿐이다. 이메이지뷰아로 donut.bmp 파일을 열면(자), 단일의 비트 맵인 것에도 불구하고, 조금씩 시점이 다른 수많은 도너츠의 형태가 존재하는 것을 알 수 있다. 애니메이션은, 백 버퍼상에서의 스프라이트의 목적지 직사각형의 위치를 변경하는 것으로 실행된다. 게다가 다양한 시점의 도너츠가 순환해 블리트 되어 스프라이트가 회전한다.

이 튜토리얼은 튜토리얼 3 에 유사하고 있지만, 여기에서는 스프라이트를 애니메이션 하는 방법에 대해서도 설명한다.

  • 스텝 1 : 스프라이트의 애니메이션


스텝 1 : 스프라이트의 애니메이션

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

donut.bmp 이미지에 포함되는 도너츠의 각 인스턴스의 높이로 폭을 알 수 있고 있기 (위해)때문에, 비트 맵을 열과 행 로 분리해, 각 셀을 도너츠의 단일 이미지로 할 수 있다.

ddsd3.lFlags = DDSD_CAPS
ddsd3.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN
Set spritesurf = dd.CreateSurfaceFromFile("donut.bmp ", ddsd3)
spriteWidth = 64
spriteHeight = 64
cols = ddsd3.lWidth / spriteWidth
rows = ddsd3.lHeight / spriteHeight

DirectDrawSurface7.BltFast 메소드를 자주(잘) 보면(자),srcRect 파라미터는, 전송원표면상으로부터 블리트 되는 직사각형의 좌상과 우하의 점을 정의하는 RECT 형인 것을 알 수 있다. 따라서, 스프라이트 표면의 부분 즉 셀을 랜덤으로 지정하면, 스프라이트 애니메이션이 생성된다.

col = currentFrame Mod cols
row = Int(currentFrame / cols)
rSprite.Left = col * spriteWidth
rSprite.Top = row * spriteHeight
rSprite.Right = rSprite.Left + spriteWidth
rSprite.Bottom = rSprite.Top + spriteHeight

'애니메이션 된 스프라이트를 백 버퍼에 blt 한다.
ddrval = backbuffer.BltFast(rSprite2.Left, rSprite2.Top, spritesurf, _
         rSprite, DDBLTFAST_SRCCOLORKEY Or DDBLTFAST_WAIT)


튜토리얼 5 : DirectDraw 디바이스의 열거

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

튜토리얼 5 의 샘플 어플리케이션에서는, DirectX for Visual Basic 의 열거 오브젝트를 사용해, DirectDraw 디바이스의 정보를 취득하는 방법을 나타낸다. 이 어플리케이션은, 시스템에 인스톨 되고 있는 DirectDraw 디바이스 마다, 하드웨어 및 소프트웨어의 능력, 3D 하드웨어 및 소프트웨어의 능력, 이용 가능한 디스플레이 모드를 보고한다.

이 튜토리얼은, 이하의 스텝으로 구성된다.

  • 스텝 1 : 인스톨 되고 있는 DirectDraw 디바이스의 취득
  • 스텝 2 : DirectDraw 디바이스의 능력의 표시
  • 스텝 3 : DirectDraw 디바이스의 3D 능력의 표시
  • 스텝 4 : 이용 가능한 디스플레이 모드의 보고


스텝 1 : 인스톨 되고 있는 DirectDraw 디바이스의 취득

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

DirectX for Visual Basic 에서는, 실행시의 디스플레이 하드웨어의 능력을 조회해, 그 호스트 컴퓨터의 하드웨어 능력으로 가능한 최고의 퍼포먼스를 제공한다. 이것은, DxVBLib 타입 라이브러리가 많은 열거 오브젝트를 사용하는 것으로써, 간단하게 실행할 수 있다.

최초의 스텝에서는, 시스템상에 인스톨 떠날 수 있어 모든 DirectDraw 디바이스를 취득한다. 프라이머리 디스플레이 어댑터 이외에, 시스템에 따라서는 복수의 디스플레이 카드가 인스톨 되고 있는 경우가 있다. 일반적으로는, 이차적인 3D 그래픽 카드이다. 인스톨 떠날 수 있어 모든 디바이스를 취득하려면 ,DirectX7.GetDDEnum 메소드를 호출한다. 이 메소드는, 정보를 조회하는 DirectDrawEnum 오브젝트를 돌려준다. DirectDrawEnum 오브젝트의 메소드에 의해, 인스톨 되고 있는 디바이스수와 각 디바이스의 명칭, 설명, GUID, 및 모니터 핸들을 취득한다.

튜토리얼 5 의 샘플 어플리케이션에서는, 이것을 이하의 코드로 실행한다.

Dim ddEnum As DirectDrawEnum
Dim strGuid As String

Set ddEnum = m_dx.GetDDEnum()
OutList.AddItem "Display Cards"
For i = 1 To ddEnum.GetCount()
    OutList.AddItem " Index        " + Str(i)
    OutList.AddItem " Description  " + ddEnum.GetDescription(i)
    OutList.AddItem " Name         " + ddEnum.GetName(i)
    OutList.AddItem " GUID         " + ddEnum.GetGuid(i)
    OutList.AddItem ""

    strGuid = ddEnum.GetGuid(i)
    GetDDCaps strGuid
    GetD3DDevices strGuid
    GetDisplayModes strGuid

Next

GetDDCaps, GetD3DDevices, 및 GetDisplayModes 의 각 프로시저는, 시스템에 인스톨 되고 있는 디바이스 마다 불려 가는 것에 주의한다.

정보는, 리스트 박스 컨트롤에 기재된 형태로 표시된다.

다음 방향 : 스텝 2 : DirectDraw 디바이스의 능력의 표시


스텝 2 : DirectDraw 디바이스의 능력의 표시

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

디바이스의 DirectDraw 하드웨어 및 소프트웨어의 능력을 취득하려면 , 우선 DirectDraw 오브젝트를 생성 해, 어플리케이션의 협조 레벨을 설정해 DirectDraw7.GetCaps 메소드를 호출한다. 이 메소드는 2 개의 파라미터를 취하지만, 어느쪽이나 DDCAPS 형 변수이다. 이 메소드를 호출하면, 최초의 파라미터 hwCaps 에 하드웨어의 능력이 저장 된다. 2 번째의 파라미터 helCaps 에는, 하드웨어 미소 배급량 계층 (HEL)의 능력이 저장 된다. 하드웨어 및 소프트웨어 능력의 상세 정보는, 「DirectDraw 아키텍쳐의 개요」를 참조할것.

GetCaps 메소드를 호출한 다음에,DDCAPS 변수에 돌려주어진 플래그를 체크해, 능력을 표시한다.

Dim dd As DirectDraw7
Dim hwCaps As DDCAPS   '하드웨어.
Dim helCaps As DDCAPS  '소프트웨어 에뮬레이션.

Set dd = m_dx.DirectDrawCreate(sGuid)
dd.SetCooperativeLevel Me.hWnd, DDSCL_NORMAL

'HW 가 기능을 지원
'할지 어떨지를 조사하는 것은 좋은 생각이다.
'지원 되지 않는 기능은, 소프트웨어를 개입시켜
'에뮬레이트 되지만, 처리 속도는 꽤 늦어진다.
dd.GetCaps hwCaps, helCaps

'이용 가능한 비디오 메모리량.
OutList.AddItem "  HW CAPS"
OutList.AddItem "   total video memory " + Str(hwCaps.lVidMemTotal)
OutList.AddItem "   free video memory " + Str(hwCaps.lVidMemFree)

'팔레트 지원.
'대부분의 어플리케이션은, 모든 카드가
'16bpp 를 지원 하기 위한(해), 팔레트를 사용하지 않는다.
'속도의 관점으로부터 8bpp 를 사용하는 경우도 있다.

lVal = hwCaps.lPalCaps
If (lVal = 0) Then
    OutList.AddItem "   no hw palette support"
End If
If (lVal And DDPCAPS_1BIT) Then
    OutList.AddItem "   palette support 1bpp "
End If
If (lVal And DDPCAPS_2BIT) Then
    OutList.AddItem "   palette support 2bit "
End If

'감마 램프 인터페이스를 지원 할까 ?
lVal = hwCaps.ddsCaps.lCaps2
If lVal And DDCAPS2_CANCALIBRATEGAMMA Then
    OutList.AddItem "   supports gamma correction"
Else
    OutList.AddItem "   no support for gamma correction"
End If

Set dd = Nothing

다음 방향 : 스텝 3 : DirectDraw 디바이스의 3D 능력의 표시


스텝 3 : DirectDraw 디바이스의 3D 능력의 표시

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

DirectDraw 디바이스의 3D 능력의 취득은, 이 튜토리얼의 전의 스텝과 거의 같이이다. 우선,Direct3D7 오브젝트를 DirectDraw7 오브젝트로부터 생성 한다. 다음에,Direct3D7.GetDevicesEnum 메소드를 호출해 Direct3DEnumDevices 열거 오브젝트를 생성 해, 정보를 묻는다. 그리고, 열거 오브젝트의 메소드를 호출해, 시스템의 Direct3D 디바이스에 대한 정보를 취득한다.

튜토리얼 5 의 샘플에서는,Direct3DEnumDevices.GetDesc 메소드를 Direct3D 디바이스 마다 호출해, 능력을 취득한다. 다음에,D3DDEVICEDESC7 형으로 능력 플래그를 체크 하면, 그 결과가 리스트 박스로 보고된다. 이것은, 이하의 문장으로 나타난다.

Set dd = m_dx.DirectDrawCreate(sGuid)
Set d3d = dd.GetDirect3D()

OutList.AddItem "   D3D devices"

Set d3denum = d3d.GetDevicesEnum()

OutList.AddItem ""

For i = 1 To d3denum.GetCount()

    d3denum.GetDesc i, hwDesc
    OutList.AddItem "     Guid        " + d3denum.GetGuid(i)
    OutList.AddItem "     Description " + d3denum.GetDescription(i)
    OutList.AddItem "     Name        " + d3denum.GetName(i)
    OutList.AddItem "     Device "
    With hwDesc
        OutList.AddItem "     Max Texture Height  " + Str(. lMaxTextureHeight)
        OutList.AddItem "     Max Texture Width   " + Str(. lMaxTextureWidth)
        If (. lDeviceRenderBitDepth And DDBD_8) Then
            OutList.AddItem "     Supports rendering to 8 bit"
        End If
        If (. lDeviceZBufferBitDepth And DDBD_8) Then
            OutList.AddItem "     Supports  8 bit z buffer"
        End If
        If (. lDevCaps And D3DDEVCAPS_TEXTURENONLOCALVIDMEM) Then
            OutList.AddItem "     Supports AGP textures"
        End If
    End With

다음 방향 : 스텝 4 : 이용 가능한 디스플레이 모드의 보고


스텝 4 : 이용 가능한 디스플레이 모드의 보고

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

디스플레이 모드란, 디스플레이 하드웨어가 프라이머리 표면으로부터 모니터에 보내는 그래픽스의 치수나 비트 깊이를 기술하는 하드웨어 설정이다. 디스플레이 모드는, 폭, 높이, 비트 깊이라고 하는 정의 특성에 의해 기술된다. 예를 들어, 대부분의 디스플레이 어댑터는, 폭 640 픽셀로 높이 480 픽셀의 그래픽스를 표시할 수 있다. 여기서, 각 픽셀은 8 비트의 데이터이다. 이 디스플레이 모드는, 640×480×8 으로 나타내진다. 디스플레이 모드의 치수가 커지거나 비트 깊이가 증가 하면, 보다 많은 디스플레이 메모리가 필요하다.

디스플레이 모드의 지원은, 디스플레이 어댑터에 따라서 다르다. 특정의 디스플레이 모드가 시스템상에서 지원 되고 있는 것을 확인하려면 ,DirectDraw7.GetDisplayModesEnum 메소드를 사용해, 유효한 디스플레이 모드를 모두 열거한다. 이 메소드는, DisplayModesEnum 로 불리는 DirectDrawEnumModes 열거 오브젝트를 생성 해, 거기에 정보를 묻는다. 그리고, 이 오브젝트를 사용해 각 디스플레이 모드의 기술을 취득한다.

튜토리얼 5 의 샘플에서는, 지원 되고 있는 디스플레이 모드 마다, DisplayModesEnum 오브젝트의 메소드를 호출한다.

Dim DisplayModesEnum As DirectDrawEnumModes
Dim ddsd2 As DDSURFACEDESC2
Dim dd As DirectDraw7
Set dd = m_dx.DirectDrawCreate(sGuid)
dd.SetCooperativeLevel Me.hWnd, DDSCL_NORMAL
Set DisplayModesEnum = dd.GetDisplayModesEnum(0, ddsd2)
OutList.AddItem " Display Modes"
For i = 1 To DisplayModesEnum.GetCount()
    DisplayModesEnum.GetItem i, ddsd2
    OutList.AddItem "  Index          " + Str(i)
    OutList.AddItem "  Width          " + Str(ddsd2.lWidth)
    OutList.AddItem "  Height         " + Str(ddsd2.lHeight)
    OutList.AddItem "  Bits Per Pixel" + Str(ddsd2.ddpfPixelFormat.lRGBBitCount)
    OutList.AddItem "  Refresh Rate   " + Str(ddsd2.lRefreshRate)
    OutList.AddItem ""
Next


DirectDraw 레퍼런스

여기에서는, Microsoft® DirectDraw® 가 제공하는 C/C++ 및 Microsoft® Visual Basic® 의 어플리케이션 프로그래밍 인터페이스 (API) 요소의 레퍼런스 정보를 기술한다. 레퍼런스 정보는 이하의 언어별로 구성된다.

  • DirectDraw C/C++ 레퍼런스
  • DirectDraw Visual Basic 레퍼런스


DirectDraw C/C++ 레퍼런스

여기에서는, DirectDraw 가 제공하는 API 요소의 레퍼런스 정보를 기술한다. 레퍼런스 정보는 이하의 카테고리로 분류된다.

  • 인터페이스
  • 함수
  • 콜백 함수
  • 구조체
  • 반환값
  • 픽셀 포맷 마스크
  • 4 문자 코드 (FOURCC)


인터페이스

여기에서는, DirectDraw 컴퍼넌트로 사용하는 인터페이스의 레퍼런스 정보를 기술한다. 이하의 인터페이스를 설명의 대상으로 한다.

  • IDDVideoPortContainer
  • IDirectDraw7
  • IDirectDrawClipper
  • IDirectDrawColorControl
  • IDirectDrawGammaControl
  • IDirectDrawPalette
  • IDirectDrawSurface7
  • IDirectDrawVideoPort


IDDVideoPortContainer

어플리케이션은,IDDVideoPortContainer 인터페이스의 메소드를 사용해, DirectDrawVideoPort 오브젝트를 생성 하거나 처리한다. 이 인터페이스에의 포인터를 취득하려면 , IID_IDDVideoPortContainer 참조 식별자를 지정해, DirectDraw 오브젝트의 IUnknown::QueryInterface 메소드를 호출한다.

IDDVideoPortContainer 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

오브젝트의 생성 | CreateVideoPort
비디오 포트 | EnumVideoPorts
 | QueryVideoPortStatus
connection | GetVideoPortConnectInfo

모든 COM 인터페이스와 같이,IDDVideoPortContaine 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDDVIDEOPORTCONTAINER 데이터형을 사용 하면,IDDVideoPortContainer 인터페이스에의 포인터를 포함한 변수를 선언할 수 있다. dvp.h 헤더 파일은, 이하의 코드로 LPDDVIDEOPORTCONTAINER 를 선언한다.

typedef struct IDDVideoPortContainer    FAR *LPDDVIDEOPORTCONTAINER;

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


IDDVideoPortContainer::CreateVideoPort

IDDVideoPortContainer::CreateVideoPort 메소드는, DirectDrawVideoPort 오브젝트를 생성 한다.

HRESULT CreateVideoPort(
  DWORD dwFlags,
  LPDDVIDEOPORTDESC lpDDVideoPortDesc,
  LPDIRECTDRAWVIDEOPORT FAR *lplpDDVideoPort,
  IUnknown FAR *pUnkOuter
);

파라미터

dwFlags
비디오 포트 컨트롤 옵션을 지정하는 플래그. 이 파라미터에는, 다음의 플래그의 1 개를 지정한다. 혹은, 컨트롤 옵션을 필요로 하지 않는 경우는 NULL 로 한다.
DDVPCREATE_VBIONLY
이 프로세스는, 단지 비디오 스트림의 VBI 부분을 제어한다.
DDVPCREATE_VIDEOONLY
이 프로세스는, 단지 비디오 스트림의 VBI 가 아닌 (비디오) 부분을 제어한다.
lpDDVideoPortDesc
생성 하는 DirectDrawVideoPort 오브젝트를 기술하는 DDVIDEOPORTDESC 구조체의 주소.
lplpDDVideoPort
호출이 성공했을 경우에, 새로운 DirectDrawVideoPort 오브젝트의 IDirectDrawVideoPort 인터페이스에의 포인터를 저장 하는 변수의 주소.
pUnkOuter
COM 처리 기능과의 장래적인 호환을 위해서(때문에) 있다. 다만, 현시점에서는, 이 파라미터를 NULL 로 설정하지 않으면 이 메소드는 에러를 돌려준다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_CURRENTLYNOTAVAIL
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOOPERATIVELEVELSET
DDERR_OUTOFCAPS
DDERR_OUTOFMEMORY

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


IDDVideoPortContainer::EnumVideoPorts

IDDVideoPortContainer::EnumVideoPorts 메소드는, 하드웨어가 공개하는 비디오 포트 가운데, 제공된 비디오 포트 기술과 호환성이 있는 모든 비디오 포트를 열거한다.

HRESULT EnumVideoPorts(
  DWORD dwFlags,
  LPDDVIDEOPORTCAPS lpDDVideoPortCaps,
  LPVOID lpContext,
  LPENUMVIDEOCALLBACK lpEnumVideoCallback
);

파라미터

dwFlags
장래적인 사용을 위해서(때문에) 확보되고 있다. 이 파라미터는 0 이 아니면 안된다.
lpDDVideoPortCaps
이용 가능한 비디오 포트와 조합하는 DDVIDEOPORTCAPS 구조체의 주소. 이 파라미터가 NULL 의 경우, 모든 비디오 포트가 열거된다.
lpContext
각각의 열거 멤버에게 건네지는, 호출측에서 정의되는 구조체의 주소.
lpEnumVideoCallback
일치하는 것이 발견될 때마다 불려 가는 EnumVideoCallback 함수의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


IDDVideoPortContainer::GetVideoPortConnectInfo

IDDVideoPortContainer::GetVideoPortConnectInfo 메소드는, 모든 비디오 포트가 지원 하는 connection 정보를 취득한다.

HRESULT GetVideoPortConnectInfo(
  DWORD dwPortId,
  LPDWORD lpNumEntries,
  LPDDVIDEOPORTCONNECT lpConnectInfo
);

파라미터

dwPortId
취득하는 connection 정보에 대한 비디오 포트의 식별자.
lpNumEntries
lpConnectInfo 의 배열로 보관 유지할 수 있는 엔트리수를 포함한 변수의 주소. 엔트리수가 connection의 합계수보다 적은 경우, 메소드는 적합할 뿐(만큼)의 엔트리를 배열에 저장 해, connection의 합계수를 나타내는 lpNumEntries 로 값을 설정해, DDERR_MOREDATA 를 돌려준다.
lpConnectInfo
지정한 비디오 포트로 지원 되는 connection 옵션을 저장 하는 DDVIDEOPORTCONNECT 구조체의 배열의 주소. 이 파라미터가 NULL 의 경우, 메소드는 비디오 포트가 지원 하는 connection의 합계수를 나타내도록(듯이) lpNumEntries 를 설정해, DD_OK 를 돌려준다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_MOREDATA

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


IDDVideoPortContainer::QueryVideoPortStatus

IDDVideoPortContainer::QueryVideoPortStatus 메소드는, DirectDrawVideoPort 오브젝트의 스테이터스를 취득한다.

HRESULT QueryVideoPortStatus(
  DWORD dwPortId,
  LPDDVIDEOPORTSTATUS lpVPStatus
);

파라미터

dwPortId
취득하는 스테이터스 정보에 대한 비디오 포트의 식별자.
lpVPStatus
지정한 비디오 포트의 스테이터스 정보를 저장 하는 DDVIDEOPORTSTATUS 구조체의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_CURRENTLYNOTAVAIL
DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


IDirectDraw7

어플리케이션은 IDirectDraw7 인터페이스의 메소드를 사용해, DirectDraw 오브젝트를 생성 해, 시스템 레벨 변수와 함께 작용한다. 여기에서는, 이 인터페이스의 메소드의 레퍼런스를 제공한다. 개념의 개요에 대해서는, 「DirectDraw 오브젝트」를 참조할것.

IDirectDraw7 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

메모리의 할당 | Compact
 | Initialize
협조 레벨 | SetCooperativeLevel
 | TestCooperativeLevel
오브젝트의 생성 | CreateClipper
 | CreatePalette
 | CreateSurface
디바이스 능력 | GetCaps
디스플레이 모드 | EnumDisplayModes
 | GetDisplayMode
 | GetMonitorFrequency
 | RestoreDisplayMode
 | SetDisplayMode
 | WaitForVerticalBlank
디스플레이 스테이터스 | GetScanLine
 | GetVerticalBlankStatus
그 외 | EvaluateMode
 | GetAvailableVidMem
 | GetDeviceIdentifier
 | GetFourCCCodes
 | StartModeTest
표면 관리 | DuplicateSurface
 | EnumSurfaces
 | FlipToGDISurface
 | GetGDISurface
 | GetSurfaceFromDC
 | RestoreAllSurfaces

모든 COM 인터페이스와 같이,IDirectDraw7 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

IDirectDraw7 인터페이스는, 이전의 버젼보다 유연하게 표면을 관리할 수 있는 메소드가 제공되는 것으로, 인터페이스의 전의 버젼에 있어서의 기능을 확장하고 있다. IDirectDraw7 인터페이스의 모든 표면 관련 메소드는,IDirectDraw2 인터페이스에 대해 대응하는 표면 관련 메소드와는 약간 다른 파라미터를 받는다. IDirectDraw2 인터페이스 메소드가 DDSURFACEDESC 구조체를 받아,IDirectDrawSurface3 인터페이스를 취득하는 위치에서는, 항상 그 대신에 IDirectDraw7 의 메소드가 DDSURFACEDESC2 구조체를 받아,IDirectDrawSurface7 인터페이스를 취득한다.

IDirectDraw7 는, 아이 오브젝트의 유효기간을 지시하는 COM 규칙에 준거해 개선되었다. 상세한 것에 대하여는, 「친오브젝트와 아이 오브젝트의 유효기간」을 참조할것.

LPDIRECTDRAW,LPDIRECTDRAW2,LPDIRECTDRAW4, 또는 LPDIRECTDRAW7 데이터형을 사용해,IDirectDraw,IDirectDraw2,IDirectDraw4, 또는 IDirectDraw7 인터페이스에의 포인터를 포함한 변수를 선언한다. ddraw.h 헤더 파일은, 이하의 코드로 이러한 데이터형을 선언한다.

typedef struct IDirectDraw     FAR *LPDIRECTDRAW;
typedef struct IDirectDraw2    FAR *LPDIRECTDRAW2;
typedef struct IDirectDraw4    FAR *LPDIRECTDRAW4;
typedef struct IDirectDraw7    FAR *LPDIRECTDRAW7;

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDraw7::Compact

IDirectDraw7::Compact 메소드는, 현시점에서는 이행되어 있지 않다.

HRESULT Compact();

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_SURFACEBUSY

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDraw7::CreateClipper

IDirectDraw7::CreateClipper 메소드는, DirectDrawClipper 오브젝트를 생성 한다.

HRESULT CreateClipper(
  DWORD dwFlags,
  LPDIRECTDRAWCLIPPER FAR *lplpDDClipper,
  IUnknown FAR *pUnkOuter
);

파라미터

dwFlags
현시점에서는 미사용이므로 0 을 설정해 둔다.
lplpDDClipper
호출이 성공했을 경우에, 유효한 IDirectDrawClipper 인터페이스 포인터를 설정하는 변수의 주소.
pUnkOuter
COM 처리 기능과의 장래적인 호환을 위해서(때문에) 있다. 다만, 현시점에서는, 이 파라미터를 NULL 로 설정하지 않으면 이 메소드는 에러를 돌려준다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOOPERATIVELEVELSET
DDERR_OUTOFMEMORY

주의

DirectDrawClipper 오브젝트는 DirectDrawSurface 에 Attach 할 수 있어IDirectDrawSurface7::Blt ,IDirectDrawSurface7::BltBatch , 및 IDirectDrawSurface7::UpdateOverlay 의 처리중에 사용할 수 있다.

특정의 DirectDraw 오브젝트에 의해 소유되지 않는 DirectDrawClipper 오브젝트를 생성 하려면 ,DirectDrawCreateClipper 함수를 사용한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::GetClipper ,IDirectDrawSurface7::SetClipper


IDirectDraw7::CreatePalette

IDirectDraw7::CreatePalette 메소드는, 이 DirectDraw 오브젝트에 대한 DirectDrawPalette 오브젝트를 생성 한다.

HRESULT CreatePalette(
  DWORD dwFlags,
  LPPALETTEENTRY lpDDColorArray,
  LPDIRECTDRAWPALETTE FAR *lplpDDPalette,
  IUnknown FAR *pUnkOuter
);

파라미터

dwFlags
이하의 플래그 가운데, 1 개 이상의 값을 취한다.
DDPCAPS_1BIT
인덱스는 1 비트이다. 컬러 테이블에는,2 개의 엔트리가 있다.
DDPCAPS_2BIT
인덱스는 2 비트이다. 컬러 테이블에는,4 개의 엔트리가 있다.
DDPCAPS_4BIT
인덱스는 4 비트이다. 컬러 테이블에는,16 의 엔트리가 있다.
DDPCAPS_8BIT
인덱스는 8 비트이다. 컬러 테이블에는,256 의 엔트리가 있다.
DDPCAPS_8BITENTRIES
인덱스가 8 비트 컬러 인덱스를 참조한다. DDPCAPS_1 BIT, DDPCAPS_2 BIT, 또는 DDPCAPS_4BIT 플래그를 사용하는 경우, 및 타겟 표면이 8 bpp 의 경우만, 이 플래그는 유효가 된다. 각각의 컬러 엔트리는 1 바이트장이며, 목적지 표면의 8 bpp 팔레트에의 인덱스이다.
DDPCAPS_ALPHA
관련지을 수 있었던 PALETTEENTRY 구조체의 peFlags 멤버가, 단일의 8 비트 알파값 (또,peRed,peGreen, 및 peBlue 멤버)으로서 판단된다. 이 플래그로 생성 되는 팔레트는, 텍스쳐, 즉, DDSCAPS_TEXTURE 능력 플래그로 생성 된 표면에게만 Attach 할 수 있다.
DDPCAPS_ALLOW256
이 팔레트는 전 256 엔트리를 정의할 수 있다.
DDPCAPS_INITIALIZE
폐지. DirectDraw 는, 항상 lpDDColorArray 로 건네받은 색배열의 색으로 이 팔레트를 초기화한다.
DDPCAPS_PRIMARYSURFACE
프라이머리 표면에 이 팔레트를 Attach 한다. 이 팔레트의 컬러 테이블을 변경 하면, DDPSETPAL_VSYNC 가 지정되어 지원 되지 않는 한, 즉석에서 디스플레이에 영향을 준다.
DDPCAPS_PRIMARYSURFACELEFT
이 팔레트는, 좌안프라이머리 표면에 Attach 된다. 이 팔레트의 컬러 테이블을 변경 하면, DDPSETPAL_VSYNC 이 지정되어 지원 되지 않는 한, 즉석에서 좌안디스플레이에 영향을 준다.
DDPCAPS_VSYNC
이 팔레트는, 모니터의 refresh rate와 동기 하도록(듯이) 수정할 수 있다.
lpDDColorArray
이 DirectDrawPalette 오브젝트를 초기화하는 2, 4, 16, 또는 256 PALETTEENTRY 구조체의 배열의 주소.
lplpDDPalette
호출이 성공했을 경우에, 유효한 IDirectDrawPalette 인터페이스 포인터로 설정되는 변수의 주소.
pUnkOuter
COM 처리 기능과의 장래적인 호환을 위해서(때문에) 있다. 다만, 현시점에서는, 이 파라미터를 NULL 로 설정하지 않으면 이 메소드는 에러를 돌려준다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOOPERATIVELEVELSET
DDERR_OUTOFMEMORY
DDERR_UNSUPPORTED

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDraw7::CreateSurface

IDirectDraw7::CreateSurface 메소드는, 이 DirectDraw 오브젝트에 대한 DirectDrawSurface 오브젝트를 생성 한다.

HRESULT CreateSurface(
  LPDDSURFACEDESC2 lpDDSurfaceDesc2,
  LPDIRECTDRAWSURFACE7 FAR *lplpDDSurface,
  IUnknown FAR *pUnkOuter
);

파라미터

lpDDSurfaceDesc2
요구하는 표면을 기술하는 DDSURFACEDESC2 구조체의 주소. 이 메소드를 호출하기 전에,DDSURFACEDESC2 구조체의 미사용 멤버를 모두 0 으로 설정한다. DDSCAPS2 구조체는,DDSURFACEDESC2 의 멤버이다.
lplpDDSurface
호출이 성공했을 경우에, 유효한 IDirectDrawSurface7 인터페이스 포인터로 설정되는 변수의 주소.
pUnkOuter
COM 처리 기능과의 장래적인 호환을 위해서(때문에) 있다. 다만, 현시점에서는, 이 파라미터를 NULL 로 설정하지 않으면 이 메소드는 에러를 돌려준다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_NOALPHAHW
DDERR_NOCOOPERATIVELEVELSET
DDERR_NODIRECTDRAWHW
DDERR_NOEMULATION
DDERR_NOEXCLUSIVEMODE
DDERR_NOFLIPHW
DDERR_NOMIPMAPHW
DDERR_NOOVERLAYHW
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_UNSUPPORTEDMODE

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDraw7::DuplicateSurface

IDirectDraw7::DuplicateSurface 메소드는, DirectDrawSurface 오브젝트를 복제한다.

HRESULT DuplicateSurface(
  LPDIRECTDRAWSURFACE7 lpDDSurface,
  LPLPDIRECTDRAWSURFACE7 FAR *lplpDupDDSurface
);

파라미터

lpDDSurface
복제하는 표면의 IDirectDrawSurface7 인터페이스의 주소.
lplpDupDDSurface
새롭게 복제하는 DirectDrawSurface 오브젝트의 IDirectDrawSurface7 인터페이스를 저장 하는 변수의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_CANTDUPLICATE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACELOST

주의

이 메소드는, 기존의 DirectDrawSurface 오브젝트로서 같은 표면 메모리를 가리키는 새로운 DirectDrawSurface 오브젝트를 생성 한다. 이 복제는, 원의 오브젝트와 완전히 똑같이 사용할 수 있다. 마지막에 참조한 오브젝트가 릴리즈 되면(자), 표면 메모리는 릴리즈 된다. 프라이머리 표면,3D 표면, 또는 암묵적으로 생성 된 표면은 복제할 수 없다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDraw7::EnumDisplayModes

IDirectDraw7::EnumDisplayModes 메소드는, 하드웨어가 DirectDraw 오브젝트를 개입시켜 공개하는 디스플레이 모드 가운데, 제공된 표면 기술과 호환성이 있는 모든 디스플레이 모드를 열거한다.

HRESULT EnumDisplayModes(
  DWORD dwFlags,
  LPDDSURFACEDESC2 lpDDSurfaceDesc2,
  LPVOID lpContext,
  LPDDENUMMODESCALLBACK2 lpEnumModesCallback
);

파라미터

dwFlags
DDEDM_REFRESHRATES
다른 refresh rate로 모드를 열거한다. IDirectDraw7::EnumDisplayModes 는, 특정의 모드를 2 회 이상 열거할 것은 없다. 이 플래그는, 모드가 독특한가 어떤가를 판단할 때에 refresh rate를 고려할지 어떨지를 지정한다.
DDEDM_STANDARDVGAMODES
320 × 200 × 8 모드 X 모드 이외에, 모드 13 을 열거한다.
lpDDSurfaceDesc2
이용 가능한 모드와 조합하는 DDSURFACEDESC2 구조체의 주소. 이 파라미터의 값이 NULL 의 경우, 모든 모드가 열거된다.
lpContext
각각의 열거 멤버에 건네주는 어플리케이션 정의 구조체의 주소.
lpEnumModesCallback
일치가 발견될 때마다 열거 프로시저가 호출하는 EnumModesCallback2 함수의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는,DDSURFACEDESC2 구조체의 dwRefreshRate 멤버를 열거한다. 즉,IDirectDraw::EnumDisplayModes 메소드에는 이 능력이 없다. IDirectDraw7::SetDisplayMode 메소드를 사용해 새로운 모드의 refresh rate을 설정하는 경우는,IDirectDraw7::EnumDisplayModes 를 사용해 dwRefreshRate 멤버를 열거해야 한다.

이 메소드는 이전의 인터페이스의 대응하는 메소드와는 달라,EnumModesCallback 함수는 아니고 파라미터로서 EnumModesCallback2 함수의 주소를 받는다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDraw7::GetDisplayMode ,IDirectDraw7::SetDisplayMode ,IDirectDraw7::RestoreDisplayMode


IDirectDraw7::EnumSurfaces

IDirectDraw7::EnumSurfaces 메소드는, 지정된 표면 기술을 채우는, 기존의 또는 가능한 표면을 모두 열거한다.

HRESULT EnumSurfaces(
  DWORD dwFlags,
  LPDDSURFACEDESC2 lpDDSD2,
  LPVOID lpContext,
  LPDDENUMSURFACESCALLBACK2 lpEnumSurfacesCallback
);

파라미터

dwFlags
1 개의 검색 타입 플래그와 1 개의 적합 플래그의 편성. 검색 타입 플래그는, 메소드에 의한 적합 플래그의 검색 방법을 결정한다. 즉,lpDDSD2 파라미터의 기술을 사용해 생성 할 수 있는 표면을 검색하거나 이미 그 기술에 적합하는 기존의 표면을 검색할 수 있다. 적합 플래그는, 메소드에 의한 표면의 열거 방법으로서 모든 표면을 열거하는, 적합하는 표면만 열거한다, 또는 lpDDSD2 파라미터의 기술에 적합하지 않는 표면만 열거할지 어떨지를 결정한다.

검색 타입 플래그

DDENUMSURFACES_CANBECREATED
생성 가능해 검색 기준에 맞는 최초의 표면을 열거한다. 이 플래그는, DDENUMSURFACES_MATCH 플래그라는 보고 병용 할 수 있다.
DDENUMSURFACES_DOESEXIST
검색 기준에 맞는 기존의 표면을 열거한다.

적합 플래그

DDENUMSURFACES_ALL
검색 기준을 채우는 표면을 모두 열거한다. 이 플래그는, DDENUMSURFACES_DOESEXIST 검색 타입 플래그라는 보고 병용 할 수 있다.
DDENUMSURFACES_MATCH
표면 기술에 적합하는 표면을 검색한다.
DDENUMSURFACES_NOMATCH
표면 기술에 적합하지 않는 표면을 검색한다.
lpDDSD2
대상의 표면을 정의하는 DDSURFACEDESC2 구조체의 주소. dwFlags 에 DDENUMSURFACES_ALL 플래그가 있는 경우, 이 파라미터는 NULL 로 한다.
lpContext
각각의 열거 멤버에 건네주는 어플리케이션 정의 구조체의 주소.
lpEnumSurfacesCallback
일치가 발견될 때마다 열거 프로시저가 호출하는 EnumSurfacesCallback2 함수의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

DDENUMSURFACES_CANBECREATED 플래그를 설정하는 경우, 이 메소드는 검색 기준에 맞는 표면을 일시적으로 생성 하려고 한다.

DDENUMSURFACES_DOESEXIST 플래그를 사용하고 있는 경우, 열거되는 표면의참조 카운트 가 인크리먼트(increment) 된다. 그 표면을 사용하지 않는 경우는, 각각의 열거의 뒤에,IDirectDrawSurface7::Release 를 사용해 표면을 릴리즈 해야 한다. 표면을 사용하는 경우는, 그 표면이 불필요하게 되었을 때에 릴리즈 한다.

이 메소드는 이전의 버젼의 인터페이스의 대응하는 메소드와는 달라,EnumSurfacesCallback 함수보다 EnumSurfacesCallback2 함수에의 포인터를 받는다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

표면의 열거


IDirectDraw7::EvaluateMode

IDirectDraw7::EvaluateMode 메소드는,IDirectDraw7::StartModeTest 를 호출한 후, 각 모드의 테스트의 클리어 또는 실패를 결정해, 테스트가 완료할 때까지 모드를 1 개씩 테스트한다.

HRESULT EvaluateMode(
  DWORD  dwFlags,
  DWORD  *pSecondsUntilTimeout
);

파라미터

dwFlags
테스트하는 모드의 스테이터스를 나타내는 플래그.
DDEM_MODEPASSED
모드가 테스트에 클리어 했다.
DDEM_MODEFAILED
모드가 테스트에 실패했다.
pSecondsUntilTimeout
현재의 모드의 클리어 또는 실패를 명시적으로 실시하지 않는 이상 자동적으로 실패라고 볼 때까지의 초수를 나타내는 값을 받는 DWORD 에의 포인터.

반환값

성공하면, DD_OK 를 돌려준다.

실패 또는 완료의 경우는, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_TESTFINISHED
DDERR_NEWMODE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

주의

IDirectDraw7::EvaluateMode 메소드를 IDirectDraw7::StartModeTest 메소드와 병용 하면, EDID 모니터 및 디스플레이 어댑터의 편성에 의해 각 스크린 해상도로 지원 할 수 있는 최대 refresh rate를 결정할 수 있다.

특히 IDirectDraw7::StartModeTest 는, 테스트 가능한 해상도세트를 생성 해, 그 세트내의 최초의 해상도에 근거해 모드를 표시하도록(듯이) DirectDraw 에 명령한다. 이 호출에 계속되는 IDirectDraw7::EvaluateMode 의 호출에서는, 각 모드의 테스트의 클리어 또는 실패를 결정해, 다음의 디스플레이 모드의 테스트하러 진행된다. 이 메소드는, 지정의 해상도를 지원 하는 최대 refresh rate로부터 순서에 테스트 가능 해상도를 1 개씩 테스트한다. 지정의 해상도의 refresh rate이 테스트에 클리어 하면, 그것보다 낮은 refresh rate의 테스트는 생략 된다.

테스트가 초기화되었을 경우, 혹은 모드가 테스트에 클리어 또는 실패했을 경우, DirectDraw 는 15 초의 타임 아웃을 다시 설정한다. 어플리케이션에서는,dwFlags 인수의 값을 0 으로 설정해 IDirectDraw7::EvaluateMode 를 호출하는 것으로, 현재의 모드가 테스트에 클리어 또는 실패할 때까지의 남은 시간을 감시할 수 있다. IDirectDraw7::EvaluateMode 가 불려 갔을 경우만, DirectDraw 는 모드를 변경 또는 테스트를 종료하므로 주의 해야 한다. 다만, 타임 아웃 기간의 경과후에 메소드가 불려 갔을 경우는, dwFlags 인수의 설정값에는 무관계하게, 현재의 모드는 실패한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDraw7::StartModeTest ,refresh rate의 열거


IDirectDraw7::FlipToGDISurface

IDirectDraw7::FlipToGDISurface 메소드는, GDI 가프라이머리 표면 에 기입하는 표면을 생성 한다.

HRESULT FlipToGDISurface();

파라미터

없음.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

주의

이 메소드는, 페이지 플립핑 어플리케이션의 마지막에 호출하면, GDI 가 기입하는 디스플레이 메모리를 표시 상태로 할 수 있다.

이 메소드는, 또, GDI 표면을 프라이머리 표면으로 해, 다이알로그 박스등의 보통의 윈도우를 풀 스크린 모드로 표시할 수 있도록(듯이) 한다. 하드웨어에는 DDCAPS2_CANRENDERWINDOWED 능력이 필요하다. 상세한 것에 대하여는, 「풀 스크린 모드에서의 윈도우의 표시」를 참조할것.

이 메소드는, 스테레오 자동 플립핑을 무효로 한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDraw7::GetGDISurface


IDirectDraw7::GetAvailableVidMem

IDirectDraw7::GetAvailableVidMem 메소드는, 이용 가능한 디스플레이 메모리의 총용량, 및 표면이 주어진 타입에 대한 디스플레이 메모리의 현재의 빈 용량을 취득한다.

HRESULT GetAvailableVidMem(
  LPDDSCAPS2 lpDDSCaps2,
  LPDWORD    lpdwTotal,
  LPDWORD    lpdwFree
);

파라미터

lpDDSCaps2
게시된 표면의 하드웨어 능력을 나타내는 DDSCAPS2 구조체의 주소.
lpdwTotal
바이트 단위로 나타내는, 이용 가능한 디스플레이 메모리의 총용량을 저장 하는 변수의 주소. 취득한 값은, 총비디오 메모리 용량을 반영한다. 이 용량에는, 프라이머리 표면용 및 디스플레이 드라이버가 확보하는 Private 캐쉬용의 비디오 메모리는 포함되지 않는다.
lpdwFree
lpDDSCaps2 의 구조체로 지정하는 능력에 적합하는 표면에 할당할 수 있는, 디스플레이 메모리의 현재의 빈 용량을 저장 하는 변수의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW

lpdwTotal 또는 lpdwFree 에 NULL 가 건네받았을 경우, 파라미터에 대한 값은 돌려주어지지 않다.

주의

다음의 C++ 의 예에서는,IDirectDraw7::GetAvailableVidMem 를 사용해, 텍스쳐 맵 표면으로 이용 가능한 디스플레이 메모리의 총용량 및 빈 용량의 양쪽 모두를 결정하는 방법을 나타낸다.

// 예를 들어, lpDD 변수는 IDirectDraw 인터페이스에의
// 유효한 포인터가 된다.
LPDIRECTDRAW7 lpDD;
DDSCAPS2      ddsCaps2;
DWORD         dwTotal;
DWORD         dwFree;
HRESULT       hr;

hr = lpDD->QueryInterface(IID_IDirectDraw7, &lpDD);
if (FAILED(hr))
    return hr;

// 구조체를 초기화한다.
ZeroMemory(&ddsCaps2, sizeof(ddsCaps2));

ddsCaps2.dwCaps = DDSCAPS_TEXTURE;
hr = lpDD->GetAvailableVidMem(&ddsCaps2, &dwTotal, &dwFree);
if (FAILED(hr))
    return hr;

표면에 DDSCAPS_VIDEOMEMORY 플래그 세트가 있는 경우, 이 메소드는, 표면이 3D 텍스쳐로서 사용할 수 있을지 어떨지에 따라서 다른 비디오 메모리 용량을 돌려준다. 표면이 3D 텍스쳐로서 사용할 수 있는 경우, GetAvailableVidMem 메소드는 AGP 시스템의 로컬 및 비로컬 비디오 메모리의 총용량을 돌려준다.

이 메소드는, 현재의 디스플레이 메모리의 순간적인 상태만을 제공한다. 디스플레이 메모리의 빈 용량은, 표면의 생성과 릴리즈에 의해 변화한다. 따라서, 빈메모리 용량의 값은 단지 근사치로서 사용해야 한다. 또, 특정의 디스플레이 어댑터 카드로 2 개가 다른 메모리 타입을 구별하지 않는 경우도 있다. 예를 들어, 어댑터는 디스플레이 메모리의 같은 부분을 사용해, Z 버퍼와 텍스쳐를 저장 하는 경우가 있다. 이 때문에, 표면이 있는 특정의 타입 (예를 들어, Z 버퍼)을 할당했을 때, 다른 타입의 표면 (예를 들어, 텍스쳐)으로 이용할 수 있는 디스플레이 메모리의 용량에 영향을 주는 경우가 있다. 따라서, 동적 사용 (텍스쳐 맵핑 등)으로 이용할 수 있는 메모리 용량을 결정하기 전에, 어플리케이션의 고정 리소스 (프런트와백 버퍼, 및 Z 버퍼등)를 최초로 할당하는 것이 최선의 방법이 된다.

이 메소드는,IDirectDraw 인터페이스에는 이행되어 있지 않다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDraw7::GetCaps

IDirectDraw7::GetCaps 메소드는, 하드웨어와 하드웨어 에뮬레이션 계층 (HEL)에 대한 디바이스 드라이버의 능력을 저장 한다.

HRESULT GetCaps(
  LPDDCAPS lpDDDriverCaps,
  LPDDCAPS lpDDHELCaps
);

파라미터

lpDDDriverCaps
디바이스 드라이버가 보고하는 하드웨어 능력을 저장 하는 DDCAPS 구조체의 주소. 디바이스 드라이버 능력을 취득하지 않는 경우는, 이 파라미터를 NULL 로 설정한다.
lpDDHELCaps
HEL 의 능력을 저장 하는 DDCAPS 구조체의 주소. HEL 의 능력을 취득하지 않는 경우는, 이 파라미터를 NULL 로 설정한다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

배제하려면 , 2 개의 파라미터의 어느쪽이든을 NULL 로 설정하는 것만으로 있다. 양쪽 모두의 파라미터에 NULL 를 설정 하면, 메소드는 실패해, DDERR_INVALIDPARAMS 를 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDraw7::GetDeviceIdentifier

IDirectDraw7::GetDeviceIdentifier 메소드는, 드라이버에 대한 정보를 취득한다. 이 메소드는, 저품질인 디바이스나 칩 세트의 동작의 회피 방법을 이행 하는 특정의 하드웨어 인스톨을 인식하기 위해서 사용할 수 있지만, 사용 시에는 주의가 필요하다.

HRESULT GetDeviceIdentifier(
  LPDDDEVICEIDENTIFIER2 lpdddi,
  DWORD dwFlags
);

파라미터

lpdddi
드라이버 정보를 받는 DDDEVICEIDENTIFIER2 구조체의 주소.
dwFlags
옵션을 지정하는 플래그. 다음의 플래그가 정의되고 있다.
DDGDI_GETHOSTIDENTIFIER
스택 된 제 2 의 3-D 어댑터와 함께 장비 되는, 시스템의 호스트 (보통은 2-D) 어댑터에 대한 정보를 돌려주기 위해서(때문에) 메소드를 일으킨다. 이러한 어댑터는, 어플리케이션에는 호스트 어댑터의 일부인것 같이 나타나지만, 보통은 다른 카드로 배치되고 있다. dwFlags 파라미터가 0 의 경우, DirectDraw 오브젝트의 품질을 가장 정확하게 반영 하면 말하는 이유로부터, 스택 되고 있는 제 2 어댑터의 정보가 돌려주어진다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면,DDERR INVALIDPARAMS 을 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDraw7::GetDisplayMode

IDirectDraw7::GetDisplayMode 메소드는, 현재의 디스플레이 모드를 취득한다.

HRESULT GetDisplayMode(
  LPDDSURFACEDESC2 lpDDSurfaceDesc2
);

파라미터

lpDDSurfaceDesc2
표면의 기술을 저장 하는 DDSURFACEDESC2 구조체의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTEDMODE

주의

어플리케이션이 이 메소드로 돌려주어진 정보를 미리 보존해, 클린 업때의 디스플레이 모드의 restore로서 이용하는 것은 바람직하지 않다. 어플리케이션에서는,IDirectDraw7::RestoreDisplayMode 메소드를 사용해, 클린 업 시에 모드를 restore 할 필요가 있다. 이것에 의해, 멀티 프로세스 환경에서 발생하는 일이 있는 경합을 회피할 수 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDraw7::SetDisplayMode ,IDirectDraw7::RestoreDisplayMode ,IDirectDraw7::EnumDisplayModes


IDirectDraw7::GetFourCCCodes

IDirectDraw7::GetFourCCCodes 메소드는, DirectDraw 오브젝트가 지원 하는 FOURCC 코드를 취득한다. 또, 이 메소드는, 지원 되는 코드수도 취득한다.

HRESULT GetFourCCCodes(
  LPDWORD lpNumCodes,
  LPDWORD lpCodes
);

파라미터

lpNumCodes
lpCodes 에 의해 나타나는 배열을 보관 유지할 수 있는 엔트리수를 포함한 변수의 주소. 엔트리수가 너무 적어 모든 코드를 적응할 수 없는 경우,lpNumCodes 에는 필요한 수가 설정되어lpCodes 에 의해 나타나는 배열에는 적합하는 모든 코드가 저장 된다.
lpCodes
DirectDraw 오브젝트가 지원 하는 FOURCC 코드를 저장 하는 변수의 배열의 주소. NULL 를 지정했을 경우,lpNumCodes 는 지원 되는 FOURCC 코드의 수로 설정되어 메소드가 돌아간다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDraw7::GetGDISurface

IDirectDraw7::GetGDISurface 메소드는, GDI 가프라이머리 표면으로서 처리하는 표면 메모리를 현재 가리키는 DirectDrawSurface 오브젝트를 취득한다.

HRESULT GetGDISurface(
  LPDIRECTDRAWSURFACE7 FAR *lplpGDIDDSSurface
);

파라미터

lplpGDIDDSSurface
GDI 의프라이머리 표면 메모리를 현재 제어하고 있는, 표면의 IDirectDrawSurface7 인터페이스에의 포인터를 저장 하는 변수의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDraw7::FlipToGDISurface


IDirectDraw7::GetMonitorFrequency

IDirectDraw7::GetMonitorFrequency 메소드는, DirectDraw 오브젝트가 동작하는 모니터의 주파수를 취득한다.

HRESULT GetMonitorFrequency(
  LPDWORD lpdwFrequency
);

파라미터

lpdwFrequency
헤르쯔 단위로 모니터 주파수를 저장 하는 변수의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDraw7::GetScanLine

IDirectDraw7::GetScanLine 메소드는, 모니터상에서 현재 드로잉(Drawing) 되고 있는 주사선을 취득한다.

HRESULT GetScanLine(
  LPDWORD lpdwScanLine
);

파라미터

lpdwScanLine
디스플레이가 현재 드로잉(Drawing) 하고 있는 주사선을 포함한 변수의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DDERR_VERTICALBLANKINPROGRESS

주의

주사선은 제로 베이스의 정수로서 보고된다. 돌려주어지는 주사선의 값은 0 으로부터 n 까지의 값이다. 주사선 0 은 스크린 위에의 최초의 가시 주사선, 주사선 n 는 마지막 가시 주사선이다. 또, 수직귀선소거 간격에 생기는 임의의 주사선도 있다. 따라서, 어플리케이션이 640 × 480 으로 실행되어 수직귀선소거 간격에 12 의 주사선이 있는 경우, 이 메소드는 0 에서 491 의 범위의 값을 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDraw7::GetVerticalBlankStatus ,IDirectDraw7::WaitForVerticalBlank


IDirectDraw7::GetSurfaceFromDC

IDirectDraw7::GetSurfaceFromDC 메소드는, 표면의 GDI 디바이스 콘텍스트 핸들에 근거해, 그 표면의 IDirectDrawSurface7 인터페이스를 취득한다.

HRESULT GetSurfaceFromDC(
  HDC hdc,
  LPDIRECTDRAWSURFACE7 * lpDDS
);

파라미터

hdc
디스플레이 디바이스 콘텍스트의 핸들.
lpDDS
호출이 성공했을 경우에, 유효한 IDirectDrawSurface7 인터페이스 포인터를 저장 하는 변수의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_GENERIC
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_NOTFOUND

주의

이 메소드는, DirectDraw 오브젝트에 이미 관련지을 수 있고 있는 표면을 식별하는, 디바이스 콘텍스트 핸들 에 대해서만 성공한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

표면 문맥과 디바이스 콘텍스트


IDirectDraw7::GetVerticalBlankStatus

IDirectDraw7::GetVerticalBlankStatus 메소드는, 수직귀선소거의 스테이터스를 취득한다.

HRESULT GetVerticalBlankStatus(
  LPBOOL lpbIsInVB
);

파라미터

lpbIsInVB
수직귀선소거의 스테이터스를 저장 하는 변수의 주소. 수직귀선소거가 발생하는 경우에 이 파라미터는 TRUE 가 되어, 그렇지 않은 경우는 FALSE 가 된다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

수직귀선소거와 동기 하려면 ,IDirectDraw7::WaitForVerticalBlank 메소드를 사용한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDraw7::GetScanLine ,IDirectDraw7::WaitForVerticalBlank


IDirectDraw7::Initialize

IDirectDraw7::Initialize 메소드는,CoCreateInstance COM 함수를 사용해 생성 된 DirectDraw 오브젝트를 초기화한다.

HRESULT Initialize(
  GUID FAR *lpGUID
);

파라미터

lpGUID
인터페이스 식별자로서 사용되는 글로벌 유니크 식별자 (GUID)의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_ALREADYINITIALIZED
DDERR_DIRECTDRAWALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW
DDERR_NODIRECTDRAWSUPPORT
DDERR_OUTOFMEMORY

이 메소드는, 컴퍼넌트 오브젝트 모델 (COM) 프로토콜 준거로 제공된다. DirectDraw 오브젝트를 생성 하기 위해서 DirectDrawCreate 함수를 사용했을 경우, 이 메소드는 DDERR_ALREADYINITIALIZED 을 돌려준다. DirectDraw 오브젝트를 생성 하기 위해서 CoCreateInstance 를 사용할때에 IDirectDraw7::Initialize 를 호출하지 않은 경우, 다음에 불려 가는 메소드는 DDERR_NOTINITIALIZED 를 돌려준다.

주의

CoCreateInstance 와 함께 IDirectDraw7::Initialize 를 사용하는 것에 대하여의 상세 정보는, 「CoCreateInstance 를 이용한 DirectDraw 오브젝트의 생성」을 참조할것.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDraw7::RestoreAllSurfaces

IDirectDraw7::RestoreAllSurfaces 메소드는, DirectDraw 오브젝트에 대해서 생성 된 모든 표면을, 그 생성순서에 restore 한다.

HRESULT RestoreAllSurfaces();

파라미터

없음.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는 편리하다. 이 메소드는, 이 DirectDraw 오브젝트에 의해 생성 된 표면 마다 효율 좋게 IDirectDrawSurface7::Restore 을 호출한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::Restore ,표면의 소실과 restore


IDirectDraw7::RestoreDisplayMode

IDirectDraw7::RestoreDisplayMode 메소드는,프라이머리 표면의 디스플레이 디바이스 하드웨어의 모드를,IDirectDraw7::SetDisplayMode 메소드가 불려 가기 전 상태에 리셋 한다. 이 메소드를 사용하려면 , 배타 레벨의 액세스가 필요하게 된다.

HRESULT RestoreDisplayMode();

파라미터

없음.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_LOCKEDSURFACES
DDERR_NOEXCLUSIVEMODE

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDraw7::SetDisplayMode ,IDirectDraw7::EnumDisplayModes ,IDirectDraw7::SetCooperativeLevel


IDirectDraw7::SetCooperativeLevel

IDirectDraw7::SetCooperativeLevel 메소드는, 어플리케이션의 최상정도 동작을 결정한다.

HRESULT SetCooperativeLevel(
  HWND hWnd,
  DWORD dwFlags
);

파라미터

hWnd
어플리케이션이 사용하는 윈도우 핸들. 호출하는 어플리케이션의 최상정도 윈도우 핸들로 설정한다 (최상정도 윈도우가 생성 한 자식 윈도우에 대한 핸들은 아니다). dwFlags 파라미터에 DDSCL_NORMAL 플래그를 지정하는 경우, 이 파라미터는 NULL 가 된다.
dwFlags
이하의 플래그 가운데, 1 개 이상의 값을 취한다.
DDSCL_ALLOWMODEX
모드 X 디스플레이 모드의 이용을 허가한다. DDSCL_EXCLUSIVE 와 DDSCL_FULLSCREEN 플래그가 존재하는 경우만, 이 플래그를 사용할 수 있다.
DDSCL_ALLOWREBOOT
배타 (풀 스크린) 모드시에, CTRL + ALT + DEL 의 기능을 허가한다.
DDSCL_CREATEDEVICEWINDOW
이 플래그는, Microsoft® Windows 98 및 Windows 2000 에서만 지원 된다. DirectDraw 가, 이 DirectDraw 오브젝트의 디폴트의 디바이스 윈도우 를 생성 및 관리하는 것을 나타낸다. 상세한 것에 대하여는, 「포커스 윈도우와 디바이스 윈도우」를 참조할것.
DDSCL_EXCLUSIVE
배타 레벨을 요구한다. 이 플래그는, DDSCL_FULLSCREEN 플래그와 함께 사용해야 한다.
DDSCL_FPUPRESERVE
호출측 어플리케이션으로 FPU 상태를 감시해, 어플리케이션에서의 관리의 아래 Direct3D 에 의한 FPU 상태를 변경하지 않는다. 이 모드에서는, Direct3D 는, FPU 상태를 변경할 필요가 있을 때마다 FPU 상태를 보존 및 복원한다. 상세한 것에 대하여는, 「DirectDraw 협조 레벨과 FPU 정밀도」를 참조할것.
DDSCL_FPUSETUP
호출측 어플리케이션에서는, FPU 를 Direct3D 퍼포먼스에 최적인 상태 (단정밀도 및 예외 무효)로 설정하므로, Direct3D 로 FPU 를 명시적으로 매회 설정할 필요는 없다. 이것은 디폴트 상태이다. 상세한 것에 대하여는, 「DirectDraw 협조 레벨과 FPU 정밀도」를 참조할것.
DDSCL_FULLSCREEN
배타 모드를 소유하는 측에프라이머리 표면 전체에 대할 책임이 있다. GDI 는 무시할 수 있다. 이 플래그는, DDSCL_EXCLUSIVE 플래그와 함께 사용해야 한다.
DDSCL_MULTITHREADED
multi-thread의 확실한 DirectDraw 동작을 요구한다. 이것에 의해, Direct3D 가 빈번하게 글로벌 위험역을 취득하게 된다.
DDSCL_NORMAL
어플리케이션은 보통의 Microsoft® Windows® 어플리케이션으로서 기능한다. 이 플래그는, DDSCL_ALLOWMODEX, DDSCL_EXCLUSIVE, 또는 DDSCL_FULLSCREEN 플래그와 함께 사용할 수 없다.
DDSCL_NOWINDOWCHANGES
DirectDraw 는, 액티브시에 어플리케이션 윈도우를 최소화 또는 원의 사이즈에 되돌릴 수가 없다.
DDSCL_SETDEVICEWINDOW
이 플래그는, Windows 98 및 Windows 2000 에서만 지원 된다. hWnd 파라미터가, 이 DirectDraw 오브젝트에 있어서의디바이스 윈도우의 윈도우 핸들인 것을 나타낸다. 이 플래그는, DDSCL_SETFOCUSWINDOW 플래그와 함께 사용할 수 없다.
DDSCL_SETFOCUSWINDOW
이 플래그는, Windows 98 및 Windows 2000 에서만 지원 된다. hWnd 파라미터가, 이 DirectDraw 오브젝트에 있어서의포커스 윈도우의 윈도우 핸들인 것을 나타낸다. 이 플래그는, DDSCL_SETDEVICEWINDOW 플래그와 함께 사용할 수 없다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_EXCLUSIVEMODEALREADYSET
DDERR_HWNDALREADYSET
DDERR_HWNDSUBCLASSED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

주의

이 메소드는, 어플리케이션 윈도우를 생성 한 같은 thread로 불려 가지 않으면 안 된다.

어플리케이션에서는, DDSCL_EXCLUSIVE 또는 DDSCL_NORMAL 플래그의 어느쪽이든을 설정할 필요가 있다.

다른 어플리케이션에 대해서, 대폭적인 퍼포먼스 변화를 일으킬 가능성이 있는 함수를 호출하려면 , DDSCL_EXCLUSIVE 플래그를 설정하지 않으면 안 된다. 상세한 것에 대하여는, 「협조 레벨」을 참조할것.

이 메소드 및 IDirectDraw7::SetDisplayMode 메소드간의 상호작용은,IDirectDraw 에서의 것과는 다르다. 상세한 것에 대하여는, 「디스플레이 모드의 restore」를 참조할것.

Microsoft Foundation Classes (MFC)를 사용하는 경우, 이 메소드에게 건네지는 윈도우 핸들은, 파생한 자식 윈도우는 아니고 어플리케이션의 최상정도 윈도우를 식별하는 것이 아니면 안된다. MFC 어플리케이션의 최상정도 윈도우 핸들을 취득하려면 , 다음에 나타내는 코드를 사용한다.

    HWND hwndTop = AfxGetMainWnd() ->GetSafeHwnd();

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDraw7::SetDisplayMode ,IDirectDraw7::Compact ,IDirectDraw7::EnumDisplayModes ,모드 X 모드와 모드 13 디스플레이 모드,포커스 윈도우와 디바이스 윈도우


IDirectDraw7::SetDisplayMode

IDirectDraw7::SetDisplayMode 메소드는, 디스플레이 디바이스 하드웨어의 모드를 설정한다.

HRESULT SetDisplayMode(
  DWORD dwWidth,
  DWORD dwHeight,
  DWORD dwBPP,
  DWORD dwRefreshRate,
  DWORD dwFlags
);

파라미터

dwWidth,dwHeight
새로운 모드의 폭과 높이.
dwBPP
새로운 모드의 비트/픽셀 (bpp).
dwRefreshRate
새로운 모드의 refresh rate. 이 값을 0 으로 설정 하면, 드라이버에 대한 디폴트 refresh rate를 요구한다.
dwFlags
추가 옵션을 기술하는 플래그. 현시점에서 유일한 유효한 플래그는 DDSDM_STANDARDVGAMODE 이며, 메소드로 모드 X 의 320 × 200 × 8 모드는 아니고, 모드 13 을 설정할 수 있다. 다른 해상도, 비트 깊이, 또는 모드 X 모드로 설정하는 경우는, 이 플래그를 사용하지 않고 파라미터를 0 으로 설정한다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_GENERIC
DDERR_INVALIDMODE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_LOCKEDSURFACES
DDERR_NOEXCLUSIVEMODE
DDERR_SURFACEBUSY
DDERR_UNSUPPORTED
DDERR_UNSUPPORTEDMODE
DDERR_WASSTILLDRAWING

주의

이 메소드는, 어플리케이션 윈도우를 생성 한 같은 thread로 불려 가지 않으면 안 된다.

다른 어플리케이션으로 디스플레이 모드를 변경 하면,프라이머리 표면이 소실, 메소드는 새로운 디스플레이 모드에 적합하는 프라이머리 표면이 생성 다시 할 때까지 DDERR_SURFACELOST 를 돌려준다.

IDirectDraw 인터페이스의 일부로서 이 메소드는 dwRefreshRate 및 dwFlags 파라미터를 포함하지 않았었다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDraw7::RestoreDisplayMode ,IDirectDraw7::GetDisplayMode ,IDirectDraw7::EnumDisplayModes ,IDirectDraw7::SetCooperativeLevel ,디스플레이 모드의 설정,디스플레이 모드의 restore


IDirectDraw7::StartModeTest

IDirectDraw7::StartModeTest 메소드는, 테스트를 시작 해, 현재의 디스플레이 어댑터 및 모니터의 조합해에 대한 refresh rate 정보로 시스템 레지스트리를 갱신한다. 보통, 이 메소드를 호출한 후,IDirectDraw7::EvaluateMode 를 호출해, 테스트로 표시된 모드의 클리어 또는 실패를 결정한다.

HRESULT StartModeTest(
  LPSIZE   lpModesToTest,
  DWORD    dwNumEntries,
  DWORD    dwFlags
);

파라미터

lpModesToTest
테스트하는 모드를 스크린 해상도의 점으로부터 기술하는 SIZE 요소의 배열에의 포인터.
dwNumEntries
lpModesToTest. 하지만 포인트 하는 배열의 요소수.
dwFlags
현시점에서 유효한 플래그의 값은, DDSMT_ISTESTREQUIRED 뿐인다. 이 플래그를 지정했을 경우,IDirectDraw7::StartModeTest 는 테스트를 시작 하지 않는다. 그 대신해,lpModesToTest 및 dwNumEntries 에 의해 식별되는 해상도의 테스트가 가능한가 어떤가 또는 테스트가 필요한가 어떤가를 나타내는 값을 돌려준다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_CURRENTLYNOTAVAIL
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_NOTFOUND
DDERR_TESTFINISHED

DDSMT_ISTESTREQUIRED 플래그로 메소드를 호출했을 경우, 이하의 값의 어느쪽이든을 돌려준다.

DDERR_NEWMODE
DDERR_NODRIVERSUPPORT
DDERR_NOMONITORINFORMATION
DDERR_TESTFINISHED

주의

IDirectDraw7::StartModeTest 메소드를 IDirectDraw7::EvaluateMode 와 병용 하면, EDID 모니터 및 디스플레이 어댑터의 편성에 의해 각 스크린 해상도로 지원 할 수 있는 최대 refresh rate를 결정할 수 있다. 테스트의 결과는, 시스템 레지스트리에 저장 되어IDirectDraw7::EnumDisplayMode 를 DDEDM_REFRESHRATES 플래그 세트로 호출했을 때의 처리에 영향을 준다.

특히 IDirectDraw7::StartModeTest 는, 테스트 가능한 해상도세트를 생성 해, 그 세트내의 최초의 해상도에 근거해 모드를 표시하도록(듯이) DirectDraw 에 명령한다. 이 호출에 계속되는 IDirectDraw7::EvaluateMode 의 호출에서는, 각 모드의 테스트의 클리어 또는 실패를 결정해, 다음의 디스플레이 모드의 테스트하러 진행된다.

이 메소드는, EDID 데이터를 포함한 모니터 에 대해서만 성공한다. 모니터가 EDID 준거가 아닌 경우, 메소드는 모드의 테스트를 실시하지 않고 DDERR_TESTFINISHED 를 돌려준다. EDID 테이블에 60 Hz 보다 높은 값이 없는 경우, 모드의 테스트는 행해지지 않는다. 100 Hz 보다 높은 refresh rate의 테스트를 하는 것은, EDID 테이블에 85 Hz 보다 높은 값이 있는 경우뿐이다.

(NULL, 0, 0)의 인수 리스트로 메소드를 호출하면, 기존의 refresh rate 정보가 레지스트리로부터 소거된다.

테스트는,lpModesToTest 및 dwNumEntries 파라미터로 기술되는 배열의 해상도에 있어서의 표시만을 보증하는 것은 아니다. 예를 들어, 640 × 480 해상도를 사용해, 320 × 200 해상도에서의 최대 표시 refresh rate를 취득할 수 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDraw7::EvaluateMode ,refresh rate의 열거


IDirectDraw7::TestCooperativeLevel

IDirectDraw7::TestCooperativeLevel 메소드는, 윈도우 또는 풀 스크린 어플리케이션에 대한 DirectDraw 디바이스의 현재의 협조 레벨 스테이터스를 보고한다.

HRESULT TestCooperativeLevel(void);

파라미터

없음.

반환값

성공하면, DD_OK 를 돌려준다. 이 반환값은, 호출측 어플리케이션을 속행할 수 있는 것을 나타낸다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다. ( 「주의」참조).

DDERR_INVALIDOBJECT
DDERR_EXCLUSIVEMODEALREADYSET
DDERR_NOEXCLUSIVEMODE
DDERR_WRONGMODE

주의

이 메소드는, 표면의 restore나 DirectDraw 오브젝트의 재생성을 실시하는 통지로서 WM_ACTIVATEAPP 및 WM_DISPLAYCHANGE 시스템 메세지를 사용하는 어플리케이션에서는 특히 편리하다. DD_OK 반환값은, 항상 어플리케이션을 속행할 수 있는 것을 나타내지만, 에러 코드의 해석은 어플리케이션으로 사용하는 협조 레벨에 따라서 다르다. 상세한 것에 대하여는, 「협조 레벨의 테스트」를 참조할것.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDraw7::WaitForVerticalBlank

IDirectDraw7::WaitForVerticalBlan 메소드는, 어플리케이션이 수직귀선소거 간격과 함께 동기 하는 방법을 제공한다.

HRESULT WaitForVerticalBlank(
  DWORD dwFlags,
  HANDLE hEvent
);

파라미터

dwFlags
수직귀선소거에 대해서의 대기 시간을 결정한다. 이하의 플래그 가운데, 1 개의 값을 취한다.
DDWAITVB_BLOCKBEGIN
수직귀선소거 간격이 발생했을 때에 돌려준다.
DDWAITVB_BLOCKBEGINEVENT
수직귀선소거가 발생 하면나무의 이벤트 방아쇠. 이 값은, 현시점에서는 지원되어 있지 않다.
DDWAITVB_BLOCKEND
수직귀선소거 간격이 종료해 표시할 경우에 돌려준다.
hEvent
수직귀선소거가 발생했을 때에 방아쇠가 되는 이벤트의 핸들. 이 파라미터는, 현시점에서는 사용할 수 없다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDraw7::GetVerticalBlankStatus ,IDirectDraw7::GetScanLine


IDirectDrawClipper

어플리케이션에서는,IDirectDrawClipper 인터페이스의 메소드를 사용해클립 리스트를 관리한다. 여기에서는, 이 인터페이스의 메소드의 레퍼런스를 제공한다. 개념의 개요에 대해서는, 「클립퍼」를 참조할것.

IDirectDrawClipper 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

메모리의 할당 | Initialize
클립 리스트 | GetClipList
 | IsClipListChanged
 | SetClipList
 | SetHWnd
핸들 | GetHWnd

모든 COM 인터페이스와 같이,IDirectDrawClipper 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTDRAWCLIPPER 데이터형을 사용 하면,IDirectDrawClipper 인터페이스에의 포인터를 포함한 변수를 선언할 수 있다. ddraw.h 헤더 파일은, 이하의 코드로 이러한 데이터형을 선언한다.

typedef struct IDirectDrawClipper    FAR *LPDIRECTDRAWCLIPPER;

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


IDirectDrawClipper::GetClipList

IDirectDrawClipper::GetClipList 메소드는, DirectDrawClipper 오브젝트에 관련지을 수 있었던클립 리스트의 카피를 취득한다. 클립 리스트를 클립 하는 직사각형을 건네주는 것으로, 클립 리스트의 서브 세트를 선택할 수 있다.

HRESULT GetClipList(
  LPRECT lpRect,
  LPRGNDATA lpClipList,
  LPDWORD lpdwSize
);

파라미터

lpRect
클립 리스트를 클립 하기 위해서 사용하는 직사각형의 주소. 이 파라미터를 NULL 로 설정 하면, 클립 리스트 전체를 취득할 수 있다.
lpClipList
클립 리스트의 카피 결과를 받는 RGNDATA 구조체의 주소. 이 파라미터를 NULL 로 설정 하면, 메소드는 클립 리스트 전체를 보관 유지하기 위해서 필요한 바이트수를 lpdwSize 로 가리키는 변수에 저장 한다.
lpdwSize
클립 리스트의 사이즈를 받는 변수의 주소. 클립 리스트를 취득하는 경우, 이 파라미터는 lpClipList 가 가리키는 버퍼의 사이즈가 된다. LpClipList 가 NULL 의 경우,lpdwSize 로 가리키는 변수는 필요한 버퍼의 사이즈를 바이트 단위로 취득한다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_GENERIC
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCLIPLIST
DDERR_REGIONTOOSMALL

주의

이 메소드로 사용되는 RGNDATA 구조체는, 다음에 나타내는 구문이 된다.

typedef struct _RGNDATA {
    RGNDATAHEADER rdh;
    char          Buffer[1];
} RGNDATA;

RGNDATA 구조체의 rdh 멤버는, 다음의 구문의 RGNDATAHEADER 구조체이다.

typedef struct _RGNDATAHEADER {
    DWORD dwSize;
    DWORD iType;
    DWORD nCount;
    DWORD nRgnSize;
    RECT  rcBound;
} RGNDATAHEADER;

이러한 구조체의 상세한 것에 대하여는, 플랫폼 SDK 를 참조할것.

동작환경

Windows NT/2000 : Windows NT Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.

참조

IDirectDrawClipper::SetClipList


IDirectDrawClipper::GetHWnd

IDirectDrawClipper::GetHWnd 메소드는,IDirectDrawClipper::SetHWnd 메소드에 의해 이 DirectDrawClipper 오브젝트에 이전 관련지을 수 있었던 윈도우 핸들을 취득한다.

HRESULT GetHWnd(
  HWND FAR *lphWnd
);

파라미터

lphWnd
IDirectDrawClipper::SetHWnd 메소드에 의해, 이 DirectDrawClipper 오브젝트에 이전 관련지을 수 있었던 윈도우 핸들의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 :ddraw.lib 를 사용.

참조

IDirectDrawClipper::SetHWnd


IDirectDrawClipper::Initialize

IDirectDrawClipper::Initialize 메소드는,CoCreateInstance COM 함수를 사용해 생성 한 DirectDrawClipper 오브젝트를 초기화한다.

HRESULT Initialize(
  LPDIRECTDRAW lpDD,
  DWORD dwFlags
);

파라미터

lpDD
DirectDraw 오브젝트를 나타내는 DirectDraw 구조체의 주소. 파라미터를 NULL 로 설정 하면, 독립한 DirectDrawClipper 오브젝트가 생성 된다 (DirectDrawCreateClipper 함수를 사용하는 경우와 같이).
dwFlags
현시점에서는 미사용이므로 0 을 설정해 둔다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_ALREADYINITIALIZED
DDERR_INVALIDPARAMS

이 메소드는, 컴퍼넌트 오브젝트 모델 (COM) 프로토콜 준거로 제공된다. DirectDrawCreateClipper 또는 IDirectDraw7::CreateClipper 메소드를 DirectDrawClipper 오브젝트의 생성에 사용했을 경우, 이 메소드는 DDERR_ALREADYINITIALIZED 를 돌려준다.

주의

CoCreateInstance 와 함께 IDirectDrawClipper::Initialize 를 사용하는 상세한 것에 대하여는, 「CoCreateInstance 를 이용한 DirectDrawClipper 오브젝트의 생성」을 참조할것.

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.

참조

IUnknown::AddRef ,IUnknown::QueryInterface ,IUnknown::Release ,IDirectDraw7::CreateClipper


IDirectDrawClipper::IsClipListChanged

IDirectDrawClipper::IsClipListChanged 메소드는, 윈도우 핸들이 DirectDrawClipper 오브젝트에 관련지을 수 있고 있는 경우,클립 리스트의 스테이터스를 모니터 한다.

HRESULT IsClipListChanged(
  BOOL FAR *lpbChanged
);

파라미터

lpbChanged
클립 리스트가 변경되었을 경우,TRUE 로 설정하는 변수의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


IDirectDrawClipper::SetClipList

IDirectDrawClipper::SetClipList 메소드는, DirectDrawClipper 의 친오브젝트를 Attach 하는 표면의 IDirectDrawSurface7::Blt ,IDirectDrawSurface7::BltBatch , 및 IDirectDrawSurface7::UpdateOverlay 메소드로 사용하는클립 리스트를 설정 또는 삭제한다.

HRESULT SetClipList(
  LPRGNDATA lpClipList,
  DWORD dwFlags
);

파라미터

lpClipList
유효한 RGNDATA 구조체의 주소, 또는 NULL. DirectDrawClipper 오브젝트에 관련지을 수 있었던클립 리스트가 존재해, 이 파라미터의 값이 NULL 의 경우, 클립 리스트를 삭제한다.
dwFlags
현시점에서는 미사용이므로 0 을 설정해 둔다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_CLIPPERISUSINGHWND
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

주의

윈도우 핸들이 이미 DirectDrawClipper 오브젝트에 관련지을 수 있고 있는 경우, 클립 리스트는 설정되지 않는다. BltFast 메소드에서는 클립 할 수 없다.

이 메소드로 사용되는 RGNDATA 구조체는, 다음에 나타내는 구문이 된다.

typedef struct _RGNDATA {
    RGNDATAHEADER rdh;
    char          Buffer[1];
} RGNDATA;

RGNDATA 구조체의 rdh 멤버는, 다음의 구문의 RGNDATAHEADER 구조체이다.

typedef struct _RGNDATAHEADER {
    DWORD dwSize;
    DWORD iType;
    DWORD nCount;
    DWORD nRgnSize;
    RECT  rcBound;
} RGNDATAHEADER;

이러한 구조체의 상세한 것에 대하여는, 플랫폼 SDK 를 참조할것.

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.

참조

IDirectDrawClipper::GetClipList ,IDirectDrawSurface7::Blt ,IDirectDrawSurface7::BltFast ,IDirectDrawSurface7::BltBatch ,IDirectDrawSurface7::UpdateOverlay


IDirectDrawClipper::SetHWnd

IDirectDrawClipper::SetHWnd 메소드는, 클리핑 정보를 취득하기 위해서 사용하는 클립퍼 오브젝트의 윈도우 핸들을 설정한다.

HRESULT SetHWnd(
  DWORD dwFlags,
  HWND hWnd
);

파라미터

dwFlags
현시점에서는 미사용이므로 0 을 설정해 둔다.
hWnd
클리핑 정보를 취득하는 윈도우 핸들.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.

참조

IDirectDrawClipper::GetHWnd


IDirectDrawColorControl

IDirectDrawColorControl 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다. 이하의 메소드가 있다.

컬러 컨트롤 | GetColorControls
 | SetColorControls

모든 COM 인터페이스와 같이,IDirectDrawColorControl 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTDRAWCOLORCONTROL 데이터형을 사용 하면,IDirectDrawColorControl 인터페이스에의 포인터를 포함한 변수를 선언할 수 있다. ddraw.h 헤더 파일은, 이하의 코드로 이러한 데이터형을 선언한다.

typedef struct IDirectDrawColorControl    FAR *LPDIRECTDRAWCOLORCONTROL;

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


IDirectDrawColorControl::GetColorControls

IDirectDrawColorControl::GetColorControls 메소드는, 지정한 오버레이나프라이머리 표면에 관련지을 수 있었던 현재의 컬러 컨트롤 설정을 돌려준다. DDCOLORCONTROL 구조체의 dwFlags 멤버는, 지원 되는 컬러 컨트롤 옵션을 나타낸다.

HRESULT GetColorControls(
  LPDDCOLORCONTROL lpColorControl
);

파라미터

lpColorControl
지정된 표면의 현재의 컨트롤 설정을 받는 DDCOLORCONTROL 구조체의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.

참조

IDirectDrawColorControl::SetColorControls ,컬러 컨트롤의 사용,감마 컨트롤과 컬러 컨트롤


IDirectDrawColorControl::SetColorControls

IDirectDrawColorControl::SetColorControls 메소드는, 지정한 오버레이 또는프라이머리 표면에 관련지을 수 있었던 컬러 컨트롤을 설정한다.

HRESULT SetColorControls(
  LPDDCOLORCONTROL lpColorControl
);

파라미터

lpColorControl
지정한 표면에 적용하는 새로운 값을 포함한 DDCOLORCONTROL 구조체의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.

참조

IDirectDrawColorControl::GetColorControls ,컬러 컨트롤의 사용,감마 컨트롤과 컬러 컨트롤


IDirectDrawGammaControl

어플리케이션은 IDirectDrawGammaControl 인터페이스의 메소드를 사용해, 프라이머리 표면의 적, 초록, 및 파랑 감마 램프 레벨을 조정한다. 여기에서는, 이 인터페이스의 메소드의 레퍼런스를 제공한다. 이 인터페이스는, DirectDrawSurface 오브젝트에 의해 지원 된다. 즉, IID_IDirectDrawGammaControl 참조 식별자를 지정해 DirectDrawSurface 오브젝트의 IUnknown::QueryInterface 메소드를 호출하는 것으로, 이 인터페이스에의 포인터를 취득할 수 있다.

개념의 개요에 대해서는, 「감마 컨트롤과 컬러 컨트롤」을 참조할것.

인터페이스에는 이하의 메소드가 있다.

감마 램프 | GetGammaRamp
 | SetGammaRamp

모든 COM 인터페이스와 같이,IDirectDrawGammaControl 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTDRAWGAMMACONTROL 데이터형을 사용 하면,IDirectDrawGammaControl 인터페이스에의 포인터를 포함한 변수를 선언할 수 있다. ddraw.h 헤더 파일은, 이하의 코드로 이러한 데이터형을 선언한다.

typedef struct IDirectDrawGammaControl    FAR *LPDIRECTDRAWGAMMACONTROL;

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


IDirectDrawGammaControl::GetGammaRamp

IDirectDrawGammaControl::GetGammaRamp 메소드는, 프라이머리 표면에 대한 적, 초록, 및 파랑 감마 램프를 취득한다.

HRESULT GetGammaRamp(
  DWORD  dwFlags,
  LPGAMMARAMP lpRampData
);

파라미터

dwFlags
현시점에서는 미사용이므로 0 을 설정해 둔다.
lpRampData
현재의 적, 초록, 및 파랑 감마 램프를 저장 하는 DDGAMMARAMP 구조체의 주소. 각각의 배열은, frame buffer의 색의 값을 디지털 아날로그 컨버터 (DAC)에 건네주는 색의 값에 맵 한다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.

참조

IDirectDrawGammaControl::SetGammaRamp ,감마 컨트롤과 컬러 컨트롤


IDirectDrawGammaControl::SetGammaRamp

IDirectDrawGammaControl::SetGammaRamp 메소드는, 프라이머리 표면에 대한 적, 초록, 및 파랑 감마 램프를 취득한다.

HRESULT SetGammaRamp(
  DWORD  dwFlags,
  LPGAMMARAMP lpRampData
);

파라미터

dwFlags
감마 calibration를 요구할지 어떨지를 나타내는 플래그. 이 파라미터를 DDSGR_CALIBRATE 로 설정 하면, 구경 측정기가 모든 시스템상에서 동일하게 되도록(듯이), 디스플레이의 물리적 성질에 따라, 감마 램프의 조정을 요구할 수 있다. calibration를 필요로 하지 않는 경우는, 이 파라미터를 0 으로 설정한다.
lpRampData
새로운 적, 초록, 및 파랑 감마 램프 엔트리를 포함한 DDGAMMARAMP 구조체의 주소. 각각의 배열은, frame buffer의 색의 값을 디지털 아날로그 컨버터 (DAC)에 건네주는 색의 값에 맵 한다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

주의

모든 시스템으로 감마 calibration를 지원 하는 것은 아니다. 감마 calibration를 지원 할지 어떨지를 결정하려면 ,IDirectDraw7::GetCaps 을 호출해, 메소드가 돌려준 후에 관련하는 DDCAPS 구조체의 dwCaps2 멤버를 조사한다. DDCAPS2_CANCALIBRATEGAMMA 능력 플래그가 존재 하면, 감마 calibration는 지원 된다.

감마 램프의 calibration에서는, 몇개의 처리에 오버헤드가 일어나므로, 빈번하게 사용할 수 없다.

감마 calibration를 지원 하지 않는 시스템으로 실행하는 경우는,dwFlags 파라미터에 DDSGR_CALIBRATE 플래그를 설정하면, 이 메소드는 실패하지 않는다. calibration 하지 않고 새로운 감마 램프값을 설정 하면, 메소드는 성공한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.

참조

IDirectDrawGammaControl::GetGammaRamp ,감마 컨트롤과 컬러 컨트롤


IDirectDrawPalette

어플리케이션은 IDirectDrawPalette 인터페이스의 메소드를 사용해, DirectDrawPalette 오브젝트를 생성 해, 시스템 레벨 변수와 함께 작용한다. 여기에서는, 이 인터페이스의 메소드의 레퍼런스를 제공한다. 개념의 개요에 대해서는, 「팔레트」를 참조할것.

IDirectDrawPalette 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

메모리의 할당 | Initialize
팔레트 능력 | GetCaps
팔레트 엔트리 | GetEntries
 | SetEntries

모든 COM 인터페이스와 같이,IDirectDrawPalette 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTDRAWPALETTE 데이터형을 사용 하면,IDirectDrawPalette 인터페이스에의 포인터를 포함한 변수를 선언할 수 있다. ddraw.h 헤더 파일은, 이하의 코드로 이러한 데이터형을 선언한다.

typedef struct IDirectDrawPalette    FAR *LPDIRECTDRAWPALETTE;

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


IDirectDrawPalette::GetCaps

IDirectDrawPalette::GetCaps 메소드는, 이 팔레트 오브젝트의 능력을 취득한다.

HRESULT GetCaps(
  LPDWORD lpdwCaps
);

파라미터

lpdwCaps
팔레트 능력을 정의하는 DDCAPS 구조체의 dwPalCaps 멤버로부터의 플래그.
DDPCAPS_1BIT
DDPCAPS_2BIT
DDPCAPS_4BIT
DDPCAPS_8BIT
DDPCAPS_8BITENTRIES
DDPCAPS_ALPHA
DDPCAPS_ALLOW256
DDPCAPS_PRIMARYSURFACE
DDPCAPS_PRIMARYSURFACELEFT
DDPCAPS_VSYNC

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


IDirectDrawPalette::GetEntries

IDirectDrawPalette::GetEntries 메소드는, DirectDrawPalette 오브젝트로부터의 팔레트값을 조회한다.

HRESULT GetEntries(
  DWORD dwFlags,
  DWORD dwBase,
  DWORD dwNumEntries,
  LPPALETTEENTRY lpEntries
);

파라미터

dwFlags
현시점에서는 미사용이므로 0 을 설정해 둔다.
dwBase
순서에 취득하는 엔트리의 선두.
dwNumEntries
lpEntries 로 지정하는 주소에 적합하는 팔레트 엔트리의 수. 각각의 팔레트 엔트리의 색은,dwStartingEntry 파라미터의 값으로부터 dwCount 파라미터의 값을 마이너스 1 한 값까지, 차례로 돌려주어진다. (이러한 값은,IDirectDrawPalette::SetEntries 로 설정된다).
lpEntries
팔레트 엔트리의 주소. DDPCAPS_8BITENTRIES 플래그를 설정하는 경우, 팔레트 엔트리는 1 바이트마다가 된다. 그 이외의 경우는, 4 바이트마다가 된다. 각각의 필드는, 색기술이 된다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTPALETTIZED

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.

참조

IDirectDrawPalette::SetEntries


IDirectDrawPalette::Initialize

IDirectDrawPalette::Initialize 메소드는, DirectDrawPalette 오브젝트를 초기화한다.

HRESULT Initialize(
  LPDIRECTDRAW lpDD,
  DWORD dwFlags,
  LPPALETTEENTRY lpDDColorTable
);

파라미터

lpDD
DirectDraw 오브젝트를 나타내는 DirectDraw 구조체의 주소.
dwFlags,lpDDColorTable
현시점에서는 미사용이므로 0 을 설정해 둔다.

반환값

이 메소드는,DDERR_ALREADYINITIALIZED 를 돌려준다.

이 메소드는, 컴퍼넌트 오브젝트 모델 (COM) 프로토콜 준거로 제공된다. DirectDrawPalette 오브젝트는 생성시에 초기화되므로, 이 메소드는 항상 DDERR_ALREADYINITIALIZED 를 돌려준다.

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.

참조

IUnknown::AddRef ,IUnknown::QueryInterface ,IUnknown::Release


IDirectDrawPalette::SetEntries

IDirectDrawPalette::SetEntries 메소드는, DirectDrawPalette 오브젝트의 엔트리를 즉석에서 변경한다.

HRESULT SetEntries(
  DWORD dwFlags,
  DWORD dwStartingEntry,
  DWORD dwCount,
  LPPALETTEENTRY lpEntries
);

파라미터

dwFlags
현시점에서는 미사용이므로 0 을 설정해 둔다.
dwStartingEntry
설정되는 최초의 엔트리.
dwCount
변경되는 팔레트 엔트리의 수.
lpEntries
팔레트 엔트리의 주소. DDPCAPS_8BITENTRIES 플래그를 설정하는 경우, 팔레트 엔트리는 1 바이트마다가 된다. 그 이외의 경우는, 4 바이트마다가 된다. 각각의 필드는, 색기술이 된다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOPALETTEATTACHED
DDERR_NOTPALETTIZED
DDERR_UNSUPPORTED

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.

참조

IDirectDrawPalette::GetEntries ,IDirectDrawSurface7::SetPalette


IDirectDrawSurface7

어플리케이션은 IDirectDrawSurface7 인터페이스의 메소드를 사용해, DirectDrawSurface 오브젝트를 생성 해, 시스템 레벨 변수와 함께 작용한다. 여기에서는, 이 인터페이스의 메소드의 레퍼런스를 제공한다. 개념의 개요에 대해서는, 「표면」을 참조할것.

IDirectDrawSurface7 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

메모리의 할당 | Initialize
 | IsLost
 | Restore
표면의 Attach | AddAttachedSurface
 | DeleteAttachedSurface
 | EnumAttachedSurfaces
 | GetAttachedSurface
블리트 | Blt
 | BltBatch
 | BltFast
 | GetBltStatus
컬러 키잉 | GetColorKey
 | SetColorKey
디바이스 콘텍스트 | GetDC
 | ReleaseDC
플립핑 | Flip
 | GetFlipStatus
표면의 락 | Lock
 | PageLock
 | PageUnlock
 | Unlock
그 외 | GetDDInterface
오버레이 | AddOverlayDirtyRect
 | EnumOverlayZOrders
 | GetOverlayPosition
 | SetOverlayPosition
 | UpdateOverlay
 | UpdateOverlayDisplay
 | UpdateOverlayZOrder
Private 표면 데이터 | FreePrivateData
 | GetPrivateData
 | SetPrivateData
표면 능력 | GetCaps
표면 클립퍼 | GetClipper
 | SetClipper
표면 특성 | ChangeUniquenessValue
 | GetPixelFormat
 | GetSurfaceDesc
 | GetUniquenessValue
 | SetSurfaceDesc
표면 팔레트 | GetPalette
 | SetPalette
텍스쳐 | GetLOD
 | GetPriority
 | SetLOD
 | SetPriority

모든 COM 인터페이스와 같이,IDirectDrawSurface7 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

IDirectDrawSurface7 인터페이스는, 보다 좋은 표면 관리와 편리한 사용을 갖춘 메소드를 제공하는 것으로써, 이전의 버젼의 인터페이스 기능을 확장했다. 이 인터페이스가 많은 메소드는, 이전의 버젼의 인터페이스로 대응하는 메소드와는 약간 다른 파라미터를 받는다. IDirectDrawSurface3 인터페이스 메소드가 DDSURFACEDESC 구조체나 IDirectDrawSurface3 인터페이스를 받는 장소는 항상, 대신에 IDirectDrawSurface7 의 메소드가 DDSURFACEDESC2 구조체나 IDirectDrawSurface7 인터페이스를 받는다.

LPDIRECTDRAWSURFACE,LPDIRECTDRAWSURFACE2,LPDIRECTDRAWSURFACE3,LPDIRECTDRAWSURFACE4,LPDIRECTDRAWSURFACE7 데이터형을 사용 하면, 다양한 DirectDrawSurface 오브젝트 인터페이스를 가리키는 변수를 선언할 수 있다. ddraw.h 헤더 파일은, 이하의 코드로 이러한 데이터형을 선언한다.

typedef struct IDirectDrawSurface     FAR *LPDIRECTDRAWSURFACE;
typedef struct IDirectDrawSurface2    FAR *LPDIRECTDRAWSURFACE2;
typedef struct IDirectDrawSurface3    FAR *LPDIRECTDRAWSURFACE3;
typedef struct IDirectDrawSurface4    FAR *LPDIRECTDRAWSURFACE4;
typedef struct IDirectDrawSurface7    FAR *LPDIRECTDRAWSURFACE7;

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDrawSurface7::AddAttachedSurface

IDirectDrawSurface7::AddAttachedSurface 메소드는, 지정한 Z 버퍼의 표면을 이 표면에 Attach 한다.

HRESULT AddAttachedSurface(
  LPDIRECTDRAWSURFACE7 lpDDSAttachedSurface
);

파라미터

lpDDSAttachedSurface
표면을 Attach 하는 IDirectDrawSurface7 인터페이스의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_CANNOTATTACHSURFACE
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACEALREADYATTACHED
DDERR_SURFACELOST
DDERR_WASSTILLDRAWING

주의

이 메소드는, Attach 되는 표면의 참조 카운트를 인크리먼트(increment) 한다. 명시적으로 표면의 Attach를 해제해, 참조 카운트를 감소 하려면 ,IDirectDrawSurface7::DeleteAttachedSurface 메소드를 사용한다. IDirectDraw7::CreateSurface 의 단일의 호출로 생성 하는복합 표면 과는 달리, 이 메소드로 Attach 하는 표면은 자동적으로 릴리즈 되지 않는다. 이러한 표면의 릴리즈는, 어플리케이션의 책임이 된다.

이 메소드로 Attach 할 수 있는 것은, Z 버퍼의 표면뿐이다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::DeleteAttachedSurface ,IDirectDrawSurface7::EnumAttachedSurfaces


IDirectDrawSurface7::AddOverlayDirtyRect

IDirectDrawSurface7::AddOverlayDirtyRect 메소드는, 현시점에서는 이행되어 있지 않다.

HRESULT AddOverlayDirtyRect(
  LPRECT lpRect
);

파라미터

lpRect
갱신할 필요가 있는 RECT 구조체의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_UNSUPPORTED

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::UpdateOverlayDisplay


IDirectDrawSurface7::Blt

IDirectDrawSurface7::Blt 메소드는, 비트 블리트 (블록 전송)를 실행한다. 이 메소드는, 블리트 처리중에 Z 버퍼 또는 알파 블렌딩 (알파 채널을 참조)을 지원 하지 않는다.

HRESULT Blt(
  LPRECT lpDestRect,
  LPDIRECTDRAWSURFACE7 lpDDSrcSurface,
  LPRECT lpSrcRect,
  DWORD dwFlags,
  LPDDBLTFX lpDDBltFx
);

파라미터

lpDestRect
목적지 표면상에 블리트 하는 직사각형의 좌상과 우하의 위치를 정의하는 RECT 구조체의 주소. 이 파라미터가 NULL 의 경우, 목적지 표면 전체를 사용한다.
lpDDSrcSurface
블리트의 전송원인 DirectDrawSurface 오브젝트의 IDirectDrawSurface7 인터페이스의 주소.
lpSrcRect
전송원표면상으로부터 블리트 하는 직사각형의 좌상과 우하의 위치를 정의하는 RECT 구조체의 주소. 이 파라미터가 NULL 의 경우, 전송원표면 전체를 사용한다.
dwFlags
컬러 키 정보를 지정한다, 또는 메소드로부터 특별한 동작을 요구하는, 관련지을 수 있었던 DDBLTFX 구조체의 유효 멤버를 결정하는 플래그의 편성. 이하의 플래그가 정의되고 있다.

평가 플래그

DDBLT_COLORFILL
목적지 표면 위에의 목적지 직사각형을 저장 하는 RGB 색으로서 DDBLTFX 구조체의 dwFillColor 멤버를 사용한다.
DDBLT_DDFX
이 블리트에 대해서 사용하는 이펙트를 지정하는,DDBLTFX 구조체의 dwDDFX 멤버를 사용한다.
DDBLT_DDROPS
Microsoft® Win32® API 의 부분이 아닌 라스터 처리 (ROPS)를 지정하는,DDBLTFX 구조체의 dwDDROP 멤버를 사용한다.
DDBLT_DEPTHFILL
목적지 Z 버퍼 표면 위에의 목적지 직사각형을 저장 하는 깊이값으로서DDBLTFX 구조체의 dwFillDepth 멤버를 사용한다.
DDBLT_KEYDESTOVERRIDE
목적지 표면의컬러 키로서 DDBLTFX 구조체의 ddckDestColorkey 멤버를 사용한다.
DDBLT_KEYSRCOVERRIDE
전송원표면의컬러 키로서 DDBLTFX 구조체의 ddckSrcColorkey 멤버를 사용한다.
DDBLT_ROP
이 블리트에 있어서의 ROP 에 DDBLTFX 구조체의 dwROP 멤버를 사용한다. 이러한 ROP 는, Win32 API 로 정의되고 있는 것 것과 같다.
DDBLT_ROTATIONANGLE
표면의 회전각 (1/100 번단위로 지정된다)으로서 DDBLTFX 구조체의 dwRotationAngle 멤버를 사용한다.

컬러 키 플랙

DDBLT_KEYDEST
목적지 표면에 관련지을 수 있었던컬러 키를 사용한다.
DDBLT_KEYSRC
전송원표면에 관련지을 수 있었던컬러 키를 사용한다.

동작 플래그

DDBLT_ASYNC
받은 순서로 퍼스트 인, 퍼스트 아웃 (FIFO) 하드웨어로부터 비동기적으로 이 블리트를 실행한다. FIFO 하드웨어의 빈영역을 이용할 수 없는 경우, 호출은 실패한다.
DDBLT_DONOTWAIT
DirectX 7.0 으로 추가. 블리트를 실행하지 않고 돌려준다, 또는 블리트가 Busy의 경우에 DDERR_WASSTILLDRAWING 을 돌려준다.
DDBLT_WAIT
블리트가 Busy의 경우, DDERR_WASSTILLDRAWING 반환값을 곧바로 돌려주지 않고 대기한다. 그리고, 블리트가 셋업 되는지, 다른 에러가 발생하면(자) 즉석에서 돌려준다.

폐지되고 지원 하지 않는 플래그

All DDBLT_ALPHA flag values.
현시점에서는, 이행되어 있지 않다.
All DDBLT_ZBUFFER flag values
이 메소드는, z 대응의 블리트 처리를 현재 지원 하고 있지 않다. "DDBLT_ZBUFFER" 로 시작되는 플래그는, DirectX 의 이 릴리스에서는 지원 하고 있지 않다.
lpDDBltFx
DDBLTFX 구조체의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_GENERIC
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOALPHAHW
DDERR_NOBLTHW
DDERR_NOCLIPLIST
DDERR_NODDROPSHW
DDERR_NOMIRRORHW
DDERR_NORASTEROPHW
DDERR_NOROTATIONHW
DDERR_NOSTRETCHHW
DDERR_NOZBUFFERHW
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

주의

이 메소드에서는, 동기 또는 비동기의 블리트 (후자가 디폴트)를, 디스플레이 메모리간, 디스플레이 메모리로부터 시스템 메모리에, 시스템 메모리로부터 디스플레이 메모리에, 또는 시스템 메모리간의 어느쪽이든으로 실행할 수 있다. 블리트는,전송원컬러 키 및목적지 컬러 키를 사용해 실행된다. 전송원 및 목적지 직사각형의 사이즈가 다른 경우는, 임의의신축(스트레치)나 수축을 한다.

보통, 블리트가 Busy의 경우, 또는 블리트를 셋업 할 수 없었던 경우,IDirectDrawSurface7：:Blt 는 에러와 함께 즉석에서 돌아간다. 동기 블리트를 요구하려면 , DDBLT_WAIT 플래그를 지정한다. DDBLT_WAIT 플래그를 지정 하면, 블리트가 셋업 되는지, 메소드가 돌아가기 전에 다른 에러가 발생할 때까지, 이 메소드는 대기한다.

RECT 구조체는,right 및 bottom 멤버가 배타적이도록 정의된다. 따라서,right 로부터 left 를 빼면(자) 직사각형의폭과 동일해진다. 이것은, 직사각형의 폭보다 1 만 적은 값은 아니다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDrawSurface7::BltBatch

IDirectDrawSurface7::BltBatch 메소드는, 현시점에서는 이행되어 있지 않다.

HRESULT BltBatch(
  LPDDBLTBATCH lpDDBltBatch,
  DWORD dwCount,
  DWORD dwFlags
);

파라미터

lpDDBltBatch
블리트 처리에 있어서의 파라미터를 정의하는, 최초의 DDBLTBATCH 구조체의 주소.
dwCount
실행하는 블리트 처리의 개수.
dwFlags
현시점에서는 미사용이므로 0 을 설정해 둔다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_GENERIC
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOALPHAHW
DDERR_NOBLTHW
DDERR_NOCLIPLIST
DDERR_NODDROPSHW
DDERR_NOMIRRORHW
DDERR_NORASTEROPHW
DDERR_NOROTATIONHW
DDERR_NOSTRETCHHW
DDERR_NOZBUFFERHW
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDrawSurface7::BltFast

IDirectDrawSurface7::BltFast 메소드는,전송원컬러 키 또는목적지 컬러 키 를 사용해, 전송원카피 블리트 혹은 투과형 블리트를 실행한다.

HRESULT BltFast(
  DWORD dwX,
  DWORD dwY,
  LPDIRECTDRAWSURFACE7 lpDDSrcSurface,
  LPRECT lpSrcRect,
  DWORD dwTrans
);

파라미터

dwX,dwY
목적지 표면상에 블리트 하는 x 좌표와 y 좌표.
lpDDSrcSurface
블리트의 전송원인 DirectDrawSurface 오브젝트의 IDirectDrawSurface7 인터페이스의 주소.
lpSrcRect
전송원표면으로부터 블리트 하는 직사각형의 좌상과 우하의 모퉁이를 정의하는 RECT 구조체의 주소.
dwTrans
전송의 타입. 이하의 전송이 정의되고 있다.
DDBLTFAST_DESTCOLORKEY
목적지컬러 키를 사용하는 투과형 블리트.
DDBLTFAST_NOCOLORKEY
비투과형의 보통의 카피 블리트.
DDBLTFAST_SRCCOLORKEY
전송원컬러 키를 사용하는 투과형 블리트.
DDBLTFAST_WAIT
블리트가 Busy의 경우, DDERR_WASSTILLDRAWING 메세지를 돌려주지 않고 대기한다. 블리트가 셋업 되든가, 혹은 다른 에러가 발생 하면 즉석에서 돌려준다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_EXCEPTION
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOBLTHW
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

주의

하드웨어가 비동기 블리트를 지원 하는 경우, 이 메소드는 항상 그것을 시도한다.

이 메소드는 디스플레이 메모리 표면상에서만 작용해, 블리트중은 클립 할 수 없다. Attach 된 클립퍼가 있는 표면으로 이 메소드를 사용 하면, 호출은 실패해, 메소드는 DDERR_UNSUPPORTED 를 돌려준다.

IDirectDrawSurface7::BltFast 의 소프트웨어 이행은,IDirectDrawSurface7::Blt 메소드보다 10 퍼센트만 고속으로 있다. 다만, 디스플레이 하드웨어를 사용하고 있는 경우는, 양자간에 속도의 차이는 없다.

보통, 블리트가 Busy의 경우, 및 블리트가 셋업되어 있지 않은 경우,IDirectDrawSurface7::BltFast 는 즉석에서 에러를 돌려준다. 다만, 블리트가 셋업 될까 다른 에러가 발생할 때까지, 이 메소드를 돌려주지 않는 경우는, DDBLTFAST_WAIT 플래그를 사용한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDrawSurface7::ChangeUniquenessValue

IDirectDrawSurface7::ChangeUniquenessValue 메소드는, 이 표면에 대한 고유치를 수동으로 갱신한다.

HRESULT ChangeUniquenessValue();

파라미터

없음.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

표면의 컨텐츠를 변경 하면 항상, DirectDraw 는 고유치를 자동적으로 갱신한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::GetUniquenessValue ,표면 고유치


IDirectDrawSurface7::DeleteAttachedSurface

IDirectDrawSurface7::DeleteAttachedSurface 메소드는, 2 개의 표면간의 Attach를 해제한다.

HRESULT DeleteAttachedSurface(
  DWORD dwFlags,
  LPDIRECTDRAWSURFACE7 lpDDSAttachedSurface
);

파라미터

dwFlags
현시점에서는 미사용이므로 0 으로 설정해 둔다.
lpDDSAttachedSurface
Attach를 해제하는 DirectDrawSurface 오브젝트의 IDirectDrawSurface7 인터페이스의 주소. 이 파라미터가 NULL 의 경우, Attach 된 모든 표면의 Attach가 해제된다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_CANNOTDETACHSURFACE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST
DDERR_SURFACENOTATTACHED

주의

이 메소드는, Attach를 해제하는 표면의 참조 카운트를 감소 한다. Attach를 해제하는 표면의 참조 카운트가 제로가 되면(자), 그 표면은 소실해, 메모리로부터 삭제된다.

IDirectDrawSurface7::AddAttachedSurface 메소드는 아니고, DirectDraw 에 의해 형성되는 암묵적인 Attach는 해제할 수 없다. 플립핑 체인으로부터 표면의 Attach를 해제 하면, 체인중의 다른 표면을 변경할 가능성이 있다. 플립핑 체인으로부터프런트 버퍼의 Attach를 해제 하면, 체인안의 다음의 표면이 프런트 버퍼가 되어, 그 다음의 표면이백 버퍼가 된다. 체인으로부터 백 버퍼의 Attach를 해제하는 경우, 다음의 표면이 백 버퍼가 된다. 체인으로부터 프레인 표면의 Attach를 해제하는 경우, 그 체인이 단지 짧아진다. 플립핑 체인에 2 개 표면이 있는 것만으로, 그러한 Attach를 해제하는 경우, 그 체인은 파기되어, 양표면은 원의 목적지에 돌아온다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::Flip


IDirectDrawSurface7::EnumAttachedSurfaces

IDirectDrawSurface7::EnumAttachedSurfaces 메소드는, 주어진 표면에 Attach 되는 모든 표면을 열거한다.

HRESULT EnumAttachedSurfaces(
  LPVOID lpContext,
  LPDDENUMSURFACESCALLBACK2 lpEnumSurfacesCallback
);

파라미터

lpContext
호출마다 열거 멤버에 건네주는, 어플리케이션 정의 구조체의 주소.
lpEnumSurfacesCallback
이 표면에 Attach 되는 각 표면에 대해서 호출하는 EnumSurfacesCallback2 함수의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패 하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

주의

이 메소드는, 이 표면에 직접 Attach 된 표면만을 열거한다. 예를 들어, 3 개(살) 이상의 표면의 플립핑 체인에서는, 각각의 표면이 플립핑 체인의 다음의 표면에게만 Attach 되므로, 1 개의 표면만 열거된다. 이러한 구성에서는, 각각이 연속하는 표면상에서 EnumAttachedSurfaces 를 호출하면, 플립핑 체인 전체를 볼 수가 있다.

이 메소드는 이전의 버젼의 인터페이스의 대응하는 메소드와는 달라,EnumSurfacesCallback 함수보다 EnumSurfacesCallback2 함수에의 포인터를 받는다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDrawSurface7::EnumOverlayZOrders

IDirectDrawSurface7::EnumOverlayZOrders 메소드는, 지정하는 목적지의오버레이 표면을 열거한다. 오버레이는, 프런트로부터 가방, 또는 가방으로부터 프런트의 순서로 열거된다.

HRESULT EnumOverlayZOrders(
  DWORD dwFlags,
  LPVOID lpContext,
  LPDDENUMSURFACESCALLBACK2 lpfnCallback
);

파라미터

dwFlags
이하의 플래그 가운데, 1 개의 값을 취한다.
DDENUMOVERLAYZ_BACKTOFRONT
가방으로부터 프런트의 순서로 오버레이를 열거한다.
DDENUMOVERLAYZ_FRONTTOBACK
프런트로부터 가방의 순서로 오버레이를 열거한다.
lpContext
각 오버레이 표면의 콜백 함수에 건네주는, 유저 정의 문맥의 주소.
lpfnCallback
이 표면에 오버레이 되는 각 표면에 대해서 호출하는,EnumSurfacesCallback2 콜백 함수의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는 이전의 버젼의 인터페이스의 대응하는 메소드와는 달라,EnumSurfacesCallback 함수보다 EnumSurfacesCallback2 함수에의 포인터를 받는다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDrawSurface7::Flip

IDirectDrawSurface7::Flip 메소드는, DDSCAPS_BACKBUFFER 표면과 관련지을 수 있었던 표면 메모리를, 프런트 버퍼 표면과 관련짓는다.

HRESULT Flip(
  LPDIRECTDRAWSURFACE7 lpDDSurfaceTargetOverride,
  DWORD dwFlags
);

파라미터

lpDDSurfaceTargetOverride
플립핑 체인의 임의의 표면에 있어서의 IDirectDrawSurface7 인터페이스의 주소. 이 파라미터의 디폴트는 NULL 이며, DirectDraw 는 서로 Attach 되고 있는 순으로 버퍼로부터 순환한다. 이 파라미터가 NULL 가 아닌 경우, DirectDraw 는 플립핑 체인의 다음의 표면 대신에 지정한 표면에 플립 한다. 지정한 표면이 플립핑 체인의 멤버가 아닌 경우, 메소드는 실패한다.
dwFlags
지정하는 플립 옵션의 플래그
DDFLIP_DONOTWAIT
IDirectDrawSurface7 인터페이스에서는, 디폴트는 DDFLIP_WAIT 이다. 디폴트를 무효로 하는 경우, 및 가속기가 Busy의 경우 (DDERR_WASSTILLDRAWING 반환값으로 나타난다)는, DDFLIP_DONOTWAIT 를 사용한다.
DDFLIP_EVEN
오버레이 표면으로 비디오를 표시하는 경우에 사용. 새로운 표면에는, 비디오 신호의짝수 필드로부터의 데이터가 포함된다. 이 플래그는, DDFLIP_ODD 플래그와 함께 사용할 수 없다.
DDFLIP_STEREO
DirectDraw 는, 메인 스테레오 표면을 플립 해 표시한다. 이 플래그를 설정 하면, 스테레오 자동 플립핑이 유효하게 된다. 각각의 스크린을 리프레쉬 하는 동안, 하드웨어는 자동적으로 좌우의 버퍼간을 플립 한다.
DDFLIP_INTERVAL2
DDFLIP_INTERVAL3
DDFLIP_INTERVAL4
이러한 플래그는, 각 플립간을 대기하는 수직 리트레이스수를 나타낸다. 디폴트값은 1. DirectDraw 에서는, 지정한 수직 리트레이스수가 될 때까지, 플립내의 각 표면에 대한 DERR_WASSTILLDRAWING 를 돌려준다. DDFLIP_INTERVAL2 를 설정 하면, DirectDraw 는 2 번째의 수직 동기 마다 플립 한다. DDFLIP_INTERVAL3 에서는 3 번째의 동기마다, DDFLIP_INTERVAL4 에서는 4 번째의 동기 마다 플립 한다.

이러한 플래그는 효율적인 것은, DDCAPS2_FLIPINTERVAL 가 디바이스에 돌려주어지는 DDCAPS 구조체로 설정되는 경우 뿐이다.

DDFLIP_NOVSYNC
다음의 주사선으로 할 수 있는 한 가까운 물리적인 플립을 실행하는 DirectDraw 를 일으킨다. 2 개의 플립 된 표면을 포함한 다음의 처리에서는, 물리적인 플립이 종료했는지 어떠했는지의 체크는 행해지지 않는다. 즉, 이 이유로부터 DDERR_WASSTILLDRAWING 가 돌려주어질 것은 없다 (그 외의 이유에 의해 돌려주어지는 경우는 있다). 이 때문에, 어플리케이션에서는 모니터 refresh rate 이상의 고주파수로 플립을 실행하는 것이 가능하지만, 눈에 보이는 이상이 발생하는 경우가 있다.

DDCAPS2_FLIPNOVSYNC 가 디바이스에 돌려주어지는 DDCAPS 구조체로 설정되지 않는 경우, DDFLIP_NOVSYNC 은 이펙트가 없다.

DDFLIP_ODD
오버레이 표면으로 비디오를 표시하는 경우에 사용. 새로운 표면에는, 비디오 신호의홀수 필드로부터의 데이터가 포함된다. 이 플래그는, DDFLIP_EVEN 플래그와 함께 사용할 수 없다.
DDFLIP_WAIT
보통, 디스플레이 하드웨어 상태가 부적절하기 때문에에 플립을 셋업 할 수 없는 경우,DDERR_WASSTILLDRAWING 에러가 즉석에서 돌아가, 플립은 일어나지 않는다. 이 플래그를 설정 하면, 메소드는 하드웨어 추상 계층 (HAL)으로부터 DDERR_WASSTILLDRAWING 에러를 받았을 경우에서도 플립을 속행하려고 한다. 이 경우, 메소드는 플립핑 처리가 성공하는지,DDERR_SURFACEBUSY 와 같은 다른 에러가 돌려주어질 때까지 돌려주지 않는다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOFLIPHW
DDERR_NOTFLIPPABLE
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

주의

IDirectDrawSurface7 의 경우, 디폴트에서는, 이 메소드는 가속기가 종료할 때까지 대기한다. 즉, 디폴트 상태에서는, 이 메소드는 DDERR_WASSTILLDRAWING 를 돌려주지 않는다. 에러 코드를 받아, 플립 처리가 성공할 때까지 대기하지 않는 경우는, DDFLIP_DONOTWAIT 플래그를 사용한다.

이 메소드를 호출할 수가 있는 것은, DDSCAPS_FLIP 및 DDSCAPS_FRONTBUFFER 능력이 있는 표면 뿐이다. 이전에프런트 버퍼에 관련지을 수 있었던 디스플레이 메모리는,백 버퍼와 관련지을 수 있다.

lpDDSurfaceTargetOverride 파라미터는, 백 버퍼가 프런트 버퍼가 되어야 할 버퍼는 아니라고 하는 경우에 사용되지만, 이러한 경우는 보기 드물다. 보통, 이 파라미터는 NULL 이다.

IDirectDrawSurface7::Flip 메소드는, 항상 수직귀선소거와 동기 한다. 표면이 비디오 포트에 할당할 수 있고 있으면(자), 이 메소드는 표시 상태의 오버레이 표면 및 비디오 포트의 타겟 표면을 갱신한다.

상세한 것에 대하여는, 「플립핑 표면」을 참조할것.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::GetFlipStatus


IDirectDrawSurface7::FreePrivateData

IDirectDrawSurface7::FreePrivateData 메소드는, 이 표면에 관련지을 수 있었던 지정하는 Private 데이터를 릴리즈 한다.

HRESULT FreePrivateData(
  REFGUID guidTag
);

파라미터

guidTag
릴리즈 하는 Private 데이터를 식별하는 글로벌 유니크 식별자의 (C++) 또는 (C)의 주소에의 참조.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

주의

DirectDraw 는, 표면이 릴리즈 되면(자) 자동적으로 이 메소드를 호출한다.

Private 데이터가 DDSPD_IUNKNOWNPOINTER 플래그를 사용해 설정되어 있는 경우, 이 메소드는 관련지을 수 있었던 인터페이스의 IUnknown::Release 메소드를 호출한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::GetPrivateData ,IDirectDrawSurface7::SetPrivateData


IDirectDrawSurface7::GetAttachedSurface

IDirectDrawSurface7::GetAttachedSurface 메소드는, 지정한 능력을 가지는 Attach 된 표면을 취득해, 취득한 인터페이스의 참조 카운트를 인크리먼트(increment) 한다.

HRESULT GetAttachedSurface(
  LPDDSCAPS2 lpDDSCaps,
  LPDIRECTDRAWSURFACE7 FAR *lplpDDAttachedSurface
);

파라미터

lpDDSCaps
표면의 하드웨어 능력을 포함한 DDSCAPS2 구조체의 주소.
lplpDDAttachedSurface
취득하는 표면의 IDirectDrawSurface7 인터페이스에의 포인터를 받는 변수의 주소. 취득하는 표면은,lpDDSCaps 파라미터의 기술에 적합하는 것이다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND
DDERR_SURFACELOST

주의

Attach는, 복수의 DirectDrawSurface 오브젝트를 복합 구조체에 접속하기 위해서 사용된다. 복합 구조체란, 예를 들어, Z 버퍼와 함께 3D 페이지 플립핑을 지원 하기 위해서 필요한 구조체이다. 요구하는 능력에 적합하는 Attach 된 표면이 1 개 이상 있는 경우, 이 메소드는 실패한다. 이 경우, 어플리케이션에서는 Attach 된 표면을 취득하려면 ,IDirectDrawSurface7::EnumAttachedSurfaces 메소드를 사용해야 한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDrawSurface7::GetBltStatus

IDirectDrawSurface7::GetBltStatus 메소드는, 블리트의 스테이터스를 취득한다.

HRESULT GetBltStatus(
  DWORD dwFlags
);

파라미터

dwFlags
이하의 플래그 가운데, 1 개의 값을 취한다.
DDGBS_CANBLT
이 표면을 필요로 하는 블리트를 곧바로 실행할 수 있을지 어떨지를 문의해 블리트가 완료 하면 DD_OK 를 돌려준다.
DDGBS_ISBLTDONE
블리트가 실행되었는지 어떠했는지를 문의해 이 표면 위에의 마지막 블리트가 완료 하면 DD_OK 를 돌려준다.

반환값

성공하면, 블리트가 존재해, DD_OK 를 돌려준다.

실패하면, 블리트가 Busy의 경우는 DDERR_WASSTILLDRAWING, 블리트가 존재하지 않는 경우는 DDERR_NOBLTHW, 그 외의 경우는 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOBLTHW
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDrawSurface7::GetCaps

IDirectDrawSurface7::GetCaps 메소드는, 표면의 능력을 취득한다. 이러한 능력은, 디스플레이 디바이스의 능력에 관련하고 있을 필요는 없다.

HRESULT GetCaps(
  LPDDSCAPS2 lpDDSCaps
);

파라미터

lpDDSCaps
표면의 하드웨어 능력을 저장 하는 DDSCAPS2 구조체의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는 IDirectDrawSurface3 인터페이스의 대응하는 메소드와는 달라, 현재는 사용되지 않는 DDSCAPS 구조체는 아니고 DDSCAPS2 구조체에의 포인터를 받는다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDrawSurface7::GetClipper

IDirectDrawSurface7::GetPalette 메소드는, 이 표면에 관련지을 수 있었던 DirectDrawPalette 오브젝트를 취득해, 돌려주어지는 클립퍼의참조 카운트를 인크리먼트(increment) 한다.

HRESULT GetClipper(
  LPDIRECTDRAWCLIPPER FAR *lplpDDClipper
);

파라미터

lplpDDClipper
표면에 관련지을 수 있었던 DirectDrawClipper 오브젝트에의 포인터의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCLIPPERATTACHED

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::SetClipper


IDirectDrawSurface7::GetColorKey

IDirectDrawSurface7::GetColorKey 메소드는, DirectDrawSurface 오브젝트에 대한컬러 키값을 취득한다.

HRESULT GetColorKey(
  DWORD dwFlags,
  LPDDCOLORKEY lpDDColorKey
);

파라미터

dwFlags
이하의 플래그의 어느쪽이든으로, 어느컬러 키를 요구하는지를 지정한다.
DDCKEY_DESTBLT
블리트 처리의목적지 컬러 키로서 사용되는 컬러 키 또는색공간(color space) .
DDCKEY_DESTOVERLAY
오버레이 처리의 목적지 컬러 키로서 사용되는 컬러 키 또는 색공간(color space).
DDCKEY_SRCBLT
블리트 처리의전송원컬러 키로서 사용되는 컬러 키 또는 색공간(color space).
DDCKEY_SRCOVERLAY
오버레이 처리의 전송원컬러 키로서 사용되는 컬러 키 또는 색공간(color space).
lpDDColorKey
DirectDrawSurface 오브젝트의, 지정된컬러 키에 대한 현재의 값을 저장 하는 DDCOLORKEY 구조체의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOLORKEY
DDERR_NOCOLORKEYHW
DDERR_SURFACELOST
DDERR_UNSUPPORTED

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::SetColorKey


IDirectDrawSurface7::GetDC

IDirectDrawSurface7::GetDC 메소드는, 표면에 대한 디바이스 콘텍스트의 GDI 호환 핸들을 생성 한다.

HRESULT GetDC(
  HDC FAR *lphDC
);

파라미터

lphDC
돌려주어지는, 디바이스 콘텍스트의 핸들의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_DCALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

주의

이 메소드는, 표면을 잠그는 IDirectDrawSurface7::Lock 메소드의 내부 버젼을 사용한다. IDirectDrawSurface7::ReleaseDC 메소드가 불려 갈 때까지는, 표면은 락 된채로 있다.

ReleaseDC 는,GetDC 를 호출하는 같은 thread로부터 호출할 필요가 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::Lock


IDirectDrawSurface7::GetDDInterface

IDirectDrawSurface7::GetDDInterface 메소드는, 표면을 생성 하기 위해서 사용된 DirectDraw 오브젝트에의 인터페이스를 취득한다.

HRESULT GetDDInterface(
  LPVOID FAR *lplpDD
);

파라미터

lplpDD
호출이 성공했을 경우에, 유효한 인터페이스 포인터를 저장 하는 변수의 주소. 이 포인터를 IUnknown 인터페이스 포인터에 캐스트 한 후에, 요구하는 DirectDraw 인터페이스에 대해서 조회한다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는,IDirectDraw 인터페이스에는 이행되어 있지 않다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDrawSurface7::GetFlipStatus

IDirectDrawSurface7::GetFlipStatus 메소드는, 표면이 플립핑 프로세스를 끝냈는지 어떠했는지를 나타낸다.

HRESULT GetFlipStatus(
  DWORD dwFlags
);

파라미터

dwFlags
이하의 플래그 가운데, 1 개의 값을 취한다.
DDGFS_CANFLIP
이 표면을 즉석에서 플립 할 수 있을지 어떨지를 문의해 플립이 완료하면(자) DD_OK 를 돌려준다.
DDGFS_ISFLIPDONE
플립이 완료했는지 어떠했는지를 문의해 이 표면의 마지막 플립이 완료하면(자) DD_OK 를 돌려준다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 표면이 플립되어 있지 않은 경우는 DDERR_WASSTILLDRAWING 를 돌려주어, 그 외의 이유에 의한 경우는 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::Flip


IDirectDrawSurface7::GetLOD

IDirectDrawSurface7::GetLOD 메소드는, 관리 밉맵 표면에 현재 설정되어 있는 최대 상세 레벨을 취득한다. 이 메소드는, 관리하의 텍스쳐 에 대해서만 성공한다 ( 「주의」참조).

HRESULT GetLOD(
    LPDWORD lpdwMaxLOD
);

파라미터

lpdwMaxLOD
호출이 성공했을 경우에, 최대 상세 레벨의 값을 저장 하는 변수의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

어플리케이션은, 관리하의 텍스쳐 (DDSCAPS2_TEXTUREMANAGE 플래그로 생성 된 텍스쳐) 에 대해서만, 이 메소드를 호출할 수가 있다. 비관리하의 텍스쳐에 대해서 이 메소드를 호출하면, 메소드는 실패해,DDERR_INVALIDOBJECT 를 돌려준다.

이 메소드는, 로컬 비디오 메모리에 로드하는 이 체인 중(안)에서 가장 상세한 밉맵을 Direct3D 텍스쳐 매니저에 통지한다. 예를 들어, 5 레벨의 밉맵 체인에 대해,lpdwMaxLOD 로 가리키는 변수의 값이 2 의 경우, 텍스쳐 매니저는 지정 시간이 되면(자) 레벨 2 에서 4 의 밉맵만 로컬 비디오 메모리에 로드한다. 같이 체인 중(안)에서 가장 상세한 밉맵의 크기가 256 × 256 의 경우,lpdwMaxLOD 의 값 2 는, 지금까지 비디오 메모리내에 있는 최대의 밉맵은 64 × 64 인 것을 나타낸다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::SetLOD ,밉맵에 의한 텍스쳐 필터링,자동 텍스쳐 관리,텍스쳐


IDirectDrawSurface7::GetOverlayPosition

액티브하게 표시 상태의오버레이 표면 (DDSCAPS_OVERLAY 플래그가 설정되어 있다)이 주어지면(자),IDirectDrawSurface7::GetOverlayPosition 메소드는 표면의 디스플레이 좌표를 돌려준다.

HRESULT GetOverlayPosition(
  LPLONG lplX,
  LPLONG lplY
);

파라미터

lplX,lplY
x 좌표와 y 좌표의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPOSITION
DDERR_NOOVERLAYDEST
DDERR_NOTAOVERLAYSURFACE
DDERR_OVERLAYNOTVISIBLE
DDERR_SURFACELOST

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::SetOverlayPosition ,IDirectDrawSurface7::UpdateOverlay


IDirectDrawSurface7::GetPalette

IDirectDrawSurface7::GetPalette 메소드는, 이 표면에 관련지을 수 있었던 DirectDrawPalette 오브젝트를 취득해, 돌려주어지는 팔레트의참조 카운트를 인크리먼트(increment) 한다.

HRESULT GetPalette(
  LPDIRECTDRAWPALETTE FAR *lplpDDPalette
);

파라미터

lplpDDPalette
팔레트 오브젝트의 IDirectDrawPalette 인터페이스에의 포인터를 저장 하는 변수의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_NOPALETTEATTACHED
DDERR_SURFACELOST
DDERR_UNSUPPORTED

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::SetPalette


IDirectDrawSurface7::GetPixelFormat

IDirectDrawSurface7::GetPixelFormat 메소드는, 표면의 컬러와 픽셀 포맷을 취득한다.

HRESULT GetPixelFormat(
  LPDDPIXELFORMAT lpDDPixelFormat
);

파라미터

lpDDPixelFormat
표면의 현재의 픽셀 및색공간(color space) 포맷의 상세 기술을 저장 하는 DDPIXELFORMAT 구조체의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDrawSurface7::GetPriority

IDirectDrawSurface7::GetPriority 메소드는, 텍스쳐의 텍스쳐 관리 우선 순위를 취득한다. 이 메소드는, 관리하의 텍스쳐 에 대해서만 성공한다 ( 「주의」참조).

HRESULT GetPriority(
  LPDWORD lpdwPriority
);

파라미터

lpdwPriority
호출이 성공했을 경우에, 텍스쳐 관리 우선 순위를 저장 하는 변수의 주소.

반환값

성공하면, D3D_OK 를 돌려준다.

실패하면, 에러값을 돌려준다. 파라미터가 무효인 경우, 또는 텍스쳐가 Direct3D 로 관리되어 있지 않은 경우, 메소드는 DDERR_INVALIDOBJECT 를 돌려준다.

주의

우선 순위를 사용해, 관리하의 텍스쳐를 메모리로부터 언제 삭제할까를 결정할 수 있다. 우선 순위가 낮은 텍스쳐는, 우선 순위가 높은 텍스쳐보다 먼저 삭제된다. 2 개의 텍스쳐의 우선 순위가 같은 경우는, 최종 사용시가 새로운 (분)편의 텍스쳐가 메모리에 보관 유지되어 이제(벌써) 한편의 텍스쳐가 삭제된다.

어플리케이션에서는, 관리하의 텍스쳐 (DDSCAPS2_TEXTUREMANAGE 플래그로 생성 한 것)에서만 우선 순위를 설정 및 취득할 수 있다. 비관리하의 텍스쳐에 대해서 이 메소드를 호출하면, 메소드는 실패해,DDERR_INVALIDOBJECT 를 돌려준다.

이 메소드는,IDirectDrawSurface7 인터페이스에 의해 도입되었다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::SetPriority ,자동 텍스쳐 관리,텍스쳐


IDirectDrawSurface7::GetPrivateData

IDirectDrawSurface7::GetPrivateData 메소드는, 제공되는 버퍼에의 표면에 관련지을 수 있었던 Private 데이터를 카피한다.

HRESULT GetPrivateData(
  REFGUID guidTag,
  LPVOID  lpBuffer,
  LPDWORD lpcbBufferSize
);

파라미터

guidTag
취득하는 Private 데이터를 식별하는 글로벌 유니크 식별자의 (C++) 또는 (C)의 주소에의 참조.
lpBuffer
호출이 성공했을 경우에, 요구한 Private 데이터를 저장 하는 할당이 끝난 버퍼의 주소. 이 메소드를 호출하는 어플리케이션은, 이 버퍼의 할당과 릴리즈에 책임을 진다.
lpcbBufferSize
바이트 단위의 lpBuffer 의 버퍼 사이즈. 이 값이 실제의 Private 데이터의 사이즈보다 작은 (0 등) 경우, 메소드는 요구되는 버퍼 사이즈에 이 파라미터를 설정해,DDERR_MOREDATA 를 돌려준다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_EXPIRED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_MOREDATA
DDERR_NOTFOUND
DDERR_OUTOFMEMORY

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::SetPrivateData ,IDirectDrawSurface7::FreePrivateData


IDirectDrawSurface7::GetSurfaceDesc

IDirectDrawSurface7::GetSurfaceDesc 메소드는, 현재 상태에 있어서의 표면 기술을 취득한다.

HRESULT GetSurfaceDesc(
  LPDDSURFACEDESC2 lpDDSurfaceDesc
);

파라미터

lpDDSurfaceDesc
이 표면의 현재의 기술을 저장 하는 DDSURFACEDESC2 구조체의 주소. 메소드를 호출하기 전에, 이 구조체의 dwSize 멤버는, 구조체의 사이즈 (바이트 단위)에 초기화만 되지 않으면 안 된다. 즉, 다른 준비는 필요없다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

DDSURFACEDESC ,DDSURFACEDESC2


IDirectDrawSurface7::GetUniquenessValue

IDirectDrawSurface7::GetUniquenessValue 메소드는, 이 표면에 대한 현재의 고유치를 취득한다.

HRESULT GetUniquenessValue(
  LPDWORD lpValue
);

파라미터

lpValue
호출이 성공했을 경우에, 표면의 현재의 고유치를 저장 하는 변수의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

정의되고 있는 고유치만이 0 이 되어, 표면이 DirectDraw 에 의한 제어를 넘어 변경되는 것이 많은 일을 나타낸다. 다른 고유치는, 캐쉬되기 전의 고유치와 다른 경우에만 중요해진다. 캐쉬되는 값과 현재의 값이 다른 경우는, 표면의 내용이 변경된다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::ChangeUniquenessValue ,표면 고유치


IDirectDrawSurface7::Initialize

IDirectDrawSurface7::Initialize 메소드는, DirectDrawSurface 오브젝트를 초기화한다.

HRESULT Initialize(
  LPDIRECTDRAW lpDD,
  LPDDSURFACEDESC2 lpDDSurfaceDesc
);

파라미터

lpDD
DirectDraw 오브젝트를 나타내는 DirectDraw 구조체의 주소.
lpDDSurfaceDesc
표면에 관련하는 상세를 저장 하는 DDSURFACEDESC2 구조체의 주소.

반환값

메소드는,DDERR_ALREADYINITIALIZED 를 돌려준다.

주의

이 메소드는, 컴퍼넌트 오브젝트 모델 (COM) 프로토콜 준거로 제공된다. DirectDrawSurface 오브젝트는 생성시에 초기화되기 (위해)때문에, 이 메소드는 항상 DDERR_ALREADYINITIALIZED 를 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IUnknown::AddRef ,IUnknown::QueryInterface ,IUnknown::Release


IDirectDrawSurface7::IsLost

IDirectDrawSurface7::IsLost 메소드는, DirectDrawSurface 오브젝트에 관련지을 수 있었던 표면 메모리가 릴리즈 되었는지 어떠했는지를 판단한다.

HRESULT IsLost();

파라미터

없음.

반환값

성공하면, 메모리가 릴리즈되어 있지 않기 때문에 DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

이 메소드를 사용해, 표면 메모리의 재할인 맞히고를 언제 실시할까를 결정할 수 있다. DirectDrawSurface 오브젝트가 표면 메모리를 소실 하면, 대부분의 메소드는 DDERR_SURFACELOST 를 돌려주어 다른 액션을 실행하지 않는다.

주의

디스플레이 카드의 모드가 변경되면(자), 또는 어플리케이션으로 디스플레이 카드에의 배타 액세스를 받아, 디스플레이 카드에 현재 할당할 수 있고 있는 표면 메모리를 모두 릴리즈 하면, 표면의 메모리가 소실하는 일이 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::Restore ,표면의 소실과 restore


IDirectDrawSurface7::Lock

IDirectDrawSurface7::Lock 메소드는, 표면 메모리에의 포인터를 취득한다.

HRESULT Lock(
  LPRECT lpDestRect,
  LPDDSURFACEDESC2 lpDDSurfaceDesc,
  DWORD dwFlags,
  HANDLE hEvent
);

파라미터

lpDestRect
락 되고 있는 표면의 영역을 지정하는 RECT 구조체의 주소. 이 파라미터가 NULL 의 경우, 표면 전체가 락 된다.
lpDDSurfaceDesc
표면에 관련하는 상세를 저장 하는 DDSURFACEDESC2 구조체의 주소.
dwFlags
이하의 플래그가 정의되고 있다.
DDLOCK_DONOTWAIT
IDirectDrawSurface7 인터페이스에서는, 디폴트는 DDLOCK_WAIT 이다. 디폴트를 무효로 하는 경우, 및 가속기가 Busy의 경우 (DDERR_WASSTILLDRAWING 반환값으로 나타난다) 경우는, DDLOCK_DONOTWAIT 를 사용한다.
DDLOCK_EVENT
현시점에서는, 이행되어 있지 않다.
DDLOCK_NOOVERWRITE
DirectX 7.0 으로 추가. Direct3D 버텍스 버퍼의 락에게만 사용한다. 락중에 프레임의 시점 (또는, 이 플래그를 사용하지 않는 경우는 마지막 락)이 변경되기 (위해)때문에, Draw*PrimitiveVB 의 호출에 참조되는 버텍스가 존재하지 않는 가리킨다. 이 플래그는, 버텍스 버퍼에 데이터를 추가할 경우에 편리하다.
DDLOCK_NOSYSLOCK
Win16Mutex (Win16Lock 로 불린다)를 사용하지 않는다. 프라이머리 표면을 잠그고 있을 때는, 이 플래그는 무시된다.
DDLOCK_DISCARDCONTENTS
DirectX 7.0 으로 추가. Direct3D 버텍스 버퍼의 락에게만 사용한다. 이 락중에 버텍스 버퍼의 내용을 계승하는 장소가 없는 것을 나타낸다. 이 플래그를 지정 하면, Direct3D 또는 드라이버는 다른 메모리 영역을 버텍스 버퍼로서 제공할 수 있다. 이 플래그는, 버텍스 버퍼의 내용을 소거해 새로운 데이터를 넣을 때 편리하다.
DDLOCK_OKTOSWAP
이 플래그는 폐지되고 있어 DDLOCK_DISCARDCONTENTS 플래그로 옮겨놓을 수 있고 있다.
DDLOCK_READONLY
락 되고 있는 표면은 읽어들여 전용인 것을 나타낸다.
DDLOCK_SURFACEMEMORYPTR
지정되는 직사각형의 상위에의 유효한 메모리 포인터를 돌려주지 않으면 안 되는 것을 나타낸다. 지정되는 직사각형이 없는 경우, 표면의 상위에의 포인터가 돌려주어진다. 이 플래그는 디폴트이다.
DDLOCK_WAIT
블리트 처리중이기 (위해)때문에 락을 취득할 수 없는 경우, 락이 취득될 때까지, 또는 DDERR_SURFACEBUSY 등의 다른 에러가 발생할 때까지, 메소드는 락을 취득하려고 반복한다.
DDLOCK_WRITEONLY
락 되고 있는 표면이 쓰기 가능한 것을 나타낸다.
hEvent
미사용이므로 NULL 를 설정해 둔다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_WASSTILLDRAWING

주의

이 메소드의 이용에 대한 상세 정보는, 「표면 메모리에의 직접 액세스」를 참조할것.

IDirectDrawSurface7 의 경우, 디폴트에서는, 이 메소드는 가속기가 종료할 때까지 대기한다. 즉, 디폴트 상태에서는, 이 메소드는 DDERR_WASSTILLDRAWING 를 돌려주지 않는다. 에러 코드를 받아, 블리트 처리가 성공할 때까지 대기하지 않는 경우는, DDLOCK_DONOTWAIT 플래그를 사용한다.

표면 메모리 포인터를 취득한 후, 대응하는 IDirectDrawSurface7::Unlock 메소드가 불려 갈 때까지 표면 메모리에 액세스 할 수 있다. 표면의 락이 해제되면(자), 표면 메모리에의 포인터는 무효가 된다.

표면의 락 된 영역으로부터 블리트 하기 위해서, DirectDraw 블리트 함수를 호출해서는 안 된다. 이 함수를 호출했을 경우, 블리트는 DDERR_SURFACEBUSY 또는 DDERR_LOCKEDSURFACES 의 어느쪽이든을 돌려준다. GDI 블리트 함수는, 락 된 비디오 메모리 표면으로 사용했을 경우는 아무것도 돌려주지 않고 실패한다.

DDLOCK_NOSYSLOCK 플래그를 포함하지 않으면, 이 메소드는 IDirectDrawSurface7::Unlock 메소드를 호출할 때까지, DirectDraw 로 Win16Mutex (Win16Lock 라고도 불린다)를 보관 유지한다. GUI 디버거는, Win16Mutex 가 보관 유지되고 있는 동안은 처리할 수 없다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::Unlock ,IDirectDrawSurface7::GetDC ,IDirectDrawSurface7::ReleaseDC


IDirectDrawSurface7::PageLock

IDirectDrawSurface7::PageLock 메소드는, 다이렉트 메모리 액세스 (DMA)에 의한 시스템 메모리에의 블리트 처리중, 또는 시스템 메모리로부터의 블리트 처리중에, 시스템 메모리 표면이 페이지 아웃 되는 것을 회피한다.

HRESULT PageLock(
  DWORD dwFlags
);

파라미터

dwFlags
현시점에서는 미사용이므로 0 을 설정해 둔다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_CANTPAGELOCK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

주의

DMA 지원을 이용하려면 , 이 메소드를 호출하지 않으면 안 된다. 이 메소드를 호출하지 않으면 블리트는 소프트웨어 에뮬레이션을 사용해 행해진다. 상세한 것에 대하여는, 「DMA 의 사용」을 참조할것.

잠그는 메모리가 너무 많으면(자), operating system의 퍼포먼스에 악영향을 준다.

락 카운트는 각각의 표면에 대해서 유지되어 표면에 대해서 IDirectDrawSurface7::PageLock 가 불려 갈 때마다 인크리먼트(increment) 된다. IDirectDrawSurface7::PageUnlock 가 불려 가면(자), 이 카운트는 감소 된다. 락 카운트가 0 이 되면(자), 메모리의 락이 해제되어 operating system로 페이징 할 수 있게 된다.

이 메소드는, 시스템 메모리 표면에 대해서만 작용한다. 즉, 디스플레이 메모리 표면이나 에뮬레이트 되는프라이머리 표면을 페이지 잠글 수 없다. 어플리케이션이 디스플레이 메모리 표면으로 이 메소드를 호출했을 경우, 메소드는 DD_OK 를 돌려주는 것만으로 있다.

이 메소드는,IDirectDraw 인터페이스에는 이행되어 있지 않다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::PageUnlock


IDirectDrawSurface7::PageUnlock

IDirectDrawSurface7::PageUnlock 메소드는, 시스템 메모리 표면의 락을 해제해, 페이지 아웃 할 수 있도록(듯이) 한다.

HRESULT PageUnlock(
  DWORD dwFlags
);

파라미터

dwFlags
현시점에서는 미사용이므로 0 을 설정해 둔다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_CANTPAGEUNLOCK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTPAGELOCKED
DDERR_SURFACELOST

주의

락 카운트는 각각의 표면에 대해서 유지되어 표면에 대해서 IDirectDrawSurface7::PageLock 가 불려 갈 때마다 인크리먼트(increment) 된다. 이 카운트는,IDirectDrawSurface7::PageUnlock 가 불려 가면(자) 감소 된다. 락 카운트가 0 이 되면(자), 메모리의 락이 해제되어 operating system로 페이징 할 수 있게 된다.

이 메소드는, 시스템 메모리 표면에 대해서만 작용한다. 즉, 디스플레이 메모리 표면이나 에뮬레이트 되는프라이머리 표면을 페이지 잠글 수 없다. 어플리케이션이 디스플레이 메모리 표면으로 이 메소드를 호출했을 경우, 이 메소드는 DD_OK 를 돌려주는 것만으로 있다.

이 메소드는,IDirectDraw 인터페이스에는 이행되어 있지 않다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::PageLock


IDirectDrawSurface7::ReleaseDC

IDirectDrawSurface7::ReleaseDC 메소드는, 이전에 IDirectDrawSurface7::GetDC 메소드로 취득한 디바이스 콘텍스트의 핸들을 릴리즈 한다.

HRESULT ReleaseDC(
  HDC hDC
);

파라미터

hDC
이전에 IDirectDrawSurface7::GetDC 로 취득한 디바이스 콘텍스트의 핸들.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST
DDERR_UNSUPPORTED

주의

이 메소드는,IDirectDrawSurface7::GetDC 메소드가 불려 갔을 때에, 미리 락 된 표면의 락도 해제한다.

ReleaseDC 는,GetDC 를 호출하는 같은 thread로부터 호출할 필요가 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::GetDC


IDirectDrawSurface7::Restore

IDirectDrawSurface7::Restore 메소드는, 소실된 표면을 restore 한다. 이것은, DirectDrawSurface 오브젝트에 관련지을 수 있었던 표면 메모리를 릴리즈 할 경우에 생긴다.

HRESULT Restore();

파라미터

없음.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_GENERIC
DDERR_IMPLICITLYCREATED
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_OUTOFMEMORY
DDERR_UNSUPPORTED
DDERR_WRONGMODE

주의

이 메소드는, 표면에 할당할 수 있고 있던 메모리를 restore 하지만, 표면의 소실전에 존재하고 있던 가능성이 있는 비트 맵은 재로드하지 않는다. 상세한 것에 대하여는, 「표면의 소실과 restore」를 참조할것.

디스플레이 카드의 모드가 변경되면(자), 또는 어플리케이션으로 디스플레이 카드에의 배타 액세스를 받아, 카드로 할당할 수 있고 있는 현재의 표면 메모리를 모두 릴리즈 하면, 표면이 소실하는 경우가 있다. DirectDrawSurface 오브젝트로 그 표면 메모리가 소실 하면, 많은 메소드는 DDERR_SURFACELOST 를 돌려주어, 그 외 모든 기능을 실행하지 않게 된다. IDirectDrawSurface7::Restore 메소드는, 표면 메모리를 다시 할당해, DirectDrawSurface 오브젝트에 재차 Attach 한다.

이 메소드의 단일의 호출을 실시하면, DirectDrawSurface 오브젝트를 관련지을 수 있고 있는 암묵적인 표면 (백 버퍼등)이 restore 된다. 암묵적으로 생성 된 표면을 restore 하려고 하면(자), 에러가 발생한다. IDirectDrawSurface7::Restore 는,IDirectDrawSurface7::AddAttachedSurface 메소드에 의한 명시적인 Attach에 대해서는 작용하지 않는다. 즉, 이러한 표면은 개별적으로 restore 해야 한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::IsLost


IDirectDrawSurface7::SetClipper

IDirectDrawSurface7::SetClipper 메소드는, 표면에 클립퍼 오브젝트를 Attach 하거나 표면으로부터 클립퍼 오브젝트를 삭제한다.

HRESULT SetClipper(
  LPDIRECTDRAWCLIPPER lpDDClipper
);

파라미터

lpDDClipper
DirectDrawSurface 오브젝트에 Attach 되는 DirectDrawClipper 오브젝트의 IDirectDrawClipper 인터페이스의 주소. 이 파라미터가 NULL 의 경우, 현재의 DirectDrawClipper 오브젝트는 Attach가 해제된다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_NOCLIPPERATTACHED

주의

클립퍼를 최초로 표면으로 설정할 경우에, 이 메소드는 클립퍼의 참조 카운트를 인크리먼트(increment) 한다. 즉, 그 후의 호출은 클립퍼의 참조 카운트에 영향을 주지 않는다. IpDDClipper 파라미터로서 NULL 를 건네주면(자), 클립퍼는 표면으로부터 삭제되어 클립퍼의 참조 카운트가 감소 된다. 클립퍼를 삭제하고 있지 않는 경우, 표면 자체가 릴리즈 될 때, 표면에 의해 클립퍼에의 참조가 자동적으로 릴리즈 된다. COM 규칙에 의해, 오브젝트가 불필요하게 되면(자), 어플리케이션에서는 클립퍼에 대해서 보관 유지하고 있는 모든 참조를 릴리즈 할 필요가 있다.

이 메소드는,프라이머리 표면에 오버레이 되는지, 블리트 되는 표면에 의해 주로 사용된다. 다만, 이 메소드는, 어느 표면상에서도 사용할 수 있다. DirectDrawClipper 오브젝트가 Attach 되어 거기에클립 리스트를 관련지을 수 있으면(자), 그 DirectDrawClipper 오브젝트는 부모의 DirectDrawSurface 오브젝트를 포함한 IDirectDrawSurface7::Blt ,IDirectDrawSurface7::BltBatch , 및 IDirectDrawSurface7::UpdateOverlay 처리로 사용된다. 이 메소드는, 또, DirectDrawSurface 오브젝트의 현재의 DirectDrawClipper 오브젝트의 Attach도 해제할 수 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::GetClipper


IDirectDrawSurface7::SetColorKey

IDirectDrawSurface7::SetColorKey 메소드는, 하드웨어가 표면 기준 마다 컬러 키를 지원 하는 경우, DirectDrawSurface 오브젝트에 대한컬러 키값을 설정한다.

HRESULT SetColorKey(
  DWORD dwFlags,
  LPDDCOLORKEY lpDDColorKey
);

파라미터

dwFlags
요구되는 컬러 키를 결정한다. 이하의 플래그가 정의되고 있다.
DDCKEY_COLORSPACE
색공간(color space) 를 포함한 구조체. 구조체에 단일의 컬러 키가 있는 경우는 설정하지 않는다.
DDCKEY_DESTBLT
블리트 처리의목적지 컬러 키로서 사용하는 컬러 키 또는 색공간(color space).
DDCKEY_DESTOVERLAY
오버레이 처리의 목적지 컬러 키로서 사용하는 컬러 키 또는 색공간(color space).
DDCKEY_SRCBLT
블리트 처리의전송원컬러 키로서 사용하는 컬러 키 또는 색공간(color space).
DDCKEY_SRCOVERLAY
오버레이 처리의 전송원컬러 키로서 사용하는 컬러 키 또는 색공간(color space).
lpDDColorKey
DirectDrawSurface 오브젝트의 새로운 컬러 키값을 포함한 DDCOLORKEY 구조체의 주소. 미리 설정한 컬러 키를 삭제하려면 , 이 값을 NULL 로 한다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_NOOVERLAYHW
DDERR_NOTAOVERLAYSURFACE
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

주의

투과형 블리트 및 오버레이에 대해서, 목적지 표면의 목적지의 색 및 전송원표면의 전송원의 색을 설정하는 것.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::GetColorKey


IDirectDrawSurface7::SetLOD

IDirectDrawSurface7::SetLOD 메소드는, 관리 밉맵 표면의 최대 상세 레벨을 설정한다. 이 메소드는, 관리하의 텍스쳐 에 대해서만 성공한다 ( 「주의」참조).

HRESULT SetLOD(
    DWORD dwMaxLOD
);
dwMaxLOD
호출이 성공했을 경우에, 밉맵 체인으로 설정하는 최대 상세 레벨의 값.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

어플리케이션에서는, 관리하의 텍스쳐 (DDSCAPS2_TEXTUREMANAGE 플래그로 생성 된 것) 에 대해서만, 이 메소드를 호출할 수가 있다. 비관리하의 텍스쳐에 대해서 이 메소드를 호출하면, 메소드는 실패해,DDERR_INVALIDOBJECT 를 돌려준다.

이 메소드는, 로컬 비디오 메모리에 로드하는 이 체인 중(안)에서 가장 상세한 밉맵을 Direct3D 텍스쳐 매니저에 통지한다. 예를 들어, 5 레벨의 밉맵 체인에 대해 dwMaxLOD 를 2 로 설정 하면, 텍스쳐 매니저는 지정 시간이 되면(자) 레벨 2 에서 4 의 밉맵만 로컬 비디오 메모리에 로드한다. 같이 체인 중(안)에서 가장 상세한 밉맵의 크기가 256 × 256 의 경우, 최대 레벨을 2 로 설정 하면, 지금까지 비디오 메모리내에 있는 최대의 밉맵은 64 × 64 인 것을 나타내게 된다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::GetLOD ,밉맵에 의한 텍스쳐 필터링,자동 텍스쳐 관리,텍스쳐


IDirectDrawSurface7::SetOverlayPosition

IDirectDrawSurface7::SetOverlayPosition 메소드는,오버레이 표면의 디스플레이 좌표를 변경한다.

HRESULT SetOverlayPosition(
  LONG lX,
  LONG lY
);

파라미터

lX,lY
새로운 x 디스플레이 좌표와 y 디스플레이 좌표.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPOSITION
DDERR_NOOVERLAYDEST
DDERR_NOTAOVERLAYSURFACE
DDERR_OVERLAYNOTVISIBLE
DDERR_SURFACELOST
DDERR_UNSUPPORTED

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::GetOverlayPosition ,IDirectDrawSurface7::UpdateOverlay


IDirectDrawSurface7::SetPalette

IDirectDrawSurface7::SetPalette 메소드는, 표면에 팔레트 오브젝트를 Attach 한다 (또는, 표면으로부터 그 Attach를 해제한다). 표면은, 모든 연속하는 처리에 이 팔레트를 사용한다. 팔레트의 변경은, 리프레쉬 타이밍에 관계없이 즉석에서 행해진다.

HRESULT SetPalette(
  LPDIRECTDRAWPALETTE lpDDPalette
);

파라미터

lpDDPalette
이 표면과와도 사용되는 팔레트 오브젝트의 IDirectDrawPalette 인터페이스의 주소. 이 파라미터가 NULL 의 경우, 현재의 팔레트는 Attach가 해제된다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDSURFACETYPE
DDERR_NOEXCLUSIVEMODE
DDERR_NOPALETTEATTACHED
DDERR_NOPALETTEHW
DDERR_NOT8BITCOLOR
DDERR_SURFACELOST
DDERR_UNSUPPORTED

주의

팔레트를 최초로 표면으로 설정할 경우에, 이 메소드는 팔레트의 참조 카운트를 인크리먼트(increment) 한다. 즉, 그 후의 호출은 팔레트의 참조 카운트에 영향을 주지 않는다. IpDDPalette 파라미터로서 NULL 를 건네주면(자), 팔레트는 표면으로부터 삭제되어 그 팔레트의 참조 카운트는 감소 된다. 팔레트를 삭제하고 있지 않는 경우, 표면 자체가 릴리즈 될 때, 표면에 의해 팔레트에의 참조가 자동적으로 릴리즈 된다. COM 규칙에 의해, 오브젝트가 불필요하게 되면(자), 어플리케이션에서는 팔레트에 대해서 보관 유지하고 있는 모든 참조를 릴리즈 할 필요가 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::GetPalette ,IDirectDraw7::CreatePalette


IDirectDrawSurface7::SetPriority

IDirectDrawSurface7::GetPriority 메소드는, 이 텍스쳐의 텍스쳐 관리 우선 순위를 할당한다. 이 메소드는, 관리하의 텍스쳐 에 대해서만 성공한다 ( 「주의」참조).

HRESULT SetPriority(
  DWORD dwPriority
);

파라미터

dwPriority
텍스쳐의 새로운 텍스쳐 관리 우선 순위를 지정하는 값.

반환값

성공하면, D3D_OK 를 돌려준다.

실패하면, 메소드는 에러를 돌려준다. 파라미터가 무효인 경우, 또는 텍스쳐가 Direct3D 로 관리되어 있지 않은 경우, 메소드는 DDERR_INVALIDOBJECT 를 돌려준다.

주의

이 메소드는,IDirectDrawSurface7 인터페이스에 의해 도입되었다.

우선 순위를 사용해, 관리하의 텍스쳐를 메모리로부터 언제 삭제할까를 결정할 수 있다. 우선 순위가 낮은 텍스쳐는, 우선 순위가 높은 텍스쳐보다 먼저 삭제된다. 2 개의 텍스쳐의 우선 순위가 같은 경우는, 최종 사용시가 새로운 (분)편의 텍스쳐가 메모리에 보관 유지되어 이제(벌써) 한편의 텍스쳐가 삭제된다.

어플리케이션에서는, 관리하의 텍스쳐 (DDSCAPS2_TEXTUREMANAGE 플래그로 생성 한 것)에서만 우선 순위를 설정 및 취득할 수 있다. 비관리하의 텍스쳐에 대해서 이 메소드를 호출하면, 메소드는 실패해,DDERR_INVALIDOBJECT 를 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::GetPriority ,자동 텍스쳐 관리,텍스쳐


IDirectDrawSurface7::SetPrivateData

IDirectDrawSurface7::SetPrivateData 메소드는, DirectDraw 는 아니고 어플리케이션으로 자주(잘) 사용되는 표면과 데이터를 관련짓는다. 데이터는 값으로 건네받아 데이터와 데이터의 복수 설정은 단일의 표면과 관련지을 수 있다.

HRESULT SetPrivateData(
  REFGUID guidTag,
  LPVOID  lpData,
  DWORD   cbSize,
  DWORD   dwFlags
);

파라미터

guidTag
설정하는 Private 데이터를 식별하는 글로벌 식별자의 (C++) 또는 (C)의 주소에의 참조.
lpData
표면에 관련지을 수 있는 데이터를 포함한 버퍼의 주소.
cbSize
바이트 단위의 lpData 에 있어서의 버퍼 사이즈.
dwFlags
건네받는 데이터의 형태를 기술하거나 표면의 변경시에 무효가 되는 데이터를 요구하는 플래그. 이하의 플래그가 정의되고 있다.
(none)
플래그가 지정되지 않는 경우, DirectDraw 는 버퍼내의 데이터를 보관 유지하는 메모리를 할당해 새로운 버퍼에 데이터를 카피한다. DirectDraw 에 의해 할당할 수 있는 버퍼는, 적당 자동적으로 릴리즈 된다.
DDSPD_IUNKNOWNPOINTER
IpData 의 데이터는,IUnknown 인터페이스에의 포인터이다. DirectDraw 는, 이 인터페이스의 IUnknown::AddRef 메소드를 자동적으로 호출한다. 이 데이터가 불필요하게 되면(자), DirectDraw 는 이 인터페이스의 IUnknown::Release 메소드를 자동적으로 호출한다.
DDSPD_VOLATILE
lpData 의 버퍼는, 표면으로 변경이 더해지지 않은 동안만 유효하다. 표면의 내용이 변경되면(자), 그 후의 IDirectDrawSurface7::GetPrivateData 메소드의 호출에서는 DDERR_EXPIRED 가 돌려주어진다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

주의

DirectDraw 는,lpData 로 메모리를 관리하지 않는다. 이 버퍼가 동적으로 할당할 수 있었을 경우, 호출측의 책임으로 메모리를 릴리즈 한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::GetPrivateData ,IDirectDrawSurface7::FreePrivateData


IDirectDrawSurface7::SetSurfaceDesc

IDirectDrawSurface7::SetSurfaceDesc 메소드는, 기존의 표면의 특성을 설정한다.

HRESULT SetSurfaceDesc(
  LPDDSURFACEDESC2 lpddsd2,
  DWORD dwFlags
);

파라미터

lpddsd2
새로운 표면 특성을 포함한 DDSURFACEDESC2 구조체의 주소.
dwFlags
현시점에서는 미사용이므로 0 을 설정해 둔다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDPARAMS
DDERR_INVALIDOBJECT
DDERR_SURFACELOST
DDERR_SURFACEBUSY
DDERR_INVALIDSURFACETYPE
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDCAPS
DDERR_UNSUPPORTED
DDERR_GENERIC

주의

현재, 이 메소드는, 명시적인 시스템 메모리 표면으로 사용되는 표면 데이터, 및 픽셀 포맷을 설정하기 위해(때문에)인 만큼 사용할 수 있다. 이 메소드를 사용 하면, 표면은 이전에 할당할 수 있었던 버퍼로부터 데이터를 카피하지 않고 사용할 수 있으므로 편리하다. 새로운 표면 메모리는, 클라이언트 어플리케이션에 의해 할당할 수 있다. 이 경우, 클라이언트 어플리케이션에서는, 그 할당의 릴리즈도 실시할 필요가 있다. 상세한 것에 대하여는, 「표면 특성의 갱신」을 참조할것.

이 메소드를 잘못해 사용 하면, 예측 불가능한 동작이 생긴다. DirectDrawSurface 오브젝트는, 그 오브젝트 자체로 할당하지 않은 표면 메모리의 할당 해제는 실시하지 않는다. 따라서, 표면 메모리가 필요없게 되면(자), 개발자가 그 할당을 해제하지 않으면 안 된다. 다만, 이 메소드가 불려 가는 경우, DirectDraw 는 표면의 생성시에 은근히 할당한 원의 표면 메모리를 릴리즈 한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDrawSurface7::Unlock

IDirectDrawSurface7::Unlock 메소드는, DirectDraw 에 직접 표면 처리가 완료한 것을 통지한다.

HRESULT Unlock(
  LPRECT lpRect
);

파라미터

lpRect
IDirectDrawSurface7::Lock 메소드에의 대응하는 호출로, 표면을 잠그기 위해서(때문에) 사용한 RECT 구조체의 주소. IDirectDrawSurface7::Lock 메소드에의 대응하는 호출의 lpDestRect 파라미터에 NULL 를 건네주는 것으로, 표면 전체를 잠그었을 경우에 한해, 이 파라미터는 NULL 가 된다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOTLOCKED
DDERR_SURFACELOST

주의

다른 목적지 직사각형이 있는 같은 표면에 대한 IDirectDrawSurface7::Lock 의 호출은 여러 차례 가능하기 때문에,lpRect 의 포인터는 IDirectDrawSurface7::Lock 및 IDirectDrawSurface7:Unlock 메소드의 호출해에 링크한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::Lock


IDirectDrawSurface7::UpdateOverlay

IDirectDrawSurface7::UpdateOverlay 메소드는,오버레이 표면의 비주얼 속성을 재배치하거나 변경한다. 이러한 표면에는, DDSCAPS_OVERLAY 플래그를 설정할 필요가 있다.

HRESULT UpdateOverlay(
  LPRECT lpSrcRect,
  LPDIRECTDRAWSURFACE7 lpDDDestSurface,
  LPRECT lpDestRect,
  DWORD dwFlags,
  LPDDOVERLAYFX lpDDOverlayFx
);

파라미터

lpSrcRect
오버레이로서 사용되는 전송원표면의 영역의 x, y, 폭, 및 높이를 정의하는 RECT 구조체의 주소. 이 파라미터는, 오버레이를 은폐 하는 경우나, 오버레이 표면 전체를 사용해, 한편 오버레이 표면이 디바이스 드라이버로부터의 경계 및 사이즈아라이먼트 제한에도 따르는 것을 나타내는 경우에, NULL 로 한다.
lpDDDestSurface
오버레이가 적용되는 표면의 IDirectDrawSurface7 인터페이스의 주소.
lpDestRect
오버레이를 이동하는 목적지 표면의 영역의 x, y, 폭, 및 높이를 정의하는 RECT 구조체의 주소. 이 파라미터는, 오버레이를 은폐 하는 경우에 NULL 가 된다.
dwFlags
이하의 플래그가 정의되고 있다.
DDOVER_ADDDIRTYRECT
에뮬레이트 된 오버레이 표면에 더티 직사각형을 추가한다.
DDOVER_ALPHADEST
폐지.
DDOVER_ALPHADESTCONSTOVERRIDE
이 오버레이의 목적지알파 채널로서DDOVERLAYFX 구조체의 dwAlphaDestConst 멤버를 사용한다.
DDOVER_ALPHADESTNEG
알파값의 증가에 따라 목적지 표면이 보다 투명형이 되는 것을 나타낸다 (0 은 불투명).
DDOVER_ALPHADESTSURFACEOVERRIDE
이 오버레이의 목적지 알파 채널로서DDOVERLAYFX 구조체의 lpDDSAlphaDest 멤버를 사용한다.
DDOVER_ALPHAEDGEBLEND
컬러 키색과의 경계에 있는, 화면의 엣지의 알파 채널로서DDOVERLAYFX 구조체의 dwAlphaEdgeBlend 멤버를 사용한다.
DDOVER_ALPHASRC
이 오버레이의 전송원알파 채널로서 픽셀 포맷의 알파 정보, 또는 전송원표면에 Attach 되는 알파 채널 표면의 어느쪽이든을 사용한다.
DDOVER_ALPHASRCCONSTOVERRIDE
이 오버레이의 전송원알파 채널로서DDOVERLAYFX 구조체의 dwAlphaSrcConst 멤버를 사용한다.
DDOVER_ALPHASRCNEG
알파값의 증가에 따라 전송원표면이 보다 투명형이 되는 것을 나타낸다 (0 은 불투명).
DDOVER_ALPHASRCSURFACEOVERRIDE
이 오버레이의 전송원알파 채널로서DDOVERLAYFX 구조체의 lpDDSAlphaSrc 멤버를 사용한다.
DDOVER_ARGBSCALEFACTORS
DirectX 7.0 으로 추가. DDOVERLAYFX 구조체가 유효한 ARGB 스케일링 계수를 포함하는 것을 나타낸다.
DDOVER_AUTOFLIP
비디오 포트 VSYNC 가 발생할 때마다, 플립핑 체인의 다음의 표면을 자동적으로 플립 한다.
DDOVER_BOB
인터 레이스 비디오 스트림의 각각의필드를 이상 없고 개별적으로 표시한다.
DDOVER_BOBHARDWARE
BOB 처리는, 소프트웨어 또는 에뮬레이트는 아니고, 하드웨어를 사용해 실행된다. 이 플래그는, DDOVER_BOB 플래그와 함께 사용하지 않으면 안 된다.
DDOVER_DDFX
IpDDOverlayFx 파라미터로 오버레이 FX 플래그를 사용해, 특수한 오버레이 이펙트를 정의한다.
DDOVER_DEGRADEARGBSCALING
DirectX 7.0 으로 추가. ARGB 스케일링 계수는, 드라이버 능력에 적합하도록(듯이) 내릴 수 있는 경우가 있다.
DDOVER_HIDE
이 오버레이를 오프로 한다.
DDOVER_INTERLEAVED
표면 메모리는, 인터리브 된 필드로부터 완성된다.
DDOVER_KEYDEST
목적지 표면에 관련지을 수 있고 있는 컬러 키를 사용한다.
DDOVER_KEYDESTOVERRIDE
목적지 표면의컬러 키로서DDOVERLAYFX 구조체의 dckDestColorkey 멤버를 사용한다.
DDOVER_KEYSRC
전송원표면에 관련지을 수 있고 있는 컬러 키를 사용한다.
DDOVER_KEYSRCOVERRIDE
전송원표면의 컬러 키로서DDOVERLAYFX 구조체의 dckSrcColorkey 멤버를 사용한다.
DDOVER_OVERRIDEBOBWEAVE
BOB/WEAVE 결정을, 다른 인터페이스로 오버라이드(override) 해서는 안 된다.
DDOVER_REFRESHALL
에뮬레이트 된 오버레이 표면에 표면 전체를 재드로잉(Drawing) 한다.
DDOVER_REFRESHDIRTYRECTS
에뮬레이트 된 오버레이 표면에 모든 더티 직사각형을 재드로잉(Drawing) 한다.
DDOVER_SHOW
이 오버레이를 온으로 한다.
lpDDOverlayFx
사용하는 이펙트를 기술하는 DDOVERLAYFX 구조체의 주소. DDOVER_DDFX 플래그를 지정하지 않는 경우는 NULL 로 할 수 있다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_DEVICEDOESNTOWNSURFACE
DDERR_GENERIC
DDERR_HEIGHTALIGN
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_INVALIDSURFACETYPE
DDERR_NOSTRETCHHW
DDERR_NOTAOVERLAYSURFACE
DDERR_OUTOFCAPS
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_XALIGN

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.


IDirectDrawSurface7::UpdateOverlayDisplay

IDirectDrawSurface7::UpdateOverlayDisplay 메소드는, 현시점에서는 이행되어 있지 않다.

HRESULT UpdateOverlayDisplay(
  DWORD dwFlags
);

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::AddOverlayDirtyRect


IDirectDrawSurface7::UpdateOverlayZOrder

IDirectDrawSurface7::UpdateOverlayZOrder 메소드는, 오버레이의 z 오더를 설정한다.

HRESULT UpdateOverlayZOrder(
  DWORD dwFlags,
  LPDIRECTDRAWSURFACE7 lpDDSReference
);

파라미터

dwFlags
이하의 플래그 가운데, 1 개의 값을 취한다.
DDOVERZ_INSERTINBACKOF
이 오버레이를 오버레이 체인의 참조 오버레이의 뒤로 삽입한다.
DDOVERZ_INSERTINFRONTOF
이 오버레이를 오버레이 체인의 참조 오버레이의 전에 삽입한다.
DDOVERZ_MOVEBACKWARD
이 오버레이를 오버레이 체인의 1 개 뒤로 이동한다.
DDOVERZ_MOVEFORWARD
이 오버레이를 오버레이 체인의 1 개전으로 이동한다.
DDOVERZ_SENDTOBACK
이 오버레이를 오버레이 체인의 뒤로 이동한다.
DDOVERZ_SENDTOFRONT
이 오버레이를 오버레이 체인의 전으로 이동한다.
lpDDSReference
오버레이 체인의 상대 위치로서 사용되는 DirectDraw 표면의 IDirectDrawSurface7 구조체의 주소. 이 파라미터는, DDOVERZ_INSERTINBACKOF 및 DDOVERZ_INSERTINFRONTOF 만의 위해(때문에) 필요하게 된다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTAOVERLAYSURFACE

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.

참조

IDirectDrawSurface7::EnumOverlayZOrders


IDirectDrawVideoPort

어플리케이션은, 라이브 비디오 데이터를 하드웨어 비디오 포트로부터 DirectDraw 표면에 채널 하기 위해서,IDirectDrawVideoPort 인터페이스의 메소드를 이용한다. 여기에서는, 이 인터페이스의 메소드의 레퍼런스를 제공한다. 개념의 개요에 대해서는, 「비디오 포트」를 참조할것.

IDirectDrawVideoPort 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

컬러 컨트롤 | GetColorControls
 | SetColorControls
필드와 신호 | GetFieldPolarity
 | GetVideoSignalStatus
플립핑 | Flip
 | SetTargetSurface
포맷 | GetInputFormats
 | GetOutputFormats
타이밍과 동기 | GetVideoLine
 | WaitForSync
비디오 컨트롤 | StartVideo
 | StopVideo
 | UpdateVideo
줌 계수 | GetBandwidthInfo

모든 COM 인터페이스와 같이,IDirectDrawVideoPort 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTDRAWVIDEOPORT 데이터형을 사용 하면,IDirectDrawVideoPort 인터페이스에의 포인터를 포함한 변수를 선언할 수 있다. dvp.h 헤더 파일은, 다음의 코드로 LPDIRECTDRAWVIDEOPORT 를 선언한다.

typedef struct IDirectDrawVideoPort    FAR *LPDIRECTDRAWVIDEOPORT;

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


IDirectDrawVideoPort::Flip

IDirectDrawVideoPort::Flip 메소드는, 새로운 표면에 비디오의 다음의 프레임을 기술하도록(듯이) DirectDrawVideoPort 오브젝트에 지시한다.

HRESULT Flip(
  LPDIRECTDRAWSURFACE lpDDSurface,
  DWORD dwFlags
);

파라미터

lpDDSurface
비디오의 다음의 프레임을 받는 표면의 IDirectDrawSurface 인터페이스의 주소. 이 파라미터에 NULL 를 설정 하면, 표면이 Attach 된 순서에 플립핑 체인의 표면으로부터 순환한다.
dwFlags
플립 옵션 플래그. 이하의 플래그 가운데, 몇개의 값을 취한다.
DDVPFLIP_VIDEO
지정한 표면은 보통의 비디오 데이터를 받는다.
DDVPFLIP_VBI
지정한 표면이 수직귀선소거 간격내의 데이터만을 받는다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는,티어링을 막기 위해서(때문에) 사용할 수 있다. IDirectDrawVideoPort::Flip 에의 호출은 비동기이다. 플립 처리는, 비디오 신호의 수직귀선소거와 항상 동기 된다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


IDirectDrawVideoPort::GetBandwidthInfo

IDirectDrawVideoPort::GetBandwidthInfo 메소드는, 요구되는 최소 오버레이 줌 계수와 제공되는 출력 픽셀 포맷을 사용하는 비디오 포트의 디바이스 제한을 취득한다.

HRESULT GetBandwidthInfo(
  LPDDPIXELFORMAT lpddpfFormat,
  DWORD dwWidth,
  DWORD dwHeight,
  DWORD dwFlags,
  LPDDVIDEOPORTBANDWIDTH lpBandwidth
);

파라미터

lpddpfFormat
대역폭 정보를 취득하기 위한 출력 픽셀 포맷을 기술하는 DDPIXELFORMAT 구조체의 주소.
dwWidth,dwHeight
오버레이 또는 비디오 데이터의 넓이. 이러한 파라미터는,dwFlags 파라미터로 지정하는 값에 의존한다.
dwFlags
어떻게 메소드가 dwWidth 및 dwHeight 파라미터를 판단하는지를 나타내는 플래그. 이하의 플래그 가운데, 몇개의 값을 취한다.
DDVPB_OVERLAY
dwWidth 및 dwHeight 파라미터는, 전송원오버레이 표면의 사이즈를 나타낸다. 비디오 포트가 오버레이 전송원사이즈에 의존하는 경우, 이 플래그를 사용한다.
DDVPB_TYPE
dwWidth 및 dwHeight 파라미터는, 설정되지 않는다. 메소드는, 관련지을 수 있었던 DDVIDEOPORTBANDWIDTH 구조체의 dwCaps 멤버로 디바이스의 의존 타입을 취득한다. 최초로 이 메소드를 호출하는 경우, 이 플래그를 사용한다.
DDVPB_VIDEOPORT
dwWidth 및 dwHeight 파라미터는, 비디오 포트가 frame buffer에 기입하는 비디오 데이터의 프레스 케일 사이즈를 나타낸다. 비디오 포트가 오버레이 줌 계수에 의존하는 경우, 이 플래그를 사용한다.
lpBandwidth
취득된 대역폭 및 디바이스 정보를 저장 하는 DDVIDEOPORTBANDWIDTH 구조체의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는 보통 2 회 불려 간다. 최초로 호출하는 경우,dwFlags 파라미터에 DDVPB_TYPE 플래그를 지정해, 디바이스의 오버레이 의존 타입에 대한 정보를 취득한다. DDVPB_VIDEOPORT 또는 DDVPB_OVERLAY 플래그를 사용한 연속하는 호출은, 디바이스의 의존 타입을 고려해 판단되지 않으면 안 된다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


IDirectDrawVideoPort::GetColorControls

IDirectDrawVideoPort::GetColorControls 메소드는, 비디오 포트에 관련지을 수 있었던 현재의 컬러 컨트롤 설정을 돌려준다.

HRESULT GetColorControls(
  LPDDCOLORCONTROL lpColorControl
);

파라미터

lpColorControl
비디오 포트의 컬러 컨트롤에 있어서의 현재의 설정을 저장 하는 DDCOLORCONTROL 구조체의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

주의

DDCOLORCONTROL 구조체의 dwFlags 멤버는, 지원 되는 컬러 컨트롤 옵션을 나타낸다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


IDirectDrawVideoPort::GetFieldPolarity

IDirectDrawVideoPort::GetFieldPolarity 메소드는, 비디오 필드의 극성을 취득한다.

HRESULT GetFieldPolarity(
  LPBOOL lpbFieldPolarity
);

파라미터

lpbFieldPolarity
현재의 필드극성을 나타내기 위해서(때문에) 설정하는 변수의 주소. 현재의 비디오 필드가 인터 레이스 비디오 신호의 짝수 필드인 경우, 이 값을 TRUE 로 설정한다. 그 외의 경우는, 이 값을 FALSE 로 설정한다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DDERR_VIDEONOTACTIVE

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


IDirectDrawVideoPort::GetInputFormats

IDirectDrawVideoPort::GetInputFormats 메소드는, DirectDrawVideoPort 오브젝트가 지원 하는 입력 포맷을 취득한다.

HRESULT GetInputFormats(
  LPDWORD lpNumFormats,
  LPDDPIXELFORMAT lpFormats,
  DWORD dwFlags
);

파라미터

lpNumFormats
lpFormats 의 배열로 보관 유지할 수 있는 엔트리수를 포함한 변수의 주소. 이 수가 전코드수보다 적은 경우, 메소드는 적합하는 모든 코드를 배열에 저장 해, 전코드수를 나타내도록(듯이) lpNumFormats 의 값을 설정해, DDERR_MOREDATA 을 돌려준다.
lpFormats
이 DirectDrawVideoPort 오브젝트에 의해 지원 되는 입력 정보를 저장 하는 DDPIXELFORMAT 구조체의 배열의 주소. 이 파라미터가 NULL 의 경우, 메소드는 lpNumFormats 를 지원 되는 포맷수로 설정해, DD_OK 를 돌려준다.
dwFlags
비디오 신호의 어느 부분에 대해서 포맷을 열거하는지를 지정하는 플래그. 이하의 플래그 가운데, 몇개의 값을 취한다.
DDVPFORMAT_VIDEO
비디오 데이터의 포맷을 돌려준다.
DDVPFORMAT_VBI
VBI 데이터의 플래그를 돌려준다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_MOREDATA

주의

이 메소드는, 지원 되는 포맷수를 돌려주기 위해서(때문에) 사용할 수도 있다. 이 경우는,lpFormats 파라미터를 NULL 로 설정한다. 메소드가 돌아가면(자),lpNumFormats 의 변수에는 지원 되는 입력 포맷의 합계수가 포함된다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


IDirectDrawVideoPort::GetOutputFormats

IDirectDrawVideoPort::GetOutputFormats 메소드는, DirectDrawVideoPort 오브젝트가 지정한 입력 포맷에 대해서 지원 하는, 출력 포맷의 리스트를 취득한다.

HRESULT GetOutputFormats(
  LPDDPIXELFORMAT lpInputFormat,
  LPDWORD lpNumFormats,
  LPDDPIXELFORMAT lpFormats,
  DWORD dwFlags
);

파라미터

lpInputFormat
변환 정보를 요구하는 입력 포맷을 기술하는 DDPIXELFORMAT 구조체의 주소.
lpNumFormats
lpFromats 의 배열로 보관 유지할 수 있는 엔트리수를 포함한 변수의 주소. 이 수가 전코드수보다 적은 경우, 메소드는 적합하는 모든 코드를 배열에 저장 해, 전코드수를 나타내도록(듯이) lpNumFormats 의 값을 설정해, DDERR_MOREDATA 을 돌려준다.
lpFormats
이 DirectDrawVideoPort 오브젝트에 의해 지원 되는 출력 포맷을 저장 하는 DDPIXELFORMAT 구조체의 주소. 이 파라미터가 NULL 의 경우, 메소드는 지원 되는 포맷수에 lpNumFormats 를 설정해, DD_OK 를 돌려준다.
dwFlags
비디오 신호의 어느 부분에 대해서 포맷을 열거하는지를 지정하는 플래그. 이하의 플래그 가운데, 몇개의 값을 취한다.
DDVPFORMAT_VIDEO
비디오 데이터의 포맷을 돌려준다.
DDVPFORMAT_VBI
VBI 데이터의 플래그를 돌려준다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_MOREDATA

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


IDirectDrawVideoPort::GetVideoLine

IDirectDrawVideoPort::GetVideoLine 메소드는, frame buffer에 현재 쓰기중의 비디오 라인을 취득한다.

HRESULT GetVideoLine(
  LPDWORD lpdwLine
);

파라미터

lpdwLine
frame buffer에 현재 기록중의 비디오 라인을 나타내는 값을 저장 하는 변수의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DDERR_VERTICALBLANKINPROGRESS
DDERR_VIDEONOTACTIVE

주의

이 메소드가 취득하는 값은, 프레스 케이 링이 발생하기 전에, 필드의 높이를 취득하는 기술된 진정한 비디오 라인을 반영한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


IDirectDrawVideoPort::GetVideoSignalStatus

IDirectDrawVideoPort::GetVideoSignalStatus 메소드는, 현재 비디오 포트에 존재하는 비디오 신호의 스테이터스를 취득한다.

HRESULT GetVideoSignalStatus(
  LPDWORD lpdwStatus
);

파라미터

lpdwStatus
비디오 포트에서의 비디오 신호의 질을 나타내는 반환값을 포함한 변수의 주소. 값은, 이하의 코드의 쳐 몇개의 값으로 설정된다.
DDVPSQ_NOSIGNAL
비디오 포트에는 비디오 신호가 존재하지 않는다.
DDVPSQ_SIGNALOK
비디오 포트에 유효한 비디오 신호가 존재한다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


IDirectDrawVideoPort::SetColorControls

IDirectDrawVideoPort::SetColorControls 메소드는, 비디오 포트에 관련지을 수 있었던 컬러 컨트롤 설정을 설정한다.

HRESULT SetColorControls(
  LPDDCOLORCONTROL lpColorControl
);

파라미터

lpColorControl
비디오 포트에 적용되는 새로운 컬러 컨트롤 설정을 포함한 DDCOLORCONTROL 구조체의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


IDirectDrawVideoPort::SetTargetSurface

IDirectDrawVideoPort::SetTargetSurface 메소드는, 라이브 비디오 데이터 및/또는 수직귀선소거 간격 데이터의 스트림을 받는 DirectDraw 표면 오브젝트를 설정한다.

HRESULT SetTargetSurface(
  LPDIRECTDRAWSURFACE lpDDSurface,
  DWORD dwFlags
);

파라미터

lpDDSurface
비디오 데이터를 받는 DirectDrawSurface 오브젝트의 주소.
dwFlags
타겟 표면의 타입을 지정하는 값. 이하의 플래그 가운데, 1 개의 값을 취한다.
DDVPTARGET_VIDEO
지정하는 표면은, 이 목적을 위해서(때문에) 다른 표면이 Attach되어 있지 않으면, 보통의 비디오 데이터와 수직귀선소거 간격 데이터를 받는다.
DDVPTARGET_VBI
지정하는 표면은, 수직귀선소거 간격내의 데이터를 받는다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.

참조

IDirectDrawVideoPort::StartVideo ,IDirectDrawVideoPort::StopVideo ,IDirectDrawVideoPort::UpdateVideo


IDirectDrawVideoPort::StartVideo

IDirectDrawVideoPort::StartVideo 메소드는, 하드웨어 비디오 포트를 이용 가능하게 해, 현재 지정되고 있는 표면에 비디오 데이터의 플로우를 시작 한다.

HRESULT StartVideo(
  LPDDVIDEOPORTINFO lpVideoInfo
);

파라미터

lpVideoInfo
DDVIDEOPORTINFO 구조체에의 포인터의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.

참조

IDirectDrawVideoPort::SetTargetSurface ,IDirectDrawVideoPort::StopVideo ,IDirectDrawVideoPort::UpdateVideo


IDirectDrawVideoPort::StopVideo

IDirectDrawVideoPort::StopVideo 메소드는, frame buffer에의 비디오 포트 데이터의 플로우를 멈춘다.

HRESULT StopVideo();

파라미터

없음.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 메소드는 DDERR_INVALIDOBJECT 를 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.

참조

IDirectDrawVideoPort::SetTargetSurface , IIDirectDrawVideoPort::StartVideo ,IDirectDrawVideoPort::UpdateVideo


IDirectDrawVideoPort::UpdateVideo

IDirectDrawVideoPort::UpdateVideo 메소드는, 비디오 포트로부터 DirectDrawSurface 오브젝트까지의 비디오 데이터의 플로우를 제어하는 파라미터를 갱신한다.

HRESULT UpdateVideo(
  LPDDVIDEOPORTINFO lpVideoInfo
);

파라미터

lpVideoInfo
비디오 전송 파라미터를 기술하는 DDVIDEOPORTINFO 구조체의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.

참조

IDirectDrawVideoPort::SetTargetSurface ,IDirectDrawVideoPort::StartVideo ,IDirectDrawVideoPort::StopVideo


IDirectDrawVideoPort::WaitForSync

IDirectDrawVideoPort::WaitForSync 메소드는, VSYNC, 또는 주어진 주사선을 그릴 때까지 대기한다.

HRESULT WaitForSync(
  DWORD dwFlags,
  DWORD dwLine,
  DWORD dwTimeout
);

파라미터

dwFlags
메소드가 비디오 VSYNC 또는 지정된 라인 번호를 어떻게 대기하는지를 지정하는 플래그. 이하의 플래그 가운데, 몇개의 값을 취한다.
DDVPWAIT_BEGIN
수직귀선소거 간격의 시작시에 돌려준다.
DDVPWAIT_END
수직귀선소거 간격의 종료시에 돌려준다.
DDVPWAIT_LINE
비디오 카운터가,dwLine 파라미터로 지정된 라인에 이를까 넘을 때 돌려준다.
dwLine
프레스 케이 링의 전에, 필드의 높이를 기준으로 하고 있고 개메소드가 돌아갈까를 결정하는 비디오 라인. dwFlags 파라미터가 DDVPWAIT_BEGIN 또는 DDVPWAIT_END 로 설정되어 있는 경우, 이 파라미터는 무시된다.
dwTimeout
타임 아웃 하기까지, 메소드가 다음의 비디오 수직귀선소거를 대기하는 시간 (밀리 세컨드). 이 파라미터가 0 의 경우, 메소드는 DDVIDEOPORTDESC 의 dwMicrosecondsPerField 멤버로 지정된 값의 3 배의 시간 대기한다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DDERR_VIDEONOTACTIVE
DDERR_WASSTILLDRAWING

주의

이 메소드는, 호출측이 수직귀선소거 간격, 또는 비디오 데이터의 임의의 라인과 동기 하는 것을 돕는다. 이 메소드는, 비디오 VSYNC 가 발생하는지, 또는 비디오 라인 카운터가 지정의 라인 번호에 일치할 때까지 thread의 호출을 블록 한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


함수

여기에서는, 이하에 나타내는 DirectDraw 글로벌 함수에 대해 설명한다.

  • DirectDrawCreate
  • DirectDrawCreateEx
  • DirectDrawCreateClipper
  • DirectDrawEnumerate
  • DirectDrawEnumerateEx


DirectDrawCreate

DirectDrawCreate 함수는, DirectDraw 오브젝트의 인스턴스를 생성 한다. 이 함수로 생성 한 DirectDraw 오브젝트에서는, 최신의 Direct3D 인터페이스 세트는 지원 되지 않는다. Direct3D 의 신기능을 공개할 수 있는 DirectDraw 오브젝트를 생성 하려면 ,DirectDrawCreateEx 함수를 사용한다.

HRESULT WINAPI DirectDrawCreate(
  GUID FAR *lpGUID,
  LPDIRECTDRAW FAR *lplpDD,
  IUnknown FAR *pUnkOuter
);

파라미터

lpGUID
생성 되는 드라이버를 나타내는 글로벌 유니크 식별자 (GUID)의 주소. 액티브 디스플레이 드라이버를 나타내려면 , 이 파라미터를 NULL 로 한다. 혹은, 디버그를 위해서(때문에) 디스플레이 드라이버의 동작을 제어하려면 , 이하의 플래그의 1 개를 건네줄 수가 있다.
DDCREATE_EMULATIONONLY
DirectDraw 오브젝트는, 모든 기능에 에뮬레이션을 사용한다. 즉, 하드웨어 지원 기능은 이용하지 않는다.
DDCREATE_HARDWAREONLY
DirectDraw 오브젝트는, 하드웨어에 의해 지원되어 있지 않은 기능을 에뮬레이트 하지 않는다. 지원되어 있지 않은 기능을 요구하는 메소드를 호출하려고 하면 실패해,DDERR_UNSUPPORTED 가 돌려주어진다.
lplpDD
호출이 성공했을 경우에, 유효한 IDirectDraw 인터페이스 포인터로 설정하는 변수의 주소.
pUnkOuter
COM 처리 기능과의 장래적인 호환을 위해서(때문에) 있다. 다만, 현시점에서는, 이 파라미터를 NULL 로 설정하지 않으면 이 메소드는 에러를 돌려준다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_DIRECTDRAWALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDDIRECTDRAWGUID
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW
DDERR_OUTOFMEMORY

주의

이 함수는, DirectDraw 오브젝트를 초기화하려고 한다. 호출이 성공하면(자), 오브젝트에의 포인터를 설정한다.

멀티 모니터의 시스템으로 lpGUID 에 NULL 를 지정 하면, 표준 협조 레벨이 설정되어 있는 경우에, DirectDraw 는 에뮬레이션 모드로 실행한다. 이러한 시스템으로 하드웨어 가속기를 사용하려면 , 디바이스의 GUID 를 지정한다. 상세한 것에 대하여는, 「MultiMon 시스템의 디바이스와 가속기」를 참조할것.

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


DirectDrawCreateEx

DirectDrawCreateEx 함수는, 최신의 Direct3D 인터페이스 세트를 지원 하는 DirectDraw 오브젝트의 인스턴스를 생성 한다. DirectX 7.0 으로 Direct3D 의 신기능을 사용하려면 , 이 함수로 DirectDraw 오브젝트를 생성 한다. DirectDraw 및 Direct3D 간의 관계의 상세한 것에 대하여는, 「DirectDraw 오브젝트와 Direct3D 」 및 「Direct3D 에의 액세스」를 참조할것.

HRESULT WINAPI DirectDrawCreateEx(
  GUID FAR *lpGUID,
  LPVOID *lplpDD,
  REFIID iid,
  IUnknown FAR *pUnkOuter
);

파라미터

lpGUID
생성 되는 드라이버를 나타내는 글로벌 유니크 식별자 (GUID)의 주소. 액티브 디스플레이 드라이버를 나타내려면 , 이 파라미터를 NULL 로 한다. 또, 디버그를 위해서(때문에) 디스플레이 드라이버의 동작을 제어하려면 , 이하의 플래그의 어느쪽이든을 건네줄 수가 있다.
DDCREATE_EMULATIONONLY
DirectDraw 오브젝트는, 모든 기능에 에뮬레이션을 사용한다. 즉, 하드웨어 지원 기능은 이용하지 않는다.
DDCREATE_HARDWAREONLY
DirectDraw 오브젝트는, 하드웨어에 의해 지원되어 있지 않은 기능을 에뮬레이트 하지 않는다. 지원되어 있지 않은 기능을 요구하는 메소드를 호출하려고 하면 실패해,DDERR_UNSUPPORTED 가 돌려주어진다.
lplpDD
호출이 성공했을 경우에, 유효한 IDirectDraw7 인터페이스 포인터로 설정하는 변수의 주소.
iid
이 파라미터는 IID_IDirectDraw7 로 설정해야 한다. 그 외의 인터페이스를 지정했을 경우, 이 함수는 실패해, DDERR_INVALIDPARAMS 를 돌려준다.
pUnkOuter
COM 처리 기능과의 장래적인 호환을 위해서(때문에) 있다. 다만, 현시점에서는, 이 파라미터를 NULL 로 설정하지 않으면 이 메소드는 에러를 돌려준다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_DIRECTDRAWALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDDIRECTDRAWGUID
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW
DDERR_OUTOFMEMORY

주의

이 함수는, DirectDraw 오브젝트를 초기화하려고 한다. 호출이 성공하면(자), 오브젝트에의 포인터를 설정한다.

멀티 모니터의 시스템으로 lpGUID 에 NULL 를 지정 하면, 표준 협조 레벨이 설정되어 있는 경우에, DirectDraw 오브젝트는 에뮬레이션 모드로 실행한다. 이러한 시스템으로 하드웨어 가속기를 사용하려면 , 디바이스의 GUID 를 지정한다. 상세한 것에 대하여는, 「MultiMon 시스템의 디바이스와 가속기」를 참조할것.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.


DirectDrawCreateClipper

DirectDrawCreateClipper 함수는, DirectDraw 오브젝트에 관련지을 수 없는 DirectDrawClipper 오브젝트의 인스턴스를 생성 한다.

HRESULT WINAPI DirectDrawCreateClipper(
  DWORD dwFlags,
  LPDIRECTDRAWCLIPPER FAR *lplpDDClipper,
  IUnknown FAR *pUnkOuter
);

파라미터

dwFlags
현시점에서는 미사용이므로 0 을 설정해 둔다.
lplpDDClipper
새로운 DirectDrawClipper 오브젝트의 주소를 저장 하는 포인터의 주소.
pUnkOuter
COM 처리 기능과의 장래적인 호환을 위해서(때문에) 있다. 다만, 현시점에서는, 이 파라미터를 NULL 로 설정하지 않으면 이 메소드는 에러를 돌려준다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면, 이하의 에러값의 어느쪽이든을 돌려준다.

DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

주의

이 함수는, 모든 DirectDraw 오브젝트를 생성 하기 전에 호출할 수가 있다. DirectDraw 오브젝트는 이러한 DirectDrawClipper 오브젝트를 소유하지 않기 때문에, 어플리케이션의 오브젝트가 릴리즈 되어도 자동적으로 릴리즈 될 것은 없다. 어플리케이션으로 명시적으로 DirectDrawClipper 오브젝트를 릴리즈 하지 않는 경우는, 어플리케이션의 종료시에 DirectDraw 가 그러한 오브젝트를 릴리즈 한다.

특정의 DirectDraw 오브젝트에 의해 소유되는 DirectDrawClipper 오브젝트를 생성 하려면 ,IDirectDraw7::CreateClipper 메소드를 사용한다.

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.

참조

IDirectDraw7::CreateClipper


DirectDrawEnumerate

이 함수는,DirectDrawEnumerateEx 함수로 옮겨놓을 수 있다.

DirectDrawEnumerate 함수는, 시스템에 인스톨 되고 있는 프라이머리 DirectDraw 디스플레이 디바이스, 및 비디스플레이 디바이스 (2D 능력이 없는 3D 액셀러레이트등)를 열거한다. NULL 엔트리는, GDI 로 공유되는 프라이머리 디스플레이 디바이스를 항상 식별한다.

HRESULT WINAPI DirectDrawEnumerate(
  LPDDENUMCALLBACK lpCallback,
  LPVOID lpContext
);

파라미터

lpCallback
열거되는 각각의 DirectDraw 로 유효한 하드웨어 추상 계층 (HAL)의 기술로 불려 가는 DDEnumCallback 함수의 주소.
lpContext
열거 콜백 함수를 호출할 때 마다 건네받는 어플리케이션 정의 문맥의 주소.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면,DDERR_INVALIDPARAMS 를 돌려준다.

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.

참조

DirectDrawEnumerateEx


DirectDrawEnumerateEx

DirectDrawEnumerateEx 함수는, 시스템상에 인스톨 된 모든 DirectDraw 디바이스를 열거한다. NULL 엔트리는, GDI 로 공유되는 프라이머리 디스플레이 디바이스를 항상 가리킨다.

HRESULT WINAPI DirectDrawEnumerateEx(
  LPDDENUMCALLBACKEX lpCallback,
  LPVOID lpContext,
  DWORD  dwFlags
);

파라미터

lpCallback
열거되는 각각의 DirectDraw 로 유효한 하드웨어 추상 계층 (HAL)의 기술로 불려 가는 DDEnumCallbackEx 함수의 주소.
lpContext
열거 콜백 함수를 호출할 때 마다 건네받는 어플리케이션 정의값의 주소.
dwFlags
열거 유효 범위를 지정하는 플래그. 이 파라미터는, 0 또는 이하의 플래그의 편성으로 한다. 파라미터의 값을 0 으로 하면(자), 함수는 프라이머리 디스플레이 디바이스만 열거한다.
DDENUM_ATTACHEDSECONDARYDEVICES
함수는, 프라이머리 디바이스, 및 데스크탑에 Attach 되는 디스플레이 디바이스를 열거한다.
DDENUM_DETACHEDSECONDARYDEVICES
함수는, 프라이머리 디바이스, 및 데스크탑에 Attach 되지 않는 디스플레이 디바이스를 열거한다.
DDENUM_NONDISPLAYDEVICES
함수는, 프라이머리 디바이스, 및 2D 능력이 없는 3D 가속기등의 비디스플레이 디바이스를 열거한다.

반환값

성공하면, DD_OK 를 돌려준다.

실패하면,DDERR_INVALIDPARAMS 를 돌려준다.

주의

멀티 모니터의 시스템에서는, 이 메소드는 멀티 디스플레이 디바이스를 열거한다. 상세 정보는, 「멀티 모니터 시스템」을 참조할것.

Windows 98 에서는, 이 함수는 DirectX 5.0 이후의 버젼이 지원 된다. 다른 operating system 모두에서는, DirectX 6.0 이 필요하다. "DirectDrawEnumerateExA" (ANSI), 또는 "DirectDrawEnumerateExW" (Unicode) 처리 명문자열로 GetProcAddress Win32 함수를 호출하는 것으로, ddraw.dll 동적 링크 라이브러리로부터 DirectDrawEnumerateEx 함수의 주소를 취득할 수 있다. GetProcAddress 가 실패했을 경우는, 인스톨 되고 있는 operating system의 버젼으로 멀티 모니터가 지원되어 있지 않다. 상세한 것에 대하여는, 「MultiMon 시스템에 있어서의 디바이스의 열거」를 참조할것.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : ddraw.lib 을 사용.
Unicode : Windows NT/2000 위에의 Unicode 및 ANSI 버젼으로서 이행 된다.


콜백 함수

여기에서는, DirectDraw 와 함께 사용되는 이하의 콜백 함수에 대해 설명한다.

  • DDEnumCallback
  • DDEnumCallbackEx
  • EnumModesCallback
  • EnumModesCallback2
  • EnumSurfacesCallback
  • EnumSurfacesCallback2
  • EnumSurfacesCallback7
  • EnumVideoCallback


DDEnumCallback

DDEnumCallback 함수는,DirectDrawEnumerate 함수의 어플리케이션 정의 콜백 함수이다.

BOOL WINAPI DDEnumCallback(
  GUID FAR *lpGUID,
  LPSTR  lpDriverDescription,
  LPSTR  lpDriverName,
  LPVOID lpContext
);

파라미터

lpGUID
DirectDraw 오브젝트의 유니크 식별자의 주소.
lpDriverDescription
드라이버 기술을 포함한 캐릭터 라인의 주소.
lpDriverName
드라이버명을 포함한 캐릭터 라인의 주소.
lpContext
함수를 호출할 때 마다 콜백 함수에게 건네지는 어플리케이션 정의 구조체의 주소.

반환값

콜백 함수는, 제로 이외의 값을 돌려주어 열거를 속행한다.

콜백 함수는, 제로를 돌려주어 열거를 정지한다.

주의

LPDDENUMCALLBACK 데이터형을 사용 하면, 이 콜백 함수에의 포인터를 포함한 변수를 선언할 수 있다.

UNICODE 가 정의되면(자), 캐릭터 라인값은 LPSTR 는 아니고 LPWSTR 형으로서 돌려주어진다.

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : 유저 정의.


DDEnumCallbackEx

DDEnumCallbackEx 함수는,DirectDrawEnumerateEx 함수의 어플리케이션 정의 콜백 함수이다.

BOOL WINAPI DDEnumCallbackEx(
  GUID FAR *lpGUID,
  LPSTR     lpDriverDescription,
  LPSTR     lpDriverName,
  LPVOID    lpContext,
  HMONITOR  hm
);

파라미터

lpGUID
DirectDraw 오브젝트의 유니크 식별자의 주소.
lpDriverDescription
드라이버 기술을 포함한 캐릭터 라인의 주소.
lpDriverName
드라이버명을 포함한 캐릭터 라인의 주소.
lpContext
함수를 호출할 때 마다 콜백 함수에게 건네지는 어플리케이션 정의 구조체의 주소.
hm
열거하는 DirectDraw 오브젝트에 관련지을 수 있었던 모니터에의 핸들. 열거하는 DirectDraw 오브젝트가 프라이머리 디바이스, 비디스플레이 디바이스 (2D 능력이 없는 3D 가속기 등), 또는 데스크탑에 Attach 되지 않는 디바이스인 경우, 이 파라미터는 NULL 가 된다.

반환값

콜백 함수는, 제로 이외의 값을 돌려주어 열거를 속행한다.

콜백 함수는, 제로를 돌려주어 열거를 정지한다.

주의

DirectDrawEnumerateEx 함수가 완료 하면, GUID 에의 포인터는 유효한 것은 없어진다. 포인터는 아니고, GUID 구조체 그 자체의 카피를 보존해야 한다. 그렇지 않으면 DirectDrawCreate 함수가 실패한다.

LPDDENUMCALLBACKEX 데이터형을 사용 하면, 이 콜백 함수에의 포인터를 포함한 변수를 선언할 수 있다.

UNICODE 가 정의되면(자), 캐릭터 라인값은 LPSTR 는 아니고 LPWSTR 형으로서 돌려주어진다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : 유저 정의.

참조

MultiMon 시스템에 있어서의 디바이스의 열거,멀티 모니터 시스템


EnumModesCallback

EnumModesCallback 함수는,IDirectDraw3::EnumDisplayModes 함수를 위한 어플리케이션으로 정의되는 콜백 함수이다. 또, 이전의 인터페이스에 대응한다.

이 콜백 함수는,IDirectDraw7::EnumDisplayModes 메소드와와도 사용되는 EnumModesCallback2 함수에 의해 옮겨놓을 수 있다.

HRESULT WINAPI EnumModesCallback(
  LPDDSURFACEDESC lpDDSurfaceDesc,
  LPVOID lpContext
);

파라미터

lpDDSurfaceDesc
모니터 주파수 및 생성 하는 모드를 제공하는 read 전용의 DDSURFACEDESC 구조체의 주소.
lpContext
함수를 호출할 때 마다 콜백 함수에게 건네지는 어플리케이션 정의 구조체의 주소.

반환값

콜백 함수는, DDENUMRET_OK 를 돌려주어 열거를 속행한다.

콜백 함수는, DDENUMRET_CANCEL 를 돌려주어 열거를 정지한다.

주의

LPDDENUMMODESCALLBACK 데이터형을 사용 하면, 이 콜백 함수에의 포인터를 포함한 변수를 선언할 수 있다.

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : 유저 정의.


EnumModesCallback2

EnumModesCallback2 함수는,IDirectDraw7::EnumDisplayModes 메소드의 어플리케이션 정의 콜백 함수이다.

HRESULT WINAPI EnumModesCallback2(
  LPDDSURFACEDESC2 lpDDSurfaceDesc,
  LPVOID lpContext
);

파라미터

lpDDSurfaceDesc
모니터 주파수 및 생성 하는 모드를 제공하는 read 전용의 DDSURFACEDESC2 구조체의 주소.
lpContext
함수를 호출할 때 마다 콜백 함수에게 건네지는 어플리케이션 정의 구조체의 주소.

반환값

콜백 함수는, DDENUMRET_OK 를 돌려주어 열거를 속행한다.

콜백 함수는, DDENUMRET_CANCEL 를 돌려주어 열거를 정지한다.

주의

LPDDENUMMODESCALLBACK2 데이터형을 사용 하면, 이 콜백 함수에의 포인터를 포함한 변수를 선언할 수 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : 유저 정의.


EnumSurfacesCallback

EnumSurfacesCallback 함수는,IDirectDraw2::EnumSurfaces,IDirectDrawSurface3::EnumAttachedSurfaces, 및 IDirectDrawSurface3::EnumOverlayZOrders 메소드 (그리고, 초기의 인터페이스 버젼)를 위한 어플리케이션으로 정의되는 콜백 함수이다.

HRESULT WINAPI EnumSurfacesCallback(
  LPDIRECTDRAWSURFACE lpDDSurface,
  LPDDSURFACEDESC lpDDSurfaceDesc,
  LPVOID lpContext
);

파라미터

lpDDSurface
Attach 되는 표면에 대한 IDirectDrawSurface 인터페이스의 주소.
lpDDSurfaceDesc
Attach 되는 표면을 기술하는 DDSURFACEDESC 구조체의 주소.
lpContext
함수를 호출할 때 마다 콜백 함수에게 건네지는 어플리케이션 정의 구조체의 주소.

반환값

콜백 함수는, DDENUMRET_OK 를 돌려주어 열거를 속행한다.

콜백 함수는, DDENUMRET_CANCEL 를 돌려주어 열거를 정지한다.

주의

LPDDENUMSURFACESCALLBACK 데이터형을 사용 하면, 이 콜백 함수에의 포인터를 포함한 변수를 선언할 수 있다.

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : 유저 정의.


EnumSurfacesCallback2

EnumSurfacesCallback2 함수는,IDirectDrawSurface4::EnumAttachedSurfaces 및 IDirectDrawSurface4::EnumOverlayZOrders 메소드의 어플리케이션 정의 콜백 함수이다.

HRESULT WINAPI EnumSurfacesCallback2(
  LPDIRECTDRAWSURFACE7 lpDDSurface,
  LPDDSURFACEDESC2 lpDDSurfaceDesc,
  LPVOID lpContext
);

파라미터

lpDDSurface
Attach 되는 표면의 IDirectDrawSurface4 인터페이스의 주소.
lpDDSurfaceDesc
Attach 되는 표면을 기술하는 DDSURFACEDESC2 구조체의 주소.
lpContext
함수를 호출할 때 마다 콜백 함수에게 건네지는 어플리케이션 정의 구조체의 주소.

반환값

콜백 함수는, DDENUMRET_OK 를 돌려주어 열거를 속행한다.

콜백 함수는, DDENUMRET_CANCEL 를 돌려주어 열거를 정지한다.

주의

LPDDENUMSURFACESCALLBACK2 데이터형을 사용 하면, 이 콜백 함수에의 포인터를 포함한 변수를 선언할 수 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : 유저 정의.


EnumSurfacesCallback7

EnumSurfacesCallback7 함수는,IDirectDrawSurface7::EnumAttachedSurfaces 및 IDirectDrawSurface7::EnumOverlayZOrders 메소드의 어플리케이션 정의 콜백 함수이다.

HRESULT WINAPI EnumSurfacesCallback7(
  LPDIRECTDRAWSURFACE7 lpDDSurface,
  LPDDSURFACEDESC2 lpDDSurfaceDesc,
  LPVOID lpContext
);

파라미터

lpDDSurface
Attach 되는 표면의 IDirectDrawSurface7 인터페이스의 주소.
lpDDSurfaceDesc
Attach 되는 표면을 기술하는 DDSURFACEDESC2 구조체의 주소.
lpContext
함수를 호출할 때 마다 콜백 함수에게 건네지는 어플리케이션 정의 구조체의 주소.

반환값

콜백 함수는, DDENUMRET_OK 를 돌려주어 열거를 속행한다.

콜백 함수는, DDENUMRET_CANCEL 를 돌려주어 열거를 정지한다.

주의

LPDDENUMSURFACESCALLBACK7 데이터형을 사용 하면, 이 콜백 함수에의 포인터를 포함한 변수를 선언할 수 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : 유저 정의.


EnumVideoCallback

EnumVideoCallback 함수는,IDDVideoPortContainer::EnumVideoPorts 메소드의 어플리케이션 정의 콜백 함수이다.

HRESULT WINAPI EnumVideoCallback(
  LPDDVIDEOPORTCAPS lpDDVideoPortCaps,
  LPVOID lpContext
);

파라미터

lpDDVideoPortCaps
ID, 능력등의 비디오 포트 정보를 포함한 DDVIDEOPORTCAPS 구조체에의 포인터. 이 데이터는, read 전용이다.
lpContext
함수를 호출할 때 마다 멤버에게 건네지는, 호출측에서 정의된 구조체에의 포인터.

반환값

콜백 함수는, DDENUMRET_OK 를 돌려주어 열거를 속행한다.

콜백 함수는, DDENUMRET_CANCEL 를 돌려주어 열거를 정지한다.

주의

비디오 포트에 관련하는 함수는,EnumVideoCallback 함수로부터 호출할 수 없다. 이것을 호출하려고 하면 실패해,DDERR_CURRENTLYNOTAVAIL 가 돌려주어진다.

LPDDENUMVIDEOCALLBACK 데이터형을 사용 하면, 이 콜백 함수에의 포인터를 포함한 변수를 선언할 수 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.
임포트 라이브러리 : 유저 정의.


구조체

여기에서는, DirectDraw 와 함께 사용되는 이하의 구조체에 대해 설명한다.

  • DDBLTBATCH
  • DDBLTFX
  • DDCAPS
  • DDCOLORCONTROL
  • DDCOLORKEY
  • DDDEVICEIDENTIFIER2
  • DDGAMMARAMP
  • DDOVERLAYFX
  • DDPIXELFORMAT
  • DDSCAPS
  • DDSCAPS2
  • DDSURFACEDESC
  • DDSURFACEDESC2
  • DDVIDEOPORTBANDWIDTH
  • DDVIDEOPORTCAPS
  • DDVIDEOPORTCONNECT
  • DDVIDEOPORTDESC
  • DDVIDEOPORTINFO
  • DDVIDEOPORTSTATUS

주 ：모든 DirectX 구조체에 있어서의 메모리는, 사용전에 제로에 초기화된다. 또,dwSize 멤버를 포함한 모든 구조체는, 사용하기 전에 멤버를 구조체의 사이즈에 바이트 단위로 설정해야 한다. 이하의 예는, 공통의 구조체 DDCAPS 로 이러한 태스크를 실행하고 있다.

DDCAPS ddcaps; //  아직 사용 불가능

ZeroMemory(&ddcaps, sizeof(DDCAPS));
ddcaps.dwSize = sizeof(DDCAPS);

//  이것으로, 구조체가 사용 가능해진다
.
.


DDBLTBATCH

DDBLTBATCH 구조체는, 블리트 (블록 전송) 처리를 IDirectDrawSurface7::BltBatch 메소드에 건네준다.

typedef struct _DDBLTBATCH{
    LPRECT              lprDest;
    LPDIRECTDRAWSURFACE lpDDSSrc;
    LPRECT              lprSrc;
    DWORD               dwFlags;
    LPDDBLTFX           lpDDBltFx;
} DDBLTBATCH, FAR *LPDDBLTBATCH;

멤버

lprDest
블리트의 목적지를 정의하는 RECT 구조체의 주소.
lpDDSSrc
블리트의 전송원이 되는 DirectDrawSurface 오브젝트의 주소.
lprSrc
블리트의 전송원의 직사각형을 정의하는 RECT 구조체의 주소.
dwFlags
옵션 제어 플래그. 이하의 값이 정의되고 있다.
DDBLT_ALPHADEST
이 블리트에 있어서의알파 채널 로서 픽셀 포맷의 알파 정보인가, 또는 목적지 표면에 Attach 되는 알파 채널 표면의 어느쪽이든을 사용한다.
DDBLT_ALPHADESTCONSTOVERRIDE
이 블리트에 있어서의 목적지 표면의 알파 채널로서DDBLTFX 구조체의 dwAlphaDestConst 멤버를 사용한다.
DDBLT_ALPHADESTNEG
알파값이 증가하는 것에 따라, 전송원표면은 보다 투명형이 된다 (0 은 불투명).
DDBLT_ALPHADESTSURFACEOVERRIDE
이 블리트에 있어서의 목적지 표면의 알파 채널로서DDBLTFX 구조체의 lpDDSAlphaDest 멤버를 사용한다.
DDBLT_ALPHAEDGEBLEND
컬러 키색과의 경계에 있는, 화면의 엣지의 알파 채널로서DDBLTFX 구조체의 dwAlphaEdgeBlend 멤버를 사용한다.
DDBLT_ALPHASRC
이 블리트에 있어서의 알파 채널로서 픽셀 포맷의 알파 정보인가, 또는 전송원표면에 Attach 되는 알파 채널 표면의 어느쪽이든을 사용한다.
DDBLT_ALPHASRCCONSTOVERRIDE
이 블리트에 있어서의 전송원알파 채널로서DDBLTFX 구조체의 dwAlphaSrcConst 멤버를 사용한다.
DDBLT_ALPHASRCNEG
알파값이 증가하는 것에 따라, 전송원표면은 보다 투명형이 된다 (0 은 불투명).
DDBLT_ALPHASRCSURFACEOVERRIDE
이 블리트에 있어서의 알파 채널 전송원으로서DDBLTFX 구조체의 lpDDSAlphaSrc 멤버를 사용한다.
DDBLT_ASYNC
받은 순서로 퍼스트 인, 퍼스트 아웃 (FIFO) 하드웨어로부터 비동기에게 이 블리트를 처리한다. FIFO 하드웨어에 비어 영역이 없는 경우, 호출은 실패한다.
DDBLT_COLORFILL
목적지 표면 위에의 목적지 직사각형을 저장 하는 RGB 색으로서 DDBLTFX 구조체의 dwFillColor 멤버를 사용한다.
DDBLT_DDFX
이 블리트로 사용하는 이펙트를 지정하는 DDBLTFX 구조체의 dwDDFX 멤버를 사용한다.
DDBLT_DDROPS
Win32 API 의 부분이 아닌 라스터 처리 (ROPs)를 지정하는 DDBLTFX 구조체의 dwDDROP 멤버를 사용한다.
DDBLT_KEYDEST
목적지 표면에 관련지을 수 있었던컬러 키를 사용한다.
DDBLT_KEYDESTOVERRIDE
목적지 표면의 컬러 키로서DDBLTFX 구조체의 ddckDestColorkey 멤버를 사용한다.
DDBLT_KEYSRC
전송원표면에 관련지을 수 있었던 컬러 키를 사용한다.
DDBLT_KEYSRCOVERRIDE
전송원표면의 컬러 키로서DDBLTFX 구조체의 ddckSrcColorkey 멤버를 사용한다.
DDBLT_ROP
이 블리트에 있어서의 ROP 에 DDBLTFX 구조체의 dwROP 멤버를 사용한다. ROPs 는 Win32 API 로 정의되는 것 것과 같다.
DDBLT_ROTATIONANGLE
표면의 회전각 (1/100о단위로 지정)으로서DDBLTFX 구조체의 dwRotationAngle 멤버를 사용한다.
DDBLT_ZBUFFER
전송원 및 목적지 표면에 Attach 되는 Z 버퍼에 의한 Z 버퍼 블리트를 실행한다. DDBLTFX 구조체의 dwZBufferOpCode 멤버를 Z 버퍼 작동코드로서 사용한다.
DDBLT_ZBUFFERDESTCONSTOVERRIDE
DDBLTFX 구조체의 dwZDestConst 및 dwZBufferOpCode 멤버에 의한 Z 버퍼 블리트를 실행한다. 각 멤버는 각각 목적지에 대한 Z 버퍼 및 Z 버퍼 작동코드로서 사용한다.
DDBLT_ZBUFFERDESTOVERRIDE
DDBLTFX 구조체의 lpDDSZBufferDest 및 dwZBufferOpCode 멤버에 의한 Z 버퍼 블리트를 실행한다. 각 멤버는 각각 목적지에 대한 Z 버퍼 및 Z 버퍼 작동코드로서 사용한다.
DDBLT_ZBUFFERSRCCONSTOVERRIDE
DDBLTFX 구조체의 dwZSrcConst 및 dwZBufferOpCode 멤버에 의한 Z 버퍼 블리트를 실행한다. 각 멤버는 각각 전송 바탕으로 대하는 Z 버퍼 및 Z 버퍼 작동코드로서 사용한다.
DDBLT_ZBUFFERSRCOVERRIDE
DDBLTFX 구조체의 IpDDSZBufferSrc 및 dwZBufferOpCode 멤버에 의한 Z 버퍼 블리트를 실행한다. 각 멤버는 각각 전송 바탕으로 대하는 Z 버퍼 및 Z 버퍼 작동코드로서 사용한다.
lpDDBltFx
추가의 블리트 이펙트를 지정하는 DDBLTFX 구조체의 주소.

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.


DDBLTFX

DDBLTFX 구조체는, 라스터 처리 (ROPs), 이펙트, 및 오버라이드(override) 정보를 IDirectDrawSurface7::Blt 메소드에 건네준다. 이 구조체는,IDirectDrawSurface7::BltBatch 메소드와 함께 사용하는 DDBLTBATCH 구조체의 일부에서도 있다.

typedef struct _DDBLTFX{
    DWORD dwSize;
    DWORD dwDDFX;
    DWORD dwROP;
    DWORD dwDDROP;
    DWORD dwRotationAngle;
    DWORD dwZBufferOpCode;
    DWORD dwZBufferLow;
    DWORD dwZBufferHigh;
    DWORD dwZBufferBaseDest;
    DWORD dwZDestConstBitDepth;
    union
    {
        DWORD               dwZDestConst;
        LPDIRECTDRAWSURFACE lpDDSZBufferDest;
    } DUMMYUNIONNAMEN(1);
    DWORD dwZSrcConstBitDepth;
    union
    {
        DWORD               dwZSrcConst;
        LPDIRECTDRAWSURFACE lpDDSZBufferSrc;
    } DUMMYUNIONNAMEN(2);
    DWORD dwAlphaEdgeBlendBitDepth;
    DWORD dwAlphaEdgeBlend;
    DWORD dwReserved;
    DWORD dwAlphaDestConstBitDepth;
    union
    {
        DWORD               dwAlphaDestConst;
        LPDIRECTDRAWSURFACE lpDDSAlphaDest;
    } DUMMYUNIONNAMEN(3);
    DWORD dwAlphaSrcConstBitDepth;
    union
    {
        DWORD               dwAlphaSrcConst;
        LPDIRECTDRAWSURFACE lpDDSAlphaSrc;
    } DUMMYUNIONNAMEN(4);
    union
    {
        DWORD               dwFillColor;
        DWORD               dwFillDepth;
        DWORD               dwFillPixel;
        LPDIRECTDRAWSURFACE lpDDSPattern;
    } DUMMYUNIONNAMEN(5);
    DDCOLORKEY ddckDestColorkey;
    DDCOLORKEY ddckSrcColorkey;
} DDBLTFX, FAR* LPDDBLTFX;

멤버

dwSize
바이트 단위의 구조체의 사이즈. 이 멤버는, 구조체를 사용하기 전에 초기화하지 않으면 안 된다.
dwDDFX
FX 처리의 타입. 이하의 종류가 정의된다.
DDBLTFX_ARITHSTRETCHY
이 블리트에 대해서, y 축으로 따라 산술신축(스트레치)를 사용한다.
DDBLTFX_MIRRORLEFTRIGHT
y 축상에서 표면을 회전한다. 이 블리트는, 표면을 왼쪽에서 오른쪽으로 밀러화한다.
DDBLTFX_MIRRORUPDOWN
x 축상에서 표면을 회전한다. 이 블리트는, 표면을 위에서 아래로 밀러화한다.
DDBLTFX_NOTEARING
이 블리트로티어링이 발생하지 않게 한다.
DDBLTFX_ROTATE180
이 블리트중에, 표면을 시계회전에 180 번 회전한다.
DDBLTFX_ROTATE270
이 블리트중에, 표면을 시계회전에 270 번 회전한다.
DDBLTFX_ROTATE90
이 블리트중에, 표면을 시계회전에 90 번 회전한다.
DDBLTFX_ZBUFFERBASEDEST
이 z 블리트중에, 목적지 z 값과 비교하기 전의 전송원 z 값의 각각에 dwZBufferBaseDest 멤버를 추가한다.
DDBLTFX_ZBUFFERRANGE
이 z 블리트중에, 전송원표면으로부터 카피한 비트에의 한계를 지정하는 범위값으로서 dwZBufferLow 및 dwZBufferHigh 멤버를 사용한다.
dwROP
Win32 라스터 처리. 지원 되는 라스터 처리의 리스트를 취득하려면 ,IDirectDraw7::GetCaps 메소드를 호출한다.
dwDDROP
DirectDraw 라스터 처리.
dwRotationAngle
블리트에 있어서의 회전 각도.
dwZBufferOpCode
Z 버퍼 비교.
dwZBufferLow
Z 버퍼의 최저한계.
dwZBufferHigh
Z 버퍼의 최고한도계.
dwZBufferBaseDest
Z 버퍼의 목적지 기저값.
dwZDestConstBitDepth
목적지 z 정수의 비트 깊이.
dwZDestConst
목적지 Z 버퍼로서 사용하는 정수.
lpDDSZBufferDest
목적지 Z 버퍼로서 사용하는 표면.
dwZSrcConstBitDepth
전송원 z 정수의 비트 깊이.
dwZSrcConst
전송원 Z 버퍼로서 사용하는 정수.
lpDDSZBufferSrc
전송원 Z 버퍼로서 사용하는 표면.
dwAlphaEdgeBlendBitDepth
알파 엣지 블렌드에 있어서의 비트 깊이 정수.
dwAlphaEdgeBlend
엣지 블렌드로 사용하는알파 정수 .
dwReserved
장래적인 사용을 위해서(때문에) 확보되고 있다.
dwAlphaDestConstBitDepth
목적지 알파 정수의 비트 깊이.
dwAlphaDestConst
목적지알파 채널로서 사용하는 정수.
lpDDSAlphaDest
목적지 알파 채널로서 사용하는 표면.
dwAlphaSrcConstBitDepth
전송원알파 정수의 비트 깊이.
dwAlphaSrcConst
전송원알파 채널로서 사용하는 정수.
lpDDSAlphaSrc
전송원알파 채널로서 사용하는 표면.
dwFillColor
DDBLT_COLORFILL 를 지정할 경우에, 표면을 전부 칠하기 위해서(때문에) 사용하는 색. 이 값은, 목적지 표면의 픽셀 포맷에 해당하는 픽셀이 아니면 안 된다. 팔레트화 표면이면팔레트 인덱스,16 비트 RGB 표면이면 16 비트 픽셀값이 된다.
dwFillDepth
Z 버퍼에 있어서의 깊이값.
dwFillPixel
RGBA 또는 RGBZ 로 전부 칠하기 위한 픽셀값. RGBZ 로 전부 칠하기 위해서(때문에) 사용하는 어플리케이션은,dwFillColor 또는 dwFillDepth 는 아니고, 이 멤버를 사용한다.
lpDDSPattern
패턴으로서 사용하는 표면. 패턴은, 전송원 및 목적지를 조합하는 특정의 블리트 처리로 사용한다.
ddckDestColorkey
목적지 컬러 키 오버라이드(override).
ddckSrcColorkey
전송원컬러 키 오버라이드(override).

주의

이 구조체의 집합은, 이름이 없는 집합을 지원 하지 않는 컴파일러로 기능하도록(듯이) 갱신되고 있다. 컴파일러가 이름의 없는 집합을 지원 하지 않는 경우는, Ddraw.h 헤더 파일을 인클루드 하기 전에 NONAMELESSUNION 토큰을 정의한다.

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.


DDCAPS

DDCAPS 구조체는, DirectDraw 오브젝트가 분명히 하는 하드웨어의 능력을 나타낸다. 이 구조체에는, 생성 할 수 있는 DirectDrawSurface 오브젝트의 종류를 기술하는 이 문맥의 DDSCAPS 구조체가 포함되어 있다. 그러나, 이러한 능력으로 기술하는 모든 표면을 동시에는 생성 할 수 없는 경우가 있다. 이 구조체는,IDirectDraw7::GetCaps 메소드로 사용된다.

Ddraw.h 헤더 파일에는 이 구조체의 복수의 버젼이 포함된다. 상세 정보는 주의를 참조할것.

typedef struct _DDCAPS {
    DWORD    dwSize;
    DWORD    dwCaps;
    DWORD    dwCaps2;
    DWORD    dwCKeyCaps;
    DWORD    dwFXCaps;
    DWORD    dwFXAlphaCaps;
    DWORD    dwPalCaps;
    DWORD    dwSVCaps;
    DWORD    dwAlphaBltConstBitDepths;
    DWORD    dwAlphaBltPixelBitDepths;
    DWORD    dwAlphaBltSurfaceBitDepths;
    DWORD    dwAlphaOverlayConstBitDepths;
    DWORD    dwAlphaOverlayPixelBitDepths;
    DWORD    dwAlphaOverlaySurfaceBitDepths;
    DWORD    dwZBufferBitDepths;
    DWORD    dwVidMemTotal;
    DWORD    dwVidMemFree;
    DWORD    dwMaxVisibleOverlays;
    DWORD    dwCurrVisibleOverlays;
    DWORD    dwNumFourCCCodes;
    DWORD    dwAlignBoundarySrc;
    DWORD    dwAlignSizeSrc;
    DWORD    dwAlignBoundaryDest;
    DWORD    dwAlignSizeDest;
    DWORD    dwAlignStrideAlign;
    DWORD    dwRops[DD_ROP_SPACE];
    DDSCAPS  ddsOldCaps;
    DWORD    dwMinOverlayStretch;
    DWORD    dwMaxOverlayStretch;
    DWORD    dwMinLiveVideoStretch;
    DWORD    dwMaxLiveVideoStretch;
    DWORD    dwMinHwCodecStretch;
    DWORD    dwMaxHwCodecStretch;
    DWORD    dwReserved1;
    DWORD    dwReserved2;
    DWORD    dwReserved3;
    DWORD    dwSVBCaps;
    DWORD    dwSVBCKeyCaps;
    DWORD    dwSVBFXCaps;
    DWORD    dwSVBRops[DD_ROP_SPACE];
    DWORD    dwVSBCaps;
    DWORD    dwVSBCKeyCaps;
    DWORD    dwVSBFXCaps;
    DWORD    dwVSBRops[DD_ROP_SPACE];
    DWORD    dwSSBCaps;
    DWORD    dwSSBCKeyCaps;
    DWORD    dwSSBFXCaps;
    DWORD    dwSSBRops[DD_ROP_SPACE];
    DWORD    dwMaxVideoPorts;
    DWORD    dwCurrVideoPorts;
    DWORD    dwSVBCaps2;
    DWORD    dwNLVBCaps;
    DWORD    dwNLVBCaps2;
    DWORD    dwNLVBCKeyCaps;
    DWORD    dwNLVBFXCaps;
    DWORD    dwNLVBRops[DD_ROP_SPACE];
    DDSCAPS2 ddsCaps;
} DDCAPS, FAR* LPDDCAPS;

멤버

dwSize
바이트 단위의 구조체의 사이즈. 이 멤버는, 구조체를 사용하기 전에 초기화하지 않으면 안 된다.
dwCaps
이하에, 드라이버 고유의 능력을 나타낸다.
DDCAPS_3D
디스플레이 하드웨어에 3D 가속기가 있다.
DDCAPS_ALIGNBOUNDARYDEST
DirectDraw 는, 표면의 dwAlignBoundaryDest 경계를 따라 x 축이 있는 오버레이 목적지 직사각형만 지원 한다.
DDCAPS_ALIGNBOUNDARYSRC
DirectDraw 는, 표면의 dwAlignBoundarySrc 경계를 따라 x 축이 있는 오버레이 전송원직사각형만 지원 한다.
DDCAPS_ALIGNSIZEDEST
DirectDraw 는, 바이트 단위에서의 x 축의 사이즈가 dwAlignSizeDest 의 배수인 오버레이 목적지 직사각형만 지원 한다.
DDCAPS_ALIGNSIZESRC
DirectDraw 는, 픽셀 단위에서의 x 축의 사이즈가 dwAlignSizeSrc 의 배수인 오버레이 전송원직사각형만 지원 한다.
DDCAPS_ALIGNSTRIDE
DirectDraw 는,dwAlignStrideAlign 값에 동일한보폭 경계를 가지는 디스플레이 메모리 표면을 생성 한다.
DDCAPS_ALPHA
디스플레이 하드웨어는, 알파 전용 표면을 지원 한다 ( 「알파 채널」을 참조할것).
DDCAPS_BANKSWITCHED
디스플레이 하드웨어는 반크스잇치이며, 디스플레이 메모리에의 랜덤 억세스가 매우 저속이 될 가능성이 있다.
DDCAPS_BLT
디스플레이 하드웨어는, 블리트 처리를 실행할 수 있다.
DDCAPS_BLTCOLORFILL
디스플레이 하드웨어는, 블리트에서의 색의 칠해를 실행할 수 있다.
DDCAPS_BLTDEPTHFILL
디스플레이 하드웨어는, 블리트로 Z 버퍼 깊이 보충을 실행할 수 있다.
DDCAPS_BLTFOURCC
디스플레이 하드웨어는, 블리트 처리중으로색공간(color space)의 변경을 실행할 수 있다.
DDCAPS_BLTQUEUE
디스플레이 하드웨어는, 비동기 블리트 처리를 실행할 수 있다.
DDCAPS_BLTSTRETCH
디스플레이 하드웨어는, 블리트 처리중에신축(스트레치)를 실행할 수 있다.
DDCAPS_CANBLTSYSMEM
디스플레이 하드웨어는, 시스템 메모리에의 또는 시스템 메모리로부터의 블리트 처리를 실행할 수 있다.
DDCAPS_CANCLIP
디스플레이 하드웨어는, 블리트 처리에서의 클리핑을 실행할 수 있다.
DDCAPS_CANCLIPSTRETCHED
디스플레이 하드웨어는, 신축(스트레치) 블리트 처리중에 클리핑을 실행할 수 있다.
DDCAPS_COLORKEY
오버레이 또는 블리트 처리의 어느 쪽인가에 두어,컬러 키의 몇개의 형식을 지원 한다. 보다 특정의 컬러 키 능력 정보는,dwCKeyCaps 멤버에 있다.
DDCAPS_COLORKEYHWASSIST
컬러 키는, 일부 하드웨어 지원을 받는다. 이 때문에, 다른 리소스 (CPU 또는 비디오 메모리)를 사용할 가능성이 있다. 이 비트가 설정되어 있지 않은 경우, 하드웨어의 풀 지원이 실시된다.
DDCAPS_GDI
디스플레이 하드웨어는, GDI 로 공유된다.
DDCAPS_NOHARDWARE
하드웨어 지원이 없다.
DDCAPS_OVERLAY
디스플레이 하드웨어는, 오버레이를 지원 한다.
DDCAPS_OVERLAYCANTCLIP
디스플레이 하드웨어는, 오버레이를 지원 하지만, 오버레이를 클립 할 수 없다.
DDCAPS_OVERLAYFOURCC
오버레이 하드웨어는, 오버레이 처리로색공간(color space)의 변경을 실행할 수 있다.
DDCAPS_OVERLAYSTRETCH
오버레이 하드웨어는,신축(스트레치)를 실행할 수 있다. DwMinOverlayStretch 및 dwMaxOverlayStretch 멤버에는, 유효한 데이터가 있다.
DDCAPS_PALETTE
DirectDraw 는,프라이머리 표면외, 그 외의 표면에 대해서도 DirectDrawPalette 오브젝트를 생성 및 지원 한다.
DDCAPS_PALETTEVSYNC
DirectDraw 는, 수직 리프레쉬와 동기 하는 팔레트를 갱신할 수 있다.
DDCAPS_READSCANLINE
디스플레이 하드웨어는, 현재의 주사선을 돌려줄 수가 있다.
DDCAPS_VBI
디스플레이 하드웨어는, 수직귀선소거 세치기를 생성할 수 있다.
DDCAPS_ZBLTS
블리트 처리와 함께 Z 버퍼의 사용을 지원 한다.
DDCAPS_ZOVERLAYS
겹이든지를 제어하는 오버레이의 z 값으로서IDirectDrawSurface7::UpdateOverlayZOrder 메소드의 사용을 지원 한다.
dwCaps2
이하에, 드라이버 고유의 능력을 나타낸다.
DDCAPS2_AUTOFLIPOVERLAY
오버레이는, 비디오 포트 VSYNC 가 발생할 때마다 플립핑 체인의 다음의 표면에 자동적으로 플립 된다. 또, CPU 오버헤드를 발생시키지 않고 , 비디오 포트 및 오버레이로부터 비디오를 더블 버퍼 할 수 있다. 이 옵션은, 표면이 비디오 포트로부터 데이터를 받을 때인 만큼 유효하다. 비디오 포트 데이터가 인터 레이스 또는 인터리브되어 있지 않은 경우, 비디오 포트 데이터는 VSYNC 가 발생할 때마다 플립 한다. 데이터가 메모리내에서 인터리브 되고 있는 경우, 데이터는 VSYNC 가 발생하는 1 회 간격으로 플립 한다.
DDCAPS2_CANBOBHARDWARE
오버레이 하드웨어는, 인터 레이스 비디오 스트림의 각각의 필드를 개별적으로 표시할 수 있다.
DDCAPS2_CANBOBINTERLEAVED
오버레이 하드웨어는, 특별한 하드웨어 지원이 없으면, 보통 발생할 가능성이 있는 이상을 일으키는 일 없이, 메모리로 인터리브 하고 있는 동안은, 인터 레이스 비디오 스트림의 각각의 필드를 개별적으로 표시할 수 있다. 이 옵션이 유효한 것은, 표면이 비디오 포트로부터 데이터를 받을 때, 및 비디오가 수직 방향으로 적어도 2 배 줌 될 때 뿐이다.
DDCAPS2_CANBOBNONINTERLEAVED
오버레이 하드웨어는, 특별한 하드웨어 지원이 없으면, 보통 발생할 가능성이 있는 이상을 일으키는 일 없이, 메모리로 인터리브 하고 있지 않는 동안은, 인터 레이스 비디오 스트림의 각각의 필드를 개별적으로 표시할 수 있다. 이 옵션이 유효한 것은, 표면이 비디오 포트로부터 데이터를 받을 때, 및 비디오가 수직 방향으로 적어도 2 배 줌 될 때 뿐이다.
DDCAPS2_CANCALIBRATEGAMMA
시스템에는, 자동적으로 감마 램프를 조정할 수 있는 구경 측정기가 인스톨 되고 있으므로, 구경 측정기가 있는 전시스템상에서 결과가 나타난다. 새로운 감마 레벨을 설정할 경우에 구경 측정기를 포함하려면 ,IDirectDrawGammaControl::SetGammaRamp 메소드를 호출할 때에 DDSGR_CALIBRATE 플래그를 사용한다. 감마 램프의 calibration에서는, 몇개의 처리에 오버헤드가 일어나므로, 빈번하게 사용할 수 없다.
DDCAPS2_CANDROPZ16BIT
16 비트 RGBZ 값을 16 비트 RGB 값으로 변환할 수 있다 (시스템에서는 8 비트 변환을 지원 하고 있지 않다).
DDCAPS2_CANFLIPODDEVEN
드라이버는,IDirectDrawSurface7::Flip 메소드와 함께 사용하는 DDFLIP_ODD 및 DDFLIP_EVEN 플래그를 지정해, 홀수 및 짝수 플립 처리를 실행할 수 있다.
DDCAPS2_CANMANAGETEXTURE
Direct3D 텍스쳐 매니저에서는, 이 능력을 사용해 관리 표면을 비로컬 비디오 메모리에 배치할지 어떨지를 결정한다. 이 능력을 설정 하면, 텍스쳐 매니저는 관리 표면을 비로컬 비디오 메모리에 배치한다. 로컬 비디오 메모리로부터의 텍스쳐 처리를 실행할 수 없는 드라이버에는, 이 능력을 설정해서는 안 된다.
DDCAPS2_CANRENDERWINDOWED
드라이버는, 윈도우 모드의 렌더링이 생긴다.
DDCAPS2_CERTIFIED
디스플레이 하드웨어가 보증되고 있다.
DDCAPS2_COLORCONTROLPRIMARY
프라이머리 표면에, 컬러 컨트롤 (감마등)이 포함된다.
DDCAPS2_COLORCONTROLOVERLAY
오버레이 표면에, 컬러 컨트롤 (휘도(Luminance), 선명도등)이 포함된다.
DDCAPS2_COPYFOURCC
드라이버는, 같은 FOURCC 의 다른 표면에의 FOURCC 표면의 블리트 처리를 지원 한다.
DDCAPS2_FLIPINTERVAL
드라이버는, DDFLIP_INTERVAL* 플래그에 응답한다 (IDirectDrawSurface7::Flip 를 참조할것).
DDCAPS2_FLIPNOVSYNC
드라이버는, DDFLIP_NOVSYNC 플래그에 응답한다 (IDirectDrawSurface7::Flip 를 참조할것).
DDCAPS2_NO2DDURING3DSCENE
IDirect3DDevice7::BeginScene 및 IDirect3DDevice7::EndScene 메소드를 호출하는 동안에 Direct3D 가 사용하는 모든 표면에 대해,IDirectDrawSurface7::Blt ,IDirectDrawSurface7::Lock 등의 2D 처리는 실행할 수 없다.
DDCAPS2_NONLOCALVIDMEM
디스플레이 드라이버는, 비로컬 비디오 메모리의 표면을 지원 한다.
DDCAPS2_NONLOCALVIDMEMCAPS
비로컬 비디오 메모리 표면의 블리트 능력은, 로컬 비디오 메모리 표면의 것과는 다르다. 이 플래그가 존재하는 경우, DDCAPS2_NONLOCALVIDMEM 플래그도 존재한다.
DDCAPS2_NOPAGELOCKREQUIRED
페이지 락되어 있지 않은 시스템 메모리 표면이, DMA 블리트 처리를 지원 한다.
DDCAPS2_PRIMARYGAMMA
프라이머리 표면에 대한 다이나믹 감마 램프를 지원 한다. 상세한 것에 대하여는, 「감마 컨트롤과 컬러 컨트롤」을 참조할것.
DDCAPS2_STEREO
DirectX 7.0 으로 추가. 디스플레이 디바이스는 스테레오 그래픽스를 지원 해, ddcaps.dwSVCaps 비트 필드를 온으로 한다. 대부분의 DDCAPS2 플래그와는 달라, 이 플래그는 특정의 모드로 실제로 스테레오를 지원 할지 어떨지에는 관계없이, 모든 모드에 대해서 설정된다. 어플리케이션에서는,IDirectDraw7::GetDisplayMode 또는IDirectDraw7::EnumDisplayModes 를 사용해, 모드 마다 스테레오 지원 정보를 취득할 수 있다.
DDCAPS2_TEXMANINNONLOCALVIDMEM
DirectX 7.0 으로 추가. Direct3D 텍스쳐 매니저에서는, 이 능력을 사용해 관리 표면을 비로컬 비디오 메모리에 배치한다. 이 능력을 설정 하면, 텍스쳐 매니저는 관리 표면을 비로컬 비디오 메모리에 배치한다. 로컬 비디오 메모리로부터의 텍스쳐 처리를 실행할 수 없는 드라이버에는, 이 능력을 설정해서는 안 된다.
DDCAPS2_VIDEOPORT
디스플레이 하드웨어는, 라이브 비디오를 지원 한다.
DDCAPS2_WIDESURFACES
디스플레이 표면은, 프라이머리 표면보다 넓은 표면을 지원 한다.
dwCKeyCaps
이하에, 컬러 키 능력을 나타낸다.
DDCKEYCAPS_DESTBLT
컬러 키에 의한 투과형 블리트 처리를 지원 한다. 컬러 키는, RGB 색의 목적지 표면의 치환가능인 비트를 나타낸다.
DDCKEYCAPS_DESTBLTCLRSPACE
색공간(color space)에 의한 투과형 블리트 처리를 지원 한다. 색공간(color space)은, RGB 색의 목적지 표면의 치환가능인 비트를 나타낸다.
DDCKEYCAPS_DESTBLTCLRSPACEYUV
색공간(color space)에 의한 투과형 블리트 처리를 지원 한다. 색공간(color space)는, YUV 색의 목적지 표면의 치환가능인 비트를 나타낸다.
DDCKEYCAPS_DESTBLTYUV
컬러 키에 의한 투과형 블리트 처리를 지원 한다. 컬러 키는, YUV 색의 목적지 표면의 치환가능인 비트를 나타낸다.
DDCKEYCAPS_DESTOVERLAY
컬러 키잉에 의한 오버레이를 지원 한다. 컬러 키잉은, RGB 색으로 오버레이 되는 목적지 표면의 치환가능인 비트이다.
DDCKEYCAPS_DESTOVERLAYCLRSPACE
RGB 색의 목적지 컬러 키로서 색공간(color space)를 지원 한다.
DDCKEYCAPS_DESTOVERLAYCLRSPACEYUV
YUV 색의 목적지 컬러 키로서 색공간(color space)를 지원 한다.
DDCKEYCAPS_DESTOVERLAYONEACTIVE
표시 상태의오버레이 표면에, 액티브한목적지 컬러 키값을 1 개만 지원 한다.
DDCKEYCAPS_DESTOVERLAYYUV
컬러 키잉에 의한 오버레이를 지원 한다. 컬러 키잉은, YUV 색으로 오버레이 되는 목적지 표면의 치환가능인 비트이다.
DDCKEYCAPS_NOCOSTOVERLAY
오버레이에서의 컬러 키의 사용에 대해 대역폭 트레이드 오프가 없는 것을 나타낸다.
DDCKEYCAPS_SRCBLT
RGB 색의 표면의 전송원컬러 키에 의한 투과형 블리트 처리를 지원 한다.
DDCKEYCAPS_SRCBLTCLRSPACE
RGB 색의 표면의 전송원의색공간(color space)에 의한 투과형 블리트를 지원 한다.
DDCKEYCAPS_SRCBLTCLRSPACEYUV
YUV 색의 표면의 전송원색공간(color space)에 의한 투과형 블리트를 지원 한다.
DDCKEYCAPS_SRCBLTYUV
YUV 색의 표면의 전송원컬러 키에 의한 투과형 블리트를 지원 한다.
DDCKEYCAPS_SRCOVERLAY
RGB 색의오버레이 표면의 전송원컬러 키에 의한 오버레이를 지원 한다.
DDCKEYCAPS_SRCOVERLAYCLRSPACE
RGB 색의 오버레이 표면으로전송원컬러 키로서 색공간(color space)를 사용한 오버레이를 지원 한다.
DDCKEYCAPS_SRCOVERLAYCLRSPACEYUV
YUV 색의 오버레이 표면으로 전송원컬러 키로서 색공간(color space)를 사용한 오버레이를 지원 한다.
DDCKEYCAPS_SRCOVERLAYONEACTIVE
표시 상태의 오버레이 표면에, 액티브한 전송원컬러 키값을 1 개만 지원 한다.
DDCKEYCAPS_SRCOVERLAYYUV
YUV 색의 오버레이 표면으로 전송원컬러 키를 사용한 오버레이를 지원 한다.
dwFXCaps
이하에, 드라이버 고유의신축(스트레치) 및 이펙트 능력을 나타낸다.
DDFXCAPS_BLTALPHA
알파 블렌딩 블리트 처리를 지원 한다.
DDFXCAPS_BLTARITHSTRETCHY
픽셀을 2 승으로 해 확대하는 기술은 아니고, 블리트 처리중에 표면을 확대하거나 수축하는 산술 처리를 사용한다. 이것은, y 축 (수직)에 따라 행해진다.
DDFXCAPS_BLTARITHSTRETCHYN
픽셀을 2 승으로 해 확대하는 기술은 아니고, 블리트 처리중에 표면을 확대하거나 수축하는 산술 처리를 사용한다. 이것은, y 축 (수직)에 따라 행해져 정수배신축(스트레치) (× 1,× 2 등) 에 대해서만 기능한다.
DDFXCAPS_BLTFILTER
드라이버는, 랩 된 블리트에 대해서 필터링 하는 표면의 복구성을 실시할 수 있다.
DDFXCAPS_BLTMIRRORLEFTRIGHT
블리트 처리로 좌우의 미러링을 지원 한다.
DDFXCAPS_BLTMIRRORUPDOWN
블리트 처리로 상하의 미러링을 지원 한다.
DDFXCAPS_BLTROTATION
블리트 처리로 임의의 회전을 지원 한다.
DDFXCAPS_BLTROTATION90
블리트 처리로 90 번의 회전을 지원 한다.
DDFXCAPS_BLTSHRINKX
x 축 (수평)에 따라 표면을 임의에 수축하는 것을 지원 한다. 이 플래그는, 블리트 처리인 만큼 유효하다.
DDFXCAPS_BLTSHRINKXN
x 축 (수평)에 따라 표면을 정수배 (× 1,× 2 등)에 수축하는 것을 지원 한다. 이 플래그는, 블리트 처리인 만큼 유효하다.
DDFXCAPS_BLTSHRINKY
y 축 (수직)에 따라 표면을 임의에 수축하는 것을 지원 한다. 이 플래그는, 블리트 처리인 만큼 유효하다.
DDFXCAPS_BLTSHRINKYN
y 축 (수직)에 따라 표면을 정수배 (× 1,× 2 등)에 수축하는 것을 지원 한다. 이 플래그는, 블리트 처리인 만큼 유효하다.
DDFXCAPS_BLTSTRETCHX
x 축 (수평)에 따라 표면을 임의에 신축(스트레치) 하는 것을 지원 한다. 이 플래그는, 블리트 처리인 만큼 유효하다.
DDFXCAPS_BLTSTRETCHXN
x 축 (수평)에 따라 표면을 정수배신축(스트레치) (× 1,× 2 등) 하는 것을 지원 한다. 이 플래그는, 블리트 처리인 만큼 유효하다.
DDFXCAPS_BLTSTRETCHY
y 축 (수직)에 따라 표면을 임의에 신축(스트레치) 하는 것을 지원 한다. 이 플래그는, 블리트 처리인 만큼 유효하다.
DDFXCAPS_BLTSTRETCHYN
y 축 (수직)에 따라 표면을 정수배신축(스트레치) (× 1,× 2 등) 하는 것을 지원 한다. 이 플래그는, 블리트 처리인 만큼 유효하다.
DDFXCAPS_BLTTRANSFORM
블리트 되는 스프라이트에 대해서 지오메트리 트랜스 폼 (또는, 랩)을 지원 한다. 현시점에서는, 트랜스 폼은 블리트 처리로 지원되어 있지 않다.
DDFXCAPS_OVERLAYALPHA
오버레이 표면에 대한 알파 블렌딩을 지원 한다.
DDFXCAPS_OVERLAYARITHSTRETCHY
픽셀을 2 배로 해 확대하는 기술은 아니고, 산술 처리를 사용해 오버레이 표면을 확대 및 수축한다. 이것은, y 축 (수직)에 따라 행해진다.
DDFXCAPS_OVERLAYARITHSTRETCHYN
픽셀을 2 배로 해 확대하는 기술은 아니고, 산술 처리를 사용해 오버레이 표면을 확대 및 수축하는 이것은, y 축 (수직)에 따라 행해져 정수배신축(스트레치) (× 1,× 2 등) 에 대해서만 기능한다.
DDFXCAPS_OVERLAYFILTER
랩 된 오버레이 스프라이트에 대해서 필터링 하는 표면의 복구성을 지원 한다. 현시점에서는, 필터링은 명시적으로 표시되는 오버레이 표면 (IDirectDrawSurface7::UpdateOverlay 를 호출하는 것으로 표시된다)에 대해서는 지원되어 있지 않다.
DDFXCAPS_OVERLAYMIRRORLEFTRIGHT
수직 축으로 따라 오버레이의 미러링을 지원 한다.
DDFXCAPS_OVERLAYMIRRORUPDOWN
수평 축으로 따라 오버레이의 미러링을 지원 한다.
DDFXCAPS_OVERLAYSHRINKX
x 축 (수평)에 따라 표면을 임의에 수축하는 것을 지원 한다. 이 플래그는, DDSCAPS_OVERLAY 표면인 만큼 유효하다. 이 플래그는, 표면의 능력만을 나타내, 수축이 가능하다 (일)것은 가리키지 않는다.
DDFXCAPS_OVERLAYSHRINKXN
x 축 (수평)에 따라 표면을 정수배수축 (× 1,× 2 등)하는 것을 지원 한다. 이 플래그는, DDSCAPS_OVERLAY 표면인 만큼 유효하다. 이 플래그는, 표면의 능력만을 나타내, 수축이 가능하다 (일)것은 가리키지 않는다.
DDFXCAPS_OVERLAYSHRINKY
y 축 (수직)에 따라 표면을 임의에 수축하는 것을 지원 한다. 이 플래그는, DDSCAPS_OVERLAY 표면인 만큼 유효하다. 이 플래그는, 표면의 능력만을 나타내, 수축이 가능하다 (일)것은 가리키지 않는다.
DDFXCAPS_OVERLAYSHRINKYN
y 축 (수직)에 따라 표면을 정수배수축 (× 1,× 2 등)하는 것을 지원 한다. 이 플래그는, DDSCAPS_OVERLAY 표면인 만큼 유효하다. 이 플래그는, 표면의 능력만을 나타내, 수축이 가능하다 (일)것은 가리키지 않는다.
DDFXCAPS_OVERLAYSTRETCHX
x 축 (수평)에 따라 표면을 임의에신축(스트레치) 하는 것을 지원 한다. 이 플래그는, DDSCAPS_OVERLAY 표면인 만큼 유효하다. 이 플래그는 표면의 능력만을 나타내, 신축(스트레치)가 가능한 것을 나타내는 것은 아니다.
DDFXCAPS_OVERLAYSTRETCHXN
x 축 (수평)에 따라 표면을 정수배신축(스트레치) (× 1,× 2 등) 하는 것을 지원 한다. 이 플래그는, DDSCAPS_OVERLAY 표면인 만큼 유효하다. 이 플래그는 표면의 능력만을 나타내, 신축(스트레치)가 가능하다 (일)것은 가리키는 것은 아니다.
DDFXCAPS_OVERLAYSTRETCHY
y 축 (수직)에 따라 표면을 임의에 신축(스트레치) 하는 것을 지원 한다. 이 플래그는, DDSCAPS_OVERLAY 표면인 만큼 유효하다. 이 플래그는 표면의 능력만을 나타내, 신축(스트레치)가 가능한 것을 나타내는 것은 아니다.
DDFXCAPS_OVERLAYSTRETCHYN
y 축 (수직)에 따라 표면을 정수배신축(스트레치) (× 1,× 2 등) 하는 것을 지원 한다. 이 플래그는, DDSCAPS_OVERLAY 표면인 만큼 유효하다. 이 플래그는 표면의 능력만을 나타내, 신축(스트레치)가 가능한 것을 나타내는 것은 아니다.
DDFXCAPS_OVERLAYTRANSFORM
오버레이 스프라이트에 대해서 지오메트리 트랜스 폼 (또는, 랩)을 지원 한다. 현시점에서는, 트랜스 폼은 명시적으로 표시되는 오버레이 표면 (IDirectDrawSurface7::UpdateOverlay 의 호출로 표시된다)에 대해서는 지원되어 있지 않다.
dwFXAlphaCaps
이하에, 드라이버 고유의 알파 능력을 나타낸다.
DDFXALPHACAPS_BLTALPHAEDGEBLEND
전송원컬러 키 표면의 인연 주위의 알파 블렌딩을 지원 한다. 블리트 처리에 대해서 사용된다.
DDFXALPHACAPS_BLTALPHAPIXELS
픽셀 포맷으로 알파 정보를 지원 한다. 픽셀 포맷의 알파 정보의 비트 깊이는, 1, 2, 4, 또는 8 이다. 알파값은, 증가하는 것에 따라보다 불투명이 된다. 알파 정보의 깊이에 관계없이, 0 은 항상 완전한 투과형값이 된다. 블리트 처리에 대해서 사용된다.
DDFXALPHACAPS_BLTALPHAPIXELSNEG
픽셀 포맷으로 알파 정보를 지원 한다. 픽셀 포맷의 알파 정보의 비트 깊이는, 1, 2, 4, 또는 8 이다. 알파값은, 증가하는 것에 따라보다 투과형이 된다. 알파 정보의 깊이에 관계없이, 0 은 항상 완전한 불투명값이 된다. 이 플래그는, DDCAPS_ALPHA 가 설정되어 있는 경우인 만큼 사용할 수 있다. 블리트 처리에 대해서 사용된다.
DDFXALPHACAPS_BLTALPHASURFACES
알파 전용 표면을 지원 한다. 알파 전용 표면의 비트 깊이는, 1, 2, 4, 또는 8 이다. 알파값은, 증가하는 것에 따라보다 불투명이 된다. 알파 정보의 깊이에 관계없이, 0 은 항상 완전한 투과형값이 된다. 블리트 처리에 대해서 사용된다.
DDFXALPHACAPS_BLTALPHASURFACESNEG
알파 채널 은, 알파값이 증가하는 것에 따라보다 투과형이 되는 것을 나타낸다. 알파 채널 데이터의 깊이는, 1, 2, 4, 또는 8 이다. 알파 정보의 깊이에 관계없이, 0 은 항상 완전한 불투명값이 된다. 이 플래그는, DDCAPS_ALPHA 가 설정되어 있는 경우에만 사용할 수 있다. 블리트 처리에 대해서 사용된다.
DDFXALPHACAPS_OVERLAYALPHAEDGEBLEND
전송원컬러 키 표면의 인연 주위의 알파 블렌딩을 지원 한다. 오버레이에 대해서 사용된다.
DDFXALPHACAPS_OVERLAYALPHAPIXELS
픽셀 포맷으로 알파 정보를 지원 한다. 픽셀 포맷의 알파 정보의 비트 깊이는, 1, 2, 4, 또는 8 이다. 알파값은, 증가하는 것에 따라보다 불투명이 된다. 알파 정보의 깊이에 관계없이, 0 은 항상 완전한 투과형값이 된다. 오버레이에 대해서 사용된다.
DDFXALPHACAPS_OVERLAYALPHAPIXELSNEG
픽셀 포맷으로 알파 정보를 지원 한다. 픽셀 포맷의 알파 정보의 비트 깊이는, 1, 2, 4, 또는 8 이다. 알파값은, 증가하는 것에 따라보다 투과형이 된다. 알파 정보의 깊이에 관계없이, 0 은 항상 완전한 불투명값이 된다. 이 플래그는, DDCAPS_ALPHA 가 설정되어 있는 경우인 만큼 사용된다. 오버레이에 대해서 사용된다.
DDFXALPHACAPS_OVERLAYALPHASURFACES
알파 전용 표면을 지원 한다. 알파 전용 표면의 비트 깊이는, 1, 2, 4, 또는 8 이다. 알파값은, 증가하는 것에 따라보다 불투명이 된다. 알파 정보의 깊이에 관계없이, 0 은 항상 완전한 투과형값이 된다. 오버레이에 대해서 사용된다.
DDFXALPHACAPS_OVERLAYALPHASURFACESNEG
알파값이 증가하는 것에 따라, 알파 채널이 보다 투과형이 되는 것을 나타낸다. 알파 채널 데이터의 깊이는, 1, 2, 4, 또는 8 이다. 알파 정보의 깊이에 관계없이, 0 은 항상 완전한 불투명값이 된다. 이 플래그는, DDCAPS_ALPHA 가 설정되어 있는 경우인 만큼 사용된다. 오버레이에 대해서 사용된다.
dwPalCaps
이하에, 팔레트 능력을 나타낸다.
DDPCAPS_1BIT
1 비트 컬러 엔트리 (2 색)를 포함한 팔레트를 지원 한다.
DDPCAPS_2BIT
2 비트 컬러 엔트리 (4 색)를 포함한 팔레트를 지원 한다.
DDPCAPS_4BIT
4 비트 컬러 엔트리 (16 색)를 포함한 팔레트를 지원 한다.
DDPCAPS_8BIT
8 비트 컬러 엔트리 (256 색)를 포함한 팔레트를 지원 한다.
DDPCAPS_8BITENTRIES
인덱스를 8 비트 컬러 인덱스로 지정한다. 이 필드는, DDPCAPS_1 BIT, DDPCAPS_2 BIT, 또는 DDPCAPS_4BIT 능력이 사용되는 경우, 및 타겟 표면이 1 픽셀 당 8 비트 (bpp)인 경우에게만 유효하다. 각각의 컬러 엔트리는 1 바이트장이며, 목적지 표면 위에의 8 bpp 팔레트에의 인덱스이다.
DDPCAPS_ALPHA
알파 성분을 포함한 팔레트를 지원 한다. 알파 능력 팔레트에서는, 팔레트에 포함되는 각 PALETTEENTRY 구조체의 peFlags 멤버는, 단일의 8 비트 알파값 (peRed,peGreen,peBlue 멤버의 데이터외)으로서 판단된다. 이 플래그로 생성 된 팔레트는, 텍스쳐 표면에게만 Attach 할 수 있다.
DDPCAPS_ALLOW256
모든 256 엔트리를 정의할 수 있는 팔레트를 지원 한다.
DDPCAPS_PRIMARYSURFACE
팔레트는프라이머리 표면에 Attach 된다. 팔레트의 변경은, DDPCAPS_VSYNC 능력의 지정 및 지원이 없는 한, 디스플레이에 즉석에서 반영된다.
DDPCAPS_PRIMARYSURFACELEFT
팔레트는, 좌측에서 프라이머리 표면에 Attach 된다. 팔레트의 변경은, DDPCAPS_VSYNC 능력의 지정 및 지원이 없는 한, 디스플레이에 즉석에서 반영된다.
DDPCAPS_VSYNC
팔레트는, 모니터의 refresh rate에 동기 해 변경할 수 있다.
dwSVCaps
이하에, 스테레오 비전 능력을 나타낸다.
DDSVCAPS_RESERVED1, DDSVCAPS_RESERVED2, DDSVCAPS_RESERVED3, DDSVCAPS_RESERVED4
향후를 위해서(때문에) 확보되고 있는 플래그.
DDSVCAPS_STEREOSEQUENTIAL
DirectX 7.0 으로 추가. 드라이버는, 현재의 모드 이외가 적어도 1 개의 모드로 스테레오를 실행할 수 있다. 어플리케이션에서는,IDirectDraw7::GetDisplayMode 또는 IDirectDraw7::EnumDisplayModes 를 사용해 각 모드의 스테레오 정보를 취득할 수 있다.
dwAlphaBltConstBitDepths
DDBD_2, DDBD_4, 또는 DDBD_8 (1 픽셀 당 2, 4, 또는 8 비트인 것을 나타낸다).
dwAlphaBltPixelBitDepths
DDBD_1, DDBD_2, DDBD_4, 또는 DDBD_8 (1 픽셀 당 1, 2, 4, 또는 8 비트인 것을 나타낸다).
dwAlphaBltSurfaceBitDepths
DDBD_1, DDBD_2, DDBD_4, 또는 DDBD_8 (1 픽셀 당 1, 2, 4, 또는 8 비트인 것을 나타낸다).
dwAlphaOverlayConstBitDepths
DDBD_2, DDBD_4, 또는 DDBD_8 (1 픽셀 당 2, 4, 또는 8 비트인 것을 나타낸다).
dwAlphaOverlayPixelBitDepths
DDBD_1, DDBD_2, DDBD_4, 또는 DDBD_8 (1 픽셀 당 1, 2, 4, 또는 8 비트인 것을 나타낸다).
dwAlphaOverlaySurfaceBitDepths
DDBD_1, DDBD_2, DDBD_4, 또는 DDBD_8 (1 픽셀 당 1, 2, 4, 또는 8 비트인 것을 나타낸다).
dwZBufferBitDepths
DDBD_8, DDBD_16, DDBD_24, 또는 DDBD_32 (1 픽셀 당 8, 16, 24, 또는 32 비트인 것을 나타낸다). 이 멤버는, DirectX 6.0 이후의 버젼을 위해서(때문에) 취득된다. IDirect3D7::EnumZBufferFormats 를 사용해, 서포트 되는 깊이 버퍼 포맷의 정보를 취득한다.
dwVidMemTotal
바이트 단위로 나타내는, 디바이스 위에의 디스플레이 메모리의 총용량. 다만, 프라이머리 표면용으로 확보되고 있는 메모리 및 드라이버로 확보하는 Private 데이터 구조 체용의 메모리를 제외하다 (이 값은,IDirectDraw7::GetAvailableVidMem 메소드가 알리는 전비디오 메모리와 같다).
dwVidMemFree
디스플레이 메모리를 릴리즈 한다. 이 값은,dwVidMemTotal 의 값으로부터, 어플리케이션이 표면용으로 현재 할당하고 있는 메모리를 당긴 값과 같다. 특정의 종류의 표면 (텍스쳐등)으로 사용 가능한 메모리를 알리는 GetAvailableVidMem 메소드와는 달라, 이 값은 모든 종류의 표면에 대해서 사용 가능한 메모리를 나타낸다.
dwMaxVisibleOverlays
표시되는 오버레이 또는 오버레이 스프라이트의 최대수.
dwCurrVisibleOverlays
표시되는 오버레이 또는 오버레이 스프라이트의 현재의 수.
dwNumFourCCCodes
FOURCC 코드의 수.
dwAlignBoundarySrc
픽셀 단위의 오버레이 표면에 대한 전송원직사각형의 아라이먼트.
dwAlignSizeSrc
픽셀 단위의 오버레이 표면에 대한 전송원직사각형의 사이즈아라이먼트. 오버레이 전송원직사각형은, 이 값의 배수의 픽셀폭이 아니면 안 된다.
dwAlignBoundaryDest
픽셀 단위의 오버레이 표면에 대한 목적지 직사각형의 아라이먼트.
dwAlignSizeDest
픽셀 단위의 오버레이 표면에 대한 목적지 직사각형의 사이즈아라이먼트. 오버레이 목적지 직사각형은, 이 값의 배수의 픽셀폭이 아니면 안 된다.
dwAlignStrideAlign
보폭 아라이먼트.
dwRops[DD_ROP_SPACE]
지원 되는 라스터 처리.
ddsOldCaps
폐지. DirectX 6.0 보다 전은, 이 멤버에는 일반적인 표면 능력이 포함되어 있었다. 현재 이러한 표면 능력은,ddsCaps 멤버 (DDSCAPS2 구조체)에 포함되어 있다.
dwMinOverlayStretch,dwMaxOverlayStretch
1000 배 되는 최소 및 최대 오버레이 신축(스트레치) 계수. 예를 들어, 1.3 = 1300.
dwMinLiveVideoStretch,dwMaxLiveVideoStretch
폐지. 사용하지 않는다.
dwMinHwCodecStretch,dwMaxHwCodecStretch
폐지. 사용하지 않는다.
dwReserved1,dwReserved2,dwReserved3
장래적인 사용을 위해서(때문에) 확보되고 있다.
dwSVBCaps
시스템 메모리로부터 디스플레이 메모리에의 블리트에 관한 드라이버 고유의 능력. 유효 플래그는,dwCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
dwSVBCKeyCaps
시스템 메모리로부터 디스플레이 메모리에의 블리트에 관한 드라이버의 컬러 키 능력. 유효 플래그는,dwCKeyCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
dwSVBFXCaps
시스템 메모리로부터 디스플레이 메모리에의 블리트에 관한 드라이버의 FX 능력. 유효 플래그는,dwFXCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
dwSVBRops[DD_ROP_SPACE]
시스템 메모리로부터 디스플레이 메모리에의 블리트로 지원 되는 라스터 처리.
dwVSBCaps
디스플레이 메모리로부터 시스템 메모리에의 블리트에 관한 드라이버 고유의 능력. 유효 플래그는,dwCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
dwVSBCKeyCaps
디스플레이 메모리로부터 시스템 메모리의 블리트에 관한 드라이버의 컬러 키 능력. 유효 플래그는,dwCKeyCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
dwVSBFXCaps
디스플레이 메모리로부터 시스템 메모리에의 블리트에 관한 드라이버의 FX 능력. 유효 플래그는,dwFXCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
dwVSBRops[DD_ROP_SPACE]
디스플레이 메모리로부터 시스템 메모리에의 블리트로 지원 되는 라스터 처리.
dwSSBCaps
시스템 메모리로부터 시스템 메모리에의 블리트에 관한 드라이버 고유의 능력. 유효 플래그는,dwCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
dwSSBCKeyCaps
시스템 메모리로부터 시스템 메모리에의 블리트에 관한 드라이버의 컬러 키 능력. 유효 플래그는,dwCKeyCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
dwSSBFXCaps
시스템 메모리로부터 시스템 메모리에의 블리트에 관한 드라이버의 FX 능력. 유효 플래그는,dwFXCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
dwSSBRops[DD_ROP_SPACE]
시스템 메모리로부터 시스템 메모리에의 블리트로 지원 되는 라스터 처리.
dwMaxVideoPorts
라이브 비디오 포트의 최대수.
dwCurrVideoPorts
라이브 비디오 포트의 현재의 수.
dwSVBCaps2
시스템 메모리로부터 비디오 메모리에의 블리트의 관한 , 드라이버 고유의 상세한 능력. 유효 플래그는,dwCaps2 멤버로 사용되는 블리트 관련 플래그와 동일하다.
dwNLVBCaps
비로컬로부터 로컬 비디오 메모리에의 블리트에 관한 드라이버 고유의 능력. 유효 플래그는,dwCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
dwNLVBCaps2
비로컬로부터 로컬 비디오 메모리에의 블리트의 관한 , 드라이버 고유의 상세한 능력. 유효 플래그는,dwCaps2 멤버로 사용되는 블리트 관련 플래그와 동일하다.
dwNLVBCKeyCaps
비로컬로부터 로컬 비디오 메모리의 블리트에 관한 드라이버의 컬러 키 능력. 유효 플래그는,dwCKeyCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
dwNLVBFXCaps
비로컬로부터 로컬 비디오 메모리의 블리트의 관한 드라이버의 FX 능력. 유효 플래그는,dwFXCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
dwNLVBRops[DD_ROP_SPACE]
비로컬로부터 로컬 비디오 메모리에의 블리트로 지원 되는 라스터 처리.
ddsCaps
일반적인 표면 능력이 있는 DDSCAPS2 구조체.

주의

후방 호환성을 유지하기 위해서(때문에), Ddraw.h 헤더 파일에는 DDCAPS 구조체의 복수의 정의가 포함되어 있다. 프리프로세서를 건네주는 버젼은, DIRECTDRAW_VERSION 정수의 값에 의해 정해진다. 상세한 것에 대하여는, 「컴퍼넌트의 버젼 정수」를 참조할것.

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
Windows CE : ddraw.h 로 선언.


DDCOLORCONTROL

DDCOLORCONTROL 구조체는, DirectDrawVideoPortObject,오버레이 표면, 또는프라이머리 표면에 관련지을 수 있었던 컬러 컨트롤을 정의한다.

typedef struct _DDCOLORCONTROL {
    DWORD   dwSize;
    DWORD   dwFlags;
    LONG    lBrightness;
    LONG    lContrast;
    LONG    lHue;
    LONG    lSaturation;
    LONG    lSharpness;
    LONG    lGamma;
    LONG    lColorEnable;
    DWORD   dwReserved1;
} DDCOLORCONTROL, FAR *LPDDCOLORCONTROL;

멤버

dwSize
바이트 단위의 구조체의 사이즈. 이 멤버는, 구조체를 사용하기 전에 초기화해야 한다.
dwFlags
이하에, 유효한 데이터를 포함한 구조체 멤버를 지정하는 플래그를 나타낸다. 구조체가 IDirectDrawColorControl::GetColorControls 메소드에 의해 돌려주어지는 경우, 디바이스로 지원 되는 옵션도 가리킨다.
DDCOLOR_BRIGHTNESS
lBrightness 멤버가 유효한 데이터를 포함한다.
DDCOLOR_COLORENABLE
lColorEnable 멤버가 유효한 데이터를 포함한다.
DDCOLOR_CONTRAST
lContrast 멤버가 유효한 데이터를 포함한다.
DDCOLOR_GAMMA
lGamma 멤버가 유효한 데이터를 포함한다.
DDCOLOR_HUE
lHue 멤버가 유효한 데이터를 포함한다.
DDCOLOR_SATURATION
lSaturation 멤버가 유효한 데이터를 포함한다.
DDCOLOR_SHARPNESS
lSharpness 멤버가 유효한 데이터를 포함한다.
lBrightness
IRE 단위 (× 100)로 나타내는 휘도(Luminance). 유효 범위는 0 에서 10,000. 디폴트값은 750 (7.5 IRE).
lContrast
IRE 단위 (× 100)로 나타내는 휘도(Luminance)에 있어서의 위와 아래의 휘도(Luminance)의 상대적 차위. 유효 범위는 0 에서 20,000. 디폴트값은 10,000 (100 IRE). 콘트라스트를 올리면(자), 보다 어두운 휘도(Luminance)는 거뭇해져, 보다 밝은 휘도(Luminance)는 희어지는 경향이 있다. 콘트라스트를 내리면(자), 모든 휘도(Luminance)가 중간의 휘도(Luminance)가 되도록(듯이) 변화한다.
lHue
크로미난스 성분의 위상 관계. 색상은 번으로 지정된다. 유효 범위는 -180 으로부터 180. 디폴트값은 0.
lSaturation
IRE 단위 (× 100)로 나타내는 컬러 강도. 유효 범위는 0 에서 20,000. 디폴트값은 10,000 (100 IRE).
lSharpness
임의의 단위의 선명도. 유효 범위는 0 에서 10. 디폴트값은 5.
lGamma
휘도(Luminance)에 적용되는 감마 수정량을 제어한다. 유효 범위는 감마 단위로 1 에서 500. 디폴트값은 1.
lColorEnable
색을 사용할지 어떨지를 나타내는 플래그. 이 멤버가 0 의 경우, 색은 사용되지 않는다. 이 멤버가 1 의 경우는 색이 사용된다. 디폴트값은 1.
dwReserved1
장래적인 사용을 위해서(때문에) 확보되고 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
Windows CE : ddraw.h 로 선언.


DDCOLORKEY

DDCOLORKEY 구조체는,전송원컬러 키,목적지 컬러 키, 또는색공간(color space)를 기술한다. 컬러 키는, 상한과 하한의 범위값이 같은 경우로 지정된다. 이 구조체는,IDirectDrawSurface7::GetColorKey 및 IDirectDrawSurface7::SetColorKey 메소드로 사용된다.

typedef struct _DDCOLORKEY{
    DWORD dwColorSpaceLowValue;
    DWORD dwColorSpaceHighValue;
} DDCOLORKEY, FAR* LPDDCOLORKEY;

멤버

dwColorSpaceLowValue
컬러 키로서 사용되는 색범위의 하한값.
dwColorSpaceHighValue
컬러 키로서 사용되는 색범위의 상한치.

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.


DDDEVICEIDENTIFIER2

DDDEVICEIDENTIFIER2 구조체는, 디바이스 정보를 취득하는 IDirectDraw7::GetDeviceIdentifier 메소드에게 건네진다.

typedef struct tagDDDEVICEIDENTIFIER2 {
    char    szDriver[MAX_DDDEVICEID_STRING];
    char    szDescription[MAX_DDDEVICEID_STRING];
    LARGE_INTEGER  liDriverVersion;
    DWORD   dwVendorId;
    DWORD   dwDeviceId;
    DWORD   dwSubSysId;
    DWORD   dwRevision;
    GUID    guidDeviceIdentifier;
    DWORD   dwWHQLLevel;
} DDDEVICEIDENTIFIER2, * LPDDDEVICEIDENTIFIER2;

멤버

szDriver
드라이버의 이름.
szDescription
드라이버의 기술.
liDriverVersion
드라이버의 버젼. 전 64 비트보다 적은가 많은가를 정당하게 비교한다. 이 요소를 사용해 의심스러운 드라이버를 식별하는 경우는, 주의해 실시하는 것. 이 목적으로는 guidDeviceIdentifier 를 사용한다.

데이터는, 다음의 폼을 취득한다.

wProduct = HIWORD(liDriverVersion.HighPart)
wVersion = LOWORD(liDriverVersion.HighPart)
wSubVersion = HIWORD(liDriverVersion.LowPart)
wBuild = LOWORD(liDriverVersion.LowPart)
dwVendorId
메이커의 식별자. 불명의 경우는 0.
dwDeviceId
칩 세트의 타입 식별자. 불명의 경우는 0.
dwSubSysId
서브 시스템의 식별자. 보통, 특정의 보드를 의미한다. 불명의 경우는 0.
dwRevision
칩 세트의 개정판 레벨의 식별자. 불명의 경우는 0.
guidDeviceIdentifier
드라이버/칩 세트 조의 고유 식별자. 드라이버 또는 칩 세트에의 변경을 추적해, 그래픽스 서브시스템 의 프로파일을 생성 다시 하는 경우는, 이 값을 사용한다. 또, 특정의 의심스러운 드라이버를 식별하는 경우에도 사용할 수 있다.
dwWHQLLevel
디바이스/드라이버의 페어의 Windows Hardware Quality Lab (WHQL) 인증 레벨.

주의

szDriver 와 szDescription 의 값은, 유저 (을) 위해서만 있다. 다른 캐릭터 라인이 같은 디바이스에 관련하고 있거나 다른 메이커의 같은 드라이버가 달라 기술되는 일이 있기 (위해)때문에, 이러한 값은 특정의 드라이버를 식별하기 위해서 사용해서는 안된다.

dwVendorId,dwDeviceId,dwSubSysId, 및 dwRevision 멤버는 특정의 칩 세트를 식별하기 위해서 사용할 수 있지만, 세심의 주의가 필요하다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.


DDGAMMARAMP

DDGAMMARAMP 구조체는,IDirectDrawGammaControl::GetGammaRamp 및 IDirectDrawGammaControl::SetGammaRamp 메소드용의 적, 초록, 및 파랑 램프 데이터를 포함한다.

typedef struct _DDGAMMARAMP {
    WORD red[256];
    WORD green[256];
    WORD blue[256];
} DDGAMMARAMP, FAR * LPDDGAMMARAMP;

멤버

red,green,blue
적, 초록, 및 파랑의 감마 램프를 기술하는 256 WORD 요소의 배열.

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.

참조

감마 컨트롤과 컬러 컨트롤


DDOVERLAYFX

DDOVERLAYFX 구조체는,IDirectDrawSurface7::UpdateOverlay 메소드에 오버라이드(override) 정보를 건네준다.

typedef struct _DDOVERLAYFX{
    DWORD dwSize;
    DWORD dwAlphaEdgeBlendBitDepth;
    DWORD dwAlphaEdgeBlend;
    DWORD dwReserved;
    DWORD dwAlphaDestConstBitDepth;
    union
    {
        DWORD               dwAlphaDestConst;
        LPDIRECTDRAWSURFACE lpDDSAlphaDest;
    } DUMMYUNIONNAMEN(1);
    DWORD dwAlphaSrcConstBitDepth;
    union
    {
        DWORD               dwAlphaSrcConst;
        LPDIRECTDRAWSURFACE lpDDSAlphaSrc;
    } DUMMYUNIONNAMEN(2);
    DDCOLORKEY dckDestColorkey;
    DDCOLORKEY dckSrcColorkey;

    DWORD dwDDFX;
    DWORD dwFlags;
} DDOVERLAYFX, FAR *LPDDOVERLAYFX;

멤버

dwSize
바이트 단위의 구조체의 사이즈. 이 멤버는, 구조체를 사용하기 전에 초기화하지 않으면 안 된다.
dwAlphaEdgeBlendBitDepth
알파 엣지 블렌드의 정수를 지정하기 위해서 사용되는 비트 깊이.
dwAlphaEdgeBlend
엣지 블렌드에 대한 알파로서 사용되는 정수.
dwReserved
장래적인 사용을 위해서(때문에) 확보되고 있다.
dwAlphaDestConstBitDepth
목적지의알파 정수를 지정하기 위해서 사용되는 비트 깊이.
dwAlphaDestConst
목적지의알파 채널로서 사용되는 정수.
lpDDSAlphaDest
목적지의 알파 채널로서 사용하는 표면의 주소.
dwAlphaSrcConstBitDepth
전송원의 알파 정수를 지정하기 위해서 사용되는 비트 깊이.
dwAlphaSrcConst
전송원의 알파 채널로서 사용하는 정수.
lpDDSAlphaSrc
전송원의 알파 채널로서 사용하는 표면의 주소.
dckDestColorkey
목적지 컬러 키 오버라이드(override).
dckSrcColorkey
전송원컬러 키 오버라이드(override).
dwDDFX
이하에, 오버레이 FX 플래그를 나타낸다.
DDOVERFX_ARITHSTRETCHY
신축(스트레치)를 실행하는 경우, 오버레이의 y 축으로 따라 산술 신축(스트레치)를 사용한다.
DDOVERFX_MIRRORLEFTRIGHT
수직축의 주위에서 오버레이를 밀러화한다.
DDOVERFX_MIRRORUPDOWN
수평축의 주위에서 오버레이를 밀러화한다.
dwFlags
현재미사용이므로 0 을 설정해 둔다.

주의

이 구조체의 집합은, 이름이 없는 집합을 지원 하지 않는 컴파일러로 기능하도록(듯이) 갱신되고 있다. 컴파일러가 이름의 없는 집합을 지원 하지 않는 경우, Ddraw.h 헤더 파일을 인클루드 하기 전에 NONAMELESSUNION 토큰을 정의한다.

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.


DDPIXELFORMAT

DDPIXELFORMAT 구조체는,IDirectDrawSurface7::GetPixelFormat 메소드에 대한 DirectDrawSurface 오브젝트의 픽셀 포맷을 기술한다.

typedef struct _DDPIXELFORMAT{
    DWORD dwSize;
    DWORD dwFlags;
    DWORD dwFourCC;
    union
    {
        DWORD dwRGBBitCount;
        DWORD dwYUVBitCount;
        DWORD dwZBufferBitDepth;
        DWORD dwAlphaBitDepth;
        DWORD dwLuminanceBitCount;
        DWORD dwBumpBitCount;
    } DUMMYUNIONNAMEN(1);
    union
    {
        DWORD dwRBitMask;
        DWORD dwYBitMask;
        DWORD dwStencilBitDepth;
        DWORD dwLuminanceBitMask;
        DWORD dwBumpDuBitMask;
    } DUMMYUNIONNAMEN(2);
    union
    {
        DWORD dwGBitMask;
        DWORD dwUBitMask;
        DWORD dwZBitMask;
        DWORD dwBumpDvBitMask;
    } DUMMYUNIONNAMEN(3);
    union
    {
        DWORD dwBBitMask;
        DWORD dwVBitMask;
        DWORD dwStencilBitMask;
        DWORD dwBumpLuminanceBitMask;
    } DUMMYUNIONNAMEN(4);
    union
    {
        DWORD dwRGBAlphaBitMask;
        DWORD dwYUVAlphaBitMask;
        DWORD dwLuminanceAlphaBitMask;
        DWORD dwRGBZBitMask;
        DWORD dwYUVZBitMask;
    } DUMMYUNIONNAMEN(5);
} DDPIXELFORMAT, FAR* LPDDPIXELFORMAT;

멤버

dwSize
바이트 단위의 구조체의 사이즈. 이 멤버는, 구조체를 사용하기 전에 초기화하지 않으면 안 된다.
dwFlags
이하에, 옵션 제어 플래그를 나타낸다.
DDPF_ALPHA
픽셀 포맷은, 알파 전용 표면을 기술한다.
DDPF_ALPHAPIXELS
표면에는, 픽셀 포맷의알파 채널 정보가 있다.
DDPF_ALPHAPREMULT
표면은, 미리 늘린 알파 포맷을 사용한다. 즉, 각각의 픽셀의 색성분은, 알파 성분을 미리 걸 수 있고 있다.
DDPF_BUMPLUMINANCE
픽셀 포맷의 휘도(Luminance) 데이터는 유효하다. 또,dwLuminanceBitMask 멤버는, 휘도(Luminance) 전용 또는 휘도(Luminance) 알파 표면에 대한 유효한 휘도(Luminance) 비트를 기술한다.
DDPF_BUMPDUDV
픽셀 포맷의 범프 맵 데이터는 유효하다. 범프 맵 정보는,dwBumpBitCount,dwBumpDuBitMask,dwBumpDvBitMask, 및 dwBumpLuminanceBitMask 멤버에 있다.
DDPF_COMPRESSED
표면은 지정된 포맷으로 픽셀 데이터를 받아, 쓰기 처리중에 그 데이터를 압축한다.
DDPF_FOURCC
dwFourCC 멤버는 유효해, 비 RGB 픽셀 포맷을 기술하는 FOURCC 코드를 포함한다.
DDPF_LUMINANCE
픽셀 포맷은, 휘도(Luminance) 전용 또는 휘도(Luminance) 알파 표면을 기술한다.
DDPF_PALETTEINDEXED1
DDPF_PALETTEINDEXED2
DDPF_PALETTEINDEXED4
DDPF_PALETTEINDEXED8
표면은, 1 비트, 2 비트, 4 비트, 또는 8 비트의 색으로 인덱스 되고 있다.
DDPF_PALETTEINDEXEDTO8
표면은, 1 비트, 2 비트, 4 비트의 색을 8 비트 팔레트에 인덱스 하고 있다.
DDPF_RGB
픽셀 포맷 구조체의 RGB 데이터는 유효하다.
DDPF_RGBTOYUV
표면은 RGB 데이터를 받아, 쓰기 처리중에 YUV 데이터에 그 데이터를 변환한다. 기입하는 데이터의 포맷은, 픽셀 포맷 구조체에 포함된다. DDPF_RGB 플래그를 설정한다.
DDPF_STENCILBUFFER
표면은, Z 버퍼의 각각의 픽셀에 있어서의 스텐실과 깊이 정보를 encode 한다. 이 플래그는, DDPF_ZBUFFER 플래그가와 같이 지정되는 경우인 만큼 사용할 수 있다.
DDPF_YUV
픽셀 포맷 구조체의 YUV 데이터는 유효하다.
DDPF_ZBUFFER
픽셀 포맷은, Z 버퍼 전용 표면을 기술한다.
DDPF_ZPIXELS
표면은, 픽셀의 z 정보를 포함한다.
dwFourCC
FOURCC 코드. 상세 정보는, 「4 문자 코드 (FOURCC) 」를 참조할것.
dwRGBBitCount
RGB 비트/픽셀 (4, 8, 16, 24, 또는 32).
dwYUVBitCount
YUV 비트/픽셀 (4, 8, 16, 24, 또는 32).
dwZBufferBitDepth
Z 버퍼 비트 깊이 (8, 16, 24, 또는 32).
dwAlphaBitDepth
알파 전용 표면 (DDPF_ALPHA)을 위한알파 채널 비트 깊이 (1, 2, 4, 또는 8). 알파 정보를 포함한 픽셀 포맷은 색데이터 (DDPF_ALPHAPIXELS)로 인터리브 되기 (위해)때문에,dwRGBAlphaBitMask 멤버의 비트를 카운트 해, 알파 성분의 비트 깊이를 취득한다. 상세 정보는 주의를 참조할것.
dwLuminanceBitCount
총휘도(Luminance) 비트/픽셀. 이 멤버는, 휘도(Luminance) 전용 및 휘도(Luminance) 알파 표면인 만큼 적용한다.
dwBumpBitCount
범프 맵 표면의 총범프 맵 비트/픽셀.
dwRBitMask
빨강 비트의 마스크.
dwYBitMask
Y 비트의 마스크.
dwStencilBitDepth
스텐실 버퍼의 비트 깊이. 이 멤버는, 스텐실 정보의 Z 버퍼의 각 픽셀내에서 확보되는 비트의 수를 지정한다. (z 비트의 총수는 dwZBufferBitDepth 로부터 dwStencilBitDepth 를 뺀 수로 동일하다).
dwLuminanceBitMask
휘도(Luminance) 비트의 마스크.
dwBumpDuBitMask
범프 맵 U 델타 비트의 마스크.
dwGBitMask
초록 비트의 마스크.
dwUBitMask
U 비트의 마스크.
dwZBitMask
z 비트의 마스크.
dwBumpDvBitMask
범프 맵 V 델타 비트의 마스크.
dwBBitMask
파랑 비트의 마스크.
dwVBitMask
V 비트의 마스크.
dwStencilBitMask
각 Z 버퍼 픽셀내의 스텐실 비트의 마스크.
dwBumpLuminanceBitMask
범프 맵 픽셀의 휘도(Luminance)의 마스크.
dwRGBAlphaBitMask,dwYUVAlphaBitMask,dwLuminanceAlphaBitMask
알파 채널의 마스크.
dwRGBZBitMask,dwYUVZBitMask
z 채널의 마스크.

주의

dwAlphaBitDepth 멤버는, 알파 전용 픽셀 포맷 (DDPF_ALPHA)의 비트 깊이를 반영한다. 색성분 (DDPF_ALPHAPIXELS)과 함께 알파 성분을 포함한 픽셀 포맷을 위해서(때문에), 알파 비트 깊이는 다양한 마스크 멤버의 비트를 세는 것으로 취득된다. 다음의 코드예는, 주어진 비트 마스크의 비트 세트수를 돌려준다.

WORD GetNumberOfBits( DWORD dwMask )
{
    WORD wBits = 0;
    while( dwMask )
    {
        dwMask = dwMask & ( dwMask - 1 );
        wBits++;
    }
    return wBits;
}

이 구조체의 집합은, 이름이 없는 집합을 지원 하지 않는 컴파일러로 기능하도록(듯이) 갱신되고 있다. 컴파일러가 이름의 없는 집합을 지원 하지 않는 경우, Ddraw.h 헤더 파일을 인클루드 하기 전에 NONAMELESSUNION 토큰을 정의한다.

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.

참조

오프 스크린 표면 포맷


DDSCAPS

DDSCAPS 구조체는, DirectDrawSurface 오브젝트의 능력을 정의한다. 이 구조체는,DDCAPS 및 DDSURFACEDESC 구조체의 일부이다.

typedef struct _DDSCAPS{
    DWORD dwCaps;
} DDSCAPS, FAR* LPDDSCAPS;

멤버

dwCaps
표면의 능력. 이하의 플래그 가운데, 1 개 이상의 값을 취한다.
DDSCAPS_3D
미대응. 대신에 DDSCAPS_3DDEVICE 를 사용한다.
DDSCAPS_3DDEVICE
이 표면은 3D 렌더링에 사용할 수 있다. 어플리케이션은 이 플래그를 사용해, 디바이스가 적절한 heap로부터 할당할 수 있었던오프 스크린 표면이 있는 특정의 heap만을 렌더링 할 수 있는 것을 보증한다. 이 플래그가 heap에 대해서 설정되어 있는 경우, 표면은 그 heap로부터 할당할 수 없다.
DDSCAPS_ALLOCONLOAD
미사용.
DDSCAPS_ALPHA
이 표면은 알파 전용 정보를 포함한다.
DDSCAPS_BACKBUFFER
이 표면은, 표면 플립핑 구조의백 버퍼이다. 보통, 이 능력은, DDSCAPS_FLIP 플래그가 사용될 때 CreateSurface 메소드로 설정된다. DDSCAPS_FRONTBUFFER 표면의 직전의 표면만, 이 능력이 설정된다. DDSCAPS_FLIP 플래그의 존재, Attach의 순서, 및 DDSCAPS_FRONTBUFFER 와 DDSCAPS_BACKBUFFER 능력의 결여에 의해, 다른 표면이 백 버퍼로서 식별된다. 이 능력이 CreateSurface 메소드에 보내지면(자), 스탠드얼론 백 버퍼를 생성 한다. 이 메소드를 호출한 후, 이 표면은,프런트 버퍼, 다른 백 버퍼, 또는 그 양쪽 모두에 Attach 해플립핑 표면 구조를 형성할 수 있다. 상세한 것에 대하여는, 「IDirectDrawSurface7::AddAttachedSurface 」를 참조할것. DirectDraw 에서는, 프립핑 구조에 표면은 몇개에서도 존재할 수 있다.
DDSCAPS_COMPLEX
복합 표면이 기술된다. 복합 표면은, 2 개(살) 이상의 표면으로부터 생성 된다. 추가 표면은, 루트 표면에 Attach 된다. 복합 표면은, 루트를 파기하는 것만으로 파기할 수 있다.
DDSCAPS_FLIP
이 표면은, 표면 플립핑 구조의 일부이다. 이 능력이 CreateSurface 메소드에게 건네지면(자),프런트 버퍼 및 1 개 이상의백 버퍼가 생성 된다. DirectDraw 는, 프런트 버퍼 표면에 DDSCAPS_FRONTBUFFER 비트, 및 프런트 버퍼 표면에 인접하는 표면에 DDSCAPS_BACKBUFFER 비트를 설정한다. 메소드의 호출이 성공하기 위해서(때문에)는,DDSURFACEDESC 구조체의 dwBackBufferCount 멤버를 적어도 1 으로 설정할 필요가 있다. CreateSurface 메소드로 복수의 표면을 생성 하는 경우, DDSCAPS_COMPLEX 능력을 항상 설정하지 않으면 안 된다.
DDSCAPS_FRONTBUFFER
이 표면은, 표면 플립핑 구조의프런트 버퍼이다. 이 플래그는, 일반적으로는 DDSCAPS_FLIP 능력을 설정할 때에 CreateSurface 메소드에 의해 설정된다. 이 능력이 CreateSurface 메소드에 보내지면(자), 스탠드얼론 프런트 버퍼가 생성 된다. 이 표면에는 DDSCAPS_FLIP 능력이 없다. 이 표면은,IDirectDrawSurface7::AddAttachedSurface 를 사용하는 것으로써,백 버퍼에 Attach 해 플립핑 구조를 형성할 수 있다.
DDSCAPS_HWCODEC
이 표면은, 하드웨어에 의해 압축 해제된 스트림을 가질 수가 있다.
DDSCAPS_LIVEVIDEO
이 표면은, 라이브 비디오를 받을 수가 있다.
DDSCAPS_LOCALVIDMEM
이 표면은, 비로컬 비디오 메모리는 아니고, 진정한 로컬 비디오 메모리에 존재한다. 이 플래그를 지정 하면나무는, DDSCAPS_VIDEOMEMORY 도 지정해야 한다. 이 플래그는, DDSCAPS_NONLOCALVIDMEM 플래그와 함께 사용할 수 없다.
DDSCAPS_MIPMAP
이 표면은,밉맵의 1 개의 레벨이다. 이 표면은, 다른 DDSCAPS_MIPMAP 표면에 Attach 해 밉맵을 형성할 수 있다. 이러한 밉맵의 생성은, 몇개의 표면을 생성 해, 그러한 표면을 IDirectDrawSurface7::AddAttachedSurface 메소드로 Attach 하는 것으로 명시적에 행해지는지,CreateSurface 메소드를 사용해 암묵적으로 행해진다. 이 능력을 설정하는 경우, DDSCAPS_TEXTURE 도 설정하지 않으면 안 된다.
DDSCAPS_MODEX
이 표면은, 320 × 200 또는 320 × 240 의모드 X 표면이다.
DDSCAPS_NONLOCALVIDMEM
이 표면은, 진정한 로컬 비디오 메모리는 아니고, 비로컬 비디오 메모리에 존재한다. 이 플래그를 지정 하면나무는, DDSCAPS_VIDEOMEMORY 플래그도 지정해야 한다. 이것은, DDSCAPS_LOCALVIDMEM 플래그와 함께 사용할 수 없다.
DDSCAPS_OFFSCREENPLAIN
이 표면은오프 스크린 표면이며, 오버레이, 텍스쳐,Z 버퍼, 프런트 버퍼, 백 버퍼, 또는 알파 표면의 머지않아도 아니다. 프레인 표면을 식별하기 위해서 사용된다.
DDSCAPS_OPTIMIZED
현시점에서는, 이행되어 있지 않다.
DDSCAPS_OVERLAY
이 표면은, 오버레이인 이 표면이 직접 표시할 수 있을지 어떨지는, 현시점에서프라이머리 표면에 오버레이 되고 있는지 어떤지에 의해 정해진다. DDSCAPS_VISIBLE 를 사용해, 표면이 현시점에서 오버레이 되고 있는지 어떤지를 판단할 수 있다.
DDSCAPS_OWNDC
이 표면은, 장시간에 걸쳐서 디바이스 콘텍스트 (DC)와 관련을 가진다.
DDSCAPS_PALETTE
이 디바이스 드라이버를 사용 하면, 고유의 DirectDrawPalette 오브젝트를 생성 해 이 표면에 Attach 할 수 있다.
DDSCAPS_PRIMARYSURFACE
표면은,프라이머리 표면이다. 이 표면은 현재의 표시 내용을 나타낸다.
DDSCAPS_STANDARDVGAMODE
이 표면은, 표준 VGA 모드 표면이며, 모드 X 표면은 아니다. 이 플래그는, DDSCAPS_MODEX 플래그의 편성으로 사용할 수 없다.
DDSCAPS_SYSTEMMEMORY
이 표면 메모리는, 시스템 메모리에 할당할 수 있었다.
DDSCAPS_TEXTURE
이 표면은, 3D 텍스쳐로서 사용할 수 있다. 다만, 표면이 현재 3D 텍스쳐로서 사용되고 있는지 어떤지를 나타내는 것은 아니다.
DDSCAPS_VIDEOMEMORY
이 표면은, 디스플레이 메모리에 있다.
DDSCAPS_VIDEOPORT
이 표면은, 비디오 포트로부터 데이터를 받을 수가 있다.
DDSCAPS_VISIBLE
이 표면에의 변경은 곧바로 표시할 수 있다. 이 표면은, 오버레이때의 오버레이나, 텍스쳐 처리때의 텍스쳐 맵에 대해서 설정되는 것 외에도,프라이머리 표면에 대해서 항상 설정된다.
DDSCAPS_WRITEONLY
표면에의 쓰기 전용 액세스가 허가되고 있다. 표면으로부터의 read 액세스는, 일반 보호 (GP) 에러를 발생할 가능성이 있다. 다만, 이 표면으로부터의 read 결과에는 의미가 있다.
DDSCAPS_ZBUFFER
. 이 표면은, Z 버퍼이다. z 버퍼에는, 표시되지 않는 정보를 포함한다. 대신에, Z 버퍼에는, 어느 픽셀이 표시되어 어느 픽셀이 표시되지 않는가를 결정하는데 사용하는 비트 깊이 정보를 포함한다.

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.


DDSCAPS2

DDSCAPS2 구조체는, DirectDrawSurface 오브젝트의 능력을 정의한다. 이 구조체는,DDSURFACEDESC2 구조체의 일부이다.

typedef struct _DDSCAPS2 {
    DWORD    dwCaps;
    DWORD    dwCaps2;
    DWORD    dwCaps3;
    DWORD    dwCaps4;
} DDSCAPS2, FAR* LPDDSCAPS2;

멤버

dwCaps
표면의 능력을 나타내는 이하의 플래그 가운데, 1 개 또는 복수의 값을 지정한다 (이 멤버의 플래그는,DDSCAPS 구조체의 대응하는 멤버의 플래그와 동일하다).
DDSCAPS_3D
미대응. 대신에 DDSCAPS_3DDEVICE 를 사용한다.
DDSCAPS_3DDEVICE
이 표면은, 3D 렌더링에 사용할 수 있다. 어플리케이션은 이 플래그를 사용해, 디바이스가 적절한 heap로부터 할당할 수 있었던오프 스크린 표면이 있는 특정의 heap만을 렌더링 할 수 있는 것을 보증한다. 이 플래그가 heap에 대해서 설정되어 있는 경우, 표면은 그 heap로부터 할당할 수 없다.
DDSCAPS_ALLOCONLOAD
미사용.
DDSCAPS_ALPHA
이 표면은, 알파 전용 정보를 포함한다.
DDSCAPS_BACKBUFFER
이 표면은, 표면 플립핑 구조의백 버퍼이다. 보통, 이 능력은, DDSCAPS_FLIP 플래그가 사용될 때 CreateSurface 메소드로 설정된다. DDSCAPS_FRONTBUFFER 표면의 직전의 표면만, 이 능력이 설정된다. DDSCAPS_FLIP 플래그의 존재, Attach의 순서, 및 DDSCAPS_FRONTBUFFER 와 DDSCAPS_BACKBUFFER 능력의 결여에 의해, 다른 표면이 백 버퍼로서 식별된다. 이 능력이 CreateSurface 메소드에 보내지면(자), 스탠드얼론 백 버퍼를 생성 한다. 이 메소드를 호출한 후, 이 표면은,프런트 버퍼, 다른 백 버퍼, 또는 그 양쪽 모두에 Attach 해플립핑 표면 구조를 형성할 수 있다. 상세한 것에 대하여는, 「IDirectDrawSurface7::AddAttachedSurface 」를 참조할것. DirectDraw 에서는, 프립핑 구조에 표면은 몇개에서도 존재할 수 있다.
DDSCAPS_COMPLEX
복합 표면이 기술된다. 복합 표면은, 2 개(살) 이상의 표면으로부터 생성 된다. 추가 표면은, 루트 표면에 Attach 된다. 복합 표면은, 루트를 파기하는 것만으로 파기할 수 있다.
DDSCAPS_FLIP
이 표면은, 표면 플립핑 구조의 일부이다. 이 능력이 CreateSurface 메소드에게 건네지면(자), 프런트 버퍼 및 1 개 이상의백 버퍼가 생성 된다. DirectDraw 는, 프런트 버퍼 표면에 DDSCAPS_FRONTBUFFER 비트, 및 프런트 버퍼 표면에 인접하는 표면에 DDSCAPS_BACKBUFFER 비트를 설정한다. 메소드의 호출이 성공하기 위해서(때문에)는,DDSURFACEDESC 구조체의 dwBackBufferCount 멤버는 적어도 1 으로 설정할 필요가 있다. CreateSurface 메소드로 복수의 표면을 생성 하는 경우, DDSCAPS_COMPLEX 능력을 항상 설정하지 않으면 안 된다.
DDSCAPS_FRONTBUFFER
이 표면은, 표면 플립핑 구조의 프런트 버퍼이다. 이 플래그는, 일반적으로는 DDSCAPS_FLIP 능력을 설정할 때에 CreateSurface 메소드에 의해 설정된다. 이 능력이 CreateSurface 메소드에 보내지면(자), 스탠드얼론 프런트 버퍼가 생성 된다. 이 표면에는 DDSCAPS_FLIP 능력이 없다. 이 표면은,IDirectDrawSurface7::AddAttachedSurface 를 사용하는 것으로써, 백 버퍼에 Attach 해 플립핑 구조를 형성할 수 있다.
DDSCAPS_HWCODEC
이 표면은, 하드웨어에 의해 압축 해제된 스트림을 가질 수가 있다.
DDSCAPS_LIVEVIDEO
이 표면은, 라이브 비디오를 받을 수가 있다.
DDSCAPS_LOCALVIDMEM
이 표면은, 비로컬 비디오 메모리는 아니고, 진정한 로컬 비디오 메모리에 존재한다. 이 플래그를 지정 하면나무는, DDSCAPS_VIDEOMEMORY 도 지정해야 한다. 이 플래그는, DDSCAPS_NONLOCALVIDMEM 플래그와 함께 사용할 수 없다.
DDSCAPS_MIPMAP
이 표면은,밉맵의 1 개의 레벨이다. 이 표면은, 다른 DDSCAPS_MIPMAP 표면에 Attach 해 밉맵을 형성할 수 있다. 이러한 밉맵의 생성은, 몇개의 표면을 생성 해, 그러한 표면을 IDirectDrawSurface7::AddAttachedSurface 메소드로 Attach 하는 것으로 명시적에 행해지는지,CreateSurface 메소드를 사용해 암묵적으로 행해진다. 이 능력을 설정하는 경우, DDSCAPS_TEXTURE 도 설정하지 않으면 안 된다.
DDSCAPS_MODEX
이 표면이, 320 × 200 또는 320 × 240 의모드 X 표면이다.
DDSCAPS_NONLOCALVIDMEM
이 표면은, 진정한 로컬 비디오 메모리는 아니고, 비로컬 비디오 메모리에 존재한다. 이 플래그를 지정 하면나무는, DDSCAPS_VIDEOMEMORY 플래그도 지정해야 한다. 이것은, DDSCAPS_LOCALVIDMEM 플래그와 함께 사용할 수 없다.
DDSCAPS_OFFSCREENPLAIN
이 표면은,오프 스크린 표면이며, 오버레이, 텍스쳐,Z 버퍼, 프런트 버퍼, 백 버퍼, 또는 알파 표면의 머지않아도 아니다. 프레인 표면을 식별하기 위해서 사용된다.
DDSCAPS_OPTIMIZED
현시점에서는, 이행되어 있지 않다.
DDSCAPS_OVERLAY
이 표면은, 오버레이이다. 이 표면이 직접 표시할 수 있을지 어떨지는, 현시점에서프라이머리 표면에 오버레이 되고 있는지 어떤지에 의해 정해진다. DDSCAPS_VISIBLE 를 사용해, 표면이 현시점에서 오버레이 되고 있는지 어떤지를 판단할 수 있다.
DDSCAPS_OWNDC
이 표면은, 장시간에 걸쳐서 디바이스 콘텍스트 (DC)와 관련을 가진다.
DDSCAPS_PALETTE
이 디바이스 드라이버를 사용 하면, 고유의 DirectDrawPalette 오브젝트를 생성 해 이 표면에 Attach 할 수 있다.
DDSCAPS_PRIMARYSURFACE
표면은, 프라이머리 표면이다. 이 표면은 현재의 표시 내용을 나타낸다.
DDSCAPS_STANDARDVGAMODE
이 표면은, 표준 VGA 모드 표면이며, 모드 X 표면은 아니다. 이 플래그는, DDSCAPS_MODEX 플래그의 편성으로 사용할 수 없다.
DDSCAPS_SYSTEMMEMORY
이 표면 메모리는, 시스템 메모리에 할당할 수 있었다.
DDSCAPS_TEXTURE
이 표면은, 3D 텍스쳐로서 사용할 수 있다. 다만, 표면이 현재 3D 텍스쳐로서 사용되고 있는지 어떤지를 나타내는 것은 아니다.
DDSCAPS_VIDEOMEMORY
이 표면은, 디스플레이 메모리에 있다.
DDSCAPS_VIDEOPORT
이 표면은, 비디오 포트로부터 데이터를 받을 수가 있다.
DDSCAPS_VISIBLE
이 표면에의 변경은 곧바로 표시할 수 있다. 이 표면은, 오버레이때의 오버레이나, 텍스쳐 처리때의 텍스쳐 맵에 대해서 설정되는 것 외에도,프라이머리 표면에 대해서 항상 설정된다.
DDSCAPS_WRITEONLY
표면에의 쓰기 전용 액세스가 허가되고 있다. 표면으로부터의 read 액세스는, 일반 보호 (GP) 에러를 발생할 가능성이 있다. 다만, 이 표면으로부터의 read 결과에는 의미가 있다.
DDSCAPS_ZBUFFER
. 이 표면은, Z 버퍼이다. z 버퍼에는, 표시되지 않는 정보를 포함한다. 대신에, Z 버퍼에는, 어느 픽셀이 표시되어 어느 픽셀이 표시되지 않는가를 결정하는데 사용하는 비트 깊이 정보를 포함한다.
dwCaps2
추가 표면 능력. 이 멤버에는 이하의 능력 플래그를 포함할 수가 있다. 이 구조체를 IDirectDrawSurface7::SetSurfaceDesc 메소드로 사용하는 경우는, 표면 메모리를 할당할 수 있었던 방법을 나타내는 추가 플래그를 포함할 수가 있다.

능력 플래그

DDSCAPS2_CUBEMAP
DirectX 7.0 으로 추가. 이 표면은, 큐브 환경 맵이다. 이 플래그를 사용할때는, 큐브 환경 맵의 어느 표면을 생성 할지도 지정해야 한다.
DDSCAPS2_CUBEMAP_POSITIVEX
DirectX 7.0 으로 추가. 이 플래그는, DDSCAPS2_CUBEMAP 플래그와와도 사용해, 큐브 환경 맵의 정방향의 X 면을 생성 한다.
DDSCAPS2_CUBEMAP_NEGATIVEX
DirectX 7.0 으로 추가. 이 플래그는, DDSCAPS2_CUBEMAP 플래그와 함께 사용해, 큐브 환경 맵의 부방향의 X 면을 생성 한다.
DDSCAPS2_CUBEMAP_POSITIVEY
DirectX 7.0 으로 추가. 이 플래그는, DDSCAPS2_CUBEMAP 플래그와 함께 사용해, 큐브 환경 맵의 정방향의 Y 면을 생성 한다.
DDSCAPS2_CUBEMAP_NEGATIVEY
DirectX 7.0 으로 추가. 이 플래그는, DDSCAPS2_CUBEMAP 플래그와 함께 사용해, 큐브 환경 맵의 부방향의 Y 면을 생성 한다.
DDSCAPS2_CUBEMAP_POSITIVEZ
DirectX 7.0 으로 추가. 이 플래그는, DDSCAPS2_CUBEMAP 플래그와 함께 사용해, 큐브 환경 맵의 정방향의 Z 면을 생성 한다.
DDSCAPS2_CUBEMAP_NEGATIVEZ
DirectX 7.0 으로 추가. 이 플래그는, DDSCAPS2_CUBEMAP 플래그와 함께 사용해, 큐브 환경 맵의 부방향의 Z 면을 생성 한다.
DDSCAPS2_CUBEMAP_ALLFACES
DirectX 7.0 으로 추가. 이 플래그는, DDSCAPS2_CUBEMAP 플래그와 함께 사용해, 큐브 환경 맵의 전 6 면을 생성 한다.
DDSCAPS2_D3DTEXTUREMANAGE
DirectX 7.0 으로 추가. 텍스쳐는, Direct3D 에 의해 항상 관리된다.
DDSCAPS2_DONOTPERSIST
DirectX 7.0 으로 추가. 관리 표면은, 안전하게 소실할 수 있다.
DDSCAPS2_HARDWAREDEINTERLACE
이 표면은, 비인터 레이스 방식 하드웨어를 사용하는 비디오 포트로부터 데이터를 받는다. 이것에 의해, 드라이버는 요구가 있을 듯 하는 외부 버퍼에 메모리를 할당할 수가 있다. DDSCAPS_VIDEOPORT 및 DDSCAPS_OVERLAY 플래그도 설정하지 않으면 안 된다.
DDSCAPS2_HINTANTIALIASING
어플리케이션으로 anti-aliasing를 사용한다. DDSCAPS_3DDEVICE 가와 같이 설정되어 있는 경우에만 유효하다. 상세한 것에 대하여는, 「anti-aliasing」를 참조할것.
DDSCAPS2_HINTDYNAMIC
이 표면은 빈번하게 락 되는 것 (수속 텍스쳐, 다이나믹 라이트 맵등을 (위해)때문에)를 드라이버에 나타낸다. 이 플래그는, 텍스쳐 표면에 대해서만 사용할 수 있다 (DDSCAPS_TEXTURE 플래그는,dwCaps 멤버로 설정한다). 이 플래그는, DDSCAPS2_HINTSTATIC 또는 DDSCAPS2_OPAQUE 플래그와 함께 사용할 수 없다.
DDSCAPS2_HINTSTATIC
이 표면이, 로드에 의해 다시 정리되거나 다시 타일 표시할 수 있는 것을 드라이버에 나타낸다. 이 처리에서는, 텍스쳐의 사이즈를 변경할 수 없다. 어플리케이션은 이러한 비트를 잠글 수 있으므로, 이 처리는 비교적 빠르고, 좌우 대칭에 실행된다 (이 때 퍼포먼스가 저하한다). 이 플래그는, 텍스쳐 표면에 대해서만 사용할 수 있다 (DDSCAPS_TEXTURE 플래그는,dwCaps 멤버로 설정한다). 이 플래그는, DDSCAPS2_HINTDYNAMIC 또는 DDSCAPS2_OPAQUE 플래그와 함께 사용할 수 없다.
DDSCAPS2_MIPMAPSUBLEVEL
DirectX 7.0 으로 추가. 이 플래그를 사용 하면, 루트 표면에 복수의 밉맵 표면이 Attach 된 큐브 맵등의 표면 구조에 대해서는,EnumAttachedSurfaces 보다 GetAttachedSurface 가 간단하게 사용할 수 있게 된다. 이 플래그는, 밉맵화 큐브 맵내의 최상정도 레벨 이외의 표면 모두로 설정할 필요가 있다. 이것에 의해,GetAttachedSurface 를 호출했을 때에 최상정도 레벨 표면과 Attach 된 밉맵 레벨을 구별할 수 있다. CreateSurface 는 이 능력 비트를 무시한다.
DDSCAPS2_OPAQUE
이 표면이, 결코 재락 되지 않는 것을 드라이버에 나타낸다. 드라이버는, 재타일 표시 및 압축에 의해, 이 표면을 자유롭게 최적화할 수 있다. 이러한 표면은 잠그거나 블리트 처리로 사용할 수 없다. 따라서, 이 능력으로 표면을 락 또는 블리트 하려고 하면(자) 실패한다. 이 플래그는, 텍스쳐 표면에 대해서만 사용할 수 있다 (DDSCAPS_TEXTURE 플래그는,dwCaps 멤버로 설정한다). 이 플래그는, DDSCAPS2_HINTDYNAMIC 또는 DDSCAPS2_HINTSTATIC 플래그와 함께 사용할 수 없다.
DDSCAPS2_STEREOSURFACELEFT
DirectX 7.0 으로 추가. 이 표면은, 스테레오 플립핑 체인의 일부이다. IDirectDraw7::CreateSurface 의 호출로 이 플래그를 설정 하면, 프라이머리 플립핑 체인의 각각의 버퍼에 대해서 스테레오 표면의 페어가 생성 된다. 복합 플립핑 체인을 생성 할 필요가 있다 (백 버퍼로). 스테레오 표면의 단일 세트를 생성 할 수 없다. IDirectDrawSurface7::Flip 메소드에서는 백 버퍼가 필요하기 때문에, 적어도 4 개의 표면을 생성 해야 한다.

또, 이 플래그를 IDirectDraw7::EnumDisplayModes 또는 IDirectDraw7::GetDisplayMode 의 호출의 결과로서 DDSURFACEDESC 구조체로 설정 하면, 그 모드에 있어서의 스테레오의 지원이 나타난다.

DDSCAPS2_TEXTUREMANAGE
드라이버에 관리 능력이 있는 경우, 클라이언트는 이 텍스쳐 표면을 드라이버로 관리하는 것을 요구한다. 드라이버에 그 능력이 없는 경우는, 이 텍스쳐 표면은 Direct3D 직접 모드 (DirectX 7.0 에서의 신기능)로 관리된다. 이 플래그는, 텍스쳐 표면에 대해서만 사용할 수 있다 (DDSCAPS_TEXTURE 플래그는,dwCaps 멤버로 설정한다). 상세한 것에 대하여는, Direct3D 직접 모드의 문서의 「자동 텍스쳐 관리」를 참조할것. 어플리케이션으로 Direct3D 보관 유지 모드를 사용하는 경우는, 이 플래그를 사용하지 않는 것. 대신에, 시스템 메모리에 텍스쳐를 생성 해, 그러한 텍스쳐를 보관 유지 모드로 관리한다.
dwCaps3,dwCaps4
현시점에서는, 미사용이다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.


DDSURFACEDESC

DDSURFACEDESC 구조체는, 표면의 기술을 포함한다. 이 구조체는,IDirectDraw2::CreateSurface 메소드에게 건네진다. 관계하는 멤버는, 표면의 각각의 타입에 의해 다르다.

IDirectDraw7 인터페이스를 사용하는 경우, 이 표면은 DDSURFACEDESC2 구조체에 의해 옮겨놓을 수 있다.

typedef struct _DDSURFACEDESC {
    DWORD          dwSize;
    DWORD          dwFlags;
    DWORD          dwHeight;
    DWORD          dwWidth;
    union
    {
        LONG       lPitch;
        DWORD      dwLinearSize;
    };
    DWORD          dwBackBufferCount;
    union
    {
        DWORD      dwMipMapCount;
        DWORD      dwZBufferBitDepth;
        DWORD      dwRefreshRate;
    };
    DWORD          dwAlphaBitDepth;
    DWORD          dwReserved;
    LPVOID         lpSurface;
    DDCOLORKEY     ddckCKDestOverlay;
    DDCOLORKEY     ddckCKDestBlt;
    DDCOLORKEY     ddckCKSrcOverlay;
    DDCOLORKEY     ddckCKSrcBlt;
    DDPIXELFORMAT  ddpfPixelFormat;
    DDSCAPS        ddsCaps;
} DDSURFACEDESC, FAR* LPDDSURFACEDESC;

멤버

dwSize
바이트 단위의 구조체의 사이즈. 이 멤버는, 구조체를 사용하기 전에 초기화하지 않으면 안 된다.
dwFlags
옵션 제어 플래그. 이하의 플래그 가운데, 1 개 이상의 값을 취한다.
DDSD_ALL
입력 멤버는 모두 유효하다.
DDSD_ALPHABITDEPTH
dwAlphaBitDepth 멤버는 유효하다.
DDSD_BACKBUFFERCOUNT
dwBackBufferCount 멤버는 유효하다.
DDSD_CAPS
ddsCaps 멤버는 유효하다.
DDSD_CKDESTBLT
ddckCKDestBlt 멤버는 유효하다.
DDSD_CKDESTOVERLAY
ddckCKDestOverlay 멤버는 유효하다.
DDSD_CKSRCBLT
ddckCKSrcBlt 멤버는 유효하다.
DDSD_CKSRCOVERLAY
ddckCKSrcOverlay 멤버는 유효하다.
DDSD_HEIGHT
dwHeight 멤버는 유효하다.
DDSD_LINEARSIZE
dwLinearSize 멤버는 유효하다.
DDSD_LPSURFACE
lpSurface 멤버는 유효하다.
DDSD_MIPMAPCOUNT
dwMipMapCount 멤버는 유효하다.
DDSD_PITCH
lPitch 멤버는 유효하다.
DDSD_PIXELFORMAT
ddpfPixelFormat 멤버는 유효하다.
DDSD_REFRESHRATE
dwRefreshRate 멤버는 유효하다.
DDSD_WIDTH
dwWidth 멤버는 유효하다.
DDSD_ZBUFFERBITDEPTH
dwZBufferBitDepth 멤버는 유효하다.
dwHeight,dwWidth
픽셀 단위로 생성 하려고 하는 표면의 넓이.
lPitch
다음의 라인의 시작까지의 바이트 단위의 거리. IDirectDrawSurface7::GetSurfaceDesc 메소드를 사용하는 경우, 이것은 반환값이 된다. 기존의 메모리로부터 표면을 생성 하는 경우, 또는 IDirectDrawSurface7::SetSurfaceDesc 메소드를 호출하는 경우, 이것은 입력값이 된다. 이 입력값은 DWORD 의 배수가 아니면 안된다.
dwLinearSize
버퍼의 사이즈. 현시점에서는, 압축된 텍스쳐 표면 (을) 위해서만 돌려주어진다.
dwBackBufferCount
백 버퍼의 수.
dwMipMapCount
밉맵 레벨의 수.
dwZBufferBitDepth
Z 버퍼의 깊이. 이 멤버는, DirectX 6.0 이후의 버젼을 위해서(때문에) 취득된다. IDirect3D7::EnumZBufferFormats 를 사용해, 지원 되는 깊이 버퍼 포맷의 정보를 취득한다.
dwRefreshRate
refresh rate (디스플레이 모드를 기술하는 경우에 사용). 이 값이 0 의 경우, 어댑터 디폴트를 나타낸다.
dwAlphaBitDepth
알파 버퍼의 깊이.
dwReserved
장래적인 사용을 위해서(때문에) 확보되고 있다.
lpSurface
관련지을 수 있었던 표면 메모리의 주소. IDirectDrawSurface7::Lock 를 호출하면, 호출이 돌아온 후, 이 멤버는 표면 메모리에의 유효한 포인터를 포함한다. 기존의 메모리로부터 표면을 생성 하는 경우, 또는 IDirectDrawSurface7::SetSurfaceDesc 메소드를 사용하는 경우, 이 멤버는 입력값이 된다. 이 입력값이란, 호출측 어플리케이션에 의해 할당할 수 있었던 시스템 메모리의 주소이다. 어플리케이션이 표면 메모리의 할당이나 관리를 위해서(때문에) DirectDraw 를 필요로 하는 경우, 이 멤버를 설정할 수 없다.
ddckCKDestOverlay
오버레이 표면의목적지 컬러 키를 기술하는 DDCOLORKEY 구조체.
ddckCKDestBlt
블리트 처리의 목적지 컬러 키를 기술하는 DDCOLORKEY 구조체.
ddckCKSrcOverlay
오버레이 표면의전송원컬러 키를 기술하는 DDCOLORKEY 구조체.
ddckCKSrcBlt
블리트 처리의 전송원컬러 키를 기술하는 DDCOLORKEY 구조체.
ddpfPixelFormat
표면의 픽셀 포맷을 기술하는 DDPIXELFORMAT 구조체.
ddsCaps
표면의 능력을 포함한 DDSCAPS 구조체.

주의

이 구조체는 DDSURFACEDESC2 구조체 와 유사하지만,DDSCAPS2 구조체는 아니고 ddsCaps 멤버로서 DDSCAPS 구조체를 포함하고 있다. DDSURFACEDESC2 과는 달리, 이 구조체는 dwZBufferBitDepth 멤버를 포함한다.

동작환경

Windows NT/2000 : Windows NT 4.0 Service Pack 3 또는 그 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.


DDSURFACEDESC2

DDSURFACEDESC2 구조체는, 표면의 기술을 포함한다. 이 구조체는, 표면 파라미터를 IDirectDraw7::CreateSurface 및 IDirectDrawSurface7::SetSurfaceDesc 메소드에 건네주기 위해서(때문에) 사용된다. 이 구조체는, 또,IDirectDrawSurface7::Lock 및 IDirectDrawSurface7::GetSurfaceDesc 의 호출로 표면 정보를 취득하기 위해서 사용된다. 관계하는 멤버는, 표면의 각각의 타입에 의해 다르다.

typedef struct _DDSURFACEDESC2 {
    DWORD         dwSize;
    DWORD         dwFlags;
    DWORD         dwHeight;
    DWORD         dwWidth;
    union
    {
        LONG      lPitch;
        DWORD     dwLinearSize;
    } DUMMYUNIONNAMEN(1);
    DWORD         dwBackBufferCount;
    union
    {
        DWORD     dwMipMapCount;
        DWORD     dwRefreshRate;
    } DUMMYUNIONNAMEN(2);
    DWORD         dwAlphaBitDepth;
    DWORD         dwReserved;
    LPVOID        lpSurface;
    union
    {
        DDCOLORKEY    ddckCKDestOverlay;
        DWORD         dwEmptyFaceColor;
    } DUMMYUNIONNAMEN(3);
    DDCOLORKEY    ddckCKDestBlt;
    DDCOLORKEY    ddckCKSrcOverlay;
    DDCOLORKEY    ddckCKSrcBlt;
    DDPIXELFORMAT ddpfPixelFormat;
    DDSCAPS2      ddsCaps;
    DWORD         dwTextureStage;
} DDSURFACEDESC2, FAR* LPDDSURFACEDESC2;

멤버

dwSize
바이트 단위의 구조체의 사이즈. 이 멤버는, 구조체를 사용하기 전에 초기화하지 않으면 안 된다.
dwFlags
옵션 제어 플래그. 이하의 플래그 가운데, 1 개 이상의 값을 취한다.
DDSD_ALL
입력 멤버는 모두 유효하다.
DDSD_ALPHABITDEPTH
dwAlphaBitDepth 멤버는 유효하다.
DDSD_BACKBUFFERCOUNT
dwBackBufferCount 멤버는 유효하다.
DDSD_CAPS
ddsCaps 멤버는 유효하다.
DDSD_CKDESTBLT
ddckCKDestBlt 멤버는 유효하다.
DDSD_CKDESTOVERLAY
ddckCKDestOverlay 멤버는 유효하다.
DDSD_CKSRCBLT
ddckCKSrcBlt 멤버는 유효하다.
DDSD_CKSRCOVERLAY
ddckCKSrcOverlay 멤버는 유효하다.
DDSD_HEIGHT
dwHeight 멤버는 유효하다.
DDSD_LINEARSIZE
dwLinearSize 멤버는 유효하다.
DDSD_LPSURFACE
IpSurface 멤버는 유효하다.
DDSD_MIPMAPCOUNT
dwMipMapCount 멤버는 유효하다.
DDSD_PITCH
IPitch 멤버는 유효하다.
DDSD_PIXELFORMAT
ddpfPixelFormat 멤버는 유효하다.
DDSD_REFRESHRATE
dwRefreshRate 멤버는 유효하다.
DDSD_TEXTURESTAGE
dwTextureStage 멤버는 유효하다.
DDSD_WIDTH
dwWidth 멤버는 유효하다.
DDSD_ZBUFFERBITDEPTH
폐지. 「주의」를 참조할것.
dwHeight,dwWidth
픽셀 단위로 생성 하려고 하는 표면의 넓이.
lPitch
다음의 라인의 시작까지의 바이트 단위의 거리. IDirectDrawSurface7：:GetSurfaceDesc 메소드를 사용하는 경우, 이것은 반환값이 된다. IDirectDrawSurface7::SetSurfaceDesc 메소드와 사용하는 경우, 이것은 입력값이 된다. 이 입력값은 DWORD 의 배수가 아니면 안 된다. 상세 정보는 주의를 참조할것.
dwLinearSize
버퍼의 사이즈. 현시점에서는, 압축된 텍스쳐 표면 (을) 위해서만 돌려주어진다.
dwBackBufferCount
백 버퍼의 수.
dwMipMapCount
밉맵 레벨의 수.
dwRefreshRate
refresh rate (디스플레이 모드를 기술하는 경우에 사용). 이 값이 0 의 경우, 어댑터 디폴트를 나타낸다.
dwAlphaBitDepth
알파 버퍼의 깊이.
dwReserved
장래적인 사용을 위해서(때문에) 확보되고 있다.
lpSurface
관련지을 수 있었던 표면 메모리의 주소. IDirectDrawSurface7::Lock 를 호출하는 경우, 이 멤버는 표면 메모리에의 유효한 포인터가 된다. IDirectDrawSurface7::SetSurfaceDesc 를 호출하는 경우, 이 멤버는 호출해 옆이 DirectDrawSurface 오브젝트에 명시적으로 할당하는 시스템 메모리에의 포인터가 된다. 상세 정보는 주의를 참조할것.
ddckCKDestOverlay
오버레이 표면의목적지 컬러 키를 기술하는 DDCOLORKEY 구조체.
dwEmptyFaceColor
하늘의 큐브 맵면의 물리적인 색.
ddckCKDestBlt
블리트 처리의 목적지 컬러 키를 기술하는 DDCOLORKEY 구조체.
ddckCKSrcOverlay
오버레이 표면의전송원컬러 키를 기술하는 DDCOLORKEY 구조체.
ddckCKSrcBlt
블리트 처리의 전송원컬러 키를 기술하는 DDCOLORKEY 구조체.
ddpfPixelFormat
표면의 픽셀 포맷을 기술하는 DDPIXELFORMAT 구조체.
ddsCaps
표면의 능력을 포함한 DDSCAPS2 구조체.
dwTextureStage
멀티 텍스쳐 cascade 3D 디바이스의 특정의 스테이지에 텍스쳐를 바인드 하기 위해서 사용하는 스테이지 식별자. 모든 하드웨어에 필요하지 않지만, 이 멤버의 설정은 3-D 가속기의 다양성에 대해서, 최적인 퍼포먼스를 준다. 명시적으로 할당할 수 있었던 텍스쳐를 요구하는 하드웨어는,IDirect3DDevice7::GetCaps 메소드로 값을 설정하는 D3DDEVICEDESC 구조체의 D3DDEVCAPS_SEPARATETEXTUREMEMORIES 3-D 디바이스 능력을 공개한다.

주의

IDirectDrawSurface7::GetSurfaceDesc 메소드를 호출하는 경우,lPitch 및 lpSurface 멤버는 출력값이 된다. 기존의 메모리로부터 표면을 생성 하거나 표면 특성을 갱신하고 있는 경우, 이러한 멤버는 입력값이 된다. 이 입력값은, DirectDraw 로 사용되는 호출측의 어플리케이션에 의해 할당할 수 있었던 메모리의 피치와 위치를 기술한다. DirectDraw 는, 어플리케이션이 할당한 메모리를 관리하거나 릴리즈 하려고 하지 않는다. 상세한 것에 대하여는, 「클라이언트 메모리 표면의 생성」 및 「표면 특성의 갱신」을 참조할것.

이 구조체는 DDSURFACEDESC 구조체와 거의 같지만,DDSCAPS2 구조체를 ddsCaps 멤버로서 포함한다. DDSURFACEDESC 과는 달리, 이 구조체는 dwZBufferBitDepth 멤버를 포함하지 않는다. Z 버퍼 깊이는,ddpfPixelFormat 멤버로 제공된다.

이 구조체의 집합은, 이름이 없는 집합을 지원 하지 않는 컴파일러에서도 기능한다. 컴파일러가 이름의 없는 집합을 지원 하지 않는 경우는, Ddraw.h 헤더 파일을 인클루드 하기 전에 NONAMELESSUNION 토큰을 정의한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : ddraw.h 로 선언.


DDVIDEOPORTBANDWIDTH

DDVIDEOPORTBANDWIDTH 구조체는, 특정의 비디오 포트와 픽셀 포맷 구성과 함께 사용하는 경우, 오버레이 표면의 대역폭 특성을 기술한다. 이 구조체는,IDirectDrawVideoPort::GetBandwidthInfo 메소드와 함께 사용된다.

typedef struct _DDVIDEOPORTBANDWIDTH {
    DWORD dwSize;
    DWORD dwCaps;
    DWORD dwOverlay;
    DWORD dwColorkey;
    DWORD dwYInterpolate;
    DWORD dwYInterpAndColorkey;
    DWORD dwReserved1;
    DWORD dwReserved2;
} DDVIDEOPORTBANDWIDTH, *LPDDVIDEOPORTBANDWIDTH;

멤버

dwSize
바이트 단위의 이 구조체의 사이즈. 이 멤버는, 구조체를 사용하기 전에 초기화하지 않으면 안 된다.
dwCaps
디바이스 의존을 지정하는 플래그값. 이 멤버는, 이하의 어느쪽이든 1 개의 값을 취한다.
DDVPBCAPS_DESTINATION
이 디바이스의 능력은, 오버레이의 최소 신축(스트레치) 계수의 점으로부터 기술된다. 이 디바이스에 대해서 제공되는 대역폭 정보는, 목적지 오버레이 사이즈에 관련한다.
DDVPBCAPS_SOURCE
이 디바이스의 능력은, 요구되는 전송원오버레이 사이즈의 관점으로부터 기술된다. 이 디바이스에 대해서 제공되는 대역폭 정보는, 전송원오버레이 사이즈에 관련한다.
dwOverlay
오버레이가 지원 되는 장소의 신축(스트레치) 계수, 또는 오버레이 전송원사이즈를 1000 배가 된 값. 예를 들어, 1.3 = 1300, 혹은 . 75 = 750.
dwColorkey
컬러 키잉이 있는 오버레이가 지원 되는 신축(스트레치) 계수, 또는 오버레이 전송원사이즈를 1000 배가 된 값. 예를 들어, 1.3 = 1300, 혹은 . 75 = 750.
dwYInterpolate
y 축보간이 있는 오버레이가 지원 되는 장소의 신축(스트레치) 계수, 또는 오버레이 전송원사이즈를 1000 배가 된 값. 예를 들어, 1.3 = 1300, 혹은 . 75 = 750.
dwYInterpAndColorkey
y 축보간 및 컬러 키잉이 있는 오버레이가 지원 되는 장소의 신축(스트레치) 계수, 또는 오버레이 전송원사이즈를 1000 배가 된 값. 예를 들어, 1.3 = 1300, 혹은 . 75 = 750.
dwReserved1,dwReserved2
향후를 위해서(때문에) 확보되고 있다. 0 을 설정한다.

주의

DDVPBCAPS_DESTINATION 를 지정 하면, 다른 멤버로 기술되는 신축(스트레치) 계수는,GetBandwidthInfo 메소드의 호출로 주어지는 넓이로 오버레이를 표시하는데 필요한 최소 신축(스트레치) 계수를 기술한다. 신축(스트레치) 계수값이 1000 미만의 경우, 표시 시에 비디오 포트는 오버레이를 수축하는 능력을 가진다. 신축(스트레치) 계수값이 1000 을 넘는 경우는, 오버레이를 표시하기 위해서 오버레이를 신축(스트레치) 해 전송원보다 크게 할 필요가 있다.

DDVPBCAPS_SOURCE 를 지정 하면, 다른 멤버에 기술되고 있는 신축(스트레치) 계수는, 오버레이를 표시하기 위해서 오버레이 전송원을 어느 정도 수축할 필요가 있는지를 나타낸다. 이 경우, 최적값은 1000 으로, 수축이 필요없는 것을 의미한다. 값이 1000 보다 작은 경우,GetBandwidthInfo 의 호출 시에 지정한 전송원직사각형이 너무 큰 것을 의미한다. 예를 들어, 신축(스트레치) 계수가 750 으로 dwWidth 파라미터에 320 픽셀을 지정했을 경우, 그 사이즈에서는 오버레이를 표시할 수 없다. 오버레이를 표시하려면 , 240 픽셀폭의 전송원직사각형을 사용해야 한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.


DDVIDEOPORTCAPS

DDVIDEOPORTCAPS 구조체는, 비디오 포트의 능력과 아라이먼트 제한을 기술한다. 이 구조체는,IDDVideoPortContainer::EnumVideoPorts 메소드와 함께 사용된다.

typedef struct _DDVIDEOPORTCAPS {
    DWORD dwSize;
    DWORD dwFlags;
    DWORD dwMaxWidth;
    DWORD dwMaxVBIWidth;
    DWORD dwMaxHeight;
    DWORD dwVideoPortID;
    DWORD dwCaps;
    DWORD dwFX;
    DWORD dwNumAutoFlipSurfaces;
    DWORD dwAlignVideoPortBoundary;
    DWORD dwAlignVideoPortPrescaleWidth;
    DWORD dwAlignVideoPortCropBoundary;
    DWORD dwAlignVideoPortCropWidth;
    DWORD dwPreshrinkXStep;
    DWORD dwPreshrinkYStep;
    DWORD dwNumVBIAutoFlipSurfaces;
    DWORD dwNumPreferredAutoflip;
    WORD  wNumFilterTapsX;
    WORD  wNumFilterTapsY;
} DDVIDEOPORTCAPS, *LPDDVIDEOPORTCAPS;

멤버

dwSize
바이트 단위의 구조체의 사이즈. 이 멤버는, 구조체를 사용하기 전에 초기화해야 한다.
dwFlags
유효한 데이터를 포함한 필드를 나타내는 플래그값. 이하의 플래그가 정의되고 있다.
DDVPD_AUTOFLIP
dwNumAutoFlipSurfaces 멤버는 유효하다.
DDVPD_ALIGN
dwAlignVideoPortBoundary,dwAlignVideoPortPrescaleWidth,dwAlignVideoPortCropBoundary, 및 dwAlignVideoPortCropWidth 멤버는 유효하다.
DDVPD_CAPS
dwCaps 멤버는 유효하다.
DDVPD_FILTERQUALITY
wNumFilterTapsX 및 wNumFilterTapsY 멤버는 유효하다.
DDVPD_FX
dwFX 멤버는 유효하다.
DDVPD_HEIGHT
dwMaxHeight 멤버는 유효하다.
DDVPD_ID
dwVideoPortID 멤버는 유효하다.
DDVPD_PREFERREDAUTOFLIP
dwNumPreferredAutoflip 멤버는 유효하다.
DDVPD_WIDTH
dwMaxWidth 멤버는 유효하다.
dwMaxWidth
비디오 포트 필드의 최대폭 .
dwMaxVBIWidth
VBI 데이터의 최대폭.
dwMaxHeight
비디오 포트 필드의 최대 높이.
dwVideoPortID
비디오 포트를 식별하는 제로 베이스의 인덱스.
dwCaps
이하에, 비디오 포트 능력을 나타낸다.
DDVPCAPS_AUTOFLIP
VREF 때,티어링을 방지하기 위해서 플립을 자동적으로 실행한다. 데이터가 메모리내에서 인터리브 되고 있는 경우, VREF 의 1 회 간격으로 플립 한다.
DDVPCAPS_COLORCONTROL
frame buffer에 기입하기 전에, 도착 데이터에 컬러 컨트롤 처리를 실시할 수 있다.
DDVPCAPS_INTERLACED
인터 레이스 방식 비디오를 지원 한다.
DDVPCAPS_NONINTERLACED
비인터 레이스 방식 비디오를 지원 한다.
DDVPCAPS_OVERSAMPLEDVBI
일반의 비디오 데이터와는 다른 포맷 또는폭의 VBI 데이터를 받는다.
DDVPCAPS_READBACKFIELD
IDirectDrawVideoPort::GetFieldPolarity 메소드를 지원 한다.
DDVPCAPS_READBACKLINE
IDirectDrawVideoPort::GetVideoLine 메소드를 지원 한다.
DDVPCAPS_SHAREABLE
비디오 포트를 공유하는 2 개의젠록킹 비디오 스트림을 지원 한다. 한편의 스트림은 짝수 필드를 사용해, 이제(벌써) 한편의 스트림은 홀수 필드를 사용한다. 각 파라미터 (주소, 스케일링, 크로핑등)는 각각의 필드에 대해서 유지된다.
DDVPCAPS_SKIPEVENFIELDS
비디오의 짝수 필드를 자동적으로 파기할 수 있다.
DDVPCAPS_SKIPODDFIELDS
비디오의 홀수 필드를 자동적으로 파기할 수 있다.
DDVPCAPS_SYNCMASTER
비디오 포트 동기에 근거해 그래픽스 동기 (refresh rate)를 실행할 수 있다.
DDVPCAPS_SYSTEMMEMORY
시스템 메모리에 생성 된 표면에 쓰기를 실행할 수 있다.
DDVPCAPS_VBIANDVIDEOINDEPENDENT
비디오 스트림의 VBI 및 비디오 부분은, 독립한 프로세스로 제어할 수 있다.
DDVPCAPS_VBISURFACE
VBI 내의 데이터를 다른 표면에 기입할 수가 있다.
dwFX
이하에, 추가 비디오 포트 능력을 나타낸다.
DDVPFX_CROPTOPDATA
VBI 데이터를 도려내기 위해서(때문에), 제한부 크로핑을 이용할 수 있다.
DDVPFX_CROPX
표면에 기입해지기 전에, 도착 데이터를 x 방향으로 도려낼 수 있다.
DDVPFX_CROPY
표면에 기입해지기 전에, 도착 데이터를 y 방향으로 도려낼 수 있다.
DDVPFX_IGNOREVBIXCROP
오버 샘플 되는 VBI 데이터를 도려내는 경우, 비디오 포트는 좌우의 크로핑 좌표를 무시할 수 있다.
DDVPFX_INTERLEAVE
메모리의 인터 레이스 필드의 인터리브를 지원 한다.
DDVPFX_MIRRORLEFTRIGHT
비디오 데이터를 frame buffer에 기입할 때에, 좌우의 미러링을 지원 한다.
DDVPFX_MIRRORUPDOWN
비디오 데이터를 frame buffer에 기입할 때에, 상하의 미러링을 지원 한다.
DDVPFX_PRESHRINKX
표면에 기술되기 전에, 데이터는 x 방향으로 임의에 수축할 수 있다.
DDVPFX_PRESHRINKY
표면에 기술되기 전에, 데이터는 y 방향으로 임의에 수축할 수 있다.
DDVPFX_PRESHRINKXB
표면에 기술되기 전에, 데이터는 x 방향으로 바이너리 수축 (1/2,1/4,1/8 등)할 수 있다.
DDVPFX_PRESHRINKYB
표면에 기술되기 전에, 데이터는 y 방향으로 바이너리 수축 (1/2,1/4,1/8 등)할 수 있다.
DDVPCAPS_PRESHRINKXS
데이터는 x 방향으로 1/x 의 인크리먼트(increment)로 수축할 수 있다. 여기서,x 는 dwShrinkXStep 멤버로 지정된다.
DDVPCAPS_PRESHRINKYS
데이터는 y 방향으로 1/y 의 인크리먼트(increment)로 수축할 수 있다. 여기서,y 는 dwShrinkYStep 멤버로 지정된다.
DDVPFX_PRESTRETCHX
표면에 기술되기 전에, 데이터는 x 방향으로 임의에 신축(스트레치) 할 수 있다.
DDVPFX_PRESTRETCHY
표면에 기술되기 전에, 데이터는 y 방향으로 임의에 신축(스트레치) 할 수 있다.
DDVPFX_PRESTRETCHXN
표면에 기입하기 전에, 데이터는 x 방향으로 정수 신축(스트레치) 할 수 있다 (1 ×, 2 ×, 3 ×등).
DDVPFX_PRESTRETCHYN
표면에 기입하기 전에, 데이터는 y 방향으로 정수 신축(스트레치) 할 수 있다 (1 ×, 2 ×, 3 ×등).
DDVPFX_VBICONVERT
VBI 내의 데이터를 나머지의 비디오 데이터 (와)는 관계없는 것으로 변환할 수 있다.
DDVPFX_VBINOINTERLEAVE
인터리브는, VBI 의 데이터에 대해서 무효로 된다.
DDVPFX_VBINOSCALE
스케일링은, VBI 내의 데이터에 대해서 무효로 된다.
dwNumAutoFlipSurfaces
비디오 포트가 지원 하는 자동 플립 가능한 표면의 최대수.
dwAlignVideoPortBoundary
표면내의 배치의 바이트 제한.
dwAlignVideoPortPrescaleWidth
프리스케이링 후의폭의 바이트 제한.
dwAlignVideoPortCropBoundary
왼쪽 크로핑의 바이트 제한.
dwAlignVideoPortCropWidth
크로핑폭의 바이트 제한.
dwPreshrinkXStep
1/dwPreshrinkXStep 의 스텝에서, 폭을 x 방향으로 수축할 수 있다.
dwPreshrinkYStep
1/dwPreshrinkYSte 의 스텝에서, 높이를 y 방향으로 수축할 수 있다.
dwNumVBIAutoFlipSurfaces
나머지의 비디오 스트림에 의존하지 않고 , 수직귀선소거 간격 (VBI)의 사이에 전송 된 데이터의 수취가 가능한 자동 플립핑 표면의 수. 자동 플립핑 체인을 구축하는 경우, VBI 표면의 수는, 나머지의 비디오 데이터를 받는 표면의 수로 동일하게 할 필요가 있다.
dwNumPreferredAutoflip
하드웨어가 지원 하는 자동 플립 가능 표면의 최적인 수.
wNumFilterTapsX,wNumFilterTapsY
프레스 케일 필터가 x 및 y 방향으로 사용하는 탭수. 예를 들어, 값이 0 이라고, 프레스 케이 링은 그 방향으로 실행되지 않는다. 값이 1 이라고, 프레스 케일은 대응하는 수로 실행한다. 값이 2 라고, 프레스 케일은 2 살의 탭을 사용한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.


DDVIDEOPORTCONNECT

DDVIDEOPORTCONNECT 구조체는, 비디오 포트 connection를 기술한다. 이 구조체는,IDDVideoPortContainer::GetVideoPortConnectInfo 메소드와 함께 사용한다.

typedef struct _DDVIDEOPORTCONNECT{
    DWORD dwSize;
    DWORD dwPortWidth;
    GUID  guidTypeID;
    DWORD dwFlags;
    ULONG_PTR dwReserved1;
} DDVIDEOPORTCONNECT, *LPDDVIDEOPORTCONNECT;

멤버

dwSize
바이트 단위의 구조체의 사이즈. 이 멤버는, 구조체를 사용하기 전에 초기화하지 않으면 안 된다.
dwPortWidth
비디오 포트의 폭. 이 값은, 메모리의 표면의폭은 아니고, 비디오 포트의 물리 핀의 수를 나타낸다. 이 멤버는,guidTypeID 의 값이 있는 정해진 사이즈를 취하는 경우에서도, 항상 설정하지 않으면 안 된다.
guidTypeID
비디오 포트의 동기 특성을 기술하는 GUID. 다음의 포트 타입이 미리 정의되고 있다.
DDVPTYPE_E_HREFH_VREFH
HREF 가 액티브 하이로, VREF 가 액티브 하이인 장소의 외부 동기.
DDVPTYPE_E_HREFH_VREFL
HREF 가 액티브 하이로, VREF 가 액티브 로인 장소의 외부 동기.
DDVPTYPE_E_HREFL_VREFH
HREF 가 액티브 로로, VREF 가 액티브 하이인 장소의 외부 동기.
DDVPTYPE_E_HREFL_VREFL
HREF 가 액티브 로로, VREF 가 액티브 로인 장소의 외부 동기.
DDVPTYPE_CCIR656
CCIR656 사양에 따라, 데이터 스트림에 동기 정보를 짜넣는다.
DDVPTYPE_BROOKTREE
Brooktree 정의를 사용해, 데이터 스트림에 동기 정보를 짜넣는다.
DDVPTYPE_PHILIPS
Philips 정의를 사용해, 데이터 스트림에 동기 정보를 짜넣는다.
dwFlags
비디오 포트 connection의 능력을 기술하는 플래그. 이 멤버는, connection 정보를 취득할 경우에 DirectDraw 에 의해, 또는 connection 정보를 설정할 경우에 클라이언트에 의해 설정할 수 있다. 이 멤버는, 다음의 플래그의 편성이 된다.
DDVPCONNECT_DOUBLECLOCK
비디오 포트는 더블 클록킹 데이터를 지원 하는지, 데이터를 더블 클럭 할 필요가 있다. 이 플래그는, 외부 동기인 만큼 유효하다.
DDVPCONNECT_VACT
비디오 포트는 외부 VACT 신호의 사용을 지원 하는지, 외부 VACT 신호를 사용할 필요가 있다. 이 플래그는, 외부 동기인 만큼 유효하다.
DDVPCONNECT_INVERTPOLARITY
비디오 포트는 필드극성을 반전하는 능력을 가지는지,필드극성을 반전한다.

비디오 포트가 필드극성을 반전시키는 경우, 짝수 필드를 홀수 필드로서 처리해, 역의 경우도 마찬가지이다.

DDVPCONNECT_DISCARDSVREFDATA
비디오 포트는 VREF 의 사이에 기입해진 데이터를 파기해, 데이터가 frame buffer에 기입해지지 않게 한다. 이 플래그는 읽어들여 전용이다.
DDVPCONNECT_HALFLINE
비디오 포트는 frame buffer에 하프 라인을 기입한다. 이것에 의해, 경우에 따라서는 데이터가 올바르게 표시되지 않는 것이 있다. 이 플래그는 읽어들여 전용이다.
DDVPCONNECT_INTERLACED
신호가 인터 레이스 된다. 이 플래그는, 비디오 포트 오브젝트를 생성 하는 경우에 클라이언트만이 사용한다.
DDVPCONNECT_SHAREEVEN
물리 비디오 포트는 공유 가능해, 이 비디오 포트 오브젝트는 짝수 필드를 사용한다. 이 플래그는, 비디오 포트 오브젝트를 생성 할 때에 클라이언트에서만 사용한다.
DDVPCONNECT_SHAREODD
물리 비디오 포트는 공유 가능해, 이 비디오 포트 오브젝트는 홀수 필드를 사용한다. 이 플래그는, 비디오 포트 오브젝트를 생성 할 때에 클라이언트에서만 사용한다.
dwReserved1
향후를 위해서(때문에) 확보되고 있다. 0 을 설정한다.

주의

이 구조체는, 독립해 DDVIDEOPORTDESC 구조체의 멤버로서 사용한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.


DDVIDEOPORTDESC

DDVIDEOPORTDESC 구조체는, 생성 하려고 하는 비디오 포트 오브젝트를 기술한다. 이 구조체는,IDDVideoPortContainer::CreateVideoPort 메소드와 함께 사용된다.

typedef struct _DDVIDEOPORTDESC {
    DWORD dwSize;
    DWORD dwFieldWidth;
    DWORD dwVBIWidth;
    DWORD dwFieldHeight;
    DWORD dwMicrosecondsPerField;
    DWORD dwMaxPixelsPerSecond;
    DWORD dwVideoPortID;
    DWORD dwReserved1;
    DDVIDEOPORTCONNECT VideoPortType;
    ULONG_PTR dwReserved2;
    ULONG_PTR dwReserved3;
 } DDVIDEOPORTDESC, *LPDDVIDEOPORTDESC;

멤버

dwSize
바이트 단위의 구조체의 사이즈. 이 멤버는, 구조체를 사용하기 전에 초기화하지 않으면 안 된다.
dwFieldWidth
픽셀 단위의 도착 비디오 스트림의폭 .
dwVBIWidth
픽셀 단위의 도착 비디오 스트림에 있어서의 VBI 데이터의 폭.
dwFieldHeight
주사선으로 나타내는, 도착 비디오 스트림의 필드의 필드 높이.
dwMicrosecondsPerField
밀리 세컨드 단위의 라이브 비디오 VREF 주기의 시간 간격. 이 수는, 가장 가까운 밀리 세컨드에 끝맺는다.
dwMaxPixelsPerSecond
초 마다의 최대 픽셀율.
dwVideoPortID
사용하는 물리 비디오 포트의 제로 베이스의 ID.
dwReserved1
향후를 위해서(때문에) 확보되고 있다. 0 을 설정한다.
VideoPortType
비디오 포트의 connection 특성을 기술하는 DDVIDEOPORTCONNECT 구조체.
dwReserved2,dwReserved3
향후를 위해서(때문에) 확보되고 있다. 0 을 설정한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.


DDVIDEOPORTINFO

DDVIDEOPORTINFO 구조체는, 표면에의 비디오 데이터의 전송을 기술한다. 이 구조체는,IDirectDrawVideoPort::StartVideo 메소드와 함께 사용된다.

typedef struct _DDVIDEOPORTINFO{
    DWORD dwSize;
    DWORD dwOriginX;
    DWORD dwOriginY;
    DWORD dwVPFlags;
    RECT rCrop;
    DWORD dwPrescaleWidth;
    DWORD dwPrescaleHeight;
    LPDDPIXELFORMAT lpddpfInputFormat;
    LPDDPIXELFORMAT lpddpfVBIInputFormat;
    LPDDPIXELFORMAT lpddpfVBIOutputFormat;
    DWORD dwVBIHeight;
    ULONG_PTR dwReserved1;
    ULONG_PTR dwReserved2;
} DDVIDEOPORTINFO, *LPDDVIDEOPORTINFO;

멤버

dwSize
바이트 단위의 이 구조체의 사이즈. 이 멤버는, 구조체를 사용하기 전에 초기화하지 않으면 안 된다.
dwOriginX,dwOriginY
표면의 비디오 데이터에 있어서의 기점의 x 좌표 및 y 좌표.
dwVPFlags
이하에, 비디오 포트 옵션을 나타낸다.
DDVP_AUTOFLIP
자동 플립핑을 실행한다. 상세한 것에 대하여는, 「자동 플립핑」을 참조할것.
DDVP_CONVERT
lpddpfVBIOutputFormat 멤버의 정보를 사용해 변환을 실행한다.
DDVP_CROP
rCrop 멤버가 지정하는 직사각형을 사용해 크로핑을 실행한다.
DDVP_IGNOREVBIXCROP
VBI 데이터를 크로핑 하는 경우, 비디오 포트는 좌우의 크로핑 좌표를 무시한다.
DDVP_INTERLEAVE
인터 레이스 된 필드를 메모리로 인터리브 한다.
DDVP_MIRRORLEFTRIGHT
frame buffer에 기입해질 때, 이미지 데이터를 왼쪽에서 오른쪽에 밀러화한다.
DDVP_MIRRORUPDOWN
frame buffer에 기입해질 때, 이미지 데이터를 위에서 밑으로 밀러화한다.
DDVP_OVERRIDEBOBWEAVE
오버레이 표면을 생성 할 경우에, 호출측에서 설정하는 디스플레이 메소드만을 사용해, 드라이버에 의해 선택되는 자동 디스플레이 메소드를 오버라이드(override) 한다.
DDVP_PRESCALE
dwPrescaleHeight 및 dwPrescaleWidth 멤버의 값에 근거해, 프레스 케이 링 또는 프레즈밍을 실행한다.
DDVP_SKIPEVENFIELDS
짝수 필드의 입력을 무시한다.
DDVP_SKIPODDFIELDS
홀수 필드의 입력을 무시한다.
DDVP_SYNCMASTER
비디오 포트 VREF 는, 비디오 포트에의 refresh rate를 잠그어, 그래픽스 VREF 를 실행할 필요가 있다.
DDVP_VBICONVERT
lpddpfVBIOutputFormat 멤버는,VBI 데이터의 변환에 사용하는 데이터를 포함한다.
DDVP_VBINOSCALE
VBI 데이터는 스케일링을 실시하지 않는다.
DDVP_VBINOINTERLEAVE
인터리브는, VBI 의 데이터에 대해서 무효로 된다.
rCrop
크로핑 직사각형. 이 멤버는 옵션이다.
dwPrescaleWidth
x 방향에서의 프레스 케이 링 또는 주밍. 이 멤버는 옵션이다.
dwPrescaleHeight
y 방향에서의 프레스 케이 링 또는 주밍. 이 멤버는 옵션이다.
lpddpfInputFormat
비디오 포트에 기입하는 픽셀 포맷을 기술하는 DDPIXELFORMAT 구조체. 많은 경우, 표면의 픽셀 포맷과 같지만, 비디오 포트가 변환을 실행하는 경우에는 다를 때도 있다.
lpddpfVBIInputFormat,lpddpfVBIOutputFormat
수직귀선소거 간격내의 데이터의 출력 픽셀 포맷을 기술하는 DDPIXELFORMAT 구조체.
dwVBIHeight
주사선으로 나타내는, 수직귀선소거 간격내의 데이터량.
dwReserved1,dwReserved2
향후를 위해서(때문에) 확보되고 있다. 0 을 설정한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.


DDVIDEOPORTSTATUS

DDVIDEOPORTSTATUS 구조체는, 비디오 포트 오브젝트의 스테이터스를 기술한다. 이 구조체는,IDDVideoPortContainer::QueryVideoPortStatus 메소드와와도 사용된다.

typedef struct _DDVIDEOPORTSTATUS {
    DWORD dwSize;
    BOOL  bInUse;
    DWORD dwFlags;
    DWORD dwReserved1;
    DDVIDEOPORTCONNECT VideoPortType;
    ULONG_PTR dwReserved2;
    ULONG_PTR dwReserved3;
} DDVIDEOPORTSTATUS, *LPDDVIDEOPORTSTATUS;

멤버

dwSize
바이트 단위의 이 구조체의 사이즈. 이 멤버는, 구조체를 사용하기 전에 초기화하지 않으면 안 된다.
bInUse
비디오 포트의 현재의 스테이터스를 나타내는 값. 이 멤버는, 비디오 포트가 현재 사용중이면 TRUE 가 되어, 그 이외는 FALSE 가 된다.
dwFlags
이하의 플래그 가운데, 1 개 이상의 값을 취한다.
DDVPSTATUS_VBIONLY
비디오 포트 인터페이스는, 비디오 스트림의 VBI 부분만 제어한다.
DDVPSTATUS_VIDEOONLY
비디오 포트 인터페이스는, 비디오 스트림의 비디오 부분만 제어한다.
dwReserved1
향후를 위해서(때문에) 확보되고 있다. 0 을 설정한다.
VideoPortType
비디오 포트 connection 정보를 받는 DDVIDEOPORTCONNECT 구조체.
dwReserved2,dwReserved3
향후를 위해서(때문에) 확보되고 있다. 0 을 설정한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dvp.h 로 선언.


반환값

에러는 부의 값으로 나타내져 짜 합쳐질 것은 없다. 이 테이블은,IDirectDraw7 ,IDirectDrawSurface7 ,IDirectDrawPalette ,IDirectDrawClipper ,IDDVideoPortContainer , 및 IDirectDrawVideoPort 인터페이스의 모든 메소드에 의해 돌려주어질 가능성이 있는 값을 일람표 가리키고 있다. 각각의 메소드가 돌려줄 가능성이 있는 에러 코드의 리스트는, 그 메소드의 기술을 참조할것.

DD_OK
요구는 성공해 완료했다.
DDERR_ALREADYINITIALIZED
오브젝트는 이미 초기화되고 있다.
DDERR_BLTFASTCANTCLIP
DirectDrawClipper 오브젝트는,IDirectDrawSurface7::BltFast 메소드의 호출에게 건네진 전송원표면에 Attach 되고 있다.
DDERR_CANNOTATTACHSURFACE
요구된 표면에는 표면을 Attach 할 수 없다.
DDERR_CANNOTDETACHSURFACE
요구된 표면으로부터 표면의 Attach를 해제할 수 없다.
DDERR_CANTCREATEDC
Windows 는 더 이상 디바이스 콘텍스트 (DC)를 생성 할 수 없다. 또, 표면에 팔레트가 없고, 디스플레이 모드가 인 DEC 첨부의 팔레트가 아닌 경우에, DC 가 인덱스 첨부 팔레트 표면을 요구했다 (이 경우, DirectDraw 는 DC 에 적절한 팔레트를 선택할 수 없다).
DDERR_CANTDUPLICATE
프라이머리 표면, 3D 표면, 은근히 만들어지는 표면은 복제할 수 없다.
DDERR_CANTLOCKSURFACE
DCI 지원없이프라이머리 표면을 잠그려고 했기 때문에, 이 표면에의 액세스가 거부되었다.
DDERR_CANTPAGELOCK
표면의 페이지 락이 실패했다. 페이지 락은, 디스플레이 메모리 표면 또는 에뮬레이트 된프라이머리 표면에서는 작용하지 않는다.
DDERR_CANTPAGEUNLOCK
표면의 페이지 락의 해제가 실패했다. 페이지 락의 해제는, 디스플레이 메모리 표면 또는 에뮬레이트 된프라이머리 표면에서는 작용하지 않는다.
DDERR_CLIPPERISUSINGHWND
윈도우 핸들을 이미 감시하고 있는 DirectDrawClipper 오브젝트에 대해서,클립 리스트를 설정하려고 했다.
DDERR_COLORKEYNOTSET
이 처리에 대해서,전송원컬러 키가 지정되어 있지 않다.
DDERR_CURRENTLYNOTAVAIL
현시점에서는 지원되어 있지 않다.
DDERR_DDSCAPSCOMPLEXREQUIRED
DirectX 7.0 으로 추가. 표면이 DDSCAPS_COMPLEX 플래그를 요구하고 있다.
DDERR_DCALREADYCREATED
디바이스 콘텍스트 (DC)는 이미 이 표면에 대해서 돌려주어지고 있다. 1 표면에 대해 1 개의 DC 밖에 취득할 수 없다.
DDERR_DEVICEDOESNTOWNSURFACE
1 개의 DirectDraw 디바이스로 생성 된 표면은, 다른 DirectDraw 디바이스로 직접 사용할 수 없다.
DDERR_DIRECTDRAWALREADYCREATED
이 드라이버를 나타내는 DirectDraw 오브젝트가, 이 프로세스로 이미 생성 되고 있는 것을 나타낸다.
DDERR_EXCEPTION
요구된 처리를 실행하는 동안에 예외가 발생했다.
DDERR_EXCLUSIVEMODEALREADYSET
이미 배타 모드가 설정되어 있는 것에도 불구하고, 협조 레벨을 설정하려고 했다.
DDERR_EXPIRED
데이터가 종료했으므로, 유효하지 않게 되었다.
DDERR_GENERIC
미정도리의 에러 상태이다.
DDERR_HEIGHTALIGN
제공된 직사각형의 높이는, 필요하게 되는 아라이먼트의 배수는 아니다.
DDERR_HWNDALREADYSET
DirectDraw 협조 레벨 윈도우 핸들이 이미 설정되어 있다. 윈도우 핸들은, 프로세스가 표면 혹은 생성 된 팔레트를 보관 유지하고 있는 동안은 리셋 할 수 없다.
DDERR_HWNDSUBCLASSED
DirectDraw 협조 레벨 윈도우 핸들이 서브 클래스화 되고 있기 (위해)때문에, DirectDraw 상태의 restore가 저지되었다.
DDERR_IMPLICITLYCREATED
표면이 은근히 생성 되었기 때문에, 표면을 restore 할 수 없다.
DDERR_INCOMPATIBLEPRIMARY
프라이머리 표면의 생성 요구가 기존의 프라이머리 표면과 일치하고 있지 않다.
DDERR_INVALIDCAPS
콜백 함수에게 건네진 1 개 이상의 능력 비트가 부정하다.
DDERR_INVALIDCLIPLIST
DirectDraw 는, 제공된클립 리스트를 지원 하지 않는다.
DDERR_INVALIDDIRECTDRAWGUID
DirectDrawCreate 함수에게 건네지는 글로벌 유니크 식별자 (GUID)가 유효한 DirectDraw 드라이버 식별자가 아니다.
DDERR_INVALIDMODE
DirectDraw 는 요구된 모드를 지원 하지 않는다.
DDERR_INVALIDOBJECT
DirectDraw 가, 무효인 DirectDraw 오브젝트의 포인터를 받았다.
DDERR_INVALIDPARAMS
메소드에게 건네진 1 개 이상의 파라미터가 부정하다.
DDERR_INVALIDPIXELFORMAT
지정된 픽셀 포맷이 무효이다.
DDERR_INVALIDPOSITION
목적지의 오버레이의 위치가 부정하다.
DDERR_INVALIDRECT
제공된 직사각형이 무효이다.
DDERR_INVALIDSTREAM
지정된 스트림에 무효인 데이터를 포함한다.
DDERR_INVALIDSURFACETYPE
표면의 종류가 잘못되어 있다.
DDERR_LOCKEDSURFACES
1 개(살) 이상의 표면이 락 되고 있어 요구된 처리에 실패했다.
DDERR_MOREDATA
지정된 버퍼 사이즈 로 유지할 수 있는 이상의 데이터가 존재한다.
DDERR_NEWMODE
DirectX 7.0 으로 추가. DDSMT_ISTESTREQUIRED 플래그로 IDirectDraw7::StartModeTest 를 호출하면, 해상도의 일부 또는 모든 것을 테스트할 수 있다, 혹은 테스트할 필요가 있는 것을 나타내는 이 값이 돌려주어진다. IDirectDraw7::EvaluateMode 는, 테스트가 새로운 디스플레이 모드에 바뀐 것을 나타내는 이 값을 돌려준다.
DDERR_NO3D
3-D 하드웨어 또는 에뮬레이션이 존재하지 않는다.
DDERR_NOALPHAHW
알파 액셀러레이트 하드웨어가 존재하지 않는가 이용할 수 없었기 (위해)때문에, 요구된 처리에 실패했다.
DDERR_NOBLTHW
블리트 하드웨어가 존재하지 않는다.
DDERR_NOCLIPLIST
이용 가능한클립 리스트가 없다.
DDERR_NOCLIPPERATTACHED
DirectDrawClipper 오브젝트가 표면 오브젝트에 Attach 할 수 없다.
DDERR_NOCOLORCONVHW
색변환 하드웨어가 존재하지 않는, 또는 이용할 수 없다.
DDERR_NOCOLORKEY
표면에 현재의컬러 키가 없다.
DDERR_NOCOLORKEYHW
목적지 컬러 키에 대한 하드웨어 지원이 없다.
DDERR_NOCOOPERATIVELEVELSET
IDirectDraw7::SetCooperativeLevel 메소드를 사용하지 않고 생성 함수가 불려 갔다.
DDERR_NODC
이 표면에 대해서, 디바이스 콘텍스트 (DC)가 생성되어 있지 않다.
DDERR_NODDROPSHW
DirectDraw 라스터 처리 (ROP) 하드웨어를 이용할 수 없다.
DDERR_NODIRECTDRAWHW
하드웨어 전용 DirectDraw 오브젝트를 생성 할 수 없다. 드라이버는 하드웨어를 지원 하지 않는다.
DDERR_NODIRECTDRAWSUPPORT
현재의 디스플레이 드라이버는 DirectDraw 를 지원 하지 않는다.
DDERR_NODRIVERSUPPORT
DirectX 7.0 으로 추가. 디스플레이 어댑터 드라이버가 refresh rate를 열거하지 않기 때문에, 테스트를 실행할 수 없다.
DDERR_NOEMULATION
소프트웨어 에뮬레이션을 이용할 수 없다.
DDERR_NOEXCLUSIVEMODE
어플리케이션에 대해서 배타 모드가 요구되었지만, 어플리케이션에는 배타 모드가 없다.
DDERR_NOFLIPHW
표시되는 표면을 플립핑 할 수 없다.
DDERR_NOFOCUSWINDOW
최초로포커스 윈도우를 설정하지 않고디바이스 윈도우를 설정 또는 생성 하려고 했다.
DDERR_NOGDI
GDI 가 존재하지 않는다.
DDERR_NOHWND
클립퍼 통지가 윈도우 핸들을 필요로 한다, 혹은 윈도우 핸들이 협조 레벨 윈도우 핸들로서 미리 설정되어 있지 않다.
DDERR_NOMIPMAPHW
밉맵 능력을 가지는텍스쳐 맵핑 하드웨어가 존재하지 않는, 또는 이용할 수 없다.
DDERR_NOMIRRORHW
미러링 하드웨어가 존재하지 않는, 또는 이용할 수 없다.
DDERR_NOMONITORINFORMATION
DirectX 7.0 으로 추가. 관련지을 수 있었던 EDID 데이터가 모니터에 존재하지 않기 때문에, 테스트를 실행할 수 없다.
DDERR_NONONLOCALVIDMEM
비로컬 비디오 메모리를 지원 하지 않는 디바이스로부터, 비로컬 비디오 메모리를 할당하려고 했다.
DDERR_NOOPTIMIZEHW
디바이스는, 최적화된 표면을 지원 하지 않는다.
DDERR_NOOVERLAYDEST
목적지로서 확립하기 위해서 IDirectDrawSurface7::UpdateOverlay 메소드가 불려 가지 않았던 오버레이에 대해,IDirectDrawSurface7::GetOverlayPosition 메소드가 불려 가고 있다.
DDERR_NOOVERLAYHW
오버레이 하드웨어가 존재하지 않는, 또는 이용할 수 없다.
DDERR_NOPALETTEATTACHED
팔레트 오브젝트를 이 표면에 Attach 할 수 없다.
DDERR_NOPALETTEHW
16 색 혹은 256 색의 팔레트에 대한 하드웨어 지원이 없다.
DDERR_NORASTEROPHW
적절한 라스터 처리 하드웨어가 존재하지 않는, 또는 이용할 수 없다.
DDERR_NOROTATIONHW
회전 하드웨어가 존재하지 않는, 또는 이용할 수 없다.
DDERR_NOSTEREOHARDWARE
스테레오 하드웨어가 존재하지 않는, 또는 이용할 수 없다.
DDERR_NOSTRETCHHW
신축(스트레치)에 대한 하드웨어 지원이 없다.
DDERR_NOSURFACELEFT
스테레오 표면을 지원 하는 하드웨어가 존재하지 않는다.
DDERR_NOT4BITCOLOR
DirectDrawSurface 오브젝트는, 4 비트색팔레트를 사용하고 있지 않다. 또, 요구된 처리는 4 비트색팔레트를 요구한다.
DDERR_NOT4BITCOLORINDEX
DirectDrawSurface 오브젝트는, 4 비트 컬러 인덱스 팔레트를 사용하고 있지 않다. 또, 요구된 처리는 4 비트 컬러 인덱스 팔레트를 요구한다.
DDERR_NOT8BITCOLOR
DirectDrawSurface 오브젝트는, 8 비트색팔레트를 사용하고 있지 않다. 또, 요구된 처리는 8 비트색팔레트를 요구한다.
DDERR_NOTAOVERLAYSURFACE
비오버레이 표면에 대해서, 오버레이 성분이 불려 가고 있다.
DDERR_NOTEXTUREHW
텍스쳐 맵핑 하드웨어가 존재하지 않는가 이용할 수 없기 때문에, 처리를 실행할 수 없다.
DDERR_NOTFLIPPABLE
플립 할 수 없는 표면을 플립 하려고 했다.
DDERR_NOTFOUND
요구된 항목이 발견되지 않았다.
DDERR_NOTINITIALIZED
오브젝트가 초기화되기 전에,CoCreateInstance 로 생성 한 DirectDraw 오브젝트의 인터페이스 메소드를 호출하려고 했다.
DDERR_NOTLOADED
표면은 최적화되고 있지만, 아직 메모리를 할당할 수 있지 않았다.
DDERR_NOTLOCKED
락되어 있지 않은 표면을 락 해제하려고 했다.
DDERR_NOTPAGELOCKED
미처리의 페이지 락이 없는 표면을 페이지 락 해제하려고 했다.
DDERR_NOTPALETTIZED
사용하고 있는 표면은 팔레트 베이스의 표면은 아니다.
DDERR_NOVSYNCHW
수직귀선소거 동기 처리에 대한 하드웨어 지원이 없다.
DDERR_NOZBUFFERHW
Z 버퍼에 대한 하드웨어 지원이 없기 때문에, 디스플레이 메모리에서의 Z 버퍼 생성, 혹은 Z 버퍼를 사용한 블리트를 실행할 수 없다.
DDERR_NOZOVERLAYHW
오버레이 표면은, 하드웨어가 오버레이 z 오더를 지원 하지 않기 때문에, z 오더가 무시되었다.
DDERR_OUTOFCAPS
요구된 처리에 필요한 하드웨어를 이미 할당할 수 있고 있다.
DDERR_OUTOFMEMORY
DirectDraw 가 처리를 실시하는데 충분한 메모리가 없다.
DDERR_OUTOFVIDEOMEMORY
DirectDraw 가 처리를 실시하는데 충분한 디스플레이 메모리가 없다.
DDERR_OVERLAPPINGRECTS
전송원 및 목적지 직사각형이 같은 표면상에 있어, 서로 오버랩 하고 있다.
DDERR_OVERLAYCANTCLIP
하드웨어는 클리핑 오버레이를 지원 하지 않는다.
DDERR_OVERLAYCOLORKEYONLYONEACTIVE
오버레이상에 복수의 액티브한컬러 키를 가지려고 했다.
DDERR_OVERLAYNOTVISIBLE
IDirectDrawSurface7::GetOverlayPosition 메소드가 비표시의 오버레이로 불려 갔다.
DDERR_PALETTEBUSY
팔레트가 이제(벌써) 1 개의 thread에 의해 락 되고 있기 (위해)때문에, 액세스가 거부되었다.
DDERR_PRIMARYSURFACEALREADYEXISTS
이 처리는 이미프라이머리 표면을 생성 하고 있다.
DDERR_REGIONTOOSMALL
IDirectDrawClipper::GetClipList 메소드에게 건네진 영역이 너무 작다.
DDERR_SURFACEALREADYATTACHED
이미 Attach 하고 있는 이제(벌써) 1 개의 표면에 표면을 Attach 하려고 했다.
DDERR_SURFACEALREADYDEPENDENT
이미 다른 표면에 의존하고 있는 표면을 의존 시키려고 했다.
DDERR_SURFACEBUSY
표면이 이제(벌써) 1 개의 thread로 락 되고 있기 (위해)때문에, 표면에의 액세스가 거부되었다.
DDERR_SURFACEISOBSCURED
표면에의 액세스가, 표면이 은폐 되고 있기 (위해)때문에 거부되었다.
DDERR_SURFACELOST
표면 메모리의 부족을 위해, 표면에의 액세스가 거부되었다. 이 표면으로 IDirectDrawSurface7::Restore 메소드를 호출하면, 관련지을 수 있었던 메모리를 restore 할 수 있다.
DDERR_SURFACENOTATTACHED
요구된 표면은 Attach 할 수 없다.
DDERR_TESTFINISHED
DirectX 7.0 으로 추가. IDirectDraw7::StartModeTest 메소드가 이 값을 돌려주었을 경우, 테스트용으로 선택한 모든 해상도는 이미 refresh rate 정보를 레지스트리에 가지고 있기 (위해)때문에, 테스트를 시작 할 수 없는 것을 의미한다. IDirectDraw7::EvaluateMode 메소드가 이 값을 돌려주었을 경우는, DirectDraw 가 refresh rate 테스트를 완료한 것을 의미한다.
DDERR_TOOBIGHEIGHT
DirectDraw 로 요구된 폭이 너무 크다.
DDERR_TOOBIGSIZE
DirectDraw 로 요구된 사이즈가 너무 크다. 다만, 각각의 높이 및폭은 유효한 사이즈이다.
DDERR_TOOBIGWIDTH
DirectDraw 에 의해 요구된폭이 너무 크다.
DDERR_UNSUPPORTED
지원 되지 않는 처리였다.
DDERR_UNSUPPORTEDFORMAT
요구된 픽셀 포맷은 DirectDraw 에서는 지원되어 있지 않다.
DDERR_UNSUPPORTEDMASK
요구된 픽셀 포맷의 비트 마스크가 DirectDraw 로 지원되어 있지 않다.
DDERR_UNSUPPORTEDMODE
디스플레이는 현재 지원되어 있지 않은 모드이다.
DDERR_VERTICALBLANKINPROGRESS
수직귀선소거기간이다.
DDERR_VIDEONOTACTIVE
비디오 포트가 액티브하지 않다.
DDERR_WASSTILLDRAWING
이 표면으로부터, 또는 표면에의 전회의 블리트 처리가 완료하고 있지 않다.
DDERR_WRONGMODE
다른 모드로 생성 되었기 때문에, 이 표면은 restore 할 수가 없다.
DDERR_XALIGN
제공된 직사각형이 필요하게 되는 범위에 수평 일렬에 늘어놓을 수가 없었다.


픽셀 포맷 마스크

여기에서는, 하드웨어 에뮬레이션 계층 (HEL)이 지원 하는 픽셀 포맷에 대해 설명한다. 이하의 항목에 대해 기술한다.

  • 텍스쳐 맵 포맷
  • 오프 스크린 표면 포맷


텍스쳐 맵 포맷

하드웨어 에뮬레이션 계층 (HEL)에 의해 광범위하게 걸쳐 텍스쳐 픽셀 포맷이 지원 되고 있다. 이하의 테이블에 이러한 포맷을 나타낸다. 마스크란에는, 픽셀 포맷 플래그와 비트 깊이의 각 집합에 대한 적, 록, 청, 및 알파의 마스크를 나타내고 있다.

픽셀 포맷 플래그 | 비트 깊이 | 마스크
DDPF_RGB | DDPF_PALETTEINDEXED1 | 1 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED1 | DDPF_PALETTEINDEXEDTO8 | 1 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED2 | 2 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED2 | DDPF_PALETTEINDEXEDTO8 | 2 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED4 | 4 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED4 | DDPF_PALETTEINDEXEDTO8 | 4 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED8 | 8 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | 8 | R:0x000000E0 G:0x0000001C B:0x00000003 A:0x00000000
DDPF_RGB | DDPF_ALPHAPIXELS | 16 | R:0x00000F00 G:0x000000F0 B:0x0000000F A:0x0000F000
DDPF_RGB | 16 | R:0x0000F800 G:0x000007E0 B:0x0000001F A:0x00000000
DDPF_RGB | 16 | R:0x0000001F G:0x000007E0 B:0x0000F800 A:0x00000000
DDPF_RGB | 16 | R:0x00007C00 G:0x000003E0 B:0x0000001F A:0x00000000
DDPF_RGB | DDPF_ALPHAPIXELS | 16 | R:0x00007C00 G:0x000003E0 B:0x0000001F A:0x00008000
DDPF_RGB | 24 | R:0x00FF0000 G:0x0000FF00 B:0x000000FF A:0x00000000
DDPF_RGB | 24 | R:0x000000FF G:0x0000FF00 B:0x00FF0000 A:0x00000000
DDPF_RGB | 32 | R:0x00FF0000 G:0x0000FF00 B:0x000000FF A:0x00000000
DDPF_RGB | 32 | R:0x000000FF G:0x0000FF00 B:0x00FF0000 A:0x00000000
DDPF_RGB | DDPF_ALPHAPIXELS | 32 | R:0x00FF0000 G:0x0000FF00 B:0x000000FF A:0xFF000000
DDPF_RGB | DDPF_ALPHAPIXELS | 32 | R:0x000000FF G:0x0000FF00 B:0x00FF0000 A:0xFF000000

HEL 에서는, 이러한 포맷을 시스템 메모리에 생성 할 수가 있다. 3D 액셀러레이트 디스플레이 카드용의 DirectDraw 디바이스 드라이버는, 디스플레이 메모리에 다른 포맷의 텍스쳐를 생성 할 수가 있다. 그러한 드라이버는, 텍스쳐를 생성 할 수 있는 것을 나타내기 위해서(때문에) DDSCAPS_TEXTURE 플래그를 export 한다.


오프 스크린 표면 포맷

이하의 겉(표)는, DirectX 하드웨어 에뮬레이션 계층 (HEL)이 지원 하는 오프 스크린 프레인 표면의 픽셀 포맷을 나타내고 있다. 마스크란에는, 픽셀 포맷 플래그와 비트 깊이의 각 집합에 대한 적, 록, 청, 및 알파의 마스크를 나타내고 있다.

픽셀 포맷 플래그 | 비트 깊이 | 마스크
DDPF_RGB | DDPF_PALETTEINDEXED1 | 1 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED2 | 2 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED4 | 4 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED8 | 8 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | 16 | R:0x0000F800 G:0x000007E0 B:0x0000001F A:0x00000000
DDPF_RGB | 16 | R:0x00007C00 G:0x000003E0 B:0x0000001F A:0x00000000
DDPF_RGB | 24 | R:0x00FF0000 G:0x0000FF00 B:0x000000FF A:0x00000000
DDPF_RGB | 24 | R:0x000000FF G:0x0000FF00 B:0x00FF0000 A:0x00000000
DDPF_RGB | 32 | R:0x00FF0000 G:0x0000FF00 B:0x000000FF A:0x00000000
DDPF_RGB | 32 | R:0x000000FF G:0x0000FF00 B:0x00FF0000 A:0x00000000
DDPF_RGB | DDPF_ZPIXELS | 32 | R:0x0000F800 G:0x000007E0 B:0x0000001F Z:0xFFFF0000
DDPF_RGB | DDPF_ZPIXELS | 32 | R:0x00007C00 G:0x000003E0 B:0x0000001F Z:0xFFFF0000

광범위한오프 스크린 표면 포맷을 지원 하는 것 외에도, HEL 는 Direct3D 또는 그 외의 3D 렌더러용의 표면을 지원 한다.


4 문자 코드 (FOURCC)

DirectDraw 는, 4 문자로부터 되는 특별한 코드의 집합을 사용한다. 이러한 코드는, 4 문자 코드 또는 FOURCC 로 불려 비트 맵 이미지, 사운드, 비디오등의 멀티미디어 데이터를 포함한 파일의 헤더 파일에 저장 되고 있다. FOURCC 는, 멀티미디어 데이터를 생성 하기 위해서 사용된 소프트웨어 기술을 나타내고 있다. 또 은근히, FOURCC 는 데이터 자체의 포맷도 기술하고 있다.

DirectDraw 어플리케이션은, 이미지 컬러나 포맷 변환에 FOURCC 를 사용한다. 어플리케이션으로,IDirectDrawSurface7::GetPixelFormat 메소드를 호출해, 포맷이 RGB 가 아닌 표면의 픽셀 포맷을 요구 하면, 메소드가 돌아갈 때 DDPIXELFORMAT 구조체의 dwFourCC 멤버가 FOURCC 를 식별한다.

게다가BITMAPINFOHEADER 구조체의 biCompression 멤버는, 이미지를 수축 또는 신축(스트레치) 하기 위해서 사용하는 코덱을 나타내기 (위해)때문에, FOURCC 로 설정할 수가 있다.

FOURCC 는, 멀티미디어 소프트웨어 기술의 각 벤더에 의해 마이크로 소프트에 등록되어 있다. 이하의 테이블에, 공통의 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 | 크리에이티브 레버러토리 YUV
DXT1 | Microsoft Corporation | DirectX Texture Compression 포맷 1
DXT2 | Microsoft Corporation | DirectX Texture Compression 포맷 2
DXT3 | Microsoft Corporation | DirectX Texture Compression 포맷 3
DXT4 | Microsoft Corporation | DirectX Texture Compression 포맷 4
DXT5 | Microsoft Corporation | DirectX Texture Compression 포맷 5
FVF1 | Iterated Systems, Inc. | 프랙탈 이론 비디오 프레임
IF09 | Intel® Corporation | 인텔 인터 미디 애트 YUV9
IV31 | Intel Corporation | 인디오 3.1
JPEG | Microsoft Corporation | 스티르이메이지 JPEG DIB
MJPG | Microsoft Corporation | 모션 JPEG Dib 포맷
MRLE | Microsoft Corporation | 렌 길이 인코딩
MSVC | Microsoft Corporation | 비디오 1
PHMO | IBM Corporation | 포토 모션
RT21 | Intel Corporation | 인디오 2.1
ULTI | IBM Corporation | 알 티모-숀
V422 | Vitec Multimedia | 24 비트 YUV 4:2:2
V655 | Vitec Multimedia | 16 비트 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


DirectDraw Visual Basic 레퍼런스

여기에서는, DirectDraw 가 제공하는 API 요소의 레퍼런스 정보를 기술한다. 레퍼런스 정보는 이하의 카테고리로 분류된다.

  • 클래스
  • 형
  • 열거
  • 에러 코드
  • 픽셀 포맷 마스크
  • 4 문자 코드 (FOURCC)


클래스

여기에서는, DirectDraw 컴퍼넌트로 사용되는 클래스의 레퍼런스 정보를 기술한다. 이하의 클래스에 도착해 설명한다.

  • DirectDraw7
  • DirectDrawClipper
  • DirectDrawColorControl
  • DirectDrawEnum
  • DirectDrawEnumModes
  • DirectDrawEnumSurfaces
  • DirectDrawGammaControl
  • DirectDrawIdentifier
  • DirectDrawPalette
  • DirectDrawSurface7
  • DirectDraw 글로벌 메소드
  • IFont


DirectDraw7

어플리케이션은 DirectDraw7 클래스의 메소드를 사용해, DirectDraw 오브젝트를 생성 해, 시스템 레벨 변수와 함께 작용한다. 이 항은, 이 클래스의 메소드의 레퍼런스이다. 개요에 대해서는, 「DirectDraw 오브젝트」를 참조할것.

DirectDraw7 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

협조 레벨 | SetCooperativeLevel
 | TestCooperativeLevel
오브젝트의 생성 | CreateClipper
 | CreatePalette
 | CreateSurface
 | CreateSurfaceFromFile
 | CreateSurfaceFromResource
 | GetDirect3D
 | LoadPaletteFromBitmap
디바이스 능력 | GetCaps
디스플레이 모드 | GetDisplayMode
 | GetDisplayModesEnum
 | GetMonitorFrequency
 | RestoreDisplayMode
 | SetDisplayMode
 | WaitForVerticalBlank
디스플레이 스테이터스 | GetScanLine
 | GetVerticalBlankStatus
그 외 | GetAvailableTotalMem
 | GetDeviceIdentifier
 | GetFourCCCodes
 | GetFreeMem
 | GetNumFourCCCodes
표면 관리 | DuplicateSurface
 | FlipToGDISurface
 | GetGDISurface
 | GetSurfaceFromDC
 | GetSurfacesEnum
 | RestoreAllSurfaces

DirectDraw7 클래스는, 이전의 버젼보다 유연하게 표면을 관리할 수 있는 메소드를 제공하는 것으로써, 클래스의 앞의 버젼에 있어서의 기능을 확장하고 있다.


DirectDraw7.CreateClipper

DirectDraw7.CreateClipper 메소드는,DirectDrawClipper 오브젝트를 생성 한다.

object. CreateClipper(flags As Long) As DirectDrawClipper

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.
flags
현재 사용되어 있지 않기 때문에, 0 으로 설정한다.

반환값

성공하면,DirectDrawClipper 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOOPERATIVELEVELSET
DDERR_OUTOFMEMORY

주의

DirectDrawClipper 오브젝트를 DirectDrawSurface 에 Attach 해,DirectDrawSurface7.Blt 의 실행시에 사용할 수가 있다.

참조

DirectDrawSurface7.GetClipper ,DirectDrawSurface7.SetClipper


DirectDraw7.CreatePalette

DirectDraw7.CreatePalette 메소드는, 이 DirectDraw 오브젝트에 대한 DirectDrawPalette 오브젝트를 생성 한다.

object. CreatePalette( _
    flags As CONST_DDPCAPSFLAGS, _
    pe() As PALETTEENTRY) As DirectDrawPalette

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.
flags
CONST_DDPCAPSFLAGS 열거의 1 개 또는 복수의 정수.
pe()
이 DirectDrawPalette 오브젝트를 초기화하는, 2, 4, 16, 또는 256 의 PALETTEENTRY 형의 배열.

반환값

성공하면,DirectDrawPalette 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOOPERATIVELEVELSET
DDERR_OUTOFMEMORY
DDERR_UNSUPPORTED


DirectDraw7.CreateSurface

DirectDraw7.CreateSurface 메소드는, 이 DirectDraw 오브젝트에 대한DirectDrawSurface7 오브젝트를 생성 한다.

object. CreateSurface( _
    dd As DDSURFACEDESC2) As DirectDrawSurface7

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.
dd
요구되는 표면을 기술하는 DDSURFACEDESC2 형. DDSCAPS2 형은,DDSURFACEDESC2 의 멤버이다.

반환값

성공하면,DirectDrawSurface7 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_NOALPHAHW
DDERR_NOCOOPERATIVELEVELSET
DDERR_NODIRECTDRAWHW
DDERR_NOEMULATION
DDERR_NOEXCLUSIVEMODE
DDERR_NOFLIPHW
DDERR_NOMIPMAPHW
DDERR_NOOVERLAYHW
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_UNSUPPORTEDMODE


DirectDraw7.CreateSurfaceFromFile

DirectDraw7.CreateSurfaceFromFile 메소드는, 이 DirectDraw 오브젝트에 대한 DirectDrawSurface7 오브젝트를 생성 해, 지정된 비트 맵 이미지를 DirectDrawSurface 오브젝트에 Attach 한다.

object. CreateSurfaceFromFile( _
    file As String, _
    dd As DDSURFACEDESC2) As DirectDrawSurface7

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.
file
생성 하는 표면에 로드하는 비트 맵 이미지의 이름.
dd
요구되는 표면을 기술하는 DDSURFACEDESC2 형. DDSCAPS2 형은,DDSURFACEDESC2 의 멤버이다.

반환값

성공하면,DirectDrawSurface7 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_NOALPHAHW
DDERR_NOCOOPERATIVELEVELSET
DDERR_NODIRECTDRAWHW
DDERR_NOEMULATION
DDERR_NOEXCLUSIVEMODE
DDERR_NOFLIPHW
DDERR_NOMIPMAPHW
DDERR_NOOVERLAYHW
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_UNSUPPORTEDMODE

주의

256 색을 사용하는 경우, 이 메소드를 호출해 팔레트 정보를 표시하기 전에, 디스플레이 모드와 팔레트를 설정한다.


DirectDraw7.CreateSurfaceFromResource

DirectDraw7.CreateSurfaceFromResource 메소드는, 이 DirectDraw 오브젝트에 대한 DirectDrawSurface7 오브젝트를 생성 해, 지정된 리소스를 DirectDrawSurface 오브젝트에 Attach 한다.

object. CreateSurfaceFromResource( _
    file As String, _
    resName As String, _
    ddsd As DDSURFACEDESC2) As DirectDrawSurface7

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.
file
생성 하는 표면에 로드하는 리소스의 파일명. 리소스가 실행 가능 파일에 포함되는 경우, 리소스의 장소를 나타내려면 , 이 파라미터에 하늘의 캐릭터 라인을 지정한다. 이 파라미터는, 리소스가 존재하는 OCX 의 이름으로 할 수도 있다.
resName
생성 하는 표면에 로드하는 리소스의 이름.
ddsd
요구된 표면을 기술하는 DDSURFACEDESC2 형. DDSCAPS2 형은,DDSURFACEDESC2 의 멤버이다.

반환값

성공하면,DirectDrawSurface7 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_NOALPHAHW
DDERR_NOCOOPERATIVELEVELSET
DDERR_NODIRECTDRAWHW
DDERR_NOEMULATION
DDERR_NOEXCLUSIVEMODE
DDERR_NOFLIPHW
DDERR_NOMIPMAPHW
DDERR_NOOVERLAYHW
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_UNSUPPORTEDMODE

주의

모듈명에 하늘의 캐릭터 라인을 사용해 Microsoft® Visual Basic® 환경에서 어플리케이션을 실행 하면, 리소스의 장소를 검색할 수 없다. 스탠드얼론의 실행 가능 파일을 사용하고 있는 경우만, 하늘의 캐릭터 라인을 건네주어도 성공한다.

리소스명은, 숫자는 아니고 문자로 지정해야 한다. 리소스명을 쿠오테이션마크로 둘러싸 캐릭터 라인으로 하지 않으면 메소드는 실패한다.


DirectDraw7.DuplicateSurface

DirectDraw7.DuplicateSurface 메소드는,DirectDrawSurface7 오브젝트를 복제한다.

object. DuplicateSurface( _
    ddIn As DirectDrawSurface7) As DirectDrawSurface7

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.
ddIn
복제되는 표면이 되는 DirectDrawSurface7 오브젝트.

반환값

성공하면, 새롭게 복제된 DirectDrawSurface7 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_CANTDUPLICATE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACELOST

주의

이 메소드는, 기존의 DirectDrawSurface 오브젝트로서 같은 표면 메모리를 가리키는 새로운 오브젝트를 생성 한다. 이 복제는, 원의 오브젝트와 완전히 똑같이 사용할 수 있다. 마지막에 참조된 오브젝트가 릴리즈 되면(자), 표면 메모리가 릴리즈 된다. 프라이머리 표면,3-D 표면, 또는 은근히 생성 된 표면은 복제할 수 없다.


DirectDraw7.FlipToGDISurface

DirectDraw7.FlipToGDISurface 메소드는, GDI 가 기입하는 표면을프라이머리 표면으로 한다.

object. FlipToGDISurface()

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

주의

이 메소드는 페이지 플립핑 어플리케이션의 마지막에 불려 가 GDI 가 기술하고 있는 디스플레이 메모리를 유저에게 표시시키도록(듯이) 한다.

이 메소드에서는, 스테레오 자동 플립핑은 사용할 수 없다.

참조

DirectDraw7.GetGDISurface


DirectDraw7.GetAvailableTotalMem

DirectDraw7.GetAvailableTotalMem 메소드는, 지정된 타입의 표면으로 사용 가능한 디스플레이 메모리의 총용량을 취득한다.

object. GetAvailableTotalMem( _
    ddsCaps As DDSCAPS2) As Long

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.
ddsCaps
지정된 표면의 하드웨어 능력을 나타내는 DDSCAPS2 형.

반환값

성공하면, 총메모리 용량을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW

주의

이 메소드는, 현재의 디스플레이 메모리의 순간적인 상태만을 제공한다. 디스플레이 메모리의 빈 용량은, 표면의 생성과 릴리즈에 의해 변화한다. 따라서, 빈메모리 용량의 값은 단지 근사치로서 사용해야 한다. 게다가 특정의 디스플레이 어댑터 카드로는, 2 개(살)이 다른 메모리 타입을 구별하지 않는다. 예를 들어, 어댑터는 디스플레이 메모리의 같은 부분을 사용해, Z 버퍼와 텍스쳐를 저장 하는 경우가 있다. 이 때문에, 표면이 있는 타입 (예를 들어 Z 버퍼)을 할당하는 것은, 표면외의 타입 (예를 들어 텍스쳐)을 이용할 수 있는 디스플레이 메모리의 용량에 영향을 준다. 따라서, 동적 사용 (텍스쳐 맵핑등)으로 이용할 수 있는 메모리 용량을 결정하기 전에, 어플리케이션의 고정 리소스 (프런트와백 버퍼, 및 Z 버퍼등)를 최초로 할당하는 것이 최선의 방법이 된다.


DirectDraw7.GetCaps

DirectDraw7.GetCaps 메소드는, 하드웨어와 하드웨어 에뮬레이션 계층 (HEL)에 대한 디바이스 드라이버의 능력을 저장 한다.

object. GetCaps(hwCaps As DDCAPS, helCaps As DDCAPS)

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.
hwCaps
디바이스 드라이버가 보고하는 하드웨어의 능력을 저장 하는 DDCAPS 형.
helCaps
HEL 의 능력을 저장 하는 DDCAPS 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


DirectDraw7.GetDeviceIdentifier

DirectDraw7.GetDeviceIdentifier 메소드는, DirectDraw 디바이스 드라이버에 관한 정보가 저장 된 DirectDrawIdentifier 오브젝트를 돌려준다.

object. GetDeviceIdentifier( _
    flags As CONST_DDDEVICEIDFLAGS _ )
    As DirectDrawIdentifier

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.
flags
정보 옵션을 지정하는 CONST_DDDEVICEIDFLAGS 열거의 정수의 1 개.

반환값

성공하면,DirectDrawIdentifier 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectDraw7.GetDirect3D

DirectDraw7.GetDirect3D 메소드는,Direct3D7 오브젝트를 생성 한다.

object. GetDirect3D() As Direct3D7

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.

반환값

성공하면,Direct3D7 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

E_INVALIDINTERFACE
E_OUTOFMEMORY

트래핑 에러의 상세한 것에 대하여는, 「Visual Basic 에러 트래핑」을 참조할것.

주의

이 메소드가 성공해 취득된 오브젝트는,Direct3D7 오브젝트 변수에 할당하지 않으면 안 된다. 이하에 예를 나타낸다.

Dim Direct3D as Direct3D7
Set Direct3D = object. GetDirect3D()


DirectDraw7.GetDisplayMode

DirectDraw7.GetDisplayMode 메소드는, 현재의 디스플레이 모드를 취득한다.

object. GetDisplayMode(surface As DDSURFACEDESC2)

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.
surface
표면의 디스플레이 모드 정보가 저장 되는 DDSURFACEDESC2 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTEDMODE

주의

어플리케이션이 이 메소드로 돌려주어진 정보를 미리 보존해, 클린 업때의 디스플레이 모드의 restore로서 이용하는 것은 바람직하지 않다. 어플리케이션에서는 DirectDraw7.RestoreDisplayMode 메소드를 사용해, 클린 업 시에 모드를 restore 해야 한다. 이것에 의해, 멀티 프로세스 환경에서 일어나는 경합을 회피할 수 있다.

참조

DirectDraw7.SetDisplayMode ,DirectDraw7.RestoreDisplayMode ,DirectDraw7.GetDisplayModesEnum


DirectDraw7.GetDisplayModesEnum

DirectDraw7.GetDisplayModesEnum 메소드는, 디스플레이 모드 정보가 저장 된 DirectDrawEnumModes 오브젝트를 돌려준다.

object. GetDisplayModesEnum( _
    flags As CONST_DDEDMFLAGS, _
    ddsd As DDSURFACEDESC2) As DirectDrawEnumModes

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.
flags
CONST_DDEDMFLAGS 열거의 정수의 1 개.
ddsd
표면의 디스플레이 모드 정보가 저장 되는 DDSURFACEDESC2 형.

반환값

성공하면,DirectDrawEnumModes 오브젝트를 돌려준다. 이 오브젝트에 의해 디스플레이 모드의 기술을 조회할 수 있다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
E_OUTOFMEMORY

주의

어플리케이션이 이 메소드로 돌려주어진 정보를 미리 보존해, 클린 업때의 디스플레이 모드의 restore로서 이용하는 것은 바람직하지 않다. 어플리케이션에서는 DirectDraw7.RestoreDisplayMode 메소드를 사용해, 클린 업 시에 모드를 restore 해야 한다. 이것에 의해, 멀티 프로세스 환경에서 일어나는 경합을 회피할 수 있다.

참조

DirectDraw7.SetDisplayMode ,DirectDraw7.RestoreDisplayMode ,DirectDraw7.GetDisplayModesEnum


DirectDraw7.GetFourCCCodes

DirectDraw7.GetFourCCCodes 메소드는, DirectDraw 오브젝트에 의해 지원 되는 FOURCC 코드를 취득한다.

object. GetFourCCCodes(ccCodes() As Long)

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.
ccCodes
이 DirectDraw 오브젝트에 의해 지원 되는 4 문자 코드 (FOURCC) 를 저장 하는 변수의 배열.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

DirectDraw7 오브젝트에 의해 지원 되는 코드의 수를 취득하려면 ,DirectDraw7.GetNumFourCCCodes 를 사용한다.


DirectDraw7.GetFreeMem

DirectDraw7.GetFreeMem 메소드는, 디스플레이 메모리의 현재의 빈 용량을 취득한다.

object. GetFreeMem(ddsCaps As DDSCAPS2) As Long

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.
ddsCaps
지정된 표면의 하드웨어 능력을 나타내는 DDSCAPS2 형.

반환값

성공하면, 메모리의 빈 용량을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW

주의

이 메소드는, 현재의 디스플레이 메모리의 순간적인 상태만을 제공한다. 디스플레이 메모리의 빈 용량은, 표면의 생성과 릴리즈에 의해 변화한다. 따라서, 빈메모리 용량의 값은 단지 근사치로서 사용해야 한다. 게다가 특정의 디스플레이 어댑터 카드로는, 2 개(살)이 다른 메모리 타입을 구별하지 않는다. 예를 들어, 어댑터는 디스플레이 메모리의 같은 부분을 사용해, Z 버퍼와 텍스쳐를 저장 하는 경우가 있다. 이 때문에, 표면이 있는 타입 (예를 들어, Z 버퍼)을 할당하는 것은, 표면외의 타입 (텍스쳐)을 이용할 수 있는 디스플레이 메모리의 용량에 영향을 준다. 따라서, 동적 사용 (텍스쳐 맵핑등)으로 이용할 수 있는 메모리 용량을 결정하기 전에, 어플리케이션의 고정 리소스 (프런트와백 버퍼, 및 Z 버퍼등)를 최초로 할당하는 것이 최선의 방법이 된다.


DirectDraw7.GetGDISurface

DirectDraw7.GetGDISurface 메소드는, GDI 가프라이머리 표면으로서 처리하는 표면 메모리를 현재 가리키는 DirectDrawSurface 오브젝트를 취득한다.

object. GetGDISurface() As DirectDrawSurface7

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectDrawSurface7 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

참조

DirectDraw7.FlipToGDISurface


DirectDraw7.GetMonitorFrequency

DirectDraw7.GetMonitorFrequency 메소드는, DirectDraw 오브젝트가 동작하는 모니터의 주파수를 취득한다.

object. GetMonitorFrequency() As Long

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 모니터의 주파수를 헤르쯔 단위로 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED


DirectDraw7.GetNumFourCCCodes

DirectDraw7.GetNumFourCCCodes 메소드는,DirectDraw 오브젝트에 의해 지원 되는 FOURCC 코드의 수를 취득한다.

object. GetFourCCCodes() As Long

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 지원 되는 4 문자 코드 (FOURCC) 의 수를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는, 보통 DirectDraw7.GetFourCCCodes 를 호출하기 전에 불려 간다.


DirectDraw7.GetScanLine

DirectDraw7.GetScanLine 메소드는, 모니터상에서 현재 드로잉(Drawing) 되고 있는 주사선을 취득한다.

object. GetScanLine(lines As Long) As Long

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.
lines
현재의 주사선.

반환값

성공하면, DD_OK 를 돌려준다. 이것은, 호출측의 어플리케이션이, 실행을 계속되는 것을 나타낸다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DDERR_VERTICALBLANKINPROGRESS

주의

주사선은 제로 베이스의 정수로서 보고된다. 돌려주어지는 주사선의 값은 0 으로부터 n 까지의 값이며, 주사선 0 은 스크린 위에의 최초의 가시 주사선, 주사선 n 는 마지막 가시 주사선이다. 게다가 수직귀선소거 간격에 생기는 임의의 주사선을 더할 수가 있다. 따라서, 어플리케이션이 640×480 으로 실행되어 수직귀선소거 간격에 12 의 주사선이 있는 경우, 이 메소드가 돌려주는 값은 0 에서 491 의 범위가 된다.

참조

DirectDraw7.GetVerticalBlankStatus ,DirectDraw7.WaitForVerticalBlank


DirectDraw7.GetSurfaceFromDC

DirectDraw7.GetSurfaceFromDC 메소드는, 그 GDI 디바이스 콘텍스트 핸들에 근거하는 표면에 대한 DirectDrawSurface7 오브젝트를 취득한다.

object. GetSurfaceFromDC(hdc As Long) As DirectDrawSurface7

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.
hdc
디스플레이 디바이스 콘텍스트에의 핸들.

반환값

성공하면,DirectDrawSurface7 를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_GENERIC
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_NOTFOUND

주의

이 메소드는, DirectDraw 오브젝트에 이미 관련지을 수 있었던 표면을 식별하는, 디바이스 콘텍스트 핸들에 대해서만 성공한다.

참조

표면 문맥과 디바이스 콘텍스트


DirectDraw7.GetSurfacesEnum

DirectDraw7.GetSurfacesEnum 메소드는, DirectDraw7 오브젝트에 Attach 된 표면의 열거에 사용되는 DirectDrawEnumSurfaces 오브젝트를 돌려준다.

object. GetSurfacesEnum( _
    flags As CONST_DDENUMSURFACESFLAGS, _
    desc As DDSURFACEDESC2) As DirectDrawEnumSurfaces

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.
flags
1 개의 검색형 플래그와 1 개의 적업 플래그의 편성을 포함한 CONST_DDENUMSURFACESFLAGS 열거. 검색형 플래그는, 메소드가 적합 플래그를 검색하는 방법을 결정한다. 즉,desc 파라미터의 기술을 사용해 생성 되는 표면을 검색하거나 이미 그 기술에 적합하는 기존의 표면을 검색할 수 있다. 적합 플래그는, 메소드가 모든 표면, 적합하는 표면만, 또는 desc 파라미터의 기술에 적합하지 않는 표면만을 열거할지 어떨지를 결정한다.
desc
대상이 되는 표면을 정의하는 DDSURFACEDESC2 형.

반환값

성공하면,DirectDrawEnumSurfaces 오브젝트를 돌려준다. 이 오브젝트를 사용해, Attach 된 표면의 기술을 조회할 수 있다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
E_OUTOFMEMORY

주의

DDENUMSURFACES_CANBECREATED 플래그를 설정하는 경우, 이 메소드는 검색 기준에 맞는 표면을 일시적으로 생성 하려고 한다.


DirectDraw7.GetVerticalBlankStatus

DirectDraw7.GetVerticalBlankStatus 메소드는, 수직귀선소거의 스테이터스를 취득한다.

object. GetVerticalBlankStatus() As Long

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 수직귀선소거의 스테이터스를 돌려준다. 수직귀선소거가 발생하는 경우에 이 파라미터는 제로가 되어, 그렇지 않은 경우는 제로 이외의 값이 된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

수직귀선소거와 동기 하려면 ,DirectDraw7.WaitForVerticalBlank 메소드를 사용한다.

참조

DirectDraw7.GetScanLine ,DirectDraw7.WaitForVerticalBlank


DirectDraw7.LoadPaletteFromBitmap

DirectDraw7.LoadPaletteFromBitmap 메소드는, 이 DirectDraw 오브젝트로 지정된 비트 맵의 팔레트에 근거해,DirectDrawPalette 오브젝트를 생성 한다.

object. LoadPaletteFromBitmap( _
    bName As String) As DirectDrawPalette

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.
bName
팔레트를 로드하는 비트 맵의 이름.

반환값

성공하면,DirectDrawPalette 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOOPERATIVELEVELSET
DDERR_OUTOFMEMORY
DDERR_UNSUPPORTED


DirectDraw7.RestoreAllSurfaces

DirectDraw7.RestoreAllSurfaces 메소드는, DirectDraw 오브젝트에 대해서 생성 된 표면 모든 것을, 표면을 생성 한 차례로 restore 한다.

object. RestoreAllSurfaces()

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는 편리하다. 이 메소드는, 이 DirectDraw 오브젝트가 생성 하는 표면 마다, 효율적으로 DirectDrawSurface7.Restore 를 호출한다.

참조

DirectDrawSurface7.Restore ,표면의 소실과 restore


DirectDraw7.RestoreDisplayMode

DirectDraw7.RestoreDisplayMode 메소드는,프라이머리 표면의 디스플레이 디바이스 하드웨어의 모드를,DirectDraw7.SetDisplayMode 메소드가 불려 가기 전 상태에 리셋 한다. 이 메소드를 사용하려면 , 배타 레벨의 액세스가 필요하게 된다.

object. RestoreDisplayMode()

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_LOCKEDSURFACES
DDERR_NOEXCLUSIVEMODE

참조

DirectDraw7.SetDisplayMode ,DirectDrawEnumModes ,DirectDraw7.SetCooperativeLevel


DirectDraw7.SetCooperativeLevel

DirectDraw7.SetCooperativeLevel 메소드는, 어플리케이션의 최상정도 동작을 결정한다.

object. SetCooperativeLevel( _
    hdl As Long, _
    flags As CONST_DDSCLFLAGS)

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.
hdl
어플리케이션이 사용하는 윈도우 핸들. 호출하는 어플리케이션의 최상정도 윈도우 핸들로 설정한다 (최상정도 윈도우가 생성 한 자식 윈도우에 대한 핸들은 아니다). flags 파라미터에 DDSCL_NORMAL 플래그를 지정하는 경우, 이 파라미터는 0 이 된다.
flags
CONST_DDSCLFLAGS 열거의 1 개 또는 복수의 정수.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_EXCLUSIVEMODEALREADYSET
DDERR_HWNDALREADYSET
DDERR_HWNDSUBCLASSED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

주의

이 메소드는, 어플리케이션 윈도우를 생성 한 같은 thread로 불려 가지 않으면 안 된다.

어플리케이션은, DDSCL_EXCLUSIVE 또는 DDSCL_NORMAL 플래그의 어느 쪽인지를 설정하지 않으면 안 된다.

다른 어플리케이션에 대해서, 대폭적인 퍼포먼스 변화를 일으킬 가능성이 있는 함수를 호출하려면 , DDSCL_EXCLUSIVE 플래그를 설정하지 않으면 안 된다. 상세한 것에 대하여는, 「협조 레벨」을 참조할것.

참조

DirectDraw7.SetDisplayMode ,DirectDraw7.GetDisplayModesEnum ,모드 X 모드와 모드 13 디스플레이 모드,포커스 윈도우와 디바이스 윈도우


DirectDraw7.SetDisplayMode

DirectDraw7.SetDisplayMode 메소드는, 디스플레이 디바이스 하드웨어의 모드를 설정한다.

object. SetDisplayMode( _
    w As Long, _
    h As Long, _
    bpp As Long, _
    ref As Long, _
    mode As CONST_DDSDMFLAGS)

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.
w,h
새로운 모드의 폭과 높이.
bpp
해상도, 새로운 모드의 비트/픽셀 (bpp).
ref
새로운 모드의 refresh rate. 이 값을 0 으로 설정 하면, 드라이버에 대한 디폴트의 refresh rate를 요구한다.
mode
추가 옵션을 기술하는 CONST_DDSDMFLAGS 열거의 정수의 1 개. 현시점에서 유일한 유효한 플래그는 DDSDM_STANDARDVGAMODE 이며, 메소드로 모드 X 의 320×200×8 모드는 아니고, 모드 13 을 설정할 수 있다. 다른 해상도, 비트 깊이, 또는 모드 X 모드로 설정하는 경우는, 이 플래그를 사용하지 않고 파라미터를 0 으로 설정한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_GENERIC
DDERR_INVALIDMODE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_LOCKEDSURFACES
DDERR_NOEXCLUSIVEMODE
DDERR_SURFACEBUSY
DDERR_UNSUPPORTED
DDERR_UNSUPPORTEDMODE
DDERR_WASSTILLDRAWING

주의

이 메소드는, 어플리케이션 윈도우를 생성 한 같은 thread로 불려 가지 않으면 안 된다.

다른 어플리케이션이 디스플레이 모드를 변경하는 경우,프라이머리 표면은 소실되어 새로운 디스플레이 모드에 적합하도록(듯이) 프라이머리 표면이 재생성 될 때까지,DDERR_SURFACELOST 를 돌려준다.

참조

DirectDraw7.RestoreDisplayMode ,DirectDraw7.GetDisplayModesEnum ,DirectDraw7.SetCooperativeLevel ,디스플레이 모드의 설정,디스플레이 모드의 restore


DirectDraw7.TestCooperativeLevel

DirectDraw7.TestCooperativeLevel 메소드는, 윈도우 또는 풀 스크린 어플리케이션에 대한 DirectDraw 디바이스의 현재의 협조 레벨 스테이터스를 보고한다.

object. TestCooperativeLevel() As Long

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.

반환값

성공하면, DD_OK 를 돌려준다. 이것은, 호출측의 어플리케이션이, 실행을 계속되는 것을 나타낸다.

에러 코드

실패하는지, DD_OK 가 돌려주어지지 않으면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다 ( 「주의」참조).

DDERR_INVALIDOBJECT
DDERR_EXCLUSIVEMODEALREADYSET
DDERR_NOEXCLUSIVEMODE
DD_OK
DDERR_WRONGMODE

주의

이 메소드는, 표면의 restore나 DirectDraw 오브젝트의 재생성의 통지로서 WM_ACTIVATEAPP 및 WM_DISPLAYCHANGE 시스템 메세지를 사용하는 어플리케이션으로 특별히 도움이 된다. 반환값 0 은, 표면을 restore 또는 재생성 하는 일 없이, 어플리케이션이 실행을 계속되는 것을 항상 가리킨다. 그러나, 에러 코드의 해석은, 어플리케이션이 사용하는 협조 레벨에 따라서 다르다. 상세한 것에 대하여는, 「협조 레벨의 테스트」를 참조할것.


DirectDraw7.WaitForVerticalBlank

DirectDraw7.WaitForVerticalBlank 메소드는, 어플리케이션이 수직귀선소거 간격과 함께 동기 하는 방법을 제공한다.

object. WaitForVerticalBlank( _
    flags As CONST_DDWAITVBFLAGS, _
    handle As Long) As Long

파라미터

object
DirectDraw7 오브젝트를 나타내는오브젝트식.
flags
수직귀선소거에 대해서의 대기 시간을 지정하는 CONST_DDWAITVBFLAGS 열거의 정수의 1 개.
handle
수직귀선소거가 발생했을 때에 방아쇠가 되는 이벤트의 핸들. 이 파라미터는, 현시점에서는 사용할 수 없다.

반환값

성공하면, DD_OK 를 돌려준다. 이것은, 호출측의 어플리케이션이, 실행을 계속되는 것을 나타낸다.

에러 코드

실패하는지, DD_OK 가 돌려주어지지 않으면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DD_OK
DDERR_WASSTILLDRAWING

참조

DirectDraw7.GetVerticalBlankStatus ,DirectDraw7.GetScanLine


DirectDrawClipper

어플리케이션은,DirectDrawClipper 클래스의 메소드를 사용해클립 리스트를 관리한다. 이 항은, 이 클래스의 메소드의 레퍼런스이다. 개요에 대해서는, 「클립퍼」를 참조할것.

DirectDrawClipper 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

클립 리스트 | GetClipList
 | GetClipListSize
 | IsClipListChanged
 | SetClipList
핸들 | GetHWnd
 | SetHWnd


DirectDrawClipper.GetClipList

DirectDrawClipper.GetClipList 메소드는, DirectDrawClipper 오브젝트에 관련지을 수 있었던클립 리스트의 카피를 취득한다.

object. GetClipList(rects() As RECT)

파라미터

object
DirectDrawClipper 오브젝트를 나타내는오브젝트식.
rects()
클립 리스트가 저장 되는 RECT 형의 배열.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_GENERIC
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCLIPLIST
DDERR_REGIONTOOSMALL

참조

DirectDrawClipper.SetClipList


DirectDrawClipper.GetClipListSize

DirectDrawClipper.GetClipListSize 메소드는, DirectDrawClipper 오브젝트에 관련지을 수 있었던클립 리스트의 사이즈를 취득한다.

object. GetClipListSize() As Long

파라미터

object
DirectDrawClipper 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 클립 리스트의 사이즈를 바이트 단위로 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_GENERIC
DDERR_INVALIDPARAMS
DDERR_NOCLIPLIST


DirectDrawClipper.GetHWnd

DirectDrawClipper.GetHWnd 메소드는,DirectDrawClipper.SetHWnd 메소드에 의해 이 DirectDrawClipper 오브젝트에 관련지을 수 있었던 윈도우 핸들을 취득한다.

object. GetHWnd() As Long

파라미터

object
DirectDrawClipper 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 윈도우 핸들을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

참조

DirectDrawClipper.SetHWnd


DirectDrawClipper.IsClipListChanged

DirectDrawClipper.IsClipListChanged 메소드는, DirectDrawClipper 오브젝트에 윈도우 핸들을 관련지을 수 있고 있는 경우에,클립 리스트 상태를 모니터 한다.

object. IsClipListChanged() As Long

파라미터

object
DirectDrawClipper 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 클립 리스트 상태를 돌려준다. 클립 리스트가 변경되고 있는 경우는 제로 이외의 값, 변경되어 있지 않은 경우는 제로가 된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


DirectDrawClipper.SetClipList

DirectDrawClipper.SetClipList 메소드는, 친 DirectDrawClipper 오브젝트가 Attach 된 표면상에서,DirectDrawSurface7.Blt 메소드가 사용하는클립 리스트를 설정 또는 삭제한다.

object. SetClipList( _
    count As Long, _
    rects() as RECT)

파라미터

object
DirectDrawClipper 오브젝트를 나타내는오브젝트식.
count
rects( ) 배열의 RECT 형의 수.
rects()
클립 리스트를 기술하는 RECT 형의 배열.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_CLIPPERISUSINGHWND
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

주의

윈도우 핸들이 이미 DirectDrawClipper 오브젝트에 관련지을 수 있고 있는 경우, 클립 리스트는 설정되지 않는다. DirectDrawSurface7.BltFast 메소드에서는 클립 할 수 없다.

참조

DirectDrawClipper.GetClipList ,DirectDrawSurface7.Blt ,DirectDrawSurface7.BltFast


DirectDrawClipper.SetHWnd

DirectDrawClipper.SetHWnd 메소드는, 클리핑 정보를 취득하는 윈도우 핸들을 설정한다.

object. SetHWnd(hdl As Long)

파라미터

object
DirectDrawClipper 오브젝트를 나타내는오브젝트식.
hdl
클리핑 정보를 취득하는 윈도우 핸들.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

참조

DirectDrawClipper.GetHWnd


DirectDrawColorControl

DirectDrawColorControl 클래스의 메소드를 사용해, 컬러 컨트롤을 취득하거나 설정할 수가 있다. 이 오브젝트는,DirectDrawSurface7.GetDirectDrawColorControl 에 의해 생성 된다. 이 클래스에는, 다음의 2 개의 메소드가 있다.

컬러 컨트롤 | GetColorControls
 | SetColorControls


DirectDrawColorControl.GetColorControls

DirectDrawColorControl.GetColorControls 메소드는, 지정한 오버레이나프라이머리 표면에 관련지을 수 있었던 현재의 컬러 컨트롤의 설정을 돌려준다. DDCOLORCONTROL 형의 lFlags 멤버는, 지원 되는 컬러 컨트롤 옵션을 나타낸다.

object. GetColorControls(colorControl As DDCOLORCONTROL)

파라미터

object
DirectDrawColorControl 오브젝트를 나타내는오브젝트식.
colorControl
지정한 표면의 현재의 컬러 컨트롤 설정을 받는 DDCOLORCONTROL 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

주의

DirectDraw 디바이스가 컬러 컨트롤을 지원 하고 있지 않는 경우, 이 메소드는 실패한다.

참조

DirectDrawColorControl.SetColorControls ,컬러 컨트롤의 사용,감마 컨트롤과 컬러 컨트롤


DirectDrawColorControl.SetColorControls

DirectDrawColorControl.SetColorControls 메소드는, 지정한 오버레이나프라이머리 표면에 관련지을 수 있었던 컬러 컨트롤을 설정한다.

object. SetColorControls(colorControl As DDCOLORCONTROL)

파라미터

object
DirectDrawColorControl 오브젝트를 나타내는오브젝트식.
colorControl
지정한 표면에 적용되는 새로운 값을 포함한 DDCOLORCONTROL 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

참조

DirectDrawColorControl.GetColorControls ,컬러 컨트롤의 사용,감마 컨트롤과 컬러 컨트롤


DirectDrawEnum

어플리케이션은,DirectDrawEnum 클래스의 메소드를 사용해, 컴퓨터에 인스톨 된 비디오 디스플레이 어댑터에 관한 정보를 취득한다. 이 오브젝트는,DirectX7.GetDDEnum 메소드에 의해 생성 되어 데이터가 저장 된다.

DirectDraw 열거 | GetCount
 | GetDescription
 | GetGuid
 | GetMonitorHandle
 | GetName


DirectDrawEnum.GetCount

DirectDrawEnum.GetCount 메소드는, 시스템에 인스톨 된 DirectDraw 드라이버의 수를 돌려준다.

object. GetCount() As Long

파라미터

object
DirectDrawEnum 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 열거 오브젝트의 엔트리의 수를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

각 엔트리에 1 개의 DirectDraw 드라이버가 기술된다. 각각의 드라이버의 기술을 취득하려면 ,DirectDrawEnum.GetDescription ,DirectDrawEnum.GetGuid , 및 DirectDrawEnum.GetName 를 사용한다.


DirectDrawEnum.GetDescription

DirectDrawEnum.GetDescription 메소드는, 지정한 DirectDraw 디바이스의 드라이버의 기술을 돌려준다.

object. GetDescription(index As Long) As String

파라미터

object
DirectDrawEnum 오브젝트를 나타내는오브젝트식.
index
DirectDrawEnum 오브젝트내의 특정의 DirectDraw 디바이스.

반환값

성공하면, 그 디바이스의 드라이버의 기술을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectDrawEnum.GetGuid

DirectDrawEnum.GetGuid 는, 지정한 DirectDraw 디바이스의 고유의 식별자를 돌려준다.

object. GetGuid(index As Long) As String

파라미터

object
DirectDrawEnum 오브젝트를 나타내는오브젝트식.
index
DirectDrawEnum 오브젝트내의 특정의 DirectDraw 디바이스.

반환값

성공하면, 디바이스의 고유의 식별자를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectDrawEnum.GetMonitorHandle

DirectDrawEnum.GetMonitorHandle 는, 지정한 DirectDraw 디바이스의 모니터 핸들을 돌려준다.

object. GetName(index As Long) As Long

파라미터

object
DirectDrawEnum 오브젝트를 나타내는오브젝트식.
index
DirectDrawEnum 오브젝트내의 특정의 DirectDraw 디바이스.

반환값

성공하면, 그 디바이스의 모니터 핸들을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectDrawEnum.GetName

DirectDrawEnum.GetName 는, 지정한 DirectDraw 디바이스의 드라이버명을 돌려준다.

object. GetName(index As Long) As String

파라미터

object
DirectDrawEnum 오브젝트를 나타내는오브젝트식.
index
DirectDrawEnum 오브젝트내의 특정의 DirectDraw 디바이스.

반환값

성공하면, 그 디바이스의 드라이버명을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 이 설정된다.


DirectDrawEnumModes

어플리케이션은,DirectDrawEnumModes 클래스의 메소드를 사용해, 그 컴퓨터로 사용 가능한 비디오 모드를 열거한다. 이 오브젝트는,DirectDraw7.GetDisplayModesEnum 메소드에 의해 생성 되어 데이터가 저장 된다.

DirectDraw 모드 열거 | GetCount
 | GetItem


DirectDrawEnumModes.GetCount

DirectDrawEnumModes.GetCount 메소드는, 사용 가능한 비디오 모드의 수를 돌려준다.

object. GetCount() As Long

파라미터

object
DirectDrawEnumModes 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 사용 가능한 비디오 모드의 수를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

각 엔트리에 1 개의 비디오 모드가 기술된다. 각각의 비디오 모드의 기술을 취득하려면 ,DirectDrawEnumModes.GetItem 를 사용한다.


DirectDrawEnumModes.GetItem

DirectDrawEnumModes.GetItem 메소드는, 열거 오브젝트로 지정한 요소의 비디오 모드의 기술을 돌려준다.

object. GetItem(index As Long, info As DDSURFACEDESC2)

파라미터

object
DirectDrawEnumModes 오브젝트를 나타내는오브젝트식.
index
배열의 어느 요소에 액세스 하는지를 나타내는 번호. 각 요소가 사용 가능한 비디오 모드가 된다.
info
비디오 모드 정보가 저장 되는 DDSURFACEDESC2 형.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

DirectDrawEnumModes 오브젝트에 포함되는 비디오 모드의 수는,DirectDrawEnumModes.GetCount 에 의해 취득할 수 있다.


DirectDrawEnumSurfaces

어플리케이션은,DirectDrawEnumSurfaces 클래스의 메소드를 사용해, 생성 된 모든 표면을 열거한다. 이 오브젝트는,DirectDrawSurface7.GetAttachedSurfaceEnum 메소드에 의해 생성 되어 데이터가 저장 된다.

DirectDraw 표면 열거 | GetCount
 | GetItem


DirectDrawEnumSurfaces.GetCount

DirectDrawEnumSurfaces.GetCount 메소드는, 생성 된 표면의 수를 돌려준다.

object. GetCount() As Long

파라미터

object
DirectDrawEnumSurfaces 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 생성 된 표면의 수를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

각 엔트리에 생성 된 DirectDraw 표면이 기술된다. 각 표면의 기술을 취득하려면 ,DirectDrawEnumSurfaces.GetItem 를 사용한다.


DirectDrawEnumSurfaces.GetItem

DirectDrawEnumSurfaces.GetItem 메소드는,DirectDrawEnumSurfaces 오브젝트에 포함되는 생성 된 표면의 리스트로부터, 특정의 표면을 돌려준다.

object. GetItem(index As Long) As DirectDrawSurface7

파라미터

object
DirectDrawEnumSurfaces 오브젝트를 나타내는오브젝트식.
index
배열의 어느 요소에 액세스 하는지를 나타내는 번호. 각 요소가 생성 된 표면을 나타낸다.

반환값

그 표면을 기술하는 DirectDrawSurface7 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

생성 된 표면의 수를 취득하려면 ,DirectDrawEnumSurfaces.GetCount 메소드를 호출한다.


DirectDrawGammaControl

어플리케이션은 DirectDrawGammaControl 클래스의 메소드를 사용해, 프라이머리 표면의 적, 초록, 및 파랑 감마 램프 레벨을 조정한다. 이 항은, 이 클래스의 메소드의 레퍼런스이다. 이 오브젝트는,DirectDrawSurface7.GetDirectDrawGammaControl 메소드에 의해 생성 된다.

개요에 대해서는, 「감마 컨트롤과 컬러 컨트롤」을 참조할것.

감마 램프 | GetGammaRamp
 | SetGammaRamp


DirectDrawGammaControl.GetGammaRamp

DirectDrawGammaControl.GetGammaRamp 메소드는, 프라이머리 표면에 대한 적, 초록, 및 파랑의 감마 램프를 취득한다.

object. GetGammaRamp( _
    flags As CONST_DDSGRFLAGS, _
    gammaRamp As DDGAMMARAMP)

파라미터

object
DirectDrawGammaControl 오브젝트를 나타내는 오브젝트식.
flags
감마 calibration를 요구할지 어떨지를 나타내는 CONST_DDSGRFLAGS 열거의 정수의 1 개. 이 파라미터를 DDSGR_CALIBRATE 로 설정 하면, 구경 측정기가 모든 시스템상에서 동일하게 되도록(듯이), 디스플레이의 물리적 성질에 따라, 감마 램프의 조절을 요구할 수 있다. calibration를 필요로 하지 않는 경우는, 이 파라미터를 0 으로 설정한다.
gammaRamp
현재의 적, 초록, 및 파랑의 감마 램프를 포함한 DDGAMMARAMP 형. 이 형태는, frame buffer의 색의 값을 디지털-아날로그 컨버터 (DAC)에 건네주는 색의 값에 맵 한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

참조

DirectDrawGammaControl.SetGammaRamp ,감마 컨트롤과 컬러 컨트롤


DirectDrawGammaControl.SetGammaRamp

DirectDrawGammaControl.SetGammaRamp 메소드는, 프라이머리 표면에 대한 적, 초록, 및 파랑의 감마 램프를 설정한다.

object. SetGammaRamp( _
    flags As CONST_DDSGRFLAGS, _
    gammaRamp As DDGAMMARAMP)

파라미터

object
DirectDrawGammaControl 오브젝트를 나타내는 오브젝트 식.
flags
감마 calibration를 요구할지 어떨지를 나타내는 CONST_DDSGRFLAGS 열거의 정수의 1 개. 이 파라미터를 DDSGR_CALIBRATE 로 설정 하면, 구경 측정기가 모든 시스템상에서 동일하게 되도록(듯이), 디스플레이의 물리적 성질에 따라, 감마 램프의 조정을 요구할 수 있다. calibration를 필요로 하지 않는 경우는, 이 파라미터를 0 으로 설정한다.
gammaRamp
새로운 적, 초록, 및 파랑의 감마 램프 엔트리를 포함한 DDGAMMARAMP 형. 각각의 배열은, frame buffer의 색의 값을 디지털-아날로그 컨버터 (DAC)에 건네주는 색의 값에 맵 한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

주의

모든 시스템으로 감마 calibration를 지원 하는 것은 아니다. 감마 calibration를 지원 할지 어떨지를 결정하려면 ,DirectDraw7.GetCaps 를 호출해, 메소드가 돌려준 후에 관련하는 DDCAPS 형의 lCaps2 멤버를 조사한다. DDCAPS_CANCALIBRATEGAMMA 능력 플래그가 존재 하면, 감마 calibration는 지원 된다.

감마 램프의 calibration에서는, 몇개의 처리에 오버헤드가 일어나므로, 빈번하게 사용할 수 없다.

감마 calibration를 지원 하지 않는 시스템상에서 실행하는 경우,flags 파라미터에 DDSGR_CALIBRATE 플래그를 설정 하면, 이 메소드는 성공한다. calibration 하지 않고 새로운 감마 램프값을 설정 하면, 메소드는 성공한다.

참조

DirectDrawGammaControl.GetGammaRamp ,감마 컨트롤과 컬러 컨트롤


DirectDrawIdentifier

어플리케이션은,DirectDrawIdentifier 클래스의 메소드를 사용해, DirectDraw 드라이버에 관한 정보를 취득한다. 심한 드라이버나 칩 세트 반응의 회피 방법을 이행 하는 특정의 하드웨어 인스톨을 인식하려면 , 이 오브젝트를 주의해 사용하는 것. 이 오브젝트는,DirectDraw7.GetDeviceIdentifier 메소드에 의해 생성 된다.

DirectDrawdentifier 의 메소드는, 이하의 그룹에 정리할 수가 있다.

드라이버 정보 | GetDescription
 | GetDeviceId
 | GetDeviceIdentifier
 | GetDriver
 | GetDriverSubVersion
 | GetDriverVersion
 | GetRevision
 | GetSubSysId
 | GetVendorId
 | GetWHQLLevel


DirectDrawIdentifier.GetDescription

DirectDrawIdentifier.GetDescription 메소드는, 드라이버의 기술을 돌려준다.

object. GetDescription() As String

파라미터

object
DirectDrawIdentifier 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 드라이버의 기술을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectDrawIdentifier.GetDeviceId

DirectDrawIdentifier.GetDeviceId 메소드는, 칩 세트의 타입을 나타내는 식별자를 돌려준다.

object. GetDeviceId() As Long

파라미터

object
DirectDrawIdentifier 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 칩 세트의 타입을 나타내는 식별자를 돌려준다. 불명의 경우는 0.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectDrawIdentifier.GetDeviceIdentifier

DirectDrawIdentifier.GetDeviceIndentifier 메소드는, 드라이버/칩 세트 페어 고유의 식별자를 돌려준다.

object. GetDeviceIndentifier() As String

파라미터

object
DirectDrawIdentifier 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 드라이버/칩 세트의 GUID 를 돌려준다. 불명의 경우는 0.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

드라이버/칩 세트에의 변경을 조사해, 그래픽스 서브시스템 의 프로필을 재생성 하고 싶은 경우는, 여기서 돌려주어진 GUID 를 사용한다. 또, 특정의 의심스러운 드라이버를 식별하는 경우에도 사용할 수 있다.


DirectDrawIdentifier.GetDriver

DirectDrawIdentifier.GetDriver 메소드는, DirectDraw 디바이스 드라이버의 이름을 돌려준다.

object. GetDriver() As String

파라미터

object
DirectDrawIdentifier 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 드라이버명을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectDrawIdentifier.GetDriverSubVersion

DirectDrawIdentifier.GetDriverSubVersion 메소드는, 드라이버의 서브 버젼을 돌려준다.

object. GetDriverSubVersion() As Long

파라미터

object
DirectDrawIdentifier 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 드라이버의 서브 버젼을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

이 요소를 사용해 의심스러운 드라이버를 식별하는 경우는, 주의해 실시하는 것. 이 목적을 위해서(때문에)는, 디바이스 식별자를 사용하는 것을 권한다.


DirectDrawIdentifier.GetDriverVersion

DirectDrawIdentifier.GetDriverVersion 메소드는, 드라이버의 메인 버젼을 돌려준다.

object. GetDriverVersion() As Long

파라미터

object
DirectDrawIdentifier 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 드라이버의 메인 버젼을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

이 요소를 사용해 의심스러운 드라이버를 식별하는 경우는, 주의해 실시하는 것. 이 목적을 위해서(때문에)는, 디바이스 식별자를 사용하는 것을 권한다.


DirectDrawIdentifier.GetRevision

DirectDrawIdentifier.GetRevision 메소드는, 칩 세트의 개정판 레벨을 돌려준다.

object. GetRevision() As Long

파라미터

object
DirectDrawIdentifier 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 칩 세트의 개정판 레벨의 식별자를 돌려준다. 불명의 경우는 0.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectDrawIdentifier.GetSubSysId

DirectDrawIdentifier.GetSubSysId 메소드는, 서브 시스템의 식별자를 돌려준다.

object. GetSubSysId() As Long

파라미터

object
DirectDrawIdentifier 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 서브 시스템의 식별자를 돌려준다. 보통, 특정의 기반을 의미한다. 불명의 경우는 0.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectDrawIdentifier.GetVendorId

DirectDrawIdentifier.GetVendorId 메소드는, 메이커의 식별자를 돌려준다.

object. GetVendorId() As Long

파라미터

object
DirectDrawIdentifier 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 메이커의 식별자를 돌려준다. 불명의 경우는 0.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectDrawIdentifier.GetWHQLLevel

DirectDrawIdentifier.GetWHQLLevel 메소드는, 디바이스/드라이버 페어의 WHQL (Windows Hardware Quality Lab) 인증 레벨을 취득한다.

object. GetWHQLLevel() As Long

파라미터

object
DirectDrawIdentifier 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 디바이스/드라이버 페어의 WHQL (Windows Hardware Quality Lab) 인증 레벨을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectDrawPalette

어플리케이션은,DirectDrawPalette 클래스의 메소드를 사용해, DirectDrawPalette 오브젝트를 생성 해, 시스템 레벨 변수와 함께 작용한다. DirectDrawPalette 오브젝트는,DirectDrawSurface7.GetPalette 메소드에 의해 생성 된다.

이 항은, 이 클래스의 메소드의 레퍼런스이다. 개요에 대해서는, 「팔레트」를 참조할것.

DirectDrawPalette 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

팔레트 능력 | GetCaps
팔레트 엔트리 | GetEntries
 | SetEntries


DirectDrawPalette.GetCaps

DirectDrawPalette.GetCaps 메소드는, 이 팔레트 오브젝트의 능력을 취득한다.

object. GetCaps() As CONST_DDPCAPSFLAGS

파라미터

object
DirectDrawPalette 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 팔레트 오브젝트의 능력을 나타내는 CONST_DDPCAPSFLAGS 열거의 정수의 1 개를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


DirectDrawPalette.GetEntries

DirectDrawPalette.GetEntries 메소드는, DirectDrawPalette 오브젝트로부터의 팔레트값을 조회한다.

object. GetEntries( _
    start As Long, _
    count As Long, _
    val() As PALETTEENTRY)

파라미터

object
DirectDrawPalette 오브젝트를 나타내는오브젝트식.
start
차례로 취득하는 엔트리의 시작.
count
val() 로 지정하는 주소에 적합하는 팔레트 엔트리의 수. 각각의 팔레트 엔트리의 색은,start 파라미터의 값으로부터 count 파라미터로부터 1 을 뺀 값까지, 차례로 돌려주어진다 (이러한 값은,DirectDrawPalette.SetEntries 로 설정된다).
val()
PALETTEENTRY 형의 변수의 배열. DirectDraw7.CreatePalette 의 flags 파라미터에 DDPCAPS_8BITENTRIES 플래그가 설정되어 있는 경우, 팔레트 엔트리는 1 바이트마다가 된다. 그 이외는 4 바이트마다가 된다. 각각의 필드는, 색기술이 된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTPALETTIZED

참조

DirectDrawPalette.SetEntries


DirectDrawPalette.SetEntries

DirectDrawPalette.SetEntries 메소드는, DirectDrawPalette 오브젝트의 엔트리를 즉석에서 변경한다.

object. SetEntries( _
    start As Long, _
    count As Long, _
    val() As PALETTEENTRY)

파라미터

object
DirectDrawPalette 오브젝트를 나타내는오브젝트식.
start
설정되는 최초의 엔트리.
count
변경되는 팔레트 엔트리의 수.
val()
PALETTEENTRY 형의 변수의 배열. DirectDraw7.CreatePalette 의 flags 파라미터에 DDPCAPS_8BITENTRIES 플래그가 설정되어 있는 경우, 팔레트 엔트리는 1 바이트마다가 된다. 그 이외는 4 바이트마다가 된다. 각각의 필드는, 색기술이 된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOPALETTEATTACHED
DDERR_NOTPALETTIZED
DDERR_UNSUPPORTED

참조

DirectDrawPalette.GetEntries ,DirectDrawSurface7.SetPalette


DirectDrawSurface7

어플리케이션은 DirectDrawSurface7 클래스의 메소드를 사용해, DirectDrawSurface 오브젝트를 생성 해, 시스템 레벨 변수와 함께 작용한다. 이 항은, 이 클래스의 메소드의 레퍼런스이다. 개요에 대해서는, 「표면」을 참조할것.

DirectDrawSurface7 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

메모리의 할당 | IsLost
 | Restore
표면의 Attach | AddAttachedSurface
 | DeleteAttachedSurface
 | GetAttachedSurface
 | GetAttachedSurfaceEnum
블리트 | Blt
 | BltColorFill
 | BltFast
 | BltFx
 | BltToDC
 | GetBltStatus
컬러 키잉 | GetColorKey
 | SetColorKey
디바이스 콘텍스트 | GetDC
 | ReleaseDC
드로잉(Drawing)와 텍스트 | DrawBox
 | DrawCircle
 | DrawEllipse
 | DrawLine
 | DrawRoundedBox
 | DrawText
 | GetDrawStyle
 | GetDrawWidth
 | GetFillColor
 | GetFillStyle
 | GetFontBackColor
 | GetFontTransparency
 | GetForeColor
 | SetDrawStyle
 | SetDrawWidth
 | SetFillColor
 | SetFillStyle
 | SetFont
 | SetFontBackColor
 | SetFontTransparency
 | SetForeColor
플립핑 | Flip
 | GetFlipStatus
락 | GetLockedArray
 | GetLockedPixel
 | Lock
 | SetLockedPixel
 | Unlock
그 외 | GetDirectDraw
 | GetDirectDrawColorControl
 | GetDirectDrawGammaControl
오버레이 | GetOverlayPosition
 | GetOverlayZOrdersEnum
 | SetOverlayPosition
 | UpdateOverlay
 | UpdateOverlayFx
 | UpdateOverlayZOrder
표면 능력 | GetCaps
표면 클립퍼 | GetClipper
 | SetClipper
표면 특성 | ChangeUniquenessValue
 | GetPixelFormat
 | GetSurfaceDesc
 | GetUniquenessValue
표면 팔레트 | GetPalette
 | SetPalette
텍스쳐 | GetLOD
 | GetPriority
 | SetLOD
 | SetPriority


DirectDrawSurface7.AddAttachedSurface

DirectDrawSurface7.AddAttachedSurface 메소드는, 지정한 표면을 이 표면에 Attach 한다.

object. AddAttachedSurface(ddS As DirectDrawSurface7)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
ddS
Attach 되는 표면에 대한 DirectDrawSurface7 오브젝트.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_CANNOTATTACHSURFACE
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACEALREADYATTACHED
DDERR_SURFACELOST
DDERR_WASSTILLDRAWING

주의

DirectDrawSurface7.DeleteAttachedSurface 메소드를 사용해, 명시적으로 표면의 Attach를 해제할 수 있다. DirectDraw7.CreateSurface 의 호출로 생성 하는복합 표면과는 달라, 이 메소드로 Attach 되는 표면은 자동적으로 릴리즈 되지 않는다. 이러한 표면의 릴리즈는, 어플리케이션의 역할이다.

Z 버퍼,알파 채널, 및백 버퍼를 포함한 Attach가 가능하다. 자동적으로 다른 Attach를 절단 하는 Attach도 있다. 예를 들어, 3D Z 버퍼를 한 번에 1 개의 백 버퍼인 만큼 Attach 할 수가 있다. Attach는 쌍방향적이지 않기 때문에, 표면을 그 자체에 Attach 할 수 없다. 에뮬레이트되어 있지 않은 표면에, 에뮬레이트 된 표면 (시스템 메모리내)을 Attach 할 수 없다. 1 개의 표면이 텍스쳐 맵이 아닌 한, 2 개의 Attach 된 표면은 같은 사이즈가 아니면들 없다. 플립핑 표면을 같은 형태의 다른 플립핑 표면에 Attach 할 수 없지만, 다른 타입의 2 개의 표면을 Attach 할 수가 있다. 예를 들어, 플립핑 Z 버퍼를, 보통의 플립핑 표면에 Attach 할 수 있다. 플립핑 하지 않는 표면을 같은 타입의 다른 플립핑 하지 않는 표면에 Attach 하면, 2 개의 표면은 플립핑 체인이 된다. 플립핑 하지 않는 표면을 플립핑 표면에 Attach 하면, 기존의 플립핑 체인의 일부가 된다. 추가 표면은 이 체인에 추가되어DirectDrawSurface7.Flip 메소드를 호출할 때 마다 표면을 1 스텝 진행되게 한다.

참조

DirectDrawSurface7.DeleteAttachedSurface ,DirectDrawSurface7.GetAttachedSurfaceEnum


DirectDrawSurface7.Blt

DirectDrawSurface7.Blt 메소드는, 비트 블리트를 실행한다. 이 메소드는, 블리트 처리중에 Z 버퍼 또는 알파 블렌딩 (알파 채널을 참조)을 지원 하지 않는다.

object. Blt( _
    destRect As RECT, _
    ddS As DirectDrawSurface7, _
    srcRect As RECT, _
    flags As CONST_DDBLTFLAGS) As Long

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
destRect
목적지 표면상에 블리트 하는 직사각형의 좌상과 우하의 위치를 정의하는 RECT 형. 이 파라미터가 하늘의 RECT 형의 경우, 목적지 표면 전체를 사용한다.
ddS
블리트의 전송원인 DirectDrawSurface 오브젝트에 대한 DirectDrawSurface7 오브젝트.
srcRect
전송원표면상으로부터 블리트 하는 직사각형의 좌상과 우하의 위치를 정의하는 RECT 형. 이 파라미터가 하늘의 RECT 의 경우, 전송원표면 전체를 사용한다.
flags
컬러 키 정보를 지정한다, 또는 메소드로부터 특별한 동작을 요구하는, 관련지을 수 있었던 DDBLTFX 형의 유효 멤버를 결정하는 CONST_DDBLTFLAGS 열거의 정수의 편성.

에러 코드

실패하면, 다음의 몇개의 에러 코드를 돌려준다.

DDERR_GENERIC
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOALPHAHW
DDERR_NOBLTHW
DDERR_NOCLIPLIST
DDERR_NODDROPSHW
DDERR_NOMIRRORHW
DDERR_NORASTEROPHW
DDERR_NOROTATIONHW
DDERR_NOSTRETCHHW
DDERR_NOZBUFFERHW
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

주의

이 메소드는, 동기 또는 비동기의 블리트 (후자는, 디폴트 동작)를, 디스플레이 메모리로부터 디스플레이 메모리에, 디스플레이 메모리로부터 시스템 메모리에, 시스템 메모리로부터 디스플레이 메모리에, 시스템 메모리로부터 시스템 메모리에의 어느쪽이든으로 실행하는 능력이 있다. 블리트는,전송원컬러 키 및목적지 컬러 키를 사용해 실행된다. 전송원 및 목적지 직사각형이 같은 사이즈가 아닌 경우, 임의의신축(스트레치)나 수축을 한다.

보통, 블리트가 Busy의 경우, 또는 블리트를 셋업 할 수 없었던 경우,DirectDrawSurface7.Blt 는 에러와 함께 즉석에서 돌아간다. 동기 블리트를 요구하려면 , DDBLT_WAIT 플래그를 지정한다. DDBLT_WAIT 플래그를 지정 하면, 블리트가 셋업 되는지, 메소드가 돌아가기 전에 다른 에러가 발생할 때까지, 이 메소드는 대기한다.

right 및 bottom 멤버는 배타이므로,dstRect 와 srcRect 파라미터를 정의하는 것에 주의한다. 따라서,right 로부터 left 를 빼면(자) 직사각형의폭과 동일해진다. 이것은, 직사각형의 폭으로부터 1 을 뺀 값은 아니다.

이 메소드는 자주 에러를 일으키므로, 에러 오브젝트에 에러를 설정하는 대신에, 에러 코드를 돌려준다.


DirectDrawSurface7.BltColorFill

DirectDrawSurface7.BltColorFill 메소드는, 지정한 목적지 직사각형에, 단색의 비트 블리트를 실행한다.

object. BltColorFill( _
    destRect As RECT, _
    fillvalue As Long) As Long

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
destRect
목적지 표면상에 블리트 하는 직사각형의 좌상과 우하의 위치를 정의하는 RECT 형. 이 파라미터가 RECT 형의 경우, 목적지 표면 전체를 사용한다.
fillvalue
블리트 하는 컬러.

에러 코드

실패하면, 다음의 몇개의 에러 코드 돌려준다.

DDERR_GENERIC
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOALPHAHW
DDERR_NOBLTHW
DDERR_NOCLIPLIST
DDERR_NODDROPSHW
DDERR_NOMIRRORHW
DDERR_NORASTEROPHW
DDERR_NOROTATIONHW
DDERR_NOSTRETCHHW
DDERR_NOZBUFFERHW
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED

주의

이 메소드는 자주 에러를 일으키므로, 에러 오브젝트에 에러를 설정하는 대신에, 에러 코드를 돌려준다.


DirectDrawSurface7.BltFast

DirectDrawSurface7.BltFast 메소드는,전송원컬러 키 또는목적지 컬러 키를 사용해, 전송원카피 블리트 또는 투과형 블리트를 실행한다.

object. BltFast( _
    dx As Long, _
    dy As Long, _
    ddS As DirectDrawSurface7, _
    srcRect As RECT, _
    trans As CONST_DDBLTFASTFLAGS) As Long

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
dx,dy
목적지 표면상에 블리트 하는 x 좌표와 y 좌표.
ddS
블리트의 전송원인 DirectDrawSurface 오브젝트에 대한 DirectDrawSurface7 오브젝트.
srcRect
전송원표면상으로부터 블리트 하는 직사각형의 좌상과 우하의 위치를 정의하는 RECT 형.
trans
전송의 타입을 식별하는 CONST_DDBLTFASTFLAGS 열거의 정수의 1 개.

에러 코드

실패하면, 다음의 몇개의 에러 코드를 돌려준다.

DDERR_EXCEPTION
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOBLTHW
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

주의

하드웨어가 비동기 블리트를 지원 하는 경우, 이 메소드는 항상 그것을 시도한다.

이 메소드는 디스플레이 메모리 표면상에서만 작용해, 블리트중은 클립 할 수 없다. Attach 한 클립퍼가 있는 표면상에서 이 메소드를 사용하는 경우, 호출은 실패해, 메소드는 DDERR_UNSUPPORTED 를 돌려준다.

DirectDrawSurface7.BltFast 의 소프트웨어 이행은,DirectDrawSurface7.Blt 메소드보다 10 퍼센트 고속이 된다. 다만, 디스플레이 하드웨어를 사용하고 있는 경우는, 속도의 차이는 없다.

보통, 블리트가 Busy의 경우, 및 블리트가 셋업되어 있지 않은 경우,DirectDrawSurface7.BltFast 는 즉석에서 에러를 돌려준다. 다만, 블리트가 셋업 될까 다른 에러가 발생할 때까지, 이 메소드를 돌려주지 않는 경우는, DDBLTFAST_WAIT 플래그를 사용한다.

이 메소드는 자주 에러를 일으키므로, 에러 오브젝트에 에러를 설정하는 대신에, 에러 코드를 돌려준다.


DirectDrawSurface7.BltFx

DirectDrawSurface7.BltFx 메소드는,BltFx 파라미터로 지정한 블리트 이펙트 동작을 추가해, 비트 블리트를 실행한다.

object. BltFx( _
    destRect As RECT, _
    ddS As DirectDrawSurface7, _
    srcRect As RECT, _
    flags As CONST_DDBLTFLAGS, _
    BltFx As DDBLTFX) As Long

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
destRect
목적지 표면상에 블리트 하는 직사각형의 좌상과 우하의 위치를 정의하는 RECT 형. 이 파라미터가 하늘의 RECT 형의 경우, 목적지 표면 전체를 사용한다.
ddS
블리트의 전송 바탕으로 되는 DirectDrawSurface7 오브젝트.
srcRect
전송원표면상으로부터 블리트 하는 직사각형의 좌상과 우하의 위치를 정의하는 RECT 형. 이 파라미터가 하늘의 RECT 의 경우, 전송원표면 전체를 사용한다.
flags
컬러 키 정보를 지정한다, 또는 메소드로부터 특별한 동작을 요구하는, 관련지을 수 있었던 DDBLTFX 형의 유효 멤버를 결정하는 CONST_DDBLTFLAGS 열거의 정수의 편성.
BltFx
실행하는 추가의 블리트 이펙트 동작을 지정하는 DDBLTFX 형.

에러 코드

실패하면, 다음의 몇개의 에러 코드를 돌려준다.

DDERR_GENERIC
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOALPHAHW
DDERR_NOBLTHW
DDERR_NOCLIPLIST
DDERR_NODDROPSHW
DDERR_NOMIRRORHW
DDERR_NORASTEROPHW
DDERR_NOROTATIONHW
DDERR_NOSTRETCHHW
DDERR_NOZBUFFERHW
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED

주의

이 메소드는 자주 에러를 일으키므로, 에러 오브젝트에 에러를 설정하는 대신에, 에러 코드를 돌려준다.


DirectDrawSurface7.BltToDC

DirectDrawSurface7.BltToDC 메소드는, 지정한 디바이스 콘텍스트에 비트 블리트를 실행한다.

object. BltToDC( _
    hdc As LONG, _
    srcRect As RECT, _
    destRect As RECT)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
hdc
디바이스 콘텍스트의 핸들.
srcRect
전송원표면상으로부터 블리트 하는 직사각형의 좌상과 우하의 위치를 정의하는 RECT 형. 이 파라미터가 하늘의 RECT 형의 경우, 전송원표면 전체를 사용한다.
destRect
목적지 표면상에 블리트 하는 직사각형의 좌상과 우하의 위치를 정의하는 RECT 형. 이 파라미터가 하늘의 RECT 의 경우, 전송원표면 전체를 사용한다.

에러 코드

실패하면, 다음의 몇개의 에러 코드를 돌려준다.

DDERR_GENERIC
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOALPHAHW
DDERR_NOBLTHW
DDERR_NOCLIPLIST
DDERR_NODDROPSHW
DDERR_NOMIRRORHW
DDERR_NORASTEROPHW
DDERR_NOROTATIONHW
DDERR_NOSTRETCHHW
DDERR_NOZBUFFERHW
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED

주의

이 메소드는 자주 에러를 일으키므로, 에러 오브젝트에 에러를 설정하는 대신에, 에러 코드를 돌려준다.


DirectDrawSurface7.ChangeUniquenessValue

DirectDrawSurface7.ChangeUniquenessValue 메소드는, 이 표면에 대한 고유치를 수동으로 갱신한다.

object. ChangeUniquenessValue()

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

표면의 컨텐츠를 변경 하면 항상, DirectDraw 는 고유치를 자동적으로 갱신한다.

참조

DirectDrawSurface7.GetUniquenessValue


DirectDrawSurface7.DeleteAttachedSurface

DirectDrawSurface7.DeleteAttachedSurface 메소드는, Attach 한 2 개의 표면의 Attach를 해제한다.

object. DeleteAttachedSurface(ddS As DirectDrawSurface7)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
ddS
Attach를 해제하는 DirectDrawSurface 오브젝트에 대한 DirectDrawSurface7 오브젝트. 이 파라미터가 Nothing 의 경우, Attach 된 모든 표면의 Attach가 해제된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_CANNOTDETACHSURFACE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST
DDERR_SURFACENOTATTACHED

주의

DirectDrawSurface7.AddAttachedSurface 메소드는 아니고, DirectDraw 에 의해 형성되는 암묵적인 Attach는 해제할 수 없다. 플립핑 체인으로부터 표면의 Attach를 해제 하면, 체인중외의 표면을 변경할 가능성이 있다. 플립핑 체인으로부터프런트 버퍼의 Attach를 해제하는 경우, 체인중의 다음의 표면이 프런트 버퍼가 되어, 그 다음의 표면이백 버퍼가 된다. 체인으로부터 백 버퍼의 Attach를 해제하는 경우, 다음의 표면이 백 버퍼가 된다. 체인으로부터 평면 표면의 Attach를 해제하는 경우, 그 체인이 단지 짧아진다. 플립핑 체인에 2 개 표면이 있는 것만으로, 그러한 Attach를 해제하는 경우, 그 체인은 파기되어, 양표면은 원의 목적지에 돌아온다.

참조

DirectDrawSurface7.Flip


DirectDrawSurface7.DrawBox

DirectDrawSurface7.DrawBox 메소드는, 표면상에 직사각형을 드로잉(Drawing) 한다.

object. DrawBox( _
    x1 As Long, _
    y1 As Long, _
    x2 As Long, _
    y2 As Long)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
x1, y1, x2, y2
드로잉(Drawing) 하는 직사각형의 좌상과 우하의 위치.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

디폴트의 선스타일은 실선, 전부 칠해 스타일은 투명하게 설정되어 있다. 이러한 스타일은, 각각 DirectDrawSurface7.SetDrawStyle 와 DirectDrawSurface7.SetFillStyle 를 사용해 변경할 수 있다.


DirectDrawSurface7.DrawCircle

DirectDrawSurface7.DrawCircle 메소드는, 표면상에 엔을 드로잉(Drawing) 한다.

object. DrawCircle( _
    x1 As Long, _
    y1 As Long, _
    r As Long)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
x1, y1, r
드로잉(Drawing) 하는 엔의 중심점과 반경.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

디폴트의 선스타일은 실선, 전부 칠해 스타일은 투명하게 설정되어 있다. 이러한 스타일은, 각각 DirectDrawSurface7.SetDrawStyle 와 DirectDrawSurface7.SetFillStyle 를 사용해 변경할 수 있다.


DirectDrawSurface7.DrawEllipse

DirectDrawSurface7.DrawEllipse 메소드는, 표면상에 타원을 드로잉(Drawing) 한다.

object. DrawEllipse(x1 As Long, _
    y1 As Long, _
    x2 As Long, _
    y2 As Long)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
x1, y1, x2, y2
드로잉(Drawing) 하는 타원의 경계 직사각형의 좌상과 우상의 모퉁이.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

디폴트의 선스타일은 실선, 전부 칠해 스타일은 투명하게 설정되어 있다. 이러한 스타일은, 각각 DirectDrawSurface7.SetDrawStyle 와 DirectDrawSurface7.SetFillStyle 를 사용해 변경할 수 있다.


DirectDrawSurface7.DrawLine

DirectDrawSurface7.DrawLine 메소드는, 표면상에 선을 그린다.

object. DrawLine( _
    x1 As Long, _
    y1 As Long, _
    x2 As Long, _
    y2 As Long)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
x1, y1, x2, y2
선의 종점.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

디폴트의 선스타일은 실선으로 설정되어 있지만,DirectDrawSurface7.SetDrawStyle 를 사용해 변경할 수 있다.


DirectDrawSurface7.DrawRoundedBox

DirectDrawSurface7.DrawRoundedBox 메소드는, 표면상에 각환직사각형을 드로잉(Drawing) 한다.

object. DrawRoundedBox( _
    x1 As Long, _
    y1 As Long, _
    x2 As Long, _
    y2 As Long, _
    rw As Long, _
    rh As Long)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
x1, y1, x2, y2
직사각형의 좌상과 우하의 위치.
rw
각환직사각형의 드로잉(Drawing)에 사용되는 타원의 폭.
rh
각환직사각형의 드로잉(Drawing)에 사용되는 타원의 높이.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

디폴트의 선스타일은 실선, 전부 칠해 스타일은 투명하게 설정되어 있다. 이러한 스타일은, 각각 DirectDrawSurface7.SetDrawStyle 와 DirectDrawSurface7.SetFillStyle 를 사용해 변경할 수 있다.


DirectDrawSurface7.DrawText

DirectDrawSurface7.DrawText 메소드는, 표면상에 텍스트를 표시한다.

object. DrawText( _
    x As Long, _
    y As Long, _
    text As String, _
    b As Boolean)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
x, y
텍스트를 표시하는 표면 위에의 장소.
text
표시하는 텍스트.
b
현재의 커서 위치에 텍스트를 표시할지 어떨지를 지정하는 불리언 값. 「주의」를 참조할것.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

DirectDrawSurface7.DrawText 에의 마지막 호출의 끝나에 텍스트를 추가하려면 , x 및 y 좌표로서 0,0 을 건네주어,b 를 TRUE 로 설정한다. b 를 FALSE 로 설정해 이 메소드를 호출하면, 지정한 x 및 y 좌표에 텍스트가 표시된다.


DirectDrawSurface7.Flip

DirectDrawSurface7.Flip 메소드는, DDSCAPS_BACKBUFFER 표면과 관련지을 수 있었던 표면 메모리를, 프런트 버퍼 표면과 관련짓는다.

object. Flip( _
    ddS As DirectDrawSurface7, _
    flags As CONST_DDFLIPFLAGS)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
ddS
플립핑 체인내의 임의의 표면에 대한 DirectDrawSurface7 오브젝트. 이 파라미터의 디폴트는 Nothing 이며, 이 경우, DirectDraw 는 서로 Attach 되고 있는 순으로 버퍼로부터 순환한다. 이 파라미터가 Nothing 가 아닌 경우, DirectDraw 는 플립핑 체인의 다음의 표면 대신에 지정한 표면에 플립 한다. 지정한 표면이 플립핑 체인의 멤버가 아닌 경우, 메소드는 실패한다.
flags
플립 옵션을 지정하는 CONST_DDFLIPFLAGS 열거의 1 개 또는 복수의 정수.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOFLIPHW
DDERR_NOTFLIPPABLE
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

주의

이 메소드를 호출할 수가 있는 것은, DDSCAPS_FLIP 및 DDSCAPS_FRONTBUFFER 능력이 있는 표면 뿐이다. 이 메소드를 호출하기 이전에프런트 버퍼와 관련지을 수 있었던 디스플레이 메모리는,백 버퍼와 관련지을 수 있다.

ddS 파라미터는, 백 버퍼가 프런트 버퍼가 되어야 할 버퍼는 아니라고 하는 보기 드문 경우에 사용된다. 보통, 이 파라미터는 Nothing 이다.

DirectDrawSurface7.Flip 메소드는, 항상 수직선 소거와 동기 한다. 표면이 비디오 포트에 할당할 수 있고 있으면(자), 이 메소드는 표시되는 오버레이 표면과 비디오 포트의 타겟 표면을 갱신한다.

상세한 것에 대하여는, 「플립핑 표면」을 참조할것.

참조

DirectDrawSurface7.GetFlipStatus


DirectDrawSurface7.GetAttachedSurface

DirectDrawSurface7.GetAttachedSurface 메소드는, 지정한 능력을 가지는 Attach 된 표면을 취득한다.

object. GetAttachedSurface( _
    caps As DDSCAPS2) As DirectDrawSurface7

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
caps
표면의 하드웨어 능력을 포함한 DDSCAPS2 형.

반환값

성공하면,DirectDrawSurface7 오브젝트를 돌려준다. 취득하는 표면은,caps 파라미터의 기술에 적합하는 것이다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND
DDERR_SURFACELOST

주의

Attach는, 복수의 DirectDrawSurface 오브젝트를 복합형에 접속하기 위해서 사용된다. 복합형은, Z 버퍼와 함께 3D 페이지 플립핑을 지원 하기 위해서 필요한 형태이다. 요구하는 능력에 적합하는 Attach 된 표면이 1 개 이상 있는 경우, 이 메소드는 실패한다. 이 경우, 어플리케이션은 Attach 된 표면을 취득하기 위해서,DirectDrawSurface7.GetAttachedSurfaceEnum 메소드를 사용해야 한다.

이 메소드의 성공에 의해 취득한 오브젝트는,DirectDrawSurface7 오브젝트 변수에 할당하지 않으면 안 된다. 이하에 예를 나타낸다.

Dim DDrawSurface as DirectDrawSurface7
Set DDrawSurface = object. GetAttachedSurface()


DirectDrawSurface7.GetAttachedSurfaceEnum

DirectDrawSurface7.GetAttachedSurfaceEnum 메소드는, Attach 된 표면의 정보를 저장 하는 DirectDrawEnumSurfaces 오브젝트를 돌려준다.

object. GetAttachedSurfaceEnum() As DirectDrawEnumSurfaces

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectDrawEnumSurfaces 열거 인터페이스를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

주의

Attach 된 표면의 수를 취득하려면 DirectDrawEnumSurfaces.GetCount , Attach 된 표면의 기술을 취득하려면 DirectDrawEnumSurfaces.GetItem 를 호출한다.

이 메소드의 성공에 의해 취득한 오브젝트는,DirectDrawEnumSurfaces 오브젝트 변수에 할당하지 않으면 안 된다. 이하에 예를 나타낸다.

Dim SurfaceEnum as DirectDrawEnumSurfaces
Set SurfaceEnum = object. GetAttachedSurfacesEnum()


DirectDrawSurface7.GetBltStatus

DirectDrawSurface7.GetBltStatus 메소드는, 블리트 스테이터스를 취득한다.

object. GetBltStatus(flags As CONST_DDGBSFLAGS) As Long

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
flags
CONST_DDGBSFLAGS 열거의 정수의 1 개.

반환값

성공하면,flags 파라미터로 지정된 정수에 응해, FALSE 의 경우는 제로, TRUE 의 경우는 제로 이외의 값을 돌려준다.

에러 코드

실패하면 에러가 발생해, 표면이 플립핑 프로세스를 끝내지 않은 경우는 Err.Number 에 DDERR_WASSTILLDRAWING 가 설정되어 그 이외의 경우는 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DD_OK
DDERR_UNSUPPORTED


DirectDrawSurface7.GetCaps

DirectDrawSurface7.GetCaps 메소드는, 표면의 능력을 취득한다. 이러한 능력은, 디스플레이 디바이스의 능력에 관련하고 있을 필요는 없다.

object. GetCaps(caps As DDSCAPS2)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
caps
표면의 하드웨어 능력을 저장 하는 DDSCAPS2 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


DirectDrawSurface7.GetClipper

DirectDrawSurface7.GetClipper 메소드는, 표면에 관련지을 수 있었던 DirectDrawClipper 오브젝트를 취득한다.

object. GetClipper() As DirectDrawClipper

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 표면에 관련지을 수 있었던 DirectDrawClipper 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCLIPPERATTACHED

참조

DirectDrawSurface7.SetClipper

주의

메소드의 성공에 의해 취득한 오브젝트는,DirectDrawClipper 오브젝트 변수에 할당할 수 없으면 안 된다. 이하에 예를 나타낸다.

Dim Clipper as DirectDrawClipper
Set Clipper = object. GetClipper()


DirectDrawSurface7.GetColorKey

DirectDrawSurface7.GetColorKey 메소드는, DirectDrawSurface 오브젝트에 대한컬러 키값을 취득한다.

object. GetColorKey(flags As Long, val As DDCOLORKEY)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
flags
요구되는컬러 키 . 이하의 어느 쪽인가에 된다.
DDCKEY_DESTBLT
블리트 처리에 대한목적지 컬러 키로서 사용되는 컬러 키나색공간(color space) .
DDCKEY_DESTOVERLAY
오버레이 처리에 대한 목적지 컬러 키로서 사용되는 컬러 키나 색공간(color space).
DDCKEY_SRCBLT
블리트 처리에 대한전송원컬러 키로서 사용되는 컬러 키나 색공간(color space).
DDCKEY_SRCOVERLAY
오버레이 처리에 대한 전송원컬러 키로서 사용되는 컬러 키나 색공간(color space).
val
DirectDrawSurface 오브젝트의 지정된컬러 키에 대한 현재의 값을 저장 하는 DDCOLORKEY 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOLORKEY
DDERR_NOCOLORKEYHW
DDERR_SURFACELOST
DDERR_UNSUPPORTED

참조

DirectDrawSurface7.SetColorKey


DirectDrawSurface7.GetDC

DirectDrawSurface7.GetDC 메소드는, 표면에 대한 디바이스 콘텍스트의 GDI 호환 핸들을 생성 한다.

object. GetDC() As Long

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 디바이스 콘텍스트의 핸들을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_DCALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

주의

이 메소드는, 표면을 잠그는 DirectDrawSurface7.Lock 메소드의 내부 버젼을 사용한다. DirectDrawSurface7.ReleaseDC 메소드가 불려 갈 때까지, 표면은 락 된채로 있다.

ReleaseDC 는,GetDC 를 호출한 같은 thread로부터 호출하지 않으면 안 된다.

참조

DirectDrawSurface7.Lock


DirectDrawSurface7.GetDirectDraw

DirectDrawSurface7.GetDirectDraw 메소드는, 표면을 생성 하기 위해서 사용된 DirectDraw 오브젝트를 취득한다.

object. GetDirectDraw() As DirectDraw7

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectDraw7 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

메소드의 성공에 의해 취득한 오브젝트는,DirectDraw7 오브젝트 변수에 할당하지 않으면 안 된다. 이하에 예를 나타낸다.

Dim DDrawObject as DirectDraw7
Set DDrawObject = object. GetDDInterface()


DirectDrawSurface7.GetDirectDrawColorControl

DirectDrawSurface7.GetDirectDrawColorControl 메소드는, 표면으로 사용되는 DirectDrawColorControl 오브젝트를 돌려준다.

object. GetDirectDrawColorControl() As DirectDrawColorControl

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectDrawColorControl 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


DirectDrawSurface7.GetDirectDrawGammaControl

DirectDrawSurface7.GetDirectDrawGammaControl 메소드는, 표면으로 사용되는 DirectDrawGammaControl 오브젝트를 돌려준다.

object. GetDirectDrawGammaControl() As DirectDrawGammaControl

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectDrawGammaControl 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


DirectDrawSurface7.GetDrawStyle

DirectDrawSurface7.GetDrawStyle 메소드는,DirectDrawSurface7.SetDrawStyle 에 의해 설정된 스타일을 돌려준다.

object. GetDrawStyle() As Long

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.

반환값

DirectDrawSurface7.SetDrawStyle 에 의해 설정된 스타일을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

디폴트의 선스타일은 실선이다.


DirectDrawSurface7.GetDrawWidth

DirectDrawSurface7.GetDrawWidth 메소드는,DirectDrawSurface7.SetDrawWidth 에 의해 설정된 폭을 돌려준다.

object. GetDrawWidth() As Long

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.

반환값

DirectDrawSurface7.SetDrawWidth 에 의해 설정된 폭을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

디폴트의 선폭은 1 이다.


DirectDrawSurface7.GetFillColor

DirectDrawSurface7.GetFillColor 메소드는,DirectDrawSurface7.SetFillColor 에 의해 설정된 전부 칠해 컬러를 돌려준다.

object. GetFillColor() As Long

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectDrawSurface7.SetFillColor 에 의해 설정된 전부 칠해 컬러의 값을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

디폴트의 전부 칠해 컬러는 흑이다.


DirectDrawSurface7.GetFillStyle

DirectDrawSurface7.GetFillStyle 메소드는,DirectDrawSurface7.SetFillStyle 에 의해 설정된 전부 칠해 스타일을 돌려준다.

object. GetFillStyle() As Long

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectDrawSurface7.SetFillStyle 에 의해 설정된 전부 칠해 스타일을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

디폴트의 전부 칠해 스타일은 투명하다.


DirectDrawSurface7.GetFlipStatus

DirectDrawSurface7.GetFlipStatus 메소드는, 표면이 플립핑 프로세스를 끝냈는지 어떠했는지를 나타낸다.

object. GetFlipStatus(flags As CONST_DDGFSFLAGS) As Long

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
flags
CONST_DDGFSFLAGS 열거의 정수의 1 개.

반환값

성공하면,flags 파라미터로 지정된 정수에 응해, FALSE 의 경우는 제로를, TRUE 의 경우는 제로 이외의 값을 돌려준다.

에러 코드

실패하면 에러가 발생해, 표면이 플립핑 프로세스를 끝내지 않은 경우는 Err.Number 에 DDERR_WASSTILLDRAWING 가 설정되어 그 이외의 경우는 다음의 몇개의 값으로 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DD_OK
DDERR_UNSUPPORTED

참조

DirectDrawSurface7.Flip


DirectDrawSurface7.GetFontBackColor

DirectDrawSurface7.GetFontBackColor 메소드는, 폰트의 배경색을 돌려준다.

object. GetFontBackColor() As Long

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 폰트의 배경색을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectDrawSurface7.SetFontBackColor


DirectDrawSurface7.GetFontTransparency

DirectDrawSurface7.GetFontTransparency 메소드는,DirectDrawSurface7.SetFontTransparency 에 의해 설정된 폰트의 투과성을 돌려준다.

object. GetFontTransparency() As Boolean

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.

반환값

폰트가 투과형으로 설정되어 있는 경우는 제로 이외의 값을, 투과형으로 설정되어 있지 않은 경우는 제로를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectDrawSurface7.GetForeColor

DirectDrawSurface7.GetForeColor 메소드는,DirectDrawSurface7.SetForeColor 에 의해 설정된 전경색을 돌려준다.

object. GetForeColor() As Long

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectDrawSurface7.SetForeColor 에 의해 설정된 전경색을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectDrawSurface7.GetLockedArray

DirectDrawSurface7.GetLockedArray 메소드는,DirectDrawSurface7.Lock 메소드의 호출에 의해 락 된 픽셀의 배열을 돌려준다.

object. GetLockedArray( _
    array() As Byte)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
array()
락 된 픽셀의 배열 (바이트).

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

이 메소드는, 경험을 쌓은 유저를 위한 메소드이다. 이 메소드는,DirectDrawSurface7.Lock 를 호출하고 나서 DirectDrawSurface7.Unlock 를 호출할 때까지 만 사용할 수 있다. 디스플레이 카드에 따라서는, 피치가 표면의 폭과 일치하지 않는 경우가 있으므로, 메모리에의 쓰기가 배열을 넘지 않게 주의한다.


DirectDrawSurface7.GetLockedPixel

DirectDrawSurface7.GetLockedPixel 메소드는,DirectDrawSurface7.SetLockedPixel 에 의해 설정된 픽셀을 돌려준다.

object. GetLockedPixel( _
    x As Long, _
    y As Long) As Long

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
x,y
락 된 픽셀의 좌표.

반환값

성공하면, 락 된 픽셀의 컬러를 돌려준다. 이 값은, 픽셀 포맷과 같은 포맷이 된다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectDrawSurface7.GetLOD

DirectDrawSurface7.GetLOD 메소드는, 관리되는 밉맵 표면에 현재 설정되어 있는 최대 상세 레벨을 취득한다. 이 메소드는, 관리하의 텍스쳐 에 대해서만 성공한다 ( 「주의」참조).

object. GetLOD() As Long

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 밉맵 체인의 최대 상세 레벨을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDPARAMS
DDERR_INVALIDOBJECT

주의

어플리케이션은, 관리하의 텍스쳐 (DDSCAPS2_TEXTUREMANAGE 플래그로 생성 된 텍스쳐) 에 대해서만 이 메소드를 호출할 수가 있다. 비관리하의 텍스쳐에 대해서 이 메소드를 호출하면, 메소드가 실패해,DDERR_INVALIDOBJECT 에러가 발생한다.

이 메소드는, 이 체인내에서 로컬 비디오 메모리에 로드할 수 있는 최대 상세 밉맵을 Direct3D 텍스쳐 매니저에 통지한다. 예를 들어, 5 레벨의 밉맵 체인으로, 반환값이 2 의 경우, 텍스쳐 매니저는 소정의 시간에 밉맵 레벨 2 에서 4 만을 로컬 비디오 메모리에 로드한다. 같이 체인내의 최대 상세 밉맵의 사이즈가 256×256 으로, 반환값이 2 의 경우, 비디오 메모리에 존재하는 최대 밉맵의 사이즈는 64×64 가 된다.

참조

DirectDrawSurface7.SetLOD ,밉맵에 의한 텍스쳐 필터링,자동 텍스쳐 관리,텍스쳐


DirectDrawSurface7.GetOverlayPosition

표시 상태의 액티브 오버레이 표면 (DDSCAPS_OVERLAY 플래그가 설정되어 있다)이 주어지면(자),DirectDrawSurface7.GetOverlayPosition 메소드는 표면의 디스플레이 좌표를 돌려준다.

object. GetOverlayPosition(x As Long, y As Long)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
x,y
x 좌표와 y 좌표의 주소.

반환값

성공하면, 액티브 오버레이 표면의 디스플레이 좌표를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPOSITION
DDERR_NOOVERLAYDEST
DDERR_NOTAOVERLAYSURFACE
DDERR_OVERLAYNOTVISIBLE
DDERR_SURFACELOST

참조

DirectDrawSurface7.SetOverlayPosition ,DirectDrawSurface7.UpdateOverlay


DirectDrawSurface7.GetOverlayZOrdersEnum

DirectDrawSurface7::GetOverlayZOrdersEnum 메소드는, 지정한 목적지의오버레이 표면의 열거에 사용되는 DirectDrawEnumSurfaces 오브젝트를 돌려준다. 오버레이는, 프런트로부터 가방, 또는 가방으로부터 프런트의 순서로 열거된다.

object. GetOverlayZOrdersEnum( _
    flags As CONST_DDENUMOVERLAYZFLAGS) _
    As DirectDrawEnumSurfaces

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
flags
열거 옵션을 지정하는 CONST_DDENUMOVERLAYZFLAGS 열거의 정수의 1 개.

반환값

성공하면, 오버레이 표면의 z 오더 정보를 조회할 수 있는 DirectDrawEnumSurfaces 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

참조

DirectDrawSurface7.UpdateOverlayZOrder


DirectDrawSurface7.GetPalette

DirectDrawSurface7.GetPalette 메소드는, 이 메소드에 관련지을 수 있었던 DirectDrawPalette 오브젝트를 취득한다.

object. GetPalette() As DirectDrawPalette

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectDrawPalette 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_NOPALETTEATTACHED
DDERR_SURFACELOST
DDERR_UNSUPPORTED

주의

이 메소드의 성공에 의해 취득한 오브젝트는,DirectDrawPalette 오브젝트 변수에 할당하지 않으면 안 된다. 이하에 예를 나타낸다.

Dim DDPalette as DirectDrawPalette
Set DDPalette = object. GetPalette()

참조

DirectDrawSurface7.SetPalette


DirectDrawSurface7.GetPixelFormat

DirectDrawSurface7.GetPixelFormat 메소드는, 표면의 컬러 포맷과 픽셀 포맷을 취득한다.

object. GetPixelFormat(pf As DDPIXELFORMAT)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
pf
표면의 현재의 픽셀 포맷과색공간(color space) 포맷의 상세 정보를 저장 하는 DDPIXELFORMAT 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE


DirectDrawSurface7.GetPriority

DirectDrawSurface7.GetPriority 메소드는, 이 텍스쳐의 텍스쳐 관리 우선 순위를 취득한다. 이 메소드는, 관리하의 텍스쳐 에 대해서만 성공한다 ( 「주의」참조).

object. GetPriority() As Long

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 텍스쳐 관리 우선 순위를 돌려준다.

에러 코드

실패하면 에러가 발생해, 파라미터가 무효의 경우, 또는 Direct3D 에 의해 텍스쳐가 관리되어 있지 않은 경우는,Err.Number 에 DDERR_INVALIDOBJECT 가 설정된다.

주의

관리하의 텍스쳐를 메모리로부터 삭제할 경우에, 이 우선 순위가 사용된다. 우선 순위의 낮은 텍스쳐는, 우선 순위의 높은 텍스쳐보다 먼저 삭제된다. 2 개의 텍스쳐의 우선 순위가 동일한 경우, 최근 사용한 텍스쳐를 메모리에 남겨, 낡은 (분)편을 삭제한다.

어플리케이션은, 관리하의 텍스쳐 (DDSCAPS2_TEXTUREMANAGE 플래그로 생성 된 텍스쳐) 에 대해서만 우선 순위를 설정 및 취득할 수 있다. 비관리화의 텍스쳐에 대해서 이 메소드를 호출하면 실패해,DDERR_INVALIDOBJECT 를 돌려준다.

참조

DirectDrawSurface7.SetPriority ,자동 텍스쳐 관리


DirectDrawSurface7.GetSurfaceDesc

DirectDrawSurface7.GetSurfaceDesc 메소드는, 현재 상태에 있어서의 표면 기술을 취득한다.

object. GetSurfaceDesc(surface As DDSURFACEDESC2)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
surface
이 표면의 현재의 기술을 저장 하는 DDSURFACEDESC2 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS


DirectDrawSurface7.GetUniquenessValue

DirectDrawSurface7.GetUniquenessValue 메소드는, 이 표면의 현재의 고유치를 취득한다.

object. GetUniquenessValue() As Long

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 표면의 현재의 고유치를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

정의되는 고유치만이, 표면이 DirectDraw 의 컨트롤 이상으로 변경되기 쉬운 일을 나타내는 0 이 된다. 다른 고유치는, 캐쉬되기 전의 고유치와 다른 경우에만 중요해진다. 현재의 값이 캐쉬되는 값과 다른 경우, 다음에 표면의 컨텐츠가 변경된다.

참조

DirectDrawSurface7.ChangeUniquenessValue


DirectDrawSurface7.IsLost

DirectDrawSurface7.IsLost 메소드는, DirectDrawSurface 오브젝트에 관련지을 수 있었던 표면 메모리가 릴리즈 되었는지 어떠했는지를 결정한다.

object. IsLost() As Long

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 표면이 릴리즈되어 있지 않은 경우는 제로 (FALSE), 릴리즈 되고 있는 경우는 제로 이외의 값을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

주의

이 메소드를 사용해, 표면 메모리를 재할인 맞히고 할 필요가 있을지 어떨지를 확인할 수 있다. 재할인 맞히고는,DirectDrawSurface7.Restore 메소드에 의해 실시한다. DirectDrawSurface 오브젝트가 표면 메모리를 소실 하면, 대부분의 메소드는 DDERR_SURFACELOST 를 돌려주어 다른 액션을 실행하지 않는다.

디스플레이 카드의 모드가 변경될 때, 또는 어플리케이션이 디스플레이 카드에의 배타 액세스를 받아, 디스플레이 카드에 현재 할당할 수 있고 있는 표면 메모리를 모두 릴리즈 할 경우에, 표면은 그러한 메모리를 소실할 수 있다.

참조

DirectDrawSurface7.Restore ,표면의 소실과 restore


DirectDrawSurface7.Lock

DirectDrawSurface7.Lock 메소드는, 표면 메모리를 취득한다.

object. Lock( _
    r As RECT, _
    desc As DDSURFACEDESC2, _
    flags As CONST_DDLOCKFLAGS, _
    hnd As Long)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
r
락 되는 표면의 영역을 나타내는 직사각형의 좌상과 우하의 위치를 정의하는 RECT 형. 이 파라미터가 하늘의 RECT 의 경우, 표면 전체가 락 된다.
desc
표면에 관한 상세 정보를 저장 하는 DDSURFACEDESC2 형.
flags
락의 타입을 기술하는 CONST_DDLOCKFLAGS 열거의 정수의 1 개.
hnd
사용되지 않기 때문에, 0 으로 설정한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_WASSTILLDRAWING

주의

이 메소드의 사용에 대해서는, 「표면 메모리에의 직접 액세스」를 참조할것.

표면 메모리를 취득한 후, 대응하는 DirectDrawSurface7.Unlock 메소드가 불려 갈 때까지 표면에 액세스 할 수 있다. 표면의 락이 해제되면(자), 표면 메모리는 무효가 된다.

표면의 락 된 영역으로부터 블리트 하기 위해서, DirectDraw 블리트 함수를 호출해서는 안 된다. 이 함수를 호출했을 경우, 블리트는 DDERR_SURFACEBUSY 또는 DDERR_LOCKEDSURFACES 의 어느 쪽인지를 돌려준다. 게다가 GDI 블리트 함수는, 락 된 비디오 메모리 표면으로 사용되면(자), 아무것도 돌려주지 않고 실패한다.

이 메소드는,DirectDrawSurface7.Unlock 메소드를 호출할 때까지, DirectDraw 로 Win16Mutex (Win16Lock 라고도 불린다)를 보관 유지하는 경우가 있다. GUI 디버거는, Win16Mutex 가 보관 유지되고 있는 동안은 처리할 수 없다.

참조

DirectDrawSurface7.Unlock ,DirectDrawSurface7.GetDC ,DirectDrawSurface7.ReleaseDC


DirectDrawSurface7.ReleaseDC

DirectDrawSurface7.ReleaseDC 메소드는,DirectDrawSurface7.GetDC 메소드에 의해 취득된 디바이스 콘텍스트의 핸들을 릴리즈 한다.

object. ReleaseDC(hdc As Long)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
hdc
DirectDrawSurface7.GetDC 에 의해 취득된 디바이스 콘텍스트의 핸들.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST
DDERR_UNSUPPORTED

주의

이 메소드는,DirectDrawSurface7.GetDC 메소드가 불려 갔을 때에, 미리 락 된 표면의 락도 해제한다.

ReleaseDC 는,GetDC 를 호출한 같은 thread로부터 호출하지 않으면 안 된다.

참조

DirectDrawSurface7.GetDC


DirectDrawSurface7.Restore

DirectDrawSurface7.Restore 메소드는, 소실된 표면을 restore 한다. 이것은, DirectDrawSurface 오브젝트에 관련지을 수 있었던 표면 메모리를 릴리즈 할 경우에 생긴다.

object. Restore()

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_GENERIC
DDERR_IMPLICITLYCREATED
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_OUTOFMEMORY
DDERR_UNSUPPORTED
DDERR_WRONGMODE

주의

이 메소드는, 표면에 대해서 할당할 수 있었던 메모리를 restore 하지만, 표면이 소실되기 전에 존재한 가능성이 있는 비트 맵은 재로드하지 않는다. DDSCAPS2_PERSISTENTCONTENT 플래그로 생성 된 표면의 컨텐츠만이 자동적으로 restore 된다. 이 플래그가 없는 표면이 소실되면(자), 메모리를 restore 하고 나서 보관 유지한 그래픽스를 완전하게 복구 이루어 없으면 안 된다.

디스플레이 카드의 모드를 변경하기 위해(때문에), 또는 어플리케이션이 디스플레이 카드에의 배타 액세스를 받아, 카드로 할당할 수 있었던 현재의 표면 메모리의 모든 것을 릴리즈 하기 위해서, 표면을 소실할 수 있다. DirectDrawSurface 오브젝트가 그 표면 메모리를 소실 하면, 대부분의 메소드는 DDERR_SURFACELOST 를 돌려주어, 다른 모든 기능을 실행할 수 없게 된다. DirectDrawSurface7.Restore 메소드는, 표면 메모리를 재할인 맞히고 해, DirectDrawSurface 오브젝트에 다시 Attach 한다.

이 메소드에의 단일의 호출은, DirectDrawSurface 오브젝트의 은근히 관련지을 수 있었던 표면 (백 버퍼등)을 restore 한다. 은근히 생성 된 표면을 restore 하려고 하면(자), 에러가 생긴다. DirectDrawSurface7.Restore 는,DirectDrawSurface7.AddAttachedSurface 메소드를 사용해 생성 한 명시적인 Attach에는 작용하지 않는다. 즉, 이러한 각각의 표면은, 개별적으로 restore 하지 않으면 안 된다.

참조

DirectDrawSurface7.IsLost


DirectDrawSurface7.SetClipper

DirectDrawSurface7.SetClipper 메소드는, 표면에 클립퍼 오브젝트를 Attach 하거나 표면으로부터 클립퍼 오브젝트를 삭제한다.

object. SetClipper(val As DirectDrawClipper)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
val
DirectDrawSurface 오브젝트에 Attach 되는 DirectDrawClipper 오브젝트에 대한 DirectDrawClipper 오브젝트. 이 파라미터가 Nothing 의 경우, 현재의 DirectDrawClipper 오브젝트는 Attach가 해제된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_NOCLIPPERATTACHED

주의

val 파라미터로서 Nothing 를 건네주는 경우, 표면으로부터 클립퍼가 삭제된다. 이 메소드는,프라이머리 표면에 오버레이 되는지, 블리트 되는 표면에 의해 주로 사용된다. 다만, 이 메소드는, 어느 표면상에서도 사용할 수 있다. DirectDrawClipper 오브젝트가 Attach 되어,클립 리스트를 거기에 관련지을 수 있으면(자),DirectDrawClipper 오브젝트는 부모의 DirectDrawSurface 오브젝트를 포함한 DirectDrawSurface7.Blt 처리로 사용된다. 이 메소드는, DirectDrawSurface 오브젝트의 현재의 DirectDrawClipper 오브젝트에 있어서의 Attach도 해제할 수 있다.

참조

DirectDrawSurface7.GetClipper


DirectDrawSurface7.SetColorKey

DirectDrawSurface7.SetColorKey 메소드는, 하드웨어가 표면 기준 마다 컬러 키를 지원 하는 경우, DirectDrawSurface 오브젝트에 대한컬러 키값을 설정한다.

object. SetColorKey( _
    flags As CONST_DDCKEYFLAGS, _
    val As DDCOLORKEY)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
flags
요구되는 컬러 키의 타입을 지정하는 CONST_DDCKEYFLAGS 열거의 정수의 1 개.
val
DirectDrawSurface 오브젝트에 대해서 새로운 컬러 키값을 포함한 DDCOLORKEY 형. 미리 설정한 컬러 키를 삭제하려면 , 이 값을 Nothing 로 한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_NOOVERLAYHW
DDERR_NOTAOVERLAYSURFACE
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

주의

투과형 블리트와 오버레이에 대해서, 목적지 표면의 목적지의 색과 전송원표면의 전송원의 색을 설정하지 않으면 안 된다.

참조

DirectDrawSurface7.GetColorKey


DirectDrawSurface7.SetDrawStyle

DirectDrawSurface7.SetDrawStyle 는, 선스타일을 설정한다.

object. SetDrawStyle(drawStyle As Long)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
drawStyle
다음의 선스타일의 어느 쪽인가에 설정한다.
설정 | 설명
0 | (디폴트) 실선
1 | 파선
2 | 점선
3 | 일점 파선
4 | 2점파선
5 | 투명
6 | 실선

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectDrawSurface7.GetDrawStyle


DirectDrawSurface7.SetDrawWidth

DirectDrawSurface7.SetDrawWidth 메소드는, 드로잉(Drawing) 메소드로 사용되는 선의 폭을 설정한다.

object. setDrawWidth(drawWidth As Long)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
drawWidth
드로잉(Drawing) 메소드로 사용되는 선의 폭. 디폴트값은 1 이다. 1 에서 32,767 의 임의의 값을 지정할 수 있다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectDrawSurface7.GetDrawWidth


DirectDrawSurface7.SetFillColor

DirectDrawSurface7.SetFillColor 메소드는, 드로잉(Drawing) 메소드로 사용되는 전부 칠해 컬러를 지정한다.

object. SetFillColor(color As Long)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
color
드로잉(Drawing) 메소드로 전부 칠해 컬러로서 사용되는 RGB 값. 디폴트값은 흑 (&H00000000)이다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectDrawSurface7.GetFillColor


DirectDrawSurface7.SetFillStyle

DirectDrawSurface7.SetFillStyle 메소드는, 드로잉(Drawing) 메소드로 사용되는 전부 칠해 스타일을 지정한다.

object. SetFillStyle(fillStyle As Long)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
fillStyle
다음의 전부 칠해 스타일의 어느 쪽인가에 설정한다.
설정 | 설명
0 | (디폴트) 균일
1 | 투명
2 | 가로 줄무늬
3 | 세로의 줄무늬
4 | 우상 꾸중 줄무늬
5 | 오른쪽 밑 줄무늬
6 | 체크 무늬
7 | 기울기 체크 무늬

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectDrawSurface7.GetFillStyle


DirectDrawSurface7.SetFont

DirectDrawSurface7.SetFont 메소드는,DirectDrawSurface7.DrawText 로 사용되는 폰트를 지정한다.

object. SetFont(font As IFont)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
font
IFont 클래스에서 지정된 폰트.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectDrawSurface7.SetFontBackColor

DirectDrawSurface7.SetFontBackColor 메소드는, 폰트의 배경색을 설정한다.

object. SetFontBackColor(color As Long)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
color
폰트의 배경색.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectDrawSurface7.SetFontTransparency

DirectDrawSurface7.SetFontTransparency 메소드는,DirectDrawSurface7.DrawText 가 투과형의 경우, 그 폰트를 사용할지 어떨지를 지정한다.

object. SetFontTransparency(b As Boolean)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
b
폰트가 투과형의 경우는 D_TRUE, 폰트가 투과형이 아닌 경우는 D_FALSE 로 설정한다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectDrawSurface7.SetForeColor

DirectDrawSurface7.SetForeColor 메소드는, 드로잉(Drawing) 메소드로 사용되는 전경색을 설정한다.

object. SetForeColor(color As Long)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
color
전경색으로서 설정하는 RGB 값.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectDrawSurface7.GetForeColor


DirectDrawSurface7.SetLockedPixel

DirectDrawSurface7.SetLockedPixel 메소드는, 지정한 컬러에 단일 픽셀을 설정해, 락 된 표면을 갱신한다.

object. SetLockedPixel( _
    x As Long, _
    y As Long, _
    col As Long)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
x,y
설정하는 픽셀의 좌표.
col
설정하는 픽셀의 RGB 값.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

사전에 DirectDrawSurface7.Lock 를 호출해 표면을 잠그어 두지 않으면 안 된다.

참조

DirectDrawSurface7.GetLockedPixel


DirectDrawSurface7.SetLOD

DirectDrawSurface7.SetLOD 메소드는, 관리되는 밉맵 표면의 최대 상세 레벨을 설정한다. 이 메소드는, 관리하의 표면 에 대해서만 성공한다 ( 「주의」참조).

object. SetLOD(lod As Long)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
lod
메소드가 성공했을 경우에 밉맵 체인으로 설정되는 상세 레벨의 최대치.

반환값

성공하면, DD_OK 를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

어플리케이션은, 관리하의 텍스쳐 (DDSCAPS2_TEXTUREMANAGE 플래그로 생성 된 텍스쳐) 에 대해서만 이 메소드를 호출할 수가 있다. 비관리화의 메소드에 대해서 이 메소드를 호출하면 실패해,DDERR_INVALIDOBJECT 를 돌려준다.

이 메소드는, 이 체인내에서 로컬 비디오 메모리에 로드할 수 있는 최대 상세 밉맵을 Direct3D 텍스쳐 매니저에 통지한다. 예를 들어, 5 레벨의 밉맵 체인으로,lod 가 2 로 설정되어 있는 경우, 텍스쳐 매니저는 소정의 시간에 밉맵 레벨 2 에서 4 만을 로컬 비디오 메모리에 로드한다. 같이 체인내의 최대 상세 밉맵의 사이즈가 256×256 으로, 최대 레벨이 2 로 설정되어 있는 경우, 비디오 메모리에 존재하는 최대 밉맵의 사이즈는 64×64 가 된다.

참조

DirectDrawSurface7.GetLOD ,밉맵에 의한 텍스쳐 필터링,자동 텍스쳐 관리,텍스쳐


DirectDrawSurface7.SetOverlayPosition

DirectDrawSurface7.SetOverlayPosition 메소드는,오버레이 표면의 디스플레이 좌표를 변경한다.

object. SetOverlayPosition(x As Long, y As Long)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
x,y
새로운 x 디스플레이 좌표와 y 디스플레이 좌표.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPOSITION
DDERR_NOOVERLAYDEST
DDERR_NOTAOVERLAYSURFACE
DDERR_OVERLAYNOTVISIBLE
DDERR_SURFACELOST
DDERR_UNSUPPORTED

참조

DirectDrawSurface7.GetOverlayPosition


DirectDrawSurface7.SetPalette

DirectDrawSurface7.SetPalette 메소드는, 표면에 팔레트 오브젝트를 Attach 한다 (또는, 표면으로부터 그 Attach를 해제한다). 표면은, 모든 연속하는 처리에 이 팔레트를 사용한다. 팔레트의 변경은, 리프레쉬 타이밍에 관계없이 즉석에서 행해진다.

object. SetPalette(ddp As DirectDrawPalette)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
ddp
이 표면과 함께 사용되는 팔레트 오브젝트에 대한 DirectDrawPalette 오브젝트. 이 파라미터가 Nothing 의 경우, 현재의 팔레트는 Attach가 해제된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDSURFACETYPE
DDERR_NOEXCLUSIVEMODE
DDERR_NOPALETTEATTACHED
DDERR_NOPALETTEHW
DDERR_NOT8BITCOLOR
DDERR_SURFACELOST
DDERR_UNSUPPORTED

주의

ddp 파라미터로서 Nothing 를 건네주는 경우, 팔레트는 표면으로부터 삭제된다.

참조

DirectDrawSurface7.GetPalette ,DirectDraw7.CreatePalette


DirectDrawSurface7.SetPriority

DirectDrawSurface7.SetPriority 메소드는, 이 텍스쳐에 텍스쳐 관리 우선 순위를 할당한다. 이 메소드는, 관리하의 텍스쳐 에 대해서만 성공한다 ( 「주의」참조).

object. SetPriority(Priority As Long)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
Priority
텍스쳐의 새로운 텍스쳐 관리 우선 순위를 나타내는 값.

에러 코드

실패하면 에러가 발생해, 파라미터가 무효의 경우, 또는 텍스쳐가 Direct3D 에 의해 관리되어 있지 않은 경우는,Err.Number 에DDERR_INVALIDOBJECT 가 설정된다.

주의

관리하의 텍스쳐를 메모리로부터 삭제할 경우에, 이 우선 순위가 사용된다. 우선 순위의 낮은 텍스쳐는, 우선 순위의 높은 텍스쳐보다 먼저 삭제된다. 2 개의 텍스쳐의 우선 순위가 동일한 경우, 최근 사용한 텍스쳐를 메모리에 남겨, 낡은 (분)편을 삭제한다.

어플리케이션은, 관리하의 텍스쳐 (DDSCAPS2_TEXTUREMANAGE 플래그로 생성 된 텍스쳐) 에 대해서만 우선 순위를 설정 및 취득할 수 있다. 비관리화의 텍스쳐에 대해서 이 메소드를 호출하면 실패해,DDERR_INVALIDOBJECT 를 돌려준다.

참조

DirectDrawSurface7.GetPriority ,자동 텍스쳐 관리


DirectDrawSurface7.Unlock

DirectDrawSurface7.Unlock 메소드는, DirectDraw 에 직접 표면 처리가 완료한 것을 통지한다.

object. Unlock(r As RECT)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
r
DirectDrawSurface7.Lock 메소드에의 호출해에 대응하는 호출로, 표면을 잠그기 위해서(때문에) 사용한 RECT 형. DirectDrawSurface7.Lock 메소드에의 호출해에 대응하는 호출의 r 파라미터에 Nothing 를 건네주는 것으로, 표면 전체를 잠그었을 경우에 한정해, 이 파라미터는 Nothing 가 된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOTLOCKED
DDERR_SURFACELOST

주의

다른 목적지 직사각형이 있는 같은 표면에 대한 DirectDrawSurface7.Lock 의 호출은 여러 차례 가능하기 때문에,r 파라미터는 DirectDrawSurface7.Lock 및 DirectDrawSurface7.Unlock 메소드의 호출해에 링크한다.

참조

DirectDrawSurface7.Lock


DirectDrawSurface7.UpdateOverlay

DirectDrawSurface7.UpdateOverlay 메소드는,오버레이 표면의 비주얼 속성을 재배치하거나 변경한다. 이러한 표면에는, DDSCAPS_OVERLAY 플래그를 설정할 필요가 있다.

object. UpdateOverlay(RECT As RECT, _
    ddS As DirectDrawSurface7, _
    rectD As RECT, _
    flags As CONST_DDOVERFLAGS)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
RECT
오버레이로서 사용되는 전송원표면의 영역의 x, y, 폭, 및 높이를 정의하는 RECT 형. 이 파라미터는, 오버레이를 은폐 하는 경우나, 오버레이 표면 전체를 사용해, 한편 오버레이 표면이 디바이스 드라이버로부터의 경계 및 사이즈아라이먼트 제한에도 따르는 것을 나타내는 경우에, 하늘의 RECT 로 한다.
ddS
오버레이를 하는 표면에 대한 DirectDrawSurface7 오브젝트.
rectD
오버레이를 이동하는 목적지 표면의 영역의 x, y, 폭, 및 높이를 정의하는 RECT 형. 이 파라미터는, 오버레이를 은폐 하는 경우에 하늘의 RECT 가 된다.
flags
CONST_DDOVERFLAGS 열거의 1 개 또는 복수의 정수.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_DEVICEDOESNTOWNSURFACE
DDERR_GENERIC
DDERR_HEIGHTALIGN
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_INVALIDSURFACETYPE
DDERR_NOSTRETCHHW
DDERR_NOTAOVERLAYSURFACE
DDERR_OUTOFCAPS
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_XALIGN


DirectDrawSurface7.UpdateOverlayFx

DirectDrawSurface7.UpdateOverlayFx 메소드는, 특수한 오버레이 이펙트를 사용해,오버레이 표면에 대한 비주얼 속성을 재배치하거나 변경한다. 이러한 표면에는, DDSCAPS_OVERLAY 플래그를 설정할 필요가 있다.

object. UpdateOverlayFx(RECT As RECT, _
    ddS As DirectDrawSurface7, _
    rectD As RECT, _
    flags As CONST_DDOVERFLAGS, _
    ddoverfx As DDOVERLAYFX)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
RECT
오버레이로서 사용되는 전송원표면의 영역의 x, y, 폭, 및 높이를 정의하는 RECT 형. 이 파라미터는, 오버레이를 은폐 하는 경우나, 오버레이 표면 전체를 사용해, 한편 오버레이 표면이 디바이스 드라이버로부터의 경계 및 사이즈아라이먼트 제한에도 따르는 것을 나타내는 경우에, 하늘의 RECT 로 한다.
ddS
오버레이를 하는 표면에 대한 DirectDrawSurface7 오브젝트.
rectD
오버레이를 이동하는 목적지 표면의 영역의 x, y, 폭, 및 높이를 정의하는 RECT 형. 이 파라미터는, 오버레이를 은폐 하는 경우에 하늘의 RECT 가 된다.
flags
CONST_DDOVERFLAGS 열거의 1 개 또는 복수의 정수. ddoverfx 파라미터에 의해 설정된 이펙트를 적용하려면 , DDOVER_DDFX 플래그를 지정해야 한다.
ddoverfx
오버레이 표면에 적용되는 추가의 이펙트를 기술하는 DDOVERLAYFX 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_DEVICEDOESNTOWNSURFACE
DDERR_GENERIC
DDERR_HEIGHTALIGN
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_INVALIDSURFACETYPE
DDERR_NOSTRETCHHW
DDERR_NOTAOVERLAYSURFACE
DDERR_OUTOFCAPS
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_XALIGN


DirectDrawSurface7.UpdateOverlayZOrder

DirectDrawSurface7.UpdateOverlayZOrder 메소드는, 오버레이의 z 오더를 설정한다.

object. UpdateOverlayZOrder( _
    flags As CONST_DDOVERZFLAGS, _
    ddS As DirectDrawSurface7)

파라미터

object
DirectDrawSurface7 오브젝트를 나타내는오브젝트식.
flags
오버레이의 위치를 기술하는 CONST_DDOVERZFLAGS 열거의 정수의 1 개.
ddS
오버레이 체인의 상대 위치로서 사용되는 DirectDraw 표면에 대한 DirectDrawSurface7 오브젝트. 이 파라미터는, DDOVERZ_INSERTINBACKOF 및 DDOVERZ_INSERTINFRONTOF 만의 위해(때문에) 필요하게 된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTAOVERLAYSURFACE


IFont

IFont 클래스는,DirectDrawSurface7.SetFont 메소드가,DirectDrawSurface7.DrawText 메소드로 사용되는 폰트를 지정하기 위해서 사용한다.

이 클래스와 관련하는 메소드에 대해서는, Visual Basic 의 Font 클래스의 항을 참조할것.


DirectDraw 글로벌 메소드

DirectX7 클래스는, DirectX for Visual Basic 어플리케이션의 기본 클래스이다. 이 클래스에는, 모든 DirectX 컴퍼넌트로 사용되는 메소드가 있다. DirectDraw 에 관련하는 메소드는 이하대로이다.

  • DirectX7.DirectDrawCreate
  • DirectX7.GetDDEnum


형

이 항에서는, DirectDraw 와 함께 사용되는 이하의 형태에 대해 설명한다.

  • DDBLTFX
  • DDCAPS
  • DDCOLORCONTROL
  • DDCOLORKEY
  • DDGAMMARAMP
  • DDOVERLAYFX
  • DDPIXELFORMAT
  • DDSCAPS2
  • DDSURFACEDESC2
  • PALETTEENTRY
  • RECT


DDBLTFX

DDBLTFX 형은, 라스터 처리, 이펙트, 및 오버라이드(override) 정보를 DirectDrawSurface7.Blt 메소드에 건네준다.

Type DDBLTFX
    ddckDestColorKey_high As Long
    ddckDestColorKey_low As Long
    ddckSrcColorKey_high As Long
    ddckSrcColorKey_low As Long
    lAlphaDestConst As Long
    lAlphaDestConstBitDepth As Long
    lAlphaEdgeBlend As Long
    lAlphaEdgeBlendBitDepth As Long
    lAlphaSrcConst As Long
    lAlphaSrcConstBitDepth As Long
    lDDFX As CONST_DDBLTFXFLAGS
    lDDROP As Long
    lFill As Long
    lReserved As Long
    lROP As Long
    lRotationAngle As Long
    lZBufferBaseDest As Long
    lZBufferHigh As Long
    lZBufferLow As Long
    lZBufferOpCode As Long
    lZDestConst As Long
    lZDestConstBitDepth As Long
    lZSrcConst As Long
    lZSrcConstBitDepth As Long
End Type

멤버

ddckDestColorKey_high
목적지 컬러 키로서 사용되는 색범위의 상한치.
ddckDestColorKey_low
목적지 컬러 키로서 사용되는 색범위의 하한값.
ddckSrcColorKey_high
전송원컬러 키로서 사용되는 색범위의 상한치.
ddckSrcColorKey_low
전송원컬러 키로서 사용되는 색범위의 하한값.
lAlphaDestConst
목적지알파 채널로서 사용하는 정수.
lAlphaDestConstBitDepth
목적지 알파 정수의 비트 깊이.
lAlphaEdgeBlend
엣지 블렌드로 사용하는알파 정수 .
lAlphaEdgeBlendBitDepth
알파 엣지 블렌드에 있어서의 비트 깊이 정수.
lAlphaSrcConst
전송원알파 채널로서 사용하는 정수.
lAlphaSrcConstBitDepth
전송원알파 정수의 비트 깊이.
lDDFX
FX 처리의 타입. CONST_DDBLTFXFLAGS 열거의 정수의 1 개.
lDDROP
DirectDraw 라스터 처리.
lFill
DDBLT_COLORFILL 를 지정할 경우에, 표면을 전부 칠하기 위해서(때문에) 사용하는 색. 이 값은, 목적지 표면의 픽셀 포맷에 해당하는 픽셀이 아니면 안 된다. 팔레트화 표면이면팔레트 인덱스,16 비트 RGB 표면이면 16 비트 픽셀값이 된다.
lReserved
장래적인 사용을 위해서(때문에) 확보되고 있다.
lROP
Win32 라스터 처리. 지원 되는 라스터 처리의 리스트를 취득하려면 ,DirectDraw7.GetCaps 메소드를 호출한다.
lRotationAngle
블리트에 있어서의 회전 각도.
lZBufferBaseDest
Z 버퍼의 목적지 기저값.
lZBufferHigh
Z 버퍼의 최고한도계.
lZBufferLow
Z 버퍼의 최저한계.
lZBufferOpCode
Z 버퍼 비교.
lZDestConst
목적지 Z 버퍼로서 사용하는 정수.
lZDestConstBitDepth
목적지 z 정수의 비트 깊이.
lZSrcConst
전송원 Z 버퍼로서 사용하는 정수.
lZSrcConstBitDepth
전송원 z 정수의 비트 깊이.


DDCAPS

DDCAPS 형은, DirectDraw 오브젝트가 분명히 하는 하드웨어의 능력을 나타낸다. 이 형태에는, 생성 할 수 있는 DirectDrawSurface 오브젝트의 종류를 기술하는 이 문맥의 DDSCAPS2 형을 포함한다. 그러나, 이러한 능력이 기술하는 표면의 모든 것을 동시에 생성 하는 것은 불가능한 경우가 있다. 이 형태는,DirectDraw7.GetCaps 메소드로 사용된다.

Type DDCAPS
    ddsCaps As DDSCAPS2
    lAlignBoundaryDest As Long
    lAlignBoundarySrc As Long
    lAlignSizeDest As Long
    lAlignSizeSrc As Long
    lAlignStrideAlign As Long
    lAlphaBltConstBitDepths As Long
    lAlphaBltPixelBitDepths As Long
    lAlphaBltSurfaceBitDepths As Long
    lAlphaOverlayConstBitDepths As Long
    lAlphaOverlayPixelBitDepths As Long
    lAlphaOverlaySurfaceBitDepths As Long
    lCaps As CONST_DDCAPS1FLAGS
    lCaps2 As CONST_DDCAPS2FLAGS
    lCKeyCaps As CONST_DDCKEYCAPSFLAGS
    lCurrVideoPorts As Long
    lCurrVisibleOverlays As Long
    lFXCaps As CONST_DDFXCAPSFLAGS
    lMaxHwCodecStretch As Long
    lMaxLiveVideoStretch As Long
    lMaxOverlayStretch As Long
    lMaxVideoPorts As Long
    lMaxVisibleOverlays As Long
    lMinHwCodecStretch As Long
    lMinLiveVideoStretch As Long
    lMinOverlayStretch As Long
    lNLVBCaps As CONST_DDCAPS1FLAGS
    lNLVBCaps2 As CONST_DDCAPS2FLAGS
    lNLVBCKeyCaps As CONST_DDCKEYCAPSFLAGS
    lNLVBFXCaps As CONST_DDFXCAPSFLAGS
    lNLVBRops (0 To 7) As Long
    lNumFourCCCodes As Long
    lPalCaps As CONST_DDPCAPSFLAGS
    lReserved1 As Long
    lReserved2 As Long
    lReserved3 As Long
    lReservedCaps As Long
    lRops (0 To 7) As Long
    lSSBCaps As CONST_DDCAPS1FLAGS
    lSSBCKeyCaps As CONST_DDCKEYCAPSFLAGS
    lSSBFXCaps As CONST_DDFXCAPSFLAGS
    lSSBRops (0 To 7) As Long
    lSVBCaps As CONST_DDCAPS1FLAGS
    lSVBCaps2 As CONST_DDCAPS2FLAGS
    lSVBCKeyCaps As CONST_DDCKEYCAPSFLAGS
    lSVBFXCaps As CONST_DDFXCAPSFLAGS
    lSVBRops (0 To 7) As Long
    lSVCaps As CONST_DDSTEREOCAPSFLAGS
    lVidMemFree As Long
    lVidMemTotal As Long
    lVSBCaps As CONST_DDCAPS1FLAGS
    lVSBCKeyCaps As CONST_DDCKEYCAPSFLAGS
    lVSBFXCaps As CONST_DDFXCAPSFLAGS
    lVSRops (0 To 7) As Long
    lZBufferBitDepths As Long
End Type

멤버

ddsCaps
추가의 능력을 기술하는 DDSCAPS2 형.
lAlignBoundaryDest
픽셀 단위의 오버레이 표면에 대한 목적지 직사각형의 아라이먼트.
lAlignBoundarySrc
픽셀 단위의 오버레이 표면에 대한 전송원직사각형의 아라이먼트.
lAlignSizeDest
픽셀 단위의 오버레이 표면에 대한 목적지 직사각형의 사이즈아라이먼트. 오버레이 목적지 직사각형은, 이 값의 배수의 픽셀폭이 아니면 안 된다.
lAlignSizeSrc
픽셀 단위의 오버레이 표면에 대한 전송원직사각형의 사이즈아라이먼트. 오버레이 전송원직사각형은, 이 값의 배수의 픽셀폭이 아니면 안 된다.
lAlignStrideAlign
보폭 아라이먼트.
lAlphaBltConstBitDepths
DDBD_2, DDBD_4, 또는 DDBD_8 (2 비트, 4 비트, 또는 8 비트/픽셀을 나타낸다).
lAlphaBltPixelBitDepths
DDBD_1, DDBD_2, DDBD_4, 또는 DDBD_8 (1 비트, 2 비트, 4 비트, 또는 8 비트/픽셀을 나타낸다).
lAlphaBltSurfaceBitDepths
DDBD_1, DDBD_2, DDBD_4, 또는 DDBD_8 (1 비트, 2 비트, 4 비트, 또는 8 비트/픽셀을 나타낸다).
lAlphaOverlayConstBitDepths
DDBD_2, DDBD_4, 또는 DDBD_8 (2 비트, 4 비트, 또는 8 비트/픽셀을 나타낸다).
lAlphaOverlayPixelBitDepths
DDBD_1, DDBD_2, DDBD_4, 또는 DDBD_8 (1 비트, 2 비트, 4 비트, 또는 8 비트/픽셀을 나타낸다).
lAlphaOverlaySurfaceBitDepths
DDBD_1, DDBD_2, DDBD_4, 또는 DDBD_8 (1 비트, 2 비트, 4 비트, 또는 8 비트/픽셀을 나타낸다).
lCaps
드라이버 고유의 능력을 기술하는 CONST_DDCAPS1FLAGS 열거의 정수.
lCaps2
추가의 드라이버 고유 능력을 기술하는 CONST_DDCAPS2FLAGS 열거의 정수.
lCKeyCaps
컬러 키 능력을 기술하는 CONST_DDCKEYCAPSFLAGS 열거의 정수.
lCurrVideoPorts
라이브 비디오 포트의 현재의 수.
lCurrVisibleOverlays
표시되는 오버레이 또는 오버레이 스프라이트의 현재의 수.
lFXCaps
드라이버 고유의신축(스트레치)와 이펙트의 능력을 기술하는 CONST_DDFXCAPSFLAGS 열거의 정수.
lMinHwCodecStretch 및 lMaxHwCodecStretch
폐지되었다. 사용하지 않는다.
lMinLiveVideoStretch 및 lMaxLiveVideoStretch
폐지되었다. 사용하지 않는다.
lMinOverlayStretch 및 lMaxOverlayStretch
1000 배 되는 최소 및 최대 오버레이 신축(스트레치) 계수. 예를 들어, 1.3 = 1300.
lMaxVideoPorts
라이브 비디오 포트의 최대수.
lMaxVisibleOverlays
표시되는 오버레이 또는 오버레이 스프라이트의 최대수.
lNLVBCaps
비로컬 비디오 메모리로부터 로컬 비디오 메모리에의 블리트에 대한 드라이버 고유의 능력을 기술하는 CONST_DDCAPS1FLAGS 열거의 정수. 유효 플래그는,lCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
lNLVBCaps2
비로컬 비디오 메모리로부터 로컬 비디오 메모리에의 블리트에 대한 추가의 드라이버 고유 능력을 기술하는 CONST_DDCAPS2FLAGS 열거의 정수. 유효 플래그는,lCap2 멤버로 사용되는 블리트 관련 플래그와 동일하다.
lNLVBCKeyCaps
비로컬 비디오 메모리로부터 로컬 비디오 메모리에의 블리트에 대한 드라이버의 컬러 키 능력을 기술하는 CONST_DDCKEYCAPSFLAGS 열거의 정수. 유효 플래그는,lCKeyCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
lNLVBFXCaps
비로컬 비디오 메모리로부터 로컬 비디오 메모리에의 블리트에 대한 드라이버의 FX 능력을 기술하는 CONST_DDFXCAPSFLAGS 열거의 정수. 유효 플래그는,lFXCap 멤버로 사용되는 블리트 관련 플래그와 동일하다.
lNLVBRops[0 에서 7]
비로컬 비디오 메모리로부터 로컬 비디오 메모리에의 블리트에 대해서 지원 되는 라스터 처리.
lNumFourCCCodes
FOURCC 코드의 수.
lPalCaps
팔레트 능력을 기술하는 CONST_DDPCAPSFLAGS 열거의 정수.
lReserved1,lReserved2,lReserved3, 및 lReservedCaps
장래적인 사용을 위해서(때문에) 확보되고 있다.
lRops[0 에서 7]
지원 되는 라스터 처리.
lSSBCaps
시스템 메모리로부터 시스템 메모리에의 블리트에 대한 드라이버 고유의 능력을 기술하는 CONST_DDCAPS1FLAGS 열거의 정수. 유효 플래그는,lCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
lSSBCKeyCaps
시스템 메모리로부터 시스템 메모리에의 블리트에 대한 드라이버의 컬러 키 능력을 기술하는 CONST_DDCKEYCAPSFLAGS 열거의 정수. 유효 플래그는,lCKeyCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
lSSBFXCaps
시스템 메모리로부터 시스템 메모리에의 블리트에 대한 드라이버의 FX 능력을 기술하는 CONST_DDFXCAPSFLAGS 열거의 정수. 유효 플래그는,lFXCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
lSSBRops[0 에서 7]
시스템 메모리로부터 시스템 메모리에의 블리트에 대해서 지원 되는 라스터 처리.
lSVBCaps
시스템 메모리로부터 디스플레이 메모리에의 블리트에 대한 드라이버 고유의 능력을 기술하는 CONST_DDCAPS1FLAGS 열거의 정수. 유효 플래그는,lCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
lSVBCaps2
시스템 메모리로부터 비디오 메모리에의 블리트에 대한 드라이버 고유의 능력을 기술하는 CONST_DDCAPS2FLAGS 열거의 정수. 유효 플래그는,lCaps2 멤버로 사용되는 블리트 관련 플래그와 동일하다.
lSVBCKeyCaps
시스템 메모리로부터 디스플레이 메모리에의 블리트에 대한 드라이버의 컬러 키 능력을 기술하는 CONST_DDCKEYCAPSFLAGS 열거의 정수. 유효 플래그는,lCKeyCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
lSVBFXCaps
시스템 메모리로부터 디스플레이 메모리에의 블리트에 대한 드라이버의 FX 능력을 기술하는 CONST_DDFXCAPSFLAGS 열거의 정수. 유효 플래그는,lFXCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
lSVBRops[0 에서 7]
시스템 메모리로부터 디스플레이 메모리에의 블리트에 대해서 지원 되는 라스터 처리.
lSVCaps
스테레오 비전 능력을 기술하는 CONST_DDSTEREOCAPSFLAGS 열거의 정수.
lVidMemFree
디스플레이 메모리의 빈 용량.
lVidMemTotal
디스플레이 메모리의 총용량.
lVSBCaps
디스플레이 메모리로부터 시스템 메모리에의 블리트에 대한 드라이버 고유의 능력을 기술하는 CONST_DDCAPS1FLAGS 열거의 정수. 유효 플래그는,lCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
lVSBCKeyCaps
디스플레이 메모리로부터 시스템 메모리에의 블리트에 대한 드라이버의 컬러 키 능력을 기술하는 CONST_DDCKEYCAPSFLAGS 열거의 정수. 유효 플래그는,lCKeyCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
lVSBFXCaps
디스플레이 메모리로부터 시스템 메모리에의 블리트에 대한 드라이버의 FX 능력을 기술하는 CONST_DDFXCAPSFLAGS 열거의 정수. 유효 플래그는,lFXCaps 멤버로 사용되는 블리트 관련 플래그와 동일하다.
lVSRops[0 에서 7]
디스플레이 메모리로부터 시스템 메모리에의 블리트에 대해서 지원 되는 라스터 처리.
lZBufferBitDepths
DDBD_8, DDBD_16, 또는 DDBD_24 (8 비트, 16 비트, 24 비트/픽셀을 나타낸다). 32 비트 버퍼는 지원되어 있지 않다.


DDCOLORCONTROL

DDCOLORCONTROL 형은, DirectDrawVideoPortObject 또는 프라이머리 표면에 관련지을 수 있었던 컬러 컨트롤을 정의한다.

Type DDCOLORCONTROL
    lBrightness As Long
    lColorEnable As Long
    lContrast As Long
    lFlags As CONST_DDCOLORFLAGS
    lGamma As Long
    lHue As Long
    lReserved1 As Long
    lSaturation As Long
    lSharpness As Long
End Type

멤버

lBrightness
IRE 단위 100 으로 나타낸 휘도(Luminance). 유효 범위는, 0 에서 10,000 까지. 디폴트값은 750 (7.5 IRE).
lColorEnable
색을 사용할지 어떨지를 나타내는 플래그. 이 멤버가 제로의 경우, 색은 사용하지 않는다. 이 멤버가 1 의 경우, 색을 사용한다. 디폴트값은 1.
lContrast
IRE 단위로 나타낸 휘도(Luminance)에 있어서의 상하의 값의 상대적 차위. 유효 범위는, 0 에서 20,000 까지. 디폴트값은 10,000 (100 IRE). 콘트라스트의 위에의값에 의해, 보다 어두운 휘도(Luminance)는 흑으로 향하는 경향이 있어, 보다 밝은 휘도(Luminance)는 흰색으로 향하는 경향이 있다. 콘트라스트아래의 값은, 모든 휘도(Luminance)를 중간의 휘도(Luminance)로 향하게 한다.
lFlags
어느 멤버가 유효한 데이터를 포함하는지를 나타내는 CONST_DDCOLORFLAGS 열거의 정수. DirectDrawColorControl.GetColorControls 메소드에 의해 돌려주어진 타입의 경우, 디바이스에 의해 지원 되는 옵션도 가리킨다.
lGamma
휘도(Luminance)에 적용되는 감마 수정량을 제어한다. 유효 범위는, 1 에서 500 감마 단위로, 디폴트값은 1.
lHue
크로미난스 성분의 위상 관계. 색상은 번으로 지정되어 유효 범위는 -180 으로부터 180 까지이다. 디폴트값은 0.
lReserved1
장래적인 사용을 위해서(때문에) 확보되고 있다.
lSaturation
IRE 단위 100 으로 나타낸 컬러 강도. 유효 범위는, 0 에서 20,000 까지. 디폴트값은 10,000 (100 IRE).
lSharpness
임의의 단위의 선명도. 유효 범위는, 0 에서 10 까지. 디폴트값은 5.


DDCOLORKEY

DDCOLORKEY 형은,전송원컬러 키,목적지 컬러 키, 또는색공간(color space)를 기술한다. 컬러 키는, 상한과 하한의 범위값이 같은 경우로 지정된다. 이 형태는,DirectDrawSurface7.GetColorKey 및 DirectDrawSurface7.SetColorKey 메소드로 사용된다.

Type COLORKEY
    high As Long
    low As Long
End Type

멤버

high
컬러 키로서 사용되는 색범위의 상한치.
low
컬러 키로서 사용되는 색범위의 하한값.


DDGAMMARAMP

DDGAMMARAMP 형은,DirectDrawGammaControl.GetGammaRamp 및 DirectDrawGammaControl.SetGammaRamp 메소드를 위한 적, 초록, 및 파랑의 램프 데이터를 포함한다.

Type DDGAMMARAMP
    blue(0 To 255) As Integer
    green(0 To 255) As Integer
    red(0 To 255) As Integer
End Type

멤버

red,green,blue
적, 초록, 및 파랑의 감마 램프.

참조

감마 컨트롤과 컬러 컨트롤


DDOVERLAYFX

DDOVERLAYFX 형은,DirectDrawSurface7.UpdateOverlay 메소드에 오버라이드(override) 정보를 건네준다.

type DDOVERLAYFX
    dckDestColorkey As DDCOLORKEY
    dckSrcColorkey As DDCOLORKEY
    lAlphaDestConst As Long
    lAlphaDestConstBitDepth As Long
    lAlphaEdgeBlend As Long
    lAlphaEdgeBlendBitDepth As Long
    lAlphaSrcConst As Long
    lAlphaSrcConstBitDepth As Long
    lDDFX As CONST_DDOVERFXFLAGS
    lFlags As Long
End Type

멤버

dckDestColorkey
목적지 컬러 키 오버라이드(override).
dckSrcColorkey
전송원컬러 키 오버라이드(override).
lAlphaDestConst
목적지의알파 채널로서 사용되는 정수.
lAlphaDestConstBitDepth
목적지의알파 정수를 지정하기 위해서 사용되는 비트 깊이.
lAlphaEdgeBlend
엣지 블렌드에 대한 알파로서 사용되는 정수.
lAlphaEdgeBlendBitDepth
알파 엣지 블렌드에 대한 정수를 지정하기 위해서 사용되는 비트 깊이.
lAlphaSrcConst
전송원의 알파 채널로서 사용하는 정수.
lAlphaSrcConstBitDepth
전송원의 알파 정수를 지정하기 위해서 사용되는 비트 깊이.
lDDFX
CONST_DDOVERFXFLAGS 열거의 정수의 1 개.
lFlags
현재 사용되어 있지 않기 때문에, 0 으로 설정한다.


DDPIXELFORMAT

DDPIXELFORMAT 형은,DirectDrawSurface7.GetPixelFormat 메소드에 대한 DirectDrawSurface 오브젝트의 픽셀 포맷을 기술한다.

Type DDPIXELFORMAT
    lAlphaBitDepth As Long
    lBBitMask As Long
    lBumpBitCount As Long
    lBumpDuBitMask As Long
    lBumpDvBitMask As Long
    lBumpLuminanceBitMask As Long
    lFlags As CONST_DDPIXELFORMATFLAGS
    lFourCC As Long
    lGBitMask As Long
    lLuminanceAlphaBitMask As Long
    lLuminanceBitCount As Long
    lLuminanceBitMask As Long
    lRBitMask As Long
    lRGBAlphaBitMask As Long
    lRGBBitCount As Long
    lRGBZBitMask As Long
    lStencilBitDepth As Long
    lStencilBitMask As Long
    lUBitMask As Long
    lVBitMask As Long
    lYBitMask As Long
    lYUVAlphaBitMask As Long
    lYUVBitCount As Long
    lYUVZBitMask As Long
    lZBitMask As Long
    lZBufferBitDepth As Long
End Type

멤버

lAlphaBitDepth
알파 전용 표면 (DDPF_ALPHA)을 위한알파 채널 비트 깊이 (1, 2, 4, 또는 8). 알파 정보를 포함한 픽셀 포맷은 색데이터 (DDPF_ALPHAPIXELS)로 인터리브 되기 (위해)때문에,lRGBAlphaBitMask 멤버의 비트를 세어 알파 성분의 비트 깊이를 취득하지 않으면 안 된다.
lBBitMask
파랑 비트의 마스크.
lBumpBitCount
범프 맵 표면의 총범프 맵 비트/픽셀.
lBumpDuBitMask
범프 맵 U 델타 비트의 마스크,
lBumpDvBitMask
범프 맵 V 델타 비트의 마스크.
lBumpLuminanceBitMask
범프 맵 픽셀의 휘도(Luminance)의 마스크.
lFlags
옵션 제어 플래그를 기술하는 CONST_DDPIXELFORMATFLAGS 열거의 정수.
lFourCC
FOURCC 코드. 상세한 것에 대하여는, 「4 문자 코드 (FOURCC)」를 참조할것.
lGBitMask
초록 비트의 마스크.
lRGBAlphaBitMask,lYUVAlphaBitMask,lLuminanceAlphaBitMask
알파 채널의 마스크.
lLuminanceBitCount
총휘도(Luminance) 비트/픽셀. 이 멤버는, 휘도(Luminance) 전용 및 휘도(Luminance) 알파 표면인 만큼 적용한다.
lLuminanceBitMask
휘도(Luminance) 비트의 마스크.
lRBitMask
빨강 비트의 마스크.
lRGBAlphaBitMask,lYUVAlphaBitMask
알파 채널의 마스크.
lRGBBitCount
RGB 비트/픽셀 (4, 8, 16, 24, 또는 32).
lRGBZBitMask,lYUVZBitMask
z 채널의 마스크.
lStencilBitDepth
스텐실 버퍼의 비트 깊이. 이 멤버는, 스텐실 정보의 Z 버퍼의 각 픽셀내에서 확보되는 비트의 수를 지정한다. (z 비트의 총수는 lZBufferBitDepth 로부터 lStencilBitDepth 를 뺀 수로 동일하다).
lStencilBitMask
각 Z 버퍼 픽셀내의 스텐실 비트의 마스크.
lUBitMask
U 비트의 마스크.
lVBitMask
V 비트의 마스크.
lYBitMask
Y 비트의 마스크.
lYUVBitCount
YUV 비트/픽셀 (4, 8, 16, 24, 또는 32).
lZBitMask
z 비트의 마스크.
lZBufferBitDepth
Z 버퍼의 비트 깊이 (8, 16, 또는 24). 32 비트 버퍼는 지원되어 있지 않다.


DDSCAPS2

DDSCAPS2 형은, DirectDrawSurface 오브젝트의 능력을 정의한다. 이 형태는,DDSURFACEDESC2 형의 일부이다.

Type DDSCAPS2
   lCaps As CONST_DDSURFACECAPSFLAGS
   lCaps2 As CONST_DDSURFACECAPS2FLAGS
   lCaps3 As Long
   lCaps4 As Long
End Type

멤버

lCaps
표면의 능력을 나타내는 CONST_DDSURFACECAPSFLAGS 열거의 1 개 또는 복수의 정수.
lCaps2
추가 표면 능력. 이 멤버는,CONST_DDSURFACECAPS2FLAGS 열거의 능력 정수를 1 개 이상 포함할 수가 있다. 또, 추가 플래그에 의해 표면 메모리의 할당 방법을 나타낼 수가 있다.
lCaps3 및 lCaps4
현시점에서는, 미사용이다.


DDSURFACEDESC2

DDSURFACEDESC2 형은, 표면의 기술을 포함한다. 이 형태는,DirectDraw7.CreateSurface 메소드에게 건네진다. 관계하는 멤버는, 표면의 각각의 타입에 의해 다르다.

Type DDSURFACEDESC2
    ddckCKDestBlt As DDCOLORKEY
    ddckCKDestOverlay As DDCOLORKEY
    ddckCKSrcBlt As DDCOLORKEY
    ddckCKSrcOverlay As DDCOLORKEY
    ddpfPixelFormat As DDPIXELFORMAT
    ddsCaps As DDSCAPS2
    lAlphaBitDepth As Long
    lBackBufferCount As Long
    lFlags As CONST_DDSURFACEDESCFLAGS
    lHeight As Long
    lLinearSize As Long
    lMipMapCount As Long
    lPitch As Long
    lRefreshRate As Long
    lTextureStage As Long
    lWidth As Long
    lZBufferBitDepth As Long
End Type

멤버

ddckCKDestBlt
블리트 처리의 목적지 컬러 키를 기술하는 DDCOLORKEY 형.
ddckCKDestOverlay
오버레이 표면에 사용하는목적지 컬러 키를 기술하는 DDCOLORKEY 형.
ddckCKSrcBlt
블리트 처리의 전송원컬러 키를 기술하는 DDCOLORKEY 형.
ddckCKSrcOverlay
오버레이 표면에 사용하는전송원컬러 키를 기술하는 DDCOLORKEY 형.
ddpfPixelFormat
표면의 픽셀 포맷을 기술하는 DDPIXELFORMAT 형.
ddsCaps
표면의 능력을 포함한 DDSCAPS2 형.
lAlphaBitDepth
알파 버퍼의 깊이.
lBackBufferCount
백 버퍼의 수.
lFlags
옵션 제어 플래그. CONST_DDSURFACEDESCFLAGS 열거의 1 개 또는 복수의 정수.
lHeight 및 lWidth
픽셀 단위로 생성 하려고 하는 표면의 넓이.
lLinearSize
현시점에서는, 미사용이다.
lMipMapCount
밉맵 레벨의 수.
lPitch
다음의 라인의 시작까지의 바이트 단위의 거리. DirectDrawSurface7.GetSurfaceDesc 메소드로 사용 하면 반환값이 된다. 기존의 메모리로부터 표면을 생성 하는 경우, 이 멤버는 입력값이 되어, 복수가 아니면 안된다.
lRefreshRate
refresh rate (디스플레이 모드를 기술하는 경우에 사용). 이 값이 0 의 경우, 어댑터 장해를 나타낸다.
lTextureStage
3D 디바이스의 멀티 텍스쳐 cascade에 있어서의 특정의 스테이지에, 텍스쳐를 바인드 하기 위해서 사용하는 스테이지 식별자. 모든 하드웨어에 필요하지 않지만, 이 멤버의 설정은 3D 가속기의 다양성에 대해서, 최적인 퍼포먼스를 준다. 명시적으로 할당할 수 있었던 텍스쳐를 요구하는 하드웨어가,Direct3DDevice7.GetCaps 메소드로 채워지는 D3DDEVICEDESC 형의 D3DDEVCAPS_SEPARATETEXTUREMEMORIES 3-D 디바이스 능력을 나타낸다.
lZBufferBitDepth
Z 버퍼의 깊이. 32 비트 Z 버퍼는 지원되어 있지 않다.

주의

DirectDrawSurface7.GetSurfaceDesc 메소드를 호출하면,lPitch 멤버가 출력값이 된다. 기존의 메모리로부터 표면을 생성 하거나 표면 특성을 갱신하고 있는 경우, 이러한 멤버는 입력값이 된다. 이 입력값은, DirectDraw 로 사용되는 호출측의 어플리케이션에 의해 할당할 수 있었던 메모리의 피치와 위치를 기술한다. DirectDraw 는, 어플리케이션이 할당한 메모리를 관리하거나 릴리즈 하려고 하지 않는다. 상세한 것에 대하여는, 「클라이언트 메모리 표면의 생성」, 및 「표면 특성의 갱신」을 참조할것.


PALETTEENTRY

PALETTEENTRY 형은, 논리색팔레트 엔트리의 색과 사용 방법을 지정한다.

Type PALETTEENTRY
    blue As Byte
    flags As Byte
    green As Byte
    red As Byte
End Type

멤버

blue
팔레트 엔트리의 파랑의 강도.
flags
팔레트 엔트리의 사용 방법을 지정한다. flags 멤버는, Nothing 또는 이하의 몇개의 값으로 설정할 수 있다.
값 | 의미
PC_EXPLICIT | 하드웨어 팔레트 인덱스를 나타내는 논리 팔레트 엔트리의 하위 워드. 이 플래그에 의해, 어플리케이션은 디스플레이 디바이스 팔레트의 컨텐츠를 표시할 수 있다.
PC_NOCOLLAPSE | 시스템 팔레트의 기존의 색에 적합하지 않고 , 미사용의 엔트리에 할당하는 색. 시스템 팔레트에 미사용의 엔트리가 없는 경우, 보통대로 적합된다. 시스템 팔레트에 할당할 수 있었던 색은, 다른 논리 팔레트의 색과 적합할 수 있다.
PC_RESERVED | 팔레트 애니메이션에 사용되는 논리 팔레트 엔트리. 색이 빈번하게 변화하므로, 이 플래그에 의해, 다른 윈도우가 그 팔레트 엔트리에 색을 적합하지 않게 한다. 미사용의 시스템 팔레트 엔트리가 사용 가능한 경우, 그 엔트리에 색을 할당할 수 있다. 그렇지 않은 경우, 그 색은 애니메이션으로 사용할 수 없다.

green
팔레트 엔트리의 초록의 강도.
red
팔레트 엔트리의 빨강의 강도.


RECT

RECT 형은, 직사각형의 좌상과 우하의 모퉁이의 좌표를 정의한다.

Type RECT
    Bottom As Long
    Left As Long
    Right As Long
    Top As Long
End Type

멤버

Bottom
직사각형의 우하각의 y 좌표.
Left
직사각형의 맨 왼쪽 위쪽의 x 좌표.
Right
직사각형의 우하각의 x 좌표.
Top
직사각형의 맨 왼쪽 위쪽의 y 좌표.


열거

DirectDraw 에서는, 열거를 사용해 정수를 그룹화 해, Visual Basic 의 스테이트먼트 완료 기능을 이용한다. DirectDraw 에서는 다음의 열거를 사용한다.

  • CONST_DDBITDEPTHFLAGS
  • CONST_DDBLTFASTFLAGS
  • CONST_DDBLTFLAGS
  • CONST_DDBLTFXFLAGS
  • CONST_DDCAPS1FLAGS
  • CONST_DDCAPS2FLAGS
  • CONST_DDCKEYCAPSFLAGS
  • CONST_DDCKEYFLAGS
  • CONST_DDCOLORFLAGS
  • CONST_DDDEVICEIDFLAGS
  • CONST_DDEDMFLAGS
  • CONST_DDENUMOVERLAYZFLAGS
  • CONST_DDENUMSURFACESFLAGS
  • CONST_DDFLIPFLAGS
  • CONST_DDFXCAPSFLAGS
  • CONST_DDGBSFLAGS
  • CONST_DDGFSFLAGS
  • CONST_DDLOCKFLAGS
  • CONST_DDOVERFLAGS
  • CONST_DDOVERFXFLAGS
  • CONST_DDOVERZFLAGS
  • CONST_DDPALFLAGS
  • CONST_DDPCAPSFLAGS
  • CONST_DDPIXELFORMATFLAGS
  • CONST_DDRAW
  • CONST_DDRAWERR
  • CONST_DDSCLFLAGS
  • CONST_DDSDMFLAGS
  • CONST_DDSGRFLAGS
  • CONST_DDSTEREOCAPSFLAGS
  • CONST_DDSURFACECAPS2FLAGS
  • CONST_DDSURFACECAPSFLAGS
  • CONST_DDSURFACEDESCFLAGS
  • CONST_DDWAITVBFLAGS


CONST_DDBITDEPTHFLAGS

CONST_DDBITDEPTHFLAGS 열거를 사용해, 비트 깊이를 지정한다.

Enum CONST_DDBITDEPTHFLAGS
    DDBD_1 = 16384
    DDBD_16 = 1024
    DDBD_2  = 8192
    DDBD_24 =  512
    DDBD_32 =  256
    DDBD_4  = 4096
    DDBD_8  = 2048
End Enum
DDBD_1 to 32
비트/픽셀


CONST_DDBLTFASTFLAGS

CONST_DDBLTFASTFLAGS 열거는,DirectDrawSurface7.BltFast 메소드의 trans 파라미터로 사용되어 전송의 타입을 정의한다.

Enum CONST_DDBLTFASTFLAGS
    DDBLTFAST_DESTCOLORKEY =  2
    DDBLTFAST_DONOTWAIT    = 32
    DDBLTFAST_NOCOLORKEY   =  0
    DDBLTFAST_SRCCOLORKEY  =  1
    DDBLTFAST_WAIT         = 16
End Enum
DDBLTFAST_DESTCOLORKEY
목적지의컬러 키를 사용하는 투과형 블리트를 지정한다.
DDBLTFAST_DONOTWAIT
블리트가 Busy의 경우 대기하지 않고, 블리트를 실시하지 않고 돌려준다.
DDBLTFAST_NOCOLORKEY
투과형이 아닌 보통의 카피 블리트를 지정한다.
DDBLTFAST_SRCCOLORKEY
전송원의컬러 키를 사용하는 투과형 블리트를 지정한다.
DDBLTFAST_WAIT
블리트가 Busy의 경우, DDERR_WASSTILLDRAWING 메세지를 돌려주지 않고 대기한다. 블리트가 셋업 되든가, 혹은 다른 에러가 발생 하면 즉석에서 돌려준다.


CONST_DDBLTFLAGS

CONST_DDBLTFLAGS 열거는,DirectDrawSurface7.Blt 및 DirectDrawSurface7.BltFx 메소드의 flag 파라미터로 사용되어 관련지을 수 있었던 DDBLTFX 형의 유효한 멤버를 정의한다. DDBLTFX 형은, 컬러 키 정보를 지정하는지, 메소드에 특수한 동작을 요구한다.

Enum CONST_DDBLTFLAGS
    DDBLT_ASYNC = 512
    DDBLT_COLORFILL = 1024
    DDBLT_DDFX = 2048
    DDBLT_DDROPS = 4096
    DDBLT_DEPTHFILL = 33554432
    DDBLT_DONOTWAIT = 134217728
    DDBLT_KEYDEST = 8192
    DDBLT_KEYDESTOVERRIDE = 16384
    DDBLT_KEYSRC = 32768
    DDBLT_KEYSRCOVERRIDE = 65536
    DDBLT_ROP = 131072
    DDBLT_ROTATIONANGLE = 262144
    DDBLT_WAIT = 16777216
End Enum
평가 플래그
DDBLT_COLORFILL
목적지 표면 위에의 목적지 직사각형을 저장 하는 RGB 색으로서 DDBLTFX 형의 lFill 멤버를 사용한다.
DDBLT_DDFX
이 블리트에 대해서 사용하는 이펙트를 지정하는,DDBLTFX 형의 lDDFX 멤버를 사용한다.
DDBLT_DDROPS
Win32 API 의 부분이 아닌 라스터 처리 (ROPS)를 지정하는,DDBLTFX 형의 lROP 멤버를 사용한다.
DDBLT_DEPTHFILL
목적지 Z 버퍼 표면 위에의 목적지 직사각형을 저장 하는 깊이값으로서DDBLTFX 형의 lFilll 멤버를 사용한다.
DDBLT_DONOTWAIT
블리트가 Busy의 경우, 블리트가 가능하게 될 때까지 대기하지 않고, 블리트를 실시하지 않고 돌려준다.
DDBLT_KEYDESTOVERRIDE
목적지 표면의컬러 키로서 DDBLTFX 형의 ddckDestColorkey_high 및 ddckDestColorkey_low 멤버를 사용한다.
DDBLT_KEYSRCOVERRIDE
전송원표면의컬러 키로서 DDBLTFX 형의 ddckSrcColorkey_high 및 ddckSrcColorkey_low 멤버를 사용한다.
DDBLT_ROP
이 블리트에 있어서의 ROP 에 대해서 DDBLTFX 형의 lROP 멤버를 사용한다. 이러한 ROP 는, Win32 API 로 정의되고 있는 것 것과 같다.
DDBLT_ROTATIONANGLE
표면의 회전각 (1/100 번단위로 지정된다)으로서 DDBLTFX 형의 lRotationAngle 멤버를 사용한다.
컬러 키 플랙
DDBLT_KEYDEST
목적지 표면에 관련지을 수 있었던컬러 키를 사용한다.
DDBLT_KEYSRC
전송원표면에 관련지을 수 있었던컬러 키를 사용한다.
동작 플래그
DDBLT_ASYNC
받는 순서로 FIFO (퍼스트 인, 퍼스트 아웃) 하드웨어로부터 비동기에게 이 블리트를 실행한다. FIFO 하드웨어의 빈영역을 이용할 수 없는 경우, 호출은 실패한다.
DDBLT_WAIT
블리트가 Busy의 경우, DDERR_WASSTILLDRAWING 반환값을 곧바로 돌려주지 않고 대기한다. 그리고, 블리트가 셋업 되는지, 다른 에러가 발생하면(자) 즉석에서 돌려준다.


CONST_DDBLTFXFLAGS

CONST_DDBLTFXFLAGS 열거는,DDBLTFX 형의 lDDFX 멤버로 사용되어 FX 처리의 타입을 지정한다.

Enum CONST_DDBLTFXFLAGS
    DDBLTFX_ARITHSTRETCHY   =   1
    DDBLTFX_MIRRORLEFTRIGHT =   2
    DDBLTFX_MIRRORUPDOWN    =   4
    DDBLTFX_NOTEARING       =   8
    DDBLTFX_ROTATE180       =  16
    DDBLTFX_ROTATE270       =  32
    DDBLTFX_ROTATE90        =  64
    DDBLTFX_ZBUFFERBASEDEST = 256
    DDBLTFX_ZBUFFERRANGE    = 128
End Enum
DDBLTFX_ARITHSTRETCHY
이 블리트에 대해서, y 축으로 따라 산술신축(스트레치)를 사용한다.
DDBLTFX_MIRRORLEFTRIGHT
y 축상에서 표면을 회전한다. 이 블리트는, 표면을 왼쪽에서 오른쪽으로 밀러화한다.
DDBLTFX_MIRRORUPDOWN
x 축상에서 표면을 회전한다. 이 블리트는, 표면을 위에서 아래로 밀러화한다.
DDBLTFX_NOTEARING
이 블리트가티어링 하지 않게 고려한다.
DDBLTFX_ROTATE180
이 블리트중에, 표면을 시계회전에 180 번 회전한다.
DDBLTFX_ROTATE270
이 블리트중에, 표면을 시계회전에 270 번 회전한다.
DDBLTFX_ROTATE90
이 블리트중에, 표면을 시계회전에 90 번 회전한다.
DDBLTFX_ZBUFFERBASEDEST
이 z 블리트중에, 목적지 z 값과 비교하기 전의 전송원 z 값의 각각에 DDBLTFX 형의 lZBufferBaseDest 멤버를 추가한다.
DDBLTFX_ZBUFFERRANGE
이 z 블리트중에, 전송원표면으로부터 카피한 비트에의 한계를 지정하는 범위값으로서 DDBLTFX 형의 lZBufferLow 및 lZBufferHigh 멤버를 사용한다.


CONST_DDCAPS1FLAGS

CONST_DDCAPS1FLAGS 열거는,DDCAPS 형의 lCaps,lNLVBCaps,lSSBCaps,lSVBCaps, 및 lVSBCaps 멤버로 사용되어 하드웨어 능력을 기술한다.

Enum CONST_DDCAPS1FLAGS
    DDCAPS_3D               =           1
    DDCAPS_ALIGNBOUNDARYDEST =          2
    DDCAPS_ALIGNBOUNDARYSRC =           8
    DDCAPS_ALIGNSIZEDEST    =           4
    DDCAPS_ALIGNSIZESRC     =          16
    DDCAPS_ALIGNSTRIDE      =          32
    DDCAPS_ALPHA            =     8388608
    DDCAPS_BANKSWITCHED     =   134217728
    DDCAPS_BLT              =          64
    DDCAPS_BLTCOLORFILL     =    67108864
    DDCAPS_BLTDEPTHFILL     =   268435456
    DDCAPS_BLTFOURCC        =         256
    DDCAPS_BLTQUEUE         =         128
    DDCAPS_BLTSTRETCH       =         512
    DDCAPS_CANBLTSYSMEM     = -2147483648
    DDCAPS_CANCLIP          =   536870912
    DDCAPS_CANCLIPSTRETCHED =  1073741824
    DDCAPS_COLORKEY         =     4194304
    DDCAPS_COLORKEYHWASSIST =    16777216
    DDCAPS_GDI              =        1024
    DDCAPS_NOHARDWARE       =    33554432
    DDCAPS_OVERLAY          =        2048
    DDCAPS_OVERLAYCANTCLIP  =        4096
    DDCAPS_OVERLAYFOURCC    =        8192
    DDCAPS_OVERLAYSTRETCH   =       16384
    DDCAPS_PALETTE          =       32768
    DDCAPS_PALETTEVSYNC     =       65536
    DDCAPS_READSCANLINE     =      131072
    DDCAPS_VBI              =      524288
    DDCAPS_ZBLTS            =     1048576
    DDCAPS_ZOVERLAYS        =     2097152
End Enum
DDCAPS_3D
디스플레이 하드웨어에 3D 가속기가 있는 것을 나타낸다.
DDCAPS_ALIGNBOUNDARYDEST
DirectDraw 가, 표면의 lAlignBoundaryDest 경계에 연속하는 x 축이 있는 오버레이 목적지 직사각형만을 지원 하는 것을 나타낸다.
DDCAPS_ALIGNBOUNDARYSRC
DirectDraw 가, 표면의 lAlignBoundarySrc 경계에 연속하는 x 축이 있는 오버레이 전송원직사각형만을 지원 하는 것을 나타낸다.
DDCAPS_ALIGNSIZEDEST
DirectDraw 가, 픽셀 단위의 x 축의 사이즈가 lAlignSizeDest 의 배수인 오버레이 목적지 직사각형만을 지원 하는 것을 나타낸다.
DDCAPS_ALIGNSIZESRC
DirectDraw 가, 픽셀 단위의 x 축의 사이즈가 lAlignSizeSrc 의 배수인 오버레이 전송원직사각형만을 지원 하는 것을 나타낸다.
DDCAPS_ALIGNSTRIDE
DirectDraw 가,lAlignStrideAlign 값에 동일한보폭 경계가 있는 디스플레이 메모리 표면을 생성 하는 것을 나타낸다.
DDCAPS_ALPHA
디스플레이 하드웨어가, 알파 전용 표면을 지원 하는 것을 나타낸다 ( 「알파 채널」참조).
DDCAPS_BANKSWITCHED
디스플레이 하드웨어가 반크스잇치이며, 디스플레이 메모리에의 랜덤 억세스가 매우 늦을 가능성이 있는 것을 나타낸다.
DDCAPS_BLT
디스플레이 하드웨어가, 블리트 처리를 실행할 수 있는 것을 나타낸다.
DDCAPS_BLTCOLORFILL
디스플레이 하드웨어가, 블리트로 색의 칠해가 할 수 있는 것을 나타낸다.
DDCAPS_BLTDEPTHFILL
디스플레이 하드웨어가, 블리트로 Z 버퍼 깊이 보충을 할 수 있는 것을 나타낸다.
DDCAPS_BLTFOURCC
디스플레이 하드웨어가, 블리트 처리중으로색공간(color space)의 변경을 할 수 있는 것을 나타낸다.
DDCAPS_BLTQUEUE
디스플레이 하드웨어가, 비동기 블리트 처리를 실행할 수 있는 것을 나타낸다.
DDCAPS_BLTSTRETCH
디스플레이 하드웨어가, 블리트 처리중에신축(스트레치) 할 수 있는 것을 나타낸다.
DDCAPS_CANBLTSYSMEM
디스플레이 하드웨어가, 시스템 메모리에 또는 시스템 메모리로부터 블리트 할 수 있는 것을 나타낸다.
DDCAPS_CANCLIP
디스플레이 하드웨어가, 블리트로 클리핑 할 수 있는 것을 나타낸다.
DDCAPS_CANCLIPSTRETCHED
디스플레이 하드웨어가, 신축(스트레치) 블리트중에 클리핑 할 수 있는 것을 나타낸다.
DDCAPS_COLORKEY
오버레이 또는 블리트 처리의 어느 쪽인지로,컬러 키의 몇개의 형식을 지원 한다. 보다 특정인컬러 키 능력 정보는,lCKeyCaps 멤버에 있다.
DDCAPS_COLORKEYHWASSIST
컬러 키가, 부분적으로 하드웨어로 지원 되고 있는 것을 나타낸다. 이 때문에, 다른 리소스 (CPU 또는 비디오 메모리)를 사용할 가능성이 있다. 이 비트가 설정되어 있지 않은 경우, 하드웨어의 풀 지원이 실시된다.
DDCAPS_GDI
디스플레이 하드웨어가, GDI 로 공유되는 것을 나타낸다.
DDCAPS_NOHARDWARE
하드웨어 지원이 없는 것을 나타낸다.
DDCAPS_OVERLAY
디스플레이 하드웨어가, 오버레이를 지원 하는 것을 나타낸다.
DDCAPS_OVERLAYCANTCLIP
디스플레이 하드웨어가 오버레이를 지원 하지만, 클립 할 수 없는 것을 나타낸다.
DDCAPS_OVERLAYFOURCC
오버레이 하드웨어가, 오버레이 처리중으로색공간(color space)의 변경할 수 있는 것을 나타낸다.
DDCAPS_OVERLAYSTRETCH
오버레이 하드웨어가,신축(스트레치) 할 수 있는 것을 나타낸다. lMinOverlayStretch 및 lMaxOverlayStretch 멤버에 유효한 데이터가 있다.
DDCAPS_PALETTE
DirectDraw 가,프라이머리 표면 뿐만이 아니라 다른 표면에도,DirectDrawPalette 오브젝트를 생성 해, 지원 할 수 있는 것을 나타낸다.
DDCAPS_PALETTEVSYNC
DirectDraw 가, 수직 리프레쉬와 동기 하는 팔레트를 갱신할 수 있는 것을 나타낸다.
DDCAPS_READSCANLINE
디스플레이 하드웨어가, 현재의 주사선을 돌려줄 수 있는 것을 나타낸다.
DDCAPS_VBI
디스플레이 하드웨어가, 수직귀선소거 세치기를 생성할 수 있는 것을 나타낸다.
DDCAPS_ZBLTS
블리트 처리와 함께 Z 버퍼의 사용을 지원 한다.
DDCAPS_ZOVERLAYS
겹이든지를 제어하는 오버레이의 z 값으로서DirectDrawSurface7.UpdateOverlayZOrder 메소드의 사용을 지원 한다.


CONST_DDCAPS2FLAGS

CONST_DDCAPS2FLAGS 열거는,DDCAPS 형의 lCaps2,lNLVBCaps2,lSVBCaps2 멤버로 사용되어 추가의 드라이버 고유 능력을 기술한다.

Enum CONST_DDCAPS2FLAGS
    DDCAPS2_AUTOFLIPOVERLAY    =     8
    DDCAPS2_CANBOBHARDWARE     = 16384
    DDCAPS2_CANBOBINTERLEAVED  =    16
    DDCAPS2_CANBOBNONINTERLEAVED =  32
    DDCAPS2_CANCALIBRATEGAMMA  = 1048576
    DDCAPS2_CANDROPZ16BIT      =   256
    DDCAPS2_CANFLIPODDEVEN     =  8192
    DDCAPS2_CANMANAGETEXTURE   = 8388608
    DDCAPS2_CANRENDERWINDOWED  = 524288
    DDCAPS2_CERTIFIED          =     1
    DDCAPS2_COLORCONTROLOVERLAY =   64
    DDCAPS2_COLORCONTROLPRIMARY =  128
    DDCAPS2_COPYFOURCC         = 32768
    DDCAPS2_FLIPINTERVAL       = 2097152
    DDCAPS2_FLIPNOVSYNC        = 4194304
    DDCAPS2_NO2DDURING3DSCENE  =     2
    DDCAPS2_NONLOCALVIDMEM     =   512
    DDCAPS2_NONLOCALVIDMEMCAPS =  1024
    DDCAPS2_NOPAGELOCKREQUIRED =  2048
    DDCAPS2_PRIMARYGAMMA       = 131072
    DDCAPS2_STEREO             = 33554432
    DDCAPS2_VIDEOPORT          =     4
    DDCAPS2_WIDESURFACES       =  4096
End Enum
DDCAPS2_AUTOFLIPOVERLAY
오버레이는, 비디오 포트 VSYNC 가 발생할 때마다, 플립 체인의 다음의 표면에 자동적으로 플립 된다. 또, CPU 의 오버헤드없이, 비디오 포트 및 오버레이로부터 비디오를 더블 버퍼 할 수 있다. 이 옵션은, 표면이 비디오 포트로부터 데이터를 받을 때인 만큼 유효하다. 비디오 포트 데이터가 인터 레이스 또는 인터리브되어 있지 않은 경우는, VSYNC 마다 플립 한다. 데이터가 메모리로 인터리브 되고 있는 경우, 1 개(살) 간격의 VSYNC 마다 플립 한다.
DDCAPS2_CANBOBHARDWARE
오버레이 하드웨어는, 인터 레이스 비디오 스트림의 각각의 필드를 개별적으로 표시할 수 있다.
DDCAPS2_CANBOBINTERLEAVED
오버레이 하드웨어는, 특별한 하드웨어 지원이 없으면, 보통 발생할 가능성이 있는 이상을 일으키는 일 없이, 메모리로 인터리브 하고 있는 동안은, 인터 레이스 비디오 스트림의 각각의 필드를 개별적으로 표시할 수 있다. 이 옵션은, 표면이 비디오 포트로부터 데이터를 받을 때, 또는 비디오가 수직 방향으로 적어도 2배 줌 될 때인 만큼 유효하다.
DDCAPS2_CANBOBNONINTERLEAVED
오버레이 하드웨어는, 특별한 하드웨어 지원이 없으면, 보통 발생할 가능성이 있는 이상을 일으키는 일 없이, 메모리로 인터리브 하고 있지 않는 동안은, 인터 레이스 비디오 스트림의 각각의 필드를 개별적으로 표시할 수 있다. 이 옵션은, 표면이 비디오 포트로부터 데이터를 받을 때, 또는, 비디오가 수직 방향으로 적어도 2배 줌 될 때인 만큼 유효하다.
DDCAPS2_CANCALIBRATEGAMMA
시스템에는, 자동적으로 감마 램프를 조절할 수 있는 인스톨 된 구경 측정기가 있으므로, 그 결과는 구경 측정기가 있는 전시스템상에서 나타난다. 새로운 감마 레벨을 설정할 경우에 구경 측정기를 포함하려면 ,DirectDrawGammaControl.SetGammaRamp 메소드를 호출하면나무에, DDSGR_CALIBRATE 플래그를 사용한다. 감마 램프의 calibration에서는, 몇개의 처리에 오버헤드가 일어나므로, 빈번하게 사용할 수 없다.
DDCAPS2_CANDROPZ16BIT
16 비트 RGBZ 값을 16 비트 RGB 값으로 변환할 수 있다 (시스템은, 8 비트 변환을 지원 하지 않는다).
DDCAPS2_CANFLIPODDEVEN
드라이버는,DirectDrawSurface7.Flip 메소드와 함께 사용하는 DDFLIP_ODD 및 DDFLIP_EVEN 플래그를 지정해, 홀수 및 짝수 플립 처리를 실행할 수 있다.
DDCAPS2_CANMANAGETEXTURE
Microsoft® Direct3D® 텍스쳐 매니저는, 이 플래그를 사용해, 관리되는 표면을 비로컬 비디오 메모리에 넣을지 어떨지를 결정한다. 이 플래그가 설정되어 있는 경우, 텍스쳐 매니저는 관리되는 표면을 비로컬 비디오 메모리에 넣는다. 비로컬 비디오 메모리로부터의 텍스쳐링이 불가능한 드라이버에서는, 이 플래그를 설정하지 않는다.
DDCAPS2_CANRENDERWINDOWED
드라이버는, 윈도우 모드의 렌더링이 생긴다.
DDCAPS2_CERTIFIED
디스플레이 하드웨어가 보증되고 있는 것을 나타낸다.
DDCAPS2_COLORCONTROLOVERLAY
오버레이 표면에, 컬러 컨트롤 (휘도(Luminance), 선명도등)을 포함한다.
DDCAPS2_COLORCONTROLPRIMARY
프라이머리 표면에, 컬러 컨트롤 (예를 들어, 감마)을 포함한다.
DDCAPS2_COPYFOURCC
드라이버가, 같은 FOURCC 의 다른 표면에 대해서, FOURCC 표면의 블리트를 지원 하는 것을 나타낸다.
DDCAPS2_FLIPINTERVAL
드라이버가 DDFLIP_INTERVAL* 플래그에 응답하는 것을 나타낸다 ( 「DirectDrawSurface7.Flip 」참조).
DDCAPS2_FLIPNOVSYNC
드라이버가 DDFLIP_NOVSYNC 플래그에 응답하는 것을 나타낸다 ( 「DirectDrawSurface7.Flip 」참조).
DDCAPS2_NO2DDURING3DSCENE
Direct3DDevice7.BeginScene 메소드를 호출하고 나서 Direct3DDevice7.EndScene 메소드를 호출할 때까지 에 Direct3D 가 사용하는 모든 표면상에서,DirectDrawSurface7.Blt 및 DirectDrawSurface7.Lock 와 같은 2D 처리를 실행할 수 없는 것을 나타낸다.
DDCAPS2_NONLOCALVIDMEM
디스플레이 드라이버가, 비로컬 비디오 메모리의 표면을 지원 하는 것을 나타낸다.
DDCAPS2_NONLOCALVIDMEMCAPS
비로컬 비디오 메모리 표면의 블리트 능력이, 로컬 비디오 메모리 표면의 경우와 다른 것을 나타낸다. 이 플래그가 존재하는 경우, DDCAPS2_NONLOCALVIDMEM 플래그도 존재한다.
DDCAPS2_NOPAGELOCKREQUIRED
페이지 락되어 있지 않은 시스템 메모리 표면이, DMA 블리트 처리를 지원 한다.
DDCAPS2_PRIMARYGAMMA
프라이머리 표면에 대한 다이나믹 감마 램프를 지원 한다. 상세한 것에 대하여는, 「감마 컨트롤과 컬러 컨트롤」을 참조할것.
DDCAPS2_STEREO
DirectX 7.0 의 신기능. 스테레오 모드를 지원 하려면 , ddcaps.dwSVCaps 비트를 온으로 한다. 드라이버는, 현재의 모드 이외가 적어도 1 개의 모드로 스테레오 뷰를 실현할 수 있다. 어플리케이션은,DirectDraw7.GetDisplayMode 또는 DirectDraw7.GetDisplayModesEnum 를 사용해, 모드마다의 스테레오 정보를 취득할 수 있다.
DDCAPS2_VIDEOPORT
디스플레이 하드웨어가, 라이브 비디오를 지원 하는 것을 나타낸다.
DDCAPS2_WIDESURFACES
디스플레이 표면이, 프라이머리 표면보다 넓은 표면을 지원 하는 것을 나타낸다.


CONST_DDCKEYCAPSFLAGS

CONST_DDCKEYCAPSFLAGS 열거는,DDCAPS 형의 lCKeyCaps,lNLVBCKeyCaps,lSSBCKeyCaps,lSVBCKeyCaps, 및 lVSBCKeyCaps 멤버로 사용되어 하드웨어의 컬러 키 능력을 기술한다.

Enum CONST_DDCKEYCAPSFLAGS
    DDCKEYCAPS_DESTBLT               =      1
    DDCKEYCAPS_DESTBLTCLRSPACE       =      2
    DDCKEYCAPS_DESTBLTCLRSPACEYUV    =      4
    DDCKEYCAPS_DESTBLTYUV            =      8
    DDCKEYCAPS_DESTOVERLAY           =     16
    DDCKEYCAPS_DESTOVERLAYCLRSPACE   =     32
    DDCKEYCAPS_DESTOVERLAYCLRSPACEYUV =    64
    DDCKEYCAPS_DESTOVERLAYONEACTIVE  =    128
    DDCKEYCAPS_DESTOVERLAYYUV        =    256
    DDCKEYCAPS_NOCOSTOVERLAY         = 262144
    DDCKEYCAPS_SRCBLT                =    512
    DDCKEYCAPS_SRCBLTCLRSPACE        =   1024
    DDCKEYCAPS_SRCBLTCLRSPACEYUV     =   2048
    DDCKEYCAPS_SRCBLTYUV             =   4096
    DDCKEYCAPS_SRCOVERLAY            =   8192
    DDCKEYCAPS_SRCOVERLAYCLRSPACE    =  16384
    DDCKEYCAPS_SRCOVERLAYCLRSPACEYUV =  32768
    DDCKEYCAPS_SRCOVERLAYONEACTIVE   =  65536
    DDCKEYCAPS_SRCOVERLAYYUV         = 131072
End Enum
DDCKEYCAPS_DESTBLT
컬러 키에 의한 투과형 블리트를 지원 한다. 컬러 키는, RGB 색의 목적지 표면의 치환가능인 비트를 식별한다.
DDCKEYCAPS_DESTBLTCLRSPACE
색공간(color space)에 의한 투과형 블리트를 지원 한다. 색공간(color space)은, RGB 색의 목적지 표면의 치환가능인 비트를 식별한다.
DDCKEYCAPS_DESTBLTCLRSPACEYUV
색공간(color space)에 의한 투과형 블리트를 지원 한다. 색공간(color space)는, YUV 색의 목적지 표면의 치환가능인 비트를 식별한다.
DDCKEYCAPS_DESTBLTYUV
컬러 키에 의한 투과형 블리트를 지원 한다. 컬러 키는, YUV 색의 목적지 표면의 치환가능인 비트를 식별한다.
DDCKEYCAPS_DESTOVERLAY
컬러 키잉에 의한 오버레이를 지원 한다. 컬러 키잉은, RGB 색으로 오버레이 되는 목적지 표면의 치환가능인 비트이다.
DDCKEYCAPS_DESTOVERLAYCLRSPACE
RGB 색의 목적지에 있어서의컬러 키로서색공간(color space)를 지원 한다.
DDCKEYCAPS_DESTOVERLAYCLRSPACEYUV
YUV 색의 목적지에 있어서의컬러 키로서색공간(color space)를 지원 한다.
DDCKEYCAPS_DESTOVERLAYONEACTIVE
표시되는오버레이 표면에 대해서,1 개의 액티브목적지 컬러 키값만을 지원 한다.
DDCKEYCAPS_DESTOVERLAYYUV
컬러 키잉을 사용해 오버레이를 지원 한다. 컬러 키잉은, YUV 색으로 오버레이 되는 목적지 표면의 치환가능인 비트이다.
DDCKEYCAPS_NOCOSTOVERLAY
오버레이로컬러 키를 사용하는 것에 대해, 대역폭 트레이드 오프가 없는 것을 나타낸다.
DDCKEYCAPS_SRCBLT
RGB 색의 표면으로 전송원의컬러 키를 사용해, 투과형 블리트를 지원 한다.
DDCKEYCAPS_SRCBLTCLRSPACE
RGB 색의 표면으로 전송원의색공간(color space)를 사용해, 투과형 블리트를 지원 한다.
DDCKEYCAPS_SRCBLTCLRSPACEYUV
YUV 색의 표면으로 전송원의색공간(color space)를 사용해, 투과형 블리트를 지원 한다.
DDCKEYCAPS_SRCBLTYUV
YUV 색의 표면으로 전송원의컬러 키를 사용해, 투과형 블리트를 지원 한다.
DDCKEYCAPS_SRCOVERLAY
RGB 색의오버레이 표면으로 전송원의컬러 키를 사용해, 오버레이를 지원 한다.
DDCKEYCAPS_SRCOVERLAYCLRSPACE
RGB 색의오버레이 표면의전송원컬러 키로서색공간(color space)를 사용해 오버레이를 지원 한다.
DDCKEYCAPS_SRCOVERLAYCLRSPACEYUV
YUV 색의오버레이 표면의전송원컬러 키로서색공간(color space)를 사용해 오버레이를 지원 한다.
DDCKEYCAPS_SRCOVERLAYONEACTIVE
표시되는오버레이 표면에 대해서,1 개의 액티브전송원컬러 키값만을 지원 한다.
DDCKEYCAPS_SRCOVERLAYYUV
YUV 색의오버레이 표면으로 전송원의컬러 키를 사용해, 오버레이를 지원 한다.


CONST_DDCKEYFLAGS

CONST_DDCKEYFLAGS 열거는,DirectDrawSurface7.SetColorKey 메소드의 flags 플래그로 사용되어 요구된 컬러 키의 타입을 지정한다.

Enum CONST_DDCKEYFLAGS
    DDCKEY_COLORSPACE =  1
    DDCKEY_DESTBLT    =  2
    DDCKEY_DESTOVERLAY = 4
    DDCKEY_SRCBLT     =  8
    DDCKEY_SRCOVERLAY = 16
End Enum
DDCKEY_COLORSPACE
색공간(color space) . 형태에 단일의 컬러 키가 있는 경우는 설정하지 않는다.
DDCKEY_DESTBLT
블리트 처리의목적지 컬러 키로서 사용되는 컬러 키나 색공간(color space).
DDCKEY_DESTOVERLAY
오버레이 처리의 목적지 컬러 키로서 사용되는 컬러 키나 색공간(color space).
DDCKEY_SRCBLT
블리트 처리의전송원컬러 키로서 사용되는 컬러 키나 색공간(color space).
DDCKEY_SRCOVERLAY
오버레이 처리의 전송원컬러 키로서 사용되는 컬러 키나 색공간(color space).


CONST_DDCOLORFLAGS

CONST_DDCOLORFLAGS 열거는,DDCOLORCONTROL 형의 lFlags 멤버로 사용되어DDCOLORCONTROL 형의 어느 멤버가 유효한 데이터를 포함하는지를 나타낸다.

Enum CONST_DDCOLORFLAGS
    DDCOLOR_BRIGHTNESS  =  1
    DDCOLOR_COLORENABLE = 64
    DDCOLOR_CONTRAST    =  2
    DDCOLOR_GAMMA       = 32
    DDCOLOR_HUE         =  4
    DDCOLOR_SATURATION  =  8
    DDCOLOR_SHARPNESS   = 16
End Enum
DDCOLOR_BRIGHTNESS
IBrightness 멤버가 유효한 데이터를 포함한다.
DDCOLOR_COLORENABLE
lColorEnable 멤버가 유효한 데이터를 포함한다.
DDCOLOR_CONTRAST
IContrast 멤버가 유효한 데이터를 포함한다.
DDCOLOR_GAMMA
IGamma 멤버가 유효한 데이터를 포함한다.
DDCOLOR_HUE
IHue 멤버가 유효한 데이터를 포함한다.
DDCOLOR_SATURATION
ISaturation 멤버가 유효한 데이터를 포함한다.
DDCOLOR_SHARPNESS
ISharpness 멤버가 유효한 데이터를 포함한다.


CONST_DDDEVICEIDFLAGS

CONST_DDDEVICEIDFLAGS 열거는,DirectDraw7.GetDeviceIdentifier 메소드의 flags 파라미터로 사용되어 스택 된 제 2 의 3D 어댑터와 함께 장비 되는, 시스템의 호스트 (보통은 2D) 어댑터에 관한 정보를 돌려준다.

Enum CONST_DDDEVICEIDFLAGS
    DDGDI_DEFAULT           = 0
    DDGDI_GETHOSTIDENTIFIER = 1
End Enum
DDGDI_DEFAULT
호스트 어댑터의 보통의 열거를 실행한다.
DDGDI_GETHOSTIDENTIFIER
스택 된 제 2 의 3D 어댑터와 함께 장비 되는, 시스템의 호스트 (보통은 2D) 어댑터에 대한 정보를 돌려주기 위해서(때문에) 메소드를 일으킨다. 이러한 어댑터는, 호스트 어댑터의 일부이지만, 다른 카드로 보통 배치되고 있도록(듯이) 어플리케이션에 나타난다. dwFlags 파라미터가 제로의 경우, DirectDraw 오브젝트의 질을 가장 정확하게 반영하기 위해서, 스톡 된 제 2 의 정보가 돌려주어진다.


CONST_DDEDMFLAGS

CONST_DDEDMFLAGS 열거는,DirectDraw7.GetDisplayModesEnum 메소드의 flags 파라미터로 사용되어 열거의 타입을 지정한다.

Enum CONST_DDEDMFLAGS
    DDEDM_DEFAULT          = 0
    DDEDM_REFRESHRATES     = 1
    DDEDM_STANDARDVGAMODES = 2
End Enum
DDEDM_DEFAULT
디스플레이 모드의 보통의 열거를 실행한다.
DDEDM_REFRESHRATES
다른 refresh rate로 모드를 열거한다. 특정의 모드가 1 회만 열거되는 것을 보증한다. 이 플래그는, 모드가 독특한가 어떤가를 결정할 때, refresh rate를 고려할지 어떨지를 지정한다.
DDEDM_STANDARDVGAMODES
320×200×8 모드 X 모드 이외에, 모드 13 을 열거한다.


CONST_DDENUMOVERLAYZFLAGS

CONST_DDENUMOVERLAYZFLAGS 열거는,DirectDrawSurface7.GetOverlayZOrdersEnum 메소드의 flags 파라미터로 사용되어 메소드가 오버레이의 z 오더를 열거하는 방법을 제어한다.

Enum CONST_DDENUMSURFACESFLAGS
    DDENUMOVERLAYZ_BACKTOFRONT = 0
    DDENUMOVERLAYZ_FRONTTOBACK = 1
End Enum
DDENUMOVERLAYZ_BACKTOFRONT
가방으로부터 프런트의 순서로 오버레이를 열거한다.
DDENUMOVERLAYZ_FRONTTOBACK
프런트로부터 가방의 순서로 오버레이를 열거한다.


CONST_DDENUMSURFACESFLAGS

CONST_DDENUMSURFACESFLAGS 열거는,DirectDraw7.GetSurfacesEnum 메소드가, Attach 된 표면을 열거하는 방법을 제어한다.

Enum CONST_DDENUMSURFACESFLAGS
    DDENUMSURFACES_ALL          =  1
    DDENUMSURFACES_CANBECREATED =  8
    DDENUMSURFACES_DOESEXIST    = 16
    DDENUMSURFACES_MATCH        =  2
    DDENUMSURFACES_NOMATCH      =  4
End Enum
검색형 플래그
DDENUMSURFACES_CANBECREATED
생성 가능해 검색 기준에 맞는 최초의 표면을 열거한다. 이 플래그는, DDENUMSURFACES_MATCH 플래그와 함께 사용되는 것만으로 있다.
DDENUMSURFACES_DOESEXIST
검색 기준에 맞는 기존의 표면을 열거한다.
적합 플래그
DDENUMSURFACES_ALL
검색 기준에 맞는 표면 모든 것을 열거한다. 이 플래그는, DDENUMSURFACES_DOESEXIST 검색형 플래그와 함께 사용되는 것만으로 있다.
DDENUMSURFACES_MATCH
표면 기술에 적합하는 표면을 검색한다.
DDENUMSURFACES_NOMATCH
표면 기술에 적합하지 않는 표면을 검색한다.


CONST_DDFLIPFLAGS

CONST_DDFLIPFLAGS 열거는,DirectDrawSurface7.Flip 메소드의 flags 파라미터로 사용되어 플립 옵션을 지정한다.

Enum CONST_DDFLIPFLAGS
    DDFLIP_DONOTWAIT  =         32
    DDFLIP_EVEN       =          2
    DDFLIP_INTERFVAL2 =  536870912
    DDFLIP_INTERFVAL3 =  805306368
    DDFLIP_INTERFVAL4 = 1073741824
    DDFLIP_NOVSYNC    =          8
    DDFLIP_ODD        =          4
    DDFLIP_WAIT       =          1
    DDFLIP_STEREO     =         16
End Enum
DDFLIP_DONOTWAIT
디폴트는 DDFLIP_WAIT. 디폴트값을 오버라이드(override) 해, 가속기가 Busy의 사이 (DDERR_WASSTILLDRAWING 에러값으로 나타난다)의 시간을 사용하고 싶은 경우는, DDFLIP_DONOTWAIT 를 사용한다.
DDFLIP_EVEN
오버레이 표면으로 비디오를 표시하는 경우에 사용한다. 새로운 표면에는, 비디오 신호의짝수 필드로부터의 데이터가 포함된다. 이 플래그는, DDFLIP_ODD 플래그와 함께 사용할 수 없다.
DDFLIP_INTERFVAL2, DDFLIP_INTERFVAL3,
DDFLIP_INTERFVAL4
이러한 플래그는, 각 플립간을 대기하는 수직 리트레이스수를 나타낸다. 디폴트값은 1. DirectDraw 에서는, 지정한 수직 리트레이스수가 될 때까지, 플립내의 각 표면에 DERR_WASSTILLDRAWING 를 돌려준다. DDFLIP_INTERVAL2 이 설정되면(자), DirectDraw 는 2 번째의 수직 동기 마다 플립 한다. DDFLIP_INTERVAL3 에서는 3 번째의 동기마다, DDFLIP_INTERVAL4 에서는 4 번째의 동기 마다 플립 한다.

DDCAPS2_FLIPINTERVAL 가 디바이스에 되돌려지는 DDCAPS 형으로 설정되는 경우에만, 이러한 플래그는 효율적이다.

DDFLIP_NOVSYNC
다음의 주사선으로 할 수 있는 한 가까운 물리적인 플립을 실행하는 DirectDraw 를 일으킨다. 2 개의 플립 된 표면을 포함한 다음의 처리에서는, 물리적인 플립이 종료했는지 어떠했는지를 체크하지 않는다. 즉, 이 결과를 위해서(때문에) DDERR_WASSTILLDRAWING 를 돌려주지 않는다 (다른 결과에서는 돌려주는 경우도 있다). 이 때문에, 어플리케이션에서는 모니터의 refresh rate 이상의 고주파수로 플립을 실행할 수 있지만, 눈에 보이는 이상이 발생하는 경우도 있다.

DDCAPS2_FLIPNOVSYNC 가 디바이스에 되돌려지는 DDCAPS 형으로 설정되어 있지 않은 경우, DDFLIP_NOVSYNC 는 비효율적이다.

DDFLIP_ODD
오버레이 표면으로 비디오를 표시하는 경우에 사용한다. 새로운 플래그에는, 비디오 신호의홀수 필드로부터의 데이터가 포함된다. 이 플래그는, DDFLIP_EVEN 플래그와 함께 사용할 수 없다.
DDFLIP_STEREO
DirectDraw 가 메인 스테레오 표면을 플립 해 표시한다. 이 플래그를 설정 하면, 스테레오 자동 플립핑이 가능하게 된다. 하드웨어는, 스크린을 리프레쉬 할 때 마다, 왼쪽과 오른쪽의 버퍼의 사이에 자동적으로 플립 한다.
DDFLIP_WAIT
보통, 디스플레이 하드웨어 상태가 부적절하기 때문에에 플립을 셋업 할 수 없는 경우,DDERR_WASSTILLDRAWING 에러가 즉석에서 돌아가, 플립은 일어나지 않는다. 그러나, 이 플래그를 설정 하면, 하드웨어 추상 계층 (HAL)으로부터 DDERR_WASSTILLDRAWING 에러를 받아도, 메소드는 플립 계속 하려고 한다. 이 경우, 메소드는 플립핑 처리가 성공하는지,DDERR_SURFACEBUSY 와 같은 다른 에러가 돌려주어질 때까지 돌려주지 않는다.


CONST_DDFXCAPSFLAGS

CONST_DDFXCAPSFLAGS 열거는,DDCAPS 형의 lFXCaps,lNLVBFXCaps,lSSBFXCaps,lSVBFXCaps, 및 lVSBFXCaps 멤버로 사용되어 신축(스트레치) 및 이펙트, 비로컬 비디오 메모리로부터 로컬 비디오 메모리에의 블리트, 시스템 메모리로부터 시스템 메모리에의 블리트, 시스템 메모리로부터 디스플레이 메모리에의 블리트, 및 디스플레이 메모리로부터 시스템 메모리에의 블리트에 대한 드라이버 고유의 능력을 기술한다.

Enum CONST_DDFXCAPSFLAGS
    DDFXCAPS_BLTALPHA               =         1
    DDFXCAPS_BLTARITHSTRETCHY       =        32
    DDFXCAPS_BLTARITHSTRETCHYN      =        16
    DDFXCAPS_BLTFILTER              =        32
    DDFXCAPS_BLTMIRRORLEFTRIGHT     =        64
    DDFXCAPS_BLTMIRRORUPDOWN        =       128
    DDFXCAPS_BLTROTATION            =       256
    DDFXCAPS_BLTROTATION90          =       512
    DDFXCAPS_BLTSHRINKX             =      1024
    DDFXCAPS_BLTSHRINKXN            =      2048
    DDFXCAPS_BLTSHRINKY             =      4096
    DDFXCAPS_BLTSHRINKYN            =      8192
    DDFXCAPS_BLTSTRETCHX            =     16384
    DDFXCAPS_BLTSTRETCHXN           =     32768
    DDFXCAPS_BLTSTRETCHY            =     65536
    DDFXCAPS_BLTSTRETCHYN           =    131072
    DDFXCAPS_BLTTRANSFORM           =         2
    DDFXCAPS_OVERLAYALPHA           =         4
    DDFXCAPS_OVERLAYARITHSTRETCHY   =    262144
    DDFXCAPS_OVERLAYARITHSTRETCHYN  =         8
    DDFXCAPS_OVERLAYFILTER          =    262144
    DDFXCAPS_OVERLAYMIRRORLEFTRIGHT = 134217728
    DDFXCAPS_OVERLAYMIRRORUPDOWN    = 268435456
    DDFXCAPS_OVERLAYSHRINKX         =    524288
    DDFXCAPS_OVERLAYSHRINKXN        =   1048576
    DDFXCAPS_OVERLAYSHRINKY         =   2097152
    DDFXCAPS_OVERLAYSHRINKYN        =   4194304
    DDFXCAPS_OVERLAYSTRETCHX        =   8388608
    DDFXCAPS_OVERLAYSTRETCHXN       =  16777216
    DDFXCAPS_OVERLAYSTRETCHY        =  33554432
    DDFXCAPS_OVERLAYSTRETCHYN       =  67108864
    DDFXCAPS_OVERLAYTRANSFORM       = 536870912
End Enum
DDFXCAPS_BLTALPHA
알파 블렌딩 블리트 처리를 지원 한다.
DDFXCAPS_BLTARITHSTRETCHY
픽셀을 2 승으로 해 확대하는 기술은 아니고, 블리트 처리중에 표면을 확대하거나 수축하는 산술 처리를 사용한다. 이것은, y 축 (수직)에 따라 행해진다.
DDFXCAPS_BLTARITHSTRETCHYN
픽셀을 2 승으로 해 확대하는 기술은 아니고, 블리트 처리중에 표면을 확대하거나 수축하는 산술 처리를 사용한다. 이것은, y 축 (수직)에 따라 행해져 정수배 (×1,×2 등)로신축(스트레치) 하기 위한(해)인 만큼 동작한다.
DDFXCAPS_BLTFILTER
드라이버는, 랩 된 블리트에 대해서 필터링 하는 표면의 복구성을 실시할 수 있다.
DDFXCAPS_BLTMIRRORLEFTRIGHT
블리트 처리로 좌우의 미러링을 지원 한다.
DDFXCAPS_BLTMIRRORUPDOWN
블리트 처리로 상하의 미러링을 지원 한다.
DDFXCAPS_BLTROTATION
블리트 처리로 임의의 회전을 지원 한다.
DDFXCAPS_BLTROTATION90
블리트 처리로 90 번의 회전을 지원 한다.
DDFXCAPS_BLTSHRINKX
x 축 (수평)에 따라 표면을 임의에 수축하는 것을 지원 한다. 이 플래그는, 블리트 처리인 만큼 유효하다.
DDFXCAPS_BLTSHRINKXN
x 축 (수평)에 따라 표면을 정수배 (×1,×2 등)에 수축하는 것을 지원 한다. 이 플래그는, 블리트 처리인 만큼 유효하다.
DDFXCAPS_BLTSHRINKY
y 축 (수직)에 따라 표면을 임의에 수축하는 것을 지원 한다. 이 플래그는, 블리트 처리인 만큼 유효하다.
DDFXCAPS_BLTSHRINKYN
y 축 (수직)에 따라 표면을 정수배 (×1,×2 등)에 수축하는 것을 지원 한다. 이 플래그는, 블리트 처리인 만큼 유효하다.
DDFXCAPS_BLTSTRETCHX
x 축 (수평)에 따라 표면을 임의에신축(스트레치) 하는 것을 지원 한다. 이 플래그는, 블리트 처리인 만큼 유효하다.
DDFXCAPS_BLTSTRETCHXN
x 축 (수평)에 따라 표면을 정수배 (×1,×2 등)에신축(스트레치) 하는 것을 지원 한다. 이 플래그는, 블리트 처리인 만큼 유효하다.
DDFXCAPS_BLTSTRETCHY
y 축 (수직)에 따라 표면을 임의에신축(스트레치) 하는 것을 지원 한다. 이 플래그는, 블리트 처리인 만큼 유효하다.
DDFXCAPS_BLTSTRETCHYN
y 축 (수직)에 따라 표면을 정수배 (×1,×2 등)에신축(스트레치) 하는 것을 지원 한다. 이 플래그는, 블리트 처리인 만큼 유효하다.
DDFXCAPS_BLTTRANSFORM
블리트 되는 스프라이트에 대해서 지오메트리 트랜스 폼 (또는, 랩)을 지원 한다. 현시점에서는, 트랜스 폼은 블리트 처리로 지원되어 있지 않다.
DDFXCAPS_OVERLAYALPHA
오버레이 표면에 대한 알파 블렌딩을 지원 한다.
DDFXCAPS_OVERLAYARITHSTRETCHY
y 축 (수직)에 따라 표면을 임의에 수축하는 것을 지원 한다.
DDFXCAPS_OVERLAYARITHSTRETCHYN
y 축 (수직)에 따라 표면을 정수배 (×1,×2 등)에 수축하는 것을 지원 한다.
DDFXCAPS_OVERLAYFILTER
랩 된 오버레이 스프라이트에 대해서 필터링 하는 표면의 복구성을 지원 한다. 현시점에서는, 필터링은 명시적으로 표시되는 오버레이 표면 (DirectDrawSurface7.UpdateOverlay 의 호출로 표시된다)으로 지원되어 있지 않다.
DDFXCAPS_OVERLAYMIRRORLEFTRIGHT
수평 축으로 따라 오버레이의 미러링을 지원 한다.
DDFXCAPS_OVERLAYMIRRORUPDOWN
수평 축으로 따라 오버레이의 미러링을 지원 한다.
DDFXCAPS_OVERLAYSHRINKX
x 축 (수평)에 따라 표면을 임의에 수축하는 것을 지원 한다. 이 플래그는, DDSCAPS_OVERLAY 표면인 만큼 유효하다. 이 플래그는, 표면의 능력만을 나타내, 수축이 가능하다 것은 아니다.
DDFXCAPS_OVERLAYSHRINKXN
x 축 (수평)에 따라 표면을 정수배 (×1,×2 등)에 수축하는 것을 지원 한다. 이 플래그는, DDSCAPS_OVERLAY 표면인 만큼 유효하다. 이 플래그는, 표면의 능력만을 나타내, 수축이 가능하다 것은 아니다.
DDFXCAPS_OVERLAYSHRINKY
y 축 (수직)에 따라 표면을 임의에 수축하는 것을 지원 한다. 이 플래그는, DDSCAPS_OVERLAY 표면인 만큼 유효하다. 이 플래그는, 표면의 능력만을 나타내, 수축이 가능하다 것은 아니다.
DDFXCAPS_OVERLAYSHRINKYN
y 축 (수직)에 따라 표면을 정수배 (×1,×2 등)에 수축하는 것을 지원 한다. 이 플래그는, DDSCAPS_OVERLAY 표면인 만큼 유효하다. 이 플래그는, 표면의 능력만을 나타내, 수축이 가능하다 것은 아니다.
DDFXCAPS_OVERLAYSTRETCHX
x 축 (수평)에 따라 표면을 임의에신축(스트레치) 하는 것을 지원 한다. 이 플래그는, DDSCAPS_OVERLAY 표면인 만큼 유효하다. 이 플래그는, 표면의 능력만을 나타내,신축(스트레치)가 가능하다 것은 아니다.
DDFXCAPS_OVERLAYSTRETCHXN
x 축 (수평)에 따라 표면을 정수배 (×1,×2 등)에신축(스트레치) 하는 것을 지원 한다. 이 플래그는, DDSCAPS_OVERLAY 표면인 만큼 유효하다. 이 플래그는, 표면의 능력만을 나타내,신축(스트레치)가 가능하다 것은 아니다.
DDFXCAPS_OVERLAYSTRETCHY
y 축 (수직)에 따라 표면을 임의에신축(스트레치) 하는 것을 지원 한다. 이 플래그는, DDSCAPS_OVERLAY 표면인 만큼 유효하다. 이 플래그는, 표면의 능력만을 나타내,신축(스트레치)가 가능하다 것은 아니다.
DDFXCAPS_OVERLAYSTRETCHYN
y 축 (수직)에 따라 표면을 정수배 (×1,×2 등)에신축(스트레치) 하는 것을 지원 한다. 이 플래그는, DDSCAPS_OVERLAY 표면인 만큼 유효하다. 이 플래그는, 표면의 능력만을 나타내,신축(스트레치)가 가능하다 것은 아니다.
DDFXCAPS_OVERLAYTRANSFORM
오버레이 스프라이트에 대해서 지오메트리 트랜스 폼 (또는, 랩)을 지원 한다. 현시점에서는, 트랜스 폼은 명시적으로 표시되는 오버레이 표면 (DirectDrawSurface7.UpdateOverlay 의 호출로 표시된다)으로 지원되어 있지 않다.


CONST_DDGBSFLAGS

CONST_DDGBSFLAGS 열거는,DirectDrawSurface7.GetBltStatus 메소드의 flags 파라미터로 사용되어 취득하는 스테이터스의 타입을 지정한다.

Enum CONST_DDGBSFLAGS
    DDGBS_CANBLT    = 1
    DDGBS_ISBLTDONE = 2
End Enum
DDGBS_CANBLT
이 표면을 필요로 하는 블리트를 곧바로 실행할 수 있을지 어떨지를 문의해 블리트가 완료 하면 DD_OK 를 돌려준다.
DDGBS_ISBLTDONE
블리트가 실행되었는지 어떠했는지를 문의해 이 표면 위에의 마지막 블리트가 완료 하면 DD_OK 를 돌려준다.


CONST_DDGFSFLAGS

CONST_DDGFSFLAGS 열거는,DirectDrawSurface7.GetFlipStatus 메소드의 flags 파라미터로 사용되어 취득하는 플립 스테이터스의 타입을 지정한다.

Enum CONST_DDGFSFLAGS
    DDGFS_CANFLIP    = 1
    DDGFS_ISFLIPDONE = 2
End Enum
DDGFS_CANFLIP
이 표면을 즉석에서 플립 할 수 있을지 어떨지를 문의해 플립이 완료하면(자) DD_OK 를 돌려준다.
DDGFS_ISFLIPDONE
플립이 완료했는지 어떠했는지를 문의해 이 표면의 마지막 플립이 완료하면(자) DD_OK 를 돌려준다.


CONST_DDLOCKFLAGS

CONST_DDLOCKFLAGS 열거는,DirectDrawSurface7.Lock 및 Direct3DVertexBuffer7.Lock 메소드의 flags 파라미터로 사용되어 락의 실행 방법을 나타낸다.

Enum CONST_DDLOCKFLAGS
    DDLOCK_DONOTWAIT     = 16384
    DDLOCK_EVENT         =    2
    DDLOCK_NOSYSLOCK     = 2048
    DDLOCK_READONLY      =   16
    DDLOCK_SURFACEMEMORYPTR = 0
    DDLOCK_WAIT          =    1
    DDLOCK_WRITEONLY     =   32
End Enum
DDLOCK_DONOTWAIT
디폴트는 DDLOCK_WAIT. 디폴트값을 오버라이드(override) 해, 가속기가 Busy의 사이 (DDERR_WASSTILLDRAWING 에러값으로 나타난다)의 시간을 사용하고 싶은 경우는, DDFLIP_DONOTWAIT 를 사용한다.
DDLOCK_EVENT
현시점에서는, 이행되어 있지 않다.
DDLOCK_NOSYSLOCK
Win16Mutex (Win16Lock 로 불린다)를 사용하지 않는다. 프라이머리 표면을 잠그고 있을 때는, 이 플래그는 무시된다.
DDLOCK_READONLY
잠그고 있는 표면이 읽어들여 전용인 것을 나타낸다.
DDLOCK_SURFACEMEMORYPTR
유효한 직사각형을 돌려주지 않으면 안 되는 것을 나타낸다. 직사각형이 지정되어 있지 않은 경우, 표면을 돌려준다. 이 플래그는 디폴트이다.
DDLOCK_WAIT
블리트 처리가 처리중을 위해서(때문에) 락을 취득할 수 없는 경우, 락이 취득될 때까지, 또는 DDERR_SURFACEBUSY 와 같은 다른 에러가 발생할 때까지, 메소드는 재시행한다.
DDLOCK_WRITEONLY
잠그고 있는 표면이 쓰기 가능한 것을 나타낸다.


CONST_DDOVERFLAGS

CONST_DDOVERFLAGS 열거의 플래그는,DirectDrawSurface7.UpdateOverlay 메소드의 flags 파라미터로 사용되어 오버레이의 비주얼 속성을 변경한다.

Enum CONST_DDOVERFLAGS
    DDOVER_ADDDIRTYRECT             = 32768
    DDOVER_ALPHADEST                = 1
    DDOVER_ALPHADESTCONSTOVERRIDE   = 2
    DDOVER_ALPHADESTNEG             = 4
    DDOVER_ALPHADESTSURFACEOVERRIDE = 8
    DDOVER_ALPHAEDGEBLEND           = 16
    DDOVER_ALPHASRC                 = 32
    DDOVER_ALPHASRCCONSTOVERRIDE    = 64
    DDOVER_ALPHASRCNEG              = 128
    DDOVER_ALPHASRCSURFACEOVERRIDE  = 256
    DDOVER_ARGBSCALEFACTORS         = 33554432
    DDOVER_AUTOFLIP                 = 1048576
    DDOVER_BOB                      = 2097152
    DDOVER_DDFX                     = 524288
    DDOVER_DEGRADEARGBSCALING       = 67108864
    DDOVER_HIDE                     = 512
    DDOVER_INTERLEAVED              = 8388608
    DDOVER_KEYDEST                  = 1024
    DDOVER_KEYDESTOVERRIDE          = 2048
    DDOVER_KEYSRC                   = 4096
    DDOVER_KEYSRCOVERRIDE           = 8192
    DDOVER_OVERRIDEBOBWEAVE         = 4194304
    DDOVER_REFRESHALL               = 131072
    DDOVER_REFRESHDIRTYRECTS        = 65536
    DDOVER_SHOW                     = 16384
End Enum
DDOVER_ADDDIRTYRECT
에뮬레이트 된 오버레이 표면에 더티 직사각형을 추가한다.
DDOVER_ALPHADEST
폐지되었다.
DDOVER_ALPHADESTCONSTOVERRIDE
이 오버레이에 대해서 목적지알파 채널로서 DDOVERLAYFX 형의 lAlphaDestConst 멤버를 사용한다.
DDOVER_ALPHADESTNEG
알파값의 증가에 따라 목적지 표면이 보다 투과형이 되는 것을 나타낸다 (0 은 불투명).
DDOVER_ALPHADESTSURFACEOVERRIDE
이 오버레이에 대해서 목적지알파 채널로서 DDOVERLAYFX 형의 lpDDSAlphaDest 멤버를 사용한다.
DDOVER_ALPHAEDGEBLEND
컬러 키색을 경계로 하는 이미지의 인연에 대한알파 채널로서 DDOVERLAYFX 형의 lAlphaEdgeBlend 멤버를 사용한다.
DDOVER_ALPHASRC
픽셀 포맷의 알파 정보인가, 이 오버레이에 대해서 전송원알파 채널로서 전송원표면에 Attach 되는알파 채널 표면의 어느 쪽인지를 사용한다.
DDOVER_ALPHASRCCONSTOVERRIDE
이 오버레이에 대해서 전송원알파 채널로서 DDOVERLAYFX 형의 lAlphaSrcConst 멤버를 사용한다.
DDOVER_ALPHASRCNEG
알파값의 증가에 따라 전송원표면이 보다 투과형이 되는 것을 나타낸다 (0 은 불투명).
DDOVER_ALPHASRCSURFACEOVERRIDE
이 오버레이에 대해서 전송원알파 채널로서 DDOVERLAYFX 형의 lpDDSAlphaSrc 멤버를 사용한다.
DDOVER_ARGBSCALEFACTORS
DirectX 7.0 의 신기능. 오버레이 FX 형에 유효한 스케일링 계수가 포함된다.
DDOVER_AUTOFLIP
비디오 포트 VSYNC 가 발생할 때마다, 플립 체인의 다음의 표면을 자동적으로 플립 한다.
DDOVER_BOB
인터 레이스 비디오 스트림의 각각의필드를 이상 없고 개별적으로 표시한다.
DDOVER_DDFX
DirectDrawSurface7.UpdateOverlayFx 를 호출하면나무에,ddoverfx 파라미터의 플래그 세트를 사용해 특수한 오버레이 이펙트를 정의한다. 이 플래그를 설정하지 않으면ddoverfx 파라미터가 무시되므로, 반드시 설정한다.
DDOVER_DEGRADEARGBSCALING
DirectX 7.0 의 신기능. 드라이버의 능력에 맞추어 ARGB 스케일링 계수를 내릴 수가 있다.
DDOVER_HIDE
이 오버레이를 오프로 한다.
DDOVER_INTERLEAVED
표면 메모리가, 인터리브 된 필드로부터 완성되는 것을 나타낸다.
DDOVER_KEYDEST
목적지 표면에 관련지을 수 있었던컬러 키를 사용한다.
DDOVER_KEYDESTOVERRIDE
목적지 표면의컬러 키로서 DDOVERLAYFX 형의 dckColorkey 멤버를 사용한다.
DDOVER_KEYSRC
전송원표면에 관련지을 수 있었던컬러 키를 사용한다.
DDOVER_KEYSRCOVERRIDE
전송원표면의컬러 키로서 DDOVERLAYFX 형의 dckSrcColorkey 멤버를 사용한다.
DDOVER_OVERRIDEBOBWEAVE
BOB/WEAVE 결정을, 다른 인터페이스로 오버라이드(override) 해서는 안 되는 것을 나타낸다.
DDOVER_REFRESHALL
에뮬레이트 된 오버레이 표면상에서 표면 전체를 재드로잉(Drawing) 한다.
DDOVER_REFRESHDIRTYRECTS
에뮬레이트 된 오버레이 표면상에서 더티 직사각형을 재드로잉(Drawing) 한다.
DDOVER_SHOW
이 오버레이를 온으로 한다.


CONST_DDOVERFXFLAGS

CONST_DDOVERFXFLAGS 열거의 플래그는,DDOVERLAYFX 형의 lDDFX 멤버로 사용되어 오버레이의 사용 방법을 지정한다.

Enum CONST_DDPALFLAGS
    DDOVERFX_ARITHSTRETCHY   = 1
    DDOVERFX_MIRRORLEFTRIGHT = 2
    DDOVERFX_MIRRORUPDOWN    = 4
End Enum
DDOVERFX_ARITHSTRETCHY
신축(스트레치) 하는 경우, 이 오버레이의 y 축으로 따라 산술 신축(스트레치)를 사용한다.
DDOVERFX_MIRRORLEFTRIGHT
수직축의 주위에서 오버레이를 밀러화한다.
DDOVERFX_MIRRORUPDOWN
수평축의 주위에서 오버레이를 밀러화한다.


CONST_DDOVERZFLAGS

CONST_DDOVERZFLAGS 열거의 플래그는,DirectDrawSurface7.UpdateOverlayZOrder 형의 flags 멤버로 사용되어 오버레이의 z 오더를 설정한다.

Enum CONST_DDPALFLAGS
    DDOVERZ_INSERTINBACKOF  = 5
    DDOVERZ_INSERTINFRONTOF = 4
    DDOVERZ_MOVEBACKWARD    = 3
    DDOVERZ_MOVEFORWARD     = 2
    DDOVERZ_SENDTOBACK      = 1
    DDOVERZ_SENDTOFRONT     = 0
End Enum
DDOVERZ_INSERTINBACKOF
이 오버레이를 오버레이 체인의 참조 오버레이의 뒤로 삽입한다.
DDOVERZ_INSERTINFRONTOF
이 오버레이를 오버레이 체인의 참조 오버레이의 전에 삽입한다.
DDOVERZ_MOVEBACKWARD
이 오버레이를 오버레이 체인의 1 개 뒤로 이동한다.
DDOVERZ_MOVEFORWARD
이 오버레이를 오버레이 체인의 1 개전으로 이동한다.
DDOVERZ_SENDTOBACK
이 오버레이를 오버레이 체인의 뒤로 이동한다.
DDOVERZ_SENDTOFRONT
이 오버레이를 오버레이 체인의 전으로 이동한다.


CONST_DDPALFLAGS

CONST_DDPALFLAGS 열거의 플래그는,PALETTEENTRY 형의 flags 멤버로 사용되어 팔레트 엔트리의 사용 방법을 지정한다.

Enum CONST_DDPALFLAGS
    PC_DEFAULT     = 0
    PC_EXPLICIT    = 2
    PC_NOCOLLAPSE  = 4
    PC_RESERVED    = 1
End Enum
PC_DEFAULT
팔레트 엔트리를, 이하의 플래그에 의해 변경하지 않고 사용한다.
PC_EXPLICIT
논리 팔레트 엔트리의 하위 워드에 의해 하드웨어 팔레트 인덱스를 나타낸다. 어플리케이션은, 이 플래그를 사용해 디스플레이 디바이스 팔레트의 컨텐츠를 표시할 수 있다.
PC_NOCOLLAPSE
색을 시스템 팔레트의 기존의 컬러에 적합하지 않고 , 시스템 팔레트의 미사용의 엔트리에 할당한다. 시스템 팔레트에 미사용의 엔트리가 없는 경우, 보통대로 적합된다. 시스템 팔레트에 할당할 수 있었던 색은, 다른 논리 팔레트의 색과 적합할 수 있다.
PC_RESERVED
팔레트 애니메이션에 사용되는 논리 팔레트 엔트리. 색이 빈번하게 변화하므로, 이 플래그에 의해, 다른 윈도우가 팔레트 엔트리에 색을 적합하지 않게 한다. 미사용의 시스템 팔레트 엔트리가 사용 가능한 경우, 그 엔트리에 색을 할당할 수 있다. 그렇지 않은 경우, 그 색은 애니메이션으로 사용할 수 없다.

주의

타입 라이브러리에서는, 이 열거는 아니고 PALETTEENTRY 의 플래그 멤버를 바이트에 정의하므로, 자동 완료는 사용할 수 없다. 이 열거의 플래그는 flags 멤버에 대해서 유효하고, 동작을 변경하기 위해서 지정할 수 있다.


CONST_DDPCAPSFLAGS

CONST_DDPCAPSFLAGS 열거는,DirectDraw7.CreatePalette 의 flags 파라미터로,DirectDrawPalette.GetCaps 의 반환값으로서 사용된다. 또,DDCAPS 의 lPalCaps 멤버에 의해 팔레트의 능력을 기술하기 위해서 사용된다.

Enum CONST_DDPCAPSFLAGS
    DDPCAPS_1BIT             =  256
    DDPCAPS_2BIT             =  512
    DDPCAPS_4BIT             =    1
    DDPCAPS_8BIT             =    4
    DDPCAPS_8BITENTRIES      =    2
    DDPCAPS_ALLOW256         =   64
    DDPCAPS_ALPHA            = 1024
    DDPCAPS_INITIALIZE       =    8
    DDPCAPS_PRIMARYSURFACE   =   16
    DDPCAPS_PRIMARYSURFACELEFT = 32
    DDPCAPS_VSYNC            =  128
End Enum
DDPCAPS_1BIT
인덱스가 1 비트인 것을 나타낸다. 컬러 테이블에는,2 개의 엔트리가 있다.
DDPCAPS_2BIT
인덱스가 2 비트인 것을 나타낸다. 컬러 테이블에는,4 개의 엔트리가 있다.
DDPCAPS_4BIT
인덱스가 4 비트인 것을 나타낸다. 컬러 테이블에는,16 의 엔트리가 있다.
DDPCAPS_8BIT
인덱스가 8 비트인 것을 나타낸다. 컬러 테이블에는,256 의 엔트리가 있다.
DDPCAPS_8BITENTRIES
인덱스를 8 비트 컬러 인덱스로 지정한다. DDPCAPS_1 BIT, DDPCAPS_2 BIT, 또는 DDPCAPS_4BIT 플래그를 사용하는 경우와 타겟 표면이 8 bpp 의 경우만, 이 플래그는 유효가 된다. 각각의 컬러 엔트리는 1 바이트장이며, 목적지 표면의 8 bpp 팔레트에의 인덱스이다.
DDPCAPS_ALLOW256
이 팔레트는, 정의되는 모든 256 엔트리를 소유할 수 있다.
DDPCAPS_ALPHA
관련지을 수 있었던 PALETTEENTRY 형의 flags 멤버가, 단일의 8 비트 알파값으로서 판단되는 것을 나타낸다. 이 플래그로 생성 되는 팔레트는, DDSCAPS_TEXTURE 능력 플래그로 생성 된 표면인 텍스쳐에 Attach 가능한 한이다.
DDPCAPS_INITIALIZE
폐지되었으므로, 무시된다.
DDPCAPS_PRIMARYSURFACE
프라이머리 표면에 이 팔레트를 Attach 한다. 이 팔레트의 컬러 테이블을 변경 하면, DDPSETPAL_VSYNC 가 지정되어 지원 되지 않는 이상 즉석에서 디스플레이에 영향을 준다.
DDPCAPS_PRIMARYSURFACELEFT
이 팔레트는, 좌안프라이머리 표면에 Attach 된다. 이 팔레트의 컬러 테이블을 변경 하면, DDPSETPAL_VSYNC 가 지정되어 지원 되지 않는 이상 즉석에서 좌안디스플레이에 영향을 준다.
DDPCAPS_VSYNC
이 팔레트는, 모니터의 refresh rate와 동기 하도록(듯이) 수정할 수 있다.


CONST_DDPIXELFORMATFLAGS

CONST_DDPIXELFORMATFLAGS 열거는,DDPIXELFORMAT 형의 lFlags 멤버로 사용되어 옵션 제어 플래그를 지정한다.

Enum CONST_DDPIXELFORMATFLAGS
    DDPF_ALPHA          =      2
    DDPF_ALPHAPIXELS    =      1
    DDPF_ALPHAPREMULT   =  32768
    DDPF_BUMPDUDV       = 524288
    DDPF_BUMPLUMINANCE  = 262144
    DDPF_COMPRESSED     =    128
    DDPF_FOURCC         =      4
    DDPF_LUMINANCE      = 131072
    DDPF_PALETTEINDEXED1 =  2048
    DDPF_PALETTEINDEXED2 =  4096
    DDPF_PALETTEINDEXED4 =     8
    DDPF_PALETTEINDEXED8 =    32
    DDPF_PALETTEINDEXEDTO8 =  16
    DDPF_RGB             =    64
    DDPF_RGBTOYUV        =   256
    DDPF_STENCILBUFFER   = 16384
    DDPF_YUV             =   512
    DDPF_ZBUFFER         =  1024
    DDPF_ZPIXELS         =  8192
End Enum
DDPF_ALPHA
픽셀 포맷은, 알파 전용 표면을 기술한다.
DDPF_ALPHAPIXELS
표면에는, 픽셀 포맷의알파 채널 정보가 있다.
DDPF_ALPHAPREMULT
표면은, 미리 늘린 알파 포맷을 사용한다. 즉, 각각의 픽셀의 색성분은, 알파 성분을 미리 걸 수 있고 있다.
DDPF_BUMPDUDV
픽셀 포맷의 범프 맵 데이터는 유효하다. 범프 맵 정보는,lBumpBitCount,lBumpDuBitMask,lBumpDvBitMask, 및 lBumpLuminanceBitMask 멤버에 있다.
DDPF_BUMPLUMINANCE
픽셀 포맷의 휘도(Luminance) 데이터는 유효하다. 또,lLuminanceBitMask 멤버는, 휘도(Luminance) 전용 또는 휘도(Luminance) 알파 표면에 대한 유효한 휘도(Luminance) 비트를 기술한다.
DDPF_COMPRESSED
표면은 지정된 특정의 포맷으로 픽셀 데이터를 받아, 쓰기 처리중에 그 데이터를 압축한다.
DDPF_FOURCC
lFourCC 멤버는 유효해, 비 RGB 픽셀 포맷을 기술하는 FOURCC 코드를 포함한다.
DDPF_LUMINANCE
픽셀 포맷은, 휘도(Luminance) 전용 또는 휘도(Luminance) 알파 표면을 기술한다.
DDPF_PALETTEINDEXED1
DDPF_PALETTEINDEXED2
DDPF_PALETTEINDEXED4
DDPF_PALETTEINDEXED8
표면은, 1 비트, 2 비트, 4 비트, 또는 8 비트의 색으로 인덱스 되고 있다.
DDPF_PALETTEINDEXEDTO8
표면은, 1 비트, 2 비트, 4 비트의 색을 8 비트 팔레트에 인덱스 하고 있다.
DDPF_RGB
픽셀 포맷형의 RGB 데이터는 유효하다.
DDPF_RGBTOYUV
표면은 RGB 데이터를 받아, 쓰기 처리중에 YUV 데이터에 그 데이터를 변환한다. 쓰기의 데이터의 포맷은, 픽셀 포맷형에 포함된다. DDPF_RGB 플래그가 설정되어 있다.
DDPF_STENCILBUFFER
표면은, Z 버퍼의 각각의 픽셀에 있어서의 스텐실과 깊이 정보를 encode 한다.
DDPF_YUV
픽셀 포맷형의 YUV 데이터는 유효하다.
DDPF_ZBUFFER
픽셀 포맷은, Z 버퍼 전용 표면을 기술한다.
DDPF_ZPIXELS
표면은, 픽셀의 z 정보를 포함한다.


CONST_DDRAW

CONST_DDRAW 열거에는, DirectDraw 전체로 사용되는 정수가 포함된다.

Enum CONST_DDRAW
    DD_ROP_SPACE = 8
End Enum
DD_ROP_SPACE
디폴트의 Win32 라스터 처리.


CONST_DDRAWERR

DirectDraw 의 에러값에 대해서는, 「에러 코드」를 참조할것.


CONST_DDSCLFLAGS

CONST_DDSCLFLAGS 열거는,DirectDraw7.SetCooperativeLevel 열거의 flags 파라미터로 사용되어 어플리케이션의 최상정도 동작을 정의한다.

Enum CONST_DDSCLFLAGS
    DDSCL_ALLOWMODEX       =    64
    DDSCL_ALLOWREBOOT      =     2
    DDSCL_CREATEDEVICEWINDOW = 512
    DDSCL_EXCLUSIVE        =    16
    DDSCL_FULLSCREEN       =     1
    DDSCL_MULTITHREADED    =  1024
    DDSCL_NORMAL           =     8
    DDSCL_NOWINDOWCHANGES  =     4
    DDSCL_SETDEVICEWINDOW  =   256
    DDSCL_SETFOCUSWINDOW   =   128
End Enum
DDSCL_ALLOWMODEX
모드 X 디스플레이 모드의 이용을 허가한다. DDSCL_EXCLUSIVE 와 DDSCL_FULLSCREEN 플러그가 존재하는 경우만, 이 플래그를 사용할 수 있다.
DDSCL_ALLOWREBOOT
배타 (풀 스크린) 모드시에, Ctrl ＋ Alt ＋ Del 의 기능을 허가한다.
DDSCL_CREATEDEVICEWINDOW
이 플래그는, Windows 98 으로 Windows NT 2000 만으로 지원 된다. DirectDraw 가, 이 DirectDraw 오브젝트에 대한 디폴트 디바이스 윈도우를 생성 해, 관리하는 것을 나타낸다. 상세한 것에 대하여는, 「포커스 윈도우와 디바이스 윈도우」를 참조할것.
DDSCL_EXCLUSIVE
배타 레벨을 요구한다. 이 플래그는, DDSCL_FULLSCREEN 플래그와 함께 사용해야 한다.
DDSCL_FULLSCREEN
배타 모드의 소유자가프라이머리 표면 전체에 대해서 책임을 지는 것을 나타낸다. GDI 를 무시할 수 있다. 이 플래그는, DDSCL_EXCLUSIVE 플래그와 함께 사용해야 한다.
DDSCL_MULTITHREADED
multi-thread의 확실한 DirectDraw 동작을 요구한다. 이것에 의해, Direct3D 가 빈번하게 글로벌 위험역을 취득하게 된다.
DDSCL_NORMAL
어플리케이션이, 보통의 Windows 어플리케이션으로서 기능하는 것을 나타낸다. 이 플래그는, DDSCL_ALLOWMODEX, DDSCL_EXCLUSIVE, 또는 DDSCL_FULLSCREEN 플래그와 함께 사용할 수 없다.
DDSCL_NOWINDOWCHANGES
DirectDraw 가, 액티브한 어플리케이션 윈도우를 최소화하거나 restore 할 수 없는 것을 나타낸다.
DDSCL_SETDEVICEWINDOW
이 플래그는, Windows 98 으로 Windows NT 2000 만으로 지원 된다. hdl 파라미터가, 이 DirectDraw 오브젝트에 대한디바이스 윈도우의 윈도우 핸들인 것을 나타낸다. 이 플래그는, DDSCL_SETFOCUSWINDOW 플래그와 함께 사용할 수 없다.
DDSCL_SETFOCUSWINDOW
이 플래그는, Windows 98 으로 Windows NT 2000 만으로 지원 된다. hdl 파라미터가, 이 DirectDraw 오브젝트에 대한포커스 윈도우의 윈도우 핸들인 것을 나타낸다. 이 플래그는, DDSCL_SETDEVICEWINDOW 플래그와 함께 사용할 수 없다.


CONST_DDSDMFLAGS

CONST_DDSDMFLAGS 열거는,DirectDraw7.SetDisplayMode 메소드의 flags 파라미터로 사용되어 디스플레이 디바이스 하드웨어의 모드를 설정한다.

Enum CONST_DDSDMFLAGS
    DDSDM_DEFAULT = 0
    DDSDM_STANDARDVGAMODE = 1
End Enum
DDSDM_DEFAULT
모드 X 대신에 모드 13 을 사용하지 않고 , 모드를 설정한다.
DDSDM_STANDARDVGAMODE
모드 X 의 320×200×8 모드는 아니고, 모드 13 을 설정할 수 있다. 다른 해상도, 비트 깊이, 또는 모드 X 모드로 설정하는 경우는, 이 플래그를 사용하지 않고 파라미터를 0 으로 설정한다.


CONST_DDSGRFLAGS

CONST_DDSGRFLAGS 열거는,DirectDrawGammaControl.SetGammaRamp 메소드의 flags 파라미터로 사용되어 요구되는 감마 calibration를 나타낸다.

Enum CONST_DDSGRFLAGS
    DDSGR_CALIBRATE = 1
    DDSGR_DEFAULT = 0
End Enum
DDSGR_DEFAULT
감마 램프를 디스플레이의 물리적 성질에 따라 calibration 하지 않고 로 설정한다.
DDSGR_CALIBRATE
조절 결과가 모든 시스템상에서 동일하게 되도록(듯이), 구경 측정기가 디스플레이의 물리적 성질에 따라 감마 램프를 조절하도록(듯이) 요구한다. calibration를 필요로 하지 않는 경우는, 이 파라미터를 0 으로 설정한다.


CONST_DDSTEREOCAPSFLAGS

CONST_DDSTEREOCAPSFLAGS 열거는,DDCAPS 형의 lSVCaps 멤버로 사용되어 스테레오 비전 능력을 기술한다.

Enum CONST_DDSTEREOCAPSFLAGS
    DDSVCAPS_ENIGMA  = 1
    DDSVCAPS_FLICKER = 2
    DDSVCAPS_REDBLUE = 4
    DDSVCAPS_SPLIT   = 8
    DDSVCAPS_STEREOSEQUENTIAL = 16
End Enum
DDSVCAPS_ENIGMA
불가사의 코딩에 의해, 스테레오 뷰를 실현하고 있는 것을 나타낸다.
DDSVCAPS_FLICKER
고주파 플릭커에 의해, 스테레오 뷰를 실현하고 있는 것을 나타낸다.
DDSVCAPS_REDBLUE
뷰워로 왼쪽과 오른쪽의 눈에 배치한 빨강과 파랑의 필터로부터 이미지를 보는 것으로, 스테레오 뷰를 실현하고 있는 것을 나타낸다. 모든 이미지는, 이 프로세스의색공간(color space)와 적합하지 않으면 안 된다.
DDSVCAPS_SPLIT
스플리트 스크린 기술에 의해, 스테레오 뷰를 실현하고 있는 것을 나타낸다.
DDSVCAPS_STEREOSEQUENTIAL
드라이버는, 현재의 모드 이외가 적어도 1 개의 모드로 스테레오 뷰를 실현할 수 있다. 어플리케이션은,DirectDraw7.GetDisplayMode 또는 DirectDraw7.GetDisplayModesEnum 를 사용해, 모드마다의 스테레오 정보를 취득할 수 있다.


CONST_DDSURFACECAPS2FLAGS

CONST_DDSURFACECAPS2FLAGS 열거는,DDSCAPS2 형의 lCaps2 멤버로 사용되어 추가의 표면 능력을 기술한다.

Enum CONST_DDSURFACECAPS2FLAGS
    DDSCAPS2_CUBEMAP             = 512
    DDSCAPS2_CUBEMAP_ALLFACES    = 65024
    DDSCAPS2_CUBEMAP_NEGATIVEX   = 2048
    DDSCAPS2_CUBEMAP_NEGATIVEY   = 8192
    DDSCAPS2_CUBEMAP_NEGATIVEZ   = 32768
    DDSCAPS2_CUBEMAP_POSITIVEX   = 1024
    DDSCAPS2_CUBEMAP_POSITIVEY   = 4096
    DDSCAPS2_CUBEMAP_POSITIVEZ   = 16384
    DDSCAPS2_D3DTEXTUREMANAGE    = 131072
    DDSCAPS2_HARDWAREDEINTERLACE = 2
    DDSCAPS2_HINTANTIALIASING    = 256
    DDSCAPS2_HINTDYNAMIC         = 4
    DDSCAPS2_HINTSTATIC          = 8
    DDSCAPS2_MIPMAPSUBLEVEL      = 65536
    DDSCAPS2_OPAQUE              = 128
    DDSCAPS2_STEREOSURFACELEFT   = 524288
    DDSCAPS2_TEXTUREMANAGE       = 16
End Enum
능력 플래그
DDSCAPS2_CUBEMAP
DirectX 7.0 의 신기능. 이 표면이 큐브 환경 맵인 것을 나타낸다.
DDSCAPS2_CUBEMAP_ALLFACES
DirectX 7.0 의 신기능. 이 플래그를 DDSCAPS2_CUBEMAP 플래그와 함께 사용해, 큐브 환경 맵의 6 개의 면을 모두 생성 한다.
DDSCAPS2_CUBEMAP_NEGATIVEX
DirectX 7.0 의 신기능. 이 플래그를 DDSCAPS2_CUBEMAP 플래그와 함께 사용해, 큐브 환경 맵의 부의 x 면을 생성 한다.
DDSCAPS2_CUBEMAP_NEGATIVEY
DirectX 7.0 의 신기능. 이 플래그를 DDSCAPS2_CUBEMAP 플래그와 함께 사용해, 큐브 환경 맵의 부의 y 면을 생성 한다.
DDSCAPS2_CUBEMAP_NEGATIVEZ
DirectX 7.0 의 신기능. 이 플래그를 DDSCAPS2_CUBEMAP 플래그와 함께 사용해, 큐브 환경 맵의 부의 z 면을 생성 한다.
DDSCAPS2_CUBEMAP_POSITIVEX
DirectX 7.0 의 신기능. 이 플래그를 DDSCAPS2_CUBEMAP 플래그와 함께 사용해, 큐브 환경 맵의 정의 x 면을 생성 한다.
DDSCAPS2_CUBEMAP_POSITIVEY
DirectX 7.0 의 신기능. 이 플래그를 DDSCAPS2_CUBEMAP 플래그와 함께 사용해, 큐브 환경 맵의 정의 y 면을 생성 한다.
DDSCAPS2_CUBEMAP_POSITIVEZ
DirectX 7.0 의 신기능. 이 플래그를 DDSCAPS2_CUBEMAP 플래그와 함께 사용해, 큐브 환경 맵의 정의 z 면을 생성 한다.
DDSCAPS2_D3DTEXTUREMANAGE
DirectX 7.0 의 신기능. 텍스쳐가 항상 Direct3D 에 의해 관리되는 것을 나타낸다.
DDSCAPS2_HARDWAREDEINTERLACE
이 표면이, 인터 레이스 방식이 아닌 하드웨어를 사용하는 비디오 포트로부터 데이터를 받는 것을 나타낸다. 이것에 의해, 드라이버는 요구될 가능성이 있는 외부 버퍼에 메모리를 할당할 수가 있다. DDSCAPS_VIDEOPORT 및 DDSCAPS_OVERLAY 플래그도 설정하지 않으면 안 된다.
DDSCAPS2_HINTANTIALIASING
어플리케이션이 에일리어징 제거를 사용하는 것을 나타낸다. DDSCAPS_3DDEVICE 가와 같이 설정되어 있는 경우에만 유효하다.
DDSCAPS2_HINTDYNAMIC
이 표면이 매우 자주(잘) 락 되는 것 (수속 텍스쳐나 다이나믹 라이트 맵등)를 드라이버에 나타낸다. 이 플래그는, 텍스쳐 표면에 대해서만 사용할 수 있다 (DDSCAPS_TEXTURE 플래그는,lCaps2 멤버로 설정한다). 이 플래그는, DDSCAPS2_HINTSTATIC 또는 DDSCAPS2_OPAQUE 플래그와 함께 사용할 수 없다.
DDSCAPS2_HINTSTATIC
이 표면이, 로드에 의해 다시 정리되거나 다시 타일 표시할 수 있는 것을 드라이버에 나타낸다. 이 처리에서는, 텍스쳐의 사이즈를 변경할 수 없다. 어플리케이션은 이러한 비트를 잠그는 경우가 있으므로, 상대적으로 빨리, 좌우 대칭이다 (이 처리 때에 퍼포먼스가 저하하는 경우가 있다). 이 플래그는, 텍스쳐 표면에 대해서만 사용할 수 있다 (DDSCAPS_TEXTURE 플래그는,lCaps2 멤버로 설정한다). 이 플래그는, DDSCAPS2_HINTDYNAMIC 또는 DDSCAPS2_OPAQUE 플래그와 함께 사용할 수 없다.
DDSCAPS2_MIPMAPSUBLEVEL
DirectX 7.0 의 신기능. 루트 표면에 복수의 밉맵 표면이 Attach 되고 있는 큐브 맵등의 표면 원가요소에 대해서,EnumAttachedSurfaces 는 아니고 GetAttachedSurface 를 사용할 수 있다. GetAttachedSurface 의 호출로, 최상정도 표면과 Attach 된 밉맵 레벨을 구별할 수 있도록(듯이), 밉맵 큐브 맵의 최상정도 레벨 이외의 표면에는 모두 이 플래그를 설정할 필요가 있다. CreateSurface 에서는 이 플래그를 무시한다.
DDSCAPS2_OPAQUE
이 표면이, 결코 재락 되지 않는 것을 드라이버에 나타낸다. 드라이버는, 재타일 표시나 실제의 압축에 의해 이 표면을 자유롭게 최적화할 수 있다. 이러한 표면은 락 되거나 블리트 처리로 사용 되거나 할 수 없다. 이 능력으로 표면을 잠그거나 블리트 하려고 하면(자), 실패한다. 이 플래그는, 텍스쳐 표면에 대해서만 사용할 수 있다 (DDSCAPS_TEXTURE 플래그는,lCaps2 멤버로 설정한다). 이 플래그는, DDSCAPS2_HINTDYNAMIC 또는 DDSCAPS2_HINTSTATIC 플래그와 함께 사용할 수 없다.
DDSCAPS2_STEREOSURFACELEFT
DirectX 7.0 의 신기능. 이 표면이, 스테레오 플립핑 체인의 일부인 것을 나타낸다. DirectDraw7.CreateSurface 의 호출시에 이 플래그를 설정 하면, 프라이머리 플립핑 체인의 각 버퍼에 대해서, 스테레오 표면의 페어가 생성 된다. 이 플래그에서는, 복합 플립핑 체인 (백 버퍼를 포함한다)을 생성 해야 한다. 단일 세트의 스테레오 표면은 생성 할 수 없다. DirectDrawSurface7.Flip 메소드를 실행하려면 , 백 버퍼가 필요하다 (적어도 4 개의 표면이 생성되어 있지 않으면 안 된다).

또,DirectDraw7.GetDisplayModesEnum 또는 DirectDraw7.GetDisplayMode 의 호출로 취득된 DDSURFACEDESC2 형에 이 플래그가 설정되어 있는 경우, 그 모드로 스테레오가 지원 되고 있는 것을 나타낸다.

DDSCAPS2_TEXTUREMANAGE
클라이언트가 이 텍스쳐 표면을, 드라이버가 사용 가능한 경우는 드라이버에 의해, 사용 불능인 경우는 Direct3D 직접 모드 (DirectX 7.0 의 신기능)에 의해 관리하는 것을 나타낸다. 이 플래그는, 텍스쳐 표면에 대해서만 사용할 수 있다 (DDSCAPS_TEXTURE 플래그는,lCaps2 멤버로 설정한다). 상세한 것에 대하여는, Direct3D 직접 모드의 「자동 텍스쳐 관리」를 참조할것. 어플리케이션이 Direct3D 보관 유지 모드를 사용하는 경우에는, 이 플래그를 사용하지 않고 , 시스템 메모리에 텍스쳐를 생성 해, 보관 유지 모드로 관리할 수 있도록(듯이) 한다.


CONST_DDSURFACECAPSFLAGS

CONST_DDSURFACECAPSFLAGS 열거는,DDSCAPS2 형의 lCaps 멤버로 사용되어 표면의 능력을 기술한다.

Enum CONST_DDSURFACECAPSFLAGS
    DDSCAPS_3DDEVICE        =        8192
    DDSCAPS_ALLOCONLOAD     =    67108864
    DDSCAPS_ALPHA           =           2
    DDSCAPS_BACKBUFFER      =           4
    DDSCAPS_COMPLEX         =           8
    DDSCAPS_FLIP            =          16
    DDSCAPS_FRONTBUFFER     =          32
    DDSCAPS_HWCODEC         =     1048576
    DDSCAPS_LIVEVIDEO       =      524288
    DDSCAPS_LOCALVIDMEM     =   268435456
    DDSCAPS_MIPMAP          =     4194304
    DDSCAPS_MODEX           =     2097152
    DDSCAPS_NONLOCALVIDMEM  =   536870912
    DDSCAPS_OFFSCREENPLAIN  =          64
    DDSCAPS_OPTIMIZED       = -2147483648
    DDSCAPS_OVERLAY         =         128
    DDSCAPS_OWNDC           =      262144
    DDSCAPS_PALETTE         =         256
    DDSCAPS_PRIMARYSURFACE  =         512
    DDSCAPS_RESERVED2       =     8388608
    DDSCAPS_STANDARDVGAMODE =  1073741824
    DDSCAPS_SYSTEMMEMORY    =        2048
    DDSCAPS_TEXTURE         =        4096
    DDSCAPS_VIDEOMEMORY     =       16384
    DDSCAPS_VIDEOPORT       =   134217728
    DDSCAPS_VISIBLE         =       32768
    DDSCAPS_WRITEONLY       =       65536
    DDSCAPS_ZBUFFER         =      131072
End Enum
DDSCAPS_3DDEVICE
이 표면이, 3D 렌더링에 사용할 수 있는 것을 나타낸다. 어플리케이션은 이 플래그를 사용해, 디바이스가 적절한 heap로부터 할당할 수 있었던오프 스크린 표면이 있는 특정의 heap만을 렌더링 할 수 있는 것을 보증한다. 이 플래그가 heap에 대해서 설정되어 있는 경우, 표면은 그 heap로부터 할당할 수 없다.
DDSCAPS_ALLOCONLOAD
사용하지 않는다. DirectDraw 와 Direct3D 에서는 무시된다.
DDSCAPS_ALPHA
이 표면이, 알파 전용 정보를 포함하는 것을 나타낸다.
DDSCAPS_BACKBUFFER
이 표면이, 표면 플립핑형의백 버퍼인 것을 나타낸다. 보통, 이 능력은, DDSCAPS_FLIP 플래그가 사용될 때 CreateSurface 메소드로 설정된다. DDSCAPS_FRONTBUFFER 표면의 직전의 표면만, 이 능력이 설정된다. 다른 표면은, DDSCAPS_FLIP 플래그의 존재, Attach의 순서, 및 DDSCAPS_FRONTBUFFER 와 DDSCAPS_BACKBUFFER 능력의 결여에 의해,백 버퍼와 식별된다. 이 능력이 CreateSurface 메소드에 보내지면(자), 스탠드얼론 백 버퍼를 생성 한다. 이 메소드의 호출 후, 이 표면은프런트 버퍼, 다른백 버퍼, 또는 그 양쪽 모두에 Attach 할 수가 있어플립핑 표면형이 형성된다. 상세한 것에 대하여는, 「DirectDrawSurface7.AddAttachedSurface 」를 참조할것. DirectDraw 는, 플립핑형의 표면에 있어서의 임의의 수를 지원 한다.
DDSCAPS_COMPLEX
복합 표면이 기술되고 있는 것을 나타낸다. 복합 표면은,1 개(살) 이상의 표면의 생성을 가져온다. 추가 표면은, 루트 표면에 Attach 된다. 복합형은, 단지 루트를 파기하는 것으로 파기할 수 있다.
DDSCAPS_FLIP
이 표면이, 표면 플립핑형의 일부인 것을 나타낸다. 이 능력이 CreateSurface 메소드에게 건네지는 경우,프런트 버퍼와 1 개 이상의백 버퍼를 생성 한다. DirectDraw 는, 프런트 버퍼 표면에 DDSCAPS_FRONTBUFFER 비트, 및 프런트 버퍼 표면에 인접하는 표면에 DDSCAPS_BACKBUFFER 비트를 설정한다. DDSURFACEDESC2 형의 lBackBufferCount 멤버는, 메소드의 호출이 성공하기 위해서(때문에), 적어도 1 으로 설정할 필요가 있다. CreateSurface 메소드로 복수의 표면을 생성 하는 경우, DDSCAPS_COMPLEX 능력을 항상 설정하지 않으면 안 된다.
DDSCAPS_FRONTBUFFER
이 표면이, 표면 플립핑형의프런트 버퍼인 것을 나타낸다. 일반적으로 이 플래그는, DDSCAPS_FLIP 능력을 설정하는 경우에,CreateSurface 메소드로 설정된다. 이 능력이 CreateSurface 메소드에 보내지면(자), 스탠드얼론 프런트 버퍼를 생성 한다. 이 표면에는, DDSCAPS_FLIP 능력이 없다. DirectDrawSurface7.AddAttachedSurface 를 사용해, 다른백 버퍼에 Attach 할 수가 있어 플립핑형을 형성한다.
DDSCAPS_HWCODEC
이 표면이, 하드웨어에 의해 압축이 해제된 스트림을 가질 수가 있는 것을 나타낸다.
DDSCAPS_LIVEVIDEO
이 표면이, 라이브 비디오를 받아들이는 것을 나타낸다.
DDSCAPS_LOCALVIDMEM
이 표면이, 비로컬 비디오 메모리는 아니고, 진정한 로컬 비디오 메모리에 존재하는 것을 나타낸다. 이 플래그를 지정 하면, DDSCAPS_VIDEOMEMORY 도 이와 같이 지정하지 않으면 안 된다. 이 플래그는, DDSCAPS_NONLOCALVIDMEM 플래그와 함께 사용할 수 없다.
DDSCAPS_MIPMAP
이 표면이, 1 레벨의밉맵인 것을 나타낸다. 이 표면을 다른 DDSCAPS_MIPMAP 표면에 Attach 하면,밉맵을 형성할 수 있다. 이것은, 다수의 표면의 생성, 및 DirectDrawSurface7.AddAttachedSurface 메소드의 사용에 의한 Attach에 의해 명시적에 행해지는지, 또는 CreateSurface 메소드의 사용에 의해 은근히 행해진다. 이 능력을 설정하는 경우, DDSCAPS_TEXTURE 도 설정하지 않으면 안 된다.
DDSCAPS_MODEX
이 표면이, 320×200 또는 320×240 의모드 X 표면인 것을 나타낸다.
DDSCAPS_NONLOCALVIDMEM
이 표면이, 진정한 로컬 비디오 메모리는 아니고, 비로컬 비디오 메모리에 존재하는 것을 나타낸다. 이 플래그를 지정 하면, DDSCAPS_VIDEOMEMORY 플래그도 이와 같이 지정하지 않으면 안 된다. 이것은, DDSCAPS_LOCALVIDMEM 플래그와 함께 사용할 수 없다.
DDSCAPS_OFFSCREENPLAIN
이 표면이, 오버레이, 텍스쳐, Z 버퍼, 프런트 버퍼, 백 버퍼, 또는 알파 표면의 어떤 것도 아닌오프 스크린 표면인 것을 나타낸다. 평면 표면을 식별하기 위해서 사용된다.
DDSCAPS_OPTIMIZED
현시점에서는, 이행되어 있지 않다.
DDSCAPS_OVERLAY
이 표면이, 오버레이 표면인 것을 나타낸다. 현재,프라이머리 표면에 오버레이 되고 있는지 어떤지에 의해, 직접적으로 표시될지 어떨지가 정해진다. DDSCAPS_VISIBLE 는, 표면이 현시점에서 오버레이 되고 있는지 어떤지를 결정하기 위해서(때문에) 사용할 수 있다.
DDSCAPS_OWNDC
이 표면이, 장시간에 걸쳐 디바이스 콘텍스트 (DC) 관련인 것을 나타낸다.
DDSCAPS_PALETTE
이 디바이스 드라이버에 의해, 고유의 DirectDrawPalette 오브젝트를 생성 해 이 표면에 Attach 할 수 있는 것을 나타낸다.
DDSCAPS_PRIMARYSURFACE
표면이,프라이머리 표면인 것을 나타낸다. 이 표면이 현재 표시되고 있는 것을 나타낸다.
DDSCAPS_RESERVED2
장래적인 사용을 위해서(때문에) 확보되고 있다.
DDSCAPS_STANDARDVGAMODE
이 표면이 표준 VGA 모드 표면이며, 모드 X 표면이 아닌 것을 나타낸다. 이 플래그는, DDSCAPS_MODEX 플래그의 편성으로 사용할 수 없다.
DDSCAPS_SYSTEMMEMORY
이 표면 메모리가, 시스템 메모리에 할당할 수 있던 것을 나타낸다.
DDSCAPS_TEXTURE
이 표면이, 3D 텍스쳐로서 사용할 수 있는 것을 나타낸다. 다만, 반드시 3D 텍스쳐로서 사용하지 않으면 안 된다고 하는 것은 아니다.
DDSCAPS_VIDEOMEMORY
이 표면이, 디스플레이 메모리에 존재하는 것을 나타낸다.
DDSCAPS_VIDEOPORT
이 표면이, 비디오 포트로부터 데이터를 받아들이는 것을 나타낸다.
DDSCAPS_VISIBLE
이 표면에 대해서 행해지는 변경이, 즉석에서 표시되는 것을 나타낸다. 오버레이 되는 동안의 오버레이나, 텍스쳐 되는 동안의 텍스쳐 맵에 대하는 것과 같이,프라이머리 표면에 대해서 항상 설정된다.
DDSCAPS_WRITEONLY
표면이, 쓰기 전용이 되는 것을 나타낸다. 표면으로부터의 read 액세스가, 일반 보호 (GP) 에러를 발생할 가능성도 있다. 이 표면으로부터의 read 결과는 의미가 없다.
DDSCAPS_ZBUFFER
이 표면이, Z 버퍼인 것을 나타낸다. Z 버퍼에는, 표시되지 않는 정보를 포함한다. 대신에, Z 버퍼에는, 어느 픽셀이 표시되어 어느 픽셀이 표시되지 않는가를 결정하는데 사용하는 비트 깊이 정보를 포함한다.


CONST_DDSURFACEDESCFLAGS

CONST_DDSURFACEDESCFLAGS 열거는,DDSURFACEDESC2 형의 lFlags 멤버로 사용되어DDSURFACEDESC2 목의 멤버가 유효한 데이터를 포함하는지를 지정한다.

Enum CONST_DDSURFACEDESCFLAGS
    DDSD_ALL          = 1047022
    DDSD_ALPHABITDEPTH =    128
    DDSD_BACKBUFFERCOUNT =   32
    DDSD_CAPS         =       1
    DDSD_CKDESTBLT    =   16384
    DDSD_CKDESTOVERLAY =   8192
    DDSD_CKSRCBLT     =   65536
    DDSD_CKSRCOVERLAY =   32768
    DDSD_HEIGHT       =       2
    DDSD_LINEARSIZE   =  524288
    DDSD_LPSURFACE    =    2048
    DDSD_MIPMAPCOUNT  =  131072
    DDSD_PITCH        =       8
    DDSD_PIXELFORMAT  =    4096
    DDSD_REFRESHRATE  =  262144
    DDSD_TEXTURESTAGE = 1048576
    DDSD_WIDTH        =       4
    DDSD_ZBUFFERBITDEPTH =   64
End Enum
DDSD_ALL
모든 입력 멤버가 유효하다.
DDSD_ALPHABITDEPTH
lAlphaBitDepth 멤버는 유효하다.
DDSD_BACKBUFFERCOUNT
lBackBufferCount 멤버는 유효하다.
DDSD_CAPS
ddsCaps 멤버는 유효하다.
DDSD_CKDESTBLT
ddckCKDestBlt 멤버는 유효하다.
DDSD_CKDESTOVERLAY
ddckCKDestOverlay 멤버는 유효하다.
DDSD_CKSRCBLT
ddckCKSrcBlt 멤버는 유효하다.
DDSD_CKSRCOVERLAY
ddckCKSrcOverlay 멤버는 유효하다.
DDSD_HEIGHT
lHeight 멤버는 유효하다.
DDSD_LINEARSIZE
사용되지 않는다 (DX6 이후에 이행 되는 경우가 있다. lLinearSize 멤버가 유효한 것을 나타낸다).
DDSD_LPSURFACE
lpSurface 멤버는 유효하다.
DDSD_MIPMAPCOUNT
lMipMapCount 멤버는 유효하다.
DDSD_PITCH
lPitch 멤버는 유효하다.
DDSD_PIXELFORMAT
ddpfPixelFormat 멤버는 유효하다.
DDSD_REFRESHRATE
lRefreshRate 멤버는 유효하다.
DDSD_TEXTURESTAGE
lTextureStage 멤버는 유효하다.
DDSD_WIDTH
lWidth 멤버는 유효하다.
DDSD_ZBUFFERBITDEPTH
lZBufferBitDepth 멤버는 유효하다.


CONST_DDWAITVBFLAGS

CONST_DDWAITVBFLAGS 열거는,DirectDraw7.WaitForVerticalBlank 메소드의 flags 파라미터로 사용되어 수직귀선소거의 대기 시간을 지정한다.

Enum CONST_DDWAITVBFLAGS
    DDWAITVB_BLOCKBEGIN      = 1
    DDWAITVB_BLOCKBEGINEVENT = 2
    DDWAITVB_BLOCKEND        = 4
End Enum
DDWAITVB_BLOCKBEGIN
수직귀선소거 간격이 발생했을 때에 돌려준다.
DDWAITVB_BLOCKBEGINEVENT
수직귀선소거가 발생 하면나무의 이벤트 방아쇠. 이 값은, 현시점에서는 지원되어 있지 않다.
DDWAITVB_BLOCKEND
수직귀선소거 간격이 종료해 표시할 경우에 돌려준다.


에러 코드

에러는 부의 값으로 나타내져 짜 합쳐질 것은 없다. 이 항에서는,DirectDraw7 ,DirectDrawSurface7 ,DirectDrawPalette , 및 DirectDrawClipper 오브젝트의 모든 메소드가 돌려줄 가능성이 있는 값의 리스트를 나타낸다. 각각의 메소드가 돌려줄 가능성이 있는 에러 코드의 리스트는, 그 메소드의 기술을 참조할것.

DD_OK
요구는 성공해 완료했다.
DDERR_ALREADYINITIALIZED
오브젝트는 이미 초기화되고 있다.
DDERR_BLTFASTCANTCLIP
DirectDrawClipper 오브젝트가 DirectDrawSurface7.BltFast 메소드의 호출에게 건네지는 전송원표면에 Attach 되고 있다.
DDERR_CANNOTATTACHSURFACE
요구된 표면에는 표면을 Attach 할 수 없다.
DDERR_CANNOTDETACHSURFACE
요구된 표면으로부터 표면의 Attach를 해제할 수 없다.
DDERR_CANTCREATEDC
Windows 는 그 이상의 어떠한 디바이스 콘텍스트 (DC)도 만들 수가 없다. 또는, 표면에 팔레트가 없고, 디스플레이 모드가 인덱스 첨부의 팔레트가 아닌 경우, DC 가 인덱스 첨부 팔레트 표면을 위해서(때문에) 요구되었다 (이 경우, DirectDraw 는 DC 의 고유의 팔레트를 선택할 수 없다).
DDERR_CANTDUPLICATE
프라이머리 표면, 3D 표면, 은근히 만들어지는 표면은 복제할 수 없다.
DDERR_CANTLOCKSURFACE
DCI 지원없이프라이머리 표면의 락을 하려고 했기 때문에, 이 표면에의 액세스가 거부되었다.
DDERR_CANTPAGELOCK
표면의 페이지 락이 실패했다. 페이지 락은 디스플레이 메모리 표면 혹은 에뮬레이트 된프라이머리 표면 위에서는 작용하지 않는다.
DDERR_CANTPAGEUNLOCK
표면의 페이지 락의 해제가 실패했다. 페이지 락의 해제는 디스플레이 메모리 표면 또는 에뮬레이트 된프라이머리 표면상에서는 작용하지 않는다.
DDERR_CLIPPERISUSINGHWND
윈도우 핸들을 이미 모니터 하고 있는 DirectDrawClipper 오브젝트에클립 리스트를 설정하려고 했다.
DDERR_COLORKEYNOTSET
이 처리에 대한전송원컬러 키가 지정되어 있지 않다.
DDERR_CURRENTLYNOTAVAIL
현시점에서는 지원되어 있지 않다.
DDERR_DCALREADYCREATED
디바이스 콘텍스트 (DC)는 이미 이 표면에 대해서 돌려주어지고 있다. 1 표면에 대해 1 개의 DC 밖에 취득할 수 없다.
DDERR_DEVICEDOESNTOWNSURFACE
1 개의 DirectDraw 오브젝트로 생성 된 표면은, 다른 DirectDraw 디바이스로 직접 사용할 수 없다.
DDERR_DIRECTDRAWALREADYCREATED
이 드라이버를 나타내는 DirectDraw 오브젝트가, 이 프로세스로 이미 생성 되고 있는 것을 나타낸다.
DDERR_EXCEPTION
요구된 처리를 실행하는 동안에 예외가 발생했다.
DDERR_EXCLUSIVEMODEALREADYSET
이미 배타 모드가 설정되어 있는 것에도 불구하고, 협조 레벨을 설정하려고 했다.
DDERR_EXPIRED
데이터가 종료했으므로, 유효하지 않게 되었다.
DDERR_GENERIC
미정도리의 에러 상태이다.
DDERR_HEIGHTALIGN
제공된 직사각형의 높이는, 필요하게 되는 아라이먼트의 배수는 아니다.
DDERR_HWNDALREADYSET
DirectDraw 협조 레벨 윈도우 핸들이 이미 설정되어 있다. 윈도우 핸들은, 프로세스가 표면 또는 생성 된 팔레트를 보관 유지하고 있는 동안은 리셋 할 수 없다.
DDERR_HWNDSUBCLASSED
DirectDraw 협조 레벨 윈도우 핸들이 서브 클래스화 되고 있기 (위해)때문에, DirectDraw 상태의 restore가 저지되었다.
DDERR_IMPLICITLYCREATED
표면이 은근히 생성 되었기 때문에, 표면을 restore 할 수 없다.
DDERR_INCOMPATIBLEPRIMARY
프라이머리 표면 생성 요구가 기존의 프라이머리 표면과 적합하지 않다.
DDERR_INVALIDCAPS
콜백 함수에게 건네진 1 개 이상의 능력 비트가 부정하다.
DDERR_INVALIDCLIPLIST
DirectDraw 는 제공된클립 리스트를 지원 하지 않는다.
DDERR_INVALIDDIRECTDRAWGUID
Directx7.DirectDrawCreate 함수에게 건네지는 글로벌 유니크 식별자 (GUID)는, 유효한 DirectDraw 드라이버 식별자는 아니다.
DDERR_INVALIDMODE
DirectDraw 는 요구된 모드를 지원 하지 않는다.
DDERR_INVALIDOBJECT
DirectDraw 가 무효인 DirectDraw 오브젝트를 받았다.
DDERR_INVALIDPARAMS
메소드에게 건네진 1 개 이상의 파라미터가 부정하다.
DDERR_INVALIDPIXELFORMAT
지정된 픽셀 포맷이 무효이다.
DDERR_INVALIDPOSITION
목적지의 오버레이의 위치가 부정하다.
DDERR_INVALIDRECT
제공된 직사각형이 무효이다.
DDERR_INVALIDSTREAM
지정된 스트림에 무효인 데이터를 포함한다.
DDERR_INVALIDSURFACETYPE
표면이 잘못한 타입이기 때문에, 요구된 처리를 실행할 수 없었다.
DDERR_LOCKEDSURFACES
1 개(살) 이상의 표면이 락 되고 있다.
DDERR_MOREDATA
지정된 버퍼 사이즈 로 유지할 수 있는 이상의 데이터가 존재한다.
DDERR_NO3D
3D 하드웨어 또는 에뮬레이션이 존재하지 않는다.
DDERR_NOALPHAHW
알파 가속화 하드웨어가 존재하지 않는지, 이용할 수 없다.
DDERR_NOBLTHW
블리트 하드웨어가 존재하지 않는다.
DDERR_NOCLIPLIST
클립 리스트를 이용할 수 없다.
DDERR_NOCLIPPERATTACHED
DirectDrawClipper 오브젝트가 표면 오브젝트에 Attach 할 수 없다.
DDERR_NOCOLORCONVHW
컬러 변환 하드웨어가 존재하지 않는지, 이용할 수 없다.
DDERR_NOCOLORKEY
표면이 현재의컬러 키를 가지고 있지 않다.
DDERR_NOCOLORKEYHW
하드웨어가목적지 컬러 키를 지원 하고 있지 않다.
DDERR_NOCOOPERATIVELEVELSET
DirectDraw7.SetCooperativeLevel 메소드가 불려 가지 않았는데 생성 함수가 불려 갔다.
DDERR_NODC
DC 가 이 표면에 대해서 생성되어 있지 않았다.
DDERR_NODDROPSHW
DirectDraw 라스터 처리 (ROP) 하드웨어를 이용할 수 없다.
DDERR_NODIRECTDRAWHW
하드웨어 전용 DirectDraw object 오브젝트를 생성 할 수 없다. 드라이버는 하드웨어를 지원 하지 않는다.
DDERR_NODIRECTDRAWSUPPORT
현재의 디스플레이 드라이버는 DirectDraw 를 지원 하지 않는다.
DDERR_NOEMULATION
소프트웨어 에뮬레이션을 이용할 수 없다.
DDERR_NOEXCLUSIVEMODE
어플리케이션에 대해서 배타 모드가 요구되었지만, 어플리케이션에는 배타 모드가 없다.
DDERR_NOFLIPHW
표시되는 표면을 플립핑 할 수 없다.
DDERR_NOFOCUSWINDOW
포커스 윈도우가 최초로 설정되지 않고 ,디바이스 윈도우를 설정하거나 생성 하려고 했다.
DDERR_NOGDI
GDI 가 존재하지 않는다.
DDERR_NOHWND
클립퍼 통지가 윈도우 핸들을 필요로 한다, 또는 윈도우 핸들이 협조 레벨 윈도우 핸들로서 미리 설정되어 있지 않다.
DDERR_NOMIPMAPHW
밉맵 대응의텍스쳐 맵핑 하드웨어가 존재하지 않는지, 이용할 수 없다.
DDERR_NOMIRRORHW
미러링 하드웨어가 존재하지 않는지, 이용할 수 없다.
DDERR_NONONLOCALVIDMEM
비로컬 비디오 메모리를 지원 하지 않는 디바이스로부터, 비로컬 비디오 메모리를 할당하려고 했다.
DDERR_NOOPTIMIZEHW
디바이스는, 최적화된 표면을 지원 하지 않는다.
DDERR_NOOVERLAYHW
오버레이 하드웨어가 존재하지 않는지, 이용할 수 없다.
DDERR_NOPALETTEATTACHED
팔레트 오브젝트를 이 표면에 Attach 할 수 없다.
DDERR_NOPALETTEHW
16 색 혹은 256 색의 팔레트에 대한 하드웨어 지원이 없다.
DDERR_NORASTEROPHW
적절한 라스터 처리 하드웨어가 존재하지 않는지, 이용할 수 없다.
DDERR_NOROTATIONHW
회전 하드웨어가 존재하지 않는지, 이용할 수 없다.
DDERR_NOSTEREOHARDWARE
스테레오 하드웨어가 존재하지 않는지, 이용할 수 없다.
DDERR_NOSTRETCHHW
하드웨어가신축(스트레치)를 지원 하고 있지 않다.
DDERR_NOSURFACELEFT
스테레오 표면을 지원 하는 하드웨어가 존재하지 않는다.
DDERR_NOT4BITCOLOR
DirectDrawSurface 오브젝트는, 4 비트색팔레트를 사용하고 있지 않다. 또, 요구된 처리는 4 비트색팔레트를 요구한다.
DDERR_NOT4BITCOLORINDEX
DirectDrawSurface 오브젝트는, 4 비트 컬러 인덱스 팔레트를 사용하고 있지 않다. 또, 요구된 처리는 4 비트 컬러 인덱스 팔레트를 요구한다.
DDERR_NOT8BITCOLOR
DirectDrawSurface 오브젝트는, 8 비트색팔레트를 사용하고 있지 않다. 또, 요구된 처리는 8 비트색팔레트를 요구한다.
DDERR_NOTAOVERLAYSURFACE
비오버레이 표면에 대해서, 오버레이 성분이 불려 갔다.
DDERR_NOTEXTUREHW
텍스쳐 맵핑 하드웨어가 존재하지 않는지, 이용할 수 없다.
DDERR_NOTFLIPPABLE
플립 할 수 없는 표면을 플립 하려고 했다.
DDERR_NOTFOUND
요구된 항목이 발견되지 않았다.
DDERR_NOTINITIALIZED
오브젝트가 초기화되기 전에,CoCreateInstance 로 생성 한 DirectDraw 오브젝트의 인터페이스 메소드를 호출하려고 했다.
DDERR_NOTLOADED
표면은 최적화되고 있지만, 아직 메모리를 할당할 수 있지 않았다.
DDERR_NOTLOCKED
락되어 있지 않은 표면의 락 해제를 했다.
DDERR_NOTPAGELOCKED
미처치의 페이지 락이 없는 표면의 페이지 락의 해제를 했다.
DDERR_NOTPALETTIZED
사용하고 있는 표면은 팔레트 베이스의 표면은 아니다.
DDERR_NOVSYNCHW
하드웨어가 수직귀선소거 동기 처리를 지원 하고 있지 않다.
DDERR_NOZBUFFERHW
하드웨어가 Z 버퍼를 지원 하고 있지 않다.
DDERR_NOZOVERLAYHW
하드웨어가 오버레이의 z 오더링을 지원 하고 있지 않다.
DDERR_OUTOFCAPS
요구된 처리에 필요한 하드웨어를 이미 할당할 수 있고 있다.
DDERR_OUTOFMEMORY
DirectDraw 가 처리를 실시하는데 충분한 메모리가 없다.
DDERR_OUTOFVIDEOMEMORY
DirectDraw 가 처리를 실시하는데 충분한 디스플레이 메모리가 없다.
DDERR_OVERLAPPINGRECTS
전송원직사각형과 목적지 직사각형이 같은 표면상에 있다.
DDERR_OVERLAYCANTCLIP
하드웨어는 클리핑 오버레이를 지원 하지 않는다.
DDERR_OVERLAYCOLORKEYONLYONEACTIVE
오버레이상에 1 개 이상의 유효한컬러 키를 가지려고 했다.
DDERR_OVERLAYNOTVISIBLE
메소드가 표시되지 않는 오버레이로 불려 갔다.
DDERR_PALETTEBUSY
팔레트가 이제(벌써) 1 개의 thread에 의해 락 되고 있기 (위해)때문에, 액세스가 거부되었다.
DDERR_PRIMARYSURFACEALREADYEXISTS
이 처리는 이미프라이머리 표면을 생성 하고 있다.
DDERR_REGIONTOOSMALL
DirectDrawClipper.GetClipList 메소드에게 건네진 영역이 너무 작다.
DDERR_SURFACEALREADYATTACHED
이미 Attach 하고 있는 이제(벌써) 1 개의 표면에 표면을 Attach 하려고 했다.
DDERR_SURFACEALREADYDEPENDENT
이미 다른 표면에 의존하고 있는 표면을 의존 시키려고 했다.
DDERR_SURFACEBUSY
표면이 이제(벌써) 1 개의 thread로 락 되고 있기 (위해)때문에, 표면에의 액세스가 거부되었다.
DDERR_SURFACEISOBSCURED
표면에의 액세스가, 표면이 은폐 되고 있기 (위해)때문에 거부되었다.
DDERR_SURFACELOST
표면 메모리의 부족을 위해, 표면에의 액세스가 거부되었다. 이 표면으로 DirectDrawSurface7.Restore 메소드를 호출하면, 관련지을 수 있었던 메모리를 restore 할 수 있다.
DDERR_SURFACENOTATTACHED
요구된 표면은 Attach 할 수 없다.
DDERR_TOOBIGHEIGHT
DirectDraw 로 요구된 폭이 너무 크다.
DDERR_TOOBIGSIZE
DirectDraw 로 요구된 사이즈가 너무 크다. 다만, 각각의 높이로폭은 유효한 사이즈이다.
DDERR_TOOBIGWIDTH
DirectDraw 로 요구된폭이 너무 크다.
DDERR_UNSUPPORTED
지원 되지 않는 처리였다.
DDERR_UNSUPPORTEDFORMAT
요구된 FOURCC 포맷은, DirectDraw 로 지원되어 있지 않다.
DDERR_UNSUPPORTEDMASK
요구된 픽셀 포맷의 비트 마스크가 DirectDraw 로 지원되어 있지 않다.
DDERR_UNSUPPORTEDMODE
디스플레이는 현재 지원되어 있지 않은 모드이다.
DDERR_VERTICALBLANKINPROGRESS
수직귀선소거기간이다.
DDERR_VIDEONOTACTIVE
비디오 포트가 액티브하지 않다.
DDERR_WASSTILLDRAWING
이 표면으로부터, 또는 표면에의 전회의 블리트 처리가 완료하고 있지 않다.
DDERR_WRONGMODE
다른 모드로 생성 되었기 때문에, 이 표면은 restore 할 수가 없다.
DDERR_XALIGN
제공된 직사각형이 필요하게 되는 범위에 수평 일렬에 늘어놓을 수가 없었다.
E_INVALIDINTERFACE
지정된 인터페이스가 무효인지, 존재하지 않는다.
E_OUTOFMEMORY
메소드를 완료하기 위해서 충분한 빈 용량이 없다.


픽셀 포맷 마스크

이 항에서는, 하드웨어 에뮬레이션 계층 (HEL)이 지원 하는 픽셀 포맷에 대해 설명한다. 이하의 항목에 대해 기술한다.

  • 텍스쳐 맵 포맷
  • 오프 스크린 표면 포맷


텍스쳐 맵 포맷

HEL 는, 광범위의 텍스쳐 맵 포맷을 지원 하고 있다. 이하의 테이블에 이러한 포맷을 나타낸다. 마스크란에는, 픽셀 포맷 플래그와 비트 깊이의 각 집합에 대한 적, 록, 청, 및 알파의 마스크를 나타내고 있다.

픽셀 포맷 플래그 | 비트 깊이 | 마스크
DDPF_RGB | DDPF_PALETTEINDEXED1 | 1 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED1 | DDPF_PALETTEINDEXEDTO8 | 1 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED2 | 2 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED2 | DDPF_PALETTEINDEXEDTO8 | 2 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED4 | 4 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED4 | DDPF_PALETTEINDEXEDTO8 | 4 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED8 | 8 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | 8 | R:0x000000E0 G:0x0000001C B:0x00000003 A:0x00000000
DDPF_RGB | DDPF_ALPHAPIXELS | 16 | R:0x00000F00 G:0x000000F0 B:0x0000000F A:0x0000F000
DDPF_RGB | 16 | R:0x0000F800 G:0x000007E0 B:0x0000001F A:0x00000000
DDPF_RGB | 16 | R:0x0000001F G:0x000007E0 B:0x0000F800 A:0x00000000
DDPF_RGB | 16 | R:0x00007C00 G:0x000003E0 B:0x0000001F A:0x00000000
DDPF_RGB | DDPF_ALPHAPIXELS | 16 | R:0x00007C00 G:0x000003E0 B:0x0000001F A:0x00008000
DDPF_RGB | 24 | R:0x00FF0000 G:0x0000FF00 B:0x000000FF A:0x00000000
DDPF_RGB | 24 | R:0x000000FF G:0x0000FF00 B:0x00FF0000 A:0x00000000
DDPF_RGB | 32 | R:0x00FF0000 G:0x0000FF00 B:0x000000FF A:0x00000000
DDPF_RGB | 32 | R:0x000000FF G:0x0000FF00 B:0x00FF0000 A:0x00000000
DDPF_RGB | DDPF_ALPHAPIXELS | 32 | R:0x00FF0000 G:0x0000FF00 B:0x000000FF A:0xFF000000
DDPF_RGB | DDPF_ALPHAPIXELS | 32 | R:0x000000FF G:0x0000FF00 B:0x00FF0000 A:0xFF000000

HEL 에서는, 이러한 포맷을 시스템 메모리에 생성 할 수가 있다. 3D 액셀러레이트 디스플레이 카드용의 DirectDraw 디바이스 드라이버는, 디스플레이 메모리에 다른 포맷의 텍스쳐를 생성 하는 일도 있다. 그러한 드라이버는, 텍스쳐를 생성 할 수 있는 것을 나타내기 위해서(때문에) DDSCAPS_TEXTURE 플래그를 export 한다.


오프 스크린 표면 포맷

이하의 테이블은, DirectX® 5,0 HEL 가 지원 하는 오프 스크린 표면의 픽셀 포맷을 나타내고 있다. 마스크란에는, 픽셀 포맷 플래그와 비트 깊이의 각 집합에 대한 적, 록, 청, 및 알파의 마스크를 나타내고 있다.

픽셀 포맷 플래그 | 비트 깊이 | 마스크
DDPF_RGB | DDPF_PALETTEINDEXED1 | 1 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED2 | 2 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED4 | 4 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | DDPF_PALETTEINDEXED8 | 8 | R:0x00000000 G:0x00000000 B:0x00000000 A:0x00000000
DDPF_RGB | 16 | R:0x0000F800 G:0x000007E0 B:0x0000001F A:0x00000000
DDPF_RGB | 16 | R:0x00007C00 G:0x000003E0 B:0x0000001F A:0x00000000
DDPF_RGB | 24 | R:0x00FF0000 G:0x0000FF00 B:0x000000FF A:0x00000000
DDPF_RGB | 24 | R:0x000000FF G:0x0000FF00 B:0x00FF0000 A:0x00000000
DDPF_RGB | 32 | R:0x00FF0000 G:0x0000FF00 B:0x000000FF A:0x00000000
DDPF_RGB | 32 | R:0x000000FF G:0x0000FF00 B:0x00FF0000 A:0x00000000
DDPF_RGB | DDPF_ZPIXELS | 32 | R:0x0000F800 G:0x000007E0 B:0x0000001F Z:0xFFFF0000
DDPF_RGB | DDPF_ZPIXELS | 32 | R:0x00007C00 G:0x000003E0 B:0x0000001F Z:0xFFFF0000

광범위한오프 스크린 표면 포맷의 지원 외에, HEL 는 Direct3D 또는 다른 3D 렌더러-에서의 사용을 의도한 표면도 지원 한다.


4 문자 코드 (FOURCC)

DirectDraw 는, 4 문자로부터 완성되는 특별한 코드의 집합을 사용한다. 4 문자 코드 또는 FOURCC 라고도 불리는 이러한 코드는, 비트 맵 이미지, 사운드, 비디오등의 멀티미디어 데이터를 포함한 파일에의 헤더 파일에 저장 되고 있다. FOURCC 는, 멀티미디어 데이터를 생성 하기 위해서 사용된 소프트웨어 기술을 나타내고 있다. 또 은근히, FOURCC 는 데이터 자체의 포맷도 기술하고 있다.

DirectDraw 어플리케이션은, 이미지 컬러나 포맷 변환에 FOURCC 를 사용한다. 포맷이 RGB 가 아닌 표면의 픽셀 포맷을 요구하기 위해서 어플리케이션이 DirectDrawSurface7.GetPixelFormat 메소드를 호출하면, 메소드가 돌아갈 때 DDPIXELFORMAT 형의 lFourCC 멤버는 FOURCC 를 식별한다.

게다가BITMAPINFOHEADER 형의 biCompression 멤버는, 이미지를 압축 또는 복원하기 위해서(때문에) 사용하는 코덱을 나타내기 (위해)때문에, FOURCC 로 설정할 수가 있다.

FOURCC 는, 멀티미디어 소프트웨어 기술의 각 벤더에 의해 마이크로 소프트에 등록되어 있다. 이하의 테이블에, 공통의 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 | 크리에이티브 레버러토리 YUV
FVF1 | Iterated Systems, Inc. | 프랙탈 이론 비디오 프레임
IF09 | Intel Corporation | 인텔 인터 미디 애트 YUV9
IV31 | Intel Corporation | 인디오 3,1
JPEG | Microsoft Corporation | 스티르이메이지 JPEG DIB
MJPG | Microsoft Corporation | 모션 JPEG Dib 포맷
MRLE | Microsoft Corporation | 렌 길이 인코딩
MSVC | Microsoft Corporation | 비디오 1
PHMO | IBM Corporation | 포토 모션
RT21 | Intel Corporation | 인디오 2.1
ULTI | IBM Corporation | 알 티모-숀
V422 | Vitec Multimedia | 24 비트 YUV 4:2:2
V655 | Vitec Multimedia | 16 비트 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


DirectDraw 의 툴과 샘플

여기에서는, DirectX SDK 에 포함되어 있는, DirectDraw 의 사용법 및 DirectDraw 어플리케이션의 개발 지원 기능을 나타내는 샘플 어플리케이션에 대해 설명한다. 설명하는 내용은 이하대로이다.

  • DirectDraw 툴
  • DirectDraw C/C++ 샘플
  • DirectDraw Visual Basic 샘플


DirectDraw 툴

여기에서는, DirectX SDK 에 포함되는 어플리케이션으로, DirectDraw 를 사용하는 어플리케이션을 개발하기 위한 어플리케이션에 대해 설명한다. 설명하는 툴은 이하대로이다.

  • DirectDraw Caps
  • DirectDraw Test
  • DirectX Texture 툴
  • KillHelp


DirectDraw Caps

설명

이 유틸리티에서는, 디바이스의 DirectDraw 능력을 조사해 여러가지 스크린 해상도를 테스트할 수 있다.

패스

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

유저즈 가이드

[Driver] 메뉴 및 [HEL] 메뉴로부터 능력의 리스트를 선택해 표시한다. 체크 박스의 선택을 해제해, 하드웨어 또는 에뮬레이션 계층의 능력을 오프로 한다.

다른 해상도에서의 능력을 체크하려면 , 희망하는 해상도를 더블 클릭 한다. 능력의 다이알로그 박스가 열려 있는 경우는,[Refresh] 를 클릭한다.

프로그램을 종료 하면, 디폴트의 스크린 해상도에 돌아온다.


DirectDraw Test

설명

DirectDraw Test 어플리케이션에서는, 표면의 생성과 조작, 표면간의 블리트, 처리 시간의 체크, 그 외의 테스트를 실행할 수 있다.

패스

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

유저즈 가이드

최초로 [Options] 를 클릭해 디바이스를 선택해, 다음에 [Connect] 를 클릭해 DirectDraw 시스템에 접속한다. [Create] 버튼을 클릭해, 희망하는 능력을 선택해, 1 개(살) 또는 복수의 표면을 생성 한다. 표면의 생성에 실패했을 경우, 메세지 리스트에 에러가 표시되므로 주의 해야 한다.

드롭 다운 리스트로부터 표면을 선택해, 다양한 버튼을 사용해 조작한다. 각종 플래그를 사용해 표면으로부터 다른 표면에 블리트 하려면 ,[Blt] 를 선택한다.

[Timing] 를 클릭해 타이밍 테스트를 실행한다. 테스트를 실행하기 전에 [Set Mode]를 클릭해 다른 해상도를 선택하면, 그 스크린 해상도에서의 처리 속도를 체크할 수 있다.


DirectX Texture 툴

설명

이 툴은, 새로운 DXTn 압축 포맷의 텍스쳐 맵을 생성하기 위한 툴이다. 압축된 텍스쳐의 생성은, 실제로는 그만큼 어렵지는 않고,IDirectDrawSurface7::Blt 메소드에 의해 변환할 수가 있다. 상급의 개발자는, 아마 각자의 필요성에 응한 전용 툴을 생성 하는 것이라고 생각되지만, 이 툴은, 이하와 같이 편리한 기본적 기능을 제공한다.

  • BMP 파일 및 DDS 파일을 연다 (DDS 파일 포맷의 설명에 대해서는, 유저즈 가이드의 대응하는 주제를 참조할것).
  • BMP 파일을 알파 채널로서 연다.
  • 텍스쳐를 DDS 포맷으로 보존한다.
  • 5 종류 모든 DXTn 압축 포맷에의 변환을 지원 한다.
  • 밉맵의 생성을 지원 한다 (박스 필터 사용).
  • 그레이 스케일 이미지로서 또는 유저 선택 가능한 백그라운드 컬러를 사용해, 알파 채널을 비주얼화할 수 있다.
  • 포맷에 의한 이미지 품질의 상위를 간단하게 비주얼 비교할 수 있다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Src\DXTex

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

유저즈 가이드

DirectX Texture 툴은, 멀티 문서 인터페이스를 사용한다. 텍스쳐 맵은 각각 문서이며, 복수의 문서를 동시에 열 수가 있다.

열려 있는 문서 마다, 텍스쳐를 1 개 또는 2 개의 포맷으로 보관 유지할 수가 있다. 예를 들어, 32 비트 ARGB 텍스쳐를 자동적으로 생성 하는 BMP 파일을 임포트 해, 그 텍스쳐를 DXT1 포맷으로 변환하는 것이 가능하다. 문서에는, 양쪽 모두의 포맷으로 이미지가 기억되어 유저는 윈도우내에서 클릭하는지, 또는 [View] 메뉴로부터 [Original] 또는 [New] 를 선택하는 것에 의해, 포맷이 다른 이미지를 플립 할 수가 있다. 이것에 의해, 이미지의 압축에 의한 아티팩트가 발견되기 쉬워져, 이미지의 질을 저하시키지 않고 , 다른 압축 포맷을 시험할 수가 있다.

이 테크닉을 사용하지 않고 ARGB 를 DXT1 로 변환했을 경우, 1 비트를 제외한 모든 알파가 없어진다. 그리고 DXT2 로 변환했다고 해도, 알파 레벨은 2 개 밖에 존재하지 않게 된다. Direct Texture 툴의 시스템에서는, 이 2 번째의 변환은 원의 ARGB 포맷화 라행 깨져 변환된 DXT2 이미지에는, DXT2 가 지원 하는 16 레벨의 알파가 모두 포함된다. 이 이미지를 보존 하면, 원의 포맷은 파기되어 새로운 포맷만이 보존된다.

이 시스템에는, 몇개인가 주의해야 할 점이 있다.

  • 문서가 열리고 나서 포맷의 변환이 전혀 요구되지 않았던 경우, 다른 한쪽의 포맷이 「원의」포맷이 되어, 문서를 보존할 경우에는 그 포맷에 이미지가 기입해진다.
  • 문서가 열리고 나서 포맷의 변환이 요구되었을 경우, 변환된 포맷이 「새로운」포맷이 되어, 문서를 보존 하면 그 포맷에 이미지가 기입해진다.
  • 2 번째의 변환이 요구되었을 경우, 최초의 변환으로 생성 된 「새롭다」포맷이 제 2 의 포맷으로 옮겨진다. 「원의」포맷은 변경되지 않는다.
  • 밉맵의 생성은, 양쪽 모두의 포맷에 동시에 적용된다.
  • 원의 포맷에 복수의 밉맵이 있어 새로운 포맷에의 변환이 요구되었을 경우, 새로운 포맷에도 자동적으로 복수의 밉맵이 존재하게 된다.

밉맵을 생성 하려면 ,[Format] 메뉴로부터 [Generate MipMaps] 를 선택한다. 소스 이미지의 높이 및 폭은, 2 의 거듭제곱이 아니면 안 된다. 필터링은, 단순한 박스 필터로 실행된다. 즉, 가장 가까운 4 개의 픽셀이 평균화되어 목적의 픽셀이 생성 된다.

DirectX Texture 툴은, 텍스쳐에 있어서의 알파를 완전 지원 한다. BMP 파일을 임포트 하면 와, 2 개의 파일이 존재해, 그 다른 한쪽의 파일명이 「_a」로 끝나는 경우 (예 tex.bmp 및 tex_a.bmp), 「_a」로 끝나는 파일이 알파 채널로서 로드 된다. 이 2 번째의 bmp 의 파랑의 채널이 알파 채널에 저장 된다.

문서를 연 후는,[File] 메뉴의 [Open As Alpha Channel] 를 사용해 명시적으로 bmp 파일을 알파 채널로서 로드할 수 있다.

알파 채널을 RGB 채널없이 직접 표시하려면 ,[View] 메뉴로부터 [Alpha Channel Only] 를 선택한다. 알파 채널이 그레이 스케일 이미지로서 표시된다. 알파 채널이 로드되어 있지 않은 경우, 알파 채널은 전역에 걸쳐서 100 퍼센트가 되어 [Alpha Channel Only] 를 선택 하면 이미지가 희게 전부 칠해지므로 주의 해야 한다.

보통의 뷰에서는 알파 채널의 이펙트가 눈에 보이지만, 이것은, 윈도우가 백그라운드 컬러로 전부 칠해지고 있어 알파 채널이 100 퍼센트 미만의 텍스쳐에서는, 그 컬러가 비쳐 보이기 때문이다. 백그라운드 컬러를 변경하려면 ,[View] 메뉴로부터 [Change Background Color] 를 선택한다. 이 선택을 실행해도, 텍스쳐 그 자체, 또는 파일을 보존할 경우에 기입해지는 데이터에는 영향을 주지 않는다.

DXT2 포맷 및 DXT4 포맷에서는, 미리 계산된 알파가 사용된다. 즉, 표면에 저장 되는 적, 초록, 및 파랑의 값에는, 대응하는 알파값이 이미 곱셈되고 있다. DirectDraw 에서는, 미리 계산된 알파가 포함되는 표면으로부터 미리 계산되어 있지 않은 알파가 포함되는 표면에 블리트 할 수 없다. 따라서, 처리에 의해 (Alpha Channel 로서 여는, DXT3 에의 변환 DXT5 에의 변환)는, DXT2 및 DXT4 포맷에서는 실행할 수 없다. DXTn 텍스쳐를 지원 하지 않는 Direct3D 디바이스에서는, 이러한 포맷을 사용한 텍스쳐를 지원 하는 것은 어렵다. 이것은, DirectDraw 에서는 이러한 포맷을 종래의 ARGB 표면에도 블리트를 처리할 수 없기 때문이다 (ARGB 표면에서도 미리 계산된 알파가 사용되고 있는 경우는 블리트 할 수 있지만, 이러한 경우는 보기 드물다). 따라서, 가능하면 DXT2 보다 DXT3 를, DXT4 보다 DXT5 를 사용하는 (분)편이 간단하다.

커멘드 라인 옵션을 사용해, 입력 파일, 출력 파일명, 및 처리 옵션을 DirectX Texture 툴에 건네줄 수가 있다. 출력 파일명을 지정하면, 그 출력 파일을 기입한 후에 프로그램이 자동 종료해, 유저 인터페이스는 표시되지 않는다.

dxtex [infilename] [-a alphaname] [-m] [DXT1|DXT2|DXT3|DXT4|DXT5] [outfilename]
infilename
로드하는 파일명.. bmp 또는 . dds 파일.
-a alphaname
「-a」를 지정했을 경우, 다음의 파라미터가 알파 채널로서 로드하는 bmp 파일명이 된다. 알파 파일명을 지정하지 않았던 경우, 어플리케이션은 infilename_a.bmp 라는 이름의 파일을 찾아, 그 파일이 존재하면 그 파일을 알파 채널로서 사용한다.
-m
이 옵션을 지정했을 경우, 밉맵이 생성된다.
DXT1 | DXT2 | DXT3 | DXT4 | DXT5
압축 포맷을 지정한다. 포맷을 지정하지 않았던 경우, 이미지는 ARGB-8888 가 된다.
outfilename
목적지 파일명을 지정한다. 목적지를 지정하지 않았던 경우, 유저 인터페이스에 의해 현재의 파일이라고 요구되고 있는 처리가 표시된다. outfilename 를 지정했을 경우, 처리된 파일을 보존한 다음에 유저 인터페이스를 제시하지 않고 어플리케이션이 종료한다.

참조

DDS 파일 포맷의 상세 정보에 대해서는, 「Compress 샘플」을 참조할것.


KillHelp

설명

KillHelp 는 Ddhelp.exe 를 슛다운 해, 슛다운 된 Ddhelp.exe 는 Ddraw.dll 를 메모리로부터 언로드한다.

패스

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

유저즈 가이드

이 프로그램은, 디바이스 드라이버 개발자 전용이다.

DirectDraw 어플리케이션에 의해 Ddraw.dll 가 처음으로 로드 되면(자), 그 Ddraw.dll 가 Ddhelp.exe 를 로드한다. Ddhelp.exe 에 의해, DirectDraw 는 적절한 스크린 해상도를 restore 해, 어플리케이션이 실패했을 경우에서도 그 외의 클린 업 태스크를 실행할 수가 있다. KillHelp 는, 시스템을 재스타트 하지 않고 Ddraw.dll, 및 Ddhelp.exe 를 메모리로부터 삭제하는 유일한 방법이다.


DirectDraw C/C++ 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 샘플」을 참조할것.

[C++]

여기에서는, 주로 DirectDraw 컴퍼넌트를 나타내는 것을 의도하고 있는, DirectX SDK 내의 샘플 어플리케이션의 요약을 제공한다. 이하의 샘플 프로그램이 포함되어 있다.

  • DDEnum 샘플
  • DDEx1 샘플
  • DDEx2 샘플
  • DDEx3 샘플
  • DDEx4 샘플
  • DDEx5 샘플
  • DDOverlay 샘플
  • Font 샘플
  • FSWindow 샘플
  • ModeTest 샘플
  • Mosquito 샘플
  • Multimon 샘플
  • Space Donuts 샘플
  • Stretch 샘플
  • Switcher 샘플
  • Wormhole 샘플

DirectX 샘플에는, Microsoft® Visual C++® 프로젝트 워크 스페이스 파일이 포함되지만, 올바르게 컴파일 하려면 , 개발 환경에 다른 설정이 필요하다. 상세 정보에 대해서는, 「DirectX 의 샘플 및 그 외의 DirectX 어플리케이션의 컴파일」을 참조할것.


DDEnum 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 샘플」을 참조할것.

[C++]

설명

이 샘플에서는, 현재의 DirectDraw 디바이스의 열거 방법과IDirectDraw7::GetDeviceIdentifier 메소드를 사용해 정보를 취득하는 방법에 대해 가리킨다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Src\DDEnum

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Bin\DDEnum.exe

유저즈 가이드

이 유저 인터페이스는 단순한 다이알로그 박스이다. 2 개의 버튼 [Prev] 및 [Next] 버튼에 의해, 열거된 전의 디바이스나 다음의 디바이스의 정보를 표시한다. 어플리케이션을 종료하려면 ,[Close] 버튼을 클릭한다.


DDEx1 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 샘플」을 참조할것.

[C++]

설명

DDEx1 에서는, DirectDraw 어플리케이션을 초기화해 실행하는데 필요한 태스크를 나타낸다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Src\Ddex1

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Bin\Ddex1.exe

유저즈 가이드

DDEx1 에서는, 유저 입력의 필요는 없다. 프로그램을 종료하려면 , F12 키 또는 ESC 키를 누른다.

프로그래밍 위에의 주의

이 프로그램에서는, DirectDraw 의 초기화 방법 및 DirectDraw 표면의 생성 방법을 나타낸다. 백 버퍼를 생성 해, 프런트 및 백 버퍼의 내용을 교대로 표시하는 페이지 플립핑을 사용한다. 또, 다른 테크닉으로서 컬러 필과 DirectDraw 표면의 GDI 함수의 사용에 대해 가리킨다.


DDEx2 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 샘플」을 참조할것.

[C++]

설명

DDEx2 는, 비트 맵을 추가한 DDEx1 프로그램의 확장이다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Src\Ddex2

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Bin\Ddex2.exe

유저즈 가이드

DDEx2 에서는, 유저 입력의 필요는 없다. 프로그램을 종료하려면 , F12 키 또는 ESC 키를 누른다.

프로그래밍 위에의 주의

DDEx2 에서는, 팔레트화 비디오 모드의 설정 방법법에 대해 가리킨다. DDutil.cpp 의 루틴은 비트 맵 파일을 로드해, DirectDraw 표면에 그 비트 맵을 카피한다.


DDEx3 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 샘플」을 참조할것.

[C++]

설명

DDEx3 프로그램은,DDEx2 의 확장이다. 이 예에서는, 오프 스크린 표면의 사용에 대해 가리킨다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Src\Ddex3

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Bin\Ddex3.exe

유저즈 가이드

DDEx3 에서는, 유저 입력의 필요는 없다. 프로그램을 종료하려면 , F12 키 또는 ESC 키를 누른다.

이 프로그램에서는, 적어도 1.2 MB 의 비디오 RAM 가 필요하다.

프로그래밍 위에의 주의

프런트 및 백 버퍼 이외에, 이 프로그램에서는 2 개의 오프 스크린 표면을 생성 해, 생성 한 오프 스크린 표면에 비트 맵을 로드한다. 오프 스크린 표면의 내용을 백 버퍼에 카피하려면 ,IDirectDrawSurface7::BltFast 메소드를 호출한다. 이 백 버퍼는, 프레임 마다 소스 표면을 바꾼다. 백 버퍼에 비트 맵을 블리트 한 후, DDEx3 에서는 프런트 및 백 버퍼에 플립 한다.


DDEx4 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 샘플」을 참조할것.

[C++]

설명

DDEx4 프로그램은,DDEx3 의 확장이다. DDEx4 에서는, 간단한 애니메이션 테크닉을 나타낸다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Src\Ddex4

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Bin\Ddex4.exe

유저즈 가이드

DDEx4 에서는, 유저 입력의 필요는 없다. 프로그램을 종료하려면 , F12 키 또는 ESC 키를 누른다.

이 프로그램에서는, 적어도 1.2 MB 의 비디오 RAM 가 필요하다.

프로그래밍 위에의 주의

DDEx3 과는 달리, DDEx4 프로그램에서는 단지 1 개의 오프 스크린 표면을 생성 한다. 그리고, 일련의 애니메이션 이미지를 포함한 비트 맵을 이 표면에 로드한다. 애니메이션을 생성 하려면 , 오프 스크린 표면의 부분을 백 버퍼에 블리트 해, 프런트 및 백 버퍼에 플립 한다.

블리트 루틴에서는, 투과형 백그라운드에서 스프라이트를 생성 하는 전송원컬러 키의 사용을 나타낸다.


DDEx5 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 샘플」을 참조할것.

[C++]

설명

DDEx5 프로그램은,DDEx4 의 확장이다. 이 프로그램에서는, 간단한 팔레트 조작을 나타낸다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Src\Ddex5

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Bin\Ddex5.exe

유저즈 가이드

DDEx4 에서는, 유저 입력의 필요는 없다. 프로그램을 종료하려면 , F12 키 또는 ESC 키를 누른다.

이 프로그램에서는, 적어도 1.2 MB 의 비디오 RAM 가 필요하다.

프로그래밍 위에의 주의

이 프로그램에서는 IDirectDrawPalette::GetEntries 를 사용해 팔레트를 읽어들여, 엔트리의 변경을 실시한 다음에,IDirectDrawPalette::SetEntries 를 사용해 팔레트를 갱신한다.


DDOverlay 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 샘플」을 참조할것.

[C++]

설명

이 샘플 어플리케이션에서는, DirectDraw 윈도우 어플리케이션에 있어서의 오버레이의 사용을 나타낸다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Src\DDovrly

가능 실행 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Bin\Ddovrly.exe

유저즈 가이드

프로그램을 실행하려면 , 오버레이를 지원 하는 하드웨어가 필요하다.

이동, 사이즈 변경, 윈도우의 축소와 restore를 시험해 보는 것. 프로그램을 종료하려면 , ALT+F4 키를 누르는지,[Close] 버튼을 클릭한다.

프로그래밍 위에의 주의

이 프로그램에서는 오버레이 지원을 체크해, 오버레이 표면에 비트 맵을 로드해, Windows 메세지에 응해 오버레이 표면으로부터 윈도우를 갱신한다.


Font 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 샘플」을 참조할것.

[C++]

설명

이 샘플 프로그램에서는, GDI 폰트로부터 생성된 텍스트를 사용해, 비디오 메모리를 직접 잠그어 액세스 하는 방법을 나타낸다. 텍스트를 DirectDrawSurface 에 드로잉(Drawing) 하려면 , 그 밖에 좀 더 뛰어난 방법이 몇개인가 있다. 이 샘플의 포인트는, 직접 비디오 메모리를 잠그어 액세스 하는 방법을 올바르게 가리키는 것에 있다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Src\Font

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Bin\Font.exe

유저즈 가이드

이 프로그램은 Arial 폰트의 텍스트 캐릭터 라인을 반복해 갱신해, 그 캐릭터 라인을 스크린의 주위에서 랜덤에 움직인다. 유저 입력의 필요는 없다. 종료하려면 윈도우를 닫는다.

프로그래밍 위에의 주의

이 프로그램에서는 메모리 디바이스 콘텍스트와 DIB 섹션에 폰트를 생성 해, 그것들을 사용해 GDI 가 드로잉(Drawing) 한 픽셀에의 액세스를 취득한다. 그 후, 텍스트 비트 맵이, 직접 메모리 카피로 프라이머리 표면에 배치된다. 그리고, 투과적 또는 비투과적으로 블리트 되는 오프 스크린 표면 대신에, 간단하게 움직일 수가 있다.


FSWindow 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 샘플」을 참조할것.

[C++]

설명

이 샘플에서는, 어플리케이션으로 DirectDraw 가 풀 스크린 배타 모드로 실행되고 있는 동안에, 다이알로그 박스 또는 윈도우를 호출하는 방법을 나타낸다. 윈도우의 내용으로부터 비트 맵을 생성 해, 그 비트 맵을 디바이스에 블리트 하면, GDI 비대응의 디바이스에서도 검출해 지원 한다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Src\FSWindow

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Bin\FSWindow.exe

유저즈 가이드

복수의 디바이스가 있는 경우, 샘플의 시작과 함께 다이알로그 박스가 표시되어 거기로부터 샘플을 실행하는 디바이스를 선택할 수가 있다. 그 후는 풀 스크린 배타 모드에 바뀌어, 다이알로그 박스와 마우스 커서가 표시된다.

다이알로그 박스를 닫아 마우스 커서를 은폐 하려면 ,[Cancel] 또는 [OK] 버튼을 클릭한다. 다이알로그 박스와 마우스 커서를 한번 더 표시하려면 , F1 키를 누른다. 다이알로그 박스가 표시되지 않게 되면(자), Esc 키를 눌러 프로그램을 종료한다.

프로그래밍 위에의 주의

중요한 코드의 상당수는, Fswindow.cpp 파일내에 있다.

샘플은 다이나믹 컨텐츠 모드를 사용해, 다이알로그 박스가 빈번하게 리프레쉬 되어, 포커스가 있는 컨트롤이나 에디트 필드의 텍스트가 표시되는 스태틱 컨텐츠 모드는 CPU 의 처리 시간이 보다 짧고, 예를 들어 헬프 메세지를 표시하는 pop-up 윈도우에 적절하고 있다.

컨텐츠 윈도우는 어떠한 종류의 윈도우에도 될 수 있는 것을 이해하는 것이 중요하다. 컨텐츠 윈도우는, HTML Help 윈도우나, 초기화된 텍스트를 표시하는 리치 에디트 컨트롤을 갖춘 윈도우로도 된다. 표시하는 윈도우의 형상에 맞추어 변화하는 복잡한 클립 영역이 있기 (위해)때문에, 윈도우에는 정방형의 클립 영역은 필요없다.


ModeTest 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 샘플」을 참조할것.

[C++]

설명

이 예는,IDirectDraw7::StartModeTest 메소드와 IDirectDraw7::EvaluateMode 메소드의 기본적인 사용 방법을 나타낸다. 이러한 메소드를 함께 사용하면, 모니터를 어떤 디스플레이 모드와 refresh rate로 디스플레이 디바이스와 접속하면 표시할 수 있을까를 어플리케이션으로 조사할 수가 있다. 어플리케이션은, 높은 refresh rate를 사용하고 싶을 때에, 이러한 메소드를 사용할 수 있다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Src\ModeTest

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Bin\ModeTest.exe

유저즈 가이드

이 유저 인터페이스는 단순한 다이알로그 박스이다. 최초로 DirectDraw 디스플레이 디바이스를 선택한다. 다음에 좌측의 리스트 박스로부터 1 개 이상의 모드를 선택해,[Test] 를 클릭한다. 디스플레이 모드 마다 테스트가 실행되어 모드가 올바르게 표시되고 있는지 어떤지를 지정할 수 있다. 잘못했을 경우는,[Reset] 를 클릭해 재차 테스트한다. 어플리케이션을 종료하려면 ,[Close] 를 클릭한다.

프로그래밍 위에의 주의

DirectDraw 에서는, 어플리케이션이 건네준 리스트를 바탕으로, 테스트하는 모드의 리스트가 셋업 되어 어플리케이션의 제어에 의해, 모드가 차례로 테스트된다.

어플리케이션은 IDirectDraw7::EvaluateMode 를 계속적으로 호출한다. DirectDraw 에 의해 모드가 설정된다. 어플리케이션으로 실행해야 하는 것은, 사전에 협조 레벨을 설정하는 것, 표면의 로스와 현재의 모드가 올바르게 표시되고 있는지 어떤지를 묻는 인터페이스의 드로잉(Drawing)를 처리하는 것 뿐이다. DirectDraw 이 EvalulateMode 로부터 돌려주는 정보에 의해, 어플리케이션은 위의 설정을 실시하는 시기와 테스트의 정지시기를 알 수 있다.

유저가 모드를 승인 하면, 어플리케이션은 플래그를 EvaluateMode 에 건네주어, DirectDraw 는 그 모드에 적절의 마크를 붙여 다음의 처리하러 진행된다. DirectDraw 에서는 또, 시간이 부족했다고 판단되어 특정의 모드의 테스트가 중단되는 일이 있다.

DirectDraw 에서는, 자동화된 수단에 의해 얻을 수 있는 정보를 활용해 테스트의 처리가 가능한 한 단축되기 (위해)때문에, 어플리케이션은 관계가 있는 모드만을 테스트하면 좋다.


Mosquito 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 샘플」을 참조할것.

[C++]

설명

이 프로그램에서는, 오버레이를 사용하는 DirectDraw 애니메이션을 나타낸다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Src\Mosquito

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Bin\Mosquito.exe

유저즈 가이드

Mosquito 어플리케이션을 실행하려면 , 오버레이를 지원 하는 디스플레이 어댑터가 필요하다. 오버레이를 지원 하는 컴퓨터에서는, 이 프로그램은 스크린상을 나는 큰 모기를 생성 한다. 디스플레이 어댑터 카드가 오버레이의 목적지 컬러 키잉을 지원 하지 않는 경우, 모기의 주위에 나쁜 상태의 검은 직사각형의 배경이 표시된다.

카드에는, 그 외의 특정의 해상도로 충분한 오버레이를 지원 하는 것도 있다. 카드가 DirectDraw 로부터 오버레이를 지원 하는데, Mosquito 프로그램으로 오버레이의 생성이나 표시에 문제가 생기는 경우는, 스크린을 저해상도로 전환하거나 색깊이를 바꾸거나 어플리케이션을 재스타트 해 보는 것.

프로그래밍 위에의 주의

이 프로그램에서는 복잡한 오버레이 표면을 생성 해, 그것을 플립 해 애니메이션 한다.


Multimon 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 샘플」을 참조할것.

[C++]

설명

이 프로그램에서는, 복수의 모니터를 이용하는 어플리케이션의 프로그래밍에 사용할 수 있는 테크닉을 몇개인가 가리킨다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Src\Multimon

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Bin\Multimon.exe

유저즈 가이드

어플리케이션에는, 입력의 필요는 없다. 종료하려면 , 임의의 장소 또는 Esc 키를 누른다.

프로그래밍 위에의 주의

GetMonitorInfo 이나 MonitorFromRect 라고 하는 멀티 모니터 함수를 Windows 95 로 사용하기 위해(때문에), Multimon.h. 파일을 인클루드 할 수가 있다. 또, C 파일 또는 C++ 파일의 1 개로 COMPILE_MULTIMON_STUBS 를 정의하고 나서 Multimon.h 를 인클루드 할 필요가 있다. 이것에 의해, Windows 95 상에서 실행했을 때에, multimon 함수에 의해 적절한 값이 돌려주어진다.

DirectDraw 디바이스를 열거 하면나무는,DirectDrawEnumerate 또는 DirectDrawEnumerateEx . 의 어느쪽이든을 사용할 수가 있다. DirectDrawEnumerateEx 는, DirectX 5.0 및 그 이후가 인스톨 되고 있는 Windows 98 시스템, DirectX 6.0 또는 그 이후가 인스톨 되고 있는 그 외의 시스템으로 사용할 수 있다.

모든 시스템에 DirectDrawEnumerateEx 가 존재 하면은 한정되지 않기 때문에, 이전의 DirectDraw 에서는 개발자가 LoadLibrary 와 GetProcAddress 을 사용해 DirectDrawEnumerateEx 의 유무를 체크해야 하게 설정되어 있었다. DirectX 7.0 에서는 이러한 제한이 없어져 DirectDrawEnumerateEx 를 직접 호출할 수가 있지만, 그렇다면, DirectX 7.0 또는 그 이후가 인스톨되어 있지 않은 경우에 프로그램을 실행할 수 없게 되는 것에 주의 해야 한다. 이 샘플에서는,DirectDrawEnumerateEx 를 이용할 수 없는 경우의 LoadLibrary/GetProcAddress 테크닉의 실행 방법, 및 DirectDrawEnumerate 의 사용 방법을 나타낸다.

풀 스크린의 멀티 모니터 어플리케이션에서는, 포커스 윈도우 및 디바이스 윈도우의 처리가 필요하다. 포커스 윈도우는, 유저 입력 메세지를 받아들여, 디바이스 윈도우는 각 스크린을 커버한다. 이 프로그램은, 이러한 윈도우를 적절히 생성 해 할당하기 (위해)때문에 IDirectDraw7::SetCooperativeLevel 를 호출하는 방법을 나타낸다.

스크린 마다 전용의 DirectDraw 인터페이스를 취득하기 위해(때문에), 어느 DirectDraw 인터페이스로 생성 된 DirectDrawSurfaces 를 다른 DirectDraw 인터페이스로 사용할 수 없다. 이 때문에, 복수 모니터상에서 사용되는 그래픽스를 생성 하려면 , 추가의 태스크가 필요하다.

이 샘플에서는 2 개의 테크닉을 소개한다. 최적인 퍼포먼스를 얻으려면 , 비디오 메모리 표면을 사용할 필요가 있다. 스크린 마다 개별의 비디오 메모리 DirectDrawSurface 를 생성 해야 한다. 시스템 메모리 표면이 필요하게 되는 경우, 또는 바람직한 경우, 스크린 마다 개별의 DirectDrawSurfaces 를 생성 할 필요가 있지만, 동일한 표면 데이터 메모리를 포인트 하도록(듯이) 구성할 수가 있다. The IDirectDrawSurface7::SetSurfaceDesc 메소드는, 이 조작에 사용할 수 있다. 이것을 실행해도 퍼포먼스에 영향은 없지만, 불필요한 시스템 메모리의 소비를 방지할 수가 있다.

IDirectDrawSurface7::Blt 의 호출은, 목적지 표면의 경계의 외측에서 데이터를 쓰기를 실시하면 실패하는 것이 보통이다. 이것을 방지하려면 , 목적지에 클립퍼 오브젝트를 부가한다. 이 샘플에서는, 각 스크린의 클립퍼를 생성 해 프런트 버퍼와 백 버퍼에 부가해, 스프라이트 표면을 어플리케이션에 의해 수동으로 클립 하지 않아도 블리트 할 수 있도록(듯이) 하는 방법을 나타낸다.


Space Donuts 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 샘플」을 참조할것.

[C++]

설명

이 간단한 게임에서는, DirectDraw, DirectInput, 및 DirectSound 의 편성 방법에 대해 가리킨다. 다른 DirectX 컴퍼넌트에 대해서도 가리키지만, 주로 복수의 스프라이트를 애니메이션 하는 방법에 대해 가리킨다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Src\Donuts

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Bin\Donuts.exe

유저즈 가이드

디폴트의 입력은 키보드이지만,[Game] 메뉴로부터 죠이스틱도 선택할 수 있다.

이 게임에서 사용할 수 있는 커멘드는, 오프닝 스크린으로 리스트 된다. 모든 숫자는 숫자 패드 패드로부터 입력한다. "Joy" 는, 죠이스틱 버튼에 대응한다.

키 | 커멘드
Esc,F12 | 종료
4 | 좌회전
6 | 오른쪽 회전
5 (Joy 3) | 정지
8 | 전진
2 | 후퇴
7 (Joy 2) | 순
Space 키 (Joy 1) | 발사
Enter | 게임의 시작
F1 | 후속 잔상 영향의 온/오프의 변환
F3 | 오디오의 온/오프의 변환
F5 | frame rate 표시의 온/오프의 변환
F10 | 메인 메뉴

Space Donuts 의 디폴트 설정은, 256 색으로 640 × 480 이다. 디폴트 이외의 해상도와 픽셀 깊이는, 커멘드 라인으로 지정할 수 있다.

이 게임에서는, 대문자와 소문자의 구별이 있는 이하의 커멘드 라인 스윗치를 사용한다.

e | 하드웨어 가속기는 아니고, 소프트웨어 에뮬레이션을 사용한다.
t | 입력의 필요가 없는 테스트 모드.
x | 스트레스 모드. 설정하는 경우, 정지할 수 없다.
S | 사운드의 온/오프를 바꾼다.

이러한 스윗치의 뒤에, x 해상도, y 해상도, 및 픽셀마다의 비트를 나타내는 3 개의 옵션 숫자가 계속되는 일도 있다. 이하에 예를 나타낸다.

donuts -S 800 600 16

프로그래밍 위에의 주의

이 게임에서는, DirectDraw 가 많은 기능을 나타낸다. 드라이버를 지원 하는 경우, 하드웨어 가속기를 이용한다.

이 프로그램에서는, 1 MB 미만의 비디오 RAM 가 필요하다.

이 어플리케이션의 사운드 코드는, DirectSound API 를 강조하도록(듯이) 고의로 설계되고 있다. DirectSound API 의 효과적인 사용 방법을 나타내고 있는 것은 아니다. 예를 들어, 스크린 위에의 각각의 항목 기호는 다른 사운드 버퍼를 사용한다. Space Donuts 에서는 70 이상의 사운드 버퍼 (복제도 포함한다)를 생성 해, 20 에서 25 의 사운드 버퍼간으로는 언제라도 놀이가 존재할 가능성이 있다.

Dsutil.h 및 Dsutil.c (Sdk\Samples\Misc 디렉토리에 있다)의 헬프 함수를 사용 하면, 사운드를 이행 할 수 있다. 이러한 함수를 사용 하면, 어플리케이션에 재빠르게 한편 간단하게 사운드를 추가할 수 있다.


Stretch 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 샘플」을 참조할것.

[C++]

설명

Stretch 샘플 응용 프로그램에서는, 비트 맵 이미지를 블리트 하는 동안의 신축(스트레치)와 클리핑을 나타낸다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Src\Stretch

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Bin\Stretch.exe

유저즈 가이드

Stretch 는, 8 bpp 를 사용하는 비디오 모드로 실행하지 않으면 안 된다. 다른 비디오 모드에서는 정확하게 동작할 수 없다.

이 프로그램은, 클라이언트 윈도우로 순환하는 빨강의 원환체를 표시한다. [Rotation] 메뉴의 [Stop],[Slow], 및 [Fast] 옵션으로 순환 속도를 제어한다. 윈도우의 사이즈를 변경하려면 ,[Size] 메뉴로부터 항목을 선택하는지, 마우스로 윈도우의 사이즈를 변경한다.

프로그래밍 위에의 주의

Stretch 프로그램 윈도우의 사이즈를 1×1 이외에 변경 하면나무는 항상, DirectDraw 블리트 메소드의 이미지 신축(스트레치) 능력을 사용하고 있다.

프라이머리 표면용의 클립퍼는, 클라이언트 윈도우로 설정된다. 클리핑을 나타내려면 , Stretch 프로그램의 윈도우상에 다른 윈도우를 부분적으로 거듭한다. Stretch 가 비트 맵을 블리트 하면, 다른 윈도우에 위치하는 비트 맵의 부분이 클립 된다.


Switcher 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 샘플」을 참조할것.

[C++]

설명

이 샘플에서는, DirectDraw 의 표준 협조 레벨과 배타 협조 레벨간의 변환 방법에 대해 가리킨다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Src\Switcher

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Bin\Switcher.exe

유저즈 가이드

ALT+ENTER 키를 누르면(자), 풀 스크린과 윈도우 모드간을 교체된다. 프로그램을 종료하려면 , ESC 키를 누른다.

프로그래밍 위에의 주의

일반적 (윈도우) 모드에서는, 이 샘플은 클립퍼를 할당해 마우스 커서를 나타내, 다른 어플리케이션의 포커스 소실에 의한 윈도우 이동, WM_PAINT 메세지, 및 일시 중단을 처리한다. 배타 (풀 스크린) 모드에서는, 블리트는 아니고 페이지 플립핑을 사용해, 장면을 갱신한다.


Wormhole 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 샘플」을 참조할것.

[C++]

설명

이 샘플 프로그램에서는, 팔레트 변경으로 애니메이션 이펙트를 생성 하는 방법에 대해 가리킨다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Src\Wormhole

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\DDraw\Bin\Wormhole.exe

유저즈 가이드

프로그램을 종료하려면 ,F12 키 또는 Esc 키를 누른다.

프로그래밍 위에의 주의

4 색의 4×4 의 디스플레이를 생각한다. 색을 설정 하면 다음과 같이 된다.

여기서, 각 행의 모든 색을 오른쪽으로 순환할 수 있다. 우측의 1 개는 왼쪽에 가린다.

이 순환을 계속하면(자), 오른쪽으로 이동하는 애니메이션 된 행을 취득할 수 있다. (와)과 같이 해, 아래로 향하는 행을 애니메이션 할 수가 있다.

여기서, 팔레트를 16 색에 확장 하면, 동시에 아래와 오른쪽에의 이동을 결합할 수 있다.

오른쪽으로 이동

아래에 이동

우하에 이동

여기서, 이러한 4×4 블록의 구석과 구석에 타일을 쳐, 위의야 게순환시키면(자), 움직이는 새발자국 무늬를 교차시킨 격자뭏� 취득할 수 있다. 벌레가 판 구멍도 이와 같이 생성 할 수 있지만, 15×15 블록 (225색)을 사용해, 평면에서 블록의 구석과 구석에 타일을 치는 대신에, 벌레가 판 구멍의 중앙에서 3-D 수습의 안쪽에 타일을 친다.

이하에 나타내는 코드로, 전술의 15×15 그리드를 사용하는 3-D 의 벌레가 판 구멍을 생성할 수 있다.

// 전태스크
// r,θ, z 를 x, y, x 로 변환해, x, y 를 숨긴다
// 포인트를 플롯 한다
// =-1. 0+(log(2.0*j/DIVS)는, 플롯용의 math eqn 를 설정하는 행
// 자유롭게, 다른 함수도 시험하는 것
// 기둥 좌표. 예를 들어, z=f(r, theta)

#define STRETCH 25
#define PI      3.14159265358979323846
#define XCENTER 160
#define YCENTER 50
#define DIVS    1200
#define SPOKES  2400

void transarray(void)
    {
    float x, y, z;
    int i, j, color;
    for(j=1;j<DIVS+1;j++)
        for(i=0;i<SPOKES;i++)
            {
            z=-1. 0+(log(2.0*j/DIVS));
            x=(320.0*j/DIVS*cos(2*PI*i/SPOKES));
            y=(240.0*j/DIVS*sin(2*PI*i/SPOKES));
            y=y-STRETCH*z;
            x+=XCENTER;
            y+=YCENTER;
            color=((i/8)%15)+15*((j/6)%15)+1;
            if ((x>=0) &&(x<=320) &&(y>=0) &&(y<=200))
                plot((int) x, (int) y, color);
            }
    }

비트 맵을 DirectDraw 표면에 로드한 후에 해야 할것은, 색을 회전시켜,충이 판 구멍을 취득하는 것만으로 있다.


DirectDraw Visual Basic 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 샘플」을 참조할것.

[Visual Basic]

여기에서는, DirectX for Visual Basic 의 DirectDraw 컴퍼넌트를 나타내는 샘플 어플리케이션에 대해 설명한다. 이하의 샘플 프로그램이 포함되어 있다.

  • DDBlend 샘플
  • Fire 샘플

또, SDK 에는, 5 개(살)의 간단한 튜토리얼 어플리케이션도 준비되어 있다. 이러한 튜토리얼에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.


DDBlend 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 샘플」을 참조할것.

[Visual Basic]

설명

DDBlend 샘플에서는, DirectDraw 의 풀 스크린 지원, 표면의 직접 처리, 및 8 비트 팔레트의 스크롤에 대해 설명한다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\DDraw\Src\DDBlend

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\DDraw\Bin\DDBlend.exe

유저즈 가이드

소용돌이 컬러의 원점은, 마우스를 사용해 변경한다. Insert 키를 누르면(자), 스크린 해상도로 전방으로 순환해, Delete 키를 누르면(자) 후방에 순환한다. 입자의 수를 늘리려면 Home 키를 눌러, 입자를 삭제하려면 End 키를 누른다. 불선명함을 증가시키려면 PageUp 키를 눌러, 저하시키려면 PageDown 키를 누른다. 팔레트를 바꾸려면 , 스페이스 키를 누른다.

프로그래밍 위에의 주의

DDBlend 는, DirectX 가 표면 메모리에 직접 액세스 하는 방법을 나타내는 풀 스크린 샘플이다. 또, 8 비트 팔레트의 스크롤과 고속 비디오 모드의 변환 방법도 가리킨다.


Fire 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectDraw C/C++ 샘플」을 참조할것.

[Visual Basic]

설명

Fire 샘플에서는, DirectDraw 를 사용해 비디오 메모리를 직접 조작하는 방법을 나타낸다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\DDraw\Src\Fire

실행 가능 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\DDraw\Bin\Fire.exe

유저즈 가이드

유저 입력의 필요는 없다. Esc 키를 누르면(자) 프로그램이 종료한다.

프로그래밍 위에의 주의

이 샘플에서는,DirectDrawSurface7.GetLockedArray 를 사용해, 디스플레이 메모리를 바이트의 배열 Pict 에 배치한다 (여기서 개별적으로 처리할 수가 있다).


DirectInput

여기에서는, Microsoft® DirectX® API (Application Programming Interface)의 DirectInput® 컴퍼넌트에 대해 설명한다. 이 정보는 다음의 주제로 나누어져 있다.

  • DirectInput 에 대해
  • DirectInput 를 사용하는 이유
  • DirectInput 아키텍쳐
  • DirectInput 의 요점
  • DirectInput 튜토리얼
  • DirectInput 레퍼런스
  • DirectInput 의 툴과 샘플


DirectInput 에 대해

DirectInput 는, 마우스, 키보드, 죠이스틱, 그 외 게임 콘트롤러의 입력 디바이스에 가세해 force feedback (입출력) 디바이스도 지원 하는 API 이다.


DirectInput 를 사용하는 이유

DirectInput 는, Microsoft® Win32® API 가 지원 하고 있지 않는 디바이스에 새로운 서비스를 제공하는 것에 가세해 Microsoft® Windows® 메세지에 의존하지 않고 , 하드웨어 드라이버와 직접 통신하는 것으로써, 입력 데이터에의 액세스를 고속화하고 있다.

DirectInput 를 사용하면(자), 어플리케이션이 백그라운드에 있는 경우에서도, 입력 디바이스에 대한 액세스권을 취득할 수 있다. 또, force feedback외, 모든 타입의 입력 디바이스를 완전하게 지원 하고 있다.

DirectInput 의 확장 서비스와 성능의 개선에 의해, DirectInput 는, Windows 로 동작하는 게임, 시뮬레이션, 및 그 외의 리얼타임 대화형 어플리케이션에 대한 유용한 툴이 되고 있다.


DirectInput 아키텍쳐

여기에서는, DirectInput 의 기본 구조, 및 Windows operating system와 입력 하드웨어에 연계한 동작 방법에 대해 설명한다. 여기서 소개하는 DirectInput 의 요소를 이행 하는 방법에 대해서는, 「DirectInput 의 요점」을 참조할것.

  • DirectInput 아키텍쳐의 개요
  • Windows 와의 통합
  • 휴먼 인터페이스 디바이스


DirectInput 아키텍쳐의 개요

[C++]

DirectInput 의 기본적 아키텍쳐는,IDirectInput7 COM 인터페이스를 지원 하는 DirectInput 오브젝트, 및 데이터를 제공하는 입력 디바이스마다의 오브젝트로 구성된다. 각 디바이스는, 디바이스 오브젝트 인스턴스 또는 단순한 디바이스 오브젝트를 가진다. 이것들은, 키, 버튼, 축등의 개별의 제어 수단 또는 스윗치이다.

주 : 오브젝트라는 말은, 코드 오브젝트를 설명하는데 사용되는 일도 있으면, 입력 디바이스에서의 개별의 제어 수단의 1 개를 설명하는데 사용되는 일도 있다. 여기서 말하는 디바이스 오브젝트는,IDirectInputDevice7 인터페이스를 인스턴스화하는 코드 오브젝트는 아니고, 입력 디바이스의 제어 수단을 나타낸다. 디바이스 총체를 나타내는 코드 오브젝트는, DirectInputDevice 오브젝트라고 부른다.

각각의 DirectInputDevice 오브젝트는, 마우스, 키보드, 또는 죠이스틱등의 입력 디바이스를 나타낸다. 터치 패드 첨부 키보드 등, 실제로는 다른 종류의 입력 디바이스를 조합한 물리 디바이스는, 2 개(살) 또는 그 이상의 DirectInputDevice 오브젝트로서 나타내진다. force feedback 디바이스는, 입력과 출력의 양쪽 모두를 조작하는 1 개의 죠이스틱 오브젝트로서 나타내진다.

DirectInputDevice 오브젝트는,IDirectInputDevice7 인터페이스를 인스턴스화한다.

어플리케이션은, 디바이스상에서 사용 가능한 오브젝트의 수와 타입을 IDirectInputDevice7::EnumObjects 메소드를 사용해 확인한다. 개별의 디바이스 오브젝트는, 코드 오브젝트로서 캡슐화되지 않고 ,DIDEVICEOBJECTINSTANCE 구조체로서 기술된다.

force feedback 이펙트는,IDirectInputEffect 인터페이스에 의해 나타내진다. 이 인터페이스의 각 메소드를 사용해, 이펙트의 생성, 변경, 시작, 및 정지를 실시한다.

모든 DirectInput 인터페이스는, ANSI 판과 Unicode 판으로 사용할 수 있다. 컴파일시에 「UNICODE」가 정의되고 있는 경우는, UNICODE 판이 사용된다.

[Visual Basic]

DirectInput 의 기본적 아키텍쳐는, 어플리케이션이 사용하고 있는 입력 디바이스 마다 1 개의 DirectInput 오브젝트와 DirectInputDevice 오브젝트로 구성된다. DirectInputDevice 오브젝트는, 입력 데이터를 취득하는데 사용된다.

또, 모든 사용 가능한 디바이스는, DirectInput 에 의해 사용되고 있는지 어떤지에 관계없이,DirectInputDeviceInstance 오브젝트로 표현할 수 있다. 이 오브젝트를 사용하는 것으로, 그 디바이스에 관한 다양한 정보를 취득할 수 있다.

각 DirectInputDevice 오브젝트는, 마우스, 키보드, 또는 죠이스틱등의 입력 디바이스를 나타낸다 (이 문서에서는, 죠이스틱이라고 하는 용어에는, 마우스나 키보드 이외의 모든 게임 콘트롤러가 포함된다). 터치 패드 첨부 키보드 등, 실제로는 다른 종류의 입력 디바이스를 조합한 물리 디바이스는, 2 개(살) 또는 그 이상의 DirectInputDevice 오브젝트로서 나타내진다. force feedback 디바이스는, 입력과 출력의 양쪽 모두를 조작하는 1 개의 죠이스틱 오브젝트로서 나타내진다.

각 디바이스는, 키, 버튼, 축등의 개별의 제어 수단 또는 스윗치인 디바이스 오브젝트를 가진다. 각 디바이스 오브젝트는,DirectInputDeviceObjectInstance 클래스의 인스턴스에 의해 표현된다. 이 메소드를 사용하는 것으로, 그 디바이스 오브젝트에 관한 정보를 취득할 수 있다 (다만, 입력 데이터는 항상 DirectInputDevice 로 취득한다).

주 : 오브젝트라는 말은, 코드 오브젝트를 설명하는데 사용되는 일도 있으면, 입력 디바이스에서의 개별의 제어 수단의 1 개를 설명하는데 사용되는 일도 있다. 여기서 말하는 디바이스 오브젝트는,DirectInputDevice 오브젝트는 아니고, 입력 디바이스의 제어 수단을 나타낸다.

디바이스와 디바이스 오브젝트는 열거할 수 있다. 열거 결과의 콜렉션은,DirectInputEnumDevices 오브젝트와 DirectInputEnumDeviceObjects 오브젝트로 나타내진다.


Windows 와의 통합

DirectInput 는 디바이스 드라이버에 직접 움직여 동작하므로, 마우스 메세지와 키보드 메세지는 억제 또는 무시된다. 배타 모드로 마우스를 사용 하면, DirectInput 는 마우스 메세지를 억제한다. 그 결과, Windows 는 표준 커서를 표시할 수 없게 된다.

DirectInput 는, 컨트롤 패널로 유저가 간 마우스와 키보드의 설정도 무시한다.

키보드의 경우, 문자 반복의 설정은, DirectInput 에서는 사용되지 않는다. 버퍼링 데이터를 이용하고 있을 때는, DirectInput 는, 각각의 키의 「밀기」와「떼어 놓아」를 반복 없음의 1 개의 이벤트로서 해석한다. 직접 데이터를 이용하고 있을 때는, DirectInput 가 관여하는 것은 키의 현재의 물리적 상태뿐이어, Windows 로 해석되는 키보드 이벤트에는 관여하지 않는다.

마우스의 경우, DirectInput 는 가속값이나 버튼 기능의 교체등의 컨트롤 패널의 설정을 무시한다. 또, DirectInput 는 직접 마우스 드라이버에 작용해, 윈도우 표시 어플리케이션에 대해서 마우스 데이터를 해석하는 Windows 서브 시스템을 우회도로 한다.

주 : 드라이버 자체의 설정은, DirectInput 에 의해 인식된다. 예를 들어, 유저가 3 개 버튼의 마우스를 가지고 있어, 드라이버 유틸리티 소프트웨어를 사용해 중앙의 버튼에 더블 클릭의 쇼트 컷을 할당하면(자), DirectInput 는, 중앙의 버튼의 1 회의 클릭을 주버튼의 2 회의 클릭으로서 보고한다.

죠이스틱이나 그 외의 게임 디바이스의 경우, DirectInput 는, 컨트롤 패널로 유저가 설정한 calibration를 사용한다.


휴먼 인터페이스 디바이스

휴먼 인터페이스 디바이스 (HID)는, 표준의 USB (Universal Serial Bus) 규격에 속하는 클래스이다. DirectInput 는, HID 에 준거한 디바이스를 완전하게 지원 한다.

HID 디바이스로부터 입수할 수 있는 데이터는, 실질상, 종래의 디바이스로부터 입수할 수 있는 데이터와 같다. 게다가 HID 디바이스는, 출력을 받아들일 수가 있다. 예를 들어, 키보드의 LED 의 온/오프를 바꿀 수가 있다.

HID 디바이스를 문의하는 것으로, DirectInput 는 그 "이용 페이지" 와 "처리 방법" 을 확인할 수 있다. 디바이스의 타입과 서브 타입에 대한 정보를 제공하는 사전 정의된 코드가 있다.

HID 컨트롤은,"콜렉션" 으로 분류된다. 콜렉션은 상자 구조로 할 수 있다.

HID 의 상세한 것에 대하여는,http://www.usb.org 를 참조할것.


DirectInput 의 요점

여기에서는, DirectInput 의 개념과 컴퍼넌트에 대해 구체적인 예를 섞어 소개해, DirectInput 시스템을 어플리케이션에 이행 하는데 필요한 정보를 제공한다. 보다 폭넓은 개요에 대해서는, 「DirectInput 아키텍쳐」를 참조할것.

이하의 테마에 대해 해설한다.

  • DirectInput 의 생성
  • DirectInput 디바이스의 열거
  • DirectInput 디바이스
  • DirectInput 디바이스 데이터
  • force feedback
  • 전의 버젼의 DirectInput 의 설계


DirectInput 의 생성

[C++]

DirectInput 어플리케이션에서는, 반드시 최초로 IDirectInput7 인터페이스를 취득한다. 이것을 가장 간단하게 실시하는 방법은,DirectInputCreateEx 함수를 호출하는 것이다.

단일의 DirectInput 오브젝트를 생성 해, 어플리케이션이 종료할 때까지 릴리즈 해서는 안된다.

[Visual Basic]

DirectInput 어플리케이션에서는, 반드시 최초로 IDirectInput7 오브젝트를 생성 한다. 이것을 실시하려면 ,DirectX7.DirectInputCreate 메소드를 사용한다.

단일의 DirectInput 오브젝트를 생성 해, 어플리케이션이 종료할 때까지 릴리즈 해서는 안된다.


DirectInput 디바이스의 열거

DirectInput 는, 모든 사용 가능한 입력 디바이스를 시스템에 문의해 그것들이 접속되고 있는지 어떤지를 판정해, 그러한 디바이스에 관한 정보를 돌려줄 수가 있다. 이 프로세스를 열거라고 부른다.

[C++]

표준의 키보드나 마우스, 또는 그 양쪽 모두만을 어플리케이션으로 사용하고 있다면, 사용 가능한 입력 디바이스를 열거할 필요는 없다. 「DirectInput 디바이스의 생성」으로 설명하도록(듯이),IDirectInput7::CreateDeviceEx 메소드를 사용할때는, 사전 정의된 글로벌 변수를 사용할 수 있다.

다른 모든 입력 디바이스, 및 복수의 키보드 또는 마우스를 사용하는 시스템에 관해서는, DirectInputDevice 오브젝트를 생성 할 수 있도록(듯이),IDirectInput7::EnumDevices 를 호출해, 적어도 인스턴스 GUID (Globally Unique IDentifier)를 취득할 필요가 있다. 열거해, 사용 가능한 디바이스를 유저가 선택할 수 있도록(듯이) 할 수도 있다.

이하는,IDirectInput7::EnumDevices 메소드 이행의 예이다.

/* lpdi 는, 유효한 IDirectInput7 인터페이스 포인터이다. */

GUID       KeyboardGUID = GUID_SysKeyboard;

lpdi->EnumDevices(DIDEVTYPE_KEYBOARD,
DIEnumDevicesCallback,
&KeyboardGUID,
DIEDFL_ATTACHEDONLY);

1 번째의 파라미터는, 열거해야 할 디바이스의 타입을 지정한다. 타입에 관계없이 모든 디바이스를 열거하고 싶으면, NULL 로 한다. 그 이외는,DIDEVICEINSTANCE 의 레퍼런스에 설명이 있는 DIDEVTYPE_* 값의 1 개를 지정한다.

2 번째의 파라미터는, 열거된 각 디바이스에 대해서 한 번 두개 불려 가는 콜백 함수에의 포인터이다. 이 함수는, 어떠한 이름이라도 좋지만, 여기에서는 플레이스홀더명의 DIEnumDevicesCallback 를 사용한다.

EnumDevices 메소드의 3 번째의 파라미터는, 콜백 함수에 건네주는 임의의 32 비트의 값이다. 이 예에서는,GUID 형의 변수에의 포인터이며, 콜백 함수가 키보드 인스턴스 GUID 를 할당할 수가 있도록(듯이) 건네받는다.

4 번째의 파라미터는, 열거 대상이 전디바이스인가, 또는Attach 되고 있는 디바이스만 (DIEDFL_ALLDEVICES 또는 DIEDFL_ATTACHEDONLY)인지를 지정하는 플래그이다.

어플리케이션이 복수의 입력 디바이스를 사용하고 있는 경우, 열거되었던 대로 디바이스를 초기화하려면 , 콜백 함수를 사용하는 것이 적합하다 (예에 대해서는, 「튜토리얼 3 : 죠이스틱의 사용」을 참조할것). 디바이스의 인스턴스 GUID 를 콜백 함수로부터 취득한다. 여기에서는, 디바이스의 특정의 서브 타입을 검색하거나 디바이스명을 리스트 박스에 추가하거나 하는 등, 다른 처리를 실행할 수도 있다.

이하의 코드는, 확장 키보드의 존재를 체크해, 발견되면 열거를 정지하는 코드의 예이다. 발견된 키보드의 인스턴스 GUID 를 KeyboardGUID 변수 (전의 예의 EnumDevices 의 호출로 pvRef 로서 건네받는다)에 할당한다. 이 변수는, 다음에 IDirectInput7::CreateDeviceEx 를 호출할 때에 사용할 수 있다.

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 번째의 파라미터는, 디바이스의 정보를 저장 하는 구조체를 가리킨다. 이 구조체는, DirectInput 가 자동적으로 생성 한다.

2 번째의 파라미터는,EnumDevices 로부터 건네받은 데이터를 가리킨다. 이 경우는, 변수 KeyboardGUID 에의 포인터이다. 이 변수에는 당초, 디폴트값을 할당할 수 있고 있지만, 디바이스가 열거될 때마다, 새로운 값을 할당할 수 있다. 단일의 키보드에 대해서 어느 인스턴스 GUID 를 사용할까는 실제로는 중요하지 않지만, 위의 코드는, 콜백 함수로부터 인스턴스 GUID 를 취득하는 기법을 구체적으로 가리키고 있다.

이 경우의 반환값은, 검색 대상의 디바이스가 발견되면 열거를 정지해, 그렇지 않으면 속행하는 것을 나타낸다. 열거는, 전디바이스의 열거가 종료 하면 즉시 자동적으로 정지한다.

[Visual Basic]

표준의 키보드나 마우스, 또는 그 양쪽 모두만을 어플리케이션으로 사용하고 있다면, 사용 가능한 입력 디바이스를 열거할 필요는 없다. 「DirectInput 디바이스의 생성」으로 설명하도록(듯이),DirectInput.CreateDevice 메소드를 호출하면나무는, 사전 정의된 GUID 앨리어스(alias)를 사용할 수 있다.

다른 모든 입력 디바이스, 및 복수의 키보드 또는 마우스를 사용하는 시스템에 관해서는,DirectInput.GetDIEnumDevices 를 호출해, 사용 가능한 디바이스의 콜렉션을 생성 한다. 이 메소드는, 디바이스의 콜렉션을 나타내는 DirectInputEnumDevices 오브젝트를 돌려준다. 콜렉션내의 각 디바이스는,DirectInputEnumDevices.GetItem 메소드를 사용하는 것으로써,DirectInputDeviceInstance 오브젝트로서 취득할 수 있다.

비표준 디바이스에 대해서 DirectInputDevice 오브젝트를 생성 하려면 , 미리 DirectInputDeviceInstance.GetGuidInstance 를 호출하는 것으로, 적어도 그 디바이스의 GUID 를 취득할 필요가 있다. 디바이스를 열거해, 특정의 타입이나 서브 타입을 검색하거나 (DirectInputDeviceInstance.GetDevType 를 사용), 유저가 게임 콘트롤러를 선택할 수 있도록(듯이) 리스트 박스에 대입하거나 할 수도 있다.

특정의 능력을 가지는 디바이스를 검색할 수도 있다. 이것을 실시하려면 , 후보가 되는 디바이스의 각각 붙어 DirectInputDevice 오브젝트를 생성 해,DirectInputDevice.GetCapabilities 메소드를 사용해 상세 기능을 조사할 필요가 있다.


DirectInput 디바이스

여기에서는, 마우스, 키보드, 죠이스틱등의 디바이스를 나타내는 코드 오브젝트에 대해 기술한다. 이하의 토픽에 대해 설명한다.

  • 디바이스의 셋업
  • DirectInput 디바이스의 생성
  • 디바이스 능력
  • 협조 레벨
  • 디바이스 오브젝트의 열거
  • 디바이스 데이터 형식
  • 디바이스 프로퍼티
  • 디바이스의 취득
  • 디바이스 변경의 인식

디바이스로부터의 데이터의 취득 및 해석의 방법에 대한 정보는, 「DirectInput 디바이스 데이터」를 참조할것.


디바이스의 셋업

어플리케이션은, 입력을 하는 디바이스 마다 오브젝트를 생성 해야 한다. 그 디바이스를 사용할 수 있도록(듯이), 최저한에서도 데이터 형식의 설정이나 디바이스의 취득등의 준비도 해야 한다. 그 밖에도, 디바이스에 관한 정보의 수집이나 디바이스의 프로퍼티의 변경 등, 독자적인 태스크를 실행하는 일도 있다.

이하의 태스크는, 셋업 순서의 일부이다. 순서안에는 필수의 것도 있으면, 디바이스의 상세 정보를 필요로 하는 경우, 혹은 디폴트값을 변경해야 하는 경우에 한정해 필요한 것도 있다.

  1. DirectInput 디바이스를 생성 한다 (필수). 「DirectInput 디바이스의 생성」을 참조.
  2. 디바이스 능력을 취득한다 (옵션).
  3. 디바이스의 키, 버튼 및 축을 열거한다 (옵션). 「디바이스 오브젝트의 열거」를 참조.
  4. 협조 레벨을 설정한다 (추천).
  5. 디바이스 데이터 형식을 설정한다 (필수).
  6. 디바이스 프로퍼티를 설정한다 (버퍼링 데이터를 취득할 예정이라면, 적어도 버퍼 사이즈를 설정해야 한다).
  7. 데이터를 읽어낼 준비를 할 수 있으면(자), 디바이스를 취득한다 (필수). 「디바이스의 취득」을 참조.


DirectInput 디바이스의 생성

디바이스로부터 입력 데이터를 취득하려면 , 우선 그 디바이스를 나타내는 오브젝트를 생성 해야 한다.

[C++]

IDirectInput7::CreateDeviceEx 메소드를 사용해,IDirectInputDevice7 인터페이스에의 포인터를 취득한다. 그 후, 이 인터페이스의 메소드를 사용해, 디바이스의 조작과 데이터의 취득을 실시한다.

다음의 코드는, 키보드 디바이스를 생성 하는 예이다. lpdi 는 IDirectInput7 인터페이스에의 포인터이다.

LPDIRECTINPUTDEVICE7  lpdiKeyboard;
lpdi->CreateDeviceEx(GUID_SysKeyboard, IID_IDirectInputDevice7,
(void**) &lpdiKeyboard, NULL);

IDirectInput7::CreateDeviceEx 의 최초의 파라미터는 인스턴스 GUID 이며, 인터페이스의 생성 대상 디바이스의 인스턴스를 식별한다. DirectInput 에는, 사전 정의된 2 개의 GUID (GUID_SysMouse 및 GUID_SysKeyboard)가 있어, 각각 시스템 마우스와 시스템키 보드를 나타낸다. 이러한 식별자를 CreateDeviceEx 메소드에 건네줄 수가 있다. CreateDeviceEx 메소드의 파라미터로서 글로벌 변수의 GUID_Joystick 를 사용해서는 안 된다. GUID_Joystick 는 제품 GUID 이며, 인스턴스 GUID 는 아니기 때문에이다.

주 : 워크스테이션에 2 개 이상의 마우스가 있는 경우는, 모든 마우스가 결합되어 시스템 디바이스를 형성한다. 키보드에 대해서도 같이이다.

DirectInput 는, 이 밖에도 주로 테스트에 사용하는 사전 정의된 4 개의 GUID 를 준비해 있다. 이것들은 GUID_SysKeyboardEm, GUID_SysKeyboardEm2, GUID_SysMouseEm, 및 GUID_SysMouseEm2 이다. 이 GUID 의 1 개를 CreateDeviceEx 에 건네주는 것으로, 열거 계층-를 개입시켜, 시스템키 보드나 시스템 마우스에 대한 레벨 1 또는 레벨 2 의 액세스권이 부여된다. 이러한 GUID 는, 항상 시스템 마우스나 시스템키 보드를 나타낸다. 이것들은 GUID_SysKeyboard 및 GUID_SysMouse 의 앨리어스(alias)이며, DIEDFL_INCLUDEALIASES 플래그가 건네받지 않으면,IDirectInput7::EnumDevices 에서는 열거되지 않는다.

시스템 마우스 또는 시스템키 보드 이외의 디바이스의 경우는,IDirectInput7::EnumDevices 로 돌려주어지는 디바이스의 인스턴스 GUID 를 사용한다. 1 개의 디바이스에 대한 인스턴스 GUID 는 항상 동일하다. 열거한 리스트로부터 유저에게 1 개의 디바이스를 선택시켜, 그 GUID 를 구성 파일에 보존해 두면(자), 후의 세션으로 그 GUID 를 다시 사용할 수가 있다.

[Visual Basic]

DirectInput.CreateDevice 메소드를 사용해,DirectInputDevice 오브젝트를 취득한다. 그 후, 이 인터페이스의 메소드를 사용해, 디바이스의 조작과 데이터의 취득을 실시한다.

다음의 코드는, 키보드 디바이스를 생성 하는 예이다. di 는 DirectInput 오브젝트이다.

Dim diDev As DirectInputDevice
Set diDev = di.CreateDevice("GUID_SysKeyboard")

파라미터는 GUID 의 앨리어스(alias)이며, 인터페이스의 생성 대상 디바이스의 인스턴스를 식별한다. DirectInput 에는, 사전 정의된 2 개의 GUID (GUID_SysMouse 및 GUID_SysKeyboard)가 있어, 각각 시스템 마우스와 시스템키 보드를 나타낸다. 이러한 식별자를 CreateDevice 메소드에 건네줄 수가 있다.

주 : 워크스테이션에 2 개 이상의 마우스가 있는 경우는, 모든 마우스가 결합되어 시스템 디바이스를 형성한다. 키보드에 대해서도 같이이다.

시스템 마우스나 시스템키 보드 이외의 디바이스의 경우는,DirectInputDeviceInstance.GetGuidInstance 로부터 취득한 디바이스의 인스턴스 GUID 를 사용한다. 1 개의 디바이스에 대한 인스턴스 GUID 는 항상 동일하다. 열거한 리스트로부터 유저에게 1 개의 디바이스를 선택시켜, 그 GUID 를 구성 파일에 보존해 두면(자), 후의 세션으로 그 GUID 를 다시 사용할 수가 있다.

다음의 샘플 코드는, 어플리케이션이 디바이스를 열거해, 적절한 디바이스 diDevInstance 를 찾아낸 것을 전제로 하고 있다. 이 디바이스를 DirectInputDevice 로서 생성 한다.

Dim guid As String
guid = diDevInstance.GetGuidInstance
Set diDev = di.CreateDevice(guid)

DirectInputDeviceInstance 오브젝트의 취득 방법에 대해서는, 「DirectInput 디바이스의 열거」를 참조할것.


디바이스 능력

디바이스로부터의 입력을 요구하기 전에, 유저가 그 능력을 어느 정도 알아 둘 필요가 있다. 죠이스틱에 시점 하트가 붙어 있을까. 마우스는 유저의 머신에 현재Attach 되고 있을까.

[C++]

그러한 의문점은,IDirectInputDevice7::GetCapabilities 메소드를 호출하는 것으로 해결할 수가 있다. 이 메소드는, 능력에 관한 데이터를 DIDEVCAPS 구조체에 돌려준다. DirectX 외의 유사한 구조체의 경우와 같게, 메소드에 이 구조체를 건네주기 전에,dwSize 멤버를 초기화해 두지 않으면 안 된다.

주 : 처리 속도나 메모리 사용을 최적화하기 위해서, 보다 작은 DIDEVCAPS_DX3 구조체를 이용할 수가 있다.

이하의 코드는, 마우스가 Attach 되고 있는지 어떤지, 및 마우스가 제 3 축 (보통은, 휠)을 가지고 있을지 어떨지를 체크하는 예이다.

//  LPDIRECTINPUTDEVICE7  lpdiMouse;  // 이전에 초기화가 끝난 상태

DIDEVCAPS DIMouseCaps;
HRESULT hr;
BOOLEAN    WheelAvailable;

DIMouseCaps.dwSize = sizeof(DIDEVCAPS);
hr = lpdiMouse->GetCapabilities(&DIMouseCaps);
WheelAvailable = ((DIMouseCaps.dwFlags & DIDC_ATTACHED)
&& (DIMouseCaps.dwAxes > 2));

어느 버튼 또는 축이 존재할지 어떨지를 체크하는 이제(벌써) 1 개의 방법은, 그 오브젝트에 대해서 IDirectInputDevice7::GetObjectInfo 를 호출하는 것이다. 그 호출에 대해 DIERR_OBJECTNOTFOUND 가 되돌아 왔을 경우, 오브젝트는 존재하지 않는다. 이하의 코드에서는, 제 3 축은 아닌으로 해도 z 축이 존재할지 어떨지를 판단한다.

DIDEVICEOBJECTINSTANCE didoi;

didoi.dwSize = sizeof(DIDEVICEOBJECTINSTANCE);
hr = lpdiMouse->GetObjectInfo(&didoi, DIMOFS_Z, DIPH_BYOFFSET);
WheelAvailable = SUCCEEDED(hr);
[Visual Basic]

그러한 의문점은,DirectInputDevice.GetCapabilities 메소드를 호출하는 것으로 해결할 수가 있다. 이 메소드는, 능력에 관한 데이터를 DIDEVCAPS 형에 돌려준다 .

이하의 코드는, 마우스가 Attach 되고 있는지 어떤지, 및 마우스가 제 3 축 (보통은, 휠)을 가지고 있을지 어떨지를 체크하는 예이다.

' diMouse 는, 유효한 DirectInputDevice 오브젝트이다. */

Dim WheelAvailable As Boolean
Dim dicaps as DIDEVCAPS

Call diDev.GetCapabilities(dicaps)
WheelAvailable = ((dicaps.lFlags And DIDC_ATTACHED) _
And (dicaps.lAxes > 2))

어느 버튼 또는 축이 존재할지 어떨지를 체크하는 이제(벌써) 1 개의 방법은, 그 오브젝트에 대해서 DirectInputDevice.GetObjectInfo 를 호출하는 것이다. 그 호출에 대해 DIERR_NOTFOUND 가 되돌아 왔을 경우, 오브젝트는 존재하지 않는다. 이하의 코드에서는, 제 3 축은 아닌으로 해도 z 축이 존재할지 어떨지를 판단한다.

Dim didoi As DirectInputDeviceObjectInstance
On Error GoTo NOTFOUND
Set didoi = diDev.GetObjectInfo(DIMOFS_Z, DIPH_BYOFFSET)
On Error GoTo 0
.
.
.
NOTFOUND:
If Err.Number = DIERR_NOTFOUND Then
MsgBox "No z-axis found. "
End If


협조 레벨

[C++]

디바이스의 협조 레벨은, 어플리케이션간 및 Windows 시스템으로 디바이스를 공유하는 방법을 정의한다. 이하의 예의 같게, 협조 레벨을 설정하려면 IDirectInputDevice7::SetCooperativeLevel 메소드를 사용한다.

/* hwnd 는, 최상정도 윈도우의 핸들이다. */
lpdiDevice->SetCooperativeLevel(hwnd,
        DISCL_NONEXCLUSIVE | DISCL_FOREGROUND)

파라미터는, 그 디바이스에 관련지을 수 있었던 최상정도 윈도우 (일반적으로는, 어플리케이션 윈도우)의 핸들과 1 개 또는 복수의 플래그이다.

[Visual Basic]

디바이스의 협조 레벨은, 어플리케이션간 및 Windows 시스템으로 디바이스를 공유하는 방법을 정의한다. 이하의 예의 같게, 협조 레벨을 설정하려면 DirectInputDevice.SetCooperativeLevel 메소드를 사용한다.

diDevice.SetCooperativeLevel(hWnd,
        DISCL_NONEXCLUSIVE Or DISCL_FOREGROUND)

파라미터는, 디바이스에 관련하는 최상정도 윈도우 (일반적으로는, 어플리케이션 윈도우)의 핸들과 1 개 또는 복수의 플래그이다. 폼의 hWnd 프로퍼티는, 그 폼이 표시될 때까지 유효하게 안 된다. 어플리케이션의 메인 폼의 Load 메소드로 DirectInput 디바이스를 초기화하고 있는 경우, 협조 레벨을 설정하기 전에,Show 메소드를 호출할 필요가 있다.

주 : DirectInput 에는 디폴트 설정이 준비되어 있지만, 협조 레벨은, 명시적으로 설정해야 한다. 이것은, DirectInput 에 윈도우의 핸들을 주기 위한 유일한 방법이니까이다. 이 핸들이 없으면 DirectInput 는, 죠이스틱의 재calibration 등, 윈도우 메세지가 필요한 상황으로 반응할 수가 없게 된다.

유효한 플래그의 편성을 이하의 겉(표)에 나타낸다.

플래그 | 메모
DISCL_NONEXCLUSIVE DISCL_BACKGROUND | 디폴트 설정
DISCL_NONEXCLUSIVE DISCL_FOREGROUND |
DISCL_EXCLUSIVE DISCL_FOREGROUND |
DISCL_EXCLUSIVE DISCL_BACKGROUND | 키보드 또는 마우스에는 무효

[C++]

키보드의 경우는, DISCL_NOWINKEY 와 DISCL_NONEXCLUSIVE 를 동시에 사용할 수도 있다. 이 플래그로 Windows 키를 무효로 하는 것으로, 유저는 부주의로 어플리케이션을 종료하는 것이 없어진다. 배타 모드에서는, Windows 키는 항상 무효이다.

협조 레벨에는 2 개의 원가요소가 있다. 디바이스를 foreground 또는 백그라운드에서 사용하는지, 및 배타 또는 비배타에 사용할까이다.

foreground와 백그라운드

foreground 협조 레벨은, 어플리케이션이 foreground에 있는 경우, 즉, 입력초점을 가지는 경우에 한정해, 입력 디바이스가 사용 가능하게 되는 것을 의미한다. 어플리케이션이 백그라운드로 옮겨지면(자), 입력 디바이스는 자동적으로 릴리즈 될까 사용 불가가 된다.

백그라운드 협조 레벨이란, 실제로는 「foreground와 백그라운드」이다. 백그라운드 협조 레벨의 디바이스는, 어플리케이션으로부터 언제라도 취득해 사용할 수 있다.

보통은, foreground 액세스권만으로 충분할 것이다. 그렇다고 하는 것도, 대부분의 어플리케이션에 있어, 다른 프로그램이 foreground에 있는 경우에 발생하는 입력은 중요하지 않기 때문에이다.

어플리케이션의 개발중에, 조건부 컴파일을 사용해, 디버그용으로 백그라운드 협조 레벨을 설정하는 것은 유용하다. 이것에 의해, 어플리케이션은, 디버그 환경에의 변환으로 백그라운드로 이동할 때마다, 디바이스에의 액세스를 잃는 것이 없어진다.

배타와 비배타

어느 어플리케이션이 디바이스를 배타 레벨로 사용하고 있다고 해도, 다른 어플리케이션이 같은 디바이스로부터 데이터를 취득할 수 없다고 하는 것으로는 되지 않는다. 「배타 레벨로 사용」이란, 다른 어플리케이션이 같은 디바이스를 배타에는 취득할 수 없다고 하는 것을 의미한다.

예를 들어 있는 뮤직 플레이어 어플리케이션의 경우, 어플리케이션은 백그라운드에 있어도, 소형의 리모트 콘트롤 디바이스로부터 입력을 받아들인다. 여기서, 같은 리모트 콘트롤 디바이스로부터의 신호에 응답해, 영화를 재생하는 어플리케이션을 실행 하면 하자. 유저가 [Play] 를 누르면(자) 무엇이 일어날까. 양쪽 모두의 프로그램이 재생을 시작 하게 된다. 이러한 결과를 유저가 바라고 있다고는 생각되지 않는다. 그렇게 되지 않게 하려면 , 각 어플리케이션에 DISCL_EXCLUSIVE 플래그를 설정해, 한 번에 어느 쪽인가의 프로그램 밖에 실행할 수 없게 할 필요가 있다.

force feedback 이펙트를 이용하려면 , 어플리케이션은 디바이스에의 배타 액세스를 할 수 없으면 안 된다.

Windows 자체에는, 마우스에의 배타 액세스가 필요하다. 왜냐하면, 액티브하지 않은 윈도우상에서의 클릭등의 마우스 이벤트를 사용해, 어플리케이션에 디바이스를 강제 릴리즈 시키는 것이 가능하고, 그것이, 입력 버퍼로부터의 데이터의 상실 등, 잠재적으로 유해한 결과를 낳을 가능성이 있기 때문이다. 이 때문에, 어느 어플리케이션이 마우스에 대한 배타 액세스권을 가지고 있으면(자), Windows 에는 일절의 액세스가 용서되지 않는다. 마우스 메세지는 생성되지 않는다. 새로운 부작용으로서 커서가 사라지는 일도 있다.

어느 어플리케이션이 키보드에 대한 배타 액세스권을 가지고 있는 경우, DirectInput 는 일절의 키보드 메세지를 억제한다. 다만, Ctrl+Alt+Del 키 및 Windows 95 나 Windows 98 에서의 Alt+Tab 키는 사용할 수 있다.


디바이스 오브젝트의 열거

디바이스상에서 어느 버튼 또는 축이 사용 가능한가를, 어플리케이션이 확인해야 하는 경우가 있다. 이 확인을 실시하려면 , 디바이스를 열거하는 경우와 거의 같은 방법으로 디바이스 오브젝트를 열거한다.

[C++]

IDirectInputDevice7::EnumObjects 의 기능은,IDirectInputDevice7::GetCapabilities 와 중복되는 곳(중)이 있다. 어느 쪽의 메소드도, 사용 가능한 버튼 또는 축이 몇개 있는지를 확인하는데 사용할 수 있다. 그러나,EnumObjects 는, 특정의 오브젝트의 존재를 체크하는 것보다도, 오히려, 사용 가능한 오브젝트를 모두 카탈로그화하는 것을 목적으로 한 메소드이다. 예를 들어, DirectX SDK 의 샘플 코드중의 DirectInput QuickTest 어플리케이션은,EnumObjects 를 사용해, 선택한 디바이스의 [Object] 페이지상에 리스트를 등록한다.

EnumObjects 메소드에는,IDirectInput7::EnumDevices 등과 같이 콜백 함수가 있어, 각 오브젝트에 대해서 다른 처리를 시킬 수가 있다. 예를 들어, 오브젝트를 리스트에 추가하거나 유저 인터페이스상에 대응하는 항목을 생성 하거나 하는 것이다.

이하의 코드는, 각 오브젝트의 이름을 추출해, 캐릭터 라인 리스트 또는 배열에 추가할 수 있도록(듯이) 하는 예이다. 이 표준 콜백은, 문서에서는 플레이스홀더명 DIEnumDeviceObjectsCallback 로 나타내지고 있지만, 자유롭게 이름을 붙일 수가 있다. 이 함수는, 열거되는 각각 오브젝트에 대해서, 한 번 두개 불려 가는 것에 주의 해야 한다.

char szName[MAX_PATH];

BOOL CALLBACK DIEnumDeviceObjectsCallback(
                      LPCDIDEVICEOBJECTINSTANCE lpddoi,
                      LPVOID pvRef)
{
  lstrcpy(szName, lpddoi->tszName);
// szName 를 리스트 혹은 배열에 추가한다.
  .
  .
  .
return DIENUM_CONTINUE;
}

1 번째의 파라미터는, 오브젝트의 정보를 저장 하는 구조체에의 포인터이다. 이 구조체는, DirectInput 에 의해 자동 생성 된다.

2 번째의 파라미터는,EnumObjects 의 2 번째의 파라미터와 동등한 데이터에 대한 어플리케이션 정의 포인터이다. 이 예에서는, 당파라미터는 사용되어 있지 않다.

이 경우의 반환값은, 열거하는 오브젝트가 존재하는 한 열거가 계속되는 것을 나타낸다.

이하의 코드는,EnumObjects 메소드를 호출해, 콜백 함수를 동작시키는 예이다.

lpdiMouse->EnumObjects(DIEnumDeviceObjectsCallback,
                       NULL, DIDFT_ALL);

1 번째의 파라미터는, 콜백 함수의 주소이다.

2 번째의 파라미터는, 콜백 함수 중(안)에서, 사용 또는 변경하고 싶은 데이터에의 포인터로서 사용할 수 있다. 이 예에서는, 이 파라미터를 사용 자제이므로, NULL 를 건네주고 있다.

3 번째의 파라미터는, 열거안에 포함하는 오브젝트의 타입 (복수가능)을 나타내는 플래그이다. 이 예에서는, 모든 오브젝트를 열거하게 된다. 열거의 범위를 한정하려면 ,IDirectInput7::EnumDevices 에 리스트 되는 것 외의 DIDFT_* 플래그를 1 개 이상 사용하면 좋다

주 : DIDFT_* 플래그의 일부는, 다른 플래그를 조합한 것이다. 예를 들어, DIDFT_AXIS 는, DIDFT_ABSAXIS | DIDFT_RELAXIS 와 동등하다.

[Visual Basic]

DirectInputDevice.GetDeviceObjectsEnum 를 호출하는 것으로, 디바이스 오브젝트를 열거한다. 이것에 의해, 요구한 파라미터에 일치하는 사용 가능한 디바이스 오브젝트의 콜렉션을 나타내는 DirectInputEnumDeviceObjects 클래스의 인스턴스가 돌려주어진다.

이하의 코드는, 디바이스 위에의축을 열거하는 예이다.

' diDev 는 DirectInputDevice 오브젝트이다.

Dim diEnumObjects As DirectInputEnumDeviceObjects
Set diEnumObjects = diDev.GetDeviceObjectsEnum(DIDFT_AXIS)

파라미터는, 열거안에 포함하는 오브젝트의 타입 (복수가능)을 나타내는 플래그이다.

주 : CONST_DIDFTFLAGS 플래그의 일부는, 다른 플래그를 조합한 것이다. 예를 들어, DIDFT_AXIS 는, DIDFT_ABSAXIS OR DIDFT_RELAXIS 와 동등하다.

특정의 디바이스 오브젝트에 관한 정보를 취득하려면 ,DirectInputDeviceObjectInstance 오브젝트의 각 메소드를 호출한다. 이 오브젝트는,DirectInputEnumDeviceObjects.GetItem 를 호출하는 것으로 취득된다. 이용 가능한 디바이스의 정보에는, 디바이스의 이름, 타입, 및 데이터 구조 체내에서의 오프셋(offset)등이 있다.

이하의 코드는, 전례로 열거된 축의 이름을 리스트 하는 예이다.

Dim diDevEnumObjects As DirectInputEnumDeviceObjects
Set diDevEnumObjects = diDev.GetDeviceObjectsEnum(DIDFT_AXIS)

Dim diDevObjInstance As DirectInputDeviceObjectInstance
Dim i As Integer
For i = 1 To diEnumObjects.GetCount
Set diDevObjInstance = diEnumObjects.GetItem(i)
Call List1.AddItem(diDevObjInstance.GetName)
Next i


디바이스 데이터 형식

디바이스의 데이터 형식의 설정은, 디바이스 취득 및 디바이스 사용을 시작하기 전에 실시하는 기본적인 순서이다. 디바이스로부터 직접 데이터 (상태 데이터)를 취득하는 것을 목적으로 하지 않은 경우에서도, 데이터 형식을 설정해야 한다. DirectInput 에서는 많은 메소드로 데이터 형식을 사용해, 특정의 디바이스 오브젝트를 식별한다.

[C++]

디바이스 오브젝트가 사용하는 디바이스와 데이터 배열의 방법은,IDirectInputDevice7::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 멤버를 (예를 들어, 축의 프로퍼티를 변경하기 위해서) 변경할 수 없다. 프로퍼티를 변경하려면 , 데이터 형식을 설정한 다음에, 디바이스를 취득하기 전에,IDirectInputDevice7::SetProperty 를 사용한다.

[Visual Basic]

디바이스 오브젝트가 사용하는 디바이스와 데이터 배열의 방법은,DirectInputDevice.SetCommonDataFormat 메소드와 DirectInputDevice.SetDataFormat 메소드가 DirectInput 에 대해서 지시한다.

마우스, 키보드, 및 DIJOYSTATE 형 또는 DIJOYSTATE2 형으로 기술할 수 있는 입력 데이터를 가지는 그 외의 게임 콘트롤러 등, 표준 디바이스의 경우,SetCommonDataFormat 메소드를 호출해,CONST_DICOMMONDATAFORMATS 열거로부터 정수를 건네주는 것으로, 데이터 형식을 설정할 수 있다. 대부분의 어플리케이션에 있어, 공통의 데이터 형식을 사용하는 것이 바람직하다.

특수 디바이스의 경우는, 데이터 형식의 기술을 SetDataFormat 메소드에 건네줄 필요가 있다. 이하의 코드는, 2 개의 축을 가져 버튼을 가지지 않는 디바이스에, 데이터 형식을 설정하는 예이다. 어느 쪽의 축도, 데이터로서 Long 를 요구한다.

Dim dx As New DirectX7
Dim di As DirectInput
Dim did As DirectInputDevice
Dim fD As DIDATAFORMAT
Dim fDA(1) As DIOBJECTDATAFORMAT

Private Sub Form_Load()
Set di = dx.DirectInputCreate()

Set did = di.CreateDevice("GUID_SysMouse")

fDA(0). lFlags = DIDOI_POLLED
fDA(0). lOfs = 0
fDA(0). lType = DIDFT_RELAXIS
fDA(0). strGuid = "GUID_XAxis"

fDA(1). lFlags = DIDOI_POLLED
fDA(1). lOfs = 4
fDA(1). lType = DIDFT_RELAXIS
fDA(1). strGuid = "GUID_YAxis"

fD.dataSize = 8
fD.lFlags = DIDF_RELAXIS
fD.lObjSize = 4
fD.numObjs = 2

did.SetDataFormat fD, fDA()

End Sub


디바이스 프로퍼티

DirectInput 디바이스의 프로퍼티에는, 데이터 버퍼의 사이즈, 축이 돌려주는 값의 범위와 세분성, 축데이터가 상대인가 절대인가, 및 죠이스틱의 물리적 위치와 보고 데이터간의 관계에 영향을 주는 죠이스틱축의데드 존과포화가 있다. 특수 디바이스는, 이외의 프로퍼티를 가지는 일도 있다.

1 개의 예외 (force feedback 디바이스의 게인 프로퍼티)를 제외해, 프로퍼티는, 디바이스가 릴리즈 된 상태에 있는 경우에 한정해 변경할 수가 있다.

[C++]

IDirectInputDevice7::SetProperty 메소드 또는 IDirectInputDevice7::GetProperty 메소드를 호출하기 전에,DIPROPHEADER 구조체와 데이터의 1 개 이상의 요소로 구성되는 프로퍼티 구조체를 설정할 필요가 있다. 입력 디바이스에는 많은 프로퍼티가 있으므로,SetProperty 는 이러한 프로퍼티를 정의하는 모든 종류의 구조체에 대해서 기능할 수 없으면 안 된다. DIPROPHEADER 구조체의 목적은, 프로퍼티 구조체의 사이즈와 데이터의 해석 방법을 정의하는 것이다.

DirectInput 는, 이하의 사전 정의된 프로퍼티 구조체를 포함한다.

  • DIPROPDWORD 는, 버퍼 사이즈 등 단일의 값을 요구하는 프로퍼티에 대해서,DIPROPHEADER 구조체와 DWORD 데이터 멤버를 포함한 구조체를 정의한다.
  • DIPROPRANGE 는 프로퍼티 범위에 대해서 , 2 개의 값 (최대치와 최소 값)을 요구한다. DIPROPHEADER 구조체와 2 개의 LONG 데이터 멤버로 구성된다.
  • DIPROPGUIDANDPATH 는, DirectInput 로 지원되어 있지 않은 HID 에 대해서 어플리케이션이 조작을 실행할 수 있는, 특수한 프로퍼티 구조체이다. 이 구조체는,DIPROPHEADER 구조체와 GUID, 및 패스를 나타내는 Unicode 캐릭터 라인으로 구성된다.
  • DIPROPSTRING 는, Unicode 캐릭터 라인 프로퍼티이다. 이 구조체는,DIPROPHEADER 구조체와 Unicode 캐릭터 라인으로 구성된다.

SetProperty 의 경우, 프로퍼티 구조체의 데이터 멤버는, 프로그래머가 설정하는 값이다. GetProperty 의 경우는, 현재의 값이 데이터 멤버에 돌려주어진다.

GetProperty 또는 SetProperty 를 호출하기 전에,DIPROPHEADER 구조체를 이하의 값으로 초기화해 두지 않으면 안 된다.

  • 프로퍼티 구조체의 사이즈
  • DIPROPHEADER 구조체 자체의 사이즈
  • 오브젝트 식별자
  • 오브젝트 식별자의 해석 방법을 지시하는 dwHow 멤버

디바이스 전체로부터 프로퍼티를 취득하거나 설정하거나 하는 경우, 오브젝트 식별자 dwObj 는, 제로이며,dwHow 멤버는, DIPH_DEVICE 이다. 1 개의 디바이스 오브젝트 (예를 들어, 특정의 축)에 대해서 프로퍼티를 설정 또는 취득하고 싶은 경우는,dwObj 와 dwHow 의 편성값에 의해, 그 오브젝트가 식별된다. 상세한 것에 대하여는, 「DIPROPHEADER 구조체」를 참조할것.

프로퍼티 구조체의 설정 후, 취득 또는 변경하고 싶은 프로퍼티의 식별자와 함께, 구조체의 헤더의 주소를,GetProperty 또는 SetProperty 에 건네준다.

SetProperty 및 GetProperty 에게 건네지는 프로퍼티를 식별하기 위해서, 이하의 값이 사용된다. 상세한 것에 대하여는, 「IDirectInputDevice7::GetProperty 」를 참조할것.

  • DIPROP_BUFFERSIZE. 「버퍼링 데이터와 직접 데이터」를 참조할것.
  • DIPROP_AXISMODE. 「상대 좌표와 절대 좌표」도 참조할것.
  • DIPROP_CALIBRATIONMODE
  • DIPROP_GRANULARITY
  • DIPROP_FFGAIN
  • DIPROP_FFLOAD
  • DIPROP_AUTOCENTER
  • DIPROP_RANGE
  • DIPROP_DEADZONE
  • DIPROP_SATURATION

마지막 3 개의 프로퍼티에 대한 자세한 것은, 「죠이스틱축데이터의 해석」도 참조할것.

이하의 샘플 코드에서는, 10 개의 데이터 항목을 보관 유지하도록(듯이) 디바이스의 버퍼 사이즈를 설정한다.

DIPROPDWORD  dipdw;
HRESULT      hres;
dipdw.diph.dwSize = sizeof(DIPROPDWORD);
dipdw.diph.dwHeaderSize = sizeof(DIPROPHEADER);
dipdw.diph.dwObj = 0;
dipdw.diph.dwHow = DIPH_DEVICE;
dipdw.dwData = 10;
hres = lpdiDevice->SetProperty(DIPROP_BUFFERSIZE, &dipdw.diph);
[Visual Basic]

DirectInputDevice.SetProperty 메소드 또는 DirectInputDevice.GetProperty 메소드는, 2 개의 파라미터를 취한다. 설정하는 프로퍼티를 식별하는 캐릭터 라인 형식의 GUID 앨리어스(alias)와Any 형의 데이터이다. 이 데이터는, 다음의 어느쪽이든 1 개의 형태로 건네받는다.

  • DIPROPLONG 는, 버퍼 사이즈 등 단일의 값을 요구하는 프로퍼티에 대해서 사용된다. 이 프로퍼티 데이터는, 단일의 Long 값으로 구성된다.
  • DIPROPRANGE 는 프로퍼티 범위에 대해서 , 2 개의 값 (최대치와 최소 값)을 요구한다. 이 프로퍼티 데이터는, 2 개의 Long 데이터 멤버로 구성된다.

SetProperty 의 경우, 프로퍼티형의 데이터 멤버는, 프로그래머가 설정하는 값이다. GetProperty 의 경우는, 현재의 값이 데이터 멤버에 돌려주어진다.

실제의 프로퍼티 데이터에 가세해, 이것들 2 개의 형태에는,lHow,lObj, 및 lSize 의 3 개의 멤버가 포함된다.

lHow 와 lObj 의 값은 연계해 기능한다. lHow 는, 프로퍼티를 설정 또는 취득하는 디바이스 오브젝트를 식별하는데 사용되는 시스템을 나타내,lObj 는 디바이스 오브젝트를 식별한다.

lHow 가 DIPH_BYID 인 경우, 디바이스 오브젝트는,lObj 의 일의인 수치 식별자로 나타내진다. 이 ID 는, 디바이스 오브젝트를 열거한 후에,DirectInputDeviceObjectInstance.GetType 에 의해 돌려주어지는 값으로부터 추출할 수 있다.

대부분의 어플리케이션의 경우, 디바이스 오브젝트를 식별하는 방법으로서 비교적 용이한 것은,DirectInputDevice.SetCommonDataFormat 또는 DirectInputDevice.SetDataFormat 로 확립되는 데이터 구조 체내의 오프셋(offset)를 사용하는 방법이다. 이 경우,lHow 는 DIPH_BYOFFSET 이며,lObj 는 바이트 단위의 오프셋(offset)이다. 키보드, 마우스, 및 DIJOYSTATE 형의 데이터를 받을 수가 있는 임의의 게임 콘트롤러의 경우, 디바이스 오브젝트는 사전 정의된 정수로 식별할 수 있다. 「CONST_DIKEYFLAGS 」, 「CONST_DIMOUSEOFS 」, 및 「CONST_DIJOYSTICKOFS 」를 참조할것.

lHow 멤버도 DIPH_DEVICE 를 포함할 수가 있다. 즉, 프로퍼티의 소속처는 단일의 디바이스 오브젝트는 아니고, 그 디바이스 전체이다. 버퍼 사이즈는 그러한 프로퍼티의 일례이다. lHow 가 DIPH_DEVICE 이면,lObj 는 제로이다.

마지막으로, 프로퍼티 타입의 lSize 멤버는, 그 타입의 사이즈에 초기화할 필요가 있다. GetProperty 나 SetProperty 는, 건네받는 프로퍼티의 타입을 인식하고 있지 않았기 때문에, 이 순서는 반드시 실행해야 한다.

SetProperty 및 GetProperty 에게 건네지는 프로퍼티를 식별하기 위해서, 이하의 캐릭터 라인이 사용된다. 상세한 것에 대하여는, 「DirectInputDevice.GetProperty 」를 참조할것.

  • DIPROP_AXISMODE. 「상대 좌표와 절대 좌표」도 참조할것.
  • DIPROP_BUFFERSIZE. 「버퍼링 데이터와 직접 데이터」를 참조할것.
  • DIPROP_DEADZONE
  • DIPROP_GRANULARITY
  • DIPROP_RANGE
  • DIPROP_SATURATION

무효 존, 범위, 및 포화값의 상세한 것에 대하여는, 「죠이스틱축데이터의 해석」을 참조할것.

이하의 코드는, 디바이스의 버퍼 사이즈를 설정하는 예이다.

' diDev 는, 데이터 형식을 설정 끝난 DirectInputDevice 이다.

Dim diProp As DIPROPLONG
diProp.lHow = DIPH_DEVICE
diProp.lObj = 0
diProp.lData = 10
diProp.lSize = Len(diProp)
Call diDev.SetProperty("DIPROP_BUFFERSIZE", diProp)


디바이스의 취득

DirectInput 디바이스의 취득이란, 어플리케이션에 디바이스에의 액세스를 시키는 것이다. 디바이스가 취득되고 있는 한, DirectInput 는, 어플리케이션이 디바이스의 데이터를 사용할 수 있도록(듯이) 한다. 디바이스가 취득되어 있지 않은 경우, 디바이스의 특성에 대한 조작은 할 수 있지만, 데이터는 일절 취득할 수 없다.

취득은 영속 하는 것은 아니다. 어플리케이션은, 디바이스를 몇회에서도 취득해, 릴리즈 할 수가 있다.

협조 레벨에 따라서는, 어플리케이션이 백그라운드로 이행하면(자) 반드시 자동적으로 디바이스가 릴리즈 되는 일이 있다. 마우스의 경우, 유저가 메뉴를 클릭 하면 자동적으로 릴리즈 된다. 클릭한 시점에서 Windows 가 디바이스의 제어를 계승하기 때문이다.

디바이스 프로퍼티의 변경에 앞서, 그 디바이스를 릴리즈 할 필요가 있다. 유일한 예외로서 force feedback 디바이스는, 취득 상태에 있어도 게인을 변경할 수 있다.

취득의 구조가 필요한 이유는, 다음의 2 개이다.

제일에, DirectInput 는, 디바이스로부터의 데이터의 흐름이 시스템에 의해 중단되었을 때에는, 어플리케이션에 통지할 수 없으면 안 된다. 예를 들어, 유저가 Alt+Tab 를 사용해 다른 어플리케이션으로 전환해 변환 후의 어플리케이션으로 입력 디바이스를 사용했을 경우에, 원의 어플리케이션은, 입력 디바이스가 이미 자신에게 속하지 않고, 버퍼 상태가 변화한 가능성이 있는 것을 알 필요가 있다. DISCL_FOREGROUND 협조 레벨에서의 어플리케이션을 관찰해 보자. 유저가 Shift 키를 누른다. Shift 키를 계속 누르고 있는 동안에, 다른 어플리케이션으로 전환한다. 그 후, 유저는 Shift 키를 떼어 놓아, 원의 어플리케이션에 돌아온다. 원의 어플리케이션으로부터 보면, Shift 키는 여전히 밀리고 있는 상태이다. 취득의 구조에서는, 원의 어플리케이션에 입력이 종료한 것을 통지해, 이 상태로부터 회복시킬 수가 있다.

2번째로, 어플리케이션이 디바이스의 프로퍼티를 변경할 수 있으므로, 보호가 없으면 유저가 데이터를 취득하려고 할 때마다, DirectInput 가 프로퍼티를 체크해야 하게 된다. 이것은, 꽤 비효율적이겠지. 한층 더 나쁜 것에는, 버퍼 사이즈를 변경하고 있는 한중간에, 데이터 버퍼에 액세스 하는 하드웨어 인터럽트가 발생할 가능성이 있다. 그러한 이유로써, DirectInput 는, 프로퍼티를 변경하기 전에, 어플리케이션에 대해서 디바이스를 릴리즈 하도록(듯이) 요구한다. 디바이스를 재취득 하면, DirectInput 는 프로퍼티를 확인해, 디바이스로부터 어플리케이션에의 최적인 데이터 전송의 방법을 결정한다. 이 처리는 한 번 밖에 행해지지 않기 때문에, 데이터 취득의 각 메소드를 매우 고속으로 할 수가 있다.

[C++]

디바이스를 상실하는 가장 일반적인 원인은, 어플리케이션이 백그라운드로 이행하는 것이다. 따라서, 어플리케이션이 액티브하게 되었을 때에는 항상, 디바이스를 재취득하는 것이 필요하게 된다. 그러나, 기동시의 WM_ACTIVATE 핸들러에 의존하려면 주의가 필요하다. 최초의 WM_ACTIVATE 메세지가 도착하는 것은, 아마 윈도우의 초기화중에서, DirectInput 의 셋업전이다. 기동시에 디바이스를 확실히 취득하려면 , 디바이스가 초기화되자 마자 IDirectInputDevice7::Acquire 를 호출하도록(듯이) 한다.

특히 표준의 키보드나 마우스 이외의 디바이스의 경우, 프로그램 윈도우가 액티브하게 되었을 때에 디바이스를 취득해도, 디바이스가 릴리즈 되는 모든 케이스에 대응할 수 있다고는 할 수 없다. 어플리케이션이 디바이스를 갑자기 릴리즈 하는 경우도 있으므로, 디바이스로부터 데이터를 취득하려고 하기 전에, 취득 상태를 확인하는 구조가 필요하다. Scrawl 샘플 어플리케이션에서는, Scrawl_OnMouseInput 함수로 이 확인을 실시하고 있다. 이 함수에서는,DIERR_INPUTLOST 에러가, 마우스를 재취득하는 메세지의 방아쇠가 된다( 「튜토리얼 2 : 마우스의 사용」도 참조할것).

[Visual Basic]

특히 배타 협조 레벨을 설정했을 경우는, 어플리케이션이 디바이스를 갑자기 릴리즈 하는 경우도 있으므로, 어플리케이션이 확실히 취득 상태를 추적하도록(듯이) 한다. 데이터를 취득하려고 한 다음에,DIERR_INPUTLOST 에러가 발생했는지 어떠했는지를 체크하는 것도 1 개의 방법이다. 이 에러가 발생하고 있으면(자), 디바이스가 릴리즈 되고 있었던 것이 알 수 있다. 어플리케이션이 이벤트 통지에 응해 입력을 취득하고 있는 경우, 취득이 상실 하면, 이벤트가 신호를 발한다.

배타 모드로 디바이스를 관리하는 방법의 상세한 것에 대하여는, 「ScrawlB 샘플」을 참조할것.

취득 끝난 디바이스를 재취득하려고 해도, 해는 전혀 없다. Acquire 에 대한 장황한 호출은 무시되어 디바이스는 상시 Unacquire 를 1 회 호출하는 것으로 릴리즈 할 수가 있다.

[C++]

Windows 는, 어플리케이션이 마우스를 배타 모드로 사용하고 있을 때는, 마우스에 액세스 하지 않는다. Windows 에 마우스를 사용시키고 싶은 경우는, 마우스를 릴리즈 해야 한다. Scrawl 샘플의 1 개의 예에서는, 오른쪽 버튼의 클릭에 반응하기 위해서, 마우스를 릴리즈 해, Windows 커서를 같은 점에 표시해, context menu를 pop-up 해, 메뉴 선택을 할 때까지 Windows 가 입력을 처리하도록(듯이) 하고 있다.

[Visual Basic]

Windows 는, 어플리케이션이 마우스를 배타 모드로 사용하고 있을 때는, 마우스에 액세스 하지 않는다. Windows 에 마우스를 사용 찌를 수 있던 차면, 마우스를 릴리즈 해야 한다. ScrawlB 샘플 의 1 개의 예에서는, 오른쪽 버튼의 클릭에 반응하기 위해서, 마우스를 릴리즈 해, Windows 커서를 같은 점에 표시해, context menu를 pop-up 해, 메뉴 선택을 할 때까지 Windows 가 입력을 처리하도록(듯이) 하고 있다.


디바이스 변경의 인식

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

USB (Universal Serial Bus) 디바이스는, 시스템을 재부팅 하지 않아도 장착이나 제외를 할 수 있으므로, 입력 디바이스의 구성의 변화에 어플리케이션을 반응할 수 있도록(듯이) 해야 한다. 예를 들어, 콘트롤러를 이제(벌써) 1 대 꽂는 것으로, 진행중의 게임에 새로운 플레이어가 참가할 수 있도록(듯이) 하는 것을 생각해 본다.

디바이스가 변화할 경우에 메세지를 받아들이려면 , 우선, 이하의 샘플 코드와 같이, 통지를 받도록(듯이) 등록할 필요가 있다.

PVOID hNotifyDevNode;

void RegisterForDevChange(HWND hDlg, PVOID *hNotifyDevNode)
{
DEV_BROADCAST_DEVICEINTERFACE *pFilterData =
(DEV_BROADCAST_DEVICEINTERFACE*)
_alloca(sizeof(DEV_BROADCAST_DEVICEINTERFACE));
ASSERT (pFilterData);

ZeroMemory(pFilterData, sizeof(DEV_BROADCAST_DEVICEINTERFACE));

pFilterData->dbcc_size = sizeof(DEV_BROADCAST_DEVICEINTERFACE);
pFilterData->dbcc_devicetype = DBT_DEVTYP_DEVICEINTERFACE;
pFilterData->dbcc_classguid  = GUID_CLASS_INPUT;

*hNotifyDevNode = RegisterDeviceNotification(hDlg, pFilterData,
            DEVICE_NOTIFY_WINDOW_HANDLE);
}

다음에, 이하의 예의 같게, 메인 윈도우 프로시저로, 디바이스가 Attach 된 것, 디바이스가 지금부터 떼어내지는 것, 디바이스가 이미 떼어내진 것을 통지하는 메세지를 체크한다.

MyWindowProc(HWND hWnd, UINT nMsg, WPARAM wParam, LPARAM lParam)
{
switch (nMsg)
    {
case WM_DEVICECHANGE:
        {
switch (wParam)
            {
case DBT_DEVICEARRIVAL:
// 디바이스의 도착을 처리한다
break;

case DBT_DEVICEQUERYREMOVE:
// 디바이스의 삭제 요구를 처리한다
break;

case DBT_DEVICEREMOVECOMPLETE:
// 디바이스의 삭제를 처리한다
break;
            }
        }
.
.
.
    }
}

DBT_DEVICEARRIVAL 이벤트에 응해,IDirectInput7::FindDevice 를 사용해 디바이스의 인스턴스 GUID 를 취득해, 이 값을 IDirectInput7::CreateDeviceEx 에 건네준다.

상세한 것에 대하여는, Platform SDK 에 포함되는 디바이스 관리의 주제를 참조할것.


DirectInput 디바이스 데이터

여기에서는, DirectInput 디바이스 데이터의 취득에 관한 기본적인 생각을 몇개인가 설명한다.

  • 버퍼링 데이터와 직접 데이터
  • 타임 스탬프와 순서 번호
  • 폴링과 이벤트
  • 상대 좌표와 절대 좌표

마우스, 키보드 및 죠이스틱 출력 데이터의 특정 사항, 및 출력 데이터에 대해서는, 이하의 주제로 상술한다.

  • 마우스 데이터
  • 키보드 데이터
  • 죠이스틱 데이터
  • 데이터 출력


버퍼링 데이터와 직접 데이터

DirectInput 는, 버퍼링 데이터와 직접 데이터의 2 종류의 데이터를 공급한다. 버퍼링 데이터는, 어플리케이션이 취득할 때까지 저장 되고 있는 이벤트의 레코드이다. 직접 데이터는, 디바이스의 현재 상태의 snapshot이다.

직접 데이터는, 디바이스의 현재 상태인 만큼 관심이 있는 어플리케이션으로 사용하는 것을 생각된다. 예를 들어, 죠이스틱의 현재 위치와 1 개 이상의 버튼 상태에 반응하는 플라이트 컴배트 시뮬레이션 등이다. 버퍼링 데이터는, 상태보다 이벤트를 중요시하는 경우에 선택 하면이야 있고. 예를 들어, 마우스의 움직임이나 버튼의 클릭에 반응하는 어플리케이션 등이다. 양쪽 모두의 타입의 데이터를 사용할 수도 있다. 예를 들어, 죠이스틱축에서는 직접 데이터를 취득해, 버튼에서는 버퍼링 데이터를 취득하는 경우 등이다.

DirectX SDK 로 제공되고 있는 DirectInput QuickTest 어플리케이션에서는, 디바이스의 직접 데이터와 버퍼링 데이터의 양쪽 모두를 볼 수가 있다. 어플리케이션 윈도우로 디바이스를 생성 한 후,[Mode] 페이지로 그 프로퍼티를 설정한다. 하면,[Data] 페이지의 좌측으로 직접 데이터, 우측으로 버퍼링 데이터가 표시된다.

[C++]

어플리케이션은,IDirectInputDevice7::GetDeviceState 메소드를 호출하는 것으로, 직접 데이터를 취득한다. 이름이 나타내는 대로, 이 메소드는 디바이스의 현재 상태를 돌려준다. 예를 들어, 각 버튼이 업 상태나 다운 상태인가, 등이다. 이 메소드는, 현재 상태와 이전 상태를 비교해 얻을 수 있는 암묵의 정보를 제외해, 마지막 호출해 이후에 디바이스에 일어난 이벤트에 관한 데이터는, 전혀 제공하지 않는다. GetDeviceState 에 대한 마지막 호출로부터 현재의 호출까지의 사이에, 유저가 버튼을 누르거나 떼어 놓거나 하고 있어도, 어플리케이션은 그것에 관해서 아무것도 인식하지 않는다. 한편, 버튼을 누른 채로 하고 있으면(자),GetDeviceState 는, 유저가 버튼을 떼어 놓을 때까지 「보턴다운」을 계속 보고한다.

이 디바이스 상태의 보고는, WM_LBUTTONDOWN 와 같은 한 번 한계의 메세지에 의한 Windows 의 이벤트 보고와는 달라, Win32 의 GetKeyboardState 함수의 보고에 유사하고 있다. GetDeviceState 를 사용해 디바이스를 폴링 하는 경우에는, 버튼 클릭, 더블 클릭, 또는 단일의 키스트로크(keystroke)의 구별을 프로그램으로 판단하지 않으면 안되어, 또, 어플리케이션이 보턴다운 상태 또는 키 다운 상태에 대해, 부적절한 타이밍에 계속 할리 가 없게 적절히 처리해야 한다.

버퍼링 데이터의 경우, 이벤트는, 프로그램이 처리를 시작 할 수 있는 상태가 될 때까지 저장 되고 있다. 버튼이나 키가 밀리거나 축이 이동 되거나 할 때마다, 그 이벤트에 대한 정보가 버퍼중의 DIDEVICEOBJECTDATA 구조체에 놓여진다. 버퍼가 오버플로우 하면, 새로운 데이터는 없어진다. 어플리케이션이 버퍼를 읽어내려면 ,IDirectInputDevice7::GetDeviceData 를 호출한다. 한 번에 임의의 수의 항목을 읽어낼 수가 있다.

항목을 읽어내면(자), 보통은, 버퍼로부터 그 항목이 소거되지만, 소거 없음 피킹도 선택할 수 있다.

버퍼링 데이터를 취득하려면 , 우선 IDirectInputDevice7::SetProperty 메소드로 버퍼 사이즈를 설정할 필요가 있다 ( 「디바이스 프로퍼티」를 참조할것). 버퍼 사이즈의 설정은, 디바이스를 최초로 취득하기 전에 실시한다. 효율상의 이유로부터, 디폴트의 버퍼 사이즈는 제로이다. 이 값을 변경하지 않는 한, 버퍼링 데이터를 취득할 수 없다. 버퍼 사이즈는 바이트 단위나워드단위는 아니고, 디바이스의 타입에 대응한 데이터의 항목 단위로 카운트 된다.

GetDeviceData 메소드를 호출한 후는,pdwInOut 파라미터값을 체크할 필요가 있다. 버퍼로부터 꺼내지는 항목수는, 이 변수에 돌려주어진다.

주 : 아날로그 죠이스틱 등, 세치기를 생성하지 않는 디바이스의 경우,IDirectInputDevice7::Poll 메소드가 불려 갈 때까지, DirectInput 는 어떠한 데이터도 취득하지 않는다. 상세한 것에 대하여는, 「폴링과 이벤트」를 참조할것.

버퍼링 데이터를 취득하는 예에 대해서는,IDirectInputDevice7::GetDeviceData 를 참조할것.

[Visual Basic]

어플리케이션은, 이하의 메소드의 어느쪽이든을 호출하는 것으로, 직접 데이터를 취득한다.

  • DirectInputDevice.GetDeviceStateKeyboard . DIKEYBOARDSTATE 형의 데이터를 취득하는 디바이스의 경우 (이것 이하의 3 개의 메소드에 대해서는,DirectInputDevice.SetCommonDataFormat 를 사용해 데이터 형식을 설정할 필요가 있다).
  • DirectInputDevice.GetDeviceStateMouse . DIMOUSESTATE 형의 데이터를 취득하는 디바이스의 경우.
  • DirectInputDevice.GetDeviceStateJoystick . DIJOYSTATE 형의 데이터를 취득하는 디바이스의 경우.
  • DirectInputDevice.GetDeviceStateJoystick2 . DIJOYSTATE2 형의 데이터를 취득하는 디바이스의 경우.
  • DirectInputDevice.GetDeviceState . DirectInputDevice.SetDataFormat 를 사용해 커스텀 데이터 형식을 설정해, 사용하는 디바이스의 경우.

이름이 나타내는 대로, 이러한 각 메소드는 디바이스의 현재 상태를 돌려준다. 예를 들어, 각 버튼이 업 상태나 다운 상태인가, 등이다. 이 메소드는, 현재 상태와 이전 상태를 비교해 얻을 수 있는 암묵의 정보를 제외해, 마지막 호출해 이후에 디바이스에 일어난 이벤트에 관한 데이터는, 전혀 제공하지 않는다. 각 메소드에 대한 마지막 호출로부터 현재의 호출까지의 사이에, 유저가 버튼을 누르거나 떼어 놓거나 하고 있어도, 어플리케이션은 그것에 관해서 아무것도 인식하지 않는다. 한편, 버튼을 누른 채로 하면(자), 메소드는, 유저가 버튼을 떼어 놓을 때까지 「보턴다운」을 계속 보고한다.

이 디바이스 상태의 보고는,Click 나 Keydown 와 같은 한 번 한계의 이벤트에 의한 Visual Basic 의 이벤트 보고와는 다르다. GetDeviceState 메소드의 어느쪽이든을 사용해 디바이스를 폴링 하는 경우에는, 버튼 클릭, 더블 클릭, 또는 단일의 키스트로크(keystroke)의 구별을 프로그램으로 판단하지 않으면 안되어, 또, 어플리케이션이 보턴다운 상태 또는 키 다운 상태에 대해, 부적절한 타이밍에 계속 할리 가 없게 적절히 처리해야 한다.

버퍼링 데이터의 경우, 이벤트는, 프로그램이 처리를 시작 할 수 있는 상태가 될 때까지 저장 되고 있다. 버튼이나 키가 밀리거나 축이 이동 되거나 할 때마다, 그 이벤트에 대한 정보가 버퍼중의 DIDEVICEOBJECTDATA 형에 놓여진다. 어플리케이션이 버퍼를 읽어내려면 ,DirectInputDevice.GetDeviceData 를 호출한다. 한 번에 임의의 수의 항목을 읽어낼 수가 있다.

항목을 읽어내면(자), 보통은, 버퍼로부터 그 항목이 소거되지만, DIGDD_PEEK 플래그를 설정 하면, 삭제하지 않고 취득하는 일도 선택할 수 있다.

버퍼링 데이터를 취득하려면 , 우선 DirectInputDevice.SetProperty 메소드로 버퍼 사이즈를 설정할 필요가 있다 ( 「디바이스 프로퍼티」를 참조할것). 버퍼 사이즈의 설정은, 디바이스를 최초로 취득하기 전에 실시한다. 효율상의 이유로부터, 디폴트의 버퍼 사이즈는 제로이다. 이 값을 변경하지 않는 한, 버퍼링 데이터를 취득할 수 없다. 버퍼 사이즈는 바이트 단위나 워드 (WORD) 단위는 아니고, 디바이스의 타입에 대응한 데이터의 항목 단위로 카운트 된다.

GetDeviceData 의 반환값은, 버퍼로부터 취득된 항목수를 나타내고 있다. 버퍼가 오버플로우 했을 경우, 데이터는 돌려주어지고 두,GetDeviceData 는 에러를 발생한다. 이 에러에 의해, 어플리케이션이 포착된다.

주 : 아날로그 죠이스틱 등, 세치기를 생성하지 않는 디바이스의 경우,DirectInputDevice.Poll 메소드를 호출할 때까지, DirectInput 는 어떠한 데이터도 취득하지 않는다. 상세한 것에 대하여는, 「폴링과 이벤트」를 참조할것.

참조

  • 타임 스탬프와 순서 번호
  • 마우스 데이터
  • 키보드 데이터
  • 죠이스틱 데이터


타임 스탬프와 순서 번호

[C++]

버퍼링 되고 있는 DirectInput 입력 데이터의 경우 ( 「버퍼링 데이터와 직접 데이터」를 참조), 각 DIDEVICEOBJECTDATA 구조체에는, 이벤트의 타입과 거기에 관련지을 수 있었던 디바이스 오브젝트 뿐만이 아니라, 타임 스탬프와 순서 번호도 저장 된다.

dwTimeStamp 멤버는, 이벤트가 발생했을 때의 시스템 시간을 밀리 세컨드 단위로 저장 한다. 이것은, Win32 GetTickCount 함수에 의해 돌려주어지는 값과 같은가, 보다 정밀도가 높은 값이다.

dwSequence 멤버는, DirectInput 가 할당한 순서 번호를 저장 한다. DirectInput 시스템은, 단일의 순서 카운터를 보관 유지하고 있다. 이 카운터는, 임의의 디바이스로, 버퍼링 되는 이벤트가 발생할 때마다 수시 증가한다. 이 번호를 사용해, 다른 디바이스로부터 발생하는 이벤트를 비교해, 어느 쪽이 앞인지를 확인할 수가 있다. DISEQUENCE_COMPARE 매크로는, 순서 카운터의 순환성을 고려하고 있다.

[Visual Basic]

버퍼링 되고 있는 DirectInput 입력 데이터의 경우 ( 「버퍼링 데이터와 직접 데이터」를 참조), 각 DIDEVICEOBJECTDATA 형에는, 이벤트의 타입과 거기에 관련하는 디바이스 오브젝트 뿐만이 아니라, 타임 스탬프와 순서 번호도 저장 된다.

lTimeStamp 멤버는, 이벤트가 발생했을 때의 시스템 시간을 밀리 세컨드 단위로 저장 한다. 이것은, Win32 GetTickCount 함수에 의해 돌려주어지는 값과 같은가, 보다 정밀도가 높은 값이다.

lSequence 멤버는, DirectInput 가 할당한 순서 번호를 저장 한다. DirectInput 시스템은, 단일의 순서 카운터를 보관 유지하고 있다. 이 카운터는, 임의의 디바이스로, 버퍼링 되는 이벤트가 발생할 때마다 수시 증가한다. 이 번호를 사용해, 다른 디바이스로부터 발생하는 이벤트를 비교해, 어느 쪽이 앞인지를 확인할 수가 있다.

동시에 발생하는 이벤트에는, 같은 순서 번호를 할당할 수 있다. 예를 들어, 마우스나 죠이스틱을 비스듬하게 이동하는 경우의 x 축과 y 축의 변화는, 같은 순서 번호를 가진다.

주 : 이벤트는, 항상, 발생시간 순서에 버퍼에 넣어지므로, 단일 디바이스로부터의 이벤트를 단지 순서 붙이고 할 뿐(만큼)이라면, 순서 번호를 체크할 필요는 없다.


폴링과 이벤트

입력 데이터가 발생하고 있을지 어떨지를 확인하려면 , 폴링과 이벤트 통지라고 하는 2 개의 방법이 있다.

디바이스의 폴링이란, 디바이스 오브젝트의 현재 상태를 정기적으로 취득하는 것, 또는 이벤트 버퍼의 내용을 체크하는 것을 의미한다. 폴링이 사용되는 것은 보통, 결코 아이돌이 되는 것이 없고, 항상 게임의 세계를 갱신, 렌더링 하는 리얼타임 게임이다.

[C++]

C++ 어플리케이션에서의 폴링은 보통, 메시지 루프내에서 행해진다.

이벤트 통지는,Scrawl 샘플과 같이, 아무것도 하지 않고 입력을 기다리는 것 같은 어플리케이션에 향하고 있다. 이벤트 통지를 사용하려면 , Win32 CreateEvent 함수로 thread 동기 오브젝트를 셋업 한 후, 이벤트의 핸들을 IDirectInputDevice7::SetEventNotification 메소드에 건네주는 것에 의해, 이 이벤트와 디바이스를 관계 붙인다. 이것으로, 디바이스 상태가 변화할 때마다, DirectInput 에 의해 이벤트가 통지된다. 어플리케이션은,WaitForSingleObject 등의 Win32 함수를 사용해, 이벤트의 통지를 받은 후, 입력 버퍼를 체크해 무슨 이벤트인지를 확인해, 응답할 수가 있다. 샘플 코드에 대해서는, 「Scrawl 샘플」 및 「IDirectInputDevice7::SetEventNotification 」를 참조할것.

죠이스틱이나 다른 게임 디바이스, 또는 이러한 디바이스 위에의 오브젝트중 몇개인가는,IDirectInputDevice7::Poll 메소드를 호출할 때까지, 하드웨어 인터럽트를 생성하지 않고, 어떠한 데이터도 돌려주지 않고, 어떠한 이벤트도 송신하지 않는다(이러한 백그라운드에서의 폴링을, 여기서 설명하는 어플리케이션 폴링과 혼동 하지 않는 것. Poll 메소드는, 데이터를 일절 취득하지 않지만, 데이터를 사용 가능하게 하는 일이 있다).

데이터를 취득하려고 할 때마다 Poll 메소드를 호출할 필요가 있을지 어떨지를 조사하려면 , 우선 디바이스의 데이터 형식을 설정해,IDirectInputDevice7::GetCapabilities 메소드를 호출해,DIDEVCAPS 구조체의 DIDC_POLLEDDATAFORMAT 플래그를 체크한다.

DIDC_POLLEDDATAFORMAT 플래그와 DIDC_POLLEDDEVICE 플래그를 혼동 하지 않는 것. 후자는, 디바이스 위에의 오브젝트중 한쪽이 폴링을 필요로 하고 있을 때 설정되는 플래그이다. 다음에,IDirectInputDevice7::GetObjectInfo 메소드를 호출해,DIDEVICEOBJECTINSTANCE 구조체에 있는 DIDOI_POLLED 플래그를 체크 하면, 폴링을 필요로 하고 있는 것이 특정의 오브젝트일지 어떨지를 분별할 수가 있다.

DIDC_POLLEDDEVICE 플래그는 디바이스의 최악 상태를 나타내는 것에서 만나며, 디바이스의 실제 상태를 나타내는 것은 아니다. 예를 들어, 소프트웨어 해상도 조절 첨부의 HID 마우스의 경우, 해상도 정보를 읽어내기 위해서(때문에) 폴링을 요구하므로, DIDC_POLLEDDEVICE 플래그가 설정된다. 디바이스의 표준 버튼과 축데이터 이외는 필요없는 경우, 이러한 조건의 아래에서 디바이스를 폴링 하는 것은, 무의미하다.

다만,IDirectInputDevice7::Poll 메소드를 호출해도, 입력 디바이스에 장해를 줄 것은 없다. 이 호출이 불필요한 때는, 어떤 이펙트도 가지지 않고 곧바로 종료한다.

[Visual Basic]

Visual Basic 어플리케이션에서는, 폴링은 보통,Sub Main 프로시저내에서 행해진다.

이벤트 통지는,ScrawlB 샘플과 같이, 아무것도 하지 않고 입력을 기다리는 것 같은 어플리케이션에 향하고 있다. 이벤트 통지를 사용하려면 , 데이터를 취득하는 폼 또는 모듈에 DirectXEvent 를 이행 한다. 다음에,DirectX7.CreateEvent 를 사용해 이벤트 핸들을 생성 해, 이 핸들을 DirectInputDevice.SetEventNotification 에 건네준다. 이것으로, 디바이스로 입력 이벤트가 발생 하면 반드시 DirectXEvent.DXCallback 메소드가 불려 가Sub Main 내와 같게, 이 메소드의 이행내에서, 디바이스 상태 또는 버퍼링 데이터의 어느 쪽인지를 취득할 수 있다.

죠이스틱이나 다른 게임 디바이스, 또는 이러한 디바이스 위에의 오브젝트중 몇개인가는,DirectInputDevice.Poll 메소드를 호출할 때까지, 하드웨어 인터럽트를 생성하지 않고, 어떠한 데이터도 돌려주지 않고, 어떠한 이벤트도 송신하지 않는다(이러한 백그라운드에서의 폴링을, 여기서 설명하는 어플리케이션 폴링과 혼동 하지 않는 것. Poll 메소드는, 데이터를 일절 취득하지 않지만, 데이터를 사용 가능하게 하는 일이 있다).

데이터를 취득하려고 할 때마다 Poll 메소드를 호출할 필요가 있을지 어떨지를 조사하려면 , 우선 디바이스의 데이터 형식을 설정해, 다음에 DirectInputDevice.GetCapabilities 메소드를 호출해,DIDEVCAPS 형의 DIDC_POLLEDDATAFORMAT 플래그를 체크한다.

DIDC_POLLEDDATAFORMAT 플래그와 DIDC_POLLEDDEVICE 플래그를 혼동 하지 않는 것. 후자는, 디바이스 위에의 오브젝트의 어떤 것인가가 폴링을 필요로 하고 있을 때 설정되는 플래그이다. 다음에,IDirectInputDevice7::GetObjectInfo 메소드를 호출해 DirectInputDeviceObjectInstance 오브젝트를 취득해,DirectInputDeviceObjectInstance.GetFlags 에 의해 돌려주어지는 값중의 DIDOI_POLLED 플래그를 체크 하면, 폴링을 필요로 하고 있는 것이 특정의 오브젝트일지 어떨지를 분별할 수가 있다.

DIDC_POLLEDDEVICE 플래그는 디바이스의 최악 상태를 나타내는 것에서 만나며, 디바이스의 실제 상태를 나타내는 것은 아니다. 예를 들어, 소프트웨어 해상도 조절 첨부의 HID 마우스에서는, 해상도 정보를 읽어내기 위해서(때문에) 폴링을 요구하므로, DIDC_POLLEDDEVICE 플래그가 설정된다. 디바이스의 표준 버튼과 축데이터 이외는 필요없는 경우는, 이러한 조건의 아래에서 디바이스를 폴링 하는 것은, 무의미하다.

다만,Poll 메소드를 호출해도, 입력 디바이스에 장해를 줄 것은 없다. 이 호출이 불필요한 때는, 어떤 이펙트도 가지지 않고 곧바로 종료한다.


상대 좌표와 절대 좌표

축좌표는, 상대값으로서 돌려주어지는 경우도 있다. 즉, 어플리케이션이 전회 디바이스 상태를 취득하고 나서의 변화량, 버퍼링 입력의 경우는, 직전의 항목이 버퍼에 넣어지고 나서의 변화량이다.

절대축좌표란, 디바이스의 취득 이래, 시스템이 돌려준 모든 상대 좌표의 연속 합계이다. 즉, 어느 고정점에 대한 축의 위치를 나타낸다.

디폴트에서는, 마우스의 축은 상대 좌표이며, 죠이스틱축은 절대 좌표로 보고된다. 프로퍼티를 설정하는 것으로, 디바이스의 좌표 시스템을 변경할 수 있다. 상세한 것에 대하여는, 「디바이스 프로퍼티」를 참조할것.


마우스 데이터

[C++]

데이터를 취득하도록(듯이) 마우스 디바이스를 설정하려면 , 파라미터로서 c_dfDIMouse 또는 c_dfDIMouse2 의 글로벌 변수를 지정해,IDirectInputDevice7::SetDataFormat 메소드를 호출한다. 5 개(살) 이상의 mouse button를 지원 하는 경우는,c_dfDIMouse2 를 사용한다.

풀 스크린 어플리케이션의 성능을 최대한 발휘하려면 , 협조 레벨에 DISCL_EXCLUSIVE | DISCL_FOREGROUND 를 설정한다. 배타를 설정 하면, Windows 커서가 소실한다. DISCL_FOREGROUND 를 설정 하면, 디버그 윈도우로 전환했을 때에, 어플리케이션이 마우스에의 액세스권을 잃는다. DISCL_BACKGROUND 로 변경 하면, 어플리케이션의 퍼포먼스는 희생이 되지만, 어플리케이션의 디버그를 보다 용이하게 실시할 수가 있게 된다.

[Visual Basic]

데이터를 취득하도록(듯이) 마우스 디바이스를 설정하려면 , 우선 파라미터에 DIFORMAT_MOUSE 를 지정해 DirectInputDevice.SetCommonDataFormat 메소드를 호출한다.

풀 스크린 어플리케이션의 성능을 최대로 하려면 , 협조 레벨에 DISCL_EXCLUSIVE | DISCL_FOREGROUND 를 설정한다. 배타 설정에서는, Windows 커서가 소실한다. DISCL_FOREGROUND 를 설정 하면, Visual Basic 개발 환경으로 전환했을 때에, 어플리케이션이 마우스에의 액세스권을 잃는다. DISCL_BACKGROUND 로 변경 하면, 어플리케이션의 퍼포먼스는 희생이 되지만, 어플리케이션의 디버그를 보다 용이하게 실시할 수가 있게 된다.

이하의 주제에는, 마우스의 직접 데이터와 버퍼링 데이터의 취득, 해석의 상세한 설명이 있다.

  • 마우스의 직접 데이터
  • 마우스의 버퍼링 데이터
  • 마우스축데이터의 해석
  • 소실한 마우스 입력의 확인

참조

디바이스 데이터 형식,협조 레벨


마우스의 직접 데이터

[C++]

마우스의 현재 상태를 취득하려면 ,DIMOUSESTATE 구조체나 DIMOUSESTATE2 구조체에의 포인터를 지정해,IDirectInputDevice7::GetDeviceState 를 호출한다. 어느 쪽의 구조체를 사용할까는, 데이터 형식에 의존한다. 이 구조체에 돌려주어지는 마우스 상태에는, 축데이터 및 각 버튼 상태가 포함된다.

구조체의 최초의 3 개의 멤버가 축좌표를 보관 유지한다 ( 「마우스축데이터의 해석」을 참조할것).

rgbButtons 멤버는, 바이트 배열이다. 4 개(살) 또는 8 개의 각 버튼에 1 요소가 대응한다. 종래형의 마우스의 경우, 일반적으로, 배열의 1 번째의 요소가 왼쪽 버튼, 2 번째가 오른쪽 버튼, 3 번째가 중앙 버튼이다. 상위 비트는, 버튼이 다운 상태의 경우에 세트 되어 버튼이 업 상태 또는 존재하지 않는 경우에 소거된다.

[Visual Basic]

마우스의 현재 상태를 취득하려면 ,DIMOUSESTATE 형을 지정해 DirectInputDevice.GetDeviceStateMouse 를 호출한다. 이 형태에 돌려주어지는 마우스 상태에는, 축데이터 및 각 버튼 상태가 포함된다.

DIMOUSESTATE 형의 x,y,z 의 각 멤버는, 축좌표를 보관 유지한다 ( 「마우스축데이터의 해석」을 참조할것). buttons 멤버는, 바이트 배열이다. 4 개의 각 버튼에 1 요소가 대응한다. 일반적으로, 배열의 1 번째의 요소가 왼쪽 버튼, 2 번째가 오른쪽 버튼, 3 번째가 중앙 버튼, 4 번째가 나머지의 버튼이다. 상위 비트는, 버튼이 다운 상태의 경우에 세트 되어 버튼이 업 상태 또는 존재하지 않는 경우에 소거된다.

참조

버퍼링 데이터와 직접 데이터


마우스의 버퍼링 데이터

마우스로부터 버퍼링 데이터를 취득하려면 , 버퍼 사이즈를 설정해야 한다 ( 「디바이스 프로퍼티」를 참조할것). 버퍼의 디폴트 사이즈는 제로이므로, 이 순서는 불가결하다.

[C++]

또,DIDEVICEOBJECTDATA 구조체의 배열도 선언할 필요가 있다. 이 배열은, 최대로 버퍼 사이즈와 동수의 요소를 가질 수가 있다. 1 번의 호출로 버퍼의 내용 전체를 취득할 필요는 없지만, 배열내의 1 요소만을 보관 유지해, 버퍼가 비울 때까지 1 개(살)씩 이벤트를 취득할 수가 있다.

디바이스의 취득 후는,IDirectInputDevice7::GetDeviceData 메소드를 사용해 언제라도 버퍼내의 이벤트를 조사하거나 플래시 하거나 할 수가 있다 ( 「버퍼링 데이터와 직접 데이터」를 참조할것). 돌려주어진DIDEVICEOBJECTDATA 배열중의 각 요소는, 마우스에 대한 단일 오브젝트 상태 변화를 나타낸다. 예를 들어, 유저가 버튼 0 을 눌러 마우스를 비스듬하게 이동 하면,GetDeviceData 에게 건네진 배열 (3 개(살) 이상의 요소를 가지고 있는 경우,dwInOut 는 3 이상)은, 3 개의 요소를 묻을 수 있다. 이러한 요소는 각각, 버튼 0 의 압하, x 축의 변화, 및 y 축의 변화를 나타낸다. pdwInOut 는 3 으로 설정된다.

배열중의 요소가 어느 오브젝트를 가리킬까는,DIDEVICEOBJECTDATA 구조체의 dwOfs 멤버를, 이하의 매크로에 의해 돌려주어지는 값과 비교하는 것으로 확인할 수 있다.

  • DIMOFS_BUTTON0 ~ DIMOFS_BUTTON3
  • DIMOFS_X
  • DIMOFS_Y
  • DIMOFS_Z

이러한 각 값은,DIMOUSESTATE 구조체 또는 DIMOUSESTATE2 구조 체내의 오브젝트에 대한 데이터의 오프셋(offset)로부터 이끌린다. 예를 들어, DIMOFS_BUTTON0 가 돌려주는 값은,DIMOUSESTATE 구조 체내의 rgbButtons[0] 오프셋(offset)와 동일하다. 매크로를 사용해 단순한 비교를 실시해, 어느 디바이스 오브젝트가 버퍼의 항목에 관련하고 있을까를 결정할 수가 있다. 예를 들어, 이하대로이다.

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)가 제로가 아닐 때, 버튼이 밀리고 있게 된다.

DIDEVICEOBJECTDATA 구조체외의 멤버의 상세한 것에 대하여는, 「타임 스탬프와 순서 번호」를 참조할것.

[Visual Basic]

또,DIDEVICEOBJECTDATA 형의 배열도 선언할 필요가 있다. 이 배열은, 최대로 버퍼 사이즈와 동수의 요소를 가질 수가 있다. 1 번의 호출로 버퍼의 내용 전체를 취득할 필요는 없지만, 배열내의 1 요소만을 보관 유지해, 버퍼가 비울 때까지 1 개(살)씩 이벤트를 취득할 수가 있다.

디바이스의 취득 후는,DirectInputDevice.GetDeviceData 메소드를 사용해 언제라도 버퍼내의 이벤트를 조사하거나 플래시 하거나 할 수가 있다 ( 「버퍼링 데이터와 직접 데이터」를 참조할것). 돌려주어진DIDEVICEOBJECTDATA 배열중의 각 요소는, 마우스에 대한 단일 오브젝트 상태의 변화를 나타낸다. 예를 들어, 유저가 버튼 0 을 눌러 마우스를 비스듬하게 이동 하면,GetDeviceData 에게 건네진 배열 (3 개(살) 이상의 요소를 가지고 있는 경우)은, 3 개의 요소를 묻을 수 있다. 이러한 요소는 각각, 버튼 0 의 압하, x 축의 변화, 및 y 축의 변화를 나타낸다. 메소드의 반환값은 3 이다.

배열중의 요소가 어느 오브젝트를 가리킬까는,DIDEVICEOBJECTDATA 형의 lOfs 멤버를,CONST_DIMOUSEOFS 열거내의 정수와 비교하는 것으로 확인할 수 있다. 이러한 각 값은,DIMOUSESTATE 형중의 오브젝트에 대한 데이터의 오프셋(offset)로부터 이끌린다. 예를 들어, DIMOFS_BUTTON0 가 돌려주는 값은,DIMOUSESTATE 형중의 buttons(0) 오프셋(offset)와 동일하다.

디바이스 오브젝트 상태 변화 데이터는,DIDEVICEOBJECTDATA 형의 lData 멤버에 저장 된다. 축의 경우에는, 좌표값이 이 멤버중에 돌려주어진다. 버튼 오브젝트에서는,lData 의 하위 바이트만이 의미가 있고, 상위 비트는 버튼이 밀렸을 때에 설정되어 버튼이 떼어 놓아졌을 때에 소거된다. 바꾸어 말하면, (lData & 0x80)가 제로가 아닐 때, 버튼이 밀리고 있게 된다.

DIDEVICEOBJECTDATA 형외의 멤버의 상세한 것에 대하여는, 「타임 스탬프와 순서 번호」를 참조할것.

다음의 코드는, 버퍼 (BufferSize 수의 요소를 포함한다)의 내용 전체를 취득해, 다양한 이벤트에 응답하는 예이다.

' objDIDev 는 DirectInputDevice 오브젝트이다.
Dim diDeviceData(1 To BufferSize) As DIDEVICEOBJECTDATA
Dim NumEvents As Integer
Dim i As Integer

NumEvents = objDIDev.GetDeviceData(diDeviceData, 0)
For i = 1 To NumEvents
Select Case diDeviceData(i). lOfs
Case DIMOFS_X
' x 축의 이동에 반응한다.

Case DIMOFS_Y
' y 축의 이동에 반응한다.

Case DIMOFS_BUTTON0
If diDeviceData(i). lData And &H80 Then
'왼쪽 버튼 압하에 반응한다.
Else
'왼쪽 버튼 릴리즈에 반응한다.
End If

End Select
Next i


마우스축데이터의 해석

마우스의 x 축 및 y 축으로 대해 돌려주어지는 데이터는, 커서는 아니고 마우스 자신의 동작을 나타낸다. 측정 단위는, 마우스의 하드웨어가 돌려주는 값에 근거하는 것이어, 픽셀이나 그 외의 화면 측정 형식과는 무관계하다. DirectInput 는 마우스 드라이버와 직접 통신하므로, 유저가 컨트롤 패널로 설정하는 마우스의 스피드와 가속값은, 이 데이터에 영향을 주지 않는다.

마우스로부터 돌려주어지는 축데이터는, 상대에서도 절대라도 좋다 ( 「상대 좌표와 절대 좌표」도 참조할것). 마우스는 상대적인 디바이스이므로 (죠이스틱과는 달라, 홈 포지션을 가지지 않는다), 디폴트에서는, 상대 데이터가 돌려주어진다.

[C++]

축모드는, 상대 데이터 또는 절대 데이터의 어느 쪽을 돌려주는지를 지정해서 , 디바이스를 취득하기 전으로 변경할 수 있는 프로퍼티이다 ( 「디바이스 프로퍼티」를 참조할것). 축모드를 "절대" 로 설정하려면 ,rguidProp 파라미터에 DIPROP_AXISMODE 값을 지정해,DIPROPDWORD 구조체의 dwData 멤버에 DIPROPAXISMODE_ABS 를 지정해,IDirectInputDevice7::SetProperty 를 호출한다.

[Visual Basic]

축모드는, 상대 데이터 또는 절대 데이터의 어느 쪽을 돌려주는지를 지정하는 것이지만, 디바이스를 취득하기 전으로 변경할 수 있는 프로퍼티이다 ( 「디바이스 프로퍼티」를 참조할것). 축모드를 "절대" 로 설정하려면 ,guid 파라미터에 DIPROP_AXISMODE 값을 지정해,DIPROPDWORD 형의 lData 멤버에 DIPROPAXISMODE_ABS 를 지정해,DirectInputDevice.SetProperty 를 호출한다.

마우스의 축모드가 "상대" 의 경우, 축좌표는, 마지막 값이 돌려주어진 이후, 축으로 따라 디바이스가 이동한 단위수를 나타낸다. 부의 값은, x축의 경우, 마우스가 좌방향으로 이동한 것, y 축의 경우, 유저로부터 멀어질 방향으로 마우스가 이동한 것, 및 z 축 (휠)이 앞에 회전한 것을 각각 가리킨다. 정의 값은 이것과 반대 방향의 움직임을 나타낸다.

축모드가 "절대" 의 경우, 축좌표는, 단순하게 DirectInput 가 수신한 상대 동작의 모든 누적 합계가 된다. 축좌표값은, 디바이스의 취득시에는, 특정의 값에 초기화되어 있지 않기 때문에, 어플리케이션은, 절대치를 미지의 원점을 기준으로 한 상대값으로서 취급할 필요가 있다. 디바이스를 취득했을 때는, 언제나 현재의 절대 위치를 기록해, 그것을 "가상 원점" 으로서 보존할 수가 있다. 이 가상 원점은, 그 후, 디바이스로부터 얻을 수 있는 절대 좌표로부터 뺄셈 하는 것으로써, 마우스가 취득시점으로부터 이동한 상대 거리를 계산할 수가 있다.

축좌표에 돌려주어지는 데이터는, 디바이스의 세분성 프로퍼티에 의해도 영향을 받는다. 마우스의 x 축과 y 축의 경우, 세분도는 보통 1 이며, 이것은, 값의 최소 변화가 1 인 것을 의미한다. 휠의 경우, 세분도가 1 보다 커질 수도 있다.


소실한 마우스 입력의 확인

[C++]

협조 레벨에 DISCL_FOREGROUND 를 설정한 상태로, 포커스가 다른 어플리케이션에 바뀌는 경우, 혹은 사용중의 어플리케이션외의 메뉴에 바뀌는 경우에서도, Windows 가 어플리케이션에 마우스를 강제적으로 릴리즈 시키는 일이 있으므로,IDirectInputDevice7::GetDeviceData 또는 IDirectInputDevice7::GetDeviceState 메소드로부터의 반환값 DIERR_INPUTLOST 를 체크해, 필요에 따라서 마우스를 재취득할 필요가 있다 ( 「디바이스의 취득」을 참조할것).

주 : DIERR_NOTACQUIRED 에러를 받았을 경우에는, 마우스의 재취득을 시도하지 않게 할 필요가 있다. 그렇게 하지 않으면 엔들레스 루프에 들어갈 우려가 있다. 취득은 실패해, DIERR_NOTACQUIRED 에러를 받는다고 하는 반복이 영원히 계속된다.

[Visual Basic]

협조 레벨에 DISCL_FOREGROUND 을 설정한 상태로, 포커스가 다른 어플리케이션에 바뀌는 경우, 혹은 사용중의 어플리케이션외의 메뉴에 바뀌는 경우에서도, Windows 가 어플리케이션에 마우스를 강제적으로 릴리즈 시키는 일이 있으므로,DirectInputDevice.GetDeviceData 또는 DirectInputDevice.GetDeviceStateMouse 메소드로부터의 DIERR_INPUTLOST 의 반환값을 체크해, 필요에 따라서 마우스를 재취득할 필요가 있다 ( 「디바이스의 취득」을 참조할것).

주 : DIERR_NOTACQUIRED 에러를 받았을 경우에는, 마우스의 재취득을 시도하지 않게 할 필요가 있다. 그렇게 하지 않으면 엔들레스 루프에 들어갈 우려가 있다. 취득은 실패해, DIERR_NOTACQUIRED 에러를 받는다고 하는 반복이 영원히 계속된다.


키보드 데이터

DirectInput 에 관한한, 키보드는, 텍스트 입력 디바이스는 아니고, 다수의 버튼을 갖춘 게임패드가 된다. 어플리케이션이 텍스트 입력을 필요로 할 때는, DirectInput 의 메소드를 이용해서는 안된다. 보통의 Windows 메세지로부터 데이터를 취득하는 것이 가장 간단하고, 문자 반복 및 물리 키의 가상 키에의 변환등의 Windows 서비스를 이용할 수가 있기 때문이다. 이것은, 영어 이외의 언어를 사용하는 경우에는 특히 중요하다. 영어 이외의 언어에서는 키의 특별한 해석이 필요한 것이 있기 때문이다.

[C++]

데이터를 취득하도록(듯이) 키보드 디바이스를 설정하려면 , 파라미터에 c_dfDIKeyboard 글로벌 변수를 지정해,IDirectInputDevice7::SetDataFormat 메소드를 호출한다 ( 「디바이스 데이터 형식 .」(을)를 참조할것).

[Visual Basic]

데이터를 취득하도록(듯이) 키보드 디바이스를 설정하려면 , 파라미터에 DIFORMAT_KEYBOARD 를 지정해,DirectInputDevice.SetCommonDataFormat 메소드를 호출한다.

이하의 주제에서는, 키보드 데이터의 취득과 해석의 상세를 설명한다.

  • 키보드의 직접 데이터
  • 키보드의 버퍼링 데이터
  • 키보드 데이터의 해석
  • 소실한 키보드 입력의 확인


키보드의 직접 데이터

[C++]

키보드의 현재 상태를 취득하려면 , 반환값 데이터를 보관 유지하는 256 바이트의 배열에의 포인터를 지정해,IDirectInputDevice7::GetDeviceState 메소드를 호출한다.

GetDeviceState 메소드는, Win32 GetKeyboardState 함수와 같게 동작해, 키보드의 현재 상태의 snapshot를 돌려준다. 각 키는, 256 바이트의 배열내의 1 바이트에 의해 나타내진다. 배열의 주소는,lpvData 파라미터로서 건네받은 것이다. 바이트의 상위 비트가 설정되어 있는 경우, 키는 누른 상태에 있다. 배열은 가장 편리하게, DirectInput 키보드 디바이스 정수에 의해 인덱스를 붙일 수 있고 있다 ( 「키보드 데이터의 해석」도 참조할것).

이하의 코드는, Esc 키의 압하에 응해 어떠한 처리를 실시하는 예이다.

// LPDIRECTINPUTDEVICE lpdiKeyboard; // 미리 초기화되어
// 취득되고 있다.

BYTE diKeys[256];
if (lpdiKeyboard->GetDeviceState(256, diKeys) == DI_OK)
{
if (diKeys[DIK_ESCAPE] & 0x80) DoSomething();
}
[Visual Basic]

키보드의 현재 상태를 취득하려면 ,DIKEYBOARDSTATE 형을 지정해 DirectInputDevice.GetDeviceStateKeyboard 를 호출한다.

GetDeviceState 메소드는, 키보드의 현재 상태의 snapshot를 돌려준다. 각 키는,DIKEYBOARDSTATE 형을 구성하는 256 바이트의 배열내의 1 바이트에 의해 나타내진다. 바이트의 상위 비트가 설정되어 있으면(자), 키는, 다운 상태에 있다. 배열은 가장 편리하게,CONST_DIKEYFLAGS 열거의 멤버에 의해 인덱스를 붙일 수 있고 있다 ( 「키보드 데이터의 해석」도 참조할것).

이하의 코드는, 현재 Esc 키가 압하되고 있는지 어떤지를 판정하는 예이다.

' objDIDev 는 DirectInputDevice 오브젝트이다.
Dim dev As DirectInputDevice
Dim KeyState As DIKEYBOARDSTATE

Call objDIDev.GetDeviceStateKeyboard(KeyState)
If (KeyState.Key(DIK_ESCAPE) And &H80) Then
'키는 압하되고 있다.
End If


키보드의 버퍼링 데이터

키보드로부터 버퍼링 데이터를 취득하려면 , 버퍼 사이즈를 설정해야 한다 ( 「디바이스 프로퍼티」를 참조할것). 이 순서는, 버퍼의 디폴트 사이즈가 제로이므로 불가결하다.

[C++]

또,DIDEVICEOBJECTDATA 구조체의 배열도 선언할 필요가 있다. 이 배열은, 최대로 버퍼 사이즈와 동수의 요소를 가질 수가 있다. 1 번의 호출로 버퍼의 내용 전체를 취득할 필요는 없지만, 배열내의 1 요소만을 보관 유지해, 버퍼가 비울 때까지 1 개(살)씩 이벤트를 취득할 수가 있다.

키보드 디바이스의 취득 후는,IDirectInputDevice7::GetDeviceData 메소드를 사용해 언제라도 버퍼를 조사하거나 플래시 하거나 할 수가 있다 ( 「버퍼링 데이터와 직접 데이터」를 참조할것).

DIDEVICEOBJECTDATA 배열의 각 요소는, 단일 키 상태 변화, 즉, 압하와 릴리즈를 나타낸다. DirectInput 는, 키보드로부터 직접 데이터를 취득하기 위해서, 컨트롤 패널의 문자 반복의 설정은 모두 무시한다. 즉, 키스트로크(keystroke)는, 키가 압하되고 있는 시간의 장단에 관계없이, 1 번 밖에 카운트 되지 않는다고 하는 것이 된다.

배열중의 요소가 어느 키를 가리킬까는, DirectInput 의키보드 디바이스 정수와DIDEVICEOBJECTDATA 구조체의 dwOfs 멤버를 비교하는 것으로써 확인할 수 있다 ( 「키보드 데이터의 해석」도 참조할것).

키 상태 변화 데이터는,DIDEVICEOBJECTDATA 구조체의 dwData 멤버에 저장 되고 있다. 의미를 가지는 것은,dwData 의 하위 바이트뿐이다. 상위 비트는, 키가 압하되었을 때에 설정되어 키가 떼어 놓아졌을 때에 소거된다. 바꾸어 말하면, (dwData & 0x80)가 제로가 아닐 때, 키가 밀리고 있게 된다.

[Visual Basic]

또,DIDEVICEOBJECTDATA 형의 배열도 선언할 필요가 있다. 이 배열은, 최대로 버퍼 사이즈와 동수의 요소를 가질 수가 있다. 1 번의 호출로 버퍼의 내용 전체를 취득할 필요는 없지만, 배열내의 1 요소만을 보관 유지해, 버퍼가 비울 때까지 1 개(살)씩 이벤트를 취득할 수가 있다.

키보드 디바이스의 취득 후는,DirectInputDevice.GetDeviceData 메소드를 사용해 언제라도 버퍼내의 이벤트를 조사하거나 플래시 하거나 할 수가 있다 ( 「버퍼링 데이터와 직접 데이터」를 참조할것).

DIDEVICEOBJECTDATA 배열의 각 요소는, 단일 키 상태 변화, 즉, 압하와 릴리즈를 나타낸다. DirectInput 는, 키보드로부터 직접 데이터를 취득하기 위해서, 컨트롤 패널의 문자 반복의 설정은 모두 무시한다. 즉, 키스트로크(keystroke)는, 키가 압하되고 있는 시간의 장단에 관계없이, 1 번 밖에 카운트 되지 않는다고 하는 것이 된다.

배열중의 요소가 어느 키를 가리킬까는,DIDEVICEOBJECTDATA 형의 lOfs 멤버를,CONST_DIKEYFLAGS 열거내의 정수와 비교하는 것으로 확인할 수 있다 ( 「키보드 데이터의 해석」도 참조할것).

키 상태 변화 데이터는,DIDEVICEOBJECTDATA 형의 lData 멤버에 저장 되고 있다. 의미를 가지는 것은,lData 의 하위 바이트뿐이다. 하위 바이트의 상위 비트는, 키가 압하되었을 때에 설정되어 키가 떼어 놓아졌을 때에 소거된다. 바꾸어 말하면, (lData And &H80)가 제로가 아닐 때, 키가 밀리고 있게 된다.


키보드 데이터의 해석

[C++]

여기에서는,IDirectInputDevice7::GetDeviceState 메소드 및 IDirectInputDevice7::GetDeviceData 메소드가 보고하는 데이터의 키의 식별에 대해 설명한다. GetDeviceData 로부터의 데이터의 해석에 대한 자세한 것은, 「타임 스탬프와 순서 번호」를 참조할것.

[Visual Basic]

여기에서는,DirectInputDevice.GetDeviceState 메소드 및 DirectInputDevice.GetDeviceData 메소드가 보고하는 데이터의 키의 식별에 대해 설명한다. GetDeviceData 로부터의 데이터의 해석에 대한 자세한 것은, 「타임 스탬프와 순서 번호」를 참조할것.

DirectInput 가 키보드를 읽어내는데 있어서, Windows 외 방법과 다른 것은, 다음의 중요한 점이다. 키보드 데이터는, 가상 키를 가리키는 것이 아니라, 실제의 물리적인 키, 즉, 스캔 코드를 가리킨다. 예를 들어, DIK_ENTER 는 메인 키보드의 Enter 키를 가리키지만, 숫자 패드의 Enter 키는 가리키지 않았다.

DirectInput 는, 확장 키보드 위에의 각 키에 대한 정수와 함께, 국제 키보드상에 있는 추가 키도 정의한다. NEC 키보드는, PC 확장 키보드와는 다른 스캔 코드를 지원 하고 있으므로, DirectInput 는, 가능한 한 NEC 스캔 코드를 PC 확장 스캔 코드로 변환한다.

또, 모든 PC 확장 키보드에, 새로운 Windows 키 (DIK_LWIN, DIK_RWIN, DIK_APPS)가 있는 것은 아니다. 키가 물리적으로도 사용 가능한지 어떤지를 확인하는 방법은 없다.

랩탑등의 소형 컴퓨터는, 풀 세트의 키를 이행 하고 있지 않다. 대신에, 일부의 키 (보통은 숫자 패드)를 다른 키와 다중화해, 보조 모드 키에 의해 선택하도록(듯이) 해, 개별의 스캔 코드를 만들지 않게 하고 있다.

키보드 서브 타입이 PC XT 또는 PC AT 키보드를 나타내고 있는 경우, DIK_F11, DIK_F12, 및 모든 확장 키 (0x7F 보다 큰 DIK_* 값을 가지는 키)는 이용할 수 없다. 게다가 PC XT 키보드에는 DIK_SYSRQ 가 없다.

일본어 키보드, 특히 NEC PC-98 키보드는, US 키보드와는 상당히 다른 키 세트를 포함하고 있다. 상세한 것에 대하여는, 「DirectInput 와 일본어 키보드」를 참조할것.


소실한 키보드 입력의 확인

[C++]

협조 레벨을 DISCL_FOREGROUND 로 설정한 상태로, 포커스가 다른 어플리케이션에 바뀌는 경우, Windows 가 어플리케이션에 키보드를 강제적으로 릴리즈 시키는 일이 있으므로,IDirectInputDevice7::GetDeviceData 메소드 또는 IDirectInputDevice7::GetDeviceState 메소드로부터의 DIERR_INPUTLOST 반환값을 체크해, 필요에 따라서 키보드를 재취득할 필요가 있다 ( 「디바이스의 취득」을 참조할것).

주 : DIERR_NOTACQUIRED 에러를 받았을 경우에는, 키보드의 재취득을 시도하지 않게 할 필요가 있다. 그렇게 하지 않으면 엔들레스 루프에 들어갈 우려가 있다. 취득은 실패해, DIERR_NOTACQUIRED 에러를 받는다고 하는 반복이 영원히 계속된다.

[Visual Basic]

협조 레벨을 DISCL_FOREGROUND 으로 설정한 상태로, 포커스가 다른 어플리케이션에 바뀌는 경우, Windows 가 어플리케이션에 키보드를 강제적으로 릴리즈 시키는 일이 있으므로,DirectInputDevice.GetDeviceData 메소드 또는 DirectInputDevice.GetDeviceStateKeyboard 메소드로부터의 DIERR_INPUTLOST 반환값을 체크해, 필요에 따라서 키보드를 재취득할 필요가 있다 ( 「디바이스의 취득」을 참조할것).

주 : DIERR_NOTACQUIRED 에러를 받았을 경우에는, 키보드의 재취득을 시도하지 않게 할 필요가 있다. 그렇게 하지 않으면 엔들레스 루프에 들어갈 우려가 있다. 취득은 실패해, DIERR_NOTACQUIRED 에러를 받는다고 하는 반복이 영원히 계속된다.


죠이스틱 데이터

[C++]

데이터를 취득하도록(듯이) 죠이스틱 디바이스를 설정하려면 , 파라미터에 c_dfDIJoystick 글로벌 변수를 지정해,IDirectInputDevice7::SetDataFormat 메소드를 호출한다 ( 「디바이스 데이터 형식」을 참조할것).

일부의 디바이스 드라이버는, 명시적으로 요구될 때까지 DirectInput 에 상태의 변화를 통지하지 않는 것이 있으므로, 죠이스틱의 데이터를 취득하기 전에는 반드시 IDirectInputDevice7::Poll 메소드를 호출하지 않으면 안 된다. 상세한 것에 대하여는, 「폴링과 이벤트」를 참조할것.

[Visual Basic]

데이터를 취득하도록(듯이) 죠이스틱 디바이스를 설정하려면 , 파라미터에 DIFORMAT_JOYSTICK 또는 DIFORMAT_JOYSTICK2 를 지정해,DirectInputDevice.SetCommonDataFormat 메소드를 호출한다 ( 「디바이스 데이터 형식」을 참조할것).

일부의 디바이스 드라이버는, 명시적으로 요구될 때까지 DirectInput 에 상태의 변화를 통지하지 않는 것이 있으므로, 죠이스틱의 데이터를 취득하기 전에는 반드시 DirectInputDevice.Poll 메소드를 호출하지 않으면 안 된다. 상세한 것에 대하여는, 「폴링과 이벤트」를 참조할것.

이하의 주제에서는, 죠이스틱 및 게임패드 또는 조종간등의 입력 디바이스로부터의 데이터의 취득과 해석을 설명한다.

  • 죠이스틱의 직접 데이터
  • 죠이스틱의 버퍼링 데이터
  • 죠이스틱축데이터의 해석
  • 소실한 죠이스틱 입력의 확인


죠이스틱의 직접 데이터

[C++]

죠이스틱의 현재 상태를 취득하려면 ,DIJOYSTATE 구조체 또는 DIJOYSTATE2 구조체에의 포인터를 지정해 IDirectInputDevice7::GetDeviceState 메소드를 호출한다. 어느 쪽의 구조체를 사용할까는,c_dfDIJoystick 이나 c_dfDIJoystick2 의 어디에서 데이터 형식이 설정되었는지에 의한다 ( 「디바이스 데이터 형식」을 참조할것). 구조체에 돌려주어지는 죠이스틱 상태에는, 축좌표, 버튼 상태, 및 시점 콘트롤러 상태등이 있다.

DIJOYSTATE 구조체의 최초의 7 개의 멤버가 축좌표를 보관 유지한다. 이 중 마지막 멤버 rglSlider 는 2 개의 값의 배열이다 ( 「죠이스틱축데이터의 해석」을 참조할것).

rgdwPOV 멤버에는, 4 개(살)까지의 시점 콘트롤러의 위치가 포함되어 있다. 이것들은, 북쪽으로부터 시계회전 (또는 전방)의 열매 각도의 100 배로 나타내진다. 중심 위치는 -1 으로서 보고된다. 5 개의 위치 밖에 가지지 않는 콘트롤러에서는,dwPOV 는 이하의 어느쪽이든 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 구조체에는, 축의 속도, 가속도, 포스, 및 토르크에 대한 정보를 제공하는 추가 멤버가 있다.

[Visual Basic]

죠이스틱의 현재 상태를 취득하려면 ,DirectInputDevice.GetDeviceStateJoystick 메소드 또는 DirectInputDevice.GetDeviceStateJoystick2 메소드를 호출한다. 어느 쪽의 메소드를 사용할까는, DIFORMAT_JOYSTICK 이나 DIFORMAT_JOYSTICK2 의 어디에서 데이터 형식이 설정되었는지에 의한다 ( 「디바이스 데이터 형식 .」(을)를 참조할것). state 파라미터에 돌려주어지는 죠이스틱 상태에는, 축좌표, 버튼 상태, 및 시점 콘트롤러 상태등이 있다.

DIJOYSTATE 형 또는 DIJOYSTATE2 형의 POV 멤버에는, 4 개(살)까지의 시점 콘트롤러의 위치가 포함되어 있다. 이것들은, 북쪽으로부터 시계회전 (또는 전방)의 열매 각도의 100 배로 나타내진다. 중심 위치는 -1 으로서 보고된다. 5 개의 위치 밖에 가지지 않는 콘트롤러의 경우,POV 는 이하의 어떤 것이나 1 개의 값을 취한다.

  • -1
  • 0
  • 9000
  • 18000
  • 27000

중심 위치로서-1 는 아니게 65,535 를 보고하는 드라이버도 있다. POV 표지가 중심 위치에 있을지 어떨지는, 다음과 같이 체크해야 한다.

Dim POVCentered As Boolean
POVCentered = (dwPOV And &HFFFF) = &HFFFF;

buttons 멤버는, 바이트 배열이다. 데이터형에 의해, 32 개 또는 128 개의 각 버튼에 1 요소가 대응한다. 각 버튼의 상위 비트는, 버튼이 다운 상태로 설정되어 업 상태 또는 존재하지 않는 경우에 소거된다.

DIJOYSTATE2 형에는, 축의 속도, 가속도, 포스, 및 토르크에 대한 정보를 제공하는 추가 멤버가 있다.

상세한 것에 대하여는, 「죠이스틱축데이터의 해석」을 참조할것.

참조

버퍼링 데이터와 직접 데이터


죠이스틱의 버퍼링 데이터

[C++]

죠이스틱으로부터 버퍼링 데이터를 취득하려면 , 우선, 버퍼 사이즈를 설정해 ( 「디바이스 프로퍼티」를 참조할것),DIDEVICEOBJECTDATA 구조체의 배열을 선언해야 한다. 이 배열은, 최고로 버퍼 사이즈와 동수의 요소를 가질 수가 있다. 1 번의 호출로 버퍼의 내용 전체를 취득할 필요는 없지만, 배열내의 1 요소만을 보관 유지해, 버퍼가 비울 때까지 1 개(살)씩 이벤트를 취득할 수가 있다.

디바이스의 취득 후는,IDirectInputDevice7::GetDeviceData 메소드를 사용해 언제라도 버퍼를 조사하거나 플래시 하거나 할 수가 있다 ( 「버퍼링 데이터와 직접 데이터」를 참조할것).

DIDEVICEOBJECTDATA 배열중의 각 요소는, 죠이스틱에 대한 단일 오브젝트 상태의 변화를 나타낸다. 예를 들어, 유저가 버튼 0 을 눌러 스틱을 비스듬하게 이동 하면,GetDeviceData 에게 건네진 배열 (3 개(살) 이상의 요소를 가지고 있는 경우,dwInOut 는 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)를 설정할 필요가 있다.

디바이스 오브젝트 상태 변화 데이터는,DIDEVICEOBJECTDATA 구조체의 dwData 멤버에 저장 된다. 축의 경우에는, 좌표값이 이 멤버중에 돌려주어진다. 버튼 오브젝트의 경우에는,dwData 의 하위 바이트만이 의미가 있다. 이 바이트의 상위 비트는, 버튼이 밀렸을 경우로 설정되어 버튼이 떼어 놓아졌을 경우에 소거된다.

다른 멤버에 대해서는, 「타임 스탬프와 순서 번호」를 참조할것.

[Visual Basic]

죠이스틱으로부터 버퍼링 데이터를 취득하려면 , 우선, 버퍼 사이즈를 설정해 ( 「디바이스 프로퍼티」를 참조할것),DIDEVICEOBJECTDATA 형의 배열을 선언해야 한다. 이 배열은, 최고로 버퍼 사이즈와 동수의 요소를 가질 수가 있다. 1 번의 호출로 버퍼의 내용 전체를 취득할 필요는 없지만, 배열내의 1 요소만을 보관 유지해, 버퍼가 비울 때까지 1 개(살)씩 이벤트를 취득할 수가 있다.

디바이스의 취득 후는,DirectInputDevice.GetDeviceData 메소드를 사용해 언제라도 버퍼내의 이벤트를 조사하거나 플래시 하거나 할 수가 있다 ( 「버퍼링 데이터와 직접 데이터」를 참조할것).

DIDEVICEOBJECTDATA 배열중의 각 요소는, 죠이스틱에 대한 단일 오브젝트 상태의 변화를 나타낸다. 예를 들어, 유저가 버튼 0 을 눌러 스틱을 비스듬하게 이동 하면,GetDeviceData 에게 건네진 배열 (3 개(살) 이상의 요소를 가지고 있는 경우)에는, 3 개의 요소를 묻을 수 있다. 이러한 요소는 각각, 버튼 0 의 압하, x 축의 변화, 및 y 축의 변화를 나타낸다. 메소드의 반환값은 3 이다.

배열중의 요소가 어느 오브젝트를 가리킬까는,DIDEVICEOBJECTDATA 형의 lOfs 멤버를,CONST_DIJOYSTICKOFS 열거내의 정수와 비교하는 것으로 확인할 수 있다. 이러한 각각의 값은,DIJOYSTATE 형중의 오브젝트에 대한 데이터의 오프셋(offset)와 동일하다. 예를 들어, DIJOFS_BUTTON0 가 돌려주는 값은,DIJOYSTATE 형중의 buttons(0) 오프셋(offset)와 동일하다.

데이터 형식이 DIFORMAT_JOYSTICK2 로 설정되었을 경우는,DIJOYSTATE 내에 존재하는 모든 디바이스 오브젝트의 오프셋(offset) 정수를 사용할 수가 있다. 다만,DIJOYSTATE2 의 추가 멤버에 표현되는 디바이스 오브젝트에는, 독자적인 오프셋(offset)를 설정할 필요가 있다. 이 형태의 내부 구조는, Dinput.h 헤더 파일에 포함되는 동명의 C++ 구조체와 같다.

디바이스 오브젝트 상태 변화 데이터는,DIDEVICEOBJECTDATA 형의 lData 멤버에 저장 된다. 축의 경우에는, 좌표값이 이 멤버중에 돌려주어진다. 버튼 오브젝트의 경우에는,lData 의 하위 바이트만이 의미가 있다. 이 바이트의 상위 비트는, 버튼이 밀렸을 경우로 설정되어 버튼이 떼어 놓아졌을 경우에 소거된다.

다른 멤버에 대해서는, 「타임 스탬프와 순서 번호」를 참조할것.


죠이스틱축데이터의 해석

죠이스틱의 축값은, 마우스의 축값과 같다. 스틱을 오른쪽으로 작동시키면(자) 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 의 사이에 존재한다.

[C++]

죠이스틱 프로퍼티의 상세한 것에 대하여는, 이하를 참조할것.

  • IDirectInputDevice7::GetProperty
  • IDirectInputDevice7::SetProperty
  • DIPROPRANGE
[Visual Basic]

죠이스틱 프로퍼티의 상세한 것에 대하여는, 이하를 참조할것.

  • DirectInputDevice.GetProperty
  • DirectInputDevice.SetProperty
  • DIPROPRANGE

죠이스틱으로부터 돌려주어지는 축좌표는, 상대에서도 절대라도 좋다 ( 「상대 좌표와 절대 좌표」도 참조할것). 죠이스틱은 절대 디바이스이므로 (마우스와는 달라, 축으로 따라 무한하게는 이동할 수 없다), 디폴트에서는 절대 데이터가 돌려주어진다. 죠이스틱의 축모드가 "상대" 로 설정되어 있는 경우에는, 축좌표는, 마지막 값이 돌려주어지고 나서 이후의 축으로 휜 이동의 단위수를 나타낸다.

[C++]

축모드는, 상대 데이터 또는 절대 데이터의 어느 쪽을 돌려주는지를 지정해서 , 디바이스를 취득하기 전으로 변경할 수 있는 프로퍼티이다 ( 「디바이스 프로퍼티」를 참조할것). 축모드를 "상대" 로 설정하려면 ,rguidProp 파라미터에 DIPROP_AXISMODE 값을 지정해,DIPROPDWORD 구조체의 dwData 멤버에 DIPROPAXISMODE_REL 를 지정해,IDirectInputDevice7::SetProperty 메소드를 호출한다.

[Visual Basic]

축모드는, 상대 데이터 또는 절대 데이터의 어느 쪽을 돌려주는지를 지정해서 , 디바이스를 취득하기 전으로 변경할 수 있는 프로퍼티이다 ( 「디바이스 프로퍼티」를 참조할것). 축모드를 "절대" 로 설정하려면 ,guid 파라미터에 DIPROP_AXISMODE 값을 지정해,DIPROPLONG 형의 lData 멤버에 DIPROPAXISMODE_ABS 를 지정해,DirectInputDevice.SetProperty 를 호출한다.


소실한 죠이스틱 입력의 확인

죠이스틱을 foreground 모드로 사용하는 ( 「협조 레벨」을 참조할것) 경우에는, 포커스가 다른 어플리케이션에 바뀔 때, 디바이스를 상실하는 일이 있다.

[C++]

IDirectInputDevice7::GetDeviceData 메소드 또는 IDirectInputDevice7::GetDeviceState 메소드로부터의 DIERR_INPUTLOST 반환값을 체크해, 필요에 따라서 죠이스틱을 재취득할 수가 있다 ( 「디바이스의 취득」을 참조할것).

주 : DIERR_NOTACQUIRED 에러를 받았을 경우에는, 죠이스틱의 재취득을 시도하지 않게 할 필요가 있다. 그렇게 하지 않으면 엔들레스 루프에 들어갈 우려가 있다. 취득은 실패해, DIERR_NOTACQUIRED 에러를 받는다고 하는 반복이 영원히 계속된다.

키보드나 마우스와는 달라, Windows 시스템은 죠이스틱을 사용하지 않기 때문에, 어플리케이션이 백그라운드로 이행하는 경우를 제외해, 죠이스틱에의 액세스권이 없어질 것은 없다. 따라서, 어느 쪽의 메소드에서도, WM_ACTIVATE 메세지에 응해 디바이스를 재취득할 수 있다.

[Visual Basic]

DirectInputDevice.GetDeviceData 메소드 또는 DirectInputDevice.GetDeviceState 메소드로부터의 DIERR_INPUTLOST 반환값을 체크해, 필요에 따라서 죠이스틱을 재취득할 수가 있다 ( 「디바이스의 취득」을 참조할것).

주 : DIERR_NOTACQUIRED 에러를 받았을 경우에는, 죠이스틱의 재취득을 시도하지 않게 할 필요가 있다. 그렇게 하지 않으면 엔들레스 루프에 들어갈 우려가 있다. 취득은 실패해, DIERR_NOTACQUIRED 에러를 받는다고 하는 반복이 영원히 계속된다.


데이터 출력

[C++]

휴먼 인터페이스 디바이스는, 입력의 생성과 같게 출력을 취급할 수가 있다. IDirectInputDevice7::SendDeviceData 메소드는, 데이터의 패킷을 그러한 디바이스에 보낸다.

SendDeviceData 는, 반대로 IDirectInputDevice7::GetDeviceData 로서 표시할 수가 있다. SendDeviceData 메소드와 같이,GetDeviceData 메소드는, 데이터의 기본 단위로서 DIDEVICEOBJECTDATA 구조체를 사용한다. 이 경우,dwOfs 멤버에 포함되는 것은, 디바이스의 데이터 형식의 오프셋(offset)는 아니고, 데이터에 관련지을 수 있었던 디바이스 오브젝트의 인스턴스 ID 이다(오프셋(offset) 식별자는, 선택된 데이터 형식에서의 입력을 제공하는 디바이스 오브젝트 (을) 위해서만 존재하므로, 출력 밖에 인정하지 않는 오브젝트는, 오프셋(offset)를 가지는 것조차 없다). dwData 멤버에는, 그 오브젝트에 적절한 데이터가 포함된다. dwTimeStamp 및 dwSequence 멤버는 사용하지 않는다. 이러한 멤버는, 제로로 설정해야 한다.

디바이스에 데이터를 보내려면 , 최초로 DIDEVICEOBJECTDATA 구조체의 배열을 설정해, 요구된 수의 요소를 데이터로 묻고 나서, 사용되는 주소와 요소수를 SendDeviceData 에 건네준다. 복수의 디바이스 오브젝트에 대한 데이터는, 디바이스에 보내지는 단일 패킷에 결합된다.

데이터 패킷의 형식은, 패킷내의 사용되지 않는 필드의 처리 방법과 같아, 디바이스에 따라서 다르다. 디바이스에 따라서는, 데이터가 제공되지 않는 경우에는, 오브젝트 상태로 변경이 없으면 간주, 필드를 옵션으로서 취급하는 일이 있다. 일반적으로는, 특히 데이터가 필드에 제공되지 않는 경우여도, 모든 필드는 중요하다. 예를 들어, 단일의 키보드 LED 에 데이터를 보내면(자), 다른 2 개의 LED 의 데이터는 제로로, 2 개의 LED 는 오프이라고 가정된다. 그러나, 이 2 개의 LED 의 데이터로서 마지막에 송신된 값을 사용하는 경우에는, DISDD_CONTINUE 플래그를 사용해 이 동작을 무효로 할 수 있다.

다음의 예에서는, 코드가 반복해 실행되는 경우, 키보드 위에의 LED (IDirectInputDevice7 인터페이스 pdev 에 의해 나타내진다)는 반복해 점멸한다. 디바이스 오브젝트 식별자,NumLockID,CapsLockID, 및 ScrollLockID 는, 디바이스 오브젝트의 열거중인가, 또는 IDirectInputDevice7::GetObjectInfo 를 호출하는 것으로,DIDEVICEOBJECTINSTANCE 구조체의 dwType 멤버로부터 사전에 취득되고 있다. LED 상태는, 데이터 바이트의 상위 비트에 의해 결정되는 것으로 한다.

void FlashLEDs(void)
    {
static int     rgiBits[] = { 1, 2, 4, 2 };
static int     iLooper = 0;
DWORD       cdod = 3;         // 항목수.
DIDEVICEOBJECTDATA rgdod[3];
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;
                                           // 1,0,0,0,...
rgdod[1]. dwData = (rgiBits[iLooper] & 2) ? 0x80 : 0;
                                           // 0,1,0,1,...
rgdod[2]. dwData = (rgiBits[iLooper] & 4) ? 0x80 : 0;
                                           // 0,0,1,0,...

iLooper = (iLooper + 1) % ARRAYSIZE(rgiBits); // 0 에서 3 까지 루프 한다.

hres = IDirectInputDevice7_SendDeviceData(pdev,
sizeof(DIDEVICEOBJECTDATA),
rgdod, &cdod, 0);
    }
[Visual Basic]

휴먼 인터페이스 디바이스는, 입력의 생성과 같게 출력을 인지할 수가 있다. 그러한 디바이스에 데이터 패킷을 송신하려면 ,DirectInputDevice.SendDeviceData 메소드를 사용한다.

SendDeviceData 는, 반대로 DirectInputDevice.GetDeviceData 로서 표시할 수가 있다. SendDeviceData 메소드와 같이,GetDeviceData 메소드는, 데이터의 기본 단위로서 DIDEVICEOBJECTDATA 형을 사용한다. 이 경우,lOfs 멤버에 포함되는 것은, 디바이스의 데이터 형식의 오프셋(offset)는 아니고, 데이터에 관련지을 수 있었던 디바이스 오브젝트의 인스턴스 ID 이다. 이 ID 는, 디바이스 오브젝트를 열거한 후에,DirectInputDeviceObjectInstance.GetType 에 의해 돌려주어지는 값으로부터 추출할 수 있다(오프셋(offset) 식별자는, 선택된 데이터 형식에서의 입력을 제공하는 디바이스 오브젝트 (을) 위해서만 존재하므로, 출력 밖에 인정하지 않는 오브젝트는, 오프셋(offset)를 가지는 것조차 없다). lData 멤버에는, 그 오브젝트에 적절한 데이터가 포함된다. lTimeStamp 및 lSequence 멤버는 사용하지 않는다. 이러한 멤버는, 제로로 설정해야 한다.

디바이스에 데이터를 보내려면 , 최초로 DIDEVICEOBJECTDATA 형의 배열을 설정해, 요구된 수의 요소를 데이터로 묻고 나서, 사용하는 주소와 요소수를 SendDeviceData 에 건네준다. 다른 디바이스 오브젝트의 데이터는, 디바이스에 보내지는 단일 패킷에 결합된다.

데이터 패킷의 형식은, 패킷내의 사용되지 않는 필드의 처리 방법과 같아, 디바이스에 따라서 다르다. 디바이스에 따라서는, 데이터가 제공되지 않는 경우에는, 오브젝트 상태로 변경이 없으면 간주, 필드를 옵션으로서 취급하는 일이 있다. 일반적으로는, 특히 데이터가 필드에 제공되지 않는 경우여도, 모든 필드는 중요하다. 예를 들어, 단일의 키보드 LED 에 데이터를 보내면(자), 다른 2 개의 LED 의 데이터는 제로로, 그러한 LED 는 오프이라고 가정된다. 그러나, 이 2 개의 LED 의 데이터로서 마지막에 송신된 값을 사용하는 경우에는, DISDD_CONTINUE 플래그를 사용해 이 동작을 무효로 할 수 있다.


force feedback

force feedback란, 입출력 디바이스 (예를 들어, 죠이스틱에 짜넣어지고 있는 모터)에 푸쉬 혹은 저항을 생성하는 것이다. DirectInput 에서는, 호환성이 있는 드라이버를 가지는 디바이스에 force feedback 이펙트를 생성할 수가 있다.

이하의 주제에서는, force feedback의 개념을 소개한다.

  • force feedback의 기본 개념
  • 이펙트의 열거
  • 파일로부터의 이펙트의 read
  • 지원 되는 이펙트에 대한 정보
  • 이펙트의 생성
  • 이펙트의 방향
  • 엔벌로프와 오프셋(offset)
  • 이펙트의 플레이백
  • 이펙트의 다운로드와 언로드
  • 이펙트의 변경
  • 게인
  • force feedback 상태
  • 이펙트 오브젝트의 열거
  • 이펙트의 타입


force feedback의 기본 개념

force feedback의 쳐 특수한 인스턴스를 "이펙트" 라고 말해, 푸쉬나 저항을 "포스" 라고 말한다. 많은 이펙트는, 이하의 카테고리의 어느 쪽인가에 속한다.

  • 정수 포스 － 단일 방향의 일정한 포스
  • 경사 포스 － 일정한 비율로 크기가 증가 또는 감소하는 포스
  • 주기적 이펙트 － 정의된 파형 패턴으로 변화하는 포스.
  • 조건 － 유저에 의한 입력에만 반응해 발생하는 포스. 예를 들어, 죠이스틱의 동작에 대해서 저항을 낳는 마찰 이펙트나, 죠이스틱이 있는 위치로부터 작동된 다음에, 스틱을 그 위치에 되돌리려고 하는 스프링 이펙트이다.

포스의 강함을 "매그니튜드" 라고 한다. 매그니튜드는, 0 (포스 없음)에서 10,000 (디바이스의 최대 포스로, C/C++ 의 경우, Dinput.h 로 DI_FFNOMINALMAX 로서 정의되고 있다)의 범위의 단위로 측정된다. 부의 값은, 반대의 방향에 있는 포스를 나타낸다. 매그니튜드는 비례적인 단위이다. 예를 들어, 포스 10,000 은 포스 5,000 의 2 배의 크기이다.

경사 포스에는, 초기 매그니튜드와 종기 매그니튜드가 있다. 주기적 이펙트에서는, 기본적 매그니튜드는 물결의 버텍스에서의 포스가 된다.

포스의 "방향" 은 포스가 올 방향이다. 어느 축위에의정의 포스는 정으로부터 부 쪽에 누르는 힘이다.

또, 이펙트에는 "계속 시간" 이 있다. 이것은, 마이크로 세컨드 단위로 측정된다. 주기적 이펙트에는,"주기" 또는 1 사이클의 계속 시간이 있어, 이것들도 마이크로 세컨드 단위로 측정된다. 주기적 이펙트의 "국면" 이란, 재생 시작 개소의 물결에 따라 존재하는 점이다.

다음의 그림은, 매그니튜드 5,000, 즉 디바이스의 최대 포스의 반에서의 톱니 주기적 이펙트를 나타낸다. 수평축은 이펙트의 계속 시간을, 수직축은 매그니튜드를 각각 나타낸다. 중앙선보다 위에의점은, 이펙트에 정의된 방향에 있어서의 정의 포스를, 아래의 점은 부의 포스, 즉 반대 방향의 포스를 나타낸다.

한층 더 포스는,"엔벌로프" 에 의해 형성된다. 엔벌로프는,"어택값" 과 "페이드값" 을 정의한다. 어택값과 페이드값에 의해, 시점과 종점간의 이펙트의 매그니튜드가 변화한다. 어택과 페이드에는 계속 시간이 있다. 계속 시간은, 매그니튜드가 "보관 유지값" 에 도달하는데 필요한 시간, 또는 보관 유지값으로부터 빗나가는데 필요로 하는 시간을 결정한다. 보관 유지값이란, 이펙트의 중간부의 매그니튜드이다.

다음의 그림은, 엔벌로프를 나타내고 있다. 어택 레벨은 8,000, 페이드 레벨은 1,000 으로 설정되어 있다. 보관 유지 레벨은, 이 엔벌로프를 적용한 포스의 기본적 매그니튜드에 의해 정의된다. 이 예에서는 보관 유지 레벨은 5,000 이다. 이 케이스에서는, 어택이 보관 유지보다 큰 것에 주의 해야 한다. 이것은, 이펙트의 초기에 강한 킥을 주게 된다. 어택 레벨과 페이드 레벨의 양쪽 모두가 보관 유지 레벨보다 큰 일도 작은 일도 있다.

다음의 그림은, 최초의 그림의 주기적 이펙트에 엔벌로프를 적용한 결과를 나타낸다. 매그니튜드의 부측에서는, 엔벌로프가 거울 사본이 되어 있다. 어택값 8,000 이 의미하는 것은, 한편의 방향의 포스의 초기 매그니튜드가, 최대 포스의 80% 가 된다고 하는 것이다.

주기적 이펙트와 조건은, 모두,"오프셋(offset)" 의 추가에 의해도 변경할 수가 있다. 오프셋(offset)란, 파형을 기본 레벨보다 위 또는 아래에 쉬프트 하는 양을 정의하는 것이다. 톱니의 예에 정의 오프셋(offset)를 적용한 실제의 이펙트에서는, 정의 포스를 강하게 해 부의 포스를 약하게 하게 된다. 즉, 포스의 파형에서는, 한방향에의 물결의 버텍스가, 한편 향에의 물결의 버텍스보다 높아진다.

또, 이펙트의 전체적 매그니튜드는,"게인" 에 의해 증감 가능하다. 게인이란, 오디오에 있어서의 음량 컨트롤에 유사하고 있다. 단일의 게인값을 1 개의 디바이스의 모든 이펙트에 적용할 수 있으므로, 이것을 사용해, 여러가지 하드웨어에 대해서 포스를 강하게 하거나 약하게 하거나 하는 보정을 더할 수가 있다. 또, 유저의 좋아해에 대응할 수도 있다.


이펙트의 열거

[C++]

IDirectInputDevice7::EnumEffects 메소드는, 다양한 종류의 이펙트에 관해서, 디바이스로 제공되는 지원에 대한 정보를 돌려준다.

"지원 되는 이펙트" 와 "생성되는 이펙트" ("이펙트 오브젝트")의 양자를 구별하는 것이 중요하다. 지원 되는 이펙트는,엔벌로프에 의해 형성할 수 있는 정수 포스이다. 그러나, 이 이펙트에는, 매그니튜드, 방향, 계속 시간,어택 또는페이드등의 프로퍼티가 전혀 없다. 어플리케이션으로 이펙트 오브젝트를 생성 하면나무는, 이러한 프로퍼티를 설정한다. 지원 되는 이펙트는, 각각 다른 파라미터를 가지는 많은 이펙트 오브젝트에 의해 나타낼 수가 있다. 예를 들어, 각각 다른 계속 시간, 매그니튜드 및 방향을 가지는 복수의 정수 포스에 의해 나타낼 수가 있다.

생성된 이펙트의 열거에 대해서는, 「이펙트 오브젝트의 열거」를 참조할것.

다른 DirectInput 열거와 같게,IDirectInputDevice7::EnumEffects 메소드에는 콜백 함수가 필요하다. 문서에서는 이 함수는 플레이스홀더명의 DIEnumEffectsCallback 로 나타내지고 있지만, 좋아하는 이름을 붙일 수가 있다. 이 함수는, 열거되는 이펙트 마다 불려 간다. 이 함수내에서는, 각각의 이펙트에 대한 GUID 를 취득할 수 있어 하드웨어 지원의 범위에 대한 정보를 취득할 수 있어 게다가 1 개(살) 또는 그 이상의 이펙트 오브젝트를 생성해, 그 오브젝트의 메소드를 사용해 이펙트를 조작할 수가 있다.

이하의 예는, 열거를 시작 하는 IDirectInputDevice7::EnumEffects 메소드를 호출하는 코드이다. 이 콜백 함수의 pvRef 파라미터는 32 비트의 임의의 값을 취할 수가 있다. 이 경우, 이 파라미터는 디바이스 인터페이스에의 포인터이며, 디바이스가 지원 하는 이펙트에 대한 정보의 취득과 이펙트 오브젝트의 생성에 사용된다.

HRESULT hr;
// LPDIRECTINPUTDEVICE lpdid2;  // 초기화가 끝난 상태.

BOOL CALLBACK DIEnumEffectsCallback(LPCDIEFFECTINFO pdei,
LPVOID pvRef)
{
LPDIRECTINPUTDEVICE2 lpdid = pvRef;  // 호출 디바이스에의 포인터.
LPDIRECTINPUTEFFECT lpdiEffect;   // 생성된 이펙트에의 포인터.
DIEFFECT      diEffect;   // 생성된 이펙트용의 파라미터.
DICONSTANTFORCE   diConstantForce; // 타입 고유 파라미터.
                                          // for diEffect

if (DIEF_GETTYPE(pdei->dwEffType) == DIEFFT_CONSTANTFORCE)
    {
/* 이펙트 타입 (pdei 로부터)의 지원 정보를
추출해, 거기에 응해 이펙트를 적응시키는 것
하지만 할 수 있다. 예를 들어, 이 디바이스는, 이 타입
의 이펙트에서는 엔벌로프를 지원 하지 않는다. */
       .
       .
       .
// 1 개(살) 또는 그 이상의 정수 포스 이펙트를 생성한다.
// 각각 붙어, DICONSTANTFORCE 와
// DIEFFECT 구조체를 초기화해야 한다.
// 「이펙트의 생성」으로 자세한 예를 참조할것.
       .
       .
       .
hr = pdid->CreateEffect(pdei->guid,
&diEffect,
&lpdiEffect,
NULL);
       .
       .
       .
    }
// 다른 타입의 이펙트에 대해서도 같이.
   .
   .
   .

return DIENUM_CONTINUE;
} // 콜백의 종료.
.
.
.
// 콜백의 시동.
hr = lpdid2->EnumEffects(&EnumEffectsCallback,
lpdid2, DIEFT_ALL);

이펙트를 초기화하는 방법의 상세한 것에 대하여는, 「이펙트의 생성」을 참조할것.

[Visual Basic]

DirectInputDevice.GetEffectsEnum 메소드는, 디바이스에 의해 지원 되는 이펙트를 열거한다. 이 메소드는, 지원 되는 이펙트의 콜렉션을 나타내는 DirectInputEnumEffects 오브젝트를 돌려준다. DirectInputEnumEffects 의 각 메소드를 사용하면(자), 특정의 이펙트에 관한 정보를 취득할 수 있다.

"지원 되는 이펙트" 와 "생성되는 이펙트" ("이펙트 오브젝트")의 양자를 구별하는 것이 중요하다. 지원 되는 이펙트는,엔벌로프 에 의해 형성할 수 있는 정수 포스이다. 그러나, 이 이펙트에는, 매그니튜드, 방향, 계속 시간,어택 또는페이드등의 프로퍼티가 전혀 없다. 어플리케이션으로 이펙트 오브젝트를 생성 하면나무는, 이러한 프로퍼티를 설정한다. 지원 되는 이펙트는, 각각 다른 파라미터를 가지는 많은 이펙트 오브젝트에 의해 나타낼 수가 있다. 예를 들어, 각각 다른 계속 시간, 매그니튜드 및 방향을 가지는 복수의 정수 포스에 의해 나타낼 수가 있다.

다음의 코드는, 어플리케이션이 하드웨어 고유의 이펙트를 열거해, Microsoft® SideWinder® 죠이스틱에 의해 지원 되는 고유의 이펙트를 찾는 예이다. 목적의 이펙트가 발견되지 않는 경우는, 어플리케이션은 표준 이펙트의 어느쪽이든을 대용한다.

Const BasketballDribble = _
"{E84CD1AC-81FA-11D0-94AB-0080C74C7E95}"
Dim diEnumEffects as DirectInputEnumEffects
Dim EffGuid As String
Dim i as Integer

' diDev 는 DirectInputDevice 오브젝트이다.
Set diEnumEffects = didev.GetEffectsEnum(DIEFT_HARDWARE)
For i = 1 To diEnumEffects.GetCount
If diEnumEffects.GetEffectGuid(i) = BasketballDribble Then
EffGuid = BasketballDribble
Exit For
End If
Next i
If EffGuid <> BasketballDribble Then
EffGuid = "GUID_Sine"
'여기서, 열거된 드리블의 파라미터를 설정한다.
End If

'마지막에 EffGuid 를 DirectInputDevice.CreateEffect 에 건네준다.


파일로부터의 이펙트의 read

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 는, 이펙트 파일을 지원 하고 있지 않다.

[C++]

DirectX SDK 로 제공되는 Force Editor , 또는 같은 파일 포맷을 사용하는 다른 어플리케이션을 사용해, 이펙트를 디자인해, 파일에 보존할 수가 있다. 실행시에 이러한 이펙트를 읽어들이는 것으로, 임의의 어플리케이션으로 사용할 수가 있다.

이펙트를 읽어들이려면 ,IDirectInputDevice7::EnumEffectsInFile 메소드를 호출한다. 디폴트에서는, 열거는 표준의 DirectInput 이펙트로 한정되지만, DIFEF_INCLUDENONSTANDARD 플래그를 설정하는 것으로, 이외의 이펙트를 열거할 수 있다. 또, DIFEF_MODIFYIFNEEDED 플래그를 설정 하면, 필요에 따라서, 이펙트가 디바이스에 대해서 작용하도록(듯이), 각 이펙트의 파라미터의 변경을 DirectInput 에 지시할 수가 있다(예를 들어, 2 개의 축으로 대해 생성 된 이펙트를, 단일축의 차의 핸들에 대해서 작용시킬 수가 있다).

다음의 샘플 코드에서는, 최초의 3 개의 표준 이펙트가 파일로부터 읽혀 DirectInputEffect 오브젝트로서 생성 된다.

// g_lpdid7 는, force feedback 디바이스에의 유효한
// IDirectInputDevice7 포인터이다.

// 이펙트 포인터의 배열은, 글로벌하게 선언된다.
LPDIRECTINPUTEFFECT pEff[3];
.
.
.
g_lpdid7->EnumEffectsInFile("FEdit1.ffe", EnumEffectsInFileProc,
NULL, DIFEF_MODIFYIFNEEDED);
.
.
.

이하의 콜백 프로시저는, DIENUM_STOP 가 돌려주어질 때까지, 이펙트 파일내의 이펙트 마다 불려 간다.

BOOL CALLBACK EnumEffectsInFileProc(LPCDIFILEEFFECT lpdife,
        LPVOID pvRef)

    {
HRESULT hr;
static int  i;

//  DIFEF_MODIFYIFNEEDED 플래그가 건네받았으므로,
// 이펙트 파라미터는 lpdife->lpDiEffect 로 변경된다.

hr = g_lpdid7->CreateEffect(lpdife->GuidEffect,
lpdife->lpDiEffect,
&pEff[i], NULL);
if (FAILED(hr))
        {
// 에러 처리
        }
if (++i > 2) return DIENUM_STOP;
else return DIENUM_CONTINUE;
    }


지원 되는 이펙트에 대한 정보

[C++]

IDirectInputDevice7::GetEffectInfo 메소드를 사용하면(자), GUID 가 판명하고 있는 이펙트에 대해, 그 디바이스의 지원 정보를 취득할 수 있다. 이 메소드는,DIEFFECTINFO 구조체로 돌려주어지는 정보와 같은 정보를 열거중에 취득한다. 상세한 것에 대하여는, 「이펙트의 열거」를 참조할것.

다음의 샘플 코드는,EffectGuid 변수에 GUID 가 저장 되고 있는 이펙트에 관한 정보를 취득해, 이펙트를 정지 또는 재부팅 하지 않고 이펙트의 방향을 변경할 수 있을지 어떨지를 조사한다.

DIEFFECTINFO diEffectInfo;
diEffectInfo.dwSize = sizeof(DIEFFECTINFO);
lpdid2->GetEffectInfo(&diEffectInfo, EffectGuid);
if (diEffectInfo.dwDynamicParams & DIEP_DIRECTION)
{
// 파라미터는 동적으로 리셋 할 수 있다.
}
[Visual Basic]

DirectX for Visual Basic 에서는, 지원 되는 이펙트에 관한 정보는,DirectInputEnumEffects 열거 오브젝트로부터 취득해야 한다. 「이펙트의 열거」를 참조할것.

다음의 샘플 코드는, 최초로 열거된 이펙트에 관한 정보를 취득해, 그 이펙트를 정지 또는 재부팅 하지 않고 이펙트의 방향을 변경할 수 있을지 어떨지를 조사한다.

' diEnumEffects 는 초기화된 DirectInputEnumEffects 오브젝트이다.
Dim params As Long
params = diEnumEffects.GetDynamicParams(1)
If params And DIEP_DIRECTION Then
Debug.Print "이펙트의 방향은 동적이다. "
End If


이펙트의 생성

[C++]

이펙트 오브젝트를 생성하려면 ,IDirectInputDevice7::CreateEffect 메소드를 사용한다. 다음의 샘플 코드로,pdev2 는 인터페이스의 인스턴스를 가리키고 있다. 이 예에서는, 반초간에 전력으로 죠이스틱을 유저로부터 멀어질 방향에 당긴다고 한다, 매우 단순한 이펙트가 생성된다.

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 = 0.5 * DI_SECONDS;
diEffect.dwSamplePeriod = 0;               // 디폴트값
diEffect.dwGain = DI_FFNOMINALMAX;         // 스케일링 없음
diEffect.dwTriggerButton = DIEB_NOTRIGGER; // 버튼 응답은 아니다.
diEffect.dwTriggerRepeatInterval = 0;   // 이용할 수 없다.
diEffect.cAxes = 2;
diEffect.rgdwAxes = &dwAxes;
diEffect.rglDirection = &lDirection;
diEffect.lpEnvelope = NULL;
diEffect.cbTypeSpecificParams = sizeof(DICONSTANTFORCE);
diEffect.lpvTypeSpecificParams = &diConstantForce;

hr = pdev2->CreateEffect(GUID_ConstantForce,
&diEffect,
&lpdiEffect,
NULL);

이 메소드 호출에서는, 최초의 파라미터는, 생성되는 이펙트에 관련지을 수 있었던 지원 되는 이펙트를 나타낸다. 이 예에서는, Dinput.h 로 정의 끝난 GUID 가운데 1 개를 사용하고 있다. 정의 끝난 GUID 를 사용하는 경우, 디바이스가 이 이펙트를 지원 하지 않으면 호출은 실패한다.

제 2 의 파라미터는,DIEFFECT 구조체로 지정되고 있는 파라미터를 설정한다.

제 3 의 파라미터는, 호출이 성공했을 경우에, 이펙트 오브젝트에의 포인터를 받는다.

DIEFF_POLAR 플래그는, 포스의 방향으로 사용하는 좌표의 종류를 지정한다 ( 「이펙트의 방향」을 참조할것). 이 플래그는 DIEFF_OBJECTOFFSETS 와 짜 합쳐진다. 이것은, 다른 멤버로 사용되는 버튼이나 축도, 이 디바이스의 DIDATAFORMAT 구조체 중(안)에서 오프셋(offset)에 의해 식별된다, 라고 하는 것을 나타낸다. 이 대신에 DIEFF_OBJECTIDS 플래그를 사용할 수가 있다. 이 플래그는, 오브젝트가 IDirectInputDevice7::EnumObjects 메소드로 열거되었을 때, 그 오브젝트에 대해서 돌려주어지는 DIDEVICEOBJECTINSTANCE 구조체의 dwType 멤버에 의해 버튼과 축이 식별된다, 라고 하는 것을 의미하고 있다.

DIEFFECT 구조체의 멤버의 상세한 것에 대하여는, 「이펙트의 방향」을 참조할것.

[Visual Basic]

이펙트 오브젝트를 생성하려면 ,DirectInputDevice.CreateEffect 메소드를 사용한다. 다음의 샘플 코드에서는,didev 는DirectInputDevice 오브젝트를 가리키고 있다. 이 예에서는, 반초간에 전력으로 죠이스틱을 유저로부터 멀어질 방향에 당긴다고 한다, 매우 단순한 이펙트가 생성된다.

Dim effectInfo As DIEFFECT
Dim objDIEffect As DirectInputEffect

With effectInfo

. constantForce.lMagnitude = 10000
. lGain = 10000
. lDuration = 500000
. x = 18000
. lTriggerButton = -1  '방아쇠 버튼 없음
End With

didev.Acquire
Set objDIEffect = didev.CreateEffect("GUID_ConstantForce", effectInfo)

최초의 파라미터에는, 사전 정의된 GUID 의 1 개, 또는, 하드웨어 문서나 DirectInputEnumEffects.GetEffectGuid 메소드로 열거된 이펙트로서 취득된, 캐릭터 라인 형식의 실제의 GUID 를 사용할 수 있다.

DIEFFECT 형중 사용하는 멤버는, 이펙트의 종류에 따라서 다르다. 정수 포스는, 단일의 타입 고유의 파라미터만을 요구한다, 가장 단순한 포스이다. lGain,lDuration, 및 lTriggerButton 의 각 멤버는, 모든 이펙트로 설정해야 한다. 이러한 멤버의 디폴트값은 제로이지만, 보통은 적절하지 않기 때문이다.

디폴트에서는, 이펙트의 방향은 극좌표에서 나타내진다. 즉,DIEFFECT.x 가 포스의 올 방향을 100 분의 1 도 단위로 보관 유지해,DIEFFECT.y 는 제로가 아니면 안된다.

이펙트는 생성시에 디바이스에 자동적으로 다운로드된다. 이것에 의해, 디바이스는 만배는 아니고, 배타 협력 레벨로 취득된다.


이펙트의 방향

[C++]

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 }

DIEFFECT 구조체에서는, 제 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] = { 1, 0 };

반복하지만, 이 배열의 요소는 rgdwAxes 가 가리키는 배열에 리스트 되고 있는 축으로 대응하고 있다. 이 예에서는 x 축으로 제로를 설정해, y 축으로 1 을 설정해 있다. 즉, 방향은 직접 y 축의 정측상, 또는 남쪽에 있다.

이펙트의 방향에 대한 이론은, 이해하는 것은 어려울지도 모르지만, 실천해 볼 수 있고 바보든지 용이하게 이해할 수 있다. 샘플 코드가 있으므로, 「이펙트 방향 설정의 실례」를 참조할것.

[Visual Basic]

DirectX for Visual Basic 는, x 축과 y 축에서의 2 축이펙트를 지원 하고 있다.

이펙트의 방향은, 이펙트가 올 방향이다. y 축의 부측에 따른 방향에서의 이펙트는, 스틱을 y 축의 정측에 따라 (유저를 향해) 누르려고 한다. 방향의 축값을 시각적으로 파악하려면 , 유저가 디바이스에 반대로 작용하는 힘을 더하고 있는 곳(중)을 상상해 보면 좋다. 이펙트를 지우기 위해서(때문에) 유저가 스틱을 좌방향에 누르지 않으면 안 되는 경우, 이 이펙트는 「왼쪽」방향이다. 즉, 이 이펙트는 x 축의 부측에 있다.

방향은 "극히" 좌표,"구(공)면" 좌표, 또는,"데카르트" 좌표로 나타낼 수가 있다. 디폴트에서는, 극좌표가 사용된다. 방향은 DIEFFECT 형의 x 멤버로 지정된다. 이 경우,y 멤버는 항상 제로이다. 데카르트 좌표를 사용하려면 ,lFlags 멤버의 DIEFF_CARTESIAN 를 지정해,x 와 y 의 양쪽 모두를 지정할 필요가 있다.

극좌표는, 이펙트에 대해서 설정된 제로 지점 (진북)으로부터 시계회전에, 열매 각도의 100 배의 단일 각도로 나타내진다. 보통 이것은 부측의 y 축, 즉, 유저로부터 멀어질 방향이다. 따라서, 극좌표 9,000 의 이펙트는 보통, 동쪽향 즉 유저의 우측의 방향을 가진다. 이 이펙트를 지우려면 , 유저는 우측에 힘을 더하지 않으면 안 된다.

데카르트 좌표는 3 차원 벡터를 닮아 있어 3 차원 환경에 있어 포스를 유저의 방향 설정에 일치시키는 경우에 매우 편리하다. 중심을 시점 (0,0)으로 하는 그래프 용지에 직선을 그으면(자), 그 직선의 방향은, 시점으로부터의 거리와는 관계없이, 직선이 통과하는 임의의 좌표에 의해 정의할 수가 있다. 따라서, 방향 (1, -2)과 방향 (5, -10)은 완전히 같은 것된다.

주 : force feedback 이펙트의 생성에 사용하는 좌표는 방향만을 정의해, 매그니튜드나 거리는 정의하지 않는다.

다음의 코드는,DirectInputEffect 오브젝트의 dieff 로 나타내지는 포스의 방향을 반전하는 예이다. dieff 는, 글로벌 DIEFFECT 형의 effectinfo 를 사용해 생성이 끝난 상태이다.

effectinfo.lFlags = DIEFF_CARTESIAN
effectinfo.X = effectinfo.X * -1
effectinfo.Y = effectinfo.Y * -1
Call dieff.SetParameters(effectinfo, DIEP_DIRECTION)

DirectX for Visual Basic 는, 조건에 의할 방향 설정을 지원 하고 있지 않다.


이펙트 방향 설정의 실례

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

단일축이펙트

단일축이펙트의 방향의 설정은, 실제로 지정하는 것이 아무것도 없기 때문에, 지극히 단순하다. 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 = { 90 * DI_DEGREES, 0 }; // 북에서 90 번,
// 즉 동쪽.
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 = { 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의 기본 개념」을 참조할것.

[C++]

이펙트의 생성 또는 변경 시에 엔벌로프를 적용하려면 ,DIENVELOPE 구조체를 초기화해, 이 구조체에의 포인터를 DIEFFECT 구조체의 lpEnvelope 멤버로 설정한다.

어느 이펙트가 엔벌로프를 지원 할까를 결정하는 것은 디바이스 드라이버이다. 보통은, 정수 포스, 경사 포스 및 주기적 포스에 엔벌로프를 적용할 수 있지만, 조건에는 적용할 수 없다. 특정의 포스가 엔벌로프를 지원 할지 어떨지를 판정하려면 ,IDirectInputDevice7::GetEffectInfo 메소드를 호출해,DIEFFECTINFO 구조체의 dwStaticParams 멤버에 있는 DIEP_ENVELOPE 플래그를 체크한다.

오프셋(offset)를 적용하려면 ,DIEFFECT 구조체의 lpvTypeSpecificParams 멤버가 가리키는 DIPERIODIC 구조체 또는 DICONDITION 구조체의 lOffset 멤버를 설정한다. 주기적 이펙트의 경우, 오프셋(offset)의 절대치와 이펙트의 매그니튜드를 더한 값이 DI_FFNOMINALMAX 를 넘어서는 안 된다.

오프셋(offset)를 정수 포스나 경사 포스에 적용할 수 없다. 이러한 포스의 경우, 매그니튜드를 변경하면 같은 이펙트를 얻을 수 있다.

[Visual Basic]

이펙트의 생성 또는 변경 시에 엔벌로프를 적용하려면 ,DIEFFECT 형의 bUseEnvelope 멤버를 TRUE 로 설정해,DIENVELOPE 형의 envelope 멤버를 초기화한다.

어느 이펙트가 엔벌로프를 지원 할까를 결정하는 것은 디바이스 드라이버이다. 보통은, 정수 포스, 경사 포스 및 주기적 포스에 엔벌로프를 적용할 수 있지만, 조건에는 적용할 수 없다. 특정의 포스가 엔벌로프를 지원 할지 어떨지를 판정하려면 ,DirectInputEnumEffects.GetStaticParams 메소드를 호출해, 돌려주어진 값의 DIEP_ENVELOPE 플래그를 체크한다.

오프셋(offset)를 적용하려면 ,DIEFFECT 의 periodic 멤버나 condition 멤버로 사용되는,DIPERIODICFORCE 형 또는 DICONDITION 형의 lOffset 멤버를 설정한다. 주기적 이펙트의 경우, 오프셋(offset)의 절대치와 이펙트의 매그니튜드를 더한 값이 10,000 을 넘어서는 안 된다.

오프셋(offset)를 정수 포스나 경사 포스에 적용할 수 없다. 이러한 포스의 경우, 매그니튜드를 변경하면 같은 이펙트를 얻을 수 있다.


이펙트의 플레이백

[C++]

이펙트의 플레이백을 시작 하는 주된 방법은 2 개 있다. IDirectInputEffect::Start 메소드를 호출해 수동으로 시작 하는 방법과 버튼 압하에의 응답으로 자동적으로 시작 하는 방법이다. DIEP_START 플래그를 지정해 IDirectInputEffect::SetParameters 메소드를 호출하는 것으로 이펙트를 변경할 경우에도, 플레이백이 시작 한다.

dwIterations 파라미터에 INFINITE 를 건네주면(자),엔벌로프를 적용하면서 이펙트의 플레이백을 반복시킬 수가 있다. 엔벌로프를 반복하는 일 없이 이펙트를 반복하고 싶을 때 (예를 들어, 최초로 강한 킥을 한 후, 동계를 가라앉힌다라고 하는 경우)는,dwIterations 에 1 을 설정해, 다음에 DIEFFECT 구조체의 dwDuration 멤버에 INFINITE 를 세트 하면 좋다(이것은 IDirectInputDevice7::CreateEffect 메소드에게 건네지는 구조체이다).

주 : 디바이스에 따라서는, 이펙트의 여러 차례의 반복이 불가능해,Start 메소드에의 파라미터 dwIterations 에 값 1 밖에 인정하지 않는 것도 있다. Start 로부터의 반환값을 항상 체크해, 이펙트가 정상적으로 재생되었는지 어떠했는지를 확인해야 한다.

이펙트를 버튼 압하에 할당하려면 ,DIEFFECT 구조체의 dwTriggerButton 멤버를 설정한다. 버튼이 압하되고 있을 때의 플레이백간에 지연을 더하고 싶다면, 그 지연값을 dwTriggerRepeatInterval 멤버로 설정한다. 이 지연은, 1 개의 플레이백의 종료로부터 다음의 플레이백의 시작까지의 간격으로, 마이크로 세컨드 단위로 나타내진다.

주 : 디바이스에 따라서는, 여러 차례의 이펙트를 같은 버튼으로 발생시킬 수가 없는 것도 있다. 2 개(살) 이상의 이펙트를 1 개의 버튼에 할당하면(자), 마지막에 다운로드된 이펙트가, 발생하는 이펙트가 된다. 또, 방아쇠의 반복 간격은 지원되어 있지 않다.

이펙트의 방아쇠 버튼에의 할당을 해제하는데는,IDirectInputEffect::Unload 메소드를 호출하는지, 또는 DIEB_NOTRIGGER 로 설정되어 있는 dwTriggerButton 에, 이 이펙트용의 파라미터를 설정하는지, 어느 쪽인가의 조작을 실시하지 않으면 안 된다.

할당한 이펙트는, 다른 모든 이펙트와 같게, 어플리케이션이 디바이스에의 액세스권을 잃으면(자) 없어진다. 다시 이러한 이펙트를 유효하게 하려면 , 어플리케이션이 디바이스를 재취득 하면 동시에 이러한 이펙트를 다운로드한다. 이 처리는 방아쇠에 할당하지 않은 이펙트에서는 불필요하다. 왜냐하면, 이런 종류의 이펙트는,Start 메소드가 불려 갈 때는 언제나, 필요에 따라서 자동적으로 다운로드되기 때문이다.

이펙트의 계속 시간이 유한해, 이펙트가 Start 메소드에의 호출에 의해 시작 하는 경우, 계속 시간이 지나면(자) 이펙트의 재생은 종료한다. 이펙트의 계속 시간이 INFINITE 로 설정되어 있었을 경우, 플레이백이 종료하는 것은,IDirectInputEffect::Stop 메소드가 불려 갔을 때 뿐인다. 방아쇠 버튼에 할당한 이펙트는 그 버튼을 누르면(자) 시작 해, 그 버튼을 떼어 놓는지, 계속 시간이 지나는지, 어느 쪽인지 빠른 (분)편의 시점에서 종료한다.

[Visual Basic]

이펙트의 플레이백을 시작 하는 주된 방법은 2 개 있다. DirectInputEffect.Start 메소드를 호출해 수동으로 시작 하는 방법과 버튼 압하에의 응답으로 자동적으로 시작 하는 방법이다. DIEP_START 플래그를 지정해 DirectInputEffect.SetParameters 메소드를 호출하는 것으로 이펙트를 변경할 경우에도, 플레이백은 시작 한다.

Start 메소드의 iterations 파라미터에 -1 를 건네주면(자),엔벌로프를 적용하면서 이펙트의 플레이백을 반복시킬 수가 있다. 엔벌로프를 반복하는 일 없이 이펙트를 반복하고 싶을 때 (예를 들어, 최초로 강한 킥을 한 후, 동계를 가라앉힌다라고 하는 경우)는,iterations 에 1 을 설정해, 다음에 형태의 lDuration 멤버에 -1 를 설정하면 좋다 (이것은 DirectInputDevice.CreateEffect 메소드에게 건네지는 타입이다).

주 : 디바이스에 따라서는, 이펙트의 여러 차례의 반복이 불가능해,Start 메소드에의 파라미터 iterations 에 값 1 밖에 인정하지 않는 것도 있다.

이펙트를 버튼에 할당하려면 ,DIEFFECT 형의 lTriggerButton 멤버를 설정한다. 버튼이 압하되고 있을 때의 플레이백간에 지연을 더하고 싶다면, 그 지연값을 lTriggerRepeatInterval 멤버로 설정한다. 이 지연은, 1 개의 플레이백의 종료로부터 다음의 플레이백의 시작까지의 간격으로, 마이크로 세컨드 단위로 나타내진다.

주 : 디바이스에 따라서는, 여러 차례의 이펙트를 같은 버튼으로 발생시킬 수가 없는 것도 있다. 2 개(살) 이상의 이펙트를 1 개의 버튼에 할당하면(자), 마지막에 다운로드된 이펙트가, 발생하는 이펙트가 된다. 또, 방아쇠의 반복 간격은 지원되어 있지 않다.

이펙트의 방아쇠 버튼에의 할당을 해제하는데는,DirectInputEffect.Unload 메소드를 호출하는지, 또는,-1 으로 설정되어 있는 lTriggerButton 에 이펙트의 파라미터를 설정하는지, 어느 쪽인가의 조작을 실시하지 않으면 안 된다.

할당한 이펙트는, 다른 모든 이펙트와 같게, 어플리케이션이 디바이스에의 액세스권을 잃으면(자) 없어진다. 다시 이러한 이펙트를 유효하게 하려면 , 어플리케이션이 디바이스를 재취득 하면 동시에 이러한 이펙트를 다운로드한다. 이 처리는 방아쇠에 할당하지 않은 이펙트에서는 불필요하다. 왜냐하면, 이런 종류의 이펙트는,Start 메소드가 불려 갈 때는 언제나, 필요에 따라서 자동적으로 다운로드되기 때문이다.

이펙트의 계속 시간이 유한해, 이펙트가 Start 메소드에의 호출에 의해 시작 하는 경우, 계속 시간이 지나면(자) 이펙트의 재생은 종료한다. 이펙트의 계속 시간이 -1 로 설정되어 있었을 경우, 플레이백이 종료하는 것은,DirectInputEffect.Stop 메소드가 불려 갔을 때 뿐인다. 방아쇠 버튼에 할당한 이펙트는 그 버튼을 누르면(자) 시작 해, 그 버튼을 떼어 놓는지, 계속 시간이 지나는지, 어느 쪽인지 빠른 (분)편의 시점에서 종료한다.


이펙트의 다운로드와 언로드

이펙트는 재생하기 전에 디바이스에 다운로드해야 한다. 이펙트의 다운로드란, 드라이버에 이펙트의 플레이백의 준비를 하도록(듯이) 통지하는 것이다. 다운로드의 방법을 결정하는 것은 완전히 드라이버에 맡길 수 있다. 일반적으로, 드라이버는 이펙트의 파라미터를 하드웨어 메모리에 두어, 디바이스와 시스템의 사이의 데이터 차례차례 전송을 최소한으로 억제한다. 이것에 의해,지연 시간이 삭감된다. 이것은,"발사" 버튼과 같이, 방아쇠에의 응답으로 기능하는 조건과 이펙트에 있어서는 특히 의미가 있다. 디바이스가 축이동과 버튼 압하에 응답하기 위해서 시스템과 전혀 교환을 실시할 필요가 없는, 이라고 하는 것이 이상적일 것이다.

디바이스가 만배는 아니고 게다가 배타 협조 레벨로 취득되고 있는 경우에는, 이펙트의 생성시에 다운로드가 자동적으로 행해진다. 이펙트를 시작, 또는 이펙트의 파라미터를 변경 하면 간, 다운로드는 디폴트로 행해진다.

[C++]

파라미터를 변경할 경우에 DIEP_NODOWNLOAD 플래그를 지정하면, 계속 IDirectInputEffect::Download 메소드를 사용해 이펙트의 다운로드나 업 로드를 실시하지 않으면 안 된다.

디바이스가 미취득 상태 때 (예를 들어, 디바이스가 배타 foreground 협조 레벨로 취득되고 있어, 어플리케이션이 백그라운드로 이행할 때), 이펙트는 언로드되고 있으므로, 어플리케이션이 foreground를 재취득할 경우에 다시 이펙트를 다운로드해야 한다. 먼저 말한 것처럼, 이펙트의 다운로드는,IDirectInputEffect::Start 메소드를 호출하면 자동적으로 행해진다. 그러나, 디바이스를 재취득 하면 동시에 모든 이펙트를 다운로드할지 어떨지를 선택할 수 있다. Start 메소드는 보통 방아쇠 버튼에 할당한 이펙트에서는 불려 가지 않기 때문에, 이런 종류의 이펙트는 반드시 다운로드할 필요가 있다.

이펙트의 다운로드중에 어플리케이션이 DIERR_DEVICEFULL 에러를 받으면(자), 낡은 이펙트를 언로드해 새로운 이펙트를 위한 스페이스를 확보할 필요가 있다. IDirectInputEffect::Unload 메소드를 호출하면, 디바이스로부터 1 개의 이펙트를 삭제할 수가 있다. 또,IDirectInputDevice7::SendForceFeedbackCommand 메소드를 호출해 디바이스를 리셋 하면, 모든 이펙트를 삭제할 수도 있다.

[Visual Basic]

파라미터를 변경할 경우에 DIEP_NODOWNLOAD 플래그를 지정하면, 계속 DirectInputEffect.Download 메소드를 사용해 이펙트의 다운로드나 업 로드를 실시하지 않으면 안 된다.

디바이스가 미취득 상태 때 (예를 들어, 디바이스가 배타 foreground 협조 레벨로 취득되고 있어, 어플리케이션이 백그라운드로 이행할 때), 이펙트는 언로드되고 있으므로, 어플리케이션이 foreground를 재취득할 경우에 다시 이펙트를 다운로드해야 한다. 먼저 말한 것처럼, 이펙트의 다운로드는,DirectInputEffect.Start 메소드를 호출하면 자동적으로 행해진다. 그러나, 디바이스를 재취득 하면 동시에 모든 이펙트를 다운로드할지 어떨지를 선택할 수 있다. Start 메소드는 보통 방아쇠 버튼에 할당한 이펙트에서는 불려 가지 않기 때문에, 이런 종류의 이펙트는 반드시 다운로드할 필요가 있다.

이펙트의 다운로드중에 어플리케이션이 DIERR_DEVICEFULL 에러를 받으면(자), 낡은 이펙트를 언로드해 새로운 이펙트를 위한 스페이스를 확보할 필요가 있다. DirectInputEffect.Unload 메소드를 호출하면, 디바이스로부터 1 개의 이펙트를 삭제할 수가 있다. 또,DirectInputDevice.SendForceFeedbackCommand 메소드를 호출해 디바이스를 리셋 하면, 모든 이펙트를 삭제할 수도 있다.

force feedback 디바이스를 생성 하면, 하드웨어와 드라이버가 리셋 되므로, 존재하고 있던 이펙트 모든 것이 소거된다.


이펙트의 변경

[C++]

이펙트의 재생 그 중에서 이펙트의 파라미터를 변경할 수가 있는 경우가 있다. 이것은 IDirectInputEffect::SetParameters 메소드를 사용해 실시한다.

DIEFFECTINFO 구조체의 dwDynamicParams 멤버는, 이펙트의 재생 그 중에서 변경할 수 있는 이펙트의 파라미터를 통지한다. 이펙트의 재생중에는 변경할 수 없는 이펙트의 파라미터를 변경하려고 해, 이펙트가 실제로 아직 재생하고 있을 때는, 보통, 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);

이 플래그에 의해,DIEFFECT 구조체로부터의 데이터 전송은, 관련하는 멤버에 한정되는 것이 보증된다. 따라서, 이 구조체 전체를 초기화할 필요가 없어져, 디바이스에 송신할 필요가 있는 데이터의 양이 최소한으로 끝난다.

[Visual Basic]

이펙트의 재생 그 중에서 이펙트의 파라미터를 변경할 수가 있는 경우가 있다. 이것을 실시하려면 ,DirectInputEffect.SetParameters 메소드를 사용한다.

이펙트의 재생 그 중에서 변경할 수 있는 이펙트의 파라미터를 조사하려면 ,DirectInputEnumEffects.GetDynamicParams 메소드를 호출한다.

이펙트 재생중에는 변경할 수 없는 이펙트의 파라미터를 변경하려고 해, 이펙트가 실제로 아직 재생하고 있을 때는, 보통, DirectInput 는 이펙트를 정지시켜, 파라미터를 갱신해, 이펙트를 재스타트 시킨다. 이 DirectInput 의 디폴트의 기능을 무효로 하려면 ,SetParameters 에 DIEP_NORESTART 플래그를 건네주면 좋다.

다음의 코드는,DirectInputEffect 오브젝트의 dieff 로 나타내지는 정수 포스의 매그니튜드를 변경하는 예이다. 이 오브젝트는, 글로벌인 DIEFFECT 형의 effectinfo 를 사용해 생성이 끝난 상태이다.

effectinfo.constantForce.lMagnitude = 5000
Call dieff.SetParameters(effectinfo, DIEP_TYPESPECIFICPARAMS)

DIEFFECT 의 condition,constantforce,periodicforce, 및 rampforce 의 각 멤버를 변경하는 경우는, DIEP_TYPESPECIFICPARAMS 플래그를 설정할 필요가 있다.


게인

포스를 미치는 디바이스의 종류에 응해, 이펙트의 포스의 크기에 차이를 내고 싶은 경우가 있을 것이다. 예를 들어, 어느 축으로 대해 최대 n 뉴턴의 포스를 낳는 디바이스로 어플리케이션의 이펙트가 올바르게 일한다고 생각될 때는, 보다 많은 포스를 낳는 디바이스용으로 게인을 조정하고 싶은 것이 있을 것이다 (축의 포스의 최대치를 늘리기 위해서(때문에) 게인을 사용할 수 없기 때문에, 낳는 포스가 작은 디바이스에 대해서, 적절한 값을 기본적 이펙트 매그니튜드로 설정해야 한다).

또, 게인을 사용해, 하드웨어로 정의된 이펙트의 매그니튜드를 감소시킬 수도 있다.

[C++]

축이나 버튼등의 디바이스 오브젝트에 의해 발생하는 포스는, 오브젝트의 열거시에 DIDEVICEOBJECTINSTANCE 구조체의 dwFFMaxForce 멤버에 저장 되어 돌려주어진다 ( 「디바이스 오브젝트의 열거」를 참조할것).

IDirectInputDevice7::SetProperty 메소드를 사용해, 디바이스 전체의 게인을 설정할 수가 있다.

개별의 이펙트를 생성 하면나무는,DIEFFECT 구조체의 dwGain 멤버에 값을 설정하는 것으로, 이펙트에 게인을 설정해야 한다(dwGain 가 제로라면, 그 이펙트는 느껴지지 않는다). 이 값은,dwFlags 파라미터에 DIEP_GAIN 를 지정해 IDirectInputEffect::SetParameters 를 호출하는 것으로, 나중에 변경할 수가 있다.

[Visual Basic]

DirectInputDevice.SetProperty 메소드를 사용해, 디바이스 전체의 게인을 설정할 수가 있다.

개별의 이펙트를 생성 하면나무는,DIEFFECT 형의 lGain 멤버에 값을 설정하는 것으로, 이펙트에 게인을 설정해야 한다(lGain 가 제로라면, 그 이펙트는 느껴지지 않는다). 이 값은,flags 파라미터에 DIEP_GAIN 를 지정해 DirectInputEffect.SetParameters 를 호출하는 것으로, 나중에 변경할 수가 있다.

디바이스 게인을 설정하는 목적은, 어플리케이션에 모든 이펙트의 포스를 일괄해 제어시키는 것이다. 예를 들어, 음향 믹서의 메인 볼륨 콘트롤러와 같이, force feedback 이펙트에 필요하게 되는 강도를 유저로 지정시키는 슬라이드 콘트롤러를 어플리케이션에 붙이고 싶다고 생각하는 일이 있을 것이다. 디바이스 게인을 설정하면, 유저의 취향에 맞추어 개별의 이펙트의 게인을, 어플리케이션이 조정할 필요가 없어진다.

1 개의 게인값은 0 에서 10,000 의 범위의 값을 취한다. 10,000 이라고 하는 값은, 매그니튜드를 스케일링 해서는 안된다고 하는 것을 나타낸다. 7,500 이라고 하는 값은, 포스의 명목 매그니튜드의 75% 에 포스를 스케일링 해야 한다라고 말하는 것을 의미하고 있다. 그 외의 수치도 이것에 준한다.


force feedback 상태

[C++]

IDirectInputDevice7::SendForceFeedbackCommand 메소드를 사용하면, 디바이스의 액츄에이터를 오프 (재생하고 있는 이펙트 모든 것을 무시하는데 유효)로 해, 이펙트의 플레이백을 중단 또는 중지해, 디바이스를 리셋 해 다운로드한 모든 이펙트를 삭제할 수가 있다.

현재의 force feedback 상태를 취득하려면 ,IDirectInputDevice7::GetForceFeedbackState 메소드를 사용한다. 이 메소드에 의해, 액츄에이터가 유효한가 어떤가 플레이백이 중단 상태인가 부디 및 디바이스가 리셋 되었는지 어떠했는지라고 하는 정보가 돌려주어진다. 또, 다양한 스윗치에 관한 정보나, 현재 디바이스에 전원이 들어가 있을지 어떨지의 정보도 취득된다.

[Visual Basic]

DirectInputDevice.SendForceFeedbackCommand 메소드를 사용하면, 디바이스의 액츄에이터를 오프 (재생하고 있는 이펙트 모든 것을 무시하는데 유효)로 해, 이펙트의 플레이백을 중단 또는 중지해, 디바이스를 리셋 해 다운로드한 모든 이펙트를 삭제할 수가 있다.

현재의 force feedback 상태를 취득하려면 ,DirectInputDevice.GetForceFeedbackState 메소드를 사용한다. 이 메소드에 의해, 액츄에이터가 유효한가 어떤가 플레이백이 중단 상태인가 부디 및 디바이스가 리셋 되었는지 어떠했는지라고 하는 정보가 돌려주어진다. 또, 다양한 스윗치에 관한 정보나, 현재 디바이스에 전원이 들어가 있을지 어떨지의 정보도 취득된다.


이펙트 오브젝트의 열거

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 는, 생성되는 이펙트의 열거를 지원 하고 있지 않다.

[C++]

프로그램에 생성한 모든 이펙트의 실험이나 조작이 필요하게 되었을 때는,IDirectInputDevice7::EnumCreatedEffectObjects 메소드를 이용할 수가 있다. 현재로서는, 이 메소드에는 플래그가 전혀 정의되어 있지 않기 때문에, 특정의 종류의 이펙트에 열거를 좁힐 수 없다. 모든 이펙트가 열거되어 버린다.

주 : 이 메소드는 생성되는 이펙트는 열거하지만, 디바이스에 의해 지원 되는 이펙트는 열거하지 않는다. 이 2 개의 이펙트의 구별에 대해 자세한 것은, 「이펙트의 열거」를 참조할것.

DirectInput 외의 열거와 같게,EnumCreatedEffectObjects 메소드에는 콜백 함수가 필요하다. 이 표준 콜백 함수는, 문서에서는 플레이스홀더명 DIEnumCreatedEffectObjectsCallback 로 나타내지고 있지만, 다른 이름을 붙여도 괜찮다. 이 함수는 열거된 이펙트 각각 붙어 불려 간다. 이 함수내에서는, 어떤 처리라도 실행할 수가 있다. 그러나, 열거의 실행중은 새로운 이펙트를 생성하지 않는 것이 안전하다.

다음에 드는 것은, 콜백 함수의 코딩의 1 예이다. 여기에서는,EnumCreatedEffectObjects 메소드에의 호출을 하고 있다. 콜백 함수의 pvRef 파라미터는, 32 비트의 임의의 값을 취할 수가 있다. 이 경우, 이 파라미터는 디바이스 인터페이스에의 포인터이다.

HRESULT hr;
// LPDIRECTINPUTDEVICE lpdid;  // 초기화가 끝난 상태.

BOOL CALLBACK DIEnumCreatedEffectObjectsCallback(
LPDIRECTINPUTEFFECT peff, LPVOID pvRef);
{
LPDIRECTINPUTDEVICE pdid = pvRef; // 호출 디바이스에의 포인터.
DIEFFECT      diEffect;   // 생성된 이펙트용의 파라미터.

diEffect.dwSize = sizeof(DIEFFECTINFO);
peff->GetParameters(&diEffect, DIEP_ALLPARAMS);
// 파라미터의 체크 또는 설정, 혹은 그 외의 처리.
    .
    .
    .
} // 콜백의 종료.

// 콜백의 시동.
hr = lpdid->EnumCreatedEffectObjects(&EnumCreatedEffectObjectsCallback,
&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)를 적용할 수 없다.

[C++]

정수 포스를 생성하려면 , GUID_ConstantForce 를 IDirectInputDevice7::CreateEffect 메소드에 건네준다. DIEFFECTINFO 구조체의 멤버 dwEffType (DIEFT_GETTYPE(dwEfftype)) 의 하위 바이트가 DIEFT_CONSTANTFORCE 과 동일할 때는,IDirectInputDevice7::EnumEffects 메소드로 취득한 것 외의 임의의 GUID 를 건네줄 수가 있다. 이 방법을 사용하면, 소란을 시뮬레이션 하는 "정수" 포스 (이름은 "정수 (정상)" 이지만 실제로는 매그니튜드가 랜덤에 변화한다) 등, 업자가 설계한 하드웨어 특유의 포스를 사용할 수가 있다.

정수 포스는,DICONSTANTFORCE 구조체를 사용해 매그니튜드를 정의한다. 부의 매그니튜드에는, 포스의 방향을 반전하는 이펙트가 있다.

[Visual Basic]

정수 포스를 생성하려면 , GUID_ConstantForce 를 DirectInputDevice.CreateEffect 메소드에 건네준다. DirectInputEnumEffects.GetType 에 의해 돌려주어진 값의 하위 바이트가 DIEFT_CONSTANTFORCE 에 동일한 경우는,DirectInputEnumEffects.GetEffectGuid 메소드에 의해 취득된 것 외의 임의의 GUID 를 건네줄 수도 있다. 이 방법을 사용하면, 소란을 시뮬레이션 하는 "정수" 포스 (이름은 "정수 (정상)" 이지만 실제로는 매그니튜드가 랜덤에 변화한다) 등, 업자가 설계한 하드웨어 특유의 포스를 사용할 수가 있다.

정수 포스의 매그니튜드는,DIEFFECT 의 constantForce 멤버내의 DICONSTANTFORCE 형에 저장 된다. 부의 매그니튜드에는, 포스의 방향을 반전하는 이펙트가 있다.


경사 포스

경사 포스는, 정의 끝난 초기 매그니튜드와 종기 매그니튜드 및 유한의 계속 시간을 가지는 포스이다. 경사 포스는, 1 방향인 만큼 늘어나는 경우도, 혹은 1 방향을 향해 강할 기세로 시작되어, 약해져, 정지해, 반대 방향으로 강하게 진행된다고 하는 경우도 있다.

다음의 그림은, 매그니튜드 -5, 000 으로 시작되어, 매그니튜드 5,000 으로 끝나는 경사 포스를 나타내고 있다.

엔벌로프를 경사 포스에 적용해, 경사 포스를 잡아늘일 수가 있다. 다음의 그림은, 전의 그림의 경사 포스에 엔벌로프 (초록으로 나타내 있다)를 적용하는 이펙트를 나타내고 있다.

엔벌로프의유지 기간 부분에서는, 이펙트의 매그니튜드는 엔벌로프의 적용전과 같은 직선을 그린다. 어택과페이드의 계속 시간에 대해서는, 경사 포스의 경사는 어택 레벨과 페이드 레벨로 변경된다.

경사 포스에는 오프셋(offset)를 적용할 수 없다.

[C++]

경사 포스를 생성하려면 , GUID_RampForce 를 IDirectInputDevice7::CreateEffect 메소드에 건네준다. DIEFFECTINFO 구조체의 멤버 dwEffType (DIEFT_GETTYPE(dwEfftype))의 하위 바이트가 DIEFT_RAMPFORCE 와 동일한 경우는,IDirectInputDevice7::EnumEffects 메소드로 취득한 것 외의 임의의 GUID 를 건네줄 수도 있다. 이 방법을 사용하면, 업자가 설계한 하드웨어 특유의 경사 포스를 사용할 수가 있다.

경사 포스는 DIRAMPFORCE 구조체를 이용해, 포스의 초기 매그니튜드와 종기 매그니튜드를 정의할 수가 있다. 한편, 그 계속 시간은 DIEFFECT 구조체에 의해 정의된다. 계속 시간을 결코 INFINITE 로 설정해선 안 된다.

[Visual Basic]

경사 포스를 생성하려면 , GUID_RampForce 를 DirectInputDevice.CreateEffect 메소드에 건네준다. DirectInputEnumEffects.GetType 에 의해 돌려주어진 값의 하위 바이트가 DIEFT_RAMPFORCE 과 동일한 경우는,DirectInputEnumEffects.GetEffectGuid 메소드로 취득된 것 외의 임의의 GUID 를 건네줄 수도 있다. 이 방법을 사용하면, 업자가 설계한 하드웨어 특유의 경사 포스를 사용할 수가 있다.

포스의 초기 매그니튜드와 종기 매그니튜드는,DIEFFECT 의 rampForce 멤버에 포함되는 DIRAMPFORCE 형으로 정의된다. 계속 시간을 무한하게 할 수 없기 때문에,DIEFFECT.lDuration 는 정의 값이 아니면 안된다.


주기적 이펙트

주기적 이펙트는 파형 이펙트이다. 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 밖에 지원 하고 있지 않는 것도 있다.

[C++]

주기적 포스를 생성하려면 ,IDirectInputDevice7::CreateEffect 메소드의 rguid 파라미터에 다음에 드는 값의 어떤 것이나 1 개를 건네준다.

  • GUID_Square
  • GUID_Sine
  • GUID_Triangle
  • GUID_SawtoothUp
  • GUID_SawtoothDown

DIEFFECTINFO 구조체의 멤버 dwEffType (DIEFT_GETTYPE(dwEfftype))의 하위 바이트가 DIEFT_PERIODICY 에 동일한 경우는,IDirectInputDevice7::EnumEffects 메소드로 취득한 것 외의 임의의 GUID 를 건네주어도 괜찮다. 이 방법을 사용하면, 업자가 설계한 하드웨어 특유의 포스를 사용할 수가 있다. 예를 들어, 스틱을 작은 원형에 회전하는 주기적 이펙트를 지원 하고 있는 하드웨어 디바이스등이 있다.

주기적 이펙트의 타입 고유 구조체는 DIPERIODIC 이다.

주기적 이펙트의 "주기" (DIPERIODIC.dwPeriod)와 "샘플링 간격" (DIEFFECT.dwSamplePeriod)을 혼동 하지 않게 주의 해야 한다. 주기는 1 개의 물결의 사이클 전체를 실행하는데 필요로 하는 시간이다. 샘플링 간격은, 모든 이펙트와 같게, 매그니튜드를 실제로 조정하는 간격의 최소 시간이다.

[Visual Basic]

주기적 포스를 생성하려면 ,DirectInputDevice.CreateEffect 메소드의 guid 파라미터에, 다음에 드는 값의 어떤 것이나 1 개를 건네준다.

  • GUID_Square
  • GUID_Sine
  • GUID_Triangle
  • GUID_SawtoothUp
  • GUID_SawtoothDown

DirectInputEnumEffects.GetType 로 돌려주어지는 값의 하위 바이트가 DIEFT_PERIODICY 에 동일한 경우는,DirectInputEnumEffects.GetEffectGuid 메소드로 취득한 것 외의 임의의 GUID 를 건네줄 수도 있다. 이 방법을 사용하면, 업자가 설계한 하드웨어 특유의 포스를 사용할 수가 있다.

주기적 이펙트의 타입 고유 파라미터는,DIEFFECT 의 periodicForce 멤버에 포함되는 DIPERIODICFORCE 형에 저장 되고 있다.

주기적 이펙트의 주기 (DIEFFECT.periodic.lPeriod)와 샘플링 간격 (DIEFFECT.lSamplePeriod)을 혼동 하지 않게 주의 해야 한다. 주기는 1 개의 물결의 사이클 전체를 실행하는데 필요로 하는 시간이다. 샘플링 간격은, 모든 이펙트와 같게, 매그니튜드를 실제로 조정하는 간격의 최소 시간이다.


조건

조건이란, 디바이스내의 현재의 센서값에 반응해 적용되는 포스이다. 즉, 조건은, 죠이스틱 핸들의 위치 또는 속도 등, 디바이스에 관한 정보를 필요로 한다.

일반적으로, 조건은 게임이나 그 외의 어플리케이션에 있어서의 개별의 이벤트에는 관련지을 수 있지 않았다. 조건은, 플라이트 스틱의 딱딱함이나 느슨함, 또는 직진의 위치에 되돌리는 핸들의 방향등의 상태를 표현한다.

조건은, 정의된 매그니튜드를 가지지 않는다. 매그니튜드는, 입력 오브젝트의 동작과 위치에 의해 측정된다.

DirectInput 는, 다음과 같은 조건의 이펙트를 정의한다.

  • 마찰 ― 축이 이동할 경우에 적용되는 포스로, 정의 끝난 마찰 계수에 의해 정해진다.
  • 댐퍼 ― 이 포스는 유저가 죠이스틱을 작동시키는 속도 에 비례해 증가한다.
  • 관성 ― 이 포스는 축의 가속도 에 비례해 증가한다.
  • 스프링 ― 이 포스는 정의되고 있는 중립점으로부터의 축의 거리 에 비례해 증가한다.

대부분의 하드웨어 디바이스에서는, 조건에엔벌로프를 적용할 수 없다.

조건에는 다음의 타입의 파라미터가 있다.

Offset
조건의 적용이 시작되는 적절한 센서값을 읽어들이는, 제로로부터의 오프셋(offset). 스프링 이펙트에서는, 중립점 (스프링이 정지하고 있다고 생각되는 축위에의점)은 조건용의 이 오프셋(offset)에 의해 정의된다. 댐퍼 이펙트에서는, 이 오프셋(offset)에 의해, 댐퍼 포스가 제로가 되는 최대 속도값이 정의된다. 보통, 오프셋(offset)는 관성 이펙트나 마찰 이펙트에는 사용하지 않는다.
Coefficient
이펙트의 스케일링을 산출하는 승수. 디바이스에 따라서는, 조건에 관계하는 축위에의 정방향과 부방향으로 다른 계수를 설정할 수가 있다. 예를 들어, 공격을 받은 비행기를 컨트롤 하는 조종간은, 왼쪽보다 오른쪽에 작동시키는 (분)편이 용이하게 된다라고 하는 경우이다.
Saturation
force feedback에서는, 포화점은 이펙트를 올리는 최대의 포스를 나타내고 있다. 예를 들어, 조종간이 X 축상에서 스프링 조건을 가지고 있으면(자) 가정해 보자. 오프셋(offset)는 제로, 계수는 10,000 이며, 보통은 조종간이 중립점으로부터 가장 떨어져 있을 때, 최대 포스가 발휘된다. 그러나, 정부 5,000 의 포화점을 정의하고 있으면(자), 조종간이 오른쪽이나 왼쪽으로 이동한 후, 포스는 증가하지 않는다.

포화점을 지원 하고 있지 않는 디바이스도 있다.

Deadband
데드 밴드란, 조건이 작용하지 않는 축의 오프셋(offset) 범위이다. 스프링이 축의 중립점에 정지하고 있는 경우는, 데드 밴드는 이 정지의 범위를 확장한다.

데드 밴드를 지원 하고 있지 않는 디바이스도 있다.

조건에 계속 시간을 설정할 수가 있다. 그러나, 계속 시간을 INFINITE (-1)로 설정해, 어플리케이션으로 특정의 이벤트에 응답 하면나무만 이펙트를 정지할 방법이 사용되는 것이 많다.

[C++]

조건을 생성하려면 ,IDirectInputDevice7::CreateEffect 메소드의 rguid 파라미터에 다음의 값의 어떤 것이나 1 개를 건네준다.

  • GUID_Spring
  • GUID_Damper
  • GUID_Inertia
  • GUID_Friction

DIEFFECTINFO 구조체의 멤버 dwEffType (DIEFT_GETTYPE(dwEfftype))의 하위 바이트가 DIEFT_CONDITION 에 동일한 경우는,IDirectInputDevice7::EnumEffects 메소드로 취득한 것 외의 임의의 GUID 를 건네줄 수가 있다. 이 방법을 사용하면, 업자가 설계한 하드웨어 특유의 조건을 사용할 수가 있다.

조건의 타입 고유 구조체는 DICONDITION 이다. 복수축의 조건에서는, 1 개의 축으로 대해 복수의 구조체로부터 되는 배열을 사용하는지, 또는 특정의 방향에서의 조건을 정의하는 1 개의 구조체를 사용할 수가 있다. 어느 쪽의 경우에서도,DIEFFECT 구조체의 cbTypeSpecificParams 멤버에, 사용하는 바이트수를 설정할 필요가 있다. 즉,sizeof(DICONDITION) * n 를 설정할 필요가 있다. 여기서 n 는 사용하는 구조체의 수를 나타낸다. 1 개(살) 혹은 복수의 구조체를 사용하는 방법의 정보는,DICONDITION 구조체에 대한 「주의」를 참조할것.

이펙트의 계수로포화에 대해 정과 부의 양쪽 모두가 디바이스로 지원 되고 있는지 어떤지를 확인하려면 , 어플리케이션으로 IDirectInputDevice7::GetEffectInfo 메소드 또는 IDirectInputDevice7::EnumEffects 메소드를 호출해,DIEFFECTINFO 구조체의 dwEffectType 멤버를 조사하지 않으면 안 된다. 이펙트가 DIEFT_POSNEGCOEFFICIENTS 플래그를 돌려주지 않으면,lNegativeCoefficient 멤버의 값은 무시되어lPositiveCoefficient 의 값이 축전체에 적용된다. 같이 이펙트가 DIEFT_POSNEGSATURATION 플래그를 돌려주지 않으면,dwNegativeSaturation 의 값은 무시되어dwPositiveSaturation 의 값이 부의 포화 레벨로서 사용된다. 또, 이펙트가 DIEFT_SATURATION 플래그를 돌려주지 않으면,dwPositiveSaturation 와 dwNegativeSaturation 의 양쪽 모두의 값이 무시되어 포화점은 적용되지 않는다.

계수에는 음수를 설정할 수가 있다. 이렇게 하면(자), 이펙트는 반대 방향의 포스를 생성한다. 예를 들어 스프링 이펙트에서는, 계수에 음수를 설정 하면, 스프링 이펙트는 오프셋(offset)점으로 향해 이끌지 않고 , 오프셋(offset)점으로부터 멀어질 방향에 누르게 된다.

또,DIEFFECTINFO.dwEffectType 에 DIEFT_DEADBAND 플래그가 설정되어 있는지 어떤지를 체크하는 것으로, 데드 밴드가 조건에 대해서 지원 되고 있는지 어떤지를 알 수 있다. 지원되어 있지 않은 경우,DICONDITION 구조체의 lDeadBand 멤버의 값은 무시된다.

[Visual Basic]

조건을 생성하려면 ,IDirectInputDevice7::CreateEffect 메소드의 rguid 파라미터에 다음의 값의 어떤 것이나 1 개를 건네준다.

  • GUID_Spring
  • GUID_Damper
  • GUID_Inertia
  • GUID_Friction

DirectInputEnumEffects.GetType 에 의해 돌려주어진 값의 하위 바이트가 DIEFT_CONDITION 에 동일한 경우는,DirectInputEnumEffects.GetEffectGuid 메소드로 취득한 것 외의 임의의 GUID 를 건네줄 수도 있다. 이 방법을 사용하면, 업자가 설계한 하드웨어 특유의 조건을 사용할 수가 있다.

조건의 타입 고유 파라미터는,DIEFFECT 형의 condition 멤버에 포함되는 DICONDITION 형에 기술된다.

이펙트의 계수로포화에 대해 정과 부의 양쪽 모두가 디바이스로 지원 되고 있는지 어떤지를 확인하려면 , 어플리케이션으로 DirectInputEnumEffects.GetType 메소드를 호출해, 돌려주어진 값의 멤버를 조사할 필요가 있다. 이펙트가 DIEFT_POSNEGCOEFFICIENTS 플래그를 돌려주지 않으면,DICONDITION.lNegativeCoefficient 의 값은 무시되어lPositiveCoefficient 의 값이 축전체에 적용된다. 같이 이펙트가 DIEFT_POSNEGSATURATION 플래그를 돌려주지 않으면,lNegativeSaturation 의 값은 무시되어lPositiveSaturation 의 값이 부의 포화 레벨로서 사용된다. 또, 이펙트가 DIEFT_SATURATION 플래그를 돌려주지 않으면,lPositiveSaturation 와 lNegativeSaturation 의 양쪽 모두의 값이 무시되어 포화점은 적용되지 않는다.

계수에는 음수를 설정할 수가 있다. 이렇게 하면(자), 이펙트는 반대 방향의 포스를 생성한다. 예를 들어 스프링 이펙트에서는, 계수에 음수를 설정 하면, 스프링 이펙트는 오프셋(offset)점으로 향해 이끌지 않고 , 오프셋(offset)점으로부터 멀어질 방향에 누르게 된다.

또,GetType 멤버에 DIEFT_DEADBAND 플래그가 설정되어 있는지 어떤지를 체크하는 것으로, 데드 밴드가 조건에 대해서 지원 되고 있는지 어떤지를 알 수 있다. 지원되어 있지 않은 경우,DICONDITION 구조체의 lDeadBand 멤버의 값은 무시된다.

단일축이펙트를 생성하려면 ,DIEFFECT 형의 conditionX 멤버 또는 conditionY 멤버에, 미사용의 축으로 대하는 계수를 제로로서 설정한다.

DirectX for Visual Basic 에서는, 조건의 회전을 지원 하고 있지 않다.


커스텀 포스

어플리케이션의 생성자는, 커스텀 포스를 생성 하는 것에 의해, 독자적인 이펙트를 생성 할 수가 있다. 커스텀 포스는, 디바이스가 재생하는 정수 포스값의 배열이다.

[C++]

커스텀 파형 이펙트의 타입 고유 구조체는,DICUSTOMFORCE 이다.

DICUSTOMFORCE 구조체의 dwSamplePeriod 멤버와 DIEFFECT 구조체의 dwSamplePeriod 멤버에는 같은 값을 설정해야 한다. 이 값은 밀리 세컨드 단위의 시간이며, 포스의 배열의 각 요소가 재생되는 시간을 나타낸다.

DIEFFECT 의 dwDuration 멤버로 설정된 시간이 지날 때까지, 커스텀 포스는 반복해 일한다.

[Visual Basic]

커스텀 포스를 생성하려면 , 우선 매그니튜드의 배열을 정의한다. 모든 매그니튜드는 -10, 000 에서 10,000 의 범위에 포함된다. 다음에, 이 배열을 DirectInputDevice.CreateCustomEffect 메소드에 건네준다.

samplePeriod 파라미터와DIEFFECT 형의 lSamplePeriod 멤버에 같은 값을 설정한다. 이 값은 밀리 세컨드 단위의 시간이며, 포스의 배열의 각 요소가 재생되는 시간을 나타낸다.

DIEFFECT.lDuration 로 설정된 시간이 지날 때까지, 커스텀 포스는 반복해 일한다.


디바이스 이펙트

하드웨어 드라이버는, DirectInput 가 정의하는 카테고리에 들어맞지 않는 특수 효과를 지원 할 수가 있다. 이러한 이펙트에 대응하는 타입 고유의 파라미터는, 하드 코딩 되고 있는 일도 있으면, 어플리케이션으로 변경할 수 있는 일도 있다.

[C++]

타입 고유의 파라미터가 변경 가능한 경우, 어플리케이션 개발자는, 이펙트에 의해 요구되는 데이터 구조를 선언하고 있는 헤더 파일을 취득해야 한다.

하드웨어 벤더는, 그 디바이스 고유 이펙트를 식별하는 GUID 를 제공해야 한다. 또 하드웨어 벤더는, 그 이펙트에 대한 타입 고유 파라미터용의 특별한 구조체를 제공하는 일도 있다. 다음에, 어플리케이션은,DIEFFECT 구조체와 그 이펙트에 대한 타입 고유 구조체를, 다른 어느 이펙트에서도 같이이지만, 초기화해야 한다. 다음에,IDirectInputDevice7::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 를 돌려준다.

[Visual Basic]

DirectX for Visual Basic 는, 커스텀의 타입 고유 파라미터를 요구하는 하드웨어 이펙트를 지원 하고 있지 않다.

하드웨어 벤더는, 디바이스 고유의 이펙트를 식별하는 GUID 를 제공해야 한다. 다음에, 어플리케이션은, 다른 이펙트와 같게,DIEFFECT 형을 초기화해야 한다. 다음에, 이 형태를 GUID 와 함께 DirectInputDevice.CreateEffect 메소드에 건네준다.

DirectInputEnumEffects 열거에 디바이스 고유의 이펙트에 대한 정보가 들어가지만,DirectInputEnumEffects.GetType 의 반환값의 하위 바이트는, 정의 끝난 DirectInput 의 이펙트 타입 (정수 포스, 경사 포스, 주기적 이펙트, 조건)의 어느 것으로 디바이스 이펙트가 분류되는지를 나타내고 있다. 정의 끝난 카테고리의 어느 것에도 분류할 수 없는 경우, 하위 바이트의 값은 DIEFT_HARDWARE 이다.

디바이스 고유의 이펙트가 정의 끝난 몇개의 종류로 분류할 수 있으면, 그 카테고리의 표준 포스의 경우와 같게,DIEFFECT 형을 초기화해야 한다. 예를 들어, 이펙트 타입이 DIEFT_CONSTANTFORCE 인 경우는,constantForce 멤버를 초기화할 필요가 있다.

DirectInput 는 확인을 위해, GUID 와 DIEFFECT 를 디바이스 드라이버에 건네준다. GUID 가 미지인 경우, 디바이스는 DIERR_DEVICENOTREG 를 돌려준다. GUID 는 기존에서도, 타입 고유 데이터가 그 이펙트에 대해서 부정확한 경우는, 디바이스는 DIERR_INVALIDPARAM 를 돌려준다.


전의 버젼의 DirectInput 의 설계

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

DirectInput 에서는, 버젼 번호를 메소드에 건네주지 않으면 안 되는 것이 있다. 이 파라미터는, DirectInput 서브 시스템이 어느 버젼의 Direct X 를 에뮬레이트 하는지를 지정한다.

최신 버젼의 DirectInput 용으로 설계된 어플리케이션은, Dinput.h 로 정의되고 있는 DIRECTINPUT_VERSION 값을 건네줄 필요가 있다.

이전의 버젼으로 실행하도록(듯이) 설계된 어플리케이션에서는, 설계 대상의 DirectInput 의 버젼에 대응한 값, 즉 상위 바이트에 메인 버젼 번호를 매긴 값을 건네줄 필요가 있다. 예를 들어, DirectInput 3 상에서 동작하도록(듯이) 설계된 어플리케이션은, 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 이후의 버젼으로 이용 가능).


DirectInput 튜토리얼

여기에서는, Microsoft® DirectInput® 의 기본적인 기능을 스텝바이스텝으로 설명하고 있다.

  • DirectInput C/C++ 튜토리얼
  • DirectInput Visual Basic 튜토리얼


DirectInput C/C++ 튜토리얼

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

여기에서는, 다음의 튜토리얼을 사용해, DirectInput 의 기본적인 기능을 C 또는 C++ 어플리케이션에 이행 하는 방법을 단계적으로 설명한다.

  • 튜토리얼 1 : 키보드의 사용

    최초의 튜토리얼은, 기존의 어플리케이션에 DirectInput 키보드 지원을 추가하는 순서를 나타낸다.

  • 튜토리얼 2 : 마우스의 사용

    2 번째의 튜토리얼은, 어플리케이션으로 DirectInput 마우스 지원을 실현하는 순서를 나타낸다. 이 튜토리얼은,Scrawl 샘플을 기본으로 하고 있어, 버퍼링 데이터에 초점을 맞힌다.

  • 튜토리얼 3 : 죠이스틱의 사용

    이 튜토리얼은, 시스템에 접속되고 있는 죠이스틱을 모두 열거하는 방법, 콜백 함수로 각 죠이스틱에 대한 DirectInput 디바이스 오브젝트를 생성 해 초기화하는 방법, 및 직접 데이터를 취득하는 방법을 나타낸다. 샘플 코드는,Space Donuts 샘플을 기본으로 하고 있다.

  • 튜토리얼 4 : force feedback의 사용

    마지막 튜토리얼은, force feedback 죠이스틱에서의 단순한 이펙트의 생성과 조작에 대해 설명한다.


튜토리얼 1 : 키보드의 사용

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

키보드 입력의 준비를 실시하려면 , 우선, DirectInput 오브젝트의 인스턴스를 생성 한다. 다음에,IDirectInput7::CreateDeviceEx 메소드를 사용해,IDirectInputDevice7 인터페이스의 인스턴스를 생성 한다. IDirectInputDevice7 인터페이스의 각 메소드는, 디바이스의 조작, 디바이스의 동작의 설정, 및 데이터의 취득을 실시하는데 사용한다.

이 튜토리얼에서는, 필요한 태스크를 이하의 순서에 분할하고 있다.

  • 스텝 1 : DirectInput 오브젝트의 생성
  • 스텝 2 : DirectInput 키보드 디바이스의 생성
  • 스텝 3 : 키보드 데이터 형식의 설정
  • 스텝 4 : 키보드의 동작의 설정
  • 스텝 5 : 키보드에의 액세스권의 취득
  • 스텝 6 : 키보드로부터의 데이터의 취득
  • 스텝 7 : DirectInput 시스템의 종료

DirectInput 키보드 지원을 어플리케이션에 추가하는 것은, 비교적 간단해서, 이 튜토리얼은, 완전한 샘플 어플리케이션으로는 되지 않았다. 튜토리얼의 모든 순서는, 본문내의 코드로 구체적으로 가리키고 있다. 시스템의 초기화의 관련 순서는, 「샘플 함수 1 : DI_Init 」에 정리해 있다. 시스템을 종료시킬 필요가 있을 때는, 이제(벌써) 1 개의 함수 「샘플 함수 2 : DI_Term 」가, 반드시 불린다.


스텝 1 : DirectInput 오브젝트의 생성

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

DirectInput 시스템의 셋업 순서의 처음은, 전체의 매니저로서 단일의 DirectInput 오브젝트를 생성 하는 것이다. 이것은,DirectInputCreateEx 함수를 호출하는 것에 의해 실시한다.

// HINSTANCE hinst; // 이전에 초기화가 끝난 상태.
HRESULT         hr;
LPDIRECTINPUT7  g_lpdi;

hr = DirectInputCreateEx(hinst, DIRECTINPUT_VERSION,
IID_IDirectInput7, (void**) &g_lpdi, NULL);
if FAILED(hr)
{
// DirectInput 는 이용 가능하지 않다. 적절한 조치를 취한다.
  }

DirectInputCreateEx 의 제 1 파라미터는, 오브젝트를 생성 하는 어플리케이션 또는 DLL 의 인스턴스 핸들이다.

제 2 파라미터는, 어느 버젼의 DirectInput 시스템을 DirectInput 오브젝트에 사용하는지를 지시한다. 이전의 버젼의 DirectInput 와 호환성이 있는 어플리케이션을 설계할 수도 있다. 상세한 것에 대하여는, 「전의 버젼의 DirectInput 의 설계」를 참조할것.

제 3 파라미터는, 어느 인터페이스가 돌려주어지는지를 지정한다. 대부분의 어플리케이션은 IID_IDirectInput7 를 건네주는 것으로, 최신의 버젼을 취득한다.

제 4 파라미터는, 이 호출이 성공했을 경우에, 유효한 인터페이스 포인터로 초기화되는 변수의 주소이다.

마지막 파라미터에는, COM 집합화로 사용하는 제어 오브젝트의 IUnknown 인터페이스의 주소를 지정한다. 어플리케이션은, 보통, 집합화를 사용하지 않기 때문에 NULL 를 건네준다.

다음 방향 : 스텝 2 : DirectInput 키보드 디바이스의 생성


스텝 2 : DirectInput 키보드 디바이스의 생성

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

DirectInput 오브젝트의 생성 후, 어플리케이션은 키보드 오브젝트 (디바이스)를 생성 해,IDirectInputDevice7 인터페이스에의 포인터를 취득해야 한다. 디바이스는, 이 인터페이스의 메소드를 사용해, 키보드 관련 태스크의 대부분을 실행한다.

이 포인터를 취득하려면 , 「샘플 함수 1 : DI_Init 」로 가리키도록(듯이),IDirectInput7::CreateDeviceEx 메소드를 호출하지 않으면 안 된다. CreateDeviceEx 는, 4 개의 파라미터를 취한다.

제 1 파라미터는, 생성 하는 디바이스의 GUID 이다. 키보드 시스템이 사용되게 되므로, 사전에 정의된 글로벌 변수를 GUID_SysKeyboard 에 건네준다.

제 2 파라미터는, 목적의 인터페이스의 GUID 이다. 대부분의 어플리케이션은 IID_IDirectInputDevice7 를 건네주는 것으로, 최신의 버젼을 취득한다.

제 3 파라미터는, 호출이 성공했을 경우에, 취득한 인터페이스 포인터로 초기화되는 변수의 주소이다.

제 4 파라미터는, COM 집합화로 사용하는 제어 오브젝트의 IUnknown 인터페이스의 주소이다. 집합화를 사용하지 않는 경우에는, 이 파라미터를 NULL 로 한다.

이하의 코드는,IDirectInputDevice7 인터페이스에의 포인터를 취득하려고 하는 예이다. 실패했을 경우에는, DI_Term 어플리케이션 정의 샘플 함수를 호출해, 기존의 DirectInput 오브젝트가 있으면 그 할당을 해제한다.

주 : 모든 예의 g_lpdi 는, DirectInput 오브젝트에 대한 초기화된 포인터이다. 메소드 호출은, C++ 형식이다.

HRESULT hr;
LPDIRECTINPUTDEVICE7  g_lpDIDEVICE

hr = g_lpDI->CreateDeviceEx(GUID_SysKeyboard, IID_IDirectInputDevice7,
(void**) &g_lpDIDevice, NULL);
if FAILED(hr)
{
DI_Term();
return FALSE;
}

다음 방향 : 스텝 3 : 키보드 데이터 형식의 설정


스텝 3 : 키보드 데이터 형식의 설정

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

IDirectInputDevice7 포인터를 취득하면(자), 「샘플 함수 1 : DI_Init 」에 나타내도록(듯이), 디바이스의 데이터 형식을 설정해야 한다. 키보드의 경우, 이것은 매우 간단한 태스크이다. 유저의 편의를 고려해 DirectInput 에 준비되어 있는 데이터 형식을,c_dfDIKeyboard 글로벌 변수로 지정해 IDirectInputDevice7::SetDataFormat 메소드를 호출한다.

이하의 코드는, 데이터 형식을 설정하려고 하는 예이다. 실패했을 경우에는, DI_Term 샘플 함수를 호출해, 기존의 DirectInput 오브젝트가 있으면 그 할당을 해제한다.

hr = g_lpDIDevice->SetDataFormat(&c_dfDIKeyboard);

if FAILED(hr){
DI_Term();
return FALSE;
}

다음 방향 : 스텝 4 : 키보드의 동작의 설정


스텝 4 : 키보드의 동작의 설정

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

어플리케이션은, 키보드에 액세스 하기 전에, 「샘플 함수 1 : DI_Init 」에 나타내도록(듯이),IDirectInputDevice7::SetCooperativeLevel 메소드를 사용해 디바이스의 동작을 설정해야 한다. 이 메소드는, 디바이스에 관련지을 수 있었던 윈도우에의 핸들과 협조 레벨을 결정하는 플래그의 편성을 받는다. 이 경우, 어플리케이션은 foreground의 비배타 액세스를 요구하고 있다.

이하의 코드는, 디바이스의 협조 레벨을 설정하려고 하는 예이다. 실패했을 경우에는, DI_Term 어플리케이션 정의 샘플 함수를 호출해, 기존의 DirectInput 오브젝트가 있으면 그 할당을 해제한다.

// 협조 레벨을 설정한다.
hr = g_lpDIDevice->SetCooperativeLevel(g_hwndMain,
DISCL_FOREGROUND | DISCL_NONEXCLUSIVE);

if FAILED(hr){
DI_Term();
return FALSE;
}

다음 방향 : 스텝 5 : 키보드에의 액세스권의 취득


스텝 5 : 키보드에의 액세스권의 취득

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

키보드의 동작을 설정하면(자), 어플리케이션은,IDirectInputDevice7::Acquire 메소드를 호출해, 디바이스에 대한 액세스권을 취득할 수 있다. 어플리케이션은, 디바이스로부터 데이터를 취득하기 전에, 디바이스를 취득해야 한다. Acquire 메소드에는, 파라미터는 없다.

이하는, 「스텝 2 : DirectInput 키보드 디바이스의 생성」으로 생성 된 키보드 디바이스를 취득하는 코드이다.

if (g_lpDIDevice) g_lpDIDevice->Acquire();

다음 방향 : 스텝 6 : 키보드로부터의 데이터의 취득


스텝 6 : 키보드로부터의 데이터의 취득

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

디바이스를 취득하면, 어플리케이션은, 디바이스로부터의 데이터의 취득을 시작 할 수 있다. 데이터를 취득하는 가장 간단한 방법은,IDirectInputDevice7::GetDeviceState 메소드를 호출하는 것이다. 이 메소드는, 디바이스를 호출했을 때의 그 순간 상태를 취득한다.

GetDeviceState 메소드는 2 개의 파라미터를 취한다. 디바이스 상태 데이터가 설정되는 버퍼의 사이즈와 그 버퍼에의 포인터이다. 키보드의 경우는, 항상, 부호 없음 256 바이트의 버퍼를 선언한다.

이하의 코드는, 키보드 상태를 취득하려고 하는 예이다. 취득에 실패했을 경우, 어플리케이션 정의의 샘플 함수를 호출해, 기존의 DirectInput 오브젝트가 있으면, 그 할당을 해제한다 ( 「샘플 함수 2 : DI_Term 」를 참조).

키보드의 현재 상태를 취득한 후, 어플리케이션은, 호출시에 밀린 특정의 키에 응답할 수가 있다. 버퍼중의 각 요소가 1 개의 키를 나타낸다. 요소의 상위 비트가 온의 경우, 그 키는, 호출시에 밀리고 있던 것을 나타낸다. 그 이외의 경우는, 키는 밀리지 않았다. 어느 키 상태를 체크하려면 , DirectInput 의키보드 디바이스 정수를 사용해, 그 키에 대한 버퍼의 인덱스를 생성 한다.

이하의 코드는, 어느 가상의 우주선 게임의 메인 루프로부터 불려 가는 스켈리턴 함수이다. 여기에서는,IDirectInputDevice7::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 시스템의 종료

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

어플리케이션을 종료하기 직전에, 모든 DirectInput 오브젝트를 릴리즈 할 필요가 있다. 이것은 3 단계의 처리로부터 완성된다.

  • 모든 DirectInput 디바이스의 액세스권을 릴리즈 한다 (IDirectInputDevice7::Unacquire )
  • 모든 DirectInput 디바이스를 릴리즈 한다 (IDirectInputDevice7::Release)
  • DirectInput 오브젝트를 릴리즈 한다 (IDirectInput7::Release)

DirectInput 시스템을 종료시키는 함수의 샘플은, 「샘플 함수 2 : DI_Term 」를 참조할것.


샘플 함수 1 : DI_Init

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

이 어플리케이션 정의 샘플 함수는, DirectInput 오브젝트를 생성 해 초기화해, 필요한 인터페이스 포인터를 취득해, 그러한 포인터를 글로벌 변수에 할당한다. 초기화가 완료하면(자), 디바이스를 취득한다.

초기화의 어느 부분에서 실패해도, 이 함수는, DI_Term 어플리케이션 정의 샘플 함수를 호출해, 프로그램을 종료할 준비로서 DirectInput 오브젝트와 인터페이스 포인터의 할당을 해제한다 ( 「샘플 함수 2 : DI_Term 」를 참조).

DI_Init 함수는, DirectInput 오브젝트를 생성 하는 것에 가세해, 이하의 튜토리얼 순서로 설명되고 있는 태스크를 실행한다.

  • 스텝 2 : DirectInput 키보드 디바이스의 생성
  • 스텝 3 : 키보드 데이터 형식의 설정
  • 스텝 4 : 키보드의 동작의 설정
  • 스텝 5 : 키보드의 액세스권의 취득

이하는, DI_Init 함수이다.

/ * 다음의 변수는 초기화가 끝난 상태로 한다.
HINSTANCE             g_hinst;    // 어플리케이션 인스턴스
HWND                  g_hwndMain; // 어플리케이션 윈도우
*/
LPDIRECTINPUT7        g_lpDI;
LPDIRECTINPUTDEVICE7  g_lpDIDevice;

BOOL WINAPI DI_Init()
{
HRESULT hr;

// DirectInput 오브젝트를 생성 한다.
hr = DirectInputCreateEx(g_hinst, DIRECTINPUT_VERSION,
IID_IDirectInput7, (void**) &g_lpDI, NULL);
if FAILED(hr) return FALSE;

// IDirectInputDevice7 인터페이스에의 포인터를 취득한다.
hr = g_lpDI->CreateDeviceEx(GUID_SysKeyboard,
IID_IDirectInputDevice7, (void**) &g_lpDIDevice, NULL);
if FAILED(hr)
    {
DI_Term();
return FALSE;
    }

// IDirectInputDevice7 인터페이스를 보관 유지해,
// 사용 준비가 갖추어졌더니 있다.

// 키보드용 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

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

이 어플리케이션 정의 샘플 함수는, 프로그램을 종료할 준비로서 또는 디바이스의 정상적인 초기화가 실패했을 경우의 처리로서 기존의 DirectInput 인터페이스 포인터의 할당을 해제한다.

/ * 다음의 변수는 초기화가 끝난 상태로 한다.
LPDIRECTINPUT7        g_lpDI;
LPDIRECTINPUTDEVICE7  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;
    }
}


튜토리얼 2 : 마우스의 사용

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

이 튜토리얼에서는, 마우스 디바이스를 셋업 해, 입력의 버퍼링 데이터를 취득하는 작업을 순서를 쫓아 설명한다. 이 예는,Scrawl 샘플을 기본으로 하고 있다.

마우스 입력의 준비를 실시하려면 , 우선, DirectInput 오브젝트의 인스턴스를 생성 한다. 다음에,IDirectInput7::CreateDeviceEx 메소드를 사용해,IDirectInputDevice7 인터페이스의 인스턴스를 생성 한다. IDirectInputDevice7 인터페이스의 각 메소드는, 디바이스의 조작, 디바이스의 동작의 설정, 및 데이터의 취득을 실시하는데 사용한다.

DirectInput 시스템의 셋업의 준비 순서와 시스템을 종료하는 마지막 순서는, 어느 어플리케이션에서도 같고, 「튜토리얼 1 : 키보드의 사용」으로 설명되어 있다.

이 튜토리얼에서는, 필요한 태스크를 이하의 순서에 분할하고 있다.

  • 스텝 1 : DirectInput 마우스 디바이스의 생성
  • 스텝 2 : 마우스 형식의 설정
  • 스텝 3 : 키보드의 동작의 설정
  • 스텝 4 : 마우스로부터의 버퍼링 데이터 입력의 준비
  • 스텝 5 : 마우스에의 액세스권의 관리
  • 스텝 6 : 마우스로부터의 버퍼링 데이터의 취득

주 : 어플리케이션이 배타 협조 레벨로 마우스를 취득하고 있을 때, Windows 는 마우스 포인터를 화면에 표시하지 않는다. 이 때문에, 어플리케이션에는, 간단한 스프라이트 엔진이 필요하다. Scrawl 샘플 어플리케이션에서는, Win32 함수의 DrawIcon 를 사용해 십자 커서를 화면에 표시한다.


스텝 1 : DirectInput 마우스 디바이스의 생성

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

DirectInput 오브젝트를 생성 하면, 어플리케이션은, 마우스 관련 태스크의 대부분을 실행하는데 사용하는 IDirectInputDevice7 인터페이스에의 포인터를 취득할 필요가 있다. 이 포인터를 취득하려면 ,IDirectInput7::CreateDeviceEx 메소드를 호출한다.

CreateDeviceEx 의 제 1 파라미터는, 어플리케이션이 생성 하려고 하고 있는 디바이스의 GUID (Globally Unique IDentifier) 값이다. 이 경우는 시스템 마우스를 사용하므로, 어플리케이션은, 사전 정의된 글로벌 변수의 GUID_SysMouse 를 건네줄 필요가 있다.

제 2 파라미터는, 목적의 DirectInputDevice 인터페이스의 GUID 이다. 대부분의 어플리케이션은 최신의 인터페이스를 요구하므로, IID_IDirectInputDevice7 를 건네준다.

제 3 파라미터는, 이 호출이 성공했을 경우에, 유효한 IDirectInputDevice7 인터페이스 포인터로 초기화되는 변수의 주소이다.

제 4 파라미터는, COM 집합화로 사용하는 제어 오브젝트의 IUnknown 인터페이스의 주소이다. 집합화를 사용하지 않는 경우에는, 이 파라미터를 NULL 로 한다.

이하의 코드는,IDirectInputDevice7 인터페이스에의 포인터를 취득하려고 하는 예이다. 호출이 실패하면, FALSE 가 돌려주어진다. g_pdi 는,IDirectInput7 에의 유효한 포인터이라고 가정한다.

LPDIRECTINPUTDEVICE g_pMouse;
HRESULT             hr;

hr = g_pdi->CreateDeviceEx(GUID_SysMouse, IID_IDirectInputDevice7,
(void**) &g_pMouse, NULL);

if (FAILED(hr)) {
return FALSE;
}

다음 방향 : 스텝 2 : 마우스 형식의 설정


스텝 2 : 마우스 형식의 설정

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

IDirectInputDevice7 포인터를 취득하면(자), 디바이스의 데이터 형식을 설정해야 한다. 마우스의 경우, 이것은 매우 간단한 태스크이다. 편의상 DirectInput 에 준비되어 있는 데이터 형식을,c_dfDIMouse 글로벌 변수로 지정해 IDirectInputDevice7::SetDataFormat 메소드를 호출한다.

이하는, 디바이스의 데이터 형식을 설정하려고 하는 코드이다. 호출이 실패하면, FALSE 가 돌려주어진다.

hr = g_pMouse->SetDataFormat(&c_dfDIMouse);

if (FAILED(hr)) {
return FALSE;
}

다음 방향 : 스텝 3 : 키보드의 동작의 설정


스텝 3 : 키보드의 동작의 설정

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

어플리케이션이 마우스에 대한 액세스권을 취득할 수 있도록(듯이) 하려면 , 미리,IDirectInputDevice7::SetCooperativeLevel 메소드를 사용해 마우스 디바이스의 동작을 설정해야 한다. 이 메소드는, 디바이스에 관련지을 수 있었던 윈도우의 핸들을 받는다. Scrawl 에서는, DISCL_EXCLUSIVE 플래그가 지정되고 있으므로, 마우스 디바이스에 대한 배타 액세스권을 가지는 것은, 이 어플리케이션뿐이다고 하는 것이 보증된다. 이 플래그와 DISCL_FOREGROUND 를 조합하고 있는 이유는, 다른 어플리케이션이 foreground에 있을 때의 마우스의 동작에는, Scrawl 는 칸치 하지 않기 때문에이다.

이하는, 디바이스의 협조 레벨을 설정하려고 하는 코드이다. 설정에 실패하면, FALSE 가 돌려주어진다.

hr = g_pMouse->SetCooperativeLevel(hwnd,
DISCL_EXCLUSIVE | DISCL_FOREGROUND);

if (FAILED(hr)) {
return FALSE;
}

다음 방향 : 스텝 4 : 마우스로부터의 버퍼링 데이터 입력의 준비


스텝 4 : 마우스로부터의 버퍼링 데이터 입력의 준비

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

Scrawl 어플리케이션은, 이벤트 통지를 사용해 마우스의 동작을 검출하는 방법, 및 마우스로부터의 버퍼링 입력을 읽어내는 방법을 나타내고 있다. 이 방법은 어느쪽이나, 어느 정도의 셋업을 필요로 한다. 그러한 순서는, 마우스 디바이스의 생성 다음에, 마우스 디바이스의 취득전이면 언제라도 실행할 수 있다.

우선, 이벤트를 생성 해, 마우스 디바이스와 관련짓는다. 이것에 의해, 새로운 유효 데이터가 발생한 것을 나타내는 하드웨어 인터럽트가 있으면, 언제라도 마우스 디바이스 오브젝트에 통지하도록(듯이), DirectInput 에 지시하고 있게 된다.

이하는 Scrawl 에서의 처리 방법이다. 여기서,g_hevtMouse 는 글로벌 HANDLE 이다.

g_hevtMouse = CreateEvent(0, 0, 0, 0);

if (g_hevtMouse == NULL) {
return FALSE;
}

hr = g_pMouse->SetEventNotification(g_hevtMouse);

if (FAILED(hr)) {
return FALSE;
}

우선, 이 단계에서 버퍼 사이즈를 설정할 필요가 있다. 이것은, 프로그램이 입력 데이터를 참조할 준비를 할 수 있을 때까지, DirectInput 가 모든 입력 데이터를 저장 할 수 있도록(듯이) 하기 위한(해)이다. 디폴트의 버퍼 사이즈는 제로이므로, 이 순서는, 버퍼링 데이터를 사용하는 경우의 기본적 순서인 것을, 기억해 두는 것.

이벤트 통지에서는, 버퍼링 데이터를 사용할 필요는 없다. 다만, 필요에 따라서, 이벤트 통지의 직후에 데이터를 취득할 수도 있다.

버퍼 사이즈를 설정하려면 ,DIPROPDWORD 구조체를, 구조체 자체에 대한 정보와 설정하고 싶은 프로퍼티에 대한 정보로 초기화할 필요가 있다. 대부분의 값은, 정형적인 것이지만, 마지막 dwData 는 중요한 값이다. 이것은, 버퍼가 보관 유지하는 항목수에 초기화한다.

#define DINPUT_BUFFERSIZE 16

DIPROPDWORD dipdw =
    {
// 헤더
        {
sizeof(DIPROPDWORD),        // diph.dwSize
sizeof(DIPROPHEADER),       // diph.dwHeaderSize
0,                          // diph.dwObj
DIPH_DEVICE,                // diph.dwHow
        },
// 데이터
DINPUT_BUFFERSIZE,              // dwData
    };

다음에, 헤더 (DIPROPDWORD 구조 체내의 DIPROPHEADER 구조체)의 주소라고 변경하고 싶은 프로퍼티의 식별자를, 다음과 같이 IDirectInputDevice7::SetProperty 메소드에 건네준다.

hr = g_pMouse->SetProperty(DIPROP_BUFFERSIZE, &dipdw.diph);

if (FAILED(hr)) {
return FALSE;
 }

이것으로 셋업은 완료해, 언제라도 마우스를 취득해 데이터의 수집을 시작할 수 있다.

다음 방향 : 스텝 5 : 마우스에의 액세스권의 관리


스텝 5 : 마우스에의 액세스권의 관리

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

DirectInput 는, 디바이스의 액세스권을 관리하기 위해서,IDirectInputDevice7::Acquire 및 IDirectInputDevice7::Unacquire 메소드를 제공한다. 어플리케이션은, 우선 Acquire 메소드를 호출해, 디바이스에 대한 액세스권을 취득해야 한다. 다음에,IDirectInputDevice7::GetDeviceState 메소드와 IDirectInputDevice7::GetDeviceData 메소드를 사용해, 마우스 정보를 요구한다.

대부분의 경우, 어플리케이션은 디바이스를 취득한다. 그러나, foreground 액세스 밖에 가지지 않는 경우는, 어플리케이션이 백그라운드로 이행하면(자) 반드시 마우스는 릴리즈 된다. 포커스가 돌아왔을 경우에는, 확실히 디바이스를 재취득할 필요가 있다. 이것은, WM_ACTIVATE 메세지에 반응하는 것으로 실시할 수가 있다.

Scrawl 에서는, 어플리케이션이 포커스를 취득하는지, 혹은 잃는지에 맞추어, 글로벌 변수의 g_fActive 를 설정하는 것으로, 이 메세지를 처리하고 있다. 다음에, 헬퍼-함수의 Scrawl_SyncAcquire 를 호출한다. 이 헬퍼-함수는,g_fActive 가 TRUE 의 경우에 마우스를 취득해, 그렇지 않은 경우에는 마우스를 릴리즈 한다.

case WM_ACTIVATE:
g_fActive = wParam == WA_ACTIVE || wParam == WA_CLICKACTIVE;
Scrawl_SyncAcquire(hwnd);
break;

배타 액세스권을 가지고 있는 경우, 메뉴나 다이알로그 박스에 액세스 하는 등, 유저가 대화 형식에서 Windows 를 조작할 수 있도록(듯이), 어플리케이션은 마우스를 릴리즈 해야 하는 것이 있다. Scrawl 에서는, Alt 키와 스페이스 키를 동시에 누르는 것으로, 유저가 시스템 메뉴를 열 수가 있다.

Scrawl 의 윈도우 프로시저는, WM_ENTERMENULOOP 에 대한 핸들러를 가지고 있다. 이 핸들러는, 글로벌 변수 g_fActive 에 FALSE 를 설정해, Scrawl_SyncAcquire 함수를 호출하는 것으로 응답한다. 이 핸들러를 사용하면(자), Windows 는 마우스를 보관 유지해, 독자적인 커서를 표시할 수가 있다.

유저가 메뉴의 사용을 종료 하면, Windows 는 어플리케이션에 WM_EXITMENULOOP 메세지를 보낸다. 이 경우, Scrawl 의 윈도우 처리에 의해, 어플리케이션 정의 메세지의 WM_SYNCACQUIRE 가 어플리케이션 자체의 메시지 큐에 송신된다. 이것에 의해, Scrawl_SyncAcquire 함수로 마우스가 재취득되기 전에, 다른 대기중의 메세지가 처리된다.

또, Scrawl 는, context menu를 여는 오른쪽 버튼 클릭에 응답해, 마우스를 릴리즈 한다. 마우스는 늦어 릴리즈 되지만, WM_ENTERMENULOOP 핸들러에서는, 메뉴가 표시되기 전에 Windows 커서의 위치를 설정할 수 있도록(듯이), 최초로 마우스를 릴리즈 하고 있다.

마지막으로, Scrawl 는, 데이터의 취득을 시도해 DIERR_INPUTLOST 에러가 돌려주어지면(자), 마우스의 재취득을 시도한다. 이것은, 다른 개소에서는 처리되지 않는 방법에 따라 디바이스가 릴리즈 되었을 경우에의 준비이다. 예를 들어, 유저가 Ctrl+Alt+Del 키를 눌렀을 경우 등이다.

정리하면(자), 어플리케이션은, 마우스로부터 데이터를 취득하기 전에, 마우스를 취득할 필요가 있다. 마우스의 취득은, 어플리케이션에 강제적으로 마우스의 액세스권을 방폐시키는 사태가 발생하지 않는 한, 한 번만 실시하면 끝난다. 배타 모드에서는, Windows 가 마우스를 필요로 할 때, 마우스의 제어를 방폐해야 한다. 또, 마우스의 액세스권을 Windows 또는 그 외의 어플리케이션에 양보한 후, 마우스에 대한 액세스권이 필요하게 되었을 경우는, 마우스를 재취득해야 한다.

다음 방향 : 스텝 6 : 마우스로부터의 버퍼링 데이터의 취득


스텝 6 : 마우스로부터의 버퍼링 데이터의 취득

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

마우스를 취득하면, 어플리케이션은, 마우스로부터의 데이터의 취득을 시작 할 수가 있다.

Scrawl 샘플에서는, 데이터 취득은, 통지된 이벤트가 방아쇠가 된다. 시그널이나 메세지가 있는 것이 MsgWaitForMultipleObjects 로부터 나타날 때까지, 어플리케이션은,WinMain 함수 중(안)에서 sleeve 상태에 들어간다. 마우스 관련의 시그널이 있으면, Scrawl_OnMouseInput 함수가 불려 간다. 이 함수는, 버퍼링 입력을 취급하는 방법의 좋은 예이므로, 이하 상세하게 설명한다.

우선, 이 함수는, 원의 커서 위치가 완전하게 소거되고 있는 것을 확인한다. Scrawl 는 독자적인 커서를 유지해, 그 드로잉(Drawing)나 소거를 전면적으로 실시하지 않으면 안 되는 것에 주의한다.

void Scrawl_OnMouseInput(HWND hwnd)
{
/* 원의 커서는, 클리어 되므로 무효가 된다.
InvalidateCursorRect(hwnd);

여기서, 함수는 루프에 들어가, 버퍼의 전내용에 대한 읽기 및 응답을 실시한다. 데이터는 한 번에 1 항목 밖에 취득할 수 없기 때문에, 데이터를 보관 유지하기 위해서는,DIDEVICEOBJECTDATA 구조체가 1 개만 있으면 좋다.

입력 처리에는 이 밖에도, 버퍼 전체를 한 번에 읽어낸 후, 루프로 취득 항목을 순서에 1 개씩 응답해 나가는 방법이 있다. 그 경우는,dwElements 를 버퍼 사이즈로 해,od 는 그 사이즈에 동일한 수의 요소를 가지는 배열로 한다.

    while (! fDone) {
        DIDEVICEOBJECTDATA od;
        DWORD dwElements = 1;   // 취득해야 할 항목수

어플리케이션은, 데이터를 취득하기 위해서 IDirectInputDevice7::GetDeviceData 메소드를 호출한다. 제 2 파라미터는 데이터를 두는 위치를, 제 3 파라미터는 필요한 항목수를, DirectInput 에 각각 통지한다. 데이터를 버퍼에 남겨 두는 경우는, 마지막 파라미터를 DIGDD_PEEK 로 한다. 다만, 이 경우는, 데이터를 재차 필요로 할 것은 없기 때문에 삭제한다.

        HRESULT hr = g_pMouse->GetDeviceData(
                             sizeof(DIDEVICEOBJECTDATA),
                             &od,
                             &dwElements, 0);

여기서, 어플리케이션은, 디바이스에 대한 액세스권이 없어지고 있는지 어떤지의 확인 체크를 실시해, 없어지고 있으면 곧바로 적절한 타이밍에 마우스의 재취득을 실시하도록(듯이) 자신에게 지시한다. 이 순서는, 「스텝 5 : 마우스에의 액세스권의 관리」로 설명한다.

        if (hr == DIERR_INPUTLOST) {
            PostMessage(hwnd, WM_SYNCACQUIRE, 0, 0L);
            break;
        }

다음에, 어플리케이션은,GetDeviceData 메소드의 호출이 성공한 것, 및 취득하는 데이터가 실제로 존재한 것을 확인한다. GetDeviceData 의 호출 후,dwElements 변수는 실제로 취득한 항목수를 나타내고 있는 것에 주의한다.

        /* 데이터를 읽을 수 없는, 또는 이용 가능 데이터가 없다. */
        if (FAILED(hr) || dwElements == 0) {
            break;
        }

여기까지 실행이 진행되면, 모두 순조롭다. 즉, 호출은 성공해, 버퍼에는 데이터 항목이 존재한다. 여기서, 어플리케이션은,DIDEVICEOBJECTDATA 구조체의 dwOfs 멤버를 조사해 디바이스 위에의 어느 오브젝트가 상태 변화를 보고했는지를 확인한다. 다음에, 헬퍼-함수를 호출해, 적절히 대응한다. dwData 멤버의 값은, 상태에 관한 정보를 가지고 있어 이러한 헬퍼-함수에게 건네진다.

        /* 요소를 조사해 무엇이 발생했는지를 확인한다. */

        switch (od.dwOfs) {

        /* DIMOFS_X:마우스의 수평 동작. */
        case DIMOFS_X: UpdateCursorPosition(od.dwData, 0); break;

        /* DIMOFS_Y:마우스의 수직 동작. */
        case DIMOFS_Y: UpdateCursorPosition(0, od.dwData); break;

        /* DIMOFS_BUTTON0:버튼 0 을 누르는 혹은 떼어 놓는다. */
        case DIMOFS_BUTTON0:

            if (od.dwData & 0x80) { /* 버튼을 누른다. */
                fDone = 1;
                Scrawl_OnButton0Down(hwnd); /* 버튼 압하 모드에
                                               바뀐다. */
            }
            break;

        /* DIMOFS_BUTTON1:버튼 1 을 누르는 또는 떼어 놓는다. */
        case DIMOFS_BUTTON1:

            if (! (od.dwData & 0x80)) {    /* 버튼을 떼어 놓는다. */
                fDone = 1;
                Scrawl_OnButton1Up(hwnd); /* context menu 타임. */
            }
        }

    }

마지막으로, 커서가 몇개의 헬퍼-함수에 의해 이동되었을 경우를 위해서(때문에), Scrawl_OnMouseInput 샘플 함수는, 커서가 점유 하고 있는 화면상의 직사각형을 무효화한다.

/* 새로운 커서가 드로잉(Drawing) 되므로 무효화한다.
InvalidateCursorRect(hwnd);
}

또, Scrawl 는, Scrawl_OnButton0Down 함수에 있는 마우스 데이터를 모은다. 이것은, 주버튼이 압하되고 있는 동안, 즉, 유저가 드로잉(Drawing) 하고 있는 동안의 마우스 이동을, 어플리케이션이 추적하는 함수이다. 이 함수는, 이벤트 통지에는 의존하지 않지만, 버튼이 떼어 놓아질 때까지, 연속적으로 DirectInput 버퍼를 폴링 한다.

Scrawl_OnButton0Down 함수로 주의해야 할 중요한 점은, 모든 대기중의 데이터가 읽힐 때까지는 실제의 드로잉(Drawing)는 행해지지 않는, 이라고 하는 것이다. 이것은, 마우스의 수평 방향과 수직 방향의 이동이, 독립한 이벤트로서 보고되기 때문에 있다 (다만, 양이벤트의 버퍼에의 배치는 동시에 행해진다). 독립한 각각의 축이동에 반응해 직선이 즉시 드로잉(Drawing) 되는 경우, 마우스를 비스듬하게 움직이면(자), 직각에 사귀는 2 직선이 드로잉(Drawing) 되게 된다.

어플리케이션의 응답전에, 양축으로 둘 수 있는 이동이 계산에 넣어지고 있는 것을 확인하려면 , x 축항목과 y 축항목의 순서 번호를 체크하는 방법도 있다. 번호가 동일하면, 2 개의 이벤트가 동시에 발생한 것이 된다. 상세한 것에 대하여는, 「타임 스탬프와 순서 번호」를 참조할것.


튜토리얼 3 : 죠이스틱의 사용

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

이 튜토리얼에서는, 시스템 위에의 죠이스틱을 열거해, 입력용에 2 개 이상의 죠이스틱을 셋업 하는 방법을 나타낸다. 샘플 코드는,Space Donuts 샘플을 기본으로 하고 있다. 메소드 호출은, C 형식에서 실시한다.

DirectInput 시스템의 셋업의 준비 순서와 시스템을 종료하는 마지막 순서는, 어느 어플리케이션에서도 같고, 이것에 대해서는 「튜토리얼 1 : 키보드의 사용」으로 설명되어 있다.

튜토리얼의 최초의 순서는, 디바이스를 열거하는 것, 즉, 사용 가능한 죠이스틱을 확인하는 것이다. 이 처리의 일부로서 각 죠이스틱 디바이스를 초기화해, 필요한 특성을 설정한다. 다음에,IDirectInputDevice7 인터페이스 메소드를 사용해, 각 죠이스틱으로부터 데이터를 취득한다.

이 튜토리얼에서는, 필요한 태스크를 이하의 순서에 분할하고 있다.

  • 스텝 1 : 죠이스틱의 열거
  • 스텝 2 : DirectInput 죠이스틱 디바이스의 생성
  • 스텝 3 : 죠이스틱 데이터 형식의 설정
  • 스텝 4 : 죠이스틱의 동작의 설정
  • 스텝 5 : 죠이스틱에의 액세스권의 취득
  • 스텝 6 : 죠이스틱으로부터의 데이터를 취득


스텝 1 : 죠이스틱의 열거

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

DirectInput 시스템을 생성 하면(자),IDirectInput7::EnumDevices 메소드를 호출해, 죠이스틱을 열거한다. 이 처리를 실시하려면 , 다음의 코드를 사용한다.

// pdi 는, IDirectInput7 에의 초기화 끝난 포인터이다.

pdi->lpVtbl->EnumDevices(pdi, DIDEVTYPE_JOYSTICK,
InitJoystickInput, pdi, DIEDFL_ATTACHEDONLY);

메소드 호출은 C 형식이다. 호출을 간단하게 하기 위해서,IDirectInput7_EnumDevices 매크로를 사용하는 것에 주의 해야 한다. 모든 DirectInput 메소드에는, 거기에 대응하는, Dinput.h 로 정의된 매크로가 포함되어 있어, 적절한 C 또는 C++ 의 문법에 따라 전개한다.

제 2 파라미터로서 건네받는 DIDEVTYPE_JOYSTICK 정수는, 열거 대상의 디바이스의 타입을 지정한다.

InitJoystickInput 는, 죠이스틱이 발견될 때마다 불려 가는 콜백 함수의 주소이다. 튜토리얼의 이 이후의 스텝에 대해, 개별의 디바이스는 이 함수 중(안)에서 초기화된다.

제 4 파라미터는, 콜백 함수를 사용할 수 있는 임의의 32 비트값이다. 이 경우는, DirectInput 인터페이스에의 포인터이다. 콜백 함수가 IDirectInput7::CreateDeviceEx 메소드를 호출하려면 , 이 포인터가 필요하다.

마지막 파라미터의 DIEDFL_ATTACHEDONLY 는, 열거 대상을 컴퓨터에Attach 되고 있는 디바이스로 한정하는 플래그이다.

다음 방향 : 스텝 2 : DirectInput 죠이스틱 디바이스의 생성


스텝 2 : DirectInput 죠이스틱 디바이스의 생성

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

DirectInput 오브젝트를 생성 하면, 어플리케이션은, 죠이스틱 관련 태스크의 대부분을 실행하는데 사용하는 IDirectInputDevice7 인터페이스에의 포인터를 취득할 필요가 있다. Space Donuts 샘플에서는, 이 처리는, 죠이스틱이 열거될 때마다 불려 가는 콜백 함수 InitJoystickInput 로 행해지고 있다.

이하는, 그 콜백 함수의 최초의 일부이다.

BOOL FAR PASCAL InitJoystickInput(LPCDIDEVICEINSTANCE pdinst,
                                  LPVOID pvRef)
{
   LPDIRECTINPUT7 pdi = pvRef;
   LPDIRECTINPUTDEVICE7 pdev;

   // DirectInput 죠이스틱 디바이스를 생성 한다.
   if (pdi->lpVtbl->CreateDeviceEx(pdi, &pdinst->guidInstance,
          IID_IDirectInputDevice7, (void**) &pdev, NULL) ! = DI_OK)
   {
      OutputDebugString("IDirectInput7::CreateDeviceEx FAILED\n");
      return DIENUM_CONTINUE;
   }

InitJoystickInput 의 콜백 함수의 파라미터는, 이하대로이다.

  • 디바이스 인스턴스에의 포인터. 인스턴스는, 디바이스가 열거되었을 때에 DirectInput 시스템에 의해 공급된다.
  • DirectInput 인터페이스에의 포인터. 이것은,IDirectInput7::EnumDevices 에 대한 파라미터로서 지정한 것이다. 이 파라미터에는, 32 비트의 임의의 값을 취할 수가 있지만, 이 경우,IDirectInput7::CreateDeviceEx 메소드를 호출할 수가 있도록(듯이), DirectInput 인터페이스를 지정한다.

샘플 함수 InitJoystickInput 는, DirectInput 오브젝트에의 로컬 포인터 pdi 를 선언해, 이 포인터에, 콜백 함수에 건네주는 값을 할당한다. 또, DirectInput 디바이스에의 로컬 포인터 pdev 도 선언한다. 이 포인터는, 디바이스의 생성시에 초기화된다.

콜백 함수의 최초의 태스크는, 디바이스를 생성 하는 것이다. IDirectInput7::CreateDeviceEx 메소드는, 4 개의 파라미터를 취한다.

제 1 파라미터는, 호출측의 DirectInput 인터페이스에 대한 포인터이며, C++ 에서는 불필요하다.

제 2 파라미터는, 디바이스의 인스턴스의 GUID 에 대한 참조값이다. 이 경우, GUID 는 DirectInput 가 디바이스를 열거했을 때에 주는 DIDEVICEINSTANCE 구조체로부터 놓친다.

제 3 파라미터는, 호출이 성공했을 경우에, 유효한 인터페이스 포인터로 초기화되는 변수의 주소이다.

제 4 파라미터는, COM 집합화로 사용하는 제어 오브젝트의 IUnknown 인터페이스의 주소이다. Space Donuts 샘플에서는 집합화를 사용하지 않기 때문에, 파라미터는 NULL 이다.

어떠한 이유로써, 디바이스 인터페이스를 생성 할 수 없는 경우는, 콜백 함수로부터 DIENUM_CONTINUE 가 돌려주어지는 것에 주의 해야 한다. 이 플래그는, 열거 대상의 디바이스가 존재하는 한, 열거를 속행하는 것을 DirectInput 에 지시한다.

다음 방향 : 스텝 3 : 죠이스틱 데이터 형식의 설정


스텝 3 : 죠이스틱 데이터 형식의 설정

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

지금까지 어플리케이션은, DirectInput 디바이스에의 포인터를 취득하고 있으므로,IDirectInputDevice7 메소드를 호출해, 그 디바이스를 조작할 수가 있다. 여기에서는 우선, 죠이스틱의 데이터 형식을 설정한다. 이 순서는 불가결하다. 이 순서에서는, DirectInput 에 대해서 입력 데이터의 서식을 설정하는 방법을 지시한다.

Space Donuts 샘플에서는, 전의 스텝에서 도입한 콜백 함수로 이 처리를 실행한다.

   if (pdev->lpVtbl->SetDataFormat(pdev, &c_dfDIJoystick) ! = DI_OK)
   {
      OutputDebugString("IDirectInputDevice7::SetDataFormat FAILED\n");
      pdev->lpVtbl->Release(pdev);
      return DIENUM_CONTINUE;
   }

pdev 변수는,IDirectInput7::CreateDeviceEx 가 생성 한 디바이스 인터페이스에의 포인터이다.

IDirectInputDevice7::SetDataFormat 메소드는, 2 개의 파라미터를 취한다. 제 1 파라미터는, 이 인터페이스의 호출측 인스턴스에 대한 포인터이며, C++ 에서는 불필요하다. 제 2 파라미터는, 디바이스의 데이터의 서식 설정 방법법에 관한 정보를 저장 하는 DIDATAFORMAT 구조체에의 포인터이다. 죠이스틱의 경우는, 사전 정의된 글로벌 변수 c_dfDIJoystick 를 여기서 사용할 수 있다.

전의 스텝과 같이, 콜백 함수는, 디바이스의 초기화에 실패했을 경우에 DIENUM_CONTINUE 를 돌려준다. 이 플래그는, 열거 대상의 디바이스가 존재하는 한, 열거를 속행하는 것을 DirectInput 에 지시한다.

다음 방향 : 스텝 4 : 죠이스틱의 동작의 설정


스텝 4 : 죠이스틱의 동작의 설정

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

지금까지, 죠이스틱 디바이스의 생성과 디바이스의 데이터 형식의 설정이 완료하고 있다. 다음은, 디바이스의 협조 레벨을 설정하는 것이다. Space Donuts 샘플에서는, 이 처리는, 디바이스가 열거되었을 때에 콜백 함수로 행해진다. 전의 스텝과 같게,pdev 는 디바이스 인터페이스에의 포인터이다.

   if(pdev->lpVtbl->SetCooperativeLevel(pdev, hWndMain,
      DISCL_NONEXCLUSIVE | DISCL_FOREGROUND) ! = DI_OK)
   {
      OutputDebugString("IDirectInputDevice7::SetCooperativeLevel
                         FAILED\n");
      pdev->lpVtbl->Release(pdev);
      return DIENUM_CONTINUE;
   }

여기에서도,IDirectInputDevice7::SetCooperativeLevel 의 제 1 파라미터는, 호출측 오브젝트에 대한 포인터이다.

제 2 파라미터는, 윈도우 핸들이다. 이 경우, 메인 프로그램의 윈도우 핸들이 건네받는다.

마지막 파라미터는, 필요한 협조 레벨을 지정하는 플래그의 편성이다. Space Donuts 샘플이 죠이스틱으로부터의 입력을 요구하는 것은, foreground 어플리케이션의 경우뿐이어, 다른 프로그램이 배타 모드로 죠이스틱을 사용하고 있을지 어떨지에는 주위를 기울이지 않는다. 따라서, 플래그에는 DISCL_NONEXCLUSIVE | DISCL_FOREGROUND 가 설정된다 (이러한 플래그의 상세한 것에 대하여는, 「협조 레벨」을 참조).

최종 순서는, 디바이스의 프로퍼티를 설정하는 것이어, 콜백 함수로 열거되고 있는 각 죠이스틱에 대해서 실행된다. 샘플에서는, 변경되는 프로퍼티에 x 축과 y 축의 양쪽 모두의 범위와데드 존이 포함되어 있다.

범위를 설정하는 것으로써, 돌려주게 하고 싶은 축의 최대치와 최소 값이 무엇으로 있을까를 DirectInput 에 지시하게 된다. 예의 같게, x 축으로 대해 범위 -1, 000 으로부터 +1, 000 을 설정 하면, 죠이스틱이 최좌단에 있는 경우에 값 -1, 000 을, 최우단에 있는 경우에 +1, 000 을, 중앙에 있는 경우에 제로를 각각 돌려주는 것을 요구하게 된다.

데드 존은, 축의 중간에 있는 허용 영역이며, 축이동의 물리적 범위의 10,000 분의 1 단위로 측정된다. x 축으로 대해 1,000 의 데드 존을 설정 하면, 스틱을 중심 위치로부터 축이동 범위의 10 분의 1 만 좌우로 이동해도, 스틱은 중심에 있다고 보이는 것을 나타낸다. 무효 존의 상세한 것에 대하여는, 「죠이스틱축데이터의 해석」을 참조할것.

이하는, x 축의 범위를 설정하는 코드이다.

   DIPROPRANGE diprg;

   diprg.diph.dwSize       = sizeof(diprg);
   diprg.diph.dwHeaderSize = sizeof(diprg.diph);
   diprg.diph.dwObj        = DIJOFS_X;
   diprg.diph.dwHow        = DIPH_BYOFFSET;
   diprg.lMin              = -1000;
   diprg.lMax              = +1000;

   if FAILED(pdev->lpVtbl->SetProperty(pdev,
                   DIPROP_RANGE, &diprg.diph))
   {
      OutputDebugString("IDirectInputDevice7::SetProperty(DIPH_RANGE)
                         FAILED\n");
      pdev->lpVtbl->Release(pdev);
      return FALSE;
   }

여기에서는 최초로,DIPROPRANGE 구조체 diprg 를 설정한다. 그 구조체의 주소는,IDirectInputDevice7::SetProperty 메소드에게 건네진다. 실제로는, 구조체 자체의 주소가 건네받는 것이 아니라, 그 최초의 멤버의 주소가 건네받는다. 최초의 멤버란, 1 개의 DIPROPHEADER 구조체이다. 상세한 것에 대하여는, 「디바이스 프로퍼티」를 참조할것.

프로퍼티 헤더는, 이하의 값으로 초기화된다.

  • 프로퍼티 구조체의 사이즈
  • 헤더 구조체의 사이즈
  • DIJOFS_X 죠이스틱 디바이스 정수 매크로가 돌려주는 값. 프로퍼티를 변경하는 대상의 오브젝트에의 포인터이다.
  • 제 3 파라미터의 해석 방법을 나타내는 플래그.

DIPROPRANGE 구조체의 lmin 와 lmax 멤버에 필요한 범위값을 할당한다.

어플리케이션은, 여기서 IDirectInputDevice7::SetProperty 메소드를 호출한다. 지금까지와 같게, 제 1 파라미터는, 호출측 오브젝트에 대한 포인터이다. 제 2 파라미터는, 어느 프로퍼티를 변경하는지를 나타내는 플래그이다. 제 3 파라미터는, 프로퍼티 구조체의 DIPROPHEADER 멤버의 주소이다.

x 축의무효 존의 설정도 이와 같이 해 실시할 수 있다. Space Donuts 샘플은, 헬퍼-함수 SetDIDwordProperty 를 사용해,DIPROPDWORD 프로퍼티 구조체를 초기화한다. DIPROPRANGE 과는 달리, 이 구조체에는, 예에서는 5,000 이 설정되어 있는 데이터 멤버가 1 개 밖에 포함되지 않았다. 이 값은, 축이 중심으로부터 그 범위의 반을 움직이지 않으면 축이 중심을 떨어졌다고는 보고되지 않는 것을 나타낸다.

   // X 축의 무효 존을 50% 로 설정한다 (불측의 회전을 피하기 (위해)때문에).
   if FAILED(SetDIDwordProperty(pdev, DIPROP_DEADZONE, DIJOFS_X,
                                DIPH_BYOFFSET, 5000))
   {
      OutputDebugString("IDirectInputDevice7::
                           SetProperty(DIPH_DEADZONE) FAILED\n");
      pdev->lpVtbl->Release(pdev);
      return FALSE;
   }

다음 방향 : 스텝 5 : 죠이스틱에의 액세스권의 취득


스텝 5 : 죠이스틱에의 액세스권의 취득

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

죠이스틱의 동작을 설정하면(자), 어플리케이션은,IDirectInputDevice7::Acquire 메소드를 호출해, 디바이스에 대한 액세스권을 취득할 수 있다. 어플리케이션은, 디바이스로부터 데이터를 취득하기 전에, 디바이스를 취득해야 한다. Acquire 메소드에는, 파라미터는 없다.

Space Donuts 어플리케이션은, ReacquireInput 함수 중(안)에서 디바이스의 취득을 처리하고 있다. 이 함수는, 이중의 기능을 실행한다. 즉, 스타트 업시에 디바이스를 취득하는 기능, 그리고 어플리케이션이 입력 데이터의 취득을 시도해, 어떠한 이유로써 DIERR_INPUTLOST 에러가 돌려주어졌을 때에 디바이스를 재취득하는 기능이다.

이하의 코드에서는,g_pdevCurrent 는, 현재 사용되고 있는 DirectInput 디바이스가 무엇으로 저것, 그에 대한 글로벌 포인터이다.

BOOL ReacquireInput(void)
{
    HRESULT hRes;

    // 현디바이스가 있으면,
    if (g_pdevCurrent)
    {
        // 그것을 취득한다.
        hRes = IDirectInputDevice_Acquire(g_pdevCurrent);
        // 이 호출은, 다음과 같이 전개되는 매크로이다.
        // g_pdevCurrent->lpVtbl->Acquire(g_pdevCurrent);

        if (SUCCEEDED(hRes))
        {
            // 취득 성공.
            return TRUE;
        }
        else
        {
            // 취득 실패.
            return FALSE;
        }
    }
    else
    {
        // 현디바이스가 없다.
        return FALSE;
    }
}

이 예에서는, 디바이스의 취득은, Dinput.h 로 정의되고 있는 IDirectInputDevice_Acquire 매크로의 호출에 의해 실현되고 있다. 이 매크로는,IDirectInputDevice7::Acquire 메소드에 대한 C 의 호출을 간단하게 하는 것이다.

다음 방향 : 스텝 6 : 죠이스틱으로부터의 데이터를 취득


스텝 6 : 죠이스틱으로부터의 데이터를 취득

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

어플리케이션에서는, 죠이스틱축의 이동보다, 죠이스틱축의 위치가 중요하다라고 하는 것이 많기 때문에, 디바이스로부터는, 버퍼링 데이터보다 직접 데이터를 취득하는 것이 자주(잘) 행해진다. 직접 데이터는,IDirectInputDevice7::GetDeviceState 로 폴링 하는 것에 의해 취득할 수 있다. 디바이스 상태가 변화했을 때, 모든 디바이스 드라이버가 DirectInput 에 통지 하면은 한정되지 않기 때문에, 디바이스 상태를 체크하기 전에 IDirectInputDevice7::Poll 메소드를 호출하는 것은 항상 적절한 처치이다.

Space Donuts 어플리케이션은, 죠이스틱이 액티브한 입력 디바이스이다고 하는 전제로, 렌더링 루프를 사용해, 각 패스에 대해 아래와 같은 함수를 호출한다.

DWORD ReadJoystickInput(void)
{
    DWORD                   dwKeyState;
    HRESULT                 hRes;
    DIJOYSTATE              js;

    // 현재 상태를 읽어내는 죠이스틱을 폴링 한다.
    hRes = IDirectInputDevice7_Poll(g_pdevCurrent);

    // 죠이스틱으로부터 데이터를 입력한다.
    hRes = IDirectInputDevice7_GetDeviceState(g_pdevCurrent,
                                            sizeof(DIJOYSTATE), &js);

    if (hRes ! = DI_OK)
    {
        // 어떠한 이유로써 입력을 잃었기 때문에 읽기가 실패했는지?
        // 그러면 재취득을 시도한다. 이것도 실패하고 싶은들 ,
        // GetDeviceData 로부터의 에러는, DIERR_NOTACQUIRED 이다.
        // 이 결과, 엔들레스 루프에 빠지지 않고 끝난다.
        if(hRes == DIERR_INPUTLOST)
            ReacquireInput();

        // 데이터가 전혀 읽어낼 수 없었다고 하는 사실이 돌려주어진다.
        return 0;
    }

    // 스틱과 버튼의 위치를 조사한다.

    dwKeyState = 0;
    if (js.lX < 0) {
        dwKeyState |= KEY_LEFT;
    } else if (js.lX > 0) {
        dwKeyState |= KEY_RIGHT;
    }

    if (js.lY < 0) {
        dwKeyState |= KEY_UP;
    } else if (js.lY > 0) {
          dwKeyState |= KEY_DOWN;
   }

    if (js.rgbButtons[0] & 0x80) {
        dwKeyState |= KEY_FIRE;
    }

    if (js.rgbButtons[1] & 0x80) {
        dwKeyState |= KEY_SHIELD;
    }

    if (js.rgbButtons[2] & 0x80) {
        dwKeyState |= KEY_STOP;
    }

    return dwKeyState;
}

IDirectInputDevice7_Poll 및 IDirectInputDevice7_GetDeviceState 에의 호출에 주의 해야 한다. 이것들은, 대응하는 메소드에의 C 의 호출을 전개하는 매크로이며, 이 튜토리얼의 전의 스텝에 나온 매크로에 유사하고 있다. 이 매크로에의 파라미터는, 메소드에 건네주는 파라미터와 같다. 이 점은,GetDeviceState 에의 호출에 유사하고 있다.

    hRes = IDirectInputDevice7_GetDeviceState(g_pdevCurrent,
                                             sizeof(DIJOYSTATE), &js);

1 번째의 파라미터는, 호출측 오브젝트에 대한 포인터이다. 제 2 파라미터는, 데이터가 돌려주어지는 구조체의 사이즈이다. 마지막 파라미터는,DIJOYSTATE 형인 이 구조체의 주소이다. 이 구조체는, 최고 6 개의 축, 32 의 버튼, 및 1 개의 시점 하트를 보관 유지한다. 샘플 프로그램에서는, 2 개의 축과 3 개의 버튼 상태를 확인한다.

축의 위치가 제로 의외로 보고되었을 경우, 그 축은무효 존의 외측에 있으므로, 함수는,dwKeyState 변수를 적절히 설정해 응답한다. 이 변수는, 키보드 또는 죠이스틱의 어느쪽이든으로 입력된 현재의 유저 커멘드세트를 보관 유지한다. 예를 들어, 죠이스틱의 x 축이 제로보다 크면, 오른쪽 방향 커서 키가 밀리고 있다고 보인다.

죠이스틱 버튼은, 키 또는 mouse button와 완전히 똑같이 기능한다. 반환값 바이트의 상위 비트가 설정되어 있으면, 버튼이 다운 상태인 것을 나타낸다.


튜토리얼 4 : force feedback의 사용

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

이 튜토리얼에서는, force feedback 죠이스틱으로 단순한 이펙트를 생성, 재생, 변경하는 순서를 나타낸다. 이 이펙트는, 시동 시키려고 해도 좀처럼 시동하지 않는 chain saw에 조금 비슷하다. 샘플 코드는 C++ 로 기술되어 있다.

DirectInput 시스템의 셋업의 준비 순서와 시스템을 종료하는 마지막 순서는, 어느 어플리케이션에서도 기본적으로 같고, 이것에 대해서는 「튜토리얼 1 : 키보드의 사용」으로 설명되어 있다. 그러나, DirectInput force feedback 시스템을 종료 하면나무는, 생성한 이펙트를 해제하는 순서를 추가해야 한다.

튜토리얼에서는, 필요한 태스크를 이하의 순서에 분할하고 있다.

  • 스텝 1 : force feedback 디바이스의 열거
  • 스텝 2 : DirectInput force feedback 디바이스의 생성
  • 스텝 3 : 지원 된 이펙트의 열거
  • 스텝 4 : 이펙트의 생성
  • 스텝 5 : 이펙트의 재생
  • 스텝 6 : 이펙트의 변경


스텝 1 : force feedback 디바이스의 열거

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

최초의 순서는, force feedback 디바이스가 시스템으로 이용할 수 있도록(듯이) 하는 것이다. 이것을 실시하려면 IDirectInput7::EnumDevices 메소드를 호출한다. 다음의 예에서는, 열거가 적어도 1 개의 적합하는 디바이스를 찾아낼 수가 있었을 경우만, 게임 디바이스 인터페이스에의 글로벌 포인터가 초기화된다.

LPDIRECTINPUTDEVICE7  g_lpdid7 = NULL;

lpdi->EnumDevices(DIDEVTYPE_JOYSTICK,
                  DIEnumDevicesProc,
                  NULL,
                  DIEDFL_FORCEFEEDBACK | DIEDFL_ATTACHEDONLY);
if (g_lpdid7 == NULL)
  {
  // force feedback 죠이스틱을 이용할 수 없다. 적절한 처리를 취한다.
  }

이 예에서는,lpdi 는 IDirectInput7 인터페이스에의 초기화가 끝난 포인터이다. EnumDevices 의 제 1 파라미터에 의해, 열거 대상이 죠이스틱류의 디바이스로 한정된다. 제 2 파라미터는, DirectInput 를 열거할 수 있는 디바이스를 식별할 때마다 불려 가는 콜백 함수이다. 제 3 파라미터는, 콜백 함수에게 건네진다, 또는 콜백 함수로부터 건네받는 유저 정의 데이터를 나타낸다. 이 예에서는 사용되어 있지 않다. 마지막으로, 제 4 파라미터의 플래그에 의해, 열거 대상이, force feedback를 지원 하는 시스템에 실제로 Attach 되고 있는 디바이스로 한정된다.

콜백 함수는, 디바이스가 발견되자마자 그 디바이스를 초기화하는데 편리하다 (최초로 발견되었던 것이 사용하고 싶은 디바이스인 것을 전제로 하고 있다). 이 처리는, 「스텝 2 : DirectInput force feedback 디바이스의 생성」으로 실시하게 된다.


스텝 2 : DirectInput force feedback 디바이스의 생성

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

DirectInput 에 디바이스를 열거시키려면 ,DIEnumDevicesCallback 와 동종의 콜백 함수를 생성 해야 한다. 스텝 1 에서는, 이 함수의 주소를 IDirectInput7::EnumDevices 메소드에 건네주고 있다.

DirectInput 는, 알 필요가 있는 디바이스에 대한 정보를 통지하는 DIDEVICEINSTANCE 구조체에의 포인터를, 제 1 파라미터로서 콜백 함수에 건네준다. 다음의 예로 가장 중요한 구조체 멤버는 guidInstance 이며, 이것은, 유저의 시스템으로 특정의 하드웨어를 식별하는 유일한 수단이다. 이 GUID 는, 다음에 IDirectInput7::CreateDeviceEx 메소드에 건네주지 않으면 안 된다.

다음에 나타내는 것은, 콜백 함수의 최초의 부분이며, GUID 를 꺼내 디바이스 오브젝트를 생성 한다.

BOOL CALLBACK DIEnumDevicesProc(LPCDIDEVICEINSTANCE lpddi,
                                LPVOID pvRef)
  {
  HRESULT hr;
  GUID DeviceGuid = lpddi->guidInstance;

  // 게임 디바이스를 생성한다.

  hr = lpdi->CreateDeviceEx(DeviceGuid, IID_IDirectInputDevice7,
          (void**) &g_lpdid7, NULL);

  if (FAILED(hr))
    {
    OutputDebugString("디바이스의 생성에 실패했습니다. \n");
    return DIENUM_STOP;
    }

다음의 순서는, 아직 콜백 함수 중(안)에서 있지만, 입력 디바이스의 셋업 처리에 유사하고 있다. 주의 해야 할 것은, 어느 force feedback 디바이스에 있어서도 배타 협조 레벨이 필요하다라고 말하는 것이다. 또, 데이터 형식을 설정할 필요도 있다.

  // 협조 레벨의 설정
  if (FAILED(g_lpdid7->SetCooperativeLevel(hMainWindow,
         DISCL_EXCLUSIVE | DISCL_FOREGROUND)))
    {
    OutputDebugString(
      "협조 레벨의 설정에 실패했습니다. \n");
    g_lpdid7->Release();
    g_lpdid7 = NULL;
    return DIENUM_STOP;
    }

  // 게임 데이터 형식의 설정
  if (FAILED(g_lpdid7->SetDataFormat(&c_dfDIJoystick)))
    {
    OutputDebugString("게임 디바이스 데이터 형식의 설정에 실패했습니다. \n");
    g_lpdid7->Release();
    g_lpdid7 = NULL;
    return DIENUM_STOP;
    }

마지막으로, 디바이스의 자동 센터링 기능을 오프로 하고 싶은 경우에 접한다. 기본적으로 자동 센터링 기능은, 모터를 사용해 표준 죠이스틱으로 스프링을 시뮬레이트 하는 조건 이펙트이다. 이 기능을 오프로 하면(자), 다른 이펙트가 방해되지 않게 된다.

  DIPROPDWORD DIPropAutoCenter;

  DIPropAutoCenter.diph.dwSize = sizeof(DIPropAutoCenter);
  DIPropAutoCenter.diph.dwHeaderSize = sizeof(DIPROPHEADER);
  DIPropAutoCenter.diph.dwObj = 0;
  DIPropAutoCenter.diph.dwHow = DIPH_DEVICE;
  DIPropAutoCenter.dwData = 0;

  if (FAILED(lpdid7->SetProperty(DIPROP_AUTOCENTER,
          &DIPropAutoCenter.diph)))
    {
    OutputDebugString("Failed to change device property. \n");
    }

  return DIENUM_STOP;   // 1 개(살)로 충분히.
  } // DIEnumDevicesProc 의 종료.

사용전에, 디바이스를 취득해야 한다. 취득 방법의 예에 대해서는, 튜토리얼 3 의 「스텝 5 : 죠이스틱에의 액세스권의 취득」을 참조할것.

다음 방향 : 스텝 3 : 지원 된 이펙트의 열거


스텝 3 : 지원 된 이펙트의 열거

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

지금까지 force feedback 디바이스의 열거와 생성에 성공했으므로, 그 디바이스가 지원 하는 이펙트의 타입을 열거할 수가 있다.

어느 디바이스에서도 이용 가능한 표준적 이펙트만을 생성하고 싶은 경우는, 이펙트의 열거는 반드시 필요하지 않다. 이펙트 오브젝트를 생성 하면 와, GUID_ConstantForce 등의 정의가 끝난 GUID 중 어떤 것이나 1 개를 사용해, 목적의 이펙트 타입을 간단하게 식별할 수가 있다. 이러한 식별자의 전리스트에 대해서는, 「IDirectInputDevice7::CreateEffect 」를 참조할것.

좀 더 유연성이 있는 방법은, 특정 타입의 지원 되는 이펙트를 열거해, 콜백 함수로부터 이펙트에 대한 GUID 를 취득하는 것이다. FFDonuts 샘플에서는, 이 방법이 사용되고 있다. 여기에서도 그 샘플 어플리케이션을 응용하기로 한다. 물론, 콜백 함수를 사용해, 이펙트에 대한 디바이스의 지원에 대한 상세 정보 (예를 들어, 디바이스가엔벌로프를 지원 하고 있을지 어떨지에 임해서)를 얻을 수도 있지만, 이 튜토리얼에서는 이펙트 GUID 만을 취득하기로 한다.

우선, 열거된 이펙트 각각 붙어 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 를 취득하기 위해서, 다음과 같이 IDirectInputDevice7::EnumEffects 메소드를 호출해, 콜백을 스타트 시킨다.

HRESULT  hr;
GUID     guidEffect;

hr = g_lpdid7->EnumEffects(
     (LPDIENUMEFFECTSCALLBACK) DIEnumEffectsProc,
     &guidEffect,
     DIEFT_PERIODIC);
if (FAILED(hr))
  {
  OutputDebugString("이펙트의 열거에 실패했습니다. \n");
  // 주의 : 성공했다고 해도, 어떤 것인가의 이펙트가 발견되었다고 하는 것을 의미하는 것은 아니고,
  // 단지 처리가 순조롭게 행해진 것을 의미한다.
  }

GUID 변수의 주소 guidEffect 를 EnumEffects 메소드에 건네주는 것에 주의 해야 한다. 이 주소는, 콜백 함수에 pv 파라미터로서 건네받는다. 게다가 DIEFT_PERIODIC 플래그를 설정해, 열거 대상을 주기적 이펙트로 한정한다.

다음 방향 : 스텝 4 : 이펙트의 생성


스텝 4 : 이펙트의 생성

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

이펙트의 열거 후 EffectFound 의 값이 FALSE 가 아니면, 필요한 이펙트 타입의 적어도 1 개(살)에 대한 지원을 DirectInput 가 발견했다고 간주라고 좋다 (물론, 실제로는, 불특정인 주기적 이펙트를 발견한 것 만으로는 만족할 수 없을 것이다. 싸인이나 톱니등의 특정의 이펙트를 사용하고 싶을까들 ). 이펙트 GUID 가 갖춰지고 있으므로, 이번은 이펙트 오브젝트를 생성할 수가 있다.

IDirectInputDevice7::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 초주기의 전력 주기적 이펙트를 생성하게 된다.

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;

셋업은 여기까지. 겨우 이펙트를 생성할 수 있다.

LPDIEFFECT  g_lpdiEffect;  // 글로벌 이펙트 오브젝트

HRESULT hr = g_lpdid7->CreateEffect(
                 guidEffect,     // 열거로부터의 GUID
                 &diEffect,      // 데이터의 장소
                 &g_lpdiEffect,  // 인터페이스 포인터를 두는 장소
                 NULL);          // 집합화 없음
if (FAILED(hr))
  {
  OutputDebugString("주기적 이펙트의 생성에 실패했습니다. ");
  }

디바이스가 배타 협조 레벨로 취득된 상태에 있으면, 디폴트에서는, 이 이펙트는 생성되는 것과 동시에 디바이스에 다운로드되는 것을 기억해 두는 것. 모든 것이 계획대로에 진행되면, 컴파일 해, 실행할 수가 있을 것이다. 발사 버튼을 누르면, 가스결의 chain saw가 세우는 격렬한 소리를 들을 수가 있을 것이다.

다음 방향 : 스텝 5 : 이펙트의 재생


스텝 5 : 이펙트의 재생

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

전의 스텝에서 생성한 이펙트는 버튼 압하에 응답해 시동한다. 명시적인 호출해에 응답해 재생하는 이펙트를 생성하려면 , 스텝 4 에 돌아와,DIEFFECT 구조체의 멤버 dwTriggerButton 를 다음과 같이 변경할 필요가 있다.

diEffect.dwTriggerButton = DIEB_NOTRIGGER;

여기서, 실제로 시동해, 계속 움직이는 chain saw를 만드는 것을 생각한다. dwDuration 멤버를 다음과 같이 변경하는 것만으로 좋다.

diEffect.dwDuration = INFINITE;

이 이펙트를 시동하는 것은 매우 간단하다.

g_lpdiEffect->Start(1, 0);

이 이펙트는 다음과 같이 해 멈출 때까지 계속 일한다.

g_lpdiEffect->Stop();

주의하기를 원하는 것은, 전의 스텝에서 생성한엔벌로프를 변경할 필요가 없는 것이다. 어택은 이펙트가 시동 하면 재생하지만,페이드값은 무시된다.

다음 방향 : 스텝 6 : 이펙트의 변경


스텝 6 : 이펙트의 변경

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 튜토리얼」을 참조할것.

[C++]

chain saw는 쾌활하게 덜컹덜컹소리를 내고 있다. 이 chain saw가 목재에 돌진할 때에 엔진이 감속하는 시뮬레이션을 하기 위해서, 이 이펙트를 변경하고 싶다고 한다. 다행히, DirectInput 에서는 재생중의 이펙트의 파라미터를 변경할 수가 있다.

이 이펙트를 변경하려면 ,DIEFFECT 구조체의 셋업, 또는 이 이펙트의 생성에 사용한 구조체에의 액세스가 필요하다. 유효한 새로운 구조체를 로컬에 셋업 하는 경우는,dwSize 멤버라고 변경하는 데이터를 포함한 또는 그 데이터를 가리키는 멤버만을 초기화하면 좋다.

이 예에서는, 타입 고유 파라미터 (이펙트의 주기)를 변경하려고 하고 있으므로, 이펙트를 생성할 경우에 사용한 DIPERIODIC 구조체에의 액세스가 필요하다. 이 구조체의 로컬 카피를 만들어, 모든 멤버를 초기화해도 괜찮다. DIPERIODIC 구조체의 주소가 DIEFFECT 구조체의 멤버 lpvTypeSpecificParams 에 저장 되고 있는 것을 확인한다.

이펙트의 새로운 주기를 설정한다.

diPeriodic.dwPeriod = (DWORD) (0.08 * DI_SECONDS);

그 후, 실제로 변경을 실시하는 메소드를 호출한다.

HRESULT hr = g_lpdiEffect->SetParameters(&diEffect,
                           DIEP_TYPESPECIFICPARAMS)

이 변경을 DIEFFECT 구조체의 1 개의 멤버로 한정하고 있는 플래그에 주의 해야 한다.

다른 플래그를 사용해, 변경의 방법을 제어할 수가 있다. 예를 들어, DIEP_NODOWNLOAD 플래그를 사용하면, 이펙트의 시동 직후로 파라미터를 변경해, 게다가, 유저가 실제로 목재를 자르기 시작할 때까지, 새로운 이펙트의 실행을 늦출 수가 있을 것이다. 그 후,IDirectInputEffect::Download 메소드를 호출하게 될 것이다. 다양한 제어 플래그의 사용 방법에 대해서는,IDirectInputEffect::SetParameters 를 참조할것.


DirectInput Visual Basic 튜토리얼

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

여기에서는, 다음의 튜토리얼을 사용해, Visual Basic 어플리케이션에 DirectInput 를 이행 하는 방법을 스텝바이스텝으로 설명한다.

  • 튜토리얼 1 : 키보드의 사용

    최초의 튜토리얼은, 이벤트 폴링을 사용해, 기존의 어플리케이션에 DirectInput 키보드 지원을 추가하는 순서를 나타낸다.

  • 튜토리얼 2 : 마우스의 사용

    2 번째의 튜토리얼은, 배타 협조 레벨과 이벤트 통지를 사용해, 어플리케이션으로 DirectInput 마우스 지원을 실현하는 순서를 나타낸다. 이 튜토리얼은,ScrawlB 샘플을 기본으로 하고 있어, 버퍼링 데이터에 초점을 맞힌다.

  • 튜토리얼 3 : 죠이스틱의 사용

    이 튜토리얼은, 시스템에 접속되고 있는 죠이스틱을 모두 열거하는 방법, 콜백 함수로 각 죠이스틱에 대한 DirectInput 디바이스 오브젝트를 생성 해 초기화하는 방법, 및 직접 데이터를 취득하는 방법을 나타낸다.

  • 튜토리얼 4 : force feedback의 사용

    마지막 튜토리얼에서는, 어플리케이션에 단순한 force feedback 이펙트를 이행 하는 방법을 나타낸다.


튜토리얼 1 : 키보드의 사용

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

키보드 입력의 준비를 실시하려면 , 우선,DirectInput 오브젝트를 생성 한다. 다음에, 키보드를 나타내는 DirectInputDevice 오브젝트를 생성 한다. 디바이스의 동작을 설정하거나 데이터를 취득하거나 하려면 ,DirectInputDevice 클래스의 메소드를 사용한다.

이 튜토리얼에서는, 필요한 태스크를 이하의 순서에 분할하고 있다.

  • 스텝 1 : DirectInput 와 키보드 디바이스의 생성
  • 스텝 2 : 키보드 파라미터의 설정
  • 스텝 3 : 키보드의 액세스권의 취득
  • 스텝 4 : 키보드로부터의 직접 데이터의 취득


스텝 1 : DirectInput 와 키보드 디바이스의 생성

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

DirectInput 시스템의 셋업 순서의 처음은, 전체의 매니저로서 단일의 DirectInput 오브젝트를 생성 하는 것이다. 이것은,DirectX7.DirectInputCreate 메소드를 호출하는 것으로 실현된다. 이 메소드는 보통, 메인 폼의 Load 이벤트인가,Sub Main 중(안)에서 다음과 같이 호출한다.

Dim dx As New DirectX7
Dim di As DirectInput

Set di = dx.DirectInputCreate()

다음에,DirectInput.CreateDevice 에 키보드 GUID 를 건네주어, 키보드를 표준 디바이스로서 생성 한다.

Dim didev As DirectInputDevice
Set didev = di.CreateDevice("GUID_SysKeyboard")

다음 방향 : 스텝 2 : 키보드 파라미터의 설정


스텝 2 : 키보드 파라미터의 설정

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

DirectInputDevice 를 생성 하면(자), 디바이스의 데이터 형식을 설정해야 한다. 키보드의 경우는, 그 외의 표준 디바이스와 같게, 매우 간단한 태스크이다. DirectInputDevice.SetCommonDataFormat 메소드를 호출한다. 파라미터로서 DIFORMAT_KEYBOARD 를 건네주는 것으로, 편의상 DirectInput 로 준비된 데이터 형식을 지정한다.

Call didev.SetCommonDataFormat(DIFORMAT_KEYBOARD)

버퍼링 데이터를 취득하는 경우여도, 데이터 형식을 설정해야 한다. DirectInput 에서는, 데이터 형식내의 오프셋(offset)로 디바이스 오브젝트를 식별한다. 키보드의 경우, 키는 DIKEYBOARDSTATE 형내의 오프셋(offset)로 식별된다.

어플리케이션은, 키보드에의 액세스권을 취득하기 전에, 다음과 같이 DirectInputDevice.SetCooperativeLevel 메소드를 사용해 디바이스의 동작을 설정해야 한다.

didev.SetCooperativeLevel Me.hWnd, _
        DISCL_NONEXCLUSIVE Or DISCL_BACKGROUND

이 메소드는, 디바이스에 관련지을 수 있었던 윈도우의 핸들과 필요한 협조 레벨을 나타내는 2 개의 플래그 (DISCL_EXCLUSIVE 와 DISCL_NONEXCLUSIVE 의 언젠가, 및 DISCL_FOREGROUND 와 DISCL_BACKGROUND 의 어느쪽이든)를 받는다. DirectInput 는, 키보드 디바이스에 대한 배타 액세스권을 지원 하고 있지 않기 때문에, 이 경우는 DISCL_NONEXCLUSIVE 플래그를 지정해야 한다.

또, 이 예에서는 백그라운드 협조 레벨을 설정해, 폼이 foreground에 있을지 어떨지에 관계없이 입력을 받아들이도록(듯이) 하고 있다. 키스트로크(keystroke)는 계속해, 포커스를 가지는 어플리케이션에게 건네지는 것에 주의 해야 한다. 대부분의 어플리케이션은 백그라운드에 있는 동안에 입력을 받아들일 필요는 없다. 또, 그러한 경우에는, DISCL_FOREGROUND 플래그를 설정해야 하는 것이다.

다음 방향 : 스텝 3 : 키보드의 액세스권의 취득


스텝 3 : 키보드의 액세스권의 취득

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

키보드의 동작을 설정 끝마치면(자),DirectInputDevice.Acquire 메소드를 호출하는 것으로 디바이스에의 액세스권을 취득할 수 있다. 어플리케이션은, 디바이스로부터 데이터를 취득하기 전에, 디바이스를 취득해야 한다. Acquire 메소드는 파라미터를 취하지 않는다.

Call didev.Acquire

샘플 코드에서는, 어플리케이션은 백그라운드의 비배타 협조 레벨을 사용하고 있으므로, 키보드의 취득에 실패하거나 다음에 액세스를 상실하거나 할 가능성은 없다. 다만 보통은,Acquire 를 호출하는 경우도, 데이터를 취득하려고 할 때와 같게, 에러 처리를 실시하는 것이 바람직하다.

다음 방향 : 스텝 4 : 키보드로부터의 직접 데이터의 취득


스텝 4 : 키보드로부터의 직접 데이터의 취득

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

디바이스를 취득하면, 어플리케이션은, 디바이스로부터의 데이터의 취득을 시작 할 수 있다. 이것을 가장 간단하게 실시하는 방법은,DirectInputDevice.GetDeviceStateKeyboard 메소드를 호출하는 것이다. 이 메소드는, 호출시의 그 순간의 디바이스 상태를 취득한다.

GetDeviceStateKeyboard 메소드는, 단일의 파라미터로서 DIKEYBOARDSTATE 형을 받는다. 이 파라미터는 단지, 256 바이트의 배열을 포함하고 있다.

이하의 코드는, 키보드 상태를 취득하는 예이다.

Dim state As DIKEYBOARDSTATE
Call didev.GetDeviceStateKeyboard(state)

키보드의 현재 상태를 취득한 후, 어플리케이션은, 호출시에 밀린 특정의 키에 응답할 수가 있다. 버퍼중의 각 요소가 1 개의 키를 나타낸다. 요소의 상위 비트가 온의 경우, 그 키는, 호출시에 밀리고 있던 것을 나타낸다. 그 이외의 경우는, 키는 밀리지 않았다. 어느 키 상태를 체크하려면 ,CONST_DIKEYFLAGS 열거의 정수를 사용해, 그 키에 대한 버퍼의 인덱스를 생성 한다.

다음의 샘플 코드에서는, 어플리케이션이 커서 키에 응답해 차를 이동하는 방법을 나타낸다.

If state.Key(DIK_UP) And &H80 Then
  '차를 윗방향으로 이동한다.
End If
if state.Key(DIK_DOWN) And &H80 Then
  '차를 아래방향으로 이동한다.
End If
'이하 같이.

다음의 코드도 똑같이 동작한다.

If state.Key(DIK_UP)
  ' Move the vehicle up
End If

DirectInput 의 현재의 버젼에 있어서의 모든 버튼과 같게, 키가 업이면, 키 상태를 나타내는 값은 제로이다. 다만, 장래의 버젼에서는, 복수 상태를 가져, 제로 이외의 값을 복수 가지는 "아날로그" 키가 지원 될 가능성이 있다. 이 때문에, 특히 키보드 이외의 디바이스를 취급하는 경우, 후자의 코드는 신중하게 사용해야 한다.

또, DIK_UP 는 전용의 방향 키이며, 오름새 화살표를 나타내는 단일의 키인 것에 주의. DirectInput 에서는, 숫자 패드 위에의 8 개의 키를 특이 키로서 취급해, NUM LOCK 가 유효한가 어떤가에 관계없이, 동일한 식별자가 부여된다. 커서 키의 어느쪽이든으로부터 입력을 받도록(듯이) 하려면 , 다음과 같은 코드를 기술할 필요가 있다.

If state.Key(DIK_UP) Or state.Key(DIK_NUMPAD8) Then
  '차를 윗방향으로 이동한다.
End If


튜토리얼 2 : 마우스의 사용

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

이 튜토리얼에서는, 마우스를 배타 협조 레벨로 사용해, 통지에 응답해 버퍼링 데이터를 취득하는 방법을 나타낸다. 샘플 코드는,ScrawlB 샘플을 기본으로 하고 있다.

이 튜토리얼은, 다음의 스텝으로 구성되어 있다.

  • 스텝 1 : 마우스의 설정
  • 스텝 2 : 통지의 설정
  • 스텝 3 : 마우스의 배타 액세스권의 관리
  • 스텝 4 : 마우스로부터의 버퍼링 데이터의 취득


스텝 1 : 마우스의 설정

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

DirectInput 로 마우스를 사용하기 위한 셋업에 있어서의 최초의 순서는, 「튜토리얼 1 : 키보드의 사용」으로 실행한 순서와 거의 같다. ScrawlB 샘플에서는,Sub Main 로 몇개의 글로벌 변수를 선언하고 나서, 다음과 같이 초기화를 실시한다.

Public objDX As New DirectX7
Public objDI As DirectInput
.
.
.
Set objDIDev = objDI.CreateDevice("guid_SysMouse")
Call objDIDev.SetCommonDataFormat(DIFORMAT_MOUSE)
Call objDIDev.SetCooperativeLevel(frmCanvas.hwnd, _
        DISCL_FOREGROUND Or DISCL_EXCLUSIVE)

여기서, 디바이스는 배타 컨트롤을 얻는다. 그 결과, 어플리케이션이 마우스를 취득한 상태에 있는 한, Windows 는 마우스 메세지를 생성하거나 시스템 커서를 표시하거나 하지 않는다. DISCL_EXCLUSIVE 는 DISCL_FOREGROUND 와 조합하지 않으면 안 된다. 왜냐하면, 어플리케이션이 포커스를 잃었을 경우, 마우스에의 배타 액세스를 가지지 못하고, 데이터를 취득하는 일도 할 수 없기 때문에이다.

ScrawlB 샘플 어플리케이션은 마우스에 대한 전책무를 계승하므로, 전용 커서의 위치를 추적하거나 마우스의 움직임에 맞추어 커서의 이동을 스케일링 하거나 해야 한다. 다음의 글로벌 변수는, 커서 좌표 (메인 폼의 좌상구석으로부터의 상대 픽셀수)와 이동 스케일링의 저장에 사용한다.

Public g_cursorx As Long
Public g_cursory As Long
Public g_Sensitivity

Sub Main 에 돌아와, 버퍼링 데이터를 받을 수가 있도록(듯이),DirectInputDevice.SetProperty 메소드를 사용해 버퍼 사이즈를 설정한다.

Dim diProp As DIPROPLONG
diProp.lHow = DIPH_DEVICE
diProp.lObj = 0
diProp.lData = BufferSize    ' BufferSize 는 정수
diProp.lSize = Len(diProp)
Call objDIDev.SetProperty("DIPROP_BUFFERSIZE", diProp)

다음 방향 : 스텝 2 : 통지의 설정


스텝 2 : 통지의 설정

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

ScrawlB 샘플 어플리케이션은,Sub Main 로 마우스 입력을 폴링 하는 것이 아니라, 마우스 이벤트가 발생했을 때에 반드시 마우스 입력을 통지하도록, DirectInput 에 의존한다. 어플리케이션은 초기화 처리중에 이벤트 핸들을 취득해, 그 핸들을 DirectInputDevice.SetEventNotification 에 건네준다.

Dim EventHandle As Long
EventHandle = objDX.CreateEvent(frmCanvas)
Call objDIDev.SetEventNotification(EventHandle)

이것에 의해, DirectInput 는 DirectXEvent 클래스를 이행 하는 모든 오브젝트를 통지한다. ScrawlB 의 경우, 이행 하는 오브젝트는 frmCanvas 폼이며, 그 선언 섹션에는 다음의 행이 포함된다.

Implements DirectXEvent

이 행에 의해,frmCanvas 는 DirectXEvent 클래스의 메소드를 계승한다. 이 행이 실행되면(자), 그 클래스의 가시 메소드는 DirectXEvent.DXCallback 뿐여, 계승한 클래스는 이 메소드를 이행 해야 한다. 입력 이벤트가 발생 하면 반드시 DirectInput 는 이 메소드를 호출하게 된다.

DXCallback 의 이행 방법에 대해서는 「스텝 4 : 마우스로부터의 버퍼링 데이터의 취득」으로 설명한다.

다음 방향 : 스텝 3 : 마우스의 배타 액세스권의 관리


스텝 3 : 마우스의 배타 액세스권의 관리

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

ScrawlB 샘플에서는, 배타 foreground 협조 레벨로 마우스를 사용하는 방법을 나타낸다. 이 레벨에서는, 마우스가 어플리케이션에 취득되고 있는 동안, Windows 는 마우스를 추적하지 않는다. 그 경우, 어플리케이션에는 주로, 다음의 3 개의 중요한 역할이 있다.

  • 커서가 필요한 경우는 커서를 표시해, DirectInput 데이터에 응답해 적절한 속도로 커서를 이동해야 한다.
  • 유저가 키보드를 사용해 다른 어플리케이션으로 전환하면(자) 취득은 없어진다. 유저가 이 어플리케이션에 되돌렸을 때에, 마우스를 재취득해야 한다.
  • 어플리케이션내의 메뉴를 조작하는 등, 유저가 시스템 커서를 사용하고 싶을 때에, Windows 가 마우스를 취득할 수 있는 수단을 제공해야 한다.

ScrawlB 는, 유저 정의의 감도값에 의해 조정된 마우스 이동의 전용 레코드를 보관 유지해, 드로잉(Drawing)용 커서로서 기능하는 아이콘을 표시하는 것으로, 제 1 의 역할을 처리한다.

ScrawlB 는, 어플리케이션 윈도우가 백그라운드로 이행하면(자), 반드시 마우스는 릴리즈 된다. 어플리케이션이 foreground에 돌아오면(자), 어플리케이션은 MouseMove 이벤트 핸들러 중(안)에서 DirectInputDevice.Acquire 를 호출하는 것으로, 마우스를 자동적으로 재취득한다. 이 핸들러는, Windows 가 마우스 메세지를 어플리케이션에 송신할 경우에 불려 간다. 이 처리는, 시스템 커서가 클라이언트 윈도우상으로 이동하는지, 클라이언트 윈도우가 시스템 커서아래의 포커스를 취득 하면, 발생한다. ScrawlB 가 마우스를 재취득한 후는, 당연히 Windows 마우스 메세지는 송신되지 않기 때문에, 이 이후의 마우스 이벤트에 응답해 Form_MouseMove 메소드가 불려 갈 것은 없다.

유저가 context menu를 조작하거나 또는 윈도우의 사이즈를 변경하는 등, 다른 목적을 위해서(때문에) 시스템 커서를 표시하거나 할 수 있도록(듯이), 유저가 메뉴를 표시 하면, ScrawlB 는 DirectInputDevice.Unacquire 메소드를 호출한다. 메뉴가 닫혀지면(자),Form_MouseMove 가 불려 가 마우스가 재취득된다. 다만, 유저가 메뉴로부터 [Suspend] 를 선택하는 경우를 제외하다. 이 경우는 플래그가 설정된다. 이 플래그는,Form_MouseMove 에 의한 마우스의 재취득을 방해하므로, 유저는 시스템 커서를 계속해 사용할 수 있다.

샘플 어플리케이션에서는, 마우스를 릴리즈 하는 복수의 방법을 나타내고 있다. 유저가 Alt 키를 누르면서 스페이스 키를 눌러, 시스템 메뉴를 표시하는 경우, Windows 는 WM_ENTERMENULOOP 메세지를 송신한다. 이 메세지는, 서브 클래스화 된 윈도우 프로시저에 의해 인터셉트 되므로, 마우스는 취득되지 않는다. 메뉴를 조작하기 위해(때문에)나 유저가 윈도우의 사이즈를 변경하기 위해서 Windows 가 시스템 커서를 사용하고 있는 한, Windows 는 frmCanvas 에 대해서 마우스 메세지를 송신하지 않는다. 따라서, 어플리케이션은 Form_MouseMove 로 마우스를 재취득하려고는 하지 않는다. WM_ACTIVATE 이나 WM_ACTIVATEAPP 등, 다른 Windows 메세지를 감청할 때에도 같은 방법이 사용된다. 이것에 의해 어플리케이션은, 포커스의 취득과 상실에 응답해, 마우스의 취득과 릴리즈를 완전하게 제어할 수 있다.

다음 방향 : 스텝 4 : 마우스로부터의 버퍼링 데이터의 취득


스텝 4 : 마우스로부터의 버퍼링 데이터의 취득

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

ScrawlB 샘플은,frmCanvas 에 의해 이행 되는 DirectXEvent.DXCallback 메소드 내부에서, 마우스의 버퍼링 데이터를 취득한다. 입력 이벤트가 발생 하면 반드시 이 메소드가 불려 간다.

이 메소드는, DirectInput 가 데이터의 저장에 사용하는 버퍼와 같은 사이즈의 버퍼를 선언한다. 이것은, 이전의 DirectInputDevice.SetProperty 의 호출에 의해 설정된 사이즈이다.

Dim diDeviceData(1 To BufferSize) As DIDEVICEOBJECTDATA

또, 실제로 취득된 항목수를 받는 변수, 루프 카운터, 및 이벤트의 전회의 순서 번호를 추적하는 변수도 필요하다.

Dim NumItems As Integer
Dim i As Integer
Static OldSequence As Long

이 시점에서 어플리케이션은,DirectInputDevice.GetDeviceData 를 한 번 호출하는 것으로, 이용 가능한 데이터를 모두 취득한다.

On Error GoTo INPUTLOST
NumItems = objDIDev.GetDeviceData(diDeviceData, 0)
On Error GoTo 0

에러 트랩에 주의하면 좋겠다. DirectInput 가 송신하는 이벤트의 1 개는, 취득의 상실이다. 예를 들어, 유저가 다른 어플리케이션으로 전환했을 경우, ScrawlB 는 마우스를 취득한 상태에는 없다. 이벤트가 송신되어 이 메소드가 불려 가도,GetDeviceData 는 실패한다. 데이터는, 취득 상태에 있는 디바이스로부터 밖에 취득할 수 없기 때문이다.

여기서 어플리케이션은, 취득한 항목을 반복해,DIDEVICEOBJECTDATA 형내의 데이터를 조사해lOfs 멤버와 목적의 다양한 버튼과 축을 나타내는 정수를 비교한다. 예를 들어 x 축의 경우, 어플리케이션은 lData 멤버로부터 축위치의 변화량을 취득해, 유저 정의의 감도를 계산하면서, 이것을 사용해 커서 위치를 조정한다.

For i = 1 To NumItems
    Select Case diDeviceData(i). lOfs
        Case DIMOFS_X
           g_cursorx = g_cursorx + diDeviceData(i). lData * _
               g_Sensitivity

또, 어플리케이션은 순서 번호를 조사해, 전회의 번호와 비교한다. 2 개의 축이벤트가 같은 순서 번호를 가지는 경우, 마우스는 비스듬하게 이동하고 있어, 2 개의 이동을 계산 끝마칠 때까지는, 커서 위치를 갱신하거나 선을 드로잉(Drawing) 하거나 해서는 안된다.

           If OldSequence <> diDeviceData(i). lSequence Then
             UpdateCursor  '커서를 이동해, 직선을 드로잉(Drawing) 한다.
             OldSequence = diDeviceData(i). lSequence
           Else
             OldSequence = 0
           End If

버튼의 경우, 메소드는,lData 내의 적절한 비트를 체크해, 이벤트의 종류를 결정한다. 비트가 설정되어 있는 경우, mouse button는 밀리고 있다. 그 이외의 경우, mouse button는 밀리지 않았다. GetDeviceData 는 디바이스의 현재 상태를 돌려주는 것은 아니기 때문에, 버튼이 눌러 내릴 수 있고 있는지 어떤지의 전용 기록을 보관 유지하는 것은, 어플리케이션이 실시하지 않으면 안 된다. 왼쪽 버튼의 경우, ScrawlB 는 이 정보를 Drawing 불형 변수 로 유지한다.

         Case DIMOFS_BUTTON0
           If diDeviceData(i). lData And &H80 Then
             Drawing = True

             ' Line 함수의 기록을 보관 유지한다.
             CurrentX = g_cursorx
             CurrentY = g_cursory

             '직후에 버튼 업이 발생했을 경우는, 점을 드로잉(Drawing) 한다.
             PSet (g_cursorx, g_cursory)
           Else
             Drawing = False
           End If
.
.
.
    End Select
Next i


튜토리얼 3 : 죠이스틱의 사용

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

이 튜토리얼에서는, 죠이스틱 디바이스의 생성 방법, 죠이스틱의 프로퍼티의 설정 방법법, 및 직접 데이터의 취득 방법을 나타낸다. 이 예는,Joystick 샘플을 기본으로 하고 있다.

이 튜토리얼에서는, 필요한 태스크를 이하의 순서에 분할하고 있다.

  • 스텝 1 : 죠이스틱의 열거와 생성
  • 스텝 2 : 죠이스틱 능력의 취득
  • 스텝 3 : 죠이스틱 프로퍼티의 설정
  • 스텝 4 : 죠이스틱으로부터의 직접 데이터의 취득


스텝 1 : 죠이스틱의 열거와 생성

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

시스템키 보드나 시스템 마우스가 있다고 하는 것으로 같은 의미에서의, 시스템 죠이스틱이라는 것은 없기 때문에, 죠이스틱의 DirectInputDevice 오브젝트를 생성 하려면 , 우선 인스턴스 GUID (글로벌 유니크 식별자)를 취득할 필요가 있다. 보통, 이것은 이용 가능한 죠이스틱을 열거해, 유저에게 선택사항을 제시해, 선택된 디바이스의 정보를 취득하는 것으로써 실현된다.

다음의 함수는, DirectInput 를 초기화해, Attach 되고 있는 죠이스틱을 열거한다.

Dim dx As New DirectX7
Dim di As DirectInput
Dim diDev As DirectInputDevice
Dim diDevEnum As DirectInputEnumDevices

Sub InitDirectInput()
    On Error GoTo Error_Out

    Set di = dx.DirectInputCreate()
    Set diDevEnum = di.GetDIEnumDevices( _
            DIDEVTYPE_JOYSTICK, DIEDFL_ATTACHEDONLY)
    If diDevEnum.GetCount = 0 Then
        MsgBox "No joystick attached. "
        Unload Me
    End If

    'Attach 되고 있는 죠이스틱을 리스트 박스에 추가한다.
    Dim i As Integer
    For i = 1 To diDevEnum.GetCount
        Call lstJoySticks.AddItem( _
                diDevEnum.GetItem(i). GetInstanceName)
    Next

    '이벤트 핸들을 취득해, 디바이스에 관련짓는다.
    EventHandle = dx.CreateEvent(Me)
    Exit Sub

Error_Out:
    MsgBox "Error initializing DirectInput. "
    Unload Me

End Sub

유저가 리스트로부터 죠이스틱을 선택 하면, 그 디바이스가 생성 되어 lstJoySticks_Click 프로시저내에서 초기화된다.

Set diDev = di.CreateDevice(diDevEnum.GetItem( _
        lstJoySticks.ListIndex + 1). GetGuidInstance)
diDev.SetCommonDataFormat DIFORMAT_JOYSTICK
diDev.SetCooperativeLevel Me.hWnd, _
        DISCL_FOREGROUND Or DISCL_NONEXCLUSIVE

DirectInput.CreateDevice 의 호출에서는, 열거로부터 취득된 DirectInputDeviceInstance 오브젝트의 GUID 를 파라미터로서 받는다. DirectX for Visual Basic 에 있어서의 모든 열거 콜렉션과 같게, 디바이스의 열거는 1 으로부터 시작 된다. 따라서, 인덱스는, 리스트 박스로 선택된 항목의 인덱스보다 1 개 커진다. 또, 리스트 박스는 소트 하지 않는다.

디바이스 위에의 오브젝트를 열거하려고 하거나 프로퍼티를 조작하려고 하거나 하기 전에, 데이터 형식을 설정할 필요가 있다.

다음 방향 : 스텝 2 : 죠이스틱 능력의 취득


스텝 2 : 죠이스틱 능력의 취득

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

디바이스 위에의 버튼, 축, 및 시점 콘트롤러에 대한 정보를 취득하려면 ,DirectInputDevice.GetCapabilities 를 호출하는 것만으로 좋다.

Dim joyCaps As DIDEVCAPS
Call diDev.GetCapabilities joyCaps

Joystick 샘플이 알 필요가 있는 것은, 디바이스 위에의 버튼과 시점 콘트롤러의 수뿐이다. DIDEVCAPS 형은, 디바이스 위에의축의 수도 보고하지만, 축 상태에 대해서는 일절 정보를 공개하지 않는다. 이 정보를 알기 위해서(때문에), 샘플은 IdentifyAxes 프로시저를 호출한다.

Sub IdentifyAxes(diDev As DirectInputDevice)

   Dim didoEnum As DirectInputEnumDeviceObjects
   Dim dido As DirectInputDeviceObjectInstance
   Dim i As Integer

   For i = 1 To 8
     AxisPresent(i) = False
   Next

몇개의 변수를 선언해,AxisPresent 배열 ( 각 축으로 대하는 불형 변수를 저장 한다)을 소거하고 나서, 프로시저는 모든 디바이스 오브젝트의 열거하러 진행된다.

   Set didoEnum = diDev.GetDeviceObjectsEnum(DIDFT_AXIS)

다음에,DirectInputDevice.SetCommonDataFormat 의 호출로 이전으로 설정된 데이터 형식 중(안)에서, 그 오프셋(offset) 마다 DirectInputDeviceObjectInstance 를 문의한다. 이 오프셋(offset)에 의해, 축의 종래의 역할이나 타입이 식별된다. 예를 들어, DIJOFS_RZ 축은, 메인 스틱의 스핀 동작에 대응하는 것을 알 수 있다. 다만, 디바이스 드라이버는, 축으로 대해 자유롭게 지시를 할당할 수가 있다. 유저가 어플리케이션내에서 축과 액션의 대응을 변경할 수 있도록(듯이) 해 두는 것은 좋은 아이디어이다.

    For i = 1 To didoEnum.GetCount
        Set dido = didoEnum.GetItem(i)
        Select Case dido.GetOfs
            Case DIJOFS_X
                AxisPresent(1) = True
            Case DIJOFS_Y
                AxisPresent(2) = True
'이하 같이.
.
.
.
        End Select
    Next
End Sub

다음에, 어플리케이션은, 이전에 생성 된 이벤트 핸들을 디바이스에 건네준다. 이것에 의해, 입력 이벤트가 발생 하면, 통지는 폼에 송신된다.

Call diDev.SetEventNotification(EventHandle)

다음 방향 : 스텝 3 : 죠이스틱 프로퍼티의 설정


스텝 3 : 죠이스틱 프로퍼티의 설정

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

프로퍼티의 변경은,DirectInputDevice.SetProperty 메소드를 사용해 실시한다. 이것은 디바이스의 확립 후, 한편 디바이스의 취득전에 실시하지 않으면 안 된다.

디바이스가 돌려주는 축의 범위의 값은 축 마다 차이가 나므로, 모든 디바이스에 적용되는 범위를 설정하는 것이 바람직하다. Joystick 샘플에서는, 모든 축의 값을 0 ~ 10,000 의 범위에 거두도록(듯이) 요구하고 있다.

Dim DiProp_Range As DIPROPRANGE

With DiProp_Range
    . lHow = DIPH_DEVICE  '모든 축으로 대해 설정한다.
    . lSize = Len(DiProp_Range)
    . lMin = 0
    . lMax = 10000
End With
diDev.SetProperty "DIPROP_RANGE", DiProp_Range

lSize 멤버내의 DIPROPRANGE 형의 길이를 지정해야 한다. 왜냐하면, 이 메소드는 다양한 형태의 파라미터를 처리할 수 있으므로, 할당하는 메모리의 양을 알 필요가 있기 때문이다. C++ 의 프로그래밍을 숙지하고 있는 경우는,Len(DIPROPRANGE) 가 유효하지 않은 것에도 주의 해야 한다. 이것은 제로를 돌려주기 때문이다.

Joystick 샘플에서는, 죠이스틱의 무효 존과 포화 존도 설정한다. 이 경우, 스롯톨이나 방향타등의 축으로 이러한 값을 설정하는 것은 바람직하지 않다. 따라서, 프로퍼티의 변경은 데이터 형식내의 오프셋(offset)로 식별되는 디바이스 오브젝트에 적용되는 것을 나타내도록(듯이), 프로퍼티 타입의 lHow 멤버가 설정되어lObj 멤버에는 그 오프셋(offset)값이 설정된다.

Dim DiProp_Dead As DIPROPLONG

With DiProp_Dead
    . lData = 1000
    . lObj = DIJOFS_X
    . lSize = Len(DiProp_Dead)
    . lHow = DIPH_BYOFFSET
' x 축의 설정.
    . lObj = DIJOFS_X
    diDev.SetProperty "DIPROP_DEADZONE", DiProp_Dead
' y 축의 설정.
    . lObj = DIJOFS_Y
    diDev.SetProperty "DIPROP_DEADZONE", DiProp_Dead
End With

lData 의 값은, 무효 존으로서 설정하는 이동 범위의 비율이며, 10,000 까지의 값으로 나타내진다. 샘플로 사용되는 1000 이라고 하는 값은, x 축과 y 축의 이동 범위중 중심의 10% 가 5000 으로서 보고되는 것을 지정하고 있다. 5000 은, 전의 스텝에서 설정한 범위의 중심을 나타내는 값이다.

주 : 무효 존과 포화값은, 디바이스에 의해 보고되는 값의 범위에 관계없이, 항상 10,000 까지의 값으로 나타내진다.

디바이스의 포화 존도 이와 같이 설정한다. 이 경우,lData 는 포화 존의 외측에 있는 최대의 이동 범위의 비율을 나타내므로, 9500 이다. 즉, 죠이스틱에 의해 돌려주어지는 미가공의 값의 상위 및 하위 5% 는, 디바이스로 설정된 최소 값 또는 최대치로서 보고된다 (이 경우, 0 또는 10,000).

다음 방향 : 스텝 4 : 죠이스틱으로부터의 직접 데이터의 취득


스텝 4 : 죠이스틱으로부터의 직접 데이터의 취득

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

이 시점에서, 필요한 프로퍼티는 설정되어 있어 디바이스는 취득 가능해, 데이터는 죠이스틱으로부터 수집 가능하다. Joystick 샘플에서는, 프로퍼티를 설정한 후의 루프내에서 디바이스를 폴링 하고 있다. 실제의 멀티미디어 어플리케이션에서는, 폴링은 메인의 게임 루프나 렌더링 루프내에서 행해진다.

diDev.Acquire

While DoEvents
    diDev.Poll
Wend

샘플 어플리케이션은, 실제로 디바이스를 폴링 할 때마다 직접 데이터를 취득하고 있는 것은 아니다. 불필요한 화면 갱신을 없애기 위해서(때문에), 폴링은 통지에 근거해 행해진다. 세치기를 생성하지 않는 디바이스에 의해 통지가 발행되고 있는 것을 보증하는 유일한 방법은,Poll 를 호출하는 것이다. 게임 디바이스 (HID 등)에 따라서는 폴링은 필요하지 않지만,DirectInputDevice.Poll 를 여분으로 호출하는 것은,Poll 를 호출하기 전에 디바이스의 플래그를 체크하는 것과 같게 효율적이다.

통지는 DirectXEvent.DXCallback 메소드의 이행내에서 보통 대로 처리된다. 이 프로시저가 불려 갈 때마다, 어플리케이션은 어떠한 죠이스틱 이벤트가 발생한 것을 인식한다. 이 시점에서,DirectInputDevice.GetDeviceData 를 호출해, 대기중의 축의 변화나 버튼 이벤트를 취득할 수도 있다. 다만, 게임 콘트롤러에서는, 디바이스 전체 상태를 취득하는 것이 보통이므로, 샘플에서는 DirectInputDevice.GetDeviceStateJoystick 를 사용하고 있다.

Dim js As DIJOYSTATE

diDev.GetDeviceStateJoystick js

여기서,DIJOYSTATE 형의 값은, 디바이스 오브젝트 상태에 관해서 어플리케이션이 알 필요가 있는 모든 정보를 나타내고 있다. 어플리케이션은 「스텝 2 : 죠이스틱 능력의 취득」으로, 어느 버튼, 축, 시점 콘트롤러가 실제로 존재할지를 알고 있으므로, 형태의 어느 멤버를 무시할지도 인식하고 있다.


튜토리얼 4 : force feedback의 사용

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

이 튜토리얼에서는, force feedback 디바이스가 존재할지 어떨지를 테스트하는 방법, 이펙트를 생성해 재생하는 방법, 및 이펙트의 재생중으로 파라미터를 변경하는 방법을 나타낸다.

이 튜토리얼에서는, 태스크를 이하의 순서에 분할하고 있다.

  • 스텝 1 : force feedback 디바이스의 초기화
  • 스텝 2 : 디바이스 프로퍼티의 설정
  • 스텝 3 : 이펙트의 생성
  • 스텝 4 : 이펙트의 변경


스텝 1 : force feedback 디바이스의 초기화

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

force feedback를 이행 하려면 , 우선, 적절한 디바이스가 사용 가능한가 어떤가를 조사해 사용 가능하면, 그 디바이스에 DirectInputDevice 오브젝트를 생성 해야 한다. 여기서, x 축과 y 축으로 이펙트를 재생할 수 있는 디바이스가 필요한 어플리케이션을 생각해 본다.

다음의 샘플은,DirectInput 오브젝트를 생성 해, 그것을 사용해 DirectInputEnumDevices 오브젝트내의 이용 가능한 디바이스를 열거하는 것으로부터 시작 한다. 모든 force feedback 디바이스는 DIDEVTYPE_JOYSTICK 형이므로, 열거 대상은 이 형태의 Attach가 끝난 디바이스에 제한되고 있다.

' dx 는 초기화 끝난 글로벌 DirectX 오브젝트.
' di 는, 글로벌 DirectInput 오브젝트.

Dim diDevInst As DirectInputDeviceInstance
Dim diDevObjEnum As DirectInputEnumDeviceObjects
Dim devobj As DirectInputDeviceObjectInstance

Dim devcaps As DIDEVCAPS
Dim ForceX As Boolean, ForceY As Boolean
Dim FoundForce As Boolean
Dim efftype As Long
Dim strObjGuid As String

Dim i As Integer, iAxes As Integer

Set di = dx.DirectInputCreate
Set diEnumDev = di.GetDIEnumDevices(DIDEVTYPE_JOYSTICK, _
        DIEDFL_ATTACHEDONLY)

여기서, 샘플은 force feedback 능력을 가지는 디바이스를 찾아낼 때까지, 사용 가능한 디바이스의 조사를 반복한다.

For i = 1 To diEnumDev.GetCount
  Set diDevInst = diEnumDev.GetItem(i)
  Set didev = di.CreateDevice(diDevInst.GetGuidInstance)
  Call didev.GetCapabilities(devcaps)
  If devcaps.lFlags And DIDC_FORCEFEEDBACK Then

여기서, 샘플은 DirectInputEnumDeviceObjects 콜렉션에 포함되는 디바이스 위에의축을 열거한다.

    Set diDevObjEnum = didev.GetDeviceObjectsEnum(DIDFT_AXIS)
    ForceX = False
    ForceY = False

다음에, 축중에서 x 축과 y 축을 찾아, 그러한 축이 force feedback 이펙트를 지원 할지 어떨지를 조사한다.

    For iAxes = 1 To diDevObjEnum.GetCount
      Set devobj = diDevObjEnum.GetItem(iAxes)
      strObjGuid = devobj.GetGuidType
      If strObjGuid = "GUID_XAxis" Then
        If devobj.GetFlags And DIDOI_FFACTUATOR Then
          ForceX = True
        End If
      ElseIf strObjGuid = "GUID_YAxis" Then
        If devobj.GetFlags And DIDOI_FFACTUATOR Then
          ForceY = True
        End If
      End If
    Next iAxes
    FoundForce = ForceX And ForceY
    if FoundForce Then Exit For
  End If
Next i

If Not FoundForce Then
  MsgBox "Two force feedback axes required. "
End

다음 방향 : 스텝 2 : 디바이스 프로퍼티의 설정


스텝 2 : 디바이스 프로퍼티의 설정

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

적절한 force feedback 디바이스가 발견되었을 경우, 능력을 체크하기 위해서 전의 스텝에서 생성 된 DirectInputDevice 오브젝트가 남아 있다. 오브젝트에는, 데이터 형식이나 협조 레벨의 설정, 및 입력용의 범위 프로퍼티의 설정등의 초기화가 필요하다. 이 처리에 대해서는, 「튜토리얼 3 : 죠이스틱의 사용」을 참조할것. 협조 레벨에는 DISCL_EXCLUSIVE 를 포함하지 않으면 안 된다. 디바이스에의 백그라운드 액세스권을 가질 필요는 없지만, DISCL_BACKGROUND 플래그를 사용하면(자), 코드 윈도우로 전환할 때 취득을 잃는 것이 없어지므로, 디버그 작업이 용이하게 된다.

Call didev.SetCommonDataFormat(DIFORMAT_JOYSTICK2)
Call didev.SetCooperativeLevel(Me.hWnd, _
        DISCL_BACKGROUND Or DISCL_EXCLUSIVE)
'범위 프로퍼티의 설정등을 실시한다.
.
.
.

force feedback의 경우, 디폴트의 스프링 액션이 생성하는 이펙트에 간섭하지 않게, 디바이스의 자동 센터링 프로퍼티를 무효로 하고 싶은 경우도 있다.

Dim prop As DIPROPLONG
prop.lData = 0
prop.lHow = DIPH_DEVICE
prop.lObj = 0
prop.lSize = Len(prop)
Call didev.SetProperty("DIPROP_AUTOCENTER", prop)

didev.Acquire

다음 방향 : 스텝 3 : 이펙트의 생성


스텝 3 : 이펙트의 생성

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

어플리케이션으로, 죠이스틱에 제어되는 이동 가능 오브젝트 (예를 들어, 철구)에 대해서 정지 오브젝트 (예를 들어, 자석)가 끌어당기는 힘을 시뮬레이트 하는 것을 생각해 보자. 이 시뮬레이션의 최초로, 철구는 자석의 남쪽에 있어, 당기는 최대 거리의 반의 위치에 있다.

정수 포스에 의해 자석이 끌어당기는 힘을 시뮬레이트 한다. 우선, 이 포스를 나타내는 DIEFFECT 형을 설정한다.

Dim EffectInfo as DIEFFECT
With EffectInfo
  . constantForce.lMagnitude = 5000
  . lDuration = -1       '무한.
  . x = 18000
  . lGain = 10000        '전매그니튜드로 재생한다.
  . lTriggerButton = -1  '방아쇠 버튼 없음.
End With

DIEFFECT 외의 모든 멤버는, 정수 포스에 무관계한가, 또는 제로로서 유효하다.

다음에 이펙트를 생성한다.

Dim di_effect As DirectInputEffect
Set di_effect = didev.CreateEffect("GUID_ConstantForce", EffectInfo)

이 때에 디바이스가 취득 상태에 있으면, 이펙트가 자동적으로 다운로드된다. 취득 상태에 없으면, 이펙트는 시작시에 다운로드된다.

di_effect.Start(1, 0)

이 이펙트는 무한의 계속 시간을 가지고 있으므로, 이펙트를 한 번만 반복하는 경우, 플래그는 불필요하다.

다음 방향 : 스텝 4 : 이펙트의 변경


스텝 4 : 이펙트의 변경

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

유저가 철구를 회전시키는데 응해, 어플리케이션은 이펙트의 방향과 매그니튜드를 조정한다. 다만, 최초로, 그 디바이스로 이펙트를 정지해 재개하지 않고 이펙트의 방향을 변경할 수 있을지 어떨지를 조사할 필요가 있다. DirectInput 는 필요에 따라서 이펙트를 정지해 재개하지만, 동작의 연속성을 유지하면서, 어플리케이션의 동작을 변경하고 싶은 경우도 있다.

이펙트의 능력을 조사하기 위해서(때문에), 지원 되는 이펙트를 열거해, 필요한 특정의 이펙트를 찾을 필요가 있다.

Dim diEnumEffects As DirectInputEnumEffects
Dim params As Long
Dim i As Long

'정수 포스를 열거한다.

Set diEnumEffects = didev.GetEffectsEnum(DIEFT_CONSTANTFORCE)

For i = 1 To diEnumEffects.GetCount

  '표준의 정수 포스를 찾는다. 다른 처리를 실시해도 괜찮다.

  If diEnumEffects.GetEffectGuid(i) = "GUID_ConstantForce" Then
    params = diEnumEffects.GetDynamicParams(i)
    Exit For
  End If

Next i

If Not (params And DIEP_DIRECTION) Then
  '방향을 동적으로 바꿀 수 없다. 변경 대상의 포인트를 제한하는 등,
  '보정을 위한 조치를 취한다.
End If

같이 이펙트의 매그니튜드를 동적으로 변경할 수 있을지 어떨지를 알려면 , 다음의 체크를 실시한다.

if Not (params And DIEP_TYPESPECIFICPARAMS)
   '타입 고유 파라미터를 동적이게는 변경할 수 없다.
End If

다음에, 디바이스에 입력의 유무를 폴링 해 철구를 이동할 때마다 이펙트를 변경해 보자. 여기서,CurrentMag 에 새로운 매그니튜드, 및 CurrentBearing 에 새로울 방향 (번단위)을 계산했다고 한다. 필요한 변경을 더하기 위해서(때문에),DIEFFECT 의 관련하는 멤버만을 초기화할 필요가 있다.

EffectInfo.constantForce.lMagnitude = CurrentMag
EffectInfo.x = CurrentBearing * 100

여기서, 어느 멤버에 유효한 데이터가 포함되어 있는지를 나타내는 플래그와 함께,DIEFFECT 형을 DirectInputEffect.SetParameters 에 건네준다.

di_effect.SetParameters(EffectInfo, _
        DIEP_DIRECTION Or DIEP_TYPESPECIFICPARAMS)

DIEP_TYPESPECIFICPARAMS 플래그는, 그 이펙트의 타입에 관련하는 정보를 포함한 멤버가 유효한 것을 나타낸다. 정수 포스의 경우, 이것은 constantForce 멤버를 의미한다.


DirectInput 레퍼런스

여기에서는, C/C++ 및 Microsoft® Visual Basic® 개발 시스템으로 Microsoft® DirectInput® 가 제공하는 API (Application Programming Interface) 요소의 레퍼런스 정보를 기술한다. 레퍼런스 정보는 이하의 언어별로 구성된다.

  • DirectInput C/C++ 레퍼런스
  • DirectInput Visual Basic 레퍼런스


DirectInput C/C++ 레퍼런스

DirectInput C/C++ API 의 레퍼런스 정보는, 다음과 같이 분류된다.

  • 인터페이스
  • 함수
  • 콜백 함수
  • 매크로
  • 구조체
  • 디바이스 정수
  • 반환값


인터페이스

여기에서는, 이하의 DirectInput 인터페이스의 메소드에 관한 레퍼런스를 제공한다.

  • IDirectInput7
  • IDirectInputDevice7
  • IDirectInputEffect

주 : 모든 DirectInput 메소드에는, 정의되고 있는 언어에 응해, C 또는 C++ 구문에 전개하는 매크로가 준비되어 있다. 이러한 매크로는 Dinput.h 헤더 파일에 있어, 독립해 기술되고 있는 것은 아니다.


IDirectInput7

어플리케이션은,IDirectInput7 인터페이스의 메소드를 사용해, DirectInput 디바이스의 열거, 생성, 스테이터스의 수신, DirectInput 오브젝트의 초기화, 및 컨트롤 패널의 인스턴스의 기동을 실시한다.

IDirectInput7 인터페이스는 DirectInputCreateEx 함수를 사용해 취득한다.

IDirectInput7 는, 지금까지의 DirectX 의 버젼으로 사용되고 있던 IDirectInput 에 취해 대신하는 인터페이스이다.

IDirectInput7 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

디바이스 관리 | CreateDevice
 | CreateDeviceEx
 | EnumDevices
 | FindDevice
 | GetDeviceStatus
그 외 | Initialize
 | RunControlPanel

모든 COM 인터페이스와 같게,IDirectInput 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTINPUT 형은 IDirectInput7 인터페이스에의 포인터로서 정의된다.

typedef struct IDirectInput7    *LPDIRECTINPUT7;

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInput7::CreateDevice

IDirectInput7::CreateDevice 메소드는, 지정의 GUID 에 근거해 디바이스의 인스턴스를 생성 해 초기화해,IDirectInputDevice 인터페이스를 취득한다. 이것은,IDirectInput7::CreateDeviceEx 에 취해 대신하는 메소드이다.

HRESULT CreateDevice(
  REFGUID rguid,
  LPDIRECTINPUTDEVICE *lplpDirectInputDevice,
  LPUNKNOWN pUnkOuter
);

파라미터

rguid
C++ 의 경우, 목적의 입력 디바이스의 인스턴스 GUID 에 대한 참조값. C 의 경우, 이 GUID 의 주소 ( 「주의」를 참조). 이 GUID 는,IDirectInput7::EnumDevices 메소드를 개입시켜 취득하는지, 또는, 다음일 전정의된 GUID 의 1 개를 사용한다.
GUID_SysKeyboard
디폴트의 시스템키 보드.
GUID_SysMouse
디폴트의 시스템 마우스.

이 GUID 값을 유효하게 하려면 , 어플리케이션은, 소스 파일의 선두에서, 다른 모든 프리프로세서 지시문에 앞서, INITGUID 를 정의하든가, 혹은 DXGUID.LIB 에 링크해야 한다.

lplpDirectInputDevice
성공시에 IDirectInputDevice 인터페이스의 포인터를 취득하는 변수의 주소.
pUnkOuter
COM 집합화에 대한 제어 오브젝트의 IUnknown 인터페이스의 주소. 인터페이스가 집합화 되지 않는 경우에는 NULL. 보통, 호출측은 NULL 를 건네준다.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 반환값의 어느쪽이든을 돌려준다.

DIERR_DEVICENOTREG
DIERR_INVALIDPARAM
DIERR_NOINTERFACE
DIERR_NOTINITIALIZED
DIERR_OUTOFMEMORY

주의

C++ 에서는,rguid 파라미터는 참조값으로서 건네주지 않으면 안 된다. C 에서는 참조값으로서 건네줄 수가 없기 때문에, 주소로서 건네주지 않으면 안 된다. 다음은, C++ 에서의 호출해 예이다.

lpdi->CreateDevice(GUID_SysKeyboard, &pdev, NULL);

다음은, C 에서의 같은 호출해 예이다.

lpdi->lpVtbl->CreateDevice(lpdi, &GUID_SysKeyboard, &pdev, NULL);

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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInput7::CreateDeviceEx

IDirectInput7::CreateDeviceEx 메소드는, 지정의 GUID 에 근거해 디바이스의 인스턴스를 생성 해 초기화해,IDirectInputDevice,IDirectInputDevice2, 또는 IDirectInputDevice7 인터페이스를 취득한다.

HRESULT CreateDeviceEx(
  REFGUID rguid,
  REFIID riid,
  LPVOID *pvOut,
  LPUNKNOWN pUnkOuter
);

파라미터

rguid
C++ 의 경우, 목적의 입력 디바이스의 인스턴스 GUID 에 대한 참조값. C 의 경우, 이 GUID 의 주소 ( 「주의」를 참조). 이 GUID 는,IDirectInput7::EnumDevices 메소드를 개입시켜 취득하는지, 또는, 다음일 전정의된 GUID 의 1 개를 사용한다.
GUID_SysKeyboard
디폴트의 시스템키 보드.
GUID_SysMouse
디폴트의 시스템 마우스.

이 GUID 값을 유효하게 하려면 , 어플리케이션은, 소스 파일의 선두에서, 다른 모든 프리프로세서 지시문에 앞서, INITGUID 를 정의하든가, 혹은 DXGUID.LIB 에 링크해야 한다.

riid
목적의 인터페이스의 일의인 식별자. 현재 받아들이는 값은, IID_IDirectInputDevice, IID_IDirectInputDevice2, 및 IID_IDirectInputDevice7 이다.
pvOut
성공시에 인터페이스 포인터를 취득하는 변수의 주소.
pUnkOuter
COM 집합화에 대한 제어 오브젝트의 IUnknown 인터페이스의 주소. 인터페이스가 집합화되어 있지 않은 경우에는 NULL. 보통, 호출측은 NULL 를 건네준다.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 반환값의 어느쪽이든을 돌려준다.

DIERR_DEVICENOTREG
DIERR_INVALIDPARAM
DIERR_NOINTERFACE
DIERR_NOTINITIALIZED
DIERR_OUTOFMEMORY

주의

C++ 에서는,rguid 파라미터는 참조값으로서 건네주지 않으면 안 된다. C 에서는 참조값으로서 건네줄 수가 없기 때문에, 주소로서 건네주지 않으면 안 된다. 다음은, C++ 에서의 호출해 예이다.

lpdi->CreateDevice(GUID_SysKeyboard, &pdev, NULL);

다음은, C 에서의 같은 호출해 예이다.

lpdi->lpVtbl->CreateDevice(lpdi, &GUID_SysKeyboard, &pdev, NULL);

많은 경우, 어플리케이션은,riid 파라미터로서 IID_IDirectInputDevice7 를 건네주어,IDirectInputDevice7 인터페이스를 취득하게 된다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInput7::EnumDevices

IDirectInput7::EnumDevice 메소드는, 현재 컴퓨터에Attach 되고 있는지, Attach 가능한 디바이스를 열거한다.

HRESULT EnumDevices(
  DWORD dwDevType,
  LPDIENUMCALLBACK lpCallback,
  LPVOID pvRef,
  DWORD dwFlags
);

파라미터

dwDevType
디바이스 타입의 필터. 이 파라미터가 제로라면, 모든 디바이스 타입이 열거된다. 제로가 아니면, 열거해야 할 디바이스 타입을 나타내는 DIDEVTYPE_* 값이 된다 ( 「DIDEVICEINSTANCE 」를 참조).
lpCallback
각 DirectInput 디바이스의 기술을 사용해 불려 가는 콜백 함수의 주소.
pvRef
어플리케이션 정의의 32 비트값. 열거 콜백 함수가 불릴 때마다 건네받는다.
dwFlags
열거의 범위를 지정하는 플래그값. 다음의 플래그를 지정한다.
DIEDFL_ALLDEVICES
모든 인스톨이 끝난 디바이스가 열거된다. 이것이 디폴트 모드이다.
DIEDFL_ATTACHEDONLY
Attach 또한 인스톨이 끝난 디바이스만.
DIEDFL_FORCEFEEDBACK
force feedback를 지원 하는 디바이스만.
DIEDFL_INCLUDEALIASES
다른 디바이스의 앨리어스(alias)인 디바이스를 포함한다.
DIEDFL_INCLUDEPHANTOMS
가상 디바이스 (플레이스홀더)를 포함한다.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

주의

모든 인스톨이 끝난 디바이스는, 비록 그것이 현존 하고 있지 않아도 열거 가능하다. 예를 들어, 조종간은, 시스템에 인스톨 하지만, 당면 컴퓨터에 접속하지 않고 둘 수도 있다. dwFlags 파라미터를 설정해, Attach 되고 있는 디바이스만을 열거하는지, 또는 인스톨 끝난 모든 디바이스를 열거하는지를 지시한다. DIEDFL_ATTACHEDONLY 플래그가 존재하지 않는 경우는, 인스톨 끝난 전디바이스가 열거된다.

선별하고 싶은 디바이스 타입을 dwDevType 필터로서 건네주어, 그 타입의 디바이스만을 열거할 수가 있다.

LpCallback 파라미터에는,DIEnumDevicesCallback 로서 표기되고 있는 종류의 콜백 함수의 주소를 지정한다. DirectInput 는, 열거되고 있는 디바이스 마다, 이 함수를 호출한다. 이 콜백 함수 중(안)에서는, 디바이스 타입과 등록명, 및 제품 GUID 와 등록명이, 각 디바이스에 대해서 주어진다. 단일의 입력 디바이스가, 복수의 DirectInput 디바이스 타입으로서 기능할 수가 있는 경우는, 지원 하는 각 디바이스 타입 마다 돌려주어진다. 예를 들어, 편입 마우스 부착의 키보드는, 1 개의 키보드로서 한편, 1 개의 마우스로서 열거된다. 다만, 제품 GUID 는 각 디바이스에 대해서 같다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInput7::FindDevice

IDirectInput7::FindDeviceStatus 메소드는, 시스템에 새롭게 Attach 된 디바이스의 인스턴스 GUID 를 취득한다. 이 메소드는, Win32 디바이스 관리 통지에 응답해 불려 간다.

HRESULT FindDevice(
  REFGUID rguidClass,
  LPCTSTR ptszName,
  LPGUID pguidInstance
);

파라미터

rguidClass
어플리케이션이 검색하는 디바이스 클래스의 일의인 식별자. 어플리케이션은, 디바이스 도착 통지로부터 클래스 GUID 를 취득한다 (Platform SDK 의 DBT_DEVICEARRIVAL 이벤트의 주제를 참조).
ptszName
디바이스의 이름. 어플리케이션은, 디바이스 도착 통지로부터 이름을 취득한다.
pguidInstance
디바이스가 발견되었을 경우에 디바이스의 인스턴스 GUID 를 받는 변수의 주소. 이 값은 IDirectInput7::CreateDeviceEx 에 건네줄 수가 있다.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 DIERR_DEVICENOTREG 를 돌려준다. GUID 와 이름이, DirectInput 에 등록되어 있는 디바이스 클래스에 대응하지 않는 경우는, 실패가 된다. 예를 들어, 입력 디바이스는 아니고, 기억 디바이스를 참조하는 경우 등이다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.

참조

디바이스 변경의 인식


IDirectInput7::GetDeviceStatus

Platform SDK: DirectX

IDirectIIDirectInput::GetDeviceStatus

IDirectInput7::GetDeviceStatus 메소드는, 지정 디바이스의 스테이터스를 취득한다.

HRESULT GetDeviceStatus(
  REFGUID rguidInstance
);

파라미터

rguidInstance
스테이터스를 체크하는 디바이스의 인스턴스 식별자.

반환값

메소드가 성공해, 디바이스가 시스템에Attach 되고 있는 경우는 DI_OK 를 돌려주어, 그렇지 않으면 DI NOTATTACHED 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_GENERIC
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInput7::Initialize

IDirectInput7::Initialize 메소드는, DirectInput 오브젝트를 초기화한다. DirectInputCreate 함수와 DirectInputCreateEx 함수는, 생성 한 DirectInput 오브젝트를 자동적으로 초기화한다. 어플리케이션은, 보통, 이 메소드를 호출할 필요는 없다.

HRESULT Initialize(
  HINSTANCE hinst,
  DWORD dwVersion
);

파라미터

hinst
DirectInput 오브젝트를 생성 하는 어플리케이션 또는 DLL 의 인스턴스 핸들. DirectInput 는, 이 값을 사용해, 어플리케이션 또는 DLL 가, 오브젝트 생성의 자격을 인정받고 있는지 어떤지를 판단해, 하위 호환성을 위해서(때문에) 취해야 할 특별한 동작을 확정한다.

DLL 가 부모의 어플리케이션의 핸들을 건네주면(자), 에러가 된다. 예를 들어, Web 페이지에 파묻히고 있어 DirectInput 를 사용하는 ActiveX 컨트롤은, Web 브라우저의 핸들은 아니고, 그것 자신의 인스턴스의 핸들을 건네주지 않으면 안 된다. 이것에 의해, DirectInput 가 그 컨트롤을 인식해, 필요라고 생각되는 특별한 동작을 모두 유효하게 하는 것이 확실히 된다.

dwVersion
어플리케이션의 설계 대상인 DirectInput 의 버젼 번호. 이 값은 보통, DIRECTINPUT_VERSION 이다. 이전의 버젼 번호를 건네주면(자), DirectInput 가 그 버젼을 에뮬레이트 하게 된다. 자세한 것은, 「전의 버젼의 DirectInput 의 설계」를 참조할것.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_BETADIRECTINPUTVERSION
DIERR_OLDDIRECTINPUTVERSION

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInput7::RunControlPanel

Platform SDK: DirectX

IDirectInputDevice::RunControlPanel

IDirectInput7::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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.

참조

IDirectInputDevice7::RunControlPanel


IDirectInputDevice7

어플리케이션은,IDirectInputDevice7 인터페이스의 메소드를 사용해, DirectInput 디바이스의 액세스권의 취득과 릴리즈, 디바이스 프로퍼티와 정보의 관리, 동작의 설정, 초기화의 실행, force feedback 이펙트의 생성과 재생, 및 디바이스의 컨트롤 패널의 기동을 실시한다.

IDirectInput7 인터페이스는 IDirectInput7::CreateDeviceEx 메소드를 사용해 취득한다. 예에 대해서는, 「DirectInput 디바이스의 생성」을 참조할것.

IDirectInputDevice7 는, 지금까지의 버젼의 DirectX 로 사용되고 있던 IDirectInputDevice 및 IDirectInputDevice2 에 취해 대신하는 인터페이스이다.

IDirectInputDevice7 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

입력 디바이스의 액세스 | Acquire
 | Unacquire
디바이스 정보 | 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 인터페이스와 같게,IDirectInputDevice7 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTINPUTDEVICE7 형은 IDirectInputDevice 인터페이스에의 포인터로서 정의된다.

typedef struct IDirectInputDevice7    *LPDIRECTINPUTDEVICE7;

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.

참조

IDirectInputDevice7

Built on 2000년 4월 13일


IDirectInputDevice7::Acquire

IDirectInputDevice7::Acquire 메소드는, 입력 디바이스에의 액세스권을 취득한다.

HRESULT Acquire();

파라미터

없음.

반환값

성공하면 DI_OK 또는 S_FALSE,

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
DIERR_OTHERAPPHASPRIO

S_FALSE 가 돌려주어졌을 경우, 디바이스는 취득이 끝난 상태이다.

주의

디바이스 취득전에 IDirectInputDevice7::SetDataFormat 메소드를 사용해, 데이터 형식을 설정해야 한다.

디바이스에 대해서 IDirectInputDevice7::GetDeviceState 또는 IDirectInputDevice7::GetDeviceData 메소드를 호출하기 전에, 그 디바이스를 취득해 두지 않으면 안 된다.

디바이스 취득에서는,참조 카운트를 사용하지 않는다. 이 때문에, 어플리케이션이 IDirectInputDevice7::Acquire 메소드를 2 회 호출해, 그 후 IDirectInputDevice7::Unacquire 메소드를 1 회 호출하면, 디바이스는 릴리즈 된다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputDevice2::CreateEffect

Platform SDK: DirectX

IDirectInputDevice7::CreateEffect

IDirectInputDevice7::CreateEffect 메소드는, 이펙트의 GUID 에 의해 식별되는 이펙트의 인스턴스를 생성, 초기화한다.

HRESULT CreateEffect(
  REFGUID rguid,
  LPCDIEFFECT lpeff,
  LPDIRECTINPUTEFFECT * ppdeff,
  LPUNKNOWN punkOuter
);

파라미터

rguid
생성 하는 이펙트의 식별 정보. 이것은 사전 정의된 이펙트 GUID 에서도, 혹은 IDirectInputDevice7::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_DEVICENOTREG
DIERR_DEVICEFULL
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

반환값이 S_OK 인 경우, 이펙트는 생성이 끝난 상태로, 이펙트의 파라미터는 갱신이 끝난 상태이지만, 이펙트를 다운로드할 필요가 없었던 것을 나타낸다. 이펙트를 다운로드하려면 , 디바이스를 배타 모드로 취득해야 한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputDevice2::EnumCreatedEffectObjec

Platform SDK: DirectX

IDirectInputDevice7::EnumCreatedEffectObjects

IDirectInputDevice7::EnumCreatedEffectObjects 메소드는, 이 디바이스에 현재 생성 떠날 수 있어 모든 이펙트를 열거한다. IDirectInputDevice7::CreateEffect 에 의해 생성 된 이펙트가 열거된다.

HRESULT EnumCreatedEffectObjects(
  LPDIENUMCREATEDEFFECTOBJECTSCALLBACK lpCallback,
  LPVOID pvRef,
  DWORD fl
);

파라미터

lpCallback
어플리케이션 정의의 콜백 함수의 주소. DirectInput 는, prototype 함수 DIEnumCreatedEffectObjectsCallback 를 제공하고 있다.
pvRef
콜백용의 레퍼런스 데이터 (문맥)
fl
플래그는 현재 미정도리이다. 이 파라미터는, 제로가 아니면 안된다.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

주의

열거의 진행중에, 이펙트를 생성 또는 폐기 하면, 그 결과는 예측할 수 없다. 그러나, 콜백 함수는, 건네받는 이펙트를 확실히 릴리즈 한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputDevice2::EnumEffects

Platform SDK: DirectX

IDirectInputDevice7::EnumEffects

IDirectInputDevice7::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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputDevice2::EnumEffects

Platform SDK: DirectX

IDirectInputDevice7::EnumEffectsInFile

IDirectInputDevice7::EnumEffectsInFile 메소드는,Force Editor 유틸리티나, 같은 파일 형식을 사용하는 다른 어플리케이션으로, 생성 된 파일에 포함되는 모든 이펙트를 열거한다.

HRESULT EnumEffectsInFile(
  LPCSTR lpszFileName,
  LPENUMEFFECTSINFILECALLBACK pec,
  LPVOID pvRef,
  DWORD dwFlags
);

파라미터

lpszFileName
Name of the RIFF file.
pec
어플리케이션 정의의 콜백 함수의 주소. 이 함수의 선언은,DIEnumEffectsInFileCallback prototype의 선언과 같게 실시하지 않으면 안 된다.
pvRef
콜백 함수에 건네주는 어플리케이션 정의의 32 비트의 값. 이 파라미터는, 32 비트의 임의의 값을 취할 수가 있다.
dwFlags
DIFEF_DEFAULT (= 0) 혹은 이하의 값의 한편 또는 양쪽 모두를 사용할 수 있다.
DIFEF_INCLUDENONSTANDARD
DirectInput 로 정의되어 있지 않은 이펙트 타입을 포함한다.
DIFEF_MODIFYIFNEEDED
현재의 디바이스로 재생할 수 있도록(듯이), 생성 한 이펙트를 필요에 따라서 변경하도록(듯이) DirectInput 에 대해서 지시한다. 예를 들어, 2 개의 축으로 대해 생성 된 이펙트는, 디폴트에서는 단일축디바이스에서는 재생되지 않는다. 이 플래그를 설정 하면, 단일축으로 그러한 이펙트가 재생된다. 파라미터는,DIEFFECT 구조 체내에서 변경된다. 이 구조체는, 콜백에게 건네지는 DIFILEEFFECT 구조체의 lpDiEffect 멤버에 의해 참조된다.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

콜백 함수가 열거를 도중에 정지 하면, 그 열거는 성공했다고 보여진다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.

참조

IDirectInputDevice7::WriteEffectToFile , 「파일로부터의 이펙트의 read」


IDirectInputDevice7::EnumObjects

IDirectInputDevice7::EnumObjects 메소드는, 디바이스상에서 사용 가능한 입력 소스 (축, 버튼등)를 열거한다.

HRESULT EnumObjects(
  LPDIENUMDEVICEOBJECTSCALLBACK lpCallback,
  LPVOID pvRef,
  DWORD dwFlags
);

파라미터

lpCallback
DirectInputDevice 오브젝트의 콜백 함수의 주소. DirectInput 는, 이 함수의 prototype를 DIEnumDeviceObjectsCallback 로서 제공하고 있다.
pvRef
콜백용의 레퍼런스 데이터 (문맥)
dwFlags
열거하는 오브젝트의 타입을 지정하는 플래그. 다음의 플래그는, 열거 대상이 지정된 타입의 오브젝트에 제한한다.
DIDFT_ABSAXIS
절대축.
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
IDirectInputDevice7::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)를 지정 하면, 이펙트 방아쇠로서 이용할 수 있는 임의의 버튼이 열거된다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputDevice2::Escape

Platform SDK: DirectX

IDirectInputDevice7::Escape

IDirectInputDevice7::Escape 메소드는, 하드웨어 고유의 커멘드를 force feedback 드라이버에 송신한다.

HRESULT Escape(
  LPDIEFFESCAPE pesc
);

파라미터

pesc
송신하는 커멘드를 나타내는 DIEFFESCAPE 구조체. 성공하면(자), 실제로 사용하는 출력 버퍼의 바이트수가 cbOutBuffer 멤버에 저장 된다.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_DEVICEFULL
DIERR_NOTINITIALIZED

다른 디바이스 고유 에러 코드를 돌려줄 수도 있다. 하드웨어 메이커로부터 상세 정보를 입수하는 것.

주의

각 드라이버는, 다른 escape sequence를 이행 하고 있으므로, 올바른 드라이버와 통신하고 있을지 어떨지는, 어플리케이션 자체가 확인해야 한다. 이것은,DIDEVICEINSTANCE 구조체의 guidFFDriver 멤버와 어플리케이션이 기대하고 있는 값을 비교하는 것으로써 확인할 수 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputDevice7::GetCapabilities

IDirectInputDevice7::GetCapabilities 메소드는, DirectInputDevice 오브젝트의 능력을 취득한다.

HRESULT GetCapabilities(
  LPDIDEVCAPS lpDIDevCaps
);

파라미터

lpDIDevCaps
디바이스의 능력을 저장 하는 DIDEVCAPS 구조체의 주소. 이 구조체의 dwSize 멤버는, 이 메소드를 호출하기 전에 초기화해 두지 않으면 안 된다.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

주의

DirectX 3 과의 호환성에 대해서는,sizeof(DIDEVCAPS_DX3) 에 초기화한 dwSize 멤버를 포함한 DIDEVCAPS_DX3 구조체를 건네주어도 괜찮다. 상세한 것에 대하여는, 「전의 버젼의 DirectInput 의 설계」를 참조할것.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputDevice2::SendDeviceData

Platform SDK: DirectX

IDirectInputDevice7::GetDeviceData

IDirectInputDevice7::GetDeviceData 메소드는, 디바이스로부터 버퍼링 데이터를 취득한다.

HRESULT GetDeviceData(
  DWORD cbObjectData,
  LPDIDEVICEOBJECTDATA rgdod,
  LPDWORD pdwInOut,
  DWORD dwFlags
);

파라미터

cbObjectData
DIDEVICEOBJECTDATA 구조체의 바이트 단위의 사이즈.
rgdod
버퍼링 데이터를 받기 위한 DIDEVICEOBJECTDATA 구조체의 배열. 이 배열의 요소수는,pdwInOut 파라미터의 값과 동일하지 않으면 안 된다. 이 파라미터가 NULL 의 경우, 버퍼링 데이터는 어디에도 저장 되지 않지만, 그 외의 부차 이펙트는 모두 발생한다.
pdwInOut
입력 파라미터는,rgdod 파라미터가 가리키는 배열의 요소수이다. 출력 파라미터는, 실제로 취득된 요소수이다.
dwFlags
데이터를 취득하는 방법을 제어하는 플래그. 제로 또는 다음의 플래그를 지정한다.
DIGDD_PEEK
버퍼로부터 항목을 삭제하지 않는다. 이 이후의 IDirectInputDevice7::GetDeviceData 호출로, 같은 데이터를 읽어낼 수가 있다. 보통, 데이터는 읽기 후, 버퍼로부터 삭제된다.

반환값

성공하면 DI_OK 또는 DI_BUFFEROVERFLOW ,

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
DIERR_NOTBUFFERED
DIERR_NOTINITIALIZED

주의

디바이스 데이터를 취득하기 전에,IDirectInputDevice7::SetDataFormat 메소드로 데이터 형식을 설정해,IDirectInputDevice7::SetProperty 메소드로 버퍼 사이즈를 설정해, 계속되어 IDirectInputDevice7::Acquire 메소드로 디바이스를 취득해야 한다.

이하의 예에서는, 버퍼링 데이터 요소를 최고 10 개까지 읽어낸다. 디바이스 버퍼로부터는, 데이터를 읽기면서 삭제하고 있다.

DIDEVICEOBJECTDATA rgdod[10];
DWORD dwItems = 10;
hres = IDirectInputDevice7_GetDeviceData(
pdid,
sizeof(DIDEVICEOBJECTDATA),
rgdod,
&dwItems,
    0);
if (SUCCEEDED(hres)) {
// dwItems = 읽어내진 요소수 (0 이 된다).
if (hres == DI_BUFFEROVERFLOW) {
// 버퍼가 오버플로우 했다.
    }
}

버퍼를 플래시 해, 플래시 한 항목의 수를 취득하려면 ,rgdod 파라미터에 NULL,pdwInOut 파라미터에 INFINITE 를 포함한 변수에의 포인터를 각각 지정한다. 이하의 예로, 그방법을 나타낸다.

dwItems = INFINITE;
hres = IDirectInputDevice7_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 = IDirectInputDevice7_GetDeviceData(
pdid,
sizeof(DIDEVICEOBJECTDATA),
NULL,
&dwItems,
DIGDD_PEEK);
if (SUCCEEDED(hres)) {
// dwItems = 버퍼내의 요소수.
if (hres == DI_BUFFEROVERFLOW) {
// 버퍼 오버플로우가 발생. 일부의 데이터
// 의 캡춰에 실패했다.
    }
}

버퍼 오버플로우가 발생했는지 어떠했는지를 조사하려면 ,rgdod 파라미터에 NULL,pdwInOut 파라미터에 제로를 설정한다. 이하의 예로, 그방법을 나타낸다.

dwItems = 0;
hres = IDirectInputDevice7_GetDeviceData(
pdid,
sizeof(DIDEVICEOBJECTDATA),
NULL,
&dwItems,
            0);
if (hres == DI_BUFFEROVERFLOW) {
// 버퍼 오버플로우가 발생.
}

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.

참조

IDirectInputDevice7::Poll , 「폴링과 이벤트」


IDirectInputDevice7::GetDeviceInfo

IDirectInputDevice7::GetDeviceInfo 메소드는, 디바이스의 식별 정보를 취득한다.

HRESULT GetDeviceInfo(
  LPDIDEVICEINSTANCE pdidi
);

파라미터

pdidi
디바이스의 식별 정보를 저장 하는 DIDEVICEINSTANCE 구조체의 주소. 어플리케이션은, 이 메소드를 호출하기 전에, 이 구조체의 dwSize 멤버를 초기화해 두지 않으면 안 된다.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

주의

DirectX 3 과의 호환성에 대해서는,sizeof(DIDEVICEINSTANCE_DX3 ) 에 초기화한 dwSize 멤버를 포함한 DIDEVICEINSTANCE_DX3 구조체를 건네주어도 괜찮다. 상세한 것에 대하여는, 「전의 버젼의 DirectInput 의 설계」를 참조할것.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputDevice7::GetDeviceState

IDirectInputDevice7::GetDeviceState 메소드는, 디바이스로부터 직접 데이터를 취득한다.

HRESULT GetDeviceState(
  DWORD cbData,
  LPVOID lpvData
);

파라미터

cbData
lpvData 파라미터내의 바이트 단위의 버퍼 사이즈.
lpvData
디바이스의 현재 상태를 받는 구조체의 주소. IDirectInputDevice7::SetDataFormat 메소드를 호출하기 전에, 데이터 형식을 설정한다.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
DIERR_NOTINITIALIZED
E_PENDING

주의

디바이스 데이터를 취득하기 전에,IDirectInputDevice7::SetCooperativeLevel 메소드로 협조 레벨을 설정한 후,IDirectInputDevice7::SetDataFormat 메소드로 데이터 형식을 설정해,IDirectInputDevice7::Acquire 메소드로 디바이스를 취득한다.

다음 표에 나타내도록(듯이), 5 개의 정의가 끝난 데이터 형식에는, 각각 대응하는 디바이스 상태 구조체가 필요하다.

데이터 형식 | 상태 구조체
c_dfDIMouse | DIMOUSESTATE
c_dfDIMouse2 | DIMOUSESTATE2
c_dfDIKeyboard | 256 바이트의 배열
c_dfDIJoystick | DIJOYSTATE
c_dfDIJoystick2 | DIJOYSTATE2

예를 들어,c_dfDIMouse 형식을 IDirectInputDevice::SetDataFormat 메소드에 건네주는 경우는,DIMOUSESTATE 구조체를 IDirectInputDevice::GetDeviceState 메소드에 건네주지 않으면 안 된다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.

참조

IDirectInputDevice7::Poll , 「폴링과 이벤트」, 「버퍼링 데이터와 직접 데이터」


IDirectInputDevice2::GetEffectInfo

Platform SDK: DirectX

IDirectInputDevice7::GetEffectInfo

IDirectInputDevice7::GetEffectInfo 메소드는, 이펙트에 관한 정보를 취득한다.

HRESULT GetEffectInfo(
  LPDIEFFECTINFO pdei,
  REFGUID rguid
);

파라미터

pdei
이펙트의 정보를 받는 DIEFFECTINFO 구조체. 호출측은, 이 메소드를 호출하기 전에, 이 구조체의 dwSize 멤버를 초기화해 두지 않으면 안 된다.
rguid
정보를 요구하는 이펙트의 식별자.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_DEVICENOTREG
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

주의

C++ 에서는,rguid 파라미터는 참조값으로서 건네주지 않으면 안 된다. C 에서는 참조값으로서 건네줄 수가 없기 때문에, 주소로서 건네주지 않으면 안 된다. 다음은, C++ 에서의 호출해 예이다.

lpdev2->GetEffectInfo(&dei, GUID_Effect);

다음은, C 에서의 같은 호출해 예이다.

lpdev2->lpVtbl->GetEffectInfo(lpdev2, &dei, &GUID_Effect);

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputDevice2::GetForceFeedbackState

Platform SDK: DirectX

IDirectInputDevice7::GetForceFeedbackState

IDirectInputDevice7::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 의 어느쪽이나 돌려주어지지 않다.

DirectInput 의 장래의 버젼으로, 플래그가 추가 정의될 가능성도 있다. 어플리케이션은, 현재 미정도리의 플래그를 모두 무시할 필요가 있다.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED
DIERR_UNSUPPORTED

주의

이 메소드를 성공시키려면 , 디바이스를 배타 협조 레벨로 취득해야 한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputDevice2::GetEffectInfo

Platform SDK: DirectX

IDirectInputDevice7::GetObjectInfo

IDirectInputDevice7::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 멤버안에 돌려주어진다. 이 구조체는,IDirectInputDevice7::EnumObjects 메소드에 대하기 이전의 호출로 돌려주어진 것이다.
DIPH_BYUSAGE | dwObj 파라미터는, 오브젝트의 "HID 사용 페이지" 와 "사용 상황" 의 값이다. 이러한 값은 DIMAKEUSAGEDWORD 매크로에 의해 조합할 수 있다.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
DIERR_OBJECTNOTFOUND

주의

DirectX 3 과의 호환성에 대해서는,sizeof(DIDEVICEOBJECTINSTANCE_DX3) 에 초기화한 dwSize 멤버를 포함한 DIDEVICEOBJECTINSTANCE_DX3 구조체를 건네주어도 괜찮다. 상세한 것에 대하여는, 「전의 버젼의 DirectInput 의 설계」를 참조할것.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputDevice7::GetProperty

IDirectInputDevice7::GetProperty 메소드는, 입력 디바이스에 대한 정보를 취득한다.

HRESULT GetProperty(
  REFGUID rguidProp,
  LPDIPROPHEADER pdiph
);

파라미터

rguidProp
취득하는 프로퍼티의 식별자. 이 식별자로서 사전 정의된 값의 1 개, 또는 프로퍼티를 식별하는 GUID 에의 포인터를 사용할 수 있다. 입력 디바이스에 대해서는, 다음의 프로퍼티가 사전 정의되고 있다.
DIPROP_AUTOCENTER
디바이스 오브젝트가 자동 센터링을 실시할지 어떨지를 지정한다. 상세한 것에 대하여는, 「IDirectInputDevice7::SetProperty 」를 참조할것.
DIPROP_AXISMODE
축모드를 취득한다. 취득값 (DIPROPAXISMODE_ABS 또는 DIPROPAXISMODE_REL)은, 할당할 수 있었던 DIPROPDWORD 구조체의 dwData 멤버로 설정된다. 자세한 것은,pdiph 파라미터의 설명을 참조할것.
DIPROP_BUFFERSIZE
입력 버퍼 사이즈를 취득한다. 취득값은, 할당할 수 있었던 DIPROPDWORD 구조체의 dwData 멤버로 설정된다. 자세한 것은,pdiph 파라미터의 설명을 참조할것.

버퍼 사이즈는,IDirectInputDevice7::GetDeviceData 메소드의 전회와 이번 호출동안에서, 버퍼가 데이터를 잃는 일 없이 보관 유지할 수 있는 데이터의 양을 결정한다. 이 값에 제로를 설정해, 어플리케이션이 디바이스로부터 버퍼링 데이터를 읽어들이지 않게 지정할 수도 있다. DIPROPDWORD 구조체의 dwData 멤버중의 버퍼 사이즈가 너무 커 디바이스가 지원 할 수 없으면, 지원 가능한 최대 버퍼 사이즈가 설정된다. 요구한 버퍼 사이즈가 설정되었는지 어떠했는지를 확인하려면 , 버퍼 사이즈 프로퍼티를 취득해, 설정하려고 한 값과 그 결과를 비교한다.

DIPROP_DEADZONE
0 ~ 10,000 의 범위에서 죠이스틱의 무효 존의 값을 취득한다. 여기서, 0 은 무효 존이 존재하지 않는 것, 5,000 은 무효 존이 축을 중심으로 한 물리 범위의 50 퍼센트에까지 퍼지고 있는 것, 및 10,000 은 축의 물리 범위의 전체가 무효라는 점을 각각 가리킨다. 축이 무효 존내에 있으면(자), 축의 범위의 중심에 있는 것이라고 보고된다.
DIPROP_FFGAIN
디바이스의 게인을 취득한다. 상세한 것에 대하여는, 「IDirectInputDevice7::SetProperty 」를 참조할것.
DIPROP_FFLOAD
디바이스의 메모리 로드를 취득한다. 이 설정값은, 개별의 오브젝트는 아니고 디바이스 전체에 적용되므로, 할당할 수 있었던 DIPROPDWORD 구조체의 dwHow 멤버는 DIPH_DEVICE 가 아니면 안된다.

dwData 멤버는, 0~100 의 범위에 있는 값을 저장 한다. 이 값은, 사용중의 디바이스 메모리의 퍼센트수를 나타낸다.

DIPROP_GRANULARITY
입력의 세분도를 취득한다. 취득값은, 할당할 수 있었던 DIPROPDWORD 구조체의 dwData 멤버로 설정된다. 자세한 것은 pdiph 파라미터의 설명을 참조할것.

세분도는, 오브젝트가 이동거리를 보고할 때의 최소량을 나타낸다. 많은 축오브젝트의 세분도는 1 이며, 모든 값을 취할 수가 있다. 축으로야는은, 보다 큰 세분도를 가지는 것도 있다. 예를 들어, 마우스의 휠축의 세분도는 20 으로 할 수도 있다. 보고되는 위치 변화는 모두, 20 의 배수가 된다. 즉, 유저가 휠을 천천히 회전시키면(자), 디바이스는 위치를 0, 20, 40 등이라고 보고한다.

이것은 읽기 전용 프로퍼티이다. IDirectInputDevice7::SetProperty 메소드를 호출해도, 값을 설정할 수 없다.

DIPROP_GUIDANDPATH
어플리케이션은, 디바이스의 클래스 GUID 와 디바이스 인터페이스 (패스)에 액세스 할 수 있다. 상세 설정의 가능한 어플리케이션은 이 프로퍼티를 사용하는 것으로, DirectInput 로 지원되어 있지 않은 HID 에 대해서 조작을 실행할 수 있다. 상세한 것에 대하여는,DIPROPGUIDANDPATH 구조체의 레퍼런스를 참조할것.
DIPROP_INSTANCENAME
디바이스의 인스턴스의 등록명을 취득한다. 상세한 것에 대하여는, 「IDirectInputDevice7::SetProperty 」를 참조할것.
DIPROP_PRODUCTNAME
디바이스의 제품의 등록명을 취득한다. 상세한 것에 대하여는, 「IDirectInputDevice7::SetProperty 」를 참조할것.
DIPROP_RANGE
오브젝트를 보고할 수 있는 값의 범위를 취득한다. 취득된 최소 값 및 최대치는, 할당할 수 있었던 DIPROPRANGE 구조체의 lMin 및 lMax 멤버로 설정된다. 자세한 것은 pdiph 파라미터의 설명을 참조할것.

일부의 디바이스에서는, 이것은 읽기 전용 프로퍼티이다. IDirectInputDevice7::SetProperty 메소드를 호출해도, 값을 설정할 수 없다.

DIPROP_SATURATION
0 ~ 10,000 의 범위에서 죠이스틱의포화 존의 값을 취득한다. 포화 레벨이란, 축이 극한 위치에 있다고 보이는 점이다. 예를 들어, 포화 레벨이 9,500 으로 설정되어 있는 경우, 축의 중심 (무효 존)으로부터 축의 구석까지의 물리적 거리의 95% 의 위치가 축의 극한 위치가 된다.
pdiph
멤버로서 DIPROPHEADER 구조체를 가지는 대형 프로퍼티 의존 구조체의,DIPROPHEADER 부분의 주소. 오브젝트의 범위 정보의 취득시에는, 이 값은,DIPROPRANGE 구조체에 포함되는 DIPROPHEADER 구조체의 주소가 된다. 다른 프로퍼티의 경우, 이 값은,DIPROPDWORD 구조체에 포함되는 DIPROPHEADER 구조체의 주소가 된다.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_INVALIDPARAM
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 = IDirectInputDevice7_GetProperty(pdid, DIPROP_BUFFERSIZE, &dipdw.diph);
if (SUCCEEDED(hr)) {
// dipdw.dwData 멤버는 버퍼 사이즈를 저장 한다.
}

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.

참조

IDirectInputDevice7::SetProperty


IDirectInputDevice7::Initialize

IDirectInputDevice7::Initialize 메소드는, DirectInputDevice 오브젝트를 초기화한다. IDirectInput7::CreateDevice 메소드는, 디바이스의 생성 후, 자동적으로 디바이스를 초기화하므로, 어플리케이션은 보통, 이 메소드를 호출할 필요는 없다.

HRESULT Initialize(
  HINSTANCE hinst,
  DWORD dwVersion,
  REFGUID rguid
);

파라미터

hinst
DirectInput 오브젝트를 생성 하는 어플리케이션 또는 DLL 의 인스턴스 핸들. DirectInput 는, 이 값을 사용해, 어플리케이션 또는 DLL 가, 오브젝트 생성의 자격을 인정받고 있는지 어떤지를 판단해, 하위 호환성을 위해서(때문에) 취해야 할 특별한 동작을 확정한다.

DLL 가 부모의 어플리케이션의 핸들을 건네주면(자), 에러가 된다. 예를 들어, Web 페이지에 파묻히고 있는 DirectInput 를 사용하는 ActiveX 컨트롤은, Web 브라우저의 핸들은 아니고, 그것 자신의 인스턴스의 핸들을 건네주지 않으면 안 된다. 이것에 의해, DirectInput 가 그 컨트롤을 인식해, 필요라고 생각되는 특별한 동작을 모두 유효하게 하는 것이 확실히 된다.

dwVersion
어플리케이션의 설계 대상인 DirectInput 의 버젼 번호. 이 값은 보통, DIRECTINPUT_VERSION 이다. 이전의 버젼 번호를 건네주면(자), DirectInput 가 그 버젼을 에뮬레이트 하게 된다. 상세한 것에 대하여는, 「전의 버젼의 DirectInput 의 설계」를 참조할것.
rguid
인터페이스를 관련짓는 디바이스의 인스턴스에 대한 식별자. IDirectInput7::EnumDevices 메소드를 사용하면(자), 시스템이 어느 인스턴스 GUID 를 지원 하고 있는지를 확인할 수가 있다.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_ACQUIRED
DIERR_DEVICENOTREG

S_FALSE 가 돌려주어지면,rGUID 를 개입시켜 건네받은 인스턴스 GUID 를 가지는 디바이스는 초기화가 끝난 상태이다.

주의

이 메소드가 실패하는 경우, 기저의 오브젝트는 부정 상태에 있는 것으로 간주해, 사용전에 재초기화해야 한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputDevice2::Poll

Platform SDK: DirectX

IDirectInputDevice7::Poll

IDirectInputDevice7::Poll 메소드는, DirectInput 디바이스 위에의 폴링 대상 오브젝트로부터 데이터를 취득한다. 디바이스에 폴링이 필요없을 때에 이 메소드를 호출해도, 이펙트는 일절 없다. 폴링 할 필요가 있는 디바이스가 정기적으로 폴링 되지 않는 경우, 이 디바이스로부터 새로운 데이터는 취득되지 않는다. 이 메소드를 호출하면, DirectInput 는 디바이스 상태를 갱신해, 버퍼링 데이터가 사용 가능하면 입력 이벤트를 생성해, 통지가 유효하면 통지 이벤트를 설정한다.

HRESULT Poll()

파라미터

없음.

반환값

성공하면 DI_OK 를 돌려준다. 디바이스가 폴링을 요구하지 않는 경우는 DI_NOEFFECT 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_INPUTLOST
DIERR_NOTACQUIRED
DIERR_NOTINITIALIZED

주의

디바이스 데이터를 폴링 하기 전에,IDirectInputDevice7::SetDataFormat 메소드로 데이터 형식을 설정해,IDirectInputDevice7::Acquire 메소드로 디바이스를 취득해야 한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.

참조

「폴링과 이벤트」


IDirectInputDevice7::RunControlPanel

IDirectInputDevice7::RunControlPanel 메소드는, 이 디바이스에 관련지을 수 있었던 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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputDevice2::SendDeviceData

Platform SDK: DirectX

IDirectInputDevice7::SendDeviceData

IDirectInputDevice7::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

주의

개별의 데이터 요소가 특정의 순서로 송신된다고 하는 보증은 없다. 그러나,IDirectInputDevice7::SendDeviceData 의 호출이 성공했을 경우, 송신된 데이터의 사이에 다른 데이터가 섞여 올 것은 없다. 또, 복수의 데이터가 1 회의 호출로 같은 오브젝트에 송신되는 경우, 어느 데이터가 송신될까는 특정되지 않는다.

예를 들어, 데이터를 패킷 단위로 송신할 수 있는 디바이스가 있어, 각 패킷은, A 및 B 라고 하는 2 개의 정보를 나타낸다고 한다. 여기서, 어플리케이션이 3 개의 데이터 요소 (B = 2, A = 1, B =0)를 송신하려고 하면(자) 어떻게 될까.

실제의 디바이스에 송신되는 패킷은 1 개이다. 패킷의 A 필드의 값은 1, 그리고 패킷의 B 필드의 값은 2 나 0 이 된다.

데이터를 지정대로 디바이스에 송신할 필요가 있는 경우는,IDirectInputDevice7::SendDeviceData 를 3 회 호출해, 호출할 것에 데이터 요소를 1 개씩 송신해야 한다.

최초의 호출해에 응답해, A 필드가 공백, B 필드의 값이 2 의 패킷을 디바이스에 송신한다.

2 번째의 호출에서는, A 필드의 값이 1, B 필드가 공백의 패킷을 송신한다.

마지막 3 번째의 호출로, A 필드가 공백, B 필드의 값이 0 의 패킷을 송신한다.

DISDD_CONTINUE 플래그가 설정되어 있는 경우, 송신된 디바이스 데이터는 이전에 송신된 디바이스 데이터에 덧쓰기된다. 플래그의 설정이 없으면, 송신되는 디바이스 데이터는 완전히 새로운 데이터로서 처리된다.

예를 들어, Button0 및 Button1 의 2 개의 버튼 출력을 지원 하는 디바이스가 있다고 한다. 어플리케이션이 최초로 IDirectInputDevice7::SendDeviceData 를 호출해 "Button0 압하" 를 건네주면(자), 디바이스에는,"Button0 압하, Button1 미압하" 라고 하는 형식의 패킷이 송신된다. 다음에, 어플리케이션이 한번 더 SendDeviceData 를 호출해 "Button1 압하" 와 DISDD_CONTINUE 플래그를 건네주면(자), 디바이스에는,"Button0 압하, Button1 압하" 라고 하는 형식의 패킷이 송신된다. 그러나, 어플리케이션이 DISDD_CONTINUE 플래그를 건네주지 않았던 경우, 디바이스에 송신되는 패킷은,"Button0 미압하 , Button1 압하" 가 된다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputDevice2::SendForceFeedbackCom

Platform SDK: DirectX

IDirectInputDevice7::SendForceFeedbackCommand

IDirectInputDevice7::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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputDevice7::SetCooperativeLevel

IDirectInputDevice7::SetCooperativeLevel 메소드는, 디바이스의 인스턴스에 대한 협조 레벨을 확립한다. 협조 레벨은, 이 인스턴스가, 같은 디바이스외의 인스턴스, 및 시스템의 이외의 부분과의 사이로, 어떻게 대화할까를 결정한다.

HRESULT SetCooperativeLevel(
  HWND hwnd,
  DWORD dwFlags
);

파라미터

hwnd
디바이스에 관련지을 수 있고 있는 윈도우 핸들. 이 파라미터는, 이 프로세스에 속하는 최상정도의 유효한 윈도우 핸들이 아니면 안된다. 디바이스에 관련지을 수 있었던 윈도우는, DirectInput 디바이스 중(안)에서 액티브한 사이는, 파괴해서는 안 된다.
dwFlags
디바이스에 관련짓는 협조 레벨을 나타내는 플래그. 다음의 플래그가 정의되고 있다.
DISCL_BACKGROUND
어플리케이션은, 백그라운드 액세스권을 요구한다. 백그라운드 액세스권이 허가되면(자), 할당할 수 있었던 윈도우가 액티브 윈도우가 아닌 경우에서도, 언제라도 디바이스를 취득할 수 있다.
DISCL_EXCLUSIVE
어플리케이션은, 배타 액세스권을 요구한다. 배타 액세스권이 부여되면(자), 디바이스가 취득되고 있는 동안, 디바이스외의 인스턴스는, 그 디바이스의 배타 액세스권을 취득할 수 없다. 다만, 다른 어플리케이션이 배타 액세스권을 취득하고 있는 경우에서도, 디바이스의 비배타 액세스권은 항상 인정된다.

어플리케이션이 마우스 또는 키보드 디바이스를 배타 모드로 취득하고 있는 경우는, WM_ENTERSIZEMOVE 메세지 및 WM_ENTERMENULOOP 메세지를 받아들이면(자), 항상 디바이스를 릴리즈 할 필요가 있다. 그 이외의 경우, 유저는 메뉴를 조작하거나 윈도우를 이동 또는 윈도우의 사이즈를 변경하거나 할 수 없다.

DISCL_FOREGROUND
어플리케이션은 foreground 액세스권을 요구한다. foreground 액세스권이 부여되면(자), 할당할 수 있었던 윈도우가 백그라운드로 이동할 때, 디바이스는 자동적으로 릴리즈 된다.
DISCL_NONEXCLUSIVE
어플리케이션은 비배타 액세스권을 요구한다. 디바이스에 대한 액세스권은, 같은 디바이스에 액세스 하고 있는 것 외의 어플리케이션의 방해가 되지 않는다.
DISCL_NOWINKEY
Windows 키를 무효로 한다. 이 플래그를 설정 하면, 유저는 잘못해 어플리케이션을 종료하는 것이 없어진다.

어플리케이션은, DISCL_FOREGROUND 또는 DISCL_BACKGROUND 의 어느 쪽인지 한편을 지정해야 한다. 양쪽 모두 지정하는 일도, 전혀 지정하지 않는 것도 에러가 된다. 같이 어플리케이션은, DISCL_EXCLUSIVE 또는 DISCL_NONEXCLUSIVE 의 어느 쪽인지 한편을 지정해야 한다.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED
E_HANDLE

주의

시스템 마우스가 배타 모드로 취득되면(자), 마우스 포인터는, 디바이스가 릴리즈 될 때까지 화면으로부터 소거된다.

어플리케이션은,IDirectInputDevice7::Acquire 메소드로 디바이스를 취득하기 전에, 이 메소드를 호출하지 않으면 안 된다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.

참조

「협조 레벨」


IDirectInputDevice7::SetDataFormat

IDirectInputDevice7::SetDataFormat 메소드는, 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

주의

IDirectInputDevice7::Acquire 로 디바이스를 취득하기 전에, 데이터 형식을 설정해 두지 않으면 안 된다. 데이터 형식은, 한 번 설정하는 것만으로 좋다. 데이터 형식은, 디바이스가 취득되고 있는 동안은 변경할 수 없다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.

참조

IDirectInputDevice7::GetDeviceState


IDirectInputDevice7::SetEventNotification

IDirectInputDevice7::SetEventNotification 메소드는, 이벤트 통지 스테이터스를 설정한다. 이 메소드는, 디바이스 상태가 변화했을 때에 설정되는 이벤트를 지정한다. 이벤트 통지를 오프로 하기 위해서(때문에)도 사용된다.

HRESULT SetEventNotification(
  HANDLE hEvent
);

파라미터

hEvent
디바이스 상태가 변화했을 때에 설정되는 이벤트의 핸들. DirectInput 는 디바이스 상태가 변화했을 때에, 이 핸들에 대해서 Win32 SetEvent 함수를 사용한다. hEvent 파라미터를 NULL 로 하면(자), 통지는 무효가 된다.

어플리케이션은, 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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.

참조

「폴링과 이벤트」


IDirectInputDevice7::SetProperty

IDirectInputDevice7::SetProperty 메소드는, 디바이스의 동작을 정의하는 프로퍼티를 설정한다. 이러한 프로퍼티에는, 입력 버퍼 사이즈나 축모드등이 있다.

HRESULT SetProperty(
  REFGUID rguidProp,
  LPCDIPROPHEADER pdiph
);

파라미터

rguidProp
설정 대상의 프로퍼티의 식별자. 이 식별자는, 사전 정의된 값의 1 개에서도, 또는 프로퍼티를 식별하는 GUID 에의 포인터라도 좋다. 이하의 프로퍼티값이 입력 디바이스에 대해서 사전 정의되고 있다.
DIPROP_AUTOCENTER
디바이스 오브젝트가 자동 센터링을 실시할지 어떨지를 지정한다. 이 설정값은, 개별의 오브젝트는 아니고 디바이스 전체에 적용되므로, 할당할 수 있었던 DIPROPDWORD 구조체의 dwHow 멤버는, DIPH_DEVICE 가 아니면 안된다.

dwData 멤버는, 다음의 어느쪽이든 1 개의 값을 취할 수가 있다.

DIPROPAUTOCENTER_OFF:유저가 디바이스를 떼어 놓아도, 자동적으로 센터링을 실시하지 않는다. force feedback를 사용하는 어플리케이션은, 이펙트의 재생전에 자동 센터링의 스프링을 무효로 할 필요가 있다.

DIPROPAUTOCENTER_ON:유저가 디바이스를 떼어 놓으면(자), 자동적으로 센터링을 실시한다. 예를 들어, 이 모드의 죠이스틱은, 자동 센터링의 스프링이 유효하게 된다.

force feedback 이펙트를 사용 하면, 자동 센터링의 스프링에 영향을 주는 경우가 있다. 일부의 디바이스에서는, force feedback 이펙트를 재생할 경우에, 자동 센터링 스프링을 무효로 한다.

자동 센터링 기능을 지원 하고 있지 않는 디바이스도 있다.

DIPROP_AXISMODE
축모드를 설정한다. 설정값 (DIPROPAXISMODE_ABS 또는 DIPROPAXISMODE_REL) 은, 할당할 수 있었던 DIPROPDWORD 구조체의 dwData 멤버로 지정하지 않으면 안 된다. 자세한 것은 pdiph 파라미터의 설명을 참조할것.

이 설정값은 디바이스 전체에 적용되므로, 할당할 수 있었던 DIPROPDWORD 구조체의 dwHow 멤버는, DIPH_DEVICE 가 아니면 안된다.

DIPROP_BUFFERSIZE
입력 버퍼 사이즈를 설정한다. 설정값은, 할당할 수 있었던 DIPROPDWORD 구조체의 dwData 멤버로 지정하지 않으면 안 된다. 자세한 것은 pdiph 파라미터의 설명을 참조할것.

이 설정값은 디바이스 전체에 적용되므로, 할당할 수 있었던 DIPROPDWORD 구조체의 dwHow 멤버는, DIPH_DEVICE 가 아니면 안된다

DIPROP_CALIBRATIONMODE
DirectInput 가 취득하는 데이터가, calibration가 끝난 상태나 calibration전인지를, 어플리케이션을 지정할 수 있도록(듯이) 한다. 디폴트에서는, DirectInput 는 calibration가 끝난 데이터를 취득한다.

디바이스 전체에 대해서 calibration 모드를 설정하는 것은, 각각의 축으로 대해 calibration 모드를 설정하는 것으로 같은 의미를 가진다.

DIPROPDWORD 구조체의 dwData 멤버는 다음의 어느쪽이든 1 개의 값을 취할 수가 있다.

DIPROPCALIBRATIONMODE_COOKED:DirectInput 는, calibration 정보의 적용 후의 데이터를 돌려준다. 이것이 디폴트 모드이다.

DIPROPCALIBRATIONMODE_RAW:DirectInput 는, calibration전의 미가공 데이터를 돌려준다. 이 모드는 보통, 컨트롤 패널형의 어플리케이션에서만 사용된다.

디바이스를 미가공 모드로 설정 하면, 무효 존, 포화값, 및 범위의 설정이 무시된다.

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

주의

버퍼 사이즈는,IDirectInputDevice7::GetDeviceData 메소드의 전회와 이번 호출동안에서, 버퍼가 데이터를 잃는 일 없이 보관 유지할 수 있는 데이터의 양을 결정한다. 이 값에 제로를 설정해, 어플리케이션이 디바이스로부터 버퍼링 데이터를 읽어들이지 않게 지정할 수도 있다. DIPROPDWORD 구조체의 dwData 멤버중의 버퍼 사이즈가 너무 커 디바이스가 지원 할 수 없는 경우는, 지원 가능한 최대 버퍼 사이즈가 설정된다. 요구한 버퍼 사이즈가 설정되었는지 어떠했는지를 확인하려면 , 버퍼 사이즈 프로퍼티를 취득해, 설정하려고 한 값과 그 결과를 비교한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.

참조

IDirectInputDevice7::GetProperty


IDirectInputDevice7::Unacquire

IDirectInputDevice7::Unacquire 메소드는, 디바이스에의 액세스권을 릴리즈 한다.

HRESULT Unacquire();

파라미터

없음.

반환값

디바이스가 릴리즈 되었을 경우는 DI_OK 를 돌려주어, 디바이스가 취득 상태에 없었던 경우는 DI_NOEFFECT 를 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputDevice7::WriteEffectToFile

IDirectInputDevice7::WriteEffectToFile 메소드는, 1 개(살) 이상의 force feedback 이펙트에 대한 정보를 파일에 보존한다. 이 파일은,IDirectInputDevice7::EnumEffectsInFile 를 사용해 읽어낼 수가 있다. 이것은 주로, 독자적인 포스를 생성하는 어플리케이션을 생성 하고 싶은 개발자전용의 메소드이다.

HRESULT WriteEffectToFile(
  LPCSTR lpszFileName,
  DWORD dwEntries,
  LPCDIFILEEFFECT rgDiFileEft,
  DWORD dwFlags
);

파라미터

lpszFileName
RIFF 파일의 이름.
dwEntries
rgDiFileEft 배열중의 구조체의 수.
rgDiFileEft
DIFILEEFFECT 구조체의 배열.
dwFlags
이펙트의 기술 방법을 제어하는 플래그. DIFEF_DEFAULT (= 0) 또는 다음의 값을 취할 수가 있다.
DIFEF_INCLUDENONSTANDARD
DirectInput 로 정의되어 있지 않은 이펙트를 포함한다. 이 플래그가 지정되지 않는 경우는, GUID_ConstantForce 등, Dinput.h 에 정의된 GUID 를 가지는 이펙트만이 기술된다.

반환값

메소드가 성공하면 DI_OK 를 돌려준다.

실패하면 DIERR_INVALIDPARAM 를 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.

참조

IDirectInputDevice7::EnumEffectsInFile


IDirectInputEffect

어플리케이션은,IDirectInputEffect 인터페이스의 메소드를 사용해, force feedback 디바이스의 이펙트를 관리한다.

이 인터페이스는 IDirectInputDevice7::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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputEffect::Download

IDirectinputEffect::Download 메소드는, 디바이스에 이펙트를 설정한다. 같은 이펙트가 이미 디바이스에 있으면,IDirectInputEffect::SetParameters 메소드로 설정된 값에 적합하도록(듯이), 기존의 이펙트가 갱신된다.

HRESULT Download(void);

파라미터

없음.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_NOTINITIALIZED
DIERR_DEVICEFULL
DIERR_INCOMPLETEEFFECT
DIERR_INPUTLOST
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_INVALIDPARAM
DIERR_EFFECTPLAYING

S_FALSE 가 돌려주어졌을 경우, 그 이펙트는 이미 디바이스에 다운로드되고 있다.

주의

이펙트의 재생중에 이펙트를 갱신하는 것은 유효하다. 이 조작의 의미는,IDirectInputEffect::SetParameters 의 레퍼런스 중(안)에서 설명되고 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputEffect::Escape

IDirectInputEffect::Escape 메소드는, 하드웨어 고유의 커멘드를 드라이버에 송신한다.

HRESULT Escape(
  LPDIEFFESCAPE pesc
);

파라미터

pesc
송신하는 커멘드를 기술하는 DIEFFESCAPE 구조체. 성공하면(자), 사용된 출력 버퍼의 바이트수가 cbOutBuffer 멤버에 저장 된다.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_NOTINITIALIZED
DIERR_DEVICEFULL

다른 디바이스 고유 에러 코드를 돌려줄 수도 있다. 하드웨어 메이커로부터 상세 정보를 입수하는 것.

주의

각 드라이버는, 다른 escape sequence를 이행 하고 있으므로, 올바른 드라이버와 통신하고 있을지 어떨지는, 어플리케이션 자체가 확인해야 한다. 이것은,DIDEVICEINSTANCE 구조체의 guidFFDriver 멤버와 어플리케이션이 기대하고 있는 값을 비교하는 것으로써 확인할 수 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputEffect::GetEffectGuid

IDirectInputEffect::GetEffectGuid 메소드는,IDirectInputEffect 오브젝트가 나타내는 이펙트의 GUID 를 취득한다.

HRESULT GetEffectGuid(
  LPGUID pguid
);

파라미터

pguid
이 메소드에 의해 저장 되는 GUID 구조체.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

주의

취득한 GUID 를 IDirectInputDevice7::GetEffectInfo 에 건네주는 것으로, 그 이펙트에 관한 확장 정보를 취득할 수 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputEffect::GetEffectStatus

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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputEffect::GetParameters

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 개(살)이 설정되어 있지 않으면 안 된다. 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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputEffect::Initialize

IDirectInputEffect::Initialize 메소드는, DirectInputEffect 오브젝트를 초기화한다.

HRESULT Initialize(
  HINSTANCE hinst,
  DWORD dwVersion,
  REFGUID rguid
);

파라미터

hinst
DirectInputEffect 오브젝트를 생성 하는 어플리케이션 또는 DLL 의 인스턴스 핸들. DirectInput 는, 이 값을 사용해, 어플리케이션 또는 DLL 가, 오브젝트 생성의 자격을 인정받고 있는지 어떤지를 판단해, 하위 호환성을 위해서(때문에) 취해야 할 특별한 동작을 확정한다. DLL 가 부모의 어플리케이션의 핸들을 건네주면(자), 에러가 된다.
dwVersion
어플리케이션의 설계 대상인 DirectInput 의 버젼 번호. 이 값은 보통, DIRECTINPUT_VERSION 이다. 이전의 버젼 번호를 건네주면(자), DirectInput 가 그 버젼을 에뮬레이트 하게 된다. 상세한 것에 대하여는, 「전의 버젼의 DirectInput 의 설계」를 참조할것.
rguid
인터페이스를 관련지을 수 있고 있는 이펙트의 식별자. IDirectInputDevice7::EnumEffects 메소드를 사용해, 디바이스가 어느 이펙트 GUID 를 지원 하고 있는지를 확인할 수 있다.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 DIERR_DEVICENOTREG 를 돌려준다.

주의

이 메소드가 실패하는 경우, 기저의 오브젝트는 부정 상태에 있는 것으로 간주해지므로, 다시 초기화하지 않으면 이후의 사용은 할 수 없다.

IDirectInputDevice7::CreateEffect 메소드는, 이펙트를 생성 후, 자동적으로 초기화한다. 어플리케이션은, 보통,Initialize 메소드를 호출할 필요는 없다.

C++ 에서는,rguid 파라미터는 참조값으로서 건네주지 않으면 안 된다. C 에서는 참조값으로서 건네줄 수가 없기 때문에, 주소로서 건네주지 않으면 안 된다. 다음은, C++ 에서의 호출해 예이다.

lpeff->Initialize(g_hinstDll, DIRECTINPUT_VERSION, GUID_Effect);

다음은, C 에서의 같은 호출해 예이다.

lpeff->lpVtbl->Initialize(lpeff, g_hinstDll,
                          DIRECTINPUT_VERSION, &GUID_Effect);

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputEffect::SetParameters

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
dwTriggerButton 멤버가 데이터를 저장 한다.
DIEP_TRIGGERBUTTON
dwTriggerButton 멤버가 데이터를 저장 한다.
DIEP_TRIGGERDELAY
dwTriggerDelay 멤버가 데이터를 저장 한다.
DIEP_TRIGGERREPEATINTERVAL
dwTriggerRepeatInterval 멤버가 데이터를 저장 한다.
DIEP_TYPESPECIFICPARAMS
DIEFFECT 구조체의 lpTypeSpecificParams 및 cbTypeSpecificParams 멤버가 이펙트의 타입 고유 데이터의 주소와 사이즈를 저장 한다.

반환값

성공하면 다음의 값의 어느쪽이든을 돌려준다.

DI_OK
DI_EFFECTRESTARTED
DI_DOWNLOADSKIPPED
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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputEffect::Start

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_INVALIDPARAM
DIERR_INCOMPLETEEFFECT
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED
DIERR_UNSUPPORTED

주의

이 메소드를 성공시키려면 , 디바이스를 배타 협조 레벨로 취득해야 한다.

여러 차례의 반복을 지원 하지 않는 디바이스도 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputEffect::Stop

IDirectInputEffect::Stop 메소드는, 이펙트의 재생을 정지한다.

HRESULT Stop(void);

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED

주의

이 메소드를 성공시키려면 , 디바이스를 배타 협조 레벨로 취득해야 한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


IDirectInputEffect::Unload

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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


함수

여기에서는, COM 인터페이스 메소드 이외의 DirectInput 함수 및 콜백 함수의 레퍼런스를 제공한다.

이 카테고리에는 다음의 함수가 분류된다.

  • DirectInputCreate 는, DirectInput 시스템을 생성 해,IDirectInput 인터페이스를 취득하는데 사용된다. 이 함수는 계속해 지원 되지만,DirectInputCreateEx 에 인계되고 있다.
  • DirectInputCreateEx 는, DirectInput 시스템을 생성 해,IDirectInput, ,IDirectInput2, 또는 IDirectInput7 인터페이스를 취득하는데 사용된다.


DirectInputCreate

DirectInputCreate 함수는,IDirectInput COM 인터페이스를 지원 하는 DirectInput 오브젝트를 생성 한다.

HRESULT WINAPI DirectInputCreate(
  HINSTANCE hinst,
  DWORD dwVersion,
  LPDIRECTINPUT * lplpDirectInput,
  LPUNKNOWN punkOuter
);

파라미터

hinst
DirectInput 오브젝트를 생성 하는 어플리케이션 또는 DLL 의 인스턴스 핸들. DirectInput 는, 이 값을 사용해, 어플리케이션 또는 DLL 가, 오브젝트 생성의 자격을 인정받고 있는지 어떤지를 판단해, 하위 호환성을 위해서(때문에) 취해야 할 특별한 동작을 확정한다.

DLL 가 부모의 어플리케이션의 핸들을 건네주면(자), 에러가 된다. 예를 들어, Web 페이지에 파묻히고 있는 DirectInput 를 사용하는 ActiveX 컨트롤은, Web 브라우저의 핸들은 아니고, 그것 자신의 인스턴스의 핸들을 건네주지 않으면 안 된다. 이것에 의해, DirectInput 가 그 컨트롤을 인식해, 필요라고 생각되는 특별한 동작을 모두 유효하게 하는 것이 확실히 된다.

dwVersion
어플리케이션의 설계 대상인 DirectInput 의 버젼 번호. 이 값은 보통, DIRECTINPUT_VERSION 이다. 이전의 버젼 번호를 건네주면(자), DirectInput 가 그 버젼을 에뮬레이트 하게 된다. 상세한 것에 대하여는, 「전의 버젼의 DirectInput 의 설계」를 참조할것.
lplpDirectInput
호출이 성공했을 경우에 IDirectInput 인터페이스 포인터를 받는 변수의 주소.
punkOuter
COM 집합화에 대한 제어 오브젝트의 IUnknown 인터페이스의 주소에의 포인터. 인터페이스가 집합화되어 있지 않은 경우에는 NULL. 보통, 호출측은 NULL 를 건네준다. 집합화가 요구되었을 경우,*lplpDirectInput 에 돌려주어지는 오브젝트는, COM 집합화가 요구하도록(듯이),IDirectInput 인터페이스는 아니고 IUnknown 에의 포인터이다.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_BETADIRECTINPUTVERSION
DIERR_INVALIDPARAM
DIERR_OLDDIRECTINPUTVERSION
DIERR_OUTOFMEMORY

주의

이 함수는,DirectInputCreateEx 에 인계되고 있다. 새로운 함수는, DirectInput 오브젝트의 기존의 인터페이스를 취득할 수 있다. 새로운 함수를 사용해, 보다 기능의 풍부한 IDirectInput7 인터페이스를 취득하는 것을 추천 한다.

punkOuter = NULL 를 지정해 이 함수를 호출하는 것은,CoCreateInstance(&CLSID_DirectInput, punkOuter, CLSCTX_INPROC_SERVER, &IID_IDirectInput, lplpDirectInput)를 사용해 오브젝트를 생성 한 후,Initialize 로 초기화하는 것으로 동등하다.

punkOuter ! = NULL 를 지정해 이 함수를 호출하는 것은,CoCreateInstance(&CLSID_DirectInput, punkOuter, CLSCTX_INPROC_SERVER, &IID_IUnknown, lplpDirectInput)를 사용해 오브젝트를 생성 하는 것으로 동등하다. 집합화한 오브젝트는 수동으로 초기화해야 한다.

이 서비스는, ANSI 와 Unicode 의 버젼으로 나누어져 있다. ANSI 버젼은,IDirectInputA 인터페이스를 지원 하는 오브젝트를 생성 해, Unicode 버젼은 IDirectInputW 인터페이스를 지원 하는 오브젝트를 생성 한다. 캐릭터 세트의 문제를 엄밀하게 구별하는 그 외의 시스템 서비스와 같게, 헤더 파일내의 매크로는,DirectInputCreate 를 적절한 캐릭터 세트에 맵 한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


DirectInputCreateEx

DirectInputCreateEx 함수는,IDirectInput,IDirectInput2, 또는 IDirectInput7 COM 인터페이스를 지원 하는 DirectInput 오브젝트를 생성 한다.

HRESULT WINAPI DirectInputCreateEx(
  HINSTANCE hinst,
  DWORD dwVersion,
  REFIID riidltf,
  LPVOID * ppvOut,
  LPUNKNOWN punkOuter
);

파라미터

상세한 것에 대하여는, 「전의 버젼의 DirectInput 의 설계」를 참조할것.
riidltf
목적의 DirectInput 인터페이스의 일의인 식별자. 지원 되는 값은, IID_IDirectInput, IID_IDirectInput2, 및 IID_IDirectInput7 이다. 컴파일시에 UNICODE 가 정의되고 있는 경우, 인터페이스의 Unicode 판이 돌려주어진다. 그 이외의 경우는, ANSI 판의 인터페이스가 돌려주어진다.
ppvOut
콜의 성공시에 인터페이스 포인터를 받는 변수의 주소.
punkOuter
COM 집합화에 대한 제어 오브젝트의 IUnknown 인터페이스의 주소에의 포인터. 인터페이스가 집합화되어 있지 않은 경우에는 NULL. 보통, 호출측은 NULL 를 건네준다. 집합화가 요구되었을 경우,*ppvOut 에 돌려주어지는 오브젝트는, COM 집합화가 요구하도록(듯이),IDirectInput 인터페이스는 아니고 IUnknown 에의 포인터이다.

반환값

성공하면 DI_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DIERR_BETADIRECTINPUTVERSION
DIERR_INVALIDPARAM
DIERR_OLDDIRECTINPUTVERSION
DIERR_OUTOFMEMORY

주의

punkOuter = NULL 를 지정해 이 함수를 호출하는 것은,CoCreateInstance(&CLSID_DirectInput, punkOuter, CLSCTX_INPROC_SERVER, &IID_IDirectInput7W, lplpDirectInput)를 사용해 오브젝트를 생성 한 후,IDirectInput7::Initialize 로 초기화하는 것으로 동등하다.

punkOuter ! = NULL 를 지정해 이 함수를 호출하는 것은,CoCreateInstance(&CLSID_DirectInput, punkOuter, CLSCTX_INPROC_SERVER, &IID_IUnknown, lplpDirectInput)를 사용해 오브젝트를 생성 하는 것으로 동등하다. 집합화한 오브젝트는 수동으로 초기화해야 한다.

이 서비스는, ANSI 와 Unicode 의 버젼으로 나누어져 있다. ANSI 버젼은,IDirectInputA 인터페이스를 지원 하는 오브젝트를 생성 해, Unicode 버젼은 IDirectInputW 인터페이스를 지원 하는 오브젝트를 생성 한다. 캐릭터 세트의 문제에 민감한 다른 시스템 서비스와 같게, 헤더 파일내의 매크로는,DirectInputCreateEx 를 적절한 캐릭터 세트에 맵 한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : dinput.lib 를 사용.


콜백 함수

다음의 4 개의 함수는, prototype의 콜백 함수이며, 다양한 열거 메소드와 함께 사용한다. 어플리케이션에서는 이러한 콜백 함수의 1 개를 선언할 수 있다. 그 때, 함수의 이름, 정의 방법은 임의로 좋지만, 파라미터의 타입과 반환값의 타입은, prototype내에서 같지 않으면 안 된다.

  • DIEnumCreatedEffectObjectsCallback
  • DIEnumDeviceObjectsCallback
  • DIEnumDevicesCallback
  • DIEnumEffectsCallback
  • DIEnumEffectsInFileCallback


DIEnumCreatedEffectObjectsCallback

DIEnumCreatedEffectObjectsCallback 함수는,IDirectInputDevice7::EnumCreatedEffectObjects 메소드에 대한 호출 결과적으로 DirectInputDevice 이펙트를 받는, 어플리케이션 정의 콜백 함수이다.

BOOL CALLBACK DIEnumCreatedEffectObjectsCallback(
  LPDIRECTINPUTEFFECT peff,
  LPVOID pvRef
);

파라미터

peff
생성 된 이펙트 오브젝트에의 포인터.
pvRef
IDirectInputDevice7::EnumCreatedEffectObjects 메소드로 지정되는 어플리케이션 정의값.

반환값

열거를 속행하는 DIENUM_CONTINUE 를 돌려주는지, 열거를 정지하는 DIENUM_STOP 를 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : 유저 정의.


DIEnumDeviceObjectsCallback

DIEnumDeviceObjectsCallback 함수는,IDirectInputDevice7::EnumObjects 메소드에 대한 호출 결과적으로 DirectInputDevice 오브젝트를 받는, 어플리케이션 정의 콜백 함수이다.

BOOL CALLBACK DIEnumDeviceObjectsCallback(
  LPCDIDEVICEOBJECTINSTANCE lpddoi,
  LPVOID pvRef
);

파라미터

lpddoi
열거 대상의 오브젝트를 기술하는 DIDEVICEOBJECTINSTANCE 구조체.
pvRef
EnumObjects 메소드로 지정되는 어플리케이션 정의값.

반환값

열거를 속행하는 DIENUM_CONTINUE 를 돌려주는지, 열거를 정지하는 DIENUM_STOP 를 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : 유저 정의.


DIEnumDevicesCallback

DIEnumDevicesCallback 함수는,IDirectInput7::EnumDevices 메소드에 대한 호출 결과적으로 DirectInput 디바이스를 받는, 어플리케이션 정의 콜백 함수이다.

BOOL CALLBACK DIEnumDevicesCallback(
  LPCDIDEVICEINSTANCE lpddi,
  LPVOID pvRef
);

파라미터

lpddi
디바이스 인스턴스를 기술하는 DIDEVICEINSTANCE 구조체의 주소.
pvRef
EnumDevices 메소드로 지정되는 어플리케이션 정의값.

반환값

열거를 속행하는 DIENUM_CONTINUE 를 돌려주는지, 열거를 정지하는 DIENUM_STOP 를 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : 유저 정의.


DIEnumEffectsCallback

DIEnumEffectsCallback 함수는,IDirectInputDevice7::EnumEffects 메소드와 함께 사용하는 어플리케이션 정의 콜백 함수이다.

BOOL CALLBACK DIEnumEffectsCallback(
  LPCDIEFFECTINFO pdei,
  LPVOID pvRef
);

파라미터

pdei
열거된 이펙트를 기술하는 DIEFFECTINFO 구조체.
pvRef
EnumEffects 메소드로 지정되는 어플리케이션 정의 데이터의 주소.

반환값

열거를 속행하는 DIENUM_CONTINUE 를 돌려주는지, 열거를 정지하는 DIENUM_STOP 를 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : 유저 정의.


DIEnumEffectsInFileCallback

DIEnumEffectsInFileCallback 함수는,IDirectInputDevice7::EnumEffectsInFile 메소드와 함께 사용하는 어플리케이션 정의 콜백 함수이다.

BOOL CALLBACK DIEnumEffectsInFileCallback(
  LPCDIFILEEFFECT lpDiFileEf,
  LPVOID pvRef
);

파라미터

lpDiFileEf
열거된 이펙트를 기술하는 DIFILEEFFECT 구조체.
pvRef
EnumEffectsInFile 메소드로 지정되는 어플리케이션 정의 데이터의 주소.

반환값

열거를 속행하는 DIENUM_CONTINUE 를 돌려주는지, 열거를 정지하는 DIENUM_STOP 를 돌려준다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.
임포트 라이브러리 : 유저 정의.


매크로

여기에서는, DirectInput 로 사용되고 있는 이하의 매크로를 설명한다.

  • DIDFT_GETINSTANCE
  • DIDFT_GETTYPE
  • DIDFT_MAKEINSTANCE
  • DIEFT_GETTYPE
  • DIMAKEUSAGEDWORD
  • DISEQUENCE_COMPARE
  • GET_DIDEVICE_SUBTYPE
  • GET_DIDEVICE_TYPE

Dinput.h 는,IDirectInput 및 IDirectInputDevice 양인터페이스의 모든 메소드에 대한 C 의 호출의 매크로도 정의한다. 이러한 매크로를 사용하는 것으로, 메소드 테이블에의 포인터가 불필요하게 된다. 예를 들어, 이하는,IDirectInputDevice7::Release 메소드에 대한 C 에 의한 호출의 예이다.

lpdid->lpVtbl->Release(lpdid));

동등의 매크로 호출은, 이하와 같은 형식이 된다.

IDirectInputDevice7_Release(lpdid);

이러한 매크로는 모두, 메소드 호출의 경우와 동일한 파라미터를 취한다.


DIDFT_GETINSTANCE

DIDFT_GETINSTANCE 매크로는, 데이터 형식 타입으로부터 오브젝트의 인스턴스 번호 코드를 추출한다.

DIDFT_GETINSTANCE(n) LOWORD((n) >> 8)

파라미터

n
DirectInput 데이터 형식 타입. 이 파라미터가 취할 수가 있는 값은,DIOBJECTDATAFORMAT 구조체의 dwType 멤버의 값과 같다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.

참조

DIDFT_MAKEINSTANCE ,DIDFT_GETTYPE


DIDFT_GETTYPE

DIDFT_GETTYPE 매크로는, 데이터 형식 타입으로부터 오브젝트 타입 코드를 추출한다.

DIDFT_GETTYPE(n)  LOBYTE(n)

파라미터

n
DirectInput 데이터 형식 타입. 이 파라미터가 취할 수가 있는 값은,DIOBJECTDATAFORMAT 구조체의 dwType 멤버의 값과 같다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. 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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.

참조

DIDFT_GETINSTANCE


DIEFT_GETTYPE

DIDFT_GETTYPE 매크로는, 데이터 형식 타입으로부터 오브젝트 타입 코드를 추출한다.

DIEFT_GETTYPE(n)  LOBYTE(n)

파라미터

n
DirectInput 이펙트 형식 타입. 이 파라미터가 취할 수가 있는 값은,DIEFFECTINFO 구조체의 dwEffType 멤버의 값과 같다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.


DIMAKEUSAGEDWORD

DIMAKEUSAGEDWORD 매크로는, 디바이스 오브젝트에 대한 HID 코드의 "사용 페이지" 와 "사용 상황" 을 조합해,IDirectInputDevice7::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 : Requires Windows 98.
Header:dinput.h 로 선언.


DISEQUENCE_COMPARE

DISEQUENCE_COMPARE 매크로는, 2 개의 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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.


GET_DIDEVICE_SUBTYPE

GET_DIDEVICE_SUBTYPE 매크로는, 디바이스 타입 기술 코드로부터 디바이스 서브 타입 코드를 추출한다.

GET_DIDEVICE_SUBTYPE(dwDevType)  HIBYTE(dwDevType)

파라미터

dwDevType
DirectInput 디바이스 타입 기술 코드. 이 파라미터가 취할 수가 있는 값은,DIDEVICEINSTANCE 구조체의 dwDevType 멤버의 값과 같다.

주의

서브 타입 코드의 해석은, 프라이머리 타입에 의해 바뀐다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.

참조

GET_DIDEVICE_TYPE ,DIDEVICEINSTANCE


GET_DIDEVICE_TYPE

GET_DIDEVICE_TYPE 매크로는, 디바이스 타입 기술 코드로부터 디바이스의 프라이머리 타입 코드를 추출한다.

GET_DIDEVICE_TYPE(dwDevType)  LOBYTE(dwDevType)

파라미터

dwDevType
DirectInput 디바이스 타입 기술 코드. 이 파라미터가 취할 수가 있는 값은,DIDEVICEINSTANCE 구조체의 dwDevType 멤버의 값과 같다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.

참조

GET_DIDEVICE_SUBTYPE ,DIDEVICEINSTANCE


구조체

여기에서는, 이하의 DirectInput 구조체를 설명한다.

  • DICONDITION
  • DICONSTANTFORCE
  • DICUSTOMFORCE
  • DIDATAFORMAT
  • DIDEVCAPS
  • DIDEVICEINSTANCE
  • DIDEVICEOBJECTDATA
  • DIDEVICEOBJECTINSTANCE
  • DIEFFECT
  • DIEFFECTINFO
  • DIEFFESCAPE
  • DIENVELOPE
  • DIFILEEFFECT
  • DIJOYSTATE
  • DIJOYSTATE2
  • DIMOUSESTATE
  • DIMOUSESTATE2
  • DIOBJECTDATAFORMAT
  • DIPERIODIC
  • DIPROPDWORD
  • DIPROPGUIDANDPATH
  • DIPROPHEADER
  • DIPROPRANGE
  • DIPROPSTRING
  • DIRAMPFORCE

주 : 사용전에 모든 DirectX 구조체의 메모리는, 제로에 초기화되지 않으면 안 된다. 또,dwSize 멤버를 포함한 모든 구조체는, 사용전에 dwSize 멤버를 그 구조체의 사이즈로 설정할 필요가 있다. 다음의 예는,DIDEVCAPS 구조체의 동작을 설명하고 있다.

DIDEVCAPS didevcaps; // 이것은 아직 사용할 수 없다.

ZeroMemory(&didevcaps, sizeof(didevcaps));
didevcaps.dwSize = sizeof(didevcaps);

// 이것으로 구조체를 사용할 수 있다.
.
.


DICONDITION

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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.


DICONSTANTFORCE

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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.


DICUSTOMFORCE

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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.


DIDATAFORMAT

DIDATAFORMAT 구조체는, 디바이스의 데이터 형식을 기술하는 정보를 저장 한다. 이 구조체는,IDirectInputDevice7::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
축은 절대 모드에 있다. 데이터 형식에 이 플래그를 설정하는 것은,IDirectInputDevice7::SetProperty 메소드를 사용해 축모드 프로퍼티를 수동으로 설정하는 것에 동일하다. 이 값은, DIDF_RELAXIS 플래그와 조합할 수 없다.
DIDF_RELAXIS
축은 상대 모드에 있다. 데이터 형식에 이 플래그를 설정하는 것은,IDirectInputDevice7::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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.


DIDEVCAPS

DIDEVCAPS 구조체는, DirectInput 디바이스의 능력에 관한 정보를 저장 한다. 이 구조체는,IDirectInputDevice7::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
이 구조체의 바이트 단위의 사이즈. IDirectInputDevice7::GetCapabilities 메소드에 호출하기 전에, 어플리케이션은, 이 멤버를 초기화해 두지 않으면 안 된다.
dwFlags
디바이스에 관련지을 수 있었던 플래그. 이 값은, 이하의 정수의 편성이 된다.
DIDC_ALIAS
디바이스는, 다른 DirectInput 디바이스의 복제이다. 별명의 디바이스는, 디폴트에서는 IDirectInput7::EnumDevices 에 의해 열거되지 않는다.
DIDC_PHANTOM
이 디바이스는 실재하지 않는다. 이 디바이스는, 장래 제공될지도 모르는 디바이스의 플레이스홀더이다. 가상 디바이스는, 디폴트에서는 IDirectInput7::EnumDevices 에 의해 열거되지 않는다.
DIDC_ATTACHED
디바이스는, 물리적으로Attach 되고 있다.
DIDC_DEADBAND
디바이스는, 적어도 1 개의 force feedback 조건으로 데드 밴드를 지원 하고 있다.
DIDC_EMULATED
이 플래그가 설정되면(자), 데이터는 유저 모드 디바이스 인터페이스 (HID 등)로부터, 또는 다른 링 3 의 수단에 의해 입력된다. 플래그가 설정되지 않는 경우, 데이터는 커널 모드 드라이버로부터 직접 입력된다.
DIDC_FORCEFEEDBACK
디바이스는, force feedback를 지원 한다.
DIDC_FFFADE
force feedback 시스템은, 적어도 1 개의 이펙트에 대한페이드 파라미터를 지원 한다. 디바이스가 페이드를 지원 하지 않는 경우, 디바이스는,DIENVELOPE 구조체의 페이드 레벨과 페이드 시간의 양파라미터를 무시한다.

IDirectInputDevice7::GetEffectInfo 메소드의 호출 후, 개별의 이펙트가 페이드를 지원 하고 있으면, DIEFT_FFFADE 플래그가 설정된다.

DIDC_FFATTACK
force feedback 시스템은, 적어도 1 개의 이펙트에 대한어택 파라미터를 지원 한다. 디바이스가 어택을 지원 하지 않는 경우, 디바이스는,DIENVELOPE 구조체의 어택 레벨과 어택 시간의 양파라미터를 무시한다.

IDirectInputDevice7::GetEffectInfo 메소드의 호출 후, 개별의 이펙트가 어택을 지원 하고 있으면, DIEFT_FFATTACK 플래그가 설정된다.

DIDC_POLLEDDATAFORMAT
현상의 데이터 형식에서 적어도 1 개의 오브젝트가, 세치기 구동은 아니고, 폴링 된다. 이것들 오브젝트를 위해서(때문에), 어플리케이션은 명시적으로 IDirectInputDevice7::Poll 메소드를 호출해, 데이터를 취득해야 한다.
DIDC_POLLEDDEVICE
디바이스 위에의 적어도 1 개의 오브젝트가, 세치기 구동은 아니고, 폴링 된다. 이것들 오브젝트를 위해서(때문에), 어플리케이션은 명시적으로 IDirectInputDevice7::Poll 메소드를 호출해, 데이터를 취득해야 한다. HID 디바이스는, 폴링 오브젝트와 비폴링 오브젝트를 혼재해 저장 할 수 있다.
DIDC_POSNEGCOEFFICIENTS
force feedback 시스템은, 적어도 1 개의 조건에 대해서 조건의 2 개의 계수값을 지원 한다 (한편은, 축의 정이동, 한편은, 축의 부이동). 디바이스가 한편의 계수 밖에 지원 하고 있지 않는 경우,DICONDITION 구조체의 부의 계수는 무시된다.

IDirectInputDevice7::GetEffectInfo 메소드의 호출 후, 개별의 조건이 정과 부의 계수를 따로 따로 지원 하고 있으면, 그 조건은 DIEFT_POSNEGCOEFFICIENTS 플래그를 설정한다.

DIDC_POSNEGSATURATION
force feedback 시스템은, 적어도 1 개의 조건에 대해서, 정부의 양쪽 모두의 포스 출력에 대한 최대포화를 지원 한다. 디바이스가 한편의 포화값 밖에 지원 하고 있지 않는 경우,DICONDITION 구조체의 부의 포화값은 무시된다.

IDirectInputDevice7::GetEffectInfo 메소드의 호출 후, 개별의 조건이 정과 부의 포화값을 따로 따로 지원 하고 있으면, 그 조건은 DIEFT_POSNEGSATURATION 플래그를 설정한다.

DIDC_SATURATION
force feedback 시스템은, 적어도 1 개의 조건에 대해서 조건 이펙트의포화를 지원 한다. 디바이스가 포화를 지원 하고 있지 않으면, 어느 조건의 아래에서 생성되는 포스는, 디바이스를 생성할 수 있는 최대 포스에 의해서만 제한된다.

IDirectInputDevice7::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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.

참조

DIDEVICEINSTANCE


DIDEVICEINSTANCE

DIDEVICEINSTANCE 구조체는, 디바이스의 인스턴스에 관한 정보를 저장 한다. 이 구조체는,IDirectInput7::EnumDevices 및 IDirectInputDevice7::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 개 상위의 바이트는, 디바이스 서브 타입을 지정한다. 이 값은, 이하의 타입의 1 개로 거기에 대응하는 서브 타입, 및 옵션으로서 DIDEVTYPE_HID 를 조합한 것이 된다. DIDEVTYPE_HID 는, 휴먼 인터페이스 디바이스를 지정한다.
디바이스 타입
DIDEVTYPE_MOUSE
마우스 또는 마우스 유사 디바이스 (트랙 볼 등).
DIDEVTYPE_KEYBOARD
키보드 또는 키보드 유사 디바이스.
DIDEVTYPE_JOYSTICK
죠이스틱 또는 유사 디바이스 (핸들 등).
DIDEVTYPE_DEVICE
위의 카테고리에 속하지 않는 디바이스.
마우스 서브 타입
DIDEVTYPEMOUSE_UNKNOWN
서브 타입은 확정할 수 없다.
DIDEVTYPEMOUSE_TRADITIONAL
디바이스는, 종래의 마우스이다.
DIDEVTYPEMOUSE_FINGERSTICK
디바이스는, FINGER 스틱이다.
DIDEVTYPEMOUSE_TOUCHPAD
디바이스는, 터치 패드이다.
DIDEVTYPEMOUSE_TRACKBALL
디바이스는, 트랙 볼이다.
키보드 서브 타입
DIDEVTYPEKEYBOARD_UNKNOWN
서브 타입은 확정할 수 없다.
DIDEVTYPEKEYBOARD_PCXT
IBM PC/XT 83 키 키보드
DIDEVTYPEKEYBOARD_OLIVETTI
Olivetti 102 키 키보드
DIDEVTYPEKEYBOARD_PCAT
IBM PC/AT 84 키 키보드
DIDEVTYPEKEYBOARD_PCENH
IBM PC 확장 101/102 키식 키보드 또는 Microsoft 내츄럴 키보드
DIDEVTYPEKEYBOARD_NOKIA1050
Nokia 1050 키보드
DIDEVTYPEKEYBOARD_NOKIA9140
Nokia 9140 키보드
DIDEVTYPEKEYBOARD_NEC98
일본어 NEC PC98 키보드
DIDEVTYPEKEYBOARD_NEC98LAPTOP
일본어 NEC PC98 랩탑 키보드
DIDEVTYPEKEYBOARD_NEC98106
일본어 NEC PC98 106 키 키보드
DIDEVTYPEKEYBOARD_JAPAN106
일본어 106 키 키보드
DIDEVTYPEKEYBOARD_JAPANAX
일본어 AX 키보드
DIDEVTYPEKEYBOARD_J3100
일본어 J3100 키보드
죠이스틱 서브 타입
DIDEVTYPEJOYSTICK_UNKNOWN
서브 타입은 확정할 수 없다.
DIDEVTYPEJOYSTICK_TRADITIONAL
종래의 죠이스틱.
DIDEVTYPEJOYSTICK_FLIGHTSTICK
플라이트 시뮬레이션용으로 최적화되고 있는 죠이스틱.
DIDEVTYPEJOYSTICK_GAMEPAD
주요 목적이 버튼 입력을 실시하는 것에 있는 디바이스.
DIDEVTYPEJOYSTICK_RUDDER
편요제어용의 디바이스.
DIDEVTYPEJOYSTICK_WHEEL
차의 핸들용의 디바이스.
DIDEVTYPEJOYSTICK_HEADTRACKER
유저의 머리의 움직임을 추적하는 디바이스.

고위 워드의 플래그

DIDEVTYPE_HID
디바이스는, HID (Human Interface Device) 프로토콜을 사용한다.
tszInstanceName[MAX_PATH]
인스턴스의 등록명. 예를 들어,"Joystick 1".
tszProductName[MAX_PATH]
제품의 등록명.
guidFFDriver
force feedback에 사용되는 드라이버의 일의인 식별자. 이 식별자는, 드라이버의 메이커가 정한다.
wUsagePage
디바이스가 HID 디바이스이면, 이 멤버에는, HID 사용 페이지 코드가 포함된다.
wUsage
디바이스가 HID 디바이스이면, 이 멤버에는, HID 사용 코드가 포함된다.

주의

이전의 버젼의 DirectX 와 호환성을 갖게하기 (위해)때문에,DIDEVICEINSTANCE 구조체의 최초의 6 개의 멤버만을 포함한 DIDEVICEINSTANCE_DX3 구조체도 정의된다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.


DIDEVICEOBJECTDATA

DIDEVICEOBJECTDATA 구조체는, 버퍼링 디바이스의 미가공의 정보를 저장 한다. 이 구조체는,IDirectInputDevice7::GetDeviceData 및 IDirectInputDevice7::SendDeviceData 메소드로 사용된다.

typedef struct DIDEVICEOBJECTDATA {
    DWORD dwOfs;
    DWORD dwData;
    DWORD dwTimeStamp;
    DWORD dwSequence;
} DIDEVICEOBJECTDATA, *LPDIDEVICEOBJECTDATA;

typedef const DIDEVICEOBJECTDATA *LPCDIDEVICEOBJECTDATA;

멤버

dwOfs
GetDeviceData 의 경우, 데이터의 보고 대상이 되고 있는 오브젝트의, 현재의 데이터 형식에 대한 오프셋(offset)값. 즉,IDirectInputDevice7::GetDeviceState 메소드의 호출에 의해 데이터가 취득되었을 경우, 그 dwData 가 저장 되고 있는 위치가 된다. 디바이스가 마우스, 키보드, 또는 죠이스틱으로서 액세스 되는 경우에, 이 dwOfs 멤버는,마우스 디바이스 정수,키보드 디바이스 정수, 또는죠이스틱 디바이스 정수의 어느 쪽인가에 된다. 커스텀 데이터 형식이 설정되어 있는 경우는, 커스텀 데이터 형식에 관련하는 오프셋(offset)가 된다.

SendDeviceData 의 경우, 데이터의 송신지인 오브젝트의 인스턴스 ID. 이것은 DIDEVICEOBJECTINSTANCE 구조체의 dwType 멤버로부터 취득된다.

dwData
디바이스로부터 취득 또는 디바이스에 송신되는 데이터.

축으로부터의 입력의 경우, 디바이스가 상대축모드에 있으면, 상대축의 움직임이 보고된다. 디바이스가 절대축모드에 있으면, 절대 좌표가 보고된다.

버튼으로부터의 입력의 경우,dwData 의 하위 바이트만이 의미가 있다. 하위 바이트의 상위 비트는, 버튼이 다운 상태의 경우로 설정되어 업 상태의 경우에 소거된다.

dwTimeStamp
입력 이벤트가 생성된 밀리 세컨드 단위의 시간 카운트. 현재의 시스템 시간 카운트 (저분해가능)는, Win32 GetTickCount 함수를 호출해 취득할 수 있다. 덧붙여 이 값은, 약 50 일에 순환한다.

구조체가 SendDeviceData 메소드와 함께 사용되는 경우, 이 멤버는 반드시 제로가 된다.

dwSequence
이 이벤트에 대한 DirectInput 순서 번호. 모든 입력 이벤트에는, 승순의 순서 번호를 할당할 수 있고 있다. 이것에 의해, 다른 디바이스로부터의 이벤트를 시간순서에 소트 하는 것이 가능하게 된다. 이 값은, 순환해 초기값에 돌아오므로, 2 개의 순서 번호를 비교하는 경우에는 주의하지 않으면 안 된다. 이 비교를 안전하게 실시하려면 ,DISEQUENCE_COMPARE 매크로를 사용하면 좋다.

구조체가 SendDeviceData 메소드와 함께 사용되는 경우, 이 멤버는 반드시 제로가 된다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.


DIDEVICEOBJECTINSTANCE

DIDEVICEOBJECTINSTANCE 구조체는, 디바이스 오브젝트의 인스턴스에 관한 정보를 저장 한다. 이 구조체는,IDirectInputDevice7::EnumObjects 메소드로 사용되어DIEnumDeviceObjectsCallback 콜백 함수에 대해서, 축 또는 버튼 등, 디바이스에 관련지을 수 있었던 특정의 오브젝트에 대한 정보를 제공한다. 또, 디바이스 오브젝트의 정보를 취득하기 위해서,IDirectInputDevice7::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
이 구조체의 바이트 단위의 사이즈. 열거동안에, 어플리케이션은 이 값을 조사해 구조체의 멤버가 몇개 유효한가를 확인할 수 있다. 구조체가 IDirectInputDevice7::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
마우스의 버튼.
GUID_Key
키보드 위에의 키.
GUID_POV
시점 인디케이터(indicator)
GUID_Unknown
확정할 수 없다.

장래, 이외의 오브젝트 타입도 정의될 가능성이 있다.

dwOfs
데이터 형식내의 오프셋(offset)로, 이 오브젝트에 보고되는 데이터의 위치. 이 값은, 메소드 호출해에 있어서의 오브젝트와 DIPH_BYOFFSET 플래그를 받는 구조체안의 오브젝트를 식별하기 위해서 사용된다.
dwType
오브젝트를 나타내는 디바이스 타입. 오브젝트 타입 (축, 버튼등)을 나타내는 DIDFT_* 플래그의 편성이며, 중앙의 16 비트에는, 오브젝트 인스턴스 번호가 저장 된다. 오브젝트 인스턴스 번호를 추출하려면 ,DIDFT_GETINSTANCE 매크로를 사용한다. DIDFT_* 플래그에 대해서는,IDirectInputDevice7::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 멤버는, 실제로는 목적의 사용 페이지 및 사용 상황을 조합해 적절히 캐스트 된 DIMAKEUSAGEDWORD 이다.
DIDOI_POLLED
IDirectInputDevice7::Poll 메소드가 불려 갈 때까지, 오브젝트는 데이터를 돌려주지 않는다.
tszName[MAX_PATH]
오브젝트의 이름. 예를 들어,"X-Axis" 또는 "Right Shift" 등.
dwFFMaxForce
이 오브젝트에 관련지을 수 있었던 액츄에이터를 만들어 낼 수 있는 최대 포스의 매그니튜드. 포스는, 뉴턴 단위로 표현되어 디바이스를 보통에 조작하고 있는 동안의 손의 위치와의 관련으로 측정된다.
dwFFForceResolution
이 오브젝트에 관련지을 수 있었던 액츄에이터의 포스 분해가능. 반환값은, force feedback 시스템이 0 (포스 없음)으로부터 최대 포스의 범위에서 표현할 수 있는 포스의 단계수 또는 하위 구분의 수를 나타낸다.
wCollectionNumber
오브젝트가 속하는 HID 링크 콜렉션.
wDesignatorIndex
HID 물리 기술자의 지정을 참조하는 인덱스. 이 수치는, 디바이스 오브젝트에 대한 추가 정보를 포함한 HID 해석 라이브러리 (Hidpi.h)의 함수에게 건네진다.
wUsagePage
오브젝트에 관련하는 HID 사용 페이지 (판명되었을 경우). 휴먼 인터페이스 디바이스는 항상 사용 페이지를 보고한다. 비 HID 디바이스는 옵션으로 사용 페이지를 보고한다. 비 HID 디바이스가 보고하지 않는 경우, 이 파라미터의 값은 제로가 된다.
wUsage
오브젝트에 관련하는 HID 사용 상황 (판명되었을 경우). 휴먼 인터페이스 디바이스는 항상 사용을 보고한다. 비 HID 디바이스는 옵션으로 사용 상황을 보고한다. 비 HID 디바이스가 보고하지 않는 경우, 이 파라미터의 값은 제로가 된다.
dwDimension
오브젝트의 값을 보고하는 단위의 HID 코드 (판명하고 있는 경우). 불명한 경우는 제로가 된다.
wExponent
단위에 붙이는 지수 (판명하고 있는 경우). 차원 단위는 항상 정수이므로, 정수 이외의 타입에 단위를 변환하려면 지수가 필요하다.
wReportId
예약이 끝난 상태.

주의

어플리케이션은 wUsagePage 및 wUsage 멤버를 사용해, 오브젝트의 설계 목적에 관한 추가 정보를 얻을 수 있다. 예를 들어,wUsagePage 의 값이 0x02 (탈 것의 컨트롤)로,wUsage 의 값이 0xB9 (승강타 트림)의 경우, 오브젝트는, 조종간의 승강타 트림콘트로르로서 설계되고 있다. 항공 시뮬레이션 게임 어플리케이션은 이 정보를 사용해, 디바이스 위에의 오브젝트에 대해서, 보다 적절한 디폴트 동작을 제공할 수가 있다. HID 사용 코드는 USB 표준 위원회에서 정해져 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.


DIEFFECT

DIEFFECT 구조체는,IDirectInputDevice7::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 의 값은,IDirectInputDevice7::EnumObjects 에 의해 취득되는 오브젝트 식별자이다.
DIEFF_OBJECTOFFSETS
dwTriggerButton 및 rgdwAxes 의 값은, 데이터 형식 오프셋(offset)로 IDirectInputDevice7::SetDataFormat 에 의해 선택되고 있는 데이터 형식을 기점으로 한다.
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 를 호출하고 나서 이펙트를 재생하기 전에, 디바이스가 대기하는 시간 (마이크로 세컨드 단위). 이 값이 제로이면, 이펙트의 재생은 즉시 시작 된다. 이 멤버는, DirectX 7.0 보다 전의 버젼에는 존재하지 않는다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.


DIEFFECTINFO

DIEFFECTINFO 구조체는,IDirectInputDevice7::EnumEffects 및 IDirectInputDevice7::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
구조체의 바이트 단위의 사이즈. 열거동안에, 어플리케이션은 이 값을 조사해 구조체의 멤버가 몇개 유효한가를 확인할 수 있다. 이 구조체가 IDirectInputDevice7::GetEffectInfo 메소드에게 건네지기 전에, 이 구조체의 멤버를 초기화해야 한다.
guid
이펙트의 식별자.
dwEffType
제로 또는 이하의 값의 언젠가.
DIEFT_ALL
IDirectInputDevice7::EnumEffects 에 대해서만 유효. 타입에 관계없이 모든 이펙트를 열거한다. 이 플래그는, 다른 어느 플래그와도 배합할 수 없다.
DIEFT_CONDITION
이펙트는, 조건을 나타낸다. 조건을 생성 또는 수정할 때는,DIEFFECT 구조체의 lpvTypeSpecificParams 멤버가 DICONDITION 구조체 ( 각 축으로 1 개(살))로부터 완성되는 배열을 가리켜,cbTypeSpecificParams 멤버에는 cAxis * sizeof(DICONDITION) 를 설정해야 한다.

모든 디바이스가, 조건의 모든 파라미터를 지원 하는 것은 아니다. 이펙트의 능력 플래그를 체크해, 어느 능력이 사용 가능한가를 조사한다.

이 플래그는,IDirectInputDevice7::EnumEffects 에 건네주어, 열거 대상을 조건으로 제한할 수가 있다.

DIEFT_CONSTANTFORCE
이펙트는, 정수 포스 이펙트를 나타낸다. 정수 포스 이펙트를 생성 또는 수정할 때는,DIEFFECT 구조체의 lpvTypeSpecificParams 멤버가 DICONSTANTFORCE 구조체를 가리켜,cbTypeSpecificParams 멤버에는 sizeof(DICONSTANTFORCE) 를 설정해야 한다.

이 플래그는,IDirectInputDevice7::EnumEffects 에 건네주어, 열거 대상을 정수 포스 이펙트에 제한할 수가 있다.

DIEFT_CUSTOMFORCE
이펙트는, 커스텀 포스 이펙트를 나타낸다. 커스텀 포스 이펙트를 생성 또는 수정할 때는,DIEFFECT 구조체의 lpvTypeSpecificParams 멤버가 DICUSTOMFORCE 구조체를 가리켜,cbTypeSpecificParams 멤버에는 sizeof(DICUSTOMFORCE)를 설정해야 한다.

이 플래그는,IDirectInputDevice7::EnumEffects 에 건네주어, 열거 대상을 커스텀 포스 이펙트에 제한할 수가 있다.

DIEFT_DEADBAND
이 조건 이펙트에 대한 이펙트 제네레이터는,lDeadBand 파라미터를 지원 한다.
DIEFT_FFATTACK
이 이펙트에 대한 이펙트 제네레이터는,어택 엔벌로프 파라미터를 지원 한다. 이펙트 제네레이터가 어택을 지원 하고 있지 않으면,DIENVELOPE 구조체의 어택 레벨과 어택 시간의 파라미터를, 이펙트가 무시한다.

DIEFT_FFATTACK 와 DIEFT_FFFADE 가 양쪽 모두 설정되어 있지 않으면, 이펙트는, 엔벌로프를 지원 하지 않고, 지정의 엔벌로프는, 모두 무시된다.

DIEFT_FFFADE
이 이펙트에 대한 이펙트 제네레이터는,페이드 파라미터를 지원 한다. 이펙트 제네레이터가 페이드를 지원 하고 있지 않으면,DIENVELOPE 구조체의 페이드 레벨과 포드 시간의 파라미터를, 이펙트가 무시한다.

DIEFT_FFATTACK 와 DIEFT_FFFADE 가 양쪽 모두 설정되어 있지 않으면, 이펙트는, 엔벌로프를 지원 하지 않고, 지정의 엔벌로프는, 모두 무시된다.

DIEFT_HARDWARE
이펙트는, 하드웨어 고유의 이펙트를 나타낸다. 하드웨어 고유 이펙트의 사용의 상세한 것에 대하여는, 하드웨어의 문서를 참조할것.

이 플래그를 IDirectInputDevice7::EnumEffects 메소드에 건네주어, 열거 대상을 하드웨어 고유 이펙트에 제한할 수가 있다.

DIEFT_PERIODIC
이펙트는, 주기적 포스 이펙트를 나타낸다. 주기적 포스 이펙트를 생성 또는 수정할 때는,DIEFFECT 구조체의 lpvTypeSpecificParams 멤버가 DIPERIODIC 구조체를 가리켜,cbTypeSpecificParams 멤버에는 sizeof(DIPERIODIC)를 설정해야 한다.

이 플래그는,IDirectInputDevice7::EnumEffects 에 건네주어, 열거 대상을 주기적 포스 이펙트에 제한할 수가 있다.

DIEFT_POSNEGCOEFFICIENTS
이 이펙트에 대한 이펙트 제네레이터는, 조건에 대한 2 개의 계수값, 한편은 정의 축이동, 한편은 부의 축이동에 대한 계수를 지원 한다. 디바이스가 한방향의 계수 밖에 지원 하지 않는 경우,DICONDITION 구조체의 부의 계수가 무시되어 정의 계수가 양쪽 모두의 방향으로 사용된다.
DIEFT_POSNEGSATURATION
이 이펙트에 대한 이펙트 제네레이터는, 정부의 양쪽 모두의 포스 출력에 대한 최대포화를 지원 한다. 디바이스가 한방향의 포화값 밖에 지원 하지 않는 것이면,DICONDITION 구조체의 부의 포화값이 무시되어 정의 포화값이 양쪽 모두의 방향으로 사용된다.
DIEFT_RAMPFORCE
이펙트는, 경사 포스 이펙트를 나타낸다. 경사 포스 이펙트를 생성 또는 수정할 때는,DIEFFECT 구조체의 lpvTypeSpecificParams 멤버가 DIRAMPFORCE 구조체를 가리켜,cbTypeSpecificParams 멤버에는 sizeof(DIRAMPFORCE )를 설정해야 한다.

이 플래그는,IDirectInputDevice7::EnumEffects 에 건네주어, 열거 대상을 경사 포스 이펙트에 제한할 수가 있다.

DIEFT_SATURATION
이 이펙트에 대한 이펙트 제네레이터는, 조건 이펙트의포화를 지원 한다. 이펙트 제네레이터가 포화를 지원 하고 있지 않으면, 조건이 생성한 포스는, 디바이스를 생성할 수 있는 최대 포스에 의해서만 제한된다.
dwStaticParams
이펙트가 지원 하는 파라미터를 나타내는 제로 이상의 DIEP_* 값. 예를 들어, DIEP_ENVELOPE 가 설정되어 있으면, 이펙트는 엔벌로프를 지원 한다. 이 멤버가 취할 수 있는 값의 리스트에 대해서는, 「IDirectInputEffect::GetParameters 」를 참조할것.

디바이스가 지원 하고 있지 않는 이펙트 파라미터를 어플리케이션이 사용하려고 해도, 에러는 되지 않는다. 지원되어 있지 않은 파라미터는, 무시되는 것만으로 있다.

이 정보는, 어플리케이션이 특정의 디바이스의 능력에 force feedback를 적합시켜 사용할 수 있도록(듯이) 하기 위해서 제공되고 있다.

dwDynamicParams
이펙트의 재생중에 수정할 수 있는 이펙트 파라미터를 나타내는 제로 이상의 DIEP_* 값. 이 멤버가 취할 수 있는 값의 리스트에 대해서는, 「IDirectInputEffect::GetParameters 」를 참조할것.

이펙트의 재생중에 어플리케이션이 파라미터를 변경하려고 해도, 드라이버가 그 이펙트를 동적으로 수정하는 기능을 지원 하고 있지 않는 경우는, 드라이버는 그 이펙트를 정지해, 파라미터를 갱신해, 그 후에 이펙트를 재개할 수가 있다. 상세한 것에 대하여는, 「IDirectInputEffect::SetParameters 」를 참조할것.

tszName[MAX_PATH]
이펙트의 이름. 예를 들어,"Sawtooth up" 또는 "Constant 포스" 등.

주의

dwEffType 플래그로부터 이펙트 타입을 추출하려면 ,DIEFT_GETTYPE 매크로를 사용한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.


DIEFFESCAPE

DIEFFESCAPE 구조체는, 하드웨어 데이터를 디바이스 드라이버에 직접, 건네주기 위해서(때문에) IDirectInputDevice7::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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.


DIENVELOPE

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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.


DIFILEEFFECT

DIFILEEFFECT 구조체는, 파일에 보존된 force feedback 이펙트의 데이터를 나타낸다. 이 구조체는,IDirectInputDevice7::EnumEffectsInFile 및 IDirectInputDevice7::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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.


DIJOYSTATE

DIJOYSTATE 구조체는, 죠이스틱 디바이스 상태에 관한 정보를 저장 한다. 이 구조체는,IDirectInputDevice7::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 축으로 불리고 있었다). 이 값의 의미는 죠이스틱으로 다르다. 이러한 값의 의미에 대한 정보를 얻으려면 ,IDirectInputDevice7::GetObjectInfo 메소드를 사용한다.
rgdwPOV[4]
최고 4 개(살)까지의 방향 콘트롤러 (시점 인디케이터(indicator)등)의 현재 위치. 이 정도치는, 북쪽으로부터 (유저의 정면측) 시계회전의 열매 각도의 100 배로 나타내진다. 중심 위치는 보통 -1 이라고 보고되지만, 이것에 대해서는 「주의」를 참조할것. 5 개의 위치 밖에 가지지 않는 인디케이터(indicator)의 경우, 콘트롤러의 값은 -1, 0, 9,000, 18,000, 27,000 의 어떤 것이나 1 개의 값을 취한다.
rgbButtons[32]
버튼 상태의 배열. 바이트의 상위 비트는, 대응하는 버튼이 다운 상태에 있을 때 설정되어 버튼이 업 상태 또는 존재하지 않을 때에는 소거된다.

주의

죠이스틱식의 액세스가 생기도록(듯이) 디바이스를 준비하려면 ,IDirectInputDevice7::SetDataFormat 메소드를 호출해,c_dfDIJoystick 글로벌 데이터 형식 변수를 건네준다.

축이 상대 모드인 경우는, 적절한 멤버가 위치의 변화량을 저장 한다. 절대 모드의 경우에는, 같은 멤버가 축의 절대 위치를 저장 한다.

POV 인디케이터(indicator)의 중심 위치를 65,535 라고 보고하는 드라이버도 있다. POV 인디케이터(indicator)가 중심 위치에 있을지 어떨지는, 다음과 같이 해 확인한다.

BOOL POVCentered = (LOWORD(dwPOV) == 0xFFFF);

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.


DIJOYSTATE2

DIJOYSTATE2 구조체는, 확장 기능부 죠이스틱 디바이스 상태에 관한 정보를 저장 한다. 이 구조체는,IDirectInputDevice7::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 축으로 불리고 있었다). 이 값의 의미는 죠이스틱으로 다르다. 이러한 값의 의미에 대한 정보를 얻으려면 ,IDirectInputDevice7::GetObjectInfo 메소드를 사용한다.
rgdwPOV[4]
최고 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]
추가축의 포스의 정보.

주의

확장 기능부 죠이스틱에의 액세스용으로 디바이스를 준비하려면 ,IDirectInputDevice7::SetDataFormat 메소드를 호출해,c_dfDIJoystick2 글로벌 데이터 형식 변수를 건네준다.

DIJOYSTATE2 구조체는 IDirectInputDevice7 인터페이스와 특별한 관련은 없다. DIJOYSTATE 또는 DIJOYSTATE2 의 어느 쪽인지 한편을,IDirectInputDevice 인터페이스 또는 IDirectInputDevice7 인터페이스의 어느 쪽인지 한편과 함께 사용할 수가 있다.

축이 상대 모드인 경우는, 적절한 멤버가 위치의 변화량을 저장 한다. 절대 모드의 경우에는, 같은 멤버가 축의 절대 위치를 저장 한다.

POV 인디케이터(indicator)의 중심 위치를 65,535 라고 보고하는 드라이버도 있다. POV 인디케이터(indicator)가 중심 위치에 있을지 어떨지는, 다음과 같이 해 확인한다.

BOOL POVCentered = (LOWORD(dwPOV) == 0xFFFF);

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.


DIMOUSESTATE

DIMOUSESTATE 구조체는, 4 개(살)까지의 버튼을 가지는 마우스 디바이스 상태에 관한 정보, 또는 마우스 디바이스와 같이 액세스 되는 그 외의 디바이스 상태에 관한 정보를 저장 한다. 이 구조체는,IDirectInputDevice7::GetDeviceState 메소드로 사용한다.

typedef struct DIMOUSESTATE {
    LONG lX;
    LONG lY;
    LONG lZ;
    BYTE rgbButtons[4];
} DIMOUSESTATE, *LPDIMOUSESTATE;

멤버

lX
마우스의 x 축정보.
lY
마우스의 y 축정보.
lZ
마우스의 z 축정보 (보통, 휠). 마우스에 z 축이 없으면, 이 값은 제로이다.
rgbButtons[4]
버튼 상태의 배열. 바이트의 상위 비트는, 대응하는 버튼이 다운 상태에 있을 때 설정된다.

주의

마우스형의 액세스가 생기도록(듯이) 디바이스를 준비하려면 ,IDirectInputDevice7::SetDataFormat 메소드를 호출해,c_dfDIMouse 글로벌 데이터 형식 변수를 건네준다.

마우스는 상대축디바이스이므로, 마우스축의 절대축위치는, 단순하게 상대적인 움직임의 누적으로서 요구된다. 따라서, 절대축위치는, 다른 절대축위치와 비교하는 경우를 제외해 무의미가 된다.

축이 상대 모드인 경우는, 적절한 멤버가 위치의 변화량을 저장 한다. 절대 모드의 경우에는, 같은 멤버가 축의 절대 위치를 저장 한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.

참조

DIMOUSESTATE2


DIMOUSESTATE2

DIMOUSESTATE2 구조체는, 8 개(살)까지의 버튼을 가지는 마우스 디바이스, 또는 마우스 디바이스와 같게 액세스 되는 그 외의 디바이스에 관한 정보를 저장 한다. 이 구조체는,IDirectInputDevice7::GetDeviceState 메소드로 사용한다.

typedef struct DIMOUSESTATE {
    LONG lX;
    LONG lY;
    LONG lZ;
    BYTE rgbButtons[8];
} DIMOUSESTATE, *LPDIMOUSESTATE;

멤버

lX
마우스의 x 축정보.
lY
마우스의 y 축정보.
lZ
마우스의 z 축정보 (보통, 휠). 마우스에 z 축이 없으면, 이 값은 제로이다.
rgbButtons[8]
버튼 상태의 배열. 바이트의 상위 비트는, 대응하는 버튼이 다운 상태에 있을 때 설정된다.

주의

마우스형의 액세스가 생기도록(듯이) 디바이스를 준비하려면 ,IDirectInputDevice7::SetDataFormat 메소드를 호출해,c_dfDIMouse2 글로벌 데이터 형식 변수를 건네준다.

마우스는 상대축디바이스이므로, 마우스축의 절대축위치는, 단순하게 상대적인 움직임의 누적으로서 요구된다. 따라서, 절대축위치는, 다른 절대축위치와 비교하는 경우를 제외해 무의미가 된다.

축이 상대 모드인 경우는, 적절한 멤버가 위치의 변화량을 저장 한다. 절대 모드의 경우에는, 같은 멤버가 축의 절대 위치를 저장 한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.

참조

DIMOUSESTATE


DIOBJECTDATAFORMAT

DIOBJECTDATAFORMAT 구조체는,IDirectInputDevice7::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 구조체로 구성된다. 이러한 구조체의 배열은,IDirectInputDevice7::SetDataFormat 에게 건네지는 DIDATAFORMAT 구조체에 저장 된다. 어플리케이션은, 보통,DIOBJECTDATAFORMAT 구조체로부터 되는 배열을 생성 할 필요는 없고,DIOBJECTDATAFORMAT 에 사전 정의되고 있는 설정값인 c_dfDIMouse,c_dfDIMouse2,c_dfDIKeyboard,c_dfDIJoystick, 또는 c_dfDIJoystick2 등의 사전 정의된 데이터 형식 데이터의 어느쪽이든을 사용할 수 있다.

이하의 오브젝트 데이터 형식은, 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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.


DIPERIODIC

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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.


DIPROPDWORD

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 데이터 형식을 선택하면(자), 이 멤버는 DIIMOFS_* 값중 어떤 것이나 1 개로 해야 한다.

dwHow | dwObj 멤버의 해석 방법을 지정한다. dwOb 가 DIPROP_AXISMODE 또는 DIPROP_BUFFERSIZE 이면,dwHow 는 DIPH_DEVICE 로 한다.

dwData
설정 또는 취득되는 프로퍼티값.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.

참조

IDirectInputDevice7::GetProperty ,IDirectInputDevice7::SetProperty


DIPROPGUIDANDPATH

DIPROPGUIDANDPATH 구조체는, GUID 와 패스를 나타내는 값을 가지는 프로퍼티에의 액세스에 사용된다.

typedef struct DIPROPGUIDANDPATH {
    DIPROPHEADER diph;
    GUID         guidClass;
    WCHAR        wszPath[MAX_PATH];
} DIPROPGUIDANDPATH, *LPDIPROPGUIDANDPATH;

멤버

diph
DIPROPHEADER 구조체. 이하와 같이 초기화한다.
멤버 | 값
dwSize | sizeof(DIPROPGUIDANDPATH)
dwHeaderSize | sizeof(DIPROPHEADER )
dwObj | 이펙트의 식별자. 디바이스의 경우는 제로이다.
dwHow | dwObj 멤버의 해석 방법.

guidClass
오브젝트의 클래스 GUID.
wszPath
돌려주어지는 오브젝트의 패스. 이것은 Unicode 캐릭터 라인이다.

주의

DIPROPGUIDANDPATH 구조체에 관련지을 수 있었던 DIPROP_GUIDANDPATH 프로퍼티를 사용하면(자), 상세 설정의 가능한 어플리케이션은, DirectInput 로 지원되어 있지 않은 HID 에 대해서 조작을 실행할 수 있다.

어플리케이션은,rguidProp 파라미터에 DIPROP_GUIDANDPATH 를 지정해 IDirectInputDevice7::GetProperty 메소드를 호출한다. 디바이스의 클래스 GUID 는,DIPROPGUIDANDPATH 구조체의 guidClass 멤버에 돌려주어진다. 디바이스 인터페이스의 패스는,wszPath 멤버에 돌려주어진다. 그 후, 어플리케이션은 이 패스에 대해서 CreateFile 함수를 호출해, 디바이스에 직접 액세스 할 수가 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : dinput.h 로 선언.


DIPROPHEADER

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_BYID | dwObj 멤버는, 오브젝트 타입 또는 인스턴스 식별자이다. 이 식별자는,IDirectInputDevice7::EnumObjects 메소드를 전회 호출했을 때의 반환값인 DIDEVICEOBJECTINSTANCE 구조체의 dwType 멤버에 돌려주어진다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.


DIPROPRANGE

DIPROPRANGE 구조체는, 디바이스내의 오브젝트의 범위에 관한 정보를 저장 한다. 이 구조체는,IDirectInputDevice7::GetProperty 및 IDirectInputDevice7::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 | dwObj 멤버의 해석 방법.

lMin
범위의 하한. 디바이스의 범위에 제한이 없으면,IDirectInputDevice7::GetProperty 메소드가 돌아올 때, 이 값은 DIPROPRANGE_NOMIN 가 된다.
lMax
범위의 상한. 디바이스의 범위에 제한이 없으면,IDirectInputDevice7::GetProperty 메소드가 돌아올 때, 이 값은 DIPROPRANGE_ NOMAX 가 된다.

주의

범위에 제한이 없는 디바이스에 대한 범위값은, 순환한다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.

참조

IDirectInputDevice7::GetProperty ,IDirectInputDevice7::SetProperty


DIPROPSTRING

DIPROPSTRING 구조체는, 캐릭터 라인 프로퍼티에 액세스 하기 위해서 사용된다.

typedef struct {
    DIPROPHEADER diph;
    WCHAR wsz;
} DIPROPSTRING;

멤버

diph
DIPROPHEADER 구조체. 이하와 같이 초기화한다.
멤버 | 값
dwSize | sizeof(DIPROPSTRING)
dwHeaderSize | sizeof(DIPROPHEADER)
dwObj | 취득 또는 설정하는 프로퍼티가 속하는 오브젝트의 식별자.
dwHow | dwObj 멤버의 해석 방법.

wsz
캐릭터 라인. 이것은 Unicode 캐릭터 라인이다.

주의

DIPROPSTRING 구조체에 관련지을 수 있었던 DIPROP_INSTANCENAME 및 DIPROP_PRODUCTNAME 프로퍼티를 사용하면(자), 상세 설정의 가능한 어플리케이션은, DirectInput 로 지원되어 있지 않은 HID 에 대해서 조작을 실행할 수 있다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 98 이 필요.
헤더 : dinput.h 로 선언.


DIRAMPFORCE

DIRAMPFORCE 구조체는,DIEFT_RAMPFORCE 로서 마크 되고 있는 이펙트에 관한 타입 정보를 포함한다. 이 구조체는 경사 포스 이펙트를 나타낸다.

이펙트에 관한 단일의 DIRAMPFORCE 구조체에의 포인터는,DIEFFECT 구조체의 lpvTypeSpecificParams 멤버에게 건네진다.

typedef struct DIPROPRANGE {
    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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dinput.h 로 선언.


디바이스 정수

여기에서는, 키, 버튼 및 축으로 대하는 데이터를 해석하는데 사용하는 정수에 관한 레퍼런스를 제공한다.

  • 키보드 디바이스 정수
  • DirectInput 와 일본어 키보드
  • 마우스 디바이스 정수
  • 죠이스틱 디바이스 정수


키보드 디바이스 정수

Dinput.h 에 정의되고 있는 키보드 디바이스 정수는, 키보드 디바이스의 데이터 패킷 (256 바이트 배열) 내에서의 오프셋(offset)를 나타낸다. 지정의 오프셋(offset) 위치의 데이터는, 키보드 키에 관련지을 수 있고 있다. 보통, 그러한 값은,DIDEVICEOBJECTDATA ,DIOBJECTDATAFORMAT , 또는 DIDEVICEOBJECTINSTANCE 구조체의 dwOfs 멤버 중(안)에서 사용되든가, 혹은 배열의 기법을 사용해 배열내의 데이터에 액세스 하면나무의 인덱스로서 사용된다.

표준 키보드 디바이스 정수는, 이하대로이다 (승순).

정수 | 메모
DIK_ESCAPE |
DIK_1 | 메인 키보드상
DIK_2 | 메인 키보드상
DIK_3 | 메인 키보드상
DIK_4 | 메인 키보드상
DIK_5 | 메인 키보드상
DIK_6 | 메인 키보드상
DIK_7 | 메인 키보드상
DIK_8 | 메인 키보드상
DIK_9 | 메인 키보드상
DIK_0 | 메인 키보드상
DIK_MINUS | 메인 키보드상
DIK_EQUALS | 메인 키보드상
DIK_BACK | BackSpace 키
DIK_TAB |
DIK_Q |
DIK_W |
DIK_E |
DIK_R |
DIK_T |
DIK_Y |
DIK_U |
DIK_I |
DIK_O |
DIK_P |
DIK_LBRACKET | [ 키
DIK_RBRACKET | ] 키
DIK_RETURN | 메인 키보드 위에의 Enter 키
DIK_LCONTROL | 왼쪽 Ctrl 키
DIK_A |
DIK_S |
DIK_D |
DIK_F |
DIK_G |
DIK_H |
DIK_J |
DIK_K |
DIK_L |
DIK_SEMICOLON |
DIK_APOSTROPHE |
DIK_GRAVE | 아크상라브 (`) 키
DIK_LSHIFT | 왼쪽 Shift 키
DIK_BACKSLASH |
DIK_Z |
DIK_X |
DIK_C |
DIK_V |
DIK_B |
DIK_N |
DIK_M |
DIK_COMMA |
DIK_PERIOD | 메인 키보드상
DIK_SLASH | 메인 키보드 위에의순서 slash
DIK_RSHIFT | 오른쪽 Shift 키
DIK_MULTIPLY | 숫자 패드 위에의 * 키
DIK_LMENU | 왼쪽 Alt 키
DIK_SPACE | 스페이스 키
DIK_CAPITAL | CapsLock 키
DIK_F1 |
DIK_F2 |
DIK_F3 |
DIK_F4 |
DIK_F5 |
DIK_F6 |
DIK_F7 |
DIK_F8 |
DIK_F9 |
DIK_F10 |
DIK_NUMLOCK |
DIK_SCROLL | ScrollLock
DIK_NUMPAD7 |
DIK_NUMPAD8 |
DIK_NUMPAD9 |
DIK_SUBTRACT | 숫자 패드 위에의 마이너스 기호
DIK_NUMPAD4 |
DIK_NUMPAD5 |
DIK_NUMPAD6 |
DIK_ADD | 숫자 패드 위에의 플러스 기호
DIK_NUMPAD1 |
DIK_NUMPAD2 |
DIK_NUMPAD3 |
DIK_NUMPAD0 |
DIK_DECIMAL | 숫자 패드 위에의 피리어드 (소수점)
DIK_OEM_102 | 영어 키보드 및 독일어 키보드상
DIK_F11 |
DIK_F12 |
DIK_F13 |
DIK_F14 |
DIK_F15 |
DIK_KANA | 일본어 키보드상
DIK_ABNT_C1 | 브라질어 키보드의 숫자 패드상
DIK_CONVERT | 일본어 키보드상
DIK_NOCONVERT | 일본어 키보드상
DIK_YEN | 일본어 키보드상
DIK_ABNT_C2 | 브라질어 키보드의 숫자 패드상
DIK_NUMPADEQUALS | 수치 키보드상 (NEC PC98)
DIK_PREVTRACK | 전의 트랙, 일본어 키보드의 서컴프렉스
DIK_AT | 일본어 키보드상
DIK_COLON | 일본어 키보드상
DIK_UNDERLINE | 일본어 키보드상
DIK_KANJI | 일본어 키보드상
DIK_STOP | 일본어 키보드상
DIK_AX | 일본어 키보드상
DIK_UNLABELED | 일본어 키보드상
DIK_NEXTTRACK | 다음의 트랙
DIK_NUMPADENTER |
DIK_RCONTROL | 오른쪽 Ctrl 키
DIK_MUTE |
DIK_CALCULATOR |
DIK_PLAYPAUSE |
DIK_MEDIASTOP |
DIK_VOLUMEDOWN |
DIK_VOLUMEUP |
DIK_WEBHOME |
DIK_NUMPADCOMMA | NEC PC98 숫자 패드 위에의 콤마
DIK_DIVIDE | 숫자 패드 위에의순서 slash
DIK_SYSRQ |
DIK_RMENU | 오른쪽 Alt 키
DIK_PAUSE |
DIK_HOME
DIK_UP | 상 커서 키
DIK_PRIOR | PageUp 키
DIK_LEFT | 왼쪽 커서 키
DIK_RIGHT | 오른쪽 커서 키
DIK_END |
DIK_DOWN | 하 커서 키
DIK_NEXT | PageDown 키
DIK_INSERT |
DIK_DELETE |
DIK_LWIN | 왼쪽 Windows 키
DIK_RWIN | 오른쪽 Windows 키
DIK_APPS | 어플리케이션 키
DIK_POWER |
DIK_SLEEP |
DIK_WAKE |
DIK_WEBSEARCH |
DIK_WEBFAVORITES |
DIK_WEBREFRESH |
DIK_WEBSTOP |
DIK_WEBFORWARD |
DIK_WEBBACK |
DIK_MYCOMPUTER |
DIK_MAIL |
DIK_MEDIASELECT |

이하의 대체명도 사용 가능하다.

대체명 | 보통명 | 메모
DIK_BACKSPACE | DIK_BACK | BackSpace
DIK_NUMPADSTAR | DIK_MULTIPLY | 숫자 패드 위에의 * 키
DIK_LALT | DIK_LMENU | 왼쪽 Alt 키
DIK_CAPSLOCK | DIK_CAPITAL | CapsLock 키
DIK_CIRCUMFLEX | DIK_PREVTRACK | 일본어 키보드상
DIK_NUMPADMINUS | DIK__SUBTRACT | 숫자 패드 위에의 마이너스 키
DIK_NUMPADPLUS | DIK_ADD | 숫자 패드 위에의 플러스 키
DIK_NUMPADPERIOD | DIK_DECIMAL | 숫자 패드 위에의 피리어드 키
DIK_NUMPADSLASH | DIK__DIVIDE | 숫자 패드 위에의순서 slash
DIK_RALT | DIK_RMENU | 오른쪽 Alt 키
DIK_UPARROW | DIK_UP | 커서 키 패드상
DIK_PGUP | DIK_PRIOR | 커서 키 패드상
DIK_LEFTARROW | DIK_LEFT | 커서 키 패드상
DIK_RIGHTARROW | DIK_RIGHT | 커서 키 패드상
DIK_DOWNARROW | DIK_DOWN | 커서 키 패드상
DIK_PGDN | DIK_NEXT | 커서 키 패드상

일본어 키보드에 대해서는, 「DirectInput 와 일본어 키보드」를 참조할것.


DirectInput 와 일본어 키보드

일본어 키보드와 US 키보드의 사이에는 상당한 차이가 있다. 이하에, 각종의 일본어 키보드로 사용 가능한 확장 키를 일람으로 가리킨다. 또, US 키보드에서는 사용 가능하지만, 많은 일본어 키보드에서는 눈에 띄지 않는 키의 일람도 가리킨다.

또, 일부의 NEC PC-98 키보드에서는, DIK_CAPSLOCK 및 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 표준 키보드 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 | mouse button 0 상태를 나타내는 데이터의 오프셋(offset).
DIMOFS_BUTTON1 | mouse button 1 상태를 나타내는 데이터의 오프셋(offset).
DIMOFS_BUTTON2 | mouse button 2 상태를 나타내는 데이터의 오프셋(offset).
DIMOFS_BUTTON3 | mouse button 3 상태를 나타내는 데이터의 오프셋(offset).
DIMOFS_BUTTON4 | mouse button 4 상태를 나타내는 데이터의 오프셋(offset) (DIMOUSESTATE2 마셔).
DIMOFS_BUTTON5 | mouse button 5 상태를 나타내는 데이터의 오프셋(offset) (DIMOUSESTATE2 마셔).
DIMOFS_BUTTON6 | mouse button 6 상태를 나타내는 데이터의 오프셋(offset) (DIMOUSESTATE2 마셔).
DIMOFS_BUTTON7 | mouse button 7 상태를 나타내는 데이터의 오프셋(offset) (DIMOUSESTATE2 마셔).
DIMOFS_X | x 축위에의 마우스의 위치를 나타내는 데이터의 오프셋(offset).
DIMOFS_Y | y 축위에의 마우스의 위치를 나타내는 데이터의 오프셋(offset).
DIMOFS_Z | z 축위에의 마우스의 위치를 나타내는 데이터의 오프셋(offset).


죠이스틱 디바이스 정수

죠이스틱 디바이스 정수는, 죠이스틱 디바이스의 데이터 패킷인 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) | 슬라이드축


반환값

이하는, DirectInput 메소드와 기능에 의해 돌려주어지는 HRESULT 값의 일람이다. 에러는 부의 값에 의해 나타나 결합할 수가 없다.

각각의 메소드 또는 기능은 에러값을 돌려줄 수가 있지만, 상세한 것에 대하여는 각각의 설명을 참조할것. 본문중의 에러 코드의 일람은, 필연적으로 불완전하게 되어 있다. 예를 들어, 어떤 DirectInput 메소드도 DIERR_OUTOFMEMORY 를 돌려줄 수가 있지만, 본문중에서는, 이 에러 코드는 그 메소드의 반환값으로서는 명시되어 있지 않다.

DI_BUFFEROVERFLOW
디바이스 버퍼가 오버플로우 해, 일부의 입력이 없어졌다. 이 값은, 표준의 COM 반환값인 S_FALSE 에 동일하다.
DI_DOWNLOADSKIPPED
이펙트의 파라미터의 갱신은 성공했지만, 이 이펙트에 관련하는 디바이스가 배타 모드로 취득되어 있지 않기 때문에, 이 이펙트를 다운로드할 수 없다.
DI_EFFECTRESTARTED
이펙트를 정지해, 그 파라미터의 갱신을 실시해, 그 후 이 이펙트를 재개했다.
DI_NOEFFECT
이 조작에 이펙트는 없다. 이 값은, 표준의 COM 반환값인 S_FALSE 에 동일하다.
DI_NOTATTACHED
디바이스는 존재하지만 현재Attach되어 있지 않다. 이 값은, 표준의 COM 반환값인 S_FALSE 에 동일하다.
DI_OK
조작은, 완전하게 종료했다. 이 값은, 표준의 COM 반환값인 S_OK 에 동일하다.
DI_POLLEDDEVICE
디바이스는, 폴링 대상 디바이스이다. 그 결과, 디바이스 버퍼링에서는, 데이터는 일절 수집되지 않고, 이벤트는,IDirectInputDevice7::Poll 메소드가 불려 갈 때까지 통지되지 않는다.
DI_PROPNOEFFECT
디바이스 프로퍼티의 변경은 이펙트가 없었다. 이 값은, 표준의 COM 반환값인 S_FALSE 에 동일하다.
DI_TRUNCATED
이펙트의 파라미터의 갱신은 성공했지만, 파라미터중 디바이스의 능력을 넘고 있는 것이 있어, 그것들은 바로 옆의 지원값에 말 수 있었다.
DI_TRUNCATEDANDRESTARTED
DI_EFFECTRESTARTED | DI_TRUNCATED 에 동일하다.
DIERR_ACQUIRED
조작은, 디바이스가 취득 상태의 사이는 실행할 수 없다.
DIERR_ALREADYINITIALIZED
이 오브젝트는 초기화가 끝난 상태이다.
DIERR_BADDRIVERVER
오브젝트는, 호환성이 없는 드라이버 버젼, 혹은 부적격 또는 불완전한 드라이버 컴퍼넌트이기 위해서(때문에) 생성 할 수 없었다.
DIERR_BETADIRECTINPUTVERSION
어플리케이션은, DirectInput 의 지원되어 있지 않은 릴리스전의 버젼용으로 생성 된 것이다.
DIERR_DEVICEFULL
디바이스는 풀이다.
DIERR_DEVICENOTREG
디바이스 또는 디바이스 인스턴스가 DirectInput 에 등록되지 않았다. 이 값은, 표준의 COM 반환값인 REGDB_E_CLASSNOTREG 에 동일하다.
DIERR_EFFECTPLAYING
파라미터는, 메모리내에서는 갱신되었지만, 디바이스에는 다운로드되지 않았다. 디바이스가 재생중의 이펙트의 갱신을 지원 하고 있지 않기 때문이다.
DIERR_HASEFFECTS
디바이스는, 이펙트가 그 디바이스에 Attach 되고 있기 위해서(때문에) 재초기화할 수 없다.
DIERR_GENERIC
DirectInput 서브 시스템으로 원인 불명의 에러가 발생했다. 이 값은, 표준의 COM 반환값인 E_FAIL 에 동일하다.
DIERR_HANDLEEXISTS
디바이스는, 이미, 자신에게 이벤트 통지가 관련짓고를 하고 있다. 이 값은, 표준의 COM 반환값인 E_ACCESSDENIED 에 동일하다.
DIERR_INCOMPLETEEFFECT
필수 정보가 없기 때문에, 이펙트를 다운로드할 수 없었다. 예를 들어, 이펙트에 관련하는 축이 없기도 하고, 타입 고유 정보가 주어지지 않은 경우.
DIERR_INPUTLOST
입력 디바이스의 액세스권을 잃었다. 재취득해야 한다.
DIERR_INVALIDPARAM
무효인 파라미터가 돌아오는 함수에게 건네졌는지, 오브젝트가 그 함수를 호출할 수 없는 상태에 없었다. 이 값은, 표준의 COM 반환값인 E_INVALIDARG 에 동일하다.
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
데이터는, 아직 사용 불가이다.


DirectInput Visual Basic 레퍼런스

DirectInput 의 Visual Basic API 의 레퍼런스 정보는, 이하의 카테고리로 분류된다.

  • 클래스
  • 형
  • 열거
  • 키보드 키
  • 에러 코드


클래스

여기에서는, 이하의 DirectInput 클래스의 메소드에 관한 레퍼런스를 제공한다.

  • DirectInput
  • DirectInputDevice
  • DirectInputDeviceInstance
  • DirectInputDeviceObjectInstance
  • DirectInputEffect
  • DirectInputEnumDeviceObjects
  • DirectInputEnumDevices
  • DirectInputEnumEffects


DirectInput

DirectInput 클래스는, DirectInput 시스템을 나타낸다. 어플리케이션은, 이 클래스의 단일의 오브젝트를 가져, Windows 컨트롤 패널의 인스턴스의 기동외, 이용 가능한 디바이스의 열거, 디바이스의 생성, 및 디바이스 상태의 취득을 실시하는데 사용된다.

DirectInput 오브젝트를 취득하려면 ,DirectX7.DirectInputCreate 메소드를 사용한다.

DirectInput 클래스에는, 다음의 메소드가 있다.

디바이스 관리 | CreateDevice
 | GetDeviceStatus
 | GetDIEnumDevices
그 외 | RunControlPanel


DirectInput.CreateDevice

DirectInput.CreateDevice 메소드는, 지정된 GUID 에 근거해 디바이스의 인스턴스를 생성 해, 초기화한다.

object. CreateDevice(guid As String) As DirectInputDevice

파라미터

object
DirectInput 오브젝트를 나타내는오브젝트식.
guid
목적의 입력 디바이스를 나타내는 인스턴스 GUID. 이 GUID 는,DirectInputEnumDevices.GetItem 메소드가 돌려주는 DirectInputDeviceInstance 오브젝트로부터 돌려주어진다. 다음의 캐릭터 라인의 어느쪽이든을 사용할 수도 있다.
GUID_SysKeyboard
디폴트의 시스템키 보드.
GUID_SysMouse
디폴트의 시스템 마우스.

반환값

성공하면,DirectInputDevice 오브젝트가 돌려주어진다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_DEVICENOTREG
DIERR_INVALIDPARAM
DIERR_NOINTERFACE
DIERR_OUTOFMEMORY

참조

GUID 의 사용


DirectInput.GetDeviceStatus

DirectInput.GetDeviceStatus 메소드는, 디바이스가 시스템에 Attach 되고 있는지 어떤지를 판정한다.

object. GetDeviceStatus(guid As String) As Boolean

파라미터

object
DirectInput 오브젝트를 나타내는오브젝트식.
guid
목적의 입력 디바이스를 나타내는 인스턴스 GUID. GUID 는,DirectInputEnumDevices.GetItem 메소드가 돌려주는 오브젝트의 DirectInputDeviceInstance.GetGuidInstance 메소드를 사용해 취득된다. 다음의 캐릭터 라인의 어느쪽이든을 사용할 수도 있다.
GUID_SysKeyboard
디폴트의 시스템키 보드.
GUID_SysMouse
디폴트의 시스템 마우스.

반환값

디바이스가 Attach 되고 있는 경우에 TRUE 가 돌려주어져 그 이외의 경우는 FALSE 가 돌려주어진다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_GENERIC
DIERR_INVALIDPARAM

참조

GUID 의 사용


DirectInput.GetDIEnumDevices

DirectInput.GetDIEnumDevices 메소드는,DirectInputEnumDevices 오브젝트를 돌려준다. 이 오브젝트를 사용해, 현재Attach 되고 있는 디바이스나, 컴퓨터에 Attach 되고 있을 가능성이 있는 디바이스를 열거한다.

object. GetDIEnumDevices( _
  deviceType As CONST_DIDEVICETYPE, _
  flags As CONST_DIENUMDEVICESFLAGS) _
  As DirectInputEnumDevices

파라미터

object
DirectInput 오브젝트를 나타내는오브젝트식.
deviceType
디바이스 타입의 필터. 이 파라미터가 제로라면, 모든 디바이스 타입이 열거된다. 제로 이외의 경우는, 다음의 열거 대상의 디바이스 타입을 나타내는 CONST_DIDEVICETYPE 열거의 DIDEVTYPE_* 정수이다.
DIDEVTYPE_MOUSE
마우스 또는 마우스 유사 디바이스 (트랙 볼 등).
DIDEVTYPE_KEYBOARD
키보드 또는 키보드 유사 디바이스.
DIDEVTYPE_JOYSTICK
죠이스틱 또는 유사 디바이스 (핸들 등).
DIDEVTYPE_DEVICE
위의 카테고리에 속하지 않는 디바이스.
flags
열거의 범위를 지정하는 플래그값. 이 파라미터는, 다음의 CONST_DIENUMDEVICESFLAGS 열거의 정수의 언젠가이다. 이 플래그가 제로 (DIEDFL_ALLDEVICES)이면, 인스톨 끝난 전디바이스가 열거된다. DIEDFL_ATTACHEDONLY 이면, 시스템에 실제로 Attach 되고 있는 디바이스만이 열거된다.

반환값

성공하면,DirectInputEnumDevices 오브젝트가 돌려주어진다.

에러 코드

실패하면 에러가 발생해,Err.Number 이 설정된다.

주의

모든 인스톨이 끝난 디바이스는, 비록 그것이 현존 하고 있지 않아도 열거 가능하다. 예를 들어, 죠이스틱은, 시스템에 인스톨 하지만, 당면 컴퓨터에 접속하지 않고 둘 수도 있다.

단일의 하드웨어가, 복수의 DirectInput 디바이스 타입으로서 기능할 수가 있는 경우는, 지원 하는 각 디바이스 타입 마다 돌려주어진다. 예를 들어, 편입 마우스 부착의 키보드는, 1 개의 키보드로서 한편, 1 개의 마우스로서 열거된다. 다만, 제품 GUID 는 각 디바이스에 대해서 같다.


DirectInput.RunControlPanel

DirectInput.RunControlPanel 메소드는, 유저가 새로운 입력 디바이스를 인스톨 하거나 구성을 변경하거나 할 수 있도록(듯이), Windows 컨트롤 패널을 실행한다.

object. RunControlPanel(hwndOwner As Long)

파라미터

object
DirectInput 오브젝트를 나타내는오브젝트식.
hwndOwner
이 이후의 유저 인터페이스의 부모 윈도우로서 사용하는 윈도우의 핸들. 이 파라미터가 제로라면, 부모 윈도우는 사용되지 않는다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectInputDevice.RunControlPanel


DirectInputDevice

어플리케이션은,DirectInputDevice 클래스의 메소드를 사용해, DirectInput 디바이스의 액세스권의 취득과 릴리즈, 디바이스 프로퍼티와 정보의 관리, 동작의 설정, 초기화의 실행, 및 디바이스의 프로퍼티 시트의 기동을 실시한다.

DirectInputDevice 오브젝트를 취득하려면 ,DirectInput.CreateDevice 메소드를 사용한다.

DirectInputDevice 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

액세스 | Acquire
 | SetCooperativeLevel
 | Unacquire
오브젝트 | GetDeviceObjectsEnum
 | GetObjectInfo
프로퍼티 | GetCapabilities
 | GetDeviceInfo
 | GetProperty
 | SetCommonDataFormat
 | SetDataFormat
 | SetProperty
데이터의 취득 | GetDeviceData
 | GetDeviceState
 | GetDeviceStateJoystick
 | GetDeviceStateJoystick2
 | GetDeviceStateKeyboard
 | GetDeviceStateMouse
 | Poll
 | SetEventNotification
force feedback | CreateCustomEffect
 | CreateEffect
 | GetEffectsEnum
 | GetForceFeedbackState
 | SendForceFeedbackCommand
그 외 | RunControlPanel
 | SendDeviceData


DirectInputDevice.Acquire

DirectInputDevice.Acquire 메소드는, 입력 디바이스의 액세스권을 취득한다.

object. Acquire()

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_INVALIDPARAM
DIERR_OTHERAPPHASPRIO

주의

디바이스를 취득하기 전에,DirectInputDevice.SetDataFormat 메소드 또는 DirectInputDevice.SetCommonDataFormat 메소드를 사용해 데이터 형식을 설정해야 한다.

디바이스로부터 입력 데이터를 취득하기 전에, 디바이스를 취득해야 한다.

참조

DirectInputDevice.Unacquire


DirectInputDevice.CreateCustomEffect

DirectInputDevice.CreateCustomEffect 메소드는, 고정적인 계속 시간을 가지는 일련의 정수 포스로 구성되는 force feedback 이펙트를 생성한다.

object. CreateCustomEffect(effectinfo As DIEFFECT, _
    channels As Long, samplePeriod As Long, _
    nSamples As Long, sampledata() As Long) _
    As DirectInputEffect

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.
effectinfo
이펙트의 일반적인 파라미터를 저장 하는 DIEFFECT 형.
channels
이 포스에 의해 영향을 받는 채널 (축)의 수. 1 또는 2 가 아니면 안된다.

채널이 1 개 밖에 존재하지 않는 경우, 이펙트는,DIEFFECT 형의 x 멤버가 지정할 방향으로 회전한다. 커스텀 이펙트의 회전을 지원 하고 있지 않는 디바이스도 있다.

복수의 채널이 존재하는 경우, 제 1 채널은 x 축으로 적용되어 제 2 채널은 y 축으로 적용된다. 회전은 허가되지 않는다.

samplePeriod
마이크로 세컨드 단위의 샘플링 간격. 「주의」를 참조할것.
nSamples
sampledata 배열중의 요소의 수.
sampledata
매그니튜드의 배열. channels 가 2 이상이면, 각 값은 차례로 할당할 수 있다. 예를 들어,channels 가 2 의 경우, 배열의 제 1 요소는 x 축, 제 2 요소는 y 축, 제 3 요소는 x 축으로 할당할 수 있다. 채널이 이것보다 많은 경우도 마찬가지이다.

주의

이론적으로는,samplePeriod 는 sampledata 에 포함되는 유효한 각 매그니튜드의 시간의 길이이다. 한편,DIEFFECT.lSamplePeriod 는, 데이터의 샘플링 간격 ( 및 매그니튜드의 변화 간격의 최소 시간)의 길이이다. 배열내의 각 요소는, 배열 전체를 반복 처리할 때에 한 번만 샘플링 할 필요가 있지만, 드라이버에 따라서는 어떠한 경우에도 samplePeriod 를 무시하는 일이 있으므로,lSamplePeriod 와 samplePeriod 의 값을 같게 하는 것이 바람직하다.

참조

커스텀 포스


DirectInputDevice.CreateEffect

DirectInputDevice.CreateEffect 메소드는, force feedback 이펙트를 생성한다. 디바이스가 현재 배타 레벨로 취득되고 있는 경우, 이펙트의 다운로드도 행해진다.

object. CreateEffect(effectGuid As String, _
  effectinfo As DIEFFECT) As DirectInputEffect

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.
effectGuid
하드웨어 드라이버에 의해 인식되는 이펙트의 GUID 의 캐릭터 라인 표현. 표준의 이펙트를 나타내는 다음의 앨리어스(alias)의 어느쪽이든을 사용할 수 있다.

GUID_ConstantForce
GUID_RampForce
GUID_Square
GUID_Sine
GUID_Triangle
GUID_SawtoothUp
GUID_SawtoothDown
GUID_Spring
GUID_Damper
GUID_Inertia
GUID_Friction

effectinfo
생성 된 이펙트에 대한 파라미터를 저장 하는 DIEFFECT 구조체.

반환값

성공하면,DirectInputEffect 오브젝트가 돌려주어진다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_DEVICENOTREG
DIERR_DEVICEFULL
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

주의

에러가 발생하지 않는 경우, 이펙트는 생성이 끝난 상태로, 이펙트의 파라미터는 갱신이 끝난 상태이지만, 이펙트를 다운로드할 필요는 없었다. 이펙트를 다운로드하려면 , 디바이스를 배타 모드로 취득해야 한다.

참조

DirectInputEffect.Download ,DirectInputEffect.Start


DirectInputDevice.GetCapabilities

DirectInputDevice.GetCapabilities 메소드는, DirectInputDevice 오브젝트의 능력을 취득한다.

object. GetCapabilities(caps As DIDEVCAPS)

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.
caps
디바이스의 능력을 저장 하는 DIDEVCAPS 형.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectInputDevice.GetDeviceData

DirectInputDevice.GetDeviceData 메소드는, 디바이스로부터 버퍼링 데이터를 취득한다.

object. GetDeviceData( _
  deviceObjectDataArray() As DIDEVICEOBJECTDATA, _
  flags As CONST_DIDGDDFLAGS) As Long

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.
deviceObjectDataArray()
버퍼링 데이터를 받기 위한 DIDEVICEOBJECTDATA 형의 배열.
flags
데이터를 취득 방법을 제어하는 플래그. 이 값은, 제로인가,CONST_DIDGDDFLAGS 열거의 정수의 어느쪽이든을 취할 수가 있다.

반환값

성공하면, 실제로 취득된 버퍼링 데이터의 요소수가 deviceObjectDataArray 에 돌려주어진다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DI_BUFFEROVERFLOW
DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
DIERR_NOTBUFFERED

주의

디바이스 데이터를 취득하기 전에,DirectInputDevice.SetDataFormat 메소드로 데이터 형식을 설정해,DirectInputDevice.SetProperty 메소드로 버퍼 사이즈를 설정해,DirectInputDevice.Acquire 메소드로 디바이스를 취득해야 한다.

이 메소드를 사용해,SetProperty 로 생성 한 버퍼로부터 1 개 이상의 입력 이벤트를 취득할 수가 있다. 한 번의 호출로, 대기중의 모든 이벤트를 취득할 필요는 없다. 예를 들어, 단일의 요소로 구성되는 deviceObjectDataArray() 에 건네주어, 모든 데이터가 돌려주어질 때까지 GetDeviceData 를 루프 처리할 수가 있다.

버퍼가 오버플로우 하면, 대기중의 모든 데이터는 없어져 DI_BUFFEROVERFLOW 에러가 발생한다.

참조

DirectInputDevice.Poll ,폴링과 이벤트


DirectInputDevice.GetDeviceInfo

DirectInputDevice.GetDeviceInfo 메소드는, 디바이스의 식별 정보를 취득한다.

object. GetDeviceInfo() As DirectInputDeviceInstance

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectInputDeviceInstance 오브젝트가 돌려주어진다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectInputDevice.GetDeviceObjectsEnum

DirectInputDevice.GetDeviceObjectsEnum 메소드는,DirectInputEnumDeviceObjects 오브젝트를 돌려준다. 이 오브젝트는, 디바이스로 이용 가능한 오브젝트를 열거하는데 사용한다. 디바이스 오브젝트는, 보통, 축이나 버튼이다.

object. GetDeviceObjectsEnum( _
  flags As CONST_DIDFTFLAGS) _
  As DirectInputEnumDeviceObjects

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.
flags
열거하는 오브젝트의 타입을 지정하는 플래그. CONST_DIDFTFLAGS 열거의 1 개 이상의 멤버를 사용할 수 있다.

반환값

성공하면, 반환값은 DirectInputEnumDeviceObjects 이다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

DIDFT_FFACTUATOR 및 DIDFT_FFEFFECTTRIGGER 의 플래그를 지정 하면, 열거 대상은, 이 2 개의 플래그로 정의 떠날 수 있어 모든 기준을 채우는 오브젝트로 한정된다. 다른 모든 플래그의 경우는, 이 카테고리로 지정한 플래그로 정의되고 있는 기준을 채우는 오브젝트가 열거된다. 예를 들어, (DIDFT_FFACTUATOR Or DIDFT_FFEFFECTTRIGGER)는, 열거 대상을 force feedback 방아쇠 오브젝트로 한정한다. 이것에 대해서, (DIDFT_FFEFFECTRIGGER Or DIDFT_TGLBUTTON Or DIDFT_PSHBUTTON)는, 이펙트 방아쇠로서 이용할 수 있는 임의의 버튼이 열거된다.


DirectInputDevice.GetDeviceState

DirectInputDevice.GetDeviceState 메소드는, 표준의 키보드, 마우스, 또는 죠이스틱 이외의 디바이스의 직접 데이터를 취득한다.

object. GetDeviceState(cb As Long, state As Any)

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.
cb
선두 요소가 state 로서 건네받는 배열의 사이즈.
state
디바이스 상태 정보를 받는 배열의 선두 요소.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
E_PENDING

주의

디바이스 데이터를 취득하기 전에,DirectInputDevice.SetCooperativeLevel 메소드로 협조 레벨을 설정해,DirectInputDevice.SetDataFormat 메소드로 데이터 형식을 설정해,DirectInputDevice.Acquire 메소드로 디바이스를 취득해야 한다.

참조

DirectInputDevice.GetDeviceStateJoystick ,DirectInputDevice.GetDeviceStateJoystick2 ,DirectInputDevice.GetDeviceStateKeyboard ,DirectInputDevice.GetDeviceStateMouse ,DirectInputDevice.SetDataFormat ,버퍼링 데이터와 직접 데이터


DirectInputDevice.GetDeviceStateJoystick

DirectInputDevice.GetDeviceStateJoystick 메소드는, 죠이스틱 디바이스로부터 직접 데이터를 취득한다.

object. GetDeviceStateJoystick(state As DIJOYSTATE)

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.
state
디바이스의 현재 상태를 받는 DIJOYSTATE 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
E_PENDING

주의

디바이스 데이터를 취득하기 전에,DirectInputDevice.SetCooperativeLevel 메소드로 협조 레벨을 설정해,DirectInputDevice.SetCommonDataFormat 메소드로 데이터 형식을 설정해,DirectInputDevice.Acquire 메소드로 디바이스를 취득해야 한다.

참조

DirectInputDevice.Poll


DirectInputDevice.GetDeviceStateJoystick2

DirectInputDevice.GetDeviceStateJoystick2 메소드는, 확장 기능부의 죠이스틱 디바이스로부터 직접 데이터를 취득한다.

object. GetDeviceStateJoystick2(state As DIJOYSTATE2)

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.
state
디바이스의 현재 상태를 받는 DIJOYSTATE2 형. 데이터 형식은, 먼저 DirectInputDevice.SetDataFormat 메소드를 호출하는 것으로 설정된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
E_PENDING

주의

디바이스 데이터를 취득하기 전에,DirectInputDevice.SetCooperativeLevel 메소드로 협조 레벨을 설정해,DirectInputDevice.SetCommonDataFormat 메소드로 데이터 형식을 설정해,DirectInputDevice.Acquire 메소드로 디바이스를 취득해야 한다.

참조

DirectInputDevice.Poll ,폴링과 이벤트


DirectInputDevice.GetDeviceStateKeyboard

DirectInputDevice.GetDeviceStateKeyboard 메소드는, 키보드 디바이스로부터 직접 데이터를 취득한다.

object. GetDeviceStateKeyboard(state As DIKEYBOARDSTATE)

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.
state
디바이스의 현재 상태를 받는 DIKEYBOARDSTATE 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
E_PENDING

주의

디바이스 데이터를 취득하기 전에,DirectInputDevice.SetCooperativeLevel 메소드로 협조 레벨을 설정해,DirectInputDevice.SetCommonDataFormat 메소드로 데이터 형식을 설정해,DirectInputDevice.Acquire 메소드로 디바이스를 취득해야 한다.

참조

DirectInputDevice.Poll


DirectInputDevice.GetDeviceStateMouse

DirectInputDevice.GetDeviceStateMouse 메소드는, 마우스 디바이스로부터 직접 데이터를 취득한다.

object. GetDeviceStateMouse(state As DIMOUSESTATE)

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.
state
디바이스의 현재 상태를 받는 DIMOUSESTATE 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
E_PENDING

주의

디바이스 데이터를 취득하기 전에,DirectInputDevice.SetCooperativeLevel 메소드로 협조 레벨을 설정해,DirectInputDevice.SetCommonDataFormat 메소드로 데이터 형식을 설정해,DirectInputDevice.Acquire 메소드로 디바이스를 취득해야 한다.

참조

DirectInputDevice.Poll


DirectInputDevice.GetEffectsEnum

DirectInputDevice.GetEffectsEnum 메소드는, 표준의 이펙트나 디바이스 메이커에 의해 설계된 이펙트 등, 디바이스가 지원 하는 force feedback 이펙트를 열거한다.

object. GetEffectsEnum( _
  effType As CONST_DIEFTFLAGS) As DirectInputEnumEffects

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.
effType
열거 대상의 이펙트 타입을 지정하는 CONST_DIEFTFLAGS 열거 가운데, 다음의 어느쪽이든 1 개의 플래그.

DIEFT_ALL
DIEFT_CONDITION
DIEFT_CONSTANTFORCE
DIEFT_CUSTOMFORCE
DIEFT_HARDWARE
DIEFT_PERIODIC
DIEFT_RAMPFORCE

반환값

DirectInputEnumEffects 오브젝트를 돌려준다. 이 오브젝트의 메소드는, 이펙트에 관한 정보의 취득에 사용한다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectInputDevice.GetForceFeedbackState

DirectInputDevice.GetForceFeedbackState 메소드는, 디바이스의 force feedback 시스템 상태를 취득한다.

object. GetForceFeedbackState() As CONST_DIGFFSFLAGS

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 디바이스의 force feedback 시스템의 현재 상태를 나타내는 CONST_DIGFFSFLAGS 열거로부터의 플래그가 돌려주어진다.

DirectInput 의 장래의 버젼으로, 플래그가 추가 정의될 가능성도 있다. 어플리케이션은, 현재 미정도리의 플래그를 모두 무시할 필요가 있다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED
DIERR_UNSUPPORTED

주의

이 메소드를 성공시키려면 , 디바이스를 배타 협조 레벨로 취득해야 한다.


DirectInputDevice.GetObjectInfo

DirectInputDevice.GetObjectInfo 메소드는, 버튼이나 축등의 디바이스 오브젝트에 관한 정보를 취득한다.

object. GetObjectInfo( _
  Obj As Long, _
  how As CONST_DIPHFLAGS) _
  As DirectInputDeviceObjectInstance

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.
Obj
정보를 취득하는 오브젝트를 식별하는 값. 이 파라미터의 해석은,how 파라미터로 지정되고 있는 값에 의존한다.
how
Obj 파라미터의 해석 방법을 지정하는 값. 이 값은,CONST_DIPHFLAGS 열거의 정수의 어느쪽이든을 취할 수가 있다.

반환값

DirectInputDeviceObjectInstance 오브젝트를 돌려준다. 이 오브젝트의 메소드는, 오브젝트에 관한 정보의 취득에 사용한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_INVALIDPARAM
DIERR_OBJECTNOTFOUND


DirectInputDevice.GetProperty

DirectInputDevice.GetProperty 메소드는, 입력 디바이스에 관한 정보를 취득한다.

object. GetProperty( _
  guid As String, _
  propertyInfo As Any)

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.
guid
취득하는 프로퍼티의 식별자. 입력 디바이스에는 다음의 프로퍼티가 정의되고 있어 캐릭터 라인으로서 건네줄 수가 있다.
DIPROP_AUTOCENTER
디바이스 오브젝트가 자동 센터링을 실시할지 어떨지를 지정한다. 상세한 것에 대하여는, 「DirectInputDevice.SetProperty 」를 참조할것.
DIPROP_AXISMODE
축모드를 취득한다. 취득되는 값은 DIPROPAXISMODE_ABS 또는 DIPROPAXISMODE_REL 이다 ( 「CONST_DINPUT 」열거를 참조).
DIPROP_BUFFERSIZE
입력 버퍼 사이즈를 취득한다. 버퍼 사이즈는,DirectInputDevice.GetDeviceData 메소드의 전회와 이번 호출동안에서, 버퍼가 데이터를 잃는 일 없이 보관 유지할 수 있는 데이터의 양을 결정한다. 이 값에 제로를 설정해, 어플리케이션이 디바이스로부터 버퍼링 데이터를 읽어들이지 않게 지정할 수도 있다.
DIPROP_DEADZONE
0 ~ 10,000 의 범위에서 죠이스틱의 무효 존의 값을 취득한다. 여기서, 0 은 무효 존이 존재하지 않는 것, 5,000 은 무효 존이 축을 중심으로 한 물리 범위의 50 퍼센트에까지 퍼지고 있는 것, 및 10,000 은 축의 물리 범위의 전체가 무효라는 점을 각각 가리킨다. 축이 무효 존내에 있으면(자), 축의 범위의 중심에 있는 것이라고 보고된다.
DIPROP_FFGAIN
디바이스의 게인을 취득한다. 상세한 것에 대하여는, 「DirectInputDevice.SetProperty 」를 참조할것.
DIPROP_FFLOAD
디바이스의 메모리 로드를 취득한다. 이 설정값은, 개별의 오브젝트는 아니고 디바이스 전체에 적용되므로, 할당할 수 있었던 DIPROPLONG 형의 lHow 멤버는 DIPH_DEVICE 가 아니면 안된다.

lData 멤버는, 0 ~ 100 의 범위에 있는 값을 저장 한다. 이 값은, 사용중의 디바이스 메모리의 퍼센트수를 나타낸다.

DIPROP_GRANULARITY
입력의 세분도를 취득한다. 세분도는, 오브젝트가 이동을 보고하는 최소 거리를 나타낸다. 많은 축오브젝트의 세분도는 1 이며, 모든 값을 취할 수가 있다. 축으로야는은, 보다 큰 세분도를 가지는 것도 있다. 예를 들어, 마우스의 휠축의 세분도는 20 으로 할 수도 있다. 보고되는 위치 변화는 모두, 20 의 배수가 된다. 즉, 유저가 휠을 천천히 회전시키면(자), 디바이스는 위치를 0, 20, 40 등이라고 보고한다.

이것은 읽기 전용 프로퍼티이므로,DirectInputDevice.SetProperty 메소드를 호출해도, 값을 설정할 수 없다.

DIPROP_RANGE
오브젝트를 보고할 수 있는 값의 범위를 취득한다. 취득된 최소 값 및 최대치는, 할당할 수 있었던 DIPROPRANGE 형의 lMin 및 lMax 멤버로 설정된다.

일부의 디바이스에서는, 이것은 읽기 전용 프로퍼티이다. DirectInputDevice.SetProperty 메소드를 호출해도, 값을 설정할 수 없다.

DIPROP_SATURATION
0 ~ 10,000 의 범위에서 죠이스틱의포화 존의 값을 취득한다. 포화 레벨이란, 축이 극한 위치에 있다고 보여지는 점이다. 예를 들어, 포화 레벨이 9,500 으로 설정되어 있는 경우, 축의 중심 (무효 존)으로부터 축의 구석까지의 물리적 거리의 95% 의 위치가 축의 극한 위치가 된다.
propertyInfo
단일의 값을 받는 DIPROPLONG 형. 또는, 1 조의 값을 받는 DIPROPRANGE 형. 이 형태의 lObj,lHow, 및 lSize 멤버는, 메소드를 호출하기 전에 초기화해야 한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_INVALIDPARAM
DIERR_OBJECTNOTFOUND
DIERR_UNSUPPORTED

참조

DirectInputDevice.SetProperty


DirectInputDevice.Poll

DirectInputDevice.Poll 메소드는, DirectInput 디바이스 위에의 폴링 대상 오브젝트로부터, 이용 가능한 데이터를 생성 한다. 디바이스에 폴링이 필요없을 때에 이 메소드를 호출해도, 이펙트는 일절 없다. 폴링 할 필요가 있는 디바이스가 정기적으로 폴링 되지 않는 경우, 이 디바이스로부터 새로운 데이터는 취득되지 않는다. 이 메소드를 호출하면, DirectInput 는 디바이스 상태를 갱신해, 버퍼링 데이터가 사용 가능한 경우는 입력 이벤트를 생성해, 통지가 유효하면 통지 이벤트를 설정한다.

object. Poll()

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_INPUTLOST
DIERR_NOTACQUIRED

주의

디바이스를 폴링 하기 전에,DirectInputDevice.SetDataFormat 메소드인가,DirectInputDevice.SetCommonDataFormat 메소드로 데이터 형식을 설정해,DirectInputDevice.Acquire 메소드로 디바이스를 취득해야 한다.


DirectInputDevice.RunControlPanel

DirectInputDevice.RunControlPanel 메소드는, 디바이스에 관련지을 수 있었던 컨트롤 패널의 프로퍼티 시트를 연다. 디바이스에 프로퍼티 시트를 관련지을 수 있지 않은 경우, 디폴트의 프로퍼티가 표시된다.

object. RunControlPanel(hwnd As Long)

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.
hwnd
부모 윈도우의 핸들. 이 파라미터가 제로라면, 부모 윈도우는 사용되지 않는다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 에러 코드가 설정된다.

DIERR_INVALIDPARAM


DirectInputDevice.SendDeviceData

DirectInputDevice.SendDeviceData 메소드는, 출력을 받아들이는 디바이스에 데이터를 송신한다. 디바이스는, 취득 끝난 상태가 아니면 안된다.

object. SendDeviceData(count As Long, _
  data() As DIDEVICEOBJECTDATA, _
  flags As CONST_DESDDFLAGS) As Long

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.
count
data 내의 요소수.
data
디바이스에 송신하는 데이터를 저장 한 DIDEVICEOBJECTDATA 형의 배열.

DIDEVICEOBJECTDATA 형의 lOfs 필드에는, 데이터의 송신지인 디바이스 오브젝트의 인스턴스 식별자 (데이터 오프셋(offset)는 아니다)를 저장 해야 한다 ( 「DirectInputDeviceObjectInstance.GetType 」를 참조). lTimeStamp 멤버와 lSequence 멤버는 제로가 아니면 안된다.

flags
데이터의 송신 방법을 제어하는 플래그. 제로 또는 다음의 값을 취할 수가 있다.
DISDD_CONTINUE
송신되는 디바이스 데이터는, 이전에 송신된 디바이스 데이터에 덧쓰기된다. 「주의」를 참조할것.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_INPUTLOST
DIERR_NOTACQUIRED
DIERR_REPORTFULL
DIERR_UNPLUGGED

주의

개별의 데이터 요소가 특정의 순서로 송신된다고 하는 보증은 없다. 그러나,SendDeviceData 의 호출이 성공했을 경우, 송신된 데이터의 사이에 다른 데이터가 섞여 올 것은 없다. 게다가 복수의 데이터가 1 회의 호출로 같은 오브젝트에 송신되는 경우, 어느 데이터가 송신될까는 특정되지 않는다.

예를 들어, 데이터를 패킷 단위로 송신할 수 있는 디바이스가 있다. 2 개의 정보를 기술하는 패킷을 각각 A 와 B 로 한다. 어플리케이션이 3 개의 데이터 요소 (B = 2, A = 1, B =0)를 송신하려고 하면(자) 어떻게 될까.

실제의 디바이스에 송신되는 패킷은, 1 개(살)이다. 패킷의 A 필드의 값은 1, 그리고 패킷의 B 필드의 값은 2 나 0 이 된다.

데이터를 지정대로 디바이스에 송신해야 하는 경우는,SendDeviceData 를 3 회 호출해, 호출할 것에 데이터 요소를 1 개씩 송신해야 한다.

최초의 호출해에 응답해, A 필드가 공백, B 필드의 값이 2 의 패킷을 디바이스에 송신한다.

2 번째의 호출에서는, A 필드의 값이 1, B 필드가 공백의 패킷을 송신한다.

마지막 3 번째의 호출로, A 필드가 공백, B 필드의 값이 0 의 패킷을 송신한다.

DISDD_CONTINUE 가 설정되어 있는 경우, 송신된 디바이스 데이터는 이전에 송신된 디바이스 데이터에 덧쓰기된다. 플래그의 설정이 없으면, 송신되는 디바이스 데이터는 완전히 새로운 것으로서 처리된다.

예를 들어, Button0 및 Button1 의 2 개의 버튼 출력을 지원 하는 디바이스가 있다고 한다. 어플리케이션이 최초로 SendDeviceData 를 호출해 "Button0 압하" 를 건네주면(자), 디바이스에는,"Button0 압하, Button1 미압하" 라고 하는 형식의 패킷이 송신된다. 다음에, 어플리케이션이 한번 더 SendDeviceData 를 호출해 "Button1 압하" 와 DISDD_CONTINUE 플래그를 건네주면(자), 디바이스에는,"Button0 압하, Button1 압하" 라고 하는 형식의 패킷이 송신된다. 그러나, 어플리케이션이 DISDD_CONTINUE 플래그를 건네주지 않았던 경우, 디바이스에 송신되는 패킷은,"Button0 미압하, Button1 압하" 가 된다.


DirectInputDevice.SendForceFeedbackCommand

DirectInputDevice.SendForceFeedbackCommand 메소드는, 디바이스의 force feedback 시스템에 커멘드를 송신한다.

object. SendForceFeedbackCommand(flags As Long)

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.
flags
목적 상태 변화를 나타내는 단일의 값. 이 값은,CONST_DISFFCFLAGS 열거의 멤버의 어느쪽이든을 취할 수가 있다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_INPUTLOST
DIERR_NOTACQUIRED
DIERR_REPORTFULL
DIERR_UNPLUGGED


DirectInputDevice.SetCommonDataFormat

DirectInputDevice.SetCommonDataFormat 메소드는, 표준 디바이스의 입력 데이터 형식을 설정한다.

object. SetCommonDataFormat( _
  format As CONST_DICOMMONDATAFORMATS)

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.
format
디바이스로 사용되는 데이터 형식을 식별하는 CONST_DICOMMONDATAFORMATS 열거의 언젠가.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_ACQUIRED
DIERR_INVALIDPARAM

주의

DirectInputDevice.Acquire 메소드로 디바이스를 취득하기 전에, 데이터 형식을 설정해야 한다. 데이터 형식은, 한 번 설정하는 것만으로 좋다. 데이터 형식은, 디바이스가 취득되고 있는 동안은 변경할 수 없다.

참조

DirectInputDevice.SetDataFormat


DirectInputDevice.SetCooperativeLevel

DirectInputDevice.SetCooperativeLevel 메소드는, 디바이스의 인스턴스에 협조 레벨을 설정한다. 협조 레벨은, 이 인스턴스가, 같은 디바이스외의 인스턴스, 및 시스템의 이외의 부분과의 사이로, 어떻게 대화할까를 결정한다.

object. SetCooperativeLevel(hwnd As Long, _
  flags As CONST_DISCLFLAGS)

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.
hwnd
디바이스에 관련지을 수 있고 있는 윈도우 핸들. 이 파라미터는, 이 프로세스에 속하는 최상정도의 유효한 윈도우 핸들이 아니면 안된다. 디바이스에 관련지을 수 있는 윈도우는, DirectInput 디바이스 중(안)에서 액티브한 사이는, 파괴해서는 안 된다.
flags
디바이스에 관련짓는 협조 레벨을 나타내는 플래그. CONST_DISCLFLAGS 열거의 정수이다.

다음의 플래그의 편성이 유효하다.
플래그 | 의미 | 대상
DISCL_NONEXCLUSIVE Or DISCL_BACKGROUND | 다른 어플리케이션은, 배타 모드 또는 비배타 모드에 있는 디바이스를 취득할 수 있다. 이 어플리케이션은, 데이터에 언제라도 액세스 할 수 있다. | 모두.
DISCL_NONEXCLUSIVE Or DISCL_FOREGROUND | 다른 어플리케이션은, 배타 모드 또는 비배타 모드에 있는 디바이스를 취득할 수 있다. 이 어플리케이션은, foreground에 있을 때 마셔 데이터에 액세스 할 수 있다. | 모두.
DISCL_EXCLUSIVE Or DISCL_BACKGROUND | 다른 어플리케이션은, 비배타 모드에 있는 디바이스를 취득할 수 있다. 이 어플리케이션은, 데이터에 언제라도 액세스 할 수 있다. | 죠이스틱.
DISCL_EXCLUSIVE Or DISC_FOREGROUND | 다른 어플리케이션은, 비배타 모드에 있는 디바이스를 취득할 수 있다. 이 어플리케이션은, foreground에 있을 때 마셔 데이터에 액세스 할 수 있다. | 모두. 마우스의 경우, 유효하지만 Windows 는 커서를 표시할 수 없다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_INVALIDPARAM
DIERR_INVALIDHANDLE

주의

2 개의 어플리케이션 (또는 동일 어플리케이션의 2 개의 인스턴스)이 동시에 1 개의 디바이스를 배타 모드로 취득할 수 없다. 이것은 주로 시큐러티면에서의 기능이다. 이것에 의해, 1 개의 어플리케이션으로부터의 입력이, 동시에 실행되고 있는 다른 어플리케이션에 흐를 것은 없다.

시스템 마우스가 배타 모드로 취득되면(자), 마우스 포인터는, 디바이스가 릴리즈 될 때까지 화면으로부터 소거된다.

어플리케이션은,DirectInputDevice.Acquire 메소드로 디바이스를 취득하기 전에, 이 메소드를 호출할 필요가 있다.

참조

협조 레벨


DirectInputDevice.SetDataFormat

DirectInputDevice.SetDataFormat 메소드는, 표준의 키보드나 마우스 이외의, DirectInput 디바이스의 데이터 형식을 설정한다.

object. SetDataFormat(format As DIDATAFORMAT, _
  formatArray() As DIOBJECTDATAFORMAT))

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.
format
디바이스가 돌려주는 데이터 형식을 나타내는 DIDATAFORMAT 형.
formatArray
디바이스 위에의 오브젝트의 데이터 형식을 나타내는 DIOBJECTDATAFORMAT 형의 배열.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_ACQUIRED
DIERR_INVALIDPARAM

주의

DirectInputDevice.Acquire 메소드로 디바이스를 취득하기 전에, 데이터 형식을 설정해야 한다. 데이터 형식은, 한 번 설정하는 것만으로 좋다. 데이터 형식은, 디바이스가 취득되고 있는 동안은 변경할 수 없다.

참조

DirectInputDevice.SetCommonDataFormat


DirectInputDevice.SetEventNotification

DirectInputDevice.SetEventNotification 메소드는, 이벤트 통지 스테이터스를 설정한다. 이 메소드는, 디바이스 상태가 변화했을 때에 설정되는 이벤트를 지정한다. 이벤트 통지를 오프로 하기 위해서(때문에)도 사용된다.

object. SetEventNotification(hEvent As Long)

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.
hEvent
디바이스 상태가 변화했을 때에 설정되는 이벤트의 핸들. 통지를 무효로 하려면 제로를 설정한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_ACQUIRED
DIERR_HANDLEEXISTS
DIERR_INVALIDPARAM

주의

디바이스 상태의 변경은 다음의 어느 쪽인가에 정의된다.

  • 축의 위치의 변경
  • 버튼 상태 (누른 상태 또는 떼어 놓은 상태)
  • 시점 컨트롤의 방향의 변경
  • 취득의 상실

이벤트 핸들을 파괴하기 전에,hEvent 파라미터에 제로를 설정해, 이 메소드를 호출하지 않으면 안 된다.

이벤트 통지 핸들은, 디바이스가 취득되고 있는 동안은 변경할 수 없다.

참조

폴링과 이벤트,DirectXEvent


DirectInputDevice.SetProperty

DirectInputDevice.SetProperty 메소드는, 디바이스의 동작을 정의하는 프로퍼티를 설정한다.

object. SetProperty( _
  guid As String, _
  propertyInfo As Any)

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.
guid
설정 대상의 프로퍼티의 식별자. 입력 디바이스에는 다음의 프로퍼티값이 정의되고 있어 캐릭터 라인으로서 건네줄 수가 있다.
DIPROP_AXISMODE
축모드를 설정한다. 설정값 (CONST_DINPUT 열거의 DIPROPAXISMODE_ABS 또는 DIPROPAXISMODE_REL) 은, 할당할 수 있었던 DIPROPLONG 형의 lData 멤버로 지정하지 않으면 안 된다.

이 설정값은 디바이스 전체에 적용되므로, 할당할 수 있었던 DIPROPLONG 형의 lHow 멤버는 DIPH_DEVICE 가 아니면 안된다.

DIPROP_BUFFERSIZE
입력 버퍼 사이즈를 설정한다. 「주의」를 참조할것.

이 설정값은 디바이스 전체에 적용되므로, 할당할 수 있었던 DIPROPLONG 형의 lHow 멤버는 DIPH_DEVICE 가 아니면 안된다.

DIPROP_CALIBRATIONMODE
DirectInput 가 취득하는 데이터가, calibration가 끝난 상태나 calibration전인지를, 어플리케이션을 지정할 수 있도록(듯이) 한다. 디폴트에서는, DirectInput 는 calibration 끝나 데이타를 뽑기 시작한다.

디바이스 전체에 대해서 calibration 모드를 설정하는 것은, 각각의 축으로 대해 calibration 모드를 설정하는 것으로 같은 의미를 가진다.

DIPROPLONG 형의 lData 멤버는 다음의 어느쪽이든 1 개의 값을 취할 수가 있다.

DIPROPCALIBRATIONMODE_COOKED:DirectInput 는, calibration 정보의 적용 후의 데이터를 돌려준다. 이것이 디폴트 모드이다.

DIPROPCALIBRATIONMODE_RAW:DirectInput 는, calibration전의 미가공 데이터를 돌려준다. 이 모드는 보통, 컨트롤 패널형의 어플리케이션에서만 사용된다.

디바이스를 미가공 모드로 설정 하면, 무효 존, 포화값, 및 범위의 설정이 무시된다.

DIPROP_DEADZONE
0 ~ 10,000 의 범위에서 죠이스틱의 무효 존의 값을 설정한다. 여기서, 0 은 무효 존이 존재하지 않는 것, 5,000 은 무효 존이 축을 중심으로 한 물리 범위의 50 퍼센트에까지 퍼지고 있는 것, 및 10,000 은 축의 물리 범위의 전체가 무효라는 점을 각각 가리킨다. 축이 무효 존내에 있으면(자), 축의 범위의 중심에 있는 것이라고 보고된다.

이 설정은, 디바이스 전체 또는 1 개의 특정의 축의 어딘가에 적용할 수 있다.

DIPROP_RANGE
오브젝트가 보고 가능한 값의 범위를 설정한다. 최소 값 및 최대치는, 할당할 수 있었던 DIPROPRANGE 형의 lMin 멤버와 lMax 멤버로부터 취득된다.

일부의 디바이스에서는, 이것은 읽기 전용 프로퍼티이다.

범위의 대소를 반대로는 할 수 없다. lMax 는,lMin 보다 크지 않으면 안 된다.

DIPROP_SATURATION
0 ~ 10,000 의 범위에서 죠이스틱의포화 존의 값을 설정한다. 포화 레벨이란, 축이 극한 위치에 있다고 보여지는 점이다. 예를 들어, 포화 레벨이 9,500 으로 설정되어 있는 경우, 축의 중심 (무효 존)으로부터 축의 구석까지의 물리적 거리의 95% 의 위치가 축의 극한 위치가 된다.

이 설정은, 디바이스 전체 또는 1 개의 특정의 축의 어딘가에 적용할 수 있다.

propertyInfo
단일의 값을 취하는 프로퍼티의 데이터를 저장 하는 DIPROPLONG 형. 또는, 1 조의 값을 취하는 프로퍼티의 데이터를 저장 하는 DIPROPRANGE 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_INVALIDPARAM
DIERR_OBJECTNOTFOUND
DIERR_UNSUPPORTED

주의

버퍼 사이즈는,DirectInputDevice.GetDeviceData 메소드의 전회와 이번 호출동안에서, 버퍼가 데이터를 잃는 일 없이 보관 유지할 수 있는 데이터의 양을 결정한다. 이 값에 제로를 설정해, 어플리케이션이 디바이스로부터 버퍼링 데이터를 읽어들이지 않게 지정할 수도 있다. DIPROPLONG 형의 lData 멤버중의 버퍼 사이즈가 너무 커 디바이스가 지원 할 수 없는 경우는, 지원 가능한 최대 버퍼 사이즈가 설정된다. 요구한 버퍼 사이즈가 설정되었는지 어떠했는지를 확인하려면 , 버퍼 사이즈 프로퍼티를 취득해, 설정하려고 한 값과 그 결과를 비교한다.

참조

DirectInputDevice.GetProperty


DirectInputDevice.Unacquire

DirectInputDevice.Unacquire 메소드는, 입력 디바이스의 액세스권을 릴리즈 한다.

object. Unacquire()

파라미터

object
DirectInputDevice 오브젝트를 나타내는오브젝트식.

에러 코드

없음.

참조

DirectInputDevice.Acquire


DirectInputDeviceInstance

DirectInputDeviceInstance 클래스는, 디바이스의 인스턴스에 관한 정보의 취득에 사용된다.

이 클래스의 오브젝트는,DirectInputDevice.GetDeviceInfo 메소드와 DirectInputEnumDevices.GetItem 메소드에 의해 돌려주어진다.

DirectInputDeviceInstance 클래스에는, 다음의 메소드가 있다.

정보 | GetDevType
 | GetGuidFFDriver
 | GetGuidInstance
 | GetGuidProduct
 | GetInstanceName
 | GetProductName
 | GetUsage
 | GetUsagePage


DirectInputDeviceInstance.GetDevType

DirectInputDeviceInstance.GetDevType 메소드는, 디바이스 타입과 서브 타입을 취득한다.

object. GetDevType() As Long

파라미터

object
DirectInputDeviceInstance 오브젝트를 나타내는오브젝트식.

반환값

디바이스 타입 식별자가 돌려주어진다. 이 값은, 타입 (최하정도 바이트)과 서브 타입의 편성 (최하정도로부터 1 개 상위의 바이트)이며, 옵션으로 Or 를 사용해 DIDEVTYPE_HID 를 조합할 수 있다. 이 플래그는 HID (Human Interface Device)를 지정한다. 이하는,CONST_DIDEVICETYPE 열거의 정수이다.

디바이스 타입
DIDEVTYPE_MOUSE
마우스 또는 마우스 유사 디바이스 (트랙 볼 등).
DIDEVTYPE_KEYBOARD
키보드 또는 키보드 유사 디바이스.
DIDEVTYPE_JOYSTICK
죠이스틱 또는 유사 디바이스 (핸들 등).
DIDEVTYPE_DEVICE
위의 카테고리에 속하지 않는 디바이스.
마우스 서브 타입
DIDEVTYPEMOUSE_UNKNOWN
서브 타입은 확정할 수 없다.
DIDEVTYPEMOUSE_TRADITIONAL
디바이스는, 종래의 마우스이다.
DIDEVTYPEMOUSE_FINGERSTICK
디바이스는, FINGER 스틱이다.
DIDEVTYPEMOUSE_TOUCHPAD
디바이스는, 터치 패드이다.
DIDEVTYPEMOUSE_TRACKBALL
디바이스는, 트랙 볼이다.
키보드 서브 타입
DIDEVTYPEKEYBOARD_UNKNOWN
서브 타입은 확정할 수 없다.
DIDEVTYPEKEYBOARD_PCXT
IBM PC/XT 83 키 키보드
DIDEVTYPEKEYBOARD_OLIVETTI
Olivetti 102 키 키보드
DIDEVTYPEKEYBOARD_PCAT
IBM PC/AT 84 키 키보드
DIDEVTYPEKEYBOARD_PCENH
IBM PC 확장 101/102 키식 키보드 또는 Microsoft 내츄럴 키보드
DIDEVTYPEKEYBOARD_NOKIA1050
Nokia 1050 키보드
DIDEVTYPEKEYBOARD_NOKIA9140
Nokia 9140 키보드
DIDEVTYPEKEYBOARD_NEC98
일본어 NEC PC98 키보드
DIDEVTYPEKEYBOARD_NEC98LAPTOP
일본어 NEC PC98 랩탑 키보드
DIDEVTYPEKEYBOARD_NEC98106
일본어 NEC PC98 106 키 키보드
DIDEVTYPEKEYBOARD_JAPAN106
일본어 106 키 키보드
DIDEVTYPEKEYBOARD_JAPANAX
일본어 AX 키보드
DIDEVTYPEKEYBOARD_J3100
일본어 J3100 키보드
죠이스틱 서브 타입
DIDEVTYPEJOYSTICK_UNKNOWN
서브 타입은 확정할 수 없다.
DIDEVTYPEJOYSTICK_TRADITIONAL
종래의 죠이스틱.
DIDEVTYPEJOYSTICK_FLIGHTSTICK
플라이트 시뮬레이션용으로 최적화되고 있는 죠이스틱.
DIDEVTYPEJOYSTICK_GAMEPAD
주요 목적이 버튼 입력을 실시하는 것에 있는 디바이스.
DIDEVTYPEJOYSTICK_RUDDER
편요제어용의 디바이스.
DIDEVTYPEJOYSTICK_WHEEL
차의 핸들용의 디바이스.
DIDEVTYPEJOYSTICK_HEADTRACKER
유저의 머리의 움직임을 추적하는 디바이스.
HID
DIDEVTYPE_HID
디바이스는, HID (Human Interface Device) 프로토콜을 사용한다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

휠 등, 디바이스의 특정의 서브 타입을 찾으려면 , 타입과 서브 타입의 양쪽 모두를 체크할 필요가 있다.


DirectInputDeviceInstance.GetGuidFFDriver

DirectInputDeviceInstance.GetGuidFFDriver 메소드는, force feedback 드라이버의 일의인 식별자를 돌려준다.

object. GetGuidFFDriver() As String

파라미터

object
DirectInputDeviceInstance 오브젝트를 나타내는오브젝트식.

반환값

force feedback 드라이버의 GUID 가 캐릭터 라인 형식에서 돌려주어진다. 이 식별자는, 드라이버의 메이커가 정한다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

GUID 의 사용


DirectInputDeviceInstance.GetGuidInstance

DirectInputDeviceInstance.GetGuidInstance 메소드는, 디바이스의 인스턴스의 일의인 식별자를 돌려준다.

object. GetGuidInstance() As String

파라미터

object
DirectInputDeviceInstance 오브젝트를 나타내는오브젝트식.

반환값

디바이스 인스턴스의 GUID 가 캐릭터 라인 형식에서 돌려주어진다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

어플리케이션은, 이 인스턴스 GUID 를 구성 파일에 보존해, 다음에 사용할 수도 있다. 인스턴스 GUID 는, 컴퓨터 마다 고유하다. 1 개의 컴퓨터로부터 취득되는 인스턴스 GUID 는, 다른 컴퓨터 위에의 인스턴스 GUID 와는 무관계하다.

참조

DirectInputDeviceInstance.GetGuidProduct ,GUID 의 사용


DirectInputDeviceInstance.GetGuidProduct

DirectInputDeviceInstance.GetGuidProduct 메소드는, 디바이스에 대한 메이커의 일의인 식별자를 취득한다.

object. GetGuidProduct() As String

파라미터

object
DirectInputDeviceInstance 오브젝트를 나타내는오브젝트식.

반환값

제품의 GUID 가 캐릭터 라인 형식에서 돌려주어진다. 이 식별자는, 디바이스 메이커가 정한다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectInputDeviceInstance.GetGuidInstance ,GUID 의 사용


DirectInputDeviceInstance.GetInstanceName

DirectInputDeviceInstance.GetInstanceName 메소드는, 디바이스 인스턴스의 이름을 취득한다.

object. GetInstanceName() As String

파라미터

object
DirectInputDeviceInstance 오브젝트를 나타내는오브젝트식.

반환값

인스턴스의 등록명이 돌려주어진다. 예를 들어,"Joystick 1" 등.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectInputDeviceInstance.GetProductName


DirectInputDeviceInstance.GetProductName

DirectInputDeviceInstance.GetProductName 메소드는, 디바이스의 제품명을 취득한다.

object. GetProductName() As String

파라미터

object
DirectInputDeviceInstance 오브젝트를 나타내는오브젝트식.

반환값

제품의 등록명이 돌려주어진다. 예를 들어,"Microsoft SideWinder" 등.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectInputDeviceInstance.GetInstanceName


DirectInputDeviceInstance.GetUsage

DirectInputDeviceInstance.GetUsage 메소드는, HID (Human Interface Devices)의 사용 코드를 취득한다.

object. GetUsage() As Integer

파라미터

object
DirectInputDeviceInstance 오브젝트를 나타내는오브젝트식.

반환값

디바이스가 HID 인 경우, 사용 코드가 돌려주어진다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectInputDeviceInstance.GetUsagePage


DirectInputDeviceInstance.GetUsagePage

DirectInputDeviceInstance.GetUsagePage 메소드는, HID (Human Interface Devices)의 사용 페이지를 취득한다.

object. GetUsagePage() As Integer

파라미터

object
DirectInputDeviceInstance 오브젝트를 나타내는오브젝트식.

반환값

디바이스가 HID 인 경우, HID 사용 페이지가 돌려주어진다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectInputDeviceInstance.GetUsage


DirectInputDeviceObjectInstance

DirectInputDeviceObjectInstance 클래스는, 버튼이나 축 등, DirectInput 디바이스 위에의 오브젝트를 나타낸다.

DirectInputDeviceObjectInstance 오브젝트는,DirectInputDevice.GetObjectInfo 메소드와 DirectInputEnumDeviceObjects.GetItem 메소드에 의해 돌려주어진다.

이 클래스에는, 다음의 메소드가 있다.

정보 | GetCollectionNumber
 | GetDesignatorIndex
 | GetDimension
 | GetExponent
 | GetFlags
 | GetGuidType
 | GetName
 | GetOfs
 | GetType
 | GetUsage
 | GetUsagePage


DirectInputDeviceObjectInstance.GetCollectionNumber

DirectInputDeviceObjectInstance.GetCollectionNumber 메소드는, 디바이스 오브젝트의 소속처인 HID 링크 콜렉션의 번호를 취득한다.

object. GetCollectionNumber() As Integer

파라미터

object
DirectInputDeviceObjectInstance 오브젝트를 나타내는오브젝트식.

반환값

디바이스가 HID (Human Interface Device)이며, 오브젝트가 콜렉션에 속하고 있다면, 콜렉션의 번호가 돌려주어진다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectInputDeviceObjectInstance.GetDesignatorIndex

DirectInputDeviceObjectInstance.GetDesignatorIndex 메소드는, HID (Human Interface Device) 위에의 오브젝트의 지정 인덱스를 취득한다.

object. GetDesignatorIndex() As Integer

파라미터

object
DirectInputDeviceObjectInstance 오브젝트를 나타내는오브젝트식.

반환값

HID 물리 기술자의 지정을 참조하는 인덱스가 돌려주어진다. 이 수치는, 디바이스 오브젝트에 대한 추가 정보를 취득하기 위해서, HID 해석 라이브러리의 함수에게 건네진다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectInputDeviceObjectInstance.GetDimension

DirectInputDeviceObjectInstance.GetDimension 메소드는, 오브젝트의 값을 보고하는 차원 단위에 대한 HID 코드를 취득한다.

object. GetDimension() As Long

파라미터

object
DirectInputDeviceObjectInstance 오브젝트를 나타내는오브젝트식.

반환값

오브젝트의 값을 보고하는 차원 단위의 코드가 돌려주어진다 (판명하고 있는 경우). 불명한 경우는 제로가 된다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectInputDeviceObjectInstance.GetExponent


DirectInputDeviceObjectInstance.GetExponent

DirectInputDeviceObjectInstance.GetExponent 메소드는, 디바이스 오브젝트의 차원 단위에 관련짓는 지수를 취득한다.

object. GetExponent() As Integer

파라미터

object
DirectInputDeviceObjectInstance 오브젝트를 나타내는오브젝트식.

반환값

단위에 붙이는 지수가 돌려주어진다 (판명하고 있는 경우). 차원 단위는 항상 정수이므로, 정수 이외의 타입에 단위를 변환하려면 지수가 필요하다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectInputDeviceObjectInstance.GetDimension


DirectInputDeviceObjectInstance.GetFlags

DirectInputDeviceObjectInstance.GetFlags 메소드는, 디바이스 오브젝트에 관련지을 수 있었던 플래그를 취득한다.

object. GetFlags() As CONST_DIDEVICEOBJINSTANCEFLAGS

파라미터

object
DirectInputDeviceObjectInstance 오브젝트를 나타내는오브젝트식.

반환값

오브젝트의 그 외의 속성을 나타내는 플래그가 돌려주어진다. 반환값은,CONST_DIDEVICEOBJINSTANCEFLAGS 열거의 1 개 이상의 멤버로 구성된다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectInputDeviceObjectInstance.GetGuidType

DirectInputDeviceObjectInstance.GetGuidType 메소드는, 오브젝트 타입의 일의인 식별자를 취득한다.

object. GetGuidType() As String

파라미터

object
DirectInputDeviceObjectInstance 오브젝트를 나타내는오브젝트식.

반환값

오브젝트 타입의 일의인 식별자를 나타내는 다음의 캐릭터 라인 식별자중 한쪽이 돌려주어진다. 오브젝트 타입이 다음의 일람에 없는 GUID 를 가지는 경우, 실제의 GUID 를 나타내는 캐릭터 라인이 돌려주어진다. 오브젝트 타입이 GUID 를 가지지 않는 경우, 하늘의 캐릭터 라인이 돌려주어진다.

GUID_XAxis
수평축. 예를 들어, 마우스의 좌우의 움직임을 나타낼 수가 있다.
GUID_YAxis
수직축. 예를 들어, 마우스의 전후의 움직임을 나타낼 수가 있다.
GUID_ZAxis
z 축. 예를 들어, 마우스 위에의 휠의 회전, 또는 죠이스틱의 스롯톨 제어의 이동을 나타낼 수가 있다.
GUID_RxAxis
x 축을 중심으로 하는 회전.
GUID_RyAxis
y 축을 중심으로 하는 회전.
GUID_RzAxis
z 축을 중심으로 하는 회전 (방향타의 컨트롤로 자주(잘) 사용된다).
GUID_Slider
슬라이드축.
GUID_Button
마우스의 버튼.
GUID_Key
키보드 위에의 키.
GUID_POV
시점 인디케이터(indicator) 또는 시점 하트.
GUID_Unknown
확정할 수 없다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectInputDeviceObjectInstance.GetName

DirectInputDeviceInstance.GetName 메소드는, 디바이스 오브젝트의 이름을 취득한다.

object. GetName() As String

파라미터

object
DirectInputDeviceObjectInstance 오브젝트를 나타내는오브젝트식.

반환값

오브젝트의 이름이 돌려주어진다. 예를 들어,"X-Axis" 또는 "Right Shift" 등.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectInputDeviceObjectInstance.GetOfs

DirectInputDeviceObjectInstance.GetOfs 메소드는, 디바이스의 데이터 형식내의, 디바이스 오브젝트의 데이터의 오프셋(offset)를 취득한다.

object. GetOfs() As Long

파라미터

object
DirectInputDeviceObjectInstance 오브젝트를 나타내는오브젝트식.

반환값

데이터 형식내의 오프셋(offset)로, 이 오브젝트에 보고되는 데이터의 위치가 돌려주어진다. 이 값은, 메소드 호출해에 있어서의 오브젝트와 DIPH_BYOFFSET 플래그를 받는 타입안의 오브젝트를 식별하기 위해서 사용된다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectInputDevice.GetObjectInfo ,DIPROPLONG ,DIPROPRANGE


DirectInputDeviceObjectInstance.GetType

DirectInputDeviceObjectInstance.GetType 메소드는, 오브젝트의 타입과 일의인 식별자를 취득한다.

object. GetType() As Long

파라미터

object
DirectInputDeviceObjectInstance 오브젝트를 나타내는오브젝트식.

반환값

오브젝트를 나타내는 디바이스 타입. 오브젝트 타입 (축, 버튼등)을 나타내는 CONST_DIDFTFLAGS 플래그의 편성이며, 중앙의 16 비트에는, 오브젝트 인스턴스 번호가 저장 된다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

오브젝트 인스턴스 ID 를 취득하려면 , 다음의 처리를 실행한다.

Dim ObjID as Long
ObjID = (diObj.GetType And &HFFFF00) \ 256


DirectInputDeviceObjectInstance.GetUsage

DirectInputDeviceObjectInstance.GetUsage 메소드는, 디바이스 오브젝트에 대한 HID (Human Interface Devices)의 사용 코드를 취득한다.

object. GetUsage() As Integer

파라미터

object
DirectInputDeviceObjectInstance 오브젝트를 나타내는오브젝트식.

반환값

오브젝트에 관련하는 HID 사용 상황이 돌려주어진다 (판명되었을 경우). HID 는 항상 사용 상황을 보고한다. 비 HID 디바이스는 옵션으로 사용 상황을 보고한다. 비 HID 디바이스가 보고하지 않는 경우, 이 파라미터의 값은 제로가 된다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectInputDeviceObjectInstance.GetUsagePage


DirectInputDeviceObjectInstance.GetUsagePage

DirectInputDeviceObjectInstance.GetUsagePage 메소드는, 디바이스 오브젝트에 대한 HID (Human Interface Devices)의 사용 페이지를 취득한다.

object. GetUsagePage() As Integer

파라미터

object
DirectInputDeviceObjectInstance 오브젝트를 나타내는오브젝트식.

반환값

오브젝트에 관련하는 HID 사용 페이지가 돌려주어진다 (판명되었을 경우). HID 는 항상 사용 페이지를 보고한다. 비 HID 디바이스는 옵션으로 사용 페이지를 보고한다. 비 HID 디바이스가 보고하지 않는 경우, 이 파라미터의 값은 제로가 된다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectInputDeviceObjectInstance.GetUsage


DirectInputEffect

DirectInputEffect 클래스의 오브젝트는, 어플리케이션이 생성하는 force feedback 이펙트를 나타낸다. 오브젝트를 생성 하려면 ,DirectInputDevice.CreateEffect 메소드를 사용한다.

이 클래스에는, 다음의 메소드가 있다.

정보 | GetEffectGuid
 | GetEffectStatus
 | GetParameters
조작 | Download
 | SetParameters
 | Start
 | Stop
 | Unload


DirectInputEffect.Download

DirectInputEffect.Download 메소드는, 디바이스에 이펙트를 배치한다. 그 이펙트가 디바이스상에 이미 존재하는 경우,DirectInputEffect.SetParameters 메소드로 설정된 값에 일치하도록(듯이), 기존의 이펙트가 갱신된다.

object. Download()

파라미터

object
DirectInputEffect 오브젝트를 나타내는오브젝트식.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_NOTINITIALIZED
DIERR_DEVICEFULL
DIERR_INCOMPLETEEFFECT
DIERR_INPUTLOST
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_INVALIDPARAM
DIERR_EFFECTPLAYING

주의

이 메소드를 성공시키려면 , 디바이스를 배타 협조 레벨로 취득해야 한다.

이펙트의 재생중에 이펙트를 갱신하는 것은 유효하다. 이 조작의 의미는,DirectInputEffect.SetParameters 의 레퍼런스 중(안)에서 설명되고 있다.


DirectInputEffect.GetEffectGuid

DirectInputEffect.GetEffectGuid 메소드는,DirectInputEffect 오브젝트가 나타내는 이펙트의 GUID 또는 GUID 앨리어스(alias)를 취득한다.

object. GetEffectGuid() As String

파라미터

object
DirectInputEffect 오브젝트를 나타내는오브젝트식.

반환값

DirectInputDevice.CreateEffect 에 건네주는 GUID 또는 앨리어스(alias)가 돌려주어진다 (예를 들어,"GUID_ConstantForce" 등).

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

GUID 의 사용


DirectInputEffect.GetEffectStatus

DirectInputEffect.GetEffectStatus 메소드는, 이펙트의 스테이터스를 취득한다.

object. GetEffectStatus() As Long

파라미터

object
DirectInputEffect 오브젝트를 나타내는오브젝트식.

반환값

이펙트의 스테이터스 플래그가 돌려주어진다. 값은 제로인가, 다음의 CONST_DIEGESFLAGS 열거의 정수의 어느쪽이든을 취할 수가 있다.

DIEGES_PLAYING
이펙트는 재생중이다.
DIEGES_EMULATED
이펙트는 에뮬레이트 된다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectInputEffect.GetParameters

DirectInputEffect.GetParameters 메소드는, 이펙트에 관한 정보를 취득한다.

object. GetParameters(effectinfo As DIEFFECT)

파라미터

object
DirectInputEffect 오브젝트를 나타내는오브젝트식.
effectinfo
이펙트 파라미터를 받는 DIEFFECT 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_INVALIDPARAM
DIERR_MOREDATA
DIERR_NOTINITIALIZED


DirectInputEffect.SetParameters

DirectInputEffect.SetParameters 메소드는, 이펙트의 특성을 설정한다.

object. SetParameters(effectinfo As DIEFFECT, flags As CONST_DIEPFLAGS)

파라미터

object
DirectInputEffect 오브젝트를 나타내는오브젝트식.
effectinfo
이펙트 파라미터를 저장 하는 DIEFFECT 형.
flags
이펙트 정보의 어느 부분을 설정하는지, 파라미터의 다운로드를 어떻게 처리하는지를 지정하는,CONST_DIEPFLAGS 열거로부터의 플래그.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_NOTINITIALIZED
DIERR_INCOMPLETEEFFECT
DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_EFFECTPLAYING

주의

어느 파라미터가 이펙트의 재생중에 동적으로 갱신할 수 있는지를 판정하려면 ,DirectInputEnumEffects.GetDynamicParams 메소드를 사용한다.

DirectInputEffect.SetParameters 메소드는, 자동적으로 이펙트를 다운로드하지만, 이 동작은, DIEP_NODOWNLOAD 플래그를 설정하는 것에 의해 억제할 수 있다. 자동 다운로드가 억제되고 있었을 경우,DirectInputEffect.Download 를 호출해 이펙트를 수동으로 다운로드할 수 있다.

이펙트의 재생중에 파라미터가 갱신되면(자), 이펙트의 시작시의 파라미터였는지와 같이, 새로운 파라미터가 유효하게 된다.

예를 들어, 3 초의 계속 시간을 가지는 주기적 이펙트가 시작 되고 있다고 한다. 2 초 후에, 이펙트의 방향이 변경된다. 그 후, 이펙트는 나머지의 1 초간은 새로울 방향으로 계속된다. 엔벌로프, 국면, 진폭등의 이펙트의 파라미터는, 방향이 변경되지 않았는지와 같이 속행된다.

앞의 예와 같은 상황으로, 이번은 2 초 후에 이펙트의 계속 시간이 1.5 초로 변경되었다고 하면, 이펙트는 정지한다.

보통, 드라이버가 재생중의 이펙트의 파라미터를 갱신할 수 없는 경우, 드라이버는 그 이펙트를 정지해, 파라미터를 갱신하고 나서 그 이펙트를 재개할 수가 있다. DIEP_NORESTART 플래그를 건네주면(자), 이 처리가 억제된다. 이펙트의 재생중에 드라이버가 이펙트의 파라미터를 갱신할 수 없을 때는, 에러 코드의 DIERR_EFFECTPLAYING 가 돌려주어져 파라미터는 갱신되지 않는다.

플래그 DIEP_NODOWNLOAD, DIEP_START, DIEP_NORESTART 중 2 개(살) 이상을 설정해선 안 된다 (아무것도 건네주지 않아도 좋다).

이 3 개의 플래그는, 다음에 나타내도록(듯이), 다운로드 처리와 플레이백 처리를 제어한다.

DIEP_NODOWNLOAD 를 설정 하면, 이펙트 파라미터는 갱신되지만, 디바이스에 다운로드는 되지 않는다.

DIEP_START 플래그를 설정 하면, 이펙트 파라미터는 갱신되어 디바이스에 다운로드된다. 그리고,DirectInputEffect.Start 메소드가 iterations 파라미터에 1 을 설정해, 플래그없이 불려 갔을 경우와 완전히 똑같이, 이펙트가 시동한다. DIEP_START 로 갱신 처리를 부가한 방법이 Start 메소드를 호출하는 방법보다 조금 고속으로 있다. 이것은 전자의 방법에서는, 디바이스에 송신하는 정보가 적어도 되기 때문에 있다.

DIEP_NODOWNLOAD 와 DIEP_START 의 어느쪽이나 설정되지 않고, 이펙트를 재생하고 있지 않을 때는, 파라미터는 갱신되어 디바이스에 다운로드된다.

DIEP_NODOWNLOAD 와 DIEP_START 의 어느쪽이나 설정되지 않고, 이펙트가 재생중 때는, 디바이스가 실행중 (온더 플라이) 갱신을 지원 하고 있으면, 파라미터는 갱신된다. 상기 이외의 경우, 처리는 DIEP_NORESTART 플래그 상태에 좌우된다. 이 플래그가 설정되어 있으면, 에러 코드 DIERR_EFFECTPLAYING 가 돌려주어진다. 이 플래그가 없으면, 이펙트는 정지해, 파라미터가 갱신되어 이펙트가 재개한다.


DirectInputEffect.Start

DirectInputEffect.Start 메소드는, 이펙트의 재생을 시작 한다. 이펙트가 이미 재생중이라면, 최초부터 시작 된다. 이펙트가 다운로드되어 있지 않은지, 또는 전회의 다운로드 이래, 변경되고 있는 경우는, 시작전에 이펙트가 다운로드된다. 이 처리는 디폴트로 행해진다. 이것을 억제하려면 , DIES_NODOWNLOAD 플래그를 건네주면 좋다.

object. Start(iterations As Long, flags As Long)

파라미터

object
DirectInputEffect 오브젝트를 나타내는오브젝트식.
iterations
연속해 이펙트를 재생하는 회수. 엔벌로프는, 반복 마다 재조정된다.

이펙트를 한 번만 재생하려면 , 1 을 건네준다. 이펙트를 명시적으로 정지할 때까지 반복 재생하려면,-1 를 건네준다. 이펙트를 명시적으로 정지할 때까지 엔벌로프를 재조정하지 않고 재생하려면 ,DirectInputEffect.SetParameters 메소드로 이펙트 파라미터를 변경해,DIEFFECT 의 lDuration 멤버를 -1 로 변경한다.

flags
디바이스가 이펙트를 어떻게 재생하는지를 나타내는,CONST_DIESFLAGS 열거의 플래그. 값은 제로 또는 다음의 플래그의 어느쪽이든을 지정한다.
DIES_SOLO
지정된 이펙트가 재생되기 전에, 디바이스 위에의 다른 모든 이펙트를 정지한다. 이 플래그를 생략 하면, 이펙트는, 디바이스상에서 이미 재생이 시작되어 있는 기존의 이펙트와 혼합되게 된다.
DIES_NODOWNLOAD
이펙트의 자동 다운로드를 실시하지 않는다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_INVALIDPARAM
DIERR_INCOMPLETEEFFECT
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED
DIERR_UNSUPPORTED

주의

이 메소드를 성공시키려면 , 디바이스를 배타 협조 레벨로 취득해야 한다.

여러 차례의 반복을 지원 하지 않는 디바이스도 있다.


DirectInputEffect.Stop

DirectInputEffect.Stop 메소드는, 재생중의 이펙트를 정지한다.

object. Stop()

파라미터

object
DirectInputEffect 오브젝트를 나타내는오브젝트식.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED

주의

이 메소드를 성공시키려면 , 디바이스를 배타 협조 레벨로 취득해야 한다.


DirectInputEffect.Unload

DirectInputEffect.Download 메소드는, 디바이스로부터 이펙트를 삭제한다. 이펙트가 재생되고 있는 경우, 이펙트는, 언로드되기 전에 자동적으로 정지한다.

object. Unload()

파라미터

object
DirectInputEffect 오브젝트를 나타내는오브젝트식.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED

주의

이 메소드를 성공시키려면 , 디바이스를 배타 협조 레벨로 취득해야 한다.


DirectInputEnumDeviceObjects

DirectInputEnumDeviceObjects 클래스는, 시스템에 인스톨 되고 있는 DirectInputDevice 오브젝트를 열거한다. 이 오브젝트는,DirectInputDevice.GetDeviceObjectsEnum 메소드를 호출한 결과적으로 생성 되어 데이터가 저장 된다.

이 클래스에는, 다음의 메소드가 있다.

정보 | GetCount
 | GetItem


DirectInputEnumDeviceObjects.GetCount

DirectInputEnumDeviceObjects.GetCount 메소드는,DirectInputEnumDeviceObjects 콜렉션에 포함되는 항목수를 돌려준다.

object. GetCount() As Long

파라미터

object
DirectInputEnumDeviceObjects 오브젝트를 나타내는오브젝트식.

반환값

디바이스에 대해서 열거된 디바이스 오브젝트의 수가 돌려주어진다.

에러 코드

없음.


DirectInputEnumDeviceObjects.GetItem

DirectInputEnumDeviceObjects.GetItem 메소드는, 지정한 디바이스 오브젝트를 나타내는 오브젝트를 취득한다.

object. GetItem(index As Long) _
  As DirectInputDeviceObjectInstance

파라미터

object
DirectInputEnumDeviceObjects 오브젝트를 나타내는오브젝트식.
index
취득하는 열거 항목의 인덱스.

반환값

DirectInputDeviceObjectInstance 오브젝트를 돌려준다. 이 오브젝트의 메소드는, 디바이스 오브젝트에 관한 정보의 취득에 사용한다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

DirectInputEnumDeviceObjects 에 포함되는 항목수를 취득하려면 , 우선 DirectInputEnumDeviceObjects.GetCount 메소드를 호출한다.


DirectInputEnumDevices

DirectInputEnumDevices 클래스는, 시스템에 인스톨 되고 있는 DirectInput 디바이스를 열거한다. 이 오브젝트는,DirectInput.GetDIEnumDevices 메소드를 호출한 결과적으로 생성 되어 데이터가 저장 된다.

이 클래스에는, 다음의 메소드가 있다.

정보 | GetCount
 | GetItem


DirectInputEnumDevices.GetCount

DirectInputEnumDevices.GetCount 메소드는,DirectInputEnumDevices 콜렉션에 포함되는 DirectInput 디바이스수를 돌려준다.

object. GetCount() As Long

파라미터

object
DirectInputEnumDevices 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectInputEnumDevices 콜렉션에 포함되는 DirectInput 디바이스의 수가 돌려주어진다.

에러 코드

없음.


DirectInputEnumDevices.GetItem

DirectInputEnumDevices.GetItem 메소드는, 열거된 디바이스에 대한 정보를 돌려준다.

object. GetItem(index As Long) As DirectInputDeviceInstance

파라미터

object
DirectInputEnumDevices 오브젝트를 나타내는오브젝트식.
index
DirectInputEnumDevices. 에 포함되는 특정의 DirectInput 데이터 항목.

반환값

DirectInputDeviceInstance 오브젝트를 돌려준다. 이 오브젝트의 메소드는, 디바이스에 관한 정보의 취득에 사용한다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

DirectInputEnumDevices 에 포함되는 항목수를 취득하려면 , 우선 DirectInputEnumDevices.GetCount 메소드를 호출한다.


DirectInputEnumEffects

DirectInputEnumEffects 클래스의 오브젝트는, 디바이스로 지원 되는 force feedback 이펙트의 콜렉션을 나타내, 이펙트에 관한 정보의 취득에 사용된다. 오브젝트를 생성 하려면 ,DirectInputDevice.GetEffectsEnum 메소드를 사용한다.

이 클래스에는, 다음의 메소드가 있다.

정보 | GetCount
 | GetDynamicParams
 | GetEffectGuid
 | GetName
 | GetStaticParams
 | GetType


DirectInputEnumEffects.GetCount

DirectInputEnumEffects.GetCount 메소드는, 콜렉션내의 열거된 이펙트수를 돌려준다.

object. GetCount() As Long

파라미터

object
DirectInputEnumEffects 오브젝트를 나타내는오브젝트식.

반환값

콜렉션내의 항목수가 돌려주어진다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectInputEnumEffects.GetDynamicParams

DirectInputEnumEffects.GetDynamicParams 메소드는, 이펙트를 정지하지 않고 DirectInputEffect.SetParameters 메소드로 변경할 수 있는 이펙트 파라미터에 대한 정보를 취득한다.

object. GetDynamicParams(i As Long) As CONST_DIEPFLAGS

파라미터

object
DirectInputEnumEffects 오브젝트를 나타내는오브젝트식.
i
콜렉션내의 이펙트의 인덱스 (1 이 기점).

반환값

이펙트의 재생중에 동적으로 갱신 가능한 파라미터를 나타내는 CONST_DIEPFLAGS 열거의 플래그가 돌려주어진다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectInputEffect.SetParameters


DirectInputEnumEffects.GetEffectGuid

DirectInputEnumEffects.GetEffectGuid 메소드는, 지원 되는 이펙트의 GUID 를 취득한다. 이 GUID 는,DirectInputDevice.CreateEffect 메소드에게 건네진다.

object. GetEffectGuid(i As Long) As String

파라미터

object
DirectInputEnumEffects 오브젝트를 나타내는오브젝트식.
i
콜렉션내의 이펙트의 인덱스 (1 이 기점).

반환값

GUID 가 캐릭터 라인 형식에서 돌려주어진다. 표준의 이펙트의 경우, 반환값은,"GUID_ConstantForce" 등의 앨리어스(alias)이다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

GUID 의 사용


DirectInputEnumEffects.GetName

DirectInputEnumEffects.GetName 메소드는, 이펙트의 이름을 취득한다.

object. GetName(i As Long) As String

파라미터

object
DirectInputEnumEffects 오브젝트를 나타내는오브젝트식.
i
콜렉션내의 이펙트의 인덱스 (1 이 기점).

반환값

"Constant Force" 등, 이펙트의 이름이 돌려주어진다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectInputEnumEffects.GetStaticParams

DirectInputEnumEffects.GetStaticParams 메소드는, 디바이스로 지원 되는 이펙트 파라미터에 관한 정보를 취득한다.

object. GetStaticParams(i As Long) As CONST_DIEPFLAGS

파라미터

object
DirectInputEnumEffects 오브젝트를 나타내는오브젝트식.
i
콜렉션내의 이펙트의 인덱스 (1 이 기점).

반환값

이펙트가 지원 하는 파라미터를 나타내는 CONST_DIEPFLAGS 열거의 플래그가 돌려주어진다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectInputEnumEffects.GetType

DirectInputEnumEffects.GetType 메소드는, 이펙트의 타입과 능력에 관한 정보를 취득한다.

object. GetType(i As Long) As CONST_DIEFTFLAGS

파라미터

object
DirectInputEnumEffects 오브젝트를 나타내는오브젝트식.
i
콜렉션내의 이펙트의 인덱스 (1 이 기점).

반환값

이펙트에 관한 정보를 나타내는 CONST_DIEFTFLAGS 열거의 플래그가 돌려주어진다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

이펙트 타입은 하위 바이트에 저장 되어 &HHF 와 AND 를 취하는 것으로, 비트 마다 취득된다.


형

여기에서는, 이하의 DirectInput 형을 설명한다.

  • DICONDITION
  • DICONSTANTFORCE
  • DIDATAFORMAT
  • DIDEVCAPS
  • DIDEVICEOBJECTDATA
  • DIEFFECT
  • DIENVELOPE
  • DIJOYSTATE
  • DIJOYSTATE2
  • DIKEYBOARDSTATE
  • DIMOUSESTATE
  • DIOBJECTDATAFORMAT
  • DIPERIODICFORCE
  • DIPROPLONG
  • DIPROPRANGE
  • DIRAMPFORCE


DICONDITION

DICONDITION 형은,DIEFFECT 형에 포함되는 force feedback 조건의 파라미터를 나타낸다.

Type DICONDITION
  lDeadBand As Long
  lNegativeCoefficient As Long
  lNegativeSaturation As Long
  lOffset As Long
  lPositiveCoefficient As Long
  lPositiveSaturation As Long
End Type

멤버

lDeadBand
0 ~ 10,000 의 범위에 있는, 조건이 액티브하지 않은 lOffset 주변의 영역. 즉,lOffset - lDeadBand 와 lOffset + lDeadBand 의 사이에서는, 조건은 액티브하지 않다.
lNegativeCoefficient
-10, 000 ~ +10. 000 의 범위에 있는, 오프셋(offset)의 부측의 계수 정수.

디바이스가 정과 부로 나누어진 계수를 지원 하고 있지 않는 경우,lNegativeCoefficient 값은 무시되어lPositiveCoefficient 값이 정부 양쪽 모두의 계수로서 사용된다.

lNegativeSaturation
0 ~ 10,000 의 범위에 있는, 오프셋(offset)의 부측의 최대 포스 출력.

디바이스가 포스의 포화값을 지원 하지 않는 경우, 이 멤버값은 무시된다.

디바이스가 정과 부로 나누어진 포화값을 지원 하고 있지 않는 경우,lNegativeSaturation 값은 무시되어lPositiveSaturation 값이 정부 양쪽 모두의 포화값으로서 사용된다.

lOffset
-10, 000 ~ +10. 000 의 범위에 있는, 조건의 오프셋(offset).
lPositiveCoefficient
-10, 000 ~ +10. 000 의 범위에 있는, 오프셋(offset)의 정측의 계수 정수.
lPositiveSaturation
0 ~ 10,000 의 범위에 있는, 오프셋(offset)의 정측의 최대 포스 출력.

디바이스가 포스의포화를 지원 하지 않는 경우, 이 멤버값은 무시된다.

주의

조건의 타입이 다르면, 파라미터의 의미도 다르지만, 기본적인 생각은, 조건에 기인하는 포스는,A(q - q0) 에 동일해진다고 하는 것이다. 여기서,A 는, 스케일링 계수,q 는 있는 거리이며,q0 는, 그 거리에 대한 중립값이다.

위의 단순한 식은, 데드 밴드에 제로 이외의 값이 지정되었을 경우는 조정해야 한다. 거리가 lOffset - lDeadBand 보다 작으면, 생성되는 포스는, 다음의 식에서 나타난다.

force = lNegativeCoefficient * (q - (lOffset - lDeadBand))

같이 거리가 lOffset + lDeadBand 보다 크면, 생성되는 포스는, 다음의 식에서 나타난다.

force = lPositiveCoefficient * (q - (lOffset + lDeadBand))

스프링 조건은, 축의 위치를 거리로서 사용한다.

댐퍼 조건은, 축의 속도를 거리로서 사용한다.

관성 조건은, 축의 가속도를 거리로서 사용한다.


DICONSTANTFORCE

DICONSTANTFORCE 형은,DIEFFECT 형에 포함되는 정수 포스의 파라미터를 나타낸다.

Type DICONSTANTFORCE
  lMagnitude As Long
End Type

멤버

lMagnitude
-10. 000 ~ +10. 000 의 범위에 있는, 이펙트의 매그니튜드. 엔벌로프가 이 이펙트에 적용되고 있으면, 이 값은,유지 기간의 매그니튜드를 나타낸다. 엔벌로프의 적용이 없으면, 이 값은, 이펙트 전체의 진폭을 나타낸다.


DIDATAFORMAT

DIDATAFORMAT 형은, 디바이스의 데이터 형식을 나타내는 정보를 저장 한다. 이 형태는,DirectInputDevice.SetDataFormat 메소드로 사용된다.

Type DIDATAFORMAT
    dataSize As Long
    lFlags As Long
    lObjSize As Long
    numObjs As Long
End Type

멤버

dataSize
디바이스가 돌려주는 데이터 패킷의 바이트 단위의 사이즈. 이 값은, 4 의 배수이며, 한편 데이터 패킷내의 오브젝트 데이터의 최대 오프셋(offset)값보다 크지 않으면 안 된다.
lFlags
데이터 형식외의 속성을 나타내는 플래그. 이 값은,CONST_DIDATAFORMATFLAGS 열거의 어느쪽이든을 취할 수가 있다.
lObjSize
DIOBJECTDATAFORMAT 형의 바이트 단위의 사이즈.
numObjs
돌려주어지는 데이터의 오브젝트수.

주의

어플리케이션이 DIDATAFORMAT 형을 생성 할 필요가 있는 것은, 표준 이외의 디바이스를 사용하는 경우뿐이다. 마우스, 키보드, 및 죠이스틱의 경우는,DirectInputDevice.SetCommonDataFormat 로 데이터 형식을 설정한다.


DIDEVCAPS

DIDEVCAPS 형은, DirectInput 디바이스의 능력에 관한 정보를 저장 한다. 이 형태는,DirectInputDevice.GetCapabilities 메소드로 사용된다.

Type DIDEVCAPS
    lAxes As Long
    lButtons As Long
    lDevType As CONST_DIDEVICETYPE
    lDriverVersion As Long
    lFFMinTimeResolution As Long
    lFFSamplePeriod As Long
    lFirmwareRevision As Long
    lFlags As CONST_DIDEVCAPSFLAGS
    lHardwareRevision As Long
    lPOVs As Long
End Type

멤버

lAxes
디바이스상에서 사용 가능한 축의 수.
lButtons
디바이스상에서 사용 가능한 버튼의 수.
lDevType
디바이스의 타입과 서브 타입에 관한 정보를 저장 한 팩값. DirectInputDeviceInstance.GetDevType 메소드가 돌려주는 것과 동일한 값이다.
lDriverVersion
디바이스 드라이버의 버젼 번호.
lFFMinTimeResolution
force feedback 이펙트의 재생시에 디바이스가 분해 가능한 최소 시간 (마이크로 세컨드 단위). 디바이스는, 모든 시간을 가장 가까운 증가값에 말다. 예를 들어,lFFMinTimeResolution 의 값이 1000 의 경우에는, 디바이스는 모든 시간을 가장 가까운 밀리 세컨드에 말다.
lFFSamplePeriod
미가공의 포스 커멘드를 연속해 재생할 때의, 재생 간격의 최소 시간.
lFirmwareRevision
디바이스의 펌 웨어 리버젼 번호.
lFlags
디바이스에 관련지을 수 있었던 플래그. CONST_DIDEVCAPSFLAGS 열거의 정수를 조합한 값이 된다.
lHardwareRevision
디바이스의 하드웨어 리버젼 번호.
lPOVs
디바이스상에서 사용 가능한 시점 콘트롤러의 수.

주의

버젼 번호의 붙이는 방법은 디바이스 메이커에 따라서 다르다. 확실한 것은, 새로운 버젼에는 이전의 버젼보다 큰 숫자가 붙는다, 라고 하는 것 뿐이다.


DIDEVICEOBJECTDATA

DIDEVICEOBJECTDATA 형은, 버퍼링 디바이스의 미가공의 정보를 저장 한다. 이 형태는,DirectInputDevice.GetDeviceData 메소드로 사용된다.

Type DIDEVICEOBJECTDATA
    lData As Long
    lOfs As Long
    lSequence As Long
    lTimeStamp As Long
End Type

멤버

lData
디바이스로부터 취득되는 데이터.

축으로부터의 입력의 경우, 디바이스가 상대축모드에 있으면, 상대축의 움직임이 보고된다. 디바이스가 절대축모드에 있으면, 절대 좌표가 보고된다.

버튼으로부터의 입력의 경우,lData 의 하위 바이트만이 의미가 있다. 하위 바이트의 상위 비트는, 버튼이 다운 상태의 경우로 설정되어 업 상태의 경우에 소거된다.

lOfs
보고되고 있는 데이터가 속하는 오브젝트의 현재의 데이터 형식에 대한 오프셋(offset). 즉,DirectInputDevice.GetDeviceStateX 메소드 (GetDeviceStateMouse 등,X 는 특정의 디바이스를 가리킨다)를 호출해 데이터를 취득했을 경우에, 데이터가 저장 되고 있는 장소. 디바이스가 키보드로서 액세스 되는 경우, 이 값을 CONST_DIKEYFLAGS 열거의 멤버와 비교하는 것으로, 어느 키가 이벤트를 생성했는지를 판정할 수 있다. 마우스나 죠이스틱의 경우,lOfs 의 값은,DIMOUSESTATE ,DIJOYSTATE , 또는 DIJOYSTATE2 형 (DirectInputDevice.SetCommonDataFormat 로 설정된 데이터 형식에 의해 다르다)에 포함되는 축 또는 버튼의 바이트 오프셋(offset)와 동일하다. 이러한 오프셋(offset)의 정수는,CONST_DIMOUSEOFS 열거 및 CONST_DIJOYSTICKOFS 열거에 포함된다. DirectInputDevice.SetDataFormat 로 커스텀 데이터 형식이 설정되어 있었을 경우,lOfs 는, 커스텀 데이터 형식내의 디바이스 오브젝트의 장소의 오프셋(offset)이다.
lSequence
이 이벤트에 대한 DirectInput 순서 번호. 모든 입력 이벤트에는, 승순의 순서 번호를 할당할 수 있고 있다. 이것에 의해, 다른 디바이스로부터의 이벤트를 시간순서에 소트 하는 것이 가능하게 된다. 이 값은, 순환해 초기값에 돌아오므로, 2 개의 순서 번호를 비교하는 경우에는 주의하지 않으면 안 된다.
lTimeStamp
입력 이벤트가 생성된 밀리 세컨드 단위의 시스템 시간. 이 값은, 약 50 일에 순환한다.


DIEFFECT

DIEFFECT 형은, force feedback 이펙트를 나타낸다. 이 형태는, 이펙트의 파라미터를 설정하기 위해서 DirectInputDevice.CreateEffect 메소드나 DirectInputEffect.SetParameters 메소드에게 건네진다. 이 형태에 포함되는 기존의 파라미터는,DirectInputEffect.GetParameters 메소드로 취득된다.

Type DIEFFECT
  bUseEnvelope As Long
  conditionFlags As CONST_DICONDITIONFLAGS
  conditionX As DICONDITION
  conditionY As DICONDITION
  constantForce As DICONSTANTFORCE
  envelope As DIENVELOPE
  lDuration As Long
  lFlags As Long
  lGain As Long
  lSamplePeriod As Long
  lStartDelay As Long
  lTriggerButton As Long
  lTriggerRepeatInterval As Long
  periodicForce As DIPERIODICFORCE
  rampForce As DIRAMPFORCE
  x As Long
  y As Long
End Type

멤버

bUseEnvelope
envelope 멤버에 기술되는엔벌로프가 이펙트에 적용되는 경우는 TRUE.
conditionFlags
CONST_DICONDITIONFLAGS 열거의 플래그. DirectX for Visual Basic 의 현재의 버젼에서는, 이 값은 제로이다.
conditionX
x 축의 조건의 파라미터를 나타내는 DICONDITION 형. 다른 형태의 이펙트에서는 무시된다.
conditionY
y 축의 조건의 파라미터를 나타내는 DICONDITION 형. 다른 형태의 이펙트에서는 무시된다.
constantForce
정수 포스의 파라미터를 나타내는 DICONSTANTFORCE 형. 다른 형태의 이펙트에서는 무시된다.
envelope
이펙트에 적용되는 엔벌로프의 파라미터를 나타내는 DIENVELOPE 형. bUseEnvelope 멤버가 TRUE 의 경우에게만 유효.
lDuration
마이크로 세컨드 단위의 이펙트의 계속 시간. -1 그렇다고 하는 값은, 무한의 계속 시간을 나타낸다. 무한의 계속 시간을 가지는 이펙트에엔벌로프가 적용되고 있으면,어택도 적용되어 무한의유지 기간도 적용되게 된다.
lFlags
제로, 또는 다른 멤버의 해석 방법을 지정하는 CONST_DIEFFFLAGS 열거의 멤버.
lGain
이펙트에 적용되는 게인. 0 ~ 10,000 의 범위에 있다. 게인이란, 이펙트의 전매그니튜드와 그 엔벌로프에 적용되는 스케일링 계수이다.
lSamplePeriod
디바이스가 이펙트를 샘플링 하는 기간 (마이크로 세컨드 단위). 즉, 포스에 있어서의 변화의 세분도. 이 값이 제로이면, 디폴트의 재생 샘플링 속도를 사용하는 것을 의미한다.

디바이스가 지정의 속도로 이펙트를 샘플링 할 수 없으면, 지정된 값에 가장 가까운 속도를 선택한다.

커스텀 샘플링 기간의 설정은, 특수 효과에 사용할 수 있다. 예를 들어, 싸인파를 의도적으로 큰 샘플링 레이트로 재생 하면, 거슬거슬 한 질감을 가져온다.

lStartDelay
DirectInputEffect.Start 를 호출하고 나서 이펙트를 재생하기 전에, 디바이스가 대기하는 시간 (마이크로 세컨드 단위). 이 값이 제로이면, 이펙트의 재생은 즉시 시작 된다.
lTriggerButton
이펙트를 방아쇠 하는 버튼의 오프셋(offset)값. CONST_DIJOYSTICKOFS 열거의 멤버의 어느쪽이든 1 개의 값을 취한다. 이펙트가 방아쇠 버튼을 가지지 않는 것을 나타내려면,-1 로 한다.
lTriggerRepeatInterval
버튼의 압하 및 계속 눌러 에 의해 이펙트가 방아쇠 되었을 때의, 1 회의 재생의 종료와 시작의 간격을 나타내는, 마이크로 세컨드 단위의 시간. 반복을 억제하려면 , 이 값을 -1 로 설정한다.

방아쇠의 반복을 지원 하지 않는 디바이스도 있다.

periodicForce
주기적 이펙트의 파라미터를 나타내는 DIPERIODICFORCE 형. 다른 형태의 이펙트에서는 무시된다.
rampForce
경사 포스의 파라미터를 나타내는 DIRAMPFORCE 형. 다른 형태의 이펙트에서는 무시된다.
x
이펙트의 방향. 많은 경우, 방향은 북쪽 (보통, y 축의 부측)으로부터의 회전량으로서 1/100 번단위로 나타내진다. 따라서, 제로라고 하는 값은, 유저의 정면에서 오는 포스를 나타내, 9000 이라고 하는 값은, 유저의 우측으로부터 오는 포스를 나타낸다. 이하와 같이 해석한다. 이 경우,y 는 제로이다.

lFlags 에 DIEFF_CARTESIAN 이 포함되어 있는 경우, 이것은 x 축위에의 상대 포스량을 나타내는 데카르트 좌표의 값이다. 예를 들어,x = -1 또한 y = 1 인 경우, 포스는, 남동 방향으로부터 온다. 상세한 것에 대하여는, 「이펙트의 방향」을 참조할것.

y
lFlags 에 DIEFF_CARTESIAN 이 포함되어 있는 경우, 이것은 y 축위에의 상대 포스량을 나타내는 데카르트 좌표의 값이다. 그 이외의 경우, 제로가 아니면 안된다.


DIENVELOPE

DIENVELOPE 형은,DIEFFECT 형에 포함되는 엔벌로프의 파라미터를 나타낸다.

Type DIENVELOPE
  lAttackLevel As Long
  lAttackTime As Long
  lFadeLevel As Long
  lFadeTime As Long
End Type

멤버

lAttackLevel
기선을 기준으로 하는 엔벌로프의 시점에 있어서의 진폭. 기선에 대한 상대값. 0 ~ 10,000 의 범위이다. 이펙트의 타입 고유 데이터가, 기선을 지정하고 있지 않으면, 진폭은 제로를 기준으로 한다.
lAttackTime
유지 기간 레벨에 도달하는데 필요한, 마이크로 세컨드 단위의 시간.
lFadeLevel
엔벌로프의 종점에서의 진폭. 기선에 대한 상대값. 0 ~ 10,000 의 범위이다. 이펙트의 타입 고유 데이터가, 기선을 지정하고 있지 않으면, 진폭은 제로를 기준으로 한다.
lFadeTime
페이드 레벨에 도달하는데 필요한 마이크로 세컨드 단위의 시간.


DIJOYSTATE

DIJOYSTATE 형은, 죠이스틱 디바이스 상태에 관한 정보를 저장 한다 ("죠이스틱" 에는, 게임패드나 핸들 등, 다른 콘트롤러도 포함된다). 이 형태는,DirectInputDevice.GetDeviceStateJoystick 메소드로 사용된다.

Type DIJOYSTATE
    buttons(0 To 31) As Byte
    POV(0 To 3) As Long
    rx As Long
    ry As Long
    rz As Long
    slider(0 To 1) As Long
    x As Long
    y As Long
    z As Long
End Type

멤버

buttons
버튼 상태의 배열. 바이트의 상위 비트는, 대응하는 버튼이 다운 상태에 있을 때 설정되어 버튼이 업 상태 또는 존재하지 않을 때에는 소거된다.
POV
최고 4 개(살)까지의 방향 콘트롤러 (시점 하트등)의 현재 위치. 이 정도치는, 북쪽으로부터 (유저의 정면측) 시계회전의 열매 각도의 100 배로 나타내진다. 중심 위치는 보통 -1 이라고 보고되지만, 이것에 대해서는 「주의」를 참조할것. 5 개의 위치 밖에 가지지 않는 인디케이터(indicator)의 경우, 콘트롤러의 값은 -1, 0, 9,000, 18,000, 27,000 의 어느쪽이든 1 개의 값을 취한다.
rx
죠이스틱의 x 축회전의 정보. 죠이스틱에 이 축이 없으면, 값은 제로이다.
ry
죠이스틱의 y 축회전의 정보. 죠이스틱에 이 축이 없으면, 값은 제로이다.
rz
죠이스틱의 z 축회전의 정보 (방향타의 컨트롤로 자주(잘) 불려 간다). 죠이스틱에 이 축이 없으면, 값은 제로이다.
slider
2 개의 추가축의 값. 그 의미는 죠이스틱에 의해 다르다. 이러한 값에 관한 의미 정보를 취득하려면 ,DirectInputDevice.GetObjectInfo 메소드를 사용한다.
x
죠이스틱의 x 축의 정보 (보통은, 스틱의 좌우의 움직임).
y
죠이스틱의 y 축의 정보 (보통은, 스틱의 전후의 움직임).
z
죠이스틱의 z 축의 정보 (보통은, 스롯톨 제어). 죠이스틱에 이 축이 없으면, 값은 제로이다.

주의

죠이스틱형의 액세스를 하려면 ,DirectInputDevice.SetCommonDataFormat 메소드를 호출해, DIFORMAT_JOYSTICK 형식 정수를 건네주는 것으로, 디바이스의 준비를 해야 한다.

축이 상대 모드인 경우는, 적절한 멤버가 위치의 변화량을 저장 한다. 절대 모드의 경우에는, 같은 멤버가 축의 절대 위치를 저장 한다.

POV 인디케이터(indicator)의 중심 위치를 65,535 라고 보고하는 드라이버도 있다. POV 인디케이터(indicator)가 중심 위치에 있을지 어떨지는, 다음과 같이 해 확인한다.

Dim POVCentered as Boolean
POVCentered = MyDijoystate.POV(0) And &HFFFF;

참조

DIJOYSTATE2


DIJOYSTATE2

DIJOYSTATE2 형은, 확장 기능부 죠이스틱 디바이스 상태에 관한 정보를 저장 한다. 이 형태는,DirectInputDevice.GetDeviceStateJoystick2 메소드로 사용된다.

이 형태는, force feedback 디바이스 등, 매우 특수한 콘트롤러전용의 형태이므로, 보통, 어플리케이션은 이 형태를 사용할 필요는 없다. 표준의 게임 콘트롤러의 경우,DirectInputDevice.GetDeviceStateJoystick 를 호출하는 것으로,DIJOYSTATE 형을 사용해 데이터를 취득한다.

Type DIJOYSTATE2
    buttons(0 To 31) As Byte
    frx As Long
    fry As Long
    frz As Long
    fslider(0 To 1) As Long
    fx As Long
    fy As Long
    fz As Long
    POV(0 To 3) As Long
    rx As Long
    ry As Long
    rz As Long
    slider(0 To 1) As Long
    vrx As Long
    vry As Long
    vrz As Long
    vslider(0 To 1) As Long
    vx As Long
    vy As Long
    vz As Long
    x As Long
    y As Long
    z As Long
End Type

멤버

buttons
버튼 상태의 배열. 바이트의 상위 비트는, 대응하는 버튼이 다운 상태에 있을 때 설정되어 버튼이 업 상태 또는 존재하지 않을 때에는 소거된다.
frx
x 축토르크의 정보.
fry
y 축토르크의 정보.
frz
z 축토르크의 정보.
fslider
추가축의 포스의 정보.
fx
x 축포스의 정보.
fy
y 축포스의 정보.
fz
z 축포스의 정보.
POV
최고 4 개(살)까지의 방향 콘트롤러 (시점 하트등)의 현재 위치. 이 정도치는, 북쪽으로부터 (유저의 정면측) 시계회전의 열매 각도의 100 배로 나타내진다. 중심 위치는 보통 -1 이라고 보고되지만, 이것에 대해서는 「주의」를 참조할것. 5 개의 위치 밖에 가지지 않는 인디케이터(indicator)의 경우, 콘트롤러의 값은 -1, 0, 9,000, 18,000, 27,000 의 어느쪽이든 1 개의 값을 취한다.
rx
죠이스틱의 x 축회전의 정보. 죠이스틱에 이 축이 없으면, 값은 제로이다.
ry
죠이스틱의 y 축회전의 정보. 죠이스틱에 이 축이 없으면, 값은 제로이다.
rz
죠이스틱의 z 축회전의 정보 (방향타의 컨트롤로 자주(잘) 불려 간다). 죠이스틱에 이 축이 없으면, 값은 제로이다.
slider
2 개의 추가축의 값. 그 의미는 죠이스틱에 의해 다르다. 이러한 값에 관한 의미 정보를 취득하려면 ,DirectInputDevice.GetObjectInfo 메소드를 사용한다.
vrx
x 축각속도의 정보.
vry
y 축각속도의 정보.
vrz
z 축각속도의 정보.
vslider[0 To 1]
추가축의 속도의 정보.
vx
x 축속도의 정보.
vy
y 축속도의 정보.
vz
z 축속도의 정보.
x
죠이스틱의 x 축의 정보 (보통은, 스틱의 좌우의 움직임).
y
죠이스틱의 y 축의 정보 (보통은, 스틱의 전후의 움직임).
z
죠이스틱의 z 축의 정보 (보통은, 스롯톨 제어). 죠이스틱에 이 축이 없으면, 값은 제로이다.

주의

확장 기능부의 죠이스틱에 액세스 하려면 ,DirectInputDevice.SetCommonDataFormat 메소드를 호출해, DIFORMAT_JOYSTICK2 데이터 형식 변수를 건네주는 것으로, 디바이스의 준비를 해야 한다.

축이 상대 모드인 경우는, 적절한 멤버가 위치의 변화량을 저장 한다. 절대 모드의 경우에는, 같은 멤버가 축의 절대 위치를 저장 한다.

POV 인디케이터(indicator)의 중심 위치를 65,535 라고 보고하는 드라이버도 있다. POV 인디케이터(indicator)가 중심 위치에 있을지 어떨지는, 다음과 같이 해 확인한다.

Dim POVCentered as Boolean
POVCentered = MyDijoystate2.POV(0) And &HFFFF;


DIKEYBOARDSTATE

DIKEYBOARDSTATE 형은, 키보드의 키 상태에 관한 정보를 저장 한다. 이 형태는,DirectInputDevice.GetDeviceStateKeyboard 메소드로 사용된다.

Type DIKEYBOARDSTATE
    key(0 To 255) As Byte
End Type

멤버

key
버튼 상태의 배열. 이 배열에는,CONST_DIKEYFLAGS 열거의 멤버로 인덱스를 생성 할 수 있다. 각 키의 상위 비트는, 키가 다운 상태로 설정되어 업 상태 또는 존재하지 않는 경우에 소거된다.

주의

다음의 코드는,Esc 키가 밀리고 있는지 어떤지를 확인하는 예이다.

Dim keyState as DIKEYBOARDSTATE
' diDevice 는 유효한 DirectInputDevice 오브젝트이다.

Call diDevice.GetDeviceStateKeyboard(keyState)
If (keyState.key(DIK_ESCAPE) And &H80) Then
    '키는 압하되고 있다.
End If


DIMOUSESTATE

DIMOUSESTATE 형은, 마우스 디바이스 상태에 관한 정보, 또는 마우스 디바이스와 같이 액세스 되는 그 외의 디바이스 상태에 관한 정보를 저장 한다. 이 형태는,DirectInputDevice.GetDeviceStateMouse 메소드로 사용된다.

Type DIMOUSESTATE
    buttons(0 To 3) As Byte
    x As Long
    y As Long
    z As Long
End Type

멤버

buttons
버튼 상태의 배열. 바이트의 상위 비트는, 대응하는 버튼이 다운 상태에 있을 때 설정된다.
x
마우스의 x 축정보.
y
마우스의 y 축정보.
z
마우스의 z 축정보 (보통, 휠). 마우스에 z 축이 없으면, 이 값은 제로이다.

주의

DirectInputDevice.SetCommonDataFormat 메소드에 DIFORMAT_MOUSE 정수를 건네주는 것으로 준비해 있던 디바이스로부터는, 이 형태에 직접 데이터가 돌려주어진다.

축이 상대 모드인 경우는, 적절한 멤버가, 이 메소드를 전회에 호출한 이후의 위치의 변화량을 저장 한다. 축이 절대 모드인 경우는, 같은 멤버가, 임의의 시점에 대한 상대적인 움직임의 누적을 저장 한다. 따라서, 절대축위치는, 다른 절대축위치와 비교하는 경우를 제외해 무의미가 된다.


DIOBJECTDATAFORMAT

DIOBJECTDATAFORMAT 형에는,DirectInputDevice.SetDataFormat 메소드로 사용되는 디바이스 오브젝트의 데이터 형식에 관한 방법이 저장 된다.

Type DIOBJECTDATAFORMAT {
    lFlags As CONST_DIDEVICEOBJINSTANCEFLAGS
    lOfs As Long
    lType As CONST_DIDFTFLAGS
    strGuid As String
End Type

멤버

lFlags
제로, 또는 다음의 CONST_DIDEVICEOBJINSTANCEFLAGS 열거의 값.
DIDOI_ASPECTACCEL
DirectInput.SetDataFormat 로 선택된 오브젝트는, 가속도 정보를 보고한다.
DIDOI_ASPECTFORCE
DirectInput.SetDataFormat 로 선택된 오브젝트는, 포스 정보를 보고한다.
DIDOI_ASPECTPOSITION
DirectInput.SetDataFormat 로 선택된 오브젝트는, 위치 정보를 보고한다.
DIDOI_ASPECTVELOCITY
DirectInput.SetDataFormat 로 선택된 오브젝트는, 속도 정보를 보고한다.
lOfs
입력 소스의 데이터를 저장 하는 데이터 패킷내의 바이트 오프셋(offset). 이 값은, 축 등,Long 사이즈의 데이터에 맞도록(듯이), 4 의 배수가 아니면 안된다. 버튼의 경우는 바이트 정렬에서도 상관없다.
lType
오브젝트를 나타내는 디바이스 타입. 오브젝트 타입 (축, 버튼등)을 나타내는 CONST_DIDFTFLAGS 열거의 값의 편성이며, 중앙의 16 비트에는, 오브젝트 인스턴스 번호가 저장 된다.
strGuid
입력 소스의 타입에 대한 일의인 식별자. 하늘의 캐릭터 라인은, 모든 타입의 오브젝트가 허용 되는 것을 나타낸다.

다음의 캐릭터 라인은, 디바이스 오브젝트의 타입을 식별하기 위해서, 실제의 GUID 캐릭터 라인 대신에 사용할 수 있다.

GUID_XAxis
GUID_YAxis
GUID_ZAxis
GUID_RxAxis
GUID_RyAxis
GUID_RzAxis
GUID_Slider
GUID_Button
GUID_Key
GUID_POV


DIPERIODICFORCE

DIPERIODICFORCE 형은,DIEFFECT 형에 포함되는 주기적 포스의 파라미터를 나타낸다.

Type DIPERIODICFORCE
  lMagnitude As Long
  lOffset As Long
  lPhase As Long
  lPeriod As Long
End Type

멤버

lMagnitude
0 ~ 10.000 의 범위에 있는, 이펙트의 매그니튜드. 엔벌로프가 이 이펙트에 적용되고 있으면, 이 값은,유지 기간의 매그니튜드를 나타낸다. 엔벌로프의 적용이 없으면, 이 값은, 이펙트 전체의 진폭을 나타낸다.
lOffset
이펙트의 오프셋(offset). 이펙트가 생성하는 포스는,lOffset - lMagnitude 로부터 lOffset + lMagnitude 의 범위가 된다. lOffset 멤버의 값은, 이펙트에 적용되는 모든 엔벌로프에 대한 기선으로도 된다.
lPhase
0 ~ 35,999 의 범위내에 있는 주기적 이펙트의 재생 시작 위치. 「주의」를 참조할것.
lPeriod
마이크로 세컨드 단위의 이펙트의 주기.

주의

디바이스 드라이버는 lPhase 멤버의 모든 값을 지원 하고 있다고는 할 수 없다. 지원되어 있지 않은 값은, 바로 옆의 지원값에 말 수 있다.


DIPROPLONG

DIPROPLONG 형은, 프로퍼티가 단일의 값을 취하는 경우에,DirectInputDevice.SetProperty 메소드나 DirectInputDevice.GetProperty 메소드로, 입력 디바이스로 설정 또는 취득되는 프로퍼티 정보를 저장 하는데 사용한다.

Type DIPROPLONG
    lData As Long
    lHow As Long
    lObj As Long
    lSize As Long
End Type

멤버

lData
설정 또는 취득되는 프로퍼티 고유의 값.
lHow
lObj 파라미터의 해석 방법을 지정하는 값. 이 값은,CONST_DIPHFLAGS 열거의 멤버의 어느쪽이든을 취할 수가 있다.

lObj 가 DIPROP_AXISMODE 또는 DIPROP_BUFFERSIZE 인 경우, 이러한 프로퍼티는 개별의 오브젝트에는 설정할 수 없기 때문에,lHow 는 DIPH_DEVICE 가 아니면 안된다.

lObj
액세스 하는 프로퍼티가 속하는 오브젝트.

lHow 멤버가 DIPH_BYID 이면, 이 멤버는, 설정 또는 취득되는 프로퍼티를 가지는 오브젝트의 식별자로 한다. 이 값은,DirectInputDeviceObjectInstance.GetType 메소드를 사용해 오브젝트 마다 취득할 수 있다.

lHow 멤버가 DIPH_ BYOFFSET 이면, 이 멤버는, 설정 또는 취득되는 프로퍼티를 가지는 오브젝트의 데이터 형식 오프셋(offset)로 한다. 이 값은,DirectInputDeviceObjectInstance.GetOfs 메소드로 취득할 수 있다.

lHow 가 DIPH_DEVICE 인 경우, 이 값은 제로이다.

lSize
이 형태의 사이즈.

주의

SetProperty 메소드에 형태가 건네받기 전에, 모든 멤버를 적절한 값으로 초기화할 필요가 있다. GetProperty 메소드에 형태가 건네받기 전에,lData 를 제외하는 모든 멤버를 적절한 값으로 초기화할 필요가 있다.

참조

DIPROPRANGE


DIPROPRANGE

DIPROPRANGE 형은, 프로퍼티가 값의 범위를 취하는 경우에 DirectInputDevice.SetProperty 메소드나 DirectInputDevice.GetProperty 메소드로, 입력 디바이스로 설정 또는 취득되는 프로퍼티 정보를 저장 하기 위해서 사용한다.

Type DIPROPRANGE
    lHow As Long
    lMax As Long
    lMin As Long
    lObj As Long
    lSize As Long
End Type

멤버

lHow
lObj 멤버의 해석 방법을 지정하는 값. 이 값은,CONST_DIPHFLAGS 열거의 멤버의 어느쪽이든을 취할 수가 있다.
lMax
범위의 상한. 디바이스의 범위에 제한이 없으면,DirectInputDevice.GetProperty 메소드가 돌아올 때, 이 값은 DIPROPRANGE_NOMAX (CONST_DINPUT 열거의 값)가 된다.
lMin
범위의 하한. 디바이스의 범위에 제한이 없으면,DirectInputDevice.GetProperty 메소드가 돌아올 때, 이 값은 DIPROPRANGE_NOMIN (CONST_DINPUT 열거의 값)가 된다.
lObj
액세스 하는 프로퍼티가 속하는 오브젝트.

lHow 멤버가 DIPH_BYID 이면, 이 멤버는, 설정 또는 취득되는 프로퍼티를 가지는 오브젝트의 식별자로 한다. 이 값은,DirectInputDeviceObjectInstance.GetType 메소드를 사용해 오브젝트 마다 취득할 수 있다.

lHow 멤버가 DIPH_ BYOFFSET 이면, 이 멤버는, 설정 또는 취득되는 프로퍼티를 가지는 오브젝트의 데이터 형식 오프셋(offset)로 한다. 이 값은,DirectInputDeviceObjectInstance.GetOfs 메소드로 취득할 수 있다.

lHow 가 DIPH_DEVICE 인 경우, 이 값은 제로이다.

lSize
이 형태의 사이즈.

참조

DIPROPLONG


DIRAMPFORCE

DIRAMPFORCE 형은,DIEFFECT 형에 포함되는 경사 포스의 파라미터를 나타낸다.

Type DIRAMPFORCE
  lRangeEnd As Long
  lRangeStart As Long
End Type

멤버

lRangeEnd
-10, 000 ~ +10. 000 의 범위에 있는, 이펙트의 종점의 매그니튜드.
lRangeStart
-10, 000 ~ +10. 000 의 범위에 있는, 이펙트의 시점의 매그니튜드.

주의

경사 포스 이펙트의 계속 시간은 유한하지 않으면 안 된다.


열거

DirectInput 는, Visual Basic 의 스테이트먼트 보완 기능을 이용하기 위해서, 열거를 사용해 정수를 그룹화 한다. DirectInput 로 사용되는 열거는 다음과 같다.

  • CONST_DICOMMONDATAFORMATS
  • CONST_DICONDITIONFLAGS
  • CONST_DIDATAFORMATFLAGS
  • CONST_DIDEVCAPSFLAGS
  • CONST_DIDEVICEOBJINSTANCEFLAGS
  • CONST_DIDEVICETYPE
  • CONST_DIDFTFLAGS
  • CONST_DIDGDDFLAGS
  • CONST_DIEFFFLAGS
  • CONST_DIEFTFLAGS
  • CONST_DIEGESFLAGS
  • CONST_DIENUMDEVICESFLAGS
  • CONST_DIEPFLAGS
  • CONST_DIESFLAGS
  • CONST_DIGFFSFLAGS
  • CONST_DIJOYSTICKOFS
  • CONST_DIKEYFLAGS
  • CONST_DIMOUSEOFS
  • CONST_DINPUT
  • CONST_DINPUTERR
  • CONST_DIPHFLAGS
  • CONST_DISCLFLAGS
  • CONST_DISDDFLAGS
  • CONST_DISFFCFLAGS


CONST_DICOMMONDATAFORMATS

CONST_DICOMMONDATAFORMATS 열거의 멤버는,DirectInputDevice.SetCommonDataFormat 메소드의 format 파라미터에 데이터 형식을 지정하는데 사용한다.

Enum CONST_DICOMMONDATAFORMATS
    DIFORMAT_JOYSTICK =  3
    DIFORMAT_JOYSTICK2 = 4
    DIFORMAT_KEYBOARD =  1
    DIFORMAT_MOUSE =     2
End Enum
DIFORMAT_JOYSTICK
상태 데이터를 DIJOYSTATE 형에 받는 죠이스틱.
DIFORMAT_JOYSTICK2
상태 데이터를 DIJOYSTATE2 형에 받는 확장 기능부 죠이스틱.
DIFORMAT_KEYBOARD
상태 데이터를 DIKEYBOARDSTATE 형에 받는 키보드.
DIFORMAT_MOUSE
상태 데이터를 DIMOUSESTATE 형에 받는 마우스.


CONST_DICONDITIONFLAGS

CONST_DICONDITIONFLAGS 열거는, force feedback 이펙트의 축과 방향을 설정하기 위해서 DIEFFECT 형의 conditionFlags 멤버에 사용된다.

Enum CONST_DICONDITIONFLAGS
    DICONDITION_USE_BOTH_AXES = 1
    DICONDITION_USE_DIRECTION = 2
End Enum
DICONDITION_USE_BOTH_AXES
현재미지원이다.
DICONDITION_USE_DIRECTION
현재미지원이다.


CONST_DIDATAFORMATFLAGS

CONST_DIDATAFORMATFLAGS 열거는, 데이터 형식의 추가 속성을 나타내기 위해서(때문에) DIDATAFORMAT 형의 lFlags 멤버에 사용된다.

Enum CONST_DIDATAFORMATFLAGS
    DIDF_ABSAXIS = 1
    DIDF_RELAXIS = 2
End Enum
DIDF_ABSAXIS
축은 절대 모드에 있다. 이 플래그를 데이터 형식으로 설정하는 것은,DirectInputDevice.SetProperty 메소드를 사용해 축모드 프로퍼티를 수동으로 설정하는 것과 동일하다. 이 값을 DIDF_RELAXIS 플래그와 조합할 수 없다.
DIDF_RELAXIS
축은 상대 모드에 있다. 이 플래그를 데이터 형식으로 설정하는 것은,DirectInputDevice.SetProperty 메소드를 사용해 축모드 프로퍼티를 수동으로 설정하는 것과 동일하다. 이 값을 DIDF_ABSAXIS 플래그와 조합할 수 없다.


CONST_DIDEVCAPSFLAGS

CONST_DIDEVCAPSFLAGS 열거는, DirectInput 디바이스를 나타내기 위해서(때문에) DIDEVCAPS 형의 lFlags 멤버에 사용된다.

Enum CONST_DIDEVCAPSFLAGS
    DIDC_ATTACHED =              1
    DIDC_DEADBAND =          16384 (&H4000)
    DIDC_EMULATED =              4
    DIDC_FFATTACK =            512 (&H200)
    DIDC_FFFADE =             1024 (&H400)
    DIDC_FORCEFEEDBACK =       256 (&H100)
    DIDC_POLLEDDATAFORMAT =      8
    DIDC_POLLEDDEVICE =          2
    DIDC_POSNEGCOEFFICIENTS = 4096 (&H1000)
    DIDC_POSNEGSATURATION =   8192 (&H2000)
    DIDC_SATURATION =         2048 (&H800)
End Enum
DIDC_ATTACHED
디바이스는, 물리적으로Attach 되고 있다.
DIDC_DEADBAND
디바이스는, 적어도 1 개의 force feedback 조건으로 데드 밴드를 지원 하고 있다.
DIDC_EMULATED
이 플래그가 설정되면(자), 데이터는 유저 모드 디바이스 인터페이스 (HID 등), 또는 다른 링 3 의 수단에 의해 입력된다. 플래그가 설정되지 않는 경우, 데이터는 커널 모드 드라이버로부터 직접 입력된다.
DIDC_FFATTACK
force feedback 시스템은, 적어도 1 개의 이펙트에 대한어택 파라미터를 지원 한다. 디바이스가 어택을 지원 하지 않는 경우,DIENVELOPE 형의 lAttackLevel 멤버와 lAttackTime 멤버는, 디바이스에 의해 무시된다.
DIDC_FFFADE
force feedback 시스템은, 적어도 1 개의 이펙트에 대한페이드 파라미터를 지원 한다. 디바이스가 페이드를 지원 하지 않는 경우,DIENVELOPE 형의 lFadeLevel 멤버와 lFadeTime 멤버는, 디바이스에 의해 무시된다.
DIDC_FORCEFEEDBACK
디바이스는, force feedback를 지원 한다.
DIDC_POLLEDDATAFORMAT
현상의 데이터 형식에서 적어도 1 개의 오브젝트가, 세치기 구동은 아니고, 폴링 된다. 이러한 오브젝트의 경우, 어플리케이션은 데이터를 취득하기 위해서 DirectInputDevice.Poll 메소드를 명시적으로 호출하지 않으면 안 된다.
DIDC_POLLEDDEVICE
디바이스 위에의 적어도 1 개의 오브젝트가, 세치기 구동은 아니고, 폴링 된다. 이러한 오브젝트의 경우, 어플리케이션은 데이터를 취득하기 위해서 DirectInputDevice.Poll 메소드를 명시적으로 호출하지 않으면 안 된다. HID 디바이스는, 폴링 오브젝트와 비폴링 오브젝트를 혼재해 저장 할 수 있다.
DIDC_POSNEGCOEFFICIENTS
force feedback 시스템은, 적어도 1 개의 조건에 대해서 조건의 2 개의 계수값을 지원 한다 (한편은, 축의 정이동, 한편은, 축의 부이동). 디바이스가 양쪽 모두의 계수를 지원 하고 있지 않으면,DICONDITION 형의 부의 계수는 무시된다.
DIDC_POSNEGSATURATION
force feedback 시스템은, 적어도 1 개의 조건에 대해서, 정부의 양쪽 모두의 포스 출력에 대한 최대포화를 지원 한다. 디바이스가 양쪽 모두의 포화값을 지원 하고 있지 않으면,DICONDITION 형의 부의 포화값은 무시된다.
DIDC_SATURATION
force feedback 시스템은, 적어도 1 개의 조건에 대해서 조건 이펙트의포화를 지원 한다. 디바이스가 포화를 지원 하고 있지 않으면, 어느 조건아래에서 생성되는 포스는, 디바이스를 생성할 수 있는 최대 포스에 의해서만 제한된다.

참조

CONST_DIEFTFLAGS


CONST_DIDEVICEOBJINSTANCEFLAGS

CONST_DIDEVICEOBJINSTANCEFLAGS 열거의 멤버는, 디바이스 오브젝트의 능력을 나타내,DirectInputDeviceObjectInstance.GetFlags 메소드에 의해 돌려주어진다. 또,DirectInputDevice.SetDataFormat 메소드에게 건네지는 DIOBJECTDATAFORMAT 형내에도 존재한다.

Enum CONST_DIDEVICEINSTANCEFLAGS
    DIDOI_ASPECTACCEL =     768 (&H300)
    DIDOI_ASPECTFORCE =    1024 (&H400)
    DIDOI_ASPECTMASK =     3840 (&HF00)
    DIDOI_ASPECTPOSITION =  256 (&H100)
    DIDOI_ASPECTVELOCITY =  512 (&H200)
    DIDOI_FFACTUATOR =        1
    DIDOI_FFEFFECTTRIGGER =   2
    DIDOI_POLLED =        32768 (&H8000)
End Enum
DIDOI_ASPECTACCEL
오브젝트는 가속도 정보를 보고한다.
DIDOI_ASPECTFORCE
오브젝트는 포스 정보를 보고한다.
DIDOI_ASPECTMASK
어스펙트 정보를 보고하기 위한 비트. 1 개의 오브젝트는 최대 1 개의 어스펙트 밖에 나타낼 수가 없다.
DIDOI_ASPECTPOSITION
오브젝트는 위치 정보를 보고한다.
DIDOI_ASPECTVELOCITY
오브젝트는 속도 정보를 보고한다.
DIDOI_FFACTUATOR
오브젝트는, force feedback 이펙트를 자신에게 적용시킬 수가 있다.
DIDOI_FFEFFECTTRIGGER
오브젝트는, force feedback 이펙트의 재생을 방아쇠 한다.
DIDOI_POLLED
오브젝트는,DirectInputDevice.Poll 메소드가 불려 갈 때까지 데이터를 돌려주지 않는다.

주의

이러한 플래그 가운데, DirectX for Visual Basic 로 개발되는 어플리케이션에 필요한 것은, DIDIO_POLLED 뿐인다.


CONST_DIDEVICETYPE

CONST_DIDEVICETYPE 열거의 멤버는, 입력 디바이스의 타입과 서브 타입을 식별하기 위해서 사용된다. 타입과 서브 타입을 나타내는 팩값은,DirectInputDeviceInstance.GetDevType 메소드에 의해 돌려주어진다. 또,DirectInputDevice.GetCapabilities 가 돌려주는 DIDEVCAPS 형의 lDevType 멤버에 포함된다. 프라이머리 타입을 나타내는 값은,deviceType 파라미터로서 DirectInput.GetDIEnumDevices 메소드에게 건네진다.

타입과 서브 타입에 의해 리스트 되는 멤버의 일람에 대해서는, 「DirectInputDeviceInstance.GetDevType 」를 참조할것.

Enum CONST_DIDEVICETYPE
    DIDEVTYPE_DEVICE              = 1
    DIDEVTYPE_HID             = 65536 (&H10000)
    DIDEVTYPE_JOYSTICK            = 4
    DIDEVTYPE_KEYBOARD            = 3
    DIDEVTYPE_MOUSE               = 2
    DIDEVTYPEJOYSTICK_FLIGHTSTICK = 3
    DIDEVTYPEJOYSTICK_GAMEPAD     = 4
    DIDEVTYPEJOYSTICK_HEADTRACKER = 7
    DIDEVTYPEJOYSTICK_RUDDER      = 5
    DIDEVTYPEJOYSTICK_TRADITIONAL = 2
    DIDEVTYPEJOYSTICK_UNKNOWN     = 1
    DIDEVTYPEJOYSTICK_WHEEL       = 6
    DIDEVTYPEKEYBOARD_J3100      = 12
    DIDEVTYPEKEYBOARD_JAPAN106   = 10
    DIDEVTYPEKEYBOARD_JAPANAX    = 11
    DIDEVTYPEKEYBOARD_NEC98       = 7
    DIDEVTYPEKEYBOARD_NEC98106    = 9
    DIDEVTYPEKEYBOARD_NEC98LAPTOP = 8
    DIDEVTYPEKEYBOARD_NOKIA1050   = 5
    DIDEVTYPEKEYBOARD_NOKIA9140   = 6
    DIDEVTYPEKEYBOARD_OLIVETTI    = 2
    DIDEVTYPEKEYBOARD_PCAT        = 3
    DIDEVTYPEKEYBOARD_PCENH       = 4
    DIDEVTYPEKEYBOARD_PCXT        = 1
    DIDEVTYPEKEYBOARD_UNKNOWN     = 0
    DIDEVTYPEMOUSE_FINGERSTICK    = 3
    DIDEVTYPEMOUSE_TOUCHPAD       = 4
    DIDEVTYPEMOUSE_TRACKBALL      = 5
    DIDEVTYPEMOUSE_TRADITIONAL    = 2
    DIDEVTYPEMOUSE_UNKNOWN        = 1
End Enum
DIDEVTYPE_DEVICE
그 외의 카테고리에 속하지 않는 디바이스.
DIDEVTYPE_HID
디바이스는, HID (Human Interface Device) 프로토콜을 사용한다.
DIDEVTYPE_JOYSTICK
죠이스틱 또는 유사 디바이스 (핸들 등).
DIDEVTYPE_KEYBOARD
키보드 또는 키보드 유사 디바이스.
DIDEVTYPE_MOUSE
마우스 또는 마우스 유사 디바이스 (트랙 볼 등).
DIDEVTYPEJOYSTICK_FLIGHTSTICK
플라이트 시뮬레이션용으로 최적화되고 있는 죠이스틱.
DIDEVTYPEJOYSTICK_GAMEPAD
주요 목적이 버튼 입력을 실시하는 것에 있는 디바이스.
DIDEVTYPEJOYSTICK_HEADTRACKER
유저의 머리의 움직임을 추적하는 디바이스.
DIDEVTYPEJOYSTICK_RUDDER
편요제어용의 디바이스.
DIDEVTYPEJOYSTICK_TRADITIONAL
종래의 죠이스틱.
DIDEVTYPEJOYSTICK_UNKNOWN
서브 타입은 확정할 수 없다.
DIDEVTYPEJOYSTICK_WHEEL
차의 핸들용의 디바이스.
DIDEVTYPEKEYBOARD_J3100
일본어 J3100 키보드.
DIDEVTYPEKEYBOARD_JAPAN106
일본어 106 키 키보드.
DIDEVTYPEKEYBOARD_JAPANAX
일본어 AX 키보드.
DIDEVTYPEKEYBOARD_NEC98
일본어 NEC PC98 키보드.
DIDEVTYPEKEYBOARD_NEC98106
일본어 NEC PC98 106 키 키보드.
DIDEVTYPEKEYBOARD_NEC98LAPTOP
일본어 NEC PC98 랩탑 키보드.
DIDEVTYPEKEYBOARD_NOKIA1050
Nokia 1050 키보드.
DIDEVTYPEKEYBOARD_NOKIA9140
Nokia 9140 키보드.
DIDEVTYPEKEYBOARD_OLIVETTI
Olivetti 102 키 키보드.
DIDEVTYPEKEYBOARD_PCAT
IBM PC/AT 84 키 키보드.
DIDEVTYPEKEYBOARD_PCENH
IBM PC 확장 101/102 키식 키보드 또는 Microsoft 내츄럴 키보드.
DIDEVTYPEKEYBOARD_PCXT
IBM PC/XT 83 키 키보드.
DIDEVTYPEKEYBOARD_UNKNOWN
서브 타입은 확정할 수 없다.
DIDEVTYPEMOUSE_FINGERSTICK
디바이스는, FINGER 스틱이다.
DIDEVTYPEMOUSE_TOUCHPAD
디바이스는, 터치 패드이다.
DIDEVTYPEMOUSE_TRACKBALL
디바이스는, 트랙 볼이다.
DIDEVTYPEMOUSE_TRADITIONAL
디바이스는, 종래의 마우스이다.
DIDEVTYPEMOUSE_UNKNOWN
서브 타입은 확정할 수 없다.


CONST_DIDFTFLAGS

CONST_DIDFTFLAGS 열거의 멤버는, 열거하는 디바이스 오브젝트의 타입을 지정하기 위해서 DirectInputDevice.GetDeviceObjectsEnum 메소드의 flags 파라미터에 사용된다. 이러한 값은, 디바이스 오브젝트의 능력을 나타내기 위해서(때문에) DirectInputDeviceObjectInstance.GetFlags 메소드에 의해도 돌려주어진다.

Enum CONST_DIDFTFLAGS
    DIDFT_ABSAXIS         =        2
    DIDFT_ALL             =        0
    DIDFT_ANYINSTANCE     = 16776960 (&HFFFF00)
    DIDFT_AXIS            =        3
    DIDFT_BUTTON          =       12
    DIDFT_COLLECTION      =       64 (&H40)
    DIDFT_FFACTUATOR      = 16777216 (&H1000000)
    DIDFT_FFEFFECTTRIGGER = 33554432 (&H2000000)
    DIDFT_INSTANCEMASK    = 16776960(&HFFFF00)
    DIDFT_NOCOLLECTION    = 16776960 (&HFFFF00)
    DIDFT_NODATA          =      128 (&H80)
    DIDFT_POV             =       16 (&H10)
    DIDFT_PSHBUTTON       =        4
    DIDFT_RELAXIS         =        1
    DIDFT_TGLBUTTON       =        8
End Enum
DIDFT_ABSAXIS
절대축.
DIDFT_ALL
모든 오브젝트.
DIDFT_ANYINSTANCE
오브젝트의 임의의 인스턴스.
DIDFT_AXIS
절대축, 상대축의 어느 쪽인지.
DIDFT_BUTTON
푸쉬 버튼 또는 토글버튼.
DIDFT_COLLECTION
HID 링크 콜렉션. HID 링크 콜렉션은, 독자적인 데이터를 생성하지 않는다.
DIDFT_FFACTUATOR
force feedback 액츄에이터를 포함한 오브젝트. 즉, 포스를 이 오브젝트에 적용할 수가 있다.
DIDFT_FFEFFECTTRIGGER
force feedback 이펙트를 방아쇠 하기 위해서 사용할 수 있는 오브젝트.
DIDFT_INSTANCEMASK
DIDFT_ANYINSTANCE 와 같다.
DIDFT_NOCOLLECTION
모든 HID 링크 콜렉션에 속하지 않는, 즉,DirectInputDeviceObjectInstance.GetCollectionNumber 가 제로를 돌려주는 오브젝트.
DIDFT_NODATA
데이터를 생성하지 않는 오브젝트.
DIDFT_POV
시점 콘트롤러.
DIDFT_PSHBUTTON
푸쉬 버튼. 푸쉬 버튼은, 유저가 눌렀을 때에 다운, 유저가 떼어 놓았을 때에 업이라고 보고된다.
DIDFT_RELAXIS
상대축.
DIDFT_TGLBUTTON
토글버튼. 토글버튼은, 유저가 눌렀을 때에 다운이라고 보고되어 유저가 재차 그 버튼을 누를 때까지 그 상태에 머문다.


CONST_DIDGDDFLAGS

CONST_DIDGDDFLAGS 열거의 멤버는, 데이터의 취득 방법을 제어하기 위해서 DirectInputDevice.GetDeviceData 메소드의 flags 파라미터에 사용된다.

Enum CONST_DIDGDDFLAGS
    DIGDD_DEFAULT = 0
    DIGDD_PEEK    = 1
End Enum
DIGDD_DEFAULT
취득한 항목을 버퍼로부터 삭제한다.
DIGDD_PEEK
취득한 항목을 버퍼로부터 삭제하지 않는다. 이 이후의 GetDeviceData 호출로, 같은 데이터를 읽어낼 수가 있다.


CONST_DIEFFFLAGS

CONST_DIEFFFLAGS 열거의 멤버는,DIEFFECT 형의 lFlags 멤버에 사용된다.

Enum CONST_DIEFFFLAGS
    DIEFF_CARTESIAN =    16 (&H10)
    DIEFF_OBJECTOFFSETS = 2
    DIEFF_POLAR =        32 (&H20)
End Enum
DIEFF_CARTESIAN
이펙트의 방향은, 데카르트 좌표로 지정된다. DIEFFECT.x 와 DIEFFECT.y 에 유효한 값이 저장 된다.
DIEFF_OBJECTOFFSETS
DIEFFECT 의 lTriggerButton 멤버의 값은, 디바이스의 데이터 구조에 포함되는 버튼의 오프셋(offset)이다.
DIEFF_POLAR
이펙트의 방향은, 극좌표에서 지정된다. DIEFFECT.x 에 유효한 값이 저장 된다.

주의

DirectInputDevice.CreateEffect 및 DirectInputDevice.CreateCustomEffect 의 디폴트의 동작은,DIEFFECT.lFlags 에 (DIEFF_OBJECTOFFSETS Or DIEFF_POLAR)가 포함되는 경우와 같게, 이펙트를 생성한다. 즉, 이러한 플래그를 지정할 필요는 없다.


CONST_DIEFTFLAGS

CONST_DIEFTFLAGS 열거의 멤버는, force feedback 이펙트의 타입과 능력을 나타낸다. 이러한 멤버는,DirectInputDevice.GetEffectsEnum 메소드로 이펙트의 열거 대상을 1 개 이상의 프라이머리 타입에 제한하기 위해서 사용된다. 또,DirectInputEnumEffects.GetType 메소드에서도 이러한 멤버가 돌려주어진다.

Enum CONST_DIEFTFLAGS
    DIEFT_ALL =                   0
    DIEFT_CONDITION =             4
    DIEFT_CONSTANTFORCE =         1
    DIEFT_CUSTOMFORCE =           5
    DIEFT_DEADBAND =          16384 (&H4000)
    DIEFT_FFATTACK =            512 (&H200)
    DIEFT_FFFADE =             1024 (&H400)
    DIEFT_HARDWARE =            255 (&HFF)
    DIEFT_PERIODIC =              3
    DIEFT_POSNEGCOEFFICIENTS = 4096 (&H1000)
    DIEFT_POSNEGSATURATION =   8192 (&H2000)
    DIEFT_RAMPFORCE =             2
    DIEFT_SATURATION =         2048 (&H800)
End Enum
DIEFT_ALL
모든 이펙트를 열거한다.
DIEFT_CONDITION
이펙트는 조건이다. 또는, 조건을 열거한다.
DIEFT_CONSTANTFORCE
이펙트는 정수 포스이다. 또는, 정수 포스를 열거한다.
DIEFT_CUSTOMFORCE
이펙트는 커스텀 포스이다. 또는, 커스텀 포스를 열거한다.
DIEFT_DEADBAND
이펙트는 데드 밴드를 지원 한다.
DIEFT_FFATTACK
이펙트는 어택을 지원 한다.
DIEFT_FFFADE
이펙트는 페이드를 지원 한다.
DIEFT_HARDWARE
이펙트는 하드웨어에 고유하다. 또는, 하드웨어 이펙트를 열거한다.
DIEFT_PERIODIC
이펙트는 주기적이다. 또는, 주기적 이펙트를 열거한다.
DIEFT_POSNEGCOEFFICIENTS
조건은 정과 부의 계수를 개별적으로 지원 한다.
DIEFT_POSNEGSATURATION
이펙트는 정과 부의포화를 개별적으로 지원 한다.
DIEFT_RAMPFORCE
이펙트는 경사 포스이다. 또는, 경사 포스를 열거한다.
DIEFT_SATURATION
이펙트는 포화값을 지원 한다.

참조

CONST_DIDEVCAPSFLAGS


CONST_DIEGESFLAGS

CONST_DIEGESFLAGS 열거의 멤버는,DirectInputEffect.GetEffectStatus 메소드에 의해 돌려주어진다.

Enum CONST_DIEGESFLAGS
    DIEGES_EMULATED = 2
    DIEGES_PLAYING = 1
End Enum
DIEGES_EMULATED
이펙트는 에뮬레이트 된다.
DIEGES_PLAYING
이펙트는 재생중이다.


CONST_DIENUMDEVICESFLAGS

CONST_DIENUMDEVICESFLAGS 열거의 멤버는, 모든 디바이스를 열거하는지, 또는 Attach 된 디바이스만을 열거하는지를 지시하기 위해서,DirectInput.GetDIEnumDevices 메소드의 flags 파라미터에 사용된다.

Enum CONST_DIENUMDEVICESFLAGS
    DIEDFL_ALLDEVICES  = 0
    DIEDFL_ATTACHEDONLY = 1
End Enum
DIEDFL_ALLDEVICES
모든 인스톨이 끝난 디바이스가 열거된다. 이것이 디폴트 모드이다.
DIEDFL_ATTACHEDONLY
Attach 또한 인스톨이 끝난 디바이스만 열거된다.


CONST_DIEPFLAGS

CONST_DIEPFLAGS 열거의 멤버는, 설정 대상의 파라미터, 및 이펙트의 그 이후의 동작을 지정하기 위해서,DirectInputEffect.SetParameters 메소드에게 건네진다. 또, 일부의 멤버는, 파라미터의 지원에 관한 정보를 취득하는 DirectInputEnumEffects.GetStaticParams 메소드 및 DirectInputEnumEffects.GetDynamicParams 메소드에 의해 돌려주어진다.

Enum CONST_DIEPFLAGS
    DIEP_ALLPARAMS =            511 (&H1FF)
    DIEP_AXES =                  32 (&H20)
    DIEP_DIRECTION =             64 (&H40)
    DIEP_DURATION =               1
    DIEP_ENVELOPE =             128 (&H80)
    DIEP_GAIN =                   4
    DIEP_NODOWNLOAD =   -2147483648 (&H80000000)
    DIEP_NORESTART =     1073741824 (&H40000000)
    DIEP_SAMPLEPERIOD =           2
    DIEP_START =          536870912 (&H20000000)
    DIEP_TRIGGERBUTTON =          8
    DIEP_TRIGGERREPEATINTERVAL = 16 (&H10)
    DIEP_TYPESPECIFICPARAMS =   256 (&H100)
End Enum
DIEP_ALLPARAMS
미사용.
DIEP_AXES
미사용.
DIEP_DIRECTION
DIEFFECT 의 x 및 y 멤버가 유효하다. 또는, 방향 파라미터가 지원 된다. 이펙트 파라미터를 설정 또는 요구하고 있는 경우,DIEFFECT.lFlags 의 DIEFF_CARTESIAN 나 DIEFF_POLAR 를 지정하는 것으로, 데카르트 좌표 또는 극좌표의 어디에서 방향을 설정, 또는 취득하는지를 지정할 수 있다.
DIEP_DURATION
DIEFFECT 의 lDuration 멤버가 유효하다. 또는, 이펙트는 방향의 변경을 지원 한다.
DIEP_ENVELOPE
DIEFFECT 의 envelope 멤버가 유효하다. 또는, 이펙트는 엔벌로프의 적용을 지원 한다.
DIEP_GAIN
lGain 멤버가 유효하다. 또는, 이펙트는 게인의 적용을 지원 한다.
DIEP_NODOWNLOAD
파라미터의 설정 후, 이펙트를 다운로드하지 않는다.
DIEP_NORESTART
이펙트의 정지나 재개를 억제해 파라미터를 변경한다.
DIEP_SAMPLEPERIOD
lSamplePeriod 멤버가 유효하다.
DIEP_START
파라미터의 설정 후, 이펙트를 즉시 시작 한다.
DIEP_TRIGGERBUTTON
lTriggerButton 멤버가 유효하다. 또는, 이펙트는 방아쇠 버튼을 지원 한다.
DIEP_TRIGGERREPEATINTERVAL
lTriggerRepeatInterval 멤버가 유효하다. 또는, 이펙트는 방아쇠의 반복을 지원 한다.
DIEP_TYPESPECIFICPARAMS
이펙트는, 어플리케이션이 변경 가능한 타입 고유의 파라미터를 가진다. 이 값은, 모든 표준 이펙트와 어플리케이션에 의한 변경이 가능한 파라미터를 가지는 하드웨어 고유의 이펙트에 대해서,GetStaticParams 에 의해 돌려주어진다. DirectX for Visual Basic 는, 이 플래그가 설정되어 있지 않은 경우에게만 하드웨어 이펙트를 지원 한다.


CONST_DIESFLAGS

CONST_DIESFLAGS 는, force feedback 이펙트의 재생동작을 제어하기 위해서 사용된다.

Enum CONST_DIESFLAGS
    DIES_NODOWNLOAD  = -2147483648 (&H80000000)
    DIES_SOLO =                  1
End Enum
멤버의 설명에 대해서는, 「DirectInputEffect.Start 」를 참조할것.


CONST_DIGFFSFLAGS

CONST_DIGFFSFLAGS 열거의 멤버는, force feedback 디바이스 상태를 나타낸다. 이러한 멤버는,DirectInputDevice.GetForceFeedbackState 메소드에 의해 돌려주어진다.

Enum CONST_DIGFFSFLAGS
    DIGFFS_ACTUATORSOFF =        32 (&H20)
    DIGFFS_ACTUATORSON =         16 (&H10)
    DIGFFS_DEVICELOST = -2147483648 (&H80000000)
    DIGFFS_EMPTY =                1
    DIGFFS_PAUSED =               4
    DIGFFS_POWEROFF =           128 (&H80)
    DIGFFS_POWERON =             64 (&H40)
    DIGFFS_SAFETYSWITCHOFF =    512 (&H200)
    DIGFFS_SAFETYSWITCHON =     256 (&H100)
    DIGFFS_STOPPED =              2
    DIGFFS_USERFFSWITCHOFF =   2048 (&H800)
    DIGFFS_USERFFSWITCHON =    1024 (&H400)
End Enum
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 의 어느쪽이나 돌려주어지지 않다.


CONST_DIJOYSTICKOFS

CONST_DIJOYSTICKOFS 열거의 멤버는, 데이터 형식내의 다양한 죠이스틱 디바이스 오브젝트에 대한 데이터의 오프셋(offset)를 나타낸다.

Enum CONST_DIJOYSTICKOFS
    DIJOFS_BUTTON0 =  48 (&H30)
    DIJOFS_BUTTON1 =  49 (&H31)
    DIJOFS_BUTTON10 = 58 (&H3A)
    DIJOFS_BUTTON11 = 59 (&H3B)
    DIJOFS_BUTTON12 = 60 (&H3C)
    DIJOFS_BUTTON13 = 61 (&H3D)
    DIJOFS_BUTTON14 = 62 (&H3E)
    DIJOFS_BUTTON15 = 63 (&H3F)
    DIJOFS_BUTTON16 = 64 (&H40)
    DIJOFS_BUTTON17 = 65 (&H41)
    DIJOFS_BUTTON18 = 66 (&H42)
    DIJOFS_BUTTON19 = 67 (&H43)
    DIJOFS_BUTTON2 =  50 (&H32)
    DIJOFS_BUTTON20 = 68 (&H44)
    DIJOFS_BUTTON21 = 69 (&H45)
    DIJOFS_BUTTON22 = 70 (&H46)
    DIJOFS_BUTTON23 = 71 (&H47)
    DIJOFS_BUTTON24 = 72 (&H48)
    DIJOFS_BUTTON25 = 73 (&H49)
    DIJOFS_BUTTON26 = 74 (&H4A)
    DIJOFS_BUTTON27 = 75 (&H4B)
    DIJOFS_BUTTON28 = 76 (&H4C)
    DIJOFS_BUTTON29 = 77 (&H4D)
    DIJOFS_BUTTON3 =  51 (&H33)
    DIJOFS_BUTTON30 = 78 (&H4E)
    DIJOFS_BUTTON31 = 79 (&H4F)
    DIJOFS_BUTTON4 =  52 (&H34)
    DIJOFS_BUTTON5 =  53 (&H35)
    DIJOFS_BUTTON6 =  54 (&H36)
    DIJOFS_BUTTON7 =  55 (&H37)
    DIJOFS_BUTTON8 =  56 (&H38)
    DIJOFS_BUTTON9 =  57 (&H39)
    DIJOFS_POV0 =     32 (&H20)
    DIJOFS_POV1 =     36 (&H24)
    DIJOFS_POV2 =     40 (&H28)
    DIJOFS_POV3 =     44 (&H2C)
    DIJOFS_RX =       12
    DIJOFS_RY =       16 (&H10)
    DIJOFS_RZ =       20 (&H14)
    DIJOFS_SLIDER0 =  24 (&H18)
    DIJOFS_SLIDER1 =  28 (&H1C)
    DIJOFS_X =         0
    DIJOFS_Y =         4
    DIJOFS_Z =         8
End Enum
DIJOFS_BUTTON(n)
버튼 n 의 데이터의 오프셋(offset).
DIJOFS_POV(n)
시점 콘트롤러 n 의 데이터의 오프셋(offset).
DIJOFS_RX, DIJOFS_RY, DIJOFS_RZ
축회전의 데이터의 오프셋(offset).
DIJOFS_SLIDER0, DIJOFS_SLIDER1
슬라이더의 데이터의 오프셋(offset).
DIJOFS_X, DIJOFS_Y, DIJOFS_Z
축의 데이터의 오프셋(offset).


CONST_DIKEYFLAGS

CONST_DIKEYFLAGS 열거는,키보드 디바이스 정수를 그룹화 한다.


CONST_DIMOUSEOFS

CONST_DIMOUSEOFS 열거의 멤버는, 데이터 형식내의 다양한 마우스 디바이스 오브젝트에 대한 데이터의 오프셋(offset)를 나타낸다.

Enum CONST_DIMOUSEOFS
    DIMOFS_BUTTON0 = 12
    DIMOFS_BUTTON1 = 13
    DIMOFS_BUTTON2 = 14
    DIMOFS_BUTTON3 = 15
    DIMOFS_X =        0
    DIMOFS_Y =        4
    DIMOFS_Z =        8
End Enum
DIMOFS_BUTTON(n)
버튼 n 의 데이터의 오프셋(offset).
DIMOFS_X, DIMOFS_Y, DIMOFS_Z
축의 데이터의 오프셋(offset).


CONST_DINPUT

CONST_DINPUT 열거는, DirectInput 전체로 사용되는 다양한 정수를 저장 한다.

Enum CONST_DINPUT
    DIPROPAXISMODE_ABS =           0
    DIPROPAXISMODE_REL =           1
    DIPROPCALIBRATIONMODE_COOKED = 0
    DIPROPCALIBRATIONMODE_RAW =    1
    DIPROPRANGE_NOMAX =   2147483647 (&H7FFFFFFF)
    DIPROPRANGE_NOMIN =  -2147483648 (&H80000000)
End Enum
DIPROPAXISMODE_ABS
DirectInputDevice.GetProperty 및 DirectInputDevice.SetProperty 로 사용되어 절대축모드를 나타낸다.
DIPROPAXISMODE_REL
DirectInputDevice.GetProperty 및 DirectInputDevice.SetProperty 로 사용되어 상대축모드를 나타낸다.
DIPROPCALIBRATIONMODE_COOKED
DIPROP_CALIBRATIONMODE 프로퍼티의 설정으로 사용되어 calibration 정보의 적용 후에 DirectInput 가 축데이터를 돌려주는 것을 나타낸다.
DIPROPCALIBRATIONMODE_RAW
DIPROP_CALIBRATIONMODE 프로퍼티의 설정으로 사용되어 DirectInput 가 미가공의 calibration전의 축데이터를 돌려주는 것을 나타낸다. 이 모드는 보통, 컨트롤 패널형의 어플리케이션에서만 사용된다.
DIPROPRANGE_NOMAX
축의 범위에 상한이 없는 경우에 DirectInputDevice.GetProperty 로부터 돌려주어진다.
DIPROPRANGE_NOMIN
축의 범위에 하한이 없는 경우에 DirectInputDevice.GetProperty 로부터 돌려주어진다.


CONST_DINPUTERR

CONST_DINPUTERR 열거는, DirectInput 의 에러 코드를 저장 한다. 모든 에러 코드와 그 정의에 대해서는, 「에러 코드」에 기재되어 있다.


CONST_DIPHFLAGS

CONST_DIPHFLAGS 열거의 멤버는, 디바이스 오브젝트의 식별 방법을 지정하기 위해서 사용된다. 이러한 멤버는,DirectInputDevice.GetObjectInfo 메소드외,DIPROPLONG 형과 DIPROPRANGE 형으로 사용된다.

Enum CONST_DIPHFLAGS
    DIPH_DEVICE  =  0
    DIPH_BYID  =    2
    DIPH_BYOFFSET = 1
End Enum
DIPH_DEVICE
프로퍼티는, 특정의 오브젝트는 아니고 디바이스 전체에 적용된다.
DIPH_BYOFFSET
디바이스 오브젝트는, 액세스 하는 정보가 소속하는 오브젝트의 현재의 데이터 형식에 대한 오프셋(offset)로 식별된다.
DIPH_BYID
디바이스 오브젝트는,DirectInputDeviceObjectInstance.GetType 메소드의 반환값으로부터 취득되는 인스턴스 식별자로 식별된다.


CONST_DISCLFLAGS

CONST_DISCLFLAGS 열거는,DirectInputDevice.SetCooperativeLevel 메소드의 flags 파라미터에 사용되어 디바이스가, 그 디바이스외의 인스턴스 및 시스템의 나머지의 부분과 통신하는 방법을 결정한다.

Enum CONST_DISCLFLAGS
    DISCL_BACKGROUND   = 8
    DISCL_EXCLUSIVE    = 1
    DISCL_FOREGROUND   = 4
    DISCL_NONEXCLUSIVE = 2
End Enum
DISCL_BACKGROUND
어플리케이션은, 백그라운드 액세스권을 요구한다. 백그라운드 액세스권이 허가되면(자), 할당할 수 있었던 윈도우가 액티브 윈도우가 아닌 경우에서도, 언제라도 디바이스를 취득할 수 있다.
DISCL_EXCLUSIVE
어플리케이션은, 배타 액세스권을 요구한다. 배타 액세스권이 부여되면(자), 디바이스가 취득되고 있는 동안, 디바이스외의 인스턴스는, 그 디바이스의 배타 액세스권을 취득할 수 없다. 다만, 다른 어플리케이션이 배타 액세스권을 취득하고 있는 경우에서도, 디바이스의 비배타 액세스권은 항상 인정된다.

어플리케이션이 마우스 디바이스나 키보드 디바이스를 취득 하면, 유저는 윈도우 메뉴를 사용하거나 윈도우를 이동하거나 윈도우의 사이즈를 변경하거나 할 수 없게 된다.

DISCL_FOREGROUND
어플리케이션은 foreground 액세스권을 요구한다. foreground 액세스권이 부여되면(자), 할당할 수 있었던 윈도우가 백그라운드로 이동할 때, 디바이스는 자동적으로 릴리즈 된다.
DISCL_NONEXCLUSIVE
어플리케이션은, 배타 액세스권을 요구한다. 디바이스에 대한 액세스권은, 같은 디바이스에 액세스 하고 있는 것 외의 어플리케이션의 방해가 되지 않는다.

어플리케이션은, DISCL_FOREGROUND 또는 DISCL_BACKGROUND 의 어느 쪽인지 한편을 지정해야 한다. 양쪽 모두 지정하는 일도, 전혀 지정하지 않는 것도 에러가 된다. 같이 어플리케이션은, DISCL_EXCLUSIVE 또는 DISCL_NONEXCLUSIVE 의 어느 쪽인지 한편을 지정해야 한다.


CONST_DISDDFLAGS

CONST_DISDDFLAGS 열거의 멤버는,DirectInputDevice.SendDeviceData 메소드에게 건네진다.

Enum CONST_DISDDCFLAGS
    DISDD_CONTINUE = 1
    DISDD_DEFAULT =  0
End Enum
DISDD_CONTINUE
데이터는 기존의 데이터를 덧쓰기한다. 상세한 것에 대하여는,DirectInputDevice.SendDeviceData 의 「주의」를 참조할것.
DISDD_DEFAULT
데이터는 기존의 데이터를 덧쓰기하지 않는다.


CONST_DISFFCFLAGS

CONST_DISFFCFLAGS 열거의 멤버는,DirectInputDevice.SendForceFeedbackCommand 메소드로 송신하는 커멘드를 지정하기 위해서 사용된다.

Enum CONST_DISFFCFLAGS
    DISFFC_CONTINUE =         8
    DISFFC_PAUSE =            4
    DISFFC_RESET =            1
    DISFFC_SETACTUATORSOFF = 32 (&H20)
    DISFFC_SETACTUATORSON =  16 (&H10)
    DISFFC_STOPALL =          2
End Enum
DISFFC_CONTINUE
중단된 모든 액티브한 이펙트의 재생을 계속한다. 디바이스가 중단 상태에 없을 때에 이 커멘드를 송신 하면, 에러가 된다.
DISFFC_PAUSE
모든 액티브 이펙트의 재생을 중단한다. 이 커멘드는 이펙트의 클럭도 정지하므로, 재개 하면, 이펙트는 계속 시간을 만료할 때까지 재생이 속행된다.

디바이스가 중단 상태에 있는 동안은, 새로운 이펙트를 시작 하거나 기존의 이펙트를 변경하거나 할 수 없다. 그러한 조작을 실시하면, 이 이후의 DISFFC_CONTINUE 커멘드가 정상적으로 기능하지 않게 되는 일이 있다.

중단을 파기해 모든 이펙트를 정지하려면 , DISFFC_STOPALL 또는 DISFCC_RESET 커멘드를 사용한다.

DISFFC_RESET
디바이스의 force feedback 시스템을 시동 상태로 한다. 모든 이펙트는 디바이스로부터 삭제되어 유효하지 않게 된다. 이러한 이펙트를 다시 사용하려면 , 재생성해야 한다. 디바이스의 액츄에이터는 무효이다.
DISFFC_SETACTUATORSOFF
디바이스의 force feedback 액츄에이터를 무효로 한다. 액츄에이터가 오프의 사이도, 이펙트는 계속해 재생되지만, 디바이스는 그것을 무시한다. 음악 재생 디바이스에 비유하면(자), 이펙트는 일시정지 (포즈)는 아니고, 소음 (뮤트)된 상태이다.
DISFFC_SETACTUATORSON
디바이스의 force feedback 액츄에이터를 유효하게 한다.
DISFFC_STOPALL
모든 액티브한 이펙트의 재생을 정지한다. 액티브한 이펙트는 모두 리셋 되지만, 디바이스에는 보존되고 있어 계속해 유효하다. 디바이스가 중단되고 있는 경우, 그 상태는 없어진다.

이 커멘드는, 재생중의 이펙트 마다 DirectInputEffect.Stop 메소드를 호출하는 것에 동일하다.


키보드 키

여기에서는, 다음의 내용에 대해 설명한다.

  • 키보드 디바이스 정수
  • DirectInput 와 일본어 키보드


키보드 디바이스 정수

CONST_DIKEYFLAGS 열거의 멤버인 키보드 디바이스 정수는, 키보드 디바이스의 데이터 패킷 (256 바이트 배열) 내에서의 오프셋(offset)를 나타낸다. 지정의 오프셋(offset) 위치의 데이터는, 키보드 키에 관련지을 수 있고 있다.

표준 키보드 디바이스 정수는, 이하대로이다 (승순).

정수 | 메모
DIK_ESCAPE |
DIK_1 | 메인 키보드상
DIK_2 | 메인 키보드상
DIK_3 | 메인 키보드상
DIK_4 | 메인 키보드상
DIK_5 | 메인 키보드상
DIK_6 | 메인 키보드상
DIK_7 | 메인 키보드상
DIK_8 | 메인 키보드상
DIK_9 | 메인 키보드상
DIK_0 | 메인 키보드상
DIK_MINUS | 메인 키보드상
DIK_EQUALS | 메인 키보드상
DIK_BACK | BaackSpace 키
DIK_TAB |
DIK_Q |
DIK_W |
DIK_E |
DIK_R |
DIK_T |
DIK_Y |
DIK_U |
DIK_I |
DIK_O |
DIK_P |
DIK_LBRACKET | [
DIK_RBRACKET | ]
DIK_RETURN | 메인 키보드 위에의 Enter 키
DIK_LCONTROL | 왼쪽 Ctrl 키
DIK_A |
DIK_S |
DIK_D |
DIK_F |
DIK_G |
DIK_H |
DIK_J |
DIK_K |
DIK_L |
DIK_SEMICOLON |
DIK_APOSTROPHE |
DIK_GRAVE | 아크상라브 (`) 키
DIK_LSHIFT | 왼쪽 Shift 키
DIK_BACKSLASH |
DIK_Z |
DIK_X |
DIK_C |
DIK_V |
DIK_B |
DIK_N |
DIK_M |
DIK_COMMA |
DIK_PERIOD | 메인 키보드상
DIK_SLASH | 메인 키보드 위에의순서 slash (/)
DIK_RSHIFT | 오른쪽 Shift 키
DIK_MULTIPLY | 숫자 패드 위에의 asterisk 키
DIK_LMENU | 왼쪽 Alt 키
DIK_SPACE | Space 키
DIK_CAPITAL | CapsLock
DIK_F1 |
DIK_F2 |
DIK_F3 |
DIK_F4 |
DIK_F5 |
DIK_F6 |
DIK_F7 |
DIK_F8 |
DIK_F9 |
DIK_F10 |
DIK_NUMLOCK |
DIK_SCROLL | ScrollLock
DIK_NUMPAD7 |
DIK_NUMPAD8 |
DIK_NUMPAD9 |
DIK_SUBTRACT | 숫자 패드 위에의 하이픈 (마이너스 기호) 키
DIK_NUMPAD4 |
DIK_NUMPAD5 |
DIK_NUMPAD6 |
DIK_ADD | 숫자 패드 위에의 플러스 기호 키
DIK_NUMPAD1 |
DIK_NUMPAD2 |
DIK_NUMPAD3 |
DIK_NUMPAD0 |
DIK_DECIMAL | 숫자 패드 위에의 피리어드 (소수점)
DIK_F11 |
DIK_F12 |
DIK_F13 |
DIK_F14 |
DIK_F15 |
DIK_KANA | 일본어 키보드상
DIK_CONVERT | 일본어 키보드상
DIK_NOCONVERT | 일본어 키보드상
DIK_YEN | 일본어 키보드상
DIK_NUMPADEQUALS | 숫자 패드상 (NEC PC98)
DIK_CIRCUMFLEX | 일본어 키보드상
DIK_AT | 일본어 키보드상
DIK_COLON | 일본어 키보드상
DIK_UNDERLINE | 일본어 키보드상
DIK_KANJI | 일본어 키보드상
DIK_STOP | 일본어 키보드상
DIK_AX | 일본어 키보드상
DIK_UNLABELED | 일본어 키보드상
DIK_NUMPADENTER |
DIK_RCONTROL | 오른쪽 Ctrl 키
DIK_NUMPADCOMMA | NEC PC98 숫자 패드 위에의 콤마
DIK_DIVIDE | 숫자 패드 위에의순서 slash (/)
DIK_SYSRQ |
DIK_RMENU | 오른쪽 Alt 키
DIK_HOME |
DIK_UP | 오름새 커서 키
DIK_PRIOR | PageUp 키
DIK_LEFT | 좌향 커서 키
DIK_RIGHT | 오른쪽 방향 커서 키
DIK_END |
DIK_DOWN | 하향 커서 키
DIK_NEXT | PageDown 키
DIK_INSERT |
DIK_DELETE |
DIK_LWIN | 왼쪽 Windows 키
DIK_RWIN | 오른쪽 Windows 키
DIK_APPS | 어플리케이션 키
DIK_PAUSE |

일본어 키보드에 대해서는, 「DirectInput 와 일본어 키보드」를 참조할것.


에러 코드

이하는, DirectInput 메소드와 함수에 의해 돌려주어지는 에러 코드의 일람이다. 에러는 부의 값에 의해 나타나 결합할 수가 없다.

각각의 메소드 또는 함수는 에러값을 돌려줄 수가 있지만, 자세하게는 각각의 설명을 참조할것. 본문중의 에러 코드의 일람은, 필연적으로 불완전하게 되어 있다. 예를 들어, 어떤 DirectInput 메소드도 DIERR_OUTOFMEMORY 를 돌려줄 수가 있지만, 본문중에서는, 이 에러 코드는 그 메소드의 반환값으로서는 명시되어 있지 않다.

DI_BUFFEROVERFLOW
입력 버퍼가 오버플로우 해, 데이터가 없어졌다.
DIERR_ACQUIRED
조작은, 디바이스가 취득 상태의 사이는 실행할 수 없다.
DIERR_ALREADYINITIALIZED
이 오브젝트는 초기화가 끝난 상태이다.
DIERR_BADDRIVERVER
오브젝트는, 호환성이 없는 드라이버 버젼, 혹은 부적격 또는 불완전한 드라이버 컴퍼넌트이기 위해서(때문에) 생성 할 수 없었다.
DIERR_BETADIRECTINPUTVERSION
어플리케이션은, DirectInput 의 지원되어 있지 않은 릴리스전의 버젼용으로 생성 된 것이다.
DIERR_DEVICEFULL
디바이스는 풀이다.
DIERR_DEVICENOTREG
디바이스 또는 디바이스 인스턴스가 DirectInput 에 등록되지 않았다. 이 값은, 표준의 COM 반환값인 REGDB_E_CLASSNOTREG 에 동일하다.
DIERR_EFFECTPLAYING
파라미터는, 메모리내에서는 갱신되었지만, 디바이스에는 다운로드되지 않았다. 디바이스가 재생중의 이펙트의 갱신을 지원 하고 있지 않기 때문이다.
DIERR_HASEFFECTS
이펙트가 디바이스에 Attach 되고 있기 (위해)때문에, 디바이스를 재초기화할 수 없다.
DIERR_GENERIC
DirectInput 서브 시스템으로 원인 불명의 에러가 발생했다. 이 값은, 표준의 COM 반환값인 E_FAIL 에 동일하다.
DIERR_HANDLEEXISTS
디바이스는, 이미, 자신에게 이벤트 통지가 관련짓고를 하고 있다. 이 값은, 표준의 COM 반환값인 E_ACCESSDENIED 에 동일하다.
DIERR_INCOMPLETEEFFECT
필수 정보가 없기 때문에, 이펙트를 다운로드할 수 없었다. 예를 들어, 이펙트에 관련하는 축이 없기도 하고, 타입 고유 정보가 주어지지 않은 경우.
DIERR_INPUTLOST
입력 디바이스의 액세스권을 잃었다. 재취득해야 한다.
DIERR_INVALIDHANDLE
무효인 윈도우 핸들이 메소드에게 건네졌다.
DIERR_INVALIDPARAM
무효인 파라미터가 돌아오는 함수에게 건네졌는지, 오브젝트가 그 함수를 호출할 수 있는 상태에 없었다. 이 값은, 표준의 COM 반환값인 E_INVALIDARG 에 동일하다.
DIERR_MOREDATA
요구 정보의 일부가 버퍼에 들어가지 않았다.
DIERR_NOAGGREGATION
오브젝트는, 집합화를 지원 하지 않는다.
DIERR_NOINTERFACE
오브젝트는, 지정의 인터페이스를 지원 하고 있지 않다. 이 값은, 표준의 COM 반환값인 E_NOINTERFACE 에 동일하다.
DIERR_NOTACQUIRED
조작은, 디바이스가 취득되지 않는 한 실행할 수 없다.
DIERR_NOTBUFFERED
디바이스는, 버퍼링되어 있지 않다. 버퍼링을 유효하게 하려면 DIPROP_BUFFERSIZE 프로퍼티를 설정한다.
DIERR_NOTDOWNLOADED
이펙트가 다운로드되어 있지 않다.
DIERR_NOTEXCLUSIVEACQUIRED
조작은, 디바이스가 DISCL_EXCLUSIVE 모드로 취득되어 있지 않으면 실행할 수 없다.
DIERR_NOTINITIALIZED
이 오브젝트는, 초기화되어 있지 않았다.
DIERR_NOTFOUND
요구된 오브젝트는 존재하지 않는다.
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_PENDING
데이터는, 아직 사용 불가이다.


DirectInput 의 툴과 샘플

여기에서는, DirectX SDK 에 부속되는 툴 및 샘플 어플리케이션 가운데, DirectInput 에 관련하는 것에 임해서 설명한다. 설명하는 내용은 이하대로이다.

  • DirectInput 툴
  • DirectInput C/C++ 샘플
  • DirectInput Visual Basic 샘플


DirectInput 툴

DirectInput 로 사용하기 위해서 이하의 툴이 준비되어 있다.

  • DirectInput QuickTest
  • Force Editor


DirectInput QuickTest

설명

DirectInput QuickTest 어플리케이션을 사용하면(자), 디바이스 및 디바이스 오브젝트의 프로퍼티를 표시하거나 디바이스로부터의 입력 데이터를 표시하거나 할 수가 있다.

패스

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DInput\Bin\Diquick.exe

유저즈 가이드

초기 화면에서, 디바이스를 선택해 [Create] 버튼을 클릭한다. 디바이스가 정상적으로 생성 되면(자), 복수의 탭을 가지는 프로퍼티 시트가 표시된다.

[Mode] 페이지에서는, 협조 레벨, 데이터 모드, 및 축모드를 선택한다. 죠이스틱의 경우, 폴링 데이터 모드를 선택해야 한다. 또,[Form of] 박스로부터 디바이스 타입을 확인할 필요도 있다. 버퍼링 데이터를 표시하고 싶은 경우는, 이 페이지로 버퍼 사이즈에 제로보다 큰 값을 지정해야 한다.

[Caps] 페이지에서는, 디바이스에 관한 그 외의 정보를 지정한다.

[Objects] 페이지에서는, 디바이스상에서 선택된 버튼이나 축을 열거할 수 있다. [Properties] 버튼을 클릭 하면, 선택한 오브젝트에 대해서,DIDEVICEOBJECTINSTANCE 구조체 (C++) 또는 DirectInputDeviceObjectInstance 오브젝트 (Visual Basic)로 나타내지는 데이터의 요약이 표시된다. 이 프로퍼티 시트에서는, 축의 범위, 무효 존, 및 포화점을 설정할 수도 있다.

또,[Data] 페이지에는, 디바이스로부터의 입력 데이터가 표시된다. 페이지의 좌측에는 직접 데이터, 페이지의 우측에는 버퍼링 데이터 (버퍼 사이즈를 설정 끝난 경우)가 표시된다.


Force Editor

설명

Force Editor 어플리케이션을 사용하면(자), force feedback 이펙트를 디자인하거나 그 이펙트를 단독으로 테스트하거나 몇개의 이펙트를 조합해 테스트하거나 할 수가 있다. 이펙트는, 파일에 보존해, DirectInput 어플리케이션에 읽어들이게 할 수가 있다.

패스

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

유저즈 가이드

F1 키를 누르면(자), on-line help가 표시된다.


DirectInput C/C++ 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 샘플」을 참조할것.

[C++]

이하의 샘플 프로그램에는, DirectInput 의 사용법과 기능이 나타나고 있다.

  • DIGame 샘플
  • FFDonuts 샘플
  • FFFileRead 샘플
  • JoyFFeed 샘플
  • JoystImm 샘플
  • KeybdBuf 샘플
  • KeybdExc 샘플
  • KeybdImm 샘플
  • MouseExc 샘플
  • MouseNon 샘플
  • Scrawl 샘플

게다가 DirectInput 의 기본 기능에 대해 구체적으로 설명하는 상세한 코멘트들이의 소스 코드가, 다음의 장소에 수록되고 있다.

(SDK 루트) \Samples\Multimedia\DInput\Src\Tutorials

DirectX 의 샘플에는 Microsoft® Visual C++® 프로젝트 워크 스페이스 파일이 포함되어 있지만, 독자의 개발 환경에서 올바르게 컴파일 할 수 있을지 어떨지를 확인할 필요가 있다. 상세한 것에 대하여는, 「DirectX 의 샘플 및 그 외의 DirectX 어플리케이션의 컴파일」을 참조할것.


DIGame 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 샘플」을 참조할것.

[C++]

설명

DIGame 샘플 어플리케이션은, 키보드, 마우스, 또는 죠이스틱으로 플레이 할 수 있는, 단순한 슈팅 게임이다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\DInput\Src\DIGame

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DInput\Bin

유저즈 가이드

디폴트의 입력 디바이스는 키보드이다. 디바이스를 변경하려면 ,[File] 메뉴의 [Select Input Device] 를 클릭한다.

커서 키, 마우스, 또는 죠이스틱을 사용해, 선체를 윗방향이나 아래방향으로 이동한다. 왼쪽이나 오른쪽으로 작동시키면(자), 방향이 변화한다. Space 키, 왼쪽 mouse button, 또는 죠이스틱의 메인 버튼을 누르면(자), 발사한다.

한번 더 시작 하려면 ,[File] 의 [New Game] 를 클릭한다.

프로그래밍 위에의 주의

입력 코드는 모두 Digame.cpp 에 포함되어 있다.


FFDonuts 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 샘플」을 참조할것.

[C++]

설명

이 프로그램은 「Space Donuts 샘플 프로그램」을 개변한 것으로, force feedback 죠이스틱이 접속되고 있는 경우에 force feedback 출력을 추가한다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\DInput\Src\FFdonuts

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DInput\Bin

유저즈 가이드

프로그램을 기동 하면, 다이알로그 박스가 표시된다. 여기서, force feedback 이펙트의 매그니튜드를 설정한다.

우주선이 표시되면(자), 가속하려면 죠이스틱을 앞에 두고 넘어뜨려, 감속하거나 후퇴하거나 하려면 죠이스틱을 되돌린다. 죠이스틱을 오른쪽이나 왼쪽으로 작동시키면(자), 우주선이 회전한다. 방아쇠 버튼을 누르면(자), 탄환이 발사한다. 세컨드 버튼을 누르면(자), 쉴드(shield)가 쳐진다. 탄환이 발사되거나 물체에 충돌하거나 화면의 구석에서는돌아가거나 했을 때에, force feedback가 효과가 있는 것을 확인받고 싶다.

프로그래밍 위에의 주의

force feedback의 루틴은, Input.c 파일에 기술되고 있다. 이 프로그램은, 정수 포스, 주기적 이펙트, 엔벌로프, 및 게인의 사용법을 구체적으로 설명하고 있다. 발사 버튼의 이펙트는,DIEFFECT 구조체로 방아쇠 버튼에 연동하는 것이 아니라, 보통의 입력 이벤트에 반응해 동작하는 것에 주의 해야 한다.

참조

Space Donuts 샘플


FFFileRead 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 샘플」을 참조할것.

[C++]

설명

이 샘플에서는,Force Editor 로 생성 된 파일로부터 이펙트를 읽어내는 방법이나 이펙트를 생성하는 방법을 나타낸다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\DInput\Src\FFFileRead

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DInput\Bin\FFeedFileRead.exe

미디어 파일 :(SDK 루트) \Samples\Multimedia\DInput\Media

유저즈 가이드

[Read File] 를 클릭해, Media 폴더에 준비되어 있다 . ffe 파일인가, 또는 독자적으로 생성 한 파일을 읽어들인다. 다음에,[Play Effects] 를 클릭한다.

프로그래밍 위에의 주의

파일로부터 열거된 이펙트의 각각 붙어, EnumAndCreateEffectsCallback 함수가 IDirectInputEffect 포인터를 초기화해, 그 포인터가 링크된 리스트에 추가한다. OnPlayEffects 함수가 이 리스트를 처리해, 모든 이펙트를 재생한다.


JoyFFeed 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 샘플」을 참조할것.

[C++]

설명

이 어플리케이션은, 실제의 동작을 force feedback 죠이스틱에 적용해, 시뮬레이터와 같은 어플리케이션으로, force feedback를 사용해, 물리 엔진으로 계산된 포스를 생성하는 방법을 구체적으로 가리킨다.

이 어플리케이션을 동작시키려면 , force feedback 디바이스를 접속해야 한다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\DInput\Src\JoyFFeed

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DInput\Bin

유저즈 가이드

이 어플리케이션을 기동 하면, 십자 커서와 검은 포인트가 윈도우에 표시된다. 윈도우의 클라이언트 에리어내의 임의의 장소에서 마우스를 클릭 하면, 검은 포인트가 이동한다(죠이스틱의 핸들을 움직여도 아무것도 일어나지 않는 것에 주의). JoyFFeed 는, 십자 커서로부터의 거리 에 비례해, 포인트의 방향으로부터 죠이스틱의 핸들에 정수 포스를 준다. 마우스의 버튼을 계속 누르면(자) , 포인트를 계속적으로 움직일 수도 있다.

프로그래밍 위에의 주의

이 샘플 프로그램은, 입력 디바이스가 몇개 접속되고 있는지를 열거해, 최초로 검출된 force feedback 죠이스틱을 취득한다. 검출되지 않으면, 메세지를 표시해 프로그램을 종료한다.

검은 포인트를 이동 하면, joySetForcesXY 함수는, 커서의 좌표를 포스의 방향과 매그니튜드로 변환한다. 이 데이터는, 정수 포스 이펙트의 파라미터를 변경하는데 사용된다.


JoystImm 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 샘플」을 참조할것.

[C++]

설명

JoystImm 샘플은, 죠이스틱의 데이터를 취득해 표시한다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\DInput\Src\JoystImm

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DInput\Bin

유저즈 가이드

죠이스틱을 작동시키거나 비틀거나 스롯트르호이르를 돌리거나 다양한 편성으로 버튼을 누르거나 했을 때에, 표시된 데이터가 어떻게 변화할까 를 보고 헤아린다.

프로그래밍 위에의 주의

이 어플리케이션은, 다이얼로그 프로시저 내부로 설정된 타이머에 응답해, 죠이스틱의 직접 데이터를 폴링 한다.


KeybdBuf 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 샘플」을 참조할것.

[C++]

설명

KeybdBuf 프로그램은, 키보드의 데이터를 취득해 표시한다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\DInput\src\KeybdBuf

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DInput\bin

유저즈 가이드

키를 누르거나 떼어 놓거나 할 때마다, 이벤트가 화면에 기록된다. 키는, 인덱스값에 의해 특정된다 ( 「키보드 디바이스 정수」를 참조).

프로그래밍 위에의 주의

이 샘플은, 어플리케이션이 키보드의 버퍼링 데이터를 취득하려면 어떻게 DirectInput 를 사용하는지를 설명하고 있다.


KeybdExc 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 샘플」을 참조할것.

[C++]

설명

KeybdExc 샘플은, 키보드를 배타 협조 레벨로 사용하는 방법을 나타낸다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\DInput\Src\KeybdExc

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DInput\Bin\KeybdExc.exe

유저즈 가이드

1 개(살) 또는 복수의 버튼을 계속 누르면(자) , 각각의 키의 인덱스값 ( 「키보드 디바이스 정수」를 참조)이 표시된다. Windows 키를 누르면(자), 「KeybdImm 샘플」에서는 [스타트] 메뉴가 표시되지만, 이 프로그램에서는 표시되지 않는 것에 주의 해야 한다.

프로그래밍 위에의 주의

이 샘플은, 배타 foreground 협조 레벨로 키보드의 직접 데이터를 취득하려면 어떻게 DirectInput 를 사용하는지를 설명하고 있다. 이 어플리케이션은 반복해 IDirectInputDevice7::GetDeviceState 를 호출해, 눌러져 모든 키의 값을 포함한 캐릭터 라인을 표시한다.


KeybdImm 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 샘플」을 참조할것.

[C++]

설명

Kyebdlmm 프로그램은, 키보드의 데이터를 취득해 표시한다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\DInput\Src\KeybdImm

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DInput\Bin

유저즈 가이드

1 개(살) 또는 복수의 버튼을 계속 누르면(자) , 각각의 키의 인덱스값 ( 「키보드 디바이스 정수」를 참조)이 표시된다.

프로그래밍 위에의 주의

이 샘플은, 비배타 foreground 협조 레벨로 키보드의 직접 데이터를 취득하려면 어떻게 DirectInput 를 사용하는지를 설명하고 있다. 이 어플리케이션은 반복해 IDirectInputDevice7::GetDeviceState 를 호출해, 눌러져 모든 키의 값을 포함한 캐릭터 라인을 표시한다.


MouseExc 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 샘플」을 참조할것.

[C++]

설명

MouseExc 프로그램은, DirectInput 디바이스의 초기화와 직접 데이터를 취득하는 방법을 설명하고 있다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\DInput\Src\MouseExc

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DInput\Bin

유저즈 가이드

마우스를 작동시키면(자), 거기에 응해 좌표가 변화해 표시된다. mouse button를 계속 누르면(자) , 그 버튼의 번호가 표시된다. 시스템 커서가 표시되지 않게 되는 것에 주의 해야 한다.

프로그래밍 위에의 주의

이 샘플은, 배타 foreground 모드로 마우스의 상대 데이터를 취득하려면 어떻게 DirectInput 를 사용하는지를 설명하고 있다. 이 프로그램은, 직전에 IDirectInputDevice7::GetDeviceState 를 호출하고 나서의 마우스 좌표의 변화를 1 초간에 약 30 회초시 한다.


MouseNon 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 샘플」을 참조할것.

[C++]

설명

MouseNon 프로그램은, DirectInput 디바이스의 초기화와 데이터의 직접적인 취득을 어떻게 실시하는지를 설명하고 있다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\DInput\Src\MouseNon

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DInput\Bin

유저즈 가이드

마우스를 작동시키면(자), 거기에 응해 좌표가 변화해 표시된다. mouse button를 계속 누르면(자) , 그 버튼의 번호가 표시된다. 커서는 어플리케이션 윈도우에 표시되지 않지만, 어플리케이션은 foreground로 되어 있지 않으면 안 되는 것에 주의 해야 한다.

프로그래밍 위에의 주의

이 샘플은, 비배타 foreground 모드로 마우스의 상대 데이터를 취득하려면 어떻게 DirectInput 를 사용하는지를 설명하고 있다. 이 프로그램은, 직전에 IDirectInputDevice7::GetDeviceState 를 호출하고 나서의 마우스 좌표의 변화를 1 초간에 약 30 회초시 한다.


Scrawl 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectInput Visual Basic 샘플」을 참조할것.

[C++]

설명

Scrawl 어플리케이션은, 윈도우 표시 어플리케이션의 배타 모드에서의 마우스의 사용법을 설명하고 있다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\DInput\Src\Scrawl

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DInput\Bin

유저즈 가이드

유저가 컨트롤 패널로 설정해 있는 내용에 관계없이, 메인의 mouse button는 항상 왼쪽 버튼으로, 세컨드리 버튼은 오른쪽 버튼이다.

왼쪽 버튼을 누르면서 마우스를 작동시키면(자), 선이 그려진다. 오른쪽 버튼을 클릭 하면, pop-up menu가 표시된다. pop-up menu로부터는, 클라이언트 윈도우의 소거, 마우스 감도의 설정, 어플리케이션의 종료를 선택할 수가 있다.

프로그래밍 위에의 주의

Scrawl 어플리케이션은, 다음과 같은 DirectInput 프로그래밍의 다양한 면을 나타내고 있다.

  • 윈도우 표시 어플리케이션의 배타 모드로 마우스를 사용한다.
  • 메뉴를 사용하기 위해서(때문에) Windows 가 필요로 했을 때에 마우스를 릴리즈 한다.
  • Windows 가 마우스를 필요로 하지 않게 되었을 때에, 마우스를 재취득한다.
  • 디바이스의 버퍼링 데이터를 읽어낸다.
  • 좌표의 이동이 완료할 때까지 화면 표시의 갱신을 연기한다.
  • 디바이스의 활동 상황을 통지한다.
  • 임의의 범위에 커서의 움직임을 제한한다.
  • 사용전에, 미처리의 마우스 좌표를 계측 한다.
  • 상대 좌표 모드를 사용한다.


DirectInput Visual Basic 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 샘플」을 참조할것.

[Visual Basic]

이하의 샘플 프로그램에는, DirectInput 의 사용법과 기능이 나타나고 있다.

  • ForceFeedback 샘플
  • Joystick 샘플
  • Keyboard 샘플
  • ScrawlB 샘플


ForceFeedback 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 샘플」을 참조할것.

[Visual Basic]

설명

이 샘플은, 이펙트의 생성, 파라미터의 설정, 및 이펙트의 재생을 실시할 수가 있는 간단한 force feedback 에디터이다.

패스

소스 파일 : (SDK 루트) \Samples\Multimedia\VBSamples\Dinput\Src\FFeedback

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\VBSamples\Dinput\Bin\ForceFeedback.exe

유저즈 가이드

일람으로부터 이펙트 타입을 선택해, 파라미터를 변경한다. 죠이스틱의 주버튼을 누르면(자), 이펙트가 재생된다.

프로그래밍 위에의 주의

이 샘플에서는, 자동 센터링 프로퍼티를 오프로 하는 방법, 및 이펙트를 생성해 변경하는 방법을 나타낸다. 이펙트 파라미터의 변경은, 즉시 적용된다.


Joystick 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 샘플」을 참조할것.

[Visual Basic]

설명

Joystick 샘플에서는, 죠이스틱을 열거해, 죠이스틱의 프로퍼티를 설정해, 직접 데이터를 취득하는 방법을 나타낸다.

패스

소스 파일 : (SDK 루트) \Samples\Multimedia\VBSamples\Dinput\Src\Joystick

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\VBSamples\Dinput\Bin\Joystick.exe

유저즈 가이드

일람으로부터 죠이스틱을 선택한다. 축 및 버튼으로부터 취득된 데이터가 표시된다.

프로그래밍 위에의 주의

선택사항이 DirectInputEnumDevices 콜렉션으로부터 용이하게 취득할 수 있도록(듯이), 리스트 박스는 소트 되지 않는다.


Keyboard 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 샘플」을 참조할것.

[Visual Basic]

설명

Keyboard 샘플에서는, 키보드 디바이스를 생성 해 직접 데이터를 취득하는 방법을 나타낸다.

패스

소스 파일 : (SDK 루트) \Samples\Multimedia\VBSamples\Dinput\Src\Keyboard

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\VBSamples\Dinput\Bin\Keyboard.exe

유저즈 가이드

1 개(살) 이상의 키를 눌러 내리면(자), 그 키의 이름 (CONST_DIKEYFLAGS )이 리스트 박스에 표시된다.

프로그래밍 위에의 주의

백그라운드 협조 레벨을 사용하므로, 어플리케이션에 입력초점이 없어도, 키는 읽어내진다.


ScrawlB 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectInput C/C++ 샘플」을 참조할것.

[Visual Basic]

설명

ScrawlB 샘플에서는, 마우스를 배타 모드로 사용하는 방법, 마우스 이벤트의 이벤트 통지를 사용하는 방법, 및 버퍼링 데이터를 취득해 해석하는 방법을 나타낸다.

패스

소스 파일 : (SDK 루트) \Samples\Multimedia\VBSamples\Dinput\Src\Scrawlb

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\VBSamples\Dinput\Bin\Scrawlb.exe

유저즈 가이드

왼쪽 버튼을 눌러 내리면(자) 드로잉(Drawing) 한다. 오른쪽 버튼을 클릭 하면, context menu가 표시된다. [Suspend] 를 선택하는 (또는 Alt 키를 눌러 떼어 놓는다)와 시스템 커서가 릴리즈 되므로, 윈도우를 이동하거나 윈도우의 사이즈를 변경하거나 다른 어플리케이션을 클릭하거나 할 수 있다. 드로잉(Drawing)를 재개하려면 , 클라이언트 윈도우를 한번 더 클릭한다.

Alt + Tab 키를 눌러 다른 어플리케이션으로 전환하면(자), ScrawlB 는 클라이언트 윈도우에 마우스를 건네주는 것과 동시에, 마우스를 회복한다.

프로그래밍 위에의 주의

어플리케이션은, WM_ENTERMENULOOP 메세지를 인터셉트 하기 위해서, 메인 윈도우를 서브 클래스화한다. 유저가 Alt 키를 누르면서 스페이스 키를 눌러 시스템 메뉴를 열었는지 어떠했는지를 조사하려면 , 이것이 최적인 방법이다. 이것을 알면, ScrawlB 는 마우스를 릴리즈 할 수 있다. 다만, 서브 클래스화하면(자), 디버그시에 문제가 생기는 일이 있다. modMain.bas 의 코멘트를 참조할것.

frmCanvas 모듈은, 입력 이벤트를 처리하기 위해서 DirectXEvent 를 이행 한다. 또, 이 폼에서는, DirectInput 가 마우스에 대한 액세스권을 가지지 않을 때에 Windows 마우스 이벤트를 취득하기 위해서, Visual Basic 의 MouseMove 이벤트를 사용한다. 이 이벤트가 방아쇠 되면(자), 어플리케이션은 커서가 클라이언트 윈도우에 돌아온 것을 인식하므로, 마우스를 재취득할 수가 있다.


DirectMusic

여기에서는, DirectX® 의 DirectMusic 컴퍼넌트에 관한 정보를, 다음의 주제로 나누어 기술한다.

  • DirectMusic 에 대해
  • DirectMusic 를 사용하는 이유
  • DirectMusic 아키텍쳐
  • DirectMusic 의 요점
  • DirectMusic 튜토리얼
  • DirectMusic 레퍼런스
  • DirectMusic 샘플


DirectMusic 에 대해

DirectMusic 는, Microsoft® DirectX® API 의 뮤직 컴퍼넌트이다. 디지털 사운드 샘플의 캡춰와 재생을 실시하는 Microsoft® DirectSound® API 과는 달리, DirectMusic 는 메세지 베이스의 뮤직 데이터를 처리한다. 뮤직 데이터는, 하드웨어 또는 소프트웨어 신디사이저에 의해, 웨이브 샘플에 변환된다. 디폴트의 소프트웨어의 이행에서는, Microsoft® Software Synthesizer 를 사용해 웨이브 샘플이 생성 된다. 생성 한 샘플은, DirectSound 에의 스트림에 보내진다. 음색의 발음은,다운로더블 사운드 (DLS) 규격에 따라, 샘플로부터 합성된다.

MIDI (Musical Instrument Digital Interface) 포맷에서의 입력의 지원은 물론이거니와, DirectMusic 에서는 실행시에 음악을 어레인지 할 수가 있다. 이 음악은, 알고리즘으로 생성되는 것이 아니라, 작곡자가 오쏘링 한 요소에 근거해 생성된다 (authoring tool의 Microsoft® DirectMusic Producer 는, 별도 문서화 되고 있다). 음악은 다양한 바리에이션으로 연주되어 프로그램의 이벤트에 동적으로 응답할 수가 있다.

DirectX 외의 컴퍼넌트와 같이, DirectMusic 는 COM (Component Object Model, 컴퍼넌트 오브젝트 모델)에 근거하고 있다.

DirectMusic 는, Microsoft® Windows® 95, Microsoft® Windows® 98, 및 Microsoft® Windows® 2000 에 대해, 모든 기능을 발휘할 수 있다. 다만, 하드웨어 가속화를 이용할 수 있는 것은, Windows 2000 및 Windows 98 Second Edition 뿐인다.


DirectMusic 를 사용하는 이유

DirectMusic API 는, Windows 플랫폼에서 음악을 연주하기 위해서, 다음의 기초적인 요건을 처리한다.

  • 재생을 일관성이 있는 방법으로 재현. 다운로더블 사운드를 사용하는 것으로, 어플리케이션은 모든 컴퓨터로 같은 음색의 소리를 재생할 수가 있다. 또, 어플리케이션 독자적인 설계에 의한 음색을 사용한 연주를 할 수 있다.
  • 지터 프리의 타이밍. MIDI 로 생성된 음악의 재생은, 타이밍 정밀도가 2 밀리 세컨드 이내이다.
  • 확장성. DirectMusic 에 의해, 벤더가 기본 레벨의 기능 세트에 제한될 것은 없다.
  • 하드웨어 가속화. Windows 98 Second Edition 및 Windows 2000 에서는, DirectMusic 는 DLS 대응의 하드웨어 신디사이저의 스트림에 출력할 수가 있다.
  • 소프트웨어 에뮬레이션. 하드웨어 가속화 기능을 갖추지 않은 컴퓨터도, 퍼포먼스에 미치는 영향을 최소한으로 억제해 DirectMusic 에 완전에 대응할 수 있다.

더해, DirectMusic 는 어플리케이션 개발의 간소화와 유저의 경험 향상을 꾀해, 다음의 중요한 기능을 제공한다.

  • 퍼포먼스 테크놀러지 에 관계없이, 뮤직 세그먼트(segment)의 로드와 연주를 행하기 위한 일반적인 메카니즘. DirectMusic 는, 스탠다드 MIDI 파일, 오쏘링 된 뮤직 세그먼트(segment), 및 써드파티의 테크놀러지를 동일하게 지원 한다.
  • 다중 연주. 음악의 복수의 부분을 동시에 연주할 수 있어 타이밍이나 음색 세트등을 완전하게 분리할 수 있다.
  • 16 을 넘는 MIDI 채널. 퍼포먼스 채널을 채널 그룹에 맵핑 하는 것으로써, DirectMusic 는 채널수 16 의 제약을 타파해, 임의의 수의 발음을 신디사이저의 제한까지, 동시에 연주하는 것을 가능하게 했다.
  • DLS 음색의 자동 관리.
  • 다이나믹하고 인터랙티브인 재생. DirectMusic Producer 와 조합하는 것으로, DirectMusic 퍼포먼스 엔진을 사용해, 보존된 악곡 재료를 베이스로 하는 다이나믹한 음악 사운드 트랙을 생성 할 수 있다. 음악은, 연주되기 직전까지 최종적인 형식이라고는 보여지지 못하고, 프로그램 이벤트에 응답할 수가 있다.
  • master clock의 사용에 의한, 모든 음악 재생의 동기화.


DirectMusic 아키텍쳐

여기에서는, DirectMusic 의 컴퍼넌트를 소개한다. 다음의 항목에 대해 설명한다.

  • 코어 계층과 퍼포먼스 계층
  • DirectMusic 오브젝트와 인터페이스의 개요 (C/C++)
  • DirectMusic 클래스의 개요 (Visual Basic)
  • DirectMusic 의 데이터의 흐름의 개요
  • DirectMusic 메세지
  • 다운로더블 사운드
  • Microsoft Software Synthesizer

이러한 컴퍼넌트를 어플리케이션에 이행 하는 방법에 대해서는, 「DirectMusic 의 요점」을 참조할것.


코어 계층과 퍼포먼스 계층

DirectMusic 의 코어 계층은 타이밍과 포트를 관리해,DLS 콜렉션을 관리하기 위한 서비스를 제공한다. 버퍼와 타임 스탬프를 갖춘 MIDI 입출력을 지원 한다. 디폴트에서는, MIDI 데이터는 DirectMusic 에 의해 순서화 된다.

코어 계층에는 Microsoft Software Synthesizer 도 포함되지만, 이것은 DLS 지원의 하드웨어 에뮬레이션으로서 기능한다. 유저의 컴퓨터에 DLS 하드웨어 가속화가 없는 경우, 소프트웨어 신디사이저는 DLS 를 사용해, 순서화 된 MIDI 데이터로부터 웨이브 출력을 합성한다. 벤더는 독자적인 소프트웨어 신디사이저를 생성 해도 괜찮다.

DirectMusic 의 퍼포먼스 계층은, MIDI 파일의 로드와 재생, 음악의 어레인지 등, 음악 재생의 상위 레벨의 처리를, DirectMusic Producer 등의 어플리케이션으로 오쏘링 된 요소에 근거해 처리한다.

[C++]

코어 계층의 인터페이스 및 관련하는 API 요소는, Dmusicc.h 헤더 파일로 선언되고 있다. 또, 퍼포먼스 계층의 인터페이스와 API 요소는, Dmusici.h 헤더 파일로 선언되고 있다.

[Visual Basic]

DirectX for Visual Basic 에서는, 주로 퍼포먼스 계층이 공개된다. 복수의 포트를 조작하거나 DLS 데이터를 하위 레벨로 조작하거나 독자적인 데이터 트랙을 생성 할 필요가 있는 특수한 어플리케이션에는, C++ 를 사용한다.


DirectMusic 오브젝트와 인터페이스의 개요

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic 클래스의 개요」를 참조할것.

[C++]

DirectMusic 에서는, 많은 오브젝트가 복수의 인터페이스를 갖추고 있으므로, 오브젝트와 그 COM 인터페이스를 구별하는 것이 중요하다. 예를 들어,IDirectMusicCollection 인터페이스를 지원 하는 오브젝트는,IDirectMusicObject 와 같게, COM 의 표준적인 IPersistStream 인터페이스도 지원 한다.

여기에서는, DirectMusic 오브젝트를 그 주요 또는 고유의 인터페이스명으로 부르지만, 최초의 "I" 는 생략 한다. 그 때문에,IDirectMusicCollection 에 의해 나타내지는 오브젝트를 DirectMusicCollection 오브젝트라고 부른다. 오브젝트는,콜렉션,퍼포먼스,세그먼트(segment),트랙등의, 짧은 이름으로 불리는 경우도 있다.

인터페이스 포인터는 자주 그 오브젝트에의 포인터로서 사용되므로, 다른 인터페이스의 메소드를 통해 그러한 오브젝트에 액세스도 할 수 있다. 실제, 인터페이스의 1 개인 IDirectMusicDownloadedInstrument 는, 자기 자신의 고유한 메소드를 갖추지 않고, 다른 인터페이스의 메소드의 파라미터로서의 보고 사용된다.

DirectMusic 는 많은 COM 오브젝트와 인터페이스에 의해 구성되어 있어 그것들은 복잡한 방법으로 서로 관련하고 있다. 다만, 다음의 광범위한 기능에 따라 몇개의 카테고리로 분류할 수 있다.

  • 코어 오브젝트와 인터페이스
  • 로더 오브젝트와 인터페이스
  • 음색 오브젝트와 인터페이스
  • 툴 오브젝트와 인터페이스
  • 퍼포먼스 오브젝트와 인터페이스
  • 작곡가 오브젝트와 인터페이스
  • 신디사이저 오브젝트와 인터페이스


코어 오브젝트와 인터페이스

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic 클래스의 개요」를 참조할것.

[C++]

코어 오브젝트는, DirectMusic 의 기본적인 요구 (입력, 출력, 및 타이밍)를 처리한다. 이러한 오브젝트는, 보통은 DirectMusicPerformance 등의 다른 오브젝트로 관리되어 개발자가 직접 인터페이스를 사용할 필요는 없다.

DirectMusic 오브젝트

IDirectMusic 인터페이스에 의해 나타내지는 DirectMusic 오브젝트는, 포트와 버퍼의 생성, DirectSound 와의 접속, 및 master clock의 설정에 사용된다. 각 어플리케이션은, 이 오브젝트의 인스턴스를 복수 생성 해서는 안된다.

많은 어플리케이션에서는, 직접 IDirectMusic 인터페이스를 사용할 필요는 없다. 이 점은, DirectX 베이스외의 인터페이스와는 다르다. 예를 들어,IDirectSound 는 모든 DirectSound 어플리케이션의 출발점이다. 협조 레벨의 설정이나 사운드 버퍼의 생성등의 기본적인 태스크를 실행한다. 한편, DirectMusic 에서는, 초기화의 대부분은 DirectMusicPerformance 등의 다른 오브젝트에 의해 처리되어 이러한 오브젝트는 CoCreateInstance 를 직접 호출해 독립적으로 생성 된다.

포트

뮤직 데이터의 송수신을 실시하는 각 디바이스는, DirectMusicPort 오브젝트내에 캡슐화되고 있다. IDirectMusicPort 인터페이스의 메소드를 사용하면(자) 포트를 직접 조작할 수 있지만, 포트는 퍼포먼스에 의해 관리되고 있기 (위해)때문에, 대부분의 어플리케이션에서는 이러한 메소드를 필요로 하지 않는다. 예를 들어, 채널내의 데이터가 올바르고 루팅 되도록(듯이) 하려면 , DirectMusicPerformance 오브젝트를 통해 채널을 포트에 할당한다.

버퍼

IDirectMusicBuffer 인터페이스는, 포트로 연주할 준비 (또는 포트로부터 읽어들일 준비)가 되어 있는 데이터를 나타낸다. 대부분의 어플리케이션에서는 버퍼 오브젝트를 직접 취급할 것은 없지만, 필요한 경우는, 그 내용을 직접 조작하기 위한 메소드가 제공되고 있다.

스르

IDirectMusicThru 인터페이스는, 캡춰 포트로부터 다른 포트에의 데이터의 직접 전송을 설정하기 위해서 사용된다.

기준 클럭

IReferenceClock 인터페이스를 이행 하는 오브젝트는 master clock를 나타내, 모든 DirectMusic 액티버티와 포트의 지연 시간 클럭을 동기 시킨다.


로더 오브젝트와 인터페이스

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic 클래스의 개요」를 참조할것.

[C++]

DirectMusicCollection 나 DirectMusicStyle 와 같은 특정의 타입의 오브젝트는, 음악의 퍼포먼스에 짜넣기 전에 (보통은 파일로부터) 로드하지 않으면 안 된다. DirectMusicSegment 등의 그 외의 오브젝트는, 실행시에 로드 또는 구축할 수가 있다. 여기서 소개하고 있는 인터페이스는, 로드에 필요하다.

로더

DirectMusicLoader 오브젝트는,IDirectMusicLoader 인터페이스를 통해서, 오브젝트의 열거, 캐싱, 및 로드를 관리한다.

스트림

파일 또는 리소스로부터 읽히는 데이터는, 스트림 오브젝트에 의해 나타내진다. 스트림은 로더에 의해 생성 및 관리되어 대부분의 어플리케이션에서는 직접 스트림을 처리할 필요는 없다. 스트림 오브젝트는, 다음의 2 개의 인터페이스를 이행 한다.

  • IStream 는, 파일 또는 리소스로부터 데이터를 스트림에 넣어 로드 되고 있는 오브젝트에 건네준다. 오브젝트는 IPersistStream 의 이행을 사용해, 이것을 해석한다.
  • IDirectMusicGetLoader 는, 스트림을 생성 한 DirectMusicLoader 오브젝트에의 포인터를 돌려주는, 1 개의 메소드를 가진다. 이 인터페이스는, 스트림에 다른 오브젝트에의 참조가 발견되었을 경우, 및 로드 되고 있는 오브젝트가 로더를 호출해, 참조된 오브젝트를 로드하는 경우에 사용된다.

이러한 인터페이스를 로드 처리로 사용하는 방법의 상세한 것에 대하여는, 「DirectMusic 로더」를 참조할것.

오브젝트

파일이나 리소스를 나타내는 DirectMusic 의 모든 오브젝트는,IDirectMusicObject 인터페이스를 지원 한다. 이것은, 로더에 의해 범용의 포인터로서 사용된다. 어플리케이션이 이 인터페이스에의 포인터를 취득하고 있는 경우는,IDirectMusicObject::QueryInterface 메소드를 사용해,IDirectMusicCollection 나 IDirectMusicStyle 등의, 오브젝트 고유의 인터페이스에의 포인터를 취득할 수 있다. 다만, 보통은 IDirectMusicLoader::GetObject 의 호출로, 필요한 인터페이스를 취득할 수가 있다.

IDirectMusicObject 의 메소드는, 로더가 오브젝트를 식별하기 위해서 내부에서 사용된다.


음색 오브젝트와 인터페이스

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic 클래스의 개요」를 참조할것.

[C++]

음색은, 기본적인 뮤직크틴바 또는 그 외의 사운드를 나타내는 오브젝트이다. 구래의 하드웨어 MIDI 포트를 제외한 모든 포트로, 각 음색은다운로더블 사운드 (DLS)의 독자적인 세트에 관련지을 수 있다. DLS 는, 음색을 사용하기 전에 포트에 다운로드해야 한다.

다운로더블 사운드는, 3 개의 추상화 레벨로 처리할 수 있다. 가장 높은 레벨에서는, 파일로부터 밴드를 로드해, 밴드 오브젝트를 사용해 음색의 DLS 를 다운로드한다. 다음의 레벨에서는, 콜렉션의 각 음색에 직접 액세스 해, 포트에 다운로드한다. 가장 낮은 레벨에서는, DLS 데이터 그 자체를 조작한다.

음색의 관리에는, 다음의 오브젝트와 인터페이스를 사용한다.

콜렉션

음색은 DirectMusicCollection 오브젝트에 저장 된다. 이 오브젝트는, DLS 파일의 인스턴스를 나타낸다. DirectMusicCollection 오브젝트가 로드 되면(자),IDirectMusicCollection 인터페이스를 사용해, 콜렉션의 음색을 열거해, 지정한 MIDI 패치 번호를 가지는 음색에의 포인터를 취득할 수 있다.

음색

콜렉션의 음색은,IDirectMusicInstrument 인터페이스에의 포인터에 의해 나타내진다. 이 포인터를 IDirectMusicPerformance::DownloadInstrument 또는 IDirectMusicPort::DownloadInstrument 메소드에 건네주어, 포트에 DLS 데이터를 다운로드할 수가 있다.

다운로드된 음색은,IDirectMusicDownloadedInstrument 인터페이스 포인터에 의해 나타내진다. 이 포인터는,IDirectMusicPort::UnloadInstrument 를 호출해 음색을 언로드하는 경우에게만 사용된다.

음색용의 독자적인 DLS 데이터를 다운로드할 필요가 있는 어플리케이션 (콜렉션 편집 툴등)은, 포트 오브젝트에 의해 이행 된 IDirectMusicPortDownload 인터페이스의 메소드를 사용해, 신디사이저용의 데이터를 취득할 수 있다. 이 인터페이스를 사용해 음색 데이터의 버퍼를 할당하면(자),IDirectMusicDownload 인터페이스 포인터가 돌려주어진다. 이 인터페이스의 유일한 메소드를 사용해, 버퍼 그 자체에의 포인터를 취득할 수가 있다.

밴드

DirectMusicBand 오브젝트는, 일련의 음색을 나타내고 있어 이것에 의해 MIDI 프로그램은 뮤직 세그먼트(segment)로 변경을 더한다. 밴드는, authoring tool로 생성 되어 파일로부터 별개에 로드할 수가 있다. 또, 오쏘링 된 세그먼트(segment) 또는 스타일의 일부로 할 수도 있다.

IDirectMusicBand 인터페이스를 사용해, 밴드를 다운로드 및 언로드할 수가 있다. 이 인터페이스에는, 밴드로부터 세컨드리 세그먼트(segment)를 생성 하는 메소드도 포함된다. 이 세그먼트(segment)는 퍼포먼스에 의해 연주되어 프로그램 체인지를 실행한다.

콜렉션과 밴드의 중요한 차이는 다음과 같다.

  • 콜렉션은, 임의의 세그먼트(segment)의 재생에 이용할 수 있는 음색의 그룹이다. 밴드는, 특정의 세그먼트(segment)를 실제로 연주하는 음색의 그룹이다.
  • 콜렉션중의 음색에는, 틴바를 정의하고 있는 DLS 데이터가 포함되어 있다. 밴드의 음색에는 이러한 데이터는 포함되지 않지만, 1 개(살) 또는 복수의 콜렉션의 음색에 링크된다.
  • 콜렉션의 음색은, 세그먼트(segment)의 특정의 퍼포먼스 채널 (P 채널)에는 관련지을 수 있지 않았다. 밴드는, 음색의 패치 번호를 세그먼트(segment)내의 각 P 채널에 할당해 발음의 우선 순위를 채널에 할당한다.
  • 콜렉션은, 음색을 연주하는 방법에 관해서 아무것도 정보를 보관 유지하고 있지 않다. 밴드는, 각 음색의 볼륨, 팬, 전조의 설정을 보관 유지하고 있다.


툴 오브젝트와 인터페이스

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic 클래스의 개요」를 참조할것.

[C++]

툴은 뮤직 메세지에 끼어들어, 포트에 건네주기 전에 메세지를 처리하는 오브젝트이다. 모든 툴은 (DirectMusic 에 의해 이행 되는 출력 툴을 제외해), 어플리케이션으로 정의된다.

툴

IDirectMusicTool 인터페이스는, 1 개의 툴을 나타낸다. 이 인터페이스의 메소드는, 툴의 기능을 정의하기 위해서 어플리케이션 또는 DLL 에 의해 이행 된다.

그래프

복수의 툴은 그래프내에 수집되어IDirectMusicGraph 인터페이스에 의해 나타내진다. 이 인터페이스는, 세그먼트(segment) 및 퍼포먼스 오브젝트의 양쪽 모두에 의해 이행 된다. 이 인터페이스는, 어느 툴로부터 다른 툴에 메세지를 전송 해, 툴을 그래프에 추가해, 개별의 툴에의 포인터를 꺼내, 그래프를 슛다운 하기 위해서 사용된다.


퍼포먼스 오브젝트와 인터페이스

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic 클래스의 개요」를 참조할것.

[C++]

뮤직 데이터를 재생하려면 , 다음의 오브젝트와 인터페이스를 사용한다. 이 그룹의 인터페이스에는, 전부 75 이상의 메소드가 있어, DirectMusic 어플리케이션에 대해 주요한 역할을 연기한다.

퍼포먼스

DirectMusicPerformance 오브젝트는, 음악 재생의 종합적인 매니저이다. IDirectMusicPerformance 인터페이스를 통해, 포트의 추가와 삭제, 음색의 다운로드, 그래프 (툴의 집합)의 부가, 복수의 세그먼트(segment)의 이벤트 통지의 관리, 및 세그먼트(segment)의 연주를 실시한다.

세그먼트(segment)

DirectMusicSegment 오브젝트는 데이터의 체크를 나타낸다. 거의 경우는 음악의 부품으로, 1 개(살) 또는 복수의 트랙에 포함된다. 보통, 세그먼트(segment)는 파일로부터 로드하는지, 실행시에 DirectMusicComposer 오브젝트를 사용해 생성 한다. 세그먼트(segment)를 연주하려면 , 어플리케이션은 IDirectMusicSegment 인터페이스 포인터를 IDirectMusicPerformance::PlaySegment 메소드에 건네준다.

IDirectMusicSegment 인터페이스의 메소드는, 타이밍, 루프, 이벤트 통지, 트랙, 툴 그래프, 및 세그먼트(segment)의 그 외의 다양한 파라미터의 관리에 사용된다.

연주중의 세그먼트(segment)의 인스턴스는, 이제(벌써) 1 개의 인터페이스 IDirectMusicSegmentState 에 의해 나타내진다. 이 인터페이스의 메소드는, 재생 상태에 관한 정보를 돌려준다. 퍼포먼스는 이 인터페이스에의 포인터를 사용해, 세그먼트(segment) 인스턴스의 정지 또는 삭제를 실시한다.

트랙

특정의 종류의 시간 베이스 데이터의 체크는 DirectMusicTrack 오브젝트에 의해 나타내지지만, 보다 단순하게는 트랙으로 불린다. IDirectMusicTrack 인터페이스의 메소드를 사용해, 데이터의 설정과 꺼내, 데이터의 연주, 및 통지의 설정을 실시할 수 있다. 보통, 트랙의 처리는 그러한 트랙을 보관 유지하는 DirectMusicSegment 오브젝트의 메소드에 의해 행해지므로, 대부분의 어플리케이션에서는 이 인터페이스를 직접 사용할 것은 없다.

주 : DirectMusicTrack 는, 음색 트랙과 같은 것은 아니다. DirectMusicTrack 는, MIDI 메세지, 코드 진행, 밴드 변경 등, 모든 종류의 시간 베이스의 데이터를 나타낸다.


작곡가 오브젝트와 인터페이스

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic 클래스의 개요」를 참조할것.

[C++]

이 카테고리의 오브젝트와 인터페이스는, 음악의 리얼타임 어레인지에 사용된다. 작곡가 자신을 제외해, DirectMusic Producer 등의 어플리케이션으로 생성 된 파일로부터 로드 된 데이터를 나타낸다. 각 오브젝트의 역할에 대해서는, 「음악의 어레인지」를 참조할것.

작곡가

IDirectMusicComposer 인터페이스의 메소드에 의해, 인간의 작곡자가 생성 한 코드 맵, 스타일, 및 템플릿을 사용해, 어플리케이션으로 뮤직 세그먼트(segment) 및 이행부를 어레인지 할 수가 있다.

스타일

스타일에는, 음표의 패턴을 포함한, 음악의 일부분에 관한 기본적인 정보가 포함된다. 스타일은, 오쏘링 된 세그먼트(segment)를 구성해 있는 경우가 있다. 이 경우, 대부분의 처리는 배경으로 실행된다. 또, 완전히 새로운 세그먼트(segment)를 실행시에 어레인지 할 수도 있다. 스타일은,IDirectMusicStyle 인터페이스에 의해 나타내진다.

코드 맵

DirectMusicChordMap 오브젝트는, 음악의 일부분의 코드 진행을 결정하기 위해서(때문에) DirectMusicComposer 로 사용되는, 코드와 패스의 집합을 나타낸다.

IDirectMusicChordMap 인터페이스는, 파일로부터 로드 된 DirectMusicChordMap 오브젝트용으로 취득한다. 이 인터페이스에의 포인터를 IDirectMusicComposer 의 메소드에 건네주는 것으로, 오쏘링 된 코드 맵을 사용해, 세그먼트(segment) 또는 이행부를 실행시에 생성 할 수가 있다. 새로운 코드 맵을 적용하는 것으로써, 기존의 세그먼트(segment)의 코드 패턴을 변경할 수도 있다.

템플릿

템플릿은, 특별한 타입의 DirectMusicSegment 오브젝트이다. 직접 연주될 것은 없지만, DirectMusicComposer 가 스타일과 코드 맵에 근거해, 세그먼트(segment)를 리얼타임에 구축하기 위해서 사용된다.


신디사이저 오브젝트와 인터페이스

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic 클래스의 개요」를 참조할것.

[C++]

신디사이저는, MIDI 메세지를 웨이브 폼 데이터로 변환해, 이것을 웨이브 출력 디바이스의 스트림에 넣는다. DirectMusic 에는 독자적인 소프트웨어 신디사이저가 부속되지만, 커스텀 신디사이저를 이행 하는 일도 가능하다. 출력을 다른 디바이스에 전송 하는 일도 가능하다. 이러한 정보는, DirectX DDK (Driver Development Kit)에 포함되어 있다.

신디사이저

어플리케이션에 의해 이행 된 신디사이저는,IDirectMusicSynth 인터페이스에 의해 나타내진다. 대부분의 어플리케이션은, 이 인터페이스를 사용하지 않는다. 또, 이 인터페이스에 대해서는 DirectX SDK 에서는 문서화되어 있지 않다.

신세신크

DirectSound 나 Microsoft® Win32® 의 웨이브 폼 오디오 등, 신디사이저가 데이터의 송신에 사용하는 웨이브 스트림으로,IDirectMusicSynthSink 인터페이스에 의해 나타내진다. 대부분의 어플리케이션은, 이 인터페이스를 사용하지 않는다. 또, 이 인터페이스에 대해서는 DirectX SDK 에서는 문서화되어 있지 않다.


DirectMusic 클래스의 개요

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectMusic 오브젝트와 인터페이스의 개요」를 참조할것.

[Visual Basic]

DirectMusic 클래스는, 광범위한 기능에 따라 다음의 카테고리에 그룹화 할 수 있다.

  • 로더 클래스
  • 퍼포먼스 클래스
  • 작곡가 클래스
  • 음색 클래스


로더 클래스

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectMusic 오브젝트와 인터페이스의 개요」를 참조할것.

[Visual Basic]

음악을 연주하기 위한 최초의 순서는, 파일 또는 리소스로부터 데이터를 로드하는 것이다. DirectMusicLoader 클래스의 오브젝트는, 밴드, 콜렉션, 세그먼트(segment), 및 스타일의 로드에 사용된다. 모든 파일 입출력과 데이터의 해석은, DirectMusic 에 의해 처리된다.

DirectMusicLoader 메소드 (SetSearchDirectory 이외)는 각각, 데이터를 나타내는 오브젝트를 돌려준다. 로드 되고 있는 프라이머리 오브젝트에 의해 참조되고 있는 것 외의 오브젝트도, 이용 가능해진다. 예를 들어,DirectMusicLoader.LoadStyle 를 사용해 로드한 스타일에 밴드에의 참조가 포함되어 있는 경우, 스타일 오브젝트의 메소드를 호출하는 것으로, 밴드 오브젝트를 언제라도 꺼낼 수가 있다.


퍼포먼스 클래스

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectMusic 오브젝트와 인터페이스의 개요」를 참조할것.

[Visual Basic]

DirectMusicPerformance 클래스는, DirectMusic 어플리케이션의 중심이다. 대부분의 어플리케이션은, 이 클래스의 오브젝트를 1 개 가져, 타이밍과 포트의 관리, 마스터 템포등의 글로벌 뮤직 파라미터의 변경, 및 뮤직 세그먼트(segment)의 연주를 실시한다.

MIDI 파일이나, DirectMusic Producer 등의 어플리케이션으로 오쏘링 된 세그먼트(segment) 등, 음악의 부품은 각각 DirectMusicSegment 클래스의 오브젝트에 의해 나타내진다. 이 클래스의 메소드를 사용하면(자), 세그먼트(segment)의 뮤직 파라미터를 설정 또는 꺼내거나 관련지을 수 있고 있는 DLS 음색을 관리할 수가 있다. DirectMusicSegment 의 특수한 형태인 템플릿은, 연주 가능한 세그먼트(segment)의 리얼타임 어레인지에 사용된다.

DirectMusicSegment 오브젝트를 DirectMusicPerformance.PlaySegment 에 건네줄 때, 메소드는, 세그먼트(segment)의 연주중의 인스턴스를 나타내는 DirectMusicSegmentState 클래스의 오브젝트를 돌려준다. 이 오브젝트의 메소드를 사용하면(자), 연주가 시작 된 타임등의 정보를 취득할 수 있다. DirectMusicSegmentState 는, 세그먼트(segment)가 현재 연주중일지 어떨지를 판정하거나 재생을 정지하기 위해서,DirectMusicPerformance 에도 건네받는다.


작곡가 클래스

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectMusic 오브젝트와 인터페이스의 개요」를 참조할것.

[Visual Basic]

DirectMusic 어플리케이션으로 연주되는 음악의 상당수는, MIDI 파일로서 또는 세그먼트(segment)로서 완전하게 오쏘링 되고 있다. 다만, DirectMusic 에서는, 스타일 및 템플릿등의 요소에 근거해, 실행시에 어플리케이션으로 음악을 어레인지 할 수도 있다.

DirectMusicComposer 클래스에는, 템플릿, 코드 맵이나 템플릿에 근거한 연주 가능한 세그먼트(segment), 또는 다른 세그먼트(segment)에 근거한 이행부를 나타내는,DirectMusicSegment 오브젝트를 생성 하는 메소드가 포함된다. 작곡가 오브젝트를 사용하면(자), 기존의 세그먼트(segment)의 코드 맵을 변경할 수도 있다.

DirectMusicChordMap 클래스는, 파일 또는 리소스로부터 로드 된 코드 맵을 나타낸다. 이것에 의해, 코드 진행을 생성 하기 위해서 필요한 정보가 DirectMusicComposer 에 공급된다.

DirectMusicStyle 클래스의 오브젝트는, 다른 엔티티로서 또는 오쏘링 된 세그먼트(segment)의 일부로서 파일 또는 리소스로부터의 데이터에도 기초를 두고 있다. 이 오브젝트는, 어레인지에 사용되는 뮤직 패턴세트를 나타내,DirectMusicComposer 의 메소드에게 건네진다. 고유의 메소드는, 모티프나 밴드 등, 스타일로 결정되고 있는 것 외의 요소를 꺼내기 위해서(때문에) 사용된다.


음색 클래스

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectMusic 오브젝트와 인터페이스의 개요」를 참조할것.

[Visual Basic]

DirectMusicBand 클래스는, 음악의 부품에 할당할 수 있었던 음색세트 (볼륨, 팬, 및 전조를 포함한다)를 나타낸다. 스타일로 결정되고 있는 밴드 체인지는, 스타일에 근거하는 세그먼트(segment)가 연주되고 있을 때 자동적으로 행해진다. 다만, 스타일로부터, 또는 다른 파일이나 리소스로부터 DirectMusicBand 오브젝트를 취득해,DirectMusicSegment 를 생성 할 수도 있다. 이 세그먼트(segment)를 연주해, 프로그램 체인지 할 수가 있다.

DirectMusicCollection 클래스는,DLS 콜렉션을 나타낸다. 세그먼트(segment)가 연주될 때, 또는 밴드가 다운로드될 때, 음색 데이터가 포트에 다운로드되므로, 대부분의 어플리케이션에서는 직접 콜렉션을 조작할 필요는 없다.

콜렉션과 밴드의 주된 차이는 다음과 같다.

  • 콜렉션은, 임의의 세그먼트(segment)의 재생에 이용할 수 있는 음색의 그룹이다. 밴드는, 특정의 세그먼트(segment)를 실제로 연주하는 음색의 그룹이다.
  • 콜렉션중의 음색에는, 틴바를 정의하고 있는 DLS 데이터가 포함되어 있다. 밴드의 음색에는, 이러한 데이터가 포함되지 않지만, 1 개(살) 또는 복수의 콜렉션의 음색에 링크된다.
  • 콜렉션의 음색은, 세그먼트(segment)의 특정의 퍼포먼스 채널 (P 채널)에는 관련지을 수 있지 않았다. 밴드는, 음색의 패치 번호를 세그먼트(segment)내의 각 P 채널에 할당해 발음의 우선 순위를 채널에 할당한다.
  • 콜렉션은, 음색을 연주하는 방법에 관해서 아무것도 정보를 보관 유지하고 있지 않다. 밴드는, 각 음색의 볼륨, 팬, 전조의 설정을 보관 유지한다.


DirectMusic 의 데이터의 흐름의 개요

일반적으로, DirectMusic 어플리케이션은, 다음에 나타내는 것 같은 1 개(살) 또는 복수의 소스로부터 뮤직 데이터를 취득한다.

  • MIDI 파일
  • DirectMusic Producer 등의 어플리케이션으로 오쏘링 된 세그먼트(segment) 파일
  • DirectMusic Producer 등의 어플리케이션으로 오쏘링 되어 DirectMusicComposer 오브젝트에 의해 완전하게 어레인지 된 컴퍼넌트 파일

주 : 이러한 데이터 소스는, 리소스로서 어플리케이션에 저장 할 수가 있다.

이러한 소스로부터의 데이터는, DirectMusicSegment 오브젝트에 캡슐화된다. 각 세그먼트(segment) 오브젝트는, 1 개의 소스로부터의 데이터를 나타낸다. 퍼포먼스에서는 언제라도, 1 개(살) 이상의 세그먼트(segment), 즉 1 개의 "프라이머리 세그먼트(segment)" 와 1 개 또는 복수의 "세컨드리 세그먼트(segment)" 을 연주할 수가 있다. 소스 파일은 혼재시킬 수가 있다. 예를 들어, MIDI 파일에 근거하는 세컨드리 세그먼트(segment)를, 오쏘링 된 세그먼트(segment) 파일과 함께 연주할 수가 있다.

1 개의 세그먼트(segment)에는 복수의 트랙이 포함되어 각각이 음표나 템포의 변경 등, 특정의 종류의 타임 데이터를 포함하고 있다.

대부분의 트랙은, 퍼포먼스로 세그먼트(segment)가 연주될 때 메세지를 생성한다. 퍼포먼스는, 어플리케이션 정의 툴에 메세지를 보내, 툴은 메세지를 변경해 건네주거나 메세지의 삭제나, 신규 메세지의 송신을 실시할 수가 있다. 툴은, 세그먼트(segment) 그래프와 퍼포먼스 그래프에 그룹화 된다. 세그먼트(segment) 그래프에서는, 자신의 세그먼트(segment)로부터의 메세지만이 처리된다. 퍼포먼스 그래프에서는, 모든 세그먼트(segment)로부터의 메세지를 받아들일 수 있다.

[Visual Basic]

어플리케이션 정의 툴은, DirectX for Visual Basic 에서는 지원되어 있지 않다.

최종적으로, 메세지는 출력 툴에 도달한다. 출력 툴로, 데이터는 포트에게 건네지기 전에 MIDI 포맷에 변환된다. 채널 고유의 MIDI 메세지는, 포트의 적절한 채널 그룹에 전송 된다. 포트는 사운드 웨이브를 합성해, 웨이브 출력 디바이스 (보통은 DirectSound 버퍼)의 스트림에 넣는다.

다음의 그림은, 파일로부터 꺼내진 뮤직 데이터가, 웨이브 출력 디바이스에 보내지는 모습을 나타내고 있다. 단순하게 하기 위해서, 1 개의 세그먼트(segment)만을 나타내고 있다. 이 세그먼트(segment)는, 3 개의 소스의 몇개의 미카등 데이타를 뽑기 시작하고 있다. 사용할 수 있는 소스는, MIDI 파일, 오쏘링 된 세그먼트(segment) 파일, 또는 DirectMusicComposer 오브젝트에 의해 결합된 컴퍼넌트 파일의 언젠가이다.

퍼포먼스에 있어서의 메세지의 흐름을 상세하게 확인하려면 , 「DirectMusic 메세지」를 참조할것.

그림에 나타나고 있는 처리를 이행 하는 방법에 대해서는, 「DirectMusic 의 요점」의 「DirectMusic 로더」 및 「음악의 연주」를 참조할것.

세그먼트(segment) 및 컴퍼넌트 파일의 상세한 것에 대하여는, 「음악의 어레인지」를 참조할것.

[C++, Visual Basic]


DirectMusic 메세지

뮤직 데이터는, 메세지의 형태로 DirectMusic 퍼포먼스 엔진에게 건네진다. 대부분의 DirectMusic 어플리케이션에서는, 이 메세지를 직접 처리할 필요는 없지만, 그 구조에 대한 기본적인 지식이 있으면(자), DirectMusic 의 동작을 이해하는데 도움이 된다.

DirectMusic 에서는, 2 종류의 메세지가 처리된다.

  • 퍼포먼스 메세지. 순서화 된 데이터는 모두, 이 형식에서 퍼포먼스 엔진에게 건네진다. 이러한 메세지에는, 데이터의 타이밍 및 루팅에 관한 상세한 정보가 포함되어 있다.
  • 스탠다드 MIDI 메세지. 이러한 메세지는, MIDI 파일 또는 디바이스로부터 읽혀 다른 디바이스에 직접 건네받는 (스르 된다)인가, 퍼포먼스에게 건네지기 전에 퍼포먼스 메세지 형식에 변환된다. 신디사이저에의 최종 출력도, MIDI 메세지의 형식이다.

다음의 주제에서는, 메세지와 그 루팅 방법에 대해 자세하게 설명한다.

  • 채널
  • 메세지의 생성과 전달
  • 퍼포먼스 메세지의 타입
  • MIDI 메세지


채널

채널은, 퍼포먼스내의 1 개의 파트에 고유의 메세지의 송신지이다. 예를 들어 채널은, 음색에 사운드를 발생시키는 노트 온 메세지를 받아들이거나 파트에 다른 음색을 할당하는 프로그램 체인지 메세지를 받아들인다 ( 「MIDI 채널 메세지」를 참조할것).

MIDI 1.0 규격에서는, 16 개의 MIDI 채널이 있어, 한 번에 16 을 넘는 음색은 연주할 수 없는 것을 의미하고 있다. DirectMusic 에서는, 이 규격에 대응 하면 동시에, 어플리케이션이 보다 많은 채널을 동시에 이용할 수 있도록(듯이), 채널 그룹이 생성 된다. 최대 65,536 개의 채널 그룹이 동시에 존재해, 각각 16 개의 채널이 포함되므로, 채널 총수는 100 만 이상으로 오른다. 특정의 포트에, 그 포트가 지원 하는 범위에서 임의의 수의 채널 그룹을 할당할 수가 있다. 종래의 MIDI 하드웨어 포트에는, 1 개의 채널 그룹 밖에 할당할 수가 없다.

시스템에크스크루시브멧세이지는, 1 개의 채널 그룹내의 16 채널의 모두에 대해서 송신할 수 있지만, 다른 채널 그룹 앞으로는 송신할 수 없다.

DirectMusic 퍼포먼스내의 모든 음색은, 고유의 퍼포먼스 채널, 즉 P 채널을 가진다. P 채널은, 특정의 포트에 대한 특정의 그룹내의 특정의 MIDI 채널을 나타낸다. 퍼포먼스가 있는 밴드를 선택 하면, 그 밴드내의 각 음색은 1 개의 P 채널에 맵 된다.

[C++]

동시에 연주할 수 있는 음표의 수는, 포트로 이용할 수 있는 발음수에 의해 제한된다 (이 수는,DMUS_PORTCAPS 구조체의 dwMaxVoices 멤버로 지정할 수 있다).

[Visual Basic]

동시에 연주할 수 있는 음표의 수는, 포트로 이용할 수 있는 발음수에 의해 제한된다 (이 수는,DMUS_PORTCAPS 형의 lMaxVoices 멤버로 지정할 수 있다).

발음은, 채널로 연주되는 1 개의 음표를 합성하는, 리소스세트이다. 이용할 수 있는 발음의 수보다 많은 음표가 연주되는 경우는, 신디사이저에 의해, 1 개(살) 또는 복수의 음표가 억제되지 않으면 안 된다. 어느 음표를 연주할까는, 현재 음표를 연주하고 있는 발음의 우선 순위에 의해 결정되어 이것은 채널의 우선 순위에 근거한다. 디폴트에서는, 채널은 인덱스값에 근거해 순위를 매기고 된다. 다만, 채널 10 은 MIDI 퍼크션 채널로, 우선 순위는 가장 높아진다.

[C++]

어플리케이션 및 신디사이저에서는, 독자적으로 채널의 우선 순위를 설정할 수 있다. 상세한 것에 대하여는,IDirectMusicPort::GetChannelPriority 의 「주의」를 참조할것. DMUS_CHANNEL_PRIORITY_PMSG 도 참조할것.


메세지의 생성과 전달

세그먼트(segment)가 연주되고 있을 때, 대부분의 트랙은, 재생중에 발생하는 이벤트에 관한 정보를 포함한 메세지를 생성한다 (상세한 것에 대하여는, 「트랙」을 참조할것).

여러종류의 메세지를 송신하는 트랙도 있다. 예를 들어, 스타일 트랙은 음표 메세지와 박자 기호 메세지를 송신한다. 이러한 경우, 어플리케이션은 트랙의 특정의 종류의 메세지를 무효로 할 수 있다. 상세한 것에 대하여는, 「트랙 파라미터의 설정과 꺼내」를 참조할것.

어플리케이션은, 메세지를 직접 큐에 넣을 수도 있다. 예를 들어, 템포를 변경하는 경우에, 이 조작을 실시할 수가 있다.

[C++]

샘플 코드에 대해서는,IDirectMusicPerformance::SendPMsg 를 참조할것.

[Visual Basic]

샘플 코드에 대해서는, 「DLSEffects 샘플」을 참조할것.

퍼포먼스 엔진은, 각 메세지를 실시간 (기준 타임)으로 언제 처리할까를 결정한다. 채널 메세지의 경우, 퍼포먼스는 메세지를 전송 하는 P 채널도 결정한다. 이 정보는, 메세지 타입, 소스 트랙, 메세지를 수신하는 최초의 그래프와 툴에의 포인터등을 보관 유지하는 것 외의 데이터와 함께, 메세지에 보존된다.

템포나 박자 기호의 변경등의 특정의 메세지는, 퍼포먼스에 의해 즉시 처리되어 릴리즈 된다. 음표나 패치의 변경 등, 그 외의 메세지는 큐에 넣어져 타임 스탬프의 순서에 처리된다.

주 : 같은 타임 스탬프의 메세지가 특정의 순서로 처리된다고 하는 보증은 없다.

템포 메세지는, 뮤직 타임을 기준 타임으로 변환하는 방법을 퍼포먼스에게 전한다. 박자 기호는 세그먼트(segment)에 내장되고 있어 변경할 수 없기 때문에, 박자 기호 메세지는 정보를 전하는 것에 지나지 않는다.

[C++]

메세지는 최초로, 세그먼트(segment)의 그래프내의 툴에 송신되어 그 다음에 퍼포먼스의 그래프내의 툴에 송신된다 (어플리케이션은, 이러한 그래프의 언젠가 또는 양쪽 모두를 생성 해, 툴을 정의한다. 디폴트의 그래프는 없다).

그래프내의 최초의 툴은 메세지를 처리해, 그 메세지를 다른 툴에 건네주고 싶은 경우는, 다음의 툴에의 포인터와 함께 그 메세지를 그래프에 스탬프 처리시킨다. 상세한 것에 대하여는, 「튜토리얼 2 : 툴의 사용법 을 참조할것.

이 시점에서, 그래프는 메세지에 전달 타입의 플래그를 할당한다. 이 플래그에 근거해, 메세지를 다음의 툴에 전달하는 시기가 정해진다. 이 플래그는, 툴로 예기 되고 있는, 다음과 같은 전달 타입에 근거하고 있다.

  • 메세지에 DMUS_PMSGF_TOOL_IMMEDIATE 플래그를 할당할 수 있고 있는 경우, 즉석에서 다음의 툴에 전달된다.
  • DMUS_PMSGF_TOOL_QUEUE 플래그를 할당할 수 있고 있는 메세지는, 지연 시간을 고려에 넣은 다음, 연주되면(자) 상정되는 시기의 직전에 전달된다 ( 「지연 시간과 범퍼 시간」을 참조할것).
  • 메세지에 DMUS_PMSGF_TOOL_ATTIME 플래그를 할당할 수 있고 있는 경우, 처리되는 것과 완전히 같은 시기에 전달된다. 통지의 처리에는, 거의 또는 전혀 지연 시간이 발생하지 않기 때문에, 통지 메세지에는 이 플래그를 할당할 수 있다.

그래프가 메세지의 스탬프 처리와 플래그 할당을 실시한 다음에, 현재의 툴은 전달 타입을 변경할 수가 있다.

최종적으로, 메세지는 파기되지 않는 이상 DirectMusic 의 출력 툴에 도달한다. 이 툴은 받은 모든 메세지를 스탠다드 MIDI 메세지로 변환해, 그것들을 포트 버퍼 경유로 신디사이저에 전달한다.


퍼포먼스 메세지의 타입

[C++]

메세지는,DMUS_PMSG 로부터 파생한 다양한 타입에 보존된다. C 는 계승을 지원 하고 있지 않기 때문에,DMUS_PMSG 의 멤버는 DMUS_PMSG_PART 매크로내의 각 메세지 타입의 선언에 포함되어 있다. 이러한 멤버는, 메세지 타입, 타임 스탬프, 메세지 송신지의 퍼포먼스 채널, 메세지 처리에 사용되는 다음의 그래프와 툴을 포함한, 모든 메세지에 있어 공통의 데이터를 보관 유지하고 있다. 다른 멤버는, 메세지 타입 고유의 데이터를 보관 유지하고 있다.

메세지 구조체는 다음과 같이 정의되고 있다.

DMUS_PMSG | 추가 파라미터가 없는 단순한 메세지.
DMUS_CHANNEL_PRIORITY_PMSG | 채널 우선 순위의 변경. 「채널」을 참조할것.
DMUS_CURVE_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 | 전조.

[Visual Basic]

DirectX for Visual Basic 에서는, 어플리케이션이 메세지 구조체에 직접 액세스 할 수 없다. 그 대신에, 특정의 종류의 메세지를 송신하기 위해서, 다음의 메소드가 준비되어 있다.

DirectMusicPerformance.SendCurvePMSG | MIDI 곡선
DirectMusicPerformance.SendNotePMSG | 음악의 음표
DirectMusicPerformance.SendPatchPMSG | 패치의 변경
DirectMusicPerformance.SendMIDIPMSG | 그 외의 MIDI 이벤트
DirectMusicPerformance.SendTempoPMSG | 템포의 변경
DirectMusicPerformance.SendTimeSigPMSG | 박자 기호의 변경
DirectMusicPerformance.SendTransposePMSG | 전조의 변경


MIDI 메세지

여기에서는, 스탠다드 MIDI 메세지의 개요와 일반적으로는 MIDI 파일로부터 스트림에게 건네지는 이러한 메세지를, DirectMusic 로 처리하는 방법에 대해 설명한다. 대부분의 어플리케이션은, MIDI 메세지를 직접 처리하지 않는다. 재생의 자세한 것은 모두, 로더와 퍼포먼스로 관리된다.

MIDI 입력은, 퍼포먼스에 의해 툴에 루팅 되기 전에, 퍼포먼스 메세지 형식에 변환된다. 출력 툴은, 데이터를 신디사이저에 건네주기 전에, 스탠다드 MIDI 메세지 형식에 되돌린다.

주 : MIDI 메세지가, 파일에 기술되고 있는 순서로 처리된다고 하는 보증은 없다. DirectMusic 메세지는 타임 스탬프의 순서에 전달된다. 타임 스탬프가 동일한 MIDI 메세지가 2 개 있는 경우는, 예상과 다른 순서로 전달되는 경우가 있다. MIDI 컨텐츠를 오쏘링 할 경우에, 이벤트를 발생시키는 순서가 정해져 있는 경우는, 이러한 이벤트에 같은 타임 스탬프를 주지 않게 주의한다. 예를 들어, 프로그램 체인지에 의존하는 음표가 있는 경우는, 이러한 음표와 프로그램 체인지를 동시에 배치하지 않는다.

MIDI 메세지는, 1 바이트의 스테이터스 바이트와 그 후에 계속되는 1 바이트나 2 바이트의 데이터 바이트에 의해 구성된다. 시스템에크스크루시브 MIDI 메세지는 가변장이다. 스테이터스 바이트는 메세지의 타입을 나타내, 일부의 상황에서는, 그 메세지를 받아들이는 채널을 나타낸다. 파일중에 같은 종류의 이벤트가 계속해 나타나는 경우는, 스테이터스 바이트를 생략 할 수 있다. 이것은, 동작 스테이터스로 불린다. 상위 비트가 항상 소거되고 있으므로, 데이터 바이트를 인식할 수 있다. 스테이터스 바이트의 상위 비트는, 항상 설정되어 있다.

MIDI 이벤트가 파일로부터 스트림에 넣어지는 타이밍은, 각 메세지의 전에 있는 숫자로 제어된다. 이 값은, 이 이벤트와 마지막 이벤트의 간격을, 틱수로 나타내고 있다. 틱의 실제의 계속 시간은, 파일 헤더의 시간의 형식에 의해 결정된다.

MIDI 메세지는, 다음의 2 개의 주요한 카테고리로 분류할 수 있다.

  • MIDI 채널 메세지
  • MIDI 시스템 메세지


MIDI 채널 메세지

채널 메세지는, 음악의 1 개의 파트에 대응하는 특정의 채널을 주소 지정된다.

채널 메세지는, 모드 메시지나 발음 메세지의 어느 쪽인지이다.

모드 메시지는, 채널이 그 이후의 발음 메세지를 취급하는 방법을 결정한다. 예를 들어, 모드 메시지는, 무엇인가 통지가 있을 때까지는 모든 노트 온 메세지를 무시해, 무음 상태를 유지하도록(듯이) 채널에 지시하는 일이 있다.

대부분의 채널 메세지는 발음 메세지이다. 이것들은 채널에 음표의 연주의 시작 또는 정지, 어떠한 방법에서의 음표의 변경을 지시해, 채널에 다른 MIDI 패치 번호를 할당하는 것으로 음색을 변경한다.

발음 메세지는, 다음의 몇개의 타입을 취한다.

발음 메세지 | 목적
노트 온 | 음표를 연주한다.
노트 오프 | 음표의 연주를 정지한다.
컨트롤 체인지 | 페달, 레바, 그 외의 디바이스로부터의 데이터를 사용해 악음을 변경한다. 볼륨이나 뱅크 셀렉트 등, 다양한 컨트롤에도 사용된다.
프로그램 (패치) 체인지 | 패치 번호를 할당하는 것으로, 채널의 음색을 선택한다.
애프터 터치 | 키의 애프터 터치에 따라, 개별의 음표 또는 채널의 모든 음표를 변경한다.
핏치벤드첸지 | 채널로 연주되는 모든 음표의 피치를 변경한다.

이러한 설명은, 스탠다드 MIDI 메세지에 적용되어 퍼포먼스 메세지 형식에 변환된 MIDI 데이터에는 적용되지 않는다. 예를 들어, 음표의 연주를 시작 및 정지하기 위한 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 패치 번호

[Visual Basic]

여기에서는, C++ 로 기술된 어플리케이션에 관련이 있는 내용만을 설명한다. DirectX for Visual Basic 에서는,DirectMusicPerformance.SendPatchPMSG 메소드를 사용하는 방법을 제외해, 어플리케이션으로 패치 번호를 변경하는 것은 인정되지 않았다.

[C++]

MIDI 가 정하는 7 비트 패치 번호와는 달라, DirectMusic 의 음색 패치 번호는 32 비트값이며, 그 중에 MIDI 패치 번호, 뱅크 셀렉트의 MSB 와 LSB, 및 드럼 킷용의 1 비트 플래그가 포함되어 있다. IDirectMusicCollection::EnumInstrument ,IDirectMusicCollection::GetInstrument , 및IDirectMusicInstrument::GetPatch 의 각 메소드는 이 확장 패치 번호를 돌려준다. IDirectMusicInstrument::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 로 불리는 시스템 공통 메세지를 송신해, 시스템에크스크루시브멧세이지의 마지막을 알린다.

[C++]

DirectMusic 에서는,DMUS_SYSEX_PMSG 구조체가, 데이터 길이와 데이터 바이트의 배열에의 포인터를 보관 유지한다.

[Visual Basic]

DirectX for Visual Basic 에서는, 어플리케이션이 시스템에크스크루시브멧세이지에 직접 액세스 할 수 없다.


다운로더블 사운드

지금까지, 대부분의 컴퓨터 음악은, 다음의 2 개의 방법의 어느쪽이든으로 생성되고 있었다. 각각 이점은 있지만, 결점도 있다.

  • 보통은 . WAV 파일, 또는 레드 북 오디오 규격에 따른 표준적인 CD 트랙에 기록되고 있는 디지털 샘플로부터 웨이브 폼 (파형)을 재현 하는 방법. 디지털 샘플에서는 어떠한 사운드도 재현 가능해, 어느 사운드 카드를 사용했을 경우에서도 얻을 수 있는 출력은 매우 자주(잘) 비슷하다. 다만, 스트리밍용으로 많은 기억 영역과 리소스가 필요하다.
  • 일반적으로는 MIDI 파일로부터의 메세지에 응답해, 음색의 사운드를 보통은 하드웨어로 합성하는 방법. MIDI 파일은 컴팩트해, 스트리밍 리소스도 불과 밖에 필요로 하지 않지만, 출력은 General MIDI 세트의 신디사이저로 이용할 수 있는 음색의 수로 한정되어 시스템에 따라서는 매우 다른 소리가 되는 경우가 있다.

디지털 샘플링의 이점과 MIDI 의 컴팩트함 및 유연성을 조합하는 1 개의 방법이, 웨이브 테이블 합성이다. 이것은, 디지털 샘플로부터 음색의 사운드를 합성하는 방법이다. 실제의 음색을 레코딩 하는 것에 의해 샘플을 취득해, 하드웨어에 보존한다. 다양한 피치와 볼륨으로 임의의 길이의 사운드를 생성 하기 위해서, 샘플의 루프라고 조정을 한다.

웨이브 테이블 합성은 알고리즘에 근거하는 FM 합성보다 현실적인 틴바를 생성 하지만, 여전히 고정 세트의 음색으로 한정된다. 한층 더 특정의 음색의 사운드는 메이커의 이행에 따라서 달라, 하드웨어의 편성이 다르면(자) 매우 다른 사운드가 되는 경우가 있다.

이러한 제한을 극복하기 위해서, MIDI Manufactures Association 에 의해 다운로더블 사운드 (downloadable sounds, DLS) 규격이 발표되었다. DLS 는, 시스템에 하드 와이어드로 이행 된 샘플 대신에, 실행시에 제공되는 샘플에 근거해 웨이브 테이블 합성을 실시할 수가 있는 방법이다. 음색을 기술하는 데이터는 신디사이저에 다운로드되어 그 후는 다른 MIDI 음색과 같게 그 음색을 연주할 수 있다. DLS 는 어플리케이션의 일부로서 전달할 수 있기 (위해)때문에, 개발자는 사운드 트랙을 모든 시스템으로 똑같이 연주시킬 수가 있다. 또, 음색의 선택이 제한될 것도 없다.

DLS 음색은 1 개 또는 복수의 샘플로부터 생성 되어 보통은 싱글 피치를 나타내지만, 신디사이저로 변경을 더하는 것으로 그 외의 피치를 생성 할 수 있다. 광범위의 피치로 음색의 사운드를 현실적으로 하려면 , 복수의 샘플을 사용한다. DLS 음색을 다운로드할 때에, 리젼으로 불리는 특정의 피치 범위가 각 샘플에 할당할 수 있다. 보통, 16 개보다 많은 리젼을 사용할 것은 없다.

더해, 샘플에 아티큘레이션을 줄 수도 있다. 이것은 어택 (음표가 풀 볼륨에 이르는 속도), 디케이 (풀 볼륨으로부터 감쇠하는 속도), 및 사운드를 실제의 음색에 의해 접근하기 위한 그 외의 특징을 정의한다.

다운로더블 사운드는 음색 콜렉션에 저장 되어 여기로부터 신디사이저에 다운로드된다.

다른 MIDI 음색의 경우와 같게, DLS 음색에는 패치 번호를 할당할 수 있어 MIDI 메세지에 응답한다. 다만, DLS 음색 (기기)은 General MIDI 세트에 따를 필요는 없다. 실제, 음색을 나타낼 필요는 전혀 없다. 연설의 일부나 생성 끝난 완전한 소절 등, 어떤 사운드라도 DLS 음색으로 변환할 수가 있다.

DLS 콜렉션과 DLS 음색의 생성 방법의 상세한 것에 대하여는, DirectMusic Producer 의 문서를 참조할것. 어플리케이션에 DLS 를 짜넣는 방법의 상세한 것에 대하여는, 「DLS 의 사용법」을 참조할것.


Microsoft Software Synthesizer

Microsoft Software Synthesizer 은 DirectMusic 와 함께 제공되어 하드웨어 DLS 를 이용할 수 없는, 또는 DLS 가 operating system로 지원되어 있지 않은 경우에, 디폴트 포트가 된다. 이 신디사이저는 DLS 샘플에 근거하는 음색의 틴바를 사용해, MIDI 메세지의 스트림에 근거하는 웨이브 폼을 생성 한다. 디폴트에서는, 샘플은 Roland GS 콜렉션으로부터 놓치지만, 이 콜렉션도 DirectMusic 의 일부로서 인스톨 된다. 신디사이저는, 출력을 DirectSound 믹서에 송신한다.

주 : Roland GM/GS Sound Set 를 수정할 수 없다. 「법적 정보」의 「저작권에 관한 주의」를 참조할것.

Microsoft Software Synthesizer 에는, 리바브 기능이 포함되어 있어 디폴트로 유효하게 되어 있다. Waves TrueVerb 리바브테크노로지가 Microsoft 에 라이센스 되고 있어 SimpleVerb 로서 이행 되고 있다.


DirectMusic 의 요점

여기에서는, DirectMusic 를 어플리케이션에 이행 하는 방법에 대한, 실제적인 정보를 설명한다. 일반적인 개요에 대해서는, 「DirectMusic 아키텍쳐」를 참조할것.

다음의 항목에 대해 설명한다.

  • DirectMusic 프로젝트의 생성
  • DirectMusic 프로젝트의 디버그
  • DirectMusic 와 DirectSound 의 통합
  • 포트의 사용법
  • DirectMusic 로더
  • DirectMusic 의 파일 형식
  • DLS 의 사용법
  • 음악의 연주
  • 뮤직 파라미터
  • 음악의 캡춰
  • DirectMusic 툴
  • 음악의 어레인지


DirectMusic 프로젝트의 생성

[Visual Basic]

여기에서는, C++ 에 의한 어플리케이션 개발에 관련하는 내용만을 설명한다.

[C++]

다른 DirectX 컴퍼넌트와 달리, DirectMusic API 는 완전한 COM 베이스이며, COM 오브젝트를 생성 하는 헬퍼-함수등의 라이브러리 함수를 포함하지 않는다. 따라서, 빌드중에 링크하는 Dmusic.lib 파일은 존재하지 않는다.

대부분의 프로젝트에서는, Dmusicc.h 및 Dmusici.h 헤더 파일을 인클루드 해야 한다. 이러한 파일에는, 각각 코어 계층 및 퍼포먼스 계층의 선언이 포함되어 있다. 또, 반환값을 포함한 Dmerror.h 파일도 인클루드 해야 한다. Dmusicf.h 에는 파일 형식이 포함되어 파일을 직접 조작하거나 DirectMusic 에 짜넣어진 로더에 전혀 의존하지 않는, 뮤직 authoring tool등의 어플리케이션에서만 필요하다.

Dmksctrl.h 에는, 프로퍼티의 설정으로 사용되는 IKsControl 인터페이스의 선언이 포함되어 있다. Ksproxy.h 및 Ks.h 파일이 있는 경우, 이 파일은 필요없다.

DirectMusic 는, Windows 32 비트 operating system의 multi-thread 기능을 사용한다. multi-thread를 이용하는 것에 의해, 어플리케이션이 다른 태스크를 실행하고 있는 동안에, DirectMusic 는 백그라운드에서 음악의 생성, 처리, 및 합성을 실시할 수가 있다. 프로젝트를 multi-thread를 사용해 개발하도록(듯이) 주의 해야 한다. 적어도, multi-thread 라이브러리와 링크하는 것.

또, 어플리케이션이 DirectMusic 로 사용되는 GUID 에 액세스 할 수 있도록(듯이) 주의한다. 상세한 것에 대하여는, 「DirectX 의 샘플 및 그 외의 DirectX 어플리케이션의 컴파일」을 참조할것.


DirectMusic 프로젝트의 디버그

[Visual Basic]

여기에서는, C++ 에 의한 어플리케이션 개발에 관련하는 내용만을 설명한다.

[C++]

DirectX 소프트웨어 개발 킷의 디버그 버젼으로 인스톨 되는 DirectMusic DLL (동적 링크 라이브러리)는, 어플리케이션의 실행시에, 정보를 디버그 출력 윈도우에 생성한다. 디폴트에서는, 이용할 수 있는 모든 정보가 표시된다.

Win.ini 의 값을 변경 하면, 디버그 출력 윈도우에 표시되는 정보를 제어할 수가 있다. DirectMusic DLL 각각의 출력은, 다음의 예에 나타내도록(듯이), 개별적으로 설정할 수가 있다.

[Debug]
DMBAND=1
DMCOMPOS=1
DMIME=1
DMLOADER=0
DMUSIC=1
DMSTYLE=3
DMSYNTH=5

각각의 값은 0 ~ 5 의 범위에서 설정할 수 있다. 표시되는 디버그 정보의 양은, 0 으로 가장 적고, 5 로 가장 많아진다. Win.ini 에 엔트리가 없는 경우, 디버그 출력의 레벨은 0 이 된다. 특정의 컴퍼넌트에 다른 컴퍼넌트보다 높은 값을 설정해, 그 컴퍼넌트의 문제에 주목할 수가 있다. 컨트롤 패널의 DirectX 프로퍼티 시트를 사용해, 디버그 레벨을 변경할 수도 있다. 다만, 이 방법에서는 모든 DirectMusic 컴퍼넌트에 같은 값이 설정된다.

「DirectX 어플리케이션의 디버그」를 참조할것.


DirectMusic 와 DirectSound 의 통합

보통, Microsoft Software Synthesizer 나 그 외의 신디사이저는, 출력 웨이브 데이터를 DirectSound 버퍼의 스트림에 넣는다. DirectMusic 에서는, 특별한 조작을 필요로 하지 않고 , DirectSound 에의 링크의 상세를 모두 처리할 수가 있다. DirectSound 오브젝트를 생성 하거나 링크할 경우에, DirectMusic 는 프라이머리 버퍼 포맷을, 모든 DirectMusic 포트간에 최고의 포맷에 일치시킨다.

[C++]

사운드 트랙으로 뮤직 파일만을 사용해, 웨이브 파일이나 리소스의 연주에 DirectSound 를 필요로 하지 않는 어플리케이션의 경우, 보통은 DirectMusic 의 퍼포먼스가 초기화될 때 DirectSound 오브젝트가 생성 된다. 다음에 예에 나타낸다. pPerf 는 IDirectMusicPerformance 인터페이스에의 포인터이다.

pPerf->Init(NULL, NULL, hwnd);

이 예에서는, 최초의 NULL 는 내부에서 생성 및 관리되는 DirectMusic 오브젝트를 지정해, 2 번째의 NULL 는 같은 DirectSound 오브젝트를 지정한다. hwnd 는, DirectSound 의 제어 윈도우의 핸들을 나타낸다.

주 : DirectMusic 에 DirectSound 오브젝트를 생성 하도록(듯이) 요구할 경우에, 최상정도 레벨 어플리케이션 윈도우의 핸들을 제공하는 것은 좋은 생각이다. IDirectMusicPerformance::Init 및 IDirectSound::SetCooperativeLevel 의 「주의」를 참조할것.

[Visual Basic]

사운드 트랙으로 뮤직 파일만을 사용해, 웨이브 파일이나 리소스의 연주에 DirectSound 를 필요로 하지 않는 어플리케이션의 경우, 일반적으로는 DirectMusic 의 퍼포먼스가 초기화될 때 DirectSound 오브젝트가 생성 된다. 다음에 예를 나타낸다. Perf 는,DirectMusicPerformance 오브젝트이다.

Perf.Init(Nothing, hwnd);

이 예에서는,Nothing 는 DirectSound 오브젝트가 내부적으로 생성 되고 관리되는 것을 나타낸다. hwnd 는 DirectSound 의 제어 윈도우의 핸들이다.

주 : DirectMusic 에 DirectSound 오브젝트를 생성 하도록(듯이) 요구할 경우에, 최상정도 레벨 어플리케이션 윈도우의 핸들을 제공하는 것은 좋은 생각이다. DirectMusicPerformance.Init 및DirectSound.SetCooperativeLevel 의 「주의」를 참조할것.

상세한 것에 대하여는, 다음의 주제를 참조할것.

  • DirectSound 오브젝트의 설정
  • DirectSound 버퍼 오브젝트의 설정


DirectSound 오브젝트의 설정

[C++]

DirectMusic 에 DirectSound 오브젝트를 생성 및 관리시켜도, DirectSound 를 사용하지 않는 어플리케이션에는 관계없다. 다만, 어플리케이션이 DirectSound 을 사용해, DirectMusic 신디사이저 이외의 소스로부터 웨이브 데이터를 연주하고 있는 경우는, DirectMusic 에서도 같은 IDirectSound 인터페이스를 사용해야 한다. 우선 DirectSound 오브젝트를 생성 해, 계속되어 DirectMusic 에 인터페이스 포인터를 건네준다. 이 처리는, 다음의 예에 나타내도록(듯이) IDirectMusicPerformance::Init 의 호출로 실행된다. pPerf 는 IDirectMusicPerformance 로,pDS 는 IDirectSound 에의 포인터이다.

pPerf->Init(NULL, pDS, NULL);

주 : IDirectSound 포인터를 IDirectMusicPerformance::Init 에 건네줄 때, 3 번째의 파라미터의 윈도우 핸들은 무시된다. 어플리케이션은 IDirectSound::SetCooperativeLevel 를 호출해, 제어 윈도우의 설정을 실시할 필요가 있다.

DirectMusic 로 사용되는 DirectSound 오브젝트에, DSSCL_PRIORITY 협조 레벨을 설정한다. DSSCL_NORMAL 협조 레벨을 설정했을 경우, DirectMusic 는 프라이머리 버퍼 포맷을 업그레이드 할 수 없다.

퍼포먼스에 의지하지 않고 ,CoCreateInstance 를 사용해 스스로 DirectMusic 오브젝트를 생성 하는 경우는, 명시적으로 기존의 IDirectSound 인터페이스에 링크해야 한다. 이 처리는,IDirectMusic::SetDirectSound 메소드를 사용해 실행된다.

IDirectMusicPort::SetDirectSound 메소드를 사용해, 포트에 다른 DirectSound 오브젝트를 할당할 수도 있다. 다른 포트가 다른 오디오 디바이스상에 있어, 각각이 고유의 IDirectSound 인터페이스로 나타내지고 있는 경우에, 이 조작을 실시한다. 포트의 DirectSound 오브젝트는, 포트가 액티브하게 된다고 변경할 수가 없다.

DirectSound 를 필요로 하는 포트를 액티브하게 하는 경우는, 다음의 리스트로부터, 우선 이용 가능한 IDirectSound 인터페이스를 취득한다.

  1. IDirectMusicPort::SetDirectSound 에게 건네지는 IDirectSound 인터페이스
  2. IDirectMusic::SetDirectSound 에게 건네지는 IDirectSound 인터페이스
  3. IDirectMusic::SetDirectSound 에 NULL 가 건네받았을 경우는, DirectMusic 에 의해 생성 된 IDirectSound 인터페이스

DirectSound 가 에뮬레이션 모드인 경우, 오디오 디바이스가 배타적으로 사용된다. 어플리케이션은, 포커스를 잃었을 때에 DirectSound 를 릴리즈 해, 다른 어플리케이션이 디바이스를 사용할 수 있도록(듯이) 해야 하는 것이다. 일반적으로는, WM_ACTIVATE 메세지에의 응답으로 이 처리를 실시한다.

DirectMusic 가 DirectSound 오브젝트를 생성 하고 있는 경우는, 모든 포트가 비액티브하게 되었을 때에, 오브젝트가 자동적으로 릴리즈 된다 (게다가 DirectMusic 를 사용하는 최초의 포트가 다시 액티브하게 되었을 때에, 오브젝트가 생성 된다). 다만, 스스로 DirectSound 오브젝트를 생성 했을 경우는, 스스로 릴리즈 해야 한다. 이 처리를 실행하려면 ,IDirectMusic::SetDirectSound 또는 IDirectMusicPort::SetDirectSound 메소드에,pDirectSound 파라미터로서 NULL 를 건네준다.

[Visual Basic]

DirectMusic 에 DirectSound 오브젝트를 생성 및 관리시켜도, DirectSound 를 사용하지 않는 어플리케이션에는 관계없다. 다만, 어플리케이션이 DirectSound 을 사용해, DirectMusic 신디사이저 이외의 소스로부터 웨이브 데이터를 연주하고 있는 경우는, DirectMusic 에서도 같은 DirectSound 오브젝트를 사용해야 한다. 우선 DirectSound 오브젝트를 생성 해, 다음에 이것을 DirectMusic 에 건네준다. 이 처리는, 다음의 예에 나타내도록(듯이) DirectMusicPerformance.Init 의 호출로 실행된다. Perf 는 DirectMusicPerformance 오브젝트로,DS 는 DirectSound 오브젝트이다.

Perf.Init(DS, 0);

주 : DirectSound 오브젝트를 DirectMusicPerformance.Init 에 건네줄 때, 2 번째의 파라미터의 윈도우 핸들은 무시된다. 어플리케이션은,DirectSound.SetCooperativeLevel 를 호출해, 제어 윈도우의 설정을 실시할 필요가 있다.

DirctMusic 로 사용되는 DirectSound 오브젝트에, DSSCL_PRIORITY 협조 레벨을 설정한다. DSSCL_NORMAL 협조 레벨을 설정했을 경우, DirectMusic 는 프라이머리 버퍼 포맷을 업그레이드 할 수 없다.


DirectSound 버퍼 오브젝트의 설정

[Visual Basic]

여기에서는, C++ 로 기술된 어플리케이션에 관련이 있는 내용만을 설명한다. DirectX for Visual Basic 에서는, DirectMusic 출력에 대해서 커스텀 DirectSound 버퍼는 지원 되지 않는다.

[C++]

DirectMusic 가 DirectSound 에 링크되는 경우, 각 포트로부터의 웨이브 출력용의 세컨드리 DirectSound 버퍼가, 포트와 같은 형식에서 생성 및 관리된다. IDirectMusicPort::SetDirectSound 메소드를 사용해 디폴트의 동작을 덧쓰기해, 데이터를 다른 버퍼의 스트림에 넣을 수가 있다. 이 조작은, 예를 들어 사운드 버퍼에 3-D 이펙트를 주기 위해서(때문에) 실행할 수 있다 ( 「3DMusic 샘플」을 참조할것). 신디사이저 포트의 인스턴스를 복수 생성 해, 각각 고유의 DirectSound 3-D 버퍼를 설정해, 공간내의 다른 장소에 다른 음색을 배치할 수도 있다.

IDirectMusicPort::SetDirectSound 에 건네주는 버퍼는, 포맷의 일치한 세컨드리 스트리밍 버퍼가 아니면 안된다. 웨이브 포맷의 정보 및 추천 버퍼 사이즈를 취득하려면 ,IDirectMusicPort::GetFormat 메소드를 호출한다.

IDirectMusicPort::SetDirectSound 에 독자적인 IDirectSoundBuffer 를 건네주면(자), DirectMusic 는 프라이머리 버퍼의 업그레이드를 시도하지 않는다.


포트의 사용법

포트는, 뮤직 데이터의 송신 또는 수신을 실시하는 디바이스이다. 하드웨어 디바이스, 소프트웨어 신디사이저, 소프트웨어 필터의 어느쪽이든을 나타낸다.

[C++]

DirectMusic 어플리케이션내의 각 포트는,IDirectMusicPort 인터페이스에 의해 나타내진다. 이 인터페이스의 메소드를 사용해, 디바이스에 관한 정보의 꺼내, 디바이스내의 메모리의 관리,DLS 음색의 다운로드와 언로드, 유입 데이터의 읽어들여, 재생 버퍼의 삽입을 실시한다.

어느 퍼포먼스도 적어도 1 개의 포트를 갖추지 않으면 안 된다. 디폴트 포트 이외의 포트를 사용해, 디폴트 포트의 특별한 파라미터를 설정하는 경우는, 우선 DMUS_PORTPARAMS 구조체를 설정한다. 모든 멤버에 값을 입력할 필요는 없지만,dwValidParams 멤버에 적절한 플래그를 기입하는 것으로, 어느 멤버가 유효한 정보를 가지고 있는지 DirectMusic 에 알리지 않으면 안 된다. 다음에, 이 구조체를 IDirectMusic::CreatePort 메소드에 건네준다.

다음의 C++코드예에서는, 디폴트의 출력 포트용의 오브젝트를 생성 해, 포트에 5 개의 채널 그룹을 설정하는 방법을 나타내고 있다. pDirectMusic 은, 유효한 IDirectMusic 포인터로 한다.

IDirectMusicPort*  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 )

설정한 포트는 IDirectMusic::Activate 또는 IDirectMusicPort::Activate 를 호출해 액티브화해,IDirectMusicPerformance::AddPort 메소드를 사용해 퍼포먼스에 부가한다.

포트를 퍼포먼스에 부가할 경우에,IDirectMusicPerformance::AssignPChannelBlock 메소드를 호출해,P 채널의 블록을 할당한다. IDirectMusicPerformance::AddPort 에 NULL 를 건네주어 디폴트 포트를 추가 하면나무만, 이 처리가 필요없다. 이 경우, P 채널 0-15 은, 포트의 최초의 그룹의 MIDI 채널에 할당할 수 있다.

IDirectMusicPerformance::AssignPChannelBlock 및 IDirectMusicPerformance::AssignPChannel 의 각 메소드를 사용하면(자), 이러한 P 채널을 다른 방법으로 할당해 다른 P 채널을 추가해, P 채널을 다른 포트에 할당할 수가 있다.

[Visual Basic]

DirectX for Visual Basic 에서는, 각 퍼포먼스에 대해서 1 개의 포트만이 지원 되어 모든 P 채널 은 이 포트에 할당할 수 있다. 퍼포먼스를 초기화한 후에,DirectMusicPerformance.SetPort 를 사용해 포트를 선택한다. 디폴트 포트 를 사용하려면 ,index 파라미터에 -1 를 건네준다.

퍼포먼스를 초기화할 경우에, 이용 가능한 포트가 자동적으로 열거된다. DirectMusicPerformance.GetPortCount ,DirectMusicPerformance.GetPortCaps , 및 DirectMusicPerformance.GetPortName 메소드를 사용해, 특정의 포트나 기능을 검색할 수가 있다. 다음의 코드에서는, 최초의 소프트웨어 신디사이저를 검색해, 퍼포먼스의 포트로서 설정해 있다. 최대로 16 의 채널 그룹이 지원 되고 있다.

' perf 는 DirectMusicPerformance 오브젝트이다.
Dim X As Integer
Dim portcaps As DMUS_PORTCAPS

perf.Init(Nothing, Me.hWnd)
For X = 1 to perf.GetPortCount
    Call perf.GetPortCaps(X, portcaps)
    If portcaps.lFlags And DMUS_PC_SOFTWARESYNTH Then
        perf.SetPort(X, 16)
        Exit For
    End If
Next X
'포트가 설정되지 않았던 경우는, 디폴트 포트를 설정하는지, 다른 조작을 실시한다.

포트의 상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 디폴트 포트
  • 종래의 포트
  • 포트의 프로퍼티 세트


디폴트 포트

Windows 95, 및 Windows 98 Second Edition 이전의 Windows 98 에 대해, 또는 DLS 를 지원 하는 하드웨어를 이용할 수 없는 경우는, Microsoft Software Synthesizer 가 디폴트 포트가 된다. Windows 98 Second Edition 이후, 및 Windows 2000 에서는, 하드웨어 신디사이저가 디폴트 포트가 되는 경우도 있다.

[C++]

어플리케이션으로 디폴트 포트를 사용하는 경우, 퍼포먼스에 포트를 추가하기 전에 IDirectMusic::CreatePort 메소드를 호출할 필요는 없다. 대신에,IDirectMusicPerformance::AddPort 에 NULL 를 건네줄 수가 있다.

IDirectMusic::GetDefaultPort 를 호출해 디폴트 포트를 취득해, 계속되어 IDirectMusicPort::GetCaps 메소드를 사용해 기능을 확인한다. 포트가 어플리케이션의 요구에 적합하지 않는 경우는,IDirectMusic::EnumPort 메소드를 사용해, Microsoft Software Synthesizer 과소의 다른 포트를 검색한다.

[Visual Basic]

DirectMusicPerformance.SetPort 의 index 파라미터로서 -1 를 건네주면(자), 퍼포먼스는 디폴트 포트를 사용한다. 다만, 이 경우, 포트의 기능을 확인할 수 없다. 어플리케이션으로 특정의 기능을 가지는 포트가 필요한 경우는, 퍼포먼스를 초기화할 경우에 DirectMusic 에 의해 생성 된 콜렉션으로 포트를 확인한다. 상세한 것에 대하여는, 「포트의 사용법」을 참조할것.


종래의 포트

Windows 95 및 Windows 98 에서는, DirectMusic 는 종래의 포트를 지원 한다. 종래의 포트란, 출력 데이터가 FM 또는 하드웨어 웨이브 테이블 합성을 사용해 MIDI 디바이스에 순서화 되는 포트이다.

DirectMusic 에서는, 종래의 포트에는 다음과 같은 제한이 있다.

  • Windows 2000 에서는 지원 되지 않는다.
  • 다운로더블 사운드 가 지원 되지 않는다.
  • 마스터 볼륨을 변경할 수 없다 (글로벌 파라미터를 설정하는 것에 의해, 다른 포트로 실행할 수 있다. 「글로벌 파라미터의 설정과 꺼내」를 참조할것).
  • 1 개의 채널 그룹 밖에 이용할 수 없다 ( 「채널」을 참조할것).

Microsoft Software Synthesizer 에 의해, 웨이브 폼 오디오를 연주할 수 있는 모든 출력 디바이스로 일관한 결과를 얻을 수 있으므로, 대부분의 어플리케이션에서는, 종래의 포트에 대해 고려할 필요는 없다.

[C++]

IDirectMusic::EnumPort 또는 IDirectMusicPort::GetCaps 메소드에 의해 돌려주어지는 DMUS_PORTCAPS 구조체의,dwType 멤버의 DMUS_PORT_WINMM_DRIVER 플래그에 의해, 종래의 포트를 인식할 수가 있다.

종래의 포트에서는, 어플리케이션은 DMUS_PORTPARAMS 구조체의 fShare 멤버를 설정해, 종래의 포트의 채널을 논리 포트간에 공유할지 어떨지를 결정하지 않으면 안 되는 점에서도, 그 외의 포트와 다르고 있다. 이 멤버는,DMUS_PORTCAPS 구조체의 dwFlags 멤버의 DMUS_PC_SHAREABLE 플래그를 가지는 포트에만 관계가 있다. 이것은 항상 종래의 포트의 경우이다.

[Visual Basic]

DirectMusicPerformance.GetPortCaps 에 의해 돌려주어지는 DMUS_PORTCAPS 형의,lType 멤버의 DMUS_PORT_WINMM_DRIVER 플래그에 의해, 종래의 포트를 인식할 수가 있다.


포트의 프로퍼티 세트

[Visual Basic]

여기에서는, C++ 로 기술된 어플리케이션에 관련이 있는 내용만을 설명한다. DirectX for Visual Basic 에서는, 포트의 프로퍼티 세트는 지원 되지 않는다.

[C++]

DirectMusic 는, 프로퍼티 세트를 통해, 하드웨어와 드라이버의 새로운 기능에 대한 지원을 제공한다. 프로퍼티 세트는 GUID 에 의해 나타내져 세트내의 각 항목은 0 으로부터 시작되는 인덱스 번호를 할당할 수 있고 있다.

하드웨어 벤더는 새로운 기능을 프로퍼티로서 정의해, GUID 를 포함해 그러한 프로퍼티에 관한 사양을 공시한다. IKsControl::KsProperty 메소드를 사용해, 프로퍼티가 이용 가능한지 어떤지를 확인해, 프로퍼티의 값을 설정 및 꺼낼 수가 있다. IDirectMusicPort::QueryInterface 메소드를 호출해, 인터페이스 식별자로서 IID_IKsControl 를 건네주는 것으로, 포트에 대응한다. IKsControl 인터페이스를 취득한다.

프로퍼티 세트는 GUID 에 의해 나타내져 세트의 각 항목은 0 으로부터 시작되는 인덱스에 의해 나타내진다. GUID 에 대해서 인덱스화 된 항목의 의미가 변경될 것은 없다. DirectMusic 로 지원 되는 프로퍼티 세트의 리스트에 대해서는,KSPROPERTY 를 참조할것.

DirectMusic 로 미리 정의되고 있는 프로퍼티 세트는 모두, 다만 1 개의 항목을 가지고 있어 보통, 인덱스 번호는 0 으로 설정되어 있다. 커널 스트리밍 (KS) 프로퍼티의 완전 정의도 지원 되고 있어 벤더는 임의의 수의 항목과 인스턴스, 및 임의의 사이즈의 데이터를 가지는 프로퍼티 세트를 자유롭게 생성 할 수 있다.

프로퍼티 항목의 요구를 포트에 대해서 송신하는 작업은, 포트의 이행에 의존한다. Win32 핸들 베이스의 멀티미디어 호출 (midiOut 와 midiIn 의 각 함수)을 이용해 DirectMusic 의 에뮬레이션을 실시하고 있는 포트에서는, 어느 프로퍼티도 지원 되지 않는다.

다음의 코드예에서는,IKsControl::KsProperty 메소드를 사용해, 포트가 General MIDI 사운드 세트를 하드웨어로 지원 하고 있을지 어떨지를 조사하고 있다.

BOOL IsGMSupported(IDirectMusicPort *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;
}

다음의 코드예는, 프로퍼티를 변경하는 방법을 나타내고 있다. 이 경우, 소프트웨어 신디사이저의 리바브프로파티는,DMUS_WAVES_REVERB_PARAMS 구조체에 포함되는 프로퍼티로 설정된다.

/* m_* 변수는, 유효한 값으로 초기화되고 있으면(자) 가정한다.
   m_pPort 는 IDirectMusicPort 에의 포인터이다. */

DMUS_WAVES_REVERB_PARAMS Params;

Params.fInGain = m_fReverbIn;
Params.fHighFreqRTRatio = m_fReverbHigh;
Params.fReverbMix = m_fReverbMix;
Params.fReverbTime = m_fReverbTime;

IKsControl *pControl;
if (m_pPort)
{
    // IKsControl 인터페이스의 쿼리.
    HRESULT hr = m_pPort->QueryInterface(IID_IKsControl,
            (void**) &pControl);
    if (SUCCEEDED(hr))
    {
        KSPROPERTY ksp;
        ULONG cb;

        ZeroMemory(&ksp, sizeof(ksp));
        ksp.Set   = GUID_DMUS_PROP_WavesReverb;
        ksp.Id    = 0;
        ksp.Flags = KSPROPERTY_TYPE_SET;

        pControl->KsProperty(&ksp,
                             sizeof(ksp),
                             (LPVOID) &Params,
                             sizeof(Params),
                             &cb);
        pControl->Release();
    }
}

다음의 코드예에서는,m_pPort 로 나타내지는 포트로 리바브에페크트를 유효하게 하고 있다.

DWORD dwEffects = 0;
IKsControl *pControl;
HRESULT hr = m_pPort->QueryInterface(IID_IKsControl,
        (void**) &pControl);
if (SUCCEEDED(hr))
{
  KSPROPERTY ksp;
  ULONG cb;

  ZeroMemory(&ksp, sizeof(ksp));
  dwEffects = DMUS_EFFECT_REVERB;
  ksp.Set   = GUID_DMUS_PROP_Effects;
  ksp.Id    = 0;
  ksp.Flags = KSPROPERTY_TYPE_SET;

  pControl->KsProperty(&ksp,
             sizeof(ksp),
             (LPVOID) &dwEffects,
             sizeof(dwEffects),
             &cb);
  pControl->Release();
}

마지막 예는, 그 외의 이펙트를 현상인 채, 리바브만을 오프로 하는 방법을 나타내고 있다.

DWORD dwEffects = 0;
IKsControl *pControl;
HRESULT hr = m_pPort->QueryInterface(IID_IKsControl,
        (void**) &pControl);
if (SUCCEEDED(hr))
{
  KSPROPERTY ksp;
  ULONG cb;

  ZeroMemory(&ksp, sizeof(ksp));
  ksp.Set   = GUID_DMUS_PROP_Effects;
  ksp.Id    = 0;
  ksp.Flags = KSPROPERTY_TYPE_GET;

  pControl->KsProperty(&ksp,
             sizeof(ksp),
             (LPVOID) &dwEffects,
             sizeof(dwEffects),
             &cb);

  ZeroMemory(&ksp, sizeof(ksp));
  dwEffects = dwEffects & ~DMUS_EFFECT_REVERB;
  ksp.Set   = GUID_DMUS_PROP_Effects;
  ksp.Id    = 0;
  ksp.Flags = KSPROPERTY_TYPE_SET;

  pControl->KsProperty(&ksp,
             sizeof(ksp),
             (LPVOID) &dwEffects,
             sizeof(dwEffects),
             &cb);

  pControl->Release();
}


DirectMusic 로더

[C++]

DirectMusic 오브젝트를 뮤직 퍼포먼스에 짜넣기 전에, 그것들을 파일 또는 리소스로부터 로드하지 않으면 안 된다. IDirectMusicLoader 인터페이스는, 이러한 오브젝트의 로드를 관리하기 위해서 사용된다. 또, 오브젝트를 검색 및 열거해, 몇번도 로드 되지 않게 캐싱 하기 위해서도 사용된다.

어플리케이션에서는, 기존의 로더의 인스턴스를, 한 번에 1 개(살)만 사용해야 하는 것이다. 1 개의 글로벌 로더 오브젝트를 생성 해, 로드가 모두 종료할 때까지 오브젝트를 릴리즈 하지 않게 한다. 이 방법에 의해, 오브젝트가 효과적으로 검색 및 캐싱 된다.

DirectMusic 에 있어서의 IStream 의 이행에 의해, 데이터가 소스로부터 스트림에 넣어진다. 데이터의 해석은,IPersistStream 의 이행을 통해, 다양한 오브젝트 자신에 의해 처리된다. 표준적인 DirectMusic 데이터만을 처리하는 경우는, 이러한 인터페이스를 직접 사용할 필요는 없다.

다른 오브젝트에 의해 참조되는 오브젝트는, 투과적으로 로드 된다. 예를 들어, DirectMusic Producer 로부터 로드 되는 스타일에, 다른 파일에 데이터가 있는 밴드에의 참조가 포함되어 있다고 한다. 스타일의 IPersistStream 는 참조를 찾아내면(자), 데이터 스트림을 건네준 IStream 로부터 IDirectMusicGetLoader 인터페이스를 취득한다. 이 인터페이스를 사용해, DirectMusicLoader 에의 포인터를 취득한다. 계속되어,IDirectMusicLoader::GetObject 를 호출해, 밴드를 로드한다.

[Visual Basic]

DirectMusic 오브젝트를 뮤직 퍼포먼스에 짜넣기 전에, 그것들을 파일 또는 리소스로부터 로드하지 않으면 안 된다. DirectMusicLoader 클래스는, 이러한 오브젝트의 로드를 관리하기 위해서 사용된다.

어플리케이션에서는, 기존의 DirectMusicLoader 오브젝트를, 한 번에 1 개(살)만 사용해야 하는 것이다. 1 개의 글로벌 로더 오브젝트를 생성 해, 로드가 모두 종료할 때까지 오브젝트를 릴리즈 하지 않게 한다. 이 방법에 의해, 오브젝트가 효과적으로 검색 및 로드 된다.

다만, 어플리케이션이 세그먼트(segment)를 몇번이나 로드하는 경우는, DirectMusic 가 내부에서 사용하고 있는 캐쉬 시스템을 위해서(때문에), 같은 세그먼트(segment) 오브젝트는, 루프의 시작 포인트나 DLS 콜렉션에의 접속등의 설정을, 같은 내용으로 취득하도록(듯이) 주의한다. 이것을 피하려면, 세그먼트(segment)을 재로드하기전에,DirectMusicLoader 오브젝트를 Nothing 로 설정해 릴리즈 해, 새로운 오브젝트를 생성 한다.

다른 오브젝트에 의해 참조되는 오브젝트는, 투과적으로 로드 된다. 예를 들어, DirectMusic Producer 로부터 로드 되는 스타일에, 다른 파일에 데이터가 있는 밴드에의 참조가 포함되어 있다고 한다. DirectMusic 는 자동적으로 밴드를 로드해, 어플리케이션은 DirectMusicStyle.GetBand 메소드를 사용해 이것을 꺼낸다.

로더의 사용 방법의 상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 로더의 검색 디렉토리의 설정
  • 디렉토리에서의 오브젝트 검색
  • 오브젝트의 열거
  • 파일로부터의 오브젝트의 로드
  • 리소스로부터의 오브젝트의 로드
  • 오브제크트데스크리프타의 취득
  • 오브젝트의 캐싱
  • 오브젝트의 설정
  • 커스텀 로드


로더의 검색 디렉토리의 설정

[C++]

검색 대상의 오브젝트를 기술하는 DMUS_OBJECTDESC 구조체의 wszFileName 멤버가 풀 패스를 지정하고 있지 않는 한, 로더는 디폴트로 현재 디렉토리를 검색한다. IDirectMusicLoader::SetSearchDirectory 메소드를 사용하면(자),IDirectMusicLoader::GetObject 과 IDirectMusicLoader::EnumObject 의 각 메소드로 다른 디폴트 패스를 설정할 수 있다. 이 디폴트 패스를 모든 오브젝트에 적용하는 일도, 특정의 클래스의 오브젝트인 만큼 적용할 수도 있다.

다음의 코드예에서는, 스타일 파일의 검색 패스를 설정해 있다.

HRESULT mySetLoaderPath (
    IDirectMusicLoader *pILoader)    // 이전에 생성이 끝난 상태.
{
    return pILoader->SetSearchDirectory(
            CLSID_DirectMusicStyle,
            L"c:\\mymusic\\funky",
            FALSE);
}

이 함수를 호출해 두면(자), 어플리케이션은 다음의 코드 예의 같게, 풀 패스를 지정하지 않고 파일명만을 사용해 스타일을 로드할 수 있다.

HRESULT myLoadStyleFromPath (
    IDirectMusicStyle **ppIStyle,    // 스타일에의 포인터를 꺼낸다.
    IDirectMusicLoader *pILoader)    // 로더는 이미 생성제.
{
    HRESULT hr;
    DMUS_OBJECTDESC Desc;

    ZeroMemory(&Desc, sizeof(DMUS_OBJECTDESC);
    Desc.dwSize = sizeof(DMUS_OBJECTDESC);
    wcscpy(Desc.wszFileName, L"polka.sty");   // 짧은 파일명.
    Desc.guidClass = CLSID_DirectMusicStyle;  // 오브젝트 클래스
    Desc.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_FILENAME;

    hr = pILoader->GetObject(&Desc,
            IID_IDirectMusicStyle, (void **) ppIStyle);
    return hr;
}
[Visual Basic]

디폴트에서는, 로드 메소드에 풀 패스를 건네주지 않는 이상 로더는 현재 디렉토리의 파일 오브젝트를 검색한다. DirectMusicLoader.SetSearchDirectory 메소드를 사용하면(자),DirectMusicLoader.LoadBand ,DirectMusicLoader.LoadCollection ,DirectMusicLoader.LoadSegment , 및 DirectMusicLoader.LoadStyle 메소드에 다른 디폴트 패스를 설정할 수가 있다.


디렉토리에서의 오브젝트 검색

[Visual Basic]

여기에서는, C++ 로 기술된 어플리케이션에 관련이 있는 내용만을 설명한다.

[C++]

IDirectMusicLoader::ScanDirectory 메소드는, 특정의 클래스의 오브젝트를 현재의 검색 디렉토리에서 찾는다. 서브 클래스와"*" 이외의 파일 확장자(extension)를 지정하는 것으로써, 검색 범위를 좁힐 수 있다.

이 메소드는 일치하는 모든 파일로부터 완성되는 리스트를 생성 해,IDirectMusicObject::ParseDescriptor 메소드를 사용해 오브젝트의 GUID 와 이름을 추출한다. 이러한 식별자는 내부 데이타베이스에 보관 유지되므로, 어플리케이션은 그 이후, 파일명은 아니고 GUID 나 이름을 사용해 오브젝트를 로드할 수 있다 ( 「파일로부터의 오브젝트의 로드」를 참조할것).

주 : 오브젝트를 로드하기 전에, 항상 IDirectMusicLoader::ScanDirectory 를 호출하는 것은 좋은 생각이다. 파일명을 명시적으로 지정해 오브젝트를 로드하는 경우에서도, 이러한 오브젝트에는 파일명으로 지정되어 있지 않은 것 외의 오브젝트에의 참조가 포함되어 있는 경우가 있다. 오브젝트가 저장 되고 있는 각 디렉토리에 대해서 ScanDirectory 가 불려 가지 않은 경우, 로더는 이러한 참조되고 있는 오브젝트를 찾아낼 수가 없다.

ScanDirectory 메소드의 pwszScanFileName 파라미터에, 캐릭터 라인에의 포인터를 포함하면(자), 그 이름을 가지는 파일에 검색 결과가 캐싱 되어 그 이후의 검색이 고속화된다. 캐쉬 파일을 이용할 수 있는 경우, 이 메소드는 타임 스탬프나 사이즈가 변경되고 있는 파일에 한해서 오브젝트 정보를 갱신한다.

주 : 현재의 버젼의 DirectMusic 에서는,ScanDirectory 는 캐쉬 파일을 사용하지 않는다. 캐쉬 파일의 이행은, 현재에도 가능하다. 이것에 의해, 향후의 버젼으로 퍼포먼스가 향상한다.

예에 대해서는, 「오브젝트의 열거」를 참조할것.


오브젝트의 열거

[Visual Basic]

여기에서는, C++ 로 기술된 어플리케이션에 관련이 있는 내용만을 설명한다.

[C++]

IDirectMusicLoader::EnumObject 메소드를 사용해,IDirectMusicLoader::ScanDirectory 또는 IDirectMusicLoader::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 를 돌려주기 때문에 있다.


파일로부터의 오브젝트의 로드

[C++]

오브젝트를 로드하려면 , 다음의 코드예에 나타내도록(듯이), 최초로 IDirectMusicLoader 인터페이스를 취득한다.

IDirectMusicLoader* m_pLoader;

CoInitialize(NULL);
HRESULT hr = CoCreateInstance(
    CLSID_DMLoader,
    NULL,
    CLSCTX_INPROC,
    IID_IDirectMusicLoader,
    (void**) &m_pLoader);

다음에 오브젝트를 기술해,IDirectMusicLoader::GetObject 메소드를 호출해 그 오브젝트를 로드해, 희망의 인터페이스를 취득한다.

다음의 코드예에서는, 디스크로부터 스타일을 로드해, 그 스타일에의 포인터를, 파라미터에 의해 지정된 변수에 돌려주고 있다.

void myLoadStyle(
    IDirectMusicStyle **ppIStyle)
{
    IDirectMusicLoader *pILoader;        // 로더 인터페이스.

/* 보통은 로더를 1 회 생성 해, 어플리케이션을 실행하고 있는 동안,
그 로더를 사용한다. 이것에 의해, 오버헤드가 감소해,
오브젝트를 캐싱 하는 로더의 기능을 이용할 수 있다. 다만,
이 예에서는, 로더를 동적으로 생성 해, 스타일을 로드한 다음에
파기하고 있다. */

    CoCreateInstance(
            CLSID_DirectMusicLoader, NULL,
            CLSCTX_INPROC,
            IID_IDirectMusicLoader,
            (void **) &pILoader);

    if (pILoader)
    {
        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;

        pILoader->GetObject(&Desc, IID_IDirectMusicStyle,
                (void **) ppIStyle);
        pILoader->Release();
    }
}

이 코드예에서는, 파일을 풀 패스명으로 지정해, 이것을 DMUS_OBJ_FULLPATH 플래그를 설정해 지시하고 있다. 이미 검색 디렉토리를 설정해 두는 경우는, 풀 패스 정보없이 파일의 짧은 이름을 사용할 수 있다. 예에 대해서는, 「로더의 검색 디렉토리의 설정」을 참조할것.

검색 대상의 특정의 파일 오브젝트를 식별하려면 ,DMUS_OBJECTDESC 구조체의 wszName,guidObject,wszFileName 의 각 멤버의 어느 쪽인가에 값을 입력해,dwValidData 멤버에 적절한 1 개(살) 또는 복수의 플래그를 세트 한다. wszFileName 는 아니고 wszName 나 guidObject 를 사용해 파일을 식별하는 경우는,IDirectMusicLoader::ScanDirectory 메소드를 호출해, 현재 디렉토리내의 GUID 와 이름을 이용 가능하게 해야 한다. 상세한 것에 대하여는, 「디렉토리에서의 오브젝트 검색」을 참조할것.

[Visual Basic]

오브젝트를 로드하려면 , 우선 DirectMusicLoader 오브젝트를 생성 한다. 계속되어, 다음의 몇개의 메소드를 호출한다.

  • DirectMusicLoader.LoadBand
  • DirectMusicLoader.LoadCollection
  • DirectMusicLoader.LoadSegment
  • DirectMusicLoader.LoadStyle

목적의 오브젝트가 포함되어 있는 파일의, 파일명 또는 풀 패스의 어느쪽이든을 건네준다. 이러한 메소드는, 적절한 클래스의 인스턴스를 돌려준다.

다음의 코드예에서는, 현재의 검색 디렉토리에 있는 파일로부터 세그먼트(segment)를 로드하고 있다. objDX 는 DirectX7 오브젝트를 나타낸다.

Dim objDMLoader As DirectMusicLoader
Dim objSeg As DirectMusicSegment

Set objDMLoader = objDX.DirectMusicLoaderCreate
Set objSeg = objDMLoader.LoadSegment("Myseg.sgt")

「리소스로부터의 오브젝트의 로드」도 참조할것.


리소스로부터의 오브젝트의 로드

[C++]

리소스로부터, 또는 메모리의 다른 장소로부터 오브젝트를 로드하는 조작은, 파일로부터 오브젝트를 로드하는 경우와 거의 같다 ( 「파일로부터의 오브젝트의 로드」를 참조할것). 다만, 이 경우,DMUS_OBJECTDESC 구조체의 wszName,guidObject, 및 wszFileName 멤버는 사용하지 않는다. 이러한 멤버 대신에, 오브젝트가 점유 하고 있는 메모리 블록에의 포인터와 그 사이즈를 취득해, 이러한 정보를 각각,DMUS_OBJECTDESC 구조체의 pbMemData 및 llMemLength 멤버에 저장 한다. dwFlags 멤버의 DMUS_OBJ_MEMORY 플래그도 설정해야 한다.

데이터를 간단하게 캐싱 할 수 있도록(듯이), 로더는 메모리에의 포인터를 내부에서 보관 유지하기 위해(때문에), 한 번 IDirectMusicLoader::GetObject 가 불려 가면(자), 메모리를 릴리즈 할 수 없다. 이것을 소거하려면 ,IDirectMusicLoader::SetObject 를 같은 DMUS_OBJECTDESC 데스크리프타를 사용해 호출한다. 다만,pbMemData 에는 NULL 를 설정한다. 리소스 메모리는 릴리즈 되지 않기 때문에, 리소스로부터 로드하는 경우는 관계없다.

다음의 예에서는, MIDI 파일을 리소스로부터 세그먼트(segment)에 로드하고 있다.

HRESULT LoadMidi(HMODULE hMod, WORD ResourceID)
{
    HRESULT              hr;
    DMUS_OBJECTDESC      ObjDesc;
    IDirectMusicSegment* pSegment = NULL;

    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_pDXPerformance->m_pLoader->GetObject(
            &ObjDesc, IID_IDirectMusicSegment2,
            (void**) &m_pSegment );

    return hr;
}

다른 오브젝트에 의해 참조되고 있는 오브젝트는, 최초로 로드하지 않으면 안 된다. 예를 들어, 스타일에의 참조를 포함한 세그먼트(segment)를 로드하는 경우, 세그먼트(segment)를 올바르게 연주하려면 , 스타일이 먼저 로드되어 있지 않으면 안 된다. 세그먼트(segment)를 스타일을 찾아낼 수 있도록(듯이), 스타일로 DirectMusicLoader::SetObject 를 호출할 수도 있다.

[Visual Basic]

리소스로부터, 또는 메모리의 다른 장소로부터 오브젝트를 로드하는 조작은, 파일로부터 오브젝트를 로드하는 경우와 거의 같다 ( 「파일로부터의 오브젝트의 로드」를 참조할것). DirectMusicLoader.LoadBandFromResource ,DirectMusicLoader.LoadChordMapFromResource ,DirectMusicLoader.LoadCollectionFromResource ,DirectMusicLoader.LoadSegmentFromResource , 및 DirectMusicLoader.LoadStyleFromResource  메소드는 각각, 모듈명과 리소스 식별자를 파라미터로서 받아, 적절한 클래스의 인스턴스를 돌려준다.

로더에서는, 다음의 종류의 리소스가 인식된다.

"DMBAND" | LoadBandFromResource
"DMCHORD" | LoadChordmapFromResource
"DMCOLL" | LoadCollectionFromResource
"DMSEG" | LoadSegmentFromResource
"DMSTYLE" | LoadStyleFromResource

다른 오브젝트에 의해 참조되고 있는 오브젝트는, 최초로 로드하지 않으면 안 된다. 예를 들어, 스타일에의 참조를 포함한 세그먼트(segment)를 로드하는 경우, 세그먼트(segment)를 올바르게 연주하려면 , 스타일이 먼저 로드되어 있지 않으면 안 된다.

다음의 코드예에서는, 실행 가능 파일에 "DMSEG" 리소스로서 저장 되고 있는 MIDI 파일을, 로드 및 연주한다. loader 는 DirectMusicLoader 오브젝트를 나타내,perf 는 DirectMusicPerformance 을 나타낸다.

Dim seg As DirectMusicSegment
Set seg = loader.LoadSegmentFromResource("listen.exe", "CANYON.MID")
Call seg.Download(perf)
Call perf.PlaySegment(SEG, 0, 0)


오브제크트데스크리프타의 취득

[Visual Basic]

여기에서는, C++ 로 기술된 어플리케이션에 관련이 있는 내용만을 설명한다.

[C++]

오브젝트를 로드한 다음에, 그 오브젝트의 IDirectMusicObject 인터페이스를 사용해,DMUS_OBJECTDESC 구조 체내의 정보를 꺼내지 않으면 안 된다. 최초로 그 오브젝트의 IDirectMusicObject 인터페이스를 취득해야 한다.

다음의 코드예에서는,IDirectMusicObject::GetDescriptor 메소드를 사용해 스타일명을 취득하고 있다.

/* pStyle 는, DirectMusicPerformance 인터페이스에의
   유효한 포인터를 나타낸다. */

if (pStyle)
{
    IDirectMusicObject *pIObject;
    DMUS_OBJECTDESC Desc;

    if (SUCCEEDED(pStyle->QueryInterface(IID_IDirectMusicObject,
            (void **) &pIObject)
    {
        if (SUCCEEDED(pIObject->GetDescriptor(&Desc))
        {
            if (Desc.dwValidData & DMUS_OBJ_NAME)
            {
                TRACE("스타일명은, %S 입니다. \n", Desc.wszName);
            }
        }
        pIObject->Release();
    }
}


오브젝트의 캐싱

[Visual Basic]

여기에서는, C++ 로 기술된 어플리케이션에 관련이 있는 내용만을 설명한다.

[C++]

오브젝트를 캐싱 하면,IDirectMusicLoader::GetObject 메소드는 항상 같은 인터페이스 포인터를 돌려주게 된다.

파일 로드 프로세스에서는, 오브젝트에의 링크를 해결하기 위해서 캐싱이 광범위하게 사용된다. 캐쉬내에 오브젝트가 발견되지 않는 경우, 그 오브젝트가 이미 존재하고 있는 경우에서도, 오브젝트를 재로드하지 않으면 안 된다. 예를 들어, 2 개의 세그먼트(segment)가 같은 스타일을 참조하고 있는 경우를 생각한다. 최초의 세그먼트(segment)를 로드할 때, 세그먼트(segment)는 로더를 호출해 스타일을 취득한다. 계속되어 스타일은, 스타일 오브젝트를 생성 해 디스크로부터 로드해, 스타일에의 포인터를 캐쉬에 저장 해, 이것을 세그먼트(segment)에 돌려준다. 캐싱이 유효한 경우, 2 번째의 세그먼트(segment)가 로드 될 때 스타일의 문의를 해 로더가 즉시 이것을 돌려준다. 2 개의 세그먼트(segment)는, 어느쪽이나 같은 스타일을 가리키고 있다. 캐싱이 무효인 경우는, 2 번째의 세그먼트(segment)가 같은 스타일을 요구했을 때에, 같은 스타일이 파일로부터 로드 되어 중복 하게 된다. 이것은 매우 효율이 나쁘다.

하나 더의 예로서IDirectMusicBand 가 General MIDI 의 DLS 콜렉션을 캐쉬에 두도록(듯이) 요구하는 경우를 생각한다. IDirectMusicBand 가 GM 음색을 조작할 때마다, 로더에 GUID_DefaultGMCollection 를 요구해, 로더로부터 콜렉션을 취득한다. CLSID_DirectMusicCollection 의 캐싱이 무효가 되어 있는 경우, MIDI 파일내에서 패치 체인지가 발생할 때마다, GM 콜렉션 전체의 카피가 생성 된다.

디폴트에서는, 모든 오브젝트 클래스에서 캐싱이 유효하게 되어 있다. IDirectMusicLoader::EnableCache 메소드를 사용하면(자), 1 개(살) 또는 모든 오브젝트 클래스의 캐싱을 무효로 할 수 있다. 이 메소드를 사용해, 임의 또는 모든 오브젝트 클래스의 캐싱을 유효하게 할 수도 있다.

향후의 캐싱을 무효로 하지 않고 캐쉬를 소거하려면 ,IDirectMusicLoader::ClearCache 메소드를 사용한다.

1 개의 오브젝트를 캐싱 하려면 , 그 오브젝트를 IDirectMusicLoader::CacheObject 메소드에 건네준다. IDirectMusicLoader::ReleaseObject 메소드를 사용해 캐쉬로부터 오브젝트를 삭제해, 다음에 그 오브젝트에 대해서 GetObject 를 호출했을 때에, 그 오브젝트가 다시 로드 되는 것을 보증할 수 있다.

Release 메소드를 호출해 오브젝트를 파기하기 전에, 캐싱 된 오브젝트, 특히 세그먼트(segment)에 대해서 ReleaseObject 를 호출한다. 호출을 실시하지 않았던 경우, 오브젝트의 카피가 캐쉬내에 남아, 특정 상태를 나타내는 정보가 보관 유지된다. 세그먼트(segment)의 경우는, 향후 생성 하는 인스턴스가 캐쉬로부터 로드 되어 시작 포인트와 루프 포인트가, 전의 인스턴스가 파기되었을 때 상태와 같게 된다.

CacheObject,ReleaseObject, 및 EnableCache 를 적절히 사용하는 것으로, 불필요한 오브젝트를 캐쉬로부터 삭제해, 그 외의 오브젝트를 캐쉬에 남길 수가 있다.


오브젝트의 설정

[Visual Basic]

여기에서는, C++ 로 기술된 어플리케이션에 관련이 있는 내용만을 설명한다.

[C++]

다음에 다른 오브젝트로부터 참조되는 오브젝트를, 참조원의 오브젝트를 로드할 때 로더를 꺼낼 수 있도록(듯이), 실제로는 로드하지 않고 , 그 자리소만을 로더에 지시하는 것이 바람직하다. 오브젝트에 새로운 속성을 주어, 로더가 속성을 사용해 오브젝트를 검색할 수 있도록(듯이) 할 수도 있다.

SetObject 메소드는, 파라미터로서 DMUS_OBJECTDESC 구조체를 받는다. 이 구조체에는, 2 개(살)의 주요한 정보가 포함된다.

  • 데이터에의 포인터. 파일 패스 또는 메모리의 블록에의 포인터가 된다 ( 「파일로부터의 오브젝트의 로드」 및 「리소스로부터의 오브젝트의 로드」를 참조할것).
  • 다음에 참조되었을 때에 사용하는, 오브젝트의 식별자. GUID 또는 이름이 된다. GetObject 의 호출로, 같은 이름 또는 GUID 를 사용해, 저장 된 오브젝트가 검색된다. 오브젝트에 이미 존재하고 있는 GUID 또는 이름을 변경할 수 없다.
  • 다음의 코드예에서는, 리소스내의 이름이 붙지 않은 오브젝트 (MIDI 파일등)에 이름을 할당하고 있다.
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");

이 이후, 오브젝트는 언제라도 이름을 사용해 로드할 수 있다.


커스텀 로드

[Visual Basic]

여기에서는, C++ 로 기술된 어플리케이션에 관련이 있는 내용만을 설명한다. DirectX for Visual Basic 에서는, 표준적인 DirectMusic 오브젝트의 로드만이 지원 된다.

[C++]

특수한 어플리케이션에서는, 파일이나 리소스로부터의 데이터를 캡슐화하는, 독자적인 오브젝트 타입을 생성 할 수 있다. DirectMusic 로더에, 이러한 오브젝트의 로드를 처리시키면(자) 편리하다. 커스텀 오브젝트가 다른 오브젝트로부터 참조되고 있는 경우나, 커스텀 오브젝트에 다른 오브젝트에의 참조가 포함되어 있는 경우에, 특히 편리가 된다.

DirectMusic 로더를 이용하는 로드 메카니즘을 이행 하려면 , 다음의 순서를 실행한다.

  • IDirectMusicLoader::GetObject 로 검색되도록(듯이), 오브젝트 클래스를 등록한다.
  • 오브젝트를 검색 및 캐싱 하기 위해서 필요한 정보를 로더를 취득할 수 있도록(듯이), 오브젝트에 IDirectMusicObject 인터페이스를 이행 한다.
  • 오브젝트에 IPersistStream 인터페이스를 이행 해,IPersistStream::Load 메소드의 기능을 모두 사용할 수 있도록(듯이) 한다. 이것에 의해, DirectMusicLoader 에 의해 건네받은,IStream 인터페이스 위에의 호출을 통해 취득한 데이터를 해석할 수가 있다.
  • Load 의 이행에 대해,IDirectMusicGetLoader 인터페이스의 IStream 의 쿼리를 실시해, 다음에 IDirectMusicGetLoader::GetLoader 를 호출해, 스트림을 생성 한 DirectMusicLoader 에의 포인터를 취득하는 것으로, 다른 오브젝트에의 참조가 처리되고 있는 것을 확인한다. 이 포인터를 취득하면(자),IDirectMusicLoader::GetObject 를 호출해, 새로운 오브젝트를 로드한다.

어플리케이션이, 파일 입력 그 자체를 관리해야 하는 경우도 있다. 예를 들어, 모든 오브젝트가, 특수한 압축 리소스 파일에 저장 되고 있는 경우 등이다. 어플리케이션은,IDirectMusicLoader 인터페이스를 지원 하는 오브젝트를 생성 해,IDirectMusicLoader::GetObject 메소드를 이행 해, 독자적인 로더를 생성 할 수가 있다. 다른 메소드는 모두 옵션이다. 또, 로더의 이 이행은,IStream 및 IDirectMusicGetLoader 인터페이스의 양쪽 모두를 가지는 독자적인 스트림 오브젝트를 생성 해야 한다.


DirectMusic 의 파일 형식

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 는, 파일 해석을 지원 하지 않는다. 파일 해석, 항상 DirectMusicLoader 오브젝트에 의해 투과적으로 처리된다.

[C++]

여기에서는, DirectMusic Producer 등의 어플리케이션으로 생성 되어IDirectMusicLoader::GetObject 가 불려 갔을 때에 DirectMusic 에 의해 읽히는, 뮤직 파일의 형식에 대해 설명한다. 대부분의 어플리케이션에서는, 이러한 파일을 직접 해석할 것은 없다. 이 파일 형식의 정보는, 뮤직 오쏘링 어플리케이션이나 DirectMusic 플러그 인의 개발자가, 데이터를 호환성이 있는 형식에서 보존하거나 독자적인 오브젝트에 데이터를 로드할 수 있도록(듯이) 하기 위해서 제공되고 있다.

DirectMusic 데이터는, RIFF (Resource Interchange File Format)로 보존된다. 다음의 주제에서는, RIFF 파일에 관한 정보와 DirectMusic 가 데이터를 저장 하는 방법에 대해 설명하고 있다.

  • RIFF 에 대해
  • RIFF 의 표기법
  • DirectMusic 파일의 체크

DirectMusic 파일로 사용되는 데이터 구조에 대해서는, 「파일의 구조체」를 참조할것.


RIFF 에 대해

RIFF 파일의 기본적인 구성 단위는 체크이다. 체크는, 데이터의 논리적인 단위이다. 각 체크에는, 다음의 필드가 포함되어 있다.

  • 체크 식별자를 나타내는, 4 문자의 코드 (FOURCC). 관습적으로, 체크타이프의 등록에는 대문자를 사용해, 그 이외에서는 소문자를 사용한다.
  • 체크의 데이터 멤버의 사이즈를 지정하는 DWORD 값.
  • 데이터.

다른 체크에 포함되어 있는 체크는, 사브체크이다. 사브체크를 포함할 수가 있는 체크는, 체크 식별자가 RIFF 또는 LIST 의 체크 뿐이다.

파일의 최초의 체크는, RIFF 로서 식별되지 않으면 안 된다. 파일내의 그 외의 체크는 모두, RIFF 체크의 사브체크가 된다.

RIFF 체크에서는, 데이터 필드의 최초의 4 바이트에 추가 필드가 포함된다. 추가 필드에서는, 체크의 형식 타입이 제공된다. 형식 타입은, 파일에 저장 되는 데이터의 형식을 식별하는, 4 문자의 코드이다. 예를 들어, DirectMusic 의 스타일의 형식 타입은 DMST 이다.

LIST 체크도, 데이터 필드의 최초의 4 바이트에 추가 필드를 포함하고 있다. 이 추가 필드에는, 필드의 리스트 타입이 포함된다. 리스트 타입은, 리스트의 내용을 식별하는 4 문자의 코드이다. 예를 들어, DirectMusic 의 스타일은, 퍼포먼스의 특정의 파트 (음색 트랙)에 관한 데이터를 포함한, 리스트 타입이 "part" 의 LIST 체크를 가지고 있다.

LIST 체크는, 사브체크를 그룹화 한 것이다. 이러한 사브체크의 몇개인가는 반복해 나타나는 경우가 있지만, LIST 는 배열은 아니다. 사용되고 있는 용어를 위해서(때문에), 혼란이 생길 가능성이 있다. 예를 들어, <part-list> 라고 하는 라벨이 붙은 체크는, 파트의 리스트이다고 예상할지도 모르지만, 실제로는,"파트" 체크의 요소의 리스트이며, 1 개의 파트를 나타내고 있다.

주 : DirectMusic 파일로 사용 떠날 수 있어 모든 4 문자 코드에는, 대응하는 매크로가 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 구조체로 구성되어 있는 것을 나타낸다. 물론, RIFF 체크와 같게, 데이터의 사이즈를 나타내는 DWORD 를, 데이터의 전에 두지 않으면 안 된다. 이 데이터 사이즈 요소는 당연 있어야 할 것이라고 생각되기 (위해)때문에, 표기법에는 가리키지 않았다.

다음의 예는, 리스트 요소를 나타내고 있다. FOURCC LIST 와 리스트 식별자의 "camp", 및 <choe-list> 라고 하는 라벨이 붙은 1 개(살) 또는 복수의 요소로 구성되어 있다. <choe-list> 요소는, 다른 장소에 전개된다.

<cmap-list> -> LIST( 'cmap'
<choe-list>... )


DirectMusic 파일의 체크

여기에서는, DirectMusic RIFF 파일로 사용되고 있는, 체크의 형식에 대해 설명한다.

  • 공통의 체크
  • 밴드 형식
  • 코드 맵 형식
  • 세그먼트(segment) 형식
  • 스타일 형식
  • 툴 형식
  • 툴 그래프 형식
  • 트랙 형식


공통의 체크

다음의 체크는, 다양한 리스트체크 및 형식에서 사용된다.

GUID 체크

<guid-ck> -> guid( <GUID> )

이것은, 요소의 GUID 식별자이다.

바젼체크

<vers-ck> -> vers( <DMUS_IO_VERSION > )

이 체크에는, 요소의 버젼 정보가 포함된다.

UNFO 체크

<UNFO-list> -> LIST( 'UNFO'
<unfo-text-ck>...
    )

UNFO 체크는, RIFF INFO 리스트를 닮아 있다. 다만, Unicode 문자를 사용하는 점이 차이가 난다. INFO 및 UNFO 리스트는, NULL 로 종료하는 캐릭터 라인을 포함한, 다양한 체크로 구성된다.

참조 리스트체크

참조 리스트체크에는, 다른 파일의 오브젝트에의 참조에 관한 정보가 포함된다. 예를 들어, 밴드 오브젝트에는, 다른 파일에 있는 DLS 콜렉션에의 참조가 포함되어 있는 경우가 있다.

참조 리스트의 표기법은, 다음과 같이 된다.

<DMRF-list> ->LIST( 'DMRF'
<refh-ck>       // 참조 헤더
[<guid-ck>]     // 오브젝트의 GUID
[<date-ck>]     // 파일의 일자
[<name-ck>]     // 이름
[<file-ck>]     // 파일명
[<catg-ck>]     // 카테고리명
[<vers-ck>]     // 버젼 정보
)

데이터는, 참조되고 있는 오브젝트에 관한 정보를 포함한 헤더로부터 시작된다.

<refh-ck> -> refh( <DMUS_IO_REFERENCE > )

다른 체크는 모두 옵션이다. GUID 및 바젼체크는, 위에서 설명했던 대로이다. 그 외의 표기법은, 다음과 같다.

<date-ck> -> date( <FILETIME> )
<name-ck> -> name( <WCHAR>...)  // NULL 로 종료하는 캐릭터 라인
<file-ck> -> file( <WCHAR>...)  // NULL 로 종료하는 캐릭터 라인
<catg-ck> -> catg( <WCHAR>...)  // NULL 로 종료하는 캐릭터 라인


밴드 형식

다음 표 기법은, 밴드 파일의 최상정도 레벨의 체크 또는 형식을 나타내고 있다. 밴드 형식은, 다른 체크에 포함할 수도 있다.

RIFF( 'DMBD'
[<guid-ck>]     // 밴드의 GUID
[<vers-ck>]     // 옵션의 버젼 정보
[<UNFO-list>]   // 이름, 작자, 저작권 정보, 코멘트
<lbil-list>     // 음색의 리스트
)

최초의 3 개의 체크는 옵션이다. 상세한 것에 대하여는, 「공통의 체크」를 참조할것.

데이터는, 리스트의 어느 쪽인가에 포함된다.

<lbil-list> -> LIST( 'lbil'
<lbin-list>...
    )

각 음색은, 리스트중에 다음의 형식에서 기술된다.

<lbin-list> -> LIST( 'lbin'
<bins-ck>
[<DMRF-list>]
    )

음색 리스트내에서, 다음의 체크에는 음색을 나타내는 헤더가 포함된다.

<bins-ck> -> bins( <DMUS_IO_INSTRUMENT > )

음색 리스트에는, DLS 음색에의 참조인 <DMRF-list> 를 포함할 수도 있다. 「공통의 체크」를 참조할것.


코드 맵 형식

다음 표 기법은, 코드 맵 파일의 최상정도 레벨의 체크, 또는 형식의 구성을 나타내고 있다.

RIFF( 'DMPR'
<perh-ck>       // 코드맙헷다체크
[ <guid-ck> ]   // GUID 체크
[ <vers-ck> ]   // 바젼체크
[ <UNFO-list> ] // UNFO 리스트
<chdt-ck>       // 코드데이타체크
<chpl-list>     // 코드 팔레트
<cmap-list>     // 코드 그래프
<spsq-list>     // 싸인 포스트리스트
)

GUID 체크, 바젼체크, 및 UNFO 리스트를 제외한, 각 항목이 필요하다. 「공통의 체크」를 참조할것.

필요한 체크와 그 사브체크는 다음과 같다.

<perh-ck> -> perh( <DMUS_IO_CHORDMAP > )

이것은, 코드 맵의 기본적인 헤더 정보이다.

<chdt-ck> -> chdt(
<WORD>    // DMUS_IO_CHORDMAP_SUBCHORD 의 사이즈
<DMUS_IO_CHORDMAP_SUBCHORD >...
    )

<chdt-ck> 체크에는, 서브 코드 당의 바이트수를 나타내는 WORD 값과 고유의 서브 코드의 배열이 포함된다. 이 파일외의 파트에서 참조되고 있는 서브 코드 식별자는 모두, 이 배열의 인덱스에 직접 대응한다.

<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>  ->  LIST( 'cmap'
<choe-list>...
    )

"cmap" 리스트에는, 코드 맵의 코드 접속 그래프 전체가 포함된다. 코드 맵의 대부분의 데이터는, 이 체크에 존재한다.

<choe-list> -> LIST( 'choe'
<cheh-ck>      // 코드 엔트리 데이터.
<chrd-list>    // 코드 데이터. 위에의 설명을 참조.
<ncsq-ck>      // 다음의 코드 리스트.
    )

"choe" 리스트에는, 코드 그래프의 1 개의 엔트리의 데이터와 다음에 코드 그래프에 나타나는 모든 코드에의 포인터가 포함된다.

<cheh-ck> -> cheh( <DMUS_IO_CHORDENTRY > )

이것은, 코드 엔트리 헤더이다. 구조체의 식별자는, 코드 접속 그래프의 식별자이며, 서브 코드 식별자는 아니다.

<ncsq-ck> -> ncsq (
<WORD>         // DMUS_IO_NEXTCHORD 의 사이즈
<DMUS_IO_NEXTCHORD >...
    )

"ncsq" 체크에는, 접속 그래프의 코드를 다른 코드에 접속하는 데이터가 포함된다. 접속 그래프의 각 코드는, 16 비트의 식별자로 나타내진다.

<spsq-list> -> LIST( 'spsq'
<spst-list>...
    )

"spsq" 리스트에는, 싸인 포스트각각의 데이터가 포함된다.

<spst-list>  ->  LIST( 'spst'
<spsh-ck>
<chrd-list>  // 코드 데이터. 위에의 설명을 참조.
[ <cade-list> ]
    )

"spst" 리스트에는, 1 개의 싸인 포스트의 데이터가 포함된다. 데이터는, 헤더, 코드 정보, 및 옵션의 카덴트코드로 구성된다.

<cade-list> -> LIST( 'cade'
<chrd-list>...
    )

"cade" 리스트에는, 카덴트코드의 정보가 포함된다. 현재, 이 리스트에서는 2 개까지의 카덴트코드가 지원 되고 있다. 그 외의 추가 코드나 정보는 무시된다.

<spsh-ck> -> spsh(
<DMUS_IO_CHORDMAP_SIGNPOST >
)

마지막으로,"spsh" 체크에는 싸인 포스트데이터가 포함된다.


세그먼트(segment) 형식

다음 표 기법은, 세그먼트(segment) 파일의 최상정도 레벨의 체크의 구성을 나타내고 있다.

RIFF( 'DMSG'
<segh-ck>       // 세그먼트헷다체크
[<guid-ck>]     // 세그먼트(segment)의 GUID
[<vers-ck>]     // 옵션의 버젼 정보
[<UNFO-list>]   // 이름, 작자, 저작권 정보, 코멘트
<trkl-list>     // 트랙의 리스트
[<DMTG-form>]   // 옵션의 툴 그래프
    )

각각의 체크 및 그 사브체크의 자세한 것은, 다음과 같다.

<segh-ck> -> segh( <DMUS_IO_SEGMENT_HEADER > )

이 체크에는, 세그먼트(segment)의 기본적인 헤더 정보가 포함된다. 다음의 3 개의 체크에 대해서는, 「공통의 체크」를 참조할것.

다음의 체크는 트랙 리스트이다. 각 트랙은,트랙 형식에 캡슐화된다.

<trkl-list> -> LIST( 'trkl'
<DMTK-form>...
    )

마지막으로, 세그먼트(segment) 형식에는툴 그래프 형식을 포함할 수가 있다.


스타일 형식

다음 표 기법은, 스타일 파일의 최상정도 레벨의 체크의 구성을 나타내고 있다.

RIFF( 'DMST'
<styh-ck>       // 스타이르헷다체크
<guid-ck>       // 일의의 식별자
[<UNFO-list>]   // 이름, 작자, 저작권 정보, 코멘트
[<vers-ck>]     // 바젼체크
<part-list>...// 패턴으로 사용되는, 스타일중의 파트의 리스트
<pttn-list>...// 스타일중의 패턴의 리스트
<DMBD-form>...// 스타일중의 밴드의 리스트
[<motf-list>]   // 스타일중의 모티프의 리스트
[<prrf-list>]   // 스타일중의 코드 맵 참조의 리스트
)

각각의 체크 및 그 사브체크의 자세한 것은, 다음과 같다.

<styh-ck> -> styh( <DMUS_IO_STYLE > )

이 체크에는, 스타일의 기본적인 헤더 정보가 포함된다. 다음의 3 개의 체크에 대해서는, 「공통의 체크」를 참조할것.

다음의 체크는, 스타일의 각 뮤직 파트의 체크이다.

<part-list> -> LIST('part'
<prth-ck>       // 파트헷다체크
[<UNFO-list>]
[<note-ck>]     // 파트의 음표의 리스트
[<crve-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  >...
    )

파트리스트체크의 다음은, 파탄리스트체크이다.

<pttn-list> -> LIST( 'pttn'
<ptnh-ck>       // 파탄헷다체크
<rhtm-ck>       // 코드 매칭용의 리듬의 리스트
[<UNFO-list>]
[<mtfs-ck>]     // 모티프 설정 체크
<pref-list>...// 파트 참조 ID 의 리스트
    )

패턴 리스트는, 다음의 사브체크로 구성된다 (옵션의 UNFO 리스트에 대해서는, 「공통의 체크」를 참조할것).

<ptnh-ck> -> ptnh(
< DMUS_IO_PATTERN  >
    )

<rhtm-ck> -> rhtm(
< DWORD >...
    )

이 체크는, 각 소절 마다 1 개의 DWORD 배열로 구성되어 리듬 패턴을 나타낸다. 비트의 배치에 대해서는,DMUS_RHYTHM_PARAM 의 dwRhythmPattern 멤버를 참조할것.

<mtfs-ck> -> mtfs(
< DMUS_IO_MOTIFSETTINGS  >
    )

<pref-list> -> LIST( 'pref'
<prfc-ck>   // 파트 참조 체크
    )

계속되어,"pref" 체크는 파트 참조의 배열로 구성된다.

<prfc-ck> -> prfc(
< DMUS_IO_PARTREF  >
    )

스타일 형식의 마지막 체크는, 코드 맵 참조의 리스트이다.

<prrf-list> -> LIST( 'prrf'
<DMRF-list>...
    )

<DMRF-list> 의 상세한 것에 대하여는, 「공통의 체크」를 참조할것.


툴 형식

툴 형식에는, 툴에 관한 정보가 포함된다. 툴은,툴 그래프 형식에 묻는지, 다른 파일에 저장 할 수가 있다.

<DMTL-form> -> RIFF( 'DMTL'
<tolh-ck>
[<guid-ck>]     // 툴 오브젝트 인스턴스의 GUID
[<vers-ck>]     // 버젼 정보
[<UNFO-list>]   // 이름, 작자, 저작권 정보, 코멘트
[<data>]        // 툴 데이터
)

트르헷다체크는 다음과 같다.

<tolh-ck> -> tolh( <DMUS_IO_TOOL_HEADER > )

다음의 3 개의 요소는 옵션이다. 「공통의 체크」를 참조할것.

<data> 요소는,DMUS_IO_TOOL_HEADER 로 식별되는 타입의 체크로 구성된다. 이 체크의 형식은, 툴의 정의에 따라서 달라, 리스트 또는 체크가 된다.


툴 그래프 형식

트르그라후체크는, 최상정도 레벨의 형식, 또는 세그먼트(segment) 형식의 사브체크로서 기술된다.

RIFF( 'DMTG'
[<guid-ck>]     // 툴 그래프의 GUID
[<vers-ck>]     // 옵션의 버젼 정보
[<UNFO-list>]   // 이름, 작자, 저작권 정보, 코멘트
<toll-list>     // 툴의 리스트
)

최초의 3 개의 요소는 옵션이다. 「공통의 체크」를 참조할것.

트르그라후체크의 주요한 부분이며, 유일 필요한 것은, 툴 리스트이다.

<toll-list> -> LIST( 'toll'
<DMTL-form>...
    )

<DMTL-form> 체크의 상세한 것에 대하여는, 「툴 형식」을 참조할것.


트랙 형식

트랙 형식에는, 1 개의 트랙에 관한 정보가 포함된다. 이 형식은,세그먼트(segment) 형식에 묻는지, 독자적인 파일에 저장 할 수가 있다.

<DMTK-form> -> RIFF( 'DMTK'
<trkh-ck>
[<guid-ck>]     // 트랙 오브젝트 인스턴스의 GUID
[<vers-ck>]     // 버젼 정보
[<UNFO-list>]   // 이름, 작자, 저작권 정보, 코멘트
[<data>]        // 트랙 데이터
)

사브체크의 자세한 것은 다음과 같다.

<trkh-ck> -> trkh(
<DMUS_IO_TRACK_HEADER >
    )

이 체크에는, 트랙의 기본적인 헤더 정보가 포함된다.

다음의 3 개의 요소는 옵션이다. 「공통의 체크」를 참조할것.

트랙 형식의 마지막 요소는, 트랙의 데이터이다. 데이터로 사용되는 체크의 종류는,DMUS_IO_TRACK_HEADER 구조체로 식별된다. 표준적인 트락크체크는, 다음과 같이 정의되고 있다.

  • 밴드 트랙 형식
  • 코드 트랙 리스트
  • 코드 맵 트랙 리스트
  • 코만드트락크체크
  • 뮤트트락크체크
  • 순서 트랙 리스트
  • 사인포스트트락크체크
  • 스타일 트랙 리스트
  • 시스템에크스크루시브트락크체크
  • 텐포트락크체크
  • 박자 기호 트락크체크


DLS 의 사용법

여기에서는, DirectMusic 에서의 다운로드 더블 사운드 (DLS)의 사용법에 대해 설명한다. DLS 의 개요는, 「다운로더블 사운드」를 참조할것.

대부분의 어플리케이션은 음색이나 다운로드 더블 사운드를 직접 취급할 필요가 없다. 콜렉션을 열거나 음색 데이터를 다운로드하는 처리는, 밴드 오브젝트에 의해 실행된다. 밴드를 다운로드 하면, 그 밴드에 관련 붙일 수 있어 모든 음색 데이터도 다운로드된다. 상세한 것에 대하여는, 「밴드의 사용법」을 참조할것.

[C++]

독자적인 DLS 관리를 실시하는 특별한 DirectMusic 어플리케이션에서는, 2 개의 스텝을 실시해야 한다. 최초로 음색 콜렉션을 로드해, 다음에 음색 데이터를 포트에 다운로드한다.

다음의 주제로, 이러한 스텝에 대해 채택한다.

  • 콜렉션의 로드
  • 음색의 조작
  • 커스텀 음색에 의한 MIDI 파일의 연주

음색과 콜렉션을 편집하는 어플리케이션에서는, 보다 낮은 레벨에서도 DLS 데이터를 조작할 수 없으면 안 된다. 상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 하위 레벨 DLS
[Visual Basic]

콜렉션의 조작의 상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 콜렉션의 로드
  • 커스텀 음색에 의한 MIDI 파일의 연주


콜렉션의 로드

[C++]

파일로부터 콜렉션을 로드하는 가장 간단한 방법은,IDirectMusicLoader 인터페이스를 사용하는 것이다 (상세한 것에 대하여는, 「파일로부터의 오브젝트의 로드」를 참조할것). IDirectMusicCollection 인터페이스에의 포인터를 취득 하면, 콜렉션내의 모든 음색에 액세스 할 수 있다. 다만, 이 시점에서는, 실제로는 음색은 포트에 다운로드되어 있지 않다. 음색 데이터는, 필요하게 될 때까지 메모리에 로드 되지 않는다.

콜렉션은,IDirectMusicCollection ,IDirectMusicObject ,IPersistStream 의 각 인터페이스를 지원 하는 COM 오브젝트이다. IPersistStream 는, 표준적인 COM 인터페이스이며, 기억의 목적으로 단순한 시리얼 스트림을 사용해, 오브젝트의 보존과 로드를 실시하는 메소드를 제공한다.

IPersistStream::Load 를 호출한 시점에서는,IDirectMusicCollection 는 콜렉션 전체를 로드할 것은 없다. 보통,IPersistStream 를 지원 하는 오브젝트는 영속적인 데이터 모든 것을 스트림에 로드해,Load 메소드의 외부에서 IStream 포인터를 사용하지 않는다. 그러나,IDirectMusicCollection 내에서 이 방법에 의해 IPersistStream::Load 를 지원 하면, 콜렉션내의 다만 1 개의 음색을 사용하는 경우에서도,DLS 콜렉션 전체를 메모리에 로드하지 않으면 안 된다. 대신에,IDirectMusicCollection 는 IStream 포인터를 보존해, 다음에 그 포인터를 사용해, DirectMusic 의 포트에 다운로드해야 할 음색의 데이터를 로드한다. IDirectMusicCollection 는,IPersistStream 인터페이스 경유로 제공되는 데이터 스트림이 DLS 파일 형식이라고 상정하고 있다.

다음의 코드예에서는,IDirectMusicLoader::GetObject 메소드가 자동적으로 실행하는 처리를, 수작업으로 가고 있다. 콜렉션 오브젝트를 생성 해, 스트림을 그 오브젝트에 로드한다.

HRESULT myLoadCollectionFromStream(
        IStream *pIStream,    // 파일로부터 생성 한 스트림
        IDirectMusicCollection **ppICollection )

{
    HRESULT hr;

    hr = CoCreateInstance(CLSID_DirectMusicCollection,
                          NULL,
                          CLSCTX_INPROC,
                          IID_IDirectMusicCollection,
                          (void **) ppICollection);
    if (SUCCEEDED(hr))
    {
        IPersistStream* pIPersistStream;
        hr = *ppICollection->QueryInterface(
                IID_IPersistStream, (void**) &pIPersistStream);
        if (SUCCEEDED(hr))
        {
            hr = pIPersistStream->Load(pIStream);
            pIPersistStream->Release();
        }
    }
    return hr;
}

다음의 코드예에서는, DirectMusicLoader 를 사용해, 파일명을 지정해 콜렉션을 로드하고 있다.

HRESULT myLoadCollectionByName(
        IDirectMusicLoader *pILoader,
        char *pszFileName,
        IDirectMusicCollection **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_IDirectMusicCollection,
            (void **) ppICollection);
    return hr;
}

표준적인 GM/GS 세트를 로드하기 위해서(때문에),DMUS_OBJECTDESC 구조체의 guidObject 멤버에, 로더에의 패스 GUID_DefaultGMCollection 를 설정한다. 로더를 사용해 이 오브젝트에 몇번이나 액세스 하는 경우는, 캐싱이 유효하게 되어 있는 것을 확인해 (디폴트의 설정), GM 콜렉션을 요구할 때마다 카피가 1 개 생성 되는 것을 방지한다.

주 : GM/GS Sound Set 를 변경할 수 없다. 상세한 것에 대하여는, 「법적 정보」의 「저작권에 관한 주의」를 참조할것.

다음의 코드예는, GUID 에 의해 식별되는 콜렉션을 로드하는 방법을 나타내고 있다.

HRESULT myGetGMCollection(
        IDirectMusicLoader *pILoader,
        IDirectMusicCollection **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_IDirectMusicCollection,
            (void **) ppICollection);
    return hr;
}
[Visual Basic]

음색 콜렉션을 로드하려면 ,DirectMusicLoader.LoadCollection 또는 DirectMusicLoader.LoadCollectionFromResource 메소드를 호출한다. 이러한 메소드는,DirectMusicCollection 오브젝트를 돌려준다. 이 오브젝트에는 메소드가 없고,DirectMusicSegment.ConnectToCollection 에의 파라미터로서의 보고 기능한다. 이 메소드를 호출해 콜렉션을 세그먼트(segment)에 관련지은 후,DirectMusicSegment.Download 를 호출해 음색을 다운로드한다.

이러한 순서는, 디폴트 이외의 콜렉션을 사용하는 경우에게만 필요하다. 세그먼트(segment)에 커스텀 콜렉션이 포함되지 않은 경우, 또는 세그먼트(segment)가 MIDI 파일의 경우, 보통은 DirectMusicSegment.Download 를 호출하면나무에, 세그먼트(segment)중에 오쏘링 된 디폴트 콜렉션의 음색, 또는 General MIDI 세트의 음색이 포트에 다운로드된다. 밴드를 다운로드할 경우에, 그 밴드의 음색으로 필요한 모든 DLS 데이터가 다운로드된다. 「밴드의 사용법」을 참조할것.


음색의 조작

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에서는, 어플리케이션이 콜렉션의 각각의 음색을 조작할 수 없다.

[C++]

DirectMusicCollection 를 생성 해 콜렉션 파일로부터 로드한 후,IDirectMusicCollection::EnumInstrument 메소드를 사용해, 이용 가능한 모든 음색의 패치 번호와 이름을 꺼낼 수 있다.

다음의 코드예에서는, 콜렉션내의 모든 음색을 열거해, 그 이름과 패치 번호를 표시하고 있다.

void myListInstruments(
        IDirectMusicCollection *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("패치 %lx 는, %S. \n", dwPatch, wszName);
        }
    }
}

IDirectMusicCollection::GetInstrument 메소드에 특정의 음색의 패치 번호를 건네주는 것으로, 그 음색에의 포인터를 취득할 수 있다.

음색을 취득한 후,IDirectMusicInstrument::SetPatch 메소드를 사용해 패치 번호를 변경할 수 있다.

콜렉션을 로드해, 음색을 꺼내는 작업은, 음색을 이용 가능하게하기 위한 최초의 스텝에 지나지 않는다. 다음에, 이러한 음색을 포트에 다운로드해야 한다.

음색을 포트에 다운로드하려면 ,IDirectMusicInstrument 인터페이스 포인터를 IDirectMusicPort::DownloadInstrument 메소드에 건네준다. 이 메소드는, 포트로 DLS 데이터를 이용 가능하게 한다. 음색을 특정의 퍼포먼스에 관련지을 것은 없다.

IDirectMusicPerformance::DownloadInstrument 메소드를 사용해, 음색을 다운로드할 수도 있다. DLS 데이터의 다운로드에 가세해, 이 메소드는 음색을 특정의 퍼포먼스 채널에 할당한다.

메모리를 절약하기 위해서, 지정된 음표의 범위에서 필요한 웨이브와 아티큘레이션만이 다운로드된다. 예를 들어, 바순을 사용하는 경우, 저음의 C 로부터 중간의 B 까지의 음표 범위에 상당하는 데이터만을 다운로드하도록(듯이) 지정하는 일이 있다. 그 범위내의리젼 의 데이터만을 다운로드해야 한다.

다음의 코드예에서는, 지정된 콜렉션, 패치 번호, 포트, 및 음표 범위에 대해서, 콜렉션으로부터 음색을 꺼내, 그 음색을 다운로드하고 있다. 이 함수는, 1 개의 DMUS_NOTERANGE 구조체로부터 되는 배열을 생성 해, 이 배열을 IDirectMusicPort::DownloadInstrument 메소드에 건네준다. 일반적으로는, 음표의 1 개의 범위만을 지정하지만, 복수의 범위를 지정할 수도 있다. 배열에의 포인터 대신에 NULL 를 건네주면(자), 모든 범위의 데이터가 다운로드된다.

HRESULT myDownload(
    IDirectMusicCollection *pCollection,    // DLS 콜렉션
    IDirectMusicPort *pPort,                // 다운로드처 포트
    IDirectMusicDownloadedInstrument **ppDLInstrument,
    DWORD dwPatch,                          // 요구된 음색
    DWORD dwLowNote,                        // 음표 범위의 하한의 음표
    DWORD dwHighNote)                       // 음표 범위의 상한의 음표

{
    HRESULT hr;
    IDirectMusicInstrument* 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;
}

Download 메소드는,IDirectMusicDownloadedInstrument 인터페이스에의 포인터를 돌려준다. 이 포인터의 목적은, 그 이후에 IDirectMusicPort::UnloadInstrument 메소드를 호출하면나무에 음색을 식별하는 것 뿐이어서, 이 메소드는 특정의 포트로부터 음색 인스턴스를 언로드한다 (DirectMusicCollection 는, 특정의 포트에 바인드 되지 않는다. 다른 음색을 다른 포트에 다운로드하는 일도, 1 개의 음색을 복수의 포트에 다운로드할 수도 있다).

다음의 코드예에서는, 음색을 다운로드한 후, 언로드하고 있다. 이 예는,IDirectMusicDownloadedInstrument 포인터의 사용 방법을 나타내고 있다.

HRESULT myFickleDownload(
        IDirectMusicInstrument* pInstrument,
        IDirectMusicPort *pPort,
        DWORD dwPatch)

{
    HRESULT hr;
    IDirectMusicDownloadedInstrument * pDLInstrument;
    hr = pPort->DownloadInstrument(
            pInstrument, &pDLInstrument,
            NULL, 0);
    if (SUCCEEDED(hr))
    {
        pPort->UnloadInstrument(pDLInstrument);
        pDLInstrument->Release();
    }
    return hr;
}

IDirectMusicBand::Download 메소드는, 밴드내의 모든 음색을 자동적으로 다운로드한다. 개발자가 퍼포먼스에의 포인터를 건네주는 것만으로, 이 메소드는 그 퍼포먼스에 부가된 적절한 포트에 각 음색을 다운로드한다.


커스텀 음색에 의한 MIDI 파일의 연주

MIDI 파일을 연주하는 경우, 디폴트에서는, Gm.dls 파일에 포함되는 Roland GM/GS Sound Set 의 음색이 사용된다. 다만, 다른 콜렉션의 음색을 사용해 MIDI 파일을 연주할 수도 있다.

[C++]

다른 콜렉션의 음색을 사용해 MIDI 파일을 연주하려면 , 최초로, 「콜렉션의 로드」에서 설명한 방법으로 콜렉션을 로드해,IDirectMusicCollection 인터페이스에의 포인터를 취득한다. 계속되어, MIDI 세그먼트(segment)에 대해서 IDirectMusicSegment::SetParam 를 호출해, 세그먼트(segment)와 콜렉션의 접속을 확립한다.

다음의 코드예는, 접속의 생성 방법을 나타내고 있다.

/* pSegment 는 MIDI 파일로부터 생성 되어
pLoadedCollection 는 유효한 IDirectMusicCollection
포인터이다고 한다. */

HRESULT hr = pSegment->SetParam(GUID_ConnectToDLSCollection,
0xFFFFFFFF, 0, 0,
(void*) pLoadedCollection);

다른 콜렉션의 경우와 같게, 자동 다운로드가 유효하지 않은 경우는, MIDI 파일의 연주에 사용하는 음색을, 세그먼트(segment)를 연주하기 전에 다운로드해야 한다 (자동 다운로드의 상세한 것에 대하여는, 「글로벌 파라미터의 설정과 꺼내」 및 「밴드의 다운로드와 언로드」를 참조할것). 음색이 자동적으로 다운로드되지 않는 경우는, 다음의 코드예에 나타내도록(듯이),IDirectMusicSegment::SetParam 를 호출해 음색을 다운로드해야 한다.

/* pSegment 는 IDirectMusicSegment 포인터이며, pPerformance 는
IDirectMusicPerformance 에의 유효한 포인터이다. */

pSegment->SetParam(GUID_Download, 0xFFFFFFFF, 0, 0, (void *) pPerformance);

SetParam 를 사용한 다운로드의 상세한 것에 대하여는, 「트랙 파라미터의 설정과 꺼내」를 참조할것.

[Visual Basic]

다른 콜렉션의 음색을 사용해 MIDI 파일을 연주하려면 , MIDI 파일에 근거해, 콜렉션을 로드해, 세그먼트(segment)에 관련짓는다. 다음에, 다른 세그먼트(segment)의 경우와 같게, 콜렉션을 다운로드한다. 상세한 것에 대하여는, 「콜렉션의 로드」를 참조할것.

주 : MIDI 세그먼트(segment)에 커스텀 콜렉션을 부가할 경우에, GM 콜렉션에의 접속은 파괴되지 않는다. 예를 들어, 패치 번호가 12 의 1 개의 음색을 포함한 콜렉션을 로드해, 이것을 세그먼트(segment)에 접속하는 경우, 12 이외의 패치 번호를 가지는 MIDI 채널에서는, GM 콜렉션의 적절한 음색을 사용해 연주가 계속된다.


하위 레벨 DLS

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에서는, 하위 레벨에서의 DLS 데이터의 조작은 지원되어 있지 않다.

[C++]

DLS 콜렉션을 편집하는 DirectMusic 어플리케이션을 생성 하고 있는 경우는, DirectMusicInstrument 오브젝트에 캡슐화하는 일 없이, 음색 데이터를 신디사이저에 다운로드할 수 없으면 안 된다.

DLS 데이터를 조작하려면 , DLS 의 사양 및 파일 구조에 대한 지식이 필요하다. 이러한 정보의 상세한 것에 대하여는, MIDI Manufactures Association 에 문의하는 것.

미가공의 음색 데이터를 다운로드하려면 , 최초로, 다음의 코드 예의 같게 IDirectMusicPortDownload 인터페이스에의 포인터를 취득할 필요가 있다. 여기에서는,pIPort 가 IDirectMusicPort 인터페이스에의 유효한 포인터인 것을 상정하고 있다.

IDirectMusicPortDownload **ppIDownloadPort;

HRESULT hr = pIPort->QueryInterface(IID_IDirectMusicPortDownload,
        (void **) ppIDownloadPort);

HRESULT 가 S_OK 가 아닌 경우, 그 포트는 DLS 다운로드를 지원 하고 있지 않다.

다음에, 준비 및 다운로드해야 하는 버퍼를 식별한다. 음색을 신디사이저에 송신하려면 , 음색 전체의 정의를 나타내, 모든 리젼과 아티큘레이션을 갖춘 1 개의 음색 버퍼와 일련의 웨이브 버퍼를 생성 한다. 음색이 리젼용으로 참조하는 1 개의 웨이브에 대해, 1 개의 웨이브 버퍼를 생성 한다.

각 버퍼에는, 고유의 식별자를 붙이지 않으면 안 된다. 이러한 식별자를 사용해 버퍼간의 링크, 특히 리젼과 웨이브의 링크를 해결한다. 다운로드할 필요가 있는 버퍼수를 집계해,IDirectMusicPortDownload::GetDLId 를 호출해, 식별자의 범위를 할당한다. 예를 들어, 1 개의 음색을 3 개의 웨이브와 함께 다운로드하는 경우, 전부 4 개의 버퍼를 다운로드해야 한다. 따라서, 4 개의 식별자세트를 요구한다.

버퍼 마다 필요한 사이즈를 계산해, 다음에 IDirectMusicPortDownload::AllocateBuffer 를 호출해 그 사이즈를 할당한다. 이 메소드는, 그 버퍼를 나타내는 IDirectMusicDownload 인터페이스를 돌려준다. 메모리에 액세스 하려면 ,IDirectMusicDownload::GetBuffer 를 호출한다.

주 : GetBuffer 메소드는 2 개 있다.

IDirectMusicPortDownload::GetBuffer 는, 다운로드 식별자가 기존의 버퍼 오브젝트에 대한 IDirectMusicDownload 인터페이스 포인터를 돌려준다.

IDirectMusicDownload::GetBuffer 는, 버퍼의 메모리에의 포인터를 돌려준다.

이번은 데이터를 각 버퍼에 기입한다. 각 버퍼는 DMUS_DOWNLOADINFO 구조체에 의해 지정된 장소에서 시작된다. 이 구조체는, 사이즈와 다운로드의 기능을 정의한다. 이 구조체는, 다음의 방법으로 준비해야 한다.

  • dwDLType 멤버를, 음색의 경우는 DMUS_DOWNLOADINFO_INSTRUMENT 에, 웨이브의 경우는 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_COPYRIGHT
  • DMUS_EXTENSIONCHUNK
  • DMUS_INSTRUMENT
  • DMUS_NOTERANGE
  • DMUS_REGION

DMUS_WAVE 구조체로 나타나는 웨이브 데이터는,DMUS_WAVEDATA 구조체로 구성된다.

버퍼 모든 것이 준비 되어 있는 경우,IDirectMusicPortDownload::Download 를 사용해 그것들을 다운로드한다. 최초로 웨이브 버퍼를 다운로드하는 것. 그 결과 웨이브 버퍼가 적절한 장소에 배치되어 음색을 다운로드할 경우에 참조할 수 있다.

버퍼를 다운로드 하면, 신디사이저는 음색을 연주할 수 있는 상태가 된다. 버퍼를 다운로드한 후, 그 버퍼로 사용되고 있는 메모리에는 액세스 할 수 없게 된다.

그 후, 음색의 연주가 종료하면(자), 버퍼의 언로드와 릴리즈를 실시한다. 최초로 음색 버퍼를 언로드해, 다음에 모든 웨이브 버퍼를 언로드한다. 언로드를 실시하려면 ,IDirectMusicPortDownload::Unload 를 호출해,IDirectMusicDownload 오브젝트를 건네준다. 다음에,IDirectMusicDownload::Release 를 호출해, 각 버퍼를 릴리즈 한다.

이미 다운로드되고 있는 음색을 갱신하는 경우, 다운로드 끝난 버퍼의 덧쓰기는 할 수 없다. 대신에, 웨이브는 아니고 음색을 옮겨놓는다. 음색을 옮겨놓으려면 ,IDirectMusicPortDownload::AllocateBuffer 를 호출해, 적절한 버퍼 사이즈를 지정해 새로운 IDirectMusicDownload 인터페이스를 할당한다. IDirectMusicPortDownload::GetDLId 를 호출해, 버퍼의 새로운 식별자를 생성하는 것. 새로운 아티큘레이션 정보를 버퍼에 쓰기, 다음에 버퍼를 다운로드한다. 계속되어,IDirectMusicPortDownload::Unload 를 호출해, 이전에 다운로드되고 있던 버퍼를 언로드한다.

웨이브 버퍼를 갱신하는 경우는, 이제(벌써) 1 개(살) 스텝이 증가한다. 새로운 웨이브 버퍼와 그 버퍼를 참조하는 갱신된 음색 버퍼의 2 개를 생성 한다. 새로운 웨이브 버퍼, 그 다음에 새로운 음색 버퍼를 다운로드한다. 한층 더 낡은 음색 버퍼, 그 다음에 낡은 웨이브 버퍼를 언로드한다.


음악의 연주

여기에서는, DirectMusic 의 퍼포먼스의 기본적인 요소와 소스로부터 뮤직 데이터를 취득해 출력하기 위해서 필요한 중요한 메소드를 소개한다.

다음의 항목에 대해 설명한다.

  • 퍼포먼스의 생성
  • 세그먼트(segment)
  • 트랙
  • 밴드의 사용법
  • 타이밍
  • 통지와 이벤트의 처리


퍼포먼스의 생성

[C++]

음악의 재생은, 퍼포먼스 오브젝트에 의해 관리된다. 퍼포먼스 오브젝트는, 소스로부터 음악을 꺼내 출력 버퍼에 보낼 때까지의, 대부분의 작업을 처리한다. 퍼포먼스 오브젝트는, 다음의 태스크를 실행한다.

  • 포트의 추가
  • 채널에의 음색의 할당
  • 신디사이저에의 음색의 다운로드
  • 세그먼트(segment)의 연주와 정지
  • 메세지의 디스팟치
  • 툴과 타이밍의 관리

대부분의 어플리케이션은, DirectMusicPerformance 오브젝트를 1 개만 사용하지만, 마스터 템포나 볼륨등의 파라미터가 다른 복수의 퍼포먼스를 사용할 수도 있다.

다음의 코드예에서는, 퍼포먼스를 1 개 생성 해,IDirectMusicPerformance 인터페이스에의 포인터를 취득하고 있다.

IDirectMusicPerformance* pPerf;

if (FAILED(CoCreateInstance(
        CLSID_DirectMusicPerformance,
        NULL,
        CLSCTX_INPROC,
        IID_IDirectMusicPerformance,
        (void**) &pPerf
    )))
{
    pPerf = NULL;
}

생성 한 퍼포먼스는 초기화해야 한다. 초기화에 있어서의 중요한 처리는, DirectMusic 오브젝트의 생성이다. CoCreateInstance 에 CLSID_DirectMusic 를 건네주어, 다음에 IDirectMusicPerformance::Init 에 IDirectMusic 인터페이스 포인터를 건네주면(자), DirectMusic 오브젝트를 생성 할 수가 있다. 다만, 많은 경우는,Init 를 사용해 DirectMusic 오브젝트를 생성 한 (분)편이 보다 간단하다. 포트 및 master clock에 대해서 필요한 제어의 정도로 응해,IDirectMusic 인터페이스에의 포인터를 취득할지 어떨지를 선택할 수도 있다. 디폴트의 신디사이저 및 디폴트의 master clock만을 사용하는 경우는, 보통,IDirectMusic 의 메소드에 액세스 할 필요는 없다. 이 경우는,Init 에 NULL 를 건네준다.

다음의 코드예에서는, 퍼포먼스를 초기화해,IDirectMusic 에의 포인터를 취득해, 어플리케이션 윈도우 핸들로 초기화된 IDirectSound 인터페이스를 생성 하고 있다.

IDirectMusic* pDirectMusic;

if (SUCCEEDED(pPerf->Init(&pDirectMusic,
NULL,     // DirectSound 오브젝트의 생성
hWnd      // 어플리케이션 윈도우 핸들
        )))
{
// 퍼포먼스의 초기화
}
[Visual Basic]

음악의 재생은, 퍼포먼스 오브젝트에 의해 관리된다. 퍼포먼스 오브젝트는, 소스로부터 음악을 꺼내 출력 버퍼에 보낼 때까지의, 대부분의 작업을 처리한다. 퍼포먼스 오브젝트는, 다음의 태스크를 실행한다.

  • 포트의 열거와 액티브 포트의 설정
  • 세그먼트(segment)의 연주와 정지
  • 메세지의 디스팟치
  • 타이밍의 관리

대부분의 어플리케이션은,DirectMusicPerformance 오브젝트를 1 개만 사용하지만, 마스터 템포나 볼륨등의 파라미터가 차이가 나거나 다른 포트로 연주를 실시하는 복수의 퍼포먼스를 사용할 수도 있다.

다음의 코드예에서는, 독자적인 DirectSound 오브젝트와 함께 퍼포먼스를 생성 해, 이것을 초기화해, 1 개의 채널 그룹에서 디폴트 포트를 사용하도록(듯이) 설정해 있다. objDX 는 DirectX7 오브젝트를 나타낸다.

Dim objDMPerformance as DirectMusicPerformance

Set objDMPerformance = objDX.DirectMusicPerformanceCreate
Call objDMPerformance.Init(Nothing, 0)
Call objDMPerformance.SetPort(-1, 1)

퍼포먼스의 설정의 상세한 것에 대하여는, 「DirectMusic 와 DirectSound 의 통합」 및 「포트의 사용법」을 참조할것.


세그먼트(segment)

[C++]

DirectMusic 내의 데이터의 기본 체크를 세그먼트(segment)라고 부른다. 세그먼트(segment)는 IDirectMusicSegment 인터페이스에 의해 나타내진다. 세그먼트(segment)는, 다음의 몇개의 방법으로 생성 할 수가 있다.

  • IDirectMusicSegment 인터페이스를 지원 하는 파일 또는 리소스 오브젝트를 로드한다. 상세한 것에 대하여는, 「DirectMusic 로더」를 참조할것.
  • IDirectMusicStyle::GetMotif 메소드를 사용해, 스타일로부터 모티프를 취득한다.
  • IDirectMusicComposer 인터페이스의 메소드를 사용해, 실행시에 어레인지 또는 이행부를 생성 한다. 「어레인지용의 프로그래밍의 개요」 및 「이행부의 사용법」을 참조할것.
  • IDirectMusicSegment::Clone 메소드를 사용해, 기존의 세그먼트(segment)의 카피를 생성 한다.
  • 기존의 트랙으로부터 세그먼트(segment)를 구축한다. CoCreateInstance 를 호출해 세그먼트(segment) 오브젝트를 생성 해, 다음에 IDirectMusicSegment::InsertTrack 를 호출해 트랙을 추가한다.
  • IDirectMusicBand::CreateSegment 메소드를 사용한다. 이 메소드에 의해, 밴드 체인지의 생성에만 사용되는, 특수한 세컨드리 세그먼트(segment)가 생성 된다. 「프로그램적인 밴드 체인지의 실행」을 참조할것.

각 세그먼트(segment)은 1 개 또는 복수의트랙에 의해 구성되어 각 트랙은 IDirectMusicTrack 인터페이스에 의해 나타내진다. 트랙은, 세그먼트(segment)의 데이터의 대부분을 보관 유지해, 데이터는, 음표 이벤트, 밴드 체인지, 템포 체인지, 또는 그 외의 타임 이벤트로 구성된다. 트랙은 세그먼트(segment) 오브젝트를 통해 관리되기 (위해)때문에, 어플리케이션은 일반적으로 이러한 인터페이스를 필요로 하지 않는다. 상세한 것에 대하여는, 「트랙」을 참조할것.

[Visual Basic]

DirectMusic 내의 데이터의 기본 체크를 세그먼트(segment)라고 부른다. 각 세그먼트(segment)는 DirectMusicSegment 오브젝트에 의해 나타내진다. 세그먼트(segment)는, 다음의 몇개의 방법으로 생성 할 수가 있다.

  • DirectMusicLoader.LoadSegment 또는 DirectMusicLoader.LoadSegmentFromResource 메소드를 사용해,DirectMusicSegment 클래스를 지원 하는 파일 또는 리소스 오브젝트를 로드한다. 상세한 것에 대하여는, 「DirectMusic 로더」를 참조할것.
  • DirectMusicStyle.GetMotif 메소드를 사용해, 스타일로부터 모티프를 취득한다.
  • DirectMusicComposer 클래스의 메소드를 사용해, 실행시에 어레인지 또는 이행부를 생성 한다. 「어레인지용의 프로그래밍의 개요」 및 「이행부의 사용법」을 참조할것.
  • DirectMusicSegment.Clone 메소드를 사용해, 기존의 세그먼트(segment)의 카피를 생성 한다.
  • DirectMusicBand.CreateSegment 메소드를 사용한다. 이 메소드에 의해, 밴드 체인지에게만 사용되는, 특수한 세컨드리 세그먼트(segment)가 생성 된다. 「프로그램적인 밴드 체인지의 실행」을 참조할것.

세그먼트(segment)는 다양한 목적을 완수한다. 다음에, 사용하는 빈도의 높은 세그먼트(segment)를 나타낸다.

  • 프라이머리 세그먼트(segment). MIDI 파일, DirectMusic Producer 로 오쏘링 된 세그먼트(segment), 작곡가 오브젝트에 의해 실행시에 생성 되는 세그먼트(segment)등의, 뮤직 부분.
  • 모티프 세그먼트(segment). 비동기적으로 연주되는 짧은 뮤직 부분. 모티프는 스타일 오브젝트의 일부이지만, 다른 소스로부터 짧은 세컨드리 세그먼트(segment)를 생성 해, 모티프와 같이 프라이머리 세그먼트(segment)에 거듭해 연주할 수도 있다.
  • 밴드 세그먼트(segment). 퍼포먼스내의 다양한 채널용의 일련의 음색 및 음색 세그먼트(segment). 어플리케이션은 밴드 세그먼트(segment)를 연주해, 음악을 연주하는 밴드로 변경을 더할 수가 있다.
  • 템플릿 세그먼트(segment). 코드 진행,그루브 레벨, 및 장식등의 가이드로서 실행시에 스타일이나 코드 맵과 함께 짜 합쳐져 음악을 형성한다. 다른 세그먼트(segment)와는 달라, 어플리케이션이 템플릿 세그먼트(segment)를 직접 연주하는 것은 결코 없다. 대신에, 템플릿 세그먼트(segment)는 작곡가 오브젝트에게 건네져 뮤직 세그먼트(segment)의 생성에 사용된다.
[C++]

세그먼트(segment)의 재생은,IDirectMusicPerformance 인터페이스로 제어되어IDirectMusicPerformance::PlaySegment 의 호출로 시작 된다. 세그먼트(segment)의 연주 인스턴스는 IDirectMusicSegmentState 인터페이스에 의해 나타내져 이 인터페이스를 사용해 세그먼트(segment)의 현재 상태에 관한 정보를 꺼낼 수 있다.

[Visual Basic]

세그먼트(segment)의 재생은,DirectMusicPerformance 오브젝트로 제어되어DirectMusicPerformance.PlaySegment 의 호출로 시작 된다. 재생하는 세그먼트(segment)의 인스턴스는 DirectMusicSegmentState 오브젝트로 나타내져 이 오브젝트를 사용해 세그먼트(segment)의 현재 상태에 관한 정보를 꺼낼 수 있다.

퍼포먼스내에서는, 다만 1 개의 프라이머리 세그먼트(segment)를 연주할 수 있다. 재생의 목적으로 프라이머리 세그먼트(segment)를 삽입하는 경우는, 현재 연주되고 있는 세그먼트(segment)가 끝난 후에 그 세그먼트(segment)를 연주하도록(듯이) 지정하거나 현재의 프라이머리 세그먼트(segment)를 옮겨놓을 수가 있다.

한편, 세컨드리 세그먼트(segment)는 프라이머리 세그먼트(segment)상에서 연주되어 임의의 수의 세컨드리 세그먼트(segment)를 동시에 연주할 수 있다.

보통, 세컨드리 세그먼트(segment)는 프라이머리 세그먼트(segment)의 퍼포먼스를 변경하지 않는다. 예를 들어, 세컨드리 세그먼트(segment)는, 프라이머리 세그먼트(segment)의 스타일에 영향을 주지 않고 , 다른 스타일에 근거할 수가 있다.

[C++]

다만, 세컨드리 세그먼트(segment)는제어 세그먼트(segment)로서 지정할 수가 있다. 이 경우, 보통은 프라이머리 세그먼트(segment)로 처리되는 IDirectMusicPerformance::SetParam 및 IDirectMusicPerformance::GetParam 호출해에 응답하는 태스크가, 세컨드리 세그먼트(segment)에 의해 빼앗긴다. 이와 같이, 제어 세그먼트(segment)에 의해, 현재의 코드 또는그루브 레벨이 관리되는 경우가 있다. 상세한 것에 대하여는, 「트랙」을 참조할것.

세컨드리 세그먼트(segment)를 제어 세그먼트(segment)로서 연주하는 방법의 상세한 것에 대하여는,DMUS_SEGF_FLAGS 를 참조할것.

[Visual Basic]

다만, 세컨드리 세그먼트(segment)는제어 세그먼트(segment)로서 지정할 수가 있다. 이 경우, 세컨드리 세그먼트(segment)는 DirectMusicPerformance.GetCommand 등의 특정의 호출해에 응답하는 태스크를 실행해, 현재의 코드나그루브 레벨 등, 음악의 몇개의 면을 제어한다.

세컨드리 세그먼트(segment)를 제어 세그먼트(segment)로서 연주하는 방법의 상세한 것에 대하여는,CONST_DMUS_SEGF_FLAGS 를 참조할것.

세그먼트(segment)의 재생의 상세한 것에 대하여는, 「세그먼트(segment)의 타이밍」을 참조할것.


트랙

트랙은 세그먼트(segment)의 컴퍼넌트로, 순서화 된 데이터가 포함된다. 데이터에는, 음표, 기조 코드, 템포, 패치 체인지, 밴드 체인지, 및 퍼포먼스가 음악의 부분을 연주할 경우에 알아 둘 필요가 있는, 그 외 모두에 관한 정보가 포함된다.

[Visual Basic]

DirectX for Visual Basic 에서는, 각각의 트랙에 액세스 할 수 있는 어플리케이션은 제공되지 않는다. 재생은 모두, 세그먼트(segment) 레벨로 처리된다.

[C++]

각 트랙은,IDirectMusicTrack 인터페이스에 의해 나타내진다. 이 인터페이스의 메소드는 퍼포먼스에 의해 불려 가 대부분의 어플리케이션에서는, 직접 사용할 필요는 없다.

어플리케이션이 IDirectMusicPerformance::PlaySegment 를 호출하면나무에, DirectMusic 는 세그먼트(segment)의 트랙에 대해서 IDirectMusicTrack::Play 메소드를 호출한다. 대부분의 트랙은, 연주되고 있는 세그먼트(segment)의 파트에 대해서 유효한 데이터를 포함한, 타임 스탬프 메세지를 즉시 생성한다. 이러한 메세지는 큐에 저장 된다 (그 후의 동작에 대해서는, 「메세지의 생성과 전달」을 참조할것).

몇개의 트랙에서는,IDirectMusicTrack::Play 에 대해서 메세지가 생성되지 않지만, 대신에,GetParam 호출의 형식에서 퍼포먼스나 다른 트랙으로부터 보내져 오는 정보의 요구에 응답한다 ( 「트랙 파라미터의 설정과 꺼내」를 참조할것).

다음의 리스트에, DirectMusic 로 이행 되는 표준적인 트랙의 종류와 각각의 간단한 설명을 나타낸다. 표준적인 트랙으로 지원 되는 메소드의 리스트에 대해서는,IDirectMusicTrack 를 참조할것.

  • 밴드. DLS 데이터를 퍼포먼스에 다운로드한다. DMUS_PATCH_PMSG ,DMUS_TRANSPOSE_PMSG ,DMUS_CHANNEL_PRIORITY_PMSG , 및 DMUS_MIDI_PMSG 형의 메세지를 송신한다 (볼륨 및 팬용). MIDI 파일 및 스타일에 근거하는 세그먼트(segment)로 사용된다.
  • 코드. 패턴에 저장 된 뮤직값을, MIDI 값으로 변환하기 위해서(때문에) 사용된다. DMUS_NOTIFICATION_PMSG 형의 메세지를 송신한다 (GUID_NOTIFICATION_CHORD 통지용).
  • 코드 맵. 코드 트랙을 생성 하기 위해서, 템플릿 세그먼트(segment)로 사용된다.
  • 커멘드. 템플릿 세그먼트(segment)로 코드 트랙을 생성 하기 위한(해), 및 스타일 세그먼트(segment)로 연주하는 패턴을 결정하기 위해서(때문에) 사용된다. DMUS_NOTIFICATION_PMSG 형의 메세지를 송신한다 (GUID_NOTIFICATION_COMMAND 의 통지용).
  • 모티프. 다른 세그먼트(segment)와 함께 모티프를 연주하기 위해서 사용한다. DMUS_CURVE_PMSG ,DMUS_NOTE_PMSG , 및 DMUS_NOTIFICATION_PMSG 형의 메세지를 송신한다 (GUID_NOTIFICATION_MEASUREANDBEAT 의 통지용).
  • 뮤트. 스타일 베이스의 세그먼트(segment), 또는 MIDI 베이스의 세그먼트(segment)와 함께 사용한다. P 채널을 다른 P 채널에 재할인 맞히고 하거나 뮤트 할 수가 있다.
  • 순서. DMUS_NOTE_PMSG 및 DMUS_MIDI_PMSG 형의 순서 메세지를 송신한다. MIDI 파일에 근거하는 세그먼트(segment)로 사용된다.. sgt 형식에서 보존된 세그먼트(segment)에 대해,DMUS_CURVE_PMSG 형의 메세지를 송신한다.
  • 싸인 포스트. 코드 트랙을 생성 하기 위해서, 템플릿 세그먼트(segment)로 사용된다.
  • 스타일. 스타일에 근거하는 세그먼트(segment)의 기본적인 트랙. DMUS_TIMESIG_PMSG ,DMUS_CURVE_PMSG, DMUS_NOTE_PMSG, 및 DMUS_NOTIFICATION_PMSG 형의 메세지를 송신한다 (GUID_NOTIFICATION_MEASUREANDBEAT 의 통지용).
  • 시스템에크스크루시브. DMUS_SYSEX_PMSG 형의 시스템에크스크루시브멧세이지를 송신한다. MIDI 파일에 근거하는 세그먼트(segment)로 사용된다.
  • 템포. DMUS_TEMPO_PMSG 형의 메세지를 송신해, 퍼포먼스의 템포를 설정한다.
  • 박자 기호. GUID_NOTIFICATION_MEASUREANDBEAT 통지와 같게,DMUS_TIMESIG_PMSG 형의 메세지를 송신한다. MIDI 파일에 근거하는 세그먼트(segment)로 사용된다.


밴드의 사용법

밴드란, 스타일내의 특정의 파트에 할당할 수 있었던 일련의 음색이다. 연주시에 각 음색 트랙은, 다음의 정보를 보존하고 있는 P 채널에 맵 된다.

  • MIDI 볼륨.
  • MIDI 팬.
  • 전조. 이 값이 0 이 아닌 경우, 채널 위에의 음악의 음표는, 음색에 맞추어 자동적으로 전조 된다.
  • 음색의 MIDI 패치 번호. 뱅크 셀렉트 의 MSB 와 LSB 도 포함된다.
  • 음색의 로드원이 되는 DLS 콜렉션에의 참조. 디폴트의 DLS 콜렉션은, 스탠다드 General MIDI 콜렉션이다.

세그먼트(segment)와 스타일은 항상, 적어도 디폴트 밴드로 불리는 1 개의 밴드에 의해 구성된다. 스타일에는, 추가의 밴드를 포함할 수가 있다. 세그먼트(segment) 또는 스타일을 로드할 때, 디폴트 밴드 및 그 외의 밴드는, 어느쪽이나 자동적으로 로드 된다. 다만, 어떤 밴드를 사용하는 경우에서도, 밴드의 음색용으로 DLS 데이터를 다운로드해야 한다.

[C++]

IDirectMusicStyle::GetDefaultBand 메소드를 사용해, 디폴트 밴드에의 포인터를 취득할 수가 있다.

스타일에 오쏘링 된 그 외의 밴드는,IDirectMusicStyle::EnumBand 및 IDirectMusicStyle::GetBand 메소드를 사용해, 검색 및 취득할 수가 있다. 밴드는, 다른 스타일 파일이나 밴드 파일로부터도 취득할 수 있다. IDirectMusicBand 인터페이스를 취득한 후, 이 밴드에 액세스 해, 디폴트의 밴드를 옮겨놓을 수도 있다.

[Visual Basic]

DirectMusicStyle.GetDefaultBand 메소드를 사용해, 디폴트 밴드를 나타내는 오브젝트를 취득할 수가 있다. 스타일에 오쏘링 된 것 외의 밴드는,DirectMusicStyle.GetBand 메소드를 사용해 취득할 수가 있다. 밴드는, 다른 스타일 파일이나 밴드 파일로부터도 취득할 수 있다. DirectMusicBand 오브젝트를 취득한 후, 이 밴드에 액세스 해, 디폴트의 밴드를 옮겨놓을 수도 있다.

독자적인 파일로부터 밴드를 로드하는 것은, DirectMusic 내외의 오브젝트를 로드하는 것에 비슷하다. 상세한 것에 대하여는, 「DirectMusic 로더」를 참조할것.

밴드의 상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 밴드의 다운로드와 언로드
  • 프로그램적인 밴드 체인지의 실행
  • 확실한 타이밍에서의 밴드 체인지


밴드의 다운로드와 언로드

밴드를 사용하려면 , 우선 참조하는 음색을 퍼포먼스에 다운로드해야 한다. 이 순서에 의해, 음색이 P 채널에 할당할 수 있어 포트에 DLS 데이터가 다운로드된다.

디폴트에서는, 사용하는 밴드의 다운로드는 어플리케이션이 실시한다. 다만, 밴드의 자동 다운로드를 유효하게 할 수도 있다. 자동 다운로드가 유효한 경우, 밴드에 포함되는 세그먼트(segment)가 큐에 저장 될 때, 밴드의 음색이 다운로드된다. 세그먼트(segment)가 정지되면(자), 같은 음색을 사용하고 있는 것 외의 세그먼트(segment)를 즉시 큐에 넣어 연주하는지, 현재 연주중이 아닌 한, 음색은 자동적으로 언로드된다.

주 : 자동 다운로드는, 세그먼트(segment)의 타이밍이 중요하지 않을 때에만 사용해야 하는 것이다. 음색의 로드와 언로드를 반복하면(자) 시간이 걸려, 복잡한 음악 환경에서는, 중대한 퍼포먼스의 저하가 발생하는 경우가 있다.

자동 다운로드 메카니즘의 일부인 자동 언로드에 대해서도, 바라지 않은 결과가 되는 경우가 있으므로, 주의하지 않으면 안 된다. 예를 들어, 채널의 음색을 변경하는 짧은 세컨드리 세그먼트(segment)를 연주하는 경우를 생각한다. 세컨드리 세그먼트(segment)가 시작 될 때, 음색이 자동적으로 다운로드되어 기존의 음색으로 옮겨진다. 세컨드리 세그먼트(segment)가 종료 하면, 음색은 자동적으로 언로드된다. 따라서, 채널의 음색이 없어져, 채널로부터는 소리가 나오지 않게 된다.

밴드의 다운로드에 의해, 퍼포먼스가 밴드를 이용할 수 있게 되지만, 프로그램 체인지는 행해지지 않는다. 프로그램 체인지는, 세그먼트(segment)의 밴드 트랙으로 생성되는 메세지에 응해 실행된다. 이 메세지는, 일반적으로는 세그먼트(segment) 파일에 오쏘링 된다. 실행시에 프로그램 체인지를 실시하는 방법에 대해서는, 「프로그램적인 밴드 체인지의 실행」을 참조할것.

밴드의 다운로드와 언로드를 이행 하는 방법에 대해서는, 다음의 주제를 참조할것.

  • 밴드의 자동 다운로드
  • 수동에 의한 밴드의 다운로드
  • 밴드의 언로드


프로그램적인 밴드 체인지의 실행

보통은, 로드 된 세그먼트(segment)의 밴드 트랙에 의해, 프로그램 체인지가 실행된다. 다만, 수동으로 실시할 수도 있다.

[C++]

우선,IDirectMusicBand::CreateSegment 메소드를 호출해, 세컨드리 세그먼트(segment)를 생성 한다. 다음에,IDirectMusicPerformance::PlaySegment 를 호출해, 생성 한 세그먼트(segment)를 연주한다. 보통은 dwFlags 파라미터내의 DMUS_SEGF_MEASURE 또는 DMUS_SEGF_GRID (DMUS_SEGF_FLAGS 를 참조)를 사용해, 적절한 경계에서 밴드 체인지가 유효하게 되도록(듯이) 보증한다.

다음의 코드예에서는, 밴드로부터 세그먼트(segment)를 생성 해, 그 세그먼트(segment)를 연주하고 있다.

/ * 자동 다운로드가 유효하게 되어 있는지, 어플리케이션이 pBand->Download 를 호출하고 있으면(자) 가정한다. */

HRESULT myPlayBand(
    IDirectMusicBand *pBand,         // 밴드 오브젝트에의 포인터.
    IDirectMusicPerformance *pPerf,  // 밴드를 사용하는 퍼포먼스.
    REFERENCE_TIME rfTime,           // 연주 시작 타임.
    DWORD dwFlags)                   // 퍼포먼스 플래그.

{
    IDirectMusicSegment *pSegment;
    HRESULT hr = pBand->CreateSegment(&pSegment);
    if (SUCCEEDED(hr))
    {
        hr = pPerf->PlaySegment(pSegment,
                dwFlags | DMUS_SEGF_SECONDARY,
                rfTime,
                NULL);
        pSegment->Release();
    }
    return hr;
}
[Visual Basic]

우선,DirectMusicBand.CreateSegment 를 사용해 세그먼트(segment)를 생성 한다. 다음에,DirectMusicPerformance.PlaySegment 를 호출해, 생성 한 세그먼트(segment)를 연주한다. 보통은,IFlags 파라미터내의 DMUS_SEGF_MEASURE 또는 DMUS_SEGF_GRID (CONST_DMUS_SEGF_FLAGS 를 참조)를 사용해, 적절한 경계에서 밴드 체인지가 유효하게 되도록(듯이) 보증한다.

퍼포먼스는, 한 번에 복수의 밴드의 음색을 연주할 수가 있다. 예를 들어, 어플리케이션이 1 개의 밴드를 사용해 프라이머리 세그먼트(segment)를 연주하고 있을 때, 다른 밴드를 가지는 스타일의 모티프를 연주하는 경우를 생각한다. 최초의 밴드의 음색이, 2 번째의 밴드의 음색 이외의 P 채널 에 할당할 수 있는 한, 충돌은 일어나지 않는다. 다만, 보통, 모티프 세그먼트(segment)는 독자적인 밴드 트랙을 가지지 않는다. 따라서, 최초로 밴드 세그먼트(segment)를 생성 하고 나서 연주하지 않으면, 모티프의 P 채널로부터는 소리가 나오지 않는다 (모티프 세그먼트(segment)에 밴드 트랙을 추가할 수도 있지만, 다른 밴드 세그먼트(segment)를 생성 하는 (분)편이 간단하다).


확실한 타이밍에서의 밴드 체인지

밴드 세그먼트(segment)를 연주할 경우에 중요한 문제가 되는 것은, 스타일 트랙으로 연주되는 음표의 타이밍의 격차이다. 예를 들어, 소절 1 의 1 박목의 음표가, 실제의 박의 경계에서(보다) 조금 진행되거나 늦거나 하는 경우가 있다. 밴드 세그먼트(segment)에서는 이 상황을 알지 않기 때문에, 몇개의 음표가 잘못한 음색으로 연주되는 경우가 있다.

[C++]

이 문제를 피하기 위해서(때문에), 어플리케이션은 밴드 세그먼트(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);
[Visual Basic]

이 문제를 피하기 위해서(때문에), 어플리케이션은 밴드 세그먼트(segment)를 빨리 큐에 저장 해야 하는 것이다. 예를 들어, 스타일 세그먼트(segment)의 styleSeg 와 밴드 세그먼트(segment)의 bandSeg 가 있어, 퍼포먼스 (perf)의 다음의 소절 경계에서, 스타일 세그먼트(segment)와 밴드 세그먼트(segment)의 양쪽 모두를 연주하는 경우를 생각한다. 스타일에는, 세그먼트(segment)의 시작 타임보다, 최대 30 틱 (뮤직 타임에) 빨리 시작 될 가능성이 있는 음표가 포함되어 있는 것을 알 수 있고 있다. 다음의 코드예에서는, 밴드 세그먼트(segment)가 스타일 세그먼트(segment)보다 31 틱전에 연주되는 것이 보증되고 있다. 따라서, 모든 음색은, 음표가 연주되기 전에 적절히 설정된다.

'우선, 다음의 소절의 타임을 취득해,
'뮤직 타임으로 변환한다.

Dim ctResolved As Long
Dim mtResolved As Long

ctResolved = perf.GetResolvedTime(ctResolved, DMUS_SEGF_MEASURE)
mtResolved = perf.ClockToMusicTime(ctResolved)

'밴드 세그먼트(segment)를, 소절 경계의 31 틱전에 연주한다.

mtResolved = mtResolved - 31
Call perf.PlaySegment(bandSeg, 0, mtResolved)

'스타일 세그먼트(segment)를 소절 경계에서 연주한다.

Call perf.PlaySegment(styleSeg, DMUS_SEGF_MEASURE, 0 )

주 : 세그먼트(segment)로 연주되는 음표에 격차가 없는 경우 (예를 들어, MIDI 파일에 근거하는 세그먼트(segment)의 경우)는, 동시에 연주되는 밴드 세그먼트(segment)의 타이밍에 대해 주의할 필요는 없다. 디폴트에서는, 모든 밴드 세그먼트(segment)는 1 틱 빨리 시작 된다.


타이밍

여기에서는, DirectMusic 의 다양한 타이밍의 개요에 대해 설명한다. 다음의 항목에 대해 설명한다.

  • master clock
  • 클럭 타임과 뮤직 타임
  • 템포의 변경
  • 준비 시간
  • 지연 시간과 범퍼 시간
  • 세그먼트(segment)의 타이밍


master clock

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에서는, 어플리케이션은 다른 master clock를 선택할 수 없다.

[C++]

정확한 타이밍과 받아들여지는 짧은 지연 시간을 보증하기 위해서, DirectMusic 는 master clock를 커널 모드에 이행 하고 있다. 이 클럭은, 하드웨어 타이머에 근거하고 있다. DirectMusic 에서는, 시스템 클록이 자동적으로 master clock로서 선택되지만, 어플리케이션에서는 사운드 카드의 웨이브 출력 크리스탈등의 다른 클럭을 선택할 수가 있다.

master clock는 고분해가능의 타이머이며, DirectMusic 를 사용하는 프로세스, 디바이스, 및 어플리케이션은 이 클럭을 공유한다. 이 클럭은, 시스템내의 모든 음악 재생을 동기화하기 위해서(때문에) 사용된다. 이것은, 표준적인IReferenceClock 인터페이스이다. IReferenceClock::GetTime 메소드는, 현재의 타임을 100 나노초단위의 64 비트 정수로서 돌려준다 (REFERENCE_TIME 형으로서 정의되고 있다).

master clock에의 인터페이스를 취득하려면 ,IDirectMusic::GetMasterClock 메소드를 사용한다.

어플리케이션으로 다른 master clock도 선택할 수 있다. 다만, master clock를 선택할 수 있는 것은, 그 밖에 동작중의 DirectMusic 어플리케이션이 없을 때 뿐이다. 최초로 IDirectMusic::EnumMasterClock 메소드를 사용해, master clock의 기능을 완수할 수 있는 모든 디바이스의 기술을 취득한다. master clock로서 사용하고 싶은 디바이스의 GUID 를 취득한 다음에, 그 GUID 를 IDirectMusic::SetMasterClock 메소드에 건네준다.


클럭 타임과 뮤직 타임

[C++]

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 에 정의되고 있다).

퍼포먼스가 초기화될 때, 내장 시계의 유지가 시작 된다. IDirectMusicPerformance::GetTime 메소드를 사용해, 현재의 퍼포먼스 타임을 기준 타임과 뮤직 타임의 양쪽 모두로 취득할 수가 있다.

IDirectMusicPerformance::AdjustTime 메소드를 사용하면(자), 퍼포먼스 타임을 조금 변경할 수가 있다. 대부분의 어플리케이션에서는, 이 조작을 실행할 필요는 없다. 다만, 다른 소스에 동기 시키는 경우에는, 이 처리가 도움이 된다.

퍼포먼스내에서 이것들 2 종류의 타임을 변환하려면 ,IDirectMusicPerformance::MusicToReferenceTime 과 IDirectMusicPerformance::ReferenceToMusicTime 의 각 메소드를 사용한다.

IDirectMusicPerformance::PlaySegment 를 호출해, 연주하고 싶은 세그먼트(segment)를 삽입할 때에, 기준 타임을 사용해 시작 타임을 지정한다. 그 시점에서 프라이머리 세그먼트(segment)가 연주되어 있지 않은 경우, 이 타임은 현재의 템포에 따라 즉시 뮤직 타임에 변환된다. 다른 프라이머리 세그먼트(segment)가 연주되고 있는 경우는, 삽입된 세그먼트(segment)의 시작 타임에 이른 시점에서, 그 시작 타임이 뮤직 타임에 변환된다.

세그먼트(segment)의 연주가 시작 되기 전으로 템포가 변경되었을 경우는, 시작 타임이 영향을 받거나 세그먼트(segment)가 희망한 경계에서 시작 되지 않는 경우가 있다. 전자의 상황에서는, 즉시 뮤직 타임에의 변환을 한다. 템포의 속도가 상승했을 경우는 (기준 타임에서의) 시작 타임은 앞당겨져, 템포의 속도가 저하했을 경우는 늦는다. 후자의 상황에서는, 시작 타임에 변환을 하므로, 템포의 변경이 발생 하면, 정확한 분해가능의 경계에서 세그먼트(segment)가 시작되지 않는 것을 의미한다. 예를 들어, 세그먼트(segment)가 있는 소절 경계 (PlaySegment 의 dwFlags 파라미터로 지시)에서 시작 되는 경우, 기준 타임에서의 시작 타임은, 세그먼트(segment)가 큐에 저장 될 때 계산된다. 그 후로 템포가 변경되면(자), 소절 경계가 계산한 타임대로 안 될 가능성이 있다.

프라이머리 세그먼트(segment)가 DMUS_SEGF_QUEUE 플래그와 함께 PlaySegment 에게 건네질 때 (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 가 중단된다.

[Visual Basic]

DirectX for Visual Basic 에서는, master clock에 의해 돌려주어지는 타임은 Long 이며, 대략 1 밀리 세컨드의 단위로 나타내진다. DirectMusicPerformance.GetClockTime 에 의해 돌려주어지는 값은, 임의의 시작 타임 이후에 경과한 시간이다.

뮤직 타임도 Long 이며, 시간의 절대적인 측정값은 아니고, 템포에 근거하는 상대값이다. 클럭은, 퍼포먼스가 초기화될 때 시작 되어 4 분 음표 당 768 의 시간이 경과한다. 현재의 타임은,DirectMusicPerformance.GetMusicTime 를 사용해 취득할 수가 있다.

퍼포먼스로 2 종류의 타임을 변환하려면 ,DirectMusicPerformance.MusicToClockTime 및 DirectMusicPerformance.ClockToMusicTime 메소드를 사용한다.

DirectMusicPerformance.PlaySegment 의 호출에 의해 세그먼트(segment)가 큐에 저장 되어 시작 타임이 클럭 타임에 주어지는 경우, DirectMusic 는 시작 타임을 뮤직 타임으로 변환하지 않으면 안 된다. 그 시점에서 프라이머리 세그먼트(segment)가 연주되어 있지 않은 경우, 이 타임은 현재의 템포에 따라 즉시 뮤직 타임에 변환된다. 다른 프라이머리 세그먼트(segment)가 연주되고 있는 경우는, 삽입된 세그먼트(segment)의 시작 타임에 이른 시점에서, 그 시작 타임은 뮤직 타임에 변환된다.

세그먼트(segment)의 연주가 시작 되기 전으로 템포가 변경되었을 경우는, 시작 타임이 영향을 받을 가능성이 있어, 세그먼트(segment)가 희망한 경계에서 시작 되지 않는 경우가 있다. 전자의 상황에서는, 즉시 뮤직 타임에의 변환을 한다. 템포의 속도가 상승했을 경우는 (기준 타임에서의) 시작 타임은 앞당겨져, 템포의 속도가 저하했을 경우는 늦는다. 후자의 상황에서는, 시작 타임에 변환을 하므로, 템포의 변경이 발생 하면, 정확한 분해가능의 경계에서 세그먼트(segment)가 시작되지 않는 것을 의미한다. 예를 들어, 세그먼트(segment)가 있는 소절 경계 (PlaySegment 의 lFlags 파라미터로 지시)에서 시작되는 경우, 세그먼트(segment)가 삽입된 시점에서 실제의 시작 타임 (클럭 타임에 표현)이 계산되지만, 그 후 템포가 변경되면(자), 소절 경계는 당초 예정되어 있던 시점과 일치하지 않을 가능성이 있다.

프라이머리 세그먼트(segment)가 DMUS_SEGF_QUEUE 플래그와 함께 PlaySegment 에게 건네질 때 (CONST_DMUS_SEGF_FLAGS 를 참조),startTime 파라미터는 무시되어 세그먼트(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)의 템포 트랙이 템포를 제어하지만, 어플리케이션으로 동적으로 템포를 설정할 수도 있다.

[C++]

템포를 설정하는 방법에는, 메세지를 송신하는 방법과 트랙 파라미터를 설정하는 방법의 2 개가 있다.

다음의 코드예에서는, 메세지를 송신해 템포를 변경하고 있다.

/* pIDMSegment 는 유효한 IDirectMusicSegment 이며,
IDMPerformance 는 유효한 IDirectMusicPerformance 이다고 한다. */

// 세그먼트(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);
[Visual Basic]

템포를 설정하는 방법에는, 마스터 템포를 설정하는 방법과 템포 메세지를 송신하는 방법의 2 개가 있다.

마스터 템포는, 퍼포먼스의 모든 템포에 곱셈하는 계수이다. 예를 들어, 0.75 의 파라미터로 DirectMusicPerformance.SetMasterTempo 를 호출해 마스터 템포를 설정해, 1 분간에 120 박의 템포를 가지는 세그먼트(segment)를 연주하는 경우, 세그먼트(segment)는 90 의 템포로 연주된다.

DirectMusicPerformance.SendTempoPMSG 메소드를 사용해 템포를 송신 하면, 메세지의 스탬프로 지정된 타임으로 템포가 변경된다. 새로운 템포는, 어플리케이션으로부터 직접, 또는 연주되고 있는 세그먼트(segment)에 의해, 다른 템포 메세지가 송신될 때까지 유효하다. 템포의 값은, 마스터 템포에 의해 변경할 수가 있다.

다음의 호출에서는, 즉시 1 분간에 100 박의 템포로 설정된다. perf 는 DirectMusicPerformance 오브젝트를 나타낸다. lTime 파라미터에 0 을 건네주어, 메세지를 즉시 송신하도록(듯이) 지정하는 경우는, DMUS_PMSGF_REFTIME 플래그도 설정해야 한다.

Call perf.SendTempoPMSG(0, DMUS_PMSGF_REFTIME, 100)


준비 시간

세그먼트(segment)를 연주할 경우에, 퍼포먼스는 세그먼트(segment)의 트랙을 반복해 호출한다. 이 호출에 의해, 1 초의 몇분의 몇개의 지정된 시간 범위 분의 메세지가 생성된다. 이러한 메세지는, 지금까지의 호출로 생성된 메세지의 뒤로 삽입된다. 디폴트에서는, 대략 1 초 분의 메세지가, 언제라도 큐에 있다.

「지연 시간과 범퍼 시간」의 그림을 참조할것.

[C++]

큐는,IDirectMusicTrack::Play 의 호출에 의해, 끊임없이 가득하게 되고 있는 가스 탱크와 같은 것이다. 퍼포먼스가 Play 를 호출할 때 마다, 현재의 타임에 준비 시간을 덧셈 해, 호출의 타임이 계산된다. 현재의 타임이 10,000 밀리 세컨드 (또는, 등가인 REFERENCE_TIME 단위)로, 준비 시간이 디폴트로 1000 밀리 세컨드인 경우, 종료 타임은 11,000 이 된다. 즉, 11,000 까지의 연주 분의 새로운 메세지를 모두 준비해, 큐에 저장 해야 한다.

큐의 사이즈는,IDirectMusicPerformance::SetPrepareTime 메소드를 호출해 변경할 수가 있다. 또, 현재의 사이즈는,IDirectMusicPerformance::GetPrepareTime 를 사용해 취득할 수가 있다.

대부분의 어플리케이션에서는, 디폴트의 준비 시간을 변경할 필요는 없다. 여기서 설명한 처리는, 어플리케이션으로부터는 인식되어 있지 않다. 다만, 어플리케이션은 IDirectMusicPerformance::PlaySegment 에 DMUS_SEGF_AFTERPREPARETIME 플래그를 건네줄 수가 있으므로, 준비 시간의 개념을 이해해 두면(자) 유효하다.

[Visual Basic]

큐는, 끊임없이 가득하게 되고 있는 가스 탱크와 같은 것이다. 퍼포먼스가 메세지를 송신하도록(듯이) 세그먼트(segment)에 요구할 때 마다, 현재의 타임에 준비 시간을 덧셈 해, 호출의 종료 타임이 계산된다. 현재의 타임이 10,000 밀리 세컨드로, 준비 시간이 디폴트로 1000 밀리 세컨드인 경우, 종료 타임은 11,000 이 된다. 즉, 11,000 까지의 연주 분의 새로운 메세지를 모두 준비해, 큐에 저장 해야 한다.

큐의 사이즈는,DirectMusicPerformance.SetPrepareTime 를 호출해 변경할 수가 있다. 현재의 사이즈는,DirectMusicPerformance.GetPrepareTime 를 사용해 취득할 수가 있다.

대부분의 어플리케이션에서는, 디폴트의 준비 시간을 변경할 필요는 없다. 여기서 설명한 처리는, 어플리케이션으로부터는 인식되어 있지 않다. 다만, 어플리케이션은 DirectMusicPerformance.PlaySegment 에 DMUS_SEGF_AFTERPREPARETIME 플래그를 건네줄 수가 있으므로, 준비 시간의 개념을 이해해 두면(자) 유효하다.

보통, 세그먼트(segment)의 시작 타임을 "현재" 로 설정 하면, 퍼포먼스는 현재 큐에 저장 되고 있는 메세지를 모두 무효로 한다. 이 시점에서 유효한 그대로의 트랙 (예를 들어, 새로운 프라이머리 세그먼트(segment)의 도입에 관계없이, 연주가 계속되는 세컨드리 세그먼트(segment)의 트랙)은, 새로운 세그먼트(segment)에 의한 음악 환경의 변화를 고려해, 메세지를 재발송신 해야 한다. 불필요한 처리를 피해 연속성을 확실히 하기 위해서 (예를 들어, 긴 음표나, 음악 이외의 DLS 사운드가 중단되지 않게 하기 위해서), DMUS_SEGF_AFTERPREPARETIME 플래그를 사용해, 현재 큐에 있는 메세지가 모두 처리되어 포트 버퍼에게 건네질 때까지, 세그먼트(segment)의 연주를 시작 하지 않게 지정할 수가 있다. 따라서, 예를 들어, 타임 10,000 까지의 메세지가 큐에 있어, 현재의 타임이 9,000 의 경우, 연주용으로 큐에 저장 되는 세그먼트(segment)는, 정확히 10,000 밀리 세컨드 후에 연주를 시작 한다.

상세한 것에 대하여는, 「세그먼트(segment)의 타이밍」을 참조할것.


지연 시간과 범퍼 시간

[C++]

지연 시간이란, 포트가 뮤직 메세지를 받아들이고 나서, 연주해야 할 충분한 웨이브가 합성될 때까지의 지연 시간을 의미한다. IDirectMusicPerformance::GetLatencyTime 메소드는, 현재의 타임에 퍼포먼스의 지연 시간을 덧셈 한 전체의 시간이 걸리기 시작한다. 이 값은, 포트의 지연 시간 클럭에 의해 돌려주어지는 최대의 값이다.

범퍼란, 음악 이벤트가 포트 버퍼에 놓여지고 나서, 포트가 그 이벤트의 처리를 시작 하는 타임까지의, 코드를 실행하기 위해서 할당할 수 있었던 시간이다. 디폴트에서는, 범퍼의 길이는 50 밀리 세컨드 (ms)이다. 어플리케이션은,IDirectMusicPerformance::SetBumperLength 메소드를 사용해 이 값을 변경해,IDirectMusicPerformance::GetBumperLength 를 호출해 현재의 값을 취득할 수 있다.

지연 시간과 범퍼 시간은 결합되는 경우가 있다. 어느 이벤트가 10,000 밀리 세컨드의 시점에서 연주되면(자) 가정한다. 이 포트의 지연 시간은 100 밀리 세컨드인 것, 및 범퍼 시간의 길이는 디폴트의 50 밀리 세컨드인 것을 알 수 있고 있다. 그 때문에, 퍼포먼스는 9,850 밀리 세컨드의 시점에서 이 메세지를 포트 버퍼에 둔다.

포트 버퍼에 놓여진 메세지는, 이미 퍼포먼스에 소속하지 않기 때문에,IDirectMusicPerformance::Invalidate 또는 IDirectMusicPerformance::Stop 메소드를 사용해도, 연주를 멈출 수 없는 점에 주의 해야 한다. 무효로 할 수 있는 최초의 메세지는, 현재의 타임에 지연 시간과 범퍼 시간을 더한 타임과 같은가, 그 이후의 타임 스탬프를 가진다. IDirectMusicPerformance::GetQueueTime 메소드를 사용하면(자), 이 값을 취득할 수가 있다.

[Visual Basic]

지연 시간이란, 포트가 뮤직 메세지를 받아들이고 나서, 연주해야 할 충분한 웨이브가 합성될 때까지의 지연 시간을 의미한다. DirectMusicPerformance.GetLatencyTime 메소드는, 현재의 타임에 퍼포먼스의 지연 시간을 덧셈 한 전체의 시간이 걸리기 시작한다. 이 값은, 포트의 지연 시간 클럭에 의해 돌려주어지는 최대의 값이다.

범퍼란, 음악 이벤트가 포트 버퍼에 놓여지고 나서, 포트가 그 이벤트의 처리를 시작 하는 타임까지의, 코드를 실행하기 위해서 할당할 수 있었던 시간이다. 디폴트에서는, 범퍼의 길이는 50 밀리 세컨드 (ms)이다. 어플리케이션은,DirectMusicPerformance.SetBumperLength 메소드를 사용해 이 값을 변경하거나DirectMusicPerformance.GetBumperLength 를 호출해 현재의 값을 취득할 수가 있다.

지연 시간과 범퍼 시간은 결합되는 경우가 있다. 어느 이벤트가 10,000 밀리 세컨드의 시점에서 연주되면(자) 가정한다. 이 포트의 지연 시간은 100 밀리 세컨드인 것, 및 범퍼 시간의 길이는 디폴트의 50 밀리 세컨드인 것을 알 수 있고 있다. 그 때문에, 퍼포먼스는 9,850 밀리 세컨드의 시점에서 이 메세지를 포트 버퍼에 둔다.

포트 버퍼에 놓여진 메세지는, 이미 퍼포먼스에 소속하지 않기 때문에,DirectMusicPerformance.Invalidate 또는 DirectMusicPerformance.Stop 메소드를 사용해도, 연주를 멈출 수 없는 점에 주의 해야 한다. 무효로 할 수 있는 최초의 메세지는, 현재의 타임에 지연 시간과 범퍼 시간을 더한 타임과 같은가, 그 이후의 타임 스탬프를 가진다. DirectMusicPerformance.GetQueueTime 메소드를 사용하면(자), 이 값을 취득할 수가 있다.

다음의 그림은, 다양한 메소드로 취득되는, 타임과 계속 시간의 관계를 나타내고 있다. 현재의 타임은 좌측으로 나타나고 있다. 우측이, 메세지의 준비가 완료하는 최종 타임이다. 준비 시간은 언제라도, 큐에 있는 메세지의 합계의 길이의 근사이다.

[Visual Basic]

그림에 나타내는 메소드는 C++ API 의 것이지만, DirectX for Visual Basic 에서도 거의 같은 이름이 사용되고 있다. 예를 들어,IDirectMusicPerformance::GetPrepareTime 는 DirectMusicPerformance.GetPrepareTime 와 등가이며, 그림의 GetTime 메소드는 DirectMusicPerformance.GetClockTime 와 등가이다.


세그먼트(segment)의 타이밍

[C++]

IDirectMusicSegment::SetStartPoint 메소드를 호출해 시작 포인트를 설정하지 않는 한, 세그먼트(segment)는 최초부터 연주된다. IDirectMusicSegment::SetRepeats 를 사용해 리피트 회수를 설정했을 경우,IDirectMusicSegment::SetLoopPoints 를 호출해 루프를 정의하지 않으면, 세그먼트(segment) 전체가 그 회수만 반복된다. 루프를 설정 하면, 세그먼트(segment)의 루프 포인트간의 부분만큼이 반복해진다.

세그먼트(segment)의 연주가 시작 되는 연주 타임은,IDirectMusicPerformance::PlaySegment 의 2 개의 파라미터에 의해 결정된다.

  • i64StartTime 파라미터는, 세그먼트(segment)의 연주를 시작 할 수 있다, 가장 빠른 타임을 설정한다. i64StartTime 가 0 의 경우는, 가능한 한 빠른 타임이 된다. 세그먼트(segment)가 시작 되는 타임은, 세그먼트(segment)의 종류에 따라서 다르다. 프라이머리 세그먼트(segment) 또는제어 세그먼트(segment) 의 경우, 가장 빠른 시작 타임은 큐 (또는 플래시) 시간이다. 제어 이외의 세컨드리 세그먼트(segment)의 경우, 가장 빠른 시작 타임은 지연 시간 다음에 있다. 큐 시간과 대기 시간의 상세한 것에 대하여는, 「지연 시간과 범퍼 시간」을 참조할것.
  • dwFlags 파라미터는, 현재 연주중의 세그먼트(segment)의 리듬에 근거해, 스케줄 된 타임 이후 얼마나 신속하게 세그먼트(segment)의 연주를 시작 할 수 있을까를 결정한다. 보통은, 새로운 세그먼트(segment)를 시작 하기 전에 적절한 시간, 즉 이행부나 모티프의 길이만 기다릴 것이다. 다음의 DMUS_SEG_FLAGS 의 어느쪽이든을 설정하는 것으로써, 지연을 제어한다.
[Visual Basic]

DirectMusicSegment.SetStartPoint 메소드를 호출해 시작 포인트를 설정하지 않는 한, 세그먼트(segment)는 최초부터 연주된다. IDirectMusicSegment.SetRepeats 를 사용해 리피트 회수를 설정했을 경우,DirectMusicSegment.SetLoopPoints 를 호출해 루프를 정의하지 않으면, 세그먼트(segment) 전체가 그 회수만 반복된다. 루프를 설정 하면, 세그먼트(segment)의 루프 포인트간의 부분만큼이 반복해진다.

세그먼트(segment)의 연주가 시작 되는 연주 타임은,DirectMusicPerformance.PlaySegment 의 2 개의 파라미터에 의해 결정된다.

  • startTime 파라미터는, 세그먼트(segment)의 연주를 시작 할 수 있다, 가장 빠른 타임을 설정한다. startTime 가 0 의 경우는, 가능한 한 빠른 타임이 된다. 세그먼트(segment)가 시작 되는 타임은, 세그먼트(segment)의 종류에 따라서 다르다. 프라이머리 세그먼트(segment) 또는제어 세그먼트(segment) 의 경우, 가장 빠른 시작 타임은 큐 (또는 플래시) 시간이다. 제어 이외의 세컨드리 세그먼트(segment)의 경우, 가장 빠른 시작 타임은 지연 시간 다음에 있다. 큐 시간과 지연 시간의 상세한 것에 대하여는, 「지연 시간과 범퍼 시간」을 참조할것
  • IFlags 파라미터는, 현재 연주중의 세그먼트(segment)의 리듬에 근거해, 스케줄 된 타임 이후 얼마나 신속하게 세그먼트(segment)의 연주를 시작 할 수 있을까를 결정한다. 보통은, 새로운 세그먼트(segment)를 시작 하기 전에 적절한 시간, 즉 이행부나 모티프의 길이만 기다릴 것이다. 다음의 CONST_DMUS_SEGF_FLAGS 의 어느쪽이든을 설정해, 지연을 제어한다.
DMUS_SEGF_AFTERPREPARETIME
가장 빠른 시작 타임에준비 시간을 더한 타임에 연주한다. 이미 큐에 있는 현재 연주중의 세그먼트(segment)로부터 포트에의 메세지는, 모두 무효가 되지 않는다. 이것에 의해 처리 시간이 생략 되어 프라이머리 세그먼트(segment)간의 이행부에서 모티프가 매끈매끈하게 연주되는 것이 보증된다.
DMUS_SEGF_GRID
그리드 경계에서 연주한다. 그리드와는 박 (비트)의 소분할이다. 스타일의 형식에서 오쏘링 된 박자 기호는, 각 박을 몇개의 그리드에 분할할까를 결정한다.
DMUS_SEGF_BEAT
박으로 연주한다.
DMUS_SEGF_MEASURE
소절의 선두에서 연주한다.
DMUS_SEGF_DEFAULT
삽입된 세그먼트(segment)의 디폴트의 경계를 사용한다.

이러한 플래그가 모두 세트되어 있지 않은 경우, 세그먼트(segment)는 가장 빠른 시작 타임에 연주를 시작 한다.

템포의 변경에 의해 시작 타임이 받는 영향에 대해서는, 「클럭 타임과 뮤직 타임」을 참조할것.


통지와 이벤트의 처리

어플리케이션은, 음악 이벤트에 응답해야 하는 경우가 있다. 예를 들어, 세그먼트(segment)가 끝난 것을 확인할 필요가 있는 경우나, 그래픽스와 음악의 박을 동기 시키고 싶은 경우 등이다. 특정의 타입의 이벤트가 발생했을 때에, 그것을 통지하도록(듯이) DirectMusic 에 지시해, 필요한 정보를 취득할 수가 있다.

[C++]

통지를 받고 싶은 음악 이벤트의 종류를 지정하려면 , 이벤트의 종류 마다 한 번 만여라 IDirectMusicPerformance::AddNotificationType 메소드를 호출한다. 다음의 코드예에서는, DirectMusic 에 세그먼트(segment)에 관련하는 이벤트를 설정하도록(듯이) 지시하고 있다. 실제의 이벤트의 종류 (세그먼트(segment)의 시작이나 세그먼트(segment)의 종료등)는, 통지 메세지로부터 얻을 수 있다.

/* pPerformance 은, 유효한
   IDirectMusicPerformance 포인터이다고 한다. */

GUID guid = GUID_NOTIFICATION_SEGMENT;
// C 의 구문
pPerformance->AddNotificationType(&guid);
// C++ 의 구문
pPerformance->AddNotificationType(guid);

IDirectMusicSegment::AddNotificationType 메소드를 사용해, 특정의 세그먼트(segment)에 대해서 통지 타입을 추가할 수도 있다. 예를 들어, 특정의 세그먼트(segment)가 연주를 정지했을 때에 통지를 받는 것 같은 경우에, 이 설정을 실시할 수가 있다. 이 메소드를 사용해 GUID_NOTIFICATION_PERFORMANCE 형을 요구할 수 없다. 이러한 형태는, 퍼포먼스 오브젝트로부터 취득해야 한다.

통지는,DMUS_NOTIFICATION_PMSG 메세지 구조체의 형식에서 보내진다. IDirectMusicPerformance::GetNotificationPMsg 메소드를 호출해, Windows 메시지 루프내에서 보류중의 통지 메세지를 폴링 할 수가 있다. 또, 메세지가 보류중 때에, DirectMusic 에 다른 thread로 이벤트 오브젝트를 통지시킬 수도 있다.

Windows 이벤트 오브젝트를 사용해, 보류중의 DirectMusic 통지 메세지를 알리고 싶은 경우는, 우선 Win32 CreateEvent 함수를 호출해, 이벤트 핸들을 취득해야 한다. 보통은, 다음과 같은 호출을 실시해, 자동 리셋 이벤트를 생성 한다.

HANDLE g_hNotify = CreateEvent(NULL, FALSE, FALSE, NULL);

이벤트의 생성 후, 이 핸들을 IDirectMusicPerformance::SetNotificationHandle 메소드에 건네주어 퍼포먼스에 할당한다. 이벤트를 꺼낼 수 없었던 경우에서도 DirectMusic 는 이벤트를 대기하지만, 이 메소드의 2 번째의 파라미터를 사용하면(자) 디폴트의 시간을 변경할 수 있다. 이 파라미터에 0 을 지정 하면, 디폴트의 시간의 2 초가 사용된다.

다음의 예에서는,g_pPerf 는 IDirectMusicPerformance 인터페이스에의 유효한 포인터를 나타내고 있다.

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);

어플리케이션의 메시지 루프로, 이벤트를 생성 해 통지 메세지를 꺼낼 필요는 없다. IDirectMusicPerformance::AddNotificationType 메소드를 호출해 통지를 요구하고 있는 경우, 메세지는 퍼포먼스에 의해 송신되어IDirectMusicPerformance::GetNotificationPMsg 의 호출로 꺼낼 수가 있다.

이벤트가 통지되는 경우, 또는 메시지 루프로 GetNotificationPMsg 를 호출하는 경우는, 복수의 메세지를 대기할 수가 있다. 모든 통지를 확실히 받으려면 , S_FALSE 가 돌려주어질 때까지 GetNotificationPMsg 의 호출을 반복한다.

같은 타임 스탬프를 가지는 메세지가 다수 있는 경우, 이러한 메세지는 큐에 저장 될 때 특정의 순서는 되지 않는다.

IDirectMusicPerformance::FreePMsg 메소드를 호출해, 꺼낸 이벤트를 릴리즈 하는 것은 개발자의 책임이다.

[Visual Basic]

통지를 받고 싶은 음악 이벤트의 종류를 지정하려면 , 이벤트의 종류 마다 한 번 만여라 DirectMusicPerformance.AddNotificationType 메소드를 호출한다. 다음의 코드예에서는, DirectMusic 에 세그먼트(segment) 이벤트를 요구하고 있다. perf 는 DirectMusicPerformance 오브젝트이다. 이벤트의 종류 (세그먼트(segment)의 시작이나 세그먼트(segment)의 종료등)는, 통지 메세지로부터 얻을 수 있다.

Call perf.AddNotificationType(DMUS_NOTIFY_ON_SEGMENT)

통지는,DMUS_NOTIFICATION_PMSG 메세지 타입의 형식에서 보내진다. Sub Main 또는 그 외의 루프로 DirectMusicPerformance.GetNotificationPMsg 메소드를 호출해, 보류중의 통지 메세지를 폴링 할 수가 있다. 또, 메세지가 보류중 때에, DirectMusic 에 다른 thread로 이벤트 오브젝트를 통지시킬 수도 있다.

DirectMusic 에 이벤트를 통지시키려면 ,DirectX7.CreateEvent 을 사용해 이벤트 핸들을 취득해, 이 핸들을DirectMusicPerformance.SetNotificationHandle 에 건네준다. CreateEvent 에 건네주는 모듈은,DirectXEvent 클래스를 이행 해,DirectXEvent.DXCallback 메소드의 이행을 제공해야 한다. 이것은, 이벤트가 통지될 때마다 DirectMusic 에 의해 불려 간다.

다음의 코드예는,frmMain 라고 하는 폼 모듈의 통지를 설정해 있다.

' DX 는 DirectX7 오브젝트를 나타내, perf 는 DirectMusicPerformance 오브젝트를 나타낸다.
Dim hEvent As Long
hEvent = DX.CreateEvent(frmMain)
Call perf.SetNotificationHandle(hEvent)

폼 모듈에는, 다음에 나타내는 것과 같은 코드가 포함된다. 이 코드는, 세그먼트(segment)가 연주를 종료한 것을 나타내는 메세지를 검색한다.

Implements DirectXEvent

Private Sub DirectXEvent_DXCallback(ByVal eventid As Long)

Dim GotMSG As Boolean
Dim PMsg As DMUS_NOTIFICATION_PMSG

Do
GotMSG = gobjDMPerformance.GetNotificationPMSG(PMsg)
If GotMSG Then
If PMsg.lNotificationOption = DMUS_NOTIFICATION_SEGEND Then
'세그먼트(segment)가 연주를 종료하고 있다.
End If
End If
Loop Until Not GotMSG

End Sub

어플리케이션의 메인 루프로, 이벤트를 생성 해 통지 메세지를 꺼낼 필요는 없다. DirectMusicPerformance.AddNotificationType 메소드를 호출해 통지를 요구하고 있는 경우, 메세지는 퍼포먼스에 의해 송신되어DirectMusicPerformance.GetNotificationPMsg 의 호출로 꺼낼 수가 있다.

이벤트가 통지되는 경우, 또는 루프로 GetNotificationPMsg 를 호출하는 경우는, 복수의 메세지를 대기할 수가 있다. 모든 통지를 확실히 받으려면 , False 가 돌려주어질 때까지 GetNotificationPMsg 의 호출을 반복한다.

같은 타임 스탬프를 가지는 메세지가 다수 있는 경우, 이러한 메세지는 큐에 저장 될 때 특정의 순서는 되지 않는다.


뮤직 파라미터

[Visual Basic]

DirectX for Visual Basic 에서는,DirectMusicPerformance 및 DirectMusicSegment 의 다양한 메소드를 사용해, 뮤직 파라미터를 설정 및 꺼낼 수가 있다.

변경된 파라미터에 음악을 즉시 응답시키려면 , 어플리케이션으로 DirectMusicPerformance.Invalidate 메소드를 사용해, 큐로부터 메세지를 플래시 한다. 이 메소드에 의해, 모든 트랙은 지정한 포인트 이후의 메세지를 재발송신 한다.

[C++]

DirectMusic 에서는, 다음의 SetParam 메소드의 어느쪽이든을 사용해 실행중으로 파라미터를 변경해, 트랙의 다양한 동작을 제어할 수가 있다. ,

  • IDirectMusicPerformance::SetParam 는, 이 퍼포먼스의 현재의제어 세그먼트(segment)내에서, 특정의 트랙에 데이터를 설정한다. 제어 세그먼트(segment)는, 보통은 프라이머리 세그먼트(segment)이지만, 세컨드리 세그먼트(segment)를 연주중에 제어 세그먼트(segment)로서 지정할 수가 있다. DMUS_SEGF_FLAGS 를 참조할것.
  • IDirectMusicSegment::SetParam 는, 세그먼트(segment)내의 특정의 트랙에 데이터를 설정한다.
  • IDirectMusicTrack::SetParam 는, 트랙에 데이터를 설정한다.

또,IDirectMusicPerformance::SetGlobalParam 메소드를 사용해, 퍼포먼스 전체에 적용되는 값을 설정할 수가 있다.

GetParam 및 GetGlobalParam 메소드는, 트랙 또는 퍼포먼스의 현재의 값을 취득한다.

변경된 파라미터에 음악을 즉시 응답시키려면 , 어플리케이션으로 IDirectMusicPerformance::Invalidate 메소드를 사용해, 큐로부터 메세지를 플래시 한다. 이 메소드에 의해, 모든 트랙은 지정한 포인트 이후의 메세지를 재발송신 한다.

파라미터의 상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 트랙 파라미터의 설정과 꺼내
  • 글로벌 파라미터의 설정과 꺼내


트랙 파라미터의 설정과 꺼내

[Visual Basic]

DirectMusicPerformance 및 DirectMusicSegment 의 메소드의 몇개인가에서는, 보통은제어 세그먼트(segment)의 특정의 트랙으로 파라미터를 설정 또는 취득할 수가 있다. 다만, DirectX for Visual Basic 를 사용하는 어플리케이션은, 이러한 트랙에 도착해 관여할 필요는 없다. 이러한 메소드는, 저레벨에서의 동작에 대해 몰라도 사용할 수가 있다.

[C++]

퍼포먼스, 세그먼트(segment), 또는 트랙의 SetParam 및 GetParam 메소드를 사용해, 트랙 파라미터를 설정 및 취득할 수가 있다. 퍼포먼스 또는 세그먼트(segment)로 이러한 메소드의 어느쪽이든을 호출하면나무에,dwGroupBits 및 dwIndex 파라미터를 설정해, 트랙을 식별할 수가 있다. 다만, 대부분의 경우는, DirectMusic 에 적절한 트랙을 검색시킬 수가 있다. 상세한 것에 대하여는, 「트랙의 식별」을 참조할것.

경우에 따라서는, 변경을 실시하는 타임, 또는 파라미터를 취득하는 타임을, 트랙내에서 지정해야 한다. 특정의 트랙 파라미터로 이 값이 사용되고 있는지 어떤지를 확인하려면 , 「트랙 파라미터의 타입」을 참조할것.

몇개의 파라미터에서는,SetParam 로 기능이 온 또는 오프가 되어, 데이터는 필요없다. 다만, 다른 파라미터를 설정할 경우에, 데이터를 포함한 구조체 또는 변수도 건네주지 않으면 안 된다. 데이터에 관련지을 수 있었던 파라미터만을 꺼낼 수가 있다. 따라서,GetParam 를 사용하는 경우, 데이터를 받으려면 , 항상 적절한 변수 또는 구조체에의 포인터를 건네주지 않으면 안 된다.

특정의 파라미터가 트랙에 의해 지원 되고 있는지 어떤지를 확인하려면 ,IDirectMusicTrack::IsParamSupported 메소드를 사용해, S_OK 의 결과를 확인한다.

상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 트랙의 식별
  • 트랙 파라미터의 타입
  • 메세지의 무효화와 유효화


트랙의 식별

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

IDirectMusicTrack::SetParam 또는 IDirectMusicTrack::GetParam 를 사용해 파라미터를 설정 또는 취득할 경우에, 파라미터는 메소드를 호출한 트랙에 관련지을 수 있다. 다만,IDirectMusicPerformance::SetParam ,IDirectMusicPerformance::GetParam ,IDirectMusicSegment::SetParam , 또는 IDirectMusicSegment::GetParam 를 호출하면나무에, DirectMusic 는 적절한 트랙을 검색할 필요가 있다.

보통은, 목적의 파라미터가 어느 트랙에 포함될까를, DirectMusic 로 결정시킬 수가 있다. 이 경우,dwGroupBits 를 0xFFFFFFFF 에,dwIndex 를 0 으로 설정한다. 예를 들어, 다음의 IDirectMusicSegment::SetParam 의 호출에서는, 세그먼트(segment)의 루프로 템포가 리셋 되지 않게, 템포 트랙을 오프로 하고 있다.

pIDMSegment->SetParam(GUID_DisableTempo, 0xFFFFFFFF, 0, 0, NULL);

다만, 트랙을 식별해야 하는 경우도 있다. 일반적으로는, 세그먼트(segment)에 같은 타입의 트랙이 2 개 이상 포함되어 있는 경우이다. 목적의 트랙으로 파라미터를 설정 또는 취득하려면 , 그룹 또는 인덱스값을 사용해, 트랙을 식별해야 한다.

모든 트랙은 1 개 또는 복수의 그룹에 속해, 각각의 그룹은 dwGroupBits 파라미터의 비트로 나타내진다. dwGroupBits 는, 다음에 설명하는 메소드의 1 개의 파라미터이다 (트랙은, 퍼포먼스에 삽입될 때, 1 개(살) 또는 복수의 그룹에 할당할 수 있다. IDirectMusicSegment::InsertTrack 를 참조할것. 파일로부터 로드 되는 세그먼트(segment)의 경우, 트랙 그룹은 세그먼트(segment)의 작가에 의해 할당할 수 있다).

트랙은, 속하고 있는 그룹 각각 두어, 제로로부터 시작되는 인덱스값으로 식별된다. 인덱스값은, 트랙이 삽입된 순서로 결정된다.

1 개의 세그먼트(segment)가, 다음의 트랙에 의해 구성되어 있으면(자) 가정한다.

트랙 | 그룹 비트
A | 0x1
B | 0x2
C | 0x1
D | 0x3

그룹 1 은 트랙 A, 트랙 C, 및 트랙 D 를 포함해, 그룹 2 는 트랙 B 와 트랙 D 를 포함한다. dwGroupBits 를 1,dwIndex 를 0 으로 해 GetParam 또는 SetParam 를 호출하면, 파라미터는, 그룹 1 의 최초의 트랙인 트랙 A 로부터 꺼내진다. dwIndex 가 1 의 경우는, 그룹에서 2 번째의 트랙 C 로부터 파라미터가 꺼내진다. 트랙 D 는, 그룹 1 으로 그룹 2 의, 2 개의 그룹에 속하고 있다. 따라서, 이 트랙은,dwGroupBits = 1 및 dwIndex =2, 또는 dwGroupBits = 2 및 dwIndex = 1 의 편성의 어느 쪽인지로 식별된다.

dwGroupBits 에 복수의 비트를 설정 하면, 그러한 모든 비트를 포함한 n 번째의 트랙으로부터 파라미터가 꺼내진다. 여기서 n 는 dwIndex 내의 값이다.


트랙 파라미터의 타입

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

SetParam 또는 GetParam 메소드의 어느쪽이든으로 설정 또는 꺼내지는 트랙 파라미터는, 메소드의 rguidType 파라미터의 GUID 로 식별된다. 데이터를 필요로 하는 각 파라미터는, 특정의 데이터 타입에 관련지을 수 있고 있다. pParam 는, 이 타입의 변수 또는 구조체를 가리키지 않으면 안 된다. 경우에 따라서는,GetParam 를 호출하면나무에도, 데이터 구조체의 일부를 초기화할 필요가 있다.

정의 끝난 파라미터를, 다음 표에 나타낸다. 각 파라미터의 상세한 것에 대하여는, 링크처의 겉(표)를 참조할것. 상세한 겉(표)로,pParam 및 mtTime 는, 다양한 GetParam 및 SetParam 메소드의 파라미터를 나타내고 있다. 파라미터는 항상 특정의 트랙 타입에 관련지을 수 있지만, 보통은, 세그먼트(segment) 또는 퍼포먼스로 메소드를 호출하면, DirectMusic 가 적절한 트랙을 검색한다 ( 「트랙의 식별」을 참조할것).

GUID_ChordParam | GUID_EnableTimeSig
GUID_Clear_All_Bands | GUID_IDirectMusicBand
GUID_CommandParam | GUID_IDirectMusicChordMap
GUID_CommandParam2 | GUID_IDirectMusicStyle
GUID_ConnectToDLSCollection | GUID_MuteParam
GUID_Disable_Auto_Download | GUID_RhythmParam
GUID_DisableTempo | GUID_SeedVariations
GUID_DisableTimeSig | GUID_StandardMIDIFile
GUID_Download | GUID_TempoParam
GUID_Enable_Auto_Download | GUID_TimeSignature
GUID_EnableTempo | GUID_Unload


글로벌 파라미터의 설정과 꺼내

[C++]

IDirectMusicPerformance::SetGlobalParam 및 IDirectMusicPerformance::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 의 단위로 나타내진다. 디폴트의 볼륨 또는 퍼포먼스 전체에 적용된다. 설정할 수 있는 값의 범위는, 포트에 의해 정해진다. 종래의 하드웨어 MIDI 포트에서는, 마스터 볼륨의 변경은 지원되어 있지 않다.

어플리케이션은, 독자적인 타입의 글로벌 파라미터를 사용할 수도 있다. 새로운 타입을 생성 하려면 , GUID 와 그 데이터 타입을 확정한다.

파라미터를 설정할 경우에, 퍼포먼스는, GUID 로 식별되는 링크된 항목의 리스트의 데이터에 메모리를 할당한다. 데이터는,IDirectMusicPerformance::GetGlobalParam 를 호출해 꺼낼 수가 있다. 정의 끝난 파라미터도, 꺼내기 전에는 설정해야 한다. 파라미터에 대해서 SetGlobalParam 가 불려 가지 않은 경우,GetGlobalParam 는 실패한다.

[Visual Basic]

DirectMusicPerformance 클래스에는, 퍼포먼스 전체에 영향을 주는 글로벌 파라미터를 설정 및 취득하기 위한 , 다음의 메소드가 준비되어 있다.

GetMasterAutoDownload SetMasterAutoDownload | 이 파라미터는, 세그먼트(segment)를 연주할 경우에 음색을 자동적으로 다운로드할지 어떨지를 제어한다. 디폴트에서는 오프이다. 「밴드의 다운로드와 언로드」를 참조할것.
GetMasterGrooveLevel SetMasterGrooveLevel | 마스터 그루브 레벨은, 커멘드 트랙으로 설정되는 그루브 레벨에 항상 덧셈 되는 값이다. 필요한 경우는, 1 ~ 100 의 범위가 되도록(듯이), 결과의 값이 조정된다.
GetMasterTempo SetMasterTempo | 마스터 템포는, 최종 출력 툴에 의해 템포에 적용되는 스케일 팩터이다. 디폴트의 값은 1 이다. 0.5 로 템포는 2 분의 1 이 되어, 2.0 으로 2 배의 템포가 된다. 이 값은, 0.25 ~ 2.0 의 범위에서 설정할 수 있다.
GetMasterVolume SetMasterVolume | 마스터 볼륨은, 증폭 또는 감쇠의 계수로, 1 데시벨의 100 분의 1 의 단위로 나타내진다. 디폴트의 볼륨 또는 퍼포먼스 전체에 적용된다. 설정할 수 있는 값의 범위는, 포트에 의해 정해진다. 종래의 하드웨어 MIDI 포트에서는, 마스터 볼륨의 변경은 지원되어 있지 않다.


메세지의 무효화와 유효화

[C++]

트랙으로 GUID_DisableTempo 및 GUID_DisableTimeSig 파라미터를 설정 하면, 각각 DMUS_TEMPO_PMSG 및 DMUS_TIMESIG_PMSG 메세지의 생성을 무효로 할 수 있다. 예를 들어, 동적으로 템포를 설정해, 프라이머리 세그먼트(segment)에 템포 메세지를 송신시키고 싶지 않은 경우 등에 사용할 수 있다.

메세지를 다시 유효하게 하려면 ,rguidType 파라미터에 GUID_EnableTempo 및 GUID_EnableTimeSig 를 지정해, 몇개의 SetParam 를 호출한다. 이러한 파라미터를 설정해,제어 세그먼트(segment)가 아닌 세그먼트(segment)에 템포 메세지를 송신시키거나 세컨드리 세그먼트(segment)에 박자 기호 메세지를 송신시킬 수도 있다 (제어 세그먼트(segment)의 상세한 것에 대하여는, 「세그먼트(segment)」라고 DMUS_SEGF_FLAGS 를 참조할것).

파라미터를 설정하는 방법에 대해서는, 「트랙 파라미터의 설정과 꺼내」를 참조할것.

IDirectMusicTrack::IsParamSupported 의 「주의」도 참조할것.

[Visual Basic]

DirectMusicSegment.SetTempoEnable 및 DirectMusicSegment.SetTimeSigEnable 메소드를 사용하면(자), 템포와 박자 기호 메세지의 생성을 각각 무효로 할 수 있다. 예를 들어, 동적으로 템포를 설정해, 프라이머리 세그먼트(segment)에 템포 메세지를 송신시키고 싶지 않은 경우 등에 사용할 수 있다.

SetTempoEnable 를 사용하면(자),제어 세그먼트(segment)가 아닌 세그먼트(segment)에도 템포 메세지를 송신시킬 수도 있다. 또,SetTimeSigEnable 를 사용해, 세컨드리 세그먼트(segment)에 박자 기호 메세지를 송신시킬 수도 있다 (제어 세그먼트(segment)의 상세한 것에 대하여는, 「세그먼트(segment)」라고 DMUS_SEGF_FLAGS 를 참조할것).


음악의 캡춰

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에서는, 음악의 캡춰는 지원 되지 않는다.

[C++]

키보드등의 디바이스로부터 MIDI 메세지를 캡춰 하는 것은, DirectMusic 에서는 매우 간단하다.

보통은, 캡춰 디바이스의 포트를 생성 해,IDirectMusicPort::SetReadNotificationHandle 메소드를 사용해, 메세지를 읽어들일 수 있을 때 항상 이벤트에 통지시킨다. 이벤트에 응답해,IDirectMusicPort::Read 메소드의 호출을 S_FALSE 가 돌려주어질 때까지 반복해, 미처리의 이벤트를 버퍼에 둔다. Read 가 불려 갈 때마다, 이용 가능할 뿐(만큼)의 이벤트, 또는 버퍼에 들어갈 뿐(만큼)의 이벤트가 버퍼에 놓여진다. 적어도 1 개의 이벤트가 버퍼에 놓여지면(자), S_OK 가 돌려주어진다.

버퍼로부터 이벤트를 꺼내려면 ,IDirectMusicBuffer::GetNextEvent 메소드를 호출한다. S_FALSE 가 돌려주어져 이용 가능한 이벤트가 없어질 때까지, 호출할 것에 1 개의 이벤트를 받는다.

다음의 코드예는, 이 처리를 나타내고 있다.

/* hEvent 는 CreateEvent 로 생성 되어 SetReadNotificationHandle 의
호출에 의해, 캡춰 포트의 pPort 에
주어진다. 또, pBuffer 는 IDirectMusic::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가 종료.

도중에 메세지를 처리하지 않고 , 단지 메세지를 포트로부터 포트에 송신하는 경우는,IDirectMusicThru 인터페이스를 사용한다.


DirectMusic 툴

DirectMusic 에 있어서의 툴이란, 메세지를 도중에 취득해, 어떠한 방법으로 처리하는 오브젝트를 의미한다. 툴은 메세지로 변경을 더해 다음의 툴에 건네주는지, 메세지를 릴리즈 하는지, 원의 메세지내의 정보에 근거해 새로운 메세지를 송신하는지, 몇개의 방법으로 처리를 실시할 수 있다.

DirectMusic 에는 출력 툴이 있어, 보통은 이 툴이 마지막에 메세지를 받아들인다. 이 툴은, 퍼포먼스 메세지를 스탠다드 MIDI 메세지로 변환해, 신디사이저에의 스트림에 넣는다. 다른 툴은, 어플리케이션에 의해 이행 하는지, 라이브러리로부터 취득한다.

[Visual Basic]

DirectX for Visual Basic 에서는, 어플리케이션 정의의 툴, 또는 써드파티제의 툴은 지원 되지 않는다.

[C++]

툴을 이행 하려면 ,IDirectMusicTool 인터페이스를 지원 하는 오브젝트를 생성 해야 한다. IDirectMusicTool 메소드의 오브젝트 이행에 의해, 이 툴이 어느 메세지를 취득하는지, 및 그 메세지에 어떠한 작업을 실시할까를 결정한다.

보통, 출력 툴 이외의 모든 툴은 그래프에 수집된다. 어플리케이션이, 출력 툴 이외에 1 개(살) 밖에 툴을 사용하고 있지 않는 경우에서도, 이것을 포함하기 위한 DirectMusicGraph 를 생성 한다. 다음에, 그 그래프를 세그먼트(segment)나 퍼포먼스에 추가한다. 그래프는, 툴간에 메세지를 전송 할 때에 유효한 메카니즘이다.

퍼포먼스 엔진이 세그먼트(segment)를 연주할 경우에, 세그먼트(segment) 그래프내의 각 툴, 그 다음에 퍼포먼스 그래프내의 각 툴이, 각 메세지를 처리할 수 있다. 어느 툴이 메세지를 처리한 후, 그 툴은 IDirectMusicGraph::StampPMsg 메소드를 호출해 (DMUS_PMSG 구조체의 pGraph 멤버로부터 IDirectMusicGraph 포인터를 취득한다), 다음에 그 메세지를 받아들이는 툴이 있는 경우는, 그 툴에의 포인터를 메세지에 스탬프 한다. 그 다음에, 이 툴은 메세지를 파이프라인에 돌려준다.

툴은, 우선 순위의 높은 thread로 메세지를 처리한다. 툴의 IDirectMusicTool::ProcessPMsg 메소드내에서는, 그래픽스나 파일 입출력등을 실시하는 시간이 걸리는 함수를 호출하지 않게 한다. 툴이 액션을 방아쇠 할 필요가 있는 경우는, 어플리케이션의 메인 thread등의 다른 thread에 통지해 실행한다.

IDirectMusicTool 의 메소드를 이행 할 경우에, 친오브젝트에의 순환 참조를 생성 하지 않게 주의한다. 순환 참조는, 어느 오브젝트가 다른 오브젝트를 생성 했을 때에, 아이 오브젝트가 친오브젝트에의 참조를 유지하고 있는 경우에 발생한다. 예를 들어 툴이,IDirectMusicTool::Init 메소드에게 건네지는, 그래프에의 새로운 참조를 생성 하는 경우를 생각한다. 툴이 이 참조를 릴리즈 할 수 없는 경우, 세그먼트(segment)가 그래프를 릴리즈 하려고 했을 때에 문제가 발생한다. 툴에는 그래프에의 참조가 남아 있기 (위해)때문에, 그래프가 완전하게 릴리즈 되지 않는다. 또, 그래프에는 툴에의 참조가 있기 (위해)때문에, 툴도 릴리즈 되지 않는다.

툴의 설정 방법법의 상세한 것에 대하여는, 「튜토리얼 2 : 툴의 사용법」을 참조할것.


음악의 어레인지

여기에서는, DirectMusic 의 작곡가 엔진에 대해 소개한다. 엔진을 사용 하면, 이미 오쏘링 되고 있는 스타일, 템플릿, 밴드등의 요소를 사용해, 동적으로 뮤직 프로그램을 이행 할 수가 있다.

여기에서는, 다음의 항목에 대해 설명한다.

  • 뮤직 오쏘링의 개요
  • 어레인지용의 뮤직 파일
  • 어레인지용의 프로그래밍의 개요
  • 재생중의 음악의 변화
  • 뮤직값과 MIDI 음표
  • 어레인지 요소의 사용법


뮤직 오쏘링의 개요

어레인지용의 음악 요소의 작가는, DirectMusic Producer 등의 툴을 사용해, 어플리케이션으로 필요한 각 음악 테마의 기본적인 요소를 생성 한다. 다음의 각 항목의 상세한 정보에 대해서는, DirectMusic Producer 의 문서를 참조할것.

  • 스타일의 오쏘링
  • 코드 맵의 오쏘링
  • 스타일 베이스의 세그먼트(segment)의 오쏘링
  • MIDI 베이스의 세그먼트(segment)의 오쏘링
  • 템플릿의 오쏘링
  • 밴드의 오쏘링

주 : 여기에서는, DirectMusic 의 작곡가 오브젝트와의 혼동을 피하기 위해서(때문에), 인간의 작곡가 (작곡자)를 작가라고 표현한다.


스타일의 오쏘링

스타일과는 음악의 기본적인 정의이다. 스타일은 패턴의 모임이며, 박자 기호와 템포 (1 분간의 박수)가 포함된다. 스타일에는, 1 개(살) 또는 복수의 밴드를 포함할 수도 있다.

패턴은, 1 소절 이상의 길이의 음형으로, 각 음색의 기본적인 일련의 음표, 즉 파트로 구성된다. 이러한 음표는 고정되어 있지 않지만, 최종적으로는, 현재의 키, 코드, 및 연주 모드에 응해, 특정의 피치에 할당할 수 있다. 패턴에는, 바리에이션도 포함된다.

모티프는, 기본 스코아상에서 솔로로 연주되도록(듯이) 계획된, 특수한 패턴이다. 보통, 모티프는, 인터랙티브 어플리케이션으로 이벤트가 발생한 것을 나타내기 위해서(때문에) 사용된다. 예를 들어,DMDonuts 샘플 을 예에 취하면(자), 우주선이 화면의 구석에 접했을 때에 드럼 비트가 연주된다.

DirectMusic Producer 에서는, 작가는 피아노 롤을 닮은 그리드를 사용해 패턴을 생성 한다. 각 파트는 (P 채널에 대응한다) 독자적인 행을 가져, 음표는 바의 길이 (지속 시간), 굵기 (velocity), 세로축 방향의 위치 (피치), 및 횡축 방향의 위치 (시간)에서 나타내진다.

작가는, 각 패턴에 대해서 많은 바리에이션을 생성 할 수가 있다. 보통은, 패턴을 카피해 1 부를 조금 변경하는 것으로써, 바리에이션을 생성 할 수 있다. 스타일의 재생 메카니즘에 의해, 실행시에 바리에이션이 선택된다. 다만, 작가는 임의의 코드에 대해서 바리에이션을 무효로 할 수도 있다. 즉, 특정의 코드가 연주되고 있을 때는, 어느 바리에이션을 결코 선택하지 않게 지정할 수 있다.

작가는, 패턴에 그루브 범위를 할당해, 패턴을 연주할 수 있는그루브 레벨을 지정할 수도 있다.

패턴은, 장식으로서 지정할 수도 있다. 장식에는, 인트로, 필, 브레이크, 및 엔드의 4 종류가 있어, 이러한 1 개(살) 또는 복수의 카테고리에, 패턴을 할당할 수가 있다. 음악의 연주중에 특정의 장식이 불려 가면(자), 그 종류의 패턴만이 재생의 후보가 된다.


코드 맵의 오쏘링

현대의 음악이 많고, 특히 파퓰러, 락, 포크, 재즈의 특색은 코드 진행의 개념에 근거하고 있어 특정의 시간범위에 연주되는 모든 음표가 특정의 코드에 관련지을 수 있고 있는 것, 및 음악은 있는 코드로부터 다른 코드로 조화적으로 이행 하는 것을 의미한다.

DirectMusic 용으로 오쏘링 된 패턴에 있는 음표는, 1 개의 코드로부터 파생하고 있는지, 코드와 조화를 이루도록(듯이) 의도된 것이다. 그러나 실행시에, 패턴은 코드 진행에 맞추어 전조 한다. 즉 근저에 있는 코드의 변화에 응해, DirectMusic 는 음표의 피치를 변경한다.

코드 맵은, 코드 진행의 Roadmap이다. 코드맙데자이나를 사용해, 작가는 희망의 음악감이나 퍼소낼러티를 표현할 수 있는 코드를 선택한다. 작가는 타임 라인에 따라, 플로차트(flow chart)내에서 이러한 코드를 어레인지 한다 (타임 라인에는 순환이라고 하는 개념이 있으므로, 뮤직 섹션의 연주가 계속되는 동안, 최초로 돌아와 루프를 형성한다).

특정의 중요한 코드를 싸인 포스트로서 지정한다. 이것들은, 특정의 포인트로 연주되지 않으면 안 되는 코드이다. 음악은, 항상 싸인 포스트로부터 싸인 포스트로 이행 한다. 그러나, 싸인 포스트간의 코드 진행은, 작가의 지정한 맵에 따라 다양한 루트를 더듬을 수도 있다.

화음표내의 루트는, 작곡가 엔진에 의해 실행시에 선택할 수가 있다. 이 경우, 패턴 자체의 바리에이션에 추가해 바리에이션이 제공된다. 작가가 세그먼트(segment)를 생성 할 때에, authoring tool을 사용해 루트를 선택할 수도 있다.

코드 맵의 코드는, 서브 코드로 불리는, 복수가 다른 코드로 구성할 수가 있다. 같은 코드를 다른 회전으로 연주해 다조성을 얻기 위해서(때문에), 작가는 다른 서브 코드에 다른 파트를 할당할 수가 있다. 각 서브 코드는, 1 개(살) 또는 복수의 레벨로 유효하고, 스타일의 포트에 할당할 수 있었던 레벨로 조화를 이룬다.

주 : DirectMusic 에서는, 코드에 최대 DMUS_MAXSUBCHORD 까지의 서브 코드를 포함할 수가 있다. 이 값은 8 에 정의되고 있지만, DirectMusic Producer 에서는, 현재로서는, 1 코드에 최대 4 개의 서브 코드 밖에 생성 할 수 없다.


스타일 베이스의 세그먼트(segment)의 오쏘링

스타일 베이스의 세그먼트(segment)는, 미리 생성 된, 음악의 큰 부분이며, 작가는 다음의 요소를 사용해 섹션을 구축한다.

  • 스타일. 스타일은, 패턴과 같이, 음악에 관한 일반적인 정보 (박자 기호나 템포등)로 구성된다.
  • 코드 진행. authoring tool가 코드 맵으로부터 자동적으로 파생한 것 (화음표로부터 패스를 선택한다), 또는 작가가 수작업으로 입력한 것.
  • 설정한 타임에 적절한 패턴을 선택하기 위한 일련의 커멘드. 스타일중의 패턴의 특징은, 장식 (인트로, 필, 브레이크, 및 엔드)으로서 지정할 수 있는 것, 및 작가가 특정의 그루브 범위를 할당할 수가 있는 것이다. 세그먼트(segment)의 커멘드 트랙은, 스타일 재생 엔진에 대해서, 인트로 패턴을 선택해 최초의 소절로 연주해, 다음의 4 소절로그루브 레벨 이 25 의 패턴만을 재생한 후, 브레이크를 연주하는, 등의 동작을 지시할 수가 있다.
  • 밴드. 작가는, 음색과 P 채널을, 다양한 패턴의 모든 파트에 할당할 수가 있다.


MIDI 베이스의 세그먼트(segment)의 오쏘링

MIDI 베이스의 세그먼트(segment)는, DirectMusic Producer 로 MIDI 파일을 임포트 해 생성 된다. 작가는, 루프 포인트나, 템포, 키, 및 밴드 체인지를 추가할 수가 있다. 스타일 베이스의 세그먼트(segment)와 달리, MIDI 세그먼트(segment)에는 패턴 및 커멘드 트랙이 없다. 이러한 대신에 순서 트랙이 있어, MIDI 음표와 그 외의 커멘드는 여기에 포함된다.


템플릿의 오쏘링

템플릿은 세그먼트(segment)이지만, 스타일 베이스의 세그먼트(segment)와는 달라, 특정의 스타일에 속박 될 것은 없고, 고정 코드 진행도 갖추지 않았다.

템플릿은 코드 진행 대신에, 타임 라인에 따라 일련의 싸인 포스트그룹 마커를 갖추고 있다. 싸인 포스트는, 코드 진행의 바리에이션이 인정되는 리젼의 선두와 최후를 마크 하는 코드이다. 싸인 포스트를 생성 할 경우에, 작가는 이것을 1 개의 그룹에 할당한다.

DirectMusicComposer 가, 템플릿과 특정의 스타일 및 코드 맵을 조합해 세그먼트(segment)를 생성할 경우에, authoring tool내나 실행시에, 다음과 같은 처리를 한다. 템플릿내의 타임 라인에 따라 엔진이 싸인 포스트그룹의 마커 페어를 찾아낼 때마다, 엔진은 그 그룹에 소속하는 싸인 포스트코드의 페어에 대응하는 코드 맵을 참조한다. 페어가 발견되어, 그 페어간의 간격이 이용 가능한 시간에 적합하는 경우는, 엔진은 코드 맵으로 정의되고 있는 2 개의 싸인 포스트코드간의 고정 코드 진행에 따른다. 페어간의 적절한 패스가 발견되지 않는 경우나, 엔드 싸인 포스트마커가 존재하지 않는 경우는, 엔진은 시작 싸인 포스트그룹 마커로부터 파생한 임의의 코드를 연주한다.

작가는 세그먼트(segment)를 생성 할 때에, 템플릿을 사용해, 복수의 스타일에 유사한 코드 진행,그루브 레벨, 및 장식을 적용할 수가 있다. 다만, DirectMusicComposer 오브젝트가 실행시에, 템플릿을 스타일이나 코드 맵과 조합하는 경우도 있다.


밴드의 오쏘링

밴드와는 일련의 음색에 각각의 퍼포먼스 파라미터를 조합해 음악의 부분내의 특정의 파트를 조합한 것이다. 밴드는 DLS 콜렉션과 같지 않다. DLS 콜렉션은 신디사이저에 다운로드할 수 있는 음색세트를 나타내, 임의의 어플리케이션으로부터 이용할 수가 있다.

작가는 DirectMusic Producer와 같은 툴을 사용해, 악기를 P 채널에 할당하는 것으로 밴드를 생성 하는 이러한 음색은 임의의 DLS 콜렉션으로부터 취득할 수가 있어 다른 소스의 음색을 1 개의 밴드에 혼재시킬 수도 있다. 예를 들어, General MIDI 세트의 재즈 기타를 파트 1, Roland GS 세트의 60 열쇠 오르간을 파트 2, 커스텀 DLS 콜렉션의 에스닉 퍼크션을 파트 3 에 배치할 수 있다. 이러한 각 음색에는, 특정의 볼륨, 팬, 전조의 설정도 할당할 수 있다.

P 채널은, 음색을 파트에 할당한다. 패턴이 P 채널 1 의 특정의 음표를 호출하는 경우, 이 음표는 P 채널 1 에 할당할 수 있고 있는 현재의 밴드의 음색으로 연주된다. 사운드는, 밴드로 설정되어 있는 음색의 볼륨, 팬, 및 전조의 값으로 수정된다.

밴드는 개별의 파일에 보존하는지, 스타일이나 세그먼트(segment)에 포함할 수 있다.


어레인지용의 뮤직 파일

DirectMusic 의 어레인지를 프로그래밍 하는 경우, DirectMusic Producer 와 같은 툴로 생성 한 다양한 파일을 사용한다. 이러한 요소를 COM 오브젝트로서 어플리케이션에 로드해, 그러한 오브젝트에의 인터페이스를 취득한다 ( 「DirectMusic 로더」를 참조할것).

다음 표에, 개발자가 취급하는 파일의 타입을 나타낸다.

[C++]

클래스 GUID 는, 오브젝트를 로드할 때에 DMUS_OBJECTDESC 구조체의 guidClass 멤버에 기입하는 값이다.

요소 | 클래스 GUID | 인터페이스 | 파일 타입
밴드 | CLSID_DirectMusicBand | IDirectMusicBand | . bnd
DLS 콜렉션 | CLSID_DirectMusicCollection | IDirectMusicCollection | . dls
코드 맵 | CLSID_DirectMusicChordMap | IDirectMusicChordMap | . cdm
세그먼트(segment) | CLSID_DirectMusicSegment | IDirectMusicSegment | . sgt
스타일 | CLSID_DirectMusicStyle | IDirectMusicStyle | . sty
템플릿 | CLSID_DirectMusicSegment | IDirectMusicSegment | . tpl

[Visual Basic]
요소 | DirectMusicLoader 메소드 | 클래스 | 파일 타입
밴드 | LoadBand | DirectMusicBand | . bnd
DLS 콜렉션 | LoadCollection | DirectMusicCollection | . dls
코드 맵 | LoadChordMap | DirectMusicChordMap | . cdm
세그먼트(segment) | LoadSegment | DirectMusicSegment | . sgt
스타일 | LoadStyle | DirectMusicStyle | . sty
템플릿 | LoadSegment | DirectMusicSegment | . tpl

주 : 밴드는 스타일의 일부로서 오쏘링 할 수 있지만, 그 경우, 스타일을 로드할 때 그것들도 자동적으로 로드 된다. 같이 스타일과 밴드는 세그먼트(segment)에 오쏘링 할 수 있다. 이 경우, 이러한 요소를 다른 파일로 나눌 필요없다.

파일에는, 다른 파일에의 참조를 포함할 수가 있다. 스타일에 밴드에의 참조가 포함되어 있는 경우, 로더가 밴드 파일을 찾아낼 수가 있으면, 스타일이 로드 될 때 자동적으로 밴드도 로드 된다.


어레인지용의 프로그래밍의 개요

실행시에 어레인지 되는 음악을 이행 할 경우에, 이미 오쏘링 되고 있는 오브젝트를 빌딩 블록으로서 사용한다. 작가나 다른 컨텐트 프로바이더와 상담하면서, 작은 빌딩 블록으로서 취득하는 뮤직 데이터를 선택하는 것으로써, 실행시에 가장 높은 유연성이나 바리에이션을 실현하거나 음악을 보다 완성된 형태로 정의하기 위해서, 미리 생성 된 요소를 보다 많이 이용할 수 있다.

[C++]

최대의 빌딩 블록을 사용해, 연주하는 음악에 대해 퍼포먼스에 지시해야 하는 정보의 모든 것이 포함되어 있는, 고도로 구조화 된 세그먼트(segment) (스타일 베이스 또는 MIDI 베이스)를 로드한다. 필요한 것은, 섹션을 로드해,IDirectMusicSegment 인터페이스의 쿼리를 실시하는 것 뿐이다. 이 인터페이스 포인터를 IDirectMusicPerformance::PlaySegment 메소드에 건네준다. 스타일 재생 엔진은, 스타일로부터 패턴 바리에이션을 선택해, 고정 코드 진행에 따라 이것들을 연주한다. 또, MIDI 베이스의 세그먼트(segment)의 경우는, MIDI 순서를 연주한다. (와)과 같이 밴드 체인지는, 보통, 세그먼트(segment)에 포함된다.

[Visual Basic]

최대의 빌딩 블록을 사용해, 연주하는 음악에 대해 퍼포먼스에 지시해야 하는 정보의 모든 것이 포함되어 있는, 고도로 구조화 된 세그먼트(segment) (스타일 베이스 또는 MIDI 베이스)를 로드한다. 필요한 작업은,DirectMusicLoader.LoadSegment 또는 DirectMusicLoader.LoadSegmentFromResource 메소드를 사용해 세그먼트(segment)를 로드하는 것 뿐이다. 계속되어, 돌려주어진 DirectMusicSegment 오브젝트를 DirectMusicPerformance.PlaySegment 메소드에 건네준다. 스타일 재생 엔진은, 스타일로부터 패턴 바리에이션을 선택해, 고정 코드 진행에 따라 이것들을 연주한다. 또, MIDI 베이스의 세그먼트(segment)의 경우는, MIDI 순서를 연주한다. (와)과 같이 밴드 체인지는, 보통, 세그먼트(segment)에 포함된다.

보다 작은 빌딩 블록을 사용하는 경우는, 다음의 요소를 취득한다.

  • 코드 맵. 코드 진행의 Roadmap를 나타낸다.
  • 스타일. 기본적인 멜로디나 리듬과 함께, 바리에이션, 모티프, 및 장식을 정의한다.
  • 템플릿 세그먼트(segment). 구조적인 계획이며, 세그먼트(segment)의 길이, 루프의 유무,그루브 레벨의 변경이나 장식을 배치하는 장소, 코드 맵으로 싸인 포스트의 역할을 완수하는 코드의 타입을 포함해 재생의 다양한 측면을 제어한다.
[C++]

IDirectMusicComposer::ComposeSegmentFromTemplate 메소드를 사용해, 코드 맵, 스타일, 및 템플릿을 조합해 세그먼트(segment)를 구축한다.

실행시의 음악 어레인지를 보다 유연하게 실시하려면 ,IDirectMusicComposer::ComposeSegmentFromShape 메소드를 사용해, 템플릿은 아니고 정의 끝난 셰이프에 근거하는 세그먼트(segment)를 생성 한다. 셰이프는, 커멘드 및 싸인 포스트트랙의 생성에 사용되어 장식 패턴, 코드 진행, 및 코드 변경의 빈도의 선택을 제어한다.

세그먼트(segment)를 연주할 경우에, 파트의 연주에 사용하는 밴드를 제어할 수도 있다. 보통, 밴드는 스타일 및 템플릿의 일부로서 오쏘링 되지만, 어플리케이션이 동적으로 밴드 체인지를 실시할 수 있도록, 밴드를 개별의 파일로서 공급할 수도 있다. 그 경우,IDirectMusicBand::CreateSegment 메소드를 사용해, 밴드만으로부터 되는 세컨드리 세그먼트(segment)를 생성 해, 음색이나 음색의 설정을 프라이머리 세그먼트(segment)에 할당할 때, 이 세컨드리 세그먼트(segment)를 연주해야 한다. 상세한 것에 대하여는, 「밴드의 사용법」을 참조할것.

[Visual Basic]

DirectMusicComposer.ComposeSegmentFromTemplate 메소드를 사용해, 코드 맵, 스타일, 및 템플릿을 조합해 세그먼트(segment)를 구축한다.

실행시의 음악 어레인지를 보다 유연하게 실시하려면 ,DirectMusicComposer.ComposeSegmentFromShape 메소드를 사용해, 템플릿은 아니고 정의 끝난 셰이프에 근거하는 세그먼트(segment)를 생성 한다. 셰이프는, 커멘드 및 싸인 포스트트랙의 생성에 사용되어 장식 패턴, 코드 진행, 및 코드 변경의 빈도의 선택을 제어한다.

세그먼트(segment)를 연주할 경우에, 파트의 연주에 사용하는 밴드를 제어할 수도 있다. 보통, 밴드는 스타일 및 템플릿의 일부로서 오쏘링 되지만, 어플리케이션이 동적으로 밴드 체인지를 실시할 수 있도록, 밴드를 개별의 파일로서 공급할 수도 있다. 그 경우,DirectMusicBand.CreateSegment 메소드를 사용해, 밴드만으로부터 되는 세컨드리 세그먼트(segment)를 생성 해, 음색이나 음색의 설정을 프라이머리 세그먼트(segment)에 할당할 때, 이 세컨드리 세그먼트(segment)를 연주해야 한다. 상세한 것에 대하여는, 「밴드의 사용법」을 참조할것.


재생중의 음악의 변화

DirectMusic 가 (단순한 MIDI 파일이나, MIDI 파일에 근거해 오쏘링 된 세그먼트(segment) 이외의) 세그먼트(segment)를 연주할 경우에, 연주가 같게 들리지 않게, 기본적인 화음과 리듬으로 변경이 더해진다. 변경의 일부는 스크립트화 되어 일부는 랜덤에 행해진다.

  • 패턴의 선택. 일반적으로, 1 개의 스타일에는 복수의 패턴이 포함된다. 이러한 패턴은, 커멘드 트랙으로부터의 커멘드에 응해 선택된다. 예를 들어, 커멘드 트랙이 브레이크 장식의 연주를 요구 하면, 스타일 재생 엔진은 현재의그루브 레벨에 모순되지 않는 브레이크 패턴을 선택한다 (작가는, 각 패턴에 어울린 그루브 레벨을 지정한다). 적절한 패턴이 몇개인가 있는 경우는, 어느쪽이든가 랜덤에 선택된다.
  • 패턴내의 바리에이션. 패턴내의 파트에는, 복수의 바리에이션을 설정할 수가 있다. 바리에이션은, 작가가 지정한 순서로 연주할 수가 있다. 그 이외의 경우는, 패턴의 각 반복에 대해, 스타일 재생 엔진이 바리에이션을 랜덤에 선택한다.
  • 그루브 레벨. 세그먼트(segment)의 현재의 그루브 레벨에 의해, 스타일내의 어느 패턴을 재생용으로 선택할 수 있을지가 정해진다. 현재의 레벨을 설정하는 것은 커멘드 트랙이지만, 커멘드 트랙은 보통, 세그먼트(segment)나 템플릿의 일부로서 오쏘링 된다. 세그먼트(segment)의 현재의 그루브 레벨은, 프로그램적으로 변경할 수가 있다. 퍼포먼스의 마스터 그루브 레벨을 설정하는 것으로, 변경을 모든 세그먼트(segment)에 적용할 수가 있다.
  • 전조. 세그먼트(segment)를 연주할 경우에, 근저에 있는 코드는 코드 트랙의 진행에 따라 변화한다. 현재의 패턴의 음표는, 새로운 코드와 조화를 이루도록, 자동적으로 전조 된다.
  • 타이밍의 바리에이션. 재생 엔진은, 각각의 음표의 파라미터, 즉 음표의 시작 시기와 종료시기에, 랜덤인 변경을 더할 수가 있다.
  • 밴드. 세그먼트(segment)의 연주중에, 음색과 음색의 설정 (볼륨, 팬, 및 전조)의 선택을, 오쏘링 된 세그먼트(segment)내의 밴드 트랙으로 변경하거나 어플리케이션으로 동적으로 변경할 수가 있다. 어플리케이션은, 밴드 오브젝트에 근거해 세컨드리 세그먼트(segment)를 생성 해, 생성 한 세그먼트(segment)를 연주하는 것으로, 밴드를 변경할 수가 있다.

어플리케이션은 대부분의 경우, 기존의 세그먼트(segment)를 조작하는 것이 아니라, 다른 세그먼트(segment)를 연주해 음악 전체를 제어한다. 예를 들어, 게임의 인텐시티의 변화를 음악에 반영시키려면 , 인텐시티레벨에 응해 오쏘링 된 새로운 세그먼트(segment)로 이행하는 것만으로 좋다. 작가에게 그루브 범위가 다른 패턴을 생성시켜, 게임 이벤트에 응해 그루브 레벨을 변경 하면, 1 개의 스타일 베이스의 세그먼트(segment)에서도 같은 이펙트를 얻을 수 있다.

실행시로 음악을 변경하는 방법에 대해서는, 「뮤직 파라미터」를 참조할것.


뮤직값과 MIDI 음표

DirectMusic 스타일내의 패턴의 음표는, 고정된 음표는 아니다. 이러한 음표는, 현재의 연주 모드와 서브 코드 레벨에 응해 현재의 코드에 전조 되었을 때에만 실제의 음표가 되는, 뮤직값이다.

뮤직값은, 음표의 의도적인 역할을 나타내는 것이다. 예를 들어, 뮤직값으로, 음표를 코드의 2 번째의 위치, 1 개(살) 위에의 스케일로 연주하도록(듯이) 지정할 수가 있다. 이 뮤직값이 특정의 코드에 적용되면(자), 그 코드의 2 번째로, 1 개(살) 위에의 스케일의 적절한 MIDI 음표에 변환된다.

[C++]

뮤직값의 데이터 형식의 설명에 대해서는,DMUS_NOTE_PMSG 를 참조할것.

[Visual Basic]

뮤직값의 데이터 형식의 설명에 대해서는,DMUS_NOTE_PMSG 를 참조할것.

코드에 대해서 음표가 어떻게 해석될까는, 연주 모드에 따라서 다르다. 예를 들어, 모드가 DMUS_PLAYMODE_NORMALCHORD 의 경우, 음표는 코드의 루트음에 근거해, 코드와 스케일의 음정으로서 해석된다. 모드가 DMUS_PLAYMODE_FIXEDTOKEY 의 경우, 음표는 선형인 값으로서 해석된다.

[Visual Basic]

각 연주 모드의 상세한 것에 대하여는,CONST_DMUS_PLAYMODE_FLAGS 를 참조할것.

서브 코드 레벨은 0 ~ 31 의 값으로, 뮤직값의 확립에 사용할 수 있는 서브 코드를 결정한다. DirectMusic 코드는 1 개 또는 복수의 서브 코드로 구성되어 복수의 평행 하는 코드 진행을 사용해 복잡한 화음이 가능해진다. 각 서브 코드는, 1 개(살) 또는 복수의 레벨을 지원 한다. 작가는, 각 서브 코드로 지원 되는 레벨을 정의한다.

세그먼트(segment)가 연주될 때, 각 음표는 DMUS_NOTE_PMSG 형에 캡슐화된다. 이 형태의 midiValue 멤버는, 보통, 신디사이저에 송신되는 MIDI 음표값을 보관 유지한다. 메세지에는, 전조로 사용되는 연주 모드와 서브 코드 레벨이나, 오리지날의 뮤직값도 보관 유지된다.

뮤직값과 연주 모드는, 주로 툴에 관련이 있지만, 이것들은 DirectX for Visual Basic 에서는 지원되어 있지 않다. DirectMusicPerformance.SendNotePMSG 를 사용해 음표를 퍼포먼스에 삽입하는 경우,DMUS_NOTE_PMSG 형으로 목적의 midiValue 를 지정해,musicValue,playModeFlags, 및 subChordLevel 멤버는 무시한다.

다음의 코드예에서는, 메세지를 송신해, 즉시 중간의 C 를 연주하고 있다.

' perf 는, DirectMusicPerformance 를 나타낸다.
Dim note As DMUS_NOTE_PMSG

note.midiValue = 60
note.mtDuration = 500
note.flags = DMUS_NOTEF_NOTEON
note.velocity = 127
Call perf.SendNotePMSG(0, DMUS_PMSGF_REFTIME, 1, note)
[C++]

각 연주 모드의 상세한 것에 대하여는,DMUS_PLAYMODE_FLAGS 를 참조할것.

서브 코드 레벨은 0 ~ 31 의 값으로, 뮤직값의 확립에 사용할 수 있는 서브 코드를 결정한다. DirectMusic 코드 (DMUS_CHORD_PARAM 또는 DMUS_CHORD_KEY 구조체로 나타내진다)는, 1 개(살) 또는 복수의 서브 코드로 구성되어 복수의 평행 하는 코드 진행을 사용해 복잡한 화음이 가능해진다. 각 서브 코드는, 1 개(살) 또는 복수의 레벨을 지원 해,DMUS_SUBCHORD 구조체의 dwLevels 멤버로 지정한다. 작가는, 각 서브 코드로 지원 되는 레벨을 정의한다.

세그먼트(segment)가 연주될 때, 각 음표는 DMUS_NOTE_PMSG 구조체에 캡슐화된다. 이 구조체의 bMidiValue 멤버는, 보통, 신디사이저에 송신되는 MIDI 음표값을 보관 유지한다. 메세지에는, 전조로 사용되는 연주 모드와 서브 코드 레벨이나, 오리지날 뮤직값도 보관 유지된다. 툴은 이 정보를 사용해, 음표를 자유롭게 변경할 수가 있다. 예를 들어, 툴은 특정의 연주 모드로 전조 되는 음표를 끼어들어 취득하거나 연주 모드를 변경할 수가 있다. 또,IDirectMusicPerformance::MusicToMIDI 메소드를 사용해 새로운 MIDI 음표를 취득하거나 메세지의 bMidiValue 멤버가 건네받기 전에 새로운 값을 설정할 수도 있다.

MusicToMIDI 메소드는, DirectMusic 의 스타일 재생 메카니즘의 중심이다. 이 메소드는 스타일 트랙에 의해 불려 가 코드 트랙의 현재의 코드를 사용해, 내부의 뮤직값을 음표로 변환한다.

툴로 처리를 반전시켜,별의 코드, 연주 모드, 또는 서브 코드 레벨을 사용해 MIDI 음표로부터 새로운 뮤직값을 취득하는 경우는,IDirectMusicPerformance::MIDIToMusic 메소드를 호출한다. 새로운 뮤직값은, 음표 메세지의 wMusicValue 멤버에 저장 되어 다른 어플리케이션 정의 툴로 이용할 수 있다. 다만, DirectMusic 출력 툴은 이것을 무시해, 보통 대로 bMidiValue 의 음표를 연주한다.


어레인지 요소의 사용법

여기서 설명하는 내용은, 뮤직 컴퍼넌트를 DirectMusic 어플리케이션에 짜넣기 위한 가이드이다. 각 컴퍼넌트의 목적과 오브젝트가 컴퍼넌트를 나타내는 방법에 대해 기본적으로 이해하고 있는 것을 상정하고 있다. 이러한 내용을 이해하려면 , 「작곡가 오브젝트와 인터페이스」 및 「뮤직 오쏘링의 개요」를 참조할것.

스타일, 코드 맵, 템플릿등의 각각의 컴퍼넌트를 조작하는 일 없이, 어플리케이션에 DirectMusic 를 짜넣을 수가 있다. 완전하게 오쏘링 된 세그먼트(segment)나, MIDI 파일을 처리할 수도 있다. 각각의 컴퍼넌트를 사용하면(자), 실행시에 퍼포먼스 전체를 보다 상세하게 제어할 수가 있다.

여기에서는, 다음의 항목을 채택한다.

  • 오쏘링 된 세그먼트(segment)의 사용법
  • 스타일의 사용법
  • 모티프의 사용법
  • 코드 맵의 사용법
  • 템플릿의 사용법
  • 이행부의 사용법


오쏘링 된 세그먼트(segment)의 사용법

오쏘링 된 세그먼트(segment)는, 음악의 부분의 데이터를 모두 포함한 파일 또는 리소스이다. 이 세그먼트(segment)는, MIDI 파일인가, 스타일 및 코드 맵에 근거해 생성 할 수가 있다. 단순한 MIDI 파일이나 리소스와 달리, 밴드 체인지나 바리에이션을 포함할 수가 있다.

주 : 같이 템플릿도 오쏘링 된 세그먼트(segment)이지만, 이것은 음악의 편입 부분을 나타내는 것은 아니다. 상세한 것에 대하여는, 「템플릿의 사용법」을 참조할것.

[C++]

다음의 코드예에 나타내도록(듯이), 세그먼트(segment)를 오브젝트로서 로드해,IDirectMusicSegment 인터페이스를 취득해, 어플리케이션으로 세그먼트(segment)를 생성 한다. 이 예에서는, 세그먼트(segment)는 DirectMusic Producer 파일로부터 로드 되고 있다.

/* pLoader 는 IDirectMusicLoader 인터페이스에의
유효한 포인터이며, 검색 디렉토리는
적절히 설정되어 있는 것으로 한다. */

DMUS_OBJECTDESC ObjectDescript;
IDirectMusicSegment* pSegment;

ObjectDescript.dwSize = sizeof(DMUS_OBJECTDESC);
ObjectDescript.idClass = CLSID_DirectMusicSegment;
strcpy(ObjectDescript.wszFileName, L"Dance.sgt");
ObjectDescript.dwValidData = DMOBJ_CLASS | DMOBJ_PATH ;
pLoader->GetObject(&ObjectDescript, IID_IDirectMusicSegment2,
    (void**) pSegment)))

이 결과,IDirectMusicPerformance::PlaySegment 메소드에 pSegment 를 건네줄 수 있다.

[Visual Basic]

다음의 코드예에 나타내도록(듯이),DirectMusicLoader.LoadSegment 또는DirectMusicLoader.LoadSegmentFromResource 메소드를 사용해, 어플리케이션으로 세그먼트(segment)를 생성 한다. 이 예에서는, 세그먼트(segment)는 DirectMusic Producer 파일로부터 로드 되고 있다.

' loader 는 DirectMusicLoader 오브젝트이다.
Dim seg As DirectMusicSegment
Set seg = loader.LoadSegment("Sample.sgt")

이 결과,DirectMusicPerformance.PlaySegment 메소드에 seg 를 건네줄 수 있다.


스타일의 사용법

DirectMusicStyle 오브젝트는, 음악 패턴의 모임을 나타낸다. 보통은, 장식과 모티프, 박자 기호, 템포, 및 밴드가 포함된다. 기본적인 리듬과 각 음색 파트에서 연주되는 음표가 정의된다.

DirectMusicStyle 오브젝트는, 스타일 파일이나 섹션 파일, 또는 리소스로부터 취득할 수 있다. 상세한 것에 대하여는, 「DirectMusic 로더」 및 「어레인지용의 뮤직 파일」을 참조할것.

스타일 단독으로는, 실행시에 뮤직 세그먼트(segment)를 생성 하는데 충분한 정보를 갖추지 않았다. 스타일 외에, 코드 맵 (코드 진행의 맵)과 연주시에그루브 레벨과 장식을 설정하는 커멘드 트랙의,2 개의 컴퍼넌트가 필요하다. 커멘드 트랙은 템플릿으로부터 꺼내는지, 실행시에 셰이프로부터 생성한다. 코드 맵은, 보통은 코드 맵 파일이나 리소스로부터 취득한다.

[C++]

템플릿에 근거해, 커멘드 트랙을 사용해 세그먼트(segment)를 생성 하려면 ,IDirectMusicComposer::ComposeSegmentFromTemplate 메소드를 호출한다 ( 「템플릿의 사용법」을 참조할것).

셰이프에 근거해 세그먼트(segment)를 생성 하려면 ,IDirectMusicComposer::ComposeSegmentFromShape 메소드를 호출한다. 스타일에의 포인터와 코드 맵에의 포인터, 및 생성 된 세그먼트(segment)에의 포인터를 받는 변수를 지정한다. 또, 코드 변경의 빈도를 제어하는 화음 진행의 레이트, 및 그루브 레벨과 장식의 진행을 결정하는 셰이프 정수도 지정한다.

[Visual Basic]

템플릿에 근거해, 커멘드 트랙을 사용해 세그먼트(segment)를 생성 하려면 ,DirectMusicComposer.ComposeSegmentFromTemplate 메소드를 호출한다 ( 「템플릿의 사용법」을 참조할것).

셰이프에 근거해 세그먼트(segment)를 생성 하려면 ,DirectMusicComposer.ComposeSegmentFromShape 메소드를 호출한다. 스타일과 코드 맵에의 포인터, 및 생성 된 세그먼트(segment)에의 포인터를 받는 변수를 지정한다. 또, 코드 변경의 빈도를 제어하는 화음 진행의 레이트, 및 그루브 레벨과 장식의 진행을 결정하는 셰이프 정수도 지정한다.


모티프의 사용법

모티프란, 보통은 인터랙티브 이벤트에 응해 연주되어서 , 기본적인 스타일 패턴상에서 연주되는 것을 의도한, 스타일내의 특종인 패턴이다. 모티프에는, 다른 패턴과 같은 복잡함을 줄 수가 있다. 또, 바리에이션이나 복수의 음색 파트를 갖추는 일도 가능하지만, 보통은 다양한 백그라운드 패턴과 조합해도 적절히 들리는, 짧은 단순한 음형이다. 커스텀 DLS 음색으로 연주하는 사운드 이펙트로도 된다.

[C++]

어느 모티프도 스타일의 일부로서 오쏘링 되므로, 스타일을 로드하자마자 모티프를 이용할 수 있다. 특정의 모티프를 재생할 수 있도록(듯이) 하려면 ,IDirectMusicStyle::GetMotif 메소드를 호출해, 다음의 파라미터를 건네준다.

  • 모티프명. 스타일에 관한 문서로부터 이 정보를 얻는지,IDirectMusicStyle::EnumMotif 메소드를 사용해 인덱스 번호로부터 취득할 수 있다.
  • 메소드가 생성 하는 세그먼트(segment) 오브젝트에의 IDirectMusicSegment 인터페이스를 받는 포인터.

다음의 코드예에서는,pwszMotifName 로 이름이 지정된 모티프를 취득해, 연주한다.

void PlayMotif(IDirectMusicPerformance* pPerf,
         IDirectMusicStyle* pStyle,
         WCHAR* pwszMotifName)
{
  IDirectMusicSegment* pSeg;

// 스타일로부터 모티프 세그먼트(segment)를 취득한다. GetMotif()는,
// 모티프를 찾아낼 수 없었던 경우는 S_FALSE 를 돌려주므로,
// S_OK 가 돌려주어지는 것을 확인한다.

  if (S_OK == pStyle->GetMotif(pwszMotifName, &pSeg))
  {
/* 세그먼트(segment)를 연주한다. DMUS_SEGF_BEAT 는, 현재 연주중의 세그먼트(segment)가
어느 경우에, 다음의 박을 연주하는 것을 의미한다. DMUS_SEGF_SECONDARY 는,
세그먼트(segment)를 세컨드리 세그먼트(segment)로서 연주하는 것을 의미한다.
세컨드리 세그먼트(segment)는, 현재 연주중의 프라이머리 세그먼트(segment)상에서 연주된다. 0 은,
곧바로 연주를 시작 하는 것을 의미한다. 마지막 NULL 는,
재생 상태를 추적할 필요가 없기 때문에,
마지막 파라미터에 IDirectMusicSegmentState* 를 돌려주지 않는 것을 의미한다. */

    pPerf->PlaySegment(pSeg,
                       DMUS_SEGF_BEAT | DMUS_SEGF_SECONDARY,
                       0,
                       NULL);
    pSeg->Release();
  }
}

보통, 모티프는 프라이머리 세그먼트(segment)에 거듭해 연주되기 (위해)때문에,pSeg 는 세컨드리 세그먼트(segment)로서 연주되는 점에 주의 해야 한다. 모티프에는 코드 트랙이나 밴드 트랙이 없기 때문에, 이것을 프라이머리 세그먼트(segment)로서 연주할 수 없다. 무음 상태 때에 모티프를 연주하는 경우는, 스타일로부터 공백의 패턴만을 포함한 프라이머리 세그먼트(segment)를 생성 해, 모티프를 연주하는 동안, 이 세그먼트(segment)를 연주해 둔다.

[Visual Basic]

어느 모티프도 스타일의 일부로서 오쏘링 되므로, 스타일을 로드하자마자 모티프를 이용할 수 있다. 특정의 모티프를 재생할 수 있도록(듯이) 하려면 ,IDirectMusicStyle::GetMotif 메소드를 호출해, 모티프의 이름을 건네준다. 이 정보는 스타일의 문서로 확인하는지,DirectMusicStyle.GetMotifName 메소드를 사용해 인덱스값으로부터 취득한다.

다음의 코드예에서는, 스타일의 최초의 모티프를 취득해 연주하고 있다.

' style 는 DirectMusicStyle 이다.
' perf 는 DirectMusicPerformance 이다.
Dim MotifName As String
Dim segMotif As DirectMusicSegment

MotifName = style.GetMotifName(0)
Set segMotif = style.GetMotif(MotifName)
Call perf.PlaySegment(segMotif, DMUS_SEGF_SECONDARY, 0)

보통, 모티프는 프라이머리 세그먼트(segment)에 거듭해 연주되기 (위해)때문에,segMotif 는 세컨드리 세그먼트(segment)로서 연주되는 점에 주의 해야 한다. 모티프에는 코드 트랙이나 밴드 트랙이 없기 때문에, 이것을 프라이머리 세그먼트(segment)로서 연주할 수 없다. 무음 상태 때에 모티프를 연주하는 경우는, 스타일로부터 공백의 패턴만을 포함한 프라이머리 세그먼트(segment)를 생성 해, 모티프를 연주하는 동안, 이 세그먼트(segment)를 연주해 둔다.


코드 맵의 사용법

코드 맵 오브젝트는, 기초가 되는 화음 구조와 음악의 분위기를 제공하는 코드의 콜렉션을 나타낸다. 코드 맵에는, 많은 관련하는 코드에 의한 몇개의 패스가 포함되어 작곡가 엔진이 음악의 부분의 코드 진행을 결정할 때에, 다양한 선택이 가능해진다.

오쏘링 된 세그먼트(segment)의 경우, 보통, 어플리케이션은 코드 맵에 관여할 필요는 없다. 코드 맵은, 고정 코드 진행을 생성 하기 위해서, 오쏘링의 단계에서 사용된다. 다만, 코드 맵을 사용해, 실행시에 세그먼트(segment)를 생성 하거나 기존의 세그먼트(segment)의 코드 진행을 변경할 수도 있다.

DirectMusicChordMap 오브젝트는, 코드 맵 파일이나 리소스로부터 취득한다. 상세한 것에 대하여는, 「DirectMusic 로더」 및 「어레인지용의 뮤직 파일」을 참조할것.

[C++]

스타일의 일부로서 코드 맵을 오쏘링 했을 경우는,IDirectMusicStyle::GetChordMap 메소드에 (작가가 할당한) 코드 맵의 이름을 건네주어,IDirectMusicChordMap 인터페이스에의 포인터를 취득할 수가 있다. IDirectMusicStyle::EnumChordMap 메소드를 사용해, 특정의 코드 맵을 검색할 수도 있다. 또,IDirectMusicStyle::GetDefaultChordMap 메소드를 사용해, 스타일의 디폴트 코드 맵에의 포인터를 취득할 수도 있다.

주 : DirectMusic Producer 에서는, 스타일 파일에의 코드 맵의 오쏘링은 지원되어 있지 않다.

IDirectMusicComposer::ComposeSegmentFromTemplate 또는 IDirectMusicComposer::ComposeSegmentFromShape 메소드를 사용해 세그먼트(segment)를 생성 할 경우에, 어레인지용의 코드 맵을 설정한다. 상세한 것에 대하여는, 「스타일의 사용법」을 참조할것.

세그먼트(segment)를 생성 한 다음에,IDirectMusicComposer::ChangeChordMap 메소드를 호출해, 언제라도 코드 맵을 변경할 수 있다. 이것에 의해, 기본적인 리듬이나 멜로디를 바꾸는 일 없이, 음악의 분위기가 변경된다.

각 코드 맵은, 24 의 음정으로부터 완성되는 기조의 스케일을 가진다. IDirectMusicChordMap::GetScale 메소드를 사용해, 스케일의 음정을 결정할 수가 있다. 이 메소드의 pdwScale 파라미터로 나타나는 변수의 하위 24 비트는, 대응하는 음정이 스케일의 일부가 되어 있는지 어떤지에 응해 세트 또는 소거된다. 상위 8 비트는, 스케일의 루트음을, 0 ~ 23 의 범위 (낮은 C 로부터 중간의 B)의 정수로 설정한다.

[Visual Basic]

DirectMusicComposer.ComposeSegmentFromTemplate 또는 DirectMusicComposer.ComposeSegmentFromShape 를 사용해 세그먼트(segment)를 생성 할 경우에, 어레인지용의 코드 맵을 설정한다. 상세한 것에 대하여는, 「스타일의 사용법」을 참조할것.

세그먼트(segment)를 생성 한 다음에,DirectMusicComposer.ChangeChordMap 메소드를 호출해, 언제라도 코드 맵을 변경할 수 있다. 이것에 의해, 기본적인 리듬이나 멜로디를 바꾸는 일 없이, 음악의 분위기가 변경된다.


템플릿의 사용법

템플릿은, 연주 가능한 음악의 세그먼트(segment)를 실행시에 어레인지 할 경우에 사용할 수 있는, 특수한 세그먼트(segment)이다. 템플릿은, 세그먼트(segment)의 길이와 루프 포인트를 설정한다. 커멘드 트랙이 제공되어그루브 레벨의 변경이나, 장식 패턴의 선택이 제어된다. 또, 새로운 코드를 각각 어느 싸인 포스트그룹으로부터 취득하는지를 지정해, 세그먼트(segment)를 어레인지 할 경우에 코드 맵을 어떻게 사용할지도 지시한다.

[C++]

각 템플릿은 DirectMusicSegment 오브젝트에 의해 나타내진다.

템플릿을 취득하는 방법은 2 개 있다.

  • 템플릿 파일 또는 리소스로부터 템플릿을 취득한다. 이 파일을 DirectMusicObject 로서 로드해,IDirectMusicSegment 인터페이스의 쿼리를 실시한다. 상세한 것에 대하여는, 「DirectMusic 로더」를 참조할것.
  • IDirectMusicComposer::ComposeTemplateFromShape 메소드를 사용해, 셰이프로부터 템플릿을 생성 한다. 템플릿의 길이, 전체의 셰이프, 인트로와 엔드의 장식 패턴을 연주할지 어떨지, 및 엔딩의 길이를 선택한다. IDirectMusicSegment 인터페이스에의 포인터가 돌려주어진다.

템플릿 세그먼트(segment) 오브젝트를 취득한 후, 스타일이나 코드 맵에의 포인터와 함께, 그 오브젝트를 IDirectMusicComposer::ComposeSegmentFromTemplate 메소드에 건네줄 수 있다. 또, 코드 변경의 빈도를 설정하는 화음 진행도 지정한다. ComposeSegmentFromTemplate 메소드는 세그먼트(segment)를 생성 해, 그 IDirectMusicSegment 인터페이스에의 포인터를,ppSectionSeg 파라미터로 지정된 주소에 돌려준다. 다음에, 이 포인터를 IDirectMusicPerformance::PlaySegment 메소드에 건네준다.

[Visual Basic]

각 템플릿은DirectMusicSegment 오브젝트에 의해 나타내진다.

템플릿을 취득하는 방법은 2 개 있다.

  • DirectMusicLoader.LoadSegment 또는 DirectMusicLoader.LoadSegmentFromResource 를 사용해, 템플릿 파일 또는 리소스로부터 취득한다.
  • DirectMusicComposer.ComposeTemplateFromShape 메소드를 사용해, 셰이프로부터 템플릿을 생성 한다. 템플릿의 길이, 전체의 셰이프, 인트로와 엔드의 장식 패턴을 연주할지 어떨지, 및 엔딩의 길이를 선택한다.

템플릿 세그먼트(segment) 오브젝트를 취득한 후, 스타일이나 코드 맵에의 포인터와 함께, 그 오브젝트를 DirectMusicComposer.ComposeSegmentFromTemplate 메소드에 건네줄 수 있다. 또, 코드 변경의 빈도를 설정하는 화음 진행도 지정한다. ComposeSegmentFromTemplate 메소드는,DirectMusicPerformance.PlaySegment 메소드에 건네줄 수 있는 세그먼트(segment)를 생성 한다.


이행부의 사용법

어느 세그먼트(segment)를 정지해 다음의 세그먼트(segment)를 시작할 때에, 귀에 거슬리는 소리인 중단이 돌연 발생하는 것을 방지하기 위해(때문에), 또는 음악을 종지형 (카덴트)에 이행 하기 위해서, 적절한 이행부를 제공하는 중간 또는 시종의 세그먼트(segment)를 생성 하도록(듯이) 작곡가에게 지시할 수 있다.

[C++]

이행부 세그먼트(segment)의 생성에는, 다음의 2 개의 메소드를 사용한다.

  • IDirectMusicComposer::AutoTransition 메소드는, 퍼포먼스에의 포인터를 받아, 현재 연주중의 세그먼트(segment)로부터 개발자가 지정한 2 번째의 세그먼트(segment)에의 이행부를 생성 한다. 계속되어, 재생의 목적으로 이행부 세그먼트(segment)와 2 번째의 세그먼트(segment)를 자동적으로 삽입해, 이것들 양쪽 모두의 세그먼트(segment)에의 IDirectMusicSegmentState 인터페이스를 돌려준다. 이행부의 연주는, 즉시, 또는 dwFlags 파라미터로 지정된 다음의 경계로부터 시작 된다. 옵션으로, 2 번째의 세그먼트(segment)를 NULL 에도 할 수 있지만, 그 경우는 이행부를 거쳐 무음에 이른다.
  • IDirectMusicComposer::ComposeTransition 메소드는, 1 번째의 세그먼트(segment)의 임의의 장소로부터 2 번째의 세그먼트(segment)의 선두 또는 무음에 이르는 이행부를 생성 해, 어플리케이션이 이행부를 연주할 수 있도록(듯이) IDirectMusicSegment 인터페이스에의 포인터를 돌려준다.

어느 쪽의 메소드도 파라미터로서 코드 맵, 커멘드, 및 일련의 플래그를 받는다.

  • 코드 맵은, 보통 대로, 세그먼트(segment)의 코드 진행을 정의하는 코드 트랙을 생성 하기 위해서 사용된다.
  • 커멘드로서DMUS_COMMANDT_TYPES 열거형의 어느쪽이든을 지정한다. 커멘드는, 이행부 세그먼트(segment)의 커멘드 트랙으로 요구하는 패턴의 타입으로서 보통의 그루브 패턴과 장식의 어느 쪽을 사용할까를 결정한다. 세그먼트(segment)를 연주할 때에, 스타일로부터 적절한 패턴이 선택된다.
  • DMUS_COMPOSEF_FLAGS 로부터 플래그를 선택해, 이행부의 상세, 특히 그 타이밍을 정의한다. DMUS_COMPOSEF_MODULATE 플래그를 사용해, 이행부를 있는 조성으로부터 다른 조성에 원활히 이행 시킨다. 2 번째의 세그먼트(segment)가 없는 경우, 무음에의 변조는 불가능해서, 이 플래그는 이용할 수 없다.
[Visual Basic]

이행부 세그먼트(segment)의 생성에는, 다음의 2 개의 메소드를 사용한다.

  • DirectMusicComposer.AutoTransition 메소드는,DirectMusicPerformance 를 받아, 현재 연주중의 세그먼트(segment)로부터 개발자가 지정한 2 번째의 세그먼트(segment)에의 이행부를 생성 한다. 계속되어, 재생의 목적으로 이행부 세그먼트(segment)와 2 번째의 세그먼트(segment)를 자동적으로 삽입한다. 이행부의 연주는, 즉시, 또는 IFlags 파라미터로 지정된 다음의 경계로부터 시작 된다. 옵션으로, 2 번째의 세그먼트(segment)를 Nothing 에도 할 수 있지만, 그 경우는 이행부를 거쳐 무음에 이른다.
  • DirectMusicComposer.ComposeTransition 메소드는, 1 번째의 세그먼트(segment)의 임의의 장소로부터 2 번째의 세그먼트(segment)의 선두 또는 무음에 이르는 이행부를 생성 해, 어플리케이션이 이행을 연주할 수 있도록(듯이) DirectMusicSegment 오브젝트를 돌려준다.

어느 쪽의 메소드도 파라미터로서 코드 맵, 커멘드, 및 일련의 플래그를 받는다.

  • 코드 맵은, 보통 대로, 세그먼트(segment)의 코드 진행을 정의하는 코드 트랙을 생성 하기 위해서 사용된다.
  • 커멘드로서CONST_DMUS_COMMANDT_TYPES 열거형의 어느쪽이든을 지정한다. 커멘드는, 이행부 세그먼트(segment)의 커멘드 트랙으로 요구하는 패턴의 타입으로서 보통의 그루브 패턴과 장식의 어느 쪽을 사용할까를 결정한다. 세그먼트(segment)를 연주할 때에, 스타일로부터 적절한 패턴이 선택된다.
  • CONST_DMUS_COMPOSEF_FLAGS 로부터 플래그를 선택해, 이행부의 상세, 특히 그 타이밍을 정의한다. DMUS_COMPOSEF_MODULATE 플래그를 사용해, 이행부를 있는 조성으로부터 다른 조성에 원활히 이행 시킨다. 2 번째의 세그먼트(segment)가 없는 경우, 무음에의 변조는 불가능해서, 이 플래그는 이용할 수 없다.

이행부의 길이는, 보통 1 소절이다. 다만, DMUS_COMPOSEF_LONG 플래그가 포함되는 경우, 및 커멘드가 DMUS_COMMANDT_END 로, 스타일내의 엔드 장식이 1 소절보다 긴 경우는 예외이다.


DirectMusic 튜토리얼

여기에서는, Microsoft® DirectMusic® 의 기본적인 기능을 이행 하는 방법에 대해 스텝바이스텝으로 설명하는 튜토리얼을 제공한다.

  • DirectMusic C/C++ 튜토리얼
  • DirectMusic Visual Basic 튜토리얼


DirectMusic C/C++ 튜토리얼

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

여기에서는, 다음의 튜토리얼을 사용해, C 또는 C++ 어플리케이션에 DirectMusic 를 이행 하는 방법을 설명한다.

  • 튜토리얼 1 : MIDI 파일의 연주
  • 튜토리얼 2 : 툴의 사용법
  • 튜토리얼 3 : 어레인지의 방법


튜토리얼 1 : MIDI 파일의 연주

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

이 튜토리얼은, 프라이머리 세그먼트(segment)를 연주할 뿐(만큼)의, 가장 간단한 DirectMusic 어플리케이션을 설정하기 위한 가이드이다. 이 예에서는, 세그먼트(segment)는 1 개의 MIDI 파일을 나타내고 있지만, 소스가 DirectMusic Producer 등의 툴로 오쏘링 된 1 개의 세그먼트(segment)인 경우도, 데이터의 로드와 연주의 프로세스는 완전히 같다.

이 튜토리얼은, 다음의 스텝으로 구성되어 있다.

  • 스텝 1 : COM 의 초기화
  • 스텝 2 : 퍼포먼스의 생성
  • 스텝 3 : 로더의 생성
  • 스텝 4 : MIDI 파일의 로드
  • 스텝 5 : MIDI 파일의 연주
  • 스텝 6 : DirectMusic 의 슛다운


스텝 1 : COM 의 초기화

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

DirectMusic 의 어떠한 호출을 실시하기 전에, 다음의 방법으로 COM 를 초기화해야 한다.

if (FAILED(CoInitialize(NULL)))
{
// 어플리케이션을 종료한다.
}   // 성공하면(자) 다음에 진행된다.

다음 방향 : 스텝 2 : 퍼포먼스의 생성


스텝 2 : 퍼포먼스의 생성

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

어느 DirectMusic 어플리케이션에서도 중심이 되는 오브젝트는 퍼포먼스이며, 세그먼트(segment)의 재생을 관리한다. 다음의 샘플 함수와 같이, COM 의 CoCreateInstance 함수를 사용해 퍼포먼스를 생성 한다.

IDirectMusicPerformance* CreatePerformance(void)
{
    IDirectMusicPerformance* pPerf;

    if (FAILED(CoCreateInstance(
            CLSID_DirectMusicPerformance,
            NULL,
            CLSCTX_INPROC,
            IID_IDirectMusicPerformance2,
            (void**) &pPerf
        )))
    {
        pPerf = NULL;
    }
    return pPerf;
}

이 함수를 사용해 글로벌 퍼포먼스 포인터를 초기화해, 후의 스텝에서 이용할 수 있다.

IDirectMusicPerformance* g_pPerf = CreatePerformance();
if (g_pPerf == NULL)
{
    // 실패. 퍼포먼스는 생성되어 있지 않다.
}

생성 한 퍼포먼스는,IDirectMusicPerformance::Init 메소드를 호출해 초기화할 필요가 있다. 메소드는 DirectMusic 오브젝트를 생성 해, 디폴트 포트를 관리한다. IDirectMusic 의 메소드에 직접 액세스 할 필요는 없기 때문에, 포인터를 취득할 필요없다. 따라서,Init 의 최초의 파라미터에는 NULL 를 건네준다. 또,IDirectSound 의 포인터 및 윈도우 핸들로서 NULL 를 건네주면(자), DirectMusic 는 DirectSound 오브젝트를 생성 해, 협조 레벨을 설정할 경우에 현재의 포커스 윈도우를 건네준다.

if (FAILED(g_pPerf->Init(NULL, NULL, NULL)))
{
    // 실패. 퍼포먼스는 초기화되어 있지 않다.
};

퍼포먼스를 생성 한 다음에, 초기화를 실시해, 포트를 추가할 필요가 있다. NULL 파라미터를 건네주어 IDirectMusicPerformance::AddPort 메소드를 호출하면, 자동적으로 1 개의 채널 그룹과 함께 디폴트 포트 (보통은 Microsoft Software Synthesizer)가 추가되어 그 그룹의 MIDI 채널에 P 채널 0-15 을 할당할 수 있다.

if (FAILED(pPerf->AddPort(NULL)))
{
// 실패. 포트는 초기화되어 있지 않다.
}

다음 방향 : 스텝 3 : 로더의 생성


스텝 3 : 로더의 생성

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

디스크로부터 무엇인가 오브젝트를 로드하려면 , 최초로 DirectMusicLoader 오브젝트를 생성 할 필요가 있다. 다음의 샘플 함수로 가리키는 대로, 다른 COM 오브젝트를 생성 하는 경우와 같다.

IDirectMusicLoader* CreateLoader(void)
{
    IDirectMusicLoader* pLoader;

    if (FAILED(CoCreateInstance(
            CLSID_DirectMusicLoader,
            NULL,
            CLSCTX_INPROC,
            IID_IDirectMusicLoader,
            (void**) &pLoader
        )))
    {
        pLoader = NULL;
    }
    return pLoader;
}

글로벌 변수의 초기화에, 이 함수를 사용한다.

IDirectMusicLoader* g_pLoader = CreateLoader();
if (g_pLoader == NULL)
{
    // 실패. 로더는 생성되어 있지 않다.
}

다음 방향 : 스텝 4 : MIDI 파일의 로드


스텝 4 : MIDI 파일의 로드

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

이 스텝에서는, 함수 LoadMIDISegment 를 이행 한다. 이 함수는 전의 스텝에서 생성 한 IDirectMusicLoader 에의 포인터를 취득해, 그 포인터를 사용해, MIDI 파일로부터 데이터를 캡슐화한 세그먼트(segment) 오브젝트를 생성 한다.

IDirectMusicSegment* LoadMIDISegment(IDirectMusicLoader* pLoader,
        WCHAR wszMidiFileName )
{
    DMUS_OBJECTDESC ObjDesc;
    IDirectMusicSegment* pSegment = NULL;

연주하는 MIDI 파일은 모두, 현재의 작업 디렉토리에 보존되고 있다고 한다. 검색 디렉토리를 설정해, 로더에 디렉토리를 지시할 필요가 있다 (검색 디렉토리를 다른 장소로 변경하지 않는 경우, 이 조작이 필요한 것은 1 번 뿐이다. 파일을 로드할 때 마다 지정할 필요는 없다).

    char szDir[_MAX_PATH];
    WCHAR wszDir[_MAX_PATH];

    if(_getcwd( szDir, _MAX_PATH ) == NULL)
    {
        return NULL;
    }

/*
다음의 매크로를 사용해, 멀티 바이트 포맷화등 Unicode 로 변환한다.
#define MULTI_TO_WIDE( x, y )  MultiByteToWideChar( CP_ACP, \
MB_PRECOMPOSED, y, -1, x, _MAX_PATH );
*/

    MULTI_TO_WIDE(wszDir, szDir);
    HRESULT hr = pLoader->SetSearchDirectory(GUID_DirectMusicAllTypes,
        wszDir, FALSE);
    if (FAILED(hr))
    {
        return NULL;
    }

다음에 DMUS_OBJECTDESC 구조체로, 로드하는 오브젝트를 기술한다.

    ObjDesc.guidClass = CLSID_DirectMusicSegment;
    ObjDesc.dwSize = sizeof(DMUS_OBJECTDESC);
    wcscpy( ObjDesc.wszFileName, wszMidiFileName );
    ObjDesc.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_FILENAME;

여기서, 오브젝트를 로드해,IDirectMusicSegment 인터페이스의 쿼리를 실시한다. 이 조작은,IDirectMusicLoader::GetObject 를 한 번 호출하는 것으로 실행된다. 오브젝트를 로드하면(자), 트랙이 초기화되어 MIDI 데이터의 재생을 준비하기 위해서 필요한 모든 작업을 하는 점에 주의 해야 한다.

pLoader->GetObject(&ObjDesc,
IID_IDirectMusicSegment2, (void**) &pSegment);

세그먼트(segment)를 스탠다드 MIDI 파일로서 연주하려면 , 여기서 밴드 트랙에 파라미터를 설정할 필요가 있다. dwGroupBits 메소드 파라미터에 -1 (또는, 0xFFFFFFFF)를 건네주어,IDirectMusicSegment::SetParam 메소드를 사용해 트랙을 검색한다.

g_pMIDISeg->SetParam(GUID_StandardMIDIFile,
-1, 0, 0, (void*) g_pPerf);

DirectMusic 가 프로그램 변경 및 뱅크 선택을 처리하는 방법은, 스탠다드 MIDI 파일의 경우와 DirectMusic 용으로 오쏘링 된 MIDI 컨텐츠의 경우에서는 다르기 (위해)때문에, 이 스텝이 필요하다. GUID_StandardMIDIFile 파라미터는, 음색을 다운로드하기 전으로 설정해야 한다.

다음의 스텝은, 음색의 다운로드이다. 디폴트의 소프트웨어 신디사이저는, General MIDI 음색 세트의 DLS 데이터를 필요로 하기 (위해)때문에, 단순한 MIDI 파일을 연주하는 경우에서도, 이 스텝이 필요하다. 이 스텝을 생략 하면, MIDI 파일을 연주해도 무음이 된다. GUID_Download 파라미터를 지정하기 위해서, 한번 더 세그먼트(segment)로 SetParam 를 호출한다.

g_pMIDISeg->SetParam(GUID_Download, -1, 0, 0, (void*) g_pPerf);

LoadMIDISegment 함수로 이미 이 조작이 완료하고 있는 경우에서도, 다운로드의 요구에 의한 실제 손해는 없는 점에 주의 해야 한다. 여분의 요구는 단지 무시된다. 최종적으로는 음색을 언로드해야 하지만, DirectMusic 를 슛다운 할 준비를 할 수 있을 때까지 대기할 수가 있다.

여기서, 함수는 연주 준비를 할 수 있던 세그먼트(segment)에의 포인터를 돌려준다.

    return pSegment;

} // LoadSegment()의 마지막

새로운 세그먼트(segment)를 로드하기 전에, 기존의 세그먼트(segment)를 클린 업 한다. 계속되어, LoadMIDISegment 함수에 파일명을 건네준다.

if (g_pMIDIseg)
{
    g_pMIDIseg->Release();
    g_pMIDIseg = NULL;
}

if (g_pLoader)
{
    IDirectMusicSegment* g_pMIDIseg = LoadMIDISegment(g_pLoader,
            L"tune.mid");
}

다음 방향 : 스텝 5 : MIDI 파일의 연주


스텝 5 : MIDI 파일의 연주

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

지금까지의 스텝에서, 준비작업은 모두 완료하고 있다. 음악의 연주 자체는 간단하다.

IDirectMusicSegmentState* g_pSegState;
if (g_pMIdiSEG)
{
    g_pPerf->PlaySegment(g_pMIDISeg, 0, 0, &g_pSegState);
}

IDirectMusicPerformance::PlaySegment 를 호출할 때에, 이하의 파라미터를 사용한다.

  • 전의 스텝에서 생성 한 세그먼트(segment).
  • 일련의 타이밍 플래그와 시작 타임 (다만, 여기에서는 즉석에서 세그먼트(segment)를 연주할 뿐(만큼)이므로 필요없다).
  • 세그먼트(segment) 상태 오브젝트에의 포인터의 주소. 돌려주어진 포인터를 사용해, 세그먼트(segment)에 관한 정보를 꺼낼 수 있다. 세그먼트(segment) 상태가 필요없는 경우, 이 파라미터를 NULL 로 할 수 있다.

파일을 여러 차례 재생하고 싶은 경우,PlaySegment 를 호출하기 전에 IDirectMusicSegment::SetRepeats 메소드를 호출하지 않으면 안 된다.

음악이 마지막에 도달하기 전, 또는 리피트가 끝나기 전에 재생을 정지하려면 ,IDirectMusicPerformance::Stop 메소드를 사용한다. 이 메소드를 사용하는 가장 단순한 방법은, 다음과 같이, 현재 연주중 및 연주의 목적으로 큐에 두어져 모든 음악을 즉석에서 정지하는 것이다.

g_pPerf->Stop(NULL, NULL, 0, 0)

대신에, 현재의 세그먼트(segment)에의 포인터 또는 세그먼트(segment) 상태에의 포인터를 지정해, 다만 1 개의 세그먼트(segment), 또는 세그먼트(segment)의 1 개의 인스턴스를 정지할 수도 있다.

다음 방향 : 스텝 6 : DirectMusic 의 슛다운


스텝 6 : DirectMusic 의 슛다운

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

종료하기 전에, 프로그램은 음색의 언로드, 생성 한 모든 오브젝트의 릴리즈, 및 COM 의 참조의 해제를 실행해야 한다 (CoInitialize 의 호출 1 개(살)에 대해,CoUninitialize 의 호출 1 개(살)을 대응시키지 않으면 안 되는 점에 주의 해야 한다).

필요한 클린 업을 실행하려면 , 다음의 함수를 사용한다.

HRESULT FreeDirectMusic()
{
// 연주중의 음악이 있는 경우는, 연주를 중지한다. 실제로는,
// 음색을 언로드 하면 와, 또는
// 퍼포먼스를 클로우즈 할 경우에 음악은 정지하므로,
// 이 처리는 반드시 필요하지 않다.
g_pPerf->Stop( NULL, NULL, 0, 0 );

// 음색을 언로드한다. 이것에 의해, 무음이 된다.
// CloseDown 는 모든 음색을 언로드한다.
// 따라서, 이 호출은 필요하다.
g_pMIDISeg->SetParam(GUID_Unload, -1, 0, 0, (void*) g_pPerf);

// 세그먼트(segment)를 릴리즈 한다.
g_pMIDISeg->Release();

// 퍼포먼스 오브젝트를 클로우즈 해, 릴리즈 한다.
g_pPerf->CloseDown();
g_pPerf->Release();

// 로더 오브젝트를 릴리즈 한다.
g_pLoader->Release();

// COM 를 릴리즈 한다.
CoUninitialize();

return S_OK;
}


튜토리얼 2 : 툴의 사용법

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

이 튜토리얼에서는, 툴을 C++의 클래스로서 이행 해, DirectMusic 어플리케이션으로 이용하는 방법을 나타낸다. CEchoTool 클래스를 사용하면(자), 어플리케이션은 퍼포먼스내의 모든 음표에 1 개 또는 복수의 메아리를 추가할 수 있다.

이하의 샘플 코드는, DirectX 에 부속의 샘플 어플리케이션 Echotool 에 근거하고 있다.

이 튜토리얼은, 이하의 스텝으로 구성되어 있다.

  • 스텝 1 : 툴 클래스의 선언
  • 스텝 2 : IUnknown 메소드의 정의
  • 스텝 3 : 메세지 타입의 지정
  • 스텝 4 : ProcessPMsg 메소드의 정의
  • 스텝 5 : 클래스 메소드의 정의
  • 스텝 6 : 퍼포먼스에의 툴의 추가


스텝 1 : 툴 클래스의 선언

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

DirectMusic 의 툴을 C++로 생성 하는 최초의 스텝은,IDirectMusicTool 의 상속 클래스를 선언하는 것이다.

여기에 샘플의 CEchoTool 클래스의 선언을 나타낸다.

class CEchoTool : public IDirectMusicTool
{
public:
  CEchoTool();
  ~CEchoTool();

public:
// IUnknown
  virtual STDMETHODIMP QueryInterface(const IID &iid, void **ppv);
  virtual STDMETHODIMP_(ULONG) AddRef();
  virtual STDMETHODIMP_(ULONG) Release();

// IDirectMusicTool
  HRESULT STDMETHODCALLTYPE Init(
          IDirectMusicGraph* pGraph);
  HRESULT STDMETHODCALLTYPE GetMsgDeliveryType(
          DWORD* pdwDeliveryType);
  HRESULT STDMETHODCALLTYPE GetMediaTypeArraySize(
          DWORD* pdwNumElements);
  HRESULT STDMETHODCALLTYPE GetMediaTypes(
          DWORD** padwMediaTypes,
          DWORD dwNumElements);
  HRESULT STDMETHODCALLTYPE ProcessPMsg(
          IDirectMusicPerformance* pPerf,
          DMUS_PMSG* pDMUS_PMSG);
  HRESULT STDMETHODCALLTYPE Flush(
         IDirectMusicPerformance* pPerf,
         DMUS_PMSG* pDMUS_PMSG,
         REFERENCE_TIME rtTime);
private:
  long m_cRef;                // reference counter.
  DWORD m_dwEchoNum;          // 생성하는 메아리의 수.
  MUSIC_TIME m_mtDelay;       // 메아리간의 지연 시간
  CRITICAL_SECTION m_CrSec;   // SetEchoNum()와 SetDelay()
                              //   (을)를 thread 세이프로 한다.
public:
// 퍼블릭 클래스 메소드
  void SetEchoNum(DWORD);
  void SetDelay(MUSIC_TIME);
};

다음 방향 : 스텝 2 : IUnknown 메소드의 정의


스텝 2 : IUnknown 메소드의 정의

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

샘플의 CEchoTool 클래스의 계승 메소드 IUnknown 는 다음과 같이 이행 되고 있다.

STDMETHODIMP CEchoTool::QueryInterface(const IID &iid, void **ppv)
{
  if (iid == IID_IUnknown || iid == IID_IDirectMusicTool)
  {
    *ppv = static_cast<IDirectMusicTool*>(this);
  } else
  {
    *ppv = NULL;
    return E_NOINTERFACE;
  }

  reinterpret_cast<IUnknown*>(this) ->AddRef();
  return S_OK;
}

STDMETHODIMP_(ULONG) CEchoTool::AddRef()
{
    return InterlockedIncrement(&m_cRef);
}

STDMETHODIMP_(ULONG) CEchoTool::Release()
{
    if( 0 == InterlockedDecrement(&m_cRef) )
    {
        delete this;
        return 0;
    }
    return m_cRef;
}

다음 방향 : 스텝 3 : 메세지 타입의 지정


스텝 3 : 메세지 타입의 지정

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

CEchoTool 클래스에서는, 모든 IDirectMusicTool 메소드를 정의할 필요가 있다. 그러나 Init 나 Flush 내에서 작업을 실시할 필요는 없고, 이러한 메소드는 단순하게 E_NOTIMPL 를 돌려준다.

이하의 메소드를 사용해, 처리의 목적으로 이 툴에 건네주는 메세지를 지정한다.

  • GetMsgDeliveryType 는, 메세지를 툴에 건네주는 시기를 지정한다. 이용 가능하게 된 직후, 메세지에 스탬프 된 타임 정확히, 처리와 포트 버퍼에의 배치의 준비를 할 수 있었을 때, 를 선택할 수 있다. 이것들 3 종류의 「전달 타입」은, 각각 DMUS_PMSG 구조체의 dwFlags 멤버내의 DMUS_PMSGF_TOOL_IMMEDIATE, DMUS_PMSGF_TOOL_ATTIME, DMUS_PMSGF_TOOL_QUEUE 의 각 플래그로 나타내진다.
  • GetMediaTypes 는, 메세지의 내용에 근거해, 어느 타입의 메세지를 툴에 건네주어야할 것인가를 결정한다. CEchoTool 는 음표와 패치 체인지만을 처리하므로, MIDI 쇼트 메세지, 음표 메세지, 및 DirectMusic 패치 메세지만을 받아들인다. 이러한 메세지는,DMUS_PMSG 메세지 구조체의 DMUS_PMSGT_TYPES 열거형의 플래그에 의해 식별된다.
  • GetMediaTypeArraySize 는, 미디어 타입 배열내의 요소의 수를 돌려준다.

CEchoTool 는, 다음의 샘플 코드내에서 이러한 메소드를 이행 한다.

HRESULT STDMETHODCALLTYPE CEchoTool::GetMsgDeliveryType(
        DWORD* pdwDeliveryType )
{
// 이 툴은 메세지를 즉석에서 필요로 한다.
// 이것은 디폴트이며, E_NOTIMPL 를 돌려주면(자)
// 정상적으로 동작한다. 이제(벌써) 1 개의 방법은,
// *pdwDeliveryType 를 DMUS_PMSGF_TOOL_IMMEDIATE,
// DMUS_PMSGF_TOOL_QUEUE, 및 DMUS_PMSGF_TOOL_ATTIME 의
// 몇개의 전달 타입에 명확하게 설정하는 것이다.

    *pdwDeliveryType = DMUS_PMSGF_TOOL_IMMEDIATE;
  return S_OK;
}

HRESULT STDMETHODCALLTYPE CEchoTool::GetMediaTypeArraySize(
        DWORD* pdwNumElements)
{
  *pdwNumElements = 3;
  return S_OK;
}

HRESULT STDMETHODCALLTYPE CEchoTool::GetMediaTypes(
        DWORD** padwMediaTypes,
        DWORD dwNumElements)
{
  if (dwNumElements == 3)
  {
    (*padwMediaTypes)[0] = DMUS_PMSGT_NOTE;
    (*padwMediaTypes)[1] = DMUS_PMSGT_MIDI;
    (*padwMediaTypes)[2] = DMUS_PMSGT_PATCH;
    return S_OK;
  }
  else
  {
    // 이것은 결코 발생하지 않을 것이다.
    return E_FAIL;
  }
}

다음 방향 : 스텝 4 : ProcessPMsg 메소드의 정의


스텝 4 : ProcessPMsg 메소드의 정의

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

이 툴의 실제의 동작은,IDirectMusicTool::ProcessPMsg 로부터 파생한 메소드내에서 실행된다. IDirectMusicTool::GetMediaTypes 가 돌려주는 배열내에 열거된 타입의 모든 메세지는, 이 메소드를 요구한다.

CEchoTool::ProcessPMsg 메소드는, 최초로 로컬 변수의 어떠한 초기화를 실시한다.

HRESULT STDMETHODCALLTYPE CEchoTool::ProcessPMsg(
  IDirectMusicPerformance* pPerf,
  DMUS_PMSG* pMsg)
{
  DMUS_NOTE_PMSG* pNote;
  DWORD dwCount;
  DWORD dwEchoNum;
  MUSIC_TIME mtDelay;

// SetEchoNum()와 SetDelay()는 이러한 멤버 변수를 사용하므로,
// 크리티컬 섹션을 이용해 이것들을 thread 세이프로 한다.
  EnterCriticalSection(&m_CrSec);
  dwEchoNum = m_dwEchoNum;
  mtDelay = m_mtDelay;
  LeaveCriticalSection(&m_CrSec);

다음에 이 메소드는, 메세지에 대해서 IDirectMusicGraph::StampPMsg 메소드를 호출한다. 처리가 끝난 다음에 이 메세지를 다른 툴에 전송 해야 하는 경우,StampPMsg 는 성공한다 (DirectMusic 가 최종 출력 툴을 준비해 있기 (위해)때문에, 메세지의 목적지가 되는 어플리케이션 고유의 툴이 존재하지 않는 경우에서도,StampPMsg 는 성공할 것이다). 실패했을 경우, 메소드는 S_FREE 를 돌려주어, 메세지는 자동적으로 무시된다.

  if ((NULL == pMsg->pGraph) ||
    FAILED(pMsg->pGraph->StampPMsg(pMsg)))
  {
    return DMUS_S_FREE;
  }

여기에서는 CEchoTool 가 메세지를 처리한다. DMUS_PMSGT_NOTE, DMUS_PMSGT_MIDI, 또는 DMUS_PMSGT_PATCH 의 타입의 메세지만을 받도록(듯이) 설정되어 있는 점에 주의 해야 한다 (이러한 타입은 DMUS_PMSGT_TYPES 열거형의 일부이다).

연속하는 메아리를 생성 할 때마다, 툴은 이하를 실시한다.

  • IDirectMusicPerformance::AllocPMsg 메소드를 호출해, 새로운 메세지를 생성 한다.
  • 오리지날의 메세지의 DMUS_PMSG 구조체를 새로운 메세지에 카피해, COM 의 관리용으로 일부의 멤버를 갱신한다.
  • 새로운 메세지를 다른 퍼포먼스 채널에 할당한다.
  • 음표의 경우는, 각 메아리의 볼륨을 서서히 내린다.
  • 메세지의 연주 타임에 지연 시간을 추가한다.
  • IDirectMusicPerformance::SendPMsg 메소드를 호출해, 파이프라인에 새로운 메세지를 둔다. 이 메세지에 대해서 IDirectMusicGraph::StampPMsg 이 불려 가지 않기 때문에, 디폴트의 최종 출력 툴 이외의 툴에 전송 될 것은 없다.

MIDI 의 음표를 취급하는 샘플 코드를 나타낸다.

  if( pPMsg->dwType == DMUS_PMSGT_MIDI )
  {
    // MIDI 메세지를 메아리 채널에 카피한다.
    for( dwCount = 1; dwCount <= dwEchoNum; dwCount++ )
    {
      DMUS_MIDI_PMSG* pMidi;
      if( SUCCEEDED( pPerf->AllocPMsg( sizeof(DMUS_MIDI_PMSG),
        (DMUS_PMSG**) &pMidi )))
      {
        // 오리지날 메세지를 이 메세지에 카피한다.
        memcpy( pMidi, pPMsg, sizeof(DMUS_MIDI_PMSG) );

        // 오브젝트에의 포인터를 보관 유지 또는 보관 유지하고 있다
        // 가능성이 있는 필드의 Addref 나 소거를 실행한다.
        if( pMidi->pTool ) pMidi->pTool->AddRef();
        if( pMidi->pGraph ) pMidi->pGraph->AddRef();
        pMidi->punkUser = NULL;

        // 메세지가 다음의 상위 그룹에 이동하도록,
        // P 채널을 설정한다.
        pMidi->dwPChannel = pMidi->dwPChannel +
                (16*dwCount);

        // 메아리 되는 메세지의 시간에의 추가를 실시한다.
        pMidi->mtTime += (dwCount * mtDelay);

        // 메세지를 추가하므로, MUSIC_TIME 만이 유효하게 된다.
        // REFERENCE_TIME 는, SendPMsg()의 내부에서
        // 재계산된다.
        pMidi->dwFlags = DMUS_PMSGF_MUSICTIME;

        // 메세지를 송신한다.
        pPerf->SendPMsg( (DMUS_PMSG*) pMidi );
      }
    }
  }

패치 체인지도 카피되어 현재 사용되지 않은 것도 포함하고 다른 모든 메아리 채널에 송신된다. 그 때문에, 다음에 메아리를 추가했을 경우에서도, 올바른 음색에 의한 연주를 한다. 샘플의 EchoTool 어플리케이션에서는, Echotool.h 로 MAX_ECHOES 가 정의되고 있는 점에 주의 해야 한다.

  else if( pPMsg->dwType == DMUS_PMSGT_PATCH )
  {
    for( dwCount = 1; dwCount <= MAX_ECHOES; dwCount++ )
    {
      DMUS_PATCH_PMSG* pPatch;
      if( SUCCEEDED( pPerf->AllocPMsg( sizeof(DMUS_PATCH_PMSG),
        (DMUS_PMSG**) &pPatch )))
      {
        // 오리지날 메세지를 이 메세지에 카피한다.
        memcpy( pPatch, pPMsg, sizeof(DMUS_PATCH_PMSG) );

        // 오브젝트에의 포인터를 보관 유지 또는 보관 유지하고 있다
        // 가능성이 있는 필드의 Addref 나 소거를 실행한다.
        if( pPatch->pTool ) pPatch->pTool->AddRef();
        if( pPatch->pGraph ) pPatch->pGraph->AddRef();
        pPatch->punkUser = NULL;

        // 메세지가 다음의 상위 그룹에 이동하도록,
        // P 채널을 설정한다.
        pPatch->dwPChannel = pPatch->dwPChannel +
          (16*dwCount);

        // 메아리 되는 메세지의 시간에의 추가를 실시한다.
        pPatch->mtTime += (dwCount * mtDelay);

        // 메세지를 추가하므로, MUSIC_TIME 만이 유효하게 된다.
        // REFERENCE_TIME 는, SendPMsg()의 내부에서
        // 재계산된다.
        pPatch->dwFlags = DMUS_PMSGF_MUSICTIME;

        // 메세지를 송신한다.
        pPerf->SendPMsg( (DMUS_PMSG*) pPatch );
      }
    }
  }

이 메소드는, MIDI 의 음표와 같은 방법으로 음표를 취급하지만, 볼륨을 내리기 위한 스텝을 추가한다.

  else if( pPMsg->dwType == DMUS_PMSGT_NOTE )
  {
    // 다음의 음표의 velocity를 추적하기 위한 변수를 생성 한다.
    BYTE bVelocity;
    pNote = (DMUS_NOTE_PMSG*) pPMsg;
    bVelocity = pNote->bVelocity;

    for( dwCount = 1; dwCount <= dwEchoNum; dwCount++ )
    {
      if( SUCCEEDED( pPerf->AllocPMsg( sizeof(DMUS_NOTE_PMSG),
              (DMUS_PMSG**) &pNote )))
      {
        // 오리지날의 음표를 이 메세지에 카피한다.
        memcpy( pNote, pPMsg, sizeof(DMUS_NOTE_PMSG) );

        // 오브젝트에의 포인터를 보관 유지 또는 보관 유지하고 있다
        // 가능성이 있는 필드의 Addref 나 소거를 실행한다.
        if( pNote->pTool ) pNote->pTool->AddRef();
        if( pNote->pGraph ) pNote->pGraph->AddRef();
        pNote->punkUser = NULL;

        // 메아리 되는 메세지의 시간에의 추가를 실시한다.
        pNote->mtTime += (dwCount * mtDelay);

        // 메아리 된 음표의 볼륨을 내린다.
        bVelocity = (BYTE) (bVelocity -
                ((bVelocity * (dwCount * 15))/100));
        pNote->bVelocity = bVelocity;

        // 메세지를 추가하므로, MUSIC_TIME 만이 유효하게 된다.
        // REFERENCE_TIME 는, SendPMsg()의 내부에서
        // 재계산된다.
        pNote->dwFlags = DMUS_PMSGF_MUSICTIME;
        pNote->dwPChannel = pNote->dwPChannel +
          (16*dwCount);

        // 메세지를 송신한다.
        pPerf->SendPMsg( (DMUS_PMSG*) pNote );
      }
    }
  }

마지막으로, ProcessPMsg 메소드는 DMUS_S_REQUEUE 를 돌려주어, 오리지날 메세지는 파이프라인에 되돌려진다.

return DMUS_S_REQUEUE;
} // CEchoTool::ProcessPMsg()의 마지막

다음 방향 : 스텝 5 : 클래스 메소드의 정의


스텝 5 : 클래스 메소드의 정의

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

샘플의 CEchoTool 클래스에는, 계승된 IUnknown 와 IDirectMusicTool 메소드 외에, constructor　 　 과 소멸자, 및 메아리의 파라미터를 설정하기 위한 2 개의 퍼블릭 메소드가 있다. 이러한 메소드의 정의는, 이 튜토리얼과는 약간 관련이 얇지만, 완전을 기하기 위해서 여기서 설명한다.

CEchoTool::CEchoTool()
{
  m_cRef = 1;               // Release()는 이것을 릴리즈 한다.
  m_dwEchoNum = 3;          // 1 개의 음표에 대해 3 개의 메아리를 디폴트에.
  m_mtDelay = DMUSPPQ / 2;  // 8 번의 음표의 메아리.
  InitializeCriticalSection(&m_CrSec);
}

CEchoTool::~CEchoTool()
{
  DeleteCriticalSection(&m_CrSec);
}

void CEchoTool::SetEchoNum(DWORD dwEchoNum)
{
  // ProcessPMsg()은 m_dwEchoNum 를 사용하므로, 크리티컬
  // 섹션을 이용해 이 메소드를 thread 세이프로 한다.
  if( dwEchoNum <= MAX_ECHOES )
  {
    EnterCriticalSection(&m_CrSec);
    m_dwEchoNum = dwEchoNum;
    LeaveCriticalSection(&m_CrSec);
  }
}

void CEchoTool::SetDelay(MUSIC_TIME mtDelay)
{
  // ProcessPMsg()는 m_mtDelay 를 사용하므로, 크리티컬
  // 섹션을 이용해 이 메소드를 thread 세이프로 한다.
  EnterCriticalSection(&m_CrSec);
  m_mtDelay = mtDelay;
  LeaveCriticalSection(&m_CrSec);
}

다음 방향 : 스텝 6 : 퍼포먼스에의 툴의 추가


스텝 6 : 퍼포먼스에의 툴의 추가

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

CEchoTool 클래스를 정의한 후, 어플리케이션은 툴 오브젝트를 생성 해, 그래프에 삽입해, 퍼포먼스에 추가하므로, 파이프라인내의 적절한 메세지를 횡령할 수 있게 된다.

다음의 코드는 CEchoTool 클래스의 인스턴스를 생성 해, 툴이 생성 해야 할 메아리의 수를 초기화해, 툴을 보관 유지하는 그래프를 생성 해, 그 그래프를 퍼포먼스에 추가한다 (샘플 어플리케이션 EchoTool 에서는, 이 작업의 일부를 헬퍼-함수 AddTool 로 실행하고 있다. 여기에서는 추적을 용이하게 하기 위한(해), 코드로 변경을 더하고 있다).

/* pPerf 가, 퍼포먼스 오브젝트의 IDirectMusicPerformance
   인터페이스에의 유효한 포인터인 것을 상정하고 있다. */

CEchoTool         *pEchoTool;
IDirectMusicGraph* pGraph;

pEchoTool = new CEchoTool;
if (pEchoTool)
{
    pEchoTool->SetEchoNum(0);

    // 툴을 보관 유지하기 위해서 IDirectMusicGraph 오브젝트를 생성 한다.
    if (SUCCEEDED(CoCreateInstance(
            CLSID_DirectMusicGraph,
            NULL,
            CLSCTX_INPROC,
            IID_IDirectMusicGraph,
            (void**) &pGraph)))
    {
        // 툴을 그래프에 추가한다.
        if (SUCCEEDED(pGraph->InsertTool(
                (IDirectMusicTool*) pCEchoTool,
                NULL,   // 모든 P 채널에 적용한다.
                0,      // 다른 P 채널은 몇개 있을까.
                0)))    // 그래프내의 툴의 인덱스 번호.
        {
        // 그래프를 퍼포먼스에 추가한다. 이 결과, 참조
        // 카운트가 증가하므로, 오리지날의 그래프는 릴리즈
        // 할 수 있게 된다.
        pPerf->SetGraph(pGraph);
        }
        pGraph->Release();
    }
}

퍼포먼스내의 그래프의 설정에 의해, 모든 세그먼트(segment)내의 메세지는, 이 툴에 의해 처리될 기회를 얻는다. 대신에,IDirectMusicSegment::SetGraph 메소드를 사용해, 특정의 세그먼트(segment)에게만 툴을 적용할 수도 있다.


튜토리얼 3 : 어레인지의 방법

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

이 튜토리얼에서는, DirectMusic Producer 로 오쏘링 된 요소에 근거해 뮤직 퍼포먼스를 설정하는 방법과 음악을 인터랙티브에, 즉 프로그램 이벤트에 응해 연주하는 방법을 나타낸다.

샘플 코드는, DirectX SDK 의 DMDonuts 샘플 에 근거하고 있다. DMDonuts 는 대규모이고 복잡한 어플리케이션이므로, 여기에서는 주요한 요점만을 취급한다. DirectMusic 의 상세한 이행에 대해서는, 소스 파일 Donuts.cpp 와 그 부속 헤더 가운데, DMUSIC BEGIN 와 DMUSIC END 의 코멘트로 둘러싸여 있는 개소를 참조할것.

이 튜토리얼은, 이하의 스텝으로 구성되어 있다.

  • 스텝 1 : define 와 글로벌
  • 스텝 2 : 퍼포먼스의 초기화
  • 스텝 3 : 뮤직 요소의 로드
  • 스텝 4 : 통지의 설정
  • 스텝 5 : 프라이머리 세그먼트(segment)의 생성
  • 스텝 6 : 프라이머리 세그먼트(segment)의 연주
  • 스텝 7 : 별의 프라이머리 세그먼트(segment)에의 이행
  • 스텝 8 : 모티프의 연주
  • 스텝 9 : 통지의 처리
  • 스텝 10 : DirectMusic 의 슛다운


스텝 1 : define 와 글로벌

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

다음의 define 와 글로벌 변수는, Donuts.cpp 의 선두에서 선언되고 있다. 이 튜토리얼을 이용할 때의 참조용으로, 여기에 나타내 둔다.

BOOL          bMusicEnabled = TRUE;

// 다양한 정수
const  GUID guidZero =    {0};
#define MOTIF_BOUNCE       0
#define MOTIF_DEATH        1
#define MOTIF_SHIELD       2
#define MOTIF_BLOWUP       4
#define MOTIF_BLOWUPLITE   3
#define NUM_MOTIFS         5
#define NUM_STYLES         2
#define SEGMENT_1          0
#define SEGMENT_2          1
#define SEGMENT_TRANS_1    2
#define SEGMENT_TRANS_2    3
#define NUM_SEGMENTS       4
#define NUM_CHORDMAP       4
#define BLOWUPS_PER_BEAT   2
#define MEASURE_LENGTH     DMUS_PPQ * 4
// 파트수/사분 음표 * 사분 음표의 수/소절 (4/4 박자를 상정)

// 글로벌 인터페이스
IDirectMusicStyle*        gapStyle[NUM_STYLES];
IDirectMusicChordMap*     gapChordMap[NUM_STYLES] [NUM_CHORDMAP];
IDirectMusicSegment*      gapMotif[NUM_STYLES] [NUM_MOTIFS];
IDirectMusicSegment*      gapSegment[NUM_SEGMENTS] =
                          {NULL, NULL, NULL, NULL};
IDirectMusicComposer *    gpComposer = NULL;
IDirectMusicPerformance*  gpPerformance = NULL;
IDirectMusic*             gpDirectMusic = NULL;
IDirectMusicLoader*       gpLoader = NULL;
IDirectMusicSegment*      gpIntroTemplate = NULL;
IDirectMusicSegment*      gpGameTemplate = NULL;
IDirectMusicSegment*      gapShieldSegment[NUM_STYLES] = {NULL, NULL};
IDirectMusicSegment*      gapDefaultSegment[NUM_STYLES] =
                                  {NULL, NULL};
IDirectMusicBand*         gapShieldBand[NUM_STYLES] = {NULL, NULL};
IDirectMusicBand*         gapDefaultBand[NUM_STYLES] = {NULL, NULL};

// 글로벌 변수
BOOL        bAnyHits = FALSE;
int         gnCurrentStyle = 0;
int         gnCurrentChordMap = 0;
int         gnLastStyle = 0;
int         gnLastChordMap = 0;

BOOL        gbShieldsOn = FALSE;
static int  snLastTempo;
static int  snSubLevel;
static int  snMaxBlowUps = BLOWUPS_PER_BEAT;

다음 방향 : 스텝 2 : 퍼포먼스의 초기화


스텝 2 : 퍼포먼스의 초기화

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

Donuts.cpp 파일내의 InitializeGame 함수로 DirectMusic 퍼포먼스를 설정한다.

어플리케이션은 최초로 GetSearchPath 함수를 호출하는 것으로, 레지스트리에의 쿼리를 실시해, DirectX 의 샘플 뮤직 파일의 검색 패스를 취득한다. 그 후, 다음과 같이 작곡가용과 퍼포먼스용의 COM 오브젝트를 생성 한다.

CoInitialize(NULL);

if ( ! SUCCEEDED(::CoCreateInstance(
        CLSID_DirectMusicComposer,
        NULL,
        CLSCTX_INPROC,
        IID_IDirectMusicComposer,
        (void**) &gpComposer
)))
{
    return CleanupAndExit("Couldn't create a composer object");
}

if ( ! SUCCEEDED( CoCreateInstance( CLSID_DirectMusicPerformance,
        NULL,
        CLSCTX_INPROC,
        IID_IDirectMusicPerformance,
        (void**) &gpPerformance )))
{
    return CleanupAndExit("Couldn't create a performance object");
}

계속되어, 이 어플리케이션은 IDirectMusicPerformance::Init 를 호출해 퍼포먼스를 초기화한다. 이 메소드는, 포트의 생성과 액티브화를 실시하는 DirectMusic 오브젝트를 생성 한다. DirectSound 가 다른 사운드 이펙트에 사용되고 있는지 어떤지에 응해,lpDS 에 건네주어 퍼포먼스에 기존의 DirectSound 오브젝트를 Attach 하는지, NULL 를 건네주어 오브젝트를 생성 한다.

#ifdef USE_DSOUND
    if( ! SUCCEEDED(gpPerformance->Init(&gpDirectMusic,
           lpDS, hWndMain)))
    {
        return CleanupAndExit("Couldn't initialize the performance");
    }
#else
    if( ! SUCCEEDED(gpPerformance->Init(&gpDirectMusic,
            NULL, hWndMain)))
    {
        return CleanupAndExit("Couldn't initialize the performance");
    }
#endif

어플리케이션은 여기서 디폴트 포트를 취득해, 1 개의 채널 그룹에서 포트의 인스턴스를 생성 해, 그 능력을 취득한다.

IDirectMusicPort* pPort = NULL;
DMUS_PORTPARAMS dmos;
DMUS_PORTCAPS dmpc;
GUID guidSynthGUID;
HRESULT hr = S_OK;

if ( ! SUCCEEDED(gpDirectMusic->GetDefaultPort(&guidSynthGUID)))
{
    return CleanupAndExit("Could't GetDefaultPort on IDirectMusic");
}

ZeroMemory(&dmos, sizeof(dmos));
dmos.dwSize = sizeof(DMUS_PORTPARAMS);
dmos.dwChannelGroups = 1;
dmos.dwValidParams = DMUS_PORTPARAMS_CHANNELGROUPS;

if( ! SUCCEEDED(gpDirectMusic->CreatePort(guidSynthGUID,
            &dmos,
            &pPort,
            NULL)))
{
    return CleanupAndExit("Couldn't CreatePort on IDirectMusic");
}

ZeroMemory(&dmpc, sizeof(dmpc));
dmpc.dwSize = sizeof(DMUS_PORTCAPS);

if( ! SUCCEEDED(pPort->GetCaps(&dmpc)))
{
    if (pPort) pPort->Release();
    return CleanupAndExit("Couldn't GetCaps on IDirectMusicPort");
}

여기서, _SOFTWARE_SYNTH_ 가 정의되고 있는지 어떤지에 응해, 어플리케이션의 동작이 바뀐다. _SOFTWARE_SYNTH_ 가 정의되고 있는 경우, DLS 기능을 가지는 신디사이저가 요구되어 어플리케이션은 디폴트 포트로 DMUS_PC_DLS 능력 플래그를 확인한다. 플래그가 발견되지 않는 경우는, 디폴트 포트를 릴리즈 해, DMUS_PC_DLS 기능을 가지는 출력 포트가 발견될 때까지, 이용 가능한 포트를 계속 열거한다. 최종적으로, 발견된 포트의 인스턴스가 생성 된다.

if ((dmpc.dwClass ! = DMUS_PC_OUTPUTCLASS)
        || ! (dmpc.dwFlags & DMUS_PC_DLS))
{
    pPort->Release();
    pPort = NULL;
}

if (! pPort)
{
    for (DWORD index = 0; hr == S_OK; index++)
    {
        ZeroMemory(&dmpc, sizeof(dmpc));
        dmpc.dwSize = sizeof(DMUS_PORTCAPS);

        hr = gpDirectMusic->EnumPort(index, &dmpc);
        if(hr == S_OK)
        {
            if ( (dmpc.dwClass == DMUS_PC_OUTPUTCLASS) &&
                 (dmpc.dwFlags & DMUS_PC_DLS) )
            {
                CopyMemory(&guidSynthGUID, &dmpc.guidPort,
                        sizeof(GUID));

                ZeroMemory(&dmos, sizeof(dmos));
                dmos.dwSize = sizeof(DMUS_PORTPARAMS);
                dmos.dwChannelGroups = 1;
                dmos.dwValidParams = DMUS_PORTPARAMS_CHANNELGROUPS;

                hr = gpDirectMusic->CreatePort(guidSynthGUID,
                        &dmos, &pPort, NULL);
                break;
            }
        }
    }
    if (hr ! = S_OK)
    {
        if (pPort) pPort->Release();
        return CleanupAndExit("Couldn't initialize the Synth port");
    }
}

한편, _SOFTWARE_SYNTH_ 가 정의되어 있지 않은 경우는, 종래의 하드웨어 포트가 요구되어 어플리케이션은 MIDI 맵퍼가 발견될 때까지, 포트를 계속 열거한다 (여기에서는, 코드를 나타내지 않았다).

다음에, 이 포트를 액티브화해, 퍼포먼스에 부가한다.

pPort->Activate(TRUE);
gpPerformance->AddPort(pPort);

다음의 호출로, P 채널 0-15 이 이 포트 위에의 최초의 MIDI 채널 그룹에 맵 된다. 이 스텝은, 어플리케이션이 AddPort 에 NULL 를 건네주지 않기 위해(때문에) 필요한 점에 주의 해야 한다.

gpPerformance->AssignPChannelBlock(0, pPort, 1);

이 시점에서, 포트에의 오리지날 참조를 릴리즈 할 수 있다. 이 호출은, 퍼포먼스로부터 포트를 삭제할 것은 없다.

if (pPort) pPort->Release();

다음 방향 : 스텝 3 : 뮤직 요소의 로드


스텝 3 : 뮤직 요소의 로드

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것

[C++]

샘플 어플리케이션 DMDonuts 로 DirectMusic 의 기능을 설정하는 다음의 스텝은, 음악의 요소인 스타일, 템플릿, 모티프, 코드 맵, 밴드를 파일로부터 로드하는 것이다. 전의 스텝과 같이, 이 코드도 InitializeGame 함수로부터 발췌한 것이다.

최초로, 이 어플리케이션은 로더 오브젝트를 생성 한다.

if (! SUCCEEDED(::CoCreateInstance(
            CLSID_DirectMusicLoader,
            NULL,
            CLSCTX_INPROC,
            IID_IDirectMusicLoader,
            (void**) &gpLoader
        )))
{
    return CleanupAndExit("로더 오브젝트를 생성 할 수 없었습니다. ");
}

다음에 모든 오브젝트의 검색 디렉토리를 설정해, 오브젝트 캐쉬를 유효하게 한다. 2 번째의 호출은, 단순하게 디폴트의 캐쉬 스테이터스를 확인한다.

hr = E_FAIL;

/ * GetSearchPath 함수는, 레지스트리로부터 미디어 디렉토리를
    취득해, 이것을 wszSearchPath 에 돌려준다. */

if (GetSearchPath(wszSearchPath))
{
    hr = gpLoader->SetSearchDirectory(
           GUID_DirectMusicAllTypes, wszSearchPath, FALSE);
}

/* 디렉토리가 존재하지 않는 경우는, 현재의 디렉토리에서 시험해 본다. */

if (FAILED(hr))
{
    hr = gpLoader->SetSearchDirectory(GUID_DirectMusicAllTypes,
            L". ", FALSE);
}
if (FAILED(hr))
{
    return CleanupAndExit("DirectMusic 로더의 검색 디렉토리를 \
            설정할 수 없었습니다. ");
}
gpLoader->EnableCache(GUID_DirectMusicAllTypes, TRUE);

다음의 코드의 일부는, Donuts.sty 파일내의 「Donuts」라고 하는 스타일을 로드한다. IDirectMusicLoader::ScanDirectory 를 호출해 데이타베이스 오브젝트를 구축 하면, 내부명을 지정해 오브젝트를 로드할 수 있지만, 이 어플리케이션은 이 메소드를 호출하지 않기 때문에, 최초로 IDirectMusicLoader::GetObject 를 호출하면 실패에 끝난다. fallback 수속은, 파일명을 사용해 오브젝트를 식별해, 한번 더 GetObject 를 호출한다.

IDirectMusicObject* pObject = NULL;
DMUS_OBJECTDESC ObjectDescript;

ObjectDescript.dwSize = sizeof(DMUS_OBJECTDESC);
ObjectDescript.guidClass = CLSID_DirectMusicStyle;
wcscpy(ObjectDescript.wszName, L"Donuts");
ObjectDescript.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_NAME;

if (! SUCCEEDED(gpLoader->GetObject(&ObjectDescript,
        IID_IDirectMusicStyle, (void**) &gapStyle[1])))
{
    wcscpy(ObjectDescript.wszFileName, L"Donuts.sty");
    ObjectDescript.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_FILENAME;
    if (! SUCCEEDED(gpLoader->GetObject(&ObjectDescript,
            IID_IDirectMusicStyle, (void**) &gapStyle[1])))
    {
        return CleanupAndExit("Couldn't load style object 1");
    }
}

다음에 InitializeGame 함수는 같은 방법으로, 이제(벌써) 1 개의 스타일과 2 개의 템플릿을 로드한다.

그 다음의 스텝은, 게임내의 특정의 이벤트를 마크 (명시) 하기 위해서 사용되는 모티프의 배열을 초기화하는 것이다. 각 모티프는 스타일내에 포함되어 있어IDirectMusicStyle::GetMotif 메소드를 호출하는 것에 의해 취득된다. 이 메소드는, 이 모티프용의 세그먼트(segment)를 생성 한다. Donuts.cpp 파일내의 다음의 예의 같게, 메소드에는 모티프의 내부명을 건네주지 않으면 안 된다.

WCHAR awszMotifs[NUM_MOTIFS][64];

wcscpy(awszMotifs[MOTIF_BOUNCE], L"Bounce");
.
.
.
hr = gapStyle[0]->GetMotif(awszMotifs[MOTIF_BOUNCE],
        &(gapMotif[0][MOTIF_BOUNCE]));

생략이 없는 완전한 코드를 참조 하면, 이 어플리케이션이 같은 이름을 가지는 모티프를 2 세트 로드하고 있는 것을 알 수 있다. 1 개(살)은 「Donuts」스타일로부터, 이제(벌써) 1 세트는 「Donutz」로부터이다. 플레이어의 레벨이 변화하는데 응해, DMDonuts 은 이것들 2 개의 스타일을 바꾼다. gapMotif 를 연주할 경우에, 글로벌인 gnCurrentStyle 의 값에 근거해 최초의 인덱스가 결정되어 모티프가 현재의 레벨에 적절한 것인 것을 보증한다.

계속되어, 어플리케이션은 스타일 마다 4 개의 코드 맵을 초기화한다. 이것들은, 다른 파일로부터 취득된다.

WCHAR awszChordMap[NUM_STYLES][NUM_CHORDMAP][64];
wcscpy(awszChordMap[0][0], L"minaeo.per");
wcscpy(awszChordMap[0][1], L"minfunc.per");
wcscpy(awszChordMap[0][2], L"mipedpt.per");
wcscpy(awszChordMap[0][3], L"tension.per");
wcscpy(awszChordMap[1][0], L"dianoble.per");
wcscpy(awszChordMap[1][1], L"minpedpt.per");
wcscpy(awszChordMap[1][2], L"mippjazz.per");
wcscpy(awszChordMap[1][3], L"minjazz.per");

ObjectDescript.guidClass = CLSID_DirectMusicChordMap;
ObjectDescript.dwValidData = DMUS_OBJ_CLASS | DMUS_OBJ_FILENAME;

for (short n = 0; n < NUM_STYLES; n++)
{
    for (short m = 0; m < NUM_CHORDMAP; m++)
    {
        if (hr == S_OK)
        {
            wcscpy(ObjectDescript.wszFileName,
                    awszChordMap[n][m]);
            hr = gpLoader->GetObject(&ObjectDescript,
                    IID_IDirectMusicChordMap,
                   (void**) &gapChordMap[n][m]);
        }
    }
}

if (hr ! = S_OK)
{
    return CleanupAndExit("코드 맵을 로드할 수 없었습니다. ");
}

이 스타일로부터 꺼내야 할 마지막 요소는 밴드이다. 각 스타일은 2 개가 다른 밴드를 갖추고 있다. 1 개(살)은 플레이어의 우주선에 쉴드(shield)가 없을 때, 이제(벌써) 1 개(살)은 쉴드(shield)가 쳐지고 있을 때이다. 밴드에 할당할 수 있고 있는 이름이, 모티프나 코드 맵에 할당할 수 있고 있는 이름과는 다른 점에 주의 해야 한다. 어느 쪽의 밴드에도,WCHAR 의 로컬 배열은 아니고 BSTR 를 할당할 수 있고 있다. 다만, Win32® API 에서는 BSTR 는 WCHAR 배열에의 포인터이므로, 이것들은 같은 이펙트를 가져온다.

각 밴드를 로드할 때, 이것들은 퍼포먼스에 다운로드되어 DLS 데이터가 음색으로 이용 가능해진다.

BSTR bstrDefault = SysAllocString(L"Default 2");
BSTR bstrShields = SysAllocString(L"Shields");

for (n = 0; n < NUM_STYLES; n++)
{
    if (hr == S_OK)
    {
        hr = gapStyle[n]->GetBand(bstrShields, &gapShieldBand[n]);
    }
    if (hr == S_OK)
    {
        hr = gapShieldBand[n]->Download(gpPerformance);
    }
    if (hr == S_OK)
    {
        hr = gapStyle[n]->GetBand(bstrDefault, &gapDefaultBand[n]);
    }
    if (hr == S_OK)
    {
        hr = gapDefaultBand[n]->Download(gpPerformance);
    }
}

SysFreeString(bstrDefault);
SysFreeString(bstrShields);

몇개의 에러 체크 코드의 다음에, InitializeGame 함수는 스스로 취득한 4 개의 밴드로부터 세그먼트(segment)를 생성 한다. 이러한 밴드를 사용해, 적절한 때에 밴드 체인지를 「연주」한다. 세그먼트(segment)를 생성 한 후, 밴드 인터페이스를 릴리즈 한다.

for (n = 0; n < NUM_STYLES; n++)
{
    if (hr == S_OK)
    {
        hr = gapShieldBand[n]->CreateSegment(&gapShieldSegment[n]);
    }
    if (hr == S_OK)
    {
        hr = gapDefaultBand[n]->CreateSegment(&gapDefaultSegment[n]);
    }
    apShieldBand[n]->Release();
    apDefaultBand[n]->Release();
}

다음 방향 : 스텝 4 : 통지의 설정


스텝 4 : 통지의 설정

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

InitializeGame 함수내의 DirectMusic 코드의 마지막 부분은, 프라이머리 세그먼트(segment)의 재생이 밴드 경계 또는 세그먼트(segment)의 마지막에 달했을 때에 통지를 실시하도록(듯이) 요구한다. 이 튜토리얼로 잠시 후에 관찰하도록(듯이), 이 통지 메카니즘은 동시에 연주할 수 있는 「폭발」모티프의 수를 제한하기 위해서 사용되고 있다.

다음의 코드에서는, 통지의 타입이 추가되고 있다. 통지 GUID 는 참조의 형태로 건네주지 않으면 안 되기 때문에, 통지 GUID 를 변수에 둘 필요가 있는 점에 주의 해야 한다.

GUID guid;
guid = GUID_NOTIFICATION_SEGMENT;
gpPerformance->AddNotificationType( guid );
guid = GUID_NOTIFICATION_MEASUREANDBEAT;
gpPerformance->AddNotificationType( guid );

다음 방향 : 스텝 5 : 프라이머리 세그먼트(segment)의 생성


스텝 5 : 프라이머리 세그먼트(segment)의 생성

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

샘플 어플리케이션 DMDonuts 내의 DirectMusic 의 1 회 한정의 초기화는 여기까지로 완료했다. setup_game 함수내에서 행해지는 이 이후의 초기화는, 게임의 스타트시, 또는 플레이어가 다음의 레벨에 진행될 때마다 실시된다.

setup_game 함수는, 최초로 ComposeNewSegments 함수를 호출한다. 이 함수는 현재의 게임 레벨에 근거해 스타일과 코드 맵을 선택해, 그때까지 생성 한 세그먼트(segment)를 릴리즈 한다. 계속되어, 지금까지 파일로부터 로드한 템플릿에 근거해 2 개의 새로운 세그먼트(segment)를 생성 한다. 이러한 세그먼트(segment) 가운데, 1 개는 아스테로이드 (소행성)가 충돌할 때까지 연주되는 도입의 테마이며, 이제 1 개(살)은 그 시점으로부터 플레이어의 레벨이 오를 때까지 연주된다. 변수 snSubLevel 는, 현재의 레벨로 어느 파트를 사용하고 있는지 추적해, 다른 장소에서는, F7 키를 눌러 음악을 바꾸도록(듯이) 지시받았을 때에 어느 세그먼트(segment)를 연주해야할 것인가 결정하기 위해서(때문에) 사용된다.

snSubLevel = 1;
snLastTempo = 0;
gnLastStyle = gnCurrentStyle;
gnLastChordMap = gnCurrentChordMap;
gnCurrentStyle = level % NUM_STYLES;
gnCurrentChordMap = ((level - 1) / 2) % NUM_CHORDMAP;
HRESULT hr = S_OK;
MUSIC_TIME mtSegmentLength;
if (gapSegment[SEGMENT_1])
{
    gapSegment[SEGMENT_1]->Release();
}
hr = gpComposer->ComposeSegmentFromTemplate(
        gapStyle[gnCurrentStyle],
        gpIntroTemplate, 0,
        gapChordMap[gnCurrentStyle][gnCurrentChordMap],
        &gapSegment[SEGMENT_1]
);
if (! SUCCEEDED(hr))
{
    CleanupAndExit("Segment 1 composition failed");
}

여기서, 이 템플릿의 마지막 소절에 싸인 포스트가 있어, 그것이 최초의 소절의 싸인 포스트와 일치하고 있는 것에 눈치챈다. 이것은 자연스러운 루프를 실현하기 때문에 있다. 세그먼트(segment)를 생성 한 다음에, 마지막 소절은 루프로부터 떼어진다. MEASURE_LENGTH 의 값이, 「스텝 1 : define 와 글로벌」로 (DMUS_PPQ * 4), 즉 뮤직 타임의 4 분 음표로서 계산되는 점에 주의 해야 한다. 박자 기호가 4/4 이므로, 이것은 유효하다.

gapSegment[SEGMENT_1]->GetLength(&mtSegmentLength);
gapSegment[SEGMENT_1]->SetLength(
        mtSegmentLength - MEASURE_LENGTH);

마지막으로, 이 세그먼트(segment)가 루프를 반복하도록(듯이) 설정된다.

gapSegment[SEGMENT_1]->SetRepeats(999);

gpGameTemplate 에 근거하는 2 번째의 세그먼트(segment)의 생성과 설정도 같은 방법으로 행해진다.

다음 방향 : 스텝 6 : 프라이머리 세그먼트(segment)의 연주


스텝 6 : 프라이머리 세그먼트(segment)의 연주

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

전의 스텝에서, Donuts.cpp 파일내의 setup_game 함수는, ComposeNewSegments 함수를 호출해, 현재의 게임 레벨로 연주되는 2 개의 프라이머리 세그먼트(segment)를 생성 했다. 여기에서는 setup_game 함수는 이러한 세그먼트(segment)중 최초의 것을 연주한다.

gpPerformance->PlaySegment(
    gapSegment[SEGMENT_1], 0, 0, NULL);

이 플래그가, 이 세그먼트(segment)를 즉석에서 연주하도록 지시하고 있는 점에 주의 해야 한다.

이 함수는, 현재의 스타일용으로 생성 된 디폴트의 밴드 세그먼트(segment)를 연주한다. (게임 레벨이 변화한 시점에서, 2 개(살)이 다른 스타일이 존재하는 점에 주의 해야 한다. 각 스타일에는 2 개의 밴드가 있어, 디폴트의 밴드는 「쉴드(shield) 있어」의 밴드이다. ) 밴드 세그먼트(segment)를 연주하는 것으로써, 올바른 음색 세트가 이 음악을 연주하는 것이 보증된다. 밴드 세그먼트(segment)를 세컨드리로서 지정하는 플래그를 할당하지 않으면 안 되는 점에 주의 해야 한다. 변경이 즉석에서 행해지므로, 3 번째의 파라미터로 시작 타임이 지정되지 않고, 세그먼트(segment) 상태에의 포인터가 필요없기 때문에, 마지막 파라미터는 NULL 가 되어 있다.

gpPerformance->PlaySegment(
    gapDefaultSegment[gnCurrentStyle],
    DMUS_SEGF_SECONDARY,
    0, NULL);

플레이어의 우주선이 쉴드(shield) 없음 상태가 되면(자), 이 스타일의 디폴트의 밴드가 사용된다. 레벨의 시작시에 반드시 이 상태가 발생한다. 쉴드(shield)가 유효하게 되면(자), 어플리케이션은 거기에 응해 UpdateDisplayList 함수내의 2 번째의 밴드를 연주해, 쉴드(shield)가 무효가 되면(자) 다시 디폴트의 밴드를 연주한다.

다음 방향 : 스텝 7 : 별의 프라이머리 세그먼트(segment)에의 이행


스텝 7 : 별의 프라이머리 세그먼트(segment)에의 이행

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

Dmdonuts 는, 2 개의 상황으로 다른 프라이머리 세그먼트(segment)를 삽입한다. 게임 레벨이 변화했을 때와 임의의 레벨로 아스테로이드에 최초로 충돌했을 때이다. 다음의 코드는, CheckForHits 함수로부터 발췌한 것이다. 이 함수는, 현재의 레벨로 충돌이 최초로 발생한 것을 검출 하면, DirectMusic 작곡가에게, 현재의 (도입) 테마로부터 액션 테마에의 이행부를 생성 하도록 지시한다. IDirectMusicComposer::AutoTransition 를 호출했을 경우도, 이행부와 다음의 액션 세그먼트(segment)가 삽입되어 그것들이 자동적으로 연주된다. 이 경우, 이행부는 다음의 소절 경계로부터 시작 된다.

if (gapSegment[SEGMENT_TRANS_1])
{
    gapSegment[SEGMENT_TRANS_1]->Release();
}
gpComposer->AutoTransition(
        gpPerformance,                 // 퍼포먼스.
        gapSegment[SEGMENT_2],         // 다음의 프라이머리 세그먼트(segment)
        DMUS_COMMANDT_FILL,            // 장식 타입.
        DMUS_COMPOSEF_MODULATE |       // 새로운 키에 전조 해,
        DMUS_COMPOSEF_MEASURE,         // 소절을 시작 한다.
        gapChordMap[gnCurrentStyle] [gnCurrentChordMap],
                                       // 현재의 코드 맵을 사용한다.
        &gapSegment[SEGMENT_TRANS_1],  // 생성 된 이행부 세그먼트(segment).
        NULL, NULL                     // 세그먼트(segment) 상태는 필요없다
);

최초의 세그먼트(segment)를 정지할 필요가 없는 점에 주의 해야 한다. 이행부 또는 새로운 프라이머리 세그먼트(segment)가 연주되면(자), 최초의 세그먼트(segment)는 자동적으로 정지한다.

다음 방향 : 스텝 8 : 모티프의 연주


스텝 8 : 모티프의 연주

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

Dmdonuts 는 몇개의 모티프를 사용해, 게임의 액션에 엑센트를 붙인다. 예를 들어, 플레이어의 우주선이 화면의 구석에 접했을 때나, 플레이어의 포화가 아스테로이드에 해당되었을 때를 들 수 있다.

모티프를 연주하는 것은, CheckForHits 함수로부터 발췌한 다음의 코드가 가리키는 대로 단순한 작업이다. 도너츠에 명중할 때마다 MOTIF_BLOWUP 가 연주된다.

gpPerformance->PlaySegment(
        gapMotif[gnCurrentStyle][MOTIF_BLOWUP],
        DMUS_SEGF_SECONDARY | DMUS_SEGF_GRID, 0, NULL);

이 모티프는 세컨드리 세그먼트(segment)로서 연주해야 하기 때문에, 프라이머리 세그먼트(segment)가 연주되고 있는 한중간이라도 메인 테마를 방해할 것은 없다. 그리드 경계에서 연주하도록(듯이) 삽입되어 프라이머리 세그먼트(segment)의 스텝을 어지럽히지 않고 연주할 수 있도록(듯이) 최소한의 분해가능이 설정된다. rtStartTime 파라미터는 0 이며, 최초의 경계에 이르렀을 때에 세그먼트(segment)를 연주하는 것을 의미하고 있어, 연주중의 세그먼트(segment)에 액세스 할 필요는 없기 때문에 ppSegmentState 파라미터는 NULL 가 되어 있다.

다음 방향 : 스텝 9 : 통지의 처리


스텝 9 : 통지의 처리

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

「스텝 4 : 통지의 설정」에서는, 세그먼트(segment)가 마지막에 달했을 때, 또는 박이나 소절의 경계에 이르렀을 때에,DMDonuts 가 통지를 요구하는 방법을 관찰했다. 이 통지의 목적은, 한 번에 연주되는 「폭발」모티프의 수를 제한하는 것을 지원하는 것에 있다.

통지는 WinMain 함수에 의해 꺼내진다. 큐내외의 메세지를 처리한 다음에, 어플리케이션은 보류중의 통지가 존재할지 어떨지를 체크한다. 이 처리는,IDirectMusicPerformance::GetNotificationPMsg 메소드의 호출에 의해 실시한다. 보류중의 통지 메세지가 없는 경우, 이 메소드는 S_FALSE 를 돌려주어, 그 이상의 처리는 필요없다. S_OK 가 돌려주어졌을 경우는, 통지 메세지가 *pEvent 에 저장 되고 있는 것을 나타내고 있다. 박에 관련하는 통지를 요구한 것만으로 있으므로, 실제로 어플리케이션으로 메세지를 확인할 필요는 없다. 메세지는 즉시 파기된다. 게다가 다음의 박까지 연주할 수 있는 폭발 모티프의 수를 추적하는 snMaxBlowUps 를 리셋 한다.

if (gpPerformance)
{
    DMUS_NOTIFICATION_PMSG* pEvent;
    while ( S_OK == gpPerformance->GetNotificationPMsg(&pEvent))
    {
        gpPerformance->FreePMsg((DMUS_PMSG*) pEvent);
        snMaxBlowUps = BLOWUPS_PER_BEAT;
    }
}

다음 방향 : 스텝 10 : DirectMusic 의 슛다운


스텝 10 : DirectMusic 의 슛다운

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 튜토리얼」을 참조할것.

[C++]

DirectMusic 를 닫으려면 , COM 의 참조를 해제해 (CoInitialize 의 호출 1 개(살)에 대해,CoUninitialize 의 호출 1 개(살)을 대응시키지 않으면 안 되는 점에 주의 해야 한다), 로더 캐쉬를 소거해, 퍼포먼스를 정지해, 생성 한 모든 오브젝트를 릴리즈 한다.

Donuts.cpp 파일에서는, 다음의 함수가 필요한 클린 업 작업을 실행한다.

void CleanUpDMusic()
{
    if (gpLoader)
    {
        gpLoader->ClearCache(GUID_DirectMusicAllTypes);
        gpLoader->Release();
    }

    if (gpComposer)
    {
        gpComposer->Release();
    }

    if (gpIntroTemplate)
    {
        gpIntroTemplate->Release();
    }

    if (gpGameTemplate)
    {
        gpGameTemplate->Release();
    }

    for (short n = 0; n < NUM_STYLES; n++)
    {
        if (gapShieldBand[n])
        {
            gapShieldBand[n]->Unload(gpPerformance);
            gapShieldBand[n]->Release();
        }
        if (gapDefaultBand[n])
        {
            gapDefaultBand[n]->Unload(gpPerformance);
            gapDefaultBand[n]->Release();
        }
        if (gapShieldSegment[n])
        {
            gapShieldSegment[n]->Release();
        }

        if (gapDefaultSegment[n])
        {
            gapDefaultSegment[n]->Release();
        }

        if (gapStyle[n])
        {
            gapStyle[n]->Release();
        }

        for (short m = 0; m < NUM_CHORDMAP; m++)
        {
            if (gapChordMap[n][m])
            {
                gapChordMap[n][m]->Release();
            }
        }

        for (m = 0; m < NUM_MOTIFS; m++)
        {
            if (gapMotif[n][m])
            {
                gapMotif[n][m]->Release();
            }
        }
    }

    if (gpPerformance)
    {
        gpPerformance->Stop( NULL, NULL, 0, 0 );
        gpPerformance->CloseDown();
        gpPerformance->Release();
    }

    for (n = 0; n < NUM_SEGMENTS; n++)
    {
        if (gapSegment[n])
        {
            gapSegment[n]->Release();
        }
    }

    if (gpDirectMusic)
    {
        gpDirectMusic->Release();
    }

    CoUninitialize();
}


DirectMusic Visual Basic 튜토리얼

[C++]

여기에서는, DirectX for Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectMusic C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

여기에서는, 다음의 튜토리얼을 사용해, Visual Basic 어플리케이션에 DirectMusic 를 이행 하는 방법을 설명한다.

  • 튜토리얼 1 : MIDI 파일의 연주
  • 튜토리얼 2 : DLS 사운드 이펙트의 사용법


튜토리얼 1 : MIDI 파일의 연주

[C++]

여기에서는, DirectX for Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「튜토리얼 1 : MIDI 파일의 연주」를 참조할것.

[Visual Basic]

이 튜토리얼은, 프라이머리 세그먼트(segment)를 연주할 뿐(만큼)의, 가장 간단한 DirectMusic 어플리케이션을 설정하기 위한 가이드이다. 이 예에서는, 세그먼트(segment)는 1 개의 MIDI 파일을 나타내고 있지만, 소스가 DirectMusic Producer 등의 툴로 오쏘링 된 1 개의 세그먼트(segment)인 경우도, 데이터의 로드와 연주의 프로세스는 완전히 같다.

이 튜토리얼은, 다음의 스텝으로 구성되어 있다.

  • 스텝 1 : 퍼포먼스와 로더의 생성
  • 스텝 2 : MIDI 파일의 로드
  • 스텝 3 : MIDI 파일의 연주


스텝 1 : 퍼포먼스와 로더의 생성

[C++]

여기에서는, DirectX for Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectMusic C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

DirectMusic 어플리케이션의 중심이 되는 오브젝트는,DirectMusicPerformance 클래스의 인스턴스이다. 다른 템포등을 사용해 다른 포트로 연주하는 복수의 퍼포먼스를 사용할 수도 있지만, 대부분의 어플리케이션은, 퍼포먼스 오브젝트를 1 개만 필요로 한다. 뮤직 데이터를 로드하려면 , 어플리케이션에 DirectMusicLoader 오브젝트도 필요하다.

이러한 오브젝트를 생성 하려면 , 우선 글로벌 DirectX7 오브젝트를 선언해야 한다.

다음의 글로벌 선언에서는, DirectX7 오브젝트와 다른 필요한 오브젝트용의 변수가 생성 된다.

Public gObjDX As New DirectX7
Public gObjDMLoader As DirectMusicLoader
Public gObjDMPerformance As DirectMusicPerformance

기동시의 코드로, 퍼포먼스 및 로더 오브젝트를 다음과 같이 생성 한다.

Set gObjDMLoader = gObjDX.DirectMusicLoaderCreate
Set gObjDMPerformance = gObjDX.DirectMusicPerformanceCreate

또, 퍼포먼스를 초기화해, 이것에 포트를 할당하지 않으면 안 된다. 다음의 코드에서는, 퍼포먼스에 독자적인 DirectSound 오브젝트를 생성시켜, 디폴트 포트를 할당하고 있다. 디폴트 포트는, 항상, Microsoft Software Synthesizer 또는 DLS 대응의 하드웨어 신디사이저의 어느 쪽인지이다. MIDI 파일에서는 최대로 16 의 채널이 필요하기 (위해)때문에, 1 개의 채널 그룹을 포트에 할당할 수 있다. 그 외의 종류의 세그먼트(segment)도 연주하는 어플리케이션에서는, 이 수를 늘리지 않으면 안 되는 경우가 있다.

' hWnd 는, 메인 폼의 윈도우 핸들이다.
Call gObjDMPerformance.Init(Nothing, hWnd)
Call gObjDMPerformance.SetPort(-1, 1)

다음 방향 : 스텝 2 : MIDI 파일의 로드


스텝 2 : MIDI 파일의 로드

[C++]

여기에서는, DirectX for Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectMusic C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

MIDI 파일을 로드하려면 , 다음의 3 개가 필요하다.

  • 전의 스텝에서 생성 한 DirectMusicLoader 오브젝트
  • DirectMusicSegment 변수
  • MIDI 파일의 이름

뮤직 파일이 어플리케이션의 작업 디렉토리 이외의 장소에 있는 경우는,DirectMusicLoader.SetSearchDirectory 를 호출해 로더에 검색하는 장소를 지시하는지, 각 파일을 풀 패스로 기술한다.

다음의 코드에서는, 로더의 검색 디렉토리를 설정해, 그 디렉토리로부터 파일을 로드하고 있다.

Call gObjDMLoader.SetSearchDirectory("c:\midiplay\media")
'이 처리는 한 번만 필요하다.

Dim objSeg As DirectMusicSegment

' FileName 는, 파일의 짧은 이름을 포함한 캐릭터 라인이다.
Set objSeg = gObjDMLoader.LoadSegment(FileName)

다음 방향 : 스텝 3 : MIDI 파일의 연주


스텝 3 : MIDI 파일의 연주

[C++]

여기에서는, DirectX for Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectMusic C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

여기까지의 스텝에서, MIDI 파일을 나타내는 DirectMusicSegment 오브젝트가 생성 되고 있다. 이것을 연주하려면 , 좀 더 준비가 필요하다.

우선, 세그먼트(segment)에, 스탠다드 MIDI 파일인 것을 통지한다. 이 스텝이 없어도 세그먼트(segment)를 연주할 수 있지만, 재생에 관한 특정의 항목이 올바르게 처리되지 않을 가능성이 있다. 다음의 코드에서는, 종래의 MIDI 파일 확장자(extension)를 가지는 파일에 대해서, 이 처리를 실행하고 있다.

If StrConv(Right(FileName, 4), vbLowerCase) = ". mid" Then
    Call objSeg.SetStandardMidiFile
End If

다음에, 음색의 DLS 데이터가, 포트에 확실히 다운로드되도록(듯이) 한다. 가장 간단한 방법은, 퍼포먼스 전체로 자동 다운로드를 유효하게 하는 것이다. 이 처리는, 셋업 코드로 다음과 같이 지정할 수 있다.

Call gObjDMPerformance.SetMasterAutoDownload(True)

이 방법의 결점은, 세그먼트(segment)의 정지와 동시에 포트로부터 음색이 언로드되기 (위해)때문에, 한번 더 음색을 다운로드해야 하는 점이다. 어플리케이션이 다른 세그먼트(segment)를 계속해 연주하는 경우, 이 처리에 의해, 용인할 수 없을 만큼의 지연이 발생할 가능성이 있다. 처리를 보다 완전하게 제어하기 위해서, 세그먼트(segment)가 연주되기 직전에, 매회 음색을 다운로드하도록(듯이) 지정할 수가 있다. 음색을 언로드하도록(듯이) 선택할 때까지, 또는 퍼포먼스가 종료할 때까지, 음색은 포트에 남은 채로된다. 중복 하는 다운로드는 무시된다.

Call objSeg.Download(gObjDMPerformance)

여기까지의 작업으로, 세그먼트(segment)는 연주 가능해졌다.

Call gObjDMPerformance.PlaySegment(objSeg, 0, 0)

재생 상태를 (예를 들어, 일시정지나 재개를 실시할 수 있도록(듯이)) 추적하는 경우는,DirectMusicSegmentState 오브젝트의 DirectMusicPerformance.PlaySegment 의 반환값을 보존해 둔다.

Dim objSegState as DirectMusicSegmentState
Set objSegState = gObjDMPerformance.PlaySegment(gObjPrimarySeg, 0, 0)


튜토리얼 2 : DLS 사운드 이펙트의 사용법

[C++]

여기에서는, DirectX for Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[Visual Basic]

이 튜토리얼에서는,DLS 를 사용해, DirectMusic 로 음악 이외의 사운드 이펙트를 생성 하는 방법을 설명한다. 코드예는,DLSEffects 샘플을 기본으로 한 것으로,DLS 콜렉션 파일의 Boids.dls 를 사용한다. 또, DirectMusic Producer 를 사용해 이 콜렉션을 검증해, 튜토리얼로 설명되고 있는 개념의 몇개인가를 보다 깊게 이해할 수도 있다. DLS 콜렉션의 표시 및 편집 방법의 상세한 것에 대하여는, DirectMusic Producer 의 문서를 참조할것.

이 튜토리얼은, 다음의 스텝으로 구성되어 있다.

  • 스텝 1 : 사운드의 로드
  • 스텝 2 : 이펙트의 연주
  • 스텝 3 : 이펙트의 수정과 정지


스텝 1 : 사운드의 로드

[C++]

여기에서는, DirectX for Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[Visual Basic]

퍼포먼스를 생성 및 초기화한 후,DLSEffects 샘플은 DLS 파일과 세그먼트(segment) 파일을 로드한다. 이러한 파일은 어느쪽이나,mediapath 로 지정된 디렉토리에서 로드 된다.

' dx 는 DirectX7 오브젝트를 나타낸다.
' perf 는 초기화된 DirectMusicPerformance 오브젝트를 나타낸다.
' seg 는 DirectMusicSegment 로서 선언된다.

mediapath = FindMediaDir("sample.sgt", "dmusic")
If mediapath <> vbNullString Then ChDir mediapath

Dim loader As DirectMusicLoader
Set loader = dx.DirectMusicLoaderCreate
Set coll = loader.LoadCollection(mediapath & "boids.dls")
Set seg = loader.LoadSegment(mediapath & "sample.sgt")

로드 되는 세그먼트(segment)의 종류가 무엇으로 있을까는 문제는 아니다. 어플리케이션은 세그먼트(segment)를 연주하지 않지만, DLS 데이터를 다운로드하려면 DirectMusicSegment 오브젝트가 필요하다.

여기서, 어플리케이션은 DirectMusicCollection 오브젝트를 세그먼트(segment)에 관련지어 포트에 다운로드한다. 세그먼트(segment)에 의해 참조되는 것 외의 음색도, 똑같이 다운로드된다.

Call seg.ConnectToCollection(coll)
Call seg.Download(perf)

Boids.dls 콜렉션에는, Vocals 라고 하는 음색이 1 개만 포함되어 있다. 이 음색의 패치 번호는 127 으로 설정되어 있다. MIDI 패치 메세지를 송신해, 이 음색을 임의의 채널에 할당할 수가 있다. 다른 샘플에 영향을 주는 일 없이, 연주하는 샘플의 1 개 (고동음의 사운드)에 핏치벤드를 설정할 수 있도록(듯이), 어플리케이션은 음색을 2 개의 채널에 할당하고 있다.

Const channel = 1
Const hbchannel = 2
Const patch = 127
Call perf.SendPatchPMSG(0, DMUS_PMSGF_REFTIME, channel, patch, 0, 0)
Call perf.SendPatchPMSG(0, DMUS_PMSGF_REFTIME, hbchannel, patch, 0, 0)

채널 1 또는 2 로 연주되는 음표는 모두, Vocals 음색을 사용한다. 이 음색을 사용해, 다른 사운드 효과를 얻는 방법에 대해서는, 「스텝 2 : 이펙트의 연주」를 참조할것.


스텝 2 : 이펙트의 연주

[C++]

여기에서는, DirectX for Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[Visual Basic]

DLSEffects 샘플에서는, 웃음소리, 무엇인가 국어인가의 스피치의 단편, 고동음 등, 유저는 다양한 사운드 이펙트를 (들)물을 수가 있다. 이러한 사운드는 모두, 1 개의 DLS 음색에 포함되어 있다.

다른 음표의 범위, 즉리젼에 대해서, 다른 웨이브 샘플을 관련지을 수가 있으므로, 1 개의 음색으로 완전히 다른 사운드를 연주할 수가 있다. 예를 들어 Boids.dls 에서는, 1 번째의 스피치는 C0 ~ B3 의 피치 범위에 할당할 수 있고 있다. 이 범위의 음표는, 모두 같은 웨이브 샘플에 근거한다. 루트 음표는 C3 이다. 이것은, C3 의 음표가 연주되었을 때에, 웨이브는 본래의 주파수로 들리는 것을 의미한다. 그 외의 음표에서는, 웨이브의 피치가 수정된다.

다음의 프로시저는, 글로벌 변수 gVelocity 로 지정되는 볼륨으로 음표를 송신한다.

Private Sub SendNote(chan As Integer, pitch As Byte, dur As Long)

  Dim noteMsg As DMUS_NOTE_PMSG
  noteMsg.velocity = gVelocity
  noteMsg.flags = DMUS_NOTEF_NOTEON
  noteMsg.midiValue = pitch
  noteMsg.mtDuration = dur
  Call perf.SendNotePMSG(0, DMUS_PMSGF_REFTIME, chan, noteMsg)

 End Sub

Boids.dls 의 웨이브는, 1 개(살)을 제외한 모든 것이 단발의 샘플이다. 즉, 음표가 연주될 때, 웨이브 샘플은 음표의 길이에 관계없이 한 번 밖에 연주되지 않는다. 예외는 고동음의 샘플로, 음표가 연주되고 있는 동안, 샘플은 루프 해 연주된다. 이 루프의 동작은, 음색 콜렉션의 작가에 의해 지정되고 있다.

다음의 프로시저는 C3 의 음표를 송신한다. C3 는, 1 번째의 스피치 샘플의 루트 음표이다. 따라서, 이 샘플은 정확한 피치로 연주된다. 정수 NoteDur 는 6000 밀리 세컨드로, DirectMusic 가 노트 오프의 MIDI 메세지를 생성하기 전에, 이 샘플 또는 그 외의 웨이브를 완전하게 재생 가능한 한의 충분한 시간을 설정해 있다(이 시간이 경과하기 전에, 버튼을 클릭해 동일한 음표를 송신했을 경우, 노트 오프 메세지에 의해 새로운 음표도 캔슬되어 연주가 완전하게 행해지지 않는 경우가 있다).

Private Sub cmdC3_Click()
  SendNote channel, 36, NoteDur
End Sub

DLSEffects 어플리케이션에서는, 대부분의 샘플은 각각의 루트 음표로 연주된다. 다만, 고동음의 샘플의 취급은 조금 달라, 사운드 이펙트의 피치를 프로그램적으로 변경할 수가 있다. 이 항목에 대해서는, 「스텝 3 : 이펙트의 수정과 정지」를 참조할것.


스텝 3 : 이펙트의 수정과 정지

[C++]

여기에서는, DirectX for Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[Visual Basic]

Boids.dls 의 Vocals 음색의 정의에서는, 고동음 샘플의 리젼은 B7 ~ B8 이다. 샘플 어플리케이션으로 연주되고 있도록(듯이), 유저는 [Note] 슬라이더를 사용해, 이 리젼내에서 음표를 선택할 수가 있다. 슬라이더를 이동할 때 마다, 이미 연주중의 음표는 정지되어 새로운 음표가 송신된다.

음표의 계속 시간은 무기한이기 (위해)때문에, 음표는 DirectMusicPerformance.SendMIDIPMSG 를 사용해, 스탠다드 MIDI 노트 온 메세지의 형식에서 송신된다 (또는,DirectMusicPerformance.SendNotePMSG 를 사용해, 계속 시간에 매우 큰 값을 지정한다). 현재의 주파수와 velocity는, 마지막 2 개의 파라미터로 주어진다. 이 메소드는 채널을 다른 파라미터로서 받아들이기 (위해)때문에, 스탠다드 MIDI 메세지와 달리, MIDI 스테이터스 바이트 (&H90)의 하위 4 비트에는 채널 번호가 함없다.

Call perf.SendMIDIPMSG(0, DMUS_PMSGF_REFTIME, hbchannel, _
        &H90, B7Freq, gVelocity)

고동음의 음표의 변경에 가세해, 유저는 음표를 연주하는 채널에 핏치벤드를 할당할 수도 있다. 핏치벤드도, 스탠다드 MIDI 메세지로서 송신된다.

Call perf.SendMIDIPMSG(0, DMUS_PMSGF_REFTIME, hbchannel, _
        &HE0, lo, hi)

lo 및 hi 파라미터는 7 비트값으로, 핏치벤드에는 16,384 로 우리의 설정이 가능하다. 상세한 것에 대하여는, MIDI 의 사양을 참조할것.

고동음의 음표를 정지하기 위해서, 샘플 어플리케이션은 SendNotePMSG 메소드를 사용해, 현재 연주되고 있는 음표와 같은 피치의 음표를 송신한다. DMUS_NOTE_PMSG 형의 flags 멤버에는, 보통의 DMUS_NOTEF_NOTEON 대신에 0 을 설정한다.

Private Sub B7NoteOff()

  Dim noteMsg As DMUS_NOTE_PMSG
  noteMsg.flags = 0
  noteMsg.midiValue = B7Freq  ' B7Freq is pitch of last note-on
  Call perf.SendNotePMSG(0, DMUS_PMSGF_REFTIME, hbchannel, noteMsg)
End Sub

채널의 핏치벤드는, 이 조작에 영향을 주지 않는다.


DirectMusic 레퍼런스

여기에서는, Microsoft® DirectMusic® 가 C/C++ 및 Microsoft® Visual Basic® 로 제공하는 API (Application Programming Interface) 요소의 레퍼런스 정보를 기술한다. 레퍼런스 정보는 이하의 언어별로 구성된다.

  • DirectMusic C/C++ 레퍼런스
  • DirectMusic Visual Basic 레퍼런스


DirectMusic C/C++ 레퍼런스

여기에서는, DirectMusic 가 제공하는 API 요소의 레퍼런스 정보를 기술한다. 레퍼런스 정보는 이하의 카테고리로 분류된다.

  • 인터페이스
  • 메세지
  • 구조체
  • 파일 구조체
  • DLS 구조체
  • 열거형
  • 반환값


인터페이스

여기에서는, 이하의 DirectMusic 인터페이스 메소드에 관한 레퍼런스를 제공한다.

  • IDirectMusic
  • IDirectMusicBand
  • IDirectMusicBuffer
  • IDirectMusicChordMap
  • IDirectMusicCollection
  • IDirectMusicComposer
  • IDirectMusicDownload
  • IDirectMusicDownloadedInstrument
  • IDirectMusicGetLoader
  • IDirectMusicGraph
  • IDirectMusicInstrument
  • IDirectMusicLoader
  • IDirectMusicObject
  • IDirectMusicPerformance
  • IDirectMusicPort
  • IDirectMusicPortDownload
  • IDirectMusicSegment
  • IDirectMusicSegmentState
  • IDirectMusicStyle
  • IDirectMusicThru
  • IDirectMusicTool
  • IDirectMusicTrack
  • IKsControl
  • IReferenceClock


IDirectMusic 인터페이스

IDirectMusic 인터페이스는, 버퍼, 포트, master clock를 관리하기 위한 메소드를 제공한다. 각 어플리케이션은, 이 인터페이스의 인스턴스를 복수 생성 해서는 안된다.

주 : 이 인터페이스를 생성 하는 헬퍼-함수는 존재하지 않는다. 어플리케이션은 COM 의 CoCreateInstance 함수나 IDirectMusicPerformance::Init 메소드를 사용해 DirectMusic 오브젝트를 생성 한다.

IDirectMusic 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

액티브화 | Activate
버퍼 | CreateMusicBuffer
링크 | SetDirectSound
포트 | CreatePort
 | EnumPort
 | GetDefaultPort
타이밍 | EnumMasterClock
 | GetMasterClock
 | SetMasterClock

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusic::Activate

IDirectMusic::Activate 메소드는, 이 인터페이스에 의해 생성 된 모든 출력 포트의 액티브화 또는 비액티브화를 실시한다.

HRESULT Activate(
  BOOL fEnable
);

파라미터

fEnable
DirectMusic 의 이 인스턴스로 생성 된 모든 포트를 액티브화 (TRUE) 또는 비액티브화 (FALSE) 한다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 DSERR_NODRIVER 를 돌려주어, 사운드 드라이버가 없는 것을 나타낸다.

주의

어플리케이션이 백그라운드에서 음악을 재생할 필요가 없는 경우, 입력초점을 잃은 단계에서 IDirectMusic::Activate(FALSE)를 호출해야 하는 것이다. 이 결과, 입력초점이 놓여져 있는 다른 어플리케이션은 이러한 포트에 액세스 할 수 있다. 입력초점이 다시 이 어플리케이션에 놓여진 단계에서,Activate(TRUE)를 호출해, 할당모든 포트를 사용 가능하게 해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPort::Activate


IDirectMusic::CreateMusicBuffer

IDirectMusic::CreateMusicBuffer 메소드는, 포트에 순서화 되고 있는 뮤직 메세지를 보관 유지하는 DirectMusicBuffer 오브젝트를 생성 한다. 포트의 추가시에 버퍼 관리는 퍼포먼스에 의해 처리되기 (위해)때문에, 대부분의 어플리케이션은 이 메소드를 호출할 필요가 없다.

HRESULT CreateMusicBuffer(
  LPDMUS_BUFFERDESC pBufferDesc,
  LPDIRECTMUSICBUFFER *ppBuffer,
  LPUNKNOWN pUnkOuter
);

파라미터

pBufferDesc
생성 되는 뮤직 버퍼의 기술을 보관 유지하는 DMUS_BUFFERDESC 구조체의 주소. 포인터를 건네주기 전에, 어플리케이션은 이 구조체의 dwSize 멤버를 초기화해야 한다. 「주의」를 참조할것.
ppBuffer
IDirectMusicBuffer 인터페이스 포인터를 받는 변수의 주소.
pUnkOuter
COM 집합체의 경우는, 제어 오브젝트의 IUnknown 인터페이스의 주소. 집합체는 현재 지원되어 있지 않기 때문에, 이 값은 NULL 로 설정해야 한다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_INVALIDARG
E_NOAGGREGATION
E_NOINTERFACE
E_OUTOFMEMORY
E_POINTER

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusic::CreatePort

IDirectMusic::CreatePort 메소드는, 특정의 DirectMusic 포트용의 오브젝트를 생성 하기 위해서 사용된다.

HRESULT CreatePort(
  REFCLSID rclsidPort,
  LPDMUS_PORTPARAMS pPortParams,
  LPDIRECTMUSICPORT *ppPort,
  LPUNKNOWN pUnkOuter
);

파라미터

rclsidPort
IDirectMusicPort 인터페이스의 생성처가 되는 포트를 식별하는 GUID 에의 참조 (C++) 또는 주소 (C). IDirectMusic::EnumPort 메소드를 사용해 GUID 를 꺼낸다. 이 파라미터가 GUID_NULL 의 경우는, 돌려주어지는 포트가 디폴트 포트가 된다. 상세한 것에 대하여는, 「디폴트 포트」를 참조할것.
pPortParams
포트의 파라미터를 보관 유지하는 DMUS_PORTPARAMS 구조체의 주소. 이 메소드를 호출하기 전에, 이 구조체의 dwSize 멤버를 초기화해야 한다.
ppPort
IDirectMusicPort 인터페이스 포인터를 받는 변수의 주소.
pUnkOuter
COM 집합체의 경우는, 제어 오브젝트의 IUnknown 인터페이스의 주소. 집합체는 현재 지원되어 있지 않기 때문에, 이 값은 NULL 로 설정해야 한다.

반환값

성공하면 S_OK 를 돌려준다. 지정한 파라미터를 이용할 수 없는 경우는 S_FALSE 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_DSOUND_NOT_SET
E_INVALIDARG
E_NOAGGREGATION
E_NOINTERFACE
E_OUTOFMEMORY
E_POINTER

주의

포트는 디폴트로, 생성시에는 비액티브하게 되어 있다. 이것을 액티브하게 해,IDirectMusic::Activate 또는 IDirectMusicPort::Activate 를 호출하지 않으면 안 된다.

모든 파라미터를 취득할 수 없는 경우는,DMUS_PORTPARAMS 구조체를 이하와 같이 변경해, 포트의 이용할 수 있는 파라미터와 일치시킨다.

엔트리내에서는, 구조체의 dwValidParams 멤버에 의해, 구조 체내의 유효한 멤버가 나타난다. 구조체의 멤버에 대해 플래그를 세트 하고 있지 않는 경우는, 포트의 생성시에, 그 파라미터에 디폴트값이 설정된다.

값이 돌려주어지면(자),dwValidParams 내의 플래그에 의해, 어느 포트 파라미터가 설정되었는지가 나타난다. 특정의 파라미터를 지정하지 않고, 디폴트값으로 설정했을 경우, 그 플래그는 건네받은 파라미터에 추가된다.

지정한 파라미터를 포트가 지원 하고 있어도, 파라미터의 값이 범위외의 경우는,*pPortParams 내의 파라미터값이 변경된다. 이 경우,dwValidParams 내의 플래그는 세트 된채로 있지만, S_FALSE 가 돌려주어져 값이 변경되었던 것(적)이 나타난다.

다음의 샘플 코드에서는, 어플리케이션이 어떻게 리바브 기능을 요구해, 그것을 취득할 수 있었는지 어떠했는지를 판별하는 방법을 나타낸다(포트 프로퍼티의 체크 및 설정의 다른 방법에 대해서는, 「포트의 프로퍼티 세트」를 참조할것).

DMUS_PORTPARAMS 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;
        }
    }
}

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusic::EnumMasterClock

IDirectMusic::EnumMasterClock 메소드는, DirectMusic 가 master clock로서 이용할 수 있는 클럭의 기술의 열거와 취득에 사용된다. 이 메소드를 호출할 때마다, 1 개의 클럭에 관한 정보를 꺼낸다.

HRESULT EnumMasterClock(
  DWORD dwIndex,
  LPDMUS_CLOCKINFO lpClockInfo
);

파라미터

dwIndex
기술을 꺼내고 싶은 클럭의 인덱스 번호. 최초로 호출하면나무는 이 파라미터를 0 으로 설정해, 그 이후는 호출마다 1 두개 크게 해야 한다. S_FALSE 가 돌려주어질 때까지 호출을 계속한다.
lpClockInfo
클럭의 기술을 받는 DMUS_CLOCKINFO 구조체의 주소. 포인터를 건네주기 전에, 어플리케이션은 이 구조체의 dwSize 멤버를 초기화해야 한다.

반환값

성공하면 S_OK 를 돌려준다. 지정한 인덱스 번호를 가지는 클럭이 존재하지 않는 경우는 S_FALSE 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_INVALIDARG
E_NOINTERFACE
E_POINTER

주의

어플리케이션은 클럭의 인덱스 번호를 신뢰하거나 보존해서는 안된다. 재부팅 또는 하드웨어의 추가나 삭제를 하면(자), 클럭의 인덱스 번호가 변화할 가능성이 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusic::SetMasterClock ,IDirectMusic::GetMasterClock


IDirectMusic::EnumPort

IDirectMusic::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

주의

어플리케이션은 포트의 인덱스 번호를 신뢰하거나 보존해서는 안된다. 재부팅 또는 하드웨어의 추가나 삭제를 하면(자), 포트의 인덱스 번호가 변화할 가능성이 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusic::GetDefaultPort

IDirectMusic::GetDefaultPort 메소드는, 디폴트의 출력 포트의 GUID 를 꺼낸다. 이것은,IDirectMusic::CreatePort 에 GUID_NULL 를 건네주었을 때에 생성 되는 포트이다.

HRESULT GetDefaultPort(
  LPGUID pguidPort
);

파라미터

pguidPort
디폴트 포트의 GUID 를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

디폴트 포트


IDirectMusic::GetMasterClock

IDirectMusic::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 인터페이스를 다 사용한 다음에, 이 인터페이스를 릴리즈 해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusic::SetMasterClock


IDirectMusic::SetDirectSound

IDirectMusic::SetDirectSound 메소드는, 웨이브 출력용으로, DirectMusic 를 DirectSound 오브젝트에 접속한다.

HRESULT SetDirectSound(
  LPDIRECTSOUND pDirectSound,
  HWND hWnd
);

파라미터

pDirectSound
출력용으로 사용하는 IDirectSound 인터페이스의 주소. 이 파라미터가 NULL 의 경우, DirectSound 오브젝트가 생성 되어 협조 레벨이 설정된다 ( 「주의」를 참조할것). 이 파라미터에 IDirectSound 포인터가 포함되는 경우는, 어플리케이션이 협조 레벨을 설정해야 한다.
hWnd
이 호출에 의해 생성 되는, DirectSound 오브젝트의 윈도우 핸들. 이 값이 NULL 의 경우, 현재의 전면 윈도우가 포커스 윈도우로서 설정된다. 「주의」를 참조할것.

pDirectSound 가 유효한 인터페이스의 경우, 이 파라미터는 무시된다. IDirectSound::SetCooperativeLevel 의 호출에서는, 어플리케이션이 유효한 윈도우 핸들을 제공할 필요가 있기 때문에 있다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 DMUS_E_DSOUND_ALREADY_SET 를 돌려준다.

주의

지정한 DirectSound 오브젝트는, 모든 포트상에서 오디오를 렌더링 할 때에 사용되는 오브젝트이다. 이 디폴트값은,IDirectMusicPort::SetDirectSound 메소드를 사용해 덧쓰기할 수 있다.

IDirectMusic::SetDirectSound 메소드를 호출할 때마다, 기존의 DirectSound 오브젝트는 릴리즈 된다.

pDirectSound 가 NULL 의 경우, DirectSound 를 사용하는 포트가 액티브화 될 때까지 새로운 DirectSound 오브젝트는 생성 되지 않는다. DirectSound 오브젝트는, 그것을 사용하고 있는 마지막 포트가 비액티브화 되면(자) 자동적으로 릴리즈 된다.

DirectSound 오브젝트를 스스로 생성 했을 경우는, 모든 포트를 비액티브화한 다음에, 이 메소드의 pDirectSound 파라미터에 NULL 를 설정해 호출하는 것에 의해 릴리즈 할 수 있다 (액티브한 포트 대해 SetDirectSound 를 호출하는 것은 잘못이다).

hWnd 파라미터에 NULL 를 건네주어, 현재의 전면 윈도우 핸들을 DirectSound 에 건네줄 수가 있다. 다만, 초기화중에 어플리케이션 윈도우가 전면에 있으면(자) 상정하지 않는 것. 보통, 최상 레벨의 어플리케이션 윈도우 핸들은, DirectMusic, DirectSound, 및 DirectDraw 에 건네주지 않으면 안 된다. 「IDirectSound::SetCooperativeLevel 」의 「주의」를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

DirectMusic 와 DirectSound 의 통합


IDirectMusic::SetMasterClock

IDirectMusic::SetMasterClock 메소드는,IDirectMusic::EnumMasterClock 을 호출했을 때에 취득된 GUID 에 의해 식별되는 클럭을, DirectMusic 의 master clock로 설정한다. 모든 DirectMusic 어플리케이션은, 다만 1 개의 master clock를 사용한다.

HRESULT SetMasterClock(
  REFGUID rguidClock
);

파라미터

rguidClock
DirectMusic 의 master clock로서 설정되는 클럭을 식별하는 GUID 에의 참조 (C++) 또는 주소 (C). 이 파라미터는,IDirectMusic::EnumMasterClock 메소드가 돌려준 GUID 가 아니면 안된다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 DMUS_E_PORTS_OPEN 를 돌려준다.

주의

실행중의 다른 어플리케이션도 DirectMusic 를 사용하고 있는 경우, 그 어플리케이션이 슛다운 할 때까지는 master clock를 변경할 수 없다.

(정도)만큼 어느 어플리케이션은 SetMasterClock 를 호출할 필요가 없다. 시스템 클록 이외의 하드웨어 타이머와의 엄밀한 동기를 필요로 하지 않는 이상 이 메소드를 호출해서는 안된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusic::GetMasterClock ,IDirectMusic::EnumMasterClock


IDirectMusicBand

IDirectMusicBand 인터페이스는, DirectMusicBand 오브젝트를 나타낸다. 밴드를 사용해, 일련의 P 채널의 음색의 선택사항과 믹서 설정을 지정한다. 개요에 대해서는, 「밴드의 사용법」을 참조할것.

밴드는 복수의 장소로부터 꺼내도 괜찮다. 이것들을 전용의 파일에 보존해도, 스타일의 밴드 리스트나 세그먼트(segment)의 밴드 트랙에 묻어도 괜찮다.

DirectMusicBand 오브젝트는, 스스로의 데이터를 로드하기 위해서(때문에) IPersistStream 과 IDirectMusicObject 의 각 인터페이스도 지원 하고 있다.

IDirectMusicBand 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

세그먼트(segment) 생성 | CreateSegment
음색 데이터 | Download
 | Unload

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDMUS_BAND 형은,IDirectMusicBand 인터페이스에의 포인터로서 정의되고 있다.

typedef IDirectMusicBand __RPC_FAR *LPDMUS_BAND;

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicBand::CreateSegment

IDirectMusicBand::CreateSegment 메소드는,IDirectMusicPerformance::PlaySegment 메소드를 사용해, 밴드내에서의 볼륨, 팬, 전조, 및 패치 체인지 커멘드를 동적으로 연주한다.

HRESULT CreateSegment(
  IDirectMusicSegment** ppSegment
);

파라미터

ppSegment
생성 된 섹션 세그먼트(segment)에의 포인터를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_FAIL
E_OUTOFMEMORY
E_POINTER

주의

밴드로부터 세그먼트(segment)를 생성 하는 방법의 예에 대해서는, 「프로그램적인 밴드 체인지의 실행」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicBand::Download

IDirectMusicBand::Download 메소드는, 밴드내의 음색의 DLS 데이터를 퍼포먼스 오브젝트에 다운로드한다. 이 메소드는,IDirectMusicPerformance::DownloadInstrument 메소드를 호출하는 것에 의해, 밴드내의 각 음색을 다운로드한다. DownloadInstrument 는 음색의 P 채널을 사용해 적절한 포트를 찾아내 그 포트에 대해서 IDirectMusicPort::DownloadInstrument 메소드를 호출한다.

밴드의 다운로드가 끝나면(자), 그 밴드내의 음색은, 프로그램 체인지 MIDI 메세지에 의해 개별적으로 선택하는지,IDirectMusicBand::CreateSegment 메소드를 호출해 생성 한 밴드 세그먼트(segment)를 재생하는 것으로써 한 번에 모든 것을 선택할 수 있다.

HRESULT Download(
  IDirectMusicPerformance* pPerformance
);

파라미터

pPerformance
악기의 다운로드처의 퍼포먼스. 퍼포먼스는 P 채널로부터 DirectMusic 포트에의 맵핑을 관리한다.

반환값

성공하면 S_OK 또는 DMUS_S_PARTIALDOWNLOAD 를 돌려준다 ( 「주의」를 참조할것).

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_NOT_INIT
E_OUTOFMEMORY
E_POINTER

주의

다운로드한 밴드는 신디사이저 리소스를 사용하기 (위해)때문에, 필요가 없을 때는 IDirectMusicBand::Unload 메소드를 사용해 언로드해야 한다.

현재의 버젼의 DirectMusic 의 경우, 포트가 DLS 를 지원 하고 있지 않아도 S_OK 가 돌려주어지는 일이 있다.

다운로드가 완전하게 실패했을 경우는, DMUS_E_NOT_INIT 가 돌려주어진다. 이것은 보통, 초기화된 포트에 퍼포먼스가 정상적으로 접속되지 않았던 것을 의미한다. 이것은 완전한 실패이기 (위해)때문에, 다음에 IDirectMusicBand::Unload 를 호출할 필요는 없다.

다운로드가 일부 성공했을 경우는, DMUS_S_PARTIALDOWNLOAD 가 돌려주어진다. 이것은, 정상적으로 다운로드할 수 있던 음색과 다운로드할 수 없었던 음색이 있는 것을 의미한다. 그 원인은 보통, 퍼포먼스와 포트의 설정에 대해 프로그래밍 에러가 발생했기 때문이다. 문제를 특정하는 최선의 방법은, Dmime.dll, Dmband.dll, 및 Dmsynth.dll 의 디버그 트레이스를 1 으로 설정하는 것이다 ( 「DirectMusic 프로젝트의 디버그」를 참조).

부분적인 다운로드가 발생하는 일반적인 원인을 이하에 나타낸다.

  • 밴드는, 퍼포먼스에 대해서 설정되어 있지 않은 P 채널상에 음색을 가지고 있다 (IDirectMusicPerformance::AssignPChannelBlock 의 사용에 의한다).
  • 밴드는, 포트에 할당할 수 있지 않은 채널 그룹의 P 채널상에 음색을 가지고 있다.
  • 밴드는, 음색의 다운로드처가 되는 신디사이저와 호환성이 없는 DLS 포맷의 음색을 가지고 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h로 선언.

참조

IDirectMusicBand::Unload


IDirectMusicBand::Unload

IDirectMusicBand::Unload 메소드는,IDirectMusicBand::Download 를 사용해 이전에 다운로드한 밴드내의 음색의 DLS 데이터를 언로드한다.

HRESULT Unload(
  IDirectMusicPerformance* pPerformance
);

파라미터

pPerformance
악기의 언로드원의 퍼포먼스.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicBand::Download ,IDirectMusicPort::UnloadInstrument


IDirectMusicBuffer::Flush

IDirectMusicBuffer::Flush 메소드는, 버퍼내의 전데이터를 파기한다.

HRESULT Flush();

파라미터

없음.

반환값

항상 S_OK 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusicBuffer::GetBufferFormat

IDirectMusicBuffer::GetBufferFormat 메소드는, 버퍼 포맷을 나타내는 GUID 를 돌려준다.

HRESULT GetBufferFormat(
  LPGUID pGuidFormat
);

파라미터

pGuidFormat
버퍼 포맷의 GUID 를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

주의

버퍼를 생성 했을 때에 포맷을 지정하지 않았던 경우,*pGuidFormat 에 KSDATAFORMAT_SUBTYPE_DIRECTMUSIC 가 돌려주어진다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusic::CreateMusicBuffer ,DMUS_EVENTHEADER


IDirectMusicBuffer::GetMaxBytes

IDirectMusicBuffer::GetMaxBytes 메소드는, 버퍼내에 보존할 수 있는 바이트수를 꺼낸다.

HRESULT GetMaxBytes(
  LPDWORD pcb
);

파라미터

pcb
버퍼를 보관 유지할 수 있는 최대의 바이트수를 포함한 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusicBuffer::GetNextEvent

IDirectMusicBuffer::GetNextEvent 메소드는, 버퍼내의 이하의 메세지에 관한 정보를 돌려주어, read 포인터를 먼저 진행한다.

HRESULT GetNextEvent(
  LPREFERENCE_TIME prt,
  LPDWORD pdwChannelGroup,
  LPDWORD pdwLength,
  LPBYTE* ppData
);

파라미터

prt
메세지의 타임을 받는 변수의 주소.
pdwChannelGroup
메세지의 채널 그룹을 받는 변수의 주소.
pdwLength
메세지의 길이 (바이트 단위)를 받는 변수의 주소.
ppData
메세지 데이터에의 포인터를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다. 다만, 버퍼내에 메세지가 존재하지 않았던 경우는 S_FALSE 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

주의

항목이 필요없는 경우, 해당하는 포인터로서 NULL 를 지정해도 괜찮다.

ppData 에 돌려주어진 포인터는, 버퍼 오브젝트의 수명의 사이에 한해서 유효하다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicBuffer::ResetReadPtr


IDirectMusicBuffer::GetRawBufferPtr

IDirectMusicBuffer::GetRawBufferPtr 메소드는, 근저에 있는 버퍼 데이터 구조체에의 포인터를 돌려준다.

HRESULT GetRawBufferPtr(
  LPBYTE* ppData
);

파라미터

ppData
버퍼의 데이터에의 포인터를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

주의

이 메소드는, 버퍼의 raw 데이터에의 포인터를 돌려준다. 이 데이터의 포맷은, 이행에 의존한다. 데이터의 수명은, 버퍼 오브젝트의 수명과 같다. 그 때문에, 다음에 IDirectMusicBuffer::Release 메소드를 호출한 후는, 돌려주어진 포인터를 보관 유지해서는 안된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusicBuffer::GetStartTime

IDirectMusicBuffer::GetStartTime 메소드는, 버퍼내의 데이터의 시작 타임을 꺼낸다. 이 타임은 master clock를 기준으로 한다.

HRESULT GetStartTime(
  LPREFERENCE_TIME prt
);

파라미터

prt
시작 타임을 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_BUFFER_EMPTY
E_POINTER

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicBuffer::SetStartTime ,IDirectMusicBuffer::TotalTime


IDirectMusicBuffer::GetUsedBytes

IDirectMusicBuffer::GetUsedBytes 메소드는, 버퍼내의 데이터의 바이트수를 꺼낸다.

HRESULT GetUsedBytes(
  LPDWORD pcb
);

파라미터

pcb
사용중의 바이트수를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicBuffer::SetUsedBytes


IDirectMusicBuffer::PackStructured

IDirectMusicBuffer::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 로서 사용한다. 「IDirectMusicPort::GetLatencyClock 」를 참조할것.

같은 타임의 스탬프가 뒤따른 메세지는, 버퍼내에 놓여진 순서와 같은 순서로 연주된다고는 할 수 없다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicBuffer::PackUnstructured


IDirectMusicBuffer::PackUnstructured

IDirectMusicBuffer::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 로서 사용한다. 「IDirectMusicPort::GetLatencyClock 」를 참조할것.

같은 타임의 스탬프가 뒤따른 메세지는, 버퍼내에 놓여진 순서와 같은 순서로 연주된다고는 할 수 없다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicBuffer::PackStructured


IDirectMusicBuffer::ResetReadPtr

IDirectMusicBuffer::ResetReadPtr 메소드는, read 포인터를 버퍼내의 데이터의 선두로 설정한다.

HRESULT ResetReadPtr()

파라미터

없음.

반환값

항상 S_OK 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicBuffer::GetNextEvent


IDirectMusicBuffer::SetStartTime

IDirectMusicBuffer::SetStartTime 메소드는, 버퍼내의 데이터의 시작 타임을 설정한다. 이 타임은 master clock를 기준으로 한다.

HRESULT SetStartTime(
  REFERENCE_TIME rt
);

파라미터

rt
버퍼의 새로운 시작 타임.

반환값

항상 S_OK 를 돌려준다.

주의

버퍼내에 이미 있는 이벤트는, 시작 타임을 기준으로 하는 타임 스탬프를 붙일 수 있어 새로운 시작 타임부터의 같은 오프셋(offset)로부터 연주한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicBuffer::GetStartTime


IDirectMusicBuffer::SetUsedBytes

IDirectMusicBuffer::SetUsedBytes 메소드는, 버퍼내의 데이터의 바이트수를 설정한다.

HRESULT SetUsedBytes(
  DWORD cb
);

파라미터

cb
버퍼내의 유효한 데이터 바이트수.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 DMUS_E_BUFFER_FULL 를 돌려준다.

주의

이 메소드를 사용하면(자), 어플리케이션은 버퍼를 수작업으로 재팩 할 수 있다. 보통, 버퍼내의 데이터 포맷이, DirectMusic 의 제공하는 디폴트의 포맷과 다를 때 마셔, 이 메소드를 사용해야 하는 것이다.

지정한 바이트수가,IDirectMusicBuffer::GetMaxBytes 메소드가 돌려주는 최대 버퍼 사이즈를 넘고 있는 경우, 이 메소드는 실패한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicBuffer::GetUsedBytes


IDirectMusicBuffer::TotalTime

IDirectMusicBuffer::TotalTime 메소드는, 버퍼내의 데이터가 포함 하는 합계 시간을 돌려준다.

HRESULT TotalTime(
  LPREFERENCE_TIME prtTime
);

파라미터

prtTime
버퍼내에 포함 되는 합계 시간 (100ns 단위)을 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicBuffer::GetStartTime


IDirectMusicChordMap

IDirectMusicChordMap 인터페이스는, 코드 맵을 나타낸다. 코드 맵은, 작곡가 (IDirectMusicComposer 에 의해 나타내진다)에 대해, 어레인지 하는 세그먼트(segment)의 코드 진행을 생성 하는데 필요한 정보를 제공한다. 코드 맵은, 기존 세그먼트(segment)내의 코드를 변경하는 경우에도 사용할 수 있다.

DirectMusicChordMap 오브젝트는, 스스로의 데이터를 로드하기 위해서(때문에) IDirectMusicObject 와 IPersistStream 의 각 인터페이스도 지원 하고 있다.

이 인터페이스는, 이하의 메소드를 지원 한다.

IDirectMusicChordMap GetScale

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicPersonality::GetScale

Platform SDK: DirectX

IDirectMusicChordMap::GetScale

IDirectMusicChordMap::GetScale 메소드는, 코드 맵에 관련지을 수 있고 있는 스케일을 꺼낸다.

HRESULT GetScale(
  DWORD* pdwScale
);

파라미터

pdwScale
스케일의 값을 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

주의

스케일은,DWORD 내의 비트를 스케일의 패턴 (하위 24 비트)과 루트음 (상위 8 비트)에 분할해 정의된다. 스케일의 패턴은, 최하정도 비트 (0x0001)는 저음의 C, 다음의 상위 비트 (0x0002)는 C# 이며, 똑같이 2 옥타브의 스케일이 정의된다. 상위 8 비트는, 스케일의 루트음을 0 ~ 23 (저음의 C 로부터 중간의 B 까지)의 정수로 나타낸다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicCollection

IDirectMusicCollection 인터페이스는,DLS 파일의 인스턴스를 관리한다. 콜렉션은, 악기에 액세스하기 위한 메소드를 제공해,IDirectMusicPort 인터페이스를 사용해 악기를 신디사이저에 다운로드한다.

DirectMusicCollection 오브젝트는, 스스로의 데이터를 로드하기 위해서(때문에) IDirectMusicObject 와 IPersistStream 의 각 인터페이스도 지원 하고 있다.

콜렉션을 사용한 작업의 상세한 것에 대하여는, 「 DLS 의 사용법」을 참조할것.

IDirectMusicCollection 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

악기 | EnumInstrument
 | GetInstrument

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusicCollection::EnumInstrument

IDirectMusicCollection::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 개의 인스턴스내에서는 정합하고 있지만, 이 순서는 파일내의 악기의 순서, 패치 번호, 악기명의 머지않아와도 관계는 없다.

악기의 열거의 예에 대해서는, 「음색의 조작」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusicCollection::GetInstrument

IDirectMusicCollection::GetInstrument 메소드는, 패치 번호를 지정해, 콜렉션으로부터 악기를 꺼낸다.

HRESULT GetInstrument(
  DWORD dwPatch,
  IDirectMusicInstrument** ppInstrument
);

파라미터

dwPatch
악기의 패치 번호.
ppInstrument
IDirectMusicInstrument 인터페이스에의 포인터를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_CORE_INVALIDPATCH
E_FAIL
E_OUTOFMEMORY
E_POINTER

주의

dwPatch 로 건네받은 패치 번호는,뱅크 셀렉트의 MSB 와 LSB 의 MIDI 파라미터도 포함한, 완전한 패치 주소를 기술한다. MSB 는 왼쪽 쉬프트 된 16 비트이며, LSB 는 왼쪽 쉬프트 된 8 비트이다. 자세한 것은, 「 MIDI 채널 메세지」를 참조할것.

더해, 특히 음색이 드럼 킷이며, MIDI 채널 10 으로 연주되는 것을 의도하고 있는 경우는, 상위 비트 (0x80000000)를 세트 해야 한다. DLS 레벨 1 용의 이 특별한 태그는, 드럼을 반드시 MIDI 채널 10 에 둔다.

이 메소드를 사용하는 방법의 상세한 것에 대하여는, 「음색의 조작」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusicComposer

IDirectMusicComposer 인터페이스를 사용하면(자), 작곡가 엔진에 액세스 할 수 있다. 템플릿이나 코드 맵으로부터 새로운 섹션 세그먼트(segment)를 구축하는 것에 가세해, 이 작곡가는 복수의 섹션 세그먼트(segment)간의 이행부를 생성 할 수 있다. 코드 맵을 기존의 섹션 세그먼트(segment)에도 적용할 수 있으므로, 섹션의 코드 진행과 분위기도 변경할 수 있다.

상세한 것에 대하여는, 「음악의 어레인지」를 참조할것.

IDirectMusicComposer 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

코드 맵의 변경 | ChangeChordMap
보통의 세그먼트(segment)의 어레인지 | ComposeSegmentFromShape
 | ComposeSegmentFromTemplate
템플릿 세그먼트(segment)의 어레인지 | ComposeTemplateFromShape
이행부 세그먼트(segment)의 어레인지 | AutoTransition
 | ComposeTransition

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicComposer::AutoTransition

IDirectMusicComposer::AutoTransition 메소드는, 퍼포먼스의 프라이머리 세그먼트(segment) (또는 무음)로부터 다른 세그먼트(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 를 참조할것. 이 값이 DMUS_COMMANDT_ENDANDINTRO 의 경우, 메소드는, 프라이머리 세그먼트(segment)의 종료부와 pToSeg 의 도입부를 포함한 세그먼트(segment)를 어레인지 한다.
dwFlags
작곡가 옵션. DMUS_COMPOSEF_FLAGS 를 참조할것.
pChordMap
이행부를 어레인지 할 경우에 사용하는 코드 맵.
ppTransSeg
생성 된 섹션 세그먼트(segment)에의 포인터를 받는 변수의 주소. 이 값은 NULL 이라도 좋다. 그 경우, 포인터는 돌려주어지지 않다.
ppToSegState
이행부 (pToSeg)의 뒤의 세그먼트(segment)의 퍼포먼스 (pPerformance)에 의해 생성 되는 세그먼트(segment) 상태에의 포인터를 받는 변수의 주소. 「주의」를 참조할것.
ppTransSegState
생성 된 세그먼트(segment) (ppTransSeg)의 퍼포먼스 (pPerformance)에 의해 생성 되는 세그먼트(segment) 상태에의 포인터를 받는 변수의 주소. 「주의」를 참조할것.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 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)내에서 발생하는 코드가 이행부의 코드로서 사용된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicComposer::ComposeTransition ,이행부의 사용법


IDirectMusicComposer::ChangeChordMap

IDirectMusicComposer::ChangeChordMap 메소드는, 새로운 코드 맵을 반영해, 기존의 섹션 세그먼트(segment)의 코드와 스케일의 패턴을 변경한다.

HRESULT ChangeChordMap(
  IDirectMusicSegment* pSegment,
  BOOL fTrackScale,
  IDirectMusicChordMap* pChordMap
);

파라미터

pSegment
변경에 사용하는 코드 맵을 포함한 섹션.
fTrackScale
TRUE 의 경우, 메소드는, 모든 코드를 새로운 코드 맙스 케일인 루트음에 상대적으로 전조 한다. 루트음을 그대로의 상태로 하지 않는다.
pChordMap
세그먼트(segment)의 새로운 코드 맵.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

주의

메소드는 세그먼트(segment)의 연주중에 호출할 수가 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicComposer::ComposeSegmentFromShape

IDirectMusicComposer::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)의 생성에 사용하는 코드 맵.
ppSegment
생성 된 섹션 세그먼트(segment)에의 포인터를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicComposer::ComposeSegmentFromTemplate ,IDirectMusicComposer::ComposeTemplateFromShape


IDirectMusicComposer::ComposeSegmentFromTemplate

IDirectMusicComposer::ComposeSegmentFromTemplate 메소드는, 스타일, 코드 맵, 및 템플릿으로부터 오리지날의 섹션 세그먼트(segment)를 생성 한다.

HRESULT ComposeSegmentFromTemplate(
  IDirectMusicStyle* pStyle,
  IDirectMusicSegment* pTemplate,
  WORD wActivity,
  IDirectMusicChordMap* pChordMap,
  IDirectMusicSegment** ppSegment
);

파라미터

pStyle
섹션 세그먼트(segment)의 생성에 사용하는 스타일.
pTemplate
섹션 세그먼트(segment)의 생성에 사용하는 템플릿.
wActivity
화음 진행의 레이트. 유효한 값은 0 ~ 3. 값이 낮으면 코드 체인지가 증가한다.
pChordMap
섹션 세그먼트(segment)의 생성에 사용하는 코드 맵.
ppSegment
생성 된 섹션 세그먼트(segment)에의 포인터를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_INVALIDARG
E_POINTER

주의

pStyle 가 NULL 가 아닌 경우, 이 스타일은 세그먼트(segment)의 어레인지에 사용된다. NULL 의 경우,pTempSeg 로 지정된 템플릿으로부터 꺼낸 스타일을 세그먼트(segment)의 작곡에 사용한다. 같이pChordMap 가 NULL 가 아닌 경우, 이 코드 맵은 세그먼트(segment)의 어레인지에 사용된다. NULL 의 경우, 위의 템플릿으로부터 꺼낸 코드 맵을 세그먼트(segment)의 어레인지에 사용한다.

pStyle 가 NULL 로 템플릿내에 스타일 트랙이 존재하지 않는 경우나,pChordMap 가 NULL 로 코드 맵 트랙이 존재하지 않는 경우, 이 메소드는 E_INVALIDARG 를 돌려준다.

섹션 세그먼트(segment)의 길이는, 건네받은 템플릿 섹션의 길이와 동일해진다.

생성 된 세그먼트(segment)의 디폴트의 시작 포인트와 루프 포인트는, 템플릿 세그먼트(segment)내의 값에 관계없이 0 이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicComposer::ComposeSegmentFromShape ,IDirectMusicComposer::ComposeTemplateFromShape ,템플릿의 사용법


IDirectMusicComposer::ComposeTemplateFromShape

IDirectMusicComposer::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 보다 크고, 이용할 수 있는 소절의 수이하가 아니면 안된다 (즉, 도입부에서는 사용되지 않는다). 「주의」도 참조할것.
ppTemp;ate
생성 된 섹션 세그먼트(segment)에의 포인터를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

주의

wEndLength 의 값은,IDirectMusicComposer::ComposeSegmentFromTemplate 메소드를 사용해 이 템플릿에 관련지을 수 있을 가능성이 있는 임의의 스타일내에서 이용할 수 있는 최장의 종료부의 길이를 넘어서는 안 된다. 종료부는, 세그먼트(segment)가 끝나기 전의 wEndLength 의 소절로 연주를 시작 한다. 종료부가 wEndLength 의 소절의 길이보다 짧은 경우, 음악은 기본 그루브 레벨에 돌아온다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicComposer::ComposeSegmentFromShape ,IDirectMusicComposer::ComposeSegmentFromTemplate ,템플릿의 사용법


IDirectMusicComposer::ComposeTransition

IDirectMusicComposer::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 를 참조할것. 이 값이 DMUS_COMMANDT_ENDANDINTRO 의 경우, 메소드는,pFromSeg 의 종료부와 pToSeg 의 도입부를 포함한 세그먼트(segment)를 어레인지 한다.
dwFlags
작곡가 옵션. 이 파라미터는,DMUS_COMPOSEF_FLAGS 열거형의 값의 1 개 또는 복수를 보관 유지하고 있어도 괜찮다.
pChordMap
이행부를 어레인지 할 경우에 사용하는 코드 맵. 「주의」를 참조할것.
ppTransSeg
생성 된 섹션 세그먼트(segment)에의 포인터를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

주의

pChordMap 의 값은 NULL 이라도 좋다. 값이 NULL 의 경우, 코드 맵 트랙으로부터 코드 맵을 취득하는 시도를 한다. 최초로 pToSeg, 다음에 pFromSeg 가 시험 받는다. 어느 세그먼트(segment)에도 코드 맵 트랙이 포함되지 않는 경우는,mtTime 에 pFromSeg 내에서 발생하는 코드가 이행부의 코드로서 사용된다.

작곡가는, 최초로 pFromSeg 내, 다음에 pToSeg 내에서 템포를 찾는다. 어느 세그먼트(segment)에도 템포 트랙이 없는 경우, 이행부 세그먼트(segment)의 템포는 스타일로부터 취득된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicComposer::AutoTransition ,이행부의 사용법


IDirectMusicDownload

IDirectMusicDownload 인터페이스는, 연속한 메모리체크를 나타내,DLS 신디사이저 포트에의 다운로드를 실시하기 위해서(때문에) 사용된다.

IDirectMusicDownload 인터페이스와 그 중에 포함되어 있는 메모리체크는,IDirectMusicPortDownload::AllocateBuffer 메소드에 의해 생성 된다. 그 후, 이 인터페이스의 1 개의 메소드를 사용해, 이 메모리에 액세스 할 수 있다.

이 인터페이스는, 이하의 메소드를 지원 한다.

IDirectMusicDownload GetBuffer

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusicDownload::GetBuffer

IDirectMusicDownload::GetBuffer 메소드는, 다운로드해야 할 데이터를 보관 유지하는 버퍼에의 포인터를 꺼낸다.

HRESULT GetBuffer(
  void** ppvBuffer,
  DWORD* pdwSize
);

파라미터

ppvBuffer
데이터 버퍼에의 포인터를 받는 변수의 주소.
pdwSize
돌려주어진 버퍼의 사이즈 (바이트 단위 )를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_BUFFERNOTAVAILABLE
E_POINTER

주의

버퍼가 이미 다운로드되고 있는 경우, 이 메소드는 DMUS_E_BUFFERNOTAVAILABLE 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusicDownloadedInstrument

IDirectMusicDownloadedInstrument 인터페이스를 사용해,IDirectMusicPort::DownloadInstrument 메소드 또는 IDirectMusicPerformance::DownloadInstrument 메소드에 의해 신디사이저에 다운로드된 음색을 식별한다. 다음에 이 인터페이스를 사용해,IDirectMusicPort::UnloadInstrument 를 호출해, 그 악기를 언로드한다. 음색을 언로드하면(자), 인터페이스 포인터는 어플리케이션에 의해 릴리즈 되지 않으면 안 된다.

구체적인 예는, 「음색의 조작」을 참조할것.

IDirectMusicDownloadedInstrument 인터페이스에는, 독자적인 메소드는 없다. 모든 COM 인터페이스와 같이,IDirectMusicDownloadedInstrument 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusicGetLoader

어느 오브젝트가, 스트림의 형태로 참조되고 있는 다른 오브젝트를 로드할 필요가 있을 때, 최초의 오브젝트는 IDirectMusicGetLoader 인터페이스를 사용해 스트림을 해석한다. 스트림이 로더를 지원 하고 있는 경우, 스트림은 반드시 IDirectMusicGetLoader 인터페이스를 제공하고 있다.

스트림으로부터 IDirectMusicGetLoader 인터페이스를 취득하는 방법의 예는,IDirectMusicGetLoader::GetLoader 를 참조할것.

IDirectMusicGetLoader 인터페이스는, 이하의 메소드를 지원 한다.

IDirectMusicGetLoader GetLoader

모든 COM 인터페이스와 같이,IDirectMusicTrack 인터페이스는 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicLoader ,DirectMusic 로더,커스텀 로드


IDirectMusicGetLoader::GetLoader

IDirectMusicGetLoader::GetLoader 메소드는, 스트림을 생성 한 로더 오브젝트에의 포인터를 꺼낸다.

HRESULT GetLoader(
  IDirectMusicLoader ** ppLoader
);

파라미터

ppLoader
IDirectMusicLoader 인터페이스 포인터를 받는 변수의 주소. 이 인터페이스의 참조 카운트는 인크리먼트(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;
}

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

커스텀 로드


IDirectMusicGraph

IDirectMusicGraph 인터페이스는, 툴의 로드와 메세지 플로우를 관리한다.

그래프는, 세그먼트(segment)와 퍼포먼스의 2 개의 장소에 둘 수가 있다. 퍼포먼스내의 툴에 대응하는 그래프는, 성질상 글로벌이며, 그 때문에(위해) 모든 세그먼트(segment)의 메세지를 처리한다. 어느 세그먼트(segment)내의 그래프는, 그 세그먼트(segment)의 재생만을 목적으로 해 존재한다.

IDirectMusicGraph 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

루팅 | StampPMsg
툴 | GetTool
 | InsertTool
 | RemoveTool

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicGraph::GetTool

IDirectMusicGraph::GetTool 메소드는, 지정된 인덱스의 툴을 꺼낸다.

HRESULT GetTool(
  DWORD dwIndex,
  IDirectMusicTool** ppTool
);

파라미터

dwIndex
그래프내의 희망의 툴을 지정하는, 0 으로부터 시작되는 인덱스.
ppTool
툴에의 포인터를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_NOT_FOUND
E_POINTER

주의

어플리케이션에는, 꺼낸 툴을 릴리즈 할 책임이 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicGraph::InsertTool

IDirectMusicGraph::InsertTool 메소드는, 그래프에 툴을 삽입한다.

HRESULT InsertTool(
  IDirectMusicTool * pTool,
  DWORD * pdwPChannels,
  DWORD cPChannels,
  LONG lIndex
);

파라미터

pTool
삽입하는 툴.
pdwPChannels
툴이 메세지를 받아들이는 P 채널의 배열의 주소. 이 툴이 모든 P 채널로 메세지를 받아들이는 경우, NULL 를 건네준다.
cPChannels
pdwPChannels 가 가리키는 P 채널의 수. pdwPChannels 가 NULL 의 경우는 무시된다.
lIndex
툴을 두는 위치. 이것은 0 으로부터 시작되는 인덱스이며, 현재의 툴 리스트의 선두 또는 최후 (값이 부의 경우 )로부터 센 위치를 의미한다. lIndex 가 범위외의 경우, 툴은 리스트의 선두 또는 마지막에 놓여진다. 툴을 리스트의 마지막에 두려면 , 현재의 툴 리스트내의 툴수보다 큰 값을 lIndex 로 지정한다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_ALREADY_EXISTS
E_OUTOFMEMORY
E_POINTER

주의

툴의 참조 카운트는 인크리먼트(increment) 된다.

이 메소드는 IDirectMusicTool::Init 를 호출한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicGraph::RemoveTool

IDirectMusicGraph::RemoveTool 메소드는, 그래프로부터 툴을 삭제한다.

HRESULT RemoveTool(
  IDirectMusicTool * pTool
);

파라미터

pTool
삭제하는 툴을 포함한 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_NOT_FOUND
E_POINTER

주의

이 툴에의 그래프의 참조는 릴리즈 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicGraph::StampPMsg

IDirectMusicGraph::StampPMsg 메소드는, 메세지를 받아들이는 다음의 툴에의 포인터를 메세지에 스탬프 한다. 툴은, 메세지를 처리한 후, 이 메소드를 호출하지 않으면 안 된다.

HRESULT StampPMsg(
  DMUS_PMSG* pPMSG
);

파라미터

pPMSG
스탬프의 대상이 되는 메세지를 보관 유지하는 구조체의 주소. 이 구조체는,DMUS_PMSG 의 파생 타입이다. 메세지 타입의 개요에 대해서는, 「메세지」를 참조할것.

반환값

성공하면 S_OK 를 돌려준다. 실패하면 DMUS_S_LAST_TOOL 를 돌려준다. 「주의」를 참조할것.

실패하면 E_POINTER 를 돌려준다.

주의

엔트리내의 pPMSG->pTool ( 「DMUS_PMSG 」를 참조)는, 현재의 툴을 가리킨다. StampPMsg 는 이 멤버를 사용해, 현재의 툴을 결정해, 그래프내의 다음의 툴을 찾아낸다. NULL 의 값은 그래프내의 최초의 툴을 나타낸다.

pPMSG->pGraph 가 가리키는 오브젝트는, 툴을 보관 유지하는 그래프를 나타낸다. StampPMsg 내부에서 이 값이 툴 자체의 값과 함께 스탬프 된다. 복수의 툴 그래프가 존재하는 경우, 메세지가 세그먼트(segment) 상태로부터 퍼포먼스에 이동하는 과정에서, 이 값이 변경되는 일이 있다.

pPMSG->dwType 의 값은, 메세지의 미디어 타입에 동일하고, 다음의 툴을 찾아내는데 사용된다. 미디어 타입으로서 지원 되고 있는 것은,IDirectMusicTool::GetMediaTypes 메소드가 돌려주는 값이다.

pPMSG->dwPChannel 의 값을 사용해 트랙을 지정하지만, 툴은 이 트랙을 처리하는 능력을 갖추지 않으면 안 된다. 섹션을 오쏘링 할 때에 할당할 수 있었던 고유의 번호를 사용해 트랙을 식별한다.

이 메소드는 pPMSG->pTool 가 가리키는 현재의 IDirectMusicTool 에 대해서 Release 를 호출해, 그래프내의 다음의 툴에 옮겨놓아 새로운 툴에 대해서 AddRef 를 호출한다.

이 메소드는, 다음의 툴이 IDirectMusicTool::GetMsgDeliveryType 메소드로 돌려주는 타입에 근거해, 메세지에 올바른 인도 타입 플래그도 할당한다. 이 플래그는, 메세지를 다음의 툴에 전달하는 시기를 결정한다.

DirectMusicSegmentState 와 DirectMusicPerformance 의 각 오브젝트에서의 이 메소드를 이행 하면, 성공했을 경우, 항상 S_OK 를 돌려준다. DirectMusicGraph 로 이행 하면, 메세지의 수취를 기다리고 있는 출력 툴 외에 툴이 없는 경우, DMUS_S_LAST_TOOL 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

DirectMusic 툴


IDirectMusicInstrument

IDirectMusicInstrument 인터페이스는,DLS 콜렉션의 개별의 음색을 나타낸다.

DirectMusicInstrument 오브젝트를 생성 해, 음색을 다운로드하기 위한 유일한 방법은, 최초로 DirectMusicCollection 오브젝트를 생성 해, 다음에 IDirectMusicCollection::GetInstrument 메소드를 호출한다. GetInstrument 는 DirectMusicInstrument 오브젝트를 생성 해,IDirectMusicInstrument 인터페이스 포인터를 돌려준다.

음색을 다운로드하려면 , 그 음색의 인터페이스 포인터를 IDirectMusicPort::DownloadInstrument 메소드 또는 IDirectMusicPerformance::DownloadInstrument 메소드에 건네준다. 이 메소드가 성공하면(자),IDirectMusicDownloadedInstrument 인터페이스에의 포인터가 돌려주어진다. 이 인터페이스는, 악기를 언로드하는 경우에게만 사용된다.

IDirectMusicInstrument 의 메소드는, 이미 다운로드되고 있는 음색에만 대해 동작한다. 이미 포트에 다운로드된 악기의 인스턴스는,IDirectMusicInstrument::GetPatch 나 IDirectMusicInstrument::SetPatch 의 각 메소드의 영향을 받지 않는다.

이 인터페이스는, 이하의 메소드를 지원 한다.

IDirectMusicInstrument | GetPatch
 | SetPatch

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusicInstrument::GetPatch

IDirectMusicInstrument::GetPatch 메소드는, 악기의 패치 번호를 꺼낸다. 이 패치 번호는,뱅크 셀렉트의 MSB 와 LSB, 및 MIDI 패치 (프로그램 체인지) 번호에 의해 구성된 주소이다. 옵션의 flag bit는, 음색이 선율계의 음색은 아니고, 드럼인 것을 나타낸다.

HRESULT GetPatch(
  DWORD* pdwPatch
);

파라미터

pdwPatch
패치 번호를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

주의

pdwPatch 에 돌려주어지는 패치 번호는,뱅크 셀렉트의 MSB 와 LSB 의 MIDI 파라미터도 포함한, 완전한 패치 번호를 기술한다. 더해, 특히 음색이 드럼 킷이며, MIDI 채널 10 으로 연주되는 것을 의도하고 있는 경우는, 상위 비트가 세트 된다. DLS 레벨 1 은 드럼을 반드시 MIDI 채널 10 으로 연주하기 위해(때문에), 이것이 DLS 레벨 1 용의 특별한 태그이다. 상세한 것에 대하여는, 「MIDI 채널 메세지」를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusicInstrument::SetPatch

IDirectMusicInstrument::SetPatch 메소드는, 악기용의 패치 번호를 설정한다. DLS 콜렉션내의 각 악기는 미리 정의된 패치 번호를 가지고 있지만,IDirectMusicCollection::GetInstrument 메소드를 사용해 콜렉션으로부터 악기를 꺼낸 후, 패치 번호를 재할인 맞히고 할 수도 있다. DirectMusic 패치 번호의 상세한 것에 대하여는,IDirectMusicInstrument::GetPatch 를 참조할것.

HRESULT SetPatch(
  DWORD dwPatch
);

파라미터

dwPatch
악기에 할당하는 새로운 패치 번호.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 DMUS_E_INVALIDPATCH 를 돌려준다.

주의

다음의 샘플 코드는, 콜렉션으로부터 음색을 취득해, 음색의 MSB 뱅크의 재맵을 실시해 다른 뱅크를 선택해, 그 음색을 다운로드한다.

HRESULT myRemappedDownload(
    IDirectMusicCollection *pCollection,
    IDirectMusicPort *pPort,
    IDirectMusicDownloadedInstrument **ppDLInstrument,
    BYTE bMSB,       // 패치 번호의 뱅크 셀렉트내에서 지정된 MIDI 의 MSB.
    DWORD dwPatch)   // 지정된 패치 번호.

{
    HRESULT hr;
    IDirectMusicInstrument* 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;
}

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusicLoader

IDirectMusicLoader 인터페이스는, 오브젝트의 검색, 열거, 캐싱, 및 로드에 사용된다. 상세한 것에 대하여는, 「DirectMusic 로더」를 참조할것.

IDirectMusicLoader 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

검색 | EnumObject
 | ScanDirectory
 | SetSearchDirectory
캐싱 | CacheObject
 | ClearCache
 | EnableCache
오브젝트 관리 | GetObject
 | ReleaseObject
 | SetObject

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDMUS_LOADER 형은,IDirectMusicLoader 인터페이스에의 포인터로서 정의되고 있다.

typedef IDirectMusicLoader __RPC_FAR *LPDMUS_LOADER;

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicLoader::CacheObject

IDirectMusicLoader::CacheObject 메소드는, 오브젝트에의 참조를 유지하도록(듯이) 로더에 지시한다. 이 결과, 오브젝트를 2 회 로드하지 않는 것이 보증된다.

HRESULT CacheObject(
  IDirectMusicObject * pObject
);

파라미터

pObject
캐쉬에 넣는 오브젝트의 IDirectMusicObject 인터페이스의 주소.

반환값

성공하면 S_OK 를 돌려준다. 오브젝트가 이미 캐쉬에 들어가 있는 경우는 S_FALSE 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_POINTER
DMUS_E_LOADER_OBJECTNOTFOUND

주의

어플리케이션의 실행 기간중, 복수의 장소로부터 액세스 되는 오브젝트가 존재하는 경우, 로더에 그 오브젝트를 캐싱 시키면(자) 퍼포먼스가 큰폭으로 고속화된다. 개요에 대해서는, 「오브젝트의 캐싱」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicLoader::EnableCache ,IDirectMusicLoader::ClearCache ,IDirectMusicLoader::ReleaseObject


IDirectMusicLoader::ClearCache

IDirectMusicLoader::ClearCache 메소드는, 특정의 타입의 오브젝트에의 모든 참조를 릴리즈 하도록(듯이) 로더에 지시한다.

HRESULT ClearCache(
  REFGUID rguidClass
);

파라미터

rguidClass
소거되는 오브젝트의 클래스 식별자에의 참조 (C++) 또는 주소 (C). GUID_DirectMusicAllTypes 를 사용해, 모든 타입을 지정할 수 있다.

반환값

S_OK 를 돌려준다.

주의

이 메소드는 현재 보관 유지 떠날 수 있어 모든 오브젝트를 소거하지만, 캐싱을 무효로 할 것은 없다. 자동적인 캐싱을 무효로 하려면 ,IDirectMusicLoader::EnableCache 메소드를 사용한다.

캐쉬로부터 1 개의 오브젝트를 소거하려면 ,IDirectMusicLoader::ReleaseObject 메소드를 호출한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicLoader::CacheObject ,오브젝트의 캐싱


IDirectMusicLoader::EnableCache

IDirectMusicLoader::EnableCache 메소드는, 로드 되는 모든 오브젝트의 자동적인 캐싱을 유효 또는 무효로 하도록(듯이) 로더에 지시한다. 디폴트에서는, 모든 클래스에서 캐싱이 유효하게 되어 있다.

HRESULT EnableCache(
  REFGUID rguidClass,
  BOOL fEnable
);

파라미터

rguidClass
캐싱 되는 오브젝트의 클래스 식별자에의 참조 (C++) 또는 주소 (C). GUID_DirectMusicAllTypes 를 사용해, 모든 타입을 지정할 수 있다.
fEnable
캐싱을 유효하게 하는 경우는 TRUE, 캐싱을 무효로 해 소거하는 경우는 FALSE.

반환값

캐쉬 상태가 변경되는 경우는 S_OK, 캐쉬가 이미 희망 상태가 되어 있는 경우는 S_FALSE 를 돌려준다.

주의

캐싱을 무효로 하지 않고 캐쉬를 소거하려면 ,IDirectMusicLoader::ClearCache 메소드를 호출한다.

다음의 샘플 코드는, 세그먼트(segment) 오브젝트에 한해서 캐싱을 무효로 하므로, 어플리케이션이 그것들을 릴리즈 한 후는 그러한 오브젝트는 메모리내에 머무를 것은 없다. 스타일, 코드 맵, DLS 콜렉션 등, 공유해야 할 그 외의 오브젝트는 계속해 캐싱 되고 있다. 디폴트로 모든 오브젝트의 캐싱은 유효하게 되어 있으므로,EnableCache 의 최초의 호출은, 보통은 불필요하다.

void myPrepareLoader(IDirectMusicLoader *pILoader)

{
    pILoader->EnableCache(GUID_DirectMusicAllTypes, TRUE);
    pILoader->EnableCache(CLSID_DirectMusicSegment, FALSE);
}

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicLoader::CacheObject ,IDirectMusicLoader::ClearCache ,오브젝트의 캐싱


IDirectMusicLoader::EnumObject

IDirectMusicLoader::EnumObject 메소드는, 요구한 타입의 이용 가능한 모든 오브젝트를 열거한다. 이용 가능한 오브젝트란, 이미 로드 되고 있는 것, 또는 IDirectMusicLoader::ScanDirectory 를 호출했을 때에 검색 디렉토리내에 존재하고 있던 것이다.

HRESULT EnumObject(
  REFGUID rguidClass,
  DWORD dwIndex,
  LPDMUS_OBJECTDESC pDesc
);

파라미터

rguidClass
표시되는 오브젝트의 클래스 식별자에의 참조 (C++) 또는 주소 (C).
dwIndex
리스트의 인덱스. 보통은 0 으로부터 시작되어, 값이 순서에 커진다.
pDesc
오브젝트에 관한 데이터를 입력하기 위한 DMUS_OBJECTDESC 구조체의 주소.

반환값

성공하면 S_OK 를 돌려준다. dwIndex 가 리스트의 최후를 넘고 있는 경우는 S_FALSE 를 돌려준다.

주의

이 메소드의 사용법의 예는, 「오브젝트의 열거」를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicLoader::ScanDirectory


IDirectMusicLoader::GetObject

IDirectMusicLoader::GetObject 메소드는, 지정된 오브젝트를 파일 또는 리소스로부터 꺼내, 희망의 인터페이스를 돌려준다.

HRESULT GetObject(
  LPDMUS_OBJECTDESC pDESC,
  REFIID riid,
  LPVOID FAR * ppv
);

파라미터

pDESC
오브젝트에 대해 기술하는 DMUS_OBJECTDESC 구조체의 주소.
riid
인터페이스의 일의의 식별자. Dmusici.h 로 정의되고 있는 IID 를 참조할것. 표준적인 인터페이스는 모두,"IID_" 와 인터페이스의 이름으로 구성되는 정의 끝난 식별자를 가진다. 예를 들어,IDirectMusicTrack 의 식별자는 IID_IDirectMusicTrack 이다.
ppv
오브젝트의 희망의 인터페이스에의 포인터를 받는 변수의 주소.

반환값

성공하면 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

주의

DMUS_S_PARTIALLOAD 의 반환값에 따라서는, 디폴트의 음색 콜렉션 파일, Gm.dls 를 이용할 수 없는 것을 의미하는 경우가 있다.

현재의 버젼의 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, 이하, 리소스, 풀 패스명, 내부명과 카테고리, 내부명, 로컬 파일명의 순서이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicLoader::ReleaseObject , IDirectMusicLoader::ScanDirectory


IDirectMusicLoader::ReleaseObject

IDirectMusicLoader::ReleaseObject 메소드는, 오브젝트에의 로더의 참조를 릴리즈 한다.

HRESULT ReleaseObject(
  IDirectMusicObject * pObject
);

파라미터

pObject
릴리즈 하는 오브젝트를 포함한 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_POINTER
DMUS_E_LOADER_OBJECTNOTFOUND

주의

ReleaseObject 는,IDirectMusicLoader::CacheObject 와 대를 이루는 메소드이다.

CacheObject 메소드를 사용해 명시적으로, 또는 IDirectMusicLoader::EnableCache 메소드를 사용해 자동적으로 오브젝트를 캐싱 할 수 있다.

특정의 타입의 모든 오브젝트를 플래시 (릴리즈 ) 하도록(듯이) 로더에 지시하려면 ,IDirectMusicLoader::ClearCache 메소드를 호출한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicLoader::GetObject ,오브젝트의 캐싱


IDirectMusicLoader::ScanDirectory

IDirectMusicLoader::ScanDirectory 메소드는, 디스크내가 있는 디렉토리에서, 지정된 쿠라스타이프와 파일 확장자(extension)를 가지는 모든 파일을 검색한다. 파일이 발견될 때마다,IDirectMusicObject::ParseDescriptor 메소드를 호출해, 오브젝트의 GUID 와 이름을 추출한다. 이 정보는 내부 데이타베이스에 보존된다. 어느 디렉토리를 검색한 후, 지정된 모든 파일은 IDirectMusicLoader::EnumObject 메소드의 열거형으로서 이용 가능하게 된다. 더해,IDirectMusicLoader::GetObject 를 사용했을 때에, 파일명없이도 오브젝트가 꺼내 가능하게 된다.

HRESULT ScanDirectory(
  REFGUID rguidClass,
  WCHAR* pwzFileExtension,
  WCHAR* pwzScanFileName
);

파라미터

rguidClass
오브젝트의 클래스 식별자에의 참조 (C++) 또는 주소 (C).
pwzFileExtension
검색 대상의 파일 타입의 파일 확장자(extension). 예를 들어, L"sty" 는 스타일 파일을 의미한다. "*" (을)를 사용해, 임의의 확장자(extension)가 붙은 파일 또는 확장자(extension)가 없는 파일을 검색한다.
pwzScanFileName
캐싱 된 파일 정보의 보존과 취득을 행하기 위한 옵션의 보존 파일의 이름. 최초로 ScanDirectory 를 호출했을 때에 이 파일이 생성 되어 그 이후의 호출로 사용된다. 캐쉬 파일이 불필요한 경우는 NULL 를 지정한다.

반환값

성공하면 S_OK 를 돌려준다. 파일이 발견되지 않았던 경우는 S_FALSE 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_NOT_FOUND
E_FAIL
E_OUTOFMEMORY
E_POINTER
REGDB_E_CLASSNOTREG

주의

검색의 장소를 설정하기 위해서, 최초로 IDirectMusicLoader::SetSearchDirectory 메소드를 호출하지 않으면 안 된다.

pwzScanFileName 로 정의된 파일에, 검색된 정보를 보존할 수 있다. 보존을 실시하면, 변경을 더해진 파일만이 검색되기 (위해)때문에, 그 이후의 ScanDirectory 의 호출이 큰폭으로 고속화된다 (캐쉬 파일은 각 오브젝트의 파일 사이즈와 일자를 보존하므로, 파일이 변경되었을 경우는 그것을 검출할 수 있다).

파일 타입이 복수의 확장자(extension)를 가지고 있는 경우, 확장자(extension) 마다 ScanDirectory 를 1 회 호출한다.

GUID_DirectMusicAllTypes 는 rguidClass 의 유효한 값은 아니다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

디렉토리에서의 오브젝트 검색


IDirectMusicLoader::SetObject

IDirectMusicLoader::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)는 이미 이름을 가지고 있어 이러한 이름을 어플리케이션에 의해 변경할 수 없다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicLoader::GetObject


IDirectMusicLoader::SetSearchDirectory

IDirectMusicLoader::SetSearchDirectory 메소드는, 오브젝트 파일을 검색하기 위한 검색 패스를 설정한다. 1 개의 오브젝트 타입, 또는 모든 파일에 대한 검색 패스를 설정할 수 있다.

HRESULT SetSearchDirectory(
  REFGUID rguidClass,
  WCHAR* pwszPath,
  BOOL fClear
);

파라미터

rguidClass
호출에 관계가 있는 오브젝트의 클래스 식별자에의 참조 (C++) 또는 주소 (C). GUID_DirectMusicAllTypes 는, 모든 타입을 지정한다.
pwszPath
디렉토리의 파일 패스. 길이가 MAX_PATH 이하의 유효한 디렉토리명이 아니면 안된다.
fClear
TRUE 의 경우, 디렉토리를 설정하기 전에, 오브젝트에 관한 모든 정보를 소거한다. 이 결과, 같은 이름을 가지는 다른 디렉토리에 있는 오브젝트에의 액세스를 회피할 수 있다. 다만, 그러한 오브젝트는 캐쉬로부터 삭제되는 것은 아니다.

반환값

성공하면 S_OK 를 돌려준다. 검색 디렉토리가 이미 pwszPath 로 설정되어 있는 경우는 S_FALSE 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_OUTOFMEMORY
E_POINTER
DMUS_E_LOADER_BADPATH

주의

검색 패스를 설정한 후, 로더는 파일명을 사용해 오브젝트를 로드할 때, 풀 패스명을 필요로 하지 않는다. 이 결과, 오브젝트는 풀 패스를 파악하고 있지 않아도 다른 오브젝트를 참조할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicLoader::ScanDirectory ,로더의 검색 디렉토리의 설정


IDirectMusicObject

파일로부터 로드할 수 있는 모든 DirectMusic 오브젝트는, DirectMusic 로더와 조합해 동작하도록(듯이),IDirectMusicObject 인터페이스를 지원 하고 있다. 새로운 타입의 오브젝트는, 이 인터페이스를 이행 해야 한다. 상세한 것에 대하여는, 「커스텀 로드」를 참조할것.

대부분의 어플리케이션은, 이 인터페이스의 메소드를 직접 사용하지 않는다. 다만,IDirectMusicObject::GetDescriptor 를 사용해, 오브젝트의 이름, GUID, 파일 패스, 버젼 등, 오브젝트에 관한 정보를 문의할 수가 있다.

IDirectMusicObject 인터페이스는, 다른 인터페이스의 QueryInterface 메소드를 호출하는 것에 의해 취득해야 한다. CoCreateInstance 를 사용해 호출할 수 없다.

IDirectMusicObject 인터페이스는, 이하의 메소드를 지원 한다.

디스크립터 | GetDescriptor
 | ParseDescriptor
 | SetDescriptor

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDMUS_OBJECT 형은,IDirectMusicObject 인터페이스에의 포인터로서 정의되고 있다.

typedef IDirectMusicObject __RPC_FAR *LPDMUS_OBJECT;

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

DirectMusic 로더,커스텀 로드


IDirectMusicObject::GetDescriptor

IDirectMusicObject::GetDescriptor 메소드는, 오브젝트의 내부적인 기술을 꺼낸다.

이 메소드는 DMUS_OBJECTDESC 구조몸을 잡아, 오브젝트가 스스로에 임해서 지는 모든 일을 그 구조체에 입력한다.

HRESULT GetDescriptor(
  LPDMUS_OBJECTDESC pDesc
);

파라미터

pDesc
오브젝트에 관한 데이터를 입력하기 위한 DMUS_OBJECTDESC 구조체의 주소. 오브젝트의 이행과 오브젝트를 파일로부터 로드한 방법에 근거해,GetDescriptor 가 표준적인 파라미터의 일부 또는 모든 것을 입력한다. dwValidData 멤버내의 플래그를 체크해, 다른 어느 멤버가 유효한가 파악한다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

주의

구체적인 예에 대해서는, 「오브제크트데스크리프타의 취득」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicObject::SetDescriptor


IDirectMusicObject::ParseDescriptor

IDirectMusicObject::ParseDescriptor 메소드는 파일 스트림을 받아,DMUS_OBJECTDESC 구조체에 보존할 수 있는 데이터를 파일로부터 검색한다. dwValidData 내에서, 공급된 멤버에 대해서 적절한 플래그를 할당한다.

이 메소드는, 주로 로더가 디렉토리에서 오브젝트를 검색할 때에 사용되는 것이어, 보통은 어플리케이션이 직접 이용할 것은 없다. 다만, 어플리케이션이 DirectMusic 내에 오브젝트 타입을 이행 하는 경우, 그 어플리케이션은 이 메소드를 지원 해야 한다.

HRESULT ParseDescriptor(
  LPSTREAM pStream,
  LPDMUS_OBJECTDESC pDesc
);

파라미터

pStream
파일의 스트림 소스.
pDesc
파일에 관한 데이터를 받는 DMUS_OBJECTDESC 구조체의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_CHUNKNOTFOUND
DMUS_E_INVALID_BAND
DMUS_E_INVALIDFILE
DMUS_E_NOTADLSCOL
E_POINTER

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicObject::SetDescriptor


IDirectMusicObject::SetDescriptor

IDirectMusicObject::SetDescriptor 메소드는, 오브젝트의 내부적인 기술을 일부 또는 모든 멤버로 설정한다.

이 메소드는, 주로 로더가 오브젝트를 생성 할 때에 사용되는 것이어, 보통은 어플리케이션이 직접 이용할 것은 없다. 다만, 어플리케이션이 DirectMusic 내에 오브젝트 타입을 이행 하는 경우, 그 어플리케이션은 이 메소드를 지원 해야 한다.

HRESULT SetDescriptor(
  LPDMUS_OBJECTDESC pDesc
);

파라미터

pDesc
오브젝트에 관한 데이터를 받는 DMUS_OBJECTDESC 구조체의 주소. dwValidData 멤버로 유효라고 정의 떠날 수 있어 모든 멤버에 데이터가 카피된다.

반환값

성공하면 S_OK 또는 S_FALSE ( 「주의」를 참조할것)를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_INVALIDARG
E_POINTER

주의

어플리케이션은 보통, 표준적인 오브젝트에 대해서 이 메소드를 호출할 것은 없다. IDirectMusicObject::GetDescriptor 에 의해 돌려주어지는 오브젝트 디스크립터를 변경하는 것은 가능하지만, 새로운 기술을 IDirectMusicLoader::GetObject 메소드에 정상적으로 건네줄 수 없다. 예를 들어, 오브젝트의 이름은 변경할 수 있지만,GetObject 는 오브젝트의 전의 이름을 사용해 그 오브젝트를 검색한다. 이것은,GetObject 가 오브젝트 자신의 SetDescriptor 의 이행에 의존하고 있기 때문에 있다.

카피되지 않았던 멤버는, 지금까지의 값을 유지한다. 예를 들어, 어느 오브젝트가 이름과 GUID 를 이미 내부에서 보존하고 있었다고 한다. 새로운 이름과 파일 패스를 지정해 (한층 더 dwValidData 에 DMUS_OBJ_NAME | DMUS_OBJ_FILENAME 를 포함해) SetDescriptor 메소드를 호출하면, 이름은 옮겨놓을 수 있어 파일명이 공급되지만, GUID 만일 수 있는은 원의 값대로 된다.

오브젝트가 1 개 또는 복수의 멤버를 설정할 수 없는 경우, 스스로가 지원 하고 있는 멤버만을 설정해, 지원 하고 있지 않는 멤버에 대응하는 dwValidData 내의 플래그를 소거해, S_FALSE 를 돌려준다. 어플리케이션에 의해 정의되는 오브젝트는, 적어도 DMUS_OBJ_NAME 와 DMUS_OBJ_OBJECT 를 지원 해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicObject::ParseDescriptor ,IDirectMusicObject::GetDescriptor


IDirectMusicPerformance

IDirectMusicPerformance 인터페이스는, 음악 재생의 종합적인 매니저이다. 이 인터페이스는, 포트의 추가와 삭제, 퍼포먼스 채널의 포트에의 맵핑, 세그먼트(segment)의 연주, 툴에 의한 메세지의 발신과 루팅, 이벤트 통지의 요구라고 받아들여, 및 뮤직 파라미터의 설정과 꺼내에 사용된다. 또, 타이밍에 관한 정보의 취득, 및 시스템간에 타임과 뮤직값을 변환하기 위한 메소드도 갖추고 있다.

어플리케이션이 2 개의 완전한 뮤직 세트를 동시에 연주하고 싶은 경우, 복수의 퍼포먼스를 생성 하는 것으로써, 그러한 연주를 실시할 수 있다. 개별의 퍼포먼스는 독립한 템포 맵에 따라, 완전하게 비동기에게 연주되지만, 한편으로 1 개의 퍼포먼스내의 모든 세그먼트(segment)는 고정적인 스텝에서 연주된다.

IDirectMusicPerformance 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

채널 | AssignPChannel
 | AssignPChannelBlock
 | PChannelInfo
악기 | DownloadInstrument
메세지 | AllocPMsg
 | FreePMsg
 | SendPMsg
MIDI 변환 | MIDIToMusic
 | MusicToMIDI
통지 | AddNotificationType
 | GetNotificationPMsg
 | RemoveNotificationType
 | SetNotificationHandle
파라미터 | GetGlobalParam
 | GetParam
 | SetGlobalParam
 | SetParam
포트 | AddPort
 | RemovePort
세그먼트(segment) | GetSegmentState
 | IsPlaying
 | PlaySegment
 | Stop
타이밍 | AdjustTime
 | GetBumperLength
 | GetLatencyTime
 | GetPrepareTime
 | GetQueueTime
 | GetResolvedTime
 | GetTime
 | MusicToReferenceTime
 | ReferenceToMusicTime
 | RhythmToTime
 | SetBumperLength
 | SetPrepareTime
 | TimeToRhythm
툴 | GetGraph
 | SetGraph
그 외 | CloseDown
 | Init
 | Invalidate

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicPerformance::AddNotificationType

IDirectMusicPerformance::AddNotificationType 메소드는, 퍼포먼스에 통지 타입을 추가한다. AddNotificationType 메소드를 호출하면, 모든 세그먼트(segment)와 트랙은 새로운 통지에 의해 자동적으로 갱신된다.

HRESULT AddNotificationType(
  REFGUID rguidNotificationType
);

파라미터

rguidNotificationType
추가되는 통지 타입의 식별자에의 참조 (C++) 또는 주소 (C). 정의 끝난 타입에 대해서는, 「DMUS_NOTIFICATION_PMSG 」를 참조할것. 어플리케이션은, 커스텀 트랙에 도착해 독자적인 타입을 정의할 수 있다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_OUTOFMEMORY
E_POINTER

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::RemoveNotificationType ,IDirectMusicSegment::AddNotificationType ,IDirectMusicTrack::AddNotificationType ,통지와 이벤트의 처리


IDirectMusicPerformance::AddPort

IDirectMusicPerformance::AddPort 메소드는, 퍼포먼스에 포트를 할당한다.

HRESULT AddPort(
  IDirectMusicPort* pPort
);

파라미터

pPort
추가하는 포트를 포함한 변수의 주소. NULL 의 경우는 디폴트 포트가 추가된다. 「주의」를 참조할것.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_NOT_INIT
DMUS_E_CANNOT_OPEN_PORT
E_OUTOFMEMORY
E_POINTER

주의

이 메소드에 NULL 를 건네주고 싶은 경우는, 최초로IDirectMusicPerformance::Init 에 NULL 를 건네줄 필요가 있다.

pPort 에 NULL 를 건네주어 디폴트 포트가 지정되었을 경우, 이 디폴트 포트에는 1 개의 채널 그룹을 할당할 수 있다. 그 외의 포트에 대해 P 채널 이 설정되어 있지 않은 경우, 0 ~ 15 의 P 채널이, 0 ~ 15 의 MIDI 채널에 할당할 수 있다.

pPort 가 NULL 가 아닌 경우,IDirectMusicPort::Activate 의 호출에 의해 포트를 액티브화해,IDirectMusicPerformance::AssignPChannelBlock 의 호출에 의해 채널 블록을 할당하지 않으면 안 된다.

이 메소드는,IDirectMusicPerformance::RemovePort 또는 IDirectMusicPerformance::CloseDown 에 의해 릴리즈 되는 IDirectMusicPort 에의 참조를 생성 한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::RemovePort ,디폴트 포트


IDirectMusicPerformance::AdjustTime

IDirectMusicPerformance::AdjustTime 메소드는, 퍼포먼스의 내부 시간을 전방 또는 후방에 조정한다. 이 메소드는 대부분의 경우, 다른 소스와의 동기화를 실시할 때에 차이를 보정하기 위해서 사용된다.

HRESULT AdjustTime(
  REFERENCE_TIME rtAmount
);

파라미터

rtAmount
덧셈 또는 뺄셈 되는 시간. －10,000,000 에서 10,000,000 (－1 초부터 +1 초)의 수치를 지정한다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_INVALIDARG 를 돌려준다.

주의

조정된 시간은, DirectMusic 에 의해 내부적으로 사용된다. IDirectMusicPerformance::GetTime 메소드에 의해 꺼내지는 시간에는 반영되지 않는다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::GetTime ,타이밍


IDirectMusicPerformance::AllocPMsg

IDirectMusicPerformance::AllocPMsg 메소드는, 퍼포먼스 메세지를 할당한다.

HRESULT AllocPMsg(
  ULONG cb,
  DMUS_PMSG** ppPMSG
);

파라미터

cb
메세지 구조체의 사이즈. 다른 다양한 타입에 대해서는, 「메세지」를 참조할것.
ppPMSG
할당할 수 있었던 메세지 구조체에의 포인터를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

주의

돌려주어진 메모리는 특정 상태에 초기화되어 있지 않다. 다만,DMUS_PMSG 구조체의 pTool 멤버와 dwSize 멤버는 예외로, 전자는 0 에 초기화되어 후자는 cb 의 값으로 설정된다.

메세지가 IDirectMusicPerformance::SendPMsg 에 의해 일단 송신되면(자), 어플리케이션은 메모리를 확보하지 않고, 메세지의 릴리즈도 실시하지 않는다. 다만, 툴은, 그 IDirectMusicTool::Flush 메소드 또는 IDirectMusicTool::ProcessPMsg 메소드내에서 메세지를 릴리즈 할 수 있다. 어플리케이션은, 통지 메세지의 릴리즈도 실시한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::FreePMsg ,IDirectMusicPerformance::SendPMsg ,DirectMusic 메세지


IDirectMusicPerformance::AssignPChannel

IDirectMusicPerformance::AssignPChannel 메소드는, 1 개의 퍼포먼스 채널 (P 채널)을 퍼포먼스에 할당해 이 채널을 포트, 그룹,MIDI 채널에 맵 한다.

HRESULT AssignPChannel(
  DWORD dwPChannel,
  IDirectMusicPort* pPort,
  DWORD dwGroup,
  DWORD dwMChannel
);

파라미터

dwPChannel
할당할 수 있는 P 채널.
pPort
P 채널의 할당처의 포트를 포함한 변수의 주소.
dwGroup
포트 위에의 채널 그룹.
dwMChannel
그룹내의 채널. 0 ~ 15 의 범위가 아니면 안된다.

반환값

성공하면 S_OK 또는 S_FALSE ( 「주의」를 참조할것)를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_INVALIDARG
E_POINTER

주의

dwGroup 가 포트의 범위외의 경우, 이 메소드는 S_FALSE 를 돌려준다. 채널은 할당할 수 있지만, 포트는 그 그룹을 연주할 수 없다.

dwMChannel 가 범위외, 또는 IDirectMusicPerformance::AddPort 메소드를 호출해 포트를 퍼포먼스에 추가하는 작업을 실시하지 않은 경우, 이 메소드는 E_INVALIDARG 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::AssignPChannelBlock ,IDirectMusicPerformance::PChannelInfo ,채널


IDirectMusicPerformance::AssignPChannelBlock

IDirectMusicPerformance::AssignPChannelBlock 메소드는, 16 의 퍼포먼스 채널 (P 채널)로부터 완성되는 그룹을 퍼포먼스에 할당해 그것들을 포트와 채널 그룹에 맵 한다. 포트를 퍼포먼스에 추가했을 때는, 이 메소드를 호출하지 않으면 안 된다. 다만,IDirectMusicPerformance::AddPort 에 NULL 를 건네주는 것에 의해디폴트 포트를 추가했을 경우를 제외하다.

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

주의

dwGroup 가 포트의 범위외의 경우, 이 메소드는 S_FALSE 를 돌려준다. 채널은 할당할 수 있지만, 포트는 그 그룹을 연주할 수 없다.

dwMChannel 가 범위외, 또는 IDirectMusicPerformance::AddPort 메소드를 호출해 포트를 퍼포먼스에 추가하는 작업을 실시하지 않은 경우, 이 메소드는 E_INVALIDARG 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::AssignPChannel ,IDirectMusicPerformance::PChannelInfo ,채널


IDirectMusicPerformance::CloseDown

IDirectMusicPerformance::CloseDown 메소드는, 퍼포먼스 오브젝트를 닫는다. 퍼포먼스 오브젝트를 생성 해, 그 오브젝트에 대해서 IDirectMusicPerformance::Init 를 호출한 어플리케이션은, 퍼포먼스를 릴리즈 하기 전에 CloseDown 를 호출하지 않으면 안 된다.

HRESULT CloseDown();

파라미터

없음.

반환값

S_OK 를 돌려준다.

주의

CloseDown 의 호출을 잊으면(자), 메모리 누수나 프로그램 장해가 발생하는 일이 있다.

어플리케이션이 NULL 또는 NULL 에의 포인터를 IDirectMusicPerformance::Init 에 건네주어 DirectMusic 오브젝트가 생성 되었을 경우,CloseDown 는 IDirectMusic 인터페이스를 처리한다. 어플리케이션이 DirectMusic 오브젝트를 명시적으로 생성 해,Init 에의 포인터를 건네주었을 경우에는, 그 어플리케이션이 IDirectMusic 인터페이스를 릴리즈 해야 한다.

CloseDown 는, 아직 언로드되어 있지 않은 임의의 다운로드 끝난 음색도 릴리즈 한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::Init


IDirectMusicPerformance::DownloadInstrument

IDirectMusicPerformance::DownloadInstrument 메소드는, 음색의 DLS 데이터를 포트에 다운로드한다.

HRESULT DownloadInstrument(
  IDirectMusicInstrument* pInst,
  DWORD dwPChannel,
  IDirectMusicDownloadedInstrument** ppDownInst,
  DMUS_NOTERANGE* pNoteRanges,
  DWORD dwNumNoteRanges,
  IDirectMusicPort** ppPort,
  DWORD* pdwGroup,
  DWORD* pdwMChannel
);

파라미터

pInst
다운로드하는 음색을 포함한 변수의 주소.
dwPChannel
악기의 할당처의 퍼포먼스 채널 (P 채널).
ppDownInst
다운로드된 악기에의 포인터를 받는 변수의 주소.
pNoteRanges
DMUS_NOTERANGE 구조체의 배열의 주소. 배열내의 각 엔트리는, 악기가 응답해야 하는 MIDI 음표 메세지의 연속 범위를 지정한다. 음색의리젼이 다운로드되는 것은, 그 리젼내의 적어도 1 개의 음표가 DMUS_NOTERANGE 구조체로 지정되고 있는 경우에 한정된다.
dwNumNoteRanges
pNoteRanges 가 가리키는 배열내의 DMUS_NOTERANGE 구조체의 수. 이 값이 0 으로 설정되어 있는 경우,pNoteRanges 파라미터는 무시되어 이 음색용의 모든 리젼과 웨이브 데이터가 다운로드된다.
ppPort
음색의 다운로드처의 포트에의 포인터를 받는 변수의 주소.
pdwGroup
음색의 할당처의 그룹을 받는 변수의 주소.
pdwMChannel
음색의 할당처의 MIDI 채널을 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_INVALIDARG
E_POINTER

주의

음색의 다운로드는 보통, 밴드에 의해 처리되기 (위해)때문에, 대부분의 어플리케이션에서는 이 메소드를 사용할 필요가 없다. 「밴드의 다운로드와 언로드」를 참조할것.

P 채널을 포트에 할당할 수 있지 않은 경우, 이 메소드는 E_INVALIDARG 를 돌려준다.

리소스의 낭비를 막으려면 , 음색이 불필요하게 되었을 때에,IDirectMusicPort::UnloadInstrument 메소드를 사용해 언로드한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPort::DownloadInstrument, ,IDirectMusicPort::UnloadInstrument ,음색의 조작


IDirectMusicPerformance::FreePMsg

IDirectMusicPerformance::FreePMsg 메소드는, 메세지를 릴리즈 한다.

HRESULT FreePMsg(
  DMUS_PMSG* pPMSG
);

파라미터

pPMSG
릴리즈 하는 메세지를 포함한 변수의 주소. 이 메세지는,IDirectMusicPerformance::AllocPMsg 메소드로 할당할 수 있던 것이 아니면 안된다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_CANNOT_FREE
E_POINTER

주의

대부분의 메세지는, 처리되면(자), 퍼포먼스에 의해 자동적으로 릴리즈 된다. 또,IDirectMusicPerformance::SendPMsg 를 사용해 송신된 메세지에 대해서,IDirectMusicPerformance::FreePMsg 를 호출해서는 안 된다. 다만,IDirectMusicPerformance::FreePMsg 를 IDirectMusicTool::ProcessPMsg 또는 IDirectMusicTool::Flush 내에서 사용해, 불필요한 메세지를 릴리즈 할 수 있다. 통지 메세지를 릴리즈 할 때에도,IDirectMusicPerformance::FreePMsg 를 사용해야 한다.

이 메소드는, 이하의 경우에 DMUS_E_CANNOT_FREE 를 돌려준다.

  • pPMSG 가,AllocPMsg 를 사용해 할당한 메세지를 나타내지 않은 경우.
  • IDirectMusicPerformance::SendPMsg 를 호출했기 때문에 pPMSG 가 현재 퍼포먼스 큐에 놓여져 있는 경우.
  • pPMSG 가 이미 릴리즈 되고 있는 경우.

pTool,pGraph,punkUser 몇개의 멤버 (DMUS_PMSG 를 참조) 내에 값이 존재하는 경우, 참조되고 있는 각 오브젝트는 릴리즈 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::AllocPMsg ,DirectMusic 메세지


IDirectMusicPerformance::GetBumperLength

IDirectMusicPerformance::GetBumperLength 메소드는, 메세지가 포트 버퍼에 놓여진 타임과 포트가 메세지의 처리를 시작 하는 타임의 사이의 시간이 걸리기 시작한다. 이 항목의 개요에 대해서는, 「타이밍」을 참조할것.

HRESULT GetBumperLength(
  DWORD* pdwMilliSeconds
);

파라미터

pdwMilliSeconds
연주전의 시간의 길이를 포함한 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

주의

디폴트의 값은 50 밀리 세컨드 (ms)이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::SetBumperLength


IDirectMusicPerformance::GetGlobalParam

IDirectMusicPerformance::GetGlobalParam 메소드는, 퍼포먼스로부터 글로벌값을 꺼낸다.

HRESULT GetGlobalParam(
  REFGUID rguidType,
  void* pParam,
  DWORD dwSize
);

파라미터

rguidType
데이터 타입의 식별자에의 참조 (C++) 또는 주소 (C).
pParam
데이터의 카피를 받기 위해서(때문에) 할당할 수 있었던 메모리에의 포인터. pParam 에는 올바른 사이즈를 지정해야 한다. 사이즈는 각 데이터 타입에 대해 일정한다. 이 파라미터는,IDirectMusicPerformance::SetGlobalParam 메소드에게 건네진 정보를 포함한다.
dwSize
데이터의 사이즈. rguidType 마다 일정한 값이다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_INVALIDARG
E_POINTER

주의

SetGlobalParam 가 rguidType 에 대해 한번도 불려 갔던 적이 없는 경우, 이 퍼포먼스가 현재 처리하고 있는 글로벌 데이터 리스트안에,rguidType 가 없을 가능성이 있다. 그 경우, 이 메소드는 E_INVALIDARG 를 돌려준다. 즉, 어느 파라미터에도,GetGlobalParam 를 사용해 꺼낼 수 있는 디폴트값이 있으면(자) 상정하지 않는 것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::SetGlobalParam ,IDirectMusicPerformance::GetParam ,뮤직 파라미터


IDirectMusicPerformance::GetGraph

IDirectMusicPerformance::GetGraph 메소드는, 퍼포먼스의 툴 그래프를 꺼낸다.

HRESULT GetGraph(
  IDirectMusicGraph** ppGraph
);

파라미터

ppGraph
툴 그래프에의 포인터를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_NOT_FOUND
E_POINTER

주의

그래프의 참조 카운트는 인크리먼트(increment) 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::SetGraph ,IDirectMusicSegment::GetGraph ,IDirectMusicPerformance::SendPMsg


IDirectMusicPerformance::GetLatencyTime

IDirectMusicPerformance::GetLatencyTime 메소드는, 현재의 지연 시간이 걸리기 시작한다. 지연 시간은, 스피커로부터 음악이 들리고 있는 시간에, 메세지를 큐에 넣어 IDirectMusicPort 에 렌더링하기 위한 소요 시간을 더한 길이가 된다. 이 항목의 개요에 대해서는, 「타이밍」을 참조할것.

HRESULT GetLatencyTime(
  REFERENCE_TIME * prtTime
);

파라미터

prtTime
현재의 지연 시간을 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_POINTER
DMUS_E_NO_MASTER_CLOCK

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicPerformance::GetNotificationPMsg

IDirectMusicPerformance::GetNotificationPMsg 메소드는, 보류중의 통지 메세지를 꺼낸다.

HRESULT GetNotificationPMsg(
  DMUS_NOTIFICATION_PMSG** ppNotificationPMsg
);

파라미터

ppNotificationPMsg
DMUS_NOTIFICATION_PMSG 구조체에의 포인터를 받는 변수의 주소. 이 메세지를 받아들인 어플리케이션은, 그 메세지에 대해서 IDirectMusicPerformance::FreePMsg 를 호출할 책임이 있다.

반환값

성공하면 S_OK 를 돌려준다. 돌려주어지는 통지 이벤트가 존재하지 않는 경우는 S_FALSE 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

주의

구체적인 예에 대해서는, 어레인지의 사용법을 기재한 튜토리얼의 「스텝 9 : 통지의 처리」를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

통지와 이벤트의 처리


IDirectMusicPerformance::GetParam

IDirectMusicPerformance::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)의 상세한 것에 대하여는, 「세그먼트(segment)」 및 「DMUS_SEGF_FLAGS 」를 참조할것.

다른 제어 세그먼트(segment)가 삽입되는 경우,*pParam 로 돌려주어지는 데이터는,*pmtNext 로 돌려주어지는 타임의 전에 무효가 되는 일이 있다.

각 트랙은 1 개 또는 복수의 그룹에 소속하지만, 각 그룹은 dwGroupBits 내의 비트에 의해 나타내지고 있다. 상세한 것에 대하여는, 「IDirectMusicSegment::InsertTrack 」 및 「트랙의 식별」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::SetParam ,IDirectMusicSegment::GetParam ,IDirectMusicTrack::GetParam ,IDirectMusicPerformance::SetGlobalParam ,IDirectMusicPerformance::GetTime ,뮤직 파라미터


IDirectMusicPerformance::GetPrepareTime

IDirectMusicPerformance::GetPrepareTime 메소드는,IDirectMusicTrack::Play 를 호출하고 나서, 스피커를 통해 메세지가 실제로 (들)물을 때까지의 시간이 걸리기 시작한다. 이전 격은, 툴이 메세지를 처리하는데 충분한 시간이다.

HRESULT GetPrepareTime(
  DWORD* pdwMilliSeconds
);

파라미터

pdwMilliSeconds
준비 시간을 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

주의

디폴트의 값은 1,000 밀리 세컨드 (ms)이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::SetPrepareTime ,타이밍


IDirectMusicPerformance::GetQueueTime

IDirectMusicPerformance::GetQueueTime 메소드는, 현재의 플래시 시간이 걸리기 시작한다. 플래시 시간이란, 큐내의 메세지를 플래시 (릴리즈) 할 수 있는 가장 빠른 타임이다. 이 타임보다 빠른 타임의 타임 스탬프를 가지는 메세지는, 이미 포트에 송신되고 있어 무효화할 수가 없다.

HRESULT GetQueueTime(
  REFERENCE_TIME * prtTime
);

파라미터

prtTime
현재의 플래시 시간을 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_POINTER
DMUS_E_NO_MASTER_CLOCK

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

지연 시간과 범퍼 시간


IDirectMusicPerformance::GetResolvedTime

IDirectMusicPerformance::GetResolvedTime 메소드는, 지정된 타임을, 지정된 경계에 해결한다.

HRESULT GetResolvedTime(
  REFERENCE_TIME rtTime,
  REFERENCE_TIME* prtResolved,
  DWORD dwTimeResolveFlags
);

파라미터

rtTime
해결하는 타임. 이 타임이 현재 타임보다 빠른 경우는, 현재 타임이 사용된다.
prtResolved
해결 지음의 타임을 받는 변수의 주소.
dwTimeResolveFlags
희망의 분해가능을 기술하는 1 개(살) 또는 복수의 DMUS_TIME_RESOLVE_FLAGS .

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

타이밍


IDirectMusicPerformance::GetSegmentState

IDirectMusicPerformance::GetSegmentState 메소드는, 현재 연주중의 프라이머리 세그먼트(segment) 상태, 또는 특정의 시점에서 연주되고 있는 프라이머리 세그먼트(segment) 상태를 꺼낸다.

HRESULT GetSegmentState(
  IDirectMusicSegmentState ** ppSegmentState,
  MUSIC_TIME mtTime
);

파라미터

ppSegmentState
세그먼트(segment) 상태에의 포인터를 받는 변수의 주소. 호출원래는, 이 포인터에 대해서 Release 를 호출할 책임이 있다.
mtTime
세그먼트(segment) 상태가 꺼내지는 타임.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_NOT_FOUND
E_POINTER

주의

현재 연주되고 있는 세그먼트(segment) 상태를 취득하려면 ,IDirectMusicPerformance::GetTime 메소드를 사용해 돌려주어지는 타임을 건네준다. 현재 연주되고 있는 세그먼트(segment) 상태는, 현재 메세지를 생성하고 있는 세그먼트(segment)를 나타낸다. 지연 시간이 존재하기 위해(때문에), 반드시 현재 연주되고 있는 세그먼트(segment) 상태가 현재 스피커로부터 실제로 들리고 있다고는 할 수 없다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicPerformance::GetTime

IDirectMusicPerformance::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

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

타이밍


IDirectMusicPerformance::Init

IDirectMusicPerformance::Init 메소드는, 퍼포먼스를 DirectMusic 오브젝트와 DirectSound 오브젝트에 관련짓는다.

HRESULT Init(
  IDirectMusic** ppDirectMusic,
  LPDIRECTSOUND pDirectSound,
  HWND hWnd
);

파라미터

ppDirectMusic
퍼포먼스에 할당하는 IDirectMusic 인터페이스 포인터가 있는 경우, 그것을 포함한 변수의 주소. 이 인터페이스의 참조 카운트는 인크리먼트(increment) 된다. IDirectMusicPerformance::AddPort 메소드에 건네주는 포트는, 이 DirectMusic 오브젝트로부터 생성 된 것이 아니면 안된다.

변수에 NULL 가 포함되는 경우, DirectMusic 오브젝트가 생성 되어 인터페이스 포인터가 돌려주어진다.

ppDirectMusic 가 NULL 의 경우, DirectMusic 오브젝트가 생성 되어 퍼포먼스에 의해 내부적으로 사용된다.

「주의」를 참조할것.

pDirectSound
웨이브 출력용으로 디폴트로 사용하는 IDirectSound 인터페이스의 주소. 이 값이 NULL 의 경우, DirectMusic 에 의해 DirectSound 오브젝트가 생성 된다. 다만, DirectSound 오브젝트를 존재할 수 있는 것은 1 개의 프로세스에 대해 1 개 뿐이다. 어플리케이션으로 DirectSound 를 개별적으로 사용하고 있는 경우, 그 인터페이스를 pDirectSound 에 건네주지 않으면 안 된다. 어플리케이션이 DirectMusic 오브젝트를 명시적으로 생성 하는 경우는, 그 인터페이스를 IDirectMusic::SetDirectSound 에 건네주지 않으면 안 된다.
hWnd
DirectSound 의 생성에 사용하는 윈도우 핸들. 이 파라미터는 NULL 이라도 좋다. 그 경우, 전면 윈도우가 사용된다. 「주의」를 참조할것.

pDirectSound 가 NULL 의 경우, 이 파라미터는 무시된다. 그 경우,IDirectSound::SetCooperativeLevel 의 호출에 대해, 어플리케이션이 윈도우 핸들의 설정을 실시하지 않으면 안 된다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_ALREADY_INITED
E_OUTOFMEMORY
E_POINTER

주의

이 메소드는 1 회만 호출해야 하는 것이어, 퍼포먼스가 연주를 시작 하기 전에 호출하지 않으면 안 된다.

DirectMusic 오브젝트는, 이하의 방법의 어느쪽이든을 사용해, 퍼포먼스에 관련지을 수가 있다.

  • 어플리케이션이 독자적인 DirectMusic 오브젝트를 생성 해,IDirectMusic 포인터의 주소를 ppDirectMusic 에 건네주는 것에 의해, 그 오브젝트를 퍼포먼스에 제공한다. 이 경우, 어플리케이션이 IDirectMusic::SetDirectSound 를 호출할 필요가 있기 (위해)때문에,pDirectSound 과 hWnd 의 각 파라미터는 무시된다.
  • 어플리케이션이 퍼포먼스에 의한 DirectMusic 오브젝트의 생성을 허가해, 그 오브젝트에의 포인터를 필요로 한다. 이 경우, 엔트리시의 *ppDirectMusic 는 NULL 로, 종료시에는 IDirectMusic 포인터를 보관 유지한다.
  • 어플리케이션이 퍼포먼스에 의한 그것 자신의 초기화를 허가해, DirectMusic 오브젝트 포인터를 필요로 하지 않는다. 이 경우,ppDirectMusic 는 NULL 이다.

퍼포먼스를 릴리즈 하기 전에,IDirectMusicPerformance::CloseDown 메소드를 사용해 퍼포먼스를 종료해야 한다.

hWnd 파라미터에 NULL 를 건네주어, 현재의 전면 윈도우 핸들을 DirectSound 에 건네줄 수가 있다. 다만, 어플리케이션 윈도우가 초기화중에 전면에 있으면(자) 상정하지 않는 것. 보통, 최상 레벨의 어플리케이션 윈도우 핸들은, DirectMusic, DirectSound, 및 DirectDraw 에게 건네진다. 「IDirectSound::SetCooperativeLevel 」의 「주의」를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

퍼포먼스의 생성,DirectMusic 와 DirectSound 의 통합


IDirectMusicPerformance::Invalidate

IDirectMusicPerformance::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 가 꽤 전의 타임으로, 그 타임에 무효화를 실시할 수 없는 경우는, 이용 가능한 범위에서 가장 빠른 타임을 사용한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

준비 시간,세그먼트(segment)의 타이밍


IDirectMusicPerformance::IsPlaying

IDirectMusicPerformance::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

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicPerformance::MIDIToMusic

IDirectMusicPerformance::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 번의 코드 음정에 비추어 해석된다. 이 구조체는, 8 개의 평행 한 서브 코드를, 각각의 코드 음정, 루트음, 스케일, 및 회전 플래그와 함께 보관 유지한다. 또, 전체적인 키의 루트음도 보관 유지한다.
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 에 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::MusicToMIDI ,뮤직값과 MIDI 음표


IDirectMusicPerformance::MusicToMIDI

IDirectMusicPerformance::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 번의 코드 음정에 비추어 해석된다. 이 구조체는, 8 개의 평행 한 서브 코드를, 각각의 코드 음정, 루트음, 스케일, 및 회전 플래그와 함께 보관 유지한다. 또, 전체적인 키의 루트음도 보관 유지한다.
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 이외의 연주 모드를 사용할 때에 발생하는 일이 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::MIDIToMusic ,뮤직값과 MIDI 음표


IDirectMusicPerformance::MusicToReferenceTime

IDirectMusicPerformance::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

주의

기준 타임은 뮤직 타임보다 정확하기 때문에, 기준 타임부터 뮤직 타임으로 변환해, 또 기준 타임으로 변환한 타임은, 아마 원의 값과는 다르다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::ReferenceToMusicTime ,클럭 타임과 뮤직 타임


IDirectMusicPerformance::PChannelInfo

IDirectMusicPerformance::PChannelInfo 메소드는, 지정된 퍼포먼스 채널의 포트, 그룹, 및 MIDI 채널을 꺼낸다.

HRESULT PChannelInfo(
  DWORD dwPChannel,
  IDirectMusicPort** ppPort,
  DWORD* pdwGroup,
  DWORD* pdwMChannel
);

파라미터

dwPChannel
정보가 필요하게 되는 P 채널.
ppPort
IDirectMusicPort 포인터를 받는 변수의 주소. 포인터가 불필요한 경우는, NULL 이라도 좋다. NULL 이외의 포인터가 돌려주어지는 경우, 참조 카운트는 인크리먼트(increment) 된다. 포인터에 대해서 Release 를 호출하는 것은 어플리케이션이다. 「주의」도 참조할것.
pdwGroup
포트 위에의 그룹에의 포인터를 받는 변수의 주소. 이 값이 불필요한 경우는, NULL 이라도 좋다.
pdwMChannel
그룹내의 MIDI 채널에의 포인터를 받는 변수의 주소. 이 값이 불필요한 경우는, NULL 이라도 좋다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_INVALIDARG
E_POINTER

주의

IDirectMusicPerformance::RemovePort 의 호출에 의해 포트가 삭제되었을 경우,*ppPort 에 NULL 포인터가 돌려주어지지만, 메소드는 성공한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::AssignPChannel ,IDirectMusicPerformance::AssignPChannelBlock


IDirectMusicPerformance::PlaySegment

IDirectMusicPerformance::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)의 시작 타임에 미치는 영향에 대해서는, 「클럭 타임과 뮤직 타임」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

세그먼트(segment)


IDirectMusicPerformance::ReferenceToMusicTime

IDirectMusicPerformance::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

주의

퍼포먼스에 대해 마스터 템포가 설정되어 있는 경우는, 뮤직 타임으로 변환할 때 고려된다. 「글로벌 파라미터의 설정과 꺼내」를 참조할것.

뮤직 타임은 기준 타임만큼 정확하지 않기 때문에, 잘라서 버림을 한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::MusicToReferenceTime ,클럭 타임과 뮤직 타임


IDirectMusicPerformance::RemoveNotificationType

IDirectMusicPerformance::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)로부터 통지 타입을 삭제할 수 없게 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::AddNotificationType ,IDirectMusicSegment::RemoveNotificationType ,IDirectMusicTrack::RemoveNotificationType ,통지와 이벤트의 처리


IDirectMusicPerformance::RemovePort

IDirectMusicPerformance::RemovePort 메소드는, 퍼포먼스로부터 포트를 삭제한다. 이 포트에 맵 되고 있던 모든 P 채널은 무효가 되어, 그 스탬프가 뒤따른 메세지가 연주될 것도 없다.

HRESULT RemovePort(
  IDirectMusicPort* pPort
);

파라미터

pPort
삭제되는 포트.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_INVALIDARG
E_POINTER

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::AddPort


IDirectMusicPerformance::RhythmToTime

IDirectMusicPerformance::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.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::TimeToRhythm


IDirectMusicPerformance::SendPMsg

IDirectMusicPerformance::SendPMsg 메소드는, 퍼포먼스 메세지를 송신한다. 이 메소드는, 트랙의 연주시에 불려 간다. 툴에 의해 불려 가 새로운 데이터를 퍼포먼스에 삽입하는 경우도 있다.

HRESULT SendPMsg(
  DMUS_PMSG* pPMSG
);

파라미터

pPMSG
IDirectMusicPerformance::AllocPMsg 에 의해 할당할 수 있는 메세지.

반환값

성공하면 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 를 호출하기 전에 IDirectMusicGraph::StampPMsg 메소드를 메세지에 대해서 호출해야 하는 것이다. 다만, 메세지를 메인의 출력 툴에 직접 송신하는 경우는, 이 스텝을 생략 해도 괜찮다. 메세지를 퍼포먼스 그래프인 만큼 건네주고 싶은 경우는,IDirectMusicPerformance::QueryInterface 를 호출하는 것에 의해,IDirectMusicGraph 인터페이스를 취득한다. 그 이외의 경우는,IDirectMusicSegment::QueryInterface 를 호출하는 것에 의해, 이 인터페이스를 취득한다. IDirectMusicPerformance::GetGraph 또는 IDirectMusicSegment::GetGraph 를 호출해 이 인터페이스를 취득하려고 하지 않는 것. 이러한 메소드는, 그래프 오브젝트에의 포인터를 돌려주는 것이어, 퍼포먼스 또는 세그먼트(segment)에 대한 IDirectMusicGraph 인터페이스의 이행에의 포인터는 돌려주지 않는다.

퍼포먼스는 보통, 처리가 끝난 메세지를 릴리즈 한다. 상세한 것에 대하여는, 「IDirectMusicPerformance::FreePMsg 」의 「주의」를 참조할것.

다음의 샘플 코드는, 시스템에크스크루시브멧세이지와 템포 메세지의 할당 방법과 송신 방법을 나타낸다.

/* pPerformance 은 유효한 IDirectMusicPerformance 포인터이며,
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 )))
    {
// 모든 필드는, AllocPMsgAll 메소드로부터
// 0 에 초기화된다.
// m_pbSysExData 은, 길이가 m_dwSysExLength 의 데이터를 포함한다
// 배열에의 포인터이라고 가정한다.

        memcpy( pSysEx->abData, m_pbSysExData, m_dwSysExLength );
        pSysEx->dwSize = sizeof(DMUS_SYSEX_PMSG);
        pSysEx->dwLen = dwSysExLength;
        pSysEx->mtTime = mtTime;
        pSysEx->dwFlags = DMUS_PMSGF_MUSICTIME;
        pSysEx->dwType = DMUS_PMSGT_SYSEX;

        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(IDirectMusicPerformance* 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;           // DirectX 6.1 의 경우는 항상 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;

}

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicTool::ProcessPMsg ,메세지,DirectMusic 메세지,DirectMusic 툴


IDirectMusicPerformance::SetBumperLength

IDirectMusicPerformance::SetBumperLength 메소드는, 렌더링의 목적으로 메세지를 포트에 송신하는 경우에, 포트의 지연 시간보다 전에 놓여지는 완충 시간 (범퍼 시간)을 설정한다. 이 항목의 상세한 것에 대하여는, 「타이밍」을 참조할것.

HRESULT SetBumperLength(
  DWORD dwMilliSeconds
);

파라미터

dwMilliSeconds
연주전의 시간의 길이. 단위는 밀리 세컨드 (ms), 디폴트값은 50 이다.

반환값

S_OK 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::GetBumperLength ,IDirectMusicPerformance::SetPrepareTime


IDirectMusicPerformance::SetGlobalParam

IDirectMusicPerformance::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 에 의해 정의되는 파라미터 및 그것들에 관련이 있는 데이터 타입에 대해서는, 「글로벌 파라미터의 설정과 꺼내」를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::GetGlobalParam ,IDirectMusicPerformance::SetParam ,뮤직 파라미터


IDirectMusicPerformance::SetGraph

IDirectMusicPerformance::SetGraph 메소드는, 퍼포먼스의 툴 그래프를 옮겨놓는다.

HRESULT SetGraph(
  IDirectMusicGraph* pGraph
);

파라미터

pGraph
설정되는 툴 그래프. 퍼포먼스로부터 그래프를 소거하기 위해서, NULL 에도 설정할 수 있다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

주의

현재의 툴 그래프내에서 처리중의 모든 메세지는 삭제된다.

이 메소드는 그래프의 참조 카운트를 인크리먼트(increment) 하므로, 오리지날의 참조를 릴리즈 해 두면(자) 안전하다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment::SetGraph ,IDirectMusicPerformance::GetGraph ,IDirectMusicPerformance::SendPMsg


IDirectMusicPerformance::SetNotificationHandle

IDirectMusicPerformance::SetNotificationHandle 메소드는, 통지용의 이벤트 핸들 (Microsoft® Win32® 의 CreateEvent 함수에 의해 생성 된다)을 설정한다. 어플리케이션은, 이 핸들에 대해서 Win32 WaitForSingleObject 함수를 적용해야 한다. 시그널이 송신되었을 때에, 어플리케이션은 IDirectMusicPerformance::GetNotificationPMsg 메소드를 호출해, 통지 이벤트를 꺼내야 하는 것이다.

HRESULT SetNotificationHandle(
  HANDLE hNotification,
  REFERENCE_TIME rtMinimum
);

파라미터

hNotification
CreateEvent 에 의해 생성 된 이벤트 핸들. 기존의 핸들을 소거하는 경우는, 0 을 지정한다.
rtMinimum
퍼포먼스가 낡은 통지 이벤트를 파기하기까지 보관 유지해 두는 최소의 시간. 값으로서 0 을 지정 하면, 디폴트의 최소 값인 20,000,000 기준 타임 단위 (2 초), 또는 이전에 이 메소드를 호출했을 때의 값을 의미한다. 어플리케이션이 아직 GetNotificationPMsg 를 호출하지 않은 경우는, 이 이벤트는 파기되어, 메모리가 릴리즈 된다.

반환값

S_OK 를 돌려준다.

주의

통지 핸들이 불필요하게 되었을 때에는, 어플리케이션이 통지 핸들에 대해서 Win32 CloseHandle 함수를 호출하지 않으면 안 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

통지와 이벤트의 처리


IDirectMusicPerformance::SetParam

IDirectMusicPerformance::SetParam 메소드는,제어 세그먼트(segment)내의 트랙상에 데이터를 설정한다.

HRESULT SetParam(
  REFGUID rguidType,
  DWORD dwGroupBits,
  DWORD dwIndex,
  MUSIC_TIME mtTime,
  void* pParam
);

파라미터

rguidType
설정되는 데이터 타입의 식별자에의 참조 (C++) 또는 주소 (C). 「트랙 파라미터의 타입」을 참조할것.
dwGroupBits
희망의 트랙이 놓여지는 그룹.
dwIndex
데이터의 설정에 사용되는,dwGroupBits 로 식별된 그룹내에서, 트랙에 할당할 수 있고 있는 인덱스.
mtTime
데이터의 설정을 실시하는 타임. IDirectMusicSegment::SetParam 과는 달리, 이 메소드에서는 퍼포먼스 타임을 사용해 이 타임을 나타낸다. 이 타임부터 세그먼트(segment)의 시작 타임을 당겨, 그 결과를 IDirectMusicSegment::GetParam 에 건네준다.
pParam
데이터를 보관 유지하는 구조체의 주소. 이 구조체는,rguidType 로 식별된 데이터 타입에 있어 적절한 종류와 사이즈를 갖추지 않으면 안 된다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_NO_MASTER_CLOCK
DMUS_E_SET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND
E_POINTER

주의

보통, 프라이머리 세그먼트(segment)는 제어 세그먼트(segment)이다. 다만, 세컨드리 세그먼트(segment)를 연주 하면나무는, 이것을 제어 세그먼트(segment)로서 지정할 수 있다. DMUS_SEGF_FLAGS 를 참조할것.

dwGroupBits 와 dwIndex 의 설명에 대해서는, 「트랙의 식별」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::GetParam ,IDirectMusicPerformance::SetGlobalParam ,IDirectMusicSegment::SetParam ,IDirectMusicTrack::SetParam ,IDirectMusicPerformance::GetTime ,뮤직 파라미터


IDirectMusicPerformance::SetPrepareTime

IDirectMusicPerformance::SetPrepareTime 메소드는,IDirectMusicTrack::Play 메소드를 호출하고 나서, 스피커를 통해 메세지가 실제로 (들)물을 때까지의 시간을 설정한다.

HRESULT SetPrepareTime(
  DWORD dwMilliSeconds
);

파라미터

dwMilliSeconds
준비 시간의 길이. 단위는 밀리 세컨드 (ms), 디폴트값은 1,000 이다.

반환값

S_OK 를 돌려준다.

주의

상세한 것에 대하여는, 「타이밍」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::GetPrepareTime ,IDirectMusicPerformance::SetBumperLength


IDirectMusicPerformance::Stop

IDirectMusicPerformance::Stop 메소드는, 1 개(살) 또는 복수의 세그먼트(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)에 관련한다. 다음의 값의 어느쪽이든을 사용하지 않으면 안 된다.
0
즉석에서 정지한다.
DMUS_SEGF_GRID
다음의 그리드 경계 또는 mtTime 의 뒤에 정지한다.
DMUS_SEGF_MEASURE
다음의 소절 경계 또는 mtTime 의 뒤에 정지한다.
DMUS_SEGF_BEAT
다음의 박경계 또는 mtTime 의 뒤에 정지한다.
DMUS_SEGF_DEFAULT
IDirectMusicSegment::SetDefaultResolution 메소드로 설정된 디폴트 경계에서 정지한다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

주의

pSegment 와 pSegmentState 의 양쪽 모두가 NULL 인 경우, 모든 음악은 정지해, 현재 큐에 두어져 모든 세그먼트(segment)가 릴리즈 된다. pSegment 와 pSegmentState 의 어느 쪽인지가 NULL 가 아닌 경우, 지정된 세그먼트(segment) 상태가 퍼포먼스로부터 삭제된다. 양쪽 모두 NULL 는 아니고, 게다가 DMUS_SEGF_DEFAULT 가 사용되고 있는 경우,pSegment 로부터 얻을 수 있던 디폴트의 분해가능을 사용한다.

모든 파라미터에 NULL 또는 0 을 설정 하면, 모든 연주가 즉석에서 정지해, 콘트롤러 리셋 메세지 및 노트 오프 메세지가, 맵 된 모든 P 채널에 송신된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::PlaySegment ,DMUS_SEGF_FLAGS


IDirectMusicPerformance::TimeToRhythm

IDirectMusicPerformance::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.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::RhythmToTime


IDirectMusicPort

IDirectMusicPort 인터페이스는, DirectMusicPort 오브젝트에의 액세스를 제공한다. DirectMusicPort 오브젝트는, 뮤직 데이터를 송신 또는 수신하는 디바이스를 나타낸다. MPU-401 의 입력 포트, MPU-401 의 출력 포트, Microsoft Software Synthesizer, IHV 가 제공하는 필터는, 모두 포트이다. MPU-401 등의 물리적인 디바이스는, 복수의 포트를 제공할 수 있다. 다만, 단일의 포트에서는, 데이터의 캡춰와 렌더링은 할 수 없다.

개요에 대해서는, 「포트의 사용법」을 참조할것.

IDirectMusicPort 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

버퍼 | PlayBuffer
 | Read
 | SetReadNotificationHandle
채널 | GetChannelPriority
 | GetNumChannelGroups
 | SetChannelPriority
 | SetNumChannelGroups
디바이스 관리 | Activate
 | DeviceIoControl
 | SetDirectSound
정보 | GetCaps
 | GetFormat
 | GetLatencyClock
 | GetRunningStats
다운로더블 사운드 | Compact
 | DownloadInstrument
 | UnloadInstrument

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTMUSICPORT 형은,IDirectMusicPort 인터페이스에의 포인터로서 정의되고 있다.

typedef IDirectMusicPort *LPDIRECTMUSICPORT;

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusicSynth::Activate

Platform SDK: DirectX

IDirectMusicPort::Activate

IDirectMusicPort::Activate 메소드는, 포트를 액티브화 또는 비액티브화한다.

HRESULT Activate(
  BOOL fActive
);

파라미터

fActive
포트를 액티브화 (TRUE) 또는 비액티브화 (FALSE)로 전환한다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 DSERR_NODRIVER 를 돌려주어, 사운드 드라이버가 없는 것을 나타낸다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusic::Activate ,포트의 사용법


IDirectMusicPort::Compact

IDirectMusicPort::Compact 메소드를 사용해,DLS 또는 웨이브 테이블의 메모리를 컴팩트화하도록(듯이) 포트에 지시한다. 이 결과, 다운로드되는 새로운 음색이, 최대한이 연속한 메모리체크를 이용할 수 있다.

HRESULT Compact();

파라미터

없음.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_FAIL
E_INVALIDARG
E_NOTIMPL
E_OUTOFMEMORY

주의

이 메소드는, 독자적인 웨이브 테이블 메모리를 관리할 필요가 있는 DLS 디바이스에만 영향을 준다. 독자적인 메모리를 관리하지 않는 포트 (호스트 시스템의 메모리를 이용하는 소프트웨어 신디사이저나 하드웨어 신디사이저)에 대해, 이 메소드는 E_NOTIMPL 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusicPort::DeviceIoControl

IDirectMusicPort::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 는 커널 스트리밍의 실행을 거부할 수 있다. 다만, 유저 정의의 조작은 결코 방해되지 않는다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusicPort::DownloadInstrument

IDirectMusicPort::DownloadInstrument 메소드는,DLS 디바이스에 악기를 다운로드하기 위해서 사용된다. 음색을 다운로드하는 것은, 음색을 구성하는 데이터를 DLS 디바이스에 건네주는 것을 의미한다. 이 안에는, 악기가 필요로 하는 아티큘레이션 데이터와 모든 웨이브가 포함된다. 웨이브의 스페이스를 절약하기 위해서, 그 범위에서 필요하게 되는 웨이브와 아티큘레이션만이 다운로드된다. 이 메소드는 IDirectMusicDownloadedInstrument 인터페이스 포인터를 돌려주지만, 이것은 다음에 악기를 언로드하기 위해서 사용된다.

HRESULT DownloadInstrument(
  IDirectMusicInstrument *pInstrument,
  IDirectMusicDownloadedInstrument **ppDownloadedInstrument,
  DMUS_NOTERANGE *pNoteRanges,
  DWORD dwNumNoteRanges;
  );

파라미터

pInstrument
메소드에 의한 데이터의 다운로드원이 되는 음색.
ppDownloadedInstrument
IDirectMusicDownloadedInstrument 인터페이스에의 포인터를 받는 변수의 주소.
pNoteRanges
DMUS_NOTERANGE 구조체의 배열의 주소. 배열내의 각 엔트리는, 악기가 응답해야 하는 MIDI 음표 메세지의 연속 범위를 지정한다. 음색의리젼이 다운로드되는 것은, 그 리젼내의 적어도 1 개의 음표가 DMUS_NOTERANGE 구조체로 지정되고 있는 경우에 한정된다.
dwNumNoteRanges
pNoteRanges 가 가리키는 배열내의 DMUS_NOTERANGE 구조체의 수. 이 값이 0 으로 설정되어 있는 경우,pNoteRanges 파라미터는 무시되어 이 음색의 모든 리젼과 웨이브 데이터가 다운로드된다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_POINTER
E_OUTOFMEMORY
E_NOTIMPL

주의

메모리의 낭비를 막으려면 , 음색이 불필요하게 되었을 때에,IDirectMusicPort::UnloadInstrument 와 IDirectMusicDownloadedInstrument::Release 의 양쪽 모두를 호출해, 언로드해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPort::Compact ,음색의 조작


IDirectMusicPort::GetCaps

IDirectMusicPort::GetCaps 메소드는, 포트의 능력을 꺼낸다.

HRESULT GetCaps(
  LPDMUS_PORTCAPS pPortCaps
);

파라미터

pPortCaps
포트의 능력을 받는 DMUS_PORTCAPS 구조체의 주소. 이 메소드를 호출하기 전에, 이 구조체의 dwSize 멤버를 올바르게 초기화해야 한다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_POINTER
E_INVALIDARG

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusicPort::GetChannelPriority

IDirectMusicPort::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

이하의 값은,DLS 레벨 1 표준에 의한, 범위내에 있어서의 채널의 디폴트 순위를 나타낸다. 우선 순위의 높은 것으로부터 순서에 리스트 한다. 퍼크션 채널의 채널 10 이, 가장 우선 순위가 높다.

DAUD_CHAN10_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN1_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN2_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN3_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN4_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN5_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN6_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN7_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN8_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN9_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN11_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN12_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN13_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN14_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN15_DEF_VOICE_PRIORITY_OFFSET
DAUD_CHAN16_DEF_VOICE_PRIORITY_OFFSET

채널의 우선 순위는, 범위와 오프셋(offset)를 사용해 나타낸다. 예를 들어, DAUD_STANDARD_VOICE_PRIORITY 와 DAUD_CHAN10_DEF_VOICE_PRIORITY 로, 표준 범위내에서 가장 높은 우선 순위를 나타낸다.

같은 우선 순위값을 가지는 채널은, 소속하는 채널 그룹의 종류에 관계없이, 같은 우선 순위를 가진다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPort::SetChannelPriority


IDirectMusicPort::GetFormat

IDirectMusicPort::GetFormat 메소드는,IDirectMusic::CreatePort 에 건네주는 DMUS_PORTPARAMS 구조체로 지정되는 웨이브 포맷에 관한 정보, 및 웨이브 출력으로 사용하는 버퍼의 추천 사이즈에 관한 정보를 꺼낸다. 이러한 정보를 사용해, 포트용으로 호환성이 있는 IDirectSoundBuffer 를 생성 할 수 있다.

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 바이트를 구조체에 기입한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPort::SetDirectSound


IDirectMusicPort::GetLatencyClock

IDirectMusicPort::GetLatencyClock 메소드는, 포트의 지연 시간 클럭에의 IReferenceClock 인터페이스 포인터를 취득하기 위해서 사용된다. 이 지연 시간 클럭은, 메세지를 연주할 수 있는, 현재에 가장 가까운 장래의 타임을 지정한다. 지연 시간 클럭은,IDirectMusic::SetMasterClock 메소드에 의해 설정되는 DirectMusic master clock에 근거하고 있다.

HRESULT GetLatencyClock(
  IReferenceClock** ppClock
);

파라미터

ppClock
지연 시간 클럭의 IReferenceClock 인터페이스 포인터를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

주의

COM 의 규칙에 따라,GetLatencyClock 는 돌려주어진 인터페이스의 참조 카운트를 늘린다. 그 때문에, 어플리케이션은 어떠한 시점에서 IReferenceClock 인터페이스에 대해서 Release 를 호출하지 않으면 안 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

지연 시간과 범퍼 시간


IDirectMusicPort::GetNumChannelGroups

IDirectMusicPort::GetNumChannelGroups 메소드는, 포트 위에의 채널 그룹의 수를 꺼낸다.

HRESULT GetNumChannelGroups
  LPDWORD pdwChannelGroups
);

파라미터

pdwChannelGroups
채널 그룹의 수를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_FAIL
E_INVALIDARG
E_NOTIMPL
E_OUTOFMEMORY

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPort::SetNumChannelGroups ,채널


IDirectMusicPort::GetRunningStats

IDirectMusicPort::GetRunningStats 메소드는, 포트의 신디사이저 상태에 관한 상태를 꺼낸다.

HRESULT GetRunningStats(
  LPDMUS_SYNTHSTATS pStats
);

파라미터

pStats
신디사이저의 동작 통계를 받는 DMUS_SYNTHSTATS 구조체의 주소. 이 메소드를 호출하기 전에, 이 구조체의 dwSize 멤버를 올바르게 초기화해야 한다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_POINTER
E_INVALIDARG
E_NOTIMPL

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusicPort::PlayBuffer

IDirectMusicPort::PlayBuffer 메소드는, 각 포트의 재생 버퍼에의 삽입을 실시한다.

HRESULT PlayBuffer(
  IDIRECTMUSICBUFFER* pBuffer
);

파라미터

pBuffer
포트의 재생 큐에 추가되는 DirectMusicBuffer 오브젝트의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_FAIL
E_INVALIDARG
E_NOTIMPL
E_OUTOFMEMORY

주의

이 버퍼가 시스템에 의해 사용되는 것은 이 메소드의 지속중 뿐이어서, 이 메소드로부터 제어가 돌아온 후는 재이용할 수 있다.

IDirectMusicBuffer::SetStartTime 메소드에 의해 시작 타임이 설정되어 있지 않은 경우,IDirectMusicBuffer::PackStructured 또는 IDirectMusicBuffer::PackUnstructured 의 각 메소드에 의해 설정되는, 버퍼내의 가장 빠른 이벤트의 타임이 시작 타임이 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicBuffer ,IDirectMusic::CreateMusicBuffer


IDirectMusicPort::Read

IDirectMusicPort::Read 메소드는, 수신한 MIDI 데이터를 버퍼에 입력한다. read에 이용할 수 있는 데이터가 없어질 때까지, 새로운 버퍼 오브젝트에 대해서 이 메소드를 호출해야 하는 것이다.

HRESULT Read(
  IDirectMusicBuffer *pBuffer
);

파라미터

pBuffer
수신 MIDI 데이터의 입력처의 DirectMusicBuffer 오브젝트의 주소.

반환값

성공하면 S_OK 또는 S_FALSE 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_POINTER
E_NOTIMPL

주의

읽어들이는 데이터가 존재하지 않는 경우, 이 메소드는 S_FALSE 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

음악의 캡춰


IDirectMusicPort::SetChannelPriority

IDirectMusicPort::SetChannelPriority 메소드는, MIDI 채널의 우선 순위를 설정하기 위해서 사용된다. 상세한 것에 대하여는, 「채널」을 참조할것.

HRESULT SetChannelPriority(
  DWORD  dwChannelGroup,
  DWORD  dwChannel,
  DWORD  dwPriority
);

파라미터

dwChannelGroup
채널이 놓여져 있는 그룹. 이 값은 1 이상이 아니면 안된다.
dwChannel
그룹내의 채널의 인덱스.
dwPriority
우선 순위. 「IDirectMusicPort::GetChannelPriority 」의 「주의」를 참조할것.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_FAIL
E_INVALIDARG
E_OUTOFMEMORY
E_NOTIMPL

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPort::GetChannelPriority ,DMUS_CHANNEL_PRIORITY_PMSG


IDirectMusicPort::SetDirectSound

IDirectMusicPort::SetDirectSound 메소드는, 포트의 웨이브 데이터가 스트림화 되는 디폴트의 DirectSound 오브젝트 또는 버퍼, 혹은 그 양쪽 모두를 덧쓰기하기 위해서 사용된다. 또, DirectSound 로부터 포트를 접속 해제할 때에도 사용된다.

HRESULT SetDirectSound(
  LPDIRECTSOUND pDirectSound,
  LPDIRECTSOUNDBUFFER pDirectSoundBuffer
);

파라미터

pDirectSound
포트의 접속처가 되는 DirectSound 오브젝트의 IDirectSound 인터페이스의 주소. 기존의 DirectSound 오브젝트를 접속 해제해, 릴리즈 하는 경우는 NULL 를 지정한다.
pDirectSoundBuffer
포트의 접속처가 되는 IDirectSoundBuffer 인터페이스의 주소. 이 값은 NULL 이라도 좋다.

반환값

성공하면 S_OK 또는 DMUS_S_NOBUFFERCONTROL 를 돌려준다. 「주의」를 참조할것.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_ALREADY_ACTIVATED
E_INVALIDARG

주의

유효한 포인터가 pDirectSoundBuffer 에게 건네지면(자), 팬이나 볼륨등의 버퍼내에서의 컨트롤 체인지가 DirectMusic 의 재생에 영향을 주지 않는 경우, 이 메소드는 DMUS_S_NOBUFFERCONTROL 를 돌려준다. 이것은, WDM 인 만큼 영향을 준다.

포트를 액티브화하면(자), 필요에 따라서 DirectSound 프라이머리 버퍼가 업그레이드 되어 이 포트 (IDirectMusic::CreatePort 에게 건네지는 DMUS_PORTPARAMS 구조체로 지정한다)의 샘플링 레이트와 채널 정보를 지원 한다.

pDirectSoundBuffer 가 가리키는 버퍼는, 이 포트의 샘플링 레이트와 채널 정보에 일치하는 포맷을 가지는, 세컨드리 스트리밍 버퍼가 아니면 안된다. 이 파라미터가 NULL 의 경우, 적절한 IDirectSoundBuffer 인스턴스가 내부적으로 생성 된다.

포트를 일단 액티브화하면(자),IDirectSound 도 IDirectSoundBuffer 도 변경할 수 없다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPort::Activate ,IDirectMusicPort::GetFormat ,DirectMusic 와 DirectSound 의 통합


IDirectMusicPort::SetNumChannelGroups

IDirectMusicPort::SetNumChannelGroups 메소드는, 어플리케이션이 포트상에서 필요로 하는 채널 그룹의 수를 변경한다.

HRESULT SetNumChannelGroups(
  DWORD dwChannelGroups
);

파라미터

dwChannelGroups
어플리케이션이 이 포트에 할당하고 싶은 채널 그룹의 수.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_FAIL
E_INVALIDARG
E_NOTIMPL
E_OUTOFMEMORY

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPort::GetNumChannelGroups ,채널


IDirectMusicPort::SetReadNotificationHandle

IDirectMusicPort::SetReadNotificationHandle 메소드는,IDirectMusicPort::Read 메소드를 사용해 MIDI 메세지를 읽어들일 수 있게 되었을 때에 설정되는 이벤트를 지정한다. 새로운 데이터가 이용 가능하게 되면(자), 반드시 이벤트의 시그널이 송신된다. 이벤트 통지를 무효로 하려면 ,hEvent 파라미터의 값으로서 NULL 를 지정해,SetReadNotificationHandle 를 호출한다.

HRESULT SetReadNotificationHandle(
  HANDLE hEvent
);

파라미터

hEvent
Win32 CreateEvent 함수를 호출했을 때에 취득한 이벤트 핸들. 포트가 릴리즈 되면(자), 어플리케이션이 이 핸들을 닫지 않으면 안 된다.

반환값

S_OK 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

음악의 캡춰


IDirectMusicPort::UnloadInstrument

IDirectMusicPort::UnloadInstrument 메소드는, 이전에 다운로드한 DLS 음색을 언로드하기 위해서 사용된다.

HRESULT UnloadInstrument(
  IDirectMusicDownloadedInstrument *pDownloadedInstrument
);

파라미터

pDownloadedInstrument
IDirectMusicPort::DownloadInstrument 메소드를 호출해 음색을 다운로드했을 때에 취득한,IDirectMusicDownloadedInstrument 인터페이스의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_NOT_DOWNLOADED_TO_PORT
E_POINTER
E_NOTIMPL

주의

IDirectMusicPort::DownloadInstrument 에 의해 할당할 수 있었던 메모리를 릴리즈 하려면 , 이 메소드를 호출하지 않으면 안 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

음색의 조작


IDirectMusicPortDownload

IDirectMusicPortDownload 인터페이스를 사용하면(자), 어플리케이션은 DLS 다운로드를 지원 하고 있는 포트와 직접 통신해, 메모리체크를 포트에 직접 다운로드할 수 있다. 이 인터페이스가 주로 사용되는 것은, DLS 음색을 직접 편집하는 어플리케이션을 오쏘링 하면나무이다. 개요에 대해서는 「하위 레벨 DLS 」를 참조할것.

IDirectMusicPortDownload 을 취득하려면 ,IDirectMusicPort::QueryInterface 메소드를 호출해, IID_IDirectMusicPortDownload 를 인터페이스 GUID 로서 건네준다. 포트가 DLS 다운로드를 지원 하고 있지 않는 경우, 이 메소드는 실패한다.

IDirectMusicPortDownload 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

버퍼 관리 | AllocateBuffer
 | GetAppend
 | GetBuffer
 | GetDLId
로드 | Download
 | Unload

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusicPortDownload::AllocateBuffer

IDirectMusicPortDownload::AllocateBuffer 메소드는,DLS 데이터를 포트에 다운로드하기 위한 메모리체크를 할당해 이 버퍼에의 액세스를 가능하게 하는 IDirectMusicDownload 인터페이스 포인터를 돌려준다.

HRESULT AllocateBuffer(
  DWORD dwSize,
  IDirectMusicDownload** ppIDMDownload
);

파라미터

dwSize
요구하는 버퍼의 사이즈.
ppIDMDownload
IDirectMusicDownload 인터페이스 포인터를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_POINTER
E_INVALIDARG
E_OUTOFMEMORY

주의

일단 버퍼를 할당하면(자), 그 사이즈는 변경할 수 없다.

IDirectMusicDownload 인터페이스를 릴리즈 하면, 버퍼도 릴리즈 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPortDownload::GetBuffer ,하위 레벨 DLS


IDirectMusicPortDownload::Download

IDirectMusicPortDownload::Download 메소드는, 웨이브 또는 악기의 정의를 포트에 다운로드한다. 최초로 IDirectMusicPortDownload::AllocateBuffer 메소드를 사용해, 메모리를 할당하지 않으면 안 된다.

HRESULT Download(
  IDirectMusicDownload* pIDMDownload
);

파라미터

pIDMDownload
버퍼용의 IDirectMusicDownload 인터페이스의 주소.

반환값

반환값은 포트의 이행에 의해 정해진다.

성공하면 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 」를 참조할것.

메모리를 다운로드한 후, 그 이상 무엇인가를 실시할 수 없다. 다운로드를 갱신하려면 , 새로운 버퍼를 생성 해,IDirectMusicPortDownload::GetDLId 메소드를 사용해 취득한 새로운 다운로드 ID 를 할당해 그 ID 를 송신해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPortDownload::Unload ,DMUS_DOWNLOADINFO ,DMUS_OFFSETTABLE


IDirectMusicPortDownload::Download

Platform SDK: DirectX

IDirectMusicPortDownload::GetAppend

IDirectMusicPortDownload::GetAppend 메소드는, 포트가 다운로드 버퍼의 마지막에 추가할 필요가 있는 메모리의 양을 꺼낸다. 포트는 이 추가 메모리를 사용해, 루프 경계에 걸쳐 데이터를 보간 할 수 있다.

HRESULT GetAppend(
  DWORD* pdwAppend
);

파라미터

pdwAppend
메모리가 필요한 추가 샘플의 수를 받는 변수의 주소. 메모리의 양은 웨이브 포맷화등 계산할 수 있다.

반환값

반환값은 포트의 이행에 의해 정해진다.

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_POINTER
E_NOTIMPL

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusicPortDownload::GetBuffer

IDirectMusicPortDownload::GetBuffer 메소드는, 일의의 식별자를 이미 알고 있는 버퍼의 IDirectMusicDownload 인터페이스 포인터를 꺼낸다.

HRESULT GetBuffer(
  DWORD dwDLId,
  IDirectMusicDownload** ppIDMDownload
);

파라미터

dwDLId
버퍼의 다운로드 식별자. 「DMUS_DOWNLOADINFO 」를 참조할것.
ppIDMDownload
버퍼의 IDirectMusicDownload 인터페이스 포인터를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_POINTER
DMUS_E_INVALID_DOWNLOADID
DMUS_E_NOT_DOWNLOADED_TO_PORT

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPortDownload::GetDLId ,IDirectMusicDownload::GetBuffer ,하위 레벨 DLS


IDirectMusicPortDownload::GetDLId

IDirectMusicPortDownload::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

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusicPortDownload::GetBuffer ,하위 레벨 DLS


IDirectMusicPortDownload::Unload

IDirectMusicPortDownload::Unload 메소드는, 이전에 IDirectMusicPortDownload::Download 를 사용해 다운로드된 버퍼를 언로드한다.

HRESULT Unload(
  IDirectMusicDownload* pIDMDownload
);

파라미터

pIDMDownload
버퍼용의 IDirectMusicDownload 인터페이스의 주소.

반환값

반환값은 포트의 이행에 의해 정해진다.

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_NOINTERFACE
DMUS_E_SYNTHNOTCONFIGURED

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusicSegment

IDirectMusicSegment 인터페이스는, 세그먼트(segment), 즉 복수의 트랙으로 구성되어 있는 뮤직크체크를 나타낸다. 세그먼트(segment)를 정의하는 거의 모든 정보가 트랙내에 보존되고 있어, 트랙은 어떠한 것이어도 상관없기 때문에, 세그먼트(segment) 자체는 비교적 간결한 오브젝트이다. 세그먼트(segment) 오브젝트는 데이터의 성질을 파악하고 있지 않다고는 해도, 트랙내의 데이터에 액세스 하는 메소드는 얼마든지 있다.

DirectMusicSegment 오브젝트는, 스스로의 데이터를 로드하기 위해서(때문에) IDirectMusicObject 와 IPersistStream 의 각 인터페이스도 지원 하고 있다.

IDirectMusicSegment 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

타이밍과 루프 | GetDefaultResolution
 | GetLength
 | GetLoopPoints
 | GetRepeats
 | GetStartPoint
 | SetDefaultResolution
 | SetLength
 | SetLoopPoints
 | SetRepeats
 | SetStartPoint
트랙 | GetTrack
 | GetTrackGroup
 | InsertTrack
 | RemoveTrack
통지 | AddNotificationType
 | RemoveNotificationType
파라미터 | GetParam
 | SetParam
툴 | GetGraph
 | SetGraph
그 외 | Clone Clone
 | InitPlay
 | SetPChannelsUsed

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

세그먼트(segment)


IDirectMusicSegment::AddNotificationType

IDirectMusicSegment::AddNotificationType 메소드는,IDirectMusicPerformance::AddNotificationType 메소드를 닮아 있어, 이 메소드로부터 불려 간다. 전자는, 세그먼트(segment)가 통지에 응답할 수 있도록(듯이) 한다. 세그먼트(segment)은, 각 트랙의 IDirectMusicTrack::AddNotificationType 메소드를 호출한다.

HRESULT AddNotificationType(
  REFGUID rguidNotificationType
);

파라미터

rguidNotificationType
추가되는 통지 타입의 식별자에의 참조 (C++) 또는 주소 (C). 정의 끝난 타입에 대해서는, 「DMUS_NOTIFICATION_PMSG 」를 참조할것. 어플리케이션은, 커스텀 트랙에 도착해 독자적인 타입을 정의할 수 있다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_POINTER
E_OUTOFMEMORY

주의

세그먼트(segment)는, 타입 GUID_NOTIFICATION_PERFORMANCE 의 통지를 생성할 수 없다. 이 타입의 통지를 취득하려면 ,IDirectMusicPerformance::AddNotificationType 를 호출하지 않으면 안 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

통지와 이벤트의 처리


IDirectMusicSegment::Clone

IDirectMusicSegment::Clone 메소드는, 세그먼트(segment)와 그 중의 트랙의 모두 또는 파트를 카피한다.

HRESULT Clone(
  MUSIC_TIME mtStart,
  MUSIC_TIME mtEnd,
  IDirectMusicSegment** ppSegment
);

파라미터

mtStart
카피 시작 파트. 0 미만의 경우나, 세그먼트(segment)의 길이를 넘는 경우는, 0 이 사용된다.
mtEnd
카피 종료 파트. 이 값이 세그먼트(segment)의 최후를 넘는 경우는, 세그먼트(segment)의 끝까지 카피된다. 0, 또는 mtStart 미만의 경우도, 끝까지 카피된다.
ppSegment
메소드가 성공했을 경우는, 생성 된 세그먼트(segment)에의 포인터를 받는 변수의 주소. 어플리케이션에는, 세그먼트(segment)의 종료시에 Release 를 호출할 책임이 있다.

반환값

성공하면 S_OK 를 돌려준다. 일부의 트랙의 카피에 실패했을 경우는 S_FALSE 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_OUTOFMEMORY
E_POINTER

주의

세그먼트(segment)내에 IDirectMusicGraph 인터페이스가 존재하는 경우, 그 포인터도 클론의 일부로서 카피되어 참조 카운트가 인크리먼트(increment) 된다. IDirectMusicSegment::SetStartPoint 와 IDirectMusicSegment::SetLoopPoints 의 각 메소드에 의해 설정된 시작 포인트와 루프 포인트는, 클론의 내부에서 디폴트값 (시작 포인트는 0, 루프 포인트는 세그먼트(segment)의 마지막을 의미하는 0)으로 설정된다. 반복 회수는 0 에 리셋 된다. IDirectMusicSegment::SetDefaultResolution 메소드에 의해 설정된 만큼 해능도, 클론의 일부로서 카피된다.

스타일 베이스의 세그먼트(segment)는,mtStart 가 0 보다 큰 경우, 소절 경계상에 없으면 안 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicSegment::GetDefaultResolution

IDirectMusicSegment::GetDefaultResolution 메소드는, 동기화용의 디폴트의 분해가능을 꺼낸다.

HRESULT GetDefaultResolution(
  DWORD* pdwResolution
);

파라미터

pdwResolution
디폴트의 분해가능을 받는 변수의 주소. DMUS_SEGF_FLAGS 를 참조할것.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment::SetDefaultResolution ,세그먼트(segment)의 타이밍


IDirectMusicSegment::GetGraph

IDirectMusicSegment::GetGraph 메소드는, 세그먼트(segment)의 툴 그래프를 꺼낸다.

HRESULT GetGraph(
  IDirectMusicGraph** ppGraph
);

파라미터

ppGraph
툴 그래프에의 포인터를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_FAIL
E_POINTER

주의

세그먼트(segment)내에 그래프가 존재하지 않는 경우, 이 메소드는 E_FAIL 를 돌려준다.

툴 그래프의 참조 카운트는 인크리먼트(increment) 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment::SetGraph


IDirectMusicSegment::GetLength

IDirectMusicSegment::GetLength 메소드는, 세그먼트(segment)의 길이를 꺼낸다.

HRESULT GetLength(
  MUSIC_TIME* pmtLength
);

파라미터

pmtLength
뮤직 타임에 나타내진 세그먼트(segment)의 길이를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

주의

어떠한 이유로써 세그먼트(segment)의 길이가 설정되어 있지 않았던 경우,*pmtLength 는 0 으로 설정된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment::SetLength


IDirectMusicSegment::GetLoopPoints

IDirectMusicSegment::GetLoopPoints 메소드는, 세그먼트(segment)내의 시작 포인트와 루프 포인트를 꺼낸다. 이러한 2 포인트간은,IDirectMusicSegment::SetRepeats 메소드로 설정된 회수만 반복된다.

HRESULT GetLoopPoints(
  MUSIC_TIME* pmtStart,
  MUSIC_TIME* pmtEnd
);

파라미터

pmtStart
루프의 시작 포인트를 받는 변수의 주소.
pmtEnd
루프의 종료 포인트를 받는 변수의 주소. 값 0 은, 세그먼트(segment) 전체를 루프 시키는 것을 의미한다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment::SetLoopPoints ,세그먼트(segment)의 타이밍


IDirectMusicSegment::GetParam

IDirectMusicSegment::GetParam 메소드는, 세그먼트(segment)내의 1 개의 트랙으로부터 데이타를 뽑기 시작한다.

HRESULT GetParam(
  REFGUID rguidType,
  DWORD dwGroupBits,
  DWORD dwIndex,
  MUSIC_TIME mtTime,
  MUSIC_TIME* pmtNext,
  void* pParam
);

파라미터

rguidType
취득되는 데이터 타입의 식별자에의 참조 (C++) 또는 주소 (C). 「트랙 파라미터의 타입」을 참조할것.
dwGroupBits
희망의 트랙이 놓여져 있는 그룹. 모든 그룹을 지정하려면 , 이 값을 0xFFFFFFFF 로 설정한다. 상세한 것에 대하여는, 「트랙의 식별」을 참조할것.
dwIndex
dwGroupBits 로 식별되는 그룹내에서, 데이터의 취득처의 트랙에 할당할 수 있고 있는 인덱스.
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)의 상세한 것에 대하여는, 「세그먼트(segment)」를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::GetParam ,IDirectMusicSegment::SetParam ,IDirectMusicTrack::GetParam ,뮤직 파라미터


IDirectMusicSegment::GetRepeats

IDirectMusicSegment::GetRepeats 메소드는, 세그먼트(segment)의 루프 부분으로 설정된 반복 회수를 꺼낸다.

HRESULT GetRepeats(
  DWORD* pdwRepeats
);

파라미터

pdwRepeats
세그먼트(segment)의 루프 부분으로 설정되어 있는 반복 회수를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment::SetRepeats


IDirectMusicSegment::GetStartPoint

IDirectMusicSegment::GetStartPoint 메소드는,IDirectMusicPerformance::PlaySegment 메소드에 응답해 세그먼트(segment)의 연주를 시작 하는 포인트를 꺼낸다.

HRESULT GetStartPoint(
  MUSIC_TIME* pmtStart
);

파라미터

pmtStart
세그먼트(segment)의 연주 시작 타임을 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment::SetStartPoint


IDirectMusicSegment::GetTrack

IDirectMusicSegment::GetTrack 메소드는, 지정된 타입, 그룹, 및 인덱스에 일치하는 트랙을 트랙 리스트로부터 검색해, DirectMusicTrack 오브젝트에의 포인터를 꺼낸다.

HRESULT GetTrack(
  REFGUID rguidType,
  DWORD dwGroupBits,
  DWORD dwIndex,
  IDirectMusicTrack** ppTrack
);

파라미터

rguidType
검색되는 트랙의 식별자 (CLSID_DirectMusicChordTrack 등)에의 참조 (C++) 또는 주소 (C). 값으로서 GUID_NULL 를 지정 하면, 임의의 트랙을 꺼낸다. 트랙 식별자에 대해서는, 「IDirectMusicTrack 」를 참조할것.
dwGroupBits
검색되는 트랙을 포함한 트랙 그룹. 값 0 은 무효이다. dwGroupBits 내의 각 비트는, 1 개의 트랙 그룹에 대응한다. 그룹 에 관계없이 모든 트랙을 검색하려면 , 이 파라미터를 0xFFFFFFFF 로 설정한다.
dwIndex
rguidType 타입, 게다가 dwGroupBits 에 일치하기 위해서 돌려주어진 그룹으로부터 1 개의 트랙을 식별하기 위해서 사용되는, 0 으로부터 시작되는 인덱스. dwGroupBits 로 복수의 그룹이 선택되고 있는 경우, 선택된 그룹의 집합 중(안)에서 발견된 pCommandGuid 타입으로부터, 이 인덱스는 n 번째의 트랙을 지정한다.
ppTrack
트랙에의 포인터를 받는 변수의 주소. 트랙이 발견되지 않았던 경우, 이 변수는 NULL 로 설정된다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_FAIL 를 돌려준다.

주의

모든 트랙을 열거하려면 ,rguidType 에 GUID_NULL,dwGroupBits 에 0xFFFFFFFF 를 지정한다. 처음은 dwIndex 를 0 으로 설정해 GetTrack 를 호출해, 메소드가 성공 코드를 돌려주지 않게 될 때까지 dwIndex 를 인크리먼트(increment) 해 호출을 계속한다.

트랙 그룹의 상세한 것에 대하여는, 「트랙의 식별」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment::InsertTrack


IDirectMusicSegment::GetTrackGroup

IDirectMusicSegment::GetTrackGroup 메소드는, 세그먼트(segment)내의 트랙에 대해서 설정된 그룹 비트를 꺼낸다.

HRESULT GetTrackGroup(
  IDirectMusicTrack* pTrack,
  DWORD* pdwGroupBits
);

파라미터

pTrack
그룹 비트의 검색 대상이 되는 트랙.
pdwGroupBits
그룹을 받는 변수의 주소. *pdwGroupBits 내의 각 비트는, 1 개의 트랙 그룹에 대응한다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_FAIL
E_INVALIDARG

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment::InsertTrack ,트랙의 식별


IDirectMusicSegment::InitPlay

IDirectMusicSegment::InitPlay 는,세그먼트(segment)가 연주되기 직전에, 퍼포먼스에 의해 불려 간다.

HRESULT InitPlay(
  IDirectMusicSegmentState** ppSegState,
  IDirectMusicPerformance* pPerformance,
  DWORD dwFlags
);

파라미터

ppSegState
IDirectMusicSegmentState 인터페이스에의 포인터를 받는 변수의 주소. 이 인터페이스는 이 메소드를 호출했을 때에 생성 되어 상태 데이터를 보관 유지하기 위해서 사용된다. 참조 카운트가 1 이 되어 돌려주어지므로,Release 메소드를 호출하면, 이 인터페이스는 완전하게 릴리즈 된다.
pPerformance
IDirectMusicPerformance 인터페이스의 주소. 퍼포먼스 오브젝트에 대해서 이 메소드를 호출하기 위해서(때문에), 세그먼트(segment)와 세그먼트(segment) 상태는 이 인터페이스를 필요로 한다.
dwFlags
트랙의 동작을 변경하는 DMUS_SEGF_FLAGS . 「주의」를 참조할것.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_POINTER
E_OUTOFMEMORY

주의

이 메소드는, DirectMusic 에 의해 내부적으로 사용되는 것이어, 어플리케이션으로부터 호출해서는 안 된다. 이 메소드는 장래의 버젼에서는 지원 되지 않는다.

세그먼트(segment)를 연주하기 직전에, 퍼포먼스 엔진은 InitPlay 메소드를 호출한다. 다음에 이 세그먼트(segment)은 IDirectMusicTrack::InitPlay 메소드를 호출해 각 트랙 상태 오브젝트를 수집해, 그 결과를 세그먼트(segment) 상태의 오브젝트에 보존한다. IDirectMusicSegmentState 인터페이스를 사용하면(자), 이 오브젝트에 액세스 할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicSegment::InsertTrack

IDirectMusicSegment::InsertTrack 메소드는, 지정된 트랙을, 세그먼트(segment)의 리스트 트랙에 삽입한다.

HRESULT InsertTrack(
  IDirectMusicTrack* pTrack,
  DWORD dwGroupBits
);

파라미터

pTrack
세그먼트(segment)에 추가되는 트랙.
dwGroupBits
트랙의 삽입처가 되는, 1 개(살) 또는 복수의 그룹. 이 값은 0 으로 할 수 없다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_FAIL
E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

주의

트랙은 서로가 올바르게 링크하도록(듯이) 그룹에서 배치된다. 예를 들어, 세그먼트(segment)에는, 스타일 트랙과 뮤트 트랙이 각각 2 개(살) 포함되는 경우가 있다. 각 스타일 트랙은, 그것들에 관련지을 수 있고 있는 뮤트 트랙과 함께 다른 그룹에 배치된다. 트랙 그룹의 상세한 것에 대하여는, 「트랙의 식별」을 참조할것.

세그먼트(segment)가 현재 연주중의 경우, 새로운 트랙은 재생에 포함되지 않는다. 이것은, 세그먼트(segment) 상태의 초기화 시에 새로운 트랙은 포함되지 않았기 (위해)때문에이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment::RemoveTrack ,IDirectMusicSegment::GetTrackGroup


IDirectMusicSegment::RemoveNotificationType

IDirectMusicSegment::RemoveNotificationType 메소드는,IDirectMusicPerformance::RemoveNotificationType 메소드를 닮아 있어, 이 메소드로부터 불려 간다. 전자에 의해, 세그먼트(segment)는 통지를 삭제할 수 있다. 세그먼트(segment)은, 각 트랙의 IDirectMusicTrack::RemoveNotificationType 메소드를 호출한다.

HRESULT RemoveNotificationType(
  REFGUID rguidNotificationType
);

파라미터

rguidNotificationType
삭제되는 통지 타입의 식별자에의 참조 (C++) 또는 주소 (C)(정의 끝난 타입에 대해서는, 「DMUS_NOTIFICATION_PMSG 」를 참조할것). 이 값을 GUID_NULL 로 설정 하면, 모든 통지가 삭제된다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

통지와 이벤트의 처리


IDirectMusicSegment::RemoveTrack

IDirectMusicSegment::RemoveTrack 메소드는, 세그먼트(segment)의 트랙 리스트로부터 트랙을 삭제한다.

HRESULT RemoveTrack(
  IDirectMusicTrack* pTrack
);

파라미터

pTrack
세그먼트(segment)의 트랙 리스트로부터 삭제되는 트랙.

반환값

성공하면 S_OK 를 돌려준다. 지정된 트랙이 트랙 리스트안에 존재하지 않는 경우는 S_FALSE 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

주의

삭제된 트랙은 릴리즈 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment::InsertTrack


IDirectMusicSegment::SetDefaultResolution

IDirectMusicSegment::SetDefaultResolution 메소드는, 동기화용의 디폴트의 분해가능을 설정한다.

HRESULT SetDefaultResolution(
  DWORD dwResolution
);

파라미터

dwResolution
희망의 디폴트의 분해가능. 이 값은, 0 또는 다음에 나타내는 DMUS_SEGF_FLAGS 열거형의 멤버의 언젠가이다.

DMUS_SEGF_MEASURE
DMUS_SEGF_BEAT
DMUS_SEGF_GRID

반환값

S_OK 를 돌려준다.

주의

이 메소드는, 주로 세컨드리 세그먼트(segment) (모티프)가 스스로를 소절, 박, 또는그리드 목의 분해가능으로 동기화하는지를 정의하기 위해서 사용된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment::GetDefaultResolution ,세그먼트(segment)의 타이밍


IDirectMusicSegment::SetGraph

IDirectMusicSegment::SetGraph 메소드는, 툴 그래프를 세그먼트(segment)에 할당한다.

HRESULT SetGraph(
  IDirectMusicGraph* pGraph
);

파라미터

pGraph
Tool graph to be set. 세그먼트(segment) 그래프를 소거하기 위해서 NULL 로 설정해도 괜찮다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

주의

현재의 툴 그래프내에서 처리중의 모든 메세지는 삭제된다.

이 메소드는 그래프의 참조 카운트를 인크리먼트(increment) 하므로, 오리지날의 참조를 릴리즈 해 두면(자) 안전하다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::SetGraph ,DirectMusic 툴


IDirectMusicSegment::SetLength

IDirectMusicSegment::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)를 큐에 삽입할 때에 문제가 발생하는 일이 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment::GetLength


IDirectMusicSegment::SetLoopPoints

IDirectMusicSegment::SetLoopPoints 메소드는, 반복하는 세그먼트(segment)의 파트의 시작 포인트와 종료 포인트를 설정한다. 세그먼트(segment)의 파트는,IDirectMusicSegment::SetRepeats 메소드에 의해 설정되는 회수만 반복한다.

HRESULT SetLoopPoints(
  MUSIC_TIME mtStart,
  MUSIC_TIME mtEnd
);

파라미터

mtStart
루프의 시작 포인트.
mtEnd
루프의 종료 포인트. 값 0 은, 세그먼트(segment) 전체를 루프 시키는 것을 의미한다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 DMUS_E_OUT_OF_RANGE 를 돌려준다.

주의

세그먼트(segment)의 연주시에는, 시작 타임부터 mtEnd 까지 연주해,mtStart 에 루프 한다. 다음에, 루프 부분을 IDirectMusicSegment::SetRepeats 에 의해 설정되는 회수만 반복해, 끝까지 연주한다.

디폴트값은, 최초부터 끝까지 세그먼트(segment) 전체를 루프 시키도록(듯이) 설정되어 있다.

mtStart 의 값이 세그먼트(segment)의 길이 이상의 경우, 또는 mtEnd 의 값이 세그먼트(segment)의 길이를 넘는 경우, 메소드는 실패한다. mtEnd 가 0 의 경우,mtStart 도 0 이 아니면 안된다.

이 메소드는, 이 세그먼트(segment)로부터 생성 된, 현재 연주중의 세그먼트(segment) 상태에 영향을 미칠 것은 없다.

캐싱 된 세그먼트(segment)의 루프 포인트는, 세그먼트(segment)가 릴리즈 되어 재로드 되었을 경우에서도 계속된다. 세그먼트(segment)가 다음에 캐쉬로부터 재로드 되지 않게 하기 위해서, 세그먼트(segment)를 릴리즈 하기 전에,IDirectMusicLoader::ReleaseObject 를 호출한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment::GetLoopPoints ,세그먼트(segment)의 타이밍


IDirectMusicSegment::SetParam

IDirectMusicSegment::SetParam 메소드는, 세그먼트(segment)내의 1 개의 트랙에 데이터를 설정한다.

HRESULT SetParam(
  REFGUID rguidType,
  DWORD dwGroupBits,
  DWORD dwIndex,
  MUSIC_TIME mtTime,
  void* pParam
);

파라미터

rguidType
설정되는 데이터 타입에의 참조 (C++) 또는 주소 (C). 「트랙 파라미터의 타입」을 참조할것.
dwGroupBits
희망의 트랙이 놓여져 있는 그룹. 모든 그룹을 지정하려면 , 이 값을 0xFFFFFFFF 로 설정한다. 상세한 것에 대하여는,IDirectMusicPerformance::SetParam 의 「주의」를 참조할것.
dwIndex
dwGroupBits 로 식별되는 그룹내에서, 데이터의 설정처의 트랙에 할당할 수 있고 있는 인덱스.
mtTime
데이터의 설정을 실시하는 타임.
pParam
데이터를 보관 유지하는 구조체의 주소. 데이터가 필요없는 경우는 NULL 를 지정한다. 이 구조체는,rguidType 로 식별된 데이터 타입에 있어 적절한 종류와 사이즈를 갖추지 않으면 안 된다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_SET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND
E_POINTER

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::SetParam ,IDirectMusicSegment::GetParam ,IDirectMusicTrack::SetParam ,뮤직 파라미터


IDirectMusicSegment::SetPChannelsUsed

IDirectMusicSegment::SetPChannelsUsed 메소드는, 이 세그먼트(segment)가 사용하는 퍼포먼스 채널 (P 채널)을 설정한다. 이 메소드는 보통, 트랙이 어느 P 채널을 사용하고 있을까를 세그먼트(segment)에 통지하기 위해서 IDirectMusicTrack::Init 메소드내에서 트랙에 의해 불려 간다.

HRESULT SetPChannelsUsed(
  DWORD dwNumPChannels,
  DWORD* paPChannels
);

파라미터

dwNumPChannels
설정되는 P 채널의 수. 이 값은,paPChannels 가 가리키는 배열내의 멤버의 수로 동일하지 않으면 안 된다.
paPChannels
P 채널의 배열에의 포인터.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_INVALIDARG
E_OUTOFMEMORY
E_POINTER

주의

이 메소드를 사용하면(자), 세그먼트(segment)가 어느 포트를 사용하고 있을까를 퍼포먼스에 알려 그 결과, 퍼포먼스가 워스트 케이스에 대비하는 대신에 실제의 지연 시간을 결정할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

지연 시간과 범퍼 시간,채널


IDirectMusicSegment::SetRepeats

IDirectMusicSegment::SetRepeats 메소드는, 세그먼트(segment)의 루프 부분의 반복 회수를 설정한다. 디폴트에서는, 세그먼트(segment) 전체가 루프 된다.

HRESULT SetRepeats(
  DWORD dwRepeats
);

파라미터

dwRepeats
세그먼트(segment)의 루프 부분이 반복되는 회수. 값 0 은, 한 번의 연주만으로 반복이 없는 것을 의미한다.

반환값

S_OK 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment::GetRepeats ,IDirectMusicSegment::SetLoopPoints ,세그먼트(segment)의 타이밍


IDirectMusicSegment::SetStartPoint

IDirectMusicSegment::SetStartPoint 메소드는,IDirectMusicPerformance::PlaySegment 메소드의 호출해에 응답해 세그먼트(segment)의 연주를 시작 하는 포인트를 설정한다.

HRESULT SetStartPoint(
  MUSIC_TIME mtStart
);

파라미터

mtStart
세그먼트(segment)의 연주 시작 포인트. 이 값이 0 미만 또는 세그먼트(segment)의 길이보다 큰 경우, 시작 포인트는 0 으로 설정된다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 DMUS_E_OUT_OF_RANGE 를 돌려준다.

주의

디폴트의 시작 포인트는 0 이며, 세그먼트(segment)의 선두로부터 시작 하는 것을 의미한다.

mtStart 가 세그먼트(segment)의 길이 이상의 경우는, 이 메소드는 실패한다. 세그먼트(segment)가 아직 길이를 가지고 있지 않은 경우, 이 메소드의 전에 IDirectMusicSegment::SetLength 를 호출하지 않으면 안 된다.

이 메소드는, 이 세그먼트(segment)로부터 생성 된, 현재 연주중의 세그먼트(segment) 상태에 영향을 미칠 것은 없다.

캐싱 된 세그먼트(segment)의 시작 포인트는, 세그먼트(segment)가 릴리즈 되어 재로드 되었을 경우에서도 계속된다. 세그먼트(segment)가 다음에 캐쉬로부터 재로드 되지 않게 하기 위해서, 세그먼트(segment)를 릴리즈 하기 전에,IDirectMusicLoader::ReleaseObject 를 호출한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment::GetStartPoint ,IDirectMusicSegmentState::GetStartPoint ,IDirectMusicSegment::SetLength ,IDirectMusicSegment::SetLoopPoints ,세그먼트(segment)의 타이밍


IDirectMusicSegmentState

IDirectMusicPerformance::PlaySegment 메소드를 호출하면, 퍼포먼스 엔진은 연주중의 세그먼트(segment) 상태를 추적하는 세그먼트(segment) 상태 오브젝트를 생성한다. 또,IDirectMusicSegmentState 인터페이스의 형태로 세그먼트(segment)에의 핸들을 어플리케이션에 제공한다. 이 핸들을 사용해, 세그먼트(segment)의 재생 스테이터스를 추적할 수 있다. 또,IDirectMusicPerformance 의 메소드와 조합하는 것으로, 세그먼트(segment) 재생의 직접적인 정지나 세그먼트(segment)의 퍼포먼스로부터의 삭제에도 이용할 수 있다.

이 인터페이스는, 이하의 메소드를 지원 한다.

정보 | GetRepeats
 | GetSeek
 | GetSegment
 | GetStartPoint
 | GetStartTime

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicSegmentState::GetRepeats

IDirectMusicSegmentState::GetRepeats 메소드는, 세그먼트(segment)의 루프 부분으로 설정된 반복 회수를 돌려준다.

HRESULT GetRepeats(
  DWORD* pdwRepeats
);

파라미터

pdwRepeats
반복 회수를 받는 변수의 주소. 값 0 은, 그 세그먼트(segment) 전체를 1 회만 연주해, 반복하는 부분이 없는 것을 의미한다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment::SetRepeats


IDirectMusicSegmentState::GetSeek

IDirectMusicSegmentState::GetSeek 메소드는, 세그먼트(segment) 상태내의 현재의 시크 포인터를 꺼낸다. 이것은, 다음에 IDirectMusicTrack::Play 메소드를 호출했을 때에 건네받는,mtStart 파라미터의 값이다. 이 값은 루프와 반복을 고려에 넣지 않기 때문에, 세그먼트(segment) 상태 전체가 최초부터 반복되는 경우는, 시크 포인터는 0 에 리셋 된다.

HRESULT GetSeek(
  MUSIC_TIME* pmtSeek
);

파라미터

pmtSeek
현재의 시크 포인터를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicSegmentState::GetSegment

IDirectMusicSegmentState::GetSegment 메소드는, 이 세그먼트(segment) 상태를 보관 유지하는 세그먼트(segment)에의 포인터를 돌려준다.

HRESULT GetSegment(
  IDirectMusicSegment** ppSegment
);

파라미터

ppSegment
IDirectMusicSegment 인터페이스에의 포인터를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

주의

ppSegment 에 돌려주어지는 포인터는, 어플리케이션이 릴리즈 해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicSegmentState::GetStartPoint

IDirectMusicSegmentState::GetStartPoint 메소드는, 연주의 시작에 사용되는 (또는 이미 사용된) 세그먼트(segment)의 오프셋(offset)를 돌려준다.

HRESULT GetStartPoint(
  MUSIC_TIME * pmtStart
);

파라미터

pmtStart
세그먼트(segment)의 선두로부터, 최초로 연주되는 세그먼트(segment) 상태까지의 오프셋(offset) (뮤직 타임 단위)를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment::SetStartPoint ,IDirectMusicSegmentState::GetStartTime


IDirectMusicSegmentState::GetStartTime

IDirectMusicSegmentState::GetStartTime 메소드는, 세그먼트(segment)의 연주가 시작 된, 또는 지금부터 시작 되는 연주 타임을 취득한다.

HRESULT GetStartTime(
  MUSIC_TIME* pmtStart
);

파라미터

pmtStart
이 세그먼트(segment) 상태에 보존되고 있는 뮤직 타임 단위의 오프셋(offset)를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

주의

세그먼트(segment)의 연주가 시작 포인트 이외외의 포인트로부터 시작 되었을 경우, 이 메소드가 돌려주는 값으로부터,IDirectMusicSegmentState::GetStartPoint 가 돌려주는 타임을 당기는 것에 의해, 이 세그먼트(segment)의 시작 타임을 꺼낼 수가 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicSegment::SetStartPoint ,IDirectMusicSegment::GetStartPoint ,IDirectMusicSegmentState::GetStartPoint


IDirectMusicStyle

IDirectMusicStyle 인터페이스는, 스타일 오브젝트에의 액세스를 제공한다. 스타일 오브젝트는, 뮤직 패턴을 연주할 경우에 필요하게 되는 정보를 퍼포먼스에 제공한다. 개요에 대해서는, 「스타일의 사용법」을 참조할것.

스타일에는 보통, 밴드와 모티프가 포함되므로,IDirectMusicStyle 는 이러한 오브젝트에 액세스하기 위한 메소드를 제공한다.

DirectMusicStyle 오브젝트는, 스스로의 데이터를 로드하기 위해서(때문에) IDirectMusicObject 와 IPersistStream 의 각 인터페이스도 지원 하고 있다.

IDirectMusicStyle 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

열거 | EnumBand
 | EnumChordMap
 | EnumMotif
정보 | GetBand
 | GetChordMap
 | GetDefaultBand
 | GetDefaultChordMap
 | GetEmbellishmentLength
 | GetMotif
 | GetTempo
 | GetTimeSignature

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicStyle::EnumBand

IDirectMusicStyle::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

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicStyle::EnumChordMap

IDirectMusicStyle::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

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicStyle::EnumMotif

IDirectMusicStyle::EnumMotif 메소드는, 주어진 인덱스에 대응하는 모티프명을 꺼낸다.

HRESULT EnumMotif(
  DWORD dwIndex,
  WCHAR * pwszName
);

파라미터

dwIndex
스타일의 모티프 리스트내의, 0 으로부터 시작되는 인덱스.
pwszName
모티프명을 받는 버퍼의 주소. MAX_PATH 의 사이즈를 가져야 하는 것이다.

반환값

성공하면 S_OK 를 돌려준다. 지정된 인덱스값을 가지는 모티프가 없으면 S_FALSE, 모티프명의 길이의 값이 MAX_PATH 보다 큰 경우는 DMUS_S_STRING_TRUNCATED 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicStyle::GetMotif ,모티프의 사용법


IDirectMusicStyle::GetBand

IDirectMusicStyle::GetBand 메소드는, 지정된 밴드를 꺼낸다.

HRESULT GetBand(
  WCHAR* pwszName,
  IDirectMusicBand** ppBand
);

파라미터

pwszName
꺼내지는 밴드의 이름. 이 이름은, 스타일의 생성자에 의해 할당할 수 있다.
ppBand
밴드에의 포인터를 받는 변수의 주소.

반환값

메소드가 성공해, 밴드가 돌려주어졌을 경우는 S_OK 를 돌려준다. 지정된 이름에 대응하는 밴드가 존재하지 않는 경우는 S_FALSE 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicStyle::GetDefaultBand ,밴드의 사용법


IDirectMusicStyle::GetChordMap

IDirectMusicStyle::GetChordMap 메소드는, 지정된 코드 맵을 꺼낸다.

HRESULT GetChordMap(
  WCHAR* pwszName,
  IDirectMusicChordMap** ppChordMap
);

파라미터

pwszName
꺼내지는 코드 맵의 이름.
ppChordMap
IDirectMusicChordMap 인터페이스에의 포인터를 받는 변수의 주소.

반환값

메소드가 성공해, 코드 맵이 돌려주어졌을 경우는 S_OK 를 돌려준다. 지정된 이름을 가지는 코드 맵이 존재하지 않는 경우는 S_FALSE 를 돌려준다.

ppChordMap 가 유효한 포인터가 아닌 경우는 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicStyle::GetDefaultChordMap ,코드 맵의 사용법


IDirectMusicStyle::GetDefaultBand

IDirectMusicStyle::GetDefaultBand 메소드는, 스타일의 디폴트의 밴드를 꺼낸다.

HRESULT GetDefaultBand(
  IDirectMusicBand ** ppBand
);

파라미터

ppBand
디폴트의 밴드에의 포인터를 받는 변수의 주소.

반환값

메소드가 성공해, 밴드가 돌려주어졌을 경우는 S_OK 를 돌려준다. 스타일에 디폴트의 밴드가 없는 경우는 S_FALSE 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicStyle::GetBand ,밴드의 사용법


IDirectMusicStyle::GetDefaultChordMap

IDirectMusicStyle::GetDefaultChordMap 메소드는, 스타일의 디폴트의 코드 맵을 꺼낸다.

HRESULT GetDefaultChordMap(
  IDirectMusicChordMap** ppChordMap
);

파라미터

ppChordMap
IDirectMusicChordMap 인터페이스에의 포인터를 받는 변수의 주소.

반환값

메소드가 성공해, 코드 맵이 돌려주어졌을 경우는 S_OK 를 돌려준다. 스타일에 디폴트의 코드 맵이 없는 경우는 S_FALSE 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicStyle::GetChordMap ,코드 맵의 사용법


IDirectMusicStyle::GetEmbellishmentLength

IDirectMusicStyle::GetEmbellishmentLength 메소드는, 지정된 장식 타입과 그루브 레벨로부터, 최단 패턴의 길이와 최장 패턴의 길이를 찾아낸다.

HRESULT GetEmbellishmentLength(
  DWORD dwType,
  DWORD dwLevel,
  DWORD* pdwMin,
  DWORD* pdwMax
);

파라미터

dwType
장식 타입. DMUS_COMMANDT_TYPES 를 참조할것.
dwLevel
1 ~ 100 의 범위의 그루브 레벨. 그루브가 아닌 장식은 무시된다.
pdwMin
지정된 타입과 그루브 레벨의 최단 패턴의 길이를 받는 변수의 주소.
pdwMax
지정된 타입과 그루브 레벨의 최장 패턴의 길이를 받는 변수의 주소.

반환값

성공하면 S_OK 또는 S_FALSE 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

주의

지정된 타입과 그루브 레벨에 대응하는 패턴이 존재하지 않는 경우는, 반환값은 S_FALSE 이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicStyle::GetMotif

IDirectMusicStyle::GetMotif 메소드는, 지정된 모티프를 포함한 세그먼트(segment)를 생성 한다.

HRESULT GetMotif(
  WCHAR* pwszName,
  IDirectMusicSegment** ppSegment
);

파라미터

pwszName
꺼내지는 모티프의 이름.
ppSegment
지정된 모티프를 포함한 세그먼트(segment)에의 포인터를 받는 변수의 주소.

반환값

성공하면 S_OK 또는 S_FALSE 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

주의

이 메소드는,pwszName 에 일치하는 이름을 가지는 모티프를 스타일 리스트로부터 검색한다. 모티프가 발견되었을 경우, 모티프 트랙을 포함한 세그먼트(segment)가 생성 된다. 트랙은, 스타일을 트랙의 관련 스타일, 모티프를 트랙의 패턴으로서 참조한다.

지정된 이름을 가지는 모티프가 존재하지 않는 경우, 이 메소드는 S_FALSE 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

모티프의 사용법


IDirectMusicStyle::GetTempo

IDirectMusicStyle::GetTempo 메소드는, 스타일의 추천 템포를 꺼낸다.

HRESULT GetTempo(
  double* pTempo
);

파라미터

pTempo
스타일의 추천 템포를 받는 변수의 주소.

반환값

성공하면 S_OK 를 돌려준다.

pTempo 가 유효한 포인터가 아닌 경우는 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicStyle::GetTimeSignature

IDirectMusicStyle::GetTimeSignature 메소드는, 스타일의 박자 기호를 꺼낸다.

HRESULT GetTimeSignature(
  DMUS_TIMESIGNATURE* pTimeSig
);

파라미터

pTimeSig
데이터를 받는 DMUS_TIMESIGNATURE 구조체의 주소.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicThru

IDirectMusicThru 인터페이스는, 뮤직 메세지의 캡춰 포트로부터 다른 포트에의 전송을 지원 한다. 이 인터페이스는, 캡춰 포트의 IDirectMusicPort 인터페이스에 대해서 QueryInterface 를 호출하는 것에 의해 취득된다. 구체적인 예에 대해서는, 「IDirectMusicThru::ThruChannel 」의 「주의」를 참조할것.

이 인터페이스는, 이하의 메소드를 지원 한다.

IDirectMusicThru ThruChannel

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

음악의 캡춰


IDirectMusicThru::ThruChannel

IDirectMusicThru::ThruChannel 메소드는, 캡춰 포트 위에의 채널과 다른 포트 위에의 채널간에서의 전송 접속을 확립 또는 해제한다.

HRESULT ThruChannel(
  DWORD dwSourceChannelGroup,
  DWORD dwSourceChannel,
  DWORD dwDestinationChannelGroup,
  DWORD dwDestinationChannel,
  LPDIRECTMUSICPORT pDestinationPort
);

파라미터

dwSourceChannelGroup
캡춰 포트 위에의 채널 그룹. 현재의 버젼의 DirectMusic 에서는, 이 값은 항상 1 으로 설정된다.
dwSourceChannel
소스 채널.
dwDestinationChannelGroup
목적지 포트 위에의 채널 그룹.
dwDestinationChannel
목적지 채널.
pDestinationPort
목적지 채널의 IDirectMusicPort 인터페이스의 주소. 이 값을 NULL 로 설정 하면, 기존의 전송 접속이 해제된다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_NOTIMPL
E_INVALIDARG
DMUS_E_PORT_NOT_RENDER

주의

시스템에크스크루시브멧세이지는, 목적지 포트에 송신되지 않는다.

Microsoft Software Synthesizer 또는 일정한 지연 시간을 가지지 않는 그 외의 신디사이저에의 전송은 추천 되지 않는다. 전송은, 수신 MIDI 이벤트를 받으면(자) 즉석에서 행해진다. 소프트웨어 신디사이저의 지연 시간이 비교적 긴 일 (하드웨어 포트와 비교했을 경우), 및 소프트웨어 신디사이저는 복수의 오디오 블록을 동시에 렌더링 하는 것으로부터, 각 이벤트에는 연주전 정원않고일까 지연이 발생한다. 이 지연의 길이는, 일정하고 있지 않다. 이 랜덤인 오프셋(offset)는, 데이터의 재생시에 지터로서 발생한다. 그 외의 디바이스 (MPU-401 포트등)의 지연 시간은 적기 (위해)때문에, 지터는 발생하지 않는다.

어플리케이션이 소프트웨어 신디사이저에 대해서 데이터를 전송 할 필요가 있는 경우, 수신 노트 이벤트의 타임 스탬프 정원않고일까 오프셋(offset)를 추가해, 신디사이저의 렌더링 지연 시간을 보정해야 한다.

다음의 샘플 코드에서는,IDirectMusicThru 인터페이스를 취득해, 캡춰 포트의 그룹 1 위에의 모든 채널과 목적지 포트 위에의 동등의 채널과의 사이에 전송 접속을 확립한다.

HRESULT SetupOneToOneThru(
    IDirectMusicPort *pCapturePort,
    IDirectMusicPort *pRenderPort)
{
    HRESULT hr;
    IDirectMusicThru *pThru;

    hr = pCapturePort->QueryInterface(IID_IDirectMusicThru,
            (void**) &pThru);
    if (FAILED(hr))
        return hr;

    for (DWORD dwChannel = 0; dwChannel < 16; dwChannel++)
    {
        hr = pThru->ThruChannel(1, dwChannel,
            1, dwChannel, pRenderPort);
        if (FAILED(hr))
            break;
    }

    pThru->Release();
    return hr;
}

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IDirectMusicTool

툴이란,IDirectMusicTool 인터페이스를 이행 하는 오브젝트이다. 이것들은 그래프의 내부에서 사용된다 (IDirectMusicGraph 를 참조). IDirectMusicPerformance::SendPMsg 를 사용해 메세지를 송신 하면, 메세지는 그래프내의 툴을 통과한다. 툴은 메세지의 변경, 추가의 메세지의 생성, 메세지의 삭제등을 실시할 수 있다.

이 인터페이스는 주로, 독자적인 툴을 생성 하는 것을 생각하고 있는 개발자에 의해 이용된다.

IDirectMusicTool 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

초기화 | Init
메세지 관리 | Flush
 | GetMediaTypeArraySize
 | GetMediaTypes
 | GetMsgDeliveryType
 | ProcessPMsg

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

DirectMusic 의 데이터의 흐름의 개요,메세지의 생성과 전달,DirectMusic 툴


IDirectMusicTool::Flush

퍼포먼스가 정지했을 때에, 큐내에 있는 각 메세지에 대해서 IDirectMusicTool::Flush 메소드가 불려 간다. 툴은 이 메소드를 사용해, 메세지의 플래시 (릴리즈)에 필요한 모든 일을 실시할 수 있다. 예를 들어, 출력 툴은 이 메소드를 사용해, 보류되고 있는 모든 노트 오프 메세지가 즉석에서 처리되도록(듯이) 한다.

HRESULT Flush(
  IDirectMusicPerformance* pPerf,
  DMUS_PMSG* pPMSG,
  REFERENCE_TIME rtTime
);

파라미터

pPerf
IDirectMusicPerformance 인터페이스의 주소.
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 툴」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicTool::GetMediaTypeArraySize

IDirectMusicTool::GetMediaTypeArraySize 메소드는,IDirectMusicTool::GetMediaTypes 메소드에 건네주지 않으면 안 되는 배열의 사이즈를 꺼낸다. 값으로서 0 이 돌려주어졌을 경우, 그 툴은 모든 타입을 처리하므로,GetMediaTypes 를 호출할 필요가 없는 것을 의미한다.

HRESULT GetMediaTypeArraySize(
  DWORD* pdwNumElements
);

파라미터

pdwNumElements
미디어 타입의 수를 받는 변수의 주소. 이 필드에 0 이 돌려주어졌을 경우, 모든 타입이 지원 되고 있다.

반환값

반환값은 이행에 의해 정해진다. 성공하면 S_OK 를 돌려준다. 실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicTool::GetMediaTypes

IDirectMusicTool::GetMediaTypes 메소드는, 이 툴이 지원 하는 메세지 타입의 리스트를 꺼낸다.

HRESULT GetMediaTypes(
  DWORD** padwMediaTypes,
  DWORD dwNumElements
);

파라미터

padwMediaTypes
DWORD 의 배열의 주소. 이 메소드는, 툴이 지원 하고 있는 미디어 타입을 이 배열에 기입한다. 미디어 타입에 대해서는,DMUS_PMSGT_TYPES 를 참조할것.
dwNumElements
padwMediaTypes 배열내의 요소의 수. 이 값은,IDirectMusicTool::GetMediaTypeArraySize 메소드가 돌려준 수로 일치하고 있어야 하는 것이다. dwNumElements 의 값이 이 수보다 작은 경우, 메소드는 지원 떠날 수 있어 모든 메세지 타입을 돌려줄 수 없다. 값이 이 수보다 큰 경우, 배열내의 여분의 요소는 0 으로 설정된다.

반환값

반환값은 이행에 의해 정해진다. 성공하면 S_OK 를 돌려준다. dwNumElements 가 너무 작아 모든 값을 기입할 수 없었던 경우는 S_FALSE 를 돌려준다. 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_POINTER
E_INVALIDARG
E_NOTIMPL

주의

메소드가 E_NOTIMPL 를 돌려주는 경우, 툴은 모든 미디어 타입을 처리한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicTool::GetMsgDeliveryType

IDirectMusicTool::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 를 돌려준다.

주의

전달 메카니즘의 개요에 대해서는, 「메세지의 생성과 전달」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicTool::Init

IDirectMusicTool::Init 메소드는, 툴을 그래프에 삽입했을 때에 불려 가 툴이 필요한 초기화를 행하기 위한 기회를 제공한다.

HRESULT Init(
  IDirectMusicGraph* pGraph
);

파라미터

pGraph
호출중의 그래프.

반환값

반환값은 이행에 의해 정해진다. 성공하면 S_OK 를 돌려준다. 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_FAIL
E_NOTIMPL

주의

툴은 복수의 그래프에 삽입할 수 있기 (위해)때문에, 이 메소드는 복수의 호출에 대해서 문제 없게 대처할 수 없으면 안 된다.

pGraph 에 의해 나타내지는 퍼포먼스에의 순환 참조는 생성 하지 않는 것. 상세한 것에 대하여는, 「DirectMusic 툴」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicGraph::InsertTool


IDirectMusicTool::ProcessPMsg

IDirectMusicTool::ProcessPMsg 메소드는, 툴의 주요한 태스크를 실행한다. 이 메소드는,IDirectMusicTool::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 툴」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::SendPMsg ,메세지,메세지의 생성과 전달


IDirectMusicTrack

IDirectMusicTrack 인터페이스는, 트랙 오브젝트를 나타낸다. 세그먼트(segment)의 정의에 관계가 있는 거의 모든 내용이 트랙에 보존되고 있다. 이 트랙 메카니즘에 의해, 세그먼트(segment)는 무한하게 확장 가능하고, 세그먼트(segment)는 스스로 사용하는 음악이나 오디오의 테크놀러지에 관해서 아무것도 파악하고 있지 않아도 상관없다.

독자적인 음악 재생 메카니즘을 DirectMusic 에 이행 하는 것을 계획하고 있는 경우, 그 메카니즘을 나타내는 DirectMusicTrack 오브젝트를 생성 할 필요가 있다. DirectMusicTrack 오브젝트를 생성 하지 않았던 경우, 이 인터페이스의 메소드는 보통, 어플리케이션으로부터 직접 불려 가지 않는다.

주 : IDirectMusicTrack 인터페이스의 메소드를 이행 하면나무는, 건네받는 오브젝트에의 참조를 보관 유지하지 않는 것. 예를 들어,IDirectMusicTrack::Init 가 파라미터로서 받는 IDirectMusicSegment 인터페이스에의 참조를 추가하는 경우는, 이 참조가 릴리즈 되도록(듯이) 한다.

IDirectMusicTrack 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

초기화 | Init
재생 | EndPlay
 | InitPlay
 | Play
통지 | AddNotificationType
 | RemoveNotificationType
파라미터 | GetParam
 | IsParamSupported
 | SetParam
그 외 | Clone

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

DirectMusicTrack 오브젝트는, 스스로의 데이터를 로드하기 위해서(때문에) IDirectMusicObject 와 IPersistStream 의 각 인터페이스도 지원 하고 있다.

다음 표에, 표준의 트랙 타입에 의해 지원 되는 메소드를 나타낸다. 표준 타입의 일반적인 설명에 대해서는, 「트랙」을 참조할것.

트랙 | IDirectMusicTrack 메소드 |  | IPersistStream 메소드
밴드 (CLSID_DirectMusicBandTrack)
 | AddNotificationType | 아니오 | IsDirty | 네
 | Clone | 네 | GetSizeMax | 아니오
 | EndPlay | 네 | Load | 네
 | GetParam | 아니오 | Save | 네
 | Init | 네 |  |
 | InitPlay | 네
 | IsParamSupported | 네
 | Play | 네
 | SetParam | 네
 | RemoveNotificationType | 아니오
코드 (CLSID_DirectMusicChordTrack)
 | AddNotificationType | 네 | IsDirty | 네
 | Clone | 네 | GetSizeMax | 아니오
 | EndPlay | 네 | Load | 네
 | GetParam | 네 | Save | 네
 | Init | 네 |  |
 | InitPlay | 네
 | IsParamSupported | 네
 | Play | 네
 | SetParam | 네
 | RemoveNotificationType | 네
코드 맵 (CLSID_DirectMusicChordMapTrack)
 | AddNotificationType | 아니오 | IsDirty | 아니오
 | Clone | 네 | GetSizeMax | 아니오
 | EndPlay | 네* | Load | 네
 | GetParam | 네 | Save | 아니오
 | Init | 네* |  |
 | InitPlay | 네*
 | IsParamSupported | 네
 | Play | 네*
 | SetParam | 네
 | RemoveNotificationType | 아니오
커멘드 (CLSID_DirectMusicCommandTrack)
 | AddNotificationType | 네 | IsDirty | 네
 | Clone | 네 | GetSizeMax | 아니오
 | EndPlay | 네 | Load | 네
 | GetParam | 네 | Save | 네
 | Init | 네 |  |
 | InitPlay | 네
 | IsParamSupported | 네
 | Play | 네
 | SetParam | 네
 | RemoveNotificationType | 네
모티프 (CLSID_DirectMusicMotifTrack)
 | AddNotificationType | 네 | IsDirty | 아니오
 | Clone | 네 | GetSizeMax | 아니오
 | EndPlay | 네 | Load | 아니오
 | GetParam | 아니오 | Save | 아니오
 | Init | 네 |  |
 | InitPlay | 네
 | IsParamSupported | 네
 | Play | 네
 | SetParam | 네
 | RemoveNotificationType | 네
뮤트 (CLSID_DirectMusicMuteTrack)
 | AddNotificationType | 아니오 | IsDirty | 네
 | Clone | 네 | GetSizeMax | 아니오
 | EndPlay | 네* | Load | 네
 | GetParam | 네 | Save | 네
 | Init | 네* |  |
 | InitPlay | 네*
 | IsParamSupported | 네
 | Play | 네*
 | SetParam | 네
 | RemoveNotificationType | 아니오
순서 (CLSID_DirectMusicSeqTrack)
 | AddNotificationType | 아니오 | IsDirty | 아니오
 | Clone | 네 | GetSizeMax | 아니오
 | EndPlay | 네 | Load | 네
 | GetParam | 아니오 | Save | 아니오
 | Init | 네 |  |
 | InitPlay | 네
 | IsParamSupported | 아니오
 | Play | 네
 | SetParam | 아니오
 | RemoveNotificationType | 아니오
싸인 포스트 (CLSID_DirectMusicSignPostTrack)
 | AddNotificationType | 아니오 | IsDirty | 네
 | Clone | 네 | GetSizeMax | 아니오
 | EndPlay | 네* | Load | 네
 | GetParam | 아니오 | Save | 네
 | Init | 네* |  |
 | InitPlay | 네*
 | IsParamSupported | 아니오
 | Play | 네*
 | SetParam | 아니오
 | RemoveNotificationType | 아니오
스타일 (CLSID_DirectMusicStyleTrack)
 | AddNotificationType | 네 | IsDirty | 아니오
 | Clone | 네 | GetSizeMax | 아니오
 | EndPlay | 네 | Load | 네
 | GetParam | 네 | Save | 아니오
 | Init | 네 |  |
 | InitPlay | 네
 | IsParamSupported | 네
 | Play | 네
 | SetParam | 네
 | RemoveNotificationType | 네
SysEx (CLSID_DirectMusicSysExTrack)
 | AddNotificationType | 아니오 | IsDirty | 아니오
 | Clone | 네 | GetSizeMax | 아니오
 | EndPlay | 네 | Load | 네
 | GetParam | 아니오 | Save | 아니오
 | Init | 네 |  |
 | InitPlay | 네
 | IsParamSupported | 아니오
 | Play | 네
 | SetParam | 아니오
 | RemoveNotificationType | 아니오
템포 (CLSID_DirectMusicTempoTrack)
 | AddNotificationType | 아니오 | IsDirty | 아니오
 | Clone | 네 | GetSizeMax | 아니오
 | EndPlay | 네 | Load | 네
 | GetParam | 네 | Save | 아니오
 | Init | 네 |  |
 | InitPlay | 네
 | IsParamSupported | 네
 | Play | 네
 | SetParam | 네
 | RemoveNotificationType | 아니오
박자 기호** (CLSID_DirectMusicTimeSigTrack)
 | AddNotificationType | 네 | IsDirty | 아니오
 | Clone | 네 | GetSizeMax | 아니오
 | EndPlay | 네 | Load | 네
 | GetParam | 네 | Save | 아니오
 | Init | 네 |  |
 | InitPlay | 네
 | IsParamSupported | 네
 | Play | 네
 | SetParam | 네
 | RemoveNotificationType | 네

주 :

* 이 메소드는 E_NOTIMPL 이외의 값을 돌려주지만, 그 외의 처리는 실시하지 않는다.

** 박자 기호 트랙은, 임포트 된 MIDI 파일 및 그것을 사용해 생성 되는 DirectMusic Producer 세그먼트(segment)내에 존재한다. 대부분의 경우, 스타일 트랙은 박자 기호 트랙의 기능을 이행 한다. 그 때문에, 스타일 트랙을 포함하고 있는 세그먼트(segment)가 박자 기호 트랙도 포함하고 있을 필요는 없다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

트랙,트랙 파라미터의 설정과 꺼내


IDirectMusicTrack::AddNotificationType

IDirectMusicTrack::AddNotificationType 메소드는, 트랙에의 이벤트 통지를 가능하게 한다. IDirectMusicSegment::AddNotificationType 메소드를 닮아 있어, 이 메소드로부터 불려 간다.

HRESULT AddNotificationType(
  REFGUID rguidNotificationType
);

파라미터

rguidNotificationType
추가되는 통지 타입의 식별자에의 참조 (C++) 또는 주소 (C). 정의 끝난 타입에 대해서는, 「DMUS_NOTIFICATION_PMSG 」를 참조할것. 어플리케이션은, 커스텀 트랙에 도착해 독자적인 타입을 정의할 수 있다.

반환값

성공하면 S_OK 를 돌려준다. 트랙이 통지 타입을 지원 하지 않는 경우는 S_FALSE 를 돌려준다.

트랙이 통지를 지원 하지 않는 경우는,E_NOTIMPL 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicTrack::RemoveNotificationType ,통지와 이벤트의 처리


IDirectMusicTrack::Clone

IDirectMusicTrack::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 를 호출하지 않으면 안 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicTrack::EndPlay

최초로 IDirectMusicTrack::InitPlay 를 호출한 오브젝트를 삭제할 경우에,IDirectMusicTrack::EndPlay 메소드가 불려 간다.

HRESULT EndPlay(
  void * pStateData
);

파라미터

pStateData
IDirectMusicTrack::InitPlay 가 돌려준 상태 데이터. 이 데이터는 EndPlay 메소드로 릴리즈 해야 한다.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 E_POINTER 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicTrack::GetParam

IDirectMusicTrack::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

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicTrack::SetParam ,IDirectMusicTrack::IsParamSupported ,IDirectMusicPerformance::GetParam ,IDirectMusicSegment::GetParam ,뮤직 파라미터


IDirectMusicTrack::Init

IDirectMusicTrack::Init 메소드는, 트랙을 추가해, 필요한 초기화를 실시할 때 세그먼트(segment)에 의해 불려 간다.

HRESULT Init(
  IDirectMusicSegment* pSegment
);

파라미터

pSegment
이 트랙이 소속하는 세그먼트(segment).

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_NOT_INIT
E_OUTOFMEMORY
E_POINTER

주의

트랙이 메세지를 연주하는 경우,Init 메소드내에서 IDirectMusicSegment::SetPChannelsUsed 를 호출해야 하는 것이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicTrack::InitPlay

IDirectMusicTrack::InitPlay 메소드는, 트랙이 연주를 시작 할 준비를 할 수 있었을 때에 불려 간다. 상태 데이터에의 포인터를 돌려주지만, 이 포인터는 IDirectMusicTrack::Play 와 IDirectMusicTrack::EndPlay 에게 건네진다.

HRESULT InitPlay(
  IDirectMusicSegmentState* pSegmentState,
  IDirectMusicPerformance* pPerformance,
  void** ppStateData,
  DWORD dwVirtualTrackID,
  DWORD dwFlags
);

파라미터

pSegmentState
호출중의 IDirectMusicSegmentState 인터페이스의 주소.
pPerformance
호출중의 IDirectMusicPerformance 인터페이스의 주소.
ppStateData
상태 정보에의 포인터를 받기 위한 변수의 주소. 데이터의 포맷과 사용 방법은, 트랙에 고유하다. 데이터는 InitPlay 메소드로 생성 해,IDirectMusicTrack::EndPlay 메소드로 릴리즈 해야 한다. 포인터는 IDirectMusicTrack::Play 메소드에게 건네진다.
dwVirtualTrackID
이 트랙 인스턴스에 할당할 수 있었던 가상 트랙 ID.
dwFlags
트랙의 동작을 제어하는 DMUS_SEGF_FLAGS . 「주의」를 참조할것.

반환값

성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_NOT_INIT
E_OUTOFMEMORY
E_POINTER

주의

트랙은 pSegmentState,pPerformance, 및 dwTrackID 의 각 파라미터를 보존할 필요가 있다. 이것들은 IDirectMusicTrack::Play 에도 건네받기 때문에 있다.

dwFlags 파라미터는,IDirectMusicPerformance::PlaySegment 의 호출로 퍼포먼스에게 건네진 플래그를 건네준다. 트랙은, DMUS_SEGF_CONTROL 와 DMUS_SEGF_SECONDARY 의 각 플래그에 근거해, 그 실행 방법을 결정한다. 예를 들어, 템포 트랙은, 그 자체가 프라이머리 세그먼트(segment) 또는 세컨드리제어 세그먼트(segment) 의 파트인 경우에 한정해, 템포의 변경을 자동적으로 연주한다 (DMUS_SEGF_SECONDARY 가 설정되어 있지 않은, 또는 DMUS_SEGF_CONTROL 가 세트 되고 있다).

트랙은 ppStateData 로 NULL 를 돌려주는 경우가 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicTrack::IsParamSupported

IDirectMusicTrack::IsParamSupported 메소드는,IDirectMusicTrack::GetParam 와 IDirectMusicTrack::SetParam 의 각 메소드로 지정된 데이터 타입을 지원 하고 있을지 어떨지를 판단한다.

HRESULT IsParamSupported(
  REFGUID rguidType
);

파라미터

rguidType
데이터 타입의 식별자에의 참조 (C++) 또는 주소 (C). 「트랙 파라미터의 타입」을 참조할것.

반환값

메소드가 성공해, 타입이 지원 되고 있으면 S_OK,

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_TYPE_DISABLED
DMUS_E_TYPE_UNSUPPORTED
E_POINTER
E_NOTIMPL

주의

SetParam 메소드의 어느쪽이든을 사용하는 것에 의해 메세지 타입이 무효가 되어 있는 경우 ( 「메세지의 무효화와 유효화」를 참조),IDirectMusicTrack::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 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicTrack::GetParam ,IDirectMusicTrack::SetParam ,뮤직 파라미터


IDirectMusicTrack::Play

IDirectMusicTrack::Play 메소드는, 트랙을 연주한다. 이 메소드는, 메세지의 생성과 송신 등, 세그먼트(segment)의 연주시에 트랙이 실시할 필요가 있는 임의의 조작을 실행한다.

HRESULT Play(
  void* pStateData,
  MUSIC_TIME mtStart,
  MUSIC_TIME mtEnd,
  MUSIC_TIME mtOffset
  DWORD dwFlags,
  IDirectMusicPerformance* pPerf,
  IDirectMusicSegmentState* pSegSt,
  DWORD dwVirtualID
);

파라미터

pStateData
IDirectMusicTrack::InitPlay 메소드가 돌려준 상태 데이터. 데이터의 포맷과 사용 방법은, 트랙에 고유하다.
mtStart
시작 타임.
mtEnd
종료 타임.
mtOffset
IDirectMusicPerformance::SendPMsg 에게 건네지는 모든 메세지에 추가되는 오프셋(offset).
dwFlags
이 호출 상태를 나타내는 플래그. DMUS_TRACKF_FLAGS 를 참조할것. 값 0 은,Play 의 호출에 의해, 재생이 전의 호출로부터 계속되는 것을 의미한다.
pPerf
메세지의 할당과 송신에 사용되는 퍼포먼스.
pSegSt
이 트랙이 소속하는 세그먼트(segment) 상태. IDirectMusicSegmentState::QueryInterface 메소드를 호출해,IDirectMusicGraph 인터페이스를 취득할 수도 있다. 예를 들어 IDirectMusicGraph::StampPMsg 를 호출하는 경우이다.
dwVirtualID
트랙의 가상 식별자. IDirectMusicPerformance::SendPMsg 로부터 건네받는 모든 메세지의 dwVirtualTrackID 멤버 (DMUS_PMSG 를 참조)에 이 값을 기입하지 않으면 안 된다.

반환값

성공하면 S_OK 또는 DMUS_S_END 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DMUS_E_NOT_INIT
E_POINTER

주의

트랙이 하늘의 경우, 이 메소드는 DMUS_S_END 를 돌려준다.

트랙은, 우선 순위가 중저도의 thread내에 메세지를 생성한다. 파일의 데이터를 스트림화하는 코드 등, 시간이 걸리는 함수를, 트랙의 Play 메소드내로부터 호출할 수가 있다. 다만, 안전한 multi-thread화를 위한 가이드 라인에 따르는 것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


IDirectMusicTrack::RemoveNotificationType

IDirectMusicTrack::RemoveNotificationType 메소드는, 트랙으로부터 이벤트 통지를 삭제한다. IDirectMusicSegment::RemoveNotificationType 를 닮아 있어, 이 메소드로부터 불려 간다.

HRESULT RemoveNotificationType(
  REFGUID rguidNotificationType
);

파라미터

rguidNotificationType
삭제되는 통지 타입의 식별자에의 참조 (C++) 또는 주소 (C). 정의 끝난 타입에 대해서는, 「DMUS_NOTIFICATION_PMSG 」를 참조할것.

반환값

성공하면 S_OK 를 돌려준다. 트랙이 통지 타입을 지원 하지 않는 경우는 S_FALSE 를 돌려준다.

트랙이 통지를 지원 하지 않는 경우는,E_NOTIMPL 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicTrack::AddNotificationType ,통지와 이벤트의 처리


IDirectMusicTrack::SetParam

IDirectMusicTrack::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

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicTrack::GetParam ,IDirectMusicTrack::IsParamSupported ,IDirectMusicPerformance::SetParam ,IDirectMusicSegment::SetParam ,트랙 파라미터의 설정과 꺼내


IKsControl

IKsControl 인터페이스는, 프로퍼티, 이벤트, 및 메소드의 지원을 취득, 설정, 또는 문의하기 위해서(때문에) 사용된다. 이 인터페이스는, Windows 드라이버 모델 커널 스트리밍 아키텍쳐의 일부이지만, DirectMusic 에 의해도 사용되어 DirectMusic 포트의 프로퍼티를 공개한다. 이 인터페이스를 꺼내려면 ,riid 파라미터에 IID_IKsControl 를 지정해 IDirectMusicPort::QueryInterface 메소드를 호출한다.

프로퍼티 항목의 요구를 포트에 대해서 송신하는 작업은, 포트의 이행에 의존한다. Win32 핸들 베이스의 멀티미디어 호출 (midiOut 와 midiIn 의 각 함수)을 이용해 DirectMusic 의 에뮬레이션을 실시하고 있는 포트는, 어느 프로퍼티도 지원 하지 않는다.

플러그 가능한 소프트웨어 신디사이저를 나타내는 포트에 대해서 프로퍼티 항목을 요구 하면, 완전하게 유저 모드로 응답이 이루어진다. 이 타입의 포트의 위상기하학은, 세면대 노드 (IDirectMusicSynthSink 인터페이스)에 접속된 신디사이저 (IDirectMusicSynth 인터페이스에 의해 나타내진다)이다. 이 프로퍼티 요구는 최초로 신디사이저 노드에 할당할 수 있어 신디사이저가 이 요구를 인식하지 않는 경우는 세면대 노드에 할당할 수 있다.

이 인터페이스는, 이하의 메소드를 지원 한다. 현재로서는,KsProperty 만이 DirectMusic 에 의해 지원 되고 있다.

IKsControl | KsProperty
 | KsEvent
 | KsMethod

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmksctrl.h 로 선언.

참조

포트의 프로퍼티 세트


IKsControl::KsProperty

IKsControl::KsProperty 메소드는, 프로퍼티의 값을 취득 또는 설정한다. 개요에 대해서는, 「포트의 프로퍼티 세트」를 참조할것.

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

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmksctrl.h 로 선언.

참조

포트의 프로퍼티 세트


IReferenceClock

IReferenceClock 인터페이스는, 시스템 기준 타임을 나타낸다. DirectMusic master clock와 포트의 지연 시간 클럭은, 이 인터페이스를 이행 한다.

이 인터페이스는, 이하의 메소드를 지원 한다.

IReferenceClock | GetTime
 | AdviseTime
 | AdvisePeriodic
 | Unadvise

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IDirectMusic::GetMasterClock ,IDirectMusicPort::GetLatencyClock ,타이밍


IReferenceClock::AdvisePeriodic

IReferenceClock::AdvisePeriodic 메소드는, 지속 시간이 경과한, 비동기의 기간 통지를 요구한다.

HRESULT AdvisePeriodic(
  REFERENCE_TIME rtStartTime,
  REFERENCE_TIME rtPeriodTime,
  HSEMAPHORE hSemaphore,
  DWORD * pdwAdviseCookie
);

파라미터

rtStartTime
통지가 시작 되는 타임.
rtPeriodTime
통지를 하는 간격.
hSemaphore
어드바이스를 행하기 위한 수단이 되는 semaphore의 핸들.
pdwAdviseCookie
요구의 식별자를 받는 변수의 주소. 이것을 사용해, 장래, 요구를 캔슬하는 경우 등에,AdvisePeriodic 의 호출을 식별한다.

반환값

반환값은 이행에 의해 정해진다. 성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_FAIL
E_POINTER
E_INVALIDARG
E_NOTIMPL

주의

rtStartTime 에 의해 나타나는 타임에 이르렀을 경우, 핸들이 hSemaphore 로서 설정되어 있는 semaphore가 릴리즈 된다. 그 이후, semaphore는 rtPeriodTime 의 기간을 사용해 반복적으로 릴리즈 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IReferenceClock::Unadvise


IReferenceClock::AdviseTime

IReferenceClock::AdviseTime 메소드는, 타임이 경과한 비동기 통지를 요구한다.

HRESULT AdviseTime(
  REFERENCE_TIME rtBaseTime,
  REFERENCE_TIME rtStreamTime,
  HEVENT hEvent,
  DWORD * pdwAdviseCookie
);

파라미터

rtBaseTime
기본이 되는 기준 타임.
rtStreamTime
스트림 오프셋(offset) 타임.
hEvent
어드바이스를 행하기 위한 수단이 되는 이벤트의 핸들.
pdwAdviseCookie
요구의 식별자를 받는 변수의 주소. 이것을 사용해, 장래, 요구를 캔슬하는 경우 등에,AdviseTime 의 호출을 식별한다.

반환값

반환값은 이행에 의해 정해진다. 성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_FAIL
E_POINTER
E_INVALIDARG
E_NOTIMPL

주의

rtBaseTime 와 rtStreamTime 를 더한 타임에 이르면(자), 핸들이 hEvent 의 이벤트가 설정된다. 타임이 이미 경과하고 있는 경우, 이벤트는 즉석에서 설정된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

IReferenceClock::Unadvise


IDirectMusicPerformance::GetTime

Platform SDK: DirectX

IReferenceClock::GetTime

IReferenceClock::GetTime 메소드는, 현재 타임을 꺼낸다.

HRESULT GetTime(
  REFERENCE_TIME * pTime
);

파라미터

pTime
현재 타임을 받는 변수의 주소.

반환값

반환값은 이행에 의해 정해진다. 성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_FAIL
E_POINTER
E_INVALIDARG
E_NOTIMPL

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


IReferenceClock::Unadvise

IReferenceClock::Unadvise 메소드는, 통지의 요구를 캔슬한다.

HRESULT Unadvise(
  DWORD dwAdviseCookie
);

파라미터

dwAdviseCookie
IReferenceClock::AdviseTime 또는 IReferenceClock::AdvisePeriodic 의 각 메소드로 설정되어 있는, 캔슬하는 요구의 식별자.

반환값

반환값은 이행에 의해 정해진다. 성공하면 S_OK 를 돌려준다.

실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_FAIL
E_POINTER
E_INVALIDARG
E_NOTIMPL

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


DMUS_PMSG

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
구조체의 사이즈. 바이트 단위로 지정한다. 이 멤버는,IDirectMusicPerformance::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 채널). 포트, 채널 그룹, 및 MIDI 채널은,IDirectMusicPerformance::PChannelInfo 메소드를 사용하는 것에 의해, 이 값으로부터 꺼낼 수 있다. 템포 메세지 등, 채널 고유하지 않는 메세지에 대해서는, 이 값을 0 으로 설정한다.
dwVirtualTrackID
트랙의 식별자. 메세지가 트랙에 의해 송신되어 있지 않은 경우, 0 으로 설정한다.
pTool
툴 인터페이스의 주소. IDirectMusicGraph::StampPMsg 를 사용해 설정할 수 있다. 메세지가 출력 툴 이외의 툴에 보내지지 않는 경우는 NULL 로 설정할 수 있다.
pGraph
툴 그래프 인터페이스의 주소. IDirectMusicGraph::StampPMsg 를 사용해 설정할 수 있다. 메세지가 출력 툴 이외의 툴에 보내지지 않는 경우는 NULL 로 설정할 수 있다.
dwType
메세지 타입 (DMUS_PMSGT_TYPES 를 참조 ).
dwVoiceID
장래의 사용에 대비해 예약되고 있다. 0 을 설정해야 한다.
dwGroupID
메세지가 트랙에 의해 생성되고 있는 경우, 그 메세지가 소속하는 트랙 그룹 또는 그룹의 식별자(트랙은,IDirectMusicSegment::InsertTrack 메소드로 그룹에 할당할 수 있다). 대부분의 목적에 대해, 이 값은 0xFFFFFFF 이라도 좋다.
punkUser
어플리케이션에 의해 제공되는 IUnknown 인터페이스의 주소. 이 포인터는, 메세지를 릴리즈 했을 때에 항상 릴리즈 된다. 어플리케이션이 오브젝트를 보관 유지하고 싶은 경우는, 메세지를 릴리즈 하기 전에,AddRef 를 호출하지 않으면 안 된다. 메세지가 COM 포인터를 필요로 하지 않는 경우, 이 값은 NULL 이라도 좋다.

주의

DMUS_PMSG 구조체는,dwType 멤버에 이하의 값을 가지는 메세지에 대해, 그 자체에 의해 사용된다.

DMUS_PMSGT_STOP
이 타입의 메세지를 송신 하면, 지정된 타임에 퍼포먼스가 정지한다.
DMUS_PMSGT_DIRTY
제어 세그먼트(segment)가 시작 또는 종료 하면 와, 세그먼트(segment) 및 퍼포먼스 그래프내의 모든 툴은, 이 타입의 메세지를 받아들인다. 이것은, 세그먼트(segment)내의 모든 툴과 퍼포먼스 그래프가 GetParam 의 호출로 데이터를 캐싱 하는 경우,GetParam 를 재차 호출해, 각각의 데이터를 리프레쉬 해야 하는 것을 의미한다. 이 메세지 타입이 필요한 툴은,IDirectMusicTool::GetMediaTypes 의 호출로 이것을 지정해야 한다. 퍼포먼스 그래프내의 툴은, 퍼포먼스내의 각 세그먼트(segment)에 대해, 메세지의 카피를 1 부만 받는다. 이러한 툴은, 같은 타임 스탬프가 붙은 여분의 메세지를 무시해도 안전하다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::SendPMsg


DMUS_CHANNEL_PRIORITY_PMSG

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
채널의 우선 순위. 정의 끝난 값의 리스트에 대해서는, 「IDirectMusicPort::GetChannelPriority 」의 「주의」를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPort::SetChannelPriority ,IDirectMusicPerformance::SendPMsg


DMUS_CURVE_PMSG

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;
} DMUS_CURVE_PMSG;
DMUS_PMSG_PART
공통의 메세지 멤버에 전개되는 매크로. DMUS_PMSG 를 참조할것.
mtDuration
곡선의 지속 시간.
mtOriginalStart
오리지날의 시작 타임. 메세지를 생성 하면나무는 0 또는 곡선의 오리지날의 시작 타임으로 설정해야 한다.
mtResetDuration
곡선이 종료한 후, 리셋값을 설정할 때까지의 시간. bFlags 내에 DMUS_CURVE_RESET 가 없는 경우는 무시된다.
nStartValue
곡선의 시작값.
nEndValue
곡선의 종료값.
nResetValue
곡선의 리셋값. mtResetDuration 의 경과후, 또는 플래시 (릴리즈)나 무효화 시에 설정된다. bFlags 내에 DMUS_CURVE_RESET 가 없는 경우는 무시된다.
wMeasure
곡선이 발생하는 소절.
nOffset
곡선이 발생하는그리드로부터의 오프셋(offset). 뮤직 타임에 나타내진다.
bBeat
이 곡선이 발생하는 (소절내의) 박수.
bGrid
이 곡선이 발생하는 박으로부터의그리드 오프셋(offset).
bType
곡선의 타입. 다음의 값의 어느쪽이든을 사용한다.
DMUS_CURVET_CCCURVE
콘티뉴어스 콘트롤러 곡선 (MIDI 컨트롤 체인지의 채널 발음 메세지. 스테이터스 바이트는 &HBn. n 는 채널 번호를 나타낸다).
DMUS_CURVET_MATCURVE
모노포닉크아후타탓치 곡선 (MIDI Channel Pressure 채널 발음 메세지. 스테이터스 바이트는 &HDn).
DMUS_CURVET_PATCURVE
다선율 애프터 터치 곡선 (MIDI Poly Key Pressure 채널 발음 메세지. 스테이터스 바이트는 &HDn).
DMUS_CURVET_PBCURVE
핏치벤드 곡선 (MIDI Pitch Bend 채널 발음 메세지. 스테이터스 바이트는 &HEn).
bCurveShape
곡선의 셰이프. 다음의 값의 어느쪽이든을 사용한다.
DMUS_CURVES_EXP
지수 곡선 셰이프.
DMUS_CURVES_INSTANT
즉시 곡선 셰이프 (곡선의 시작과 종료가 거의 동시에 발생한다).
DMUS_CURVES_LINEAR
선형 곡선 셰이프.
DMUS_CURVES_LOG
대수 곡선 셰이프.
DMUS_CURVES_SINE
사인 곡선 셰이프.
bCCData
컨트롤 체인지 타입의 경우는, CC 번호를 지정한다.
bFlags
디폴트의 타임에 이르렀을 때, 또는 이행부가 원인으로 무효화가 발생했을 때에 nResetValue 를 설정해야 하는 경우는, 이 값을 DMUS_CURVE_RESET 로 설정한다. 이 값을 0 으로 설정했을 경우는, 곡선은 새로운 값에 영속적에 머무른다. 다른 모든 비트는 예약되고 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::SendPMsg


DMUS_MIDI_PMSG

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 경계까지의 추가.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

MIDI 메세지,IDirectMusicPerformance::SendPMsg


DMUS_NOTE_PMSG

DMUS_NOTE_PMSG 구조체는, 음악의 음표 이벤트용의 데이터에 의해 구성되어 있다.

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;
} DMUS_NOTE_PMSG;
DMUS_PMSG_PART
공통의 메세지 멤버에 전개되는 매크로. DMUS_PMSG 를 참조할것.
mtDuration
음표의 지속 시간.
wMusicValue
음표의 기술. 대부분의 연주 모드에서는, 이하에 나타내도록(듯이), 팩 된 4 비트값의 배열이다.
옥타브
-2 ~ 14 의 범위. 이 음표는, 1 옥타브의 12 배로 상하에 전조 된다.
코드 위치
0 ~ 15 의 범위이지만, 3 을 넘어서는 안 된다. 코드내의 최초의 위치는 0 이다.
스케일 위치
0 ~ 15 의 범위. 보통은 0 ~ 2 의 범위이지만, 1 음표의 코드로 해, 코드의 위에의 모든 것을 스케일 위치로서 해석하는 일도 가능.
변화음
-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 음표의 값.

주의

음표를 연주 하면 와,DMUS_NOTE_PMSG 는 그래프, 그래프내의 모든 툴을 경유해, 최종적인 MIDI 출력 툴에 도달한다. bFlags 멤버가 DMUS_NOTEF_NOTEON 로 설정되어 있는 것을 툴이 인식 하면, 툴은 MIDI 노트 온 메세지를 (DMUS_PMSG 파트의 dwPChannel 멤버에 따라) 적절한 포트에 송신한다. 다음에 이 플래그를 소거해, 타임 스탬프에 mtDuration 를 더해 메세지를 요구한다. 그 결과, 적절한 타임에 음표는 종료한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::SendPMsg ,뮤직값과 MIDI 음표


DMUS_NOTIFICATION_PMSG

DMUS_NOTIFICATION_PMSG 구조체는,DMUS_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_SEGMENT
세그먼트(segment) 이벤트. dwNotificationOption 로 한층 더 정의된다.
dwNotificationOption
통지 서브 타입의 식별자.

통지 타입이 GUID_NOTIFICATION_SEGMENT 의 경우, 이 멤버는 다음의 값의 어느쪽이든을 보관 유지한다.

DMUS_NOTIFICATION_SEGABORT
세그먼트(segment)가 IDirectMusicPerformance::Stop 에 의해 정지되었다.
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_MUSICSTARTED
재생이 시작 했다.
DMUS_NOTIFICATION_MUSICSTOPPED
재생이 정지했다.

통지 타입이 GUID_NOTIFICATION_MEASUREANDBEAT 의 경우, 이 멤버는 DMUS_NOTIFICATION_MEASUREBEAT 를 보관 유지한다. 그 외의 서브 타입은 정의되지 않는다.

통지 타입이 GUID_NOTIFICATION_CHORD 의 경우, 이 멤버는 DMUS_NOTIFICATION_CHORD 를 보관 유지한다. 그 외의 서브 타입은 정의되지 않는다.

dwField1
통지 타입에 고유의 추가 데이터. GUID_NOTIFICATION_MEASUREANDBEAT 통지의 경우, 이 멤버는 소절내의 박번호를 돌려준다.
dwField2
통지 타입에 고유의 추가 데이터. 장래의 사용 또는 어플리케이션에 의해 정의되는 사용에 대비해 예약되고 있다.

주의

대부분의 통지에 대해,punkUser 멤버 ( 「DMUS_PMSG 」를 참조)는, 세그먼트(segment) 상태의 IUnknown 포인터를 보관 유지한다. 이것은, 코드 및 커멘드의 취득에 사용 하면 매우 편리하다. 그 경우,IDirectMusicSegmentState 인터페이스의 쿼리를 실시해,IDirectMusicSegmentState::GetSegment 를 호출해 IDirectMusicSegment 포인터를 취득한다. 다음에,IDirectMusicSegment::GetParam 메소드를 호출해, 통지 메세지의 mtTime 멤버로 지정된 타임에 코드 또는 커멘드를 취득한다.

GUID_NOTIFICATION_PERFORMANCE 타입의 통지의 경우,punkUser 멤버는 항상 NULL 이다.

어플리케이션은 독자적인 통지 메세지 타입 및 서브 타입을 정의할 수 있어 여분의 데이터에 대해서는 dwField1 와 dwField2 를 사용할 수 있다. 그러한 커스텀 통지 메세지는, 그 외의 메세지와 같게, 할당 및 송신할 수 있다. 어플리케이션에 의해 정의된 트랙은, GUID (guidNotificationType) 가 IDirectMusicTrack::AddNotificationType 에게 건네진 후에, 특정 타입의 메세지를 송신할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

통지와 이벤트의 처리,IDirectMusicPerformance::SendPMsg


DMUS_PATCH_PMSG

DMUS_PATCH_PMSG 구조체는, 프로그램 체인지 메세지용의 데이터에 의해 구성되어 있다.

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 경계까지의 추가. 이 값은 무시된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

DMUS_MIDI_PMSG ,IDirectMusicPerformance::SendPMsg ,MIDI 메세지


DMUS_SYSEX_PMSG

DMUS_SYSEX_PMSG 구조체는 DMUS_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
데이터 배열. 메모리의 할당 방법 및 데이터를 이 멤버에 카피하는 방법의 예에 대해서는, 「IDirectMusicPerformance::SendPMsg 」의 「주의」를 참조할것.

주의

시스템에크스크루시브멧세이지의 데이터 부분은, 시스템에크스크루시브 식별자 (0xF0)로 시작되어, EOX (0xF7)로 끝나지 않으면 안 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

DMUS_MIDI_PMSG ,DMUS_PATCH_PMSG ,MIDI 메세지,IDirectMusicPerformance::SendPMsg


DMUS_TEMPO_PMSG

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 의 범위에 있는 템포.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::SendPMsg


DMUS_TIMESIG_PMSG

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 」를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::SendPMsg ,DMUS_TIMESIGNATURE


DMUS_TRANSPOSE_PMSG

DMUS_TRANSPOSE_PMSG 구조체는, 전조를 제어하는 메세지용의 데이터에 의해 구성되어 있다.

typedef struct _DMUS_TRANSPOSE_PMSG {
    DMUS_PMSG_PART
    short nTranspose;
} DMUS_TRANSPOSE_PMSG;
DMUS_PMSG_PART
공통의 메세지 멤버에 전개되는 매크로. DMUS_PMSG 를 참조할것.
nTranspose
전조 되는 반음의 수. 부의 값이어도 괜찮다.

주의

음표의 전조에 의해, 스탠다드 MIDI 의 범위 0 ~ 127 보다 외측에 이르렀을 경우는, 그 음표는 연주되지 않는다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::SendPMsg


DMUS_BUFFERDESC

DMUS_BUFFERDESC 구조체는,IDirectMusic::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 바이트와 데이터 사이즈를 맞춘 사이즈가 아니면 안된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

DMUS_EVENTHEADER ,IDirectMusicBuffer::PackStructured ,IDirectMusicBuffer::PackUnstructured


DMUS_CHORD_KEY

DMUS_CHORD_KEY 구조체는,IDirectMusicPerformance::MIDIToMusic 와 IDirectMusicPerformance::MusicToMIDI 의 각 메소드내에서 코드를 기술하는 경우에 사용된다.

typedef struct _DMUS_CHORD_KEY {
    WCHAR         wszName[16];
    WORD          wMeasure;
    BYTE          bBeat;
    BYTE          bSubChordCount;
    DMUS_SUBCHORD SubChordList[DMUS_MAXSUBCHORD];
    DWORD         dwScale;
    BYTE          bKey;
} DMUS_CHORD_KEY;

멤버

wszName
코드명.
wMeasure
코드가 소속하는 소절.
bBeat
코드가 소속하는 박.
bSubChordCount
코드의 서브 코드 리스트내에 있는 코드의 수.
SubChordList
코드를 구성하는 컴퍼넌트를 기술하는,DMUS_SUBCHORD 구조체의 배열.
dwScale
코드 전체의 기조가 되는 스케일.
bKey
코드 전체의 기조가 되는 키.

주의

이 구조체는,GUID_ChordParam 트랙 파라미터의 설정과 취득으로 사용되는,DMUS_CHORD_PARAM 구조체라고 해도 정의된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::GetParam ,IDirectMusicPerformance::SetParam ,IDirectMusicSegment::GetParam ,IDirectMusicSegment::SetParam ,IDirectMusicTrack::GetParam ,IDirectMusicTrack::SetParam ,뮤직 파라미터


DMUS_CHORD_PARAM

DMUS_CHORD_PARAM 구조체는, 트랙이 코드 트랙이며,rguidType 가 GUID_ChordParam 인 경우,GetParam 와 SetParam 의 다양한 메소드의 호출 시에 pParam 파라미터로서 사용된다.

typedef DMUS_CHORD_KEY DMUS_CHORD_PARAM;

「DMUS_CHORD_KEY 」를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.

참조

IDirectMusicPerformance::GetParam ,IDirectMusicPerformance::SetParam ,IDirectMusicSegment::GetParam ,IDirectMusicSegment::SetParam ,IDirectMusicTrack::GetParam ,IDirectMusicTrack::SetParam ,뮤직 파라미터


DMUS_CLOCKINFO

DMUS_CLOCKINFO 구조체는,IDirectMusic::EnumMasterClock 메소드를 사용해 열거된 클럭에 관한 정보를 보고한다.

typedef struct _DMUS_CLOCKINFO{
    DWORD           dwSize;
    DMUS_CLOCKTYPE  ctType;
    GUID            guidClock;
    WCHAR           wszDescription[DMUS_MAX_DESCRIPTION];
} DMUS_CLOCKINFO, *LPDMUS_CLOCKINFO;

멤버

dwSize
구조체의 사이즈. 바이트 단위로 지정한다. 이 구조체를 메소드에 건네주기 전에, 이 멤버를 sizeof(DMUS_CLOCKINFO) 에 초기화해야 한다.
ctType
클럭의 타입을 지정하는,DMUS_CLOCKTYPE 열거형의 멤버.
guidClock
클럭의 식별자. DirectMusic 의 master clock를 설정하기 위해서, 이 값을 IDirectMusic::SetMasterClock 메소드에 건네주어도 괜찮다.
wszDescription
클럭의 기술.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


DMUS_COMMAND_PARAM

DMUS_COMMAND_PARAM 구조체는, 트랙이 커멘드 트랙이며,rguidType 파라미터가 GUID_CommandParam 인 경우,GetParam 와 SetParam 의 다양한 메소드의 호출 시에 pParam 파라미터로서 사용된다.

typedef struct {
    BYTE bCommand;
    BYTE bGrooveLevel;
    BYTE bGrooveRange;
} DMUS_COMMAND_PARAM;

멤버

bCommand
커멘드 타입. DMUS_COMMANDT_TYPES 를 참조할것.
bGrooveLevel
커멘드의 그루브 레벨. 그루브 레벨은, 1 ~ 100 의 범위에서 지정하는 값이다.
bGrooveRange
그루브 레벨을 랜덤화할 수 있는 양. 예를 들어, 그루브 레벨이 35 로 범위가 4 의 경우, 실제의 그루브 레벨은 33 에서 37 의 몇개의 값이 된다. 현재는 이행되어 있지 않다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.

참조

IDirectMusicPerformance::GetParam ,IDirectMusicPerformance::SetParam ,IDirectMusicSegment::GetParam ,IDirectMusicSegment::SetParam ,IDirectMusicTrack::GetParam ,IDirectMusicTrack::SetParam


DMUS_COMMAND_PARAM2

DMUS_COMMAND_PARAM2 구조체는, 트랙이 커멘드 트랙이며,rguidType 파라미터가 GUID_CommandParam2 인 경우,GetParam 와 SetParam 의 다양한 메소드의 호출 시에 pParam 파라미터로서 사용된다.

typedef struct {
    MUSIC_TIME mtTime;
    BYTE bCommand;
    BYTE bGrooveLevel;
    BYTE bGrooveRange;
} DMUS_COMMAND_PARAM2;

멤버

mtTime
커멘드의 타임.
bCommand
커멘드 타입. DMUS_COMMANDT_TYPES 를 참조할것.
bGrooveLevel
커멘드의 그루브 레벨. 그루브 레벨은, 1 ~ 100 의 범위에서 지정하는 값이다.
bGrooveRange
그루브 레벨을 랜덤화할 수 있는 양. 예를 들어, 그루브 레벨이 35 로 범위가 4 의 경우, 실제의 그루브 레벨은 33 에서 37 의 몇개의 값이 된다. 현재는 이행되어 있지 않다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.

참조

IDirectMusicPerformance::GetParam ,IDirectMusicPerformance::SetParam ,IDirectMusicSegment::GetParam ,IDirectMusicSegment::SetParam ,IDirectMusicTrack::GetParam ,IDirectMusicTrack::SetParam


DMUS_EVENTHEADER

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 바이트 경계까지 추가된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusbuff.h 로 선언.

참조

IDirectMusicBuffer::GetNextEvent ,IDirectMusicBuffer::PackStructured ,IDirectMusicBuffer::PackUnstructured


DMUS_NOTERANGE

DMUS_NOTERANGE 구조체는, 악기가 응답해야 하는 음표 범위를 지정한다. 이 구조체의 배열을 IDirectMusicPerformance::DownloadInstrument 와 IDirectMusicPort::DownloadInstrument 의 각 메소드에 건네주어, 음색이 어느 음표에 응답해야할 것인가, 그 때문에(위해) 어느 음색리젼을 다운로드할 필요가 있는지를 지정한다.

typedef struct _DMUS_NOTERANGE {
    DWORD dwLowNote;
    DWORD dwHighNote;
} DMUS_NOTERANGE, *LPDMUS_NOTERANGE;

멤버

dwLowNote
음색이 응답해야 하는 MIDI 음표 범위의 낮은 소리.
dwHighNote
음색이 응답해야 하는 MIDI 음표 범위의 높은 소리.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmdls.h 로 선언.


DMUS_MUTE_PARAM

DMUS_MUTE_PARAM 구조체는, 트랙이 뮤트 트랙이며,rguidType 가 GUID_MuteParam 인 경우,GetParam 와 SetParam 의 다양한 메소드의 호출 시에 pParam 파라미터로서 사용된다.

typedef struct _DMUS_MUTE_PARAM {
    DWORD  dwPChannel;
    DWORD  dwPChannelMap;
    BOOL   fMute;
} DMUS_MUTE_PARAM;

멤버

dwPChannel
뮤트 또는 재맵 하는 퍼포먼스 채널. 구조체가 GetParam 에게 건네져 있는 경우, 이 멤버를 초기화해야 한다.
dwPChannelMap
dwPChannel 가 맵 되고 있는 채널. fMute 가 TRUE 의 경우, 이 멤버는 무시된다.
fMute
dwPChannel 가 뮤트 되고 있는 경우는 TRUE.

주의

P 채널 3 위에의 모든 음표를 P 채널 9 상에서 연주하고 싶은 경우, 이 구조체를 SetParam 메소드의 어느 쪽인가에 건네주기 전에,dwPChannel 을 3 으로 설정해,dwPChannelMap 를 9 로 설정한다. P 채널 8 위에의 음표를 뮤트 하고 싶은 경우,dwPChannel 을 8 으로 설정해,dwPChannelMap 를 0xFFFFFFFF 로 설정한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.

참조

IDirectMusicPerformance::GetParam ,IDirectMusicPerformance::SetParam ,IDirectMusicSegment::GetParam ,IDirectMusicSegment::SetParam ,IDirectMusicTrack::GetParam ,IDirectMusicTrack::SetParam


DMUS_OBJECTDESC

DMUS_OBJECTDESC 구조체를 사용해, DirectMusic 오브젝트를 기술한다. 이 구조체를 IDirectMusicLoader::GetObject 메소드에 건네주어, 로더가 기억장치로부터 꺼내야 할 오브젝트를 식별한다. 이 구조체로부터 오브젝트에 관한 정보를 꺼내려면 ,IDirectMusicLoader::EnumObject 과 IDirectMusicObject::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;
    PBYTE         pbMemData;
} DMUS_OBJECTDESC, *LPDMUS_OBJECTDESC;

멤버

dwSize
구조체의 사이즈. 바이트 단위로 지정한다. 이 구조체를 임의의 메소드에 건네주기 전에, 이 멤버를 sizeof(DMUS_OBJECTDESC) 에 초기화해야 한다.
dwValidData
어느 멤버가 유효한가 기술해, 몇개의 멤버에 관한 상세한 정보를 제공하는 플래그. 다음의 값이 정의되고 있다.
DMUS_OBJ_OBJECT
guidObject 멤버는 유효하다.
DMUS_OBJ_CLASS
guidClass 멤버는 유효하다.
DMUS_OBJ_NAME
wszName 멤버는 유효하다.
DMUS_OBJ_CATEGORY
wszCategory 멤버는 유효하다.
DMUS_OBJ_FILENAME
wszFileName 멤버는 유효하다.
DMUS_OBJ_FULLPATH
wszFileName 멤버는 풀 패스를 보관 유지하고 있다. 이 플래그를 세트 했을 경우, 로더는, DMUS_OBJ_FILENAME 가 세트되어 있지 않아도 wszFileName 가 유효하다라고 상정한다.
DMUS_OBJ_MEMORY
오브젝트는 메모리내에 있어,llMemLength 와 pbMemData 는 유효하다.
DMUS_OBJ_URL
wszFileName 멤버는 URL 를 보관 유지하고 있다 (DirectMusic 로더는 현재 URL 를 지원 하고 있지 않다).
DMUS_OBJ_VERSION
vVersion 멤버는 유효하다.
DMUS_OBJ_DATE
ftDate 멤버는 유효하다.
DMUS_OBJ_LOADED
오브젝트는 현재 메모리내에 로드 되고 있다.
guidObject
이 오브젝트의 일의의 식별자.
guidClass
오브젝트 클래스의 일의의 식별자. 모든 표준적인 오브젝트는,"CLSID_" 와 오브젝트명으로 구성되는 정의 끝난 식별자를 가지고 있다. 예를 들어, 세그먼트(segment) 오브젝트는 CLSID_DirectMusicSegment 로서 식별된다. Dmusici.h 헤더 파일내의 정의를 참조할것.
ftDate
오브젝트가 마지막에 편집된 일자.
vVersion
버젼 정보를 보관 유지하는 DMUS_VERSION 구조체.
wszName
오브젝트의 이름.
wszCategory
오브젝트의 카테고리.
wszFileName
파일의 패스. DMUS_OBJ_FULLPATH 가 설정되어 있는 경우, 이 값은 풀 패스이다. 그 이외의 경우, 파일명 뿐이다.
llMemLength
메모리내의 데이터의 사이즈.
pbMemData
메모리내의 데이터.

주의

IDirectMusicLoader::GetObject 메소드를 사용해 오브젝트를 꺼낼 수 있도록(듯이),wszName,idGuid, 및 wszFileName 가 적어도 1 개(살)에 유효한 데이터를 기입하지 않으면 안 된다.

이름과 카테고리의 캐릭터 라인은, 8 비트의 ANSI 문자는 아니고, WCHAR 포맷의 16 비트 문자를 사용한다. 필요에 따라서 변환을 실시하도록(듯이) 주의 해야 한다. C 라이브러리의 mbstowcs 함수를 사용해, 멀티 바이트로부터 Unicode,wcstombs 함수를 사용해 Unicode 로부터 멀티 바이트에의 변환도 실시할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

DirectMusic 로더


DMUS_PORTCAPS

DMUS_PORTCAPS 구조체는,IDirectMusic::EnumPort 메소드를 호출했을 때에 열거된 포트에 관한 정보를 받는다. IDirectMusicPort::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_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_XGINHARDWARE
이 포트는, 하드웨어내에 Yamaha XG 확장을 보관 유지하고 있다.
guidPort
포트의 식별자. 포트의 IDirectMusicPort 인터페이스를 취득하기 위해서, 이 값을 IDirectMusic::CreatePort 메소드에 건네주어도 괜찮다.
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" 와 같은 유저 지정의 알기 쉬운 이름이라도 좋다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


DMUS_PORTPARAMS

DMUS_PORTPARAMS 구조체는, DirectMusic 포트를 열기 위한 파라미터에 의해 구성되어 있다. IDirectMusic::CreatePort 메소드를 호출했을 때에, 이러한 파라미터가 건네받는다.

typedef struct _DMUS_PORTPARAMS {
    DWORD dwSize;
    DWORD dwValidParams;
    DWORD dwVoices;
    DWORD dwChannelGroups;
    DWORD dwAudioChannels;
    DWORD dwSampleRate;
    DWORD dwEffectFlags;
    DWORD fShare;
} DMUS_PORTPARAMS, *LPDMUS_PORTPARAMS;

멤버

dwSize
구조체의 사이즈. 바이트 단위로 지정한다. 이 구조체를 임의의 메소드에 건네주기 전에, 이 멤버를 sizeof(DMUS_PORTPARAMS) 에 초기화해야 한다.
dwValidParams
이 구조 체내의 어느 포트 파라미터에의 쓰기를 하고 있는지를 지정한다. 특정의 파라미터에 플래그를 세트 하는 것은, 포트의 생성시에, 메소드의 호출로 그 파라미터를 설정하고 싶은, 또는 디폴트값을 덧쓰기하고 싶은 것을 의미한다. 다음의 플래그가 정의되고 있다.

DMUS_PORTPARAMS_VOICES
DMUS_PORTPARAMS_CHANNELGROUPS
DMUS_PORTPARAMS_AUDIOCHANNELS
DMUS_PORTPARAMS_SAMPLERATE
DMUS_PORTPARAMS_EFFECTS
DMUS_PORTPARAMS_SHARE

dwVoices
이 포트로 필요한 발음의 수. 이것은 절대적인 최대치는 아니다. 포트는, 우선 순위의 낮은 발음을 삭제할 필요가 있을 때, 추가의 발음을 일시적으로 생성 해, 순조롭게 변화시킬 수가 있다.
dwChannelGroups
이 포트에 할당할 수 있는 채널 그룹의 수. IDirectMusic::EnumPort 와 IDirectMusicPort::GetCaps 의 각 메소드가 돌려준 DMUS_PORTCAPS 구조체로 지정되는 채널 그룹수이하가 아니면 안된다.
dwAudioChannels
희망의 출력 채널수.
dwSampleRate
희망의 샘플링 레이트. 헤르쯔 (Hz) 단위로 지정한다.
dwEffectFlags
희망의 특수 효과를 나타내는 플래그. 다음의 플래그가 정의되고 있다.

DMUS_EFFECT_NONE
DMUS_EFFECT_REVERB
DMUS_EFFECT_CHORUS

fShare
TRUE 의 경우, 모든 포트가, 이 포트에 할당할 수 있었던 채널 그룹을 사용한다. FALSE 의 경우, 포트는 배타 모드로 열려 그 외의 포트에 의한 같은 채널 그룹의 사용이 금지된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.

참조

DMUS_PORTCAPS


DMUS_RHYTHM_PARAM

트랙이 코드 트랙이며,rguidType 가 GUID_RhythmParam 인 경우, 다양한 GetParam 메소드를 호출할 때에 DMUS_RHYTHM_PARAM 구조체는 pParam 파라미터로서 사용된다.

typedef struct {
    DMUS_TIMESIGNATURE  TimeSig;
    DWORD               dwRhythmPattern;
} DMUS_RHYTHM_PARAM;

멤버

TimeSig
리듬 파라미터의 박자 기호를 보관 유지하는 DMUS_TIMESIGNATURE 구조체. DMUS_RHYTHM_PARAM 구조체를 GetParam 에 건네주기 전에, 이 구조체를 초기화해야 한다.
dwRhythmPattern
코드 순서의 리듬 패턴. 각 비트는 1 개 또는 복수의 소절내의 1 개의 박을 나타내, 1 은 그 박으로 코드가 온이 되어 있는 것, 0 은 코드가 존재하지 않는 것을 나타낸다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.

참조

IDirectMusicPerformance::GetParam ,IDirectMusicPerformance::SetParam ,IDirectMusicSegment::GetParam ,IDirectMusicSegment::SetParam ,IDirectMusicTrack::GetParam ,IDirectMusicTrack::SetParam


DMUS_SUBCHORD

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 이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


DMUS_SYNTHSTATS

IDirectMusicPort::GetRunningStats 메소드는,DMUS_SYNTHSTATS 구조체를 사용해, 신디사이저의 현재의 동작 스테이터스를 돌려준다.

typedef struct DMUS_SYNTHSTATS {
    DWORD dwSize;
    DWORD dwValidStats;
    DWORD dwVoices;
    DWORD dwTotalCPU;
    DWORD dwCPUPerVoice;
    DWORD dwLostNotes;
    DWORD dwFreeMemory;
    long  lPeakVolume;
} DMUS_SYNTHSTATS, *LPDMUS_SYNTHSTATS;

멤버

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) 단위로 측정된다.

주의

dwFreeMemory 를 제외해, 동작중의 모든 스테이터스 파라미터는 1 초 마다 갱신된다. 예를 들어,dwLostNotes 는, 1 초간에 없어진 음표의 합계수를 제공한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


DMUS_TEMPO_PARAM

DMUS_TEMPO_PARAM 구조체는, 트랙이 템포 트랙이며,rguidType 가 GUID_TempoParam 인 경우,GetParam 와 SetParam 의 다양한 메소드의 호출 시에 pParam 파라미터로서 사용된다.

typedef struct _DMUS_TEMPO_PARAM {
    MUSIC_TIME  mtTime;
    double      dblTempo;
} DMUS_TEMPO_PARAM;

멤버

mtTime
템포가 꺼내진 시간(이 멤버는 SetParam 의 메소드에서는 사용되지 않는다. SetParam 의 메소드는 대신에 그러한 mtTime 파라미터를 사용한다).
dblTempo
DMUS_TEMPO_MIN ~ DMUS_TEMPO_MAX 의 범위에 있는 템포.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.

참조

IDirectMusicPerformance::GetParam ,IDirectMusicPerformance::SetParam ,IDirectMusicSegment::GetParam ,IDirectMusicSegment::SetParam ,IDirectMusicTrack::GetParam ,IDirectMusicTrack::SetParam


DMUS_TIMESIGNATURE

IDirectMusicStyle::GetTimeSignature 메소드에 DMUS_TIMESIGNATURE 구조체를 건네주어, 스타일의 박자 기호에 관한 정보를 꺼낸다. 이 구조체는,rguidType 파라미터가 GUID_TimeSignature 이며, 트랙이 박자 기호 트랙 또는 스타일 트랙인 경우,DMUS_RHYTHM_PARAM 구조체 또는 다양한 GetParam 메소드에서도 사용된다.

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 를 참조 ).

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::GetParam ,IDirectMusicPerformance::SetParam ,IDirectMusicSegment::GetParam ,IDirectMusicSegment::SetParam ,IDirectMusicTrack::GetParam ,IDirectMusicTrack::SetParam ,DMUS_TIMESIG_PMSG


DMUS_VERSION

DMUS_VERSION 구조체는,DMUS_OBJECTDESC 구조체에 기술된 오브젝트의 버젼 정보를 보관 유지한다.

typedef struct _DMUS_VERSION {
    DWORD  dwVersionMS;
    DWORD  dwVersionLS;
} DMUS_VERSION, FAR *LPDMUS_VERSION;

멤버

dwVersionMS
버젼 번호의 최상정도 DWORD.
dwVersionLS
버젼 번호의 최하정도 DWORD.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


DMUS_WAVES_REVERB_PARAMS

DMUS_WAVES_REVERB_PARAMS 구조체는, 리바브에페크트에 관한 정보를 보관 유지한다.

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 Software Synthesizer 로 사용되는 SimpleVerb 로서 이행 되고 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


KSPROPERTY

KSPROPERTY 구조체는 IKsControl::KsProperty 메소드에게 건네져 프로퍼티와 조작을 식별한다.

KSPROPERTY 는 KSIDENTIFIER 구조체로서 정의되어 다음과 같이 선언된다.

typedef struct {
    union {
        struct {
            GUID   Set;
            ULONG  Id;
            ULONG  Flags;
        };
        LONGLONG    Alignment;
    };
} KSIDENTIFIER, *PKSIDENTIFIER;

멤버

Set
프로퍼티 세트의 식별자. 이하의 프로퍼티 세트 GUID 는, DirectMusic 에 의해 사전에 정의되고 있다.
GUID_DMUS_PROP_DLS1
항목 0 은, 이 포트가 DLS 샘플의 다운로드를 지원 할지 어떨지를 나타내는 불리언 값이다.
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_LegacyCaps
항목 0 은, 이 포트를 이행 하고 있는 기반의 Windows 멀티미디어 디바이스를 기술하는 MIDIINCAPS 구조체 또는 MIDIOUTCAPS 구조체이다. 이 포트의 능력의 구조체로 dwClass 가 DMUS_PC_INPUTCLASS 의 경우,MIDIINCAPS 구조체가 돌려주어진다. 그 이외의 경우는 MIDIOUTCAPS 구조체가 돌려주어진다.
GUID_DMUS_PROP_MemorySize
항목 0 은, 이 디바이스상에서 샘플 RAM 가 몇 바이트 이용할 수 있는지를 나타내는 불리언 값이다.
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
프로퍼티 세트내의 항목.
Flags
다음의 몇개의 플래그를 사용해, 조작을 지정한다.
KSPROPERTY_TYPE_GET
지정된 프로퍼티 항목의 값을 꺼낸다.
KSPROPERTY_TYPE_SET
지정된 프로퍼티 항목의 값을 설정한다.
KSPROPERTY_TYPE_BASICSUPPORT
프로퍼티 세트용으로 이용할 수 있는 지원의 타입을 결정한다. IKsControl::KsProperty 가 *pvPropertyData 에 돌려주는 데이터는, KSPROPERTY_TYPE_GET 와 KSPROPERTY_TYPE_SET 의 어느 쪽인지, 또는 양쪽 모두를 포함한 DWORD 이다. 이것은, 그 조작이 가능한가를 나타낸다.
Alignment
DirectMusic 에서는 사용되지 않는다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmksctrl.h 로 선언.

참조

포트의 프로퍼티 세트


파일 구조체

여기에서는, DirectMusic 파일로 사용되는 데이터 구조체의 레퍼런스 정보를 기술한다. 표준적인 DirectMusic 의 각 오브젝트는,IPersistStream 인터페이스를 사용해, 그 자체의 데이터를 로드하기 (위해)때문에, 대부분의 어플리케이션에서는, 이러한 구조체에 관한 지식은 필요없다. 이러한 구조체는, DirectMusic 와 호환성이 있는 포맷으로 데이터를 보존할 필요가 있는 뮤직 오쏘링 어플리케이션용으로 주로 준비되어 있다.

DirectMusic 파일에서는, 이하의 구조체가 사용된다.

  • DMUS_IO_BAND_ITEM_HEADER
  • DMUS_IO_BAND_TRACK_HEADER
  • DMUS_IO_CHORD
  • DMUS_IO_CHORDENTRY
  • DMUS_IO_CHORDMAP
  • DMUS_IO_CHORDMAP_SIGNPOST
  • DMUS_IO_CHORDMAP_SUBCHORD
  • DMUS_IO_COMMAND
  • DMUS_IO_CURVE_ITEM
  • DMUS_IO_INSTRUMENT
  • DMUS_IO_MOTIFSETTINGS
  • DMUS_IO_MUTE
  • DMUS_IO_NEXTCHORD
  • DMUS_IO_PARTREF
  • DMUS_IO_PATTERN
  • DMUS_IO_REFERENCE
  • DMUS_IO_SEGMENT_HEADER
  • DMUS_IO_SEQ_ITEM
  • DMUS_IO_SIGNPOST
  • DMUS_IO_STYLE
  • DMUS_IO_STYLECURVE
  • DMUS_IO_STYLENOTE
  • DMUS_IO_STYLEPART
  • 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_HEADER
  • DMUS_IO_VERSION

참조

DirectMusic 의 파일 형식


DMUS_IO_BAND_ITEM_HEADER

DMUS_IO_BAND_ITEM_HEADER 구조체는, 밴드 체인지에 관한 정보를 보관 유지한다. 이 구조체는,밴드 트랙 형식내에서 사용된다.

typedef struct _DMUS_IO_BAND_ITEM_HEADER {
    MUSIC_TIME lBandTime;
} DMUS_IO_BAND_ITEM_HEADER;
lBandTime
밴드 체인지의 타임.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.


DMUS_IO_BAND_TRACK_HEADER

DMUS_IO_BAND_TRACK_HEADER 구조체는, 밴드 트랙의 디폴트 동작에 관한 정보를 보관 유지한다. 이 구조체는,밴드 트랙 형식내에서 사용된다.

typedef struct _DMUS_IO_BAND_TRACK_HEADER {
    BOOL bAutoDownload;
} DMUS_IO_BAND_TRACK_HEADER;
bAutoDownload
세그먼트(segment)를 연주하고 있을 때의, 음색을 자동 다운로드하기 위한 플래그.

주의

자동 다운로드의 상세한 것에 대하여는, 「밴드의 사용법」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.


DMUS_IO_CHORD

DMUS_IO_CHORD 구조체는, 코드 체인지에 관한 정보를 보관 유지한다. 이 구조체는,코드 트랙 리스트내에서 사용된다.

typedef struct _DMUS_IO_CHORD {
    WCHAR       wszName[16];
    MUSIC_TIME  mtTime;
    WORD        wMeasure;
    BYTE        bBeat;
} DMUS_IO_CHORD;
wszName
코드의 이름.
mtTime
코드의 타임.
wMeasure
코드가 소속하는 소절.
bBeat
코드가 소속하는 박.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.


DMUS_IO_CHORDENTRY

DMUS_IO_CHORDENTRY 구조체는, 코드 엔트리에 관한 정보를 보관 유지한다. 이 구조체는,코드 맵 형식내에서 사용된다.

typedef struct _DMUS_IO_CHORDENTRY {
    DWORD   dwFlags;
    WORD    wConnectionID;
} DMUS_IO_CHORDENTRY;
dwFlags
코드가 코드 그래프내의 시작 코드 (비트 2 가 세트)일까 종료 코드 (비트 3 이 세트)인지를 나타내는 플래그.
wConnectionID
실행시 포인터를 this 에 옮겨놓는다. 각 코드 엔트리에는, 일의의 접속 식별자가 태그 붙이고 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.


DMUS_IO_CHORDMAP

DMUS_IO_CHORDMAP 구조체는, 코드 맵에 관한 정보를 보관 유지한다. 이 구조체는,코드 맵 형식내에서 사용된다.

typedef struct _DMUS_IO_CHORDMAP {
    WCHAR   wszLoadName[20];
    DWORD   dwScalePattern;
    DWORD   dwFlags;
} DMUS_IO_CHORDMAP;
wszLoadName
코드 맵의 이름. 코드 맵을 로드할 때, 오브젝트 기술 중(안)에서 사용된다.
dwScalePattern
코드 맵에 관련지을 수 있었던 스케일. 하위 24 비트는 각각 1 개의 반음을 나타내, 최하정도 비트는 루트음이다. 비트가 세트 되고 있는 경우, 거기에 대응하는 음표는 스케일내에 존재한다.
dwFlags
장래의 사용에 대비해 예약되고 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.


DMUS_IO_CHORDMAP_SIGNPOST

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 개의 플래그를 조합한 것을 설정할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.

참조

DMUS_IO_SIGNPOST


DMUS_IO_CHORDMAP_SUBCHORD

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
이 서브 코드가 지원 하는 레벨을 나타내는 비트 필드. 스타일내의 각 파트에는 레벨을 할당할 수 있어 레벨이 이 멤버에 포함되는 파트에만 도착해 이 코드가 사용된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.

참조

DMUS_SUBCHORD


DMUS_IO_COMMAND

DMUS_IO_COMMAND 구조체는, 커멘드 이벤트에 관한 정보를 보관 유지한다. 이 구조체는,코만드트락크체크내에서 사용된다.

typedef struct _DMUS_IO_COMMAND {
    MUSIC_TIME  mtTime;
    WORD        wMeasure;
    BYTE        bBeat;
    BYTE        bCommand;
    BYTE        bGrooveLevel;
    BYTE        bGrooveRange;
} DMUS_IO_COMMAND;
mtTime
커멘드의 타임.
wMeasure
커멘드가 소속하는 소절.
bBeat
커멘드가 소속하는 박.
bCommand
커멘드 타입. DMUS_COMMANDT_TYPES 를 참조할것.
bGrooveLevel
그루브 레벨. 커멘드가 그루브 커멘드가 아닌 경우는 0 을 지정한다.
bGrooveRange
그루브 레벨을 랜덤화할 수 있는 양. 예를 들어, 그루브 레벨이 35 로 범위가 4 의 경우, 실제의 그루브 레벨은 33 ~ 37 의 몇개의 값이 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.


DMUS_IO_CURVE_ITEM

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;
} 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).
bCurveShape
곡선의 셰이프. 다음의 셰이프가 정의되고 있다.
DMUS_CURVES_EXP
지수 곡선 셰이프.
DMUS_CURVES_INSTANT
즉시 곡선 셰이프 (곡선의 시작과 종료가 거의 동시에 발생한다).
DMUS_CURVES_LINEAR
선상 곡선 셰이프.
DMUS_CURVES_LOG
대수 곡선 셰이프.
DMUS_CURVES_SINE
사인 곡선 셰이프.
bCCData
컨트롤 체인지 타입의 경우는, CC 번호를 지정한다.
bFlags
디폴트의 타임에 이르렀을 때, 또는 이행부가 원인으로 무효화가 발생했을 때에 nResetValue 를 설정해야 하는 경우는, 이 값을 1 으로 설정한다. 이 값을 0 으로 설정했을 경우는, 곡선은 새로운 값에 영속적에 머무른다. 다른 모든 비트는 예약되고 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.

참조

DMUS_IO_SEQ_ITEM


DMUS_IO_INSTRUMENT

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;
} 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_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
채널의 우선 순위. 정의 끝난 값의 리스트에 대해서는, 「IDirectMusicPort::GetChannelPriority 」를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.


DMUS_IO_MOTIFSETTINGS

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
루프 부분의 종료 포인트.
dwResolution
디폴트의 분해가능. 「DMUS_TIME_RESOLVE_FLAGS 」를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.

참조

IDirectMusicSegment::SetLoopPoints


DMUS_IO_MUTE

DMUS_IO_MUTE 구조체는, 채널 위에의 뮤트 이벤트에 관한 정보를 보관 유지한다. 이 구조체는,뮤트트락크체크내에서 사용된다.

typedef struct _DMUS_IO_MUTE {
    MUSIC_TIME  mtTime;
    DWORD       dwPChannel;
    DWORD       dwPChannelMap;
} DMUS_IO_MUTE;
mtTime
이벤트의 타임.
dwPChannel
뮤트 또는 재맵 하는 퍼포먼스 채널.
dwPChannelMap
dwPChannel 가 맵 되고 있는 채널. dwPChannel 를 뮤트 하는 경우는 0xFFFFFFFF 로 설정한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.

참조

DMUS_MUTE_PARAM


DMUS_IO_NEXTCHORD

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 멤버를 참조한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.


DMUS_IO_PARTREF

DMUS_IO_PARTREF 구조체는, 파트 참조에 관한 정보를 보관 유지한다. 이 구조체는,스타일 형식내에서 사용된다.

typedef struct _DMUS_IO_PARTREF {
    GUID  guidPartID;
    WORD  wLogicalPartID;
    BYTE  bVariationLockID;
    BYTE  bSubChordLevel;
    BYTE  bPriority;
    BYTE  bRandomVariation;
} DMUS_IO_PARTREF;
guidPartID
파트의 식별자.
wLogicalPartID
포트 위에의 특정의 MIDI 채널에 대응하고 있는 식별자.
bVariationLockID
이 멤버내의 값과 같은 값을 가지는 파트는, 항상 같은 바리에이션을 연주한다.
bSubChordLevel
이 파트가 필요로 하는 서브 코드 레벨. 「주의」를 참조할것.
bPriority
파트의 우선 순위. 우선 순위의 상세한 것에 대하여는, 「채널」을 참조할것.
bRandomVariation
이 값을 설정 하면, 일치하는 바리에이션이 랜덤인 순서로 연주된다. 이 값을 해제 하면, 일치하는 바리에이션이 시퀀셜인 순서로 연주된다.

주의

bSubChordLevel 멤버는, 0 으로부터 시작되는 인덱스값을 가진다. 실행시에는, 이 값에 의해 1 이 왼쪽 쉬프트 되어DMUS_SUBCHORD 구조체의 dwLevels 멤버와 비교하기 위한 1 비트값이 생성된다. 따라서,bSubChordLevel 가 0 의 파트는,dwLevels 에 1 을 포함하고 있던 임의의 서브 코드에 맵 된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.


DMUS_IO_PATTERN

DMUS_IO_PATTERN 구조체는, 패턴에 관한 정보를 보관 유지한다. 이 구조체는,스타일 형식내에서 사용된다.

typedef struct _DMUS_IO_PATTERN {
    DMUS_IO_TIMESIG  timeSig;
    BYTE             bGrooveBottom;
    BYTE             bGrooveTop;
    WORD             wEmbellishment;
    WORD             wNbrMeasures;
} DMUS_IO_PATTERN;
timeSig
스타일의 디폴트의 박자 기호를 덧쓰기하기 위한 박자 기호를 보관 유지하는 DMUS_IO_TIMESIG 구조체.
bGrooveBottom
그루브 범위의 최저음.
bGrooveTop
그루브 범위의 최고음.
wEmbellishment
장식의 타입. DMUS_COMMANDT_TYPES 를 참조할것.
wNbrMeasures
소절내의 패턴의 길이.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.


DMUS_IO_REFERENCE

DMUS_IO_REFERENCE 구조체는, 다른 파일에 보존되고 있는 다른 오브젝트에의 참조에 관한 정보를 보관 유지한다. 이 구조체는, 참조 리스트체크내에서 사용된다. 「공통의 체크」를 참조할것.

typedef struct _DMUS_IO_REFERENCE {
    GUID    guidClassID;
    DWORD   dwValidData;
} DMUS_IO_REFERENCE;
guidClassID
클래스 식별자.
dwValidData
참조의 어느 데이타체크가 존재하는지를 나타내는 플래그. 값의 리스트에 대해서는, 대응하는 DMUS_OBJECTDESC 의 멤버를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.


DMUS_IO_SEGMENT_HEADER

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;
} DMUS_IO_SEGMENT_HEADER;
dwRepeats
반복 회수.
mtLength
세그먼트(segment)의 길이.
mtPlayStart
재생의 시작 포인트. 보통은 0 으로 설정한다.
mtLoopStart
르브 부분의 시작 포인트. 보통은 0 으로 설정한다.
mtLoopEnd
루프 부분의 종료 포인트.
dwResolution
디폴트의 분해가능. 「DMUS_TIME_RESOLVE_FLAGS 」를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.

참조

DMUS_IO_MOTIFSETTINGS ,IDirectMusicSegment::SetLoopPoints


DMUS_IO_SEQ_ITEM

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
음표가 연주되는그리드 경계로부터의 오프셋(offset). 뮤직 타임에 나타내진다. MIDI 음표는 로드시에 가장 가까운 그리드에 관련지을 수 있기 (위해)때문에, 이 값은 정 또는 부 이라도 좋다.
bStatus
MIDI 이벤트 타입. MIDI 스테이터스 바이트와 같지만, 채널 정보가 없다.
bByte1
MIDI 데이터의 최초의 1 바이트.
bByte2
MIDI 데이터의 2 바이트째.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.

참조

DMUS_IO_CURVE_ITEM ,MIDI 메세지


DMUS_IO_SIGNPOST

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
싸인 포스트가 소속하는 소절.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.

참조

DMUS_IO_CHORDMAP_SIGNPOST


DMUS_IO_STYLE

DMUS_IO_STYLE 구조체는, 스타일의 박자 기호와 템포에 관한 정보를 보관 유지한다. 이 구조체는,스타일 형식내에서 사용된다.

typedef struct _DMUS_IO_STYLE {
    DMUS_IO_TIMESIG  timeSig;
    double           dblTempo;
} DMUS_IO_STYLE;
timeSig
스타일의 디폴트의 박자 기호를 보관 유지하는 DMUS_IO_TIMESIG 구조체.
dblTempo
스타일의 템포.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.


DMUS_IO_STYLECURVE

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;
} DMUS_IO_STYLECURVE;
mtGridStart
곡선이 발생하는 그리드의 시작 타임.
dwVariation
이 곡선이 소속하는 바리에이션. 각 비트는 32 있는 바리에이션의 어느 쪽인가에 대응한다.
mtDuration
곡선의 지속 시간.
mtResetDuration
곡선이 종료한 후, 리셋값을 설정할 때까지의 시간.
nTimeOffset
곡선이 발생하는 mtGridStart 로부터의 오프셋(offset).
nStartValue
시작값.
nEndValue
종료값.
nResetValue
곡선의 리셋값. mtResetDuration 의 경과후, 또는 플래시 (릴리즈)나 무효화 시에 설정된다.
bEventType
곡선의 타입. 상세한 것에 대하여는, 「DMUS_IO_CURVE_ITEM 」를 참조할것.
bCurveShape
곡선의 셰이프. 상세한 것에 대하여는, 「DMUS_IO_CURVE_ITEM 」를 참조할것.
bCCData
컨트롤 체인지 타입의 경우는, CC 번호를 지정한다.
bFlags
디폴트의 타임에 이르렀을 때, 또는 이행부가 원인으로 무효화가 발생했을 때에 nResetValue 를 설정해야 하는 경우는, 이 값을 1 으로 설정한다. 이 값을 0 으로 설정했을 경우는, 곡선은 새로운 값에 영속적에 머무른다. 다른 모든 비트는 예약되고 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.

참조

DMUS_CURVE_PMSG ,DMUS_IO_CURVE_ITEM


DMUS_IO_STYLENOTE

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;
} DMUS_IO_STYLENOTE;
mtGridStart
음표가 발생하는 타임.
dwVariation
이 음표가 소속하는 바리에이션. 각 비트는 32 있는 바리에이션의 어느 쪽인가에 대응한다.
mtDuration
음표의 지속 시간.
nTimeOffset
mtGridStart 로부터의 오프셋(offset).
wMusicValue
스케일내의 위치.
bVelocity
음표의 velocity.
bTimeRange
시작 타임을 랜덤화하는 범위.
bDurRange
지속 시간을 랜덤화하는 범위.
bVelRange;
velocity를 랜덤화하는 범위.
bInversionID
이 음표가 소속하는 회전 그룹의 식별자.
bPlayModeFlags
파트의 연주 모드를 덧쓰기하는 플래그. 값의 리스트에 대해서는, 「DMUS_PLAYMODE_FLAGS 」를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.


DMUS_IO_STYLEPART

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;
} DMUS_IO_STYLEPART;
timeSig
스타일의 디폴트의 박자 기호를 덧쓰기하기 위한 박자 기호를 보관 유지하는 DMUS_IO_TIMESIG 구조체.
dwVariationChoices
각 WORD 는, 32 있는 바리에이션의 어느 쪽인가에 대응한다. 각 WORD 에 세트 되는 플래그는, 그 바리에이션으로 지원 되는 코드의 타입을 나타낸다 ( 「주의」를 참조). 다음의 플래그가 정의되고 있다.
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_IMA25_MODE
DMUS_VARIATIONF_DMUS_MODE
몇개의 플래그를 세트 해, 모드를 나타낸다. DirectMusic 의 경우, 이 값은 항상 DMUS_VARIATIONF_DMUS_MODE 가 아니면 안된다.
guidPartID
파트의 일의의 식별자.
wNbrMeasures
파트의 길이. 소절 단위로 나타낸다.
bPlayModeFlags
연주 모드를 정의하는 플래그. 값의 리스트에 대해서는, 「DMUS_PLAYMODE_FLAGS 」를 참조할것.
bInvertUpper
회전의 상한.
bInvertLower
회전의 하한.

주의

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도위에 음의 코드가 계속되는 코드를 처리한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.


DMUS_IO_SUBCHORD

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 이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.

참조

DMUS_SUBCHORD


DMUS_IO_SYSEX_ITEM

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
데이터의 길이. 바이트 단위로 지정한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.

참조

MIDI 시스템 메세지


DMUS_IO_TEMPO_ITEM

DMUS_IO_TEMPO_ITEM 구조체는, 트랙내의 템포 체인지에 관한 정보를 보관 유지한다. 이 구조체는,텐포트락크체크내에서 사용된다.

typedef struct _DMUS_IO_TEMPO_ITEM {
    MUSIC_TIME  mtTime;
    double      dblTempo;
} DMUS_IO_TEMPO_ITEM;
mtTime
템포 체인지의 타임.
dblTempo
템포. 1 분 쯤의 박수로 나타낸다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.


DMUS_IO_TIMESIG

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
박근처의 그리드 (소분할 ).

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.

참조

DMUS_IO_TIMESIGNATURE_ITEM


DMUS_IO_TIMESIGNATURE_ITEM

DMUS_IO_TIMESIGNATURE_ITEM 구조체는, 박자 기호 체인지에 관한 정보를 보관 유지한다. 이 구조체는,박자 기호 트락크체크내에서 사용된다.

typedef struct _DMUS_IO_TIMESIGNATURE_ITEM {
    MUSIC_TIME  mtTime;
    BYTE        bBeatsPerMeasure;
    BYTE        bBeat;
    WORD        wGridsPerBeat;
} DMUS_IO_TIMESIGNATURE_ITEM;
mtTime
이벤트의 타임.
bBeatsPerMeasure
소절 근처의 박수 (박자 기호의 분자).
bBeat
음표가 받는 박 (박자 기호의 분모). 이 값이 1 때는 전음부, 2 때는 2 분 음표, 4 때는 4 분 음표를 의미한다. 이하 같이이다. 0 은 256 분 음표를 의미한다.
wGridsPerBeat
박근처의 그리드 (소분할 ).

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.

참조

DMUS_IO_TIMESIG , DMUS_TIMESIG_PMSG


DMUS_IO_TOOL_HEADER

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
툴이 유효한 퍼포먼스 채널의 배열.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.

참조

IDirectMusicGraph::InsertTool


DMUS_IO_TRACK_HEADER

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 이외의 값이 아니면 안된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.

참조

IDirectMusicSegment::GetTrackGroup ,IDirectMusicSegment::InsertTrack ,트랙 형식


DMUS_IO_VERSION

DMUS_IO_VERSION 구조체는, 데이터의 버젼 번호를 보관 유지한다. 이 구조체는, 다양한 체크의 바젼사브체크내에서 사용된다. 「공통의 체크」를 참조할것.

typedef struct _DMUS_IO_VERSION {
    DWORD  dwVersionMS;
    DWORD  dwVersionLS;
} DMUS_IO_VERSION;
dwVersionMS
버젼 번호의 상위 32 비트.
dwVersionLS
버젼 번호의 하위 32 비트.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicf.h 로 선언.


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_WAVEDATA


DMUS_ARTICPARAMS

DMUS_ARTICPARAMS 구조체는,DLS 아티큐레이션체크의 파라미터를 기술한다. 아티큘레이션에 관한 모든 파라미터는 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 구조체.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmdls.h 로 선언.


DMUS_ARTICULATION

DMUS_ARTICULATION 구조체는,DLS 음색의 아티큐레이션체크에 대해 기술한다. 이 체크는, 이용 가능한 모든 아티큘레이션 데이터를 1 개의 리스트내 로 유지할 수 있다. 예를 들어, DLS 레벨 1 체크와 있는 메이커 고유의 아티큐레이션체크를 보관 유지할 수 있다. DLS 체크는 ulArt1Idx 에 의해 참조되어 추가의 아티큐레이션체크는 모두 ulFirstExtCkIdx 로 시작되는 리스트에 의해 참조된다.

typedef struct {
    ULONG ulArt1Idx;
    ULONG ulFirstExtCkIdx;
} DMUS_ARTICULATION;
ulArt1Idx
DMUS_OFFSETTABLE 구조 체내에 있는, DLS 아티큐레이션체크의 인덱스. 이 값이 0 의 경우, DLS 아티큘레이션은 존재하지 않는다.
ulFirstExtCkIdx
최초의 써드파티 확장 체크의 인덱스. 이 값이 0 의 경우, 이 아티큘레이션에 관련하는 써드파티 확장 체크는 존재하지 않는다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmdls.h 로 선언.

참조

DMUS_ARTICULATION2


DMUS_ARTICULATION2

DMUS_ARTICULATION 구조체는,DLS 음색의 아티큐레이션체크에 대해 기술한다. 이 구조체는, 포맷이 DMUS_DOWNLOADINFO_INSTRUMENT2 로서 정의되고 있는 경우 (Dmdls.h 헤더 파일로 선언)에 사용된다. 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 아티큘레이션을 보다 지원하기 위한 추가의 아티큐레이션체크.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmdls.h 로 선언.

참조

DMUS_ARTICULATION


DMUS_COPYRIGHT

DMUS_COPYRIGHT 구조체는,DLS 데이터내에 옵션의 저작권 체크를 기술한다.

typedef struct {
    ULONG cbSize;
    BYTE  byCopyright[ ];
} DMUS_COPYRIGHT;
cbSize
데이터의 사이즈.
byCopyright[ ]
저작권 데이터.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmdls.h 로 선언.


DMUS_DOWNLOADINFO

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_WAVE
DMUS_WAVE 구조체로부터 시작되는 PCM 웨이브의 데이터.
dwDLId
오브젝트의 일의의 32 비트 식별자. 「주의」를 참조할것.
dwNumOffsetTableEntries
후에 계속되는 DMUS_OFFSETTABLE 구조 체내의 엔트리의 수.
cbSize
DMUS_DOWNLOADINFO,DMUS_OFFSETTABLE, 및 실제의 데이타체크의 합계 사이즈.

주의

dwDLId 내의 식별자는, 오브젝트를 접속하기 위해서 사용되어IDirectMusicPortDownload::GetDLId 메소드를 사용해 취득된다. 주로, 악기내의 리젼을 웨브체크에 결합한다. 예를 들어, 웨이브 다운로드에 3 의 dwDLId 를 지정했을 경우, 음색 체크는, 몇개의 DMUS_REGION 구조체의 WaveLink.ulTableIndex 멤버에 값 3 이 배치된 형태로 다운로드된다. 이것은, 리젼이 웨브체크에 접속되고 있는 것을 나타낸다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmdls.h 로 선언.

참조

하위 레벨 DLS


DMUS_EXTENSIONCHUNK

DMUS_EXTENSIONCHUNK 구조체는,DLS 확장 체크를 기술한다. DirectMusic 에 있어 미지의 확장을 DLS 파일 포맷에 가세했을 경우, 이러한 확장 모든 것을 이 가변 사이즈의 체크로 다운로드한다.

typedef struct {
    ULONG  cbSize;
    ULONG  ulNextExtCkIdx;
    FOURCC ExtCkID;
    BYTE   byExtCk[ ];
} DMUS_EXTENSIONCHUNK;
cbSize
체크의 사이즈.
ulNextExtCkIdx
DMUS_OFFSETTABLE 구조 체내에 있는, 다음의 확장 체크의 인덱스. 이 값이 0 의 경우, 써드파티의 확장 체크는 그 이상 존재하지 않는다.
ExtCkID
체크 식별자.
byExtCk[ ]
데이터.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmdls.h 로 선언.


DMUS_INSTRUMENT

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 를 참조)의 인덱스. 이 값이 0 의 경우, 이 악기에는 글로벌 아티큘레이션이 없다.
ulFirstExtCkIdx
DMUS_OFFSETTABLE 구조 체내에 있는, 최초의 확장 체크 (DMUS_ARTICULATION 를 참조)의 인덱스. DirectMusic 가 인식하고 있지 않는 새로운 체크를 추가하기 위해서 사용된다. 이 값이 0 의 경우, 이 악기에는 써드파티의 확장을 관련지을 수 있지 않았다.
ulCopyrightIdx
DMUS_OFFSETTABLE 구조 체내에 있는, 옵션의 저작권 체크 ( 「DMUS_COPYRIGHT 」를 참조)의 인덱스. 이 값이 0 의 경우, 이 악기에는 저작권 정보를 관련지을 수 있지 않았다.
ulFlags
악기의 추가의 플래그. 다음의 플래그가 정의되고 있다.
DMUS_INSTRUMENT_GM_INSTRUMENT
이 악기는 General MIDI 표준의 악기이다. 패치가 중복 하고 있는 경우, GM 악기의 우선 순위는 반드시 다른 DLS 악기보다 낮아진다. 예를 들어, 패치 0 을 지정해 GM 악기를 다운로드해, 같은 패치 0 을 지정해 GM 이외의 악기를 다운로드했을 경우, 재생 시에 반드시 GM 이외의 악기가 선택된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmdls.h 로 선언.


DMUS_LFOPARAMS

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)의 규격을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmdls.h 로 선언.

참조

DMUS_ARTICPARAMS


DMUS_MSCPARAMS

DMUS_MSCPARAMS 구조체는,DLS 아티큐레이션체크의 팬을 정의한다. 이 구조체는,DMUS_ARTICPARAMS 구조체로 사용된다.

typedef struct {
    PERCENT ptDefaultPan;
} DMUS_MSCPARAMS;
ptDefaultPan
디폴트의 팬. -50% ~ 50% 의 범위를 0.1% 단위로 지정해, 16 비트왼쪽 쉬프트 한 것.

주의

PERCENT 는 long 로서 정의된다. 팬의 값에 대해서는, MMA (MIDI Manufacturers Association)의 규격을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmdls.h 로 선언.

참조

DMUS_ARTICPARAMS


DMUS_OFFSETTABLE

DMUS_OFFSETTABLE 구조체는, 포트에 다운로드중의 DLS 음색 데이터의 헤더로 사용된다.

typedef struct _DMUS_OFFSETTABLE {
    ULONG ulOffsetTable[DMUS_DEFAULT_SIZE_OFFSETTABLE];
} DMUS_OFFSETTABLE;
ulOffsetTable
데이터의 바이트 오프셋(offset)의 배열.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmdls.h 로 선언.

참조

하위 레벨 DLS


DMUS_PEGPARAMS

DMUS_PEGPARAMS 구조체는,DLS 아티큐레이션체크의 피치 엔벌로프를 정의한다. 이 구조체는,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)의 규격을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmdls.h 로 선언.

참조

DMUS_ARTICPARAMS


DMUS_REGION

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 내에서 선언되고 있다 ).

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmdls.h 로 선언.


DMUS_VEGPARAMS

DMUS_VEGPARAMS 구조체는,DLS 아티큐레이션체크의 볼륨 엔벌로프를 정의한다.

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)의 규격을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmdls.h 로 선언.

참조

DMUS_ARTICPARAMS


DMUS_WAVE

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
체크의 웨이브 포맷.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmdls.h 로 선언.


DMUS_WAVEDATA

DMUS_WAVEDATA 구조체는,DLS 웨이브 다운로드의 데이타체크를 구성한다. 웨이브 데이터가 WAVEFORMATEX 체크에 의해 정의되는 성질상, 이 구조체는 DMUS_WAVE 구조체에도 파묻히고 있다.

typedef struct {
    ULONG cbSize;
    BYTE byData[ ];
} DMUS_WAVEDATA;
cbSize
데이터의 사이즈.
byData[ ]
PCM 웨이브 데이터.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmdls.h 로 선언.


열거형

여기에서는, 다음의 열거형에 관한 레퍼런스를 제공한다.

  • DMUS_CLOCKTYPE
  • DMUS_COMMANDT_TYPES
  • DMUS_COMPOSEF_FLAGS
  • DMUS_NOTEF_FLAGS
  • DMUS_PLAYMODE_FLAGS
  • DMUS_PMSGF_FLAGS
  • DMUS_PMSGT_TYPES
  • DMUS_SEGF_FLAGS
  • DMUS_SHAPET_TYPES
  • DMUS_TIME_RESOLVE_FLAGS
  • DMUS_TRACKF_FLAGS


DMUS_CLOCKTYPE

DMUS_CLOCKTYPE 열거형의 멤버는,DMUS_CLOCKINFO 구조체의 ctType 멤버내에서 사용된다.

typedef enum {
    DMUS_CLOCK_SYSTEM = 0,
    DMUS_CLOCK_WAVE   = 1
} DMUS_CLOCKTYPE;
DMUS_CLOCK_SYSTEM
클럭은 시스템 클록이다.
DMUS_CLOCK_WAVE
클럭은 웨이브 재생 디바이스상에 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h로 선언.


DMUS_COMMANDT_TYPES

DMUS_COMMANDT_TYPES 열거형의 멤버는,IDirectMusicComposer::AutoTransition 와 IDirectMusicComposer::ComposeTransition 의 각 메소드의 wCommand 파라미터, 및 DMUS_COMMAND_PARAM 구조체의 bCommand 멤버로서 사용된다.

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
커멘드는 종료부와 도입부이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


DMUS_COMPOSEF_FLAGS

DMUS_COMPOSEF_FLAGS 는,IDirectMusicComposer::ComposeTransition 와 IDirectMusicComposer::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_MODULATE       = 0x1000,
    DMUS_COMPOSEF_LONG           = 0x2000
}  DMUS_COMPOSEF_FLAGS;
DMUS_COMPOSEF_NONE
플래그 없음. 디폴트에서는, 이행부는 소절 경계로부터 시작 한다.
DMUS_COMPOSEF_ALIGN
이행부를, 현재 연주되고 있는 세그먼트(segment)의 박자 기호에 가지런히 한다. 이 플래그는 현재 이행되어 있지 않다.
DMUS_COMPOSEF_OVERLAP
이행부를 pToSeg 에 거듭한다 (오버랩). 이 플래그는 현재 이행되어 있지 않다.
DMUS_COMPOSEF_IMMEDIATE
AutoTransition only. 뮤직 타임 또는 기준 타임의 경계로부터 이행부를 시작 한다.
DMUS_COMPOSEF_GRID
AutoTransition 마셔. 그리드 경계로부터 이행부를 시작 한다.
DMUS_COMPOSEF_BEAT
AutoTransition 마셔. 박의 경계로부터 이행부를 시작 한다.
DMUS_COMPOSEF_MEASURE
AutoTransition only. 소절 경계로부터 이행부를 시작 한다.
DMUS_COMPOSEF_AFTERPREPARETIME
AutoTransition 마셔. 이행부를 삽입 하면나무는, DMUS_SEGF_AFTERPREPARETIME 플래그를 사용한다.
DMUS_COMPOSEF_MODULATE
pToSeg 의 코드를 사용해,pFromSeg 로부터 pToSeg 에 순조롭게 변화하는 이행부를 어레인지 한다.
DMUS_COMPOSEF_LONG
긴 이행부를 어레인지 한다. 이 플래그가 세트되어 있지 않은 경우,ComposeTransition 또는 AutoTransition 의 wCommand 파라미터로 종료부를 지정해, 스타일에 1 소절보다 긴 종료부가 포함되지 않은 한, 이행부의 길이는 최대에서도 1 소절이다. 이 플래그가 세트 되고 있는 경우, 이행부의 길이는 1 소절 증가한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

DMUS_SEGF_FLAGS


DMUS_NOTEF_FLAGS

DMUS_NOTEF_FLAGS 는,DMUS_NOTE_PMSG 구조체의 bFlags 멤버내에서 사용된다.

typedef enum enumDMUS_NOTEF_FLAGS {
    DMUS_NOTEF_NOTEON = 1,
} DMUS_NOTEF_FLAGS;
DMUS_NOTEF_NOTEON
MIDI 노트 온의 경우는 세트 해, MIDI 노트 오프의 경우는 소거한다. IDirectMusicPerformance::SendPMsg 메소드로 최초로 DMUS_NOTE_PMSG 를 지정하는 경우는, 이 플래그를 세트 해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


DMUS_PLAYMODE_FLAGS

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 의 편성. 키의 루트음은 사용되지만, 음표는 스케일내의 음정만을 쫓는다. 코드의 루트음과 음정은 무시된다. 이것은, 키의 루트음을 기준으로 해 연주되는 선율계의 라인에 있어 편리하다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::MIDIToMusic ,IDirectMusicPerformance::MusicToMIDI ,DMUS_NOTE_PMSG ,DMUS_IO_STYLENOTE ,DMUS_IO_STYLEPART ,뮤직값과 MIDI 음표


DMUS_PMSGF_FLAGS

DMUS_PMSGF_FLAGS 열거형의 멤버는,DMUS_PMSG 구조체의 dwFlags 멤버내에서 사용된다.

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    = 16,
    DMUS_PMSGF_TOOL_FLUSH     = 32
} 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
메세지를 플래시 (릴리즈) 해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::SendPMsg ,IDirectMusicTool::GetMsgDeliveryType


DMUS_PMSGT_TYPES

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_USER             = 255
} DMUS_PMSGT_TYPES;
DMUS_PMSGT_MIDI
MIDI 채널 메세지. 「DMUS_MIDI_PMSG 」를 참조할것.
DMUS_PMSGT_NOTE
음악의 음표. 「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_USER
유저 정의 메세지.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


DMUS_SEGF_FLAGS

DMUS_SEGF_FLAGS 열거형의 멤버는, 세그먼트(segment)에 대한 액션의 타이밍 및 그 외의 요소를 제어하기 위해서,IDirectMusicPerformance 의 다양한 메소드에게 건네진다.

typedef enum enumDMUS_SEGF_FLAGS {
    DMUS_SEGF_REFTIME          = 64,
    DMUS_SEGF_SECONDARY        = 128,
    DMUS_SEGF_QUEUE            = 256,
    DMUS_SEGF_CONTROL          = 512
    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_FLAGS;
DMUS_SEGF_REFTIME
타임 파라미터는 기준 타임에 나타내진다.
DMUS_SEGF_SECONDARY
세컨드리 세그먼트(segment).
DMUS_SEGF_QUEUE
프라이머리 세그먼트(segment) 큐의 마지막에 둔다 (프라이머리 세그먼트(segment)만).
DMUS_SEGF_CONTROL
제어 세그먼트(segment) 로서 연주한다 (세컨드리 세그먼트(segment)만). 「주의」를 참조할것.
DMUS_SEGF_AFTERPREPARETIME
준비 시간의 뒤에 연주한다. 「IDirectMusicPerformance::GetPrepareTime 」를 참조할것.
DMUS_SEGF_GRID
그리드 경계에서 연주한다.
DMUS_SEGF_BEAT
박의 경계에서 연주한다.
DMUS_SEGF_MEASURE
소절 경계에서 연주한다.
DMUS_SEGF_DEFAULT
세그먼트(segment)의 디폴트의 경계를 사용한다.
DMUS_SEGF_NOINVALIDATE
프라이머리 세그먼트(segment) 또는 제어 세그먼트(segment)에 대해, 이 플래그를 IDirectMusicPerformance::PlaySegment 에 세트 하면, 새로운 세그먼트(segment)로 무효화가 발생하지 않는다. 이 플래그가 없으면 무효화가 발생해, 연주중의 곡선이나 음표가 중단되어 리셋 된다. 이 플래그는 DMUS_SEGF_AFTERPREPARETIME 와 조합하지 않으면 안 된다. 그렇게 하는 것에 의해, 새로운 세그먼트(segment)내의 음표는, 낡은 세그먼트(segment)가 연주하는 음표에 거듭해 연주하지 않는다.

주의

보통, 프라이머리 세그먼트(segment)는 제어 세그먼트(segment)이다. DMUS_SEGF_CONTROL 플래그를 사용해, 세컨드리 세그먼트(segment)를 제어 세그먼트(segment)로 할 수 있다. 다만, 제어 세그먼트(segment)를 존재할 수 있는 것은 한 번에 1 개(살) 뿐이다 (복수의 제어 세그먼트(segment)를 생성 할 수 있지만, 실제로 어느 제어 세그먼트(segment)가 DirectMusic 에 의해 사용될까는 보증되지 않는다). 트랙이 다른 트랙에 대해서 GetParam 를 호출하면나무는, 제어 세그먼트(segment)에 대해서도 이와 같이 호출한다. 디폴트에서는, 제어 세그먼트(segment)만이 템포 메세지를 송신한다.

DMUS_SEGF_CONTROL 플래그를 세트 하면, DMUS_SEGF_SECONDARY 가 상정된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.

참조

IDirectMusicPerformance::Invalidate ,IDirectMusicPerformance::PlaySegment ,IDirectMusicPerformance::Stop ,IDirectMusicSegment::GetDefaultResolution ,IDirectMusicSegment::SetDefaultResolution ,DMUS_TIME_RESOLVE_FLAGS


DMUS_SHAPET_TYPES

DMUS_SHAPET_TYPES 열거형의 멤버는,IDirectMusicComposer::ComposeSegmentFromShape 과 IDirectMusicComposer::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 소절로부터 완성되는 복수의 락구를 어레인지 해, 정리하는 것에 의해, 그루브 레벨에 바리에이션이 있는 바스코라스에페크트가 만들어진다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


DMUS_TIME_RESOLVE_FLAGS

DMUS_TIME_RESOLVE_FLAGS 열거형의 멤버는,DMUS_PMSG 구조체의 dwFlags 멤버, 및 IDirectMusicPerformance::GetResolvedTime 메소드의 dwTimeResolveFlags 파라미터로 사용된다.

typedef enum enumDMUS_TIME_RESOLVE_FLAGS {
    DMUS_TIME_RESOLVE_AFTERPREPARETIME = 1<<10,
    DMUS_TIME_RESOLVE_GRID             = 1<<11,
    DMUS_TIME_RESOLVE_BEAT             = 1<<12,
    DMUS_TIME_RESOLVE_MEASURE          = 1<<13
} DMUS_TIME_RESOLVE_FLAGS;
DMUS_TIME_RESOLVE_AFTERPREPARETIME
준비 시간의 뒤의 타임에 해결한다.
DMUS_TIME_RESOLVE_GRID
그리드 경계 위에의 타임에 해결한다.
DMUS_TIME_RESOLVE_BEAT
박경계 위에의 타임에 해결한다.
DMUS_TIME_RESOLVE_MEASURE
소절 경계 위에의 타임에 해결한다.

주의

이러한 플래그는, 대응하는 DMUS_SEGF_FLAGS 와 교환해 사용할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


DMUS_TRACKF_FLAGS

DMUS_TRACKF_FLAGS 의 값은,IDirectMusicTrack::Play 메소드의 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  = 16
} DMUS_TRACKF_FLAGS;
DMUS_TRACKF_SEEK
IDirectMusicTrack::Play 는, 시크에 대응해 불려 갔다. mtStart 파라미터가 직전의 호출의 mtEnd 와 같지 않아도 상관없는 것을 의미한다.
DMUS_TRACKF_LOOP
루프에 응답해 Play 가 불려 갔다.
DMUS_TRACKF_START
이것은 IDirectMusicTrack::Play 의 최초의 호출이다. 트랙이 선두로부터 연주되어 있지 않은 경우는, DMUS_TRACKF_SEEK 를 세트 해도 상관없다.
DMUS_TRACKF_FLUSH
플래시 (릴리즈)나 무효화에 응답해 Play 가 불려 갔다. 이것은, 이미 연주된 어떠한 것을 재연 상주하도록(듯이) 트랙에 요구한다. 이 경우, DMUS_TRACKF_SEEK 도 세트 된다.
DMUS_TRACKF_DIRTY
제어 세그먼트(segment) 가 시작 또는 종료했다. mtNext 가 IDirectMusicTrack::GetParam 를 호출할 때까지 보통 호출을 기다리고 있는 트랙은, 데이터가 무효가 될 가능성이 있기 (위해)때문에, 대기하지 않고 , 즉석에서 호출을 실시해야 하는 것이다. 제어 세그먼트(segment)의 설정 방법법에 대해서는, 「DMUS_SEGF_FLAGS 」를 참조할것.

주의

반복 (리피트 )에 응답해 Play 를 호출했을 경우, DMUS_TRACKF_LOOP 과 DMUS_TRACKF_SEEK 가 세트 된다.

무효화를 지원 하려면 , 트랙은 시크를 지원 해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusici.h 로 선언.


반환값

이하에서는, DirectMusic 인터페이스의 메소드가 보통 돌려주는 값을 나타낸다. 각 메소드가 돌려줄 가능성이 있는 에러 코드의 리스트에 대해서는, 개별의 메소드의 설명을 참조할것. 이러한 리스트는 반드시 포괄적인 것이라고는 할 수 없다.

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_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_DOWNLOADID
다운로드 버퍼의 생성 프로세스로, 무효인 다운로드 식별자가 사용되었다.
DMUS_E_INVALID_EVENT
이벤트는, 유효한 MIDI 메세지는 아닌, 또는 동작 스테이터스를 이용하고 있어 버퍼내에 팩 할 수 없다.
DMUS_E_INVALID_TOOL_HDR
IStream 오브젝트의 데이터에는, 무효인 툴 헤더가 포함되어 있기 (위해)때문에, 그래프 오브젝트에 의한 read를 할 수 없다.
DMUS_E_INVALID_TRACK_HDR
IStream 오브젝트의 데이터에는, 무효인 트랙 헤더가 포함되어 있기 (위해)때문에, 세그먼트(segment) 오브젝트에 의한 read를 할 수 없다.
DMUS_E_INVALIDBUFFER
무효인 DirectSound 버퍼가 포트에게 건네졌다.
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_OBJECTDESC 로 클래스 ID 가 공급되지 않았다
DMUS_E_LOADER_NOFILENAME
DMUS_OBJECTDESC 로 파일명이 공급되지 않았다
DMUS_E_LOADER_OBJECTNOTFOUND
오브젝트가 발견되지 않았다.
DMUS_E_NO_MASTER_CLOCK
퍼포먼스내에 master clock가 존재하지 않는다. IDirectMusicPerformance::Init 메소드를 반드시 호출하는 것.
DMUS_E_NOARTICULATION
DLS 콜렉션내의 음색으로부터 아티큘레이션이 발견되지 않는다.
DMUS_E_NOSYNTHSINK
세면대가 신디사이저에 접속되어 있지 않다.
DMUS_E_NOT_DOWNLOADED_TO_PORT
오브젝트가 포트상에 없기 때문에, 언로드할 수 없다.
DMUS_E_NOT_FOUND
요구된 항목은 오브젝트에 포함되지 않았다.
DMUS_E_NOT_INIT
필요한 오브젝트는 초기화되어 있지 않은지, 초기화에 실패했다.
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_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
IStream 오브젝트의 데이터에는 최초의 체크로서의 툴 헤더가 없기 때문에, 그래프 오브젝트에 의한 read를 할 수 없다.
DMUS_E_TRACK_HDR_NOT_FIRST_CK
IStream 오브젝트의 데이터에는 최초의 체크로서의 트랙 헤더가 없기 때문에, 세그먼트(segment) 오브젝트에 의한 read를 할 수 없다.
DMUS_E_TRACK_NOT_FOUND
요구된 타입의 트랙이 없다.
DMUS_E_TYPE_DISABLED
트랙 파라미터는 무효화되고 있기 (위해)때문에 이용할 수 없다.
DMUS_E_TYPE_UNSUPPORTED
파라미터는 이 트랙상에서 지원되어 있지 않다.
DMUS_E_UNKNOWNDOWNLOAD
신디사이저는 이 타입의 다운로드를 지원 하고 있지 않다.
DMUS_E_UNKNOWN_PROPERTY
이 포트에는 프로퍼티 세트나 항목이 이행되어 있지 않다.
DMUS_E_UNSUPPORTED_STREAM
IStream 오브젝트는, 로드안의 오브젝트가 지원 하고 있는 데이터를 포함하지 않았다.
DMUS_E_WAVEFORMATNOTSUPPORTED
무효인 버퍼 포맷이 신디사이저 세면대에게 건네졌다.
DMUS_S_DOWN_OCTAVE
음표가 1 옥타브 또는 복수 옥타브분 내릴 수 있어 MIDI 값의 범위내에 들어가고 있다.
DMUS_S_END
조작에 성공해, 데이터의 마지막에 달했다.
DMUS_S_FREE
할당할 수 있었던 메모리를 릴리즈 해야 한다.
DMUS_S_LAST_TOOL
그래프내에는 더 이상의 툴이 없다.
DMUS_S_NOBUFFERCONTROL
포트로부터의 오디오 출력은, 지정된 DirectSound 버퍼와 같은 디바이스에 전송 되지만, 팬이나 볼륨등의 버퍼 컨트롤은 출력에 영향을 주지 않는다.
DMUS_S_OVER_CHORD
뮤직값이 코드의 최고음보다 높은 위치에 있는 음표를 가지고 있기 (위해)때문에, MIDI 값은 계산되어 있지 않다.
DMUS_S_PARTIALDOWNLOAD
일부의 음색을 포트에 다운로드할 수 없었다.
DMUS_S_PARTIALLOAD
오브젝트는 부분적인 로드 밖에 할 수 없었다. 이것은, 파묻힌 트랙이나 툴등의 일부의 컴퍼넌트가 올바르게 등록되지 않은 경우에 발생하는 일이 있다.
DMUS_S_REQUEUE
메세지를 다음의 툴에 건네주어야 하는 것이다.
DMUS_S_STRING_TRUNCATED
메소드는 성공했지만, 돌려주어진 캐릭터 라인을 잘라 버리지 않으면 안 되었다.
DMUS_S_UP_OCTAVE
음표가 1 옥타브 또는 복수 옥타브 분죠, MIDI 값의 범위내에 들어가고 있다.
E_FAIL
이 메소드는 성공하지 않았다.
E_INVALIDARG
무효인 인수. 구조체의 dwSize 멤버를 초기화하는 것을 잊어 이 멤버를 메소드에 건네주었을 경우에 이 에러가 일어나는 것이 많다.
E_NOAGGREGATION
집합체는 지원 하고 있지 않다. LPUNKNOWN 파라미터를 NULL 로 설정해야 한다.
E_NOINTERFACE
이용 가능한 오브젝트 인터페이스가 없다.
E_NOTIMPL
이 메소드는 이행되어 있지 않다. 동작에 필요한 기능을 드라이버가 지원 하고 있지 않기 위해(때문에), 이 메소드가 돌려주어지는 일이 있다.
E_OUTOFMEMORY
메모리 부족을 위해, 태스크를 완료할 수 없다.
E_POINTER
무효인 포인터 (보통은 NULL)가 파라미터로서 건네받았다.
REGDB_E_CLASSNOTREG
오브젝트 클래스가 등록되지 않았다.
S_FALSE
메소드는 성공했지만, 해야 할것이 아무것도 없었다.
S_OK
동작은 완료해, 성공했다.


DirectMusic Visual Basic 레퍼런스

여기에서는, Microsoft® DirectMusic® for Microsoft® Visual Basic® 의 API 요소에 관한 레퍼런스 정보를 기술한다. 레퍼런스 정보는 이하의 카테고리로 분류된다.

  • 클래스
  • 형
  • 열거형
  • 에러 코드


클래스

여기에서는, 이하의 DirectMusic 클래스의 메소드에 관한 레퍼런스를 제공한다.

  • DirectMusicBand
  • DirectMusicChordMap
  • DirectMusicCollection
  • DirectMusicComposer
  • DirectMusicLoader
  • DirectMusicPerformance
  • DirectMusicSegment
  • DirectMusicSegmentState
  • DirectMusicStyle


DirectMusicBand

DirectMusicBand 클래스의오브젝트는, 밴드를 나타낸다. 밴드를 사용해, 일련의 퍼포먼스 채널의 음색의 선택사항과 믹서 설정을 지정한다.

밴드는 전용의 파일에 직접 보존해도, 스타일에 묻어도 괜찮다. DirectMusicBand 오브젝트는, 다음의 몇개의 메소드를 사용해 취득한다.

  • DirectMusicLoader.LoadBand
  • DirectMusicLoader.LoadBandFromResource
  • DirectMusicStyle.GetDefaultBand
  • DirectMusicStyle.GetBand

DirectMusicBand 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

세그먼트(segment) 생성 | CreateSegment
음색 데이터 | Download
 | Unload


DirectMusicBand.CreateSegment

DirectMusicBand.CreateSegment 메소드는,DirectMusicPerformance.PlaySegment 메소드를 사용해,DirectMusicSegment 오브젝트를 생성 한다. 이 오브젝트를 사용해, 밴드내에서의 볼륨, 팬, 전조, 및 패치 체인지 커멘드를 동적으로 실행할 수 있다.

object. CreateSegment() As DirectMusicSegment

파라미터

object
DirectMusicBand 오브젝트를 나타내는오브젝트식.

반환값

성공하면 DirectMusicSegment 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_FAIL
DMUS_E_OUTOFMEMORY


DirectMusicBand.Download

DirectMusicBandDirectDownload 메소드는, 밴드내의 음색의 DLS 데이터를 퍼포먼스 오브젝트에 다운로드한다. 밴드의 다운로드가 끝나면(자), 그 밴드내의 음색은, 프로그램 체인지 MIDI 메세지에 의해 개별적으로 선택하는지,DirectMusicBand.CreateSegment 메소드를 호출해 생성 한 밴드 세그먼트(segment)를 연주하는 것으로써 한 번에 모든 것을 선택할 수 있다.

object. Download(performance As DirectMusicPerformance)

파라미터

object
DirectMusicBand 오브젝트를 나타내는오브젝트식.
performance
밴드가 연주하는 퍼포먼스. 퍼포먼스는, 채널로부터 DirectMusic 포트에의 맵핑을 관리한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_NOT_INIT
DMUS_E_OUTOFMEMORY

주의

다운로드된 밴드는 신디사이저 리소스를 사용하기 위해(때문에), 불필요하게 되었을 때는,DirectMusicBand.Unload 메소드를 사용해 언로드해야 한다.

현재의 버젼의 DirectMusic 의 경우, 포트가 DLS 를 지원 하고 있지 않아도 성공하는 일이 있다.

DMUS_E_NOT_INIT 가 돌려주어졌을 경우는, 보통, 초기화된 포트에 퍼포먼스가 정상적으로 접속되지 않았던 것을 의미한다. 이것은 완전한 실패이기 (위해)때문에, 다음에 DirectMusicBand.Unload 를 호출할 필요는 없다.

다운로드가 부분적에 성공하는 경우, 에러는 돌려주어지지 않지만, 일부의 음색이 연주되지 않는 경우가 있다. 부분적인 다운로드가 발생하는 일반적인 원인을 이하에 나타낸다.

  • 밴드는, 포트에 할당할 수 있지 않은 채널 그룹의 P 채널상에 음색을 가지고 있다.
  • 밴드는, 음색의 다운로드처가 되는 신디사이저와 호환성이 없는 DLS 포맷의 음색을 가지고 있다.


DirectMusicBand.Unload

DirectMusicBand.Unload 메소드는,DirectMusicBand.Download 에 의해 전에 다운로드된 밴드내의 음색의 DLS 데이터를 언로드한다.

object. Unload(performance As DirectMusicPerformance)

파라미터

object
DirectMusicBand 오브젝트를 나타내는오브젝트식.
performance
음색의 언로드원의 퍼포먼스.

에러 코드

실패하면 에러가 발생해,Err.Number 이 설정된다.


DirectMusicChordMap

DirectMusicChordMap 클래스의 오브젝트는, 코드 맵을 나타낸다. 코드 맵은, 작곡가 (DirectMusicComposer 에 의해 나타내진다)에 대해, 어레인지 하는 세그먼트(segment)의 코드 진행을 생성 하는데 필요한 정보를 제공한다. 코드 맵을 기존의 세그먼트(segment)에 적용해, 코드를 변경할 수도 있다.

이 클래스에는, 퍼블릭 메소드가 없다. 이 클래스의 인스턴스는,DirectMusicPerformance.GetChordmap 메소드를 사용해 취득한다.

참조

DirectMusicComposer.AutoTransition ,DirectMusicComposer.ChangeChordMap ,DirectMusicComposer.ComposeSegmentFromShape ,DirectMusicComposer.ComposeSegmentFromTemplate ,DirectMusicComposer.ComposeTransition ,DirectMusicPerformance.GetChordmap


DirectMusicCollection

DirectMusicCollection 클래스의 오브젝트는, DLS 파일의 인스턴스를 관리한다.

이 클래스에는, 퍼블릭 메소드가 없다. 이 클래스의 인스턴스는,DirectMusicLoader.LoadCollection 또는 DirectMusicLoader.LoadCollectionFromResource 의 각 메소드를 사용해 취득해,DirectMusicSegment.ConnectToCollection 를 호출하는 것에 의해 세그먼트(segment)에 관련짓는다.


DirectMusicComposer

어플리케이션은,DirectMusicComposer 클래스의 메소드를 사용해, 악곡 요소로부터 세그먼트(segment)와 이행부를 어레인지 해, 기존 세그먼트(segment)의 코드 맵을 변경한다.

DirectMusicComposer 오브젝트는,DirectX7.DirectMusicComposerCreate 메소드를 사용해 취득한다.

DirectMusicComposer 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

코드 맵의 변경 | ChangeChordMap
보통의 세그먼트(segment)의 어레인지 | ComposeSegmentFromShape
 | ComposeSegmentFromTemplate
템플릿 세그먼트(segment)의 어레인지 | ComposeTemplateFromShape
이행부 세그먼트(segment)의 어레인지 | AutoTransition
 | ComposeTransition


DirectMusicComposer.AutoTransition

DirectMusicComposer.AutoTransition 메소드는, 퍼포먼스의 프라이머리 세그먼트(segment) (또는 무음) 내부로부터 다른 세그먼트(segment)에의 이행부를 어레인지 해, 연주의 목적으로 그 이행부와 세컨드리 세그먼트(segment)를 삽입한다.

object. AutoTransition( _
    performance As DirectMusicPerformance, _
    toSeg As DirectMusicSegment, _
    lCommand As Long, _
    lFlags As Long, _
    chordmap As DirectMusicChordMap) _
    As DirectMusicSegment

파라미터

object
DirectMusicComposer 오브젝트를 나타내는오브젝트식.
performance
이행에 관계하는 퍼포먼스.
toSeg
이행처 섹션. 이행부는 이 섹션에 원활히 이행 한다. 「주의」를 참조할것.
lCommand
이행부를 생성 할 경우에 사용되는 장식. 「CONST_DMUS_COMMANDT_TYPES 」를 참조할것. 이 값이 DMUS_COMMANDT_ENDANDINTRO 의 경우, 메소드는, 프라이머리 세그먼트(segment)의 종료부와 toSeg 의 도입부를 포함한 세그먼트(segment)를 어레인지 한다.
lFlags
작곡가 옵션. 「CONST_DMUS_COMPOSEF_FLAGS 」를 참조할것.
chordmap
이행부를 어레인지 할 경우에 사용하는 DirectMusicChordmap 오브젝트.

반환값

성공하면, 이행부 세그먼트(segment)의 어레인지에 이용할 수 있는 스타일이 그 밖에 없는 경우에 한정해,DirectMusicSegment 오브젝트를 돌려준다. 「주의」를 참조할것.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

lFlags 가 DMUS_COMPOSEF_MODULATE 를 포함하지 않은 경우,toSeg 의 값은 NULL 이라도 좋다. toSeg 가 NULL 또는 스타일 트랙을 포함하지 않는 세그먼트(segment)의 경우, 도입부의 장식은 무효가 된다. 연주중의 세그먼트(segment)가 없는 경우 또는 세그먼트(segment)가 스타일 트랙을 포함하지 않은 경우는, 필, 브레이크, 엔드, 및 그루브의 장식이 무효가 된다.

연주중의 세그먼트(segment) 또는 toSeg 의 어느쪽이나, NULL 또는 스타일 트랙을 포함하지 않는 세그먼트(segment) (MIDI 파일에 근거하는 세그먼트(segment)등)를 지정할 수 있다. 그 경우, 모든 장식은 무효가 되어, 연주중의 세그먼트(segment)와 toSeg 의 사이에 이행은 행해지지 않는다. 메소드는 NULL 를 돌려주지만, 성공해,toSeg 에 의해 나타내지는 세그먼트(segment)를 삽입한다.

chordmap 의 값은 NULL 이라도 좋다. 값이 NULL 의 경우, 코드 맵 트랙으로부터 코드 맵을 취득하는 시도를 한다. 최초로 toSeg, 다음에 퍼포먼스의 프라이머리 세그먼트(segment)가 시험 받는다. 어느 세그먼트(segment)에도 코드 맵 트랙이 포함되지 않는 경우는, 현재의 타임에 프라이머리 세그먼트(segment)내에서 발생하는 코드가 이행부의 코드로서 사용된다.


DirectMusicComposer.ChangeChordMap

DirectMusicComposer.ChangeChordMap 메소드는, 새로운 코드 맵을 반영해, 기존 세그먼트(segment)의 코드와 스케일 패턴을 변경한다.

object. ChangeChordMap(segment As DirectMusicSegment, _
    trackScale As Boolean, _
    chordmap As DirectMusicChordMap)

파라미터

object
DirectMusicComposer 오브젝트를 나타내는오브젝트식.
segment
변경에 사용하는 코드 맵을 포함한 섹션.
trackScale
TRUE 의 경우, 메소드는, 모든 코드를 새로운 코드 맙스 케일인 루트음에 상대적으로 전조 한다. 루트음을 그대로의 상태로 하지 않는다.
chordmap
세그먼트(segment)의 새로운 코드 맵.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

메소드는 세그먼트(segment)의 연주중에 호출할 수가 있다.


DirectMusicComposer.ComposeSegmentFromShape

DirectMusicComposer.ComposeSegmentFromShape 메소드는, 미리 정의된 셰이프에 근거해, 스타일과 코드 맵으로부터 오리지날의 섹션 세그먼트(segment)를 생성 한다. 이 셰이프는, 섹션 전체로 시간의 경과에 수반해 코드와 장식을 발생시키는 방법을 나타낸다.

object. ComposeSegmentFromShape(style As DirectMusicStyle, _
    numberOfMeasures As Integer, _
    shape As Integer, _
    activity As Integer, _
    bIntro As Boolean, _
    bEnd As Boolean, _
    chordmap As DirectMusicChordMap) As DirectMusicSegment

파라미터

object
DirectMusicComposer 오브젝트를 나타내는오브젝트식.
style
섹션 세그먼트(segment)의 어레인지에 사용하는 스타일.
numberOfMeasures
어레인지 하는 섹션 세그먼트(segment)의 길이. 소절 단위로 지정한다.
shape
어레인지 하는 섹션 세그먼트(segment)의 셰이프. 그루브 레벨의 변경에 근거한다. CONST_DMUS_SHAPET_TYPES 열거형의 몇개의 값을 지정한다.
activity
화음 진행의 레이트. 유효한 값은 0 ~ 3. 값이 낮으면 코드 체인지가 증가한다.
bIntro
섹션 세그먼트(segment)의 도입부를 어레인지 하고 싶은 경우는 TRUE. 그 이외의 경우는 False.
bEnd
섹션 세그먼트(segment)의 종료부를 어레인지 하고 싶은 경우는 TRUE. 그 이외의 경우는 False.
chordmap
섹션 세그먼트(segment)의 생성에 사용하는 DirectMusicChordmap 오브젝트.

반환값

성공하면 DirectMusicSegment 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectMusicComposer.ComposeSegmentFromTemplate ,DirectMusicComposer.ComposeTemplateFromShape


DirectMusicComposer.ComposeSegmentFromTemplate

DirectMusicComposer.ComposeSegmentFromTemplate 메소드는, 스타일, 코드 맵, 및 템플릿으로부터 오리지날의 섹션 세그먼트(segment)를 생성 한다.

object. ComposeSegmentFromTemplate( _
    style As DirectMusicStyle, _
    templateSeg As DirectMusicSegment, _
    activity As Integer, _
    chordmap As DirectMusicChordMap)
    As DirectMusicSegment

파라미터

object
DirectMusicComposer 오브젝트를 나타내는오브젝트식.
style
섹션 세그먼트(segment)의 생성에 사용하는 DirectMusicStyle 오브젝트.
templateSeg
섹션 세그먼트(segment)의 생성에 사용하는 템플릿을 나타내는 DirectMusicSegment 오브젝트.
activity
화음 진행의 레이트. 유효한 값은 0 ~ 3. 값이 낮으면 코드 체인지가 증가한다.
chordmap
섹션 세그먼트(segment)의 생성에 사용하는 코드 맵을 나타내는 DirectMusicChordmap 오브젝트.

반환값

성공하면 DirectMusicSegment 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 값이 설정된다.

DMUS_E_INVALIDARG

주의

style 가 NULL 가 아닌 경우, 이 스타일은 세그먼트(segment)의 어레인지에 사용된다. NULL 의 경우,templateSeg 로 지정된 템플릿으로부터 꺼낸 스타일을 세그먼트(segment)의 어레인지에 사용한다. 같이chordmap 가 NULL 가 아닌 경우, 이 코드 맵은 세그먼트(segment)의 어레인지에 사용된다. NULL 의 경우, 템플릿으로부터 꺼낸 코드 맵을 세그먼트(segment)의 어레인지에 사용한다.

style 가 NULL 로 템플릿내에 스타일 트랙이 존재하지 않는 경우나,chordmap 가 NULL 로 코드 맵 트랙이 존재하지 않는 경우, 이 메소드는 DMUS_E_INVALIDARG 를 돌려준다.

섹션 세그먼트(segment)의 길이는, 건네받은 템플릿 섹션의 길이와 동일해진다.

참조

DirectMusicComposer.ComposeSegmentFromShape ,DirectMusicComposer.ComposeTemplateFromShape


DirectMusicComposer.ComposeTemplateFromShape

DirectMusicComposer.ComposeTemplateFromShape 메소드는, 미리 정의된 셰이프에 근거해 새로운 템플릿 세그먼트(segment)를 생성 한다.

object. ComposeTemplateFromShape(numMeasures As Integer, _
    shape As Integer, _
    bIntro As Boolean, _
    bEnd As Boolean, _
    endLength As Integer) As DirectMusicSegment

파라미터

object
DirectMusicComposer 오브젝트를 나타내는오브젝트식.
numMeasures
어레인지 하는 섹션 세그먼트(segment)의 길이. 소절 단위로 지정한다. 0 보다 큰 값이 아니면 안된다.
shape
어레인지 하는 템플릿 세그먼트(segment)의 셰이프. 그루브 레벨에 근거한다. CONST_DMUS_SHAPET_TYPES 열거형의 어느쪽이든을 지정한다.
bIntro
템플릿 세그먼트(segment)의 도입부를 어레인지 하고 싶은 경우는 True. 그 이외의 경우는 False.
bEnd
템플릿 세그먼트(segment)의 종료부를 어레인지 하고 싶은 경우는 True. 그 이외의 경우는 False.
endLength
종료부를 생성 하고 싶은 경우는, 종료부의 길이. 소절 단위로 지정한다. bEnd 가 True 의 경우, 이 값은 0 보다 크고, 이용할 수 있는 소절수이하가 아니면 안된다 (즉, 도입부에서 사용되지 않는다). 「주의」도 참조할것.

반환값

성공하면 DirectMusicSegment 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY

주의

endLength 의 값은, 임의의 스타일내에서 이용할 수 있는 최장의 종료부의 길이를 넘어서는 안 된다. 이 경우의 스타일이란,DirectMusicComposer.ComposeSegmentFromTemplate 메소드를 사용해 이 템플릿에 관련지을 수 있을 가능성이 있는 것을 가리킨다. 종료부의 연주는, 세그먼트(segment)가 끝나기 전의 endLength 의 소절로부터 시작 된다. 종료부가 endLength 의 소절의 길이보다 짧은 경우, 음악은 기본 그루브 레벨에 돌아온다.

참조

DirectMusicComposer.ComposeSegmentFromShape ,DirectMusicComposer.ComposeSegmentFromTemplate


DirectMusicComposer.ComposeTransition

DirectMusicComposer.ComposeTransition 메소드는, 어느 섹션 세그먼트(segment)로부터 다른 섹션 세그먼트(segment)에의 이행부를 어레인지 한다.

object. ComposeTransition(fromSeg As DirectMusicSegment, _
    toSeg As DirectMusicSegment, _
    mtTime As Long, _
    lCommand As Long, _
    lFlags As Long, _
    chordmap As DirectMusicChordMap) _
    As DirectMusicSegment

파라미터

object
DirectMusicComposer 오브젝트를 나타내는오브젝트식.
fromSeg
이행부의 생성에 사용하는 섹션 세그먼트(segment)를 나타내는 DirectMusicSegment 오브젝트.
toSeg
이행처 섹션. 이행부는 이 섹션에 원활히 이행 한다. lFlags 가 DMUS_COMPOSEF_MODULATE 를 포함하지 않은 경우, NULL 이라도 좋다.
mtTime
fromSeg 의 섹션내에서 이행부의 어레인지를 시작 하는 타임.
lCommand
이행부를 생성 할 경우에 사용되는 장식. 「CONST_DMUS_COMMANDT_TYPES 」를 참조할것. 이 값이 DMUS_COMMANDT_ENDANDINTRO 의 경우, 메소드는,fromSeg 의 종료부와 toSeg 의 도입부를 포함한 세그먼트(segment)를 어레인지 한다.
lFlags
작곡가 옵션. 이 파라미터는,CONST_DMUS_COMPOSEF_FLAGS 열거형의 1 개 또는 복수의 값을 보관 유지하고 있어도 괜찮다.
chordmap
이행부의 어레인지에 사용하는 코드 맵을 나타내는 DirectMusicChordmap 오브젝트. 「주의」를 참조할것.

반환값

성공하면 DirectMusicSegment 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY

주의

chordmap 의 값은 NULL 이라도 좋다. 값이 NULL 의 경우, 코드 맵 트랙으로부터 코드 맵을 취득하는 시도를 한다. 최초로 toSeg, 다음에 fromSeg 가 시험 받는다. 어느 세그먼트(segment)에도 코드 맵 트랙이 포함되지 않는 경우는,mtTime 에 fromSeg 내에서 발생하는 코드가 이행부의 코드로서 사용된다.

작곡가는, 최초로 fromSeg 내, 다음에 toSeg 내에서 템포를 찾는다. 어느 세그먼트(segment)에도 템포 트랙이 없는 경우, 이행부 세그먼트(segment)의 템포는 스타일로부터 취득된다.

참조

DirectMusicComposer.AutoTransition


DirectMusicLoader

DirectMusicLoader 오브젝트는, 뮤직 데이터와 음색 데이터를 나타내는 오브젝트의 검색과 로드에 사용된다.

이 오브젝트는,DirectX7.DirectMusicLoaderCreate 메소드를 사용해 취득한다.

다른 오브젝트에 의해 참조되는 오브젝트는, 자동적으로 로드 된다. 예를 들어, 스타일에는, 그 외의 파일내의 밴드와 콜렉션에의 참조가 포함되는 경우가 있어, 이러한 참조가 로드 되는 것은,DirectMusicLoader.LoadStyle 메소드를 호출했을 때이다.

DirectMusicLoader 의 메소드는, 이하의 그룹에 정리할 수가 있다.

로드 | LoadBand
 | LoadBandFromResource
 | LoadChordMap
 | LoadChordMapFromResource
 | LoadCollection
 | LoadCollectionFromResource
 | LoadSegment
 | LoadSegmentFromResource
 | LoadStyle
 | LoadStyleFromResource
검색 | SetSearchDirectory


DirectMusicLoader.LoadBand

DirectMusicLoader.LoadBand 메소드는, 파일로부터 밴드를 로드한다.

object. LoadBand(filename As String) As DirectMusicBand

파라미터

object
DirectMusicLoader 오브젝트를 나타내는오브젝트식.
filename
밴드를 포함한 파일의 이름. 현재 디렉토리내 또는 DirectMusicLoader.SetSearchDirectory 에 의해 설정되는 디렉토리내에 파일이 없는 경우, 풀 패스를 지정해야 한다.

반환값

성공하면 DirectMusicBand 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_INVALID_BAND
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED

참조

DirectMusicLoader.LoadBandFromResource


DirectMusicLoader.LoadBandFromResource

DirectMusicLoader.LoadBandFromResource 메소드는, 리소스로부터 밴드를 로드한다.

object. LoadBandFromResource(moduleName As String, _
    resourceName As String) As DirectMusicBand

파라미터

object
DirectMusicLoader 오브젝트를 나타내는오브젝트식.
moduleName
리소스를 포함한 모듈의 이름.
resourceName
밴드를 포함한 리소스의 식별자. 리소스의 타입은 "DMBAND" 가 아니면 안된다.

반환값

성공하면 DirectMusicBand 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_INVALID_BAND
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED

참조

DirectMusicLoader.LoadBand


DirectMusicLoader.LoadChordMap

DirectMusicLoader.LoadChordMap 메소드는, 파일로부터 코드 맵을 로드한다.

object. LoadChordMap(filename As String) _
    As DirectMusicChordMap

파라미터

object
DirectMusicLoader 오브젝트를 나타내는오브젝트식.
filename
코드 맵을 포함한 파일의 이름. 현재 디렉토리내 또는 DirectMusicLoader.SetSearchDirectory 에 의해 설정되는 디렉토리내에 파일이 없는 경우, 풀 패스를 지정해야 한다.

반환값

성공하면 DirectMusicChordMap 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED

참조

DirectMusicLoader.LoadChordMapFromResource


DirectMusicLoader.LoadChordMapFromResource

DirectMusicLoader.LoadChordMapFromResource 메소드는, 리소스로부터 코드 맵을 로드한다.

object. LoadChordMapFromResource( _
    moduleName As String, _
    resourceName As String) As DirectMusicChordMap

파라미터

object
DirectMusicLoader 오브젝트를 나타내는오브젝트식.
moduleName
리소스를 포함한 모듈의 이름.
resourceName
코드 맵을 포함한 리소스의 식별자. 리소스의 타입은 "DMCHORD" 가 아니면 안된다.

반환값

성공하면 DirectMusicChordMap 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED

참조

DirectMusicLoader.LoadChordMap


DirectMusicLoader.LoadCollection

DirectMusicLoader.LoadCollection 메소드는, 파일로부터 DLS 콜렉션을 로드한다.

object. LoadCollection(filename As String) _
    As DirectMusicCollection

파라미터

object
DirectMusicLoader 오브젝트를 나타내는오브젝트식.
filename
DLS 콜렉션을 포함한 파일의 이름. 현재 디렉토리내 또는 DirectMusicLoader.SetSearchDirectory 에 의해 설정되는 디렉토리내에 파일이 없는 경우, 풀 패스를 지정해야 한다.

반환값

성공하면 DirectMusicCollection 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED
DMUS_E_NOTADLSCOL

참조

DirectMusicLoader.LoadCollectionFromResource


DirectMusicLoader.LoadCollectionFromResource

DirectMusicLoader.LoadCollectionFromResource 메소드는, 리소스로부터 DLS 콜렉션을 로드한다.

object. LoadCollectionFromResource( _
    moduleName As String, _
    resourceName As String) As DirectMusicCollection

파라미터

object
DirectMusicLoader 오브젝트를 나타내는오브젝트식.
moduleName
리소스를 포함한 모듈의 이름.
resourceName
콜렉션을 포함한 리소스의 식별자. 리소스의 타입은 "DMCOLL" 가 아니면 안된다.

반환값

성공하면 DirectMusicCollection 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED
DMUS_E_NOTADLSCOL

참조

DirectMusicLoader.LoadCollection


DirectMusicLoader.LoadSegment

DirectMusicLoader.LoadSegment 메소드는, 파일로부터 세그먼트(segment)를 로드한다.

object. LoadSegment(filename As String) As DirectMusicSegment

파라미터

object
DirectMusicLoader 오브젝트를 나타내는오브젝트식.
filename
세그먼트(segment)를 포함한 파일의 이름. 현재 디렉토리내 또는 DirectMusicLoader.SetSearchDirectory 에 의해 설정되는 디렉토리내에 파일이 없는 경우, 풀 패스를 지정해야 한다.

반환값

성공하면 DirectMusicSegment 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED

참조

DirectMusicLoader.LoadSegmentFromResource


DirectMusicLoader.LoadSegmentFromResource

DirectMusicLoader.LoadSegmentFromResource 메소드는, 리소스로부터 세그먼트(segment)를 로드한다.

object. LoadSegmentFromResource( _
    moduleName As String, _
    resourceName As String) As DirectMusicSegment

파라미터

object
DirectMusicLoader 오브젝트를 나타내는오브젝트식.
moduleName
리소스를 포함한 모듈의 이름. 리소스의 타입은 "DMSEG" 가 아니면 안된다.
resourceName
세그먼트(segment)를 포함한 리소스의 식별자.

반환값

성공하면 DirectMusicSegment 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED
DMUS_E_UNSUPPORTED_STREAM

참조

DirectMusicLoader.LoadSegment


DirectMusicLoader.LoadStyle

DirectMusicLoader.LoadStyle 메소드는, 파일로부터 스타일 오브젝트를 로드한다.

object. LoadStyle(filename As String) As DirectMusicStyle

파라미터

object
DirectMusicLoader 오브젝트를 나타내는오브젝트식.
filename
스타일 오브젝트를 포함한 파일의 이름. 현재 디렉토리내 또는 DirectMusicLoader.SetSearchDirectory 에 의해 설정되는 디렉토리내에 파일이 없는 경우, 풀 패스를 지정해야 한다.

반환값

성공하면 DirectMusicStyle 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED

참조

DirectMusicLoader.LoadStyleFromResource


DirectMusicLoader.LoadStyleFromResource

DirectMusicLoader.LoadStyleFromResource 메소드는, 리소스로부터 스타일 오브젝트를 로드한다.

object. LoadStyleFromResource( _
    moduleName As String, _
    resourceName As String) As DirectMusicStyle

파라미터

object
DirectMusicLoader 오브젝트를 나타내는오브젝트식.
moduleName
리소스를 포함한 모듈의 이름.
resourceName
스타일 오브젝트를 포함한 리소스의 식별자. 리소스의 타입은 "DMSTYLE" 가 아니면 안된다.

반환값

성공하면 DirectMusicStyle 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED

참조

DirectMusicLoader.LoadStyle


DirectMusicLoader.SetSearchDirectory

DirectMusicLoader.SetSearchDirectory 메소드는, 풀 패스가 지정되지 않았던 경우에 DirectMusicLoader.LoadBand ,DirectMusicLoader.LoadChordmap ,DirectMusicLoader.LoadCollection ,DirectMusicLoader.LoadSegment , 및 DirectMusicLoader.LoadStyle 의 각 메소드에 의해 검색되는 디렉토리를 설정한다.

object. SetSearchDirectory(dir As String)

파라미터

object
DirectMusicLoader 오브젝트를 나타내는오브젝트식.
dir
검색되는 디렉토리.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_BADPATH

주의

검색 패스를 설정한 후, 로더는 파일명을 사용해 오브젝트를 로드할 때, 풀 패스명을 필요로 하지 않는다. 이 결과, 다른 오브젝트를 참조하는 오브젝트는, 풀 패스를 파악하고 있지 않아도 파일명만으로 그것들을 검색할 수 있다.


DirectMusicPerformance

DirectMusicPerformance 클래스의 오브젝트는, 음악 재생의 종합적인 매니저이다. 이 오브젝트는, 퍼포먼스 채널의 포트에의 맵핑, 세그먼트(segment)의 연주, 메세지의 송신, 이벤트 통지의 송수신, 및 뮤직 파라미터의 설정과 취득을 실시한다. 또, 타이밍에 관한 정보의 취득, 및 시스템간에 타임과 뮤직값을 변환하기 위한 메소드도 갖추고 있다.

어플리케이션이 2 개 이상의 완전한 음악 세트를 동시에 연주하고 싶은 경우, 복수의 퍼포먼스 오브젝트를 생성 하는 것으로써, 그러한 연주를 실시할 수 있다. 개별의 퍼포먼스는 독립한 템포 맵에 따르기 (위해)때문에, 완전하게 비동기에게 연주되지만, 한편으로 1 개의 퍼포먼스내의 모든 세그먼트(segment)는 고정적인 스텝에서 연주된다.

DirectMusicPerformance 오브젝트는,DirectX7.DirectMusicPerformanceCreate 메소드를 사용해 취득한다.

DirectMusicPerformance 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

메세지 | SendCurvePMSG
 | SendMIDIPMSG
 | SendNotePMSG
 | SendPatchPMSG
 | SendTempoPMSG
 | SendTimeSigPMSG
 | SendTransposePMSG
통지 | AddNotificationType
 | GetNotificationPMSG
 | RemoveNotificationType
 | SetNotificationHandle
파라미터 | GetChordmap
 | GetCommand
 | GetGrooveLevel
 | GetMasterAutoDownload
 | GetMasterGrooveLevel
 | GetMasterTempo
 | GetMasterVolume
 | GetStyle
 | GetTempo
 | GetTimeSig
 | Reset
 | SetMasterAutoDownload
 | SetMasterGrooveLevel
 | SetMasterTempo
 | SetMasterVolume
포트 | GetPortCaps
 | GetPortCount
 | GetPortName
 | SetPort
세그먼트(segment) | GetSegmentState
 | IsPlaying
 | PlaySegment
 | Stop
타이밍 | AdjustTime
 | ClockToMusicTime
 | GetBumperLength
 | GetClockTime
 | GetLatencyTime
 | GetMusicTime
 | GetPrepareTime
 | GetQueueTime
 | GetResolvedTime
 | MusicToClockTime
 | SetBumperLength
 | SetPrepareTime
그 외 | CloseDown
 | Init
 | Invalidate


DirectMusicPerformance.AddNotificationType

DirectMusicPerformance.AddNotificationType 메소드는, 요구된 타입의 이벤트가 발생할 때마다, 퍼포먼스에 통지 메세지를 생성시킨다.

object. AddNotificationType( _
    type As CONST_DMUS_NOTIFICATION_TYPE)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
type
통지 메세지가 송신되는 이벤트의 타입. 지정할 수 있는 값에 대해서는, 「CONST_DMUS_NOTIFICATION_TYPE 」를 참조할것.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY

참조

DirectMusicPerformance.RemoveNotificationType


DirectMusicPerformance.AdjustTime

DirectMusicPerformance.AdjustTime 메소드는, 퍼포먼스의 내부 시간을 전방 또는 후방에 조정한다. 이 메소드는 대부분의 경우, 다른 소스와의 동기화를 실시할 때에 차이를 보정하기 위해서 사용된다.

object. AdjustTime(rtAmount As Long)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
rtAmount
덧셈 또는 뺄셈 되는 시간. 클럭 타임 단위로 나타낸다. －1,000 ~로부터 1,000 (－1 초~ +1 초)의 수치를 지정한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DMUS_E_INVALIDARG 가 설정된다.

주의

조정된 시간은, DirectMusic 에 의해 내부적으로 사용된다. DirectMusicPerformance.GetClockTime 메소드가 꺼내는 타임에는 반영되지 않는다.


DirectMusicPerformance.ClockToMusicTime

DirectMusicPerformance.ClockToMusicTime 메소드는, 클럭 타임을 뮤직 타임으로 변환한다. 클럭 타임은 절대 타임이다. 뮤직 타임은, 퍼포먼스의 템포에 근거하는 상대 타임이다.

object. ClockToMusicTime(ctTime As Long) As Long

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
ctTime
변환되는 타임. 클럭 타임 단위로 나타낸다.

반환값

성공하면, 변환된 뮤직 타임을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DMUS_E_NO_MASTER_CLOCK 가 설정된다.

주의

퍼포먼스에 대해 마스터 템포가 설정되어 있는 경우는, 뮤직 타임으로 변환할 때 고려된다.

뮤직 타임은 클럭 타임만큼 정확하지 않기 때문에, 잘라서 버림을 한다.

참조

DirectMusicPerformance.MusicToClockTime ,클럭 타임과 뮤직 타임


DirectMusicPerformance.CloseDown

DirectMusicPerformance.CloseDown 메소드는, 퍼포먼스를 종료한다. 퍼포먼스 오브젝트를 생성 해, 그에 대한 DirectMusicPerformance.Init 를 호출한 어플리케이션은, 퍼포먼스 오브젝트를 릴리즈 하기 전에,CloseDown 를 호출하지 않으면 안 된다.

object. CloseDown()

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

CloseDown 의 호출을 잊으면(자), 메모리 누수나 어플리케이션 장해가 발생하는 일이 있다.

CloseDown 는, 아직 언로드되어 있지 않은 임의의 다운로드 끝난 음색도 릴리즈 한다.


DirectMusicPerformance.GetBumperLength

DirectMusicPerformance.GetBumperLength 메소드는, 메세지가 포트 버퍼에 놓여지고 나서, 포트에 의한 처리가 시작 될 때까지의 시간이 걸리기 시작한다.

object. GetBumperLength() As Long

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 범퍼의 길이를 밀리 세컨드 단위로 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

디폴트의 값은 50 밀리 세컨드 (ms)이다.

참조

DirectMusicPerformance.SetBumperLength


DirectMusicPerformance.GetChordmap

DirectMusicPerformance.GetChordmap 메소드는, 퍼포먼스의제어 세그먼트(segment)로부터 코드 맵을 꺼낸다.

object. GetChordMap(mtTime As Long, _
    mtUntil As Long) As DirectMusicChordMap

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
mtTime
코드 맵이 꺼내지는 타임. 뮤직 타임에 지정한다.
mtUntil
코드 맵이 유효하게 되는 뮤직 타임 (mtTime 로부터의 상대 타임)을 받는 변수. 이 변수가 값 0 을 돌려주었을 경우, 코드 맵이 항상 유효하게 되어 있는지, 코드 맵이 무효가 되는 타임이 불명한 것을 의미한다. 「주의」를 참조할것.

반환값

성공하면 DirectMusicChordmap 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_NO_MASTER_CLOCK
DMUS_E_GET_UNSUPPORTED
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND

주의

보통, 프라이머리 세그먼트(segment)는 제어 세그먼트(segment)이다. 다만, 세컨드리 세그먼트(segment)를 연주 하면나무는, 이것을 제어 세그먼트(segment)로서 지정할 수 있다. 다른 제어 세그먼트(segment)가 삽입되는 경우, 이 메소드에 의해 돌려주어지는 오브젝트는,mtUntil 에 돌려주어지는 타임의 전에 무효가 되는 일이 있다.

참조

CONST_DMUS_SEGF_FLAGS


DirectMusicPerformance.GetClockTime

DirectMusicPerformance.GetClockTime 메소드는, 현재 타임을 꺼낸다.

object. GetClockTime() As Long

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 임의의 시작 타임부터의 상대 타임을 돌려준다. 약 1 밀리 세컨드의 단위로 나타내진다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DMUS_E_NO_MASTER_CLOCK 가 설정된다.

참조

DirectMusicPerformance.GetMusicTime ,클럭 타임과 뮤직 타임


DirectMusicPerformance.GetCommand

DirectMusicPerformance.GetCommand 메소드는, 퍼포먼스의제어 세그먼트(segment)로부터 커멘드를 꺼낸다. 커멘드는, 지정의 타임에 연주되고 있는 패턴의 타입을 나타낸다.

object. GetCommand(mtTime As Long, mtUntil As Long) As Byte

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
mtTime
커멘드가 꺼내지는 타임. 뮤직 타임에 지정한다.
mtUntil
코드 맵이 유효하게 되는 뮤직 타임 (mtTime 로부터의 상대 타임)을 받는 변수. 이 변수가 값 0 을 돌려주었을 경우, 커멘드가 항상 유효하게 되어 있는지, 커멘드가 무효가 되는 타임이 불명한 것을 의미한다. 「주의」를 참조할것.

반환값

성공하면, 커멘드의 타입을 돌려준다. 「CONST_DMUS_COMMANDT_TYPES 」를 참조할것.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_NO_MASTER_CLOCK
DMUS_E_GET_UNSUPPORTED
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND

주의

보통, 프라이머리 세그먼트(segment)는 제어 세그먼트(segment)이다. 다만, 세컨드리 세그먼트(segment)를 연주 하면나무는, 이것을 제어 세그먼트(segment)로서 지정할 수 있다. 다른 제어 세그먼트(segment)가 삽입되는 경우, 이 메소드에 의해 돌려주어지는 오브젝트는,mtUntil 에 돌려주어지는 타임의 전에 무효가 되는 일이 있다.

참조

CONST_DMUS_SEGF_FLAGS


DirectMusicPerformance.GetGrooveLevel

DirectMusicPerformance.GetGrooveLevel 메소드는, 퍼포먼스의제어 세그먼트(segment)로부터 그루브 레벨을 꺼낸다. 그루브 레벨에 의해, 지정의 타임에 연주할 수 있는 패턴이 정해진다.

object. GetGrooveLevel(mtTime As Long, _
    mtUntil As Long) As Byte

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
mtTime
그루브 레벨이 꺼내지는 타임. 뮤직 타임에 지정한다.
mtUntil
그루브 레벨이 유효하게 되는 뮤직 타임 (mtTime 로부터의 상대 타임)을 받는 변수. 이 변수가 값 0 을 돌려주었을 경우, 그루브 레벨이 항상 유효하게 되어 있는지, 그루브 레벨이 무효가 되는 타임이 불명한 것을 의미한다. 「주의」를 참조할것.

반환값

성공하면 1 ~ 100 의 범위에서 값을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_NO_MASTER_CLOCK
DMUS_E_GET_UNSUPPORTED
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND

주의

보통, 프라이머리 세그먼트(segment)는 제어 세그먼트(segment)이다. 다만, 세컨드리 세그먼트(segment)를 연주 하면나무는, 이것을 제어 세그먼트(segment)로서 지정할 수 있다. 다른 제어 세그먼트(segment)가 삽입되는 경우, 이 메소드에 의해 돌려주어지는 오브젝트는,mtUntil 에 돌려주어지는 타임의 전에 무효가 되는 일이 있다.

참조

CONST_DMUS_SEGF_FLAGS


DirectMusicPerformance.GetLatencyTime

DirectMusicPerformance.GetLatencyTime 메소드는, 현재의 지연 시간이 걸리기 시작한다. 지연 시간이란, 메세지가 렌더링을 위해서(때문에) 포트에 송신되는 타임이다.

object. GetLatencyTime() As Long

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 지연 시간을 클럭 타임 단위로 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DMUS_E_NO_MASTER_CLOCK 가 설정된다.


DirectMusicPerformance.GetMasterAutoDownload

DirectMusicPerformance.GetMasterAutoDownload 메소드는, 음색의 자동 다운로드의 현재의 설정을 꺼낸다.

object. GetMasterAutoDownload() As Boolean

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 자동 다운로드가 온의 경우에 True 를 돌려준다. 그 이외의 경우는 False 를 돌려준다. 디폴트값은 False 이다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectMusicPerformance.SetMasterAutoDownload ,DirectMusicSegment.SetAutoDownloadEnable


DirectMusicPerformance.GetMasterGrooveLevel

DirectMusicPerformance.GetMasterGrooveLevel 메소드는, 현재의 마스터 그루브 레벨을 꺼낸다. 이것은, 퍼포먼스내의 모든 그루브 레벨에 추가되는 값이다. 돌려주어지는 값은 1 ~ 100 의 범위에 들어가도록(듯이) 필요에 따라서 조정된다.

object. GetMasterGrooveLevel() As Integer

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 마스터 그루브 레벨을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectMusicPerformance.SetMasterGrooveLevel


DirectMusicPerformance.GetMasterTempo

DirectMusicPerformance.GetMasterTempo 메소드는, 현재의 마스터 템포를 꺼낸다.

object. GetMasterTempo() As Single

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.

반환값

성공하면 0.25 ~ 2.0 의 범위에서 값을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

마스터 템포는, 최종적인 출력 툴에 의해 템포에 적용되는 스케일링 계수이다. 디폴트에서는 1 이 설정된다. 값이 0.5 의 경우, 템포는 반이 되어, 2.0 의 경우는 2 배가 된다.

참조

DirectMusicPerformance.SetMasterTempo


DirectMusicPerformance.GetMasterVolume

DirectMusicPerformance.GetMasterVolume 메소드는, 현재의 마스터 볼륨을 꺼낸다.

object. GetMasterVolume() As Long

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 현재의 마스터 볼륨을 1/100 dB (데시벨) 단위로 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

마스터 볼륨은, 퍼포먼스 전체의 디폴트 볼륨에 적용되는 증폭 계수 또는 감쇠 계수이다. 설정할 수 있는 값의 범위는 포트에 의해 정해진다.

참조

DirectMusicPerformance.SetMasterVolume


DirectMusicPerformance.GetMusicTime

DirectMusicPerformance.GetMusicTime 메소드는, 퍼포먼스의 현재 타임을 뮤직 타임에 돌려준다.

object. GetMusicTime() As Long

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 현재 타임을 뮤직 타임 단위로 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DMUS_E_NO_MASTER_CLOCK 가 설정된다.

참조

DirectMusicPerformance.GetClockTime ,클럭 타임과 뮤직 타임


DirectMusicPerformance.GetNotificationPMsg

DirectMusicPerformance.GetNotificationPMsg 메소드는, 보류되고 있는 통지 메세지를 꺼낸다.

object. GetNotificationPMSG( _
    message As DMUS_NOTIFICATION_PMSG) As Boolean

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
message
메세지를 받아들이는 DMUS_NOTIFICATION_PMSG 형.

반환값

성공하면, 메세지가 받아 들여졌을 경우에 True 를 돌려준다. 보류되고 있는 메세지가 없었던 경우는 False 를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectMusicPerformance.GetPortCaps

DirectMusicPerformance.GetPortCaps 메소드는, 포트의 능력에 관한 정보를 꺼낸다.

object. GetPortCaps(index As Long, caps As DMUS_PORTCAPS)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
index
포트의 인덱스. 1 ~ DirectMusicPerformance.GetPortCount 가 돌려주는 값의 범위에서 지정한다.
caps
포트에 관한 정보를 받는 DMUS_PORTCAPS 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DMUS_E_INVALIDARG 가 설정된다.


DirectMusicPerformance.GetPortCount

DirectMusicPerformance.GetPortCount 메소드는, 시스템상에서 이용할 수 있는 DirectMusic 포트의 수를 돌려준다.

object. GetPortCount() As Long

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 이용할 수 있는 포트의 수를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectMusicPerformance.GetPortName

DirectMusicPerformance.GetPortName 메소드는, 포트의 이름을 돌려준다.

object. GetPortName(index As Long) As String

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
index
포트의 인덱스. 1 ~ DirectMusicPerformance.GetPortCount 가 돌려주는 값의 범위에서 지정한다.

반환값

성공하면, Microsoft Synthesizer 등, 포트의 이름을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectMusicPerformance.GetPrepareTime

DirectMusicPerformance.GetPrepareTime 메소드는, 메세지가 준비되고 나서, 처리되어 스피커로부터 들릴 때까지의 대체로의 시간이 걸리기 시작한다.

object. GetPrepareTime() As Long

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 준비 시간을 밀리 세컨드 단위로 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

디폴트의 값은 1,000 밀리 세컨드 (ms)이다.

참조

DirectMusicPerformance.SetPrepareTime


DirectMusicPerformance.GetQueueTime

DirectMusicPerformance.GetQueueTime 메소드는, 현재의 큐 (또는 플래시) 타임을 꺼낸다. 이 타임보다 빠른 타임의 타임 스탬프를 가지는 메세지는, 이미 포트의 큐에 넣어지고 있어 무효화할 수가 없다.

object. GetQueueTime() As Long

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 큐 타임을 클럭 타임 단위로 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DMUS_E_NO_MASTER_CLOCK 가 설정된다.

주의

큐 타임은,DirectMusicPerformance.GetLatencyTime 와 DirectMusicPerformance.GetBumperLength 의 각 메소드가 돌려주는 값을 덧셈 한 값에 동일하다.

세그먼트(segment)를 즉석에서 정지 하면, 이미 송신되었지만, 포트 버퍼의 큐에 넣어지지 않은 메세지는 모두 플래시 (릴리즈) 된다. 세그먼트(segment)의 연주를 마지막으로 정지한 시점으로부터 재개하고 싶은 경우는, 새로운 시작 포인트를, 세그먼트(segment)를 정지했을 때의 세그먼트(segment)내에 있어서의 큐 타임의 오프셋(offset)로 설정한다.

참조

DirectMusicPerformance.Invalidate


DirectMusicPerformance.GetResolvedTime

DirectMusicPerformance.GetResolvedTime 메소드는, 지정된 타임을, 지정된 경계에 맞추어 조정한다.

object. GetResolvedTime(ctTime As Long, _
    flags As Long) As Long

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
ctTime
해결되는 타임. 클럭 타임 단위로 지정한다. 이 타임이 현재 타임보다 빠른 경우는, 현재 타임이 사용된다.
flags
희망의 분해가능을 기술하는, 이하의 1 개 이상의 CONST_DMUS_SEGF_FLAGS .
DMUS_SEGF_AFTERPREPARETIME
준비 시간의 뒤의 타임에 해결한다.
DMUS_SEGF_GRID
그리드 경계 위에의 타임에 해결한다.
DMUS_SEGF_BEAT
박경계 위에의 타임에 해결한다.
DMUS_SEGF_MEASURE
소절 경계 위에의 타임에 해결한다.

반환값

성공하면, 해결된 타임을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectMusicPerformance.GetSegmentState

DirectMusicPerformance.GetSegmentState 메소드는, 지정의 타임에 연주되고 있는 프라이머리 세그먼트(segment)를 나타내는 DirectMusicSegmentState 오브젝트를 꺼낸다.

object. GetSegmentState(mtTime As Long) _
    As DirectMusicSegmentState

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
mtTime
세그먼트(segment) 상태가 꺼내지는 타임. 뮤직 타임에 지정한다.

반환값

성공하면 DirectMusicSegmentState 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DMUS_E_NOT_FOUND 가 설정된다.

주의

현재 연주되고 있는 세그먼트(segment) 상태를 취득하려면 ,DirectMusicPerformance.GetMusicTime 메소드에 의해 꺼내진 타임을 건네준다. 이 문맥의 현재 연주되고 있다는 것은, 메세지를 연주하기 위해서 현재 불려 가고 있는 것을 의미한다. 지연 시간이 존재하기 위해(때문에), 반드시 현재 연주되고 있는 세그먼트(segment) 상태가 현재 스피커로부터 들리고 있다고는 할 수 없다.

DirectMusicPerformance.PlaySegment 를 호출한 직후에 세그먼트(segment) 상태를 꺼내는 경우는, 지연 시간을 고려해 mtTime 의 값에 150 을 덧셈 하면이야 있고.


DirectMusicPerformance.GetStyle

DirectMusicPerformance.GetStyle 메소드는, 지정의 타임에 있어서의,제어 세그먼트(segment)의 기조가 되는 스타일을 꺼낸다.

object. GetStyle(mtTime As Long, mtUntil As Long) _
    As DirectMusicStyle

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
mtTime
스타일이 꺼내지는 타임. 뮤직 타임에 지정한다.
mtUntil
스타일이 유효하게 되는 뮤직 타임 (mtTime 로부터의 상대 타임)을 받는 변수의 주소. 이 변수가 값 0 을 돌려주었을 경우, 스타일이 항상 유효하게 되어 있는지, 스타일이 무효가 되는 타임이 불명한 것을 의미한다. 「주의」를 참조할것.

반환값

성공하면 DirectMusicStyle 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_NO_MASTER_CLOCK
DMUS_E_GET_UNSUPPORTED
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND

주의

보통, 프라이머리 세그먼트(segment)는 제어 세그먼트(segment)이다. 다만, 세컨드리 세그먼트(segment)를 연주 하면나무는, 이것을 제어 세그먼트(segment)로서 지정할 수 있다. 다른 제어 세그먼트(segment)가 삽입되는 경우, 이 메소드에 의해 돌려주어지는 타임은,mtUntil 에 돌려주어지는 타임의 전에 무효가 되는 일이 있다.


DirectMusicPerformance.GetTempo

DirectMusicPerformance.GetTempo 메소드는, 지정된 타임의 템포를 꺼낸다.

object. GetTempo(mtTime As Long, mtUntil As Long) As Double

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
mtTime
템포가 꺼내지는 타임. 뮤직 타임에 지정한다. 이 타임 또는 이것보다 전에 행해진 템포의 마지막 변경을 사용해, 템포가 정해진다.
mtUntil
템포가 유효하게 되는 뮤직 타임 (mtTime 로부터의 상대 타임)을 받는 변수의 주소. 이 변수가 값 0 을 돌려주었을 경우, 템포가 항상 유효하게 되어 있는지, 템포가 무효가 되는 타임이 불명한 것을 의미한다.

반환값

성공하면, 템포를 1 분 쯤의 박수로 돌려준다. 이 값은 DMUS_TEMPO_MIN ~ DMUS_TEMPO_MAX 의 범위에 있다 ( 「CONST_DMUS 」를 참조).

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_NO_MASTER_CLOCK
DMUS_E_GET_UNSUPPORTED
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND


DirectMusicPerformance.GetTimeSig

DirectMusicPerformance.GetTimeSig 메소드는, 지정된 타임의 박자 기호를 꺼낸다.

object. GetTimeSig(mtTime As Long, _
    mtUntil As Long, _
    timeSig As DMUS_TIMESIGNATURE)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
mtTime
박자 기호가 꺼내지는 타임. 뮤직 타임에 지정한다. 이 타임 또는 이것보다 전에 행해진 박자 기호의 마지막 변경을 사용해, 박자 기호가 정해진다.
mtUntil
박자 기호가 유효하게 되는 뮤직 타임 (mtTime 로부터의 상대 타임)을 받는 변수의 주소. 이 변수가 값 0 을 돌려주었을 경우, 박자 기호가 항상 유효하게 되어 있는지, 박자 기호가 무효가 되는 타임이 불명한 것을 의미한다. 「주의」를 참조할것.
timeSig
박자 기호에 관한 정보를 받는 DMUS_TIMESIGNATURE 형. mtTime 멤버는, 요구된 타임부터, 박자 기호의 마지막 변경을 한 시점까지의 오프셋(offset)를 받는다. 항상 0 미만의 값이 된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_NO_MASTER_CLOCK
DMUS_E_GET_UNSUPPORTED
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND


DirectMusicPerformance.Init

DirectMusicPerformance.Init 메소드는, 퍼포먼스를 초기화해, 그것을 DirectSound 오브젝트에 관련짓는다. 퍼포먼스에 대해서 그 외의 메소드를 호출하기 전에, 이 메소드는 한 번 밖에 호출할 수가 없다.

object. Init(DirectSound As DirectSound, hwnd As Long)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
DirectSound
기존의 DirectSound 오브젝트. DirectMusic 에 의해 오브젝트가 생성 되도록(듯이) 하고 싶은 경우는 NULL 를 지정한다.
hwnd
DirectSound 의 생성에 사용하는 윈도우 핸들. 이 파라미터는 0 이라도 좋다. 그 경우, 전면 윈도우가 사용된다. 「주의」를 참조할것.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_ALREADY_INITED
DMUS_E_OUTOFMEMORY

주의

DirectSound 오브젝트를 존재할 수 있는 것은 1 개의 프로세스에 대해 1 개 뿐이다. 어플리케이션이 웨이브의 연주에 DirectSound 오브젝트를 사용하는 경우, 오브젝트를 이 메소드에 건네주지 않으면 안 된다.

DirectSound 가 NULL 의 경우에만 hwnd 파라미터가 중요하게 된다. DirectSound 오브젝트가 어플리케이션에 의해 개별적으로 생성 되어 이 메소드에게 건네졌을 경우,DirectSound.SetCooperativeLevel 의 호출로, 어플리케이션이 윈도우 핸들을 설정해야 한다.

메소드의 호출시에 어플리케이션 윈도우가 전면에 없는 경우가 있기 (위해)때문에,hwnd 에 0 을 건네주지 않는 것. 보통, 최상정도의 어플리케이션 윈도우 핸들은,DirectMusicPerformance.Init,DirectSound.SetCooperativeLevel, 및 DirectDraw7.SetCooperativeLevel 에 건네주지 않으면 안 된다.

퍼포먼스를 릴리즈 하기 전에,DirectMusicPerformance.CloseDown 메소드를 사용해 퍼포먼스를 종료해야 한다.


DirectMusicPerformance.Invalidate

DirectMusicPerformance.Invalidate 메소드는, 지정된 타임보다 후의 타임 스탬프를 가지는 큐내의 모든 메세지를 플래시 (릴리즈) 해, 지정된 타임부터 전방을 향해, 모든 세그먼트(segment)의 모든 트랙에 데이터를 재발송시킨다.

object. Invalidate(mtTime As Long, flags As Long)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
mtTime
무효로 하는 타임. flags 에 의해 조정된다. 이 값을 0 으로 설정 하면, 즉석에서 무효가 된다.
flags
mtTime 를 조정해 소절, 박, 또는 그리드에 가지런히 한다. 이 값은, 0 또는 다음에 나타내는 CONST_DMUS_SEGF_FLAGS 의 몇개의 멤버라도 좋다.

DMUS_SEGF_MEASURE
DMUS_SEGF_BEAT
DMUS_SEGF_GRID

에러 코드

실패하면 에러가 발생해,Err.Number 에 DMUS_E_NO_MASTER_CLOCK 가 설정된다.

주의

mtTime 가 꽤 전의 타임으로, 그 타임에 무효화를 실시할 수 없는 경우는, 이용 가능한 범위에서 가장 빠른 타임을 사용한다.

참조

DirectMusicPerformance.GetQueueTime


DirectMusicPerformance.IsPlaying

DirectMusicPerformance.IsPlaying 메소드는, 특정의 세그먼트(segment) 또는 세그먼트(segment) 상태가 현재 스피커로부터 연주되고 있는지 어떤지를 판별한다.

object. IsPlaying(segment As DirectMusicSegment, _
    segmentState As DirectMusicSegmentState) As Boolean

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
segment
체크되는 DirectMusicSegment 오브젝트. NULL 의 경우,segmentState 만을 체크한다.
segmentState
체크되는 DirectMusicSegmentState 오브젝트. NULL 의 경우, 세그먼트(segment)만을 체크한다.

반환값

이 메소드가 성공해, 요구한 세그먼트(segment)와 세그먼트(segment) 상태의 어느 쪽인지가 연주되고 있는 경우는 True 를 돌려준다. 어느쪽이나 연주되어 있지 않은 경우, 또는 어느 쪽인지 1 개만을 요구해, 그것이 연주되어 있지 않은 경우는, False 를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 값이 설정된다.

DMUS_E_NO_MASTER_CLOCK


DirectMusicPerformance.MusicToClockTime

DirectMusicPerformance.MusicToClockTime 메소드는, 뮤직 타임 포맷의 타임을 클럭 타임 포맷으로 변환한다.

object. MusicToClockTime(mtTime As Long) As Long

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
mtTime
변환되는 뮤직 타임 포맷의 타임.

반환값

성공하면, 타임을 클럭 타임 단위로 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DMUS_E_NO_MASTER_CLOCK 가 설정된다.

주의

클럭 타임은 뮤직 타임보다 정확하기 때문에, 클럭 타임부터 뮤직 타임으로 변환해, 또 클럭 타임으로 변환한 타임은, 아마 원의 값과는 다르다.

참조

DirectMusicPerformance.ClockToMusicTime ,클럭 타임과 뮤직 타임


DirectMusicPerformance.PlaySegment

DirectMusicPerformance.PlaySegment 메소드는, 세그먼트(segment)의 재생을 시작 한다.

object. PlaySegment(segment As DirectMusicSegment, _
    lFlags As Long, _
    startTime As Long) As DirectMusicSegmentState

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
segment
연주되는 DirectMusicSegment 오브젝트.
lFlags
메소드의 동작을 변경하는 플래그. 「CONST_DMUS_SEGF_FLAGS 」를 참조할것.
startTime
세그먼트(segment)의 연주가 시작 되는 타임. lFlags 로 지정하는 임의의 분해가능 경계에 조정된다. DMUS_SEGF_REFTIME 플래그가 세트되어 있지 않은 한, 타임은 뮤직 타임에 나타내진다. 값이 0 의 경우, 세그먼트(segment)의 연주는 할 수 있는 한 빨리 시작 된다.

반환값

성공하면, 연주중의 세그먼트(segment)를 나타내는 DirectMusicSegmentState 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 값중 한쪽이 설정된다.

DMUS_E_OUTOFMEMORY
DMUS_E_NO_MASTER_CLOCK
DMUS_E_SEGMENT_INIT_FAILED
DMUS_E_TIME_PAST

주의

세그먼트(segment)의 길이는 250 밀리 세컨드 (ms)를 넘고 있어야 하는 것이다.

lFlags 의 경계 분해가능은, 현재 연주되고 있는 프라이머리 세그먼트(segment)에 관련하는 것이다.

프라이머리 세그먼트(segment)의 연주가, 다른 프라이머리 세그먼트(segment)의 연주중에 스케줄 설정되어 있는 경우, 후에 연주되는 세그먼트(segment)에 DMUS_SEGF_QUEUE 플래그를 세트 하지 않는 한, 최초의 세그먼트(segment)는 정지한다. DMUS_SEGF_QUEUE 플래그를 세트 했을 경우, 2 번째의 세그먼트(segment)는, 최초의 세그먼트(segment)의 연주가 끝나는 것과 동시에 연주가 시작 된다.

참조

DirectMusicPerformance.IsPlaying


DirectMusicPerformance.RemoveNotificationType

DirectMusicPerformance.RemoveNotificationType 메소드는, 전에 추가된 통지 타입을 퍼포먼스로부터 삭제해, 그 타입의 통지 메세지가 그 이후 송신되지 않게 한다.

object. RemoveNotificationType( _
    type As CONST_DMUS_NOTIFICATION_TYPE)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
type
통지 메세지가 송신되지 않는 이벤트의 타입. 지정할 수 있는 값에 대해서는, 「CONST_DMUS_NOTIFICATION_TYPE 」를 참조할것.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DMUS_E_INVALIDARG 가 설정된다.

참조

DirectMusicPerformance.AddNotificationType


DirectMusicPerformance.Reset

DirectMusicPerformance.Reset 메소드는, 포트를 리셋 한다.

object. Reset(resetflags As Long)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
resetflags
플래그. 디폴트 (resetflags = 0)의 경우, 메소드는 GMReset 를 실행한다. 이 값이 1 의 경우, 포트를 일단 닫아 재차 여는 것에 의해, 리셋 된다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectMusicPerformance.SendCurvePMSG

DirectMusicPerformance.SendCurvePMSG 메소드는, MIDI 곡선에 관한 정보를 포함한 퍼포먼스 메세지를 송신한다.

object. SendCurvePMSG(lTime As Long, _
    flags As Long, _
    channel As Long, _
    msg As DMUS_CURVE_PMSG)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
lTime
메세지가 연주되는 타임. flags 에 DMUS_PMSGF_REFTIME 를 지정하지 않는 한, 이 타임은 뮤직 타임에 나타내진다.
flags
메세지 처리의 방법과 타임을 변경하는 플래그. 「CONST_DMUS_PMSGF_FLAGS 」를 참조할것.
channel
메세지의 송신지가 되는 퍼포먼스 채널.
msg
곡선에 관한 정보를 포함한 DMUS_CURVE_PMSG 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
DMUS_E_INVALIDARG

주의

메세지의 타임이 0,flags 파라미터가 DMUS_PMSGF_REFTIME 로 설정되어 있는 경우, 이 메세지는 즉석에서 배웅하는 것으로서 큐에 삽입된다.


DirectMusicPerformance.SendMIDIPMSG

DirectMusicPerformance.SendMIDIPMSG 메소드는, 그 외의 메소드에 의해 처리되지 않는 MIDI 채널 메세지에 관한 정보를 포함한 퍼포먼스 메세지를 송신한다.

object. SendMIDIPMSG(lTime As Long, _
    flags As Long, _
    channel As Long, _
    status As Byte, _
    byte1 As Byte, _
    byte2 As Byte)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
lTime
메세지가 연주되는 타임. flags 에 DMUS_PMSGF_REFTIME 를 지정하지 않는 한, 이 타임은 뮤직 타임에 나타내진다.
flags
메세지 처리의 방법과 타임을 변경하는 플래그. 「CONST_DMUS_PMSGF_FLAGS 」를 참조할것.
channel
메세지의 송신지가 되는 퍼포먼스 채널.
status
스탠다드 MIDI 의 스테이터스 바이트. 「주의」를 참조할것.
byte1
선두의 데이터 바이트. 이것을 필요로 하지 않는 MIDI 메세지에서는 무시된다.
byte2
2 번째의 데이터 바이트. 이것을 필요로 하지 않는 MIDI 메세지에서는 무시된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
DMUS_E_INVALIDARG

주의

메세지의 타임이 0,flags 파라미터가 DMUS_PMSGF_REFTIME 로 설정되어 있는 경우, 이 메세지는 즉석에서 배웅하는 것으로서 큐에 삽입된다.

채널은 다른 파라미터내에서 지정되기 (위해)때문에, 스탠다드 MIDI 메세지의 경우와는 달라,status 의 하위 4 비트에는 채널 번호가 포함되지 않는다. 따라서,status 는 노트 오프의 경우에 &H80, 노트 온의 경우에 &H90 등이 된다. 그 외의 스테이터스 바이트에 대해서는, MIDI 규격을 참조할것.


DirectMusicPerformance.SendNotePMSG

DirectMusicPerformance.SendNotePMSG 메소드는, 음표에 관한 정보를 포함한 퍼포먼스 메세지를 송신한다.

object. SendNotePMSG(lTime As Long, _
    flags As Long, _
    channel As Long, _
    msg As DMUS_NOTE_PMSG)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
lTime
메세지가 연주되는 타임. flags 에 DMUS_PMSGF_REFTIME 를 지정하지 않는 한, 이 타임은 뮤직 타임에 나타내진다.
flags
메세지 처리의 방법과 타임을 변경하는 플래그. 「CONST_DMUS_PMSGF_FLAGS 」를 참조할것.
channel
메세지의 송신지가 되는 퍼포먼스 채널.
msg
음표에 관한 정보를 포함한 DMUS_NOTE_PMSG 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
DMUS_E_INVALIDARG

주의

메세지의 타임이 0,flags 파라미터가 DMUS_PMSGF_REFTIME 로 설정되어 있는 경우, 이 메세지는 즉석에서 배웅하는 것으로서 큐에 삽입된다.

참조

뮤직값과 MIDI 음표


DirectMusicPerformance.SendPatchPMSG

DirectMusicPerformance.SendPatchPMSG 메소드는, MIDI 패치의 변경에 관한 정보를 포함한 퍼포먼스 메세지를 송신한다.

object. SendPatchPMSG(lTime As Long, _
    flags As Long, _
    channel As Long, _
    instrument As Byte, _
    byte1 As Byte, _
    byte2 As Byte)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
lTime
메세지가 연주되는 타임. flags 에 DMUS_PMSGF_REFTIME 를 지정하지 않는 한, 이 타임은 뮤직 타임에 나타내진다.
flags
메세지 처리의 방법과 타임을 변경하는 플래그. 「CONST_DMUS_PMSGF_FLAGS 」를 참조할것.
channel
메세지의 송신지가 되는 퍼포먼스 채널.
instrument
채널에 할당하는 패치 번호.
byte1
뱅크 셀렉트의 상위 바이트.
byte2
뱅크 셀렉트의 하위 바이트.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
DMUS_E_INVALIDARG

주의

메세지의 타임이 0,flags 파라미터가 DMUS_PMSGF_REFTIME 로 설정되어 있는 경우, 이 메세지는 즉석에서 배웅하는 것으로서 큐에 삽입된다.


DirectMusicPerformance.SendTempoPMSG

DirectMusicPerformance.SendTempoPMSG 메소드는, 템포의 변경에 관한 정보를 포함한 퍼포먼스 메세지를 송신한다.

object. SendTempoPMSG(lTime As Long, _
    flags As Long, _
    tempo As Double)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
lTime
메세지가 연주되는 타임. flags 에 DMUS_PMSGF_REFTIME 를 지정하지 않는 한, 이 타임은 뮤직 타임에 나타내진다.
flags
메세지 처리의 방법과 타임을 변경하는 플래그. 「CONST_DMUS_PMSGF_FLAGS 」를 참조할것.
tempo
새로운 템포. 1 분 쯤의 박수로 나타낸다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
DMUS_E_INVALIDARG

주의

메세지의 타임이 0,flags 파라미터가 DMUS_PMSGF_REFTIME 로 설정되어 있는 경우, 이 메세지는 즉석에서 배웅하는 것으로서 큐에 삽입된다.


DirectMusicPerformance.SendTimeSigPMSG

DirectMusicPerformance.SendCurvePMSG 메소드는, MIDI 곡선에 관한 정보를 포함한 퍼포먼스 메세지를 송신한다.

object. SendTimeSigPMSG(lTime As Long, _
    flags As Long, _
    timeSig As DMUS_TIMESIGNATURE)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
lTime
메세지가 연주되는 타임. flags 에 DMUS_PMSGF_REFTIME 를 지정하지 않는 한, 이 타임은 뮤직 타임에 나타내진다.
flags
메세지 처리의 방법과 타임을 변경하는 플래그. 「CONST_DMUS_PMSGF_FLAGS 」를 참조할것.
timeSig
박자 기호에 관한 정보를 포함한 DMUS_TIMESIGNATURE 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
DMUS_E_INVALIDARG

주의

메세지의 타임이 0,flags 파라미터가 DMUS_PMSGF_REFTIME 로 설정되어 있는 경우, 이 메세지는 즉석에서 배웅하는 것으로서 큐에 삽입된다.


DirectMusicPerformance.SendTransposePMSG

DirectMusicPerformance.SendTransposePMSG 메소드는, 전조를 시작 시키는 퍼포먼스 메세지를 송신한다.

object. SendTransposePMSG(lTime As Long, _
    flags As Long, _
    channel As Long, _
    transpose As Integer)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
lTime
메세지가 연주되는 타임. flags 에 DMUS_PMSGF_REFTIME 를 지정하지 않는 한, 이 타임은 뮤직 타임에 나타내진다.
flags
메세지 처리의 방법과 타임을 변경하는 플래그. 「CONST_DMUS_PMSGF_FLAGS 」를 참조할것.
channel
전조를 하는 P 채널 .
transpose
음표가 전조 되는 반음의 수. 부의 값이어도 괜찮다. 음표의 전조에 의해, 스탠다드 MIDI 의 범위 0 ~ 127 보다 외측에 이르렀을 경우는, 그 음표는 연주되지 않는다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
DMUS_E_INVALIDARG

주의

메세지의 타임이 0,flags 파라미터가 DMUS_PMSGF_REFTIME 로 설정되어 있는 경우, 이 메세지는 즉석에서 배웅하는 것으로서 큐에 삽입된다.


DirectMusicPerformance.SetBumperLength

DirectMusicPerformance.SetBumperLength 메소드는, 메세지가 포트 버퍼에 놓여지고 나서, 포트에 의한 처리가 시작 될 때까지의 시간을 설정한다.

object. SetBumperLength(lMilliSeconds As Long)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
lMilliSeconds
범퍼의 희망의 길이. 밀리 세컨드 단위로 지정한다. 디폴트값은 50 이다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectMusicPerformance.GetBumperLength ,DirectMusicPerformance.SetPrepareTime


DirectMusicPerformance.SetMasterAutoDownload

DirectMusicPerformance.SetMasterAutoDownload 메소드는, 음색의 자동 다운로드를 온 또는 오프로 전환한다.

object. SetMasterAutoDownload(b As Boolean)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
b
자동 다운로드를 온으로 하는 경우는 True, 오프로 하는 경우는 False 를 지정한다. 디폴트값은 False 이다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectMusicPerformance.GetMasterAutoDownload ,DirectMusicSegment.SetAutoDownloadEnable


DirectMusicPerformance.SetMasterGrooveLevel

DirectMusicPerformance.SetMasterGrooveLevel 메소드는, 퍼포먼스내의 모든 그루브 레벨에 덧셈 되는 값을 설정한다.

object. SetMasterGrooveLevel(level As Integer)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
level
그루브 레벨에 덧셈 되는 값. -99 ~ 99 의 범위에서 지정한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_FAIL
DMUS_E_OUTOFMEMORY

참조

DirectMusicPerformance.GetMasterGrooveLevel

주의

조정된 그루브 레벨은, 항상 1 ~ 100 의 범위에 있다.


DirectMusicPerformance.SetMasterTempo

DirectMusicPerformance.SetMasterTempo 메소드는, 템포에 적용되는 스케일링 계수를 설정한다.

object. SetMasterTempo(tempo As Single)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
tempo
희망의 마스터 템포. 0.25 ~ 2.0 의 범위에서 지정한다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

마스터 템포는 디폴트로 1 이 설정된다. 값이 0.5 의 경우 템포는 반이 되어, 2.0 의 경우는 2 배가 된다.

참조

DirectMusicPerformance.GetMasterTempo


DirectMusicPerformance.SetMasterVolume

DirectMusicPerformance.SetMasterVolume 메소드는, 퍼포먼스의 마스터 볼륨을 조정한다.

object. SetMasterVolume(vol As Long)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
vol
마스터 볼륨의 조정. 1/100 dB (데시벨) 단위로 지정한다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

마스터 볼륨은, 퍼포먼스 전체의 디폴트 볼륨에 적용되는 증폭 계수 또는 감쇠 계수이다. 설정할 수 있는 값의 범위는 포트에 의해 정해진다.

참조

DirectMusicPerformance.GetMasterVolume


DirectMusicPerformance.SetNotificationHandle

DirectMusicPerformance.SetNotificationHandle 메소드는, 통지의 이벤트 핸들을 설정한다. 시그널이 송신되면(자), 어플리케이션은 DirectMusicPerformance.GetNotificationPMsg 메소드를 호출해, 통지 이벤트를 꺼내지 않으면 안 된다.

object. SetNotificationHandle(hnd As Long)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
hnd
이벤트 핸들. 기존의 핸들을 소거하는 경우는 0 을 지정한다.

참조

DirectXEvent


DirectMusicPerformance.SetPort

DirectMusicPerformance.SetPort 메소드는, 퍼포먼스의 액티브 포트를 설정한다. 이 메소드는, 퍼포먼스를 초기화한 후, 및 임의의 음색을 다운로드 또는 임의의 세그먼트(segment)를 연주하기 전에 호출하지 않으면 안 된다.

object. SetPort(index As Long, numGroups As Long)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
index
포트의 인덱스. 1 ~ DirectMusicPerformance.GetPortCount 가 돌려주는 값의 범위에서 지정해야 한다. 디폴트 포트의 경우는 -1 을 지정한다.
numGroups
포트 위에의 채널 그룹의 수. lMaxChannelGroups 멤버로 보고되는 채널 그룹의 수이하가 아니면 안된다. 이 멤버는,DirectMusicPerformance.GetPortCaps 메소드에 의해 돌려주어지는 DMUS_PORTCAPS 형의 멤버이다.

주의

각 채널 그룹은 16 개의 채널로 구성된다. 충분한 수의 채널 그룹을 할당해 연주하는 세그먼트(segment)내에 모든 퍼포먼스 채널이 들어가도록(듯이) 한다. MIDI 파일의 경우는, 1 개의 채널 그룹에서 충분하다. Microsoft Software Synthesizer 은, 최대 1,000 개까지의 채널 그룹을 지원 한다.


DirectMusicPerformance.SetPrepareTime

DirectMusicPerformance.SetPrepareTime 메소드는, 메세지가 준비되고 나서, 처리되어 스피커로부터 들릴 때까지의 대체로의 시간을 설정한다.

object. SetPrepareTime(lMilliSeconds As Long)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
lMilliSeconds
준비 시간의 길이. 밀리 세컨드 단위로 지정한다. 디폴트값은 1,000 이다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectMusicPerformance.GetPrepareTime ,DirectMusicPerformance.SetBumperLength


DirectMusicPerformance.Stop

DirectMusicPerformance.Stop 메소드는, 1 개(살) 또는 복수의 세그먼트(segment)의 재생을 정지한다.

object. Stop(segment As DirectMusicSegment, _
    segmentState As DirectMusicSegmentState, _
    mtTime As Long, _
    lFlags As Long)

파라미터

object
DirectMusicPerformance 오브젝트를 나타내는오브젝트식.
segment
연주를 정지하는 DirectMusicSegment 오브젝트. 이 세그먼트(segment)에 근거하는 모든 세그먼트(segment) 상태는,mtTime 의 시점에서 정지된다. 「주의」를 참조할것.
segmentState
연주를 정지하는 세그먼트(segment)의 인스턴스를 나타내는 DirectMusicSegmentState 오브젝트. 「주의」를 참조할것.
mtTime
세그먼트(segment), 세그먼트(segment) 상태, 또는 그 양쪽 모두를 정지하는 뮤직 타임. 이 타임이 과거의 타임인 경우나, 값으로서 0 을 지정했을 경우는, 요구한 세그먼트(segment)와 세그먼트(segment) 상태의 연주가 즉석에서 정지된다.
lFlags
연주의 정지 타임을 지정하는 플래그. 경계는 현재의 프라이머리 세그먼트(segment)에 관련한다. 다음의 값의 어느쪽이든을 사용하지 않으면 안 된다.
0
즉석에서 정지한다.
DMUS_SEGF_GRID
다음의 그리드 경계 또는 mtTime 의 뒤에 정지한다.
DMUS_SEGF_MEASURE
다음의 소절 경계 또는 mtTime 의 뒤에 정지한다.
DMUS_SEGF_BEAT
다음의 박경계 또는 mtTime 의 뒤에 정지한다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

segment 와 segmentState 의 양쪽 모두가 NULL 인 경우, 모든 음악은 정지해, 현재 큐에 두어져 모든 세그먼트(segment)가 릴리즈 된다. segment 와 segmentState 의 어느 쪽인지가 NULL 가 아닌 경우, 지정된 세그먼트(segment) 상태가 퍼포먼스로부터 삭제된다.

모든 파라미터에 NULL 또는 0 을 설정 하면, 모든 연주가 즉석에서 정지해, 콘트롤러 리셋 메세지 및 노트 오프 메세지가, 맵 된 모든 퍼포먼스 채널에 송신된다.

참조

DirectMusicPerformance.PlaySegment ,CONST_DMUS_SEGF_FLAGS


DirectMusicSegment

DirectMusicSegment 클래스의 오브젝트는, 1 곡의 음악 또는 1 개의 템플릿을 나타낸다.

세그먼트(segment)은 보통,DirectMusicLoader.LoadSegment 와 DirectMusicLoader.LoadSegmentFromResource 의 각 메소드를 호출하는 것에 의해 로드 된다. 또,DirectMusicComposer 오브젝트의 메소드를 사용해 뮤직 요소로부터 어레인지 하거나DirectMusicSegment.Clone 메소드를 사용해 기존의 세그먼트(segment)로부터 생성 하거나 할 수도 있다.

DirectMusicSegment 오브젝트의 메소드는, 이하의 그룹에 정리할 수가 있다.

타이밍과 루프 | GetLength
 | GetLoopPointStart
 | GetLoopPointEnd
 | GetRepeats
 | GetStartPoint
 | SetLength
 | SetLoopPoints
 | SetRepeats
 | SetStartPoint
복제 | Clone
음색 | ConnectToCollection
 | Download
 | Unload
파라미터 | SetAutoDownloadEnable
 | SetStandardMidiFile
 | SetTempoEnable
 | SetTimeSigEnable


DirectMusicSegment.Clone

DirectMusicSegment.Clone 메소드는, 세그먼트(segment)의 모두 또는 파트의 카피를 생성 한다.

object. Clone(mtStart As Long, _
    mtEnd As Long) As DirectMusicSegment

파라미터

object
DirectMusicSegment 오브젝트를 나타내는오브젝트식.
mtStart
복제 시작 파트. 뮤직 타임에 지정한다. 0 미만의 경우나, 세그먼트(segment)의 길이를 넘는 경우는, 0 이 사용된다.
mtEnd
복제 종료 파트. 뮤직 타임에 지정한다. 이 값이 세그먼트(segment)의 최후를 넘는 경우는, 세그먼트(segment)의 끝까지 카피된다. 0 또는 mtStart 미만의 경우도, 끝까지 카피된다.

반환값

성공하면 DirectMusicSegment 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DMUS_E_OUTOFMEMORY 가 설정된다.

주의

DirectMusicSegment.SetStartPoint 와 DirectMusicSegment.SetLoopPoints 의 각 메소드에 의해 설정된 시작 포인트와 루프 포인트는, 클론의 내부에서 디폴트값 (시작 포인트는 0, 루프 포인트는 세그먼트(segment)의 마지막을 의미하는 0)으로 설정된다. 반복 회수도 0 에 리셋 된다.

스타일 베이스의 세그먼트(segment)는,mtStart 가 0 보다 큰 경우, 소절 경계상에 없으면 안 된다.


DirectMusicSegment.ConnectToCollection

DirectMusicSegment.ConnectToCollection 메소드는, 세그먼트(segment)를 DLS 음색 콜렉션에 관련짓는다. 이 콜렉션은,DirectMusicSegment.Download 메소드를 호출했을 때에 다운로드되는 콜렉션이다.

object. ConnectToCollection(c As DirectMusicCollection)

파라미터

object
DirectMusicSegment 오브젝트를 나타내는오브젝트식.
c
세그먼트(segment)의 연주로 사용되는 음색을 나타내는 DirectMusicCollection 오브젝트.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_SET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND

주의

디폴트에서는, Gm.dls 파일내의 General MIDI 콜렉션이 사용된다. 이 메소드를 호출할 필요가 있는 것은, 세그먼트(segment)를 커스텀인 음색을 사용해 연주 하면나무 뿐이다.


DirectMusicSegment.Download

DirectMusicSegment.Download 메소드는, 포트가 음색을 연주할 수 있도록(듯이), 세그먼트(segment)에 관련지을 수 있었던 콜렉션을 다운로드한다.

object. Download(performance As DirectMusicPerformance)

파라미터

object
DirectMusicSegment 오브젝트를 나타내는오브젝트식.
performance
포트에 현재 음색이 다운로드되고 있는 DirectMusicPerformance 오브젝트.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectMusicSegment.ConnectToCollection ,DirectMusicSegment.Unload ,DirectMusicSegment.SetAutoDownloadEnable


DirectMusicSegment.GetLength

DirectMusicSegment.GetLength 메소드는, 세그먼트(segment)의 길이를 꺼낸다.

object. GetLength() As Long

파라미터

object
DirectMusicSegment 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 세그먼트(segment)의 길이를 뮤직 타임에 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

어떠한 이유로써 세그먼트(segment)의 길이가 설정되어 있지 않았던 경우, 이 메소드는 0 을 돌려준다.

참조

DirectMusicSegment.SetLength


DirectMusicSegment.GetLoopPointEnd

DirectMusicSegment.GetLoopPointEnd 메소드는, 반복 섹션이 종료하는 세그먼트(segment)내의 포인트를 꺼낸다.

object. GetLoopPointEnd() As Long

파라미터

object
DirectMusicSegment 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 루프의 종료 포인트를 뮤직 타임에 돌려준다. 이 값이 0 의 경우, 세그먼트(segment) 전체가 루프 한다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

DirectMusicSegment.SetRepeats 메소드를 사용해 반복 회수가 1 이상으로 설정되어 있지 않은 한, 이 섹션은 반복하지 않는다. 디폴트에서는, 세그먼트(segment) 전체가 반복한다.

참조

DirectMusicSegment.GetLoopPointStart ,DirectMusicSegment.SetLoopPoints ,DirectMusicSegment.GetRepeats


DirectMusicSegment.GetLoopPointStart

DirectMusicSegment.GetLoopPointStart 메소드는, 반복 섹션이 시작 하는 세그먼트(segment)내의 포인트를 꺼낸다.

object. GetLoopPointStart() As Long

파라미터

object
DirectMusicSegment 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 루프의 시작 포인트를 뮤직 타임에 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

DirectMusicSegment.SetRepeats 메소드를 사용해 반복 회수가 1 이상으로 설정되어 있지 않은 한, 이 섹션은 반복하지 않는다. 디폴트에서는, 세그먼트(segment) 전체가 반복한다.

참조

DirectMusicSegment.GetLoopPointEnd ,DirectMusicSegment.SetLoopPoints ,DirectMusicSegment.GetRepeats


DirectMusicSegment.GetRepeats

DirectMusicSegment.GetRepeats 메소드는, 세그먼트(segment)의 루프 부분으로 설정되어 있는 반복 회수를 꺼낸다.

object. GetRepeats() As Long

파라미터

object
DirectMusicSegment 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 루프 부분의 반복 회수를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectMusicSegment.SetRepeats ,DirectMusicSegment.SetLoopPoints ,DirectMusicSegment.GetLoopPointStart ,DirectMusicSegment.GetLoopPointEnd ,DirectMusicSegmentState.GetRepeats


DirectMusicSegment.GetStartPoint

DirectMusicSegment.GetStartPoint 메소드는, 세그먼트(segment)가 DirectMusicPerformance.PlaySegment 메소드에 응답해 연주를 시작 하는 포인트를 꺼낸다.

object. GetStartPoint() As Long

파라미터

object
DirectMusicSegment 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 세그먼트(segment)의 시작 포인트를 뮤직 타임에 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectMusicSegment.SetStartPoint


DirectMusicSegment.SetAutoDownloadEnable

DirectMusicSegment.SetAutoDownloadEnable 메소드는, 세그먼트(segment)에 관련지을 수 있었던 콜렉션내의 음색의 자동 다운로드와 언로드를 유효 또는 무효로 한다.

object. SetAutoDownloadEnable(b As Boolean)

파라미터

object
DirectMusicSegment 오브젝트를 나타내는오브젝트식.
b
자동 다운로드를 유효하게 하는 경우는 True, 무효로 하는 경우는 False 를 지정한다.

주의

자동 다운로드는 디폴트로 무효가 되어 있다. 자동 다운로드를 유효하게 하면, 음색은 세그먼트(segment)의 연주시에 자동적으로 다운로드되어 연주를 정지 하면 언로드된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_SET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND

참조

DirectMusicSegment.Download


DirectMusicSegment.SetLength

DirectMusicSegment.SetLength 메소드는, 세그먼트(segment)의 길이를 설정한다.

object. SetLength(mtLength As Long)

파라미터

object
DirectMusicSegment 오브젝트를 나타내는오브젝트식.
mtLength
세그먼트(segment)의 희망의 길이. 뮤직 타임에 지정한다. 0 보다 큰 값이 아니면 안된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DMUS_E_OUT_OF_RANGE 가 설정된다.

주의

대부분의 경우, 어플리케이션은 길이를 설정할 필요는 없다. 세그먼트(segment)의 로드시에 자동적으로 설정되기 때문에 있다. 다만, 이 메소드를 사용해, 세그먼트(segment)의 길이를 짧게 할 수가 있다.

참조

DirectMusicSegment.GetLength


DirectMusicSegment.SetLoopPoints

DirectMusicSegment.SetLoopPoints 메소드는, 세그먼트(segment)내의 루프 부분의 시작 포인트와 종료 포인트를 설정한다. 반복 회수는 DirectMusicSegment.SetRepeats 메소드에 의해 설정된다.

object. SetLoopPoints(mtStart As Long, mtEnd As Long)

파라미터

object
DirectMusicSegment 오브젝트를 나타내는오브젝트식.
mtStart
루프의 시작 포인트. 뮤직 타임에 지정한다.
mtEnd
루프의 종료 포인트. 뮤직 타임에 지정한다. 값 0 은, 세그먼트(segment) 전체를 루프 시키는 것을 의미한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DMUS_E_OUT_OF_RANGE 가 설정된다.

주의

세그먼트(segment)의 연주시에는, 시작 타임부터 mtEnd 까지 연주해,mtStart 에 루프 한다. 다음에, 루프 부분을 DirectMusicSegment.SetRepeats 에 의해 설정되는 회수만 반복해, 끝까지 연주한다.

디폴트값은, 최초부터 끝까지 세그먼트(segment) 전체를 루프 시키도록(듯이) 설정되어 있다.

mtStart 의 값이 세그먼트(segment)의 길이 이상의 경우, 또는 mtEnd 의 값이 세그먼트(segment)의 길이를 넘는 경우, 메소드는 실패한다. mtEnd 가 0 의 경우,mtStart 도 0 이 아니면 안된다.

이 메소드는, 이 세그먼트(segment)로부터 생성 된, 현재 연주중의 세그먼트(segment) 상태에 영향을 미칠 것은 없다.

재이용되는 세그먼트(segment)는, 내장형 캐쉬로부터 로드 될 가능성도 있다. 그 경우, 그 세그먼트(segment)의 루프 포인트는, 마지막에 설정된 값과 같은 값을 가진다. 오브젝트를 릴리즈 또는 리셋 하기 전에는, 루프 포인트를 0 에 리셋 하면이야 있고.

참조

DirectMusicSegment.GetLoopPointStart ,DirectMusicSegment.GetLoopPointEnd ,DirectMusicSegment.SetRepeats


DirectMusicSegment.SetRepeats

DirectMusicSegment.SetRepeats 메소드는, 세그먼트(segment)의 루프 부분의 반복 회수를 설정한다.

object. SetRepeats(lRepeats As Long)

파라미터

object
DirectMusicSegment 오브젝트를 나타내는오브젝트식.
lRepeats
반복 회수.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectMusicSegment.GetRepeats ,DirectMusicSegment.SetLoopPoints


DirectMusicSegment.SetStandardMidiFile

DirectMusicSegment.SetStandardMidiFile 메소드는, 세그먼트(segment)가, DirectMusic 용으로 특별히 오쏘링 된 것은 아니고, 스탠다드 MIDI 파일에 근거하고 있는 것을 DirectMusic 에 통지한다. 이 메소드를 호출하면, 세그먼트(segment)의 연주시에 특정의 이벤트가 적절히 처리된다.

object. SetStandardMidiFile()

파라미터

object
DirectMusicSegment 오브젝트를 나타내는오브젝트식.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

이 메소드는, 음색을 다운로드하기 전에 호출하지 않으면 안 된다.


DirectMusicSegment.SetStartPoint

DirectMusicSegment.SetStartPoint 메소드는, 세그먼트(segment)가 DirectMusicPerformance.PlaySegment 메소드의 호출해에 응답해 연주를 시작 하는 포인트를 설정한다.

object. SetStartPoint(mtStart As Long)

파라미터

object
DirectMusicSegment 오브젝트를 나타내는오브젝트식.
mtStart
세그먼트(segment)의 연주 시작 포인트. 뮤직 타임에 지정한다. 이 값이 0 미만 또는 세그먼트(segment)의 길이보다 큰 경우, 시작 포인트는 0 으로 설정된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DMUS_E_OUT_OF_RANGE 가 설정된다.

주의

디폴트의 시작 포인트는 0 이며, 세그먼트(segment)의 선두로부터 시작 하는 것을 의미한다.

mtStart 의 값이 세그먼트(segment)의 길이 이상의 경우, 이 호출은 실패한다.

이 메소드는, 이 세그먼트(segment)로부터 생성 된, 현재 연주중의 세그먼트(segment) 상태에 영향을 미칠 것은 없다.

재이용되는 세그먼트(segment)는, 내장형 캐쉬로부터 로드 될 가능성도 있다. 그 경우, 그 세그먼트(segment)의 시작 포인트는, 마지막에 설정된 값과 같은 값을 가진다. 오브젝트를 릴리즈 또는 리셋 하기 전에는, 시작 포인트를 0 으로 설정 하면이야 있고.

참조

DirectMusicSegment.GetStartPoint ,DirectMusicSegmentState.GetStartPoint ,DirectMusicSegment.SetLoopPoints


DirectMusicSegment.SetTempoEnable

DirectMusicSegment.SetTempoEnable 메소드는, 세그먼트(segment)의 템포 메세지를 유효 또는 무효로 한다.

object. SetTempoEnable(b As Boolean)

파라미터

object
DirectMusicSegment 오브젝트를 나타내는오브젝트식.
b
템포 메세지를 유효하게 하는 경우는 True, 무효로 하는 경우는 False 를 지정한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_SET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND


DirectMusicSegment.SetTimeSigEnable

DirectMusicSegment.SetTimeSigEnable 메소드는, 세그먼트(segment)의 박자 기호 메세지를 유효 또는 무효로 한다.

object. SetTempoEnable(b As Boolean)

파라미터

object
DirectMusicSegment 오브젝트를 나타내는오브젝트식.
b
박자 기호 메세지를 유효하게 하는 경우는 True, 무효로 하는 경우는 False 를 지정한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DMUS_E_SET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND


DirectMusicSegment.Unload

DirectMusicSegment.Unload 메소드는,DirectMusicSegment.Download 메소드에 의해 포트에 다운로드된 음색을 언로드한다.

object. Unload(performance As DirectMusicPerformance)

파라미터

object
DirectMusicSegment 오브젝트를 나타내는오브젝트식.
performance
포트로부터 현재 음색이 언로드되고 있는 DirectMusicPerformance 오브젝트.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectMusicSegment.SetAutoDownloadEnable


DirectMusicSegmentState

DirectMusicSegmentState 클래스는, 세그먼트(segment)의 인스턴스에 관한 정보를 취득하기 위해서 사용된다. DirectMusicPerformance.PlaySegment 메소드를 호출하면, 세그먼트(segment)의 인스턴스를 나타내는 DirectMusicSegmentState 오브젝트가 생성 되어 어플리케이션은 그 인스턴스에 관한 정보를 취득할 수 있게 된다. 이 오브젝트를 DirectMusicPerformance 의 메소드에 건네주어, 세그먼트(segment)의 인스턴스가 연주중일지 어떨지를 판별하거나 그것을 정지하거나 할 수도 있다.

이 클래스는, 이하의 그룹에 정리할 수가 있다.

정보 | GetRepeats
 | GetSeek
 | GetSegment
 | GetStartPoint
 | GetStartTime

참조

DirectMusicPerformance.GetSegmentState ,DirectMusicPerformance.IsPlaying ,DirectMusicPerformance.Stop


DirectMusicSegmentState.GetRepeats

DirectMusicSegmentState.GetRepeats 메소드는, 세그먼트(segment)의 루프 부분으로 설정되어 있는 반복 회수를 돌려준다.

object. GetRepeats() As Long

파라미터

object
DirectMusicSegmentState 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 반복 회수를 돌려준다. 값 0 은, 그 세그먼트(segment) 전체를 1 회만 연주해, 반복하는 부분이 없는 것을 의미한다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectMusicSegment.SetRepeats


DirectMusicSegmentState.GetSeek

DirectMusicSegmentState.GetSeek 메소드는, 세그먼트(segment) 상태내의 현재의 시크 포인터를 꺼낸다. 시크 포인터는, 메세지가 생성된 세그먼트(segment)내의 마지막 포인트의 직후에 있다.

object. GetSeek() As Long

파라미터

object
DirectMusicSegmentState 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 현재의 시크 포인터를 뮤직 타임에 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

세그먼트(segment)를 정지 하면, 이미 송신되었지만, 포트 버퍼의 큐에 아직 들어가 있지 않은 메세지는, 플래시 (릴리즈) 된다. 따라서, 세그먼트(segment)를 정지해, 마지막 시크 포인터로 재개 하면, 일부의 음표가 없어진다.


DirectMusicSegmentState.GetSegment

DirectMusicSegmentState.GetSegment 메소드는, 이 세그먼트(segment) 상태를 보관 유지하는 세그먼트(segment)를 나타내는 오브젝트를 돌려준다.

object. GetSegment() As DirectMusicSegment

파라미터

object
DirectMusicSegmentState 오브젝트를 나타내는오브젝트식.

반환값

성공하면 DirectMusicSegment 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectMusicSegmentState.GetStartPoint

DirectMusicSegmentState.GetStartPoint 메소드는, 연주의 시작에 사용된, 또는 지금부터 사용되는 세그먼트(segment)의 오프셋(offset)를 돌려준다.

object. GetStartPoint() As Long

파라미터

object
DirectMusicSegmentState 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 이 세그먼트(segment) 상태의 시작 포인트를 뮤직 타임에 돌려준다. 이 세그먼트(segment) 상태를 생성 하고 나서, 세그먼트(segment)의 시작 포인트를 변경했을 경우, 돌려주어지는 값은 DirectMusicSegment.GetStartPoint 가 돌려주는 값과는 다른 경우가 있다. 연주중의 세그먼트(segment)가 다른 인스턴스는, 각각 다른 시작 포인트를 가질 수가 있다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectMusicSegment.SetStartPoint ,DirectMusicSegmentState.GetStartTime


DirectMusicSegmentState.GetStartTime

DirectMusicSegmentState.GetStartTime 메소드는, 세그먼트(segment)가 연주된, 또는 지금부터 연주되는 연주 타임을 취득한다.

object. GetStartTime() As Long

파라미터

object
DirectMusicSegmentState 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 세그먼트(segment)의 이 인스턴스의 시작 타임을 뮤직 타임에 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DMUS_E_BUFFER_EMPTY 가 설정된다.

주의

세그먼트(segment)의 연주가 시작 포인트 이외외의 포인트로부터 시작 되었을 경우, 이 메소드가 돌려주는 값으로부터,DirectMusicSegmentState.GetStartPoint 가 돌려주는 타임을 당기는 것에 의해, 이 세그먼트(segment)의 시작 타임을 꺼낼 수가 있다.

참조

DirectMusicSegment.SetStartPoint ,DirectMusicSegment.GetStartPoint ,DirectMusicSegmentState.GetStartPoint


DirectMusicStyle

DirectMusicStyle 클래스의 오브젝트는, 음악 패턴을 연주할 경우에 필요하게 되는 정보를 퍼포먼스에 제공한다. 스타일에는 보통 밴드와 모티프가 포함되어 코드 맵이 포함되는 경우도 있기 (위해)때문에,DirectMusicStyle 오브젝트는, 이러한 오브젝트에 액세스하기 위한 메소드도 제공한다.

오브젝트는 보통,DirectMusicLoader.LoadStyle 또는 DirectMusicLoader.LoadStyleFromResource 의 각 메소드를 사용해 취득한다. 현재의제어 세그먼트(segment)가 스타일에 근거하고 있는 경우는,DirectMusicPerformance.GetStyle 메소드를 사용하는 것에 의해, 오브젝트를 퍼포먼스로부터 취득할 수도 있다.

DirectMusicStyle 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

밴드 | GetBand
 | GetBandCount
 | GetBandName
 | GetDefaultBand
모티프 | GetMotif
 | GetMotifCount
 | GetMotifName
시간 | GetTempo
 | GetTimeSignature


DirectMusicStyle.GetBand

DirectMusicStyle.GetBand 메소드는, 이름을 사용해 밴드 오브젝트를 취득한다.

object. GetBand(name As String) As DirectMusicBand

파라미터

object
DirectMusicStyle 오브젝트를 나타내는오브젝트식.
name
스타일의 생성자에 의해 밴드에 할당할 수 있었던 이름.

반환값

성공하면 DirectMusicBand 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DMUS_E_FAIL 가 설정된다.

참조

DirectMusicStyle.GetBandName ,DirectMusicStyle.GetDefaultBand


DirectMusicStyle.GetBandCount

DirectMusicStyle.GetBandCount 메소드는, 스타일내에서 이용할 수 있는 밴드의 수를 취득한다.

object. GetBandCount() As Long

파라미터

object
DirectMusicStyle 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 스타일내의 밴드의 수를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectMusicStyle.GetBand ,DirectMusicStyle.GetBandName


DirectMusicStyle.GetBandName

DirectMusicStyle.GetBandName 메소드는, 스타일내의 밴드의 이름을 취득한다.

object. GetBandName(index As Long) As String

파라미터

object
DirectMusicStyle 오브젝트를 나타내는오브젝트식.
index
스타일내의 밴드의 인덱스. 1 ~ DirectMusicStyle.GetBandCount 가 돌려주는 값의 범위에서 지정한다.

반환값

성공하면, 스타일의 생성자에 의해 밴드에 할당할 수 있었던 이름을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectMusicStyle.GetBand


DirectMusicStyle.GetDefaultBand

DirectMusicStyle.GetDefaultBand 메소드는, 스타일의 디폴트 밴드를 취득한다.

object. GetDefaultBand() As DirectMusicBand

파라미터

object
DirectMusicStyle 오브젝트를 나타내는오브젝트식.
name
스타일의 생성자에 의해 밴드에 할당할 수 있었던 이름.

반환값

성공하면 DirectMusicBand 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectMusicStyle.GetBand


DirectMusicStyle.GetMotif

DirectMusicStyle.GetMotif 메소드는, 지정된 모티프를 포함한 세그먼트(segment)를 생성 한다.

object. GetMotif(name As String) As DirectMusicSegment

파라미터

object
DirectMusicStyle 오브젝트를 나타내는오브젝트식.
name
스타일의 생성자에 의해 모티프로 할당할 수 있었던 이름.

반환값

성공하면, 모티프를 나타내는 DirectMusicSegment 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectMusicStyle.GetMotifCount ,DirectMusicStyle.GetMotifName


DirectMusicStyle.GetMotifCount

DirectMusicStyle.GetMotifCount 메소드는, 스타일내에서 이용할 수 있는 모티프의 수를 취득한다.

object. GetMotifCount() As Long

파라미터

object
DirectMusicStyle 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 스타일내의 모티프의 수를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectMusicStyle.GetMotifName

DirectMusicStyle.GetMotifName 메소드는, 스타일내의 모티프의 이름을 취득한다.

object. GetMotifName(index As Long) As String

파라미터

object
DirectMusicStyle 오브젝트를 나타내는오브젝트식.
index
스타일내의 모티프의 인덱스. 1 ~ DirectMusicStyle.GetMotifCount 가 돌려주는 값의 범위에서 지정한다.

반환값

성공하면, 스타일의 생성자에 의해 모티프로 할당할 수 있었던 이름을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectMusicStyle.GetMotif


DirectMusicStyle.GetTempo

DirectMusicStyle.GetTempo 메소드는, 스타일의 추천 템포를 꺼낸다.

object. GetTempo() As Double

파라미터

object
DirectMusicStyle 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 추천 템포를 1 분 쯤의 박수로 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectMusicStyle.GetTimeSignature

DirectMusicStyle.GetTimeSignature 메소드는, 스타일의 박자 기호를 꺼낸다.

object. GetTimeSignature(pTimeSig As DMUS_TIMESIGNATURE)

파라미터

object
DirectMusicStyle 오브젝트를 나타내는오브젝트식.
pTimeSig
박자 기호에 관한 정보를 받는 DMUS_TIMESIGNATURE 형.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


형

여기에서는, DirectMusic for Visual Basic 로 사용되는 이하의 형태에 관한 정보를 제공한다.

  • DMUS_CURVE_PMSG
  • DMUS_NOTE_PMSG
  • DMUS_NOTIFICATION_PMSG
  • DMUS_PORTCAPS
  • DMUS_TIMESIGNATURE


DMUS_CURVE_PMSG

DMUS_CURVE_PMSG 형은, MIDI 곡선 메세지에 관한 정보를 보관 유지한다.

Type DMUS_CURVE_PMSG
    beat As Byte
    ccData As Byte
    curveShape As Byte
    endValue As Integer
    flags As Byte
    grid As Byte
    measure As Integer
    mtDuration As Long
    mtOriginalStart As Long
    mtResetDuration As Long
    offset As Integer
    resetValue As Integer
    startValue As Integer
    type As Byte
End Type

멤버

beat
이 곡선이 발생하는 (소절내의) 박수.
ccData
컨트롤 체인지 타입의 경우는, CC 번호를 지정한다.
curveShape
곡선의 셰이프. 이 파라미터에는,CONST_DMUS_CURVES 열거형의 몇개의 값을 지정할 수 있다.
endValue
곡선의 종료값.
flags
디폴트의 타임에 이르렀을 때, 또는 이행부가 원인으로 무효화가 발생했을 때에 resetValue 를 설정해야 하는 경우는, 이 값을 DMUS_CURVE_RESET 로 설정한다. 이 값을 0 으로 설정했을 경우는, 곡선은 새로운 값에 영속적에 머무른다.
grid
이 곡선이 발생하는 박으로부터의 그리드 오프셋(offset).
measure
곡선이 발생하는 소절.
mtDuration
곡선의 지속 시간.
mtOriginalStart
오리지날의 시작 타임. 뮤직 타임에 지정한다. 메세지를 생성 하면나무는 0 으로 설정해야 한다. 그 이외의 경우는, 곡선의 오리지날의 시작 타임으로 설정해야 한다.
mtResetDuration
곡선이 종료한 후, 리셋값을 설정할 때까지의 시간. 뮤직 타임에 지정한다.
offset
곡선이 발생하는 그리드로부터의 오프셋(offset). 뮤직 타임에 지정한다.
resetValue
곡선의 리셋값. mtResetDuration 의 경과후, 또는 플래시 (릴리즈)나 무효화 시에 설정된다.
startValue
곡선의 시작값.
type
곡선의 타입. 이 파라미터에는,CONST_DMUS_CURVET 열거형의 몇개의 값을 지정할 수 있다.

참조

DirectMusicPerformance.SendCurvePMSG


DMUS_NOTE_PMSG

DMUS_NOTE_PMSG 형은, 음악의 음표 이벤트용의 데이터에 의해 구성되어 있다.

Type DMUS_NOTE_PMSG
    beat as Byte
    durRange As Byte
    flags As Byte
    grid As Byte
    measure As Integer
    midiValue As Byte
    mtDuration As Long
    musicValue As Integer
    offset As Integer
    playModeFlags As Byte
    subChordLevel As Byte
    timeRange As Byte
    velocity As Byte
    velRange As Byte
End Type

멤버

beat
이 음표가 발생하는 (소절내의) 박수.
durRange
랜덤 지속 시간의 범위.
flags
DMUS_NOTEF_NOTEON 로 설정해야 한다. 「주의」를 참조할것.
grid
이 음표가 발생하는 박으로부터의 그리드 오프셋(offset).
measure
음표가 발생하는 소절.
midiValue
musicValue 로부터 변환된 MIDI 음표의 값.
mtDuration
음표의 지속 시간.
musicValue
음표의 기술. 대부분의 연주 모드에서는, 이하에 나타내도록(듯이), 팩 된 4 비트값의 배열이다.

-2 ~ 14 의 범위의 옥타브. 이 음표는, 1 옥타브의 12 배로 상하에 전조 된다.

0 ~ 15 의 범위의 코드 위치. 다만, 3 을 넘어서는 안 된다. 코드내의 최초의 위치는 0 이다.

0 ~ 15 의 범위의 스케일 위치. 보통은 0 ~ 2 의 범위이지만, 1 음표의 코드로 해, 코드의 위에의 모든 것을 스케일 위치로서 해석하는 일도 가능.

-8 ~ 7 의 범위의 변화음. 보통은 -2 ~ 2 의 범위. 이것은, 스케일로부터 음표를 꺼내는 오프셋(offset)를 나타낸다.

고정 연주 모드에서는, 뮤직값은 0 ~ 127 의 범위에 있는 MIDI 음표의 값이다.

offset
음표가 발생하는 그리드로부터의 오프셋(offset). 뮤직 타임에 지정한다.
playModeFlags
뮤직값이 코드와 서브 코드에 어떻게 관련할까를 결정하는 연주 모드. 값의 리스트에 대해서는, 「CONST_DMUS_PLAYMODE_FLAGS 」를 참조할것.
subChordLevel
음표가 사용하는 서브 코드 레벨.
timeRange
랜덤 시간의 범위.
velocity
음표의 velocity.
velRange
velocity를 랜덤화하는 범위.

주의

음표 메세지를 송신하는 어플리케이션은,flags,midiValue,mtDuration, 및 velocity 의 각 멤버인 만큼 값을 제공해야 한다. 그 외의 멤버는 툴인 만큼 따라 이용된다. 툴은 DirectX for Visual Basic 로 지원되어 있지 않다.

어플리케이션은 보통,flags 를 DMUS_NOTEF_NOTEON 로 설정한다. 어플리케이션은 노트 오프 메세지를 송신할 필요는 없다. DirectMusic 출력 툴은,DMUS_NOTE_PMSG 를 받아, DMUS_NOTEF_NOTEON 가 설정되어 있는 것을 인식 하면, 플래그를 소거해, 타임 스탬프에 mtDuration 를 더해 메세지를 요구한다. 그 결과, 적절한 타임에 음표는 종료한다.

다만, 어플리케이션은,flags 가 0 에 세트 된 같은 채널 위에의 같은 음표를 송신하는 것에 의해, 음표를 도중에 정지할 수가 있다.

참조

DirectMusicPerformance.SendNotePMSG ,뮤직값과 MIDI 음표


DMUS_NOTIFICATION_PMSG

DMUS_NOTIFICATION_PMSG 형은, 퍼포먼스에 의해 송신된 통지 메세지에 관한 정보를 보관 유지한다.

Type DMUS_NOTIFICATION_PMSG
    ctTime As Long
    lField1 As Long
    lField2 As Long
    lNotificationOption As Long
    lNotificationType As Long
    mtTime As Long
End Type

멤버

ctTime
메세지의 타임 스탬프. 클럭 타임에 지정한다.
lField1
통지 타입에 고유의 추가 데이터. DMUS_NOTIFY_ON_MEASUREANDBEAT 통지의 경우, 이 멤버는 소절내의 박번호를 돌려준다.
lField2
통지 타입에 고유의 추가 데이터. 장래의 사용 또는 어플리케이션에 의해 정의되는 사용에 대비해 예약되고 있다.
lNotificationOption
CONST_DMUS_NOTIFICATION_SUBTYPE 열거형의 통지 서브 타입의 식별자.

통지 타입이 DMUS_NOTIFY_ON_SEGMENT 의 경우, 이 멤버는 다음의 값의 어느쪽이든을 보관 유지한다.

DMUS_NOTIFICATION_SEGABORT
세그먼트(segment)가 DirectMusicPerformance.Stop 에 의해 정지되었다.
DMUS_NOTIFICATION_SEGALMOSTEND
세그먼트(segment)가 종료 타임부터 준비 시간을 당긴 타임에 이르렀다.
DMUS_NOTIFICATION_SEGEND
세그먼트(segment)가 종료했다.
DMUS_NOTIFICATION_SEGLOOP
세그먼트(segment)가 루프 했다.
DMUS_NOTIFICATION_SEGSTART
세그먼트(segment)가 시작 했다.

통지 타입이 DMUS_NOTIFY_ON_COMMAND 의 경우, 이 멤버는 다음의 값의 어느쪽이든을 보관 유지한다.

DMUS_NOTIFICATION_GROOVE
그루브 체인지.
DMUS_NOTIFICATION_EMBELLISHMENT
장식 커멘드 (인트로, 필, 브레이크, 또는 엔드).

통지 타입이 DMUS_NOTIFY_ON_PERFORMANCE 의 경우, 이 멤버는 다음의 값의 어느쪽이든을 보관 유지한다.

DMUS_NOTIFICATION_MUSICSTARTED
재생이 시작 했다.
DMUS_NOTIFICATION_MUSICSTOPPED
재생이 정지했다.

통지 타입이 DMUS_NOTIFY_ON_MEASUREANDBEAT 의 경우, 이 멤버는 DMUS_NOTIFICATION_MEASUREBEAT 를 보관 유지한다. 그 외의 서브 타입은 정의되지 않는다.

통지 타입이 DMUS_NOTIFY_ON_CHORD 의 경우, 이 멤버는 DMUS_NOTIFICATION_CHORD 를 보관 유지한다. 그 외의 서브 타입은 정의되지 않는다.

lNotificationType
CONST_DMUS_NOTIFICATION_TYPE 열거형의 통지 타입의 식별자.
mtTime
메세지의 타임 스탬프. 뮤직 타임에 지정한다.

참조

DirectMusicPerformance.AddNotificationType ,DirectMusicPerformance.GetNotificationPMSG


DMUS_PORTCAPS

DMUS_PORTCAPS 형은, 포트의 능력에 관한 정보를 돌려준다. 이 형태는,DirectMusicPerformance.GetPortCaps 메소드에게 건네진다.

Type DMUS_PORTCAPS
    lClass as Long
    lEffectFlags As Long
    lFlags As Long
    lMaxAudioChannels As Long
    lMaxChannelGroups As Long
    lMaxVoices As Long
    lMemorySize As Long
    lType As Long
End Type

멤버

lClass
이 포트의 클래스. CONST_DMUS_PC_CLASS 열거형의 몇개의 멤버이다.
lEffectFlags
포트상에서 어떠한 오디오 이펙트를 이용할 수 있는지를 나타내는,CONST_DMUS_EFFECT_FLAGS 열거형의 플래그.
lFlags
포트의 다양한 능력을 기술하는 플래그. 「CONST_DMUS_PC_FLAGS 」를 참조할것.
lMaxAudioChannels
포트에 의해 렌더링 할 수 있는 오디오 채널의 최대수. 이 파라미터가 돌려주어지는 것을 드라이버가 지원 하고 있지 않는 경우, 값은 -1 이라도 좋다.
lMaxChannelGroups
이 포트가 지원 하는 채널 그룹의 최대수. 1 개의 채널 그룹은, 16 개의 MIDI 채널로부터 완성되는 세트이다.
lMaxVoices
이 포트를 열었을 때에 할당을 할 수 있는 발음의 최대수. 이 파라미터가 돌려주어지는 것을 드라이버가 지원 하고 있지 않는 경우, 값은 -1 이라도 좋다.
lMemorySize
DLS 음색의 보존에 이용할 수 있는 메모리의 양. 포트가 시스템 메모리를 사용하고 있어, 이용 가능한 시스템 메모리에 의해 그 양이 제한을 받는 경우, 이 필드는 DMUS_PC_SYSTEMMEMORY 를 보관 유지한다.
lType
이 포트의 타입. 「CONST_DMUS_PORT_TYPE 」를 참조할것.


DMUS_TIMESIGNATURE

DMUS_TIMESIGNATURE 형은, 박자 기호에 관한 정보를 보관 유지한다. 이 형태는,DirectMusicPerformance.GetTimeSig 과 DirectMusicStyle.GetTimeSignature 의 각 메소드에게 건네져DirectMusicPerformance.SendTimeSigPMSG 메소드가 송신하는 메세지내에서도 사용된다.

Type DMUS_TIMESIGNATURE
    beat As Byte
    beatsPerMeasure As Byte
    gridsPerBeat As Integer
    mtTime As Long
End Type

멤버

beat
박자 기호의 분모.
beatsPerMeasure
박자 기호의 분자.
gridsPerBeat
박근처의 그리드 (소분할). 이 값은, 특정의 음악 이벤트의 타이밍 분해가능을 결정한다. 예를 들어, DMUS_SEGF_GRID 플래그를 사용한 세그먼트(segment)의 삽입을 들 수 있다 ( 「CONST_DMUS_SEGF_FLAGS 」를 참조).
mtTime
이 박자 기호가 발생하는 뮤직 타임.


열거형

DirectMusic for Visual Basic 에서는, 정수를 그룹화 하는 열거형을 사용해, Microsoft® Visual Studio® 개발 환경의 스테이트먼트 종료 기능을 활용한다.

여기에서는, 이하의 열거형에 관한 레퍼런스 정보를 제공한다.

  • CONST_DMUS
  • CONST_DMUS_COMMANDT_TYPES
  • CONST_DMUS_COMPOSEF_FLAGS
  • CONST_DMUS_CURVE_FLAGS
  • CONST_DMUS_CURVES
  • CONST_DMUS_CURVET
  • CONST_DMUS_EFFECT_FLAGS
  • CONST_DMUS_NOTEF_FLAGS
  • CONST_DMUS_NOTIFICATION_SUBTYPE
  • CONST_DMUS_NOTIFICATION_TYPE
  • CONST_DMUS_PC_CLASS
  • CONST_DMUS_PC_FLAGS
  • CONST_DMUS_PLAYMODE_FLAGS
  • CONST_DMUS_PMSGF_FLAGS
  • CONST_DMUS_PORT_TYPE
  • CONST_DMUS_SEGF_FLAGS
  • CONST_DMUS_SHAPET_TYPES
  • CONST_DMUSERR


CONST_DMUS

CONST_DMUS 열거형은, DirectMusic 로 사용되는 다양한 정수를 보관 유지한다.

Enum CONST_DMUS
    DMUS_MAXSUBCHORD = 8
    DMUS_TEMPO_MAX = 350 (&H15E)
    DMUS_TEMPO_MIN =  10
End Enum
DMUS_MAXSUBCHORD
코드내에서 허가되는 서브 코드의 최대수.
DMUS_TEMPO_MAX
최대 템포. 1 분 쯤의 박수로 나타낸다.
DMUS_TEMPO_MIN
최소 템포. 1 분 쯤의 박수로 나타낸다.


CONST_DMUS_COMMANDT_TYPES

CONST_DMUS_COMMANDT_TYPES 열거형의 멤버는, 음악 패턴을 확립하는 커멘드를 나타낸다. 이러한 멤버는,DirectMusicComposer.AutoTransition 와 DirectMusicComposer.ComposeTransition 의 각 메소드의 lCommand 파라미터내에서 사용되어DirectMusicPerformance.GetCommand 메소드에 의해 돌려주어진다.

Type CONST_DMUS_COMMANDT_TYPES
    DMUS_COMMANDT_BREAK       = 3
    DMUS_COMMANDT_END         = 4
    DMUS_COMMANDT_ENDANDINTRO = 5
    DMUS_COMMANDT_FILL        = 1
    DMUS_COMMANDT_GROOVE      = 0
    DMUS_COMMANDT_INTRO       = 2
End Enum
DMUS_COMMANDT_BREAK
커멘드는 변환점이다.
DMUS_COMMANDT_END
커멘드는 종료부이다.
DMUS_COMMANDT_ENDANDINTRO
커멘드는 종료부와 도입부이다.
DMUS_COMMANDT_FILL
커멘드는 필이다.
DMUS_COMMANDT_GROOVE
커멘드는 그루브 커멘드이다.
DMUS_COMMANDT_INTRO
커멘드는 도입부이다.


CONST_DMUS_COMPOSEF_FLAGS

CONST_DMUS_COMPOSEF_FLAGS 열거형의 멤버는,DirectMusicComposer.AutoTransition 와 DirectMusicComposer.ComposeTransition 의 각 메소드의 lFlags 파라미터내에서 사용된다.

Enum CONST_DMUS_COMPOSEF_FLAGS
    DMUS_COMPOSEF_AFTERPREPARETIME = 64 (&H40)
    DMUS_COMPOSEF_ALIGN             = 1
    DMUS_COMPOSEF_BEAT             = 16 (&H10)
    DMUS_COMPOSEF_GRID              = 8
    DMUS_COMPOSEF_IMMEDIATE         = 4
    DMUS_COMPOSEF_LONG           = 8192 (&H2000)
    DMUS_COMPOSEF_MEASURE          = 32 (&H20)
    DMUS_COMPOSEF_MODULATE       = 4096 (&H1000)
    DMUS_COMPOSEF_NONE              = 0
    DMUS_COMPOSEF_OVERLAP           = 2
End Enum
DMUS_COMPOSEF_AFTERPREPARETIME
AutoTransition 마셔. 이행부를 삽입 하면나무는, DMUS_SEGF_AFTERPREPARETIME 플래그 ( 「CONST_DMUS_SEGF_FLAGS 」를 참조)를 사용한다.
DMUS_COMPOSEF_ALIGN
이행부를, 현재 연주되고 있는 세그먼트(segment)의 박자 기호에 가지런히 한다. 현재 이행되어 있지 않다.
DMUS_COMPOSEF_BEAT
AutoTransition 마셔. 박의 경계로부터 이행부를 시작 한다.
DMUS_COMPOSEF_GRID
AutoTransition 마셔. 그리드 경계로부터 이행부를 시작 한다.
DMUS_COMPOSEF_IMMEDIATE
AutoTransition 마셔. 뮤직 타임 또는 클럭 타임의 경계로부터 이행부를 시작 한다.
DMUS_COMPOSEF_MEASURE
AutoTransition 마셔. 소절 경계로부터 이행부를 시작 한다.
DMUS_COMPOSEF_LONG
긴 이행부를 어레인지 한다. 이 플래그가 세트되어 있지 않은 경우,ComposeTransition 또는 AutoTransition 의 lCommand 파라미터로 종료부를 지정해, 스타일에 1 소절보다 긴 종료부가 포함되지 않은 한, 이행부의 길이는 최대에서도 1 소절이다. 이 플래그가 세트 되고 있는 경우, 이행부의 길이는 1 소절 증가한다.
DMUS_COMPOSEF_MODULATE
toSeg 의 코드를 사용해,fromSeg 로부터 toSeg 에 순조롭게 변화하는 이행부를 어레인지 한다.
DMUS_COMPOSEF_NONE
플래그 없음. 디폴트에서는, 이행부는 소절 경계로부터 시작 한다.
DMUS_COMPOSEF_OVERLAP
이행부를 toSeg 에 거듭한다 (오버랩). 현재 이행되어 있지 않다.


CONST_DMUS_CURVE_FLAGS

CONST_DMUS_CURVE_FLAGS 열거형은,DMUS_CURVE_PMSG 형으로 사용되는 1 개의 정수를 보관 유지한다.

Enum CONST_DMUS_CURVE_FLAGS
    DMUS_CURVE_RESET = 1
End Enum
DMUS_CURVE_RESET
디폴트의 타임에 이르렀을 때, 또는 이행부가 원인으로 무효화가 발생했을 때에 리셋값을 설정해야 한다.


CONST_DMUS_CURVES

CONST_DMUS_CURVES 열거형의 멤버는,DMUS_CURVE_PMSG 형내에서 곡선의 셰이프를 정의할 때에 사용된다.

Enum CONST_DMUS_CURVES
    DMUS_CURVES_EXP =     2
    DMUS_CURVES_INSTANT = 1
    DMUS_CURVES_LINEAR =  0
    DMUS_CURVES_LOG =     3
    DMUS_CURVES_SINE =    4
End Enum
DMUS_CURVES_EXP
지수 곡선 셰이프.
DMUS_CURVES_INSTANT
즉시 곡선 셰이프 (곡선의 시작과 종료가 거의 동시에 발생한다).
DMUS_CURVES_LINEAR
선상 곡선 셰이프.
DMUS_CURVES_LOG
대수 곡선 셰이프.
DMUS_CURVES_SINE
사인 곡선 셰이프.


CONST_DMUS_CURVET

CONST_DMUS_CURVET 열거형의 멤버는,DMUS_CURVE_PMSG 형내에서 곡선의 타입을 기술할 때에 사용된다.

Enum CONST_DMUS_CURVET
    DMUS_CURVET_CCCURVE =  4
    DMUS_CURVET_MATCURVE = 5
    DMUS_CURVET_PATCURVE = 6
    DMUS_CURVET_PBCURVE =  3
End Enum
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).


CONST_DMUS_EFFECT_FLAGS

CONST_DMUS_EFFECT_FLAGS 열거형의 멤버는, 포트가 지원 하는 이펙트의 종류를 지정하기 위해서 DMUS_PORTCAPS 형내에서 사용된다.

Enum CONST_DMUS_EFFECT_FLAGS
    DMUS_EFFECT_CHORUS = 2
    DMUS_EFFECT_NONE   = 0
    DMUS_EFFECT_REVERB = 1
End Enum
DMUS_EFFECT_CHORUS
포트는 코러스를 지원 한다.
DMUS_EFFECT_NONE
포트는 어느 이펙트도 지원 하지 않는다.
DMUS_EFFECT_REVERB
포트는 리바브를 지원 한다.


CONST_DMUS_NOTEF_FLAGS

CONST_DMUS_NOTEF_FLAGS 열거형은, 음표 메세지로 사용되는 1 개의 정수를 보관 유지한다.

Enum CONST_DMUS_NOTEF_FLAGS
    DMUS_NOTEF_NOTEON = 1
End Enum
DMUS_NOTEF_NOTEON
「DMUS_NOTE_PMSG 」의 「주의」를 참조할것.


CONST_DMUS_NOTIFICATION_SUBTYPE

CONST_DMUS_NOTIFICATION_SUBTYPE 열거형의 멤버는, 통지 메세지내에서 보고되는 음악 이벤트에 관한 정보를 제공한다.

Enum CONST_DMUS_NOTIFICATION_SUBTYPE
    DMUS_NOTIFICATION_CHORD =         0
    DMUS_NOTIFICATION_EMBELLISHMENT = 1
    DMUS_NOTIFICATION_GROOVE =        0
    DMUS_NOTIFICATION_MEASUREBEAT =   0
    DMUS_NOTIFICATION_MUSICSTARTED =  0
    DMUS_NOTIFICATION_MUSICSTOPPED =  1
    DMUS_NOTIFICATION_SEGABORT =      4
    DMUS_NOTIFICATION_SEGALMOSTEND =  2
    DMUS_NOTIFICATION_SEGEND =        1
    DMUS_NOTIFICATION_SEGLOOP =       3
    DMUS_NOTIFICATION_SEGSTART =      0
End Enum

값의 설명에 대해서는, 「DMUS_NOTIFICATION_PMSG 」를 참조할것.


CONST_DMUS_NOTIFICATION_TYPE

CONST_DMUS_NOTIFICATION_TYPE 열거형의 멤버는, 통지 타입을 식별한다. 이러한 멤버는,DirectMusicPerformance.AddNotificationType 와 DirectMusicPerformance.RemoveNotificationType 의 각 메소드에게 건네져DirectMusicPerformance.GetNotificationPMSG 가 꺼내는 메세지내의 통지 타입을 식별한다.

Enum CONST_DMUS_NOTIFICATION_TYPE
    DMUS_NOTIFY_ON_CHORD          = 1
    DMUS_NOTIFY_ON_COMMAND        = 2
    DMUS_NOTIFY_ON_MEASUREANDBEAT = 3
    DMUS_NOTIFY_ON_PERFORMANCE    = 4
    DMUS_NOTIFY_ON_SEGMENT        = 5
End Enum
DMUS_NOTIFY_ON_CHORD
코드 체인지.
DMUS_NOTIFY_ON_COMMAND
커멘드 이벤트.
DMUS_NOTIFY_ON_MEASUREANDBEAT
소절 및 박이벤트.
DMUS_NOTIFY_ON_PERFORMANCE
퍼포먼스 이벤트. 이 값이 DMUS_NOTIFICATION_PMSG 형의 lNotificationType 멤버내에서 발견되었을 경우, 이벤트는 lNotificationOption 멤버내에서 한층 더 정의된다.
DMUS_NOTIFY_ON_SEGMENT
세그먼트(segment) 이벤트. 이 값이 DMUS_NOTIFICATION_PMSG 형의 lNotificationType 멤버내에서 발견되었을 경우, 이벤트는 lNotificationOption 멤버내에서 한층 더 정의된다.

참조

DMUS_NOTIFICATION_PMSG


CONST_DMUS_PC_CLASS

CONST_DMUS_PC_CLASS 열거형의 멤버는, 포트의 클래스를 지정하기 위해서 DMUS_PORTCAPS 형내에서 사용된다.

Enum CONST_DMUS_PC_CLASS
    DMUS_PC_INPUTCLASS =  0
    DMUS_PC_OUTPUTCLASS = 1
End Enum
DMUS_PC_INPUTCLASS
입력 포트.
DMUS_PC_OUTPUTCLASS
출력 포트.


CONST_DMUS_PC_FLAGS

CONST_DMUS_PC_FLAGS 열거형의 멤버는, 포트의 다양한 능력을 기술하기 위해서,DMUS_PORTCAPS 형내에서 사용된다.

Enum CONST_DMUS_PC_FLAGS
    DMUS_PC_DIRECTSOUND =         128 (&H80)
    DMUS_PC_DLS =                   1
    DMUS_PC_EXTERNAL =              2
    DMUS_PC_GMINHARDWARE =         16 (&H10)
    DMUS_PC_GSINHARDWARE =         32 (&H20)
    DMUS_PC_MEMORYSIZEFIXED =       8
    DMUS_PC_SHAREABLE =           256 (&H100)
    DMUS_PC_SOFTWARESYNTH =         4
    DMUS_PC_SYSTEMMEMORY = 2147483647 (&H7FFFFFFF)
    DMUS_PC_XGINHARDWARE =         64 (&H40)
End Enum
DMUS_PC_DIRECTSOUND
포트는 DirectSound 에 보내는 스트리밍 웨이브 데이터를 지원 한다.
DMUS_PC_DLS
포트는 DLS 레벨 1 의 샘플 콜렉션을 지원 한다.
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_SYSTEMMEMORY
포트는 시스템 메모리를 사용하고 있기 (위해)때문에, 그 메모리량은 이용 가능한 시스템 메모리인 만큼 따라 제한된다. 이 정수는,lFlags 는 아니고,DMUS_PORTCAPS.lMemorysize 내에서 사용된다.
DMUS_PC_XGINHARDWARE
이 포트는, 하드웨어내에 Yamaha XG 확장을 보관 유지하고 있다.


CONST_DMUS_PLAYMODE_FLAGS

CONST_DMUS_PLAYMODE_FLAGS 열거형의 멤버는,DMUS_NOTE_PMSG 메세지 타입내에서 연주 모드를 설정할 때에 사용된다. 연주 모드에 의해, 음표가 MIDI 음표에 변환되기 전에, 현재의 코드에 전조 될 방법이 정해진다.

Enum CONST_DMUS_PLAYMODE_FLAGS
    DMUS_PLAYMODE_ALWAYSPLAY     = 14
    DMUS_PLAYMODE_CHORD_INTERVALS = 8
    DMUS_PLAYMODE_CHORD_ROOT      = 2
    DMUS_PLAYMODE_FIXED           = 0
    DMUS_PLAYMODE_FIXEDTOCHORD    = 2
    DMUS_PLAYMODE_FIXEDTOKEY      = 1
    DMUS_PLAYMODE_KEY_ROOT        = 1
    DMUS_PLAYMODE_MELODIC         = 6
    DMUS_PLAYMODE_NONE           = 16 (&H10)
    DMUS_PLAYMODE_NORMALCHORD    = 10
    DMUS_PLAYMODE_PEDALPOINT      = 5
    DMUS_PLAYMODE_SCALE_INTERVALS = 4
End Enum

이하의 멤버는 기본적인 플래그이다.

DMUS_PLAYMODE_CHORD_INTERVALS
코드 패턴의 코드의 음정을 사용한다.
DMUS_PLAYMODE_CHORD_ROOT
코드의 루트음상에 전조 한다.
DMUS_PLAYMODE_KEY_ROOT
키의 루트음상에 전조 한다.
DMUS_PLAYMODE_NONE
모드 없음. 친파트의 모드를 사용할 필요가 있는 것을 나타낸다.
DMUS_PLAYMODE_SCALE_INTERVALS
스케일 패턴의 스케일의 음정을 사용한다.
이하의 멤버는 기본적인 플래그의 편성을 나타낸다.
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 의 편성. 키의 루트음이 사용되어 음표는 스케일내의 음정만을 쫓는다. 코드의 루트음과 음정은 무시된다. 이것은, 키의 루트음을 기준으로 해 연주되는 선율계의 라인에 있어 편리하다.


CONST_DMUS_PMSGF_FLAGS

CONST_DMUS_PMSGF_FLAGS 열거형의 멤버는, 메세지를 툴에 전달하는 타임을 지정하기 위해서,DirectMusicPerformance 의 다양한 메세지 송신 메소드내에서 사용된다.

Enum CONST_DMUS_PMSGF_FLAGS
    DMUS_PMSGF_MUSICTIME      = 2
    DMUS_PMSGF_REFTIME        = 1
    DMUS_PMSGF_TOOL_ATTIME   = 16 (&H10)
    DMUS_PMSGF_TOOL_FLUSH    = 32 (&H20)
    DMUS_PMSGF_TOOL_IMMEDIATE = 4
    DMUS_PMSGF_TOOL_QUEUE     = 8
End Enum
DMUS_PMSGF_REFTIME
타임 스탬프는 클럭 타임에 나타내진다.
DMUS_PMSGF_MUSICTIME
타입 스탬프는 뮤직 타임에 나타내진다.
DMUS_PMSGF_TOOL_IMMEDIATE
DMUS_PMSGF_TOOL_QUEUE
DMUS_PMSGF_TOOL_ATTIME
DMUS_PMSGF_TOOL_FLUSH
「주의」를 참조할것.

주의

DirectX for Visual Basic 는 DirectMusic 툴을 지원 하지 않기 때문에, DMUS_PMSGF_REFTIME 와 DMUS_PMSGF_MUSICTIME 만이 현재 유효하다. 메세지의 타임은 디폴트로 뮤직 타임에 나타내지기 (위해)때문에, DMUS_PMSGF_REFTIME 는 어플리케이션이 보통 사용하는 유일한 플래그이다.


CONST_DMUS_PORT_TYPE

CONST_DMUS_PORT_TYPE 열거형은, 포트의 드라이버 모델을 지정하기 위해서,DMUS_PORTCAPS 형내에서 사용된다.

Enum CONST_DMUS_PORT_TYPE
    DMUS_PORT_KERNEL_MODE =     2
    DMUS_PORT_USER_MODE_SYNTH = 1
    DMUS_PORT_WINMM_DRIVER =    0
End Enum
DMUS_PORT_WINMM_DRIVER
Windows 멀티미디어 드라이버.
DMUS_PORT_USER_MODE_SYNTH
유저 모드 신디사이저.
DMUS_PORT_KERNEL_MODE
WDM (Windows Driver Model) 드라이버.


CONST_DMUS_SEGF_FLAGS

CONST_DMUS_SEGF_FLAGS 열거형의 멤버는, 세그먼트(segment)에 대한 액션의 타이밍이나 그 외의 요소를 제어하기 위해서,DirectMusicPerformance 오브젝트의 다양한 메소드내에서 사용된다.

Enum CONST_DMUS_SEGF_FLAGS
    DMUS_SEGF_AFTERPREPARETIME = 1024 (&H400)
    DMUS_SEGF_BEAT             = 4096 (&H1000)
    DMUS_SEGF_CONTROL           = 512 (&H200)
    DMUS_SEGF_DEFAULT         = 16384 (&H4000)
    DMUS_SEGF_GRID             = 2048 (&H800)
    DMUS_SEGF_MEASURE          = 8192 (&H2000)
    DMUS_SEGF_NOINVALIDATE    = 32768 (&H8000)
    DMUS_SEGF_QUEUE             = 256 (&H100)
    DMUS_SEGF_REFTIME            = 64 (&H40)
    DMUS_SEGF_SECONDARY         = 128 (&H80)
End Enum
DMUS_SEGF_AFTERPREPARETIME
준비 시간의 뒤에 연주한다 ( 「DirectMusicPerformance.GetPrepareTime 」를 참조).
DMUS_SEGF_BEAT
박의 경계에서 연주한다.
DMUS_SEGF_CONTROL
제어 세그먼트(segment)로서 연주한다 (세컨드리 세그먼트(segment)만). 「주의」를 참조할것.
DMUS_SEGF_DEFAULT
세그먼트(segment)의 디폴트의 경계를 사용한다.
DMUS_SEGF_GRID
그리드 경계에서 연주한다.
DMUS_SEGF_MEASURE
소절 경계에서 연주한다.
DMUS_SEGF_NOINVALIDATE
프라이머리 세그먼트(segment) 또는 제어 세그먼트(segment)에 대해, 이 플래그를 DirectMusicPerformance.PlaySegment 내에서 세트 하면, 새로운 세그먼트(segment)로 무효화가 발생하지 않는다. 이 플래그가 없으면 무효화가 발생해, 연주중의 곡선이나 음표가 중단되어 리셋 된다. 이 플래그는 DMUS_SEGF_AFTERPREPARETIME 와 조합하지 않으면 안 된다. 그렇게 하는 것에 의해, 새로운 세그먼트(segment)내의 음표는, 낡은 세그먼트(segment)가 연주하는 음표에 거듭해 연주하지 않는다.
DMUS_SEGF_QUEUE
프라이머리 세그먼트(segment) 큐의 마지막에 둔다 (프라이머리 세그먼트(segment)만).
DMUS_SEGF_REFTIME
타임 파라미터는 클럭 타임에 나타내진다.
DMUS_SEGF_SECONDARY
세컨드리 세그먼트(segment).

주의

보통, 프라이머리 세그먼트(segment)는 제어 세그먼트(segment)이다. DMUS_SEGF_CONTROL 플래그를 사용해, 세컨드리 세그먼트(segment)를 제어 세그먼트(segment)로 할 수 있다. 다만, 제어 세그먼트(segment)를 존재할 수 있는 것은 한 번에 1 개(살) 뿐이다 (복수의 제어 세그먼트(segment)를 생성 할 수 있지만, 실제로 어느 제어 세그먼트(segment)가 DirectMusic 에 의해 사용될까는 보증되지 않는다). 디폴트에서는, 제어 세그먼트(segment)만이 템포 메세지를 송신한다.

DMUS_SEGF_CONTROL 플래그를 세트 하면, DMUS_SEGF_SECONDARY 가 상정된다.

참조

DirectMusicPerformance.GetResolvedTime ,DirectMusicPerformance.Invalidate ,DirectMusicPerformance.PlaySegment ,DirectMusicPerformance.Stop


CONST_DMUS_SHAPET_TYPES

CONST_DMUS_SHAPET_TYPES 열거형의 멤버는,DirectMusicComposer.ComposeSegmentFromShape 과 DirectMusicComposer.ComposeTemplateFromShape 의 각 메소드의 wShape 파라미터내에서 사용되어 그루브 레벨의 희망의 패턴을 지정한다.

Enum CONST_DMUS_SHAPET_TYPES
    DMUS_SHAPET_FALLING  = 0
    DMUS_SHAPET_LEVEL    = 1
    DMUS_SHAPET_LOOPABLE = 2
    DMUS_SHAPET_LOUD     = 3
    DMUS_SHAPET_PEAKING  = 5
    DMUS_SHAPET_QUIET    = 4
    DMUS_SHAPET_RANDOM   = 6
    DMUS_SHAPET_RISING   = 7
    DMUS_SHAPET_SONG     = 8
End Enum
DMUS_SHAPET_FALLING
그루브 레벨은 하강한다.
DMUS_SHAPET_LEVEL
그루브 레벨은 균등하게 유지된다.
DMUS_SHAPET_LOOPABLE
세그먼트(segment)는 선두에 루프 하도록(듯이) 조정되고 있다.
DMUS_SHAPET_LOUD
그루브 레벨은 높다.
DMUS_SHAPET_PEAKING
그루브 레벨은 피크까지 상승해, 그 후 하강한다.
DMUS_SHAPET_QUIET
그루브 레벨은 낮다.
DMUS_SHAPET_RANDOM
그루브 레벨은 랜덤이다.
DMUS_SHAPET_RISING
그루브 레벨은 상승한다.
DMUS_SHAPET_SONG
섹션은 노래의 형식이다. 6 ~ 8 소절로부터 완성되는 복수의 락구를 어레인지 해, 정리하는 것에 의해, 그루브 레벨에 바리에이션이 있는 바스코라스에페크트가 만들어진다.


CONST_DMUSERR

CONST_DMUSERR 열거형은, DirectMusic 의에러 코드를 나타낸다.


에러 코드

여기에서는, DirectMusic 의 메소드에 의해 돌려주어지는 다양한 에러 코드에 대해 간단하게 설명한다. 각 메소드가 돌려주는 특정의 에러 코드의 리스트에 대해서는, 개별의 메소드의 설명을 참조할것. 이러한 리스트는 반드시 포괄적인 것이라고는 할 수 없다.

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_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_OPEN_PORT
디폴트의 시스템 포트를 열 수가 없었다.
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_FAIL
이 메소드는 성공하지 않았다.
DMUS_E_GET_UNSUPPORTED
파라미터의 취득은 지원 하고 있지 않다.
DMUS_E_INSUFFICIENTBUFFER
요구된 조작을 실행하기 위한 버퍼가 충분한 크기는 아니다.
DMUS_E_INVALIDARG
무효인 인수.
DMUS_E_INVALID_BAND
파일에 유효한 밴드가 포함되지 않았다.
DMUS_E_INVALID_DOWNLOADID
다운로드 버퍼의 생성 프로세스로, 무효인 다운로드 식별자가 사용되었다.
DMUS_E_INVALID_EVENT
이벤트는, 유효한 MIDI 메세지는 아닌, 또는 동작 스테이터스를 이용하고 있어 버퍼내에 팩 할 수 없다.
DMUS_E_INVALIDBUFFER
무효인 DirectSound 버퍼가 포트에게 건네졌다.
DMUS_E_INVALIDFILE
파일이 무효이다.
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_OBJECTNOTFOUND
오브젝트가 발견되지 않았다.
DMUS_E_NO_MASTER_CLOCK
퍼포먼스내에 master clock가 존재하지 않는다. DirectMusicPerformance.Init 메소드를 반드시 호출하는 것.
DMUS_E_NOINTERFACE
이용 가능한 오브젝트 인터페이스가 없다.
DMUS_E_NOT_DOWNLOADED_TO_PORT
오브젝트가 포트상에 없기 때문에, 언로드할 수 없다.
DMUS_E_NOT_FOUND
요구된 항목은 오브젝트에 포함되지 않았다.
DMUS_E_NOT_INIT
필요한 오브젝트는 초기화되어 있지 않은지, 초기화에 실패했다.
DMUS_E_NOTADLSCOL
로드안의 오브젝트는 유효한 DLS 콜렉션은 아니다.
DMUS_E_NOTIMPL
이 메소드는 이행되어 있지 않다. 동작에 필요한 기능을 드라이버가 지원 하고 있지 않기 위해(때문에), 이 메소드가 돌려주어지는 일이 있다.
DMUS_E_OUT_OF_RANGE
요구된 타임은 세그먼트(segment)의 범위외이다.
DMUS_E_OUTOFMEMORY
메모리 부족을 위해, 태스크를 완료할 수 없다.
DMUS_E_PORT_NOT_RENDER
출력 포트는 아니다.
DMUS_E_PORTS_OPEN
시스템내의 임의의 프로세스에 인스턴스화 된 포트가 있을 때는, 요구된 조작을 실행할 수 없다.
DMUS_E_SEGMENT_INIT_FAILED
세그먼트(segment)의 초기화에 실패했다. 메모리로 중대한 문제가 발생했다고 생각된다.
DMUS_E_SET_UNSUPPORTED
파라미터의 설정은 지원 하고 있지 않다.
DMUS_E_TIME_PAST
요구된 타임은 과거의 타임이다.
DMUS_E_TRACK_NOT_FOUND
요구된 타입의 트랙이 없다.
DMUS_E_TYPE_DISABLED
파라미터는 무효화되고 있기 (위해)때문에 이용할 수 없다.
DMUS_E_TYPE_UNSUPPORTED
파라미터는 이 트랙상에서 지원되어 있지 않다.
DMUS_E_UNKNOWN_PROPERTY
이 포트에는 프로퍼티 세트나 항목이 이행되어 있지 않다.
DMUS_E_UNSUPPORTED_STREAM
스트림은, 로드안의 오브젝트가 지원 하고 있는 데이터를 포함하지 않았다.


DirectMusic 샘플

여기에서는, DirectX SDK 에 포함되어 있는, DirectMusic 를 사용한 샘플 어플리케이션에 대해 설명한다. 설명하는 내용은 이하대로이다.

  • DirectMusic C/C++ 샘플
  • DirectMusic Visual Basic 샘플


DirectMusic C/C++ 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 샘플」을 참조할것.

[C++]

다음의 샘플 어플리케이션에서는, DirectMusic® 어플리케이션 프로그래밍 인터페이스의 사용 방법과 기능을 나타내고 있다.

  • 3DMusic 샘플
  • DMBoids 샘플
  • DMDonuts 샘플
  • DirectMusic MIDI 샘플
  • DirectMusic Shell 샘플
  • EchoTool 샘플
  • MusicLines 샘플
  • PlayMotif 샘플
  • PlayPrimary 샘플

DirectX® 샘플에는 Microsoft Visual C++ 프로젝트 워크 스페이스 파일이 포함되어 있지만, 독자의 개발 환경에서 올바르게 컴파일 할 수 있을지 어떨지를 확인할 필요가 있다. 자세하게는, 「DirectX 의 샘플 및 그 외의 DirectX 어플리케이션의 컴파일 .」(을)를 참조할것.


3DMusic 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 샘플」을 참조할것.

[C++]

설명

3DMusic 샘플에서는, 커스텀 DirectSound 3-D 버퍼로 MIDI 파일을 연주하는 방법을 나타낸다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\Dmusic\Src\3DMusic

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DMusic\Bin\3DMusic.exe

유저즈 가이드

표시되는 아이콘은, 3-D 환경에 있어서의 청취자와 음원을 나타내고 있다. 다만, 이동과 방향의 설정은 2 차원만된다.

음원을 이동하려면 , 방향 키를 사용한다. 청취자의 방향을 변경하려면 , 수치 키패드를 사용한다.

[File] 메뉴의 [Play Stereo Drip] 를 선택 하면, 물방울이 떨어지는 사운드가, 랜덤인 팬 및 볼륨 설정으로 재생된다. 이것에 의해, 2-D 버퍼로, 어떻게 유사 3-D 이펙트가 생성되고 있는지를 확인할 수가 있다.

프로그래밍 위에의 주의

프로그램은, DirectX SDK 셋업으로 설정된 레지스트리 키를 사용해, 미디어 파일 패스를 검색한다.

Helper.cpp 에는, DirectMusic 를 설정하기 위한 유용한 함수가 포함되어 있다. 이러한 함수는, Soud.cpp 로부터 불려 간다.


DMBoids 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 샘플」을 참조할것.

[C++]

설명

DMBoids 는,Boids 에 DirectMusic 지원을 추가한 샘플이다. 오브젝트를 간단한 지형 위를 비행시켜, 유저의 입력 및 화면상의 이벤트에 반응해 음악을 연주한다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\Dmusic\Src\DMBoids

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DMusic\Bin\Dmboids.exe

유저즈 가이드

메인 메뉴에 액세스 하려면 , F10 키를 누른다. [Drivers] 메뉴를 사용하면(자), 드라이버, 디바이스, 및 비디오 모드를 변경할 수 있다. 어플리케이션은, 풀 스크린 모드에서만 실행된다.

A (정렬), C (집합), 및 O 키 (장해)를 누르면(자), 키를 누르고 있는 동안, 보이드의 움직임이 여러가지로 변화한다.

S 키 또는 Space 키를 계속 누르면(자) , 새가 근처에 모인다. 키를 떼어 놓으면(자) 산개 한다. 이 동작에 맞추어, 모티프가 사용되고 있는 점에 주의 해야 한다.

M 키를 계속 누르면(자) , 새는 코스를 빗나간다. 음악이 완전하게 변화하는 점에 주의 해야 한다. 키를 떼어 놓으면(자), 최종적으로 새는 코스로 돌아간다.

Esc 키를 누르면(자) 종료한다.

프로그래밍 위에의 주의

DirectMusic 의 다음과 같은 기능이 사용되고 있다.

  • DLS 에 의한 소프트웨어 합성. 어플리케이션은, GS 사운드 세트의 악기에 가세해, 혹성 (장애물)에 가까워졌을 때에 재생되는 음성 등, 독자적인 다운로더블 사운드를 사용한다.
  • 스타일에 근거하는 세그먼트(segment)의 생성과 연주.
  • 스타일에 근거하는 모티프와 세그먼트(segment)의 삽입을 사용한 음악의 이행.
  • 코드화 된 메아리/아티큘레이션 툴. 음악을 연주할 경우에, 새의 접근으로부터 메아리와 음표의 길이를 조정한다.


DMDonuts 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 샘플」을 참조할것.

[C++]

설명

DM Donuts 는,Space Donuts 샘플에, 게임 이벤트에 응한 음악을 추가한 것이다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\Dmusic\Src\DMDonuts

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DMusic\Bin\Dmdonuts.exe

유저즈 가이드

도너츠가 우주에 떠올라 있는 동안은, 조용한 음악인 점에 주의 해야 한다. 방향 키를 누르면(자), 우주선이 이동한다. 우주선이 주위로 튀어올랐을 때에, 거기에 맞추어 음악과 리듬이 변화하는 것을 확인한다.

Space 키를 눌러, 도너츠에 총알을 맞힌다. 즉시 폭발음이 울어, 배경 뮤직이 커진다.

수치 키패드의 7 키를 누르면(자), 쉴드(shield)가 온이 된다. 쉴드(shield)의 안쪽에서 (들)물어 있는 것과 같게, 음악이 소음되고 있는 점에 주의한다.

모든 도너츠의 단편을 파괴 하면, 즉시 음악은 종료부로 옮겨, 다음의 레벨이, 다음의 뮤직 테마의 선두로부터 시작 되는 점에 주의 해야 한다.

음악이 같지 않은 점에 주의 해야 한다.

[Game] 메뉴로 입력 디바이스를 변경 하면, 죠이스틱으로 우주선을 조작할 수가 있다.

다음의 일람에, 모든 게임 커멘드를 나타낸다. 숫자는 모두 수치 키패드로부터 입력해야 한다. "Joy" 는 죠이스틱 버튼을 나타낸다.

키 | 커멘드
ESC,F12 | 종료
4 | 왼쪽 선회
6 | 오른쪽 선회
5 (Joy 3) | 정지
8 | 전방에 가속
2 | 후방에 가속
7 (Joy 2) | 쉴드(shield)
Space (Joy 1) | 발사
Enter | 게임 시작
F1 | 잔상 이펙트의 온/오프
F5 | frame rate의 표시의 온/오프
F7 | 음악의 온/오프
F10 | 메인 메뉴

디폴트의 표시는, 640x480 로 256 색이다. 커멘드 라인으로, 다른 해상도와 색 가지수를 지정할 수가 있다.

이 게임에서는, 다음의 커멘드 라인 스윗치가 사용된다. 대문자와 소문자는 구별된다.

e | 하드웨어 가속화는 아니고, 소프트웨어 에뮬레이션을 사용한다.
t | 테스트 모드. 입력을 필요로 하지 않는다.
x | 스트레스 모드. 플레이어가 조작하지 않으면 멈추지 않는다.

이러한 스윗치의 뒤에, x 해상도, y 해상도, 및 픽셀 근처의 비트수를 지정할 수도 있다. 예를 들어, 다음과 같이 지정한다.

donuts -t 800 600 16

프로그래밍 위에의 주의

여기에서는, 다음의 테크닉이 사용되고 있다.

  • 스타일에 근거하는 세그먼트(segment)의 생성과 연주.
  • 게임 스테이지가 바뀔 때의 자동 이행.
  • 액션을 강조하는 모티프 (짧은 뮤직 클립). 모티프는 기조가 되는 음악의 리듬과 화음에 추종하기 위해(때문에), 음악에 음향적인 강화가 더해진다.
  • 리얼타임 이벤트에 응해, 오케스트레이션을 변화시키는 동적인 밴드.

디폴트에서는, 이 샘플은 소프트웨어 신디사이저로 동작한다. 하드웨어에서의 DLS 합성을 지원 하는 operating system에서는, _SOFTWARE_SYNTH_ 컴파일 플래그를 정의하지 않고 , 샘플을 재컴파일 하는 것.


DirectMusic MIDI 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 샘플」을 참조할것.

[C++]

설명

DirectMusic MIDI 샘플은, 간단한 MIDI 파일 플레이어이다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\Dmusic\Src\DMusMIDI

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DMusic\Bin\Dmusmidi.exe

유저즈 가이드

[File] 메뉴의 [Open] 를 선택해, MIDI 파일을 로드한다 (\Samples\Multimedia\DMusic\Media 폴더에, 샘플 파일이 준비되어 있다). 드래그 앤드 드롭 조작에서도, 파일을 로드할 수가 있다. [Option] 메뉴의 [Autoplay Dropped Files] 가 선택되고 있는 경우는, 드롭 한 파일이 자동적으로 연주된다.

로드한 파일은,[File] 메뉴 또는 툴바로부터, 연주, 일시정지, 및 정지할 수가 있다.

[Options] 메뉴에서는, 리바브를 추가할지 어떨지를 선택하거나 인터페이스를 선택할 수가 있다. 시간은, 연주 시작으로부터의 시간, 분 , 및 초, 또는 뮤직 타임의 틱으로 표시된다.

음악을 연주하고 있지 않을 때에,[Device] 메뉴로부터 포트를 선택할 수가 있다. "MIDI Out" 포트로부터 음악을 들으려면 , 외부 신디사이저를 접속할 필요가 있는 점에 주의 해야 한다.

프로그래밍 위에의 주의

어플리케이션에서는, MIDI 파일을 세그먼트(segment)로서 로드하는 방법, 연주와 정지의 방법, 및 연주를 최초부터 또는 정지한 위치로부터 재개하는 방법을 나타내고 있다. 리바브프로파티의 설정 방법법도 나타나고 있다.

코드는 순수한 C 로 기술되고 있다. 따라서, 메소드는 vtables 에의 포인터를 통해 불려 간다. 상세한 것에 대하여는, 「C 로부터의 COM 오브젝트에의 액세스」를 참조할것.


DirectMusic Shell 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 샘플」을 참조할것.

[C++]

설명

DirectMusic Shell 샘플에서는, Windows 의 시스템 이벤트에 응답하는 인터랙티브 뮤직을 나타낸다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\Dmusic\Src\DMShell

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DMusic\Bin\Dmshell.exe

유저즈 가이드

프로그램을 실행 하면, 태스크바의 트레이에 인디케이터(indicator) 아이콘이 표시된다. 아이콘을 클릭 하면 메뉴가 표시되어 음악 스킴의 변경, 출력 디바이스의 선택, 음악의 시작과 정지, 및 프로그램의 종료를 실행할 수가 있다.

시스템 이벤트에 응해 음악이 변화하는 모습, 및 모티프가 삽입되는 모습에 주의 해야 한다. 시스템 이벤트에는, 윈도우의 최소화, 복원, 또는 종료, 어플리케이션 메뉴 또는 스타트 메뉴의 표시, 키의 밀기 인하 (몇개의 키에서는 특수한 사운드가 발생한다)등이 있다.

프로그래밍 위에의 주의

Windows 의 시스템 메세지는, Dmhook.dll 로 취득된다. 소스 코드는 (SDK 루트) \Samples\Multimedia\Dmusic\Src\DMHook 폴더에 있다(Dmhook.dll 는, Microsoft 의 컴파일러로 컴파일 해야 한다).


EchoTool 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 샘플」을 참조할것.

[C++]

설명

EchoTool 샘플에서는, DirectMusic 로 툴을 이행 하는 방법을 나타낸다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\Dmusic\Src\EchoTool

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DMusic\Bin

유저즈 가이드

메아리의 지연을 변경하려면 , 옵션 버튼을 선택한다. 어플리케이션을 종료하려면 ,[Close] 버튼을 클릭한다.

프로그래밍 위에의 주의

툴에서는, 연주하고 있는 음악의 지연 한 메아리를 최대 4 개(살)까지 생성 한다.

Helper.cpp 에는, DirectMusic 를 설정하기 위한 유용한 함수가 포함되어 있다. 이러한 함수는, Main.cpp 로부터 불려 간다. Echotool.cpp 에는, 툴 코드가 포함되어 있다.

상세한 것에 대하여는, 「튜토리얼 2 : 툴의 사용법」을 참조할것.


MusicLines 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 샘플」을 참조할것.

[C++]

설명

MusicLines 샘플에서는, 인터랙티브 뮤직 요소를 간단한 게임에서 설명하고 있다. 특히, 음악에 의해 게임 요소가 구동되는 모습이 나타나고 있다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\Dmusic\Src\MusicLines

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DMusic\Bin

유저즈 가이드

표시되는 다이알로그 박스로, 윈도우 모드와 풀 스크린 모드, 난이도, 및 플레이어를 인간과 컴퓨터의 어느 쪽으로 하는지를 선택한다. 2 명이 플레이 하는 경우, 1 명은 방향 키를 사용해, 이제(벌써) 1 명은 AZSW 키를 사용한다. 방향 키를 눌러, 이동을 시작 한다.

게임의 목적은, 이동한 후에 남는 라인에 상대의 플레이어를 충돌시키는 것이다.

방향 키, 또는 AZSW 키를 눌러, 선의 방향을 변경한다. 플레이의 현재 상태에 응해 메인의 음악이 어떻게 변화하는지, 충돌등의 이벤트를 알리기 위해서(때문에) 모티프가 어떻게 사용되고 있는지, 및 선의 스피드가 음악에 의해 실제로 어떻게 제어되고 있을까에 주의 해야 한다.

컴퓨터에 이겼을 경우, 선을 계속 늘리는지 , 일부러 충돌해 게임을 종료할 수가 있다. 한번 더 플레이 하려면 , Space 키를 누른다. 종료하려면 , Alt 키를 누르면서 F4 키를 누른다.

프로그래밍 위에의 주의

음악 논리는 Mlmusic.cpp 에 있어, 파일중에 상세하게 코멘트되고 있다.


PlayMotif 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 샘플」을 참조할것.

[C++]

설명

이 샘플 어플리케이션에서는, 프라이머리 세그먼트(segment)상에서 모티프를 어떻게 연주할 수 있는지를 나타낸다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\Dmusic\Src\PlayMotf

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DMusic\Bin

유저즈 가이드

버튼을 클릭 하면, 메인에서 연주되고 있는 프라이머리 세그먼트(segment)상에서, 다양한 세컨드리 세그먼트(segment) (모티프)가 연주된다. 어플리케이션을 종료하려면 ,[Close] 를 클릭한다.

프로그래밍 위에의 주의

프로그램은, DirectX SDK 셋업으로 설정된 레지스트리 키를 사용해, 미디어 파일 패스를 검색한다.


PlayPrimary 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectMusic Visual Basic 샘플」을 참조할것.

[C++]

설명

PlayPrimary 샘플에서는, 오쏘링 된 뮤직 섹션상에서 프라이머리 세그먼트(segment)를 연주하는 방법을 나타낸다.

패스

소스 파일 :(SDK 루트) \Samples\Multimedia\Dmusic\Src\PlayPri

실행 가능 파일 :(SDK 루트) \Samples\Multimedia\DMusic\Bin

유저즈 가이드

[Close] 를 클릭 하면, 프로그램이 종료한다.

프로그래밍 위에의 주의

프로그램은, DirectX SDK 셋업으로 설정된 레지스트리 키를 사용해, 미디어 파일 패스를 검색한다.


DirectMusic Visual Basic 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectMusic C/C++ 샘플」을 참조할것.

[Visual Basic]

다음의 샘플 어플리케이션에는, DirectMusic® 어플리케이션 프로그래밍 인터페이스의 사용법과 기능이 나타나고 있다.

  • ClubMet 샘플
  • DLSEffects 샘플
  • DMDrums 샘플
  • PlayDMusic 샘플


ClubMet 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectMusic C/C++ 샘플」을 참조할것.

[Visual Basic]

설명

ClubMet 샘플 어플리케이션에서는, DirectMusic 가 입력 이벤트에 대해서 어떻게 응답하는지를 나타낸다.

패스

소스 파일 : (SDK 루트) \Samples\Multimedia\VBSamples\Dmusic\Src\ClubMet

실행 가능 파일 : (SDK 루트) \Samples\Multimedia\VBSamples\DMusic\Bin\ClubMet.exe

유저즈 가이드

요일과 버튼을 클릭한다. 선택한 요일에 응해 스타일이 변화하는 모습에 주의 해야 한다. 또, 버튼의 클릭에 응해 모티프가 연주되는 모습에도 주의한다.

프로그래밍 위에의 주의

이 샘플은,DirectMusicComposer 에 의해, 세그먼트(segment)와 이행부가 스타일로부터 어떻게 생성 되는지를 나타내고 있다.


DLSEffects 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectMusic C/C++ 샘플」을 참조할것.

[Visual Basic]

설명

DLSEffects 샘플 어플리케이션에서는, 음악 이외의 사운드 이펙트에 대해서, 어플리케이션이 DirectMusic 와 DLS 파일을 어떻게 사용하는지를 나타낸다.

패스

소스 파일 : (SDK 루트) \Samples\Multimedia\VBSamples\Dmusic\Src\DLSEffects

실행 가능 파일 : (SDK 루트) \Samples\Multimedia\VBSamples\DMusic\Bin\DLSEffects.exe

유저즈 가이드

[C3] 로부터 [C10] 까지의 라벨이 붙은 버튼을 클릭 하면, 음성의 이펙트가 연주된다. [On] 를 클릭 하면 고동음의 이펙트가 연속해 연주되어[Note] 및 [Pitch Bend] 슬라이더를 사용하면(자) 피치가 변화한다. 우측의 슬라이더를 사용해, 음표의 velocity (볼륨)를 설정한다. velocity의 변경은, 변경 후에 시작 된 음표에만 적용된다.

프로그래밍 위에의 주의

이 어플리케이션은, 다운로더블 사운드를 사운드 이펙트에 사용하는 방법과 MIDI 음표의 송신 방법을 나타내고 있다.

DLS 음색은 Boids.dls 로부터 취득하고 있다. 콜렉션에는,"Vocals" 라고 하는 1 개의 음색만이 포함되어 있다. 다만, 음색이 기초를 두고 있는 웨이브 샘플은,"리젼" 또는 음표의 범위에 의해 차이가 난다. 예를 들어, 최초의 스피치의 사운드는, C3 ~ B3 의 사이의 음표가 송신되었을 때에 사용된다. 스피치의 사운드는, 리젼으로 가장 낮은 음표 때에만, 올바른 피치로 연주된다.

Heartbeat 의 샘플은, B7 ~ B8 의 범위에서 유효하다. 이것은 음성의 샘플은 아니기 때문에, 피치를 적당히 변화시킬 수가 있다. 이 처리는, 슬라이더 설정으로 결정한, 범위내의 다양한 음표로 연주하는 것으로 실행된다.

Heartbeat 는, DLS 콜렉션으로 유일한, 루프 한 웨이브에 근거하는 샘플이기도 하다. 따라서, 음표의 최대의 계속 시간까지 연속해 연주할 수가 있다. 다른 샘플은, 송신된 음표의 계속 시간에 관계없이, 한 번 밖에 연주되지 않는다.


DMDrums 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectMusic C/C++ 샘플」을 참조할것.

[Visual Basic]

설명

DMDrums 샘플 어플리케이션에서는, 마스터 그루브 레벨, 밴드, 볼륨, 및 템포를 변경해, 어플리케이션이 어떻게 음악을 변경하는지를 나타낸다. 유저의 입력에 응해, 모티프를 변주 하는 방법도 나타나고 있다.

패스

소스 파일 : (SDK 루트) \Samples\Multimedia\VBSamples\Dmusic\Src\DMDrums

실행 가능 파일 : (SDK 루트) \Samples\Multimedia\VBSamples\DMusic\Bin\Dmdrums.exe

유저즈 가이드

초록 및 빨강의 버튼을 클릭 하면, 음악이 시작 또는 정지한다. 위쪽의 리스트 박스로 음악의 종류를 선택해, 아래 쪽의 리스트 박스로 밴드를 선택한다. 오름새 화살표와 하향 화살표의 버튼으로, 템포와 볼륨을 조정한다. 드럼 버튼을 클릭 하면, 드럼의 모티프가 연주된다.

프로그래밍 위에의 주의

음악의 "스타일" 은, 실제로는 마스터 그루브 레벨로 결정된다. 이것에 의해, 세그먼트(segment)에 관련지을 수 있었던 스타일 오브젝트로부터, 다른 패턴이 선택된다.

각 드럼 버튼으로, 각각 다른 모티프가 연주된다. 버튼에 관련지을 수 있고 있는 음색은, 모티프로 할당할 수 있다.


PlayDMusic 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectMusic C/C++ 샘플」을 참조할것.

[Visual Basic]

설명

PlayDMusic 샘플에서는, 오쏘링 된 세그먼트(segment)와 스탠다드 MIDI 파일을 로드해 연주하는 방법을 나타낸다.

패스

소스 파일 : (SDK 루트) \Samples\Multimedia\VBSamples\Dmusic\Src\Play

실행 가능 파일 : (SDK 루트) \Samples\Multimedia\VBSamples\DMusic\Bin\Playdmusic.exe

유저즈 가이드

[File] 메뉴의 [Open] 를 클릭하는지, 아이콘을 클릭해, 세그먼트(segment) 또는 MIDI 파일을 로드한다. 각각의 버튼을 사용해, 세그먼트(segment)를 연주, 일시정지, 또는 정지한다. 볼륨을 조정하려면 , 화살표를 클릭한다.

[Option] 메뉴의 [Show] 를 클릭해, 표시하는 시간의 단위를, 초 또는 뮤직크타임틱의 어느 쪽으로 하는지 선택한다.

밴드를 다른 DLS 콜렉션에 접속할 수가 있다. 또,[File] 메뉴로부터, GMReset 커멘드를 실행할 수도 있다.

프로그래밍 위에의 주의

프로그램에서는, 2 번째의 퍼포먼스를 사용해, 세그먼트(segment)를 연주하기 전에 그 정보를 취득하고 있다.


DirectPlay

DirectPlay® 어플리케이션 프로그래밍 인터페이스 (API)는, DirectX® 의 컴퍼넌트이며, 멀티 플레이어 게임등의 네트워크 어플리케이션의 기술을 가능하게 한다.

DirectPlay 에 관한 정보는, 다음의 주제를 참조할것.

  • DirectPlay 에 대해
  • DirectPlay 를 사용하는 이유
  • DirectPlay 아키텍쳐
  • DirectPlay 의 요점
  • DirectPlay 튜토리얼
  • DirectPlay 레퍼런스
  • DirectPlay 의 툴과 샘플


DirectPlay 에 대해

Microsoft Windows® 용의 Microsoft® DirectPlay® 어플리케이션 프로그래밍 인터페이스 (API)를 사용 하면, 개발자는 개별의 트랜스폴트, 프로토콜, 또는 온라인 서비스용의 코드를 기술하지 않고 , 멀티 플레이어 게임, 게임 서버, 채팅 클라이언트, 및 그 외의 네트워크 어플리케이션을 생성 할 수가 있다.

DirectPlay 는, 다음의 태스크를 위한 서비스를 제공한다.

  • 네트워크, 인터넷, 또는 도메인을 개입시켜, 컴퓨터간의 접속을 확립한다.
  • 로비를 개입시켜 통신한다. 로비에서는, 참가자가 서로 만나거나 세션을 편성하거나 할 수가 있다.
  • 세션을 생성 하거나 세션에 참가하거나 한다.
  • 세션내의 플레이어와 그룹을 관리한다.
  • 메세지의 교환에 의해, 다른 컴퓨터상에서 세션 상태를 일치시킨다.


DirectPlay 를 사용하는 이유

DirectPlay 는, 명확하게 정의된 범용적인 통신 기능을 제공한다. 개발자는, 다양한 접속 솔루션이 가져오는 차이에 대처할 필요는 없다. DirectPlay 는, 기반이 되는 다양한 접속의 이행의 복잡함을 개발자로부터 숨겨, 뛰어난 어플리케이션을 생성 하는 것에 집중할 수 있도록(듯이) 한다.

DirectPlay 어플리케이션 프로그래밍 인터페이스 (API)는, 네트워크 추상이며, 분산 오브젝트 시스템이다. 이 API 는, 추상적인 DirectPlay 네트워크의 기능을 정의한다. 모든 기능은, 실제로 기반이 되고 있는 네트워크가 그 기능을 지원 하고 있을지 어떨지에 관계없이, 어플리케이션으로부터 이용 가능하다. 기반이 되는 네트워크가 기능을 지원 하고 있지 않는 경우, DirectPlay 는 그 기능을 에뮬레이트 한다. 예로서 그룹 메시징이나 보증 메시징등이 있다.

DirectPlay 는 로비도 지원 하고 있다. 로비란, 다양한 어플리케이션의 유저가 만나거나 메세지를 교환하거나 게임 세션을 편성하거나 어플리케이션을 기동하거나 하는 장소이다. 최종 사용자에 있어, 로비의 큰 이점은, 다른 플레이어와 함께 세션을 간단하게 확립할 수 있는 것이다. 로비는 플레이어가 대전 상대를 찾아내는 장소를 제공하는 것 만이 아니다. 어플리케이션이 기동했을 때, 유저는 다음 일을 실행하지 않고 끝난다.

  • 서비스 프로바이더의 선택. 로비에 의해, 사용하는 서비스 프로바이더가 지정된다.
  • 네트워크 주소의 입력과 네트워크의 구성. 이러한 정보가 필요한 경우는, 로비에 의해 제공된다.
  • 플레이어의 이름의 입력. 로비에 의해, 플레이어가 로비에 접속하기 위해서 입력한 이름이 건네받는다.

로비의 그 외의 이점으로서 다음의 것이 있다.

  • 실행중의 세션을 추적해, 유저가 세션에 참가할 수 있도록(듯이) 한다.
  • 세션으로부터 스테이터스 메세지를 수신해, 기록 게시판상에서 다른 유저에게 진행 상황을 표시한다.
  • 토너먼트 플레이로 최종 스코아를 취득해, 플레이어 랭킹을 메인트넌스 한다.


DirectPlay 아키텍쳐

DirectPlay 의 서비스 프로바이더의 아키텍쳐는, 어플리케이션을 그것이 실행되고 있는 네트워크로부터 떼어낸다. 어플리케이션은, DirectPlay 에 네트워크의 특정의 기능, 예를 들어 대기 시간이나 대역폭을 문의해 거기에 응해 통신을 조정할 수가 있다.

다음의 그림은, DirectPlay 서비스 프로바이더의 아키텍쳐를 나타내고 있다.

DirectPlay 를 사용하기 위한 최초의 스텝은, 사용하는 서비스 프로바이더를 선택하는 것이다. 서비스 프로바이더에 의해, 통신에 이용하는 네트워크 또는 프로토콜의 종류가 정해진다. 프로토콜은, 인터넷상의 TCP/IP , IPX 근거리 통신망, 또 2 개의 컴퓨터간의 시리얼 접속까지, 다방면에 이른다.

어플리케이션은, 서비스 프로바이더를 사용해, 네트워크 위에의 있는 포인트에의 접속을 확립한다. 접속을 확립하려면 , 유저가 추가 정보를 제공해야 하는 경우도 있다. 또는, 어플리케이션으로 접속 파라미터를 지정할 수도 있다.

DirectPlay 아키텍쳐에 관한 한층 더 상세한 정보는, 다음의 주제를 참조할것.

  • 통신 모델
  • 로비
  • 서비스 프로바이더
  • 시큐러티
  • DirectPlay 인터페이스의 개요 [C++]
  • DirectPlay 클래스의 개요 [Visual Basic]


통신 모델

여기에서는, 네트워크 게임 또는 같은 어플리케이션에 있어서의 통신과 공통 상태의 유지에 관한 일반적인 원칙에 대해 설명한다. 어플리케이션으로 DirectPlay 를 사용 하면, 이하에 설명하는 몇개의 모델을 이용해, 어플리케이션 자체의 데이터를 유지할 수가 있다.

네트워크에 대응한 멀티 플레이어 게임을 기술할 때의 주요한 관심사는, 세션에 참가하고 있는 모든 컴퓨터에 어떻게 해 상태 정보를 전하는가 하는 것이다. 세션 상태는, 유저가 자신의 컴퓨터상에서 보는 것과 유저가 실행할 수 있는 것을 정의한다. 일반적으로, 세션 상태는 2 개의 것에 의해 구성된다. 즉, 「환경」이라고, 개별의 유저 또는 플레이어이다.

주 : "유저" 와 "플레이어" 는 일반적으로는 같은 의미로 사용되는 것이 많지만, 플레이어는 DirectPlay 어플리케이션의 논리 개념이기도 한 것을 기억해 두는 것이 중요하다. 어플리케이션에서는, 2 명 이상의 플레이어에 의해 표현되는, 어느 유저도 허용 한다.

「환경」은, 플레이어가 대화하거나 조작하거나 하는 오브젝트에 의해 구성된다. 예를 들어, 지하 감옥, 레이스 코스, 일련의 채팅 메세지 등이다. 또, 「환경」에는, 컴퓨터에 의해 제어되는 플레이어가 포함되는 경우도 있다.

「환경」내에서는, 각 플레이어가 플레이어의 현재의 프로퍼티를 나타내는 상태를 보관 유지한다. 이러한 프로퍼티에는, 위치, 속도, 에너지, 방어용 기구등이 포함된다.

플레이어가 세션에 최초로 참가 하면나무는, 「환경」을 포함한 세션의 현재 상태와 다른 플레이어 상태를 다운로드할 필요가 있다.

유저가 실행하는 동작과 게임의 자연스러운 진행에 의해, 세션 상태가 변화한다. 이러한 변화가 발생했을 경우, 그 변화를 메세지에 의해 세션에 참가하고 있는 것 외의 컴퓨터에게 전할 필요가 있다. 세션 상태를 갱신하는 방법은 얼마든지 있지만, 이러한 방법은 모두 컴퓨터간에서의 메세지의 송신에 의존하고 있다.

세션으로 상태 데이터를 유지하기 위한 방법은, 주로 2 개 있다. 1 개(살)은,피어 투 피어로 불리는 방법이다. 피어 투 피어 세션에서는, 세션에 참가하고 있는 모든 컴퓨터가 「환경」 및 모든 플레이어에 대한 완전한 상태를 보관 유지한다. 어느 컴퓨터상에서 상태의 변경이 발생하면(자), 그것을 세션에 참가하는 것 외의 모든 컴퓨터에게 전할 필요가 있다. 1 대의 컴퓨터가 상태 데이터를 관리하는 것은 아니다.

세션 상태를 유지하기 위한 이제(벌써) 1 개의 방법은,클라이언트/서버로 불리는 것이다. 클라이언트/서버 세션에서는, 1 대의 컴퓨터가 서버로서 지정되어 그 컴퓨터가 게임의 완전한 상태를 유지해, 충돌을 해결한다. 세션내외의 모든 컴퓨터는 클라이언트가 된다. 각 클라이언트는, 그 컴퓨터에 관련하는 정보만을 보관 유지해, 그 정보를 서버로부터 받는다. 어느 컴퓨터가 무엇인가를 변경했을 때는, 그 변경을 서버에게 전한다. 계속되어 서버는, 그 변경을 전해야 할 클라이언트를 판단한다.

DirectPlay 를 사용 하면, 피어 투 피어 어플리케이션과 클라이언트/서버 어플리케이션의 양쪽 모두를 생성 및 관리할 수가 있다. DirectPlay 는, 네트워크에 대응한 멀티 플레이어 어플리케이션을 기술하기 위해서 필요한 툴을 모두 제공한다. 이것을 실현하기 위해서(때문에), DirectPlay 는, 플레이어를 관리해, 플레이어 사이에 메세지를 송신해, 모든 컴퓨터간에 상태를 자동적으로 전달하기 위한 서비스를 제공한다.

이하의 주제에서는, DirectPlay 세션에 있어서의 2 개의 통신 모델에 대해 설명한다.

  • 피어 투 피어 세션
  • 클라이언트/서버 세션


피어 투 피어 세션

피어 투 피어 세션에서는, 1 대의 컴퓨터가 네임서버-로 지정된다. 이 컴퓨터는, 열거 요구에 응답해, 세션에 참가하는 컴퓨터를 조정해, 세션에 참가한 새로운 컴퓨터에 세션 상태를 다운로드해, 플레이어 및 그룹이 생성 될 때마다 ID 번호를 생성한다. 그러나 그 이전에, 네임서버-는 세션에 있어서의 1 개의 피어이며, 다른 모든 피어와 같은 어플리케이션을 실행한다. 메세지는 네임서버-를 경유하지 않는다. 또, 네임서버-는 모든 시스템 메세지를 생성하는 것은 아니다.

DirectPlay 는, 네임서버-기능을 자동적으로 실행한다. 이 네임서버-기능은, 어떠한 방법에서도 어플리케이션에 공개되지 않는다. 네임서버-위에서 실행되는 DirectPlay 어플리케이션의 인스턴스는, 세션의 호스트이기도 하다. 세션 기술의 데이터를 변경할 수 있는 것은, 호스트 인스턴스 뿐이다. 세션내의 각 피어 어플리케이션은, 세션에 참가하고 있는 플레이어와 그룹의 완전한 리스트에 액세스 할 수 있어 세션내외의 플레이어와의 사이에 메세지를 송수신 하거나 세션내외의 그룹에 메세지를 송신하거나 할 수가 있다. 상세한 것에 대하여는, 「세션 관리」를 참조할것.

세션의 네트워크 주소는, 네임서버-의 네트워크 주소에 대응한다. 컴퓨터는, 세션에 참가할 필요가 있는 경우, 참가 요구를 네임서버-에 보낸다. 네임서버-는 이것에 응답해, 세션 상태를 새로운 컴퓨터에 다운로드한다. 네임서버-가 세션을 떨어지면(자), 새로운 컴퓨터가 네임서버-로서 선택된다. 네임서버-가 이행 하면, 세션의 네트워크 주소도 변경된다.

다음의 그림은, 세션에의 참가를 나타내고 있다. 컴퓨터가 세션에 참가하려면 , 세션의 네임서버-에 참가 요구를 보낼 필요가 있다.

피어 투 피어 세션에서는, 모든 컴퓨터에 있어서의 모든 상태 변경 (플레이어의 이동등)을, 세션내외의 모든 컴퓨터에 브로드캐스트 할 필요가 있다. 컴퓨터가 전화 회선을 사용해 접속되고 있는 경우는 특히 그렇지만, 컴퓨터를 수신할 수 있는 데이터의 양에는 제한이 있기 (위해)때문에, 어플리케이션에서는 참가할 수 있는 컴퓨터의 수를 제한해야 한다. 데이터 변경의 양과 빈도를 최소한으로 억제하면(자), 퍼포먼스를 저하시키지 않고 세션에 참가할 수 있는 컴퓨터의 수를 늘릴 수가 있다.

피어 투 피어의 DirectPlay 세션에 참가하고 있는 컴퓨터는, 서로 직접 통신한다. 즉, 메세지는 중간의 컴퓨터를 경유해 목적지에 송신되는 것은 아니다 (다만, 라우터를 경유하는 경우가 있다). 같은 메세지를 복수의 컴퓨터에 송신할 필요가 있는 경우, DirectPlay 는 서비스 프로바이더내의 임의의 멀티 캐스트 기능의 사용을 시도한다. 멀티 캐스트가 지원되어 있지 않은 경우는, 개별의 uni-cast 메세지가 목적지의 각 컴퓨터에 송신된다.

다음의 그림은, 멀티 캐스트를 사용하지 않는 경우의 그룹 메시징을 나타내고 있다. 메세지를 브로드캐스트 하기 위해서, 개별의 메세지가 각 머신에 송신된다.

그룹 메시징은, 4 명 이상이 참가하는 세션에서는 효율을 저하시키는 원인이 되는 경우가 있다. 세션에 멀티 캐스트 서버를 추가 하면, 효율의 저하를 완화할 수가 있다. 멀티 캐스트 서버는, 단일의 메세지를 복수의 목적지에 전송 하는 컴퓨터이다. 세션에 참가하고 있는 것 외의 모든 컴퓨터에 메세지를 브로드캐스트 하는 컴퓨터는, 1 개의 메세지를 멀티 캐스트 서버에 송신한다. 이것에 대해, 멀티 캐스트 서버는, 각 메세지를 다른 모든 컴퓨터에 송신한다. 이 방법은, 다른 컴퓨터가 저속 링크 (전화 회선등)로 네트워크에 접속하고 있어, 서버가 고속 링크 (T1 회선등)로 접속하고 있으면, 보다 효율이 높아진다.

다음의 그림은, 멀티 캐스트 서버를 사용한 그룹 메시징을 나타내고 있다. 플레이어대 플레이어의 메세지는, 목적지에 직접 송신된다. 그룹 메세지는 멀티 캐스트 서버에 송신되어 멀티 캐스트 서버가 그 메세지를 모든 목적지 머신에 전송 한다.

DirectPlay 는, 세션에서의 멀티 캐스트 서버의 생성을 지원 하고 있다. 네임서버-가 충분히 고속의 링크로 접속하고 있는 경우는, 그 네임서버-를 세션에 대한 멀티 캐스트 서버라고 해도 기능시키는 것이 가능하다. 멀티 캐스트 서버를 세션에 추가해도, 그룹 메세지 (브로드캐스트를 포함한다)의 루팅 방법이 바뀌는 것만으로 있어, 어플리케이션의 동작은 변함없다. 플레이어대 플레이어의 uni-cast 메세지는, 계속 목적지에 직접 송신된다.


클라이언트/서버 세션

DirectPlay 의 클라이언트/서버 세션에서는, 1 대의 컴퓨터가 서버로서 지정된다. 이 컴퓨터는, 피어 투 피어의 네임서버-와 같이, 열거 요구에 응답하거나 세션에 참가하는 컴퓨터를 제어하거나 세션 상태를 새롭게 세션에 참가한 컴퓨터에 다운로드하거나 플레이어와 그룹이 생성 될 때마다 ID 번호를 생성하거나 한다. 클라이언트/서버 모델이 피어 투 피어 모델과 다른 점은, 세션에 있어서의 모든 메세지가 서버를 경유해 루팅 되는 것이다.

서버 컴퓨터는, 어플리케이션의 특별한 버젼을 실행한다. 이것을 어플리케이션 서버라고 말한다. 어플리케이션 서버는, 게임의 마스터 상태를 유지해, 클라이언트 컴퓨터가 실행한 액션에 응해 그 상태를 갱신해, 관련하는 이벤트를 개별의 클라이언트에 통지할 수가 있다. 어플리케이션 서버는, 서버 플레이어라고 하는 특별한 플레이어를 생성 한다. 모든 클라이언트는, 서버 플레이어에게 메세지를 직접 송신해, 서버 플레이어로부터 메세지를 직접 수신할 수가 있다. 서버 플레이어는, 메세지를 수신 하면, 다른 클라이언트 플레이어에게 메세지를 송신해, 상태의 변화를 통지할 수가 있다.

다음의 그림은, 클라이언트/서버의 통신을 나타내고 있다. 각 컴퓨터는, 서버라는 봐 직접 통신한다. 서버는 메세지를 다른 클라이언트에 전송 할 수가 있다.

클라이언트 컴퓨터는, 어플리케이션의 클라이언트 버젼을 실행한다. 이 버젼은, 로컬인 상태를 유지해, 그 상태를 서버로부터의 메세지에 응해 갱신해, 로컬인 액션이 발생했을 경우에 서버에 메세지를 송신할 수가 있다.

클라이언트/서버는 2 개의 방법으로 이행 할 수 있다. 1 개(살)은, 피어 투 피어와 클라이언트/서버의 혼합이다. 이 경우, 각 클라이언트 어플리케이션은, 스스로가 이용 가능한 플레이어와 그룹 (서버 플레이어를 포함한다)의 완전한 리스트를 보관 유지한다. 클라이언트 플레이어는, 세션에 참가하고 있는 임의의 플레이어에게 메세지를 직접 송신할 수가 있다. 각 플레이어 또는 그룹은, 그 자체에 관한 데이터 (이름이나 리모트 데이터등)를 보관 유지할 수가 있다. 이 데이터는, 변경이 있을 때마다, 모든 컴퓨터상에서 갱신된다. 피어 투 피어 상태 전달의 이점을 모두 활용 가능할 뿐만 아니라, 서버 플레이어도 이용할 수 있다. 그러나, 플레이어대 플레이어의 데이터의 전달을 제어할 수 없다. 플레이어와 그룹이 생성 및 파기되거나 또는 그러한 데이터가 변경 되거나 하는 빈도에 따라서는, 클라이언트 컴퓨터가 착신 메세지로 과부하가 되는 경우가 있다. 이 타입의 세션은, 플레이어가 약 16 명 이상이 되면(자) 대응이 곤란하다. 이 세션은, 서버 플레이어가 존재해, 모든 메세지가 서버를 경유해 루팅 되어 서버 플레이어가 서버를 통과하는 모든 메세지의 카피를 수신 하면 말하는 점을 제외하면, 피어 투 피어 세션과 그만큼 큰 차이는 없다.

이제(벌써) 1 개의 방법은, 진정한 클라이언트/서버 모드이다. 각 클라이언트 어플리케이션은 서버 플레이어와 세션내의 자신의 로컬 플레이어만을 참조한다. 클라이언트 플레이어는, 서버 플레이어에게만 메세지를 송신할 수가 있어 서버 플레이어로부터의 메세지만을 수신할 수가 있다. 어플리케이션 서버는, 모든 클라이언트 위에의 모든 플레이어를 참조할것이 생긴다. 서버는 클라이언트로부터 메세지를 수신 하면, 어플리케이션의 마스터 상태를 갱신하는 방법과 그 갱신을 클라이언트에 통지하는 방법을 판단한다. 이 방법에서는, 클라이언트 어플리케이션은 플레이어와 각 플레이어에게 관련하는 데이터의 리스트를 유지할 필요가 있다.

다음의 그림은, DirectPlay 클라이언트/서버 세션의 내용을 논리적으로 가리킨 것이다.

피어 투 피어 세션의 경우와 같이, 세션의 네트워크 주소는 서버의 네트워크 주소에 대응한다. 컴퓨터가 세션에 참가하려면 , 참가 요구를 서버에 송신한다. 이것에 대해, 서버는 세션 상태를 새로운 컴퓨터에 다운로드한다. 서버가 세션을 떨어지면(자), 세션이 종료한다.

모든 메세지가 서버를 경유해 루팅 되기 (위해)때문에, 서버는 자동적으로 멀티 캐스트 서버로서 기능하게 된다.


로비

DirectPlay 의 로비 서버 는, (최악이어도) DirectPlay 어플리케이션의 진행중의 세션과 접속하고 있는 유저를 추적하기 위한 , 네트워크 위에의 공통의 장소이다. 유저는 로비 서버를 경유해 흥미가 있는 장소를 찾아내거나 다른 유저라고 채팅하거나세션에 참가하거나 플레이어의그룹을 생성 해 새로운 세션을 시작 하거나 할 수가 있다.

로비 서버의 큰 이점은, 그것이 중앙의 기존의 위치로서 기능해, 거기서 유저가 세션을 검색하거나 대화 상대의 유저를 찾아내거나 할 수 있다고 하는 것이다. 로비 서버는 다양한 플레이어 및 세션의 네트워크 주소를 모두 관리해, 유저의 컴퓨터상에서 어플리케이션을 자동적으로 기동해, 그것을 유저의 개재없이 적절한 네트워크 주소에 접속할 수가 있다. 세션, 플레이어, 및 네트워크 주소의 관리는, 인터넷상에서는 특히 유효하다.

로비 서버는, 다수의 서비스를 유저에게 제공하도록(듯이) 확장할 수가 있다. 예를 들어, 토너먼트, 개별의 스코아 추적, 하이 스코아 리스트, 퍼스널 프로파일, 아바타(Avatar) (유저를 나타내는 그래피컬 요소), 게시판, 뉴스, 회원의 인증, 소프트웨어의 갱신등의 서비스를 제공할 수가 있다.

로비 대응 어플리케이션은, 로비 서버와 함께 기능하도록(듯이) 특별히 설계된 어플리케이션이다. 유저가 이용하는 로비에는 2 개의 종류가 있다. 즉, 외부 로비와 내부 로비이다.

외부 로비는, 로비 서버 및 로비 서버에 접속하고 있는 것 외의 유저와 교환하는 것을 유일한 목적으로 한 클라이언트 어플리케이션이다. 로비 클라이언트는, 어플리케이션 세션을 시작 하거나 어플리케이션 세션에 참가하거나 할 경우에, 어플리케이션을 독립한 프로세스로 기동해, 세션에의 접속을 확립하기 위해서 필요한 정보를 모두 제공한다. 외부 로비의 기동에 대한 지원을 DirectPlay 어플리케이션에 추가하는 것은 간단하다. 상세한 것에 대하여는, 「외부 로비에 의한 시작의 지원」으로 설명하고 있다.

내부 로비는, 로비의 유저 인터페이스이며, 어플리케이션 자체에 통합되고 있다. 내부 로비는 이행 하는 것이 어렵다. 이것은, 어플리케이션으로 게임에 대한 유저 인터페이스 뿐만이 아니라, 로비에 대한 유저 인터페이스도 이행 해야 하기 때문에이다. 그러나, 어플리케이션의 테마로 응해 로비를 커스터마이즈 할 수 있다고 하는 이점이 있다.

DirectPlay 로비의 아키텍쳐는, 모든 어플리케이션 (외부 로비의 클라이언트나, 로비 클라이언트가 짜넣어진 어플리케이션을 포함한다)이 DirectPlay 호환의 로비 서버에 접속하기 위해서 사용하는 클라이언트 API 로 구성된다. 이 아키텍쳐는, 로비 프로바이더의 인터페이스를 개입시켜 실현되고 있다. 로비 프로바이더는, 서비스 프로바이더와 같은 기능을 가져, 로비 서버와의 교환을 추상화 한다. 로비 서버 어플리케이션의 생성자는, 클라이언트 컴퓨터상에 상주하는 로비 프로바이더를 기술할 필요가 있다. 어플리케이션이 표준의 DirectPlay 메소드를 호출하면, 로비 프로바이더의 동적 링크 라이브러리 (DLL)가, 로비 서버 소프트웨어와 통신하는 것으로 이러한 메소드를 지원 한다.

다음의 그림은, DirectPlay 로비의 아키텍쳐를 나타내고 있다. 다른 로비 클라이언트의 어플리케이션이 DirectPlay API 를 개입시켜, 같은 로비 서버에 접속할 수가 있다.

마지막으로, 로비 서버는 현재 접속하고 있는 모든 유저를 추적해, 그것들을 그룹화 해 관리해, 어플리케이션 세션의 기동을 동기 시킬 필요가 있다.

DirectPlay API 는, 모든 로비 서버에 대한 공통 레벨의 기능을 정의한다. 임의의 범용 로비 클라이언트 어플리케이션이 임의의 범용 로비 서버에 접속해, DirectPlay API 와 로비 프로바이더의 아키텍쳐를 개입시켜 모두 기능할 수가 있다. 어플리케이션은, 메세지에 대응해 변경 가능한 프로퍼티를 정의하는 것으로써, 기본적인 기능을 확장할 수가 있다. 특정의 로비 서버와 함께 기능하도록(듯이) 설계된 로비 클라이언트는, DirectPlay API 로 정의되어 있지 않은 확장 기능을 이행 할 수가 있다.


서비스 프로바이더

DirectPlay 오브젝트는, 세션, 플레이어, 및 그룹 관리, 데이터의 관리 및 전달, 네트워크 위에의 다른 플레이어를 검색하기 위한 로비 서비스등을 (위해)때문에의 공통의 인터페이스이다.

서비스 프로바이더는, DirectPlay의 요구에 응해, 네트워크에 고유의 통신 서비스를 공급한다. 서비스 프로바이더는, DirectPlay 와 기존의 트랜스폴트 (Windows Sockets 등)의 사이의 단순한 계층이 되는 일도, 온라인 서비스 위에의 특별한 리소스 (멀티 캐스트 서버, 품질이 강화된 서비스, 청구서 송부 서비스등)를 이용할 수도 있다.

Microsoft 는, DirectPlay 에 4 개의 범용 서비스 프로바이더를 준비해 있다. 즉,모뎀 투 모뎀 (TAPI),시리얼 링크,TCP/IP (Windows Sockets 를 사용), 및 IPX (이쪽도 Windows Sockets 를 사용)의 4 개이다. 온라인 서비스와 네트워크 오퍼레이터는, 다른 서비스 프로바이더를 제공할 수가 있다.

DirectPlay 는, 통신 링크를 확립하기 위해서 필요한 고유의 태스크와 복잡함을, 서비스 프로바이더의 이행내에 은폐 한다. DirectPlay 를 사용하는 어플리케이션은, DirectPlay 에 의해 제공되는 가상 네트워크의 퍼포먼스와 능력만을 배려하면 좋다. 모뎀, 네트워크 카드, 온라인 서비스의 머지않아가 미디어를 제공하고 있는 것을 파악할 필요는 없다.

DirectPlay 는, 유저의 시스템에 인스톨 되고 있는 임의의 DirectPlay 프로바이더에 동적으로 바인드 한다. 어플리케이션은, DirectPlay 오브젝트와 교환한다. DirectPlay 오브젝트는, 이용 가능한 DirectPlay 서비스 프로바이더의 어느쪽이든교환한다. 선택된 서비스 프로바이더는, 트랜스폴트, 프로토콜, 및 그 외의 네트워크 리소스와 교환한다.


시큐러티

DirectPlay 의 시큐러티 기능을 이용하는 것으로, 서버상에서 실행되는 어플리케이션은,시큐어 세션을 생성 할 수가 있다. DirectPlay 는, Windows 위에의 Security Support Provider Interface (SSPI)를 개입시켜 시큐러티를 이행 한다. 시큐어 세션으로 DirectPlay 에 의해 지원 되는 주된 기능은 다음과 같다.

  • 유저의 신원을 확인하기 위한 인증. 유저를 인증 하면, 디지털 서명을 첨부하는지, 또는 메세지를 암호화하는 것으로써, 클라이언트와 서버의 사이의 통신을 안전하게 실행할 수가 있다.
  • 송신측의 신원을 확인하기 위한 , 디지털 서명 첨부의시스템 메세지 .
  • 중요한 시스템 메세지의 암호화.

다음의 그림은, DirectPlay 의 시큐러티의 아키텍쳐를 나타내고 있다.

범례

SSPI
Security Support Provider Interface
CAPI
CryptoAPI
MS RSA Base CP
Microsoft RSA Base Cryptographic Provider

DirectPlay 는, Windows Cryptography Application Programming Interface (CAPI)를 개입시켜, 메세지의 암호화를 지원 한다. CAPI 는 SSPI 를 닮은 표준 인터페이스로, 소프트웨어가 Windows operating system아래에서 다양한 암호화 패키지에 액세스 할 수 있도록(듯이) 한다. 이 아키텍쳐에 의해, DirectPlay 어플리케이션은, 법적으로 허가되고 있는 필요한 레벨의 암호화 레벨 (40 비트, 128 비트등)을 제공하는 암호화 패키지를 적용하는 것이 가능하게 된다.

DirectPlay 의 암호화 서비스에 대한 디폴트의 CryptoAPI (CAPI) 프로바이더는, Microsoft RSA Base Cryptographic Provider 버젼 1.0 이다. 이 디폴트 CAPI 프로바이더의 타입은, PROV_RSA_FULL 이다. 디폴트의 암호화 알고리즘은, CALG_RC4 스트림사이파이다. 이 프로바이더는, 32 비트의 Microsoft Windows operating system에 포함되어 있다.

DirectPlay 는, Windows 위에의 SSPI (Security Support Provider Interface)를 개입시켜, 유저와 메세지의 인증 (디지털 서명)을 제공한다. 이것은, 소프트웨어가 Windows OS 아래에서 다양한 시큐러티 패키지에 액세스 하는 것을 가능하게 하는 표준적인 인터페이스이다. 시큐러티 패키지란, 클라이언트의 신원을 확인해, 디지털 서명등의 시큐러티 서비스도 제공하는, 클라이언트와 서버의 사이의 프로토콜의 이행이다. DirectPlay 가 사용하는 디폴트의 시큐러티 패키지는, NTLM Security Support Provider (NTLMSSP)로 불린다.

이 시큐러티 패키지는, NTLM 의 인증 프로토콜에 근거하고 있다. NTLM 는, 비밀을 공유하는, 유저의 챌린지/리스폰스 인증 프로토콜이다. 이 프로토콜은, 서버의 도메인 또는 현재의 도메인의 도메인 콘트롤러에 의해 신뢰되는 도메인의 도메인 콘트롤러에 대한 파스스르 인증을 지원 하고 있다. 이 프로토콜에서는, 패스워드가 네트워크상에 내보내지는 것이 없기 때문에, 높은 시큐러티가 실현된다. NTLMSSP 는 Windows operating system에 부속되어 있다.

시큐어 세션의 시작 방법, 시큐러티 패키지의 지정 방법, 파이어 월(fire wall)에 대한 지원의 추가 방법등의 상세한 것에 대하여는, 「시큐러티와 인증」을 참조할것.


DirectPlay 인터페이스의 개요

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

DirectPlay 는, 컴퍼넌트 오브젝트 모델 (COM)에 근거한 오브젝트와 인터페이스에 의해 구성된다. 개요에 대해서는, 「컴퍼넌트 오브젝트 모델」을 참조할것.

이 섹션에서는, DirectPlay COM 인터페이스의 개요에 대해, 다음의 주제로 나누어 기술한다.

  • Unicode 인터페이스대 ANSI 인터페이스
  • IDirectPlay4 인터페이스
  • IDirectPlayLobby3 인터페이스


Unicode 인터페이스대 ANSI 인터페이스

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

DirectPlay 는, Unicode 캐릭터 라인과 ANSI 캐릭터 라인의 양쪽 모두를 지원 한다. 이것을 실현하기 위해서(때문에), 캐릭터 라인 포인터를, 구조 체내에서 Unicode 캐릭터 라인 포인터 (LPWSTR) 및 ANSI 캐릭터 라인 포인터 (LPSTR) 의 편성으로서 정의하고 있다. 2 개의 캐릭터 라인 포인터는 다른 이름을 가진다. 보통, ANSI 멤버는, 마지막에 “A”라고 하는 문자가 붙는다. 사용하는 DirectPlay 인터페이스 (Unicode 의 경우는 IDirectPlay4, ANSI 의 경우는 IDirectPlay4A) 또는 DirectPlayLobby 인터페이스 (Unicode 의 경우는 IDirectPlayLobby3, ANSI 의 경우는 IDirectPlayLobby3A)에 응해, 어플리케이션은 적절한 구조체로부터 캐릭터 라인을 읽고 쓰기해, 이제(벌써) 한편을 무시한다.


IDirectPlay4 인터페이스

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

IDirectPlay4 인터페이스는, 로비 서비스를 제공하지 않고, 요구도 하지 않는 네트워크 어플리케이션을 생성 하기 위해서 필요한 유일한 인터페이스이다.

Dplay.h 는, 이 인터페이스의 이전의 버젼을 포함하고 있다. 이것들이 포함되어 있는 것은, DirectX 의 이전의 버젼으로 기술된 어플리케이션과의 호환성을 확보하기 위해(때문에)이다.

  • IDirectPlay 는, DirectX SDK 버젼 1 및 2 로 기술된 어플리케이션을 실행하기 위해서 필요한 메소드를 포함하고 있다. 게다가 Dplay.h 는, 원의 IDirectPlay 인터페이스의 메소드에서만 사용되는 정의와 구조체를 다수 포함하고 있다. 이러한 구식의 요소를 무시하려면 , 코드 또는 컴파일러로 IDIRECTPLAY2_OR_GREATER 를 정의한다.
  • IDirectPlay2 는, DirectX 버젼 3 으로 기술된 어플리케이션을 실행하기 위해서 필요한 메소드를 포함하고 있다.
  • IDirectPlay3 는, DirectX 버젼 5.0 으로 기술된 어플리케이션을 실행하기 위해서 필요한 메소드를 포함하고 있다.

이러한 구식의 인터페이스의 어느쪽이든을 사용해 새로운 어플리케이션을 생성 하는 일도 가능하지만, 새로운 IDirectPlay4 인터페이스를 사용해, 새로운 기능을 이용하는 것을 추천 한다. IDirectPlay4 는 IDirectPlay3 를 직접 계승하고 있기 (위해)때문에,IDirectPlay3 를 사용하도록(듯이) 기술된 어플리케이션은, 수정을 더하지 않아도 IDirectPlay4 로 기능한다. 상세한 것에 대하여는, 「DirectX 의 이전의 버젼으로부터의 이행」을 참조할것.


IDirectPlayLobby3 인터페이스

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

게임 개발자는 IDirectPlayLobby3 인터페이스를 사용해, 외부 어플리케이션을 기동하거나 어플리케이션과 로비 클라이언트간의 통신을 가능하게 하거나 DirectPlay 주소를 조작하거나 할 수가 있다. 로비 세션의 개요에 대해서는, 「로비」를 참조할것. 외부 로비에 의한 기동의 검출과 로비 대응 어플리케이션의 등록에 관한 실용적인 정보에 대해서는, 「로비 대응 어플리케이션의 생성」을 참조할것.

인클루드 파일 Dplobby.h 는, COM 인터페이스의 IDirectPlayLobby 와 IDirectPlayLobby2 도 선언한다. IDirectPlayLobby 는, DirectX 버젼 1, 2, 및 3 으로 기술된 어플리케이션을 실행하기 위해서 필요한 메소드를 포함하고 있다. IDirectPlayLobby2 는, DirectX 버젼 5.0 으로 기술된 어플리케이션을 실행하기 위해서 필요한 메소드를 포함하고 있다. 이러한 인터페이스를 사용해 새로운 어플리케이션을 생성 하는 일도 가능하지만, 새로운 기능을 이용하려면 ,IDirectPlayLobby3 를 사용하는 것을 추천 한다. 상세한 것에 대하여는, 「DirectX 의 이전의 버젼으로부터의 이행」을 참조할것.


DirectPlay 클래스의 개요

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[Visual Basic]

모든 DirectPlay 어플리케이션의 중심이 되는 오브젝트는,DirectPlay4 클래스의 인스턴스이다. 이 오브젝트의 메소드를 사용해, 접속, 세션, 플레이어, 및 그룹을 관리한다.

DirectPlaySessionData 클래스는, 세션에 관한 데이터를 나타낸다. 이 클래스의 오브젝트를 사용해, 세션의 열거, 생성, 및 세션에의 참가를 처리한다.

DirectPlayLobby3 클래스는, 로비를 개입시킨 어플리케이션간 통신과 로비 서버에 의한 어플리케이션의 기동을 가능하게 한다. 보통, 어플리케이션으로 로비를 사용할 필요가 없는 경우는,DirectPlayLobby3 오브젝트를 생성 할 필요는 없다. 그러나, 이 클래스는, 모뎀을 열거하거나 비로비 어플리케이션으로 사용되는 DirectPlay 주소를 생성 하거나하기 위한 메소드를 보관 유지하고 있다.

DirectPlayLobbyConnection 클래스는, 어플리케이션이 로비에 의해 기동되었을 때에, 어플리케이션에게 건네지는 접속 데이터를 나타낸다.

다양한 종류의 데이터의 수집 (열거라고 말한다)은, 다음의 클래스의 오브젝트에 의해 관리된다.

  • DirectPlayEnumConnections
  • DirectPlayEnumLocalApplications
  • DirectPlayEnumPlayers
  • DirectPlayEnumSessions

예를 들어, 이용 가능한 접속에 관한 정보를 어플리케이션으로 취득하려면 ,DirectPlayEnumConnections 오브젝트를 생성 한다. 이 오브젝트의 메소드를 사용 하면, 임의의 접속에 관한 데이터를 취득할 수가 있다.

DirectPlayMessage 클래스의 오브젝트는, 어플리케이션 또는 로비와의 사이에 송수신 되는 메세지를 나타낸다.

DirectPlayAddress 클래스는, IP 주소나 전화번호 등, 어플리케이션에 의해 사용되는 기존의 접속 데이터를 캡슐화한다. 대부분의 어플리케이션에서는 이 클래스를 사용할 필요는 없다.

마지막으로,DirectPlaySessionData 클래스의 오브젝트는, 기존의 세션 또는 지금부터 생성 되는 세션에 관한 정보를 보관 유지한다.


DirectPlay 의 요점

여기에서는, DirectPlay® API 를 이행하기 위한 실천적인 가이드를 제공한다. 다음의 토픽에 대해 설명한다.

  • DirectPlay 어플리케이션을 기술하기 위한 기본 순서
  • DirectPlay 프로바이더의 사용
  • 로비 프로바이더
  • 세션 관리
  • 플레이어 관리
  • 그룹 관리
  • 로비 세션
  • 로비 대응 어플리케이션의 생성
  • DirectPlay 메세지
  • DirectPlay 주소
  • DirectPlay 프로토콜
  • DirectPlay 프로토콜을 사용한 비동기 네트워킹
  • 시큐러티와 인증
  • DirectX 의 이전의 버젼으로부터의 이행


DirectPlay 어플리케이션을 기술하기 위한 기본 순서

이 섹션에서는, 비로비형 멀티 플레이어 게임 또는 그 외의 네트워크 어플리케이션에 참가하기 위해서, 전형적인 어플리케이션이 취하는 기본스텝에 대해 간단하게 설명한다.

[C++]

이러한 스텝을 실행한 코드예를 확인하려면 ,Duel 샘플의 코드를 참조할것. 또, 「튜토리얼 2 : 다이알로그 박스를 사용한 접속」도 참조할것.

1. DirectPlay 를 초기화한다

어플리케이션은, 최초로 IDirectPlay4 인터페이스의 인스턴스를 생성 해, DirectPlay 오브젝트를 생성 해야 한다. 이 인터페이스의 메소드를 사용해, 로비의 외부에 있어서의 통신의 요소를 모두 관리한다.

2. 서비스 프로바이더를 열거한다

어플리케이션은,IDirectPlay4::EnumConnections 메소드를 사용해, 시스템상에서 이용 가능한서비스 프로바이더를 열거한다. 보통은 이용 가능한 접속이 리스트 박스로 제시되어 유저는 그 중에서 1 개(살)을 선택하도록(듯이) 요구된다.

3. 접속을 초기화한다

유저가 접속을 선택 하면, 어플리케이션은 IDirectPlay4::InitializeConnection 를 호출한다. 이 때, 서비스 프로바이더는 유저에 대해, 사용하는 모뎀이나 전화번호등의 추가 정보를 요구하는 경우가 있다. 유저가 서비스 프로바이더의 다이얼로그를 캔슬했을 경우,세션을 생성 하는 것은 가능하지만, 기존의 세션에 참가할 수 없다.

4. 세션을 생성 하는지, 또는 세션에 참가한다

어플리케이션에서는 보통, 새로운 세션을 생성 하는지, 기존의 세션에 참가할까를 유저에게 선택시킨다. 기존의 세션의 리스트를 취득하려면 ,IDirectPlay4::EnumSessions 를 호출한다. 세션을 생성 하거나 기존의 세션에 참가하거나 하려면 ,IDirectPlay4::Open 메소드 또는 IDirectPlay4::SecureOpen 메소드를 사용한다. 세션을 생성 하는 어플리케이션은, 자동적으로 그 세션에 참가해, 보통은 그 세션의호스트가 된다.

5. 플레이어를 생성 한다

어플리케이션은, 세션에 참가 하면, 식별과 메세지 관리를 위해서(때문에) 최저 1 명의 플레이어를 생성 해야 한다. 거기에는,IDirectPlay4::CreatePlayer 메소드를 사용한다.

IDirectPlay4::EnumPlayers 를 호출하면, 생성 한 플레이어를 열거할 수가 있다. 어플리케이션은, 예를 들어 세션에 현재 참가하고 있는 플레이어의 이름을 일람표시 하기 위해서, 이 메소드를 호출할 수가 있다.

또, 플레이어를 그룹 또는 서브 그룹에서 정리할 수도 있다. 상세한 것에 대하여는, 「그룹 관리」를 참조할것.

6. 게임을 시작 한다

어플리케이션은, 게임 (또는 그 외의 종류의 세션)을 언제, 어떻게 시작 할까를 판단한다. 플레이어가 일정한 인원수에 이른 후에 호스트 유저가 언제라도 게임을 시작 할 수 있도록(듯이) 하는 경우도 있으면, 일정 인원수의 유저가 참가했을 때에 게임이 자동적으로 시작 되도록(듯이) 하는 경우도 있다. 호스트는 모든 플레이어에게 메세지를 송신해, 게임이 시작된 것을 통지한다. 플레이어는,IDirectPlay4::Send ,IDirectPlay4::SendEx , 및 IDirectPlay4::Receive 메소드를 사용해 메세지를 교환해, 게임 상태를 갱신한다.

[Visual Basic]

이러한 스텝을 실행한 코드예를 확인하려면 , 「튜토리얼 1 : 간단한 네트워크 게임의 생성」을 참조할것.

1. DirectPlay 를 초기화한다

어플리케이션은, 최초로 DirectX7.DirectPlayCreate 를 호출해,DirectPlay4 오브젝트를 생성 할 필요가 있다. DirectPlay4 클래스의 멤버를 사용해, 로비를 사용하지 않는 경우의 통신의 요소를 모두 관리한다.

2. 서비스 프로바이더를 열거한다

어플리케이션은,DirectPlay4.GetDPEnumConnections 메소드를 사용해, 시스템상에서 다양한서비스 프로바이더를 개입시켜 이용 가능한 접속을 열거한다. 보통은 이용 가능한 접속이 리스트 박스로 제시되어 유저는 그 중에서 1 개(살)을 선택하도록(듯이) 요구된다.

3. 접속을 초기화한다

유저가 접속을 선택 하면, 어플리케이션은 DirectPlay4.InitializeConnection 를 호출한다. 이것에 의해, DirectPlay 가 특정의 서비스 프로바이더에 바인드 된다. 이 때, 서비스 프로바이더는 유저에 대해, 사용하는 모뎀이나 전화번호등의 추가 정보를 요구하는 경우가 있다. 유저가 서비스 프로바이더의 다이알로그 박스를 캔슬했을 경우, 세션을 생성 해, 다른 플레이어가 (통화중 등에 의해) 접속할 수 있게 될 때까지 물리 접속의 확립을 연기할 수가 있다.

4. 세션을 생성 하는지, 또는 세션에 참가한다

어플리케이션에서는 보통, 새로운 세션을 생성 하는지, 기존의 세션에 참가할까 (물리 세션이 확립해 있는 경우)를 유저에게 선택시킨다. 기존의 세션의 리스트를 취득하려면 ,DirectPlay4.GetDPEnumSessions 를 호출한다. 세션을 생성 하거나 세션에 참가하거나 하려면 ,DirectPlay4.Open 메소드 또는 DirectPlay4.SecureOpen 메소드를 사용한다. 세션을 생성 하는 어플리케이션은, 자동적으로 그 세션에 참가해, 보통은 그 세션의 호스트가 된다.

5. 플레이어를 생성 한다

어플리케이션은, 세션에 참가 하면, 식별과 메세지 관리를 위해서(때문에) 최저 1 명의 플레이어를 생성 해야 한다. 거기에는,DirectPlay4.CreatePlayer 메소드를 사용한다.

DirectPlay4.GetDPEnumPlayers 를 호출하면, 생성 한 플레이어를 열거할 수가 있다. 어플리케이션은, 예를 들어 세션에 현재 참가하고 있는 플레이어의 이름을 일람표시 하기 위해서, 이 메소드를 호출할 수가 있다.

또, 플레이어를 그룹 또는 서브 그룹에서 정리할 수도 있다. 상세한 것에 대하여는, 「그룹 관리」를 참조할것.

6. 게임을 시작 한다

어플리케이션은, 게임 (또는 그 외의 종류의 세션)을 언제, 어떻게 시작 할까를 판단한다. 플레이어가 일정한 인원수에 이른 후에 호스트 유저가 언제라도 게임을 시작 할 수 있도록(듯이) 하는 경우도 있으면, 일정 인원수의 유저가 참가했을 때에 게임이 자동적으로 시작 되도록(듯이) 하는 경우도 있다. 호스트는 모든 플레이어에게 어플리케이션으로 정의된 메세지를 송신해, 게임이 시작된 것을 통지한다. 플레이어는,DirectPlay4.Send ,DirectPlay4.SendEx , 및 DirectPlay4.Receive 메소드를 사용해 메세지를 교환해, 게임 상태를 갱신한다.


DirectPlay 프로바이더의 사용

서비스 프로바이더는, DirectPlay 의 요구에 응해, 네트워크에 고유의 통신 서비스를 제공한다. 개요에 대해서는, 「서비스 프로바이더」를 참조할것.

Microsoft 는, DirectPlay 에 다음의 서비스 프로바이더를 포함하고 있다.

  • TCP/IP
  • IPX
  • 모뎀 투 모뎀
  • 시리얼 링크

여기에서는, 디폴트의 서비스 프로바이더를 사용해 할 수 있는 것에 대하여 간단하게 설명한다. 써드파티의 서비스 프로바이더의 동작에 관한 정보를 취득하려면 , 네트워크 사업자에게 문의하는 것.


TCP/IP

TCP/IP (전송 제어 프로토콜/인터넷 프로토콜) 서비스 프로바이더는, TCP/IP 프로토콜을 이용해, Windows Sockets 를 사용해, 인터넷 또는 근거리 통신망 (LAN)을 개입시켜 통신한다. 이 서비스 프로바이더는, 비보증 메시징에는 UDP (User Datagram Protocol) 패킷을 사용해, 보증 메시징에는 TCP 를 사용한다. 1 대의 컴퓨터로, TCP/IP를 사용해 복수의 DirectPlay 세션을 호스트 할 수가 있다.

어플리케이션이 세션을 열거 하면, TCP/IP 가 다이알로그 박스를 표시해, 세션의 IP 주소를 유저에게 묻는다. 인터넷상의 세션의 경우, 유저는 참가하는 세션을 호스트 하는 컴퓨터의 IP 주소를 입력할 필요가 있다. 컴퓨터가 이름을 가지고 있는 경우 (microsoft.com 등), 그 이름을 IP 주소 대신에 사용할 수가 있다. 그 경우, DirectPlay 는 DNS (Domain Name System) 룩 업을 사용해 그 이름을 검색한다. 또, 유저는 주소를 하늘대로 해 [OK] 를 클릭할 수도 있다. 그 경우, DirectPlay 는 메세지를 브로드캐스트 해 세션을 검색한다. 이 처리는, 보통은 LAN 상 및 동일 서브 넷상에서만 기능한다.

[C++]

세션을 호스트 하고 있는 경우는, 어플리케이션으로 IDirectPlay4::GetPlayerAddress 를 사용해 로컬 IP 주소를 취득할 수가 있다.

어플리케이션은,IDirectPlay4::InitializeConnection 메소드를 사용하는지, 또는 IDirectPlayLobby3::SetConnectionSettings 메소드를 사용하고 나서 IDirectPlayLobby3::Connect 메소드를 호출하는 것으로,DirectPlay 주소의 서비스 프로바이더에 IP 주소를 제공할 수가 있다. 주소는, null 로 끝나는 ANSI 또는 Unicode 캐릭터 라인이 아니면 안된다 (각각 다른 데이터 타입 GUID 를 가진다). 세션의 브로드캐스트 열거가 바람직한 경우, 주소는, 길이 0 의 캐릭터 라인, 즉 null 터미네이터만으로부터 되는 캐릭터 라인이 아니면 안된다. 상세한 것에 대하여는, 「DirectPlay 주소」를 참조할것.

TCP/IP 서비스 프로바이더는, 포트 47624 를 사용해 열거 요구를 송수신 한다. 통신은, 포트 2300 ~ 2400 의 사이에 송신된다. 파이어 월(fire wall)를 통과해 통신하려면 , 모든 컴퓨터가 DirectX 6.0 이후포트 47624 를 사용해, 내향과 외부로 향한 양쪽 모두의 TCP 및 UDP 트래픽에 대해서 포트 2300 ~ 2400 을 비워 둘 필요가 있다. 상세한 것에 대하여는, 「파이어 월(fire wall)의 지원」을 참조할것.

주 : DirectPlay 는, 최초로 포트 2300 을 할당한 이후의 포트를 순서에 할당한다. 여는 포트의 범위가 2400 에 못 미친 경우도 있다.

어플리케이션은, 사용하는 특정의 포트를 선택할 수가 있다. 그 때문에(위해)는, DPAID_INetPort 라고 하는 데이터를 포함한 DirectPlay 주소를 사용해 TCP/IP 서비스 프로바이더를 초기화할 필요가 있다. 상세한 것에 대하여는, 「DirectPlay 주소」 및 「DirectPlay 주소의 데이터형」을 참조할것. 어플리케이션이 사용하는 특정의 포트를 선택 하면, 모든 통신은 그 포트를 경유해 송신된다. 이 경우, TCP 및 UDP 를 사용한 밖으로 향한 및 내향의 양쪽 모두의 통신에 대해서, 그 포트를 여는 것만으로 좋다.

TCP/IP 서비스 프로바이더의 GUID 는, DPSPGUID_TCPIP 라고 정의되고 있다.

[Visual Basic]

세션을 호스트 하고 있는 경우는, 어플리케이션으로 DirectPlay4.GetPlayerAddress 를 사용해 로컬 IP 주소를 취득할 수가 있다.

어플리케이션은,DirectPlayLobby3.CreateINetAddress 메소드를 사용해 DirectPlay 주소를 생성 할 수가 있다. 생성 한 주소는,DirectPlayAddress 오브젝트를 DirectPlay4.InitializeConnection 메소드에 건네주는지, 또는 그 오브젝트를 DirectPlayLobby3.SetConnectionSettings 에 건네주고 나서 DirectPlayLobby3.Connect 를 호출하는 것으로, 서비스 프로바이더에 건네줄 수가 있다. 상세한 것에 대하여는, 「DirectPlay 주소」를 참조할것.

DirectPlay 로비의 지원을 추가 하면, 유저는 게임의 시작시에 IP 주소를 입력할 필요가 없어진다. 상세한 것에 대하여는, 「동기 기동」을 참조할것.


IPX

IPX 서비스 프로바이더는, IPX (Internet Packet Exchange) 프로토콜을 이용해, Windows Sockets 를 사용해 근거리 통신망 (LAN)을 개입시켜 통신을 실시한다. 이 서비스 프로바이더는, 비보증 메시징만을 지원 한다. IPX 상에서 보증 메시징을 실행하려면 ,DirectPlay 프로토콜을 사용한다. 1 대의 컴퓨터로 IPX 를 사용해 호스트 할 수 있는 DirectPlay 세션은 1 개 뿐이다.

IPX 는, 네트워크 위에의 세션을 검색하기 위해서, 항상 브로드캐스트를 사용한다. 그 때문에, 이 서비스 프로바이더는, 추가 정보를 요구하는 다이알로그 박스를 표시할 것은 없다.

IPX 는, 다른 서브 넷 위에의 세션은 열거하지 않는다.

세션이 확립 하면, 패킷은 컴퓨터간에 직접 송신된다 (브로드캐스트 되지 않는다).

IPX 서비스 프로바이더의 GUID 는, DPSPGUID_IPX 와 지정할 수가 있다.


모뎀 투 모뎀

모뎀 투 모뎀 서비스 프로바이더는, 전화 API (TAPI)를 사용해 다른 모뎀과 통신한다. 이 서비스 프로바이더는, 비보증 메시징만을 지원 한다. 모뎀 세션으로 보증 메시징을 실행하려면 ,DirectPlay 프로토콜을 사용한다.

세션을 생성 하면, 다이알로그 박스가 표시된다. 유저는 모뎀과 그 설정을 선택하고 나서, 모뎀을 자동 응답 모드로 설정한다. 세션을 열거했을 경우도 다이알로그 박스가 표시되어 전화번호와 사용하는 모뎀이 물어본다. 정보가 입력되면(자), DirectPlay 는 모뎀에 다이얼 해, 상대방의 컴퓨터가 호스트 하고 있는 세션을 검색한다.

[C++]

다이알로그 박스를 표시하지 않고 모뎀 세션을 열거하려면 (예를 들어, 어플리케이션이 전화번호를 파악하고 있어,IDirectPlay4::InitializeConnection 가 불려 갔을 때에 그 전화번호가 서비스 프로바이더에게 건네져 있었을 경우), DPENUMSESSIONS_RETURNSTATUS 플래그를 설정하지 않고 IDirectPlay4::EnumSessions 를 루프로 사용한다 (상세한 것에 대하여는,EnumSessions 를 참조). DP_OK 가 돌려주어졌을 경우, 어플리케이션은 EnumSessions 를 한번 더 사용해 실제의 세션의 리스트를 취득할 필요가 있다.

이와 같이 해 EnumSessions 를 루프로 사용하는 경우, 어플리케이션에서는 윈도우 메세지의 루프를 다음과 같이 이행 할 필요가 있다.

while (lpDPLAY->EnumSessions(lpsd, 0, lpEnumSessionsCallback,
        lpContext, DPENUMSESSIONS_RETURNSTATUS) == DPERR_CONNECTING)
{
    MSG    msg;

    if (PeekMessage(&msg, 0, 0, 0, PM_REMOVE))
    {
        TranslateMessage(&msg);
        DispatchMessage(&msg);
    }

    Sleep(500);
}

메세지 처리에 삽입하는 지연 시간이 너무 길면(자), 패킷을 잃는 경우가 있다. 예를 들어, 대량의 디버그 정보를 출력하는 경우 등에, 이러한 일이 일어날 가능성이 있다.

이용 가능한 모뎀의 최신의 리스트를 서비스 프로바이더로부터 취득하려면 , 그 서비스 프로바이더를 초기화해, 플레이어 ID 에 제로를 지정해 IDirectPlay4::GetPlayerAddress 메소드를 호출한다. 돌려주어지는 DirectPlay 주소에는, ANSI 의 모뎀명 (DPAID_Modem)과 Unicode 의 모뎀명 (DPAID_ModemW)이 포함되어 있다. 모뎀의 리스트는, null 로 끝나는 일련의 캐릭터 라인으로, 리스트의 마지막에 길이 제로의 캐릭터 라인이 포함되어 있다. 상세한 것에 대하여는, 「DirectPlay 주소의 데이터형」을 참조할것.

[Visual Basic]

다이알로그 박스를 표시하지 않고 모뎀 세션을 열거하려면 (예를 들어, 어플리케이션이 전화번호를 파악하고 있어,DirectPlay4.InitializeConnection 가 불려 갔을 때에 그 전화번호가 서비스 프로바이더에게 건네져 있었을 경우), DPERR_CONNECTING 에러가 발생하지 않게 될 때까지, DPENUMSESSIONS_RETURNSTATUS 플래그를 설정해 DirectPlay4.GetDPEnumSessions 를 반복해 호출한다. 루프의 실행중에 이벤트를 처리할 수 있도록(듯이) 할 필요가 있다. 이것을 실시하는 방법의 일례를 다음의 샘플 코드에 나타낸다.

' objDPlay 는 DirectPlay4 오브젝트.
' SessionData 는, 유효한 정보를 포함한 DirectPlaySessionData 오브젝트.

On Error GoTo DO_AGAIN
Do While DoEvents
    objDPlay.GetDPEnumSessions(SessionData, 0, _
          DPENUMSESSIONS_AVAILABLE Or DPENUMSESSIONS_RETURNSTATUS)
    Exit Do    '에러 없음. 열거 완료.
DO_AGAIN:
    '다른 에러의 경우는, 포기한다.
    if Err.Number <> DPERR_CONNECTING Then
        '에러를 처리하는 - 세션을 열거할 수 없다.
        Exit Do
    End If
    ' 아직 접속하고 있으므로, 재차 시도한다.
Loop
On Error GoTo 0

이용 가능한 모뎀의 이름을 서비스 프로바이더로부터 취득하려면 , 그 서비스 프로바이더를 초기화해, 인덱스값 1 으로부터 DirectPlayLobby3.GetModemCount 에 의해 돌려주어지는 값까지 대해,DirectPlayLobby3.GetModemName 메소드를 호출한다.

모뎀 투 모뎀 서비스 프로바이더의 GUID 는, DPSPGUID_MODEM 와 지정할 수가 있다.


시리얼 링크

시리얼 링크는, 다른 컴퓨터와 시리얼 포트를 개입시켜 통신하기 위해서 이용된다. 이 서비스 프로바이더는, 비보증 메시징만을 지원 한다. 시리얼 링크로 보증 메시징을 실행하려면 ,DirectPlay 프로토콜을 사용한다.

세션을 생성 하는지, 또는 세션을 열거 하면, 시리얼 포트를 구성하도록(듯이) 유저에게 묻는 다이알로그 박스가 표시된다. 포트는 양쪽 모두의 컴퓨터로 똑같이 구성되어 있을 필요가 있다.

시리얼 링크 서비스 프로바이더는, DPSPGUID_SERIAL 와 지정할 수가 있다.


로비 프로바이더

로비 프로바이더는,로비 서버의 개발자에 의해 제공되는 클라이언트 컴퍼넌트 (DLL)이다. 로비 프로바이더는, DirectPlay 의 요구에 응해, 로비 서버와의 통신 기능을 이행 한다. DirectPlay API 를 사용해 기술된 로비 클라이언트는, 시스템상에 존재하는 어느 로비 프로바이더 DLL 의 로비 서버와도 교환할 수가 있다.

DirectX SDK 는, SDK 에 포함되어 있는 테스트용의 로비 서버 및 클라이언트로 사용하는 로비 프로바이더를 인스톨 한다. 이 로비 프로바이더를 사용하려면 , DirectX SDK 디렉토리의 \Samples\Multimedia\DPlay\Bin 폴더에 있는 Dpldplay.reg 를 더블 클릭 해 그것을 등록할 필요가 있다. 상세한 것에 대하여는, 「Bellhop 샘플」을 참조할것.


세션 관리

DirectPlay 세션은, 2 개(살) 이상의 어플리케이션 또는 어플리케이션의 인스턴스의 사이의 통신 채널이다.

주 : 접속의 종류에 따라서는, 1 대의 컴퓨터 위에의 복수의 어플리케이션 인스턴스가 세션에 참가하는 경우가 있다. 예를 들어, 최대 4 명의 플레이어가 IPX 또는 TCP/IP 접속을 사용해 1 대의 컴퓨터상에서 Memory 샘플을 플레이 할 수가 있다. 그러나, 대부분의 경우는, 세션에는 독립한 컴퓨터가 포함된다. 설명을 간단하게 하기 위해서, 이하에서는, 세션의 각 참가자를 "컴퓨터" 라고 부른다.

컴퓨터는, 2 개의 방법의 어느쪽이든으로 세션의 일부가 된다. 즉, 컴퓨터는 네트워크 위에의 기존의 세션을 모두 열거해 그 중의 어느 쪽인가에 참가하는지, 또는 새로운 세션을 생성 해 다른 컴퓨터가 참가하는 것을 대기할 수가 있다. 어플리케이션이 세션의 일부가 되면(자), 플레이어를 생성 해, 세션내외의 모든 플레이어와의 사이에 메세지를 교환할 수가 있다.

각 세션에는,호스트로서 1 대의 컴퓨터를 할당할 수 있다. 호스트는, 세션의 소유자이며, 세션의 프로퍼티를 변경할 수 있는 유일한 컴퓨터이다.

다음의 그림은, DirectPlay 의 세션 모델을 나타내고 있다.

DirectPlay 는, 다음의 세션 관리용 메소드를 제공한다.

[C++]
  • IDirectPlay4::EnumSessions 는, 이용 가능한 세션을 모두 열거한다.
  • IDirectPlay4::Open 는, 열거한 세션의 어느 쪽인가에 참가하는지, 또는 새로운 세션을 생성 한다.
  • IDirectPlay4::SecureOpen 는,IDirectPlay4::Open 와 같은 기능을 실행하지만, 어플리케이션에 의한 디폴트의 오픈 동작의 변경을 가능하게 한다.
  • IDirectPlay4::StartSession 는, staging 영역으로부터 세션을 시작 한다.
  • IDirectPlay4::Close 는, 현재 열려 있는 세션을 떨어진다.
  • IDirectPlay4::GetSessionDesc 는, 현재 세션의 프로퍼티를 취득한다.
  • IDirectPlay4::SetSessionDesc 는, 현재 세션의 프로퍼티를 변경한다.
  • IDirectPlay4::GetCaps 는, 기반이 되는 네트워크의 통신 기능을 취득한다.
[Visual Basic]
  • DirectPlay4.GetDPEnumSessions 는, 이용 가능한 세션을 모두 열거한다.
  • DirectPlay4.Open 는, 열거한 세션의 어느 쪽인가에 참가하는지, 또는 새로운 세션을 생성 한다.
  • DirectPlay4.SecureOpen 는,DirectPlay4.Open 와 같은 기능을 실행하지만, 어플리케이션에 의한 디폴트의 오픈 동작의 변경을 가능하게 한다.
  • DirectPlay4.StartSession 는, staging 영역으로부터 세션을 시작 한다.
  • DirectPlay4.Close 는, 현재 열려 있는 세션을 떨어진다.
  • DirectPlay4.CreateSessionData 는, 세션의 기술에 사용되는 DirectPlaySessionData 오브젝트를 생성 한다.
  • DirectPlay4.GetSessionDesc 는, 현재 세션의 프로퍼티를 취득한다.
  • DirectPlay4.SetSessionDesc 는, 현재 세션의 프로퍼티를 변경한다.
  • DirectPlay4.GetCaps 는, 기반이 되는 네트워크의 통신 기능을 취득한다.


플레이어 관리

플레이어는, 메세지를 송수신 할 수 있는,세션내의 논리 오브젝트를 나타낸다. 플레이어를 생성 하면, DirectPlay 에 의해, 세션이 계속되고 있는 한 재이용되지 않는 일의의 ID 번호를 할당할 수 있다.

각 플레이어는, 로컬 플레이어 (로컬의 컴퓨터상에 존재한다) 또는 리모트 플레이어 (다른 컴퓨터상에 존재한다)로서 식별된다. 각 컴퓨터는, 메세지의 송수신을 시작 하기 전에 최저 1 명의 플레이어를 보관 유지하고 있지 않으면 안 된다. 각 컴퓨터는, 1 명 이상의 로컬 플레이어를 보관 유지할 수가 있다.

어플리케이션이 메세지를 송신하는 경우, 그 메세지는 다른 컴퓨터는 아니고, 항상 다른 플레이어를 향한다. 송신지의 플레이어는, 다른 로컬 플레이어 (이 경우, 메세지는 네트워크상에는 송출되지 않는다) 또는 리모트 플레이어의 어디라도 좋다. 같이 어플리케이션이 메세지를 수신하는 경우, 그것들은 항상 특정의 (로컬) 플레이어에게 보내져 다른 플레이어로부터의 것이라고 마크 된다 (다만, 시스템 메세지는 항상 DPID_SYSMSG 로부터의 것이라고 마크 된다).

DirectPlay 는, 어플리케이션으로 이용 가능한 추가의 플레이어 관리 메소드를 제공한다. 이것들을 사용 하면, 이름을 플레이어와 관련지어 그 이름을 세션에 참가하고 있는 것 외의 모든 컴퓨터에 자동적으로 전승할 수가 있다. 같이 세션내외의 모든 플레이어에게 전승되는 임의의 데이터를 플레이어에게 관련지을 수도 있다. 또, 로컬 컴퓨터만을 사용할 수 있는 사적인 로컬 데이터를 플레이어에게 관련지을 수도 있다.

[C++]

DirectPlay 는, 플레이어 관리에 필수의 이하의 메소드를 제공한다.

  • IDirectPlay4::EnumPlayers 는, 세션내의 모든 플레이어를 열거한다.
  • IDirectPlay4::CreatePlayer 는, 로컬 플레이어를 생성 한다.
  • IDirectPlay4::DestroyPlayer 는, 로컬 플레이어를 파기한다.

DirectPlay 는, 플레이어 정보를 관리하기 위한 이하의 추가 메소드를 제공한다.

  • IDirectPlay4::GetPlayerAccount 는, 플레이어의 어카운트 정보를 취득한다.
  • IDirectPlay4::GetPlayerAddress 는, 플레이어의 네트워크 고유 주소를 취득한다.
  • IDirectPlay4::GetPlayerData 는, 플레이어가 관련지을 수 있었던 어플리케이션 고유 데이터를 취득한다.
  • IDirectPlay4::GetPlayerFlags 는, 플레이어에 관한 추가 정보를 취득한다.
  • IDirectPlay4::GetPlayerCaps 는, 플레이어의 통신 능력에 관한 정보를 취득한다.
  • IDirectPlay4::GetPlayerName 는, 플레이어의 프렌들리명과 정식명을 취득한다.
  • IDirectPlay4::SetPlayerName 는, 플레이어의 프렌들리명과 정식명을 변경한다.
  • IDirectPlay4::SetPlayerData 는, 어플리케이션에 고유의 데이터를 플레이어에게 관련짓는다.
[Visual Basic]

DirectPlay 는, 플레이어 관리에 필수의 이하의 메소드를 제공한다.

  • DirectPlay4.GetDPEnumPlayers 는, 세션내의 모든 플레이어를 열거한다.
  • DirectPlay4.CreatePlayer 는, 로컬 플레이어를 생성 한다.
  • DirectPlay4.DestroyPlayer 는, 로컬 플레이어를 파기한다.

DirectPlay 는, 플레이어 정보를 관리하기 위한 이하의 추가 메소드를 제공한다.

  • DirectPlay4.GetPlayerAccountId 는, 플레이어의 어카운트 정보를 취득한다.
  • DirectPlay4.GetPlayerAddress 는, 플레이어의 네트워크 고유 주소를 취득한다.
  • DirectPlay4.GetPlayerCaps 는, 플레이어의 통신 능력을 취득한다.
  • DirectPlay4.GetPlayerData 는, 플레이어가 관련지을 수 있었던 어플리케이션 고유 데이터를 취득한다.
  • DirectPlay4.GetPlayerFlags 는, 플레이어에 관한 추가 정보를 취득한다.
  • DirectPlay4.GetPlayerFormalName 는, 플레이어의 정식명 ("긴" 이름)을 취득한다.
  • DirectPlay4.GetPlayerFriendlyName 는, 플레이어의 프렌들리명 ("짧은" 이름)을 취득한다.
  • DirectPlay4.SetPlayerName 는, 플레이어의 프렌들리명과 정식명을 변경한다.
  • DirectPlay4.SetPlayerData 는, 어플리케이션에 고유의 데이터를 플레이어에게 관련짓는다.


그룹 관리

DirectPlay 는,세션내의그룹을 지원 한다. 그룹은,플레이어의 논리적인 모임이다. 어플리케이션은 메세지를 그룹에 송신할 수가 있다. 하면, 그 그룹내의 모든 플레이어가 메세지를 수신한다. 플레이어와 같이, 그룹은, 세션의 계속중에 재이용되지 않는 일의의 번호에 의해 식별된다.

그룹은, 세션에 참가하고 있는 플레이어를 정리하기 위해서 이용할 수 있다. 예를 들어, 팀별로 정리하는 것이 가능하다. 플레이어는 2 개 이상의 그룹에 속할 수가 있다. 그룹을 파기 하면, 모든 플레이어가 그룹으로부터 삭제되지만, 플레이어 자체는 파기되지 않는다.

또, 그룹은 서브 그룹이나, 그룹에의 쇼트 컷을 보관 유지할 수가 있다. CreateGroup 메소드를 사용해 그룹을 생성 하면, 그 그룹이 최상정도의 그룹 (A 로 한다)이 된다. 이 그룹에의 쇼트 컷을,AddGroupToGroup 메소드를 사용해 다른 그룹 (B 로 한다)에 추가할 수가 있다. 그룹 B 를 파기 하면, A 에의 쇼트 컷도 파기되지만, A 는 최상정도의 그룹으로서 남는다. 한편,CreateGroupInGroup 메소드를 사용해 그룹 B 내에서 그룹 A 를 생성 했을 경우, A 는 최상정도 그룹은 아니기 때문에, B 를 파기 하면, A 도 파기된다.

그룹에 송신된 메세지는, 그 그룹에 직접 또는 간접적으로 속하는 모든 플레이어에게 보내진다. 예를 들어, Quarterback 라고 하는 플레이어를 BlueOffense 라고 하는 그룹에 추가해, BlueOffense 그룹을 BlueTeam 그룹에 추가했다고 하자. Quarterback 는 BlueTeam 에 직접 추가된 것은 아니지만, BlueOffense 에 송신된 메세지 만이 아니고, BlueTeam 에 송신된 메세지도 모두 수신한다.

플레이어의 그룹을 관리하기 위한 독자적인 시스템을 이행 하는 것보다도, DirectPlay 의 그룹 관리 방법을 이용하는 것이 현명하다. DirectPlay 는, 서비스 프로바이더의 모든 멀티 캐스팅 기능을 이용해 그룹 메세지를 송신해, 메세지 트래픽을 경감할 수가 있다. 상세한 것에 대하여는, 「피어 투 피어 세션」을 참조할것.

[C++]

DirectPlay 는, 그룹과 그 멤버를 관리하기 위해서 불가결한 이하의 메소드를 제공한다.

IDirectPlay4::AddPlayerToGroup 는, 플레이어를 그룹에 추가한다.

IDirectPlay4::CreateGroup 는, 새로운 최상정도 그룹을 생성 한다.

IDirectPlay4::DeletePlayerFromGroup 는, 플레이어를 그룹으로부터 삭제한다.

IDirectPlay4::DestroyGroup 는, 그룹을 파기한다.

IDirectPlay4::EnumGroupPlayers 는, 그룹내의 플레이어를 열거한다.

IDirectPlay4::EnumGroups 는, 세션내의 모든 그룹을 열거한다.

DirectPlay 는, 그룹과 그룹 정보를 관리하기 위한 이하의 추가 메소드를 제공한다.

IDirectPlay4::AddGroupToGroup 는, 그룹의 쇼트 컷을 기존의 그룹에 추가한다.

IDirectPlay4::CreateGroupInGroup 는, 기존의 그룹내에 그룹을 생성 한다.

IDirectPlay4::DeleteGroupFromGroup 는,AddGroupToGroup 를 사용해 그룹에 추가된 그룹을 삭제한다. 다만, 삭제된 그룹은 파기되지 않는다.

IDirectPlay4::EnumGroupsInGroup 는, 그룹내의 그룹을 모두 열거한다.

IDirectPlay4::GetGroupConnectionSettings 는, 그룹의 접속 설정을 취득한다.

IDirectPlay4::GetGroupData 는, 그룹에 관련지을 수 있었던 어플리케이션 고유 데이터를 취득한다.

IDirectPlay4::GetGroupFlags 는, 그룹의 생성 방법에 관한 추가 정보를 취득한다.

IDirectPlay4::GetGroupName 는, 그룹의 이름을 취득한다.

IDirectPlay4::GetGroupOwner 는, 그룹의 소유자를 취득한다.

IDirectPlay4::GetGroupParent 는,CreateGroupInGroup 를 사용해 생성 된 서브 그룹의 부모의 ID 를 취득한다.

IDirectPlay4::SetGroupConnectionSettings 는, 그룹의 접속 설정을 실시한다.

IDirectPlay4::SetGroupData 는, 해당의 컴퓨터에 의해 생성 된 그룹에 관련지을 수 있고 있는 어플리케이션 고유 데이터를 변경한다.

IDirectPlay4::SetGroupName 는, 해당의 컴퓨터에 의해 생성 된 그룹의 이름을 변경한다.

IDirectPlay4::SetGroupOwner 는, 그룹의 소유자를 변경한다.

[Visual Basic]

DirectPlay 는, 그룹과 그 멤버를 관리하기 위해서 불가결한 이하의 메소드를 제공한다.

DirectPlay4.AddPlayerToGroup 는, 플레이어를 그룹에 추가한다.

DirectPlay4.CreateGroup 는, 새로운 최상정도 그룹을 생성 한다.

DirectPlay4.DeletePlayerFromGroup 는, 플레이어를 그룹으로부터 삭제한다.

DirectPlay4.DestroyGroup 는, 그룹을 파기한다.

DirectPlay4.GetDPEnumGroupPlayers 는, 그룹내의 플레이어를 열거한다.

DirectPlay4.GetDPEnumGroups 는, 세션내의 모든 그룹을 열거한다.

DirectPlay 는, 그룹과 그룹 정보를 관리하기 위한 이하의 추가 메소드를 제공한다.

DirectPlay4.AddGroupToGroup 그룹의 쇼트 컷을 기존의 그룹에 추가한다.

DirectPlay4.CreateGroupInGroup 는, 기존의 그룹내에 그룹을 생성 한다.

DirectPlay4.DeleteGroupFromGroup 는,AddGroupToGroup 를 사용해 그룹에 추가된 그룹을 삭제한다. 다만, 삭제된 그룹은 파기되지 않는다.

DirectPlay4.GetDPEnumGroupsInGroup 는, 그룹내의 그룹을 모두 열거한다.

DirectPlay4.GetGroupData 는, 그룹에 관련지을 수 있었던 어플리케이션 고유 데이터를 취득한다.

DirectPlay4.GetGroupFlags 는, 그룹의 생성 방법에 관한 추가 정보를 취득한다.

DirectPlay4.GetGroupLongName 는, 그룹의 로그 온명 또는 정식명을 취득한다.

DirectPlay4.GetGroupOwner 는, 그룹의 소유자를 취득한다.

DirectPlay4.GetGroupParent 는,CreateGroupInGroup 을 사용해 생성 된 서브 그룹의 부모의 ID 를 취득한다.

DirectPlay4.GetGroupShortName 는, 그룹의 쇼트 컷명 또는 프렌들리명을 취득한다.

DirectPlay4.SetGroupConnectionSettings 는, 로비 세션에 있어서의 그룹의 접속 설정을 실시한다.

DirectPlay4.SetGroupData 는, 해당의 컴퓨터에 의해 생성 된 그룹에 관련지을 수 있고 있는 어플리케이션 고유 데이터를 변경한다.

DirectPlay4.SetGroupName 는, 그룹의 롱 네임과 쇼트 네임을 변경한다.

DirectPlay4.SetGroupOwner 는, 그룹의 소유자를 변경한다.


로비 세션

로비 세션은, DirectPlay 클라이언트/서버 세션 ( 「클라이언트/서버 세션」의 그림을 참조)에 자주(잘) 비슷하다. 로비 세션과는, 로비 서버에의 접속을 나타낸다. 이 경우, 클라이언트와 서버는, 공동으로 기능하도록(듯이)는 기술되어 있지 않다. 어플리케이션 세션이란, 전통적인 DirectPlay 세션을 나타낸다. 이 세션에서는, 모든 클라이언트와 서버는, 공동으로 기능하도록(듯이) 기술되고 있다.

DirectPlay 를 사용해 로비 서버와 통신하기 위한 최초의 스텝은, 사용하는 로비 프로바이더와 접속하는 로비 서버를 선택하는 것이다. 이용 가능한 프로바이더를 다른 DirectPlay 서비스 프로바이더와 같이 열거해, 접속을 같은 방법으로 확립한다. 「DirectPlay 어플리케이션을 기술하기 위한 기본 순서」를 참조할것.

로비 클라이언트는, 어플리케이션 클라이언트가 어플리케이션 세션을 검색해 거기에 참가하는 방법과 같은 방법으로 로비 세션을 검색해, 거기에 참가한다 ( 「세션 관리」를 참조). 로비 세션에 참가 하면, 클라이언트 어플리케이션은 로비 서버 위에의 모든 정보에 액세스 할 수 있게 되어, 유저는 로비 서버 위에의 다른 유저와 교환할 수 있게 된다.

DirectPlay 어플리케이션 세션의 경우와 같이, 플레이어는 로비 세션에 있어서의 기본 엔티티이다. 각 플레이어는, 로비 서버에 접속하고 있는 클라이언트 컴퓨터 위에의 유저를 나타낸다. 또, 로비 서버를 나타내는 서버 플레이어도 존재한다. 로비 클라이언트는, (로비 세션에 참가하는 것으로써) 로비 서버에 접속한 후, 유저의 존재를 확립해야 한다. 그 때문에(위해), 플레이어를 생성 해, 그 플레이어가 서버나 다른 플레이어와의 통신을 시작 하기 전에, 그 플레이어를 초기 그룹에 추가한다. 사실, 세션에 접속하고 있는 것 외의 유저는, 이와 같이 해 유저의 존재가 확립될 때까지는, 그 유저의 존재를 알아차리지 않는다.

로비 세션에 참가하고 있는 플레이어를 관리하기 위해서는, 어플리케이션 세션으로 이용하는 플레이어 관리 방법과 같은 방법을 사용한다. 「플레이어 관리」를 참조.

로비 세션에 참가하고 있는 플레이어는, 보통의 메세지를 서로 교환할 수 없다. DirectPlay 의 로비 구조에서는, DirectPlay API 를 사용하는 임의의 어플리케이션은, 임의의 로비 서버에 접속할 수 있다. 즉, 같은 로비 세션내에 복수가 다른 로비 클라이언트 어플리케이션이 존재해, 그것들 모든 것이 어플리케이션으로 정의된 다른 메세지 세트를 사용하고 있을 가능성이 있다.

[C++]

그러나, 클라이언트는, 표준의 로비 메세지와 IDirectPlayLobby3::SendLobbyMessage 메소드를 사용해, 로비와 메세지를 교환할 수가 있다. 게다가 플레이어는 IDirectPlay4::SendChatMessage 메소드를 사용해, 서로 텍스트를 송신할 수가 있다. 이 메소드를 사용 하면, 로비는 채팅 메세지를 포함한 시스템 메세지를 입수자에게 송신한다.

[Visual Basic]

그러나, 클라이언트는, 표준의 로비 메세지와 DirectPlayLobby3.SendLobbyMessage 메소드를 사용해, 로비와 메세지를 교환할 수가 있다. 게다가 플레이어는 DirectPlay4.SendChatMessage 메소드를 사용해, 서로 텍스트를 송신할 수가 있다. 이 메소드를 사용 하면, 로비는 채팅 메세지를 포함한 시스템 메세지를 입수자에게 송신한다.

그룹은, 로비 세션에서는 보다 중요한 역할을 완수한다. 이것은, 그룹은 로비 서버 전체의 편성을 정의해, 어플리케이션 세션을 기동하기 위해서 이용되기 때문이다.

로비 서버의 목적상, 그룹은룸또는staging 영역의 어느 쪽인가에 구분된다.

룸은, 플레이어나 다른 그룹을 보관 유지할 수 있는 표준의 그룹이다. 룸은, 주로 플레이어가 로비의 문맥내에서 다른 플레이어와 교환하는 만남의장으로서 이용된다. 룸은, 다른 룸에의 링크와 이제(벌써) 1 개의 종류의 그룹, 즉 staging 영역에의 링크를 보관 유지한다.

staging 영역은, 보통은 플레이어만을 보관 유지한다. staging 영역은, 새로운 세션의 시작에 해당해 플레이어를 정리하기 위해서 이용된다. 세션을 시작 한 후는, staging 영역을 파기하는지, 또는 새로운 플레이어가 진행중의 세션에 참가할 수 있도록(듯이) 그대로 유지해 둘 수가 있다.

룸 그룹은, 주로 계층 구조로 정리된다. 최상정도 그룹이 몇개인가 생성 되어 계속되어 기존의 그룹내에 다른 그룹이 생성 된다. 로비 클라이언트는, 최상정도 그룹과 그룹내에 포함되어 있는 그룹을 모두 열거할 수가 있다. 로비 서버는, 그룹을 Web 구조에 정리할 수도 있다. 생성 한 그룹은, 다른 그룹에 추가할 수가 있다. 하면, 2 개의 그룹간에 링크가 생성 된다. 로비 클라이언트가 그룹내의 그룹을 열거 하면, 서브 그룹과 링크처 그룹이 모두 돌려주어진다.

다음의 그림은, 로비 세션의 편성을 나타내고 있다.

플레이어는, 그룹에 참가할 때까지는, 인식되지 않는다. 플레이어는 한 번에 2 개(살) 이상의 그룹에 속할 수가 있다.

보통, 플레이어가 확인할 수 있는 로비 세션의 범위는, 그 플레이어가 속하는 그룹에 의해 제한된다. 이 제한에 의해, 서버가 클라이언트에 다운로드해야 하는 정보량이 경감된다. 플레이어는, 스스로를 현재의 그룹으로부터 삭제해, 새로운 그룹에 추가하는 것으로써, 로비 서버의 공간을 이동할 수가 있다.


동기 기동

[C++]

어플리케이션 세션은, staging 영역에서 준비되어 기동된다. 1 명의 플레이어가 staging 영역을 생성 해, 다른 플레이어가 거기에 참가하는 것을 대기한다. 플레이어는,IDirectPlay4::SetGroupConnectionSettings 메소드를 사용해, 생성 되는 어플리케이션 세션의 프로퍼티를 설정할 수가 있다. 그룹에의 참가를 검토하고 있는 것 외의 플레이어는,IDirectPlay4::GetGroupConnectionSettings 메소드를 호출해, 어플리케이션 세션의 프로퍼티를 확인할 수가 있다. 충분한 인원수의 플레이어가 staging 영역에 모이면(자), 임의의 플레이어가 IDirectPlay4::StartSession 메소드를 호출해 동기 기동의 순서를 시작 할 수가 있다.

staging 영역내의 모든 플레이어는,DPLCONNECTION 구조체를 포함한 DPMSG_STARTSESSION 시스템 메세지를 수신한다. 플레이어가 외부 로비 클라이언트를 사용하고 있는 경우, 그 로비 클라이언트는 접속 정보를 IDirectPlayLobby3::RunApplication 메소드에 건네주는 것으로, 어플리케이션을 기동할 수가 있다. 플레이어가 내부 로비를 사용하고 있는 경우, 어플리케이션은 IDirectPlayLobby3::ConnectEx 를 호출하는 것으로, 적절한 세션에의 접속을 확립할 수가 있다. 상세한 것에 대하여는, 「외부 로비에 의한 시작의 지원」을 참조할것.

[Visual Basic]

어플리케이션 세션은, staging 영역에서 준비되어 기동된다 ( 「로비 세션」을 참조). 1 명의 플레이어가 staging 영역을 생성 해, 다른 플레이어가 거기에 참가하는 것을 대기한다.

플레이어는,DirectPlay4.SetGroupConnectionSettings 메소드를 사용해, 생성 되는 어플리케이션 세션의 프로퍼티를 설정할 수가 있다. 충분한 인원수의 플레이어가 staging 영역에 모이면(자), 임의의 플레이어가 DirectPlay4.StartSession 메소드를 호출해 동기 기동의 순서를 시작 할 수가 있다.

staging 영역내의 모든 플레이어는, 접속에 관한 정보를 포함한 DPSYS_STARTSESSION 시스템 메세지를 수신한다. 플레이어가 외부 로비 클라이언트를 사용하고 있는 경우, 그 로비 클라이언트는 DirectPlayLobby3.RunApplication 메소드를 사용해, 어플리케이션을 기동할 수가 있다. 플레이어가 내부 로비를 사용하고 있는 경우, 어플리케이션은 DirectPlayMessage.ReadSysMsgConnection 를 호출해 접속 설정을 취득해,DirectPlayLobby3.SetConnectionSettings 에 의해 그것을 설정하고 나서 DirectPlayLobby3.Connect 를 호출하는 것으로, 적절한 세션에의 접속을 확립할 수가 있다. 상세한 것에 대하여는, 「외부 로비에 의한 시작의 지원」을 참조할것.


로비 대응 어플리케이션의 생성

DirectPlay 어플리케이션이 로비 대응이 되기 위해서(때문에)는, 최악이어도 로비로부터의 기동을 지원 할 필요가 있다. 그 외의 기능을 추가해, 로비와의 통합을 강화할 수도 있다. 상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 로비 대응 어플리케이션의 등록
  • 외부 로비에 의한 시작의 지원
  • 리플 기동의 지원
  • 동적 로비 접속의 지원
  • 로비와의 관계의 유지

DirectX 의 샘플에는, 테스트용의 로비 서버 (Lserver.exe)와 로비 클라이언트 (Bellhop.exe)가 포함되어 있다. 이것들을 조합해 사용 하면, 어플리케이션의 로비 대응 기능을 테스트할 수가 있다.


로비 대응 어플리케이션의 등록

어플리케이션이 DirectPlay 로비 클라이언트로부터 인식 및 기동되도록(듯이) 하려면 , 그 어플리케이션을 DirectPlay 어플리케이션으로서 시스템 레지스트리에 등록할 필요가 있다. 보통, 어플리케이션은 셋업중에 등록하지만, 거기에는 셋업 프로그램으로 DirectPlayLobby3 오브젝트를 생성 할 필요가 있다. 또, 어플리케이션을 언인스톨했을 경우는, 그 등록을 해제할 필요가 있다.

[C++]

어플리케이션을 등록하려면 ,DPAPPLICATIONDESC 구조체 또는 DPAPPLICATIONDESC2 구조체에 필요한 정보를 입력해, 그것을 IDirectPlayLobby3::RegisterApplication 에 건네준다. 레지스트리 엔트리를 삭제하려면 ,IDirectPlayLobby3::UnRegisterApplication 를 호출한다.

또, DirectX 의 셋업 처리중에 로비 대응 어플리케이션을 등록할 수도 있다. 거기에는,DirectXRegisterApplication 함수를 호출한다. 이 함수의 장점은, DirectPlay 의 런타임 파일을 인스톨 하기 전에 호출할 수 있다고 하는 것이다.

[Visual Basic]

어플리케이션을 등록하려면 ,DPAPPLICATIONDESC2 형에 필요한 정보를 입력해, 그것을 DirectPlayLobby3.RegisterApplication 에 건네준다. 레지스트리 엔트리를 삭제하려면 ,DirectPlayLobby3.UnRegisterApplication 를 호출한다.


외부 로비에 의한 시작의 지원

로비의 기동을 파악해, 어플리케이션 세션에 참가하기 위한 기본적인 스텝은, 다음과 같다.

[C++]
  1. 스타트 업시에,CoCreateInstance 함수를 사용해 IDirectPlayLobby3 인터페이스를 생성 한다.
  2. IDirectPlayLobby3::GetConnectionSettings 메소드를 호출한다 (보통은, 필요한 버퍼의 사이즈를 취득하기 위해(때문에)와 버퍼를 할당한 후의 합계 2 회 호출한다). 이 메소드가 DPERR_NOTLOBBIED 를 돌려주는 경우, 어플리케이션은 로비에 의해 기동되지 않고, 유저에 의해 보통의 방법으로 실행된 가능성이 높다. 비로비 세션의 생성 또는 접속을 유저에게 허가하는 코드 패스에 따라 먼저 진행된다. GetConnectionSettings 이 성공했을 경우, 로비에 의해 설정된 접속 설정 (세션 기술을 포함한다)을 보관 유지하는 DPLCONNECTION 구조체가 돌려주어진다. 변경을 더하려면 ,IDirectPlayLobby3::SetConnectionSettings 를 사용한다.
  3. IDirectPlayLobby3::ConnectEx 를 호출해, 어플리케이션 세션을 생성 하는지, 또는 어플리케이션 세션에 참가한다 (어플리케이션은 DPLCONNECTION.dwFlags 를 조사해, 세션을 생성 하는지, 또는 세션에 참가할까를 판단한다).
  4. 스텝 2 로 취득한 DPLCONNECTION 구조체에 의해 제공되는 이름 정보를 사용해, 플레이어를 생성 한다.

이 시점에서, 어플리케이션은, 유저가 접속을 수동으로 선택해, 세션에 참가하든가 또는 생성 해, 생성 하는 플레이어의 이름을 입력했을 경우와 같은 코드 패스에 따라, 먼저 진행될 수가 있다.

게임에서 로비에 정보를 돌려주는 경우는,IDirectPlayLobby3 인터페이스를 보존할 수 있다 ( 「로비와의 관계의 유지」를 참조). 그 이외의 경우는,Release 메소드를 사용해 이 인터페이스를 삭제할 수 있다.

추가 정보와 샘플 코드에 대해서는,Duel (Lobby.c) 샘플과 ChatConnect (Lobby.cpp) 샘플, 및 「튜토리얼 1 : 로비를 사용한 접속」을 참조할것.

[Visual Basic]
  1. 스타트 업시에,DirectX7.DirectPlayLobbyCreate 메소드를 사용해 DirectPlayLobby3 오브젝트를 생성 한다.
  2. DirectPlayLobby3.GetConnectionSettings 메소드를 호출한다. 이 메소드에 의해 DPERR_NOTLOBBIED 에러가 발생하는 경우, 어플리케이션은 로비에 의해 기동되지 않고, 유저에 의해 보통의 방법으로 실행된 가능성이 높다. 비로비 세션의 생성 또는 접속을 유저에게 허가하는 코드 패스에 따라 먼저 진행된다. GetConnectionSettings 이 성공했을 경우, 로비에 의해 설정된 접속 설정 (세션 기술을 포함한다)을 나타내는 DirectPlayLobbyConnection 오브젝트가 돌려주어진다. 변경을 더하려면 ,DirectPlayLobby3.SetConnectionSettings 를 사용한다.
  3. DirectPlayLobby3.Connect 를 호출해, 어플리케이션 세션을 생성 하는지, 또는 거기에 참가한다 (어플리케이션은,DirectPlayLobbyConnection.GetFlags 에 의해 돌려주어지는 값을 조사해, 세션을 생성 하는지, 또는 세션에 참가할까를 판단한다).
  4. 스텝 2 로 취득한 irectPlayLobbyConnection 오브젝트에 의해 제공되는 이름 정보를 사용해, 플레이어를 생성 한다.

이 시점에서, 어플리케이션은, 유저가 접속을 수동으로 선택해, 세션에 참가하든가 또는 생성 해, 생성 하는 플레이어의 이름을 입력했을 경우와 같은 코드 패스에 따라, 먼저 진행될 수가 있다.

게임에서 로비에 정보를 돌려주는 경우는,DirectPlayLobby3 오브젝트를 보존할 수 있다 ( 「로비와의 관계의 유지」를 참조).

로비의 상당수는, 어플리케이션을 기동하고 나서 중지 모드에 들어가, 어플리케이션이 종료하는 것을 대기한다. DirectPlay 는, 기동한 어플리케이션이 종료했을 때에, 로비에 통지한다. 그 때문에, 로비에 의해 기동된 어플리케이션이 다른 어플리케이션을 기동하지 않는 것이 중요하다 (그러나, 올바르게 등록된 어플리케이션 자체를 란체에 의해 기동하는 것이 가능하다 「리플 기동의 지원」을 참조).


리플 기동의 지원

리플 기동이란, 그 자체가 로비에 의해 기동된 다른 어플리케이션으로부터 어플리케이션을 실행하는 것이다. 이하의 설명에서는, 로비에 의해 실행되는 프로그램을란체이라고 불러 , 란체가 기동하는 프로그램을어플리케이션이라고 부른다.

[C++]

어플리케이션으로 리플 기동을 지원 하기 위해서는,IDirectPlayLobby3::RegisterApplication 에 DPAPPLICATIONDESC2 구조체를 건네주어, 그 어플리케이션을 등록할 필요가 있다. 이 구조체에는, 란체의 이름을 보관 유지하는 lpszAppLauncherName 라고 하는 멤버가 포함되어 있다. 란체는 어플리케이션과 같은 디렉토리에 위치하고 있을 필요가 있다.

로비 클라이언트가 IDirectPlayLobby3::RunApplication 를 호출해 어플리케이션을 실행 하면, DirectPlay 는 레지스트리내에서 란체의 이름을 검색해, 어플리케이션은 아니고, 란체를 실행한다. 어플리케이션을 실행하는 것은 란체의 역할이다.

란체는, 건네받은 커멘드 라인 파라미터를 어플리케이션에 모두 건네줄 필요가 있다. 어플리케이션은, 이해할 수 없는 커멘드 라인 파라미터를 단순하게 무시한다.

어플리케이션은,IDirectPlayLobby3::WaitForConnectionSettings 를 사용하기 전에, 최저 1 회는 반드시 IDirectPlayLobby3::GetConnectionSettings 를 호출한다 ( 「동적 로비 접속의 지원」을 참조).

이하의 예는, 리플 기동의 어플리케이션을 등록하는 방법을 나타내고 있다. lpDPLobby3A 는,IDirectPlayLobby3 인터페이스를 나타내고 있다.

DPAPPLICATIONDESC2  dpad2;

dpad2.dwSize = sizeof (DPAPPLICATIONDESC2);
dpad2.dwFlags = 0;
dpad2.lpszApplicationNameA= "MyApp";
dpad2.guidApplication = {12345678-...};
dpad2.lpszFilenameA= "myapp.exe";
dpad2.lpszCommandLineA= "/lobbied";
dpad2.lpszPathA= "C:\\games";
dpad2.lpszCurrentDirectoryA= "C:\\games";
dpad2.lpszDescriptionA= "My Application";
dpad2.lpszDescriptionW= L"My Application";
dpad2.lpszAppLauncherNameA= "launcher.exe";

HRESULT hr = lpDPLobby3A->RegisterApplication(0, &dpad2);

이하의 예는, Duel 샘플을 기동하는 완전한 콘솔 프로그램이다.

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

int main(int argc, char* argv[])
{
  PROCESS_INFORMATION ProcInfo;
  STARTUPINFO StartupInfo;
  BOOL bCreated;

  LPTSTR lpCommandLine;

  printf("Launcher application\n");

  lpCommandLine = GetCommandLineA();

  // EXE 명을 커멘드 라인으로부터 없애,
  // 나머지를 리플 기동 어플리케이션에 건네준다.

  while(*lpCommandLine && *lpCommandLine! = ' ') lpCommandLine++;

  printf("passing command line: %s\n", lpCommandLine);

  memset(&StartupInfo, 0, sizeof(StartupInfo));
  StartupInfo.cb = sizeof(StartupInfo);

  bCreated=CreateProcessA(
    "duel.exe",
    lpCommandLine,
    NULL,
    NULL,
    TRUE,
    0,
    NULL,
    NULL,
    &StartupInfo,
    &ProcInfo);

  if(bCreated){
    printf("Waiting for application to exit\n");
    WaitForSingleObject(ProcInfo.hThread, INFINITE);
  } else {
    printf("Failed to create process\n");
  }

  printf("launcher application has left the building...\n");

  return 0;
}
[Visual Basic]

어플리케이션으로 리플 기동을 지원 하기 위해서는,DirectPlayLobby3.RegisterApplication 에 DPAPPLICATIONDESC2 형을 건네주어, 그 어플리케이션을 등록할 필요가 있다. 이 형태에는, 란체의 이름을 보관 유지하는 strAppLauncherName 라고 하는 멤버가 포함되어 있다. 란체는 어플리케이션과 같은 디렉토리에 위치하고 있을 필요가 있다.

로비 클라이언트가 DirectPlayLobby3.RunApplication 를 호출해 어플리케이션을 실행 하면, DirectPlay 는 레지스트리내에서 란체의 이름을 검색해, 어플리케이션은 아니고, 란체를 실행한다. 어플리케이션을 실행하는 것은 란체의 역할이다.

란체는, 건네받은 커멘드 라인 파라미터를 어플리케이션에 모두 건네줄 필요가 있다. 어플리케이션은, 이해할 수 없는 커멘드 라인 파라미터를 단순하게 무시한다.

어플리케이션은,DirectPlayLobby3.WaitForConnectionSettings 를 사용하기 전에, 최저 1 회는 반드시 DirectPlayLobby3.GetConnectionSettings 를 호출한다 ( 「동적 로비 접속의 지원」을 참조).

이하의 예는, 리플 기동의 어플리케이션을 등록하는 방법을 나타내고 있다. DPLobby3 는,DirectPlayLobby3 오브젝트이다.

Dim dpad2 As DPAPPLICATIONDESC2

With dpad2
  . lFlags = 0
  . strAppLauncherName= "launcher.exe"
  . strApplicationName= "MyApp"
  . strCommandLine= "/lobbied"
  . strCurrentDirectory= "C:\games"
  . strDescription= "My Application"
  . strFilename= "myapp.exe"
  . strGuid = "{AC330441-9B71-11D2-9AAB-0020781461AC}"
  . strPath= "C:\games"
End With

Call DPLobby3.RegisterApplication(dpad2)


동적 로비 접속의 지원

외부 로비 기동의 결점은, 어플리케이션의 인스턴스가 이미 실행중의 경우에서도, 로비 서버가 로비 클라이언트에 대해서 항상 새로운 인스턴스를 기동하도록(듯이) 지시하는 것이다. 동적 로비 접속을 지원 하면, 장황적인 기동을 피할 수가 있다.

여기서의 설명은, 어플리케이션이 이미 실행중이며, 접속 설정을 돌려주는 로비 서버에의 접속이 확립되어 있는 것을 전제로 한다.

[C++]
  1. 스타트 업시에,CoCreateInstance 함수를 사용해 IDirectPlayLobby3 인터페이스를 생성 한다.
  2. 유저에게, 수동 접속을 확립시키는 것이 아니라,"로비 접속을 기다려 주세요" 또는 그 이펙트를 나타내는 말을 선택시킨다. 그 선택이 실행되었을 경우에 한정해, 이하의 스텝을 실행한다 (이행예에 대해서는, 「Duel 샘플」을 참조).
  3. IDirectPlayLobby3::WaitForConnectionSettings 를 호출해, 어플리케이션을 대기 모드로 한다. 이 때, 실행은 중단되지 않는다. 어플리케이션이 액티브하고, 접속을 대기하고 있다고 하는 것이 DirectPlay 에게 전할 수 있는 것만으로 있다. 따라서, 로비 클라이언트가 DirectPlayLobby3.RunApplication 를 호출해도, 다른 인스턴스는 기동되지 않는다.
  4. IDirectPlayLobby3::ReceiveLobbyMessage 를 사용해, 송신되는 로비 메세지를 대기한다. 대기하는 메세지 타입은 DPLSYS_NEWCONNECTIONSETTINGS 시스템 메세지이다. 유저가 캔슬했을 경우는,WaitForConnectionSettings 를 한번 더 호출해 대기 모드를 캔슬할 수가 있다.
  5. 시스템 메세지를 수신하면(자), 로비에 의해 건네받은 접속 정보를 조사해 필요에 따라서 설정을 변경한다. IDirectPlayLobby3::GetConnectionSettings 메소드는, 접속 설정을 포함한 DPLCONNECTION 구조체를 돌려준다. 새롭게 설정을 실시하려면 ,IDirectPlayLobby3::SetConnectionSettings 를 사용한다.
  6. IDirectPlayLobby3::ConnectEx 를 호출해 어플리케이션 세션을 생성 하는지, 또는 거기에 접속한다 (어플리케이션은 DPLCONNECTION.dwFlags 를 조사해, 세션을 생성 하는지, 또는 세션에 참가할까를 판단한다).
  7. 스텝 5 로 취득한 DPLCONNECTION 구조체에 의해 제공되는 이름 정보를 사용해, 플레이어를 생성 한다.
[Visual Basic]
  1. 스타트 업시에,DirectX7.DirectPlayLobbyCreate 메소드를 사용해 DirectPlayLobby3 오브젝트를 생성 한다.
  2. 유저에게, 수동 접속을 확립시키는 것이 아니라,"로비 접속을 기다려 주세요" 또는 그 이펙트를 나타내는 말을 선택시킨다. 그 선택이 실행되었을 경우에 한정해, 이하의 스텝을 실행한다
  3. DirectPlayLobby3.WaitForConnectionSettings 를 호출해, 어플리케이션을 대기 모드로 한다. 이 때, 실행은 중단되지 않는다. 어플리케이션이 액티브하고, 접속을 대기하고 있다고 하는 것이 DirectPlay 에게 전할 수 있는 것만으로 있다. 따라서, 로비 클라이언트가 DirectPlayLobby3.RunApplication 를 호출해도, 다른 인스턴스는 기동되지 않는다.
  4. DirectPlayLobby3.ReceiveLobbyMessage 를 사용해, 송신되는 로비 메세지를 대기한다. 대기하는 메세지 타입은, DPLSYS_NEWCONNECTIONSETTINGS 시스템 메세지이다. 유저가 캔슬했을 경우는,WaitForConnectionSettings 를 한번 더 호출해 대기 모드를 캔슬할 수가 있다.
  5. 시스템 메세지를 수신하면(자), 로비에 의해 건네받은 접속 정보를 조사해 필요에 따라서 설정을 변경한다. DirectPlayLobby3.GetConnectionSettings 메소드는, 접속 설정을 포함한 DirectPlayLobbyConnection 오브젝트를 돌려준다. 새롭게 설정을 실시하려면 ,DirectPlayLobby3.SetConnectionSettings . (을)를 사용한다.
  6. DirectPlayLobby3.Connect 를 호출해 어플리케이션 세션을 생성 하는지, 또는 거기에 접속한다 (어플리케이션은,DirectPlayLobbyConnection.GetFlags 에 의해 돌려주어지는 값을 조사해, 세션을 생성 하는지, 또는 세션에 참가할까를 판단한다).
  7. 스텝 5 로 취득한 DirectPlayLobbyConnection 오브젝트에 의해 제공되는 이름 정보를 사용해, 플레이어를 생성 한다.


로비와의 관계의 유지

어플리케이션에서는, 로비에 의해 기동되거나 로비에 동적으로 접속한 다음에, 로비와의 정보의 교환을 계속하고 싶은 경우가 있다. 예를 들어, 로비 서버에서는, 현재 게임에 참가하고 있는 플레이어의 인원수나 그 스코아를 로비내외의 유저에게 표시하기 위해서, 이러한 정보를 추적하고 싶은 경우가 있다. 같이 플레이어나 게임의 구성이 어플리케이션 자체는 아니고, 로비에서 설정되어 있는 경우에는, 그러한 데이터를 수신하고 싶은 경우도 있다.

[C++]

로비와 메세지를 교환하려면 ,IDirectPlayLobby3::SendLobbyMessage 메소드와 IDirectPlayLobby3::ReceiveLobbyMessage 메소드를 사용한다.

정보는, 프로퍼티를 설정하는 것으로써, 로비에 송신된다. 어플리케이션은,DPLMSG_SETPROPERTY 메세지 구조체를 생성 해 데이터를 대입해,SendLobbyMessage 메소드를 사용해 그것을 로비에 송신할 필요가 있다. 각 프로퍼티는, 데이터의 개별의 타입을 식별한다. 어플리케이션 개발자는, 디자인시에, 설정 가능한 각 프로퍼티에 GUID 를 할당한다. 로비 오퍼레이터는, 이 GUID 의 리스트와 각 프로퍼티의 설명 및 데이터 구조체를 어플리케이션 개발자로부터 취득할 필요가 있다.

어플리케이션은, 프로퍼티가 올바르게 설정된 것의 확인을 요구할 수가 있다. 거기에는,DPLMSG_SETPROPERTY.dwRequestID 에 제로 이외의 값을 지정한다. 하면, 로비는 DPLMSG_SETPROPERTYRESPONSE 메세지를 돌려준다.

로비로부터 정보를 취득 하면 간, 똑같이 프로퍼티를 요구한다. 어플리케이션은,DPLMSG_GETPROPERTY 구조체에 데이터를 대입해,SendLobbyMessage 메소드를 사용해 그것을 로비에 송신한다. 로비는, 요구된 프로퍼티 데이터를 포함한 DPLMSG_GETPROPERTYRESPONSE 구조체를 돌려준다. 방금전같이, 어플리케이션 개발자는 각 프로퍼티에 대한 GUID 를 생성 해, 그것들을 로비 개발자와 공유한다.

모든 로비가 이러한 표준의 로비 메세지를 지원 할 수 있는 것은 아니다. 어플리케이션에서는, 기동원의 로비가 표준의 로비 메세지를 지원 하고 있을지 어떨지를 판단할 수가 있다. 거기에는,DPLMSG_GETPROPERTY 메세지를 송신해,DPLPROPERTY_MessagesSupported 프로퍼티를 요구한다.

상세한 것에 대하여는, 「DirectPlay 정의가 끝난 프로퍼티」를 참조할것.

[Visual Basic]

로비와 메세지를 교환하려면 ,DirectPlayLobby3.SendLobbyMessage 메소드와 DirectPlayLobby3.ReceiveLobbyMessage 메소드를 사용한다.

정보는, 프로퍼티를 설정하는 것으로써, 로비에 송신된다. 어플리케이션은,DirectPlayMessage.WriteLong 메소드와 DirectPlayMessage.WriteGuid 메소드를 사용해,DPLMSG_SETPROPERTY C 구조체와 같은 순서로 데이터를 포함한 DirectPlayMessage 오브젝트를 생성 할 필요가 있다.

로비로부터 정보를 취득 하면 간, 똑같이 프로퍼티를 요구한다. 어플리케이션은,DPLMSG_GETPROPERTY C 구조체에 포함되어 있는 데이터와 같은 데이터를 포함한 메세지를 생성 해, 그것을 로비에 송신한다. 로비는, 요구된 프로퍼티 데이터를 포함한 DPLMSG_GETPROPERTYRESPONSE 메세지를 돌려준다. 데이터를 취득하려면 ,DirectPlayMessage.ReadLong 메소드와 DirectPlayMessage.ReadGuid 메소드를 사용한다.

상세한 것에 대하여는, 이 주제의 C++ 의 기술을 참조할것.


DirectPlay 메세지

어플리케이션으로플레이어를 생성 하면, 그 플레이어는세션에 참가하고 있는 것 외의 플레이어와플레이어 메세지를 교환할 수가 있다. 게다가 DirectPlay 자체가시스템 메세지를 생성 해, 플레이어에게 이벤트를 통지한다. 이 이벤트에는, 플레이어의 세션에의 참가나 퇴출등이 포함된다.

플레이어 메세지는, 개별의 플레이어, 모든 플레이어, 그룹으로서 정의된 플레이어의 서브 세트의 어느 쪽인가에 송신할 수가 있어 송신측 플레이어의 ID 에 의해 식별된다. 시스템 메세지는, 세션에 참가하고 있는 모든 플레이어에게 송신되어 정수 DPID_SYSMSG 와 같은 값의 송신측 ID 를 보관 유지한다.

어플리케이션이 수신한 메세지는, 모두 수신 큐에 넣어진다. 어플리케이션은, 각 메세지를 큐로부터 꺼내, 거기에 응해 동작할 필요가 있다. 어플리케이션은, 수신 큐를 폴링 해 메세지를 조사하는지, 새로운 메세지가 도착했다고 하는 통지에 대한 동기 이벤트에 의존할 수가 있다.

이하의 주제에서는, DirectPlay 로 메세지를 사용하는 방법에 대해 자세하게 설명한다.

  • 메세지의 수신
  • 동기화
  • 플레이어 메세지의 사용
  • 시스템 메세지의 사용
  • 비동기 메시징
  • 로비 메세지의 사용


메세지의 수신

[C++]

어플리케이션은,IDirectPlay4::Receive 를 호출해, 큐안의 다음의 메세지를 꺼낸다.

2 명 이상의 로컬 플레이어가 있는 경우 (즉, 어플리케이션의 해당의 인스턴스에 의해, 2 명 이상의 플레이어가 생성 되고 있는 경우)는, 메세지의 송신측의 플레이어의 ID 를 Receive 메소드의 lpidTo 파라미터에 건네주어, DPRECEIVE_TOPLAYER 플래그를 설정할 필요가 있다.

메세지 데이타를 뽑기 시작하려면 , 최초로 적절한 양의 메모리를 할당할 필요가 있다. 필요한 버퍼의 사이즈를 판단하려면 , 최초로 lpData 파라미터에 NULL 를 설정해 메소드를 호출하는지, 또는 임의의 사이즈의 기존의 버퍼에의 포인터를 건네주어,*lpdwDataSize 에 현재의 길이를 설정한다. 대기중의 메세지가 있는데,lpData 가 NULL 인지, 또는 버퍼의 사이즈가 너무 작은 경우, 메소드는 DPERR_BUFFERTOOSMALL 로 실패해, 필요한 메모리량이 *lpdwDataSize 에 돌려주어진다. 그 경우는, 할당을 재차 실행해 메소드를 재시행한다.

메소드가 성공해, 버퍼에 메세지 데이터가 넣을 수 있으면(자), 그 메세지가 시스템 메세지의 경우는,*lpidFrom 가 DPID_SYSMSG 에 동일해진다. 그 경우는, 「시스템 메세지의 사용」의 스텝에 따른다. 그렇지 않은 경우는, 「플레이어 메세지의 사용」의 스텝에 따른다.

이 처리의 예에 대해서는,Duel 샘플의 ReceiveMessages 함수를 참조할것.

[Visual Basic]

DirectPlay4.Receive 메소드는, 큐안의 다음의 메세지를 꺼내, 메세지 데이터를 포함한 DirectPlayMessage 오브젝트를 돌려준다. 게다가 이 메소드는 송신측의 플레이어의 ID (시스템 메세지의 경우는 DPID_SYSMSG)와 수신측의 플레이어의 ID 를 돌려준다. 이것들은, 메소드에게 건네진 변수에 돌려주어진다.

2 명 이상의 로컬 플레이어가 있는 경우 (즉, 어플리케이션의 해당의 인스턴스에 의해, 2 명 이상의 플레이어가 생성 되고 있는 경우)는, 메세지의 송신측의 플레이어의 ID 를 Receive 메소드의 toPlayerId 파라미터에 건네주어, DPRECEIVE_TOPLAYER 플래그를 설정할 필요가 있다.

이하의 샘플 함수는, 대기중의 메세지를 모두 꺼낸다.

' gObjDPlay 는 DirectPlay4 오브젝트.
' gMyPlayerID 는 플레이어의 ID.

Sub ReceiveMessages
    Dim MsgCount as Long
    Dim MsgType as Long
    Dim FromPlayerID As Long
    Dim ToPlayerID As Long
    Dim dpMsg as DirectPlayMessage

    MsgCount = gObjDPlay.GetMessageCount(gMyPlayerID)
    For X% = 1 to MsgCount
        Set dpMsg = gObjDPlay.Receive(FromPlayerID, _
            ToPlayerID, DPRECEIVE_ALL)
        If FromPlayerID = DPID_SYSMSG Then
            MsgType = dpMsg.ReadLong()
           '여기서 시스템 메세지를 처리한다.
        Else
           '여기서 플레이어 메세지를 처리한다.
        End If
    Next X
End Sub

수신한 메세지의 처리 방법의 상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 시스템 메세지의 사용
  • 플레이어 메세지의 사용
  • 로비 메세지의 사용


동기화

[C++]

어플리케이션으로 DirectPlay 의 메세지를 취득하기 위해서 사용할 수 있는 방법은 2 개 있다. 1 개(살)은, 어플리케이션의 메인 루프로 수신 큐를 체크하는 방법이다. 이것은 보통, 어플리케이션이 싱글스 레드인 것을 의미한다.

이제(벌써) 1 개(살)은, 어플리케이션으로 독립한 thread를 확보해, 메세지를 대기해 그것을 처리하는 방법이다. 이 경우, 어플리케이션은 플레이어를 생성 할 경우에, 비 NULL 의 자동 리셋 동기 이벤트 (Win32® 의 CreateEvent 함수를 참조)에의 핸들을 제공할 필요가 있다. DirectPlay 는, 생성 된 플레이어에 대한 메세지가 도착했을 때에, 이 이벤트를 설정한다.

계속되어, 메세지 처리 thread는 Win32 의 WaitForSingleObject 함수를 사용해, 이벤트가 설정되는 것을 대기한다. DPERR_NOMESSAGES 가 돌려주어져 메시지 큐에 메세지가 남지 않은 것이 나타날 때까지,IDirectPlay4::Receive 를 계속 호출한다.

어플리케이션으로 복수의 로컬 플레이어를 생성 하는 경우는, 모든 플레이어가 같은 이벤트를 공유하는지, 또는 각 플레이어가 독립한 이벤트를 확보할 수가 있다.

[Visual Basic]

어플리케이션으로 DirectPlay 의 메세지를 취득하기 위해서 사용할 수 있는 방법은 2 개 있다. 1 개(살)은, 어플리케이션의 메인 루프로 수신 큐를 체크하는 방법이다. Visual Basic 에서는, 이하의 샘플 코드에 나타내도록(듯이),Sub Main 로 메세지를 폴링 할 수가 있다.

Public Sub Main()

    Do While DoEvents()  '이벤트 처리를 허가한다.
        ReceiveMessages  ' 「메세지의 수신」을 참조.
    Loop
End Sub

이제(벌써) 1 개(살)은, 플레이어가 메세지를 수신할 때마다 신호되는 이벤트를 생성 하는 방법이다. 이 방법을 이용하려면 , 폼 또는 클래스 모듈에 DirectXEvent 클래스를 이행 해,DirectXEvent.DXCallBack 메소드를 준비할 필요가 있다. 계속되어,DirectX7.CreateEvent 메소드에 DirectXEvent 오브젝트 (보통은,DirectXEvent 클래스를 이행 하는 폼)를 건네주어 이벤트 핸들을 취득해, 그 핸들을 DirectPlay4.CreatePlayer 메소드의 receiveEvent 파라미터에 건네준다. 하면, 메세지가 그 플레이어의 수신 큐에 넣어질 때마다 DXCallBack 메소드가 자동적으로 불려 간다. 어플리케이션은, 이 프로시저내에서 큐로부터 임의의 보류 메세지를 꺼낼 수가 있다.

어플리케이션으로 복수의 로컬 플레이어를 생성 하는 경우는, 모든 플레이어가 같은 이벤트를 공유하는지, 또는 각 플레이어가 독립한 이벤트를 확보할 수가 있다.


플레이어 메세지의 사용

[C++]

플레이어 메세지는,IDirectPlay4::Send 또는 IDirectPlay4::SendEx 를 사용해 송신할 수가 있다. SendEx 에 의해 송신되는 메세지에는, 우선 순위를 할당할 수가 있다. 우선 순위의 높은 메세지가 최초로 송신된다. 우선 순위는, 메세지의 수신 순위에는 영향을 주지 않는다.

플레이어 메세지내의 데이터의 편성은, 어플리케이션에 의해서만 결정할 수 있다. 관례에서는, 최초의 요소는, 어플리케이션으로 정의되는 메세지 식별자이다.

보통, C++ 어플리케이션은,IDirectPlay4::Receive 를 사용해 메세지 버퍼를 취득해, 그것을 DPMSG_GENERIC 에 캐스트 해, 메세지가 DPID_SYSMSG 로부터 송신된 것 화도인지를 확인한다. DPID_SYSMSG 로부터 송신된 것이 아닌 경우, 어플리케이션은 데이터를 어플리케이션으로 정의된 범용 타입에 캐스트 해, 그 구조 체내의 메세지 타입을 확인해, 그 메세지에 적절한 어플리케이션 정의 타입에 재차 캐스트 한다. 예로서 「Duel 샘플」을 참조할것. 여기에서는, ReceiveMessages 함수와 DoApplicationMessage 함수를 사용하고 있다.

[Visual Basic]

플레이어 메세지는,DirectPlay4.Send 또는 DirectPlay4.SendEx . (을)를 사용해 송신할 수가 있다. SendEx 에 의해 송신되는 메세지에는, 우선 순위를 할당할 수가 있다. 우선 순위의 높은 메세지가 최초로 송신된다. 우선 순위는, 메세지의 수신 순위에는 영향을 주지 않는다.

플레이어 메세지내의 데이터의 편성은, 어플리케이션에 의해서만 결정할 수 있다. 관례에서는, 최초의 요소는, 어플리케이션으로 정의되는 메세지 식별자이다.

메세지 데이터는,DirectPlayMessage 오브젝트에 의해 나타내진다. 송신측의 어플리케이션은,DirectPlay4.CreateMessage 메소드를 사용해, 이 오브젝트를 취득한다.

플레이어 메세지의 데이터를 구축하는 방법은 2 개 있다. 1 개(살)은,DirectPlayMessage 의 다양한 기술용 메소드를 사용해, 데이터의 요소를 1 개씩 기술하는 방법이다. 각 요소를 기술할 때 마다, 내부의 기술 포인터가 진행된다. 이제(벌써) 1 개(살)은,DirectPlayMessage.SetMessageData 에 유저 정의형을 건네주는 방법이다. 대부분의 어플리케이션에서는, 최초의 방법을 사용한다. 이것은,SetMessageData 를 사용하려면 , 메소드에게 건네지는 데이터의 정확한 사이즈를 파악하고 있을 필요가 있기 때문이다. 이 사이즈는, 항상 간단하게 파악할 수 있다고는 할 수 없다.

주 : 메세지 데이터를 설정하기 위한 이것들 2 개의 방법을 조합해 사용할 수 없다. 예를 들어,DirectPlayMessage.WriteLong 를 사용해 메세지 타입을 기술하고 나서,SetMessageData 를 사용해 추가 데이터를 기술할 수 없다. SetMessageData 는, 메세지의 내용 전체를 설정한다.

데이터를 메세지로부터 취득하려면 ,DirectPlayMessage 의 대응하는 읽기용 메소드를 사용하는지, 또는 DirectPlayMessage.GetMessageData 를 사용한다. 읽기 메소드를 사용할때, 어플리케이션은 데이터 요소가 기술된 순서와 같은 순서로 읽어낼 필요가 있다. GetMessageData 는, 데이터가 SetMessageData 에 의해 설정되었을 경우에게만 사용한다.


시스템 메세지의 사용

[C++]

IDirectPlay4::Receive 메소드에 의해 DPID_SYSMSG 라고 하는 플레이어 ID 로부터 돌려주어지는 메세지는, 시스템 메세지이다. 모든 시스템 메세지는,dwType 의 값에 의해 지정되는 식별자로부터 시작된다. IDirectPlay4::Receive 메소드에 의해 돌려주어지는 버퍼를 범용 메세지 (DPMSG_GENERIC )에 캐스트 해,dwType 요소를 조사할 수가 있다. 이 요소는, DPSYS_ 라고 하는 접두사가 붙는 메세지 타입 식별자의 어느 쪽인가에 동일한 값을 가진다. 어플리케이션으로 시스템 메세지의 종류를 판단하면(자), 버퍼를 적절한 구조체 (접두사 DPMSG_ 로 시작된다)에 캐스트 해, 데이터를 읽어낸다.

어플리케이션에서는, 이하의 시스템 메세지를 처리할 수 있도록(듯이) 해 둘 필요가 있다.

dwType 의 값 | 메세지 구조체 | 원인
DPSYS _ADDGROUPTOGROUP | DPMSG_ADDGROUPTOGROUP | 기존의그룹에 기존의 그룹이 추가되었다.
DPSYS _ADDPLAYERTOGROUP | DPMSG_ADDPLAYERTOGROUP | 기존의 그룹에 기존의 플레이어가 추가되었다.
DPSYS_CHAT | DPMSG_CHAT | 채팅 메세지가 도착했다.
DPSYS _CREATEPLAYERORGROUP | DPMSG_CREATEPLAYERORGROUP | 새로운 플레이어 또는 그룹이 생성 되었다.
DPSYS _DELETEGROUPFROMGROUP | DPMSG_DELETEGROUPFROMGROUP | 그룹이 그룹으로부터 삭제되었다.
DPSYS _DELETEPLAYERFROMGROUP | DPMSG_DELETEPLAYERFROMGROUP | 플레이어가 그룹으로부터 삭제되었다.
DPSYS _DESTROYPLAYERORGROUP | DPMSG_DESTROYPLAYERORGROUP | 기존의 플레이어 또는 그룹이 파기되었다.
DPSYS_HOST | DPMSG_HOST | 현재의호스트가세션을 멀어져 이 어플리케이션이 새로운 호스트가 되었다.
DPSYS _SECUREMESSAGE | DPMSG_SECUREMESSAGE | 디지털 서명 또는 암호화가 베풀어진 메세지가 도착했다.
DPSYS _SENDCOMPLETE | DPMSG_SENDCOMPLETE | 비동기 송신이 완료했다.
DPSYS _SESSIONLOST | DPMSG_SESSIONLOST | 세션의 접속이 없어졌다.
DPSYS _SETGROUPOWNER | DPMSG_SETGROUPOWNER | 그룹의 소유자가 변경되었다.
DPSYS _SETPLAYERORGROUPDATA | DPMSG_SETPLAYERORGROUPDATA | 플레이어 또는 그룹의 데이터가 변경되었다.
DPSYS _SETPLAYERORGROUPNAME | DPMSG_SETPLAYERORGROUPNAME | 플레이어 또는 그룹의 이름이 변경되었다.
DPSYS _SETSESSIONDESC | DPMSG_SETSESSIONDESC | 세션 기술이 변경되었다.
DPSYS _STARTSESSION | DPMSG_STARTSESSION | 로비 서버가, 세션을 시작 하도록(듯이) 요구하고 있다.

[Visual Basic]

DirectPlay4.Receive 메소드에 의해 돌려주어져 플레이어 ID DPID_SYSMSG 로부터의 것이라고 마크 되고 있는 메세지는, 시스템 메세지이다. 모든 시스템 메세지는,Long 라고 하는 형태 식별자로부터 시작된다.

시스템 메세지를 해석하려면 , 최초로 DirectPlayMessage.ReadLong 메소드를 사용해, 그 형태 식별자를 취득할 필요가 있다. 다음에,DirectPlayMessage 의 다양한 읽기 메소드를 사용해, 메세지 데이터의 요소를 꺼낸다. 요소는, 메세지 타입에 기재되어 있는 것과 같은 순서로 꺼낼 필요가 있다 ( 「CONST_DPSYSMSGTYPES 」를 참조).

플레이어 메세지와 시스템 메세지에 사용되는 표준의 읽기 메소드에 가세해, DirectPlay 는 시스템 메세지를 해석하기 위한 이하의 메소드를 제공한다.

  • DirectPlayMessage.MoveToSecureMessage
  • DirectPlayMessage.ReadSysMsgData
  • DirectPlayMessage.ReadSysChatString
  • DirectPlayMessage.ReadSysMsgConnection
  • DirectPlayMessage.ReadSysMsgSessionDesc

ReadSysChatString,ReadSysMsgConnection, 및 ReadSysMsgSessionDesc 는, 읽기 포인터의 위치에 관계없이 호출할 수가 있다. 또, 이러한 메소드를 호출해도, 읽기 포인터는 진행되지 않는다. 한편,ReadSysMsgData 를 호출할 수 있는 것은, 메세지내의 앞의 데이터가 모두 꺼내지고 있는 경우 뿐이다. 또, 이 메소드를 호출하면, 읽기 포인터가 진행된다. 이것은, 최초의 3 개의 메소드는 사용하는 데이터의 기반이 되는 메세지 구조 체내에서의 장소를 항상 파악하고 있지만,ReadSysMsgData 를 사용 하면, 다른 메세지 타입이 다른 장소로부터 데이타를 뽑기 시작할 수가 있기 때문이다.


비동기 메시징

메세지를 비동기에게 송신할 수 있으면, 어플리케이션의 통신 코드가 각 메세지를 전송 하는 동안에 제어를 독점하는 것을 피할 수가 있다. 이것에 의해, 송출하는 메세지를 관리하기 위한 부담을 DirectPlay 에 전가해, 게다가 어플리케이션으로 메시지 큐를 감시해 메세지를 캔슬하는 것이 가능하게 된다.

비동기 메시징 기능은,세션으로 DirectPlay 프로토콜을 사용하고 있는지, 또는 서비스 프로바이더에 의해 이 기능이 지원 되고 있는 경우에게만 이용할 수 있다. 예를 들어,TCP/IP 서비스 프로바이더는, 컴퓨터가 Windows Sockets 2.0 이후를 사용하고 있는 경우만, 비동기 메세지를 지원 한다.

[C++]

DirectPlay 프로토콜을 사용하고 있지 않는 경우는, 세션이 확립한 후에 IDirectPlay4::GetCaps 메소드를 사용해 DPCAPS_ASYNCSUPPORTED 플래그를 조사해 비동기 메세지가 지원 되고 있는지 어떤지를 판단하는 것이 중요하다.

비동기 메세지를 송신하려면 ,IDirectPlay4::SendEx 메소드를 사용한다. 이 때,dwFlags 파라미터에 DPSEND_ASYNC 플래그를 설정한다. SendEx 는, 즉시 돌아온다. 잠시 후에, 어플리케이션은 송신한 메세지의 결과를 나타내는 상태를 포함한 DPMSG_SENDCOMPLETE 시스템 메세지를 수신한다. 이 통지가 실행되지 않게 하려면 , 메세지를 송신할 경우에 DPSEND_NOSENDCOMPLETEMSG 플래그를 설정한다. 어플리케이션은,SendEx 에 의해 돌려주어지는 dwMsgID 파라미터를 사용해, 각각의 메세지를 추적할 수가 있다. 이 ID 는, 각각의 메세지를 캔슬하거나 완료 통지 메세지와 비교할 때에 사용할 수가 있다.

SendEx 를 사용 하면, 타임 아웃값과 우선 순위를 지원 하는 세션내의 메세지에, 그러한 값을 할당할 수가 있다. 또,IDirectPlay4::CancelMessage 메소드 또는 IDirectPlay4::CancelPriority 메소드를 사용해, 송신 큐내의 메세지를 캔슬할 수도 있다. 타임 아웃, 우선 순위, 및 캔슬의 기능에는, DirectPlay 프로토콜 또는 서비스 프로바이더에 의한 지원이 필요하다. 이것들은,IDirectPlay4::GetCaps 메소드에 의해 판단된다.

[Visual Basic]

DirectPlay 프로토콜이 사용되어 있지 않은 경우는, 세션이 확립한 다음에 DirectPlay4.GetCaps 메소드를 사용해 DPCAPS_ASYNCSUPPORTED 플래그를 체크해, 비동기 메세지가 지원 되고 있는지 어떤지를 확인하는 것이 중요하다.

비동기 메세지를 송신하려면 ,DirectPlay4.SendEx 메소드를 사용한다. 이 때,flags 파라미터에 DPSEND_ASYNC 플래그를 설정한다. SendEx 는 즉시 돌아온다. 잠시 후에, 어플리케이션은 송신한 메세지의 결과를 나타내는 상태를 포함한 DPMSG_SENDCOMPLETE 시스템 메세지를 수신한다. 이 통지가 실행되지 않게 하려면 , 메세지를 송신할 경우에 DPSEND_NOSENDCOMPLETEMSG 플래그를 설정한다. 어플리케이션은,SendEx 에 의해 돌려주어지는 dwMsgID 파라미터를 사용해, 각각의 메세지를 추적할 수가 있다. 이 ID 는, 각각의 메세지를 캔슬하거나 완료 통지 메세지와 비교할 때에 사용할 수가 있다.

SendEx 를 사용 하면, 타임 아웃값과 우선 순위를 지원 하는 세션내의 메세지에, 그러한 값을 할당할 수가 있다. 또,DirectPlay4.CancelMessage 메소드 또는 DirectPlay4.CancelPriority 메소드를 사용해, 송신 큐내의 메세지를 캔슬할 수도 있다. 타임 아웃, 우선 순위, 및 캔슬의 기능에는, DirectPlay 프로토콜 또는 서비스 프로바이더에 의한 지원이 필요하다. 이것들은,DirectPlay4.GetCaps 메소드에 의해 판단된다.

비동기 메세지와 동기 메세지를 조합해 사용하는 경우는, 충분한 주의가 필요하다. 큐내의 비동기 메세지에 이어 동기 메세지가 송신되면(자), 그 동기 메세지가 완료할 때까지, 제어가 블록 된다.

타임 아웃과 우선 순위가 지원 되고 있는 경우는, 이것들을 동기 메세지로 사용할 수 있다. ID에 의한 메세지의 추적과 캔슬은, 동기 메세지에는 적용되지 않는다.

비동기 메시징은, 대역폭을 확대하거나 대기 시간을 경감하거나 하는 것은 아니다.

비동기 메세지를 효과적으로 사용하는 방법의 상세한 것에 대하여는, 「DirectPlay 프로토콜을 사용한 비동기 네트워킹」을 참조할것.


로비 메세지의 사용

로비 메세지는, 2 개의 카테고리로 나눌 수가 있다. 즉, DirectPlay 에 의해 정의되는 메세지와 어플리케이션에 의해 정의되는 메세지이다.

DirectPlay 정의의 메세지는, DirectPlay 에 의해 자동적으로 생성되어 어플리케이션의 변경을 통지하기 위해서 로비에 송신되는 시스템 메세지인가, 어플리케이션과 로비의 사이에 교환되는 표준의 메세지 타입의 언젠가이다.

어플리케이션 정의의 메세지에 대한 표준 메세지의 이점은, 수신측이 항상 표준 메세지를 해석할 수 있다고 하는 것이다. 로비 클라이언트는, 반드시 어플리케이션으로부터의 커스텀 메세지를 처리할 수 있다고는 할 수 없다. 또, 어플리케이션도 로비 클라이언트로부터의 커스텀 메세지를 처리할 수 없는 경우가 있다.

[C++]

로비 메세지를 수신하려면 ,IDirectPlayLobby3::ReceiveLobbyMessage 메소드를 사용한다. 메세지의 카테고리는,lpdwMessageFlags 파라미터를 조사하는 것에 의해 판단할 수가 있다. DPLMSG_SYSTEM 또는 DPLMSG_STANDARD 가 어느 쪽도 아닌 경우, 메세지는 어플리케이션 정의이다.

로비는, 모든 표준 메세지를 처리할 수 있을 필요가 있다. 어플리케이션으로 DPLMSG_GETPROPERTY 메세지를 사용하는 경우는,DPLMSG_GETPROPERTYRESPONSE 메세지를 처리할 수 있을 필요가 있다 ( 「로비와의 관계의 유지」를 참조).

DirectPlay 정의의 메세지는, 모두 메세지 타입을 나타내는 DWORD 값으로부터 시작된다. ReceiveLobbyMessage 를 사용해 메세지를 취득하면(자),*lpData 를 DPLMSG_GENERIC 구조체에 캐스트 해, 그 구조체의 dwType 멤버를 조사한다. 계속되어,*lpData 를 적절한 메세지 구조체에 캐스트 해, 이후의 처리에 대비한다.

이하는, 표준 메세지에 대한 DPLMSG_GENERIC.dwType 의 값과 각각의 값의 구조체 및 원인을 나타내고 있다.

dwType 의 값 | 메세지 구조체 | 원인
DPLSYS _APPTERMINATED | DPLMSG_SYSTEMMESSAGE | 어플리케이션이 종료했다.
DPLSYS _CONNECTIONSETTINGSREAD | DPLMSG_SYSTEMMESSAGE | 어플리케이션이 접속 설정을 읽어냈다.
DPLSYS _DPLAYCONNECTFAILED | DPLMSG_SYSTEMMESSAGE | 어플리케이션이 DirectPlay 세션에의 접속에 실패했다.
DPLSYS _DPLAYCONNECTSUCCEEDED | DPLMSG_SYSTEMMESSAGE | 어플리케이션이 DirectPlay 세션에의 접속에 성공했다.
DPLSYS _GETPROPERTY | DPLMSG_GETPROPERTY | 어플리케이션이 로비의 프로퍼티를 요구하고 있다. 「로비와의 관계의 유지」를 참조.
DPLSYS _GETPROPERTYRESPONSE | DPLMSG_GETPROPERTYRESPONSE | 로비가 DPLMSG_GETPROPERTY 메세지에 응답하고 있다. 「로비와의 관계의 유지」를 참조.
DPLSYS _NEWCONNECTIONSETTINGS | DPLMSG_SYSTEMMESSAGE | 로비 클라이언트가 RunApplication 를 호출했을 때에, 대기중의 어플리케이션이 발견되었다. 「동적 로비 접속의 지원」을 참조.
DPLSYS _NEWSESSIONHOST | DPLMSG_NEWSESSIONHOST | 어플리케이션 세션의 소유자가 새로워졌다.
DPLSYS _SETPROPERTY | DPLMSG_SETPROPERTY | 어플리케이션이 로비의 프로퍼티를 설정해 있다. 「로비와의 관계의 유지」를 참조.
DPLSYS _SETPROPERTYRESPONSE | DPLMSG_SETPROPERTYRESPONSE | 로비가 DPLMSG_SETPROPERTY 메세지에 응답하고 있다. 「로비와의 관계의 유지」를 참조.

[Visual Basic]

로비 메세지를 수신하려면 ,DirectPlayLobby3.ReceiveLobbyMessage 메소드를 사용한다. 메세지의 카테고리는,messageFlags 파라미터에 돌려주어지는 값에 의해 판단할 수가 있다. DPLMSG_SYSTEM 또는 DPLMSG_STANDARD 가 어느 쪽도 아닌 경우, 메세지는 어플리케이션 정의이다.

로비는, 모든 표준 메세지를 처리할 수 있을 필요가 있다. 어플리케이션으로 DPLSYS_GETPROPERTY 메세지를 사용하는 경우는, DPLSYS_GETPROPERTYRESPONSE 메세지를 처리할 수 없으면 안 된다 ( 「로비와의 관계의 유지」를 참조).

DirectPlay 정의의 메세지는 모두, 메세지 타입을 식별하는 CONST_DPSYSMSGTYPES 열거형의 값으로부터 시작된다. 이 값을 취득하려면 ,DirectPlayMessage.ReadLong 를 사용한다.

이하는, 메세지 타입과 각각의 값에 관련하는 메세지의 원인을 나타내고 있다.

메세지 타입 | 원인
DPLSYS _APPTERMINATED | 어플리케이션이 종료했다.
DPLSYS _CONNECTIONSETTINGSREAD | 어플리케이션이 접속 설정을 읽어냈다.
DPLSYS _DPLAYCONNECTFAILED | 어플리케이션이 DirectPlay 세션에의 접속에 실패했다.
DPLSYS _DPLAYCONNECTSUCCEEDED | 어플리케이션이 DirectPlay 세션에의 접속에 성공했다.
DPLSYS _GETPROPERTY | 어플리케이션이 로비의 프로퍼티를 요구하고 있다. 「로비와의 관계의 유지」를 참조.
DPLSYS _GETPROPERTYRESPONSE | 로비가 DPLMSG_GETPROPERTY 메세지에 응답하고 있다. 「로비와의 관계의 유지」를 참조.
DPLSYS _NEWCONNECTIONSETTINGS | 로비 클라이언트가 RunApplication 를 호출했을 때에, 대기중의 어플리케이션이 발견되었다. 「동적 로비 접속의 지원」을 참조.
DPLSYS _NEWSESSIONHOST | 어플리케이션 세션의 소유자가 새로워졌다.
DPLSYS _SETPROPERTY | 어플리케이션이 로비의 프로퍼티를 설정해 있다. 「로비와의 관계의 유지」를 참조.
DPLSYS _SETPROPERTYRESPONSE | 로비가 DPLMSG_SETPROPERTY 메세지에 응답하고 있다. 「로비와의 관계의 유지」를 참조.


DirectPlay 주소

DirectPlay 주소는, DirectPlay 가 로비 서버, 어플리케이션, DirectPlay, 및 서비스 프로바이더의 사이에 주소 정보를 건네주기 위해서(때문에) 사용하는 데이터 서식이다. 이 주소는, 가변장 데이터와 GUID 로 구성되어 DirectPlay 가 필요로 하는 주소 정보를 모두 보관 유지한다. 예로서 서버의 네트워크 주소, 플레이어의 네트워크 주소, 세션의 네트워크 주소, 다이얼 업 접속의 모뎀 및 전화번호등이 있다.

DirectPlay 를 사용하기 위해서, DirectPlay 주소를 이해할 필요는 없다. DirectPlay 주소에 대해 배울 필요가 있는 것은, 이하의 어느쪽이든을 실행하는 경우 뿐이다.

  • 표준의 서비스 프로바이더의 다이알로그 박스를 옮겨놓는다. 이 경우는, 사용하는 서비스 프로바이더를 지정해, 그 서비스 프로바이더가 접속을 확립하기 위해서 필요로 하는 정보를 모두 포함한 DirectPlay 주소를 생성 한다. 그 주소를 사용해, 접속을 초기화한다.
  • 외부의 DirectPlay 어플리케이션을 기동하는 로비 클라이언트를 기술한다. 이 로비 클라이언트는, 사용하는 서비스 프로바이더를 지정해, 그 서비스 프로바이더가 접속을 확립해 세션의 클라이언트에 접속하기 위해서 필요로 하는 정보를 모두 포함한 DirectPlay 주소를 생성 할 필요가 있다. 이 정보를, 어플리케이션의 기동시에 건네준다.

상세 정보에 대해서는, 다음의 주제를 참조할것.

  • 서비스 프로바이더 다이얼로그의 치환
  • DirectPlay 주소의 데이터형
  • DirectPlay 주소의 사용예


서비스 프로바이더 다이얼로그의 치환

DirectPlay 가 접속을 열거할 경우에 취득하는 DirectPlay 주소는, 유저가 선택 가능한 등록을 마친 DirectPlay 프로바이더에 지나지 않고, 접속을 확립하기 위해서 필요한 정보를 모두 포함하고 있을 필요는 없다. 이러한 주소의 어느쪽이든을 사용해 세션을 열거 하면, 서비스 프로바이더가 유저에게 추가 정보를 문의하는 경우가 있다.

예를 들어, 유저가 서비스 프로바이더의 리스트로부터 "Modem Connection for DirectPlay" 를 선택해, 어플리케이션이 그 접속을 초기화해 세션의 열거를 시작 하면, 모뎀을 선택해 전화번호를 입력하도록(듯이) 요구하는 다이알로그 박스가 표시된다. 유저가 이 다이알로그 박스를 캔슬 하면, 세션을 생성 할 수 있지만, 기존의 세션에 참가할 수 없다. 유저가 세션의 생성을 선택 하면, 호출에 응답하기 위한 모뎀을 선택 및 구성할 수 있는 다른 다이알로그 박스가 표시된다.

[C++]

이 동작이 바람직하지 않은 경우도 있다. 어플리케이션은, 필요한 접속 정보 (게임을 호스트 하고 있는 중앙 사이트의 IP 주소등)를 이미 보관 유지하고 있는 경우나, 독자적인 인터페이스를 개입시켜 유저로부터 정보를 취득하는 경우도 있다. 이러한 경우, 어플리케이션은 IDirectPlay4::InitializeConnection 에 완전한 접속 정보를 건네주어, 서비스 프로바이더가 추가 정보를 요구하지 않게 할 수가 있다.

DirectPlay 주소를 생성 하려면 ,IDirectPlayLobby3::CreateAddress 메소드 또는 IDirectPlayLobby3::CreateCompoundAddress 메소드를 호출한다. CreateAddress 는, 단일의 요소 (IP 주소등)를 포함하고 있는 단순한 주소의 경우에 한정해 사용할 수 있다. CreateCompoundAddress 를 사용 하면, 모뎀과 전화번호의 양쪽 모두를 포함한 전화 주소 등, 보다 복잡한 주소를 생성 할 수 있다. DirectPlay 로 정의되고 있는 요소의 타입에 대해서는, 「DirectPlay 주소의 데이터형」을 참조할것.

[Visual Basic]

이 동작이 바람직하지 않은 경우도 있다. 어플리케이션은, 필요한 접속 정보 (게임을 호스트 하고 있는 중앙 사이트의 IP 주소등)를 이미 보관 유지하고 있는 경우나, 독자적인 인터페이스를 개입시켜 유저로부터 정보를 취득하는 경우도 있다. 이러한 경우, 어플리케이션은 DirectPlay4.InitializeConnection 에 완전한 접속 정보를 건네주어, 서비스 프로바이더가 추가 정보를 요구하지 않게 할 수가 있다.

DirectPlayLobby3 클래스에는, 다양한 종류의 DirectPlayAddress 오브젝트를 생성하기 위한 이하와 같은 메소드가 있다.

  • CreateComPortAddress
  • CreateCustomAddress
  • CreateINetAddress
  • CreateLobbyProviderAddress
  • CreateModemAddress
  • CreateServiceProviderAddress


DirectPlay 주소의 데이터형

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 용의 DirectX 에서는,DirectPlayAddress 오브젝트의 데이터 서식은, 그 오브젝트를 생성 하기 위해서 사용된 DirectPlayLobby3 에 의해 정해진다.

[C++]

이하는,IDirectPlayLobby3::CreateCompoundAddress 를 사용해 생성 된 DirectPlay 주소에 포함되어 있는 데이타체크 (DPCOMPOUNDADDRESSELEMENT )의 표준의 데이터형을 나타내고 있다.

GuidDataType | lpData
DPAID_ComPort | COM 포트의 모든 설정을 포함한 DPCOMPORTADDRESS 구조체. 시리얼 접속 서비스 프로바이더는, 이 정보를 사용해 시리얼 포트를 구성한다.
DPAID_INet | IP 주소 ("192.168. 0.1" 등) 또는 도메인명 ("microsoft.com" 등)을 포함한, Null 로 끝나는 ANSI 캐릭터 라인. dwDataSize 에는 터미네이터가 포함되어 있을 필요가 있다. 하늘의 주소가 제공되면(자), 인터넷 TCP/IP 접속 서비스 프로바이더는, 이 정보를 사용해 지정된 네트워크 주소 위에의 세션을 열거하는지, 서브 넷상에서 브로드캐스트를 실행한다. 하늘의 주소는, ANSI 의 터미네이터 (0x00)만을 포함한, 길이가 1 바이트의 캐릭터 라인이다.
DPAID_INetW | IP 주소 또는 도메인명을 포함한, Null 로 끝나는 ANSI 캐릭터 라인. dwDataSize 에는 터미네이터가 포함되어 있을 필요가 있다. 하늘의 주소가 제공되면(자), 인터넷 TCP/IP 접속 서비스 프로바이더는, 이 정보를 사용해 지정된 네트워크 주소 위에의 세션을 열거하는지, 서브 넷상에서 브로드캐스트를 실행한다. 하늘의 주소는, Unicode 의 터미네이터 (0x0000)만을 포함한, 길이가 2 바이트의 캐릭터 라인이다.
DPAID_INetPort | 사용하는 특정의 포트 번호를 포함한 정수. TCP/IP 의 포트의 선택에 관한 항목을 참조. 이 DirectPlay 주소의 사용법에 대해서는, 「파이어 월(fire wall)의 지원」을 참조.
DPAID _LobbyProvider | 이 DirectPlay 주소가 적용되는 로비 프로바이더를 지정하는 GUID.
DPAID_Modem | 사용하는 모뎀을 지정하는, NULL 로 끝나는 가변장의 ANSI 캐릭터 라인. dwDataSize 에는 터미네이터가 포함되어 있을 필요가 있다. 모뎀 서비스 프로바이더는, 유저에게 사용하는 모뎀을 묻는 다이알로그 박스를 표시하지 않고 , 이 모뎀을 사용한다.
DPAID_ModemW | 사용하는 모뎀을 지정하는, NULL 로 끝나는 가변장의 Unicode 캐릭터 라인. dwDataSize 에는 터미네이터가 포함되어 있을 필요가 있다. 모뎀 서비스 프로바이더는, 유저에게 사용하는 모뎀을 묻는 다이알로그 박스를 표시하지 않고 , 이 모뎀을 사용한다. 이용 가능한 모뎀을 판단하려면 ,IDirectPlay4::GetPlayerAddress 메소드를 사용한다.
DPAID_Phone | 전화번호를 포함한, NULL 로 끝나는 가변장의 ANSI 캐릭터 라인. dwDataSize 에는 터미네이터가 포함되어 있을 필요가 있다. 모뎀 서비스 프로바이더는,IDirectPlay4::EnumSessions 메소드로 이 전화번호에 전화를 건다. 모뎀이 지정되어 있지 않은 경우는, 최초의 모뎀이 사용된다.
DPAID_PhoneW | 전화번호를 포함한, NULL 로 끝나는 가변장의 Unicode 캐릭터 라인 (LPWSTR). dwDataSize 에는 터미네이터가 포함되어 있을 필요가 있다. 모뎀 서비스 프로바이더는,IDirectPlay4::EnumSessions 메소드로 이 전화번호에 전화를 건다. 모뎀이 지정되어 있지 않은 경우는, 최초의 모뎀이 사용된다.
DPAID _ServiceProvider | 이 DirectPlay 주소가 적용되는 서비스 프로바이더의 16 바이트 GUID.
DPAID_TotalSize | DirectPlay 주소 전체의 사이즈를 포함한 DWORD. 이 데이타체크는,CreateCompoundAddress 에 의해 자동적으로 추가된다.


DirectPlay 주소의 사용예

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 용의 DirectX 에서는,DirectPlayAddress 클래스의 오브젝트가 주소 정보를 보관 유지한다. 이 오브젝트는,DirectPlayLobby3 의 몇개의 메소드에 의해 생성 된다. 상세한 것에 대하여는, 「서비스 프로바이더 다이얼로그의 치환」을 참조할것.

[C++]

여기에서는, DirectPlay 주소와 거기에 포함되는 데이터를, 접속 형태 마다 설명한다.

IPX 접속을 기술하는 DirectPlay 주소

이 접속을 초기화 하면, DirectPlay 오브젝트가 IPX 서비스 프로바이더에 바인드 된다.

guidDataType | dwDataSize | 데이터
DPAID_ServiceProvider | 16 | {685BC400-9D2C-11cf-A9CD-00AA006886E3}

모뎀 접속을 기술하는 DirectPlay 주소

이 접속을 초기화 하면, DirectPlay 가 모뎀 서비스 프로바이더에 바인드 되어 전화번호가 저장 된다. 어플리케이션이 세션의 열거를 시작 하면, 서비스 프로바이더는 유저에게 전화번호를 묻는 일 없이, 이 번호에 전화한다.

guidDataType | dwDataSize | 데이터
DPAID_ServiceProvider | 16 | {44EAA760-CB68-11cf-9C4E-00A0C905425E}
DPAID_Phone | 9 (NULL 터미네이터를 포함한다) | "555-8237"

TCP/IP 접속을 기술하는 DirectPlay 주소

이 접속을 초기화 하면, DirectPlay 가 TCP/IP 서비스 프로바이더에 바인드 되어IP 주소가 저장 된다. 어플리케이션이 세션을 열거 하면 와, 서비스 프로바이더는 유저에게 IP 주소를 묻지 않는다.

guidDataType | dwDataSize | 데이터
DPAID_ServiceProvider | 16 | {36E95EE0-8577-11cf-960C-0080C7534E82}
DPAID_INet | 10 (NULL 터미네이터를 포함한다) | "127.0. 0.1"


DirectPlay 프로토콜

DirectPlay 프로토콜은, 보증되어 있지 않은 서비스 프로바이더상에 있어서의 보증 메시징의 이행이다. 예를 들어, IPX (Internetwork Packet Exchange) 서비스 프로바이더는 그 성질상, 보증 메시징을 지원 하고 있지 않다. 어플리케이션이 IPX 상에서 보증 메세지를 송신하려고 하면(자), DirectPlay 프로토콜이 메세지의 전송을 보증하기 위해서 필요한 처리를 모두 실행한다.

DirectPlay 프로토콜은, 비동기 메시징이라고 메세지의쓰로틀링도 지원 하고 있다. 다만, 서비스 프로바이더가 이러한 기능을 최적화하는 경우도 있다.

어플리케이션은, 세션을 생성 할 경우에 DPSESSION_DIRECTPLAYPROTOCOL 플래그를 설정해, DirectPlay 프로토콜을 기동한다.

시스템 메세지는, 서비스 프로바이더가 보증 메세지를 네이티브에 지원 하고 있을지 어떨지에 관계없이, 또, DirectPlay 프로토콜 플래그를 설정해 둘지 어떨지에 관계없이, 항상 보증 첨부로 송신된다. 시스템 메세지를 보증 첨부로 송신하는 경우는, DirectPlay 프로토콜이 자동적으로 사용된다.

[C++]

시스템 메세지 이외의 경우는, 어플리케이션이 DirectPlay 프로토콜 플래그를 설정해, (IDirectPlay4::SendEx 로 DPSEND_GUARANTEED 플래그를 설정하는 것으로써) 메세지를 보증 첨부로 송신 하면, 서비스 프로바이더가 보증 메세지를 지원 하고 있을지 어떨지에 관계없이, 메세지는 보증 첨부로 송신된다.

[Visual Basic]

시스템 메세지 이외의 경우는, 어플리케이션이 DirectPlay 프로토콜 플래그를 설정해, (DirectPlay4.SendEx 로 DPSEND_GUARANTEED 플래그를 설정하는 것으로써) 메세지를 보증 첨부로 송신 하면, 서비스 프로바이더가 보증 메세지를 지원 하고 있을지 어떨지에 관계없이, 메세지는 보증 첨부로 송신된다.

어플리케이션이 DirectPlay 플래그를 설정하지 않고 메세지를 보증 첨부로 송신 하면, DPSEND_GUARANTEED 플래그에 관계없이, 서비스 프로바이더가 보증 메세지를 지원 하는 경우에 한정해, 전송이 보증된다.

어플리케이션은, 서비스 프로바이더에 의해 이행 된 디폴트의 보증 메시징 대신에, DirectPlay 프로토콜을 사용하도록(듯이) 지정할 수도 있다. 이 지정은, 세션을 생성 할 경우에 DPSESSION_DIRECTPLAYPROTOCOL 플래그를 설정해 실시할 수도 있다.

이하는, 시스템 메세지 이외의 메세지가 송신되는 구조를 집계한 것이다.

DirectPlay 프로토콜 플래그가 설정되어 있지 않은 경우

서비스 프로바이더 | 보증 첨부로 송신되는 메세지가 사용하는 것 | 보증없이 송신되는 메세지가 사용하는 것
IPX | IPX. 보증 첨부에서는 송신되지 않는다 | IPX
TCP/IP | TCP | UDP
모뎀 | 모뎀. 보증 첨부에서는 송신되지 않는다 | 모뎀

DirectPlay 프로토콜 플래그가 설정되어 있는 경우

서비스 프로바이더 | 보증 첨부로 송신되는 메세지가 사용하는 것 | 보증없이 송신되는 메세지가 사용하는 것
IPX | DirectPlayProtocol/IPX | DirectPlayProtocol/IPX
TCP/IP | DirectPlayProtocol/UDP | DirectPlayProtocol/UDP
모뎀 | DirectPlayProtocol/모뎀 | DirectPlayProtocol/모뎀

DirectPlay 프로토콜 플래그가 설정되어 있지 않은 경우, 어플리케이션은 (세션이 열린 후에) 서비스 프로바이더의 능력을 조사해, 비동기 메시징, 메세지의 캔슬, 메세지의 타임 아웃, 메세지의 우선 순위 등에 관련해 이용할 수 있는 기능을 판단할 필요가 있다. DirectPlay 프로토콜 플래그가 설정되어 있는 경우는, 이러한 기능을 모두 이용할 수 있다.


DirectPlay 프로토콜을 사용한 비동기 네트워킹

네트워크 대응의 게임 어플리케이션을 설계 하면나무는, 네트워킹 코드의 오브젝트가, 동기 된 게임 환경의 기반을 다수의 플레이어에게 제공한다. 네트워킹 코드에서는, 다수가 다른 네트워크 환경을 처리할 필요가 있다. 이러한 환경은, 대기 시간, 대역폭, 신뢰성의 정도가 다른 경우가 있다.

DirectPlay 를 이용하기 전에, 게임 개발자는, 네트워크 링크의 성질을 판단해, 게임을 적절히 적응시킬 필요가 있다. 보통, 개발자가 채용하는 해결책은, 송신하는 데이터의 양과 빈도를 최소한으로 억제한다고 하는 것이다. 이 방법은 가혹한 환경에서도 잘 기능하지만, 최종 사용자에 최고의 게임 체험을 제공할 수 없다. 많은 경우는, 게임에서 보다 많은 업데이트 또는 업데이트마다의 정보를 송신하는 것으로써, 유저의 체감을 향상시켜, 게임 환경을 보다 조밀하게 동기 시킬 수가 있다.

네트워크 코드의 목표는, 이용 가능한 대역폭을 모두 이용해 게임 상태를 갱신하는 것이다. 동시에, 링크의 처리 능력을 넘어 데이터를 빠르게 송신하는 것으로써 발생하는 접속의 백 로그를 막을 필요가 있다. 백 로그가 발생 하면, 대기 시간이 증가하거나 게임의 동기가 잘 되지 않게 된다.

DirectPlay 프로토콜과 비동기 메시징이 제공하는 환경에서는, 어플리케이션의 네트워크 코드가, 링크의 능력을 판단해, 이용 가능한 대역폭을 최대한으로 활용할 수 있도록(듯이) 스스로의 동작을 적응시킬 수가 있다.

DirectPlay 프로토콜은, 수신 측에서의 피드백을 사용해, 수신 측에 닿은 데이터량을 파악한다. 기존의 네트워크 프로토콜과 달라, DirectPlay 프로토콜은 피드백을 사용하는 것으로써 송신 레이트를 정확하게 제어해, 송신측과 수신측의 사이에 메세지 패킷의 백 로그가 생성 되지 않게 할 수가 있다.

DirectPlay 프로토콜은, 이 피드백을 비보증 메세지에도 적용한다. 송신 메세지의쓰로틀링은, 클라이언트 어플리케이션이 백 로그를 생성 하는 것으로써 게임에 여분의 대기 시간을 발생시키지 않게 할 뿐만 아니라, 클라이언트가 스스로를 메세지에 적응시키는 것을 가능하게 한다. 클라이언트는, 송신 큐를 확인하는 것으로써, 링크의 전송 능력보다 빠르게 데이터를 송신하고 있는 상태나, 클라이언트가 이용 가능한 대역폭을 가득 사용하고 있는 상태를 인식할 수가 있다. 이것에 의해, 클라이언트는 기존의 링크의 능력에 응해, 송신 방법을 조정하는 것이 가능하게 된다.

DirectPlay 프로토콜을 최대한으로 활용하려면 , 메세지를 비동기적으로 송신할 필요가 있다 (이 방법의 상세한 것에 대하여는, 「비동기 메시징」을 참조). 비동기적으로 송신된 메세지는, 제어를 점유 하지 않는다. 메세지를 비동기적으로 송신 하면,SendEx 가 돌아오는 시점에서는, 송신은 완료하고 있지 않다. 다음에 송신이 완료 하면, 완료 메세지가 수신 큐에 보내진다.

비동기 송신을 이용 하면, DirectPlay 프로토콜은, 보증 첨부 및 보증 없음의 양쪽 모두의 메세지를, 링크상에서 동시에 다수 송신할 수가 있다. 즉, 어느 메세지의 완료를 대기하지 않고 , 다음의 메세지를 송신할 수 있다. 이것에 의해, 단일의 패킷이 없어진 것에 의해 링크를 사용할 수 없게 된다고 하는 사태를 막을 수가 있다. 또, 보증 첨부의 패킷이 1 개 없어진 것에 의해 다른 보증 메세지의 전송이 늦는다고 하는 일도 없어진다.

종래, 네트워크 게임에서는, 리얼타임의 게임 상태를 전송 하는 경우에 한정해, 보증 없음의 메세지를 이용하는 것이 일반적이었다. 이것은, 보증 없음의 메세지를 송신 하면, 보통은 제어가 점유 되지 않고, 다수의 메세지를 대기 시간없이 송신할 수 있기 때문이다. DirectPlay 프로토콜을 사용 하면, 제어를 점유 하지 않는 보증 메세지를 송신해, 각 접속에 대한 다수의 송신을 미완 상태로 해 둘 수가 있다. 즉, 게임에서 보증 송신을 이용해, 게다가 비보증 송신을 이용하는 게임과 동일한 정도의 응답성을 확보할 수 있다. 이것에 의해, 게임 상태의 갱신에 관한 설계가 큰폭으로 간소화되어 인크리멘탈인 갱신이 가능하게 된다. 이것을 비보증 송신으로 실현되는 것은, 거의 불가능하다.

DirectPlay 프로토콜을 사용할때에는, 이하의 사항에 주의할 필요가 있다.

  • DirectPlay 프로토콜이 액티브한 경우는,쓰로틀링이 원인으로, 동기형의 비보증 송신이 제어를 점유 하는 경우가 있다. 송신시에 비동기 플래그를 설정 하면, 비보증 송신이 즉시 돌아오도록(듯이) 해, 게임의 thread가 제어를 점유 하는 것을 막을 수가 있다.
  • DirectPlay 프로토콜을 사용 하면, 네트워크 링크를 유효하게 활용할 수 있지만, 여전히 송신하는 데이터의 양을 최소한으로 억제하도록(듯이) 주의할 필요가 있다. 상태의 갱신시에 송신하는 데이터는, 적으면 적을수록 좋다. 또, 최종적인 목표는, 1 초간의 갱신 회수를 늘려, 유저의 체감을 향상시키는 것이다.
  • 비동기 송신을 실행 하면, 프로토콜은 송신 데이터의 카피한다. 그 때문에, 버퍼를 재이용할 수가 있다 (또는, 메세지를 스택에 할당할 수가 있다). 따라서, 여전히 보류 큐에 포함할 수 있어 모든 송신 메세지는, 그 송신과 같은 사이즈의 메모리 할당을 나타내고 있다. 송신 큐를 무제한하게 크게 해선 안 된다. 보통은, 특정의 플레이어에 대한 송신 큐를 16 송신 이상으로 해도, 어떤 이점도 얻을 수 없다. DirectPlay 프로토콜의 현재의 이행에서는, 송신 큐내의 메세지의 수는 29 에 제한되고 있다. 그 이상의 송신은, 동시에 송신된다. 즉, 다른 송신이 종료하는 것을 대기하고 나서, 패킷이 네트워크 링크에 송신된다. 각 플레이어의 송신 큐 또는 수신 큐를 조사하려면 ,GetMessageQueue 를 사용한다.
  • 특정의 플레이어에 대한 송신 큐와 모든 송신 큐의 차이에 주의하지 않으면 안 된다. 송신을쓰로틀링 하는 경우, 보통은 모든 플레이어에 대해서는 아니고, 송신지의 플레이어에 대한 큐를 취득할 필요가 있다. 이것은, 그룹 송신은 아니고, 직접 송신을 사용하는 경우에도 들어맞는다.
  • 송신 큐가 항상 하늘의 경우는, 데이터의 송신 레이트를 높게 해, 게임의 동기 처리를 향상시켜야 하는 것이다. 이 프로토콜은 수신측으로부터 피드백을 취득하므로, 수신 측에 악영향을 줄 걱정은 없다. 하늘의 큐는, 대역폭의 헛됨을 의미한다.
  • 큐를 확인할 경우에는, 루프를 타이트로 하지 않고, 적당한 sleeve 시간을 삽입한다. thread를 상시 확인 하면, CPU 사이클을 모두 사용할 가능성이 있다. sleeve 시간은, 큐에 다음의 송신을 실행할 때까지의 시간을 기본으로 해 결정한다.
  • 송신 큐는 백 로그를 나타낸다. 송신 큐가 길어질수록, 이후의 송신의 대기 시간은 길어진다. 큐가 너무 길어 졌을 경우는, 메세지를 캔슬한다.


시큐러티와 인증

DirectPlay 의 시큐러티를 이용 하면, 서버상에서 실행되는 어플리케이션으로, 유저의 세션에의 참가를 허가하기 전에, 그 유저를 기존의 유저의 데이타베이스에 대조해 인증할 수가 있다. 유저가 인증되면(자), 클라이언트와 서버간의 모든 통신은, 디지털 서명 첨부 메세지 (송신측의 신원을 확인하기 위해(때문에)) 또는 암호화 메세지에 의해, 안전하게 실행된다.

구조에 관한 개요에 대해서는, 「시큐러티」를 참조할것.

그 외의 정보에 대해서는, 다음의 주제를 참조할것.

  • 유저와 메세지의 인증
  • 메세지의 암호화
  • 파이어 월(fire wall)의 지원
  • 시큐어 세션


유저와 메세지의 인증

DirectPlay 는, Windows® Security Support Provider Interface (SSPI)를 개입시켜, 유저와 메세지의 인증 (디지털 서명)에 대한 지원을 제공한다. DirectPlay 가 사용하는 디폴트의 시큐러티 패키지는, NTLM Security Support Provider 이다.

[Visual Basic]

DirectPlay 어플리케이션은,세션의 생성시에 DirectPlay4.SecureOpen 를 사용해, 다른 SSPI 시큐러티 패키지를 선택할 수가 있다. 예를 들어, 조직이 대규모 고객 베이스 (수십만 단위)에 대해서 멘바십서비스를 제공하기 위해서 이용할 수 있는 시큐러티 패키지로서 DPA (Distributed Password Authentication)가 있다. 이 시큐러티 패키지는, Microsoft Commercial Internet Services (MCIS) Membership Server 를 개입시켜 이용할 수 있다.

[C++]

DirectPlay 어플리케이션은,세션의 생성시에 IDirectPlay4::SecureOpen 를 사용해, 다른 SSPI 시큐러티 패키지를 선택할 수가 있다. 예를 들어, 조직이 대규모 고객 베이스 (수십만 단위)에 대해서 멘바십서비스를 제공하기 위해서 이용할 수 있는 시큐러티 패키지로서 DPA (Distributed Password Authentication)가 있다. 이 시큐러티 패키지는, Microsoft Commercial Internet Services (MCIS) Membership Server 를 개입시켜 이용할 수 있다.


메세지의 암호화

DirectPlay 는, Windows Cryptography Application Programming Interface (CAPI)를 개입시켜, 메세지의 암호화에 대한 지원을 제공한다. DirectPlay 의 암호화 서비스에 대한 디폴트의 CAPI 프로바이더는, Microsoft RSA Base Cryptographic Provider 버젼 1.0 이다. 이 디폴트의 CAPI 프로바이더의 타입은 PROV_RSA_FULL 이며, 디폴트의 암호화 알고리즘은 CALG_RC4 스트림사이파이다.

[C++]

DirectPlay 어플리케이션은,세션의 생성시에 IDirectPlay4::SecureOpen 메소드를 사용해, 다른 암호화 프로바이더를 선택할 수가 있다. 다만, DirectPlay 는 스트림사이파만을 지원 하는 것에 주의 해야 한다.

[Visual Basic]

DirectPlay 어플리케이션은,세션의 생성시에 DirectPlay4.SecureOpen 메소드를 사용해, 다른 암호화 프로바이더를 선택할 수가 있다. 다만, DirectPlay 는 스트림사이파만을 지원 하는 것에 주의 해야 한다.


파이어 월(fire wall)의 지원

DirectPlay 의 파이어 월(fire wall) 지원을 이용하기 위해서, 어플리케이션을 고쳐 쓸 필요는 없다. 디폴트의 동작에서는, DirectPlay 의 레인지로부터 동적으로 할당할 수 있는 포트를 사용한다. 이것에 의해, 기존의 어플리케이션과의 후방 호환성이 확보됨과 동시에, 1 대의 컴퓨터상에서 복수의 DirectPlay 어플리케이션을 사용하는 것이 가능하게 된다.

또, DirectPlay 의 새로운 고정 포트 기능을 이용하도록(듯이) 어플리케이션을 기술할 수도 있다. 개발자는, 어플리케이션용의 특정의 포트를 선택할 수가 있다. 파이어 월(fire wall) 관리자는, 그 포트만을 열면 좋다. 상세한 것에 대하여는,TCP/IP 의 해당하는 항목을 참조할것.

DirectX 6.0 이후의 유저는, 파이어 월(fire wall)가 개재하고 있지 않는 경우에 한정해, DirectX 5.0 의 유저와 통신할 수가 있다. 즉, 컴퓨터가 1 대로도 파이어 월(fire wall)의 뒤에 위치하고 있으면, DirectX 5.0 컴퓨터와의 피어 투 피어 게임은 기능하지 않는다. 클라이언트/서버 게임은, 호스트가 DirectX 6.0 이상이며, 게다가 호스트와 클라이언트간의 통신이 파이어 월(fire wall)를 경유하는 각 부분에서, 클라이언트가 DirectPlay 6.0 이후인 경우에 한정해, 기능한다.

프록시의 구조상, 이용할 수 있는 컴퓨터는 1 대에 제한된다. 그러나, 그 컴퓨터상에서 복수의 어플리케이션을 실행하는 것이 가능하다 ( 각 어플리케이션은, DirectPlay 의 동적인 레인지 또는 어플리케이션 정의의 일의의 포트를 사용한다).

DirectPlay 를 사용해 파이어 월(fire wall)를 지원 하는 방법의 상세한 것에 대하여는, 다음의 주제를 참조할것.

  • DirectPlay 의 동적 레인지를 사용한 클라이언트의 파이어 월(fire wall) 지원의 설정
  • DirectPlay 의 동적 레인지를 사용한 호스트의 파이어 월(fire wall) 지원의 설정
  • 어플리케이션으로 지정되는 고정 포트의 사용
  • 어플리케이션으로 지정되는 포트를 사용한 클라이언트의 파이어 월(fire wall) 지원의 설정
  • 어플리케이션으로 지정되는 포트를 사용한 호스트의 파이어 월(fire wall) 지원의 설정
  • 동적 레인지의 포트에 관한 참조표
  • DirectX 5.0 으로 DirectX 6.0 의 호환성에 관한 참조표


DirectPlay 의 동적 레인지를 사용한 클라이언트의 파이어 월(fire wall) 지원의 설정

파이어 월(fire wall)를 개입시켜 게임에 참가하려면 , DirectX 6.0 이후를 사용하고 있는 클라이언트가, DirectX 6.0 이후를 사용하고 있는 호스트와 통신하지 않으면 습관. DirectPlay 의 동적 레인지를 사용하고 있는 어플리케이션을 지원 하려면, 파이어 월(fire wall) 관리자는, 초기의 밖으로 향한 TCP 접속을 포트 47624 상에서 허가해, 2 차적인 내향 TCP 접속을 포트 2300 ~ 2400, 밖으로 향한 TCP 접속을 포트 2300 ~ 2400, 내향 UDP 접속을 포트 2300 ~ 2400, 밖으로 향한 UDP 접속을 포트 2300 ~ 2400 으로 각각 허가할 필요가 있다. 이러한 요건을 나타내는 표에 대해서는, 「동적 레인지의 포트에 관한 참조표」를 참조할것.

Microsoft Proxy Server 2.0 의 구성예

  • Internet Service Manager, Windows Sockets Proxy 서비스 : 서비스의 프로퍼티
    • [프로토콜] 탭을 클릭해,"DirectPlay (client)" 라고 하는 프로토콜을 추가한다.
      • 초기 접속
        • 47624 TCP 밖으로 향한
      • 2 차적인 접속
        • 2300 ~ 2400 TCP 내향
        • 2300 ~ 2400 TCP 밖으로 향한
        • 2300 ~ 2400 UDP 내향
        • 2300 ~ 2400 UDP 밖으로 향한
    • [허가] 탭을 클릭해,[DirectPlay (client)] 프로토콜에 적절한 액세스권을 허가한다.
  • mspclnt.ini 파일에 이하의 내용을 추가한다. 이 파일은, 디폴트에서는 C:\Msp\Clients 폴더에 있다.
    • [Common Configuration]
    • RemoteBindUdpPorts=2300-2400
    • ServerBindTcpPorts=2300-2400
    • KillOldSession=1


DirectPlay 의 동적 레인지를 사용한 호스트의 파이어 월(fire wall) 지원의 설정

파이어 월(fire wall)을 개입시켜 게임을 호스트 하려면 , 호스트가 DirectX 6.0 이후를 사용해, 파이어 월(fire wall)의 뒤에 위치하는 클라이언트도 DirectX 6.0 이후를 사용하고 있을 필요가 있다. DirectPlay 의 동적 레인지를 사용하는 어플리케이션을 지원 하려면, 파이어 월(fire wall) 관리자는, 초기의 내향 TCP 접속을 포트 47624 상에서 허가해, 2 차적인 내향 TCP 접속을 포트 2300 ~ 2400, 밖으로 향한 TCP 접속을 포트 2300 ~ 2400, 내향 UDP 접속을 포트 2300 ~ 2400, 밖으로 향한 UDP 접속을 포트 2300 ~ 2400 으로 각각 허가할 필요가 있다. 이러한 요건을 나타내는 표에 대해서는, 「동적 레인지의 포트에 관한 참조표」를 참조할것.

Microsoft Proxy Server 2.0 의 이론상의 구성

  • Internet Service Manager, Windows Sockets Proxy 서비스 : 서비스의 프로퍼티
    • [프로토콜] 탭을 클릭해,"DirectPlay (host)" 라고 하는 프로토콜을 추가한다.
      • 초기 접속
        • 47624 TCP 내향
      • 2 차적인 접속
        • 2300-2400 TCP 내향
        • 2300-2400 TCP 밖으로 향한
        • 2300-2400 UDP 내향
        • 2300-2400 UDP 밖으로 향한
    • [허가] 탭을 클릭해,[DirectPlay (host)] 프로토콜에 적절한 액세스권을 허가한다.
  • mspclnt.ini 파일에 이하의 내용을 추가한다. 이 파일은, 디폴트에서는 C:\Msp\Clients 폴더에 있다.
    • [Common Configuration]
    • RemoteBindUdpPorts=2300-2400
    • ServerBindTcpPorts=2300-2400
    • KillOldSession=1

유감스럽지만, Microsoft Proxy Server 2.0 을 포함한 일부의 파이어 월(fire wall) 솔루션은, 이외의 내향 접속을 2 차적인 접속으로서 인식하지 않는다. 이 문제를 회피하려면 , 어플리케이션으로 지정되는 고정 포트와 같이, 레인지내의 각 포트 (2300, 2301, 2302 등)에 독자적인 프로토콜 정의를 설정할 필요가 있다. 상세한 것에 대하여는, 「어플리케이션으로 지정되는 포트를 사용한 호스트의 파이어 월(fire wall) 지원의 설정」을 참조할것. 실제로는, 액티브한 DirectPlay 어플리케이션의 수만큼 포트를 열 필요가 있다. 즉,"SuperDuperGame" 와 "WackyFunGame" 를 동시에 실행 하면, 포트 2300 으로 2301 만이 사용된다.


어플리케이션으로 지정되는 고정 포트의 사용

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

어플리케이션은, DirectPlay 의 디폴트의 포트는 아니고, 고정 포트를 선택할 수가 있다. 이 경우, 그 어플리케이션을 파이어 월(fire wall)를 개입시켜 기능시키려면 , 1 개의 포트만을 열면 좋다.

어플리케이션으로 고정 포트를 지정하려면 , DPAID_InetPort 용의 데이타체크를 포함한 DirectPlay 주소를 생성 할 필요가 있다. 어플리케이션은, 이 데이타체크를 IDirectPlay4::InitializeConnection 에 건네주기 전에,IDirectPlay4::EnumConnections 에 의해 돌려주어지는 lpAddress 에 첨부할 수가 있다. 또는, 완전한 DirectPlay 주소 (서비스 프로바이더, IP 주소, 및 포트 번호를 지정한다)를 생성 해, 그것을 InitializeConnection 에 건네줄 수도 있다.

상세한 것에 대하여는, 「DirectPlay 주소」를 참조할것.


어플리케이션으로 지정되는 포트를 사용한 클라이언트의 파이어 월(fire wall) 지원의 설정

파이어 월(fire wall)를 개입시켜 게임에 참가하려면 , DirectX 6.0 이후를 사용하고 있는 클라이언트가, DirectX 6.0 이후를 사용하고 있는 호스트와 통신하지 않으면 습관. 어플리케이션으로 지정되는 고정 포트 n 를 사용하는 어플리케이션을 지원 하려면, 파이어 월(fire wall) 관리자는, 초기의 밖으로 향한 TCP 접속을 포트 n 로 허가해, 2 차적인 내향 TCP 접속을 포트 n, 내향 UDP 접속을 포트 n, 밖으로 향한 UDP 접속을 포트 n 로 각각 허가할 필요가 있다.

어플리케이션 "SuperDuperGame" (superdg.exe)가 포트 12345 를 지정하고 있는 경우의, Microsoft Proxy Server 2.0 의 구성예

  • Internet Service Manager, Windows Sockets Proxy 서비스 : 서비스의 프로퍼티
    • [프로토콜] 탭을 클릭해," SuperDuperGame (client)" 라고 하는 프로토콜을 추가한다.
      • 초기 접속
        • 12345 TCP 밖으로 향한
      • 2 차적인 접속
        • 12345 TCP 내향
        • 12345 UDP 내향
        • 12345 UDP 밖으로 향한
    • [허가] 탭을 클릭해,[SuperDuperGame] 프로토콜에 적절한 액세스권을 허가한다.
  • mspclnt.ini 파일에 이하의 내용을 추가한다. 이 파일은, 디폴트에서는 C:\Msp\Clients 폴더에 있다.
    • [superdg]
    • RemoteBindUdpPorts=12345
    • ServerBindTcpPorts=12345
    • KillOldSession=1


어플리케이션으로 지정되는 포트를 사용한 호스트의 파이어 월(fire wall) 지원의 설정

파이어 월(fire wall)을 개입시켜 게임을 호스트 하려면 , 호스트가 DirectX 6.0 이후를 사용해, 파이어 월(fire wall)의 뒤에 위치하는 클라이언트도 DirectX 6.0 이후를 사용하고 있을 필요가 있다. 어플리케이션으로 지정되는 고정 포트 n 를 사용하는 어플리케이션을 지원 하려면, 파이어 월(fire wall) 관리자는, 초기의 내향 TCP 접속을 포트 n 로 허가해, 2 차적인 밖으로 향한 TCP 접속을 포트 n, 내향 UDP 접속을 포트 n, 밖으로 향한 UDP 접속을 포트 n 로 각각 허가할 필요가 있다.

어플리케이션 "SuperDuperGame" (superdg.exe)가 포트 12345 를 지정하고 있는 경우의, Microsoft Proxy Server 2.0 의 구성예

  • Internet Service Manager, Windows Sockets Proxy 서비스 : 서비스의 프로퍼티
    • [프로토콜] 탭을 클릭해," SuperDuperGame (host)" 라고 하는 프로토콜을 추가한다.
      • 초기 접속
        • 12345 TCP 내향
      • 2 차적인 접속
        • 12345 TCP 밖으로 향한
        • 12345 UDP 내향
        • 12345 UDP 밖으로 향한
    • [허가] 탭을 클릭해,[SuperDuperGame] 프로토콜에 적절한 액세스권을 허가한다.
  • mspclnt.ini 파일에 이하의 내용을 추가한다. 이 파일은, 디폴트에서는 C:\Msp\Clients 폴더에 있다.
    • [superdg]
    • RemoteBindUdpPorts=12345
    • ServerBindTcpPorts=12345
    • KillOldSession=1


동적 레인지의 포트에 관한 참조표

이하는, DirectPlay 의 동적 레인지를 사용하는 어플리케이션에 대해서, 관리자가 열릴 필요가 있는 포트를 나타내고 있다.

접속 | 클라이언트의 구성 | 호스트의 구성
초기 TCP 접속 | 47624 밖으로 향한 | 47624 내향
2 차적인 내향 TCP 접속 | 2300 ~ 2400 | 2300 ~ 2400
2 차적인 밖으로 향한 TCP 접속 | 2300 ~ 2400 | 2300 ~ 2400
2 차적인 내향 UDP 접속 | 2300 ~ 2400 | 2300 ~ 2400
2 차적인 밖으로 향한 UDP 접속 | 2300 ~ 2400 | 2300 ~ 2400


DirectX 5.0 으로 DirectX 6.0 의 호환성에 관한 참조표

이하는, 버젼간의 호환성을 나타내고 있다. 여기에서는, 컴퓨터가 2 대만으로, 파이어 월(fire wall)이 양쪽 모두에 있어 물리적으로 같은 파이어 월(fire wall)인 (즉, 클라이언트와 호스트의 양쪽 모두가 같은 파이어 월(fire wall)의 뒤에 위치한다)와 가정하고 있다. 여기서 말하는 DirectX 6.0 이란,"DirectX 6.0 이후" 를 의미한다.

 | 인터넷상의 DirectX 5.0 호스트 | 파이어 월(fire wall)의 뒤에 위치하는 DirectX 5.0 호스트 | 인터넷상의 DirectX 6.0 호스트 | 파이어 월(fire wall)의 뒤에 위치하는 DirectX 6.0 호스트
인터넷상의 DirectX 5.0 클라이언트 | 있어 | 없음 | 있어 | 없음
파이어 월(fire wall)의 뒤에 위치하는 DirectX 5.0 클라이언트 | 없음 | 있어 | 없음 | 있어
인터넷상의 DirectX 6.0 클라이언트 | 있어 | 없음 | 있어 | 있어
파이어 월(fire wall)의 뒤에 위치하는 DirectX 6.0 클라이언트 | 없음 | 있어 | 있어 | 있어

이 표는, 세션이 클라이언트/서버형이면, 컴퓨터가 3 대 이상의 경우에도 들어맞는다. 3 대 이상의 컴퓨터가 존재해, 세션이 피어 투 피어로, 파이어 월(fire wall)가 어디엔가 존재하는 경우는, 모든 컴퓨터가 DirectX 6.0 이후를 사용할 필요가 있다.


시큐어 세션

시큐어 세션은, 인증된 유저만이 참가 가능한 세션이다. 이것은, 패스워드에 의한 보호와는 다르다. 인증에서는, 유저가 서버의 관리자에 의해 멘바십데이타베이스에 추가되고 있는지 어떤지에 근거해, 그 유저에게 서버에의 액세스가 허가되고 있는지 어떤지를 판단한다. 세션에의 참가가 허가되는 것은, 멘바십데이타베이스에 포함되어 있는 유저 뿐이다. 패스워드는, 시큐어 세션일지 어떨지에 관계없이, 임의의 세션에 추가할 수가 있다. 시큐어 세션을 호스트 할 수 있는 것은 인증을 지원 하는 컴퓨터 뿐이지만, 세션에 패스워드를 추가하는 것은 어느 컴퓨터로도 가능하다.

[C++]

DirectPlay 의 시큐어 세션을 생성 하려면 , 서버 어플리케이션이,IDirectPlay4::Open 또는 IDirectPlay4::SecureOpen 에 건네주는 DPSESSIONDESC2 구조체로, DPSESSION_SECURESERVER 플래그를 설정하는 것만으로 좋다. Open 를 사용 하면, 디폴트의 시큐러티 패키지를 사용해, 클라이언트가 세션에 참가했을 때에는 인증을 요구하지 않는 세션을 생성 할 수가 있다.

DirectPlay 어플리케이션은, 세션을 생성 할 경우에 SecureOpen 메소드를 호출해, 사용하는 프로바이더를 DPSECURITYDESC 구조체로 지정하는 것으로써, 다른 프로바이더를 선택할 수가 있다. 유저 및 메세지의 인증에 사용하는 SSPI 프로바이더가 다른 경우, 어플리케이션은 DPSECURITYDESC 구조체의 lpszSSPIProvider 멤버에 프로바이더의 이름을 지정할 필요가 있다. 메세지의 프라이버시에 사용하는 CryptoAPI 프로바이더가 다른 경우는, 프로바이더의 이름, 타입, 및 암호화 알고리즘을, 각각 lpszCAPIProvider,dwCAPIProviderType, 및 dwEncryptionAlgorithm 멤버로 지정할 필요가 있다.

클라이언트가 이 세션을 열거 하면,IDirectPlay4::EnumSessions 에 의해 돌려주어지는 DPSESSIONDESC2 구조체로 DPSESSION_SECURESERVER 플래그가 설정된다. 이 플래그는 클라이언트에 대해, 세션에 참가하기 위해서는, 인증용의 신용 증명이 필요한 것을 전한다. 클라이언트가 IDirectPlay4::Open 를 사용해 세션에의 참가를 시도하면(자), 그 유저의 신용 증명이 시스템에의 로그 온을 통해 이미 확립되어 있으면, 시큐러티 패키지에 의해 유저의 참가가 허가되는 경우가 있다. 그 이외의 경우는,DPERR_LOGONDENIED 에러가 돌려주어진다. 그 경우, 어플리케이션은 유저로부터 신용 증명을 수집해, 그것을 DPCREDENTIALS 구조체에 저장 해, 그 구조체를 건네주어 IDirectPlay4::SecureOpen 를 호출해, 세션에의 참가를 재차 시도할 필요가 있다. 시큐러티 위에의 이유에 의해,SecureOpen 가 추천 되고 있다.

[Visual Basic]

DirectPlay 의 시큐어 세션을 생성 하려면 , 서버 어플리케이션이,DirectPlay4.Open 또는 DirectPlay4.SecureOpen 에 건네주는 DirectPlaySessionData 오브젝트로, DPSESSION_SECURESERVER 플래그를 설정하는 것만으로 좋다. Open 를 사용 하면, 디폴트의 시큐러티 패키지를 사용해, 클라이언트가 세션에 참가했을 때에는 인증을 요구하지 않는 세션을 생성 할 수가 있다.

DirectPlay 어플리케이션은, 세션을 생성 할 경우에 SecureOpen 메소드를 호출해, 사용하는 프로바이더를 DPSECURITYDESC 형으로 지정하는 것으로, 다른 프로바이더를 선택할 수가 있다. 유저 및 메세지의 인증에 사용하는 SSPI 프로바이더가 다른 경우, 어플리케이션은 DPSECURITYDESC 형의 strSSPIProvider 멤버에 프로바이더의 이름을 지정할 필요가 있다. 메세지의 프라이버시에 사용하는 CryptoAPI 프로바이더가 다른 경우는, 프로바이더의 이름, 타입, 및 암호화 알고리즘을, 각각 strCAPIProvider,lCAPIProviderType, 및 lEncryptionAlgorithm 멤버로 지정할 필요가 있다.

클라이언트가 이 세션을 열거 하면,DirectPlayEnumSessions.GetItem 에 의해 돌려주어지는 DirectPlaySessionData 오브젝트로 DPSESSION_SECURESERVER 플래그가 설정된다. 이 플래그는 클라이언트에 대해, 세션에 참가하기 위해서는, 인증용의 신용 증명이 필요한 것을 전한다. 클라이언트가 DirectPlay4.Open 를 사용해 세션에의 참가를 시도하면(자), 그 유저의 신용 증명이 시스템에의 로그 온을 통해 이미 확립되어 있으면, 시큐러티 패키지에 의해 유저의 참가가 허가되는 경우가 있다. 그 이외의 경우는,DPERR_LOGONDENIED 에러가 돌려주어진다. 그 경우, 어플리케이션은 유저로부터 신용 증명을 수집해, 그것을 DPCREDENTIALS 형에 저장 해, 그것을 건네주어 DirectPlay4.SecureOpen 를 호출해, 세션에의 참가를 재차 시도할 필요가 있다.

시큐어 세션에서는, DirectPlay 의시스템 메세지에는, 송신측의 신원을 알 수 있도록(듯이), 모두 디지털 서명이 베풀어진다. 중요한 정보를 옮기는 일부의 시스템 메세지는, 암호화된다. 어느 플레이어로부터 발생해, 세션내외의 모든 플레이어에게 브로드캐스트 해야 하는 시스템 메세지는, 우선 서버에 송신된다. 서버는, 스스로의 서명을 메세지에 가세해, 그 메세지를 세션내외의 모든 컴퓨터에 송신한다. 디폴트에서는, 플레이어대 플레이어의 메세지에는 서명은 더해지지 않고, 서버도 경유하지 않는다.

어플리케이션은, 메세지의 송신시에 DPSEND_SIGNED 플래그 또는 DPSEND_ENCRYPTED 플래그를 설정해, 플레이어대 플레이어의 메세지에 서명하는지, 또는 암호화하는지를 선택할 수가 있다. 서명된 메세지와 암호화된 메세지는, 서버를 경유해, 시큐어인 시스템 메세지로서 도착된다. 플레이어가 시큐어인 메세지를 수신 하면, 서명이 더해지고 있는지, 또는 암호화되고 있는지를 나타내는 플래그가 메세지에 포함되어 있다. 확인 처리를 패스하지 않는 메세지는, 파기된다.


DirectX 의 이전의 버젼으로부터의 이행

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

DirectPlay API 의 현재의 버젼은, DirectX 의 이전의 버젼으로 기술된 어플리케이션과의 완전한 호환성을 갖춘다. 즉, 코드로 변경을 더하는 일 없이, 어플리케이션을 DirectX 의 현재의 버젼용으로재컴파일 할 수가 있다. 그러나, 새로운 기능을 이용하려면 , 코드를 수정해야 하는 경우가 있다.

상세한 것에 대하여는, 다음의 주제를 참조할것.

  • DirectX 3.0 이후부터의 이행
  • DirectX 2.0 으로부터의 이행


DirectX 3.0 이후부터의 이행

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

DirectX 버젼 3.0 이후의 일부에서 만난 버젼으로부터 DirectPlay 의 현재의 버젼에 이후 하는 경우는, 어떠한 변경도 더할 필요는 없다. 그러나, 새로운 IDirectPlay4 또는 IDirectPlay4A 인터페이스를 사용하는 경우는, 어플리케이션을 업그레이드 할 필요가 있다.

일부의 시스템 메세지는 DirectX 6.0 으로 변경되어 새로운 데이터 멤버가 마지막에 추가되었다. 이러한 새로운 멤버는, 현재의 버젼에서도 계속해 이용된다. 종래의 런타임 파일과의 호환성을 확보해야 하는 어플리케이션에서는, 이하의 어느쪽이든을 실시할 필요가 있다.

  • DirectX 3.0 의 헤더 파일 및 라이브러리와 함께 컴파일 한다.
  • 새로운 데이터 멤버에의 참조를 피한다.
  • DirectX 3.0 으로 현재의 런타임 파일의 양쪽 모두로 테스트한다.

버젼 5.0 에 대해서 새로운 멤버가 추가된 시스템 메세지 구조체는, 이하대로이다.

구조체 | 새로운 멤버
DPMSG_CREATEPLAYERORGROUP | DPID dpIdParent
 | DWORD dwFlags
DPMSG_DESTROYPLAYERORGROUP | DPNAME dpnName
 | DPID dpIdParent
 | DWORD dwFlags


DirectX 2.0 으로부터의 이행

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

DirectX 버젼 3.0 이후의 DirectPlay 의 DLL 의 이름은, 그 이전의 버젼의 것과는 다르다. Applications compiled with DirectX 2.0 이전과 호환성이 있는 어플리케이션은, DirectPlay 의 새로운 DLL 를 사용하지 않는다. 이러한 새로운 DLL 를 사용하려면 , 어플리케이션을 재컴파일 해, 임포트 라이브러리 Dplayx.lib 에 링크해야 한다.

또, 어플리케이션을 로비에 대응시키기 위한 코드도 추가해야 한다. 이것에 의해, 외부 로비 또는 중개 프로그램이 어플리케이션을 시작 해, 세션에 접속하기 위해서 필요한 정보를 모두 제공할 수 있게 된다. 어플리케이션에서는, 서비스 프로바이더를 결정하거나 세션을 선택하거나 그 외의 정보 (전화번호, 네트워크 주소등)를 제공하거나 하도록(듯이), 유저에게 요구할 필요는 없다.

게다가 DirectX 버젼 6.0 에서는, 그 밖에도 새로운 기능이 몇개인가 추가되었다. 이러한 신기능에는, 이하와 같은 것이 있다.

  • 보증 메시징
  • 비동기 메시징
  • 메세지의쓰로틀링
  • 파이어 월(fire wall)의 지원
  • 로비의 개선
  • 시큐러티의 개선
  • 로컬라이즈 지원의 개선
  • 어플리케이션을 등록 및 등록 해제하기 위한 API
  • 그룹 소유권의 관리의 개선
  • 킵얼라이브의 지원의 개선
  • 사적인 서비스 프로바이더

DirectPlay 버젼 2.0 이전에 생성 된 어플리케이션을 이행 시키려면 , 다음의 스텝을 실행한다.

어플리케이션이 로비 클라이언트로부터 기동되고 있었는지 어떠했는지를 확인한다. 상세한 것에 대하여는, 「스텝 2 : 접속 설정의 취득」을 참조할것.

어플리케이션이 서비스 프로바이더를 열거하고 있는 경우는,DirectPlay4::EnumConnections 메소드를 사용해, 서비스 프로바이더가 이용 가능한가 어떤가를 판단한다. 이용 가능한 경우는, 그 서비스 프로바이더에 대해서 DirectPlay4::InitializeConnection 메소드를 호출한다. InitializeConnection 가 에러를 돌려주는 경우, 서비스 프로바이더를 시스템상에서 실행할 수 없기 때문에, 그 서비스 프로바이더를 유저에게 표시하는 리스트에 추가해서는 안된다. 호출이 성공했을 경우는,Release 메소드를 사용해 DirectPlay 오브젝트를 릴리즈 해, 그 서비스 프로바이더를 리스트에 추가한다.

IDirectPlay 인터페이스 위에의 QueryInterface 메소드를 호출해,IDirectPlay4 (Unicode) 또는 IDirectPlay4A (ANSI) 인터페이스를 취득한다. 2 개의 인터페이스의 차이는, 구조 체내의 캐릭터 라인을 읽고 쓰기하는 방법 뿐이다. Unicode 인터페이스의 경우는, 구조체의 LPWSTR 형의 멤버에 Unicode 캐릭터 라인이 읽고 쓰기된다. ANSI 인터페이스의 경우는, 구조체의 LPSTR 형의 멤버에 ANSI 캐릭터 라인이 읽고 쓰기된다.

기존의 API 로 새로운 구조체를 사용하기 위해서 필요한 변경을 모두 더한다. 예를 들어, 다음과 같은 코드가 있다고 한다.

lpDP->SetPlayerName(pidPlayer, lpszFriendlyName, lpszFormalName)

lpDP 는,IDirectPlay 인터페이스이다. 이 경우는, 다음과 같은 코드를 사용한다.

DPNAME PlayerName, *lpPlayerName
PlayerName.dwSize = sizeof(DPNAME)
lpPlayerName = &PlayerName

lpPlayerName->lpszShortNameA = lpszFriendlyName
lpPlayerName->lpszLongNameA = lpszFormalName
lpDP4A->SetPlayerName(pidPlayer, lpPlayerName, 0)

lpDP4A 는,IDirectPlay4A 인터페이스이다. 이 어플리케이션으로 Unicode 캐릭터 라인을 사용하고 있는 경우 (따라,IDirectPlay4 인터페이스의 인스턴스를 생성 하는 경우)는, 다음과 같은 코드를 사용한다.

lpPlayerName->lpszShortName = lpwszFriendlyName
lpPlayerName->lpszLongName = lpwszFormalName
lpDP4->SetPlayerName(pidPlayer, lpPlayerName, 0)

lpDP4 는,IDirectPlay4 인터페이스이다.

이하의 시스템 메세지를 갱신한다.

DPSYS_ADDPLAYER 는, DPSYS_CREATEPLAYERORGROUP 로 옮겨졌다.

DPSYS_DELETEPLAYER 와 DPSYS_DELETEGROUP 는, 단일의 DPSYS_DESTROYPLAYERORGROUP 메세지로 통일되었다.

DPSYS_DELETEPLAYERFROMGRP 는, DPSYS_DELETEPLAYERFROMGROUP 로 변경되었다.

어플리케이션을 갱신해, 플레이어 또는그룹의 이름이 변경되었을 때에 DPSYS_SETPLAYERORGROUPNAME 메세지를 생성해, 플레이어 또는 그룹의 데이터가 변경되었을 때에 DPSYS_SETPLAYERORGROUPDATA 메세지를 생성하도록(듯이) 한다.

DPSESSIONDESC 구조체를 DPSESSIONDESC2 에 갱신해,DPCAPS 구조체에 새로운 멤버를 추가한다.

IDirectPlay4::EnumSessions ,IDirectPlay4::EnumGroups ,IDirectPlay4::EnumGroupPlayers , 및 IDirectPlay4::EnumPlayers 에 대한 콜백 함수를 갱신한다.

hEvent 파라미터를 IDirectPlay4::CreatePlayer 메소드에 건네주는 방법을 갱신한다. DirectPlay 의 이전의 버젼에서는, 이 파라미터는 lpEvent 였다. DirectPlay 는 이벤트를 돌려주지 않기 때문에, 어플리케이션으로 그것을 생성 할 필요가 있다. 이것에 의해, 어플리케이션에서는, 모든 플레이어에 대해서 1 개의 이벤트를 생성 하면 말하는 유연성을 얻을 수 있다.

플레이어가 게임으로부터 부적절한 방법으로 퇴출 한 것을 DirectPlay 에 의해 검출하고 싶은 경우는,DPSESSIONDESC2 구조체의 DPSESSION_KEEPALIVE 플래그를 설정한다.

어플리케이션을 갱신해, DPSESSION_MIGRATEHOST 플래그를 설정해 세션을 생성 하도록(듯이) 한다. 이것에 의해, 현재의 호스트가 세션을 퇴출 했을 때에, 다른 컴퓨터가호스트가 되는 것이 가능하게 된다. 호스트만이 실행하는 특별한 코드가 어플리케이션에 있는 경우는, 어플리케이션으로 세션을 생성 할 경우에, 이 플래그를 설정할 필요가 있다. 또는, DPSYS_HOST 시스템 메세지에 대한 지원도 추가해야 한다. 시스템 메세지의 일람에 대해서는, 「시스템 메세지의 사용」을 참조할것.

IDirectPlay4 인터페이스의 새로운 메소드에 익숙해 그것들을 어플리케이션으로 사용한다. 플레이어 상태에 관한 정보를 다른 모든 플레이어에게 브로드캐스트 하는 코드는,IDirectPlay4::SendEx 메소드와 IDirectPlay4::Receive 메소드를 사용해 옮겨놓을 수 있는 경우가 있다.


DirectPlay 튜토리얼

여기에서는, 어플리케이션에 DirectPlay 기능을 이행 하는 방법을 나타내는 튜토리얼을 제공한다. 튜토리얼은, 언어 마다 다음의 그룹으로 나누어져 있다.

  • DirectPlay C/C++ 튜토리얼
  • DirectPlay Visual Basic 튜토리얼


DirectPlay C/C++ 튜토리얼

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 튜토리얼」을 참조할것.

[C++]

이 주제는, 다음의 튜토리얼로 구성된다. 이러한 튜토리얼은, DirectPlay 의 이행을 스텝바이스텝으로 설명한다.

  • 튜토리얼 1 : 로비를 사용한 접속 (DPChat)
  • 튜토리얼 2 : 다이알로그 박스를 사용한 접속 (DPChat)
  • 튜토리얼 3 : 서비스 프로바이더 다이얼로그의 개서
  • 튜토리얼 4 : 자동 리프레쉬식 세션 리스트의 생성

주 : 이러한 튜토리얼의 샘플 코드는 C++ 로 기술되고 있다. C 컴파일러를 사용하는 경우, 잘 컴파일 할 수 있도록(듯이) 파일을 적절히 변경할 필요가 있다. 상세한 것에 대하여는, 「C 로부터의 COM 오브젝트에의 액세스」를 참조할것.


튜토리얼 1 : 로비를 사용한 접속

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 튜토리얼」을 참조할것.

[C++]

IDirectPlayLobby3 인터페이스를 사용하도록(듯이) 기술된 어플리케이션에서는, 유저에게 접속 정보를 다이알로그 박스에 수작업으로 입력하도록(듯이) 요구하지 않고 , 세션에 접속할 수가 있다. 로비를 사용한 어플리케이션의 생성 방법을 나타내기 위해서(때문에),SimpleConnect 샘플 에서는 다음의 스텝을 실행한다.

  • 스텝 1 : DirectPlayLobby 오브젝트의 생성
  • 스텝 2 : 접속 설정의 취득
  • 스텝 3 : 세션 기술의 구성
  • 스텝 4 : 세션에의 접속
  • 스텝 5 : 플레이어의 생성


스텝 1 : DirectPlayLobby 오브젝트의 생성

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 튜토리얼」을 참조할것.

[C++]

DirectPlay 로비를 사용하려면 , 우선 CoCreateInstance 를 호출해 DirectPlayLobby 오브젝트의 인스턴스를 생성 한다. 다음의 예는, DirectPlayLobby 오브젝트의 생성 방법의 일례를 나타내고 있다.

// IDirectPlayLobby3A 인터페이스를 생성 한다.
if ( FAILED( hr = CoCreateInstance( CLSID_DirectPlayLobby, NULL,
        CLSCTX_INPROC_SERVER,
        IID_IDirectPlayLobby3A,
        (VOID**) &g_pDPLobby ) ) )
    return hr;

다음 방향 : 스텝 2 : 접속 설정의 취득


스텝 2 : 접속 설정의 취득

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 튜토리얼」을 참조할것.

[C++]

DirectPlayLobby 를 생성 하면(자),IDirectPlayLobby3::GetConnectionSettings 메소드를 사용해, 로비로부터 돌려주어지는 접속 설정을 취득한다. 이 메소드가DPERR_NOTLOBBIED 를 돌려주는 경우, 로비는 이 어플리케이션을 기동하고 있지 않고, 유저는 접속을 수작업으로 구성할 필요가 있다. 그 외의 에러가 발생했을 경우, 어플리케이션에서는 에러를 보고해, 어플리케이션의 로비가 실패한 것을 알릴 필요가 있다.

다음의 예는, 접속 설정의 취득 방법을 나타내고 있다.

// 로비로부터 접속 설정을 취득해, g_pdplConnection 로 설정한다.
hr = g_pDPLobby->GetConnectionSettings( 0, NULL, &dwSize );
if ( FAILED(hr) && (DPERR_BUFFERTOOSMALL ! = hr) )
{
    if( DPERR_NOTLOBBIED == hr )
    {
        *pbLaunchedByLobby = FALSE;

        // 로비로부터 기동한 것은 아니기 때문에, 클린 업 한다.
        SAFE_DELETE_ARRAY( g_pDPLConnection );
        SAFE_RELEASE( g_pDPLobby );

        return S_OK;
    }

    return hr;
}

// 접속에 메모리를 할당한다.
SAFE_DELETE_ARRAY( g_pDPLConnection );
g_pDPLConnection = (DPLCONNECTION*) new BYTE[ dwSize ];

// 접속 설정을 취득한다.
if ( FAILED( hr = g_pDPLobby->GetConnectionSettings(
         0, g_pDPLConnection, &dwSize ) ) )
    return hr;

다음 방향 : 스텝 3 : 세션 기술의 구성


스텝 3 : 세션 기술의 구성

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 튜토리얼」을 참조할것.

[C++]

DPSESSIONDESC2 구조체를 조사해 어플리케이션에 필요한 플래그와 프로퍼티가 모두 올바르게 설정되어 있는지 어떤지를 확인할 필요가 있다. 수정이 필요한 경우는,IDirectPlayLobby3::SetConnectionSettings 메소드를 사용해, 수정한 접속 설정을 저장 한다.

다음의 예는, 세션 기술을 구성해, 접속 설정을 설정하는 방법을 나타내고 있다.

// 세션 플래그를 설정한다.
g_pDPLConnection->lpSessionDesc->dwFlags =
        DPSESSION_KEEPALIVE | DPSESSION_MIGRATEHOST;

// 접속 플래그를 로비에게 전한다.
if ( FAILED( hr = g_pDPLobby->SetConnectionSettings(
        0, 0, g_pDPLConnection ) ) )
    return hr;

다음 방향 : 스텝 4 : 세션에의 접속


스텝 4 : 세션에의 접속

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 튜토리얼」을 참조할것.

[C++]

세션 기술을 올바르게 구성하면(자), 어플리케이션에서는IDirectPlayLobby3::ConnectEx 메소드를 사용해 스스로를 기동해, 세션에 접속할 수가 있다. 이 메소드가 DP_OK 를 돌려주는 경우, 1 개(살) 이상의 플레이어를 생성 할 수 있다. 이 메소드가 DPERR_NOTLOBBIED 를 돌려주는 경우, 유저는 어플리케이션에 대한 통신 매체를 수작업으로 선택할 필요가 있다 (IDirectPlay4::EnumConnections 메소드를 사용 하면, 시스템에 인스톨 되고 있는 서비스 프로바이더를 식별할 수가 있다). 그 외의 에러값을 돌려주는 경우, 어플리케이션에서는 에러를 보고해, 어플리케이션의 로비가 실패한 것을 알릴 필요가 있다.

다음의 예는, 세션에의 접속 방법을 나타내고 있다.

if ( FAILED( hr = g_pDPLobby->ConnectEx( 0, IID_IDirectPlay4A,
        (VOID**) &g_pDP, NULL ) ) )
    return hr;

다음 방향 : 스텝 5 : 플레이어의 생성


스텝 5 : 플레이어의 생성

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 튜토리얼」을 참조할것.

[C++]

IDirectPlayLobby3::ConnectEx 메소드에 의해 어플리케이션의 기동에 성공하면(자), 1 개(살) 이상의 플레이어를 생성 할 수가 있다. 플레이어를 생성 하려면 ,IDirectPlay4::CreatePlayer 메소드를 사용해, 이름을 DPNAME 구조체 (이 구조체는 IDirectPlayLobby3::GetConnectionSettings 메소드에 의해 설정된다)로 지정한다.

다음의 예는, 플레이어의 생성 방법을 나타내고 있다.

DPNAME dpname;
ZeroMemory( &dpname, sizeof(DPNAME) );
dpname.dwSize  = sizeof(DPNAME);
dpname.lpszShortNameA = g_strLocalPlayerName;

if ( FAILED( hr = g_pDP->CreatePlayer( &g_LocalPlayerDPID, &dpname,
        NULL, NULL, 0, 0 ) ) )
    return hr;

이것으로 어플리케이션에의 접속이 완료해, 재생할 준비가 갖추어졌다.


튜토리얼 2 : 다이알로그 박스를 사용한 접속

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 튜토리얼」을 참조할것.

[C++]

로비에 의해 어플리케이션이 기동하지 않는 경우, 유저가 접속 정보를 수작업으로 입력할 수 있도록(듯이) 하는 코드를 더할 필요가 있다. 세션에의 접속과 1 개 이상의 플레이어의 생성을 수작업으로 실행하는 방법을 나타내기 위해서(때문에),SimpleConnect 샘플 에서는 다음의 스텝을 실행한다.

  • 스텝 1 : DirectPlay 오브젝트의 생성
  • 스텝 2 : 서비스 프로바이더의 열거와 초기화
  • 스텝 3 : 세션에의 참가
  • 스텝 4 : 세션의 생성
  • 스텝 5 : 새로운 플레이어의 생성


스텝 1 : DirectPlay 오브젝트의 생성

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 튜토리얼」을 참조할것.

[C++]

메소드를 호출하기 전에, 어플리케이션에서는 DirectPlay 오브젝트에의 인터페이스를 취득할 필요가 있다.

다음의 예는,IDirectPlay4 인터페이스를 취득하는 방법을 나타내고 있다.

if ( FAILED( hr = CoCreateInstance( CLSID_DirectPlay, NULL,
        CLSCTX_ALL, IID_IDirectPlay4A, (VOID**) &g_pDP ) ) )
    return hr;

다음 방향 : 스텝 2 : 서비스 프로바이더의 열거와 초기화


스텝 2 : 서비스 프로바이더의 열거와 초기화

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 튜토리얼」을 참조할것.

[C++]

수동 접속을 생성하기 위한 다음의 스텝은, 어플리케이션에 대한 통신 매체를 선택하도록(듯이) 유저에게 요구하는 것이다. 어플리케이션에서는,EnumConnections 메소드를 사용해, 퍼스널 컴퓨터에 인스톨 되고 있는 서비스 프로바이더를 식별할 수가 있다.

다음의 예는, 서비스 프로바이더를 열거하는 방법을 나타내고 있다.

// DirectPlay 접속을 모두 열거해
// 그것들을 리스트 박스에 저장 한다.
if ( FAILED( hr = pDP->EnumConnections( &g_AppGUID,
        DPConnect_EnumConnectionsCallback, hWndListBox, 0 ) ) )
{
    SAFE_RELEASE( pDP );
    return hr;
}

EnumConnections 메소드의 2 번째의 파라미터는, DirectPlay 에 의해 등록된 서비스 프로바이더를 열거하는 콜백이다. 다음의 예는,SimpleConnect 샘플 에 있어서의 이 콜백 함수의 이행 방법을 나타내고 있다.

BOOL FAR PASCAL DPConnect_EnumConnectionsCallback(
        LPCGUID   pguidSP,
        VOID*     pConnection,
        DWORD     dwConnectionSize,
        LPCDPNAME pName,
        DWORD     dwFlags,
        VOID*     pvContext )
{
    HRESULT       hr;
    LPDIRECTPLAY4 pDP = NULL;
    VOID*         pConnectionBuffer = NULL;
    HWND          hWndListBox = (HWND) pvContext;
    LRESULT       iIndex;

    // IDirectPlay 오브젝트를 생성 한다.
    if ( FAILED( hr = CoCreateInstance( CLSID_DirectPlay, NULL,
            CLSCTX_ALL, IID_IDirectPlay4A, (VOID**) &pDP ) ) )
            return FALSE; // 에러. 열거를 중지한다.

    // 초기화를 시도해, 접속을 이용할 수 있을지 어떨지
    // 테스트한다.
        // 접속.
    if( FAILED( hr = pDP->InitializeConnection( pConnection, 0 ) ) )
    {
        SAFE_RELEASE( pDP );
        return TRUE; // 이용할 수 없는 접속. 열거를 계속한다.
    }

    // IDirectPlay 인터페이스는 더 이상 필요없기 때문에, 릴리즈 한다.
    SAFE_RELEASE( pDP );

    // 적절한 접속이 발견되었으므로, 이것을 리스트 박스에 대입한다.
    iIndex = SendMessage( hWndListBox, LB_ADDSTRING, 0,
            (LPARAM) pName->lpszShortNameA );
    if( iIndex == CB_ERR )
        return FALSE; // 에러. 열거를 중지한다.

    pConnectionBuffer = new BYTE[ dwConnectionSize ];
    if( pConnectionBuffer == NULL )
        return FALSE; // 에러. 열거를 중지한다.

    // GUID 에의 포인터를 리스트 박스에 저장 한다.
    memcpy( pConnectionBuffer, pConnection, dwConnectionSize );
    SendMessage( hWndListBox, LB_SETITEMDATA, iIndex,
            (LPARAM) pConnectionBuffer );

    return TRUE; // 열거를 계속한다.
}

유저가 사용하는 접속을 선택하면(자), 열거에 의해 돌려주어지는 접속 데이터를 취득해, 그 데이터를 사용해 DirectPlay 오브젝트를 초기화할 필요가 있다.

if ( FAILED( hr = g_pDP->InitializeConnection( pConnection, 0 ) ) )
    return hr;

다음 방향 : 스텝 3 : 세션에의 참가


스텝 3 : 세션에의 참가

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 튜토리얼」을 참조할것.

[C++]

유저가 기존의 세션에의 참가를 요구하고 있는 경우는,IDirectPlay4::EnumSessions 메소드를 사용해 이용 가능한 세션을 열거해, 유저에게 선택사항을 나타낸다. 다음에, DPOPEN_JOIN 플래그를 설정해 IDirectPlay4::Open 메소드를 호출해, 세션에 접속한다. 세션을 열거하기 전에, 서비스 프로바이더에 의해 유저에게 정보를 요구하는 다이알로그 박스가 표시되는 경우도 있다.

비동기의 EnumSessions 기능에 관한 상세한 것에 대하여는, 「튜토리얼 4 : 자동 리프레쉬식 세션 리스트의 생성」을 참조할것.

다음의 예는, 이용 가능한 세션을 열거하는 방법을 나타내고 있다.

// 세션을 열거해, DirectPlay 에 타임 아웃을 판단시킨다.
ZeroMemory( &dpsd, sizeof(dpsd) );
dpsd.dwSize          = sizeof(dpsd);
dpsd.guidApplication = g_AppGUID;

// 선택된 접속으로, 액티브한 DirectPlay 게임을
// 모두 열거한다.
hr = g_pDP->EnumSessions( &dpsd, 0,
        DPConnect_EnumSessionsCallback, NULL,
        DPENUMSESSIONS_ALL | DPENUMSESSIONS_ASYNC );

IDirectPlay4::EnumSessions 메소드의 3 번째의 파라미터는, 이용 가능한 세션을 열거하는 콜백이다. 다음의 코드는,SimpleConnect 샘플 에 있어서의 이 콜백 함수의 이행 방법을 나타내고 있다.

BOOL FAR PASCAL DPConnect_EnumSessionsCallback(
        LPCDPSESSIONDESC2 pdpsd,
        DWORD*            pdwTimeout,
        DWORD             dwFlags,
        VOID*             pvContext )
{
    DPSessionInfo* pDPSINew = NULL;

    if ( dwFlags & DPESC_TIMEDOUT )
        return FALSE; // 타임 아웃. 열거를 중지한다.

    // 적절한 세션이 발견되었다. 이것을 보존한다.
    pDPSINew = new DPSessionInfo;
    if ( NULL == pDPSINew )
        return FALSE;

    ZeroMemory( pDPSINew, sizeof(DPSessionInfo) );

    // 정보를 pDPSINew 에 카피한다.
    pDPSINew->guidSession = pdpsd->guidInstance;
    sprintf( pDPSINew->szSession, "%s (%d/%d)",
            pdpsd->lpszSessionNameA,
            pdpsd->dwCurrentPlayers,
            pdpsd->dwMaxPlayers );

    // pDPSINew 를 순환형의 링크 리스트 g_pDPSIFirst 에 추가한다.
    pDPSINew->pDPSINext = g_DPSIHead.pDPSINext;
    g_DPSIHead.pDPSINext = pDPSINew;

    return TRUE;
}

유저가 세션을 선택하면(자), 어플리케이션에서는 기존의 세션에의 참가를 허가할 수가 있다. 다음의 예는, 기존의 세션에 참가하는 방법을 나타내고 있다.

// DPSESSIONDESC2 를 설정해, 리스트 박스의 선택된 항목으로부터
// 세션의 GUID 를 취득한다.
ZeroMemory( &dpsd, sizeof(dpsd) );
dpsd.dwSize          = sizeof(dpsd);
dpsd.guidInstance    = pDPSISelected->guidSession;
dpsd.guidApplication = g_AppGUID;

// 세션에 참가한다.
g_bHostPlayer = FALSE;
if ( FAILED( hr = g_pDP->Open( &dpsd, DPOPEN_JOIN ) ) )
    return hr;

다음 방향 : 스텝 4 : 세션의 생성


스텝 4 : 세션의 생성

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 튜토리얼」을 참조할것.

[C++]

유저가 새로운 세션을 생성 하는 경우는, 어플리케이션으로 IDirectPlay4::Open 메소드를 호출해, DPOPEN_CREATE 플래그를 설정하는 것으로써, 신규의 세션을 생성 할 수가 있다. 이 경우도, 세션을 생성 하기 전에, 서비스 프로바이더에 의해 유저에게 정보를 요구하는 다이알로그 박스가 표시되는 일이 있다.

다음의 예는, 새로운 세션의 생성 방법을 나타내고 있다.

ZeroMemory( &dpsd, sizeof(dpsd) );
dpsd.dwSize           = sizeof(dpsd);
dpsd.guidApplication  = g_AppGUID;
dpsd.lpszSessionNameA = g_strSessionName;
dpsd.dwMaxPlayers     = 10;
// DPSESSION_KEEPALIVE 플래그는, 플레이어가
// 이상종료(ABEND) 했을 경우에 세션을 유지한다.
dpsd.dwFlags          = DPSESSION_KEEPALIVE | DPSESSION_MIGRATEHOST;
if ( g_bUseProtocol )
    dpsd.dwFlags |= DPSESSION_DIRECTPLAYPROTOCOL;

// 새로운 세션을 생성 한다.
g_bHostPlayer = TRUE;
if ( FAILED( hr = g_pDP->Open( &dpsd, DPOPEN_CREATE ) ) )
    return hr;

다음 방향 : 스텝 5 : 새로운 플레이어의 생성


스텝 5 : 새로운 플레이어의 생성

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 튜토리얼」을 참조할것.

[C++]

세션을 생성 하는지, 또는 기존의 세션에 참가하면(자), 어플리케이션에서는 IDirectPlay4::CreatePlayer 메소드를 사용해 1 개(살) 이상의 플레이어를 생성 할 수가 있다. 다음의 코드는,SimpleConnect 샘플 에 있어서의 플레이어의 생성 방법을 나타내고 있다.

DPNAME dpname;
ZeroMemory( &dpname, sizeof(DPNAME) );
dpname.dwSize         = sizeof(DPNAME);
dpname.lpszShortNameA = g_strLocalPlayerName;

if ( FAILED( hr = g_pDP->CreatePlayer( &g_LocalPlayerDPID, &dpname,
        NULL, NULL, 0, 0 ) ) )
    return hr;

어플리케이션에서는,IDirectPlay4::GetCaps 메소드와 IDirectPlay4::GetPlayerCaps 메소드를 사용해, 플레이어의 통신 기능을 판단할 수가 있다. 다른 플레이어를 찾아내려면 ,IDirectPlay4::EnumPlayers 메소드를 사용한다.

이것으로 어플리케이션에의 접속이 완료해, 플레이할 준비가 갖추어졌다.


튜토리얼 3 : 서비스 프로바이더 다이얼로그의 개서

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 튜토리얼」을 참조할것.

[C++]

어플리케이션으로 DirectPlay 를 사용할 때, 서비스 프로바이더의 표준의 다이얼로그를 은폐 할 수 있게 되었다. 이하에, 그 때문에 방법을 간단하게 가리킨다. 코드예는, Override 샘플 어플리케이션에 있다.

일반적으로, 서비스 프로바이더의 다이얼로그를 모두 은폐 하는 것은 불가능하다. 표준의 TCP/IP, 모뎀, 및 시리얼 서비스 프로바이더의 다이얼로그는 은폐 하는 것이 가능하다 (IPX 에는 다이알로그 박스는 존재 없다). 그러나, 써드파티의 서비스 프로바이더가 유저로부터의 비교적 복잡한 정보를 필요로 하고 있어, 그것을 일반적인 방법으로 고쳐 쓸 수 없는 경우가 있다. 이 문제에 대한 해결책은, 그러한 다이알로그 박스를 어플리케이션의 유저 인터페이스로 표시하는 것이다. 어플리케이션이 DirectDraw® 의 풀 스크린 어플리케이션의 경우,IDirectPlay4::EnumSessions 또는 IDirectPlay4::Open 를 호출해 세션을 생성 하기 전에, 페이지 플립핑을 오프로 해 둘 필요가 있다.

서비스 프로바이더의 다이알로그 박스를 은폐하기 위한 이제(벌써) 1 개의 방법은, 어플리케이션을 로비에 대응시키는 것이다. 써드파티의 서비스 프로바이더의 대부분은, 게임을 기동하기 위한 로비도 준비해 있다. 로비로부터 기동된 게임은, 접속의 다이알로그 박스를 표시하지 않는다.

어플리케이션에서는, 최초로 IDirectPlay4::EnumConnections 를 호출해 이용 가능한 접속을 확인해, 그러한 접속의 리스트를 제공해, 유저에게 접속을 선택시킨다. 유저가 접속을 선택하면(자),IDirectPlay4::EnumSessions 또는 IDirectPlay4::Open 를 호출하기 전에, 다이알로그 박스의 개서를 시도한다.

서비스 프로바이더의 다이알로그 박스를 고쳐 쓰기 위한 스텝은 다음과 같다.

선택된 서비스 프로바이더의 서비스 프로바이더 GUID 를 조사해, 그것이 어플리케이션이 개서 방법을 파악하고 있는 기존의 서비스 프로바이더의 어느쪽이든일치할지 어떨지를 확인한다. 서비스 프로바이더 GUID 가 기존의 것이 아닌 경우는, 이하의 스텝을 임의매매라고, 다이알로그 박스의 표시를 허가한다.

특정의 서비스 프로바이더에 필요한 정보를 유저로부터 수집하기 위한 적절한 유저 인터페이스를 표시한다. IPX 의 경우는, 정보는 불필요하다. TCP/IP 의 경우는,EnumSessions 에 대한 IP 주소 (DPAID_INet 또는 DPAID_INetW)가 필요하지만,Open 를 사용해 세션을 생성 하기 위해서 필요한 것은 없다. 모뎀 투 모뎀의 경우는, 유저가 모뎀 (DPAID_Modem 또는 DPAID_ModemW)을 선택할 뿐만 아니라,EnumSessions 를 호출하면나무에 전화번호 (DPAID_Phone 또는 DPAID_PhoneW)도 필요하다. 시리얼 링크의 경우는,EnumSessions 와 Open 에 대해서 COM 포트를 구성하기 위해서,DPCOMPORTADDRESS 구조체 (DPAID_ComPort)에 데이터를 대입할 필요가 있다.

IDirectPlayLobby3::CreateCompoundAddress 메소드를 사용해,DirectPlay 주소 를 생성 한다. 건네줄 필요가 있는 주소 요소는, 서비스 프로바이더 GUID (DPAID_ServiceProvider)와 선택된 서비스 프로바이더의 개별의 주소 컴퍼넌트이다.

DirectPlay 주소를 사용해 InitializeConnection 를 호출해, DirectPlay 오브젝트를 초기화한다.

DPENUMSESSIONS_RETURNSTATUS 플래그를 설정해 EnumSessions 를 호출한다. 이것에 의해, 모든 스테이터스 다이알로그 박스가 표시되지 않게 된다. 접속을 곧바로 실행할 수 없는 경우,EnumSessions 은 DPERR_CONNECTING 에러를 돌려준다. 어플리케이션에서는, DP_OK 가 돌려주어지는 (열거에 성공한 것을 의미한다)인가, 또는 그 외의 에러가 돌려주어지는 (호출해에 실패한 것을 의미한다)까지,EnumSessions 를 정기적으로 호출할 필요가 있다.

Open 메소드로 DPOPEN_CREATE 을 사용해 세션을 생성 하는 경우는, DPOPEN_RETURNSTATUS 플래그도 지정한다. DPENUMSESSIONS_RETURNSTATUS 와 같이, 이 플래그에 의해 스테이터스 다이알로그 박스가 은폐 되어 함수가 완료할 때까지 DPERR_CONNECTING 가 돌려주어진다.

주 : 경우에 따라서는, 어플리케이션으로 실행시에 서비스 프로바이더를 문의해, 특정의 DirectPlay 주소 요소에 대한 유효한 선택사항의 리스트를 취득해야 하는 경우도 있다. 예를 들어, 시스템에 인스톨 되고 있는 모뎀의 리스트를 취득하는 경우 등이다. 이 경우, 어플리케이션에서는 다른 DirectPlay 오브젝트를 생성 해, 모뎀 서비스 프로바이더를 초기화하고 나서, DirectPlay ID 에 제로를 설정해 IDirectPlay4::GetPlayerAddress 를 호출해, 모뎀의 리스트를 보관 유지하는 DirectPlay 주소를 취득할 필요가 있다. DirectPlay 오브젝트를 릴리즈 하면(자),IDirectPlayLobby3::EnumAddress 를 사용해 주소를 해석해, 모뎀 리스트를 추출해 유저에게 제시할 필요가 있다.


튜토리얼 4 : 자동 리프레쉬식 세션 리스트의 생성

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 튜토리얼」을 참조할것.

[C++]

어플리케이션에서는,IDirectPlay4::EnumSessions 를 비동기적으로 호출해, 자동 리프레쉬식의 세션 리스트를 유지할 수가 있다. 이 방법은, Bellhop, DPChat, DPSlots, Duel, 및 Override 의 5 개의 DirectPlay 샘플로 이용되고 있다. 이러한 샘플 어플리케이션의 코드예는, 모두 참조 가능하다.

자동 리프레쉬식의 세션 리스트를 생성하기 위한 스텝은, 다음과 같다.

  1. IDirectPlay4::EnumSessions 를 호출한다. 이 때, DPENUMSESSIONS_ASYNC 플래그를 설정해, 타임 아웃을 제로로 설정한다 (이것에 의해, 서비스 프로바이더의 디폴트값이 사용된다). 이 메소드는 세션을 열거하지 않고, 즉시 돌아온다. 그러나, DirectPlay 는 백그라운드에서 세션을 열거하고 있다.
  2. 모든 세션을 표시하는 유저 인터페이스를 표시한다. 세션 리스트의 리프레쉬를 실행하는 간격에 응해, 타이머를 설정한다. 어플리케이션으로 열거의 디폴트의 타임 아웃 간격을 확인하려면 ,IDirectPlay4::GetCaps 를 호출한다.
  3. 타이머가 시작 할 때마다,EnumSessions 를 호출해 현재의 세션 리스트를 취득한다. 이 리스트는, 액티브한 세션의 완전한 리스트이다. 낡은 세션은 삭제되어 새로운 세션은 추가되어 기존의 세션은 갱신되고 있다. EnumSessions 를 호출하기 전에 리스트로부터 모든 항목을 삭제해,EnumSessionsCallback2 함수에 의해 리스트에 세션을 재차 추가한다.
  4. DPERR_CONNECTING 이외의 에러가 돌려주어졌을 경우는,EnumSessions 에 의해 돌려주어진 에러 결과를 확인해, 타이머를 정지한다. 이것에 의해 유저는, 접속을 해제하거나 캔슬하거나 할 수가 있게 된다.


DirectPlay Visual Basic 튜토리얼

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectPlay C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

여기에서는, 다음의 튜토리얼을 사용해, Visual Basic 어플리케이션에 DirectPlay 를 이행 하는 방법을 설명한다.

  • 튜토리얼 1 : 간단한 네트워크 게임의 생성
  • 튜토리얼 2 : 로비에 의한 시작의 지원


튜토리얼 1 : 간단한 네트워크 게임의 생성

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectPlay C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

이 튜토리얼에서는, DirectX for Visual Basic 를 사용해 DirectPlay 어플리케이션을 기술하기 위해서 불가결한 순서에 대해 설명한다. 샘플 코드는,Memory 샘플 어플리케이션에 근거하고 있다.

이 튜토리얼은, 다음의 스텝으로 구성되어 있다.

  • 스텝 1 : DirectPlay 의 초기화와 프로바이더의 열거
  • 스텝 2 : 접속의 초기화와 세션의 열거
  • 스텝 3 : 세션의 생성 또는 세션에의 참가
  • 스텝 4 : 플레이어의 생성
  • 스텝 5 : 게임의 시작과 메세지의 교환


스텝 1 : DirectPlay 의 초기화와 프로바이더의 열거

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectPlay C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

어플리케이션으로 DirectPlay 를 이행하기 위한 최초의 스텝은,DirectPlay4 오브젝트를 생성 해, 이용 가능한 접속 또는 서비스 프로바이더를 열거하는 것이다. Memory 샘플에서는, 몇개의 글로벌 선언의 후에, InitDPlay 프로시저내에서 다음의 순서를 실행하고 있다.

Public gObjDX As New DirectX7
Public gObjDPlay As DirectPlay4
Public gObjEnumConnections As DirectPlayEnumConnections

Public Sub InitDPlay()

  On Error GoTo FAILED
  Set gObjDPlay = gObjDX.DirectPlayCreate("")
  Set gObjEnumConnections = gObjDPlay.GetDPEnumConnections( _
          "", DPCONNECTION_DIRECTPLAY)
  Exit Sub

FAILED:
  MsgBox ("Failed to initialize DirectPlay. ")
  End
End Sub

DirectPlay4.GetDPEnumConnections 를 호출해, 서비스 프로바이더의 콜렉션을 생성 한다. guid 파라미터에는, 하늘의 캐릭터 라인을 건네준다. 어플리케이션 전용에 설계된 서비스 프로바이더를 검색하는 경우에 한정해, 어플리케이션의 GUID 를 건네준다. DP_CONNECTION_DIRECTPLAY 플래그는, 이 어플리케이션으로 로비 프로바이더를 사용하지 않는 것을 나타낸다.

InitDPlay 프로시저는, InitConnectionList 함수로부터 불려 간다. 그 후, 이 함수는, 이용 가능한 서비스 프로바이더를 리스트 박스에 대입한다. 이 함수 전체는, 다음과 같이 되어 있다.

Public Function InitConnectionList() As Boolean

  Dim NumConnections As Long
  Dim strName As String
  Dim X As Long

  Call InitDPlay     '실패하면(자), 프로그램을 중단한다.

  lstConnections.Clear

  On Error GoTo FAILED
  NumConnections = gObjEnumConnections.GetCount
  For X = 1 To NumConnections
    strName = gObjEnumConnections.GetName(X)
    Call lstConnections.AddItem(strName)
  Next X

  '선택사항을 초기화한다.
  lstConnections.ListIndex = 0
  InitConnectionList = True
  Exit Function

  '에러 핸들러.
FAILED:
  InitConnectionList = False
  Exit Function

End Function

DirectPlayEnumConnections 콜렉션은, 1 으로부터 시작된다. 이것은, DirectX for Visual Basic 외의 열거된 콜렉션에서도 같다.

다음 방향 : 스텝 2 : 접속의 초기화와 세션의 열거


스텝 2 : 접속의 초기화와 세션의 열거

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectPlay C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

유저가 [Multiple Player] 다이알로그 박스로 서비스 프로바이더와 플레이어명을 선택해,[OK] 를 클릭 하면, Memory 어플리케이션은 선택된 접속을 초기화한다. DirectPlay4.InitializeConnection 는 접속을 DirectPlay 에 바인드 해, 이후의 메소드 호출이 그 접속에 대해서 행해지도록(듯이) 한다. 다만, 물리 접속을 확립하는 것은 아니다. 물리 접속은, 세션이 열거되었을 때에 확립된다.

이 접속상에서 세션의 열거를 시도하면(자), 서비스 프로바이더에 따라서는 (모뎀 서비스 프로바이더 등), 물리 접속을 확립하기 위한 추가 정보를 요구하는 다이알로그 박스가 표시되는 경우가 있다. 유저는, 기존의 게임에 참가하는 것이 아니라, 새로운 게임을 생성 하는 경우는, 이러한 다이알로그 박스를 캔슬할 수가 있다.

Memory 에서는, 유저가 기존의 세션을 표시할 생각이 없고, 새로운 세션을 직접 생성 하고 싶은 경우에서도, 세션이 열거된다. 실제의 어플리케이션에서는, 이 동작을 변경해, 유저가 기존의 세션의 리스트를 요구했을 경우 이외는,DirectPlay4.GetDPEnumSessions 를 호출하지 않게 해도 괜찮다. 이 메소드를 호출하지 않으면 경우에 따라서는 유저에 대한 처리를 간소화할 수가 있다. 예를 들어, 모뎀 서비스 프로바이더에는, 2 개(살)이 다른 다이알로그 박스가 있다. 1 개(살)은 다이얼용으로, 이제(벌써) 1 개(살)은 응답용이다. 새로운 게임을 생성 하는 플레이어에게는, 다이얼용의 prompt는 불필요하다. 이것은, 모뎀 게임의 호스트는, 항상 다른 플레이어로부터의 호출을 대기하는 것이니까이다. 세션의 열거를 생략 해 DirectPlay4.Open 를 호출하면, 호스트에게 다이얼용의 prompt가 표시되지 않게 된다.

frmMultiplayer 내의 이하의 프로시저는, 선택된 접속을 초기화해, 다음의 다이알로그 박스에 표시되는 리스트 박스에 이용 가능한 세션을 대입한다.

Private Sub cmdOK_Click()

  Dim CIndex As Long
  Dim ConnectionMade As Boolean
  Dim objDPAddress As DirectPlayAddress

  CIndex = lstConnections.ListIndex + 1

열거된 콜렉션은 1 으로부터 시작되지만, 리스트 박스내의 리스트는 0 으로부터 시작된다. 그 때문에, 콜렉션의 인덱스를 조정할 필요가 있다.

여기서, 어플리케이션은 접속의 DirectPlay 주소를 취득해, 그것을 초기화한다.
  On Error GoTo INITIALIZEFAILED
  Set objDPAddress = gObjEnumConnections.GetAddress(CIndex)
  Call gObjDPlay.InitializeConnection(objDPAddress)
  On Error GoTo 0

다음의 호출에 대해서는, 다음에 자세하게 설명한다.

  ConnectionMade = frmSessions.UpdateSessionList

폼이 닫아 새로운 폼이 표시된다. 이 폼에는, 세션의 리스트와 세션에의 참가 또는 생성을 허가하는 버튼이 표시되고 있다.

  If ConnectionMade Then
    Hide
    frmSessions.Show
  Else
    InitDPlay
  End If
  Exit Sub
  '에러 핸들러.

INITIALIZEFAILED:
  If Err.Number <> DPERR_ALREADYINITIALIZED Then
    MsgBox ("Failed to initialize connection. ")
    Exit Sub
  End If

End Sub

세션의 열거는 이하의 함수로 실행한다. 이 함수는, 새로운 세션이 이용 가능하게 되거나 낡은 세션이 삭제되었을 때에, 세션의 리스트를 갱신하기 위해서도 이용된다.

Public Function UpdateSessionList() As Boolean

  Dim SessionCount As Integer
  Dim X As Integer
  Dim SessionData As DirectPlaySessionData
  Dim Details As String

  '낡은 리스트를 삭제한다.
  lstSessions.Clear

  Set SessionData = gObjDPlay.CreateSessionData

DirectPlaySessionData 오브젝트는, 열거하는 세션을 기술한다. Memory 에서는, 다른 어플리케이션의 세션을 이용하지 않기 때문에, 독자적으로 정의한 어플리케이션 GUID 를 (캐릭터 라인의 형식에서) 지정한다. 특정의 패스워드를 갖추는 세션만을 열거할 수 있도록(듯이) 하는 경우는, 여기서 세션 기술에 패스워드도 설정한다.

  Call SessionData.SetGuidApplication(AppGuid)
  Call SessionData.SetSessionPassword("")

DirectPlay4.GetDPEnumSessions 를 호출하면, 이용 가능한 세션만이 필요하다라고 말하는 것이 지정된다. 이것에는, 플레이어의 최대 인원수에 이르지 않으면 참가할 수 없는 세션은 포함되지 않는다.

  On Error GoTo USERCANCEL
  Set gObjDPEnumSessions = gObjDPlay.GetDPEnumSessions(SessionData, _
          0, DPENUMSESSIONS_AVAILABLE)
  On Error GoTo 0

이 메소드는, 유저가 서비스 프로바이더의 다이알로그 박스를 캔슬했을 경우에는 실패한다. 그 경우, 어플리케이션에서는, 플레이어가 새로운 세션을 생성 하려고 하고 있으면(자) 상정한다. 따라서, 이것을 치명적인 에러라고는 보지 않는다.

열거에 성공하면(자), 어플리케이션은 DirectPlayEnumSessions 오브젝트를 사용해, 각 세션에 관한 정보를 취득한다. 이것에는, 세션의 이름, 현재의 플레이어수, 최대 플레이어수등이 포함된다. 이러한 정보를 조합해 캐릭터 라인을 생성 해, 그 캐릭터 라인을 리스트 박스에 표시한다.

  On Error GoTo ENUM_ERROR
  SessionCount = gObjDPEnumSessions.GetCount
  For X = 1 To SessionCount
    Set SessionData = gObjDPEnumSessions.GetItem(X)
    Details = SessionData.GetSessionName & " (" _
            & SessionData.GetCurrentPlayers _
            & "/" & SessionData.GetMaxPlayers & ")"
    Call lstSessions.AddItem(Details)
  Next X

여기에서는 생략 하지만, 이 함수의 이후의 부분에서는, 인터페이스를 갱신해, 에러를 처리한다.

다음 방향 : 스텝 3 : 세션의 생성 또는 세션에의 참가


스텝 3 : 세션의 생성 또는 세션에의 참가

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectPlay C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

유저는,Memory 샘플의 frmSessions 폼으로, 일람에 표시된 세션에 참가하는지, 또는 새로운 세션을 생성 하는지를 선택한다.

어느 경우도, 수속은 같다. 세션을 DirectPlaySessionData 오브젝트에 기술해, 그 오브젝트를 DirectPlay4.Open 에 건네준다.

이하의 코드는,frmCreateGame 의 cmdCreate_Click 메소드로부터 발췌한 것이다. 이 코드에서는, 2 ~ 4 명까지의 플레이어를 받아들이는 새로운 게임을 생성 한다. 플레이어의 수는, 옵션 버튼에 의해 지정된다.

Dim SessionData As DirectPlaySessionData

Set SessionData = gObjDPlay.CreateSessionData
.
.
.
  '플레이어수를 설정한다.
If Option1.Value = True Then
    Call SessionData.SetMaxPlayers(2)
ElseIf Option2.Value = True Then
    Call SessionData.SetMaxPlayers(3)
Else
    Call SessionData.SetMaxPlayers(4)
End If

'세션의 기술을 종료한다.
Call SessionData.SetSessionName(txtGameName.Text)
Call SessionData.SetGuidApplication(AppGuid)
Call SessionData.SetFlags(DPSESSION_MIGRATEHOST)

'세션을 생성 ( 및 참가) 한다.
'유저가 서비스 프로바이더의 다이알로그 박스를
'캔슬했을 경우는, 실패한다. 모뎀의 경우는,
'이것이 "대답" 이다.

  On Error GoTo FAILEDOPEN
  Call gObjDPlay.Open(SessionData, DPOPEN_CREATE)
.
.
.
End Sub

세션에 참가하는 경우는, 처리가 약간 간단하게 된다. 이것은,frmSessions 의 cmdJoin_Click 와 같이, 열거로부터 세션 기술을 취득하는 것만으로 좋기 때문에이다.

Dim SessionData As DirectPlaySessionData

Set SessionData = gObjDPEnumSessions.GetItem( _
        lstSessions.ListIndex + 1)
On Error GoTo NOSESSION
Call gObjDPlay.Open(SessionData, DPOPEN_JOIN)

다음 방향 : 스텝 4 : 플레이어의 생성


스텝 4 : 플레이어의 생성

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectPlay C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

이것으로, 어플리케이션은 오픈 세션의 일부가 되었다. 그러나, 유저는, 플레이어를 생성 할 때까지는, 참가할 수가 없다.

이 순서는 극히 간단하다. DirectPlay4.CreatePlayer 에 몇개의 이름을 건네주면(자), 플레이어에 대한 일의의 ID 가 돌려주어진다. 이 ID 는, 메세지로 플레이어를 식별하는 것이므로, 중요하다. Memory 에서는, 이 ID 를 글로벌 변수 gMyPlayerID 로 유지한다.

Memory 샘플에서는,PlayerName 캐릭터 라인이, 유저에 의해 제공되는 이름이다 (디폴트의 캐릭터 라인은, 시스템에 의한 Win32 의 GetUserName 의 호출에 의해 취득된다). 어플리케이션에서는, 이 이름을, 플레이어에 대한 프렌들리명으로서 사용한다. PlayerHandle 를 다른 목적으로 내부적으로 사용하는 일도 가능하지만, Memory 에서는 불필요하다.

PlayerName = frmMultiplayer.txtYourName.Text
PlayerHandle = "Player"

On Error GoTo FAILEDCREATE
gMyPlayerID = gObjDPlay.CreatePlayer(PlayerName, PlayerHandle, 0, 0)

다음 방향 : 스텝 5 : 게임의 시작과 메세지의 교환


스텝 5 : 게임의 시작과 메세지의 교환

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectPlay C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

DirectPlay 는, 최저 1 명의 플레이어가 세션에 참가 하면, 즉시 메세지의 송신을 시작 한다. 플레이어가 세션에 참가하거나 세션으로부터 멀어지거나 할 때마다, 시스템 메세지가 송신된다. Memory 샘플에서는, 이 메세지를 계기로서frmWaiting 내의 플레이어의 리스트가 갱신된다.

게임 (또는 다른 형식의 DirectPlay 세션)을 어떻게 시작 할까는, 어플리케이션 나름이다. DirectPlay 로부터 보면(자), 어플리케이션이 메세지를 송신해 게임 상태를 갱신하고 있든지 있지 않든지가, 세션은 세션이다.

Memory 샘플에서는, 최저 1 명의 플레이어가 참가했을 때에, 호스트가 세션을 시작 할 수 있다. 호스트가 [Start] 버튼을 클릭하면(자), 세션에의 참가를 불가능하게 해, 새로운 유저가 그 세션을 이용할 수 없게 한다.

Set SessionData = gObjDPlay.CreateSessionData
Call gObjDPlay.GetSessionDesc(SessionData)
Call SessionData.SetFlags(SessionData.GetFlags + _
        DPSESSION_JOINDISABLED)
Call gObjDPlay.SetSessionDesc(SessionData)

다음에, 타입 식별자, 플레이 하는 차례에 따른 플레이어 ID 의 리스트, 및 게임 보드의 타일의 배치를 포함한 메세지를 생성 한다. 이 메세지에 응답해, 어플리케이션외의 인스턴스가, 플레이어의 차례와 게임 보드에 관한 정보를 갱신한다. 이 메세지는, 플레이어가 게임 상태에 관한 정보를 교환하는 방법의 일례를 나타내고 있다.

우선,DirectPlayMessage 의 다양한 쓰기 메소드를 사용해, 데이터를 메세지에 짜넣는다.

Dim dpMsg As DirectPlayMessage

Set dpMsg = gObjDPlay.CreateMessage

'메세지 타입을 짜넣는다.
Call dpMsg.WriteLong(MSG_SETUPBOARD)

'플레이어의 수를 짜넣는다.
Call dpMsg.WriteByte(gNumPlayers)

'플레이어 ID 를 짜넣는다.
Dim PlayerID As Long
For X = 0 To gNumPlayers - 1
    PlayerID = objDPEnumPlayers.GetDPID(X + 1)
    dpMsg.WriteLong (PlayerID)
    '플레이어 ID 의 로컬 카피를 보관 유지한다.
    gPlayerIDs(X) = PlayerID
    '플레이의 차례를 호스트에게 할당한다.
    If PlayerID = gMyPlayerID Then gMyTurn = X
Next X

'타일의 배치를 짜넣는다.
For X = 0 To NumCells - 1
    dpMsg.WriteByte (gPicArray(X))
Next X

호스트의 어플리케이션 인스턴스는, 여기서 스스로의 게임 상태를 갱신할 필요가 있다. 어플리케이션의 인스턴스는, 호스트가 송신한 메세지를 수신하지 않는다. 그 때문에, 호스트에게 있어서는, 여기가 다른 인스턴스가 메세지를 수신했을 때에 실행하는 갱신을 실행하는 마지막 찬스이다.

다음에, DPSEND_GUARANTEED 플래그를 사용해, 이 메세지를 다른 모든 플레이어에게 송신한다. 이 플래그를 설정하는 것은, 다른 모든 플레이어가 이 정보를 수신할 필요가 있기 때문이다 (움직임의 빠른 액션 게임에서 몇 안 되는 변경을 통지하는 경우는, 보증 없음의 메세지로 충분하다).

Call gObjDPlay.Send(gMyPlayerID, DPID_ALLPLAYERS, _
        DPSEND_GUARANTEED, dpMsg)

수신측에서는,Sub Main 프로시저로 메세지를 검색한다. 이 때,DoEvents 를 사용해, 문의중에 다른 처리를 실행할 수 있도록(듯이) 한다.

Do While DoEvents()
    GetDPMessages
Loop

GetDPMessages 프로시저에서는, 보류가 되어 있는 메세지의 수를 확인한다.

Dim MsgCount As Long
MsgCount = gObjDPlay.GetMessageCount(gMyPlayerID)

다음에, 각 메세지를 취득해, 그것을 DirectPlayMessage 오브젝트의 dpMsg 에 대입한다. 게다가 메세지의 타입을 취득한다. 이것은, 시스템 메세지의 경우도, Memory 로 정의되는 메세지의 경우도, 항상 최초의 Long 값이다.

Dim FromPlayerID As Long
Dim ToPlayerID As Long
Dim dpMsg As DirectPlayMessage
Dim MsgType As Long
'일부의 선언에 대해서는 생략 한다. GlobalModule.bas 를 참조할것.
.
.
.
Do While MsgCount > 0
    Set dpMsg = gObjDPlay.Receive(FromPlayerID, ToPlayerID, _
            DPRECEIVE_ALL)
    MsgType = dpMsg.ReadLong()

    MsgCount = MsgCount - 1

시스템 메세지의 경우,FromPlayerID 은 DPSYS_MESSAGE 이다. 그 이외는, 모두 어플리케이션 정의의 메세지이다. Memory 는, MSG_SETUPBOARD 라고 하는 타입의 어플리케이션 정의를 찾아내면(자), 데이터를 짜넣어지고 있는 차례로 읽기, 몇개의 추가 처리를 실행해 게임 상태를 갱신해, 플레이를 시작 할 수 있도록(듯이) 한다.

    Select Case MsgType

        Case MSG_SETUPBOARD

          '플레이어의 수.
          gNumPlayers = dpMsg.ReadByte

          '플레이순서의 플레이어 ID. 사용되어 있지 않은 플레이어의 ID 는 0.
          For X = 0 To gNumPlayers - 1
              gPlayerIDs(X) = dpMsg.ReadLong
              If gPlayerIDs(X) = gMyPlayerID Then gMyTurn = X
          Next X

          '타일의 배치.
          For X = 0 To NumCells - 1
              gPicArray(X) = dpMsg.ReadByte
          Next X

          '게임 보드를 표시한다.
          frmWaiting.Hide
          gGameUnderway = True
          frmGameBoard.Show
.
.
.
    End Select
.
.
.
Loop


튜토리얼 2 : 로비에 의한 시작의 지원

이 튜토리얼에서는, 어플리케이션으로 로비에 의한 외부로부터의 시작과 로비에 의해 시작 된 세션에의 접속을 지원 하는 방법을 나타낸다. 이러한 테크닉을 사용하고 있는 어플리케이션은, 로비 또는 유저로부터 기동할 수가 있어 로비에서 생성 된 어플리케이션 세션에 자동적으로 참가한다.

이러한 주제의 개요에 대해서는, 「로비 대응 어플리케이션의 생성」을 참조할것.

이 튜토리얼은, 다음의 스텝으로 구성되어 있다.

  • 스텝 1 : 어플리케이션의 등록
  • 스텝 2 : 접속 설정의 취득
  • 스텝 3 : 세션에의 참가

이 샘플 코드는,Chat 샘플에 근거하고 있다.


스텝 1 : 어플리케이션의 등록

로비 클라이언트로부터 어플리케이션을 인식할 수 있도록(듯이) 하려면 , 어플리케이션을 등록할 필요가 있다. 로비 대응 어플리케이션을 등록하려면 , DirectSetup의 DirectXRegisterApplication C/C++ 함수를 사용하는지,DirectPlayLobby3.RegisterApplication 메소드를 사용하는 독자적인 등록 유틸리티를 제공한다. 이하의 샘플 프로시저는, DXVBChat.exe 를 등록한다. 이 때, DXVBChat.exe 는 등록을 실시하는 어플리케이션과 같은 폴더에 없으면 안 된다.

Dim dx As New DirectX7
Dim dpl As DirectPlayLobby3
Const AppGuid = "{EB5E7E20-0303-11d3-9AAB-00104BCC1EAA}"

Private Sub RegisterApp()

  Dim dpappdesc As DPAPPLICATIONDESC2
  Dim dpl as DirectPlayLobby3

  With dpappdesc
    . strApplicationName = "DXVBChat"
    . strCommandLine = ""
    . strCurrentDirectory = App.Path
    . strDescription = "Chat (DirectX for Visual Basic)"
    . strFilename = "DXVBChat.exe"
    . strGuid = AppGuid
    . strPath = App.Path
  End With

  On Local Error GoTo ERRORS

  Set dpl = dx.DirectPlayLobbyCreate
  Call dpl.RegisterApplication(dpappdesc)
  Exit Sub

ERRORS:
  MsgBox "Failed to register application. "
  Unload Me

End Sub

이하의 프로시저는, 같은 어플리케이션의 등록을 해제한다.

Private Sub UnregisterApp()

  On Local Error GoTo FAILED
  Call dpl.UnregisterApplication(AppGuid)
  MsgBox "Unregistration successful. "
  Exit Sub

FAILED:
  If Err.Number = DPERR_UNKNOWNAPPLICATION Then
    MsgBox "Application not registered. "
  End If
  Unload Me

End Sub

다음 방향 : 스텝 2 : 접속 설정의 취득


스텝 2 : 접속 설정의 취득

이 스텝에서는, 어플리케이션으로 DirectPlay 를 초기화해, 어플리케이션이 로비에 의해 시작 되고 있는지 어떤지를 판단한다. 로비에 의해 시작 되고 있는 경우는, 즉시 접속 설정을 취득한다. 그렇지 않은 경우는, 접속 설정을 대기한다.

최초로,DirectPlayLobby3 오브젝트를 생성 한다. 거기에는, 초기화된 DirectX7 오브젝트의 objDX 를 사용한다.

Public Function InitDPlay() As Boolean

  InitDPlay = True

  On Local Error GoTo FAILED
  Set objDPLobby = objDX.DirectPlayLobbyCreate

다음에,DirectPlayLobby3.GetConnectionSettings 를 호출한다. 어플리케이션이, 로비 클라이언트내에서의 DirectPlayLobby3.RunApplication 의 호출해에 응답해 시작 되고 있는 경우,GetConnectionSettings 은 성공한다. 그렇지 않은 경우는,DPERR_NOTLOBBIED 가 돌려주어진다.

  On Local Error Resume Next
  Set objDPLConnection = objDPLobby.GetConnectionSettings(0)

  '어플리케이션은 로비에 의해 시작 되었다.
  If Err.Number = 0 Then GoTo GOTCONNECTION

어플리케이션이 로비에 의해 기동되어 있지 않은 경우는, 이 시점에서 유저에 대해서, 싱글 플레이어 게임을 시작 하는지, 내부 로비 클라이언트를 개입시켜 세션에 접속하는지를 선택시킬 수도 있다. 샘플 어플리케이션에서는, 로비 접속을 대기하는 방법을 채용하고 있다. 우선,DirectPlayLobby3.WaitForConnectionSettings . (을)를 호출해, 대기 모드에 들어간다. 이것에 의해, 유저가 로비 클라이언트로 어플리케이션 세션을 생성 하거나 또는 어플리케이션 세션에 참가하거나 했을 때에,RunApplication 에 의해 어플리케이션의 다른 인스턴스가 실행되지 않게 된다. 대신에, 이 인스턴스로 접속 설정을 이용할 수 있게 된다.

  On Local Error GoTo FAILED
  Call objDPLobby.WaitForConnectionSettings(DPLWAIT_DEFAULT)

여기서, 샘플 어플리케이션은 다이알로그 박스를 표시한다. 이 다이알로그 박스는, 접속이 확립되는지, 또는 유저가 캔슬할 때까지, 액티브한 그대로가 되어 있다.

  frmWaiting.Show
  Call WaitForConnectionMessage

어플리케이션이 실제로 대기하는 것은, 이 부분이다. WaitForConnectionMessage 함수는, 로비로부터 DPLSYS_NEWCONNECTIONSETTINGS 메세지를 수신하는지, 또는 유저가 캔슬할 때까지, 블록 한다.

Public Sub WaitForConnectionMessage()
  Dim msg As DirectPlayMessage
  Dim flags As Long
  Dim MsgType As Long

  On Local Error Resume Next
  gGotConnection = False
  Do While DoEvents
      Set msg = objDPLobby.ReceiveLobbyMessage(0, flags)
      If Not (msg Is Nothing) Then
        MsgType = msg.ReadLong
        If MsgType = DPLSYS_NEWCONNECTIONSETTINGS Then
          gGotConnection = True
          Exit Do
        End If
      End If
  Loop
  Exit Sub
End Sub

샘플 어플리케이션에서는, 유저가 다이알로그 박스를 캔슬 하면, FALSE 가 돌려주어진다. 이것은, 가시 상태의 폼이 그 밖에 존재하지 않고,DoEvents 가 FALSE 를 돌려주기 때문이다. 가시 상태의 폼이 그 밖에 존재하는 어플리케이션에서는, 다른 방법을 사용해, 유저가 캔슬을 선택했을 때에 루프를 빠질 필요가 있다.

호출측의 프로시저에서는, DPLSYS_NEWCONNECTIONSETTINGS 를 받으면(자), 상태의 다이알로그 박스를 닫아,DirectPlayLobbyConnection 오브젝트를 취득한다.

  If gGotConnection Then
    frmWaiting.Hide
    Set objDPLConnection = objDPLobby.GetConnectionSettings(0)
  Else
    GoTo FAILED  '유저가 캔슬했다.
  End If

다음 방향 : 스텝 3 : 세션에의 참가


스텝 3 : 세션에의 참가

여기서, 2 개의 코드 브랜치(branch) (로비에 의한 시작과 유저에 의한 시작)가 1 개에 모인다. 프로그램에서는, 로비로부터 접속 설정을 취득했으므로, 어플리케이션 세션을 로컬인 DirectPlay4 오브젝트에 접속할 수가 있다. 이 오브젝트는, 이하에서는 objDPlay 와 나타내지고 있다.

GOTCONNECTION:
  On Local Error GoTo FAILED
  Set objDPlay = objDPLobby.Connect(0)

이것으로, 어플리케이션은 세션에 관해서 필요한 정보를 뭐든지 취득해, 접속 데이터의 정보에 근거해 플레이어를 생성 할 수 있게 되었다.

  '이하는, 글로벌하게 선언된다.
  ' Dim objDPSessionData as DirectPlaySessionData
  ' Dim gMyPlayerName As String
  ' Dim gMyPlayerID As Long

  Set objDPSessionData = objDPLConnection.GetSessionDesc
  '세션 데이터에는, 세션의 이름, 플레이어의 수등이
  '포함되어 있다. 이것들은 모두, staging 영역에서 설정되어 있다.

  gMyPlayerName = objDPLConnection.GetPlayerShortName
  gMyPlayerID = objDPlay.CreatePlayer(gMyPlayerName, "PLAYER", _
          0, DPPLAYER_DEFAULT)
  Exit Function

이것으로, 플레이어가 메세지의 송수신을 시작 하기 위해서 필요한 준비가 갖추어졌다.

처리가 잘 되지 않았던 경우는, 에러 핸들러에 의해 InitDPlay 의 반환값을 FALSE 로 설정한다. 이것으로, 어플리케이션을 신속하게 종료할 수 있게 된다.

FAILED:
  InitDPlay = False

End Function


DirectPlay 레퍼런스

여기에서는, DirectPlay® 가 제공하는 C/C++ 와 Visual Basic® 의 어플리케이션 프로그래밍 인터페이스 (API) 요소에 대한 레퍼런스 정보를 나타낸다. 레퍼런스는 언어별로 편성되고 있다.

  • DirectPlay C/C++ 레퍼런스
  • DirectPlay Visual Basic 레퍼런스


DirectPlay C/C++ 레퍼런스

DirectPlay C/C++ 어플리케이션 프로그래밍 인터페이스의 레퍼런스는, 다음과 같이 분류된다.

  • 인터페이스
  • 함수
  • 콜백 함수
  • 구조체
  • 시스템 메세지
  • 표준 로비 메세지
  • DirectPlay 정의가 끝난 프로퍼티
  • 반환값


인터페이스

여기에서는, DirectPlay 의 다음의 인터페이스의 메소드에 관한 레퍼런스를 나타낸다.

  • IDirectPlay4
  • IDirectPlayLobby3


IDirectPlay4

어플리케이션에서는,IDirectPlay4 인터페이스의 메소드를 사용해 DirectPlay 오브젝트를 생성 해, 시스템 레벨 변수를 사용한다 (IDirectPlay4A 인터페이스는,IDirectPlay4 인터페이스와 같다. 다만,IDirectPlay4A 에서는 ANSI 문자를 사용해,IDirectPlay4 에서는 Unicode 를 사용한다).

IDirectPlay4 인터페이스의 메소드는, 다음과 같이 분류할 수 있다.

세션 관리 | Close
 | EnumConnections
 | EnumSessions
 | GetCaps
 | GetGroupConnectionSettings
 | GetSessionDesc
 | InitializeConnection
 | Open
 | SecureOpen
 | SetGroupConnectionSettings
 | SetSessionDesc
 | StartSession
플레이어 관리 | CreatePlayer
 | DestroyPlayer
 | EnumPlayers
 | GetPlayerAccount
 | GetPlayerAddress
 | GetPlayerCaps
 | GetPlayerData
 | GetPlayerFlags
 | GetPlayerName
 | SetPlayerData
 | SetPlayerName
메세지 관리 | CancelMessage
 | CancelPriority
 | GetMessageCount
 | GetMessageQueue
 | Receive
 | Send
 | SendChatMessage
 | SendEx
그룹 관리 | AddGroupToGroup
 | AddPlayerToGroup
 | CreateGroup
 | CreateGroupInGroup
 | DeleteGroupFromGroup
 | DeletePlayerFromGroup
 | DestroyGroup
 | EnumGroupPlayers
 | EnumGroups
 | EnumGroupsInGroup
 | GetGroupData
 | GetGroupFlags
 | GetGroupName
 | GetGroupOwner
 | GetGroupParent
 | SetGroupData
 | SetGroupName
 | SetGroupOwner
초기화 | Initialize

IDirectPlay4 인터페이스는, 모든 COM 인터페이스와 같이,IUnknown 인터페이스의 메소드를 계승하고 있다. IUnknown 인터페이스는, 다음의 3 개의 메소드를 지원 하고 있다.

IUnknown | AddRef
 | QueryInterface
 | Release

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.


IDirectPlay4::AddGroupToGroup

IDirectPlay4::AddGroupToGroup 메소드는, 어느그룹에의 쇼트 컷을 기존의 그룹에 추가한다. 이것에 의해, 링크한 그룹을 IDirectPlay4::EnumGroupsInGroup 메소드로 열거하는 것이 가능하게 된다. 그룹의 쇼트 컷을 다른 그룹으로부터 삭제하려면 ,DeleteGroupFromGroup 를 호출한다.

HRESULT AddGroupToGroup(
  DPID idParentGroup,
  DPID idGroup
);

파라미터

idParentGroup
쇼트 컷의 추가처 그룹의 그룹 ID. 유효한 임의의 그룹 ID 를 지정 가능.
idGroup
쇼트 컷을 추가하는 그룹의 그룹 ID. 유효한 임의의 그룹 ID 를 지정 가능.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP

주의

이 메소드를 사용해, 어느 그룹을 복수의 그룹 「 안」에 배치할 수 있다.

이 변경을 플레이어에게 알리기 위해서(때문에),DPMSG_ADDGROUPTOGROUP 시스템 메세지가 생성된다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::CreateGroupInGroup ,IDirectPlay4::DeleteGroupFromGroup ,IDirectPlay4::EnumGroupsInGroup ,DPMSG_ADDGROUPTOGROUP


IDirectPlay4::AddPlayerToGroup

IDirectPlay4::AddPlayerToGroup 메소드는, 플레이어를 기존의그룹에 추가한다. 플레이어는, 복수의 그룹의 멤버가 될 수가 있다. 이 API 를 사용해, 그룹을 다른 그룹에 추가할 수 없다 (IDirectPlay4::AddGroupToGroup 를 참조). 어플리케이션에서는, 임의의 플레이어를 임의의 그룹에 추가할 수 있다 (로컬에 생성되어 있지 않은 플레이어 및 그룹을 포함한다).

HRESULT AddPlayerToGroup(
  DPID idGroup,
  DPID idPlayer
);

파라미터

idGroup
추가하는 그룹의 그룹 ID.
idPlayer
그룹에 추가하는 플레이어의 플레이어 ID.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_CANTADDPLAYER
DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDPLAYER
DPERR_NOSESSIONS

idPlayer 가 플레이어 ID 가 아닌 경우, 또는 ID 가 로컬 플레이어의 것이 아닌 경우는,DPERR_INVALIDPLAYER 를 돌려준다.

주의

DPMSG_ADDPLAYERTOGROUP 시스템 메세지가 생성 되어 그 외의 모든 플레이어에게 송신된다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::CreateGroup ,IDirectPlay4::DeletePlayerFromGroup ,DPMSG_ADDPLAYERTOGROUP


IDirectPlay4::CancelMessage

IDirectPlay4::CancelMessage 메소드는, 송신 큐에 아직 남아 있는 특정의 메세지 (또는 모든 메세지)를 취소한다. CancelMessage 는, 비동기 메세지에게만 적용된다.

특정의 메세지를 취소하기 위해서(때문에)는, 어플리케이션으로 IDirectPlay4::SendEx 메소드에 의해 돌려주어지는 메세지 ID 를 취득해 보존할 필요가 있다.

메시지 큐에 남아 있지만, 일부가 이미 송신되고 있는 메세지에 대해서는, 취소할 수가 없다. 그룹에 송신되는 메세지는, 그룹의 일부의 멤버에 이미 송신되고 있으면(자) 취소할 수가 없다.

메세지를 취소해도, 그 취지를 나타내는 DPMSG_SENDCOMPLETE 시스템 메세지는 생성된다.

HRESULT CancelMessage(
  DWORD dwMsgID,
  DWORD dwFlags
);

파라미터

dwMsgID
취소하는 특정의 메세지의 ID. 이 ID 는,IDirectPlay4::SendEx 를 사용해 메세지를 송신 하면 돌려주어진다. 모든 메세지를 취소하는 경우는 0 을 지정한다.
dwFlags
이 파라미터는 장래의 사용에 대비해 예약되고 있으므로, 0 으로 설정해 둔다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_CANCELFAILED
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_UNKNOWNMESSAGE
DPERR_UNSUPPORTED

메세지를 취소할 수가 없었던 경우는, DPERR_CANCELFAILED 를 돌려준다. 또, 취소하는 메세지의 ID 가 무효인 경우는, DPERR_UNKNOWNMESSAGE 를 돌려준다. 송신 큐에 메세지가 없었던 경우는, DP_OK 를 돌려준다.

주의

DirectPlay 프로토콜이세션 기술로 지정되고 있는 경우,CancelMessage 의 모든 옵션을 사용할 수 있다. 그 이외의 경우, 어플리케이션에서는 서비스 프로바이더에 의해 이행 되고 있는 옵션을 판정하기 위해서,GetCaps 를 호출할 필요가 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::SendEx ,IDirectPlay4::Send ,IDirectPlay4::GetMessageQueue ,DPMSG_SENDCOMPLETE ,IDirectPlay4::CancelPriority


IDirectPlay4::CancelPriority

IDirectPlay4::CancelPriority 메소드는, 아직 송신 큐에 들어가 있는 특정의, 또는 특정 범위의 우선 순위의 메세지를, 모두 취소할 때 사용한다. CancelPriority 는, 비동기 메세지에게만 적용된다.

메시지 큐에 남아 있지만, 일부가 이미 송신되고 있는 메세지에 대해서는, 취소할 수 없다. 그룹에 송신되는 메세지로, 그 그룹의 일부에 이미 송신되고 있는 경우는 취소할 수가 없다.

메세지를 취소해도, 메세지가 삭제된 것을 나타내는 DPMSG_SENDCOMPLETE 시스템 메세지는 생성된다.

HRESULT CancelPriority(
  DWORD dwMinPriority,
  DWORD dwMaxPriority,
  DWORD dwFlags
);

파라미터

dwMinPriority
취소하는 우선 순위의 범위에서, 가장 낮은 우선 순위.
dwMaxPriority
취소하는 우선 순위의 범위에서, 가장 높은 우선 순위. dwMinPriority 보다 높지 않으면 안 된다. 가능한 최고 우선 순위의 MAXPRIORITY 를 설정한다.
dwFlags
이 파라미터는 장래의 사용에 대비해 예약되고 있으므로, 0 으로 설정해 둔다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_UNSUPPORTED

송신 큐에 메세지가 전혀 없는 경우는, DP_OK 를 돌려준다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::SendEx ,IDirectPlay4::Send ,IDirectPlay4::GetMessageQueue ,DPMSG_SENDCOMPLETE ,IDirectPlay4::CancelMessage


IDirectPlay4::Close

IDirectPlay4::Close 메소드는, 전에 열린 세션을 닫는다. 로컬에 생성 된 그룹은, 세션의호스트에 의해 소유되게 된다.

HRESULT Close( );

파라미터

없음.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS

주의

로컬에 생성 된 플레이어는 모두 파기되어 다른 세션 참가자에게는 적절한 DPMSG_DELETEPLAYERFROMGROUP 시스템 메세지와 DPMSG_DESTROYPLAYERORGROUP 시스템 메세지가 송신된다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::DestroyPlayer ,DPMSG_DESTROYPLAYERORGROUP ,IDirectPlay4::Open


IDirectPlay4::CreateGroup

IDirectPlay4::CreateGroup 메소드는, 현재 세션내에서그룹을 생성 한다. 그룹과는, 플레이어 또는 그 외의 그룹의 논리적인 집합이다.

HRESULT CreateGroup(
  LPDPID lpidGroup,
  LPDPNAME lpGroupName,
  LPVOID lpData,
  DWORD dwDataSize,
  DWORD dwFlags
);

파라미터

lpidGroup
DirectPlay 그룹 ID 가 설정되는 변수에의 포인터. 이 값은, DirectPlay 에 의해 정의된다.
lpGroupName
그룹의 이름이 설정되어 있는 DPNAME 구조체에의 포인터. NULL 가 설정되어 있는 경우는, 그룹에 초기설정명이 없는 것을 나타낸다. lpGroupName 의 이름은 유저가 사용하기 위해(때문에)인 만큼 설정한다. 시스템내에서는 사용되지 않기 때문에, 일의가 아니어도 상관없다.
lpData
시스템내에서 그룹 ID 에 관련짓는 어플리케이션에 의해 정의된 리모트 데이터의 블록에의 포인터. NULL 가 설정되어 있는 경우는, 그룹에 초기설정명이 없는 것을 나타낸다. 여기서 지정한 데이터는,IDirectPlay4::SetGroupData 가 불려 갔을 경우와 같이,세션내의 그 외 모든 어플리케이션에 전파 되는 리모트 데이터이다고 보여진다.
dwDataSize
lpData 가 가리키는 데이터 블록의 사이즈 (바이트 단위).
dwFlags
생성 하는 그룹의 타입을 나타내는 플래그. 디폴트 (dwFlags = 0)에서는, 그룹의 소유권은 소유자가 세션을 멀어진 시점에서호스트로 이행해, 그룹은 명시적으로 파기될 때까지 존속한다.

설정 가능한 값은, 다음의 언젠가이다.

DPGROUP_HIDDEN
은폐 플래그에 의해 그룹을 생성 한다. 그룹이 열거되면(자), 은폐 플래그가 설정된다. 로비 세션에서는, 은폐 그룹은 IDirectPlay4::AddGroupToGroup 에 의해 생성 된 쇼트 컷으로부터 마셔 사용할 수 있다. 이 플래그는, 플레이어에게 있어 DPPLAYER_SPECTATOR 플래그와 같이 기능한다.
DPGROUP_STAGINGAREA
그룹을 staging 영역으로서 생성 한다. staging 영역은, 새로운 세션을 기동하기 위해서 플레이어를 정렬할 경우에 사용한다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_CANTADDPLAYER
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS

주의

그룹이 클라이언트/서버 세션으로 생성 되었을 경우, 그룹 통지 메세지는 송신되지 않는다. 그룹은, 머신이 클라이언트일까 호스트일까에 관계없이, 그 그룹을 생성 한 머신으로 밖에 표시할 수 없다.

그룹이 피어 투 피어 세션으로 생성 되었을 경우,CreateGroup 에 의해 그 외의 모든 플레이어에게 송신되는 DPMSG_CREATEPLAYERORGROUP 시스템 메세지가 생성된다. 어플리케이션으로 IDirectPlay4::Send 를 사용 하면, 1 개의 메세지를 그룹 ID 에 송신하는 것만으로 그 그룹내의 모든 플레이어에게 메세지를 송신할 수 있다. DirectPlay 는, 멀티 캐스트를 사용해, 이 메세지를 송신하는 (이 기능이서비스 프로바이더에 의해 지원 되고 있는 경우)인가, 또는 각 메세지를 그룹내의 각 플레이어에게 송신한다.

메세지의 수수나 데이터가 관련짓고로 그룹을 식별 하면나무는, 어플리케이션에 돌려주어지는 그룹 ID 를 사용한다. DirectPlay 에 의해 할당할 수 있었던 플레이어 ID 나 그룹 ID 는 세션내에서 항상 일의이다.

CreateGroup 에 의해 생성 되는 그룹은, 세션내에서 최상정도 그룹이 된다. 이것들은,IDirectPlay4::EnumGroups 에 의해 열거된다. IDirectPlay4::CreateGroupInGroup 메소드에서는, 친그룹의 서브 그룹이 되는 그룹이 생성 된다.

그룹은, 일반기업의 어플리케이션에서도 사용할 수 있다. 로비 세션에서는, 플레이어를 수집하는 메카니즘으로서 staging 영역을 사용해,IDirectPlay4::StartSession 를 사용해 새로운 어플리케이션 세션을 기동한다.

그룹을 생성 한 플레이어가, 그 디폴트의 소유자가 된다. 이름이나 리모트 데이터등의 그룹 프로퍼티를 변경할 수 있는 것은, 소유자 뿐이다. 소유자가 세션을 빠지면(자), 소유권은 세션의호스트로 옮긴다.

세션내의 그룹을 인식하고 있는 플레이어이면, 그룹의 멤버를 변경하거나 그룹을 삭제하거나 할 수 있다.

그룹은, 명시적으로 파기될 때까지 세션내에 존속한다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

DPNAME ,DPMSG_CREATEPLAYERORGROUP ,IDirectPlay4::AddGroupToGroup ,IDirectPlay4::DestroyGroup ,IDirectPlay4::EnumGroups ,IDirectPlay4::EnumGroupPlayers ,IDirectPlay4::Send ,IDirectPlay4::SetGroupData ,IDirectPlay4::SetGroupName ,IDirectPlay4::CreateGroupInGroup ,IDirectPlay4::GetGroupFlags


IDirectPlay4::CreateGroupInGroup

IDirectPlay4::CreateGroupInGroup 메소드는, 기존의 그룹내에그룹을 생성 한다. 다른 그룹내에 생성 한 그룹을 열거할 수 있는 것은,IDirectPlay4::EnumGroupsInGroup 메소드 뿐이다. 이 방법으로 생성 한 그룹을 파기하려면 ,IDirectPlay4::DestroyGroup 메소드를 호출한다.

HRESULT CreateGroupInGroup(
  DPID idParentGroup,
  LPDPID lpidGroup,
  LPDPNAME lpGroupName,
  LPVOID lpData,
  DWORD dwDataSize,
  DWORD dwFlags
);

파라미터

idParentGroup
그룹의 생성처 그룹의 ID. 이 그룹은 기존의 그룹이 아니면 안된다.
lpidGroup
생성 한 그룹의 DirectPlay 그룹 ID 를 받는 변수의 주소.
lpGroupName
생성 하는 그룹의 이름을 보관 유지하고 있는 DPNAME 구조체에의 포인터. NULL 가 설정되어 있는 경우는, 그룹에 초기설정명이 없는 것을 나타낸다.
lpData
최초로 그룹 ID 에 관련짓는 어플리케이션에 의해 정의된 리모트 데이터의 블록에의 포인터. NULL 가 설정되어 있는 경우는, 그룹에 초기 데이터가 없는 것을 나타낸다. 여기서 지정한 데이터는,IDirectPlay4::SetGroupData 가 불려 갔을 경우와 같이,세션내의 그 외 모든 어플리케이션에 전파 되는 리모트 데이터이다고 보여진다.
dwDataSize
lpData 파라미터의 포인트처 데이터 블록의 사이즈 (바이트 단위).
dwFlags
생성 하는 그룹의 타입을 나타내는 플래그. 디폴트 (dwFlags = 0)는, 보통의 그룹이다.
DPGROUP_HIDDEN
은폐 플래그에 의해 그룹을 생성 한다. 그룹이 열거될 때, 은폐 플래그가 설정된다. 로비 세션에서는, 은폐 그룹은 IDirectPlay4::AddGroupToGroup 에 의해 생성 된 쇼트 컷으로부터 마셔 사용할 수 있다.
DPGROUP_STAGINGAREA
그룹을 staging 영역으로서 생성 한다. staging 영역은,IDirectPlay4::StartSession 메소드를 사용해 DirectPlay 세션을 기동할 경우에 사용한다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_CANTADDPLAYER
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS

그룹이 생성 할 수 없었던 경우는 DPERR_CANTADDPLAYER 를 돌려준다. 또, 친그룹 ID 가 무효인 경우는,DPERR_INVALIDGROUP 를 돌려준다.

주의

그룹이 클라이언트/서버 세션으로 생성 되었을 경우, 그룹 통지 메세지는 송신되지 않는다. 그룹은, 머신이 클라이언트일까 호스트일까에 관계없이, 그 그룹을 생성 한 머신으로 밖에 표시할 수 없다.

그룹이 피어 투 피어 세션으로 생성 되었을 경우,CreateGroupInGroup 에 의해, 이 변경을 플레이어에게 알리기 위해서(때문에) DPMSG_CREATEPLAYERORGROUP 시스템 메세지가 생성된다.

최상정도 그룹을 파기했을 경우, 거기에 포함되는 멤버 그룹도 모두 파기되어 파기 메세지가 송신된다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::DestroyGroup ,IDirectPlay4::EnumGroupsInGroup ,DPMSG_CREATEPLAYERORGROUP


IDirectPlay4::CreatePlayer

IDirectPlay4::CreatePlayer 메소드는, 현재 세션에 로컬 플레이어를 생성 한다.

HRESULT CreatePlayer(
  LPDPID lpidPlayer,
  LPDPNAME lpPlayerName,
  HANDLE hEvent,
  LPVOID lpData,
  DWORD dwDataSize,
  DWORD dwFlags
);

파라미터

lpidPlayer
DirectPlay 플레이어 ID 가 설정되는 변수에의 포인터. 이 값은, DirectPlay 에 의해 정의된다.
lpPlayerName
플레이어의 이름이 설정되어 있는 DPNAME 구조체에의 포인터. NULL 가 설정되어 있는 경우는, 플레이어에게 초기설정명이 없는 것을 나타낸다. lpPlayerName 의 이름은 유저가 사용하기 위해(때문에)인 만큼 설정한다. 시스템내에서는 사용되지 않기 때문에, 일의가 아니어도 상관없다.
hEvent
플레이어 앞으로 설정된 메세지가 수신되었을 때에 DirectPlay 로부터 그 통지를 받은 어플리케이션에 의해 생성 되는 이벤트 오브젝트.
lpData
플레이어 ID 에 관련짓는 어플리케이션에 의해 정의된 데이터의 블록에의 포인터. NULL 가 설정되어 있는 경우는, 플레이어에게 초기 데이터가 없는 것을 나타낸다. 여기서 지정한 데이터는,IDirectPlay4::SetPlayerData 가 불려 갔을 경우와 같이, 세션내의 그 외 모든 어플리케이션에 전파 되는 리모트 데이터이다고 보여진다.
dwDataSize
LpData 파라미터의 포인트처 데이터 블록의 사이즈 (바이트 단위).
dwFlags
생성 하는 플레이어의 타입을 나타내는 플래그. 디폴트 (dwFlags = 0)는, 관객은 아니고, 서버도 아닌 플레이어를 나타낸다.
DPPLAYER_SERVERPLAYER
플레이어는, 클라이언트/서버 통신의 서버 플레이어이다. 서버 플레이어를 생성 할 수 있는 것은,호스트 뿐이다. 1 개의 세션에 존재할 수 있는 서버 플레이어는 1 명 뿐이다. 이 플래그가 지정되고 있는 경우,CreatePlayer 로부터는 DPID_SERVERPLAYER 의 플레이어 ID 가 반드시 돌려주어진다.
DPPLAYER_SPECTATOR
플레이어는 관객으로서 생성 된다. 관객 플레이어는, 관객으로서 플래그가 설정되는 것을 제외하면, 보통의 플레이어와 같다. 어플리케이션으로, 관객 플레이어의 기능을 제한할 수 있다. 관객 플레이어의 동작은 모두, 어플리케이션이 정의한다. DirectPlay 는, 다만 이 플래그를 전파 하는 것만으로 있다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_CANTADDPLAYER
DPERR_CANTCREATEPLAYER
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_NOCONNECTION

주의

1 개의 프로세스로, 복수의 로컬 플레이어가, 같은 컴퓨터의 다른 플레이어나 리모트 컴퓨터의 플레이어와 DirectPlay 오브젝트를 개입시켜 통신하는 것이 가능하다.

처리가 정상적으로 종료 하면, 이 메소드는, 신규 플레이어가 세션에 참가한 것을 알리는 DPMSG_CREATEPLAYERORGROUP 시스템 메세지를세션의 다른 모든 플레이어에게 송신한다. 디폴트에서는, 모든 로컬 플레이어는 모든 시스템 메세지의 카피를 수신한다.

메세지의 수수나 데이터가 관련짓고로 플레이어를 식별 하면나무는, 어플리케이션에 돌려주어지는 플레이어 ID 를 사용한다. DirectPlay 에 의해 할당할 수 있었던 플레이어 ID 나그룹 ID 는 세션내에서 항상 일의이다.

플레이어를 생성 한 어플리케이션에서만, 다음의 처리가 가능하다.

  • 플레이어의 이름을 변경한다.
  • 플레이어의 리모트 데이터를 변경한다.
  • 플레이어로부터의 메세지를 송신한다.

어플리케이션이 세션을 닫았을 경우, 생성 된 로컬 플레이어는 모두 자동적으로 파기된다. IDirectPlay4::DestroyPlayer 를 사용 하면, 플레이어를 생성 한 세션 호스트나 어플리케이션은 언제라도 그것을 파기할 수 있다.

어플리케이션이 DirectPlay 메세지를 취득하는데 다른 thread를 사용했을 경우, NULL 이외의 hEvent 를 지정해, 그것을 동기 처리로 사용하는 것을 강하게 추천 한다. 이 이벤트는, 플레이어가 메세지를 수신 하면 설정된다. 메세지 수신 thread내에서, 플레이어가 메세지를 가지고 있을지 어떨지를 판정하려면 , thread내의 Win32® API WaitForSingleObject 를 사용한다 (또는, 복수의 이벤트가 사용되고 있는 경우는 WaitForMultipleObjects 를 사용한다). 메세지를 기다리고 있는 다른 thread내의 IDirectPlay4::Receive 로 루프 처리를 실시하는 것은 비효율적이다. 모든 로컬 플레이어로 같은 이벤트를 사용하는 일도, 플레이어 마다 다른 이벤트를 어플리케이션으로 지정하는 일도 가능하다. 이벤트의 생성, 파기는, 어플리케이션의 역할이다. 상세한 것에 대하여는, 「동기」를 참조할것.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

DPNAME ,DPMSG_CREATEPLAYERORGROUP ,IDirectPlay4::DestroyPlayer ,IDirectPlay4::EnumPlayers ,IDirectPlay4::Receive ,IDirectPlay4::Send ,IDirectPlay4::SetPlayerData ,IDirectPlay4::SetPlayerName ,IDirectPlay4::GetPlayerFlags


IDirectPlay4::DeleteGroupFromGroup

IDirectPlay4::DeleteGroupFromGroup 메소드는,IDirectPlay4::AddGroupToGroup 메소드에 의해 추가된그룹에의 쇼트 컷을 그룹으로부터 삭제한다. 쇼트 컷을 삭제해도, 그룹은 파기되지 않는다.

HRESULT DeleteGroupFromGroup(
  DPID idParentGroup,
  DPID idGroup
);

파라미터

idParentGroup
삭제하는 쇼트 컷이 포함되어 있는 그룹의 ID. 유효한 임의의 그룹의 ID 를 지정 가능.
idGroup
삭제하는 그룹의 ID. 유효한 임의의 그룹의 ID 를 지정 가능.

반환값

처리가 성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러 메세지의 어느쪽이든을 돌려준다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP

주의

이 변경을 플레이어에게 알리기 위해서(때문에),DPMSG_DELETEGROUPFROMGROUP 시스템 메세지가 생성된다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::AddGroupToGroup ,DPMSG_DELETEGROUPFROMGROUP


IDirectPlay4::DeletePlayerFromGroup

IDirectPlay4::DeletePlayerFromGroup 메소드는, 플레이어를그룹으로부터 삭제한다.

HRESULT DeletePlayerFromGroup(
  DPID idGroup,
  DPID idPlayer
);

파라미터

idGroup
조정하는 그룹의 그룹 ID.
idPlayer
그룹으로부터 삭제하는 플레이어의 플레이어 ID.

반환값

처리가 성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러 메세지의 어느쪽이든을 돌려준다.

DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER

주의

여기서의 변경을 다른 플레이어에게 알리기 위해서(때문에),DPMSG_DELETEPLAYERFROMGROUP 시스템 메세지가 생성된다. 시스템 메세지의 리스트에 대해서는, 「시스템 메세지의 사용」을 참조할것.

다른 컴퓨터로 생성 된 그룹에서도, 플레이어는 임의의 플레이어를 그 그룹으로부터 삭제할 수 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::AddPlayerToGroup ,DPMSG_DELETEPLAYERFROMGROUP


IDirectPlay4::DestroyGroup

IDirectPlay4::DestroyGroup 메소드는, 그룹을 세션으로부터 삭제한다. 이 그룹에 속하는 ID 는, 현재 세션에서는 재이용되지 않는다.

HRESULT DestroyGroup(
  DPID idGroup
);

파라미터

idGroup
게임으로부터 삭제되는 그룹의 ID.

반환값

처리가 성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러 메세지의 어느쪽이든을 돌려준다.

DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

주의

그룹을 삭제하기 전에, 그 그룹을 비울 필요는 없다. 그 그룹에 속하는 개별의 플레이어는, 파기되지 않는다. 이 메소드는, 그룹의 플레이어 마다 DPMSG_DELETEPLAYERFROMGROUP 시스템 메세지를 생성 하고 나서,DPMSG_DESTROYPLAYERORGROUP 시스템 메세지를 생성 한다. 시스템 메세지의 리스트에 대해서는, 「시스템 메세지의 사용」을 참조할것.

어플리케이션에서는, 로컬에 생성 된 그룹이 아니어도, 임의의 그룹을 파기할 수 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::CreateGroup ,DPMSG_DESTROYPLAYERORGROUP


IDirectPlay4::DestroyPlayer

IDirectPlay4::DestroyPlayer 메소드는, 로컬 플레이어를 세션으로부터 삭제해, 그 플레이어 앞의 보류 상태의 메세지를 메시지 큐로부터 삭제해, 플레이어가 속하는 모든 그룹으로부터 플레이어를 삭제한다. 이 플레이어 ID 는, 현재 세션으로 재이용되지 않는다.

일반적으로는, 플레이어를 생성 한 어플리케이션만이 그 플레이어를 파기할 수 있다. 그러나, 세션의 호스트도, 플레이어를 파기할 수 있다.

HRESULT DestroyPlayer(
  DPID idPlayer
);

파라미터

idPlayer
로컬에 소유되고 있는 플레이어로, 세션으로부터 삭제하는 플레이어의 플레이어 ID. 세션의 호스트로부터 DestroyPlayer 를 호출하는 경우는, 이 ID 는 로컬 플레이어의 ID 에서도, 리모트 플레이어의 ID 에서도 상관없다.

반환값

처리가 성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러 메세지의 어느쪽이든을 돌려준다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER
DPERR_UNAVAILABLE

주의

이 메소드는, 플레이어가 속하는 그룹 마다 DPMSG_DELETEPLAYERFROMGROUP 시스템 메세지를 생성 하고 나서,DPMSG_DESTROYPLAYERORGROUP 시스템 메세지를 생성 한다.

플레이어의 송신 큐에 보류 상태의 비동기 메세지가 있는 경우, 그 플레이어는 파기할 수 없다. 모든 메세지를 완료하는지, 또는 취소할 필요가 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::CreatePlayer ,DPMSG_DESTROYPLAYERORGROUP


IDirectPlay4::EnumConnections

IDirectPlay4::EnumConnections 메소드는, 어플리케이션으로 사용 가능한 등록이 끝난 서비스 프로바이더와 로비 프로바이더를 모두 열거한다. 유저는 이러한 안으로부터, 서비스 프로바이더와 로비 프로바이더를 선택한다. 유저가 선택한 접속은,IDirectPlay4::InitializeConnection 메소드에게 건네진다.

HRESULT EnumConnections(
  LPCGUID lpguidApplication,
  LPDPENUMCONNECTIONSCALLBACK lpEnumCallback,
  LPVOID lpContext,
  DWORD dwFlags
);

파라미터

lpguidApplication
어플리케이션의 글로벌 유니크 식별자 (GUID)에의 포인터. 어플리케이션으로 사용 가능한 등록이 끝난 서비스 프로바이더와 로비 프로바이더만이 돌려주어진다. NULL 포인터를 설정했을 경우, 어플리케이션 GUID 에 관계없이, 모든 접속이 열거된다.
lpEnumCallback
사용 가능한 접속 마다 불려 가는, 유저 지정의 EnumConnectionsCallback 함수에의 포인터.
lpContext
콜백 함수에 건네받는, 유저 정의의 문맥에의 포인터.
dwFlags
열거되는 접속의 타입을 지정하는 플래그. 디폴트 (dwFlags = 0)에서는, DPCONNECTION_DIRECTPLAY 와 같은 결과가 된다.

다음에, 가능한 값을 나타낸다.

DPCONNECTION_DIRECTPLAY
어플리케이션 세션으로 통신하는 DirectPlay 서비스 프로바이더만을 열거한다.
DPCONNECTION_DIRECTPLAYLOBBY
로비 서버와 통신하는 DirectPlay 로비 프로바이더만을 열거한다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS

주의

이 메소드는,DirectPlayEnumerate 함수의 대신이 된다. DirectPlayEnumerate 함수는 여전히 기능하지만, 등록이 끝난 서비스 프로바이더 밖에 돌려주지 않는다.

서비스 프로바이더와 로비 프로바이더가 돌려주어지는 순서는,EnumConnections 를 호출한 순서와 같다라고는 한정되지 않는다.

열거된 접속의 모든 것을 사용할 수 있는 것은 아니다. 예를 들어, 이 메소드는 유저가 모뎀을 인스톨 하고 있지 않아도 모뎀 서비스 프로바이더를 돌려준다. 어플리케이션에서는, 접속 마다 IDirectPlay4::InitializeConnection 메소드를 호출해, 에러 코드를 조사해 서비스 프로바이더가 사용 가능한지 어떤지를 판단할 수가 있다.

IDirectPlay4A(ANSI) 인터페이스로 이 메소드를 호출하면, 반드시 적절히 로컬라이즈 된 1 바이트 문자의 캐릭터 라인이 돌려주어진다. 멀티 바이트 문자의 캐릭터 라인은 사용되지 않기 때문에, 그것을 지원 하고 있지 않는 폰트를 사용해도 캐릭터 라인을 표시할 경우에 문제가 발생하지 않는다. IDirectPlay4(Unicode) 인터페이스로 이 메소드를 호출하면, 로컬라이즈 된 와이드 문자의 기술이 돌려주어진다.

서비스 프로바이더안에는, 그것들을 Private로서 등록할 수 있는 것도 있다. 이러한 서비스 프로바이더는, 이 메소드를 사용해도 열거되지 않는다. Private의 서비스 프로바이더를 사용하려면 , 로비에 의해 어플리케이션을 기동하는지, 또는 DirectPlay 주소를 생성 해 그것을 InitializeConnection 에 건네주어, Private의 서비스 프로바이더를 그 GUID 에 의해 명시적으로 참조할 필요가 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::InitializeConnection ,EnumConnectionsCallback


IDirectPlay4::EnumGroupPlayers

IDirectPlay4::EnumGroupPlayers 메소드는, 현재 열려 있는 세션의 특정의그룹에 속하고 있는 플레이어를 열거한다. 열려 있는 세션이 없는 경우는, DPENUMPLAYERS_SESSION 플래그와 세션의 guidInstance 를 지정 하면, 리모트 세션의 플레이어를 열거할 수 있다. 패스워드로 보호된 리모트 세션은 열거할 수 없다.

어플리케이션으로 이행 하는 콜백 함수에의 포인터는 반드시 지정한다. DirectPlay 는, 그룹 중(안)에서 dwFlags 로 지정된 조건에 일치하는 플레이어 마다 그 콜백 함수를 호출한다.

접속하고 있지 않는 로비 세션으로 EnumGroupPlayers 를 사용할 수 없다.

HRESULT EnumGroupPlayers(
  DPID idGroup,
  LPGUID lpguidInstance,
  LPDPENUMPLAYERSCALLBACK2 lpEnumPlayersCallback2,
  LPVOID lpContext,
  DWORD dwFlags
);

파라미터

idGroup
열거하는 플레이어의 그룹의 ID.
lpguidInstance
열거하는 세션을 식별하기 위한 글로벌 유니크 식별자 (GUID)에의 포인터. 이 파라미터는, DPENUMPLAYERS_SESSION 플래그가 지정되어 있지 않은 경우는 무시된다. GUID 는,IDirectPlay4::EnumSessions 에 의해 열거되는 세션의 언젠가가 아니면 안된다.
lpEnumPlayersCallback2
그룹내에서 dwFlags 로 지정된 조건에 일치하는 모든 플레이어에 대해서 호출하는 EnumPlayersCallback2 함수에의 포인터.
lpContext
각 열거 콜백 함수에게 건네지는, 어플리케이션 정의의 문맥에의 포인터.
dwFlags
열거 방법을 지정하는 플래그. 디폴트 (dwFlags = 0)에서는, 현재 액티브한 세션의 그룹의 플레이어가 열거된다. 지정하고 싶은 플래그에 대해서 논리 연산자의 OR 를 실행한다. 지정한 플래그의 조건을 모두 채우는 플레이어만이 열거된다. 예를 들어, (DPENUMPLAYERS_LOCAL | DPENUMPLAYERS_SPECTATOR)라고 지정 하면, 그룹 중(안)에서 로컬로, 게다가 관객 플레이어인 플레이어만이 열거된다. (DPENUMPLAYERS_LOCAL | DPENUMPLAYERS_REMOTE)(와)과 지정 하면, 플레이어가 동시에 로컬 또한 리모트가 되는 것은 있을 수 없기 때문에, 플레이어는 전혀 열거되지 않는다.

다음의 값의 언젠가 또는 몇개인가를 지정할 수 있다.

DPENUMPLAYERS_LOCAL
이 DirectPlay 오브젝트에 의해 로컬에 생성 된 플레이어를 열거한다.
DPENUMPLAYERS_OWNER
이 그룹의 소유자인 플레이어만을 열거한다.
DPENUMPLAYERS_REMOTE
리모트의 DirectPlay 오브젝트에 의해 생성 된 플레이어를 열거한다.
DPENUMPLAYERS_SERVERPLAYER
서버 플레이어를 열거한다.
DPENUMPLAYERS_SESSION
lpguidInstance 에 의해 지정된 세션의 플레이어를 열거한다. 이 플래그는, 현재 열려 있는 세션이 없는 경우에게만 사용할 수 있다. 이 플래그는,로비 세션에서는 사용할 수 없다.
DPENUMPLAYERS_SPECTATOR
관객 플레이어인 플레이어를 열거한다.

반환값

처리가 성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러 메세지의 어느쪽이든을 돌려준다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDPARAMS
DPERR_INVALIDGROUP
DPERR_NOSESSIONS
DPERR_UNAVAILABLE

세션이 유저에 의해 접속되어 있지 않은 로비 세션인 경우는, DPERR_ACCESSDENIED 를 돌려준다. 콜백이 무효인 경우,guidInstance 가 무효인 경우, 또는 무효인 플래그가 지정되었을 경우는, DPERR_INVALIDPARAMS 를 돌려준다. 액티브한 세션이 없는 경우는, DPERR_NOSESSIONS 를 돌려준다. 세션을 열거할 수 없었던 경우는, DPERR_UNAVAILABLE 를 돌려준다.

주의

디폴트에서는, 이 메소드는 현재 세션의 모든 플레이어를 열거한다. DPENUMPLAYERS_SESSION 플래그는, 세션 인스턴스의 GUID 와 함께 사용해, 세션의호스트에게 그 열거용 리스트를 제공하도록(듯이) 요구할 수 있다. 이 메소드로 DPENUMPLAYERS_SESSION 플래그를 사용할때는,IDirectPlay4::EnumSessions 메소드가 불려 간 다음에, 또 IDirectPlay4::Close 메소드나 IDirectPlay4::Open 메소드를 호출하기 전에 실시할 필요가 있다.

그룹의 소유자인 플레이어를 나타내기 위해서(때문에), 콜백 함수로 DPENUMPLAYERS_OWNER 플래그가 돌려주어진다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::CreatePlayer ,IDirectPlay4::DestroyPlayer ,IDirectPlay4::AddPlayerToGroup ,IDirectPlay4::DeletePlayerFromGroup


IDirectPlay4::EnumGroups

IDirectPlay4::EnumGroups 메소드는, 현재 세션의 최상정도 그룹을 모두 열거한다. 최상정도 그룹이란,IDirectPlay4::CreateGroup 메소드에 의해 생성 된 그룹이다. 열려 있는 세션이 없는 경우는, DPENUMGROUPS_session 플래그와 세션의 guidInstance 를 지정 하면, 리모트 세션의 그룹을 열거할 수 있다. 패스워드로 보호된 리모트 세션은 열거할 수 없다.

어플리케이션으로 이행 하는 콜백 함수에의 포인터는 반드시 지정한다. DirectPlay 는, 세션내에서 dwFlags 로 지정된 조건에 일치하는 그룹 마다 그 콜백 함수를 호출한다.

접속하고 있지 않는 로비 세션으로 EnumGroups 를 사용할 수 없다.

HRESULT EnumGroups(
  LPGUID lpguidInstance,
  LPDPENUMPLAYERSCALLBACK2 lpEnumPlayersCallback2,
  LPVOID lpContext,
  DWORD dwFlags
);

파라미터

lpguidInstance
현재 열려 있는 세션내의 그룹을 열거하려면 , 이 파라미터에 NULL 를 지정한다. 열려 있는 세션이 없는 경우는, 이 파라미터에, 열거하는 세션을 식별하기 위한 글로벌 유니크 식별자 (GUID)에의 포인터를 지정할 수 있다. 이 GUID 는,IDirectPlay4::EnumSessions 에 의해 열거되는 세션의 언젠가가 아니면 안된다. 이 파라미터는, DPENUMGROUPS_SESSION 플래그가 지정되어 있지 않은 경우는 무시된다.
lpEnumPlayersCallback2
세션내에서 dwFlags 로 지정된 조건에 일치하는 모든 그룹에 대해서 호출하는 EnumPlayersCallback2 함수에의 포인터.
lpContext
각 열거 콜백 함수에게 건네지는, 어플리케이션 정의의 문맥에의 포인터.
dwFlags
열거 방법을 지정하는 플래그. 디폴트 (dwFlags = 0)에서는, 현재 액티브한 세션의 그룹이 모두 열거된다. 지정하고 싶은 플래그에 대해서 논리 연산자의 OR 를 실행한다. 지정한 플래그의 조건을 모두 채우는 그룹만이 열거된다. 예를 들어, (DPENUMGROUPS_LOCAL | DPENUMGROUPS_STAGINGAREA)라고 지정 하면, 로컬로, 게다가 staging 영역인 그룹만이 열거된다. (DPENUMGROUPS_LOCAL | DPENUMGROUPS_REMOTE)(와)과 지정 하면, 그룹이 동시에 로컬 또한 리모트가 되는 것은 있을 수 없기 때문에, 그룹은 전혀 열거되지 않는다.

다음의 값의 언젠가 또는 몇개인가를 지정할 수 있다.

DPENUMGROUPS_ALL
이 세션내의 모든 그룹을 열거한다.
DPENUMGROUPS_HIDDEN
현재 사용 가능한 은폐 그룹만을 열거한다.
DPENUMGROUPS_LOCAL
이 DirectPlay 오브젝트에 의해 로컬에 생성 된 그룹을 열거한다.
DPENUMGROUPS_REMOTE
리모트의 DirectPlay 오브젝트에 의해 생성 된 그룹을 열거한다.
DPENUMGROUPS_SESSION
lpguidInstance 파라미터에 의해 지정된 세션으로 열거를 실행한다. 이 플래그는, 현재 액티브한 세션이 없는 경우에게만 사용할 수 있다. 이 플래그는,로비 세션에서는 사용할 수 없다.
DPENUMGROUPS_STAGINGAREA
staging 영역인 그룹을 열거한다 (staging 영역은, 새로운 세션을 기동하기 위해서 플레이어를 정렬할 경우에 사용한다).

반환값

처리가 성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러 메세지의 어느쪽이든을 돌려준다.

DPERR_CONNECTIONLOST
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS
DPERR_UNAVAILABLE

콜백이 무효인 경우,guidInstance 가 무효인 경우, 또는 무효인 플래그가 지정되었을 경우는, DPERR_INVALIDPARAMS 를 돌려준다. 열려 있는 세션이 없는 경우는, DPERR_NOSESSIONS 를 돌려준다. 리모트 세션을 열거할 수 없었던 경우는, DPERR_UNAVAILABLE 를 돌려준다.

주의

그룹내의 서브 그룹을 열거하려면 ,IDirectPlay4::EnumGroupsInGroup 를 사용하는 것.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

EnumPlayersCallback2 ,IDirectPlay4::CreateGroup ,IDirectPlay4::DestroyGroup ,IDirectPlay4::EnumSessions


IDirectPlay4::EnumGroupsInGroup

IDirectPlay4::EnumGroupsInGroup 메소드는, 다른그룹에 포함되는 모든 그룹과 그룹에의 쇼트 컷을 열거한다. 그룹을 다른 그룹내에 배치하려면 ,IDirectPlay4::CreateGroupInGroup 메소드를 사용해 그룹을 생성 하는지, 또는IDirectPlay4::AddGroupToGroup 메소드에 의해 그룹을 다른 그룹에 추가한다. 이 메소드는, 재귀적이지 않다.

접속하고 있지 않는 로비 세션으로 EnumGroupsInGroup 를 사용할 수 없다.

HRESULT EnumGroupsInGroup(
  DPID idGroup,
  LPGUID lpguidInstance,
  LPDPENUMPLAYERSCALLBACK2 lpEnumCallback,
  LPVOID lpContext,
  DWORD dwFlags
);

파라미터

idGroup
열거하는 서브 그룹이 포함되는 그룹의 ID.
lpguidInstance
열거하는 세션을 식별하기 위한 글로벌 유니크 식별자 (GUID)에의 포인터. 이 파라미터는, DPENUMPLAYERS_SESSION 플래그가 지정되어 있지 않은 경우는 무시된다. GUID 는,IDirectPlay4::EnumSessions 메소드에 의해 열거되는 세션의 언젠가가 아니면 안된다.
lpEnumCallback
그룹내에서 dwFlags 로 지정된 조건에 일치하는 모든 그룹에 대해서 호출하는 EnumPlayersCallback2 함수에의 포인터.
lpContext
각 열거 콜백 함수에게 건네지는, 어플리케이션 정의의 문맥에의 포인터.
dwFlags
열거 방법을 지정한 플래그. 디폴트 (dwFlags = 0)에서는, 현재 액티브한 세션의 그룹이 모두 열거된다. 지정하고 싶은 플래그에 대해서 논리 연산자의 OR 를 실행한다. 지정한 플래그의 조건을 모두 채우는 그룹만이 열거된다. 예를 들어, (DPENUMGROUPS_LOCAL | DPENUMGROUPS_STAGINGAREA)라고 지정 하면, 로컬로, 게다가 staging 영역인 그룹만이 열거된다. (DPENUMGROUPS_LOCAL | DPENUMGROUPS_REMOTE)(와)과 지정 하면, 그룹이 동시에 로컬 또한 리모트가 되는 것은 있을 수 없기 때문에, 그룹은 전혀 열거되지 않는다.

다음의 값의 언젠가 또는 몇개인가를 지정할 수 있다.

DPENUMGROUPS_ALL
그룹내의 모든 그룹을 열거한다.
DPENUMGROUPS_HIDDEN
그룹내에서 현재 사용 가능한 은폐 그룹만을 열거한다.
DPENUMGROUPS_LOCAL
이 DirectPlay 오브젝트에 의해 로컬에 생성 된 그룹내의 그룹을 열거한다.
DPENUMGROUPS_REMOTE
리모트의 DirectPlay 오브젝트에 의해 생성 된 그룹내의 그룹을 열거한다.
DPENUMGROUPS_SESSION
lpguidInstance 파라미터에 의해 지정된 세션으로 열거를 실행한다. 이 플래그는, 현재 액티브한 세션이 없는 경우에게만 사용할 수 있다. 이 플래그는, 로비 세션에서는 사용할 수 없다.
DPENUMGROUPS_SHORTCUT
IDirectPlay4::AddGroupToGroup 메소드를 사용해 그룹에 추가된 쇼트 컷인 그룹을 열거한다 (쇼트 컷이란, 다른 그룹에의 링크이다).
DPENUMGROUPS_STAGINGAREA
staging 영역인 그룹내의 그룹을 열거한다 (staging 영역은, 새로운 세션을 기동하기 위해서 플레이어를 정렬할 경우에 사용한다).

반환값

처리가 성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러 메세지의 어느쪽이든을 돌려준다.

DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS
DPERR_UNSUPPORTED

콜백이 무효인 경우, 또는 무효인 guidInstance 가 지정되었을 경우는, DPERR_INVALIDPARAMS 를 돌려준다. 액티브한 세션이 없는 경우는, DPERR_NOSESSIONS 를 돌려준다. 세션을 열거할 수 없었던 경우는, DPERR_UNSUPPORTED 를 돌려준다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::CreateGroupInGroup ,IDirectPlay4::DestroyGroup ,IDirectPlay4::AddGroupToGroup ,IDirectPlay4::DeleteGroupFromGroup


IDirectPlay4::EnumPlayers

IDirectPlay4::EnumPlayers 메소드는, 현재 열려 있는 세션의 플레이어를 열거한다. 열려 있는 세션이 없는 경우는, DPENUMPLAYERS_SESSION 플래그와 세션의 guidInstance 를 지정 하면, 리모트 세션의 플레이어를 열거할 수 있다. 패스워드로 보호된 리모트 세션은 열거할 수 없다.

어플리케이션으로 이행 하는 콜백 함수에의 포인터는 반드시 지정한다. DirectPlay 는, 세션 중(안)에서 dwFlags 로 지정된 조건에 일치하는 플레이어 마다 그 콜백 함수를 호출한다.

이 메소드는,로비 세션내에서는 반드시 DPERR_ACCESSDENIED 를 돌려준다.

HRESULT EnumPlayers(
  LPGUID lpguidInstance,
  LPDPENUMPLAYERSCALLBACK2 lpEnumPlayersCallback2,
  LPVOID lpContext,
  DWORD dwFlags
);

파라미터

lpguidInstance
현재 열려 있는 세션내의 플레이어를 열거하려면 , 이 파라미터에 NULL 를 지정한다. 열려 있는 세션이 없는 경우는, 이 파라미터에, 열거하는 세션을 식별하기 위한 GUID 에의 포인터를 지정할 수 있다. 이 GUID 는,IDirectPlay4::EnumSessions 에 의해 열거되는 세션의 언젠가가 아니면 안된다. 이 파라미터는, DPENUMPLAYERS_SESSION 플래그가 지정되어 있지 않은 경우는 무시된다.
lpEnumPlayersCallback2
세션내에서 dwFlags 로 지정된 조건에 일치하는 모든 플레이어에 대해서 호출하는 EnumPlayersCallback2 함수에의 포인터.
lpContext
각 열거 콜백 함수에게 건네지는, 어플리케이션 정의의 문맥에의 포인터.
dwFlags
열거 방법을 지정하는 플래그. 디폴트 (dwFlags = 0)에서는, 현재 액티브한 세션의 플레이어가 모두 열거된다. 지정하고 싶은 플래그에 대해서 논리 연산자의 OR 를 실행한다. 지정한 플래그의 조건을 모두 채우는 플레이어만이 열거된다. 예를 들어, (DPENUMPLAYERS_LOCAL | DPENUMPLAYERS_SPECTATOR)라고 지정 하면, 그룹 중(안)에서 로컬로, 게다가 관객 플레이어인 플레이어만이 열거된다. (DPENUMPLAYERS_LOCAL | DPENUMPLAYERS_REMOTE)(와)과 지정 하면, 플레이어가 동시에 로컬 또한 리모트가 되는 것은 있을 수 없기 때문에, 플레이어는 전혀 열거되지 않는다.

다음의 값의 언젠가 또는 몇개인가를 지정할 수 있다.

DPENUMPLAYERS_ALL
이 세션내의 모든 플레이어를 열거한다.
DPENUMPLAYERS_GROUP
플레이어의 열거에 그룹을 포함한다.
DPENUMPLAYERS_LOCAL
이 DirectPlay 오브젝트에 의해 로컬에 생성 된 플레이어를 열거한다.
DPENUMPLAYERS_REMOTE
리모트의 DirectPlay 오브젝트에 의해 생성 된 플레이어를 열거한다.
DPENUMPLAYERS_SERVERPLAYER
서버 플레이어를 열거한다.
DPENUMPLAYERS_SESSION
lpguidInstance 에 의해 지정된 세션의 플레이어를 열거한다. 이 플래그는, 현재 열려 있는 세션이 없는 경우에게만 사용할 수 있다.
DPENUMPLAYERS_SPECTATOR
관객 플레이어인 플레이어를 열거한다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_CONNECTIONLOST
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS
DPERR_UNAVAILABLE

콜백이 무효인 경우,guidInstance 가 무효인 경우, 또는 무효인 플래그가 지정되었을 경우는, DPERR_INVALIDPARAMS 를 돌려준다. 열려 있는 세션이 없는 경우는, DPERR_NOSESSIONS 를 돌려준다. 리모트 세션을 열거할 수 없었던 경우는, DPERR_UNAVAILABLE 를 돌려준다.

주의

이 메소드는, 디폴트에서는, 현재 열려 있는 세션의 플레이어를 열거한다. DPENUMPLAYERS_GROUP 플래그를 사용 하면, 그룹도 열거에 포함할 수가 있다. DPENUMPLAYERS_SESSION 플래그는, 세션 인스턴스의 GUID 와 함께 사용해, 세션의 호스트에게 그 열거용 리스트를 제공하도록(듯이) 요구할 수 있다. 이 메소드는,IDirectPlay4::EnumSessions 열거내로부터는 호출할 수가 없다. 또, 이 메소드로 DPENUMPLAYERS_SESSION 플래그를 사용할때는,IDirectPlay4::EnumSessions 메소드가 불려 간 다음에, 또 IDirectPlay4::Close 메소드나 IDirectPlay4::Open 메소드를 호출하기 전에 실시할 필요가 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::CreatePlayer ,IDirectPlay4::DestroyPlayer ,IDirectPlay4::EnumSessions


IDirectPlay4::EnumSessions

IDirectPlay4::EnumSessions 메소드는, 특정의 어플리케이션의 액티브한 세션과 특정의 어플리케이션을 제공하고 있는 액티브한 로비 세션의 모든 것을 열거한다. 이 메소드는,DirectPlayCreate 메소드 또는 IDirectPlay4::InitializeConnection 메소드의 어느 쪽인가에보다 오브젝트를 생성 및 초기화한 후에 호출할 수가 있다.

이 메소드는, 세션이 아직 열려 있는 동안에 불려 가면(자), 에러를 돌려준다.

HRESULT EnumSessions(
  LPDPSESSIONDESC2 lpsd,
  DWORD dwTimeout,
  LPDPENUMSESSIONSCALLBACK2 lpEnumSessionsCallback2,
  LPVOID lpContext,
  DWORD dwFlags
);

파라미터

lpsd
열거하는 세션을 기술한 DPSESSIONDESC2 구조체에의 포인터. 이 구조체로 설정되어 있는 조건을 채우는 세션만이 열거된다. guidApplication 멤버에, 그것이 인식되고 있을 때 목적의 어플리케이션의 글로벌 유니크 식별자 (GUID)를 설정하거나 또는 GUID_NULL 를 설정해 모든 세션을 취득할 수가 있다. lpszPassword 멤버는, Private 세션을 희망하는 경우에게만 필요하다. guidApplication 와 lpszPassword 이외의 데이터 멤버는 모두 무시된다.
dwTimeout
동기의 경우, DirectPlay 가 열거 요구에 대한 응답을 기다리고 있는 시간 (열거와 열거동안의 시간은 아니다)(밀리 세컨드 단위). 이 타임 아웃값이 경과하고 나서 응답을 수신해도, 그것들은 모두 무시된다. 어플리케이션은, 타임 아웃값을 경과할 때까지 블록 된다.

비동기의 경우, 이 값은, 내부 세션 리스트를 갱신하기 위해서 DirectPlay 에 의해 열거 요구가 브로드캐스트 되는 간격 (밀리 세컨드 단위)을 나타낸다.

타임 아웃값에 0 을 설정 하면,서비스 프로바이더와 접속 타입에 적합한 디폴트의 타임 아웃값이 사용된다. 이 값에 0 을 설정하는 것을 추천 한다. 어플리케이션에서는,IDirectPlay4::GetCaps 메소드를 호출해 DPCAPS 구조체의 dwTimeout 데이터 멤버를 조사하는 것으로, 이 타임 아웃값을 판정할 수 있다.

lpEnumSessionsCallback2
DirectPlay 세션의 응답 마다 불려 가는, 어플리케이션에 의해 지정된 EnumSessionsCallback2 함수에의 포인터.
lpContext
각 열거 콜백 함수에 건네받는, 유저 정의의 문맥에의 포인터.
dwFlags
디폴트는 0 이며, DPENUMSESSIONS_AVAILABLE 와 등가이다. DPENUMSESSIONS_ALL 또는 DPENUMSESSIONS_PASSWORDREQUIRED 를 사용해 열거 하면 와, 참가할 수 없는 세션이나, 유저가 경고하거나 패스워드 입력을 요구할 수 있도록(듯이) 패스워드로 보호되고 있는 세션을, 어플리케이션으로 인식하는 것이 중요하다.
DPENUMSESSIONS_ALL
세션이 새로운 플레이어를 받아들이고 있는지 어떤지에 관계없이, 모든 액티브한 세션을 열거한다. 플레이어 제한에 이른 세션, 새로운 플레이어가 무효가 된 세션, 또는 참가가 무효가 된 세션을 열거한다.

패스워드에 의해 보호된 세션은, DPENUMSESSIONS_PASSWORDREQUIRED 플래그도 지정되어 있지 않으면 열거되지 않는다.

DPENUMSESSIONS_ALL 가 지정되어 있지 않은 경우는, DPENUMSESSIONS_AVAILABLE 이다고 보여진다.

DPENUMSESSIONS_ASYNC
세션 캐쉬의 현재 세션을 모두 열거해, 즉석에서 돌아온다. 비동기 열거 프로세스가 아직 기동되어 있지 않은 경우는, 그것을 기동한다. DPENUMSESSIONS_STOPASYNC 플래그를 지정해 EnumSessions 를 호출하는지, 또는 Open 나 Release 를 호출해 취소할 때까지, 세션 리스트는 갱신계속 된다.

이 플래그가 지정되어 있지 않은 경우, 열거는 동기를 잡으면서 실행된다.

DPENUMSESSIONS_AVAILABLE
새로운 플레이어의 참가를 받아들이고 있는 세션을 모두 열거한다. 플레이어의 최대수에 이르고 있는 세션, 새로운 플레이어가 무효가 된 세션, 또는 참가가 무효가 된 세션은 열거하지 않는다.

패스워드에 의해 보호된 세션은,DPENUMSESSIONS_PASSWORDREQUIRED 플래그도 지정되어 있지 않으면 열거되지 않는다.

DPENUMSESSIONS_PASSWORDREQUIRED
DPENUMSESSIONS_AVAILABLE 플래그 또는 DPENUMSESSIONS_ALL 플래그의 어느쪽이든과 함께 사용 하면, 패스워드에 의해 보호되어 있지 않은 세션에 가세해, 패스워드에 의해 보호되고 있는 세션도 열거된다.

이 플래그를 지정하지 않는 경우는, 패스워드에 의해 보호되고 있는 세션은 돌려주어지지 않다.

DPENUMSESSIONS_RETURNSTATUS
이 플래그를 지정했을 경우는, 열거시에 접속의 진행 상황을 나타내는 다이알로그 박스가 표시되지 않는다. 곧바로 접속할 수 없는 경우, 메소드는 DPERR_CONNECTING 에러를 돌려준다. 어플리케이션은, 정상 종료를 나타내는 DP_OK 가 돌려주어지는지, 또는 에러를 나타내는 그 다른 에러 코드가 돌려주어질 때까지 EnumSessions 를 계속 호출할 필요가 있다.
DPENUMSESSIONS_STOPASYNC
세션 캐쉬의 현재 세션을 모두 열거해, 비동기 열거 프로세스를 취소한다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_CONNECTING
DPERR_CONNECTIONLOST
DPERR_EXCEPTION
DPERR_GENERIC
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOCONNECTION
DPERR_UNINITIALIZED
DPERR_USERCANCEL

세션이 이미 열려 있는 경우는, DPERR_GENERIC 를 돌려준다. DirectPlay 오브젝트가 초기화되어 있지 않은 경우는, DPERR_UNINITIALIZED 를 돌려준다. 유저가 열거 프로세스를 취소했을 경우 (일반적으로서비스 프로바이더의 다이알로그 박스를 취소하는 것으로)는 DPERR_USERCANCEL 를 돌려주어, 유저가 TCP/IP 서비스 프로바이더의 다이알로그 박스에 IP 주소로 변환할 수 없는 컴퓨터명을 입력했을 경우는 DPERR_INVALIDPARAMS 를 돌려준다. 메소드가 네트워크에 접속중의 경우는, DPERR_CONNECTING 를 돌려준다.

주의

EnumSessions 는, 서비스 프로바이더가 네트워크 위에의 호스트를 검색해, 그것들을 열거 요구에 송신하도록(듯이) 요구하는 것으로 기능한다. 수신한 응답에 의해, 열거되는 세션이 모두 갖추어진다.

EnumSessions 는, 동기 (디폴트) 또는 비동기에게 호출할 수가 있다. 동기를 잡으면서 호출했을 경우, DirectPlay 는 내부 세션 캐쉬를 클리어 해, 열거 요구를 송신해, 지정된 타임 아웃이 될 때까지 응답을 수집한다. 각 세션은, 콜백 함수에 의해 어플리케이션에 돌려주어진다. 어플리케이션은, 모든 세션이 콜백 함수로부터 돌려주어질 때까지 블록 된다.

비동기에게 불려 갔을 경우 (DPENUMSESSIONS_ASYNC ), 세션 캐쉬의 현재 세션 (존재하는 경우)은 모두 콜백 함수에 의해 어플리케이션에 돌려주어져 또 메소드는 돌아온다. DirectPlay 는, 타임 아웃 파라미터를 지정해 열거 요구를 자동적으로 송신해, 응답이 돌려주어지는 것을 기다린다. 다음과 같이, 각 응답을 사용해 세션 캐쉬를 갱신한다.

  • 캐쉬내에 이미 존재하는 세션을 갱신한다.
  • 설정된 기간에 갱신되지 않고, 타임 아웃 시간에 이른 세션을 삭제한다.
  • 새로운 세션을 추가한다.

어플리케이션은, 실효한 세션을 모두 삭제해, 새로운 세션을 추가해, 또 세션을 갱신한 최신의 세션 리스트를 취득하기 위해서,EnumSessions 를 (DPENUMSESSIONS_ASYNC 플래그를 설정해) 재차 호출할 필요가 있다. 그 이후는 EnumSessions 를 호출해도 열거 요구는 생성되지 않는다. DPENUMSESSIONS_STOPASYNC 플래그를 설정해 EnumSessions 를 호출해, 프로세스를 취소하는지,IDirectPlay4::Open 메소드를 사용해 세션을 여는지, 또는 DirectPlay 오브젝트를 릴리즈 할 때까지, 열거 요구는 DirectPlay 에 의해 정기적으로 생성 된다.

비동기에게 열거하는 세션의 기술을 변경하려면 , 비동기 열거를 정지해, 그것을 재부팅 할 필요가 있다. 예를 들어, 패스워드를 지정하지 않으면 열거를 기동할 수 없기 때문에, 나중에 비동기 호출로 패스워드를 추가해, 그것에 의해 그 패스워드를 사용해 Private 세션의 열거를 시작 한다. 반대로, 올바른 패스워드를 지정하고 나서, 부정한 패스워드에 변경해도, 그 세션은 열거된다. 다만, DPENUMSESSIONS_STOPASYNC 플래그를 지정해 EnumSessions 를 호출해, 패스워드를 지정 하면, Private 세션이 열거된다.

사용 가능한 세션의 열거가 완료하면(자), 어플리케이션은 IDirectPlay4::Open 메소드를 사용해 세션의 어느 쪽인가에 참가할 수 있다. 여는 것이 가능한 것은, 세션 캐쉬의 세션 뿐이다. 어플리케이션은, 마지막에 EnumSessions 를 호출해 에러가 돌려주어지고 나서, 실효한 세션을 열 수도 있다.

인증은, 보증 서버로 세션을 열거할 경우에는 실행되지 않는다. 열거 조건을 채우는 세션이 모두 돌려주어진다. 어플리케이션으로 IDirectPlay4::Open 또는 IDirectPlay4::SecureOpen 를 사용해 이러한 세션의 어느쪽이든을 열려고 하면, 인증을 한다.

어플리케이션이 로비에 의해 기동된 것은 아닌 경우, 네트워크로 열거를 실행하기 위한 정보 (전화번호나 IP 주소등)가 IDirectPlay4::InitializeConnection 에게 건네지지 않으면,서비스 프로바이더는 다이알로그 박스를 표시해 유저에게 그러한 정보를 입력하도록(듯이) 요구할 수 있다. 서비스 프로바이더가 브로드캐스트 열거를 실행할 수 있는 경우, 유저에게 정보를 입력받을 필요가 없으면, 다이알로그 박스는 표시되지 않는다. 유저가 서비스 프로바이더의 다이알로그 박스를 취소하면(자),EnumSessions 는 DPERR_USERCANCEL 를 돌려준다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

DPSESSIONDESC2 ,IDirectPlay4::Open ,IDirectPlay4::SecureOpen


IDirectPlay4::GetCaps

IDirectPlay4::GetCaps 메소드는, 해당하는 DirectPlay 오브젝트의 능력을 취득한다.

HRESULT GetCaps(
  LPDPCAPS lpDPCaps,
  DWORD dwFlags
);

파라미터

lpDPCaps
DirectPlay 오브젝트의 능력을 받는 DPCAPS 구조체에의 포인터. IDirectPlay4::GetCaps 를 사용하기 전에 DPCAPS 구조체의 dwSize 멤버를 설정할 필요가 있다.
dwFlags
이 파라미터에 0 을 설정했을 경우, 보증 없음의 메세지 처리에 대한 능력이 계산된다.
DPGETCAPS_GUARANTEED
보증 첨부의 메세지 전달의 능력을 취득한다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS

주의

IDirectPlay4::GetPlayerCaps 메소드가 요구된 플레이어의 능력을 돌려주는데 대해, 이 메소드는 현재 세션의 능력을 돌려준다.

다만, 세션이 열려 있는 동안은,SendEx 로 지원 되고 있는 옵션을 나타내는 능력을 사용할 수 없다. 세션의 호스트인 어플리케이션이 DPSESSIONDESC2 구조체로 DPSESSION_DIRECTPLAYPROTOCOL 플래그를 지정하고 있는 경우는, 모든 SendEx 옵션이 지원 된다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

DPCAPS ,IDirectPlay4::GetPlayerCaps ,IDirectPlay4::Send


IDirectPlay4::GetGroupConnectionSettings

IDirectPlay4::GetGroupConnectionSettings 메소드는,DPLCONNECTION 구조체로부터 그룹의 접속 설정을 취득한다. 이 그룹으로부터 기동된 세션은 모두, 이러한 설정값을 사용한다. 이 메소드는, 로비 세션에서만 사용할 수 있다.

HRESULT GetGroupConnectionSettings(
  DWORD dwFlags,
  DPID idGroup,
  LPVOID lpData,
  LPDWORD lpdwDataSize
);

파라미터

dwFlags
사용하지 않는다. 0 으로 설정해 둔다.
idGroup
접속 설정을 취득하는 그룹의 ID.
lpData
DPLCONNECTION 구조체와 그 전데이터를 카피하는 버퍼에의 포인터. 데이터의 사이즈만을 요구하는 경우는, 이 파라미터에 NULL 를 설정한다. lpdwDataSize 파라미터에는, 데이터를 보관 유지하기 위해서 필요한 최저 사이즈를 설정한다.
lpdwDataSize
이 메소드를 호출하기 전에, 버퍼의 사이즈에 초기화된 변수에의 포인터. 메소드가 돌아오면(자), 이 파라미터에는 데이터의 사이즈가 바이트 단위로 설정되어 있다. 버퍼가 너무 작은 경우 (DPERR_BUFFERTOOSMALL), 이 파라미터에는 최저한 필요한 버퍼의 사이즈가 설정된다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_ACCESSDENIED
DPERR_BUFFERTOOSMALL
DPERR_INVALIDGROUP
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_UNSUPPORTED

주의

그룹의 접속 설정은, staging 영역의 그룹에게만 관계가 있다.

DPSESSIONDESC2 구조체의 guidInstance 데이터 멤버를 참조 하면, 게임이 기동되고 있는지 어떤지를 조사할 수가 있다. 이 구조체의 포인터는, 이 메소드로 돌려주어지는 DPLCONNECTION 구조체의 lpSessionDesc 데이터 멤버에 저장 되고 있다. guidInstance 는, 게임이 기동될 때까지는 GUID_NULL 이다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

DPLCONNECTION ,IDirectPlayLobby3::RunApplication ,IDirectPlay4::SetGroupConnectionSettings


IDirectPlay4::GetGroupData

IDirectPlay4::GetGroupData 메소드는,IDirectPlay4::SetGroupData 를 사용해,그룹 ID 에 관련지을 수 있었던 어플리케이션 고유의 데이터 블록을 취득한다.

HRESULT GetGroupData(
  DPID idGroup,
  LPVOID lpData,
  LPDWORD lpdwDataSize,
  DWORD dwFlags
);

파라미터

idGroup
데이터를 요구하는 그룹 ID.
lpData
어플리케이션 고유의 그룹 데이터를 기입하는 버퍼에의 포인터. 데이터의 사이즈만을 요구 하면나무는, 이 파라미터에 NULL 를 설정한다. lpdwDataSize 파라미터는 데이터를 보관 유지하는데 필요한 사이즈로 설정된다.
lpdwDataSize
이 메소드를 호출하기 전에, 버퍼의 사이즈에 초기화된 변수에의 포인터. 메소드가 돌아오면(자), 이 파라미터에는 그룹 데이터의 사이즈가 바이트 단위로 설정되어 있다. 버퍼가 너무 작은 경우 (DPERR_BUFFERTOOSMALL), 이 파라미터에는 필요한 버퍼의 사이즈가 설정된다.
dwFlags
이 파라미터에 0 을 설정했을 경우, 리모트 데이터가 취득된다.
DPGET_LOCAL
어플리케이션에 의해 설정된 로컬 데이터를 취득한다.
DPGET_REMOTE
리모트의 공유 데이터 영역으로부터 현재 데이터를 취득한다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_BUFFERTOOSMALL
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

주의

DirectPlay 에서는, 로컬과 리모트의 양쪽 모두의 그룹 데이터를 유지할 수 있다. 어플리케이션은, 검색하는 데이터의 타입을 지정할 필요가 있다. 로컬 데이터는, 이 DirectPlay 오브젝트에 의해, DPSET_LOCAL 플래그를 사용해 설정되어 있다. 리모트 데이터는, 세션내의 임의의 어플리케이션에 의해, DPSET_REMOTE 플래그를 사용해 설정되어 있을 가능성이 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::SetGroupData


IDirectPlay4::GetGroupFlags

IDirectPlay4::GetGroupFlags 메소드는, 그룹에 대해 기술하고 있는 플래그를 돌려준다.

HRESULT GetGroupFlags(
  DPID idGroup,
  LPDWORD lpdwFlags
);

파라미터

idGroup
플래그 설정을 취득하는 그룹의 ID.
lpdwFlags
그룹의 플래그 설정을 설정하는 DWORD 에의 포인터. 다음의 언젠가 또는 몇개인가를 설정한다.
DPGROUP_LOCAL
그룹은, 이 어플리케이션에 의해 생성 된 것이다. 이 플래그가 지정되지 않는 경우, 그룹은 리모트 그룹이다.
DPGROUP_STAGINGAREA
그룹은, staging 영역이다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::CreateGroup


IDirectPlay4::GetGroupName

IDirectPlay4::GetGroupName 메소드는, 그룹에 관련지을 수 있고 있는 이름을 돌려준다.

HRESULT GetGroupName(
  DPID idGroup,
  LPVOID lpData,
  LPDWORD lpdwDataSize
);

파라미터

idGroup
이름이 요구되고 있는 그룹의 ID.
lpData
이름 데이터를 기입하는 버퍼에의 포인터. 데이터의 사이즈만을 요구하는 경우는, 이 파라미터에 NULL 를 설정한다. lpdwDataSize 파라미터는 데이터를 보관 유지하는데 필요한 사이즈로 설정된다.
lpdwDataSize
이 메소드를 호출하기 전에, 버퍼의 사이즈에 초기화된 변수에의 포인터. 메소드가 돌아오면(자), 이 파라미터에는 이름 데이터의 사이즈가 바이트 단위로 설정되어 있다. 버퍼가 너무 작은 경우 (DPERR_BUFFERTOOSMALL), 이 파라미터에는 필요한 버퍼의 사이즈가 설정된다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_BUFFERTOOSMALL
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

주의

메소드가 돌아오면(자), 포인터 lpData 를 DPNAME 구조체에 캐스트 해, 그룹명 데이터를 읽어낼 필요가 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

DPNAME ,IDirectPlay4::SetGroupName


IDirectPlay4::GetGroupOwner

IDirectPlay4::GetGroupOwner 메소드는,그룹의 현재의 소유자의 ID 를 돌려준다. 이 메소드는,로비 세션에서만 유효하다.

HRESULT GetGroupOwner(
  DPID idGroup,
  LPDPID lpidOwner
);

파라미터

idGroup
소유자가 요구된 그룹의 ID.
lpidOwner
소유자의 ID 를 받는 변수의 주소.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_GENERIC
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS
DPERR_UNAVAILABLE

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::SetGroupOwner


IDirectPlay4::GetGroupParent

IDirectPlay4::GetGroupParent 메소드는, 그룹의 친그룹의 ID 를 돌려준다.

HRESULT GetGroupParent(
  DPID idGroup,
  LPDPID lpidParent
);

파라미터

idGroup
친그룹이 요구된 그룹의 ID.
lpidParent
친그룹의 ID 를 받는 변수의 주소. 이 메소드로 돌려주어진 친그룹의 ID 가 0 의 경우, 그 그룹은 루트 그룹이다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::CreateGroupInGroup


IDirectPlay4::GetMessageCount

IDirectPlay4::GetMessageCount 메소드는, 특정의 로컬 플레이어의 수신 큐의 메세지수를 문의한다.

HRESULT GetMessageCount(
  DPID idPlayer,
  LPDWORD lpdwCount
);

파라미터

idPlayer
메세지수가 요구되고 있는 플레이어의 ID. 플레이어는, 로컬이 아니면 안된다.
lpdwCount
메소드에 의해 메세지수가 돌려주어지는 변수의 포인터.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::Receive


IDirectPlay4::GetMessageQueue

IDirectPlay4::GetMessageQueue 메소드는, 송신 큐 또는 수신 큐내의 메세지수를 판정한다. 송신 큐의 스테이터스를 모니터 하는 것으로, 어플리케이션은 기저 네트워크의 대역폭에 근거해 세션내의 그 외의 플레이어에게 송신하는 메세지의 수를 조정할 수 있다.

1 대의 컴퓨터의 세션에 복수의 플레이어가 존재하는 경우, 컴퓨터의 큐 사이즈는 개별의 플레이어는 아니고, 그 컴퓨터의 세션의 전플레이어에게 대응하고 있으므로, 주의 해야 한다.

HRESULT GetMessageQueue(
  DPID idFrom,
  DPID idTo,
  DWORD dwFlags,
  LPDWORD lpdwNumMsgs,
  LPDWORD lpdwNumBytes
);

파라미터

idFrom
큐의 스테이터스를 취득하고 싶은 메세지 송신원의 플레이어의 ID. 0 을 지정 하면, 송신된 모든 메세지에 관한 정보가 돌려주어진다. idTo 도 지정했을 경우,idFrom 의 플레이어로부터 idTo 의 플레이어에게 송신된 메세지에 관한 정보만이 돌려주어진다.
idTo
큐의 스테이터스를 취득하고 싶은 메세지 송신지의 플레이어의 ID. 0 을 지정 하면, 송신된 모든 메세지에 관한 정보가 돌려주어진다. idFrom 도 지정했을 경우,idFrom 의 플레이어로부터 idTo 의 플레이어에게 송신된 메세지에 관한 정보만이 돌려주어진다. 다만,idTo 에 그룹 ID 는 지정할 수 없다.
dwFlags
큐에 관한 정보로 취득하는 타입을 지정한다. 디폴트 (dwFlags = 0)에서는, 송신 큐에 관한 정보가 돌려주어진다. 다음의 값의 어느쪽이든을 1 개(살)만 지정할 수 있다.
DPMESSAGEQUEUE_SEND
송신 큐에 관한 정보를 취득한다.
DPMESSAGEQUEUE_RECEIVE
수신 큐에 관한 정보를 취득한다.
lpdwNumMsgs
큐의 메세지수가 설정되는 DWORD 에의 포인터. NULL 의 경우, 값은 아무것도 돌려주어지지 않다.
lpdwNumBytes
큐의 바이트 총수가 설정되는 DWORD 에의 포인터. NULL 의 경우, 값은 아무것도 돌려주어지지 않다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_UNSUPPORTED

유저가 리모트 플레이어의 idTo 를 지정해 수신 큐를 조사했을 경우는 (DPMESSAGEQUEUE_RECEIVE), DPERR_INVALIDPLAYER 가 돌려주어진다. 리모트 플레이어의 idFrom 를 지정해 송신 큐를 조사했을 경우도 (DPMESSAGEQUEUE_SEND), DPERR_INVALIDPLAYER 가 돌려주어진다. 수신 큐 플래그와 송신 큐 플래그의 양쪽 모두를 지정했을 경우 (dwFlags = DPMESSAGEQUEUE_RECEIVE|DPMESSAGEQUEUE_SEND)는, DPERR_INVALIDFLAGS 가 돌려주어진다. DirectPlay 프로토콜이 온이 되어 있지 않고, 또 서비스 프로바이더로 송신 큐의 체크 기능이 지원되어 있지 않은 경우에, 송신 큐를 조사하려고 하면, DPERR_UNSUPPORTED 가 돌려주어진다.

주의

리모트 컴퓨터 위에의 메시지 큐를 조사할 수 없다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::Send ,IDirectPlay4::SendEx


IDirectPlay4::GetPlayerAccount

IDirectPlay4::GetPlayerAccount 메소드는,시큐어 세션으로세션의호스트로부터 호출해, 지정한 플레이어에 관한 어카운트 정보를 취득할 수 있다.

HRESULT GetPlayerAccount(
  DPID idPlayer,
  DWORD dwFlags,
  LPVOID lpData,
  LPDWORD lpdwDataSize
);

파라미터

idPlayer
어카운트 정보를 취득하는 플레이어의 ID.
dwFlags
사용하지 않는다. 0 으로 설정해 둔다.
lpData
어카운트 데이터가 기입해지고 있는 버퍼 (어플리케이션에 의해 할당할 수 있었다)에의 포인터. DPACCOUNTDESC 구조체는, 구조체의 멤버에 의해 참조되는 데이터와 함께 카피된다. 그 때문에, 카피되는 바이트수는 가변이 된다. 이름을 읽어내려면 ,lpData 파라미터를 LPDPACCOUNTDESC 에 캐스트 한다. 어플리케이션에서는, NULL 를 지정해, 필요한 바이트수를 lpdwDataSize 파라미터로 설정하도록(듯이) 요구할 수 있다. 그 후, 그 영역을 할당해 이 메소드를 재차 호출할 수가 있다.
lpdwDataSize
버퍼의 사이즈를 지정해 초기화된 DWORD 에의 포인터. 메소드가 돌아오면(자),lpdwDataSize 에는 실제로 버퍼에 카피된 바이트수가 설정된다. 버퍼가 너무 작은 경우, 메소드로부터는 DPERR_BUFFERTOOSMALL 가 돌려주어져lpdwDataSize 에는 필요한 최저 버퍼 사이즈가 설정된다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_ACCESSDENIED
DPERR_BUFFERTOOSMALL
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

주의

GetPlayerAccount 로부터 돌려주어지는 정보에서는, 어카운트가 일의에 식별된다. 이 정보를 사용해, 로그 온 한 플레이어의 트랜잭션(transaction)나 그 외의 액티버티를 기록할 수 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::SecureOpen


IDirectPlay4::GetPlayerAddress

IDirectPlay4::GetPlayerAddress 메소드는, 플레이어의 DirectPlay 주소를 취득한다.

DirectPlay 주소는, 특정의 서비스 프로바이더를 사용하고 있는 플레이어의 네트워크 주소이다. IDirectPlay4::GetPlayerAddress 에 의해 취득된 버퍼를 해석하려면 ,IDirectPlayLobby3::EnumAddress 메소드를 호출한다.

이 메소드를 로컬 플레이어에 대해서 호출하면, 그 컴퓨터의 네트워크 주소가 취득 가능하면 그것이 돌려주어진다. 경우에 따라서는, 복수의 주소가 돌려주어지는 일도 있다 (예를 들어, 네트워크 카드와 다이얼 업 인터넷 접속의 양쪽 모두가 탑재되고 있는 컴퓨터의 TCP/IP 의 경우 등).

HRESULT GetPlayerAddress(
  DPID idPlayer,
  LPVOID lpData,
  LPDWORD lpdwDataSize
);

파라미터

idPlayer
주소를 요구하는 플레이어의 ID. 0 을 지정 하면,서비스 프로바이더의 유효한 주소 옵션의 리스트를 취득할 수 있다 (예를 들어, 모뎀간 서비스 프로바이더의 유효한 모뎀 옵션의 리스트 등).
lpData
DirectPlay 주소를 기입하는 버퍼에의 포인터. 데이터의 사이즈만을 요구 하면나무는, 이 파라미터에 NULL 를 설정한다. lpdwDataSize 파라미터는 데이터를 보관 유지하는데 필요한 사이즈로 설정된다.
lpdwDataSize
이 메소드를 호출하기 전에, 버퍼의 사이즈에 초기화된 변수에의 포인터. 메소드가 돌아오면(자), 이 파라미터에는 DirectPlay 주소 데이터의 사이즈가 바이트 단위로 설정되어 있다. 버퍼가 너무 작은 경우, 이 파라미터에는 필요한 버퍼 사이즈가 설정되어 메소드로부터는 DPERR_BUFFERTOOSMALL 가 돌려주어진다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_BUFFERTOOSMALL
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_UNAVAILABLE

요구된 플레이어 ID 의 주소를 취득할 수 없는 경우는, DPERR_UNAVAILABLE 를 돌려준다.

주의

유효한 모뎀 옵션의 리스트를 취득하려면 ,idPlayer 파라미터에 0 을 지정한다. 모뎀 옵션의 리스트는, ANSI 캐릭터 라인 또는 Unicode 캐릭터 라인의 리스트로, 종단에 길이가 0 의 캐릭터 라인이 설정되어 돌려주어진다.

이 메소드를 호출했을 때의 인터페이스에 관계없이, DirectPlay 주소에는 주소와 함께 ANSI 캐릭터 라인과 Unicode 캐릭터 라인의 양쪽 모두가 설정된다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlayLobby3::EnumAddress ,DirectPlay 주소


IDirectPlay4::GetPlayerCaps

IDirectPlay4::GetPlayerCaps 메소드는, 지정된 플레이어의 현재의 능력을 취득한다.

HRESULT GetPlayerCaps(
  DPID idPlayer,
  LPDPCAPS lpPlayerCaps,
  DWORD dwFlags
);

파라미터

idPlayer
능력을 계산하는 플레이어의 ID.
lpPlayerCaps
능력을 지정하는 DPCAPS 구조체에의 포인터. DPCAPS 구조체의 dwSize 멤버는,IDirectPlay4::GetPlayerCaps 를 사용하기 전으로 지정할 필요가 있다.
dwFlags
이 파라미터에 0 을 설정했을 경우, 보증 없음의 메세지 처리의 능력이 계산된다.
DPGETCAPS_GUARANTEED
보증 첨부의 메세지 처리의 능력을 취득한다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

주의

IDirectPlay4::GetCaps 메소드가 현재 세션의 능력을 돌려주는데 대해, 이 메소드는 요구된 플레이어의 능력을 돌려준다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

DPCAPS ,IDirectPlay4::GetCaps ,IDirectPlay4::Send


IDirectPlay4::GetPlayerData

메소드는,IDirectPlay4::SetPlayerData 를 사용해 플레이어 ID 에 관련지을 수 있었던 어플리케이션 고유의 데이터 블록을 취득한다.

HRESULT GetPlayerData(
  DPID idPlayer,
  LPVOID lpData,
  LPDWORD lpdwDataSize,
  DWORD dwFlags
);

파라미터

idPlayer
데이터를 요구하는 플레이어 ID.
lpData
어플리케이션 고유의 플레이어 데이터를 기입하는 버퍼에의 포인터. 데이터의 사이즈만을 요구 하면나무는, 이 파라미터에 NULL 를 설정한다. lpdwDataSize 파라미터는 데이터를 보관 유지하는데 필요한 사이즈로 설정된다.
lpdwDataSize
이 메소드를 호출하기 전에, 버퍼의 사이즈에 초기화된 변수에의 포인터. 메소드가 돌아오면(자), 이 파라미터에는 플레이어 데이터의 사이즈가 바이트 단위로 설정되어 있다. 버퍼가 너무 작은 경우 (DPERR_BUFFERTOOSMALL), 이 파라미터에는 필요한 버퍼의 사이즈가 설정된다.
dwFlags
이 파라미터에 0 을 설정했을 경우, 리모트 데이터가 취득된다.
DPGET_LOCAL
어플리케이션에 의해 설정된 로컬 데이터를 취득한다.
DPGET_REMOTE
리모트의 공유 데이터 영역으로부터 현재 데이터를 취득한다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_BUFFERTOOSMALL
DPERR_INVALIDFLAGS
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER

주의

DirectPlay 에서는, 로컬과 리모트의 양쪽 모두의 플레이어 데이터를 보수할 수 있다. 어플리케이션은, 검색하는 데이터의 타입을 지정할 필요가 있다. 로컬 데이터는, 이 DirectPlay 오브젝트에 의해 DPSET_LOCAL 플래그를 사용해 설정되어 있다. 리모트 데이터는, 세션내의 임의의 어플리케이션에 의해 DPSET_REMOTE 플래그를 사용해 설정되어 있을 가능성이 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::SetPlayerData


IDirectPlay4::GetPlayerFlags

IDirectPlay4::GetPlayerFlags 메소드는, 플레이어에 대해 기술하고 있는 플래그를 돌려준다.

HRESULT GetPlayerFlags(
  DPID idPlayer,
  LPDWORD lpdwFlags
);

파라미터

idPlayer
플래그 설정을 취득하는 플레이어의 ID.
lpdwFlags
플레이어의 플래그 설정이 설정되는 DWORD 에의 포인터. 다음의 언젠가 또는 몇개인가를 설정한다.
DPPLAYER_LOCAL
플레이어는 이 어플리케이션에 의해 생성 되었다. 이 플래그가 지정되지 않는 경우, 플레이어는 리모트 그룹이다.
DPPLAYER_SERVERPLAYER
플레이어는, 클라이언트/서버 통신의 서버 플레이어이다.
DPPLAYER_SPECTATOR
플레이어는, 관객으로서 생성 되었다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::CreatePlayer


IDirectPlay4::GetPlayerName

IDirectPlay4::GetPlayerName 메소드는, 플레이어가 관련지을 수 있고 있는 이름을 돌려준다.

HRESULT GetPlayerName(
  DPID idPlayer,
  LPVOID lpData,
  LPDWORD lpdwDataSize
);

파라미터

idPlayer
이름이 요구되고 있는 플레이어의 ID.
lpData
이름 데이터를 기입하는 버퍼에의 포인터. 데이터의 사이즈만을 요구 하면나무는, 이 파라미터에 NULL 를 설정한다. lpdwDataSize 파라미터는 데이터를 보관 유지하는데 필요한 사이즈로 설정된다.
lpdwDataSize
이 메소드를 호출하기 전에, 버퍼의 사이즈에 초기화된 변수에의 포인터. 메소드가 돌아오면(자), 이 파라미터에는 이름 데이터의 사이즈가 바이트 단위로 설정되어 있다. 버퍼가 너무 작은 경우 (DPERR_BUFFERTOOSMALL), 이 파라미터에는 필요한 버퍼의 사이즈가 설정된다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_BUFFERTOOSMALL
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER

주의

메소드가 돌아오면(자), 포인터 lpData 를 DPNAME 구조체에 캐스트 해, 그룹명 데이터를 읽어낼 필요가 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

DPNAME ,IDirectPlay4::SetPlayerName


IDirectPlay4::GetSessionDesc

IDirectPlay4::GetSessionDesc 메소드는, 현재 열려 있는 세션의 프로퍼티를 취득한다.

HRESULT GetSessionDesc(
  LPVOID lpData,
  LPDWORD lpdwDataSize
);

파라미터

lpData
세션 기술 데이터를 기입하는 버퍼에의 포인터. 데이터의 사이즈만을 요구 하면나무는, 이 파라미터에 NULL 를 설정한다. lpdwDataSize 파라미터는 데이터를 보관 유지하는데 필요한 사이즈로 설정된다.
lpdwDataSize
이 메소드를 호출하기 전에, 버퍼의 사이즈에 초기화된 변수에의 포인터. 메소드가 돌아오면(자), 이 파라미터에는 세션 데이터의 사이즈가 바이트 단위로 설정되어 있다. 버퍼가 너무 작은 경우 (DPERR_BUFFERTOOSMALL), 이 파라미터에는 필요한 버퍼의 사이즈가 설정된다. 이 파라미터에 NULL 를 지정 하면, 메소드로부터 DPERR_INVALIDPARAM 가 돌려주어진다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_BUFFERTOOSMALL
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOCONNECTION

주의

이 메소드가 돌려주어지면(자), 포인터 lpData 를 DPSESSIONDESC2 구조체에 캐스트 해, 세션 기술 데이터를 읽어낼 필요가 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

DPSESSIONDESC2 ,IDirectPlay4::EnumSessions ,IDirectPlay4::Open


IDirectPlay4::Initialize

IDirectPlay4::Initialize 메소드는, COM 프로토콜에 준거하기 위해서 준비되어 있다.

HRESULT Initialize(
  LPGUID lpGUID
);

파라미터

lpGUID
인터페이스 식별자로서 사용되는 글로벌 유니크 식별자 (GUID)에의 포인터.

반환값

DPERR_ALREADYINITIALIZED 를 돌려준다.

주의

DirectPlay 오브젝트는 생성시에 초기화되므로, 이 메소드는 반환값으로서 반드시 DPERR_ALREADYINITIALIZED 를 돌려준다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IUnknown::AddRef ,IUnknown::QueryInterface


IDirectPlay4::InitializeConnection

IDirectPlay4::InitializeConnection 메소드는, DirectPlay 접속을 초기화한다. 사용하는서비스 프로바이더, 서버의 네트워크 주소, 세션의 GUID 등, 접속에 관한 모든 정보가,lpConnection 파라미터를 개입시켜 건네받는다

HRESULT InitializeConnection(
  LPVOID lpConnection,
  DWORD dwFlags
);

파라미터

lpConnection
DirectPlay 주소로서 초기화하는 접속에 관한 모든 정보가 저장 되는 버퍼에의 포인터.
dwFlags
사용하지 않는다. 0 으로 설정해 둔다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_ALREADYINITIALIZED
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_UNAVAILABLE

InitializeConnection 가 이전에 이 오브젝트에 대해 불려 갔던 적이 있는 경우는, DPERR_ALREADYINITIALIZED 를 돌려준다. 서비스 프로바이더를 초기화할 수 없는 경우는, DPERR_UNAVAILABLE 를 돌려준다. 이러한 사태는, 이 서비스 프로바이더를 조작하기 위해서 필요한 리소스가 존재하지 않기 위해(때문에) 발생하는 일이 있다 (예를 들어, TCP/IP 스택이 존재하지 않는 경우 등).

주의

이 메소드로 지정하는 lpConnection 파라미터는,IDirectPlay4::EnumConnections 메소드로부터 취득하는지, 또는 어플리케이션으로IDirectPlayLobby3::CreateCompoundAddress 메소드를 사용해 직접 생성 할 수 있다.

이 메소드는, 해당하는 서비스 프로바이더를 로드해 초기화한다. 이 서비스 프로바이더에 lpConnection 파라미터를 건네주어, 관련 정보를 추출해 보존한다. 이 정보는, 서비스 프로바이더로 그 정보를 입력하기 위한 다이알로그 박스를 표시하지 않고 IDirectPlay4::EnumSessions 메소드 또는 IDirectPlay4::Open 메소드를 호출하면나무에 사용된다.

이 메소드는 DirectPlayCreate 대신에 사용해, 서비스 프로바이더를 DirectPlay 오브젝트에 바인드 할 수가 있다. InitializeConnection 의 주된 이점은, 서비스 프로바이더의 다이알로그 박스를 덧쓰기해,로비 프로바이더를 초기화할 수 있는 것에 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::EnumConnections ,IDirectPlayLobby3::CreateCompoundAddress ,DirectPlay 주소


IDirectPlay4::Open

IDirectPlay4::Open 메소드는,IDirectPlay4::EnumSessions 메소드의 호출로 열거한세션에 참가하거나 다른 유저가 열거 및 참가할 수 있는 새로운 세션을 생성 할 경우에 사용된다.

HRESULT Open(
  LPDPSESSIONDESC2 lpsd,
  DWORD dwFlags
);

파라미터

lpsd
생성 또는 참가하는 세션을 기술한 DPSESSIONDESC2 구조체에의 포인터. 세션에 참가하는 경우는,dwSize,guidInstance,lpszPassword 데이터 멤버만을 지정하면 좋다. 열거한 세션으로 DPSESSION_PASSWORD 플래그가 설정되어 있는 경우는, 패스워드만을 지정하면 좋다.

세션을 생성 하는 경우, 어플리케이션으로, 생성 하는 세션의 프로퍼티를 사용해 DPSESSIONDESC2 구조체를 모두 설정할 필요가 있다. guidInstance 는, DirectPlay 에 의해 생성 된다.

dwFlags
다음의 플래그의 어느쪽이든을 1 개(살)만 설정한다.
DPOPEN_CREATE
어플리케이션 세션의 새로운 인스턴스를 생성 한다. 로컬 컴퓨터가, 세션의 네임서버-겸호스트가 된다.
DPOPEN_JOIN
어플리케이션 세션의 기존의 인스턴스에 참가한다. 어플리케이션은 플레이어를 생성 해, 메세지를 송수신 할 수 있다.
DPOPEN_RETURNSTATUS
이 플래그를 지정했을 경우는, 접속의 진행 상황을 나타내는 다이알로그 박스가 표시되지 않는다. 곧바로 접속할 수 없는 경우, 메소드는 DPERR_CONNECTING 에러를 돌려준다. 어플리케이션은, 정상 종료를 나타내는 DP_OK 가 돌려주어지는지, 또는 에러를 나타내는 그 다른 에러 코드가 돌려주어질 때까지 Open 를 계속 호출할 필요가 있다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_ACCESSDENIED
DPERR_ALREADYINITIALIZED
DPERR_AUTHENTICATIONFAILED
DPERR_CANNOTCREATESERVER
DPERR_CANTCREATEPLAYER
DPERR_CANTLOADCAPI
DPERR_CANTLOADSECURITYPACKAGE
DPERR_CANTLOADSSPI
DPERR_CONNECTING
DPERR_CONNECTIONLOST
DPERR_ENCRYPTIONFAILED
DPERR_ENCRYPTIONNOTSUPPORTED
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPASSWORD
DPERR_LOGONDENIED
DPERR_NOCONNECTION
DPERR_NONEWPLAYERS
DPERR_NOSESSIONS
DPERR_SIGNFAILED
DPERR_TIMEOUT
DPERR_UNINITIALIZED
DPERR_USERCANCEL

이 DirectPlay 오브젝트로 세션이 이미 열리고 있는 경우는, DPERR_ALREADYINITIALIZED 를 돌려준다.

세션 기술의 최대 플레이어수에 이미 달하고 있는 경우는, DPERR_CANTCREATEPLAYER 를 돌려준다.

세션으로부터 Open 요구에 응답이 돌려주어지지 않았던 경우는, DPERR_TIMEOUT 를 돌려준다.

유저가 열거 요구를 취소했을 경우 (일반적으로,서비스 프로바이더의 다이알로그 박스를 취소하는 것으로)는,DPERR_USERCANCEL 를 돌려준다.

기존의 세션에 참가하기 위해서 불려 갔지만, 세션이 내부 세션 리스트에 없었던 경우 (또는 세션의 guidInstance 가 파손하고 있었을 경우)는, DPERR_NOSESSIONS 를 돌려준다.

주의

어플리케이션이 세션에 참가 하면, 플레이어를 생성 해, 세션내의 다른 플레이어와 통신을 시작 할 수가 있다. 다만,IDirectPlay4::CreatePlayer 메소드를 사용해 로컬 플레이어를 생성 할 때까지는, 이 DirectPlay 오브젝트로 메세지는 수신되지 않고, 또 메세지를 송신할 수 없다.

어플리케이션으로 동시에 2 개의 세션을 열려면 , DirectPlay 오브젝트를 2 개 생성 해, 각각 1 개(살)씩 세션을 열 필요가 있다.

세션에 참가하려면 ,DPSESSIONDESC2 구조체의 dwSize 멤버와 guidInstance 멤버를 지정하는 것만으로 좋다. 세션이 패스워드 보호와 마크 되고 있으면,lpszPassword 멤버도 지정할 필요가 있다. 열거된 세션으로 패스워드가 필요한 경우는, 그 세션에 DPSESSION_PASSWORDREQUIRED 플래그가 설정된다.

시큐어 세션에 참가하는 경우는,SecureOpen 를 사용해 로그 온 증명서를 지정할 필요가 있다. 열거된 세션으로 증명서가 필요한 경우는, 그 세션에 DPSESSION_SECURESERVER 플래그가 설정된다.

DPSESSIONDESC2 구조체의 DPSESSION_SECURESERVER 플래그를 지정 하면, 세션은 디폴트의 시큐러티 패키지의 NTLM(NT LAN Manager)로 열린다. 다른 시큐러티 패키지를 지정하려면 ,SecureOpen 를 사용한다.

어플리케이션으로 세션에 참가하는 경우, 서버는 Open 요구를 거부하거나 그것을 무시할 수가 있다 (Open 가 마감 시간의 경우). 신규 플레이어가 무효인 세션, 참가가 무효인 세션, 플레이어의 제한에 이르고 있는 세션, 또는 부정한 패스워드가 지정된 세션에 참가하려고 하면(자),DPERR_NONEWPLAYERS 에러 또는 DPERR_INVALIDPASSWORD 에러가 발생한다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

DPSESSIONDESC2 ,IDirectPlay4::Close ,IDirectPlay4::SecureOpen ,IDirectPlay4::EnumSessions


IDirectPlay4::Receive

IDirectPlay4::Receive 메소드는, 메시지 큐로부터 메세지를 취득한다.

HRESULT Receive(
  LPDPID lpidFrom,
  LPDPID lpidTo,
  DWORD dwFlags,
  LPVOID lpData,
  LPDWORD lpdwDataSize
);

파라미터

lpidFrom
송신측 플레이어의 ID 를 받는 변수의 주소. DPRECEIVE_FROMPLAYER 플래그를 지정하는 경우, 이 변수는, 이 메소드를 호출하기 전에 플레이어 ID 에 의해 초기화할 필요가 있다.
lpidTo
수신측 플레이어의 ID 를 받는 변수의 주소. DPRECEIVE_TOPLAYER 플래그를 지정하는 경우, 이 변수는, 이 메소드를 호출하기 전에 플레이어 ID 에 의해 초기화할 필요가 있다.
dwFlags
다음의 컨트롤 플래그의 언젠가 또는 몇개인가를 설정할 수 있다. 디폴트 (dwFlags = 0)에서는, 최초의 사용 가능한 메세지가 취득된다.
DPRECEIVE_ALL
최초의 사용 가능한 메세지를 돌려준다. 이것이 디폴트이다.
DPRECEIVE_PEEK
다른 플래그에 의해 지정된 것처럼 메세지를 돌려주지만, 그것을 메시지 큐로부터 삭제하지 않는다. 이 플래그는,lpData 가 NULL 의 경우로 지정할 필요가 있다.
DPRECEIVE_TOPLAYER 및 DPRECEIVE_FROMPLAYER
DPRECEIVE_TOPLAYER 와 DPRECEIVE_FROMPLAYER 를 양쪽 모두 지정했을 경우,Receive 는 1) lpidTo 에 의해 지정된 플레이어에게 송신된 메세지와 2) lpidFrom 에 의해 지정된 플레이어로부터 송신된 메세지만을 돌려준다. 다만, 이것들 양쪽 모두의 조건이 채워지지 않으면 안 된다.

DPRECEIVE_TOPLAYER lpidTo 에 의해 지정된 플레이어에게 송신된 메세지만을 돌려준다.

DPRECEIVE_FROMPLAYER 만을 지정했을 경우,Receive 는 lpidFrom 에 의해 지정된 플레이어로부터 송신된 메세지만을 돌려준다.

DPRECEIVE_TOPLAYER 도 DPRECEIVE_FROMPLAYER 도 설정하지 않는 경우,Receive 는 최초로 사용 가능한 메세지를 돌려준다.

lpData
메세지 데이터를 기입하는 버퍼에의 포인터. 데이터의 사이즈만을 요구 하면나무는, 이 파라미터에 NULL 를 설정한다. lpdwDataSize 파라미터는 데이터를 보관 유지하는데 필요한 사이즈로 설정된다. 플레이어 ID 가 DPID_SYSMSG의 플레이어로부터 메세지가 송신되고 있는 경우, 어플리케이션은 lpData 를 DPMSG_GENERIC 로 설정해,dwType 멤버를 조사해 시스템 메세지의 타입을 조사하고 나서 그것을 처리한다.
lpdwDataSize
이 메소드를 호출하기 전에, 버퍼의 사이즈에 초기화된 DWORD 에의 포인터. 메소드가 돌아오면(자), 이 파라미터에는 버퍼에 카피된 바이트수가 설정되어 있다. 버퍼가 너무 작은 경우 (DPERR_BUFFERTOOSMALL), 이 파라미터에는 필요한 버퍼의 사이즈가 설정된다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_BUFFERTOOSMALL
DPERR_GENERIC
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_NOMESSAGES

주의

DPID_SYSMSG 로서 정의된 플레이어 ID 로부터 수신한 메세지는, 세션으로 어플리케이션으로 변경을 통지할 경우에 사용하는 시스템 메세지이다. 이러한 경우, 시스템 메세지의 lpData 를 DPMSG_GENERIC 로 설정해,dwType 멤버를 조사해 무엇에 고유의 시스템 메세지인지를 조사한다.

DPID_ALLPLAYERS 로서 정의된 플레이어 ID, 또는 그룹 ID 에 송신된 메세지는, 송신원의 플레이어 ID 로부터 취득했는지와 같이 표시된다. 어플리케이션은, 로컬 플레이어에게 송신된 메세지만을 수신한다. 플레이어는,lpidFrom 와 lpidTo 가 포인트 하고 있는 값이 같은 메세지는 수신할 수 없다.

세션 기술로 DPSESSION_NOMESSAGEID 를 지정했을 경우,lpidFrom 는 반드시 0xFFFFFFFF 가 되어, 또 lpidTo 값은 임의가 된다.

DirectPlay 에 탑재되고 있는 서비스 프로바이더는 모두, 데이터를 파손으로부터 지키기 위해서(때문에) 정합성 체크를 행한다. Receive 를 사용해 취득한 메세지는, 파손하고 있지 않으면 보증되고 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

DPMSG_GENERIC ,IDirectPlay4::Send


IDirectPlay4::SecureOpen

IDirectPlay4::SecureOpen 메소드는,시큐어 세션을 생성 하거나 그 세션에 참가하거나 한다. 시큐어 세션에 참가 하면 와, 이 메소드를 사용해 로그 온 증명서를 지정한다.

새로운 세션을 생성 하면 와,호스트 컴퓨터는 사용하는 대체 시큐러티 패키지를 지정할 수 있다. 세션에 참가 하면나무는, 유저명과 패스워드를 지정할 수 있다.

HRESULT SecureOpen(
  LPCDPSESSIONDESC2 lpsd,
  DWORD dwFlags,
  LPCDPSECURITYDESC lpSecurity,
  LPCDPCREDENTIALS lpCredentials
);

파라미터

lpsd
생성 또는 참가하는 세션에 대해 기술한 DPSESSIONDESC2 구조체에의 포인터. 세션에 참가하는 경우,guidInstance 멤버와 lpszPassword 멤버를 지정하는 것만으로 좋다. 열거된 세션으로 DPSESSION_PASSWORDREQUIRED 플래그가 설정되어 있는 경우는, 패스워드를 지정하는 것만으로 좋다.

세션을 생성 하는 경우는, 어플리케이션으로, 생성 하는 세션의 프로퍼티를 사용해 DPSESSIONDESC2 구조체를 모두 설정할 필요가 있다. guidInstance 는, DirectPlay 에 의해 생성 된다. 다만, 세션을 열려고 하는 컴퓨터는 모두 인증되어 있지 않으면 안 되는 것을 나타내기 위해서(때문에), DPSESSION_SECURESERVER 플래그를 설정할 필요가 있다.

DPSESSIONDESC2 구조체를 설정하는 경우에 DPSESSION_SECURESERVER 플래그를 지정하지 않으면,SecureOpen 는 Open 가 불려 갔을 때 것과 같이 비시큐어 세션을 연다.

dwFlags
다음의 플래그의 어느쪽이든을 지정한다.
DPOPEN_CREATE
시큐어 세션의 새로운 인스턴스를 생성 한다.
DPOPEN_JOIN
시큐어 세션의 기존의 인스턴스에 참가한다.
DPOPEN_RETURNSTATUS
이 플래그를 지정했을 경우는, 접속의 진행 상황을 나타내는 다이알로그 박스가 표시되지 않는다. 곧바로 접속할 수 없는 경우, 메소드는 DPERR_CONNECTING 에러를 돌려준다. 어플리케이션은, 정상 종료를 나타내는 DP_OK 가 돌려주어지는지, 또는 에러를 나타내는 그 다른 에러 코드가 돌려주어질 때까지 SecureOpen 를 계속 호출할 필요가 있다.
lpSecurity
사용하는 시큐러티 패키지가 저장 되고 있는 DPSECURITYDESC 구조체에의 포인터. 디폴트의 시큐러티 패키지 (NT LAN Manager)나 CryptoAPI 패키지 (Microsoft RSA Base Cryptographic Provider)를 사용할때는, 이 파라미터에 NULL 를 설정한다. 이것은, 세션을 생성 하는 경우에게만 관계가 있다. 세션에 참가 하면나무는 NULL 를 설정해야 한다.
lpCredentials
서버로 인증하는 로그 온명, 패스워드, 도메인이 저장 되고 있는 DPCREDENTIALS 구조체에의 포인터. 증명서가 없는 경우는, NULL 를 지정한다. 세션을 생성 하면 와, 증명서는 무시된다.

반환값

성공하면 DP_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_ACCESSDENIED
DPERR_ALREADYINITIALIZED
DPERR_AUTHENTICATIONFAILED
DPERR_CANNOTCREATESERVER
DPERR_CANTLOADCAPI
DPERR_CANTLOADSECURITYPACKAGE
DPERR_CANTLOADSSPI
DPERR_CONNECTING
DPERR_CONNECTIONLOST
DPERR_ENCRYPTIONFAILED
DPERR_ENCRYPTIONNOTSUPPORTED
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPASSWORD
DPERR_LOGONDENIED
DPERR_NOCONNECTION
DPERR_NONEWPLAYERS
DPERR_SIGNFAILED
DPERR_TIMEOUT
DPERR_UNINITIALIZED
DPERR_USERCANCEL

무효인 증명서를 사용해 불려 갔을 경우, 또는 증명서가 필요한데 그것을 지정하지 않고 불려 갔을 경우는, DPERR_LOGONDENIED 를 돌려준다. 어플리케이션은 유저의 증명서를 수집해,SecureOpen 를 재차 호출할 필요가 있다.

주의

세션에 참가하는 경우, 최초로 증명서를 지정하지 않고 SecureOpen 를 호출한다. 메소드로부터 DPERR_LOGONDENIED 가 돌려주어지면(자), 유저에게 유저명과 패스워드를 입력받아, 유저의 증명서를 lpCredentials 파라미터로 지정해 SecureOpen 를 재차 호출할 필요가 있다. 메소드로부터 DP_OK 가 돌려주어졌을 경우, 플레이어는 전에 시스템 로그 온 (NTLM 에서의 네트워크 로그 온) 시로 지정한 증명서를 사용해 로그 온 할 수 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::Open


IDirectPlay4::Send

IDirectPlay4::Send 메소드는, 메세지를 세션내의 다른 플레이어, 플레이어의 그룹, 또는 모든 플레이어에게 송신한다. 메세지를 다른 플레이어에게 송신하려면 , 그 대상이 되는 플레이어의 플레이어 ID 를 지정한다. 메세지를 플레이어의 그룹에 송신하려면 , 메세지를 그룹에 할당할 수 있었던 그룹 ID 에 송신한다. 메세지를 세션 전체에 송신하려면 , 메세지를 플레이어 ID 의 DPID_ALLPLAYERS 에 송신한다. 메세지는, 메세지 마다 보증 첨부 프로토콜 또는 보증 없음 프로토콜의 머지않아를 사용해도 송신할 수 있다. 세션이 보증 서버에 있는 경우, 메세지는 메세지 마다 암호화해 (프라이버시를 보호하기 위해(때문에)), 또는 디지털 서명을 해 (인증을 실시하기 (위해)때문에) 송신할 수 있다.

HRESULT Send(
  DPID idFrom,
  DPID idTo,
  DWORD dwFlags,
  LPVOID lpData,
  DWORD dwDataSize
);

파라미터

idFrom
송신측 플레이어의 ID. 플레이어 ID 는, 이 컴퓨터의 로컬 플레이어가 있지 않고 게대응하고 있지 않으면 안 된다.
idTo
메세지의 송신지 ID. 메세지를 다른 플레이어에게 송신하려면 , 플레이어의 ID 를 지정한다. 메세지를 그룹내의 모든 플레이어에게 송신하려면 , 그룹의 ID 를 지정한다. 메세지를 세션내의 모든 플레이어에게 송신하려면 , 정수 기호의 DPID_ALLPLAYERS 를 사용한다. 메세지를 서버 플레이어에게 송신하려면 , 정수 기호의 DPID_SERVERPLAYER 를 지정한다. 플레이어는, 그 자체에 메세지를 송신할 수 없다.
dwFlags
메세지의 송신 방법을 지정한다. 디폴트 (dwFlags = 0)에서는, 메세지는 보증없이 송신된다.
DPSEND_ENCRYPTED
메세지를 암호화해 송신한다. 이것은,시큐어 세션에서만 행해진다. 이 플래그는, DPSEND_GUARANTEED 플래그도 설정되어 있는 경우에게만 사용할 수 있다. 메세지는,DPMSG_SECUREMESSAGE 시스템 메세지로서 송신된다.
DPSEND_GUARANTEED
보증 첨부 전달 방식을 사용해 메세지를 송신한다.
DPSEND_SIGNED
디지털 서명을 사용해 메세지를 송신한다. 이것은, 시큐어 세션에서만 실시할 수가 있다. 이 플래그는, DPSEND_GUARANTEED 플래그도 설정되어 있는 경우에게만 사용할 수 있다. 메세지는,DPMSG_SECUREMESSAGE 시스템 메세지로서 송신된다.
lpData
송신하는 데이터에의 포인터.
dwDataSize
송신하는 데이터의 길이.

반환값

성공하면 DP_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_BUSY
DPERR_CONNECTIONLOST
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_NOTLOGGEDIN
DPERR_SENDTOOBIG

보증 첨부 전달 방식을 사용하도록(듯이) 지정되어 있지 않은 메세지에 암호화 플래그나 서명 플래그가 지정되었을 경우는, DPERR_INVALIDPARAMS 를 돌려준다. 클라이언트 어플리케이션이 최초로 로그 온 하지 않고 기밀 보호 메세지를 송신하려고 했을 경우는, DPERR_NOTLOGGEDIN 를 돌려준다.

메세지를 그룹에 송신했을 경우, 반환값의 DP_OK 가, 그룹내의 모든 플레이어가 메세지를 수신한 것을 나타낸다고는 할 수 없다. 메세지를 보증 첨부로 송신했을 경우, DP_OK 는 DirectPlay 가 메세지를 그룹내의 모든 플레이어에게 송신하도록(듯이) 최선을 다한 것을 의미하고 있다. 일반적으로, 메세지를 수신하고 있지 않는 플레이어는, 그 접속에 문제가 있어 삭제되고 있다.

주의

비동기 송신 옵션에서는,IDirectPlay4::SendEx 를 사용하는 것.

메세지는, 보증 붙어, 또는 보증없이 송신할 수 있다. 디폴트에서는, 메세지는 보증없이 송신된다. 즉, DirectPlay 는, 메세지가 목적의 수신자에게 도착해 있을지 어떨지를 검증하지 않는다. 보증 첨부 메세지를 송신 하면, 시간이 걸린다. 적어도, 보증 없음 메세지의 2~3배의 시간이 걸린다. 어플리케이션은, 할 수 있는 한 보증 첨부 메세지의 송신을 줄여, 또 상실 메세지에 견딜 수 있도록(듯이) 설계할 필요가 있다. DirectPlay 에 탑재되고 있는 서비스 프로바이더는 모두, 데이터를 파손으로부터 지키기 위해서(때문에) 정합성 체크를 실시하고 있다. 이 메소드를 사용해 송신된 메세지는, 파손하고 있지 않으면 보증된다.

서비스 프로바이더가 보증 첨부 메세지를 지원 하고 있을지 어떨지에 관계없이, 또 DirectPlay 프로토콜 플래그를 설정해 있을지 어떨지에 관계없이, 시스템 메세지는 항상 보증 첨부로 송신된다. 보증 첨부 시스템 메세지를 송신 하면나무는, DirectPlay 프로토콜이 자동적으로 사용된다.

시스템 메세지 이외로, 어플리케이션이 DirectPlay 프로토콜 플래그를 설정해, 메세지를 보증 첨부로 송신했을 (DPSEND_GUARANTEED 플래그를 설정한다) 경우, 서비스 프로바이더가 보증 첨부 메세지를 지원 하고 있을지 어떨지에 관계없이, 그 메세지는 보증 첨부로 송신된다.

시스템 메세지 이외로, 어플리케이션이 DirectPlay 프로토콜 플래그를 설정하지 않고, 메세지를 보증 첨부로 송신했을 경우, 그 메세지는, 서비스 프로바이더가 보증 첨부 메세지를 지원 하고 있을 때 마셔 보증 첨부로 송신된다. 서비스 프로바이더가 그것을 지원 하고 있지 않는 경우, DPSEND_GUARANTEED 플래그에 관계없이, 메세지는 보증 첨부로 송신되지 않는다.

어플리케이션은, 세션 생성시에 DPSESSION_DIRECTPLAYPROTOCOL 플래그를 설정해 DirectPlay 프로토콜을 기동한다.

플레이어는, 자기 자신에게 메세지를 송신할 수 없다. 플레이어가, DPID_ALLPLAYERS 에 포함되는 그룹이나 DPID_ALLPLAYERS 에 메세지를 송신했을 경우, 플레이어에게는 그 메세지의 카피가 송신되지 않는다. 다만, 세션 기술 (DPSESSIONDESC2 )에 DPSESSION_NOMESSAGEID 가 지정되고 있는 경우는 예외이다. 이 경우, 플레이어는 그룹에 송신한 메세지를 수신할 수 있다. 이 메세지에는 DirectPlay 메세지 ID 헤더 (메세지의 송신자를 나타낸다)가 없기 때문에, 메세지 ID 에 근거해 메세지가 필터링 되지 않는다.

DPSESSION_NOMESSAGEID 를 사용하고 있는 경우,idFrom 파라미터는 의미가 없어져, 또 idTo 파라미터는 올바른 타겟 컴퓨터에 메세지를 방향 짓기 (위해)때문에인 만큼 사용된다. 타겟 컴퓨터에 복수의 플레이어가 있는 경우는, 메세지를 설정하는 수신 큐를 특정할 수 없다. 메세지는, 수신되어도 DPID_UNKNOWN 플레이어로부터 송신된 것이라고 표시된다.

Send 메소드를 사용해 전송 가능한 메세지의 사이즈에는 제한이 없다. DirectPlay 는, 사이즈의 큰 메세지를 자동적으로 몇개의 패킷에 분할해, 수신측에서 그것들을 조립한다. 사이즈의 큰 메세지를 보증없이 송신하는 경우는, 그 패킷중 1 개(살)에서도 수신 측에 도달하지 않으면, 메세지 전체가 무시된다. 어플리케이션은,GetCaps 를 호출해 DPCAPS 구조체의 dwMaxBufferSize 멤버를 조사하는 것으로, 1 개의 패킷으로 송신 가능한 메세지의 최대 사이즈를 판정할 수 있다.

암호화 메세지나 서명 첨부 메세지를 송신했을 경우, 그 메세지는 어플리케이션 메세지는 아니고, 시스템 메세지의 DPMSG_SECUREMESSAGE 로서 배포된다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::Receive ,IDirectPlay4::SendEx ,IDirectPlay4::SendChatMessage ,DPMSG_SECUREMESSAGE


IDirectPlay4::SendChatMessage

IDirectPlay4::SendChatMessage 메소드는, 텍스트 메세지를 다른 플레이어, 플레이어의 그룹, 또는 모든 플레이어에게 송신한다. 이 메소드는, Unicode 캐릭터 라인 (IDirectPlay4 인터페이스)과 ANSI 캐릭터 라인 (IDirectPlay4A 인터페이스)을 양쪽 모두 지원 하고 있다. 채팅 메세지를 수신한 플레이어에게는, 플레이어의 수신 큐의 DPMSG_CHAT 시스템 메세지에 의해 통지가 있다. 이 메소드는,로비 세션으로 사용된다.

HRESULT SendChatMessage(
  DPID idFrom,
  DPID idTo,
  DWORD dwFlags,
  LPDPCHAT lpChatMessage
);

파라미터

idFrom
송신측 플레이어의 ID. 플레이어 ID 는, 이 컴퓨터의 로컬 플레이어가 있지 않고 게대응하고 있지 않으면 안 된다.
idTo
메세지의 송신지인 플레이어의 ID 또는 플레이어의 그룹의 ID, 혹은 메세지를 세션내의 모든 플레이어에게 송신 하면나무는 DPID_ALLPLAYERS.
dwFlags
메세지의 송신 방법을 지정한다. 이 파라미터에 0 을 설정했을 경우, 메세지는 보증없이 송신된다.
DPSEND_GUARANTEED
보증 첨부 전달 방식을 사용할 수 있는 경우는, 그것에 의해 메세지를 송신한다.
lpChatMessage
송신하는 메세지가 저장 되고 있는 DPCHAT 구조체에의 포인터.

반환값

성공하면 DP_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

idTo 의 ID 가 유효한 플레이어 또는 그룹이 아닌 경우는, DPERR_INVALIDPARAMS 를 돌려준다. idFrom 의 ID 가 유효한 플레이어 또는 그룹이 아닌 경우는, DPERR_INVALIDPLAYER 를 돌려준다. idFrom 의 ID 가 로컬 플레이어가 아닌 경우는, DPERR_ACCESSDENIED 를 돌려준다.

주의

이 메소드는, 다른 클라이언트 어플리케이션을 접속 가능한 로비 세션내에서의 플레이어 사이의 채팅을 용이하게 한다. 이 메소드는,로비 세션으로 사용한다. 어플리케이션 세션에서의 사용은, 옵션이다.

수신측 플레이어는, 시스템 메세지 (idFrom = DPID_SYSMSG)를 수신한다. DPCHAT 구조체는, 채팅 메세지의 송신원플레이어를 지정한다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

DPCHAT ,DPMSG_CHAT ,IDirectPlay4::Send


IDirectPlay4::SendEx

IDirectPlay4::SendEx 메소드는, 메세지를 세션내의 다른 플레이어, 플레이어의 그룹, 또는 모든 플레이어에게 송신한다. SendEx 는,Send 메소드를 강화한 것이어, 사용 가능한 옵션도 많다. SendEx 에서는, 보증 첨부 메세지와 보증 없음 메세지의 양쪽 모두를 지원 하고 있다. 또, 비동기 메세지를 송신하거나 메세지의 우선 순위나 타임 아웃을 설정할 수도 있다.

HRESULT SendEx(
  DPID idFrom,
  DPID idTo,
  DWORD dwFlags,
  LPVOID lpData,
  DWORD dwDataSize,
  DWORD dwPriority,
  DWORD dwTimeout,
  LPVOID lpContext,
  LPDWORD lpdwMsgID
);

파라미터

idFrom
송신측 플레이어의 ID. 플레이어 ID 는, 메세지의 송신원컴퓨터의 로컬 플레이어가 있지 않고 게대응하고 있지 않으면 안 된다.
idTo
메세지의 송신지 ID. 메세지를 다른 플레이어에게 송신하려면 , 플레이어의 ID 를 지정한다. 메세지를 그룹내의 모든 플레이어에게 송신하려면 , 그룹의 ID 를 지정한다. 메세지를 세션내의 모든 플레이어에게 송신하려면 , 정수 기호의 DPID_ALLPLAYERS 를 사용한다. 메세지를 서버 플레이어에게 송신하려면 , 정수 기호의 DPID_SERVERPLAYER 를 지정한다. 플레이어가 자신에게 메세지를 송신할 수 없다.
dwFlags
메세지의 송신 방법을 지정한다. 디폴트 (dwFlags = 0)에서는, 메세지는 보증없이 송신된다.
DPSEND_ASYNC
메세지를 비동기에게 송신한다. 함수는 곧바로 돌아와,lpdwMsgID 파라미터에는 값이 설정되어 있다. 이 플래그를 지정하지 않는 경우, 메세지가 송신되는 (보증 첨부로 송신되고 있는 경우는, 긍정 응답을 받아들인다)까지 함수는 돌아오지 않는다. 송신이 완료 하면,DPMSG_SENDCOMPLETE 시스템 메세지가 보내진다.

이 플래그를 사용했을 경우, 메세지가 송신 큐로 설정되었을 때는, 반환값이 DPERR_PENDING 가 된다. 이것은, 치명적인 에러는 아니고, 메세지가 곧바로 송신되지 않았던 것을 유저에게 다만 알리기 위한 반환값이다.

DPSEND_ENCRYPTED
메세지를 암호화해 송신한다. 이것은,시큐어 세션에서만 행해진다. 이 플래그는, DPSEND_GUARANTEED 플래그도 설정되어 있는 경우에게만 사용할 수 있다. 메세지는,DPMSG_SECUREMESSAGE 시스템 메세지로서 송신된다.
DPSEND_GUARANTEED
보증 첨부 전달 방식이 사용 가능한 경우, 그것에 의해 메세지를 송신한다.
DPSEND_NOSENDCOMPLETEMSG
이 플래그를 설정했을 경우, 미완료 메세지가 송신된다. 이 플래그는, DPSEND_ASYNC 플래그도 설정되어 있는 경우에게만 사용할 수 있다.
DPSEND_SIGNED
디지털 서명을 사용해 메세지를 송신한다. 이것은,시큐어 세션에서만 실시할 수가 있다. 이 플래그는, DPSEND_GUARANTEED 플래그도 설정되어 있는 경우에게만 사용할 수 있다. 메세지는,DPMSG_SECUREMESSAGE 시스템 메세지로서 송신된다.
lpData
송신하는 데이터에의 포인터.
dwDataSize
송신하는 데이터의 길이.
dwPriority
메세지의 우선 순위로, 범위는 0~65535 이다. 0 이 최저의 우선 순위의 메세지가 된다. 값이 크면 큰 만큼, 메세지의 우선 순위는 높아진다. 큐안에, 여기서 지정한 우선 순위보다 높은 우선 순위의 메세지가 없는 경우에게만, 그 메세지가 송신된다.

메모 모든 서비스 프로바이더로 이 옵션이 지원 되고 있다고는 할 수 없다. 이것이 지원되어 있지 않은 경우, 0 이외의 우선 순위를 지정 하면, DPERR_UNSUPPORTED 에러가 돌려주어진다. 이 옵션이 지원 되고 있는지 어떤지를 판정하려면 ,GetCaps 를 호출한다.

dwTimeout
메세지 전달시의 시간제한을 어플리케이션이 옵션으로 지정하는 타임 아웃 (밀리 세컨드 단위). 이 시간내에 메세지를 전달할 수 없는 경우, 그 메세지는 자동적으로 삭제되어, DPMSG_SENDCOMPLETE 메세지가 송신된다. 0 은, 타임 아웃을 사용하는 것을 나타낸다.

메모 모든 서비스 프로바이더로 이 옵션이 지원 되고 있다고는 할 수 없다. 지원되어 있지 않은 경우, 0 이외의 타임 아웃을 지정 하면, DPERR_UNSUPPORTED 에러가 돌려주어진다. 이 옵션이 지원 되고 있는지 어떤지를 판정하려면 ,GetCaps 를 호출한다.

lpContext
어플리케이션에 의해 정의된 문맥으로, 송신이 완료했을 때에 완료 메세지의 일부로서 어플리케이션에 돌려주어지는 것. NULL 도 설정할 수 있다.
lpdwMsgID
DirectPlay 에 의해 메세지용으로 생성된 ID 가 설정되는 DWORD 에의 포인터. 이 ID 는, 메세지의 스테이터스를 조사하거나 그것을 취소할 때 사용한다. 메세지 ID 가 필요없는 경우는, NULL 를 지정한다. 이 파라미터는, 비동기 메세지의 경우에게만 돌려주어진다.

반환값

동기 메세지의 경우는, 처리가 성공하면(자) DP_OK 를 돌려준다. 비동기 메세지의 경우는, 송신 처리로 메세지를 큐로 설정할 수 있으면(자) DPERR_PENDING 를 돌려준다. 유저는,DPMSG_SENDCOMPLETE 메세지로부터 완료 정보를 취득한다. 그 이외의 경우는, 다음의 에러값의 어느쪽이든인지를 돌려준다.

DPERR_BUSY
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_INVALIDPRIORITY
DPERR_NOTLOGGEDIN
DPERR_SENDTOOBIG
DPERR_UNSUPPORTED

보증 첨부로서 지정되어 있지 않은 메세지에 암호화 플래그나 서명 첨부 플래그가 지정되었을 경우, 또는 비동기가 아닌 메세지에 DPSEND_NOCOMPLETEMSG 플래그가 지정되었을 경우는, DPERR_INVALIDPARAMS 를 돌려준다. 우선 순위가 0~65535 의 범위내에 없는 경우는, DPERR_INVALIDPRIORITY 을 돌려준다. 0 이외의 우선 순위가 지정되었을 경우에 서비스 프로바이더가 우선 순위를 지원 하고 있지 않을 때, 또는 0 이외의 타임 아웃이 지정되었을 경우에 서비스 프로바이더가 이 옵션을 지원 하고 있지 않을 때는, DPERR_NOTSUPPORTED 를 돌려준다.

주의

DirectPlay 프로토콜이 세션 기술로 지정되고 있는 (DPSESSIONDESC2 구조체의 DPSESSION_DIRECTPLAYPROTOCOL 플래그를 설정하는 것으로써) 경우,SendEx 의 모든 옵션을 사용할 수 있다. 그 이외의 경우, 어플리케이션은 GetCaps 를 호출해 서비스 프로바이더로 이행 되고 있는 옵션을 판정할 필요가 있다. SendEx 는, 보증 첨부 메세지와 보증 없음 메세지의 양쪽 모두를 지원 하고 있다. 보증 첨부로 송신된 메세지는, 수신 측에서의 긍정 응답을 기다리고 있는 보류 상태의 메세지가 있어도 블록 되지 않는다.

메세지가 비동기에게 송신되었을 (DPSEND_ASYNC 플래그를 설정하는 것으로써) 경우, 그 메세지는 송신 큐로 설정되어,SendEx 함수는 곧바로 돌아온다. 시스템 메세지 (DPMSG_SENDCOMPLETE)가 송신측 플레이어의 수신 큐로 설정되어 그것에 의해 송신 결과가 나타난다.

메세지에 우선 순위를 설정할 수 있다. 메세지는, 송신되는 것을 대기하고 있는 메세지안에, 그것보다 우선 순위가 높은 메세지가 없고, 또 사용 가능한 대역폭이 있는 경우에 송신된다.

메세지의 타임 아웃을 지정할 수 있다. DirectPlay 가 지정된 시간내에 메세지를 전달할 수 없었던 경우, 그것은 삭제된다.

DPSESSION_NOPRESERVEORDER 플래그가 세션 기술 (DPSESSIONDESC2 )로 설정되어 있기 위해서(때문에), 보증 첨부 메세지의 배포 순서가 보관 유지되지 않는 경우, DPSEND_SIGNED 플래그나 DPSEND_ENCRYPTED 플래그를 사용할 수 없다.

다양한 우선 순위를 지정해 메세지를 송신했을 경우는, 서명이나 암호가 기능하지 않는다. 어플리케이션에서는, 기밀 보호 메세지의 우선 순위를 1 개로 결정해, 또 그 우선 순위에서만 시큐러티 플래그를 사용 하면이야 있고. 이것은, 기밀 보호 메세지의 검증이 그 수신 순서에 근거해 행해져 또 우선 순위를 설정 하면 그 순서가 변경될 가능성이 있기 때문에 있다.

DirectPlay 프로토콜은, 액티브한 경우, 송신 방향의 네트워크 트래픽을 억제하려고 한다. 즉, 반드시 할 수 있는 한 빠르게 패킷을 송신하는 것은 아니다. 그것은, 수신측 컴퓨터의 수신 방향의 대역폭에 영향을 주지 않는 범위에서 할 수 있는 한 빠르게 패킷을 송신한다.

서비스 프로바이더가 보증 첨부 메세지를 지원 하고 있어 어떤가에 관계없이, 또 DirectPlay 프로토콜 플래그를 설정해 있을지 어떨지에 관계없이, 시스템 메세지는 항상 보증 첨부로 송신된다. 보증 첨부 시스템 메세지를 송신 하면, DirectPlay 프로토콜이 자동적으로 사용된다.

시스템 메세지 이외로, 어플리케이션이 DirectPlay 프로토콜 플래그를 설정해, 메세지를 보증 첨부로 송신했을 (DPSEND_GUARANTEED 플래그를 설정하는 것으로써) 경우, 서비스 프로바이더가 보증 첨부 메세지를 지원 하고 있을지 어떨지에 관계없이, 그 메세지는 보증 첨부로 송신된다.

시스템 메세지 이외로, 어플리케이션이 DirectPlay 프로토콜 플래그를 설정하지 않고, 메세지를 보증 첨부로 송신했을 경우, 그 메세지는, 서비스 프로바이더가 보증 첨부 메세지를 지원 하고 있을 때 마셔 보증 첨부로 송신된다. 서비스 프로바이더가 그것을 지원 하고 있지 않는 경우, DPSEND_GUARANTEED 플래그에 관계없이, 메세지는 보증 첨부로 송신되지 않는다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::Send ,IDirectPlay4::CancelMessage ,IDirectPlay4::CancelPriority ,IDirectPlay4::GetMessageQueue ,DPMSG_SENDCOMPLETE


IDirectPlay4::SetGroupConnectionSettings

IDirectPlay4::SetGroupConnectionSettings 메소드는, 이그룹으로부터 기동되는세션의 접속 설정을 설정한다. 이 메소드는,로비 세션에서만 사용할 수 있다.

HRESULT SetGroupConnectionSettings(
  DWORD dwFlags,
  DPID idGroup,
  LPDPLCONNECTION lpConnection
);

파라미터

dwFlags
사용하지 않는다. 0 으로 설정해 둔다.
idGroup
접속 설정을 설정하는 그룹의 ID.
lpConnection
기동하는 어플리케이션, 사용하는서비스 프로바이더, 생성 하는 세션의 세션 기술을 기술한 DPLCONNECTION 구조체에의 포인터.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS
DPERR_UNSUPPORTED

주의

DPLCONNECTION 구조체의 멤버안에 디폴트값 (NULL 이외 또는 0 이외)이 이미 설정되어 있는 것이 있을지 어떨지를 조사하려면 ,SetGroupConnectionSettings 을 호출하기 전에 IDirectPlay4::GetGroupConnectionSettings 를 호출한다. 디폴트값이 설정되어 있는 경우에, 그것들을 변경하려고 하면(자), 에러가 돌려주어지는 일이 있다.

SetGroupConnectionSettings에 의해 DPLCONNECTION 구조체의 lpAddress 데이터 멤버나 dwAddressSize 데이터 멤버를 설정할 필요는 없다. DPLCONNECTION 구조 체내의 DPSESSIONDESC2 구조체의 guidInstance 멤버도 지정할 필요는 없다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

DPLCONNECTION ,IDirectPlayLobby3::RunApplication ,IDirectPlay4::GetGroupConnectionSettings


IDirectPlay4::SetGroupData

IDirectPlay4::SetGroupData 메소드는, 어플리케이션 고유의 데이터 블록을 그룹 ID 에 관련짓는다. 그룹에 관련지을 수 있었던 리모트 데이터를 변경할 수 있는 것은, 그것을 생성 한 컴퓨터뿐이다.

HRESULT SetGroupData(
  DPID idGroup,
  LPVOID lpData,
  DWORD dwDataSize,
  DWORD dwFlags
);

파라미터

idGroup
데이터를 설정하는 그룹 ID.
lpData
설정하는 데이터에의 포인터. 기존의 그룹 데이터를 클리어 하려면 , NULL 를 설정한다.
dwDataSize
데이터 버퍼의 사이즈. lpData 가 NULL 이며, 이 파라미터가 0 이 아닌 경우, 메소드는 DPERR_INVALIDPARAMS 를 돌려준다.
dwFlags
그룹 데이터의 전파 방법을 나타내는 플래그. 이 파라미터에 0 을 설정했을 경우, 리모트 그룹 데이터는 보증 없음 메세지 방식에서 설정 및 전파 된다.
DPSET_GUARANTEED
보증 첨부 메세지 방식 (가능한 경우)에 의해 데이터를 전파 한다. 이 플래그는, DPSET_REMOTE 에서만 사용할 수 있다.
DPSET_LOCAL
데이터는 로컬 밖에 사용되지 않고, 전파 되지 않는다.
DPSET_REMOTE
이 데이터는, 모든 어플리케이션에 의해 사용되므로, 세션내의 그 외 모든 어플리케이션에 전파 된다. 이 플래그는, 로컬 세션에 의해 소유되고 있는 그룹에서만 사용할 수 있다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS

주의

DirectPlay 에서는, 로컬과 리모트의 양쪽 모두의 그룹 데이터를 보수할 수 있다. 로컬 데이터는, 로컬 컴퓨터의 어플리케이션에서만 사용할 수 있다. 리모트 데이터는, 세션내의 그 외 모든 어플리케이션에 전파 된다. 세션 기술로 DPSESSION_NODATAMESSAGES 가 설정되어 있는 경우를 제외해, 모든 플레이어 (송신원의 플레이어를 포함한다)로 변경을 알리는 DPMSG_SETPLAYERORGROUPDATA 시스템 메세지가 송신된다. 리소스에의 포인터는, 로컬 데이터에 안전하게 보존할 수 있다. 그룹이 망가져도 로컬 데이터 블록은 사용할 수 있는 (DPMSG_DESTROYPLAYERORGROUP 시스템 메세지에 대해) 것으로, 어플리케이션은 그 리소스를 릴리즈 할 수 있다.

이 메소드를 사용 하면, 오바헷드가 생기므로, 리얼타임의 정보 (위치의 갱신등)를 갱신하는 경우는 사용하지 않는 것. IDirectPlay4::Send 가, 리얼타임의 정보를 갱신하기에는 유효하다. 또, 너무 빈번하게 변경되지 않고, 또 시간을 중시하지 않는 (팀의 특성 등) 공유 상태의 정보에 대해서는,IDirectPlay4::SetGroupData 가 보다 적합하다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

DPMSG_SETPLAYERORGROUPDATA ,IDirectPlay4::GetGroupData ,IDirectPlay4::Send


IDirectPlay4::SetGroupName

IDirectPlay4::SetGroupName 메소드는, 그룹의 생성 후에 그 이름을 설정한다. 그룹의 이름을 설정할 수 있는 것은, 그것을 생성 한 컴퓨터뿐이다. 세션 기술로 DPSESSION_NODATAMESSAGES 가 설정되어 있는 경우를 제외해, 그 외 모든 플레이어에게, 변경을 알리는 DPMSG_SETPLAYERORGROUPNAME 시스템 메세지가 송신된다.

HRESULT SetGroupName(
  DPID idGroup,
  LPDPNAME lpGroupName,
  DWORD dwFlags
);

파라미터

idGroup
이름을 설정하는 그룹 ID.
lpGroupName
그룹의 이름 정보가 저장 되고 있는 DPNAME 구조체에의 포인터. 그룹에 이름 정보가 없는 경우는, 이 파라미터에 NULL 를 설정한다.
dwFlags
이 파라미터에 0 을 설정했을 경우, 이름은, 보증 없음 메세지 방식에서 모든 리모트 시스템에 전파 된다. 이 값은, 로컬 세션에 의해 소유되고 있는 그룹에서만 사용할 수 있다.
DPSET_GUARANTEED
보증 첨부 메세지 방식 (가능한 경우)에 의해 데이터를 전파 한다.
DPSET_LOCAL
데이터는 로컬 밖에 사용되지 않고, 전파 되지 않는다.
DPSET_REMOTE
이 데이터는, 모든 어플리케이션에 의해 사용되므로, 세션내의 그 외 모든 어플리케이션에 전파 된다. 이 플래그는, 로컬 세션에 의해 소유되고 있는 그룹에서만 사용할 수 있다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

DPNAME ,DPMSG_SETPLAYERORGROUPNAME ,IDirectPlay4::GetGroupName ,IDirectPlay4::Send


IDirectPlay4::SetGroupOwner

IDirectPlay4::SetGroupOwner 메소드는,그룹의 소유자를 변경한다. 이 메소드는,로비 세션에서만 사용할 수 있다. DPMSG_SETGROUPOWNER 시스템 메세지가 생성된다.

HRESULT SetGroupOwner(
  DPID idGroup,
  DPID idOwner
);

파라미터

idGroup
소유자를 변경하는 그룹의 ID.
idOwner
그룹의 소유자로서 설정하는 플레이어의 ID.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_CONNECTIONLOST
DPERR_GENERIC
DPERR_INVALIDGROUP
DPERR_INVALIDPLAYER
DPERR_UNAVAILABLE

세션이로비 세션이 아닌 경우는,DPERR_UNAVAILABLE 를 돌려준다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::GetGroupOwner ,DPMSG_SETGROUPOWNER


IDirectPlay4::SetPlayerData

IDirectPlay4::SetPlayerData 메소드는, 어플리케이션 고유의 데이터 블록을 플레이어 ID 에 관련짓는다.

HRESULT SetPlayerData(
  DPID idPlayer,
  LPVOID lpData,
  DWORD dwDataSize,
  DWORD dwFlags
);

파라미터

idPlayer
데이터를 설정하는 플레이어의 ID.
lpData
설정하는 데이터에의 포인터. 기존의 플레이어 데이터를 클리어 하려면 , 이 파라미터에 NULL 를,dwDataSize 에 0 을 설정한다.
dwDataSize
데이터 버퍼의 사이즈. lpData 가 NULL 이며, 이 파라미터가 0 이 아닌 경우, 메소드는 DPERR_INVALIDPARAMS 를 돌려준다.
dwFlags
이 파라미터에 0 을 설정했을 경우, 리모트 플레이어 데이터는 보증 없음 메세지 방식에서 설정 및 전파 된다.
DPSET_GUARANTEED
보증 첨부 메세지 방식 (가능한 경우)에 의해 데이터를 전파 한다. 이 플래그는, DPSET_REMOTE 에서만 사용할 수 있다.
DPSET_LOCAL
이 데이터는 로컬 밖에 사용되지 않고, 전파 되지 않는다.
DPSET_REMOTE
이 데이터는, 모든 어플리케이션에 의해 사용되므로, 세션내의 그 외 모든 어플리케이션에 전파 된다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

주의

SetPlayerData 를 사용 하면, 오바헷드가 생기므로, 리얼타임의 정보 (위치의 갱신등)를 갱신하는 경우는 사용하지 않는 것. 이러한 처리에는,Send 가 유효하다. 또, 너무 빈번하게 변경되지 않고, 시간을 중시하지 않는 (플레이어의 이름 등) 공유 상태의 정보에 대해서는,SetPlayerData 가 적합하다.

DirectPlay 에서는, 로컬과 리모트의 양쪽 모두의 플레이어 데이터를 보수할 수 있다. 로컬 데이터는, 로컬 컴퓨터의 어플리케이션에서만 사용할 수 있다. 리모트 데이터는, 세션내의 그 외 모든 어플리케이션에 전파 된다. 리모트 플레이어의 플레이어 데이터를 설정하려고 하면(자),DPERR_ACCESSDENIED 가 돌려주어진다. 세션 기술로 DPSESSION_NODATAMESSAGES 가 설정되어 있는 경우를 제외해, 모든 플레이어 (송신원의 플레이어를 포함한다)에게, 변경을 알리는 DPMSG_SETPLAYERORGROUPDATA 시스템 메세지가 송신된다. 리소스에의 포인터는, 로컬 데이터에 보존하면 안전하다. 플레이어가 망가져도 로컬 데이터 블록은 사용할 수 있는 (DPMSG_DESTROYPLAYERORGROUP 시스템 메세지에 대해) 것으로, 어플리케이션은 그 리소스를 릴리즈 할 수 있다. 시스템 메세지의 리스트에 대해서는, 「시스템 메세지의 사용」을 참조할것.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

DPMSG_SETPLAYERORGROUPDATA ,IDirectPlay4::GetPlayerData ,IDirectPlay4::Send


IDirectPlay4::SetPlayerName

IDirectPlay4::SetPlayerName 메소드는, 로컬 플레이어의 생성 후에 그 이름을 설정한다. 플레이어의 이름을 설정할 수 있는 것은, 그것을 생성 한 컴퓨터뿐이다. 세션 기술로 DPSESSION_NODATAMESSAGES 가 설정되어 있는 경우를 제외해, 그 외 모든 플레이어에게, 변경을 알리는 DPMSG_SETPLAYERORGROUPNAME 시스템 메세지가 송신된다.

HRESULT SetPlayerName(
  DPID idPlayer,
  LPDPNAME lpPlayerName,
  DWORD dwFlags
);

파라미터

idPlayer
데이터를 송신하는 로컬 플레이어의 ID.
lpPlayerName
플레이어의 이름 정보가 저장 되고 있는 DPNAME 구조체에의 포인터. 플레이어에게 이름 정보가 없는 경우는, 이 파라미터에 NULL 를 설정한다.
dwFlags
이름의 전파 방법을 나타내는 플래그. 다음의 몇개의 값을 지정할 수 있다.
DPSET_GUARANTEED
보증 첨부 메세지 방식 (가능한 경우)에 의해 데이터를 전파 한다.
DPSET_LOCAL
데이터는 그 외의 플레이어에게 전파 되지 않는다.
DPSET_REMOTE
보증 없음 메세지 방식에서, 세션내의 모든 플레이어에게 데이터를 전파 한다. 이것이 디폴트값이다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_CONNECTIONLOST
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

DPNAME ,DPMSG_SETPLAYERORGROUPNAME ,IDirectPlay4::GetPlayerName ,IDirectPlay4::Send


IDirectPlay4::SetSessionDesc

IDirectPlay4::SetSessionDesc 메소드는, 현재 세션의 프로퍼티를 변경한다. 세션 프로퍼티를 변경할 수 있는 것은,세션의호스트 뿐이다. 호스트 이외로부터 이 메소드를 호출하려고 하면, DPERR_ACCESSDENIED 가 돌려주어진다.

갱신된 세션 기술이, 세션내의 그 외 모든 컴퓨터에 전파 된다. 각 플레이어에게는,DPMSG_SETSESSIONDESC 시스템 메세지가 송신된다.

SetSessionDesc 는,로비 세션에서는 사용할 수 없다.

HRESULT SetSessionDesc(
  LPDPSESSIONDESC2 lpSessDesc,
  DWORD dwFlags
);

파라미터

lpSessDesc
새로운 설정값이 저장 되고 있는 DPSESSIONDESC2 구조체에의 포인터.
dwFlags
현재, 이 메소드로 플래그는 사용되어 있지 않다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS

이 컴퓨터로 세션을 변경하는 권한이 없는 경우는, DPERR_ACCESSDENIED 를 돌려준다. 세션 프로퍼티를 변경할 수 있는 것은 호스트 뿐이다. 어플리케이션이 변경 불가능한 세션 기술의 프로퍼티를 변경하려고 했을 경우, 또는 프로퍼티에 무효인 값을 지정했을 경우는, DPERR_INVALIDPARAMS 를 돌려준다.

주의

세션 기술을 변경 하면,DPMSG_SETSESSIONDESC 시스템 메세지가 세션내의 그 외 모든 컴퓨터로 생성된다.

DPSESSIONDESC2 구조체의 다음의 멤버와 플래그는,IDirectPlay4::SetSessionDesc 를 사용해 변경할 수 있다.

dwFlags
DPSESSION_JOINDISABLED

DPSESSION_NEWPLAYERSDISABLED

DPSESSION_NODATAMESSAGES

DPSESSION_PRIVATE

dwMaxPlayers
최대 플레이어수에 현재의 플레이어수보다 적은 값을 설정 하면,DPERR_INVALIDPARAMS 가 돌려주어진다.
lpszSessionName / lpszSessionNameA
lpszPassword / lpszPasswordA
dwUser1
dwUser2
dwUser3
dwUser4

DPSESSIONDESC2 구조체의 다음의 멤버와 플래그가 변경되면(자), 에러가 발생한다 (예를 들어, DPSESSION_KEEPALIVE 플래그가 현재 설정 그런데 있는 경우에, 이 비트를 설정하려고 해도 에러는 발생하지 않지만, 그 비트를 클리어 하려고 하면(자) 에러가 발생해,IDirectPlay4::SetSessionDesc 는 실패한다).

dwSize
dwFlags
DPSESSION_NOMESSAGEID

DPSESSION_KEEPALIVE

DPSESSIONDESC2 구조체의 다음의 멤버는 무시된다 (즉, 이 멤버에 무엇을 지정해도, DirectPlay 는 반드시 IDirectPlay4::Open 가 불려 갔을 때에 건네받은 값을 사용한다).

guidInstance
guidApplication
dwCurrentPlayers
dwReserved1
dwReserved2

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

DPSESSIONDESC2 ,IDirectPlay4::GetSessionDesc


IDirectPlay4::StartSession

IDirectPlay4::StartSession 메소드는, staging 영역으로부터 DirectPlay 세션을 기동한다. 우선,SetGroupConnectionSettings 를 호출해 기동하는 어플리케이션, 사용하는서비스 프로바이더, 및 사용하는 세션 기술을 지정한다.

StartSession 가 불려 가면(자),그룹내의 각 플레이어는, 플레이어에게 세션을 기동하도록(듯이) 지시받은 DPMSG_STARTSESSION 를 수신한다.

HRESULT StartSession(
  DWORD dwFlags,
  DPID idGroup
);

파라미터

dwFlags
사용하지 않는다. 0 으로 설정해 둔다.
idGroup
세션 기동 커멘드를 송신하는 그룹의 ID. 그룹은, staging 영역이 아니면 안된다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS

지정된 그룹 ID 가 유효한 staging 영역이 아닌 경우는, DPERR_INVALIDGROUP 를 돌려준다.

주의

세션이 이미 기동되고 있는 staging 영역 그룹에 참가하는 플레이어는, 이 메소드를 호출하면 세션에 참가할 수 있다. 플레이어는, 세션에의 참가 방법을 지시한 DPMSG_STARTSESSION 메세지를 받아들인다.

IDirectPlay4::GetGroupConnectionSettings 를 호출해,DPLCONNECTION 구조체의 포인터를 개입시켜 DPSESSIONDESC2 구조체에 돌려주어지는 guidInstance 파라미터를 조사하면(자), 세션이 이미 처리되고 있는지 어떤지를 판정할 수 있다. guidInstance 가 GUID_NULL 의 경우, 처리중의 세션은 없다. 그 외의 값의 경우, 세션은 이미 처리되고 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

동기 기동


IDirectPlayLobby3

어플리케이션은,IDirectPlayLobby3 인터페이스의 각 메소드를 사용해, 어플리케이션이나 거기에 관련지을 수 있고 있는 데이터를 관리한다. 여기에서는,IDirectPlayLobby3 인터페이스의 각 메소드의 레퍼런스를 제공합니다.

IDirectPlayLobby3 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

주소 관리 | CreateAddress
 | CreateCompoundAddress
 | EnumAddress
 | EnumAddressTypes
어플리케이션 관리 | Connect
 | ConnectEx
 | EnumLocalApplications
 | RegisterApplication
 | RunApplication
 | UnregisterApplication
 | WaitForConnectionSettings
데이터 관리 | GetConnectionSettings
 | ReceiveLobbyMessage
 | SendLobbyMessage
 | SetConnectionSettings
 | SetLobbyMessageEvent

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.


IDirectPlayLobby3::Connect

IDirectPlayLobby3::Connect 메소드는, DirectPlayLobby 오브젝트로 현재 저장 되고 있는 DPLCONNECTION 구조체에 의해 지정된세션에 어플리케이션을 접속한다.

메모 이 메소드는,IDirectPlay2 또는 IDirectPlay2A 인터페이스를 돌려준다. 이것이 목적의 DirectPlay COM 인터페이스가 아닌 경우 (예를 들어,IDirectPlay4 또는 IDirectPlay4A), 어플리케이션은 QueryInterface 를 사용해 현재 인터페이스를 취득해, 이 인터페이스를 릴리즈 할 필요가 있다. 최신 메소드의 IDirectPlayLobby3::ConnectEx 를 사용 하면, 어플리케이션으로 돌려주어지는 DirectPlay COM 인터페이스를 지정할 수 있다.

Connect 는, 디폴트에서는, 접속된 후, 또는 접속이 마감 시간이 되었을 때에 돌아온다. DPCONNECT_RETURNSTATUS 플래그를 사용했을 경우,Connect 는 곧바로 돌아와, 그 때 접속이 처리중인 것을 나타내는 DPERR_CONNECTING 에러 코드가 돌려주어진다. 어플리케이션은, DP_OK 또는 장해 코드가 돌려주어질 때까지, 이 메소드를 정기적으로 계속 호출할 필요가 있다. 어플리케이션은,IDirectPlayLobby3 인터페이스를 릴리즈 하는 것으로 접속을 취소할 수가 있다.

HRESULT Connect(
  DWORD dwFlags,
  LPDIRECTPLAY2 *lplpDP,
  IUnknown FAR *pUnk
);

파라미터

dwFlags
접속 방법을 나타내는 플래그. 디폴트 (dwFlags = 0)에서는, 접속이 확립되는지, 또는 처리가 마감 시간이 되면(자), 메소드가 돌려주어진다.
DPCONNECT_RETURNSTATUS
메소드는 곧바로 돌아와, 그 때 접속의 스테이터스가 돌려주어진다. 어플리케이션은, 정상 종료를 나타내는 코드 또는 장해 코드가 돌려주어질 때까지,Connect 를 계속 호출할 필요가 있다.
lplpDP
IDirectPlay2(IDirectPlayLobby3 로 불려 갔을 경우) 또는 IDirectPlay2A(IDirectPlayLobby3A 로 불려 갔을 경우)의 몇개의 유효한 인터페이스에 의해 초기화된 포인터에의 포인터. 다만, 그 외의 인터페이스를 희망하는 경우는, 어플리케이션으로 QueryInterface 를 사용해 신규 인터페이스에의 포인터를 취득해, 그것을 릴리즈 하는 것. 혹은,ConnectEx 메소드를 사용해도 괜찮다.
pUnk
포함되어 있는 IUnknown 인터페이스에의 포인터. 이 파라미터는, 장래 COM 집합화 기능과 호환성을 취하기 위해서(때문에) 준비되어 있다. 다만, 현재는 이 파라미터에 NULL 이외의 값을 지정 하면 IDirectPlayLobby3::Connect 로부터 에러가 돌려주어진다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

CLASS_E_NOAGGREGATION
DPERR_CONNECTING
DPERR_INVALIDFLAGS
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOTLOBBIED
DPERR_OUTOFMEMORY

접속 처리가 실행되고 있는 동안은 DPERR_CONNECTING 를 돌려준다. 최신의 스테이터스를 취득하려면 , 메소드를 재차 호출한다.

주의

접속의 타임 아웃의 상한은 1 분이다.

이 메소드가 정상적으로 종료한 후는, 어플리케이션으로 IDirectPlay4::InitializeConnection ,IDirectPlay4::EnumSessions ,IDirectPlay4::Open 를 호출하는 처리를 생략 할 수 있다. 어플리케이션은 유저에게 이름을 문의하는 것이 아니라,DPLCONNECTION 구조체의 플레이어명 정보를 사용해 플레이어를 생성 한다.

어플리케이션은, 이 메소드를 호출하기 전에,IDirectPlayLobby3::GetConnectionSettings 메소드를 사용해 어플리케이션을 기동할 경우에 사용된 접속 설정을 조사할 수가 있다. 계속되어,IDirectPlayLobby3::SetConnectionSettings 메소드에 의해 그러한 설정값을 변경해, 설정할 수 있다. 다만, 적절한 세션 프로퍼티가 설정되어 있는 것을 확인하기 위해서,DPSESSIONDESC2 구조체, 특히 dwFlags,dwMaxPlayers,dwUser 멤버에 주의할 필요가 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlayLobby3::ConnectEx


IDirectPlayLobby3::ConnectEx

IDirectPlayLobby3::ConnectEx 메소드는, DirectPlayLobby 오브젝트로 현재 저장 되고 있는 DPLCONNECTION 구조체에 의해 지정된세션에 어플리케이션을 접속한다.

이 메소드는,Connect 메소드를 확장한 것이다. 이것을 사용 하면, 어플리케이션으로 돌려주어지는 DirectPlay\ COM 인터페이스의 버젼을 지정할 수 있다.

ConnectEx 는, 디폴트에서는, 접속된 후, 또는 접속이 마감 시간이 된 후에 돌아온다. DPCONNECT_RETURNSTATUS 플래그를 사용했을 경우,ConnectEx 는 곧바로 돌아와, 그 때 접속이 처리중인 것을 나타내는 DPERR_CONNECTING 에러 코드가 돌려주어진다. 어플리케이션은, DP_OK 또는 장해 코드가 돌려주어질 때까지, 이 메소드를 정기적으로 계속 호출할 필요가 있다. 어플리케이션은,IDirectPlayLobby3 인터페이스를 릴리즈 하는 것으로 접속을 취소할 수가 있다.

HRESULT ConnectEx(
  DWORD dwFlags,
  REFIID riid,
  LPVOID *lplpDP,
  IUnknown FAR *pUnk
);

파라미터

dwFlags
접속 방법을 나타내는 플래그. 디폴트 (dwFlags = 0)에서는, 접속이 확립되는지, 또는 처리가 마감 시간이 된 후, 메소드가 돌려주어진다.
DPCONNECT_RETURNSTATUS
메소드는 곧바로 돌아와, 그 때 접속의 스테이터스가 돌려주어진다. 어플리케이션은, 정상 종료를 나타내는 코드 또는 장해 코드가 돌려주어질 때까지,ConnectEx 를 계속 호출할 필요가 있다.
riid
돌려주어지는 특정의 DirectPlay COM 인터페이스의 IID. 예를 들어, IID_IDirectPlay4A 가 된다.
lplpDP
riid 파라미터에 의해 지정된 DirectPlay 인터페이스로 초기화된 포인터에의 포인터.
pUnk
포함되어 있는 IUnknown 인터페이스에의 포인터. 이 파라미터는, 장래 COM 집합화 기능과 호환성을 취하기 위해서(때문에) 준비되어 있다. 다만, 현재는 이 파라미터에 NULL 이외의 값을 지정 하면 IDirectPlayLobby3::ConnectEx 로부터 에러가 돌려주어진다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_CONNECTING
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS

접속 처리가 실행되고 있는 동안은 DPERR_CONNECTING 를 돌려준다. 최신의 스테이터스를 취득하려면 , 메소드를 재차 호출한다.

주의

접속의 타임 아웃의 상한은 1 분이다.

이 메소드인가 정상적으로 종료한 후는, 어플리케이션으로 IDirectPlay4::InitializeConnection ,IDirectPlay4::EnumSessions ,IDirectPlay4::Open 를 호출하는 처리를 생략 할 수 있다. 어플리케이션은 유저에게 이름을 문의하는 것이 아니라,DPLCONNECTION 구조체의 플레이어명 정보를 사용해 플레이어를 생성 한다.

어플리케이션은, 이 메소드를 호출하기 전에,IDirectPlayLobby3::GetConnectionSettings 메소드를 사용해 어플리케이션을 기동할 경우에 사용된 접속 설정을 조사할 수가 있다. 그리고,IDirectPlayLobby3::SetConnectionSettings 메소드에 의해 그러한 설정값을 변경해, 설정할 수 있다. 다만, 적절한 세션 프로퍼티가 설정되어 있는 것을 확인하기 위해서,DPSESSIONDESC2 구조체, 특히 dwFlags,dwMaxPlayers,dwUser 멤버에 주의할 필요가 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlayLobby3::ConnectEx

Built on 2000년 4월 13일


IDirectPlayLobby3::CreateAddress

IDirectPlayLobby3::CreateAddress 메소드는, 서비스 프로바이더에 고유의 네트워크 주소를 지정해 DirectPlay 주소를 생성 한다. 결과 출력된 주소에는,서비스 프로바이더의 글로벌 유니크 식별자 (GUID)와 서비스 프로바이더가 네트워크 주소로서 해석 가능한 데이터가 포함되어 있다.

다만,IDirectPlayLobby3::CreateCompoundAddress 에서는, 복수의 데이타체크를 사용해 주소를 사용할 수 있다. 그 때문에,IDirectPlayLobby3::CreateCompoundAddress 를 사용할 필요가 있다.

HRESULT CreateAddress(
  REFGUID guidSP,
  REFGUID guidDataType,
  LPCVOID lpData,
  DWORD dwDataSize,
  LPVOID lpAddress,
  LPDWORD lpdwAddressSize
);

파라미터

guidSP
서비스 프로바이더의 GUID 에의 포인터 (C++ 의 경우, 이것은 GUID 에의 레퍼런스이다).
guidDataType
사용되고 있는 특정의 네트워크 주소 타입을 식별하는 GUID 에의 포인터(C++ 의 경우, 이것은 GUID 에의 레퍼런스이다). 사전에 정의되고 있는 네트워크 주소 타입에 대해서는,DirectPlay 주소 를 참조할것.
lpData
특정의 네트워크 주소가 저장 되고 있는 버퍼에의 포인터.
dwDataSize
lpData 내의 네트워크 주소의 사이즈 (바이트 단위).
lpAddress
생성 한 DirectPlay 주소를 기입하는 버퍼에의 포인터.
lpdwAddressSize
DirectPlay address buffer의 사이즈가 저장 되고 있는 변수에의 포인터. 서비스 프로바이더는, 이 메소드를 호출하기 전에,lpdwAddressSize 를 버퍼의 사이즈에 초기화할 필요가 있다. 메소드가 돌아온 후, 이 파라미터에는 lpAddress 에 기입해진 바이트수가 설정되어 있다. 버퍼가 너무 작았을 경우 (DPERR_BUFFERTOOSMALL), 이 파라미터에는 DirectPlay 주소를 저장 하는데 필요한 사이즈가 설정되어 있다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_BUFFERTOOSMALL
DPERR_INVALIDPARAMS

주의

IDirectPlayLobby3::CreateCompoundAddress 메소드를 사용 하면,CreateAddress 로 허가되고 있는 것보다도 긴 DirectPlay 주소를 생성 할 수 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlayLobby3::EnumAddress ,IDirectPlayLobby3::CreateCompoundAddress ,DirectPlay 주소,DirectPlay 주소의 데이터형


IDirectPlayLobby3::CreateCompoundAddress

IDirectPlayLobby3::CreateCompoundAddress 메소드는, 개별의 데이타체크의 리스트로부터 DirectPlay 주소 를 생성 한다. 이 메소드를 사용 하면,IDirectPlayLobby3::CreateAddress 로 허가되고 있는 것보다도 긴 DirectPlay 주소를 생성 할 수 있다.

HRESULT CreateCompoundAddress(
  LPDPCOMPOUNDADDRESSELEMENT lpElements,
  DWORD dwElementCount,
  LPVOID lpAddress,
  LPDWORD lpdwAddressSize
);

파라미터

lpElements
DirectPlay 주소를 생성할 경우에 사용하는 DPCOMPOUNDADDRESSELEMENT 구조체의 배열의 선두 요소에의 포인터.
dwElementCount
lpElements 파라미터가 가리키고 있는 배열의 주소 요소의 수.
lpAddress
완전한 DirectPlay 주소를 기입하는 버퍼에의 포인터. 버퍼의 필요한 사이즈를 취득하는 경우는, NULL 를 지정한다.
lpdwAddressSize
lpAddress 버퍼의 사이즈가 저장 되는 DWORD 에의 포인터. DWORD 는, 버퍼에 실제로 카피된 바이트수를 나타내도록(듯이) 변경된다. 버퍼가 너무 작은 경우, 필요한 바이트수가 설정된다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_BUFFERTOOSMALL
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlayLobby3::CreateAddress ,IDirectPlayLobby3::EnumAddress ,DPCOMPOUNDADDRESSELEMENT ,DirectPlay 주소


IDirectPlayLobby3::EnumAddress

IDirectPlayLobby3::EnumAddress 메소드는,DirectPlay 주소 버퍼로부터 체크를 해석한다.

HRESULT EnumAddress(
  LPDPENUMADDRESSCALLBACK lpEnumAddressCallback,
  LPCVOID lpAddress,
  DWORD dwAddressSize,
  LPVOID lpContext
);

파라미터

lpEnumAddressCallback
DirectPlay 주소의 정보 체크 마다 호출하는 EnumAddressCallback 함수에의 포인터.
lpAddress
DirectPlay address buffer의 선두에의 포인터.
dwAddressSize
DirectPlay 주소의 사이즈.
lpContext
콜백 함수에 건네주는 문맥.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_EXCEPTION
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlayLobby3::CreateAddress ,DirectPlay 주소


IDirectPlayLobby3::EnumAddressTypes

IDirectPlayLobby3::EnumAddressTypes 메소드는, 특정의서비스 프로바이더가 DirectPlay 주소를 구축하는데 필요한 주소 타입을 모두 열거한다. 어플리케이션 또는 로비는, 이 정보를 사용해, 유저로부터 올바른 정보를 취득하거나 DirectPlay 주소를 생성 하거나 할 수가 있다.

HRESULT EnumAddressTypes(
  LPDPLENUMADDRESSTYPESCALLBACK lpEnumAddressTypeCallback,
  REFGUID guidSP,
  LPVOID lpContext,
  DWORD dwFlags
);

파라미터

lpEnumAddressTypeCallback
서비스 프로바이더의 주소 타입 마다 호출하는 EnumAddressTypeCallback 함수에의 포인터. 서비스 프로바이더로 주소 타입이 사용되지 않는 경우는, 콜백 함수는 불려 가지 않는다.
guidSP
열거하는 주소 타입의 서비스 프로바이더의 GUID 에의 포인터 (C++ 의 경우, 이것은 GUID 에의 레퍼런스이다).
lpContext
콜백 함수에 건네주는 문맥.
dwFlags
장래의 사용에 대비해 예약되고 있으므로, 0 으로 설정해 둔다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_EXCEPTION
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS

주의

EnumAddressTypes 를 사용 하면, 서비스 프로바이더가 유저에게 정보의 입력을 요구하는 다이알로그 박스를 표시할지 어떨지를 판정할 수 있다. 이 다이알로그 박스에는, IP 주소를 입력하도록(듯이) 요구하는 것등이 있다. 서비스 프로바이더로 주소 타입이 사용되지 않는 경우, 정보는 불필요해서, 다이알로그 박스는 표시되지 않는다.

어플리케이션은,IDirectPlay4::GetPlayerAddress 를 호출하면, 주소 타입으로서 선택 가능한 항목의 리스트를 취득할 수 있다. 이것은, 모뎀간 서비스 프로바이더에서만 사용할 수 있다. ANSI 캐릭터 라인 (최후가 NULL)인 DirectPlay 주소의 데이터형의 최후가 W 가 아닌 (예를 들어, DPAID_INet) 것에 대해, Unicode 캐릭터 라인 (최후가 NULL)인 DirectPlay 주소의 데이터형의 최후는 W 이다 (예를 들어, DPAID_INetW). 사전에 정의된 Microsoft 사의 데이터 타입의 리스트에 대해서는,DirectPlay 주소의 데이터형을 참조할것.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

DirectPlay 주소,IDirectPlayLobby3::CreateAddress


IDirectPlayLobby3::EnumLocalApplications

IDirectPlayLobby3::EnumLocalApplications 메소드는, DirectPlay 에 의해 등록된 어플리케이션을 열거한다.

IDirectPlayLobby3A(ANSI) 인터페이스로 이 메소드를 호출하면, 적절히 로컬라이즈 된 1 바이트 문자의 캐릭터 라인이 돌려주어진다. 멀티 바이트 문자의 캐릭터 라인은 사용되지 않기 때문에, 그것을 지원 하고 있지 않는 폰트를 사용해도 캐릭터 라인을 표시할 경우에 문제가 발생하지 않는다. IDirectPlayLobby3(Unicode) 인터페이스로 이 메소드를 호출하면, 로컬라이즈 된 와이드 문자의 기술이 돌려주어진다. 특별히 로컬라이즈 한 로비는, 이 메소드를 Unicode 인터페이스로 호출할 필요가 있다.

HRESULT EnumLocalApplications(
  LPDPENUMLOCALAPPLICATIONSCALLBACK lpEnumLocalAppCallback,
  LPVOID lpContext,
  DWORD dwFlags
);

파라미터

lpEnumLocalAppCallback
열거된 어플리케이션 마다 불려 가는 EnumLocalApplicationsCallback 함수에의 포인터.
lpContext
콜백 함수에 건네받는 문맥.
dwFlags
장래의 사용에 대비해 예약되고 있으므로, 0 으로 설정해 둔다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

DPLAPPINFO


IDirectPlayLobby3::GetConnectionSettings

IDirectPlayLobby3::GetConnectionSettings 메소드는, 어플리케이션을 기동해 접속하기 위해서 필요한 모든 정보가 저장 된 DPLCONNECTION 구조체를 취득한다. 돌려주어진 데이터는,로비 클라이언트에 의해 IDirectPlayLobby3::RunApplication 메소드에 건네받은 데이터나,IDirectPlayLobby3::SetConnectionSettings 메소드를 호출해 설정된 데이터와 같다.

HRESULT GetConnectionSettings(
  DWORD dwAppID,
  LPVOID lpData,
  LPDWORD lpdwDataSize
);

파라미터

dwAppID
(복수의 어플리케이션과 통신한다) 로비 클라이언트로부터 호출했을 때에 취득하는 어플리케이션의 접속 설정을 지정한다. (1 살의 로비 클라이언트라는 보고 통신한다) 어플리케이션으로부터 호출하면나무는, 이 파라미터는 0 이 아니면 안된다. 이 ID 번호는,IDirectPlayLobby3::RunApplication 로부터 취득한다.
lpData
접속 설정을 기입하는 버퍼에의 포인터. 데이터의 사이즈만을 요구 하면나무는, 이 파라미터에 NULL 를 설정한다. lpdwDataSize 파라미터는 데이터를 보관 유지하는데 최저한 필요한 사이즈로 설정된다.
lpdwDataSize
이 메소드를 호출하기 전에, 버퍼의 사이즈에 초기화된 변수에의 포인터. 메소드가 돌아오면(자), 이 파라미터에는 데이터의 사이즈가 바이트 단위로 설정되어 있다. 버퍼가 너무 작은 (DPERR_BUFFERTOOSMALL) 경우, 이 파라미터에는 최저한 필요한 버퍼의 사이즈가 설정된다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_BUFFERTOOSMALL
DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOTLOBBIED
DPERR_OUTOFMEMORY

주의

메소드가 돌아오면(자),lpData 멤버를 DPLCONNECTION 구조체에 캐스트 해, 데이터를 읽어낼 필요가 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

DPLCONNECTION ,IDirectPlayLobby3::RunApplication ,IDirectPlayLobby3::SetConnectionSettings ,IDirectPlayLobby3::WaitForConnectionSettings


IDirectPlayLobby3::ReceiveLobbyMessage

IDirectPlayLobby3::ReceiveLobbyMessage 메소드는,로비 클라이언트 어플리케이션과 DirectPlay 어플리케이션의 사이에 송신되는 메세지를 취득한다. 메세지는 큐로 설정되므로, 시간내에 읽어내지지 않아도 데이터가 없어져 버리는 위험성은 없다.

HRESULT ReceiveLobbyMessage(
  DWORD dwFlags,
  DWORD dwAppID,
  LPDWORD lpdwMessageFlags,
  LPVOID lpData,
  LPDWORD lpdwDataSize
);

파라미터

dwFlags
장래의 사용에 대비해 예약되고 있으므로, 0 으로 설정해 둔다.
dwAppID
(복수의 어플리케이션과 통신하고 있다) 로비 클라이언트로부터 호출했을 때에 취득하는 어플리케이션의 메세지를 지정한다. (1 살의 로비 클라이언트라는 보고 통신하고 있다) 어플리케이션으로부터 호출하면나무는, 이 파라미터는 0 이 아니면 안된다. 이 ID 번호는,IDirectPlayLobby3::RunApplication 메소드로부터 취득한다.
lpdwMessageFlags
돌려주어지는 메세지의 타입을 지정하는 플래그. 디폴트 (lpdwMessageFlags = 0)는, 메세지가 송신자에 의해 커스텀 정의된 것이라고 지정한다. 이 타입의 메세지의 처리는, 옵션이다. 수신자는, 송신측 어플리케이션의 식별 정보에 근거해 이 메세지를 해석할 필요가 있다. 로비는, 기동된 어플리케이션의 GUID 에 근거해 송신측 어플리케이션을 식별할 수 있다. 어플리케이션은, 식별 GUID 를 요구하는 표준 메세지를 로비에 송신하는 것으로, 로비를 식별할 필요가 있다.
DPLMSG_STANDARD
DirectPlay 에 의해 정의된 메세지이라고 지정한다. 이 타입의 메세지의 처리는, 옵션이다.
DPLMSG_SYSTEM
로비에 의해 기동된 어플리케이션의 스테이터스가 변경된 것을 그 로비에 통지할 경우에 사용되는 DirectPlay 에 의해 생성된 시스템 메세지이라고 지정한다.
lpData
메세지가 기입해지는 버퍼에의 포인터. 메세지의 사이즈만을 요구 하면나무는, 이 파라미터에 NULL 를 설정한다. lpdwDataSize 파라미터에는, 메세지를 보관 유지하는데 최저한 필요한 사이즈가 설정된다.
lpdwDataSize
이 메소드를 호출하기 전에, 버퍼의 사이즈에 초기화된 변수에의 포인터. 메소드가 돌아오면(자), 이 파라미터에는 메세지의 사이즈가 바이트 단위로 설정되어 있다. 버퍼가 너무 작은 (DPERR_BUFFERTOOSMALL) 경우, 이 파라미터에는 최저한 필요한 버퍼의 사이즈가 설정된다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_APPNOTSTARTED
DPERR_BUFFERTOOSMALL
DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOMESSAGES
DPERR_OUTOFMEMORY

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlayLobby3::RunApplication ,IDirectPlayLobby3::SendLobbyMessage


IDirectPlayLobby3::RegisterApplication

IDirectPlayLobby3::RegisterApplication 메소드는, DirectPlay 에 의해로비 어웨어 어플리케이션을 등록한다. DirectPlay 로비로부터의 기동이 가능한 것 같게, 어플리케이션을 등록할 필요가 있다.

어플리케이션의 등록은 1 번만 행할 필요가 있다. 또, 어플리케이션에서는, 언인스톨되었을 때에 등록을 해제할 필요가 있다 (IDirectPlayLobby3::UnregisterApplication 를 참조할것).

HRESULT RegisterApplication(
  DWORD  dwFlags,
  LPVOID lpAppDesc
);

파라미터

dwFlags
장래의 사용에 대비해 예약되고 있으므로, 0 으로 설정해 둔다.
lpAppDesc
어플리케이션의 모든 등록값에 의해 설정된 DPAPPLICATIONDESC 구조체 또는 DPAPPLICATIONDESC2 구조체에의 포인터.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlayLobby3::UnregisterApplication ,DirectXRegisterApplication


IDirectPlayLobby3::RunApplication

IDirectPlayLobby3::RunApplication 메소드는, 어플리케이션을 기동해, 그것을 세션에 접속하기 위해서 필요한 모든 정보를 그 어플리케이션에 건네준다. 이 메소드는,로비 클라이언트에 의해 사용된다.

HRESULT RunApplication(
  DWORD dwFlags,
  LPDWORD lpdwAppID,
  LPDPLCONNECTION lpConn,
  HANDLE hReceiveEvent
);

파라미터

dwFlags
장래의 사용에 대비해 예약되고 있으므로, 0 으로 설정해 둔다.
lpdwAppID
기동된 어플리케이션을 식별하는 ID 가 설정되는 변수에의 포인터. 로비 클라이언트는,IDirectPlayLobby3::SendLobbyMessage 메소드나 IDirectPlayLobby3::ReceiveLobbyMessage 메소드를 호출하면나무에 사용하기 위해서, 이 어플리케이션 ID 를 보존해 둘 필요가 있다.
lpConn
기동하는 어플리케이션이나, 유저 다이알로그 박스를 표시하지 않고세션 인스턴스에 그 어플리케이션을 접속하는 방법을 지정하는데 필요한 정보가 모두 저장 된 DPLCONNECTION 구조체에의 포인터.
hReceiveEvent
로비 메세지가 수신되었을 때에 설정되는 동기 이벤트를 지정한다. 이 이벤트는,IDirectPlayLobby3::SetLobbyMessageEvent 메소드를 사용 하면, 다음에 변경할 수 있다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_CANTCREATEPROCESS
DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY
DPERR_UNKNOWNAPPLICATION

주의

이 메소드는, 어플리케이션 프로세스가 생성 된 다음에 돌아온다. 로비 클라이언트는, 어플리케이션의 스테이터스를 나타내는 시스템 메세지를 받아들인다. 로비 클라이언트가 세션의 호스트인 어플리케이션을 기동하고 있는 경우, 세션에 참가하는 그 외의 어플리케이션을 기동 하면나무는, DPLSYS_DPLAYCONNECTSUCCEEDED 시스템 메세지를 받아들일 때까지 기다리고 나서 처리를 실시한다. 어플리케이션이 세션을 생성 하거나 참가하거나 할 수 없는 경우는, DPLSYS_DPLAYCONNECTFAILED 메세지가 생성된다. 또 로비 클라이언트는, 어플리케이션이 접속 설정을 읽어냈을 때는 DPLSYS_CONNECTIONSETTINGSREAD 시스템 메세지를, 어플리케이션이 종료했을 때는 DPLSYS_APPTERMINATED 시스템 메세지를 받아들인다.

로비 클라이언트가 DPLSYS_CONNECTIONSETTINGSREAD 시스템 메세지를 받아들이기 전에, 그 IDirectPlayLobby3 인터페이스를 릴리즈 하지 않는 것은 중요하다. 로비 클라이언트는, 메세지를 수신할 때까지 IDirectPlayLobby3::ReceiveLobbyMessage 를 루프 처리로 체크하는 일도, 동기 이벤트를 지정할 수도 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlayLobby3::ReceiveLobbyMessage ,IDirectPlayLobby3::GetConnectionSettings , ,IDirectPlayLobby3::SetLobbyMessageEvent


IDirectPlayLobby3::SendLobbyMessage

IDirectPlayLobby3::SendLobbyMessage 메소드는, 어플리케이션과 로비 클라이언트의 사이에 메세지를 송신한다.

HRESULT SendLobbyMessage(
  DWORD dwFlags,
  DWORD dwAppID,
  LPVOID lpData,
  DWORD dwDataSize
);

파라미터

dwFlags
송신하는 메세지의 타입을 나타내는 플래그. 디폴트 (dwFlags = 0)는, 송신원어플리케이션에 의해 정의된 커스텀 메세지이다. 다음에, 그 외의 값을 나타낸다.
DPLMSG_STANDARD
DirectPlay 에 의해 정의된 표준의 메세지.
dwAppID
(복수의 어플리케이션과 통신하고 있다) 로비 클라이언트로부터 호출했을 때에 메세지를 송신하는 어플리케이션을 지정한다. (1 살의 로비 클라이언트라는 보고 통신하고 있다) 어플리케이션으로부터 호출하면나무는, 이 파라미터는 0 이 아니면 안된다. 이 ID 는,IDirectPlayLobby3::RunApplication 메소드를 사용해 취득한다.
lpData
송신하는 메세지가 저장 되고 있는 버퍼에의 포인터.
dwDataSize
버퍼의 사이즈 (바이트 단위).

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_APPNOTSTARTED
DPERR_BUFFERTOOLARGE
DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY
DPERR_TIMEOUT

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlayLobby3::RunApplication ,IDirectPlayLobby3::ReceiveLobbyMessage ,DPLMSG_SETPROPERTY ,DPLMSG_SETPROPERTYRESPONSE ,DPLMSG_GETPROPERTY ,DPLMSG_GETPROPERTYRESPONSE ,


IDirectPlayLobby3::SetConnectionSettings

IDirectPlayLobby3::SetConnectionSettings 메소드는, 어플리케이션을 기동 및 접속할 경우에 사용하는 설정값을 변경한다.

HRESULT SetConnectionSettings(
  DWORD dwFlags,
  DWORD dwAppID,
  LPDPLCONNECTION lpConn
);

파라미터

dwFlags
장래의 사용에 대비해 예약되고 있으므로, 0 으로 설정해 둔다.
dwAppID
(복수의 어플리케이션과 통신하고 있다) 로비 클라이언트로부터 호출하면 와, 이 파라미터는 설정하는 어플리케이션의 접속 설정을 지정한다. (1 살의 로비 클라이언트라는 보고 통신하고 있다) 어플리케이션으로부터 호출하면나무는, 이 파라미터는 0 이 아니면 안된다. 이 ID 는,IDirectPlayLobby3::RunApplication 메소드를 사용해 취득한다.
lpConn
기동하는 어플리케이션이나, 유저 다이알로그 박스를 표시하지 않고 그 어플리케이션을 세션 인스턴스에 접속하는 방법을 지정하는데 필요한 정보가 모두 저장 된 DPLCONNECTION 구조체에의 포인터.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlayLobby3::GetConnectionSettings


IDirectPlayLobby3::SetLobbyMessageEvent

IDirectPlayLobby3::SetLobbyMessageEvent 메소드는, 로비 메세지를 수신했을 때에 설정되는 이벤트를 등록한다. 어플리케이션은, 메세지와 동기를 잡을 필요가 있는 경우, 이 메소드를 호출하지 않으면 안 된다. 로비 클라이언트는, 이 메소드를 호출하면,IDirectPlayLobby3::RunApplication 메소드에의 호출로 지정된 이벤트를 변경할 수 있다.

HRESULT SetLobbyMessageEvent(
  DWORD dwFlags,
  DWORD dwAppID,
  HANDLE hReceiveEvent
);

파라미터

dwFlags
장래의 사용에 대비해 예약되고 있으므로, 0 으로 설정해 둔다.
dwAppID
(복수의 어플리케이션과 통신하고 있다) 로비 클라이언트로부터 호출하면 와, 이벤트를 관련지을 수 있었던 어플리케이션을 지정한다. (1 살의 로비 클라이언트라는 보고 통신하고 있다) 어플리케이션으로부터 호출하면나무는, 이 파라미터는 0 이 아니면 안된다. 이 ID 번호는,IDirectPlayLobby3::RunApplication 메소드로부터 취득한다.
hReceiveEvent
메세지를 수신했을 때에 설정되는 이벤트 핸들.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlayLobby3::ReceiveLobbyMessage ,IDirectPlayLobby3::SendLobbyMessage


IDirectPlayLobby3::UnregisterApplication

IDirectPlayLobby3::UnregisterApplication 메소드는, DirectPlay 어플리케이션의 등록 엔트리를 삭제한다. 어플리케이션을 언인스톨하면(자), 이 엔트리를 삭제할 필요가 있다.

HRESULT UnregisterApplication(
  DWORD dwFlags,
  REFGUID guidApplication
);

파라미터

dwFlags
장래의 사용에 대비해 예약되고 있으므로, 0 으로 설정해 둔다.
guidApplication
레지스트리로부터 삭제하는 어플리케이션의 글로벌 유니크 식별자 (GUID). C 언어의 경우, 이 파라미터는 GUID 에의 포인터이다. C++ 언어의 경우, 이것은 GUID 에의 레퍼런스이다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_UNKNOWNAPPLICATION

어플리케이션의 GUID 가 레지스트리내에 없는 경우는, DPERR_UNKNOWNAPPLICATION 를 돌려준다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlayLobby3::RegisterApplication ,DirectXUnregisterApplication


IDirectPlayLobby3::WaitForConnectionSettings

IDirectPlayLobby3::WaitForConnectionSettings 메소드는, 어플리케이션을 대기 모드로 설정한다. 이 모드에서는, 어플리케이션은 접속 설정이 송신되는 것을 대기한다. 어플리케이션이 대기 모드 때,RunApplication 를 사용하고 있는 로비 클라이언트는 새로운 어플리케이션의 인스턴스를 기동하지 않고, 이미 대기 모드로 실행되고 있는 어플리케이션에 접속 설정을 직접 송신한다.

어플리케이션은, 대기 모드 때, DPLSYS_NEWCONNECTIONSETTINGS 시스템 메세지가 송신되고 있는지 어떤지를 폴링 할 필요가 있다. 어플리케이션은, 이 메세지를 수신 하면, 자동적으로 대기 모드를 종료한다. 어플리케이션은,ConnectEx 를 사용해 세션에 접속할 수 있다.

HRESULT WaitForConnectionSettings(
  DWORD dwFlags
);

파라미터

dwFlags
어플리케이션을 대기 모드로 설정하거나 대기 모드를 종료시키는 플래그. 디폴트 (dwFlags = 0)에서는, 메소드는 어플리케이션을 대기 모드로 설정한다. dwFlags 에 DPLWAIT_CANCEL 를 설정 하면, 어플리케이션은 대기 모드를 종료한다. 로비 클라이언트에 의해 접속 설정이 송신되자마자, 어플리케이션은 대기 모드를 종료한다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_INVALIDFLAGS
DPERR_UNAVAILABLE

대기 모드를 취소하도록(듯이) 플래그를 설정해 있어, 어플리케이션이 대기 모드가 아닌 경우는, DPERR_UNAVAILABLE 를 돌려준다.

주의

로비 클라이언트가 RunApplication 를 사용 하면, DirectPlay 는 접속 설정이 송신되는 것을 기다리고 있는 어플리케이션의 인스턴스를 검색한다. 그러한 인스턴스가 발견되지 않는 경우는, 새로운 어플리케이션의 인스턴스가 기동된다. 대기중의 어플리케이션인가 발견되었을 경우, DirectPlay 는 DPLSYS_NEWCONNECTIONSETTINGS 시스템 메세지를 송신한다. 어플리케이션은,GetConnectionSettings 에 의해 접속 설정을 읽기,ConnectEx 를 사용해 세션에 참가할 수가 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.


함수

다음에, DirectPlay 의 함수를 나타낸다.

  • DirectPlayCreate . 이 함수는 사용되어 있지 않기 때문에 주의 해야 한다. 대신에,CoCreateInstance 를 사용하는 것을 추천 한다.
  • DirectPlayEnumerate . 이 함수는 사용되어 있지 않기 때문에 주의 해야 한다. 대신에,IDirectPlay4::EnumConnections 를 사용하는 것을 추천 한다.
  • DirectPlayLobbyCreate


DirectPlayCreate

이 함수는 이제 사용되어 있지 않지만, DirectX 3 을 사용해 생성 된 어플리케이션과의 호환성을 유지하기 위해서(때문에) 남아 있다. 어플리케이션으로 목적의 DirectPlay 인터페이스를 생성 하면나무는 CoCreateInstance 를 직접 사용하는 것을 추천 한다. CoCreateInstance 를 사용 하면,IDirectPlay 인터페이스를 취득해,QueryInterface 에 의해 IDirectPlay4 인터페이스에 액세스 해,IDirectPlay 인터페이스를 릴리즈 하지 않아도 IDirectPlay4 인터페이스를 직접 취득할 수 있다.

DirectPlayCreate 함수는, 새로운 DirectPlay 오브젝트를 생성 해,IDirectPlay 인터페이스 포인터를 취득한다. 어플리케이션으로 lpGUIDSP 파라미터에 GUID_NULL 가 지정되었을 경우, 이 함수는, DirectPlay 오브젝트는 생성 하지만, 서비스 프로바이더는 초기화하지 않는다. 어플리케이션은,IDirectPlay4::InitializeConnection 메소드를 호출해서비스 프로바이더 또는로비 프로바이더를 초기화한다.

어플리케이션은, 서비스 프로바이더의 GUID (DirectPlayEnumerate 를 참조할것)를 지정해, 바인드 하는 서비스 프로바이더를 지정할 수 있다.

최신의 DirectPlay 기능을 사용하기 위해서, 어플리케이션은 QueryInterface 메소드를 사용해 IDirectPlay4 또는 IDirectPlay4A 인터페이스 포인터를 취득할 필요가 있다.

HRESULT WINAPI DirectPlayCreate(
  LPGUID lpGUIDSP,
  LPDIRECTPLAY FAR *lplpDP,
  IUnknown *lpUnk
);

파라미터

lpGUIDSP
DirectPlay 오브젝트를 초기화할 경우에 사용하는 서비스 프로바이더의 GUID 에의 포인터. 초기화하지 않고 DirectPlay 오브젝트를 생성 하려면 , GUID_NULL 에의 포인터를 건네준다.
lplpDP
유효한 IDirectPlay 인터페이스에 의해 초기화하는 인터페이스 포인터에의 포인터. 어플리케이션에서는,QueryInterface 메소드를 사용해,IDirectPlay2,IDirectPlay4 인터페이스 (UNICODE 캐릭터 라인), 또는 IDirectPlay2A,IDirectPlay4A 인터페이스 (ANSI 캐릭터 라인)를 취득할 필요가 있다.
lpUnk
포함되어 있는 IUnknown 에의 포인터. 이 파라미터는, 장래 COM 집합화 기능과 호환성을 취하기 위해서(때문에) 준비되어 있다. 다만, 현재는 이 파라미터에 NULL 이외의 값을 지정 하면 DirectPlayCreate 로부터 에러가 돌려주어진다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

CLASS_E_NOAGGREGATION
DPERR_EXCEPTION
DPERR_INVALIDPARAMS
DPERR_UNAVAILABLE

DirectPlay 오브젝트를 생성 할 수 없었던 경우는, DPERR_UNAVAILABLE 를 돌려준다. 지정된 GUID 가 무효인 경우는, DPERR_INVALIDPARAMS 를 돌려준다.

주의

이 함수는, DirectPlay 오브젝트를 초기화해, 그것이 성공했을 경우는 그 오브젝트에의 포인터를 설정하려고 한다. 어플리케이션은, 사용 가능한 서비스 프로바이더의 타입을 판정하기 위해서, 초기화 처리의 직전에 DirectPlayEnumerate 함수를 호출한다 (DirectPlayEnumerate 함수에 의해 DirectPlayCreate 의 lpGUIDSP 파라미터가 설정된다).

이 함수는,IDirectPlay 인터페이스에의 포인터를 돌려준다. 현재 인터페이스는,IDirectPlay4 와 IDirectPlay4A 이며, 이것들은 이 IDirectPlay 인터페이스로 QueryInterface 메소드를 호출해 취득할 필요가 있다. 상세한 것에 대하여는,DirectPlay 인터페이스의 개요를 참조할것.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::InitializeConnection ,DirectPlayEnumerate


DirectPlayEnumerate

DirectPlayEnumerate 함수는, 시스템에 인스톨 되고 있는 DirectPlay 서비스 프로바이더를 열거한다.

이 함수는 이제 사용되어 있지 않지만, DirectX 3 을 사용해 생성 된 어플리케이션과의 호환성을 유지하기 위해서(때문에) 남아 있다. 이것은, 서비스 프로바이더만을 열거해,DirectPlay 주소 (접속)는 열거하지 않는다. IDirectPlay4 인터페이스를 생성 한 다음에 어플리케이션으로 사용 가능한 접속을 모두 열거 하면나무는, 어플리케이션으로 IDirectPlay4::EnumConnections 메소드를 사용하는 것을 추천 한다.

이 함수는, 레지스트리의 Enumerate 값에 0 이 설정되어 있는 서비스 프로바이더는 열거하지 않는다. 전의 버젼과의 호환성을 유지하기 (위해)때문에,"서비스 프로바이더" 레지스트리 키로 등록되어 있는 서비스 프로바이더를 1 개만 돌려준다.

HRESULT WINAPI DirectPlayEnumerate(
  LPDPENUMDPCALLBACK lpEnumCallback,
  LPVOID lpContext
);

파라미터

lpEnumCallback
시스템에 인스톨 되고 있는 각 DirectPlay 서비스 프로바이더의 기술을 사용해 호출하는 콜백 함수에의 포인터. UNICODE 가 정의되고 있는지 어떤지에 의해, 콜백 함수의 prototype는 서비스 프로바이더명의 lpSPName 를 LPWSTR(Unicode 의 경우) 또는 LPSTR(ANSI 의 경우)로서 정의한다.
lpContext
함수가 불려 갈 때마다, 콜백 함수에게 건네지는 어플리케이션에 의해 정의된 구조체에의 포인터.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

DPERR_EXCEPTION
DPERR_GENERIC
DPERR_INVALIDPARAMS

무효인 열거 콜백 함수가 지정되었을 경우는, DPERR_INVALIDPARAMS 를 돌려준다.

주의

이 함수는, 시스템이 거기에 인스톨 된 서비스 프로바이더를 사용할 수 없어도, 그것들을 열거한다. 예를 들어, 시스템으로 모뎀이 인스톨되어 있지 않아도, TAPI 서비스 프로바이더는 열거된다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.

참조

IDirectPlay4::EnumConnections ,DirectPlayCreate


DirectPlayLobbyCreate

DirectPlayLobbyCreate 함수는, DirectPlayLobby 오브젝트의 인스턴스를 생성 해,IDirectPlayLobby 인터페이스에의 포인터를 돌려준다.

HRESULT WINAPI DirectPlayLobbyCreate(
  LPGUID lpGUIDSP,
  LPDIRECTPLAYLOBBY *lplpDPL,
  IUnknown *lpUnk,
  LPVOID lpData,
  DWORD dwDataSize
);

파라미터

lpGUIDSP
장래의 사용에 대비해 예약되고 있으므로, NULL 로 설정해 둔다.
lplpDPL
유효한 IDirectPlayLobby 인터페이스에 의해 초기화된 포인터에의 포인터. IDirectPlayLobby3 인터페이스를 취득하려면 , 이 함수를 사용해 IDirectPlayLobby 인터페이스를 취득하고 나서, 다음과 같이 QueryInterface 를 호출한다.
IDirectPlayLobby->QueryInterface( IID_IDirectPlayLobby3,
        (LPVOID*) &lpDP2 );
lpUnk
포함되어 있는 IUnknown 인터페이스에의 포인터. 이 파라미터는, 장래 COM 집합화 기능과 호환성을 취하기 위해서(때문에) 준비되어 있다. 다만, 현재는 이 파라미터에 NULL 이외의 값을 지정 하면 DirectPlayLobbyCreate 로부터 에러가 돌려주어진다.
lpData
DirectPlayLobby 오브젝트를 생성 하는데 필요한 여분의 데이터. 이 파라미터에는 NULL 를 설정해 둔다.
dwDataSize
이 파라미터에는, 0 을 설정해 둔다.

반환값

성공했을 경우는 DP_OK 를 돌려준다. 실패했을 경우는, 다음의 에러값의 어느쪽이든을 돌려준다.

CLASS_E_NOAGGREGATION
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.


콜백 함수

다음에, DirectPlay 의 콜백 함수를 나타낸다.

  • EnumAddressCallback
  • EnumAddressTypeCallback
  • EnumConnectionsCallback
  • EnumDPCallback
  • EnumLocalApplicationsCallback
  • EnumPlayersCallback2
  • EnumSessionsCallback2


EnumAddressCallback

EnumAddressCallback 는,IDirectPlayLobby3::EnumAddress 메소드에 대한 어플리케이션 정의의 콜백 함수이다.

BOOL FAR PASCAL EnumAddressCallback(
  REFGUID guidDataType,
  DWORD dwDataSize,
  LPCVOID lpData,
  LPVOID lpContext
);

파라미터

guidDataType
이 데이타체크의 타입을 나타내는 글로벌 유니크 식별자 (GUID)에의 포인터. 예를 들어, 이 파라미터에는 &DPAID_Phone 나 &DPAID_INet 가 설정된다 (C++ 의 경우, 이것은 GUID 에의 레퍼런스이다).
dwDataSize
데이타체크의 사이즈 (바이트 단위).
lpData
정수 데이터에의 포인터.
lpContext
콜백 함수에 건네주는 문맥.

반환값

열거를 계속하는 경우는, TRUE 를 돌려준다. 열거를 정지하는 경우는, FALSE 를 돌려준다.

주의

서비스 프로바이더는,guidDataType 파라미터의 GUID 를 조사해,lpData 로 지정된 값을 처리 또는 보존한다. guidDataType 로 인식되어 있지 않은 값은, 무시해도 괜찮다.

콜백 함수로 돌려주어지는 포인터는 일시적인 것이며, 콜백 함수의 내부에서만 유효하다. 어플리케이션에서는, 포인터 정보를 보존할 필요가 있는 경우, 데이터를 보관 유지하기 위한 메모리를 할당해 데이터를 카피하고 나서, 이 새로운 데이터에의 포인터를 보존할 필요가 있다. 이 함수로,lpData 는 일시적인 것이다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.


EnumAddressTypeCallback

EnumAddressTypeCallback 은,IDirectPlayLobby3::EnumAddressTypes 메소드에 대한 어플리케이션 정의의 콜백 함수이다.

BOOL FAR PASCAL EnumAddressTypeCallback(
  REFGUID guidDataType,
  LPVOID lpContext,
  DWORD dwFlags
);

파라미터

guidDataType
주소 타입을 나타내는 글로벌 유니크 식별자 (GUID)에의 포인터 (C++ 의 경우, 이것은 GUID 에의 레퍼런스이다). 사전에 정의되고 있는 주소 타입은, DPAID_Phone, DPAID_INet, DPAID_ComPort 이다. 이러한 주소 타입의 상세한 것에 대하여는,DirectPlay 주소를 참조할것.
lpContext
콜백 함수에 건네주는 문맥.
dwFlags
장래의 사용에 대비해 예약되고 있으므로, 사용하지 않는 것.

반환값

열거를 계속하는 경우는, TRUE 를 돌려준다. 열거를 정지하는 경우는, FALSE 를 돌려준다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Requires Windows 98.
헤더 : dplay.h 로 선언.


EnumConnectionsCallback

EnumConnectionsCallback 는,IDirectPlay4::EnumConnections 메소드에 대한 어플리케이션 정의의 콜백 함수이다.

BOOL FAR PASCAL EnumConnectionsCallback(
  LPCGUID lpguidSP,
  LPVOID lpConnection,
  DWORD dwConnectionSize,
  LPCDPNAME lpName,
  DWORD dwFlags,
  LPVOID lpContext
);

파라미터

lpguidSP
접속에 관련지을 수 있었던 DirectPlay 서비스 프로바이더 또는로비 프로바이더의 GUID. 이 GUID 를 사용 하면, 열거의 순서나 이름을 사용하지 않아도, 서비스 프로바이더나 로비 프로바이더를 일의에 식별할 수 있다.
lpConnection
접속이 저장 되고 있는 버퍼에의 읽기 전용 포인터. 이 파라미터는, DirectPlay 오브젝트를 초기화하기 위해서 IDirectPlay4::InitializeConnection 메소드에게 건네진다. 이 버퍼에는,DirectPlay 주소가 저장 되고 있다.
dwConnectionSize
lpConnection 버퍼의 사이즈 (바이트 단위).
lpName
DPNAME 구조체에의 읽기 전용 포인터. 이 구조체에는, 유저에게 표시하는 접속의 단축명이 저장 되고 있다.

ANSI 인터페이스로 IDirectPlay4::EnumConnections 를 호출하는 경우는, 캐릭터 라인을 ANSI 로서 참조할것. Unicode 인터페이스로 EnumConnections 를 호출하는 경우는, 캐릭터 라인을 Unicode 로서 참조할것.

dwFlags
접속의 타입을 나타내는 플래그. EnumConnections 에게 건네지는 dwFlags 와 등가이다.
lpContext
어플리케이션에 의해 정의된 문맥에의 포인터.

반환값

열거를 계속하는 경우는, TRUE 를 돌려준다. 열거를 정지하는 경우는, FALSE 를 돌려준다.

주의

어플리케이션은,IDirectPlay4::EnumConnections 메소드를 사용하기 위해서, 이 함수를 이행 할 필요가 있다. 이 함수는, 열거된 접속 마다 1 회씩 불려 간다.

어플리케이션은, 유저에게 표시하거나IDirectPlay4::InitializeConnection 메소드로 사용하기 위해서, 메모리를 할당해 각 접속을 카피한다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::EnumConnections ,IDirectPlay4::InitializeConnection


EnumDPCallback

EnumDPCallback 은,DirectPlayEnumerate 함수에 대해서 어플리케이션에 의해 정의된 콜백 함수이다. UNICODE 가 정의되고 있는지 어떤지에 의해, 콜백 함수의 prototype는 lpSPName 를 LPWSTR 형 (Unicode 의 경우) 또는 LPSTR 형 (ANSI 의 경우)의 어느쪽이든으로서 정의한다.

BOOL FAR PASCAL EnumDPCallback(
  LPGUID lpguidSP,
  LPSTR/LPWSTR lpSPName,
  DWORD dwMajorVersion,
  DWORD dwMinorVersion,
  LPVOID lpContext
);

파라미터

lpguidSP
DirectPlay 서비스 프로바이더의 일의의 식별자에의 포인터.
lpSPName
드라이버의 기술이 저장 되고 있는 캐릭터 라인에의 포인터. UNICODE 심볼이 정의되고 있는지 어떤지에 의해, 파라미터는 LPWSTR 형 (Unicode) 또는 LPSTR 형 (ANSI)의 언젠가된다.
dwMajorVersion 및 dwMinorVersion
드라이버의 메이저 버젼과 마이너 버젼.
lpContext
어플리케이션에 의해 정의된 문맥에의 포인터.

반환값

열거를 계속하는 경우는, TRUE 를 돌려준다. 열거를 정지하는 경우는, FALSE 를 돌려준다.

주의

콜백 함수로 돌려주어지는 포인터는 일시적인 것이며, 콜백 함수의 내부에서만 유효하다. 어플리케이션은, 포인터 정보를 보존할 필요가 있는 경우, 데이터를 보관 유지하기 위한 메모리를 할당해 데이터를 카피하고 나서, 이 새로운 데이터에의 포인터를 보존할 필요가 있다. 이 함수로,lpguidSP 와 lpSPName 는 일시적인 것이다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.


EnumLocalApplicationsCallback

EnumLocalApplicationsCallback 는,IDirectPlayLobby3::EnumLocalApplications 메소드에 대한 어플리케이션 정의의 콜백 함수이다.

BOOL FAR PASCAL EnumLocalApplicationsCallback(
  LPCDPLAPPINFO lpAppInfo,
  LPVOID lpContext,
  DWORD dwFlags
);

파라미터

lpAppInfo
열거되는 어플리케이션에 관한 정보가 저장 되고 있는 DPLAPPINFO 구조체에의 읽기 전용 포인터.
lpContext
IDirectPlayLobby3::EnumLocalApplications 호출로부터 건네받는 문맥.
dwFlags
장래의 사용에 대비해 예약되고 있다. 사용하지 않는 것.

반환값

열거를 계속하는 경우는, TRUE 를 돌려준다. 열거를 정지하는 경우는, FALSE 를 돌려준다.

주의

콜백 함수로 돌려주어지는 포인터는 일시적인 것이며, 콜백 함수의 내부에서만 유효하다. 어플리케이션은, 포인터 정보를 보존할 필요가 있는 경우, 데이터를 보관 유지하기 위한 메모리를 할당해 데이터를 카피하고 나서, 이 새로운 데이터에의 포인터를 보존할 필요가 있다. 이 함수로,lpAppInfo 는 일시적인 것이다. 또,lpAppInfo 파라미터로 지정된 구조 체내의 포인터의 lpszAppNameA 와 lpszAppName 도 일시적인 것이므로 주의 해야 한다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.


EnumPlayersCallback2

EnumPlayersCallback2 는, 어플리케이션에 의해 정의된 콜백 함수이다. 어플리케이션에서는, 이 함수를 이행 해,IDirectPlay4::EnumGroups 메소드,IDirectPlay4::EnumGroupPlayers 메소드,IDirectPlay4::EnumPlayers 메소드, 및 IDirectPlay4::EnumGroupsInGroup 메소드에 함수에의 포인터를 건네줄 필요가 있다. 이 콜백 함수는, 열거되는 플레이어 또는그룹 마다 1 회씩 불려 간다.

BOOL FAR PASCAL EnumPlayersCallback2(
  DPID dpId,
  DWORD dwPlayerType,
  LPCDPNAME lpName,
  DWORD dwFlags,
  LPVOID lpContext
);

파라미터

dpId
열거하는 플레이어 또는 그룹의 ID.
dwPlayerType
DPPLAYERTYPE_GROUP 또는 DPPLAYERTYPE_PLAYER 의 몇개의 엔티티의 타입.
lpName
플레이어 또는 그룹의 이름이 저장 되고 있는 DPNAME 구조체에의 읽기 전용 포인터. 이 포인터는, 콜백 함수의 처리중에게만 유효하다. 나중에 참조하기 위해서 데이터를 보존 하면나무는, 그것을 어플리케이션이 소유하고 있는 메모리에 카피할 필요가 있다.
dwFlags
열거하는 그룹이나 플레이어를 기술한 플래그.
DPENUMGROUPS_HIDDEN
그룹은, 은폐 플래그를 사용해 생성 되었다.
DPENUMGROUPS_SHORTCUT
그룹은, 쇼트 컷이다.
DPENUMGROUPS_STAGINGAREA
그룹은, staging 영역이다.
DPENUMPLAYERS_GROUP
플레이어와 그룹의 양쪽 모두가 열거되고 있다. 이 플래그는, 이 콜백 함수의 호출원의 열거 메소드로 그것이 지정되고 있었을 경우에게만 돌려주어진다.
DPENUMPLAYERS_LOCAL
플레이어 또는 그룹은 로컬 컴퓨터상에 존재한다. 이 플래그는, 이 콜백 함수의 호출원의 열거 메소드로 그것이 지정되고 있었을 경우에게만 돌려주어진다.
DPENUMPLAYERS_OWNER
플레이어는, 그룹의 소유자이다. 이 콜백 함수의 호출원의 IDirectPlay4::EnumGroupPlayers 메소드로 그것이 지정되고 있었을 경우에게만 돌려주어진다.
DPENUMPLAYERS_REMOTE
플레이어나 그룹은, 리모트 컴퓨터상에 존재한다. 이 플래그는, 이 콜백 함수의 호출원의 열거 메소드로 그것이 지정되고 있었을 경우에게만 돌려주어진다.
DPENUMPLAYERS_SERVERPLAYER
플레이어는, 어플리케이션/서버 세션의 서버 플레이어이다. 각 세션에 서버 플레이어는 1 개 밖에 존재하지 않는다.
DPENUMPLAYERS_SESSION
플레이어나 그룹은, 열거 메소드의 lpguidInstance 에 의해 지정된세션에 존재한다. 이 플래그는, 이 콜백 함수의 호출원의 열거 메소드로 그것이 지정되고 있었을 경우에게만 돌려주어진다.
DPENUMPLAYERS_SPECTATOR
플레이어는, 관객이다 (플레이어에게만 적용된다).
lpContext
어플리케이션에 의해 정의된 문맥에의 포인터.

반환값

열거를 계속하는 경우는, TRUE 를 돌려준다. 열거를 정지하는 경우는, FALSE 를 돌려준다.

주의

콜백 함수로 돌려주어지는 포인터는 일시적인 것이며, 콜백 함수의 내부에서만 유효하다. 어플리케이션은, 포인터 정보를 보존할 필요가 있는 경우, 데이터를 보관 유지하기 위한 메모리를 할당해 데이터를 카피하고 나서, 이 새로운 데이터에의 포인터를 보존할 필요가 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

DPNAME ,IDirectPlay4::EnumGroups ,IDirectPlay4::EnumPlayers ,IDirectPlay4::EnumGroupPlayers ,IDirectPlay4::EnumGroupsInGroup


EnumSessionsCallback2

EnumSessionsCallback2 는,IDirectPlay4::EnumSessions 메소드에 대한 어플리케이션 정의의 콜백 함수이다.

BOOL FAR PASCAL EnumSessionsCallback2(
  LPCDPSESSIONDESC2 lpThisSD,
  LPDWORD lpdwTimeOut,
  DWORD dwFlags,
  LPVOID lpContext
);

파라미터

lpThisSD
열거되는 세션을 기술한 DPSESSIONDESC2 구조체에의 포인터. 열거 처리가 마감 시간이 되었을 경우, 이 파라미터에는 NULL 가 설정된다.
lpdwTimeOut
현행의 타임 아웃값이 저장 되는 변수에의 포인터. 세션으로부터의 응답을 좀 더 기다리고 싶은 경우에 DPESC_TIMEDOUT 플래그가 돌려주어졌을 때, 이 파라미터는 리셋 할 수 있다.
dwFlags
일반적으로, 이 플래그는 0 으로 설정된다.
DPESC_TIMEDOUT
열거 처리가 마감 시간이 되었다. 처리를 속행하려면 lpdwTimeOut 를 리셋 해 TRUE 를 돌려준다. 처리를 정지하려면 , FALSE 를 돌려준다.
lpContext
어플리케이션에 의해 정의된 문맥에의 포인터.

반환값

열거를 계속하는 경우는, TRUE 를 돌려준다. 열거를 정지하는 경우는, FALSE 를 돌려준다.

주의

어플리케이션에서는,IDirectPlay4::EnumSessions 메소드를 사용하기 위해서, 이 함수를 이행 할 필요가 있다. 이 콜백 함수는, 열거된세션 마다 1 회씩 불려 간다. 모든 세션이 열거되면(자), 이 콜백 함수는 DPESC_TIMEDOUT 플래그를 설정해 한번 더 불려 간다.

어플리케이션으로 세션의 성질을 판정하려면 ,DPSESSIONDESC2 의 각 플래그를 조사한다.

시큐어 세션 의 경우,DPSESSIONDESC2 의 dwMaxPlayers 멤버와 dwCurrentPlayers 멤버에는 0 이 설정된다.

콜백 함수로 돌려주어지는 포인터는 일시적인 것이며, 콜백 함수의 내부에서만 유효하다. 어플리케이션은, 포인터 정보를 보존할 필요가 있는 경우, 데이터를 보관 유지하기 위한 메모리를 할당해 데이터를 카피하고 나서, 이 새로운 데이터에의 포인터를 보존할 필요가 있다. 이 함수로,lpThisSD 는 일시적인 것이다. 또,lpThisSD 파라미터로 지정된 구조 체내의 포인터의 lpszSessionName/lpszSessionNameA 와 lpszPassword/lpszPasswordA 도 일시적인 것이므로 주의 해야 한다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.


구조체

DirectX 5.0 의 DirectPlay 구조체에는 새로운 데이터 멤버가 몇개인가 추가되었지만, 그것들은 현재의 버젼에서도 지원 되고 있다. DirectPlay 의 이전의 버젼의 실행시 파일과의 호환성을 확보해야 하는 어플리케이션에서는, 다음의 어느쪽이든을 행할 필요가 있다.

  • DirectX 3.0 의 헤더 파일에 존재하는 구조체를 사용한다.
  • 구조체의 모든 멤버에 액세스 하기 전에, 각 구조체의 dwSize 멤버를 조사한다.

다음에, DirectPlay 구조체를 나타낸다.

  • DPACCOUNTDESC
  • DPAPPLICATIONDESC
  • DPAPPLICATIONDESC2
  • DPCAPS
  • DPCHAT
  • DPCOMPORTADDRESS
  • DPCOMPOUNDADDRESSELEMENT
  • DPCREDENTIALS
  • DPLAPPINFO
  • DPLCONNECTION
  • DPNAME
  • DPSECURITYDESC
  • DPSESSIONDESC2


DPACCOUNTDESC

DPACCOUNTDESC 구조체는, 특정의 플레이어의 어카운트 정보를 기술한다.

typedef struct {
    DWORD  dwSize;
    DWORD  dwFlags;
    union {
        LPWSTR  lpszAccountID;
        LPSTR   lpszAccountIDA;
    };
} DPACCOUNTDESC, FAR *LPDPACCOUNTDESC;

멤버

dwSize
DPACCOUNTDESC 구조체의 사이즈. dwSize = sizeof(DPACCOUNTDESC).
dwFlags
사용하지 않는다. 0 으로 설정해 둔다.
lpszAccountID
어카운트 식별자가 저장 되고 있는 Unicode 캐릭터 라인에의 포인터. 이것은, 안전하게 로그 온 한 플레이어를 기술한 일의의 식별자. 식별자의 포맷은, 사용되고 있는 시큐러티 지원 프로바이더 인터페이스 (SSPI) 패키지에 의해 정해진다.
lpszAccountIDA
어카운트 식별자가 저장 되고 있는 ANSI 캐릭터 라인에의 포인터. 이것은, 안전하게 로그 온 한 플레이어를 기술한 일의의 식별자. 식별자의 포맷은, 사용되고 있는 SSPI 패키지에 의해 정해진다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::GetPlayerAccount


DPAPPLICATIONDESC

DPAPPLICATIONDESC 구조체는,IDirectPlayLobby3::RegisterApplication 를 사용해 로비 대응 어플리케이션을 등록하기 위해서 필요한 정보를 모두 기술한다.

typedef struct {
    DWORD   dwSize;
    DWORD   dwFlags;
    union {
      LPSTR    lpszApplicationNameA;
      LPWSTR   lpszApplicationName;
    }
    GUID    guidApplication;
    union {
      LPSTR     lpszFilenameA;
      LPWSTR    lpszFilename;
    }
    union {
      LPSTR   lpszCommandLineA;
      LPWSTR  lpszCommandLine;
    }
    union {
      LPSTR   lpszPathA;
      LPWSTR  lpszPath;
    }
    union {
      LPSTR    lpszCurrentDirectoryA;
      LPWSTR   lpszCurrentDirectory;
    }
    LPSTR   lpszDescriptionA;
    LPWSTR  lpszDescriptionW;
} DPAPPLICATIONDESC, *LPDPAPPLICATIONDESC;

멤버

dwSize
DPAPPLICATIONDESC 구조체의 사이즈. dwSize = sizeof(DPAPPLICATIONDESC).
dwFlags
사용하지 않는다. 0 으로 설정해 둔다.
lpszApplicationNameA, lpszApplicationName
어플리케이션의 이름이 저장 되고 있는 캐릭터 라인에의 포인터. 메모: 이 타이틀은 로컬라이즈 되지 않는다. 어플리케이션명을 로컬라이즈 하려면 ,lpszDescriptionA 멤버와 lpszDescriptionW 멤버를 사용한다.
guidApplication
어플리케이션의 글로벌 유니크 식별자 (GUID). 이것은, 게임 세션의 호스트일 때는 DPSESSIONDESC2 구조체의 guidApplication 멤버로 사용되는 값과 같지 않으면 안 된다.
lpszFilenameA, lpszFilename
기동되는 실행 가능 프로그램의 이름이 저장 되고 있는 캐릭터 라인에의 포인터. 메모: 로비로부터 기동 하면나무는, 그루터기의 실행 가능 프로그램을 사용하지 않는 것. 로비로부터 기동 하면나무는, 그루터기는 생략 되어, 메인의 실행 가능 프로그램이 기동된다.
lpszCommandLineA, lpszCommandLine
로비에 의해 기동될 때, 실행 가능 프로그램에게 건네지는 커멘드행의 인수가 저장 된 캐릭터 라인에의 포인터.
lpszPathA, lpszPath
실행 가능 프로그램이 놓여져 있는 패스가 저장 되고 있는 캐릭터 라인에의 포인터.
lpszCurrentDirectoryA, lpszCurrentDirectory
현재 디렉토리를 설정하는 패스가 저장 되고 있는 캐릭터 라인에의 포인터. 일반적으로, 이것은 lpszPath 또는 lpszPathA 와 같다.
lpszDescriptionA
어플리케이션의 로컬라이즈 된 기술이 저장 되고 있는 ANSI 의 1 바이트 캐릭터 라인에의 포인터. ANSI 인터페이스 (IDirectPlayLobby3A 등)로 EnumLocalApplications 이 불려 갔을 경우, 그 캐릭터 라인이 있으면, 그것이 돌려주어진다. 그 이외의 경우,lpszApplicationName 데이터 멤버가 돌려주어진다. 메모: 이 캐릭터 라인에는 복수 문자는 설정되지 않는다. 로컬라이즈 한 ANSI 기술이 필요하지 않은 경우는, NULL 를 설정한다.
lpszDescriptionW
어플리케이션의 로컬라이즈 된 기술이 저장 되고 있는 Unicode 캐릭터 라인에의 포인터. Unicode 인터페이스 (IDirectPlayLobby3 등)로 EnumLocalApplications 이 불려 갔을 경우, 그 캐릭터 라인이 있으면, 그것이 돌려주어진다. 그 캐릭터 라인이 없는 경우는,lpszDescriptionA 데이터 멤버가 Unicode 에 변환되어 돌려주어진다. lpszDescriptionA 도 lpszDescriptionW 도 존재하지 않는 경우,lpszApplicationName 데이터 멤버가 돌려주어진다. 메모: 이 캐릭터 라인은 Unicode 문자만으로 구성되지 않으면 안 된다. 로컬라이즈 한 Unicode 기술이 필요하지 않은 경우는, NULL 를 설정한다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.

참조

IDirectPlayLobby3::RegisterApplication ,DPAPPLICATIONDESC2


DPAPPLICATIONDESC2

DPAPPLICATIONDESC2 구조체는,IDirectPlayLobby3::RegisterApplication 를 사용해 로비 대응 어플리케이션을 등록하기 위해서 필요한 정보를 모두 기술한다. 어플리케이션을 기동 어플리케이션에 의해 기동하는 경우는, 대신에 DPAPPLICATIONDESC 를 사용한다.

typedef struct {
    DWORD   dwSize;
    DWORD   dwFlags;
    union {
      LPSTR    lpszApplicationNameA;
      LPWSTR   lpszApplicationName;
    }
    GUID    guidApplication;
    union {
      LPSTR     lpszFilenameA;
      LPWSTR    lpszFilename;
    }
    union {
      LPSTR   lpszCommandLineA;
      LPWSTR  lpszCommandLine;
    }
    union {
      LPSTR   lpszPathA;
      LPWSTR  lpszPath;
    }
    union {
      LPSTR    lpszCurrentDirectoryA;
      LPWSTR   lpszCurrentDirectory;
    }
    LPSTR   lpszDescriptionA;
    LPWSTR  lpszDescriptionW;
    union
    {
      LPSTR   lpszAppLauncherNameA;
      LPWSTR  lpszAppLauncherName;
    };
} DPAPPLICATIONDESC2, *LPDPAPPLICATIONDESC2;

멤버

dwSize
DPAPPLICATIONDESC2 구조체의 사이즈. dwSize = sizeof(DPAPPLICATIONDESC2).
dwFlags
사용하지 않는다. 0 으로 설정해 둔다.
lpszApplicationNameA, lpszApplicationName
어플리케이션의 이름이 저장 되고 있는 캐릭터 라인에의 포인터. 메모: 이 타이틀은 로컬라이즈 되지 않는다. 어플리케이션명을 로컬라이즈 하려면 ,lpszDescriptionA 멤버와 lpszDescriptionW 멤버를 사용한다.
guidApplication
어플리케이션의 글로벌 유니크 식별자 (GUID). 이것은, 게임 세션의 호스트일 때는 DPSESSIONDESC2 구조체의 guidApplication 멤버로 사용되는 값과 같지 않으면 안 된다.
lpszFilenameA, lpszFilename
기동되는 실행 가능 프로그램의 이름이 저장 되고 있는 캐릭터 라인에의 포인터. 메모: 로비로부터 기동 하면나무는, 그루터기의 실행 가능 프로그램을 사용하지 않는 것. 로비로부터 기동 하면나무는, 그루터기는 생략 되어, 메인의 실행 가능 프로그램이 기동된다.
lpszCommandLineA, lpszCommandLine
로비에 의해 기동될 때, 실행 가능 프로그램에게 건네지는 커멘드행의 인수가 저장 된 캐릭터 라인에의 포인터.
lpszPathA, lpszPath
실행 가능 프로그램이 놓여져 있는 패스가 저장 되고 있는 캐릭터 라인에의 포인터.
lpszCurrentDirectoryA, lpszCurrentDirectory
현재 디렉토리를 설정하는 패스가 저장 되고 있는 캐릭터 라인에의 포인터. 일반적으로, 이것은 lpszPath 또는 lpszPathA 와 같다.
lpszDescriptionA
어플리케이션의 로컬라이즈 된 기술이 저장 되고 있는 ANSI 의 1 바이트 캐릭터 라인에의 포인터. ANSI 인터페이스 (IDirectPlayLobby3A 등)로 EnumLocalApplications 이 불려 갔을 경우, 그 캐릭터 라인이 있으면, 그것이 돌려주어진다. 그 이외의 경우,lpszApplicationName 데이터 멤버가 돌려주어진다. 메모: 이 캐릭터 라인에는 복수 문자는 설정되지 않는다. 로컬라이즈 한 ANSI 기술이 필요하지 않은 경우는, NULL 를 설정한다.
lpszDescriptionW
어플리케이션의 로컬라이즈 된 기술이 저장 되고 있는 Unicode 캐릭터 라인에의 포인터. Unicode 인터페이스 (IDirectPlayLobby3 등)로 EnumLocalApplications 이 불려 갔을 경우, 그 캐릭터 라인이 있으면, 그것이 돌려주어진다. 그 캐릭터 라인이 없는 경우는,lpszDescriptionA 데이터 멤버가 Unicode 에 변환되어 돌려주어진다. lpszDescriptionA 도 lpszDescriptionW 도 존재하지 않는 경우,lpszApplicationName 데이터 멤버가 돌려주어진다. 메모: 이 캐릭터 라인은 Unicode 문자만으로 구성되지 않으면 안 된다. 로컬라이즈 한 Unicode 기술이 필요하지 않은 경우는, NULL 를 설정한다.
lpszAppLauncherNameA, lpszAppLauncherName
기동 어플리케이션의 실행 가능 프로그램의 이름이 저장 되고 있는 캐릭터 라인에의 포인터. 기동 어플리케이션은 로비에 의해 기동되어 그것이 lpszApplicationName 에 기술된 어플리케이션을 기동한다. 기동 어플리케이션은, 그 어플리케이션과 같은 디렉토리에 없으면 안 된다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.

참조

IDirectPlayLobby3::RegisterApplication


DPCAPS

DPCAPS 구조체는,IDirectPlay4::GetCaps 메소드나 IDirectPlay4::GetPlayerCaps 메소드를 호출한 다음에, DirectPlay 오브젝트의 능력을 보관 유지한다. 이러한 능력은, 요구된 능력이 보증 첨부인지, 보증없이 있을까에 의해 다르다. 이 구조체는, 읽기 전용이다. IDirectPlay4::SendEx 메소드로 지원 되고 있는 부분을 나타내는 능력 (dwFlags 의 DPCAPS_SENDPRIORITYSUPPORTED 플래그와 DPCAPS_SENDTIMEOUTSUPPORTED 플래그등)은, 세션이 열릴 때까지 사용할 수 없다. 세션의 호스트인 어플리케이션이 DPSESSIONDESC2 구조체의 DPSESSION_DIRECTPLAYPROTOCOL 플래그를 지정하고 있는 경우, 모든 SendEx 옵션이 지원 된다.

typedef struct {
    DWORD dwSize;
    DWORD dwFlags;
    DWORD dwMaxBufferSize;
    DWORD dwMaxQueueSize;
    DWORD dwMaxPlayers;
    DWORD dwHundredBaud;
    DWORD dwLatency;
    DWORD dwMaxLocalPlayers;
    DWORD dwHeaderLength;
    DWORD dwTimeout;
} DPCAPS, FAR *LPDPCAPS;

멤버

dwSize
DPCAPS 구조체의 멤버. dwSize = sizeof(DPCAPS). 어플리케이션은, 이 구조체를 사용하기 전에, 우선 이 멤버를 설정한다. 설정하지 않으면, 에러가 발생한다.
dwFlags
DirectPlay 오브젝트의 프로퍼티를 나타내는 플래그.
DPCAPS_ASYNCCANCELALLSUPPORTED
보류 상태의 비동기 메세지를 모두 취소하는 기능이 지원 되고 있는 것을 나타낸다. 이 플래그는, 지원 되고 있는 취소 처리의 타입이 미송신 메세지를 취소하는 처리 뿐인 것을 나타낸다. 우선 순위의 범위나 메세지 ID 를 지정해 메세지를 취소하려고 하면, DPERR_UNSUPPORTED 가 돌려주어진다. 대조적으로, DPCAPS_ASYNCCANCELSUPPORTED 플래그는 취소해 처리의 모든 타입이 지원 되고 있는 것을 나타낸다. 다만,SendEx 로 지원 되고 있는 부분을 나타내는 능력은, 세션이 열릴 때까지 사용할 수 없다.
DPCAPS_ASYNCCANCELSUPPORTED
비동기 메세지를 취소하는 기능이 지원 되고 있는 것을 나타낸다. 메세지 ID 에 의한 취소, 우선 순위의 범위에 의한 취소, 모든 미송신 메세지의 취소라고 한 모든 타입의 취소 처리가 지원 되고 있다. 다만, SendEx 로 지원 되고 있는 부분을 나타내는 능력은, 세션이 열릴 때까지 사용할 수 없다.
DPCAPS_ASYNCSUPPORTED
비동기 메세지 처리가 지원 되고 있는 것을 나타낸다. 그 때문에, 어플리케이션은 SendEx 로 DPSEND_ASYNC 플래그를 사용할 수 있다. 상세한 것에 대하여는, 「주의」를 참조할것. 다만, SendEx 로 지원 되고 있는 부분을 나타내는 능력은, 세션이 열릴 때까지 사용할 수 없다.
DPCAPS_ENCRYPTIONSUPPORTED
세션이시큐어 세션이기 (위해)때문에, 또는서비스 프로바이더로 메세지를 암호화할 수 있기 (위해)때문에, 이 DirectPlay 오브젝트에 의해 메세지의 암호화가 지원 되고 있는 것을 나타낸다.
DPCAPS_GROUPOPTIMIZED
이 DirectPlay 오브젝트에 바인드 되고 있는 서비스 프로바이더가그룹 (멀티 캐스트)의 메세지 처리를 최적화할 수 있는 것을 나타낸다.
DPCAPS_GUARANTEEDOPTIMIZED
이 DirectPlay 오브젝트에 바인드 되고 있는 서비스 프로바이더로 보증 첨부 메세지 전달이 지원 되고 있는 것을 나타낸다.
DPCAPS_GUARANTEEDSUPPORTED
보증 첨부 메세지 전달은, 그것이 서비스 프로바이더로 지원 되고 있기 (위해)때문에, 또는 보증 없음 서비스 프로바이더로 DirectPlay 에 의해 그것이 이행 되고 있기 (위해)때문에, 그것이 이 DirectPlay 오브젝트에 의해 지원 되고 있는 것을 나타낸다.
DPCAPS_ISHOST
호출원어플리케이션에 의해 생성 된 DirectPlay 오브젝트가 세션 호스트인 것을 나타낸다.
DPCAPS_KEEPALIVEOPTIMIZED
서비스 프로바이더가 세션에의 접속이 언제 상실했는지를 검출할 수 있는 것을 나타낸다.
DPCAPS_SENDPRIORITYSUPPORTED
SendEx 로 설정된 메세지의 우선 순위가 지원 되고 있는 것을 나타낸다. 다만, SendEx 로 지원 되고 있는 부분을 나타내는 능력은, 세션이 열릴 때까지 사용할 수 없다.
DPCAPS_SENDTIMEOUTSUPPORTED
SendEx 로 지정된 메세지의 타임 아웃이 지원 되고 있는 것을 나타낸다. 이 플래그는, 서비스 프로바이더 또는 DirectPlay 에 의해 설정할 수 있다. 다만, SendEx 로 지원 되고 있는 부분을 나타내는 능력은, 세션이 열릴 때까지 사용할 수 없다.
DPCAPS_SIGNINGSUPPORTED
시큐어 세션이기 (위해)때문에, 또는 서비스 프로바이더로 메세지에 서명을 설정할 수 있기 (위해)때문에, 메세지 인증이 이 DirectPlay 오브젝트에 의해 지원 되고 있는 것을 나타낸다.
dwMaxBufferSize
이 서비스 프로바이더에 의해 싱글 패킷으로 송신할 수 있는 최대 바이트수. 비교적 사이즈의 큰 메세지는, 복수의 패킷을 사용해 송신된다.
dwMaxQueueSize
이 멤버는, 사용되지 않게 되어 있다.
dwMaxPlayers
이 DirectPlay 오브젝트에 의해 세션내에서 지원 되고 있는 로컬 플레이어와 리모트 플레이어의 최대수.
dwHundredBaud
1 초 쯤의 대역폭 (100 비트의 배수로 지정). 예를 들어, 값이 24 때, 1 초 쯤 2400 비트의 대역폭이 된다.
dwLatency
서비스 프로바이더에 의한지연 시간의 견적 (밀리 세컨드 단위). 이 값이 0 의 경우, DirectPlay 는 추측할 수가 없다. 서비스 프로바이더의 정밀도는, 평균 메세지 사이즈를 고려에 넣은 어플리케이션간의 테스트에 의해 정해진다. 지연 시간은, 어플리케이션이 보증 첨부 메세지 전달 방식과 보증 없음 메세지 전달 방식의 어느 쪽을 사용하고 있을까에 의해 다른 일이 있다.
dwMaxLocalPlayers
세션으로 지원 되는 로컬 플레이어의 최대수.
dwHeaderLength
이 DirectPlay 오브젝트에 의해 플레이어 메세지에 추가되는 헤더의 사이즈 (바이트 단위). 다만, 헤더의 사이즈는, 사용하고 있는 서비스 프로바이더에 의해 다르므로 주의 해야 한다.
dwTimeout
서비스 프로바이더의 추천 타임 아웃값. 디폴트로 DirectPlay 는, 메세지에의 응답을 기다릴 때 이 타임 아웃값을 사용한다.

주의

DPCAPS_ASYNCSUPPORTED 플래그, DPCAPS_SENDTIMEOUTSUPPORTED 플래그, DPCAPS_SENDPRIORITYSUPPORTED 플래그, DPCAPS_ASYNCCANCELSUPPORTED 플래그, 및 DPCAPS_ASYNCCANCELALLSUPPORTED 플래그는, 현재 세션의 통신 능력을 나타내고 있다.

어플리케이션이 SendEx 로 DPSEND_ASYNC 를 사용할 수 있도록(듯이) 하려면 , 다음의 조건의 어느쪽이든 (또는 양쪽 모두)가 진이 아니면 안된다.

세션이 생성 되었을 때에 DPSESSION_DIRECTPLAYPROTOCOL 플래그를 지정했다.

서비스 프로바이더로 비동기 메세지 처리가 지원 되고 있다.

이것은, 모뎀, 시리얼, 인터넷 패킷데이터 교환기 (IPX) 서비스 프로바이더는, 그것들이 사용 가능한 보증 첨부 메세지 처리를 실행할 수 있지만, 비동기의 메세지 처리에 대해서는 DPSESSION_DIRECTPLAYPROTOCOL 플래그를 명시적으로 설정하지 않는 한 실행할 수 없는 것을 의미한다. 컴퓨터에 Windows Sockets 2.0 이 탑재되고 있는 경우,TCP/IP 서비스 프로바이더는 비동기 메세지 처리를 이행 하고 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::Send ,IDirectPlay4::SendEx ,IDirectPlay4::GetCaps ,IDirectPlay4::GetPlayerCaps


DPCHAT

DPCHAT 구조체는, DirectPlay 채팅 메세지를 보관 유지한다. 채팅 메세지는,IDirectPlay4::SendChatMessage 메소드에 의해 송신된다.

typedef struct {
    DWORD dwSize;
    DWORD dwFlags;
    union{
      LPWSTR lpszMessage;
      LPSTR  lpszMessageA;
    };
} DPCHAT, FAR *LPDPCHAT;

멤버

dwSize
DPCHAT 구조체의 사이즈. dwSize = sizeof(DPCHAT).
dwFlags
사용하지 않는다. 0 으로 설정해 둔다.
lpszMessage
송신하는 메세지가 저장 되고 있는 Unicode 캐릭터 라인에의 포인터. Unicode 인터페이스 (IDirectPlay4 )에서만 사용할 수 있다.
lpszMessageA
송신하는 메세지가 저장 되고 있는 ANSI 캐릭터 라인에의 포인터. ANSI 인터페이스 (IDirectPlay4A)에서만 사용할 수 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::SendChatMessage


DPCOMPORTADDRESS

DPCOMPORTADDRESS 구조체는, COM 포트의 구성에 관한 정보를 보관 유지한다.

typedef struct DPCOMPORTADDRESS{
    DWORD dwComPort;
    DWORD dwBaudRate;
    DWORD dwStopBits;
    DWORD dwParity;
    DWORD dwFlowControl;
} DPCOMPORTADDRESS;

typedef DPCOMPORTADDRESS FAR* LPDPCOMPORTADDRESS;

멤버

dwComPort
사용하는 COM 포트의 번호를 나타낸다. 이 멤버의 값은, 1, 2, 3, 4 의 언젠가이다.
dwBaudRate
COM 포트의 보를 나타낸다. 이 멤버의 값은, 다음의 언젠가이다.
CBR_110 | CBR_300 | CBR_600
CBR_1200 | CBR_2400 | CBR_4800
CBR_9600 | CBR_14400 | CBR_19200
CBR_38400 | CBR_56000 | CBR_57600
CBR_115200 | CBR_128000 | CBR_256000

dwStopBits
stop bit의 수이다. 이 멤버의 값은, ONESTOPBIT, ONE5STOPBITS, TWOSTOPBITS 의 언젠가이다.
dwParity
COM 포트로 사용하는 패리티를 나타낸다. 이 멤버의 값은, NOPARITY, ODDPARITY, EVENPARITY, MARKPARITY 의 언젠가이다.
dwFlowControl
COM 포트로 사용하는 플로우 컨트롤의 방법을 나타낸다. 이 멤버의 값은, 다음의 언젠가이다.
DPCPA_DTRFLOW
DTR 에 의한 하드웨어 플로우 컨트롤을 나타낸다.
DPCPA_NOFLOW
플로우 컨트롤일까 있고 일을 나타낸다.
DPCPA_RTSDTRFLOW
RTS 와 DTR 에 의한 하드웨어 플로우 컨트롤을 나타낸다.
DPCPA_RTSFLOW
RTS 밤하드웨어 플로우 컨트롤을 나타낸다.
DPCPA_XONXOFFFLOW
소프트웨어 플로우 컨트롤을 나타낸다 (xon/xoff).

주의

보, stop bit, 및 패리티를 정의하는 정수는, Winbase.h 로 정의되고 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.


DPCOMPOUNDADDRESSELEMENT

DPCOMPOUNDADDRESSELEMENT 구조체는, DirectPlay 주소의 데이타체크를 기술한다.

typedef struct {
    GUID    guidDataType;
    DWORD   dwDataSize;
    LPVOID  lpData;
} DPCOMPOUNDADDRESSELEMENT, FAR *LPDPCOMPOUNDADDRESSELEMENT;

멤버

guidDataType
이 구조체에 저장 되고 있는 데이터의 타입을 지정한 GUID.
dwDataSize
데이터의 사이즈 (바이트 단위).
lpData
데이터가 저장 되고 있는 버퍼에의 포인터.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.

참조

IDirectPlayLobby3::CreateCompoundAddress ,DirectPlay 주소의 데이터형


DPCREDENTIALS

DPCREDENTIALS 구조체는, 보증 서버에 접속하기 위한 유저명, 패스워드, 도메인을 보관 유지한다.

typedef struct {
    DWORD  dwSize;
    DWORD  dwFlags;
    union {
           LPWSTR lpszUsername;
           LPSTR  lpszUsernameA;
          };
    union {
           LPWSTR lpszPassword;
           LPSTR  lpszPasswordA;
          };
    union {
           LPWSTR lpszDomain;
           LPSTR  lpszDomainA;
          };

} DPCREDENTIALS, FAR *LPDPCREDENTIALS;

멤버

dwSize
DPCREDENTIALS 구조체의 사이즈. dwSize = sizeof(DPCREDENTIALS).
dwFlags
사용하지 않는다. 0 으로 설정해 둔다.
lpszUsername, lpszPassword, lpszDomain
유저명, 패스워드, 도메인이 저장 되고 있는 Unicode 캐릭터 라인에의 포인터. Unicode 인터페이스에서만 사용할 수 있다.
lpszUsernameA, lpszPasswordA, lpszDomainA
유저명, 패스워드, 도메인이 저장 되고 있는 ANSI 캐릭터 라인에의 포인터. ANSI 인터페이스에서만 사용할 수 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::SecureOpen


DPLAPPINFO

DPLAPPINFO 구조체는, 레지스트리내의 어플리케이션에 관한 정보를 보관 유지한다. 이 구조체는,IDirectPlayLobby3::EnumLocalApplications 콜백 함수에게 건네진다.

typedef struct {
    DWORD  dwSize;
    GUID   guidApplication;
    union {
           LPSTR  lpszAppNameA;
           LPWSTR lpszAppName;
          };
} DPLAPPINFO, FAR *LPDPLAPPINFO;

멤버

dwSize
DPLAPPINFO 구조체의 사이즈. dwSize = sizeof(DPLAPPINFO). 어플리케이션은, 이 구조체를 사용하기 전에, 이 멤버를 설정할 필요가 있다. 설정하지 않으면, 에러가 발생한다.
guidApplication
어플리케이션의 글로벌 유니크 식별자 (GUID).
lpszAppNameA, lpszAppName
ANSI 또는 Unicode 의 어플리케이션명. ANSI 또는 Unicode 일까는, 사용하고 있는 인터페이스에 의해 정해진다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.


DPLCONNECTION

DPLCONNECTION 구조체는, 어플리케이션을세션에 접속하기 위해서 필요한 정보를 보관 유지한다.

typedef struct {
    DWORD            dwSize;
    DWORD            dwFlags;
    LPDPSESSIONDESC2 lpSessionDesc;
    LPDPNAME         lpPlayerName;
    GUID             guidSP;
    LPVOID           lpAddress;
    DWORD            dwAddressSize;
} DPLCONNECTION, FAR *LPDPLCONNECTION;

멤버

dwSize
DPLCONNECTION 구조체의 사이즈. dwSize = sizeof(DPLCONNECTION). 어플리케이션은, 이 구조체를 사용하기 전에, 이 멤버를 설정할 필요가 있다. 설정하지 않으면, 에러가 발생한다.
dwFlags
세션의 여는 방법을 나타낸다.
DPLCONNECTION_CREATESESSION
세션 기술에 기술되고 있도록(듯이) 새로운 세션을 생성 한다.
DPLCONNECTION_JOINSESSION
세션 기술에 기술되고 있도록(듯이) 기존의 세션에 참가한다.
lpSessionDesc
생성 하는 세션 또는 참가하는 세션을 기술한 DPSESSIONDESC2 구조체에의 포인터.
lpPlayerName
플레이어를 생성 할 경우에 사용하는 이름을 보관 유지한 DPNAME 구조체에의 포인터. 이것은, 로비에 등록된 인물의 이름이다. 어플리케이션에서는, 이 이름을 무시해도 괜찮다.
guidSP
세션을 접속할 경우에 사용하는 서비스 프로바이더의 글로벌 유니크 식별자 (GUID).
lpAddress
서비스 프로바이더가 세션을 접속할 경우에 필요한 정보가 저장 되고 있는 DirectPlay 주소에의 포인터.
dwAddressSize
주소 데이터의 사이즈 (바이트 단위).

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.

참조

IDirectPlayLobby3::RunApplication ,IDirectPlayLobby3::GetConnectionSettings ,IDirectPlayLobby3::SetConnectionSettings ,DirectPlay 주소


DPNAME

DPNAME 구조체는, 플레이어나 그룹등의 DirectPlay 엔티티의 이름 정보를 보관 유지한다.

typedef struct {
    DWORD dwSize;
    DWORD dwFlags;
    union {
        LPWSTR lpszShortName;
        LPSTR  lpszShortNameA;
    };
    union {
        LPWSTR lpszLongName;
        LPSTR  lpszLongNameA;
    };
} DPNAME, FAR *LPDPNAME;

멤버

dwSize
DPNAME 구조체의 사이즈. dwSize = sizeof(DPNAME). 어플리케이션은, 이 구조체를 사용하기 전에, 이 멤버를 설정할 필요가 있다. 설정하지 않으면, 에러가 발생한다.
dwFlags
구조체에 고유의 플래그. 현재는 0 으로 설정되어 있다.
lpszShortName 및 lpszLongName
플레이어나 그룹의 짧은 이름 (친구 사이에 사용)과 긴 이름 (정식으로 사용)이 저장 되고 있는 Unicode 캐릭터 라인에의 포인터. 이러한 멤버는,IDirectPlay4 인터페이스가 사용되고 있는 경우에게만 사용한다.
lpszShortNameA 및 lpszLongNameA
플레이어나 그룹의 짧은 이름 (친구 사이에 사용)과 긴 이름 (정식으로 사용)이 저장 되고 있는 ANSI 캐릭터 라인에의 포인터. 이러한 멤버는,IDirectPlay4A 인터페이스가 사용되고 있는 경우에게만 사용한다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::CreateGroup ,IDirectPlay4::CreatePlayer ,IDirectPlay4::GetGroupName ,IDirectPlay4::GetPlayerName ,IDirectPlay4::SetGroupName ,IDirectPlay4::SetPlayerName


DPSECURITYDESC

DPSECURITYDESC 구조체는, DirectPlay 세션의 인스턴스의 시큐러티 프로퍼티에 대해 기술한다.

typedef struct {
    DWORD  dwSize;
    DWORD  dwFlags;
    union {
        LPWSTR  lpszSSPIProvider;
        LPSTR   lpszSSPIProviderA;
    };
    union {
        LPWSTR lpszCAPIProvider;
        LPSTR  lpszCAPIProviderA;
    };
    DWORD  dwCAPIProviderType;
    DWORD  dwEncryptionAlgorithm;
} DPSECURITYDESC, FAR *LPDPSECURITYDESC;

멤버

dwSize
DPSECURITYDESC 구조체의 사이즈. dwSize = sizeof(DPSECURITYDESC).
dwFlags
사용하지 않는다. 0 으로 설정해 둔다.
lpszSSPIProvider, lpszSSPIProviderA
인증 로그 온으로 사용하는 시큐러티 지원 프로바이더 인터페이스 (SSPI) 패키지를 기술한 Unicode 캐릭터 라인 또는 ANSI 캐릭터 라인에의 포인터. 디폴트의 NTLM(NT LAN Manager) 시큐러티 프로바이더를 사용할때는, NULL 를 건네준다.
lpszCAPIProvider, lpszCAPIProviderA
암호화 서비스로 사용하는 CryptoAPI 패키지를 기술한 Unicode 캐릭터 라인 또는 ANSI 캐릭터 라인에의 포인터. 디폴트의 Microsoft RSA Base Cryptographic Provider v. 1.0 을 사용할때는, NULL 를 건네준다.
dwCAPIProviderType
CryptoAPI 서비스 프로바이더 타입. 디폴트 타입의 PROV_RSA_FULL 를 사용할때는, 0 을 건네준다.
dwEncryptionAlgorithm
사용하는 암호화 알고리즘. DirectPlay 는, 스트림 암호만을 지원 하고 있다. 디폴트의 CALG_RC4 스트림 암호를 사용할때는, 0 을 건네준다.

주의

DirectPlay 는, 블록 암호를 지원 하고 있지 않다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::SecureOpen


DPSESSIONDESC2

DPSESSIONDESC2 구조체는, 세션의 능력의 기술을 보관 유지한다.

다만, 세션 기술 플래그의 일부는 읽기 전용이며, 변경할 수 없다. 또, 나머지의 플래그는 호스트 밖에 변경할 수 없기 때문에 주의 해야 한다. dwFlags 멤버의 설명을 참조할것.

typedef struct {
    DWORD dwSize;
    DWORD dwFlags;
    GUID  guidInstance;
    GUID  guidApplication;
    DWORD dwMaxPlayers;
    DWORD dwCurrentPlayers;
    union  {
        LPWSTR lpszSessionName;
        LPSTR  lpszSessionNameA;
    };
    union  {
        LPWSTR lpszPassword;
        LPSTR  lpszPasswordA;
    };
    DWORD dwReserved1;
    DWORD dwReserved2;
    DWORD dwUser1;
    DWORD dwUser2;
    DWORD dwUser3;
    DWORD dwUser4;
} DPSESSIONDESC2, FAR *LPDPSESSIONDESC2;

멤버

dwSize
DPSESSIONDESC2 구조체의 사이즈. 어플리케이션은, 이 구조체를 사용하기 전에, 우선 이 멤버를 설정할 필요가 있다.
dwFlags
DPSESSION_CLIENTSERVER, DPSESSION_DIRECTPLAYPROTOCOL, DPSESSION_KEEPALIVE, DPSESSION_MIGRATEHOST, DPSESSION_MULTICASTSERVER, DPSESSION_NOMESSAGEID, DPSESSION_OPTIMIZELATENCY, 및 DPSESSION_SECURESERVER 의 플래그의 편성. 세션이 기동되고 있는 경우, 이러한 플래그는 변경할 수 없다. 그 외의 플래그의 DPSESSION_JOINDISABLED, DPSESSION_NEWPLAYERSDISABLED, DPSESSION_NODATAMESSAGES, DPSESSION_NOPRESERVEORDER, DPSESSION_PASSWORDREQUIRED, 및 DPSESSION_PRIVATE 는,IDirectPlay4::SetSessionDesc 에 의해 세션이 기동된 다음에도 변경할 수 있지만, 변경할 수 있는 것은 호스트 뿐이다.
DPSESSION_CLIENTSERVER
이것이, 어플리케이션 서버 프로세스가 호스트의 클라이언트/서버 세션이라고 지정한다. 이 플래그는, 세션이 생성 되었을 때에 지정할 필요가 있다. 이 세션에 참가한 클라이언트는, 그 서버 플레이어와 로컬 플레이어를 열거할 수 밖에 할 수 없다. 세션의 호스트에서는, 모든 플레이어가 열거된다. 이 플래그가 설정되어 있지 않은 경우, 세션은피어 투 피어 세션이다. 이 플래그가 설정되어 있는 경우, 서버 플레이어를 생성 할 수 있는 것은 호스트 뿐이다. 이 플래그는, DPSESSION_MIGRATEHOST 에서는 사용할 수 없다.
DPSESSION_DIRECTPLAYPROTOCOL
이 세션에서는 서비스 프로바이더에 의해 이행 되는 프로토콜은 아니고, DirectPlay 의 보증 첨부 프로토콜을 사용하도록(듯이) 지정한다. 메세지 쓰로틀링에 의해 퍼포먼스를 향상시키고 싶은 경우, 또는 IDirectPlay4::SendEx 의 모든 기능을 사용할 수 있도록(듯이) 하고 싶은 경우에, 이 플래그를 사용한다. 이 플래그를 설정 하면, 신뢰성의 낮은 프로바이더에서의 보증 첨부 송신도 가능하게 된다. 또, 이 플래그에 의해, TCP/IP 상에서 DirectPlay 의 신뢰성의 높은 코드를 사용하는 것이 가능하게 된다. 이것에 의해, 일반적으로 throughput와 전달의 양쪽 모두의 면에서 퍼포먼스가 향상한다.
DPSESSION_JOINDISABLED
새로운 어플리케이션이 이 세션에 참가할 수 없게 지정한다. IDirectPlay4::Open 메소드로 DPOPEN_JOIN 플래그를 설정해 호출하거나 또 이 세션의 인스턴스의 글로벌 유니크 식별자 (GUID)에 의해, 에러가 발생한다. 이 플래그가 지정되어 있지 않은 경우, 새로운 리모트 어플리케이션은 세션 플레이어의 제한에 이를 때까지 세션에 참가할 수 있다.
DPSESSION_KEEPALIVE
리모트 플레이어가 게임을 이상하게 퇴출 하면, 이 세션이 그것을 자동적으로 검출하도록(듯이) 지정한다. 그 플레이어는, 세션으로부터 삭제된다. 일시적인 네트워크의 용량 부족에보다 플레이어를 상실했을 경우, 그 플레이어에게는 돌아왔을 때에, 세션으로부터 퇴출 당했던 것이 DPMSG_SESSIONLOST 시스템 메세지에 의해 알게 된다. 이 플래그는, 세션이 생성 되었을 때에 지정할 필요가 있다. 이 플래그가 지정되어 있지 않은 경우, 플레이어가 이상종료(ABEND) 하면 DirectPlay 에 의해 그 세션이 자동적으로 유지되지 않는다.
DPSESSION_MIGRATEHOST
현재 호스트가 존재하는 경우에 세션내의 다른 컴퓨터가 호스트가 되도록(듯이) 지정한다. 새로운 호스트 컴퓨터의 플레이어는,DPMSG_HOST 시스템 메세지를 받아들인다. 이 플래그는, 세션이 생성 되었을 때에 지정할 필요가 있다. 이 플래그가 설정되어 있지 않은 경우, 호스트는 이행 하지 않고, 새로운 컴퓨터는 세션에 참가할 수 없다. 또, 현재 호스트가 퇴출 하면 새로운 플레이어를 생성 할 수 없다. DPSESSION_MIGRATEHOST 플래그는, DPSESSION_CLIENTSERVER 플래그, DPSESSION_MULTICASTSERVER 플래그, 또는 DPSESSION_SECURESERVER 플래그와 함께 사용할 수 없기 때문에 주의 해야 한다.
DPSESSION_MULTICASTSERVER
피어 투 피어 세션으로 브로드캐스트 메세지나 그룹 메세지가, 멀티 캐스트 서버와 같이 기능하는 호스트로부터 루팅 되도록(듯이) 지정한다. 이 플래그는, 세션이 생성 되었을 때에 지정할 필요가 있다. 이 플래그는, 호스트가 네트워크에 고대역폭으로 접속되고 있는 경우에게만 유용하다. 이 플래그가 지정되어 있지 않은 경우, 브로드캐스트 메세지나 그룹 메세지는 피어간에 직접 송신된다. 이 플래그는, DPSESSION_MIGRATEHOST 로 사용할 수 없다.
DPSESSION_NEWPLAYERSDISABLED
새로운 플레이어를 세션내에서 생성 할 수 없게 지정한다. 세션내의 어플리케이션이 IDirectPlay4::CreatePlayer 메소드를 호출하면, 에러가 발생한다. 또, 새로운 어플리케이션은 세션에 참가할 수 없다. 이 플래그가 지정되어 있지 않은 경우, 플레이어는, 세션 플레이어의 제한에 이를 때까지 생성 할 수 있다.
DPSESSION_NODATAMESSAGES
IDirectPlay4::SetPlayerData ,IDirectPlay4::SetGroupData ,IDirectPlay4::SetPlayerName ,IDirectPlay4::SetGroupName , 또는 IDirectPlay4::SetSessionDesc 메소드에 의해, 리모트 플레이어 데이터, 그룹 데이터, 또는 세션 데이터를 변경했을 때에, 세션으로 시스템 메세지를 송신하지 않게 지정한다. 플래그가 지정되어 있지 않은 경우, 데이터가 변경된 것을 나타내는 메세지가 생성된다.

다만, 이 플래그를 설정 하면 DPMSG_SETSESSIONDESC 메세지도 억제된다.

DPSESSION_NOMESSAGEID
세션으로, 메세지의 송신원이나 송신지의 플레이어를 나타내는 메세지를 데이터에 첨부하지 않게 지정한다. 이 플래그를 설정 하면, 이 정보가 관계없는 경우, 메세지의 오바헷드가 억제 당한다 (상세한 것에 대하여는,IDirectPlay4::Receive 메소드를 참조할것). 이 플래그가 지정되어 있지 않은 경우, 메세지 ID 가 추가된다. 이 플래그는, 세션이 생성 되었을 때에 지정할 필요가 있다.
DPSESSION_NOPRESERVEORDER
세션으로 보증 첨부 메세지의 수신 순서를 보관 유지하지 않게 지정한다. 디폴트에서는, 보증 첨부 메세지의 수신 순서가 보관 유지된다. 이 순서가 필요없는 경우, 이 플래그를 사용 하면, 전달시의 지연을 없앨 수가 있다.
DPSESSION_OPTIMIZELATENCY
서비스 프로바이더에지연 시간에 대해 최적화를 실시하도록(듯이) 요구한다 (TCP/IP 로나그링 기능을 오프로 한다). 디폴트에서는, 대역폭에 대해 최적화를 한다.
DPSESSION_PASSWORDREQUIRED
이 세션이 패스워드에 의해 보호되도록(듯이) 지정한다. 세션에 참가하고 싶은 어플리케이션은,IDirectPlay4::Open 호출로 패스워드를 지정할 필요가 있다. 이것은, 읽기 전용 플래그이다. 세션의 호스트로 NULL 이외의 패스워드가 지정되면(자), 이것은 DirectPlay 에 의해 자동적으로 설정된다.
DPSESSION_PRIVATE
이것이 Private 세션이라고 지정한다. 이것은, 요구에 NULL 이외의 일치하는 패스워드가 포함되지 않은 한, 열거 요구에 응답할 수 없다. 이 플래그가 지정되어 있지 않은 경우, 세션은 열거 요구에 응답한다.
DPSESSION_SECURESERVER
세션이, 열기 전에 인증 증명서를 요구하는 보증 서버를 호스트로 할 것 같게 지정한다. 호스트는, 세션이 생성 될 때 이 플래그를 지정할 필요가 있다. IDirectPlay4::SetSessionDesc 를 사용해도 다음에 변경할 수 없다. 이 플래그는, DPSESSION_MIGRATEHOST 플래그에서는 사용이 아니다.
guidInstance
세션 인스턴스의 GUID.
guidApplication
세션 인스턴스로 실행되고 있는 어플리케이션의 GUID. 이것은, DirectPlay 가 같은 어플리케이션을 실행하고 있는 그 외의 컴퓨터에게만 접속되도록(듯이), 어플리케이션을 일의에 식별한다. 이 멤버에 GUID_NULL 를 설정하면, 임의의 어플리케이션의 세션을 열거할 수 있다.
dwMaxPlayers
이 세션으로 허가되고 있는 플레이어의 최대수. 이 값이 0 때는, 최대수가 지정되어 있지 않은 것을 의미한다.
dwCurrentPlayers
세션내의 현재의 플레이어수.
lpszSessionName
세션의 이름이 저장 되고 있는 Unicode 캐릭터 라인에의 포인터. Unicode DirectPlay 인터페이스 (IDirectPlay4 인터페이스 )가 사용되고 있는 경우에게만 사용한다.
lpszSessionNameA
세션의 이름이 저장 되고 있는 ANSI 캐릭터 라인에의 포인터. ANSI DirectPlay 인터페이스 (IDirectPlay4A)가 사용되고 있는 경우에게만 사용한다.
lpszPassword
참가하기 위해서 세션에 참가할 경우에 사용되는 패스워드가 저장 되고 있는 Unicode 캐릭터 라인에의 포인터. Unicode DirectPlay 인터페이스 (IDirectPlay4 인터페이스 )가 사용되고 있는 경우에게만 사용한다.
lpszPasswordA
세션에 참가할 경우에 사용되는 패스워드가 저장 되고 있는 ANSI 캐릭터 라인에의 포인터. ANSI DirectPlay 인터페이스 (IDirectPlay4A)가 사용되고 있는 경우에게만 사용한다.
dwReserved1 및 dwReserved2
0 이 아니면 안된다.
dwUser1,dwUser2,dwUser3, 및 dwUser4
세션의 어플리케이션 고유의 데이터.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::EnumSessions ,IDirectPlay4::GetSessionDesc ,IDirectPlay4::Open ,IDirectPlay4::SecureOpen ,IDirectPlay4::SetSessionDesc ,IDirectPlay4::CreatePlayer


시스템 메세지

다음에, DirectPlay 의 시스템 메세지를 나타낸다.

  • DPMSG_ADDGROUPTOGROUP
  • DPMSG_ADDPLAYERTOGROUP
  • DPMSG_CHAT
  • DPMSG_CREATEPLAYERORGROUP
  • DPMSG_DELETEGROUPFROMGROUP
  • DPMSG_DELETEPLAYERFROMGROUP
  • DPMSG_DESTROYPLAYERORGROUP
  • DPMSG_GENERIC
  • DPMSG_HOST
  • DPMSG_SECUREMESSAGE
  • DPMSG_SENDCOMPLETE
  • DPMSG_SESSIONLOST
  • DPMSG_SETGROUPOWNER
  • DPMSG_SETPLAYERORGROUPDATA
  • DPMSG_SETPLAYERORGROUPNAME
  • DPMSG_SETSESSIONDESC
  • DPMSG_STARTSESSION


DPMSG_ADDGROUPTOGROUP

그룹이 그룹에 추가되면(자),DirectPlay 는 DPMSG_ADDGROUPTOGROUP 구조체를 생성해, 그것을 모든 플레이어에게 송신한다.

typedef struct{
    DWORD    dwType;
    DPID     dpIdParentGroup;
    DPID     dpIdGroup;
} DPMSG_ADDGROUPTOGROUP, FAR *LPDPMSG_ADDGROUPTOGROUP;
dwType
메세지를 식별한다. 이 멤버는, DPSYS_ADDGROUPTOGROUP 이다.
dpIdParentGroup
그룹의 추가처 그룹의 ID.
dpIdGroup
그룹에 추가된 그룹의 ID.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::AddGroupToGroup


DPMSG_ADDPLAYERTOGROUP

DPMSG_ADDPLAYERTOGROUP 구조체에는, DPSYS_ADDPLAYERTOGROUP 시스템 메세지에 관한 정보가 저장 된다. 플레이어가 그룹에 추가되면(자), DirectPlay 는 이 메세지를 생성해, 그것을 모든 플레이어에게 송신한다.

이 어플리케이션에서는, 이 메세지의 IDirectPlay4::GetPlayerCaps ,IDirectPlay4::GetPlayerName , 및 IDirectPlay4::GetPlayerData 를 사용해 기동된 플레이어의 정보를 취득하거나 또는 이 메세지의 IDirectPlay4::GetGroupName 나 IDirectPlay4::GetGroupData 를 사용해 기동된 그룹의 상세 정보를 취득할 수 있다.

typedef struct{
    DWORD dwType;
    DPID  dpIdGroup;
    DPID  dpIdPlayer;
} DPMSG_ADDPLAYERTOGROUP, FAR *LPDPMSG_ADDPLAYERTOGROUP;
dwType
메세지를 식별한다. 이 멤버는, DPSYS_ADDPLAYERTOGROUP 이다.
dpIdGroup
플레이어의 추가처 그룹의 ID.
dpIdPlayer
그룹에 추가되는 플레이어의 ID.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::AddPlayerToGroup


DPMSG_CHAT

DPMSG_CHAT 구조체는, DPSYS_CHAT 시스템 메세지에 관한 정보를 보관 유지한다. 이 시스템 메세지는, 다른 플레이어로부터 채팅 메세지를 받아들인 로컬 플레이어에 대해서 생성된다.

typedef struct{
    DWORD dwType;
    DWORD dwFlags;
    DPID  idFromPlayer;
    DPID  idToPlayer;
    DPID  idToGroup;
    LPDPCHAT  lpChat;
} DPMSG_CHAT, FAR *LPDPMSG_CHAT;
dwType
메세지를 식별한다. 이 멤버에는, DPSYS_CHAT 값이 설정된다.
dwFlags
사용하지 않는다.
idFromPlayer
메세지의 송신원플레이어의 ID. DPID_SERVERPLAYER 는, 메세지의 발신기지가 서버인 것을 나타내고 있다.
idToPlayer
메세지의 송신지 플레이어의 ID. 이 값이 0 의 경우, 메세지는 그룹에 송신되는지, 또는 모두에게 브로드캐스트 된다.
idToGroup
메세지의 송신지 그룹의 ID. 이 값이 0 으로, 또 idToPlayer 도 0 의 경우, 메세지는 모두에게 브로드캐스트 된다.
lpChat
수신한 채팅 메세지의 컨텐츠가 저장 되고 있는 DPCHAT 구조체에의 포인터.

주의

이 idFromPlayer 값을 사용해, 메세지의 송신원을 판정한다. Receive 로 사용 가능한 lpidFrom 의 값은 항상 0 이므로,DPMSG_CHAT 구조체의 idFromPlayer 의 값을 취득할 필요가 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::SendChatMessage ,DPCHAT ,IDirectPlay4::Receive


DPMSG_CREATEPLAYERORGROUP

DPMSG_CREATEPLAYERORGROUP 구조체는, DPSYS_CREATEPLAYERORGROUP 시스템 메세지에 관한 정보를 보관 유지한다. 플레이어나 그룹이 세션으로 생성 되면(자), 시스템에 의해 이 메세지가 생성된다.

DirectPlay 는, 새로운 플레이어나 그룹이 세션으로 생성 되면(자), 이 메세지를 생성해 각 플레이어에게 송신한다.

typedef struct{
    DWORD  dwType;
    DWORD  dwPlayerType;
    DPID   dpId;
    DWORD  dwCurrentPlayers;
    LPVOID lpData;
    DWORD  dwDataSize;
    DPNAME dpnName;
    DPID   dpIDParent;
    DWORD  dwFlags;
} DPMSG_CREATEPLAYERORGROUP, FAR *LPDPMSG_CREATEPLAYERORGROUP;
dwType
메세지를 식별하는 DWORD. 이 멤버에는, DPSYS_CREATEPLAYERORGROUP 를 설정하는 것.
dwPlayerType
메세지를 플레이어 (DPPLAYERTYPE_PLAYER) 또는 그룹 (DPPLAYERTYPE_GROUP)의 머지않아에 적용하는지를 지정하는 DWORD.
dpId
생성 하는 플레이어 또는 그룹의 ID.
dwCurrentPlayers
세션내의 플레이어수.
lpData
이 플레이어나 그룹에 관련지을 수 있고 있는 어플리케이션에 고유의 리모트 데이터에의 포인터. 이 멤버가 NULL 의 경우, 리모트 데이터는 없다.
dwDataSize
lpData 에 의해 참조되는 버퍼에 저장 되고 있는 데이터의 사이즈.
dpnName
플레이어나 그룹의 이름이 저장 되고 있는 구조체.
dpIDParent
IDirectPlay4::CreateGroupInGroup 를 호출했기 때문에 이 메세지가 생성되었을 경우는 친그룹의 ID. 그 이외의 경우, 이 값은 0 이 된다.
dwFlags
플레이어 또는 그룹의 플래그.
DPGROUP_HIDDEN
은폐 그룹이 생성 될 때, 설정된다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::CreateGroup ,IDirectPlay4::CreatePlayer ,IDirectPlay4::CreateGroupInGroup


DPMSG_DELETEGROUPFROMGROUP

DirectPlay 는, 그룹이 그룹으로부터 삭제되면(자),DPMSG_DELETEGROUPFROMGROUP 구조체를 생성해, 그것을 모든 플레이어에게 송신한다. 이 구조체는 DPMSG_ADDGROUPTOGROUP 와 같다 것으로 주의 해야 한다.

typedef struct{
    DWORD    dwType;
    DPID     dpIdParentGroup;
    DPID     dpIdGroup;
} DPMSG_ADDGROUPTOGROUP, FAR *LPDPMSG_ADDGROUPTOGROUP;
typedef DPMSG_ADDGROUPTOGROUP DPMSG_DELETEGROUPFROMGROUP;
dwType
메세지를 식별한다. 이 멤버는, DPSYS_DELETEGROUPFROMGROUP 이다.
dpIdParentGroup
그룹을 삭제하는 그룹의 ID.
dpIdGroup
그룹으로부터 삭제되는 그룹의 ID.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::DeleteGroupFromGroup


DPMSG_DELETEPLAYERFROMGROUP

DPMSG_DELETEPLAYERFROMGROUP 구조체는, DPSYS_DELETEPLAYERFROMGROUP 시스템 메세지에 관한 정보를 보관 유지한다. DirectPlay 는, 플레이어가 그룹으로부터 삭제되면(자), 이 메세지를 생성해, 그것을 컴퓨터 위에의 각 로컬 플레이어에게 송신한다.

구조체의 멤버에 대해서는,DPMSG_ADDPLAYERTOGROUP 구조체를 참조할것.

이 어플리케이션에서는, 이 메세지의 IDirectPlay4::GetPlayerCaps ,IDirectPlay4::GetPlayerName , 및 IDirectPlay4::GetPlayerData 를 사용해 기동된 플레이어의 정보를 취득하거나 또는 이 메세지의 IDirectPlay4::GetGroupName 나 IDirectPlay4::GetGroupData 를 사용해 기동된 그룹의 상세 정보를 취득할 수 있다.

typedef struct{
    DWORD dwType;
    DPID  dpIdGroup;
    DPID  dpIdPlayer;
} DPMSG_ADDPLAYERTOGROUP, FAR *LPDPMSG_ADDPLAYERTOGROUP;
typedef DPMSG_ADDPLAYERTOGROUP DPMSG_DELETEPLAYERFROMGROUP;
dwType
메세지를 식별한다. 이 멤버는, DPSYS_DELETEPLAYERFROMGROUP 이다.
dpIdGroup
플레이어를 삭제하는 그룹의 ID.
dpIdPlayer
그룹으로부터 삭제되는 플레이어의 ID.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::DeletePlayerFromGroup


DPMSG_DESTROYPLAYERORGROUP

DPMSG_DESTROYPLAYERORGROUP 구조체는, DPSYS_DESTROYPLAYERORGROUP 시스템 메세지에 관한 정보를 보관 유지한다. DirectPlay 는, 플레이어나 그룹이 세션내에서 망가지면(자), 이 메세지를 생성해, 각 플레이어에게 송신한다.

typedef struct{
    DWORD  dwType;
    DWORD  dwPlayerType;
    DPID   dpId;
    LPVOID lpLocalData;
    DWORD  dwLocalDataSize;
    LPVOID lpRemoteData;
    DWORD  dwRemoteDataSize;
    DPNAME dpnName;
    DPID   dpIdParent;
    DWORD  dwFlags;
} DPMSG_DESTROYPLAYERORGROUP, FAR *LPDPMSG_DESTROYPLAYERORGROUP;
dwType
메세지를 식별하는 DWORD. 이 멤버는, DPSYS_DESTROYPLAYERORGROUP 이다.
dwPlayerType
메세지를 플레이어 (DPPLAYERTYPE_PLAYER) 또는 그룹 (DPPLAYERTYPE_GROUP)의 머지않아에 적용하는지를 지정하는 DWORD.
dpId
부수어진 플레이어 또는 그룹의 ID.
lpLocalData
이 플레이어 또는 그룹에 관련지을 수 있었던 로컬 데이터에의 포인터.
dwLocalDataSize
로컬 데이터의 사이즈 (바이트 단위).
lpRemoteData
이 플레이어 또는 그룹에 관련지을 수 있었던 리모트 데이터에의 포인터.
dwRemoteDataSize
리모트 데이터의 사이즈 (바이트 단위).
dpnName
플레이어나 그룹의 이름이 저장 되고 있는 구조체.
dpIdParent
부수어진 그룹이 친그룹의 서브 그룹의 경우, 즉 부수어진 그룹이 IDirectPlay4::CreateGroupInGroup 를 호출해 생성 되었을 경우, 친그룹의 ID. 그 이외의 경우, 이 값은 0 이 된다.
dwFlags
플레이어 또는 그룹의 플래그. 다음의 값의 언젠가, 또는 몇개인가가 된다.
DPGROUP_HIDDEN
은폐 그룹이 망가졌을 때, 설정된다.
DPGROUP_STAGINGAREA
staging 영역인 그룹이 망가졌을 때, 설정된다.
DPPLAYER_SERVERPLAYER
망가진 플레이어가 클라이언트/서버 통신의 서버 플레이어 때, 설정된다.
DPPLAYER_SPECTATOR
망가진 플레이어가 관객 때, 설정된다.

주의

DirectX 5.0 에서는, 이 구조체의 버젼으로 dpnName,dpIdParent,dwFlags 의 3 개의 멤버가 마지막에 추가되고 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::DestroyGroup ,IDirectPlay4::DestroyPlayer


DPMSG_GENERIC

DPMSG_GENERIC 구조체는, 메세지 처리를 위해서(때문에) 제공되고 있다.

typedef struct{
    DWORD dwType;
} DPMSG_GENERIC, FAR *LPDPMSG_GENERIC;
dwType
시스템 메세지의 타입을 식별한다. 타입 리스트에 대해서는,시스템 메세지의 사용 을 참조할것.

주의

시스템 메세지를 받아들이면(자) (즉,lpidFrom 파라미터에 의해 포인트 되고 있는 값이 DPID_SYSMSG 이라고), 우선 미확인의 메세지 데이터를 DPMSG_GENERIC 형으로 설정해, 한층 더 dwType 의 값에 근거해 처리를 실행한다. 메세지 타입이 판정된 후, 그 메세지는, 한층 더 처리하기 위해서 시스템 메세지의 기존의 타입의 어느 쪽인가에 설정할 수 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.


DPMSG_HOST

현재 세션의 호스트가 세션을 종료 하면, 호스트의 일을 계승하는 컴퓨터 위에의 모든 플레이어에게 DPMSG_HOST 메세지가 송신된다.

typedef DPMSG_GENERIC    DPMSG_HOST;
typedef DPMSG_HOST  FAR *LPDPMSG_HOST;

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

DPMSG_GENERIC


DPMSG_SECUREMESSAGE

DirectPlay 는, 다른 플레이어로부터 서명 첨부 메세지 또는 암호화 메세지를 받아들이면(자) DPMSG_SECUREMESSAGE 구조체를 생성한다.

typedef struct {
    DWORD   dwType;
    DWORD   dwFlags;
    DPID    dpIdFrom;
    LPVOID  lpData;
    DWORD   dwDataSize;
} DPMSG_SECUREMESSAGE, FAR *LPDPMSG_SECUREMESSAGE;
dwType
시스템 메세지의 타입을 식별한다. 이것은, DPSYS_SECUREMESSAGE 가 된다.
dwFlags
송신자에 의한 메세지의 보호 방법을 나타내는 플래그. 다음의 값의 언젠가된다.
DPSEND_SIGNED
메세지는 송신자에 의해 서명되고 있어 그 서명은 검증이 끝난 상태이다.
DPSEND_ENCRYPTED
메세지는 송신자에 의해 암호화되고 있어 정상적으로 해독되었다.
dpIdFrom
기밀 보호 메세지를 송신한 플레이어의 DPID.
lpData
완전하게 검증된 메세지가 저장 된 버퍼에의 포인터.
dwDataSize
메세지가 저장 되고 있는 버퍼의 사이즈.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::Send


DPMSG_SENDCOMPLETE

DPMSG_SENDCOMPLETE 구조체는, 어플리케이션에 비동기 송신의 완료 스테이터스를 알리기 위해서(때문에) 수신 큐에 송신된다. 디폴트에서는, 비동기 메세지가 IDirectPlay4::SendEx 의 DPSEND_ASYNC 플래그를 사용해 송신되면(자), 이 메세지가 생성된다.

typedef struct{
    DWORD    dwType;
    DPID     idFrom;
    DPID     idTo;
    DWORD    dwFlags;
    DWORD    dwPriority;
    DWORD    dwTimeout;
    LPVOID   lpContext;
    DWORD    dwMsgID;
    HRESULT  hr;
    DWORD    dwSendTime;
} DPMSG_SENDCOMPLETE, FAR *LPDPMSG_SENDCOMPLETE;
dwType
메세지를 식별하는 값. 이 멤버는, DPSYS_SENDCOMPLETE 이다.
idFrom
메세지를 송신하는 플레이어의 DPID.
idTo
메세지의 송신지 플레이어의 DPID.
dwFlags
메세지가 송신되었을 때에 SendEx 로 지정된 플래그.
dwPriority
메세지 송신시의 우선 순위.
dwTimeout
메세지 송신시로 지정된 타임 아웃 (SendEx 로 지정). 0 은, 디폴트의 타임 아웃을 나타낸다.
lpContext
어플리케이션에 의해 SendEx 에게 건네지는 lpContext 파라미터.
dwMsgID
DirectPlay 에 의해 SendEx 로부터 어플리케이션에 돌려주어지는 dwMsgID.
hr
비동기 메세지의 HRESULT. 다음의 값의 언젠가된다.
DP_OK
메세지는 정상적으로 송신되었다.
DPERR_ABORTED
메세지는, 전송시에 삭제되었다.
DPERR_CANCELLED
메세지는, 아직 송신 큐에 있을 때 삭제되었다.
DPERR_GENERIC
메세지는 송신할 수 없었다.
DPERR_TIMEOUT
메세지는 마감 시간이 되어, 송신 큐로부터 삭제되었다.
dwSendTime
어플리케이션이 메세지를 (SendEx 를 호출하는 것으로) 송신하고 나서, DirectPlay 가 메세지를 송신할 수 있을 때까지의 경과시간 (밀리 세컨드 단위). 이것에는, 송신 큐에서의 경과시간이나, 서비스 프로바이더에 메세지를 건네주기 위한 시간도 포함된다. 보증 첨부 메세지의 경우는, 메세지 전달의 긍정 응답을 돌려주기 위한 시간도 포함된다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::SendEx


DPMSG_SESSIONLOST

DPMSG_SESSIONLOST 구조체는, 세션내의 그 외 모든 플레이어에게로의 접속이 상실했을 때에 DirectPlay 에 의해 생성된다. 세션이 상실한 후는, 메세지를 리모트 플레이어에게 송신할 수 없지만, 세션 상실시의 데이터는 모두 아직 사용할 수 있다. 이 메세지를 받아들이면(자), 어플리케이션으로 회복을 시도해, 종료하는 것.

typedef DPMSG_GENERIC    DPMSG_SESSIONLOST;
typedef DPMSG_SESSIONLOST  FAR  *LPDPMSG_SESSIONLOST;

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

DPMSG_GENERIC


DPMSG_SETGROUPOWNER

DPMSG_SETGROUPOWNER 구조체는, 그룹의 소유자가 변경되었을 때에 DirectPlay 에 의해 생성된다. 그룹의 소유권은, 현재의 소유자가 세션을 퇴출 하거나IDirectPlay4::SetGroupOwner 를 호출한 것에 의해, 또는 임의로 로비 세션의 로비 서버에 의해 변경된다.

typedef struct{
  DWORD   dwType;
  DPID    idGroup;
  DPID    idNewOwner;
  DPID    idOldOwner;
} DPMSG_SETGROUPOWNER, FAR *LPDPMSG_SETGROUPOWNER;
dwType
메세지를 식별하는 값. 이 멤버는, DPSYS_SETGROUPOWNER 이다.
idGroup
소유자가 변경된 그룹의 ID.
idNewOwner
그룹의 새로운 소유자인 플레이어의 ID.
idOldOwner
그룹의 낡은 소유자인 플레이어의 ID.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::SetGroupOwner


DPMSG_SETPLAYERORGROUPDATA

DPMSG_SETPLAYERORGROUPDATA 메세지 구조체는, DPSYS_SETPLAYERORGROUPDATA 시스템 메세지에 관한 정보를 보관 유지한다. DirectPlay 는, 플레이어나 그룹의 리모트 데이터가 변경되면(자), 이 메세지를 생성해 각 플레이어에게 송신한다. 이 메세지는, 세션 기술로 DPSESSION_ NODATAMESSAGES 플래그가 지정되고 있는 경우는 생성되지 않는다.

typedef struct {
    DWORD  dwType;
    DWORD  dwPlayerType;
    DPID   dpId;
    LPVOID lpData;
    DWORD  dwDataSize;
} DPMSG_SETPLAYERORGROUPDATA, FAR *LPDPMSG_SETPLAYERORGROUPDATA;
dwType
메세지를 식별한다. 이 값은, 항상 DPSYS_SETPLAYERORGROUPDATA 이다.
dwPlayerType
메세지를 플레이어 (DPPLAYERTYPE_PLAYER) 또는 그룹 (DPPLAYERTYPE_GROUP)의 머지않아에 적용할지 어떨지를 식별한다.
dpId
데이터가 변경되는 플레이어 또는 그룹의 ID.
lpData
데이터의 어플리케이션 고유의 블록에의 포인터.
dwDataSize
lpData 에 의해 참조되는 버퍼에 저장 되고 있는 데이터의 사이즈.

주의

데이터는 IDirectPlay4::GetPlayerData 또는 IDirectPlay4::GetGroupData 를 사용 자제개에서도 취득할 수 있으므로, 어플리케이션이 이 메세지로부터 데이터를 보존할 필요는 없다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::SetPlayerData ,IDirectPlay4::SetGroupData


DPMSG_SETPLAYERORGROUPNAME

DPMSG_SETPLAYERORGROUPNAME 구조체는, DPSYS_SETPLAYERORGROUPNAME 시스템 메세지에 관한 정보를 보관 유지한다. DirectPlay 는, 플레이어 또는 그룹의 이름이 변경되면(자), 이 메세지를 생성해, 컴퓨터 위에의 각 로컬 플레이어에게 송신한다. 이 메세지는, 세션 기술로 DPSESSION_NODATAMESSAGES 플래그가 지정되고 있는 경우는 생성되지 않는다.

typedef struct {
    DWORD  dwType;
    DWORD  dwPlayerType;
    DPID   dpId;
    DPNAME dpnName;
} DPMSG_SETPLAYERORGROUPNAME, FAR *LPDPMSG_SETPLAYERORGROUPNAME;
dwType
메세지를 식별한다. 이 값은, 항상 DPSYS_SETPLAYERORGROUPNAME 가 된다.
dwPlayerType
메세지를 플레이어 (DPPLAYERTYPE_PLAYER) 또는 그룹 (DPPLAYERTYPE_GROUP)의 머지않아에 적용할지 어떨지를 식별한다.
dpId
이름이 변경되는 플레이어 또는 그룹의 ID.
dpnName
플레이어 또는 그룹의 새로운 이름 정보가 저장 되고 있는 구조체.

주의

dpnName 는 IDirectPlay4::GetPlayerName 또는 IDirectPlay4::GetGroupName 를 사용 자제개에서도 취득할 수 있으므로, 어플리케이션이 이 메세지로부터 그것을 보존할 필요는 없다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::GetPlayerName ,IDirectPlay4::GetGroupName ,IDirectPlay4::SetPlayerName ,IDirectPlay4::SetGroupName


DPMSG_SETSESSIONDESC

DPMSG_SETSESSIONDESC 는, DPSYS_SETSESSIONDESC 시스템 메세지에 관한 정보를 보관 유지한다. 세션 기술이 변경되면(자), 모든 플레이어가 이 시스템 메세지를 받아들인다.

이 메세지는, 세션 기술로 DPSESSION_NODATAMESSAGES 플래그가 지정되고 있는 경우는 생성되지 않는다.

typedef struct {
    DWORD           dwType;
    DPSESSIONDESC2  dpDesc;
} DPMSG_SETSESSIONDESC, FAR *LPDPMSG_SETSESSIONDESC;
dwType
메세지를 식별한다. 이 값은, 항상 DPSYS_SETSESSIONDESC 가 된다.
dpDesc
갱신된 세션 기술이 저장 되고 있는 DPSESSIONDESC2 구조체에의 포인터.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::GetSessionDesc ,IDirectPlay4::SetSessionDesc


DPMSG_STARTSESSION

DPMSG_STARTSESSION 메세지 구조체는, DPSYS_STARTSESSION 시스템 메세지에 관한 정보를 보관 유지한다. 로비 서버는, 플레이어가 어플리케이션 세션에 참가하는 시간이 되면(자), 그 그룹의 각 플레이어에게 이 메세지를 송신한다.

typedef struct {
   DWORD            dwType;
   LPDPLCONNECTION  lpConn;
} DPMSG_STARTSESSION, FAR *LPDPMSG_STARTSESSION;
dwType
메세지를 식별한다. 이 값은, 항상 DPSYS_STARTSESSION 가 된다.
lpConn
세션으로 어플리케이션을 기동하는데 필요한 모든 정보가 저장 되고 있는 DPLCONNECTION 구조체에의 포인터. 이 구조체를 IDirectPlayLobby3::RunApplication 에 건네주거나 (외부 어플리케이션이 기동되는 경우),IDirectPlayLobby3::SetConnectionSettings 에 건네준 후,IDirectPlayLobby3::Connect 가 불려 간다 (현재 어플리케이션을 세션에 접속하기 위해(때문에)).

주의

standalone의 로비 클라이언트가 이 메세지를 받아들였을 경우, 클라이언트는 DPLCONNECTION 구조체를 사용해 IDirectPlayLobby3::RunApplication 메소드를 호출해, 어플리케이션을 기동할 필요가 있다.

내부 로비에서 어플리케이션이 이 메세지를 받아들였을 경우, 그 어플리케이션은 IDirectPlayLobby3::SetConnectionSettings 메소드를 호출해 접속 설정을 설정하고 나서,IDirectPlayLobby3::Connect 메소드를 사용해 세션에 접속할 필요가 있다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplay.h 로 선언.

참조

IDirectPlay4::StartSession ,IDirectPlayLobby3::RunApplication ,IDirectPlayLobby3::SetConnectionSettings ,IDirectPlayLobby3::Connect


표준 로비 메세지

어플리케이션을 기동한 로비에서 표준 로비 메세지가 지원 되고 있는지 어떤지를 판정하려면 , 로비에 최초로 DPLMSG_GETPROPERTY 요구를 송신해, 거기에 응답이 있을지 어떨지를 조사한다. 요구하는 프로퍼티는,DPLPROPERTY_MessagesSupported 이다.

로비로부터의 응답이 TRUE 였을 경우, 그 이후의 메세지에도 모두 응답이 돌려주어진다고 보는 것으로 온다. 응답이 FALSE 인지, 또는 지정된 타임 아웃의 시간내에 전혀 응답이 없었던 경우, 그 메세지는 지원되어 있지 않다고 보여진다.

어플리케이션은, 관객 플레이어를 지원 하고 있는 경우, 플레이어를 생성 하면 와, 그 전에 그것을 관객으로서 생성 할지 어떨지를 판정하기 위해서 DPLPROPERTY_PlayerGuid 를 요구하는 일도 필요하다.

다음에, DirectPlay 표준 로비 메세지를 나타낸다.

  • DPLMSG_GENERIC
  • DPLMSG_GETPROPERTY
  • DPLMSG_GETPROPERTYRESPONSE
  • DPLMSG_NEWSESSIONHOST
  • DPLMSG_SETPROPERTY
  • DPLMSG_SETPROPERTYRESPONSE
  • DPLMSG_SYSTEMMESSAGE

참조

로비 메세지의 사용,로비와의 관계의 유지


DPLMSG_GENERIC

DPLMSG_GENERIC 는,로비 클라이언트와 어플리케이션의 사이에 송수신 되는 시스템 메세지의 범용 구조체이다.

typedef struct {
    DWORD dwType;
} DPLMSG_GENERIC, FAR *LPDPLMSG_GENERIC;
dwType
수신된 시스템 메세지의 타입을 식별한다.

주의

로비 시스템 메세지가 수신되면(자) (즉,lpidFrom 파라미터에 의해 포인트 된 값이 DPID_SYSMSG 이라고), 우선 미확인의 메세지 데이터를 DPLMSG_GENERIC 형에 캐스트 해, 한층 더 dwType 의 값에 근거해 처리를 실행한다. 메세지 타입이 판정된 후, 그 메세지는, 한층 더 처리하기 위해서 로비 시스템 메세지의 기존의 타입의 어느 쪽인가에 설정할 수 있다.

로비 메세지의 타입 리스트에 대해서는,로비 메세지의 사용 을 참조할것.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.

참조

DPLMSG_SYSTEMMESSAGE


DPLMSG_GETPROPERTY

DPLMSG_GETPROPERTY 메세지는, 어플리케이션에 의해, 프로퍼티의 현재의 값을 요구하기 위해서 송신된다. 이러한 프로퍼티는, 플레이어의 랭킹, 플레이어를 나타내는 비트 맵, 또는 로비내에서 행해진 게임이나 플레이어의 초기 구성 정보등의 정보이기도 하다.

typedef struct {
    DWORD   dwType;
    DWORD   dwRequestID;
    GUID    guidPlayer;
    GUID    guidPropertyTag;
} DPLMSG_GETPROPERTY, FAR *LPDPLMSG_GETPROPERTY;
dwType
메세지를 식별한다. 이 값은, DPLSYS_ GETPROPERTY 이다.
dwRequestID
요구를 식별하기 위해서 어플리케이션에 의해 생성된 ID. 로비로부터 응답이 돌려주어질 때, 이 요구 ID 가 설정되어 있다. 어플리케이션은, 이 요구 ID 를 사용해, 응답을 보류 상태의 요구와 조합할 수 있다.
guidPlayer
이 프로퍼티가 적용되는 (적용 가능한 경우) 플레이어를 식별하는 GUID. 프로퍼티가 플레이어에게 고유하지 않은 경우, 이 멤버에는 GUID_NULL 가 설정된다. 이 어플리케이션에 의해 생성된 플레이어의 GUID 는,DPLPROPERTY_PlayerGuid 프로퍼티를 요구하는 것으로써 로비로부터 취득할 수 있다.
guidPropertyTag
요구된 프로퍼티를 식별하는 GUID. 이 프로퍼티는 「DirectPlay 정의가 끝난 프로퍼티」에 나타내고 있는 사전에 정의된 GUID 의 언젠가인지, 또는 어플리케이션이나 로비에 의해 추가 프로퍼티에 독자적인 GUID 를 정의할 수도 있다.」

주의

각 프로퍼티는, GUID (어플리케이션 개발자 또는 로비 개발자에 의해 정의된다)에 의해 식별된다. 프로퍼티 요구를 하면(자), 로비는 DPLMSG_GETPROPERTYRESPONSE 메세지를 사용해 응답을 돌려준다. 로비는, 정보를 제공할 수 없는 경우에서도, 그 정보가 사용 불가능한 것을 나타내는 에러를 돌려준다.

어플리케이션에서는, 응답을 대기하는 것이 아니라, 보류 상태의 요구가 채워지지 않으면 그것들을 마감 시간에 해야 한다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.

참조

DPLMSG_GETPROPERTYRESPONSE


DPLMSG_GETPROPERTYRESPONSE

DPLMSG_GETPROPERTYRESPONSE 메세지는, 로비에 의해,DPLMSG_GETPROPERTY 메세지에의 응답으로서 어플리케이션에 송신된다. 요구가 채워졌을 경우, 그 요구는 dwRequestID 멤버에 의해 식별된다.

typedef struct {
    DWORD    dwType;
    DWORD    dwRequestID
    GUID     guidPlayer;
    GUID     guidPropertyTag;
    HRESULT  hr;
    DWORD    dwDataSize;
    DWORD    dwPropertyData[1];
} DPLMSG_GETPROPERTYRESPONSE, FAR *LPDPLMSG_GETPROPERTYRESPONSE;
dwType
메세지를 식별한다. 이 값은, DPLSYS_ GETPROPERTYRESPONSE 이다.
dwRequestID
이 메세지의 응답처의 DPLMSG_GETPROPERTY 메세지를 식별하는 ID.
guidPlayer
이 프로퍼티가 적용되는 (적용 가능한 경우) 플레이어를 식별하는 GUID. 프로퍼티가 플레이어에게 고유하지 않은 경우, 이 멤버에는 GUID_NULL 가 설정된다. 이것은,DPLMSG_GETPROPERTY 메세지의 GUID 와 같다.
guidPropertyTag
요구된 프로퍼티를 식별하는 GUID. 이것은,DPLMSG_GETPROPERTY 메세지의 GUID 와 같다.
hr
프로퍼티 취득 요구의 귀가 코드. 다음의 값의 언젠가이다.
DP_OK
프로퍼티는 정상적으로 돌려주어졌다.
DPERR_UNKNOWNMESSAGE
요구된 프로퍼티는, 로비에서는 확인되어 있지 않다.
DPERR_UNAVAILABLE
요구된 프로퍼티는, 사용 불가능한 상태이다.
dwDataSize
프로퍼티 데이터의 사이즈 (바이트 단위).
dwPropertyData
프로퍼티 데이터가 저장 되고 있는 가변 사이즈의 버퍼. 프로퍼티 태그는, 이 데이터의 해석 방법을 정의하고 있다.

주의

로비는, 모든 DPLMSG_GETPROPERTY 요구에 응답하는지, 또는 전혀 응답하지 않는다.

이 메세지를 구성 하면 와, 로비는 DPLMSG_GETPROPERTYRESPONSE 구조체와 완전한 프로퍼티 데이터를 보관 유지하는데 충분한 메모리를 할당할 필요가 있다. 예를 들어, 프로퍼티 데이터로 52 바이트가 필요한 경우, 로비는 (sizeof(DPLMSG_GETPROPERTYRESPONSE) + 52) 바이트를 할당해 그것을 DPLMSG_GETPROPERTYRESPONSE 포인터에 할당한다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.

참조

DPLMSG_GETPROPERTY


DPLMSG_NEWSESSIONHOST

DPLMSG_NEWSESSIONHOST 메세지는, 컴퓨터 위에의 클라이언트가 어플리케이션 세션의 새로운 호스트가 되었을 때, DirectPlay 에 의해 생성되어 로비 클라이언트/프로바이더에 송신된다.

typedef struct {
    DWORD    dwType;
    GUID     guidInstance;
} DPLMSG_NEWSESSIONHOST, FAR *LPDPLMSG_NEWSESSIONHOST;
dwType
메세지를 식별하는 값. 이 값은, DPLSYS_NEWSESSIONHOST 이다.
guidInstance
세션의 이 인스턴스의 글로벌 유니크 식별자 (GUID)를 식별하는 값.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.


DPLMSG_SETPROPERTY

DPLMSG_SETPROPERTY 메세지는, 특정의 플레이어의 프로퍼티 또는 세션의 프로퍼티가 변경된 것을 로비에 알리기 위해서(때문에), 어플리케이션에 의해 로비에 송신된다. 이러한 프로퍼티에는, 플레이어의 스코아나 상태로부터, 게임의 현재 레벨이나 세션의 현재 상태까지가 포함된다.

typedef struct {
    DWORD    dwType;
    DWORD    dwRequestID
    GUID     guidPlayer;
    GUID     guidPropertyTag;
    DWORD    dwDataSize;
    DWORD    dwPropertyData[1];
} DPLMSG_SETPROPERTY, FAR *LPDPLMSG_SETPROPERTY;
dwType
메세지를 식별한다. 이 값은, DPLSYS_SETPROPERTY 이다.
dwRequestID
데이터가 인식되어 적절히 설정된 것을 확인하고 싶은 경우에 어플리케이션에 의해 지정되는 0 이외의 요구 ID. 확인의 필요가 없는 경우는, 이것에는 DPL_NOCONFIRMATION 가 설정된다.
guidPlayer
이 프로퍼티가 적용되는 (적용 가능한 경우) 플레이어를 식별하는 GUID. 프로퍼티가 플레이어에게 고유하지 않은 경우, 이 멤버에는 GUID_NULL 가 설정된다. 이 어플리케이션에 의해 생성된 플레이어의 GUID 는,DPLPROPERTY_PlayerGuid 프로퍼티를 요구하는 것으로써 로비로부터 취득할 수 있다.
guidPropertyTag
설정된 프로퍼티를 식별하는 GUID. 이 프로퍼티는 「DirectPlay 정의가 끝난 프로퍼티」에 나타내고 있는 사전에 정의된 GUID 의 언젠가인지, 또는 어플리케이션이나 로비에 의해 추가 프로퍼티에 독자적인 GUID 를 정의할 수도 있다.
dwDataSize
프로퍼티 데이터의 사이즈 (바이트 단위).
dwPropertyData
프로퍼티 데이터가 저장 되고 있는 가변 사이즈의 버퍼. 프로퍼티 태그는, 이 데이터의 해석 방법을 정의하고 있다.

주의

각 프로퍼티는, GUID (어플리케이션 개발자 또는 로비 개발자에 의해 정의된다)에 의해 식별된다. 다양한 어플리케이션의 프로퍼티 GUID 로부터 그 기술이나 데이터 타입에의 맵핑을 보관 유지하는 것은, 로비의 역할이다. 로비 서버는, 정보에 근거해 처리하도록(듯이)도, 그것을 무시하도록(듯이)도 선택할 수 있다.

이 메세지를 구성 하면 와, 어플리케이션은 DPLMSG_SETPROPERTY 구조체와 완전한 프로퍼티 데이터를 보관 유지하는데 충분한 메모리를 할당할 필요가 있다. 예를 들어, 프로퍼티 데이터로 52 바이트가 필요한 경우, 어플리케이션은 (sizeof(DPLMSG_SETPROPERTY) + 52) 바이트를 할당해 그것을 LPDPLMSG_SETPROPERTY 포인터에 할당한다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dplobby.h 로 선언.

참조

DPLMSG_SETPROPERTYRESPONSE


DPLMSG_SETPROPERTYRESPONSE

DPLMSG_SETPROPERTYRESPONSE 메세지는,DPLMSG_SETPROPERTY 메세지의 확인으로서 로비에 의해 어플리케이션에 송신된다. 확인하는 메세지는,dwRequestID 멤버에 의해 식별된다.

typedef struct {
    DWORD    dwType;
    DWORD    dwRequestID
    GUID     guidPlayer;
    GUID     guidPropertyTag;
    HRESULT  hr;
} DPLMSG_SETPROPERTYRESPONSE, FAR *LPDPLMSG_SETPROPERTYRESPONSE;
dwType
메세지를 식별한다. 이 값은, DPLSYS_SETPROPERTYRESPONSE 이다.
dwRequestID
확인하는 DPLMSG_SETPROPERTY 메세지를 식별하는 ID.
guidPlayer
이 프로퍼티가 적용되는 (적용 가능한 경우) 플레이어를 식별하는 GUID. 프로퍼티가 플레이어에게 고유하지 않은 경우, 이 멤버에는 GUID_NULL 가 설정된다. 이 어플리케이션에 의해 생성된 플레이어의 GUID 는,DPLMSG_SETPROPERTY 메세지로부터의 GUID 와 같다.
guidPropertyTag
설정된 프로퍼티를 식별하는 GUID. 이것은,DPLMSG_SETPROPERTY 메세지의 GUID 와 같다.
hr
확인의 결과. 다음의 값의 언젠가이다.
DP_OK
프로퍼티는 정상적으로 설정되었다.
DPERR_ACCESSDENIED
로비에 의해 변경이 허가되어 있지 않은 프로퍼티를 설정하려고 했다.
DPERR_UNKNOWNMESSAGE
프로퍼티는, 로비에서 확인되어 있지 않다.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.

참조

DPLMSG_SETPROPERTY


DPLMSG_SYSTEMMESSAGE

DPLMSG_SYSTEMMESSAGE 구조체는, 로비와 어플리케이션간에 송수신 되는 시스템 메세지이다.

typedef struct {
    DWORD    dwType;
    GUID     guidInstance;
} DPLMSG_SYSTEMMESSAGE, FAR *LPDPLMSG_SYSTEMMESSAGE;
dwType
받은 시스템 메세지의 타입을 식별한다.
DPLSYS_APPTERMINATED
IDirectPlayLobby3::RunApplication 메소드에 의해 기동된 어플리케이션이 종료한 것을 나타낸다.
DPLSYS_CONNECTIONSETTINGSREAD
IDirectPlayLobby3::RunApplication 메소드에 의해 기동된 어플리케이션이 접속 설정을 읽어낸 것을 나타낸다.
DPLSYS_DPLAYCONNECTFAILED
IDirectPlayLobby3::RunApplication 메소드에 의해 기동된 어플리케이션으로 세션에의 접속이 실패한 것을 나타낸다.
DPLSYS_DPLAYCONNECTSUCCEEDED
IDirectPlayLobby3::RunApplication 메소드에 의해 기동된 어플리케이션이 세션을 생성 해, 다른 어플리케이션이 참가하기 위한 준비를 갖추었는지, 또는 세션에의 참가가 성공한 것을 나타낸다.
DPLSYS_NEWCONNECTIONSETTINGS
로비 클라이언트가 RunApplication 를 호출했을 때에 대기중의 어플리케이션이 발견된 것을 나타낸다. 대기중의 어플리케이션은, 이 때 GetConnectionSettings 에 의해 접속 설정을 읽어내,ConnectEx 를 사용해 세션에 참가할 수가 있다.
guidInstance
이 메세지가 대응하고 있는 DirectPlay 세션의 인스턴스를 식별하는 GUID.

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.


DirectPlay 정의가 끝난 프로퍼티

여기에서는, 어플리케이션에 의해 로비로부터 설정하거나 취득할 수 있는 사전에 정의된 프로퍼티에 대해 설명한다.

DPLMSG_GETPROPERTYRESPONSE 메세지를 받아들이면(자), 그 guidPropertyTag 멤버에는 프로퍼티를 식별하기 위한 정보가,dwPropertyData 멤버에는 프로퍼티 정보가 저장 되고 있다. 이 정보를 추출하려면 ,dwPropertyData 멤버에 적절한 값을 설정한다. 예를 들어, 다음의 루틴에서는 지정한 메세지로부터 DPLDATA_PLAYERGUID 구조체를 취득한다 (DPLPROPERTY_PlayerGuid 를 참조할것).

BOOL GetPlayerGuid(
        LPDPLMSG_GETPROPERTYRESPONSE lpPropertyResponseMsg,
        LPDPLDATA_PLAYERGUID lpPlayerGuid)
{
   if (IsEqualGUID(lpPropertyResponseMsg->guidPropertyTag,
           DPLPROPERTY_PlayerGuid))
   {
      *lpPlayerGuid = *((LPDPLDATA_PLAYERGUID)
              lpPropertyResponseMsg->dwPropertyData);
      return (TRUE);
   }
   else
   {
      return (FALSE);
   }
}

사전에 정의된 프로퍼티에 대해서는, 이하를 참조할것.

  • DPLPROPERTY_LobbyGuid
  • DPLPROPERTY_MessagesSupported
  • DPLPROPERTY_PlayerGuid
  • DPLPROPERTY_PlayerScore


DPLPROPERTY_LobbyGuid

DPLPROPERTY_LobbyGuid 는, 로비 소프트웨어를 식별할 경우에 사용한다. 어플리케이션이 커스텀 메세지를 사용해 특정의 로비와 상호 조작하도록(듯이) 설계되고 있는 경우, 로비를 식별할 경우에 이 프로퍼티를 사용.

다만, 가능한 한 많은 로비와 상호 조작할 수 있도록(듯이) 하기 위해서, 어플리케이션에서는 가능한 한 표준 메세지를 사용해야 한다.

이 프로퍼티의 경우,DPLMSG_GETPROPERTYRESPONSE 구조체의 dwPropertyData 멤버의 내용은 다음과 같이 된다.

GUID  guidLobby;

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.


DPLPROPERTY_MessagesSupported

DPLPROPERTY_MessagesSupported 는, 로비에서 표준 메세지가 지원 되고 있는지 어떤지를 나타내는 불리언 값이다. 어플리케이션은, 표준 메세지가 지원 되고 있는지 어떤지를 판정하기 위해서, 로비의 이 프로퍼티를 요구할 수 있다. 로비가 이 메세지에 응답하지 않았던 경우, 또는 FALSE 가 돌려주어졌을 경우, 어플리케이션에서는 표준 로비 메세지가 지원되어 있지 않다고 보여져 그 이후는 메세지를 송신하지 않는다. 로비로부터 TRUE 가 돌려주어졌을 경우, 어플리케이션은 지장 없고 표준 메세지를 로비에 송신해, 한층 더 로비의 프로퍼티를 문의한다.

이 프로퍼티의 경우,DPLMSG_GETPROPERTYRESPONSE 구조체의 dwPropertyData 멤버의 내용은 다음과 같다.

BOOL  fMessagesSupported;

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.


DPLPROPERTY_PlayerGuid

DPLPROPERTY_PlayerGuid 는, 어플리케이션의 로컬 플레이어를 일의에 식별할 경우에 사용한다. 플레이어의 GUID 를 필요로 하는 DPLMSG_SETPROPERTY 메세지나 DPLMSG_GETPROPERTY 메세지는, 로비와 통신할 경우에 이 값을 사용할 필요가 있다.

어플리케이션은, 다른 컴퓨터 위에의 리모트 플레이어의 프로퍼티를 조작할 수 있다. 어플리케이션은, 리모트 플레이어로부터 (로비로부터는 아니게) 플레이어의 GUID 를 취득하는 것만으로 좋다.

어플리케이션은 관객 플레이어를 지원 하고 있는 경우, 플레이어를 생성 할 경우에 사용하는 플래그 (존재하는 경우)를 판정하기 위해서, 플레이어를 생성 하기 전에 이 프로퍼티를 요구할 필요가 있다. 그 플래그는, DPPLAYER_SPECTATOR 나 DPPLAYER_SERVERPLAYER 등이다.

이 프로퍼티의 경우,DPLMSG_GETPROPERTYRESPONSE 구조체의 dwPropertyData 멤버의 내용은 다음과 같다.

typedef struct {
    GUID  guidPlayer;
    DWORD dwPlayerFlags;
} DPLDATA_PLAYERGUID, FAR *LPDPLDATA_PLAYERGUID;

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.


DPLPROPERTY_PlayerScore

DPLPROPERTY_PlayerScore 는, 로비에 복합 스코아값을 보고할 때 어플리케이션으로 사용할 수 있는 범용 구조체이다. 스코아가 적용되는 플레이어의 guidPlayer GUID 는, 이 프로퍼티를 설정하거나 취득할 경우에 지정해야 한다. 이 구조체에서는, 플레이어의 스코아를 집합적으로 나타낸 long 형 정수값의 임의의 리스트를 취급할 수가 있다. 어플리케이션은, 모든 스코아를 보관 유지하는데 충분한 메모리를 할당할 필요가 있다. 예를 들어, 스코아가 N 개의 정수로서 건네받았을 경우, 어플리케이션은 ( sizeof(DPLDATA_PLAYERSCORE) + N*sizeof(LONG) ) 바이트를 할당해 그 포인터를 LPDPLDATA_PLAYERSCORE 로 설정할 필요가 있다.

이 프로퍼티의 경우,DPLMSG_GETPROPERTYRESPONSE 구조체의 dwPropertyData 멤버의 내용은 다음과 같다.

typedef struct {
    DWORD   dwScoreCount;
    LONG    Score[1];
} DPLDATA_PLAYERSCORE, FAR *LPDPLDATA_PLAYERSCORE;

필요 조건

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : Dplobby.h 로 선언.
임포트 라이브러리 : dplayx.lib 를 사용.


반환값

에러는 부의 값으로 나타내져 그것들을 조합할 수 없다. 다음 표에,IDirectPlay4 인터페이스와 IDirectPlayLobby3 인터페이스의 모든 메소드에 의해 돌려주어지는 값을 나타낸다. 각 메소드에 의해 돌려주어지는 에러값에 대해서는, 개별의 메소드의 설명을 참조할것.

DirectPlay 샘플이 많게는,HRESULT 값을 DirectPlay 에러의 캐릭터 라인명으로 변환하는 GetDirectPlayErrStr 함수가 포함되어 있다. 개발자는, 진단 트레이스나 에러 리포트용으로 각자의 어플리케이션에 이 코드를 카피할 수 있다.

CLASS_E_NOAGGREGATION
DirectPlayCreate ,DirectPlayLobbyCreate , 또는 IDirectPlayLobby3::Connect 의 pUnkOuter 파라미터에, NULL 이외의 값이 건네받았다.
DP_OK
요구는 정상적으로 종료했다.
DPERR_ABORTED
조작은, 완료전에 삭제되었다.
DPERR_ACCESSDENIED
세션이 가득해 있는지, 또는 부정한 패스워드가 지정되었다.
DPERR_ACTIVEPLAYERS
기존의 액티브한 플레이어가 존재하고 있어, 요구된 조작을 실행할 수 없었다.
DPERR_ALREADYINITIALIZED
이 오브젝트는 이미 초기화되고 있다.
DPERR_APPNOTSTARTED
어플리케이션이 아직 기동되어 있지 않다.
DPERR_AUTHENTICATIONFAILED
지정된 패스워드 또는 증명서를 인증할 수 없었다.
DPERR_BUFFERTOOLARGE
데이터 버퍼가 너무 커 보존할 수 없다.
DPERR_BUFFERTOOSMALL
지정된 버퍼가, 요구된 데이터를 저장 하는데 충분한 크기가 아니다.
DPERR_BUSY
전송 매체가 Busy 상태이기 (위해)때문에, 메세지를 송신할 수 없다.
DPERR_CANCELFAILED
아마 메세지가 그룹의 멤버에 이미 송신되고 있는 그룹 메세지이기 위해서(때문에), 취소할 수가 없었다.
DPERR_CANCELLED
조작이 삭제되었다.
DPERR_CANNOTCREATESERVER
새로운 세션으로 서버를 생성 할 수 없다.
DPERR_CANTADDPLAYER
플레이어를 세션에 추가할 수 없다.
DPERR_CANTCREATEGROUP
새로운 그룹을 생성 할 수 없다.
DPERR_CANTCREATEPLAYER
새로운 플레이어를 생성 할 수 없다.
DPERR_CANTCREATEPROCESS
어플리케이션을 기동할 수 없다.
DPERR_CANTCREATESESSION
새로운 세션을 생성 할 수 없다.
DPERR_CANTLOADCAPI
증명서가 지정되지 않고, 또 암호화 서비스로 사용하는 CryptoAPI 패키지 (CAPI)를 로드할 수 없다.
DPERR_CANTLOADSECURITYPACKAGE
소프트웨어 시큐러티 패키지를 로드할 수 없다.
DPERR_CANTLOADSSPI
증명서가 지정되지 않고, 또 증명서를 요구하는 시큐러티 지원 프로바이더 인터페이스 (SSPI)를 로드할 수 없다.
DPERR_CAPSNOTAVAILABLEYET
DirectPlay 오브젝트의 능력이 아직 결정되어 있지 않다. 이 에러는, DirectPlay 오브젝트가 사용 가능한 대역폭과 지연 시간을 판정하기 위해서 폴링 할 필요가 있는 접속 솔루션에 이행 되고 있는 경우에 발생한다.
DPERR_CONNECTING
이 메소드는, 네트워크에 접속중이다. 어플리케이션은, 정상 종료를 나타내는 DP_OK 가 돌려주어질 때까지, 또는 다른 에러가 돌려주어질 때까지 이 메소드를 계속 사용한다.
DPERR_CONNECTIONLOST
데이터의 송신중에 서비스 프로바이더 접속이 리셋 되었다.
DPERR_ENCRYPTIONFAILED
요구된 정보가 디지털식에 암호화할 수 없었다. 메세지의 프라이버시를 보호하기 위해서 암호화 기능이 사용된다. 이 에러는, 시큐어 세션에게만 관계가 있다.
DPERR_ENCRYPTIONNOTSUPPORTED
DPSECURITYDESC 구조체로 요구된 암호화의 타입은 사용할 수 없다. 이 에러는, 시큐어 세션에게만 관계가 있다.
DPERR_EXCEPTION
요구 처리시에 예외가 발생했다.
DPERR_GENERIC
미정도리 에러 조건이 발생했다.
DPERR_INVALIDFLAGS
이 메소드에게 건네진 플래그가 무효였다.
DPERR_INVALIDGROUP
그룹 ID 가, 이 게임 세션의 유효한 그룹 ID 로서 인식되지 않는다.
DPERR_INVALIDINTERFACE
인터페이스 파라미터가 무효이다.
DPERR_INVALIDOBJECT
DirectPlay 오브젝트 포인터가 무효이다.
DPERR_INVALIDPARAMS
메소드에게 건네진 파라미터의 언젠가 또는 몇개인가가 무효이다.
DPERR_INVALIDPASSWORD
패스워드가 필요한 세션에 참가하려고 했을 때에, 무효인 패스워드가 지정되었다.
DPERR_INVALIDPLAYER
플레이어 ID 가 이 게임 세션의 유효한 플레이어 ID 로서 인식되지 않는다.
DPERR_INVALIDPRIORITY
지정된 우선 순위가, 허가되고 있는 우선 순위의 범위 (0 이상 65535 이하) 외이다.
DPERR_LOGONDENIED
증명서가 요구되고 있는데, 증명서가 지정되어 있지 않은지, 또는 증명서가 무효이기 (위해)때문에, 세션을 열 수가 없었다.
DPERR_NOCAPS
DirectPlay 가 사용하려고 하고 있는 통신 링크에서는, 이 기능을 사용할 수 없다.
DPERR_NOCONNECTION
통신 링크가 확립되지 않았다.
DPERR_NOINTERFACE
인터페이스가 지원되어 있지 않다.
DPERR_NOMESSAGES
수신 큐에 메세지가 없다.
DPERR_NONAMESERVERFOUND
네임서버- (호스트)를 찾아낼 수가 없었는지, 생성 할 수 없었다. 플레이어를 생성 하려면 , 호스트가 존재하고 있지 않으면 안 된다.
DPERR_NONEWPLAYERS
세션은, 새로운 플레이어를 받아들이지 않았다.
DPERR_NOPLAYERS
세션내에 액티브한 플레이어가 없다.
DPERR_NOSESSIONS
이 게임에 대응하는 기존의 세션이 없다.
DPERR_NOTLOBBIED
어플리케이션이 IDirectPlayLobby3::RunApplication 메소드를 사용해 기동되지 않았던 경우, 또는 이 DirectPlayLobby 오브젝트에 대해서 현재 초기화되고 있는 DPLCONNECTION 구조체가 없는 경우,IDirectPlayLobby3::Connect 메소드에 의해 돌려주어진다.
DPERR_NOTLOGGEDIN
플레이어 어플리케이션 또는 클라이언트 어플리케이션이 로그 온되어 있지 않기 때문에, 처리를 실행할 수 없다. 클라이언트 어플리케이션이 로그 온 하지 않고 기밀 보호 메세지를 송신하려고 하면(자),IDirectPlay4::Send 메소드에 의해 돌려주어진다.
DPERR_OUTOFMEMORY
요구된 조작을 실행하려면 , 메모리가 부족하다.
DPERR_PENDING
에러는 아니다. 이 반환값은, 비동기 송신으로, 큐에의 설정이 성공하는 곳(중)까지 처리가 진행된 것을 나타낸다. 상세한 것에 대하여는,IDirectPlay4::SendEx 를 참조할것.
DPERR_PLAYERLOST
플레이어는, 세션에의 접속을 상실했다.
DPERR_SENDTOOBIG
IDirectPlay4::Send 메소드에 의해 송신되고 있는 메세지가 너무 크다.
DPERR_SESSIONLOST
세션에의 접속이 상실했다.
DPERR_SIGNFAILED
요구된 정보에, 디지털 서명 할 수 없었다. 디지털 서명은, 메세지를 인증할 경우에 사용된다.
DPERR_TIMEOUT
지정된 시간내에 처리를 완료할 수 없었다.
DPERR_UNAVAILABLE
이 시점에서는, 요구된 함수를 사용할 수 없다.
DPERR_UNINITIALIZED
요구된 오브젝트가 초기화되어 있지 않다.
DPERR_UNKNOWNAPPLICATION
미확인의 어플리케이션이 지정되었다.
DPERR_UNKNOWNMESSAGE
메세지 ID 가 유효하지 않다. 취소하는 메세지의 ID 가 무효의 경우에,IDirectPlay4::CancelMessage 로부터 돌려주어진다
DPERR_UNSUPPORTED
함수 또는 기능을, 이 이행이나 이 서비스 프로바이더로 사용할 수 없다. IDirectPlay4::GetGroupConnectionSettings 나 IDirectPlay4::SetGroupConnectionSettings 로비 세션이 아닌 세션으로부터 불려 갔을 경우에, 그것들로부터 돌려주어진다. 우선 순위나 타임 아웃이 설정되어 있는 경우에, 그것들이 서비스 프로바이더에 의해 지원 되지 않고, 또 DirectPlay 프로토콜이 온이 아닐 때에,IDirectPlay4::SendEx 로부터 돌려주어진다. 송신 큐를 체크하는 경우에, 그것이 서비스 프로바이더에 의해 지원 되지 않고, 또 DirectPlay 프로토콜이 온이 아닐 때,IDirectPlay4::GetMessageQueue 로부터 돌려주어진다.
DPERR_USERCANCEL
다음의 경우에 돌려주어진다. 1) 유저가 IDirectPlay4::Open 메소드를 호출하고 있는 한중간에 접속 프로세스를 취소했을 경우. 2) IDirectPlay4::EnumSessions 를 호출하고 있는 한중간에, 유저가 DirectPlay 서비스 프로바이더의 다이알로그 박스의 어느쪽이든으로 [캔슬] 을 클릭했을 경우.
E_UNKNOWN
일반적으로, 하등의 중대한 장해가 발생한 것을 나타낸다. 예를 들어, 서비스 프로바이더가 올바르게 초기화할 수 없기도 하고, IPX 등의 프로토콜이 컴퓨터에 올바르고 인스톨 되지 않았다.


DirectPlay Visual Basic 레퍼런스

여기에서는, DirectPlay® for Visual Basic® 의 어플리케이션 프로그래밍 인터페이스 (API) 요소의 레퍼런스 정보를 기술한다. 레퍼런스 정보는, 이하의 카테고리로 분류된다.

  • 클래스
  • 형
  • 열거형
  • 에러 코드


클래스

이 섹션은, 이하의 DirectPlay 클래스의 메소드에 관한 레퍼런스 정보를 제공한다.

  • DirectPlay4
  • DirectPlayAddress
  • DirectPlayEnumConnections
  • DirectPlayEnumLocalApplications
  • DirectPlayEnumPlayers
  • DirectPlayEnumSessions
  • DirectPlayLobby3
  • DirectPlayLobbyConnection
  • DirectPlayMessage
  • DirectPlaySessionData


DirectPlay4

어플리케이션은,DirectPlay4 클래스의 메소드를 사용해, DirectPlay 오브젝트를 생성 하거나 열거를 실행하거나 접속을 확립하거나세션,플레이어, 및그룹을 관리하거나 한다.

DirectX7.DirectPlayCreate 메소드를 사용해, 각 어플리케이션에 대해서 1 개의 DirectPlay4 오브젝트를 생성 한다.

DirectPlay4 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

접속 | GetDPEnumConnections
 | InitializeConnection
 | SetGroupConnectionSettings
세션 | Close
 | CreateSessionData
 | GetDPEnumSessions
 | GetCaps
 | GetSessionDesc
 | Open
 | SecureOpen
 | SetSessionDesc
 | StartSession
플레이어 | CreatePlayer
 | DestroyPlayer
 | GetDPEnumPlayers
 | GetPlayerAccountId
 | GetPlayerAddress
 | GetPlayerCaps
 | GetPlayerData
 | GetPlayerFlags
 | GetPlayerFormalName
 | GetPlayerFriendlyName
 | SetPlayerData
 | SetPlayerName
메세지 | CancelMessage
 | CancelPriority
 | CreateMessage
 | GetMessageCount
 | GetMessageQueue
 | Receive
 | Send
 | SendChatMessage
 | SendEx
그룹 | AddGroupToGroup
 | AddPlayerToGroup
 | CreateGroup
 | CreateGroupInGroup
 | DeleteGroupFromGroup
 | DeletePlayerFromGroup
 | DestroyGroup
 | GetDPEnumGroupPlayers
 | GetDPEnumGroups
 | GetDPEnumGroupsInGroup
 | GetGroupData
 | GetGroupFlags
 | GetGroupLongName
 | GetGroupShortName
 | GetGroupOwner
 | GetGroupParent
 | SetGroupData
 | SetGroupName
 | SetGroupOwner


DirectPlay4.AddGroupToGroup

DirectPlay4.AddGroupToGroup 메소드는, 그룹에의 쇼트 컷을, 기존의 그룹에 추가한다. 이것에 의해, 링크된 그룹을,DirectPlay4.GetDPEnumGroupsInGroup 메소드로 열거할 수 있게 된다. 그룹의 쇼트 컷을 다른 그룹으로부터 삭제하려면 ,DirectPlay4.DeleteGroupFromGroup 를 호출한다.

object. AddGroupToGroup(ParentGroupId As Long, _
    GroupId As Long)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
ParentGroupId
쇼트 컷의 추가처의 그룹의 ID. 임의의 유효한 그룹 ID 를 사용할 수 있다.
GroupId
추가하는 쇼트 컷이 가리키는 그룹의 ID. 임의의 유효한 그룹 ID 를 사용할 수 있다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP

주의

이 메소드를 사용 하면, 2 개(살) 이상의 그룹내에 그룹을 배치할 수가 있다.

이 변경을 플레이어에게 통지하기 위해서,DPSYS_ADDGROUPTOGROUP 시스템 메세지가 생성된다.

참조

DirectPlay4.CreateGroupInGroup


DirectPlay4.AddPlayerToGroup

DirectPlay4.AddPlayerToGroup 메소드는, 플레이어를 기존의 그룹에 추가한다. 플레이어는, 복수의 그룹의 멤버가 될 수가 있다. 어플리케이션은, 임의의 플레이어를 임의의 그룹에 추가할 수가 있다 (로컬에 생성되어 있지 않은 플레이어 및 그룹을 포함한다). 이 메소드를 사용해, 그룹을 다른 그룹에 추가할 수 없다 ( 「DirectPlay4.AddGroupToGroup 」를 참조).

object. AddPlayerToGroup(GroupId As Long, _
    playerId As Long)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
GroupId
추가처의 그룹의 ID.
playerId
그룹에 추가하는 플레이어의 ID.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_CANTADDPLAYER
DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDPLAYER
DPERR_NOSESSIONS

플레이어의 DirectPlay ID 가 플레이어 ID 가 아닌 경우, 또는 그 ID 가 로컬 플레이어의 것이 아닌 경우는, DPERR_INVALIDPLAYER 를 돌려준다.

주의

DPSYS_ADDPLAYERTOGROUP 시스템 메세지가 생성되어 다른 모든 플레이어에게 송신된다.

참조

DirectPlay4.CreateGroup ,DirectPlay4.DeletePlayerFromGroup


DirectPlay4.CancelMessage

DirectPlay4.CancelMessage 메소드는, 송신 큐내의 특정의 메세지 또는 모든 메세지를 캔슬한다. CancelMessage 는, 비동기 메세지에게만 적용된다. 특정의 메세지를 캔슬하려면 , 어플리케이션으로 DirectPlay4.SendEx 메소드에 의해 돌려주어지는 메세지 ID 를 취득해, 그것을 보존할 필요가 있다.

이미 메시지 큐를 떨어져 있어, 부분적으로 송신되는 메세지는, 캔슬할 수가 없다. 그룹에 송신된 메세지는, 그룹의 최저 1 명의 멤버에 송신된 다음에는, 캔슬할 수가 없다.

object. CancelMessage(msgid As Long)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
msgid
캔슬하는 메세지의 ID. 이 ID 는,DirectPlay4.SendEx 를 사용해 메세지가 송신되었을 때에 돌려주어진다. 모든 메세지를 캔슬하려면 , 0 을 지정한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_CANCELFAILED
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_UNKNOWNMESSAGE
DPERR_UNSUPPORTED

참조

DirectPlay4.CancelPriority ,DirectPlay4.Send


DirectPlay4.CancelPriority

DirectPlay4.CancelPriority 메소드는, 송신 큐에 남아 있는 메세지 가운데, 특정의 우선 순위에 해당하는 것이나, 특정의 우선 순위의 범위에 해당하는 것을 캔슬한다. CancelPriority 는, 비동기 메세지에게만 적용된다.

이미 메시지 큐를 떨어져 있어, 부분적으로 송신되는 메세지는, 캔슬할 수가 없다. 그룹에 송신된 메세지는, 그룹의 최저 1 명의 멤버에 송신된 다음에는, 캔슬할 수가 없다.

object. CancelPriority(minPriority As Long, _
    maxPriority As Long)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
minPriority
캔슬하는 우선 순위의 범위의 최소 값.
maxPriority
캔슬하는 우선 순위의 범위의 최대치 minPriority 보다 크지 않으면 안 된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS

참조

DirectPlay4.SendEx ,DirectPlay4.Send ,DirectPlay4.CancelMessage


DirectPlay4.Close

DirectPlay4.Close 메소드는, 이미 열리고 있는세션을 닫는다. 로컬에 생성 된 그룹은, 세션의호스트에게 소유되도록(듯이) 이행 한다.

object. Close()

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS

주의

로컬에 생성 된 플레이어는 모두 파기되어 적절한 DPSYS_DELETEPLAYERFROMGROUP 및 DPSYS_DESTROYPLAYERORGROUP 시스템 메세지가 다른 모든 세션 참가자에게 송신된다.

참조

DirectPlay4.DestroyPlayer ,DirectPlay4.Open


DirectPlay4.CreateGroup

DirectPlay4.CreateGroup 메소드는, 현재의세션내에서그룹을 생성 한다.

object. CreateGroup(friendlyName As String, _
    formalName As String, _
    flags As CONST_DPGROUPFLAGS) As Long

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
friendlyName
생성 되는 그룹을 식별해, 그 그룹에 액세스 하기 위해서 사용하는 핸들. 이 토큰 식별자는,formalName 와는 다른 것이 아니면 안된다.
formalName
생성 되는 그룹을 식별해, 그 그룹에 액세스 하기 위해서 사용하는 핸들. 이 토큰 식별자는,friendlyName 와는 다른 것이 아니면 안된다.
flags
CONST_DPGROUPFLAGS 열거형의 플래그로, 생성 하는 그룹의 타입을 나타낸다. DPGROUP_DEFAULT, DPGROUP_HIDDEN, 또는 DPGROUP_STAGINGAREA 의 어느 쪽인가에 된다.

반환값

그룹 ID 를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_CANTADDPLAYER
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS

주의

그룹을 클라이언트/서버 세션으로 생성 했을 경우, 그룹 통지 메세지는 송신되지 않는다. 그룹은, 컴퓨터가 클라이언트인지, 호스트일까에 관계없이, 그 그룹을 생성 한 컴퓨터로부터 밖에 인식할 수가 없다.

그룹을 피어 투 피어 세션으로 생성 했을 경우,CreateGroup 는, 다른 모든 플레이어에게 송신되는 DPSYS_CREATEPLAYERORGROUP 시스템 메세지를 생성한다. 어플리케이션에서는,DirectPlay4.Send 메소드를 사용해, 1 개의 메세지를 그룹 ID 에 송신하는 것에 의해, 메세지를 그룹내의 모든 플레이어에게 송신할 수가 있다. DirectPlay 는, 멀티 캐스트를 사용해 메세지를 송신하는지 (서비스 프로바이더가 멀티 캐스트를 지원 하는 경우), 또는 각각의 메세지를 그룹내의 각각의 플레이어에게 송신한다.

어플리케이션에 돌려주어진 그룹 ID 를 사용해, 메세지를 송신하는 그룹이나, 관련하는 데이터를 식별한다. DirectPlay 에 의해 할당할 수 있는 플레이어와 그룹의 ID 는, 세션내에서는 항상 일의이다.

CreateGroup 에 의해 생성 한 그룹은, 세션내의 최상정도의 그룹이다. 이러한 그룹은,DirectPlay4.GetDPEnumGroups 에 의해 열거된다. 한편,DirectPlay4.CreateGroupInGroup 메소드는, 친그룹의 서브 그룹에 상당하는 그룹을 생성 한다.

어플리케이션에서는, 일반적인 정리 목적으로 그룹을 사용할 수도 있다. 로비 세션에서는,DirectPlay4.StartSession . (을)를 사용해 새로운 어플리케이션 세션을 생성 하기 위해서 플레이어를 수집하는 메카니즘으로서 staging 영역이 사용된다.

그룹을 생성 한 플레이어는, 그 그룹의 디폴트의 소유자가 된다. 소유자만이, 이름이나 리모트 데이터등의 그룹의 프로퍼티를 변경하거나 그룹의 멤버를 변경하거나 그룹을 삭제하거나 할 수가 있다. 소유자가 세션을 떨어지면(자), 세션의호스트에게 소유권이 건네받는다.

그룹은, 명시적으로 파기될 때까지, 세션내에 존속한다.

참조

DirectPlay4.AddGroupToGroup ,DirectPlay4.DestroyGroup ,DirectPlay4.GetDPEnumGroupPlayers ,DirectPlay4.GetGroupFlags ,DirectPlay4.SetGroupData ,DirectPlay4.SetGroupName


DirectPlay4.CreateGroupInGroup

DirectPlay4.CreateGroupInGroup 메소드는, 기존의그룹내에 그룹을 생성 한다. 다른 그룹내에 생성 된 그룹이 열거되는 것은,DirectPlay4.GetDPEnumGroupsInGroup 메소드를 사용했을 경우 뿐이다. 이와 같이 해 생성 된 그룹을 파기하려면 ,DirectPlay4.DestroyGroup 메소드를 호출한다.

object. CreateGroupInGroup(parentid As Long,
  friendlyName As String,
  formalName As String,
  flags As CONST_DPGROUPFLAGS) As Long

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
parentid
그룹의 생성처가 되는, 기존의 그룹의 DirectPlay ID.
friendlyName
생성 된 그룹을 식별해, 거기에 액세스 하기 위해서 사용하는 핸들. 이 토큰 식별자는,formalName 와는 다른 것이 아니면 안된다.
formalName
생성 된 그룹을 식별해, 거기에 액세스 하기 위해서 사용하는 핸들. 이 토큰 식별자는,friendlyName 와는 다른 것이 아니면 안된다.
flags
CONST_FLAGS 열거형의 플래그로, 생성 하는 그룹의 타입을 나타낸다. DPGROUP_LOCAL 또는 DPGROUP_STAGINGAREA 의 어느 쪽인가에 된다. DPGROUP_LOCAL 가 설정되어 있지 않은 경우, 그룹은 리모트 그룹이다.

반환값

생성 된 그룹의 DirectPlay ID 를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_CANTADDPLAYER
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS

그룹을 생성 할 수 없었던 경우는, DPERR_CANTADDPLAYER 를 돌려준다. 친그룹의 ID 가 무효의 경우는, DPERR_INVALIDGROUP 를 돌려준다.

주의

그룹을 클라이언트/서버 세션으로 생성 했을 경우, 그룹 통지 메세지는 송신되지 않는다. 그룹은, 컴퓨터가 클라이언트인지, 호스트일까에 관계없이, 그 그룹을 생성 한 컴퓨터로부터 밖에 인식할 수가 없다.

그룹을 피어 투 피어 세션으로 생성 했을 경우,CreateGroupInGroup 는,DPSYS_CREATEPLAYERORGROUP 시스템 메세지를 생성해, 이 변경을 다른 플레이어에게 통지한다.

최상정도 그룹을 파기 하면, 그 그룹에 포함되는 멤버도 모두 파기되어 적절한 파기 메세지가 송신된다.


DirectPlay4.CreateMessage

DirectPlay4.CreateMessage 메소드는, 메세지 오브젝트를 생성 한다. 이 오브젝트는, 데이터와 조합해 송신할 수가 있다.

object. CreateMessage() As DirectPlayMessage

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectPlayMessage 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectPlay4.Send


DirectPlay4.CreatePlayer

DirectPlay4.CreatePlayer 메소드는, 현재의 세션에 대한 로컬 플레이어를 생성 한다.

object. CreatePlayer(friendlyName As String, _
    formalName As String, _
    receiveEvent As Long, _
    flags As CONST_DPPLAYERFLAGS) As Long

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
friendlyName
생성 되는 플레이어를 식별해, 그 플레이어에게 액세스 하기 위해서 사용하는 핸들. 이 토큰 식별자는,formalName 와는 다른 것이 아니면 안된다.
formalName
생성 되는 플레이어를 식별해, 그 플레이어에게 액세스 하기 위해서 사용하는 핸들. 이 토큰 식별자는,friendlyName 와는 다른 것이 아니면 안된다.
receiveEvent
어플리케이션에 의해 생성 되는 이벤트. DirectPlay 는, 이 플레이어에 대해서 송신된 메세지를 수신했을 때에, 이 이벤트를 발생시킨다.
flags
플레이어의 타입을 나타내는 플래그. 디폴트 (flags = 0)는, 관객은 아니고, 서버 플레이어가 아닌 플레이어이다.
DPPLAYER_SERVERPLAYER
플레이어는, 클라이언트/서버 통신의 서버 플레이어이다. 서버 플레이어를 생성 할 수 있는 것은,호스트 뿐이다. 1 개의 세션에 대한 서버 플레이어는, 1 명 뿐이다. 이 플래그가 설정되어 있는 경우,CreatePlayer 는 항상 DPID_SERVERPLAYER 의 플레이어 ID 를 돌려준다.
DPPLAYER_SPECTATOR
플레이어는 관객으로서 생성 된다. 관객 플레이어의 동작은, 어플리케이션에 의해 완전하게 정의된다. DirectPlay 는, 이 플래그를 단순하게 전승한다.

반환값

성공하면, 일의의 플레이어 ID 를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_CANTADDPLAYER
DPERR_CANTCREATEPLAYER
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_NOCONNECTION

주의

단일의 프로세스로, 복수의 로컬 플레이어를 가질 수가 있다. 이러한 플레이어는, DirectPlay 오브젝트를 개입시켜, 같은 컴퓨터 위에의 다른 플레이어나, 리모트 컴퓨터 위에의 플레이어와 통신한다.

이 메소드는, 적절히 종료 하면,DPSYS_CREATEPLAYERORGROUP 시스템 메세지를 세션내의 모든 플레이어에게 송신해, 새로운 플레이어가 세션에 참가한 것을 전한다. 디폴트에서는, 모든 로컬 플레이어가, 모든 시스템 메세지의 카피를 수신한다.

어플리케이션에서는, 돌려주어진 플레이어 ID 를 사용해, 메세지의 송신이나 데이터가 관련짓고를 위해서(때문에) 플레이어를 식별할 필요가 있다. DirectPlay 에 의해 할당할 수 있는 플레이어와그룹의 ID 는, 세션내에서는 항상 일의이다.

이하를 실행할 수 있는 것은, 플레이어를 생성 한 어플리케이션 뿐이다.

  • 플레이어의 이름의 변경
  • 플레이어의 리모트 데이터의 변경
  • 플레이어로부터의 메세지의 송신

어플리케이션이 세션을 닫으면(자), 생성 된 로컬 플레이어는, 자동적으로 파기된다. 세션의 호스트 또는 플레이어를 생성 한 어플리케이션은,DirectPlay4.DestroyPlayer 메소드를 사용해, 언제라도 플레이어를 파기할 수가 있다.

참조

DirectPlay4.GetDPEnumPlayers ,DirectPlay4.GetPlayerFlags ,DirectPlay4.Send ,DirectPlay4.SetPlayerData ,DirectPlay4.SetPlayerName ,DirectX7.CreateEvent


DirectPlay4.CreateSessionData

DirectPlay4.CreateSessionData 메소드는, 세션에 관한 정보를 설정 및 취득하기 위해서 이용되는 오브젝트를 생성 한다.

object. CreateSessionData() As DirectPlaySessionData

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectPlaySessionData 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlay4.DeleteGroupFromGroup

DirectPlay4.DeleteGroupFromGroup 메소드는,DirectPlay4.AddGroupToGroup 메소드에 의해 추가된 쇼트 컷을, 그룹으로부터 삭제한다. 쇼트 컷을 삭제해도, 그룹은 파기되지 않는다.

object. DeleteGroupFromGroup(groupParentId As Long, _
    GroupId As Long)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
groupParentId
삭제하는 쇼트 컷을 포함한 그룹의 DirectPlay ID.
GroupId
삭제하는 그룹의 DirectPlay ID.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP

주의

이 변경을 플레이어에게 통지하기 위해서,DPSYS_DELETEGROUPFROMGROUP 시스템 메세지가 생성된다.


DirectPlay4.DeletePlayerFromGroup

DirectPlay4.DeletePlayerFromGroup 메소드는,그룹으로부터 플레이어를 삭제한다.

object. DeletePlayerFromGroup(GroupId As Long, _
    playerId As Long)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
GroupId
플레이어를 삭제하는 그룹의 ID.
playerId
그룹으로부터 삭제하는 플레이어의 ID.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER

주의

이 변경을 통지하기 위해서,DPSYS_DELETEPLAYERFROMGROUP 시스템 메세지가 생성된다.

플레이어는, 그룹이 다른 컴퓨터에 의해 생성 된 것이어도, 그룹으로부터 임의의 플레이어를 삭제할 수가 있다.

참조

DirectPlay4.AddPlayerToGroup


DirectPlay4.DestroyGroup

DirectPlay4.DestroyGroup 메소드는, 세션으로부터그룹을 삭제한다.

object. DestroyGroup(GroupId As Long)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
GroupId
게임으로부터 삭제되는 그룹의 ID.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

주의

그룹은, 삭제하기 전에 하늘일 필요는 없다. 삭제하는 그룹에 속하는 각각의 플레이어는, 파기되지 않는다.

이 메소드는, 그룹내의 각 플레이어에 대해서,DPSYS_DELETEPLAYERFROMGROUP 시스템 메세지를 생성해, 한층 더 DPSYS_DESTROYPLAYERORGROUP 시스템 메세지를 생성한다.

그룹이 로컬에 생성 된 것이 아닌 경우에서도, 임의의 어플리케이션으로 임의의 그룹을 파기할 수가 있다.

파기하는 그룹의 ID 는, 현재의 세션이 계속하고 있는 동안은, 재이용되지 않는다.

참조

DirectPlay4.CreateGroup


DirectPlay4.DestroyPlayer

DirectPlay4.DestroyPlayer 메소드는, 세션으로부터 로컬 플레이어를 삭제해, 그 플레이어에 대한 보류중의 메세지를 송신 큐로부터 삭제해, 그 플레이어가 속하는 모든그룹으로부터 그 플레이어를 삭제한다.

일반적으로, 플레이어를 삭제할 수 있는 것은, 그 플레이어를 생성 한 어플리케이션 뿐이다. 그러나,세션의호스트도, 플레이어를 삭제할 수가 있다.

object. DestroyPlayer(playerId As Long)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
playerId
세션으로부터 삭제하는, 로컬에 보관 유지되는 플레이어의 ID. 세션의 호스트가 DestroyPlayer 를 호출하는 경우, 이 ID 는, 로컬 또는 리모트에 관계없이, 임의의 플레이어의 ID 로 좋다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER
DPERR_UNAVAILABLE

주의

이 메소드는, 플레이어가 속하는 각 그룹에 대해서 DPSYS_DELETEPLAYERFROMGROUP 시스템 메세지를 생성해, 한층 더 DPSYS_DESTROYPLAYERORGROUP 시스템 메세지를 생성한다.

플레이어에 대한 비동기 메세지가 송신 큐내에서 보류 상태가 되어 있으면(자), 그 플레이어를 파기할 수 없다. 이 메소드는, 삭제하는 플레이어에 대한 보류중의 메세지를,

플레이어 ID 는, 현재의 세션이 계속하고 있는 동안은, 재이용되지 않는다.

참조

DirectPlay4.CreatePlayer


DirectPlay4.GetCaps

DirectPlay4.GetCaps 메소드는, 현재의 DirectPlay 접속 및세션의 능력을 취득한다.

object. GetCaps(caps As DPCAPS, _
    flags As CONST_DPGETCAPSFLAGS)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
caps
DirectPlay 오브젝트의 능력이 설정되는 DPCAPS 형.
flags
CONST_DPGETCAPSFLAGS 열거형의 몇개의 멤버. 이 파라미터를 DPGETCAPS_DEFAULT (또는 0)로 설정 하면, 보증 없음의 메시징에 대한 능력이 계산된다. DPGETCAPS_GUARANTEED 로 설정 하면, 보증 첨부의 메세지 전달에 대한 능력이 취득된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_UNINITIALIZED

주의

이 메소드를 호출하기 전에, 접속이 초기화되어 있지 않으면 안 된다. 연 세션이 존재하지 않는 경우,DPCAPS 의 일부의 멤버는, 유효한 값을 돌려주지 않는다.

참조

DirectPlay4.GetPlayerCaps ,DirectPlay4.InitializeConnection


DirectPlay4.GetDPEnumConnections

DirectPlay4.GetDPEnumConnections 메소드는, 어플리케이션으로 이용 가능한 등록을 마친 서비스 프로바이더 및 로비 프로바이더를 열거한다. 보통은, 이것들을 유저에게 선택을 재촉하는 형태로 제시해, 선택된 접속을 DirectPlay4.InitializeConnection 메소드에 건네준다.

object. GetDPEnumConnections(guid As String, _
    flags As CONST_DPENUMCONNECTIONFLAGS) _
    As DirectPlayEnumConnections

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
guid
어플리케이션의 글로벌 유니크 식별자 (GUID). 이 어플리케이션으로 이용 가능한 서비스 프로바이더와 로비 프로바이더만이 돌려주어진다. "" (으)로 설정 하면, 어플리케이션의 GUID 에 관계없이, 모든 접속이 열거된다.
flags
열거되는 접속의 타입을 지정하는 CONST_DPENUMCONNECTIONFLAGS 플래그. 디폴트 (flags = 0)에서는, DPCONNECTION_DIRECTPLAY 와 같은 결과를 얻을 수 있다.

반환값

성공하면,DirectPlayEnumConnections 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS

주의

돌려주어지는 서비스 프로바이더와 로비 프로바이더의 차례는, 이후의 GetDPEnumConnections 의 호출과 같게 된다고는 할 수 없다.

열거된 접속이 모두 이용 가능한 것은 아니다. 예를 들어, 이 메소드는, 유저가 모뎀을 인스톨 하고 있지 않는 경우에서도, 모뎀 서비스 프로바이더를 돌려준다. 어플리케이션에서는, 각각의 접속에 대해서 DirectPlay4.InitializeConnection 메소드를 호출해, 에러 코드를 체크해, 서비스 프로바이더가 이용 가능한가 어떤가를 판단할 수가 있다.

서비스 프로바이더안에는, 스스로를 사적인 것으로 해 등록할 수 있는 것이 있다. 이러한 서비스 프로바이더는, 이 메소드에서는 열거되지 않는다. 사적인 서비스 프로바이더를 사용하려면 , 그것들을 GUID 에 의해 명시적으로 참조할 필요가 있다. 거기에는, 어플리케이션을 로비로부터 기동하는지, 또는 DirectPlay 주소를 생성 해, 그것을 InitializeConnection 에 건네준다.

참조

GUID 의 사용


DirectPlay4.GetDPEnumGroupPlayers

DirectPlay4.GetDPEnumGroupPlayers 메소드는, 현재의 오픈 세션내에서 특정의그룹에 속하는 플레이어를 열거한다.

GetDPEnumGroupPlayers(GroupId As Long, _
    sessionGuid As String, _
    flags As CONST_DPENUMPLAYERFLAGS) _
    As DirectPlayEnumPlayers

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
GroupId
열거하는 플레이어가 속하는 그룹의 DirectPlay ID.
sessionGuid
열거하는 세션을 나타내는 글로벌 유니크 식별자 (GUID). DPENUMPLAYERS_SESSION 플래그가 설정되어 있는 경우를 제외해, 이 파라미터는 무시된다. 이 GUID 는,DirectPlay4.GetDPEnumSessions 메소드에 의해 열거되는 세션의 언젠가와 같지 않으면 안 된다.
flags
열거의 방법을 지정하는 플래그. 디폴트 (flags = 0)에서는, 현재의 액티브한 세션내의 그룹의 플레이어를 열거한다. 지정하는 플래그를 조합하려면 , 논리 Or 연산을 사용한다. 조합할 수 있었던 플래그의 모든 조건에 일치하는 플레이어만이, 열거된다. 예를 들어, (DPENUMPLAYERS_LOCAL Or DPENUMPLAYERS_SPECTATOR)라고 지정 하면, 그룹내의, 로컬로, 게다가 관객인 플레이어만이 열거된다. (DPENUMPLAYERS_LOCAL Or DPENUMPLAYERS_REMOTE)(와)과 지정 하면, 로컬로, 게다가 리모트인 플레이어는 존재하지 않기 때문에, 플레이어는 열거되지 않는다.

이 플래그에는,CONST_DPENUMPLAYERFLAGS 열거형의 이하의 1 개 이상의 값을 설정할 수 있다.

DPENUMPLAYERS_LOCAL
DPENUMPLAYERS_OWNER
DPENUMPLAYERS_REMOTE
DPENUMPLAYERS_SERVERPLAYER
DPENUMPLAYERS_SESSION
DPENUMPLAYERS_SPECTATOR

반환값

성공하면,DirectPlayEnumPlayers 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDPARAMS
DPERR_INVALIDGROUP
DPERR_NOSESSIONS
DPERR_UNAVAILABLE

이 메소드는, 세션이, 접속처가 아닌 로비 세션의 경우는, DPERR_ACCESSDENIED 를 돌려준다. sessionGuid 또는 플래그가 무효인 경우는, DPERR_INVALIDPARAMS 를 돌려준다. 액티브한 세션이 존재하지 않는 경우는, DPERR_NOSESSIONS 를 돌려준다. 세션을 열거할 수 없었던 경우는, DPERR_UNAVAILABLE 를 돌려준다.

주의

패스워드로 보호된 리모트 세션은 열거되지 않는다. 접속하고 있지 않는 로비 세션으로 이 메소드를 사용할 수 없다.

이 메소드는, 디폴트에서는, 현재의 세션내의 모든 플레이어를 열거한다. 세션의 호스트가 열거용의 리스트를 제공하도록(듯이) 요구하려면 , DPENUMPLAYERS_SESSION 플래그와 세션 인스턴스의 GUID 를 사용한다. DPENUMPLAYERS_SESSION 플래그를 이 메소드로 사용하는 것은,DirectPlay4.GetDPEnumSessions 메소드를 호출한 다음에, 게다가 DirectPlay4.Close 메소드 또는 DirectPlay4.Open 메소드를 호출하기 전이 아니면 안된다.

참조

DirectPlay4.CreatePlayer ,DirectPlay4.DestroyPlayer ,DirectPlay4.AddPlayerToGroup ,DirectPlay4.DeletePlayerFromGroup ,GUID 의 사용


DirectPlay4.GetDPEnumGroups

DirectPlay4.GetDPEnumGroups 메소드는, 현재의 세션내의 최상정도 그룹을 모두 열거한다. 최상정도 그룹은,DirectPlay4.CreateGroup 메소드를 사용해 생성 된 그룹이다.

object. GetDPEnumGroups(sessionGuid As String, _
    flags As CONST_DPENUMGROUPFLAGS) _
    As DirectPlayEnumPlayers

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
sessionGuid
열거하는 세션을 식별하는 글로벌 유니크 식별자 (GUID). 현재 열려 있는 세션의 그룹을 열거하려면 , 이 파라미터를 "" 로 설정한다. 그 이외의 경우, 이 GUID 는,DirectPlay4.GetDPEnumSessions . 에 의해 열거되는 세션의 어느쪽이든동일하지 않으면 안 된다.
flags
열거의 방법을 지정하는 플래그. 디폴트에서는 (flags = 0), 현재의 액티브 세션내의 그룹을 모두 열거한다. 조합할 수 있었던 플래그의 모든 조건에 일치하는 그룹만이 열거된다. 예를 들어, (DPENUMGROUPS_LOCAL Or DPENUMGROUPS_STAGINGAREA)라고 지정 하면, 로컬로, 게다가 staging 영역인 그룹만이 열거된다. (DPENUMGROUPS_LOCAL Or DPENUMGROUPS_REMOTE)(와)과 지정 하면, 로컬로 게다가 리모트인 그룹은 존재하지 않기 때문에, 그룹은 열거되지 않는다.

이 플래그에는,CONST_DPENUMGROUPFLAGS 열거형의 이하의 몇개의 값을 설정할 수 있다.

DPENUMGROUPS_ALL
세션내의 모든 그룹을 열거한다.
DPENUMGROUPS_LOCAL
이 DirectPlay 오브젝트에 의해 로컬에 생성 된 그룹을 열거한다.
DPENUMGROUPS_REMOTE
리모트의 DirectPlay 오브젝트에 의해 생성 된 그룹을 열거한다.
DPENUMGROUPS_SESSION
sessionGuid 파라미터에 의해 지정되는 세션내에서 열거를 실행한다. 이 플래그는, 현재 액티브한 세션이 존재하지 않는 경우에게만 사용할 수 있다. 이 플래그를 로비 세션으로 사용할 수 없다.
DPENUMGROUPS_STAGINGAREA
staging 영역에 있는 그룹을 열거한다 (staging 영역은, 새로운 세션을 시작 할 때에, 플레이어를 배치하기 위해서 이용된다).

반환값

성공하면,DirectPlayEnumPlayers 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_CONNECTIONLOST
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS
DPERR_UNAVAILABLE

이 메소드는, 제공된 sessionGuid 또는 플래그가 무효인 경우는, DPERR_INVALIDPARAMS 를 돌려준다. 연 세션이 존재하지 않는 경우는, DPERR_NOSESSIONS 를 돌려준다. 리모트 세션을 열거할 수 없었던 경우는, DPERR_UNAVAILABLE 를 돌려준다.

주의

접속하고 있지 않는 로비 세션으로,GetDPEnumGroups 를 사용할 수 없다.

연 세션이 존재하지 않는 경우는, DPENUMGROUPS_SESSION 플래그를 지정해, 세션의 sessionGuid 를 지정하는 것으로써, 리모트 세션의 그룹을 열거할 수가 있다. 패스워드로 보호된 리모트 세션을 열거할 수 없다.

그룹내의 서브 그룹을 열거하려면 ,DirectPlay4.GetDPEnumGroupsInGroup 를 사용한다.

참조

DirectPlay4.DestroyGroup ,DirectPlay4.GetDPEnumSessions ,GUID 의 사용


DirectPlay4.GetDPEnumGroupsInGroup

DirectPlay4.GetDPEnumGroupsInGroup 메소드는, 다른 그룹에 포함되어 있는 그룹 및 그룹에의 쇼트 컷을 모두 열거한다. 그룹을 DirectPlay4.CreateGroupInGroup 메소드에 의해 생성 하는지, 또는 DirectPlay4.AddGroupToGroup 메소드에 의해 다른 그룹에 추가 하면, 그 그룹은 다른 그룹의 내부에 배치된다. 이 메소드는 재귀적이지 않다.

object. GetDPEnumGroupsInGroup(GroupId As Long, _
    sessionGuid As String, _
    flags As CONST_DPENUMGROUPFLAGS) _
    As DirectPlayEnumPlayers

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
GroupId
열거하는 서브 그룹이 속하는 그룹의 ID.
sessionGuid
열거하는 세션의 글로벌 유니크 식별자 (GUID). DPENUMPLAYERS_SESSION 플래그가 설정되어 있는 경우를 제외해, 이 파라미터는 무시된다. 이 GUID 는,DirectPlay4.GetDPEnumSessions 메소드에 의해 열거되는 세션의 어느쪽이든동일하지 않으면 안 된다.
flags
열거의 방법을 지정하는 플래그. 디폴트 (flags = 0)에서는, 현재의 액티브한 세션내의 그룹을 모두 열거한다. 조합할 수 있었던 플래그의 모든 조건에 일치하는 그룹만이, 열거된다. 예를 들어, (DPENUMGROUPS_LOCAL Or DPENUMGROUPS_STAGINGAREA)라고 지정 하면, 로컬로, 게다가 staging 영역인 그룹만이 열거된다. (DPENUMGROUPS_LOCAL Or DPENUMGROUPS_REMOTE)(와)과 지정 하면, 로컬로, 게다가 리모트인 그룹은 존재하지 않기 때문에, 그룹은 열거되지 않는다.

이 플래그에는,CONST_DPENUMGROUPFLAGS 열거형의 이하의 1 개 이상의 값을 설정할 수 있다.

DPENUMGROUPS_ALL
그룹내의 모든 그룹을 열거한다.
DPENUMGROUPS_HIDDEN
그룹내의 현재 이용 가능한 숨은 그룹만을 열거한다.
DPENUMGROUPS_LOCAL
이 DirectPlay 오브젝트에 의해 로컬에 생성 된 그룹내의 그룹만을 열거한다.
DPENUMGROUPS_REMOTE
리모트의 DirectPlay 오브젝트에 의해 생성 된 그룹내의 그룹만을 열거한다.
DPENUMGROUPS_SESSION
sessionGuid 파라미터에 의해 지정되는 세션내에서 열거를 실행한다. 이 플래그는, 현재 액티브한 세션이 존재하지 않는 경우에게만 사용할 수 있다. 이 플래그를 로비 세션으로 사용할 수 없다.
DPENUMGROUPS_SHORTCUT
DirectPlay4.AddGroupToGroup 를 사용해 그룹에 추가된 쇼트 컷인 그룹을 열거한다 (쇼트 컷은, 다른 그룹에의 링크이다).
DPENUMGROUPS_STAGINGAREA
staging 영역인 그룹내의 그룹을 열거한다 (staging 영역은, 새로운 세션을 시작 할 때에, 플레이어를 배치하기 위해서 이용된다).

반환값

성공하면,DirectPlayEnumPlayers 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS
DPERR_UNSUPPORTED

이 메소드는, 건네받은 sessionGuid 이 무효의 경우는, DPERR_INVALIDPARAMS 를 돌려준다. 액티브한 세션이 존재하지 않는 경우는, DPERR_NOSESSIONS 를 돌려준다. 세션을 열거할 수 없었던 경우는, DPERR_UNSUPPORTED 를 돌려준다.

주의

이 메소드를, 접속하고 있지 않는 로비 세션으로 사용할 수 없다.

참조

DirectPlay4.DeleteGroupFromGroup ,DirectPlay4.DestroyGroup ,GUID 의 사용


DirectPlay4.GetDPEnumPlayers

DirectPlay4.GetDPEnumPlayers 메소드는, 현재 열려 있는세션내의 플레이어를 열거해, 옵션으로 그룹도 열거한다. 연 세션이 존재하지 않는 경우는, 리모트 세션내의 플레이어를 열거할 수 있다.

object. GetDPEnumPlayers(sessionGuid As String, _
    flags As CONST_DPENUMPLAYERFLAGS) _
    As DirectPlayEnumPlayers

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
sessionGuid
현재 열려 있는 세션의 플레이어를 열거하는 경우는, 이 파라미터를 "" 로 설정할 필요가 있다. 연 세션이 존재하지 않는 경우, 이 파라미터에는, 열거하는 세션의 GUID 를 지정할 수 있다. 이 GUID 는,DirectPlay4.GetDPEnumSessions 에 의해 설정되는 세션의 어느 쪽인가에 속하지 않으면 안 된다. DPENUMPLAYERS_SESSION 플래그가 설정되어 있는 경우를 제외해, 이 파라미터는 무시된다.
flags
열거의 방법을 지정하는 플래그. 디폴트 (flags = 0)에서는, 현재의 액티브한 세션내의 플레이어를 모두 열거한다. 조합할 수 있었던 플래그의 모든 조건에 일치하는 플레이어만이, 열거된다. 예를 들어, (DPENUMPLAYERS_LOCAL Or DPENUMPLAYERS_SPECTATOR)라고 지정 하면, 로컬로, 게다가 관객인 플레이어만이 열거된다. (DPENUMPLAYERS_LOCAL Or DPENUMPLAYERS_REMOTE)(와)과 지정 하면, 로컬로, 게다가 리모트인 플레이어는 존재하지 않기 때문에, 플레이어는 열거되지 않는다.

이 플래그에는,CONST_DPENUMPLAYERFLAGS 열거형의 이하의 1 개 이상의 값을 설정할 수 있다.

DPENUMPLAYERS_ALL
DPENUMPLAYERS_GROUP
DPENUMPLAYERS_LOCAL
DPENUMPLAYERS_REMOTE
DPENUMPLAYERS_SERVERPLAYER
DPENUMPLAYERS_SESSION
DPENUMPLAYERS_SPECTATOR

반환값

성공하면,DirectPlayEnumPlayers 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS
DPERR_UNAVAILABLE

이 메소드는, 건네받은 sessionGuid 또는 플래그가 무효인 경우는, DPERR_INVALIDPARAMS 를 돌려준다. 연 세션이 존재하지 않는 경우는, DPERR_NOSESSIONS 를 돌려준다. 리모트 세션을 열거할 수 없었던 경우는, DPERR_UNAVAILABLE 를 돌려준다.

이 메소드는, 로비 세션내에서는, 항상 DPERR_ACCESSDENIED 를 돌려준다.

주의

이 메소드는, 디폴트에서는, 현재 열려 있는 세션내의 플레이어를 열거한다. DPENUMPLAYERS_GROUP 플래그를 사용 하면, 그룹을 열거에 포함할 수가 있다. 세션의호스트가 열거용으로 리스트를 제공하도록(듯이) 요구하려면 ,DPENUMPLAYERS_SESSION 플래그와 세션 인스턴스의 GUID 를 사용한다. 이 메소드는,DirectPlay4.GetDPEnumSessions 의 열거로부터 호출할 수 없다. 게다가 DPENUMPLAYERS_SESSION 플래그를 이 메소드로 사용하는 것은,GetDPEnumSessions 메소드를 호출한 다음에, 게다가 DirectPlay4.Close 메소드 또는 DirectPlay4.Open 메소드를 호출하기 전이 아니면 안된다.

참조

DirectPlay4.CreatePlayer ,DirectPlay4.DestroyPlayer ,GUID 의 사용


DirectPlay4.GetDPEnumSessions

DirectPlay4.GetDPEnumSessions 메소드는, 특정의 어플리케이션에 대한 액티브 세션과 특정의 어플리케이션에 대해서 서비스를 제공하는 액티브 로비 세션의 언젠가 또는 양쪽 모두를 모두 열거한다. 이 메소드는,DirectPlay4.InitializeConnection 에 의해 접속이 생성 되어 초기화된 후에 호출할 수가 있다.

이 메소드는, 세션이 이미 열려 있을 때 불려 가면(자), 에러를 돌려준다.

object. GetDPEnumSessions( _
    sessionDesc As DirectPlaySessionData, _
    timeOut As Long, _
    flags As CONST_DPENUMSESSIONFLAGS) _
    As DirectPlayEnumSessions

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
sessionDesc
열거되는 세션의 기술을 나타내는 DirectPlaySessionData 오브젝트. 이 오브젝트를 취득하려면 ,DirectPlay4.CreateSessionData 메소드를 사용한다. GuidApplication 멤버에는, 대상이 되는 어플리케이션을 알 수 있고 있는 경우에는 그 글로벌 유니크 식별자 (GUID), 모든 세션을 취득하는 경우에는 "" 을 설정할 수 있다. SessionPassword 멤버는, Private 세션을 열거하는 경우에게만 필요하다. 다른 데이터 멤버는, 모두 무시된다.
timeOut
동기를 취하는 경우는, DirectPlay 가 열거 요구의 응답을 대기하는 시간 ( 각 열거간의 시간은 아니다)을 밀리 세컨드로 지정한다. 여기로 지정한 시간이 경과한 후에 수신된 응답은, 모두 무시된다. 이 타임 아웃 시간이 경과할 때까지, 어플리케이션은 블록 한다.

비동기의 경우는, 내부 세션 리스트를 갱신하기 위해서 DirectPlay 가 열거 요구를 브로드캐스트 하는 간격을 밀리 세컨드 단위로 지정한다.

이 타임 아웃을 0 으로 설정 하면,서비스 프로바이더와 접속의 타입에 적절한 디폴트의 타임 아웃이 사용된다. 이 값은, 0 으로 설정하도록(듯이) 추천 되고 있다. 어플리케이션에서는,DirectPlay4.GetCaps 를 호출해,DPCAPS 형의 lTimeout 멤버를 조사해, 이 타임 아웃을 판단할 수가 있다.

flags
CONST_DPENUMSESSIONFLAGS 열거형의 0 개 이상의 플래그. 디폴트는 0 이며, 이것은 DPENUMSESSIONS_AVAILABLE 에 동일하다. DPENUMSESSIONS_ALL 또는 DPENUMSESSIONS_PASSWORDREQUIRED 로 세션을 열거 하면나무는, 어느 세션이 참가 불가능해, 어느 세션이 패스워드로 보호되고 있을까를 어플리케이션으로 파악해, 유저에게 경고하거나 패스워드를 요구할 수 있도록(듯이) 하는 것이 중요하다.

반환값

성공하면,DirectPlayEnumSessions 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_CONNECTING
DPERR_CONNECTIONLOST
DPERR_EXCEPTION
DPERR_GENERIC
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOCONNECTION
DPERR_UNINITIALIZED
DPERR_USERCANCEL

이 메소드는, 세션이 이미 열려 있는 경우는, DPERR_GENERIC 를 돌려준다. DirectPlay 오브젝트가 아직 초기화되어 있지 않은 경우는, DPERR_UNINITIALIZED 를 돌려준다. 유저가 열거 처리를 캔슬했을 경우 (보통은, 서비스 프로바이더의 다이알로그 박스를 캔슬하는 것으로써, 열거 처리가 캔슬된다)는, DPERR_USERCANCEL 를 돌려준다. 네트워크에의 접속 처리로 사용되고 있는 경우는, DPERR_CONNECTING 를 돌려준다.

주의

이 메소드는, 1 개(살) 이상의 호스트를 네트워크상에서 찾아내 그것들에 열거 요구를 송신하도록(듯이) 서비스 프로바이더에 요구하는 것에 의해 기능한다. 수신된 응답이, 열거된 세션을 형성한다.

이 메소드는, 동기적 (디폴트) 또는 비동기적으로 호출할 수가 있다. 동기적으로 호출하면, DirectPlay 가 내부의 세션 캐쉬를 소거해, 열거 요구를 송신해, 지정된 타임 아웃이 경과할 때까지 응답을 수집한다. 하면, 각 세션이 어플리케이션에 돌려주어진다. 어플리케이션은, 모든 세션이 돌려주어질 때까지 블록 한다.

비동기적으로 호출하면 (DPENUMSESSIONS_ASYNC), 세션 캐쉬내의 모든 현재 세션 (존재하는 경우)이 어플리케이션에 돌려주어져 그 후로 메소드가 돌아온다. 그 후, DirectPlay 는 타임 아웃 파라미터로 설정된 간격으로 열거 요구를 자동적으로 송신해, 응답을 대기한다. 각 응답은, 세션 캐쉬를 갱신하기 위해서 이용된다.

  • 캐쉬내에 이미 존재하는 세션이 갱신된다.
  • 설정된 시간내에 갱신되어 있지 않은 (따라, 실효한) 세션이 삭제된다.
  • 새로운 세션이 추가된다.

어플리케이션에서는, DPENUMSESSIONS_ASYNC 플래그를 설정해 GetDPEnumSessions 를 한번 더 호출해, 실효한 세션이 삭제되어 새로운 세션이 추가되어 세션이 갱신된 최신의 세션 리스트를 취득할 필요가 있다. 이후에 GetDPEnumSessions 를 호출하면, 열거 요구는 생성되지 않는다. 열거 요구는, 프로세스가 DPENUMSESSIONS_STOPASYNC 를 설정한 GetDPEnumSessions 의 호출에 의해 캔슬되는지,DirectPlay4.Open 메소드에 의해 세션이 열리는지, 또는 DirectPlay 오브젝트가 릴리즈 될 때까지, DirectPlay 에 의해 정기적으로 생성된다.

비동기적으로 열거되고 있는 세션의 기술을 변경하려면 , 비동기의 열거를 중지해, 재차 시작 할 필요가 있다. 예를 들어, 패스워드없이 세션을 시작 해, 다음에 비동기 호출 때에 패스워드를 추가해, 그 패스워드를 사용해 Private 세션의 열거를 시작 시킬 수 없다. 반대로, 올바른 패스워드를 설정해, 그것을 틀린 패스워드에 변경해도, 여전히 세션을 열거할 수가 있다. 그러나, DPENUMSESSIONS_STOPASYNC 플래그를 설정해 GetDPEnumSessions 를 호출하고 나서 패스워드를 설정 하면, Private 세션이 열거된다.

이용 가능한 세션의 열거가 완료하면(자), 어플리케이션에서는 DirectPlay4.Open 메소드를 사용해, 몇개의 세션에 참가할 수가 있다. 열 수가 있는 것은, 세션 캐쉬내의 세션 뿐이다. 어플리케이션에서는,GetDPEnumSessions 가 마지막에 불려 가고 나서 실효한 세션을 여는 것을 시도할 수가 있다. 이 경우, 에러가 돌려주어진다.

보증 서버상에서 세션을 열거 하면나무는, 인증은 실행되지 않는다. 열거의 조건에 맞는 세션이 모두 돌려주어진다. 인증은, 어플리케이션이 그러한 세션의 어느쪽이든을 Open 또는 DirectPlay4.SecureOpen 메소드로 열리려고 했을 때에 실행된다.

어플리케이션이 로비에 의해 기동되어 있지 않은 경우, 서비스 프로바이더는 다이알로그 박스를 표시해, 네트워크상에서 열거를 실행하기 위한 정보 가운데,DirectPlay4.InitializeConnection 로 제공되어 있지 않은 것 (전화번호, IP 주소등)를 유저에게 요구할 수가 있다. 서비스 프로바이더가 브로드캐스트 열거를 실행할 수 있어 유저에게 추가 정보를 요구하지 않는 경우, 다이알로그 박스는 표시되지 않는다.


DirectPlay4.GetGroupData

DirectPlay4.GetGroupData 메소드는, 그룹에 관련지을 수 있던, 어플리케이션에 고유의 캐릭터 라인을 취득한다.

object. GetGroupData(GroupId As Long, _
    flags As CONST_DPGETFLAGS) As String

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
GroupId
데이터를 요구하는 그룹의 ID.
flags
CONST_DPGETFLAGS 열거형의 값으로, 취득하는 그룹 데이터의 타입 (로컬 또는 리모트)을 나타낸다. 이 파라미터를 0 으로 설정 하면, 리모트 데이터가 취득된다.

반환값

성공하면,DirectPlay4.SetGroupData 메소드에 의해 그룹에 관련지을 수 있었던 데이터를 포함한 캐릭터 라인을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

주의

DirectPlay 는, 로컬 또는 리모트의 몇개의 타입의 그룹 데이터를 유지할 수가 있다. 어플리케이션에서는, 어느 쪽의 타입의 데이터를 취득하는지 지정할 필요가 있다. 로컬 데이터는, 이 DirectPlay 오브젝트에 의해, DPSET_LOCAL 플래그를 사용해 설정되어 있다. 리모트 데이터는, 세션내의 임의의 어플리케이션에 의해, DPSET_REMOTE 플래그를 사용해 설정되어 있다.


DirectPlay4.GetGroupFlags

DirectPlay4.GetGroupFlags 메소드는, 지정된그룹을 기술하는 플래그를 취득한다.

object. GetGroupFlags(GroupId As Long) As Long

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
GroupId
플래그 설정을 취득하는 그룹의 ID.

반환값

성공하면, 그룹 플래그의 설정으로 설정된 값을 돌려준다. 이 값은,CONST_DPGROUPFLAGS 열거형의 이하의 멤버의 언젠가 또는 양쪽 모두가 된다.

DPGROUP_LOCAL
그룹은, 이 어플리케이션에 의해 생성 되었다. 이 플래그가 지정되어 있지 않은 경우, 그룹은 리모트 그룹이다.
DPGROUP_STAGINGAREA
그룹은 staging 영역이다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS .

참조

DirectPlay4.CreateGroup


DirectPlay4.GetGroupLongName

DirectPlay4.GetGroupLongName 메소드는,그룹에 관련지을 수 있었던 롱 네임을 취득한다.

object. GetGroupLongName(GroupId As Long) As String

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
GroupId
이름을 요구하는 그룹의 ID.

반환값

이 메소드는, 그룹의 롱 네임을 돌려준다. 이 이름은,DirectPlay4.CreateGroup ,DirectPlay4.CreateGroupInGroup , 또는 DirectPlay4.SetGroupName 메소드의 formalName 파라미터로서 건네받는 값에 동일하다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlay4.GetGroupOwner

DirectPlay4.GetGroupOwner 메소드는,그룹의 현재의 소유자의 ID 를 취득한다. 이 메소드는, 로비 세션에서만 유효하다.

object. GetGroupOwner(GroupId As Long) As Long

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
GroupId
소유자를 요구하는 그룹의 ID.

반환값

그룹의 소유자의 DirectPlay ID 를 돌려준다. 소유자는,DirectPlay4.SetGroupOwner 메소드에 의해 설정되어 있다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlay4.GetGroupParent

DirectPlay4.GetGroupParent 메소드는, 그룹을 포함하고 있는그룹의 ID 를 취득한다.

object. GetGroupParent(GroupId As Long) As Long

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
GroupId
부모를 요구하는 그룹의 ID.

반환값

DirectPlay4.CreateGroupInGroup 에 의해, 그룹이 다른 그룹내에서 생성 되고 있는 경우는, 부모의 DirectPlay ID 를 돌려준다. 그룹이 다른 그룹내에서 생성되어 있지 않은 경우는, 0 을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectPlay4.CreateGroupInGroup


DirectPlay4.GetGroupShortName

DirectPlay4.GetGroupShortName 메소드는,그룹에 관련지을 수 있고 있는 쇼트 네임을 취득한다.

object. GetGroupShortName(GroupId As Long) As String

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
GroupId
이름을 요구하는 그룹의 ID.

반환값

그룹의 쇼트 네임을 돌려준다. 이 이름은,DirectPlay4.CreateGroup ,DirectPlay4.CreateGroupInGroup , 또는 DirectPlay4.SetGroupName 메소드의 friendlyName 파라미터로서 건네받는 값에 동일하다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlay4.GetMessageCount

DirectPlay4.GetMessageCount 메소드는, 지정된 로컬 플레이어의 수신 큐내에 있는 메세지의 수를 취득한다.

object. GetMessageCount(playerId As Long) As Long

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
playerId
메세지수를 요구하는 플레이어의 ID. 이 플레이어는 로컬이 아니면 안된다.

반환값

메세지의 수를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectPlay4.Receive


DirectPlay4.GetMessageQueue

DirectPlay4.GetMessageQueue 메소드는, 로컬 플레이어에 대한 송신 또는 수신 큐에 관한 정보를 취득한다. 1 대의 머신상에서 1 개의 세션내에 2 명 이상의 플레이어가 존재하는 경우, 돌려주어지는 데이터는, 그러한 플레이어 모든 편성에 대해서 유효하다.

object. GetMessageQueue(from As Long, _
    to As Long, _
    flags As CONST_DPMESSAGEQUEUEFLAGS, _
    nMessage As Long, _
    nBytes As Long)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
from
큐 상태의 취득 대상이 된다, 메세지를 송신하고 있는 플레이어의 ID. 0 을 지정 하면, 송신된 모든 메세지에 관한 정보가 돌려주어진다. to 도 지정했을 경우는,from 로 지정된 플레이어로부터의 메세지와to 로 지정된 메세지에 대한 메세지만이 돌려주어진다.
to
큐 상태의 취득 대상이 된다, 메세지가 송신된 플레이어의 ID. 0 을 지정 하면, 송신된 모든 메세지에 관한 정보가 돌려주어진다. from 도 지정했을 경우는,from 로 지정된 플레이어로부터의 메세지와to 로 지정된 메세지에 대한 메세지만이 돌려주어진다. 그룹 ID 를 to 로 지정하는 것은 할 수 없다.
flags
큐에 관해서 취득하는 정보의 타입을 지정하는 플래그. 디폴트 (flags = 0)에서는, 송신 큐에 관한 정보를 돌려준다. 이 플래그에는, 이하의 몇개의 값만을 설정할 수 있다.
DPMESSAGEQUEUE_SEND
송신 큐에 관한 정보를 취득한다.
DPMESSAGEQUEUE_RECEIVE
수신 큐에 관한 정보를 취득한다.
nMessage
큐내의 메세지의 수를 받는 변수.
nBytes
큐내의 모든 메세지의 바이트수를 받는 변수.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_UNSUPPORTED

이 메소드는,to 에 리모트 플레이어를 지정해 수신 큐 (DPMESSAGEQUEUE_RECEIVE)를 체크 하면, DPERR_INVALIDPLAYER 를 돌려준다. from 에 리모트 플레이어를 지정해 송신 큐 (DPMESSAGEQUEUE_SEND)를 체크 하면, DPERR_INVALIDPLAYER 를 돌려준다. flags 가 DPMESSAGEQUEUE_RECEIVE Or DPMESSAGEQUEUE_SEND 의 경우는, DPERR_INVALIDFLAGS 를 돌려준다. DirectPlay 프로토콜이 온이 되어 있지 않고, 서비스 프로바이더가 송신 큐의 체크를 지원 하고 있지 않는 경우에 송신 큐를 체크하려고 하면(자), DPERR_UNSUPPORTED 를 돌려준다.

주의

어플리케이션에서는, 송신 큐 상태를 감시하는 것으로써, 기반이 되는 네트워크의 대역폭에 근거해, 세션내외의 플레이어에게 송신하는 메세지의 수를 조절할 수가 있다.


DirectPlay4.GetPlayerAccountId

DirectPlay4.GetPlayerAccountId 메소드는, 보증 세션으로세션의호스트에 의해 불려 갔을 경우에, 지정된 플레이어의 어카운트 식별자를 취득한다.

object. GetPlayerAccountId(playerId As Long) As String

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
playerId
어카운트 정보를 취득하는 플레이어의 ID.

반환값

이 메소드는, 안전한 방법으로 로그 온 하고 있는 플레이어를 기술하는 일의의 식별자를 돌려준다. 식별자의 형식은, 사용하고 있는 Security Support Provider Interface (SSPI) 패키지에 따라서 다르다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

이 메소드에 의해 돌려주어지는 정보는, 어카운트를 일의에 식별한다. 이 정보를 사용해, 로그 온 하고 있는 플레이어의 트랜잭션(transaction)나 다른 동작을 기록할 수가 있다.

참조

DirectPlay4.SecureOpen


DirectPlay4.GetPlayerAddress

DirectPlay4.GetPlayerAddress 메소드는, 플레이어의DirectPlay 주소를 취득한다.

로컬 플레이어에 대해서 불려 갔을 경우는, 그 컴퓨터의 네트워크 주소 (이용 가능한 경우)를 돌려준다. 경우에 따라서는, 2 개(살) 이상의 주소가 돌려주어지는 경우가 있다 (예를 들어, TCP/IP 로, 컴퓨터가 네트워크 카드와 다이얼 업 인터넷 접속의 양쪽 모두를 갖추고 있는 경우 등).

object. GetPlayerAddress(playerId As Long) _
    As DirectPlayAddress

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
playerId
주소를 요구하는 플레이어의 ID. 0 을 건네주면(자), 서비스 프로바이더에 대해서 유효한 주소 옵션의 리스트가 돌려주어진다.

반환값

성공하면,DirectPlayAddress 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해, 요구된 플레이어 ID 를 이용할 수 없는 경우는,Err.Number 에 DPERR_UNAVAILABLE 가 설정된다.


DirectPlay4.GetPlayerCaps

DirectPlay4.GetPlayerCaps 메소드는, 지정된 플레이어의 현재의 능력을 취득한다.

object. GetPlayerCaps(playerId As Long, _
    caps As DPCAPS, _
    flags As CONST_DPGETCAPSFLAGS)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
playerId
능력을 취득하는 플레이어의 ID.
caps
능력이 설정되는 DPCAPS 형.
flags
능력의 계산방법을 나타내는 값. 0 을 설정 하면, 보증 없음의 메시징에 대한 능력이 계산된다. DPGETCAPS_GUARANTEED 를 설정 하면, 보증 메시징에 대한 능력이 취득된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

참조

DirectPlay4.GetCaps ,DirectPlay4.Send


DirectPlay4.GetPlayerData

DirectPlay4.GetPlayerData 메소드는,DirectPlay4.SetPlayerData 에 의해 플레이어 ID 에 관련지을 수 있던, 어플리케이션 고유의 데이터 블록을 소득한다.

object. GetPlayerData(playerId As Long, _
    flags As CONST_DPGETFLAGS) As String

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
playerId
데이터를 요구하는 플레이어의 ID.
flags
취득하는 플레이어 데이터의 타입 (로컬 또는 리모트)을 나타내는,CONST_DPGETFLAGS 열거형의 값. 이 파라미터에 0 을 설정 하면, 리모트 데이터가 취득된다.

반환값

어플리케이션 정의의 데이터를 포함한 캐릭터 라인을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_BUFFERTOOSMALL
DPERR_INVALIDFLAGS
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER

주의

로컬 데이터는, 현재의 DirectPlay 오브젝트에 의해,DirectPlay4.SetPlayerData 로 DPSET_LOCAL 플래그를 사용해 설정되어 있다. 리모트 데이터는,세션내의 임의의 어플리케이션에 의해,DPSET_REMOTE 플래그를 사용해 설정된 가능성이 있다.


DirectPlay4.GetPlayerFlags

DirectPlay4.GetPlayerFlags 메소드는, 플레이어가 생성 되었을 때에, 그 플레이어를 기술하기 위해서 사용된 플래그를 취득한다.

object. GetPlayerFlags(id As Long) As CONST_DPPLAYERFLAGS

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
id
플래그 설정을 취득하는 플레이어의 ID.

반환값

플레이어의 플래그 설정을 돌려준다. 반환값에는, 이하의 1 개 이상의 값이 포함된다.

DPPLAYER_LOCAL
플레이어는, 이 어플리케이션에 의해 생성 되었다. 이 플래그가 지정되어 있지 않은 경우, 플레이어는 리모트 플레이어이다.
DPPLAYER_SERVERPLAYER
플레이어는, 클라이언트/서버 통신의 서버 플레이어이다.
DPPLAYER_SPECTATOR
플레이어는, 관객으로서 생성 되었다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectPlay4.CreatePlayer


DirectPlay4.GetPlayerFormalName

DirectPlay4.GetPlayerFormalName 메소드는, 플레이어가 관련지을 수 있고 있는 정식명을 취득한다.

object. GetPlayerFormalName(playerId As Long) As String

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
playerId
이름을 요구하는 플레이어의 ID.

반환값

성공하면, 플레이어의 정식명을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER

참조

DirectPlay4.CreatePlayer ,DirectPlay4.GetPlayerFriendlyName ,DirectPlay4.SetPlayerName


DirectPlay4.GetPlayerFriendlyName

DirectPlay4.GetPlayerFriendlyName 메소드는, 플레이어가 관련지을 수 있고 있는 프렌들리명을 취득한다.

object. GetPlayerFriendlyName(playerId As Long) As String

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
playerId
이름을 요구하는 플레이어의 ID.

반환값

성공하면, 플레이어의 프렌들리명을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER

참조

DirectPlay4.CreatePlayer ,DirectPlay4.GetPlayerFormalName ,DirectPlay4.SetPlayerName


DirectPlay4.GetSessionDesc

DirectPlay4.GetSessionDesc 메소드는, 현재 열려 있는 세션의 프로퍼티를 취득한다.

object. GetSessionDesc(sessionDesc As DirectPlaySessionData)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
sessionDesc
세션에 관한 정보를 받는 DirectPlaySessionData 오브젝트. 이 오브젝트는,DirectPlay4.CreateSessionData 메소드를 사용해 취득된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_BUFFERTOOSMALL
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOCONNECTION


DirectPlay4.InitializeConnection

DirectPlay4.InitializeConnection 메소드는, DirectPlay 접속을 초기화한다. 사용하는서비스 프로바이더, 서버의 네트워크 주소, 세션의 GUID 등, 접속에 관한 모든 정보는,addr 파라미터를 개입시켜 건네받는다.

object. InitializeConnection(addr As DirectPlayAddress)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
addr
초기화하는 접속에 관한 모든 정보에의 액세스를 제공하는 DirectPlayAddress 오브젝트. 「주의」를 참조할것.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_ALREADYINITIALIZED
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_UNAVAILABLE

이 메소드는, 이 오브젝트에 대해서,InitializeConnection 가 이미 불려 가고 있는 경우는, DPERR_ALREADYINITIALIZED 를 돌려준다. 서비스 프로바이더를 초기화할 수 없었던 경우는, DPERR_UNAVAILABLE 를 돌려준다. 이 상태는, 해당의 서비스 프로바이더를 이용하기 위한 필요한 리소스가 존재하지 않는 경우 (예를 들어, TCP/IP 스택이 존재하지 않는 경우등)에 발생할 가능성이 있다.

주의

이 메소드에게 건네지는 addr 파라미터는,DirectPlay4.GetDPEnumConnections 메소드로부터 취득할 수가 있다. 또는,DirectPlayLobby3 의 주소 생성 메소드의 어느쪽이든을 사용해, 이 파라미터를 직접 생성 할 수도 있다.

이 메소드는, 적절한 서비스 프로바이더를 로드해, 초기화한다. addr 파라미터는, 서비스 프로바이더에게 건네진다. 서비스 프로바이더는, 관련하는 정보를 꺼내 보존한다. 이 정보는,DirectPlay4.GetDPEnumSessions 메소드 또는 DirectPlay4.Open 메소드를 호출하면나무에 사용된다. 이것에 의해, 서비스 프로바이더가 같은 정보를 요구하는 다이알로그 박스를 표시하지 않게 한다.

참조

DirectPlayAddress


DirectPlay4.Open

DirectPlay4.Open 메소드는,DirectPlay4.GetDPEnumSessions 메소드를 호출해 열거된세션에 참가 하면 와, 또는 유저가 열거 및 참가 가능한 새로운 세션을 생성 할 경우에 사용한다.

object. Open(sessionDesc As DirectPlaySessionData, _
    flags As CONST_DPOPENFLAGS)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
sessionDesc
세션을 기술하는 DirectPlaySessionData 오브젝트. 이 오브젝트는,DirectPlay4.CreateSessionData 메소드를 사용해 취득된다.

세션을 생성 하는 경우는, 생성 하는 세션의 프로퍼티 (DirectPlay 에 의해 제공되는 GuidInstance 를 제외한다)를 사용해,DirectPlaySessionData 오브젝트를 완전하게 초기화할 필요가 있다.

flags
CONST_DPOPENFLAGS 열거형의 플래그.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_ACCESSDENIED
DPERR_ALREADYINITIALIZED
DPERR_AUTHENTICATIONFAILED
DPERR_CANNOTCREATESERVER
DPERR_CANTCREATEPLAYER
DPERR_CANTLOADCAPI
DPERR_CANTLOADSECURITYPACKAGE
DPERR_CANTLOADSSPI
DPERR_CONNECTING
DPERR_CONNECTIONLOST
DPERR_ENCRYPTIONFAILED
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPASSWORD
DPERR_LOGONDENIED
DPERR_NOCONNECTION
DPERR_NONEWPLAYERS
DPERR_NOSESSIONS
DPERR_SIGNFAILED
DPERR_TIMEOUT
DPERR_UNINITIALIZED
DPERR_USERCANCEL

이 메소드는, 이 DirectPlay 오브젝트상에 이미 연 세션이 존재하는 경우는, DPERR_ALREADYINITIALIZED 를 돌려준다.

세션 기술의 최대 플레이어수에 이미 달하고 있는 경우는, DPERR_CANTCREATEPLAYER 를 돌려준다.

세션이 Open 요구에 응답하지 않았던 경우는, DPERR_TIMEOUT 를 돌려준다.

유저가 열거 처리를 캔슬했을 경우 (보통은,서비스 프로바이더의 다이알로그 박스를 캔슬하는 것으로써, 열거 처리를 캔슬한다)는,DPERR_USERCANCEL 를 돌려준다.

기술에 일치하는 오픈 세션이 존재하지 않는 경우, 세션이 내부 세션 리스트에 존재하지 않는 경우, 또는 세션 GUID 가 부정한 경우는, DPERR_NOSESSIONS 를 돌려준다.

주의

어플리케이션이 세션에 참가 하면, 플레이어를 생성 해, 세션내외의 플레이어와의 통신을 시작 할 수가 있다. 어플리케이션은,DirectPlay4.CreatePlayer 를 사용해 로컬 플레이어를 생성 할 때까지는, 이 DirectPlay 오브젝트상에서 메세지를 수신하는 일도, 메세지를 송신하는 일도 할 수 없다.

2 개의 세션을 동시에 열어 고향은, 2 개의 DirectPlay 오브젝트를 생성 해, 각각으로 세션을 열 필요가 있다.

세션을 패스워드로 보호하는 경우는,DirectPlaySessionData.SetSessionPassword 를 호출할 필요가 있다. 세션을 열거 하면, 패스워드를 요구하는 세션에는, DPSESSION_PASSWORDREQUIRED 플래그가 설정된다.

보증 세션에 참가하는 경우는,DirectPlay4.SecureOpen 를 사용해, 로그 온용의 신용 정보를 제공할 필요가 있다. 세션을 열거 하면, 신용 정보를 요구하는 세션에는, DPSESSION_SECURESERVER 플래그가 설정된다.

DPSESSION_SECURESERVER 플래그를 설정 하면, 세션은 디폴트의 시큐러티 패키지인 NTLM 를 사용해 열린다. 다른 시큐러티 패키지를 지정하려면 ,SecureOpen 를 사용한다.

어플리케이션이 세션에 참가하려고 할 때, 서버는 Open 요구를 거부하는지, 또는 무시하는 (이 경우,Open 는 타임 아웃이 된다) 일이 생긴다. 새로운 플레이어가 무효가 되어 있거나, 참가가 무효가 되어 있거나, 플레이어의 한도에 이르러 있거나, 잘못한 패스워드가 제공되어 있거나 하는 세션에 참가하려고 하면(자), DPERR_NONEWPLAYERS 에러 또는 DPERR_INVALIDPASSWORD 에러가 돌려주어진다.

참조

DirectPlay4.Close


DirectPlay4.Receive

DirectPlay4.Receive 메소드는, 메시지 큐로부터 메세지를 꺼낸다.

object. Receive(fromPlayerId As Long, _
    toPlayerId As Long, _
    flags As CONST_DPRECEIVEFLAGS) As DirectPlayMessage

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
fromPlayerId
이 메소드가 돌아왔을 때에, 송신측의 플레이어의 ID 가 설정되는 변수. DPRECEIVE_FROMPLAYER 플래그를 지정했을 경우, 이 메소드를 호출하기 전에, 플레이어 ID 를 사용해 이 파라미터를 초기화할 필요가 있다.
toPlayerId
이 메소드가 돌아왔을 때에, 수신측의 플레이어의 ID 가 설정되는 변수. DPRECEIVE_TOPLAYER 플래그를 지정했을 경우, 이 메소드를 호출하기 전에, 플레이어 ID 를 사용해 이 파라미터를 초기화할 필요가 있다.
flags
CONST_DPRECEIVEFLAGS 열거형의 플래그로, 메세지의 취득 방법을 나타낸다. 이하의 1 개 이상의 제어 플래그를 설정할 수 있다. 디폴트 (flags = 0)에서는, 이용 가능한 최초의 메세지가 취득된다.
DPRECEIVE_ALL
이용 가능한 최초의 메세지를 돌려주어, 그 메세지를 메시지 큐로부터 삭제한다. 이것이 디폴트이다.
DPRECEIVE_PEEK
다른 플래그에 의해 지정된 메세지를 돌려주지만, 그 메세지를 메시지 큐로부터 삭제하지 않는다.
DPRECEIVE_TOPLAYER 및 DPRECEIVE_FROMPLAYER
DPRECEIVE_TOPLAYER 와 DPRECEIVE_FROMPLAYER 의 양쪽 모두를 지정했을 경우,Receive 에 의해, (1) toPlayerId 에 의해 지정되는 플레이어에게 송신된 메세지와(2) fromPlayerId 에 의해 지정되는 플레이어로부터 송신된 메세지만이 돌려주어진다. 양쪽 모두의 조건을 채우지 않으면 안 된다.

IDPRECEIVE_TOPLAYER 만을 지정했을 경우,Receive 는,toPlayerId 로 지정되는 플레이어에게 송신된 메세지만을 돌려준다.

DPRECEIVE_FROMPLAYER 만을 지정했을 경우,Receive 는,fromPlayerId 에 의해 지정되는 플레이어로부터 송신된 메세지만을 돌려준다.

DPRECEIVE_TOPLAYER 와 DPRECEIVE_FROMPLAYER 의 어느쪽이나 설정하고 있지 않는 경우,Receive 는 이용 가능한 최초의 메세지를 돌려준다.

반환값

성공하면, 메세지의 내용을 취득하기 위해서 사용하는 메소드를 가지는 DirectPlayMessage 오브젝트를 돌려준다. 보류중의 메세지가 존재하지 않는 경우는, Nothing 를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_GENERIC
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

주의

DPID_ALLPLAYERS 라고 정의되는 플레이어 ID 에 송신된 메세지, 또는그룹 ID 에 송신된 메세지도, 송신측의 플레이어 ID 로부터 송신된 것처럼 인식된다. 어플리케이션은, 로컬 플레이어에게 송신된 메세지만을 수신한다. 플레이어는,fromPlayerId 로 나타나는 값과toPlayerId 로 나타나는 값이 동일한 메세지를 수신할 수 없다.

DPSESSION_NOMESSAGEID 가세션 기술로 지정되고 있는 경우,fromPlayerId 는 항상 0xFFFFFFFF 가 되어,toPlayerId 의 값은 임의가 된다.

DirectPlay 에 부속하고 있는 모든 서비스 프로바이더는, 파괴를 막기 위해서(때문에), 데이터에 대해서 정합성 체크를 실행한다. Receive 를 사용해 취득한 메세지는, 모두 파괴로부터 보호된다.

참조

DirectPlay4.Send


DirectPlay4.SecureOpen

DirectPlay4.SecureOpen 메소드는, 보증 세션을 생성 하는지, 또는 참가한다. 보증 세션에 참가하려면 , 이 메소드를 사용해, 로그 온용의 인증 정보를 건네준다.

새로운 세션을 생성 하는 경우,호스트 컴퓨터는, 사용하는 다른 시큐러티 패키지를 지정할 수가 있다. 세션에 참가하는 경우, 컴퓨터는, 유저명과 패스워드를 지정할 수가 있다.

object. SecureOpen(sessionDesc DirectPlaySessionData, _
    flags As CONST_DPOPENFLAGS, _
    security As DPSECURITYDESC,
    credentials As DPCREDENTIALS))

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
sessionDesc
생성 또는 참가하는세션을 기술하는DirectPlaySessionData 오브젝트. 세션에 참가하는 경우는,SetGuidInstance 메소드와 SetSessionPassword 메소드만을 호출해, 오브젝트를 초기화하면 좋다. 패스워드를 건네줄 필요가 있는 것은, 열거된 세션에 DPSESSION_PASSWORDREQUIRED 플래그가 설정되어 있는 경우 뿐이다.

세션을 생성 하는 경우는, 생성 하는 세션의 프로퍼티 (다만, DirectPlay 가 제공하는, 인스턴스의 GUID 를 제외한다)를 사용해,DirectPlaySessionData 오브젝트를 완전하게 초기화할 필요가 있다.

세션을 여는 모든 컴퓨터를 인증할 필요가 있는 것을 나타내기 위해서(때문에), DPSESSION_SECURESERVER 플래그를 설정한다. DPSESSION_SECURESERVER 플래그를 설정하지 않는 경우,SecureOpen 는,DirectPlay4.Open 를 호출했을 때 것과 같이, 비보증 세션을 연다.

flags
CONST_DPOPENFLAGS 열거형의 플래그.
security
사용하는 시큐러티 패키지를 포함한 DPSECURITYDESC 형. 디폴트의 시큐러티 패키지 (NTLM)와 CryptoAPI 패키지 (Microsoft RSA Base Cryptographic Provider)를 사용하는 경우는, 이 형태의 모든 멤버를 0 에 초기화한다. 이 멤버는, 세션을 생성 하는 경우에게만 관계가 있다. 세션에 참가하는 경우는, 초기화되어 있지 않은 구조체를 건네주어도 괜찮다.
credentials
로그 온명, 패스워드, 및 서버상에서 인증하는 도메인을 포함한 DPCREDENTIALS 형. 신용 정보가 존재하지 않는 경우는, 이 형태의 멤버를 0 에 초기화한다. 세션을 생성 할 경우에는, 신용 정보는 무시된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_ACCESSDENIED
DPERR_ALREADYINITIALIZED
DPERR_AUTHENTICATIONFAILED
DPERR_CANNOTCREATESERVER
DPERR_CANTLOADCAPI
DPERR_CANTLOADSECURITYPACKAGE
DPERR_CANTLOADSSPI
DPERR_CONNECTING
DPERR_CONNECTIONLOST
DPERR_ENCRYPTIONFAILED
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPASSWORD
DPERR_LOGONDENIED
DPERR_NOCONNECTION
DPERR_NONEWPLAYERS
DPERR_SIGNFAILED
DPERR_TIMEOUT
DPERR_UNINITIALIZED
DPERR_USERCANCEL

무효인 신용 정보를 사용해 불려 갔을 경우, 또는 신용 정보가 필요한 경우에 신용 정보없이 불려 갔을 경우는, DPERR_LOGONDENIED 를 돌려준다. 어플리케이션에서는, 유저의 신용 정보를 수집해,SecureOpen 를 재차 호출할 필요가 있다.

주의

세션에 참가하는 경우는, 우선 신용 정보를 사용하지 않고 SecureOpen 를 호출한다. DPERR_LOGONDENIED 가 돌려주어지면(자), 유저로부터 유저명과 패스워드를 취득해 SecureOpen 를 재차 호출해,credentials 파라미터를 개입시켜 유저에게 신용 정보를 건네줄 필요가 있다. DP_OK 가 돌려주어지면(자), 플레이어는, 시스템에의 로그 온시 (NTLM에서는, 네트워크 로그 온)로 지정한 신용 정보를 사용해, 로그 온 할 수 있던 것이 된다.


DirectPlay4.Send

DirectPlay4.Send 메소드는, 다른 플레이어, 플레이어의그룹, 또는 세션내의 모든 플레이어에게 메세지를 송신한다.

메세지는, 메세지 마다 보증 붙어 또는 보증 없음의 프로토콜을 사용해 송신할 수가 있다. 세션이 보증 서버에 의해 호스트 되고 있는 경우는, 메세지 마다 암호화 (프라이버시를 보증하기 위해(때문에)) 또는 디지털 서명 (신원을 보증하기 위해(때문에))을 베풀어, 메세지를 송신할 수가 있다.

object. Send(fromPlayerId As Long, _
    toPlayerId As Long, _
    flags As CONST_DPSENDFLAGS, _
    msg As DirectPlayMessage)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
fromPlayerId
송신측 플레이어의 ID. 이 플레이어 ID 는, 컴퓨터 위에의 로컬 플레이어의 어느 쪽인가에 일치하고 있지 않으면 안 된다.
toPlayerId
메세지의 송신지 ID. 메세지를 다른 플레이어에게 송신하려면 , 송신지의 플레이어의 ID 를 지정한다. 메세지를 그룹내의 모든 플레이어에게 송신하려면 , 그 그룹의 ID 를 지정한다. 메세지를 세션내의 모든 플레이어에게 송신하려면 , 정수 DPID_ALLPLAYERS 를 사용한다. 메세지를 서버 플레이어에게 송신하려면 , 정수 DPID_SERVERPLAYER 를 사용한다. 플레이어는, 스스로에 메세지를 송신할 수 없다.
flags
메세지의 송신 방법을 지정하는 값. 디폴트 (flags = 0)에서는, 메세지는 보증없이 송신된다.
DPSEND_ENCRYPTED
메세지를 암호화해 송신한다. 이것을 할 수 있는 것은, 보증 세션의 경우 뿐이다. 이 플래그는, DPSEND_GUARANTEED 플래그도 설정되어 있는 경우에 한정해, 사용할 수 있다. 메세지는,DPSYS_SECUREMESSAGE 시스템 메세지로서 송신된다.
DPSEND_GUARANTEED
보증된 전달 방법을 사용해, 메세지를 송신한다.
DPSEND_SIGNED
디지털 서명을 더해, 메세지를 송신한다. 이것을 할 수 있는 것은, 보증 세션의 경우 뿐이다. 이 플래그는, DPSEND_SIGNED 플래그도 설정되어 있는 경우에 한정해, 사용할 수 있다. 메세지는, DPSYS_SECUREMESSAGE 시스템 메세지로서 송신된다.
msg
송신되는 데이터를 나타내는 DirectPlayMessage 오브젝트. 이 오브젝트는,DirectPlay4.CreateMessage 메소드를 사용해 취득된다. 또, 이 오브젝트 자체의 메소드를 사용해, 오브젝트에 데이터를 대입할 수가 있다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_BUSY
DPERR_CONNECTIONLOST
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_NOTLOGGEDIN
DPERR_SENDTOOBIG

보증 첨부와 지정되어 있지 않은 메세지에 암호화 또는 서명의 플래그가 설정되어 있는 경우는, DPERR_INVALIDPARAMS 를 돌려준다. 클라이언트 어플리케이션이, 최초로 로그 온 하지 않고 보증 메세지를 송신하려고 했을 경우는, DPERR_NOTLOGGEDIN 를 돌려준다.

메세지를 그룹에 송신하는 경우, 반환값 DP_OK 는, 반드시 그룹내의 모든 플레이어가 메세지를 수신한 것을 나타내는 것은 아니다. 메세지를 보증 첨부로 송신했을 경우, DP_OK 는, DirectPlay 가 그 메세지를 그룹내의 모든 플레이어에게 송신하기 위해서 전력을 다한 것을 의미한다. 보통, 이 메세지를 수신하지 않는 플레이어는, 세션으로부터 삭제된다. 이것은, 그러한 플레이어의 접속에 문제가 있기 때문이다.

주의

비동기 송신의 옵션을 사용하는 경우는,DirectPlay4.SendEx 를 사용한다.

시스템 메세지 이외의 메세지는, 보증 붙어 또는 보증 없음의 어느 쪽인지로 송신할 수 있다. 디폴트에서는, 비시스템 메세지는, 보증없이 송신된다. 이것은, DirectPlay 가, 메세지가 송신지에 닿은 것을 보증하지 않는다고 하는 것이다. 보증 메세지의 송신에는, 상당한 시간이 걸린다. 최악이어도, 보증 없음의 메세지의 2 배에서 3 배의 시간이 걸린다. 어플리케이션에서는, 보증 메세지의 송신을 가능한 한 줄임과 동시에, 메세지의 상실에 견딜 수 있도록(듯이) 할 필요가 있다.

시스템 메세지는, 서비스 프로바이더가 보증 메세지를 네이티브에 지원 하고 있을지 어떨지, 또는 DirectPlay 프로토콜의 플래그가 설정되어 있는지 어떤지에 관계없이, 항상 보증 첨부로 송신된다. 시스템 메세지를 보증 첨부로 송신하는 경우는, DirectPlay 프로토콜이 자동적으로 사용된다.

시스템 메세지 이외의 메세지의 경우, 어플리케이션이 DirectPlay 프로토콜의 플래그를 설정해, 메세지를 보증 첨부로 송신 하면 (DPSEND_GUARANTEED 플래그를 설정한다), 서비스 프로바이더가 보증 메세지를 지원 할지 어떨지에 관계없이, 메세지는 보증 첨부로 송신된다.

시스템 메세지 이외의 메세지의 경우, 어플리케이션이 DirectPlay 프로토콜의 플래그를 설정하지 않고, 메세지를 보증 첨부로 송신 하면, 서비스 프로바이더가 보증 메세지를 지원 하는 경우에 한정해, 메세지는 보증 첨부로 송신된다. 서비스 프로바이더가 보증 메세지를 지원 하지 않는 경우, DPSEND_GUARANTEED 플래그에 관계없이, 메세지는 보증 첨부에서는 송신되지 않는다.

어플리케이션은, 세션을 생성 할 경우에 DPSESSION_DIRECTPLAYPROTOCOL 플래그를 설정해, DirectPlay 프로토콜을 시작 한다.

DirectPlay 에 부속하고 있는 모든 서비스 프로바이더는, 파괴를 막기 위해서(때문에), 데이터에 대해서 정합성 체크를 실행한다. 이 메소드를 사용해 송신된 메세지는, 모두 파괴로부터 보호된다.

플레이어는, 스스로에 메세지를 송신할 수 없다. 플레이어가, DPID_ALLPLAYERS 의 일부인 그룹 또는 DPID_ALLPLAYERS 에 메세지를 송신 하면, 플레이어는 그 메세지의 카피를 받지 않는다. 다만, 세션 기술로 DPSESSION_NOMESSAGEID 가 지정되고 있는 경우는 예외이다. 이 경우, 플레이어는, 스스로가 그룹에 송신한 메세지를 수신할 수가 있다. 이 메세지에는, 메세지의 송신자를 나타내는 DirectPlay 의 ID 헤더가 존재하지 않기 때문에, 메세지 ID 에 근거해 메세지를 필터링 할 수 없다.

타겟 컴퓨터상에 2 명 이상의 플레이어가 있는 경우, 메세지가 누구의 수신 큐에 나타날까를 판단할 수 없다. 메세지를 수신 하면, 그 메세지는, DPID_UNKNOWN 라고 하는 플레이어로부터 송신된 것처럼 보인다.

Send 메소드를 사용해 송신할 수 있는 메세지의 사이즈에 제한은 없다. DirectPlay 는, 사이즈의 큰 메세지를 자동적으로 패킷에 분할 (패킷화)해, 수신측에서 그것들을 재차 조립한다. 큰 메세지를 보증없이 송신하는 경우에는 주의가 필요하다. 패킷이 1 개에서도 송신지에 닿지 않는다고 메세지 전체가 무시된다. 어플리케이션에서는,GetCaps 를 호출해,DPCAPS 형의 lMaxBufferSize 멤버를 조사하는 것으로, 패킷의 최대 사이즈를 판단할 수가 있다.

암호화된 메세지 또는 서명 첨부의 메세지를 송신 하면, 그 메세지는, 어플리케이션 메세지는 아니고,DPSYS_SECUREMESSAGE 시스템 메세지로서 전송 된다.

참조

DirectPlay4.Receive ,DirectPlay4.SendChatMessage ,CONST_DPIDFLAGS


DirectPlay4.SendChatMessage

DirectPlay4.SendChatMessage 메소드는, 다른 플레이어, 플레이어의그룹, 또는 모든 플레이어에게 텍스트 메세지를 송신한다. 채팅 메세지를 수신하고 있는 플레이어는, 플레이어의 수신 큐내의 DPSYS_CHAT 시스템 메세지로 통지된다. 이 메소드는, 로비 세션으로 사용할 필요가 있다.

object. SendChatMessage(fromPlayerId As Long, _
    toPlayerId As Long, _
    flags As CONST_DPSENDFLAGS, _
    message As String)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
fromPlayerId
송신측의 플레이어의 ID. 이 플레이어 ID 는, 이 컴퓨터 위에의 로컬 플레이어의 어느 쪽인가에 일치하고 있지 않으면 안 된다.
toPlayerId
메세지를 송신하는 플레이어의 ID, 플레이어의 그룹의 ID, 또는 세션내의 모든 플레이어에게 메세지를 송신하는 경우는 DPID_ALLPLAYERS.
flags
메세지의 송신 방법을 나타내는 값. 이 파라미터에 0 을 설정 하면, 메세지는 보증없이 송신된다.
DPSEND_GUARANTEED
이용 가능하면, 보증된 전달 방법을 사용해 메세지를 송신한다.
message
송신하는 메세지.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

toPlayerId 의 ID 가 유효한 플레이어 또는 그룹이 아닌 경우는, DPERR_INVALIDPARAMS 를 돌려준다. fromPlayerId 의 ID 가 유효한 플레이어가 아닌 경우는, DPERR_INVALIDPLAYER 를 돌려준다. fromPlayerId 의 ID 가 로컬 플레이어가 아닌 경우는, DPERR_ACCESSDENIED 를 돌려준다.

주의

이 메소드는, 다른 클라이언트 어플리케이션이 접속 가능한 로비 세션내에서의 플레이어대 플레이어의 채팅을 가능하게 한다. 어플리케이션 세션에서는,DirectPlay4.Send 메소드를 사용해 채팅 메세지를 송신할 수가 있다.

수신측의 플레이어는, 시스템 메세지 (fromPlayerId = DPID_SYSMSG)를 받아들인다.


DirectPlay4.SendEx

DirectPlay4.SendEx 메소드는, 다른 플레이어, 플레이어의그룹, 또는 세션내의 모든 플레이어에게 메세지를 송신한다. SendEx 는,DirectPlay4.Send 메소드의 강화판이며, 보다 많은 옵션을 이용할 수 있다. SendEx 는, 보증 첨부 및 보증 없음의 양쪽 모두의 메세지를 지원 한다. 또, 비동기 메세지의 송신이라고 메세지의 우선 순위 및 타임 아웃의 설정을 가능하게 한다.

object. SendEx(fromPlayerId As Long, _
    toPlayerId As Long, _
    flags As CONST_DPSENDFLAGS, _
    msg As DirectPlayMessage, _
    priority As Long, _
    timeOut As Long, _
    context As Long) As Long

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
fromPlayerId
송신측의 플레이어의 ID. 이 플레이어 ID 는, 이 메세지를 발신한 컴퓨터 위에의 로컬 플레이어의 어느 쪽인가에 일치하고 있지 않으면 안 된다.
toPlayerId
메세지의 송신지의 ID. 메세지를 다른 플레이어에게 송신하려면 , 그 플레이어의 ID 를 설정한다. 메세지를 그룹내의 모든 플레이어에게 송신하려면 , 그 그룹의 ID 를 지정한다. 메세지를 세션내의 모든 플레이어에게 송신하려면 , 정수 DPID_ALLPLAYERS 를 사용한다. 메세지를 서버 플레이어에게 송신하려면 , 정수 DPID_SERVERPLAYER 를 지정한다. 플레이어는, 스스로에 메세지를 송신할 수 없다.
flags
메세지의 송신 방법을 지정하는,CONST_DPSENDFLAGS 열거형의 플래그. 디폴트 (flags = 0)에서는, 메세지는 보증없이 송신된다.
DPSEND_ASYNC
메세지를 비동기에 송신한다. 메소드는 즉시 돌아온다. 이 플래그를 지정하지 않는 경우, 메소드는, 메세지가 송신될 때까지 ( 및, 보증 첨부로 송신되는 경우는, 송신이 확인될 때까지) 돌아오지 않는다. 송신이 완료 하면,DPSYS_SENDCOMPLETE 시스템 메세지가 송신된다.

이 플래그를 사용 하면, 메세지가 송신 큐에 배치되었을 경우는, 반환값이 DPERR_PENDING 가 된다. 이것은 치명적인 에러는 아니고, 메세지가 송신되지 않았던 것을 즉시 전하는 것만으로 있다.

DPSEND_ENCRYPTED
메세지를 암호화해 송신한다. 이것을 할 수 있는 것은, 보증 세션의 경우 뿐이다. 이 플래그는, DPSEND_GUARANTEED 플래그도 설정되어 있는 경우에 한정해, 사용할 수 있다. 메세지는,DPSYS_SECUREMESSAGE 시스템 메세지로서 송신된다.
DPSEND_GUARANTEED
이용 가능하면, 보증된 전달 방법을 사용해 메세지를 송신한다.
DPSEND_NOSENDCOMPLETEMSG
이 플래그를 설정 하면, 완료 메세지는 송신되지 않는다. 이 플래그는, DPSEND_ASYNC 도 설정되어 있는 경우에 한정해, 사용할 수 있다.
DPSEND_SIGNED
디지털 서명 첨부로 메세지를 송신한다. 이것을 할 수 있는 것은, 보증 세션의 경우 뿐이다. 이 플래그는, DPSEND_GUARANTEED 플래그도 설정되어 있는 경우에 한정해, 사용할 수 있다. 메세지는, DPSYS_SECUREMESSAGE 시스템 메세지로서 송신된다.
msg
송신하는 데이터를 나타내는 DirectPlayMessage 오브젝트. 이 오브젝트는,DirectPlay4.CreateMessage 메소드를 사용해 취득된다. 이 오브젝트 자체의 메소드를 사용해, 오브젝트에 데이터를 대입할 수가 있다.
priority
메세지의 우선 순위를, 0 ~ 65535 의 범위에서 지정한다. 0 은, 가장 우선 순위가 낮다. 번호가 커지는 만큼, 우선 순위는 높다. 우선 순위의 설정된 메세지는, 큐내에 그 메세지보다 우선 순위의 높은 메세지가 없어지고 나서, 송신된다.

모든 서비스 프로바이더가, 이 옵션을 지원 하고 있는 것은 아니다. 지원되어 있지 않은 경우는, 0 이외의 우선 순위를 지정 하면, DPERR_UNSUPPORTED 에러가 돌려주어진다. 이 옵션이 지원 되고 있는지 어떤지를 판단하려면 ,DirectPlay4.GetCaps 를 호출한다.

timeOut
어플리케이션으로 제공되는 옵션의 타임 아웃. 메세지를 송신하는 시간제한을, 밀리 세컨드 단위로 지정한다. 이 시간내에 메세지를 송신할 수 없었던 경우, 메세지는 자동적으로 캔슬된다. 0 을 지정 하면, 타임 아웃은 사용되지 않는다.

모든 서비스 프로바이더가 이 옵션을 지원 하고 있는 것은 아니다. 지원 하고 있지 않는 경우는, 0 이외의 타임 아웃을 지정 하면, DPERR_UNSUPPORTED 에러가 돌려주어진다. 이 옵션이 지원 되고 있는지 어떤지를 판단하려면 ,DirectPlay4.GetCaps 를 호출한다.

context
송신이 완료했을 때에, 완료 메세지의 일부로서 어플리케이션에 돌려주어지는, 어플리케이션 정의의 문맥. 0 으로 설정할 수도 있다.

반환값

DirectPlay 에 의해 생성된, 메세지에 대한 ID 를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_BUSY
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER
DPERR_INVALIDPRIORITY
DPERR_NOTLOGGEDIN
DPERR_SENDTOOBIG
DPERR_UNSUPPORTED

보증 첨부와 지정되어 있지 않은 메세지에 대해서 암호화 또는 서명의 플래그가 설정되어 있는 경우는, DPERR_INVALIDPARAMS 를 돌려준다. 우선 순위의 값이 0 ~ 65535 가 아닌 경우는, DPERR_INVALIDPRIORITY 를 돌려준다. 우선 순위에 0 이외의 값이 지정되어 서비스 프로바이더가 우선 순위를 지원 하지 않는 경우, 또는 타임 아웃에 0 이외의 값을 지정해, 서비스 프로바이더가 그 옵션을 지원 하지 않는 경우는, DPERR_UNSUPPORTED 를 돌려준다.

주의

이 메소드는, 보증 첨부의 메세지와 보증 없음의 메세지를 지원 한다. 보증 첨부로 송신되는 메세지는, 수신 측에 인식되는 것을 대기하고 있는 보류중의 메세지가 존재하는 경우에, 블록 하지 않는다.

메세지를 비동기에 송신 하면, 메세지는 송신 큐에 넣어져SendEx 메소드는 즉시 돌아온다. 송신의 결과를 나타내기 위해서(때문에), 시스템 메세지가 송신측의 플레이어의 수신 큐에 넣어진다.

메세지에 우선 순위를 설정할 수가 있다. 메세지는, 그 메세지보다 우선 순위의 높은 메세지가 송신을 대기하고 있지 않고, 충분한 대역폭이 이용 가능한 경우에, 송신된다.

메세지에 타임 아웃을 설정할 수가 있다. DirectPlay 가 지정된 시간내에 메세지를 전달할 수 없는 경우, 메세지는 캔슬된다.

세션 기술로 플래그가 설정되어 있기 위해서(때문에), 보증 메세지의 전달의 차례가 확보되어 있지 않은 경우는, DPSEND_SIGNED 플래그와 DPSEND_ENCRYPTED 플래그를 사용할 수 없다.

다른 우선 순위를 사용해 메세지를 송신 하면, 서명과 암호화는 잘 되지 않는 경우가 있다. 어플리케이션에서는, 안전한 메세지를 위한 우선 순위 레벨을 1 개 결정해 그 레벨에서만 시큐러티 플래그를 사용해야 한다. 이것은, 안전한 메세지의 확인은 수신된 순서에 근거하고 있어, 우선 순위에 의해 이 순서가 변경될 가능성이 있기 때문이다.

DirectPlay 프로토콜이 액티브하다라고, 외부로 향한 네트워크 트래픽을 쓰로틀링 하려고 한다. 즉, 패킷을 항상 가능한 한 빠르게 송신하는 것은 아니다고 하는 것이다. DirectPlay 프로토콜은, 수신측의 컴퓨터의 내향의 대역폭에 영향을 주지 않는 범위에서, 가능한 한 고속으로 패킷을 송신한다.

시스템 메세지는, 서비스 프로바이더가 보증 메세지를 네이티브에 지원 하고 있을지 어떨지, 또는 DirectPlay 프로토콜의 플래그가 설정되어 있는지 어떤지에 관계없이, 항상 보증 첨부로 송신된다. 시스템 메세지를 보증 첨부로 송신하는 경우는, DirectPlay 프로토콜이 자동적으로 사용된다.

시스템 메세지 이외의 메세지의 경우, 어플리케이션이 DirectPlay 프로토콜의 플래그를 설정해, 메세지를 보증 첨부로 송신 하면 (DPSEND_GUARANTEED 플래그를 설정한다), 서비스 프로바이더가 보증 메세지를 지원 할지 어떨지에 관계없이, 메세지는 보증 첨부로 송신된다.

시스템 메세지 이외의 메세지의 경우, 어플리케이션이 DirectPlay 프로토콜의 플래그를 설정하지 않고, 메세지를 보증 첨부로 송신 하면, 서비스 프로바이더가 보증 메세지를 지원 하는 경우에 한정해, 메세지는 보증 첨부로 송신된다. 서비스 프로바이더가 보증 메세지를 지원 하지 않는 경우, DPSEND_GUARANTEED 플래그에 관계없이, 메세지는 보증 첨부에서는 송신되지 않는다.

참조

DirectPlay4.Send ,DirectPlay4.CancelMessage ,DirectPlay4.CancelPriority


DirectPlay4.SetGroupConnectionSettings

DirectPlay4.SetGroupConnectionSettings 메소드는,그룹에 의해 시작 되는세션의 접속 설정을 실시한다. 이 메소드는, 로비 세션에서만 사용할 수 있다.

object. SetGroupConnectionSettings(id As Long, _
    connection As DirectPlayLobbyConnection)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
id
접속 설정을 실시하는 그룹의 ID.
connection
기동하는 어플리케이션에 대한 기술, 사용하는서비스 프로바이더, 및 생성 하는 세션에 대한 기술에의 액세스를 제공하는,DirectPlayLobbyConnection 오브젝트.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS
DPERR_UNSUPPORTED

참조

DirectPlayLobby3.RunApplication


DirectPlay4.SetGroupData

DirectPlay4.SetGroupData 메소드는, 어플리케이션에 고유의 데이터를그룹 ID 에 관련짓는다. 그룹에 관련지을 수 있고 있는 리모트 데이터를 변경할 수 있는 것은, 그 그룹을 생성 한 컴퓨터 뿐이다.

object. SetGroupData(GroupId As Long, _
    data As String, _
    flags As CONST_DPSETFLAGS)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
GroupId
데이터를 설정하는 그룹 ID.
data
저장 하는 데이터. 기존의 데이터를 소거하는 경우는,"" 을 설정한다.
flags
그룹 데이터의 전승 방법을 지정하는,CONST_DPGETCAPSFLAGS 열거형의 플래그. 이 파라미터에 0 을 설정 하면, 보증 없음의 메시징에 의해 리모트 그룹 데이터가 설정되어 전승된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS

주의

DirectPlay 는, 로컬과 리모트의 2 종류의 그룹 데이터를 유지할 수 있다. 로컬 데이터는, 로컬 컴퓨터 위에의 어플리케이션만으로 이용할 수 있다. 리모트 데이터는, 세션내외의 모든 어플리케이션에 전승된다. 세션 기술에 DPSESSION_NODATAMESSAGES 가 설정되어 있는 경우를 제외해, 변경을 통지하기 위해서, 모든 플레이어 (송신한 플레이어를 포함한다)에게 DPSYS_SETPLAYERORGROUPDATA 시스템 메세지가 송신된다. 리소스에의 포인터를, 로컬 데이터에 안전하게 보존해 둘 수가 있다. 이 로컬 데이터 블록은, 그룹이 파기될 때 (DPSYS_DESTROYPLAYERORGROUP 시스템 메세지내에서) 이용할 수 있다. 그 때문에, 어플리케이션에서는, 이러한 리소스를 릴리즈 할 수가 있다.

이 메소드는, 오버헤드가 생기기 (위해)때문에, 리얼타임 정보의 갱신 (위치의 갱신등)을 위해서(때문에)는 사용해서는 안된다. 그러한 경우는,DirectPlay4.Send 가 현격히 효율적이다. 좀처럼 변경되지 않고, 시간이 중요하지 않는 공유 상태 정보 (팀의 특성등)에는,SetGroupData 가 적합하다.

참조

DirectPlay4.GetGroupData


DirectPlay4.SetGroupName

DirectPlay4.SetGroupName 메소드는,그룹이 생성 된 후에, 그 이름을 설정한다. 그룹의 이름을 설정할 수 있는 것은, 그 그룹을 생성 한 컴퓨터 뿐이다.

object. SetGroupName(GroupId As Long, _
    friendlyName As String, _
    formalName As String, _
    flags As CONST_DPSETFLAGS)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
GroupId
이름을 설정하는 그룹의 ID.
friendlyName
그룹의 쇼트 네임. 그룹이 프렌들리명을 가지지 않는 경우는,"" 을 설정한다.
formalName
그룹의 롱 네임. 그룹이 정식명을 가지지 않는 경우는,"" 을 설정한다.
flags
데이터 전승의 옵션을 설정하는,CONST_DPSETFLAGS 열거형의 플래그. 이 파라미터에 0 을 설정 하면, 이름은 보증 없음의 메시징을 사용해, 모든 리모트 시스템에 전승된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_CONNECTIONLOST
DPERR_INVALIDGROUP
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

주의

세션 기술로 DPSESSION_NODATAMESSAGES 가 설정되어 있는 경우를 제외해, 변경을 통지하기 위해서, 다른 모든 플레이어에게 DPSYS_SETPLAYERORGROUPNAME 시스템 메세지가 송신된다.

참조

DirectPlay4.GetGroupLongName ,DirectPlay4.GetGroupShortName ,DirectPlay4.Send


DirectPlay4.SetGroupOwner

DirectPlay4.SetGroupOwner 메소드는,그룹의 소유자를 변경한다. 이 메소드는, 로비 세션에서만 사용할 수 있다.

object. SetGroupOwner(GroupId As Long, _
    ownerId As Long)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
GroupId
소유자를 변경하는 그룹의 ID.
ownerId
그룹의 소유자로서 설정하는 플레이어의 ID.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_CONNECTIONLOST
DPERR_GENERIC
DPERR_INVALIDGROUP
DPERR_INVALIDPLAYER
DPERR_UNAVAILABLE

세션이 로비 세션이 아닌 경우는, DPERR_UNAVAILABLE 를 돌려준다.

참조

DirectPlay4.GetGroupOwner


DirectPlay4.SetPlayerData

DirectPlay4.SetPlayerData 메소드는, 어플리케이션에 고유의 데이터 블록을, 플레이어 ID 에 관련짓는다.

object. SetPlayerData(playerId As Long, _
    data As String, _
    flags As CONST_DPSETFLAGS)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
playerId
데이터를 설정하는 플레이어의 ID.
data
설정하는 데이터. 기존의 플레이어 데이터를 소거하는 경우는,"" 을 설정한다.
flags
데이터 전승의 옵션을 설정하는,CONST_DPSETFLAGS 열거형의 플래그. 이 파라미터에 0 (DPGET_REMOTE)을 설정 하면, 보증 없음의 메시징을 사용해, 리모트 플레이어의 데이터가 설정 및 전승된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_INVALIDPLAYER

주의

이 메소드는, 오버헤드가 생기기 (위해)때문에, 리얼타임 정보의 갱신 (위치의 갱신등)을 위해서(때문에)는 사용해서는 안된다. 그러한 경우는,DirectPlay4.Send 가 현격히 효율적이다. 좀처럼 변경되지 않고, 시간이 중요하지 않는 공유 상태 정보 (플레이어의 이름등)에는,SetPlayerData 가 적합하다.

DirectPlay 는, 로컬과 리모트의 2 종류의 그룹 데이터를 유지할 수 있다. 로컬 데이터는, 로컬 컴퓨터 위에의 어플리케이션만으로 이용할 수 있다. 리모트 데이터는, 세션내외의 모든 어플리케이션에 전승된다. 리모트 플레이어에 대해서 플레이어 데이터를 설정하려고 하면(자), DPERR_ACCESSDENIED 가 돌려주어진다. 세션 기술에 DPSESSION_NODATAMESSAGES 가 설정되어 있는 경우를 제외해, 변경을 통지하기 위해서, 모든 플레이어 (송신한 플레이어를 포함한다)에게 DPSYS_SETPLAYERORGROUPDATA 시스템 메세지가 송신된다. 리소스에의 포인터를, 로컬 데이터에 안전하게 보존해 둘 수가 있다. 이 로컬 데이터 블록은, 그룹이 파기될 때 (DPSYS_DESTROYPLAYERORGROUP 시스템 메세지내에서) 이용할 수 있다. 그 때문에, 어플리케이션에서는, 이러한 리소스를 릴리즈 할 수가 있다.

참조

DirectPlay4.GetPlayerData


DirectPlay4.SetPlayerName

DirectPlay4.SetPlayerName 메소드는, 로컬 플레이어의 정식명 및 프렌들리명을 변경한다. 이름을 변경할 수 있는 것은, 그 플레이어를 생성 한 컴퓨터 뿐이다.

object. SetPlayerName(playerId As Long, _
  friendlyName As String, _
  formalName As String, _
  flags As CONST_DPSETFLAGS)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
playerId
데이터를 송신하는 로컬 플레이어의 ID.
friendlyName
플레이어의 프렌들리 ("쇼트") 명.
formalName
플레이어의 정식 ("롱") 명.
flags
이름의 전승 방법을 나타내는,CONST_DPSETFLAGS 열거형의 플래그.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDOBJECT
DPERR_INVALIDPLAYER

주의

세션 기술에 DPSESSION_NODATAMESSAGES 가 설정되어 있는 경우를 제외해, 변경을 통지하기 위해서, 다른 모든 플레이어에게 DPSYS_SETPLAYERORGROUPNAME 시스템 메세지가 송신된다.

참조

DirectPlay4.GetPlayerFriendlyName ,DirectPlay4.GetPlayerFormalName


DirectPlay4.SetSessionDesc

DirectPlay4.SetSessionDesc 메소드는, 현재의세션의 프로퍼티를 변경한다. 세션의 프로퍼티를 변경할 수 있는 것은, 세션의호스트 뿐이다.

이 메소드는, 로비 세션에서는 사용할 수 없다.

object. SetSessionDesc(sessionDesc As DirectPlaySessionData)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
sessionDesc
새로운 설정을 포함한 DirectPlaySessionData 오브젝트. 이 오브젝트는,DirectPlay4.GetSessionDesc 메소드를 사용해 취득할 수 있다. 이 오브젝트 자체의 메소드를 사용해, 데이터를 변경할 수가 있다. 「주의」를 참조할것.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDPARAMS
DPERR_NOSESSIONS

이 컴퓨터가 세션을 변경하는 권한을 가지고 있지 않은 경우는, DPERR_ACCESSDENIED 를 돌려준다. 어플리케이션을 변경할 수 없는 세션 기술의 프로퍼티를 변경하려고 했을 경우나, 프로퍼티에 무효인 값을 설정하려고 했을 경우는, DPERR_INVALIDPARAMS 를 돌려준다.

주의

갱신된 세션 기술은, 세션내외의 모든 컴퓨터에 전승된다. 각 플레이어는,DPSYS_SETSESSIONDESC 시스템 메세지를 수신한다.

이하의 메소드를 사용해, 세션 기술의 변경 가능한 요소를 설정할 수가 있다.

DirectPlaySessionData.SetFlags
이하의 플래그를 추가 또는 삭제할 수 있다.

DPSESSION_JOINDISABLED
DPSESSION_NEWPLAYERSDISABLED
DPSESSION_NODATAMESSAGES
DPSESSION_PRIVATE

이하의 플래그를 유지할 필요가 있다. 그렇지 않은 경우,SetSessionDesc 를 호출했을 때에, 에러가 발생한다.
DPSESSION_NOMESSAGEID
DPSESSION_KEEPALIVE
DirectPlaySessionData.SetMaxPlayers
현재의 플레이어수보다 적은 최대 플레이어수가 설정되었을 경우는,DPERR_INVALIDPARAMS 를 돌려준다.
DirectPlaySessionData.SetSessionName
DirectPlaySessionData.SetSessionPassword
DirectPlaySessionData.SetUser1
DirectPlaySessionData.SetUser2
DirectPlaySessionData.SetUser3
DirectPlaySessionData.SetUser4

DirectPlaySessionData.SetGuidInstance 또는 DirectPlaySessionData.SetGuidApplication 를 호출해 오브젝트외의 프로퍼티를 변경했을 경우는, 새로운 설정은 무시된다. 즉, DirectPlay 는,DirectPlay4.Open 가 불려 갔을 때의 값을 항상 사용한다.

참조

DirectPlay4.GetSessionDesc


DirectPlay4.StartSession

DirectPlay4.StartSession 메소드는, staging 영역으로부터 DirectPlay 세션을 시작 한다. 최초로,SetGroupConnectionSettings 를 호출해, 기동하는 어플리케이션, 사용하는서비스 프로바이더, 및 사용하는 세션 기술을 지정한다.

object. StartSession(id As Long)

파라미터

object
DirectPlay4 오브젝트를 나타내는오브젝트식.
id
세션을 시작 하는 커멘드를 송신하는 그룹의 ID. 이 그룹은, staging 영역이 아니면 안된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_ACCESSDENIED
DPERR_CONNECTIONLOST
DPERR_INVALIDFLAGS
DPERR_INVALIDGROUP
DPERR_INVALIDPARAMS

지정된 그룹 ID 가 유효한 staging 영역이 아닌 경우는, DPERR_INVALIDGROUP 를 돌려준다.

주의

StartSession 를 호출하면,그룹내의 각 플레이어는, 세션을 시작 하도록(듯이) 지시하는 DPSYS_STARTSESSION 시스템 메세지를 수신한다.

세션이 이미 시작 되고 있는 staging 영역의 그룹에 참가하는 플레이어는, 이 메소드를 호출해 세션에 참가할 수가 있다. 플레이어는, 세션에 참가하는 방법에 관한 정보를 포함한 DPSYS_STARTSESSION 메세지를 받아들인다.

참조

동기 기동


DirectPlayAddress

DirectPlayAddress 클래스는, DirectPlay 가, 로비 서버, 어플리케이션, DirectPlay, 및서비스 프로바이더의 사이에 주소 정보를 건네주기 위해서(때문에) 사용하는 데이터 서식을 나타낸다. 개요에 대해서는, 「DirectPlay 주소」를 참조할것.

DirectPlayAddress 오브젝트는, 이하의 메소드에 의해 돌려주어진다.

  • DirectPlay4.GetPlayerAddress
  • DirectPlayEnumConnections.GetAddress
  • DirectPlayLobby3.CreateComPortAddress
  • DirectPlayLobby3.CreateCustomAddress
  • DirectPlayLobby3.CreateINetAddress
  • DirectPlayLobby3.CreateIPXAddress
  • DirectPlayLobby3.CreateLobbyProviderAddress
  • DirectPlayLobby3.CreateModemAddress
  • DirectPlayLobby3.CreateServiceProviderAddress
  • DirectPlayLobbyConnection.GetAddress

DirectPlayAddress 클래스 자체는, 퍼블릭 메소드를 가지지 않는다.

참조

DirectPlay4.InitializeConnection ,DirectPlayLobbyConnection.SetAddress


DirectPlayEnumConnections

DirectPlayEnumConnections 클래스는, 접속을 열거한다. 어플리케이션에서는,DirectPlayEnumConnections 클래스 오브젝트의 메소드를 사용해, 열거된 항목에 관한 정보를 취득할 수가 있다.

DirectPlayEnumConnections 오브젝트를 취득하려면 ,DirectPlay4.GetDPEnumConnections 메소드를 사용한다.

DirectPlayEnumConnections 클래스에는, 이하의 메소드가 있다.

열거 | GetAddress
 | GetCount
 | GetFlags
 | GetGuid
 | GetName


DirectPlayEnumConnections.GetAddress

DirectPlayEnumConnections.GetAddress 메소드는, 열거형으로부터 주소 오브젝트를 취득한다

object. GetAddress(index As Long) As DirectPlayAddress

파라미터

object
DirectPlayEnumConnections 오브젝트를 나타내는오브젝트식.
index
데이터를 취득하는 열거형 오브젝트의 요소.

반환값

DirectPlayAddress 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayEnumConnections.GetCount

DirectPlayEnumConnections.GetCount 메소드는, 열거형 오브젝트의 요소의 수를 취득한다.

object. GetCount() As Long

파라미터

object
DirectPlayEnumConnections 오브젝트를 나타내는오브젝트식.

반환값

열거형 오브젝트의 요소의 수를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayEnumConnections.GetFlags

DirectPlayEnumConnections.GetFlags 메소드는, 열거된 접속에 대한 플래그를 취득한다.

object. GetFlags(index As Long) As Long

파라미터

object
DirectPlayEnumConnections 오브젝트를 나타내는오브젝트식.
index
데이터를 취득하는 열거형 오브젝트의 요소.

반환값

접속에 대한 플래그를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

반환값은,DirectPlay4.GetDPEnumConnections 에게 건네지는 플래그에 동일하다.


DirectPlayEnumConnections.GetGuid

DirectPlayEnumConnections.GetGuid 메소드는, 열거된 접속에 대한 글로벌 유니크 식별자 (GUID)를 돌려준다.

object. GetGuid(index As Long) as String

파라미터

object
DirectPlayEnumConnections 오브젝트를 나타내는오브젝트식.
index
데이터를 취득하는 열거형 오브젝트의 요소.

반환값

접속의 GUID 를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

GUID 의 사용


DirectPlayEnumConnections.GetName

DirectPlayEnumConnections.GetName 메소드는, 열거형으로부터 이름 오브젝트를 취득한다.

object. GetName(index As Long) As String

파라미터

object
DirectPlayEnumConnections 오브젝트를 나타내는오브젝트식.
index
데이터를 취득하는 열거형의 요소.

반환값

접속의 이름 (예를 들어,"IPX Connection for DirectPlay")을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayEnumLocalApplications

DirectPlayEnumLocalApplications 클래스는, 로컬 어플리케이션을 열거한다. 어플리케이션은,DirectPlayEnumLocalApplications 클래스의 메소드를 사용해, 열거된 항목에 관한 정보를 취득한다.

DirectPlayEnumLocalApplications 오브젝트는,DirectPlayLobby3.GetDPEnumLocalApplications 메소드에 의해 돌려주어진다.

DirectPlayEnumLocalApplications 클래스에는, 이하의 메소드가 있다.

열거 | GetCount
 | GetGuid
 | GetName


DirectPlayEnumLocalApplications.GetCount

DirectPlayEnumLocalApplications.GetCount 메소드는, 열거형 오브젝트의 엔트리의 수를 돌려준다.

object. GetCount() As Long

파라미터

object
DirectPlayEnumLocalApplications 오브젝트를 나타내는오브젝트식.

반환값

열거형 오브젝트의 엔트리의 수를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayEnumLocalApplications.GetGuid

DirectPlayEnumLocalApplications.GetGuid 메소드는, 열거된 어플리케이션의 글로벌 유니크 식별자 (GUID)를 취득한다.

object. GetItem(index As Long) as String

파라미터

object
DirectPlayEnumLocalApplications 오브젝트를 나타내는오브젝트식.
index
데이터를 취득하는 열거형 오브젝트의 요소.

반환값

어플리케이션의 GUID 를 나타내는 캐릭터 라인을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

GUID 의 사용


DirectPlayEnumLocalApplications.GetName

DirectPlayEnumLocalApplications.GetName 메소드는, 열거된 어플리케이션의 이름을 돌려준다.

object. GetItem(index As Long) as String

파라미터

object
DirectPlayEnumLocalApplications 오브젝트를 나타내는오브젝트식.
index
데이터를 취득하는 열거형 오브젝트의 요소.

반환값

어플리케이션의 이름을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayEnumPlayers

DirectPlayEnumPlayers 클래스는, 세션 또는 그룹내의 플레이어 또는 그룹을 열거한다. 어플리케이션은,DirectPlayEnumPlayers 클래스의 메소드를 사용해, 열거된 플레이어 또는 그룹에 관한 정보를 취득한다.

DirectPlayEnumPlayers 오브젝트는, 이하의 메소드에 의해 돌려주어진다.

  • DirectPlay4.GetDPEnumGroups
  • DirectPlay4.GetDPEnumGroupsInGroup
  • DirectPlay4.GetDPEnumGroupPlayers
  • DirectPlay4.GetDPEnumPlayers

DirectPlayEnumPlayers 클래스에는, 이하의 메소드가 있다.

열거 | GetCount
 | GetDPID
 | GetFlags
 | GetLongName
 | GetShortName
 | GetType


DirectPlayEnumPlayers.GetCount

DirectPlayEnumPlayers.GetCount 메소드는, 열거형 오브젝트의 엔트리의 수를 취득한다.

object. GetCount() As Long

파라미터

object
DirectPlayEnumPlayers 오브젝트를 나타내는오브젝트식.

반환값

열거형 오브젝트내의 엔트리의 수를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayEnumPlayers.GetDPID

DirectPlayEnumPlayers.GetDPID 메소드는, 열거된 플레이어 또는 그룹의 수치의 식별자를 돌려준다.

object. GetDPID(index As Long) As Long

파라미터

object
DirectPlayEnumPlayers 오브젝트를 나타내는오브젝트식.
index
데이터를 취득하는 열거형 오브젝트의 요소.

반환값

플레이어 또는 그룹이 생성 되었을 때에 할당할 수 있었던 일의의 식별자를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayEnumPlayers.GetFlags

DirectPlayEnumPlayers.GetFlags 메소드는, 열거된 플레이어 또는 그룹에 관한 다양한 정보를 취득한다.

object. GetFlags(index As Long) As Long

파라미터

object
DirectPlayEnumPlayers 오브젝트를 나타내는오브젝트식.
index
데이터를 취득하는 열거형 오브젝트의 요소.

반환값

플레이어에 대한 플래그를 돌려준다. 이것에는, 열거형을 생성 한 메소드에게 건네진 플래그가 포함된다. 이것들은, 특정의 플레이어 또는 그룹에 관한 추가 정보와 조합할 수 있고 있다.

DIRECTPLAYENUMGROUPS_ALL
이 세션내의 모든 그룹.
DIRECTPLAYENUMGROUPS_LOCAL
이 DirectPlay 오브젝트에 의해 로컬에 생성 된 그룹.
DIRECTPLAYENUMGROUPS_REMOTE
리모트의 DirectPlay 오브젝트에 의해 생성 된 그룹.
DIRECTPLAYENUMGROUPS_SESSION
지정된 세션에 대한 그룹
DIRECTPLAYENUMGROUPS_SHORTCUT
DirectPlay4.AddGroupToGroup 에 의해 그룹에 추가된 그룹 (쇼트 컷은, 다른 그룹에의 링크이다).
DIRECTPLAYENUMGROUPS_STAGINGAREA
staging 영역인, 그룹내의 그룹 (staging 영역은, 새로운 세션을 기동할 때에, 플레이어를 배치하기 위해서 사용된다).
DIRECTPLAYENUMPLAYERS_LOCAL
이 DirectPlay 오브젝트에 의해 로컬에 생성 된 플레이어.
DIRECTPLAYENUMPLAYERS_OWNER
이 그룹의 소유자인 플레이어.
DIRECTPLAYENUMPLAYERS_REMOTE
리모트의 DirectPlay 오브젝트에 의해 생성 된 플레이어.
DIRECTPLAYENUMPLAYERS_SERVERPLAYER
서버 플레이어.
DIRECTPLAYENUMPLAYERS_SESSION
지정된 세션에 대한 플레이어. 이 플래그는, 현재 열려 있는 세션이 존재하지 않는 경우에게만 사용할 수 있다. 로비 세션에서는 사용할 수 없다.
DIRECTPLAYENUMPLAYERS_SPECTATOR
관객인 플레이어.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectPlay4.GetDPEnumGroups ,DirectPlay4.GetDPEnumGroupsInGroup ,DirectPlay4.GetDPEnumPlayers ,DirectPlay4.GetDPEnumGroupPlayers


DirectPlayEnumPlayers.GetLongName

DirectPlayEnumPlayers.GetLongName 메소드는, 플레이어 또는 그룹의 정식명을 취득한다.

object. GetLongName(index As Long) As String

파라미터

object
DirectPlayEnumPlayers 오브젝트를 나타내는오브젝트식.
index
데이터를 취득하는 열거형 오브젝트의 요소.

반환값

플레이어 또는 그룹이 생성 되었을 때에 할당할 수 있었던 정식명 또는 핸들을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayEnumPlayers.GetShortName

DirectPlayEnumPlayers.GetShortName 메소드는, 플레이어 또는 그룹의 프렌들리명을 취득한다.

object. GetShortName(index As Long) As String

파라미터

object
DirectPlayEnumPlayers 오브젝트를 나타내는오브젝트식.
index
데이터를 취득하는 열거형 오브젝트의 요소.

반환값

플레이어 또는 그룹이 생성 되었을 때에 할당할 수 있었던 쇼트 네임 또는 프렌들리명을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayEnumPlayers.GetType

DirectPlayEnumPlayers.GetType 메소드는, 열거된 항목이 플레이어 또는 그룹의 어디에서 있는지를 확인한다.

object. GetType(index As Long) As Long

파라미터

object
DirectPlayEnumPlayers 오브젝트를 나타내는오브젝트식.
index
데이터를 취득하는 열거형 오브젝트의 요소.

반환값

열거된 항목의 타입 (DPPLAYERTYPE_GROUP 또는 DPPLAYERTYPE_PLAYER)을,CONST_DPPLAYERTYPEFLAGS 열거형으로부터 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayEnumSessions

DirectPlayEnumSessions 클래스는, 특정의 어플리케이션에 대한 액티브 세션 또는 특정의 어플리케이션에 서비스를 제공하는 모든 액티브 로비 세션을 열거한다.

DirectPlayEnumSessions 오브젝트를 취득하려면 ,DirectPlay4.GetDPEnumSessions 메소드를 사용한다.

이 클래스에는, 이하의 메소드가 있다.

열거 | GetCount
 | GetItem


DirectPlayEnumSessions.GetCount

DirectPlayEnumSessions 메소드는, 열거형 오브젝트의 엔트리의 수를 돌려준다.

object. GetCount() As Long

파라미터

object
DirectPlayEnumSessions 오브젝트를 나타내는오브젝트식.

반환값

열거형 오브젝트의 엔트리의 수를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayEnumSessions.GetItem

DirectPlayEnumSessions.GetItem 메소드는, 열거된 세션에 대한 데이터를 나타내는 DirectPlaySessionData 오브젝트를 취득한다.

object. GetItem(index As Long) As DirectPlaySessionData

파라미터

object
DirectPlayEnumSessions 오브젝트를 나타내는오브젝트식.
index
데이터를 취득하는 열거형 오브젝트의 요소.

반환값

성공하면,DirectPlaySessionData 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayLobby3

어플리케이션은,DirectPlayLobby3 클래스의 메소드를 사용해, 어플리케이션과 거기에 관련하는 데이터를 관리한다.

DirectPlayLobby3 오브젝트를 취득하려면 ,DirectX7.DirectPlayLobbyCreate 메소드를 사용한다.

DirectPlayLobby3 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

주소 | CreateComPortAddress
 | CreateCustomAddress
 | CreateInetAddress
 | CreateIPXAddress
 | CreateLobbyProviderAddress
 | CreateModemAddress
 | CreateServiceProviderAddress
 | GetModemCount
 | GetModemName
어플리케이션 | Connect
 | GetDPEnumLocalApplications
 | RegisterApplication
 | RunApplication
 | UnregisterApplication
 | WaitForConnectionSettings
메세지 | CreateMessage
 | ReceiveLobbyMessage
 | SendLobbyMessage
 | SetLobbyMessageEvent
접속 | CreateConnectionData
 | GetConnectionSettings
 | SetConnectionSettings


DirectPlayLobby3.Connect

DirectPlayLobby3.Connect 메소드는, 현재 DirectPlayLobby3 오브젝트와 함께 저장 되고 있는 DirectPlayLobbyConnection 오브젝트에 의해 지정되는세션에, 어플리케이션을 접속한다.

object. Connect(flags As Long) As DirectPlay4

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.
flags
접속의 방법을 나타내는,CONST_DPCONNECTFLAGS 열거형의 멤버. 디폴트 (flags = 0 또는 DPCONNECTION_DEFAULT)에서는, 접속이 확립되는지, 또는 조작이 타임 아웃이 되고 나서, 메소드가 돌아온다. 이 플래그가 DPCONNECTION_RETURNSTATUS 의 경우, 메소드는 접속 상태와 함께 즉시 돌아온다.

반환값

성공하면,DirectPlay4 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_CONNECTING
DPERR_INVALIDFLAGS
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOTLOBBIED
DPERR_OUTOFMEMORY

주의

디폴트에서는,Connect 는 접속이 확립되는지, 또는 접속이 타임 아웃이 된 다음에 돌아온다. DPCONNECT_RETURNSTATUS 플래그를 사용 하면,Connect 는, 접속이 진행중인 것을 나타내는 DPERR_CONNECTING 에러 코드와 함께 즉시 돌아온다. 어플리케이션은, 메소드가 성공하는지, 또는 다른 실패 코드가 돌려주어질 때까지, 이 메소드를 반복해 호출할 필요가 있다. 접속을 캔슬하려면 ,DirectPlayLobby3 오브젝트를 릴리즈 한다.

접속의 타임 아웃의 상한은, 1 분이다.

이 메소드가 적절히 완료 하면, 어플리케이션은 DirectPlay4.InitializeConnection ,DirectPlay4.GetDPEnumSessions , 및 DirectPlay4.Open 를 호출하는 순서를 생략 할 수가 있다. 어플리케이션에서는, 유저에게 이름을 물어서는 안된다. 대신에,DirectPlayLobbyConnection 인터페이스로 플레이어명을 사용해 플레이어를 생성 해야 한다.

어플리케이션에서는, 이 메소드를 호출하기 전에,DirectPlayLobby3.GetConnectionSettings 메소드를 사용해, 어플리케이션을 기동하기 위해서 사용되는 접속 설정을 조사할 수가 있다. DirectPlayLobby3.SetConnectionSettings 메소드를 사용 하면, 이러한 설정을 수정 및 설정할 수가 있다. DirectPlaySessionData 오브젝트에는 특별히 주위를 기울여, 세션의 적절한 프로퍼티가 설정되도록(듯이) 할 필요가 있다.


DirectPlayLobby3.CreateComPortAddress

DirectPlayLobby3.CreateComPortAddress 메소드는, COM 포트에 대한 DirectPlay 주소를 생성 한다.

object. CreateComPortAddress(port As Long, _
    baudRate As Long, _
    stopBits As Long, _
    parity As Long, _
    flowcontrol As Long) As DirectPlayAddress

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.
port
사용하는 COM 포트의 번호. 1, 2, 3, 4 의 어느쪽이든을 설정할 수 있다.
baudRate
포트의 baud rate. 이하의 몇개의 값을 설정할 수 있다.
110 | 300 | 600
1200 | 2400 | 4800
9600 | 14400 | 19200
38400 | 56000 | 57600
115200 | 128000 | 256000

stopBits
stop bit의 번호. 0 (stop bit 없음), 1 (1.5 stop bit), 2 (2 stop bit)의 어느쪽이든을 설정할 수 있다.
parity
패리티. 이하의 몇개의 값을 설정할 수 있다.
0 | 패리티 없음
1 | 홀수 패리티
2 | 짝수 패리티
3 | 마크 패리티

flowcontrol
flow control의 방법. 이하의 몇개의 값을 설정할 수 있다.
0 | flow control 없음
1 | 소프트웨어 플로우 콘트롤 (xon/xoff)
2 | RTS 를 사용한 하드웨어 플로우 콘트롤
3 | DTR 를 사용한 하드웨어 플로우 콘트롤
4 | RTS 와 DTR 를 사용한 하드웨어 플로우 콘트롤

반환값

성공하면,DirectPlayAddress 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 값이 설정된다.

DPERR_INVALIDPARAMS


DirectPlayLobby3.CreateConnectionData

DirectPlayLobby3.CreateConnectionData 메소드는, 접속 설정을 실시하기 위해서(때문에) 사용할 수 있는 오브젝트를 생성 한다.

object. CreateConnectionData() As DirectPlayLobbyConnection

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectPlayLobbyConnection 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectPlayLobby3.SetConnectionSettings


DirectPlayLobby3.CreateCustomAddress

DirectPlayLobby3.CreateCustomAddress 메소드는, 다른 주소 생성 메소드로 지원되어 있지 않은 종류의 DirectPlay 주소를 생성 한다.

object. CreateCustomAddress(size As Long, _
    data As Any) As DirectPlayAddress

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.
size
데이터의 사이즈.
data
주소에 짜넣어지는 데이터.

반환값

성공하면,DirectPlayAddress 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 값이 설정된다.

DPERR_INVALIDPARAMS


DirectPlayLobby3.CreateINetAddress

DirectPlayLobby3.CreateINetAddress 메소드는, 인터넷 주소에 대한 DirectPlay 주소를 생성 한다.

object. CreateINetAddress(addr As String, _
    port As Long) As DirectPlayAddress

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.
addr
IP 주소 ("192.168. 0.1" 등) 또는 도메인명 ("microsoft.com" 등).
port
접속에 사용하는 포트. 디폴트의 포트를 지정하려면 , 0 을 설정한다. 상세한 것에 대하여는, 「TCP/IP 」를 참조할것.

반환값

성공하면,DirectPlayAddress 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 값이 설정된다.

DPERR_INVALIDPARAMS


DirectPlayLobby3.CreateIPXAddress

DirectPlayLobby3.CreateIPXAddress 메소드는, IPX 서비스 프로바이더에 대한 DirectPlay 주소를 생성 한다.

object. CreateIPXAddress() As DirectPlayAddress

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectPlayAddress 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectPlayLobby3.CreateServiceProviderAddress


DirectPlayLobby3.CreateLobbyProviderAddress

DirectPlayLobby3.CreateLobbyProviderAddress 메소드는, 로비 프로바이더에 대한 DirectPlay 주소를 생성 한다.

object. CreateLobbyProviderAddress( _
    guid As String) As DirectPlayAddress

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.
guid
로비 프로바이더에 대한 일의의 식별자.

반환값

성공하면,DirectPlayAddress 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 값이 설정된다.

DPERR_INVALIDPARAMS


DirectPlayLobby3.CreateMessage

DirectPlayLobby3.CreateMessage 메소드는, 로비 메세지를 생성 한다.

object. CreateMessage() As DirectPlayMessage

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectPlayMessage 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayLobby3.CreateModemAddress

DirectPlayLobby3.CreateModemAddress 메소드는, 모뎀에 대한 DirectPlay 주소를 생성 한다.

object. CreateModemAddress( _
    modem As String, _
    phone as String) As DirectPlayAddress

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.
modem
모뎀의 이름. 이용 가능한 모뎀의 이름을 취득하려면 ,DirectPlayLobby3.GetModemName 메소드를 사용한다. 디폴트의 모뎀을 지정하려면 , 하늘의 캐릭터 라인을 사용한다.
phone
다이얼 하는 전화번호.

반환값

성공하면,DirectPlayAddress 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 값이 설정된다.

DPERR_INVALIDPARAMS


DirectPlayLobby3.CreateServiceProviderAddress

DirectPlayLobby3.CreateServiceProviderAddress 메소드는, 서비스 프로바이더에 대한 DirectPlay 주소를 생성 한다.

object. CreateServiceProviderAddress( _
    guid as String) As DirectPlayAddress

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.
guid
서비스 프로바이더의 일의의 식별자.

반환값

성공하면,DirectPlayAddress 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 값이 설정된다.

DPERR_INVALIDPARAMS

참조

DirectPlayLobby3.CreateIPXAddress


DirectPlayLobby3.GetConnectionSettings

DirectPlayLobby3.GetConnectionSettings 메소드는, 어플리케이션을 시작 및 접속하기 위해서 필요한 정보를 모두 포함한 DirectPlayLobbyConnection 오브젝트를 취득한다. 돌려주어지는 정보는,로비 클라이언트에 의해 DirectPlayLobby3.RunApplication 메소드에게 건네진 데이터, 또는 DirectPlayLobby3.SetConnectionSettings 메소드의 호출에 의해 설정된 데이터와 같다.

object. GetConnectionSettings(applicationId As Long) _
    As DirectPlayLobbyConnection

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.
applicationId
(복수의 어플리케이션과 통신한다) 로비 클라이언트로부터 불려 가는 경우는, 어느 어플리케이션의 접속 설정을 취득하는지를 지정한다. 이 ID 번호는,DirectPlayLobby3.RunApplication 로부터 취득된다. (1 살의 로비 클라이언트와 통신하고 있다) 어플리케이션으로부터 불려 가는 경우는, 이 파라미터는 0 이다.

반환값

성공하면,DirectPlayLobbyConnection 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_BUFFERTOOSMALL
DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_NOTLOBBIED
DPERR_OUTOFMEMORY

참조

DirectPlayLobby3.WaitForConnectionSettings


DirectPlayLobby3.GetDPEnumLocalApplications

DirectPlayLobby3.GetDPEnumLocalApplications 메소드는, DirectPlay 에 의해 등록된 어플리케이션을 열거한다.

object. GetDPEnumLocalApplications() _
    As DirectPlayEnumLocalApplications

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.

반환값

성공하면,DirectPlayEnumLocalApplications 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_GENERIC
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY


DirectPlayLobby3.GetModemCount

DirectPlayLobby3.GetModemCount 메소드는, 플레이어의 시스템상에서 이용 가능한 모뎀의 수를 취득한다.

object. GetModemCount() As Long

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.

반환값

성공하면, 이용 가능한 모뎀의 수를 돌려준다. 이러한 모뎀의 이름은,DirectPlayLobby3.GetModemName 메소드를 사용해 취득할 수가 있다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayLobby3.GetModemName

DirectPlayLobby3.GetModemName 메소드는, 플레이어의 시스템상에서 이용 가능한 모뎀의 이름을 취득한다.

object. GetModemName(index As Long) As String

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.
index
이용 가능한 모뎀의 리스트의 인덱스. 값은, 1 으로부터 DirectPlayLobby3.GetModemCount 까지의 범위가 아니면 안된다.

반환값

성공하면, 모뎀의 이름을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectPlayLobby3.CreateModemAddress


DirectPlayLobby3.ReceiveLobbyMessage

DirectPlayLobby3.ReceiveLobbyMessage 메소드는,로비 클라이언트 어플리케이션과 DirectPlay 어플리케이션의 사이에 송신되는 메세지를 취득한다. 메세지는 큐에 넣어지므로, 시간내에 읽을 수 없어도, 데이터를 잃는 위험은 없다.

object. ReceiveLobbyMessage(applicationId As Long, _
    messageFlags As Long) As DirectPlayMessage

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.
applicationId
메세지를 수신하는 어플리케이션의 식별자. (복수의 어플리케이션과 통신한다) 로비 클라이언트로부터 불려 가는 경우, 이 ID 번호는,DirectPlayLobby3.RunApplication 메소드에 의해 취득되지만 어느 쪽인가에 된다. (1 살의 로비 클라이언트만과 통신한다) 어플리케이션으로부터 불려 가는 경우, 이 파라미터에는 0 을 설정할 필요가 있다.
messageFlags
돌려주어지는 메세지의 타입을 나타내는,CONST_DPLMSG 열거형의 플래그. 디폴트 (messageFlags = 0 또는 DPLMSG_USERDEFINED)는, 메세지가 송신 측에야는 독자적으로 정의된 것인 것을 나타낸다. 이런 종류의 메세지의 처리는 옵션이다. 수신측은, 이 메세지를, 송신측의 어플리케이션의 신원에 응해 해석할 필요가 있다. 로비는, 기동된 어플리케이션의 GUID 에 응해, 송신측의 어플리케이션을 식별할 수가 있다. 어플리케이션은, 식별용의 GUID 를 요구하는 표준의 메세지를 송신하는 것으로써, 로비를 식별할 필요가 있다.

반환값

성공하면,DirectPlayMessage 오브젝트를 돌려준다. 이 오브젝트의 메소드를 사용해, 메세지의 데이타를 뽑기 시작할 수가 있다. 보류중의 메세지가 존재하지 않는 경우는, Nothing 를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_APPNOTSTARTED
DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY

참조

DirectPlayLobby3.SendLobbyMessage


DirectPlayLobby3.RegisterApplication

DirectPlayLobby3.RegisterApplication 메소드는, DirectPlay 에 로비 대응 어플리케이션을 등록한다. DirectPlay 로비로부터 어플리케이션을 기동할 수 있도록(듯이) 하려면 , 그 어플리케이션을 등록할 필요가 있다.

어플리케이션은 1 회만 등록하면 좋다. 언인스톨시에는, 어플리케이션의 등록을 해제할 필요가 있다.

object. RegisterApplication( _
    ApplicationInfo As DPAPPLICATIONDESC2)

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.
ApplicationInfo
등록하는 어플리케이션을 기술하는 DPAPPLICATIONDESC2 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS .

참조

DirectPlayLobby3.UnregisterApplication


DirectPlayLobby3.RunApplication

DirectPlayLobby3.RunApplication 메소드는, 어플리케이션을 시작 해, 그 어플리케이션을 세션에 접속하기 위해서 필요한 정보를 모두 건네준다. 이 메소드는,로비 클라이언트에 의해 사용된다.

object. RunApplication( _
    connection As DirectPlayLobbyConnection, _
    receiveEvent As Long) As Long

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.
connection
유저에게 다이알로그 박스를 표시하지 않고 , 시작 하는 어플리케이션과세션의 인스턴스에 접속하는 방법을 지정하기 위해서 필요한 정보를 모두 포함한,DirectPlayLobbyConnection 인터페이스.
receiveEvent
로비 메세지를 수신했을 때에 설정되는 동기 이벤트에의 핸들. 이 이벤트는, 다음에 DirectPlayLobby3.SetLobbyMessageEvent 메소드를 사용해 변경할 수가 있다.

반환값

시작 된 어플리케이션의 ID 를 돌려준다. 로비 클라이언트는, 이 어플리케이션 ID 를 보존해,DirectPlayLobby3.SendLobbyMessage 메소드 및 DirectPlayLobby3.ReceiveLobbyMessage 메소드의 호출로 사용할 수 있도록(듯이) 할 필요가 있다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_CANTCREATEPROCESS
DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY
DPERR_UNKNOWNAPPLICATION

주의

이 메소드는, 어플리케이션 프로세스가 생성 된 후에 돌아온다. 로비 클라이언트는, 어플리케이션 상태를 나타내는 시스템 메세지를 수신한다. 로비 클라이언트가 세션을 호스트 하는 어플리케이션을 기동하고 있는 경우는,DPLSYS_DPLAYCONNECTSUCCEEDED 시스템 메세지를 수신하고 나서, 그 세션에 참가하는 것 외의 어플리케이션을 기동할 필요가 있다. 어플리케이션이 세션을 생성 또는 참가할 수 없었던 경우는,DPLSYS_DPLAYCONNECTFAILED 메세지가 생성된다. 또, 로비 클라이언트는, 어플리케이션이 접속 설정을 읽어냈을 때에 DPLSYS_CONNECTIONSETTINGSREAD 시스템 메세지를 수신해, 어플리케이션이 종료했을 때에 DPLSYS_APPTERMINATED 시스템 메세지를 수신한다.

로비 클라이언트는, DPLSYS_CONNECTIONSETTINGSREAD 시스템 메세지를 수신할 때까지,DirectPlayLobby3 오브젝트를 릴리즈 하지 않는 것이 중요하다. 로비 클라이언트는,ReceiveLobbyMessage 메세지를 수신할 때까지 루프로 확인하는지, 또는 동기 이벤트를 제공할 수가 있다.

참조

DirectPlayLobby3.GetConnectionSettings ,DirectX7.CreateEvent


DirectPlayLobby3.SendLobbyMessage

DirectPlayLobby3.SendLobbyMessage 메세지는, 어플리케이션과로비 클라이언트의 사이에 메세지를 송신한다.

object. SendLobbyMessage(flags As CONST_DPLMSG, _
    applicationId As Long, _
    msg As DirectPlayMessage)

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.
flags
송신하는 메세지의 타입을 나타내는,CONST_DPLMSG 열거형의 플래그. 디폴트 (flags = 0 또는 DPLMSG_USERDEFINED)는, 송신하는 어플리케이션에 의해 정의되는 커스텀 메세지이다. 그 밖에는, DirectPlay 로 정의되는 표준 메세지를 나타내는 DPLMSG_STANDARD 를 지정할 수 있다.
applicationId
(복수의 어플리케이션과 통신한다) 로비 클라이언트로부터 불려 가는 경우는, 메세지를 송신하는 어플리케이션을 지정한다. (1 살의 로비 클라이언트라는 보고 통신한다) 어플리케이션으로부터 불려 가는 경우는, 이 파라미터는 0 이 아니면 안된다. 이 ID 를 취득하려면 ,DirectPlayLobby3.RunApplication 메소드를 사용한다.
msg
송신하는 메세지를 나타내는 DirectPlayMessage 오브젝트. 이 오브젝트를 취득하려면 ,DirectPlayLobby3.CreateMessage 메소드를 사용한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_APPNOTSTARTED
DPERR_BUFFERTOOLARGE
DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY
DPERR_TIMEOUT

참조

DirectPlayLobby3.ReceiveLobbyMessage


DirectPlayLobby3.SetConnectionSettings

DirectPlayLobby3.SetConnectionSettings 메소드는, 어플리케이션을 기동 및 접속하기 위해서 필요한 정보를 변경한다.

object. SetConnectionSettings(applicationId As Long, _
    connection As DirectPlayLobbyConnection)

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.
applicationId
(복수의 어플리케이션과 통신한다) 로비 클라이언트로부터 불려 가는 경우는, 접속 설정을 실시하는 어플리케이션을 식별한다. 이 ID 를 취득하려면 ,DirectPlayLobby3.RunApplication 메소드를 사용한다. (1 살의 로비 클라이언트만과 통신한다) 어플리케이션으로부터 불려 가는 경우는, 0 이 아니면 안된다.
connection
유저에게 다이알로그 박스를 표시하지 않고 , 시작 하는 어플리케이션과세션의 인스턴스에 접속하는 방법을 지정하기 위해서 필요한 정보를 모두 포함한,DirectPlayLobbyConnection 오브젝트.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY

참조

DirectPlayLobby3.GetConnectionSettings


DirectPlayLobby3.SetLobbyMessageEvent

DirectPlayLobby3.SetLobbyMessageEvent 메소드는, 로비 메세지를 수신했을 때에 설정되는 이벤트를 등록한다. 어플리케이션에서는, 메세지와의 동기가 필요한 경우는, 이 메소드를 호출할 필요가 있다. 로비 클라이언트는, 이 메소드를 호출해,DirectPlayLobby3.RunApplication 메소드의 호출로 지정된 이벤트를 변경할 수가 있다.

object. SetLobbyMessageEvent(applicationId As Long, _
    receiveEvent As Long)

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.
applicationId
(복수의 어플리케이션과 통신한다) 로비 클라이언트로부터 불려 가는 경우는, 이벤트를 관련짓는 어플리케이션을 식별한다. 이 ID 번호는,RunApplication 로부터 취득한다. (1 살의 로비 클라이언트만과 통신한다) 어플리케이션으로부터 불려 가는 경우는, 0 이 아니면 안된다.
receiveEvent
메세지를 수신했을 때에 설정되는 이벤트에의 핸들.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_GENERIC
DPERR_INVALIDINTERFACE
DPERR_INVALIDOBJECT
DPERR_INVALIDPARAMS
DPERR_OUTOFMEMORY

참조

DirectPlayLobby3.ReceiveLobbyMessage ,DirectPlayLobby3.SendLobbyMessage ,DirectX7.CreateEvent


DirectPlayLobby3.UnregisterApplication

DirectPlayLobby3.UnregisterApplication 메소드는, DirectPlay 어플리케이션의 레지스트리 엔트리를 삭제한다.

object. UnregisterApplication(GuidApplication As String)

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.
GuidApplication
레지스트리로부터 삭제하는 어플리케이션의 글로벌 유니크 식별자 (GUID).

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_INVALIDFLAGS
DPERR_INVALIDPARAMS
DPERR_UNKNOWNAPPLICATION

어플리케이션의 GUID 가 레지스트리로 발견되지 않았던 경우는, DPERR_UNKNOWNAPPLICATION 를 돌려준다.

참조

DirectPlayLobby3.RegisterApplication ,DPAPPLICATIONDESC2


DirectPlayLobby3.WaitForConnectionSettings

DirectPlayLobby3.WaitForConnectionSettings 메소드는, 어플리케이션을 대기 모드로 설정한다. 대기 모드에서는, 접속 설정을 대기한다. 어플리케이션이 대기 모드로 설정되어 있는 경우, aDirectPlayLobby3.RunApplication 메소드를 사용하는로비 클라이언트는, 어플리케이션의 새로운 인스턴스를 기동하지 않고, 이미 대기 모드로 실행되고 있는 어플리케이션에 접속 설정을 직접 송신한다.

어플리케이션은,DirectPlayLobby3.Connect 메소드를 사용해 세션에 접속할 수가 있다.

object. WaitForConnectionSettings(flags As CONST_DPLWAIT)

파라미터

object
DirectPlayLobby3 오브젝트를 나타내는오브젝트식.
flags
어플리케이션을 대기 모드로 설정하는지, 또는 대기 모드로부터 해제하는,CONST_DPLWAIT 열거형의 플래그. 디폴트 (flags = DPLWAIT_DEFAULT 또는 0)에서는, 어플리케이션을 대기 모드로 설정한다. DPLWAIT_CANCEL 를 설정 하면, 어플리케이션을 대기 모드로부터 해제한다. 로비 클라이언트로부터 접속 설정이 송신되면(자), 어플리케이션은 즉시 대기 모드로부터 자동적으로 해제된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 값이 설정된다.

DPERR_INVALIDFLAGS
DPERR_UNAVAILABLE

어플리케이션이 대기 모드로 설정되어 있지 않은 경우에, 대기 모드를 캔슬하는 플래그를 설정했을 경우는, DPERR_UNAVAILABLE 를 돌려준다.

로비 클라이언트가 RunApplication 를 사용 하면, DirectPlay 는, 접속 설정을 대기하고 있는 어플리케이션의 인스턴스를 검색한다. 그것이 발견되지 않는 경우는, 어플리케이션의 새로운 인스턴스를 기동한다. 대기중의 어플리케이션이 발견되었을 경우는,DirectPlayLobby3.GetConnectionSettings 메소드를 사용해 접속 설정을 읽기,Connect 를 사용해 세션에 접속한다.


DirectPlayLobbyConnection

DirectPlayLobbyConnection 클래스는, 어플리케이션을세션에 접속하기 위해서 필요한 정보에 액세스 하는 메소드를 제공한다. 이 클래스의 오브젝트는,DirectPlayLobby3.CreateConnectionData 메소드 및 DirectPlayLobby3.GetConnectionSettings 메소드에 의해 돌려주어진다.

DirectPlayLobbyConnection 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

취득 | GetAddress
 | GetFlags
 | GetGuidSP
 | GetPlayerLongName
 | GetPlayerShortName
 | GetSessionDesc
설정 | SetAddress
 | SetFlags
 | SetGuidSP
 | SetPlayerLongName
 | SetPlayerShortName
 | SetSessionDesc


DirectPlayLobbyConnection.GetAddress

DirectPlayLobbyConnection.GetAddress 메소드는,서비스 프로바이더가세션에 접속하기 위해서 필요한 정보에의 액세스를 제공하는 DirectPlay 주소를 취득한다.

object. GetAddress() As DirectPlayAddress

파라미터

object
DirectPlayLobbyConnection 오브젝트를 나타내는오브젝트식.

반환값

DirectPlayAddress 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayLobbyConnection.GetFlags

DirectPlayLobbyConnection.GetFlags 메소드는, 세션을 여는 방법을 나타내는 플래그를 취득한다.

object. GetFlags() As Long

파라미터

object
DirectPlayLobbyConnection 오브젝트를 나타내는오브젝트식.

반환값

세션을 여는 방법을 나타내는,CONST_DPLCONNECTIONFLAGS 열거형의 몇개의 플래그를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayLobbyConnection.GetGuidSP

DirectPlayLobbyConnection.GetGuidSP 메소드는, 세션에 접속하기 위해서 이용하는서비스 프로바이더의 글로벌 유니크 식별자 (GUID)를 취득한다.

object. GetGuidSP() As String

파라미터

object
DirectPlayLobbyConnection 오브젝트를 나타내는오브젝트식.

반환값

서비스 프로바이더의 GUID 를, 캐릭터 라인 형식에서 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

GUID 의 사용


DirectPlayLobbyConnection.GetPlayerLongName

DirectPlayLobbyConnection.GetPlayerLongName 메소드는, 플레이어의 정식명을 취득한다. 어플리케이션에서는, 이 이름을 무시할 수가 있다.

object. GetPlayerLongName() As String

파라미터

object
DirectPlayLobbyConnection 오브젝트를 나타내는오브젝트식.

반환값

플레이어의 정식명을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectPlayLobbyConnection.SetPlayerLongName


DirectPlayLobbyConnection.GetPlayerShortName

DirectPlayLobbyConnection.GetPlayerShortName 메소드는, 플레이어의 프렌들리명을 취득한다. 어플리케이션에서는, 이 이름을 무시할 수가 있다.

object. GetPlayerShortName() As String

파라미터

object
DirectPlayLobbyConnection 오브젝트를 나타내는오브젝트식.

반환값

플레이어의 프렌들리명을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectPlayLobbyConnection.SetPlayerShortName


DirectPlayLobbyConnection.GetSessionDesc

DirectPlayLobbyConnection.GetSessionDesc 메소드는, 세션을 기술하는 데이터를 포함한 오브젝트를 취득한다.

object. GetSessionDesc() As DirectPlaySessionData

파라미터

object
DirectPlayLobbyConnection 오브젝트를 나타내는오브젝트식.

반환값

DirectPlaySessionData 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectPlay4.Open ,DirectPlay4.SecureOpen ,DirectPlay4.SetSessionDesc


DirectPlayLobbyConnection.SetAddress

DirectPlayLobbyConnection.SetAddress 메소드는,서비스 프로바이더가세션에 접속하기 위해서 필요한 정보에의 액세스를 제공하는 DirectPlay 주소를 설정한다.

object. SetAddress(address As DirectPlayAddress)

파라미터

object
DirectPlayLobbyConnection 오브젝트를 나타내는오브젝트식.
address
DirectPlayAddress 오브젝트.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayLobbyConnection.SetFlags

DirectPlayLobbyConnection.SetFlags 메소드는, 세션을 여는 방법을 나타내는 플래그를 설정한다.

object. SetFlags(flags As CONST_DPLCONNECTIONFLAGS)

파라미터

object
DirectPlayLobbyConnection 오브젝트를 나타내는오브젝트식.
flags
세션을 여는 방법을 나타내는,CONST_DPLCONNECTIONFLAGS 열거형의 플래그.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayLobbyConnection.SetGuidSP

DirectPlayLobbyConnection.SetGuidSP 메소드는, 세션에 접속하기 위해서 이용하는서비스 프로바이더의 글로벌 유니크 식별자 (GUID)를 설정한다.

object. SetGuidSP(guid As String)

파라미터

object
DirectPlayLobbyConnection 오브젝트를 나타내는오브젝트식.
guid
서비스 프로바이더의 GUID. 이하의 캐릭터 라인 앨리어스(alias)의 어느쪽이든을 설정할 수 있다.
DPSPGUID_IPX
DPSPGUID_TCPIP
DPSPGUID_SERIAL
DPSPGUID_MODEM

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

GUID 의 사용


DirectPlayLobbyConnection.SetPlayerLongName

DirectPlayLobbyConnection.SetPlayerLongName 메소드는, 플레이어의 정식명을 설정한다. 이 이름은, 로비에 등록되는 유저의 정식명이 된다. 어플리케이션에서는, 이 이름을 무시할 수가 있다.

object. SetPlayerLongName(name As String)

파라미터

object
DirectPlayLobbyConnection 오브젝트를 나타내는오브젝트식.
name
설정하는 플레이어의 정식명

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectPlayLobbyConnection.SetPlayerShortName


DirectPlayLobbyConnection.SetPlayerShortName

DirectPlayLobbyConnection.SetPlayerShortName 메소드는, 플레이어의 프렌들리명을 설정한다. 이 이름은, 로비에 등록되는 유저의 프렌들리명이 된다. 어플리케이션에서는, 이 이름을 무시할 수가 있다.

object. SetPlayerShortName(name As String)

파라미터

object
DirectPlayLobbyConnection 오브젝트를 나타내는오브젝트식.
name
설정하는 플레이어의 프렌들리명.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectPlayLobbyConnection.SetPlayerLongName


DirectPlayLobbyConnection.SetSessionDesc

DirectPlayLobbyConnection.SetSessionDesc 메소드는, 생성 또는 참가하는 세션에 관한 기술을 설정한다.

object. SetSessionDesc(sessionDesc As DirectPlaySessionData)

파라미터

object
DirectPlayLobbyConnection 오브젝트를 나타내는오브젝트식.
sessionDesc
세션을 기술하는 DirectPlaySessionData 오브젝트. 이 오브젝트를 취득하려면 ,DirectPlay4.CreateSessionData 메소드를 사용한다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayMessage

DirectPlayMessage 클래스는, 메세지 데이터를 읽고 쓰기하기 위한 메소드를 제공한다. 어플리케이션으로 DirectPlayMessage 오브젝트를 생성 하려면 ,DirectPlay4.CreateMessage 메소드를 사용한다. 메세지 오브젝트는,DirectPlay4.Receive 메소드 또는 DirectPlayLobby3.ReceiveLobbyMessage 메소드에 의해 취득된다.

메세지에는, 임의의 타입의 데이터를 포함할 수가 있다. 이러한 타입은, 메세지내에서 자유롭게 조합할 수가 있다. 어플리케이션에서는, 데이터가 기술된 순서와 같은 순서로, 데이터를 읽어낼 필요가 있다.

시스템 메세지에는, 메세지의 타입을 나타내는 최초의 요소로서Long 가 항상 존재한다. 이 값을 읽어내 메세지의 타입을 판단하면(자),DirectPlayMessage 의 읽기 메소드를 사용해, 나머지의 데이터를 적절히 해석할 수가 있다. 각종의 시스템 메세지의 데이터 서식에 관한 상세한 것에 대하여는, 「CONST_DPSYSMSGTYPES 」를 참조할것.

DirectPlayMessage 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

데이터의 읽기 | GetMessageData
 | MoveToSecureMessage
 | MoveToTop
 | ReadByte
 | ReadDouble
 | ReadGuid
 | ReadLong
 | ReadShort
 | ReadSingle
 | ReadString
 | ReadSysChatString
 | ReadSysMsgConnection
 | ReadSysMsgData
 | ReadSysMsgSessionDesc
데이터의 쓰기 | SetMessageData
 | WriteByte
 | WriteDouble
 | WriteGuid
 | WriteLong
 | WriteShort
 | WriteSingle
 | WriteString
그 외 | Clear
 | GetMessageSize


DirectPlayMessage.Clear

DirectPlayMessage.Clear 메소드는, 메세지 오브젝트의 데이터를 모두 소거한다.

object. Clear()

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

어플리케이션으로 메세지를 송신할 때마다 새로운 오브젝트를 생성 하는 것보다도, 기존의 메세지 오브젝트를 소거해, 거기에 새로운 데이터를 설정해 재이용한 (분)편이, 시간이 걸리지 않는다.


DirectPlayMessage.GetMessageData

DirectPlayMessage.GetMessageData 메소드는, 메세지로부터 생의 데이터를 취득한다.

object. GetMessageData(userDefinedType As Any)

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.
userDefinedType
메세지 데이터를 받는 유저 정의형.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

이 메소드는,DirectPlayMessage.SetMessageData 를 사용해 기술된 메세지로부터 데이터를 취득하는 경우에게만 사용해야 한다. 이 메소드는, 메세지의 일부가 1 개 이상의DirectPlayMessage.ReadX 메소드에 의해 이미 취득되고 있는지 어떤지에 관계없이, 메세지 전체를 취득한다.


DirectPlayMessage.GetMessageSize

DirectPlayMessage.GetMessageSize 메소드는, 메세지의 사이즈를 취득한다.

object. GetMessageSize() As Long

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.

반환값

메세지의 사이즈를 바이트 단위로 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayMessage.MoveToSecureMessage

DirectPlayMessage.MoveToSecureMessage 는, 보증 메세지내에서, 읽기 포인터를 메세지 데이터의 최초의 부분으로 이동한다.

object. MoveToSecureMessage()

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

보증 시스템 메세지는, 메세지의 타입 (DPSYS_SECUREMESSAGE)을 나타내는 Long, 플래그를 나타내는 Long, 메세지를 발신한 플레이어의 ID 를 나타내는 Long, 및 메세지 데이터에의 포인터로 구성된다. MoveToSecureMessage 메소드는, 읽기 포인터를 데이터의 시작 부분으로 이동해,DirectPlayMessage.ReadLong 등 다른 메소드를 사용해, 데이터를 해석할 수 있도록(듯이) 한다.

참조

CONST_DPSYSMSGTYPES


DirectPlayMessage.MoveToTop

DirectPlayMessage.MoveToTop 메소드는, 메세지 데이터의 최초의 부분에 읽기 포인터를 이동한다.

object. MoveToTop()

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

DirectPlayMessage.ReadX 메소드의 어느 쪽인가에 따라 메세지 데이터의 요소를 취득할 때마다, 읽기 포인터가 진행된다. MoveToTop 를 사용 하면, 메세지를 최초부터 재차 읽어낼 수가 있다.


DirectPlayMessage.ReadByte

DirectPlayMessage.ReadByte 메소드는, 메세지 데이터로부터 Byte 형의 값을 읽기, 읽기 포인터를 진행시킨다.

object. ReadByte() As Byte

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.

반환값

메세지의 Byte 형의 값을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayMessage.ReadDouble

DirectPlayMessage.ReadDouble 메소드는, 메세지 데이터로부터 Double 형의 값을 읽기, 읽기 포인터를 진행시킨다.

object. ReadDouble() As Double

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.

반환값

메세지의 Double 형의 값을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayMessage.ReadGuid

DirectPlayMessage.ReadGuid 메소드는, 메세지 데이터로부터 GUID 를 읽기, 읽기 포인터를 진행시킨다.

object. ReadGuid() As String

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.

반환값

GUID 를 캐릭터 라인 형식에서 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

GUID 의 사용


DirectPlayMessage.ReadLong

DirectPlayMessage.ReadLong 메소드는, 메세지로부터 Long 형의 값을 읽기, 읽기 포인터를 진행시킨다.

object. ReadLong() As Long

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.

반환값

메세지의 Long 형의 값을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayMessage.ReadShort

DirectPlayMessage.ReadShort 메소드는, 메세지 데이터로부터 Integer 형의 값을 읽기, 읽기 포인터를 진행시킨다.

object. ReadShort() As Integer

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.

반환값

메세지의 Integer 형의 값을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayMessage.ReadSingle

DirectPlayMessage.ReadSingle 메소드는, 메세지 데이터로부터 Single 형의 값을 읽기, 읽기 포인터를 진행시킨다.

object. ReadSingle() As Single

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.

반환값

메세지의 Single 형의 값을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayMessage.ReadString

DirectPlayMessage.ReadString 메소드는, 메세지 데이터로부터 캐릭터 라인을 읽기, 읽기 포인터를 진행시킨다.

object. ReadString() As String

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.

반환값

메세지의 캐릭터 라인을 돌려준다.

에러 코드

패 하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayMessage.ReadSysChatString

DirectPlayMessage.ReadSysChatString 메소드는,DPSYS_CHAT 메세지로부터 캐릭터 라인을 읽어낸다.

object. ReadSysChatString() As String

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.

반환값

메세지의 캐릭터 라인을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayMessage.ReadSysMsgConnection

DirectPlayMessage.ReadSysMsgConnection 메소드는,DPSYS_STARTSESSION 메세지로부터 DirectPlayLobbyConnection 오브젝트를 취득한다.

object. ReadSysMsgConnection() As DirectPlayLobbyConnection

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.

반환값

DirectPlayLobbyConnection 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayMessage.ReadSysMsgData

DirectPlayMessage.ReadSysMsgData 메소드는,DPSYS_CREATEPLAYERORGROUP 메세지,DPSYS_DESTROYPLAYERORGROUP 메세지, 또는 DPSYS_SETPLAYERORGROUPDATA 메세지로부터 데이터를 취득한다.

object. ReadSysMsgData() As String

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.

반환값

메세지 데이터를 포함한 캐릭터 라인을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

이 메소드를 올바르게 호출하려면 , 읽기 포인터가 메세지내의 올바른 위치에 있을 필요가 있다. 예를 들어,DPSYS_DESTROYPLAYERORGROUP 메세지를 해석하는 경우는, 우선 DirectPlayMessage.ReadLong 를 3 회 호출해, 메세지의 타입, 플레이어의 타입, 및 플레이어의 ID 를 취득할 필요가 있다. ReadSysMsgData 를 호출하면, 읽기 포인터는, 메세지 타입의 참조로 기술되고 있는 다음의 필드로 나아간다 ( 「CONST_DPSYSMSGTYPES 」를 참조). 이 점으로부터 생각하면(자), 이 메소드는,DirectPlayMessage.ReadSysChatString ,DirectPlayMessage.ReadSysMsgConnection , 및 DirectPlayMessage.ReadSysMsgSessionDesc 와는 다르다. 이러한 메소드는, 메세지의 일부가 취득이 끝난 상태인가 어떤가에 관계없이 데이터를 취득해, 읽기 포인터를 진행시키지 않는다.


DirectPlayMessage.ReadSysMsgSessionDesc

DirectPlayMessage.ReadSysMsgSessionDesc 메소드는,DPSYS_SETSESSIONDESC 시스템 메세지로부터 세션 기술을 취득한다.

object. ReadSysMsgSessionDesc() As DirectPlaySessionData

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.

반환값

DirectPlaySessionData 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayMessage.SetMessageData

DirectPlayMessage.SetMessageData 메소드는, 유저 정의형의 데이터를 메세지에 기입한다.

object. SetMessageData(userDefinedType As Any, size As Long)

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.
userDefinedType
메세지 데이터를 포함한 형태. 이 유저 정의형의 모든 멤버는, 캐릭터 라인은 아니고, 수치형이 아니면 안된다. 보통, 이 형태의 최초의 멤버는, 메세지의 종류를 정의하는 Long 형의 값이다.
size
userDefinedType 의 바이트 단위의 사이즈.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

SetMessageData 는, 메세지 전체의 내용을 설정하는 경우에게만 사용할 수 있다. 1 개의 메세지에 대해서 2 회 이상 호출해 안되어, 또 다른 쓰기 메소드와 조합해 사용할 수 없다. 이 데이터를 취득하려면 ,DirectPlayMessage.GetMessageData 를 사용한다.

이 메소드는, 상급 유저만이 사용하도록(듯이) 추천 되고 있다. 대부분의 경우는,DirectPlayMessage.WriteX 메소드를 사용해 메세지 데이터를 생성 하고 나서, 대응하는 DirectPlayMessage.ReadX 메소드를 사용해 데이터를 읽어들이는 (분)편이 좋다.


DirectPlayMessage.WriteByte

DirectPlayMessage.WriteByte 메소드는, 메세지 데이터에 Byte 형의 값을 쓰기, 쓰기 포인터를 진행시킨다.

object. WriteByte(val As Byte)

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.
val
메세지에 기입하는 값.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayMessage.WriteDouble

DirectPlayMessage.WriteDouble 메소드는,Double 형의 값을 메세지 데이터에 쓰기, 쓰기 포인터를 진행시킨다.

object. WriteDouble(val As Double)

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.
val
메세지에 기입하는 값.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayMessage.WriteGuid

DirectPlayMessage.WriteGUID 메소드는, GUID 캐릭터 라인을 메세지 데이터에 쓰기, 쓰기 포인터를 진행시킨다.

object. WriteGUID(val As String)

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.
val
메세지에 기입하는 값.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

GUID 의 사용


DirectPlayMessage.WriteLong

DirectPlayMessage.WriteLong 메소드는,Long 형의 값을 메세지 데이터에 쓰기, 쓰기 포인터를 진행시킨다.

object. WriteLong(val As Long)

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.
val
메세지에 기입하는 값.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayMessage.WriteShort

DirectPlayMessage.WriteShort 메소드는,Integer 형의 값을 메세지 데이터에 쓰기, 쓰기 포인터를 진행시킨다.

object. WriteShort(val As Integer)

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.
val
메세지에 기입하는 값.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayMessage.WriteSingle

DirectPlayMessage.WriteSingle 메소드는,Single 형의 값을 메세지 데이터에 쓰기, 쓰기 포인터를 진행시킨다.

object. WriteSingle(val As Single)

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.
val
메세지에 기입하는 값.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlayMessage.WriteString

DirectPlayMessage.WriteString 메소드는,String 형의 값을 메세지 데이터에 쓰기, 쓰기 포인터를 진행시킨다.

object. WriteString(val As String)

파라미터

object
DirectPlayMessage 오브젝트를 나타내는오브젝트식.
val
메세지에 기입하는 값.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlaySessionData

DirectPlaySessionData 클래스는,세션에 관련하는 기술 데이터를 나타낸다. 이 클래스의 오브젝트는,DirectPlay4.CreateSessionData 메소드에 의해 돌려주어져DirectPlay4.Open 또는 DirectPlay4.SecureOpen 에게 건네진다. 또, 이 클래스의 오브젝트는, 세션 기술을 설정 및 취득하기 위해서, 다른 다양한 메소드에 의해 사용된다.

DirectPlaySessionData 클래스에는, 이하의 메소드가 있다.

데이터의 취득 | GetCurrentPlayers
 | GetFlags
 | GetGuidApplication
 | GetGuidInstance
 | GetMaxPlayers
 | GetSessionName
 | GetSessionPassword
 | GetUser1
 | GetUser2
 | GetUser3
 | GetUser4
데이터의 설정 | SetFlags
 | SetGuidApplication
 | SetGuidInstance
 | SetMaxPlayers
 | SetSessionName
 | SetSessionPassword
 | SetUser1
 | SetUser2
 | SetUser3
 | SetUser4

참조

DirectPlay4.GetSessionDesc ,DirectPlay4.SetSessionDesc ,DirectPlayLobbyConnection.GetSessionDesc ,DirectPlayLobbyConnection.SetSessionDesc ,DirectPlay4.GetDPEnumSessions ,DirectPlayEnumSessions.GetItem


DirectPlaySessionData.GetCurrentPlayers

DirectPlaySessionData.GetCurrentPlayers 메소드는, 세션내의 플레이어의 현재의 수를 취득한다.

object. GetCurrentPlayers() As Long

파라미터

object
DirectPlaySessionData 오브젝트를 나타내는오브젝트식.

반환값

플레이어의 현재의 수를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlaySessionData.GetFlags

DirectPlaySessionData.GetFlags 메소드는, 세션에 대한 플래그를 취득한다.

object. GetFlags() As Long

파라미터

object
DirectPlaySessionData 오브젝트를 나타내는오브젝트식.

반환값

세션을 기술하는,CONST_DPSESSIONFLAGS 열거형의 플래그를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlaySessionData.GetGuidApplication

DirectPlaySessionData.GetGuidApplication 메소드는, 세션을 생성 한 어플리케이션의 GUID 를 취득한다.

object. GetGuidApplication() As String

파라미터

object
DirectPlaySessionData 오브젝트를 나타내는오브젝트식.

반환값

어플리케이션의 GUID 를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlaySessionData.GetGuidInstance

DirectPlaySessionData.GetGuidInstance 메소드는, 세션 인스턴스의 GUID 를 취득한다.

object. GetGuidInstance() As String

파라미터

object
DirectPlaySessionData 오브젝트를 나타내는오브젝트식.

반환값

세션이 생성 되었을 때에, 어플리케이션에 의해 할당할 수 있었던 GUID 를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlaySessionData.GetMaxPlayers

DirectPlaySessionData.GetMaxPlayers 메소드는, 세션에 참가 가능한 플레이어의 최대수를 취득한다.

object. GetMaxPlayers() As Long

파라미터

object
DirectPlaySessionData 오브젝트를 나타내는오브젝트식.

반환값

플레이어의 최대수를 돌려준다. 최대수가 존재하지 않는 경우는, 0 을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlaySessionData.GetSessionName

DirectPlaySessionData.GetSessionName 메소드는, 세션의 이름을 취득한다.

object. GetSessionName() As String

파라미터

object
DirectPlaySessionData 오브젝트를 나타내는오브젝트식.

반환값

세션의 이름을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlaySessionData.GetSessionPassword

DirectPlaySessionData.GetSessionPassword 메소드는, 세션에 대한 패스워드를 취득한다.

object. GetSessionPassword() As String

파라미터

object
DirectPlaySessionData 오브젝트를 나타내는오브젝트식.

반환값

세션에 참가하기 위해서 필요한 패스워드를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlaySessionData.GetUser1

「DirectPlaySessionData.GetUser(n) 」를 참조.


DirectPlaySessionData.GetUser2

「DirectPlaySessionData.GetUser(n) 」를 참조.


DirectPlaySessionData.GetUser3

「DirectPlaySessionData.GetUser(n) 」를 참조.


DirectPlaySessionData.GetUser4

「DirectPlaySessionData.GetUser(n) 」를 참조.


DirectPlaySessionData.GetUser(n)

DirectPlaySessionData.GetUser1 메소드,DirectPlaySessionData.GetUser2 메소드,DirectPlaySessionData.GetUser3 메소드, 및DirectPlaySessionData.GetUser4 메소드는, 세션에 대한 어플리케이션 정의의 데이터를 취득한다.

object. GetUser1() As Long

파라미터

object
DirectPlaySessionData 오브젝트를 나타내는오브젝트식.

반환값

어플리케이션 정의의 데이터를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlaySessionData.SetFlags

DirectPlaySessionData.SetFlags 메소드는, 세션에 대한 플래그를 설정한다.

object. SetFlags(val As CONST_DPSESSIONFLAGS)

파라미터

object
DirectPlaySessionData 오브젝트를 나타내는오브젝트식.
val
세션을 기술하는,CONST_DPSESSIONFLAGS 열거형의 플래그.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlaySessionData.SetGuidApplication

DirectPlaySessionData.SetGuidApplication 메소드는, 세션 기술내의 어플리케이션의 GUID 를 설정한다.

object. SetGuidApplication(guid As String)

파라미터

object
DirectPlaySessionData 오브젝트를 나타내는오브젝트식.
guid
어플리케이션의 GUID. 이 멤버에 하늘의 캐릭터 라인을 설정 하면, 임의의 어플리케이션에 대한 세션을 열거할 수가 있다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlaySessionData.SetGuidInstance

DirectPlaySessionData.SetGuidInstance 메소드는, 세션 인스턴스에 대한 GUID 를 설정한다.

object. SetGuidInstance(guid As String)

파라미터

object
DirectPlaySessionData 오브젝트를 나타내는오브젝트식.
guid
세션의 GUID.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlaySessionData.SetMaxPlayers

DirectPlaySessionData.SetMaxPlayers 메소드는, 세션에 참가 가능한 플레이어의 최대수를 설정한다.

object. SetMaxPlayers(val As Long)

파라미터

object
DirectPlaySessionData 오브젝트를 나타내는오브젝트식.
val
플레이어의 최대수. 0 의 경우, 최대수는 존재하지 않는다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlaySessionData.SetSessionName

DirectPlaySessionData.SetSessionName 메소드는, 세션의 이름을 설정한다.

object. SetSessionName(val As String)

파라미터

object
DirectPlaySessionData 오브젝트를 나타내는오브젝트식.
val
세션의 이름.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlaySessionData.SetSessionPassword

DirectPlaySessionData.SetSessionPassword 메소드는, 세션에 대한 패스워드를 설정한다.

object. SetSessionPassword(val As String)

파라미터

object
DirectPlaySessionData 오브젝트를 나타내는오브젝트식.
val
세션에 대한 패스워드

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectPlaySessionData.SetUser1

「DirectPlaySessionData.SetUser(n) 」를 참조.


DirectPlaySessionData.SetUser2

「DirectPlaySessionData.SetUser(n) 」를 참조.


DirectPlaySessionData.SetUser3

「DirectPlaySessionData.SetUser(n) 」를 참조.


DirectPlaySessionData.SetUser4

「DirectPlaySessionData.SetUser(n) 」를 참조.


DirectPlaySessionData.SetUser(n)

DirectPlaySessionData.SetUser1 메소드,DirectPlaySessionData.SetUser2 메소드,DirectPlaySessionData.SetUser3 메소드, 및 DirectPlaySessionData.SetUser4 메소드는, 세션에 대한 어플리케이션 정의의 데이터를 설정한다.

object. SetUser1(val As Long)

파라미터

object
DirectPlaySessionData 오브젝트를 나타내는오브젝트식.
val
어플리케이션 정의의 데이터.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


형

여기에서는, DirectPlay 용으로 정의되고 있는 이하의 형태에 관한 레퍼런스를 제공한다.

  • DPAPPLICATIONDESC2
  • DPCAPS
  • DPCREDENTIALS
  • DPSECURITYDESC


DPAPPLICATIONDESC2

DPAPPLICATIONDESC2 형은,DirectPlayLobby3.RegisterApplication 메소드를 사용해 등록되는 어플리케이션에 관한 정보를 포함하고 있다.

Type DPAPPLICATIONDESC2
    lFlags As Long
    strAppLauncherName As String
    strApplicationName As String
    strCommandLine As String
    strCurrentDirectory As String
    strDescription As String
    strFilename As String
    strGuid As String
    strPath As String
End Type

멤버

lFlags
사용하지 않는다. 0 으로 하는 것.
strAppLauncherName
란체의 실행 가능 파일의 이름. 란체는, 로비에 의해 시작 되어strApplicationName 로 기술되는 어플리케이션을 기동하는 책임을 다한다. 란체는, 어플리케이션과 같은 디렉토리에 존재하고 있지 않으면 안 된다.
strApplicationName
어플리케이션의 이름. 이 타이틀을 로컬라이즈 하지 않는 것. 어플리케이션명을 로컬라이즈 하는 경우는,strDescription 멤버를 사용한다.
strCommandLine
로비에 의해 기동되었을 때에 실행 가능 파일에게 건네지는, 커멘드 라인 인수.
strCurrentDirectory
현재 디렉토리를 설정하는 패스.
strDescription
어플리케이션의, 로컬라이즈 된 기술. DirectPlayLobby3.GetDPEnumLocalApplications 를 호출하면, 이 캐릭터 라인이 돌려주어진다.
strFilename
기동하는 실행 가능 파일의 이름. 주 : 로비로부터 기동하는 경우는, 그루터기의 실행 가능 파일의 사용은 피해야 하는 것이다. 로비로부터 기동하는 시나리오에서는, 그루터기를 우회도로 해, 메인의 실행 가능 파일을 기동해야 한다.
strGuid
어플리케이션의 글로벌 유니크 식별자 (GUID). 이것은, 게임 세션을 호스트 하는 경우에는,DirectPlaySessionData.SetGuidApplication 에 의해 설정되는 값과 같은 필요가 있다.
strPath
실행 가능 파일이 존재하는 패스.


DPCAPS

DPCAPS 형은,DirectPlay4.GetCaps 메소드 또는 DirectPlay4.GetPlayerCaps 메소드를 호출한 후에, DirectPlay 오브젝트의 능력을 보관 유지한다. 보증 붙어 또는 보증 없음의 어느 쪽의 능력을 필요로 하고 있을까에 응해, 이러한 능력의 임의의 것을 변경할 수가 있다.

Type DPCAPS
    lFlags As Long
    lHeaderLength As Long
    lHundredBaud As Long
    lLatency As Long
    lMaxBufferSize As Long
    lMaxLocalPlayers As Long
    lMaxPlayers As Long
    lMaxQueueSize As Long
    lTimeout As Long
End Type

멤버

lFlags
DirectPlay 오브젝트의 프로퍼티를 나타내는,CONST_DPCAPSFLAGS 열거형의 멤버. DPCAPS_ASYNCSUPPORTED 플래그, DPCAPS_SENDTIMEOUTSUPPORTED 플래그, DPCAPS_SENDPRIORITYSUPPORTED 플래그, DPCAPS_ASYNCCANCELSUPPORTED 플래그, 및 DPCAPS_ASYNCCANCELALLSUPPORTED 플래그는, 현재의 세션의 통신 능력을 나타낸다.
lHeaderLength
이 DirectPlay 오브젝트에 의해 플레이어 메세지에 추가되는 헤더의, 바이트 단위의 사이즈. 이 헤더 사이즈는, 사용하는 서비스 프로바이더에 따라서 다르다.
lHundredBaud
1 초 쯤의 대역폭을 100 비트의 배수로 가리킨다. 예를 들어, 이 값이 24 의 경우는, 2400 비트/초를 나타낸다.
lLatency
서비스 프로바이더에 의한 추정의지연 시간을 밀리 세컨드 단위로 지정한다. 이 값이 0 의 경우, DirectPlay 는 지연 시간을 추정할 수 없다. 서비스 프로바이더에 따라서는, 메세지 사이즈의 평균을 고려해, 어플리케이션간 테스트에 근거한 정밀도가 된다. 지연 시간은, 어플리케이션으로 보증 붙어 또는 보증 없음의 어느 쪽의 메세지 전달을 이용할까에 따라서 다른 경우가 있다.
lMaxBufferSize
이 서비스 프로바이더가 1 개의 패킷으로 송신할 수 있는 바이트수. 이것보다 큰 메세지는, 2 개(살) 이상의 패킷을 사용해 송신된다.
lMaxLocalPlayers
세션으로 지원 되는 로컬 플레이어의 최대수.
lMaxPlayers
이 DirectPlay 오브젝트에 의해, 세션내에서 지원 되는 로컬 플레이어와 리모트 플레이어의 최대수.
lMaxQueueSize
사용되지 않는다.
lTimeout
서비스 프로바이더가 제안하는 타임 아웃값. 디폴트에서는, DirectPlay 는 메세지에의 응답을 대기할 경우에, 이 타임 아웃값을 사용한다.

주의

DirectPlay4.SendEx 메소드의 어느 요소가 지원 되고 있는지를 나타내는 능력 (lFlags 의 DPCAPS_SENDPRIORITYSUPPORTED 플래그, DPCAPS_SENDTIMEOUTSUPPORTED 플래그등)은, 세션이 열린 다음이 아니면 이용할 수 없다.

SendEx 로 DPSEND_ASYNC 를 사용하려면 , 이하의 조건의 언젠가 또는 양쪽 모두가 진이 아니면 안된다.

  • 세션을 생성 할 경우에, DPSESSION_DIRECTPLAYPROTOCOL 플래그를 설정했다.
  • 서비스 프로바이더가, 비동기 메시징을 지원 하고 있다.

즉, 모뎀, 시리얼, 및 IPX (Internetwork Packet Exchange)의 서비스 프로바이더에서는, 보증 메시징을 이용할 수 있지만, DPSESSION_DIRECTPLAYPROTOCOL 플래그를 명시적으로 설정하지 않으면, 비동기 메시징을 실행할 수 없다고 하는 것이다. TCP/IP 서비스 프로바이더는, 컴퓨터에 Windows Sockets 2.0 이 존재하는 경우에, 비동기 메시징을 이행 한다.

세션을 호스트 하고 있는 어플리케이션이 DirectPlaySessionData 오브젝트로 DPSESSION_DIRECTPLAYPROTOCOL 플래그를 설정했을 경우,SendEx 의 모든 옵션이 지원 된다.


DPCREDENTIALS

DPCREDENTIALS 형은, 보증 서버에 접속하기 위한 유저의 도메인, 패스워드, 및 이름을 포함한다.

Type DPCREDENTIALS
    lFlags As Long
    strDomain As String
    strPassword As String
    strUsername As String
End Type

멤버

lFlags
사용하지 않는다. 0 으로 설정하는 것.
strDomain,strPassword,strUsername
유저의 도메인, 패스워드, 및 이름을 포함한 ANSI 캐릭터 라인.


DPSECURITYDESC

DPSECURITYDESC 형은, DirectPlay 세션의 인스턴스의 시큐러티 프로퍼티를 기술한다.

Type DPSECURITYDESC
    lCAPIProviderType As Long
    lEncryptionAlgorithm As Long
    lFlags As Long
    strCAPIProvider As String
    strSSPIProvider As String
End Type

멤버

lCAPIProviderType
CryptoAPI 서비스 프로바이더 타입. 디폴트의 타입 PROV_RSA_FULL 를 사용하는 경우는, 0 을 건네준다.
lEncryptionAlgorithm
사용하는 암호화 알고리즘. DirectPlay 는, 스트림사이파만을 지원 한다. 디폴트의 CALG_RC4 스트림사이파를 사용하는 경우는, 0 을 건네준다.
lFlags
사용하지 않는다. 0 을 설정하는 것.
strCAPIProvider
암호화 서비스를 위해서(때문에) 사용하는 CryptoAPI 패키지를 기술하는, Unicode 또는 ANSI 의 캐릭터 라인. 디폴트의 Microsoft RSA Base Cryptographic Provider 1.0 을 사용하는 경우는, NULL 를 건네준다.
strSSPIProvider
인증 로그 온에 사용하는 Security Support Provider Interface (SSPI) 패키지를 기술하는, Unicode 또는 ANSI 의 캐릭터 라인. 디폴트의 NTLM 시큐러티 프로바이더를 사용하는 경우는, NULL 를 건네준다.


열거형

여기에서는, DirectPlay for Visual Basic 로 사용하는 이하의 열거형에 관한 레퍼런스를 제공한다.

  • CONST_DPCAPSFLAGS
  • CONST_DPCONNECTFLAGS
  • CONST_DPENUMCONNECTIONFLAGS
  • CONST_DPENUMGROUPFLAGS
  • CONST_DPENUMPLAYERFLAGS
  • CONST_DPENUMSESSIONFLAGS
  • CONST_DPGETCAPSFLAGS
  • CONST_DPGETFLAGS
  • CONST_DPGROUPFLAGS
  • CONST_DPIDFLAGS
  • CONST_DPLAYERR
  • CONST_DPLCONNECTIONFLAGS
  • CONST_DPLMSG
  • CONST_DPLWAIT
  • CONST_DPMESSAGEQUEUEFLAGS
  • CONST_DPOPENFLAGS
  • CONST_DPPLAYERFLAGS
  • CONST_DPPLAYERTYPEFLAGS
  • CONST_DPRECEIVEFLAGS
  • CONST_DPSENDFLAGS
  • CONST_DPSESSIONFLAGS
  • CONST_DPSETFLAGS
  • CONST_DPSYSMSGTYPES


CONST_DPCAPSFLAGS

CONST_DPCAPSFLAGS 열거형의 정수는, DirectPlay 오브젝트의 능력을 지정하기 위해서,DPCAPS 형으로 사용된다.

Enum CONST_DPCAPSFLAGS
    DPCAPS_ASYNCCANCELALLSUPPORTED = 8192 (&H2000)
    DPCAPS_ASYNCCANCELSUPPORTED =    4096 (&H1000)
    DPCAPS_ASYNCSUPPORTED =         65536 (&H10000)
    DPCAPS_ENCRYPTIONSUPPORTED =      256 (&H100)
    DPCAPS_GROUPOPTIMIZED =             8
    DPCAPS_GUARANTEEDOPTIMIZED =       32 (&H20)
    DPCAPS_GUARANTEEDSUPPORTED =       64 (&H40)
    DPCAPS_ISHOST =                     2
    DPCAPS_KEEPALIVEOPTIMIZED =        16 (&H10)
    DPCAPS_SENDPRIORITYSUPPORTED =  32768 (&H8000)
    DPCAPS_SENDTIMEOUTSUPPORTED =   16384 (&H4000)
    DPCAPS_SIGNINGSUPPORTED =         128 (&H80)
End Enum
DPCAPS_ASYNCCANCELALLSUPPORTED
보류중의 모든 비동기 메세지의 캔슬을 지원 하고 있다. 이 플래그는, 지원 되고 있는 캔슬의 형식이, 송신되어 있지 않은 모든 메세지의 캔슬인 것을 나타내고 있다. 우선 순위의 범위 또는 메세지 ID 를 지정해 메세지를 캔슬 하면, DPERR_UNSUPPORTED 가 돌려주어진다. 한편, DPCAPS_ASYNCCANCELSUPPORTED 플래그는, 모든 종류의 캔슬이 지원 되고 있는 것을 나타낸다. SendEx 목의 요소가 지원 되고 있는지를 나타내는 능력은, 세션이 열리지 않으면 이용할 수 없다.
DPCAPS_ASYNCCANCELSUPPORTED
비동기 메세지의 캔슬을 지원 하고 있다. 메세지 ID 에 의한 캔슬, 우선 순위의 범위에 의한 캔슬, 송신되어 있지 않은 모든 메세지의 캔슬 등, 모든 종류의 캔슬이 지원 되고 있다. SendEx 목의 요소가 지원 되고 있는지를 나타내는 능력은, 세션이 열리지 않으면 이용할 수 없다.
DPCAPS_ASYNCSUPPORTED
비동기 메시징을 지원 하고 있다. 그 때문에, 어플리케이션에서는,SendEx 로 DPSEND_ASYNC 플래그를 사용할 수 있다. SendEx 목의 요소가 지원 되고 있는지를 나타내는 능력은, 세션이 열리지 않으면 이용할 수 없다.
DPCAPS_ENCRYPTIONSUPPORTED
이 DirectPlay 오브젝트는, 메세지의 암호화를 지원 하고 있다. 이것은, 세션이 보증 세션인지, 또는서비스 프로바이더가 메세지를 암호화할 수 있기 때문에 있다.
DPCAPS_GROUPOPTIMIZED
이 DirectPlay 오브젝트에 결합하고 있는 서비스 프로바이더는,그룹 (멀티 캐스트) 메시징을 최적화할 수 있다.
DPCAPS_GUARANTEEDOPTIMIZED
이 DirectPlay 오브젝트에 결합하고 있는 서비스 프로바이더는, 보증 메세지 전달을 지원 하고 있다.
DPCAPS_GUARANTEEDSUPPORTED
이 DirectPlay 오브젝트는, 보증 메세지 전달을 지원 한다. 이것은, 서비스 프로바이더가 보증 메세지 전달을 지원 하고 있는지, 또는 DirectPlay 가 그것을 보증 없음의 서비스 프로바이더상에서 이행 하기 위한(해)이다.
DPCAPS_ISHOST
호출측의 어플리케이션에 의해 생성 된 DirectPlay 오브젝트는, 세션의호스트이다.
DPCAPS_KEEPALIVEOPTIMIZED
이 서비스 프로바이더는, 세션에의 접속이 해제된 타이밍을 파악할 수가 있다.
DPCAPS_SENDPRIORITYSUPPORTED
SendEx 로 설정되는 메세지의 우선 순위를 지원 한다. SendEx 목의 요소가 지원 되고 있는지를 나타내는 능력은, 세션이 열리지 않으면 이용할 수 없다.
DPCAPS_SENDTIMEOUTSUPPORTED
SendEx 로 지정되는 메세지의 타임 아웃을 지원 한다. 이 플래그를 설정할 수 있는 것은, 서비스 프로바이더 또는 DirectPlay 이다. SendEx 목의 요소가 지원 되고 있는지를 나타내는 능력은, 세션이 열리지 않으면 이용할 수 없다.
DPCAPS_SIGNINGSUPPORTED
이 DirectPlay 오브젝트는, 메세지의 인증을 지원 한다. 이것은, 이 오브젝트가 보증 세션을 지원 하고 있는지, 또는 서비스 프로바이더가 서명을 첨부할 수 있기 때문이다.


CONST_DPCONNECTFLAGS

CONST_DPCONNECTFLAGS 열거형의 멤버는, 메소드가 돌아오는 타이밍을 지정하기 위해서,DirectPlayLobby3.Connect 메소드로 사용된다.

Enum CONST_DPCONNECTFLAGS
    DPCONNECTION_DEFAULT =        0
    DPCONNECTION_RETURNSTATUS = 128 (&H80)
End Enum
DPCONNECTION_DEFAULT
메소드는, 접속이 확립되는지, 또는 조작이 타임 아웃이 된 다음에 돌아온다.
DPCONNECTION_RETURNSTATUS
메소드는, 접속 상태와 함께 즉시 돌아온다.


CONST_DPENUMCONNECTIONFLAGS

CONST_DPENUMCONNECTIONFLAGS 열거형의 멤버는, 열거하는 접속의 종류를 지정하기 위해서,DirectPlay4.GetDPEnumConnections 메소드로 사용된다.

Enum CONST_DPENUMCONNECTIONFLAGS
    DPCONNECTION_DIRECTPLAY = 1
    DPCONNECTION_DIRECTPLAYLOBBY = 2
End Enum
DPCONNECTION_DIRECTPLAY
어플리케이션 세션으로 통신하기 위한 , DirectPlay 서비스 프로바이더를 열거한다.
DPCONNECTION_DIRECTPLAYLOBBY
로비 서버와 통신하기 위한 ,DirectPlay 로비 프로바이더를 열거한다.


CONST_DPENUMGROUPFLAGS

CONST_DPENUMGROUPFLAGS 열거형의 멤버는, 열거하는 그룹의 종류를 지정하기 위해서,DirectPlay4.GetDPEnumGroups 메소드 및 DirectPlay4.GetDPEnumGroupsInGroup 메소드로 사용된다.

Enum CONST_DPENUMGROUPFLAGS
    DPENUMGROUPS_ALL =            0
    DPENUMGROUPS_HIDDEN =      4096 (&H1000)
    DPENUMGROUPS_LOCAL =          8
    DPENUMGROUPS_REMOTE =        16 (&H10)
    DPENUMGROUPS_SESSION =      128 (&H80)
    DPENUMGROUPS_SHORTCUT =    1024 (&H400)
    DPENUMGROUPS_STAGINGAREA = 2048 (&H800)
End Enum
DPENUMGROUPS_ALL
모든 그룹을 열거한다.
DPENUMGROUPS_HIDDEN
그룹내의 현재 이용 가능한 숨고 그룹을 열거한다. GetDPEnumGroupsInGroup 에서만 유효하다.
DPENUMGROUPS_LOCAL
이 DirectPlay 오브젝트에 의해 로컬에 생성 된 그룹을 열거한다.
DPENUMGROUPS_REMOTE
리모트의 DirectPlay 오브젝트에 의해 생성 된 그룹을 열거한다.
DPENUMGROUPS_SESSION
sessionGuid 파라미터로 지정되는 세션내에서 열거를 실행한다. 이 플래그는, 현재 액티브한 세션이 존재하지 않는 경우에게만 사용할 수 있어 로비 세션에서는 사용할 수 없다.
DPENUMGROUPS_SHORTCUT
DirectPlay4.AddGroupToGroup 를 사용해 그룹에 추가된 쇼트 컷인 그룹을 열거한다 (쇼트 컷은, 다른 그룹에의 링크이다). GetDPEnumGroupsInGroup 에서만 유효하다.
DPENUMGROUPS_STAGINGAREA
staging 영역인 그룹을 열거한다 (staging 영역은, 새로운 세션을 기동할 때에, 플레이어를 배치하기 위해서 이용된다).


CONST_DPENUMPLAYERFLAGS

CONST_DPENUMPLAYERFLAGS 열거형의 멤버는, 열거하는 플레이어의 종류를 지정하기 위해서,DirectPlay4.GetDPEnumPlayers 메소드 및 DirectPlay4.GetDPEnumGroupPlayers 메소드로 사용된다.

Enum CONST_DPENUMPLAYERFLAGS
    DPENUMPLAYERS_ALL =            0
    DPENUMPLAYERS_GROUP =         32 (&H20)
    DPENUMPLAYERS_LOCAL =          8
    DPENUMPLAYERS_OWNER =       8192 (&H2000)
    DPENUMPLAYERS_REMOTE =        16 (&H10)
    DPENUMPLAYERS_SERVERPLAYER = 200 (&H100)
    DPENUMPLAYERS_SESSION =      128 (&H80)
    DPENUMPLAYERS_SPECTATOR =    512 (&H200)
End Enum
DPENUMPLAYERS_ALL
이 세션의 모든 플레이어.
DPENUMPLAYERS_GROUP
그룹.
DPENUMPLAYERS_LOCAL
이 DirectPlay 오브젝트에 의해 로컬에 생성 된 플레이어.
DPENUMPLAYERS_OWNER
그룹의 소유자.
DPENUMPLAYERS_REMOTE
리모트의 DirectPlay 오브젝트에 의해 생성 된 플레이어.
DPENUMPLAYERS_SERVERPLAYER
서버 플레이어.
DPENUMPLAYERS_SESSION
sessionGuid 에 의해 지정되는 세션의 플레이어. 이 플래그는, 현재 열려 있는 세션이 존재하지 않는 경우에게만, 사용할 수 있다.
DPENUMPLAYERS_SPECTATOR
관객 플레이어.


CONST_DPENUMSESSIONFLAGS

CONST_DPENUMSESSIONFLAGS 열거형의 멤버는, 열거하는 세션을 지정하기 위해서,DirectPlay4.GetDPEnumSessions 메소드로 사용된다.

Enum CONST_DPENUMSESSIONFLAGS
    DPENUMSESSIONS_ALL =               2
    DPENUMSESSIONS_ASYNC =            16 (&H10)
    DPENUMSESSIONS_AVAILABLE =         1
    DPENUMSESSIONS_PASSWORDREQUIRED = 64 (&H40)
    DPENUMSESSIONS_RETURNSTATUS =    128 (&H80)
    DPENUMSESSIONS_STOPASYNC =        16 (&H10)
End Enum
DPENUMSESSIONS_ALL
세션이 새로운 플레이어를 받아들일지 어떨지에 관계없이, 모든 액티브 세션을 열거한다. 플레이어의 한도에 이르고 있는 세션, 새로운 플레이어를 무효로 하고 있는 세션, 또는 참가를 무효로 하고 있는 세션도 열거된다. 패스워드로 보호된 세션은, DPENUMSESSIONS_PASSWORDREQUIRED 플래그도 지정되고 있는 경우를 제외해, 열거되지 않는다.
DPENUMSESSIONS_ASYNC
세션 캐쉬내의 현재의 세션을 모두 열거해, 즉시 돌아온다. 비동기 열거 처리가 아직 시작되지 않은 경우는, 그것을 시작 한다. 세션 리스트의 갱신은, DPENUMSESSIONS_STOPASYNC 플래그를 설정해 GetDPEnumSessions 를 호출하는지, 또는 DirectPlay4.Open 를 호출할 때까지, 계속한다.

이 플래그를 지정하지 않는 경우, 열거는 비동기에 행해진다.

DPENUMSESSIONS_AVAILABLE
새로운 플레이어의 참가를 받아들이는 세션을 모두 열거한다. 플레이어의 한도에 이르고 있는 세션, 새로운 플레이어를 무효로 하고 있는 세션, 또는 참가를 무효로 하고 있는 세션은 열거되지 않는다. 패스워드로 보호된 세션은, DPENUMSESSIONS_PASSWORDREQUIRED 플래그도 지정되고 있는 경우를 제외해, 열거되지 않는다.
DPENUMSESSIONS_PASSWORDREQUIRED
DPENUMSESSIONS_AVAILABLE 또는 DPENUMSESSIONS_ALL 와 조합해 사용 하면, 패스워드로 보호된 세션이, 패스워드로 보호되어 있지 않은 세션과 함께 열거된다.
DPENUMSESSIONS_RETURNSTATUS
이 플래그를 지정 하면, 열거시에, 접속의 진행 상황을 나타내는 다이알로그 박스가 표시되지 않는다. 접속을 즉시 확립할 수 없는 경우는, DPERR_CONNECTING 에러를 돌려준다. 어플리케이션에서는, 메소드가 성공하는지, 또는 다른 에러 코드가 돌려주어질 때까지,GetDPEnumSessions 를 계속 호출할 필요가 있다.
DPENUMSESSIONS_STOPASYNC
세션 캐쉬내의 현재의 세션을 모두 열거해, 비동기의 열거 처리를 캔슬한다.


CONST_DPGETCAPSFLAGS

CONST_DPGETCAPSFLAGS 열거형의 멤버는, DirectPlay 및 플레이어의 능력을 나타내기 위해서(때문에) 이용된다. 이러한 플래그는,DirectPlay4.GetCaps 메소드 및 DirectPlay4.GetPlayerCaps 메소드에 의해 돌려주어진다.

Enum CONST_DPGETCAPSFLAGS
    DPGETCAPS_DEFAULT =    0
    DPGETCAPS_GUARANTEED = 1
End Enum
DPGETCAPS_DEFAULT
보증 없음의 메시징에 대한 능력.
DPGETCAPS_GUARANTEED
보증 첨부의 메시징에 대한 능력.


CONST_DPGETFLAGS

CONST_DPGETFLAGS 열거형의 멤버는,DirectPlay4.GetGroupData 메소드 및 DirectPlay4.GetPlayerData 메소드에 의해 돌려주어지는 데이터를 결정하기 위해서(때문에) 사용된다.

Enum CONST_DPGETFLAGS
    DPGET_LOCAL = 1
    DPGET_REMOTE = 0
End Enum
DPGET_LOCAL
이 어플리케이션에 의해 설정된 로컬 데이터를 취득한다.
DPGET_REMOTE
리모트의 공유 데이터 공간으로부터 현재의 데이터를 취득한다.

참조

CONST_DPSETFLAGS


CONST_DPGROUPFLAGS

Members of the CONST_DPGROUPFLAGS 열거형의 멤버는, 생성 하는 그룹의 종류를 지정하기 위해서,DirectPlay4.CreateGroup 메소드와 DirectPlay4.CreateGroupInGroup 메소드로 사용된다. 이러한 멤버는,DirectPlay4.GetGroupFlags 메소드에 의해 돌려주어진다.

Enum CONST_DPGROUPFLAGS
    DPGROUP_DEFAULT =        0
    DPGROUP_HIDDEN =      4096 (&H1000)
    DPGROUP_LOCAL =          8
    DPGROUP_STAGINGAREA = 2048 (&H800)
End Enum
DPGROUP_DEFAULT
그룹은, 이하의 특성을 모두 가지지 않는다.
DPGROUP_HIDDEN
그룹은 숨겨지고 있다. 로비 세션에서는, 은폐 그룹을 이용하려면 ,DirectPlay4.AddGroupToGroup 에 의해 생성 된 쇼트 컷을 사용할 필요가 있다. 이 플래그는, 플레이어에 대한 DPPLAYER_SPECTATOR 플래그와 같이 기능한다.
DPGROUP_LOCAL
그룹은, 이 어플리케이션에 의해 생성 되었다. 이 그룹을 지정하지 않는 경우, 그룹은 리모트 그룹이다.
DPGROUP_STAGINGAREA
그룹은, staging 영역이다. staging 영역은, 새로운 세션을 시작 할 때에, 플레이어를 배치하기 위해서 이용된다.


CONST_DPIDFLAGS

CONST_DPIDFLAGS 열거형의 멤버는, 특별한 플레이어 ID 에 대해서 사용된다.

Enum CONST_DPIDFLAGS
    DPID_ALLPLAYERS   = 0
    DPID_SERVERPLAYER = 1
    DPID_SYSMSG       = 0
    DPID_UNKNOWN     = -1 (&HFFFFFFFF)
End Enum
DPID_ALLPLAYERS
모든 플레이어에게 송신된 메세지를 식별한다.
DPID_SERVERPLAYER
서버 플레이어를 식별한다. 이 ID 는,DirectPlay4.CreatePlayer 로 DPPLAYER_SERVERPLAYER 플래그를 설정해 생성 된 플레이어에 대해서 할당할 수 있다.
DPID_SYSMSG
시스템에 의해 송신된 메세지를 식별한다.
DPID_UNKNOWN
메세지의 송신자 또는 수신자가 불명하다.


CONST_DPLAYERR

CONST_DPLAYERR 열거형의 멤버는, DirectPlay 의에러 코드를 나타낸다.


CONST_DPLCONNECTIONFLAGS

CONST_DPLCONNECTIONFLAGS 열거형의 멤버는,DirectPlayLobbyConnection 오브젝트의 플래그로 사용된다.

Enum CONST_DPLCONNECTIONFLAGS
    DPLCONNECTION_CREATESESSION = 2
    DPLCONNECTION_JOINSESSION =   1
End Enum
DPLCONNECTION_CREATESESSION
세션 기술로 기술되고 있는 대로, 새로운 세션을 생성 한다.
DPLCONNECTION_JOINSESSION
세션 기술로 기술되고 있는 대로, 기존의 세션에 참가한다.

참조

DirectPlayLobbyConnection.GetFlags ,DirectPlayLobbyConnection.SetFlags


CONST_DPLMSG

CONST_DPLMSG 열거형은, 로비에 송신되는 메세지와 로비로부터 송신되는 메세지를 식별하기 위해서 사용된다.

Enum CONST_DPLMSG
    DPLMSG_STANDARD =    2
    DPLMSG_SYSTEM =      1
    DPLMSG_USERDEFINED = 0
End Enum
DPLMSG_STANDARD
DirectPlay 로 정의된 메세지이다. 이런 종류의 메세지의 처리는 옵션이다.
DPLMSG_SYSTEM
DirectPlay 에 의해 생성된 시스템 메세지이다. 이 메세지는, 로비에 기동된 어플리케이션의 입장에서, 로비로 변경을 통지하기 위해서 이용된다.
DPLMSG_USERDEFINED
메세지는, 어플리케이션에 의해 정의되고 있다.

참조

DirectPlayLobby3.ReceiveLobbyMessage ,DirectPlayLobby3.SendLobbyMessage


CONST_DPLWAIT

CONST_DPLWAIT 열거형은,DirectPlayLobby3.WaitForConnectionSettings 메소드로 사용된다.

Enum CONST_DPLWAIT
    DPLWAIT_CANCEL =  1
    DPLWAIT_DEFAULT = 0
End Enum
DPLWAIT_CANCEL
메소드는, 어플리케이션을 대기 모드로부터 해제한다.
DPLWAIT_DEFAULT
메소드는, 어플리케이션을 대기 모드로 설정한다.


CONST_DPMESSAGEQUEUEFLAGS

CONST_DPMESSAGEQUEUEFLAGS 열거형의 멤버는,DirectPlay4.GetMessageQueue 메소드로 사용된다.

Enum CONST_DPMESSAGEQUEUEFLAGS
    DPMESSAGEQUEUE_RECEIVE = 2
    DPMESSAGEQUEUE_SEND =    1
End Enum
DPMESSAGEQUEUE_RECEIVE
수신 큐에 관한 메세지를 취득한다.
DPMESSAGEQUEUE_SEND
송신 큐에 관한 메세지를 취득한다.


CONST_DPOPENFLAGS

CONST_DOPENFLAGS 열거형의 멤버는, 세션을 여는 방법을 지정하기 위해서,DirectPlay4.Open 메소드와 DirectPlay4.SecureOpen 메소드로 사용된다.

Enum CONST_DOPENFLAGS
    DPOPEN_CREATE =         2
    DPOPEN_JOIN =           1
    DPOPEN_RETURNSTATUS = 128 (&H80)
End Enum
DPOPEN_CREATE
어플리케이션 세션의 새로운 인스턴스를 생성 한다. 로컬 컴퓨터는, 세션의 네임서버- 및 호스트가 된다.
DPOPEN_JOIN
어플리케이션 세션의 기존의 인스턴스에 참가한다. 어플리케이션에서는, 플레이어를 생성 해, 메세지를 송수신 할 수 있게 된다. DPOPEN_CREATE 와 조합해 사용할 수 없다.
DPOPEN_RETURNSTATUS
이 플래그를 지정 하면, 접속의 진행 상황을 나타내는 다이알로그 박스가 표시되지 않는다. 접속을 즉시 확립할 수 없는 경우는, 메소드가 DPERR_CONNECTING 에러와 함께 즉시 돌아온다. 어플리케이션에서는, 메소드가 성공하는지, 또는 다른 에러 코드가 돌려주어질 때까지, 메소드를 계속 호출할 필요가 있다.


CONST_DPPLAYERFLAGS

CONST_DPPLAYERFLAGS 열거형의 멤버는,DirectPlay4.CreatePlayer 메소드로 플레이어가 할당할 수 있어DirectPlay4.GetPlayerFlags 를 사용해 취득할 수가 있다.

Enum CONST_DPPLAYERFLAGS
    DPPLAYER_LOCAL          = 8
    DPPLAYER_SERVERPLAYER = 256 (&H100)
    DPPLAYER_SPECTATOR    = 512 (&H200)
End Enum
DPPLAYER_LOCAL
플레이어는, 이 어플리케이션에 의해 생성 되었다. 이 플래그를 지정하지 않는 경우, 플레이어는 리모트 플레이어이다.
DPPLAYER_SERVERPLAYER
플레이어는, 클라이언트/서버 통신의 서버 플레이어이다.
DPPLAYER_SPECTATOR
플레이어는, 관객으로서 생성 되었다.


CONST_DPPLAYERTYPEFLAGS

CONST_DPPLAYERTYPEFLAGS 열거형의 멤버는, 항목이 플레이어 또는 그룹의 어느 쪽에 속하는지를 나타내기 위해서(때문에),DirectPlayEnumPlayers 오브젝트와 다양한 시스템 메세지로 사용된다.

Enum CONST_DPPLAYERTYPEFLAGS
    DPPLAYERTYPE_GROUP =  0
    DPPLAYERTYPE_PLAYER = 1
End Enum
DPPLAYERTYPE_GROUP
항목은, 그룹에 속한다.
DPPLAYERTYPE_PLAYER
항목은, 플레이어에 속한다.


CONST_DPRECEIVEFLAGS

CONST_DPRECEIVEFLAGS 열거형의 멤버는, 취득하는 메세지의 종류와 취득 방법을 지정하기 위해서 사용된다.

Enum CONST_DPRECEIVEFLAGS
    DPRECEIVE_ALL =        1
    DPRECEIVE_FROMPLAYER = 4
    DPRECEIVE_PEEK =       8
    DPRECEIVE_TOPLAYER =   2
End Enum

이러한 값의 의미에 대해서는,DirectPlay4.Receive 를 참조할것.


CONST_DPSENDFLAGS

CONST_DPSENDFLAGS 열거형의 멤버는, 메세지의 송신 방법을 제어하기 위해서 사용된다.

Enum CONST_DPSENDFLAGS
    DPSEND_ASYNC =              512 (&H200)
    DPSEND_DEFAULT =              0
    DPSEND_ENCRYPTED =           64 (&H40)
    DPSEND_GUARANTEED =           1
    DPSEND_NOSENDCOMPLETEMSG = 1024 (&H400)
    DPSEND_SIGNED =              32 (&H20)
End Enum

이러한 값의 의미에 대해서는, 「DirectPlay4.Send 」 및 「DirectPlay4.SendEx 」를 참조할것.


CONST_DPSESSIONFLAGS

CONST_DPSESSIONFLAGS 열거형의 멤버는, 세션의 특성을 기술하기 위해서 사용된다.

Enum CONST_DPSESSIONFLAGS
    DPSESSION_CLIENTSERVER       = 4096 (&H1000)
    DPSESSION_DIRECTPLAYPROTOCOL = 8192 (&H2000)
    DPSESSION_JOINDISABLED         = 32 (&H20)
    DPSESSION_KEEPALIVE            = 64 (&H40)
    DPSESSION_MIGRATEHOST           = 4
    DPSESSION_MULTICASTSERVER    = 2048 (&H800)
    DPSESSION_NEWPLAYERSDISABLED    = 1
    DPSESSION_NODATAMESSAGES      = 128 (&H80)
    DPSESSION_NOMESSAGEID           = 8
    DPSESSION_NOPRESERVEORDER   = 16384 (&H4000)
    DPSESSION_OPTIMIZELATENCY   = 32768 (&H8000)
    DPSESSION_PASSWORDREQUIRED   = 1024 (&H400)
    DPSESSION_PRIVATE             = 512 (&H200)
    DPSESSION_SECURESERVER        = 256 (&H100)
End Enum
DPSESSION_CLIENTSERVER
어플리케이션-서버 프로세스에 의해 호스트 되는, 클라이언트/서버 세션이다. 이 플래그는, 세션의 생성시로 지정할 필요가 있다. 서버 플레이어와 임의의 로컬 플레이어를 열거할 수 있는 것은, 이 세션에 참가하는 클라이언트 뿐이다. 세션의 호스트는, 모든 플레이어를 인식할 수 있다. 이 플래그를 설정하지 않는 경우, 세션은 피어 투 피어 세션이다. 이 플래그를 설정했을 경우, 서버 플레이어를 생성 할 수 있는 것은 호스트 뿐이다. 이 플래그는, DPSESSION_MIGRATEHOST 와 함께 사용할 수 없다.
DPSESSION_DIRECTPLAYPROTOCOL
이 세션에서는, 서비스 프로바이더에 의해 이행 된 프로토콜은 아니고, DirectPlay 의 보증 첨부 프로토콜을 사용할 필요가 있다. 메세지 쓰로틀링 ( 및 거기에 따른 퍼포먼스의 향상)이 필요한 경우는, 이 플래그를 사용한다.
DPSESSION_JOINDISABLED
새로운 어플리케이션은, 이 세션에 참가할 수 없다. DPOPEN_JOIN 플래그와 이 세션 인스턴스의 글로벌 유니크 식별자 (GUID)를 설정해 DirectPlay4.Open 메소드를 호출하면, 에러가 발생한다. 이 플래그를 지정하지 않는 경우, 새로운 리모트 어플리케이션은, 세션에 있어서의 플레이어의 한도에 이를 때까지, 그 세션에 참가할 수 있다.
DPSESSION_KEEPALIVE
이 세션은, 리모트 플레이어가 게임으로부터 부정하게 퇴출 한 것을, 자동적으로 검출한다. 이러한 플레이어는, 세션으로부터 삭제된다. 네트워크의 일시적인 장해에 의해 플레이어가 없어졌을 경우, 그 플레이어가 돌아왔을 때에,DPSYS_SESSIONLOST 시스템 메세지에 의해, 세션으로부터 빠진 것을 알게 된다. 이 플래그는, 세션의 생성시로 지정할 필요가 있다. 이 플래그를 설정하지 않는 경우, DirectPlay 는, 플레이어가 부정하게 종료했을 때에, 세션을 자동적으로는 유지하지 않는다.
DPSESSION_MIGRATEHOST
현재의 호스트가 세션을 빠지면(자), 세션내의 다른 컴퓨터가 호스트가 된다. 새로운 호스트 컴퓨터 위에의 플레이어는,DPSYS_HOST 시스템 메세지를 수신한다. 이 플래그는, 세션의 생성시로 지정할 필요가 있다. 이 플래그를 지정하지 않는 경우, 현재의 호스트가 세션을 떨어지면(자), 호스트는 이행 되지 않고, 새로운 컴퓨터는 세션에 참가하지 못하고, 새로운 플레이어를 생성 하는 일도 할 수 없게 된다. DPSESSION_MIGRATEHOST 플래그는, DPSESSION_CLIENTSERVER 플래그, DPSESSION_MULTICASTSERVER 플래그, 또는 DPSESSION_SECURESERVER 플래그와 조합해 사용할 수 없다.
DPSESSION_MULTICASTSERVER
피어 투 피어 세션에서는, 브로드캐스트라고 그룹 메세지가, 멀티 캐스트 서버와 같이 기능하는 호스트를 개입시켜 송신된다. 이 플래그는, 세션의 생성시로 지정할 필요가 있다. 이 플래그는, 호스트가 네트워크에 높은 대역폭으로 접속하고 있는 경우에게만, 유효하다. 이 플래그를 지정하지 않는 경우, 브로드캐스트라고 그룹 메세지는, 노드간에 직접 송신된다. 이 플래그는, DPSESSION_MIGRATEHOST 와 함께 사용할 수 없다.
DPSESSION_NEWPLAYERSDISABLED
세션내에서 새로운 플레이어를 생성 할 수 없다. 세션내의 어플리케이션이 DirectPlay4.CreatePlayer 메소드를 호출하면, 에러가 발생한다. 또, 새로운 어플리케이션이 세션에 참가하는 일도 할 수 없다. 이 플래그를 설정하지 않는 경우는, 세션에 있어서의 플레이어의 한도에 이를 때까지, 플레이어를 생성 할 수가 있다.
DPSESSION_NODATAMESSAGES
이 세션은, 리모트 플레이어 데이터, 그룹 데이터, 또는 세션 데이터가,DirectPlay4.SetPlayerData 메소드,DirectPlay4.SetGroupData 메소드,DirectPlay4.SetPlayerName 메소드,DirectPlay4.SetGroupName 메소드, 또는 DirectPlay4.SetSessionDesc 메소드의 어느 쪽인가에보다 변경되었을 경우에, 시스템 메세지를 송신하지 않는다. 이 플래그를 지정하지 않는 경우는, 데이터의 변경을 나타내는 메세지가 생성된다.

이 플래그를 설정 하면,DPSYS_SETSESSIONDESC 시스템 메세지도 생략 된다.

DPSESSION_NOMESSAGEID
세션이, 메세지를 발신한 플레이어와 메세지가 송신되는 플레이어를 나타내는 데이터를 메세지에 첨부하지 않는 것을 지정한다. 이 플래그를 설정 하면, 이 메세지가 관계가 없는 것으로 있는 경우에, 메세지의 오버헤드를 막을 수가 있다. 이 플래그를 지정하지 않는 경우, 메세지 ID 가 추가되는 이 플래그는, 세션의 생성시로 지정할 필요가 있다.
DPSESSION_NOPRESERVEORDER
이 세션이, 보증 첨부의 메세지의 수신 순서를 보존하지 않는 것을 지정한다. 디폴트에서는, 보증 메세지의 수신 순서는 보존된다. 이 순서가 불필요한 경우는, 이 플래그를 사용해, 전달의 지연을 막을 수가 있다.
DPSESSION_OPTIMIZELATENCY
서비스 프로바이더에,지연 시간에 대해서 최적화하도록(듯이) 요구한다 (이것에 의해, TCP/IP 의나그링이 오프가 된다). 디폴트에서는, 대역폭에 대해서 최적화한다.
DPSESSION_PASSWORDREQUIRED
이 세션이, 패스워드로 보호되고 있는 것을 지정한다. 이 세션에 참가하는 어플리케이션은,DirectPlay4.Open 의 호출로 패스워드를 제공할 필요가 있다. 이 플래그는, 읽기 전용이다. 세션의 호스트가 패스워드를 지정 하면, 자동적으로 설정된다.
DPSESSION_PRIVATE
세션이, Private 세션인 것을 지정한다. 요구에, NULL 이외의 일치하는 패스워드가 포함되어 있는 경우를 제외해, 열거 요구에 응답할 수 없다. 이 플래그를 지정하지 않는 경우, 세션은 열거 요구에 응답한다.
DPSESSION_SECURESERVER
이 세션이, 열기 전에 인증 정보를 요구하는 보증 서버상에서 호스트 되고 있는 것을 지정한다. 호스트는, 세션의 생성시에, 이 플래그를 지정할 필요가 있다. 이 플래그는, 다음에 DirectPlay4.SetSessionDesc 에 의해 변경할 수 없다. 또, DPSESSION_MIGRATEHOST 와 조합해 사용할 수 없다.

주의

이하의 플래그는, 세션의 시작 후에는 변경할 수 없다.

DPSESSION_CLIENTSERVER
DPSESSION_DIRECTPLAYPROTOCOL
DPSESSION_KEEPALIVE
DPSESSION_MIGRATEHOST
DPSESSION_MULTICASTSERVER
DPSESSION_NOMESSAGEID
DPSESSION_OPTIMIZELATENCY
DPSESSION_SECURESERVER

이하의 플래그는,DirectPlay4.SetSessionDesc 를 사용해 설정할 수 있다. 다만, 그것이 생기는 것은 호스트 뿐이다.

DPSESSION_JOINDISABLED
DPSESSION_NEWPLAYERSDISABLED
DPSESSION_NODATAMESSAGES
DPSESSION_NOPRESERVEORDER
DPSESSION_PASSWORDREQUIRED
DPSESSION_PRIVATE


CONST_DPSETFLAGS

CONST_DPSETFLAGS 열거형의 멤버는,DirectPlay4.SetGroupData 메소드,DirectPlay4.SetGroupName 메소드,DirectPlay4.SetPlayerData 메소드, 및 DirectPlay4.SetPlayerName 메소드에 의해 설정되는 데이터를 결정하기 위해서(때문에) 사용된다.

Enum CONST_DPSETFLAGS
    DPSET_GUARANTEED = 2
    DPSET_LOCAL = 1
    DPSET_REMOTE = 0
End Enum
DPSET_GUARANTEED
보증 메시징을 사용해 (이용 가능한 경우), 데이터를 전승한다. 이 플래그는, DPSET_LOCAL 와 조합해 사용할 수 없다.
DPSET_LOCAL
이 데이터는, 로컬 밖에 사용하지 못하고, 전승되지 않는다.
DPSET_REMOTE
이 데이터는, 모든 어플리케이션을 이용할 수 있어 세션내외의 모든 어플리케이션에 전승된다. 이 플래그는, 그룹에 대해서는, 로컬 세션에 의해 소유되고 있는 그룹 에 대해서만 사용할 수 있다.

참조

CONST_DPGETFLAGS


CONST_DPSYSMSGTYPES

CONST_DPSYSMSGTYPES 열거형의 멤버는, 시스템 메세지라고 로비 메세지가 다른 종류를 식별하기 위해서 이용된다. 시스템 메세지 또는 로비 메세지를 나타내는 각 DirectPlayMessage 오브젝트는,DirectPlayMessage.ReadLong 의 최초의 호출로부터, 이러한 정수의 어느쪽이든을 돌려준다. 메세지의 종류를 판단해,DirectPlayMessage 의 다양한 읽기 메소드를 호출해 데이터를 해석하는 것은, 어플리케이션의 역할이다

DPLSYS_GETPROPERTY 및 DPLSYS_SETPROPERTY 의 2 살의 로비 메세지는, 시스템은 아니고, 어플리케이션에 의해 송신된다. 어플리케이션에서는,DirectPlayMessage 의 적절한 쓰기 메소드를 사용해, 타입 식별자와 관리하는 나머지의 데이터를 기술할 필요가 있다.

어플리케이션에서는, 보통의 시스템 메세지라고 로비 메세지를 나누어 취급하는 것이 중요하다. 일부의 로비 메세지와 비로비 메세지는, 같은 값을 공유한다 (DPLSYS_SETPROPERTY 와 DPSYS_DESTROYPLAYERORGROUP 등). 따라서, 메세지가 로비 메세지나 비로비 메세지인지를 나타내는 정보를 사용하지 않고 , 모든 메세지를 공통의 핸들러에 보내는 것은 현명하지 않다.

Enum CONST_DPSYSMSGTYPES
    DPLSYS_APPTERMINATED =          4
    DPLSYS_CONNECTIONSETTINGSREAD = 1
    DPLSYS_DPLAYCONNECTFAILED =     2
    DPLSYS_DPLAYCONNECTSUCCEEDED =  3
    DPLSYS_GETPROPERTY =            7
    DPLSYS_GETPROPERTYRESPONSE =    8
    DPLSYS_NEWCONNECTIONSETTINGS = 10
    DPLSYS_NEWSESSIONHOST =         9
    DPLSYS_SETPROPERTY =            5
    DPLSYS_SETPROPERTYRESPONSE  =   6
    DPSYS_ADDGROUPTOGROUP =       261 (&H105)
    DPSYS_ADDPLAYERTOGROUP =        7
    DPSYS_CHAT =                  265 (&H109)
    DPSYS_CREATEPLAYERORGROUP =     3
    DPSYS_DELETEGROUPFROMGROUP =  262 (&H106)
    DPSYS_DELETEPLAYERFROMGROUP =  33 (&H21)
    DPSYS_DESTROYPLAYERORGROUP =    5
    DPSYS_HOST =                  257 (&H101)
    DPSYS_SECUREMESSAGE =         263 (&H107)
    DPSYS_SENDCOMPLETE =          269 (&H10D)
    DPSYS_SESSIONLOST =            49 (&H31)
    DPSYS_SETGROUPOWNER =         266 (&H10A)
    DPSYS_SETPLAYERORGROUPDATA =  258 (&H102)
    DPSYS_SETPLAYERORGROUPNAME =  259 (&H103)
    DPSYS_SETSESSIONDESC =        260 (&H104)
    DPSYS_STARTSESSION =          264 (&H108)
End Enum

이하의 기술에는, 각 메세지 타입의 여분의 데이터 멤버의 리스트가 포함되어 있다. 이것들은, 기본으로 되는 구조체로 사용되는 차례로 쓰여져 있다 (기본으로 되는 C/C++ 구조체의 상세한 것에 대하여는, 「시스템 메세지」를 참조할것). 여기에서는, 어플리케이션이 ReadLong 를 사용해, 이미 메세지 타입을 취득한 것과 가정하고 있다.

메세지 데이터가 Long 형의 값과 거기에 계속되는 GUID 로 구성되어 있는 경우, 어플리케이션에서는, 최초로 DirectPlayMessage.ReadLong 를 호출해, 다음에 DirectPlayMessage.ReadString 를 호출해, 데이터를 해석할 수가 있다. 기본으로 되는 구조체에 버퍼에의 포인터가 포함되어 있는 경우,DirectPlayMessage.ReadSysChatString 등이 특별한 메소드를 사용해, 버퍼로부터 데이터를 취득할 필요가 있다.

표준 로비 메세지
DPLSYS_APPTERMINATED
DirectPlayLobby3.RunApplication 에 의해 시작 된 어플리케이션이 종료했다.
GUID
로비 메세지를 적용하는 세션의 일의의 식별자.
DPLSYS_CONNECTIONSETTINGSREAD
DirectPlayLobby3.RunApplication 에 의해 시작 된 어플리케이션이, 접속 설정을 읽어냈다.
GUID
로비 메세지를 적용하는 세션의 일의의 식별자.
DPLSYS_DPLAYCONNECTFAILED
DirectPlayLobby3.RunApplication 에 의해 시작 된 어플리케이션이, 세션에의 접속에 실패했다.
GUID
로비 메세지를 적용하는 세션의 일의의 식별자.
DPLSYS_DPLAYCONNECTSUCCEEDED
DirectPlayLobby3.RunApplication 에 의해 시작 된 어플리케이션이, 세션을 생성 해 다른 어플리케이션의 참가를 대기하고 있는지, 또는 세션에의 참가에 성공했다.
GUID
로비 메세지를 적용하는 세션의 일의의 식별자.
DPLSYS_GETPROPERTY
어플리케이션으로부터 로비에 대해, 프로퍼티의 현재의 값을 요구하기 위해서 송신되는 메세지.
Long
요구를 식별하는 어플리케이션에 의해 생성되는 ID. 로비의 응답은, 이 ID 에 송신된다. 어플리케이션에서는, 이 요구 ID 를 사용해, 응답을 보류중의 요구에 일치시킬 수가 있다.
GUID
이 프로퍼티가 적용되는 플레이어의 일의인 식별자 (적용되는 경우). 이 프로퍼티가 플레이어에게 고유의 것이 아닌 경우, 이 멤버에는 하늘의 캐릭터 라인을 설정할 필요가 있다.
GUID
요구되고 있는 프로퍼티의 일의인 식별자. DirectPlay 는, 특정의 프로퍼티를 정의한다. 어플리케이션 또는 로비는, 추가의 프로퍼티에 대한 독자적인 GUID 를 정의할 수가 있다. 상세한 것에 대하여는, DirectPlay C++ 레퍼런스의 「DirectPlay 정의가 끝난 프로퍼티」를 참조할것.
DPLSYS_GETPROPERTYRESPONSE
DPLSYS_GETPROPERTY 메세지에 응답해, 로비로부터 어플리케이션에 송신되는 메세지.
Long
응답하고 있는 요구의 ID.
GUID
이 프로퍼티가 적용되는 플레이어의 일의인 식별자. 이 프로퍼티가 플레이어에게 고유의 것이 아닌 경우는, 이 멤버에는 하늘의 캐릭터 라인을 설정한다. 이 값은, DPLSYS_GETPROPERTY 메세지로 건네받은 값과 같다.
GUID
요구되고 있는 프로퍼티의 일의인 식별자. 이 값은, DPLSYS_GETPROPERTY 메세지로 건네받은 값과 같다.
Long
프로퍼티를 취득하는 요구에 대한 귀가 코드. 요구가 성공했을 경우는 0, 그 이외의 경우는

DPERR_UNKNOWNMESSAGE 또는

DPERR_UNAVAILABLE 의 어느 쪽인가에 된다.

Long
데이터의 사이즈를 나타내는 바이트수. 이 값의 뒤에, 프로퍼티 데이터를 포함한 가변 사이즈의 버퍼가 계속된다. 이 프로퍼티 태그에 의해, 이 데이터의 읽기 방법과 해석 방법이 정해진다. 상세한 것에 대하여는, DirectPlay C++ 레퍼런스의 「DirectPlay 정의가 끝난 프로퍼티」를 참조할것.
DPLSYS_NEWCONNECTIONSETTINGS
로비 시스템 메세지. 로비 클라이언트가 DirectPlayLobby3.RunApplication 를 호출하면, 대기중의 어플리케이션이 발견된다. 대기중의 어플리케이션은,DirectPlayLobby3.GetConnectionSettings 를 사용해, 접속 설정을 읽어낼 수가 있다.
GUID
로비 메세지를 적용하는 세션의 일의의 식별자.
DPLSYS_NEWSESSIONHOST
로비로부터, 새롭게 세션의 호스트가 된 어플리케이션 인스턴스에 송신되는 메세지.
GUID
이 인스턴스의, 일의인 식별자.
DPLSYS_SETPROPERTY
프로퍼티의 값을 설정하기 위해서, 어플리케이션으로부터 로비로 송신되는 메세지.
Long
요구를 식별하는, 어플리케이션에 의해 생성되는 ID. 로비의 응답은, 이 ID 에 송신된다. 어플리케이션에서는, 이 요구 ID 를 사용해, 응답을 보류중의 요구에 일치시킬 수가 있다.
GUID
이 프로퍼티가 적용되는 플레이어의 일의인 식별자. 이 프로퍼티가 플레이어에게 고유의 것이 아닌 경우는, 이 멤버에는 하늘의 캐릭터 라인을 설정한다.
GUID
요구되고 있는 프로퍼티의 일의인 식별자. DirectPlay 는, 특정의 프로퍼티를 정의한다. 어플리케이션 또는 로비는, 추가의 프로퍼티에 대한 독자적인 GUID 를 정의할 수가 있다.
Long
데이터의 사이즈를 나타내는 바이트. 이 값의 뒤에, 프로퍼티 데이터를 포함한 가변 사이즈의 버퍼가 계속된다. 이 프로퍼티 태그에 의해, 이 데이터의 정리 방법과 쓰기 방법이 정해진다. 예를 들어, DPLPROPERTY_PlayerScore 프로퍼티의 경우는,DirectPlayMessage.WriteLong 를 1 회 호출해 스코아의 수를 기록해, 각 스코아에 대해서 이 메소드를 재차 호출한다. 상세한 것에 대하여는, DirectPlay C++ 레퍼런스의 「DirectPlay 정의가 끝난 프로퍼티」를 참조할것.
DPLSYS_SETPROPERTYRESPONSE
DPLSYS_SETPROPERTY 메세지에 응답해, 로비로부터 어플리케이션에 송신되는 메세지.
Long
응답하고 있는 요구의 ID.
GUID
이 프로퍼티가 적용되는 플레이어의 일의인 식별자 (적용되는 경우). 이 프로퍼티가 플레이어에게 고유의 것이 아닌 경우, 이 멤버에는 하늘의 캐릭터 라인을 설정한다. 이 값은, DPLSYS_SETPROPERTY 메세지로 건네받은 값과 같다.
GUID
요구되고 있는 프로퍼티의 일의인 식별자. 이 값은, DPLSYS_SETPROPERTY 메세지로 건네받은 값과 같다.
Long
프로퍼티를 설정하는 요구에 대한 귀가 코드. 요구가 성공했을 경우는 0, 그 이외의 경우는 DPERR_ACCESSDENIED 또는

DPERR_UNKNOWNMESSAGE 의 어느 쪽인가에 된다.

비로비 시스템 메세지
DPSYS_ADDGROUPTOGROUP
그룹이 그룹에 추가되었다.
Long
그룹이 추가된 그룹의 ID.
Long
그룹에 추가된 그룹의 ID.
DPSYS_ADDPLAYERTOGROUP
플레이어가 그룹에 추가되었다.
Long
플레이어가 추가된 그룹의 ID.
Long
그룹에 추가된 플레이어의 ID.
DPSYS_CHAT
메세지는, 로비를 개입시켜 전송 되는 채팅 캐릭터 라인이다.
Long
플래그. 항상 0.
Long
메세지를 발신한 플레이어의 ID. DPID_SERVERPLAYER 는, 메세지가 서버로부터 발신된 것을 나타낸다.
Long
메세지가 송신된 플레이어의 ID. 이 ID 가 0 의 경우, 메세지는 그룹에 송신되었는지, 전원에게 브로드캐스트 되었다.
Long
메세지가 송신된 그룹의 ID. 이 ID 가 0 으로, 직전의 Long 도 0 의 경우, 메세지는 전원에게 브로드캐스트 되었다.
Long
채팅 캐릭터 라인에의 포인터. 이 캐릭터 라인을 읽어내려면 ,DirectPlayMessage.ReadSysChatString 메소드를 사용한다.
DPSYS_CREATEPLAYERORGROUP
플레이어 또는 그룹이 생성 되었다.
Long
플레이어 (DPPLAYERTYPE_PLAYER) 또는 그룹 (DPPLAYERTYPE_GROUP)의 어느 쪽이 생성 되었는지를 나타내는 플래그.
Long
생성 된 플레이어 또는 그룹의 ID.
Long
세션내의 플레이어의 수.
Long (2)
그룹에 대한 로컬 데이터를 포함한 버퍼에의 포인터와 그 사이즈. 이 버퍼의 내용을 취득하려면 ,DirectPlayMessage.ReadSysMsgData 메소드를 사용한다.
Long (2)
그룹에 대한 리모트 데이터를 포함한 버퍼에의 포인터와 그 사이즈. 이 버퍼의 내용을 취득하려면 ,ReadSysMsgData 를 사용한다.
Long
기본으로 되는 이름 구조체의 사이즈를 바이트로 가리킨다. 무시할 수 있다.
Long
이름 구조체에 대한 플래그. 항상 0.
String
그룹의 쇼트 네임.
String
그룹의 롱 네임.
Long
그룹이 DirectPlay4.CreateGroupInGroup 의 호출에 의해 생성 되었을 경우는, 친그룹의 ID. 그 이외의 경우는 0.
Long
플레이어 또는 그룹의 플래그. 0 또는 DPGROUP_HIDDEN 가 된다 ( 「CONST_DPGROUPFLAGS 」를 참조).
DPSYS_DELETEGROUPFROMGROUP
그룹으로부터 그룹이 삭제되었다.
Long
그룹이 삭제된 그룹의 ID.
Long
삭제된 그룹의 ID.
DPSYS_DELETEPLAYERFROMGROUP
그룹으로부터 플레이어가 삭제되었다.
Long
플레이어가 삭제된 그룹의 ID.
Long
삭제된 플레이어의 ID.
DPSYS_DESTROYPLAYERORGROUP
플레이어 또는 그룹이 파기되었다.
Long
플레이어 (DPPLAYERTYPE_PLAYER) 또는 그룹 (DPPLAYERTYPE_GROUP)의 어느 쪽이 파기되었는지를 나타내는 플래그.
Long
파기된 플레이어 또는 그룹의 ID.
Long (2)
그룹에 대한 로컬 데이터를 포함한 버퍼에의 포인터와 그 사이즈. 이 버퍼의 내용을 취득하려면 ,DirectPlayMessage.ReadSysMsgData 메소드를 사용한다.
Long (2)
그룹에 대한 리모트 데이터를 포함한 버퍼에의 포인터와 그 사이즈. 이 버퍼의 내용을 취득하려면 ,ReadSysMsgData 를 사용한다.
Long
기본으로 되는 이름 구조체의 사이즈를 바이트로 가리킨다. 무시할 수 있다.
Long
이름 구조체에 대한 플래그. 항상 0.
String
그룹의 쇼트 네임.
String
그룹의 롱 네임.
Long
파기되고 있는 그룹이 친그룹의 서브 그룹인 경우, 즉, 파기되고 있는 그룹이 DirectPlay4.CreateGroupInGroup 의 호출에 의해 생성 된 것인 경우는, 친그룹의 ID. 그 이외의 경우는 0.
Long
플레이어 또는 그룹의 플래그. CONST_DPGROUPFLAGS 열거형의 이하의 몇개의 값을 포함할 수가 있다.

DPGROUP_HIDDEN

숨은 그룹이 파기되었을 때에 설정된다.

DPGROUP_STAGINGAREA

staging 영역인 그룹이 파기되었을 때에 설정된다.

DPPLAYER_SERVERPLAYER

파기되고 있는 플레이어가 클라이언트/서버 통신의 서버 플레이어인 경우로 설정된다.

DPPLAYER_SPECTATOR

파기되고 있는 플레이어가 관객인 경우로 설정된다.

DPSYS_HOST
메세지를 수신하고 있는 플레이어는, 세션의호스트이다. 이 메세지는, 그 이상의 데이터를 포함하지 않았다.
DPSYS_SECUREMESSAGE
다른 플레이어가 서명 붙어 또는 암호화된 메세지를 수신했다.
Long
송신자에 의한 메세지의 보증 방법을 나타내는 플래그. CONST_DPSENDFLAGS 열거형의 이하의 몇개의 값이 된다.

DPSEND_SIGNED

메세지는 송신자에 의해 서명되어 그 서명은 올바른 것으로 있다고 확인되었다.

DPSEND_ENCRYPTED

메세지는 송신자에 의해 암호화되어 올바르고 복호화 되었다.

Long
메세지를 송신한 플레이어의 ID.

복호화 된 메세지를 읽어내려면 ,DirectPlayMessage.MoveToSecureMessage 메소드를 사용해, 읽기 포인터를 데이터 버퍼의 시작 부분으로 이동한다. 데이터를 읽어내려면 ,DirectPlayMessage 의 표준의 읽기 메소드를 사용한다.

DPSYS_SENDCOMPLETE
비동기 송신의 완료 상태를 통지하기 위해서, 어플리케이션에 송신되는 메세지. 이 메세지는, 디폴트에서는,DirectPlay4.SendEx 로 DPSEND_ASYNC 플래그를 사용해 비동기 메세지가 송신될 때마다, 생성된다.
Long
메세지를 송신한 플레이어의 ID.
Long
메세지가 송신된 플레이어의 ID.
Long
메세지가 송신되었을 때에,SendEx 로 지정된 플래그.
Long
메세지의 송신시의 우선 순위.
Long
메세지가 송신되었을 때에,SendEx 로 지정된 타임 아웃. 0 은, 디폴트의 타임 아웃을 나타낸다.
Long
어플리케이션으로부터 SendEx 에 제공된 context 파라미터.
Long
SendEx 에 의해 어플리케이션에 돌려주어진 메세지 ID.
Long
비동기 메세지의 결과. 메세지가 올바르게 송신되었을 경우는 0, 그 이외의 경우는, 이하의 몇개의 에러 코드가 된다.

DPERR_ABORTED

메세지는, 전송중에 캔슬되었다.

DPERR_CANCELLED

메세지는, 송신 큐내에서 캔슬되었다.

DPERR_GENERIC

메세지를 송신할 수 없었다.

DPERR_TIMEOUT

메세지는 타임 아웃이 되어, 송신 큐로부터 삭제되었다.

Long
어플리케이션에 의해 메세지가 송신되고 나서, DirectPlay 가 그 메세지를 송신했을 때까지의 경과시간을 밀리 세컨드로 가리킨다. 이것에는, 송신 큐내에서 소비한 시간이라고 메세지를 서비스 프로바이더에 건네주기까지 소비한 시간이 포함된다. 보증 첨부의 메세지의 경우는, 메세지의 전달의 확인에 필요로 한 시간도 포함된다.
DPSYS_SESSIONLOST
다른 모든 플레이어에게로의 접속이 없어졌다. 세션이 없어지면(자), 리모트 플레이어에게 메세지를 송신할 수 없지만, 세션이 없어졌을 때의 데이터는 여전히 모두 이용 가능하다. 어플리케이션으로 이 메세지를 수신했을 경우는, 신속하게 복원해, 종료할 필요가 있다. 이 메세지에는, 더 이상의 데이터는 없다.
DPSYS_SETGROUPOWNER
그룹의 소유자가 변경했다. 그룹의 소유권은, 세션을 떨어지는 현재의 소유자가 DirectPlay4.SetGroupOwner 를 호출해 변경하는지, 또는 로비 세션내의 로비 서버가 변경할 수가 있다.
Long
소유자가 변경한 그룹의 ID.
Long
그룹의 새로운 소유자의 플레이어 ID.
Long
그룹의 낡은 소유자의 플레이어 ID.
DPSYS_SETPLAYERORGROUPDATA
DirectPlay 는, 플레이어 또는 그룹의 리모트 데이터가 변경되었을 때에, 이 메세지를 생성해, 각 플레이어에게 송신한다. 세션 기술로 DPSESSION_NODATAMESSAGES 플래그가 설정되어 있는 경우는, 이 메세지는 생성되지 않는다.
Long
메세지가 플레이어 (DPPLAYERTYPE_PLAYER) 또는 그룹 (DPPLAYERTYPE_GROUP)의 어느 쪽으로 적용되는지를 나타낸다.
Long
데이터가 변경된 플레이어 또는 그룹의 ID.
Long (2)
어플리케이션에 고유의 데이터를 포함한 버퍼에의 포인터와 그 사이즈. 이 버퍼의 내용을 취득하려면 ,DirectPlayMessage.ReadSysMsgData 메소드를 사용한다.
DPSYS_SETPLAYERORGROUPNAME
DirectPlay 는, 플레이어 또는 그룹의 이름이 변경되었을 때에, 이 메세지를 생성해, 컴퓨터 위에의 각 로컬 플레이어에게 송신한다. 세션 기술로 DPSESSION_NODATAMESSAGES 플래그가 설정되어 있는 경우는, 이 메세지는 생성되지 않는다.
Long
메세지가 플레이어 (DPPLAYERTYPE_PLAYER) 또는 그룹 (DPPLAYERTYPE_GROUP)의 어느 쪽으로 적용되는지를 나타낸다.
Long
이름이 변경된 플레이어 또는 그룹의 ID.
Long
기본으로 되는 이름 구조체의 사이즈. 무시할 수 있다.
Long
플래그. 항상 0.
String
플레이어 또는 그룹의 새로운 쇼트 네임.
String
플레이어 또는 그룹의 새로운 롱 네임.
DPSYS_SETSESSIONDESC
모든 플레이어는, 세션 기술이 변경되었을 때에, 이 메세지를 수신한다. 새로운 세션 기술을 취득하려면 ,DirectPlayMessage.ReadSysMsgSessionDesc 메소드를 사용한다.
DPSYS_STARTSESSION
로비 서버는, 그룹내의 각 플레이어가 어플리케이션 세션에 참가할 경우에, 그러한 플레이어에게 이 메세지를 송신한다. 접속 데이터를 취득하려면 ,DirectPlayMessage.ReadSysMsgConnection 메소드를 사용한다.


에러 코드

여기에서는, DirectPlay 클래스의 메소드에 의해 돌려주어지는 값을 기술한다. 각 메소드가 돌려주는 에러 코드의 일람에 대해서는, 각각의 메소드의 설명을 참조할것.

DirectPlay 의 에러 정수는,CONST_DPLAYERR 열거형의 멤버이다.

DP_OK
요구는 올바르게 완료했다.
DPERR_ABORTED
처리는, 완료하기 전에 캔슬되었다.
DPERR_ACCESSDENIED
세션이 정원에 이르고 있는지, 또는 부정한 패스워드가 지정되었다.
DPERR_ACTIVEPLAYERS
액티브한 플레이어가 이미 존재하기 위해(때문에), 요구된 처리를 실행할 수 없다.
DPERR_ALREADYINITIALIZED
오브젝트는 이미 초기화되고 있다.
DPERR_APPNOTSTARTED
어플리케이션은 아직 시작되어 있지 않다.
DPERR_AUTHENTICATIONFAILED
패스워드 또는 신원 증명을 인증할 수 없었다.
DPERR_BUFFERTOOLARGE
데이터 버퍼가 너무 커 저장 할 수 없다.
DPERR_BUFFERTOOSMALL
지정된 버퍼가 너무 작아, 요구된 데이터를 저장 할 수 없다.
DPERR_BUSY
전송 미디어가 Busy이기 (위해)때문에, 메세지를 송신할 수 없다.
DPERR_CANCELFAILED
메세지를 캔슬할 수 없었다. 아마 이 메세지는, 그룹내의 1 명 이상의 멤버에 이미 송신된 그룹 메세지이다.
DPERR_CANCELLED
처리가 캔슬되었다.
DPERR_CANNOTCREATESERVER
새로운 세션에 대한 서버를 생성 할 수 없다.
DPERR_CANTADDPLAYER
플레이어를 세션에 추가할 수 없다.
DPERR_CANTCREATEGROUP
새로운 그룹을 생성 할 수 없다.
DPERR_CANTCREATEPLAYER
새로운 플레이어를 생성 할 수 없다.
DPERR_CANTCREATEPROCESS
어플리케이션을 시작 할 수 없다.
DPERR_CANTCREATESESSION
새로운 세션을 생성 할 수 없다.
DPERR_CANTLOADCAPI
신원 정보가 제공되지 않고, 암호화 서비스에 사용하는 CryptoAPI 패키지 (CAPI)를 로드할 수 없다.
DPERR_CANTLOADSECURITYPACKAGE
소프트웨어 시큐러티 패키지를 로드할 수 없다.
DPERR_CANTLOADSSPI
신원 정보가 제공되지 않고, 신원 정보를 요구하는 Security Support Provider Interface (SSPI)를 로드할 수 없다.
DPERR_CAPSNOTAVAILABLEYET
DirectPlay 오브젝트의 능력이, 아직 결정되어 있지 않다. 이 에러는, DirectPlay 오브젝트가, 폴링에 의해 이용 가능한 대역폭과 지연 시간을 판단하는 접속 솔루션에 이행 되고 있는 경우에 발생한다.
DPERR_CONNECTING
메소드는 네트워크에의 접속 처리중이다. 어플리케이션에서는, 올바르게 완료한 것을 나타내는 DP_OK 인가, 또는 다른 에러가 돌려주어질 때까지, 이 메소드를 계속 사용할 필요가 있다.
DPERR_CONNECTIONLOST
데이터의 송신중에, 서비스 프로바이더의 접속이 리셋 되었다.
DPERR_ENCRYPTIONFAILED
요구된 정보를 암호화할 수 없었다. 암호화는, 메세지의 프라이버시를 보호하기 위해서 이용된다. 이 에러는, 보증 세션에서만 발생한다.
DPERR_EXCEPTION
요구를 처리하고 있을 때 예외가 발생했다.
DPERR_GENERIC
정의되어 있지 않은 에러 조건이 발생했다.
DPERR_INVALIDFLAGS
이 메소드에게 건네진 플래그는 무효이다.
DPERR_INVALIDGROUP
그룹 ID 가, 이 게임 세션에 대한 유효한 그룹 ID 로서 인식되어 있지 않다.
DPERR_INVALIDINTERFACE
인터페이스 파라미터가 무효이다.
DPERR_INVALIDOBJECT
DirectPlay 오브젝트가 무효이다.
DPERR_INVALIDPARAMS
메소드에게 건네진 1 개 이상의 파라미터가 무효이다.
DPERR_INVALIDPASSWORD
패스워드를 요구하는 세션에 참가할 경우에, 무효인 패스워드가 제공되었다.
DPERR_INVALIDPLAYER
플레이어 ID 가, 이 게임 세션에 대한 유효한 플레이어 ID 로서 인식되어 있지 않다.
DPERR_INVALIDPRIORITY
지정된 우선 순위가, 지정 가능한 범위내 (0 ~ 65535)는 아니다.
DPERR_LOGONDENIED
신원 증명이 요구되고 있는지, 신원 증명이 제시되지 않았는지, 또는 신원 증명이 무효였기 때문에, 세션을 열 수가 없었다.
DPERR_NOCAPS
DirectPlay 가 사용하는 통신 링크가, 이 함수에 대응하고 있지 않다.
DPERR_NOCONNECTION
통신 링크가 확립되어 있지 않다.
DPERR_NOINTERFACE
인터페이스가 지원되어 있지 않다.
DPERR_NOMESSAGES
수신 큐에 메세지가 존재하지 않는다.
DPERR_NONAMESERVERFOUND
네임서버- (호스트)가 발견되지 않는가, 또는 생성 할 수 없었다. 플레이어의 생성에는호스트가 필요하다.
DPERR_NONEWPLAYERS
세션이 새로운 플레이어를 받아들이지 않았다.
DPERR_NOPLAYERS
세션내에 액티브한 플레이어가 존재하지 않는다.
DPERR_NOSESSIONS
불려 간 메소드의 대상이 되는 세션이 존재하지 않는다.
DPERR_NOTLOBBIED
어플리케이션이 DirectPlayLobby3.RunApplication 메소드에 의해 시작되어 있지 않은 경우, 또는 이 DirectPlayLobby 오브젝트에 대해서 DirectPlayLobbyConnection 인터페이스가 현재 초기화되어 있지 않은 경우에,DirectPlayLobby3.Connect 메소드로부터 돌려주어진다.
DPERR_NOTLOGGEDIN
플레이어 또는 클라이언트 어플리케이션이 로그 온 하고 있지 않기 때문에, 동작을 실행할 수 없다. 클라이언트 어플리케이션이 로그 온 하지 않고 보증 메세지를 송신했을 때에,DirectPlay4.Send 메소드로부터 돌려주어진다.
DPERR_OUTOFMEMORY
요구된 처리를 실행하기 위해서 필요한 양의 메모리가 존재하지 않는다.
DPERR_PENDING
에러는 아니다. 비동기 송신이, 올바르게 큐에 넣어지는 포인트에 이른 것을 나타낸다. 상세한 것에 대하여는, 「SendEx 」를 참조할것.
DPERR_PLAYERLOST
플레이어가 세션에의 접속을 잃었다.
DPERR_SENDTOOBIG
DirectPlay4.Send 메소드에 의해 송신된 메세지가 너무 크다.
DPERR_SESSIONLOST
세션에의 접속이 없어졌다.
DPERR_SIGNFAILED
요구된 정보에 디지털 서명을 추가할 수 없다. 디지털 서명은, 메세지가 진짜인 것을 나타내기 위해서(때문에) 사용된다.
DPERR_TIMEOUT
지정된 시간내에 처리를 완료할 수 없었다.
DPERR_UNAVAILABLE
요구된 함수는 현재 이용할 수 없다.
DPERR_UNINITIALIZED
요구된 오브젝트가 초기화되어 있지 않다.
DPERR_UNKNOWNAPPLICATION
불명한 어플리케이션이 지정되었다.
DPERR_UNKNOWNMESSAGE
메세지 ID 가 유효하지 않다. 캔슬하는 메세지의 ID 가 무효인 경우에,DirectPlay4.CancelMessage 로부터 돌려주어진다.
DPERR_UNSUPPORTED
함수 또는 기능이, 이 이행 또는 서비스 프로바이더에서는 이용할 수 없다. 로비 세션이 아닌 세션으로부터 DirectPlay4.SetGroupConnectionSettings 메소드가 불려 갔을 경우에, 돌려주어진다. 또, 우선 순위 또는 타임 아웃이 설정되어 있어, 이러한 기능이 서비스 프로바이더에 의해 지원 되지 않고, DirectPlay 프로토콜이 온으로 되어 있지 않은 경우에,DirectPlay4.SendEx 로부터 돌려주어진다. 게다가 송신 큐를 체크해, 그것이 서비스 프로바이더에 의해 지원 되지 않고, DirectPlay 프로토콜이 온으로 되어 있지 않은 경우는,DirectPlay4.GetMessageQueue 로부터 돌려주어진다.
DPERR_USERCANCEL
유저가 DirectPlay4.Open 메소드의 호출중에 접속 처리를 캔슬했을 경우, 또는 유저가 DirectPlay4.GetDPEnumSessions 의 호출중에 DirectPlay 서비스 프로바이더의 다이알로그 박스로 [캔슬] 을 클릭했을 경우에 돌려주어진다.


DirectPlay 의 툴과 샘플

여기에서는, DirectX SDK 에 포함되어 있는 샘플 어플리케이션에 대해 설명한다. 이러한 어플리케이션은, DirectPlay 와 어플리케이션을 테스트하기 위해서 이용할 수 있는 툴의 사용법을 나타내고 있다. 설명은 다음과 같이 나뉘고 있다.

  • DirectPlay 툴
  • DirectPlay C++ 샘플
  • DirectPlay Visual Basic 샘플


DirectPlay 툴

다음의 툴을 사용 하면, C++ 또는 Visual Basic 로 기술된 DirectPlay 어플리케이션을 테스트할 수가 있다.

  • DirectPlay Simulator
  • 로비 서버


DirectPlay Simulator

설명

DirectPlay Simulator 툴은, 네트워크 어플리케이션의 견뢰성을 테스트하기 위한 의사 환경을 제공한다. 고속의 근거리 통신망상에서 저대역폭 또는 지연 시간의 긴 접속을 시뮬레이트 해, 임의 또는 프로그래밍 된 메세지 전송의 실패를 생성할 수가 있다.

패스

실행 가능 파일과 DLL: (SDK 루트)\Samples\Multimedia\DPlay\Bin

DPSimcfg.exe 는, 이 툴을 구성하기 위해서 사용된다. 툴의 기능은 DPSim.dll 에 포함되어 있다. 이 파일을 Windows 시스템 디렉토리에 카피할 필요가 있다.

유저즈 가이드

DPSimcfg.exe 는, DirectPlay Simulator 에 의해 사용되는 레지스트리 파라미터를 구성하기 위해서 이용된다. 또, 서비스 프로바이더의 레지스트리 엔트리를 추가 또는 삭제하는 것에 의해, DirectPlay Simulator 를 기동 또는 정지시킨다. DirectPlay Simulator 가 액티브한 때는, 그것을 서비스 프로바이더의 리스트로부터 선택할 수 있다. DirectPlay Simulator 는, TCP/IP 서비스 프로바이더상에 이행 된다.

이하의 조작 모드를 바꾸려면 , 화살표 버튼을 클릭한다.

  • 패킷을 드롭 하지 않는다.
  • n% 의 패킷을 임의에 드롭 한다. 퍼센티지는 슬라이더로 설정한다.
  • n 패킷 마다 1 개의 패킷을 드롭 한다. n 의 값은 슬라이더로 설정한다.
  • 패턴에 따라 패킷을 드롭 한다. 텍스트 박스에, 건네받는 패킷수, 드롭 하는 패킷수, 건네받는 패킷수 와 같이 일련의 숫자를 입력한다. 각각의 숫자는 칸마 또는 스페이스에서 단락짓는다. 일련의 숫자의 마지막에 달하면(자), 패턴이 반복해진다.

통신이 시작되고 나서 일정한 기간 (밀리 세컨드)이 경과할 때까지 패킷의 드롭이 발생하지 않게 지정하거나 일정한 기간 (밀리 세컨드)이 경과할 때까지 패킷의 드롭을 계속하도록(듯이) 지정할 수가 있다. 이러한 기간을 정의하려면 ,[Start After] 텍스트 박스와 [Stop After] 텍스트 박스에 값을 입력한다. [Stop After] 텍스트 박스의 값이 제로의 경우, 패킷의 드롭은 무한하게 실행된다.

메세지의 드롭을 확실히 실행하려면 ,[Drop Guaranteed] 체크 박스를 온으로 한다.

송신 메세지와 수신 메세지의 양쪽 모두에 지연 시간을 설정하려면 ,[Latency] 를 클릭한다. 슬라이더를 사용해, 지연 시간을 밀리 세컨드 단위로 설정한다. 각각의 지연 시간은,+/- 같은 배분으로 가변 레인지가 되어 있다.

주 : 슬라이더 컨트롤을 세세하게 조정하려면 , 슬라이더 컨트롤을 클릭해, 방향 키를 사용해 값을 증가 또는 감소시킨다.

지연 시간은 아니고, 시뮬레이트 하는 대역폭을 선택하려면 ,[Bandwidth] 를 클릭해 텍스트 박스에 baud rate를 입력하는지, 또는 화살표 버튼을 클릭해 baud rate를 선택한다.

[Activate] 를 클릭해, DirectPlay Simulator 를 서비스 프로바이더로서 이용할 수 있도록(듯이) 한다.


로비 서버

설명

로비 서버 어플리케이션은,로비 세션을 생성 해, 다른 컴퓨터를 사용하고 있는 유저가 Bellhop 샘플등의로비 클라이언트를 사용해 주어 잡기할 수 있도록(듯이) 한다.

패스

실행 가능 필: (SDK 루트)\Samples\Multimedia\DPlay\Bin\LServer.exe

유저즈 가이드

로비 서버를 디폴트 모드로 초기화하려면 ,[Server] 메뉴의 [Start] 를 클릭한다. 다음에, 로비 세션의 이름을 입력한다. 로비 서버는 최상정도 레벨의 디폴트의 그룹을 몇개인가 생성 한다. 유저가 실행할 수 있는 것은, 최상정도 레벨의 그룹내에 서브 그룹을 생성 하는 것, staging 에리어를 생성 하는 것, 및 staging 에리어에의 쇼트 컷을 생성 하는 것 뿐이다.

로비 서버 어플리케이션은, 유저의 편의를 위해서(때문에), 최상정도 레벨의 그룹이 자동적으로 생성 되지 않는 테스트 모드를 제공한다. 유저는 임의의 그룹 계층을, 임의의 깊이로 생성 할 수가 있다. 로비 서버를 테스트 모드로 설정하는 작업은,[Server] 메뉴의 [Start] 를 클릭하기 전에 실시할 필요가 있다. 로비 서버를 테스트 모드로 설정하려면 ,[Server] 메뉴의 [Test Mode] 를 클릭한다. 다음에 [Server] 메뉴의 [Start] 를 클릭 하면, 로비 서버가 테스트 모드로 기동한다.

[Server] 메뉴의 [Secure Mode] 를 클릭하고 나서 [Start] 를 클릭해, 게다가 로비 서버가 Windows NT 4.0 또는 Windows 2000 상에서 실행되고 있는 경우, 클라이언트는 로그인하도록(듯이) 요구된다.

클라이언트는, 사용하는 서비스 프로바이더를 묻는다. 서버에 접속하는 모든 클라이언트가 같은 서비스 프로바이더를 선택할 필요가 있다. 계속되어, 로비 서버 세션의 이름을 제공하도록(듯이) 요구된다.


DirectPlay C++ 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 샘플」을 참조할것.

[C++]

이하의 샘플은, DirectPlay 의 사용법을 나타내고 있다. 이러한 샘플은 C++ 로 기술되고 있다.

  • Bellhop 샘플
  • ChatConnect 샘플
  • DPLaunch 샘플
  • DPSlots 샘플
  • Duel 샘플
  • Override 샘플
  • SimpleConnect 샘플
  • StagedConnect 샘플


Bellhop 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 샘플」을 참조할것.

[C++]

설명

Bellhop 샘플은,IDirectPlay4 인터페이스를 사용해로비 서버와 교환하는로비 클라이언트 프로그램이다. Bellhop 를 실행하려면 ,로비 서버 어플리케이션을 실행해 둘 필요가 있다.

Bellhop 를 사용 하면, 어플리케이션의 로비 지원을 테스트할 수가 있다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DPlay\Src\Bellhop

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DPlay\Bin\Bellhop.exe

유저즈 가이드

Bellhop 를 기동 하면, 로비 프로바이더를 선택하도록(듯이) 요구된다. 로비 서버 어플리케이션이 실행중의 경우는,[Lobby Connection for DirectPlay] 를 선택한다.

서비스 프로바이더를 선택하는 다이알로그 박스가 표시된다. 샘플의 로비 서버와 로비 클라이언트는, DirectPlay 로 지원 되고 있는 임의의 네트워크상에서 기능한다. 적절한 서비스 프로바이더 (TCP/IP 등)를 선택해,[OK] 를 클릭한다.

TCP/IP 접속을 선택했을 경우는, 로비 서버의 주소가 요구된다. 이 주소를 비워, 로컬 네트워크상에서 주소를 검색할 수가 있다. 혹은, 컴퓨터명 또는 IP 주소를 입력해도 괜찮다. 로비 세션명이 표시되면(자), 플레이어 또는 관객으로서 그 세션에 참가한다 (양자에게 실질적인 차이는 없다. 어플리케이션에서는, 플레이어와 관객은 똑같이 다루어진다).

로비 서버가 테스트 모드로 실행되어 있지 않은 경우, 그룹 또는 룸을 나타내는 문이 몇개인가 표시된다. 몇개의 문을 더블 클릭 한다. 가상 게임 환경에서 유저를 나타내는 문자가 표시된다. 최초의 그룹을 떠나는 일 없이 다른 그룹에 참가하려면 , 참가하고 싶은 그룹의 문을 더블 클릭 한다. 룸을 떠나려면 , 플레이어 아이콘을 마우스의 오른쪽 버튼으로 클릭해,[Delete Player From Group] 를 클릭한다. 어느 룸을 떠나는 것과 동시에 다른 룸에 들어가려면 , 자신의 플레이어를 나타내는 아이콘을 드래그 앤드 드롭 한다.

표시할 수 있는 것은, 자신이 참가한 룸의 내용 뿐이다. 룸을 떠나면(자), 그 룸에 있는 문 (서브 그룹)과 플레이어는 모두 사라진다.

Bellhop 는 상황 의존의 메뉴를 제공한다. 플레이어 또는 그룹을 마우스의 오른쪽 버튼으로 클릭 하면, 그 아이템으로 이용 가능한 고유의 옵션이 표시된다. 배경을 마우스의 오른쪽 버튼으로 클릭 하면, 그 표시를 리프레쉬 할 수가 있다. 이용 가능한 모든 그룹과 플레이어가 재차 열거된다.

기존의 룸에서 서브 그룹 또는 staging 에리어를 생성 하고 싶은 경우는, 폴더를 마우스의 오른쪽 버튼으로 클릭한다. 표시되는 메뉴로 [Create Group In Group] 를 클릭한다. staging 에리어를 선택했을 경우는, 플레이 하는 게임을 리스트로부터 선택할 필요가 있다. DirectPlay 에 등록된 어플리케이션만이 표시된다. 네트워크상에서 실행되고 있는 그 외의 어플리케이션은 무시된다. 게임 뿐만이 아니라, 게임을 시작 하기 위해서 사용하는 접속도 선택할 필요가 있다. 옵션으로서 세션에 대한 패스워드를 지정하거나 플레이어의 최대수를 지정할 수가 있다.

staging 에리어에 참가하는 경우는, 그 아이콘을 마우스의 오른쪽 버튼으로 클릭해, 표시되는 메뉴로[Connection Settings] 를 클릭한다. staging 에리어의 프로퍼티가 표시된다. 이러한 프로퍼티의 설정을 변경할 수가 있다.

staging 에리어로부터 게임을 시작 하려면 , staging 에리어의 아이콘을 마우스의 오른쪽 버튼으로 클릭해,[Start Session] 를 클릭한다. 이것에 의해, staging 에리어모든 유저의 머신상에서 어플리케이션이 기동해, 그러한 유저가 세션에 접속된다. 세션이 시작 한 후에 staging 에리어로 이동하려면 ,[Start Session] 를 클릭해 진행중의 세션에 참가한다. 세션의 진행중은, 아이콘이 초록의 삼각형으로부터 적과 흙의 삼각형에 변화한다.

로컬 그룹 또는 플레이어의 이름을 변경하려면 , 그룹 또는 플레이어를 마우스의 오른쪽 버튼으로 클릭해,[Set Group Name] 또는 [Set Player Name] 를 클릭한다. 혹은, 그룹 또는 플레이어의 이름의 텍스트를 클릭해도 괜찮다.

같은 룸에 있는 다른 플레이어에게 채팅 메세지를 송신하려면 , 화면아래에 있는 텍스트 박스에 텍스트를 입력해,[Send] 를 클릭한다.


ChatConnect 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 샘플」을 참조할것.

[C++]

설명

ChatConnect 샘플은, 로비로부터 실행 가능한 채팅 프로그램이다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DPlay\Src\ChatConnect

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DPlay\Bin\ChatConnect.exe.

유저즈 가이드

플레이어의 이름을 입력해, 접속의 종류를 선택하는지, 또는 리스트로부터 [Wait for Lobby Connection] 를 선택한다. [Multiplayer Games] 다이알로그 박스로,[Create] 를 클릭해 세션을 시작 하는지, 또는 [Start Search] 를 클릭해 액티브한 세션을 검색한다. 액티브한 세션에 참가하려면 , 세션을 선택해 [Join] 를 클릭한다. 세션에 참가하는지, 또는 세션을 생성 하면, 즉시 채팅이 시작된다. 다른 플레이어는 채팅에 언제라도 참가할 수 있다. DirectPlayer 는 호스트 플레이어를 자동적으로 이행 하므로, 호스트 플레이어는 언제라도 채팅을 그만둘 수가 있다.

TCP/IP 서비스 프로바이더를 사용 하면, 단일의 머신상에서 샘플의 복수의 인스턴스를 테스트할 수가 있다.

프로그래밍의 주의

이 샘플은, DirectPlay 를 채팅 세션용으로 사용하는 방법을 나타내고 있다.


DPLaunch 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 샘플」을 참조할것.

[C++]

설명

DPLaunch 샘플은,IDirectPlayLobby3 인터페이스를 사용해 기존의 소스로부터 DirectPlay 어플리케이션을 기동하는 방법을 나타내는 스탠드얼론의 어플리케이션이다. 또, 이 샘플을 사용해 어플리케이션의 로비 지원을 테스트할 수도 있다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DPlay\Src\DPLaunch

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DPlay\Bin\DPLaunch.exe

유저즈 가이드

DPLaunch 를 기동 하면, 컴퓨터에 등록된 DirectPlay 어플리케이션의 리스트가 표시된다. 실행하는 어플리케이션을 선택하면(자), 접속 방법을 선택해, 자신의 플레이어명을 지정한다. 게다가 세션명을 선택해, 기존의 세션에 참가하는지, 또는 새로운 세션을 생성 하는지를 지정할 필요가 있다.


DPSlots 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 샘플」을 참조할것.

[C++]

설명

DPSlots 샘플은, DirectPlay 의 시큐러티 기능을 이용하는, 클라이언트/서버형의 슬롯 머신 시뮬레이터이다.

서버는 모든 슬롯 머신을 제어해, 각 플레이어가 소유하는 금액을 추적한다. 클라이언트는 서버에 확실히 로그 온 한다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DPlay\Src\DPSlots

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DPlay\Bin\DPSlots.exe

유저즈 가이드

DPSlots 는, 실제로는 2 개의 어플리케이션으로 구성된다. 유저가 세션을 호스트 하는 경우, DPSlots 는 서버로서 기능한다. 유저가 세션에 참가하는 경우, DPSlots 는 클라이언트로서 기능한다.

서버는, 로그 온의 허가된 모든 유저에 대한 거래 잔고의 간단한 데이타베이스를 관리한다. 클라이언트는 서버에 대해, 현재의 잔금을 요구할 수 있다. 또, 클라이언트는 서버에 대해, 슬롯 머신을 실행해, 승부의 합계 금액을 계산하도록(듯이) 요구할 수가 있다. 서버는 Slotsdb.txt 라고 하는 간단한 텍스트 데이타베이스를 유지한다. 이 데이타베이스는, 각 유저의 잔금을 기록한다. 텍스트 파일의 각 행에는, 다음의 예에 나타내도록(듯이), 유저 어카운트의 ID 와 잔금을 나타내는 8 문자의 숫자가 칸마로 단락지어져 저장 되고 있다.

Account1,    1000
Account2,     500

이 파일에 유저 마다 행을 수작업으로 입력할 필요가 있다. "Account1"의 부분에는, 네트워크 유저명을 입력한다.

유저가 세션에 참가 하면, DPSlots 는 클라이언트로서 기능해, 모든 조작에 대한 메세지를 서버에 송신한다. 클라이언트는, 이름과 패스워드를 사용해 유저를 서버에 로그 온 하도록(듯이) 요구되는 경우가 있다.

시큐러티를 사용해 DPSlots 를 호스트 하려면 , 호스트 하는 것을 선택한 후에,[Require Secure Login] 체크 박스를 온으로 한다. [Security Provider] 텍스트 박스를 공백대로 하면, 디폴트의 NTLM 시큐러티 패키지가 사용된다. 다른 SSPI 시큐러티 패키지를 인스톨 하고 있는 경우는, 여기서 그 패키지를 지정할 수 있다.

시큐러티 프로바이더를 설정 하면, 서버는 시큐어 세션을 제공할 수 있게 된다. 클라이언트가 세션에 참가하려면 , 유저명으로 패스워드를 사용해 안전하게 로그 온 할 필요가 있다. 클라이언트와 서버간에 교환되는 메세지는, 모두 디지털 서명 되어 암호화된다.

안전한 서버를 호스트 하면나무는, 사용하고 있는 시큐러티 패키지에 의해 각 유저의 어카운트 ID 가 정의된다. 이 어카운트 ID 를, 적절한 잔금과 함께 데이타베이스 파일에 저장 할 필요가 있다. 디폴트의 시큐러티 패키지는 NTLM 이다. NTLM 는, 도메인과 유저명을 사용해 어카운트 ID 를 정의한다. 예를 들어, NTLM 를 사용하고 있는 경우, 도메인이"GAMES"로,"Bob"및"Jane"라고 하는 2 명의 유저가 있으면, 데이타베이스 파일은 다음과 같이 된다.

GAMES/Bob,    1000
GAMES/Jane,    500

현재, 시큐어 세션을 호스트 할 수 있는 것은, Windows NT 또는 Windows 2000 의 워크스테이션 또는 서버상에서 NTLM 를 사용하고 있는 경우 뿐이다.


Duel 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 샘플」을 참조할것.

[C++]

설명

Duel 샘플은, 로비로부터 실행 가능한 멀티 플레이어 게임이다. 이 샘플은, DirectPlay 의 사용법을 나타낼 뿐만 아니라, DirectDraw, DirectInput, 및 DirectSound 도 이용하고 있다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DPlay\Src\Duel

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DPlay\Bin\Duel.exe

유저즈 가이드

Enter 키를 눌러 시작 한다. 새로운 게임을 호스트 하는지, 또는 기존의 게임에 참가하는지를 선택할 수가 있다.

게임의 플레이어는, 모두 소행성 필드의 작은 우주선으로 나타내진다. 우주선을 왼쪽으로 선회시키려면 좌향의 방향 키를, 오른쪽으로 선회시키려면 오른쪽 방향의 방향 키를 사용한다. 오름새의 방향 키는 우주선을 전진시켜, 아래로 향한 방향 키는 후퇴 시킨다. 공격하려면 ,Space 키를 누른다. 게임을 종료하려면 ,ESC 키 또는 F12 키를 누른다.

TCP/IP 접속을 사용 하면, 단일의 컴퓨터상에서 프로그램의 복수의 인스턴스를 실행할 수가 있다. 다만, 갱신되는 것은 전면의 인스턴스 뿐이다.

인터넷상에서 TCP/IP 를 사용해 플레이 하려면 , 게임에 참가하고 있는 유저가 게임을 호스트 하는 머신의 IP 주소를 입력할 필요가 있다. Windows 95 또는 Windows 98 의 유저는, Winipcfg.exe 를 실행해 로컬 IP 주소를 판단할 수가 있다. Windows 2000 에서는, lpconfig.exe 를 실행해 같은 것이 생긴다. 유저가 LAN 와 다이얼 업에 의한 인터넷 서비스 프로바이더 (ISP)의 양쪽 모두에 접속하고 있는 경우는, 컴퓨터가 2 개의 IP 주소를 가지고 있는 경우가 있다. 그 경우는, 게임에 대해서 적절한 IP 주소를 선택할 필요가 있다. 다이얼 업 ISP 의 대부분은, 동적인 IP 주소를 할당한다. 이 IP 주소는, 유저가 로그 온 할 때마다 변화한다

이 게임은, 프록시 또는 파이어 월(fire wall)를 개입시켰을 경우에는 기능하지 않는다.


Override 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 샘플」을 참조할것.

[C++]

설명

Override 샘플은, DirectPlay 의서비스 프로바이더 다이알로그 박스를 고쳐 쓰기 위한 방법을 간단하게 가리킨다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DPlay\Src\Override

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DPlay\Bin\Override.exe

유저즈 가이드

프로그램이 기동하면(자), 서비스 프로바이더를 선택한다. 서비스 프로바이더를 선택 하면, 그 서비스 프로바이더에 필요한 정보를 모으기 위해서(때문에) 생성 된 다이알로그 박스가 표시된다. 프로그램에 의해 파악되어 있지 않은 서비스 프로바이더를 선택 하면, 서비스 프로바이더의 다이알로그 박스는 고쳐 쓸 수 있는 두, 디폴트의 다이알로그 박스가 표시된다.

유저로부터 서비스 프로바이더의 정보를 수집하면(자), 그것을 DirectPlay 의 주소에 서식 설정할 필요가 있다. 이 주소를 사용해, 서비스 프로바이더를 초기화할 수가 있다.

IDirectPlay4::EnumSessions 메소드와 IDirectPlay4::Open 메소드를 호출하면나무에,dwFlags 파라미터에 값 DPENUMSESSIONS_RETURNSTATUS 를 설정할 필요가 있다. 이것에 의해, 접속의 진행 상황을 나타내기 위해서(때문에) 표시되는 스테이터스 다이알로그 박스가 모두 은폐 된다.


SimpleConnect 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 샘플」을 참조할것.

[C++]

설명

SimpleConnect 샘플은, DirectPlay 세션을 생성 하는 방법과 세션에 참가하는 방법, 및 메세지를 송수신 하는 방법을 나타낸다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DPlay\Src\SimpleConnect

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DPlay\Bin\SimpleConnect.exe

유저즈 가이드

플레이어의 이름을 입력해, 접속의 종류를 선택하는지, 또는 리스트로부터 [Wait for Lobby Connection] 를 선택한다. [Multiplayer Games] 다이알로그 박스로,[Create] 를 클릭해 새로운 세션을 시작 하는지, 또는 [Start Search] 를 클릭해 액티브한 세션을 검색한다. 액티브한 세션에 참가하려면 , 그 세션을 선택해 [Join] 를 클릭한다. "게임"은 시작되지만, 다른 플레이어는 언제라도 게임에 참가할 수가 있다. 세션에 참가하고 있는 다른 모든 플레이어에게 메세지를 송신하려면 ,[Wave to Other Players] 를 클릭한다. DirectPlayer 는 호스트 플레이어를 자동적으로 이행 하므로, 호스트 플레이어는 언제라도 게임을 떨어질 수가 있다.

TCP/IP 서비스 프로바이더를 사용 하면, 단일의 머신상에서 샘플의 복수의 인스턴스를 테스트할 수가 있다.

프로그래밍의 주의

이 샘플은, DirectPlay 를 게임에 사용하는 방법의 기본을 나타내고 있다.


StagedConnect 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectPlay Visual Basic 샘플」을 참조할것.

[C++]

설명

StagedConnect 샘플은,ChatConnect 샘플과SimpleConnect 샘플의 고성능판이다. 이 샘플에서는, 세션은 staging 에리어로부터 시작된다. staging 에리어에서는, 호스트가 플레이어의 수를 제한하거나 플레이어를 거부하거나 게임을 시작 하거나 할 수가 있다. 또, staging 에리어에서는, 플레이어는 게임이 시작되기 전에 채팅을 실시하거나 게임을 떨어지거나 할 수가 있다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DPlay\Src\StagedConnect

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DPlay\Bin\StagedConnect.exe

유저즈 가이드

플레이어의 이름을 입력해, 접속의 종류를 선택하는지, 또는 리스트로부터 [Wait for Lobby Connection] 를 선택한다. [Multiplayer Games] 다이알로그 박스로,[Create] 를 클릭해 새로운 세션을 시작 하는지, 또는 [Start Search] 를 클릭해 액티브한 세션을 검색한다. 액티브한 세션에 참가하려면 , 그 세션을 선택해 [Join] 를 클릭한다.

세션에 참가하는 경우는, staging 에리어에서 자신의 이름의 옆에 있는 체크 박스를 온으로 한다. staging 에리어에 있는 다른 플레이어에게 채팅 메세지를 송신하려면 , 아래에 있는 텍스트 박스에 메세지를 입력해,Enter 키를 누른다.

호스트는, 슬롯의 버튼을 클릭하는 것으로써, 슬롯을 닫거나 그 슬롯에서 플레이어를 거부하거나 할 수가 있다. 또,[Start Game] 를 클릭해 플레이를 시작 할 수가 있다. 게임은, 모든 플레이어가 모이고 처음으로 시작 할 수 있다.

프로그래밍의 주의

이 샘플은, 로비 세션은 아니고, 어플리케이션 세션내에서 staging 에리어를 셋업 하는 방법을 나타내고 있다.


DirectPlay Visual Basic 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectPlay C++ 샘플」을 참조할것.

[Visual Basic]

이하의 샘플은, DirectPlay 의 사용법을 나타내고 있다. 이러한 샘플은 Visual Basic 로 기술되고 있다.

  • Chat 샘플
  • Memory 샘플
  • Whiteboard 샘플


Chat 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectPlay C++ 샘플」을 참조할것.

[Visual Basic]

설명

Chat 샘플은, 간단한 채팅 클라이언트이다. 이 샘플은, 로비 클라이언트로부터 기동하는 일도, 유저에 의해 기동된 후에 로비 세션에 참가하는 일도 가능하다.

패스

소스 : (SDK 루트)\Samples\Multimedia\VBSamples\DPlay\Src\Chat

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\VBSamples\DPlay\Bin\DXVBChat.exe

유저즈 가이드

채팅을 시작 하려면 , 다음의 순서를 실행한다.

1. 컴퓨터상에서로비 서버를 실행한다. 보통의 세션을 시작 한다.

2. 각 클라이언트 머신상에서Bellhop 샘플을 실행해, 로비 서버에 의해 생성 된 로비 세션에 참가한다.

3. 1 대의 클라이언트 위에의 Bellhop 로, DXVBChat 에 대한 staging 영역을 생성 한다 (Chat 문을 마우스의 오른쪽 버튼으로 클릭해,[CreateGroupInGroup] 를 클릭한다).

4. 각 클라이언트상에서, 삼각형을 더블 클릭 해, staging 영역에 들어간다. 1 대의 클라이언트상에서, 삼각형을 마우스의 오른쪽 버튼으로 클릭해,[StartSession] 를 클릭해, 세션을 시작 한다. 이것에 의해, staging 영역내의 모든 클라이언트상에서 DXVBChat 가 실행되는지, 또는 DXVBChat 가 대기 모드로부터 빠진다.

세션이 시작된 후에 새로운 플레이어가 참가하려면 , staging 영역에 들어가, 세션을 재차 "시작" 한다.

세션이 시작되기 전에 DXVBChat 를 실행하는 것은 가능하지만, Visual Basic 환경으로부터 실행할 수 없다. DXVBChat.exe 를 실행할 필요가 있다.

1 대의 컴퓨터상에서 어플리케이션의 복수의 인스턴스를 테스트하려면 , TCP/IP 를 사용한다. 실행되고 있는 처리를 자세하게 확인하려면 , Bellhop 의 각 인스턴스로 다른 플레이어명을 선택한다.

프로그래밍 위에의 주의

InitDPlay 함수는, 어플리케이션이 유저에 의해 기동되었는지 (접속의 설정을 대기할 필요가 있다), 또는 로비에 의해 기동되었는지를 판단하는 방법을 나타내고 있다.


Memory 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectPlay C++ 샘플」을 참조할것.

[Visual Basic]

설명

Memory 는, 4 명까지의 플레이어가 참가할 수 있는 간단한 네트워크 게임이다. 이 게임은, 접속을 확립해, 세션을 생성 하든가 또는 세션에 참가해, 플레이어를 생성 해, DirectPlay 메세지를 송수신 하는 방법을 나타내고 있다.

패스

소스 : (SDK 루트)\Samples\Multimedia\VBSamples\DPlay\Src\Memory

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\VBSamples\DPlay\Bin\Memory.exe

유저즈 가이드

네트워크 세션을 생성 하는지, 또는 네트워크 세션에 참가하려면 ,[Multiplayer] 버튼을 클릭한다. 접속의 종류를 선택해, 옵션으로 플레이어의 이름을 변경해,[OK] 를 클릭한다. 세션을 호스트 하고 있는 경우는, 서비스 프로바이더의 모든 다이알로그 박스를 캔슬할 수가 있다.

TCP/IP 접속을 선택 하면, 1 대의 컴퓨터상에서 복수의 세션을 실행해, 게임을 플레이 할 수가 있다.

[Join or Create Game] 다이알로그 박스로,[New] 를 클릭해 새로운 게임을 생성 하는지, 또는 리스트로부터 게임을 선택해 [Join] 를 클릭한다. 이 리스트는 자동적으로는 갱신되지 않기 때문에, 다른 플레이어가 게임을 생성 하는 것을 대기하고 있는 경우는,[Refresh] 버튼을 정기적으로 클릭할 필요가 있다.

게임을 생성 하는 경우는, 플레이어의 최대수와 이름을 설정해,[Create] 를 클릭한다. [Waiting for Host to Start Game] 다이알로그 박스가 표시된다. 최저 1 명의 플레이어가 리스트에 표시되고 있으면, 게임을 즉시 시작 할 수가 있다.

게임을 플레이 하려면 , 자신의 이름이 기록 게시판에 강조 표시되는 것을 기다려, 임의의 2 개의 타일을 클릭한다. 타일이 일치하면(자), 한번 더 플레이 한다. 일치한 타일이 가장 많은 플레이어가 승리이다. 일치하지 않는 타일은, 다음의 플레이어가 타일을 클릭 하면, 즉시 숨겨진다.

다른 모든 플레이어에게 채팅 메세지를 송신하려면 ,Enter 키를 누른다.

도중에 게임을 빠지면(자), 다른 플레이어가 호스트가 된다.

프로그래밍 위에의 주의

어플리케이션은, GlobalModule.bas 모듈의 Sub Main 로 메세지를 문의한다. 또, 대부분의 폼에, DirectPlay 의 코드가 포함되어 있다.


Whiteboard 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectPlay C++ 샘플」을 참조할것.

[Visual Basic]

설명

Whiteboard 샘플은, 로비에 대응하고 있지 않는 채팅 어플리케이션이다. 이 어플리케이션에서는, 유저가 스케치 보드상에서 공동 작업하거나 텍스트 메세지를 교환하거나 할 수가 있다.

패스

소스 : (SDK 루트)\Samples\Multimedia\VBSamples\DPlay\Src\Whiteboard

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\VBSamples\DPlay\Bin\Whiteboard.exe

유저즈 가이드

몇개의 유저가,[Sessions] 메뉴의 [Create Host] 를 클릭해, 세션을 시작 할 필요가 있다. 이 세션에, 다른 플레이어가 참가한다.

메세지를 송신하려면 , 화면의 하부에 있는 텍스트 박스에 입력해,[Send] 버튼을 클릭한다. 화이트 보드에 드로잉(Drawing) 하려면 , 마우스를 드러그 한다. 그린 것을 지우려면 ,[Clear] 를 클릭한다.

프로그래밍 위에의 주의

메세지는, 바다거북 겨이삭띠에 응해 취득된다.


DirectSetup

여기에서는, Platform Software Development Kit (SDK) 또는 standalone DirectX SDK 에 있어서의 Microsoft® DirectX® 어플리케이션 프로그래밍 인터페이스 (API)의 Microsoft® DirectSetup® 컴퍼넌트에 관한 정보를 이하의 항목으로 나누어 설명한다.

  • DirectSetup 에 대해
  • DirectSetup 의 요점
  • DirectSetup 레퍼런스
  • DirectSetup 샘플


DirectSetup 에 대해

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 로 기술된 어플리케이션의 배포에 대해서는, 「DirectX for Visual Basic 어플리케이션의 인스톨」을 참조할것.

[C++]

DirectSetup 는, DirectX 의 모든 컴퍼넌트를 한 번의 호출로 인스톨하기 위한 심플한 API 이다. 이 API 의 의의는, 단지 편리라고 하는 만큼 머물지 않는다. DirectX 는 복잡한 구성이 되어 있기 (위해)때문에, 인스톨도 복잡한 태스크가 된다. 그 때문에, DirectX 의 인스톨은 수동으로 실시해서는 안된다.

게다가 DirectSetup 를 사용하는 것으로, DirectPlayLobby 오브젝트를 이용하는 어플리케이션에 필요한 Microsoft® Windows® operating system의 레지스트리 정보를 자동적으로 인스톨 할 수 있다. 이 레지스트리 정보는, DirectPlayLobby 오브젝트에 의한 어플리케이션의 열거 및 기동에 필요하게 된다.

DirectSetup 에는, 몇개의 API 함수와 구조체가 포함된다. 그 외 , 인스톨 프로세스용의 유저 인터페이스를 어플리케이션측에서 커스터마이즈하기 위한 prototype로서DirectXSetupCallbackFunction 도 준비되어 있다. DirectX SDK 에는, 이 콜백 함수의 사용예를 나타내는 샘플 어플리케이션이 수록되고 있다. 상세한 것에 대하여는, 「Dinstall 샘플」을 참조할것.


DirectSetup 의 요점

여기에서는, DirectSetup 컴퍼넌트의 개요에 대해 설명한다. 설명하는 내용은 이하대로이다.

  • DirectSetup 의 셋업의 개요
  • DirectX for Visual Basic 어플리케이션의 인스톨
  • 셋업 폴더의 준비
  • 셋업의 커스터마이즈
  • 셋업 프로그램의 테스트
  • AutoPlay 의 사용


DirectSetup 의 셋업의 개요

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 로 기술된 어플리케이션의 배포에 대해서는, 「DirectX for Visual Basic 어플리케이션의 인스톨」을 참조할것.

[C++]

DirectX 를 베이스로 하는 어플리케이션 및 게임은,DirectXSetup 함수를 사용해, 이미 인스톨 되고 있는 Windows 시스템에 필요한 시스템 컴퍼넌트를 인스톨 할 수가 있다. 이 함수에서는, 디스플레이나 오디오 디바이스로 적절히 DirectX 가 지원 되도록, 드라이버의 업데이트도 실시할 수가 있다. DirectXSetup 는, 보통, 어플리케이션 파일의 인스톨에 사용하는 프로그램으로부터 호출한다.

주 : DirectXSetup 함수는, 구버젼의 DirectX 시스템 컴퍼넌트를 덧쓰기한다. 예를 들어, 이미 DirectX 5.0 의 컴퍼넌트가 존재하는 시스템에 DirectX 7.0 을 인스톨 하면, DirectX 5.0 의 컴퍼넌트 모든 것이 덧쓰기된다. 다만, DirectX 의 컴퍼넌트는 모두 컴퍼넌트 오브젝트 모델 (COM)의 하위 호환성 규칙에 준거하고 있으므로, DirectX 5.0 용으로 기술한 소프트웨어도 계속해 정상적으로 기능한다.

DirectXSetup 함수는, DirectX 컴퍼넌트, 디스플레이 드라이버, 오디오 드라이버의 업그레이드가 필요한 일을 알릴 수가 있다. 또, 이러한 컴퍼넌트를, Windows operating system에 악영향을 주는 것 없이 업그레이드 할 수 있을지 어떨지도 판단할 수 있다. 이것이 이른바 세이프 업그레이드이다. 업그레이드때는, 컴퓨터상에서 동작하고 있는 어플리케이션 뿐만이 아니라, operating system에 대한 안전성도 고려한다. 또, Windows 에 있어서는 안전해도, 일부의 하드웨어 의존 어플리케이션에 악영향을 주어 버리는 경우도 있다.

디폴트에서는,DirectXSetup 함수는 안전한 업그레이드만을 실행한다. 디바이스 드라이버의 업그레이드에 의해 Windows 의 동작에 악영향이 미칠 가능성이 있는 경우, 업그레이드는 행해지지 않는다.

셋업 처리중, DirectSetup 는 옮겨놓는 시스템 컴퍼넌트와 드라이버의 백업 카피를 생성 한다. 이러한 카피는, 문제가 발생했을 경우에 복원하기 위한 것이다.

디스플레이 드라이버 또는 오디오 드라이버를 업그레이드 하면 와,DirectXSetup 함수는, Microsoft 사가 생성 한 데이타베이스를 이용해 업그레이드 프로세스를 관리한다. 이 데이타베이스에는, Microsoft 사, 하드웨어의 제조업자, 또는 하드웨어의 판매점이 제공하는 드라이버에 대한 정보가 포함되어 있다. 또, Microsoft 사나 그 외에서의 검사에 근거하는 각각의 드라이버의 업그레이드 상황도 등록되어 있다.

DirectXSetup 함수를 실행하면(자), 반환값을 체크한다. 반환값이 DSETUPERR_SUCCESS_RESTART 의 경우는, 재부팅 할 때까지 변경 내용이 유효하게 안 되는 것을 유저에게 알려 곧바로 재부팅 할지 어떨지 선택시킨다. 이 방법에 대해서는,Dinstall 샘플 어플리케이션의 Dinstall.c 의 예를 참조할것.


DirectX for Visual Basic 어플리케이션의 인스톨

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[Visual Basic]

모듈내에서 함수에 참조를 선언 하면, Visual Basic 어플리케이션으로 DirectSetup 함수를 사용할 수 있지만, 추천 방법은 어플리케이션 위저드의 사용이다. CD 로 어플리케이션을 배포하려면 , 다음의 순서를 실행한다.

Visual Basic 어플리케이션의 배포

1. 어플리케이션 위저드를 기동한다.

2. 의존 리스트로부터 DxVBLib.dll 를 삭제한다.

3. 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 으로 개발하고 있는 경우는, 어플리케이션 위저드로 생성 된 배치파일을 실행한다.

7. 이것으로, CD 로 파일을 배포할 준비가 갖추어진다.


셋업 폴더의 준비

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 로 기술된 어플리케이션의 배포에 대해서는, 「DirectX for Visual Basic 어플리케이션의 인스톨」을 참조할것.

[C++]

DirectXSetup 함수는, 인스톨의 루트 디렉토리를 나타내는 파라미터 lpszRootPath 를 취한다. 이 파라미터를 NULL 로 해, 현재의 디렉토리 (즉, 셋업 프로그램이 보존되고 있는 디렉토리)를 루트 패스로 할 수도 있다.

루트 디렉토리에는, dsetup.dll 와 dsetup32.dll 를 보존할 필요가 있다. 또, 이 안에는 「DirectX」 (대문자 소문자의 구별 없음)이라는 이름의 폴더를 준비해, 재배포 가능한 모든 파일 및 드라이버를 보존한다. 올바른 구조의 어플리케이션 셋업 디스크는, DirectX SDK 디스크의 Dxf\Redist\DirectX7 폴더의 내용 모든 것을 셋업 프로그램의 루트 패스에 카피 하면 생성 할 수 있다. 이 폴더는, SDK 의 인스톨시에 개발용의 컴퓨터에 카피되지 않기 때문에, 오리지날 디스크로부터 별도 카피할 필요가 있다.


셋업의 커스터마이즈

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 로 기술된 어플리케이션의 배포에 대해서는, 「DirectX for Visual Basic 어플리케이션의 인스톨」을 참조할것.

[C++]

DirectSetup 에서는, DirectX 셋업 프로세스를 커스터마이즈하기 위한 콜백 함수를 정의할 수가 있다. 이 콜백 함수는, DirectSetup 문서 중(안)에서는 DirectXSetupCallbackFunction 로 불리고 있지만, 실제로는 임의의 이름을 할당할 수가 있다.

셋업 프로그램으로 콜백 함수를 사용하지 않는 경우,DirectXSetup 함수는, Microsoft® Win32® MessageBox 함수를 호출해, 다이알로그 박스내에 스테이터스 정보나 에러 정보를 표시해, 유저 입력의 취득을 실시한다. 콜백 함수를 사용하는 경우, 이 스테이터스 다이얼로그 또는 메시지 박스의 생성에 사용되어야할 정보는, 대신에 콜백 함수에게 건네진다. 콜백 함수는, 인스톨 또는 업그레이드 가능한 DirectX 컴퍼넌트 및 디바이스 드라이버 마다 한 번 두개 불려 간다.

콜백 함수는, 이하의 용도에 사용할 수 있다.

  • 커스텀 인터페이스의 사용 － MessageBox 나 Windows 의 표준 다이알로그 박스 이외 방법으로, 셋업 프로그램의 메세지를 표시할 수 있다. 콜백 함수를 사용하는 것으로, DirectX 컴퍼넌트의 인스톨용 메세지를, 독자적인 인터페이스에 통합할 수 있다.
  • 진행 인디케이터(indicator)의 갱신
  • 스테이터스 메세지 및 에러 메세지의 표시 제어 － 초심자전용의 프로그램을 개발하는 경우에는, 에러 메세지를 제어해, 셋업 프로그램에 에러의 처리나 업그레이드의 선택을 자동적으로 처리시키고 싶은 경우가 있다. 이러한 셋업 프로그램의 개발에는 시간이 들지만, 대상 유저층을 생각하면(자) 적절한 조치라고 할 수 있다.

셋업의 커스터마이즈에 해당해서는, 다음의 각 주제를 참고로 하는 것.

  • DirectSetup 콜백 함수의 생성
  • 콜백 함수의 설정
  • 콜백 함수에서의 업그레이드 플래그의 사용
  • 콜백 함수에 의한 디폴트 동작의 무효화


DirectSetup 콜백 함수의 생성

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 로 기술된 어플리케이션의 배포에 대해서는, 「DirectX for Visual Basic 어플리케이션의 인스톨」을 참조할것.

[C++]

셋업 프로세스를 커스터마이즈 하려면 , 우선 다음의 선언으로 가리킨 DirectXSetupCallbackFunction prototype에 적합하는 콜백 함수를 생성 한다.

DWORD WINAPI DirectXSetupCallbackFunction(
        DWORD dwReason,
        DWORD dwMsgType,
        LPSTR szMessage,
        LPSTR szName,
        void *pInfo);

이 예 (Dinstall 를 수정한 것)에서는, 함수명이 prototype와 같게 되어 있지만, 이것은 변경 가능하다. 파라미터명은, dsetup.h 헤더 파일로 선언되고 있는 prototype와 약간 다르지만, 이하의 설명에서는 이러한 이름을 사용한다.

파라미터

dwReason 는, 콜백 함수가 불려 간 이유를 나타내는 파라미터이다. 유효값의 일람 및 각 유효값의 설명에 대해서는,DirectXSetupCallbackFunction 의 레퍼런스를 참조할것.

dwMsgType 파라미터는, 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] 버튼과 [Concel] 버튼이 있다.
       이 루틴에서는, IDBUT1 가 [OK] 버튼에 상당한다.
       이 버튼이 선택되지 않는 경우는 [Cancel] 가 된다.  */
    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 를 돌려준다.


콜백 함수의 설정

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 로 기술된 어플리케이션의 배포에 대해서는, 「DirectX for Visual Basic 어플리케이션의 인스톨」을 참조할것.

[C++]

콜백 함수를 사용하는 경우는,DirectXSetup 를 호출하기 전에 시스템에 알려 둘 필요가 있다. 이것에는, 콜백에의 포인터를 파라미터로서 건네주어 DirectXSetupSetCallback 함수를 호출한다. 다음의 예를 참조할것.

DirectXSetupSetCallback(
        (DSETUP_CALLBACK) DirectXSetupCallbackFunction);


콜백 함수에서의 업그레이드 플래그의 사용

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 로 기술된 어플리케이션의 배포에 대해서는, 「DirectX for Visual Basic 어플리케이션의 인스톨」을 참조할것.

[C++]

어플리케이션으로 정의된 콜백 함수 DirectXSetupCallbackFunction 가 DirectXSetup 함수로 불려 가면(자), 콜백 함수에 호출해 이유를 나타내는 파라미터가 건네받는다. 이유가 DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE 의 경우,pInfo 파라미터는,DirextXSetup 함수가 추천 하는 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

2차 업그레이드 플래그
다음의 언젠가 또는 양쪽 모두의 플래그가 존재한다.

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 함수의 디폴트 동작에서는, 업그레이드는 실행되지 않는다.


콜백 함수에 의한 디폴트 동작의 무효화

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 로 기술된 어플리케이션의 배포에 대해서는, 「DirectX for Visual Basic 어플리케이션의 인스톨」을 참조할것.

[C++]

어플리케이션으로 정의된 함수 DirectXSetupCallbackFunction 의 반환값을 사용해,DirectXSetup 함수의 디폴트 동작의 일부를 무효화할 수가 있다.

예를 들어,DirectXSetup 의 디폴트 동작에서는,pInfo 파라미터가 가리키는 구조 체내의 업그레이드 타입이 (DSETUP_CB_UPGRADE_SAFE | DSETUP_CB_UPGRADE_HAS_WARNINGS)로 설정되어 있으면(자) 컴퍼넌트는 인스톨 되지 않는다. 이 경우, 콜백 함수의 MsgType 파라미터는 (MB_YESNO | MB_DEFBUTTON2)으로 설정된다. 콜백 함수를 사용하지 않는 경우는,[No] 가 디폴트 버튼이 된 다이알로그 박스가 유저에게 표시된다. 유저 입력을 조사하지 않고 디폴트를 받아들이는 경우, 콜백 함수는 IDNO 를 돌려준다. 디폴트를 무효로 하는 경우는, IDYES 를 돌려준다. 디폴트를 무효로 하는 경우,DirectXSetup 함수는 유저에게 통지한다.


셋업 프로그램의 테스트

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 로 기술된 어플리케이션의 배포에 대해서는, 「DirectX for Visual Basic 어플리케이션의 인스톨」을 참조할것.

[C++]

생성 한 셋업 프로그램의 DirectSetup 컴퍼넌트를 테스트하려면 ,DirectXSetup 함수에 DSETUP_TESTINSTALL 플래그를 건네준 버젼을 컴파일 한다. 그리고, 「셋업 폴더의 준비」로 설명한 인스톨 디렉토리를 셋업 한다.

셋업 프로그램을 실행 하면, DirectSetup 는, 실제로는 컴퍼넌트를 인스톨 하지 않고 , DirectX 인스톨시의 모의 동작을 실시한다. 콜백 함수를 설정해 있는 경우는, 콜백 함수의 동작도 조사할 수 있다.


AutoPlay 의 사용

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 로 기술된 어플리케이션의 배포에 대해서는, 「DirectX for Visual Basic 어플리케이션의 인스톨」을 참조할것.

[C++]

AutoPlay 대응의 CD 타이틀을 생성 하려면 , DirectX SDK CD 의 루트 디렉토리중의 Autorun.inf 파일을, 어플리케이션 디렉토리의 루트에 카피한다. Autorun.inf 는, 이하의 정보를 저장 하는 텍스트 파일이다.

[autorun]
OPEN=SETUP.EXE

어플리케이션의 셋업 프로그램명이 Setup.exe 의 경우, 이 파일을 변경할 필요는 없다. 그 이외의 이름이 붙어 있는 경우는, 실제의 셋업 프로그램명에 맞추어 이 파일을 편집해야 한다.


DirectSetup 레퍼런스

여기에서는, Microsoft® DirectSetup® 의 API 요소의 레퍼런스 정보를 기술한다. 레퍼런스 정보는 이하의 카테고리로 분류된다.

  • 함수
  • 구조체
  • 반환값

이 레퍼런스는 주로, C++ 로 프로그래밍을 실시할 때 사용한다. Microsoft® DirectX® for Visual Basic 의 셋업 정보에 대해서는, 「DirectX for Visual Basic 어플리케이션의 인스톨」을 참조할것.


함수

여기에서는, DirectSetup 로 사용하는 이하의 글로벌 함수에 대해 설명한다.

  • DirectXRegisterApplication
  • DirectXSetup
  • DirectXSetupCallbackFunction
  • DirectXSetupGetVersion
  • DirectXSetupSetCallback
  • DirectXUnRegisterApplication


DirectXRegisterApplication

DirectXRegisterApplication 함수는, 어플리케이션을 DirectPlayLobby 대응 어플리케이션으로서 등록한다.

int WINAPI DirectXRegisterApplication(
  HWND hWnd,
  LPDIRECTXREGISTERAPP lpDXRegApp
);

파라미터

hWnd
부모 윈도우의 핸들. 이 파라미터가 NULL 의 경우는, 데스크탑이 부모 윈도우가 된다.
lpDXRegApp
DirectPlayLobby 로 올바르게 어플리케이션을 동작시키기 위해서(때문에) 필요한 레지스트리 엔트리를 포함한 DIRECTXREGISTERAPP 구조체의 주소.

반환값

성공하면 TRUE 를 돌려준다. 실패하면 FALSE 를 돌려준다. GetLastError 함수를 사용 하면, 확장 에러 정보를 취득할 수 있다.

주의

DirectXRegisterApplication 함수에서는, 시스템에 인스톨되어 있지 않은 dsetup.dll 와 dsetup32.dll 의 양쪽 모두가 필요하지만, 양쪽 모두 SDK 에 준비되어 있다.

DirectXRegisterApplication 함수는, 어플리케이션이 DirectPlayLobby 로 동작하는데 필요한 레지스트리 엔트리를 삽입하지만, 로비 어플리케이션의 인스톨과 언인스톨에는,IDirectPlayLobby3::RegisterApplication 와 IDirectPlayLobby3::UnregisterApplication 의 각 메소드의 사용을 추천 한다. 그 때문에,DirectXRegisterApplication 를 사용했을 경우, 어플리케이션의 언인스톨시에는,DirectXUnRegisterApplication 로 이러한 레지스트리 엔트리를 삭제할 필요가 있다.

시판되고 있는 인스톨 프로그램의 상당수는, 프로그램의 언인스톨시에 레지스트리 엔트리를 자동적으로 삭제한다. 다만, 이것은, 프로그램 자체가 레지스트리 엔트리를 추가했을 경우에 한정된다. DirectXRegisterApplication 에 의해 DirectPlayLobby 의 레지스트리 엔트리가 추가되었을 경우는, 시판의 인스톨 프로그램으로 언인스톨해도, 레지스트리 엔트리가 삭제되지 않는다. 따라서,DirectXRegisterApplication 에 의해 생성 된 DirectPlayLobby 의 레지스트리 엔트리는,DirectXUnRegisterApplication 를 사용해 삭제해야 한다.

DirectPlayLobby 액세스에 필요한 레지스트리 엔트리는,DirectXRegisterApplication 를 사용하지 않아도 생성 할 수 있다. 다만, 이 방법은 일반적으로 추천 되는 것은 아니다. Microsoft® DirectPlay® 의 「로비 대응 어플리케이션의 등록」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsetup.h 로 선언.
임포트 라이브러리 : dsetup.lib 를 사용.

참조

DirectXUnRegisterApplication


DirectXSetup

DirectXSetup 함수는, 1 개(살) 또는 복수의 DirectX 컴퍼넌트를 인스톨 한다.

int WINAPI DirectXSetup(
  HWND  hWnd,
  LPSTR lpszRootPath,
  DWORD dwFlags
);

파라미터

hWnd
셋업 다이알로그 박스의 부모 윈도우의 핸들.
lpszRootPath
DirectX 컴퍼넌트 파일의 루트 패스를 포함한 캐릭터 라인의 주소. 이 캐릭터 라인에는, 파일 dsetup.dll 및 dsetup.dll32 와 재배포 가능 파일을 저장 한 「DirectX」 (대문자 소문자의 구별 없음) 디렉토리가 있는 디렉토리에의 풀 패스를 지정해야 한다. 이 값이 NULL 의 경우는, 현재의 작업 디렉토리가 사용된다.
dwFlags
인스톨 대상이 되는 DirectX 컴퍼넌트를 나타내는 1 개(살) 또는 복수의 플래그. 추천은, 풀 인스톨 (DSETUP_DIRECTX).
DSETUP_D3D | 사용하지 않는다. 이 플래그를 사용하는 DirectX 3 의 프로그램은 모든 DirectX 컴퍼넌트를 인스톨 한다.
DSETUP_DDRAW | 사용하지 않는다. 이 플래그를 사용하는 DirectX 3 의 프로그램은 모든 DirectX 컴퍼넌트를 인스톨 한다.
DSETUP_DDRAWDRV | DirectX 7.0 에서는 사용하지 않는다.
DSETUP_DINPUT | 사용하지 않는다. 이 플래그를 사용하는 DirectX 3 의 프로그램은 모든 DirectX 컴퍼넌트를 인스톨 한다.
DSETUP_DIRECTX | DirectX 와 호환성이 있는 디스플레이 드라이버 및 오디오 드라이버에 가세해 DirectX 런타임 컴퍼넌트를 인스톨 한다.
DSETUP_DIRECTXSETUP | 사용하지 않는다. 이 플래그를 사용하는 DirectX 3 의 프로그램은 모든 DirectX 컴퍼넌트를 인스톨 한다.
DSETUP_DPLAY | 사용하지 않는다. 이 플래그를 사용하는 DirectX 3 의 프로그램은 모든 DirectX 컴퍼넌트를 인스톨 한다.
DSETUP_DPLAYSP | 사용하지 않는다. 이 플래그를 사용하는 DirectX 3 의 프로그램은 모든 DirectX 컴퍼넌트를 인스톨 한다.
DSETUP_DSOUND | 사용하지 않는다. 이 플래그를 사용하는 DirectX 3 의 프로그램은 모든 DirectX 컴퍼넌트를 인스톨 한다.
DSETUP_DSOUNDDRV | DirectX 7.0 에서는 사용하지 않는다.
DSETUP_DXCORE | DirectX 런타임 컴퍼넌트를 인스톨 한다. DirectX 와 호환성이 있는 디스플레이 드라이버와 오디오 드라이버는 인스톨 하지 않는다.
DSETUP_TESTINSTALL | 인스톨 내용을 테스트한다. 새로운 컴퍼넌트를 인스톨 할 것은 없다.
DSETUP_USEROLDERFLAG | -14 (을)를 돌려줄 수 있다. 이것은, 인스톨 되고 있는 DirectX 의 버젼이 인스톨 하는 버젼보다 새로운 일을 의미한다.

반환값

성공하면 DSETUPERR_SUCCESS 또는 DSETUPERR_SUCCESS_RESTART (변경 내용을 유효하게 하기 위해서 시스템을 재부팅 할 필요가 있는 경우)를 돌려준다. 실패하면 에러 코드를 돌려준다. 반환값에 대해서는, 「반환값」을 참조할것.

주의

셋업 프로그램으로 DirectXSetup 함수를 사용하기 전에, 시스템에 최저 15 MB 의 빈디스크 영역이 있는 것을 확인하는 것. 이것은 적절한 파일을 셋업 하기 위해서 DirectX 가 필요로 하는 최대 영역이다. 다만, 시스템에 DirectX 파일이 이미 존재하는 경우는 필요없다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsetup.h 로 선언.
임포트 라이브러리 : dsetup.lib 를 사용.


DirectXSetupCallbackFunction

DirectXSetupCallbackFunction 는, 옵션으로 셋업 프로그램으로 설정하는 콜백 함수의 플레이스홀더명이다. 설정된 콜백 함수는, 셋업 프로세스의 각 스텝 마다 한 번 두개 불려 간다.

DWORD DirectXSetupCallbackFunction(
  DWORD  Reason,
  DWORD  MsgType,
  char  *szMessage,
  char  *szName,
  void  *pInfo
);

파라미터

Reason
콜백의 이유. 다음의 몇개의 값을 취한다.
DSETUP_CB_MSG_BEGIN_INSTALL
DirectXSetup 가 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
사용하고 있는 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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsetup.h 로 선언.
임포트 라이브러리 : 유저 정의.

참조

MessageBox,DirectXSetupSetCallback ,셋업의 커스터마이즈


DirectXSetupGetVersion

DirectXSetupGetVersion 함수는, 현재 인스톨 되고 있는 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 | 0x00040001
DirectX 2 | 0x00040002
DirectX 3 | 0x00040003
DirectX 5,0 | 0x00040005
DirectX 6.0 | 0x00040006
DirectX 7,0 | 0x00040007

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 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsetup.h 로 선언.
임포트 라이브러리 : dsetup.lib 를 사용.

참조

DirectXSetup


DirectXSetupSetCallback

DirectXSetupSetCallback 함수는,DirectXSetup 로부터 주기적으로 불려 가는 콜백 함수에 포인터를 세트 한다. 콜백 함수는, 셋업의 진행 상황의 통지와 어플리케이션의 셋업 프로그램용의 커스텀 유저 인터페이스의 이행에 사용할 수가 있다. 상세한 것에 대하여는,DirectXSetupCallbackFunction 를 참조할것. 셋업 프로그램이 콜백 함수를 주지 않는 경우,DirectXSetupSetCallback 는 불려 가지 않는다.

INT WINAPI DirectXSetupSetCallback(
  DSETUP_CALLBACK  Callback
);

파라미터

Callback
콜백 함수의 주소.

반환값

현재 상태로서는 0 을 돌려준다.

주의

콜백 함수를 설정하려면 ,DirectXSetup 를 호출하기 전에 DirectXSetupSetCallback 를 호출하지 않으면 안 된다.

DirectXSetupSetCallback 에게 건네지는 콜백 함수의 이름은, 셋업 프로그램에 의해 주어지지만,DirectXSetupCallbackFunction 로 주어지는 prototype에 적합하는 것이 아니면 안된다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsetup.h 로 선언.
임포트 라이브러리 : dsetup.lib 를 사용.

참조

DirectXSetupCallbackFunction ,DirectXSetup


DirectXUnRegisterApplication

DirectXUnRegisterApplication 함수는, DirectPlayLobby 대응 어플리케이션의 등록을 삭제한다.

int WINAPI DirectXUnRegisterApplication(
  HWND   hWnd,
  LPGUID lpGUID
);

파라미터

hWnd
부모 윈도우의 핸들. 데스크탑이 부모 윈도우 때는, 이 파라미터에 NULL 를 설정한다.
lpGUID
삭제 대상이 되는 DirectPlay 어플리케이션의 GUID 의 주소.

반환값

성공하면, 등록 삭제가 완료한 것을 나타내는 TRUE 를 돌려준다. 실패하면 FALSE 를 돌려준다.

주의

DirectXUnRegisterApplication 함수에서는, 시스템에 인스톨되어 있지 않은 dsetup.dll 와 dsetup32.dll 의 양쪽 모두가 필요하지만, 양쪽 모두 SDK 에 준비되어 있다.

DirectXRegisterApplication 함수는, 어플리케이션이 DirectPlayLobby 로 동작하는데 필요한 레지스트리 엔트리를 삽입하지만, 로비 어플리케이션의 인스톨과 언인스톨에는,IDirectPlayLobby3::RegisterApplication 와 IDirectPlayLobby3::UnregisterApplication 의 각 메소드의 사용을 추천 한다. 어플리케이션의 인스톨시에 DirectXRegisterApplication 를 사용했을 경우는, 언인스톨 프로그램으로 반드시 DirectXUnRegisterApplication 를 사용해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsetup.h 로 선언.
임포트 라이브러리 : dsetup.lib 를 사용.

참조

DirectXRegisterApplication


구조체

여기에서는, DirectSetup 로 사용되는 이하의 구조체에 대해 설명한다.

  • DIRECTXREGISTERAPP
  • DSETUP_CB_UPGRADEINFO

주 : DirectX 구조체의 메모리는 모두, 사용전에 0 에 초기화해야 한다. 또,dwSize 멤버를 가지는 모든 구조체는, 사용전에 이 멤버를 구조체의 사이즈 (바이트 단위)로 설정해야 한다. 이러한 태스크를 구조체 DDCAPS 로 실행하고 있는 Microsoft® DirectDraw® 의 예를 다음에 나타낸다.

DDCAPS ddcaps; // 이 구조체는 아직 사용할 수 없다.

ZeroMemory(&ddcaps, sizeof(ddcaps));
ddcaps.dwSize = sizeof(ddcaps);

// 구조체는 사용 가능.
.
.


DIRECTXREGISTERAPP

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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsetup.h 로 선언.


DSETUP_CB_UPGRADEINFO

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
컴퍼넌트가 업그레이드 되지 않으면, Windows 가 정상적으로 기능하지 않을 우려가 있다. 업그레이드는 실행된다.
DSETUP_CB_UPGRADE_HASWARNINGS
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 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsetup.h 로 선언.

참조

DirectXSetupCallbackFunction


반환값

DirectXSetup 함수는 이하의 값을 돌려준다. 이 함수에서는 표준 COM 에러를 돌려줄 수도 있다.

DSETUPERR_SUCCESS
셋업이 성공했다. 재부팅의 필요는 없다.
DSETUPERR_SUCCESS_RESTART
셋업이 성공했다. 재부팅 할 필요가 있다.
DSETUPERR_BADSOURCESIZE
파일 사이즈를 검증할 수 없었는지, 잘못이었다.
DSETUPERR_BADSOURCETIME
파일의 일자 및 타임을 검증할 수 없었는지, 잘못이었다.
DSETUPERR_BADWINDOWSVERSION
DirectX 는 이 버젼의 Windows 를 지원 하고 있지 않다.
DSETUPERR_CANTFINDDIR
셋업 프로그램으로 작업 디렉토리가 발견되지 않았다.
DSETUPERR_CANTFINDINF
필요한 . inf 파일이 발견되지 않았다.
DSETUPERR_INTERNAL
내부 에러가 발생했다.
DSETUPERR_NEWERVERSION
DirectX 의 상위 버젼이 이미 인스톨 되고 있다. 상위 버젼이 덧쓰기될 것은 없고, 이전의 버젼용으로 기술된 어플리케이션과도 완전하게 호환성이 있기 (위해)때문에, 어플리케이션은 안전하게 이 에러를 무시할 수 있다.
DSETUPERR_NOCOPY
파일의 버젼을 검증할 수 없었는지, 잘못이었다.
DSETUPERR_NOTPREINSTALLEDONNT
시스템의 Windows NT 또는 Windows 2000 의 버젼에, DirectX 의 최신 버젼이 포함되지 않았다. DirectX 의 낡은 버젼이 존재하는지, DirectX 목의 버젼도 존재하지 않는지, 어느 쪽인가의 가능성이 있다.
DSETUPERR_OUTOFDISKSPACE
셋업 프로그램에 의한 인스톨중에 디스크 영역이 부족하게 되었다.
DSETUPERR_SOURCEFILENOTFOUND
필요한 소스 파일 가운데중 한쪽이 발견되지 않았다.
DSETUPERR_UNKNOWNOS
지원되어 있지 않은 버젼의 operating system이다.
DSETUPERR_USERHITCANCEL
어플리케이션의 인스톨이 완료하기 전에,[Cancel] 버튼이 밀렸다.


DirectSetup 샘플

DirectSetup 의 사용 방법 및 기능을 설명하는 샘플로서 다음의 프로그램이 제공되고 있다.

  • Dinstall 샘플 (C/C++)
  • DXVBSetup 샘플 (Visual Basic)

DirectX 샘플에는 Microsoft® Visual C++® 의 프로젝트 워크 스페이스 파일이 포함되어 있지만, 각자의 개발 환경에서 올바르게 컴파일 할 수 있도록(듯이) 다른 설정을 확인할 필요가 있는 경우가 있다. 상세한 것에 대하여는, 「DirectX 의 샘플 및 그 외의 DirectX 어플리케이션의 컴파일」을 참조할것.


Dinstall 샘플

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DXVBSetup 샘플」을 참조할것.

[C++]

설명

Dinstall 는, DirectSetup 함수를 사용해 DirectX 서브 시스템 및 DirectX 드라이버를 인스톨 하는 샘플이다. 여기에서는, 콜백 함수를 사용해, 커스텀 인터페이스 (이 경우는 신풀궶드레스다이아로그복스) 경유로 메세지의 표시와 유저 입력의 취득을 실시하는 예를 나타내고 있다.

패스

소스 파일 :(SDK 루트)\Samples\Multimedia\Dxmisc\Src\Setup

유저즈 가이드

우선, DirectX SDK CD 의 \Redist\DirectX7 폴더의 내용을 모두 Dinstall.exe 와 같은 폴더에 카피한다. 개발 환경의 작업 디렉토리도 이 폴더로 설정한다 (Microsoft® Visual C++® 에서는,[Project Settings] 다이알로그 박스의 [Debug] 페이지에 이 설정이 있다).

프로그램을 실행해,[File] 메뉴의 [Start Install] 를 클릭한다. DirectSetup 는, DirectX 의 모의 인스톨을 실행해 ( 「프로그래밍 위에의 주의」를 참조), 모드레스다이아로그복스에 진척 상황을 표시한다. [Options] 메뉴에서는, 표시하는 메세지 레벨을 변경할 수 있다. 다만, 모의 인스톨만을 실시하는 경우는, 문제 발생 메세지나 업데이트 메세지는 표시되지 않는다.

[File] 메뉴의 [Get Version] 를 클릭 하면, 시스템에 현재 인스톨 되고 있는 DirectX 의 버젼 번호 및 리버젼 번호가 표시된다.

프로그래밍 위에의 주의

\Redist\DirectX7\Directx\Drivers 의 각 드라이버 폴더에는, Microsoft 가 제공하는 DirectX 드라이버의 로컬라이즈 버젼이 보존되고 있다. 디스크 용량을 절약하고 싶은 경우는, 작업 디렉토리로부터 이러한 폴더를 적당 삭제 하면이야 있고.

디폴트에서는, 프로그램은 DirectXSetup 함수에 DSETUP_TESTINSTALL 를 건네준다. 이것은, 실제로 파일은 카피되지 않고, 레지스트리의 변경도 행해지지 않는 것을 나타낸다. 실제로 인스톨을 실시하려면 , 이 플래그를 함수 호출로부터 삭제한다.

Dinstall 에서는, 인스톨 진척 상황의 감시나 메세지의 인터셉트에 콜백 함수를 사용하고 있다. 유저가 지정한 경고 레벨 (g_fStatus 로 추적)에 응해, 메세지를 무시하거나 모드레스다이아로그복스에 메세지를 표시하거나 할 수 있다. 유저 입력이 필요한 경우는 적절한 버튼이 표시되어 몇개의 버튼이 밀릴 때까지 GetReply 함수가 메시지 큐를 감시한다.


DXVBSetup 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Dinstall 샘플」을 참조할것.

[Visual Basic]

설명

DXVBSetup 샘플은, DirectSetup 를 Visual Basic 어플리케이션으로 사용하는 방법을 나타낸 것이다.

패스

Visual Basic 5 소스 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\Dxmisc\Src\DXVB5Setup

Visual Basic 6 소스 파일 :(SDK 루트)\Samples\Multimedia\VBSamples\Dxmisc\Src\DXVB6Setup

유저즈 가이드

셋업 어플리케이션 디렉토리에는, dsetup.dll 및 dsetup32.dll 를 포함한 Setup 라고 하는 서브 폴더가 없으면 안 된다. 또, 이 안에는 「DirectX」 (대문자 소문자의 구별 없음)이라는 이름의 폴더를 준비해, 재배포 가능한 모든 파일 및 드라이버를 보존한다. 올바른 구조의 어플리케이션 셋업 디스크는, DirectX SDK 디스크의 Dx\Redist\DirectX7 폴더의 내용을 모두 셋업 프로그램의 루트 패스에 카피하는 것만으로 생성 할 수 있다. 이 폴더는, SDK 의 인스톨시에 개발용의 머신에 카피되지 않기 때문에, 오리지날 디스크로부터 별도 카피할 필요가 있다.

프로그래밍 위에의 주의

\Redist\DirectX7\Directx\Drivers 의 각 드라이버 폴더에는, Microsoft 가 제공하는 DirectX 드라이버의 로컬라이즈 버젼이 보존되고 있다. 디스크 용량을 절약하고 싶은 경우는, 작업 디렉토리로부터 이러한 폴더를 적당 삭제 하면이야 있고.


DirectSound

여기에서는, Microsoft DirectX® 어플리케이션 프로그래밍 인터페이스 (API)의 DirectSound® 컴퍼넌트에 관한 정보를 이하의 주제로 나누어 설명한다.

  • DirectSound 에 대해
  • DirectSound 를 사용하는 이유
  • DirectSound 아키텍쳐
  • DirectSound 의 요점
  • DirectSound 튜토리얼
  • DirectSound 레퍼런스
  • DirectSound 의 툴과 샘플


DirectSound 에 대해

Microsoft® DirectSound® 어플리케이션 프로그래밍 인터페이스 (API)는, DirectX® API 의 웨이브 오디오 컴퍼넌트이다. DirectSound 는, 지연 시간 (지연시간)이 적은 믹싱, 하드웨어 가속화, 사운드 디바이스에의 직접 액세스를 실현한다. 기존의 디바이스 드라이버와의 사이의 호환성을 유지하면서, 이 기능을 제공한다.

DirectSound 에 의해, 웨이브 사운드의 캡춰와 재생이 가능하게 된다. 또 C++ 에서는 프로퍼티 세트도 지원 해, 어플리케이션 개발자는, 사운드 카드와 관련 드라이버의 제공하는 확장 서비스를 활용할 수 있다.


DirectSound 를 사용하는 이유

DirectX 의 최우선의 설계 목표는 스피드에 있다. DirectX 외 컴퍼넌트와 같이, DirectSound 는 디바이스에 의존하지 않는 인터페이스를 채용해, 개발자에게 하드웨어 개별의 상세한 지식을 요구하는 일 없이, 하드웨어를 최고의 효율로 사용할 수 있도록(듯이) 한다. 어플리케이션은 가장 간소한 오디오 하드웨어로도 적절히 동작하지만, DirectSound 용으로 기능확장 된 카드나 드라이버의 특별한 기능도 활용할 수 있다.

그 밖에도 DirectSound 는 이하를 용이하게 한다.

  • 실행시에 하드웨어 능력을 문의해 특정의 퍼스널 컴퓨터의 구성에 대한 최선의 솔루션을 결정한다.
  • C++ 로 프로그래밍 하는 경우, 프로퍼티 세트를 사용하는 것에 의해, DirectSound 가 하드웨어를 직접 지원 하고 있지 않는 경우에서도, 새로운 하드웨어의 능력을 활용할 수 있도록(듯이) 한다.
  • 응답을 고속화하기 위해(때문에), 오디오 스트림의 지연 시간의 적은 믹싱을 실시한다.
  • 3D 사운드를 이행 한다.
  • 사운드를 캡춰 한다.

DirectSound 에는 이러한 이점이 있지만, 특정의 상황에서는 Windows® 표준의 웨이브 폼 오디오 기능이 계속해 실용적인 솔루션이 된다. 예를 들어, 어플리케이션은 PlaySound 나 waveOut 의 각 함수를 사용해, 도입 뮤직과 같은 단일의 사운드 또는 오디오 스트림을 용이하게 연주할 수 있다.


DirectSound 아키텍쳐

여기에서는, DirectSound 컴퍼넌트를 소개해, DirectSound 를 하드웨어나 다른 어플리케이션과 조합했을 때에 어떻게 동작하는지를 설명한다. 이하의 토픽에 대해 설명한다.

  • DirectSound 아키텍쳐의 개요
  • 사운드 데이터
  • 재생의 개요
  • 캡춰의 개요
  • 프로퍼티 세트의 개요
  • 하드웨어 추상과 에뮬레이션
  • 시스템의 통합


DirectSound 아키텍쳐의 개요

DirectSound 는, 디지털 사운드의 샘플의 재생과 캡춰 링, 및 샘플 소스의 믹싱용의 새로운 모델을 이행 하고 있다. DirectX API 외 요소와 같이, DirectSound 는 하드웨어의 기능을 최대한으로 꺼내, 하드웨어가 지원 하고 있지 않는 특정의 기능을 소프트웨어로 에뮬레이트 한다.

[C++]

DirectSound 의 재생 기능은,IDirectSound 컴퍼넌트 오브젝트 모델 (COM) 인터페이스와 사운드 버퍼 및 3D 이펙트를 조작하는 다른 인터페이스에 의해 구축되고 있다. 이러한 인터페이스는,IDirectSoundBuffer ,IDirectSound3DBuffer ,IDirectSound3DListener 이다.

DirectSound 캡춰는,IDirectSoundCapture 및 IDirectSoundCaptureBuffer 의 각 COM 인터페이스에 근거하고 있다.

이제(벌써) 1 개의 COM 인터페이스인 IKsPropertySet 는, 장래 채용되는 것도 포함한 사운드 카드의 확장 기능을 어플리케이션이 활용하기 위한 수단을 제공한다.

마지막에 IDirectSoundNotify 인터페이스는, 재생이나 캡춰가 버퍼의 특정의 포인트에 이르렀을 때에, 이벤트의 시그널을 보낸다.

DirectX API 를 사용한 어플리케이션을 생성 하기 위해서 이해해야 할 COM 의 개념에 대해서는, 「컴퍼넌트 오브젝트 모델」을 참조할것.

[Visual Basic]

DirectSound 의 재생 기능은,DirectSound 클래스와 사운드 버퍼 및 3D 이펙트를 조작하는 다른 클래스에 의해 구축되고 있다. 이러한 클래스는,DirectSoundBuffer ,DirectSound3DBuffer ,DirectSound3DListener 이다.

DirectSound 캡춰는,DirectSoundCapture 및 DirectSoundCaptureBuffer 의 각 클래스에 근거하고 있다.

마지막에 DirectXEvent 클래스는, 재생이나 캡춰가 버퍼의 특정의 포인트에 이르렀을 때에,DirectX7.CreateEvent 메소드로 생성 된 이벤트와 함께 이벤트의 시그널을 보낸다.


사운드 데이터

[C++]

IDirectSound 와 IDirectSoundCapture 는, 고정 주파수의 사운드에 의해 구성되는 웨이브 폼 오디오 데이터를 사용해 기능을 완수한다. 사운드의 특정의 포맷은,WAVEFORMATEX 구조체를 사용해 기술할 수 있다. 이 구조체는 Platform SDK 문서의 「Multimedia Structures」로 문서화 되고 있지만, 간편을 위해서(때문에) 여기에서도 간단하게 설명한다.

typedef struct {
    WORD  wFormatTag;
    WORD  nChannels;
    DWORD nSamplesPerSec;
    DWORD nAvgBytesPerSec;
    WORD  nBlockAlign;
    WORD  wBitsPerSample;
    WORD  cbSize;
} WAVEFORMATEX;

wFormatTag 멤버는, Microsoft 가 할당한 일의의 식별자를 보관 유지한다. 완전한 리스트는 헤더 파일 Mmreg.h 에 기술되고 있다. DirectSound 로 유효한 유일한 태그는 WAVE_FORMAT_PCM 이다. 이 태그는 PCM (Pulse Code Modulation), 즉 각 샘플이 샘플링 시점에서의 진폭의 신호를 나타내는 비압축 포맷을 의미한다. DirectSoundCapture 는, Audio Compression Manager 를 사용하는 것으로, 다른 포맷의 데이터도 캡춰 할 수 있다.

DirectSound 로 PCM 이외의 데이터를 취급하는 방법의 상세한 것에 대하여는, 「압축 웨이브 포맷」을 참조할것.

nChannels 멤버는, 채널의 수를 기술한다. 보통은 1 (단청의)이나 2 (스테레오)이다. 스테레오 데이터의 경우, 샘플은 인터리브 된다. nSamplesPerSec 멤버는, 샘플링 레이트 (샘플링 주파수)를 헤르쯔 (Hz) 단위로 기술한다. 표준적인 값은, 11,025, 22,050, 44,100 이다.

wBitsPerSample 멤버는, 각 샘플의 사이즈를 기술한다. 보통은 8 비트나 16 비트이다. nBlockAlign 의 값은, 완전한 샘플을 기록하는데 필요한 바이트수를 의미해, PCM 포맷에서는 (wBitsPerSample * nChannels / 8)에 동일한 값이 된다. nAvgBytesPerSec 의 값은,nBlockAlign 와 nSamplesPerSec 의 적이다.

마지막으로,cbSize 는 특별한 웨이브 포맷을 기술하는데 필요한 추가 필드의 사이즈를 나타낸다. PCM 포맷에서는, 이 멤버의 값은 항상 0 이다.

[Visual Basic]

DirectSound 와 DirectSoundCapture 는, 고정 주파수의 사운드에 의해 구성되는 웨이브 폼 오디오 데이터를 사용해 기능을 완수한다. 사운드의 포맷은,WAVEFORMATEX 형을 사용해 기술할 수 있다.


재생의 개요

DirectSoundBuffer 오브젝트는, 사운드 데이터를 보관 유지하는 버퍼를 나타낸다. 버퍼 오브젝트는, 사운드의 재생의 시작, 정지, 일시정지와 주파수나 포맷등의 속성을 설정하기 위해서 사용된다.

프라이머리 사운드 버퍼는, 청취자가 실제로 (듣)묻는 오디오를 보관 유지한다. 각세컨드리 사운드 버퍼는, 1 개의 사운드 또는 오디오 스트림을 보관 유지한다. DirectSound 는 자동적으로 프라이머리 버퍼를 생성 하지만, 세컨드리 버퍼는 어플리케이션이 생성 해야 한다. 세컨드리 버퍼내의 사운드가 재생되면(자), DirectSound 는 프라이머리 버퍼내에서 이것들을 믹싱 해, 출력 디바이스에 배웅한다. DirectSound 를 믹싱 할 수 있는 버퍼수는 처리 시간에게만 제한되어 처리 시간이 허락하는 한 믹싱 할 수가 있다.

1 개의 사운드 디바이스에 대해서 복수의 어플리케이션이 DirectSound 오브젝트를 생성 할 수가 있다. 입력초점이 있는 어플리케이션으로부터 다른 어플리케이션에 이동할 때에, 오디오 출력은 있는 어플리케이션의 스트림으로부터 다른 어플리케이션의 스트림으로 자동적으로 바뀐다. 따라서, 입력초점이 이동할 때에, 어플리케이션은 버퍼의 재생과 정지를 반복할 필요는 없다.

[C++]

데이터를 올바른 포맷에 정돈해 세컨드리 버퍼에 보내는 것은, 개발자의 책임이다. DirectSound 에는, 사운드 파일이나 웨이브 리소스를 해석하는 기능은 없다. 그러나, 관련하는 샘플 어플리케이션내에, 이 태스크를 지원하는 코드가 기술되고 있다. 상세한 것에 대하여는, 「웨이브 파일의 사용법」이라고, 「리소스로부터의 웨이브 데이터의 read」를 참조할것.

어플리케이션은 IDirectSoundNotify 인터페이스를 통해, 스트림 버퍼가 새로운 데이터를 수신할 준비를 할 수 있었을 때나, 버퍼중 한쪽이 정지했을 때에 그것을 파악할 수 있다. 현재 플레이 포지션이 이러한 위치의 어느 쪽인가에 도달 하면, 신호가 송신된다. 대신에, 어플리케이션은 재생 커서의 위치를 정기적으로 폴링 할 수도 있다.

[Visual Basic]

짧은 웨이브 파일과 리소스는, 버퍼가 생성 되면(자) 세컨드리 버퍼에 직접 로드 된다. 한층 더 긴 파일에서는, 파일을 해석해 데이터를 보내는 것은 개발자의 책임이다. 상세한 것에 대하여는, 「웨이브 파일의 사용법」이라고, 「리소스로부터의 웨이브 데이터의 read」를 참조할것.

어플리케이션은 DirectX7.CreateEvent 메소드로 이벤트를 생성 하고 나서 DirectSoundBuffer.SetNotificationPositions 메소드를 호출해 통지 위치를 설정하는 것으로써, 스트림 버퍼가 새로운 데이터를 수신할 준비를 할 수 있었을 때나, 버퍼중 한쪽이 정지했을 때에 그것을 파악할 수 있다. 현재 플레이 포지션이 이러한 위치의 어느 쪽인가에 도달 하면, 신호가 송신된다. 대신에, 어플리케이션은 현재 플레이 포지션을 정기적으로 폴링 할 수도 있다.

통지의 상세한 것에 대하여는, 「재생 버퍼의 통지」를 참조할것.


캡춰의 개요

[C++]

DirectSoundCapture 오브젝트는, 사운드 캡춰 디바이스의 능력의 문의나, 입력 소스로부터 오디오를 캡춰하기 위한 버퍼의 생성에 사용된다. DirectSoundCapture 를 사용하면(자), PCM 포맷 또는 압축 포맷으로 데이터를 캡춰 할 수 있다.

DirectSoundCaptureBuffer 오브젝트는, 입력 디바이스로부터 데이터를 캡춰 하기 위해서 사용되는 버퍼를 나타낸다. 재생 버퍼와 같이, 이 버퍼는 순환이라고 하는 개념을 채용하고 있다. 입력 포인터가 버퍼의 마지막에 도달 하면, 자동적으로 시작점에 돌아온다.

DirectSoundCaptureBuffer 오브젝트의 메소드를 사용하면(자), 버퍼의 프로퍼티의 취득, 오디오 캡춰의 시작과 정지, 메모리의 일부의 락이 생기므로, 파일에 보존하는 등의 목적으로 데이터를 안전하게 취득할 수 있다.

재생의 경우와 같이, DirectSound 는, 캡춰 한 데이터가 버퍼내의 지정된 위치에 도달했을 때나, 캡춰 링이 정지했을 때에, 그 취지를 통지하도록(듯이) 요구할 수가 있다. 이 서비스는,IDirectSoundNotify 인터페이스로 제공된다.

[Visual Basic]

DirectSoundCapture 오브젝트는, 사운드 캡춰 디바이스의 능력의 문의나, 입력 소스로부터 오디오를 캡춰하기 위한 버퍼의 생성에 사용된다. DirectSoundCapture 를 사용하면(자), PCM 포맷 또는 압축 포맷으로 데이터를 캡춰 할 수 있다.

DirectSoundCaptureBuffer 오브젝트는, 입력 디바이스로부터 데이터를 캡춰 하기 위해서 사용되는 버퍼를 나타낸다. 재생 버퍼와 같이, 이 버퍼는 순환이라고 하는 개념을 채용하고 있다. 입력 포인터가 버퍼의 마지막에 도달 하면, 자동적으로 시작점에 돌아온다.

DirectSoundCaptureBuffer 오브젝트의 메소드를 사용하면(자), 버퍼의 프로퍼티의 취득, 오디오 캡춰의 시작과 정지, 메모리의 일부의 락이 생기므로, 파일에 보존하는 등의 목적으로 데이터를 안전하게 취득할 수 있다.

재생의 경우와 같이, DirectSound 는, 캡춰 한 데이터가 버퍼내의 지정된 위치에 도달했을 때나, 캡춰 링이 정지했을 때에, 그 취지를 통지하도록(듯이) 요구할 수가 있다. 이 서비스는,DirectX7.CreateEvent 메소드로 이벤트를 생성 해,DirectSoundCaptureBuffer.SetNotificationPositions 메소드로 통지 위치를 설정하는 것으로써 제공된다.

통지의 상세한 것에 대하여는, 「캡춰 버퍼의 통지」를 참조할것.


프로퍼티 세트의 개요

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

DirectSound 는 프로퍼티 세트를 통해, 사운드 카드와 관련 드라이버의 메이커가 제공하는 확장 서비스를 지원 할 수 있다.

하드웨어 벤더는 새로운 능력을 프로퍼티로서 정의해, 그 프로퍼티의 사양을 발표한다. 이 문서의 대상 독자인 어플리케이션 개발자는,IKsPropertySet 인터페이스의 메소드를 사용해, 목적의 하드웨어상에서 특정의 프로퍼티 세트가 제공되고 있는지 어떤지를 확인해, 예를 들어 개별의 특수 효과의 온, 오프를 실시해, 그러한 프로퍼티를 조작할 수 있다.

프로퍼티 세트는, DirectSound 의 능력을 무제한하게 확장할 것을 전망한 것이다. 개발자는 IKsPropertySet::Set 라고 하는 1 개의 메소드를 사용해, 메이커의 사양에 근거해 임의의 방법으로 디바이스 상태를 변경할 수 있다.

상세한 것에 대하여는, 「DirectSound 프로퍼티 세트」를 참조할것.


하드웨어 추상과 에뮬레이션

DirectSound 는, 오디오 디바이스 드라이버가 이행 하는 인터페이스, 즉 DirectSound 하드웨어 추상 계층 (HAL)을 사용해 사운드 기기에 액세스 한다.

DirectSound HAL 는, 이하의 기능을 제공한다.

  • 오디오 기기에 대한 컨트롤의 취득과 릴리즈
  • 오디오 기기의 능력의 평가
  • 하드웨어가 이용 가능한 경우의 특정의 조작의 실행
  • 하드웨어가 이용 불가능한 경우에 장해를 보고하는 조작의 요구

디바이스 드라이버는, 소프트웨어 에뮬레이션을 일절 실시하지 않는다. 하드웨어의 능력을 DirectSound 에 통지해, DirectSound 로부터의 요구를 하드웨어에게 전하는 것만으로 있다. 요구된 조작을 하드웨어를 실행할 수 없는 경우에는, 디바이스 드라이버가 요구의 실패를 보고한 후, DirectSound 가 그 조작을 에뮬레이트 한다.

DirectX 의 실행시 파일이 유저의 시스템상에 있는 한, 어플리케이션은 DirectSound 를 이용할 수 있다. 사운드 기기에 대응하는 DirectSound 드라이버가 이행되어 있지 않은 경우는, DirectSound 는 Windows 의 멀티미디어 웨이브 폼 오디오 함수 (waveIn 와 waveOut)를 이용한 하드웨어 에뮬레이션 계층 (HEL)을 사용한다. DirectSound 의 대부분의 기능은, HEL 를 통해 이용할 수 있지만, 하드웨어 가속화는 당연 불가능하다. 어플리케이션이 에뮬레이션 드라이버를 사용해 동작하고 있을지 어떨지를 조사하려면 , C++ 의 IDirectSound::GetCaps 메소드, 또는 Visual Basic 의 DirectSound.GetCaps 메소드를 호출해, DSCAPS_EMULDRIVER 플래그를 체크한다.

DirectSound 는, 하드웨어 믹싱이나 하드웨어 사운드 버퍼 메모리등의 사운드 기기의 가속화 기능을 자동적으로 활용한다. 이 하드웨어 가속화를 사용할 때에, 어플리케이션으로부터 하드웨어나 프로그램에 특별히 문의할 필요는 없다. 다만, 하드웨어 리소스를 최대한으로 이용하려면 , (다양한 GetCaps 메소드를 사용해) 실행시에 DirectSound 에의 문의를 실시해 사운드 기기의 능력의 전정보를 입수해, 특정의 기능의 유무에 응해 최적의 루틴을 사용한다. 또, 어느 사운드 버퍼에 하드웨어 가속화를 적용하는지를 지정할 수도 있다.


시스템의 통합

다음의 그림은, DirectSound 와 다른 시스템 오디오 컴퍼넌트와의 관계를 나타내고 있다.

DirectSound 함수와 Windows 표준의 웨이브 폼 오디오 함수를 사용하면(자), 사운드 기기의 웨이브 폼 오디오 부분에의 패스에 선택사항이 주어진다. 1 개의 디바이스에서는, 한 번에 액세스를 제공하는 패스는 1 개이다. 웨이브 폼 오디오 드라이버가 있는 디바이스를 할당했을 경우, DirectSound 에서의 동디바이스에의 할당은 실패한다. 같이 DirectSound 가 1 개의 디바이스를 할당했을 경우, 웨이브 폼 오디오 드라이버에서의 디바이스의 할당은 실패한다.

2 개의 사운드 디바이스가 시스템에 인스톨 되고 있는 경우, 어플리케이션은 DirectSound 함수와 웨이브 폼 오디오 함수의 어느 쪽인지를 사용해, 각각의 디바이스에 독립해 액세스 할 수 있다.

주 : Microsoft Video for Windows 는 현재, 웨이브 폼 오디오 함수를 사용해, avi (audio visual interleaved, 오디오 비디오 인터리브) 파일의 오디오 트랙을 재생한다. 따라서, 어플리케이션이 DirectSound 를 사용하고 있을 때, 유저가 동시에 avi 파일을 재생하려고 해도, 그 오디오 트랙을 (들)물을 수 없다. 같이 avi 파일의 재생과 DirectSound 오브젝트의 생성을 동시에 실시하려고 하면, 생성 함수는 에러를 돌려준다.

현재로서는, 어플리케이션이 DirectSound 오브젝트를 릴리즈 하기 위해서는, avi 파일을 재생하기 전에 C++ 의 IDirectSound::Release 를 호출하는지, Visual Basic 의 DirectSound 오브젝트를 Nothing 로 설정한다. 어플리케이션은, 비디오의 재생 종료후에 오브젝트와 그 버퍼 오브젝트의 생성과 초기화를 한번 더 실시할 수 있다.


DirectSound 의 요점

여기에서는, 사운드의 재생과 캡춰를 행하기 위한 다양한 DirectSound 인터페이스의 사용법의 개요를 기술한다. 이하의 토픽에 대해 설명한다.

  • DirectSound 디바이스
  • DirectSound 버퍼
  • DirectSound 의 3D 에의 응용
  • DirectSound 3D 버퍼
  • DirectSound 3D 청취자
  • DirectSoundCapture
  • DirectSound 프로퍼티 세트
  • DirectSound 의 성능의 최적화
  • 웨이브 파일의 사용법
  • 리소스로부터의 웨이브 데이터의 read
[C++]

주 : 이 주제의 메소드 호출해 예의 대부분은 C 언어 형식에서 주어져 함수에의 포인터로부터 완성되는 테이블에의 포인터를 사용해 메소드에 액세스 하지만, 어느 호출에서도 이 포인터를 최초의 파라미터로 할 필요가 있다. 예를 들어, C 로부터 IDirectSound::GetCaps 메소드를 호출하면나무는, 다음의 형태를 취한다.

lpDirectSound->lpVtbl->GetCaps(lpDirectSound, &dscaps);

C++ 형식에서 같은 메소드를 호출하면나무는, COM 인터페이스 메소드를 클래스 메소드와 같이 취급해, 다음과 같이 된다.

lpDirectSound->GetCaps(&dscaps);

Dsound.h 에 정의되고 있는 매크로는, 환경에 응해, C 와 C++ 어느 쪽의 형식의 메소드 호출도 확장한다. 이러한 매크로는 C 에 의한 호출을 간이화 해, 어느 쪽의 언어에서도 이용할 수 있는 루틴을 개발 가능하게 한다. 예를 들어, 다음과 같이 할 수 있다.

IDirectSound_GetCaps(lpDirectSound, &dscaps);

[C++, Visual Basic]


DirectSound 디바이스

어플리케이션에 DirectSound 를 이행 하는 최초의 스텝은, 사운드 디바이스를 나타내는 DirectSound 오브젝트를 생성 하는 것이다.

여기에서는, 이용 가능한 사운드 디바이스의 열거, 디바이스에 대한 DirectSound 오브젝트의 생성, 오브젝트의 메소드를 사용한 협조 레벨의 설정, 디바이스 능력의 취득, 사운드 버퍼의 생성, 시스템 스피커의 구성, 하드웨어 메모리의 압축을 어플리케이션이 실시하는 방법에 대해 설명한다.

  • 사운드 디바이스의 열거
  • DirectSound 오브젝트의 생성
  • 협조 레벨
  • 디바이스의 능력
  • 스피커의 구성
  • 하드웨어 메모리의 압축


사운드 디바이스의 열거

[C++]

유저가 좋아하는 재생장치로 단순하게 사운드를 재생할 뿐(만큼)의 어플리케이션에서는, 이용 가능한 디바이스를 열거할 필요는 없다. 디바이스 식별자로서 NULL 를 지정해 DirectSound 오브젝트를 생성 하는 경우, 디폴트의 디바이스가 존재 하면, 인터페이스는 자동적으로 그 디바이스에 관련지을 수 있다. 디바이스 드라이버가 존재하지 않는 경우는,DirectSoundCreate 함수의 호출은 실패한다.

그러나, 특정의 종류의 디바이스를 찾고 있는 경우나, 복수의 디바이스를 사용해 동작할 필요가 있는 경우는, 시스템상에서 이용 가능한 디바이스를 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,
        &hCombo))
{
    EndDialog( hDlg, TRUE );
    return( TRUE );
}

이 예에서는, combobox의 핸들의 주소는 DirectSoundEnumerate 에 보내져 다음에 콜백 함수에게 건네진다. 이 파라미터는, 콜백 함수내에서 액세스 하고 싶은 임의의 32 비트의 값으로 할 수가 있다.

[Visual Basic]

유저가 좋아하는 재생장치로 단순하게 사운드를 재생할 뿐(만큼)의 어플리케이션에서는, 이용 가능한 디바이스를 열거할 필요는 없다. 디바이스 식별자로서 하늘의 캐릭터 라인을 건네주어 DirectSound 오브젝트를 생성 하는 경우, 디폴트의 디바이스가 존재 하면, 오브젝트는 자동적으로 그 디바이스에 관련지을 수 있다. 디바이스 드라이버가 존재하지 않는 경우는,DirectX7.DirectSoundCreate 메소드의 호출은 실패한다.

그러나, 특정의 종류의 디바이스를 찾고 있는 경우나, 복수의 디바이스를 사용해 동작할 필요가 있는 경우는, 시스템상에서 이용 가능한 디바이스를 DirectSound 에 열거시키지 않으면 안 된다.

열거는 3 개의 목적으로 사용된다.

  • 이용 가능한 하드웨어를 보고.
  • 각 디바이스에 GUID 를 공급.
  • 각 디바이스를 열거했을 때에, 디바이스에 대해서 DirectSound 를 초기화. 그 결과, 각 디바이스의 능력을 체크할 수 있다.

디바이스를 열거하려면 ,DirectX7.GetDSEnum 메소드를 최초로 호출해, DirectSound 의 이용 가능한 디바이스의 콜렉션을 보관 유지하는 DirectSoundEnum 오브젝트를 생성 해야 한다. 이용 가능한 디바이스수를 결정하려면 ,DirectSoundEnum.GetCount 메소드를 호출한다. 그리고 각 디바이스의 정보는,DirectSoundEnum.GetDescription ,DirectSoundEnum.GetGuid ,DirectSoundEnum.GetName 의 각 메소드를 호출해, 콜렉션내의 특정의 디바이스를인덱스인수로서 건네주는 것으로 취득한다.


DirectSound 오브젝트의 생성

[C++]

DirectSound 오브젝트를 생성 하는 가장 간단한 방법은,DirectSoundCreate 함수를 사용하는 것이다. 이 함수의 최초의 파라미터는, 이 오브젝트에 관련지을 수 있는 디바이스의 GUID 를 지정한다. 이 GUID 는, 「사운드 디바이스의 열거」로 취득할 수 있다. 그 밖에, 디폴트의 디바이스에 대응하는 오브젝트를 생성 하려면 , 단순하게 NULL 를 건네주면 좋다.

LPDIRECTSOUND lpds;
HRESULT hr = DirectSoundCreate(NULL, &lpds, NULL));

사운드 디바이스가 존재하지 않는 경우나, 웨이브 폼 오디오 함수 (DirectSound 는 아니다)를 이용하는 어플리케이션이 사운드 디바이스를 제어하고 있는 경우는, 이 함수는 에러를 돌려준다. 어플리케이션은 이 호출이 실패했을 경우에 대비해, 사운드없이 어플리케이션을 속행하는지, 이미 사운드 디바이스를 사용하고 있는 어플리케이션을 닫도록(듯이) 유저에게 prompt를 표시하는지, 어느 쪽인가의 준비를 할 필요가 있다.

CoCreateInstance 함수를 사용해, 다음과 같이 DirectSound 오브젝트를 생성 할 수도 있다.

  1. 어플리케이션의 기동시에 CoInitialize 를 호출해, NULL 를 지정해 COM 를 초기화한다.
    if FAILED(CoInitialize(NULL))
    return FALSE;
  2. DirectSoundCreate 함수는 아니고,CoCreateInstance 와 IDirectSound::Initialize 의 각 메소드를 사용해 DirectSound 오브젝트를 생성 한다.
    LPDIRECTSOUND lpds;
dsrval = CoCreateInstance(&CLSID_DirectSound,
                          NULL,
                          CLSCTX_INPROC_SERVER,
                          &IID_IDirectSound,
                          &lpds);
if SUCCEEDED(dsrval)
    dsrval = IDirectSound_Initialize(lpds, NULL);

CLSID_DirectSound 는, DirectSound 의 드라이버 오브젝트 클래스의 클래스 식별자이며,IID_IDirectSound 는 필수의 DirectSound 인터페이스이다. lpds 파라미터는,CoCreateInstance 가 돌려주는, 초기화되어 있지 않은 오브젝트이다.

CoCreateInstance 함수를 사용해 생성 한 DirectSound 를 사용하기 전에,IDirectSound::Initialize 메소드를 호출하지 않으면 안 된다. 이 메소드는,DirectSoundCreate 가 사용하는 드라이버의 GUID 파라미터 (이 경우는 NULL)를 취한다. DirectSound 오브젝트를 초기화한 후,DirectSoundCreate 함수를 사용해 생성 했을 경우와 같이, 이 오브젝트의 사용과 릴리즈를 실시할 수 있다.

어플리케이션을 닫기 전에, 다음과 같이 CoUninitialize 함수를 호출해 COM 라이브러리를 닫는다.

CoUninitialize();
[Visual Basic]

DirectX7.DirectSoundCreate 메소드를 사용해 DirectSound 오브젝트를 생성 한다. 단일의 파라미터로, 이 오브젝트에 관련짓는 디바이스의 GUID 를 지정한다. 이 GUID 는, 「사운드 디바이스의 열거」로 취득할 수 있다. 그 밖에, 디폴트의 디바이스에 대응하는 오브젝트를 생성 하려면 , 다음과 같이 하늘의 캐릭터 라인을 건네주면 좋다.

Dim m_dx As New DirectX7
Dim m_ds As DirectSound
Set m_ds = m_dx.DirectSoundCreate("")

사운드 디바이스가 존재하지 않는 경우나, 표준적인 웨이브 폼 오디오 함수 (DirectSound 는 아니다)를 이용하는 어플리케이션이 사운드 디바이스를 제어하고 있는 경우는, 이 메소드는 에러가 된다. 어플리케이션은 이 호출이 실패했을 경우에 대비해, 사운드없이 어플리케이션을 속행하는지, 사운드 디바이스를 사용하고 있는 어플리케이션을 닫도록(듯이) 유저에게 prompt를 표시하는지, 어느 쪽인가의 준비를 할 필요가 있다.


협조 레벨

Windows 는 멀티태스킹 환경이므로, 복수의 어플리케이션이 임의의 시점에서 같은 디바이스 드라이버를 사용해 동작하는 일이 있다. DirectX 는 협조 레벨을 사용해, 각 어플리케이션이 부적절한 방법 또는 부적절한 타이밍에 디바이스에 액세스 하지 않는 것을 보증한다. DirectSound 의 각 어플리케이션은, 디바이스에 대해서 인정되는 액세스 범위를 결정하는 1 개의 협조 레벨을 가진다.

[C++]

DirectSound 오브젝트를 생성 한 다음에, 사운드를 재생하기 전에 IDirectSound::SetCooperativeLevel 메소드를 사용해 디바이스의 협조 레벨을 설정해야 한다.

[Visual Basic]

DirectSound 오브젝트를 생성 한 다음에, 사운드를 재생하기 전에 DirectSound.SetCooperativeLevel 메소드를 사용해 디바이스의 협조 레벨을 설정해야 한다.

DirectSound 는, 표준, 우선, 배타, 쓰기 우선의 4 개의 협조 레벨을 정의하고 있다. 이것들은, DSSCL_NORMAL, DSSCL_PRIORITY, DSSCL_EXCLUSIVE, DSSCL_WRITEPRIMARY 의 값으로 나타내진다.

게임 어플리케이션은, 거의 모든 환경에서 DSSCL_PRIORITY 를 사용한다. 이 레벨은, 샘플링 레이트와 비트 깊이에 대한 어플리케이션 제어를 가능하게 하면서, 가장 강력하게 동작한다. 또, 우선 협조 레벨에서는, 다른 어플리케이션 (IP 테레포니등)으로부터의 오디오를 게임으로부터의 오디오와 함께 (들)물을 수도 있다. 우선 레벨과 배타 레벨은 같은 성능을 제공하므로, DSSCL_EXCLUSIVE 는 다른 모든 어플리케이션을 무음으로 하도록(듯이) 요구하는 어플리케이션 에 대해서만 사용해야 하는 것이다. 예를 들어, 뮤직 오쏘링 어플리케이션에서는, 재생중에 다른 오디오가 들리지 않는 것이 중요하다.

[C++]

다음의 C 의 예는 「DirectSound 오브젝트의 생성」으로 초기화한 DirectSound 디바이스의 협조 레벨을 설정한다. hwnd 파라미터는, 어플리케이션 윈도우에의 핸들이다.

HRESULT hr = lpDirectSound->lpVtbl->SetCooperativeLevel(
        lpDirectSound, hwnd, DSSCL_PRIORITY);
[Visual Basic]

다음의 코드예는 「DirectSound 오브젝트의 생성」으로 초기화한 DirectSound 디바이스의 협조 레벨을 설정한다. hwnd 인수는, 어플리케이션 윈도우에의 핸들이다.

m_ds.SetCooperativeLevel Me.hWnd, DSSCL_PRIORITY

표준 협조 레벨

표준 협조 레벨에서는, 어플리케이션은, 프라이머리 사운드 버퍼의 포맷의 설정, 프라이머리 버퍼에의 쓰기, 디바이스의 온보드 메모리의 압축을 실시할 수 없다. 이 협조 레벨을 사용하는 모든 어플리케이션은, 22 kHz, 스테레오 사운드, 8 비트 샘플링의 프라이머리 버퍼 포맷을 사용하므로, 디바이스는 어플리케이션간에 가장 원활히 교체된다.

우선 협조 레벨

우선 협조 레벨로 DirectSound 디바이스를 사용하면(자), 어플리케이션은 하드웨어 믹싱등의 하드웨어 리소스에 대해서 최고의 권한을 확보해, 프라이머리 사운드 버퍼의 포맷의 설정, 디바이스의 온보드 메모리의 압축을 실시할 수 있다.

배타 협조 레벨

배타 협조 레벨에서는, 어플리케이션은 우선 레벨의 모든 특권을 가지는 것 외에 그 어플리케이션이 foreground로 실행되고 있는 경우는, 그 프라이머리 사운드 버퍼의 소리만이 들린다.

쓰기 우선 협조 레벨

최상정도의 협조 레벨은 쓰기 우선이다. 이 협조 레벨로 DirectSound 디바이스를 사용하면(자), 어플리케이션은 프라이머리 사운드 버퍼에 직접 액세스 할 수 있다. 이 모드에서는, 어플리케이션은 프라이머리 버퍼에 직접 쓰기를 실시하지 않으면 안 된다. 이 쓰기중은, 세컨드리 버퍼를 재생할 수 없다.

[C++]

프라이머리 버퍼내의 오디오 샘플에 직접 쓰기의 액세스를 하려면 , 어플리케이션을 쓰기 우선 레벨로 설정해야 한다. 어플리케이션을 이 레벨로 설정해 두지 않으면 프라이머리 버퍼에 대한 C++ 의 IDirectSoundBuffer::Lock 메소드, 또는 Visual Basic 의 DirectSoundBuffer.ReadBuffer 와 DirectSoundBuffer.WriteBuffer 의 모든 호출은 실패한다.

쓰기 우선 협조 레벨로 설정된 어플리케이션이 foreground가 되면(자), 다른 어플리케이션의 모든 세컨드리 버퍼는 정지되어 「없어졌다」라고 마크 된다. 최초의 어플리케이션이 백그라운드로 옮겨지면(자), 그 프라이머리 버퍼는 「없어졌다」라고 마크 되어 어플리케이션이 재차 foreground로 옮길 때는 이 버퍼를 복원하지 않으면 안 된다. 상세한 것에 대하여는, 「버퍼 관리」를 참조할것.

DirectSound 드라이버가 유저의 시스템에 존재하고 있지 않는 경우는, 쓰기 우선 레벨의 설정은 할 수 없다. 이 상황에 해당할지 어떨지를 확인하려면 , C++ 의 IDirectSound::GetCaps 메소드나 Visual Basic 의 DirectSound.GetCaps 메소드를 호출해,DSCAPS 구조체의 DSCAPS_EMULDRIVER 플래그를 체크한다.

상세한 것에 대하여는, 「프라이머리 버퍼에의 액세스」를 참조할것.

[Visual Basic]

Visual Basic 어플리케이션에서는, DSSCL_WRITEPRIMARY 협조 레벨을 사용해서는 안된다.


디바이스의 능력

DirectSound 를 사용하면(자), 어플리케이션은 사운드 디바이스의 하드웨어 능력을 취득할 수 있다. DirectSound 는 이용 가능한 하드웨어 가속화를 자동적으로 이용하므로, 어플리케이션에서는, 보통 이 취득을 실시할 필요는 없다. 그러나 고성능의 어플리케이션은 이 정보를 이용해, 이용 가능한 하드웨어에 대해서 사운드의 요구 사항을 평가할 수 있다. 예를 들어, 하드웨어 믹싱이 이용 가능한 경우는, 이용 불가능한 경우에 비해, 어플리케이션이 보다 많은 사운드를 재생할 수 있을 것이다.

[C++]

DirectSoundCreate 함수를 호출해 DirectSound 오브젝트를 생성 한 후는,IDirectSound::GetCaps 메소드를 사용해 사운드 디바이스의 능력을 취득할 수 있다.

다음의 예는, 「DirectSound 오브젝트의 생성」으로 초기화한 디바이스의 능력을 취득한다.

DSCAPS dscaps;

dscaps.dwSize = sizeof(DSCAPS);
HRESULT hr = lpDirectSound->lpVtbl->GetCaps(lpDirectSound,
    &dscaps);

DSCAPS 구조체는, 사운드 디바이스의 능력과 리소스에 관한 정보를 받지만, 이 안에는 타입마다의 최대의 리소스와 현재 이용 가능한 리소스가 포함된다. 이 메소드를 호출하기 전에, 이 구조체의 dwSize 멤버를 초기화해야 하는 점에 주의 해야 한다.

어플리케이션이 하드웨어 능력을 평가하는 경우는, 버퍼 할당을 실시할 때마다 IDirectSound::GetCaps 메소드를 호출해, 다음의 버퍼를 생성 하는데 충분한 리소스가 있을지 어떨지를 확인해야 한다.

[Visual Basic]

DirectX7.DirectSoundCreate 메소드를 호출해 DirectSound 오브젝트를 생성 한 후는,DirectSound.GetCaps 메소드를 사용해 사운드 디바이스의 능력을 취득할 수 있다.

다음의 예는, 「DirectSound 오브젝트의 생성」으로 초기화한 디바이스의 능력을 취득한다.

Dim DSCAPS As DSCAPS

m_ds.GetCaps DSCAPS

DSCAPS 형은, 사운드 디바이스의 능력과 리소스에 관한 정보를 받지만, 이 안에는 타입마다의 최대의 리소스와 현재 이용 가능한 리소스가 포함된다.

어플리케이션이 하드웨어 능력을 평가하는 경우는, 버퍼 할당을 실시할 때마다 DirectSound.GetCaps 메소드를 호출해, 다음의 버퍼를 생성 하는데 충분한 리소스가 있을지 어떨지를 확인해야 한다.


스피커의 구성

DirectSound 는, 스피커가 청취자에 대한 상대적인 위치를 잡는 스피커 구성을 사용해, 유저의 사운드 시스템에 맞추어 3D 이펙트를 최적화한다.

[C++]

Windows 98 으로 Windows 2000 에서는, 유저는 컨트롤 패널을 사용해 스피커 구성을 설정할 수 있다. 어플리케이션은 IDirectSound::GetSpeakerConfig 를 사용해 이 값을 꺼내,IDirectSound::SetSpeakerConfig 를 호출해 그 값을 변경할 수 있다.

[Visual Basic]

Windows 98 으로 Windows 2000 에서는, 유저는 컨트롤 패널을 사용해 스피커 구성을 설정할 수 있다. 어플리케이션은 DirectSound.GetSpeakerConfig 를 사용해 이 값을 꺼내,DirectSound.SetSpeakerConfig 를 호출해 그 값을 변경할 수 있다.

Windows 95 에서는,GetSpeakerConfig 는 단순하게, 디폴트의 값 또는 SetSpeakerConfig 로 설정한 직전의 값을 돌려준다.


하드웨어 메모리의 압축

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

어플리케이션은 최소한의 협조 레벨을 갖추고 있는 것을 전제로서IDirectSound::Compact 메소드를 사용해, 임의의 온보드 사운드 메모리를 이동해 연속 블록을 형성해, 프리 메모리의 최대 부분을 사용 가능하게 할 수 있다.


DirectSound 버퍼

여기에서는, 사운드를 재생하기 위한 기본적인 기구인 DirectSoundBuffer 오브젝트의 생성과 관리에 대해 취급한다. 다음의 토픽을 다룬다.

  • 버퍼의 기본
  • 세컨드리 버퍼의 생성
  • 다이나믹 음성 관리
  • 버퍼 컨트롤 옵션
  • 프라이머리 버퍼에의 액세스
  • 스태틱 버퍼의 쓰기와 재생
  • 스트림 버퍼의 사용법
  • 재생의 컨트롤
  • 현재 플레이 포지션과 현재 라이트 포지션
  • 재생 버퍼의 통지
  • 사운드의 믹싱
  • 커스텀 믹서
  • 버퍼 관리
  • 압축 웨이브 포맷


버퍼의 기본

어플리케이션이 DirectSound 를 초기화 하면, DirectSound 는 사운드의 믹싱과 출력 디바이스에의 송신을 하기 위해서, 프라이머리 사운드 버퍼의 생성과 관리를 자동적으로 실시한다.

어플리케이션은, 각각의 사운드의 보존과 재생을 하기 위해서, 적어도 1 개의 세컨드리 사운드 버퍼를 생성 해야 한다. 이 방법의 상세한 것에 대하여는, 「세컨드리 버퍼의 생성」을 참조할것.

세컨드리 버퍼는, 어플리케이션이 동작하고 있는 동안 항상 지속하는 일도, 불필요하게 되었을 때에 삭제할 수도 있다. 세컨드리 버퍼에는, 게임중의 효과음등 반복해 재생되는 1 개의 사운드를 저장 하거나 적당 새로운 데이터를 기록할 수도 있다. 어플리케이션은, 세컨드리 버퍼에 기억되고 있는 사운드를 1 개의 이벤트, 또는 연속 재생되는 루프 사운드로서 재생할 수 있다. 사운드 파일의 데이터가 매우 크고, 메모리에 기억해 두는 것이 실용적이지 않는 경우, 데이터를 스트림 하기 위해서 세컨드리 버퍼를 이용할 수 있다.

[C++]

IDirectSound::DuplicateSoundBuffer 메소드를 사용해, 복수의 세컨드리 버퍼를 같은 물리 메모리내에 생성 할 수 있다. 프라이머리 사운드 버퍼는 복제할 수 없다. 원의 버퍼가 하드웨어 메모리에 놓여져 있어, 중복 버퍼용의 하드웨어 리소스가 이용 불가능한 경우는, 이 호출은 실패한다. 같이 비록 호출이 성공했다고 해도, 실제로 중복 버퍼가 원의 버퍼와 메모리를 공유 하면은 한정되지 않기 때문에, 이러한 변경이 모든 중복 버퍼에 반영될 것이다라고 하는 예측의 아래에서 버퍼를 변경해서는 안된다.

[Visual Basic]

DirectSound.DuplicateSoundBuffer 메소드를 사용해, 복수의 세컨드리 버퍼를 같은 물리 메모리내에 생성 할 수 있다. 프라이머리 사운드 버퍼는 복제할 수 없다. 원의 버퍼가 하드웨어 메모리에 놓여져 있어, 중복 버퍼용의 하드웨어 리소스가 이용 불가능한 경우는, 이 호출은 실패한다.

다른 세컨드리 버퍼의 사운드는, 이것들을 동시에 재생하는 것만으로 믹싱 할 수 있다. 처리 능력의 한계내이면, 임의의 수의 세컨드리 버퍼를 동시에 재생할 수 있다.

DirectSound 믹서의 지연 시간은 20 밀리 세컨드의 짧음이므로, 재생 시작까지의 지연은 감지할 수 없다. 이 상태에서는, 어플리케이션이 버퍼를 재생해, 즉석에서 화면에서 애니메이션을 시작 하면, 오디오와 비디오는 동시에 스타트 하는 것처럼 보인다. 다만, DirectSound 가 하드웨어 기능을 소프트웨어로 에뮬레이트 해야 하는 경우는, 믹서는 짧은 지연 시간을 달성하지 못하고, 사운드가 재생 될 때까지 약간 긴 (표준에서는 100~150 밀리 세컨드) 의 지연이 생긴다.

[C++]

보통, 개발자는 프라이머리 버퍼를 의식할 필요는 전혀 없다. DirectSound 가 내부에서 관리를 실시한다. 그러나, 어플리케이션이 고유의 믹싱을 실시하는 경우는, 개발자가 프라이머리 버퍼에 직접 쓰기를 실시할 필요가 있다. 이것을 실시하면, 세컨드리 버퍼를 동시에는 이용할 수 없다. 상세한 것에 대하여는, 「프라이머리 버퍼에의 액세스」를 참조할것.


세컨드리 버퍼의 생성

[C++]

사운드 버퍼를 생성 하려면 , 어플리케이션이 DSBUFFERDESC 구조체에의 쓰기를 실시해, 그 주소를 IDirectSound::CreateSoundBuffer 메소드에 건네준다. 이 메소드는 DirectSoundBuffer 오브젝트를 생성 해,IDirectSoundBuffer 인터페이스에의 포인터를 돌려준다. 어플리케이션은 이 인터페이스를 버퍼의 조작과 재생에 사용한다.

다음의 예는, 기본적인 세컨드리 사운드 버퍼를 생성 하는 방법을 나타낸다.

BOOL AppCreateBasicBuffer(
        LPDIRECTSOUND 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;

    // 3 초의 버퍼.
    dsbdesc.dwBufferBytes = 3 * pcmwf.wf.nAvgBytesPerSec;
    dsbdesc.lpwfxFormat = (LPWAVEFORMATEX) &pcmwf;
    // 버퍼를 생성 한다.
    hr = lpDirectSound->lpVtbl->CreateSoundBuffer(lpDirectSound,
        &dsbdesc, lplpDsb, NULL);
    if SUCCEEDED(hr)
    {
        // 유효한 인터페이스는 *lplpDsb 내에 있다.
        return TRUE;
    }
    else
    {
        // 실패.
        *lplpDsb = NULL;
        return FALSE;
    }
}

어플리케이션은, 가장 중요한 사운드의 버퍼를 최초로 생성 해야 한다. DirectSound 는 하드웨어 리소스를 최초의 버퍼에 할당해 그 이점을 살린다. 하드웨어 버퍼는 사운드 카드 프로세서로 믹싱 되므로, 어플리케이션 성능에 거의 영향을 미치지 않는다.

버퍼의 위치를 DirectSound 로 결정하게 한 하지않고서 스스로 지정하고 싶은 경우는,DSBUFFERDESC 구조체에 DSBCAPS_LOCHARDWARE 또는 DSBCAPS_LOCSOFTWARE 의 어느 쪽인가의 플래그를 설정한다. DSBCAPS_LOCHARDWARE 플래그를 설정해, 하드웨어 리소스가 부족한 경우, 버퍼의 생성 요구는 실패한다.

DirectSound 의 음성 관리 기능을 이용하고 싶은 경우는, 버퍼의 생성시에 DSBCAPS_LOCDEFER 플래그를 지정한다. 이 플래그는, 버퍼에 대한 리소스의 할당을, 버퍼가 재생될 때까지 지연 한다.

기존의 버퍼의 위치를 확인하려면 ,IDirectSoundBuffer::GetCaps 메소드를 사용해,DSBCAPS 구조체의 dwFlags 멤버를 체크해, DSBCAPS_LOCHARDWARE 과 DSBCAPS_LOCSOFTWARE 의 어느 쪽의 플래그가 되어 있을까를 조사한다. 어느 쪽인지가 반드시 지정되고 있다.

DSBCAPS_STATIC 플래그를 설정 하면, 가능한 경우는 버퍼를 온보드의 하드웨어 메모리에 생성 해야 한다라고 하는 것이 DirectSound 에 통지된다. 하드웨어 버퍼를 이용할 수 없는 경우에서도,IDirectSound::CreateSoundBuffer 메소드는 실패하지 않는다. 이 플래그는, 버퍼용으로 시스템 메모리를 사용하는 최근의 사운드 카드가 많게는 영향을 주지 않는다. 하드웨어 스태틱 버퍼는, 반복 재생되는 짧은 사운드에 대해서만 사용해야 하는 것이다.

DirectSoundBuffer 오브젝트는, 이것을 생성 한 DirectSound 오브젝트가 소유한다. DirectSound 오브젝트가 릴리즈 되면(자), 이 오브젝트가 생성 한 모든 버퍼도 릴리즈 되어 참조할 수 없게 된다.

[Visual Basic]

사운드 버퍼를 생성 하려면 ,DirectSound.CreateSoundBuffer ,DirectSound.CreateSoundBufferFromFile , 또는 DirectSound.CreateSoundBufferFromResource 메소드를 호출한다. 이 메소드는, 버퍼의 조작과 재생에 사용되는 DirectSoundBuffer 오브젝트를 생성 해 돌려준다.

DirectSound.CreateSoundBufferFromFile 와 DirectSound.CreateSoundBufferFromResource 는, 사운드가 그만큼 길지 않은 경우에 사용하는데 적합한 메소드이다. DirectSound 는, 사운드 전체를 보관 유지하는데 충분한 버퍼를 생성 해, 파일이나 리소스로부터의 데이터를 그 버퍼에 기입한다. DirectSound.CreateSoundBuffer 는 스트림 버퍼에 적절하고 있지만, 개발자가 웨이브 파일이나 리소스를 해석해, 버퍼에 대한 데이터의 스트리밍 처리를 실시하지 않으면 안 된다.

CreateSoundBuffer 는,DirectSound3Dlistener 오브젝트를 취득할 수 있는 프라이머리 버퍼의 생성에도 사용된다. 상세한 것에 대하여는, 「DirectSound3DListener 오브젝트의 취득」을 참조할것.

다음의 예는, 기본적인 세컨드리 사운드 버퍼를 생성 하는 방법을 나타낸다.

Dim m_dx As New DirectX7
Dim m_ds As DirectSound

Private Sub Form_Load()
  Set m_ds = m_dx.DirectSoundCreate("")
  CreateSoundBuffer
End Sub

Public Sub CreateSoundBuffer()
  Dim m_dsb As DirectSoundBuffer
  Dim buffdesc As DSBUFFERDESC
  Dim format As WAVEFORMATEX

  '웨이브 포맷을 지정한다.

  format.nFormatTag = WAVE_FORMAT_PCM
  format.nChannels = 2
  format.lSamplesPerSec = 22050
  format.nBitsPerSample = 16
  format.nBlockAlign = (format.nChannels * format.nBitsPerSample) / 8
  format.lAvgBytesPerSec = format.lSamplesPerSec * format.nBlockAlign
  format.nSize = 0

  '생성 하는 사운드 버퍼를 기술한다.

  buffdesc.lBufferBytes = format.lAvgBytesPerSec
  buffdesc.lFlags = DSBCAPS_CTRLPAN Or DSBCAPS_CTRLVOLUME _
          Or DSBCAPS_CTRLFREQUENCY

  '버퍼를 생성 한다.

  Set m_dsb = m_ds.CreateSoundBuffer(buffdesc, format)
End Sub

DSBUFFERDESC 형은, 포맷, 사이즈, 능력 등, 희망의 버퍼의 특성을 기술한다. 어플리케이션은 필요한 능력을 지정해야 한다. 그렇지 않으면, 그러한 능력은 이용할 수 없다. 예를 들어, 어플리케이션이 DSBCAPS_CTRLFREQUENCY 플래그를 지정하지 않고 버퍼를 생성 하면,DirectSoundBuffer.SetFrequency 에 대한 모든 호출은 실패한다.

어플리케이션은, 가장 중요한 사운드의 버퍼를 최초로 생성 해야 한다. DirectSound 는 하드웨어 리소스를 최초의 버퍼에 할당해 그 이점을 살린다. 하드웨어 버퍼는 사운드 카드 프로세서로 믹싱 되므로, 어플리케이션 성능에 거의 영향을 미치지 않는다.

버퍼의 위치를 DirectSound 로 결정하게 한 하지않고서 스스로 지정하고 싶은 경우는,DSBUFFERDESC 형에 DSBCAPS_LOCHARDWARE 또는 DSBCAPS_LOCSOFTWARE 의 어느 쪽인가의 플래그를 설정한다. DSBCAPS_LOCHARDWARE 플래그를 설정해, 하드웨어 리소스가 부족한 경우, 버퍼의 생성 요구는 실패한다.

기존의 버퍼의 위치를 확인하려면 ,DirectSoundBuffer.GetCaps 메소드를 사용해,DSBCAPS 형의 lFlags 멤버를 체크해, DSBCAPS_LOCHARDWARE 과 DSBCAPS_LOCSOFTWARE 의 어느 쪽의 플래그가 되어 있을까를 조사한다. 어느 쪽인지가 반드시 지정되고 있다.

DSBCAPS_STATIC 플래그를 설정 하면, 가능한 경우는 버퍼를 온보드의 하드웨어 메모리에 생성 해야 한다라고 하는 것이 DirectSound 에 통지된다. 하드웨어 버퍼를 이용할 수 없는 경우에서도,IDirectSound::CreateSoundBuffer 메소드는 실패하지 않는다. 이 플래그는, 버퍼용으로 시스템 메모리를 사용하는 최근의 사운드 카드가 많게는 영향을 주지 않는다. 하드웨어 스태틱 버퍼는, 반복 재생되는 짧은 사운드에 대해서만 사용해야 하는 것이다.


다이나믹 음성 관리

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

많은 사운드 카드는 고유의 세컨드리 버퍼를 유지해, 3D 이펙트와 그 믹싱을 처리한다. 이러한 하드웨어 버퍼는, 호출때, 보통은 카드 자체는 아니고 시스템 메모리에 배치된다. 그러나, 이것들은 디바이스가 관리하므로, 시스템 프로세서상에서는 소프트웨어 버퍼보다 요구는 훨씬 적게 된다. 따라서, 하드웨어로 할 수 있는 한 많은 버퍼, 특히 3D 버퍼를 가지는 것이 가장 효율적이다.

디폴트에서는, DirectSound 는 가능하면 항상 버퍼를 하드웨어에 둔다. 그러나, DirectSound 는 디바이스가 한 번에 재생 가능한 한의 하드웨어 버퍼 밖에 생성 할 수 없다. 즉, 하드웨어 버퍼수는, 이용 가능한 하드웨어 음성으로 제한된다. DirectSound 는, 버퍼가 생성 될 때 하드웨어 음성을 할당해 버퍼가 불필요하게 되었을 때 만 릴리즈 한다. 음성은, 버퍼가 재생중이 아닐 때도 프리는 아니다. 어플리케이션이 많은 버퍼를 생성 하는 경우, 몇개의 버퍼가 소프트웨어에 존재할 가능성이 있다. 즉, 사운드 카드는 아니고 CPU 로 버퍼의 관리와 믹싱을 한다.

다이나믹 음성 관리를 사용하면(자), 버퍼가 재생될 때까지 음성 할당을 지연 하거나 DirectSound 가 우선 순위의 낮은 사운드를 빨리 정지해 리소스를 새로운 사운드에 할당하는 것으로, 하드웨어 리소스의 이용 제한을 극복할 수 있다.

하드웨어 믹싱과 3D 이펙트에 대한 리소스의 할당을 버퍼가 재생될 때까지 지연 하려면 ,IDirectSound::CreateSoundBuffer 에게 건네지는 DSBUFFERDESC 구조체에 DSBCAPS_LOCDEFER 플래그를 지정한다. DSBCAPS_LOCDEFER 플래그에 의해 생성 된 버퍼 위에의 IDirectSoundBuffer::Play 를 호출하는 경우, DirectSound 는 가능하면 하드웨어에 버퍼를 배치해, 그 이외의 경우는 소프트웨어에 배치한다.

Play 를 호출하는 경우는, 아래 표에 나타내는 플래그의 1 개, 혹은 최초의 2 개의 플래그의 어느 쪽인지를 3 번째의 플래그와 조합해 건네주는 것으로, 버퍼에 대한 하드웨어 음성의 릴리즈를 시도할 수가 있다. 그 후, DirectSound 는 플래그의 지정하는 종료 기준에 적절한 재생 버퍼를 검색한다.

플래그 | 기준
DSBPLAY_TERMINATEBY_TIME | 어느 후보 버퍼보다 길게 재생되고 있는 버퍼를 선택한다.
DSBPLAY_TERMINATEBY_DISTANCE | 청취자로부터 가장 먼 3D 의 후보 버퍼를 선택한다.
DSBPLAY_TERMINATEBY_PRIORITY | IDirectSoundBuffer::Play 의 dwPriority 파라미터의 설정에 근거해, 후보 버퍼의 쳐 가장 우선도의 낮은 버퍼를 선택한다. 이 플래그를 다른 2 개의 플래그의 어느 쪽일까하고 조합하면(자), 그 플래그는 우선도가 동일한 경우인 만큼 사용된다.

적절한 버퍼가 발견되면(자), DirectSound 는 그 버퍼를 정지해, 사용하고 있던 음성을 새롭게 재생되는 버퍼에 할당한다. 어느 버퍼도 종료 기준에 적절하지 않은 경우는, DSBPLAY_LOCHARDWARE 플래그가 지정되어 있지 않으면, 새롭게 재생되는 버퍼는 소프트웨어로 재생된다. 이 플래그가 지정되고 있는 경우,Play 에 대한 호출은 실패한다.

지연 버퍼의 재생시의 처리에 대한 자세한 것은,IDirectSoundBuffer::Play 를 참조할것.

주 : 버퍼의 생성시는, DSBCAPS_LOCDEFER 플래그를 DSBCAPS_STATIC 플래그와 조합해 사용하지 않는 것. PCI 카드가 있는 것의 경우와 같이, 온 카드 메모리가 이용 가능한 때에는, DSBCAPS_STATIC 버퍼는 이 메모리에 놓여진다. DSBCAPS_LOCDEFER 플래그로 이러한 버퍼를 생성 하는 경우, 버퍼 메모리는 IDirectSoundBuffer::Play 에 대한 최초의 호출까지 사운드 카드로 카피되지 않고, 부적절한 지연이 생긴다.


버퍼 컨트롤 옵션

[C++]

사운드 버퍼를 생성 할 경우에, 버퍼가 필요로 하는 컨트롤 옵션을 지정해야 한다. 이것에는 DSBUFFERDESC 구조체의 dwFlags 멤버를 사용한다. 이 구조체는, 1 개(살) 또는 복수의 DSBCAPS_CTRL* 플래그를 보관 유지할 수 있다. 다음의 컨트롤을 이용할 수 있다.

  • 3D 프로퍼티
  • 주파수
  • 팬
  • 볼륨
  • 위치의 통지

모든 사운드 카드로부터 최고의 성능을 얻으려면 , 어플리케이션이 사용하는 옵션만을 지정해야 한다.

DirectSound 는 컨트롤 옵션을 사용해, 사운드 버퍼에 하드웨어 리소스를 할당할 수 있을지 어떨지를 결정한다. 예를 들어, 어느 디바이스가 하드웨어 버퍼를 지원 하고 있어, 그러한 버퍼에 팬 컨트롤을 제공하고 있지 않다고 한다. 이 경우, DirectSound 는 DSBCAPS_CTRLPAN 플래그가 지정되어 있지 않은 경우에 한해서, 하드웨어 가속화를 사용한다.

버퍼가 갖추지 않은 컨트롤을 사용하려고 하면, 메소드는 실패한다. 예를 들어,IDirectSoundBuffer::SetVolume 메소드를 사용해 볼륨을 변경하려고 할 때, 그 버퍼의 생성시에 DSBCAPS_CTRLVOLUME 플래그가 지정되고 있었을 경우에 한해서 메소드는 성공한다. 이 플래그가 지정되어 있지 않았던 경우는 메소드는 실패에 끝나,DSERR_CONTROLUNAVAIL 에러 코드가 돌려주어진다.

[Visual Basic]

사운드 버퍼를 생성 할 경우에, 버퍼가 필요로 하는 컨트롤 옵션을 지정해야 한다. 이것에는 DSBUFFERDESC 형의 lFlags 멤버를 사용한다. 이 구조체는, 1 개(살) 또는 복수의 DSBCAPS_CTRL* 플래그를 보관 유지할 수 있다. 다음의 컨트롤을 이용할 수 있다.

  • 3D 프로퍼티
  • 주파수
  • 팬
  • 볼륨
  • 위치의 통지

모든 사운드 카드로부터 최고의 성능을 얻으려면 , 어플리케이션이 사용하는 옵션만을 지정해야 한다.

DirectSound 는 컨트롤 옵션을 사용해, 사운드 버퍼에 하드웨어 리소스를 할당할 수 있을지 어떨지를 결정한다. 예를 들어, 어느 디바이스가 하드웨어 버퍼를 지원 하고 있어, 그러한 버퍼에 팬 컨트롤을 제공하고 있지 않다고 한다. 이 경우, DirectSound 는 DSBCAPS_CTRLPAN 플래그가 지정되어 있지 않은 경우에 한해서, 하드웨어 가속화를 사용한다.

버퍼가 갖추지 않은 컨트롤을 사용하려고 하면, 메소드는 실패한다. 예를 들어,DirectSoundBuffer.SetVolume 메소드를 사용해 볼륨을 변경하려고 할 때, 그 버퍼의 생성시에 DSBCAPS_CTRLVOLUME 플래그가 지정되고 있었을 경우에 한해서 메소드는 성공한다. 이 플래그가 지정되어 있지 않았던 경우는 메소드는 실패에 끝나,DSERR_CONTROLUNAVAIL 에러값이 돌려주어진다.

팬 컨트롤과 3D 처리는, 서로 배타적이다. 버퍼의 생성시에 DSBCAPS_CTRL3D 와 DSBCAPS_CTRLPAN 를 함께 지정 하면, 에러가 된다.


프라이머리 버퍼에의 액세스

[Visual Basic]

버퍼 기술로 DSBCAPS_PRIMARYBUFFER 플래그를 지정해, 이 기술을 DirectSound.CreateSoundBuffer 에 건네주는 것으로, 프라이머리 버퍼 오브젝트를 생성 할 수 있다. 이러한 처리를 실시하는 가장 일반적인 상황으로서 프라이머리 버퍼의 DirectSoundBuffer.Play 메소드를 호출해, 단시간의 사운드 중단의 빈발을 방지하는 것이 들고 있다. 상세한 것에 대하여는, 「프라이머리 버퍼의 연속 재생」을 참조할것.

DirectX for Visual Basic 어플리케이션에서는, 프라이머리 버퍼에의 쓰기 액세스의 취득을 시도하지 않는 것.

[C++]

세컨드리 버퍼가 지원 하고 있지 않는 특별한 믹싱이나 다른 이펙트를 필요로 하는 어플리케이션에 대해서, DirectSound 는 프라이머리 버퍼에의 직접 액세스를 허가한다.

프라이머리 사운드 버퍼에의 쓰기 액세스를 취득 하면, DirectSound 외 기능은 이용할 수 없게 된다. 세컨드리 버퍼의 믹싱도 행해지지 않기 때문에, 하드웨어 가속화 믹싱도 이용할 수 없게 된다.

대부분의 어플리케이션은, 프라이머리 버퍼에 직접 액세스 하지 않고 세컨드리 버퍼를 사용한다. 세컨드리 버퍼에의 쓰기는 간단하게 실시할 수 있다. 보다 큰 버퍼에 의해, 다음의 데이터 블록의 쓰기까지의 시간이 길어져, 오디오의 소리가 중단되는 위험이 최소한으로 억제 당한다. 어플리케이션이 필요로 하는 오디오가, 믹싱을 필요로 하지 않는 1 개의 오디오 스트림과 같이 단순한 것이어도, 세컨드리 버퍼를 사용해 오디오 데이터를 재생하는 것으로써, 보다 높은 성능을 실현될 수 있다.

프라이머리 버퍼의 사이즈는 지정하지 못하고, 버퍼를 생성 한 후에 돌려주어지는 사이즈를 받아들이지 않으면 안 된다. 보통, 프라이머리 버퍼는 지극히 작고, 만약 어플리케이션이 이러한 버퍼에 직접 기입하는 경우는 짧은 간격으로 데이터 블록을 쓰기, 이전의 데이터가 한번 더 재생되는 것을 막지 않으면 안 된다.

DSBUFFERDESC 구조체에 DSBCAPS_PRIMARYBUFFER 플래그를 지정해, 이 구조체를 IDirectSound::CreateSoundBuffer 메소드에 건네주어, 액세스 가능한 프라이머리 버퍼를 생성 한다. 버퍼에 쓰기를 하고 싶은 경우는, 협조 레벨은 DSSCL_WRITEPRIMARY 가 아니면 안된다.

프라이머리 버퍼가 하드웨어상에 존재하고 있지 않는 한, 그 버퍼의 쓰기 액세스는 취득할 수 없다. 이것에 해당할지 어떨지를 확인하려면 ,IDirectSoundBuffer::GetCaps 메소드를 호출해 DSBCAPS 구조체의 dwFlags 멤버내의 SBCAPS_LOCHARDWARE 플래그의 유무를 체크한다. 소프트웨어로 에뮬레이트 한 프라이머리 버퍼를 잠그려고 하면, 호출은 실패한다.

프라이머리 사운드 버퍼는, 루프 해 재생해야 한다. 그 목적으로, DSBPLAY_LOOPING 플래그가 설정되어 있는 것을 확인한다.

다음의 예는, 프라이머리 버퍼에의 쓰기 액세스를 취득하는 방법을 나타낸다.

BOOL AppCreateWritePrimaryBuffer(
    LPDIRECTSOUND 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->lpVtbl->SetCooperativeLevel(lpDirectSound,
        hwnd, DSSCL_WRITEPRIMARY);
    if SUCCEEDED(hr)
    {
        // 버퍼의 생성을 시도한다.
        hr = lpDirectSound->lpVtbl->CreateSoundBuffer(lpDirectSound,
            &dsbdesc, lplpDsb, NULL);
        if SUCCEEDED(hr)
        {
            // 프라이머리 버퍼를 희망의 포맷으로 설정한다.
            hr = (*lplpDsb) ->lpVtbl->SetFormat(*lplpDsb, &wf);
            if SUCCEEDED(hr)
            {
                // 버퍼의 사이즈를 알고 싶은 경우는 GetCaps 를 호출한다.
                    dsbcaps.dwSize = sizeof(DSBCAPS);
                (*lplpDsb) ->lpVtbl->GetCaps(*lplpDsb, &dsbcaps);
                *lpdwBufferSize = dsbcaps.dwBufferBytes;
                return TRUE;
            }
        }
    }
    // 실패.
    *lplpDsb = NULL;
    *lpdwBufferSize = 0;
    return FALSE;
}

DSSCL_WRITEPRIMARY 이외의 협조 레벨을 지정 하면, 쓰기 액세스가 없어도 프라이머리 버퍼 오브젝트를 생성 할 수 있다. 이러한 처리를 실시하는 상황의 1 개로서 프라이머리 버퍼에 대해서 IDirectSoundBuffer::Play 메소드를 호출해, 단시간의 사운드 중단의 빈발을 방지하는 것이 들고 있다. 상세한 것에 대하여는, 「프라이머리 버퍼의 연속 재생」 및 「커스텀 믹서」를 참조할것.


스태틱 버퍼의 쓰기와 재생

독립한 사운드 전체를 보관 유지하는 세컨드리 버퍼를, 스태틱 버퍼라고 한다. 같은 버퍼를 다른 사운드로 재이용할 수도 있지만, 보통은 데이터를 한 번만 스태틱 버퍼에 기술한다.

주 : 스태틱 버퍼는 반드시, DSBCAPS_STATIC 플래그를 버퍼 기술로 설정하는 것으로 생성 되는 것은 아니다. 이 플래그는 사운드 카드의 메모리의 할당을 요구하지만, 이 메모리는 이용 불가능하게 되어 있는 것이 많다. 스태틱 버퍼는 시스템 메모리내에 놓여져 DSBCAPS_LOCHARDWARE 또는 DSBCAPS_LOCSOFTWARE 의 어느 쪽인가의 플래그로 생성 된다.

[C++]

스태틱 버퍼에의 데이터의 로드는, 3 개의 스텝에서 행해진다.

  1. IDirectSoundBuffer::Lock 를 사용해 버퍼 전체를 잠근다. 기술을 시작하는 버퍼내의 오프셋(offset)를 지정해 (보통은 0), 그 위치의 메모리 주소를 돌려준다.
  2. 표준의 메모리 카피 루틴을 사용해, 돌려주어진 주소에 오디오 데이터를 기입한다.
  3. IDirectSoundBuffer::Unlock 를 사용해, 버퍼를 언락 한다.

이러한 스텝을 다음의 예로 가리킨다. lpdsbStatic 는 IDirectSoundBuffer 인터페이스 포인터이며,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 사이즈는 없음.
    }

다음의 예는,IDirectSoundBuffer::Play 를 호출해 버퍼를 재생한다.

lpdsbStatic->SetCurrentPosition(0);
HRESULT hr = lpdsbStatic->Play(
        0,    // 미사용.
        0,    // 음성 관리용으로 우선.
        0);   // 플래그.

이 예에서는 DSBPLAY_LOOPING 플래그를 설정하고 있지 않았기 때문에, 버퍼는 마지막에 도달 하면 자동적으로 정지한다. 또,IDirectSoundBuffer::Stop 를 사용하면(자) 버퍼를 빨리 정지할 수 있다. 버퍼를 빨리 정지하는 경우는, 현재의 read 위치가 그 자리소에 머무른다. 따라서, 예의 IDirectSoundBuffer::SetCurrentPosition 에 대한 호출은, 버퍼가 처음부터 시작 하는 것을 보증하는 것이다.

[Visual Basic]

스태틱 버퍼는,DirectSound.CreateSoundBufferFromFile 또는 DirectSound.CreateSoundBufferFromResource 의 어느 쪽인가의 메소드의 호출을 사용해 생성 되어 데이터가 기입해진다.

다음의 샘플 코드는, 리소스 파일로 "bounce" 로서 식별되는 웨이브로부터 스태틱 버퍼를 생성 한다. m_ds 는 DirectSound 오브젝트와 가정한다.

Dim dsbd As DSBUFFERDESC
Dim dsbResource As DirectSoundBuffer
Dim waveFormat As WAVEFORMATEX

dsbd.lFlags = DSBCAPS_CTRLVOLUME
Set dsbResource = m_ds.CreateSoundBufferFromResource( _
        "", "bounce", dsbd, waveFormat)

리소스 파일은 실행 가능 파일에 컴파일 되고 있으므로, 모듈명을 줄 필요는 없다. 같이 메소드가 데이터의 사이즈로부터 버퍼의 사이즈를 결정하므로,DSBUFFERDESC 형의 lBufferBytes 멤버의 값도 설정할 필요는 없다. WAVEFORMATEX 형은, 파일이나 리소스에 저장 된 헤더로부터 웨이브 포맷에 대한 정보를 받는다.

버퍼를 재생하려면 , 다음과 같이 DirectSoundBuffer.Play 를 호출한다.

dsbResource.SetCurrentPosition 0
dsbResource.Play 0

이 예에서는 DSBPLAY_LOOPING 플래그를 설정하고 있지 않았기 때문에, 버퍼는 마지막에 도달 하면 자동적으로 정지한다. 또,DirectSoundBuffer.Stop 를 사용하면(자) 버퍼를 빨리 정지할 수 있다. 버퍼를 빨리 정지하는 경우는, 현재의 read 위치가 그 자리소에 머무른다. 따라서, 예의 DirectSoundBuffer.SetCurrentPosition 에 대한 호출은, 버퍼가 처음부터 시작 하는 것을 보증하는 것이다.

또,DirectSound.CreateSoundBuffer 를 사용해 스태틱 버퍼를 생성 한 후,DirectSoundBuffer.WriteBuffer 메소드를 사용해 메모리의 다른 위치로부터 데이터를 기입할 수도 있다.

세컨드리 버퍼에의 쓰기에 대한 자세한 것은, 「스트림 버퍼의 사용법」을 참조할것.


스트림 버퍼의 사용법

스트림 버퍼는, 한 번에 버퍼에 들어가지 않는 긴 사운드를 재생한다. 버퍼가 재생되는 것에 따라, 낡은 데이터는 정기적으로 새로운 데이터에 옮겨진다.

[C++]

스트림 버퍼를 재생하려면 ,dwFlags 파라미터에 DSBPLAY_LOOPING 를 지정해 IDirectSoundBuffer::Play 메소드를 호출한다.

재생을 정지하려면 ,IDirectSoundBuffer::Stop 메소드를 호출한다. 이 메소드는 버퍼를 즉시에 정지하므로, 모든 데이터가 재생된 것을 확인할 필요가 있다. 이것을 실시하려면 , 재생 위치를 폴링 하는지, 통지 위치를 설정한다.

버퍼에 스트리밍 하려면 , 다음의 스텝이 필요하다.

  1. IDirectSoundBuffer::Lock 를 사용해, 버퍼의 일부를 잠근다. 이 메소드는, 데이터가 기술되는 1 개(살), 혹은 2 개의 주소를 돌려준다.
  2. 이 1 개(살) 또는 2 개의 주소에 대해서, 표준의 메모리 카피 루틴을 사용해 오디오 데이터를 기입한다.
  3. IDirectSoundBuffer::Unlock 를 사용해, 버퍼를 언락 한다.

IDirectSoundBuffer::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 을 잠그어 기입하도록(듯이) 한다. 오디오 출력이 중단될 가능성을 최소한으로 억제하기 위해서(때문에), 현재 플레이 포지션의 적어도 1 초 전방으로 쓰기를 실시해야 하는 것이다.

다음의 C 함수는,dwOffset 에게 건네진 버퍼의 오프셋(offset)로부터, 데이터를 사운드 버퍼에 기입한다.

BOOL AppWriteDataToBuffer(
    LPDIRECTSOUNDBUFFER lpDsb,  // DirectSound 버퍼.
    DWORD dwOffset,             // 이 샘플 고유의 쓰기 커서.
    LPBYTE lpbSoundData,        // 이 샘플 고유의 데이터 시작점.
    DWORD dwSoundBytes)         // 카피되는 블록의 사이즈.
{
    LPVOID  lpvPtr1;
    DWORD   dwBytes1;
    LPVOID  lpvPtr2;
    DWORD   dwBytes2;
    HRESULT hr;

    // 쓰기 블록의 메모리 주소를 취득한다. 블록이 rack-around 한다
    // (선두로 돌아간다) 경우, 쓰기 블록은 2 개의 부분으로 나누어져 있다.
    hr = lpDsb->lpVtbl->Lock(lpDsb, dwOffset, dwSoundBytes, &lpvPtr1,
        &dwBytes1, &lpvPtr2, &dwBytes2, 0);

    // DSERR_BUFFERLOST 가 돌려주어졌을 경우, 복원과 락의 재시행을 실시한다.
    if (DSERR_BUFFERLOST == hr)
    {
        lpDsb->lpVtbl->Restore(lpDsb);
        hr = lpDsb->lpVtbl->Lock(lpDsb, dwOffset, dwSoundBytes,
            &lpvPtr1, &dwAudio1, &lpvPtr2, &dwAudio2, 0);
    }
    if SUCCEEDED(hr)
    {
        // 포인터에 기입한다.
        CopyMemory(lpvPtr1, lpbSoundData, dwBytes1);
        if (NULL ! = lpvPtr2)
        {
            CopyMemory(lpvPtr2, lpbSoundData+dwBytes1, dwBytes2);
        }
        // 데이터를 릴리즈 해 DirectSound 에 돌려준다.
        hr = lpDsb->lpVtbl->Unlock(lpDsb, lpvPtr1, dwBytes1, lpvPtr2,
            dwBytes2);
        if SUCCEEDED(hr)
        {
            // 성공.
            return TRUE;
        }
    }
    // 락, 언락, 복원중 한쪽이 실패.
    return FALSE;
}
[Visual Basic]

스트림 버퍼를 재생하려면 ,flags 파라미터에 DSBPLAY_LOOPING 를 지정해 DirectSoundBuffer.Play 메소드를 호출한다.

재생을 정지하려면 ,DirectSoundBuffer.Stop 메소드를 호출한다. 이 메소드는 버퍼를 즉시에 정지하므로, 모든 데이터가 재생된 것을 확인할 필요가 있다. 이것을 실시하려면 , 재생 위치를 폴링 하는지, 통지 위치를 설정한다.

DirectSoundBuffer.WriteBuffer 메소드를 사용해 버퍼에 데이터를 스트리밍 한다. 이 메소드에 의해, 버퍼의 임의의 부분에 데이터를 기입할 수 있다. 버퍼 전체에 기입할 수도 있지만, 재생중에 실시해서는 안된다. 매회 버퍼의 일부만을 리프레쉬 하는 것. 예를 들어, 현재 플레이 포지션이 2/4 에 이르자 마자, 버퍼의 최초의 것 1/4 에 기입하도록(듯이) 한다. 오디오 출력이 중단될 가능성을 최소한으로 억제하기 위해서(때문에), 현재 플레이 포지션의 적어도 1 초 전방으로 쓰기를 실시해야 하는 것이다.

다음의 샘플 코드는, 바이트 배열 myBuffer 로부터,dsb 로 나타내진 DirectSoundBuffer 의 선두에 데이터 1,000 바이트를 기입한다.

dsb.WriteBuffer 0, 1000, myBuffer(0), DSBLOCK_DEFAULT

WriteBuffer 는, rack-around를 투과적으로 처리한다. 예를 들어, 세컨드리 버퍼가 10,000 바이트로 생성 되고 있어 어플리케이션이 버퍼의 중간을 지난 오프셋(offset)에 5,000 바이트 기입하는 경우는, 다음과 같이 된다.

dsb.WriteBuffer 8000, 5000, myBuffer(0), DSBLOCK_DEFAULT

이 호출은, 버퍼의 마지막에 최초의 2,000 바이트를 쓰기, 버퍼의 선두에 다음의 3,000 바이트를 기입한다.

계속되는 데이터 기술에 대한 오프셋(offset)를 추적하는 것은, 어플리케이션의 책임이다. 이 처리의 가장 간단한 방법은, 통지 위치를 설정해, 이벤트가 방아쇠 될 때마다 고정한 바이트수를 기입하는 것이다.

상세 정보에 대해서는, 다음의 주제를 참조할것.

  • 현재 플레이 포지션과 현재 라이트 포지션
  • 재생 버퍼의 통지


재생의 컨트롤

[C++]

IDirectSoundBuffer::GetVolume 과 IDirectSoundBuffer::SetVolume 의 각 메소드를 사용하면(자), 재생중의 버퍼의 볼륨의 취득과 설정을 실시할 수 있다. 프라이머리 사운드 버퍼의 볼륨을 설정 하면, 사운드 카드의 웨이브 폼 오디오의 볼륨이 변경된다.

같이IDirectSoundBuffer::GetFrequency 와 IDirectSoundBuffer::SetFrequency 의 각 메소드를 사용하면(자), 샘플링 오디오의 재생 주파수의 취득과 설정을 실시할 수 있다. 프라이머리 버퍼의 주파수는 변경할 수 없다.

팬의 취득과 설정을 실시하려면 ,IDirectSoundBuffer::GetPan 과 IDirectSoundBuffer::SetPan 의 각 메소드를 호출한다. 프라이머리 버퍼의 팬은 변경할 수 없다.

[Visual Basic]

DirectSoundBuffer.GetVolume 과 DirectSoundBuffer.SetVolume 의 각 메소드를 사용하면(자), 재생중의 버퍼의 볼륨의 취득과 설정을 실시할 수 있다. 프라이머리 사운드 버퍼의 볼륨을 설정 하면, 사운드 카드의 웨이브 폼 오디오의 볼륨이 변경된다.

같이DirectSoundBuffer.GetFrequency 와 DirectSoundBuffer.SetFrequency 의 각 메소드를 사용하면(자), 샘플링 오디오의 재생 주파수의 취득과 설정을 실시할 수 있다. 프라이머리 버퍼의 주파수는 변경할 수 없다.

팬의 취득과 설정을 실시하려면 ,DirectSoundBuffer.GetPan 과 DirectSoundBuffer.SetPan 의 각 메소드를 호출한다. 프라이머리 버퍼의 팬은 변경할 수 없다.

이러한 컨트롤의 어느쪽이든을 사용하려면 , 버퍼를 생성 할 때에 적절한 플래그를 설정해야 한다. 「버퍼 컨트롤 옵션」을 참조할것.


현재 플레이 포지션과 현재 라이트 포지션

DirectSound 는 버퍼에 대해, 현재 플레이 포지션 (재생 커서라고도 불린다)과 현재 라이트 포지션 (쓰기 커서라고도 불린다)이라고 하는 2 개의 포인터를 유지하고 있다. 이러한 위치는 버퍼의 바이트 오프셋(offset)이며, 메모리의 절대 주소는 아니다.

[C++]

IDirectSoundBuffer::Play 메소드는, 항상 현재 플레이 포지션으로부터 버퍼의 재생을 시작 한다. 버퍼를 생성 한 시점에서, 재생 위치는 0 으로 설정된다. 사운드가 재생되는 것에 따라, 재생 위치는 이동해, 다음에 출력되는 데이터 바이트를 나타낸다. 버퍼가 정지했을 때는, 재생 위치는 다음의 데이터 바이트에 머무른다.

[Visual Basic]

DirectSoundBuffer.Play 메소드는, 항상 현재 플레이 포지션으로부터 버퍼의 재생을 시작 한다. 버퍼를 생성 한 시점에서, 재생 위치는 0 으로 설정된다. 사운드가 재생되는 것에 따라, 재생 위치는 이동해, 다음에 출력되는 데이터 바이트를 나타낸다. 버퍼가 정지했을 때는, 재생 위치는 다음의 데이터 바이트에 머무른다.

버퍼로 현재 라이트 포지션보다 후의 장소에는, 데이터를 안전하게 기입할 수 있다. 현재 플레이 포지션과 현재 라이트 포지션의 사이에 있는 블록은, 이미 재생이 확정되어 있어, 안전하게 변경할 수 없다.

버퍼를 시계의 문자판으로 나타내, 시계회전의 방향으로 데이터를 기입한다고 생각한다. 재생 위치와 쓰기 위치는, 이 문자판상에서 같은 속도로 회전하는 2 개의 바늘에 비유되어 쓰기 위치는, 항상 재생 위치의 조금 전방에 있다. 재생 위치가 1 을 나타내, 쓰기 위치가 2 를 나타내고 있는 경우는, 데이터를 기입해도 안전한 것은 2 의 뒤 뿐이다. 1 으로 2 의 사이의 데이터는 DirectSound 가 이미 재생 큐에 넣고 있을 가능성도 있으므로, 변경해서는 안된다.

쓰기 위치는, 버퍼에 기입해진 데이터는 아니고 재생 위치에 맞추어 이동한다. 데이터를 스트리밍 하는 경우, 다음에 쓰기를 실시하는 데이터 블록의 위치를 나타내기 위해서(때문에), 개발자는 독자적인 포인터를 유지할 책임을 진다.

[C++]

IDirectSoundBuffer::Lock 메소드의 dwWriteCursor 파라미터가, 현재 라이트 포지션이 아닌 점에 주의 해야 한다. 이것은 버퍼내에서 실제로 데이터를 기입하는 오프셋(offset)이다. 현재 라이트 포지션으로 쓰기를 시작하고 싶은 경우는,dwFlags 파라미터에 DSBLOCK_FROMWRITECURSOR 를 지정한다. 이 경우,dwWriteCursor 파라미터는 무시된다.

어플리케이션은,IDirectSoundBuffer::GetCurrentPosition 메소드를 호출하는 것으로, 현재 플레이 포지션과 현재 라이트 포지션을 취득할 수 있다. IDirectSoundBuffer::SetCurrentPosition 메소드를 사용하면(자), 현재 플레이 포지션을 설정할 수 있지만, 현재 라이트 포지션은 변경할 수 없다.

현재 플레이 포지션을 가능한 한 정확하게 보고하려면 , 세컨드리 버퍼를 생성 할 때에 DSBCAPS_GETCURRENTPOSITION2 플래그를 지정해야 한다. 상세한 것에 대하여는,DSBUFFERDESC 를 참조할것.

[Visual Basic]

DirectSoundBuffer.WriteBuffer 메소드의 start 파라미터가, 현재 라이트 포지션이 아닌 점에 주의 해야 한다. 이것은 버퍼내에서 실제로 데이터를 기입하는 오프셋(offset)이다. 현재 라이트 포지션으로 쓰기를 시작하고 싶은 경우는,flags 파라미터에 DSBLOCK_FROMWRITECURSOR 를 지정한다. 이 경우,start 파라미터는 무시된다.

어플리케이션은,DirectSoundBuffer.GetCurrentPosition 메소드를 호출하는 것으로, 현재 플레이 포지션과 현재 라이트 포지션을 취득할 수 있다. DirectSoundBuffer.SetCurrentPosition 메소드를 사용하면(자), 현재 플레이 포지션을 설정할 수 있지만, 현재 라이트 포지션은 변경할 수 없다.

현재 플레이 포지션을 가능한 한 정확하게 보고하려면 , 세컨드리 버퍼를 생성 할 때에 DSBCAPS_GETCURRENTPOSITION2 플래그를 지정해야 한다. 상세한 것에 대하여는,DSBUFFERDESC 를 참조할것.


재생 버퍼의 통지

[C++]

데이터가 세컨드리 버퍼에 스트리밍 되는 경우, 현재 플레이 포지션이 버퍼내가 있는 점에 도달했을 때나, 재생이 정지했을 때에, 어플리케이션에의 통지를 발생시키고 싶은 것이 있다. IDirectSoundNotify::SetNotificationPositions 메소드를 사용하면(자), 이벤트의 시그널을 송신하는 포인트를 버퍼내에 몇개에서도 설정할 수 있다. 다만, 버퍼의 재생중은 이벤트 포인트의 설정을 실시할 수 없다.

최초로 IDirectSoundNotify 인터페이스에의 포인터를 취득해야 한다. 이 취득은, 버퍼 오브젝트의 QueryInterface 메소드를 사용해 실시한다. 다음에 C++ 에 의한 예를 나타낸다. lpDsbSecondary 는 IDirectSoundBuffer 인터페이스 포인터이다.

LPDIRECTSOUNDNOTIFY lpDsNotify;

HRESULT hr = lpDsbSecondary->QueryInterface(IID_IDirectSoundNotify,
                                            (LPVOID *) &lpDsNotify);
if SUCCEEDED(hr)
{
    // 먼저 진행되어, lpDsNotify->SetNotificationPositions 를 사용한다.
}

IDirectSoundNotify 인터페이스는, 포인터를 취득한 버퍼에 관련지을 수 있고 있다. 새로운 인터페이스의 메소드는 자동적으로 이 버퍼에 적용된다.

여기서 Win32 의 CreateEvent 함수를 사용해 이벤트 오브젝트를 생성 한다. 이 이벤트의 핸들을 DSBPOSITIONNOTIFY 구조체의 hEventNotify 멤버에 기입한다. 이 구조체의 dwOffset 멤버로, 버퍼내에서 이벤트의 시그널을 송신하고 싶은 위치의 오프셋(offset)를 지정한다. 다음에 이 구조체의 주소를, 또는 복수의 통지 위치를 설정하고 싶은 경우는 구조체의 배열을,IDirectSoundNotify::SetNotificationPositions 메소드에 건네준다.

다음의 예는, 1 개의 통지 위치를 설정한다. 루프 하지 않는 조건으로 버퍼의 종료 위치에 도달했는지, 어플리케이션이 IDirectSoundBuffer::Stop 메소드를 호출했는지, 어느 쪽인가의 이유로써 재생이 정지했을 때에, 이벤트의 시그널이 송신된다.

DSBPOSITIONNOTIFY PositionNotify;

PositionNotify.Offset = DSBPN_OFFSETSTOP;
PositionNotify.hEventNotify = hMyEvent;
// hMyEvent 는, CreateEvent()가 돌려준 핸들이다.

lpDsNotify->SetNotificationPositions(1, &PositionNotify);

음성 관리를 사용하고 있는 경우는, 통지 위치에 도달하기 전에 버퍼를 종료할 수 있다. DSBPOSITIONNOTIFY 의 주의를 참조할것.

[Visual Basic]

데이터가 세컨드리 버퍼에 스트리밍 되는 경우, 현재 플레이 포지션이 버퍼내가 있는 점에 도달했을 때나, 재생이 정지했을 때에, 어플리케이션에의 통지를 발생시키고 싶은 것이 있다. DirectSoundBuffer.SetNotificationPositions 메소드를 사용하면(자), 이벤트의 시그널을 송신하는 포인트를 버퍼내에 몇개에서도 설정할 수 있다. 다만, 버퍼의 재생중은 이벤트 포인트의 설정을 실시할 수 없다.

버퍼에 통지 이벤트를 설정하려면 , 버퍼의 코드를 보관 유지하는 폼에 DirectXEvent 오브젝트를 이행 하지 않으면 안 된다. 그리고 DirectX7.CreateEvent 메소드를 호출해, 이벤트 핸들을 생성 한다. 이 이벤트 핸들을 DSBPOSITIONNOTIFY 형의 hEventNotify 멤버에 배치한다. 이 형태를 DirectSoundBuffer.SetNotificationPositions 메소드에 건네준다.

재생 위치가 버퍼의 통지 위치에 도달 하면,DirectXEvent.DXCallback 가 불려 간다.

음성 관리를 사용하고 있는 경우는, 통지 위치에 도달하기 전에 버퍼를 종료할 수 있다. DSBPOSITIONNOTIFY 의 주의를 참조할것.

다음의 코드의 예로, 단일의 통지 위치의 설정 방법법을 나타낸다. 이하는, 모듈의 선언 섹션의 행이다.

Dim gDX As New DirectX7
Dim gDSB As DirectSoundBuffer
Dim dsbpn(0) As DSBPOSITIONNOTIFY
Dim endEvent As Long
Implements DirectXEvent

dsbpn 는 단일의 통지 위치만을 보관 유지하지만, 배열이 아니면 안 되는 것에 주의 해야 한다.

폼이 로드 되면(자), 이벤트가 생성 된다.

endEvent = gDX.CreateEvent(Me)

DirectSoundBuffer 오브젝트의 생성 후, 통지 위치가 설정되어 다음과 같이 이벤트에 관련지을 수 있다.

With dsbpbn(0)
  . hEventNotify = endEvent
  . lOffset = DSBPN_OFFSETSTOP
End With
gDX.SetEvent endEvent
gDSB.SetNotificationPositions 1, dsbpn()

루프 하지 않는 조건으로 버퍼의 종료 위치에 도달했는지, 어플리케이션이 DirectSoundBuffer.Stop 메소드를 호출했는지, 어느 쪽인가의 이유로써 버퍼가 재생을 정지했을 때, 통지의 오프셋(offset)는 DSBPN_OFFSETSTOP 또는 –1 라고 하는, 이벤트가 설정되는 것을 나타내는 특별한 값을 취한다. 이것이 발생 하면, 어플리케이션 정의의 콜백 함수가 자동적으로 불려 가 파라미터로서 endEvent 이벤트 식별자가 건네받는다.

Private Sub DirectXEvent_DXCallback(ByVal eventid As Long)
  If eventid = endEvent Then
    lblStatusDesc.Caption = "Buffer stopped. "
  End If
End Sub


사운드의 믹싱

[C++]

DirectSound 로 복수의 스트림을 믹싱 하는 것은 간단하다. 단순하게 세컨드리 사운드 버퍼를 생성 해, 각 사운드에 대한 IDirectSoundBuffer 인터페이스를 취득하는 것만으로 있다. 다음에 그러한 버퍼를 동시에 재생한다. DirectSound 는, 프라이머리 사운드 버퍼로 믹싱을 실시해, 그 결과를 재생한다.

[Visual Basic]

DirectSound 로 복수의 스트림을 믹싱 하는 것은 간단하다. 단순하게 세컨드리 사운드 버퍼를 생성 해, 각 사운드에 대한 DirectSoundBuffer 오브젝트를 취득하는 것만으로 있다. 다음에 그러한 버퍼를 동시에 재생한다. DirectSound 는, 프라이머리 사운드 버퍼로 믹싱을 실시해, 그 결과를 재생한다.

어플리케이션내의 모든 사운드가 같은 웨이브 포맷을 사용해, 하드웨어 출력 포맷이 그러한 사운드의 포맷과 일치하고 있는 경우, DirectSound 믹서는 최고의 품질의 사운드를 가져온다. 이 경우, 믹서는 포맷 변환을 할 필요가 없다.

[C++]

하드웨어 출력 포맷을 변경하려면 , 프라이머리 사운드 버퍼를 생성 해,IDirectSoundBuffer::SetFormat 메소드를 호출한다. 이 프라이머리 버퍼는 컨트롤의 목적으로만 사용할 수 있는 점에 주의 해야 한다. 이 버퍼의 생성은, 「프라이머리 버퍼에의 액세스」로 설명한 프라이머리 버퍼에의 쓰기 액세스의 취득과 같은 것을 의미하지 않고, 협조 레벨을 DSSCL_WRITEPRIMARY 로 설정할 필요도 없다. 그러나,SetFormat 메소드를 호출하기 위해서(때문에), DSSCL_PRIORITY 또는 그 이상의 협조 레벨을 설정할 필요가 있다. 어플리케이션이 입력초점을 취득할 때마다, DirectSound 는 하드웨어 포맷을, 전회의 호출로 지정된 포맷에 복원한다.

[Visual Basic]

어플리케이션으로 하드웨어 출력 포맷을 변경하려면 , 프라이머리 사운드 버퍼를 생성 해,DirectSoundBuffer.SetFormat 메소드를 호출한다. SetFormat 메소드를 호출하려면 , DSSCL_PRIORITY 의 협조 레벨 또는 그 이상의 레벨이 필요하다. 어플리케이션이 입력초점을 취득할 때마다, DirectSound 는 하드웨어 포맷을, 전회의 호출로 지정된 포맷에 복원한다.


커스텀 믹서

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

대부분의 어플리케이션은 DirectSound 믹서를 사용한다. 이 믹서는 거의 모든 믹싱의 요구를 채워, 이용 가능한 모든 하드웨어 가속화를 자동적으로 활용한다. 그러나, DirectSound 가 제공하지 않는 기능을 어플리케이션이 필요로 하는 경우는, 프라이머리 사운드 버퍼에의 쓰기 액세스를 취득해, 거기서 스트림을 직접 믹싱 할 수 있다.

커스텀 믹서를 이행 하려면 , 어플리케이션은 최초로 DSSCL_WRITEPRIMARY 협조 레벨을 설정해, 프라이머리 사운드 버퍼를 생성 해야 한다. ( 「프라이머리 버퍼에의 액세스」를 참조. ) 다음에 버퍼를 잠그어, 데이터를 쓰기, 버퍼를 언락 해, 다른 버퍼와 같이 재생한다. 다만, DSBPLAY_LOOPING 플래그를 지정해야 한다. 그렇지 않으면 IDirectSoundBuffer::Play 의 호출이 실패하는 점에 주의 해야 한다.

다음의 예는, 어플리케이션이 커스텀 믹서를 이행 하는 방법을 나타낸다. 사운드 디바이스가 데이터 블록의 재생을 반복하지 않게, 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->lpVtbl->Lock(lpDsbPrimary,
                                    dwOldPos, dwDataBytes,
                                    &lpvPtr1, &dwBytes1,
                                    &lpvPtr2, &dwBytes2, 0);
    // DSERR_BUFFERLOST 가 돌려주어졌을 경우, 복원과 락의 재시행을 실시한다.
    if (DSERR_BUFFERLOST == hr)
    {
        lpDsbPrimary->lpVtbl->Restore(lpDsbPrimary);
        hr = lpDsbPrimary->lpVtbl->Lock(lpDsbPrimary,
                                        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->lpVtbl->Unlock(lpDsbPrimary,
                                          lpvPtr1, dwBytes1,
                                          lpvPtr2, dwBytes2);
        if SUCCEEDED(hr)
        {
            return TRUE;
        }
    }
    // 락 또는 언락이 실패했다.
    return FALSE;
}


버퍼 관리

[C++]

IDirectSoundBuffer::GetCaps 는, DirectSoundBuffer 오브젝트의 능력을 취득한다.

어플리케이션은 IDirectSoundBuffer::GetStatus 메소드를 사용해, 현재의 사운드 버퍼가 재생중이나 정지하고 있는지를 확인할 수 있다.

IDirectSoundBuffer::GetFormat 메소드를 사용하면(자), 버퍼내의 사운드 데이터의 포맷 정보를 취득할 수 있다. IDirectSoundBuffer::GetFormat 와 IDirectSoundBuffer::SetFormat 의 각 메소드를 사용해, 프라이머리 사운드 버퍼내의 사운드 데이터의 포맷의 취득과 설정도 실시할 수 있다.

주 : 세컨드리 사운드 버퍼를 생성 한 후, 그 포맷이 고정된다. 다른 포맷을 사용하는 세컨드리 버퍼가 필요한 경우는, 그 포맷을 지정해 새로운 사운드 버퍼를 생성 해야 한다.

사운드 버퍼용의 메모리는 특정의 상황으로 없어지는 일이 있다. 예를 들어, 버퍼가 사운드 카드의 메모리에 놓여져 있어, 다른 어플리케이션이 하드웨어 리소스의 제어를 취득했을 경우이다. 쓰기 우선의 협조 레벨로 동작하는 어플리케이션이 foreground로 이동했을 경우도, 메모리가 없어지는 일이 있다. 이 경우, 다른 모든 사운드 버퍼는 없어지므로, foreground로 이동한 어플리케이션은 프라이머리 버퍼에 직접 기입할 수 있다.

없어진 버퍼에 대해서 IDirectSoundBuffer::Lock ,IDirectSoundBuffer::Play 메소드의 어느쪽이든을 호출하면,DSERR_BUFFERLOST 에러 코드가 돌려주어진다. 버퍼를 잃게 한 어플리케이션의 협조 레벨이 쓰기 우선으로부터 내리거나 그 어플리케이션이 백그라운드로 이동했을 경우는, 다른 어플리케이션은 IDirectSoundBuffer::Restore 메소드를 호출해 버퍼 메모리의 재배치를 시도할 수가 있다. 성공했을 경우, 이 메소드는 버퍼 메모리와 볼륨이나 팬의 설정 등 다른 모든 설정을 복원한다. 그러나, 복원된 버퍼는 유효한 사운드 데이터를 보관 유지하고 있지 않다. 따라서, 어플리케이션은 복원된 버퍼에 데이터를 한번 더 기입해야 하는 것이다.

[Visual Basic]

DirectSoundBuffer.GetCaps 메소드는,DirectSoundBuffer 오브젝트의 능력을 취득한다.

어플리케이션은 DirectSoundBuffer.GetStatus 메소드를 사용해, 현재의 사운드 버퍼가 재생중이나 정지하고 있는지를 확인할 수 있다.

DirectSoundBuffer.GetFormat 메소드를 사용하면(자), 버퍼내의 사운드 데이터의 포맷 정보를 취득할 수 있다. DirectSoundBuffer.GetFormat 와 DirectSoundBuffer.SetFormat 의 각 메소드를 사용해, 프라이머리 사운드 버퍼내의 사운드 데이터의 포맷의 취득과 설정도 실시할 수 있다.

주 : 세컨드리 사운드 버퍼를 생성 한 후, 그 포맷이 고정된다. 다른 포맷을 사용하는 세컨드리 버퍼가 필요한 경우는, 그 포맷을 지정해 새로운 사운드 버퍼를 생성 해야 한다.

사운드 버퍼용의 메모리는 특정의 상황으로 없어지는 일이 있다. 예를 들어, 버퍼가 사운드 카드의 메모리에 놓여져 있어, 다른 어플리케이션이 하드웨어 리소스의 제어를 취득했을 경우이다. 쓰기 우선의 협조 레벨로 동작하는 어플리케이션이 foreground로 이동했을 경우도, 메모리가 없어지는 일이 있다. 이 경우, 다른 모든 사운드 버퍼는 없어지므로, foreground로 이동한 어플리케이션은 프라이머리 버퍼에 직접 기입할 수 있다.

없어진 버퍼에 대해서 DirectSoundBuffer.WriteBuffer ,DirectSoundBuffer.Play 메소드의 어느쪽이든을 호출하면,DSERR_BUFFERLOST 에러 코드가 돌려주어진다. 버퍼를 잃게 한 어플리케이션의 협조 레벨이 쓰기 우선으로부터 내리거나 그 어플리케이션이 백그라운드로 이동했을 경우는, 다른 어플리케이션은 DirectSoundBuffer.Restore 메소드를 호출해 버퍼 메모리의 재배치를 시도할 수가 있다. 성공했을 경우, 이 메소드는 버퍼 메모리와 볼륨이나 팬의 설정 등 다른 모든 설정을 복원한다. 그러나, 복원된 버퍼는 유효한 사운드 데이터를 보관 유지하고 있지 않다. 따라서, 어플리케이션은 복원된 버퍼에 데이터를 한번 더 기입해야 하는 것이다.


압축 웨이브 포맷

DirectSound 는 현재, 압축 웨이브 포맷을 지원 하고 있지 않다. 어플리케이션은 사운드 버퍼에 데이터를 기입하기 전에, Platform SDK 내의 Win32 API 로 제공되고 있는 오디오 압축 매니저 (ACM) 함수를 사용해, 압축된 오디오 데이터를 PCM (pulse-code modulation) 데이터에 변환해야 한다. 실제, 사운드 버퍼 메모리에의 포인터를 잠그어, ACM 에 이 포인터를 건네주면(자), 데이터는 최대의 효율로 사운드 버퍼에 직접 디코드할 수 있다.


DirectSound 의 3D 에의 응용

DirectSound 에 의해, 어플리케이션은 음원이나 청취자의 외관의 위치 (정정도)나 방향을 변경할 수 있다. 게다가 돕라시후트를 사용해 음원과 청취자의 상대속도도 시사할 수 있다.

다음의 주제에서는, 3D 사운드의 기본적 개념을 몇개인가 소개한다.

  • Direct3D 에의 통합
  • 단청의 음원과 스테레오 음원
  • 음원 위치의 인식

다음의 주제에서는, 어플리케이션내에서의 3D 사운드의 사용법에 대한 정보를 나타낸다.

  • DirectSound 3D 버퍼
  • DirectSound 3D 청취자


Direct3D 에의 통합

[C++]

IDirectSound3DBuffer 와 IDirectSound3DListener 의 각 인터페이스는, Direct3D® 와 조합해 동작하도록(듯이) 설계되고 있다. Direct3D 가 가상 환경내의 오브젝트를 배열할 때에 사용하는 위치 결정 정보는, 음원을 배열하는 목적으로도 사용할 수 있다. Direct3D 프로그래머에게 있어 기존의 D3DVECTOR 와 D3DVALUE 의 각 구조체는,IDirectSound3DBuffer 와 IDirectSound3DListeners 의 각 인터페이스에서도 사용된다. 또, Direct3D 로 사용되고 있는 왼손 좌표계와 같은 것이 DirectSound 에서도 채용되고 있다. (좌표계에 대해서는, Direct3D 의 「3D 좌표계」를 참조할것. )

Direct3D 의 시스템 콜 백 메카니즘을 사용해, 어플리케이션에의 3D 사운드의 이행을 간소화할 수 있다. 예를 들어, 어플리케이션 정의 함수 D3DRMFRAMEMOVECALLBACK 를 사용해, 어플리케이션내의 프레임의 움직임을 감시해, 어느 조건이 성립했을 때만 사운드 환경을 변경할 수 있다.

[Visual Basic]

DirectSound3DBuffer 와 DirectSound3DListener 의 각 클래스는, Direct3D® 와 조합해 동작하도록(듯이) 설계되고 있다. Direct3D 가 가상 환경내의 오브젝트를 배열할 때에 사용하는 위치 결정 정보는, 음원을 배열하는 목적으로도 사용할 수 있다. Direct3D 프로그래머에게 있어 기존의 D3DVECTOR 형은,DirectSound3DBuffer 와 DirectSound3DListener 의 각 클래스에서도 사용된다. 또, Direct3D 로 사용되고 있는 왼손 좌표계와 같은 것이 DirectSound 에서도 채용되고 있다. (좌표계에 대해서는, Direct3D 의 「3D 좌표계」를 참조할것. )

보통, DirectSound 에서는 거리는 미터 단위로 측정된다. 어플리케이션이 3D 그래픽의 측정 단위로서 미터 이외의 것을 사용하고 있는 경우,거리 계수를 설정해, 어플리케이션이 사용하는 거리 단위가 몇 미터에 상당할까를 부동 소수점의 값으로서 표현한다. 예를 들어, 어플리케이션이 피트 단위를 사용하고 있는 경우, DirectSound 의 거리 계수로서 0.3048 을 지정하지만, 이것은 1 피트를 미터 단위로 표현한 것이다.


단청의 음원과 스테레오 음원

DirectSound 는 단청의 입력으로부터 고유의 스테레오 출력을 생성 하므로, DirectSound 의 3D 사운드 환경에서는 스테레오 음원이 특별히 도움이 되는 것은 아니다. 어플리케이션이 스테레오 사운드 버퍼를 사용하는 경우, 각 샘플의 좌우 각각의 값을 평균화한 다음에, 3D 처리를 적용한다.

DirectSound 의 3D 능력을 이용 하면나무는, 어플리케이션은 단청의 음원을 제공해야 한다. 시스템이 스테레오 음원을 단청의로 변환하는 기능을 갖추고 있는 경우에서도, 스테레오를 공급할 이유는 없고, 변환이 시간의 헛됨이 된다.


음원 위치의 인식

현실의 세계에서는, 공간내의 음원 위치의 인식은, 다수의 요소에 영향을 받는다. 다음에 그 일부를 나타낸다.

  • 볼륨. 소리를 내는 물체가 청취자로부터 멀어지는 만큼, 그 소리는 작게 되어 간다. 이 현상은 롤 오프로 불리고 있다.
  • 청감 위에의 강도의 차이. 청취자의 우측향으로 발생한 소리는, 왼쪽귀보다 오른쪽귀의 (분)편으로 크게 들린다. 이 이펙트는, 스테레오 사운드 시스템의 소리를 듣는 것에 비슷하다.
  • 도달이 질질 꺼라. 청취자의 우측향으로 발생한 소리는, 왼쪽귀보다 약간 빨리 오른쪽귀에 도달한다. (이 차이의 시간은, 약 1 밀리 세컨드이다. )
  • 소음. 귀는 적극적으로 도착해 있으므로, 청취자의 뒤방향으로 발생한 소리는, 전으로 발생한 소리에 비해 희미하게 약해지고 있다. 게다가 우측향으로 소리가 발생했을 경우, 왼쪽귀에 닿는 소리는, 머리 부분에 차단해지는 것으로 왼쪽귀의 방향에 의해 약해진다.

인간이 소리의 위치를 식별하기 위한 단서는 이만큼은 아니지만, 여기에 올린 것은 주요한 것이다. 그리고 DirectSound 의 위치 결정 시스템은 이러한 요소를 제공한다. 3D 사운드용으로 최적화된 하드웨어는, 다를 방향으로부터 발 다투어지는 소리의 높이나 타이밍에 대한 귓불의 이펙트 등, 다른 단서도 지원 할 수 있다. 이 이펙트의 배경에 있는 수학적 이론을머리 부분 전달 함수라고 부른다.

그러나, 매우 중요한 소리의 위치 식별 요소는, 음원의 시각적인 외관의 위치이다. 예를 들어, 멀리 있는 작은 점으로서 보이고 있던 발사체가, 대륙간 탄도 미사일의 크기가 되어, 매우 큰 소리를 내 관찰자의 두상을 넘어 가면, 청취자는 음원의 위치와 속도를 파악하기 위한 음향 위에의 사소한 단서를 필요로 하지 않는다.


DirectSound 3D 버퍼

[C++]

3D 사운드 버퍼는 다른 사운드 버퍼와 같은 방법으로 생성과 관리를 해IDirectSoundBuffer 인터페이스의 모든 메소드도 이용할 수 있다. 다만, 3D 의 파라미터를 설정하려면 , 버퍼용의 IDirectSound3DBuffer 인터페이스를 취득할 필요가 있다. 이 인터페이스를 지원 하는 것은, DSBCAPS_CTRL3D 플래그를 지정해 생성 된 사운드 버퍼 뿐이다.

여기에서는, 어플리케이션이 IDirectSound3DBuffer 인터페이스를 사용해 버퍼를 관리하는 방법과 인터페이스의 메소드를 사용한 버퍼 파라미터의 관리에 대해 설명한다. 다음의 토픽을 다룬다.

[Visual Basic]

3D 환경에 있어서의 각 음원은, 그 취득원이 되는 DirectSoundBuffer 의 3D 프로퍼티를 제어하는 DirectSound3DBuffer 오브젝트로 나타내진다. DirectSound3DBuffer 오브젝트는, DSBCAPS_CTRL3D 플래그로 생성 된 DirectSoundBuffer 로부터 마셔 취득할 수 있다.

여기에서는, 어플리케이션이 DirectSound3DBuffer 클래스 메소드 사용해 버퍼를 관리하는 방법에 대해 설명한다. 다음의 토픽을 다룬다.

  • DirectSound3DBuffer 오브젝트의 취득
  • DirectSound3DBuffer 의 배치 파라미터
  • 최소 거리와 최대 거리
  • 처리 모드
  • 버퍼의 위치와 속도
  • 사운드 콘


DirectSound3DBuffer 오브젝트의 취득

[C++]

IDirectSound3DBuffer 인터페이스에의 포인터를 취득하려면 , 최초로 세컨드리 3D 사운드 버퍼를 생성 해야 한다. 이것을 생성 하려면 ,IDirectSound::CreateSoundBuffer 메소드를 사용해,DSBUFFERDESC 구조체의 dwFlags 멤버에 DSBCAPS_CTRL3D 플래그를 지정한다. 그리고 생성 된 버퍼에 대해서 IDirectSoundBuffer::QueryInterface 메소드를 호출해, 그 버퍼의 IDirectSound3Dlistener 인터페이스에의 포인터를 취득한다.

다음의 예에서는 C++ 의 구문으로 QueryInterface 메소드를 호출한다.

// LPDIRECTSOUNDBUFFER lpDsbSecondary;
// DSBCAPS_CTRL3D 를 지정해 생성 한 버퍼.
LPDIRECTSOUND3DBUFFER lpDs3dBuffer;

HRESULT hr = lpDsbSecondary->QueryInterface(IID_IDirectSound3DBuffer,
                                            (LPVOID *) &lpDs3dBuffer);
if SUCCEEDED(hr)
{
    // 이 사운드의 3D 파라미터를 설정한다.
    .
    .
    .
}
[Visual Basic]

DirectSound3DBuffer 오브젝트를 취득하려면 , 최초로 세컨드리 3D 사운드 버퍼를 생성 해야 한다. 이것을 생성 하려면 ,DirectSound.CreateSoundBuffer 메소드를 사용해,DSBUFFERDESC 형의 lFlags 멤버에 DSBCAPS_CTRL3D 플래그를 지정한다. 그리고 생성 된 버퍼에 대해서,DirectSoundBuffer.GetDirectSound3DBuffer 메소드를 호출한다.

다음의 예는,DirectSound3DBuffer 오브젝트의 생성 방법을 나타낸다.

Dim dsbd As DSBUFFERDESC
Dim dsBuffer As DirectSoundBuffer
Dim waveFormat As WAVEFORMATEX
Dim ds3dBuffer As DirectSound3DBuffer

'웨이브 포맷을 설정한다.

With waveFormat
    . nSize = LenB(waveFormat)
    . nFormatTag = WAVE_FORMAT_PCM
    . nChannels = 2
    . lSamplesPerSec = 22050
    . nBitsPerSample = 16
    . nBlockAlign = _
            waveFormat.nBitsPerSample / 8 * waveFormat.nChannels
    . lAvgBytesPerSec = _
            waveFormat.lSamplesPerSec * waveFormat.nBlockAlign
End With

'세컨드리 버퍼의 생성.

dsbd.lFlags = DSBCAPS_CTRL3D
Set dsBuffer = m_ds.CreateSoundBuffer(dsbd, waveFormat)

' 3D 버퍼 오브젝트의 취득.

Set ds3dBuffer = dsBuffer.GetDirectSound3DBuffer


DirectSound3Dbuffer 의 배치 파라미터

[C++]

어플리케이션은, 3D 사운드 파라미터의 취득이나 설정을 개별 또는 배치 단위로 실시할 수 있다. 개별의 값을 설정하려면 , 어플리케이션으로 적용 가능한 IDirectSound3DBuffer 인터페이스 메소드를 사용할 수 있다. 그러나, 모든 값을 한 번으로 설정 또는 취득할 필요가 생기는 일도 자주 있다. 그 경우는,IDirectSound3DBuffer::GetAllParameters 와 IDirectSound3DBuffer::SetAllParameters 의 각 메소드를 사용한다.

[Visual Basic]

어플리케이션은, 3D 사운드 파라미터의 취득이나 설정을 개별 또는 배치 단위로 실시할 수 있다. 개별의 값을 설정하려면 , 어플리케이션으로 적용 가능한 DirectSound3DBuffer 오브젝트 메소드를 사용할 수 있다. 그러나, 모든 값을 한 번으로 설정 또는 취득할 필요가 생기는 일도 자주 있다. 그 경우는,DirectSound3DBuffer.GetAllParameters 와 DirectSound3DBuffer.SetAllParameters 의 각 메소드를 사용한다.

또, 파라미터의 변경은, 그것들에 지연의 플래그를 붙여 두어 그 후 모든 것을 한 번에 실행하는 것으로보다 효율적으로 실시할 수 있다. 상세한 것에 대하여는, 「지연 설정」을 참조할것.


최소 거리와 최대 거리

청취자가 음원에 가까워지는 것에 따라 소리는 커진다. 거리가 반이 되면 볼륨은 배가 된다. 그러나, 특정의 점을 지나면(자), 볼륨이 계속 증가하는 것은 합리적은 아니다. 이것이 음원의최소 거리이다.

어플리케이션이 다른 소리의 절대 볼륨 레벨의 차이를 보정해야 하는 경우, 최소 거리는 특별히 도움이 된다. 예를 들어, 제트 엔진의 소리는 벌의 날개소리보다 훨씬 크지만, 실용 위에의 이유로써 이러한 소리를 동일한 정도의 절대 볼륨으로 녹음해야 한다. 어플리케이션은 제트 엔진의 최소 거리를 100 미터, 벌의 최소 거리를 2 센치로 설정하는 것을 생각된다. 이러한 설정에서는, 청취자가 200 미터 떨어지면(자) 제트 엔진은 반의 볼륨이 되어, 청취자가 4 센치 떨어지면(자) 벌의 날개소리는 반의 볼륨이 된다.

사운드 버퍼의 디폴트의 최소 거리는, DS3D_DEFAULTMINDISTANCE 이며, 현재는 1 단위로 정의되고 있다. 이 값을 변경하지 않는 한, 유저로부터 2 미터 떨어지면(자) 소리는 반의 크기, 4 미터 떨어지면(자) 1/4 의 크기가 된다. 대부분의 사운드에서는, 아마 이것보다 큰 최대 거리를 설정할 것이다.

음원의최대 거리란, 그 이상 떨어져도 소리가 보다 작게 안 되는 거리를 의미한다. DirectSound 의 3D 버퍼의 디폴트의 최대 거리 (DS3D_DEFAULTMAXDISTANCE)는 매우 큰 값이며, 소리가 들리지 않게 되었다고 해도 계속 감쇠를 계산해야 하는 것을 의미한다. 불필요한 처리를 피하기 위해서(때문에), 어플리케이션은 적절한 최대 거리를 설정해, 버퍼를 생성 할 때에 DSBCAPS_MUTE3DATMAXDISTANCE 플래그를 포함해야 하는 것이다.

사운드가 들리지 않게 되는 것을 방지하는 목적으로도, 최대 거리를 이용할 수 있다. 예를 들어, 어느 사운드의 최소 거리를 100 미터로 설정해, 1,000 미터 이상 떨어지면(자) 그 사운드가 사실상 들리지 않게 되면(자) 가정한다. 여기서 최대 거리를 800 미터로 설정 하면, 거리 에 관계없이, 그 사운드는 최대 볼륨의 적어도 1/8 로 들리는 것이 보증된다. 물론, 이 경우는 DSBCAPS_MUTE3DATMAXDISTANCE 플래그를 설정하지 않는다.

다음의 그림은, 최소 거리와 최대 거리의 개념을 나타낸다.

[C++]

최소 거리값의 설정과 취득을 실시하려면 IDirectSound3DBuffer::SetMinDistance 와 IDirectSound3DBuffer::GetMinDistance 의 각 메소드를 사용한다. 같이 최대 거리값의 설정과 취득을 실시하려면 IDirectSound3DBuffer::SetMaxDistance 와 IDirectSound3DBuffer::GetMaxDistance 의 각 메소드를 사용한다.

[Visual Basic]

최소 거리값의 설정과 취득을 실시하려면 DirectSound3DBuffer.SetMinDistance 와 DirectSound3DBuffer.GetMinDistance 의 각 메소드를 사용한다. 같이 최대 거리값의 설정과 취득을 실시하려면 DirectSound3DBuffer.SetMaxDistance 와 DirectSound3DBuffer.GetMaxDistance 의 각 메소드를 사용한다.

디폴트에서는, 거리값은 미터 단위로 나타내진다. 「거리 계수」를 참조할것.

모든 사운드 버퍼로, 거리가 볼륨에 미치는 이펙트를 조정하려면 ,롤 오프 계수를 변경한다.


처리 모드

사운드 버퍼는, 표준, 머리 상대 (청취자 상대), 무효의 3 개의 처리 모드를 가진다.

표준 모드에서는, 음원은 월드 스페이스내의 절대 위치와 절대 방향에 근거해 처리된다. 이것은 디폴트의 모드이다.

[C++]

머리 상대 (청취자 상대) 모드에서는, 청취자의 이동과 회전에 응해, 버퍼는 월드 스페이스내에서 자동적으로 위치 조정된다. IDirectSound3DBuffer::SetPosition ,IDirectSound3DBuffer::SetVelocity ,IDirectSound3DBuffer::GetConeOrientation 등의 메소드로 값의 설정과 취득을 실시할 수 있지만, 이것들은 모두 청취자의 현재의 위치, 속도, 방향에 대한 상대적인 것이다.

무효 모드에서는 3D 사운드 처리는 무효가 되어, 사운드는 청취자의 머릿속심으로 발생하고 있도록(듯이) 들린다.

어플리케이션은 IDirectSound3DBuffer::SetMode 메소드를 사용해 3D 사운드 버퍼의 모드를 설정한다.

[Visual Basic]

머리 상대 (청취자 상대) 모드에서는, 청취자의 이동과 회전에 응해, 버퍼는 월드 스페이스내에서 자동적으로 위치 조정된다. DirectSound3DBuffer.SetPosition ,DirectSound3DBuffer.SetVelocity ,DirectSound3DBuffer.GetConeOrientation 등의 메소드로 값의 설정과 취득을 실시할 수 있지만, 이것들은 모두 청취자의 현재의 위치, 속도, 방향에 대한 상대적인 것이다.

무효 모드에서는 3D 사운드 처리는 무효가 되어, 사운드는 청취자의 머릿속심으로 발생하고 있도록(듯이) 들린다.

어플리케이션은 DirectSound3DBuffer.SetMode 메소드를 사용해 3D 사운드 버퍼의 모드를 설정한다.


버퍼의 위치와 속도

[C++]

어플리케이션은,IDirectSound3DBuffer::SetPosition 와 IDirectSound3DBuffer::GetPosition 의 각 메소드를 사용해, 3D 공간에서의 음원의 위치의 설정과 취득을 실시할 수 있다. 포지션은 처리 모드에 근거해, 월드 스페이스나 청취자의 어느 쪽인지를 기준으로 한 상대적인 벡터로서 나타내진다.

DirectSound 가 청취자에 대한 돕라시후트에페크트를 계산할 때에 사용하는 속도값의 설정이나 취득을 실시하려면 ,IDirectSound3DBuffer::SetVelocity 와 IDirectSound3DBuffer::GetVelocity 의 각 메소드를 사용한다. 속도는 초쯤의 거리 단위로 측정된다. 디폴트에서는 미터/초이다.

[Visual Basic]

어플리케이션은,DirectSound3DBuffer.SetPosition 와 DirectSound3DBuffer.GetPosition_ 의 각 메소드를 사용해, 3D 공간에서의 음원의 위치의 설정과 취득을 실시할 수 있다. 포지션은 처리 모드에 근거해, 월드 스페이스나 청취자의 어느 쪽인지를 기준으로 한 상대적인 벡터로서 나타내진다.

DirectSound 가 청취자에 대한 돕라시후트에페크트를 계산할 때에 사용하는 속도값의 설정이나 취득을 실시하려면 ,DirectSound3DBuffer.SetVelocity 와 DirectSound3DBuffer.GetVelocity 의 각 메소드를 사용한다. 속도는 초쯤의 거리 단위로 측정된다. 디폴트에서는 미터/초이다.

속도가 버퍼의 실제의 위치나 이동으로부터 완전하게 독립하고 있는 점에 주의 해야 한다. 버퍼의 적절한 속도를 설정하는 작업은, 완전하게 어플리케이션에 의존하고 있다.


사운드 콘

어느 방향으로도, 거리에 응해 소리의 크기가 정해진다. 방향이 있는 소리는 사운드 콘이다.

[C++]

DirectSound 의 사운드 콘은, 내부 콘과 외부 콘으로 형성된다. 내부 콘의 안쪽에서는, 볼륨은 콘이 존재하지 않는 경우와 같은 크기가 된다. 바꾸어 말하면(자), 보통의 볼륨으로부터의 감쇠는 발생하지 않는다. (물론, 보통의 볼륨은 최대 볼륨이라고는 할 수 없다. 보통의 볼륨은 IDirectSoundBuffer::SetVolume 메소드에 의해 설정되어서 , 한층 더 청취자와의 거리, 청취자의 방향, 롤 오프 계수, 버퍼의 최소 거리에 의해 정해진다. ). 외부 콘의 외측에서는, 보통의 볼륨은 어플리케이션에 의해 설정된 데시벨수만큼 감쇠한다. 내부 콘과 외부 콘의 사이의 각도는, 내부 볼륨으로부터 외부 볼륨에의 이행 지대이다.

[Visual Basic]

DirectSound 의 사운드 콘은, 내부 콘과 외부 콘으로 형성된다. 내부 콘의 안쪽에서는, 볼륨은 콘이 존재하지 않는 경우와 같은 크기가 된다. 바꾸어 말하면(자), 보통의 볼륨으로부터의 감쇠는 발생하지 않는다. (물론, 보통의 볼륨은 최대 볼륨이라고는 할 수 없다. 보통의 볼륨은 DirectSoundBuffer.SetVolume 메소드에 의해 설정되어서 , 한층 더 청취자와의 거리, 청취자의 방향, 롤 오프 계수, 버퍼의 최소 거리에 의해 정해진다. ). 외부 콘의 외측에서는, 보통의 볼륨은 어플리케이션에 의해 설정된 데시벨수만큼 감쇠한다. 내부 콘과 외부 콘의 사이의 각도는, 내부 볼륨으로부터 외부 볼륨에의 이행 지대이다.

다음의 그림은, 사운드 콘의 개념을 나타낸다.

기술적으로는, DirectSound 내의 모든 3D 버퍼는 사운드 콘이다. 그러나, 외부 볼륨은 0 (즉 감쇠가 존재하지 않는다), 내부 콘과 외부 콘의 각도는 어느쪽이나 360 번이므로, 디폴트에서는 버퍼는 단일 방향의 음원으로서 동작한다. 어플리케이션이 이러한 값을 변경할 때까지는, 사운드에는 외관의 방향은 없다.

사운드 콘을 적절히 설계 하면, 어플리케이션에 극적인 이펙트가 추가된다. 예를 들어 음원을 방의 중앙에 두어, 음원의 방향을, 복도에 접해 연 문의 방향으로 설정한다. 다음에 그 문의 폭에 맞추어 내부 콘의 각도를 설정한다. 외부 콘을 그것보다 약간 넓게 설정해, 외부 콘의 볼륨을 청취 불가능하게 설정한다. 청취자가 복도를 걸어, 문의 근처까지 오면(자) 사운드가 들리기 시작한다. 그리고 열려 있는 문의 정면으로 오면(자) 사운드는 최대가 된다.

[C++]

어플리케이션은,IDirectSound3DBuffer::SetConeAngles 와 IDirectSound3DBuffer::GetConeAngles 의 각 메소드를 사용해, 사운드 콘을 정의하는 각도의 설정과 취득을 실시한다. 외부 콘의 각도는, 항상 내부 콘의 각도 이상이 아니면 안된다.

어플리케이션은,IDirectSound3DBuffer::SetConeOrientation 와 IDirectSound3DBuffer::GetConeOrientation 의 각 메소드를 사용해, 사운드 콘의 방향의 설정과 취득을 실시한다.

어플리케이션은,IDirectSound3DBuffer::SetConeOutsideVolume 과 IDirectSound3DBuffer::GetConeOutsideVolume 의 각 메소드를 사용해, 외부 콘의 볼륨의 설정과 취득을 실시한다. 외부 콘의 볼륨은,1/100 dB 단위의 부의 수로 나타내진다. 디폴트의 볼륨을 0 으로 해, 이 볼륨은 거기로부터의 감쇠를 나타내기 때문이다.

[Visual Basic]

어플리케이션은,DirectSound3DBuffer.SetConeAngles 와 DirectSound3DBuffer.GetConeAngles 의 각 메소드를 사용해, 사운드 콘을 정의하는 각도의 설정과 취득을 실시한다. 외부 콘의 각도는, 항상 내부 콘의 각도 이상이 아니면 안된다.

어플리케이션은,DirectSound3DBuffer.SetConeOrientation 와 DirectSound3DBuffer.GetConeOrientation 의 각 메소드를 사용해, 사운드 콘의 방향의 설정과 취득을 실시한다.

어플리케이션은,DirectSound3DBuffer.SetConeOutsideVolume 과 DirectSound3DBuffer.GetConeOutsideVolume 의 각 메소드를 사용해, 외부 콘의 볼륨의 설정과 취득을 실시한다. 외부 콘의 볼륨은,1/100 dB 단위의 부의 수로 나타내진다. 디폴트의 볼륨을 0 으로 해, 이 볼륨은 거기로부터의 감쇠를 나타내기 때문이다.


DirectSound 3D 청취자

사운드는, 들리고 있을 때 한정해 사운드라고 말할 수 있다. DirectSound 어플리케이션의 3D 사운드 이펙트는, 사운드 버퍼의 위치와 방향과 속도 만이 아니고, 청취자의 위치와 방향과 속도의 영향을 받는다.

[C++]

IDirectSound3DListener 인터페이스는, 3D 공간에 있어서의 청취자의 위치, 방향, 외관의 속도를 컨트롤 한다. 도플러 효과의 양이나 거리에 응한 볼륨의 감쇠 등, 청감 환경의 일반적인 파라미터도 컨트롤 한다.

여기에서는,IDirectSound3Dlistener 인터페이스에의 포인터를 취득하는 방법과 인터페이스 메소드를 사용해 청취자 파라미터를 관리하는 방법을 설명한다. 다음의 토픽을 다룬다.

[Visual Basic]

DirectSound3DListener 클래스는, 3D 공간에 있어서의 청취자의 위치, 방향, 외관의 속도를 컨트롤 한다. 도플러 효과의 양이나 거리에 응한 볼륨의 감쇠 등, 청감 환경의 일반적인 파라미터도 컨트롤 한다.

여기에서는,DirectSound3DListener 오브젝트를 취득하는 방법과 인터페이스 메소드를 사용해 청취자 파라미터를 관리하는 방법을 설명한다. 다음의 토픽을 다룬다.

  • DirectSound3DListener 오브젝트의 취득
  • DirectSound3Dlistener 의 배치 파라미터
  • 지연 설정
  • 거리 계수
  • 청취자의 방향
  • 청취자의 위치와 속도
  • 돕라 계수
  • 롤 오프 계수


DirectSound3DListener 오브젝트의 취득

[C++]

IDirectSound3DListener 인터페이스에의 포인터를 취득하려면 , 최초로 프라이머리 3D 사운드 버퍼를 생성 해야 한다. 이것을 생성 하려면 ,IDirectSound::CreateSoundBuffer 메소드를 사용해, 관련하는 DSBUFFERDESC 구조체의 dwFlags 멤버로 DSBCAPS_CTRL3D 와 DSBCAPS_PRIMARYBUFFER 의 각 플래그를 지정한다. 그리고 생성 된 버퍼에 대해서 IDirectSoundBuffer::QueryInterface 메소드를 호출해, 그 버퍼의 IDirectSound3Dlistener 인터페이스에의 포인터를 취득한다. C++ 의 구문에 의한 다음의 예는 이것을 나타낸다.

/* 이 예에서는, lpds 가 DirectSound 오브젝트에의
   유효한 포인터이라고 상정한다. */

DSBUFFERDESC        dsbd;
LPDIRECTSOUNDBUFFER lpdsbPrimary;

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_IDirectSound3DListener,
            (LPVOID *) &lp3DListener))
    {
    lpdsbPrimary->Release();
    }
}
[Visual Basic]

DirectSound3DListener 오브젝트를 취득하려면 , 최초로 프라이머리 3D 사운드 버퍼를 생성 해야 한다. 이것을 생성 하려면 ,DirectSound.CreateSoundBuffer 메소드를 사용해, 관련하는 DSBUFFERDESC 형의 lFlags 멤버로 DSBCAPS_CTRL3D 와 DSBCAPS_PRIMARYBUFFER 의 각 플래그를 지정한다. 그리고 생성 된 버퍼에 대해서 DirectSoundBuffer.GetDirectSound3DListener 메소드를 호출해,DirectSound3DListener 오브젝트를 취득한다. 다음의 예로 이 스텝을 나타낸다. ds 는 글로벌인 DirectSound 오브젝트이다.

Dim dsbd As DSBUFFERDESC
Dim dsbPrimary As DirectSoundBuffer
Dim waveFormat As WAVEFORMATEX
Dim ds3dListener As DirectSound3DListener

'프라이머리 버퍼를 생성 한다. 프라이머리 버퍼에서는
' waveFormat 파라미터는 무시되므로, 초기화하지 않아 좋다.

dsbd.lFlags = DSBCAPS_CTRL3D Or DSBCAPS_PRIMARYBUFFER
Set dsbPrimary = ds.CreateSoundBuffer(dsbd, waveFormat)

' DirectSound3DListener 오브젝트를 생성 한다.

Set ds3DListener = dsbPrimary.GetDirectSound3DListener

청취자를 취득한 후는, 프라이머리 버퍼 오브젝트는 필요없게 되어, 스코프외에 낼 수 있다.


DirectSound3Dlistener 의 배치 파라미터

[C++]

어플리케이션은, 3D 청취자 오브젝트 파라미터의 취득이나 설정을 개별 또는 배치 단위로 실시할 수 있다. 개별의 값을 설정하려면 , 어플리케이션으로 적용 가능한 IDirectSound3DListener 인터페이스 메소드를 사용할 수 있다. 그러나, 청취자를 표현하는 모든 값을 한 번으로 설정 또는 취득할 필요가 생기는 일도 자주 있다. 그 경우는,IDirectSound3DListener::GetAllParameters 와 IDirectSound3DListener::SetAllParameters 의 각 메소드를 사용하면(자), 배치 파라미터 조작을 1 회의 호출로 실행할 수 있다.

[Visual Basic]

어플리케이션은, 3D 청취자 오브젝트 파라미터의 취득이나 설정을 개별 또는 배치 단위로 실시할 수 있다. 개별의 값을 설정하려면 , 어플리케이션으로 적용 가능한 DirectSound3DListener 오브젝트 메소드를 사용할 수 있다. 그러나, 청취자를 표현하는 모든 값을 한 번으로 설정 또는 취득할 필요가 생기는 일도 자주 있다. 그 경우는,DirectSound3DListener.GetAllParameters 와 DirectSound3DListener.SetAllParameters 의 각 메소드를 사용하면(자), 배치 파라미터 조작을 1 회의 호출로 실행할 수 있다.

또, 파라미터의 변경은, 그것들에 지연의 플래그를 붙여 두어 그 후 모든 것을 한 번에 실행하는 것으로보다 효율적으로 실시할 수 있다. 상세한 것에 대하여는, 「지연 설정」을 참조할것.


지연 설정

[C++]

3D 사운드 버퍼와 청취자의 설정을 변경할 때마다, DirectSound 믹서는 재믹싱을 실시해, CPU 사이클을 소비한다. 3D 설정의 변경에 의한 처리 성능에의 영향을 최소한으로 억제하려면 , 3D 설정을 변경하는 IDirectSound3DListener 와 IDirectSound3DBuffer 의 몇개의 메소드의 dwApply 파라미터로 DS3D_DEFERRED 플래그를 지정한다. 그 후 IDirectSound3DListener::CommitDeferredSettings 메소드를 호출해, 지연 되고 있던 모든 커멘드를 1 회에 실행한다.

[Visual Basic]

3D 사운드 버퍼와 청취자의 설정을 변경할 때마다, DirectSound 믹서는 재믹싱을 실시해, CPU 사이클을 소비한다. 3D 설정의 변경에 의한 처리 성능에의 영향을 최소한으로 억제하려면 , 3D 설정을 변경하는 DirectSound3DListener 와 DirectSound3DBuffer 의 몇개의 메소드의 applyFlag 파라미터로 DS3D_DEFERRED 플래그를 지정한다. 그 후 DirectSound3DListener.CommitDeferredSettings 메소드를 호출해, 지연 되고 있던 모든 커멘드를 1 회에 실행한다.

주 : CommitDeferredSettings 메소드를 호출하기 전에, 어플리케이션이 DS3D_IMMEDIATE 플래그를 지정해 같은 설정 메소드를 호출하면, 모든 지연 설정값이 덧쓰기된다. 예를 들어, DS3D_DEFERRED 플래그를 지정해 청취자 속도를 (1.0, 0.0, 0.0)로 설정한 후, DS3D_IMMEDIATE 플래그를 지정해 청취자 속도를 (2.0, 0.0, 0.0)로 설정 하면, 속도는 (2.0, 0.0, 0.0)이 된다. 그 후, 어플리케이션이 CommitDeferredSettings 메소드를 호출했을 경우에서도, 속도는 (2.0, 0.0, 0.0)인 채로 변화하지 않는다.


거리 계수

DirectSound 는 디폴트의 거리 측정 단위로서 미터를 사용한다. 어플리케이션이 미터를 사용하지 않는 경우, 거리 계수, 즉 벡터의 단위가 되는 임의의 승수를 설정할 수 있다.

[C++]

청취자에 대한 거리 계수를 설정한 후, 청취자에게 적용할 수 있는 임의의 메소드를 호출할 때에, 어플리케이션 고유의 거리 단위를 사용한다. 예를 들어, 현재의 어플리케이션이 측정의 기본 단위로서 피트를 사용하고 있다고 한다. 그 경우,IDirectSound3DListener::SetDistanceFactor 메소드를 호출해,flDistanceFactor 파라미터에 0.3048 (1 피트의 미터 환산값)을 지정한다. 그 이후, 메소드를 호출할 때에 파라미터를 피트 단위로 지정 하면, 그러한 값은 미터 단위에 자동적으로 환산된다.

IDirectSound3DListener::GetDistanceFactor 메소드를 사용하면(자), 청취자에 대해서 설정되어 있는 현재의 거리 계수를 취득할 수 있다.

[Visual Basic]

청취자에 대한 거리 계수를 설정한 후, 청취자에게 적용할 수 있는 임의의 메소드를 호출할 때에, 어플리케이션 고유의 거리 단위를 사용한다. 예를 들어, 현재의 어플리케이션이 측정의 기본 단위로서 피트를 사용하고 있다고 한다. 그 경우,DirectSound3DListener.SetDistanceFactor 메소드를 호출해,distanceFactor 파라미터에 0.3048 (1 피트의 미터 환산값)을 지정한다. 그 이후, 메소드를 호출할 때에 파라미터를 피트 단위로 지정 하면, 그러한 값은 미터 단위에 자동적으로 환산된다.

DirectSound3DListener.GetDistanceFactor 메소드를 사용하면(자), 청취자에 대해서 설정되어 있는 현재의 거리 계수를 취득할 수 있다.

거리 계수는 (1 초 쯤 n 단위로 나타내지는 실제의 속도를 변경하는 것으로써) 주로 도플러 효과에 영향을 미친다. 롤 오프에 직접적인 영향을 미칠 것은 없다. 거리에 응한 감쇠율은, 이 단위를 사용한 최소 거리에 근거하고 있기 때문이다. 어느 사운드의 최소 거리를 2 단위로 설정했을 경우, 4 단위 떨어지면(자) 볼륨은 반이 된다. 거리가 피트나 미터나 다른 단위여도, 이것은 공통이다. 상세한 것에 대하여는, 「최소 거리와 최대 거리」를 참조할것.


청취자의 방향

청취자의방향은, 청취자의 머릿속심을 원점으로 하는 2 개의 벡터,윗쪽 벡터와전방 벡터의 관계에 의해 정의된다. 윗쪽 벡터는 두정부를 지나는 오름새의 직선으로, 전방 벡터는 윗쪽 벡터와 직각을 이루어 청취자의 얼굴을 통과하는 직선이다. 다음의 그림은 이러한 관계를 나타낸다.

[C++]

어플리케이션은 IDirectSound3DListener::SetOrientation 와 IDirectSound3DListener::GetOrientation 의 각 메소드를 사용해, 청취자의 방향의 설정과 취득을 실시한다. 디폴트에서는, 전방 벡터가 (0, 0, 1.0), 윗쪽 벡터가 (0, 1.0, 0)이다.

[Visual Basic]

어플리케이션은 DirectSound3DListener.SetOrientation 와 DirectSound3DListener.GetOrientation 의 각 메소드를 사용해, 청취자의 방향의 설정과 취득을 실시한다. 디폴트에서는, 전방 벡터가 (0, 0, 1.0), 윗쪽 벡터가 (0, 1.0, 0)이다.

이것들 2 개의 벡터는, 항상 서로 대해 직각이 아니면 안된다. 필요에 따라서, DirectSound 는 전방 벡터에 조정을 더해 윗쪽 벡터에 대해서 직각의 관계를 유지한다.


청취자의 위치와 속도

[C++]

어플리케이션은 IDirectSound3DListener::SetPosition 와 IDirectSound3DListener::GetPosition 의 각 메소드를 사용해, 3D 공간에 있어서의 청취자의 위치의 설정과 취득을 실시할 수 있다.

DirectSound 가 청취자에 대한 도플러 효과를 계산할 때에 사용하는 속도값의 설정과 취득을 실시하려면 ,IDirectSound3DListener::SetVelocity 와 IDirectSound3DListener::GetVelocity 의 각 메소드를 사용한다. 속도는 초쯤의 거리 단위로 측정된다. 디폴트에서는 미터/초이다.

[Visual Basic]

어플리케이션은 DirectSound3DListener.SetPosition 와 DirectSound3DListener.GetPosition 의 각 메소드를 사용해, 3D 공간에 있어서의 청취자의 위치의 설정과 취득을 실시할 수 있다.

DirectSound 가 청취자에 대한 도플러 효과를 계산할 때에 사용하는 속도값의 설정과 취득을 실시하려면 ,DirectSound3DListener.SetVelocity 와 DirectSound3DListener.GetVelocity 의 각 메소드를 사용한다. 속도는 초쯤의 거리 단위로 측정된다. 디폴트에서는 미터/초이다.

버퍼와 같이, 청취자의 위치와 속도와는 완전하게 독립하고 있다. 청취자의 적절한 속도를 설정하는 작업은, 완전하게 어플리케이션에 의존하고 있다.


돕라 계수

DirectSound 는,속도를 가지는 버퍼나 청취자에 대해서, 자동적으로 도플러 효과를 생성 한다. 이 이펙트는 누적한다. 청취자와 사운드 버퍼의 양쪽 모두가 이동하고 있는 경우, 시스템은 상대속도를 자동적으로 계산해, 거기에 따라서 도플러 효과를 조정한다.

현실적인 도플러 효과를 어플리케이션에 추가하려면 , 이동하고 있는 모든 오브젝트의 속도를 계산해, 그 음원 또는 청취자의 적절한 속도를 설정해야 한다. 특정의 상황에서는 특수 효과를 가져오기 위해서(때문에), 이 값을 자유롭게 과장 또는 감소시켜도 좋다. 돕라 계수를 변경 하면, 돕라시후트를 전체적으로 증가 또는 감소 당한다.

돕라 계수는, DS3D_MINDOPPLERFACTOR 로부터 DS3D_MAXDOPPLERFACTOR 의 범위에서 변경할 수 있지만, 이것들은 현재 Dsound.h 내에서 0.0 으로 10.0 으로 설정되어 있다. 값 0 은, 사운드에 돕라시후트를 적용하지 않는 것을 의미한다. 다른 값은, 열매 세계의 돕라시후트에 대한 승수를 나타낸다. 바꾸어 말하면, 값 1 (또는 DS3D_DEFAULTDOPPLERFACTOR)은 열매 세계에서 체험하는 돕라시후트를 사운드에 적용하는 것, 값 2 는 열매 세계의 돕라시후트의 2 배를 의미한다. 이하 같이이다.

[C++]

IDirectSound3DListener::SetDopplerFactor 와 IDirectSound3DListener::GetDopplerFactor 의 각 메소드를 사용하면(자), 돕라 계수의 설정과 취득을 실시할 수 있다.

[Visual Basic]

DirectSound3DListener.SetDopplerFactor 와 DirectSound3DListener.GetDopplerFactor 의 각 메소드를 사용하면(자), 돕라 계수의 설정과 취득을 실시할 수 있다.


롤 오프 계수

롤 오프와는, 청취자와 사운드의 거리에 의해 생기는 소리의 감쇠의 정도이다. DirectSound 는 롤 오프 계수라고 부르는 변수에 의해, 롤 오프의 무시, 과장, 열매 세계와 같은 이펙트의 재현이 생긴다.

롤 오프 계수는, DS3D_MINROLLOFFFACTOR 로부터 DS3D_MAXROLLOFFFACTOR 의 범위에서 변경할 수 있지만, 이것들은 현재 Dsound.h 내에서 0.0 으로 10.0 으로 설정되어 있다. 값 DS3D_MINROLLOFFFACTOR 는, 사운드에 롤 오프를 적용하지 않는 것을 의미한다. 다른 값은, 열매 세계의 롤 오프에 대한 승수를 나타낸다. 바꾸어 말하면, 값 1 (DS3D_DEFAULTROLLOFFFACTOR)은 열매 세계에서 체험하는 롤 오프를 사운드에 적용하는 것, 값 2 는 열매 세계의 롤 오프의 2 배를 의미한다. 이하 같이이다.

[C++]

IDirectSound3DListener::SetRolloffFactor 와 IDirectSound3DListener::GetRolloffFactor 의 각 메소드를 사용하면(자), 롤 오프 계수의 설정과 취득을 실시할 수 있다.

[Visual Basic]

DirectSound3DListener.SetRolloffFactor 와 DirectSound3DListener.GetRolloffFactor 의 각 메소드를 사용하면(자), 롤 오프 계수의 설정과 취득을 실시할 수 있다.

개별의 사운드 버퍼의 롤 오프를 변경하기 위해서, 그 버퍼의 최소 거리를 설정할 수 있다. 상세한 것에 대하여는, 「최소 거리와 최대 거리」를 참조할것.


DirectSoundCapture

[C++]

DirectSoundCapture 는, 입력원으로부터 디지털 오디오 데이터를 캡춰하기 위한 툴세트를 어플리케이션에 제공한다. DirectSoundCapture 를 사용하려면 ,IDirectSoundCapture 인터페이스의 인스턴스를 생성 해, 그 메소드를 사용해 1 개의 캡춰 버퍼를 생성 한다. 실제의 캡춰 링은, 버퍼 오브젝트의 메소드에 의해 행해진다.

[Visual Basic]

DirectSoundCapture 는, 입력원으로부터 디지털 오디오 데이터를 캡춰하기 위한 툴세트를 어플리케이션에 제공한다. DirectSoundCapture 을 사용하려면 ,DirectSoundCapture 오브젝트를 생성 해, 그 메소드를 사용해 1 개의 캡춰 버퍼를 생성 한다. 실제의 캡춰 링은,DirectSoundCaptureBuffer 오브젝트의 메소드에 의해 행해진다.

여기에서는, 다음의 토픽을 다룬다.

  • 캡춰 디바이스의 열거
  • DirectSoundCapture 오브젝트의 생성
  • 캡춰 디바이스의 능력
  • 캡춰 버퍼의 생성
  • 캡춰 버퍼의 정보
  • 캡춰 버퍼의 통지
  • 캡춰 버퍼의 사용법


캡춰 디바이스의 열거

[C++]

유저가 좋아하는 재생장치로 단순하게 사운드를 재생할 뿐(만큼)의 어플리케이션에서는, 이용 가능한 디바이스를 열거할 필요는 없다. 디바이스 식별자로서 NULL 를 지정해 DirectSoundCapture 오브젝트를 생성 하는 경우, 디폴트의 디바이스가 존재 하면, 인터페이스는 자동적으로 그 디바이스에 관련지을 수 있다. 디바이스 드라이버가 존재하지 않는 경우는,DirectSoundCaptureCreate 함수의 호출은 실패한다.

[Visual Basic]

유저가 좋아하는 재생장치로 단순하게 사운드를 재생할 뿐(만큼)의 어플리케이션에서는, 이용 가능한 디바이스를 열거할 필요는 없다. 디바이스 식별자로서 하늘의 캐릭터 라인을 지정해 DirectSoundCapture 오브젝트를 생성 하는 경우, 디폴트의 디바이스가 존재 하면, 인터페이스는 자동적으로 그 디바이스에 관련지을 수 있다. 디바이스 드라이버가 존재하지 않는 경우는,DirectX7.DirectSoundCaptureCreate 함수의 호출은 실패한다.

그러나, 특정의 종류의 디바이스를 찾고 있는 경우나, 복수의 디바이스를 사용해 동작할 필요가 있는 경우는, 시스템상에서 이용 가능한 디바이스를 열거해야 한다.

열거는 3 개의 목적으로 사용된다.

  • 이용 가능한 하드웨어를 보고.
  • 각 디바이스에 GUID 를 공급.
  • 각 디바이스를 열거했을 때에, 디바이스에 대해서 DirectSoundCapture 를 초기화. 그 결과, 각 디바이스의 능력을 체크할 수 있다.
[C++]

디바이스를 열거하려면 , DirectSound 가 디바이스를 찾아낼 때마다 호출하는 콜백 함수를 최초로 생성 해야 한다. 필요한 모든 처리를 이 함수내에서 실행해, 함수에 임의의 이름을 붙일 수가 있지만, 이 함수는 prototype인 DSEnumCallback 와 같은 형식에서 선언해야 한다. 이 콜백 함수는, 열거를 계속하는 경우는 TRUE, 그 외 (예를 들어 필요한 능력을 갖춘 디바이스를 찾아낸 후등)의 경우는 FALSE 를 돌려주지 않으면 안 된다.

콜백 함수의 예에 대해서는, 「사운드 디바이스의 열거」를 참조할것. 각 디바이스의 GUID 가, 이 함수에게 건네지는 파라미터의 1 개로서 취득되는 점에 주의 해야 한다.

열거는 DirectSoundCaptureEnumerate 함수를 사용하는 것으로 동작에 옮겨진다.

DWORD pv;  // 임의의 32 비트값.

HRESULT hr = DirectSoundCaptureEnumerate(
        (LPDSENUMCALLBACK) DSEnumProc,
        &pv)
[Visual Basic]

디바이스를 열거하려면 ,DirectX7.GetDSCaptureEnum 메소드를 최초로 호출해, 디바이스의 콜렉션을 나타내는 DirectSoundEnum 오브젝트를 생성 해야 한다. 그 후 DirectSoundEnum.GetDescription ,DirectSoundEnum.GetGuid ,DirectSoundEnum.GetName 의 각 메소드를 사용해 각 디바이스에 대해 문의하고 할 수 있다.


DirectSoundCapture 오브젝트의 생성

[C++]

DirectSoundCapture 오브젝트를 생성 하려면 ,DirectSoundCaptureCreate 함수를 호출한다. 이 함수는,IDirectSoundCapture 인터페이스에의 포인터를 돌려준다.

DirectSoundCaptureCreate 에게 건네지는 lpGUID 파라미터는, 열거에 의해 취득된 GUID, 또는 기호의 캡춰 디바이스를 가리키는 경우는 NULL 여도 괜찮다. 대부분의 경우, NULL 를 건네준다.

CoCreateInstance 함수를 사용해 오브젝트를 생성 할 수도 있다. 그 순서는, DirectSound 오브젝트를 생성 하는 순서와 같다. 상세한 것에 대하여는, 「DirectSound 오브젝트의 생성」을 참조할것. CoCreateInstance 를 사용하는 경우, 멀티미디어 컨트롤 패널로 유저가 선택한 디폴트의 캡춰 디바이스에 대응하는 오브젝트가 생성 된다.

DirectSound 오브젝트와 DirectSoundCapture 오브젝트를 공존시키고 싶은 경우는, DirectSoundCapture 오브젝트의 생성과 초기화를 실시하기 전에, DirectSound 오브젝트의 생성과 초기화를 실시한다.

오디오 기기에 따라서는, 디폴트로 전이중 오디오 구성으로 되어 있지 않은 것도 있다. DirectSound 오브젝트와 DirectSoundCapture 오브젝트의 생성과 초기화 시에 문제가 발생했을 경우는, 유저에 대해서 오디오 디바이스 프로퍼티의 체크와 전이중 오디오가 유효하게 되어 있는 것의 확인을 요구하지 않으면 안 된다.

[Visual Basic]

DirectSoundCapture 오브젝트를 생성 하려면 ,DirectX7.DirectSoundCaptureCreate 메소드를 호출한다. 이 메소드는,DirectSoundCapture 오브젝트를 돌려준다.

DirectSoundCaptureCreate 에게 건네지는 guid 파라미터는, 열거에 의해 취득된 GUID, 또는 기호의 캡춰 디바이스를 가리키는 경우는 하늘의 캐릭터 라인이어도 괜찮다. 대부분의 경우, 하늘의 캐릭터 라인을 건네준다.

DirectSound 오브젝트와 DirectSoundCapture 오브젝트를 공존시키고 싶은 경우는,DirectSoundCapture 오브젝트를 생성 하기 전에,DirectSound 오브젝트를 생성 한다.

오디오 기기에 따라서는, 디폴트로 전이중 오디오 구성으로 되어 있지 않은 것도 있다. DirectSound 오브젝트와 DirectSoundCapture 오브젝트의 생성과 초기화 시에 문제가 발생했을 경우는, 유저에 대해서 오디오 디바이스 프로퍼티의 체크와 전이중 오디오가 유효하게 되어 있는 것의 확인을 요구하지 않으면 안 된다.


캡춰 디바이스의 능력

[C++]

캡춰 디바이스의 능력을 취득하려면 ,IDirectSoundCapture::GetCaps 메소드를 호출한다. 이 메소드의 인수는,DSCCAPS 구조체이다. 다른 구조체와 같이, 이 인수를 건네주기 전에 dwSize 멤버를 초기화해 두지 않으면 안 된다. 반환값으로서 이 구조체는 이 디바이스가 지원 하는 채널수, 및 지원 되는 포맷에 관한 값의 편성을 보관 유지한다. 후자의 값은, Win32 웨이브 폼 오디오 함수로 사용되고 있는 WAVEINCAPS 구조체의 값과 동등하다.

[Visual Basic]

캡춰 디바이스의 능력을 취득하려면 ,DirectSoundCapture.GetCaps 메소드를 호출한다. 이 메소드의 인수는,DSCCAPS 형이다. 반환값으로서 이 형태는 이 디바이스가 지원 하는 채널수, 및 지원 되는 포맷에 관한 값의 편성을 보관 유지한다.


캡춰 버퍼의 생성

[C++]

DirectSoundCapture 오브젝트의 IDirectSoundCapture::CreateCaptureBuffer 메소드를 호출해, 캡춰 버퍼를 생성 한다.

이 메소드에게 건네지는 파라미터의 1 개는 DSCBUFFERDESC 구조체이며, 이것은 희망의 버퍼의 특성을 기술하고 있다. 이 구조체의 마지막 멤버는,WAVEFORMATEX 구조체이지만, 희망의 웨이브 포맷의 상세하게 따라서 이 구조체를 초기화해야 한다. 이 구조체의 멤버의 정보는, 「사운드 데이터」를 참조할것.

어플리케이션이 DirectSound 와 DirectSoundCapture 의 양쪽 모두를 사용하는 경우, 캡춰 버퍼의 포맷이 프라이머리 버퍼의 포맷과 다르고 있으면(자), 캡춰 버퍼의 생성은 실패한다. 일부의 카드는 클럭을 1 개 밖에 준비하고 있지 않기 때문에, 2 개(살)이 다른 주파수로 캡춰와 재생을 실시할 수 없는 것이 원인이다.

다음의 예에서는, 대략 1 초 분의 데이터를 보관 유지하는 캡춰 버퍼를 설정한다.

/* 이 예에서는, pDSC 가 DirectSoundCapture 오브젝트에의
   유효한 포인터인 것을 상정한다. */

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;

pDSCB = NULL;

HRESULT hr = pDSC->CreateCaptureBuffer(&dscbd,
        &pDSCB, NULL);
[Visual Basic]

DirectSoundCapture.CreateCaptureBuffer 메소드를 호출해, 캡춰 버퍼를 생성 한다.

이 메소드에게 건네지는 1 개의 파라미터는 DSCBUFFERDESC 형이며, 이것은 희망의 버퍼의 특성을 기술하고 있다. fxFormat 멤버는 WAVEFORMATEX 형이지만, 희망의 웨이브 포맷의 상세하게 따라서 이 형태를 초기화해야 한다.

어플리케이션이 DirectSound 와 DirectSoundCapture 의 양쪽 모두를 사용하는 경우, 캡춰 버퍼의 포맷이 프라이머리 버퍼의 포맷과 다르고 있으면(자), 캡춰 버퍼의 생성은 실패한다. 일부의 카드는 클럭을 1 개 밖에 준비하고 있지 않기 때문에, 2 개(살)이 다른 주파수로 캡춰와 재생을 실시할 수 없는 것이 원인이다.

다음의 예에서는, 대략 1 초 분의 데이터를 보관 유지하는 캡춰 버퍼를 설정한다.

' DSC 는 DirectSoundCapture 오브젝트.

Dim dscbd As DSCBUFFERDESC
Dim DSCB As DirectSoundCaptureBuffer
Dim waveFormat As WAVEFORMATEX

'웨이브 포맷을 설정한다.

waveFormat.nSize = LenB(waveFormat)
    waveFormat.nFormatTag = WAVE_FORMAT_PCM
    waveFormat.nChannels = 2
    waveFormat.lSamplesPerSec = 22050
    waveFormat.nBitsPerSample = 16
    waveFormat.nBlockAlign = _
            waveFormat.nBitsPerSample / 8 * WaveFormat.nChannels
    waveFormat.lAvgBytesPerSec = _
            waveFormat.lSamplesPerSec * waveFormat.nBlockAlign

' DSCBUFFERDESC 를 설정한다.

dscbd.lFlags = DSCBCAPS_DEFAULT
dscbd.lBufferBytes = waveFormat.lAvgBytesPerSec
dscbd.fxFormat = waveFormat

'캡춰 버퍼를 생성 한다.

Set DSCB = DSC.CreateCaptureBuffer (dscbd)


캡춰 버퍼의 정보

[C++]

IDirectSoundCaptureBuffer::GetCaps 메소드를 사용해, 캡춰 버퍼의 사이즈를 취득한다. 이 구조체를 파라미터로서 건네주기 전에,DSCBCAPS 구조체의 dwSize 멤버를 초기화해 두지 않으면 안 된다. 버퍼 생성시로 설정된, 버퍼내의 데이터 포맷의 정보를 취득할 수도 있다. IDirectSoundCaptureBuffer::GetFormat 메소드를 호출하면, 이 메소드는 WAVEFORMATEX 구조체를 사용해 포맷 정보를 돌려준다. 이 구조체의 멤버의 정보는, 「사운드 데이터」를 참조할것.

lpwfxFormat 파라미터로 NULL 를 지정해 GetFormat 메소드를 최초로 호출하는 것으로, 어플리케이션이 WAVEFORMATEX 구조체를 통해 추가의 포맷 정보를 입수할 수 있는 점에 주의 해야 한다. 이 경우,lpdwSizeWritten 파라미터가 가리키는 DWORD 가, 완전한 포맷 정보를 받는데 필요한 구조체의 사이즈를 받는다.

캡춰 버퍼가 현재 가고 있는 것을 파악하려면 ,IDirectSoundCaptureBuffer::GetStatus 메소드를 호출한다. 이 메소드는 플래그의 편성을 변수 DWORD 에 기입하지만, 그 플래그는 버퍼가 캡춰 링으로 Busy일지 어떨지, Busy의 경우는 루프 하고 있을지 어떨지 (즉 IDirectSoundCaptureBuffer::Start 를 직전에 호출한 시점에서 DSCBSTART_LOOPING 플래그를 세트 하고 있었는지)를 나타낸다.

마지막으로,IDirectSoundCaptureBuffer::GetCurrentPosition 메소드는, 버퍼내에서의 현재의 read 위치와 캡춰 위치를 돌려준다. read 위치는, 이 시점에서 캡춰 되어 버퍼에 놓여진 데이터의 최후이다. 캡춰 위치는, 현재 하드웨어로부터 카피되고 있는 한중간의 데이터 블록의 최후이다. 버퍼로부터 안전하게 카피할 수 있는 것은 read 위치까지의 데이터뿐이다.

[Visual Basic]

DirectSoundCaptureBuffer.GetCaps 메소드를 사용해, 버퍼 능력에 대한 정보를 취득한다. 버퍼 생성시로 설정된 버퍼의 데이터 포맷에 대한 정보를 취득하려면 ,DirectSoundCaptureBuffer.GetFormat 메소드를 호출한다.

캡춰 버퍼가 가고 있는 것을 파악하려면 ,DirectSoundCaptureBuffer.GetStatus 메소드를 호출한다. 이 메소드는 플래그의 편성을 돌려주지만, 그 플래그는 버퍼가 캡춰 링으로 Busy일지 어떨지, Busy의 경우는 루프 하고 있을지 어떨지 (즉 DirectSoundCaptureBuffer.Start 를 직전에 호출한 시점에서 DSCBSTART_LOOPING 플래그를 세트 하고 있었는지)를 나타낸다.

마지막으로,DirectSoundCaptureBuffer.GetCurrentPosition 메소드는, 버퍼내에서의 현재의 read 위치와 캡춰 위치를 돌려준다. read 위치는, 이 시점에서 캡춰 되어 버퍼에 놓여진 데이터의 최후이다. 캡춰 위치는, 하드웨어로부터 카피되고 있는 한중간의 데이터 블록의 최후이다. 버퍼로부터 안전하게 카피할 수 있는 것은 read 위치까지의 데이터뿐이다.


캡춰 버퍼의 통지

[C++]

현재의 read 위치가 버퍼내가 있는 위치 또는 마지막에 달했을 때에, 어플리케이션에의 통지를 발생시키고 싶은 것이 있다. 버퍼내에서 현재의 read 위치까지의 부분은, 안전하게 read가 생긴다. IDirectSoundNotify::SetNotificationPositions 메소드를 사용하면(자), 이벤트의 시그널을 송신하는 포인트를 버퍼내에 몇개에서도 설정할 수 있다.

최초로 IDirectSoundNotify 인터페이스에의 포인터를 취득해야 한다. 「재생 버퍼의 통지」로 설명했던 대로, 캡춰 버퍼의 QueryInterface 메소드를 사용해 이 취득을 실시할 수 있다.

다음에, Win32 의 CreateEvent 함수를 사용해, 이벤트 오브젝트를 생성 한다. 이 이벤트에의 핸들을 DSBPOSITIONNOTIFY 구조체의 hEventNotify 멤버에 쓰기, 이 구조체의 dwOffset 멤버로, 버퍼내에서 이벤트의 시그널을 송신하고 싶은 위치의 오프셋(offset)를 지정한다. 그리고 이 구조체의 주소를, 또는 복수의 통지 위치를 설정하고 싶은 경우는 구조체의 배열을,IDirectSoundNotify::SetNotificationPositions 메소드에 건네준다.

다음의 예는, 3 개의 통지 위치를 설정한다. 1 개의 이벤트는 읽어들여 위치가 버퍼내의 중앙에 이르렀을 때, 2 번째는 마지막 근처에 이르렀을 때, 3 번째는 캡춰가 정지했을 때에, 각각 시그널을 송신한다.

#define cEvents  3

/* 이 예에서는, 다음의 각 변수가 이미 올바르게 초기화되고 있어,
   버퍼를 생성 할 때에 그러한 변수의 wfx 가 버퍼 기술에
   포함할 수 있던 것을 상정한다.

   LPDIRECTSOUNDNOTIFY  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);
[Visual Basic]

현재의 read 위치가 버퍼내가 있는 위치 또는 마지막에 달했을 때에, 어플리케이션에의 통지를 발생시키고 싶은 것이 있다. 버퍼내에서 현재의 read 위치까지의 부분은, 안전하게 read가 생긴다. DirectSoundCaptureBuffer.SetNotificationPositions 메소드를 사용하면(자), 이벤트의 시그널을 송신하는 포인트를 버퍼내에 몇개에서도 설정할 수 있다.

버퍼에 통지 이벤트를 설정하려면 , 버퍼의 코드를 보관 유지하는 폼에 DirectXEvent 오브젝트를 최초로 이행 해야 한다. 다음에,DirectX7.CreateEvent 메소드를 호출해 이벤트 핸들을 생성 해, 그 이벤트 핸들을 DSBPOSITIONNOTIFY 형의 hEventNotify 멤버에 건네준다. 그리고 DSBPOSITIONNOTIFY 형을 DirectSoundCaptureBuffer.SetNotificationPositions 메소드에 건네준다.

재생 위치가 버퍼의 통지 위치에 이르면(자),DirectXEvent.DXCallback 가 불려 간다.


캡춰 버퍼의 사용법

[C++]

사운드의 캡춰는, 다음의 스텝으로 구성된다.

  1. IDirectSoundCaptureBuffer::Start 메소드를 호출해 버퍼링을 시작 한다. 입력 디바이스로부터 얻은 오디오 데이터를, 버퍼의 시작 위치 이후에 기입한다.
  2. 희망의 양의 데이터가 이용 가능하게 될 때까지 기다린다. 캡춰 위치가 특정의 지점에 이르는 시기를 결정하는 방법의 1 개에 대해서는, 「캡춰 버퍼의 통지」를 참조할것.
  3. 충분한 데이터가 이용 가능하게 되었을 때,IDirectSoundCaptureBuffer::Lock 메소드를 호출해 캡춰 버퍼의 일부를 잠근다.

    락을 시도하는 부분이, 캡춰에 사용되려 하고 있는 메모리 부분과 겹치지 않은 것을 확인하려면 , 최초로 IDirectSoundCaptureBuffer::GetCurrentPosition 를 호출해 현재의 read 위치를 취득한다. read 위치에 대해서는, 「캡춰 버퍼의 정보」를 참조할것.

    Lock 메소드의 파라미터로서 읽어들이고 싶은 메모리 블록의 사이즈와 오프셋(offset)를 건네준다. 이 메소드는, 메모리 블록 시작 위치의 주소에의 포인터와 블록의 사이즈를 돌려준다. 블록이 버퍼의 최후로부터 최초에 rack-around 하고 있는 (선두에 돌아오고 있다) 경우, 블록의 섹션 마다 1 개(살), 합계 2 개의 포인터가 돌려주어진다. 버퍼의 락 부분이 rack-around 하고 있지 않는 경우는, 2 번째의 포인터는 NULL 이다.

  4. Lock 메소드가 돌려준 주소와 블록 사이즈를 사용해, 버퍼로부터 데이터를 카피한다.
  5. IDirectSoundCaptureBuffer::Unlock 메소드를 사용해, 버퍼를 언락 한다.
  6. 전데이터의 캡춰가 끝날 때까지, 스텝 2 에서 5 를 반복한다. 다음에,IDirectSoundCaptureBuffer::Stop 메소드를 호출한다.

보통, 캡춰 위치가 버퍼의 마지막에 달하면(자), 버퍼는 캡춰 링을 자동적으로 정지한다. 그러나,IDirectSoundCaptureBuffer::Start 메소드에 건네주는 dwFlags 파라미터로 DSCBSTART_LOOPING 플래그를 세트 했을 경우는, 어플리케이션이 IDirectSoundCaptureBuffer::Stop 메소드를 호출할 때까지 캡춰는 속행된다.

[Visual Basic]

사운드의 캡춰는, 다음의 스텝으로 구성된다.

  1. DirectSoundCaptureBuffer.Start 메소드를 호출해 버퍼링을 시작 한다. 입력 디바이스로부터 얻은 오디오 데이터를, 버퍼의 시작 위치 이후에 기입한다.
  2. 희망의 양의 데이터가 이용 가능하게 될 때까지 기다린다. 캡춰 위치가 특정의 지점에 이르는 시기를 결정하는 방법의 1 개에 대해서는, 「캡춰 버퍼의 통지」를 참조할것.
  3. 충분한 데이터가 이용 가능하게 되었을 때,DirectSoundCaptureBuffer.ReadBuffer 메소드를 호출해 캡춰 버퍼의 일부를 읽어들인다.

    read를 시도하는 부분이, 캡춰에 사용되려 하고 있는 메모리 부분과 겹치지 않은 것을 확인하려면 ,DirectSoundCaptureBuffer.GetCurrentPosition 를 호출해 현재의 read 위치를 취득한다. read 위치에 대해서는, 「캡춰 버퍼의 정보」를 참조할것.

  4. 전데이터의 캡춰가 끝날 때까지, 스텝 2 에서 3 을 반복한다. 다음에,DirectSoundCaptureBuffer.Stop 메소드를 호출한다.

디폴트에서는, 캡춰 위치가 버퍼의 마지막에 달하면(자), 버퍼는 캡춰 링을 자동적으로 정지한다. 그러나,DirectSoundCaptureBuffer.Start 메소드에 건네주는 flags 파라미터로 DSCBSTART_LOOPING 플래그를 세트 했을 경우는, 어플리케이션이 DirectSoundCapture.Stop 메소드를 호출할 때까지 캡춰는 속행된다.


DirectSound 프로퍼티 세트

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

IKsPropertySet 인터페이스를 통해, DirectSound 는 사운드 카드와 그 관련 드라이버의 제공하는 확장 서비스를 지원 할 수 있다.

프로퍼티는 세트에 편성된다. GUID 가 세트를 식별해,ULONG 가 세트내의 특정의 프로퍼티를 식별한다. 예를 들어, 하드웨어 벤더가 반향 이펙트를 생성 할 수 있는 카드를 설계해, DSPROPERTY_REVERBPROPERTIES_HALL 와 DSPROPERTY_REVERBPROPERTIES_STADIUM 등의 프로퍼티를 보관 유지하는 프로퍼티 세트 DSPROPSETID_ReverbProperties 를 정의하는 일도 생각할 수 있다.

보통, 번호 0 으로 시작되는 C 언어의 열거형을 사용해 프로퍼티 식별자를 정의한다.

개별의 프로퍼티에 파라미터를 관련지어도 괜찮다. IKsPropertySet 인터페이스의 사양은, 의도적으로 그러한 파라미터를 미정도리로 하고 있으므로, 프로퍼티 세트의 설계자는, 설계 대상세트내의 프로퍼티에 있어 가장 도움이 되는 방법으로 설계를 실시할 수 있다. 파라미터의 정확한 의미는, 프로퍼티의 정의에 의해 정해진다.

사운드 카드 위에의 확장 프로퍼티를 이용하려면 , 최초로 그 드라이버가 IKsPropertySet 인터페이스를 지원 하고 있을지 어떨지를 확인해, 지원 하고 있는 경우는 그 인터페이스에의 포인터를 취득해야 한다. 이것을 실시하려면 , DirectSound3DBuffer 오브젝트 위에의 현존 하는 인터페이스에 대해서 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 를 사용하는 것은 거의 없다.

조금 바뀐 예에 대해 채택한다. 어느 사운드 카드에는, 몇사람의 유명한 테너 가수의 소리로 일련의 노래를 연주하는 기능이 갖춰지고 있다고 한다. 드라이버 개발자는, DSPROPERTY_SONG_IRISH_EYES 나 DSPROPERTY_SONG_O_SOLE_MIO 등의 프로퍼티를 보관 유지하는 프로퍼티 세트 DSPROPSETID_Song 를 생성 한다. 드라이버 개발자는 이 프로퍼티 세트를 모든 테너 가수에 적용해,pPropertyParams 가 테너의 인스턴스를 정의 하면 지정했다. 여기서 어플리케이션 개발자는, Caruso (카루조)에 이러한 노래의 어느쪽이든을 노래하게 하고 싶다고 생각하고 있다.

/* 하드웨어 벤더가 이미 헤더 파일내에서 CARUSO 와 START
   (을)를 정의하고 있는 것을 상정한다. */

DWORD dwTenor = CARUSO;
BOOL  StartOrStop = START;

HRESULT hr = lpKsPropertySet->Set(
        DSPROPSETID_Song,
        DSPROPERTY_SONG_IRISH_EYES,
        &dwTenor,
        sizeof(dwTenor),
        &StartOrStop,
        sizeof(StartOrStop));


DirectSound 의 성능의 최적화

여기에서는, DirectSound 의 성능을 향상시키는 다른 몇개의 힌트를 제공한다. 다음의 토픽을 다룬다.

  • 버퍼 포맷의 매칭
  • 프라이머리 버퍼의 연속 재생
  • 하드웨어 믹싱의 이용
  • 컨트롤의 변경의 최소화
  • 3D 버퍼에 관계하는 CPU 의 고려사항


버퍼 포맷의 매칭

DirectSound 믹서는, 각 세컨드리 버퍼로부터 얻은 데이터를 프라이머리 버퍼용의 포맷으로 변환한다. 이 변환은 데이터를 프라이머리 버퍼에 믹싱 할 때에 그 자리에서 행해져 CPU 사이클을 소비한다. 프라이머리 버퍼의 포맷을 세컨드리 버퍼 (즉 웨이브 파일)에 맞추는 것으로, 이 오버헤드를 배제할 수 있다.

DirectSound 가 채용하는 포맷 변환 방법에서는, 샘플링 레이트와 채널수를 맞추는 것만으로 좋다. 샘플링 사이즈 (8 비트나 16 비트인가)는 관계없다.


프라이머리 버퍼의 연속 재생

[C++]

사운드가 재생되어 있지 않은 경우, DirectSound 는 믹서 엔진을 정지해, DMA (다이렉트 메모리 액세스)를 정지시킨다. 재생 없음 상태가 빈번하게 발생하는 어플리케이션에서는, 사운드를 재생할 때마다 믹서의 시작과 정지를 실시하는 경우의 오버헤드는, 믹서를 상시 액티브하게 하는 경우의 DMA 의 오버헤드보다 커지는 일이 있다. 또, 사운드 기기나 드라이버에 따라서는, 재생의 빈번한 시작과 정지에 의해 불필요한 잡음을 내는 일도 있다. 어플리케이션이 거의 연속적으로 재생을 실시해, 휴지 시간이 적은 경우는, 프라이머리 버퍼에 대해서 IDirectSoundBuffer::Play 메소드를 호출해, 믹서 엔진을 상시 액티브하게도 할 수 있다. 믹서는 소리를 내지 않고 연속 운전한다.

사운드의 재생이 없을 때에 믹서 엔진을 정지하는 디폴트 상태에 되돌리려면 , 프라이머리 버퍼에 대해서 IDirectSoundBuffer::Stop 메소드를 호출한다.

[Visual Basic]

사운드가 재생되어 있지 않은 경우, DirectSound 는 믹서 엔진을 정지해, DMA (다이렉트 메모리 액세스)를 정지시킨다. 재생 없음 상태가 빈번하게 발생하는 어플리케이션에서는, 사운드를 재생할 때마다 믹서의 시작과 정지를 실시하는 경우의 오버헤드는, 믹서를 상시 액티브하게 하는 경우의 DMA 의 오버헤드보다 커지는 일이 있다. 또, 사운드 기기나 드라이버에 따라서는, 재생의 빈번한 시작과 정지에 의해 불필요한 잡음을 내는 일도 있다. 어플리케이션이 거의 연속적으로 재생을 실시해, 휴지 시간이 적은 경우는, 프라이머리 버퍼에 대해서 DirectSoundBuffer.Play 메소드를 호출해, 믹서 엔진을 상시 액티브하게도 할 수 있다. 믹서는 소리를 내지 않고 연속 운전한다.

사운드의 재생이 없을 때에 믹서 엔진을 정지하는 디폴트 상태에 되돌리려면 , 프라이머리 버퍼에 대해서 DirectSoundBuffer.Stop 메소드를 호출한다.

상세한 것에 대하여는, 「프라이머리 버퍼에의 액세스」를 참조할것.


하드웨어 믹싱의 이용

대부분의 사운드 카드는, 대응하는 DirectSound 드라이버가 존재하면, 어떠한 레벨의 하드웨어 믹싱을 지원 한다. 다음의 힌트는, 하드웨어 믹싱을 가능한 한 이용하는데 도움이 된다.

[C++]
  • 실행시에 IDirectSound::GetCaps 메소드를 호출해, 사운드 가속기 하드웨어가 지원 하고 있는 포맷을 확인해, 할 수 있는 한 그 포맷을 사용한다.
  • 가장 이용이 많은 사운드의 사운드 버퍼를 최초로 생성 한다. 하드웨어로 믹싱 할 수 있는 버퍼수에는 한도가 있다.
  • 버퍼를 하드웨어에 반드시 생성 하려면 ,DSBUFFERDESC 구조체의 dwFlags 멤버에 DSBCAPS_LOCHARDWARE 플래그를 지정한다. 이 플래그를 지정해, 하드웨어 믹싱에 대한 리소스를 이용할 수 없는 경우는,IDirectSound::CreateSoundBuffer 메소드는 실패한다.
  • 음성 관리를 사용해, 하드웨어 리소스가 이용 가능한 때에 버퍼를 리소스에 할당하거나 그다지 중요하지 않은 버퍼를 강제 종료시켜 하드웨어 리소스를 릴리즈 할 수 있도록(듯이) 한다. 상세한 것에 대하여는, 「다이나믹 음성 관리」를 참조할것.
[Visual Basic]

대부분의 사운드 카드는, 대응하는 DirectSound 드라이버가 존재하면, 어떠한 레벨의 하드웨어 믹싱을 지원 한다. 다음의 힌트는, 하드웨어 믹싱을 가능한 한 이용하는데 도움이 된다.

  • 실행시에 DirectSound.GetCaps 메소드를 호출해, 사운드 가속기 하드웨어가 지원 하고 있는 포맷을 확인해, 할 수 있는 한 그 포맷을 사용한다.
  • 가장 이용이 많은 사운드의 사운드 버퍼를 최초로 생성 한다. 하드웨어로 믹싱 할 수 있는 버퍼수에는 한도가 있다.
  • 버퍼를 하드웨어에 반드시 생성 하려면 ,DSBUFFERDESC 형의 lFlags 멤버에 DSBCAPS_LOCHARDWARE 플래그를 지정한다. 이 플래그를 지정해, 하드웨어 믹싱에 대한 리소스를 이용할 수 없는 경우는,DirectSound.CreateSoundBuffer 메소드는 실패한다.


컨트롤의 변경의 최소화

세컨드리 버퍼의 팬, 볼륨, 주파수를 변경 하면 성능에 영향을 준다. 사운드 출력이 중단되는 것을 방지하려면 , DirectSound 믹서는 20ms 에서 100 ms, 또는 그 이상 선행해 믹싱을 실시하지 않으면 안 된다. 컨트롤을 변경했을 경우는, 믹서는 선행 믹싱 버퍼를 플래시 (소거) 해, 변경 후의 사운드를 사용해 재믹싱을 실시하지 않으면 안 된다.

[C++]

송신하는 컨트롤의 변경 회수를 최소로 하는 것은 좋은 생각이다. IDirectSoundBuffer::SetVolume ,IDirectSoundBuffer::SetPan ,IDirectSoundBuffer::SetFrequency 의 각 메소드를 사용하는 루틴의 호출 회수를 줄이도록(듯이) 노력한다. 예를 들어, 애니메이션의 프레임에 동기 해 소리를 왼쪽 스피커로부터 오른쪽 스피커에 작동시키는 루틴을 사용하고 있는 경우,SetPan 메소드를 1 프레임 마다 2 회가 아니고 1 회 부르는 것을 시도한다.

[Visual Basic]

송신하는 컨트롤의 변경 회수를 최소로 하는 것은 좋은 생각이다. DirectSoundBuffer.SetVolume ,DirectSoundBuffer.SetPan ,DirectSoundBuffer.SetFrequency 의 각 메소드를 사용하는 루틴의 호출 회수를 줄이도록(듯이) 노력한다. 예를 들어, 애니메이션의 프레임에 동기 해 소리를 왼쪽 스피커로부터 오른쪽 스피커에 작동시키는 루틴을 사용하고 있는 경우,SetPan 메소드를 1 프레임 마다 2 회가 아니고 1 회 부르는 것을 시도한다.

주 : 3D 컨트롤 (방향, 위치, 속도, 돕라 계수등)을 변경했을 경우도, DirectSound 믹서는 선행 믹싱 버퍼를 재믹싱 해야 한다. 그러나, 3D 컨트롤의 변경을 그룹화 해, 재믹싱을 1 회에 삭감할 수 있다. 「지연 설정」을 참조할것.


3D 버퍼에 관계하는 CPU 의 고려사항

소프트웨어에 의한 3D 버퍼의 에뮬레이션은, 많은 계산 처리를 필요로 한다. 예를 들어, 각 버퍼가 Pentium 90 의 처리 시간의 약 6 퍼센트를 소비하는 일도 있다. 어플리케이션내의 3D 버퍼의 사용시기와 사용 방법을 결정할 때에 이것을 고려할 필요가 있다.

[C++]

3D 사운드의 이용은 최소한으로 억제해 3D 이펙트가 이점이 되지 않는 사운드에는 3D 사운드를 적용하지 않는다. 각 사운드의 3D 이펙트를 간단하게 유효 또는 무효로 할 수 있도록(듯이) 어플리케이션을 설계한다. 임의의 3D 사운드 버퍼에 대한 3D 처리를 정지하려면 , DS3DMODE_DISABLE 플래그를 지정해 IDirectSound3DBuffer::SetMode 메소드를 호출한다.

[Visual Basic]

3D 사운드의 이용은 최소한으로 억제해 3D 이펙트가 이점이 되지 않는 사운드에는 3D 사운드를 적용하지 않는다. 각 사운드의 3D 이펙트를 간단하게 유효 또는 무효로 할 수 있도록(듯이) 어플리케이션을 설계한다. 임의의 3D 사운드 버퍼에 대한 3D 처리를 정지하려면 , DS3DMODE_DISABLE 플래그를 지정해 DirectSound3DBuffer.SetMode 메소드를 호출한다.

DirectSound 는, 3D 오디오 버퍼의 가속화를 실현하기 위한 수단을 하드웨어 메이커에 제공한다. 그러한 오디오 카드로는, 호스트 CPU 의 소비를 고려할 필요는 없다.


웨이브 파일의 사용법

[Visual Basic]

DirectSound 로 웨이브 파일을 사용하는 정보는, 다음의 토픽으로 다룬다.

[C++]

IDirectSound 와 IDirectSoundCapture 의 각 인터페이스는, 웨이브 파일을 처리하기 위한 메소드를 갖추지 않았다. 그러나, 몇개의 샘플 어플리케이션의 소스 코드는, 웨이브 파일을 열어, 생성 해, 파일 헤더의 read와 쓰기를 실시해, 파일과의 사이에 데이터의 스트리밍을 실시하는 함수를 인클루드 하고 있다. 이러한 함수는, Wavread.cpp 와 Wavwrite.cpp 에 있다.

웨이브 파일은 RIFF (Resource Interchange File Format, 리소스 교환 파일 포맷)를 채용하고 있어 헤더 정보 (예를 들어 사운드 샘플의 웨이브 포맷)와 데이터 (샘플 자체)를 보관 유지하는, 임의의 수의 「체크」에 의해 구성되어 있다. Win32 API 는, RIFF 파일을 열거나 닫거나하기 위한 함수나, 체크의 검색 함수등을 제공한다. 이름이 「mmio」로 시작되는 이러한 함수는, 샘플 코드내의 래퍼 함수에 의해 사용되고 있다.

래퍼 함수의 사용법에 대한 자세한 것은, 다음의 2 개의 토픽으로 다룬다.

  • 웨이브 파일의 read
  • 웨이브 파일에의 쓰기


웨이브 파일의 read

[Visual Basic]

짧은 사운드에서는,DirectSound.CreateSoundBufferFromFile 메소드를 사용해 스태틱 버퍼에 웨이브 파일을 로드하는 것이, 웨이브 파일을 재생하는 가장 간단한 방법이다. 메모리에 때마침 들어가지 않을 만큼의 긴 파일에서는, 스트림 버퍼를 생성 해, 부분적으로 파일을 읽어들이지 않으면 안 된다.

웨이브 파일은 RIFF (Resource Interchange File Format, 리소스 교환 파일 포맷)를 채용하고 있어 파일 헤더와 각각 헤더와 데이터로부터 완성되는 임의의 수의 「체크」에 의해 구성되어 있다. 체크헷다는, 데이터의 형태를 식별하는 4 문자의 태그와 데이터의 길이를 주는 Long 로 구성된다.

웨이브 파일 헤더는 다음과 같이 된다.

  • 캐릭터 라인 "RIFF". Long &H46464952 라고 해도 읽기 가능.
  • 파일의 사이즈를 주는 Long.
  • 캐릭터 라인 "WAVE". Long &H45564157 라고 해도 읽기 가능.

최초의 체크는 항상 포맛트체크이며, 다음과 같은 포맷이 된다.

  • 캐릭터 라인 "fmt" 와 거기에 계속되는 스페이스.
  • 포맷 데이터의 사이즈를 주는 Long.
  • 데이터의 웨이브 포맷을 기술하는 데이터. PCM 포맷의 파일에서는, 이 데이터는 WAVEFORMATEX 형의 데이터와 같은 (편성은 다르다) 16 바이트의 데이터가 된다.

웨이브 파일의 PCM 샘플 데이터는, 캐릭터 라인 "data" 로 시작되는 체크에 보관 유지된다. 이것은,Long &H61746164 라고 해도 읽어내진다. 대부분의 경우 이 체크는 포맛트체크에 직접 계속되지만, RIFF 가 확장 가능한 포맷이므로, 다른 타입의 체크가 선행하지 않는다고 하는 보증은 없다. 파일 퍼서에게는, 처리할 수 없는 체크를 무시할 수 있는 능력이 필요하다.

웨이브 파일을 해석하려면 , 3 살의 유저 정의형을 준비 하면이야 있고. 최초의 타입은, 파일 헤더와 포맛트체크의 헤더내의 정보를 모두 받는다.

Private Type FileHeader
    lRiff As Long
    lFileSize As Long
    lWave As Long
    lFormat As Long
    lFormatLength As Long
End Type

2 번째의 타입은, 포맷 데이터를 받는다. 이것에는, 멤버가 다른 순서인 WAVEFORMATEX 형은 사용할 수 없다. 이 형태는, 16 바이트의 체크중 14 바이트만을 취득해야 한다. 왜냐하면, 마지막 Integer 값은 WAVEFORMATEX.lExtra 와 동등해, PCM 파일에서는 사용되지 않기 때문에이다.

Private Type WaveFormat
    wFormatTag As Integer
    nChannels As Integer
    nSamplesPerSec As Long
    nAvgBytesPerSec As Long
    nBlockAlign As Integer
    wBitsPerSample As Integer
End Type

3 번째의 타입은, 데이타체크도 포함 임의의 체크의 헤더를 취득하는데 사용된다.

Private Type ChunkHeader
    lType As Long
    lLen As Long
End Type

다음의 샘플 함수는, 파일이 RIFF 웨이브 파일인 것을 확인해, 샘플 데이터의 시작을 검색해, 웨이브 포맷에 대한 정보를 보관 유지하는 WAVEFORMATEX 형을 돌려준다.

Dim FileFree As Long           '글로벌인 파일 핸들.
Dim lDataLength As Long        '글로벌인 데이터 길이.

Private Function FillFormat(FileName As String) As WAVEFORMATEX

    Dim Header As FileHeader
    Dim HdrFormat As WaveFormat
    Dim chunk As ChunkHeader
    Dim by As Byte
    Dim i As Long

    '파일을 열어, 헤더를 읽어들인다.

    Close #FileFree
    FileFree = FreeFile
    Open FileName For Binary Access Read As #FileFree
    Get #FileFree, , Header

    ' "RIFF" 태그를 체크해, 발견되지 않는 경우는 종료한다.

    If Header.lRiff <> &H46464952 Then
        Exit Function
    End If

    ' "WAVE" 태그를 체크해, 발견되지 않는 경우는 종료한다.

    If Header.lWave <> &H45564157 Then
        Exit Function
    End If

    '포맛트체크의 길이를 체크한다. 16 바이트보다
    '적은 경우는, PCM 데이터는 아니기 때문에 사용할 수 없다.

    If Header.lFormatLength < 16 Then
        Exit Function
    End If

    '포맷을 취득한다.

    Get #FileFree, , HdrFormat

    '포맷 바이트를 버려 다음의 체크를 검색한다.

    For i = 1 To Header.lFormatLength - 16
        Get #FileFree, , by
    Next

    ' "data" 체크에 이를 때까지 체크를 무시한다.

    Get #FileFree, , chunk
    Do While chunk.lType <> &H61746164
        For i = 1 To chunk.lLen
            Get #FileFree, , by
        Next
        Get #FileFree, , chunk
    Loop

    '데이터의 사이즈를 취득한다.

    lDataLength = chunk.lLen

   '포맷 정보를 돌려주어진 형태에 기입한다.

    With FillFormat
        . lAvgBytesPerSec = HdrFormat.nAvgBytesPerSec
        . lExtra = 0
        . lSamplesPerSec = HdrFormat.nSamplesPerSec
        . nBitsPerSample = HdrFormat.wBitsPerSample
        . nBlockAlign = HdrFormat.nBlockAlign
        . nChannels = HdrFormat.nChannels
        . nFormatTag = HdrFormat.wFormatTag
    End With

End Function

이것으로 어플리케이션은, 파일로부터의 데이터를 읽어들여, 세컨드리 사운드 버퍼에 그 데이터를 스트리밍 할 수 있게 된다. 파일로부터 데이터를 직접 DirectSoundBuffer 에 읽어들이는 방법은 없기 때문에, 최초로 Private 버퍼에 그 데이터를 읽어들이고 나서,DirectSoundBuffer.WriteBuffer 를 사용해 그 데이터를 기입하지 않으면 안 된다. 상세한 것에 대하여는, 「스트림 버퍼의 사용법」을 참조할것.

[C++]

Wavread.cpp 내에서 래퍼 함수를 사용하려면 , 다음의 4 개의 변수를 선언해야 한다.

WAVEFORMATEX  *pwfx;          // 웨이브 포맷 정보.
HMMIO         hmmio;          // 파일 핸들.
MMCKINFO      mmckinfoData;   // 체크 정보.
MMCKINFO      mmckinfoParent; // 친체크의 정보.

웨이브 파일을 읽어들이는 최초의 스텝은,WaveOpenFile 함수를 호출하는 것이다. 이 함수는 파일에의 핸들을 취득해, 그 파일이 RIFF 포맷인 것을 확인해, 웨이브 포맷에 관한 정보를 취득한다. 파라미터로서 파일명이라고 선언한 변수중 3 개의 변수의 주소를 지정한다.

if (WaveOpenFile(lpzFileName, &hmmio, &pwfx, &mmckinfoParent) ! = 0)
{
    // 실패.
}

어느 래퍼 함수도, 성공했을 경우는 0 을 돌려주는 점에 주의 해야 한다.

다음의 스텝은 WaveStartDataRead 함수를 호출해, 파일 포인터를 사용해 데이타체크에 도달하는 것이다. 이 함수는 데이타체크용의 MMCKINFO 구조체에의 쓰기를 실시하므로, 이용 가능한 데이터의 양을 파악할 수 있다.

if (WaveStartDataRead(&hmmio, &mmckinfoData, &mmckinfoParent) ! = 0)
    {
    // 실패.
    }

이것으로, 어플리케이션은 파일로부터 세컨드리 버퍼에의 카피를 시작 할 수 있다. 보통은, 데이타체크의 사이즈와 웨이브의 포맷을 취득할 때까지는 사운드 버퍼를 생성 하지 않는다. 다음의 코드는, 파일내의 전데이터를 보관 유지하는데 딱 좋은 사이즈의 스태틱 버퍼를 생성 한다.

/* lpds 가 DirectSound 오브젝트에의 유효한 포인터이다
   (와)과 상정한다. */

LPDIRECTSOUNDBUFFER  lpdsbStatic;
DSBUFFERDESC         dsbdesc;

memset(&dsbdesc, 0, sizeof(DSBUFFERDESC));
dsbdesc.dwSize = sizeof(DSBUFFERDESC);
dsbdesc.dwFlags = DSBCAPS_STATIC;
dsbdesc.dwBufferBytes = mmckinfoData.cksize;
dsbdesc.lpwfxFormat = pwfx;

if FAILED(lpds->CreateSoundBuffer(&dsbdesc, &lpdsbStatic, NULL))
{
    WaveCloseReadFile(&hmmio, &pwfx);
    return FALSE;
}

이 경우는, 어플리케이션은 데이터의 스트리밍을 실시하지 않고, 단순하게 스태틱 버퍼에의 쓰기를 실시하므로, 버퍼 전체는 선두로부터 락 된다. rack-around (선두에 돌아온다)도 발생하지 않기 때문에, 필요한 것은 1 개의 포인터와 바이트 카운트이다.

LPVOID lpvAudio1;
DWORD  dwBytes1;

if FAILED(lpdsbStatic->Lock(
        0,              // 락 시작의 오프셋(offset).
        0,              // 락의 사이즈. 이 경우는 무시된다.
        &lpvAudio1,     // 락 시작의 주소.
        &dwBytes1,      // 락 된 바이트수.
        NULL,           // rack-around의 시작. 미사용.
        NULL,           // rack-around의 사이즈. 미사용.
        DSBLOCK_ENTIREBUFFER))  // 플래그.
{
    // 에러 처리.
    Close();
    .
    .
    .
}

WaveReadFile 함수는, 파일로부터 버퍼의 포인터에 데이터를 카피해, 성공했을 경우는 0 을 돌려준다.

UINT cbBytesRead;

if (WaveReadFile(
        hmmio,              // 파일 핸들.
        dwBytes1,           // 읽어들여야 할 바이트수.
        (BYTE *) lpvAudio1, // 카피처.
        &mmckinfoData,      // 파이르체크 정보.
        &cbBytesRead))      // 실제로 읽힌 바이트수.
{
    // 0 이외의 값이 돌려주어졌을 경우의 실패를 처리한다.
    WaveCloseReadFile(&hmmio, &pwfx);
    .
    .
    .
}

마지막에 어플리케이션은 버퍼를 언락 해, 웨이브 파일을 닫는다.

lpdsbStatic->Unlock(lpvAudio1, dwBytes1, NULL, 0);
Close();

스트림 버퍼의 경우는, 보통은 현재의 read 위치에 의해 결정된 일정한 간격으로 WaveReadFile 를 호출한다. ( 「재생 버퍼의 통지」를 참조. ) 버퍼내의 락 된 부분이 rack-around 하고 (선두로 돌아가고) 있는 경우는, 물론 락 되고 있는 세그먼트(segment) 마다 WaveReadFile 를 1 회 호출해야 하는 것이다.


웨이브 파일에의 쓰기

[Visual Basic]

DirectSoundBuffer.SaveToFile 를 사용하면(자), 짧은 사운드를 세컨드리 버퍼로부터 웨이브 파일에 보존할 수 있다. 이 메소드는 버퍼의 내용 전체를 파일에 카피한다.

많은 경우, 사운드의 보존은 캡춰 버퍼로부터 시작한다. 다음의 코드는, 캡춰 버퍼 dscb 로부터, 파일에 보존할 수 있는 세컨드리 버퍼에 데이터를 이동하는 방법을 나타낸다.

Dim ByteBuffer() As Integer
Dim dsc As DirectSoundCapture
Dim dscd As DSCBUFFERDESC
Dim dsd As DSBUFFERDESC
Dim capCURS As DSCURSORS
.
.
.
' dscd 는 캡춰 버퍼의 포맷으로 초기화되어
' dsb 가 같은 사이즈의 세컨드리 버퍼를
'나타내면(자) 가정한다.

'캡춰 버퍼와 같은 포맷으로
'세컨드리 버퍼를 생성 한다.

Set dsb = ds.CreateSoundBuffer(dsd, dscd.fxFormat)

'캡춰 버퍼의 쓰기 커서까지의 내용을 보관 유지할 수 있다
'크기로 Private 버퍼를 생성 한다.

dscb.GetCurrentPosition capCURS
ReDim ByteBuffer(capCURS.lWrite + 1)

'캡춰 버퍼의 내용을 Private 버퍼에 읽어들인다.

dscb.ReadBuffer 0, capCURS.lWrite * dscd.fxFormat.nBlockAlign, _
        ByteBuffer(0), DSCBLOCK_DEFAULT

'Private 버퍼를 세컨드리 버퍼에 기입한다.

dsb.WriteBuffer 0, capCURS.lWrite, ByteBuffer(0), DSBLOCK_DEFAULT

캡춰 버퍼의 길이를 넘어 버리는 사운드에 대해서는, 개발자 자신이 웨이브 파일을 생성 해, 그 파일에 데이터를 스트리밍 해야 한다. 캡춰 된 데이터를 웨이브 파일에 스트리밍 하는 것은, 다음의 스텝에서 실시한다.

  1. 파일을 생성 해, 파일 헤더, 포맛트체크, 및 데이타체크의 헤더를 기입한다. 포맛트체크는,DirectSoundCaptureBuffer.GetFormat 로 취득할 수 있는 캡춰 버퍼의 포맷을 기술해야 한다. 다만, 포맷의 요소는 WAVEFORMATEX 형과 같은 차례는 아닌 것에 주의 해야 한다. 헤더와 체크의 편성에 대한 정보는, 「웨이브 파일의 read」를 참조할것.
  2. 캡춰 버퍼로부터 Private 버퍼까지, 또 그 버퍼로부터 파일까지의 데이터의 스트리밍을 실시한다. 이 때, 기입해진 바이트의 수를 추적한다. 상세한 것에 대하여는, 「캡춰 버퍼의 사용법」을 참조할것.
  3. 캡춰가 정지해, 모든 데이터가 기입해지면(자), 데이타체크의 길이와 파일의 합계 사이즈를 계산해, 이러한 값을 데이타체크헷다와 파일 헤더의 각각의 적절한 위치에 기입한다.
[C++]

웨이브 파일에의 쓰기를 준비하려면 , 어플리케이션은 최초로, Wavwrite.cpp 내의 함수에게 건네지는 4 개의 변수를 선언해야 한다.

WAVEFORMATEX  wfx;            // 웨이브 포맷 정보.
HMMIO         hmmio;          // 파일 핸들.
MMCKINFO      mmckinfoData;   // 체크 정보.
MMCKINFO      mmckinfoParent; // 친체크 (파일) 정보.

캡춰 버퍼의 정보를 사용해 WAVEFORMATEX 구조체의 초기화도 실시하지 않으면 안 된다.

다음에 WaveOpenFile 함수를 호출해, 희망의 파일명과 글로벌 변수의 주소를 건네준다. 이 함수는 지정된 파일을 생성 해, 어떠한 헤더 정보를 기입한다. Wavwrite.cpp 내의 다른 함수와 같이,WaveOpenFile 는 성공했을 경우에 0 을 돌려준다.

if (WaveOpenFile(pszFileName, &hmmio, &wfx,
        &mmckinfoData, &mmckinfoParent))
{
    // 실패.
}

다음에 WaveStartDataWrite 함수를 호출한다. 이 함수는, 데이타체크를 초기화한다.

if (WaveStartDataWrite(&hmmio, &mmckinfoData, &mmioinfo))
{
     // 실패.
}

이것으로 파일은 데이터를 받을 준비를 할 수 있었다. 다음의 부분적인 코드는, 캡춰 버퍼로부터 파일에 데이터를 카피하는 방법을 나타낸다.

/* 다음의 변수에 유효한 값을 할당할 수 있고 있는 것을
   상정한다.
LPDIRECTSOUNDCAPTUREBUFFER lpdscb;    // 캡춰 버퍼.
DSCBUFFERDESC    dscbDesc;            // 캡춰 버퍼의 기술.
DWORD            dwReadCursor;        // 버퍼내의 내부 커서.
DWORD            dwNumBytes;          // 이용 가능한 바이트수.
DWORD            dwTotalBytesWritten; // 현시점까지 파일내에 기입해진 합계 바이트수.
*/

LPBYTE pbInput1, pbInput2; // 버퍼내의 데이터에의 포인터.
DWORD  cbInput1, cbInput2; // 락 된 부분의 바이트 카운트.
UINT   BytesWritten;       // 파일에 기입해진 바이트 카운트.

if FAILED(hr = lpdscb->Lock(dwReadCursor, dwNumBytes,
                      (LPVOID *) &pbInput1, &cbInput1,
                      (LPVOID *) &pbInput2, &cbInput2, 0))
{
    // 실패.
}
else
{
    if (WaveWriteFile(hmmio, cbInput1, pbInput1, &mmckinfoData,
                    &dwBytesWritten, &mmioinfo))
    {
        // 실패.
    }
    else dwTotalBytesWritten += BytesWritten;
    if (pbInput2 ! = NULL)
    {
        if (WaveWriteFile(hmmio, cbInput2, pbInput2, &mmckinfoData,
                    &BytesWritten, &mmioinfo))
        {
            // 실패.
        }
        else dwTotalBytesWritten += BytesWritten;

    }
    lpdscb->Unlock(pbInput1, cbInput1, pbInput2, cbInput2);

    // 내부 커서를 인크리먼트(increment) 해, rack-around (선두에 돌아온다)를 보정한다.
    dwReadCursor += dwNumBytes;
    while (dwReadCursor >= dscbDesc.dwBufferBytes)
                dwMyReadCursor -= dscbDesc.dwBufferBytes;

}

데이터의 캡춰 링이 끝난 다음에, 파일을 닫는다.

WaveCloseWriteFile(&hmmio, &mmckinfoData,
        &mmckinfoParent, &mmioinfo,
        dwTotalBytesWritten / (wfx.wBitsPerSample / 8));

WaveCloseWriteFile 함수는, 파일내의 샘플의 합계수를 계산해, 그 값을 데이타체크의 헤더에 기입한다.


리소스로부터의 웨이브 데이터의 read

[Visual Basic]

리소스로서 저장 된 사운드는 짧은 일이 많기 때문에, 스태틱 버퍼로 재생되는 것이 바람직하다. 스태틱 버퍼를 생성 해, 리소스로부터의 데이터를 그 버퍼에 기입하려면 ,DirectSound.CreateSoundBufferFromResource 메소드를 사용한다. 예로서 「스태틱 버퍼의 쓰기와 재생」을 참조할것.

한층 더 긴 사운드는 웨이브 파일에 저장 되어 스트림 버퍼로부터 재생된다. 상세한 것에 대하여는, 다음의 주제를 참조할것.

  • 스트림 버퍼의 사용법
  • 웨이브 파일의 read
[C++]

DirectSound API 는, 리소스로부터 웨이브를 읽어들이는 메소드를 갖추지 않았다. 그러나, Dsutil3d.c 에는 몇개의 헬퍼-함수가 있어, DirectMusic 샘플 디렉토리에 있는 3DMusic 샘플용의 소스 코드가 부속되어 있다.

실행 가능 파일이나 DLL 에 웨이브 사운드를 보존하려면 , 웨이브 파일을 리소스로서 임포트 해, 캐릭터 라인의 이름을 할당한다. Dsutil3d.c 가 이러한 리소스를 "WAV" 타입이다고 기대하는 점에 주의 해야 한다. Microsoft® Visual C++® 를 사용하는 경우, 임포트 된 웨이브 파일은 "WAVE" 타입의 리소스에 변환된다. 리소스 파일을 편집해 이 명칭을 "WAV" 로 변경하는지, Dsutil3d.c 내의 c_szWAV 의 대입을 변경해야 한다. 그 결과,FindResource 함수는 "WAVE" 리소스를 검색할 수 있다.

DSLoadSoundBuffer 함수가 적절한 컨트롤 플래그만을 세트 하도록, Dsutil3d.c 를 변경할 수도 있다.

스태틱 버퍼를 생성 해, 사운드를 이 버퍼에 로드하려면 , 단순하게 IDirectSound 인터페이스 포인터와 리소스의 이름을 DSLoadSoundBuffer 함수에 건네준다. 성공했을 경우, 이 함수는 버퍼에의 포인터를 돌려준다. 다음은 샘플의 호출이며,lpds 는 IDirectSound 인터페이스에의 포인터이다.

#include "dsutil.h"

LPDIRECTSOUNDBUFFER  lpdsbFootstep;

lpdsbFootstep = DSLoadSoundBuffer(lpds, "FOOTSTEP");
if (lpdsbFootstep == NULL)
{
    // 실패.
}


DirectSound 튜토리얼

여기에서는, DirectSound 의 기본적인 기능을 C/C++ 또는 Visual Basic 어플리케이션에 이행 하는 방법에 대해 스텝바이스텝으로 설명하는 튜토리얼을 제공한다. 각 튜토리얼은, 이 SDK 의 \Samples\Multimedia\DSound\Tutorials 디렉토리에서 제공되는 일련의 샘플 파일과 대응해, 코드의 흐름에 따라 설명한다. 샘플 코드를 참조하면서 튜토리얼을 읽어 진행시켜 나가는 것을 권한다.

  • DirectSound C/C++ 튜토리얼
  • DirectSound Visual Basic 튜토리얼


DirectSound C/C++ 튜토리얼

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 튜토리얼」을 참조할것.

[C++]

여기에서는, 다음의 튜토리얼을 사용해, DirectSound 의 기본적인 기능을 이행 하는 방법을 스텝바이스텝으로 설명한다.

  • 튜토리얼 1 : 사운드의 재생

    최초의 튜토리얼은, DirectSound 시스템의 설정, 세컨드리 버퍼의 생성, 웨이브 파일로부터의 데이터의 재생을 실시하는 방법을 나타낸다.

  • 튜토리얼 2 : 사운드의 캡춰

    2 번째의 튜토리얼은, DirectSoundCapture 오브젝트와 캡춰 버퍼의 생성, 및 데이터를 웨이브 파일에 기입하는 방법을 나타낸다.


튜토리얼 1 : 사운드의 재생

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 튜토리얼」을 참조할것.

[C++]

이 튜토리얼은, 임의의 사이즈의 웨이브 파일을 재생하는, 단순한 DirectSound 어플리케이션을 생성 하는 방법을 나타낸다.

웨이브 파일을 열어, 읽어들여, 닫는 함수는, DirectX SDK 내의 DSShow3D 툴 어플리케이션에 부속의 모듈인 Wavread.cpp 파일내에 기술되고 있다. 이 튜토리얼로 가리키는 방법을 이행 하려면 , Wavread.cpp 와 Wavread.h 를 프로젝트에 추가해, Winmm.lib 에 링크해야 한다. 그 밖에, 같은 샘플 디렉토리의 Debug.c 와 Debug.h 를 추가하는지, 표준적인 assert 함수를 호출하도록, Wavread.cpp 파일내의 ASSERT 매크로의 호출을 변경해야 한다.

이 튜토리얼내의 메소드 호출은, C 와 C++ 의 어디라도 유효한, Dsound.h 내의 매크로를 통해 가고 있다.

이 튜토리얼은, 이하의 스텝으로 구성되어 있다.

  • 스텝 1 : DirectSound 의 설정
  • 스텝 2 : 웨이브 파일을 연다
  • 스텝 3 : 세컨드리 사운드 버퍼의 생성
  • 스텝 4 : 재생의 통지의 설정
  • 스텝 5 : 재생의 통지의 처리
  • 스텝 6 : 웨이브 파일로부터의 데이터의 스트리밍
  • 스텝 7 : DirectSound 의 슛다운


스텝 1 : DirectSound 의 설정

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 튜토리얼」을 참조할것.

[C++]

이 튜토리얼에서는, 이하의 정의와 글로벌 변수를 필요로 한다.

#define NUMEVENTS 2

LPDIRECTSOUND               lpds;
DSBUFFERDESC                dsbdesc;
LPDIRECTSOUNDBUFFER         lpdsb;
LPDIRECTSOUNDBUFFER         lpdsbPrimary;
LPDIRECTSOUNDNOTIFY         lpdsNotify;
WAVEFORMATEX                *pwfx;
HMMIO                       hmmio;
MMCKINFO                    mmckinfoData, mmckinfoParent;
DSBPOSITIONNOTIFY           rgdsbpn[NUMEVENTS];
HANDLE                      rghEvent[NUMEVENTS];

최초의 스텝은, DirectSound 오브젝트를 생성 해, 협조 레벨을 확립해, 프라이머리 버퍼의 포맷을 설정하는 것이다. 이것들은 모두, 다음의 코드로 가리키는 InitDSound 함수내에서 행해진다.

이 함수는 파라미터로서 메인 윈도우 핸들과 사운드 디바이스의 GUID 에의 포인터의 2 개를 취한다. 대부분의 경우, 2 번째의 파라미터에 NULL 를 건네주어, 디폴트의 디바이스를 사용하도록 지시하지만, 디바이스 열거에 의해 GUID 의 취득도 할 수 있다.

BOOL InitDSound(HWND hwnd, GUID *pguid)
{
   // DirectSound 를 생성 한다.

    if FAILED(DirectSoundCreate(pguid, &lpds, NULL))
        return FALSE;

    // 협조 레벨을 설정한다.

    if FAILED(IDirectSound_SetCooperativeLevel(
            lpds, hwnd, DSSCL_PRIORITY))
        return FALSE;

여기에서는 프라이머리 버퍼의 포맷을 설정할 수 있도록, 프라이머리 협조 레벨을 설정했다. 디폴트의 포맷으로 변경을 더하지 않는 경우, 입력의 포맷 에 관계없이, 출력은 8 비트, 22 kHz 포맷이 된다. 프라이머리 버퍼를 이것보다 위에의 포맷으로 설정해도, 문제는 없다. 세컨드리 버퍼가 이것보다 아래의 포맷이었다고 해도, DirectSound 가 샘플의 변환을 자동적으로 실시하기 때문이다. IDirectSoundBuffer::SetFormat 의 호출이 실패했을 경우도, 문제는 없는 점에 주의 해야 한다. 하드웨어는 이 상위 포맷을 지원 하지 않기 때문에이다. DirectSound 는 단순하게, 이용할 수 있는 가운데 가장 가까운 포맷으로 설정한다.

프라이머리 버퍼의 포맷을 설정하려면 , 최초로 글로벌인 DSBUFFERDESC 구조체로 그 포맷을 기술해, 다음에 그 기술을 IDirectSound::CreateSoundBuffer 메소드에 건네준다.

    // 프라이머리 버퍼를 취득한다.

    ZeroMemory(&dsbdesc, sizeof(DSBUFFERDESC));
    dsbdesc.dwSize = sizeof(DSBUFFERDESC);
    dsbdesc.dwFlags = DSBCAPS_PRIMARYBUFFER;
    if FAILED(lpds->CreateSoundBuffer(&dsbdesc, &lpdsbPrimary, NULL))
        return FALSE;

프라이머리 버퍼 오브젝트를 취득한 다음에, 희망의 웨이브 포맷을 기술해, 그 기술을 IDirectSoundBuffer::SetFormat 메소드에 건네준다.

    // 프라이머리 버퍼의 포맷을 설정한다.

    WAVEFORMATEX wfx;
    memset(&wfx, 0, sizeof(WAVEFORMATEX));
    wfx.wFormatTag = WAVE_FORMAT_PCM;
    wfx.nChannels = 2;
    wfx.nSamplesPerSec = 44100;
    wfx.wBitsPerSample = 16;
    wfx.nBlockAlign = wfx.wBitsPerSample / 8 * wfx.nChannels;
    wfx.nAvgBytesPerSec = wfx.nSamplesPerSec * wfx.nBlockAlign;

    hr = lpdsbPrimary->SetFormat(&wfx);

    return TRUE;
}  // InitDSound()

다음 방향 : 스텝 2 : 웨이브 파일을 연다


스텝 2 : 웨이브 파일을 연다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 튜토리얼」을 참조할것.

[C++]

이 샘플 프로그램은 범용의 웨이브 파일 리더이며, 사운드 데이터가 특정의 포맷인 것을 기대하고 있지 않다. 이 경우는, 데이터의 포맷을 파악할 수 있을 때까지, 세컨드리 사운드 버퍼의 생성을 기다리지 않으면 안 된다.

파일을 열어, 세컨드리 버퍼를 생성 하는 스텝은, SetupStreamBuffer 함수내에 정리하고 있다. 이 함수는 최초로, 직전에 사운드가 연주되고 있던 상태를 클린 업 하기 위해서 필요한 모든 작업을 실시한다.

BOOL SetupStreamBuffer(LPSTR lpzFileName)
{
    // 열려 있는 모든 파일을 닫아 인터페이스를 릴리즈 한다.

    Close();  // Wavread.cpp 의 함수.

    if (lpdsNotify ! = NULL)
    {
        lpdsNotify->Release();
        lpdsNotify = NULL;
    }

    if (lpdsb ! = NULL)
    {
        lpdsb->Release();
        lpdsb = NULL;
    }

이 함수는 다음에 웨이브 파일을 열어, 그 포맷을 취득해, 파일 포인터를 사운드 데이터의 선두에 진행한다. 이 작업은 Wavread.cpp 내의 2 개의 함수를 사용해 실시한다.

    if (WaveOpenFile(lpzFileName, &hmmio, &pwfx,
            &mmckinfoParent) ! = 0)
        return FALSE;
    if (WaveStartDataRead(&hmmio, &mmckinfoData,
            &mmckinfoParent) ! = 0)
        return FALSE;

WaveOpenFile 함수는, 이 튜토리얼의 선두에서 선언한 3 개의 글로벌 함수, 즉 파일 핸들,WAVEFORMATEX 구조체에의 포인터, 친체크 (파일 전체에 관한 정보)의 MMCKINFO 구조체를 초기화한다.

다음에 파일 핸들과 체크 정보는 WaveStartDataRead 함수에게 건네져 이 함수는 mmckinfoData 내의 데이타체크에 관한 정보를 돌려준다. 전데이터 바이트를 보관 유지하는데 정확히의 크기의 스태틱 버퍼를 생성 하고 싶은 경우는, 이 구조체가 중요하게 된다. 그러나 이 튜토리얼에서는 스트림 버퍼를 생성 하므로, 데이타체크의 사이즈를 파악할 필요는 없다.

다음 방향 : 스텝 3 : 세컨드리 사운드 버퍼의 생성


스텝 3 : 세컨드리 사운드 버퍼의 생성

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 튜토리얼」을 참조할것.

[C++]

여기에서는 계속해 SetupStreamBuffer 함수의 내부를 조사한다. 이번은 웨이브 파일과 같은 포맷으로 세컨드리 사운드 버퍼를 생성 한다. 이 프로세스는, 프라이머리 버퍼를 생성 한 스텝 1 을 닮아 있다. 최초로, 글로벌인 DSBUFFERDESC 구조체로 이 버퍼에 대해 기술해, 다음에 그 기술을 IDirectSound::CreateSoundBuffer 메소드에 건네준다.

    memset(&dsbdesc, 0, sizeof(DSBUFFERDESC));
    dsbdesc.dwSize = sizeof(DSBUFFERDESC);
    dsbdesc.dwFlags =
            DSBCAPS_GETCURRENTPOSITION2   // 이것을 실시하는 것은 항상 좋은 생각이다.
            | DSBCAPS_GLOBALFOCUS         // 백그라운드 재생을 가능하게 한다.
            | DSBCAPS_CTRLPOSITIONNOTIFY; // 통지에 필요하다.

    // 버퍼의 사이즈는 임의이지만, 재생 위치의 충분히
    // 앞으로 데이터를 기입할 수 있도록(듯이), 적어도 2 초의 길이에
    // 해야 한다.

    dsbdesc.dwBufferBytes = pwfx->nAvgBytesPerSec * 2;
    dsbdesc.lpwfxFormat = pwfx;

    if FAILED(IDirectSound_CreateSoundBuffer(
            lpds, &dsbdesc, &lpdsb, NULL))
    {
        WaveCloseReadFile(&hmmio, &pwfx);
        return FALSE;
    }

다음 방향 : 스텝 4 : 재생의 통지의 설정


스텝 4 : 재생의 통지의 설정

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 튜토리얼」을 참조할것.

[C++]

여기까지로 스트림 버퍼의 생성에 성공했으므로, 다음은 현재 플레이 포지션이 버퍼내의 특정의 위치에 이르렀을 때에 통지를 받아 다른 데이터를 스트림 하는 시기를 파악할 수 있도록(듯이) 한다. 이 예에서는, 이러한 위치를 버퍼의 선두와 중간으로 설정한다.

최초로, 필요한 수의 이벤트를 생성 해, 그러한 핸들을 rghEvent 배열에 보존한다.

    for (int i = 0; i < NUMEVENTS; i++)
    {
        rghEvent[i] = CreateEvent(NULL, FALSE, FALSE, NULL);
        if (NULL == rghEvent[i]) return FALSE;
    }

다음에,DSBPOSITIONNOTIFY 구조체의 배열을 생성 한다. 각 구조체는, 버퍼내의 위치를 이벤트 핸들에 관련짓는다.

    rgdsbpn[0]. dwOffset = 0;
    rgdsbpn[0]. hEventNotify = rghEvent[0];
    rgdsbpn[1]. dwOffset = (dsbdesc.dwBufferBytes/2);
    rgdsbpn[1]. hEventNotify = rghEvent[1];

한층 더 세컨드리 버퍼로부터 IDirectSoundNotify 인터페이스를 취득해,DSBPOSITIONNOTIFY 배열을 SetNotificationPositions 메소드에 건네준다.

    if FAILED(IDirectSoundBuffer_QueryInterface(lpdsb,
            IID_IDirectSoundNotify, (VOID **) &lpdsNotify))
        return FALSE;

    if FAILED(IDirectSoundNotify_SetNotificationPositions(
             lpdsNotify, NUMEVENTS, rgdsbpn))
    {
        IDirectSoundNotify_Release(lpdsNotify);
        return FALSE;
    }

이것으로, 스트림 버퍼의 설정이 완료한다. 이미 웨이브 파일을 열어, 데이터의 스트리밍을 시작 할 준비가 되어 있으므로, 여기서 버퍼의 설정을 차례차례 실시할 수 있다. 사운드 전체의 재생이 끝날 때까지 동작을 계속하고 싶기 때문에, DSBPLAY_LOOPING 플래그를 세트 한다.

    IDirectSoundBuffer_Play(lpdsb, 0, 0, DSBPLAY_LOOPING);

    return TRUE;
} // SetupStreamBuffer()의 마지막.

다음 방향 : 스텝 5 : 재생의 통지의 처리


스텝 5 : 재생의 통지의 처리

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 튜토리얼」을 참조할것.

[C++]

통지는,WinMain 함수의 메시지 루프내에서, 시그널 송신된 이벤트로서 수신된다. 다음의 부분적인 코드는, 루프로 어떻게 해 시그널 송신된 이벤트와 표준적인 메세지를 수중에 넣는지를 나타낸다.

BOOL Done = FALSE;
while (! Done)
{
    DWORD dwEvt = MsgWaitForMultipleObjects(
            NUMEVENTS,      // 생각되는 이벤트수.
            rghEvent,       // 핸들의 위치.
            FALSE,          // 모든 것을 기다릴까.
            INFINITE,       // 대기 시간의 길이.
            QS_ALLINPUT);   // 모든 메세지는 이벤트이다.

    // WAIT_OBJECT_0 == 0 이외에서는 최초의 이벤트에 할당할 수 있었다
    // 임의의 인덱스값으로서 적절히 다루어지므로, dwEvt 로부터
    // 이 값을 당겨, 0 으로부터 시작되는 이벤트의 인덱스를 취득한다.

    dwEvt -= WAIT_OBJECT_0;

    // 버퍼가 이벤트를 설정해 있었을 경우, 이 프로세스에의
    // 입력이 발생한다.

    if (dwEvt < NUMEVENTS)
    {
        StreamToBuffer(dwEvt); // 데이터를 출력 스트림에 카피한다.
    }

    // 이것이 마지막 이벤트인 경우, 그 이벤트는 메세지이다.

    else if (dwEvt == NUMEVENTS)
    {
        while (PeekMessage(&msg, NULL, 0, 0, PM_REMOVE))
        {
            if (msg.message == WM_QUIT)
            {
                Done = TRUE;
            }
            else
            {
                TranslateMessage(&msg);
                DispatchMessage(&msg);
            }
        }
    }  // 메세지 처리의 종료.
} // while (! Done)

다음 방향 : 스텝 6 : 웨이브 파일로부터의 데이터의 스트리밍


스텝 6 : 웨이브 파일로부터의 데이터의 스트리밍

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 튜토리얼」을 참조할것.

[C++]

전의 2 개의 스텝에서 통지의 설정과 처리를 실시한 것은, 버퍼내의 데이터의 반이 재생되었을 때에 경계체제를 보내는 것을 목적으로 하고 있다. 현재 플레이 포지션이 버퍼의 선두 또는 중간을 지나자 마자, 재생을 끝낸지 얼마 안된 버퍼 세그먼트(segment)에 데이터를 기입한다. (버퍼가 시작 된 직후에 통지를 받아, 버퍼의 후반에 쓰기를 실시한다. ) 이 버퍼는 2 초 분의 데이터를 보관 유지하므로, 현재 플레이 포지션보다 거의 1 초 먼저 데이터를 기입하게 되지만, 이것은 재생 위치가 새로운 데이터에 이르기 전에 처리를 완료하는데 충분한 시간이다.

WinMain 함수에서는, 이벤트의 시그널이 송신되었을 때에, 이 이벤트의 인덱스를 StreamToBuffer 함수에 건네준다. 이 인덱스는,DSBPOSITIONNOTIFY 배열내에서 통지가 차지하는 위치의 인덱스에 대응한다.

여기에, StreamToBuffer 함수의 선두 부분을 나타낸다.

BOOL StreamToBuffer(DWORD dwPos)
{
    LONG            lNumToWrite;
    DWORD           dwStartOfs;
    VOID            *lpvPtr1, *lpvPtr2;
    DWORD           dwBytes1, dwBytes2;
    UINT            cbBytesRead;
    static DWORD    dwStopNextTime = 0xFFFF;

    if (dwStopNextTime == dwPos)   // 모든 데이터가 재생되었다.
    {
        lpdsb->Stop();
        dwStopNextTime = 0xFFFF;
        return TRUE;
    }

    if (dwStopNextTime ! = 0xFFFF)  // 스트림해야할 것은 없지만,
                                 // 데이터의 끝까지 연주를 계속한다.
        return TRUE;

dwStopNextTime 변수는, 파일의 마지막에 달한 것을 나타내는 플래그이다. 함수의 나머지의 부분에서 이 변수를 세트 한다. 이 값이 0 이 아닌 경우, 스트림 해야 할 데이터는 이제 존재하지 않는다. dwStopNextTime 의 값이 처리중의 통지의 인덱스에 동일한 경우, 파일의 마지막에 이르렀을 때에 상당하는 장소에, 현재 플레이 포지션이 돌아온 것, 즉 버퍼에 카피한 데이터의 마지막 세그먼트(segment)가 이미 재생된 것을 알 수 있다. 이 경우는 버퍼를 정지해야 하고, 낡은 데이터의 재생을 계속하지 않는다.

StreamToBuffer 함수가 계속되는 부분에서는, 버퍼내에서, 새로운 데이터의 카피를 시작 하는 장소의 오프셋(offset)를 결정한다. 이 튜토리얼의 버퍼에는 통지 위치가 2 개 밖에 없지만, 이 코드는 임의의 통지수로 동작하도록(듯이) 설계되고 있다. dwPos 가, 현재 플레이 포지션에 의해 건네받은지 얼마 안된 통지 위치의 인덱스인 점에 주의 해야 한다. 직전의 통지 위치로부터 시작되는 버퍼 세그먼트(segment)에 쓰기를 실시하게 된다.

    if (dwPos == 0)
        dwStartOfs = rgdsbpn[NUMEVENTS - 1]. dwOffset;
    else
        dwStartOfs = rgdsbpn[dwPos-1]. dwOffset;

여기서, 버퍼 세그먼트(segment)의 사이즈를 결정한다.

    lNumToWrite = (LONG) rgdsbpn[dwPos]. dwOffset - dwStartOfs;
    if (lNumToWrite < 0) lNumToWrite += dsbdesc.dwBufferBytes;

여기까지로, 데이터 쓰기를 실시하기 위해서(때문에) 버퍼를 잠그는데 필요한 모든 정보를 입수했다.

    IDirectSoundBuffer_Lock(lpdsb,
                     dwStartOfs,       // 락 시작 위치의 오프셋(offset).
                     lNumToWrite,      // 락 되는 바이트수.
                     &lpvPtr1,         // 락 시작 주소.
                     &dwBytes1,        // 락 되는 바이트 카운트.
                     &lpvPtr2,         // rack-around 주소.
                     &dwBytes2,        // rack-around 바이트 카운트.
                     0);               // 플래그.

이 예에서는, 락은 결코 rack-around 하지 않는 (락 된 부분이 버퍼의 선두에 돌아와, 버퍼의 최후와 선두의 2 개에 걸칠 것은 없다) 것으로, 파일로부터 1 회의 데이터 카피를 실시하는 것만으로 충분하다. Wavread.cpp 내의 WaveReadFile 함수를 호출해, 데이터를 취득한다.

    WaveReadFile(hmmio,                // 파일 핸들.
                 dwBytes1,             // 취득되는 바이트수.
                 (BYTE *) lpvPtr1,     // 쓰기처.
                 &mmckinfoData,        // 파이르체크 정보.
                 &cbBytesRead);        // 실제로 읽어들이는 바이트.

이번은, 파일의 마지막에 달했는지 어떠했는지를 판단한다. 달했을 경우는, 파일을 닫아 이 세그먼트(segment)의 나머지의 부분에 무음의 데이터를 쓰기 (세그먼트(segment) 전체를 재생한 다음에 버퍼를 정지하는 사양이 되고 있기 (위해)때문에),dwStopNextTime 플래그를 세트 한다.

    if (cbBytesRead < dwBytes1)        // 파일의 마지막에 달했다.
    {
        WaveCloseReadFile(&hmmio, &pwfx);
        FillMemory((PBYTE) lpvPtr1 + cbBytesRead,
                dwBytes1 - cbBytesRead,
                (dsbdesc.lpwfxFormat->wBitsPerSample==8) ?  128 : 0);
        dwStopNextTime = dwPos;
    }

마지막에 버퍼를 언락 해, 메시지 루프에 돌아온다.

    IDirectSoundBuffer_Unlock(lpdsb,
            lpvPtr1, dwBytes1, lpvPtr2, dwBytes2);

    return TRUE;
} // StreamToBuffer()의 마지막.

다음 방향 : 스텝 7 : DirectSound 의 슛다운


스텝 7 : DirectSound 의 슛다운

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 튜토리얼」을 참조할것.

[C++]

어플리케이션을 종료하기 전에, 열려 있는 모든 웨이브 파일을 닫아 DirectSoundNotify 오브젝트와 DirectSound 오브젝트를 릴리즈 할 필요가 있다. DirectSoundBuffer 오브젝트로부터 IDirectSoundNotify 인터페이스를 문의했기 때문에, DirectSound 를 릴리즈 하기 전에 DirectSoundNotify 오브젝트를 릴리즈 해야 한다. DirectSound 를 릴리즈 하면, 기존의 버퍼도 자동적으로 릴리즈 된다.

다음의 함수는, 필요한 모든 클린 업을 실시한다.

void DSExit(void)
{
    Close();
    if (lpdsNotify)
        lpdsNotify->Release();
    if (lpds)
        lpds->Release();
}


튜토리얼 2 : 사운드의 캡춰

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 튜토리얼」을 참조할것.

[C++]

이 튜토리얼은, (보통은 마이크 입력으로부터) 사운드를 캡춰 해, 웨이브 파일에 기입하는 DirectSoundCapture 를 이행 하는 방법을 나타낸다.

웨이브 파일을 생성 해, 쓰기, 닫는 함수는, DirectX SDK 내의 CaptureSound 샘플 어플리케이션에 부속의 모듈, Wavwrite.cpp 파일내에 기술되고 있다. 이 튜토리얼로 가리키는 방법을 이행 하려면 , Wavwrite.cpp 와 Wavwrite.h 를 프로젝트에 추가해, Winmm.lib 에 링크해야 한다. 그 밖에, 같은 샘플 디렉토리의 Debug.c 와 Debug.h 를 추가하는지, 표준적인 assert 함수를 호출하도록, Wavwrite.cpp 파일내의 ASSERT 매크로의 호출을 변경해야 한다.

이 튜토리얼내의 메소드 호출은, C 와 C++ 의 어디라도 유효한, Dsound.h 내의 매크로를 통해 가고 있다.

이 튜토리얼은, 이하의 스텝으로 구성되어 있다.

  • 스텝 1 : DirectSoundCapture 의 설정
  • 스텝 2 : 캡춰 포맷의 설정
  • 스텝 3 : 캡춰 버퍼의 생성
  • 스텝 4 : 캡춰의 통지의 설정
  • 스텝 5 : 웨이브 파일의 생성
  • 스텝 6 : 캡춰의 통지의 처리
  • 스텝 7 : 웨이브 파일에의 데이터의 스트리밍
  • 스텝 8 : 캡춰의 정지
  • 스텝 9 : DirectSoundCapture 의 슛다운


스텝 1 : DirectSoundCapture 의 설정

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 튜토리얼」을 참조할것.

[C++]

이 튜토리얼에서는, 이하의 정의와 글로벌 선언을 필요로 한다.

#define NUMCAPTUREEVENTS 2

LPDIRECTSOUNDCAPTURE        lpdsc;
LPDIRECTSOUNDCAPTUREBUFFER  lpdscb;
LPDIRECTSOUNDNOTIFY         lpdsNotify;
DSCBUFFERDESC               dscbDesc;
HANDLE                      rghEvent[NUMCAPTUREEVENTS];
DSBPOSITIONNOTIFY           rgdscbpn[NUMCAPTUREEVENTS];
WAVEFORMATEX                wfx =
                       {WAVE_FORMAT_PCM, 1, 22050, 44100, 2, 16, 0};
HMMIO                       hmmio;
MMCKINFO                    mmckinfoData, mmckinfoParent;
MMIOINFO                    mmioinfo;
DWORD                       dwTotalBytesWritten;

DirectSoundCapture 를 사용하기 위해서(때문에), DirectSound 오브젝트를 생성 할 필요는 없다. 그러나, 어플리케이션이 사운드의 녹음에 가세해 재생을 실시하는 경우는, 최초로 DirectSound 를 생성 해야 한다.

이 튜토리얼에서는, 캡춰 시스템의 모든 초기화는, 파라미터를 취하지 않는 함수 InitDSoundCapture 중(안)에서 실시된다. 최초의 스텝은, DirectSoundCapture 오브젝트를 생성 하는 것이다. DirectSoundCaptureCreate 함수의 최초의 파라미터로서 NULL 를 건네주는 것으로, 이 오브젝트에 디폴트의 캡춰 디바이스를 관련짓는다.

BOOL InitDSoundCapture(void)
{

    if FAILED(DirectSoundCaptureCreate(NULL, &lpdsc, NULL))
        return FALSE;

다음 방향 : 스텝 2 : 캡춰 포맷의 설정


스텝 2 : 캡춰 포맷의 설정

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 튜토리얼」을 참조할것.

[C++]

DirectSoundCapture 를 생성 한 다음에, 유저의 디바이스가 지원 하고 있는 웨이브 포맷을 선택해야 한다. 이것을 실시하는 1 개의 방법은, 가장 위에의 포맷화등 시작해, 생성 메소드가 성공할 때까지, 각 포맷의 캡춰 버퍼를 순서에 생성 하는 것이다. (다양한 포맷을 순서에 생성 하는 방법의 예는, 샘플 프로그램 Fdfilter 내의 Fdaudio.cpp 를 참조할것. ) 이 튜토리얼에서는 단순하게, 디바이스의 능력을 체크해, 디폴트의 16 비트 포맷 (WAVEFORMATEX 구조체의 선언에 의해 정의되고 있다)이 지원 되고 있는지 어떤지를 체크한다. 지원되어 있지 않은 경우, 모든 디바이스가 지원 하고 있는 8 비트 포맷을 선택한다.

다음의 코드는, InitDSoundCapture 함수로부터 발췌한 것이다.

    DSCCAPS dsccaps;

    dsccaps.dwSize = sizeof(DSCCAPS);
    if FAILED(IDirectSoundCapture_GetCaps(lpdsc, &dsccaps))
        return FALSE;

    if ((dsccaps.dwFormats & WAVE_FORMAT_2M16) == 0)
    {
        wfx.nSamplesPerSec = 11025;
        wfx.nAvgBytesPerSec = 11025;
        wfx.nBlockAlign = 1;
        wfx.wBitsPerSample = 8;
    }

어플리케이션으로 DirectSound 의 재생도 이용하고 있는 경우는, 프라이머리 버퍼의 포맷과 호환성이 있는 캡춰 포맷을 선택해야 한다. 상세한 것에 대하여는, 다음의 「스텝 3 : 캡춰 버퍼의 생성」을 참조할것.


스텝 3 : 캡춰 버퍼의 생성

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 튜토리얼」을 참조할것.

[C++]

유저의 디바이스에 있어 WAVEFORMATEX 구조체가 유효한 것을 확인한 후, 앞에 진행되어 그 포맷으로 캡춰 버퍼를 생성 할 수 있다.

    dscbDesc.dwSize = sizeof(DSCBUFFERDESC);
    dscbDesc.dwFlags = 0;
    // 버퍼는 1 초 분의 오디오를 보관 유지한다.
    dscbDesc.dwBufferBytes = wfx.nAvgBytesPerSec;
    dscbDesc.dwReserved = 0;
    dscbDesc.lpwfxFormat = &wfx;

    if FAILED(IDirectSoundCapture_CreateCaptureBuffer(lpdsc,
            &dscbDesc, &lpdscb, NULL))
        return FALSE;

이것으로 버퍼 오브젝트에의 포인터를 lpdscb 에 취득할 수 있었다.

다음 방향 : 스텝 4 : 캡춰의 통지의 설정


스텝 4 : 캡춰의 통지의 설정

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 튜토리얼」을 참조할것.

[C++]

InitDSoundCapture 함수의 마지막 초기화 스텝으로서 캡춰 버퍼내의 통지 위치를 설정해, 어플리케이션이 다른 데이터를 파일에 스트림 하는 시기를 파악할 수 있도록(듯이) 한다. 이 예에서는, 이러한 위치를 버퍼의 선두와 중간으로 설정한다.

최초로, 필요한 수의 이벤트를 생성 해, 그러한 핸들을 rghEvent 배열에 보존한다.

    for (int i = 0; i < NUMCAPTUREEVENTS; i++)
    {
        rghEvent[i] = CreateEvent(NULL, FALSE, FALSE, NULL);
        if (NULL == rghEvent[i]) return FALSE;
    }

다음에,DSBPOSITIONNOTIFY 구조체의 배열을 생성 한다. 각 구조체는, 버퍼내의 위치를 이벤트 핸들에 관련짓는다.

    rgdscbpn[0]. dwOffset = 0;
    rgdscbpn[0]. hEventNotify = rghEvent[0];
    rgdscbpn[1]. dwOffset = dscbDesc.dwBufferBytes/2;
    rgdscbpn[1]. hEventNotify = rghEvent[1];

마지막에 캡춰 버퍼로부터 IDirectSoundNotify 인터페이스를 취득해,DSBPOSITIONNOTIFY 배열을 SetNotificationPositions 메소드에 건네준다.

    if FAILED(IDirectSoundCaptureBuffer_QueryInterface(lpdscb,
            IID_IDirectSoundNotify, (VOID **) &lpdsNotify))
        return FALSE;

    if FAILED(IDirectSoundNotify_SetNotificationPositions(lpdsNotify,
            NUMCAPTUREEVENTS, rgdscbpn))
    {
        IDirectSoundNotify_Release(lpdsNotify);
        return FALSE;
    }

    return TRUE;
}  // InitDSoundCapture()의 마지막.

캡춰 버퍼와 세컨드리 (출력) 버퍼의 양쪽 모두에 통지를 설정할 필요가 있는 경우, 이벤트 핸들을 같은 rghEvent 배열에 보존해야 한다. 메시지 루프내에서 통지를 받았을 때에, 인덱스 번호에 의해 그것들 2 종류의 이벤트를 구별할 수 있다.

다음 방향 : 스텝 5 : 웨이브 파일의 생성


스텝 5 : 웨이브 파일의 생성

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 튜토리얼」을 참조할것.

[C++]

이 시점에서, 이미 유효한 파일명을 취득해, 웨이브 파일에의 사운드 데이터의 보존을 시작 할 준비가 되어 있는 것을 상정한다. 이 프로세스는, 다음의 함수내에서 실시된다.

BOOL StartWrite(TCHAR *pszFileName)
{
    if (WaveOpenFile(pszFileName, &hmmio, &wfx,
            &mmckinfoData, &mmckinfoParent))
      return FALSE;

    if (WaveStartDataWrite(&hmmio, &mmckinfoData, &mmioinfo))
    {
        WaveCloseWriteFile(&hmmio, &mmckinfoData,
                &mmckinfoParent, &mmioinfo,
                dwTotalBytesWritten / (wfx.wBitsPerSample / 8));
        DeleteFile(pszFileName);
        return FALSE;
    }
    if FAILED(IDirectSoundCaptureBuffer_Start(lpdscb,
            DSCBSTART_LOOPING))
    {
        WaveCloseWriteFile(&hmmio, &mmckinfoData,
                &mmckinfoParent, &mmioinfo, 0);
        DeleteFile(pszFileName);
        return FALSE;
    }

    dwTotalBytesWritten = 0;

    return TRUE;
}

이 함수는 최초로 Wavwrite.cpp 내의 WaveOpenFile 함수를 호출해, RIFF 파일의 생성과 웨이브 포맷에 관련하는 헤더를 기입한다. 다음에 WaveStartDataWrite 함수를 호출해, 파일 포인터를 데이타체크에 진행한다. 마지막으로, 버퍼의 캡춰를 시작 한다. 버퍼의 반에 상당하는 1 초가 경과한 시점에서, 어플리케이션은 데이터가 이용 가능하다라는 통지를 받으므로, 그 시점까지 데이터를 파일에 카피할 준비를 해 두지 않으면 안 된다.

dwTotalBytesWritten 의 초기화에도 주의 해야 한다. 캡춰를 끝낸 다음에, 데이타체크의 헤더는 이 값을 필요로 한다.

다음 방향 : 스텝 6 : 캡춰의 통지의 처리


스텝 6 : 캡춰의 통지의 처리

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 튜토리얼」을 참조할것.

[C++]

재생의 통지와 같이, 메시지 루프내에서, 이벤트로서 캡춰의 통지를 받는다. 여기에 샘플 루프를 나타낸다.

BOOL Done = FALSE;
while (! Done)
{
    DWORD dwEvt = MsgWaitForMultipleObjects(
            NUMCAPTUREEVENTS,  // 생각되는 이벤트수.
            rghEvent,          // 핸들의 위치.
            FALSE,             // 모든 것을 기다릴까.
            INFINITE,          // 대기 시간의 길이.
            QS_ALLINPUT);      // 모든 메세지는 이벤트이다.

    dwEvt -= WAIT_OBJECT_0;

    // 버퍼가 이벤트를 설정해 있었을 경우, 이 프로세스에의
    // 입력이 발생한다.

    if (dwEvt < NUMCAPTUREEVENTS)
    {
        StreamToFile();
    }

    // 이것이 마지막 이벤트인 경우, 그 이벤트는 메세지이다.

    else if (dwEvt == NUMCAPTUREEVENTS)
    {
        while (PeekMessage(&msg, NULL, 0, 0, PM_REMOVE))
        {
            if (msg.message == WM_QUIT)
            {
                Done = TRUE;
            }
            else
            {
                TranslateMessage(&msg);
                DispatchMessage(&msg);
            }
        }
    }  // 메세지 처리의 종료.
} // while (! Done)

전술대로, 캡춰 버퍼와 세컨드리 (출력) 버퍼의 양쪽 모두로부터 통지를 받았을 경우,dwEvt 내의 인덱스 번호를 사용해 이것들 2 종류의 이벤트를 식별해야 한다. 예를 들어, 이벤트 0 으로 1 은 재생의 통지, 이벤트 2 로 3 은 캡춰의 통지라고 하는 것을 생각된다.

다음 방향 : 스텝 7 : 웨이브 파일에의 데이터의 스트리밍


스텝 7 : 웨이브 파일에의 데이터의 스트리밍

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 튜토리얼」을 참조할것.

[C++]

최초의 튜토리얼에서는, 통지 위치의 오프셋(offset)를 체크하는 것으로써, 안전하게 쓰기를 실시할 수 있는 버퍼 세그먼트(segment)를 식별하는 방법을 배웠다. 이 방법은, 이 튜토리얼의 캡춰 버퍼에도와 같이 적용할 수 있지만, 여기에서는 다소 다른 작업을 실시할 필요가 있다.

전의 스텝에서는, 통지 이벤트에 응답해 StreamToFile 함수를 호출하는 방법을 배웠다. 최초의 튜토리얼의 StreamToBuffer 함수와는 달라, 이 함수는 파라미터로서 이벤트 인덱스를 취하지 않는다.

BOOL StreamToFile(void)
{
    DWORD               dwReadPos;
    DWORD               dwNumBytes;
    LPBYTE              pbInput1, pbInput2;
    DWORD               cbInput1, cbInput2;
    static DWORD        dwMyReadCursor = 0;
    UINT                dwBytesWritten;

dwMyReadCursor 가 스태틱으로서 선언되고 있는 점에 주의 해야 한다. 이것은, 읽어들이고 싶은 다음의 데이터 바이트의 오프셋(offset)이다. 바꾸어 말하면(자), 직전에 읽어들여 이 함수를 통해 건네준 바이트의 바로 후의 바이트이다.

이 함수는 최초로, 현재의 read 위치를 검색한다. 이 정도치가, 읽어들여도 안전한 데이터의 최초의 위치를 나타내고 있는 점에 주의 해야 한다. 이것은 통지 위치에 일치 하면은 한정되지 않는다. 이벤트가 시그널 송신된 후, 아마 현재의 read 위치는 앞에 진행되고 있기 때문이다.

    IDirectSoundCaptureBuffer_GetCurrentPosition(lpdscb,
            NULL, &dwReadPos);

다음에 이 함수는, (rack-around에 대처한 후 ) 현재의 read 위치로부터 어플리케이션 내부의 read 커서를 당겨, 새로운 데이터가 몇 바이트 이용할 수 있을까를 결정한다.

    if (dwReadPos < dwMyReadCursor)
            dwReadPos += dscbDesc.dwBufferBytes;
    dwNumBytes = dwReadPos - dwMyReadCursor;

다음에 버퍼를 잠그어, 카피를 실시한다. 이용 가능한 것으로 해 식별한 데이터 세그먼트는, 버퍼의 선두와 중간에 있는 통지 위치와 반드시 일치하고 있는 것은 아니기 때문에, 버퍼의 락 위치는 rack-around 하고 있을 (락 된 부분이 버퍼의 선두에 돌아와, 버퍼의 최후와 선두의 2 개에 걸칠) 가능성이 있다. 이 경우, 카피 작업을 2 회 실시할 필요가 있다.

    if FAILED(IDirectSoundCaptureBuffer_Lock(lpdscb,
            dwMyReadCursor, dwNumBytes,
            (LPVOID *) &pbInput1, &cbInput1,
            (LPVOID *) &pbInput2, &cbInput2, 0))
        OutputDebugString("Capture lock failure");

    else
        {
        if (WaveWriteFile(hmmio, cbInput1, pbInput1, &mmckinfoData,
                        &dwBytesWritten, &mmioinfo))
          OutputDebugString("파일에의 데이터의 쓰기에 실패했습니다. \n");
        dwTotalBytesWritten += dwBytesWritten;

        // rack-around.
        if (pbInput2 ! = NULL)
        {
            if (WaveWriteFile(hmmio, cbInput2, pbInput2,
                    &mmckinfoData, &dwBytesWritten, &mmioinfo))
              OutputDebugString("파일에의 데이터의 쓰기에 실패했습니다. \n");
            dwTotalBytesWritten += dwBytesWritten;
        }

        IDirectSoundCaptureBuffer_Unlock(lpdscb,
                pbInput1, cbInput1,
                pbInput2, cbInput2);
    }

WaveWriteFile 함수는, 성공했을 경우는 0 을 돌려주어, 실제로 파일에 카피한 바이트수를 dwBytesWritten 에 기입한다. 이 값을 누적 합계에 추가한다. 누적 합계는, 파일을 닫을 때 필요하게 된다.

마지막으로, 내부의 read 커서를 갱신해, rack-around를 보정해, 메시지 루프에 돌아온다.

    dwMyReadCursor += dwNumBytes;
    if (dwMyReadCursor >= dscbDesc.dwBufferBytes)
                dwMyReadCursor -= dscbDesc.dwBufferBytes;

    return TRUE;
} // StreamToFile()의 마지막.

다음 방향 : 스텝 8 : 캡춰의 정지


스텝 8 : 캡춰의 정지

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 튜토리얼」을 참조할것.

[C++]

여기서 녹음을 정지한다. 다음의 함수를 호출한다.

BOOL StopWrite()
{
    IDirectSoundCaptureBuffer_Stop(lpdscb);
    StreamToFile();
    WaveCloseWriteFile(&hmmio, &mmckinfoData,
            &mmckinfoParent, &mmioinfo,
            dwTotalBytesWritten / (wfx.wBitsPerSample / 8));
    return TRUE;
}

이 함수는 버퍼의 캡춰를 정지해, StreamToFile 함수를 한번 더 호출해, 현재의 read 위치까지의 모든 데이터를 보존해, 파일을 닫는다. Wavwrite.cpp 내의 WaveCloseWriteFile 함수는, 샘플의 합계수를 기입하는 것으로, 데이타체크의 헤더도 갱신한다.

다음 방향 : 스텝 9 : DirectSoundCapture 의 슛다운


스텝 9 : DirectSoundCapture 의 슛다운

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 튜토리얼」을 참조할것.

[C++]

어플리케이션을 종료하기 전에, 캡춰 시스템을 슛다운 해야 한다. 이것은 단순하게, 모든 오브젝트를 릴리즈 하는 것을 의미한다. 캡춰 버퍼를 릴리즈 하기 전에,IDirectSoundNotify 인터페이스를 릴리즈 해야 한다.

void CleanupDSoundCapture(void)
{
    if (lpdsNotify)
        IDirectSoundNotify_Release(lpdsNotify);
    if (lpdscb)
        IDirectSoundCaptureBuffer_Release(lpdscb);
    if (lpdsc)
        IDirectSoundCapture_Release(lpdsc);
}


DirectSound Visual Basic 튜토리얼

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectSound C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

여기에서는, 다음의 튜토리얼을 사용해, DirectSound 의 기본적인 기능을 이행 하는 방법을 단계적으로 설명한다. 이 튜토리얼은, DirectX SDK Installation의 \samples\Multimedia\VBSamples\DSound\src\Tutorial1 와 \samples\Multimedia\VBSamples\DSound\src\Tutorial2 의 각 폴더에 있는 샘플을 기본으로 하고 있다.

  • 튜토리얼 1 : 사운드의 로드와 재생
  • 튜토리얼 2 : 3D 사운드의 로드와 재생


튜토리얼 1 : 사운드의 로드와 재생

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectSound C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

이 튜토리얼은, DirectSound 의 가장 기본적인 기능의 1 개인 사운드의 로드와 재생에 대해 설명한다. 이것은, 웨이브 파일을 버퍼에 로드해, 버퍼 데이터를 재생하는 것으로 행해진다. 코드는, DirectX SDK Installation의 \samples\Multimedia\VBSamples\DSound\src\Tutorial1 폴더의 샘플 어플리케이션을 기본으로 하고 있다.

이 튜토리얼은 이하의 스텝으로 분류된다.

  • 스텝 1 : DirectSound 오브젝트의 생성
  • 스텝 2 : 웨이브 파일의 버퍼에의 로드
  • 스텝 3 : 사운드의 재생


스텝 1 : DirectSound 오브젝트의 생성

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectSound C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

DirectSound 어플리케이션의 주된 오브젝트는,DirectSound 클래스의 인스턴스이다. 어플리케이션은,DirectSound 오브젝트의 메소드를 사용해 사운드 환경을 설정해, 오디오 데이터를 보관 유지하는 버퍼를 생성 한다.

이 오브젝트는, 모든 DirectX for Visual Basic 어플리케이션의 핵인 글로벌인 DirectX7 오브젝트를 생성 한 후에,DirectX7.DirectSoundCreate 메소드를 호출하는 것으로 취득된다.

이하의 글로벌 선언은,DirectX7 오브젝트, 및 DirectSound 오브젝트와 2 개의 버퍼에 대한 변수를 생성 한다.

Dim m_dx As New DirectX7
Dim m_ds As DirectSound
Dim m_dsBuffer(2) As DirectSoundBuffer

스타트 업 코드에서는, 다음과 같이 DirectSound 오브젝트를 생성 한다.

On Local Error Resume Next

Set m_ds = m_dx.DirectSoundCreate("")

If Err.Number <> 0 Then
    MsgBox "DirectSound 를 시작 할 수가 없습니다. 사운드 카드가 적절히" & _
           "인스톨 되고 있는지 어떤지 확인해 주세요. "
    End
End If

하늘의 캐릭터 라인을 DirectSoundCreate 메소드에 건네주는 것으로, 시스템에 디폴트의 사운드 디바이스를 배치하는 것을 나타낸다.

여기서, 사운드 디바이스에 협조 레벨을 설정해야 한다. 튜토리얼 1 의 샘플에서는, 다음의 스테이트먼트로 설정해 있다.

m_ds.SetCooperativeLevel Me.hWnd, DSSCL_PRIORITY

최초의 인수는, 어플리케이션에의 윈도우 핸들이다. 폼의 hWnd 프로퍼티는, 폼이 표시될 때까지 설정되지 않는 것에 주의 해야 한다. 보통, 폼은 폼의 Load 프로시저가 완전하게 실행된 후에 표시된다. 이 샘플에서는, 폼 윈도우에 대한 Show 가 프로시저의 최초로 불려 가기 (위해)때문에,hWnd 가 이용 가능하게 된다.

2 번째의 인수는, 많은 어플리케이션에 최적인 우선 협조 레벨을 설정한다.

다음 방향 : 튜토리얼 1 : 스텝 2 : 웨이브 파일의 버퍼에의 로드

다음 방향 : 튜토리얼 2 : 스텝 2 : 청취자의 취득


스텝 2 : 웨이브 파일의 버퍼에의 로드

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectSound C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

주된 DirectSound 오브젝트를 생성 한 후, 다음의 스텝에서는 세컨드리 사운드 버퍼를 생성 해, 웨이브 파일을 그 버퍼에 로드한다.

DSBUFFERDESC 형에 버퍼의 특성을 기술한다. 최초의 멤버는 버퍼의 사이즈를 설정한다. 다만, 파일로부터 버퍼를 생성 하기 위한(해), 이 멤버를 초기화할 필요는 없다. DirectSound 는, 파일의 데이터에 적절한 사이즈로 버퍼를 생성 한다. 2 번째의 멤버에는, 버퍼에 요구하는 다양한 능력을 기술한다. 다음의 코드예는, 어플리케이션이 주파수, 팬, 볼륨을 변경할 수 있는 버퍼를 기술한다. 한층 더 DDSBCAPS_STATIC 플래그로, 사운드 카드의 메모리가 이용 가능한 경우에 버퍼를 거기에 배치해야 하는 것을 나타낸다. 사운드 카드의 메모리는 보통은 이용 불가이다.

Dim bufferDesc As DSBUFFERDESC
Dim waveFormat As WAVEFORMATEX

bufferDesc.lFlags = DSBCAPS_CTRLFREQUENCY Or DSBCAPS_CTRLPAN _
                    Or DSBCAPS_CTRLVOLUME Or DSBCAPS_STATIC

생성 메소드에 건네주어야 할 다른 변수는,WAVEFORMATEX 형이다. DirectSound 는 파일로부터 필요한 웨이브 포맷 정보를 재차 취득하기 위해(때문에), 이 형태를 초기화할 필요는 없다. 메소드를 호출한 후, 필요에 따라서 이 형태를 체크해, 설정된 포맷을 확인할 수 있다.

버퍼를 생성 하려면 , 다음과 같이 DirectSound.CreateSoundBufferFromFile 메소드를 호출한다.

Set m_dsBuffer(i) = m_ds.CreateSoundBufferFromFile( _
                   sfile, bufferDesc, waveFormat)

다음 방향 : 스텝 3 : 사운드의 재생


스텝 3 : 사운드의 재생

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectSound C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

튜토리얼 1 의 샘플에서는, 유저가 [Play] 버튼을 클릭 하면, 사운드가 사운드 버퍼에 로드 된다. 동시에,Volume 와 Pan 의 각 슬라이더 상태가 Scroll 프로시저의 호출로 체크되어 사운드 버퍼의 프로퍼티가 슬라이더 상태에 응해 조정된다.

Private Sub scrlVol_Scroll(i As Integer)
    If m_dsBuffer(i) Is Nothing Then Exit Sub
    m_dsBuffer(i). SetVolume scrlVol(i). Value
End Sub

Private Sub scrlPan_Scroll(i As Integer)
    If m_dsBuffer(i) Is Nothing Then Exit Sub
    m_dsBuffer(i). SetPan scrlPan(i). Value
End Sub

이러한 프로시저와 거기에 대응하는 Change 프로시저는, 유저가 볼륨과 팬의 슬라이더를 조정 하면나무 항상 불려 간다. 어플리케이션은, 버퍼의 재생중에 볼륨과 팬을 변경할 수 있다.

또, 이 샘플은 [Loop Play] 체크 박스 상태도 체크해, 이것이 온의 경우, 플래그를 1 (DSBPLAY_LOOPING)으로 설정한다.

Dim flag As Long
flag = 0
If chLoop(i). Value <> 0 Then flag = 1

이 플래그는, 다음과 같이 DirectSoundBuffer.Play 메소드에게 건네진다.

m_dsBuffer(i). Play flag

사운드가 루프 하는 경우, 유저는 [Stop] 버튼을 클릭할까 [Loop Play] 체크 박스를 오프로 해 사운드를 정지할 수 있다. 이것에 응답해, 어플리케이션은 버퍼를 정지해, 현재 플레이 포지션을 선두로 다시 설정한다.

m_dsBuffer(i). Stop
m_dsBuffer(i). SetCurrentPosition 0

유저가 [Pause] 버튼을 클릭 하면, 버퍼는 정지하지만, 현재 플레이 포지션은 그 자리에 남는다. 이 때문에,DirectSoundBuffer.Play 가 다음에 불려 갔을 때, 사운드는 같은 장소로 돌아간다.


튜토리얼 2 : 3D 사운드의 로드와 재생

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectSound C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

이 튜토리얼은, 3 차원에 있어서의 사운드의 재생 방법을 나타낸다. 이것은, DirectX SDK Installation의 \samples\Multimedia\VBSamples\DSound\src\Tutorial2 폴더의 샘플 어플리케이션을 기본으로 하고 있다. 유저 인터페이스는, 「튜토리얼 1 : 사운드의 로드와 재생」으로 사용한 샘플과 닮아 있지만, 청취자의 위치와 2 개의 사운드를 표시하는데 사용하는 픽쳐 박스 컨트롤이 붙어 있다.

이 튜토리얼은, 이하의 스텝으로 분류된다. 스텝 1 은, 튜토리얼 1 의 스텝 1 과 같다.

  • 스텝 1 : DirectSound 오브젝트의 생성
  • 스텝 2 : 청취자의 취득
  • 스텝 3 : 웨이브 파일의 3D 버퍼에의 로드
  • 스텝 4 : 3D 사운드의 재생이라고 변경


스텝 2 : 청취자의 취득

스텝 1 으로 채용한 글로벌 변수에 가세해 튜토리얼 2 에서는 다음의 글로벌 변수를 사용한다.

Dim m_ds3dBuffer(2) As DirectSound3DBuffer
Dim m_dsPrimaryBuffer As DirectSoundBuffer
Dim m_dsListener As DirectSound3DListener

DirectSound 오브젝트를 생성 한 후, 3D 사운드 환경을 설정하는 다음의 스텝에서는 DirectSound3DListener 오브젝트를 취득한다. 이 오브젝트는, 이 환경의 가상 청취자의 위치와 방향을 포함한 글로벌 사운드 파라미터의 제어에 사용된다.

청취자는 프라이머리 버퍼로부터 취득되므로, 적절한 DirectSoundBuffer 오브젝트를 생성 해야 한다. 이 버퍼에는 2 개의 플래그를 설정해, 버퍼가 3D 능력이 있는 프라이머리 버퍼로서 생성 되도록(듯이) 한다. WAVEFORMATEX 형은, 프라이머리 버퍼의 디폴트의 웨이브 포맷을 취득한다. 이 형태의 초기화는 필요없다.

Dim primDesc As DSBUFFERDESC
Dim format As WAVEFORMATEX

primDesc.lFlags = DSBCAPS_CTRL3D Or DSBCAPS_PRIMARYBUFFER
Set m_dsPrimaryBuffer = m_ds.CreateSoundBuffer(primDesc, format)

다음에 DirectSoundBuffer.GetDirectSound3DListener 를 호출해, 프라이머리 버퍼로부터 청취자를 취득한다.

Set m_dsListener = m_dsPrimaryBuffer.GetDirectSound3DListener()

튜토리얼 2 의 샘플에서는 DirectSound3DListener 를 사용하지 않는다. 다만 이 오브젝트는, 사운드 버퍼에 대한 상대적인 청취자의 위치와 방향의 변경, 롤 오프 계수와 같은 글로벌 사운드 파라미터의 변경, 및 모든 3D 버퍼의 지연 설정의 위탁에 사용된다.

다음 방향 : 스텝 3 : 웨이브 파일의 3D 버퍼에의 로드


스텝 3 : 웨이브 파일의 3D 버퍼에의 로드

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectSound C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

다음의 스텝에서는, 웨이브 파일을 사운드 버퍼에 로드한다. 세컨드리 버퍼에 대해서는, 튜토리얼 1 으로 설명하고 있다. 「스텝 2 : 웨이브 파일의 버퍼에의 로드」를 참조할것. 이번은, DSBCAPS_CTRLPAN 가 아니고 DSBCAPS_CTRL3D 를 필요로 한다. 3D 버퍼에서는, 2D 이펙트의 팬을 사용하지 않는다.

튜토리얼 2 의 SDK 샘플로부터 채용된 다음의 코드에서는, 파일이 유효한 웨이브 파일의 이름이 된다.

Dim bufferDesc1 As DSBUFFERDESC
Dim waveFormat1 As WAVEFORMATEX

bufferDesc1.lFlags = DSBCAPS_CTRL3D Or DSBCAPS_CTRLFREQUENCY _
    Or DSBCAPS_CTRLVOLUME Or DSBCAPS_STATIC
Set m_dsBuffer(i) = m_ds.CreateSoundBufferFromFile( _
    file, bufferDesc1, waveFormat1)

여기서 DirectSound3DBuffer 오브젝트를 생성 해, 사운드 버퍼의 3D 프로퍼티를 캡슐화한다.

Set m_ds3dBuffer(i) = m_dsBuffer(i). GetDirectSound3DBuffer

다음 방향 : 스텝 4 : 3D 사운드의 재생이라고 변경


스텝 4 : 3D 사운드의 재생이라고 변경

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectSound C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

여기까지로 3D 사운드 버퍼가 2 개의 오브젝트로 나타내졌다. 버퍼의 표준 기능을 갖춘 DirectSoundBuffer 오브젝트와 버퍼의 3D 프로퍼티를 제어하는 DirectSound3DBuffer 오브젝트이다.

이 버퍼를 재생하려면 , 2D 버퍼의 경우와 같이 한다. 튜토리얼 1 의 「스텝 3 : 사운드의 재생」을 참조할것.

버퍼의 3D 프로퍼티의 변경은, 재생중인가 아닌가에 관계없이 언제라도 실시할 수 있다. 이 샘플 어플리케이션에서는, 버퍼를 생성 하면나무나, 유저가 [Direction] 스크롤 바나 버퍼를 나타내는 삼각형을 움직이는데 응답해, 프로퍼티가 설정된다.

버퍼에 대한 사운드 콘의 방향은,[Direction] 스크롤 바의 Change 프로시저로 설정된다.

Private Sub scrlAngle_Change(i As Integer)

  Dim x As Single
  Dim z As Single

  '방향 벡터를 계산한다.
  '단위의 번을 라디안으로 변환해, cos 또는 sin 를 취득한다.

  x = 5 * Cos(3.141 * scrlAngle(0). Value / 180)
  z = 5 * Sin(3.141 * scrlAngle(0). Value / 180)

  '그래픽스를 갱신한다.

  DrawPositions

  If m_dsBuffer(i) Is Nothing Then Exit Sub
  m_ds3dBuffer(i). SetConeOrientation x, 0, z, DS3D_IMMEDIATE

End Sub

이 샘플에서는, 유저가 마우스의 왼쪽 버튼이나 오른쪽 버튼을 클릭하거나 사운드를 나타내는 삼각형을 이동하는 것으로, 청취자에 대한 상대적인 2 개의 사운드의 위치를 이동할 수 있다. 사운드의 위치는,DirectSound3DBuffer.SetPosition 메소드로 변경한다. 샘플의 UpdatePosition 프로시저를 참조할것.


DirectSound 레퍼런스

여기에서는, C/C++ 및 Visual Basic 의 DirectSound 가 제공하는 어플리케이션 프로그래밍 인터페이스 (API) 요소의 레퍼런스 정보를 기술한다. 레퍼런스 정보는 이하의 언어별로 구성된다.

  • DirectSound C/C++ 레퍼런스
  • DirectSound Visual Basic 레퍼런스


DirectSound C/C++ 레퍼런스

여기에서는, DirectSound 가 제공하는 API 요소의 레퍼런스 정보를 기술한다. 레퍼런스 정보는 이하의 카테고리로 분류된다.

  • 인터페이스
  • 함수
  • 콜백 함수
  • 구조체
  • 반환값


인터페이스

여기에서는, 이하의 DirectSound 인터페이스의 메소드에 관한 레퍼런스를 제공한다.

  • IDirectSound
  • IDirectSound3DBuffer
  • IDirectSound3DListener
  • IDirectSoundBuffer
  • IDirectSoundCapture
  • IDirectSoundCaptureBuffer
  • IDirectSoundNotify
  • IKsPropertySet


IDirectSound 인터페이스

어플리케이션은,IDirectSound 인터페이스의 메소드를 사용해, DirectSound 오브젝트의 생성과 환경 설정을 실시한다. 여기에서는, IDirectSound 인터페이스의 메소드의 레퍼런스를 제공한다.

이 인터페이스는,DirectSoundCreate 함수를 사용해 취득한다.

IDirectSound 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

초기화 | Initialize
 | SetCooperativeLevel
버퍼 생성 | CreateSoundBuffer
 | DuplicateSoundBuffer
디바이스의 능력 | GetCaps
메모리 메니지먼트 | Compact
스피커의 구성 | GetSpeakerConfig
 | SetSpeakerConfig

모든 COM 인터페이스와 같이,IDirectSound 인터페이스는 IUuknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUND 형은,IDirectSound 인터페이스에의 포인터로서 정의되고 있다.

typedef struct IDirectSound    *LPDIRECTSOUND;

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSound::Compact

IDirectSound::Compact 메소드는, 온보드 사운드 메모리에 미사용 부분이 존재하는 경우, 이것들을 이동해 연속 블록을 형성해, 빈메모리 영역을 최대로 한다.

HRESULT Compact();

파라미터

없음.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED
DSERR_UNINITIALIZED

주의

어플리케이션의 DirectSound 오브젝트는, 적어도 DSSCL_PRIORITY 의 협조 레벨을 갖추지 않으면 안 된다. IDirectSound::SetCooperativeLevel 를 참조할것.

진행중의 조작이 그 밖에 1 개(살)에서도 존재 하면, 이 메소드는 실패한다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSound::CreateSoundBuffer

IDirectSound::CreateSoundBuffer 메소드는, 샘플링 오디오의 순서를 보관 유지하기 위한 DirectSoundBuffer 오브젝트를 생성 한다.

HRESULT CreateSoundBuffer(
  LPCDSBUFFERDESC lpcDSBufferDesc,
  LPLPDIRECTSOUNDBUFFER lplpDirectSoundBuffer,
  IUnknown FAR * pUnkOuter
);

파라미터

lpcDSBufferDesc
생성 되는 사운드 버퍼의 기술을 보관 유지하는 DSBUFFERDESC 구조체에의 포인터.
lplpDirectSoundBuffer
신규의 DirectSoundBuffer 오브젝트에의 포인터. 버퍼를 생성 할 수 없는 경우는 NULL.
pUnkOuter
전체의 미정도리의 컨트롤. 이 값은 NULL 가 아니면 안된다.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_ALLOCATED
DSERR_CONTROLUNAVAIL
DSERR_BADFORMAT
DSERR_INVALIDPARAM
DSERR_NOAGGREGATION
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

주의

DSBCAPS_CTRLDEFAULT 는, 이것이 나타내는 개별의 플래그를 사용하도록(듯이)와 삭제되었다. DSBCAPS_CTRLDEFAULT 는, DSBCAPS_CTRLPAN | DSBCAPS_CTRLVOLUME | DSBCAPS_CTRLFREQUENCY 로서 정의되었다. 필요한 플래그만을 지정하는 것으로써, 불필요한 리소스를 줄일 수가 있다.

사운드 버퍼를 재생하기 전에, 어플리케이션은 IDirectSound::SetCooperativeLevel 메소드를 사용해 DirectSound 오브젝트의 협조 레벨을 지정해야 한다.

lpDSBufferDesc 파라미터는, 포맷, 사이즈, 능력 등, 희망의 버퍼의 타입 정보를 포함한 구조체를 가리킨다. 어플리케이션은 필요한 능력을 지정해야 한다. 그렇지 않으면, 그러한 능력은 이용할 수 없다. 예를 들어, DirectSound 오브젝트를 생성 할 경우에 DSBCAPS_CTRLFREQUENCY 플래그를 지정해 두지 않으면IDirectSoundBuffer::SetFrequency 의 호출은 모두 실패한다.

DSBCAPS_STATIC 플래그를 지정할 수도 있다. 그 경우, DirectSound 는 온보드 메모리 (사용 가능한 경우)에 버퍼를 저장 해, 하드웨어 믹싱을 이용할 수 있다. 하드웨어 또는 소프트웨어의 믹싱을 버퍼에 사용하게 하려면 , 각각 DSBCAPS_LOCHARDWARE 또는 DSBCAPS_LOCSOFTWARE 플래그를 사용한다. 게다가 DirectSound 는 DSBCAPS_LOCDEFER 플래그를 사용하는 것으로, 재생중에 하드웨어나 소프트웨어의 리소스를 할당한다.

버퍼가 하드웨어나 소프트웨어에 생성 된 것을 파악하려면 ,IDirectSoundBuffer:GetCaps 메소드를 호출해, 돌려주어진 DSBCAPS 구조체의 dwFlags 멤버의 DBSCAPS_LOCHARDWARE 플래그, 또는 DSBCAPS_LOCSOFTWARE 플래그를 체크한다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 :Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

DSBUFFERDESC ,IDirectSound::DuplicateSoundBuffer ,IDirectSound::SetCooperativeLevel ,IDirectSoundBuffer , IDirectSoundBuffer::GetFormat ,IDirectSoundBuffer::GetVolume ,IDirectSoundBuffer::Lock ,IDirectSoundBuffer::Play ,IDirectSoundBuffer::SetFormat ,IDirectSoundBuffer::SetFrequency


IDirectSound::DuplicateSoundBuffer

IDirectSound::DuplicateSoundBuffer 메소드는, 새로운 DirectSoundBuffer 오브젝트를 생성 한다. 이 오브젝트는, 오리지날의 오브젝트와 같은 버퍼 메모리를 사용한다.

HRESULT DuplicateSoundBuffer(
  LPDIRECTSOUNDBUFFER lpDsbOriginal,
  LPLPDIRECTSOUNDBUFFER lplpDsbDuplicate
);

파라미터

lpDsbOriginal
복제되는 DirectSoundBuffer 오브젝트에의 포인터.
lplpDsbDuplicate
새로운 DirectSoundBuffer 오브젝트에의 포인터.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_ALLOCATED
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED

주의

새로운 오브젝트는 오리지날의 오브젝트와 같은 방법으로 사용할 수 있다.

복제 직후의 버퍼는, 오리지날 버퍼와 같은 파라미터를 가진다. 다만, 어플리케이션은 각 버퍼의 파라미터를 개별적으로 변경할 수 있어 각 버퍼는 차이에 영향을 미치는 일 없이 재생과 정지를 실시할 수 있다.

어느 쪽인가의 오브젝트가 버퍼내의 데이터를 변경 하면, 버퍼 메모리가 공유되고 있기 (위해)때문에, 그 변경은 이제(벌써) 한편의 오브젝트에도 반영된다.

후에 남은 참조측 오브젝트가 릴리즈 되면(자), 버퍼 메모리는 릴리즈 된다.

어플리케이션은, 사운드 버퍼의 복제 작업이 항상 성공한다고는 상정할 수 없다. 특히, DirectSound 는 하드웨어 버퍼의 소프트웨어 복제를 생성 할 수 없다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound::CreateSoundBuffer


IDirectSound::GetCaps

IDirectSound::GetCaps 메소드는, DirectSound 오브젝트로서 나타내지고 있는 하드웨어 디바이스의 능력을 취득한다.

HRESULT GetCaps(
  LPDSCAPS lpDSCaps
);

파라미터

lpDSCaps
사운드 디바이스의 능력을 보관 유지하고 있는 DSCAPS 구조체에의 포인터.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_UNINITIALIZED

주의

DSCAPS 구조체에 보관 유지되고 있는 정보는, 하드웨어 믹싱 채널의 수, 온보드 사운드 메모리의 용량 등, 사운드 디바이스의 최대 능력과 현재 사용 가능한 능력을 기술한다. 이러한 정보를 사용해 성능을 조정해, 리소스의 할당을 최적화할 수 있다.

리소스의 공유가 전제가 되고 있기 (위해)때문에, 어느 분야에서 최대의 능력을 이용 하면, 다른 분야가 그 영향을 받는 일이 있다. 예를 들어, 최대수의 스트림 사운드 버퍼를 하드웨어 믹싱 하면, 하드웨어 스태틱 사운드 버퍼는 1 개나 이용할 수 없게 된다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

DirectSoundCreate


IDirectSound::GetSpeakerConfig

IDirectSound::GetSpeakerConfig 메소드는, DirectSound 오브젝트에 할당할 수 있었던 스피커의 구성을 취득한다.

HRESULT GetSpeakerConfig(
  LPDWORD lpdwSpeakerConfig
);

파라미터

lpdwSpeakerConfig
이 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

주의

lpdwSpeakerConfig 에 돌려주어지는 값은, 구성과 지오메트리 정보의 양쪽 모두를 보관 유지하는 팩 DWORD 가 되는 일이 있다. DWORD 를 unpack 하려면 , 다음의 예의 같게 DSSPEAKER_CONFIG 와 DSSPEAKER_GEOMETRY 의 각 매크로를 사용한다.

if (DSSPEAKER_CONFIG(dwSpeakerConfig) == DSSPEAKER_STEREO)
    {
    if (DSSPEAKER_GEOMETRY(dwSpeakerConfig) ==
                      DSSPEAKER_GEOMETRY_WIDE)
       {...}
    }

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound::SetSpeakerConfig ,스피커의 구성


IDirectSound::Initialize

IDirectSound::Initialize 메소드는,CoCreateInstance 함수를 사용해 생성 한 DirectSound 오브젝트를 초기화한다.

HRESULT Initialize(
  LPCGUID lpcGuid
);

파라미터

lpcGuid
DirectSound 오브젝트에 할당할 수 있는 사운드 드라이버를 지정하는 GUID (글로벌 유니크 식별자) 주소. 프라이머리 사운드 드라이버를 선택하려면 , NULL 를 건네준다.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_ALREADYINITIALIZED
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_NODRIVER

주의

이 메소드는 COM 프로토콜에 준거해 제공되고 있다. DirectSoundCreate 함수를 사용해 DirectSound 오브젝트를 생성 했을 경우는, 이 메소드는 DSERR_ALREADYINITIALIZED 를 돌려준다. CoCreateInstance 를 사용해 DirectSound 오브젝트를 생성 한 후,IDirectSound::Initialize 를 호출하지 않으면 그 후에 호출한 모든 메소드는 DSERR_UNINITIALIZED 를 돌려준다.

lLpcGuid 파라미터는, DirectX 7.0 으로 LPGUID 로부터 LPCGUID 로 변경되었다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

DirectSoundCreate


IDirectSound::SetCooperativeLevel

IDirectSound::SetCooperativeLevel 메소드는, 이 사운드 디바이스의 어플리케이션 협조 레벨을 설정한다.

HRESULT SetCooperativeLevel(
  HWND hwnd,
  DWORD dwLevel
);

파라미터

hwnd
어플리케이션에의 윈도우 핸들. 「주의」를 참조할것.
dwLevel
요구되는 우선 레벨. 이하의 값의 어느쪽이든을 지정한다.
DSSCL_EXCLUSIVE
어플리케이션을 배타 레벨로 설정한다. 입력초점이 놓여져 있는 어플리케이션만이 소리를 낼 수 있다 (DSBCAPS_GLOBALFOCUS 플래그가 설정되어 있는 어플리케이션의 사운드는 무음이 된다). 이 레벨로 설정된 어플리케이션은, DSSCL_PRIORITY 레벨의 모든 특권도 갖추고 있다. 어플리케이션이 입력초점을 얻으면(자), DirectSound 는 전회 IDirectSoundBuffer::SetFormat 메소드를 호출했을 때에 지정된 하드웨어 포맷을 복원한다. (어느 우선 레벨이 설정되어 있어도, DirectSound 는 항상 웨이브 포맷을 복원하는 점에 주의 해야 한다. )
DSSCL_NORMAL
어플리케이션을 완전하게 협조 가능한 스테이터스로 설정한다. 이 레벨에서는 가장 순조로운 multitasking와 리소스 공유의 동작을 얻을 수 있지만, 프라이머리 버퍼의 포맷의 변경은 실시하지 못하고, 출력도 디폴트의 8 비트 포맷으로 한정된다.
DSSCL_PRIORITY
어플리케이션을 우선 레벨로 설정한다. 이 협조 레벨로 설정된 어플리케이션은 IDirectSoundBuffer::SetFormat 와 IDirectSound::Compact 의 각 메소드를 호출할 수 있다.
DSSCL_WRITEPRIMARY
이것은 최상정도의 우선 레벨이다. 이 어플리케이션은 프라이머리 사운드 버퍼에의 쓰기 액세스를 보관 유지한다. 세컨드리 사운드 버퍼는 모두 재생할 수 없다. 디바이스가 DirectSound 드라이버로 에뮬레이트 되고 있는 경우, 즉 IDirectSound::GetCaps 메소드가 DSCAPS 구조 체내에 DSCAPS_EMULDRIVER 플래그를 돌려주었을 경우는, 이 레벨은 설정할 수 없다.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_ALLOCATED
DSERR_INVALIDPARAM
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

주의

어플리케이션은 버퍼를 재생하기 전에, 이 메소드를 호출해 협조 레벨을 설정해야 한다. 추천 되는 협조 레벨은 DSSCL_PRIORITY 이다. 다른 우선 레벨은 필요에 따라서 사용한다. 상세한 것에 대하여는, 「협조 레벨」을 참조할것.

hwnd 파라미터는, 최상정도의 윈도우 핸들로 해야 한다. DirectDraw 도 사용하고 있는 경우는,IDirectDraw7::SetCooperativeLevel 메소드에 건네준 것과 같은 핸들을 지정해야 한다.

어플리케이션이 윈도우 핸들을 간단하게 제공할 수 없는 경우, 다음의 코드를 사용해 윈도우 핸들을 취득할 수 있다.

HWND hWnd = GetForegroundWindow();
if (hWnd == NULL)
{
    hWnd = GetDesktopWindow();
}

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound::Compact ,IDirectSoundBuffer::GetFormat ,IDirectSoundBuffer::GetVolume ,IDirectSoundBuffer::Lock ,IDirectSoundBuffer::Play ,IDirectSoundBuffer::Restore ,IDirectSoundBuffer::SetFormat


IDirectSound::SetSpeakerConfig

IDirectSound::SetSpeakerConfig 메소드는, DirectSound 오브젝트의 스피커 구성을 지정한다.

HRESULT SetSpeakerConfig(
  DWORD dwSpeakerConfig
);

파라미터

dwSpeakerConfig
DirectSound 오브젝트의 스피커 구성. 이 파라미터에, 이하의 값의 어느쪽이든을 지정한다.
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));

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 :dsound.h 로 선언.
임포트 라이브러리 :dsound.lib 를 사용.

참조

IDirectSound::GetSpeakerConfig ,스피커의 구성


IDirectSound3DBuffer 인터페이스

어플리케이션은 IDirectSound3DBuffer 인터페이스의 메소드를 사용해, 3D 공간에 있어서의 청취자의 위치, 방향, 환경을 기술하는 파라미터의 취득과 설정을 실시한다. 여기에서는, IDirectSound3DBuffer 인터페이스의 메소드의 레퍼런스를 제공한다. 개요에 대해서는, 「DirectSound 3D 버퍼」를 참조할것.

IDirectSound3DBuffer 는,IDirectSoundBuffer::QueryInterface 메소드를 사용해 취득한다. 상세한 것에 대하여는, 「DirectSound3DBuffer 오브젝트의 취득」을 참조할것.

IDirectSound3DBuffer 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

배치 파라미터 조작 | GetAllParameters
 | SetAllParameters
거리 | GetMaxDistance
 | GetMinDistance
 | SetMaxDistance
 | SetMinDistance
조작 모드 | GetMode
 | SetMode
위치 | GetPosition
 | SetPosition
사운드 프로젝션 콘 | GetConeAngles
 | GetConeOrientation
 | GetConeOutsideVolume
 | SetConeAngles
 | SetConeOrientation
 | SetConeOutsideVolume
속도 | GetVelocity
 | SetVelocity

모든 COM 인터페이스와 같이,IDirectSound3DBuffer 인터페이스는 IUuknown 인터페이스 메소드를 계승하고 있다. IUnknown 인터페이스는 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUND3DBUFFER 형은,IDirectSound3DBuffer 인터페이스에의 포인터로서 정의되고 있다.

typedef struct IDirectSound3DBuffer    *LPDIRECTSOUND3DBUFFER;

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSound3DBuffer::GetAllParameters

IDirectSound3DBuffer::GetAllParameters 메소드는, 지정한 시점에서의 사운드 버퍼의 3D 특성에 관한 정보를 취득한다.

HRESULT GetAllParameters(
  LPDS3DBUFFER lpDs3dBuffer
);

파라미터

lpDs3dBuffer
DS3DBUFFER 구조체의 주소. 이 구조체는 사운드 버퍼의 3D 특성에 관한 정보를 보관 유지하고 있다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSound3DBuffer::GetConeAngles

IDirectSound3DBuffer::GetConeAngles 메소드는, 사운드 버퍼의 사운드 프로젝션 콘의 내부 각도와 외부 각도를 취득한다.

HRESULT GetConeAngles(
  LPDWORD lpdwInsideConeAngle,
  LPDWORD lpdwOutsideConeAngle
);

파라미터

lpdwInsideConeAngle,lpdwOutsideConeAngle
사운드 프로젝션 콘의 내부 각도와 외부 각도를 보관 유지하는 각 변수의 주소. 단위는 번 (˚).

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

최소, 최대, 디폴트의 각 콘 각도는 dsound.h 내에서 각각 DS3D_MINCONEANGLE, DS3D_MAXCONEANGLE, DS3D_DEFAULTCONEANGLE 로서 정의된다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSound3DBuffer::GetConeOrientation

IDirectSound3DBuffer::GetConeOrientation 메소드는, 사운드 버퍼의 사운드 프로젝션 콘의 방향을 취득한다.

HRESULT GetConeOrientation(
  LPD3DVECTOR lpvOrientation
);

파라미터

lpvOrientation
D3DVECTOR 구조체의 주소. 이 구조체는, 사운드 프로젝션 콘의 현재의 방향을 보관 유지한다. 벡터 정보는 사운드 콘의 중심을 나타낸다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

반환값은 반드시 IDirectSound3DBuffer::SetConeOrientation 메소드를 사용해 설정한 것과 같은 값은 아니다. DirectSound 는 방향 벡터에 조정을 더해 그러한 크기를 1.0 이하로 한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DBuffer::SetConeOrientation ,IDirectSound3DBuffer::SetConeAngles ,IDirectSound3DBuffer::SetConeOutsideVolume


IDirectSound3DBuffer::GetConeOutsideVolume

IDirectSound3DBuffer::GetConeOutsideVolume 메소드는, 사운드 버퍼의 현재의 콘 외부 볼륨을 취득한다.

HRESULT GetConeOutsideVolume(
  LPLONG lplConeOutsideVolume
);

파라미터

lplConeOutsideVolume
버퍼의 현재의 콘 외부 볼륨을 보관 유지하는 변수의 주소.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

볼륨 레벨은 감쇠에 의해 나타내진다. 허용 되는 값은 DSBVOLUME_MAX (감쇠 없음)와 DSBVOLUME_MIN (무음)의 사이이다. 디폴트값은 DS3D_DEFAULTCONEOUTSIDEVOLUME (감쇠 없음)이다. 이러한 값은 dsound.h 내에서 정의되고 있다. 현재 DirectSound 는 증폭을 지원 하고 있지 않다.

콘 외부 볼륨의 개념에 대해서는, 「사운드 콘」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSoundBuffer::SetVolume


IDirectSound3DBuffer::GetMaxDistance

IDirectSound3DBuffer::GetMaxDistance 메소드는, 사운드 버퍼의 현재의 최대 거리를 취득한다.

HRESULT GetMaxDistance(
  LPD3DVALUE lpflMaxDistance
);

파라미터

lpflMaxDistance
현재의 최대 거리의 설정을 보관 유지하는 변수의 주소.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

디폴트의 최대 거리는 DS3D_DEFAULTMAXDISTANCE 에 의해 정의되어 실질적으로 무한대이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DBuffer::GetMinDistance ,IDirectSound3DBuffer::SetMaxDistance


IDirectSound3DBuffer::GetMinDistance

IDirectSound3DBuffer::GetMinDistance 메소드는, 사운드 버퍼의 현재의 최소 거리를 취득한다.

HRESULT GetMinDistance(
  LPD3DVALUE lpflMinDistance
);

파라미터

lpflMinDistance
현재의 최소 거리의 설정을 보관 유지하는 변수의 주소.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

디폴트에서는, 최소 거리값은 DS3D_DEFAULTMINDISTANCE 이며, 현재는 1.0 으로 정의되고 있다 (디폴트의 거리 계수 1.0 을 사용했을 경우는, 1 단위는 1.0 미터에 상당한다).

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DBuffer::SetMinDistance ,IDirectSound3DBuffer::GetMaxDistance


IDirectSound3DBuffer::GetMode

IDirectSound3DBuffer::GetMode 메소드는, 3D 사운드 처리의 현재의 조작 모드를 취득한다.

HRESULT GetMode(
  LPDWORD lpdwMode
);

파라미터

lpdwMode
현재의 조작 모드의 설정을 보관 유지하는 변수의 주소. 다음의 값중 한쪽이 돌려주어진다.
DS3DMODE_DISABLE
3D 사운드 처리는 무효가 된다. 사운드는 청취자의 머릿속심으로 발생하고 있도록(듯이) 들린다.
DS3DMODE_HEADRELATIVE
사운드 파라미터 (위치, 속도, 방향)는 청취자의 파라미터에 대한 상대적인 것이다. 이 모드에서는, 청취자의 파라미터가 변화했을 때에 사운드의 절대 파라미터가 자동적으로 갱신되므로, 상대 파라미터는 일정으로 유지된다.
DS3DMODE_NORMAL
표준의 처리. 이것은 디폴트의 모드이다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSound3DBuffer::GetPosition

IDirectSound3DBuffer::GetPosition 메소드는, 사운드 버퍼의 현재 위치를 거리 단위로 취득한다. 디폴트에서는 거리 단위는 미터이지만,IDirectSound3DListener::SetDistanceFactor 메소드를 사용해 단위를 변경할 수 있다.

HRESULT GetPosition(
  LPD3DVECTOR lpvPosition
);

파라미터

lpvPosition
D3DVECTOR 구조체의 주소. 이 구조체는, 사운드 버퍼의 현재 위치를 보관 유지한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSound3DBuffer::GetVelocity

IDirectSound3DBuffer::GetVelocity 메소드는, 사운드 버퍼의 현재의 속도를 취득한다. 속도는, 초속 단위로 계측 된다. 디폴트의 단위는 미터/초이지만,IDirectSound3DListener::SetDistanceFactor 메소드를 사용해 변경할 수 있다.

HRESULT GetVelocity(
  LPD3DVECTOR lpvVelocity
);

파라미터

lpvVelocity
D3DVECTOR 구조체의 주소. 이 구조체는 사운드 버퍼의 현재의 속도를 보관 유지한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

속도는 도플러 효과에서만 사용된다. 실제로 버퍼를 이동할 것은 없다. 상세한 것에 대하여는, 「돕라 계수」를 참조할것.

디폴트의 계측 단위는 미터/초이지만,IDirectSound3DListener::SetDistanceFactor 메소드를 사용해 변경할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DBuffer::SetPosition ,IDirectSound3DBuffer::SetVelocity


IDirectSound3DBuffer::SetAllParameters

IDirectSound3DBuffer::SetAllParameters 메소드는,DS3DBUFFER 구조체로 지정한, 모든 3D 사운드 버퍼 파라미터를 설정한다. 이 구조체는, 어느 순간의 사운드 버퍼의 모든 상태를 기술한다.

HRESULT SetAllParameters(
  LPCDS3DBUFFER lpcDs3dBuffer,
  DWORD dwApply
);

파라미터

lpcDs3dBuffer
DS3DBUFFER 구조체의 주소. 이 구조체는 사운드 버퍼의 3D 특성을 보관 유지하고 있다.
dwApply
설정이 적용되는 타이밍을 나타내는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener::CommitDeferredSettings 메소드를 호출할 때까지 설정을 적용하지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSound3DBuffer::SetConeAngles

IDirectSound3DBuffer::SetConeAngles 메소드는, 사운드 버퍼의 사운드 프로젝션 콘의 내부 각도와 외부 각도를 설정한다.

HRESULT SetConeAngles(
  DWORD dwInsideConeAngle,
  DWORD dwOutsideConeAngle,
  DWORD dwApply
);

파라미터

dwInsideConeAngle,dwOutsideConeAngle
사운드 프로젝션 콘의 내부 각도와 외부 각도. 단위는 번 (˚).
dwApply
설정이 적용되는 타이밍을 나타내는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener::CommitDeferredSettings 메소드를 호출할 때까지 설정을 적용하지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

최소, 최대, 디폴트의 각 콘 각도는 dsound.h 내에서 각각 DS3D_MINCONEANGLE, DS3D_MAXCONEANGLE, DS3D_DEFAULTCONEANGLE 로서 정의된다. 각 각도의 범위는, 0 번 (콘 없음)에서 360 번 (전범위)까지이다. 디폴트값은 360 이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DBuffer::GetConeOutsideVolume ,IDirectSound3DBuffer::SetConeOutsideVolume


IDirectSound3DBuffer::SetConeOrientation

IDirectSound3DBuffer::SetConeOrientation 메소드는, 사운드 버퍼의 사운드 프로젝션 콘의 방향을 설정한다. 콘 각도와 콘 볼륨 계수가 이미 설정되어 있지 않은 한, 이 메소드는 아무것도 하지 않는다.

HRESULT SetConeOrientation(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z,
  DWORD dwApply
);

파라미터

x,y,z
D3DVALUE 형의 값. 이러한 값은, 사운드 콘의 새로울 방향 벡터의 좌표를 나타낸다.
dwApply
설정이 적용되는 타이밍을 나타내는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener::CommitDeferredSettings 메소드를 호출할 때까지 설정을 적용하지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DBuffer::SetConeAngles ,IDirectSound3DBuffer::SetConeOutsideVolume


IDirectSound3DBuffer::SetConeOutsideVolume

IDirectSound3DBuffer::SetConeOutsideVolume 메소드는, 사운드 버퍼의 현재의 콘 외부 볼륨을 설정한다.

HRESULT SetConeOutsideVolume(
  LONG lConeOutsideVolume,
  DWORD dwApply
);

파라미터

lConeOutsideVolume
사운드 버퍼의 콘 외부 볼륨을 100 분의 1 데시벨 (dB)의 단위로 지정한다. 허용 되는 값은 DSBVOLUME_MAX (감쇠 없음)와 DSBVOLUME_MIN (무음)의 사이이다. 이러한 값은 dsound.h 내에서 정의되고 있다.
dwApply
설정이 적용되는 타이밍을 나타내는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener::CommitDeferredSettings 메소드를 호출할 때까지 설정을 적용하지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

볼륨 레벨은 감쇠에 의해 나타내진다. 허용 되는 값은 DSBVOLUME_MAX (감쇠 없음)와 DSBVOLUME_MIN (무음)의 사이이다. 디폴트값은 DS3D_DEFAULTCONEOUTSIDEVOLUME (감쇠 없음)이다. 이러한 값은 dsound.h 내에서 정의되고 있다. 현재 DirectSound 는 증폭을 지원 하고 있지 않다.

콘 외부 볼륨의 개념에 대해서는, 「사운드 콘」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSoundBuffer::SetVolume


IDirectSound3DBuffer::SetMaxDistance

IDirectSound3DBuffer::SetMaxDistance 메소드는, 현재의 최대 거리값을 설정한다.

HRESULT SetMaxDistance(
  D3DVALUE flMaxDistance,
  DWORD dwApply
);

파라미터

flMaxDistance
새로운 최대 거리값.
dwApply
설정이 적용되는 타이밍을 나타내는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener::CommitDeferredSettings 메소드를 호출할 때까지 설정을 적용하지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

디폴트의 최대 거리는 DS3D_DEFAULTMAXDISTANCE 에 의해 정의되어 실질적으로 무한대이다.

동작환경

Windows NT/2000 :Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DBuffer::GetMaxDistance ,IDirectSound3DBuffer::SetMinDistance


IDirectSound3DBuffer::SetMinDistance

IDirectSound3DBuffer::SetMinDistance 메소드는, 현재의 최소 거리값을 설정한다.

HRESULT SetMinDistance(
  D3DVALUE flMinDistance,
  DWORD dwApply
);

파라미터

flMinDistance
새로운 최소 거리값.
dwApply
설정이 적용되는 타이밍을 나타내는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener::CommitDeferredSettings 메소드를 호출할 때까지 설정을 적용하지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

디폴트에서는, 최소 거리값은 DS3D_DEFAULTMINDISTANCE 이며, 현재는 1.0 으로 정의되고 있다 (디폴트의 거리 계수 1.0 을 사용했을 경우는, 1 단위는 1.0 미터에 상당한다).

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DBuffer::SetMaxDistance


IDirectSound3DBuffer::SetMode

IDirectSound3DBuffer::SetMode 메소드는, 3D 사운드 처리의 조작 모드를 설정한다.

HRESULT SetMode(
  DWORD dwMode,
  DWORD dwApply
);

파라미터

dwMode
설정되는 3D 사운드 처리 모드를 지정하는 플래그.
DS3DMODE_DISABLE
3D 사운드 처리는 무효가 된다. 사운드는 청취자의 머릿속심으로 발생하고 있도록(듯이) 들린다.
DS3DMODE_HEADRELATIVE
사운드 파라미터 (위치, 속도, 방향)는 청취자의 파라미터에 대한 상대적인 것이다. 이 모드에서는, 청취자의 파라미터가 변화했을 때에 사운드의 절대 파라미터는 자동적으로 갱신되므로, 상대 파라미터는 일정으로 유지된다.
DS3DMODE_NORMAL
표준의 처리. 이것은 디폴트의 모드이다.
dwApply
설정이 적용되는 타이밍을 나타내는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener::CommitDeferredSettings 메소드를 호출할 때까지 설정을 적용하지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSound3DBuffer::SetPosition

IDirectSound3DBuffer::SetPosition 메소드는, 사운드 버퍼의 현재 위치를 거리 단위로 설정한다. 디폴트에서는 거리 단위는 미터이지만,IDirectSound3DListener::SetDistanceFactor 메소드를 사용해 단위를 변경할 수 있다.

HRESULT SetPosition(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z,
  DWORD dwApply
);

파라미터

x,y,z
D3DVALUE 형의 값. 이러한 값은, 새로운 위치 벡터의 좌표를 나타낸다. 부동 소수점의 오버플로우를 방지하기 위해서, DirectSound 가 이러한 값에 조정을 더할 가능성이 있는 점에 주의 해야 한다.
dwApply
설정이 적용되는 타이밍을 나타내는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener::CommitDeferredSettings 메소드를 호출할 때까지 설정을 적용하지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSound3DBuffer::SetVelocity

IDirectSound3DBuffer::SetVelocity 메소드는, 사운드 버퍼의 현재의 속도를 설정한다.

HRESULT SetVelocity(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z,
  DWORD dwApply
);

파라미터

x,y,z
D3DVALUE 형의 값. 이러한 값은, 새로운 속도벡터의 좌표를 나타낸다. 부동 소수점의 오버플로우를 방지하기 위해서, DirectSound 가 이러한 값에 조정을 더할 가능성이 있는 점에 주의 해야 한다.
dwApply
설정이 적용되는 타이밍을 나타내는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener::CommitDeferredSettings 메소드를 호출할 때까지 설정을 적용하지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

속도는 도플러 효과에서만 사용된다. 실제로 버퍼를 이동할 것은 없다. 상세한 것에 대하여는, 「돕라 계수」를 참조할것.

디폴트의 계측 단위는 미터/초이지만,IDirectSound3DListener::SetDistanceFactor 메소드를 사용해 변경할 수 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DBuffer::SetPosition ,IDirectSound3DBuffer::GetVelocity


IDirectSound3DListener 인터페이스

어플리케이션은 IDirectSound3DListener 인터페이스의 메소드를 사용해, 3D 공간에서의 청취자의 위치, 방향, 리스닝 환경을 기술하는 파라미터의 취득과 설정을 실시한다. 여기에서는, IDirectSound3DListener 인터페이스의 메소드의 레퍼런스를 제공한다. 개요에 대해서는, 「DirectSound 3D 청취자」를 참조할것.

IDirectSoundBuffer::QueryInterface 메소드를 사용해, 이 인터페이스를 취득한다. 상세한 것에 대하여는, 「DirectSound3DListener 오브젝트의 취득」을 참조할것.

IDirectSound3DListener 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

배치 파라미터 조작 | GetAllParameters
 | SetAllParameters
지연 설정 | CommitDeferredSettings
거리 계수 | GetDistanceFactor
 | SetDistanceFactor
돕라 계수 | GetDopplerFactor
 | SetDopplerFactor
방향 | GetOrientation
 | SetOrientation
위치 | GetPosition
 | SetPosition
롤 오프 계수 | GetRolloffFactor
 | SetRolloffFactor
속도 | GetVelocity
 | SetVelocity

모든 COM 인터페이스와 같이,IDirectSound3DListener 인터페이스는 IUuknown 인터페이스 메소드를 계승하고 있다. IUnknown 인터페이스는 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUND3DLISTENER 형은,IDirectSound3DListener 인터페이스에의 포인터로서 정의되고 있다.

typedef struct IDirectSound3DListener    *LPDIRECTSOUND3DLISTENER;

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSound3DListener::CommitDeferredSettings

IDirectSound3DListener::CommitDeferredSettings 메소드는, 전회 이 메소드를 호출한 후에 행해진 지연 설정을 위탁한다.

HRESULT CommitDeferredSettings();

파라미터

없음.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

최대의 효율을 가져오는 지연 설정의 사용법에 대해서는, 「지연 설정」을 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSound3DListener::GetAllParameters

IDirectSound3DListener::GetAllParameters 메소드는, 3D 월드와 청취자의 현재 상태를 나타내는 정보를 취득한다.

HRESULT GetAllParameters(
  LPDS3DLISTENER lpListener
);

파라미터

lpListener
DS3DLISTENER 구조체의 주소. 이 구조체는 3D 월드와 청취자의 현재 상태를 보관 유지한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DListener::SetAllParameters


IDirectSound3DListener::GetDistanceFactor

IDirectSound3DListener::GetDistanceFactor 메소드는, 현재의 거리 계수를 취득한다.

HRESULT GetDistanceFactor(
  LPD3DVALUE lpflDistanceFactor
);

파라미터

lpflDistanceFactor
D3DVALUE 형의 변수의 주소. 이 변수는, 현재의 거리 계수의 값을 보관 유지한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

거리 계수의 상세한 것에 대하여는, 「거리 계수」를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DListener::SetDistanceFactor


IDirectSound3DListener::GetDopplerFactor

IDirectSound3DListener::GetDopplerFactor 메소드는, 현재의 도플러 효과 계수를 취득한다.

HRESULT GetDopplerFactor(
  LPD3DVALUE lpflDopplerFactor
);

파라미터

lpflDopplerFactor
D3DVALUE 형의 변수의 주소. 이 변수는 현재의 돕라 계수의 값을 보관 유지한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

돕라 계수의 범위는, DS3D_MINDOPPLERFACTOR (도플러 효과 없음)로부터 DS3D_MAXDOPPLERFACTOR (현재의 정의에서는 열매 세계의 10 배의 도플러 효과)까지이다. 디폴트값은 DS3D_DEFAULTDOPPLERFACTOR (1.0)이다. 상세한 것에 대하여는, 「돕라 계수」를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DListener::SetDopplerFactor


IDirectSound3DListener::GetOrientation

IDirectSound3DListener::GetOrientation 메소드는, 전방 벡터와 윗쪽 벡터의 2 개의 벡터에 의해, 청취자의 현재의 방향을 취득한다.

HRESULT GetOrientation(
  LPD3DVECTOR lpvOrientFront,
  LPD3DVECTOR lpvOrientTop
);

파라미터

lpvOrientFront
D3DVECTOR 구조체의 주소. 이 구조체는 청취자의 전방 벡터를 보관 유지한다.
lpvOrientTop
D3DVECTOR 구조체의 주소. 이 구조체는 청취자의 윗쪽 벡터를 보관 유지한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

전방 벡터는 청취자의 코의 방향, 윗쪽 벡터는 청취자의 두정부의 방향을 가리킨다. 디폴트에서는, 전방 벡터는 (0, 0, 1.0), 윗쪽 벡터는 (0, 1.0, 0)이다.

반환값은 반드시 IDirectSound3DListener::SetOrientation 를 사용해 설정한 것과 같은 값은 아니다. DirectSound 는 방향 벡터에 조정을 더해, 그것들이 서로 직교 하도록(듯이) 해, 양쪽 모두의 크기를 1.0 이하로 한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DListener::SetOrientation


IDirectSound3DListener::GetPosition

IDirectSound3DListener::GetPosition 메소드는, 청취자의 현재 위치를 거리 단위로 취득한다. 디폴트에서는 거리 단위는 미터이지만,IDirectSound3DListener::SetDistanceFactor 메소드를 사용해 단위를 변경할 수 있다.

HRESULT GetPosition(
  LPD3DVECTOR lpvPosition
);

파라미터

lpvPosition
D3DVECTOR 구조체의 주소. 이 구조체는 청취자의 현재 위치를 보관 유지한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DListener::SetPosition


IDirectSound3DListener::GetRolloffFactor

IDirectSound3DListener::GetRolloffFactor 메소드는, 현재의 롤 오프 계수를 취득한다.

HRESULT GetRolloffFactor(
  LPD3DVALUE lpflRolloffFactor
);

파라미터

lpflRolloffFactor
D3DVALUE 형의 변수의 주소. 이 변수는 현재의 롤 오프 계수의 값을 보관 유지한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

롤 오프 계수는, DS3D_MINROLLOFFFACTOR (롤 오프 없음)로부터 DS3D_MAXROLLOFFFACTOR (현재의 정의에서는 열매 세계의 10 배)까지의 범위를 취한다. 디폴트값은 DS3D_DEFAULTROLLOFFFACTOR (1.0)이다. 상세한 것에 대하여는, 「롤 오프 계수」를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DListener::SetRolloffFactor


IDirectSound3DListener::GetVelocity

IDirectSound3DListener::GetVelocity 메소드는, 청취자의 현재의 속도를 취득한다.

HRESULT GetVelocity(
  LPD3DVECTOR lpvVelocity
);

파라미터

lpvVelocity
D3DVECTOR 구조체의 주소. 이 구조체는 청취자의 현재의 속도를 보관 유지한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

속도는 도플러 효과에서만 사용된다. 실제로 청취자를 이동할 것은 없다. 청취자의 위치를 변경하려면 IDirectSound3DListener::SetPosition 메소드를 사용한다. 디폴트의 속도는 (0,0,0)이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DListener::SetVelocity


IDirectSound3DListener::SetAllParameters

IDirectSound3DListener::SetAllParameters 메소드는,DS3DLISTENER 구조체로 지정한, 모든 3D 청취자 파라미터를 설정한다. 이 구조체는 있는 순간의 청취자의 모든 상태를 기술한다.

HRESULT SetAllParameters(
  LPCDS3DLISTENER lpcListener,
  DWORD dwApply
);

파라미터

lpcListener
DS3DLISTENER 구조체의 주소. 이 구조체는 현재의 3D 청취자의 모든 파라미터 정보를 보관 유지한다.
dwApply
설정이 적용되는 타이밍을 나타내는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener::CommitDeferredSettings 메소드를 호출할 때까지 설정을 적용하지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DListener::GetAllParameters


IDirectSound3DListener::SetDistanceFactor

IDirectSound3DListener::SetDistanceFactor 메소드는, 현재의 거리 계수를 설정한다.

HRESULT SetDistanceFactor(
  D3DVALUE flDistanceFactor,
  DWORD dwApply
);

파라미터

flDistanceFactor
새로운 거리 계수.
dwApply
설정이 적용되는 타이밍을 나타내는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener::CommitDeferredSettings 메소드를 호출할 때까지 설정을 적용하지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

거리 계수의 상세한 것에 대하여는, 「거리 계수」를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DListener::GetDistanceFactor


IDirectSound3DListener::SetDopplerFactor

IDirectSound3DListener::SetDopplerFactor 메소드는, 현재의 도플러 효과 계수를 설정한다.

HRESULT SetDopplerFactor(
  D3DVALUE flDopplerFactor,
  DWORD dwApply
);

파라미터

flDopplerFactor
새로운 돕라 계수의 값.
dwApply
설정이 적용되는 타이밍을 나타내는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener::CommitDeferredSettings 메소드를 호출할 때까지 설정을 적용하지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

돕라 계수의 범위는, DS3D_MINDOPPLERFACTOR (도플러 효과 없음)로부터 DS3D_MAXDOPPLERFACTOR (현재의 정의에서는 열매 세계의 10 배의 도플러 효과)까지이다. 디폴트값은 DS3D_DEFAULTDOPPLERFACTOR (1.0)이다. 상세한 것에 대하여는, 「돕라 계수」를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DListener::GetDopplerFactor


IDirectSound3DListener::SetOrientation

IDirectSound3DListener::SetOrientation 메소드는, 전방 벡터와 윗쪽 벡터의 2 개의 벡터에 의해, 청취자의 현재의 방향을 설정한다.

HRESULT SetOrientation(
  D3DVALUE xFront,
  D3DVALUE yFront,
  D3DVALUE zFront,
  D3DVALUE xTop,
  D3DVALUE yTop,
  D3DVALUE zTop,
  DWORD dwApply
);

파라미터

xFront,yFront,zFront
D3DVALUE 형의 값. 이러한 값은, 전방 벡터의 좌표를 나타낸다.
xTop,yTop,zTop
D3DVALUE 형의 값. 이러한 값은, 윗쪽 벡터의 좌표를 나타낸다.
dwApply
설정이 적용되는 타이밍을 나타내는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener::CommitDeferredSettings 메소드를 호출할 때까지 설정을 적용하지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

전방 벡터는 청취자의 코의 방향, 윗쪽 벡터는 청취자의 두정부의 방향을 가리킨다. 디폴트에서는, 전방 벡터는 (0, 0, 1.0), 윗쪽 벡터는 (0, 1.0, 0)이다.

윗쪽 벡터는 전방 벡터에 대해서 직각이 아니면 안된다. 필요에 따라서, DirectSound 는 전방 벡터를 설정한 다음에 윗쪽 벡터를 조정한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DListener::GetOrientation


IDirectSound3DListener::SetPosition

IDirectSound3DListener::SetPosition 메소드는, 청취자의 현재 위치를 거리 단위로 설정한다. 디폴트에서는 거리 단위는 미터이지만,IDirectSound3DListener::SetDistanceFactor 메소드를 사용해 단위를 변경할 수 있다.

HRESULT SetPosition(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z,
  DWORD dwApply
);

파라미터

x,y,z
D3DVALUE 형의 값. 이러한 값은, 청취자의 새로운 위치 벡터의 좌표를 나타낸다. 부동 소수점의 오버플로우를 방지하기 위해서, DirectSound 가 이러한 값에 조정을 더할 가능성이 있는 점에 주의 해야 한다.
dwApply
설정이 적용되는 타이밍을 나타내는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener::CommitDeferredSettings 메소드를 호출할 때까지 설정을 적용하지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DListener::GetPosition


IDirectSound3DListener::SetRolloffFactor

IDirectSound3DListener::SetRolloffFactor 메소드는, 롤 오프 계수를 설정한다.

HRESULT SetRolloffFactor(
  D3DVALUE flRolloffFactor,
  DWORD dwApply
);

파라미터

flRolloffFactor
새로운 롤 오프 계수.
dwApply
설정이 적용되는 타이밍을 나타내는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener::CommitDeferredSettings 메소드를 호출할 때까지 설정을 적용하지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

롤 오프 계수는, DS3D_MINROLLOFFFACTOR (롤 오프 없음)로부터 DS3D_MAXROLLOFFFACTOR (현재의 정의에서는 열매 세계의 10 배)까지의 범위를 취한다. 디폴트값은 DS3D_DEFAULTROLLOFFFACTOR (1.0)이다. 상세한 것에 대하여는, 「롤 오프 계수」를 참조할것.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DListener::GetRolloffFactor


IDirectSound3DListener::SetVelocity

IDirectSound3DListener::SetVelocity 메소드는, 청취자의 속도를 설정한다.

HRESULT SetVelocity(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z,
  DWORD dwApply
);

파라미터

x,y,z
D3DVALUE 형의 값. 이러한 값은, 청취자의 새로운 속도 좌표를 나타낸다. 부동 소수점의 오버플로우를 방지하기 위해서, DirectSound 가 이러한 값에 조정을 더할 가능성이 있는 점에 주의 해야 한다.
dwApply
설정이 적용되는 타이밍을 나타내는 값. 다음의 값의 언젠가가 아니면 안된다.
DS3D_DEFERRED
어플리케이션이 IDirectSound3DListener::CommitDeferredSettings 메소드를 호출할 때까지 설정을 적용하지 않는다. 어플리케이션은 복수의 설정을 변경한 후, 1 회의 재계산으로 그것들을 적용할 수 있다.
DS3D_IMMEDIATE
설정을 즉시에 적용해, 시스템은 모든 3D 사운드 버퍼의 3D 좌표를 재계산한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

속도는 도플러 효과에서만 사용된다. 실제로 청취자를 이동할 것은 없다. 청취자의 위치를 변경하려면 IDirectSound3DListener::SetPosition 메소드를 사용한다. 디폴트의 속도는 (0,0,0)이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound3DListener::GetVelocity


IDirectSoundBuffer 인터페이스

어플리케이션은 IDirectSoundBuffer 인터페이스의 메소드를 사용해, DirectSoundBuffer 오브젝트의 생성과 환경 설정을 실시한다.

IDirectSound::CreateSoundBuffer 메소드를 사용해 이 인터페이스를 취득한다.

IDirectSoundBuffer 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

정보 | GetCaps
 | GetFormat
 | GetStatus
 | SetFormat
메모리 메니지먼트 | Initialize
 | Restore
재생 관리 | GetCurrentPosition
 | Lock
 | Play
 | SetCurrentPosition
 | Stop
 | Unlock
사운드 관리 | GetFrequency
 | GetPan
 | GetVolume
 | SetFrequency
 | SetPan
 | SetVolume

모든 COM 인터페이스와 같게,IDirectSoundBuffer 인터페이스도 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUNDBUFFER 형은,IDirectSoundBuffer 인터페이스에의 포인터로서 정의되고 있다.

typedef struct IDirectSoundBuffer    *LPDIRECTSOUNDBUFFER;

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSoundBuffer::GetCaps

IDirectSoundBuffer::GetCaps 메소드는, DirectSoundBuffer 오브젝트의 능력을 취득한다.

HRESULT GetCaps(
  LPDSBCAPS lpDSBufferCaps
);

파라미터

lpDSBufferCaps
DSBCAPS 구조체의 주소. 이 구조체는, 사운드 버퍼의 능력을 보관 유지하고 있다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

DSBCAPS 구조체는,IDirectSound::CreateSoundBuffer 메소드에게 건네지는 DSBUFFERDESC 구조체와 동등의 정보에 가세해, 몇개의 추가 정보를 보관 유지하고 있다. 추가 정보로서 버퍼의 위치 (하드웨어 또는 소프트웨어)와 코스트 측정값을 들 수 있다. 코스트 측정값에는, 하드웨어 버퍼에의 다운로드 소요 시간, 버퍼가 시스템 메모리내에 배치되고 있는 경우의 믹싱이나 재생 처리의 오버헤드가 포함된다.

DSBCAPS 구조체의 dwFlags 멤버내에서 지정되는 플래그는,DSBUFFERDESC 구조체로 사용되는 플래그와 같은 것이다. 유일한 차이는,DSBCAPS 구조체에서는 버퍼 메모리의 장소에 응해 DSBCAPS_LOCHARDWARE 과 DSBCAPS_LOCSOFTWARE 의 어느 쪽인지가 지정되는 것이다. DSBUFFERDESC 구조체에서는 이러한 플래그는 옵션이며, 플래그의 지정에 응해, 버퍼를 하드웨어와 소프트웨어의 어딘가에 강제적으로 배치할 수 있다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

DSBCAPS ,DSBUFFERDESC ,IDirectSoundBuffer ,IDirectSound::CreateSoundBuffer


IDirectSoundBuffer::GetCurrentPosition

IDirectSoundBuffer::GetCurrentPosition 메소드는, 사운드 버퍼내의 재생 커서와 쓰기 커서의 현재의 위치를 취득한다.

HRESULT GetCurrentPosition(
  LPDWORD lpdwCurrentPlayCursor,
  LPDWORD lpdwCurrentWriteCursor
);

파라미터

lpdwCurrentPlayCursor
DirectSoundBuffer 오브젝트내의 현재 플레이 포지션을 보관 유지하는 변수의 주소. 이 정도치는 사운드 버퍼내의 오프셋(offset)이며, 바이트 단위로 지정된다. 현재 플레이 포지션이 필요없는 경우는, 이 파라미터는 NULL 여도 괜찮다.
lpdwCurrentWriteCursor
DirectSoundBuffer 오브젝트내의 현재 라이트 포지션을 보관 유지하는 변수의 주소. 이 정도치는 사운드 버퍼내의 오프셋(offset)이며, 바이트 단위로 지정된다. 현재 라이트 포지션이 필요없는 경우는, 이 파라미터는 NULL 여도 괜찮다.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

쓰기 커서는, 버퍼에의 데이터 쓰기를 안전하게 실시할 수 있는 위치를 나타낸다. 쓰기 커서는 보통, 재생 커서보다 15 밀리 세컨드의 오디오 데이터분만큼 선행하고 있다. 상세한 것에 대하여는, 「현재 플레이 포지션과 현재 라이트 포지션」을 참조할것.

lpdwCurrentPlayCursor 파라미터가 가리키는 위치에서(보다) 후의 장소에서는, 반드시 데이터를 안전하게 변경할 수 있다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSoundBuffer ,IDirectSoundBuffer::SetCurrentPosition


IDirectSoundBuffer::GetFormat

IDirectSoundBuffer::GetFormat 메소드는, 버퍼내의 사운드 데이터의 포맷에 관한 정보, 또는 포맷의 기술을 취득하는데 필요한 버퍼 사이즈를 취득한다.

HRESULT GetFormat(
  LPWAVEFORMATEX lpwfxFormat,
  DWORD dwSizeAllocated,
  LPDWORD lpdwSizeWritten
);

파라미터

lpwfxFormat
버퍼내의 사운드 데이터에 관한 정보를 보관 유지하는 WAVEFORMATEX 구조체의 주소. 포맷의 기술을 보관 유지하는데 필요한 버퍼 사이즈를 취득하려면 NULL 를 지정한다. 이 경우,lpdwSizeWritten 파라미터가 가리키는 DWORD 가, 완전한 포맷 정보를 받는데 필요한 구조체의 사이즈를 받는다.
dwSizeAllocated
WAVEFORMATEX 구조체의 사이즈. 단위는 바이트. DirectSound 가 포인터에 기입하는 바이트수는, 최대로 dwSizeAllocated 바이트이다. WAVEFORMATEX 구조체가 그것보다 많은 메모리를 필요로 하는 경우, 잘라서 버림을 한다.
lpdwSizeWritten
WAVEFORMATEX 구조체에 기입해진 바이트수를 보관 유지하는 변수의 주소. 이 파라미터는 NULL 로 해도 괜찮다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

주의

WAVEFORMATEX 구조체는, 포맷의 상세하게 응한 가변장이어도 괜찮다. 어플리케이션은 포맷의 기술을 취득하기 전에,lpwfxFormat 파라미터에 NULL 를 지정해 이 메소드를 호출해, 포맷의 사이즈에 관해서 DirectSoundBuffer 에 쿼리-를 실시해야 하는 것이다. 구조체의 사이즈는 lpdwSizeWritten 파라미터에 돌려주어진다. 그 후, 어플리케이션은 충분한 메모리를 할당해 한번 더 IDirectSoundBuffer::GetFormat 를 호출해, 포맷의 기술을 취득할 수 있다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSoundBuffer ,IDirectSoundBuffer::SetFormat


IDirectSoundBuffer::GetFrequency

IDirectSoundBuffer::GetFrequency 메소드는, 버퍼의 재생을 하고 있는 장소에서의 1 초 쯤의 샘플링 회수를 주파수로서 취득한다.

HRESULT GetFrequency(
  LPDWORD lpdwFrequency
);

파라미터

lpdwFrequency
오디오 버퍼가 재생되고 있는 장소에서의 주파수를 나타내는 변수의 주소.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

주파수의 값은, DSBFREQUENCY_MIN 로부터 DSBFREQUENCY_MAX 의 범위를 취한다. 현재 이러한 값은, dsound.h 내에서 각각 100, 100,000 으로 정의되고 있다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSoundBuffer ,IDirectSoundBuffer::SetFrequency


IDirectSoundBuffer::GetPan

IDirectSoundBuffer::GetPan 메소드는, 좌우의 오디오 채널의 상대 볼륨을 나타내는 변수를 취득한다.

HRESULT GetPan(
  LPLONG lplPan
);

파라미터

lplPan
좌우의 상대 믹싱율을 보관 유지하는 변수의 주소.

반환값

성공하면 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 으로 정의되고 있다. lplPan 가 0 일 때, 양쪽 모두의 채널이 최대 볼륨인 것을 의미한다 (어느쪽이나 0 dB 의 감쇠이다). DSBPAN_CENTER 이외의 값은 모두, 한편이 최대 볼륨으로 이제(벌써) 한편이 감쇠하고 있는 것을 의미한다.

팬의 값이 -2, 173 때, 왼쪽 채널은 최대 볼륨으로, 오른쪽 채널은 21.73 dB 감쇠하고 있는 것을 의미한다. (와)과 같이 팬의 값이 870 때, 왼쪽 채널은 8.7 dB 감쇠하고 있어, 오른쪽 채널은 최대 볼륨인 것을 의미한다. DSBPAN_LEFT 의 팬은, 오른쪽 채널이 무음으로, 사운드가 왼쪽으로부터 마셔 발생하고 있는 것을 의미한다. 한편, DSBPAN_RIGHT 의 팬은, 왼쪽 채널이 무음으로, 사운드가 오른쪽으로부터 마셔 발생하고 있는 것을 의미한다.

팬 컨트롤의 효과는, 음량 조절에 누적된다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSoundBuffer ,IDirectSoundBuffer::GetVolume ,IDirectSoundBuffer::SetPan ,IDirectSoundBuffer::SetVolume


IDirectSoundBuffer::GetStatus

IDirectSoundBuffer::GetStatus 메소드는, 사운드 버퍼의 현재의 스테이터스를 취득한다.

HRESULT GetStatus(
  LPDWORD lpdwStatus
);

파라미터

lpdwStatus
사운드 버퍼의 스테이터스를 보관 유지하는 변수의 주소. 스테이터스는, 이하의 플래그의 편성이다.
DSBSTATUS_BUFFERLOST
버퍼는 없어지고 있어 재생이나 락을 실시하기 전에 복원하지 않으면 안 된다.
DSBSTATUS_LOOPING
버퍼는 루프 하고 있다. 이 값이 설정되어 있지 않은 경우, 버퍼의 사운드 데이터의 마지막에 달하면(자) 재생은 정지한다. 이 값이 설정되어 있을 때, 버퍼는 반드시 재생되고 있는 점에 주의 해야 한다.
DSBSTATUS_PLAYING
버퍼는 재생중이다. 이 값이 설정되어 있지 않은 경우, 버퍼는 정지하고 있다.
DSBSTATUS_LOCSOFTWARE
소프트웨어의 버퍼는 재생중이다. DSBCAPS_LOCDEFER 플래그로 생성 한 버퍼에만 설정한다.
DSBSTATUS_LOCHARDWARE
하드웨어의 버퍼는 재생중이다. DSBCAPS_LOCDEFER 플래그로 생성 한 버퍼에만 설정한다.
DSBSTATUS_TERMINATED
음성 관리가 버퍼를 빨리 종료해, 버퍼는 정지하고 있다. DSBCAPS_LOCDEFER 플래그로 생성 한 버퍼에만 설정한다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSoundBuffer


IDirectSoundBuffer::GetVolume

IDirectSoundBuffer::GetVolume 메소드는, 사운드 버퍼의 현재의 볼륨을 취득한다.

HRESULT GetVolume(
  LPLONG lplVolume
);

파라미터

lplVolume
지정된 DirectSound 버퍼에 관련지을 수 있었던 볼륨을 보관 유지하는 변수의 주소.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

볼륨은 100 분의 1 데시벨 (dB) 단위로 지정된다. 허용 되는 값은 DSBVOLUME_MAX (감쇠 없음)와 DSBVOLUME_MIN (무음)의 사이이다. 현재 이러한 값은, dsound.h 내에서 각각 0,-10, 000 으로 정의되고 있다. 값 DSBVOLUME_MAX 는, 스트림 본래의 미조정의 볼륨을 나타낸다. 값 DSBVOLUME_MIN 는, 오디오의 볼륨이 100 dB 감쇠하고 있는 것을 나타내지만, 이것은 실제적으로는 무음을 의미한다. 현재, DirectSound 는 증폭을 지원 하고 있지 않다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSoundBuffer ,IDirectSoundBuffer::SetVolume


IDirectSoundBuffer::Initialize

IDirectSoundBuffer::Initialize 메소드는, 초기화되어 있지 않은 DirectSoundBuffer 오브젝트를 초기화한다.

HRESULT Initialize(
  LPDIRECTSOUND lpDirectSound,
  LPCDSBUFFERDESC lpcDSBufferDesc
);

파라미터

lpDirectSound
DirectSoundBuffer 오브젝트에 관련지을 수 있었던 DirectSound 오브젝트의 주소.
lpcDSBufferDesc
이 사운드 버퍼를 초기화하기 위해서 사용되는 값을 보관 유지하는 DSBUFFERDESC 구조체의 주소.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_INVALIDPARAM
DSERR_ALREADYINITIALIZED

주의

IDirectSound::CreateSoundBuffer 메소드는 내부에서 IDirectSoundBuffer::Initialize 를 호출하므로, 현재의 릴리스의 DirectSound 에서는 Initialize 를 명시적으로 호출할 필요는 없다. Initialize 메소드는 장래의 확장성에 대비해 준비되어 있다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

DSBUFFERDESC ,IDirectSound::CreateSoundBuffer ,IDirectSoundBuffer


IDirectSoundBuffer::Lock

IDirectSoundBuffer::Lock 메소드는, 사운드 버퍼의 오디오 데이터에 대한 유효한 쓰기 포인터를 취득한다.

HRESULT Lock(
  DWORD dwWriteCursor,
  DWORD dwWriteBytes,
  LPVOID lplpvAudioPtr1,
  LPDWORD lpdwAudioBytes1,
  LPVOID lplpvAudioPtr2,
  LPDWORD lpdwAudioBytes2,
  DWORD dwFlags
);

파라미터

dwWriteCursor
버퍼의 선두로부터 락 시작 위치까지의 오프셋(offset). 단위는 바이트. dwFlags 파라미터로 DSBLOCK_FROMWRITECURSOR 플래그가 지정되고 있는 경우는, 이 파라미터는 무시된다.
dwWriteBytes
락 되는 버퍼 부분의 사이즈. 단위는 바이트. 사운드 버퍼는 개념적으로는 순환 버퍼인 점에 주의 해야 한다.
lplpvAudioPtr1
락 되는 사운드 버퍼의 최초의 블록을 보관 유지하는 포인터의 주소.
lpdwAudioBytes1
lplpvAudioPtr1 파라미터가 가리키는 바이트수를 보관 유지하는 변수의 주소. 이 값이 dwWriteBytes 파라미터보다 작은 경우,lplpvAudioPtr2 는 사운드 데이터의 2 번째의 블록을 가리킨다.
lplpvAudioPtr2
락 되는 사운드 버퍼의 2 번째의 블록을 보관 유지하는 포인터의 주소. 이 파라미터의 값이 NULL 의 경우,lplpvAudioPtr1 파라미터는 사운드 버퍼의 락 된 부분 전체를 가리킨다.
lpdwAudioBytes2
lplpvAudioPtr2 파라미터가 가리키는 바이트수를 보관 유지하는 변수의 주소. lplpvAudioPtr2 가 NULL 의 경우, 이 값은 0 이 된다.
dwFlags
락 이벤트로 변경을 더하는 플래그. 이하의 플래그가 정의되고 있다.
DSBLOCK_FROMWRITECURSOR
현재 라이트 포지션으로부터 락을 실시한다. 이 결과,IDirectSoundBuffer::GetCurrentPosition 의 호출이 불필요하게 된다. 이 플래그를 지정 하면 dwWriteCursor 파라미터는 무시된다.
DSBLOCK_ENTIREBUFFER
버퍼 전체를 잠근다. dwWriteBytes 파라미터는 무시된다.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

이 메소드는 오프셋(offset)와 바이트 카운트를 받아, 2 개의 쓰기 포인터와 각각 관련하는 사이즈를 돌려준다. 사운드 버퍼가 순환하기 위해(때문에), 2 개의 포인터가 필요하다. 락 된 바이트가 버퍼의 최후로부터 rack-around 하지 않는 (선두에 돌아오지 않는다) 경우, 2 번째의 포인터인 lplpvAudioBytes2 는 NULL 가 된다. 다만, 바이트가 rack-around 하는 경우는, 2 번째의 포인터는 버퍼의 선두를 가리킨다.

어플리케이션이 lplpvAudioPtr2 와 lpdwAudioBytes2 의 각 파라미터에 NULL 를 건네주면(자), DirectSound 는 버퍼의 rack-around 부분을 잠그지 않는다.

어플리케이션은,IDirectSoundBuffer::Lock 메소드가 돌려준 포인터에 데이터를 쓰기,IDirectSoundBuffer::Unlock 메소드를 호출해, 버퍼를 릴리즈 해 DirectSound 에 돌려주어야 하는 것이다. 사운드 버퍼는 장시간에 걸쳐서 락 해서는 안된다. 장시간의 락을 실시하면, 재생 커서가 락 된 부분에 이르러 버려, 기기 구성에 의존하는 랜덤 노이즈등의 오디오의 문제가 발생하는 일이 있다.

경고：이 메소드는, 쓰기 포인터만을 돌려준다. 어플리케이션은, 그 포인터를 사용한 사운드 데이터의 read를 실시해서는 안된다. DirectSoundBuffer 오브젝트가 유효한 사운드 데이터를 보관 유지하고 있는 경우에서도, 그 데이터가 유효하지 않을 가능성이 있다. 예를 들어, 버퍼가 온보드 메모리에 배치되고 있는 경우, 그 포인터는 메인 시스템 메모리내의 일시 버퍼의 주소가 되고 있는 일도 생각할 수 있다. IDirectSoundBuffer::Unlock 를 호출하면, 이 일시 버퍼는 온보드 메모리에 전송 된다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSoundBuffer ,IDirectSoundBuffer::GetCurrentPosition ,IDirectSoundBuffer::Unlock


IDirectSoundBuffer::Play

IDirectSoundBuffer::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
하드웨어 버퍼만으로 음성을 재생한다. 하드웨어에 이용 가능한 음성이 없고, 음성 관리 플래그도 설정되어 있지 않은 경우,IDirectSoundBuffer::Play 에 대한 호출은 실패한다. 이 플래그를 DSBPLAY_LOCSOFTWARE 와 조합할 수 없다.
DSBPLAY_LOCSOFTWARE
소프트웨어 버퍼만으로 음성을 재생한다. 이 플래그를 DSBPLAY_LOCHARDWARE 나 음성 관리 플래그의 어떤 것일까하고 조합할 수 없다.
음성 관리 플래그
음성 관리 플래그는, 버퍼가 DSBCAPS_LOCDEFER 플래그로 생성 되었을 때에 마셔 유효하고, 하드웨어로 재생하는 사운드에 사용된다. 이러한 플래그는, 사용중의 하드웨어 리소스에 현재의 사운드가 주고 받아지도록(듯이) 한다. DSBCAPS_LOCDEFER 플래그로 생성 된 버퍼만이, 빨리 종료되는 후보가 된다. 「주의」를 참조할것.
DSBPLAY_TERMINATEBY_TIME
하드웨어에 이용 가능한 음성이 없는 경우는, 새로운 버퍼용의 빈 곳을 확보하기 위해서 현재 재생중의 버퍼를 정지한다. 빨리 종료되는 버퍼는, 재생의 남은 시간이 가장 적은 버퍼이다.
DSBPLAY_TERMINATEBY_DISTANCE
하드웨어에 이용 가능한 음성이 없는 경우는, 새로운 버퍼용의 빈 곳을 확보하기 위해서 현재 재생중의 버퍼를 정지한다. 빨리 종료되는 버퍼는, DSBCAPS_MUTE3DATMAXDISTANCE 플래그가 세트 되어 최대 거리를 넘고 있는 것의 중으로부터 선택된다. 이러한 버퍼가 없는 경우, 메소드는 실패한다.
DSBPLAY_TERMINATEBY_PRIORITY
하드웨어에 이용 가능한 음성이 없는 경우는, 새로운 버퍼용의 빈 곳을 확보하기 위해서 현재 재생중의 버퍼를 정지한다. 빨리 종료되는 버퍼는,IDirectSoundBuffer::Play 에게 건네지는 dwPriority 파라미터로 설정된 우선도가 가장 낮은 버퍼이다.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_BUFFERLOST
DSERR_HWUNAVAIL
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

IDirectSound::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 | 새로운 사운드의 우선도가 하드웨어로 현재 재생중의 사운드보다 높은가 같은 경우, 우선도의 가장 낮은 사운드를 종료해, 새로운 사운드를 하드웨어로 재생한다. 그 이외의 경우, 이 호출은 실패한다. | 새로운 사운드의 우선도가 하드웨어로 현재 재생중의 사운드보다 높은가 같은 경우, 우선도의 가장 낮은 사운드를 종료해, 새로운 사운드를 하드웨어로 재생한다. 그 이외의 경우는, 새로운 사운드를 소프트웨어로 재생한다. | 새로운 사운드를 소프트웨어로 재생한다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSoundBuffer ,IDirectSound::SetCooperativeLevel


IDirectSoundBuffer::Restore

IDirectSoundBuffer::Restore 메소드는, 지정된 DirectSoundBuffer 오브젝트에 관련지을 수 있고 있던, 없어진 사운드 버퍼에의 메모리 할당을 복원한다.

HRESULT Restore();

파라미터

없음.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

어플리케이션에 입력초점이 놓여지지 않으면IDirectSoundBuffer::Restore 는 성공하지 않는 것이 있다. 예를 들어, 입력초점이 놓여져 있는 어플리케이션이 DSSCL_WRITEPRIMARY (쓰기 우선) 협조 레벨로 설정되어 있는 경우, 다른 어느 어플리케이션도 버퍼를 복원할 수 없다. (와)과 같이 DSSCL_WRITEPRIMARY 협조 레벨의 어플리케이션이 프라이머리 사운드 버퍼를 복원하려면 , 입력초점이 필요하다.

DirectSound 가 버퍼 메모리를 복원한 후, 유효한 사운드 데이터를 쓰기 고칠 필요가 있다. DirectSound 는 메모리를 복원하지만, 메모리의 내용은 복원할 수 없다.

어플리케이션은 버퍼를 지정해 IDirectSoundBuffer::Lock 또는 IDirectSoundBuffer::Play 의 각 메소드를 호출하면, 그 버퍼가 없어지고 있는 경우에 통지를 받게 된다. 버퍼가 없어지고 있는 경우는, 이러한 메소드는 DSERR_BUFFERLOST 를 돌려준다. IDirectSoundBuffer::GetStatus 메소드를 사용해, 사운드 버퍼의 스테이터스의 취득과 DSBSTATUS_BUFFERLOST 플래그의 테스트를 실시할 수도 있다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSoundBuffer ,IDirectSoundBuffer::Lock ,IDirectSoundBuffer::Play ,IDirectSoundBuffer::GetStatus


IDirectSoundBuffer::SetCurrentPosition

IDirectSoundBuffer::SetCurrentPosition 메소드는, 세컨드리 사운드 버퍼의 현재 플레이 포지션을 이동한다.

HRESULT SetCurrentPosition(
  DWORD dwNewPosition
);

파라미터

dwNewPosition
사운드 버퍼의 재생에 사용되는 새로운 위치. 버퍼의 선두로부터의 오프셋(offset)값으로 지정한다. 단위는 바이트.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

프라이머리 사운드 버퍼에 대해서는, 이 메소드를 호출할 수 없다.

버퍼가 재생중 때에 이 메소드를 호출하면, 즉석에서 신규의 위치에 이동해 재생을 속행한다. 버퍼가 정지하고 있는 경우는, 다음에 IDirectSoundBuffer::Play 메소드를 호출했을 때에, 새로운 위치로부터 재생을 시작 한다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSoundBuffer ,IDirectSoundBuffer::GetCurrentPosition ,IDirectSoundBuffer::Play


IDirectSoundBuffer::SetFormat

IDirectSoundBuffer::SetFormat 메소드는, 이 어플리케이션용의 프라이머리 사운드 버퍼의 포맷을 설정한다. 이 어플리케이션에 입력초점이 놓여질 때마다, DirectSound 는 프라이머리 버퍼가 지정된 포맷으로 설정한다.

HRESULT SetFormat(
  LPCWAVEFORMATEX lpcfxFormat
);

파라미터

lpcfxFormat
WAVEFORMATEX 구조체의 주소. 이 구조체는, 프라이머리 사운드 버퍼의 새로운 포맷을 기술한다.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_BADFORMAT
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY
DSERR_PRIOLEVELNEEDED
DSERR_UNSUPPORTED

주의

쓰기 우선 협조 레벨로 액세스 되고 있는 프라이머리 버퍼에 대해서 이 메소드를 호출하는 경우는,IDirectSoundBuffer::SetFormat 를 호출하기 전에 버퍼를 정지해 두지 않으면 안 된다. 쓰기 우선 이외의 협조 레벨의 프라이머리 버퍼에 대해서 이 메소드를 호출하는 경우는, DirectSound 는 프라이머리 버퍼를 명시적으로 정지해, 포맷을 변경해, 프라이머리를 재개한다. 어플리케이션이 이러한 작업을 명시적으로 실시할 필요는 없다.

하드웨어가, 요구된 포맷을 지원 하고 있지 않는 경우에서도, 이 메소드는 성공한다. DirectSound 는 버퍼를, 요구에 가장 가까운 포맷으로 설정해, 요구된 포맷으로 사운드를 믹스 해, 변환한 다음 프라이머리 버퍼에 보낸다. 이러한 상황이 발생하고 있을지 어떨지를 판단하려면 , 어플리케이션은 프라이머리 버퍼에 대해서 IDirectSoundBuffer::GetFormat 메소드를 호출해, 그 결과를,SetFormat 메소드로 요구한 포맷과 비교한다.

어플리케이션이 DSSCL_NORMAL 협조 레벨로 설정되어 있는 경우, 이 메소드의 호출은 실패한다.

이 메소드는 세컨드리 사운드 버퍼에는 유효하지 않다. 세컨드리 사운드 버퍼가 포맷의 변경을 필요로 하는 경우, 어플리케이션은 새로운 포맷을 사용하는 새로운 DirectSoundBuffer 오브젝트를 생성 해야 한다.

DirectSound 는 PCM 포맷을 지원 하고 있다. 현재, 압축 포맷은 지원 하고 있지 않다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSoundBuffer ,IDirectSoundBuffer::GetFormat


IDirectSoundBuffer::SetFrequency

IDirectSoundBuffer::SetFrequency 메소드는, 샘플링 오디오의 재생 주파수를 설정한다.

HRESULT SetFrequency(
  DWORD dwFrequency
);

파라미터

dwFrequency
샘플링 오디오를 재생하는 새로운 주파수로, 단위는 헤르쯔 (Hz)이다. 값의 범위는 DSBFREQUENCY_MIN 로부터 DSBFREQUENCY_MAX 의 사이가 아니면 안된다. 현재 이러한 값은 dsound.h 내에서, 각각 100, 100,000 으로 정의되고 있다.

값이 DSBFREQUENCY_ORIGINAL 의 경우, 주파수는 현재의 버퍼 포맷내의 디폴트값에 리셋 된다. 이 포맷은 IDirectSound::CreateSoundBuffer 메소드로 지정된 것이다.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

주파수를 상하시키면(자), 오디오 데이터의 인식 피치가 변화한다. 이 메소드는 버퍼의 포맷에는 영향을 미치지 않는다.

이 메소드는 프라이머리 사운드 버퍼에는 유효하지 않다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSoundBuffer ,IDirectSound::CreateSoundBuffer ,IDirectSoundBuffer::GetFrequency ,IDirectSoundBuffer::Play ,IDirectSoundBuffer::SetFormat


IDirectSoundBuffer::SetPan

IDirectSoundBuffer::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 으로 정의되고 있다. lplPan 가 0 일 때, 양쪽 모두의 채널이 최대 볼륨인 것을 의미한다 (어느쪽이나 0 dB 의 감쇠이다). DSBPAN_CENTER 이외의 값은 모두, 한편이 최대 볼륨으로 이제(벌써) 한편이 감쇠하고 있는 것을 의미한다.

팬의 값이 -2, 173 때, 왼쪽 채널은 최대 볼륨으로, 오른쪽 채널은 21.73 dB 감쇠하고 있는 것을 의미한다. (와)과 같이 팬의 값이 870 때, 왼쪽 채널은 8.7 dB 감쇠하고 있어, 오른쪽 채널은 최대 볼륨인 것을 의미한다. DSBPAN_LEFT 의 팬은, 오른쪽 채널이 무음으로, 사운드가 왼쪽으로부터 마셔 발생하고 있는 것을 의미한다. 한편, DSBPAN_RIGHT 의 팬은, 왼쪽 채널이 무음으로, 사운드가 오른쪽으로부터 마셔 발생하고 있는 것을 의미한다.

팬 컨트롤의 효과는, 음량 조절에 누적된다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSoundBuffer ,IDirectSoundBuffer::GetPan ,IDirectSoundBuffer::GetVolume ,IDirectSoundBuffer::SetVolume


IDirectSoundBuffer::SetVolume

IDirectSoundBuffer::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 는 증폭을 지원 하고 있지 않다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSoundBuffer ,IDirectSoundBuffer::GetPan ,IDirectSoundBuffer::GetVolume ,IDirectSoundBuffer::SetPan


IDirectSoundBuffer::Stop

IDirectSoundBuffer::Stop 메소드는, 사운드 버퍼의 재생을 정지한다.

HRESULT Stop();

파라미터

없음.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

세컨드리 사운드 버퍼에 대해서 IDirectSoundBuffer::Stop 를 호출하면, 현재의 버퍼의 위치가, 직전에 재생된 샘플의 직후의 샘플로 설정된다. 이것은, 그 버퍼에 대해서 다음에 IDirectSoundBuffer::Play 메소드를 호출하면, 이전에 재생을 정지한 장소로부터 재생이 재개되는 것을 의미한다.

DSSCL_WRITEPRIMARY 레벨로 설정된 어플리케이션이 프라이머리 사운드 버퍼에 대해서 이 메소드를 호출하면, 이 메소드는 버퍼를 정지해, 현재의 포지션을 0 (버퍼의 선두)에 리셋 한다. 대부분의 사운드 카드는 버퍼의 선두로부터 마셔 재생을 실시할 수 있으므로, 이러한 처리가 필요하다.

그러나, 쓰기 우선 이외의 협조 레벨로 설정되어 있는 어플리케이션이, 프라이머리 버퍼에 대해서 IDirectSoundBuffer::Stop 를 호출했을 경우는, 이 메소드는 IDirectSoundBuffer::Play 와는 역의 이펙트를 가져오는 것만으로 있다. 세컨드리 버퍼가 재생되어 있지 않은 경우는 프라이머리 버퍼를 정지하도록(듯이) 설정한다. 이 어플리케이션 또는 다른 어플리케이션이 다른 버퍼를 재생하고 있는 경우, 그러한 재생이 정지할 때까지 프라이머리 버퍼도 실제로는 정지하지 않는다. 비록 진폭이 0 dB 여도, 버퍼가 사운드 데이터를 재생하고 있는 경우는 처리의 오버헤드가 발생하므로, 이 메소드를 사용해 프라이머리 버퍼를 정지하는 것은 도움이 된다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSoundBuffer ,IDirectSoundBuffer::Play


IDirectSoundBuffer::Unlock

IDirectSoundBuffer::Unlock 메소드는, 사운드 버퍼를 언락 한다.

HRESULT Unlock(
  LPVOID lpvAudioPtr1,
  DWORD dwAudioBytes1,
  LPVOID lpvAudioPtr2,
  DWORD dwAudioBytes2
);

파라미터

lpvAudioPtr1
IDirectSoundBuffer::Lock 메소드의 lplpvAudioPtr1 파라미터로 취득한 값의 주소.
dwAudioBytes1
lpvAudioPtr1 파라미터에 실제로 기입해진 바이트수. IDirectSoundBuffer::Lock 메소드가 돌려준 바이트수이하로 해야 한다.
lpvAudioPtr2
IDirectSoundBuffer::Lock 메소드의 lplpvAudioPtr2 파라미터로 취득한 값의 주소.
dwAudioBytes2
lpvAudioPtr2 파라미터에 실제로 기입해진 바이트수. IDirectSoundBuffer::Lock 메소드가 돌려준 바이트수이하로 해야 한다.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

어플리케이션은,IDirectSoundBuffer::Lock 와 IDirectSoundBuffer::Unlock 를 올바르게 조합해,IDirectSoundBuffer::Lock 메소드가 돌려준 포인터 lpvAudioPtr1 와 lpvAudioPtr2 의 양쪽 모두를 IDirectSoundBuffer::Unlock 에 건네주지 않으면 안 된다. 비록 2 번째의 포인터에 0 바이트가 기입해졌을 경우에서도, 2 번째의 포인터는 필요하다.

어플리케이션은 2 개의 포인터에 실제로 기입해진 바이트수를,dwAudioBytes1 와 dwAudioBytes2 의 각 파라미터에 건네주지 않으면 안 된다.

사운드 버퍼의 락 상태를 장시간 유지하지 않게 주의 해야 한다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSoundBuffer ,IDirectSoundBuffer::GetCurrentPosition ,IDirectSoundBuffer::Lock


IDirectSoundCapture 인터페이스

IDirectSoundCapture 인터페이스의 메소드는, 사운드 캡춰 버퍼를 생성 하기 위해서 사용된다.

DirectSoundCaptureCreate 함수를 사용해 이 인터페이스를 취득한다.

IDirectSoundCapture 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

생성 | CreateCaptureBuffer
 | Initialize
능력 | GetCaps

모든 COM 인터페이스와 같게,IDirectSoundCapture 인터페이스도 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUNDCAPTURE 형은,IDirectSoundCapture 인터페이스에의 포인터로서 정의되고 있다.

typedef struct IDirectSoundCapture    *LPDIRECTSOUNDCAPTURE;

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSoundCapture::CreateCaptureBuffer

IDirectSoundCapture::CreateCaptureBuffer 메소드는, 캡춰 버퍼를 생성 한다.

출력의 목적으로 복수의 사운드를 1 개의 사운드에 믹싱 할 수 있는 DirectSound 과는 달리, DirectSoundCapture 는 그 역, 즉 1 개의 입력 사운드로부터 복수의 사운드를 추출할 수 없다. DirectSoundCapture 의 최초의 버젼은, 1 개의 캡춰 디바이스에 대해서, 어느 시점에서도 1 개의 캡춰 버퍼의 존재 밖에 인정하지 않았다.

HRESULT CreateCaptureBuffer(
  LPDSCBUFFERDESC lpDSCBufferDesc,
  LPLPDIRECTSOUNDCAPTUREBUFFER lplpDirectSoundCaptureBuffer,
  LPUNKNOWN pUnkOuter
);

파라미터

lpDSCBufferDesc
DSCBUFFERDESC 구조체에의 포인터. 이 구조체는, 생성 되는 캡춰 버퍼용의 값을 보관 유지하고 있다.
lplpDirectSoundCaptureBuffer
성공의 경우,IDirectSoundCaptureBuffer 인터페이스 포인터의 주소.
pUnkOuter
전체의 IUnknown 의 컨트롤. 이 값은 NULL 가 아니면 안된다.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_INVALIDPARAM
DSERR_BADFORMAT
DSERR_GENERIC
DSERR_NODRIVER
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSoundCapture::GetCaps

IDirectSoundCapture::GetCaps 메소드는, 캡춰 디바이스의 능력을 취득한다.

HRESULT GetCaps(
  LPDSCCAPS lpDSCCaps
);

파라미터

lpDSCCaps
DSCCAPS 구조체에의 포인터. 캡춰 디바이스는, 이 구조체에 쓰기를 실시한다. 이 메소드를 호출하려면 ,dwSize 멤버는 구조체의 사이즈를 바이트 단위로 지정해야 한다.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_INVALIDPARAM
DSERR_UNSUPPORTED
DSERR_NODRIVER
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSoundCapture::Initialize

CoCreateInstance 를 사용해 DirectSoundCapture 오브젝트를 생성 했을 경우,IDirectSoundCapture::Initialize 메소드를 사용해 이 오브젝트를 초기화해야 한다. DirectSoundCaptureCreate 함수를 사용해 오브젝트를 생성 했을 경우는, 이 메소드를 호출할 필요는 없다.

HRESULT Initialize(
  LPCGUID lpcGuid
);

파라미터

lpcGuid
DirectSoundCapture 오브젝트에 결합되는 사운드 드라이버를 지정하는 GUID 의 주소. 프라이머리 사운드 드라이버를 선택하려면 , NULL 또는 GUID_NULL 를 지정한다.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_INVALIDPARAM
DSERR_NODRIVER
DSERR_OUTOFMEMORY
DSERR_ALREADYINITIALIZED

주의

lpcGuid 파라미터는, DirectX 7.0 으로 LPGUID 로부터 LPCGUID 로 변경되었다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSoundCaptureBuffer 인터페이스

IDirectSoundCaptureBuffer 인터페이스의 메소드는, 사운드 캡춰 버퍼를 조작하기 위해서 사용된다.

IDirectSoundCapture::CreateCaptureBuffer 메소드를 호출해 이 인터페이스를 취득한다.

IDirectSoundCaptureBuffer 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

초기화 | Initialize
정보 | GetCaps
 | GetCurrentPosition
 | GetFormat
 | GetStatus
캡춰 관리 | Lock
 | Start
 | Stop
 | Unlock

모든 COM 인터페이스와 같게,IDirectSoundCaptureBuffer 인터페이스도 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUNDCAPTUREBUFFER 형은,IDirectSoundCaptureBuffer 인터페이스에의 포인터로서 정의되고 있다.

typedef struct IDirectSoundCaptureBuffer  *LPDIRECTSOUNDCAPTUREBUFFER;

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSoundCaptureBuffer::GetCaps

IDirectSoundCaptureBuffer::GetCaps 메소드는, DirectSound 캡춰 버퍼의 능력을 돌려준다.

HRESULT GetCaps(
  LPDSCBCAPS lpDSCBCaps
);

파라미터

lpDSCBCaps
DSCBCAPS 구조체에의 포인터. 캡춰 버퍼는, 이 구조체에 쓰기를 실시한다. 입력시에,dwSize 멤버는 구조체의 사이즈를 바이트 단위로 지정해야 한다.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_INVALIDPARAM
DSERR_UNSUPPORTED
DSERR_OUTOFMEMORY

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSoundCaptureBuffer::GetCurrentPosition

IDirectSoundCaptureBuffer::GetCurrentPosition 메소드는, 버퍼내의 현재의 캡춰 위치와 읽어들여 위치를 취득한다.

캡춰 위치는, read 위치에서(보다) 전방에 있다. 물리 디바이스 또는 호스트가 캡춰 데이터를 버퍼링 할 가능성이 있으므로, 이러한 위치는 항상 동일하게 된다고는 할 수 없다. read 위치에서(보다) 다음에 캡춰 위치보다 전의 데이터는 (캡춰 위치를 포함한다), 반드시 유효한 데이터라고는 할 수 없다.

HRESULT GetCurrentPosition(
  LPDWORD lpdwCapturePosition,
  LPDWORD lpdwReadPosition
);

파라미터

lpdwCapturePosition
DirectSoundCaptureBuffer 오브젝트내의 현재의 캡춰 위치를 받는 변수의 주소. 이 정도치는, 캡춰 버퍼내의 오프셋(offset)이며, 바이트 단위로 지정한다. 호출측이 이 정도치정보에 관심이 없는 경우에는, 이 값을 NULL 로 할 수 있다.
lpdwReadPosition
DirectSoundCaptureBuffer 오브젝트내에서, 안전하게 데이터를 읽어들일 수 있는 현재 위치를 받는 변수의 주소. 이 정도치는, 캡춰 버퍼내의 오프셋(offset)이며, 바이트 단위로 지정한다. 호출측이 이 정도치정보에 관심이 없는 경우에는, 이 값을 NULL 로 할 수 있다.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_INVALIDPARAM
DSERR_NODRIVER
DSERR_OUTOFMEMORY

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSoundCaptureBuffer::GetFormat

IDirectSoundCaptureBuffer::GetFormat 메소드는, 사운드 캡춰 버퍼의 현재의 포맷을 취득한다.

HRESULT GetFormat(
  LPWAVEFORMATEX lpwfxFormat,
  DWORD dwSizeAllocated,
  LPDWORD lpdwSizeWritten
);

파라미터

lpwfxFormat
WAVEFORMATEX 변수의 주소. 이 변수는, 캡춰 버퍼내의 사운드 데이터의 기술을 보관 유지하고 있다. 포맷의 기술을 보관 유지하는데 필요한 버퍼 사이즈를 취득하려면 NULL 를 지정한다. 이 경우,lpdwSizeWritten 파라미터가 가리키는 DWORD 가, 완전한 포맷 정보를 받는데 필요한 구조체의 사이즈를 받는다.
dwSizeAllocated
WAVEFORMATEX 구조체의 사이즈. 단위는 바이트. DirectSoundCapture 가 구조체에 기입하는 바이트수는, 최대로 dwSizeAllocated 바이트이다. 구조체가 그것보다 많은 메모리를 필요로 하는 경우, 잘라서 버림을 한다.
lpdwSizeWritten
WAVEFORMATEX 구조체에 기입해진 바이트수를 받는 변수의 주소. 이 파라미터는 NULL 로 해도 괜찮다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSoundCaptureBuffer::GetStatus

IDirectSoundCaptureBuffer::GetStatus 메소드는, 사운드 캡춰 버퍼의 현재의 스테이터스를 취득한다.

HRESULT GetStatus(
  DWORD *lpdwStatus
);

파라미터

lpdwStatus
캡춰 버퍼의 스테이터스를 보관 유지하는 변수의 주소. 스테이터스로서 이하의 값의 1 개 또는 복수를 설정할 수 있다.
DSCBSTATUS_CAPTURING
버퍼는 현재 오디오 데이터를 캡춰 하고 있다.
DSCBSTATUS_LOOPING
버퍼는 현재 루프 하고 있다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSoundCaptureBuffer::Initialize

IDirectSoundCaptureBuffer::Initialize 메소드는, DirectSoundCaptureBuffer 오브젝트가 아직 초기화되어 있지 않은 경우, 이 오브젝트를 초기화한다.

HRESULT Initialize(
  LPDIRECTSOUNDCAPTURE lpDirectSoundCapture,
  LPCDSCBUFFERDESC lpcDSCBufferDesc
);

파라미터

lpDirectSoundCapture
DirectSoundCaptureBuffer 오브젝트에 관련지을 수 있었던 DirectSoundCapture 오브젝트의 주소.
lpcDSCBufferDesc
이 사운드 버퍼를 초기화하기 위해서 사용되는 값을 보관 유지하는 DSBUFFERDESC 구조체의 주소.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_INVALIDPARAM
DSERR_ALREADYINITIALIZED

주의

IDirectSoundCapture::CreateCaptureBuffer 메소드는 내부에서 IDirectSoundCaptureBuffer::Initialize 메소드를 호출하므로, 현재의 릴리스의 DirectSound 에서는 Initialize 를 명시적으로 호출할 필요는 없다. Initialize 메소드는 장래의 확장성에 대비해 준비되어 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

DSBUFFERDESC ,IDirectSoundCapture::CreateCaptureBuffer


IDirectSoundCaptureBuffer::Lock

IDirectSoundCaptureBuffer::Lock 메소드는, 버퍼를 잠근다. 버퍼를 잠그면(자), 그 버퍼에의 포인터가 돌려주어져 어플리케이션이 그 메모리에 대해서 오디오 데이터를 읽고 쓰기할 수 있게 된다.

HRESULT Lock(
  DWORD dwReadCursor,
  DWORD dwReadBytes,
  LPVOID *lplpvAudioPtr1,
  LPDWORD lpdwAudioBytes1,
  LPVOID *lplpvAudioPtr2,
  LPDWORD lpdwAudioBytes2,
  DWORD dwFlags
);

파라미터

dwReadCursor
버퍼의 선두로부터 락 시작 위치까지의 오프셋(offset). 단위는 바이트.
dwReadBytes
락 되는 버퍼 부분의 사이즈. 단위는 바이트. 사운드 캡춰 버퍼는 개념적으로는 순환 버퍼인 점에 주의 해야 한다.
lplpvAudioPtr1
락 되는 사운드 캡춰 버퍼의 최초의 블록을 보관 유지하는 포인터의 주소.
lpdwAudioBytes1
lplpvAudioPtr1 파라미터가 가리키는 바이트수를 보관 유지하는 변수의 주소. 이 값이,dwReadBytes 파라미터보다 작은 경우,lplpvAudioPtr2 는 2 번째의 데이터 블록을 가리킨다.
lplpvAudioPtr2
락 되는 사운드 캡춰 버퍼의 2 번째의 블록을 보관 유지하는 포인터의 주소. 이 파라미터의 값이 NULL 의 경우,lplpvAudioPtr1 파라미터는 사운드 캡춰 버퍼의 락 된 부분 전체를 가리킨다.
lpdwAudioBytes2
lplpvAudioPtr2 파라미터가 가리키는 바이트수를 보관 유지하는 변수의 주소. lplpvAudioPtr2 가 NULL 의 경우, 이 값은 0 이 된다.
dwFlags
락 이벤트로 변경을 더하는 플래그. 이 값은 NULL 또는 다음의 플래그이다.
DSCBLOCK_ENTIREBUFFER
dwReadBytes 파라미터를 무시해, 캡춰 버퍼 전체를 잠근다.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_INVALIDPARAM
DSERR_INVALIDCALL

주의

이 메소드는, 오프셋(offset)와 바이트 카운트를 받아, 2 개의 read 포인터와 각각 관련하는 사이즈를 돌려준다. 사운드 캡춰 버퍼가 순환하기 위해(때문에), 2 개의 포인터가 필요하다. 락 된 바이트가 버퍼의 최후로부터 rack-around 하지 않는 (선두에 돌아오지 않는다) 경우, 2 번째의 포인터인 lplpvAudioBytes2 는 NULL 가 된다. 다만, 바이트가 rack-around 하는 경우는, 2 번째의 포인터는 버퍼의 선두를 가리킨다.

어플리케이션이 lplpvAudioPtr2 와 lpdwAudioBytes2 의 각 파라미터에 NULL 를 건네주면(자), DirectSoundCapture 는, 버퍼의 rack-around 부분을 잠그지 않는다.

어플리케이션은,IDirectSoundCaptureBuffer::Lock 메소드가 돌려준 포인터로부터 데이터를 읽어들여,IDirectSoundCaptureBuffer::Unlock 메소드를 호출해, 버퍼를 릴리즈 해 DirectSoundCapture 에 돌려주어야 하는 것이다. 사운드 버퍼는 장시간에 걸쳐서 락 해서는 안된다. 장시간의 락을 실시하면, 캡춰 커서가 락 된 바이트에 이르러 버려, 기기 구성에 의존하는 오디오의 문제가 발생하는 일이 있다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSoundCaptureBuffer::Start

IDirectSoundCaptureBuffer::Start 메소드는, 캡춰 버퍼를 캡춰 상태에 두어, 버퍼에의 데이터의 캡춰 링을 시작 한다. 캡춰 버퍼가 이미 캡춰 상태에 있는 경우에는, 이 메소드는 아무것도 하지 않는다.

HRESULT Start(
  DWORD dwFlags
);

파라미터

dwFlags
사운드 데이터를 캡춰 링 하면나무의 캡춰 버퍼의 동작을 지정하는 플래그. 다음의 플래그가 정의되고 있다.
DSCBSTART_LOOPING
버퍼의 마지막에 달하면(자), 선두로부터 캡춰를 재개해, 명시적으로 정지될 때까지 속행한다.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_INVALIDPARAM
DSERR_NODRIVER
DSERR_OUTOFMEMORY

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSoundCaptureBuffer::Stop

IDirectSoundCaptureBuffer::Stop 메소드는, 캡춰 버퍼를 「정지」상태에 두어, 데이터의 캡춰를 정지한다. 캡춰 버퍼가 이미 정지상태태에 있는 경우는, 이 메소드는 아무것도 하지 않는다.

HRESULT Stop();

파라미터

없음.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_NODRIVER
DSERR_OUTOFMEMORY

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSoundCaptureBuffer::Unlock

IDirectSoundCaptureBuffer::Unlock 메소드는, 버퍼를 언락 한다.

HRESULT Unlock(
  LPVOID lpvAudioPtr1,
  DWORD dwAudioBytes1,
  LPVOID lpvAudioPtr2,
  DWORD dwAudioBytes2
);

파라미터

lpvAudioPtr1
IDirectSoundCaptureBuffer::Lock 메소드의 lplpvAudioPtr1 파라미터로 취득한 값의 주소.
dwAudioBytes1
lpvAudioPtr1 파라미터로부터 실제로 읽힌 바이트수. IDirectSoundCaptureBuffer::Lock 메소드가 돌려준 바이트수이하로 해야 한다.
lpvAudioPtr2
IDirectSoundCaptureBuffer::Lock 메소드의 lplpvAudioPtr2 파라미터로 취득한 값의 주소.
dwAudioBytes2
lpvAudioPtr2 파라미터로부터 실제로 읽힌 바이트수. IDirectSoundCaptureBuffer::Lock 메소드가 돌려준 바이트수이하로 해야 한다.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_INVALIDPARAM
DSERR_INVALIDCALL

주의

어플리케이션은,IDirectSoundCaptureBuffer::Lock 와 IDirectSoundCaptureBuffer::Unlock 를 올바르게 조합해,IDirectSoundCaptureBuffer::Lock 메소드가 돌려준 2 개의 포인터 lpvAudioPtr1 와 lpvAudioPtr2 의 양쪽 모두를 IDirectSoundCaptureBuffer::Unlock 에 건네주지 않으면 안 된다. 비록 2 번째의 포인터에 0 바이트가 기입해졌을 경우에서도, 2 번째의 포인터는 필요하다.

어플리케이션은 2 개의 포인터에 실제로 기입해진 바이트수를,dwAudioBytes1 와 dwAudioBytes2 의 각 파라미터에 건네주지 않으면 안 된다.

사운드 캡춰 버퍼의 락 상태를 장시간 유지하지 않게 주의 해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSoundNotify 인터페이스

IDirectSoundNotify 인터페이스는, 재생 버퍼나 캡춰 버퍼의 통지 이벤트를 설정하는 메카니즘을 제공한다.

DirectSoundBuffer 오브젝트 위에의 기존의 인터페이스에 대해서 QueryInterface 메소드를 호출해, 이 인터페이스를 취득한다. 구체적인 예에 대해서는, 「재생 버퍼의 통지」를 참조할것.

IDirectSoundNotify 인터페이스는, 다음의 메소드를 지원 한다.

SetNotificationPositions

모든 COM 인터페이스와 같게,IDirectSoundNotify 인터페이스도 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTSOUNDNOTIFY 형은,IDirectSoundNotify 인터페이스에의 포인터로서 정의되고 있다.

typedef struct IDirectSoundNotify    *LPDIRECTSOUNDNOTIFY;

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IDirectSoundNotify::SetNotificationPositions

IDirectSoundCaptureBuffer::SetNotificationPositions 메소드는 통지 위치를 설정한다. 캡춰나 재생동안, 호출측이 공급한 배열내의 DSBPOSITIONNOTIFY 구조체의 어느쪽이든으로 지정되고 있는 오프셋(offset)에 캡춰 위치가 달하면(자), 관련하는 이벤트가 시그널 송신된다. 재생시에는 현재 플레이 포지션을 추적한다. 캡춰시에는 현재의 read 위치를 추적한다.

HRESULT SetNotificationPositions(
  DWORD cPositionNotifies,
  LPCDSBPOSITIONNOTIFY lpcPositionNotifies
);

파라미터

cPositionNotifies
DSBPOSITIONNOTIFY 구조체의 수.
lpcPositionNotifies
DSBPOSITIONNOTIFY 구조체로부터 완성되는 배열에의 포인터.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY

주의

dwOffset 멤버로 값 DSBPN_OFFSETSTOP 를 지정 하면,IDirectSoundBuffer::Stop 나 IDirectSoundCaptureBuffer::Stop 메소드를 호출했을 때, 또는 버퍼의 마지막에 달해 루프 재생을 실시하지 않을 때에, 관련 이벤트를 시그널 송신하도록(듯이) DirectSound 에 지시할 수 있다. 이 값을 사용할 때는, 위치 통지 배열의 마지막 항목으로 해야 한다.

위치 통지 배열이 이미 설정되어 있는 경우, 이 함수를 한번 더 호출하면 이전의 위치 통지 배열을 옮겨놓을 수 있다.

이 메소드를 호출하면나무는, 버퍼를 정지시키지 않으면 안 된다.

주 : VxD 드라이버에서는, 사운드 버퍼가 DSBCAPS_CTRLPOSITIONNOTIFY 로 생성 되는 경우, 이 버퍼는 항상 소프트웨어 버퍼가 된다. 이것은, VxD 드라이버 모델이 통지 인터페이스를 지원 하지 않기 때문이다. 하드웨어가 이용 가능한 경우는, WDM 드라이버에 의해, 위치 통지 가능한 버퍼가 하드웨어에 존재하는 일이 있다.

음성 관리의 TERMINATEBY 플래그와 함께 LOC_DEFER 와 NOTIFY 를 사용하고 있는 경우, 아직 도달하지 않고, 통지 설정을 보관 유지하는 사운드는, 음성 관리에 의해 종료되는 일도 있다. 이 경우, 통지 이벤트는 발생하지 않는다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


IKsPropertySet 인터페이스

IKsPropertySet 인터페이스는, WDM KS (Win32® driver model kernel streaming, Win32® 드라이버 모델의 커널 스트리밍) 아키텍쳐의 일부이다. 드라이버는 이 인터페이스를 사용하는 것으로, API 에 확장을 더하는 일 없이, 이용할 수 있는 확장 기능을 제공하는 것이 가능하게 된다. DirectSound 는, 사운드 드라이버의 프로퍼티에 액세스 할 수 있도록, 이 인터페이스를 지원 한다.

DirectSound 버퍼의 임의의 인터페이스의 QueryInterface 메소드를 호출해, 이 인터페이스를 취득한다.

IKsPropertySet 인터페이스는, 다음의 메소드를 지원 한다.

IKsPropertySet | Get
 | QuerySupport
 | Set

모든 COM 인터페이스와 같게,IKsPropertySet 인터페이스도 IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.


IKsPropertySet::Get

IKsPropertySet::Get 메소드는, 프로퍼티 세트내의 특정의 항목에 대응하는 데이타를 뽑기 시작한다.

HRESULT Get(
  REFGUID rguidPropSet,
  ULONG ulId,
  LPVOID pInstanceData,
  ULONG ulInstanceLength,
  LPVOID pPropertyData,
  ULONG ulDataLength,
  ULONG * pulBytesReturned
);

파라미터

rguidPropSet
액세스 해야 할 프로퍼티 세트를 나타내는 GUID 에의 참조 (C++) 또는 주소 (C).
ulId
액세스 해야 할 프로퍼티 세트내의 항목. 항목은 0 으로부터 시작되는 인덱스 번호를 할당할 수 있고 있어 특정의 프로퍼티 세트 GUID 에서는 항상 같다.
pInstanceData
Get 호출의 대상이 되는 인스턴스 데이터.
ulInstanceLength
pInstanceData 가 가리키는 바이트수.
pPropertyData
이 항목으로부터 취득되는 데이터.
ulDataLength
pPropertyData 가 가리키는 바이트수.
pulBytesReturned
pPropertyData 에 기입해진 바이트수를 받는 변수의 주소.

반환값

반환값은, 프로퍼티 세트의 설계자에 의해 결정된다.

성공하면 S_OK, 실패하면 E_POINTER 를 돌려준다.

주의

pInstanceData 와 pPropertyData 의 각 데이터의 포맷은, 항목 마다 다르다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.


IKsPropertySet::QuerySupport

IKsPropertySet::QuerySupport 메소드는, 프로퍼티 세트내가 있는 프로퍼티가 포트 또는 디바이스에 의해 지원 되고 있는지 어떤지를 결정한다.

HRESULT QuerySupport(
  REFGUID rguidPropSet,
  ULONG ulId,
  ULONG* pulTypeSupport
);

파라미터

rguidPropSet
문의해야 할 프로퍼티 세트를 나타내는 GUID 에의 참조 (C++) 또는 주소 (C).
ulId
액세스 해야 할 프로퍼티 세트내의 항목. 항목은 0 으로부터 시작되는 인덱스 번호를 할당할 수 있고 있어 특정의 프로퍼티 세트 GUID 에서는 항상 같다.
pulTypeSupport
프로퍼티의 지원에 관한 정보를 받는 변수의 주소. 프로퍼티 또는 프로퍼티 세트가 존재하지 않는 경우, 이 값은 0 으로 설정된다. 그 이외의 경우는, 이하의 플래그의 1 개 또는 양쪽 모두를 보관 유지한다.
KSPROPERTY_SUPPORT_GET
프로퍼티 항목은 취득할 수 있다.
KSPROPERTY_SUPPORT_SET
프로퍼티 항목은 설정할 수 있다.

반환값

반환값은, 프로퍼티 세트의 설계자에 의해 결정된다.

성공하면 S_OK ( 「주의」를 참조할것), 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

E_NOTIMPL ( 「주의」를 참조)
E_POINTER

주의

세트내에서 특정의 프로퍼티를 지원 할지 어떨지는, 프로퍼티 세트의 정의에 의존한다. 관심이 있는 프로퍼티 세트에 대해서는, 하드웨어 메이커의 사양을 참조할것.

어느 사양에서는 프로퍼티가 지원되어 있지 않은 경우에 S_OK 를 돌려주어, 다른 사양에서는 E_NOTIMPL 를 돌려준다. 프로퍼티가 지원 되고 있는지 어떤지를 확인하려면 , 이 메소드의 반환값과pulTypeSupport 의 반환값의 양쪽 모두를 체크해야 한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.


IKsPropertySet::Set

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, 실패하면 E_POINTER 를 돌려준다.

주의

pInstanceData 와 pPropertyData 의 각 데이터의 포맷은, 항목 마다 다르다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.


함수

여기에서는, DirectSound 와 DirectSoundCapture 의 이하의 글로벌 함수의 레퍼런스 정보를 제공한다.

  • DirectSoundCaptureCreate
  • DirectSoundCaptureEnumerate
  • DirectSoundCreate
  • DirectSoundEnumerate


DirectSoundCaptureCreate

DirectSoundCaptureCreate 함수는,IDirectSoundCapture 인터페이스를 지원 하는 오브젝트의 생성과 초기화를 실시한다.

HRESULT WINAPI DirectSoundCaptureCreate(
  LPCGUID lpcGUID,
  LPDIRECTSOUNDCAPTURE *lplpDSC,
  LPUNKNOWN pUnkOuter
);

파라미터

lpcGUID
사운드 캡춰 디바이스를 식별하는 GUID 의 주소. 이 파라미터의 값은,DirectSoundCaptureEnumerate 가 돌려준 GUID 의 언젠가, 또는 디폴트의 디바이스를 지정하는 NULL 가 아니면 안된다.
lplpDSC
이 함수가 생성 한 DirectSoundCapture 오브젝트에의 포인터의 주소.
pUnkOuter
전체의 미정도리의 컨트롤. 이 값은 NULL 가 아니면 안된다.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_ALLOCATED
DSERR_INVALIDPARAM
DSERR_NOAGGREGATION
DSERR_OUTOFMEMORY

주의

전이중을 지원 하지 않는 사운드 카드로는, 이 메소드는 실패해, DSERR_ALLOCATED 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


DirectSoundCaptureEnumerate

DirectSoundCaptureEnumerate 함수는, 시스템에 인스톨 되고 있는 DirectSoundCapture 오브젝트를 열거한다.

HRESULT WINAPI DirectSoundCaptureEnumerate(
  LPDSENUMCALLBACK lpDSEnumCallback,
  LPVOID lpContext
);

파라미터

lpDSEnumCallback
DSEnumCallback 함수의 주소. 이 함수는, 시스템에 인스톨 되고 있는 각 DirectSoundCapture 오브젝트에 대해서 불려 간다.
lpContext
유저 정의 문맥의 주소. 열거형 콜백 함수를 호출할 때마다, 그 함수에 이 문맥이 건네받는다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.


DirectSoundCreate

DirectSoundCreate 함수는,IDirectSound 인터페이스의 생성과 초기화를 실시한다.

HRESULT WINAPI DirectSoundCreate(
  LPCGUID lpcGuid,
  LPDIRECTSOUND * ppDS,
  LPUNKNOWN  pUnkOuter
);

파라미터

lpcGuid
사운드 디바이스를 식별하는 GUID 의 주소. 이 파라미터의 값은 DirectSoundEnumerate 가 돌려준 GUID 의 언젠가, 또는 디폴트의 디바이스를 지정하는 NULL 가 아니면 안된다.
ppDS
이 함수가 생성 한 DirectSound 오브젝트에의 포인터의 주소.
pUnkOuter
전체의 미정도리의 컨트롤. 이 값은 NULL 가 아니면 안된다.

반환값

성공하면 DS_OK, 실패하면 다음의 에러값의 어느쪽이든을 돌려준다.

DSERR_ALLOCATED
DSERR_INVALIDPARAM
DSERR_NOAGGREGATION
DSERR_NODRIVER
DSERR_OUTOFMEMORY

주의

어플리케이션은 DirectSound 오브젝트를 생성 한 직후에,IDirectSound::SetCooperativeLevel 메소드를 호출하지 않으면 안 된다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

IDirectSound::GetCaps ,IDirectSound::SetCooperativeLevel


DirectSoundEnumerate

DirectSoundEnumerate 함수는, 시스템에 인스톨 되고 있는 DirectSound 드라이버를 열거한다.

HRESULT WINAPI DirectSoundEnumerate(
  LPDSENUMCALLBACK lpDSEnumCallback,
  LPVOID lpContext
);

파라미터

lpDSEnumCallback
DSEnumCallback 함수의 주소. 이 함수는, 시스템에 인스톨 되고 있는 각 DirectSound 오브젝트에 대해서 불려 간다.
lpContext
유저 정의 문맥의 주소. 열거형 콜백 함수를 호출할 때마다, 그 함수에 이 문맥이 건네받는다.

반환값

성공하면 DS_OK, 실패하면 DSERR_INVALIDPARAM 를 돌려준다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : dsound.lib 를 사용.

참조

DSEnumCallback


콜백 함수

여기에서는, DirectSound 콜백 함수의 레퍼런스 정보를 제공한다.

  • DSEnumCallback


DSEnumCallback

DSEnumCallback 는, DirectSound 드라이버를 열거하는 어플리케이션 정의 콜백 함수이다. 어플리케이션이 직전에 호출한 DirectSoundEnumerate 함수 또는 DirectSoundCaptureEnumerate 함수에 응답해, 시스템은 이 함수를 호출한다.

BOOL CALLBACK DSEnumCallback(
  LPGUID lpGuid,
  LPCSTR lpcstrDescription,
  LPCSTR lpcstrModule,
  LPVOID lpContext
);

파라미터

lpGuid
열거중의 DirectSound 드라이버를 식별하는 GUID 의 주소. 이 값을 DirectSoundCreate 함수에 건네주면(자), 드라이버의 DirectSound 오브젝트를 생성 할 수 있다.
lpcstrDescription
DirectSound 디바이스의 텍스트 기술을 제공하는, NULL 로 끝나는 캐릭터 라인의 주소.
lpcstrModule
이 디바이스에 대응하는 DirectSound 드라이버의 모듈명을 지정하는, NULL 로 끝나는 캐릭터 라인의 주소.
lpContext
어플리케이션 정의 데이터의 주소. 이 데이터는, 각 콜백 함수에 건네받는다.

반환값

드라이버의 열거가 속행하는 경우는 TRUE, 종료하는 경우는 FALSE 를 돌려준다.

주의

어플리케이션은 lpstrDescription 와 lpstrModule 의 각 파라미터에게 건네진 캐릭터 라인을, heap로부터 할당할 수 있었던 메모리에 카피하는 것으로써, 이러한 캐릭터 라인을 보존할 수 있다. 캐릭터 라인을 이 콜백 함수에 건네주는데 사용된 메모리는, 이 콜백 함수가 실행중 때에게만 유효하게 된다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.
임포트 라이브러리 : 유저 정의.

참조

DirectSoundEnumerate


구조체

여기에서는, DirectSound 가 사용하는 이하의 구조체의 레퍼런스 정보를 제공한다.

  • DS3DBUFFER
  • DS3DLISTENER
  • DSBCAPS
  • DSBPOSITIONNOTIFY
  • DSBUFFERDESC
  • DSBUFFERDESC1
  • DSCAPS
  • DSCBCAPS
  • DSCBUFFERDESC
  • DSCCAPS

주 : 모든 DirectX 구조 체용의 메모리는, 사용전에 초기화해야 한다. 더해,dwSize 멤버를 보관 유지하는 구조체에서는, 사용전에 그 멤버를 구조체의 바이트 단위의 사이즈로 설정해야 한다. 다음의 예는, 자주(잘) 사용되는 구조체 DSCAPS 에 대해서 이러한 처리를 실행한다.

DSCAPS dscaps; // 아직 이 구조체는 이용할 수 없다.

ZeroMemory(&dscaps, sizeof(dscaps));
dscaps.dwSize = sizeof(dscaps);

// 이것으로 이 구조체가 이용 가능하게 되었다.
.
.


DS3DBUFFER

DS3DBUFFER 구조체는, 3D 사운드 버퍼의 위치, 방향, 동작을 일의에 기술하기 위해서 필요한 모든 정보를 보관 유지하고 있다. 이 구조체는,IDirectSound3DBuffer::GetAllParameters 와 IDirectSound3DBuffer::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
표준의 처리. 이것은 디폴트의 모드이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.


DS3DLISTENER

DS3DLISTENER 구조체는, 3D 월드 파라미터와 청취자의 위치를 일의에 기술하기 위해서 필요한 모든 정보를 보관 유지하고 있다. 이 구조체는,IDirectSound3DListener::GetAllParameters 와 IDirectSound3DListener::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
각각 현재의 거리 계수, 롤 오프 계수, 돕라 계수.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.


DSBCAPS

DSBCAPS 구조체는 DirectSound 버퍼 오브젝트의 능력을 지정한다. IDirectSoundBuffer::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_CTRLPAN
버퍼는 팬 컨트롤 능력을 갖추고 있다.
DSBCAPS_CTRLVOLUME
버퍼는 음량 조절 능력을 갖추고 있다.
DSBCAPS_CTRLPOSITIONNOTIFY
버퍼는 위치 통지 능력을 갖추고 있다. VxD 드라이버에서는, 이 플래그로 생성 된 사운드 버퍼는 항상 소프트웨어 버퍼가 된다. 이것은, VxD 드라이버 모델이 통지를 지원 하지 않기 때문이다. 하드웨어가 이용 가능한 경우는, WDM 드라이버에 의해, 통지 가능한 버퍼가 하드웨어에 존재하는 일이 있다. 이 플래그는, DSBPLAY_LOCHARDWARE 플래그가 IDirectSoundBuffer::Play 메소드에게 건네졌을 경우에, 메소드가 실패하는 원인이 된다.
DSBCAPS_GETCURRENTPOSITION2
IDirectSoundBuffer::GetCurrentPosition 에서는, 재생 커서의 새로운 동작을 사용해야 하는 것이다. DirectX 1 의 DirectSound 에서는, 에뮬레이트 된 사운드 카드상에서 재생 커서는 실제로 재생되고 있는 사운드보다 아득하게 전방에 있어, 쓰기 커서의 직후에 놓여져 있었다. 이후의 버젼에서는, DSBCAPS_GETCURRENTPOSITION2 플래그를 지정 하면, 어플리케이션은 보다 정확한 재생 위치를 취득할 수 있다. 이 플래그를 지정하지 않는 경우, 호환성을 유지하는 목적으로 이전의 동작이 유지된다. 이 플래그는, 에뮬레이트 된 사운드 카드에게만 영향을 미친다. DirectSound 드라이버가 존재하는 경우, DirectX 목의 버젼에서도, DirectSound 의 재생 커서는 정확한 위치를 나타낸다.
DSBCAPS_GLOBALFOCUS
이 버퍼는 글로벌인 사운드 버퍼이다. 이 플래그를 설정 하면, 유저가 다른 어플리케이션에 포커스를 이동해, 그 새로운 어플리케이션이 DirectSound 를 사용하는 경우에서도, DirectSound 를 사용하고 있는 어플리케이션은 계속해 그 버퍼를 재생할 수 있다. 1 개의 예외는, 협조 레벨로 DSSCL_WRITEPRIMARY 플래그를 설정한 DirectSound 어플리케이션에 포커스를 이동했을 경우이다. 이 경우, 다른 어플리케이션으로부터의 글로벌인 사운드는 들리지 않게 된다.
DSBCAPS_LOCDEFER
재생시, 버퍼는 하드웨어 또는 소프트웨어의 리소스에 할당할 수 있다.
DSBCAPS_LOCHARDWARE
버퍼는 하드웨어 믹싱을 사용한다.
DSBCAPS_LOCSOFTWARE
버퍼는 소프트웨어 메모리내에 있어, 소프트웨어 믹싱을 사용한다.
DSBCAPS_MIXIN
버퍼는 다른 버퍼로부터의 송신을 받을 수가 있다.
DSBCAPS_MUTE3DATMAXDISTANCE
사운드는, 최대 거리로 무음이 된다. 최대 거리를 넘으면(자) 버퍼의 재생이 정지하므로, 프로세서 시간을 소비하고있고로 해결된다.
DSBCAPS_PRIMARYBUFFER
이 버퍼는 프라이머리 사운드 버퍼이다. 이 값을 지정하지 않는 경우, 세컨드리 사운드 버퍼가 생성 된다.
DSBCAPS_STATIC
버퍼는 온보드 하드웨어 메모리에 있다.
DSBCAPS_STICKYFOCUS
버퍼는 스틱키 포커스를 갖추고 있다. 유저가 DirectSound 를 사용하지 않은 다른 어플리케이션으로 전환했을 경우, 버퍼는 계속해 소리를 낸다. 다만, 유저가 다른 DirectSound 어플리케이션으로 전환했을 경우, 버퍼는 무음이 된다.
dwBufferBytes
이 버퍼의 사이즈. 단위는 바이트.
dwUnlockTransferRate
IDirectSoundBuffer::Unlock 를 호출했을 때에 데이터를 버퍼 메모리에 전송 하는 속도. 단위는 1 초 쯤의 킬로바이트 (KB/s). 고성능의 어플리케이션은 이 값을 사용해,IDirectSoundBuffer::Unlock 를 실행하는데 필요한 시간을 결정할 수 있다. 시스템 메모리내에 배치되고 있는 소프트웨어 버퍼의 경우, 처리가 불필요해서 전송 속도는 매우 높다. 하드웨어 버퍼의 경우, 버퍼를 사운드 카드로 로드하지 않으면 안 될 가능성이 있으므로, 전송 속도는 보다 늦어질 가능성이 있다. 그 결과, 전송 속도가 제한되는 일이 있다.
dwPlayCpuOverhead
처리의 오버헤드. 이것은, 사운드 버퍼를 믹싱 하는데 필요한 메인 처리 사이클의 퍼센티지이다. 하드웨어 버퍼의 경우, 사운드 디바이스가 믹싱을 실시하므로, 이 멤버는 0 이다. 소프트웨어 버퍼의 경우, 이 멤버의 값은 버퍼 포맷과 시스템 프로세서의 속도에 의존한다.

주의

DSBCAPS 구조체는,IDirectSound::CreateSoundBuffer 메소드에게 건네지는 DSBUFFERDESC 구조체를 닮은 정보와 그 이외의 몇개의 추가 정보를 보관 유지하고 있다. 추가 정보로서 버퍼의 위치 (하드웨어 또는 소프트웨어)와 몇개의 코스트 측정값, 예를 들어, 버퍼가 하드웨어에 배치되고 있는 경우는 다운로드 시간, 소프트웨어로 버퍼를 믹싱 하는 경우는 재생 처리의 오버헤드등을 들 수 있다.

주 : DSBCAPS 구조체의 dwFlags 멤버가 보관 유지하는 플래그는,DSBUFFERDESC 구조체로 사용되는 플래그와 같은 것이다. 유일한 차이는,DSBCAPS 구조체에서는 버퍼의 장소에 응해 DSBCAPS_LOCHARDWARE 과 DSBCAPS_LOCSOFTWARE 의 어느 쪽인지가 지정되는 것이다. DSBUFFERDESC 구조체에서는 이러한 플래그는 옵션이며, 플래그의 지정에 응해, 버퍼를 하드웨어와 소프트웨어의 어딘가에 강제적으로 배치할 수 있다.

DSBCAPS_CTRLPOSITIONNOTIFY 플래그로 생성 된 사운드 버퍼에는, 통지 이벤트를 설정해야 한다. 이 플래그로 사운드 버퍼를 생성 해, 아무것도 통지를 설정하지 않으면 동작이 정의되지 않고, 사운드가 2 회 재생되는 일이 있다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.

참조

IDirectSound::CreateSoundBuffer ,IDirectSoundBuffer::GetCaps


DSBPOSITIONNOTIFY

DSBPOSITIONNOTIFY 구조체는,IDirectSoundNotify::SetNotificationPositions 메소드에 의해 사용된다.

typedef struct {
    DWORD   dwOffset;
    HANDLE  hEventNotify;
} DSBPOSITIONNOTIFY, *LPDSBPOSITIONNOTIFY;

typedef const DSBPOSITIONNOTIFY *LPCDSBPOSITIONNOTIFY;

멤버

dwOffset
버퍼의 선두로부터, 통지 이벤트가 방아쇠 되는 장소까지의 오프셋(offset), 또는 DSBPN_OFFSETSTOP.
hEventNotify
지정의 오프셋(offset)에 이르렀을 때에 시그널 송신되는 이벤트에의 핸들.

주의

dwOffset 멤버내에서 값 DSBPN_OFFSETSTOP 가 설정되어 있는 경우, 재생 또는 캡춰가 버퍼의 마지막에 달했다 (그리고 재생 또는 캡춰가 루프 하고 있지 않다)인가, 어플리케이션이 IDirectSoundBuffer::Stop 또는 IDirectSoundCaptureBuffer::Stop 의 어느 쪽인가의 메소드를 호출했던 것이 원인으로, 재생 또는 캡춰가 정지 하면, 이벤트가 시그널 송신된다.

주 : 음성 관리의 TERMINATEBY 플래그와 함께 LOC_DEFER 와 NOTIFY 를 사용하고 있는 경우, 아직 도달하지 않고, 통지 설정을 보관 유지하는 사운드는, 음성 관리에 의해 종료되는 일도 있다. 이 경우, 통지 이벤트는 발생하지 않는다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.


DSBUFFERDESC

DSBUFFERDESC 구조체는, 새로운 DirectSoundBuffer 오브젝트의 특징을 나타낸다. 이 구조체는,IDirectSound::CreateSoundBuffer 메소드에 의해 사용된다.

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_CTRLFREQUENCY
버퍼는 주파수 컨트롤 능력을 갖추지 않으면 안 된다.
DSBCAPS_CTRLPAN
버퍼는 팬 컨트롤 능력을 갖추지 않으면 안 된다.
DSBCAPS_CTRLPOSITIONNOTIFY
버퍼는 위치 통지 능력을 갖추지 않으면 안 된다. VxD 드라이버에서는, 사운드 버퍼가 DSBCAPS_CTRLPOSITIONNOTIFY 로 생성 되는 경우, 이 버퍼는 항상 소프트웨어 버퍼가 된다. 하드웨어 버퍼가 이용 가능한 경우, WDM 드라이버에 의해, 통지 가능한 버퍼가 하드웨어에 존재하는 일이 있다. 「주의」를 참조할것.
DSBCAPS_CTRLVOLUME
버퍼는 음량 조절 능력을 갖추지 않으면 안 된다.
DSBCAPS_GETCURRENTPOSITION2
IDirectSoundBuffer::GetCurrentPosition 에서는, 재생 커서의 새로운 동작을 사용해야 하는 것이다. DirectX 1 의 DirectSound 에서는, 에뮬레이트 된 사운드 카드상에서 재생 커서는 실제로 재생되고 있는 사운드보다 아득하게 전방에 있어, 쓰기 커서의 직후에 놓여져 있었다. 이후의 버젼에서는, DSBCAPS_GETCURRENTPOSITION2 플래그를 지정 하면, 어플리케이션은 보다 정확한 재생 위치를 취득할 수 있다. 이 플래그를 지정하고 있지 않는 경우, 호환성을 유지하는 목적으로 이전의 동작이 유지된다. 이 플래그는, 에뮬레이트 된 사운드 카드에게만 영향을 미친다. DirectSound 드라이버가 존재하는 경우, 어느 버젼의 DirectX 에서도 DirectSound 의 재생 커서는 정확한 위치를 나타낸다.
DSBCAPS_GLOBALFOCUS
이 버퍼는 글로벌인 사운드 버퍼이다. 이 플래그를 설정 하면, 유저가 다른 어플리케이션에 포커스를 이동해, 그 새로운 어플리케이션이 DirectSound 를 사용하는 경우에서도, DirectSound 를 사용하고 있는 어플리케이션은 계속해 그 버퍼를 재생할 수 있다. 1 개의 예외는, 협조 레벨로 DSSCL_WRITEPRIMARY 플래그를 설정한 DirectSound 어플리케이션에 포커스를 이동했을 경우이다. 이 경우, 다른 어플리케이션으로부터의 글로벌인 사운드는 들리지 않게 된다.
DSBCAPS_LOCDEFER
재생시, 버퍼는 하드웨어 또는 소프트웨어의 리소스에 할당할 수 있다. 이 플래그는, 음성 관리를 사용하는 버퍼로 설정되지 않으면 안 된다.
DSBCAPS_LOCHARDWARE
버퍼는 하드웨어 믹싱을 사용한다. 디바이스가 하드웨어 믹싱을 지원 하고 있지 않는 경우나, 필요한 하드웨어 메모리가 이용 불가능한 경우는,IDirectSound::CreateSoundBuffer 메소드의 호출은 실패한다. 어플리케이션은, 이 버퍼가 믹싱 채널을 이용 가능하다라고 보증할 필요가 있다. 이 상황은 보증되어 있지 않다.
DSBCAPS_LOCSOFTWARE
DSBCAPS_STATIC 가 지정되고 있어, 하드웨어 리소스가 이용 가능해도, 버퍼를 소프트웨어 메모리에 배치해, 소프트웨어 믹싱을 사용하도록(듯이) 한다.
DSBCAPS_MUTE3DATMAXDISTANCE
사운드는, 최대 거리로 무음이 된다. 최대 거리를 넘으면(자) 버퍼의 재생이 정지하므로, 프로세서 시간을 소비하고있고로 해결된다.
DSBCAPS_PRIMARYBUFFER
이 버퍼는 프라이머리 사운드 버퍼이다. 이 값을 지정하지 않는 경우, 세컨드리 사운드 버퍼가 생성 된다.
DSBCAPS_STATIC
온보드 하드웨어 메모리가 이용 가능한 경우, 버퍼는 거기에 놓여진다. 이러한 메모리를 이용할 수 없는 경우, 에러는 발생하지 않는다. 이것에 대해서 DSBCAPS_LOCHARDWARE 는, 버퍼를 강제적으로 하드웨어 메모리 (아마, 드라이버가 버퍼의 믹싱에 사용하는 시스템 메모리)에 두므로, 이러한 메모리를 이용할 수 없는 경우는 에러를 일으킨다.
DSBCAPS_STICKYFOCUS
버퍼는, 스틱키 포커스를 가지게 된다. 유저가 DirectSound 를 사용하지 않은 다른 어플리케이션으로 전환했을 경우, 어플리케이션의 표준 버퍼는 무음이 되지만, 스틱키 포커스 버퍼는 계속해 소리를 낸다.
dwBufferBytes
새로운 버퍼의 사이즈. 단위는 바이트. 프라이머리 버퍼를 생성 하면나무는, 이 값은 0 이 아니면 안된다. 세컨드리 버퍼로 허용 되는 최소 사이즈와 최대 사이즈는, dsound.h 내에서 정의되는 DSBSIZE_MIN, DSBSIZE_MAX 이다.
dwReserved
이 멤버는 예약되고 있다.
lpwfxFormat
이 버퍼의 웨이브 포맷을 지정하는 구조체의 주소. 프라이머리 버퍼에서는, 이 값은 NULL 가 아니면 안된다. 어플리케이션은 IDirectSoundBuffer::SetFormat 를 사용해, 프라이머리 버퍼의 포맷을 설정할 수 있다.
guid3DAlgorithm
DirectSound3D HEL 가 사용하는 이중 스피커의 가상 알고리즘의 유니크 식별자. 사운드 버퍼에 DSCAPS_CTRL3D 플래그가 설정되어 있지 않은 경우, 이 값은 무시된다. DSBCAPS_CTRL3D 가 dwFlags 로 설정되어 있지 않은 경우, 이 멤버는 GUID_NULL (DS3DALG_DEFAULT)에 해야 한다. DirectX 7.0 이후의 버젼으로 유효. 「주의」를 참조할것.

다음의 알고리즘 식별자가 정의되고 있다.

DS3DALG_DEFAULT
HEL 가 디폴트 알고리즘으로서 설정된다. 현재, 이것은 DS3DALG_NO_VIRTUALIZATION 알고리즘을 선택한다. 이 알고리즘은, 3D 이펙트 이외의 CPU 효율을 제공한다.

소프트웨어 믹싱에만 적용된다. WDM 또는 VxD 드라이버로 이용할 수 있다.

DS3DALG_NO_VIRTUALIZATION
Direct3D API 는, 표준의 좌우 스테레오의 팬에 맵 된다. 왼쪽으로 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 는, 사용하는 특정의 사운드 디바이스에 대해서 최적인 버퍼 사이즈를 결정한다. 생성 된 프라이머리 버퍼의 사이즈를 취득하려면 ,IDirectSoundBuffer::GetCaps 를 호출한다.

DSBCAPS_CTRLDEFAULT 플래그는 이제 지원되어 있지 않다. 이 플래그는, DSBCAPS_CTRLPAN | DSBCAPS_CTRLVOLUME | DSBCAPS_CTRLFREQUENCY 로서 정의되었다. 필요한 플래그만을 지정하는 것으로써, 불필요한 리소스를 줄일 수가 있다.

DSBCAPS_LOCHARDWARE 과 DSBCAPS_LOCSOFTWARE 의 각 플래그는 옵션이며, 서로 배타적이다. DSBCAPS_LOCHARDWARE 는, 강제적으로 버퍼를 하드웨어에 배치한다. 이것은, 버퍼가 사운드 카드에 의해 믹싱 되는 것을 의미한다. DSBCAPS_LOCSOFTWARE 는, 강제적으로 버퍼를 소프트웨어에 배치한다. 이 경우, 버퍼는 CPU 에 의해 믹싱 된다. 이러한 플래그는 DSBCAPS 구조체의 dwFlags 멤버용으로도 정의되고 있다. 이 멤버로 이러한 플래그를 사용하는 경우, 플래그는 DirectSoundBuffer 오브젝트의 실제의 장소를 나타낸다.

3D 알고리즘은, 소프트웨어 에뮬레이션 계층만의 선택을 실시한다. 이것은, 가속화용의 하드웨어가 없는 경우에 사용되는 소프트웨어 알고리즘이다. 하드웨어의 이용을 최대로 하려면 , DS3DALG_NO_VIRTUALIZATION 가 특별한 경우로서 다루어진다. 3D 하드웨어 음성의 빈 곳을 이용할 수 없는 경우, 버퍼는 3D API 컨트롤과 함께 2D 버퍼로서 다루어진다. 특히, 사운드 버퍼를 DS3DALG_NO_VIRTUALIZATION 와 DSBCAPS_LOCDER 로 생성 하는 경우는, 다음의 순서에 따른다.

  • 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 매크로를 사용할 필요가 있다.

DSBCAPS_CTRLPOSITIONNOTIFY 플래그로 생성 된 사운드 버퍼에는, 통지 이벤트를 설정해야 한다. 이 플래그로 사운드 버퍼를 생성 해, 아무것도 통지를 설정하지 않으면 동작은 정의되지 않는다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.

참조

DSBUFFERDESC1


DSBUFFERDESC1

DSBUFFERDESC1 구조체는, 새로운 DirectSoundBuffer 오브젝트의 필수의 특징을 나타낸다. 이 구조체는, DirectX 7.0 이전의 버젼으로 DirectSound 어플리케이션을 생성 할 때,IDirectSound::CreateSoundBuffer 메소드에 의해 사용된다.

typedef struct {
    DWORD           dwSize;
    DWORD           dwFlags;
    DWORD           dwBufferBytes;
    DWORD           dwReserved;
    LPWAVEFORMATEX  lpwfxFormat;
} DSBUFFERDESC, *LPDSBUFFERDESC;

typedef const DSBUFFERDESC *LPCDSBUFFERDESC;

멤버

dwSize
이 구조체의 사이즈. 단위는 바이트. 이 구조체를 사용하기 전에, 이 멤버를 초기화해야 한다.
dwFlags
새로운 DirectSoundBuffer 오브젝트를 생성 할 경우에 포함하는 능력을 식별한다. 이하의 1 개 또는 복수를 지정한다.
DSBCAPS_CTRL3D
이 버퍼는, 3D 컨트롤을 사용하는, 프라이머리 버퍼 또는 세컨드리 버퍼의 어느 쪽인지이다.
DSBCAPS_CTRLFREQUENCY
버퍼는 주파수 컨트롤 능력을 갖추지 않으면 안 된다.
DSBCAPS_CTRLPAN
버퍼는 팬 컨트롤 능력을 갖추지 않으면 안 된다.
DSBCAPS_CTRLPOSITIONNOTIFY
버퍼는 위치 통지 능력을 갖추지 않으면 안 된다. VxD 드라이버에서는, 사운드 버퍼가 DSBCAPS_CTRLPOSITIONNOTIFY 로 생성 되는 경우, 이 버퍼는 항상 소프트웨어 버퍼가 된다. 이것은, VxD 드라이버 모델이 통지 인터페이스를 지원 하지 않기 때문이다. 하드웨어가 이용 가능한 경우, WDM 드라이버에 의해, 위치 통지 가능한 버퍼가 하드웨어에 존재하는 일이 있다. 이 플래그 설정으로 생성 된 버퍼의 재생중은, DSBPLAY_LOCHARDWARE 플래그에 의한 IDirectSoundBuffer::Play 의 호출은 실패한다.
DSBCAPS_CTRLVOLUME
버퍼는 음량 조절 능력을 갖추지 않으면 안 된다.
DSBCAPS_GETCURRENTPOSITION2
IDirectSoundBuffer::GetCurrentPosition 가 재생 커서의 새로운 동작을 사용해야 하는 것인 것을 나타낸다. DirectX 1 의 DirectSound 에서는, 에뮬레이트 된 사운드 카드상에서 재생 커서는 실제로 재생되고 있는 사운드보다 아득하게 전방에 있어, 쓰기 커서의 직후에 놓여져 있었다. 현재는, DSBCAPS_GETCURRENTPOSITION2 플래그를 지정 하면, 어플리케이션은 보다 정확한 재생 위치를 취득할 수 있다. 이 플래그를 지정하고 있지 않는 경우, 호환성을 유지하는 목적으로 과거의 동작이 유지된다. 이 플래그는, 에뮬레이트 된 사운드 카드에게만 영향을 미치는 점에 주의 해야 한다. DirectSound 드라이버가 존재하는 경우, DirectX 목의 버젼에서도, DirectSound 의 재생 커서는 정확한 위치를 나타낸다.
DSBCAPS_GLOBALFOCUS
이 버퍼는 글로벌인 사운드 버퍼이다. 이 플래그를 설정 하면, 유저가 다른 어플리케이션에 포커스를 이동해, 그 새로운 어플리케이션이 DirectSound 를 사용하는 경우에서도, DirectSound 를 사용하고 있는 어플리케이션은 계속해 그 버퍼를 재생할 수 있다. 1 개의 예외는, 협조 레벨로 DSSCL_EXCLUSIVE 또는 DSSCL_WRITEPRIMARY 플래그를 설정한 DirectSound 어플리케이션에 포커스를 이동했을 경우이다. 이 경우, 다른 어플리케이션으로부터의 글로벌인 사운드는 들리지 않게 된다.
DSBCAPS_LOCHARDWARE
DSBCAPS_STATIC 가 지정되어 있지 않은 경우에서도, 강제적으로 버퍼에 하드웨어 믹싱을 사용하게 한다. 디바이스가 하드웨어 믹싱을 지원 하고 있지 않는 경우나, 필요한 하드웨어 메모리가 이용 불가능한 경우는,IDirectSound::CreateSoundBuffer 의 호출은 실패한다. 어플리케이션은, 이 버퍼가 믹싱 채널을 이용 가능하다라고 보증할 필요가 있다. 이 상황은 보증되어 있지 않다.
DSBCAPS_LOCSOFTWARE
DSBCAPS_STATIC 가 지정되고 있어, 하드웨어 리소스가 이용 가능해도, 강제적으로 버퍼를 소프트웨어 메모리에 배치해, 소프트웨어 믹싱을 사용하도록(듯이) 한다.
DSBCAPS_MUTE3DATMAXDISTANCE
사운드는, 최대 거리로 무음이 된다. 최대 거리를 넘으면(자) 버퍼의 재생이 정지하므로, 프로세서 시간을 소비하고있고로 해결된다.
DSBCAPS_PRIMARYBUFFER
이 버퍼가 프라이머리 사운드 버퍼인 것을 나타낸다. 이 값을 지정하지 않는 경우, 세컨드리 사운드 버퍼가 생성 된다.
DSBCAPS_STATIC
이 버퍼를 스태틱 사운드 데이터용으로 사용하는 것을 나타낸다. 일반적으로, 이러한 버퍼는 1 회 로드 되어 몇번이나 재생된다. 이러한 버퍼는 하드웨어 메모리에 배치되는 일이 있다.
DSBCAPS_STICKYFOCUS
사운드 버퍼의 포커스의 동작을 변경한다. IDirectSound::CreateSoundBuffer 를 호출할 때에, 이 플래그를 지정할 수 있다. 이 플래그를 설정 하면, 유저가 DirectSound 를 사용하지 않은 다른 어플리케이션으로 전환했을 경우에서도, DirectSound 를 사용하고 있는 어플리케이션은 스틱키 포커스 버퍼의 재생을 속행할 수 있다. 이 상태로 어플리케이션의 표준 버퍼는 무음이 되지만, 스틱키 포커스 버퍼는 계속해 소리를 낸다. 예를 들어 유저가 Microsoft Word 나 Microsoft Excel 로 입력을 하면서, 게임 이외의 어플리케이션, 예를 들어 영화 재생 (DirectShow ™)으로 사운드 트랙을 (듣)묻고 싶다고 생각하는 경우에 도움이 된다. 그러나, 유저가 다른 DirectSound 어플리케이션으로 전환하면(자), 모든 사운드 버퍼, 이 예에서는 표준 버퍼와 스틱키 포커스 버퍼의 양쪽 모두가 무음이 된다.
dwBufferBytes
새로운 버퍼의 사이즈. 단위는 바이트. 프라이머리 버퍼를 생성 하면나무는, 이 값은 0 이 아니면 안된다. 세컨드리 버퍼로 허용 되는 최소 사이즈와 최대 사이즈는, dsound.h 내에서 정의되는 DSBSIZE_MIN, DSBSIZE_MAX 이다.
dwReserved
이 멤버는 예약되고 있다. 사용하지 않는 것.
lpwfxFormat
이 버퍼의 웨이브 포맷을 지정하는 구조체의 주소. 프라이머리 버퍼에서는, 이 값은 NULL 가 아니면 안된다. 어플리케이션은 IDirectSoundBuffer::SetFormat 를 사용해, 프라이머리 버퍼의 포맷을 설정할 수 있다.

주의

이 구조체는, DirectX 6.1 이전의 버젼만으로 사용 가능하다. DirectX 7.0 으로 호환성이 있는 어플리케이션에서는, DSBUFFERDESC 구조체를 사용할 필요가 있다.

dwFlags 멤버로 사용되는 DSBCAPS_LOCHARDWARE 과 DSBCAPS_LOCSOFTWARE 의 각 플래그는 옵션이며, 서로 배타적이다. DSBCAPS_LOCHARDWARE 는, 강제적으로 버퍼를 사운드 카드의 메모리에 배치한다. DSBCAPS_LOCSOFTWARE 는, 가능하면, 강제적으로 버퍼를 메인 시스템 메모리에 배치한다.

이러한 플래그는 DSBCAPS 구조체의 dwFlags 멤버에서도 사용하도록(듯이) 정의되고 있다. 이 멤버로 이러한 플래그를 사용하는 경우, 플래그는 DirectSoundBuffer 오브젝트의 실제의 장소를 나타낸다.

프라이머리 버퍼를 생성 할 때, 어플리케이션은 dwBufferBytes 멤버를 0 으로 설정해야 한다. DirectSound 는, 사용중의 특정의 사운드 디바이스에 대한 최적인 버퍼 사이즈를 결정한다. 생성 된 프라이머리 버퍼의 크기를 취득하려면 ,IDirectSoundBuffer::GetCaps 를 호출한다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.

참조

IDirectSound::CreateSoundBuffer


DSCAPS

DSCAPS 구조체는, DirectSound 디바이스의 능력을 지정한다. IDirectSound::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
디바이스의 능력을 지정한다. 이하의 1 개 또는 복수를 지정할 수 있다.
DSCAPS_CERTIFIED
이 드라이버는 Microsoft 에 의해 시험과 보증을 하고 있다.
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, dwFreeHwMixingStaticBuffers, dwFreeHwMixingStreamingBuffers
비어 또는 미할당의 디바이스의 하드웨어 믹싱 능력의 기술. 어플리케이션은 이러한 값을 사용해, 세컨드리 사운드 버퍼의 할당에 하드웨어 리소스가 이용 가능한가 어떤가를 판단할 수 있다. 또, 최대의 믹싱 능력을 지정하는 멤버와 이러한 값을 비교 하면, 이미 할당할 수 있고 있는 리소스를 결정할 수 있다. 「주의」를 참조할것.
dwMaxHw3DallBuffers, dwMaxHw3DstaticBuffers, dwMaxHw3DStreamingBuffers
디바이스의 하드웨어 3D 정정도 능력의 기술.
dwFreeHw3DallBuffers, dwFreeHw3DstaticBuffers, dwFreeHw3DStreamingBuffers
비어 또는 미할당의 디바이스의 하드웨어 3D 정정도 능력의 기술. 「주의」를 참조할것.
dwTotalHwMemBytes
스태틱 사운드 버퍼를 보관 유지하는 사운드 카드 위에의 메모리 용량의 사이즈. 단위는 바이트.
dwFreeHwMemBytes
사운드 카드 건성나무 메모리의 사이즈. 단위는 바이트.
dwMaxContigFreeHwMemBytes
사운드 카드 건성나무 메모리 가운데, 최대의 연속 블록의 사이즈. 단위는 바이트.
dwUnlockTransferRateHwBuffers
하드웨어 스태틱 사운드 버퍼에의 데이터 전송 속도. 단위는 1 초 쯤의 킬로바이트 (KB/s). 이 속도와 전송 바이트수에 의해,IDirectSoundBuffer::Unlock 메소드를 호출했을 때의 실행 시간이 정해진다.
dwPlayCpuOverheadSwBuffers
(메인 시스템 메모리내의) 소프트웨어 버퍼를 믹싱 하는데 필요한 처리 오버헤드를, CPU 퍼센티지로 기술한 값. 이 값은, 버스 타입, 프로세서 타입, 클럭 속도에 응해 변화한다.

소프트웨어 버퍼의 언락 전송 속도는 0 이다. 데이터를 어디에도 전송 할 필요가 없기 때문에이다. 같이 하드웨어 버퍼의 재생 오버헤드도, 믹싱이 사운드 디바이스에 의해 처리되기 (위해)때문에, 0 이다.

dwReserved1,dwReserved2
장래의 사용에 예약.

주의

몇개의 오디오 사운드 카드는, 이용 가능한 하드웨어 버퍼나 그 빈 곳을 정확하게 보고할 수 없는 경우가 있다. 이것은 예를 들어, 카드가, 높은 샘플링 레이트보다 낮은 샘플링 레이트로 보다 많은 사운드를 재생할 수 있을 때 발생한다. 보통, 하드웨어 버퍼의 빈수에 관계하는 멤버의 값이 0 이외 때, 적절한 타입의 하드웨어 리소스가 적어도 1 개(살) 이용할 수 있는 것을 나타낸다.

동작환경

Windows NT/2000 : Service Pack 3 을 적용한 Windows NT 버젼 4.0 이후가 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.

참조

IDirectSound::GetCaps


DSCBCAPS

DSCBCAPS 구조체는,IDirectSoundCaptureBuffer::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
장래의 사용에 예약.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.


DSCBUFFERDESC

DSCBUFFERDESC 구조체는,IDirectSoundCapture::CreateCaptureBuffer 메소드에 의해 사용된다.

typedef struct {
    DWORD           dwSize;
    DWORD           dwFlags;
    DWORD           dwBufferBytes;
    DWORD           dwReserved;
    LPWAVEFORMATEX  lpwfxFormat;
} DSCBUFFERDESC, *LPDSCBUFFERDESC;

typedef const DSCBUFFERDESC *LPCDSCBUFFERDESC;

멤버

dwSize
이 구조체의 사이즈. 단위는 바이트. 이 구조체를 사용하기 전에, 이 멤버를 초기화해야 한다.
dwFlags
디바이스의 능력을 지정한다. 0 또는 다음의 플래그를 지정한다.
DSCBCAPS_WAVEMAPPED
이 디바이스가 지원 하지 않는 포맷에 대해서, Win32 웨이브 맵퍼를 사용한다.
dwBufferBytes
생성 되는 캡춰 버퍼의 사이즈. 단위는 바이트.
dwReserved
장래의 사용에 예약.
lpwfxFormat
데이터의 캡춰에 사용하는 포맷을 보관 유지하는 WAVEFORMATEX 구조체에의 포인터.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.


DSCCAPS

DSCCAPS 구조체는,IDirectSoundCapture::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 드라이버이다.
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 는 스테레오를 의미한다. 이하 같이이다.

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dsound.h 로 선언.


반환값

에러는 부의 값으로 나타내져 짜 합쳐질 것은 없다. 이 표는,IDirectSound 와 IDirectSoundBuffer 의 모든 메소드가 돌려줄 가능성이 있는 값의 일람이다. 개별의 메소드가 돌려주는 에러 코드의 리스트에 대해서는, 그 메소드의 기술을 참조할것.

DS_OK
요구는 성공해 완료했다.
DSERR_ACCESSDENIED
액세스가 거부되었기 때문에, 요구는 실패했다.
DSERR_ALLOCATED
우선 레벨등의 리소스가 다른 호출에 의해 이미 사용중이기 (위해)때문에, 요구는 실패했다.
DSERR_ALREADYINITIALIZED
오브젝트는 이미 초기화되고 있다.
DSERR_BADFORMAT
지정한 웨이브 포맷은 지원되어 있지 않다.
DSERR_BUFFERLOST
버퍼 메모리가 없어졌기 때문에, 복원하지 않으면 안 된다.
DSERR_CONTROLUNAVAIL
호출원이 요구하는 버퍼 컨트롤 (볼륨, 팬등)은 이용할 수 없다.
DSERR_GENERIC
DirectSound 서브 시스템내에서 불확정의 에러가 발생했다.
DSERR_HWUNAVAIL
DirectSound 하드웨어 디바이스는 이용 불가능하다.
DSERR_INVALIDCALL
이 오브젝트의 현재 상태에서는, 이 함수는 유효하지 않다.
DSERR_INVALIDPARAM
무효인 파라미터가 함수에게 건네졌다.
DSERR_NOAGGREGATION
이 오브젝트는 COM 집합화를 지원 하지 않는다.
DSERR_NODRIVER
이용 가능한 사운드 드라이버가 존재하지 않는다.
DSERR_NOINTERFACE
요구된 COM 인터페이스는 이용할 수 없다.
DSERR_OTHERAPPHASPRIO
다른 어플리케이션이 보다 높은 우선 레벨을 가지고 있기 (위해)때문에, 이 호출은 성공하지 않았다.
DSERR_OUTOFMEMORY
DirectSound 서브 시스템은, 호출원의 요구를 완료하기 위한 충분한 메모리를 할당할 수 없었다.
DSERR_PRIOLEVELNEEDED
호출원래는, 함수를 성공시키기 위해서(때문에) 필요한 우선 레벨을 가지고 있지 않다.
DSERR_UNINITIALIZED
다른 메소드를 호출하기 전에 IDirectSound::Initialize 메소드를 호출하지 않았는지, 호출이 성공하지 않았다.
DSERR_UNSUPPORTED
호출한 함수는 이 시점에서는 지원되어 있지 않다.


DirectSound Visual Basic 레퍼런스

여기에서는, Microsoft® Visual Basic® 에 있어서의 Microsoft® DirectSound® 의 API 요소의 레퍼런스 정보를 기술한다. 레퍼런스 정보는 이하의 카테고리로 분류된다.

  • 클래스
  • 형
  • 열거
  • 에러 코드


클래스

여기에서는, 이하의 DirectSound 클래스의 레퍼런스를 기술한다.

  • DirectSound
  • DirectSound3DBuffer
  • DirectSound3DListener
  • DirectSoundBuffer
  • DirectSoundCapture
  • DirectSoundCaptureBuffer
  • DirectSoundEnum


DirectSound 클래스

어플리케이션은 DirectSound 클래스의 메소드를 사용해,DirectSound 오브젝트의 생성과 환경 설정을 실시한다. 여기에서는,DirectSound 클래스의 메소드의 레퍼런스를 제공한다.

이 오브젝트는,DirectX7.DirectSoundCreate 함수를 사용해 취득한다.

DirectSound 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

초기화 | SetCooperativeLevel
버퍼 생성 | CreateSoundBuffer
 | CreateSoundBufferFromFile
 | CreateSoundBufferFromResource
 | DuplicateSoundBuffer
디바이스의 능력 | GetCaps
스피커의 구성 | GetSpeakerConfig
 | SetSpeakerConfig


DirectSound.CreateSoundBuffer

DirectSound.CreateSoundBuffer 메소드는, 샘플링 오디오의 순서를 보관 유지하기 위한 DirectSoundBuffer 오브젝트를 생성 한다.

object. CreateSoundBuffer(bufferDesc As DSBUFFERDESC, _
    format As WAVEFORMATEX) As DirectSoundBuffer

파라미터

object
DirectSound 오브젝트를 나타내는오브젝트식.
bufferDesc
생성 하는 사운드 버퍼의 기술을 지정하는 DSBUFFERDESC 형.
format
버퍼가 재생하는 데이터의 포맷을 지정하는 WAVEFORMATEX 형.

반환값

성공하면 DirectSoundBuffer 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_ALLOCATED
DSERR_BADFORMAT
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

참조

DirectSound.CreateSoundBufferFromFile ,DirectSound.CreateSoundBufferFromResource ,DirectSound.DuplicateSoundBuffer


DirectSound.CreateSoundBufferFromFile

DirectSound.CreateSoundBufferFromFile 메소드는, 샘플링 오디오의 순서를 보관 유지하기 위한 DirectSoundBuffer 오브젝트를 생성 해, 파일로부터의 데이터를 버퍼에 로드한다.

object. CreateSoundBufferFromFile(filename As String, _
    bufferDesc As DSBUFFERDESC, _
    format As WAVEFORMATEX) As DirectSoundBuffer

파라미터

object
DirectSound 오브젝트를 나타내는오브젝트식.
filename
생성 한 버퍼에 로드하는 웨이브 파일명.
bufferDesc
생성 하는 사운드 버퍼의 기술을 지정하는 DSBUFFERDESC 형. lBufferBytes 멤버는 무시된다.
format
파일의 웨이브 포맷의 정보를 받는 WAVEFORMATEX 형. 메소드에 이 형태를 건네주기 전에 멤버를 초기화할 필요는 없다.

반환값

성공하면 DirectSoundBuffer 를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_ALLOCATED
DSERR_BADFORMAT
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

참조

DirectSound.CreateSoundBuffer ,DirectSound.CreateSoundBufferFromResource ,DirectSound.DuplicateSoundBuffer


DirectSound.CreateSoundBufferFromResource

DirectSound.CreateSoundBufferFromResource 메소드는, 샘플링 오디오의 순서를 보관 유지하는 DirectSoundBuffer 오브젝트를 생성 해, 리소스로부터의 데이터를 버퍼에 로드한다. 사운드 리소스는, WAV 혹은 WAVE 의 어느 쪽인가의 타입이 아니면 안된다.

object. CreateSoundBufferFromResource( _
    dll As String, _
    resourceName As String, _
    bufferDesc As DSBUFFERDESC, _
    format As WAVEFORMATEX) As DirectSoundBuffer

파라미터

object
DirectSound 오브젝트를 나타내는오브젝트식.
dll
리소스나, 리소스를 실행 가능 파일에 포함한 경우의 하늘의 캐릭터 라인을 포함한 DLL 명.
resourceName
생성 된 사운드 버퍼에 로드하는 리소스명.
bufferDesc
생성 하는 사운드 버퍼의 기술을 지정하는 DSBUFFERDESC 형. lBufferBytes 멤버는 무시된다.
format
리소스의 웨이브 포맷의 정보를 받는 WAVEFORMATEX 형. 메소드에 이 형태를 건네주기 전에 멤버를 초기화할 필요는 없다.

반환값

성공하면 DirectSoundBuffer 를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_ALLOCATED
DSERR_BADFORMAT
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

참조

DirectSound.CreateSoundBuffer ,DirectSound.CreateSoundBufferFromFile ,DirectSound.DuplicateSoundBuffer


DirectSound.DuplicateSoundBuffer

DirectSound.DuplicateSoundBuffer 메소드는, 새로운 DirectSoundBuffer 오브젝트를 생성 한다. 이 오브젝트는, 오리지날의 오브젝트와 같은 버퍼 메모리를 사용한다.

object. DuplicateSoundBuffer( _
    original As DirectSoundBuffer) _
    As DirectSoundBuffer

파라미터

object
DirectSound 오브젝트를 나타내는오브젝트식.
original
복제하는 DirectSoundBuffer 오브젝트.

반환값

성공하면 DirectSoundBuffer 를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_ALLOCATED
DSERR_INVALIDCALL
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED

주의

새로운 오브젝트는 오리지날의 오브젝트와 같은 방법으로 사용할 수 있다.

복제 직후의 버퍼는, 오리지날 버퍼와 같은 파라미터를 가진다. 다만, 어플리케이션은 각 버퍼의 파라미터를 개별적으로 변경할 수 있어 각 버퍼는 서로 영향을 미치는 일 없이 재생과 정지를 실시할 수 있다.

어느 쪽인가의 오브젝트가 버퍼내의 데이터를 변경 하면, 버퍼 메모리가 공유되고 있기 (위해)때문에, 보통 그 변경은 이제(벌써) 한편의 오브젝트에도 반영된다. 다만, 몇개의 환경에서는 복제 버퍼가 고유의 메모리를 보관 유지하기 위해(때문에), 이 동작을에게 해서는 안된다.

후에 남은 참조측 오브젝트가 릴리즈 되면(자), 버퍼 메모리는 릴리즈 된다.

어플리케이션은, 사운드 버퍼의 복제 작업이 성공한다고는 상정할 수 없다. 특히, DirectSound 는 하드웨어 버퍼의 소프트웨어 복제를 생성 할 수 없다.

참조

DirectSound.CreateSoundBuffer ,DirectSound.CreateSoundBufferFromFile ,DirectSound.CreateSoundBufferFromResource


DirectSound.GetCaps

DirectSound.GetCaps 메소드는,DirectSound 오브젝트로서 나타내지고 있는 하드웨어 디바이스의 능력을 취득한다.

object. GetCaps(caps As DSCAPS)

파라미터

object
DirectSound 오브젝트를 나타내는오브젝트식.
caps
사운드 디바이스의 능력을 보관 유지하고 있는 DSCAPS 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_GENERIC
DSERR_UNINITIALIZED

주의

DSCAPS 형에 보관 유지되고 있는 정보는, 하드웨어 믹싱 채널의 수, 온보드 사운드 메모리의 용량 등, 사운드 디바이스의 최대 능력과 현재 사용 가능한 능력을 기술한다. 이러한 정보를 사용해 성능을 조정해, 리소스의 할당을 최적화할 수 있다.

리소스의 공유가 전제가 되고 있기 (위해)때문에, 어느 분야에서 최대의 능력을 이용 하면, 다른 분야가 그 영향을 받는 일이 있다. 예를 들어, 하드웨어 스태틱 사운드 버퍼가 1 개나 이용할 수 없는 경우는, 최대수의 스트림 사운드 버퍼의 하드웨어 믹싱이 사용 가능하게 된다.

참조

DirectX7.DirectSoundCreate


DirectSound.GetSpeakerConfig

DirectSound.GetSpeakerConfig 메소드는,DirectSound 오브젝트에 할당할 수 있었던 스피커의 구성을 취득한다.

object. GetSpeakerConfig() As CONST_DSSPEAKERFLAGS

파라미터

object
DirectSound 오브젝트를 나타내는오브젝트식.

반환값

성공하면 CONST_DSSPEAKERFLAGS 열거의 정수의 1 개 또는 복수를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_INVALIDPARAM
DSERR_UNINITIALIZED

주의

스피커의 지오메트리는 디폴트로 0 으로 설정된다. 이것은, 스피커의 지오메트리가 미정도리 상태이다. 지오메트리는,DirectSound.SetSpeakerConfig 메소드를 사용해 DSSPEAKER_STEREO 플래그에 스피커의 지오메트리 플래그의 1 개를 건네주는 것으로, 명시적으로 설정해야 한다.

참조

DirectSound.SetSpeakerConfig


DirectSound.SetCooperativeLevel

DirectSound.SetCooperativeLevel 메소드는, 이 사운드 디바이스의 어플리케이션 협조 레벨을 설정한다.

object. SetCooperativeLevel(hwnd As Long, _
    level As CONST_DSSCLFLAGS)

파라미터

object
DirectSound 오브젝트를 나타내는오브젝트식.
hwnd
어플리케이션에의 윈도우 핸들. 「주의」를 참조할것.
level
요구되는 우선 레벨. CONST_DSSCLFLAGS 열거의 정수가 아니면 안된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_ALLOCATED
DSERR_INVALIDPARAM
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

주의

어플리케이션은 버퍼를 재생하기 전에, 이 메소드를 호출해 협조 레벨을 설정해야 한다. 추천 되는 협조 레벨은 DSSCL_PRIORITY 이며, 다른 우선 레벨은 필요에 따라서 사용한다.

hwnd 파라미터는, 최상정도의 어플리케이션 윈도우 핸들로 해야 한다. DirectDraw 도 사용하고 있는 경우는,DirectDraw7.SetCooperativeLevel 메소드에 건네준 것과 같은 핸들을 지정해야 한다.


DirectSound.SetSpeakerConfig

DirectSound.SetSpeakerConfig 메소드는,DirectSound 오브젝트의 스피커 구성을 지정한다.

object. SetSpeakerConfig( _
    speakerConfig As CONST_DSSPEAKERFLAGS)

파라미터

object
DirectSound 오브젝트를 나타내는오브젝트식.
speakerConfig
DirectSound 오브젝트의 스피커 구성. CONST_DSSPEAKERFLAGS 열거의 정수의 1 개 또는 복수를 지정해야 한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_INVALIDPARAM
DSERR_UNINITIALIZED

주의

스피커의 지오메트리는 디폴트로 0 으로 설정된다. 이것은, 스피커의 지오메트리가 미정도리 상태이다. 지오메트리는, DSSPEAKER_STEREO 플래그와 조합한 스피커의 지오메트리 플래그의 1 개를 건네주는 것으로, 명시적으로 설정해야 한다.

참조

DirectSound.GetSpeakerConfig


DirectSound3Dbuffer 클래스

어플리케이션은 DirectSound3DBuffer 클래스의 메소드를 사용해, 3D 공간에 있어서의 사운드 버퍼의 위치, 방향, 환경을 기술하는 파라미터의 취득과 설정을 실시한다. 여기에서는, DirectSound3Dbuffer 클래스의 메소드의 레퍼런스를 제공한다.

DirectSound3DBuffer 는, 3D 능력으로 생성 된 세컨드리 버퍼의 DirectSoundBuffer.GetDirectSound3DBuffer 메소드를 사용해 취득한다.

DirectSound3DBuffer 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

배치 파라미터 조작 | GetAllParameters
 | SetAllParameters
거리 | GetMaxDistance
 | GetMinDistance
 | SetMaxDistance
 | SetMinDistance
취득 오브젝트 | GetDirectSound3DListener
 | GetDirectSoundBuffer
조작 모드 | GetMode
 | SetMode
위치 | GetPosition
 | SetPosition
사운드 프로젝션 콘 | GetConeAngles
 | GetConeOrientation
 | GetConeOutsideVolume
 | SetConeAngles
 | SetConeOrientation
 | SetConeOutsideVolume
속도 | GetVelocity
 | SetVelocity


DirectSound3DBuffer.GetAllParameters

DirectSound3DBuffer.GetAllParameters 메소드는, 사운드 버퍼의 3D 특성에 관한 정보를 취득한다.

object. GetAllParameters(buffer As DS3DBUFFER)

파라미터

object
DirectSound3DBuffer 오브젝트를 나타내는오브젝트식.
buffer
사운드 버퍼의 3D 특성의 기술을 받는 DS3DBUFFER 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.


DirectSound3DBuffer.GetConeAngles

DirectSound3DBuffer.GetConeAngles 메소드는, 사운드 버퍼의 사운드 프로젝션 콘의 내부 각도와 외부 각도를 취득한다.

object. GetConeAngles(inCone As Long, _
    outCone As Long)

파라미터

object
DirectSound3DBuffer 오브젝트를 나타내는오브젝트식.
inCone
사운드 프로젝션 콘의 내부 각도를 받는 변수. 단위는 번 (˚).
outCone
사운드 프로젝션 콘의 외부 각도를 받는 변수. 단위는 번 (˚).

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

최소, 최대, 디폴트의 각 콘 각도는 각각 DS3D_MINCONEANGLE, DS3D_MAXCONEANGLE, DS3D_DEFAULTCONEANGLE 로서 정의된다.


DirectSound3DBuffer.GetConeOrientation

DirectSound3DBuffer.GetConeOrientation 메소드는, 사운드 버퍼의 사운드 프로젝션 콘의 방향을 취득한다.

object. GetConeOrientation(orientation As D3DVECTOR)

파라미터

object
DirectSound3DBuffer 오브젝트를 나타내는오브젝트식.
orientation
사운드 프로젝션 콘의 현재의 방향을 받는 D3DVECTOR 형. 벡터 정보는 사운드 콘의 중심을 나타낸다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

반환값은 반드시 DirectSound3DBuffer.SetConeOrientation 메소드를 사용해 설정한 것과 같은 값은 아니다. DirectSound 는 방향 벡터에 조정을 더해 그러한 크기를 1.0 이하로 한다.

참조

DirectSound3DBuffer.SetConeOrientation ,DirectSound3DBuffer.SetConeAngles ,DirectSound3DBuffer.SetConeOutsideVolume


DirectSound3DBuffer.GetConeOutsideVolume

DirectSound3DBuffer.GetConeOutsideVolume 메소드는, 사운드 버퍼의 현재의 콘 외부 볼륨을 취득한다.

object. GetConeOutsideVolume() As Long

파라미터

object
DirectSound3DBuffer 오브젝트를 나타내는오브젝트식.

반환값

성공하면 이 사운드 버퍼의 현재의 콘 외부 볼륨을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

볼륨 레벨은 감쇠에 의해 나타내진다. 허용 되는 값은 DSBVOLUME_MAX (감쇠 없음)와 DSBVOLUME_MIN (무음)의 사이이다. 디폴트값은 DS3D_DEFAULTCONEOUTSIDEVOLUME (감쇠 없음)이다. DirectSound 는 증폭을 지원 하고 있지 않다.


DirectSound3DBuffer.GetDirectSound3DListener

DirectSound3DBuffer.GetDirectSound3DListener 메소드는,DirectSound3DListener 오브젝트를 돌려준다.

object. GetDirectSound3DListener() As DirectSound3DListener

파라미터

object
DirectSound3DBuffer 오브젝트를 나타내는오브젝트식.

반환값

성공하면 DirectSound3DListener 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 E_NOINTERFACE 가 설정된다.

주의

이 메소드는, 프라이머리 버퍼를 나타내는 DirectSoundBuffer 로부터 취득된 DirectSound3DBuffer 로부터의 청취자의 취득에 사용된다. 많은 어플리케이션은 DirectSoundBuffer.GetDirectSound3DListener 를 호출해, 프라이머리 버퍼를 나타내는 오브젝트로부터 직접 청취자를 취득한다.


DirectSound3DBuffer.GetDirectSoundBuffer

DirectSound3DBuffer.GetDirectSoundBuffer 메소드는,DirectSoundBuffer 오브젝트를 돌려준다.

object. GetDirectSoundBuffer() As DirectSoundBuffer

파라미터

object
DirectSound3DBuffer 오브젝트를 나타내는오브젝트식.

반환값

성공하면 DirectSoundBuffer 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

이 메소드는,DirectSound3DBuffer 오브젝트를 취득한 DirectSoundBuffer 를 이미 이용할 수 없는 경우,DirectSoundBuffer 를 취득하는데 사용된다.


DirectSound3DBuffer.GetMaxDistance

DirectSound3DBuffer.GetMaxDistance 메소드는, 사운드 버퍼의 현재의 최대 거리를 취득한다. 이것은, 볼륨이 그 이상 감쇠하지 않게 되는 거리이다.

object. GetMaxDistance() As Single

파라미터

object
DirectSound3DBuffer 오브젝트를 나타내는오브젝트식.

반환값

성공하면 현재의 최대 거리의 설정값을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

디폴트의 최대 거리는 DS3D_DEFAULTMAXDISTANCE 에 의해 정의되어 실질적으로 무한대이다.

참조

DirectSound3DBuffer.GetMinDistance ,DirectSound3DBuffer.SetMaxDistance


DirectSound3DBuffer.GetMinDistance

DirectSound3DBuffer.GetMinDistance 메소드는, 사운드 버퍼의 현재의 최소 거리를 취득한다. 이것은, 사운드가 최대 볼륨이 되는 거리이다.

object. GetMinDistance() As Single

파라미터

object
DirectSound3DBuffer 오브젝트를 나타내는오브젝트식.

반환값

성공하면 현재의 최소 거리의 설정값을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

디폴트에서는, 최소 거리값은 DS3D_DEFAULTMINDISTANCE 이며, 현재는 1.0 으로 정의되고 있다 (디폴트의 거리 계수 1.0 을 사용했을 경우, 1 단위는 1.0 미터에 상당한다).

참조

DirectSound3DBuffer.SetMinDistance ,DirectSound3DBuffer.GetMaxDistance


DirectSound3DBuffer.GetMode

DirectSound3DBuffer.GetMode 메소드는, 3D 사운드 처리의 현재의 조작 모드를 취득한다.

object. GetMode() As CONST_DS3DMODEFLAGS

파라미터

object
DirectSound3DBuffer 오브젝트를 나타내는오브젝트식.

반환값

성공하면 현재의 모드의 설정을 포함한 값을 돌려준다. 이 값은,CONST_DS3DMODEFLAGS 열거의 정수의 언젠가이다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.


DirectSound3DBuffer.GetPosition

DirectSound3DBuffer.GetPosition 메소드는, 사운드 버퍼의 위치를 거리 단위로 취득한다.

object. GetPosition(position As D3DVECTOR)

파라미터

object
DirectSound3DBuffer 오브젝트를 나타내는오브젝트식.
position
사운드 버퍼의 위치를 받는 D3DVECTOR 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

디폴트의 거리 단위는 미터이지만,DirectSound3DListener.SetDistanceFactor 메소드를 사용해 단위를 변경할 수 있다.


DirectSound3DBuffer.GetVelocity

DirectSound3DBuffer.GetVelocity 메소드는, 사운드 버퍼의 현재의 속도를 취득한다.

object. GetVelocity(velocity As D3DVECTOR)

파라미터

object
DirectSound3DBuffer 오브젝트를 나타내는오브젝트식.
velocity
버퍼의 현재의 속도를 받는 D3DVECTOR 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

속도는 도플러 효과에서만 사용된다. 버퍼를 이동할 것은 없다. 상세한 것에 대하여는, 「돕라 계수」를 참조할것.

디폴트의 계측 단위는 미터/초이지만,DirectSound3DListener.SetDistanceFactor 메소드를 사용해 변경할 수 있다.

참조

DirectSound3DBuffer.SetPosition ,DirectSound3DBuffer.SetVelocity


DirectSound3DBuffer.SetAllParameters

DirectSound3DBuffer.SetAllParameters 메소드는, 사운드 버퍼의 모든 3D 파라미터를 설정한다.

object. SetAllParameters(buffer As DS3DBUFFER, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

파라미터

object
DirectSound3DBuffer 오브젝트를 나타내는오브젝트식.
buffer
사운드 버퍼의 3D 특성을 기술하는 정보를 포함한 DS3DBUFFER 형.
applyFlag
설정이 적용되는 타이밍을 나타내는 값. 이 값은,CONST_DS3DAPPLYFLAGS 열거의 정수의 언젠가가 아니면 안된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.


DirectSound3DBuffer.SetConeAngles

DirectSound3DBuffer.SetConeAngles 메소드는, 사운드 버퍼의 사운드 프로젝션 콘의 내부 각도와 외부 각도를 설정한다.

object. SetConeAngles(inCone As Long, _
    outCone As Long, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

파라미터

object
DirectSound3DBuffer 오브젝트를 나타내는오브젝트식.
inCone
사운드 프로젝션 콘의 내부 각도. 단위는 번 (˚).
outCone
사운드 프로젝션 콘의 외부 각도. 단위는 번 (˚).
applyFlag
설정이 적용되는 타이밍을 나타내는 값. 이 값은,CONST_DS3DAPPLYFLAGS 열거의 정수의 언젠가가 아니면 안된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

최소, 최대, 디폴트의 콘 각도는 각각 DS3D_MINCONEANGLE, DS3D_MAXCONEANGLE, DS3D_DEFAULTCONEANGLE 로서 정의된다. 각 각도의 범위는, 0 번 (콘 없음)에서 360 번 (전범위)까지이다. 디폴트값은 360 이다.

참조

DirectSound3DBuffer.GetConeOutsideVolume ,DirectSound3DBuffer.SetConeOutsideVolume


DirectSound3DBuffer.SetConeOrientation

DirectSound3DBuffer.SetConeOrientation 메소드는, 사운드 버퍼의 사운드 프로젝션 콘의 방향을 설정한다. 콘 각도와 콘 볼륨 계수가 이미 설정되어 있지 않은 한, 이 메소드는 아무것도 하지 않는다.

object. SetConeOrientation( _
    x As Single, _
    y As Single, _
    z As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

파라미터

object
DirectSound3DBuffer 오브젝트를 나타내는오브젝트식.
x,y,z
사운드 콘의 새로울 방향 벡터의 좌표.
applyFlag
설정이 적용되는 타이밍을 나타내는 값. CONST_DS3DAPPLYFLAGS 열거의 정수의 언젠가가 아니면 안된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

참조

DirectSound3DBuffer.SetConeAngles ,DirectSound3DBuffer.SetConeOutsideVolume


DirectSound3DBuffer.SetConeOutsideVolume

DirectSound3DBuffer.SetConeOutsideVolume 메소드는, 사운드 버퍼의 콘 외부 볼륨을 설정한다.

object. SetConeOutsideVolume(coneOutsideVolume As Long, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

파라미터

object
DirectSound3DBuffer 오브젝트를 나타내는오브젝트식.
coneOutsideVolume
사운드 버퍼의 콘 외부 볼륨을 100 분의 1 데시벨 (dB)의 단위로 지정한다.
applyFlag
설정이 적용되는 타이밍을 나타내는 값. 이 값은,CONST_DS3DAPPLYFLAGS 열거의 정수의 언젠가가 아니면 안된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

볼륨 레벨은 감쇠에 의해 나타내진다. 허용 되는 값은 DSBVOLUME_MAX (감쇠 없음)와 DSBVOLUME_MIN (무음)의 사이이다. 디폴트값은 DS3D_DEFAULTCONEOUTSIDEVOLUME (감쇠 없음)이다.

참조

DirectSoundBuffer.SetVolume


DirectSound3DBuffer.SetMaxDistance

DirectSound3DBuffer.SetMaxDistance 메소드는, 버퍼의 최대 거리를 설정한다. 이것은, 볼륨이 그 이상 감쇠하지 않게 되는 거리이다.

object. SetMaxDistance(maxDistance As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

파라미터

object
DirectSound3DBuffer 오브젝트를 나타내는오브젝트식.
maxDistance
최대 거리값.
applyFlag
설정이 적용되는 타이밍을 나타내는 값. 이 값은,CONST_DS3DAPPLYFLAGS 열거의 정수의 언젠가가 아니면 안된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

디폴트의 최대 거리는 DS3D_DEFAULTMAXDISTANCE 에 의해 정의되어 실질적으로 무한대이다.

참조

DirectSound3DBuffer.GetMaxDistance ,DirectSound3DBuffer.SetMinDistance


DirectSound3DBuffer.SetMinDistance

DirectSound3DBuffer.SetMinDistance 메소드는, 버퍼의 최소 거리를 설정한다. 이것은, 사운드가 최대 볼륨이 되는 거리이다.

object. SetMinDistance(minDistance As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

파라미터

object
DirectSound3DBuffer 오브젝트를 나타내는오브젝트식.
minDistance
최소 거리값.
applyFlag
설정이 적용되는 타이밍을 나타내는 값. 이 값은,CONST_DS3DAPPLYFLAGS 열거의 정수의 언젠가가 아니면 안된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

디폴트에서는, 최소 거리값은 DS3D_DEFAULTMINDISTANCE 이며, 1.0 으로 정의되고 있다 (디폴트의 거리 계수 1.0 을 사용했을 경우, 1 단위는 1.0 미터에 상당한다).

참조

DirectSound3DBuffer.SetMaxDistance


DirectSound3DBuffer.SetMode

DirectSound3DBuffer.SetMode 메소드는, 3D 사운드 처리의 조작 모드를 설정한다.

object. SetMode(mode As CONST_DS3DMODEFLAGS, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

파라미터

object
DirectSound3DBuffer 오브젝트를 나타내는오브젝트식.
mode
설정하는 3D 사운드 처리 모드를 나타내는 CONST_DS3DMODEFLAGS 열거의 정수의 1 개를 지정한다.
applyFlag
설정이 적용되는 타이밍을 나타내는 값. 이 값은,CONST_DS3DAPPLYFLAGS 열거의 정수의 언젠가가 아니면 안된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.


DirectSound3DBuffer.SetPosition

DirectSound3DBuffer.SetPosition 메소드는, 사운드 버퍼의 위치를 거리 단위로 설정한다.

object. SetPosition(x As Single, _
    y As Single, _
    z As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

파라미터

object
DirectSound3DBuffer 오브젝트를 나타내는오브젝트식.
x,y,z
위치 벡터의 좌표를 나타내는 값. 부동 소수점의 오버플로우를 방지하기 위해서, DirectSound 가 이러한 값에 조정을 더할 가능성이 있다.
applyFlag
설정이 적용되는 타이밍을 나타내는 값. 이 값은,CONST_DS3DAPPLYFLAGS 열거의 정수의 언젠가가 아니면 안된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

10 이상 또는 –10 이하의 값을 건네주면(자), 오디오의 한계를 넘어 사운드가 감쇠할 가능성이 있다.

디폴트의 거리 단위는 미터이지만,DirectSound3DListener.SetDistanceFactor 메소드를 사용해 단위를 변경할 수 있다.


DirectSound3DBuffer.SetVelocity

DirectSound3DBuffer.SetVelocity 메소드는, 사운드 버퍼의 속도를 설정한다.

object. SetVelocity(x As Single, _
    y As Single, _
    z As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

파라미터

object
DirectSound3DBuffer 오브젝트를 나타내는오브젝트식.
x,y,z
속도벡터의 좌표를 나타내는 값. 부동 소수점의 오버플로우를 방지하기 위해서, DirectSound 가 이러한 값에 조정을 더할 가능성이 있다.
applyFlag
설정이 적용되는 타이밍을 나타내는 값. 이 값은,CONST_DS3DAPPLYFLAGS 열거의 정수의 언젠가가 아니면 안된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

속도는 도플러 효과에서만 사용된다. 버퍼를 이동할 것은 없다.

디폴트의 계측 단위는 미터/초이지만,DirectSound3DListener.SetDistanceFactor 메소드를 사용해 단위를 변경할 수 있다.

참조

DirectSound3DBuffer.SetPosition ,DirectSound3DBuffer.GetVelocity


DirectSound3DListener 클래스

어플리케이션은 DirectSound3DListener 클래스의 메소드를 사용해, 3D 공간에서의 청취자의 위치, 방향, 리스닝 환경을 기술하는 파라미터의 취득과 설정을 실시한다. 여기에서는, DirectSound3DListener 클래스의 메소드의 레퍼런스를 제공한다.

DirectSoundBuffer.GetDirectSound3DListener 메소드를 사용해, 이 클래스의 오브젝트를 취득한다. 청취자로부터 취득되는 버퍼는, DSBCAPS_PRIMARYBUFFER 플래그로 생성 되지 않으면 안 된다. 또, 프라이머리 버퍼로부터 취득되는 DirectSound3DBuffer 오브젝트의 DirectSound3DBuffer.GetDirectSound3DListener 메소드를 호출하면, 청취자도 취득할 수 있다.

DirectSound3DListener 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

배치 파라미터 | GetAllParameters
 | SetAllParameters
지연 설정 | CommitDeferredSettings
거리 계수 | GetDistanceFactor
 | SetDistanceFactor
돕라 계수 | GetDopplerFactor
 | SetDopplerFactor
오브젝트의 취득 | GetDirectSoundBuffer
방향 | GetOrientation
 | SetOrientation
위치 | GetPosition
 | SetPosition
롤 오프 계수 | GetRolloffFactor
 | SetRolloffFactor
속도 | GetVelocity
 | SetVelocity


DirectSound3DListener.CommitDeferredSettings

DirectSound3DListener.CommitDeferredSettings 메소드는, 전회 이 메소드를 호출한 후에 행해진 지연 설정을 위탁한다.

object. CommitDeferredSettings()

파라미터

object
DirectSound3DListener 오브젝트를 나타내는오브젝트식.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.


DirectSound3DListener.GetAllParameters

DirectSound3DListener.GetAllParameters 메소드는, 3D 월드와 청취자 상태를 취득한다.

object. GetAllParameters(listener As DS3DLISTENER)

파라미터

object
DirectSound3DListener 오브젝트를 나타내는오브젝트식.
listener
파라미터를 받는 DS3DLISTENER 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

참조

DirectSound3DListener.SetAllParameters


DirectSound3DListener.GetDirectSoundBuffer

DirectSound3DListener.GetDirectSoundBuffer 메소드는, 프라이머리 버퍼를 나타내는 DirectSoundBuffer 오브젝트를 돌려준다.

object. GetDirectSoundBuffer() As DirectSoundBuffer

파라미터

object
DirectSound3DListener 오브젝트를 나타내는오브젝트식.

반환값

성공하면 DirectSoundBuffer 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_OUTOFMEMORY 가 설정된다.


DirectSound3DListener.GetDistanceFactor

DirectSound3DListener.GetDistanceFactor 메소드는, 벡터 단위의 미터수로 거리 계수를 취득한다.

object. GetDistanceFactor() As Single

파라미터

object
DirectSound3DListener 오브젝트를 나타내는오브젝트식.

반환값

성공하면 거리 계수의 값을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

참조

DirectSound3DListener.SetDistanceFactor


DirectSound3DListener.GetDopplerFactor

DirectSound3DListener.GetDopplerFactor 메소드는, 도플러 효과 계수를 취득한다.

object. GetDopplerFactor() As Single

파라미터

object
DirectSound3DListener 오브젝트를 나타내는오브젝트식.

반환값

성공하면 돕라 계수의 값을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

Remarks

돕라 계수의 범위는, DS3D_MINDOPPLERFACTOR (도플러 효과 없음)로부터 DS3D_MAXDOPPLERFACTOR (열매 세계의 10 배의 도플러 효과)까지이다. 디폴트값은 DS3D_DEFAULTDOPPLERFACTOR (1.0)이다.

참조

DirectSound3DListener.SetDopplerFactor


DirectSound3DListener.GetOrientation

DirectSound3DListener.GetOrientation 메소드는, 3D 공간의 청취자의 방향을 취득한다.

object. GetOrientation(orientFront As D3DVECTOR, _
    orientTop As D3DVECTOR)

파라미터

object
DirectSound3DListener 오브젝트를 나타내는오브젝트식.
orientFront
청취자의 전방 벡터를 받는 D3DVECTOR 형.
orientTop
청취자의 윗쪽 벡터를 받는 D3DVECTOR 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

전방 벡터는 청취자의 코의 방향, 윗쪽 벡터는 청취자의 두정부의 방향을 가리킨다. 디폴트에서는, 전방 벡터는 (0,0,1.0), 윗쪽 벡터는 (0,1.0, 0)이다.

반환값은 반드시 DirectSound3DListener.SetOrientation 메소드를 사용해 설정한 것과 같은 값은 아니다. DirectSound 는 방향 벡터에 조정을 더해 그것들이 서로 직각이 되도록(듯이) 해, 양쪽 모두의 크기를 1.0 이하로 한다.


DirectSound3DListener.GetPosition

DirectSound3DListener.GetPosition 메소드는, 3D 공간에 있어서의 청취자의 위치를 취득한다.

object. GetPosition(position As D3DVECTOR)

파라미터

object
DirectSound3DListener 오브젝트를 나타내는오브젝트식.
position
청취자의 위치 벡터를 받는 D3DVECTOR 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

참조

DirectSound3DListener.SetPosition


DirectSound3DListener.GetRolloffFactor

DirectSound3DListener.GetRolloffFactor 메소드는, 거리에 응한 감쇠율을 제어하는 롤 오프 계수를 취득한다.

object. GetRolloffFactor() As Single

파라미터

object
DirectSound3DListener 오브젝트를 나타내는오브젝트식.

반환값

성공하면 롤 오프 계수의 값을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

롤 오프 계수는, DS3D_MINROLLOFFFACTOR (롤 오프 없음)로부터 DS3D_MAXROLLOFFFACTOR (열매 세계의 10 배의 롤 오프)까지의 범위를 취한다. 디폴트값은 DS3D_DEFAULTROLLOFFFACTOR (1.0)이다.

참조

DirectSound3DListener.SetRolloffFactor


DirectSound3DListener.GetVelocity

DirectSound3DListener.GetVelocity 메소드는, 청취자의 속도를 취득한다.

object. GetVelocity() As D3DVECTOR

파라미터

object
DirectSound3DListener 오브젝트를 나타내는오브젝트식.

반환값

성공하면 청취자의 속도를 포함한 D3DVECTOR 형을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

디폴트의 속도는 (0,0,0)이다.

속도는 도플러 효과에서만 사용된다. 청취자를 이동할 것은 없다.

참조

DirectSound3DListener.SetVelocity


DirectSound3DListener.SetAllParameters

DirectSound3DListener.SetAllParameters 메소드는, 모든 3D 청취자의 프로퍼티와 글로벌 사운드 파라미터를 설정한다.

object. SetAllParameters(listener As DS3DLISTENER, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

파라미터

object
DirectSound3DListener 오브젝트를 나타내는오브젝트식.
listener
모든 3D 청취자의 파라미터 정보를 보관 유지하는 DS3DLISTENER 형.
applyFlag
설정이 적용되는 타이밍을 나타내는 값. 이 값은,CONST_DS3DAPPLYFLAGS 열거의 정수의 언젠가가 아니면 안된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

참조

DirectSound3DListener.GetAllParameters


DirectSound3DListener.SetDistanceFactor

DirectSound3DListener.SetDistanceFactor 메소드는, 거리 계수를 설정한다.

object. SetDistanceFactor(distanceFactor As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

파라미터

object
DirectSound3DListener 오브젝트를 나타내는오브젝트식.
distanceFactor
거리 계수.
applyFlag
설정이 적용되는 타이밍을 나타내는 값. 이 값은,CONST_DS3DAPPLYFLAGS 열거의 정수의 언젠가가 아니면 안된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

거리 계수의 상세한 것에 대하여는, 「거리 계수」를 참조할것.

참조

DirectSound3DListener.GetDistanceFactor


DirectSound3DListener.SetDopplerFactor

DirectSound3DListener.SetDopplerFactor 메소드는, 도플러 효과 계수를 설정한다.

object. SetDopplerFactor(dopplerFactor As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

파라미터

object
DirectSound3DListener 오브젝트를 나타내는오브젝트식.
dopplerFactor
돕라 계수의 값.
applyFlag
설정이 적용되는 타이밍을 나타내는 값. 이 값은,CONST_DS3DAPPLYFLAGS 열거의 정수의 언젠가가 아니면 안된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

돕라 계수의 범위는, DS3D_MINDOPPLERFACTOR (도플러 효과 없음)로부터 DS3D_MAXDOPPLERFACTOR (열매 세계의 10 배의 도플러 효과)까지이다. 디폴트값은 DS3D_DEFAULTDOPPLERFACTOR (1.0)이다.

참조

DirectSound3DListener.GetDopplerFactor


DirectSound3DListener.SetOrientation

DirectSound3DListener.SetOrientation 메소드는, 전방 벡터와 윗쪽 벡터의 2 개의 벡터에 의해, 청취자의 방향을 설정한다.

object. SetOrientation(xFront As Single, _
    yFront As Single, _
    zFront As Single, _
    xTop As Single, _
    yTop As Single, _
    zTop As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

파라미터

object
DirectSound3DListener 오브젝트를 나타내는오브젝트식.
xFront,yFront,zFront
전방 벡터의 좌표를 나타내는 값.
xTop,yTop,zTop
윗쪽 벡터의 좌표를 나타내는 값.
applyFlag
설정이 적용되는 타이밍을 나타내는 값. 이 값은,CONST_DS3DAPPLYFLAGS 열거의 정수의 언젠가가 아니면 안된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

전방 벡터는 청취자의 코의 방향, 윗쪽 벡터는 청취자의 두정부의 방향을 가리킨다. 디폴트에서는, 전방 벡터는 (0,0,1.0), 윗쪽 벡터는 (0,1.0, 0)이다.

윗쪽 벡터는 전방 벡터에 대해서 직각이 아니면 안된다. 필요에 따라서, DirectSound 는 전방 벡터를 설정한 다음에 윗쪽 벡터를 조정한다.

참조

DirectSound3DListener.GetOrientation


DirectSound3DListener.SetPosition

DirectSound3DListener.SetPosition 메소드는, 청취자의 위치를 거리 단위로 설정한다.

object. SetPosition(x As Single, _
    y As Single, _
    z As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

파라미터

object
DirectSound3DListener 오브젝트를 나타내는오브젝트식.
x,y,z
청취자의 위치 벡터의 좌표를 나타내는 값. 부동 소수점의 오버플로우를 방지하기 위해서, DirectSound 가 이러한 값에 조정을 더할 가능성이 있다.
applyFlag
설정이 적용되는 타이밍을 나타내는 값. 이 값은,CONST_DS3DAPPLYFLAGS 열거의 정수의 언젠가가 아니면 안된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

디폴트에서는 이러한 단위는 미터이지만,DirectSound3DListener.SetDistanceFactor 메소드를 사용해 단위를 변경할 수 있다.

참조

DirectSound3DListener.GetPosition


DirectSound3DListener.SetRolloffFactor

DirectSound3DListener.SetRolloffFactor 메소드는, 롤 오프 계수를 설정한다.

object. SetRolloffFactor(rolloffFactor As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

파라미터

object
DirectSound3DListener 오브젝트를 나타내는오브젝트식.
rolloffFactor
롤 오프 계수.
applyFlag
설정이 적용되는 타이밍을 나타내는 값. 이 값은,CONST_DS3DAPPLYFLAGS 열거의 정수의 언젠가가 아니면 안된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

롤 오프 계수는, DS3D_MINROLLOFFFACTOR (롤 오프 없음)로부터 DS3D_MAXROLLOFFFACTOR (열매 세계의 10 배의 롤 오프)까지의 범위를 취한다. 디폴트값은 DS3D_DEFAULTROLLOFFFACTOR (1.0)이다.

참조

DirectSound3DListener.GetRolloffFactor


DirectSound3DListener.SetVelocity

DirectSound3DListener.SetVelocity 메소드는, 청취자의 속도를 설정한다.

object. SetVelocity(x As Single, _
    y As Single, _
    z As Single, _
    applyFlag As CONST_DS3DAPPLYFLAGS)

파라미터

object
DirectSound3DListener 오브젝트를 나타내는오브젝트식.
x,y,z
청취자의 속도벡터의 좌표를 나타내는 값. 부동 소수점의 오버플로우를 방지하기 위해서, DirectSound 가 이러한 값에 조정을 더할 가능성이 있다.
applyFlag
설정이 적용되는 타이밍을 나타내는 값. 이 값은,CONST_DS3DAPPLYFLAGS 열거의 정수의 언젠가가 아니면 안된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

디폴트의 속도는 (0,0,0)이다.

속도는 도플러 효과에서만 사용된다. 청취자를 이동할 것은 없다. 청취자의 위치를 변경하려면 DirectSound3DListener.SetPosition 메소드를 사용한다.

참조

DirectSound3DListener.GetVelocity


DirectSoundBuffer 클래스

어플리케이션은 DirectSoundBuffer 클래스의 메소드를 사용해,DirectSoundBuffer 오브젝트의 생성과 환경 설정을 실시한다.

DirectSound.CreateSoundBuffer ,DirectSound.CreateSoundBufferFromFile ,DirectSound.CreateSoundBufferFromResource 의 각 메소드를 사용해 이 오브젝트를 취득한다.

DirectSoundBuffer 메소드는, 이하의 그룹에 정리할 수가 있다.

정보 | GetCaps
 | GetFormat
 | GetStatus
 | SetFormat
메모리 메니지먼트 | Restore
그 외 | SaveToFile
오브젝트의 취득 | GetDirectSound3DBuffer
 | GetDirectSound3DListener
재생 관리 | GetCurrentPosition
 | Play
 | ReadBuffer
 | SetCurrentPosition
 | SetNotificationPositions
 | Stop
 | WriteBuffer
사운드 관리 | GetFrequency
 | GetPan
 | GetVolume
 | SetFrequency
 | SetPan
 | SetVolume


DirectSoundBuffer.GetCaps

DirectSoundBuffer.GetCaps 메소드는, 버퍼의 능력을 취득한다.

object. GetCaps(caps As DSBCAPS)

파라미터

object
DirectSoundBuffer 오브젝트를 나타내는오브젝트식.
caps
사운드 버퍼의 능력을 보관 유지하고 있는 DSBCAPS 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

주의

DSBCAPS 형은,DirectSound.CreateSoundBuffer 메소드에게 건네지는 DSBUFFERDESC 형과 동등의 정보에 가세해, 몇개의 추가 정보를 보관 유지하고 있다. 이 정보로서 버퍼의 위치 (하드웨어와 소프트웨어의 어느 쪽인지)와 코스트 측정값을 들 수 있다. 코스트 측정값의 예에는, 하드웨어 버퍼에의 다운로드 소요 시간, 버퍼가 소프트웨어내에 배치되고 있는 경우의 믹싱이나 재생 처리의 오버헤드가 포함된다.

DSBCAPS 형의 lFlags 멤버내의 플래그는,DSBUFFERDESC 형으로 사용되는 플래그와 같은 것이다. 유일한 차이는,DSBCAPS 형에서는 버퍼 메모리의 장소에 응해 DSBCAPS_LOCHARDWARE 과 DSBCAPS_LOCSOFTWARE 의 어느 쪽인지가 지정되는 것이다. DSBUFFERDESC 형에서는 이러한 플래그는 옵션이며, 플래그의 지정에 응해, 버퍼를 하드웨어와 소프트웨어의 어딘가에 강제적으로 배치할 수 있다.


DirectSoundBuffer.GetCurrentPosition

DirectSoundBuffer.GetCurrentPosition 메소드는, 사운드 버퍼내의 재생 커서와 쓰기 커서의 위치를 취득한다.

object. GetCurrentPosition(cursors As DSCURSORS)

파라미터

object
DirectSoundBuffer 오브젝트를 나타내는오브젝트식.
cursors
버퍼의 현재 플레이 포지션과 현재 라이트 포지션을 받는 DSCURSORS 형. 이 정도치는 사운드 버퍼내의 오프셋(offset)이며, 바이트 단위로 지정된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

쓰기 커서는 보통, 재생 커서보다 15 밀리 세컨드의 오디오 데이터분만큼 항상 선행하고 있다. 재생 위치와 쓰기 위치동안의 데이터의 쓰기는 안전하게 실시할 수 없다.

참조

DirectSoundBuffer ,DirectSoundBuffer.SetCurrentPosition


DirectSoundBuffer.GetDirectSound3DBuffer

DirectSoundBuffer.GetDirectSound3DBuffer 메소드는,DirectSound3DBuffer 오브젝트를 돌려준다.

object. GetDirectSound3DBuffer() As DirectSound3DBuffer

파라미터

object
DirectSoundBuffer 오브젝트를 나타내는오브젝트식.

반환값

성공하면 DirectSound3DBuffer 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 E_NOINTERFACE 또는 DSERR_OUTOFMEMORY 가 설정된다.

주의

이 메소드는, DSBCAPS_CTRL3D 플래그로 생성 된 버퍼만으로 성공한다.

참조

DirectSound.CreateSoundBuffer


DirectSoundBuffer.GetDirectSound3DListener

DirectSoundBuffer.GetDirectSound3DListener 메소드는,DirectSound3DListener 오브젝트를 돌려준다.

object. GetDirectSound3DListener() As DirectSound3DListener

파라미터

object
DirectSoundBuffer 오브젝트를 나타내는오브젝트식.

반환값

성공하면 DirectSound3DListener 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

주의

이 메소드는, DSBCAPS_CTRL3D 와 DSBCAPS_PRIMARYBUFFER 의 플래그로 생성 된 버퍼만으로 성공한다.

참조

DirectSound.CreateSoundBuffer


DirectSoundBuffer.GetFormat

DirectSoundBuffer.GetFormat 메소드는, 버퍼의 웨이브 포맷의 기술을 취득한다.

object. GetFormat(format As WAVEFORMATEX)

파라미터

object
DirectSoundBuffer 오브젝트를 나타내는오브젝트식.
format
버퍼의 웨이브 포맷의 기술을 받는 WAVEFORMATEX 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.

참조

DirectSoundBuffer.SetFormat


DirectSoundBuffer.GetFrequency

DirectSoundBuffer.GetFrequency 메소드는, 버퍼의 재생을 하고 있는 장소에서의 1 초 쯤의 샘플링 회수를 주파수로서 취득한다.

object. GetFrequency() As Long

파라미터

object
DirectSoundBuffer 오브젝트를 나타내는오브젝트식.

반환값

오디오 버퍼의 재생을 하고 있는 장소의 주파수.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

주파수의 값은, DSBFREQUENCY_MIN (100)로부터 DSBFREQUENCY_MAX (100,000)의 범위를 취한다.

참조

DirectSoundBuffer.SetFrequency


DirectSoundBuffer.GetPan

DirectSoundBuffer.GetPan 메소드는, 좌우의 오디오 채널의 상대 볼륨을 나타내는 변수를 취득한다.

object. GetPan() As Long

파라미터

object
DirectSoundBuffer 오브젝트를 나타내는오브젝트식.

반환값

좌우의 스피커의 상대 믹싱율. 「주의」를 참조할것.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

반환값은 DSBPAN_LEFT (-10, 000)로부터 DSBPAN_RIGHT (10,000)의 범위에서, 100 분의 1 데시벨 (dB) 단위이다. 값 DSBPAN_LEFT 는 오른쪽 채널이 100 dB 감쇠하고 있는 것을 의미한다. 값 DSBPAN_RIGHT 는 왼쪽 채널이 100 dB 감쇠하고 있는 것을 의미한다. 중립값은 DSBPAN_CENTER (0)이며, 양쪽 모두의 채널이 최대 볼륨인 것을 의미한다 (0 dB 의 감쇠).

DSBPAN_CENTER 이외의 값은 모두, 한편이 최대 볼륨으로 이제(벌써) 한편이 감쇠하고 있는 것을 의미한다. 예를 들어, 값이 -2, 173 때, 왼쪽 채널은 최대 볼륨으로, 오른쪽 채널은 21.73 dB 감쇠하고 있는 것을 의미한다. (와)과 같이 팬의 값이 870 때, 왼쪽 채널은 8.7 dB 감쇠하고 있어, 오른쪽 채널은 최대 볼륨인 것을 의미한다.

팬 컨트롤의 이펙트는, 음량 조절에 누적된다.

참조

DirectSoundBuffer.GetVolume ,DirectSoundBuffer.SetPan ,DirectSoundBuffer.SetVolume


DirectSoundBuffer.GetStatus

DirectSoundBuffer.GetStatus 메소드는, 사운드 버퍼의 스테이터스를 취득한다.

object. GetStatus() As CONST_DSBSTATUSFLAGS

파라미터

object
DirectSoundBuffer 오브젝트를 나타내는오브젝트식.

반환값

사운드 버퍼의 스테이터스. 스테이터스는 버퍼가 없어지고 있을까 재생중이 어느 쪽도 아닌 것을 나타내는 0, 또는 CONST_DSBSTATUSFLAGS 열거의 정수의 편성이다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

DirectSoundBuffer


DirectSoundBuffer.GetVolume

DirectSoundBuffer.GetVolume 메소드는, 사운드 버퍼의 볼륨을 취득한다.

object. GetVolume() As Long

파라미터

object
DirectSoundBuffer 오브젝트를 나타내는오브젝트식.

반환값

버퍼의 볼륨을 돌려준다. 「주의」를 참조할것.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

볼륨은 100 분의 1 데시벨 (dB) 단위로 지정된다. 허용 되는 값은 DSBVOLUME_MAX (감쇠 없음)와 DSBVOLUME_MIN (무음)의 사이이다. 이러한 값은, 각각 0,-10, 000 으로 정의되고 있다. 값 DSBVOLUME_MAX 는, 사운드 본래의 미조정의 볼륨을 나타낸다. 값 DSBVOLUME_MIN 는, 오디오의 볼륨이 100 dB 감쇠하고 있는 것을 나타내지만, 이것은 실제적으로는 무음을 의미한다.

참조

DirectSoundBuffer.SetVolume ,DirectSoundBuffer.GetPan


DirectSoundBuffer.Play

DirectSoundBuffer.Play 메소드는, 사운드 버퍼를 현재 플레이 포지션으로부터 재생한다.

object. Play(flags As CONST_DSBPLAYFLAGS)

파라미터

object
DirectSoundBuffer 오브젝트를 나타내는오브젝트식.
flags
버퍼의 재생 방법을 지정하는 플래그. CONST_DSBPLAYFLAGS 열거의 정수의 어느쪽이든을 지정한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

이 메소드는 세컨드리 사운드 버퍼를 프라이머리 사운드 버퍼에 믹싱 해, 사운드 디바이스에 송신한다.

이 메소드가 지정한 버퍼가 이미 재생중이었던 경우, 메소드의 호출은 성공해, 버퍼는 재생을 계속한다. 다만 최신의 호출로 정의한 플래그는, 이전의 호출로 정의된 플래그를 옮겨놓는다.

이 메소드가 사운드 버퍼로 불려 가기 전에, 어플리케이션은 DirectSound.SetCooperativeLevel 메소드를 호출하지 않으면 안 된다.


DirectSoundBuffer.ReadBuffer

DirectSoundBuffer.ReadBuffer 메소드는, 사운드 버퍼의 세그먼트(segment)를 읽어들여, 어플리케이션 버퍼에 그 데이터를 저장 한다.

object. ReadBuffer(start As Long, _
    size As Long, _
    buffer As Any, _
    flags As CONST_DSBLOCKFLAGS)

파라미터

object
DirectSoundBuffer 오브젝트를 나타내는오브젝트식.
start
버퍼의 선두로부터 읽어들여 시작 위치까지의 오프셋(offset). 단위는 바이트. DSBLOCK_FROMWRITECURSOR 를 flags 파라미터로 지정하면(자), 이 파라미터는 무시된다.
size
읽어들이는 버퍼 부분의 사이즈. 단위는 바이트. 사운드 버퍼는 개념적으로는 순환 버퍼이므로, 이 값은 버퍼의선두로부터 끝까지의 바이트수보다 커질 수도 있다. DSBLOCK_ENTIREBUFFER 를 flags 파라미터로 지정하면(자), 이 파라미터는 무시된다.
buffer
읽어들이는 데이터를 보관 유지하는 변수. 보통 이것은 바이트의 배열이며, 배열의 최초의 요소를 건네준다.
flags
CONST_DSBLOCKFLAGS 열거의 정수의 어느쪽이든을 지정한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

참조

DirectSoundCaptureBuffer.ReadBuffer


DirectSoundBuffer.Restore

DirectSoundBuffer.Restore 메소드는, 없어진 사운드 버퍼에의 메모리 할당을 복원한다.

object. Restore()

파라미터

object
DirectSoundBuffer 오브젝트를 나타내는오브젝트식.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_PRIOLEVELNEEDED

주의

어플리케이션에 입력초점이 놓여지지 않으면DirectSoundBuffer.Restore 는 성공하지 않는 것이 있다. 예를 들어, 입력초점이 놓여져 있는 어플리케이션이 DSSCL_WRITEPRIMARY (쓰기 우선) 협조 레벨로 설정되어 있는 경우, 다른 어느 어플리케이션도 버퍼를 복원할 수 없다.

DirectSound 가 버퍼 메모리를 복원한 후, 유효한 사운드 데이터를 쓰기 고칠 필요가 있다. DirectSound 는 메모리 자체를 복원하지만, 메모리의 내용은 복원할 수 없다.

어플리케이션은 버퍼를 지정해 DirectSoundBuffer.WriteBuffer 또는 DirectSoundBuffer.Play 의 각 메소드를 호출하면, 그 버퍼가 없어지고 있는 경우에 통지를 받게 된다. 버퍼가 없어지고 있는 경우는, 이러한 메소드는 DSERR_BUFFERLOST 를 돌려준다. DirectSoundBuffer.GetStatus 메소드를 사용해, 사운드 버퍼의 스테이터스의 취득과 DSBSTATUS_BUFFERLOST 플래그의 테스트를 실시할 수도 있다.

참조

DirectSoundBuffer.GetStatus


DirectSoundBuffer.SaveToFile

DirectSoundBuffer.SaveToFile 메소드는, DirectSound 버퍼의 내용을 웨이브 파일에 보존한다.

object. SaveToFile(filename As String)

파라미터

object
DirectSoundBuffer 오브젝트를 나타내는오브젝트식.
filename
사운드 버퍼가 보존되는 장소의 파일명. 그 이름의 파일이 존재하는 경우, 데이터는 파일에 추가되는 것이 아니라, 파일이 덧쓰기된다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_INVALIDCALL
DSERR_INVALIDPARAM


DirectSoundBuffer.SetCurrentPosition

DirectSoundBuffer.SetCurrentPosition 메소드는, 버퍼의 현재 플레이 포지션을 이동한다.

object. SetCurrentPosition(newPosition As Long)

파라미터

object
DirectSoundBuffer 오브젝트를 나타내는오브젝트식.
newPosition
재생 위치에 대한 버퍼의 선두로부터의 오프셋(offset). 단위는 바이트.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

프라이머리 사운드 버퍼에 대해서는, 이 메소드를 호출할 수 없다.

버퍼가 이미 재생중의 경우는, 즉석에서 신규의 위치에 이동해 재생을 속행한다. 버퍼가 정지하고 있는 경우는, 다음에 DirectSoundBuffer.Play 메소드를 호출했을 때에, 새로운 위치로부터 재생을 시작 한다.

참조

DirectSoundBuffer.GetCurrentPosition


DirectSoundBuffer.SetFormat

DirectSoundBuffer.SetFormat 메소드는, 이 어플리케이션용의 프라이머리 사운드 버퍼의 포맷을 설정한다. 이 어플리케이션에 입력초점이 놓여질 때마다, DirectSound 는 프라이머리 버퍼가 지정된 포맷으로 설정한다.

object. SetFormat(format As WAVEFORMATEX)

파라미터

object
DirectSoundBuffer 오브젝트를 나타내는오브젝트식.
format
프라이머리 사운드 버퍼의 새로운 포맷을 지정하는 WAVEFORMATEX 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_BADFORMAT
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY
DSERR_PRIOLEVELNEEDED
DSERR_UNSUPPORTED

주의

하드웨어가 요구된 포맷을 지원 하지 않는 경우에서도, 이 메소드는 성공한다. DirectSound 는 버퍼를, 요구에 가장 가까운 포맷으로 설정해, 요구된 포맷으로 사운드를 믹스 해, 변환한 다음 프라이머리 버퍼에 보낸다. 이러한 상황이 발생하고 있을지 어떨지를 판단하려면 , 어플리케이션은 프라이머리 버퍼에 대해서 DirectSoundBuffer.GetFormat 메소드를 호출해, 그 결과를,SetFormat 메소드로 요구한 포맷과 비교한다.

호출하는 어플리케이션에 DSSCL_NORMAL 협조 레벨이 설정되어 있으면(자), 이 메소드는 실패한다.

이 메소드는 세컨드리 사운드 버퍼에는 유효하지 않다. 세컨드리 사운드 버퍼가 포맷의 변경을 필요로 하는 경우, 어플리케이션은 신규의 포맷을 사용하는 새로운 DirectSoundBuffer 오브젝트를 생성 해야 한다.


DirectSoundBuffer.SetFrequency

DirectSoundBuffer.SetFrequency 메소드는, 샘플링 오디오의 재생 주파수를 설정한다.

object. SetFrequency(frequency As Long)

파라미터

object
DirectSoundBuffer 오브젝트를 나타내는오브젝트식.
frequency
샘플링 오디오를 재생하는 새로운 주파수로, 단위는 헤르쯔 (Hz)이다. 값의 범위는 DSBFREQUENCY_MIN (100)로부터 DSBFREQUENCY_MAX (100,000)의 사이가 아니면 안된다.

값이 DSBFREQUENCY_ORIGINAL 의 경우, 주파수는 현재의 버퍼 포맷내의 디폴트값에 리셋 된다. 이 포맷은 DirectSound.CreateSoundBuffer 메소드로 지정된 것이다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

주파수를 상하시키면(자), 오디오 데이터의 인식 피치가 변화한다. 이 메소드는 버퍼의 포맷에 영향을 미치지 않는다.

이 메소드는 프라이머리 사운드 버퍼에는 유효하지 않다.

참조

DirectSoundBuffer.GetFrequency


DirectSoundBuffer.SetNotificationPositions

DirectSoundBuffer.SetNotificationPositions 메소드는, 통지 위치를 설정한다. 재생중에 현재 플레이 포지션이 지정된 오프셋(offset)에 도달할 때마다, 관련하는 이벤트가 시그널 송신된다.

object. SetNotificationPositions(nElements As Long, _
    psa() As DSBPOSITIONNOTIFY)

파라미터

object
DirectSoundBuffer 오브젝트를 나타내는오브젝트식.
nElements
psa 배열의 요소수.
psa
DSBPOSITIONNOTIFY 형의 배열.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED


DirectSoundBuffer.SetPan

DirectSoundBuffer.SetPan 메소드는, 좌우의 채널의 상대 볼륨을 설정한다.

object. SetPan(pan As Long)

파라미터

object
DirectSoundBuffer 오브젝트를 나타내는오브젝트식.
pan
좌우의 채널의 상대 볼륨.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

반환값은 DSBPAN_LEFT (-10, 000)로부터 DSBPAN_RIGHT (10,000)의 범위에서, 100 분의 1 데시벨 (dB) 단위이다. 값 DSBPAN_LEFT 는 오른쪽 채널이 100 dB 감쇠하고 있는 것을 의미한다. 값 DSBPAN_RIGHT 는 왼쪽 채널이 100 dB 감쇠하고 있는 것을 의미한다. 중립값은 DSBPAN_CENTER (0)이며, 양쪽 모두의 채널이 최대 볼륨인 것을 의미한다 (0 dB 의 감쇠).

DSBPAN_CENTER 이외의 값은 모두, 한편이 최대 볼륨으로 이제(벌써) 한편이 감쇠하고 있는 것을 의미한다. 예를 들어, 값이 -2, 173 때, 왼쪽 채널은 최대 볼륨으로, 오른쪽 채널은 21.73 dB 감쇠하고 있는 것을 의미한다. (와)과 같이 팬의 값이 870 때, 왼쪽 채널은 8.7 dB 감쇠하고 있어, 오른쪽 채널은 최대 볼륨인 것을 의미한다.

팬 컨트롤의 에페크토무콘트로르에 누적된다.

참조

DirectSoundBuffer.GetPan ,DirectSoundBuffer.SetVolume


DirectSoundBuffer.SetVolume

DirectSoundBuffer.SetVolume 메소드는, 사운드 버퍼의 볼륨을 변경한다.

object. SetVolume(volume As Long)

파라미터

object
DirectSoundBuffer 오브젝트를 나타내는오브젝트식.
volume
이 사운드 버퍼로 요구하는 볼륨.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

볼륨은, 감쇠의 100 분의 1 데시벨 (dB) 단위로 지정된다. 허용 되는 값은 DSBVOLUME_MAX (감쇠 없음)와 DSBVOLUME_MIN (무음)의 사이이다. 이러한 값은, 각각 0,-10, 000 으로 정의되고 있다. 값 DSBVOLUME_MAX 는, 사운드 본래의 미조정의 볼륨을 나타낸다. 값 DSBVOLUME_MIN 는, 오디오 볼륨이 100 dB 감쇠하고 있는 것을 나타내지만, 이것은 실제적으로는 무음을 의미한다.

참조

DirectSoundBuffer.GetVolume ,DirectSoundBuffer.SetPan


DirectSoundBuffer.Stop

DirectSoundBuffer.Stop 메소드는, 사운드 버퍼의 재생을 정지한다.

object. Stop()

파라미터

object
DirectSoundBuffer 오브젝트를 나타내는오브젝트식.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

주의

이 메소드는, 버퍼의 현재 플레이 포지션을 직전에 재생된 샘플의 직후의 샘플로 설정한다. 그 버퍼에 대해서 다음에 DirectSoundBuffer.Play 메소드를 호출하면, 이전에 재생을 정지한 장소로부터 재생이 재개된다.


DirectSoundBuffer.WriteBuffer

DirectSoundBuffer.WriteBuffer 메소드는, 오디오 데이터를 보관 유지하는 어플리케이션 버퍼로부터, 사운드 버퍼의 세그먼트(segment)에의 쓰기를 실시한다.

object. WriteBuffer(start As Long, _
    size As Long, _
    buffer As Any, _
    flags As CONST_DSBLOCKFLAGS)

파라미터

object
DirectSoundBuffer 오브젝트를 나타내는오브젝트식.
start
버퍼의 선두로부터 read를 시작 하는 장소까지의 오프셋(offset). 단위는 바이트. DSBLOCK_FROMWRITECURSOR 정수를 flags 파라미터로 지정하면(자), 이 파라미터는 무시된다.
size
읽어들이는 버퍼 부분의 사이즈. 단위는 바이트. 사운드 버퍼는 개념적으로는 순환 버퍼이므로, 이 값은 버퍼의선두로부터 끝까지의 바이트수보다 커질 수도 있다. DSBLOCK_ENTIREBUFFER 를 flags 파라미터로 지정하면(자), 이 파라미터는 무시된다.
buffer
사운드 버퍼에 기입하는 데이터를 보관 유지하는 변수. 보통 이것은 바이트의 배열이며, 배열의 최초의 요소를 건네준다.
flags
데이터를 기입하는 방법을 나타내는 CONST_DSBLOCKFLAGS 열거의 정수의 어느쪽이든을 지정한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED


DirectSoundCapture 클래스

DirectSoundCapture 클래스의 오브젝트는, 사운드 캡춰 디바이스를 나타낸다. 이 클래스의 메소드는, 사운드 캡춰 버퍼의 생성과 그 디바이스 능력의 문의에 사용된다.

DirectX7.DirectSoundCaptureCreate 메소드를 사용해 이 클래스의 오브젝트를 취득한다.

DirectSoundCapture 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

버퍼의 생성 | CreateCaptureBuffer
능력 | GetCaps


DirectSoundCapture.CreateCaptureBuffer

DirectSoundCapture.CreateCaptureBuffer 메소드는, 캡춰 버퍼를 생성 한다.

object. CreateCaptureBuffer( _
    bufferDesc As DSCBUFFERDESC) _
    As DirectSoundCaptureBuffer

파라미터

object
DirectSoundCapture 오브젝트를 나타내는오브젝트식.
bufferDesc
생성 되는 캡춰 버퍼용의 값을 지정하는 DSCBUFFERDESC 형.

반환값

성공하면 DirectSoundCaptureBuffer 오브젝트를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_INVALIDPARAM
DSERR_BADFORMAT
DSERR_GENERIC
DSERR_NODRIVER
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED

주의

캡춰 디바이스에서는, 1 개의 캡춰 버퍼만 존재할 수 있다.


DirectSoundCapture.GetCaps

DirectSoundCapture.GetCaps 메소드는, 캡춰 디바이스의 능력을 취득한다.

object. GetCaps(caps As DSCCAPS)

파라미터

object
DirectSoundCapture 오브젝트를 나타내는오브젝트식.
caps
캡춰 디바이스의 능력을 받는 DSCCAPS 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_INVALIDPARAM
DSERR_UNSUPPORTED
DSERR_NODRIVER
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED


DirectSoundCaptureBuffer 클래스

DirectSoundCaptureBuffer 클래스의 메소드는, 사운드 캡춰 버퍼를 조작하기 위해서 사용된다.

DirectSoundCapture.CreateCaptureBuffer 메소드를 호출해 이 클래스의 오브젝트를 취득한다.

DirectSoundCaptureBuffer 클래스의 메소드는, 이하의 그룹에 정리할 수가 있다.

정보 | GetCaps
 | GetCurrentPosition
 | GetFormat
 | GetStatus
버퍼 | ReadBuffer
 | WriteBuffer
통지 | SetNotificationPositions
캡춰 관리 | Start
 | Stop


DirectSoundCaptureBuffer.GetCaps

DirectSoundCaptureBuffer.GetCaps 메소드는, 버퍼의 능력을 돌려준다.

object. GetCaps(caps As DSCBCAPS)

파라미터

object
DirectSoundCaptureBuffer 오브젝트를 나타내는오브젝트식.
caps
캡춰 버퍼의 능력을 받는 DSCBCAPS 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_INVALIDPARAM
DSERR_UNSUPPORTED
DSERR_OUTOFMEMORY


DirectSoundCaptureBuffer.GetCurrentPosition

DirectSoundCaptureBuffer.GetCurrentPosition 메소드는, 버퍼의 현재의 캡춰 위치와 읽어들여 위치를 취득한다.

object. GetCurrentPosition(cursors As DSCURSORS)

파라미터

object
DirectSoundCaptureBuffer 오브젝트를 나타내는오브젝트식.
cursors
현재의 캡춰 위치 (lPlay)와 read 위치 (lWrite)를 받는 DSCURSORS 형. 각각의 위치는 캡춰 버퍼의 오프셋(offset)이며, 바이트 단위로 지정한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_INVALIDPARAM
DSERR_NODRIVER
DSERR_OUTOFMEMORY

주의

캡춰 위치는 읽어들여 위치에서(보다) 전방에 있어, 데이터가 캡춰 되는 위치를 나타낸다. read 위치 (DSCURSORS.lWrite)까지의 위치에서는, 데이터를 안전하게 read 할 수 있다. 버퍼링이기 때문에, read 위치에서(보다) 다음에 캡춰 위치보다 전의 데이터는 (캡춰 위치를 포함한다), 반드시 유효한 데이터라고는 할 수 없다.


DirectSoundCaptureBuffer.GetFormat

DirectSoundCaptureBuffer.GetFormat 메소드는, 캡춰 버퍼의 포맷을 취득한다.

object. GetFormat(waveformat As WAVEFORMATEX)

파라미터

object
DirectSoundCaptureBuffer 오브젝트를 나타내는오브젝트식.
waveformat
캡춰 버퍼 포맷의 기술을 받는 WAVEFORMATEX 형.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.


DirectSoundCaptureBuffer.GetStatus

DirectSoundCaptureBuffer.GetStatus 메소드는, 캡춰 버퍼의 현재의 스테이터스를 취득한다.

object. GetStatus() As CONST_DSCBSTATUSFLAGS

파라미터

object
DirectSoundCaptureBuffer 오브젝트를 나타내는오브젝트식.

반환값

성공하면 캡춰 버퍼의 스테이터스를 돌려준다. 스테이터스는,CONST_DSCBSTATUSFLAGS 열거의 정수의 1 개 또는 복수이다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.


DirectSoundCaptureBuffer.ReadBuffer

DirectSoundCaptureBuffer.ReadBuffer 메소드는, 사운드 캡춰 버퍼의 세그먼트(segment)를 읽어들여, 그 데이터를 어플리케이션 버퍼에 저장 한다.

object. ReadBuffer(start As Long, _
    size As Long, _
    buffer As Any, _
    flags As CONST_DSCBLOCKFLAGS)

파라미터

object
DirectSoundCaptureBuffer 오브젝트를 나타내는오브젝트식.
start
버퍼의 선두로부터 읽어들여 시작 위치까지의 오프셋(offset). 단위는 바이트.
size
읽어들이는 버퍼 부분의 사이즈. 단위는 바이트. 사운드 버퍼는 개념적으로는 순환 버퍼이므로, 이 값은 버퍼의선두로부터 끝까지의 바이트수보다 커질 수도 있다. DSCBLOCK_ENTIREBUFFER 정수를 flags 인수로 설정 하면, 이 파라미터는 무시된다.
buffer
읽어들이는 데이터를 보관 유지하는 변수. 보통 이것은 바이트의 배열이며, 배열의 최초의 요소를 건네준다.
flags
CONST_DSCBLOCKFLAGS 열거의 정수의 어느쪽이든을 지정한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED


DirectSoundCaptureBuffer.SetNotificationPositions

DirectSoundCaptureBuffer.SetNotificationPositions 메소드는, 통지 이벤트가 시그널 송신되는 버퍼의 위치를 설정한다. 현재의 read 위치가 통지 위치에 도달 하면, 이벤트가 시그널 송신된다.

object. SetNotificationPositions(nElements As Long, _
    psa() As DSBPOSITIONNOTIFY)

파라미터

object
DirectSoundCaptureBuffer 오브젝트를 나타내는오브젝트식.
nElements
psa 배열의 요소수.
psa
DSBPOSITIONNOTIFY 형의 배열.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

참조

DirectSoundCaptureBuffer.GetCurrentPosition


DirectSoundCaptureBuffer.Start

DirectSoundCaptureBuffer.Start 메소드는, 버퍼에의 데이터의 캡춰 링을 시작 한다. 캡춰 버퍼가 이미 캡춰 상태에 있는 경우에는, 이 메소드는 아무것도 하지 않는다.

object. Start(flags As CONST_DSCBSTARTFLAGS)

파라미터

object
DirectSoundCaptureBuffer 오브젝트를 나타내는오브젝트식.
flags
사운드 데이터를 캡춰 링 하면나무의 캡춰 버퍼의 동작을 지정하는 플래그. CONST_DSCBSTARTFLAGS 열거의 정수의 어느쪽이든을 지정한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_INVALIDPARAM
DSERR_NODRIVER
DSERR_OUTOFMEMORY


DirectSoundCaptureBuffer.Stop

DirectSoundCaptureBuffer.Stop 메소드는, 데이터의 캡춰를 정지한다. 캡춰 버퍼가 이미 정지하고 있는 경우는, 이 메소드는 아무것도 하지 않는다.

object. Stop()

파라미터

object
DirectSoundCaptureBuffer 오브젝트를 나타내는오브젝트식.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_NODRIVER
DSERR_OUTOFMEMORY


DirectSoundCaptureBuffer.WriteBuffer

DirectSoundCaptureBuffer.WriteBuffer 메소드는, 오디오 데이터를 보관 유지하는 어플리케이션 버퍼로부터, 사운드 캡춰 버퍼의 세그먼트(segment)에의 쓰기를 실시한다.

object. WriteBuffer(start As Long, _
    size As Long, _
    buffer As Any, _
    flags As CONST_DSCBLOCKFLAGS)

파라미터

object
DirectSoundCaptureBuffer 오브젝트를 나타내는오브젝트식.
start
버퍼의 선두로부터 쓰기를 시작 하는 위치까지의 오프셋(offset). 단위는 바이트.
size
읽어들이는 버퍼 부분의 사이즈. 단위는 바이트. 사운드 버퍼는 개념적으로 순환 버퍼이므로, 이 값은 버퍼의선두로부터 끝까지의 바이트수보다 커질 수도 있다. DSCBLOCK_ENTIREBUFFER 를 flags 파라미터로 설정 하면, 이 파라미터는 무시된다.
buffer
캡춰 버퍼에 기입하는 데이터를 보관 유지하는 변수. 보통 이 값은 바이트의 배열이며, 배열의 최초의 요소를 건네준다.
flags
CONST_DSCBLOCKFLAGS 열거의 정수의 어느쪽이든을 지정한다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 다음의 몇개의 에러 코드가 설정된다.

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED


DirectSoundEnum 클래스

DirectSoundEnum 클래스의 오브젝트는, DirectSound 로 이용 가능한 디바이스의 콜렉션을 나타낸다. DirectX7.GetDSEnum 메소드를 호출해 이 오브젝트를 취득한다.

이 클래스에는 이하의 메소드가 있다.

정보 | GetCount
 | GetDescription
 | GetGuid
 | GetName


DirectSoundEnum.GetCount

DirectSoundEnum.GetCount 메소드는, 열거내의 디바이스수를 취득한다.

object. GetCount() As Long

파라미터

object
DirectSoundEnum 오브젝트를 나타내는오브젝트식.

반환값

성공하면 열거내의 엔트리수를 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectSoundEnum.GetDescription

DirectSoundEnum.GetDescription 메소드는, 열거내의 디바이스의 드라이버 기술을 취득한다.

object. GetDescription(index As Long) As String

파라미터

object
DirectSoundEnum 오브젝트를 나타내는오브젝트식.
index
열거내의 디바이스의 인덱스.

반환값

성공하면 디바이스의 드라이버 기술을 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.


DirectSoundEnum.GetGuid

DirectSoundEnum.GetGuid 메소드는, 열거내의 디바이스의 유니크 식별자를 취득한다.

object. GetGuid(index As Long) As String

파라미터

object
DirectSoundEnum 오브젝트를 나타내는오브젝트식.
index
열거내의 디바이스의 인덱스.

반환값

성공하면 디바이스의 GUID 를 캐릭터 라인 형식에서 돌려준다.

에러 코드

실패하면 에러가 발생해,Err.Number 가 설정된다.

참조

GUID 의 사용


DirectSoundEnum.GetName

DirectSoundEnum.GetName 메소드는, 열거내의 디바이스 드라이버의 이름을 돌려준다.

object. GetName(index As Long) As String

파라미터

object
DirectSoundEnum 오브젝트를 나타내는오브젝트식.
index
열거내의 디바이스의 인덱스.

반환값

성공하면 디바이스 드라이버명을 돌려준다. 이것은 일반적인 디바이스명은 아니고,DirectSoundEnum.GetDescription 에 의해 돌려주어진다.

에러 코드

실패하면 에러가 발생해,Err.Number 에 DSERR_INVALIDPARAM 가 설정된다.


형

여기에서는, DirectSound 가 사용하는 이하의 형태의 레퍼런스 정보를 제공한다.

  • DS3DBUFFER
  • DS3DLISTENER
  • DSBCAPS
  • DSBPOSITIONNOTIFY
  • DSBUFFERDESC
  • DSCAPS
  • DSCBCAPS
  • DSCBUFFERDESC
  • DSCCAPS
  • DSCURSORS
  • WAVEFORMATEX


DS3DBUFFER

DS3DBUFFER 형은, 3D 사운드 버퍼의 위치, 방향, 동작을 기술한다. 이 형태는,DirectSound3DBuffer.GetAllParameters 와 DirectSound3DBuffer.SetAllParameters 의 각 메소드와 함께 사용된다.

Type DS3DBUFFER
    lConeOutsideVolume As Long
    lInsideConeAngle As Long
    lMode As CONST_DS3DMODEFLAGS
    lOutsideConeAngle As Long
    maxDistance As Single
    minDistance As Single
    vConeOrientation As D3DVECTOR
    vPosition As D3DVECTOR
    vVelocity As D3DVECTOR
End Type

멤버

lConeOutsideVolume
사운드 콘 외부 볼륨.
lInsideConeAngle
안쪽 사운드 프로젝션 콘의 각도.
lMode
설정되는 3D 사운드 처리 모드. CONST_DS3DMODEFLAGS 열거의 정수의 언젠가이다.
lOutsideConeAngle
외측 사운드 프로젝션 콘의 각도.
maxDistance
최대 거리.
minDistance
최소 거리.
vConeOrientation
사운드 프로젝션 콘의 방향을 기술하는 D3DVECTOR 형.
vPosition
버퍼의 위치를 기술하는 D3DVECTOR 형.
vVelocity
버퍼의 속도를 기술하는 D3DVECTOR 형.


DS3DLISTENER

DS3DLISTENER 형은, 3D 글로벌 파라미터와 청취자의 프로퍼티를 기술한다. 이 형태는,DirectSound3DListener.GetAllParameters 와 DirectSound3DListener.SetAllParameters 의 각 메소드와 함께 사용된다.

Type DS3DLISTENER
    distanceFactor As Single
    dopplerFactor As Single
    rolloffFactor As Single
    vOrientFront As D3DVECTOR
    vOrientTop As D3DVECTOR
    vPosition As D3DVECTOR
    vVelocity As D3DVECTOR
End Type

멤버

distanceFactor
거리 단위에서의 미터수.
dopplerFactor
속도를 보관 유지하는 버퍼에 대한 돕라시후트에 적용되는 계수.
rolloffFactor
거리에 의한 사운드의 감쇠에 적용되는 계수.
vOrientFront
청취자의 전방향을 기술하는 D3DVECTOR 형.
vOrientTop
청취자의 윗방향을 기술하는 D3DVECTOR 형.
vPosition
청취자의 위치를 기술하는 D3DVECTOR 형.
vVelocity
청취자의 속도를 기술하는 D3DVECTOR 형.


DSBCAPS

DSBCAPS 형은,DirectSoundBuffer 오브젝트의 능력을 기술한다. 이 형태는,DirectSoundBuffer.GetCaps 메소드로 사용된다.

Type DSBCAPS
    lBufferBytes As Long
    lFlags As CONST_DSBCAPSFLAGS
    lPlayCpuOverhead As Long
    lUnlockTransferRate As Long
End Type

멤버

lBufferBytes
버퍼의 사이즈. 단위는 바이트.
lFlags
CONST_DSBCAPSFLAGS 열거의 정수의 1 개 또는 복수를 지정한다.
lPlayCpuOverhead
처리의 오버헤드. 이것은, 사운드 버퍼를 믹싱 하는데 필요한 메인 처리 사이클의 퍼센티지로서 지정된다. 하드웨어 버퍼의 경우, 사운드 디바이스가 믹싱을 실시하므로, 이 값은 0 이다. 소프트웨어 버퍼의 경우, 이 값은 버퍼 포맷과 시스템 프로세서의 속도에 의존한다.
lUnlockTransferRate
데이터를 버퍼 메모리에 전송 하는 속도. 단위는 1 초 쯤의 킬로바이트 (KB/s).

주의

DSBCAPS 형은,DirectSound.CreateSoundBuffer 메소드에게 건네지는 DSBUFFERDESC 형을 닮은 정보를 보관 유지하고 있다.

DSBCAPS 형의 lFlags 멤버가 보관 유지하는 플래그는,DSBUFFERDESC 형으로 사용되는 플래그와 같은 것이다. 유일한 차이는,DSBCAPS 형에서는 버퍼 메모리의 장소에 응해 DSBCAPS_LOCHARDWARE 과 DSBCAPS_LOCSOFTWARE 의 어느 쪽인가의 플래그가 지정되는 것이다. DSBUFFERDESC 형에서는 이러한 플래그는 옵션이며, 플래그의 지정에 응해, 버퍼를 하드웨어와 소프트웨어의 어딘가에 강제적으로 배치할 수 있다.


DSBPOSITIONNOTIFY

DSBPOSITIONNOTIFY 형은,DirectSoundBuffer.SetNotificationPositions 와 DirectSoundCaptureBuffer.SetNotificationPositions 의 각 메소드에 의해 사용된다.

Type DSBPOSITIONNOTIFY
    hEventNotify As Long
    lOffset As Long
End Type

멤버

hEventNotify
지정의 오프셋(offset)에 이르렀을 때에 시그널 송신하는 이벤트에의 핸들. DirectX7.CreateEvent 메소드를 사용해 이 핸들을 취득한다.
lOffset
버퍼의 선두로부터, 통지 이벤트가 방아쇠 되는 장소까지의 오프셋(offset), 또는 DSBPN_OFFSETSTOP. 「주의」를 참조할것.

주의

lOffset 멤버내에서 값 DSBPN_OFFSETSTOP 가 설정되어 있는 경우, 재생 또는 캡춰가 버퍼의 마지막에 달했다 (그리고 재생 또는 캡춰가 루프 하고 있지 않다)인가, 어플리케이션이 DirectSoundBuffer.Stop 또는 DirectSoundCaptureBuffer.Stop 의 어느 쪽인가의 메소드를 호출했던 것이 원인으로, 재생 또는 캡춰가 정지 하면, 이벤트가 시그널 송신된다.

음성 관리 플래그와 함께 DSBCAPS_LOCDEFER 와 DSBCAPS_NOTIFY 를 사용하고 있는 경우는, 통지를 보관 유지하는 사운드는 설정할 수 있지만, 도달하는 일 없이 음성 관리에 의해 종료되는 일도 있다. 이 경우, 통지 이벤트는 발생하지 않는다.


DSBUFFERDESC

DSBUFFERDESC 형은, 새로운 DirectSoundBuffer 오브젝트의 필요한 특징을 기술한다. 이 형태는,DirectSound.CreateSoundBuffer 메소드에 의해 사용된다.

Type DSBUFFERDESC
    lBufferBytes As Long
    lFlags As CONST_DSBCAPSFLAGS
End Type

멤버

lBufferBytes
버퍼의 사이즈. 단위는 바이트. 프라이머리 버퍼를 생성 하면나무는, 이 값은 0 이 아니면 안된다. 세컨드리 버퍼의 사이즈는, 4 로부터 &H0FFFFFFF (268,435,455)까지의 범위가 아니면 안된다.
lFlags
버퍼의 능력을 식별하는 플래그. 0, 또는 CONST_DSBCAPSFLAGS 열거의 정수의 1 개 또는 복수를 지정한다.

주의

lFlags 멤버로 사용되는 DSBCAPS_LOCHARDWARE 과 DSBCAPS_LOCSOFTWARE 의 각 플래그는 옵션이며, 서로 배타적이다. DSBCAPS_LOCHARDWARE 는, 강제적으로 버퍼를 사운드 카드로 배치된 메모리에 배치한다. DSBCAPS_LOCSOFTWARE 는, 가능하면, 강제적으로 버퍼를 메인 시스템 메모리에 배치한다.

DSBCAPS_CTRLPOSITIONNOTIFY 플래그로 생성 된 사운드 버퍼는, 통지 이벤트를 설정해야 한다. 이 플래그로 사운드 버퍼를 생성 해, 아무것도 통지를 설정하지 않는 경우, 동작은 정의되지 않는다.


DSCAPS

DSCAPS 형은,DirectSound.GetCaps 메소드가 사용하는 DirectSound 디바이스의 능력을 지정한다.

Type DSCAPS
    lFlags As CONST_DSCAPSFLAGS
    lFreeHw3DAllBuffers As Long
    lFreeHw3DStaticBuffers As Long
    lFreeHw3DStreamingBuffers As Long
    lFreeHwMemBytes As Long
    lFreeHwMixingAllBuffers As Long
    lFreeHwMixingStaticBuffers As Long
    lFreeHwMixingStreamingBuffers As Long
    lMaxContigFreeHwMemBytes As Long
    lMaxHw3DAllBuffers As Long
    lMaxHw3DStaticBuffers As Long
    lMaxHw3DStreamingBuffers As Long
    lMaxHwMixingAllBuffers As Long
    lMaxHwMixingStaticBuffers As Long
    lMaxHwMixingStreamingBuffers As Long
    lMaxSecondarySampleRate As Long
    lMinSecondarySampleRate As Long
    lPlayCpuOverheadSwBuffers As Long
    lPrimaryBuffers As Long
    lReserved1 As Long
    lReserved2 As Long
    lTotalHwMemBytes As Long
    lUnlockTransferRateHwBuffers As Long
End Type

멤버

lFlags
디바이스의 능력. CONST_DSCAPSFLAGS 열거로부터의 정수의 1 개 또는 복수를 지정한다.
lFreeHw3DallBuffers,lFreeHw3DstaticBuffers,lFreeHw3DStreamingBuffers
비어 또는 미할당의 디바이스의 하드웨어 3D 정정도 능력의 기술.
lFreeHwMemBytes
사운드 카드의 빈메모리의 사이즈. 단위는 바이트.
lFreeHwMixingAllBuffers, lFreeHwMixingStaticBuffers,lFreeHwMixingStreamingBuffers
비어 또는 미할당의 디바이스의 하드웨어 믹싱 능력의 기술. 어플리케이션은 이러한 값을 사용해, 세컨드리 사운드 버퍼의 할당에 하드웨어 리소스가 이용 가능한가 어떤가를 판단할 수 있다. 또, 최대의 믹싱 능력을 지정하는 멤버와 이러한 값을 비교 하면, 이미 할당할 수 있고 있는 리소스를 결정할 수 있다.
lMaxContigFreeHwMemBytes
사운드 카드 건성나무 메모리 가운데, 최대의 연속 블록의 사이즈. 단위는 바이트.
lMaxHw3DallBuffers,lMaxHw3DstaticBuffers,lMaxHw3DStreamingBuffers
디바이스의 하드웨어 3D 정정도 능력의 기술.
lMaxHwMixingAllBuffers
하드웨어로 믹싱 할 수 있는 버퍼의 합계수. 이 멤버는 lMaxHwMixingStaticBuffers 와 lMaxHwMixingStreamingBuffers 의 합계보다 작은 값을 취한다. 리소스의 트레이드 오프가 자주 발생한다.
lMaxHwMixingStaticBuffers
스태틱 사운드 버퍼의 최대수.
lMaxHwMixingStreamingBuffers
스트림 사운드 버퍼의 최대수.
LMaxSecondarySampleRate,lMinSecondarySampleRate
이 디바이스의 하드웨어 세컨드리 사운드 버퍼가 지원 하는 최소와 최대의 샘플링 레이트의 사양.
lPlayCpuOverheadSwBuffers
(메인 시스템 메모리내의) 소프트웨어 버퍼를 믹싱 하는데 필요한 처리 오버헤드를, CPU 퍼센티지로 기술한 값. 이 값은, 버스 타입, 프로세서 타입, 및 클럭 속도에 응해 변화한다.

소프트웨어 버퍼의 언락 전송 속도는, 데이터를 어디에도 전송 할 필요가 없기 때문에 0 이다. 같이 하드웨어 버퍼의 재생 오버헤드도, 믹싱이 사운드 디바이스에 의해 처리되기 (위해)때문에 0 이다.

lPrimaryBuffers
지원 되고 있는 프라이머리 버퍼의 수. 이 값은 항상 1 이다.
lReserved1,lReserved2
장래의 사용에 예약.
lTotalHwMemBytes
스태틱 사운드 버퍼를 보관 유지하는 사운드 카드 위에의 메모리 용량의 사이즈. 단위는 바이트.
lUnlockTransferRateHwBuffers
하드웨어 스태틱 사운드 버퍼에의 데이터 전송 속도. 단위는 1 초 쯤의 킬로바이트 (KB/s).


DSCBCAPS

DSCBCAPS 형은, 캡춰 버퍼의 능력을 기술한다. 이 형태는,DirectSoundCaptureBuffer.GetCaps 메소드에 의해 사용된다.

Type DSCBCAPS
    lBufferBytes As Long
    lFlags As CONST_DSCBCAPSFLAGS
    lReserved As Long
End Type

멤버

lBufferBytes
캡춰 버퍼의 사이즈. 단위는 바이트.
lFlags
디바이스 능력을 기술하는 플래그. CONST_DSCBCAPSFLAGS 열거의 정수의 어느쪽이든을 지정한다.
lReserved
장래의 사용에 예약.


DSCBUFFERDESC

DSCBUFFERDESC 형은, 캡춰 버퍼를 기술한다. 이 형태는,DirectSoundCapture.CreateCaptureBuffer 메소드에 의해 사용된다.

Type DSCBUFFERDESC
    fxFormat As WAVEFORMATEX
    lBufferBytes As Long
    lFlags As CONST_DSCBCAPSFLAGS
End Type

멤버

fxFormat
데이터의 캡춰에 사용하는 포맷을 보관 유지하는 WAVEFORMATEX 형.
lBufferBytes
생성 되는 캡춰 버퍼의 사이즈. 단위는 바이트.
lFlags
디바이스의 능력을 지정하는 플래그. CONST_DSCBCAPSFLAGS 열거의 정수의 어느쪽이든을 지정한다.


DSCCAPS

DSCCAPS 형은, 캡춰 디바이스의 능력을 기술한다. 이 형태는,DirectSoundCapture.GetCaps 메소드에 의해 사용된다.

Type DSCCAPS
    lChannels As Long
    lFlags As CONST_DSCCAPSFLAGS
    lFormats As CONST_WAVEFORMATFLAGS
End Type

멤버

lChannels
디바이스가 지원 하는 채널수. 1 은 단청의, 2 는 스테레오를 의미한다. 이하 같이이다.
lFlags
디바이스의 능력. CONST_DSCCAPSFLAGS 열거의 멤버의 어느쪽이든을 지정한다.
lFormats
지원 되고 있는 표준 포맷. CONST_WAVEFORMATFLAGS 열거의 정수의 1 개 또는 복수를 지정한다.


DSCURSORS

DSCURSORS 형은,DirectSoundBuffer.GetCurrentPosition 와 DirectSoundCaptureBuffer.GetCurrentPosition 의 각 메소드에 의해 사용된다.

Type DSCURSORS
    lPlay As Long
    lWrite As Long
End Type

멤버

lPlay
DirectSoundBuffer 의 현재 플레이 포지션, 또는 DirectSoundCaptureBuffer 의 현재의 캡춰 위치.
lWrite
DirectSoundBuffer 의 현재 라이트 포지션, 또는 DirectSoundCaptureBuffer 오브젝트의 현재의 read 위치. 이 정도치는 사운드 버퍼내의 오프셋(offset)이며, 바이트 단위로 지정된다.

주의

값은 버퍼의 선두로부터의 오프셋(offset)이며, 단위는 바이트이다.

lPlay 가 나타내는 커서는,lWrite 가 나타내는 커서의 불과 전방에 있다. 2 개의 커서간의 버퍼 부분은, 읽고 쓰기의 준비가 되어 있지 않다. lWrite 까지의 위치에서는, 어플리케이션은 캡춰 버퍼로부터의 데이터의 read와 세컨드리 버퍼에의 데이터의 쓰기를 안전하게 실시할 수 있다.


WAVEFORMATEX

WAVEFORMATEX 형은, 웨이브 폼 오디오 데이터의 포맷을 정의한다.

Type WAVEFORMATEX
    lAvgBytesPerSec As Long
    lExtra As Long
    lSamplesPerSec As Long
    nBitsPerSample As Integer
    nBlockAlign As Integer
    nChannels As Integer
    nFormatTag As Integer
    nSize As Integer
End Type

멤버

lAvgBytesPerSec
포맷용으로 요구된 평균 데이터 전송 속도. 단위는 1 초 쯤의 바이트수이다. nFormatTag 가 WAVE_FORMAT_PCM 의 경우,nAvgBytesPerSec 는 lSamplesPerSec 와 nBlockAlign 의 적에 동일해진다.
lExtra
미사용. 0 으로 설정한다.
lSamplesPerSec
각 채널의 재생이나 녹음에 있어서의 샘플링 레이트. 단위는 1 초 쯤의 샘플링 회수 (헤르쯔). nFormatTag 가 WAVE_FORMAT_PCM 의 경우,lSamplesPerSec 의 보통의 값은 8.0 kHz, 11.025 kHz, 22.05 kHz, 및 44.1 kHz 이다.
nBitsPerSample
샘플링 근처의 비트수. nFormatTag 가 WAVE_FORMAT_PCM 의 경우,nBitsPerSample 는 8 이나 16 이 아니면 안된다.
nBlockAlign
브록크아라이먼트. 단위는 바이트. 브록크아라이먼트는,nFormatTag 포맷 타입의 데이터의 최소단위이다. nFormatTag 가 WAVE_FORMAT_PCM 의 경우,nBlockAlign 는 8 (바이트 근처의 비트수)으로 나눈 nChannels 와 nBitsPerSample 의 적에 동일해진다.

버퍼에 읽고 쓰기되는 데이터는, 항상 블록의 선두에서 시작 해야 한다. 예를 들어, PCM 데이터의 재생을, 샘플의 중간, 즉 비블록 정렬의 경계로부터 시작 하는 것은 실수이다.

nChannels
웨이브 폼 오디오 데이터의 채널수. 단청의 데이터는 1 개의 채널을 사용해, 스테레오 데이터는 2 개의 채널을 사용한다.
nFormatTag
웨이브 폼 오디오 포맷의 타입. DirectSound 에서는, 이 멤버가 항상 WAVE_FORMAT_PCM 가 아니면 안된다.
nSize
추가 포맷 정보의 사이즈. 단위는 바이트. WAVE_FORMAT_PCM 포맷에서는, 이 멤버는 무시된다.


열거

DirectSound 는 열거를 사용해, Visual Basic 의 스테이트먼트 보완 기능을 이용해 정수를 그룹화 한다. DirectSound 로 사용하는 열거를 이하에 나타낸다.

  • CONST_DS3DAPPLYFLAGS
  • CONST_DS3DMODEFLAGS
  • CONST_DSBCAPSFLAGS
  • CONST_DSBLOCKFLAGS
  • CONST_DSBPLAYFLAGS
  • CONST_DSBSTATUSFLAGS
  • CONST_DSCAPSFLAGS
  • CONST_DSCBCAPSFLAGS
  • CONST_DSCBLOCKFLAGS
  • CONST_DSCBSTARTFLAGS
  • CONST_DSCBSTATUSFLAGS
  • CONST_DSCCAPSFLAGS
  • CONST_DSOUND
  • CONST_DSSCLFLAGS
  • CONST_DSSPEAKERFLAGS
  • CONST_WAVEFORMATFLAGS


CONST_DS3DAPPLYFLAGS

CONST_DS3DAPPLYFLAGS 열거는,DirectSound3DBuffer 와 DirectSound3DListener 의 각 클래스의 다양한 메소드에 대한 파라미터로서 사용된다. 이 열거의 멤버는, 새로운 설정을 적용 하면나무의 지정에 사용된다.

Enum CONST_DS3DAPPLYFLAGS
    DS3D_DEFERRED  = 1
    DS3D_IMMEDIATE = 0
End Enum
DS3D_DEFERRED
어플리케이션이 DirectSound3DListener.CommitDeferredSettings 메소드를 호출할 때까지 설정을 적용하지 않는다.
DS3D_IMMEDIATE
즉시로 설정을 적용한다.

주의

몇개의 파라미터를 곧바로 변경하는 경우는, 그것들에 DS3D_DEFERRED 의 플래그를 붙여 1 회의 호출로 위탁 하면보다 효율적이다.


CONST_DS3DMODEFLAGS

CONST_DS3DMODEFLAGS 열거는,DirectSound3DBuffer.GetMode 과 DirectSound3DBuffer.SetMode 의 각 메소드로 사용되어 3D 사운드 처리의 조작 모드의 설정과 취득을 실시한다.

Enum CONST_DS3DMODEFLAGS
    DS3DMODE_DISABLE      = 2
    DS3DMODE_HEADRELATIVE = 1
    DS3DMODE_NORMAL       = 0
End Enum
DS3DMODE_DISABLE
3D 사운드 처리는 무효가 된다. 사운드는, 청취자의 머릿속심으로 발생하고 있도록(듯이) 들린다.
DS3DMODE_HEADRELATIVE
사운드 파라미터 (위치, 속도, 및 방향)는, 청취자의 파라미터에 대한 상대적인 것이다. 이 모드에서는, 청취자의 파라미터가 변화했을 때에 사운드의 절대 파라미터가 갱신되므로, 상대 파라미터는 일정으로 유지된다.
DS3DMODE_NORMAL
사운드 파라미터는, 월드 스페이스에 대한 상대적인 것이다. 이것은 디폴트의 모드이다.


CONST_DSBCAPSFLAGS

CONST_DSBCAPSFLAGS 열거는,DSBCAPS 와 DSBUFFERDESC 의 각 형의 lFlags 멤버로 사용되어 버퍼의 능력을 지정한다.

Enum CONST_DSBCAPSFLAGS
    DSBCAPS_CTRL3D              =     16 (&H10)
    DSBCAPS_CTRLFREQUENCY       =     32 (&H20)
    DSBCAPS_CTRLPAN             =     64 (&H40)
    DSBCAPS_CTRLPOSITIONNOTIFY  =    256
    DSBCAPS_CTRLVOLUME          =    128 (&H80)
    DSBCAPS_GETCURRENTPOSITION2 =  65536 (&H10000)
    DSBCAPS_GLOBALFOCUS         =  32768 (&H8000)
    DSBCAPS_LOCHARDWARE         =      4
    DSBCAPS_LOCSOFTWARE         =      8
    DSBCAPS_MUTE3DATMAXDISTANCE = 131072 (&H20000)
    DSBCAPS_PRIMARYBUFFER       =      1
    DSBCAPS_STATIC              =      2
    DSBCAPS_STICKYFOCUS         =  16384 (&H4000)
End Enum
DSBCAPS_CTRL3D
버퍼는 3D 컨트롤을 사용한다.
DSBCAPS_CTRLFREQUENCY
버퍼는 주파수 컨트롤 능력을 갖추지 않으면 안 된다.
DSBCAPS_CTRLPAN
버퍼는 팬 컨트롤 능력을 갖추지 않으면 안 된다.
DSBCAPS_CTRLPOSITIONNOTIFY
버퍼는 위치 통지 능력을 갖추지 않으면 안 된다. 「주의」를 참조할것.
DSBCAPS_CTRLVOLUME
버퍼는 음량 조절 능력을 갖추지 않으면 안 된다.
DSBCAPS_GETCURRENTPOSITION2
DirectSoundBuffer.GetCurrentPosition 가 재생 커서의 새로운 동작을 사용해야 하는 것인 것을 나타낸다. DirectX for Visual Basic 어플리케이션에서는, 항상 이 플래그를 설정한다.
DSBCAPS_GLOBALFOCUS
버퍼는 글로벌인 사운드 버퍼이다. 이 플래그를 설정 하면, 유저가 다른 어플리케이션에 포커스를 이동해, 그 새로운 어플리케이션이 DirectSound 를 사용하는 경우에서도, DirectSound 를 사용하고 있는 어플리케이션은 계속해 그 버퍼를 재생할 수 있다. 예외는, 협조 레벨로 DSSCL_EXCLUSIVE 또는 DSSCL_WRITEPRIMARY 플래그를 설정한 DirectSound 어플리케이션에 포커스를 이동했을 경우이다. 이 경우, 다른 어플리케이션으로부터의 글로벌인 사운드는 들리지 않게 된다.
DSBCAPS_LOCHARDWARE
버퍼는 하드웨어 믹싱을 사용한다. 디바이스가 하드웨어 믹싱을 지원 하고 있지 않는 경우나, 필요한 하드웨어 메모리가 이용 불가능한 경우는,DirectSound.CreateSoundBuffer 메소드의 호출은 실패한다. 어플리케이션은, 이 버퍼가 믹싱 채널을 이용 가능하다라고 보증할 필요가 있다. 이 상황은 보증되어 있지 않다.
DSBCAPS_LOCSOFTWARE
DSBCAPS_STATIC 가 지정되고 있어, 하드웨어 리소스가 이용 가능해도, 버퍼를 소프트웨어 메모리에 배치해, 소프트웨어 믹싱을 사용하도록(듯이) 한다.
DSBCAPS_MUTE3DATMAXDISTANCE
최대 거리를 넘으면(자) 버퍼의 재생이 정지하므로, 프로세서 시간을 소비하고있고로 해결된다.
DSBCAPS_PRIMARYBUFFER
버퍼가 프라이머리 사운드 버퍼인 것을 나타낸다. 이 값을 지정하지 않는 경우, 세컨드리 사운드 버퍼가 생성 된다.
DSBCAPS_STATIC
사운드 카드의 메모리가 이용 가능한 경우, 버퍼가 거기에 놓여지는 것을 나타낸다. 버퍼를 강제적으로 메모리 (보통은 드라이버가 관리하는 시스템 메모리)에 배치하는 DSBCAPS_LOCHARDWARE 와는 다르다.
DSBCAPS_STICKYFOCUS
사운드 버퍼의 포커스의 동작을 변경한다. 유저가 DirectSound 를 사용하지 않은 다른 어플리케이션으로 전환했을 경우에서도, DirectSound 를 사용하고 있는 어플리케이션은 스틱키 포커스 버퍼의 재생을 속행할 수 있다. 이 상태에서는 어플리케이션의 표준 버퍼는 무음이 되지만, 스틱키 포커스 버퍼는 계속해 소리를 낸다. 유저가 다른 어플리케이션을 사용하면서, 게임 이외의 어플리케이션의 사운드 트랙을 (듣)묻고 싶다고 생각하는 경우에 도움이 된다. 그러나, 유저가 다른 DirectSound 어플리케이션으로 전환하면(자), 지금까지의 어플리케이션의 모든 사운드 버퍼, 이 경우는 표준 버퍼와 스틱키 포커스 버퍼의 양쪽 모두가 무음이 된다.

주의

VxD 드라이버에서는, 사운드 버퍼가 DSBCAPS_CTRLPOSITIONNOTIFY 로 생성 되는 경우, 이 버퍼는 항상 소프트웨어 버퍼가 된다. 이것은, VxD 드라이버 모델이 통지 인터페이스를 지원 하지 않기 때문이다. 하드웨어가 이용 가능한 경우, WDM 드라이버에 의해, 위치 통지 가능한 버퍼가 하드웨어에 존재하는 일이 있다. 이 플래그 설정으로 생성 된 버퍼의 재생중은, DSBPLAY_LOCHARDWARE 플래그에 의한 DirectSoundBuffer.Play 의 호출은 실패한다.

DSBCAPS_CTRLPOSITIONNOTIFY 플래그로 생성 된 사운드 버퍼에는, 통지 이벤트를 설정해야 한다. NOTIFY 플래그로 사운드 버퍼를 생성 해, 아무것도 통지를 설정하지 않으면 동작이 정의되지 않고, 사운드가 2 회 재생될 가능성이 있다. 따라서, 어플리케이션은 통지 이벤트가 설정될 때까지, DSBCAPS_CTRLPOSITIONNOTIFY 를 사용해서는 안된다.


CONST_DSBLOCKFLAGS

CONST_DSBLOCKFLAGS 열거의 멤버는,DirectSoundBuffer.ReadBuffer 와 DirectSoundBuffer.WriteBuffer 의 각 메소드의 flags 파라미터로 사용되어 버퍼의 read와 쓰기 위치를 지정한다.

Enum CONST_DSBLOCKFLAGS
    DSBLOCK_DEFAULT         = 0
    DSBLOCK_ENTIREBUFFER    = 2
    DSBLOCK_FROMWRITECURSOR = 1
End Enum
DSBLOCK_DEFAULT
start 파라미터로 지정된 위치로부터의 read와 쓰기를 실시한다.
DSBLOCK_FROMWRITECURSOR
현재 라이트 포지션에 쓰기, 현재의 read 위치로부터 읽어들인다. 이 결과,DirectSoundBuffer.GetCurrentPosition 메소드의 호출이 불필요하게 된다. start 파라미터는 무시된다.
DSBLOCK_ENTIREBUFFER
버퍼 전체로부터의 read와 버퍼 전체에의 쓰기를 실시한다. size 파라미터는 무시된다.


CONST_DSBPLAYFLAGS

CONST_DSBPLAYFLAGS 열거는,DirectSoundBuffer.Play 메소드의 flags 파라미터로 사용되어 버퍼의 재생 방법을 지정한다.

Enum CONST_DSBPLAYFLAGS
    DSBPLAY_DEFAULT = 0
    DSBPLAY_LOOPING = 1
End Enum
DSBPLAY_DEFAULT
현재 플레이 포지션으로부터 오디오 버퍼의 끝까지를 재생한다.
DSBPLAY_LOOPING
현재 플레이 포지션으로부터 버퍼의 끝까지를 재생해, 버퍼의 선두에서 재생을 재개한다. 명시적으로 정지될 때까지 재생을 속행한다.


CONST_DSBSTATUSFLAGS

CONST_DSBSTATUSFLAGS 열거의 멤버는, 버퍼의 스테이터스를 기술해,DirectSoundBuffer.GetStatus 메소드에 의해 돌려주어진다.

Enum CONST_DSBSTATUSFLAGS
    DSBSTATUS_BUFFERLOST = 2
    DSBSTATUS_LOOPING    = 4
    DSBSTATUS_PLAYING    = 1
End Enum
DSBSTATUS_BUFFERLOST
버퍼는 없어지고 있어 재생이나 락을 실시하기 전에 복원하지 않으면 안 된다.
DSBSTATUS_LOOPING
버퍼는 루프 하고 있다. 이 값이 설정되어 있지 않은 경우, 사운드 데이터의 마지막에 달하면(자) 버퍼가 정지한다. 이 값은, 항상 DSBSTATUS_PLAYING 와의 편성으로 돌려주어진다.
DSBSTATUS_PLAYING
버퍼는 재생중이다.


CONST_DSCAPSFLAGS

CONST_DSCAPSFLAGS 열거는,DSCAPS 형의 lFlags 멤버로 사용되어 디바이스의 능력을 기술한다.

Enum CONST_DSCAPSFLAGS
    DSCAPS_CERTIFIED       =   64 (&H40)
    DSCAPS_CONTINUOUSRATE  =   16 (&H10)
    DSCAPS_EMULDRIVER      =   32 (&H20)
    DSCAPS_PRIMARY16BIT    =    8
    DSCAPS_PRIMARY8BIT     =    4
    DSCAPS_PRIMARYMONO     =    1
    DSCAPS_PRIMARYSTEREO   =    2
    DSCAPS_SECONDARY16BIT  = 2048 (&H800)
    DSCAPS_SECONDARY8BIT   = 1024 (&H400)
    DSCAPS_SECONDARYMONO   =  256 (&H100)
    DSCAPS_SECONDARYSTEREO =  512 (&H200)
End Enum
DSCAPS_CERTIFIED
이 드라이버는 Microsoft 에 의해 시험과 보증을 하고 있다.
DSCAPS_CONTINUOUSRATE
이 디바이스는,lMinSecondarySampleRate 과 lMaxSecondarySampleRate 의 각 멤버값의 사이의 모든 샘플링 레이트를 지원 한다. 일반적으로 이것은, 실제의 출력 레이트가 요구된 주파수의 ±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
이 디바이스는, 하드웨어 믹싱의 스테레오 세컨드리 버퍼를 지원 한다.


CONST_DSCBCAPSFLAGS

CONST_DSCBCAPSFLAGS 열거는,DSCBCAPS 형의 lFlags 멤버로 사용되어 디바이스의 능력을 지정한다.

Enum CONST_DSCBCAPSFLAGS
    DSCBCAPS_DEFAULT    =  0
    DSCBCAPS_WAVEMAPPED = -2147483648 (&H80000000)
End Enum
DSCBCAPS_WAVEMAPPED
디바이스가 지원 하지 않는 포맷에 대해서, Win32 웨이브 맵퍼를 사용한다.


CONST_DSCBLOCKFLAGS

CONST_DSCBLOCKFLAGS 열거는,DirectSoundCaptureBuffer.ReadBuffer 와 DirectSoundCaptureBuffer.WriteBuffer 의 각 메소드에 의해 사용되어 사운드 캡춰 버퍼로부터의 read와 그 버퍼에의 쓰기를 지정한다.

Enum CONST_DSCBLOCKFLAGS
    DSCBLOCK_DEFAULT      = 0
    DSCBLOCK_ENTIREBUFFER = 1
End Enum
DSCBLOCK_DEFAULT
start 파라미터의 지정하는 오프셋(offset)로 read와 쓰기를 실시한다.
DSCBLOCK_ENTIREBUFFER
버퍼 전체의 read와 쓰기를 실시한다. size 파라미터는 무시된다. start 가 0 이 아닌 경우, 데이터 전송은 start 로 시작 해, 버퍼의 선두까지 rack-around 한다.


CONST_DSCBSTARTFLAGS

CONST_DSCBSTARTFLAGS 열거의 멤버는,DirectSoundCaptureBuffer.Start 메소드의 flags 멤버로 사용되어 사운드 데이터의 캡춰 링 때에 캡춰 버퍼의 동작을 지정한다.

Enum CONST_DSCBSTARTFLAGS
    DSCBSTART_DEFAULT = 0
    DSCBSTART_LOOPING = 1
End Enum
DSCBSTART_DEFAULT
버퍼의 마지막에 달하면(자) 캡춰는 정지한다.
DSCBSTART_LOOPING
버퍼의 마지막에 달하면(자), 선두로부터 캡춰를 재개해, 명시적으로 정지될 때까지 속행한다.


CONST_DSCBSTATUSFLAGS

CONST_DSCBSTATUSFLAGS 열거의 멤버는, 캡춰 버퍼의 스테이터스를 기술해,DirectSoundCaptureBuffer.GetStatus 메소드에 의해 돌려주어진다.

Enum CONST_DSCBSTATUSFLAGS
    DSCBSTATUS_CAPTURING = 1
    DSCBSTATUS_LOOPING   = 2
End Enum
DSCBSTATUS_CAPTURING
캡춰 버퍼는 사운드 데이터를 캡춰 하고 있다.
DSCBSTATUS_LOOPING
캡춰 버퍼는 루프 하고 있다. 이 값은, 항상 DSCBSTATUS_CAPTURING 와의 편성으로 돌려주어진다.


CONST_DSCCAPSFLAGS

CONST_DSCCAPSFLAGS 열거는,DSCCAPS 형의 lFlags 멤버로 사용되어 캡춰 디바이스 능력을 기술한다.

Enum CONST_DSCCAPSFLAGS
    DSCCAPS_DEFAULT    = 0
    DSCCAPS_EMULDRIVER = 32 (&H20)
End Enum
DSCCAPS_DEFAULT
디바이스는 DirectSound 캡춰 가능하다.
DSCCAPS_EMULDRIVER
디바이스에 대해서 이용 가능한 드라이버가 없기 때문에, 표준의 웨이브 오디오 기능이 사용되고 있다.


CONST_DSOUND

CONST_DSOUND 열거는, DirectSound 전체로 사용되는 몇개의 정수를 보관 유지한다.

Enum
    DS3D_DEFAULTCONEANGLE         = 360 (&H168)
    DS3D_DEFAULTCONEOUTSIDEVOLUME = 0
    DS3D_DEFAULTDISTANCEFACTOR    = 1
    DS3D_DEFAULTDOPPLERFACTOR     = 1
    DS3D_DEFAULTMAXDISTANCE       = 1000000000 (&H3B9ACA00)
    DS3D_DEFAULTMINDISTANCE       = 1
    DS3D_DEFAULTROLLOFFFACTOR     = 1
    DS3D_MAXCONEANGLE             = 360 (&H168)
    DS3D_MAXDISTANCEFACTOR        = 10
    DS3D_MAXDOPPLERFACTOR         = 10
    DS3D_MAXROLLOFFFACTOR         = 10
    DS3D_MINCONEANGLE             = 0
    DS3D_MINDISTANCEFACTOR        = 0
    DS3D_MINDOPPLERFACTOR         = 0
    DS3D_MINROLLOFFFACTOR         = 0
    DSBFREQUENCY_MAX              = 100000 (&H186A0)
    DSBFREQUENCY_MIN              = 100 (&H64)
    DSBFREQUENCY_ORIGINAL         = 0
    DSBPAN_CENTER                 = 0
    DSBPAN_LEFT                   = -10000 (&HFFFFD8F0)
    DSBPAN_RIGHT                  = 10000 (&H2710)
    DSBPN_OFFSETSTOP              = -1 (&HFFFFFFFF)
    DSBSIZE_MAX                   = 268435455 (&HFFFFFFF)
    DSBSIZE_MIN                   = 4
    DSBVOLUME_MAX                 = 0
    DSBVOLUME_MIN                 = -10000 (&HFFFFD8F0)
    WAVE_FORMAT_PCM               = 1
End Enum


CONST_DSSCLFLAGS

CONST_DSSCLFLAGS 열거는,DirectSound.SetCooperativeLevel 메소드의 level 파라미터로 사용되어 우선 레벨을 지정한다.

Enum CONST_DSSCLFLAGS
    DSSCL_EXCLUSIVE    = 3
    DSSCL_NORMAL       = 1
    DSSCL_PRIORITY     = 2
    DSSCL_WRITEPRIMARY = 4
End Enum
DSSCL_EXCLUSIVE
어플리케이션을 배타 레벨로 설정한다. 입력초점이 놓여져 있는 어플리케이션만이 소리를 낼 수 있다. DSBCAPS_GLOBALFOCUS 플래그가 설정되어 있는 어플리케이션의 사운드는 무음이 된다. 이 레벨로 설정된 어플리케이션은, DSSCL_PRIORITY 레벨의 모든 특권도 갖추고 있다. 이 레벨의 어플리케이션이 입력초점을 얻으면(자), DirectSound 는 전회 DirectSoundBuffer.SetFormat 메소드를 호출했을 때에 지정된 하드웨어 포맷을 복원한다.
DSSCL_NORMAL
어플리케이션을 완전하게 협조 가능한 스테이터스로 설정한다. 이 레벨에서는 가장 순조로운 multitasking와 리소스 공유의 동작을 얻을 수 있지만, 프라이머리 버퍼의 포맷의 변경은 실시하지 못하고, 출력도 디폴트의 8 비트 포맷으로 한정된다.
DSSCL_PRIORITY
어플리케이션을 우선 레벨로 설정한다. 이 협조 레벨로 설정된 어플리케이션은, 프라이머리 사운드 버퍼의 DirectSoundBuffer.SetFormat 메소드를 호출할 수 있다.
DSSCL_WRITEPRIMARY
어플리케이션을 최상정도의 우선 레벨로 설정한다. 이 어플리케이션은 프라이머리 사운드 버퍼에의 쓰기 액세스를 보관 유지한다. DirectX for Visual Basic 어플리케이션에서는 이 협조 레벨을 설정해서는 안된다.


CONST_DSSPEAKERFLAGS

CONST_DSSPEAKERFLAGS 열거는,DirectSound.GetSpeakerConfig 와 DirectSound.SetSpeakerConfig 의 각 메소드로 사용되어 스피커 구성을 지정한다.

Enum CONST_DSSPEAKERFLAGS
    DSSPEAKER_GEOMETRY_MAX    = 180 (&HB4)
    DSSPEAKER_GEOMETRY_MIN    =   5
    DSSPEAKER_GEOMETRY_NARROW =  10
    DSSPEAKER_GEOMETRY_WIDE   =  20 (&H14)
    DSSPEAKER_HEADPHONE       =   1
    DSSPEAKER_MONO            =   2
    DSSPEAKER_QUAD            =   3
    DSSPEAKER_STEREO          =   4
    DSSPEAKER_SURROUND        =   5
End Enum
DSSPEAKER_GEOMETRY_MAX
2 개의 스피커는 청취자를 중심으로서 180 번의 각도에 놓여져 있다.
DSSPEAKER_GEOMETRY_MIN
2 개의 스피커는 청취자를 중심으로서 5 번의 각도에 놓여져 있다.
DSSPEAKER_GEOMETRY_NARROW
2 개의 스피커는 청취자를 중심으로서 10 번의 각도에 놓여져 있다.
DSSPEAKER_GEOMETRY_WIDE
2 개의 스피커는 청취자를 중심으로서 20 번의 각도에 놓여져 있다.
DSSPEAKER_HEADPHONE
스피커는 헤드폰이다.
DSSPEAKER_MONO
스피커는 단청의이다.
DSSPEAKER_QUAD
스피커는 4 채널이다.
DSSPEAKER_STEREO
스피커는 스테레오이다.
DSSPEAKER_SURROUND
스피커는 환경 사운드이다.


CONST_WAVEFORMATFLAGS

CONST_WAVEFORMATFLAGS 열거는,DSCCAPS 형의 lFormats 멤버로 사용되어 지원 되는 표준 포맷을 지정한다.

Enum CONST_WAVEFORMATFLAGS
    WAVE_FORMAT_1M08 =    1
    WAVE_FORMAT_1M16 =    4
    WAVE_FORMAT_1S08 =    2
    WAVE_FORMAT_1S16 =    8
    WAVE_FORMAT_2M08 =   16 (&H10)
    WAVE_FORMAT_2M16 =   64 (&H40)
    WAVE_FORMAT_2S08 =   32 (&H20)
    WAVE_FORMAT_2S16 =  128 (&H80)
    WAVE_FORMAT_4M08 =  256 (&H100)
    WAVE_FORMAT_4M16 = 1024 (&H400)
    WAVE_FORMAT_4S08 =  512 (&H200)
    WAVE_FORMAT_4S16 = 2048 (&H800)
End Enum
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 비트


에러 코드

에러는 부의 값으로 나타내져 짜 합쳐질 것은 없다. 이 표는,DirectSound 와 DirectSoundBuffer 의 모든 메소드가 돌려줄 가능성이 있는 값의 일람이다. 개별의 메소드가 돌려주는 에러 코드의 리스트에 대해서는, 그 메소드의 기술을 참조할것.

DS_OK
요구는 성공해 완료했다.
DSERR_ALLOCATED
우선 레벨등의 리소스가 다른 호출에 의해 이미 사용중이기 (위해)때문에, 요구는 실패했다.
DSERR_ALREADYINITIALIZED
오브젝트는 이미 초기화되고 있다.
DSERR_BADFORMAT
지정한 웨이브 포맷은 지원되어 있지 않다.
DSERR_BUFFERLOST
버퍼 메모리가 없어졌기 때문에, 복원하지 않으면 안 된다.
DSERR_CONTROLUNAVAIL
호출원이 요구하는 컨트롤 (볼륨, 팬등)은 이용할 수 없다.
DSERR_GENERIC
DirectSound 서브 시스템내에서 불확정의 에러가 발생했다.
DSERR_INVALIDCALL
이 오브젝트의 현재 상태에서는, 이 함수는 유효하지 않다.
DSERR_INVALIDPARAM
무효인 파라미터가 함수에게 건네졌다.
DSERR_NOAGGREGATION
이 오브젝트는 COM 집합화를 지원 하지 않는다.
DSERR_NODRIVER
이용 가능한 사운드 드라이버가 존재하지 않는다.
DSERR_NOINTERFACE
요구된 COM 인터페이스는 이용할 수 없다.
DSERR_OTHERAPPHASPRIO
다른 어플리케이션보다 높은 우선 레벨을 가지고 있기 (위해)때문에, 이 호출은 성공하지 않았다.
DSERR_OUTOFMEMORY
DirectSound 서브 시스템은, 호출원의 요구를 완료하기 위한 충분한 메모리를 할당할 수 없었다.
DSERR_PRIOLEVELNEEDED
호출원래는, 함수를 성공시키기 위해서(때문에) 필요한 우선 레벨을 가지고 있지 않다.
DSERR_UNINITIALIZED
DirectSound 디바이스는 초기화되어 있지 않았다.
DSERR_UNSUPPORTED
호출한 함수는 이 시점에서는 지원되어 있지 않다.


DirectSound 의 툴과 샘플

여기에서는, DirectX SDK 에 포함되는 샘플 어플리케이션에 대해 설명해, DirectSound 의 사용법을 예시한다. 설명하는 내용은 다음과 같다.

  • DirectSound 툴
  • DirectSound C/C++ 샘플
  • DirectSound Visual Basic 샘플


DirectSound 툴

여기에서는, DirectSound 능력의 테스트에 사용되는 이하의 어플리케이션에 대한 정보를 나타낸다.

  • DSShow3D


DSShow3D

설명

DSShow3D 를 사용하면(자), 사운드 버퍼와 3D 청취자의 파라미터를 변경할 수 있다.

패스

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DSound\Bin

유저즈 가이드

[File] 메뉴의 [Open] 를 선택 하면, 1 개(살) 또는 복수의 짧은 사운드 파일을 열어, 그것들을 동시에 재생할 수 있다. 3D 프로퍼티에 액세스 하려면 ,［File Open］ 다이알로그 박스의 ［Create as a 3D Buffer］ 를 선택해야 하는 것에 주의 해야 한다. 향후, 이 옵션이 자동적으로 설정되도록(듯이) 하려면 ,［Option］ 메뉴의 ［Setting］ 를 선택해,［Open 3D as Default］ 를 선택한다.

파일을 이 프로그램의 아이콘에 드러그 해, 그 파일을 로드할 수도 있다. 또는, 다음의 구문에 따라 커멘드 라인으로 지정해도 괜찮다.

DSShow3D [/PLAY [/LOOP]] [file] [file] ...

/PLAY 를 지정 하면, 지정한 파일은 열었다고 동시에 재생된다. /LOOP 를 추가 하면, 그러한 파일은 루프 재생된다. 그러나, /PLAY 를 생략 해 /LOOP 만을 지정해도, 아무것도 일어나지 않는다. 파일명은 인용부호 (' ')로 둘러싸도 괜찮다.

웨이브 파일을 열 때마다, DSShow3D 는 클라이언트 윈도우에 일련의 버퍼 컨트롤을 표시한다. 모든 3D 버퍼에 적용되는 청취자의 설정은, 개별의 윈도우내에 표시된다.

사운드를 재생하려면 , 그 윈도우내의 [Play] 버튼을 클릭한다. 사운드를 연속 재생하려면 ,[Looped] 버튼을 클릭한다. 클라이언트 윈도우의 메뉴로부터 [Duplicate! ] (을)를 선택 하면, 사운드 버퍼의 복제를 생성 할 수 있다.

버퍼를 닫으려면 , 버퍼 윈도우의 [File] 메뉴로부터 [Close] 를 선택하는지, 단순하게 윈도우를 닫는다.

메인 윈도우의 [Options] 메뉴로부터 [Output Format] 를 선택 하면, 프라이머리 버퍼의 포맷을 변경할 수 있다. [Options] 메뉴의 [Settings] 를 선택 하면, 기호의 설정을 실시해, 다음에 이 어플리케이션을 기동했을 때에 그 설정을 유효하게 할 수 있다.

[3DListener Object Settings] 윈도우로 변경을 더했을 경우,[Commit] 버튼을 클릭할 때까지는 그 변경 결과는 유효하게 안 된다.


DirectSound C/C++ 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 샘플」을 참조할것.

[C++]

여기에서는, DirectSound 컴퍼넌트를 사용한 샘플 프로그램을 채택한다. 이하의 샘플 프로그램에는, DirectSound 의 사용법과 기능이 나타나고 있다.

  • AdjustSound 샘플
  • CaptureSound 샘플
  • EnumDevices 샘플
  • FullDuplexFilter 샘플
  • Play3DSound 샘플
  • PlaySound 샘플
  • PlayStreaming 샘플
  • VoiceManagement 샘플

DirectX 의 샘플에는, Microsoft® Visual C++® 의 프로젝트 워크 스페이스 파일도 포함되어 있지만, 이러한 샘플을 올바르게 컴파일 하는데 있어서, 개발 환경의 다른 설정을 검사할 필요가 생기는 일이 있다. 상세한 것에 대하여는, 「DirectX 의 샘플 및 그 외의 DirectX 어플리케이션의 컴파일」을 참조할것.


AdjustSound 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 샘플」을 참조할것.

[C++]

설명

AdjustSound 는, 스태틱 DirectSound 버퍼를 사용해 웨이브 파일을 재생하는 방법과 포커스, 주파수, 팬, 및 볼륨을 설정하는 방법을 나타낸다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DSound\Src\AdjustSound

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DSound\Bin\AdjustSound.exe

유저즈 가이드

[Sound File] 버튼을 클릭해, 웨이브 파일을 로드한다. 설정을 선택해,[Play] 버튼을 클릭한다. 사운드의 재생 그 중에서 설정을 변경할 수 있다.

프로그래밍 위에의 주의

이 샘플은, 2D 세컨드리 버퍼를 사용하는 기본적인 방법을 나타낸다.


CaptureSound 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 샘플」을 참조할것.

[C++]

설명

CaptureSound 프로그램은, DirectSound 를 사용해 사운드를 웨이브 파일에 캡춰 하는 방법을 나타낸다.

마이크로 폰, 또는 다른 오디오 입력이 필요하다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DSound\Src\CaptureSound

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DSound\Bin\CaptureSound.exe

유저즈 가이드

캡춰 포맷을 하이라이트 해,[OK] 버튼을 클릭한다. [Sound File] 버튼을 클릭해, 기존의 파일을 여는지, 새로운 파일을 생성 한다. [Record] 버튼을 클릭해 녹음을 시작 해, 같은 버튼을 클릭해 정지한다.

프로그래밍 위에의 주의

이 샘플은, 사운드의 캡춰와 웨이브 파일에의 쓰기의 기본적인 방법을 나타낸다.


EnumDevices 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 샘플」을 참조할것.

[C++]

설명

EnumDevices 프로그램은, DirectSound 와 DirectSoundCapture 디바이스를 열거하는 방법을 나타낸다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DSound\Src\EnumDevices

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DSound\Bin\EnumDevices.exe

유저즈 가이드

드롭 다운 리스트로부터 재생 및 캡춰 하는 디바이스를 선택해,[Create] 버튼을 클릭한다.

프로그래밍 위에의 주의

이 샘플 코드는,DirectSoundEnumerate ,DirectSoundCreate ,DirectSoundCaptureEnumerate ,DirectSoundCaptureCreate 함수의 사용법을 나타낸다.


FullDuplexFilter 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 샘플」을 참조할것.

[C++]

설명

FullDuplexFilter 프로그램은, DirectSound 를 사용해 전이중 오디오와 필터를 이행 하는 방법을 나타낸다.

마이크로 폰, 또는 다른 오디오 입력이 필요하다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DSound\Src\FullDuplexFilter

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DSound\Bin\FullDuplexFilter.exe

유저즈 가이드

입력 버퍼의 포맷과 다음의 출력 버퍼의 포맷을 하이라이트 한다. [OK] 버튼을 클릭한다.

이 프로그램은, 옵셔널의 필터를 유효하게 할 수 있는 다이알로그 박스를 표시해, 캡춰와 재생을 시작 할 수 있도록(듯이) 한다.

프로그래밍 위에의 주의

이 샘플은 주로, 입력 소스로서 waveIn, 출력 디바이스로서 DirectSound 를 사용해 전이중 오디오를 실현하기 위해서(때문에), 시스템에 이행 되고 있는 사운드 디바이스를 취급하는 적절한 순서를 나타내는 것을 목적으로 하고 있다.


Play3DSound 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 샘플」을 참조할것.

[C++]

설명

이 어플리케이션은, DirectSound 를 사용해 웨이브 파일을 3D 포지셔닝에 의해 재생하는 방법을 나타낸다.

패스

소스 : Mssdk\Samples\Multimedia\DSound\Src\Play3DSound

실행 가능 파일 : Mssdk\Samples\Multimedia\DSound\Bin\Play3DSound.exe

유저즈 가이드

[Sound File] 버튼을 클릭해, 웨이브 파일을 로드한다. 다음에,[Select 3-D Algorithm] 다이알로그 박스의 옵션을 선택한다. [Play] 버튼을 클릭해 사운드를 루프 재생한다. 슬라이더를 사용해 재생 프로퍼티를 조정한다. 변경을 곧바로 적용하고 싶지 않은 경우는,[Defer] 버튼을 클릭한다. 새로운 설정을 확정하는 빈도는, 이 버튼의 옆에 있는 슬라이더를 사용해 조정할 수 있다. 청취자에 대한 음원의 위치는, 그래프상에 빨강의 점으로써 표시된다. 그래프아래와 옆의 슬라이더를 사용해, 사운드의 움직임의 범위를 조정한다.

프로그래밍 위에의 주의

이 샘플은, DirectSound 의 3D 기능을 사용한 사운드의 기본적인 재생과IDirectSound3DListener::CommitDeferredSettings 를 사용해 동시에 복수의 파라미터를 변경하는 방법을 나타낸다.


PlaySound 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 샘플」을 참조할것.

[C++]

설명

이 샘플은, 스태틱 DirectSoundBuffer 를 사용해 웨이브 파일을 재생하는 방법을 나타낸다.

패스

소스 : Mssdk\Samples\Multimedia\DSound\Src\PlaySound

실행 가능 파일 : Mssdk\Samples\Multimedia\DSound\Bin\PlaySound.exe

유저즈 가이드

[Sound File] 버튼을 클릭해, 웨이브 파일을 로드한다. 다음에,[Play] 버튼을 클릭해 사운드를 재생한다. 사운드를 반복해 재생하려면 ,[Loop] 를 선택한다.

프로그래밍 위에의 주의

스트림 버퍼를 사용하는 「PlayStreaming 샘플」이라고 비교하는 것.


PlayStreaming 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 샘플」을 참조할것.

[C++]

설명

이 샘플은, 스트리밍 하는 DirectSoundBuffer 를 사용해 웨이브 파일을 재생하는 방법을 나타낸다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DSound\Src\PlayStreaming

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DSound\Bin\PlayStreaming.exe

유저즈 가이드

[Sound File] 버튼을 클릭해, 웨이브 파일을 로드한다. 다음에,[Play] 버튼을 클릭해 사운드를 재생한다. 사운드를 반복해 재생하려면 ,[Loop] 를 선택한다.

프로그래밍 위에의 주의

스태틱 버퍼를 사용하는 「PlaySound 샘플」이라고 비교하는 것.


VoiceManagement 샘플

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectSound Visual Basic 샘플」을 참조할것.

[C++]

설명

이 샘플은, DirectDound 버퍼를 재생할 경우에, 음성 할당 및 음성 관리의 플래그를 사용하는 방법을 나타낸다.

패스

소스 : (SDK 루트)\Samples\Multimedia\DSound\Src\VoiceManagement

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\DSound\Bin\VoiceManagement.exe

유저즈 가이드

[Sound File] 버튼을 클릭해, 웨이브 파일을 로드한다. 음성 관리 옵션을 선택한다. (선택한 옵션은,[Expected Behavior] 프레임으로 설명된다. ) 사운드를 반복해 재생하고 싶은 경우는,[Loop] 를 선택한다. [Play] 버튼을 클릭해 사운드의 재생을 시작 한다.

프로그래밍 위에의 주의

버퍼는, DSBCAPS_LOCDEFER 플래그를 사용해 생성 되지 않으면 안 된다. 이외의 플래그로 생성 되었을 경우는, DirectSound 는 실행시에 하드웨어 또는 소프트웨어에 버퍼를 동적으로 배치할 수 없게 된다.


DirectSound Visual Basic 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectSound C/C++ 샘플」을 참조할것.

[Visual Basic]

여기에서는, 주로 DirectSound 컴퍼넌트를 예시하는 것을 의도하고 있는, DirectX SDK 내의 어플리케이션의 요약을 제공한다. 이하의 샘플 프로그램은, DirectSound 의 사용법과 능력을 나타낸다.

  • Capture 샘플
  • Full Duplex 샘플
  • Memo 샘플
  • PlaySound 샘플
  • SoundMix 샘플
  • StreamFrom 샘플
  • StreamTo 샘플

참조

DirectSound Visual Basic 튜토리얼


Capture 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectSound C/C++ 샘플」을 참조할것.

[Visual Basic]

설명

Capture 어플리케이션은, 웨이브 입력 디바이스로부터 사운드를 캡춰 하는 방법을 나타낸다. 보통 이 디바이스는, 마이크로 폰 첨부의 사운드 카드이다.

패스

소스 : (SDK 루트)\Samples\Multimedia\VBSamples\DSound\Src\Capture

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\VBSamples\DSound\Bin\Capture.exe

유저즈 가이드

[Record] 버튼을 클릭해, 사운드를 20 초간 캡춰 하고 나서 [Stop] 버튼을 클릭한다. 버퍼를 재생할 수 있어 그 버퍼를 웨이브 파일에 보존할 수 있다.

프로그래밍 위에의 주의

사운드 데이터를 보존하기 위해서는, 프로그램은 DirectSoundBuffer.SaveToFile 메소드를 사용할 수 있도록(듯이), 출력 버퍼에 이 데이터를 카피해야 한다.


Full Duplex 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectSound C/C++ 샘플」을 참조할것.

[Visual Basic]

설명

Full Duplex 어플리케이션은, 사운드의 캡춰와 재생을 동시에 실시하는 방법을 나타낸다.

패스

소스 : (SDK 루트)\Samples\Multimedia\VBSamples\DSound\Src\Fullduplex

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\VBSamples\DSound\Bin\Fullduplex.exe

유저즈 가이드

[Select Device] 다이알로그 박스로, 입력 디바이스와 출력 디바이스를 선택한다. 사운드 카드를 사용해 재생과 녹음을 동시에 실시하려면 , 컨트롤 패널로 설정을 변경해야 하는 것에 주의 해야 한다.

[Select Formats] 다이알로그 박스로, 입력 포맷을 선택한다. 호환성이 있는 출력 포맷이 일람표 나타난다. 이 일람으로부터 1 개를 선택한다.

[Full Duplex] 윈도우로 [Run] 버튼을 클릭해, 캡춰와 재생을 시작 한다.

프로그래밍 위에의 주의

캡춰 버퍼와 재생 버퍼는 같은 사이즈이므로, 한편으로부터 읽어들여, 이제(벌써) 한편에 카피할 때, 어플리케이션은 다만 1 개의 포인터만을 보관 유지할 필요가 있다.


Memo 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectSound C/C++ 샘플」을 참조할것.

[Visual Basic]

설명

Memo 샘플은, 데이타베이스에 저장 하는 음성 메모를 녹음할 수 있다.

패스

소스 : (SDK 루트)\Samples\Multimedia\VBSamples\DSound\Src\Memo

실행 가능 파일 : 없음

유저즈 가이드

이 어플리케이션을 실행하려면 , Microsoft Data Access Components 가 시스템에 인스톨되어 있지 않으면 안 된다.

달력의 달을 변경하려면 , 화살표 버튼을 사용하는지, 지난달 혹은 다음달의 회색의 일자상을 클릭한다. 일자에 대한 [Current Memo] 다이알로그 박스를 표시하려면 , 이번달의 일자상을 더블 클릭 한다. 메모를 관리하려면 버튼을 사용한다. 메모는 30 초간 표시할 수 있다.

프로그래밍 위에의 주의

캡춰 버퍼는, 미가공의 데이터로서 데이타베이스에 기입해진다.


PlaySound 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectSound C/C++ 샘플」을 참조할것.

[Visual Basic]

설명

PlaySound 샘플은, DirectSound 버퍼의 기본적인 재생을 나타낸다.

패스

소스 : (SDK 루트)\Samples\Multimedia\VBSamples\DSound\Src\PlaySound

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\VBSamples\DSound\Bin\Vb_PlaySound.exe

유저즈 가이드

[Sound File] 버튼을 클릭해, 웨이브 파일을 로드한다. 사운드를 연속해 (듣)묻고 싶은 경우는 [Loop Sound] 를 선택하고 나서,[Play] 버튼을 클릭한다. 사운드의 재생중에 주파수, 팬, 볼륨을 조정할 수 있다.

프로그래밍 위에의 주의

이 샘플은, 파일로부터 사운드 버퍼를 생성 하는 방법, 버퍼를 재생하는 방법, 및 파라미터를 변경하는 방법을 나타낸다.


SoundMix 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectSound C/C++ 샘플」을 참조할것.

[Visual Basic]

설명

SoundMix 어플리케이션은, 복수의 DirectSound 버퍼를 동시에 재생하는 방법과 재생중에 버퍼의 파라미터를 변경하는 방법을 나타낸다.

패스

소스 : (SDK 루트)\Samples\Multimedia\VBSamples\DSound\Src\SoundMix

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\VBSamples\DSound\Bin\SoundMix.exe

유저즈 가이드

[Load] 버튼을 클릭해, 1 개(살) 또는 복수의 웨이브 파일을 로드한다. 짧은 사운드가 반복해지도록,[Loop Play] 체크 박스를 온으로 한다. 버튼을 사용해 사운드의 재생, 일시정지, 정지를 실시해, 슬라이더를 사용해 파라미터를 변경한다.

프로그래밍 위에의 주의

이 어플리케이션은, 사운드 버퍼를 개별적으로 조작하는 방법과 프라이머리 버퍼에 믹싱 하는 방법을 나타낸다.


StreamFrom 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectSound C/C++ 샘플」을 참조할것.

[Visual Basic]

설명

StreamFrom 어플리케이션은, 스트림 버퍼와 이벤트 통지를 사용해, 웨이브 파일로부터 사운드를 스트림 하는 방법을 나타낸다.

패스

소스 : (SDK 루트)\Samples\Multimedia\VBSamples\DSound\Src\StreamFrom

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\VBSamples\DSound\Bin\Streamfrom.exe

유저즈 가이드

[Load File] 버튼을 클릭해, 비교적 큰 웨이브 파일을 연다.

프로그래밍 위에의 주의

이 샘플은 프라이머리 버퍼 오브젝트를 생성 해, 파일이 재생되어 있지 않을 때에서도 재생을 실시한다. 「프라이머리 버퍼의 연속 재생」을 참조할것.


StreamTo 샘플

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「DirectSound C/C++ 샘플」을 참조할것.

[Visual Basic]

설명

StreamTo 어플리케이션은, 사운드를 캡춰 버퍼에 스트림 하는 방법을 나타낸다.

패스

소스 : (SDK 루트)\Samples\Multimedia\VBSamples\DSound\Src\StreamTo

실행 가능 파일 : (SDK 루트)\Samples\Multimedia\VBSamples\DSound\Bin\Streamto.exe

유저즈 가이드

버퍼에의 사운드의 캡춰 링을 시작 하려면 ,[Start Streaming] 버튼을 클릭한다. [End Streaming] 버튼을 클릭 하면, 파일명을 입력할 수 있어 사운드를 파일에 보존할 수 있다.

프로그래밍 위에의 주의

캡춰 버퍼는, 사운드를 2 초 보관 유지할 수 있다. 이벤트 통지는, 데이터의 일시파일에의 쓰기를 방아쇠 하는데 사용된다. 유저가 캡춰를 정지해, 파일명을 주면(자), 미가공의 데이터가 웨이브 포맷 정보와 함께 Resource Interchange File Format (RIFF)로 보존된다.


용어집

여기에서는, Microsoft® DirectX® DSK 의 문서로 사용되는 기술 용어를 해설한다.

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 등). 보기 드물게, 독립한 알파 표면내에 픽셀마다의 알파값이 저장 되고 있는 화면의 알파값을 가리켜 ”알파 성분”이라고 하는 경우도 있다.
알파 정수 (alpha constant)
표면 전체에 적용되는 불투명도 (알파값).
알파 엣지 블렌드 (alpha edge blend)
알파 블렌딩 ( 및알파 채널 정보)의 용법의 1 개. 픽셀의 적용 범위에 근거해 엣지를 혼합색 하는 것으로써, 앨리어싱(aliasing)를 감소시키는 방법이다.
앰비언트 속성 (ambient property)
환경광속성, 라이트로부터의 각도에 의존하지 않고 반사하는 머트리얼 속성. 오브젝트의 향해, 위치, 표면 특성 등에 관계없이, 장면의 모든 것을 비추는 광원 및 머트리얼 속성. 장면의 모든 장소를 같은 광원에서 비추기 (위해)때문에, 앰비언트 광원에 놓여진 프레임의 위치나 방향은 중요하지 않다. 1 살의 장면에서는, 복수의 앰비언트 광원이 결합되고 있다.
비등방성 필터링 (anisotropic filtering)
비등방성의 일그러짐을 보정하는 밉맵 필터링 모드의 1 개.
비등방성 (anisotropy)
표면이 표시면에 대해서 각도를 가져 위치하는 3D 오브젝트의 이미지에 생기는, 눈에 보이는 일그러짐. 비등방성은 텍스쳐 공간에 역맵 된 스크린 픽셀의 성장 (길이÷폭)으로서 계측 할 수 있다.
배열 오브젝트 (array object)
1 개의 배열에 정리된 오브젝트군. 배열 오브젝트를 사용하면(자), 일련의 오브젝트 모두에게 어떠한 처리를 실시하는 경우의 조작이 간단하게 된다. 배열 오브젝트를 취급할 수가 있는 COM 인터페이스에는,GetElement 와 GetSize 라고 하는 메소드가 준비되어 있다. 이 2 개의 메소드는 각각, 배열 요소에의 포인터의 취득, 및 배열 사이즈의 취득을 실시한다.
Attach (attach)
복수의 DirectDrawSurface 오브젝트를 접속해, Z 버퍼 첨부의 3D 페이지 플립을 지원 하는 경우 등에 필요한 복합 구조체로 하는 것. Attach는 쌍방향적인 것은 아니다. 표면을 그 표면 자신에게 Attach 할 수 없다. 또, (시스템 메모리내에서) 에뮬레이트 되고 있는 표면을, 에뮬레이트에 의하지 않는 표면에 Attach 하는 일도 할 수 없다. 2 개의 표면을 Attach 하는 경우, 다른 한쪽의 표면이 텍스쳐 맵이 아닌 한, Attach 되는 표면 끼리는 동일 사이즈가 아니면 안된다.
Attach 상태 (attached)
시스템에 물리적으로 접속되고 있는 상태. 디바이스는, 인스톨 되고 있어도, Attach 상태에는 없는 경우도 있다.
어택 (attack)
매그니튜드가 기본 레벨 (유지 기간 레벨)에 이르러 force feedback 이펙트가 시작될 때의 초기 기간.
오디오 스트림 (audio stream)
사운드 데이터. 믹싱 되고 있는 것도, 되어 있지 않은 것도 포함한다. DirectSound 는, 재생중의 각세컨드리 사운드 버퍼로부터 얻은 오디오 스트림을 믹싱 해, 결과를프라이머리 사운드 버퍼에 출력한다. 프라이머리 사운드 버퍼는, 사운드 하드웨어에 오디오 데이터를 공급하는 버퍼이다.


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)
서버만이 세션의 완전한 상태를 저장 하는 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)
루트 표면에 Attach 되고 있는 복수의 DirectDrawSurface 오브젝트를 정리해 가리키는 용어. 복합 표면 구조체는, 루트를 파기하는 것에 의해서 밖에 파기할 수 없다.
제어 세그먼트(segment) (control segment)
재생의 일정 국면을 제어하는 뮤지컬 세그먼트(segment). 보통은 프라이머리 세그먼트(segment)이지만, 제어 세그먼트(segment)로서 세컨드리 세그먼트(segment)를 지정할 수가 있다.
컬링(Culling) (culling)
렌더링 처리로 3D 프리미티브의 뒷면등을 생략하는 것.
현재 플레이 포지션 (current play position)
DirectSound 버퍼내에서의 현재의 사운드의 재생 위치.
현재 라이트 포지션 (current write position)
DirectSound 버퍼내의 안전하게 데이터를 변경할 수 있는 위치.


D

암색빛 (dark light)
장면으로부터 라이트를 제거하는 광원. 라이트의 색에 부의 값을 지정하는 것으로써 생성 할 수 있다.
DCI
Display Control Interface (디스플레이 컨트롤 인터페이스)의 약어. DCI 는, Intel® 및 Microsoft® 에 의해 정의된 인터페이스로, 비디오 메모리에 직접 액세스 하는 것에 의해, 보다 높은 그래픽스 퍼포먼스를 제공한다.
데드 존 (dead zone)
그 범위내에서는 축이 중심에 위치하고 있다고 보여지는 축내의 영역.
디칼 (decal)
비주얼 오브젝트로서 직접 렌더링 되는 텍스쳐. 뷰포트에 위치를 맞춘 직사각형에 렌더링 된다.
목적지 컬러 키 (destination color key)
블리트의 경우는 옮겨놓을 수 있는 색, 오버레이의 경우는 목적지의 표면상에서 덮어 가려지는 색.
디바이스 윈도우 (device window)
Microsoft® DirectDraw® 가 표시용으로 사용하는 어플리케이션 윈도우. 반드시 화면에 표시된다. 어플리케이션은, 주어진 컴퓨터에 Attach 되고 있는 각 표시 디바이스에 1 개씩 디바이스 윈도우를 가질 수가 있다. 「포커스 윈도우」를 참조할것.
디퓨즈 속성 (diffuse property)
디 푸즈 반사 속성, 라이트로부터의 입사각에 의존해 반사하는 머트리얼 속성. 머트리얼의 반사 및 발광을 결정하는 속성은 4 개 있지만, 디퓨즈 속성은 그 중의 1 개(살)이다. 에미션(emission) 속성, 앰비언트 속성, 및 「스펙큐러 속성」을 참조할것.
디렉셔널 (directional)
프레임에 Attach 되지만, 모든 오브젝트를 같은 휘도(Luminance)로 비추는 광원의 기술. 마치 광원이 오브젝트로부터 무한의 거리에 위치할 것 같은 이펙트를 준다. 디렉셔널 라이트는, 방향은 가지지만 위치를 가지지 않고, 일반적으로, 태양과 같이 멀게 멀어진 광원을 시뮬레이트 하기 위해서 이용된다.
DirectPlay 주소 (DirectPlay address)
Microsoft® DirectPlay® 가 로비 서버, 어플리케이션, DirectPlay, 및 서비스 프로바이더의 사이에 주소 정보를 건네주기 위해서(때문에) 사용하는 데이터 형식. DirectPlay 주소는, 글로벌 유니크 식별자 (GUID)로 태그 붙이고 된 일련의 가변장의 데이타체크이다. GUID 는, DirectPlay 에 필요한 주소 정보를 모두 제공한다. 주소 정보의 예로서 서버의 네트워크 주소, 플레이어의 네트워크 주소, 플레이어의 전자 메일명, 세션의 네트워크 주소등을 들 수 있다.
DLS
DownLoadable Sounds (다운로더블 사운드)의 약어. DownLoadable Sample (다운로더블 샘플)의 약어로서 사용되는 경우도 있다. 소프트웨어의 디지털 샘플로, 신디사이저가 악기의 음색을 생성할 때에 사용된다.


E

에미션(emission) 속성 (emissive property)
자기 발색 속성, 머트리얼 (소재)의 라이트로 의존하지 않는 색속성을 나타내는 머트리얼 속성, 발광 또는 발색. 머트리얼의 반사 및 발광을 결정하는 속성은 4 개 있지만, 에미션(emission) 속성은 그 중의 1 개(살)이다. 앰비언트 속성, 디퓨즈 속성, 및 「스펙큐러 속성」을 참조할것.
에미션(emission) 설정 (emissive setting)
「에미션(emission) 속성」을 참조할것.
유효 프레임 (enable frame)
광원을 적용할 수가 있는 프레임.
엔벌로프 (envelope)
초기 (어택)와 종기 (페이드)에서의 매그니튜드를 변경하는 것으로써, force feedback 이펙트의 형상을 정의하는 일련의 값.
짝수 필드 (even field)
비디오 프레임을 구성하는 홀수/짝수의 필드 세트의 2 번째의필드 . 필드 2 라고도 불린다.
실행 버퍼 (execute buffer)
3D 신을 기술하는, 모든 정보가 저장 되고 있어 독립한 정보 패킷. 실행 버퍼에는, 버텍스의 리스트가 저장 되어 거기에 계속되어 명령 스트림이 저장 된다. 명령 스트림은, 연산 코드 (작동코드)와 그 작동코드에 의한 처리의 대상이 되는 데이터로부터 완성된다.


F

면 (face)
메쉬내의 단일의 다각형.
페이드 (fade)
force feedback 이펙트의 중앙 부분 (유지 기간)으로부터 force feedback 이펙트가 끝날 때까지의 기간.
폴 오프 (falloff)
spotlight의 안쪽의 원추면과 외측의 원추면과의 사이의 빛의 감쇠.
필드 (field)
비디오 스트림내의 단일의비디오 프레임의 반에 상당하는 데이터. 각 필드에는, 1 개(살) 간격의 주사 라인의 데이터가 저장 된다. 필드의 송수신은,홀수 필드,짝수 필드의 순서로 행해진다.
필드극성 (field polarity)
필드가짝수 필드와홀수 필드의 어디에서 있는지를 나타내는 특성. 주사 라인중에 VREF 의 하강 모서리가 발생하지 않는 경우는, 홀수 필드이다. 주사 라인중에 VREF 의 하강 모서리가 발생하면, 짝수 필드이다.
flimmering (flimmering)
z 값의 분리가 불완전하기 때문에, 전사시에 3D 프리미티브상에 발생하는 표시후들 붙어 있는. 뒷면의 텍스쳐의 일부의 픽셀이 전면의 텍스쳐상에 렌더링 되거나 그 역이 일어나거나 한다.
플립 (flip)
백 버퍼와프런트 버퍼의 주소를 스왑 (교환) 하는 것. 이것에 의해,백 버퍼내의 이미지를 프런트 버퍼에 카피 또는 블리트 할 필요가 없는, 그 결과, 백 버퍼내에 있던 이미지를 효율적으로 화면에 표시할 수 있다.
플립핑 체인 (flipping chain)
서로 접속되고 있어 플립 가능한 일련의 표면. 플립을 참조할것.
플립핑 표면 (flipping surface)
플립핑 가능한 메모리. 플립을 참조할것.
포커스 윈도우 (focus window)
DirectDraw 가 윈도우 메세지를 받아들이기 위해서(때문에) 사용하는 어플리케이션 윈도우. 실제로 화면에 표시되는 경우도 있으면, 표시되지 않는 경우도 있다. 포커스 윈도우의 메세지 핸들러는, DirectDraw 에 의해 전송 된 입력 메세지를 받아들인다. 어플리케이션이 가질 수 있는 포커스 윈도우는 1 개 뿐이다. 「디바이스 윈도우」를 참조할것.
프레임 (frame)
장면 위에의 오브젝트의 배치의 기본으로 되는 비표시의 박스. 장면상에서의 오브젝트의 위치는, 적절한 기준 프레임에 대한 공간적인 관계를 지정하는 것에 의해 결정할 수가 있다. 비주얼 오브젝트는, 그 위치나 방향을 프레임으로부터 취득한다.

동영상이나 애니메이션내의 단일의 이미지도 마찬가지이다.

프런트 버퍼 (front buffer)
플립핑 체인의 선두의 버퍼. 많은 경우, 화면에 표시되는프라이머리 표면을 가리킨다. 다만, 다른 경우 (텍스쳐의 플립핑 체인등)는, 3D 엔진이 거기로부터 텍스쳐를 취득해 오기 위한 표면이며, 프라이머리 표면도 아니면 표시도 되지 않는 경우도 있다. 또, 플립핑 오버레이 표면의 경우의 프런트 버퍼는, 화면에 표시되고는 하지만, 프라이머리 표면에 오버레이 된 표면에 지나지 않는다. 「프라이머리 표면」을 참조할것.
전방 클립면 (front clipping plane)
절두체의 전면의 한계. 전방 클립면보다카메라 집합에 있는 오브젝트는 렌더링 되지 않는다. 전방 클립면의 높이에 의해, 뷰의 필드가 정해진다. 「후방 클립면」을 참조할것.


G

젠록킹 (genlocking)
2 개의 비디오 신호의 동기를 취하는 처리. 젠록킹 된 신호는 원의 신호와 동기가 잡히고 있기 (위해)때문에, 원의 신호와 믹싱 할 수가 있어 디조르브, 와이프등의 트란지션에페크트가 가능해진다.
그리드 (grid)
박 (비트)의 소분할. 비트마다의 그리드수는, Microsoft® DirectMusic® 의 박자 기호의 일부이다.
그루브 레벨 (groove level)
스타일의 재생중에 뮤직으로 지정되는 값. 지정된 시간에 어느 패턴을 선택할 수 있을까를 판단한다. 작곡가는, 광범위의 그루브 레벨을 각 패턴에 할당한다.
그룹 (group)
플레이어의 논리적인 모임. DirectPlay 는 세션내에서 그룹을 지원 한다. 플레이어의 그룹을 생성 하는 것으로써, 어플리케이션은 그룹에 단일의 메세지를 송신할 수 있어 그룹내의 모든 플레이어가 그 메세지를 수신할 수 있다. 이것에 의해, 그룹이 네트워크의 멀티 캐스트 기능을 어플리케이션에 나타내는 수단이 된다.

그룹은, 세션내의 플레이어를 정리하기 위해서(때문에) 사용할 수가 있다. 플레이어는, 1 개(살) 이상의 그룹에 속할 수가 있다. DirectPlay 에서는, 그룹이나 그 멘바십을 관리할 수가 있다.


H

HAL
Hardware Abstraction Layer (하드웨어 추상 계층)의 약어. 하드웨어 및 디바이스 드라이버의 메카니즘에 의해 구성되어 각각의 디바이스 고유의 이행 상세를 어플리케이션으로부터 숨기는 기능을 담당한다. 사용하고 있는 하드웨어가, 어플리케이션으로부터 요구된 기능을 이행 하고 있지 않았던 경우는, 그 기능을 소프트웨어에 의해 에뮬레이트 한다.
하드웨어 블리트 (블록 전송) (hardware blitter)
디스플레이 어댑터에 짜넣어지고 있어 효과적인 블리트 처리를 실시하는 하드웨어 컴퍼넌트.
HEL
Hardware Emulation Layer (하드웨어 에뮬레이션 계층)의 약어. 하드웨어가 지원 하고 있지 않는 기능을 소프트웨어에 의해 에뮬레이트 한다.
HID
Human Interface Device (휴먼 인터페이스 디바이스)의 약어. 인간이 컴퓨터를 제어할 수 있는 디바이스를 나타내는 USB 클래스.
히트 검출 (hit detection)
「충돌 검출」을 참조할것.
호스트 (host)
DirectPlay 로, DPID_SYSMSG 라고 하는 ID 를 가지는 가상 플레이어. 호스트는, 시스템 메세지나 세션내의 모든 플레이어에게 보내지는 메세지를 관리한다.
HREF
Horizontal REFresh (수평 리프레쉬)의 약어. HREF 신호는, 비디오 스트림내에서, 디스플레이가 새로운 주사 라인을 시작 하려고 하고 있는 것을 알릴 때 액티브하게 된다. 「VREF 」를 참조할것.


I

인덱스 팔레트 (index palette)
다른 팔레트 오브젝트의 인덱스가 되는 엔트리를 가지는 DirectDrawPalette 오브젝트.
IPX 서비스 프로바이더 (IPX service provider)
Internetwork Packet Exchange (IPX) 프로토콜을 사용해 근거리 통신망 (LAN) 상에서 통신을 실시하기 위해서(때문에) Windows Sockets 를 사용하는 서비스 프로바이더. 이 서비스 프로바이더는, 비보증의 메시지 교환만을 지원 한다. 1 대의 컴퓨터는, IPX 를 사용해 1 개의 DirectPlay 세션만의 호스트로서 기능한다.
IRE 율 (IRE scale)
International Radio Engineers 의 비율. IRE 는, 브로드캐스트 비디오 신호의 휘도(Luminance)를 정의하는 0 ~ 100 까지의 범위의 값. IRE 값이 높아지면(자), 비디오 신호의 휘도(Luminance)가 증가한다. 7.5 IRE 의 휘도(Luminance) 유니트 (National Television System Committee (NTSC) 신호의 흑에 의한 절단의 해 귀의값)에서는, NTSC 디스플레이 디바이스의 전자총은 절단 되어 화면에는 이미지가 표시되지 않는다.


L

지연 시간 (latency)
응답 지연 시간. 예를 들어 Microsoft® DirectSound® 에서는,사운드 버퍼가 재생되고 나서 실제로 사운드가 스피커로부터 나올 때까지 의 시간이다. DirectPlay 에서는, 패킷이 지정된 목적지에 도달할 때까지의 시간이다.
라이트 맵 (light map)
3D 신의 라이팅 정보가 들어간 텍스쳐.
로비 어웨어 어플리케이션 (lobby-aware application)
로비로부터의 기동을 최소한 지원 하는 어플리케이션.
로비 클라이언트 (lobby client)
유저의 컴퓨터상에서 실행되는 로비 관리 루틴. 어플리케이션의 기동, 유저 인터페이스의 갱신,로비 서버와의 통신을 실시한다.
로비 프로바이더 (lobby provider)
로비 서버의 개발자가 제공하는 클라이언트 컴퍼넌트 (동적 링크 라이브러리). 이것에는, DirectPlay 의 요구에 응해 로비 서버와의 통신 기능이 이행 된다.
로비 서버 (lobby server)
리모트 서버-위에서 실행되는 로비 관리 루틴. 로비 서버는, 관리 대상의 어플리케이션에 접속해 온 유저에 관한 모든 정보를 조정한다.
로비 세션 (lobby session)
클라이언트와 서버가 상호 운용하도록(듯이) 특별히 기술되어 있지 않았던 로비 서버에의 접속.


M

마하 밴드 (Mach bands)
3D 프리미티브의 블렌딩이 순조롭게 행해지지 않는 색범위.
머트리얼 (material)
표면이 어떻게 빛을 반사 및 발색할까를 결정하는 속성. 머트리얼 (소재)에는,에미션(emission) 속성 (라이트로 의존하지 않고 발색), 앰비언트 속성, 디퓨즈 속성, 및스펙큐러 속성의 4 개의 원가요소가 있다. 반사의 밝음은, 강도의 설정에 의해 결정된다.
메쉬 (mesh)
단순한 다각형으로 표현되는 면이 모인 것.
밉맵 (mipmap)
MIP 맵이라고도 불린다. (MIP 는, 영어의 "much in little" 를 의미하는 라틴어 “multium in parvo”의 약어. ) 동일 이미지가 서서히 저해상도가 되어 가는 일련의 텍스쳐로, 1 개의 이미지에 몇 종류의 필터를 걸치는 것으로 생성 된다. 오브젝트가 근처에 표시될 때는 고해상도의 이미지가 사용되어 오브젝트가 멀어지는에 따라 (즉 화면에서의 표시가 작아지는에 따라) 저해상도의 이미지가 사용된다.
믹싱 (mixing)
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)
표면으로부터 수직에 성장하는 가공의 선으로, 면의 방향의 정의에 사용된다.


O

홀수 필드 (odd field)
비디오 프레임을 구성하는 홀수/짝수의 필드 세트의 1 번째의필드 .
오프 스크린 표면 (off-screen surface)
메모리 위에의 개념적인 직사각형 영역. 일반적으로, 표시하기 전에백 버퍼에 블리트 하는 비트 맵을 저장 하는데 사용한다. 보통, 스프라이트가 저장 된다.
작동코드 (opcode)
실행 버퍼내의 버텍스를 해석하는 방법이나 시스템 상태를 변경하는 방법을 정의하는 연산 코드.
오버 드로우 (overdraw)
스크린 픽셀이 드로잉(Drawing) 되는 평균 회수.
오버레이 표면 (overlay surface)
메모리 위에의 개념적인 직사각형 영역. 오버레이 표면에 저장 된 이미지 정보는, 그 오버레이 표면이 적용되는프라이머리 표면의 이미지 정보 위에 씌울 수 있다. 오버레이는, 그 외의 모든 스크린 요소보다 위에 있는 것으로서 처리된다.
오버레이 Z 오더 (overlay z-order)
오버레이 끼리의 클리핑의 차례를 결정한다. 이것에 의해, 하드웨어 스프라이트 시스템을 DirectDraw 에 이행 하는 것이 가능하게 된다.


P

페이지 플립핑 (page flipping)
「플립」을 참조할것.
팔레트 (palette)
오브젝트나 어플리케이션이 사용하는 색세트. DirectX 에서는, DirectDrawPalette 오브젝트를 가리킨다.
팔레트 인덱스 (palette index)
색을 선택할 경우에 사용되는 팔레트 테이블 배열의 인덱스가 되는 정수.
팔레트화 된 표면 (palettized surface)
Attach 된 팔레트를 색정보의 저장 장소로서 사용하는 DirectDrawSurface 오브젝트.
팬값 (pan value)
좌우의 오디오 채널의 상대 음량. 100 분의 1 데시벨 단위로 나타내진다.
패러럴 포인트 (parallel point)
평행한 광선으로 오브젝트를 비추지만, 빛의 방향은 그 위치로부터 결정되는 것 같은 광원의 기술. 예를 들어, 패러럴 포인트 광원의 양측으로 놓여진 2 개의 메쉬가 있는 경우, 각 메쉬는 광원에 접하고 있는 (분)편의 면이 비추어진다.
P 채널 (PChannel)
Performance channel (퍼포먼스 채널)의 약어. 특정의 포트상에 있는 특정의 채널 그룹내의 MIDI 채널.
피어 투 피어 세션 (peer-to-peer session)
세션의 완전한 상태가 그 세션내의 모든 컴퓨터상에 복제되는 DirectPlay 세션. 세션 기술 데이터 (플레이어와 그룹의 리스트, 및 각 세션에 관한 이름과 리모트 데이터)는, 모든 컴퓨터에 복제된다. 1 대의 컴퓨터로 무엇인가 변경했을 경우는, 다른 모든 컴퓨터에 즉석에서 통지된다. 이것은, DirectPlay 의 통신의 디폴트 모드이다. 「클라이언트/서버 세션」을 참조할것.
퍼스펙티브 보정 (perspective correction)
원근 보정. 카메라로부터 각도를 이루어 떨어져 가는 다각형에 텍스쳐 맵을 적용할 때에, 다각형의 깊이를 알 수 있도록(듯이) 텍스쳐를 다각형상에 넓히는 기법. Direct3D 에서는, 퍼스펙티브 보정은 자동적으로 행해진다.
피킹 (pick)
뷰포트의 2D 좌표로 주어진 장소에 있는 비주얼 오브젝트를 장면내에서 찾는 것.
PID
Physical Interface Device (물리 인터페이스 디바이스)의 약어. 인간이 컴퓨터로부터 force feedback를 느낄 수 있는 USB 클래스.
피치 (pitch)
비트 맵 라인의 선두를 나타내는 주소와 다음의 라인의 선두를 나타내는 주소의 사이의 거리. 바이트 단위로 나타내진다. 모든 디스플레이 메모리가 1 개의 선형 블록으로서 배치되고 있다고는 할 수 없기 때문에, 메모리 피치와 메모리폭을 혼동 하지 않는 것. 예를 들어, 직사각형 메모리와 같이, 비트 맵의 폭과 캐쉬 부분이 더해진 것이 디스플레이 메모리의 피치가 되고 있는 경우도 있다. 「폭」, 「보폭」을 참조할것.
플레이어 (player)
DirectPlay 세션의 참가자. 각 플레이어에게는, 플레이어 사이에서의 메시지 교환을 가능하게 하기 위해서플레이어 ID 가 주어진다.
플레이어 ID (player ID)
DirectPlay 세션의 참가자의 생성시에 참가자에게 줄 수 있는, 그 참가자 고유의 번호. 어플리케이션은, 플레이어 ID 를 사용해 참가자 끼리에게 메시지 교환을 실시하게 한다. 호스트에게는, 항상 DPID_SYSMSG 라고 하는 플레이어 ID 가 주어진다.
포인트 라이트 (point light)
그 기점으로부터 모든 방향에 균등하게 빛을 방사하는 광원.
점리스트 (point list)
가장 단순한 3D 프리미티브. 3D 공간내의 서로 접속되어 있지 않은 점의 모임이다.
강도 (power)
머트리얼의스펙큐러 속성으로, 스펙큐러 하이라이트의 선명도를 결정하는 값. 이 값이 5 때는 금속적인 외관이 되어, 값이 좀 더 높아지면(자)보다 플라스틱적인 외관이 된다.
프라이머리 사운드 버퍼 (primary sound buffer)
게임중에 유저의 귀로 들리는 소리가 저장 되는 버퍼. 일반적으로는 세컨드리 버퍼의 사운드를 믹싱 한 결과의 출력처로 여겨지지만, 커스텀 믹싱이나 그 외의 특별 처리를 실시하기 위해서(때문에) 직접 액세스 할 수도 있다.
프라이머리 표면 (primary surface)
디스플레이에 표시되는 이미지가 저장 되는 메모리 영역. DirectX 에서는, 프라이머리 표면은, 프라이머리 DirectDrawSurface 오브젝트에 의해 나타내진다.
투영 공간 (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)
DirectMusic 에서는, 악기의 음색을 합성할 때에, 그 디지털 샘플이 사용되는 음색의 범위.
루트 프레임 (root frame)
Direct3D 에서의, 친프레임을 가지지 않는 (즉, 프레임의 계층 구조의 최상정도에 위치한다) 프레임. 루트 프레임에는, 장면을 구성하는 일련의 오브젝트 모든 것이 저장 된다. 「장면」을 참조할것.


S

포화 (saturation)
어느 범위에 대해, 실제의 값이 극한으로 가까운 시일내에 되었을 때에 극한치를 조정하는 것. 예를 들어, 값의 범위의 최대치가 1,000 이었던 경우에, 최대 포화점을 900 으로 설정 하면, 899 보다 큰 값은 모두 1,000 에 조정된다.
장면 (scene)
가상 환경을 구성하는 일련의 오브젝트 모든 것을 가리킨다. 가시 오브젝트, 사운드, 라이트, 프레임이 포함된다. Direct3D 에서는,루트 프레임내의 오브젝트 전체를 가리킨다.
스크린 공간 (screen space)
좌표가 frame buffer내의 2D (2 차원)의 위치에 직접 맵핑 되고 있는 기준 프레임. 디스플레이나 그 외의 표시 디바이스에 표시하기 위한 프레임이다. 스크린 공간의 좌표는, 뷰포트의 파라미터로부터 생성 한 트랜스 폼 행렬을 사용해 투영 공간의 좌표를 트랜스 폼 하는 것으로써 얻을 수 있다.
세컨드리 사운드 버퍼 (secondary sound buffer)
오디오 메모리내의 부분 가운데, 어플리케이션으로 재생되는 각각의 사운드가 저장 되는 부분. 여기에 저장 된 사운드는, 1 회의 이벤트로서 재생할 수도 있으면, 루프 사운드로서 반복해 재생할 수도 있다. 세컨드리 버퍼를 사용하면(자), 실제로 이용할 수 있는 사운드 버퍼 메모리보다 큰 사운드를 재생하는 일도 가능하다. 이 경우, 세컨드리 버퍼는, 사운드의 지금부터 재생되는 부분만큼을 저장 한 큐로서의 역할을 완수한다.
시큐어 세션 (secure session)
세션에 참가하기 전에, 기존의 유저의 데이타베이스에 대해서 모든 유저가 인증된 세션. 시큐어 세션에서는, DirectPlay 의 시스템 메세지는 모두 디지털 서명 되어 송신원의 신원이 확인된다. 기밀성의 높은 정보를 송신하는 특정의 시스템 메세지는 암호화된다. 1 명의 플레이어로부터 발생해, 세션내외의 모든 플레이어에게 브로드캐스트 해야 하는 시스템 메세지는, 우선 최초로 서버에 송신된다. 그 후, 서버는 메세지에 서명해, 세션내외의 모든 컴퓨터에 메세지를 전송 한다. 디폴트에서는, 플레이어로부터 플레이어에게로의 메세지는 서명되지 않고, 서버 경유로 루팅 되지 않는다.
서비스 프로바이더 (service provider)
DirectPlay 가 네트워크를 개입시킨 통신을 실시하기 위해서(때문에) 사용하는 동적 링크 라이브러리. 서비스 프로바이더에는, 메세지를 송수신 하기 위해서 필요한 네트워크 고유의 코드가 모두 포함되어 있다. 각종 온라인 서비스나 네트워크 오퍼레이터는, 서비스 프로바이더를 제공하는 것으로써, 하드웨어, 프로토콜, 통신 매체, 네트워크 자원 등에 특수한 것을 사용할 수가 있다.
세션 (session)
DirectPlay 로, 리모트 컴퓨터상에서 실행되고 서로 서로 통신하고 있는 몇개의 어플리케이션의 인스턴스. 어플리케이션이 다른 컴퓨터와의 통신을 시작 하는 경우, 어플리케이션은 몇개의 세션에 속하고 있을 필요가 있다. 어플리케이션은 네트워크 위에의 기존의 세션 모든 것을 열거해, 그러한 1 개(살)에 참가하거나 새로운 세션을 생성 해, 생성 한 세션에 다른 컴퓨터가 참가하는 것을 대기하거나 할 수가 있다. 어플리케이션이 세션의 일부가 되면(자), 플레이어를 생성 해, 세션내외의 모든 플레이어와 메세지를 교환할 수 있다.
사운드 버퍼 (sound buffer)
DirectSound 의 오디오 데이터가 저장 되는 메모리 부분. 사운드 버퍼에는, 프라이머리와 세컨드리가 있어, 또 스태틱 스트림의 구별도 있다.
전송원컬러 키 (source color key)
블리트의 경우는 전송으로 카피되지 않는 색, 오버레이의 경우는 출력처에서 표시되지 않는 색.
스펙큐러 속성 (specular property)
스펙큐러 반사 속성, 라이트로부터의 입사빛의 각도와 시점에의 반사광의 각도의 양쪽 모두에 의존한 머트리얼 속성. 머트리얼의 빛의 반사 및 발색을 결정하는 속성은 4 개 있지만, 스펙큐러 속성은 그 중의 1 개(살)이다. 앰비언트 속성, 디퓨즈 속성, 및 「에미션(emission) 속성」을 참조할것.
spotlight (spotlight)
원추형의 미츠루를 추방하는 광원. 원추안에 있는 오브젝트만이 비추어진다. 원추는 2 개의 휘도(Luminance)를 생성한다. 중앙의 밝은 부분은 포인트 라이트와 같은 기능을 해, 주위의 어슴푸레한 부분은 주변의 어두운 그림자와 머지 된다.
스태틱 사운드 버퍼 (static sound buffer)
완전한 사운드가 저장 되는 부분. 사운드 전체를 한 번에 버퍼에 기입할 수 있기 (위해)때문에, 편리하다.
스틱키 포커스 (sticky focus)
DirectSound 로, 버퍼를 소유하는 어플리케이션이 입력초점을 가지고 있지 않을 때에도사운드 버퍼를 재생할 수 있는 능력. 예를 들어, 유저가 다른 어플리케이션으로 작업하고 있는 동안에도, DirectSound 어플리케이션은 사운드 버퍼를 계속 재생할 수가 있다.
스트림 사운드 버퍼 (streaming sound buffer)
버퍼의 재생중에 동적으로 오디오 데이터를 읽어들일 수 있기 (위해)때문에, 사이즈가 작음에도 불구하고 긴 사운드를 재생할 수 있는 사운드 버퍼. 예를 들어, 3 초간 분의 오디오 데이터를 저장 할 수 있는 버퍼를 사용해 2 분간의 사운드를 재생하거나 할 수 있다. 스트림 버퍼를 사용하면(자), 스태틱 버퍼의 경우보다 필요한 메모리량이 훨씬 적게 된다.
신축(스트레치) (stretching)
사이즈가 다른 목적지에 이미지를 블리트 하는 것. 이 처리를 직접 지원 하는 하드웨어도 있다.
보폭 (stride)
피치와 동의. 「폭」을 참조할것.
표면 (surface)
비주얼 이미지가 저장 되는 메모리. 대부분의 경우는 디스플레이 메모리내에 놓여지지만, 시스템 메모리에 둘 수도 있다. 「복합 표면」, 「오프 스크린 표면」, 「오버레이 표면」, 「프라이머리 표면」을 참조할것.
유지 기간 (sustain)
force feedback 이펙트의 기본 매그니튜드가 도달되고 있는 기간. Attach로부터페이드까지의 사이.
시스템 메세지 (system message)
DirectPlay 에서는, 플레이어 ID 의 DPID_SYSMSG 로부터의 메세지. 모든 시스템 메세지는 DWORD 값으로 시작된다.


T

TCP/IP 서비스 프로바이더 (TCP/IP service provider)
TCP/IP 프로토콜을 사용해 인터넷이나 근거리 통신망 (LAN) 상에서 통신을 실시하기 위해서(때문에) Windows Sockets 를 사용하는 서비스 프로바이더. 비보증 메세지에 User Datagram Protocol (UDP) 패킷을 사용해, 보증 첨부 메세지에 TCP 를 사용한다. 1 대의 컴퓨터는, TCP/IP 를 사용해 복수의 DirectPlay 세션의 호스트로서 기능할 수 있다.
티어링 (tearing)
스크린의 refresh rate가 어플리케이션의 frame rate와 동기 하고 있지 않을 때에 발생한다, 표시가 꾸불꾸불하는 것처럼 보이는 현상. 1 개의 프레임의 상부가 다른 프레임의 하부와 같게 표시되어 2 개의 이미지의 사이에 갈라진 곳이 생긴다.
테셀레이션 (tessellation)
3D 그래픽스로 오브젝트의 표면을 삼각형 다각형에 세분화하는 것.
텍셀 (texel)
텍스쳐내의 단일의 요소. 텍스쳐가 오브젝트에 적용되었을 때, 텍셀이 스크린 위에의 픽셀에 대응하는 것은 좀처럼 없다. 어플리케이션은, 텍스쳐 필터링을 사용해, 장면내에 픽셀을 생성 하기 위해서 시스템이 텍셀간을 보간 하는 방법을 제어할 수 있다.
텍스쳐 (texture)
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 공간의 점. 다각형이나 프리미티브는 복수의 버텍스를 가진다. 버텍스는 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)
면이나 메쉬의텍스쳐 좌표의 계산에 사용되는 처리. 기본적인 랩핑 타입에는, 플랫, 원기둥(실린더), 구(공)체, 크롬이 있다.


Z

Z 버퍼 (z-buffer)
장면 위에의 각 픽셀의 깊이를 저장 한 버퍼. z 값의 작은 픽셀은 z 값의 큰 픽셀을 덧쓰기한다.
Z 화이팅 (z fighting)
「flimmering」를 참조할것.


Direct3D 보관 유지 모드의 소개

Microsoft® Direct3D® 보관 유지 모드에 어서 오십시오. 보관 유지 모드에서는, 퍼스널 컴퓨터상에서 3 차원 (3D) 그래픽스 환경의 생성, 리얼타임 조작이 가능하게 된다.

최종 갱신일: 2000년 4월 13일

보관 유지 모드에 대해
Direct3D 보관 유지 모드의 개요를 간단하게 소개한다.
처음에
Direct3D 보관 유지 모드 버젼 6. x 의 신기능, 학습을 시작하는 포인트, 공통 항목의 참조 먼저 대해 설명한다. 게다가 3D 로 점을 조작하는데 필요한 기초적인 지식도 일부 소개한다. 좌표계, 변환, 다각형, 삼각형의 전개도와 선형, 벡터, 버텍스, 쿼터니온등에 대해서도 설명한다.
기초지식
3 D그래픽스를 짜넣는 프로그램을 생성 할 때에 이해해 두어야 할 기술적인 기초지식에 대해 설명한다. 이 마디에서는, 좌표계와 변환의 기초에 대해 설명한다.
아키텍쳐
Direct3D 보관 유지 모드 오브젝트, 및 오브젝트가 지원 하는 인터페이스에 대해 설명한다. 참조 카운트나 Z 버퍼에 관한 힌트도 소개한다.
개요
몇개의 Direct3D 보관 유지 모드 인터페이스의 사용법을 설명한다. 모든 보관 유지 모드 인터페이스의 상세한 것에 대하여는, 「C++/COM 레퍼런스」를 참조할것.
튜토리얼
간단한 보관 유지 모드 어플리케이션의 코드를, 순서를 쫓아 설명한다.
C++/COM 레퍼런스
인터페이스 메소드, 비멤버 함수, 콜백 함수에 대해, 구문, 파라미터의 기술, 플래그의 기술, 사용 위에의 주의를 설명한다. 게다가 Direct3D 구조체의 멤버, 열거형, 그 외의 정의형, 및 돌려주어질 가능성이 있는 에러값에 대해서도 설명한다.
Visual Basic 레퍼런스
인터페이스, 클래스, 메소드, 및 콜백 인터페이스에 대해, 구문, 파라미터의 기술, 플래그의 기술을 설명한다. 게다가 Direct3D 보관 유지 모드형의 멤버, 열거형, 그 외의 정의형, 및 돌려주어질 가능성이 있는 에러값에 대해서도 설명한다.
샘플의 인트러덕션
Microsoft Developer Studio™ 를 사용해 Direct3D 보관 유지 모드의 샘플을 빌드 하는 방법을 설명한다. 참고로 하는 샘플을 결정할 수 있도록(듯이), 샘플의 요약도 소개한다.
DirectX 파일 포맷
DirectX (. x) 파일의 파일 포맷에 대해 설명한다.. x 파일을 사용 하면, 어플리케이션은 사전 정의 오브젝트를 읽어들여, 구축한 메쉬 정보를 리얼타임에 기입할 수가 있게 된다. 템플릿, 샘플, 파일의 바이너리 포맷, 및 다른 패키지의 3D 모델을 x파일에 콘버터 하는 Conv3ds.exe 에 대해서도 설명한다.
용어집
Direct3D 보관 유지 모드로 사용되고 있는 기본적인 그래픽스 용어를 정의한다.

주 : 아이콘 external link 은, microsoft.com 이외의 사이트로 액세스 하는 URL 를 나타내고 있다. Direct3D 보관 유지 모드 사이트로 돌아가려면 ,［돌아오는］ 버튼을 사용한다. 대부분의 외부 링크는, Microsoft가 관리하고 있지 않는 서버로 연결되어 있다. 관리외의 서버에 관한 Microsoft 의공식 견해를 참조해 주시길 바란다.


보관 유지 모드에 대해

Microsoft® Direct3D®보관 유지 모드는, 퍼스널 컴퓨터상에서 3 차원(3 D) 그래픽스를 실현하기 위해서(때문에) Microsoft가 제공하는 솔루션이다. 3 D환경을 생성 해, 리얼타임에 처리하고 싶은 경우는, Direct3D 보관 유지 모드 API를 사용해야 하는 것이다.

Direct3D 보관 유지 모드의 기초에 있는 개념은, 이전에 3 D그래픽스의 코드를 쓴 것이 있는 개발자에게 있어서는 친숙한 것일 것이다. 그러나, 처음으로 3 D프로그래밍을 실시하는 개발자는, 「Direct3D 보관 유지 모드 아키텍쳐」 및 「기초지식」의 설명을 충분히 이해할 필요가 있다. 지금부터 3 D프로그래밍의 경험이 있는 개발자도, 시작한지 얼마 안된 개발자도, 이 Software Development Kit에 포함되어 있는 샘플 코드를 주의 깊게 읽어 주셨으면 한다. 샘플 코드는, 실제의 어플리케이션에 보관 유지 모드를 이행 하는 방법을 나타내고 있다.

Direct3D 보관 유지 모드의 프로그래밍의 가이던스에 대해서는, 「Direct3D 보관 유지 모드 튜토리얼」을 참조할것.


처음에

이 마디에서는, Microsoft® Direct3D® 보관 유지 모드 버젼 6. x 의 신기능, 및 메뉴얼로 특정의 항목을 조사하는 참조 먼저 대해 설명한다. 또, 상세한 코멘트를 붙인 샘플 코드의 워크 스루도 실시한다.

  • Direct3D 보관 유지 모드의 신기능
  • 문서의 구성
  • 오브젝트의 회전：RMBegin1 샘플
  • 프레임 계층：RMBegin2 샘플
  • 디바이스의 열거：RMEnum 샘플


Direct3D 보관 유지 모드의 신기능

이 마디에서는, Microsoft ® Direct3D ® 보관 유지 모드 버젼 6.0 의 신기능과 문서에 대해 설명한다.

Microsoft Visual Basic 의 프로그래머는, Direct3D 보관 유지 모드의 사용법에 대해, 「Visual Basic 레퍼런스」를 참조할것.

이 항에서는 다음의 항목에 대해 설명한다.

  • 새로운 항목
  • 새로운 인터페이스

새로운 항목

「처음에」의 대부분은, 새롭고 생성 되고 있어 이하의 항목을 포함하고 있다.

  • 「문서의 구성」에서는, 특정의 항목에 대해 문서를 조사하는 경우의 참조처를 해설하고 있다.
  • 「오브젝트의 회전：샘플 RMBegin1 」에서는, 오브젝트를 회전하는 간단한 샘플의 워크 스루를 실시한다.
  • 「프레임 계층：샘플 RMBegin2 」에서는, 태양, 지구, 달이 다른 오브젝트의 주위를 올바르게 회전하는 간단한 샘플을 순서를 쫓아 설명한다.
  • 「디바이스의 열거：RMEnum 샘플」에서는, 디바이스를 열거하는 샘플을 순서를 쫓아 설명한다.
  • 「장황한 상태 변경의 삭제」에서는, 퍼포먼스를 향상하기 위해서, 현재가와 같은 값이 되는 상태의 설정을 회피하는 방법에 대해 설명한다.

이 문서의 「샘플」시에는, 새롭게 생성 한 것이다. 이 마디는, 「Direct3D 보관 유지 모드 샘플의 인트러덕션」으로부터 시작된다. 여기에는, 다음의 새로운 항목이 포함되어 있다.

  • Developer Studio 5.0 을 사용한 샘플의 빌드
  • Direct3D 보관 유지 모드의 샘플

「Direct3D 보관 유지 모드의 개요」에는, 다음의 새로운 항목이 포함되어 있다.

  • 인터페이스 계층
  • 인터페이스의 변경점

새로운 인터페이스

Microsoft® Direct3D® 보관 유지 모드 버젼 6.0에서는, 몇개의 인터페이스, 및, 새로운 메소드에 의해 구버젼의 인터페이스에 신기능을 추가한 다수의 인터페이스가 도입되고 있다. 새로운 인터페이스 및 메소드의 완전한 리스트에 대해서는, 「인터페이스의 변경점」을 참조할것. 인터페이스의 계승에 대해서는, 「인터페이스 계층」을 참조할것.

이 문서에서는, 최신 버젼의 인터페이스를 소개하는 것으로 해, 버젼에 의한 기능의 상위에 대해서는 설명하지만, 중복 한 설명은 실시하지 않는다. 예를 들어, 구버젼의 메뉴얼에서는,IDirect3DRMTexture3::GetDecalSize ,IDirect3DRMTexture2::GetDecalSize,IDirect3DRMTexture::GetDecalSize에 대해, 거의 같은 설명이 따로 따로 기술되고 있었지만, 이 문서에서는, 최신 버젼의IDirect3DRMTexture3::GetDecalSize 로 정리해 설명하고 있다.

「C++/COM 레퍼런스」에는, 이하의 새로운 인터페이스가 포함되어 있다.

  • 보관 유지 모드 버젼 6.0에서는, 새로운IDirect3DRM3 인터페이스와Direct3DRM3 오브젝트가 도입되었다. IDirect3DRM3로 생성 된MeshBuilder3 오브젝트는, Direct3D 직접 모드의DrawPrimitive인터페이스를 사용한다. IDirect3DRM3로 생성 된 조명은, 직접 모드의 신기능을 이용해, 직접 모드의D3DLIGHT2구조체를 사용한다. IDirect3DRM3는,IDirect3DRM2와IDirect3DRM의 전기능을 제공한다. 플래그 파라미터가CreateDeviceFromSurface 에 추가되어 Z버퍼를 생성 하지 않는 것을 통지할 수 있게 되었다. RegisterClient 메소드와UnregisterClient 메소드가 추가되었다. 게다가IDirect3DRM3에 의해, 사용하는 지오메트리가 오른손 좌표계나 왼손 좌표계인지를 설정 및 취득하는GetOptions 메소드와SetOptions 메소드가 추가되었다.

  • 모든 오브젝트는, 새로운IDirect3DRMObject2인터페이스를 이행 하고 있다. IDirect3DRMObject2는, 다른 새로운 인터페이스와 달리, 구버젼의 메소드를 모두 이행 하고 있는 것은 아니다. IDirect3DRMObject2 와IDirect3DRMObject 에 대해서는, 이 문서로 개별적으로 설명한다. IDirect3DRMObject2에는, 새로운IDirect3DRM3::RegisterClient 메소드와IDirect3DRM3::UnregisterClient 메소드와 함께 동작하는SetClientData 메소드와GetClientData 메소드가 추가되었다. 게다가IDirect3DRMObject2에는,GetDirect3DRM 메소드와GetAge 메소드도 추가되었다.

  • IDirect3DRMAnimation2 에는,AddKey ,DeleteKeyByID ,GetKeys ,ModifyKey 메소드가 추가되어 애니메이션 키에의 액세스가 가능하게 되었다. 또, 대응하는 애니메이션의 프레임을 돌려주는GetFrame 메소드도 추가되었다.

  • 새로운IDirect3DRMAnimationArray 인터페이스를 사용 하면,GetSize 를 사용해 배열의 애니메이션수를 취득해,GetElement 를 사용해 애니메이션의 인터페이스를 요구할 수 있다.

  • IDirect3DRMAnimationSet2 에GetAnimations 메소드가 추가되어 구성 애니메이션을 취득할 수 있게 되었다.

  • 새로운IDirect3DRMClippedVisual 인터페이스를 사용 하면, 렌더링전에 임의의 프레인에 비주얼 오브젝트를 클립 할 수 있다. 새로운ClippedVisual 오브젝트는,Direct3DRM3 오브젝트로부터 생성 한다.

  • IDirect3DRMDevice3 에, 소정의 기준에 따라 텍스쳐 형식을 선택하는FindPreferredTextureFormat 메소드가 추가되었다. 또,IDirect3DRMDevice3 에는 몇개의 메소드 (GetStateChangeOptions ,LightStateChange ,RenderStateChange ,SetStateChangeOptions )가 추가되어, 장황한 상태 변경을 삭제할 수 있게 되었다.

  • IDirect3DRMFace2 에SetTexture 메소드가 추가되어 높이와 폭이 2의 거듭제곱 이외의 텍스쳐를 지정할 수 있게 되었다.

  • IDirect3DRMFrame3 는, 모델 공간과 월드 공간과의 사이에 보다 다채로운 변환을 실시하는 메소드를 제공한다. 4×4 행렬을 취득해, 호랑이 용기 옵션을 설정 및 취득해, 포그(안개:fog) 처리에 버텍스 포그(안개:fog) 또는 테이블 포그(안개:fog)의 어느 쪽을 사용하는지를 취득 및 설정한다. 또,IDirect3DRMFrame3는, 머트리얼의 오버라이드(override)를 설정 및 취득하는 메소드도 제공한다. SetOrientation 메소드는, 스케일링과 경사를 처리할 수 있게 되었다.

  • IDirect3DRMMaterial2 에GetAmbient 메소드와SetAmbient 메소드가 추가되어 머트리얼의 프로퍼티가 상세하게 제어할 수 있게 되었다.

  • IDirect3DRMMeshBuilder3 에, 면, 법선, 버텍스 오브젝트를 삭제하는 메소드가 추가되었다. 또,Empty 메소드와Optimize 메소드도 추가되었다. 다른 새로운IDirect3DRMMeshBuilder3메소드는, 1개 또는 복수의 법선, 법선수, 텍스쳐 위상기하학, 1개또는 복수의 버텍스, 및 메쉬 빌더 상태 (유효 또는 무효)를 취득한다. 이 인터페이스를 사용 하면, 버텍스와 법선을 설정하거나 서브 메쉬 및 메쉬 빌더의 친메쉬를 생성 및 취득할 수가 있다. 또,IDirect3DRMMeshBuilder3에 의해, 어플리케이션은,AddTriangles 를 사용해 새로운 삼각형을 추가하거나 새로운 면을 명시적으로 생성 할 수가 있다.

  • IDirect3DRMShadow2 에 메소드가 추가되어 비주얼, 조명, 프레인, 옵션 그림자 파라미터를 생성 후로 변경할 수 있게 되었다. SetOptions 를 사용 하면, 블렌드의 투명도를 유효하게 할 경우에, 비주얼 아치 팩트를 삭제하는 옵션을 설정할 수 있다.

  • IDirect3DRMTexture3 는,Changed 메소드를 확장해, 텍스쳐의 변경제영역을 지정할 수 있도록(듯이) 했다. IDirect3DRMTexture3는, 게다가 텍스쳐 관리 캐싱 메소드의GetCacheOptions 와SetCacheOptions 도 제공하고 있다. 새로운IDirect3DRMTexture3의 메소드로서는, 그 밖에,GetSurface ,SetDownSampleCallback ,SetValidationCallback 가 있다.

  • IDirect3DRMViewport2 는,Clear 에 플래그 파라미터를 추가해, 타겟 표면, Z버퍼 표면, 더티 직사각형 리스트를 클리어 할지 어떨지 통지한다.


문서의 구성

여기에서는, Microsoft® Direct3D® 보관 유지 모드의 문서로 특정의 항목을 찾는 참조 먼저 대해 설명한다.

보관 유지 모드를 처음으로 사용하는 경우는, 「인터페이스의 개요」를 최초로 읽어, 일반적인 개념을 이해하는 것. 3 D프로그래밍을 처음으로 실시하는 경우는, 「기초지식」을 읽는 것. 이것에 의해,튜토리얼과샘플에 대한 이해가 깊어진다. 「샘플」과「튜토리얼」에 게재한 코드의 처리의 상세한 것에 대하여는, 「레퍼런스」 및 「인터페이스」를 읽는 것. 「용어집」에서는, 일반적인 용어의 정의를 설명하고 있다.

상급 개발자는,DirectX 파일 포맷의 상세 정보가 필요하게 될 가능성이 있다. .

어디를 참조할까

다음의 리스트는, C++/COM 의 프로그래머가 자주(잘) 사용하는 정보와 그 참조처의 일람이다.
정보 | 참조처
에러 코드 | 반환값
인터페이스의 계승 | 인터페이스 계층
인터페이스의 이력 | 인터페이스의 변경점
인터페이스 | 인터페이스
정수 | 정수
열거형 | 열거형
구조체 | 구조체
샘플의 빌드 | Developer Studio 5.0에 의한 샘플의 빌드
Developer Studio | Developer Studio 5.0에 의한 샘플의 빌드
샘플 코드 | 샘플
보관 유지 모드 오브젝트 및 관련 COM 인터페이스 | 아키텍쳐
3 D그래픽스 개념 | 기초지식
DirectX 파일 | DirectX 파일 포맷

다음의 리스트는, Microsoft Visual Basic 의 프로그래머가 자주(잘) 사용하는 정보와 그 참조처의 일람이다.
정보 | 참조처
에러 코드 | 반환값
인터페이스 | 인터페이스
콜백 | 콜백 함수
열거형 | 열거형
구조체 | 구조체
3 D그래픽스 개념 | 기초지식
DirectX 파일 | DirectX 파일 포맷


오브젝트의 회전：RMBegin1 샘플

디바이스의 생성, 장면의 구축과 이동은, Microsoft® Direct3D®보관 유지 모드의 기본적인 개념이다. RMBegin1 샘플에서는, 디폴트의 디바이스를 생성 해, Microsoft DirectX®파일로부터 메쉬를 로드해, 오브젝트에 색을 추가해, 장면에 조명을 추가해, 오브젝트를 회전하는 것으로, 이 기본적인 개념을 구체적으로 가리킨다. 샘플에서는, 장면의 구축시에 메쉬 빌더, 프레임, 조명, 머트리얼을 사용한다. 게다가DirectDrawClipper오브젝트, 뷰포트,카메라도 생성 한다.

이 항에서는, RMBegin1 샘플의 코드의 워크 스루를 실시한다. 샘플 소스 코드는, 필요한 요소를 모두 갖춘 1개의 파일 (RMBegin1.cpp)로 구성되어 있어 Microsoft Windows® DirectDraw® 및 Direct3D 보관 유지 모드의 표준 헤더 파일 이외의 개별의 헤더 파일은 사용하고 있지 않다. 이것은, 알기 쉽게하기 위해(때문에)이다. 메뉴나 아이콘등의 리소스도 사용하고 있지 않다.

이 샘플은, DirectX Foundation SDK (Software Development Kit)의 Teapot.x 파일을 사용해, 장면에 티폿(주전자)의 화면을 준다. 디폴트에서는, SDK를 인스톨 하면, SDK의 셋업 프로그램은, 환경 변수를 SDK의 미디어 디렉토리로 설정한다. Teapot.x 파일은 미디어 디렉토리에 있으므로, 어플리케이션은 파일을 자동적으로 검출한다. SDK를 인스톨 하지 않고 RMBegin1.exe를 실행하는 경우, Teapot.x 파일은 RMBegin1.exe와 같은 디렉토리에 둘 필요가 있다.

이 항은, 유저가 C 또는 C++의 프로그래밍 경험이 있는 것, 또, 메시지 루프, 윈도우의 생성, 메뉴의 사용 등, Windows 프로그래밍의 기본 개념에 정통하고 있는 것을 전제로 하고 있다.

이 항은, 다음의 항목으로 나누어져 있다.

  • 전제
  • 글로벌 선언
  • 함수 개요
  • 관련 주제

전제

  • RMBegin1는 DDraw.lib와 D3DRM.lib를 링크한다.
  • RMBegin1는, 전술과 같이, Teapot.x로부터 티폿(주전자)의 화면을 로드한다.
  • Direct3D 어플리케이션은, 글로벌 유니크 식별자 (GUID)를 적절히 초기화하기 위해서, 코드의 선두에서 다음의 정의를 실시할 필요가 있다.
    #define INITGUID
  • 샘플의 RMBegin1.cpp 파일은 다음의 헤더 파일을 인클루드 하고 있다.
    #include <windows.h>   // 표준 Windows 헤더 파일
#include <direct.h>    // DirectDraw 의 정의
#include <d3drmwin.h>  // Direct3D 보관 유지 모드의 정의

글로벌 선언

이 샘플에서는, 몇개의 정수와 글로벌 변수를 정의해, 정보를 정리한다.

어플리케이션으로 정의되고 있는 RELEASE 매크로는, 오브젝트가 NULL 이외의 경우에만 오브젝트를 릴리즈 해, 릴리즈 후에 오브젝트를 NULL에 초기화한다. 벌써 릴리즈 한 오브젝트를 릴리즈 하면, 페이지 폴트등의 예기치 못한 결과가 발생하지만, 이 순서에 의해, 그러한 문제를 회피할 수 있다.

// 오브젝트를 릴리즈 하는 매크로
#define RELEASE(x) if (x ! = NULL) {x->Release(); x = NULL;}

어플리케이션으로 정의되고 있는 DISPLAYMSG 매크로는, Windows MessageBox 함수를 사용해 유저에 대해서 정보를 표시한다. 이 매크로를 사용 하면, 샘플 코드로 MessageBox를 직접 호출하는 것보다도, 코드가 간소화되어 읽기 쉬워진다.

// 주어진 캐릭터 라인을 포함한 메시지 박스를 표시하는 매크로
#define DISPLAYMSG(x) MessageBox(NULL, x, "D3DRM Sample", MB_OK);

글로벌 변수는, Direct3D 보관 유지 모드 및 DirectDrawClipper 오브젝트등이 주요한 오브젝트를 추적한다. DirectDrawClipper 오브젝트는, 드로잉(Drawing)을 지정한 영역에 제한한다. myglobs 구조체는, 디바이스, 뷰포트, 장면, 카메라에 관한 정보에 가세해, 어플리케이션의 최소화나 오브젝트의 초기화에 관한 정보도 수집한다.

// 글로벌 변수
LPDIRECT3DRM lpD3DRM = NULL;            // Direct3DRM 오브젝트
LPDIRECTDRAWCLIPPER lpDDClipper = NULL; // DirectDrawClipper 오브젝트

// 글로벌 구조체
struct _myglobs {

    // Direct3D 보관 유지 모드 디바이스
    LPDIRECT3DRMDEVICE dev;

    // 장면을 표시하는 Direct3D 보관 유지 모드 뷰포트
    LPDIRECT3DRMVIEWPORT view;

    // 다른 프레임을 배치하는 마스터 프레임
    LPDIRECT3DRMFRAME scene;

    // 유저의 시점을 기술하는 프레임
    LPDIRECT3DRMFRAME camera;

    // 어플리케이션은 최소화되고 있다.
    BOOL bMinimized;

    // Direct3D 보관 유지 모드의 전오브젝트가 초기화되고 있다.
    BOOL bInitialized;

} myglobs;

함수 개요

RMBegin1.cpp에는, 이하의 함수가 포함되어 있다.

BuildScene 함수는, 렌더링 하는 장면을 생성 한다. DirectX 파일로부터 메쉬를 로드해, 색을 메쉬에 추가해, 장면에 조명을 추가한다. 게다가BuildScene는, 오브젝트의 위치와 회전의 방법을 설정한다. 글로벌 변수를 초기화해, 디폴트의 디바이스, 프레임, 뷰포트를 생성 하는CreateObjects가, 이 함수를 사용한다.

BOOL BuildScene(LPDIRECT3DRM, LPDIRECT3DRMDEVICE,
                LPDIRECT3DRMFRAME, LPDIRECT3DRMFRAME);

RenderScene 함수는,BuildScene가 생성 한 장면을 드로잉(Drawing) 한다. WinMain가 이 함수를 사용할 때마다,RenderScene는 장면을 이동해, 오브젝트에 회전 효과를 준다.

static BOOL RenderScene(void);

CreateObjects 함수는, 글로벌 변수를 초기화해, 디폴트의 디바이스, 카메라 프레임, 장면 프레임, 뷰포트를 생성 한다. CreateObjects는BuildScene를 사용해, 렌더링 하는 장면을 생성 한다. InitApp가CreateObjects를 사용한다.

BOOL CreateObjects(HWND win);

InitApp 함수는, Windows 어플리케이션의 표준적인 코드에 의해, 윈도우 클래스와 어플리케이션의 윈도우를 생성 한다. InitApp는,CreateObjects를 사용해, 글로벌 오브젝트를 초기화한다.

static HWND InitApp(HINSTANCE, int);

WinMain 함수는, 어플리케이션의 메시지 루프를 제공한다. InitApp를 사용해 어플리케이션을 초기화해,RenderScene를 사용해 장면을 드로잉(Drawing) 한다.

int APIENTRY WinMain(HINSTANCE, HINSTANCE, LPSTR, int);

WindowProc 함수는, 어플리케이션의 메세지를 처리한다. 어플리케이션의 최소화나 파기를 처리한다.

LRESULT CALLBACK WindowProc(HWND, UINT, WPARAM, LPARAM);

이상의 함수의 상세한 것에 대하여는, 이 항의 다음의 항목을 참조할것.

  • BuildScene
  • RenderScene
  • CreateObjects
  • InitApp
  • WinMain
  • WindowProc

BuildScene

BuildScene함수는, 렌더링 하는 장면을 생성 한다. Direct3D 보관 유지 모드의 모든 어플리케이션은 장면을 생성 할 필요가 있지만, 필요한 코드는 장면에 의존한다. 어플리케이션은 보통, 프레임과 조명을 생성 해, 시각적인 요소를 장면에 추가해, 오브젝트의 위치를 설정한다.

이 마디에서는,BuildScene함수의 코드를 부분적으로 나타내, RMBegin1 샘플이 장면을 구축하는 순서에 대해 설명한다. 게다가 RMBegin1 샘플의BuildScene함수에 관한 모든 소스 코드도 가리킨다. 에러가 발생했을 경우는,goto문으로 함수의 마지막에 점프 해, 함수로부터 돌아가기 전에, 모든 오브젝트를 적절히 릴리즈 한다.

  1. IDirect3DRM3::CreateMeshBuilder 와IDirect3DRMMeshBuilder3::Load 메소드를 사용해, DirectX 파일로부터 메쉬를 로드한다.
        if (FAILED(lpD3DRM->CreateMeshBuilder(&meshbuilder)))
        goto generic_error;

    rval = meshbuilder->Load("teapot.x",
                              NULL, D3DRMLOAD_FROMFILE, NULL, NULL);
  2. IDirect3DRM3::CreateFrame 메소드를 사용해, 장면의 아이 프레임을 생성 한다.
        if (FAILED(lpD3DRM->CreateFrame(scene, &childframe)))
        goto generic_error;
  3. IDirect3DRMFrame3::AddVisual 메소드를 사용해, 로드한 메쉬를 아이 프레임에 추가한다.
        if (FAILED(childframe->AddVisual((LPDIRECT3DRMVISUAL) meshbuilder)))
        goto generic_error;
  4. IDirect3DRMFrame3::SetPosition 메소드를 사용해, 장면에 카메라 위치를 설정한다.
        rval = camera->SetPosition(scene, D3DVAL(0), D3DVAL(0), -D3DVAL(7));
  5. IDirect3DRMFrame3::SetRotation 메소드를 사용해, 아이 프레임의 회전을 설정한다.
        if (FAILED(childframe->SetRotation(scene,
                                       D3DVAL(0), D3DVAL(1), D3DVAL(0),
                                       D3DVAL(0.03)))) // 각도
        goto generic_error;
  6. IDirect3DRM3::CreateFrame 메소드를 사용해, 장면의 아이 프레임이 되는 조명 프레임을 생성 한다.
        if (FAILED(lpD3DRM->CreateFrame(scene, &lights)))
        goto generic_error;
  7. IDirect3DRMFrame3::SetPosition 메소드를 사용해, 장면에 조명 프레임을 배치한다.
        if (FAILED(lights->SetPosition(scene,
                                   D3DVAL(5), D3DVAL(0), -D3DVAL(7))))
        goto generic_error;
  8. IDirect3DRM3::CreateLightRGB 와IDirect3DRMFrame3::AddLight 메소드를 사용해, 밝은패러럴 포인트조명을 생성 해, 조명 프레임에 추가한다.
        if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_PARALLELPOINT,
                                       D3DVAL(1.0), D3DVAL(0.8),
                                       D3DVAL(0.9), &light1)))
        goto generic_error;

    if (FAILED(lights->AddLight(light1)))
        goto generic_error;
  9. IDirect3DRM3::CreateLightRGB 와IDirect3DRMFrame3::AddLight 메소드를 한번 더 사용해, 어두운앰비언트조명을 생성 해, 장면에 추가한다.
        if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_AMBIENT,
                                       D3DVAL(0.1), D3DVAL(0.1),
                                       D3DVAL(0.1), &light2)))
        goto generic_error;

    if (FAILED(scene->AddLight(light2)))
        goto generic_error;
  10. IDirect3DRM3::CreateMaterial 와IDirect3DRMMeshBuilder3::SetMaterial 메소드를 사용해, 머트리얼을 생성 해, 반사 특성을 설정한다.
        if (FAILED(lpD3DRM->CreateMaterial(D3DVAL(10.0), &mat)))
        goto generic_error;

    if (FAILED(meshbuilder->SetMaterial(mat)))
        goto generic_error;
  11. IDirect3DRMMeshBuilder3::SetColorRGB 메소드를 사용해, 메쉬의 색을 설정한다.
        if (FAILED(meshbuilder->SetColorRGB(D3DVAL(0.0),   // 빨강
                                        D3DVAL(0.7),   // 초록
                                        D3DVAL(0.0)))) // 파랑
        goto generic_error;
  12. 이 함수로 생성 한 모든 오브젝트를 릴리즈 해 종료한다.
        RELEASE(childframe);
    RELEASE(lights);
    RELEASE(meshbuilder);
    RELEASE(light1);
    RELEASE(light2);
    RELEASE(mat);

BuildScene함수 소스 코드

// 렌더링 하는 장면을 생성 한다.

BOOL BuildScene(LPDIRECT3DRM lpD3DRM,
                LPDIRECT3DRMDEVICE dev,
                LPDIRECT3DRMFRAME scene,
                LPDIRECT3DRMFRAME camera)
{
    LPDIRECT3DRMFRAME lights = NULL;
    LPDIRECT3DRMMESHBUILDER meshbuilder = NULL;
    LPDIRECT3DRMFRAME childframe = NULL;
    LPDIRECT3DRMLIGHT light1 = NULL;
    LPDIRECT3DRMLIGHT light2 = NULL;
    LPDIRECT3DRMMATERIAL mat = NULL;
    HRESULT rval;

    // irectX 파일로부터 메쉬를 로드한다.
    if (FAILED(lpD3DRM->CreateMeshBuilder(&meshbuilder)))
        goto generic_error;

    rval = meshbuilder->Load("teapot.x",
                              NULL, D3DRMLOAD_FROMFILE, NULL, NULL);
    if (FAILED(rval))
    {
        DISPLAYMSG("Failed to load . x file. ");
        goto ret_with_error;
    }

    // 장면의 아이 프레임을 생성 한다.
    if (FAILED(lpD3DRM->CreateFrame(scene, &childframe)))
        goto generic_error;

    // 로드한 메쉬를 아이 프레임에 추가한다.
    if (FAILED(childframe->AddVisual((LPDIRECT3DRMVISUAL) meshbuilder)))
        goto generic_error;

    // 카메라 프레임 위치를 설정한다. 카메라와 같은 x 값과
    // y 값을 가지는 오브젝트는, 똑바로 표시된다.
    // z 값이 마이너스이라고, 오브젝트는 멀어져,
    // 음수의 절대치가 커지는 만큼, 오브젝트는 작아진다.
    rval = camera->SetPosition(scene, D3DVAL(0), D3DVAL(0), -D3DVAL(7));
    if (FAILED(rval))
    {
        DISPLAYMSG("Failed to position the camera in the frame. ");
        goto ret_with_error;
    }

    // 아이 메쉬를 y 축으로 따라 회전시킨다 (x 값과 z 값은 제로).
    // 작은 회전각을 사용해, 천천히 회전시킨다.
    if (FAILED(childframe->SetRotation(scene,
                                       D3DVAL(0), D3DVAL(1), D3DVAL(0),
                                       D3DVAL(0.03)))) // angle
        goto generic_error;

    // 장면의 조명을 초기화한다. 장면의 아이 프레임이 된다
    // 조명 프레임을 생성 한다.
    if (FAILED(lpD3DRM->CreateFrame(scene, &lights)))
        goto generic_error;

    // 조명 프레임을 장면에 배치한다. 빛은 카메라의 우측으로부터 비춘다.
    // x 값은 다르지만, y 값과 z 값은 카메라 위치와 같다.
    if (FAILED(lights->SetPosition(scene,
                                   D3DVAL(5), D3DVAL(0), -D3DVAL(7))))
        goto generic_error;

    // 밝은 패러럴 포인트 조명을 생성 해, 조명 프레임에 추가한다.
    // 컬러값은, 0.0 (어둡다)에서 1.0 (밝다)까지의 범위로 한다.
    if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_PARALLELPOINT,
                                       D3DVAL(1.0), D3DVAL(0.8),
                                       D3DVAL(0.9), &light1)))
        goto generic_error;

    if (FAILED(lights->AddLight(light1)))
        goto generic_error;

    // 어두운 앰비언트 조명을 생성 해, 장면의 프레임에 추가해,
    // 장면 전체에 적용한다. 앰비언트 조명은 전방향으로부터 비춘다. 따라서,
    // 밝은 앰비언트 조명은 오브젝트의 색을 진하지 않게 한다.
    if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_AMBIENT,
                                       D3DVAL(0.1), D3DVAL(0.1),
                                       D3DVAL(0.1), &light2)))
        goto generic_error;

    if (FAILED(scene->AddLight(light2)))
        goto generic_error;

    // 머트리얼을 생성 해, 전에 로드한 메쉬의 반사 특성을 설정한다
    // (5.0 은 금속적인 외관이 되어, 그 이상의 값에서는, 보다 부드러운 외관이 된다).
    if (FAILED(lpD3DRM->CreateMaterial(D3DVAL(10.0), &mat)))
        goto generic_error;

    if (FAILED(meshbuilder->SetMaterial(mat)))
        goto generic_error;

    // 메쉬의 색을 설정한다. 여기에서는 밝은 초록으로 한다.
    if (FAILED(meshbuilder->SetColorRGB(D3DVAL(0.0),   // 빨강
                                        D3DVAL(0.7),   // 초록
                                        D3DVAL(0.0)))) // 파랑
        goto generic_error;

    // 종료 처리.
    RELEASE(childframe);
    RELEASE(lights);
    RELEASE(meshbuilder);
    RELEASE(light1);
    RELEASE(light2);
    RELEASE(mat);
    return TRUE;

generic_error:
    DISPLAYMSG("A failure occured while building the scene. ");
ret_with_error:
    RELEASE(childframe);
    RELEASE(lights);
    RELEASE(meshbuilder);
    RELEASE(light1);
    RELEASE(light2);
    RELEASE(mat);
    return FALSE;
}

RenderScene

RenderScene함수는, 실제로 장면을 스크린에 드로잉(Drawing) 한다. BuildScene가 생성 한 장면을 다음의 순서에 따라 드로잉(Drawing) 한다.

  1. IDirect3DRMFrame3::Move 를 사용해, 장면을 이동한다.
  2. IDirect3DRMViewport2::Clear 를 사용해, 뷰포트를 클리어 한다.
  3. IDirect3DRMViewport2::Render 를 사용해, 장면을 렌더링 한다.
  4. IDirect3DRMDevice3::Update 를 사용해, 윈도우를 갱신한다.

RenderScene함수 소스 코드

// 뷰포트를 클리어 해, 다음의 프레임을 렌더링 해, 윈도우를 갱신한다.

static BOOL RenderScene()
{
    HRESULT rval;

    // 장면의 이동.
    rval = myglobs.scene->Move(D3DVAL(1.0));
    if (FAILED(rval))
    {
        DISPLAYMSG("Moving scene failed. ");
        return FALSE;
    }

    // 뷰포트의 클리어.
    rval = myglobs.view->Clear();
    if (FAILED(rval))
    {
        DISPLAYMSG("Clearing viewport failed. ");
        return FALSE;
    }

    // 장면을 뷰포트에 렌더링 한다.
    rval = myglobs.view->Render(myglobs.scene);
    if (FAILED(rval))
    {
        DISPLAYMSG("Rendering scene failed. ");
        return FALSE;
    }

    // 윈도우의 갱신.
    rval = myglobs.dev->Update();
    if (FAILED(rval))
    {
        DISPLAYMSG("Updating device failed. ");
        return FALSE;
    }
    return TRUE;
}

CreateObjects

CreateObjects는, 샘플의 글로벌 변수를 초기화해, 오브젝트를 생성 한다. 글로벌 변수를 초기화한 후, 디바이스의 생성에 필요한 순서를 실행해, 디바이스를 어플리케이션의 메인 윈도우에 관련지어 마스터 신 프레임, 카메라 프레임, 뷰포트를 생성 한다. 이하의 순서에 따른다.

  1. irectDraw의DirectDrawCreateClipper함수를 사용해, DirectDrawClipper 오브젝트를 생성 한다.
  2. DirectDrawClipper의SetHWnd메소드를 사용해, 어플리케이션의 윈도우를 DirectDrawClipper에 관련짓는다. DirectDrawClipper 오브젝트는, 후속의 드로잉(Drawing)를, 지정한 영역 (여기에서는, 어플리케이션의 윈도우)에 제한한다.
  3. Direct3DRMCreate 함수를 사용해, Direct3D 보관 유지 모드 오브젝트를 생성 한다.
  4. Windows의GetClientRect함수를 사용해, 어플리케이션의 메인 윈도우의 높이와 폭을 취득한다.
  5. Direct3D 보관 유지 모드 오브젝트의CreateDeviceFromClipper 메소드를 사용해 디바이스를 생성 해, NULL를 건네주어 디폴트 디바이스를 생성 한다. 게다가 어플리케이션의 윈도우의 폭과 높이를 메소드에 건네준다.
  6. IDirect3DRM3::CreateFrame 를 사용해, 마스터 신 프레임을 생성 한다.
  7. IDirect3DRM3::CreateFrame 를 사용해, 카메라 프레임을 생성 한다.
  8. IDirect3DRM3::CreateViewport 를 사용해, Direct3D 보관 유지 모드의 뷰포트를 생성 한다.
  9. BuildScene 를 사용해, 장면을 생성 한다.

CreateObjects함수 소스 코드

// 글로벌 변수를 초기화해, 디바이스와 오브젝트를 생성 한다.

BOOL CreateObjects(HWND win)
{
    HRESULT rval; // 반환값
    RECT rc;      // 메인 윈도우의 직사각형의 경계
    int width;    // 디바이스의 폭
    int height;   // 디바이스의 높이

    // 글로벌 변수 구조체의 전체를 제로에 초기화한다.
    memset(&myglobs, 0, sizeof(myglobs));

    // DirectDrawClipper 오브젝트를 생성 해, 윈도우를 관련짓는다.
    rval = DirectDrawCreateClipper(0, &lpDDClipper, NULL);
    if (FAILED(rval))
    {
        DISPLAYMSG("Failed to create DirectDrawClipper object");
        return FALSE;
    }

    rval = lpDDClipper->SetHWnd(0, win);
    if (FAILED(rval))
    {
        DISPLAYMSG("Failed to set the window handle for the DirectDrawClipper");
        return FALSE;
    }

    // Direct3D 보관 유지 모드 오브젝트를 생성 한다.
    rval = Direct3DRMCreate(&lpD3DRM);
    if (FAILED(rval))
    {
        DISPLAYMSG("Failed to create Direct3DRM. ");
        return FALSE;
    }

    // Direct3D 보관 유지 모드의 디폴트 디바이스를 생성 한다.
    GetClientRect(win, &rc);

    rval = lpD3DRM->CreateDeviceFromClipper(lpDDClipper,
                           NULL, // 디폴트 디바이스
                           rc.right, rc.bottom, &myglobs.dev);
    if (FAILED(rval))
    {
        DISPLAYMSG("Failed to create the D3DRM device. ");
        return FALSE;
    }

    // 마스터 신 프레임과 카메라 프레임을 생성 한다.
    rval = lpD3DRM->CreateFrame(NULL, &myglobs.scene);
    if (FAILED(rval))
    {
        DISPLAYMSG("Failed to create the master scene frame. ");
        return FALSE;
    }

    rval = lpD3DRM->CreateFrame(myglobs.scene, &myglobs.camera);
    if (FAILED(rval))
    {
        DISPLAYMSG("Failed to create the camera's frame. ");
        return FALSE;
    }

    // 디바이스, 카메라 프레임, 디바이스의 폭과 높이를 사용해,
    // Direct3D 보관 유지 모드의 뷰포트를 생성 한다.
    wid
    height = myglobs.dev->GetHeight();

    rval = lpD3DRM->CreateViewport(myglobs.dev, myglobs.camera, 0, 0,
                                   width, height, &myglobs.view);
    if (FAILED(rval))
    {
        myglobs.bInitialized = FALSE;
        RELEASE(myglobs.dev);
        return FALSE;
    }

    // 렌더링 하는 장면을 생성 한다.
    if (! BuildScene(lpD3DRM, myglobs.dev, myglobs.scene,
                    myglobs.camera))
        return FALSE;

    // 글로벌 변수는 초기화되었다.
    myglobs.bInitialized = TRUE;

    return TRUE;
}

InitApp

InitApp함수는, 메인 윈도우 클래스와 메인 윈도우를 생성 한다. 이것은, Windows 어플리케이션에서는 일반적인 처리이다. InitApp로부터 불려 가는 Direct3D 보관 유지 모드는,CreateObjects 의 호출 뿐이다.

InitApp함수 소스 코드

// 메인 윈도우를 생성 해, 오브젝트를 초기화한다.

static HWND InitApp(HINSTANCE this_inst, int cmdshow)
{
    HWND win;     // 메인 윈도우 핸들
    WNDCLASS wc;  // 윈도우 클래스

    // 윈도우 클래스를 설정해 등록한다.
    wc.style = CS_HREDRAW | CS_VREDRAW;
    wc.lpfnWndProc = WindowProc;
    wc.cbClsExtra = 0;
    wc.cbWndExtra = sizeof(DWORD);
    wc.hInstance = this_inst;
    wc.hIcon = LoadIcon(NULL, IDI_APPLICATION);
    wc.hCursor = LoadCursor(NULL, IDC_ARROW);
    wc.hbrBackground = (HBRUSH) GetStockObject(BLACK_BRUSH);
    wc.lpszMenuName = NULL;
    wc.lpszClassName = "D3DRM Example";
    if (! RegisterClass(&wc))
        return FALSE;

    // 윈도우의 생성.
    win = CreateWindow(
            "D3DRM Example",                   // 클래스
            "RMBegin1: Direct3DRM Sample One", // 캡션
            WS_OVERLAPPEDWINDOW,               // 스타일
            CW_USEDEFAULT,                     // init.  x pos
            CW_USEDEFAULT,                     // init.  y pos
            350,                               // init.  x size
            300,                               // init.  y size
            NULL,                              // 부모 윈도우
            NULL,                              // 메뉴 핸들
            this_inst,                         // 프로그램 핸들
            NULL);                             // 생성 파라미터

    if (! win)
        return FALSE;

    // 글로벌 변수를 초기화해, Direct3D 보관 유지 모드
    // 오브젝트를 생성 한다.
    if (! CreateObjects(win))
        return FALSE;

    // 윈도우의 표시.
    ShowWindow(win, cmdshow);
    UpdateWindow(win);

    return win;
}

WinMain

WinMain함수는, 어플리케이션의 메시지 루프를 제공한다. 글로벌 변수가 초기화되고 있어, 어플리케이션이 최소화되어 있지 않으면, WinMain는RenderScene 를 사용해 장면을 스크린에 드로잉(Drawing) 한다.

WinMain함수 소스 코드

// 어플리케이션을 초기화해, 메세지를 처리해, 장면을 렌더링 한다.

int APIENTRY WinMain (HINSTANCE this_inst,
                      HINSTANCE prev_inst,
                      LPSTR cmdline,
                      int cmdshow)
{
    HWND    hwnd;
    MSG     msg;
    prev_inst;
    cmdline;

    // 윈도우를 생성 해, 오브젝트를 초기화한다.
    if (! (hwnd = InitApp(this_inst, cmdshow)))
        return 1;

    while (TRUE)
    {
        // 메시지 큐를 감시해, 메세지를 처리한다. PeekMessage는
        // 제어를 즉석에서 어플리케이션에 돌려주므로, 어플리케이션은
        // 메세지의 처리와 렌더링을 계속할 수 있다.
        // 메세지가 WM_QUIT이면, 어플리케이션이 종료하고 있기 (위해)때문에,
        // 이 함수를 빠진다.
        if (PeekMessage(&msg, NULL, 0, 0, PM_REMOVE))
        {
            if (msg.message == WM_QUIT)
                break;
            TranslateMessage(&msg);
            DispatchMessage(&msg);
        }

        // 어플리케이션이 최소화되지 않고, Direct3D 보관 유지 모드
        // 오브젝트가 초기화되고 있으면, 렌더링을 실시한다.
        if (! myglobs.bMinimized && myglobs.bInitialized)
        {
            // 장면을 1 프레임, 렌더링 한다. 렌더링이 실패하면(자),
            // WM_DESTROY 메세지를 발행한다. 이것에 의해, 어플리케이션이
            // 종료하기 전에, 리소스를 릴리즈 할 수 있다.
            if (! RenderScene())
            {
                DISPLAYMSG("Rendering failed.  Aborting execution. ");
                PostMessage(NULL, WM_DESTROY, 0, 0);
                break;
            }

        // 이 어플리케이션이 현재 렌더링을 하고 있지 않으면,
        // 다른 어플리케이션에 제어를 건네준다.
        } else
              WaitMessage();

    }
    return msg.wParam;
}

WindowProc

WindowProc는, 어플리케이션의 메인 윈도우의 메세지를 처리한다. 플래그를 세트 해, 어플리케이션이 최소화되고 있을 때는 렌더링을 정지시킨다. 게다가 이 함수는, 어플리케이션이 슛다운 했을 때에 오브젝트를 릴리즈 한다.

WindowProc함수 소스 코드

// 메인 윈도우의 메세지를 처리한다.

LRESULT CALLBACK WindowProc(HWND win,
                            UINT msg,
                            WPARAM wparam,
                            LPARAM lparam)
{
    switch (msg)
    {
        case WM_SIZE:
            // 윈도우의 최소화를 처리한다. 어플리케이션이 최소화되어
            // 있으면, 플래그를 세트 해, 최소화시에는 렌더링을 정지한다.
            // 그 이외의 경우는, 렌더링을 계속한다.
            if (SIZE_MINIMIZED == wparam)
                myglobs.bMinimized = TRUE;
            else
                myglobs.bMinimized = FALSE;
            break;

        case WM_DESTROY:
            // bInitialized 플래그를 클리어 해, 오브젝트를 릴리즈 해,
            // WM_QUIT 메세지를 발행해, 어플리케이션을 종료한다.
            // 디바이스를 릴리즈 하기 전에, 뷰포트를 릴리즈 하는 것.
            // 이 순서를 잘못하면(자), 일반보호위반이 발생한다.
            myglobs.bInitialized = FALSE;
            RELEASE(myglobs.view);
            RELEASE(myglobs.dev);
            RELEASE(lpD3DRM);
            RELEASE(lpDDClipper);
            PostQuitMessage(0);
            break;

        default:
            return DefWindowProc(win, msg, wparam, lparam);
    }
    return 0L;
}

관련 주제

여기에서는 Direct3D 보관 유지 모드를 사용해 오브젝트를 생성 해, 스크린에 배치하는 기본을 학습했다. Direct3D 보관 유지 모드의 샘플 코드가, 전보다도 간단하게 이해할 수 있게 되었을 것이다. 대부분의 샘플은,RMMain 가 제공하는 헬퍼 코드를 사용해 디바이스를 생성 해, 장면을 렌더링 하고 있지만, 독자적인BuildScene함수에 의해, 각각의 장면을 생성 하고 있다.

다음의 스텝으로서는, RMBegin1의 기능을 확장한,RMBegin2 샘플을 보면(자) 좋다. 또, RMBegin1와 닮은 기능을 가지는Egg 나Globe 등의 Direct3D 보관 유지 모드 샘플을 조사해도 괜찮다.

하나 더의 Direct3D 보관 유지 모드의 일반적인 태스크에 대해서는, 「디바이스의 열거：샘플 RMEnum 」를 참조할것. 이 마디에서는, RMEnum의 샘플 코드의 워크 스루를 실시한다. RMEnum는, 디바이스를 열거하는 방법으로 초점을 맞히고 있다.

보관 유지 모드 샘플의 모든 개요에 대해서는, 「샘플」을 참조할것.


프레임 계층：RMBegin2 샘플

디바이스의 생성, 장면의 구축과 이동은, Microsoft® Direct3D®보관 유지 모드의 기본적인 개념이다. RMBegin2 샘플은,RMBegin1 샘플로 소개한, 이 기본 개념 위에 구축되고 있다. 이 마디에서는, RMBegin2 샘플의 코드의 워크 스루를 실시한다.

RMBegin2 샘플은, RMBegin1와 같이, 디폴트 디바이스를 생성 해, Microsoft DirectX®파일로부터 메쉬를 로드해, 오브젝트에 색을 추가해, 장면에 조명을 추가해, 오브젝트를 회전한다. RMBegin2 샘플에서는, RMBegin1보다 복잡한 장면을 구축해, 오브젝트를 스케일링 해, 프레임 계층을 사용한다. 장면을 구축할 때, 이 샘플에서는, 3개의 메쉬 빌더, 복수의 프레임, 복수의 조명을 사용한다. 또,DirectDrawClipper오브젝트, 뷰포트,카메라도 생성 한다. RMBegin2 샘플에는, 어플리케이션의 윈도우 사이즈를 변경할 때 장면을 리사이즈 해, WM_ACTIVATE 메세지와 WM_PAINT 메세지를 처리하는 새로운 기능이 추가되고 있다.

RMBegin2에서는, 3개의 구(공)체 (태양, 지구, 달)의 프레임 계층을 사용한다. 각 구(공)체는 각각의 친프레임의 주위를 회전한다.

RMBegin2 샘플의 코드는, 필요한 요소를 모두 갖춘 1개의 파일 (RMBegin2.cpp)로 구성되어 있다. 알기 쉽게하기 위해(때문에), Microsoft Windows® DirectDraw® 및 Direct3D 보관 유지 모드의 표준 헤더 파일 이외의 개별의 헤더 파일은 사용하고 있지 않다. 메뉴나 아이콘등의 리소스도 사용하고 있지 않다.

이 샘플은, DirectX Foundation SDK (Software Development Kit)의 Sphere0.x, Sphere1.x, Sphere2.x 파일을 사용해, 장면에 달, 지구, 태양의 화면을 준다. 디폴트에서는, SDK를 인스톨 하면, SDK의 셋업 프로그램은, 환경 변수를 SDK의 미디어 디렉토리로 설정한다. 3개의 DirectX (. x) 파일은 미디어·디렉토리에 있으므로, 어플리케이션은 파일을 자동적으로 검출한다. SDK를 인스톨 하지 않고 RMBegin2.exe를 실행하는 경우, DirectX 파일은 RMBegin2.exe와 같은 디렉토리에 둘 필요가 있다.

이 항은, 유저가 C 또는 C++의 프로그래밍 경험이 있는 것, 및 메시지 루프, 윈도우의 생성, 메뉴의 사용 등, Windows 프로그래밍의 기본 개념에 정통하고 있는 것을 전제로 하고 있다.

이 항은, 다음의 항목으로 나누어져 있다.

  • 전제
  • 글로벌 선언
  • 함수 개요
  • 관련 주제

전제

  • RMBegin2는 DDraw.lib와 D3DRM.lib를 링크한다.
  • RMBegin2는, 전술과 같이, Sphere0.x, Sphere1.x, Sphere2.x 로부터 구(공)체의 화면을 로드한다.
  • Direct3D 어플리케이션은, 글로벌 유니크 식별자 (GUID)를 적절히 초기화하기 위해서, 코드의 선두에서 다음의 정의를 실시할 필요가 있다.
    #define INITGUID
  • 샘플의 RMBegin2.cpp 파일은 다음의 헤더 파일을 인클루드 하고 있다.
    #include <windows.h>   // 표준 Windows 헤더 파일
#include <direct.h>    // DirectDraw 정의
#include <d3drmwin.h>  // Direct3D 보관 유지 모드 정의

글로벌 선언

이 샘플에서는, 몇개의 정수와 글로벌 변수를 정의해, 정보를 정리한다.

어플리케이션으로 정의되고 있는 RELEASE 매크로는, 오브젝트가 NULL 이외의 경우에만 오브젝트를 릴리즈 해, 릴리즈 후에 오브젝트를 NULL에 초기화한다. 벌써 릴리즈 한 오브젝트를 릴리즈 하면, 페이지 폴트등의 예기치 못한 결과가 발생하지만, 이 순서에 의해, 그러한 문제를 회피할 수 있다.

// 오브젝트를 릴리즈 하는 매크로
#define RELEASE(x) if (x ! = NULL) {x->Release(); x = NULL;}

어플리케이션으로 정의되고 있는 DISPLAYMSG 매크로는, Windows MessageBox 함수를 사용해 유저에 대해서 정보를 표시한다. 이 매크로를 사용 하면, 샘플 코드로 MessageBox를 직접 호출하는 것보다도, 코드가 간소화되어 읽기 쉬워진다.

// 주어진 캐릭터 라인을 포함한 메시지 박스를 표시하는 매크로
#define DISPLAYMSG(x) MessageBox(NULL, x, "D3DRM Sample", MB_OK);

글로벌 변수는, Direct3D 보관 유지 모드 및 DirectDrawClipper 오브젝트등이 주요한 오브젝트를 추적한다. DirectDrawClipper 오브젝트는, 드로잉(Drawing)을 지정한 영역에 제한한다. myglobs 구조체는, 디바이스, 윈도우 디바이스, 뷰포트, 장면,카메라에 관한 정보에 가세해, 어플리케이션의 최소화나 오브젝트의 초기화에 관한 정보도 수집한다. RMBegin2에서는, RMBegin1로 사용하고 있던 오브젝트에 Direct3D 보관 유지 모드의 윈도우 디바이스를 추가하고 있는 것에 주의한다.

// 글로벌 변수
LPDIRECT3DRM lpD3DRM = NULL;            // Direct3D 보관 유지 모드브제크트
LPDIRECTDRAWCLIPPER lpDDClipper = NULL; // DirectDrawClipper 오브젝트

// 글로벌 구조체
struct _myglobs {

    // Direct3D 보관 유지 모드 디바이스
    LPDIRECT3DRMDEVICE dev;

    // Direct3D 보관 유지 모드 윈도우 디바이스
    LPDIRECT3DRMWINDEVICE windevice;

    // 장면을 표시하는 Direct3D 보관 유지 모드 뷰포트
    LPDIRECT3DRMVIEWPORT view;

    // 다른 프레임을 배치하는 마스터 프레임
    LPDIRECT3DRMFRAME scene;

    // 유저의 시점을 기술하는 프레임
    LPDIRECT3DRMFRAME camera;

    // 어플리케이션은 최소화되고 있다.
    BOOL bMinimized;

    // Direct3D 보관 유지 모드의 전오브젝트가 초기화되고 있다.
    BOOL bInitialized;

} myglobs;

함수 개요

RMBegin2.cpp에는, 이하의 함수가 포함되어 있다.

BuildScene 함수는, 렌더링 하는 장면을 생성 한다. DirectX 파일로부터 메쉬를 로드해, 메쉬를 스케일링 해, 색을 메쉬에 추가해, 프레임의 계층을 생성 해, 장면에 조명을 추가한다. 게다가BuildScene는, 오브젝트의 위치와 회전의 방법을 설정한다. 글로벌 변수를 초기화해, 디폴트의 디바이스, 프레임, 뷰포트를 생성 하는CreateObjects가, 이 함수를 사용한다. 기본적으로는, RMBegin1의BuildScene함수를 닮아 있지만, RMBegin2의BuildScene함수는, 보다 복잡한 장면을 생성 한다.

BOOL BuildScene(LPDIRECT3DRM, LPDIRECT3DRMDEVICE,
                LPDIRECT3DRMFRAME, LPDIRECT3DRMFRAME);

RenderScene 함수는,BuildScene가 생성 한 장면을 드로잉(Drawing) 한다. WinMain가 이 함수를 사용할 때마다,RenderScene는 장면을 이동해, 오브젝트에 회전 효과를 준다. 이 함수는, RMBegin1 샘플의RenderScene함수와 같다.

static BOOL RenderScene(void);

CreateObjects 함수는, 글로벌 변수를 초기화해, 디폴트의 디바이스, 윈도우 디바이스, 카메라 프레임, 장면 프레임, 뷰포트를 생성 한다. CreateObjects는BuildScene를 사용해, 렌더링 하는 장면을 생성 한다. 어플리케이션의 윈도우를 생성 하는InitApp가,CreateObjects를 사용한다. 이 함수는, 윈도우 디바이스를 생성 하는 점을 제외하면, RMBegin1 샘플의CreateObjects함수와 같다.

BOOL CreateObjects(HWND win);

InitApp 함수는, Windows 어플리케이션의 표준적인 코드에 의해, 윈도우 클래스와 어플리케이션의 윈도우를 생성 한다. InitApp는,CreateObjects를 사용해, 글로벌 오브젝트를 초기화한다. 이 함수는, 윈도우 캡션이 다른 것을 제외하면, RMBegin1 샘플의InitApp함수와 같다.

static HWND InitApp(HINSTANCE, int);

WinMain 함수는, 어플리케이션의 메시지 루프를 제공한다. InitApp를 사용해 어플리케이션을 초기화해,RenderScene를 사용해 장면을 드로잉(Drawing) 한다. 이 함수는, RMBegin1 샘플의WinMain함수와 같다.

int APIENTRY WinMain(HINSTANCE, HINSTANCE, LPSTR, int);

WindowProc 함수는, 어플리케이션의 메세지를 처리한다. 어플리케이션의 최소화, 사이즈 변경, 액티브화, 드로잉(Drawing), 파기를 처리한다.

LRESULT CALLBACK WindowProc(HWND, UINT, WPARAM, LPARAM);

이상의 함수의 상세한 것에 대하여는, 이 항의 다음의 항목을 참조할것.

  • BuildScene
  • RenderScene
  • CreateObjects
  • InitApp
  • WinMain
  • WindowProc

BuildScene

BuildScene함수는, 렌더링 하는 장면을 생성 한다. Direct3D 보관 유지 모드의 모든 어플리케이션은 장면을 생성 할 필요가 있지만, 필요한 코드는 장면에 의존한다. 어플리케이션은 보통, 프레임과 조명을 생성 해, 시각적인 요소를 장면에 추가해, 오브젝트의 위치를 설정한다. 이 함수는, 게다가 오브젝트를 스케일링 해, 프레임 계층을 설정한다.

이 마디에서는,BuildScene함수의 코드를 부분적으로 나타내, RMBegin2 샘플이 태양, 지구, 달의 장면을 구축하는 순서에 대해 설명한다. 게다가 RMBegin2 샘플의BuildScene함수에 관한 모든 소스 코드도 가리킨다. 에러가 발생했을 경우는,goto문으로 함수의 마지막에 점프 해, 함수로부터 돌아가기 전에, 모든 오브젝트를 적절히 릴리즈 한다.

  1. IDirect3DRM3::CreateMeshBuilder 와IDirect3DRMMeshBuilder3::Load 메소드를 사용해, DirectX 파일로부터 메쉬를 로드한다. 다음의 코드는, 1개의 메쉬를 로드하고 있다. 샘플에서는, 같은 처리를 사용해, 다른 메쉬도 로드하고 있다.
        if (FAILED(lpD3DRM->CreateMeshBuilder(&sun_builder)))
        goto generic_error;

    rval = sun_builder->Load("sphere2.x", NULL,
                    D3DRMLOAD_FROMFILE, NULL, NULL);
    if (FAILED(rval)) {
        DISPLAYMSG("Failed to load sun . x file. ");
        goto ret_with_error;
    }
  2. 메쉬를 스케일링 해 색을 추가한다. 샘플이 로드하는 3개의 구(공)체는, 거의 같은 크기이므로, 태양을 확대해, 지구와 달을 축소한다. 다음의 코드는, 1개의 메쉬에 대해서, 이 처리를 실시하고 있다.
        if (FAILED(sun_builder->Scale(D3DVAL(1.2), D3DVAL(1.2),
                                  D3DVAL(1.2))))
        goto generic_error;
    if (FAILED(sun_builder->SetColorRGB(D3DVAL(1.0), D3DVAL(1.0),
                                        D3DVAL(0.0))))
        goto generic_error;
  3. IDirect3DRM3::CreateFrame 메소드를 사용해, 장면의 프레임 계층을 생성 한다. 다음의 코드에서는, 마스터 신 프레임에 태양의 프레임, 태양의 프레임에 지구의 프레임, 지구의 프레임에 달의 프레임을 생성 하고 있다. 오브젝트의 회전을 설정 하면 와, 이 프레임 계층은, 어느 오브젝트의 회전을, 어느 오브젝트가 공전하는지를 관리한다.
        if (FAILED(lpD3DRM->CreateFrame(scene, &sun)))
        goto generic_error;
    if (FAILED(lpD3DRM->CreateFrame(sun, &planet)))
        goto generic_error;
    if (FAILED(lpD3DRM->CreateFrame(planet, &moon)))
        goto generic_error;
  4. IDirect3DRMMeshBuilder3::CreateMesh 를 사용해, 메쉬 빌더 오브젝트를 메쉬로 변환한다. 다음의 코드는 태양의 메쉬를 생성 한다.
        if (FAILED(sun_builder->CreateMesh(&sun_mesh)))
        goto generic_error;
  5. IDirect3DRMFrame3::AddVisual 메소드를 사용해, 로드한 메쉬를 적절한 아이 프레임에 추가한다. 다음의 코드는, 태양의 메쉬를 태양의 프레임에 추가한다.
        if (FAILED(sun->AddVisual((LPDIRECT3DRMVISUAL) sun_mesh)))
        goto generic_error;
  6. IDirect3DRMFrame3::SetPosition 메소드를 사용해, 장면에 카메라 위치를 설정한다. 다른 오브젝트의 위치도 설정한다. 다음의 코드는 카메라와 태양의 위치를 설정한다. 태양의 위치와 카메라 위치의 x좌표와 y좌표가 ,함께(0,0)이기 (위해)때문에, 태양은 카메라의 정면의 직선상에 표시된다.
        if (FAILED(camera->SetPosition(scene, D3DVAL(0), D3DVAL(0),
                                   -D3DVAL(25))))
        goto generic_error;
    if (FAILED(sun->SetPosition(scene, D3DVAL(0), D3DVAL(0),
                                D3DVAL(0))))
        goto generic_error;
  7. IDirect3DRMFrame3::SetRotation 메소드를 사용해, 프레임의 회전을 설정한다. 다음의 코드는, 태양의 회전을 설정한다.
        if (FAILED(sun->SetRotation(scene, D3DVAL(0), D3DVAL(0),
                                D3DVAL(1),
                                D3DVAL(0.01))))
  8. IDirect3DRM3::CreateFrame 메소드를 사용해, 장면의 아이 프레임이 되는 조명 프레임을 생성 한다. IDirect3DRMFrame3::SetPosition 메소드를 사용해, 장면에 조명 프레임을 배치한다. IDirect3DRM3::CreateLightRGB 와IDirect3DRMFrame3::AddLight 메소드를 사용해, 밝은 포인트 조명을 생성 해, 조명 프레임에 추가한다.
        if (FAILED(lpD3DRM->CreateFrame(scene, &lights)))
        goto generic_error;
    if (FAILED(lights->SetPosition(scene, D3DVAL(0), D3DVAL(0),
                                -D3DVAL(7))))
        goto generic_error;
    if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_POINT, D3DVAL(0.9),
                                  D3DVAL(0.8), D3DVAL(0.7), &light1)))
        goto generic_error;
    if (FAILED(lights->AddLight(light1)))
        goto generic_error;
  9. IDirect3DRM3::CreateLightRGB 와IDirect3DRMFrame3::AddLight 메소드를 한번 더 사용해, 어두운앰비언트조명을 생성 해, 장면에 추가한다.
        if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_AMBIENT, D3DVAL(0.1),
                                  D3DVAL(0.1), D3DVAL(0.1), &light2)))
        goto generic_error;
    if (FAILED(scene->AddLight(light2)))
        goto generic_error;
  10. 앰비언트 조명의 생성과 같은 메소드를 사용해, 밝은패러럴 포인트조명을 생성 해, 조명 프레임에 추가한다.
        if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_PARALLELPOINT,
                                  D3DVAL(0.9), D3DVAL(0.9), D3DVAL(0.9),
                                  &light3)))
        goto generic_error;
    if (FAILED(sun->AddLight(light3)))
        goto generic_error;
  11. 이 함수로 생성 한 모든 오브젝트를 릴리즈 해 종료한다.
        RELEASE(sun_builder);
    RELEASE(planet_builder);
    RELEASE(moon_builder);
    RELEASE(sun_mesh);
    RELEASE(planet_mesh);
    RELEASE(moon_mesh);
    RELEASE(sun);
    RELEASE(planet);
    RELEASE(moon);
    RELEASE(lights);
    RELEASE(light1);
    RELEASE(light2);
    RELEASE(light3);

BuildScene함수 소스 코드

// 렌더링 하는 장면을 생성 한다.

BOOL BuildScene(LPDIRECT3DRM lpD3DRM,
                LPDIRECT3DRMDEVICE dev,
                LPDIRECT3DRMFRAME scene,
                LPDIRECT3DRMFRAME camera)
{
    LPDIRECT3DRMMESHBUILDER sun_builder = NULL;
    LPDIRECT3DRMMESHBUILDER planet_builder = NULL;
    LPDIRECT3DRMMESHBUILDER moon_builder = NULL;
    LPDIRECT3DRMMESH sun_mesh = NULL;
    LPDIRECT3DRMMESH planet_mesh = NULL;
    LPDIRECT3DRMMESH moon_mesh = NULL;
    LPDIRECT3DRMFRAME sun = NULL;
    LPDIRECT3DRMFRAME planet = NULL;
    LPDIRECT3DRMFRAME moon = NULL;
    LPDIRECT3DRMLIGHT light1 = NULL;
    LPDIRECT3DRMLIGHT light2 = NULL;
    LPDIRECT3DRMLIGHT light3 = NULL;
    LPDIRECT3DRMFRAME lights = NULL;
    HRESULT rval;

    // 로드하는 DirectX 파일 (태양, 지구, 달) 마다, 메쉬 빌더를
    // 생성 해, 메쉬를 로드한다.
    if (FAILED(lpD3DRM->CreateMeshBuilder(&sun_builder)))
        goto generic_error;
    if (FAILED(lpD3DRM->CreateMeshBuilder(&planet_builder)))
        goto generic_error;
    if (FAILED(lpD3DRM->CreateMeshBuilder(&moon_builder)))
        goto generic_error;

    rval = sun_builder->Load("sphere2.x", NULL,
                    D3DRMLOAD_FROMFILE, NULL, NULL);
    if (FAILED(rval)) {
        DISPLAYMSG("Failed to load sun . x file. ");
        goto ret_with_error;
    }

    rval = planet_builder->Load("sphere1.x", NULL,
                    D3DRMLOAD_FROMFILE, NULL, NULL);
    if (FAILED(rval)) {
        DISPLAYMSG("Failed to load planet . x file. ");
    goto ret_with_error;
    }

    rval = moon_builder->Load("sphere0.x", NULL,
                    D3DRMLOAD_FROMFILE, NULL, NULL);
    if (FAILED(rval)) {
        DISPLAYMSG("Failed to load moon . x file. ");
        goto ret_with_error;
    }

    // 태양, 지구, 달의 메쉬의 사이즈를 조정한다.
    // x 축, y 축, z 축으로 같은 크기로 스케일링 해, 메쉬의 구(공)체를 유지한다.
    // 태양의 사이즈는 늘려,
    // 지구와 달의 사이즈는 줄여,
    // 적절한 상대적인 크기를 얻는다.
    if (FAILED(sun_builder->Scale(D3DVAL(1.2), D3DVAL(1.2),
                                  D3DVAL(1.2))))
        goto generic_error;
    if (FAILED(planet_builder->Scale(D3DVAL(0.5), D3DVAL(0.5),
                                     D3DVAL(0.5))))
        goto generic_error;
    if (FAILED(moon_builder->Scale(D3DVAL(0.2), D3DVAL(0.2),
                                   D3DVAL(0.2))))
        goto generic_error;

    // 태양, 지구, 달의 메쉬의 색을 조정한다.
    // 태양은 황색, 지구는 초록이 산 청색,
    // 달은 적색으로 설정한다.
    if (FAILED(sun_builder->SetColorRGB(D3DVAL(1.0), D3DVAL(1.0),
                                        D3DVAL(0.0))))
        goto generic_error;
    if (FAILED(planet_builder->SetColorRGB(D3DVAL(0.2), D3DVAL(1.0),
                                           D3DVAL(0.8))))
        goto generic_error;
    if (FAILED(moon_builder->SetColorRGB(D3DVAL(0.7), D3DVAL(0.2),
                                         D3DVAL(0.3))))
        goto generic_error;

    // 프레임의 계층을 생성 한다.
    // - 마스터 신 프레임에 태양의 프레임,
    // - 태양의 프레임에 지구의 프레임,
    // - 지구의 프레임에 달의 프레임을 생성 한다.
    if (FAILED(lpD3DRM->CreateFrame(scene, &sun)))
        goto generic_error;
    if (FAILED(lpD3DRM->CreateFrame(sun, &planet)))
        goto generic_error;
    if (FAILED(lpD3DRM->CreateFrame(planet, &moon)))
        goto generic_error;

    // 메쉬 빌더로부터 메쉬를 생성 해, Direct3D 보관 유지 모드가 같은 변환을
    // 반복하는 것을 피한다. 메쉬 빌더는 여기서 릴리즈 할 수도 있지만,
    // 코드를 알기 쉽게 하기 위해서, 이 함수의 최후로,
    // 다른 오브젝트와 함께 릴리즈 한다.
    if (FAILED(sun_builder->CreateMesh(&sun_mesh)))
        goto generic_error;
    if (FAILED(planet_builder->CreateMesh(&planet_mesh)))
        goto generic_error;
    if (FAILED(moon_builder->CreateMesh(&moon_mesh)))
        goto generic_error;

    // 메쉬를 프레임에 추가한다.
    if (FAILED(sun->AddVisual((LPDIRECT3DRMVISUAL) sun_mesh)))
        goto generic_error;
    if (FAILED(planet->AddVisual((LPDIRECT3DRMVISUAL) planet_mesh)))
        goto generic_error;
    if (FAILED(moon->AddVisual((LPDIRECT3DRMVISUAL) moon_mesh)))
        goto generic_error;

    // 프레임의 위치를 설정한다.
    if (FAILED(camera->SetPosition(scene, D3DVAL(0), D3DVAL(0),
                                   -D3DVAL(25))))
        goto generic_error;
    if (FAILED(sun->SetPosition(scene, D3DVAL(0), D3DVAL(0),
                                D3DVAL(0))))
        goto generic_error;
    if (FAILED(planet->SetPosition(sun, D3DVAL(7), D3DVAL(0),
                                   D3DVAL(0))))
        goto generic_error;
    if (FAILED(moon->SetPosition(planet, D3DVAL(0), D3DVAL(3),
                                 D3DVAL(0))))
        goto generic_error;

    // 프레임의 회전을 설정한다.
    if (FAILED(sun->SetRotation(scene, D3DVAL(0), D3DVAL(0),
                                D3DVAL(1),
                                D3DVAL(0.01))))
        goto generic_error;
    if (FAILED(planet->SetRotation(sun, D3DVAL(1), D3DVAL(0),
                                   D3DVAL(0),
                                   D3DVAL(0.02))))
        goto generic_error;
    if (FAILED(moon->SetRotation(planet, D3DVAL(0.1), D3DVAL(0.2),
                               D3DVAL(0.7),
                               D3DVAL(0.03))))
       goto generic_error;

    // 장면의 조명을 초기화한다.
    // - 조명 프레임을 생성 해, 장면에 배치하는 위치를 설정한다
    //   (태양의 정면의 직선상에 두어, 태양을 비춘다).
    //   포인트 조명을 조명 프레임에 Attach 한다.
    // - 소프트인 앰비언트 조명을 생성 해, 장면에 추가한다.
    // - 밝은 패러럴 포인트 조명을 생성 해, 태양의 프레임에
    //   추가한다. 지구와 달이 태양의 회전을 공전할 때,
    //   적절히 비추도록(듯이) 한다.

    // 태양의 정면으로 포인트 조명을 생성 한다.
    if (FAILED(lpD3DRM->CreateFrame(scene, &lights)))
        goto generic_error;
    if (FAILED(lights->SetPosition(scene, D3DVAL(0), D3DVAL(0),
                                -D3DVAL(7))))
        goto generic_error;
    if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_POINT, D3DVAL(0.9),
                                  D3DVAL(0.8), D3DVAL(0.7), &light1)))
        goto generic_error;
    if (FAILED(lights->AddLight(light1)))
        goto generic_error;

    // 앰비언트 조명을 생성 해, 장면에 추가한다.
    if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_AMBIENT, D3DVAL(0.1),
                                  D3DVAL(0.1), D3DVAL(0.1), &light2)))
        goto generic_error;
    if (FAILED(scene->AddLight(light2)))
        goto generic_error;

    // 패러럴 포인트 조명을 생성 해, 태양의 프레임에 추가한다.
    if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_PARALLELPOINT,
                                  D3DVAL(0.9), D3DVAL(0.9), D3DVAL(0.9),
                                  &light3)))
        goto generic_error;
    if (FAILED(sun->AddLight(light3)))
        goto generic_error;

    // 종료 처리
    RELEASE(sun_builder);
    RELEASE(planet_builder);
    RELEASE(moon_builder);
    RELEASE(sun_mesh);
    RELEASE(planet_mesh);
    RELEASE(moon_mesh);
    RELEASE(sun);
    RELEASE(planet);
    RELEASE(moon);
    RELEASE(lights);
    RELEASE(light1);
    RELEASE(light2);
    RELEASE(light3);
    return TRUE;

generic_error:
    DISPLAYMSG("A failure occurred while building the scene. ");
ret_with_error:
    RELEASE(sun_builder);
    RELEASE(planet_builder);
    RELEASE(moon_builder);
    RELEASE(sun_mesh);
    RELEASE(planet_mesh);
    RELEASE(moon_mesh);
    RELEASE(sun);
    RELEASE(planet);
    RELEASE(moon);
    RELEASE(lights);
    RELEASE(light1);
    RELEASE(light2);
    RELEASE(light3);
    return FALSE;
}

RenderScene

RenderScene함수는, 실제로 장면을 스크린에 드로잉(Drawing) 한다. BuildScene가 생성 한 장면을 다음의 순서에 따라 드로잉(Drawing) 한다.

  1. IDirect3DRMFrame3::Move 를 사용해, 장면을 이동한다.
  2. IDirect3DRMViewport2::Clear 를 사용해, 뷰포트를 클리어 한다.
  3. IDirect3DRMViewport2::Render 를 사용해, 장면을 렌더링 한다.
  4. IDirect3DRMDevice3::Update 를 사용해, 윈도우를 갱신한다.

RenderScene함수 소스 코드

// 뷰포트를 클리어 해, 다음의 프레임을 렌더링 해, 윈도우를 갱신한다.

static BOOL RenderScene()
{
    HRESULT rval;

    // 장면의 이동.
    rval = myglobs.scene->Move(D3DVAL(1.0));
    if (FAILED(rval))
    {
        DISPLAYMSG("Moving scene failed. ");
        return FALSE;
    }

    // 뷰포트의 클리어.
    rval = myglobs.view->Clear();
    if (FAILED(rval))
    {
        DISPLAYMSG("Clearing viewport failed. ");
        return FALSE;
    }

    // 장면을 뷰포트에 렌더링 한다.
    rval = myglobs.view->Render(myglobs.scene);
    if (FAILED(rval))
    {
        DISPLAYMSG("Rendering scene failed. ");
        return FALSE;
    }

    // 윈도우의 갱신.
    rval = myglobs.dev->Update();
    if (FAILED(rval))
    {
        DISPLAYMSG("Updating device failed. ");
        return FALSE;
    }
    return TRUE;
}

CreateObjects

CreateObjects는, 샘플의 글로벌 변수를 초기화해, 오브젝트를 생성 한다. 글로벌 변수를 초기화한 후, 디바이스의 생성에 필요한 순서를 실행해, 디바이스를 어플리케이션의 메인 윈도우에 관련지어 마스터 신 프레임, 카메라 프레임, 뷰포트를 생성 한다. 이하의 순서에 따른다.

  1. DirectDraw의DirectDrawCreateClipper함수를 사용해, DirectDrawClipper 오브젝트를 생성 한다.
  2. DirectDrawClipper 오브젝트의SetHWnd메소드를 사용해, 어플리케이션의 윈도우를 DirectDrawClipper에 관련짓는다. DirectDrawClipper 오브젝트는, 후속의 드로잉(Drawing)를, 지정한 영역 (여기에서는 어플리케이션의 윈도우)에 제한한다.
  3. Direct3DRMCreate 함수를 사용해, Direct3D 보관 유지 모드 오브젝트를 생성 한다.
  4. Windows의GetClientRect함수를 사용해, 어플리케이션의 메인 윈도우의 높이와 폭을 취득한다.
  5. Direct3D 보관 유지 모드 오브젝트의CreateDeviceFromClipper 메소드를 사용해 디바이스를 생성 해, NULL를 건네주어 디폴트 디바이스를 생성 한다. 게다가 어플리케이션의 윈도우의 폭과 높이를 메소드에 건네준다.
  6. IDirect3DRMWinDevice 인터페이스를 지원 하는 디바이스를 문의해, Direct3D 보관 유지 모드의 윈도우 디바이스를 생성 한다. 윈도우 디바이스는, WM_ACTIVATE 메세지와 WM_PAINT 메세지를 처리한다.
  7. IDirect3DRM3::CreateFrame 를 사용해, 마스터 신 프레임을 생성 한다.
  8. IDirect3DRM3::CreateFrame 를 사용해, 카메라 프레임을 생성 한다.
  9. IDirect3DRM3::CreateViewport 를 사용해, Direct3D 보관 유지 모드의 뷰포트를 생성 한다.
  10. BuildScene 를 사용해, 장면을 생성 한다.

CreateObjects함수 소스 코드

// 글로벌 변수를 초기화해, 디바이스와 오브젝트를 생성 한다.

BOOL CreateObjects(HWND win)
{
    HRESULT rval; // 반환값
    RECT rc;      // 메인 윈도우의 직사각형의 경계
    int width;    // 디바이스의 폭
    int height;   // 디바이스의 높이

    // 글로벌 변수 구조체의 전체를 제로에 초기화한다.
    memset(&myglobs, 0, sizeof(myglobs));

    // DirectDrawClipper 오브젝트를 생성 해, 윈도우를 관련짓는다.
    rval = DirectDrawCreateClipper(0, &lpDDClipper, NULL);
    if (FAILED(rval)) {
        DISPLAYMSG("Failed to create DirectDrawClipper object. ");
        return FALSE;
    }
    rval = lpDDClipper->SetHWnd(0, win);
    if (FAILED(rval)) {
        DISPLAYMSG("Failed to set the window handle for the DirectDrawClipper. ");
        return FALSE;
    }

    // Direct3D 보관 유지 모드 오브젝트를 생성 한다.
    rval = Direct3DRMCreate(&lpD3DRM);
    if (FAILED(rval)) {
        DISPLAYMSG("Failed to create Direct3DRM. ");
        return FALSE;
    }

    // Direct3D 보관 유지 모드의 디폴트 디바이스를 생성 한다.
    GetClientRect(win, &rc);

    rval = lpD3DRM->CreateDeviceFromClipper(lpDDClipper,
                           NULL, // Default device
                           rc.right, rc.bottom, &myglobs.dev);

    if (FAILED(rval)) {
        DISPLAYMSG("Failed to create the D3DRM device. ");
        return FALSE;
    }

    // WM_ACTIVATE와 WM_PAINT 메세지를 처리하기 위해(때문에),
    // Direct3D 보관 유지 모드의 윈도우 디바이스를 생성 한다.
    rval = myglobs.dev->QueryInterface(IID_IDirect3DRMWinDevice,
                                       (void **) &myglobs.windevice);
    if (FAILED(rval)) {
        DISPLAYMSG("Failed to create the window device. ");
        return FALSE;
    }

    // 마스터 신 프레임과 카메라 프레임을 생성 한다.
    rval = lpD3DRM->CreateFrame(NULL, &myglobs.scene);
    if (FAILED(rval)) {
        DISPLAYMSG("Failed to create the master scene frame. ");
        return FALSE;
    }

    rval = lpD3DRM->CreateFrame(myglobs.scene, &myglobs.camera);
    if (FAILED(rval)) {
        DISPLAYMSG("Failed to create the camera's frame. ");
        return FALSE;
    }

    // 디바이스, 카메라 프레임, 디바이스의 폭과 높이를 사용해,
    // Direct3D 보관 유지 모드의 뷰포트를 생성 한다.
    width = myglobs.dev->GetWidth();
    height = myglobs.dev->GetHeight();

    rval = lpD3DRM->CreateViewport(myglobs.dev, myglobs.camera, 0, 0,
                                   width, height, &myglobs.view);
    if (FAILED(rval)) {
        myglobs.bInitialized = FALSE;
        RELEASE(myglobs.dev);
        return FALSE;
    }

    // 렌더링 하는 장면을 생성 한다.
    if (! BuildScene(lpD3DRM, myglobs.dev, myglobs.scene,
                    myglobs.camera))
        return FALSE;

    // 글로벌 변수는 초기화되었다.
    myglobs.bInitialized = TRUE;

    return TRUE;
}

InitApp

InitApp함수는, 메인 윈도우 클래스와 메인 윈도우를 생성 한다. 이것은, Windows 어플리케이션에서는 일반적인 처리이다. InitApp 로부터 불려 가는 Direct3D 보관 유지 모드는,CreateObjects 의 호출 뿐이다.

InitApp함수 소스 코드

// 메인 윈도우를 생성 해, 오브젝트를 초기화한다.

static HWND InitApp(HINSTANCE this_inst, int cmdshow)
{
    HWND win;     // 메인 윈도우 핸들
    WNDCLASS wc;

    // 윈도우 클래스를 설정해 등록한다.
    wc.style = CS_HREDRAW | CS_VREDRAW;
    wc.lpfnWndProc = WindowProc;
    wc.cbClsExtra = 0;
    wc.cbWndExtra = sizeof(DWORD);
    wc.hInstance = this_inst;
    wc.hIcon = LoadIcon(NULL, IDI_APPLICATION);
    wc.hCursor = LoadCursor(NULL, IDC_ARROW);
    wc.hbrBackground = (HBRUSH) GetStockObject(BLACK_BRUSH);
    wc.lpszMenuName = NULL;
    wc.lpszClassName = "D3DRM Example";
    if (! RegisterClass(&wc))
        return FALSE;

    // 윈도우의 생성.
    win = CreateWindow(
            "D3DRM Example",                   // 클래스
            "RMBegin2: Direct3DRM Sample Two", // 캡션
            WS_OVERLAPPEDWINDOW,               // 스타일
            CW_USEDEFAULT,                     // init.  x pos
            CW_USEDEFAULT,                     // init.  y pos
            350,                               // init.  x size
            300,                               // init.  y size
            NULL,                              // 부모 윈도우
            NULL,                              // 메뉴 핸들
            this_inst,                         // 프로그램 핸들
            NULL                               // 생성 파라미터
        );
    if (! win)
        return FALSE;

    // 글로벌 변수를 초기화해, 디바이스를 열거해,
    // Direct3D 보관 유지 모드 오브젝트를 생성 한다.
    if (! CreateObjects(win))
        return FALSE;

    // 윈도우의 표시.
    ShowWindow(win, cmdshow);
    UpdateWindow(win);

    return win;
}

WinMain

WinMain함수는, 어플리케이션에 메시지 루프를 제공한다. 글로벌 변수가 초기화되고 있어, 어플리케이션이 최소화되어 있지 않으면, WinMain는RenderScene 를 사용해 장면을 스크린에 드로잉(Drawing) 한다.

WinMain함수 소스 코드

// 어플리케이션을 초기화해, 메세지를 처리해, 장면을 렌더링 한다.
int APIENTRY WinMain (HINSTANCE this_inst,
                      HINSTANCE prev_inst,
                      LPSTR cmdline,
                      int cmdshow)
{
    HWND    hwnd;
    MSG     msg;
    prev_inst;
    cmdline;

    // 윈도우를 생성 해, 오브젝트를 초기화한다.
    if (! (hwnd = InitApp(this_inst, cmdshow)))
        return 1;

    while (TRUE) {
        // 메시지 큐를 감시해, 메세지를 처리한다. PeekMessage는
        // 제어를 즉석에서 어플리케이션에 돌려주므로, 어플리케이션은
        // 메세지의 처리와 렌더링을 계속할 수 있다.
        // 메세지가 WM_QUIT이면, 어플리케이션이 종료하고 있기 (위해)때문에,
        // 이 함수를 빠진다.
        if (PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)) {

            if (msg.message == WM_QUIT)
                break;
            TranslateMessage(&msg);
            DispatchMessage(&msg);
        }

        // 어플리케이션이 최소화되지 않고, Direct3D 보관 유지 모드
        // 오브젝트가 초기화되고 있으면, 렌더링을 실시한다.
        if (! myglobs.bMinimized && myglobs.bInitialized) {

            // 장면을 1 프레임, 렌더링 한다. 렌더링이 실패하면(자),
            // WM_DESTROY 메세지를 발행한다. 이것에 의해, 어플리케이션이
            // 종료하기 전에, 리소스를 릴리즈 할 수 있다.
            if (! RenderScene()) {
                DISPLAYMSG("Rendering failed.  Aborting execution. ");
                PostMessage(NULL, WM_DESTROY, 0, 0);
                break;
            }

        // 이 어플리케이션이 현재 렌더링을 하고 있지 않으면,
        // 다른 어플리케이션에 제어를 건네준다.
        } else
              WaitMessage();

    }
    return msg.wParam;
}

WindowProc

WindowProc는, 어플리케이션의 메인 윈도우의 메세지를 처리한다. 플래그를 세트 해, 어플리케이션이 최소화되고 있을 때는 렌더링을 정지시킨다. 게다가 이 함수는, 어플리케이션 윈도우의 사이즈 변경, 윈도우의 액티브화, 드로잉(Drawing), 어플리케이션이 슛다운 했을 때의 오브젝트 릴리즈를 실시한다.

유저가 어플리케이션 윈도우의 사이즈를 변경 하면, RMBegin2 샘플은 장면의 사이즈를 증감하는 것으로, 윈도우의 화면을 계속해 표시시킨다. 이 함수는, 이하의 순서에 따라, WM_SIZE 메세지(윈도우의 사이즈 변경)를 처리한다.

  • 어플리케이션이 최소화되고 있는 경우, 사이즈를 변경할 필요가 없기 때문에, 최소화 플래그를 세트 해, 함수로부터 빠진다.
  • 현재의 윈도우, 뷰포트, 디바이스의 폭과 높이를 취득한다.
  • 어플리케이션 윈도우가 현재의 디바이스보다 크게 변경되었을 경우, 전의 뷰포트, 디바이스, 윈도우 디바이스를 파기해, 새롭게 생성 한다. 어플리케이션 윈도우가 현재의 디바이스보다 작게 변경되었을 경우는, 뷰포트만을 생성 다시 한다.

WindowProc는,IDirect3DRMWinDevice::HandleActivate 메소드를 사용해 WM_ACTIVATE 메세지를,IDirect3DRMWinDevice::HandlePaint 메소드를 사용해 WM_PAINT 메세지를 처리한다.

WindowProc함수 소스 코드

// 메인 윈도우의 메세지를 처리한다.

LRESULT CALLBACK WindowProc(HWND win,
                            UINT msg,
                            WPARAM wparam,
                            LPARAM lparam)
{
HRESULT rval;

switch (msg) {

    case WM_SIZE:
        // 윈도우의 사이즈 변경을 처리한다. 어플리케이션이 최소화되어
        // 있으면, 플래그를 세트 해, 최소화시의 렌더링을 정지해,
        // 함수로부터 빠진다. 그 이외의 경우는, 최소화 플래그가
        // 클리어 되고 있는 것을 확인해, 최소화 이외의
        // 윈도우 사이즈의 변경을 위한 검사를 실시한다.
        {
        if (SIZE_MINIMIZED == wparam)
        {
            myglobs.bMinimized = TRUE;
            break;
        }
        else
            myglobs.bMinimized = FALSE;

        // 윈도우 사이즈의 변경을 처리한다. 윈도우의 현재의 폭과 높이를
        // 취득한다.
        int width = LOWORD(lparam);
        int height = HIWORD(lparam);

        // 뷰포트나 디바이스등의 글로벌 변수가 초기화되고 있으면,
        // 뷰포트와 디바이스의 폭과 높이를 취득한다.
        // 필요에 따라서, 새로운 디바이스와 윈도우 디바이스, 또는 뷰포트
        // (을)를 생성 한다. 새로운 디바이스와 윈도우 디바이스는,
        // 윈도우가 전의 디바이스보다 큰 경우에만 필요하게 된다.
        if (myglobs.bInitialized)
        {
            int view_width = myglobs.view->GetWidth();
            int view_height = myglobs.view->GetHeight();
            int dev_width = myglobs.dev->GetWidth();
            int dev_height = myglobs.dev->GetHeight();

            // 윈도우 사이즈의 폭 또는 높이가 증가하고 있을까 조사한다.
            if (width > dev_width || height > dev_height)
            {
                // 어플리케이션 윈도우는 현재의 디바이스보다 커지고 있다.
                // 전의 뷰포트와 디바이스를 파기해, 새롭게 생성 한다.
                // 디바이스를 릴리즈 하기 전에, 뷰포트를 릴리즈 하는 것.
                // 이 순서를 잘못하면(자), 일반보호위반이 발생한다.
                myglobs.bInitialized = FALSE;
                RELEASE(myglobs.view);
                RELEASE(myglobs.dev);

                // 디폴트의 Direct3D 보관 유지 모드 디바이스를 신규 생성 한다.
                rval = lpD3DRM->CreateDeviceFromClipper(lpDDClipper,
                                        NULL, // Default device
                                        width, height,
                                        &myglobs.dev);

                if (FAILED(rval))
                {
                    // 새로운 디바이스가 생성 할 수 없는 경우, 유저에게 통지해,
                    // 어플리케이션을 슛다운 한다.
                    DISPLAYMSG("Failed to create the D3DRM device. ");
                    PostMessage(NULL, WM_DESTROY, 0, 0);
                    return FALSE;
                }

                // 전의 Direct3D 보관 유지 모드 윈도우 디바이스를 파기해,
                // 신규 생성 한 디바이스와 일치하는 새로운 윈드우데바이
                // 스를 생성 한다. 윈도우 디바이스는, WM_ACTIVATE와
                // WM_PAINT 메세지를 처리한다.
                RELEASE(myglobs.windevice);
                rval = myglobs.dev->QueryInterface(
                                       IID_IDirect3DRMWinDevice,
                                       (void **) &myglobs.windevice);
                if (FAILED(rval)) {
                    DISPLAYMSG("Failed to create the window device. ");
                    return FALSE;
                }

            }

            // 윈도우의 사이즈가 변경되고 있으면, 전의 뷰포트를
            // 릴리즈 해, 새로운 뷰포트를 적절한 사이즈로 생성 한다.
            myglobs.bInitialized = FALSE;
            RELEASE(myglobs.view);
            rval = lpD3DRM->CreateViewport(myglobs.dev,
                                           myglobs.camera,
                                           0, 0, width, height,
                                           &myglobs.view);
            if (FAILED(rval))
            {
                // 새로운 뷰포트가 생성 할 수 없는 경우, 유저에게 통지해,
                // 어플리케이션을 슛다운 한다.
                DISPLAYMSG("Failed to create a new viewport. ");
                PostMessage(NULL, WM_DESTROY, 0, 0);
                break;
            }

            myglobs.bInitialized = TRUE;
        }
        }
        break;

    case WM_ACTIVATE:
        // 윈도우 디바이스의 HandleActivate 메소드를 사용해,
        // 윈도우의 액티브화를 처리한다.
        if (myglobs.bInitialized)
            if (FAILED(myglobs.windevice->HandleActivate(wparam)))
                DISPLAYMSG("Failed to handle WM_ACTIVATE. ");
        break;

    case WM_PAINT:
        // 글로벌 변수가 초기화되고 있으면,
        // 윈도우 디바이스의 HandlePaint 메소드를 사용해,
        // 재드로잉(Drawing)를 처리한다.
        if (! myglobs.bInitialized)
            return DefWindowProc(win, msg, wparam, lparam);

        // 윈도우 디바이스를 사용해, 재드로잉(Drawing)를 처리한다.
        RECT rc;
        PAINTSTRUCT ps;

        if (GetUpdateRect(win, &rc, FALSE)) {
            BeginPaint(win, &ps);
            if (FAILED(myglobs.windevice->HandlePaint(ps.hdc)))
                DISPLAYMSG("Failed to handle WM_PAINT. ");
        }
        EndPaint(win, &ps);
        break;

    case WM_DESTROY:
        // bInitialized 플래그를 클리어 해, 오브젝트를 릴리즈 해,
        // WM_QUIT 메세지를 발행해, 어플리케이션을 종료한다.
        // 디바이스를 릴리즈 하기 전에, 뷰포트를 릴리즈 하는 것.
        // 이 순서를 잘못하면(자), 일반보호위반이 발생한다.
        myglobs.bInitialized = FALSE;
        RELEASE(myglobs.view);
        RELEASE(myglobs.windevice);
        RELEASE(myglobs.dev);
        RELEASE(lpD3DRM);
        RELEASE(lpDDClipper);
        PostQuitMessage(0);
        break;

    default:
        return DefWindowProc(win, msg, wparam, lparam);
    }
    return 0L;
}

관련 주제

여기에서는 Direct3D 보관 유지 모드를 사용해 오브젝트를 생성 해, 스크린에 배치하는 기본을 학습했다. Direct3D 보관 유지 모드의 샘플 코드가, 전보다도 간단하게 이해할 수 있게 되었을 것이다. 대부분의 샘플은,RMMain 가 제공하는 헬퍼 코드를 사용해 디바이스를 생성 해, 장면을 렌더링 하고 있지만, 독자적인BuildScene함수에 의해, 각각의 장면을 생성 하고 있다.

다음의 스텝으로서는,Egg 나Globe 등의 Direct3D 보관 유지 모드 샘플을 보면(자) 좋다. 이 샘플은,RMBegin1 나RMBegin2 와 닮은 기능을 가진다.

이제(벌써) 1개의 Direct3D 보관 유지 모드의 일반적인 태스크에 대해서는, 「디바이스의 열거：RMEnum 샘플」을 참조할것. 이 마디에서는, RMEnum의 샘플 코드의 워크 스루를 실시한다. RMEnum는, 디바이스를 열거하는 방법으로 초점을 맞히고 있다.

보관 유지 모드 샘플의 모든 개요에 대해서는, 「샘플」을 참조할것.


디바이스의 열거：RMEnum 샘플

디바이스의 열거는, Microsoft® Direct3D®보관 유지 모드의 기본적인 개념이다. 디폴트 디바이스는, 디바이스를 열거하지 않고생성 할 수 있다. 디바이스를 열거 하면, 시스템에 있는 디바이스를 식별해, 가장 적절한 디바이스를 선택해, 보다 고도의 기능을 사용할 수 있다.

이 항에서는, 샘플 RMEnum의 코드의 워크 스루를 실시한다. RMEnum는 시스템의 하드웨어 디바이스 및 소프트웨어 디바이스를 열거해, 최적인 디바이스를 선택해, 디바이스를 생성 한다. 게다가 열거한 디바이스를 어플리케이션의 [파일] 메뉴에 추가해, 유저가 메뉴로부터 디바이스를 선택할 수 있도록(듯이) 한다. 실제의 Direct3D 보관 유지 모드 어플리케이션과는 달라, RMEnum는 3 D오브젝트의 표시와 렌더링은 실시하지 않는다. 이 샘플은, 설명을 간결하게 하기 위해서, 열거만을 취급하고 있다.

이 항은, 유저가 C 또는 C++의 프로그래밍 경험이 있는 것, 및, 메시지 루프, 윈도우의 생성, 메뉴의 사용 등, Windows 프로그래밍의 기본 개념에 정통하고 있는 것을 전제로 하고 있다.

이 항은, 다음의 항목으로 나누어져 있다.

  • 전제
  • 글로벌 선언
  • 함수 개요
  • 관련 주제

전제

RMEnum는 DDraw.lib와 D3DRM.lib를 링크한다. RMEnum는, Error.c의Msg와D3DRMErrorToString 헬퍼 함수를 사용해, 에러 발생시에 상세 정보를 표시한다. 디폴트에서는, Error.c는 Microsoft® DirectX® Software Development Kit (SDK)의 Samples\Misc 디렉토리에 들어가 있다. 헬퍼 함수를 사용하는 대신에, Microsoft® Windows®의 표준MessageBox함수를 사용하는 것만으로도 좋지만, 알기 쉽고 상세한 에러 보고는 얻을 수 없다. 샘플은, RMEnum.rc가 제공하는 메뉴등의 리소스도 링크하고 있다.

글로벌 유니크 식별자(GUID)를 적절히 초기화하기 위해서, Direct3D 어플리케이션은, 코드의 선두에서 다음의 정의를 실시할 필요가 있다.

#define INITGUID

샘플의 RMEnum.cpp 파일은 다음의 헤더 파일을 인클루드 한다.

#include <windows.h>   /* 표준 Windows 헤더 파일 */
#include <direct.h>    /* DirectDraw의 정의 */
#include <d3drmwin.h>  /* Direct3D 보관 유지 모드의 정의 */
#include "RMEnum.h"    /* RMEnum.rc로 사용하는 정수의 정의 */
#include "rmerror.h"   /* rmerror.c의, 에러 보고 함수의 prototype */

글로벌 선언

이 샘플에서는, 몇개의 정수와 글로벌 변수를 정의해, 정보를 정리한다.

RMEnum.cpp에서는, 코드를 간략화하기 위해서, 열거하는 드라이버의 수를 제한하고 있지만, 1회 드라이버를 열거해 사용 가능한 드라이버수를 조사한 후, 이제(벌써) 1번 열거해 드라이버의 기능을 조사할 수도 있다. 실제의 어플리케이션에서는, 이 샘플과 같이 사이즈를 고정한 배열은 아니고, 드라이버 정보의 동적인 리스트를 관리하는 일도 있다.

#define MAX_DRIVERS 5  /* 검출하는 Direct3D의 드라이버수를
                          자의적으로 제한한다.  */

어플리케이션으로 정의되고 있는 RELEASE 매크로는, 오브젝트가 NULL 이외의 경우에만 오브젝트를 릴리즈 해, 릴리즈 후에 오브젝트를 NULL에 초기화한다. 벌써 릴리즈 한 오브젝트를 릴리즈 하면, 페이지 폴트등의 예기치 못한 결과가 발생하지만, 이 순서에 의해, 그러한 문제를 회피할 수 있다.

/* 오브젝트를 릴리즈 하는 매크로.  */
#define RELEASE(x) if (x ! = NULL) {x->Release(); x = NULL;}

myglobs 구조체는, 어플리케이션의 현재 상태에 가세해, 디바이스와 드라이버의 정보를 수집한다. Direct3D 보관 유지 모드 및 DirectDrawClipper 오브젝트도 글로벌이다(DirectDrawClipper 오브젝트는, 드로잉(Drawing)를 지정한 영역에 제한한다).

/*
 * 글로벌 변수
 */
LPDIRECT3DRM lpD3DRM = NULL;            /* Direct3DRM 오브젝트 */
LPDIRECTDRAWCLIPPER lpDDClipper = NULL; /* DirectDrawClipper 오브젝트 */

struct _myglobs {
    /* Direct3DRM 디바이스 */
    LPDIRECT3DRMDEVICE dev;

    /* 사용 가능한 Direct3D (D3D) 드라이버의 GUID */
    GUID DriverGUID[MAX_DRIVERS];

    /* 사용 가능한 D3D 드라이버의 이름 */
    char DriverName[MAX_DRIVERS][50];

    /* 사용 가능한 D3D 드라이버수를 나타내는 카운터 */
    int  NumDrivers;

    /* 현재 사용중의 D3D 드라이버의 수. enumDeviceFunc로,
     * 지정한 드라이버로 설정한다.  */
    int  CurrDriver;

    /* 프로그램은 종료중이다. */
    BOOL bQuit;

    /* 모든 D3D 오브젝트는 초기화되고 있다.  */
    BOOL bInitialized;

    /* 현재의 디스플레이 모드의 비트 깊이.  */
    DWORD BPP;
} myglobs;

함수 개요

RMEnum.cpp에는, 이하의 함수가 포함되어 있다.

CreateObjects 는, 글로벌 변수를 초기화하는 마스터 함수이며,EnumDevices 를 사용해 디바이스를 열거해, 오브젝트를 생성 한다. InitApp는CreateObjects를 사용한다.

BOOL CreateObjects(HWND win);

GetCurrentBitDepth 는, 현재의 비트 깊이를CreateObjects에 돌려준다.

static DWORD GetCurrentBitDepth(HWND);

EnumDevices 는, 디바이스의 열거에 사용하는 Direct3D 오브젝트를 취득해, 직접 모드의IDirect3D2::EnumDevices함수를 사용해, 파라미터로서enumDeviceFunc 콜백 함수를 건네주어, 열거한 디바이스를 [파일] 메뉴에 넣는다.

static BOOL EnumDevices(HWND);

enumDeviceFunc 콜백 함수는, 사용 가능한 드라이버를 순환해, 최적인 드라이버를 선택한다.

static HRESULT WINAPI enumDeviceFunc(LPGUID,
                                            LPSTR,
                                            LPSTR,
                                            LPD3DDEVICEDESC,
                                            LPD3DDEVICEDESC,
                                            LPVOID);

RMEnum는, 유저의 메뉴 선택에 응해,ChangeDriver 를 사용해 다른 사용 가능한 드라이버로 전환한다.

void ChangeDriver(HWND, WPARAM);

CleanUpAndQuit 는, 어플리케이션을 종료하기 전에 오브젝트를 릴리즈 한다.

static void CleanUpAndQuit(void);

그 외의 함수 (InitApp ,WinMain ,AppAbout ,WindowProc )는, 표준 Windows 함수를 기본으로, 샘플 RMEnum 고유의 코드를 조금 포함하고 있다.

static HWND InitApp(HINSTANCE, int);
int APIENTRY WinMain (HINSTANCE, HINSTANCE, LPSTR, int);
LRESULT CALLBACK AppAbout(HWND, UINT, WPARAM, LPARAM);
LRESULT CALLBACK WindowProc(HWND, UINT, WPARAM, LPARAM);

이상의 함수의 상세한 것에 대하여는, 이 항의 다음의 항목을 참조할것.

  • CreateObjects
  • GetCurrentBitDepth
  • EnumDevices
  • enumDeviceFunc
  • ChangeDriver
  • CleanUpAndQuit
  • 표준 Windows 함수

CreateObjects

CreateObjects는, 샘플 RMEnum의 핵이 되는 코드이다. 글로벌 변수를 초기화해, 현재의 비트 깊이를 취득한 후,EnumDevices 를 사용해 실제로 디바이스를 열거한다. enumDeviceFunc 콜백 함수는, 다음에 비트 깊이를 사용해, 현재의 비트 깊이를 지원 하는 드라이버를 결정한다.

CreateObjects는, 디바이스를 열거한 후, 디바이스의 생성에 필요한 순서를 실행해, 어플리케이션의 메인 윈도우에 관련짓는다. 이하의 순서에 따른다.

  1. Direct3DRMCreate 를 사용해, Direct3D 보관 유지 모드 오브젝트를 생성 한다.
  2. DirectDraw의DirectDrawCreateClipper함수를 사용해, DirectDrawClipper 오브젝트를 생성 한다.
  3. DirectDrawClipper의SetHWnd메소드를 사용해, 어플리케이션의 윈도우를 클리퍼에 관련짓는다. DirectDrawClipper 오브젝트는, 후속의 드로잉(Drawing)를, 지정한 영역 (여기에서는 어플리케이션의 윈도우)에 제한한다.
  4. Windows의GetClientRect함수를 사용해, 어플리케이션의 메인 윈도우의 높이와 폭을 취득한다.
  5. Direct3D 보관 유지 모드 오브젝트의CreateDeviceFromClipper 메소드를 사용해 디바이스를 생성 해, 열거에 의해 선택한 드라이버, 및 어플리케이션 윈도우의 폭과 높이를 메소드에 건네준다.

다음에,CreateObjects함수의 소스 코드를 나타낸다.

/*
 * 글로벌 변수를 초기화해, 디바이스를 열거해, 오브젝트를 생성 한다.
 */
BOOL CreateObjects(HWND win)
{
    HRESULT rval; /* 반환값 */
    RECT rc;      /* 메인 윈도우의 직사각형의 경계 */

    /*
     * 글로벌 변수의 초기화.
     */
    memset(&myglobs, 0, sizeof(myglobs));

    /*
     * 디스플레이의 현재의 비트 깊이를 기록한다.
     */
     myglobs.BPP = GetCurrentBitDepth(win);

    /*
     * D3D 드라이버를 열거해, 1개를 선택한다.
     */
    if (! EnumDevices(win))
        return FALSE;

    /*
     * Direct3DRM 오브젝트와 윈도우 오브젝트를 생성 한다.
     */
    rval = Direct3DRMCreate(&lpD3DRM);
    if (rval ! = D3DRM_OK) {
        Msg("Failed to create Direct3DRM. \n%s", D3DRMErrorToString(rval));
        return FALSE;
    }

    /*
     * DirectDrawClipper 오브젝트를 생성 해, 윈도우에 관련짓는다.
     */
    rval = DirectDrawCreateClipper(0, &lpDDClipper, NULL);
    if (rval ! = DD_OK) {
        Msg("Failed to create DirectDrawClipper object");
        return FALSE;
    }
    rval = lpDDClipper->SetHWnd(0, win);
    if (rval ! = DD_OK) {
        Msg("Failed to set the window handle for the DirectDrawClipper");
        return FALSE;
    }
    /*
     * 선택한 D3D 드라이버로 D3DRM 디바이스를 생성 한다. GUID를
     * NULL에 세트 하면, 열거없이 디폴트 디바이스를 생성 할 수 있다.
     */
    GetClientRect(win, &rc);

    rval = lpD3DRM->CreateDeviceFromClipper(lpDDClipper,
                           &myglobs.DriverGUID[myglobs.CurrDriver],
                           rc.right, rc.bottom, &myglobs.dev);

    if (rval) {
        Msg("Failed to create the D3DRM device. \n%s",
            D3DRMErrorToString(rval));
        return FALSE;
    }

    /*
     * 글로벌 변수는 초기화되었다.
     */
    myglobs.bInitialized = TRUE;

    return TRUE;
}

GetCurrentBitDepth

GetCurrentBitDepth함수는, 현재의 디바이스의 비트 깊이 성능을 결정해, DirectDraw 비트 깊이 플래그의 형식에서 정보를 돌려준다. 비트 깊이는, 디바이스의 컬러 설정 (8 비트, 16 비트, 또는 24 비트 컬러)을 나타낸다.

/*
 * 현재의 디스플레이의 비트 깊이를 BPP (bits per pixel)로 나타낸다
 * DirectDraw 비트 깊이 플래그를 취득한다.
 */
static DWORD GetCurrentBitDepth(HWND win)
{
    HDC hdc;
    int BPP;

    /*
     * 현재의 디스플레이의 BPP를 기록한다.
     */
    hdc = GetDC(win);
    BPP = GetDeviceCaps(hdc, BITSPIXEL);
    ReleaseDC(win, hdc);

    /*
     * BPP값을 DirectDraw 비트 깊이에 맵핑 한다.
     */
    switch(BPP) {
        case 1:
            return DDBD_1;
        case 2:
            return DDBD_2;
        case 4:
            return DDBD_4;
        case 8:
            return DDBD_8;
        case 16:
            return DDBD_16;
        case 24:
            return DDBD_24;
        case 32:
            return DDBD_32;
        default:
            return 0;
    }
}

EnumDevices

RMEnum의EnumDevices함수는, 이하의 순서에 따라, 디바이스를 열거한다. 순서에는, 샘플의 변수와 코드의 일부도 가리킨다.

  1. DirectDrawCreate함수를 사용해, DirectDraw 오브젝트를 생성 한다.
    LPDIRECTDRAW lpDD;
HRESULT rval;
rval = DirectDrawCreate(NULL, &lpDD, NULL);
  2. DirectDraw 오브젝트의QueryInterface메소드를 사용해, Direct3D 직접 모드 오브젝트를 취득한다. Direct3D 직접 모드의 상세한 것에 대하여는, 「Direct3D 직접 모드」를 참조할것.
    LPDIRECT3D lpD3D;
rval = lpDD->QueryInterface(IID_IDirect3D, (void**) &lpD3D);
  3. Direct3D 직접 모드 오브젝트의IDirect3D2::EnumDevices함수를 사용해, 시스템의 디바이스를 열거한다. IDirect3D2::EnumDevices는enumDeviceFunc 콜백 함수를 파라미터로서 건네준다.
    rval = lpD3D->EnumDevices(enumDeviceFunc, &myglobs.CurrDriver);

    이 콜백 함수는, 사용 가능한 디바이스를 순환해, 어느 기준에 맞는 드라이버를 선택한다.

ARMEnum의EnumDevices함수는 드라이버를 열거한 후, DirectDraw와 Direct3D의 디바이스를 릴리즈 해, 어플리케이션의 [파일] 메뉴에 드라이버를 추가한다.

lpD3D->Release();
lpDD->Release();

다음에, RMEnum의EnumDevices함수의 전소스 코드를 나타낸다.

/*
 * EnumDevices
 * 사용 가능한 Direct3D 드라이버를 열거해,[파일] 메뉴에 추가해,
 * 사용하는 드라이버를 1개 선택한다.
 */
static BOOL EnumDevices(HWND win)
{
    LPDIRECTDRAW lpDD;
    LPDIRECT3D lpD3D;
    HRESULT rval;
    HMENU hmenu;
    int i;

    /*
     * DirectDraw 오브젝트를 생성 해, 드라이버의 열거에 사용한다
     * Direct3D 인터페이스를 문의한다.
     */
    rval = DirectDrawCreate(NULL, &lpDD, NULL);
    if (rval ! = DD_OK) {
        Msg("Creation of DirectDraw HEL failed. \n%s",
            D3DRMErrorToString(rval));
        return FALSE;
    }
    rval = lpDD->QueryInterface(IID_IDirect3D, (void**) &lpD3D);
    if (rval ! = DD_OK) {
        Msg("Creation of Direct3D interface failed. \n%s",
            D3DRMErrorToString(rval));
        lpDD->Release();
        return FALSE;
    }
    /*
     * 드라이버를 열거한다. 어플리케이션 정의 데이터로서
     * 임의의 값이다―1을 건네준다. enumDeviceFunc 콜백 함수는,
     * -1에 대응해, 특수한 초기화 코드를 실행한다.
     */
    myglobs.CurrDriver = -1;
    rval = lpD3D->EnumDevices(enumDeviceFunc, &myglobs.CurrDriver);
    if (rval ! = DD_OK) {
        Msg("Enumeration of drivers failed. \n%s",
            D3DRMErrorToString(rval));
        return FALSE;
    }
    /*
     * 유효한 드라이버가 적어도  1개있는 것을 보증한다.
     */
    if (myglobs.NumDrivers == 0) {
        Msg("Could not find a D3D driver that is compatible with this \
            display depth");
        return FALSE;
    }
    lpD3D->Release();
    lpDD->Release();
    /*
     * 드라이버명을 [파일] 메뉴에 추가한다.
     */
    hmenu = GetSubMenu(GetMenu(win), 0);
    for (i = 0; i < myglobs.NumDrivers; i++) {
        InsertMenu(hmenu, 2 + i, MF_BYPOSITION | MF_STRING,
                   MENU_FIRST_DRIVER + i,
                   myglobs.DriverName[i]);
    }
    return TRUE;
}

enumDeviceFunc

Direct3D 직접 모드는, 시스템에 인스톨 된 Direct3D 디바이스를 열거하는 콜백 함수의 prototype 정의로서 D3DENUMDEVICESCALLBACK을 정의하고 있다. RMEnum는enumDeviceFunc를 열거 콜백 함수로서 제공한다. Direct3D 직접 모드는, 시스템에 인스톨 된 디바이스 마다enumDeviceFunc를 호출해, 디바이스 정보를enumDeviceFunc에 건네준다. D3D 직접 모드가 사용 가능한 드라이버를 루프 하는 동안,enumDeviceFunc는, 현재의 디스플레이의 비트 깊이로 렌더링 가능한 드라이버에 관한 정보를 글로벌 변수에 저장 한다. enumDeviceFunc는, 소프트웨어 에뮬레이션 드라이버보다, 하드웨어 드라이버를 우선적으로 선택한다(하드웨어 드라이버는 일반적으로 렌더링이 고속의 유익이다). 또, 3 차원 조명의 효과를 올리기 위해서(때문에), 흑백 조명보다 컬러 조명을 우선적으로 선택한다. 이 샘플에서는, RMEnum가 실제로는 렌더링을 실시하지 않기 때문에, 이 선택의 효과는 나타나지 않는다. 그러나, 실제의 어플리케이션에서는, 이러한 선택에 의해, 3 D그래픽스의 표시 상태에 큰 영향이 나온다.

enumDeviceFunc의 파라미터에는, 디바이스의 글로벌 유니크 식별자 (GUID), 디바이스의 텍스트 기술, 및 디바이스명이 있다. 그 외에, Direct3D 직접 모드의D3DDEVICEDESC 구조체가 2개 포함된다. 최초의 구조체 (lpHWDesc)에는, Direct3D 디바이스의 하드웨어 능력, 2개째의 구조체 (lpHELDesc)에는, 디바이스의 하드웨어 에뮬레이션 계층 (HEL)의 소프트웨어 에뮬레이션 능력이 각각 저장 된다. 마지막 파라미터는, Direct3D 직접 모드가 이 콜백 함수를 최초로 호출하면나무에, 어플리케이션 정의 데이터로서 건네받는다.

다음에, RMEnum의enumDeviceFunc콜백 함수의 전소스 코드를 나타낸다.

/*
 * enumDeviceFunc
 * 사용 가능한 D3D 드라이버의 이름과 GUID를 기록하는 콜백 함수.
 * 시스템의 드라이버를 선택한다. 소프트웨어 드라이버보다
 * 하드웨어 드라이버, 또, 흑백 조명보다 컬러 조명을
 * 우선적으로 선택한다. myglobs.CurrDriver에, 선택한 드라이버를
 * 설정한다.
 */
static HRESULT WINAPI enumDeviceFunc(LPGUID lpGuid,
                                     LPSTR lpDeviceDescription,
                                     LPSTR lpDeviceName,
                                     LPD3DDEVICEDESC lpHWDesc,
                                     LPD3DDEVICEDESC lpHELDesc,
                                     LPVOID lpContext)
{
    static BOOL hardware = FALSE; /* 현재의 시작 드라이버는 소프트웨어이다. */
    static BOOL mono = FALSE;     /* 현재의 시작 드라이버는 컬러 조명이다. */
    LPD3DDEVICEDESC lpDesc;       /* 현재의 드라이버의 기술. */

    /*
     * 이 어플리케이션이 정의하는 데이터. -1이면,
     * 최초로 열거된 드라이버를 현재의 드라이버로 하는 것을 나타낸다.
     */
    int *lpStartDriver = (int *) lpContext;

    /*
     * 어느 디바이스 기술을 조사할까 결정한다. 드라이버는 하드웨어 (HW)인가
     * 소프트웨어이다. 소프트웨어 드라이버는, HEL (하드웨어
     * 에뮬레이션 계층)으로 지원 된다.
     */
    lpDesc = lpHWDesc->dcmColorModel ?  lpHWDesc : lpHELDesc;
    /*
     * 이 드라이버가, 현재의 디스플레이의 비트 깊이에서는 렌더링 할 수 없다
     * 경우, D3DENUMRET_OK를 돌려주어, 이 드라이버를 스킵 한다.
     * 3 D3는 다음의 드라이버에 대해서 enumDeviceFunc를 다시 호출하므로,
     * 열거는 자동적으로 계속된다.
     */
    if (! (lpDesc->dwDeviceRenderBitDepth & myglobs.BPP))
        return D3DENUMRET_OK;
    /*
     * 이 드라이버의 GUID와 이름을 기록한다.
     */
    memcpy(&myglobs.DriverGUID[myglobs.NumDrivers], lpGuid, sizeof(GUID));
    lstrcpy(&myglobs.DriverName[myglobs.NumDrivers][0], lpDeviceName);
    /*
     * 소프트웨어보다 하드웨어를, 흑백 조명보다 컬러 조명을
     * 선택한다.
     */
    if (*lpStartDriver == (int)-1) {
        /*
         * 이것이 최초의 유효한 드라이버이다. 거기서, 이것이 하드웨어
         * 드라이버일지 어떨지, 흑백 조명으로 한정되고 있는지 어떤지를
         * 기록한다.
         */
        myglobs.CurrDriver = myglobs.NumDrivers;
        hardware = lpDesc == lpHWDesc ?  TRUE : FALSE;
        mono = lpDesc->dcmColorModel & D3DCOLOR_MONO ?  TRUE : FALSE;
    } else if (lpDesc == lpHWDesc && ! hardware) {
        /*
         * 이 드라이버가 하드웨어 드라이버이며, 시작 드라이버가
         * 하드웨어 드라이버가 아니면, 이 드라이버를 새로운 드라이버로 해,
         * 하드웨어 또한 흑백 성능인 것을 기록한다. D3D가
         * enumDeviceFunc를 다음에 호출하면 와, 그 드라이버는,
         * 이 새로운 시작 드라이버라고 비교된다.
         */
        myglobs.CurrDriver = myglobs.NumDrivers;
        hardware = lpDesc == lpHWDesc ?  TRUE : FALSE;
        mono = lpDesc->dcmColorModel & D3DCOLOR_MONO ?  TRUE : FALSE;
    } else if ((lpDesc == lpHWDesc && hardware ) || (lpDesc == lpHELDesc
                                                     && ! hardware)) {
        if (lpDesc->dcmColorModel == D3DCOLOR_RGB && mono) {
            /*
             * 이 드라이버와 시작 드라이버가 같은 타입
             * (양쪽 모두 하드웨어인가, 양쪽 모두 소프트웨어)(으)로, 이 드라이버는
             * 컬러 조명이지만 시작 드라이버는 컬러 조명이 아니면, 이 드라이버를
             * 새로운 드라이버로 설정해, 성능을 기록한다.
             * D3D가 enumDeviceFunc을 다음에 호출하면 와, 그 드라이버는,
             * 이 새로운 시작 드라이버라고 비교된다.
             */
            myglobs.CurrDriver = myglobs.NumDrivers;
            hardware = lpDesc == lpHWDesc ?  TRUE : FALSE;
            mono = lpDesc->dcmColorModel & D3DCOLOR_MONO ?  TRUE : FALSE;
        }
    }
    /*
     * 다음의 드라이버에 대비해, 현재의 드라이버 번호를
     * 늘린다.
     */
    myglobs.NumDrivers++;

    /* 드라이버의 최대수에 이르면(자), 열거를 정지한다.  */
    if (myglobs.NumDrivers == MAX_DRIVERS)
        return (D3DENUMRET_CANCEL);
    /*
     * 드라이버의 열거를 계속한다. D3D는 다음의 드라이버에 대해서,
     * 이 정보를 사용해 enumDeviceFunc를 호출한다.
     */
    return (D3DENUMRET_OK);
}

ChangeDriver

ChangeDriver는, 샘플 RMEnum에 있어 필수의 함수는 아니지만, 유저가 드라이버를 선택하는 유연성을 부가한다. ChangeDriver는, 메뉴 선택에 응해 현재의 드라이버를 변경한다. 그리고, RMEnum의CreateObjects 함수가 디바이스를 최초로 생성 한 것처럼, Direct3D 보관 유지 모드 오브젝트의CreateDeviceFromClipper 메소드를 사용해 디바이스를 재생성 한다.

다음에,ChangeDriver의 소스 코드를 나타낸다.

/*
 * 현재의 디바이스를 릴리즈 해, 새로운 디바이스를 생성 한다.
 */
void ChangeDriver(HWND win, WPARAM wparam)
{
    HRESULT rval;
    RECT rc;

    /*
     * 전의 드라이버 선택을 LastDriver로서 보존한다.
     */
    int LastDriver = myglobs.CurrDriver;

    /*
     * 선택 내용이 변경되었기 때문에, 글로벌 변수는 정확하지 않게 된다.
     */
    myglobs.bInitialized = FALSE;

    /*
     * 현재의 디바이스를 릴리즈 한다.
     */
    RELEASE(myglobs.dev);

    /*
     * 현재의 드라이버를 메뉴로부터 선택된 드라이버로 설정한다.
     */
    myglobs.CurrDriver = LOWORD(wparam) -MENU_FIRST_DRIVER;

    /*
     * 윈도우의 경계 직사각형을 취득한다. 글로벌 오브젝트 DirectDrawClipper
     * (을)를 사용해, 그 윈도우의 새로운 현재의 드라이버를 생성 한다.
     */
    GetClientRect(win, &rc);

    rval = lpD3DRM->CreateDeviceFromClipper(lpDDClipper,
                             &myglobs.DriverGUID[myglobs.CurrDriver],
                             rc.right, rc.bottom, &myglobs.dev);

    /*
     * 에러가 발생하면(자), 전의 드라이버를 재생성 한다.
     */
    if (rval) {
        myglobs.CurrDriver = LastDriver;

        rval = lpD3DRM->CreateDeviceFromClipper(lpDDClipper,
                                 &myglobs.DriverGUID[myglobs.CurrDriver],
                                 rc.right, rc.bottom, &myglobs.dev);
        if (rval) {
            Msg("Failed to create the D3DRM device. \n%s",
                D3DRMErrorToString(rval));
            CleanUpAndQuit();
        }
        else {
            Msg("There was not enough video memory available to use the \
                 3D accelerated hardware device. \nRestoring old software \
                 device. ");
            myglobs.bInitialized = TRUE;
        }
    }
    else {
        /*
         * 글로벌 변수는, 다시 적절히 초기화되었다.
         */
        myglobs.bInitialized = TRUE;
    }
}

CleanUpAndQuit

매우 짧은CleanUpAndQuit함수는, 글로벌 오브젝트를 릴리즈 해, quit 플래그를 TRUE로 설정해, 어플리케이션의 종료 준비가 갖추어진 것을 나타낸다.

void CleanUpAndQuit(void)
{
    myglobs.bInitialized = FALSE;
    RELEASE(myglobs.dev);
    RELEASE(lpD3DRM);
    RELEASE(lpDDClipper);
    myglobs.bQuit = TRUE;
}

표준 Windows 함수

RMEnum.cpp의, 그 외의 함수 (InitApp,WinMain,AppAbout,WindowProc)는, 본래는 표준 Windows 함수로, 샘플 RMEnum에 고유의 짧은 코드를 포함하고 있다. 상세한 것에 대하여는, RMEnum의 샘플 코드를 참조할것.

  • InitApp는, 메인 윈도우를 생성 해, 샘플의CreateObjects 함수를 사용한다.
  • WinMain는,InitApp함수를 호출한다. 이 함수는, Windows의 메인 메시지 루프를 포함하고 있어 글로벌 변수 myglobs.bQuit가 TRUE가 될 때까지, 메세지를 처리한다. WinMain는, 어플리케이션의 종료를 통지하는 표준 Windows WM_QUIT 메세지에 응해CleanUpAndQuit를 사용한다.
  • AppAbout는, 어플리케이션의 [About] 다이알로그 박스의 메세지를 처리한다.
  • WindowProc는, 어플리케이션의 메인 윈도우의 메세지를 처리한다. 열거한 드라이버를 선택할 수 있도록(듯이) [파일] 메뉴를 초기화해, 어플리케이션의ChangeDriver 함수를 사용해, 유저의 드라이버 선택을 처리한다. WindowProc는CleanUpAndQuit 를 사용해, 표준 Windows WM_DESTROY 메세지에 응해 리소스를 릴리즈 한다. 이 메세지는, 유저가 어플리케이션을 종료했으므로, Windows가 어플리케이션 윈도우를 파기중인 것을 통지하는 것이다.

관련 주제

여기에서는 디바이스를 열거하는 방법을 학습했다. Direct3D 보관 유지 모드의 샘플 코드가, 전보다도 간단하게 이해할 수 있게 되었을 것이다. 대부분의 샘플은,RMMain 가 제공하는 헬퍼 코드를 사용해 디바이스를 열거한다. 다음의 스텝으로서는,Egg 나Globe 등의 샘플을 봐, 장면의 뒤에서 디바이스의 열거를 실시하고 있는 것을 염두에 두면서, 렌더링 하는 방법을 조사하면(자) 좋다.

보관 유지 모드 샘플의 모든 개요에 대해서는, 「샘플」을 참조할것.


기초지식

이하의 주제에서는, 3 D그래픽스를 짜넣는 프로그램을 쓰기 전에 이해할 필요가 있는 기술적인 개념을 몇개인가 설명한다. 그러한 항에서는, 좌표계와 변환의 일반적인 설명을 실시하고 있다. 이것은, 모델, 조명, 뷰잉파라메이타의 설정등의, 폭넓은 아키텍쳐 위에의 상세 사항을 설명하는 것은 아니다. 그러한 사항의 상세한 것에 대하여는, 「Direct3D 보관 유지 모드 아키텍쳐」를 참조할것.

3 D그래픽스를 만든 경험이 있는 경우에는, Microsoft® Direct3D® 보관 유지 모드에 특유의 정보만을 조사하도록(듯이) 이하의 토픽을 읽는 것.

  • 3 D좌표계
  • 3 D변환
  • 다각형
  • 삼각형의 전개도와 선형
  • 벡터, 버텍스, 및 4원수
  • Z버퍼와 오버레이

3 D좌표계

3 D그래픽스 어플리케이션에서는, 보통, 왼손 좌표계와 오른손 좌표계의 2살의 데카르트 좌표계를 사용한다. 양쪽 모두의 좌표계로, x축의 정방향은 우측이며, y축의 정방향은 윗쪽이다. z축의 정방향은, x축의 정방향에 왼손 또는 오른손의 손가락을 향해 그것을 y축의 정의 방향으로 회전한 방향이 된다. 엄지의 방향, 앞 또는 안쪽이, 이 좌표계에서의 z축의 정방향이다.

이 항은, Direct3D의 좌표계와 유저의 어플리케이션을 사용할 수 있는 좌표 타입을 설명한다.

  • Direct3D의 좌표계
  • U좌표와 V좌표

Direct3D의 좌표계

Direct3D는 디폴트에서는 왼손 좌표계를 사용한다. 즉, 아래의 그림에 나타내도록(듯이) 정의 z축이 보는 사람으로부터 멀어질 방향을 가리킨다.

왼손 좌표계에서는, 회전은, 보는 사람을 가리키는 임의의 축의 주위를 시계회전에 회전한다.

오른손 좌표계로 작업할 필요가 있는 경우, 예를 들어, 오른손 좌표계에 따르는 어플리케이션을 이식하는 경우에는, Direct3D에게 건네지는 데이터에 2개의 단순한 변경을 더하는 것만으로 실시할 수가 있다.

주: DirectX 버젼 6.0으로부터는,IDirect3DRM3::SetOptions 를 사용해, Direct3D 보관 유지 모드에 대해서 오른손 좌표계를 사용하는 것을 지시할 수 있다. IDirect3DRM3::SetOptions를 사용 하면, 데이터를 변경할 필요가 없어진다.

DirectX 버젼 6.0보다 전의 버젼에서는, 오른손 좌표계를 사용하는 경우, Direct3D 보관 유지 모드에 건네주는 데이터를, 다음과 같이 변경할 필요가 있다.

  • 삼각형의 버텍스의 순서를 반전해, 시스템이 전부터 시계회전에 더듬을 수 있도록(듯이) 한다. 즉, 버텍스를 v0, v1, v2와 하면, Direct3D에는 v0, v2, v1로서 건네준다.
  • 뷰 매트릭스를 사용해, 월드 공간을 z축방향으로―1 스케일링 한다. 그 때문에(위해)는, 뷰 매트릭스에 사용하는D3DMATRIX 구조체의_13,_23,_33,_43의 각 멤버의 부호를 반전한다.

U좌표와 V좌표

Direct3D는,텍스쳐 좌표도 사용한다. 이 좌표(u와 v)는, 오브젝트상에 텍스쳐를 맵 할 경우에 사용한다. v벡터는, 텍스쳐의 방향 또는 방향을 나타내, z축으로 따라 존재한다. u벡터(또는업벡터)는 보통, y축으로 따라 존재해, 그 원점은[0,0,0]에 있다. u와 v좌표의 상세한 것에 대하여는, 「랩」을 참조할것.

3 D변환

3 D그래픽스와 기능하는 프로그램에서는, 기하 변환을 사용해 다음 일이 가능하다.

  • 다른 오브젝트를 기준으로 해 오브젝트의 위치를 나타내는 것.
  • 오브젝트를 회전, 절단, 사이즈를 변경하는 것.
  • 보는 위치, 방향, 및 퍼스펙티브를 변경하는 것.

4×4 행렬을 사용해, 임의의 점을 다른 점으로 변환할 수가 있다. 이하의 예에서는, 행렬을 사용해 점(x, y, z)을 변환해 새로운 점(x', y', z')을 만들어 내고 있다.

4×4행렬을 사용한 점의 변환

이하의 조작을(x, y, z) 및 행렬에 실행해 점(x', y', z')을 만들어 낸다.

행렬 변환에 의한 조작

가장 보통 변환은, 평행이동, 회전 및 스케일링이다. 이러한 효과를 만들어 내는 행렬을 1개의 행렬에 결합해, 복수의 변환을 한 번에 계산할 수가 있다. 예를 들어, 1개의 행렬을 생성 해, 일련의 점을 평행이동 해 회전할 수가 있다.

행렬은 행순으로 지정된다. 예를 들어, 다음의 행렬은, 배열로 나타내는 일도 가능하다.

이하의 배열로 나타내지는 행렬 샘플

이 행렬에 대응하는 배열은, 이하와 같이 된다.

D3DMATRIX scale = {
    D3DVAL(s),    0,            0,            0,
    0,            D3DVAL(s),    D3DVAL(t),    0,
    0,            0,            D3DVAL(s),    D3DVAL(v),
    0,            0,            0,            D3DVAL(1)
};

이 항에서는, Direct3를 개입시켜 유저의 어플리케이션을 사용할 수 있는 3 D변환을 설명한다.

  • 평행이동
  • 회전
  • 스케일링

이 메뉴얼의 다른 부분에서도 변환에 대해 설명하고 있다. 보관 유지 모드의 뷰포트만을 취급한 항 「변환」에 변환의 일반적인 설명이 있다. 프레임중의 변환의 설명에 대해서는, 「변환」을 참조할것. 이상의 각 항에서는, 보관 유지 모드 API를 설명하고 있지만, 변환의 아키텍쳐와 수학은, 보관 유지 모드와 직접 모드의 양쪽 모두에 적용된다.

평행이동

이하의 변환은, 점(x, y, z)을 새로운 점(x', y', z')에 평행이동 한다.

점을 변환하는 행렬

회전

이 항으로 설명하는 변환은, 왼손 좌표계에 대하는 것이므로, 유저가 외로 본 변환 행렬과는 다른 경우도 있다.

이하의 변환은, 점(x, y, z)을 x축의 회전으로 회전해, 새로운 점(x', y', z')을 만들어 낸다.

x축의 회전으로 점을 회전시키는 행렬

이하의 변환은, 점을 y축의 회전으로 회전시킨다.

y축의 회전으로 점을 회전시키는 행렬

이하의 변환은, 점을 z축의 회전으로 회전시킨다.

z축의 회전으로 점을 회전시키는 행렬

이상의 예의 행렬로, 그리스 문자의 시타는, 라디안 단위로 지정된 회전각을 나타내는 것에 주의한다. 각도는, 원점 방향으로 회전축에 따라 볼 방향으로, 시계회전에 잰다.

스케일링

이하의 변환은, x, y, z의 각방향의 임의의 값에 의해 점(x, y, z)을 새로운 점(x', y', z')에 스케일링 한다.

점을 스케일링 하는 행렬

다각형

Direct3D의 3 차원 오브젝트는, 메쉬로 구성된다. 메쉬란, 면의 집합이며, 각면은 단순한 다각형으로 나타내진다. 기본적인 다각형의 타입은, 삼각형이다. 보관 유지 모드 어플리케이션에서는, 4 버텍스 이상의 다각형을 지정할 수 있는 것에도 불구하고, 시스템은, 오브젝트를 렌더링 하기 전에 다각형을 삼각형으로 변환한다. 직접 모드 어플리케이션에서는, 삼각형을 사용해야 한다.

이 항에서는, 유저의 어플리케이션이 Direct3D 다각형을 어떻게 사용하는지를 설명한다.

  • 도형 요건
  • 면법선과 버텍스 법선
  • 쉐이딩 모드
  • 삼각형 보간 요소

도형 요건

삼각형은 자주(잘) 사용되는 다각형의 타입이다. 삼각형은, 렌더러가 다각형에 요구하는 2조건 (항상 철이며, 항상 평탄하다)을 채우기 때문이다. 다각형은, 다각형의 임의의 2점을 직선으로 묶었을 때, 그 직선이 또 다각형의 내부에 존재하는 경우에 철이다고 한다.

요철장의 다각형의 그림

삼각형의 3 버텍스는, 항상 평면을 나타내지만, 이제(벌써) 1개의 버텍스를 추가하는 것에 의해, 비평면의 다각형을 생성 하는 것은 간단하다.

비평면의 다각형의 그림

면법선과 버텍스 법선

메쉬중의 각면에는, 수직면의 법선 벡터가 있다. 법선 벡터 의 방향은, 버텍스가 정의되고 있는 순서와 좌표계가, 왼손 좌표계나 오른손 좌표계 등에 의해서 결정된다. 면의 법선 벡터가 보는 사람의 방향을 향하고 있는 경우에는, 그 옆의 면이 전이 된다. Direct3D에서는, 면의 앞측만이 가시이며, 전면은, 그 중에 버텍스가 시계회전에 정의되는 것이 된다.

다각형의 면의 버텍스와 법선 벡터의 그림

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

버텍스 법선과 면법선의 그림

쉐이딩 모드

flat shading 모드에서는, 시스템은, 1개의 버텍스의 색을 프리미티브의 다른 면의 모두에게 재현 한다. 굿 로와 폰 쉐이딩 모드에서는, 버텍스 법선은, 다각형 오브젝트가 원활히 보이도록(듯이) 하기 위해서 사용한다. gouraud shading에서는, 인접의 버텍스의 색과 휘도(Luminance)는, 버텍스를 멀리하고 있는 공간에 건너 보간 된다. 폰 쉐이딩에서는, 시스템이 얼굴의 각 픽셀에 대한 적절한 쉐이딩값을 산출한다.

주 폰 쉐이딩은, 현재 지원되어 있지 않다.

어플리케이션은, 보통, 오브젝트를 매끄럽게 보이게 해 또 계산도 효율적이므로, gouraud shading를 사용한다. 다만, gouraud shading는, 폰 쉐이딩이 놓치지 않는 세부를 놓치는 경우가 있다. 이 예로서 들었던 것이 다음의 그림이다. 여기에서는,spotlight가 다각형의 표면에 완전하게 흡수되어 버리고 있다.

gouraud shading와 폰 쉐이딩을 비교한 얼굴의 spotlight의 그림

이 경우, 폰 쉐이딩 모드는, 각 픽셀에 대한 값을 계산해, spotlight를 표시한다. gouraud shading 모드는, 버텍스의 사이를 보간 하므로, spotlight는 모두 생략 되어 마치 spotlight가 존재하지 않는 것처럼 면이 렌더링 된다.

flat shading 모드에서는, 다음의 피라미드는 인접하는 면의 사이에 날카로운 엣지가 있도록 표시된다. 시스템은, 자동적으로 면법선을 생성한다. 그러나, 굿 로 또는 폰 쉐이딩 모드에서는, 쉐이딩값이 엣지 전체에 보간 되어 최종적으로 곡면의 표면이 표시된다.

flat shading 모드의 피라미드

굿 로 또는 폰 쉐이딩 모드를 사용해 곡면을 표시해, 또, 날카로운 엣지를 가지는 복수의 오브젝트를 포함하고 싶은 경우, 유저의 어플리케이션에서는, 다음의 그림으로 가리키도록(듯이) 날카로운 엣지를 필요로 하는 면의 임의의 교제로 버텍스 법선을 재현 할 필요가 있다.

평면은 아니고 쉐이딩에 날카로운 엣지를 보관 유지하기 위해서 필요한 버텍스 법선

단일의 오브젝트에, 곡면과 평면의 양쪽 모두를 가지도록(듯이) 하는데 더해, gouraud shading 모드는, 평탄한 표면을, flat shading 모드보다 현실감이 있도록(듯이) 빛으로 비춘다. flat shading 모드에서의 표면은 한결같은 색이지만, gouraud shading 모드에서는, 빛이 면전반에 올바르게 맞도록 할 수 있다. 이 효과는 근처에 점소스가 있는 경우에, 특별히 눈에 띄게 된다. gouraud shading 모드는, 많은 Direct3D 어플리케이션이 요구하는 쉐이딩 모드이다.

삼각형 보간 요소

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

  • 색
  • 반사색
  • 포그(안개:fog)
  • 알파

이러한 삼각형 보간 요소는 모두, 현재의 쉐이딩 모드에 의해 바뀐다.

플랫 | 보간은 행해지지 않는다. 그 대신해, 삼각형의 최초의 버텍스의 색이 면전체에 적용된다.
굿 로 | 선형 보간이 3개의 버텍스 모든 사이에 실행된다.
폰 | 버텍스 파라미터가, 현재의 조명을 사용해, 면의 각 픽셀에 대해서 재계산된다. 폰 쉐이딩 모드는, 현재 지원되어 있지 않다.

색보간 요소와 반사색보간 요소의 처리는 색모델에 따라서 다르다. RGB색모델(D3DCOLOR_RGB )에서는, 시스템은 적색, 녹색, 및 청색 성분을 사용해 보간을 실시한다. 흑백 모델(D3DCOLOR_MONO )에서는, 시스템은 버텍스색의 청색 성분만 사용한다.

예를 들어, 버텍스 1의 색의 빨강 성분이 0.8, 버텍스 2의 빨강 성분이 0.4이라고 하면, gouraud shading 모드와 RGB색모델에서는, 시스템은 보간을 사용해, 그러한 버텍스의 선분의 중점에 있는 픽셀에 빨강 성분의 0.6을 할당한다.

색의 알파 성분은, 별개의 보간 요소로서 처리된다. 디바이스 드라이버가 투명성을,텍스쳐 블렌딩또는 점묘에 의한 2로 우리 방법으로 이행 할 수 있기 때문이다.

어플리케이션은,D3DPRIMCAPS 구조체의dwShadeCaps멤버를 사용해, 현재의 디바이스 드라이버가 지원 하는 보간의 형식을 확인할 수가 있다.

삼각형의 전개도와 선형

각 삼각형의 3 버텍스 모든 것을 지정하는 일 없이, 삼각형 전개도와 삼각형 선형을 사용해 전면을 지정할 수가 있다. 예를 들어, 이하의 삼각형의 전개도를 정의하려면 , 7개의 버텍스 밖에 필요로 하지 않는다.

삼각형의 전개도와 그 버텍스의 샘플

시스템이, 버텍스의 v1, v2, v3를 사용해 최초의 삼각형을, v2, v4, v3를 사용해 2번째의 삼각형을, v3, v4, v5를 사용해 3번째의 삼각형을, v4, v6, v5를 사용해 4번째의 삼각형을, 이라고 하는 순서로 드로잉(Drawing) 해 나간다. 2번째와 4번째의 삼각형의 버텍스가 순서 대로가 아닌 것에 주의한다. 이것은, 모든 삼각형이 시계회전의 방향으로 드로잉(Drawing) 하는 것을 보증하기 위해서 필요하다.

삼각형 선형은, 모든 삼각형이 1개의 버텍스를 공유하는 점을 제외하면, 삼각형 전개도에 유사하고 있다.

삼각형 선형의 그림

시스템은, 버텍스 v1, v2, v3를 사용해 최초의 삼각형을, v3, v4, v1를 사용해 2번째의 삼각형을, v1, v4, v5를 사용해 3번째의 삼각형을, 이라고 하는 순서로 드로잉(Drawing) 해 나간다.

D3DTRIANGLE 구조체의wFlags멤버를 사용해, 삼각형 전개도와 선형을 생성 하는 플래그를 지정할 수가 있다.

벡터, 버텍스, 및 4원수

Direct3D 전체를 통해서, 버텍스는 위치와 방향을 나타낸다. 프리미티브중의 각 버텍스는, 그 위치를 주는 벡터와 그 방향을 주는법선 벡터, 텍스쳐 좌표, 및 색에 의해 기술된다(보관 유지 모드에서는,D3DRMVERTEX 구조체가 이상의 값을 저장 한다).

4원수는, 벡터를 정의하는 [x, y, z] 값에 4번째의 요소를 추가한다. 4원수는, 3 D회전에 사용되는 행렬 메소드에 대신하는 것이다. 4원수는, 3 D공간에서의 축과 그 축을 중심으로 하는 회전을 나타낸다. 예를 들어, 4원수는, (1,1,2) 축과 1 라디안의 회전을 나타낼 수도 있다. 4원수는, 중요한 정보를 전하지만, 그 진정한 위력은, 그에 대한 실행할 수 있는 2개의 조작의합성과보간에 있다.

4원수에 합성을 실행하는 것은, 결합하는 것으로 유사하고 있다. 2개의 4원수의 합성은, 이하와 같이 나타내진다.

2살의4원수의 합성을 나타내는 식

도형에 적용되는 2개의 4원수의 합성은, 「축 2의 회전에 회전 2로 도형을 회전시킨 후, 축 1의 회전에 회전 1으로 회전시킨다」일을 의미한다. 이 경우, Q가 단일의 축의 회전의 회전을 나타내, 그 결과가 q2에 적용된 후, q1이 도형에 적용된다.

4원수보간을 사용 하면, 어플리케이션은, 1개의 축과 방향으로부터 다른 축과 방향에, 매끄러워 합리성이 있는 패스를 산출할 수가 있다. 따라서, q1으로 q2의 사이의 보간은, 1개의 방향으로부터 다른 방향에 애니메이션을 움직이는 간단한 방법을 제공한다.

합성과 보간을 동시에 사용 하면, 복잡하게 보이지만, 실은 단순한 방법으로 도형을 처리할 수가 있다. 예를 들어, 지정의 방향으로 회전시키고 싶은 도형이 있는 것과 가정한다. 축2를 중심으로 r2번 회전시킨 후, 축1을 중심으로 r1번 회전시키고 싶은 것까지는 알고 있지만, 최종적인 4원수는 모른다. 합성을 사용해, 도형 위에의 2개의 회전을 합성해, 결과적으로 단일의 4원수를 얻을 수 있다. 그 후, 원의 4원수로부터 합성된 4원수까지 보간 해, 한편으로부터 한편에의 매끄러운 이행을 실현한다.

Direct3D 보관 유지 모드에는, 4원수를 사용하는데 있어서, 유저가 도움이 되는 함수가 몇개인가 포함되어 있다. 예를 들어,D3DRMQuaternionFromRotation 함수는, 회전값을 회전축을 정의하는 벡터에 추가해, 결과를D3DRMQUATERNION 구조체가 정의하는 4원수에 돌려준다. 또,D3DRMQuaternionMultiply 함수는, 4원수를 합성해,D3DRMQuaternionSlerp 는, 2개의 4원수간에 구(공)면선형 보간을 실행한다.

보관 유지 모드 어플리케이션은, 이하의 함수를 사용해 벡터와 4원수를 사용하는 작업을 간단하게 할 수가 있다.

  • D3DRMQuaternionFromRotation
  • D3DRMQuaternionMultiply
  • D3DRMQuaternionSlerp
  • D3DRMVectorAdd
  • D3DRMVectorCrossProduct
  • D3DRMVectorDotProduct
  • D3DRMVectorModulus
  • D3DRMVectorNormalize
  • D3DRMVectorRandom
  • D3DRMVectorReflect
  • D3DRMVectorRotate
  • D3DRMVectorScale
  • D3DRMVectorSubtract

Z버퍼와 오버레이

Z버퍼의 순서는, 오버레이가 서로 클리핑 하는 그 순서를 결정한다. 오버레이는, 다른 모든 스크린 컴퍼넌트의 선두에 오는 것과 가정되고 있다. 지정 Z오더를 가지지 않는 오버레이는, 프라이머리 표면의 같은 영역에서 오버레이를 실시할 때 예측할 수 없는 동작을 한다. Z버퍼가 없으면 Direct3D 보관 유지 모드는 오버레이를 소트 하지 않는다. 지정 Z오더를 가지지 않는 오버레이는 Z오더 0을 가지는 것으로 여겨져 렌더링 하는 순서로 나타난다. 오버레이의 Z오더의 가능한 범위는, 프라이머리 표면의 바로 위인 0으로부터, 보는 인으로 할 수 있는 한 가까운 40억까지이다. Z오더 2의 오버레이는, Z오더 1의 오버레이를 덮어 가린다. 어느 오버레이도, 다른 오버레이와 동일한 Z오더를 가질 수 없다.


아키텍쳐

이 마디에서는, Microsoft® Direct3D® 보관 유지 모드 오브젝트 및 COM 아키텍쳐에 대해 해설한다. 다음의 항목에 대해 설명한다.

  • 「Direct3D 보관 유지 모드 오브젝트」에서는,Direct3D 보관 유지 모드 오브젝트에 대해 간단하게 설명한다.
  • 「오브젝트와 인터페이스」에서는, 각 오브젝트가 지원 하는 인터페이스, 및, 단일 오브젝트와배열 오브젝트의 양쪽 모두에, 인터페이스를 생성하기 위한 정보를 열거하고 있다.
  • 「오브젝트와 참조 카운트」에서는,Direct3D 보관 유지 모드의 참조 카운트에 관한 힌트를 준다.

Direct3D 보관 유지 모드 오브젝트

Direct3D 보관 유지 모드에의 액세스는, 몇 안 되는 수의 오브젝트를 통해 행해진다. 이하의 겉(표)에 이러한 오브젝트를 리스트업 해, 각각 붙어 간단하게 설명한다.

오브젝트 | 설명
Direct3DRMAnimation2 | 많은 경우,Direct3DRMFrame3오브젝트에 관련해, 변환을 얼마나 변경하는지를 정의한다. 따라서, 이 오브젝트를 사용해Direct3DRMVisual ,Direct3DRMLight 및Direct3DRMViewport2 오브젝트의 위치, 방향 및 스케일의 애니메이션을 실시할 수가 있다. Direct3DRMAnimation오브젝트와 같지만, 애니메이션의 키와 프레임에 액세스 할 수 있다.
Direct3DRMAnimationArray | 배열의 애니메이션수, 및 요구한 애니메이션에의 인터페이스를 취득한다.
Direct3DRMAnimationSet2 | Direct3DRMAnimation2 오브젝트를 그룹화 한다. Direct3DRMAnimationSet오브젝트와 같지만, 원가요소 애니메이션에 액세스 할 수 있다.
Direct3DRMClippedVisual | 렌더링전에, 비주얼을 임의의 프레인에 클리핑 할 수 있다.
Direct3DRMDevice3 | 렌더러의 비주얼 표시처를 나타낸다. Direct3DRMDevice2오브젝트를 확장해, 유저에 의한 머트리얼의 설정과 취득을 가능하게 했다. Direct3DRMDevice2는Direct3DRMDevice오브젝트와 같은 기능을 가지지만, 투명도의 제어가 확장되고 있다.
Direct3DRMFace2 | 메쉬 위에의 1개의 다각형을 나타낸다.
Direct3DRMFrame3 | 장면에 오브젝트를 배치해, 비주얼 오브젝트의 위치나 방향을 정의한다. 프레임축, 경계 박스, 및 머트리얼에 대한 액세스를 유효하게 하는 것에 의해,Direct3DRMFrame오브젝트를 확장한다. 광선 픽도 지원 한다. Direct3DRMFrame2오브젝트를 확장해, 변환, 호랑이 용기, 포그(안개:fog) 처리의 기능을 추가했다.
Direct3DRMInterpolator | 액션을 저장 해, 중간값을 자동 계산해 오브젝트에 그 액션을 적용한다.
Direct3DRMLight | 5 종류의 조명의 하나를 정의해, 장면의 비주얼 오브젝트를 채색 하기 위해서 이용된다.
Direct3DRMMaterial2 | 표면의 반사 특성을 정의한다. Direct3DRMMaterial오브젝트와 같지만, 머트리얼의 프로퍼티를, 보다 세세하게 조정할 수 있다.
Direct3DRMMesh | 다각형의 면세트를 포함한다. 면이나 버텍스의 그룹을 조작하기 위해서 사용할 수 있다.
Direct3DRMMeshBuilder3 | 메쉬에 있는 각각의 버텍스나 면을 조작할 수가 있다. Direct3DRMMeshBuilder오브젝트를 확장해, 법선에 대한 제어를 강화해, 메쉬의 면을 취득 가능하게 했다. Direct3DRMMeshBuilder2오브젝트를 확장해,IDirect3DRM3 인터페이스에 의한 생성시에, 직접 모드의 DrawPrimitive 인터페이스를 사용하도록(듯이) 했다.
Direct3DRMObject | Direct3D의 다른 모든 보관 유지 모드 오브젝트에 의해 기본 클래스로서 이용된다. 모든 오브젝트에 공통된 특징을 보관 유지하고 있다.
Direct3DRMObject2 | Direct3D의 다른 모든 보관 유지 모드 오브젝트에 의해 기본 클래스로서 이용된다. 모든 오브젝트에 공통된 특징을 보관 유지하고 있다. Direct3DRMObject 를 확장해, 오브젝트에 데이터를, 보다 유연하게 관련지을 수 있도록(듯이) 했다.
Direct3DRMPickedArray | 주어진 2 D의 점에 대응하는 비주얼 오브젝트를 식별한다.
Direct3DRMPicked2Array | 주어진 광선의 교선에 대응하는 비주얼 오브젝트를 식별한다.
Direct3DRMProgressiveMesh | “메쉬를 단계적으로 상세한 것으로 하는 방법을 기술하는 레코드”라고“엉성한 베이스 메쉬”로 구성된다. 이것은, 일반적인 레벨의 상세 항목을 메쉬상에서 세트함과 함께, 리모트 소스로부터의 메쉬를 단계적으로 다운로드하는 일도 가능하게 한다.
Direct3DRMShadow2 | 그림자를 정의한다. Direct3DRMShadow오브젝트와 같지만, 그림자의 프로퍼티를 설정하거나 생성 후에 취득할 수가 있다.
Direct3DRMTexture3 | 색이 붙은 픽셀이 직사각형에 줄서 구성된다. Direct3DRMTexture오브젝트와 같지만, 현재 실행하고 있는 파일 이외의 파일로부터 리소스를 로드 할 수 있어 텍스쳐는 메모리의 이미지로부터 생성 할 수 있어 또밉맵을 생성할 수 있는 점이 다르다. Direct3DRMTexture2오브젝트를 확장해, 텍스쳐 관리를 상세하게 실시할 수 있도록(듯이) 했다.
Direct3DRMUserVisual | 시스템이 제공하지 않는 기능을 실현한다. 어플리케이션에 의해 정의된다.
Direct3DRMViewport2 | 3 D신이 어떻게 2 D윈도우에 렌더링 되는지를 정의한다. Direct3DRMViewport오브젝트와 같지만, 클리어 하는 대상을 지정할 수 있다.
Direct3DRMVisual | 장면에 렌더링 할 수가 있다. 비주얼 오브젝트는 가시 상태가 아니어도 좋다. 예를 들어, 프레임을 비주얼 오브젝트로서 추가할 수도 있다.
Direct3DRMWrap | 면이나 메쉬의 텍스쳐 좌표를 계산한다.

많은 오브젝트는,배열 오브젝트로 불리는 배열에 그룹화 할 수가 있다. 배열 오브젝트에 의해, 그룹 전체에 조작을 적용하는 것이 용이하게 된다. 배열 오브젝트를 사용할 수 있는 COM(Component Object Model) 인터페이스에는,GetElement와GetSize메소드가 포함되어 있다. 이러한 메소드는, 배열 요소에의 포인터와 배열의 사이즈를 받는다. 배열 인터페이스의 상세한 것에 대하여는, 「인터페이스 레퍼런스」를 참조할것.

오브젝트와 인터페이스

IObjectName::QueryInterface는, 오브젝트가 그 인터페이스를 지원 하고 있는 경우만, 유효한 인터페이스에의 포인터를 취득한다. 따라서,IDirect3DRMDevice3::QueryInterface 를 사용해IDirect3DRMWinDevice 인터페이스를 받을 수 있지만,IDirect3DRMVisual 인터페이스를 받을 수 없다.

오브젝트명 | 지원 되는 인터페이스
Direct3DRMAnimation2 | IDirect3DRMAnimation2
Direct3DRMAnimationSet2 | IDirect3DRMAnimationSet2
Direct3DRMClippedVisual | IDirect3DRMClippedVisual , IDirect3DRMVisual
Direct3DRMDevice3 | IDirect3DRMDevice3 , IDirect3DRMWinDevice
Direct3DRMFace2 | IDirect3DRMFace2
Direct3DRMFrame3 | IDirect3DRMFrame3 , IDirect3DRMVisual
Direct3DRMInterpolator | IDirect3DRInterpolator
Direct3DRMLight | IDirect3DRMLight
Direct3DRMMaterial2 | IDirect3DRMMaterial2
Direct3DRMMesh | IDirect3DRMMesh , IDirect3DRMVisual
Direct3DRMMeshBuilder3 | IDirect3DRMMeshBuilder3 , IDirect3DRMVisual
Direct3DRMProgressiveMesh | IDirect3DRMProgressiveMesh , IDirect3DRMVisual
Direct3DRMShadow2 | IDirect3DRMShadow2 , IDirect3DRMVisual
Direct3DRMTexture3 | IDirect3DRMTexture3 , IDirect3DRMVisual
Direct3DRMUserVisual | IDirect3DRMUserVisual , IDirect3DRMVisual
Direct3DRMViewport2 | IDirect3DRMViewport2
Direct3DRMWrap | IDirect3DRMWrap

다음의 샘플에서는, 1개의Direct3DRMDevice3 오브젝트에 2개의 인터페이스를 생성하는 방법을 설명하고 있다. IDirect3DRM3::CreateObject 메소드는, 초기화되어 있지 않은Direct3DRMDevice3 오브젝트를 생성한다. 오브젝트의 초기화는,IDirect3DRMDevice3::InitFromClipper 메소드에 의해 행해진다. IDirect3DRMDevice3::QueryInterface 메소드의 호출은,Direct3DRMDevice3 오브젝트에의 2개째의 인터페이스(WM_PAINT 및 WM_ACTIVATE 메세지에의 응답시에 이용되는IDirect3DRMWinDevice 인터페이스)를 생성한다.

d3drmapi->CreateObject(CLSID_CDirect3DRMDevice, NULL,
    IID_IDirect3DRMDevice3, (LPVOID FAR*) &dev1);
dev1->InitFromClipper(lpDDClipper, IID_IDirect3DRMDevice3,
    r.right, r.bottom);
dev1->QueryInterface(IID_IDirect3DRMWinDevice, (LPVOID*) &dev2);

2개의 인터페이스가 동일한 오브젝트를 참조하고 있을지 어떨지를 판정하려면 , 각각의 인터페이스에 대해QueryInterface메소드를 사용해, 돌려주어지는 포인터의 값을 비교한다. 포인터의 값이 동일한 경우, 인터페이스는 같은 오브젝트를 참조하고 있다.

모든 Direct3D 보관 유지 모드 오브젝트는, 전술한 리스트중의 인터페이스에 가세해IDirect3DRMObject 인터페이스와IDirect3DRMObject2 인터페이스,IUnknown 인터페이스를 지원 하고 있다. IDirect3DRMObject는 배열 오브젝트를 제공하지 않는다. 배열 오브젝트는, 필요가 없기 때문에, 클래스 식별자(CLSID)를 가지고 있지 않다. IDirect3DRM3::CreateObject 메소드의 호출에서는, 배열 오브젝트를 생성 할 수 없다. 그 대신해, 각 인터페이스에 대해 이하의 생성 메소드를 사용한다.

배열 인터페이스 | 생성 메소드
IDirect3DRMAnimationArray | IDirect3DRMAnimationSet2::GetAnimations
IDirect3DRMDeviceArray | IDirect3DRM3::GetDevices
IDirect3DRMFaceArray | IDirect3DRMMeshBuilder3::GetFaces
IDirect3DRMFrameArray | IDirect3DRMPickedArray::GetPick , IDirect3DRMPicked2Array::GetPick 또는IDirect3DRMFrame3::GetChildren
IDirect3DRMLightArray | IDirect3DRMFrame3::GetLights
IDirect3DRMObjectArray | IDirect3DRMInterpolator::GetAttachedObjects
IDirect3DRMPickedArray | IDirect3DRMViewport2::Pick
IDirect3DRMPicked2Array | IDirect3DRMFrame3::RayPick
IDirect3DRMViewportArray | IDirect3DRM3::CreateFrame
IDirect3DRMVisualArray | IDirect3DRMFrame3::GetVisuals

오브젝트와 참조 카운트

오브젝트가 생성되면(자), 그참조 카운트가 인크리먼트(increment) 된다. 어플리케이션이 오브젝트의 아이를 생성 하거나 메소드가 오브젝트에의 포인터를 돌려주거나 할 때마다, 시스템은 그 오브젝트의 참조 카운트를 증가시킨다. 오브젝트는, 참조 카운트가 0이 될 때까지 삭제될 것은 없다. 오브젝트에 대한 조작이 완료하면(자),Release 메소드를 호출해, 참조 카운트를 반드시 감소 한다. 예를 들어,IDirect3DRM3::CreateMeshBuilder 을 호출해IDirect3DRMMeshBuilder3오브젝트를 생성 해,IDirect3DRMMeshBuilder3::GetFaces 를 호출해IDirect3DRMFaceArray오브젝트를 취득했다고 한다. 이 경우, 어플리케이션을 종료하기 전에,IDirect3DRMMeshBuilder3오브젝트의Release메소드를 호출해,IDirect3DRMFaceArray오브젝트의Release메소드도 호출한다. Release메소드를 호출하지 않으면 오브젝트는 적절히 릴리즈 되지 않고, 리소스가 낭비된다. 오브젝트를 릴리즈 하는 샘플에 대해서는, Direct3D 보관 유지 모드의 샘플 코드를 참조할것.

Direct3D 보관 유지 모드에는, 내부 참조 카운트와 외부 참조 카운트가 있다. 텍스쳐등의 오브젝트를 생성 또는 임포트 해, 프레임이나 메쉬등의 장면에 오브젝트를 적용 하면, 생성 또는 임포트 한 오브젝트의 인터페이스의 카피는 릴리즈 할 수 있다. 오브젝트를 사용하는 장면이 완료 하면, 그 오브젝트는 D3DRM에 의해 자동적으로 릴리즈 된다. 예를 들어, 메쉬 빌더 오브젝트를 생성 하면, 참조 카운트는 1에 세트 된다. 다음에, 오브젝트를 프레임에 추가 하면, 참조 카운트는 2에 세트 된다. 그 후, 메쉬 빌더 오브젝트에의 포인터의 카피를 릴리즈 하면, 메쉬 빌더 오브젝트의 참조 카운트는 1에 되돌려진다. 게다가 그 프레임을 포함한 장면을 릴리즈 하면, 메쉬 빌더 오브젝트의 참조 카운트는 감소 되어 0이 되어, 오브젝트가 릴리즈 된다. 이제(벌써) 1개예를 나타낸다. 텍스쳐를 임포트 하면, 텍스쳐 오브젝트의 참조 카운트는 1에 세트 된다. 텍스쳐를 메쉬에 적용 하면, 참조 카운트는 2가 된다. 텍스쳐 오브젝트에의 포인터의 카피를 릴리즈 하면, 참조 카운트는 1에 돌아온다. 메쉬를 릴리즈 하면, 텍스쳐 오브젝트의 참조 카운트는 감소 되어 릴리즈 된다.

장면에 적용한 다음에 오브젝트를 릴리즈 하면(자), 어플리케이션은 참조 카운트를 추적할 필요는 없고, 장면의 루트만 추적하면 좋다. 보관 유지 모드는 다른 참조 카운트를 자동적으로 추적한다. 이 경우, 클린 업이 완료해 어플리케이션을 종료하기 전에, 어플리케이션은, 장면, 뷰포트, 디바이스를 릴리즈 하는 것만으로 좋다. 어플리케이션이 뷰포트를 릴리즈 하면, 시스템은카메라의 참조 카운트를 자동적으로 조정한다.

아이 오브젝트나 비주얼 오브젝트의 참조 카운트는, 프레임에 추가될 때 늘려진다. IDirect3DRMFrame3::AddChild 메소드를 사용해, 어느 친오브젝트로부터 다른 부모에게 아이 오브젝트를 이동 하면, 시스템은 자동적으로 참조 카운트를 조작한다.

어플리케이션이 비주얼 오브젝트를 장면에 로드한 후는, 장면이 오브젝트의 참조 카운트를 관리한다. 어플리케이션에 있어서는, 비주얼 오브젝트는 이제(벌써) 불필요해져, 릴리즈 할 수가 있다.

랩의 생성과 적용은, 어느 오브젝트의 참조 카운트도 증가시키지 않다. 랩핑은, 단지 텍스쳐의 좌표를 계산할 뿐(만큼)의 편리한 메소드에 지나지 않기 때문이다.


개요

이 마디에서는, Microsoft® Direct3D® 보관 유지 모드를 다양한 관점으로부터 해설한다. 최초의 2개의 주제에서는, Direct3D 보관 유지 모드 인터페이스에 관한 일반 정보를 제공한다. 이 안에는, 계층도, 및 인터페이스의 이력과 버젼간의 차이를 상술하는 자료가 포함된다.

  • 인터페이스 계층
  • 인터페이스의 변경점

다음에, Direct3D 보관 유지 모드를 특정의 관점으로부터 설명한다. 각 인터페이스의 메소드에 대해서는, 대응하는 「레퍼런스」를 참조할것.

  • 장황한 상태 변경의 삭제
  • 프레임
  • 인타포레이타
  • 조명
  • 출력 디바이스
  • 텍스쳐
  • 뷰포트
  • 랩

Direct3D 보관 유지 모드 버젼 6에서는, 외부 비주얼의 지원이 추가되었다. 외부 비주얼은, Direct3D 보관 유지 모드 (D3DRM)의 계층에서 커스텀 hierarchy 오브젝트를 허가하는 메소드를 제공한다. 외부 비주얼은, COM 오브젝트이며,IDirect3DRMExternalVisual인터페이스 ( 및, 필요하게 응한 다른 인터페이스)를 지원 한다. D3DRM는, 이 오브젝트를 퍼스트 클래스 비주얼 오브젝트로서 취급해, 커스텀 렌더링, 피킹, 바운딩 박스 리포트등의 동작을 허가한다. D3DRM의 구버젼으로 지원 되고 있던 유저 비주얼은, 콜백 함수를 사용한 커스텀 렌더링 밖에 인정하지 않았지만, 거기에 비교하면(자) 외부 비주얼은 한층 강화되고 있다. 외부 비주얼은, 변형 가능한 메쉬나 인바스키네마틱소르바 등, 모든 타입의 비주얼 오브젝트를 D3DRM 비주얼 계층에 삽입하는 확장 기능을 제공한다.

외부 비주얼에는 D3DRM로부터 액세스 할 수도 있지만, 외부 비주얼은 DirectX 변환 인터페이스를 지원 하고 있으므로, DirectX Transform DXETool.exe에서도 사용할 수 있다. 이유는, DirectX Media SDK의 「DirectX Transform」로 설명한다. 외부 비주얼의 상세한 것에 대하여는, DirectX Media SDK의 「DirectX Transform」메뉴얼의 「레퍼런스」를 참조할것.


인터페이스 계층

 IUnknown
 |
 +--IDirect3DRM (교환)
 |
 +--IDirect3DRM2 (교환)
 |
 +--IDirect3DRM3
 |
 +--IDirect3DRMArray
 |  |
 |  +--IDirect3DRMAnimationArray
 |  |
 |  +--IDirect3DRMDeviceArray
 |  |
 |  +--IDirect3DRMFaceArray
 |  |
 |  +--IDirect3DRMFrameArray
 |  |
 |  +--IDirect3DRMLightArray
 |  |
 |  +--IDirect3DRMObjectArray
 |  |
 |  +--IDirect3DRMPicked2Array
 |  |
 |  +--IDirect3DRMPickedArray
 |  |
 |  +--IDirect3DRMViewportArray
 |  |
 |  +--IDirect3DRMVisualArray
 |
 +--IDirect3DRMObject
 |  |
 |  +--IDirect3DRMAnimation (교환)
 |  |
 |  +--IDirect3DRMAnimation2
 |  |
 |  +--IDirect3DRMAnimationSet (교환)
 |  |
 |  +--IDirect3DRMAnimationSet2
 |  |
 |  +--IDirect3DRMDevice (교환)
 |  |  |
 |  |  +--IDirect3DRMDevice2 (교환)
 |  |
 |  +--IDirect3DRMDevice3
 |  |
 |  +--IDirect3DRMFace2
 |  |
 |  +--IDirect3DRMInterpolator
 |  |
 |  +--IDirect3DRMLight
 |  |
 |  +--IDirect3DRMMaterial (교환)
 |  |
 |  +--IDirect3DRMMaterial2
 |  |
 |  +--IDirect3DRMViewport (교환)
 |  |
 |  +--IDirect3DRMViewport2
 |  |
 |  +--IDirect3DRMVisual
 |  |  |
 |  |  +--IDirect3DRMFrame (교환)
 |  |  |  |
 |  |  |  +--IDirect3DRMFrame2 (교환)
 |  |  |
 |  |  +--IDirect3DRMFrame3
 |  |  |
 |  |  +--IDirect3DRMMesh
 |  |  |
 |  |  +--IDirect3DRMMeshBuilder (교환)
 |  |  |  |
 |  |  |  +--IDirect3DRMMeshBuilder2 (교환)
 |  |  |
 |  |  +--IDirect3DRMMeshBuilder3
 |  |  |
 |  |  +--IDirect3DRMProgressiveMesh
 |  |  |
 |  |  +--IDirect3DRMShadow (교환)
 |  |  |
 |  |  +--IDirect3DRMShadow2
 |  |  |
 |  |  +--IDirect3DRMTexture (교환)
 |  |  |  |
 |  |  |  +--IDirect3DRMTexture2 (교환)
 |  |  |
 |  |  +--IDirect3DRMTexture3
 |  |  |
 |  |  +--IDirect3DRMUserVisual
 |  |
 |  +--IDirect3DRMWinDevice
 |  |
 |  +--IDirect3DRMWrap
 |
 +--IDirect3DRMObject2


인터페이스의 변경점

이 항에서는, Microsoft® Direct3D® 보관 유지 모드 인터페이스의 이력이라고 변경에 대해 설명한다. 연번이 붙어 있는 인터페이스의 명명 규칙에 대해 설명해, 구버젼 및 옮겨놓을 수 있었던 인터페이스의 리스트를 나타낸다. 게다가 새로운 인터페이스로 추가된 메소드, 및 종래부터의 인터페이스에 대해 추가된 메소드의 리스트도 가리킨다.

이 항에서는 다음의 항목에 대해 설명한다.

  • 연번 첨부의 인터페이스와 메소드
  • 새로운 인터페이스 및 옮겨놓을 수 있었던 인터페이스
  • 추가 및 변경된 메소드

연번 첨부의 인터페이스와 메소드

Direct3D 보관 유지 모드와 같은 COM (컴퍼넌트 오브젝트 모델) 시스템에서는, 새로운 메소드와 기능은, 연번을 붙인 새로운 인터페이스에 의해 제공된다. 예를 들어,IDirect3DRMFrame3인터페이스는,IDirect3DRMFrame2으로 개시된 것에 메소드를 추가해,IDirect3DRMFrame2은IDirect3DRMFrame로 개시된 것에 메소드를 추가한다.

DirectX 6.0으로부터, 새로운 Direct3D 보관 유지 모드 인터페이스는, 구버젼의 인터페이스로부터 계승되지 않게 되었다. 예를 들어, DirectX 5.0으로 도입된IDirect3DRMFrame2은,IDirect3DRMFrame 으로부터 직접 계승되지만, DirectX 6.0으로 도입된IDirect3DRMFrame3은,IDirect3DRMFrame2 이나 IDirect3DRMFrame 로부터 계승되지 않는다. 모든 Direct3D 보관 유지 모드 인터페이스의 관계를 나타내는 그림은, 「인터페이스 계층」을 참조할것.

DirectX 6.0으로부터, 새로운 Direct3D 보관 유지 모드 인터페이스는, 최신의 인터페이스 오브젝트에의 포인트 등, 입력 파라미터로서 최신 버젼을 요구한다. 구버젼의 인터페이스는 변경하고 있지 않기 때문에, 기존의 어플리케이션을 고쳐 쓸 필요는 없다. 예를 들어,IDirect3DRMFrame3 은,IDirect3DRMFrame2과IDirect3DRMFrame의 전기능을 제공하고 있다. IDirect3DRMFrame3::AddChild 는,IDirect3DRMFrame3인터페이스에의 포인터를 파라미터로서 받는다. 한편, 구버젼의 인터페이스의 메소드는, 파라미터로서IDirect3DRMFrame의 기본 인터페이스에의 포인터를 받는다. DirectX 6.0으로 도입된 인터페이스의 리스트는, 이 항의 「새로운 인터페이스 및 옮겨놓을 수 있었던 인터페이스」를 참조할것.

Direct3D 보관 유지 모드 라이브러리와 런타임에는, 구버젼과의 호환성을 유지하기 위해서(때문에), 낡은 인터페이스가 변경되지 않고 포함되어 있다. 그러나, 이 메뉴얼에서는 설명이 장황하게 안 되게, 최신의 인터페이스와 메소드만을 설명한다. 이 항에서는, 변경에 대해 넓게 설명한다. 각각의 인터페이스와 메소드에 관한 설명에서는, 버젼간의 변경점에 대해, 약간 한정적으로 설명한다. 구버젼의 인터페이스를 사용해도, 새로운 어플리케이션을 생성 할 수 있지만, 새로운 인터페이스를 사용해, 강화된 기능을 활용하는 것을 추천 한다.

DirectX 6.0 이전으로는, 새로운 Direct3D 보관 유지 모드 메소드는, 입력 파라미터로서 항상 기본 인터페이스 오브젝트를 받고 있었다. 새로운 메소드는, 출력 파라미터로서 새로운 인터페이스나 오브젝트를 돌려준다. 어느 메소드의 파라미터가 변경되었을 경우, 변경된 메소드의 이름은 연번을 붙일 수 있어 (예를 들어, 이름에"2"를 붙여), 새로운 인터페이스에 추가된다. 예를 들어,IDirect3DRMFrame::AddMoveCallback에는 2개의 파라미터가 있다. 기능을 확장하기 위해서, 파라미터를 추가한 새로운 버젼의 메소드는,IDirect3DRMFrame2::AddMoveCallback2와 같이, 연번을 붙인 새로운 인터페이스로 개시되었다. 그러나, DirectX 6.0으로부터는, 새로운 인터페이스는 낡은 인터페이스를 계승하지 않기 때문에, 변경한 메소드의 이름에 번호를 부가하는 방법은 불필요하게 되었다. 그 때문에 DirectX 6.0이후에서는, DirectX 5.0으로"2"를 붙인 Direct3D 보관 유지 모드 메소드의 이름으로부터, "2"가 삭제되고 있다. IDirect3DRMFrame2::AddMoveCallback2은IDirect3DRMFrame3::AddMoveCallback 에,IDirect3DRMMeshBuilder2::GenerateNormals2는IDirect3DRMMeshBuilder3::GenerateNormals 로 옮겨지고 있다.

새로운 인터페이스 및 옮겨놓을 수 있었던 인터페이스

다음의 리스트는, Microsoft DirectX® Software Development Kit (SDK) 버젼 6으로 새롭게 도입된 인터페이스를 나타내고 있다. 새로운 인터페이스와 옮겨놓을 수 있던 낡은 인터페이스도 가리키고 있다.
낡은 인터페이스 | 새로운 인터페이스
없음 | IDirect3DRMClippedVisual
없음 | IDirect3DRMAnimationArray
없음 | IDirect3DRMObject2
IDirect3DRM | IDirect3DRM3
IDirect3DRM2 | IDirect3DRM3
IDirect3DRMAnimation | IDirect3DRMAnimation2
IDirect3DRMAnimationSet | IDirect3DRMAnimationSet2
IDirect3DRMDevice | IDirect3DRMDevice3
IDirect3DRMDevice2 | IDirect3DRMDevice3
IDirect3DRMFrame | IDirect3DRMFrame3
IDirect3DRMFrame2 | IDirect3DRMFrame3
IDirect3DRMMaterial | IDirect3DRMMaterial2
IDirect3DRMMeshBuilder | IDirect3DRMMeshBuilder3
IDirect3DRMMeshBuilder2 | IDirect3DRMMeshBuilder3
IDirect3DRMShadow | IDirect3DRMShadow2
IDirect3DRMTexture | IDirect3DRMTexture3
IDirect3DRMTexture2 | IDirect3DRMTexture3
IDirect3DRMViewport | IDirect3DRMViewport2

추가 및 변경된 메소드

이하의 리스트는, 메소드와 인터페이스가 추가 또는 변경된 메소드와 버젼을 열기해, Direct3D 보관 유지 모드의 이력을 나타내고 있다. 3개(살) 이상의 버젼이 존재하는 경우 (IDirect3DRM3, IDirect3DRM2, IDirect3DRM등)는, 최초를 제외한 모든 버젼을 게재해, 버젼간의 기능 강화를 나타낸다. Direct3D 보관 유지 모드가 최초로 개발된 이후, 변경되어 있지 않은 인터페이스는 가리키지 않다. 인터페이스가 도입되었을 때의 DirectX SDK의 버젼은, 인터페이스명의 옆에 외모 쓰기로 가리킨다.

  • IDirect3DRM2 (DirectX 5.0. DirectX 6.0에서는 IDirect3DRM3에 치환)
    • CreateProgressiveMesh
  • IDirect3DRM3 (DirectX 6.0)
    • CreateDeviceFromSurface
    • GetOptions
    • RegisterClient
    • SetOptions
    • UnregisterClient
  • IDirect3DRMAnimation2 (DirectX 6.0)
    • AddKey
    • DeleteKeyByID
    • GetFrame
    • GetKeys
    • ModifyKey
  • IDirect3DRMAnimationArray (DirectX 6.0)
    • GetElement
    • GetSize
  • IDirect3DRMAnimationSet2 (DirectX 6.0)
    • GetAnimations
  • IDirect3DRMClippedVisual (DirectX 6.0)
    • AddPlane
    • DeletePlane
    • GetPlane
    • GetPlaneIDs
    • Init
    • SetPlane
  • IDirect3DRMDevice2 (DirectX 5.0. DirectX 6.0에서는 IDirect3DRMDevice3에 치환)
    • GetDirect3DDevice2
    • GetRenderMode
    • InitFromD3D2
    • InitFromSurface
    • SetRenderMode
  • IDirect3DRMDevice3 (DirectX 6.0)
    • FindPreferredTextureFormat
  • IDirect3DRMFrame2 (DirectX 5.0. DirectX 6.0에서는 IDirect3DRMFrame3에 치환)
    • AddMoveCallback2 (IDirect3DRMFrame3::AddMoveCallback 에 치환)
    • GetAxes
    • GetBox
    • GetBoxEnable
    • GetHierarchyBox
    • GetInheritAxes
    • GetMaterial
    • RayPick
    • Save
    • SetAxes
    • SetBox
    • SetBoxEnable
    • SetInheritAxes
    • SetMaterial
    • SetQuaternion
  • IDirect3DRMFrame3 (DirectX 6.0)
    • GetMaterialOverride
    • GetSceneFogMethod
    • GetTransform (IDirect3DRMFrame::GetTransform를 확장)
    • GetTraversalOptions
    • InverseTransformVectors
    • SetMaterialOverride
    • SetSceneFogMethod
    • SetTraversalOptions
    • TransformVectors
  • IDirect3DRMMaterial2 (DirectX 6.0)
    • GetAmbient
    • SetAmbient
  • IDirect3DRMMeshBuilder2 (DirectX 5.0. DirectX 6.0에서는 IDirect3DRMMeshBuilder3에 치환)
    • GenerateNormals2 (IDirect3DRMMeshBuilder3::GenerateNormals 에 치환)
    • GetFace
  • IDirect3DRMMeshBuilder3 (DirectX 6.0)
    • AddFacesIndexed
    • AddTriangles
    • CreateSubMesh
    • DeleteFace
    • DeleteNormals
    • DeleteSubMesh
    • DeleteVertices
    • Empty
    • Enable
    • GetEnable
    • GetNormal
    • GetGeometry (IDirect3DRMMeshBuilder::GetVertices에 치환)
    • GetNormalCount
    • GetNormals
    • GetParentMesh
    • GetSubMeshes
    • GetVertex
    • GetVertices (IDirect3DRMMeshBuilder::GetVertices의GetGeometry 를 참조)
    • Optimize
    • SetNormals
    • SetVertices
  • IDirect3DRMObject2 (DirectX 6.0)

    이 인터페이스는,IDirect3DRMObject 의 치환은 아니기 때문에 주의 해야 한다.

    • AddDestroyCallback
    • Clone
    • DeleteDestroyCallback
    • GetAge
    • GetClientData
    • GetDirect3DRM
    • GetName
    • SetClientData
    • SetName
  • IDirect3DRMShadow2 (DirectX 6.0)
    • GetLight
    • GetOptions
    • GetPlane
    • GetVisual
    • SetLight
    • SetOptions
    • SetPlane
    • SetVisual
  • IDirect3DRMTexture2 (DirectX 5.0. DirectX 6.0에서는 IDirect3DRMTexture3에 치환)
    • GenerateMIPMap
    • InitFromImage
    • InitFromResource2
  • IDirect3DRMTexture3 (DirectX 6.0)
    • Changed (IDirect3DRMTexture::Changed를 확장)
    • GetCacheOptions
    • GetSurface
    • SetCacheOptions
    • SetDownsampleCallback
    • SetValidationCallback
  • IDirect3DRMViewport2 (DirectX 6.0)
    • Clear (IDirect3DRMViewport::Clear를 확장)


장황한 상태 변경의 삭제

구버젼의 Microsoft® Direct3D® 보관 유지 모드에서는, 어느 호출로부터 다음의 호출까지 렌더링 상태와 조명 상태가 변경되지 않을 가능성이 있는 것을 고려하고 있지 않았다. 이 결과, 보관 유지 모드는 현재가와 같은 값을 설정하기 위해(때문에), 일반적인 어플리케이션으로 장황한 상태 변경이 다수 발생했다. IDirect3DRMDevice3 인터페이스에서는, 퍼포먼스를 향상시키기 (위해)때문에, 이러한 장황한 상태 변경을 해소하는GetStateChangeOptions ,LightStateChange ,RenderStateChange ,SetStateChangeOptions 메소드가 도입되었다. 이상의 메소드를 사용하려면 , 이하의 순서에 따른다.

  1. IDirect3DRMDevice3인터페이스의 2개의 메소드를 사용해, 장황 상태 변경 체크를 온으로 한다. 이것은, 렌더링 상태나 조명 상태를 변경하는 경우에, 통지하는 것을 나타낸다.
    Dev3->SetStateChangeOptions(D3DRMSTATECHANGE_RENDER, 0,
                            D3DRMSTATECHANGE_NONVOLATILE);
Dev3->SetStateChangeOptions(D3DRMSTATECHANGE_LIGHT, 0, D3DRMSTATECHANGE_NONVOLATILE);
  2. 실행 버퍼 또는 Draw Primitive 메소드로 렌더링 상태 또는 조명 상태를 변경하는 경우, 상태 캐쉬를 갱신하기 위해서, Direct3D 보관 유지 모드로 변경을 통지할 필요가 있다. 통지에는 2방법의 방법이 있다. 보관 유지 모드로 상태를 변경하는지 (장황한 변경은 방지한다), 상태를 새로운 값으로 변경한 것을 보관 유지 모드에 통지한다. 어느 쪽의 경우도LightStateChange 및RenderStateChange 메소드를 사용한다.

예를 들어, 다음의 코드는, 텍스쳐 핸들을 변경해, 상태 캐쉬를 갱신하는 방법을 나타내고 있다.

Dev3->RenderStateChange(D3DRENDERSTATE_TEXTUREHANDLE, hTex, 0UL);

상태를 변경해, 보관 유지 모드에 상태 캐쉬를 갱신시키려면 , UPDATEONLY 플래그를 다음과 같이 사용한다.

Dev3->RenderStateChange(D3DRENDERSTATE_TEXTUREHANDLE, hTex,
                        D3DRMSTATECHANGE_UPDATEONLY);

상태값을 몇번이나 변경하기 위해(때문에), 보관 유지 모드에 현재가를 추적시키고 싶지 않은 경우, 다음의 코드에 나타내도록(듯이), 지정한 상태에 대한 장황 상태 체크를 오프로 설정한다. 다만, 이 방법은 퍼포먼스가 향상하지 않기 때문에 추천 하지 않는다.

Dev3->SetStateChangeOptions(D3DRMSTATECHANGE_RENDER, D3DRENDERSTATE_TEXTUREHANDLE,
                            D3DRMSTATECHANGE_VOLATILE);


프레임

프레임이라고 하는 용어는, 오브젝트의 물리 프레임을 참조하고 있는 것에 유래하고 있다. 보관 유지 모드에 있어서의 프레임의 역할은, 윈도우 시스템에 있어서의 윈도우의 역할을 닮아 있다. 오브젝트는, 단지 월드 공간에 놓여지는 것이 아니라, 관련하는 참조 프레임과의 공간적인 릴레이션 쉽(상호 관계)을 기술하는 것에 의해 장면에 배치된다. 프레임은 오브젝트를 장면에 배치한다. 또, 비주얼 오브젝트를 표시할 경우에는, 프레임으로부터 위치나 방향을 취득한다.

보관 유지 모드의장면은, 친프레임을 가지지 않는 프레임이 정의한다. 즉, 프레임 계층의 최상정도 프레임이 정의한다. 또, 이 프레임은루트 프레임또는마스터 프레임으로 불리는 일도 있다. 장면은, 다른 모든 오브젝트에 대해서 참조 프레임을 정의한다. 장면의 생성은,IDirect3DRM3::CreateFrame 메소드를 호출해, 최초의 파라미터를 NULL로 지정해 실시할 수가 있다.

IDirect3DRMFrame3 인터페이스는,IDirect3DRMFrame2인터페이스의 확장이다. 또,IDirect3DRMFrame2는, 머트리얼, 경계 박스, 및 프레임 첨부의 축의 사용을 가능하게 하는 메소드를 갖추고 있다. IDirect3DRMFrame2는, 광선 픽도 지원 한다.

IDirect3DRMFrame3::SetAxes 및IDirect3DRMViewport2::SetProjection 메소드로,D3DRMPROJECTIONTYPE 구조체의 오른손 투영 타입을 사용해, 오른손 투영을 가능하게 할 수 있다.

관련 정보에 대해서는, 「IDirect3DRMFrame3 」를 참조할것.

이 항에서는, 프레임과 그 사용법에 대해 설명한다.

  • 계층
  • 변환
  • 운동(모션)
  • 콜백 함수

계층

장면의 프레임은 계층 구조가 되어 있다. 프레임은 친프레임이나 아이 프레임을 가질 수가 있다. 친프레임을 가지지 않는 프레임은루트 프레임으로 불려 장면을 정의한다.

아이 프레임은, 친프레임에 대해서 상대적인 위치와 방향을 나타내고 있다. 친프레임이 이동 하면, 아이 프레임도 이동한다.

프레임의 위치나 방향은, 장면 위에의 다른 프레임으로부터의 상대값으로 설정할 수가 있다. 절대 위치를 설정할 필요가 있는 경우는, 루트 프레임으로부터의 상대값을 사용할 수 있다. 또, 어느 친프레임으로부터 프레임을 삭제해,IDirect3DRMFrame3::AddChild 메소드에 의해, 언제라도 다른 프레임에 추가할 수가 있다. 아이 프레임을 완전하게 삭제하려면IDirect3DRMFrame3::DeleteChild 메소드를 사용한다. 아이 프레임이나 친프레임을 취득하려면 ,IDirect3DRMFrame3::GetChildren 및IDirect3DRMFrame3::GetParent 메소드를 사용한다.

프레임은, 다른 프레임의 비주얼 오브젝트로서 추가할 수 있어 주어진 계층 구조를, 장면 전체에 건너 몇번이나 이용하는 것이 가능하게 된다. 새로운 계층은인스턴스로 불린다. 퍼포먼스의 저하를 막기 위해, 친프레임을 아이 프레임에 넣지 않게 주의가 필요하다. 보관 유지 모드는, 실행시에 순회 계층의 체크를 실시하지 않는다. 순회 계층의 생성은,IDirect3DRMFrame3 인터페이스의 메소드에서는 하지 못하고, 프레임을 비주얼 오브젝트로서 추가할 경우에 마셔 가능하다.

변환

프레임의 위치나 방향은, 친프레임에의 상대적인 선형 변환이라고 생각할 수도 있다. 이 변환은 친프레임으로부터 아이 프레임에의 상대 벡터를 취득해, 친프레임에의 상대 벡터를 요구한다.

변환은 4×4 행렬로 나타낼 수가 있어 좌표는 4 요소의 행 벡터 [x, y, z,1] 으로 나타낼 수가 있다.

아이 프레임에 있어서의 좌표를vchild와 하면, 같은 좌표를 친프레임vparent로 나타내는 식은, 다음과 같이 정의된다.

Tchild는, 아이 프레임의 변환 행렬이다.

아이 프레임으로부터루트 프레임까지의 모든 친프레임의 변환은, 아이 프레임이 월드 좌표를 생성하는 변환과 연결시킬 수 있고 있다. 이 월드 변환은, 렌더링의 전에, 아이 프레임 위에의 비주얼 오브젝트에 대해서 적용된다. 아이 프레임에 대한 상대 좌표는,모델 좌표로 불리는 일이 있다. 월드 변환을 한 좌표는,월드 좌표로 불린다.

프레임의 변환은,IDirect3DRMFrame3::AddTransform ,IDirect3DRMFrame3::AddScale ,IDirect3DRMFrame3::AddRotation ,IDirect3DRMFrame3::AddTranslation 의 각 메소드에 의해, 직접 변경할 수가 있다. 각각의 메소드에는D3DRMCOMBINETYPE 열거형의 멤버를 건네주어, 어떻게 어플리케이션이 제공한 행렬을 현재의 프레임의 행렬과 합성하는지를 지정한다.

IDirect3DRMFrame3::GetRotation 와IDirect3DRMFrame3::GetTransform 메소드는, 프레임의 회전축과 변환 행렬을 취득한다. 프레임의 회전을 변경하려면 ,IDirect3DRMFrame3::SetRotation 메소드를 이용한다.

월드 좌표와 모델 좌표를 변환하려면 ,IDirect3DRMFrame3::Transform 와IDirect3DRMFrame3::InverseTransform 메소드를 사용한다.

변환의 한층 더 일반적인 설명은, 뷰포트만을 취급한 항 「변환」에 있다. 변환의 수학의 개요에 대해서는, 「3 D변환」을 참조할것.

운동(모션)

각 프레임은 고유의 회전이나 속도로 움직인다. 회전도 이동도 하지 않는 프레임에서는, 이러한 속성은 0이다. 이러한 속성은, 장면을 렌더링 해 오브젝트를 움직이기 전에 사용되어 단순한 애니메이션을 생성 할 수도 있다.

콜백 함수

프레임은, 보다 복잡한 애니메이션을 실현하기 (위해)때문에, 콜백 함수를 지원 하고 있다. 어플리케이션이 등록한 콜백 함수는, 모션 속성이 적용되기 전에 프레임으로부터 불려 간다. 계층에 복수의 프레임이 있어, 각각이 콜백 함수에 관련지을 수 있고 있는 경우는, 아이 프레임의 전에 친프레임이 불려 간다. 이러한 계층에서는, 콜백 함수의 모든 것이 불려 갈 때까지, 렌더링은 실행되지 않는다.

콜백 함수를 추가하려면 ,IDirect3DRMFrame3::AddMoveCallback 메소드를 사용한다. 콜백 함수를 삭제하려면 ,IDirect3DRMFrame3::DeleteMoveCallback 메소드를 사용한다.

이러한 콜백 함수를 이용하면(자), 프로그램 끝난 애니메이션 순서에 새로운 위치나 방향을 설정하거나 장면 위에의 다른 오브젝트의 위치에 의해 비주얼 오브젝트의 동작을 동적으로 인플리맨트 할 수가 있다.


인타포레이타

인타포레이타는, 액션을 저장 한 후, 중간값을 자동 계산해 오브젝트에 액션을 적용하는 방법을 제공한다. 예를 들어, 유저는 시간 0으로 빨강을, 시간 10으로 초록을 장면의 배경색에 세트 할 수가 있다. 그 후, 인타포레이타는 자동적으로, 연속하는 장면에 색조를 붙여 빨강으로부터 초록에 혼합하도록 할 수 있다. 인타포레이타를 사용해, 색을 혼합해, 다른 위치간에서 오브젝트를 원활히 이동해, 메쉬를 morphing 해, 또 다른 다양한 변환도 실시할 수가 있다.

Direct3D 보관 유지 모드 이행에서는, 인타포레이타는, 유저가 아니메이트 할 수 있는 오브젝트 파라미터의 종류를 증가시키는IDirect3DRMAnimation2 인터페이스의 일반화이다. IDirect3DRMAnimation2인터페이스가 오브젝트의 위치, 사이즈, 및 방향의 애니메이션을 가능하게 하는 한편으로,IDirect3DRMInterpolator 인터페이스는 또한 색, 메쉬, 텍스쳐, 및 머트리얼의 애니메이션을 enable로 한다.

이 항에서는, 다음의 항목에 대해 설명한다.

  • 인타포레이타키
  • 인타포레이타타이프
  • 인타포레이타의 예
  • 인타포레이타가 지원 하는 메소드
  • 인타포레이타인젝스스판
  • 보간 옵션

인타포레이타키

인타포레이타가 저장 하는 액션은, 키로 불린다. 키는, 저장 된 프로시저 호출로, 거기에 관련한 인덱스를 가진다. 인타포레이타는, 자동적으로 중간의 키값을 계산한다.

지원 되고 있는 인타포레이트 가능한 인터페이스 메소드의 하나를 호출해, 키를 인타포레이타안에 저장 한다. 메소드와 메소드에게 건네지는 파라미터값이 키를 구성한다. 「인타포레이타가 지원 하는 메소드」에, 지원 되고 있는 메소드의 일람이 있다.

인타포레이타 내부에 저장 되고 있는 각 키에는, 인덱스값이 있다. 키가 기록될 때, 키에는, 현재의 인타포레이타인젝스값의 스탬프가 밀린다. 이 키의 인덱스값은, 이 값을 일단 설정 하면 절대로 변할 것은 없다.

인타포레이타타이프

오브젝트는, 관련 타입의 인타포레이타에 접속할 수가 있다. 예를 들어, Mesh는, MeshInterpolator에 접속할 수 있다. 인타포레이타에는, 이하의 타입이 있다.

  • FrameInterpolator
  • LightInterpolator
  • MaterialInterpolator
  • MeshInterpolator
  • TextureInterpolator
  • ViewportInterpolator

어느 인타포레이타를 다른 인타포레이타에 접속하는 일도 가능하다. 인타포레이타의 인덱스를 변경 하면, 임의의 접속하는 앞의 인타포레이타의 인덱스에 같은 값을 세트 하게 된다.

MeshInterpolators의 경우, MeshInterpolator 오브젝트의IDirect3DRMMesh 인터페이스상에서,SetVertices 를 호출하는 것에 의해, MeshInterpolator 오브젝트에SetVertices키를 추가하는 것에 주의한다. SetVertices로 사용되는 그룹 인덱스는, Mesh 오브젝트 또는 인타포레이타가 적용되는 오브젝트중의 유효한 그룹 인덱스에 대응해야 한다.

인타포레이타의 예

예로서 프레임의 위치를 보간 하고 싶은 경우를 생각한다. 이 경우, 2개의 인터페이스IDirect3DRMInterpolator 및IDirect3DRMFrame3 를 가지는 FrameInterpolator 오브젝트가 필요하게 된다.

pd3drm->CreateObject(CLSID_CDirect3DRMFrameInterpolator, 0,

     IID_IDirect3DRMInterpolator, &pInterp);
pInterp->QueryInterface(IID_IDirect3DRMFrame3, &pFrameInterp);

위치 키를 인타포레이타에 추가하려면 ,IDirect3DRMInterpolator::SetIndex 를 호출해 인타포레이타의 내부 인덱스를 설정해,IDirect3DRMFrame3 인터페이스의SetPosition 메소드를 호출해 그 위치를 기록한다. 이 메소드는, 실제의 프레임은 아니고, 인타포레이타에 적용된다. 함수 호출과 그 파라미터가, 현재의 인덱스 첨부의 새로운 키로서 저장 된다.

pInterp->SetIndex(keytime);
pFrameInterp->SetPosition(NULL, keypos.x, keypos.y, keypos.z);

1개또는 복수의 오브젝트의 메소드가, 후에 계속되는IDirect3DRMInterpolator::SetIndex 를 사용해 인덱스를 설정하는 처리를 반복하는 것에 의해, 복수의 키를 추가할 수가 있다. 실제의 프레임을 개입시켜 역방향으로 액션을 재생하려면 , 그 프레임을 인타포레이타에 접속한다.

pInterp->AttachObject(pRealFrame);

여기서,IDirect3DRMInterpolator::Interpolate 를 호출해, 보간 된 위치를 사용해pRealFrame의 위치를 세트 한다.

pInterp->Interpolate(time, NULL,

      D3DRMINTERPOLATIONSPLINE | D3DRMINTERPOLATION_OPEN);

인타포레이타는, 가장 가까운SetPosition 키 끼리를(이 경우, B스플라인을 사용해) 보간 해 산출한 위치를 건네주어, 접속되고 있는 프레임의SetPosition메소드를 호출한다.

또는, 직접 형식의Interpolate 를 사용해, 오브젝트를 2번째의 파라미터로서 건네줄 수가 있다. 이 조작은, 접속되고 있는 오브젝트의 모두에게 우선한다.

pInterp->Interpolate(time, pRealFrame, D3DRMINTERPOLATIONSPLINE | D3DRMINTERPOLATION_OPEN);

같은 인타포레이타를 사용해 방향, 스케일, 속도, 및 컬러 키등의 다른 키를 저장 할 수가 있다. 각 프로퍼티는, 평행의 타임 라인상에 존재해,Interpolate 의 호출은, 각 프로퍼티의 보간 된 값이 접속되고 있는 프레임에 할당한다.

복수의 메소드를 보간 하는 일도 가능하다. 예를 들어,SetGroupColor및SetVertices의 각 키를 같은 인타포레이타에 저장 하는 일도 가능하다. 다른 메소드의 키 끼리를 보간 할 수 없기 때문에, 키 최인으로 불리는 병행 실행 thread에 저장 된다. 또,SetGroupColor(0, black) 및SetGroupColor(2, white)등의 다른 그룹으로부터 2개의 키를 지정하는 경우는, 키가 다른 그룹에 적용되므로, 인타포레이타가SetGroupColor(1, gray)의 중간 액션을 생성하는 것은 무의미하다. 이 경우, 키는 별개의 최인에도 저장 된다.

인타포레이타가 지원 하는 메소드

뷰포트

SetFront (value)
SetBack (value)
SetField (value)
SetPlane (left, right, bottom, top)

프레임

SetPosition (reference*, x, y, z)
SetRotation (reference*, x, y, z, theta)
SetVelocity (reference*, x, y, z, withRotation*)
SetOrientation (reference*, dx, dy, dz, ux, uy, uz)
SetColor (color)
SetColorRGB (red, green, blue)
SetSceneBackground (color)
SetSceneBackgroundRGB (red, green, blue)
SetSceneFogColor (color)
SetSceneFogParams (start, end, density)
SetQuaternion (reference*, quat)

메쉬

Translate (x, y, z)
SetVertices (group*, index*, count*, vertices)
SetGroupColor (group*, color)
SetGroupColorRGB (group*, red, green, blue)

라이트

SetColor (color)
SetColorRGB (red, green, blue)
SetRange (value)
SetUmbra (value)
SetPenumbra (value)
SetConstantAttenuation (value)
SetLinearAttenuation (value)
SetQuadraticAttenuation (value)

텍스쳐

SetDecalSize (width, height)
SetDecalOrigin (x, y)
SetDecalTransparentColor (color)

머트리얼

SetPower (value)
SetSpecular (red, green, blue)
SetEmissive (red, green, blue)

*(은)는, 이 파라미터에 대해서 다른 값의 키가 다른 최인에 삽입되는 것을 나타낸다.

지원되어 있지 않은 키를 설정하려고 하면(자), 치명적이지 않지만, D3DRMERR_BADOBJECT 에러의 원인이 된다.

인타포레이타인젝스스판

인타포레이타는, 어느 범위의 인덱스값을 받아들인다. 이 인덱스의 범위는, 이하의 규칙에 의해 지시받는다.

  • 범위의 시점은, 모든 키인덱스값과 현재의 인덱스안의 최소 값이다.
  • 범위의 종점은, 모든 키인덱스값과 현재의 인덱스안의 최대치이다.

보간 옵션

IDirect3DRMInterpolator::Interpolate 의d3drmInterpFlags파라미터에, 다음의 옵션으로부터 1개이상을 지정해, 보간을 실행한다.

  • D3DRMINTERPOLATION_CLOSED
  • D3DRMINTERPOLATION_LINEAR
  • D3DRMINTERPOLATION_NEAREST
  • D3DRMINTERPOLATION_OPEN
  • D3DRMINTERPOLATION_SLERPNORMALS
  • D3DRMINTERPOLATION_SPLINE
  • D3DRMINTERPOLATION_VERTEXCOLOR

인타포레이타가 CLOSED로 실행되는 경우, 보간은 순환적으로 된다. 키는, 실제로는, 인덱스 범위에 동일한 시간에 영원히 반복해진다. 애니메이션과의 호환성을 취하기 위해서(때문에), 인덱스 범위의 종점에 동일한 인덱스의 키는, 모두 무시된다.

보간이 OPEN의 경우에는, 각 키 최인의 최초와 마지막 키가 인덱스 범위외의 보간값을 수정한다.

NEAREST, LINEAR, SPLINE 옵션은, 각 키 최인으로 보간이 어떻게 행해지는지를 지정한다. 중간값은 키 최인간의 값으로부터 계산되어 키 데이터의 포인트를 매끄럽게 결합한다. NEAREST가 지정되면(자), 제일 가까운 키의 값이 사용된다. LINEAR는, 선형 보간을 2개의 가장 가까운 키의 사이에 실시한다. SPLINE는, B스플라인 혼합 함수를 4개의 가장 가까운 키에 대해서 사용한다.

다음의 2개의 옵션은,IDirect3DRMMesh::SetVertices 의 보간인 만큼 영향을 준다.

  • VERTEXCOLOR는, 버텍스의 색을 보간 하도록(듯이) 지정한다.
  • SLERPNORMALS는, 버텍스의 법선이 구(공)면보간 되도록(듯이) 지정한다(현재미이행).


조명

장면을 리얼하게 보이게 하기 위해서(때문에)는, 조명 효과를 이용한다. 시스템은, 장면의 조명에 대한 오브젝트의 방향에 근거해, 모든 오브젝트를 채색 한다. 오브젝트의 색은, 렌더링중에 각 조명의 영향을 고려해 결정된다. 모든 조명은 색과 휘도(Luminance)를 가지고 있어 따로 따로 변화시킬 수가 있다.

어플리케이션은 프레임에 빛을 Attach 해, 장면에 조명을 줄 수가 있다. 프레임에 Attach 된 빛은, 장면 위에의 비주얼 오브젝트를 밝게 한다. 프레임은, 빛의 위치와 방향의 양쪽 모두를 제공한다. 바꾸어 말하면, 빛은 Attach 된 프레임의 원점으로부터 퍼져 간다. 어플리케이션은, 조명이 Attach 된 프레임을 움직이거나 회전하는 것에 의해, 조명의 이동이나 방향 전환을 간단하게 실현될 수가 있다.

각 뷰포트는, 1개또는 복수의 조명을 소유한다. 조명이, 복수의 뷰포트에 의해 소유될 것은 없다.

현재 상태로서는, 보관 유지 모드는,앰비언트(환경빛),디렉셔널,패러럴 포인트,포인트,spotlight의 5 종류의 조명을 제공하고 있다.

IDirect3DRMLight인터페이스의 메소드의 레퍼런스는, 「IDirect3DRMLight 」를 참조할것.

이 섹션에서는, Direct3D로 이용할 수가 있는 조명 효과와 그 사용법에 대해 설명한다.

  • 앰비언트(환경빛)
  • 디렉셔널
  • 패러럴 포인트
  • 포인트
  • spotlight

앰비언트

앰비언트조명은, 오브젝트의 향해, 위치, 표면의 특성등과 관계없이, 장면 위에의 모든 것을 비추는 빛이다. 장면의 모든 장소를 같은 광도로 비추기 (위해)때문에, Attach 된 프레임의 위치나 방향은 중요하지 않다. 1개의 장면에는, 복수의 앰비언트 라이트가 결합되고 있다.

디렉셔널

디렉셔널(유향) 조명은 방향을 가지지만, 위치는 가지고 있지 않다. 프레임에 Attach 되면(자) 모든 오브젝트를 같은 휘도(Luminance)로 비추어, 조명이 오브젝트로부터 쭉 멀어진 위치에 있는 것 같은 효과를 준다. 디렉셔널 조명은, 태양과 같이 멀게 떨어진 조명을 시뮬레이트 하기 위해서 이용된다.

패러럴 포인트

패러럴 포인트조명은 패러럴 라이트로 오브젝트를 비추지만, 빛의 방향은 광원의 위치로부터 결정된다. 즉, 패러럴 포인트 조명에는 디렉셔널 조명과 같이 방향이 있어, 한층 더 위치도 가지고 있다. 예를 들어, 패러럴 포인트 조명의 양측으로 메쉬가 있는 경우, 조명에 접하고 있는 편의 메쉬가 밝아진다. 패러럴 포인트 조명의 렌더링 스피드는, 디렉셔널 조명과 동등하다.

포인트

포인트조명은, 광원으로부터 방사상에 미츠루를 추방한다. 빛이 맞는 면이나 법선의 각각 붙어, 새로운 빛의 벡터를 계산할 필요가 있기 (위해)때문에, 패러럴 포인트 조명보다 계산 시간이 걸린다. 그러나, 보다 정확한 조명 효과를 실현될 수 있으므로, 리얼한 표시가 요구되는 경우에 이용해야 하는 것이다.

spotlight

spotlight조명은 원추형의 빛을 생성한다. 빛은, 원추의 내부에 있는 오브젝트에게만 맞힐 수 있다. 원추는 2개의 휘도(Luminance)를 생성한다. 중앙의 밝은 부분(명부)은 포인트 조명과 같은 기능을 해, 주위의 어슴푸레한 부분(암영부)은, 그 주변의 어두운 그림자와 머지 된다. 이 2개의 부분의 각도는,IDirect3DRMLight::GetPenumbra ,IDirect3DRMLight::GetUmbra ,IDirect3DRMLight::SetPenumbra , 및IDirect3DRMLight::SetUmbra 에 의해 각각으로 지정할 수가 있다.

암영부의 각도, 명부의 각도, 및 명부의 원추


출력 디바이스

렌더링 된 모든 출력 형식은, 출력 디바이스와 관련하고 있지 않으면 안 된다. 디바이스 오브젝트는, 렌더링의 출력처의 가시 디스플레이를 나타내고 있다.

디바이스 오브젝트는, 렌더링의 출력처의 가시 디스플레이를 나타내고 있다. 렌더링의 동작은, 지정된 출력 디바이스의 타입에 의존한다. 디바이스에 복수의 뷰포트를 정의해, 동시에 표시되는 장면에 다른 시점을 줄 수도 있다. 또, 디바이스는 몇개에서도 지정할 수 있어 같은 장면에 복수의 출력처를 준비하는 일도 가능하다.

보관 유지 모드는, 스크린이나 윈도우, 또는 어플리케이션 메모리에 직접 렌더링 하는 디바이스를 지원 한다.

어플리케이션은,IDirect3DRMDevice3 ,IDirect3DRMDevice2,IDirect3DRMDevice인터페이스를 사용해, 출력 디바이스라고 대화한다. 상세한 것에 대하여는 「IDirect3DRMDevice3 」를 참조할것.

이 섹션에서는, Direct3D 이미지를 출력 디바이스에 표시할 때에 유효한 옵션에 대해 설명한다.

  • 퀄리티
  • 컬러 모델
  • 윈도우 관리

퀄리티

장면이나 그 원가요소는, 출력 디바이스에 의해, 리얼의 정도를 여러가지로 바꾸어 렌더링 할 수가 있다. 렌더링 퀄리티란, 디바이스의 렌더링 표면상에서 실행되는 렌더링의 퀄리티의 최대치이다. 메쉬, 프로그래시브 메쉬 및 메쉬 빌더 오브젝트에서도, 렌더링 퀄리티를 지정할 수가 있다.

디바이스 또는 오브젝트의 퀄리티에는, 3개의 컴퍼넌트가 있다. 즉, 쉐이딩 모드 (플랫 또는 굿 로로, 폰은 이행되어 있지 않다. 디폴트는 gouraud shading), 조명 타입 (온 또는 오프) 및 전부 칠해 모드 (포인트, 와이어 프레임 또는 솔리드)이다.

IDirect3DRMDevice3::SetQuality 메소드를 이용해, 디바이스의 퀄리티를 설정한다. 디폴트로, 디바이스 퀄리티는 D3DRMRENDER_FLAT (flat shading, 조명 온 및 솔리드 전부 칠해)이다.

Direct3DRMProgressiveMesh, Direct3DRMMeshBuilder3 또는 Direct3DRMMeshBuilder3 오브젝트의 퀄리티는, 각각의SetQuality메소드, 즉IDirect3DRMProgressiveMesh::SetQuality ,IDirect3DRMMeshBuilder3::SetQuality , 및IDirect3DRMMeshBuilder3::SetQuality를 이용해 설정할 수가 있다. 디폴트로, 이러한 오브젝트의 퀄리티는 D3DRMRENDER_GOURAUD (gouraud shading, 조명 온 및 솔리드 전부 칠해)이다.

힌트: gouraud shading를 사용 하면, 상세 레벨을 고속으로 변경하는 프로그래시브 메쉬 오브젝트의 퍼포먼스가 향상한다.

Direct3D 보관 유지 모드는, 디바이스나 오브젝트의 각각의 컴퍼넌트에 대한 현재의 설정 중에서 가장 저위의 퀄리티로, 오브젝트에 렌더링을 실시한다. 예를 들어, 오브젝트의 현재의 퀄리티 설정이 D3DRMRENDER_GOURAUD로, 디바이스가 D3DRMRENDER_FLAT이라고, 오브젝트는 flat shading, 솔리드 전부 칠해 및 조명 온으로 렌더링 된다.

오브젝트의 현재의 퀄리티 설정이 D3DRMSHADE_GOURAUD|D3DRMLIGHT_OFF|D3DRMFILL_WIREFRAME로, 디바이스의 퀄리티 설정이 D3DRMSHADE_FLAT|D3DRMLIGHT_ON|D3DRMFILL_POINT이라고, 오브젝트는 flat shading, 조명 오프 및 포인트 전부 칠해 모드로 렌더링 된다.

이러한 룰은, Direct3DRMMeshBuilder3 오브젝트 및 Direct3DRMProgressiveMesh 오브젝트에 적용된다. 그러나, Direct3DRMMesh 오브젝트는 이러한 룰에 따르지 않다. 메쉬 오브젝트는 디바이스의 퀄리티 설정을 무시해, 그룹 퀄리티 설정을 이용한다(디폴트로 D3DRMRENDER_GOURAUD).

컬러 모델

보관 유지 모드는, RGB 모델과 흑백(램프) 모델의 2개의 컬러 모델을 지원 한다. 컬러 모델을 취득하기 위해서는, 어플리케이션으로부터IDirect3DRMDevice3::GetColorModel 메소드를 사용한다.

RGB 모델은, 색을 적, 초록, 파랑의 빛의 편성으로서 취급해, 색이 붙은 복수의 조명을 지원 한다. 장면에서 사용되는 색 가지수에는 제한이 없다. 이 모델은, 8, 16, 24, 32 비트의 디스플레이로 이용할 수가 있다. 디스플레이의 표시 가능 색 가지수가 24 비트보다 적으면 색해상도의 제한에 의해 계단상에 계조가 변화하는 것이 눈에 띄는 밴딩(마하 밴드라고도 부른다)이 발생하는 경우가 있다. 이것은, 옵션의 dither 처리를 이용하는 것으로 회피할 수가 있다.

흑백 모델에서도 복수의 조명은 지원 되지만, 그 색요소는 무시된다. 각각의 조명은, 회색의 광도로 설정된다. 버텍스의 RGB 컬러는 휘도(Luminance)로서 해석된다. 다른 밝음으로 버텍스의 사이의 휘도(Luminance)가(gouraud shading 모드에서는) 보간 된다. 흑백 모델에서는, 장면 위에의 오브젝트의 색 가지수가 제한된다. 시스템 팔레트의 빈엔트리를 모두 쓰여지면(자), 시스템 내부의 팔레트 매니저는, 지정된 색에 가장 가까운 색을 팔레트내로부터 찾는다. 흑백 모델은, RGB 모델과 같게, 8, 16, 24, 32 비트의 디스플레이로 사용할 수가 있다(다만, 흑백 모델은 8 비트의 텍스쳐 밖에 지원 하지 않는다). RGB 모델 대신에 흑백 모델을 사용하는 이점은, 퍼포먼스가 꽤 향상하는 것이다.

Direct3D 디바이스의 컬러 모델은, 변경할 수가 없다. 어플리케이션은, 필요한 컬러 모델을 지원 한 드라이버를 식별하기 위해서,IDirect3D::EnumDevices 메소드나IDirect3D::FindDevice 메소드를 사용해, 디바이스 생성 메소드 중(안)에서 그 드라이버를 지정하지 않으면 안 된다.

팔레트는 텍스쳐, 오프 스크린 표면 및 오버레이 표면으로 지원 되고 있어 프라이머리 표면과 동일한 팔레트일 필요는 없다. 디바이스가 4 비트 인덱스 첨부 팔레트 (16색)를 지원 해, 8 비트 인덱스 첨부 작품 (256색)이 있는 경우, 보관 유지 모드는 팔레트로부터 최초의 16 엔트리를 꺼내 재맵핑을 실시해, 4 비트로서 작품의 렌더링을 실시한다. 따라서, 가능하면 바람직한 16색을 팔레트의 처음의 부분에 배치 하면이야 있고.

윈도우 관리

올바른 조작을 실시하기 위해서(때문에), operating system로부터 WM_MOVE나 WM_PAINT, WM_ACTIVATE 메세지를 받아들였을 때, 어플리케이션은,IDirect3DRMWinDevice::HandlePaint 및IDirect3DRMWinDevice::HandleActivate 메소드를 사용해 Direct3D에 통지하지 않으면 안 된다.

관련 정보에 대해서는, 「IDirect3DRMWinDevice 」를 참조할것.


텍스쳐

텍스쳐는, 색첨부의 픽셀이 직사각형에 줄선 것이다(직사각형은 반드시 정방형이 아니어도 좋지만, 시스템이 가장 효율적으로 동작하는 것은 정방형의 경우이다). 텍스쳐는 텍스쳐 맵핑의 면으로서 사용할 수도 있지만, 이 경우는 정방형이 아니면 안 된다.

어플리케이션은,D3DRMIMAGE 구조체로부터 텍스쳐를 생성 하기 위해서,IDirect3DRM3::CreateTexture 메소드를 사용할 수 있다. 또,IDirect3DRM3::CreateTextureFromSurface 메소드에 의해 DirectDraw 표면으로부터 텍스쳐를 생성 할 수도 있다. 게다가IDirect3DRM3::LoadTexture 메소드를 이용하면(자), 파일로부터 텍스쳐를 로드할 수가 있다. 이 경우, 텍스쳐는 Microsoft® Windows®의 비트 맵(. bmp)인가, 포타브르피크스맙포맛트(. ppm)가 아니면 안 된다. 텍스쳐를 생성 할 경우에 불필요한 지연을 피하기 (위해)때문에, 재이용하는 텍스쳐는 보관 유지하도록(듯이) 해, 필요하게 될 때마다 생성 하지 않아도 되도록(듯이) 한다. 최적인 퍼포먼스를 얻으려면 , 사용하는 디바이스의 지원 하는 텍스쳐 표면 포맷을 사용한다. 이것에 의해, 텍스쳐를 생성 한 다음에 그것이 변경될 때, 수고가 걸리는 포맷 변환을 회피할 수가 있다. 텍스쳐가 16색이하로 구성되어 있는 경우, 4 비트로 팔레트화한 표면 포맷을 사용해, 하드웨어 디바이스의 비디오 메모리 사용량을 줄인다.

각면의 텍스쳐 좌표는, 그 특정의 면에 맵핑 되는 텍스쳐의 리젼을 정의하고 있다. 어플리케이션은, 텍스쳐 좌표를 계산하기 위해서 랩을 이용할 수가 있다. 상세 정보는, 「랩」을 참조할것.

IDirect3DRMTexture3인터페이스는, (IDirect3DRMTexture인터페이스의 확장이다)IDirect3DRMTexture2인터페이스의 확장이다.

텍스쳐는, 우측을 위로 해IDirect3DRMTexture3::InitFromFile , ,IDirect3DRMTexture3::InitFromResource2 , 및IDirect3DRMTexture2인터페이스에서의 같은 메소드로, BMP와 DIB(디바이스 독립 비트 맵) 파일로부터 로드 된다. 이것은, 반전된 로드 되는IDirect3DRMTexture::InitFromFile및IDirect3DRMTexture::InitFromResource2와는 다르다.

이러한 인터페이스의 메소드에 대해서는, 「IDirect3DRMTexture3 」를 참조할것.

이 항에서는, Direct3D가 지원 하는 텍스쳐의 종류와 사용법을 설명한다.

  • 디칼
  • 텍스쳐의 색
  • 밉맵
  • 텍스쳐 필터링
  • 텍스쳐의 투명화
  • 텍스쳐 포맷 선택 룰

디칼

텍스쳐는, 비주얼 오브젝트로서 직접 렌더링 할 수가 있다. 이와 같이 이용되는 텍스쳐는,디칼로서 알려져 있다. 디칼과는 보관 유지 모드로 채용된 용어이다. 디칼은, 뷰포트와 일치한 직사각형에 렌더링 된다. 이 직사각형은, 옵션으로서 디칼의 입체 위치에 의한 스케일링이 가능하다. IDirect3DRMTexture3::SetDecalSize 메소드를 사용 하면, 프레임에 대해서 상대적으로 정의된 직사각형으로부터 디칼의 사이즈를 설정할 수가 있다(어플리케이션은,IDirect3DRMTexture3::GetDecalSize 메소드에 의해 디칼의 사이즈를 알 수 있다). 그 후, 디칼은 변환되어 투시 투영 된다.

디칼의 원점은, 어플리케이션으로부터 설정 및 취득할 수가 있다. 이것에는IDirect3DRMTexture3::SetDecalOrigin 및IDirect3DRMTexture3::GetDecalOrigin 메소드를 이용한다. 원점은, 디칼의 좌상구석으로부터의 오프셋(offset)로 나타내진다. 디폴트의 원점은[0, 0]이다. 렌더링 시에는, 디칼의 원점은 프레임의 위치에 맞출 수 있다.

텍스쳐의 색

텍스쳐의 렌더링으로 이용되는 색 가지수의 취득이나 설정을 실시하려면 ,IDirect3DRMTexture3::SetColors 및IDirect3DRMTexture3::GetColors 메소드를 이용한다.

RGB색모델을 이용하는 어플리케이션에서는, 8 비트, 24 비트, 32 비트의 텍스쳐를 사용할 수가 있다. 그러나, 흑백 (램프) 컬러 모델을 이용하는 경우에는, 8 비트의 텍스쳐만 사용할 수 있다.

장면에 빛을 적용 하면 와, 각각의 색의 그림자가 사용된다. 사용되고 있는 그림자의 수의 설정이나 취득을 실시하려면 , 어플리케이션으로부터IDirect3DRMTexture3::SetShades 및IDirect3DRMTexture3::GetShades 메소드를 호출한다.

Direct3DRMTexture 오브젝트는, 텍스쳐가 렌더링 되는 원이 되는 비트 맵을 정의하기 위해서D3DRMIMAGE 구조체를 사용한다. 어플리케이션이D3DRMIMAGE구조체를 제공하면, 렌더링중에 간단하게 텍스쳐를 움직이거나 변경할 수 있다.

밉맵

밉맵과는 연속한 텍스쳐를 나타내, 각 텍스쳐는, 같은 이미지에 필터를 걸어 서서히 저해상도로 한 것이다. 밉맵은, 계산상 저비용에 텍스쳐의 렌더링 정밀도를 높이는 수단이다. 밉맵중의 필터 된 이미지나 레벨은, 전의 레벨보다 작게 되어 간다. 밉맵은,IDirect3DRMDevice3::SetTextureQuality 메소드를 호출해 텍스쳐를 필터링 할 경우에 지정할 수가 있다.

밉맵의 상세한 것에 대하여는, 「밉맵」을 참조할것.

텍스쳐 필터링

텍스쳐가 면에 맵핑 된 후는, 텍스쳐 요소(텍셀)가 최종 이미지의 각각의 픽셀과 일치하는 것은 분별없게 않다. 최종 이미지중의 픽셀은, 텍셀의 큰 집합체인가, 1개의 텍셀의 오부분에 상당한다. 픽셀에 텍셀의 값을 보간 하는 방법을 지정하려면 , 텍스쳐 필터링을 이용한다.

어플리케이션은,IDirect3DRMDevice3::SetTextureQuality 메소드와D3DRMTEXTUREQUALITY 열거형을 사용해, 텍스쳐 필터링 모드를 지정할 수가 있다.

텍스쳐의 투명화

투명한 텍스쳐를 생성하려면IDirect3DRMTexture3::SetDecalTransparency 메소드를 이용한다. 텍스쳐를 투명화하는 다른 방법으로서는, DirectDraw가 지원 하는컬러 키를 사용하는 방법이 있다. 컬러 키란, 블록 전송이나 오버레이 조작에 있어서의, 전송원 혹은 목적지 부분의 색 또는 색의 범위이다. 이러한 색은, 항상 덧쓰기되도록(듯이)도, 결코 변경되지 않게도 지정할 수가 있다.

DirectDraw의 컬러 키 지원의 상세한 것에 대하여는, 「컬러 키잉」을 참조할것.

텍스쳐 포맷 선택 룰

디바이스 독립 소스 이미지를 사용해, 렌더링 하는 디바이스 의존 텍스쳐 표면을 생성 하는 경우, 이하의 룰이 있다(우선 순위순서).

1. RGB/팔레트화 특성을 보존한다.

2. 알파 채널을 보존한다.

3. 비트 깊이 또는 팔레트 사이즈를 보존한다.

4. RBGA 마스크를 보존한다.

5. 8 비트 팔레트화 또는 16 비트 RGB를 우선한다.

텍스쳐 픽셀 포맷의 상세한 것에 대하여는, 「텍스쳐 맵 포맷」을 참조할것.

관련 정보에 대해서는, 「IDirect3DRMTexture3 」를 참조할것.


뷰포트

뷰포트는, 3 D신이 어떻게 2 D윈도우에 렌더링 되는지를 정의한다. 뷰포트는, 오브젝트가 렌더링 되는 디바이스 위에의 직사각형 영역을 정의한다.

이 인터페이스의 메소드의 레퍼런스는, 「IDirect3DRMViewport2 」를 참조할것.

이 섹션에서는, 뷰포트와 그 원가요소, 사용 위에의 테크닉에 대해 설명한다.

  • 카메라
  • 시추대
  • 변환
  • 피킹

카메라

뷰포트는 Direct3DRMFrame 오브젝트를카메라로서 사용한다. 카메라프레임은, 렌더링 되는 장면, 표시 위치 및 방향을 정의한다. 뷰포트는, 카메라 프레임의 정의 z축상에 있는 가시 오브젝트만을, y축위에의 정방향에 렌더링 한다.

어플리케이션은, 주어진 뷰포트에 카메라를 세트 하기 위해서,IDirect3DRMViewport2::SetCamera 메소드를 이용할 수가 있다. 이 메소드는, 뷰포트의 위치, 방향, 방향을 카메라 프레임으로 설정한다. 현재의 카메라의 설정을 취득하려면 ,IDirect3DRMViewport2::GetCamera 메소드를 호출한다.

절두체

절두체는, 뷰포트 카메라와 대립되어 놓여진, 장면안의 3 D볼륨이다. 파스페크티브뷰잉에서는, 카메라는 상상 위에의 피라미드의 버텍스에 놓여진다. 이 피라미드는, 2개의 클립면의프런트 클리핑 프레인과백 클리핑 프레인과 교차한다. 이 전후의 클립면의 사이에 있는 피라미드의 체적이 절두체이다. 절두체내의 오브젝트만이 가시 상태가 된다.

프런트 및 백 클리핑 프레인과 절두체를 나타내는 그림

카메라의 z축은, 피라미드의 버텍스로부터 백 클리핑 프레인의 중심을 통과한다. 유저의 어플리케이션이, 전후의 클립 프레인의 위치를 설정, 꺼내려면 ,IDirect3DRMViewport2::SetFront ,IDirect3DRMViewport2::SetBack ,IDirect3DRMViewport2::GetFront , 및IDirect3DRMViewport2::GetBack 메소드를 사용해 실시할 수가 있다.

프런트 클리핑 프레인 위에의 뷰포트의 차원이 카메라의 렌즈의 외관상의 초점장을 결정한다(이것은, 추대안의 오브젝트의 확대율을 설정하는 방법이라고 생각할 수도 있다). 프런트 클리핑 프레인 위에의 뷰포트용의 비례 차원을 설정, 꺼내려면 ,IDirect3DRMViewport2::SetField 및IDirect3DRMViewport2::GetField 메소드를 사용한다. 프런트 클리핑 프레인 위에의 뷰포트용의 임의의 차원을 설정, 꺼내려면 ,IDirect3DRMViewport2::SetPlane 및IDirect3DRMViewport2::GetPlane 메소드를 사용한다.

이하의 식을 사용해, 프런트 클리핑 프레인의 높이 (또는 폭)와 뷰잉 각도와의 관계를 결정할 수가 있다.

프런트 클리핑 프레인과 뷰잉 각도와의 관계를 나타내는 식

이 식에서, 뷰잉 각도는A, 프런트 클리핑 프레인의 카메라로부터의 거리는D, 프런트 클리핑 프레인의 높이는 2h이다. 디바이스가 정방형이 아니면, 따라 클립면이 정방형이 아니면, 뷰잉 각도는 프런트 클리핑 프레인의 반의 높이 또는 폭의 큰 (분)편을 고용해 계산된다. 축척 계수는, 비뚤어진 오브젝트가 되지 않게, 디바이스의 주축에 세트 한다. 이것을 바라지 않는 경우는, 일님 스케일링을 설정할 필요가 있다.

전의 식에서 사용되는 넓이의 그림

시추대의 피라미드는, 투시 투영의 경우에게만 적용된다. 평행 투영에 대해서는, 시추대는 입방체가 된다. 뷰의 타입(또는 투영 방법)은D3DRMPROJECTIONTYPE 열거형으로 정의되고 있어IDirect3DRMViewport2::GetProjection 및IDirect3DRMViewport2::SetProjection 메소드로 사용된다.

단위

DirectSound는, 디폴트의 단위 (미터)가 정해져 있는 유일한 DirectX 모듈이다. 디폴트 단위는 거리 계수를 사용해 변경할 수 있다. 그러나, Direct3D 직접 모드 및 보관 유지 모드에서는 특정의 디폴트 단위가 없다. 개발자는 어플리케이션에 최적인 단위를 결정해, 프로그램에 짜넣을 필요가 있다. 대부분의 어플리케이션에서는, 미터나 피트가 적절하지만, 그렇지 않은 경우도 있다. 예를 들어, 태양과 달을 화면에 배치 하면나무는, 거리를 마일 단위로 계측 한다. 또, 곤충이나 원자의 입자를 모델링 하면나무는, 단위를 미터나 피트보다 훨씬 작게 할 필요가 있다. DirectX는 단순하게 「단위」베이스로 동작해, 실제의 거리의 개념은 가지지 않는다.

단위를 지정하지 않고 장면을 구축 하면, 각종 소스로부터 DirectX 파일을 임포트 할 경우에 문제가 발생한다. 단위는 파일에 포함되지 않고, 임의의 「단위」를 자유롭게 사용할 수 있기 (위해)때문에, 표준 단위를 필요로 하지 않는다. 그 때문에, 다른 소스로부터 임포트 한 2기의 비행기를 올바르게 스케일링 하는 것은 어렵다. 한편의 모델이 미터, 이제(벌써) 한편이 피트로 모델링 되고 있으면, 한편의 모델을 로드할 때, 스케일링 하면 좋다. IDirect3DRMMeshBuilder3::Scale 함수는, 모델의 단위를 알고 있을 때 사용한다. 모델 생성시에 사용한 단위를 모르는 경우, 개발자는 시행 착오와 직감적인 추량으로 작업을 진행시킬 필요가 있다.

DirectSound를 사용하는 경우는, 어플리케이션 전체로 디폴트의 단위를 미터로 설정 하면이야 있고. 상세한 것에 대하여는, DirectSound 의 「최소 거리와 최대 거리」와「거리 계수」를 참조할것.

변환

3 D좌표의 오브젝트를 2 D윈도우에 렌더링 하기 위해서는, 오브젝트를카메라프레임내로 변환하지 않으면 안 된다. 거기서, 4개의 요소를 가지는 동질의 좌표[x y z w]를 요구하기 (위해)때문에, 투영 행렬이 이용된다. 좌표[x y z w]는, 3 요소의 좌표[x/w y/w z/w]를 취득하기 위해서 사용된다. [x/w y/w] 는 윈도우가 사용하는 좌표이다. 또,z/w는 깊이를 0에서 1의 범위에서 가리켜, 0은프런트 클리핑 프레인, 1은백 클리핑 프레인이 된다. 투영 행렬은, 투시 변환의 뒤에 오브젝트의 스케일링과 이동을 결합한 것이다.

다음의 값이 투영 행렬의 요소이다. 이 등식에 대해,h는시 추대의 반의 높이,F는 카메라로부터의 거리,D는 프런트 클리핑 프레인의 z좌표를 나타내고 있다.

투영을 한 후, 다음의 스텝은, 클리핑 및 뷰포트내의 스크린 픽셀 좌표에의 x와 y의 변환이다. 이 때문에, D3DVIEWPORT 데이터 멤버를 이용한다. 뷰포트는, 렌더링 표면 위에의 직사각형 윈도우이다.

typedef struct _D3DVIEWPORT {
    DWORD    dwSize;
    DWORD    dwX;
    DWORD    dwY;
    DWORD    dwWidth;
    DWORD    dwHeight;
    D3DVALUE dvScaleX;
    D3DVALUE dvScaleY;
    D3DVALUE dvMaxX;
    D3DVALUE dvMaxY;
    D3DVALUE dvMinZ;
    D3DVALUE dvMaxZ;
} D3DVIEWPORT, *LPD3DVIEWPORT;

dwX및dwY필드는, 표면 위에의 뷰포트의 좌상에의 오프셋(offset)를 스크린 픽셀로 지정한다.

dwWidth및dwHeight필드는, 스크린 픽셀로 나타낸 뷰포트의 폭과 높이이다.

dvScaleX및dvScaleY필드는, 화면 좌표를 생성하기 위해서 x값 및 y값에 적용되는 축척 계수이다. 보통, 다음의 등식을 이용해, 정규화 투시 뷰 볼륨 전체를 뷰포트에 맵핑 한다.

  dvScaleX = dwWidth / 2
  dvScaleY = dwHeight / 2

예를 들어-1에서 1의 X좌표는,－dwWidth / 2로부터 dwWidth / 2에 스케일링 되어 그 다음에, dwWidth / 2의 오프셋(offset)가 더해진다. 이 스케일링은, 클리핑의 뒤에 행해진다.

윈도우가 정방형이 아니고, 올바른 어스펙트비(가로세로 비율)을 보관 유지하고 싶으면, 2개의 윈도우 넓이의 큰 (분)편을 양스케일링값으로서 이용한다. 또, 뷰 볼륨의 일부를 클립 할 필요가 있다.

dvMaxX,dvMaxY,dvinZ, 및dvMaxZ필드는, 클립면을 지정한다. x = dvMaxX, x =－dvMaxX, y = dvMaxy, y =－dvMaxY, z = dvMinZ, z = dvMaxZ. 예를 들어, 뷰 볼륨을 표시하려면 ,dvMaxX = dvMaxY = dvMaxZ = 1 및dvMinZ = 0으로 한다. 상술한 것처럼, 비정방형 윈도우로 올바른 어스펙트비(가로세로 비율)을 보관 유지하고 싶으면, 뷰 볼륨의 일부를 클립 할 필요가 있다. 거기에는, 이하의 등식을 이용한다. 이러한 등식은, 정방형 뷰포트의 경우에도 사용할 수가 있어 따라 항상 사용할 수 있다.

dvMaxX = dwWidth / (2 * dvScaleX)
dvMaxY = dwHeight / (2 * dvScaleY)

뷰포트 변환을 이용하면(자),월드 좌표에서의 오브젝트의 이동거리를 카메라로부터 깊이까지의 거리와 일치시킬 수가 있다. IDirect3DRMViewport2::Transform 메소드의 결과는, 4개의 요소를 가지는 벡터로 나타내지는 것에 주의받고 싶다. 이것에 의해, 카메라의 위치에 한없고 가까운 좌표로 생기는 문제를 회피할 수가 있다.

프레임의 변환에 대해서는, 「변환」을 참조할것. 변환의 수학의 개요에 대해서는, 「3 D변환」을 참조할것.

피킹

피킹이란, 뷰포트의 윈도우로, 2 D좌표로부터 장면 위에의 비주얼 오브젝트를 탐색하는 프로세스이다. 어플리케이션은IDirect3DRMViewport2::Pick 메소드를 사용해, 장면 위에의 가장 가까운 오브젝트, 또는 오브젝트의 겹쳐 순서의 리스트를 취득할 수가 있다.


랩

랩은, 면이나 메쉬의 텍스쳐 좌표의 계산에 사용할 수가 있다. 랩을 생성 하려면 , 어플리케이션은, 랩의 타입이나 참조 프레임, 원점, 방향 벡터, 상 벡터를 지정하지 않으면 안 된다. 또, 스케일링 계수와 텍스쳐 좌표의 원점도 지정할 필요가 있다.

어플리케이션은,IDirect3DRM3::CreateWrap 메소드를 호출해IDirect3DRMWrap 인터페이스를 생성한다. 이 인터페이스에는,IDirect3DRMWrap::Apply 와IDirect3DRMWrap::ApplyRelative 의 2개의 특유인 메소드가 포함되어 있다. IDirect3DRMWrap::Apply는, 오브젝트의 버텍스에 랩을 적용한다. IDirect3DRMWrap::ApplyRelative는, 적용된 랩의 버텍스를 변환한다.

샘플에서는, 방향 벡터(v벡터)는 z축으로 따라, 상 벡터(u벡터)는 y축으로 따르고 있다. 원점은[0, 0, 0]이다.

IDirect3DRMWrap인터페이스의 메소드의 레퍼런스는 「IDirect3DRMWrap 」를 참조할것.

이 섹션에서는, 랩핑 플래그와 4개의 랩핑 타입에 대해 설명한다.

  • 랩핑 플래그
  • 평면
  • 원기둥(실린더)
  • 구(공)체
  • 크롬

랩핑 플래그

D3DRMMAPPING 형에는, D3DRMMAP_WRAPU 플래그와 D3DRMMAP_WRAPV 플래그가 포함되어 있다. 이러한 플래그에 의해, 래스터라이저가 텍스쳐 좌표를 해석할 방법이 결정된다. 래스터라이저는, 항상 텍스쳐 좌표간의 최단 거리 (즉 직선)를 보간 한다. 이 직선의 패스와 유효한 u 및 v좌표의 값은, 랩핑 플래그의 사용법에 따라서 다르다. 플래그의 다른 한쪽 혹은 양쪽 모두가 세트 되면(자), 직선은 u 또는 v방향의 텍스쳐의 옆을 따라, 원기둥(실린더)장이나 도너츠장의 형상인가와 같이 rack-around 된다.

  • 랩핑 플래그가 세트되어 있지 않은 평면 랩핑 모드에서는, u 또는 v좌표로 지정된 평면에는, 텍스쳐가 무한하게 타일링 된다. 이 경우, 유효한 u 및 v좌표값은 1.0이상이다. 점(0.1, 0.1)과(0.9, 0,9)를 묶는 최단의 직선은, 점(0.5, 0.5)을 통과한다.
  • D3DRMMAP_WRAPU 또는 D3DRMMAP_WRAPV중 한쪽이 세트 되었을 경우, 텍스쳐는 원주 1.0의 마지막이 없는 원통형이 된다. 1.0이상의 텍스쳐 좌표는, 랩되어 있지 않은 범위내만 유효하다. 텍스쳐 좌표간의 최단 거리는 랩핑 플래그에 따라서 다르다. D3DRMMAP_WRAPU가 세트 되고 있을 때는, 점(0.1, 0.1)으로부터(0.9, 0.9)까지의 최단의 직선은, 점(0, 0.5)을 통과한다.
  • D3DRMMAP_WRAPU와 D3DRMMAP_WRAPV 플래그의 양쪽 모두가 세트 되었을 때는, 텍스쳐는 원환체(도너츠) 장이 된다. 시스템은 폐쇄하고 있기 (위해)때문에, 1.0이상의 텍스쳐 좌표는 무효이다. 점(0.1, 0.1)으로부터(0.9, 0.9)까지의 최단의 직선은, 점(0, 0)을 통과한다.

무효 영역에 있던 텍스쳐 좌표를 유효 영역에 넣었다고 해도, 그 때의 동작은 보증되어 있지 않다.

일반적으로 어플리케이션은, 텍스쳐의 교선이 면의 옆과 일치하지 않을 때, 원기둥(실린더)장에 랩 하기 위해서 랩핑 플래그를 세트 한다. 1개의 면에 텍스쳐의 반이상이 사용되는 경우에는, 랩핑 플래그는 설정하지 않는다.

평면

평면 랩에서는, 텍스쳐는, 오브젝트상에 스트렛치 된 고무와 같이 오브젝트의 면에 일치한다.

다음의 등식에 의해, 벡터[x y z]로부터[u v]좌표가 요구된다.

평면 랩의 벡터로부터 [u v] 좌표를 요구하는 식

이러한 공식으로 두어,s는 윈도우의 스케일링 계수,o는 윈도우의 원점을 나타내고 있다. 어플리케이션은, 1조의 스케일링 계수와u및v가 유효한 값을 취하도록(듯이)x와y를 0에서 1의 범위에 맵하기 위한 오프셋(offset)를 결정하지 않으면 안 된다.

원기둥(실린더)

원기둥(실린더) 랩에서는, 텍스쳐는 원기둥(실린더)의 회전을 싸는 종이와 같이 다루어져 그 좌단은 우단으로 연결되어 있다. 오브젝트는 원주의 중앙에 배치되어 오브젝트의 표면에 맞추어 텍스쳐가 변형된다.

다음의 그림은, 원기둥(실린더) 텍스쳐 맵에 있어서의 각 벡터의 효과를 나타낸 것이다.

원기둥(실린더) 랩 위에의 벡터의 효과를 나타내는 그림

방향 벡터는 원기둥(실린더)의 축을 나타내, 상 벡터는 원통의 외측의u = 0인 점을 나타낸다. 시스템은, 벡터[x y z]에 대한 텍스쳐의[u v]좌표를 계산하기 위해서, 다음의 등식을 사용한다.

원기둥(실린더) 랩의 벡터로부터 [u v] 좌표를 요구하는 식

보통,u는 스케일링 되지 않은 채이다. v가 유효한 값을 취하도록(듯이) z를 0에서 1의 범위에 맵 해,v의 스케일링과 변환을 한다.

구(공)체

구(공)체 랩에서는, 벡터[x y 0]으로 x축의 각도로부터(원기둥(실린더) 랩과 같게) u좌표가 요구된다. v좌표는, 벡터[x y z]와 z축의 각도로부터 요구된다. 이 맵핑에서는, z축상에 일그러짐이 생기는 것에 주의가 필요하다.

구(공)체 랩 위에의 벡터의 효과를 나타내는 그림

이것은 다음의 등식에서 나타내진다.

구(공)체 랩의 벡터로부터 [u v] 좌표를 요구하는 식

여기에서는, 스케일링되어 있지 않은u와v의 범위는 항상 0에서 1이기 (위해)때문에, 스케일링 계수와 텍스쳐의 원점은 필요하게 되지 않는 것이 많다.

크롬

크롬 랩은, 텍스쳐가 오브젝트상에 반사해 보이도록(듯이) 텍스쳐 좌표를 할당한다. 크롬 랩은 참조 프레임의 위치를 취득해, 반사 벡터를 계산하기 위해서 메쉬의 버텍스 법선을 사용한다. 그 후, 메쉬를 둘러싸는 가상의 구(공)체를 이용해, 반사 벡터의 교선으로부터 텍스쳐의 u 및 v좌표를 계산한다. 이것에 의해, 구(공)체에 무엇이 랩 되고 있어도, 메쉬에 반사 효과가 주어진다.


튜토리얼

Microsoft® Windows®베이스의 Direct3D®보관 유지 모드 어플리케이션을 생성 하기 위해서는, 다른 2개의 환경을 설정하지 않으면 안 된다. 하나는, 디바이스, 뷰포트, 색해상도라고 하는 Windows 환경이며, 이제(벌써) 하나는, 모델, 텍스쳐, 조명, 위치라고 하는 가상 환경이다. 이 튜토리얼에서는, 간단한 보관 유지 모드 어플리케이션의 전코드를 소개하고 있다. 다음의 그림은, 동작중의 애니메이션의 프레임의 하나이다.

동작중의 애니메이션의1개의 프레임

이 튜토리얼은, 이하의 섹션으로 나눌 수 있고 있다.

  • Helworld 샘플의 생성
  • 매크로 정의와 글로벌 변수
  • Windows의 셋업과 초기화
  • 디바이스 드라이버의 열거
  • 3 D환경의 셋업
  • 렌더링 루프
  • 장면의 생성
  • 종료 처리

Helworld 샘플의 생성

이 튜토리얼에는, 실제의 Direct3D 보관 유지 모드 어플리케이션의 모든 코드가 포함되어 있다. 이하의 조건을 채우면(자), 튜토리얼로부터 이 코드를 단일의. c파일에 카피해, 컴파일 해 실행할 수가 있다.

  • Direct3D 헤더 파일(D3d.h, D3drm.h등)을 인클루드 패스로 설정해 있는 것.
  • Winmm.lib, D3drm.lib, 및 Ddraw.lib 정적 라이브러리와 링크하고 있는 것.
  • 사용하는 컴파일러가, Microsoft® DirectX® Software Development Kit의 Media 디렉토리안의 Sphere3.x 파일을 발견할 수 있는 것.
  • Tutor.bmp 파일을 공급하는 것.

    이 비트 맵의 픽셀 사이즈는, 2의 거듭제곱이 아니면 안되는 것에 주의한다. 예를 들어, 16×16 픽셀 비트 맵, 128×1024 픽셀 비트 맵, 512×256 픽셀 비트 맵 등이다.

이 샘플 중(안)에서, 3 D효과를 맡는 코드의 대부분은, 별개의 함수로 분할되고 있으므로, 유저는, 샘플의 일부를 서서히 수정해 실험할 수가 있다. Direct3D의 한층 더 복잡한 기능을 이행 하려면 , DirectX SDK의 샘플을 조사할 필요가 있다.

이하의 항목은, 단순한 Direct3D 보관 유지 모드 어플리케이션의 개발 전반에 적용할 수 있는 사항을 몇개인가 설명하는 것이다.

  • 샘플의 제한
  • DirectDraw의 윈도우 모드

샘플의 제한

이 튜토리얼에는, Helworld.c의 샘플 코드가 포함되어 있다. 그 코드는, 구(공)을 생성해, 그 구(공)에 텍스쳐를 적용해, 윈도우 중(안)에서 회전시킨다. 이것은, 이 어플리케이션을 생성 하는데 필요한, 다만 1개의 C소스 파일이다. 그 밖에 필요한 파일은, Sphere3.x, DirectX SDK의 Media 디렉토리 중(안)에서 배포되고 있는 1개의 메쉬 파일, 유저가 공급하는 비트 맵의 Tutor.bmp 뿐이다(유저의 인클루드 패스중에 Direct3D 헤더 파일을 설정해 있는 것, Winmm.lib, D3drm.lib, 및 Ddraw.lib 정적 라이브러리에 링크하고 있는 것이 전제인 것에 주의한다).

이 튜토리얼은, DirectX SDK의 일부인 Globe 샘플을 간단하게 한 것이다. Globe 샘플은, SDK의 모든 Direct3D 보관 유지 모드 샘플과 같게, Rmmain.cpp 파일 물어 구두인가의 헤더 파일을 인클루드 하는 것을 필요로 한다. Helworld.c에서는, Rmmain.cpp의 사용 가능 부분을 C++로부터 C로 변환해 소스 코드에 수중에 넣어 있다.

이 튜토리얼로 가리키는 코드는, 실용 코드로 잘못알아선 안 된다. 프로그램과 가능한 유저의 대화형 조작은, 프로그램을 기동, 정지하는 것으로, 실행중에 윈도우를 최소화하는 것에 한정되고 있다. 코드를 알기 쉽게하기 위해(때문에), 에러 체크의 대부분은 제외해 있다. 이 샘플의 목적은, 번잡한 일을 최소한으로 해 출력을 실시하는,"Hello, world! "(을)를 화면상에 표시하는 초보의 프로그램의 목적을 닮아 있다.

DirectDraw의 윈도우 모드

거의 모든 Direct3D 어플리케이션은, DirectDraw®를 이용해 스크린에 그래픽스를 표시한다. 이러한 어플리케이션은, DirectDraw의 배타(풀 스크린) 모드 또는 비배타(윈도우) 모드의 어느쪽이든을 사용한다. 이 문서의 코드는 윈도우 모드를 사용하고 있다. 풀 스크린 모드는 퍼포먼스 위에의 이점이나 쾌적함을 제공하지만, 윈도우 모드로 쓰여진 코드 쪽이 디버그가 간단하다. 대부분의 개발자는 윈도우 모드로 코드를 써, 디버그 종료후, 풀 스크린 모드에 이행 시킨다.

매크로 정의와 글로벌 변수

이하는, Helworld.c 샘플의 최초의 몇 줄기이다. 이 어플리케이션을 빌드 하는데 다른 C소스 파일은 필요없지만, 파일의 확장자(extension)는. cpp는 아니고 . c로 한다. C컴파일러는, 확장자(extension). cpp가 붙은 파일을 C++의 코드로 간주해,lpVtbl 포인터와 추가 파라미터의this를 취급한다. 자세하게는, DirectX SDK 문서의 「C로부터의 COM 오브젝트에의 액세스」를 참조할것. 이 튜토리얼은 C로 쓰여져 있기 (위해)때문에, 명시적으로lpVtbl 포인터를 인클루드 해, 초기this파라미터를 추가하고 있다. 이 파일의 확장자(extension)를. cpp로 하면(자), 컴파일러는 다수의 compile error를 생성한다.

INITGUID는, 다른 인클루드나 매크로 정의보다 전에 정의되어 있지 않으면 안 된다. 이것은, DirectX를 처음으로 조작하는 개발자가 틀리기 쉬운, 중요한 포인트이다.

/////////////////////////////////////////////////////////////////////
//
//  Copyright (C) 1996 Microsoft Corporation.  All Rights Reserved.
//
//  File: Helworld.c
//
//  "Globe" SDK 샘플에 근거한,
//  간단한 Direct3D 보관 유지 모드의 샘플.
//
/////////////////////////////////////////////////////////////////////

#define INITGUID           // 다른 매크로 정의나 인클루드의 전에 정의하지 않으면 안 된다

#include <windows.h>
#include <malloc.h>        // memset의 호출에 필요
#include <d3drmwin.h>

#define MAX_DRIVERS 5           // D3D 드라이버의 최대수

// 글로벌 변수

LPDIRECT3DRM lpD3DRM;           // Direct3DRM 오브젝트
LPDIRECTDRAWCLIPPER lpDDClipper;// DirectDrawClipper 오브젝트

struct _myglobs {
    LPDIRECT3DRMDEVICE dev;     // Direct3DRM 디바이스
    LPDIRECT3DRMVIEWPORT view;  // 신이 표시되는 Direct3DRM 뷰포트
    LPDIRECT3DRMFRAME scene;    // 다른 오브젝트가 배치되는 마스터 프레임
    LPDIRECT3DRMFRAME camera;   // 유저의 POV를 나타내는 프레임

    GUID DriverGUID[MAX_DRIVERS];     // 유효한 D3D 드라이버의 GUID
    char DriverName[MAX_DRIVERS][50]; // 유효한 D3D 드라이버의 이름
    int  NumDrivers;                  // 유효한 D3D 드라이버의 수
    int  CurrDriver;                  // 현재 사용되고 있는 D3D 드라이버의 수

    BOOL bQuit;                 // 프로그램이 종료하려고 하고 있다
    BOOL bInitialized;          // 모든 D3DRM 오브젝트가 초기화되었다
    BOOL bMinimized;            // 윈도우가 최소화되었다

    int BPP;                    // 현재의 디스플레이 모드의 비트 깊이

} myglobs;

// 함수의 prototype

static BOOL InitApp(HINSTANCE, int);
long FAR PASCAL WindowProc(HWND, UINT, WPARAM, LPARAM);
static BOOL EnumDrivers(HWND win);
static HRESULT WINAPI enumDeviceFunc(LPGUID lpGuid,
    LPSTR lpDeviceDescription, LPSTR lpDeviceName,
    LPD3DDEVICEDESC lpHWDesc, LPD3DDEVICEDESC lpHELDesc,
    LPVOID lpContext);
static DWORD BPPToDDBD(int bpp);
static BOOL CreateDevAndView(LPDIRECTDRAWCLIPPER lpDDClipper,
    int driver, int width, int height);
static BOOL SetRenderState(void);
static BOOL RenderLoop(void);
static BOOL MyScene(LPDIRECT3DRMDEVICE dev, LPDIRECT3DRMVIEWPORT view,
    LPDIRECT3DRMFRAME scene, LPDIRECT3DRMFRAME camera);
void MakeMyFrames(LPDIRECT3DRMFRAME lpScene, LPDIRECT3DRMFRAME lpCamera,
    LPDIRECT3DRMFRAME * lplpLightFrame1,
    LPDIRECT3DRMFRAME * lplpWorld_frame);
void MakeMyLights(LPDIRECT3DRMFRAME lpScene, LPDIRECT3DRMFRAME lpCamera,
    LPDIRECT3DRMFRAME lpLightFrame1,
    LPDIRECT3DRMLIGHT * lplpLight1, LPDIRECT3DRMLIGHT * lplpLight2);
void SetMyPositions(LPDIRECT3DRMFRAME lpScene,
    LPDIRECT3DRMFRAME lpCamera, LPDIRECT3DRMFRAME lpLightFrame1,
    LPDIRECT3DRMFRAME lpWorld_frame);
void MakeMyMesh(LPDIRECT3DRMMESHBUILDER  * lplpSphere3_builder);
void MakeMyWrap(LPDIRECT3DRMMESHBUILDER  sphere3_builder,
                LPDIRECT3DRMWRAP * lpWrap);
void AddMyTexture(LPDIRECT3DRMMESHBUILDER  lpSphere3_builder,
                  LPDIRECT3DRMTEXTURE * lplpTex);
static void CleanUp(void);

Windows의 셋업과 초기화

이 항에서는, Helworld.c 샘플 코드에 인플리맨트 되고 있는, Windows 프로그램의 표준적인 셋업과 초기화 함수에 대해 설명한다.

  • WinMain 함수
  • InitApp 함수
  • 메인 윈도우 프로시저

WinMain 함수

Helworld.c의 WinMain 함수에는, DirectDraw나 Direct3D 보관 유지 모드를 이용하는 어플리케이션에 특유인 코드가 약간 포함되어 있다. InitApp 함수와 CleanUp 함수는 Windows 프로그램의 표준적인 부분이지만, Helworld.c에서는, 한층 더 몇개의 특별한 태스크를 실행한다. Direct3D에 대해, WinMain 함수가 실시하는 가장 중요한 처리는, RenderLoop 함수의 호출이다. RenderLoop 함수는, 애니메이션의 각각의 프레임을 드로잉(Drawing) 하기 위해서 필요하다. RenderLoop 함수에 대해 자세하게는 「렌더링 루프」를 참조할것.

/////////////////////////////////////////////////////////////////////
//
// WinMain
// 어플리케이션을 초기화해, 메시지 루프를 시작 한다.
// 메시지 루프는, 종료 메세지를 받아들일 때까지 장면을 렌더링 한다.
//
/////////////////////////////////////////////////////////////////////

int PASCAL
WinMain (HINSTANCE this_inst, HINSTANCE prev_inst, LPSTR cmdline,
    int cmdshow)
{
    MSG     msg;
    HACCEL  accel = NULL;
    int     failcount = 0;  // RenderLoop가 실패한 회수

    prev_inst;
    cmdline;

    // 윈도우를 생성 해, 렌더링을 시작 하기 위해서 필요한
    // 모든 오브젝트를 초기화한다.

    if (! InitApp(this_inst, cmdshow))
        return 1;

    while (! myglobs.bQuit) {

        // 처리하는 메세지가 없어질 때까지, 메시지 큐
        // (을)를 감시한다.

        while (PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)) {
            if (! TranslateAccelerator(msg.hwnd, accel, &msg)) {
                TranslateMessage(&msg);
                DispatchMessage(&msg);
            }
        }

        // 어플리케이션이 최소화되지 않고, 종료할려고도 하고 있지 않고, 한편
        // D3DRM가 초기화되고 있으면, 렌더링을 시작 한다.

        if (! myglobs.bMinimized && ! myglobs.bQuit &&
             myglobs.bInitialized) {

            // 프레임의 렌더링을 시도한다. 렌더링이 2회 이상
            // 실패하면(자), 실행을 중단한다.

            if (! RenderLoop())
                ++failcount;
            if (failcount > 2) {
                CleanUp();
                break;
            }
        }
    }
    return msg.wParam;
}

InitApp 함수

Helwold.c의 초기화 함수(InitApp)는, 대부분의 Windows 베이스의 어플리케이션과 같게, 윈도우 클래스를 등록해, 메인 어플리케이션 윈도우를 생성 한다. 이 후, InitApp 함수는 DirectDraw나 Direct3D를 이용하는 어플리케이션에 특유의 처리를 실시한다.

다음에, InitApp 함수는, 현재의 디스플레이의 픽셀 당의 비트수를 취득한다. 이 값은, 어플리케이션이 렌더링의 퀄리티를 설정할 때에 사용된다. 자세하게는 「렌더링 스테이트의 설정」을 참조할것.

그 후, 어느 Direct3D 드라이버가 유효한가를 결정해, 적절한 드라이버를 선택하기 위해서, 로컬 정의의 EnumDrivers 함수를 사용한다. 드라이버의 열거에 대해 자세하게는, 「디바이스 드라이버의 열거」를 참조할것.

다음에,Direct3DRMCreate 함수를 사용해,IDirect3DRM3 인터페이스를 생성 한다. 이 인터페이스는, 장면이나카메라프레임을 생성 하거나 카메라를 장면에 설치하기 (위해)때문에,IDirect3DRM3::CreateFrame 나IDirect3DRMFrame3::SetPosition 를 호출하면나무에 사용된다.

DirectDrawClipper 오브젝트는, 어느 부분의 3 D신을 가시 상태로 하는지를 제어하는 클립면의 관리를 간단하게 한다. Helworld.c는,DirectDrawCreateClipper 함수를 사용해IDirectDrawClipper 인터페이스를 생성한 후,IDirectDrawClipper::SetHWnd 메소드를 사용해, 클립 정보를 취득하기 위해서 윈도우 핸들을 설정한다.

그리고, 로컬 정의의 CreateDevAndView 함수를 사용해, Direct3D 디바이스와 뷰포트를 생성 한다. 이 함수에 대해 자세하게는 「디바이스와 뷰포트의 생성」을 참조할것.

Direct3D 어플리케이션이 지원 하는 모든 구조체의 초기화가 완료 하면, 3 D신을 세세하게 구성할 수가 있게 된다. 이 처리는 MyScene 함수가 가고 있다. MyScene 함수의 상세한 것에 대하여는, 「디바이스와 뷰포트의 생성」을 참조할것.

마지막에 InitApp 함수는, 표준적인 초기화 함수와 같게, 윈도우의 표시와 갱신을 실시한다.

/////////////////////////////////////////////////////////////////////
//
// InitApp
// 윈도우를 생성 해, 렌더링을 시작 하기 위해서 필요한
// 모든 오브젝트를 초기화한다.
//
/////////////////////////////////////////////////////////////////////

static BOOL
InitApp(HINSTANCE this_inst, int cmdshow)
{
    HWND win;
    HDC hdc;
    WNDCLASS wc;
    RECT rc;

    // 셋업을 실시해, 윈도우 클래스를 등록한다.

    wc.style = CS_HREDRAW | CS_VREDRAW;
    wc.lpfnWndProc = WindowProc;
    wc.cbClsExtra = 0;
    wc.cbWndExtra = sizeof(DWORD);
    wc.hInstance = this_inst;
    wc.hIcon = LoadIcon(this_inst, "AppIcon");
    wc.hCursor = LoadCursor(NULL, IDC_ARROW);
    wc.hbrBackground = (HBRUSH) GetStockObject(BLACK_BRUSH);
    wc.lpszMenuName = NULL;
    wc.lpszClassName = "D3DRM Example";
    if (! RegisterClass(&wc))
        return FALSE;

    // 글로벌 변수를 초기화한다.

    memset(&myglobs, 0, sizeof(myglobs));

    // 윈도우를 생성 한다.

    win =
        CreateWindow
        (   "D3DRM Example",            // 윈도우 클래스
            "Hello World (Direct3DRM)", // 타이틀 바
            WS_VISIBLE | WS_OVERLAPPED | WS_CAPTION | WS_SYSMENU |
                 WS_MINIMIZEBOX | WS_MAXIMIZEBOX,
            CW_USEDEFAULT,              // 초기 x좌표
            CW_USEDEFAULT,              // 초기 y좌표
            300,                        // 초기의 폭
            300,                        // 초기의 높이
            NULL,                       // 부모 윈도우
            NULL,                       // 메뉴 핸들
            this_inst,                  // 프로그램의 인스턴스 핸들
            NULL                        // 생성 파라미터
        );
    if (! win)
        return FALSE;

    // 현재의 디스플레이의 픽셀 당의 비트수를 기억한다.

    hdc = GetDC(win);
    myglobs.BPP = GetDeviceCaps(hdc, BITSPIXEL);
    ReleaseDC(win, hdc);

    // D3D 드라이버를 열거해, 1개를 선택한다.

    if (! EnumDrivers(win))
        return FALSE;

    // D3DRM 오브젝트와 D3DRM 오브젝트를 생성 한다.

    lpD3DRM = NULL;
    Direct3DRMCreate(&lpD3DRM);

    // 마스터 신의 프레임과 카메라 프레임을 생성 한다.

    lpD3DRM->lpVtbl->CreateFrame(lpD3DRM, NULL, &myglobs.scene);
    lpD3DRM->lpVtbl->CreateFrame(lpD3DRM, myglobs.scene,
        &myglobs.camera);
    myglobs.camera->lpVtbl->SetPosition(myglobs.camera, myglobs.scene,
        D3DVAL(0.0), D3DVAL(0.0), D3DVAL(0.0));

    // DirectDrawClipper 오브젝트를 생성 해,
    // 윈도우와 관련짓는다.

    DirectDrawCreateClipper(0, &lpDDClipper, NULL);
    lpDDClipper->lpVtbl->SetHWnd(lpDDClipper, 0, win);

    // 선택된 D3D 드라이버를 이용해 D3DRM 디바이스를 생성 한다.

    GetClientRect(win, &rc);
    if (! CreateDevAndView(lpDDClipper, myglobs.CurrDriver, rc.right,
            rc.bottom)) {
        return FALSE;
    }

    // 렌더링 되는 장면을 생성 한다.

    if (! MyScene(myglobs.dev, myglobs.view, myglobs.scene,
            myglobs.camera))
        return FALSE;

    myglobs.bInitialized = TRUE;  // 초기화 완료.

    // 윈도우를 표시한다.

    ShowWindow(win, cmdshow);
    UpdateWindow(win);

    return TRUE;
}

메인 윈도우 프로시저

Helworld.c 샘플의 메인 윈도우 프로시저는 매우 단순하다. 실제는, 이 샘플은 유저의 입력을 전혀 받아들이지 않는 어플리케이션이 된다.

윈도우 프로시저는, WM_DESTROY 메세지를 받아들이면(자) CleanUp 함수를 사용한다.

또, WM_ACTIVATE 메세지를 받아들였을 때에는, 윈도우 프로시저는IDirect3DRMWinDevice 를 취득해, 액티브한 렌더링 윈도우의 정색해 구표시하기 위해서IDirect3DRMWinDevice::HandleActivate 메소드를 사용한다. 같이 WM_PAINT 메세지에 응답해, 윈도우 프로시저는IDirect3DRMWinDevice::HandlePaint 메소드를 사용한다.

/////////////////////////////////////////////////////////////////////
//
// WindowProc
// 메인 윈도우의 메세지 핸들러
//
/////////////////////////////////////////////////////////////////////

LONG FAR PASCAL WindowProc(HWND win, UINT msg,
    WPARAM wparam, LPARAM lparam)
{
    RECT r;
    PAINTSTRUCT ps;
    LPDIRECT3DRMWINDEVICE lpD3DRMWinDev;

    switch (msg)    {

    case WM_DESTROY:
        CleanUp();
        break;

    case WM_ACTIVATE:
        {

        // 이 메세지를 처리하는, 윈도우 고유의
        // Direct3D 보관 유지 모드 윈도우 디바이스를 생성 한다.

        if (! myglobs.dev)
            break;
        myglobs.dev->lpVtbl->QueryInterface(myglobs.dev,
            &IID_IDirect3DRMWinDevice, (void **) &lpD3DRMWinDev);
        lpD3DRMWinDev->lpVtbl->HandleActivate(lpD3DRMWinDev,
            (WORD) wparam);
        lpD3DRMWinDev->lpVtbl->Release(lpD3DRMWinDev);
        }
        break;

    case WM_PAINT:
        if (! myglobs.bInitialized || ! myglobs.dev)
            return DefWindowProc(win, msg, wparam, lparam);

        // 이 메세지를 처리하는, 윈도우 고유의
        // Direct3D 보관 유지 모드 윈도우 디바이스를 생성 한다.

        if (GetUpdateRect(win, &r, FALSE)) {
            BeginPaint(win, &ps);
            myglobs.dev->lpVtbl->QueryInterface(myglobs.dev,
                &IID_IDirect3DRMWinDevice, (void **) &lpD3DRMWinDev);
            lpD3DRMWinDev->lpVtbl->HandlePaint(lpD3DRMWinDev,
                ps.hdc);
            lpD3DRMWinDev->lpVtbl->Release(lpD3DRMWinDev);
            EndPaint(win, &ps);
        }
        break;
    default:
        return DefWindowProc(win, msg, wparam, lparam);
    }
    return 0L;
}

디바이스 드라이버의 열거

Direct3D를 이용하는 어플리케이션은, 반드시, 유효한 드라이버를 열거해, 필요한 조작을 실시하기 위해서(때문에) 최적인 드라이버를 선택해야 한다. 이하의 섹션에서는, 이 처리를 실행하는 함수에 대해 설명한다.

  • EnumDrivers 함수
  • enumDeviceFunc 콜백 함수
  • BPPToDDBD 헬퍼 함수

EnumDrivers 함수

EnumDrivers 함수는, InitApp 함수가 어플리케이션의 장면과 카메라를 생성하기 직전에 사용된다.

IDirect3D COM(Component Object Model) 인터페이스는, 실제로는 DirectDraw 오브젝트에 대한 인터페이스이므로, 이 열거 함수가 최초로 하는 것은,DirectDrawCreate 함수를 사용해 DirectDrawObject를 생성 하는 것이다. 그 후, EnumDrivers가QueryInterface 메소드를 사용해IDirect3D인터페이스를 생성한다. QueryInterface의 C의 이행이, 단순하게 정수 자체는 아니고(C++의 이행과 같이), 2번째의 파라미터로서 인터페이스 식별자의 주소를 건네주는 것을 요구하는 것에 주의한다.

드라이버의 열거는,IDirect3D::EnumDevices 메소드에 의해 행해진다. IDirect3D::EnumDevices메소드는, 로컬에 정의된 enumDeviceFunc 콜백 함수를 이용한다. 이 콜백 함수의 상세한 것에 대하여는, 「enumDeviceFunc 콜백 함수」를 참조할것.

IDirect3D::EnumDevices는 Direct3D 메소드이며, Direct3DRM 메소드는 아닌 것에 주의가 필요하다. 보관 유지 모드의 API에는, 열거를 실시하는 메소드는 존재하지 않는다. 이것은, 1개의 어플리케이션으로 보관 유지 모드와 직접 모드의 양쪽 모두를 사용하는 경우가 좋은 예이다.

/////////////////////////////////////////////////////////////////////
//
// EnumDrivers
// 유효한 D3D 드라이버를 열거해, 1개를 선택한다.
//
/////////////////////////////////////////////////////////////////////

static BOOL
EnumDrivers(HWND win)
{
    LPDIRECTDRAW lpDD;
    LPDIRECT3D lpD3D;
    HRESULT rval;

    // DirectDraw 오브젝트를 생성 해, 드라이버의 열거에
    // 이용하는 Direct3D 인터페이스를 문의한다.

    DirectDrawCreate(NULL, &lpDD, NULL);
    rval = lpDD->lpVtbl->QueryInterface(lpDD, &IID_IDirect3D,
        (void**) &lpD3D);
    if (rval ! = DD_OK) {
        lpDD->lpVtbl->Release(lpDD);
        return FALSE;
    }

    // enumDeviceFunc의 드라이버 선택 코드를 초기화한다
    // 모아 두어 CurrDriver에―1을 설정해, 드라이버를 열거한다.

    myglobs.CurrDriver = -1;
    lpD3D->lpVtbl->EnumDevices(lpD3D, enumDeviceFunc,
        &myglobs.CurrDriver);

    // 적어도 유효한 드라이버가 1개는 있는 것을 보증한다.

    if (myglobs.NumDrivers == 0) {
        return FALSE;
    }
    lpD3D->lpVtbl->Release(lpD3D);
    lpDD->lpVtbl->Release(lpDD);

    return TRUE;
}

enumDeviceFunc 콜백 함수

enumDeviceFunk 함수는,D3DENUMDEVICESCALLBACK 형의 콜백 함수이다. D3DENUMDEVICESCALLBACK형은 헤더 파일 D3dcaps.h에 정의되고 있다. 시스템은 이 함수에, 인스톨 되고 있는 각 Direct3D 드라이버의 식별자와 이름, 및 하드웨어와 에뮬레이트 된 드라이버의 능력을 통지한다.

콜백 함수는,D3DDEVICEDESC 구조체의dcmColorModel멤버를 사용해, 하드웨어와 열거된 드라이버의 어느 쪽을 조사할까를 결정한다. 이 멤버에 하드웨어가 설정되어 있는 경우, 함수는 하드웨어의 성능을 조사한다.

다음에, 콜백 함수는, 열거된 드라이버가 현재의 컬러 비트수로 렌더링을 실시할 수가 있을지 어떨지를 판정한다. 불가능한 경우는 D3DENUMRET_OK를 돌려주어, 그 드라이버에 관한 나머지의 처리를 스킵 해, 다음의 드라이버의 열거를 계속한다. 콜백 함수는, 로컬 정의의 BPPToDDBD 함수를 이용해 통지된 컬러 비트수와 InitApp 함수에서의GetDeviceCaps함수의 호출에 의해 취득된 색해상도를 비교한다(BPPToDDBD는 bits-per-pixel to DirectDraw bit-depth의 약어이다). BPPToDDBD 함수의 코드에 대해서는, 「BPPToDDBD 헬퍼 함수」를 참조할것.

열거된 드라이버에 대해 간단한 테스트를 실시한 후는,D3DDEVICEDESC구조체의 다른 멤버를 판정한다. 콜백 함수는, 소프트웨어 에뮬레이션보다 하드웨어를, RGB 조명보다 흑백 조명을 선택한다.

/////////////////////////////////////////////////////////////////////
//
// enumDeviceFunc
// 사용 가능한 D3D 드라이버의 이름과 GUID를 기억하는 콜백 함수.
// 드라이버를 선택해, *lpContext로 설정한다.
//
/////////////////////////////////////////////////////////////////////

static HRESULT
WINAPI enumDeviceFunc(LPGUID lpGuid, LPSTR lpDeviceDescription,
    LPSTR lpDeviceName, LPD3DDEVICEDESC lpHWDesc,
    LPD3DDEVICEDESC lpHELDesc, LPVOID lpContext)
{
    static BOOL hardware = FALSE; // 현재의 시작 드라이버는 하드웨어이다.
    static BOOL mono = FALSE;     // 현재의 시작 드라이버는 흑백 조명이다.
    LPD3DDEVICEDESC lpDesc;
    int *lpStartDriver = (int *) lpContext;

    // 어느 디바이스 기술을 조사할까를 결정한다.

    lpDesc = lpHWDesc->dcmColorModel ?  lpHWDesc : lpHELDesc;

    // 현재의 디스플레이의 비트 깊이에서는, 이 드라이버가 렌더링
    // (을)를 실시할 수 없는 경우, 드라이버를 스킵 해 열거를 속행한다.

    if (! (lpDesc->dwDeviceRenderBitDepth & BPPToDDBD(myglobs.BPP)))
        return D3DENUMRET_OK;

    // 이 드라이버의 이름과 GUID를 기억한다.

    memcpy(&myglobs.DriverGUID[myglobs.NumDrivers], lpGuid,
        sizeof(GUID));
    lstrcpy(&myglobs.DriverName[myglobs.NumDrivers][0], lpDeviceName);

    // 소프트웨어보다 하드웨어를, 흑백 조명보다 RGB 조명을 선택한다.

    if (*lpStartDriver == -1) {

        // 이것이 최초의 유효한 드라이버이다.

        *lpStartDriver = myglobs.NumDrivers;
        hardware = lpDesc == lpHWDesc ?  TRUE : FALSE;
        mono = lpDesc->dcmColorModel & D3DCOLOR_MONO ?  TRUE : FALSE;
    } else if (lpDesc == lpHWDesc && ! hardware) {

        // 이 드라이버는 하드웨어이며, 시작 드라이버는 소프트웨어이다.

        *lpStartDriver = myglobs.NumDrivers;
        hardware = lpDesc == lpHWDesc ?  TRUE : FALSE;
        mono = lpDesc->dcmColorModel & D3DCOLOR_MONO ?  TRUE : FALSE;
    } else if ((lpDesc == lpHWDesc && hardware ) ||
               (lpDesc == lpHELDesc && ! hardware)) {
        if (lpDesc->dcmColorModel == D3DCOLOR_MONO && ! mono) {

            // 이 드라이버와 시작 드라이버는 같은 종류이다. 시작 드라이버는
            // RGB 조명이었는데 대해, 이 드라이버는 흑백이다.

            *lpStartDriver = myglobs.NumDrivers;
            hardware = lpDesc == lpHWDesc ?  TRUE : FALSE;
            mono = lpDesc->dcmColorModel & D3DCOLOR_MONO ?  TRUE : FALSE;
        }
    }
    myglobs.NumDrivers++;
    if (myglobs.NumDrivers == MAX_DRIVERS)
        return (D3DENUMRET_CANCEL);
    return (D3DENUMRET_OK);
}

BPPToDDBD 헬퍼 함수

enumDeviceFunc 콜백 함수는, BPPToDDBD 헬퍼 함수를 이용해, 현재의 디바이스가 지원 하는 색해상도를, 열거된 드라이버의 컬러 비트수와 비교할 수 있는 형식으로 변환한다. enumDeviceFunc의 상세한 것에 대하여는, 「enumDeviceFunc 콜백 함수」를 참조할것.

/////////////////////////////////////////////////////////////////////
//
// BPPToDDBD
// 픽셀 당의 비트수를 DirectDraw의 비트 깊이로 변환한다.
//
/////////////////////////////////////////////////////////////////////

static DWORD
BPPToDDBD(int bpp)
{
    switch(bpp) {
        case 1:
            return DDBD_1;
        case 2:
            return DDBD_2;
        case 4:
            return DDBD_4;
        case 8:
            return DDBD_8;
        case 16:
            return DDBD_16;
        case 24:
            return DDBD_24;
        case 32:
            return DDBD_32;
        default:
            return 0;
    }
}

3 D환경의 셋업

이 항에서는, Helworld.c의 코드 가운데, 3 D환경을 구축하는 부분에 도착해 설명한다. 이하의 섹션은, 이 처리를 실행하기 위한 2개의 함수에 대해 설명하고 있다.

  • 디바이스와 뷰포트의 생성
  • 렌더링 스테이트의 설정

이러한 함수는, 3 D환경에 오브젝트나 프레임, 빛을 배치하는 것은 아니다. 장면의 생성은, MyScene 함수와 MyScene 함수가 사용하는 함수군에 의해 실현된다. 3 D환경에 장면을 설정하는 방법에 대해서는, 「장면의 생성」을 참조할것.

디바이스와 뷰포트의 생성

Direct3D 디바이스와 뷰포트는, 어플리케이션의 초기화의 일환으로서 생성 된다. InitApp 함수는, DirectDrawClipper 오브젝트를 생성한 후, DirectDrawClipper 오브젝트와 선택된 드라이버, 및 클라이언트 직사각형의 치수를 파라미터로서 CreateDevAndView 함수를 사용한다.

CreateDevAndView 함수는, 열거 프로세스로 선택된 드라이버를 사용해,IDirect3DRM3::CreateDeviceFromClipper 메소드에 의해 Direct3DRM 디바이스를 생성 한다. 이IDirect3DRMDevice3 인터페이스는, 디바이스의 폭 및 높이를 취득하는IDirect3DRMDevice3::GetWidth 와IDirect3DRMDevice3::GetHeight 메소드의 사용으로 이용된다. CreateDevAndView 함수는, 디바이스의 폭이나 높이의 정보를 받은 후,IDirect3DRM3::CreateViewport 메소드를 사용해IDirect3DRMViewport2 인터페이스를 취득한다.

다음에, CreateDevAndView 함수가,IDirect3DRMViewport2::SetBack 메소드에 의해 뷰포트의 백 클리핑 프레인을 설정 하면, 로컬 정의의 SetRenderState 함수가 사용된다. SetRenderState 함수에 대해서는, 다음의 「렌더링 스테이트의 설정」으로 설명한다.

/////////////////////////////////////////////////////////////////////
//
// CreateDevAndView
// 지정된 D3D 드라이버와 사이즈로 D3DRM 디바이스와
// 뷰포트를 생성 한다.
//
/////////////////////////////////////////////////////////////////////

static BOOL
CreateDevAndView(LPDIRECTDRAWCLIPPER lpDDClipper, int driver,
    int width, int height)
{
    HRESULT rval;

    // 지정된 D3D 드라이버를 이용해 이 윈도우로부터
    // D3DRM 디바이스를 생성 한다.

    lpD3DRM->lpVtbl->CreateDeviceFromClipper(lpD3DRM, lpDDClipper,
        &myglobs.DriverGUID[driver], width, height, &myglobs.dev);

    // 카메라 프레임을 사용해 D3DRM 뷰포트를 생성 한다.
    // 배경의 깊이를 큰 수로 설정한다. 폭과 높이는 대체로
    // 조절되고 있으므로, 디바이스로부터 그 값을 취득한다.

    width = myglobs.dev->lpVtbl->GetWidth(myglobs.dev);
    height = myglobs.dev->lpVtbl->GetHeight(myglobs.dev);
    rval = lpD3DRM->lpVtbl->CreateViewport(lpD3DRM, myglobs.dev,
        myglobs.camera, 0, 0, width, height, &myglobs.view);
    if (rval ! = D3DRM_OK) {
        myglobs.dev->lpVtbl->Release(myglobs.dev);
        return FALSE;
    }
    rval = myglobs.view->lpVtbl->SetBack(myglobs.view, D3DVAL(5000.0));
    if (rval ! = D3DRM_OK) {
        myglobs.dev->lpVtbl->Release(myglobs.dev);
        myglobs.view->lpVtbl->Release(myglobs.view);
        return FALSE;
    }

    // 렌더링의 퀄리티, 전부 칠해 모드, 조명 상태,
    // 컬러 쉐이딩의 정보를 설정한다.

    if (! SetRenderState())
        return FALSE;
    return TRUE;
}

렌더링 스테이트의 설정

Direct3D는스테이트 머신이다. 어플리케이션은, 조명 모듈, 렌더링 모듈, 및 변환 모듈 상태를 설정해, 그것들을 통해 데이터를 송출한다. 이 구조를 의식하는 것은, 직접 모드에 있어서는 불가결하지만, 보관 유지 모드에서는 부분적으로 은폐 되고 있다. 보관 유지 모드 어플리케이션은, SetRenderState 함수에 의해, 렌더링 스테이트를 간단하게 설정할 수가 있다.

우선, SetRenderState 함수는, 빛을 온, 전부 칠해 모드를 솔리드로 해, gouraud shading 모드를 이용하도록(듯이) 지정해,IDirect3DRMDevice3::SetQuality 메소드를 사용한다. 이 때, dither 모드나 텍스쳐의 퀄리티를 변경할 필요가 있는 어플리케이션은,IDirect3DRMDevice3::SetDither 메소드나IDirect3DRMDevice3::SetTextureQuality 메소드를 사용할 수 있다.

/////////////////////////////////////////////////////////////////////
//
// SetRenderState
// 렌더링의 퀄리티와 쉐이딩 정보를 설정한다.
//
/////////////////////////////////////////////////////////////////////

BOOL
SetRenderState(void)
{
    HRESULT rval;

    // 렌더링의 퀄리티(조명의 타글, 전부 칠해 모드, 쉐이딩 모드)를 설정한다.
    rval = myglobs.dev->lpVtbl->SetQuality(myglobs.dev,
        D3DRMLIGHT_ON | D3DRMFILL_SOLID | D3DRMSHADE_GOURAUD);
    if (rval ! = D3DRM_OK) {
        return FALSE;
    }

    // dither 모드를 변경하고 싶은 경우, 여기서 SetDither를 사용한다.

    // 텍스쳐의 퀄리티를 D3DRMTEXTURE_NEAREST(디폴트) 이외
    // (으)로 하고 싶은 경우, 여기서 SetTextureQuality를 사용한다.

   return TRUE;
}

렌더링 루프

WinMain 함수는, 다음의 프레임을 드로잉(Drawing) 하기 위한(해), RenderLoop 함수를 사용한다. RenderLoop 함수는, 몇개의 단순한 처리를 실행한다.

  • IDirect3DRMFrame3::Move 메소드를 사용해, 계층하의 모든 프레임의 회전이나 속도의 적용을 실시한다.
  • IDirect3DRMViewport2::Clear 메소드를 사용해, 현재의 뷰포트를 배경색으로 클리어 한다.
  • IDirect3DRMViewport2::Render 메소드를 사용해, 현재의 장면을 뷰포트에 렌더링 한다.
  • IDirect3DRMDevice3::Update 메소드를 사용해, 렌더링 된 이미지를 스크린에 카피한다.
/////////////////////////////////////////////////////////////////////
//
// RenderLoop
// 뷰포트를 클리어 해 다음의 프레임을 렌더링 해, 윈도우를 갱신한다.
//
/////////////////////////////////////////////////////////////////////

static BOOL
RenderLoop()
{
    HRESULT rval;

    // 현재의 장면을 확인한다.

    rval = myglobs.scene->lpVtbl->Move(myglobs.scene, D3DVAL(1.0));
    if (rval ! = D3DRM_OK) {
        return FALSE;
    }

    // 뷰포트를 클리어 한다.

    rval = myglobs.view->lpVtbl->Clear(myglobs.view);
    if (rval ! = D3DRM_OK) {
        return FALSE;
    }

    // 장면을 뷰포트에 렌더링 한다.

    rval = myglobs.view->lpVtbl->Render(myglobs.view, myglobs.scene);
    if (rval ! = D3DRM_OK) {
        return FALSE;
    }

    // 윈도우를 갱신한다.

    rval = myglobs.dev->lpVtbl->Update(myglobs.dev);
    if (rval ! = D3DRM_OK) {
        return FALSE;
    }
    return TRUE;
}

장면의 생성

3 D환경의 셋업(드라이버의 선택, 3 D디바이스와 뷰포트의 생성, 렌더링 스테이트의 설정등)이 완료 하면, Helworld.c는, 이 3 D환경에 오브젝트나 프레임, 빛을 배치하기 위한 함수군을 사용한다.

  • MyScene 함수
  • MakeMyFrames 함수
  • MakeMyLights 함수
  • SetMyPositions 함수
  • MakeMyMesh 함수
  • MakeMyWrap 함수
  • AddMyTexture 함수

MyScene 함수

Helworld.c의 MyScene 함수는, DirectX SDK의 모든 Direct3D 샘플에 인플리맨트 되고 있는, BuildScene 함수에 상당한다. 어플리케이션의 오브젝트를 텍스쳐나 조명 효과와 함께 표시하는 처리는, 모두 이 함수내에서 행해진다.

MyScene 함수는, 생성 되는 장면의 각 특성을 설정하는, 로컬 정의의 함수군을 사용한다. 이러한 함수를 이하에 나타낸다.

  • MakeMyFrames
  • MakeMyLights
  • SetMyPositions
  • MakeMyMesh
  • MakeMyWrap
  • AddMyTexture

이러한 함수가 비주얼 오브젝트의 셋업을 완료 하면, MyScene 함수는IDirect3DRMFrame3::AddVisual 메소드를 호출해, 오브젝트를 3 D환경의 world 프레임에 추가한다. 그 후는 생성 된 인터페이스는 불필요하게 되기 (위해)때문에, 반복Release 메소드를 사용해, 모든 인터페이스를 릴리즈 할 수가 있다.

/////////////////////////////////////////////////////////////////////
//
// MyScene
// 프레임, 조명, 메쉬, 텍스쳐를 생성 하는 함수를 사용한다.
// 완료하면(자), 모든 인터페이스를 릴리즈 한다.
//
/////////////////////////////////////////////////////////////////////

BOOL
MyScene(LPDIRECT3DRMDEVICE dev, LPDIRECT3DRMVIEWPORT view,
    LPDIRECT3DRMFRAME lpScene, LPDIRECT3DRMFRAME lpCamera)
{
    LPDIRECT3DRMFRAME lpLightframe1 = NULL;
    LPDIRECT3DRMFRAME lpWorld_frame = NULL;
    LPDIRECT3DRMLIGHT lpLight1      = NULL;
    LPDIRECT3DRMLIGHT lpLight2      = NULL;
    LPDIRECT3DRMTEXTURE lpTex       = NULL;
    LPDIRECT3DRMWRAP lpWrap         = NULL;
    LPDIRECT3DRMMESHBUILDER  lpSphere3_builder = NULL;

    MakeMyFrames(lpScene, lpCamera, &lpLightframe1, &lpWorld_frame);
    MakeMyLights(lpScene, lpCamera, lpLightframe1, &lpLight1,
        &lpLight2);
    SetMyPositions(lpScene, lpCamera, lpLightframe1, lpWorld_frame);
    MakeMyMesh(&lpSphere3_builder);
    MakeMyWrap(lpSphere3_builder, &lpWrap);
    AddMyTexture(lpSphere3_builder, &lpTex);

    // 머트리얼을 생성 할 필요가 있는 경우(예를 들어, 빛나 빛나는 면을 생성
    // 하는 경우), 여기서 CreateMaterial와 SetMaterial를 사용한다.

    // 이것으로 비주얼 오브젝트가 생성 되었으므로,
    // 월드 프레임에 추가한다.

    lpWorld_frame->lpVtbl->AddVisual(lpWorld_frame,
        (LPDIRECT3DRMVISUAL) lpSphere3_builder);

    lpLightframe1->lpVtbl->Release(lpLightframe1);
    lpWorld_frame->lpVtbl->Release(lpWorld_frame);
    lpSphere3_builder->lpVtbl->Release(lpSphere3_builder);
    lpLight1->lpVtbl->Release(lpLight1);
    lpLight2->lpVtbl->Release(lpLight2);
    lpTex->lpVtbl->Release(lpTex);
    lpWrap->lpVtbl->Release(lpWrap);

    return TRUE;
}

MakeMyFrames 함수

MyScene 함수는 MakeMyFrames 함수를 사용해, Helworld.c로 이용되는디렉셔널조명 프레임이나 월드 프레임을 생성 한다. MakeMyFrames 함수는,IDirect3DRM3::CreateFrame 메소드를 사용해, 이 처리를 실행한다.

/////////////////////////////////////////////////////////////////////
//
// MakeMyFrames
// 장면에서 사용하는 프레임을 생성 한다.
//
/////////////////////////////////////////////////////////////////////

void MakeMyFrames(LPDIRECT3DRMFRAME lpScene, LPDIRECT3DRMFRAME lpCamera,
    LPDIRECT3DRMFRAME * lplpLightFrame1,
    LPDIRECT3DRMFRAME * lplpWorld_frame)
{
    lpD3DRM->lpVtbl->CreateFrame(lpD3DRM, lpScene, lplpLightFrame1);
    lpD3DRM->lpVtbl->CreateFrame(lpD3DRM, lpScene, lplpWorld_frame);
}

MakeMyLights 함수

MyScene 함수는 MakeMyLights 함수를 사용해, Helworld.c로 이용되는디렉셔널조명이나앰비언트조명을 생성 한다. MakeMyLights 함수는IDirect3DRM3::CreateLightRGB 와IDirect3DRMFrame3::AddLight 메소드를 사용해, 방향을 가진 밝은 조명을 생성해, 그것을 프레임에 추가한다. 또, 어슴푸레한 앰비언트 조명을 생성해, 장면 전체에 추가한다(앰비언트 조명은, 항상 장면 전체에 관련지을 수 있다).

/////////////////////////////////////////////////////////////////////
//
// MakeMyLights
// 장면에서 사용하는 조명을 생성 한다.
//
/////////////////////////////////////////////////////////////////////

void MakeMyLights(LPDIRECT3DRMFRAME lpScene, LPDIRECT3DRMFRAME lpCamera,
    LPDIRECT3DRMFRAME lpLightFrame1,
    LPDIRECT3DRMLIGHT * lplpLight1, LPDIRECT3DRMLIGHT * lplpLight2)
{
    lpD3DRM->lpVtbl->CreateLightRGB(lpD3DRM, D3DRMLIGHT_DIRECTIONAL,
        D3DVAL(0.9), D3DVAL(0.9), D3DVAL(0.9), lplpLight1);

    lpLightFrame1->lpVtbl->AddLight(lpLightFrame1, *lplpLight1);

    lpD3DRM->lpVtbl->CreateLightRGB(lpD3DRM, D3DRMLIGHT_AMBIENT,
        D3DVAL(0.1), D3DVAL(0.1), D3DVAL(0.1), lplpLight2);

    lpScene->lpVtbl->AddLight(lpScene, *lplpLight2);
}

SetMyPositions 함수

MyScene 함수는 SetMyPositions 함수를 사용해, Helworld.c가 사용하는 프레임의 위치와 방향을 설정한다. SetMyPositions 함수는, 이 처리를IDirect3DRMFrame3::SetPosition 및IDirect3DRMFrame3::SetOrientation 메소드의 사용에 의해 실행한다. IDirect3DRMFrame3::SetRotation 메소드는, 구(공)체가 추가되는 프레임에 회전을 설정한다.

/////////////////////////////////////////////////////////////////////
//
// SetMyPositions
// 조명, 카메라, 월드 프레임의 위치와 방향을 설정한다.
// 구(공)체의 회전을 설정한다.
//
/////////////////////////////////////////////////////////////////////

void SetMyPositions(LPDIRECT3DRMFRAME lpScene,
    LPDIRECT3DRMFRAME lpCamera, LPDIRECT3DRMFRAME lpLightFrame1,
    LPDIRECT3DRMFRAME lpWorld_frame)
{

    lpLightFrame1->lpVtbl->SetPosition(lpLightFrame1, lpScene,
        D3DVAL(2), D3DVAL(0.0), D3DVAL(22));

    lpCamera->lpVtbl->SetPosition(lpCamera, lpScene,
        D3DVAL(0.0), D3DVAL(0.0), D3DVAL(0.0));
    lpCamera->lpVtbl->SetOrientation(lpCamera, lpScene,
        D3DVAL(0.0), D3DVAL(0.0), D3DVAL(1),
        D3DVAL(0.0), D3DVAL(1), D3DVAL(0.0));

    lpWorld_frame->lpVtbl->SetPosition(lpWorld_frame, lpScene,
        D3DVAL(0.0), D3DVAL(0.0), D3DVAL(15));
    lpWorld_frame->lpVtbl->SetOrientation(lpWorld_frame, lpScene,
        D3DVAL(0.0), D3DVAL(0.0), D3DVAL(1),
        D3DVAL(0.0), D3DVAL(1), D3DVAL(0.0));

    lpWorld_frame->lpVtbl->SetRotation(lpWorld_frame, lpScene,
        D3DVAL(0.0), D3DVAL(0.1), D3DVAL(0.0), D3DVAL(0.05));
}

MakeMyMesh 함수

MyScene 함수는, Helworld.c로 사용되는 구(공)장의 메쉬를 로드해, 세트 하기 위해서 MakeMyMesh 함수를 사용한다. MekeMyMesh 함수는IDirect3DRM3::CreateMeshBuilder 메소드를 사용해IDirect3DRMMeshBuilder3 인터페이스를 생성한다. 다음에,IDirect3DRMMeshBuilder3::Load ,IDirect3DRMMeshBuilder3::Scale , 및IDirect3DRMMeshBuilder3::SetColorRGB 메소드를 사용해, Sphere3.x 파일이 가리키는 메쉬를 준비한다(Sphere3.x 파일은, DirectX SDK에 수록되고 있다).

/////////////////////////////////////////////////////////////////////
//
// MakeMyMesh
// MeshBuilder 오브젝트를 생성 해, 로드, 스케일링, 메쉬의 채색을 실시한다.
//
/////////////////////////////////////////////////////////////////////

void MakeMyMesh(LPDIRECT3DRMMESHBUILDER  * lplpSphere3_builder)
{
    lpD3DRM->lpVtbl->CreateMeshBuilder(lpD3DRM, lplpSphere3_builder);

    (*lplpSphere3_builder) ->lpVtbl->Load(*lplpSphere3_builder,
        "sphere3.x", NULL, D3DRMLOAD_FROMFILE, NULL, NULL);

    (*lplpSphere3_builder) ->lpVtbl->Scale(*lplpSphere3_builder,
        D3DVAL(2), D3DVAL(2), D3DVAL(2));

    // 예상외의 텍스쳐 블렌딩을 피하기 (위해)때문에, 구(공)체를 흰색으로 설정한다.

    (*lplpSphere3_builder) ->lpVtbl->SetColorRGB(*lplpSphere3_builder,
        D3DVAL(1), D3DVAL(1), D3DVAL(1));
}

MakeMyWrap 함수

MyScene 함수는 MakeMyWrap 함수를 사용해 텍스쳐 좌표를 생성 해, MakeMyMesh 함수가 로드한 구(공)체에 적용한다. MakeMyWrap 함수는, 구(공)체를 포함한 경계 박스를 취득하기 위해서IDirect3DRMMeshBuilder3::GetBox 메소드를 호출해, 그 경계 박스의 사이즈를IDirect3DRM3::CreateWrap 메소드의 호출시에 사용한다. IDirect3DRM3::CreateWrap메소드는 원기둥(실린더)의 텍스쳐 랩을 생성 해,IDirect3DRMWrap 인터페이스를 취득한다. 텍스쳐 좌표를 구(공)체에 적용하려면 ,IDirect3DRMWrap::Apply 메소드의 호출을 실시한다.

/////////////////////////////////////////////////////////////////////
//
// MakeMyWrap
// 랩을 생성 해, 텍스쳐에 적용한다.
//
/////////////////////////////////////////////////////////////////////

void MakeMyWrap(LPDIRECT3DRMMESHBUILDER  sphere3_builder,
                LPDIRECT3DRMWRAP * lpWrap)
{
    D3DVALUE miny, maxy, height;
    D3DRMBOX box;

    sphere3_builder->lpVtbl->GetBox(sphere3_builder, &box);

    maxy = box.max.y;
    miny = box.min.y;
    height = maxy - miny;

    lpD3DRM->lpVtbl->CreateWrap
        (lpD3DRM, D3DRMWRAP_CYLINDER, NULL,
        D3DVAL(0.0), D3DVAL(0.0), D3DVAL(0.0),
        D3DVAL(0.0), D3DVAL(1.0), D3DVAL(0.0),
        D3DVAL(0.0), D3DVAL(0.0), D3DVAL(1.0),
        D3DVAL(0.0), D3DDivide(miny, height),
        D3DVAL(1.0), D3DDivide(D3DVAL(1.0), height),
        lpWrap);

    (*lpWrap) ->lpVtbl->Apply(*lpWrap, (LPDIRECT3DRMOBJECT)
        sphere3_builder);

}

AddMyTexture 함수

MyScene 함수는, AddMyTexture 함수를 사용해 텍스쳐를 로드해, 구(공)에 관련짓는다. AddMyTexture은,IDirect3DRM3::LoadTexture 메소드를 사용해 Tutor.bmp 비트 맵을 로드한 후,IDirect3DRMMeshBuilder3::SetTexture 메소드를 호출해 그 비트 맵을 구(공)에 관련짓는다.

구(공) 위에의 텍스쳐로서 사용되는 비트 맵

/////////////////////////////////////////////////////////////////////
//
// AddMyTexture
// 랩을 생성 해, 텍스쳐에 적용한다.
//
/////////////////////////////////////////////////////////////////////

void AddMyTexture(LPDIRECT3DRMMESHBUILDER  lpSphere3_builder,
    LPDIRECT3DRMTEXTURE * lplpTex)
{
    lpD3DRM->lpVtbl->LoadTexture(lpD3DRM, "tutor.bmp", lplpTex);

    // 디폴트(16) 이외의 컬러 깊이가 필요한 경우, 여기서
    // IDirect3DRMTexture::SetShades를 사용한다.

    lpSphere3_builder->lpVtbl->SetTexture(lpSphere3_builder, *lplpTex);

}

종료 처리

Helworld.c는, WM_DESTROY 메세지를 받아들였을 때, 또는 RenderLoop 함수의 사용에 몇번이나 실패했을 때, CleanUp 함수를 사용한다.

/////////////////////////////////////////////////////////////////////
//
// CleanUp
// 모든 D3DRM 오브젝트를 릴리즈 해, bQuit 플래그를 세트 한다.
//
/////////////////////////////////////////////////////////////////////

void
CleanUp(void)
{
    myglobs.bInitialized = FALSE;
    myglobs.scene->lpVtbl->Release(myglobs.scene);
    myglobs.camera->lpVtbl->Release(myglobs.camera);
    myglobs.view->lpVtbl->Release(myglobs.view);
    myglobs.dev->lpVtbl->Release(myglobs.dev);
    lpD3DRM->lpVtbl->Release(lpD3DRM);
    lpDDClipper->lpVtbl->Release(lpDDClipper);

    myglobs.bQuit = TRUE;
}


C++/COM 레퍼런스

Microsoft® Direct3D®보관 유지 모드의 레퍼런스는, 인터페이스, 메소드 (인터페이스 멤버 함수), 비멤버 함수, 콜백 함수에 대해, 구문, 파라미터 기술, 플래그 기술등의 상세 정보를 제공한다. 또, Direct3D 보관 유지 모드의 구조체 멤버, 열거형, 그 외의 정의제타입, 돌려주어질 가능성이 있는 에러값에 대해서도 기술한다. 이 항에는, 다음의 주제가 포함된다.

함수와 인터페이스

  • 콜백 함수
  • 인터페이스
  • 비멤버 함수

데이터 타입

  • 정수
  • 열거형
  • 구조체

다른 주제

  • 반환값
  • 추가 정보


C++콜백 함수

Microsoft® Direct3D® 보관 유지 모드의 C++콜백 함수는 다음과 같다.

  • D3DRMDEVICE3UPDATECALLBACK (D3DRMUPDATECALLBACK와 교환)
  • D3DRMDOWNSAMPLECALLBACK
  • D3DRMFRAME3MOVECALLBACK (D3DRMFRAMEMOVECALLBACK와 교환)
  • D3DRMLOADCALLBACK
  • D3DRMLOADTEXTURECALLBACK
  • D3DRMLOADTEXTURE3CALLBACK
  • D3DRMOBJECTCALLBACK
  • D3DRMUSERVISUALCALLBACK
  • D3DRMVALIDATIONCALLBACK
  • D3DRMWRAPCALLBACK

D3DRMDEVICE3UPDATECALLBACK

디바이스가 변경되었을 때는 어플리케이션에 경고한다. 이 콜백 함수의 실체는 어플리케이션 정의이다.

구문

void (*D3DRMDEVICE3UPDATECALLBACK)(
  LPDIRECT3DRMDEVICE3 lpobj,
  LPVOID lpArg,
  int iRectCount,
  LPD3DRECT d3dRectUpdate);

파라미터

lpobj
콜백 함수를 적용하는Direct3DRMDevice3 오브젝트에의 포인터의 주소.
lpArg
콜백 함수에게 건네지는 어플리케이션 정의의 데이터에의 포인터의 주소.
iRectCount
d3dRectUpdate파라미터로 지정된 직사각형의 수.
d3dRectUpdate
갱신되는 영역을 나타내는, 1개이상의D3DRECT 구조체의 배열. 좌표는 디바이스 단위로 지정된다.

반환값

없음.

주의

시스템은, 콜백 함수를 사용하는 순서를 결정하기 (위해)때문에, 우선 계층의 톱 레벨에 있는 오브젝트를 검색한다. 다음에, 생성 된 차례로 콜백 함수를 사용한다.

D3DRMDEVICE3UPDATECALLBACK는 DirectX version 6.0으로 도입되어 이전의D3DRMUPDATECALLBACK의 교체이다. 이 2개의 콜백의 상위는, 신규의 콜백이lpobj파라미터에 대해서는Direct3DRMDevice오브젝트가 아니고Direct3DRMDevice3오브젝트를 취하는 것 뿐이다.

참조

IDirect3DRMDevice3::AddUpdateCallback , IDirect3DRMDevice3::DeleteUpdateCallback , IDirect3DRMDevice3::Update

D3DRMDOWNSAMPLECALLBACK

비디오 메모리가 overload 해, 텍스쳐 표면의 사이즈를 삭감할 필요가 있을 때 불려 간다. Direct3D 보관 유지 모드에서는, DirectDraw 블록 전송과 쌍일차 필터링등의 텍스쳐 사이즈를 삭감하는 디폴트의 메소드가 제공되지만, 유저는, 독자적인 메소드를 정의해, 이 콜백 함수로 텍스쳐 사이즈를 스케일 다운할 수가 있다. 이 콜백 함수의 실체는 어플리케이션으로 정의된다.

구문

HRESULT (*D3DRMDOWNSAMPLECALLBACK)(
  LPDIRECT3DRMTEXTURE3 lpDirect3DRMTexture,
  LPVOID lpArg,
  LPDIRECTDRAWSURFACE pDDSSrc,
  LPDIRECTDRAWSURFACE pDDSDst);

파라미터

lpDirect3DRMTexture
콜백 함수를 적용하는Direct3DRMTexture3 오브젝트에의 포인터의 주소.
lpArg
콜백 함수에게 건네지는 어플리케이션 정의의 데이터에의 포인터의 주소.
pDDSSrc
시스템 메모리 prototype 표면에의 포인터.
pDDSDst
스케일 다운된 표면에의 포인터.

반환값

없음.

주의

D3DRMDOWNSAMPLECALLBACK는, DirectX version 6.0과 함께 도입되었다.

참조

IDirect3DRMTexture3::SetDownsampleCallback

D3DRMFRAME3MOVECALLBACK

프레임의 이동이나 갱신시에, 어플리케이션이 커스터마이즈 한 알고리즘을 적용할 수 있도록(듯이) 한다. frame rate를 변경하기 위해서 이 콜백 함수를 사용할 수가 있다. 이 콜백 함수의 실체는 어플리케이션으로 정의된다.

구문

void (*D3DRMFRAME3MOVECALLBACK)(
  LPDIRECT3DRMFRAME3 lpD3DRMFrame,
  LPVOID lpArg,
  D3DVALUE delta);

파라미터

lpD3DRMFrame
변경하려고 하고 있는Direct3DRMFrame3 오브젝트에의 포인터의 주소.
lpArg
콜백 함수에게 건네지는 어플리케이션 정의의 데이터에의 포인터의 주소.
delta
운동에 적용되는 변화량. 프레임의 위치를 변경하려면 , 직선과 회전의 2개의 요소가 있다. 각 요소에 있어서의 변경은,velocity_of_component×delta에 동일하다. 이러한 한편 또는 양쪽 모두의 속도는, 임의의 프레임을 기점으로서 설정할 수가 있지만, 시스템은, 자동적으로 델타 시간을 적용하므로, 친프레임을 기점으로 한 속도로 변환한다.

반환값

없음.

주의

어플리케이션은, 친프레임을 기준으로 해 프레임의 가속을 합성할 수가 있다. 그 때문에(위해)는, 각 틱으로, 어플리케이션은, 아이 프레임의 속도를 어플리케이션 자신을 기준으로 한(1 틱 근처a유니트)×1 틱으로 설정할 필요가 있다. 여기서, a는 요구된 가속도이다. 이것은, 틱 당의a×delta에 동일하다. 내부적으로는, 아이 프레임을 기준으로 한 틱 당의a×delta는, 친프레임을 기준으로 한(v+(a×delta)) 유니트에 변환된다. 여기서,v는, 부모를 기준으로 하는 아이 프레임의 현재의 속도이다.

이 콜백 함수를 추가/삭제하려면 ,IDirect3DRMFrame3::AddMoveCallback 및IDirect3DRMFrame3::DeleteMoveCallback 메소드를 사용한다.

시스템은, 콜백 함수를 사용하는 순서를 결정하기 (위해)때문에, 우선 계층의 톱 레벨에 있는 오브젝트를 검색한다. 다음에, 생성 된 차례로 콜백 함수를 사용한다.

D3DRMFRAME3MOVECALLBACK는, DirectX version 6.0으로 도입되어 구의D3DRMFRAMEMOVECALLBACK를 치환한다. 이 2개의 콜백의 상위는, 신규의 콜백이lpD3DRMFrame파라미터에 대해서는Direct3DRMFrame오브젝트가 아니고Direct3DRMFrame3오브젝트를 취하는 것 뿐이다.

D3DRMLOADCALLBACK

IDirect3DRM3::Load 메소드 내부에서 오브젝트의 로드를 실시한다. 이 콜백 함수의 실체는 어플리케이션으로 정의된다.

구문

void (*D3DRMLOADCALLBACK)(
  LPDIRECT3DRMOBJECT lpObject,
  REFIID ObjectGuid,
  LPVOID lpArg);

파라미터

lpObject
로드 되는 Direct3DRMObject에의 포인터의 주소.
ObjectGuid
로드 되는 오브젝트의 글로벌 유니크 식별자(GUID).
lpArg
콜백 함수에게 건네지는 어플리케이션 정의의 데이터에의 포인터의 주소.

반환값

없음.

주의

시스템은, 콜백 함수를 사용하는 순서를 결정하기 (위해)때문에, 우선 계층의 톱 레벨에 있는 오브젝트를 검색한다. 다음에, 생성 된 차례로 콜백 함수를 사용한다.

참조

IDirect3DRM3::Load

D3DRMLOADTEXTURECALLBACK

Load메소드의 내부에서, 텍스쳐 파일(혹은 리소스)의 실제의 read를 실시한다. 이 콜백 함수의 실체는 어플리케이션으로 정의된다.

구문

HRESULT (*D3DRMLOADTEXTURECALLBACK)(
  char *tex_name,
  void *lpArg,
  LPDIRECT3DRMTEXTURE *lpD3DRMTex);

파라미터

tex_name
텍스쳐명에의 포인터의 주소.
lpArg
어플리케이션 고유의 데이터에의 포인터의 주소.
lpD3DRMTex
Direct3DRMTexture 오브젝트에의 포인터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

정확한 참조 카운트를 유지하려면 , 텍스쳐 콜백으로 생성 된 텍스쳐 오브젝트 위에의AddRef를 호출한다.

어플리케이션은, Microsoft® Windows®비트 맵(. bmp)나 휴대용 픽셀 맵 비트 맵(. ppm) P6형식 이외의 텍스쳐의 지원을 인플리맨트 하기 위한(해), 이 콜백 함수를 사용할 수가 있다. P6포맷은, 색이미지의 바이노리필드 포맷이다.

시스템은, 콜백 함수를 사용하는 순서를 결정하기 (위해)때문에, 우선 계층의 톱 레벨에 있는 오브젝트를 검색한다. 다음에, 생성 된 차례로 콜백 함수를 사용한다.

참조

IDirect3DRM3::Load , IDirect3DRMAnimationSet2::Load , IDirect3DRMFrame3::Load , IDirect3DRMMeshBuilder3::Load

D3DRMLOADTEXTURE3CALLBACK

Load메소드의 내부에서, 텍스쳐 파일(혹은 리소스)의 실제의 read를 실시한다. 이 콜백 함수의 실체는 어플리케이션으로 정의된다.

구문

HRESULT (*D3DRMLOADTEXTURE3CALLBACK)(
  char *tex_name,
  void *lpArg,
  LPDIRECT3DRMTEXTURE3 *lpD3DRMTex3);

파라미터

tex_name
텍스쳐명에의 포인터의 주소.
lpArg
어플리케이션 고유의 데이터에의 포인터의 주소.
lpD3DRMTex3
Direct3DRMTexture3 오브젝트에의 포인터의 주소.

반환값

성공하면 D3DRM_OK를 돌려준다. 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

정확한 참조 카운트를 유지하려면 , 텍스쳐 콜백으로 생성 된 텍스쳐 오브젝트 위에의AddRef를 호출한다.

어플리케이션은, Microsoft® Windows®비트 맵(. bmp)나 휴대용 픽셀 맵 비트 맵(. ppm) P6형식 이외의 텍스쳐의 지원을 인플리맨트 하기 위한(해), 이 콜백 함수를 사용할 수가 있다. P6포맷은, 색이미지의 바이노리필드 포맷이다.

시스템은, 콜백 함수를 사용하는 순서를 결정하기 (위해)때문에, 우선 계층의 톱 레벨에 있는 오브젝트를 검색한다. 다음에, 생성 된 차례로 콜백 함수를 사용한다.

참조

IDirect3DRM3::Load , IDirect3DRMAnimationSet2::Load , IDirect3DRMFrame3::Load , IDirect3DRMMeshBuilder3::Load

D3DRMOBJECTCALLBACK

IDirect3DRM3::EnumerateObjects 메소드의 호출해에 응답하는 오브젝트를 열거한다. 이 콜백 함수의 실체는 어플리케이션 정의이다.

구문

void (*D3DRMOBJECTCALLBACK)(
  LPDIRECT3DRMOBJECT lpD3DRMobj,
  LPVOID lpArg);

파라미터

lpD3DRMobj
오브젝트를 열거하는IDirect3DRMObject 인터페이스에의 포인터. 어플리케이션은, 열거된 각 오브젝트에 대해Release메소드를 호출하지 않으면 안 된다.
lpArg
콜백 함수에게 건네지는 어플리케이션 정의의 데이터에의 포인터의 주소.

반환값

없음.

주의

시스템은, 콜백 함수를 사용하는 순서를 결정하기 (위해)때문에, 우선 계층의 톱 레벨에 있는 오브젝트를 검색한다. 다음에, 생성 된 차례로 콜백 함수를 사용한다.

참조

IDirect3DRM3::EnumerateObjects

D3DRMUSERVISUALCALLBACK

유저 비주얼 오브젝트를 제공하는 어플리케이션에, 실행 버퍼를 실행할 필요가 있는 것을 통지한다. 이 콜백 함수의 실체는 어플리케이션 정의이다.

구문

int (*D3DRMUSERVISUALCALLBACK)(
  LPDIRECT3DRMUSERVISUAL lpD3DRMUV,
  LPVOID lpArg,
  D3DRMUSERVISUALREASON lpD3DRMUVreason,
  LPDIRECT3DRMDEVICE lpD3DRMDev,
  LPDIRECT3DRMVIEWPORT lpD3DRMview);

파라미터

lpD3DRMUV
Direct3DRMUserVisual 오브젝트에의 포인터의 주소.
lpArg
콜백 함수에게 건네지는 어플리케이션 정의의 데이터에의 포인터의 주소.
lpD3DRMUVreason
D3DRMUSERVISUALREASON 열거형의 멤버의 하나.
D3DRMUSERVISUAL_CANSEE
유저 비주얼 오브젝트가 뷰포트내에서 가시 상태이면, 어플리케이션은 TRUE를 돌려준다. 이 경우, 어플리케이션은,lpD3DRMview파라미터로 지정된 디바이스를 사용한다.
D3DRMUSERVISUAL_RENDER
어플리케이션은, 유저 비주얼 엘리먼트를 렌더링 하지 않으면 안 된다. 이 경우, 어플리케이션은,lpD3DRMDev파라미터로 지정된 디바이스를 사용한다.
lpD3DRMDev
Direct3DRMUserVisual 오브젝트를 렌더링 하기 위해서 사용되는 Direct3DRMDevice 오브젝트에의 포인터의 주소.
lpD3DRMview
Direct3DRMUserVisual 오브젝트가 가시 상태인가 어떤가를 결정하기 위해서(때문에) 사용되는 Direct3DRMViewport 오브젝트에의 포인터의 주소.

반환값

lpD3DRMUVreason파라미터에 D3DRMUSERVISUAL_CANSEE가 지정되어 유저 비주얼 오브젝트가 뷰포트내에서 가시 상태의 경우는 TRUE를 돌려준다. 그렇지 않은 경우는 FALSE를 돌려준다. lpD3DRMUVreason파라미터에 D3DRMUSERVISUAL_RENDER가 지정되고 있는 경우는 어플리케이션 정의의 반환값이 된다. 이 경우, 항상 TRUE를 돌려주는 것이 안전하다.

주의

어플리케이션이 렌더링 상태를 변경하는 경우, 이 함수로부터 복귀하기 전에 렌더링 상태를 복원할 필요가 있다.

시스템은, 콜백 함수를 사용하는 순서를 결정하기 (위해)때문에, 우선 계층의 톱 레벨에 있는 오브젝트를 검색한다. 다음에, 생성 된 차례로 콜백 함수를 사용한다.

참조

IDirect3DRMUserVisual::Init , IDirect3DRM3::CreateUserVisual

D3DRMVALIDATIONCALLBACK

변경제이지만 갱신되어 있지 않은 것을 의미하는, 무효의 마크를 붙일 수 있었던 텍스쳐-존을 갱신할 필요가 있을 때 불려 간다. 이 콜백 함수의 실체는 어플리케이션으로 정의된다.

구문

HRESULT (*D3DRMVALIDATIONCALLBACK)(
  LPDIRECT3DRMTEXTURE3 lpDirect3DRMTexture,
  LPVOID lpArg,
  DWORD dwFlags,
  DWORD dwcRects,
  LPRECT pRects);

파라미터

lpDirect3DRMTexture
콜백 함수를 적용하는Direct3DRMTexture3 오브젝트에의 포인터의 주소.
lpArg
콜백 함수에게 건네지는 어플리케이션 정의의 데이터에의 포인터의 주소.
dwFlags
사용하지 않는다. 0으로 하는 것
dwcRects
pRects파라미터로 지정된 직사각형의 수.
pRects
갱신되는 영역을 나타내는, 1개이상의RECT구조체의 배열. 좌표는 디바이스 단위로 지정된다.

반환값

없음.

주의

Direct3D 보관 유지 모드에 대해서, 텍스쳐-존의 변경을 통지하지만, 그 변경을 보류하는 경우, 리젼은 무효이다고 선언해, 리젼을pRects가 가리키는 배열에 저장 할 수가 있다. 그 후, 텍스쳐가 필요하게 되면, 이 콜백 함수를 호출해, 어플리케이션에 텍스쳐-존을 갱신하는 것을 통지한다.

D3DRMVALIDATIONCALLBACK는, DirectX version 6.0과 함께 도입되었다.

참조

IDirect3DRMTexture3::SetValidationCallback

D3DRMWRAPCALLBACK

이 콜백 함수는 지원되어 있지 않다.

구문

void (*D3DRMWRAPCALLBACK)(
  LPD3DVECTOR lpD3DVector,
  int *lpU,
  int *lpV,
  LPD3DVECTOR lpD3DRMVA,
  LPD3DVECTOR lpD3DRMVB,
  LPVOID lpArg);


C++인터페이스

이 항에는, 다음의 Microsoft® Direct3D®보관 유지 모드의 C++인터페이스에 관한 정보가 포함된다.

  • IDirect3DRM3
  • IDirect3DRMAnimation2
  • IDirect3DRMAnimationArray
  • IDirect3DRMAnimationSet2
  • IDirect3DRMArray
  • IDirect3DRMClippedVisual
  • IDirect3DRMDevice3
  • IDirect3DRMDeviceArray
  • IDirect3DRMFace2
  • IDirect3DRMFaceArray
  • IDirect3DRMFrame3
  • IDirect3DRMFrameArray
  • IDirect3DRMInterpolator
  • IDirect3DRMLight
  • IDirect3DRMLightArray
  • IDirect3DRMMaterial2
  • IDirect3DRMMesh
  • IDirect3DRMMeshBuilder3
  • IDirect3DRMObject
  • IDirect3DRMObject2
  • IDirect3DRMObjectArray
  • IDirect3DRMPicked2Array
  • IDirect3DRMPickedArray
  • IDirect3DRMProgressiveMesh
  • IDirect3DRMShadow2
  • IDirect3DRMTexture3
  • IDirect3DRMUserVisual
  • IDirect3DRMViewport2
  • IDirect3DRMViewportArray
  • IDirect3DRMVisual
  • IDirect3DRMVisualArray
  • IDirect3DRMWinDevice
  • IDirect3DRMWrap


IDirect3DRM3

어플리케이션은,IDirect3DRM3인터페이스를 사용해 Direct3DRM3 오브젝트를 생성해, 시스템 레벨 변수에 따라 동작한다. Direct3D 보관 유지 모드 인터페이스의 이력에 대해서는, 「인터페이스의 변경점」을 참조할것.

IDirect3DRM3 ,IDirect3DRM2, 및IDirect3DRM인터페이스의 메소드는, 다음의 오브젝트를 생성 한다.

  • 애니메이션과 애니메이션 세트
  • 클립 비주얼
  • 디바이스
  • 면
  • 프레임
  • 범비초기화 오브젝트
  • 조명
  • 머트리얼
  • 메쉬와 메쉬 빌더
  • 영
  • 텍스쳐
  • 유저 비주얼
  • 뷰포트
  • 랩

Microsoft DirectX version 6.0은,IDirect3DRM3인터페이스를 도입하고 있다. IDirect3DRM3는,IDirect3DRM2와IDirect3DRM인터페이스가 제공하는 모든 메소드를 지원 해, 이것들 2개의 구인터페이스를 치환한다. 이것은, 플래그 파라미터를IDirect3DRM2의CreateDeviceFromSurface 에 추가해,RegisterClient ,UnregisterClient 및CreateClippedVisual 메소드를IDirect3DRM2가 제공하는 메소드에 추가한다. IDirect3DRM3는, 왼손 또는 오른손 지오메트리의 어느 쪽을 사용할까를 세트 해 꺼내는GetOptions 와SetOptions 메소드도 추가한다.

IDirect3DRM3는,IDirect3DRM2와 같게IDirect3DRM중의 모든 메소드를 지원 한다. 이것은,CreateProgressiveMesh 메소드를IDirect3DRM가 제공하는 메소드에 추가한다. CreateDeviceFromSurface ,CreateDeviceFromD3D 및CreateDeviceFromClipper 메소드는 모두,IDirect3DRM2에 의해 DIRECT3DRMDEVICE2 오브젝트를 생성 해,IDirect3DRM3에 의해 DIRECT3DRMDEVICE3 오브젝트를 생성 한다. CreateViewport 메소드는, DirectDRMDevice2 오브젝트상에 뷰포트를 생성 한다. LoadTexture 과LoadTextureFromResource 메소드는,IDirect3DRM2에 의해 Direct3DRMTexture2 오브젝트를 로드해,IDirect3DRM3에 의해 Direct3DRMTexture3 오브젝트를 로드한다.

IDirect3DRM3또는IDirect3DRM2 COM (Component Object Model) 인터페이스에 액세스 하려면 ,Direct3DRMCreate 에 의해IDirect3DRM오브젝트를 생성 해, 다음에IDirect3DRM로부터 각각IDirect3DRM3또는IDirect3DRM2를 조회한다. 또,CoCreateInstance를 직접 사용해 메인의 Direct3D 보관 유지 모드 오브젝트에 액세스 할 수가 있다.

IDirect3DRM3인터페이스를 사용해 MeshBuilder 오브젝트를 생성 하면, MeshBuilder는, 그 임플리멘테이션에 직접 모드의DrawPrimitive인터페이스를 사용한다.

IDirect3DRM3인터페이스를 사용해 조명을 생성 하면, 조명은 최신의 직접 모드 기능을 활용해, D3DLIGHT2 구조체를 사용하게 된다.

어플리케이션은IDirect3DRMDevice3 ,IDirect3DRMDevice2,IDirect3DRMDevice인터페이스를 사용해 출력 디바이스라고 회화한다. IDirect3DRM3,IDirect3DRM2또는IDirect3DRM인터페이스를 사용해 생성 할 때의 출력 디바이스 기능의 상세한 것에 대하여는, 「IDirect3DRMDevice3 」를 참조할것. 출력 디바이스의 개요에 대해서는, 「출력 디바이스」를 참조할것.

IDirect3DRM3인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.
애니메이션 | CreateAnimation
 | CreateAnimationSet
어플리케이션 고유의 데이터 | RegisterClient
 | UnregisterClient
클립 비주얼 | CreateClippedVisual
디바이스 | CreateDevice
 | CreateDeviceFromClipper
 | CreateDeviceFromD3D
 | CreateDeviceFromSurface
 | GetDevices
열거 | EnumerateObjects
면 | CreateFace
프레임 | CreateFrame
조명 | CreateLight
 | CreateLightRGB
머트리얼 | CreateMaterial
메쉬 | CreateMesh
 | CreateMeshBuilder
그 외 | CreateObject
 | CreateUserVisual
 | GetNamedObject
 | GetOptions
 | Load
 | SetOptions
 | Tick
프로그래시브 메쉬 | CreateProgressiveMesh
패스 검색 | AddSearchPath
 | GetSearchPath
 | SetSearchPath
영 | CreateShadow
텍스쳐 | CreateTexture
 | CreateTextureFromSurface
 | LoadTexture
 | LoadTextureFromResource
 | SetDefaultTextureColors
 | SetDefaultTextureShades
뷰포트 | CreateViewport
랩 | CreateWrap

모든 COM 인터페이스와 같이,IDirect3DRM3인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는 다음의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

IDirect3DRM3::AddSearchPath

IDirect3DRM3

현재의 파일 검색 패스의 마지막에 디렉토리의 리스트를 추가한다.

구문

HRESULT AddSearchPath(
  LPCSTR lpPath
  );

파라미터

lpPath
현재의 검색 패스에 추가하는 패스를 지정하는 눌 종단 캐릭터 라인의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

Microsoft® Windows®에서는, 패스는, 세미콜론(;)으로 단락지어진 리스트로 할 필요가 있다.

참조

IDirect3DRM3::SetSearchPath

IDirect3DRM3::CreateAnimation

IDirect3DRM3

하늘의 Direct3DRMAnimation 오브젝트를 생성한다.

구문

HRESULT CreateAnimation(
  LPDIRECT3DRMANIMATION2  *lplpD3DRMAnimation
  );

파라미터

lplpD3DRMAnimation
호출이 성공했을 경우,IDirect3DRMAnimation2 인터페이스에의 포인터가 세트 되는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRM3::CreateAnimationSet

IDirect3DRM3

하늘의 Direct3DRMAnimationSet 오브젝트를 생성 한다.

구문

HRESULT CreateAnimationSet (
  LPDIRECT3DRMANIMATIONSET2  *lplpD3DRMAnimationSet
  );

파라미터

lplpD3DRMAnimationSet
호출이 성공하면,IDirect3DRMAnimationSet2 인터페이스에의 포인터가 세트 되는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRM3::CreateClippedVisual

IDirect3DRM3

클립 비주얼 오브젝트를 생성 한다.

구문

HRESULT CreateClippedVisual(
  LPDIRECT3DRMVISUAL lpVisual,
  LPDIRECT3DRMCLIPPEDVISUAL  *lpClippedVisual);

파라미터

lpVisual
메쉬 빌더 오브젝트등의 비주얼 오브젝트에의 포인터.
lpClippedVisual
생성 된IDirect3DRMClippedVisual 클립 비주얼 오브젝트를 받는 포인터.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRM3::CreateDevice

IDirect3DRM3

Windows 플랫폼에서는 미이행이다.

구문

HRESULT CreateDevice(
  DWORD dwWidth,
  DWORD dwHeight,
  LPDIRECT3DRMDEVICE3 *lplpD3DRMDevice
  );

IDirect3DRM3::CreateDeviceFromClipper

IDirect3DRM3

지정된 DirectDrawClipper 오브젝트를 사용해 Direct3D 보관 유지 모드 Windows 디바이스를 생성한다.

구문

HRESULT CreateDeviceFromClipper(
  LPDIRECTDRAWCLIPPER lpDDClipper,
  LPGUID lpGUID,
  int width,
  int height,
  LPDIRECT3DRMDEVICE3  *lplpD3DRMDevice
  );

파라미터

lpDDClipper
DirectDrawClipper 오브젝트의 주소.
lpGUID
글로벌 유니크 식별자(GUID)의 주소. 이 파라미터는 NULL로 할 수 있다.
width, height
생성 해야 할 디바이스의 폭과 높이.
lplpD3DRMDevice
호출이 성공했을 경우,IDirect3DRMDevice3 인터페이스에의 포인터가 세트 되는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

lpGUID파라미터가 NULL의 경우, 시스템은, 디바이스 성능의 디폴트 세트를 검색한다. 이것은, 보관 유지 모드 디바이스를 생성하는 방법으로서 추천 한다. 왜냐하면, 유저가 새로운 하드웨어를 인스톨 했을 경우에서도, 항상 기능하기 때문이다.

시스템은, 내부 디바이스 열거의 호출로,D3DPRIMCAPS 구조체로부터의 이하의 플래그를 사용해, 디폴트 설정값을 기술한다.
D3DPSHADECAPS_ALPHAFLATSTIPPLED
D3DPTBLENDCAPS_COPY | D3DPTBLENDCAPS_MODULATE
D3DPMISCCAPS_CULLCCW
D3DPRASTERCAPS_FOGVERTEX
D3DPCMPCAPS_LESSEQUAL
D3DPTFILTERCAPS_NEAREST
D3DPTEXTURECAPS_PERSPECTIVE | D3DPTEXTURECAPS_TRANSPARENCY
D3DPTADDRESSCAPS_WRAP

하드웨어 데이 버스가 검출되지 않았던 경우에는, 흑백(램프)의 소프트웨어 드라이버가 로드 된다. 특별한 요건이 있어, 디폴트 설정값의 이 리스트에서는 만족할 수 없는 경우, 어플리케이션은,lpGUID에 대해서 NULL를 지정하는 대신에 디바이스를 열거할 필요가 있다.

디바이스에 대한 자세한 것은, 「출력 디바이스」 및 「IDirect3DRMDevice3 」를 참조할것.

IDirect3DRM3::CreateDeviceFromD3D

IDirect3DRM3

지정된 Direct3D 오브젝트를 사용해, Direct3D 보관 유지 모드 Windows 디바이스를 생성한다.

구문

HRESULT CreateDeviceFromD3D(
  LPDIRECT3D2 lpD3D,
  LPDIRECT3DDEVICE2 lpD3DDev,
  LPDIRECT3DRMDEVICE3  *lplpD3DRMDevice
  );

파라미터

lpD3D
Direct3D 직접 모드Direct3D2오브젝트의 인스턴스에의 포인터.
lpD3DDev
Direct3D 직접 모드Direct3DDevice2오브젝트에의 포인터.
lplpD3DRMDevice
호출이 성공했을 경우,IDirect3DRMDevice3 인터페이스에의 포인터가 세트 되는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

디바이스에 대한 자세한 것은, 「출력 디바이스」 및 「IDirect3DRMDevice3 」를 참조할것.

IDirect3DRM3::CreateDeviceFromSurface

IDirect3DRM3

지정된 DirectDraw 표면으로부터 렌더링하기 위한 Direct3D 보관 유지 모드 Windows 디바이스를 생성한다.

구문

HRESULT CreateDeviceFromSurface(
  LPGUID lpGUID,
  LPDIRECTDRAW lpDD,
  LPDIRECTDRAWSURFACE lpDDSBack,
  DWORD dwFlags,
  LPDIRECT3DRMDEVICE3 *lplpD3DRMDevice);

파라미터

lpGUID
요구된 디바이스 드라이버로서 사용되는 글로벌 유니크 식별자(GUID)의 주소. 이 파라미터가 NULL의 경우, 디폴트의 디바이스 드라이버가 사용된다.
lpDD
DirectDraw 표면의 소스인 DirectDraw 오브젝트의 주소.
lpDDSBack
백 버퍼를 나타내는DirectDrawSurface오브젝트의 주소.
dwFlags
현재 정의되고 있는 유일한 플래그는, 다음과 같다.
D3DRMDEVICE_NOZBUFFER
lpDDSBack파라미터에 z버퍼가 Attach되어 있지 않으면, z버퍼가 생성 되지 않는 것을 나타낸다. 디폴트에서는, z버퍼가 생성 된다.
lplpD3DRMDevice
호출이 성공했을 경우,IDirect3DRMDevice3 인터페이스에의 포인터가 세트 되는 주소.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다. 이 메소드는,dwFlags파라미터를, 그것이 치환하는 구의IDirect3DRM2::CreateDeviceFromSurface메소드에 추가한다.

디바이스에 대한 자세한 것은, 「출력 디바이스」 및 「IDirect3DRMDevice3 」를 참조할것.

IDirect3DRM3::CreateFace

IDirect3DRM3

IDirect3DRMFace2 인터페이스의 인스턴스를 생성한다.

구문

HRESULT CreateFace(
  LPDIRECT3DRMFACE2  *lplpd3drmFace2
  );

파라미터

lplpd3drmFace2
호출이 성공했을 경우,IDirect3DRMFace2 인터페이스에의 포인터가 세트 되는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRM3::CreateFrame

IDirect3DRM3

지정의 친프레임의 새로운 아이 프레임 (Direct3DRMFrame3 오브젝트)을 생성한다.

구문

HRESULT CreateFrame(
  LPDIRECT3DRMFRAME3 lpD3DRMFrame,
  LPDIRECT3DRMFRAME3 *lplpD3DRMFrame
  );

파라미터

lpD3DRMFrame
새로운 프레임의 부모가 되는IDirect3DRMFrame3 오브젝트의 주소.
lplpD3DRMFrame
호출이 성공했을 경우,IDirect3DRMFrame3 인터페이스에의 포인터가 세트 되는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

아이 프레임은, 그 부모로부터 운동 속성을 계승한다. 예를 들어, 부모가 일정한 속도로 움직이고 있을 때는, 아이 프레임도 같은 속도로 움직인다. 게다가 부모에게 회전이 세트 되면(자), 아이 프레임은, 부모의 원점의 주위를 회전한다. 부모를 가지지 않는 프레임은, 장면으로 불린다. 장면을 생성 하려면 , 부모로서 NULL를 지정한다. 어플리케이션은, 부모가 없는 프레임을 생성 한 후,IDirect3DRMFrame3::AddChild 메소드를 사용해, 다음에 친프레임에 관련시킬 수가 있다.

어플리케이션이 오른손 지오메트리를 세트 하기 위해서IDirect3DRM3::SetOptions 를 호출했을 경우,루트 프레임 (부모로서 NULL를 가지는 프레임)의 디폴트축은, v = (0, 0, -1) 또한 u = (0, 1, 0)가 된다. 이 때문에,IDirect3DRMFrame3::GetOrientation 와IDirect3DRMFrame3::SetOrientation 는, 오른손 모드로 올바르게 기능한다.

참조

IDirect3DRMFrame3::AddChild

IDirect3DRM3::CreateLight

IDirect3DRM3

지정의 타입과 색으로, 새로운 조명을 생성 한다.

구문

HRESULT CreateLight(
  D3DRMLIGHTTYPE d3drmltLightType,
  D3DCOLOR cColor,
  LPDIRECT3DRMLIGHT *lplpD3DRMLight
  );

파라미터

d3drmltLightType
D3DRMLIGHTTYPE 열거형으로 주어지는 조명 타입의 하나.
cColor
조명의 색.
lplpD3DRMLight
호출이 성공했을 경우,IDirect3DRMLight 인터페이스에의 포인터가 세트 되는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRM3::CreateLightRGB

IDirect3DRM3

지정의 타입과 색으로, 새로운 조명을 생성 한다.

구문

HRESULT CreateLightRGB(
  D3DRMLIGHTTYPE ltLightType,
  D3DVALUE vRed,
  D3DVALUE vGreen,
  D3DVALUE vBlue,
  LPDIRECT3DRMLIGHT *lplpD3DRMLight
  );

파라미터

ltLightType
D3DRMLIGHTTYPE 열거형으로 주어지는 조명 타입의 하나.
vRed, vGreen, vBlue
조명의 색. 색의 각 요소는, 0.0에서 1.0의 범위에 있을 필요가 있다.
lplpD3DRMLight
호출이 성공했을 경우,IDirect3DRMLight 인터페이스에의 포인터가 세트 되는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

다음의 코드 부분은,CreateLightRGB를 호출해 밝은디렉셔널조명을 생성 한다. 이것은,Direct3DRMCreate 함수를 사용해 벌써 Direct3D 보관 유지 모드 오브젝트가 생성 되고 있는 것을 전제로 하고 있다.

LPDIRECT3DRM3 lpD3DRM;
LPDIRECT3DRMLIGHT light;

if (FAILED(lpD3DRM->CreateLightRGB(D3DRMLIGHT_DIRECTIONAL,
                                   D3DVAL(0.9), D3DVAL(0.9), D3DVAL(0.9),
                                   &light))
{
    // 에러
}

IDirect3DRM3::CreateMaterial

IDirect3DRM3

지정의반사 프로퍼티를 가지는 머트리얼을 생성 한다.

구문

HRESULT CreateMaterial(
  D3DVALUE vPower,
  LPDIRECT3DRMMATERIAL2  *lplpD3DRMMaterial
  );

파라미터

vPower
반사하는 하이라이트의 날카로움. 렌더링 하는 표면에, 5의 값은 금속의 외관을 주어보다 큰 값은 보다 플라스틱적인 외관을 준다.
lplpD3DRMMaterial
호출이 성공했을 경우,IDirect3DRMMaterial2 인터페이스에의 포인터가 세트 되는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRM3::CreateMesh

IDirect3DRM3

면을 갖지 않는 새로운 메쉬 오브젝트를 생성한다. 이 메쉬는, 프레임에 추가될 때까지는 눈에 보이지 않는다.

구문

HRESULT CreateMesh(
  LPDIRECT3DRMMESH *lplpD3DRMMesh
  );

파라미터

lplpD3DRMMesh
호출이 성공했을 경우,IDirect3DRMMesh 인터페이스에의 포인터가 세트 되는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRM3::CreateMeshBuilder

IDirect3DRM3

새로운 메쉬 빌더 오브젝트를 생성한다.

구문

HRESULT CreateMeshBuilder(
  LPDIRECT3DRMMESHBUILDER3  *lplpD3DRMMeshBuilder3
  );

파라미터

lplpD3DRMMeshBuilder3
호출이 성공했을 경우,IDirect3DRMMeshBuilder3 인터페이스에의 포인터가 세트 되는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

디폴트에서는, 퍼스펙티브 보정이온이다.

IDirect3DRM3::CreateObject

IDirect3DRM3

오브젝트를 초기화하는 일 없이 새로운 오브젝트를 생성한다.

구문

HRESULT CreateObject(
  REFCLSID rclsid,
  LPUNKNOWN pUnkOuter,
  REFIID riid,
  LPVOID FAR *ppv
  );

파라미터

rclsid
새로운 오브젝트의 클래스 식별자.
pUnkOuter
COM 집합화를 가능하게 하는 외부IUnknown인터페이스에의 포인터.
riid
생성 하는 오브젝트의 인터페이스 식별자.
ppv
메소드가 돌아왔을 때의 오브젝트에의 포인터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드를 호출한 어플리케이션이 생성한 오브젝트의 초기화를 실시하지 않으면 안 된다(다른IDirect3DRM3 인터페이스의 생성 메소드는, 자동적으로 오브젝트의 초기화를 실시한다). 어느 경우, 예를 들어, Direct3DRMViewport2 오브젝트에 관한 그 오브젝트에,Init메소드를 사용할 수가 있다. 어플리케이션은, 임의의 오브젝트를 초기화하는데Init메소드를 호출하는 것은 한 번 한정해로 할 필요가 있다.

어플리케이션은, 이 메소드를 사용해 Direct3DRM 오브젝트의 집합체를 이행 할 수가 있다.

IDirect3DRM3::CreateProgressiveMesh

IDirect3DRM3

면을 갖지 않는 새로운 프로그래시브 메쉬 오브젝트를 생성한다. 메쉬는, 프레임에 추가될 때까지 눈에 보이지 않는다.

구문

HRESULT CreateProgressiveMesh(
  LPDIRECT3DRMPROGRESSIVEMESH *lplpD3DRMProgressiveMesh
  );

파라미터

lplpD3DRMProgressiveMesh
호출이 성공했을 경우,IDirect3DRMProgressiveMesh 인터페이스에의 포인터가 세트 되는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRM3::CreateShadow

IDirect3DRM3

지정의 비주얼과 조명을 사용해 그림자를 생성 해, 지정의 평면에 그 그림자를 투영 한다. 그림자도 일종의 비주얼이며, 비주얼을 포함한 프레임에 추가할 필요가 있다.

구문

HRESULT CreateShadow(
  LPUNKNOWN pUnk,
  LPDIRECT3DRMLIGHT lpLight,
  D3DVALUE px,
  D3DVALUE py,
  D3DVALUE pz,
  D3DVALUE nx,
  D3DVALUE ny,
  D3DVALUE nz,
  LPDIRECT3DRMSHADOW2  *lplpShadow
  );

파라미터

pUnk
그림자를 투영 하는 오브젝트의 주소.
lpLight
조명인IDirect3DRMLight 인터페이스의 주소.
px, py, pz
그림자가 투영 되는 평면.
nx, ny, nz
그림자가 투영 되는 평면에 대한 법선.
lplpShadow
호출이 성공했을 경우, 그림자 비주얼에 대한 유효한 포인터로 초기화되는 포인터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRM3::CreateTexture

IDirect3DRM3

메모리의 이미지로부터 텍스쳐를 생성 한다.

구문

HRESULT CreateTexture(
  LPD3DRMIMAGE lpImage,
  LPDIRECT3DRMTEXTURE3 *lplpD3DRMTexture3
  );

파라미터

lpImage
텍스쳐의 소스를 기술하는D3DRMIMAGE 구조체의 주소.
lplpD3DRMTexture3
호출이 성공했을 경우,IDirect3DRMTexture3 인터페이스에의 포인터가 세트 되는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이미지에 관련하는 메모리는, Direct3D 보관 유지 모드의 버퍼에 카피되는 것이 아니라, 텍스쳐가 렌더링 될 때마다 사용된다. 이것은, 이미지가 렌더링 대상 및 텍스쳐의 양쪽 모두로서 사용되는 것을 가능하게 한다.

IDirect3DRM3::CreateTextureFromSurface

IDirect3DRM3

지정한 DirectDraw 표면으로부터 텍스쳐를 생성 한다.

구문

HRESULT CreateTextureFromSurface(
  LPDIRECTDRAWSURFACE lpDDS,
  LPDIRECT3DRMTEXTURE3  *lplpD3DRMTexture3
  );

파라미터

lpDDS
텍스쳐를 저장 하는 DirectDrawSurface 오브젝트의 주소.
lplpD3DRMTexture3
호출이 성공했을 경우,IDirect3DRMTexture3 인터페이스에의 포인터가 세트 되는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

DirectDraw 표면으로부터 텍스쳐를 생성 하는 경우, 시스템 메모리중에 표면을 생성 하는 것이 최선이다. 이것으로 소프트웨어 디바이스의 최적인 퍼포먼스가 가능하게 되어, Direct3D 보관 유지 모드가 하드웨어 디바이스에 대해서 비디오 메모리의 사용을 보다 효율적으로 관리할 수 있게 된다.

IDirect3DRM3::CreateUserVisual

IDirect3DRM3

어플리케이션 정의의 비주얼 오브젝트를 생성한다. 생성 된 오브젝트는, 어플리케이션 정의 핸들러를 사용해 장면에 추가하거나 렌더링 하거나 할 수가 있다.

구문

HRESULT CreateUserVisual(
  D3DRMUSERVISUALCALLBACK fn,
  LPVOID lpArg,
  LPDIRECT3DRMUSERVISUAL  *lplpD3DRMUV
  );

파라미터

fn
어플리케이션 정의D3DRMUSERVISUALCALLBACK 콜백 함수.

lpArg
콜백 함수에게 건네진 어플리케이션 정의 데이터의 주소.
lplpD3DRMUV
호출이 성공했을 경우,IDirect3DRMUserVisual 인터페이스에의 포인터가 세트 되는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMUserVisual::Init

IDirect3DRM3::CreateViewport

IDirect3DRM3

디바이스 좌표가(dwXPos, dwYPos)로부터(dwXPos + dwWidth, dwYPos + dwHeight)까지의 디바이스상에서, 뷰포트를 생성 한다.

구문

HRESULT CreateViewport(
  LPDIRECT3DRMDEVICE3 lpDev,
  LPDIRECT3DRMFRAME3 lpCamera,
  DWORD dwXPos,
  DWORD dwYPos,
  DWORD dwWidth,
  DWORD dwHeight,
  LPDIRECT3DRMVIEWPORT2 *lplpD3DRMViewport
  );

파라미터

lpDev
생성 하는 뷰포트가 존재하는IDirect3DRMDevice3 디바이스의 주소.
lpCamera
뷰의 위치와 방향을 기술하는 프레임의 주소.
dwXPos, dwYPos, dwWidth, dwHeight
디바이스 좌표에서의 뷰포트의 위치와 사이즈. 뷰포트 사이즈는 물리 디바이스보다 크게 할 수 없다. 크고 하면, 메소드는 실패에 끝난다.
lplpD3DRMViewport
호출이 성공했을 경우,IDirect3DRMViewport2 인터페이스에의 포인터가 세트 되는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 뷰포트 사이즈가 물리 디바이스보다 크면, D3DRMERR_BADVALUE를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

뷰포트는,카메라를 포함한 장면 중(안)에서, 카메라로부터 취한 뷰 방향과 업 벡터를 사용해 오브젝트를 표시한다. 뷰포트 사이즈는, 물리 디바이스보다 크게 할 수 없다.

디바이스에 관한 자세한 것은, 「출력 디바이스」와「IDirect3DRMDevice3 」를 참조할것.

IDirect3DRM3::CreateWrap

IDirect3DRM3

면과 메쉬에 텍스쳐 좌표를 할당하는데 사용할 수 있는 랩핑 함수를 생성 한다. 벡터[ox oy oz]는, 랩의 원점을[dx dy dz]는 랩의 z축을,[ux uy uz]는 랩의 y축을 각각 준다. 2 D벡터의[ou ov]와[su sv]는, 랩핑 함수의 결과에 적용되는 텍스쳐의 원점과 스케일 팩터를 준다.

구문

HRESULT CreateWrap(
  D3DRMWRAPTYPE type,
  LPDIRECT3DRMFRAME3 lpRef,
  D3DVALUE ox,
  D3DVALUE oy,
  D3DVALUE oz,
  D3DVALUE dx,
  D3DVALUE dy,
  D3DVALUE dz,
  D3DVALUE ux,
  D3DVALUE uy,
  D3DVALUE uz,
  D3DVALUE ou,
  D3DVALUE ov,
  D3DVALUE su,
  D3DVALUE sv,
  LPDIRECT3DRMWRAP *lplpD3DRMWrap
  );

파라미터

type
D3DRMWRAPTYPE 열거형의 멤버의 하나.
lpRef
랩의 참조 프레임.
ox, oy, oz
랩의 원점.
dx, dy, dz
랩의 z축.
ux, uy, uz
랩의 y축.
ou, ov
텍스쳐의 원점.
su, sv
텍스쳐의 스케일 팩터.
lplpD3DRMWrap
호출이 성공했을 경우,IDirect3DRMWrap 인터페이스에의 포인터가 세트 되는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMWrap

IDirect3DRM3::EnumerateObjects

IDirect3DRM3

각 Direct3DRM 오브젝트의func파라미터에 의해 지정되는 콜백 함수를 사용한다.

구문

HRESULT EnumerateObjects(
  D3DRMOBJECTCALLBACK func,
  LPVOID lpArg
  );

파라미터

func
각 Direct3DRMObject 오브젝트 및 어플리케이션 정의 인수에 의해 사용되는 어플리케이션 정의의D3DRMOBJECTCALLBACK 콜백 함수.
lpArg
콜백 함수에게 건네진 어플리케이션 정의 데이터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRM3::GetDevices

IDirect3DRM3

시스템으로 생성 된 모든 Direct3DRM 디바이스를 돌려준다.

구문

HRESULT GetDevices(
  LPDIRECT3DRMDEVICEARRAY *lplpDevArray
  );

파라미터

lplpDevArray
Direct3DRM 디바이스의 결과의 배열이 세트 되는 포인터의 주소. Direct3DRMDeviceArray 오브젝트의 상세한 것에 대하여는, 「IDirect3DRMDeviceArray 」를 참조할것.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRM3::GetNamedObject

IDirect3DRM3

지정의 이름으로 Direct3DRMObject를 취득한다.

구문

HRESULT GetNamedObject(
  const char  *lpName,
  LPDIRECT3DRMOBJECT *lplpD3DRMObject
  );

파라미터

lpName
검색하는 오브젝트의 이름.
lplpD3DRMObject
호출이 성공했을 경우에, 유효한 Direct3DRMObject 포인터로 초기화되는 포인터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

시스템이lpName파라미터로 지정한 이름의 오브젝트를 발견하지 않았던 경우에, 이 메소드는, D3DRM_OK를 돌려주지만,lplpD3DRMObject파라미터는 NULL가 된다.

IDirect3DRM3::GetOptions

IDirect3DRM3

Direct3D 보관 유지 모드로 왼손 또는 오른손 지오메트리의 어느 쪽을 사용할까를 꺼낸다.

구문

HRESULT GetOptions(
  LPDWORD lpdwOptions);

파라미터

lpdwOptions
현재의 Direct3D 보관 유지 모드 옵션을 나타내는 플래그값에의 포인터. 현재 정의되고 있는 플래그는, 다음과 같다.
D3DRMOPTIONS_LEFTHANDED
왼손 지오메트리를 사용한다. 이것은 디폴트값이다.
D3DRMOPTIONS_RIGHTHANDED
오른손 지오메트리를 사용한다.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

D3DRMOPTIONS_LEFTHANDED와D3DRMOPTIONS_RIGHTHANDED는, 피킹과 광선 피킹은 물론이거니와, 다음의 오브젝트에도 영향을 준다.

  • IDirect3DRMClippedVisual
  • IDirect3DRMMesh
  • IDirect3DRMMeshBuilder3
  • IDirect3DRMProgressiveMesh
  • IDirect3DRMShadow2
  • IDirect3DRMTexture3
  • IDirect3DRMViewport2

이 메소드는, DirectX version 6.0으로 도입되었다.

참조

「Direct3D의 좌표계 」

IDirect3DRM3::SetOptions

IDirect3DRM3::GetSearchPath

IDirect3DRM3

현재의 검색 패스를 돌려준다. Windows에서는, 패스는, 세미콜론(;)으로 단락지어진 디렉토리의 리스트이다.

구문

HRESULT GetSearchPath(
  DWORD  *lpdwSize,
  LPSTR lpszPath
  );

파라미터

lpdwSize
DWORD값에의 포인터. GetSearchPath가 사용되었을 때,lpszPath의 길이를 포함할 필요가 있다. 돌아왔을 때에는, 현재의 검색 패스를 포함한lpszPath의 캐릭터 라인의 길이를 저장 한다. 이 파라미터는 NULL로 할 수 없다.
lpszPath
검색 패스를 지정하는 눌 종단의 캐릭터 라인에의 포인터. GetSearchPath가 사용되었을 때,lpszPath가 NULL의 경우, 이 메소드는,lpdwSize파라미터가 가리키는 위치에 있는 현재의 캐릭터 라인의 길이를 돌려준다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRM3::SetSearchPath

IDirect3DRM3::Load

IDirect3DRM3

오브젝트를 로드한다.

구문

HRESULT Load(
  LPVOID lpvObjSource,
  LPVOID lpvObjID,
  LPIID  *lplpGUIDs,
  DWORD dwcGUIDs,
  D3DRMLOADOPTIONS d3drmLOFlags,
  D3DRMLOADCALLBACK d3drmLoadProc,
  LPVOID lpArgLP,
  D3DRMLOADTEXTURE3CALLBACK d3drmLoadTextureProc,
  LPVOID lpArgLTP,
  LPDIRECT3DRMFRAME3 lpParentFrame
  );

파라미터

lpvObjSource
로드하는 오브젝트의 소스. 이 소스는,d3drmLOFlags파라미터로 지정된 소스 플래그에 따라, 파일, 리소스, 메모리 블록, 또는 스트림으로 할 수 있다.
lpvObjID
로드하는 오브젝트의 이름 또는 위치. 이 파라미터의 사용은,d3drmLOFlags파라미터로 지정되고 있는 식별 플래그에 의존한다. D3DRMLOAD_BYPOSITION 플래그가 지정되고 있으면, 이 파라미터는, 파일중의 오브젝트의 순서를 주는DWORD값에의 포인터가 된다. 이 파라미터는 NULL로 할 수 있다.
lplpGUIDs
로드하는 인터페이스 식별자의 배열의 주소. 예를 들어, 이 파라미터가 IID_IDirect3DRMMeshBuilder3 및 IID_IDirect3DRMAnimationSet2를 저장 하는 2개의 요소의 배열이면, 이 메소드는, 모든 애니메이션 세트 오브젝트와 메쉬 빌더 오브젝트를 로드한다. 가능한 GUID는, IID_IDirect3DRMProgressiveMesh, IID_IDirect3DRMMeshBuilder3, IID_IDirect3DRMAnimationSet2, IID_IDirect3DRMAnimation2, 및 IID_IDirect3DRMFrame3안의 하나 이상이 아니면 안된다.
dwcGUIDs
lplpGUIDs파라미터로 지정되고 있는 요소의 수.
d3drmLOFlags
로드 옵션을 기술하는D3DRMLOADOPTIONS 형의 값.
d3drmLoadProc
시스템이 지정의 오브젝트를 읽어들였을 때에 사용되는D3DRMLOAD3CALLBACK 콜백 함수.
lpArgLP
D3DRMLOADCALLBACK 콜백 함수에게 건네지는 어플리케이션 정의 데이터의 주소.
d3drmLoadTextureProc
D3DRMLOADTEXTURE3CALLBACK 콜백 함수. 이것은, 특별한 포맷을 필요로 하는 오브젝트가 이용하는 텍스쳐를 읽어낼 때 불려 간다. 이 파라미터에는 NULL를 지정할 수가 있다.
lpArgLTP
D3DRMLOADTEXTURE3CALLBACK 콜백 함수에게 건네지는 어플리케이션 정의 데이터의 주소.
lpParentFrame
친Direct3DRMFrame 오브젝트의 주소. 이 인수는, 애니메이션 세트의 로드에만 영향을 준다. X파일로부터 로드 된 애니메이션이, X파일중의 부모가 없는 프레임을 참조 하면나무는, 그 부모에게는,lpParentFram가 세트 된다. 다만, X파일중의 임의의 프레임을 로드하도록(듯이),Load를 사용했을 경우에는,lpParentFrame는, 부모가 없는 X파일중의 프레임에 대한 친프레임으로서 사용될 것은 없다. 즉,lpParentFrame는, 애니메이션 세트를 로드했을 때에 한계 사용된다. lpParentFrame의 값은 NULL로 할 수 있다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

디폴트에서는, 퍼스펙티브 보정이온이다.

이 메소드에 의해, Microsoft® DirectX® 파일로부터의 오브젝트의 로드가 지극히 유연하게 실시할 수 있게 된다. 다음에 그 사용법의 예를 나타낸다.

샘플 코드

#include <windows.h>
#include <stdio.h>
#include <initguid.h>
#include <d3drm.h>

LPDIRECT3DRM d3dApi;

int totalMesh = 0, totalAnim = 0, totalFrames = 0;

HRESULT loadTexture(LPSTR name, LPVOID lpArg, LPDIRECT3DRMTEXTURE *tex)
{
    return d3dApi->lpVtbl->LoadTexture(d3dApi, name, tex);
}

void loadCallback(LPDIRECT3DRMOBJECT lpObject, REFIID objGuid, LPVOID lpArg)
{
    if (IsEqualIID(objGuid, &IID_IDirect3DRMFrame3)) {
        totalFrames ++;
        return;
    }

    if (IsEqualIID(objGuid, &IID_IDirect3DRMAnimationSet2)) {
        totalAnim ++;
        return;
    }

    if (IsEqualIID(objGuid, &IID_IDirect3DRMMeshBuilder)) {
        totalMesh ++;
        return;
    }

    return;
}

BOOL loadObjects(LPSTR filename)
{
    LPGUID guids[] = { (LPGUID) &IID_IDirect3DRMMeshBuilder,
        (LPGUID) &IID_IDirect3DRMAnimationSet2,
        (LPGUID) &IID_IDirect3DRMFrame3 };

    /* 로더에 어느 오브젝트를 대상으로 할까를 고한다 */

    if (FAILED(d3dApi->lpVtbl->Load(d3dApi, filename, NULL,
            guids, 3, D3DRMLOAD_FROMFILE,
            loadCallback, NULL, loadTexture, NULL, NULL)))
        return FALSE;

    printf("Total Frames loaded = %d\n", totalFrames);
    printf("Total Animation Sets loaded = %d\n", totalAnim);
    printf("Total Meshbuilders loaded = %d\n", totalMesh);

    return TRUE;
}

int main(int argc, char **argv)
{

    if (FAILED(Direct3DRMCreate(&d3dApi)))
        return FALSE;

    if (argc ! = 2) {
        fprintf(stderr, "usage: %s filename\n", argv[0]);
        return FALSE;
    }

    if (! loadObjects(argv[1])) return FALSE;

  return(0);
}

IDirect3DRM3::LoadTexture

IDirect3DRM3

지정 파일로부터 Direct3DRMTexture2 텍스쳐를 로드한다. 이 텍스쳐는, 8, 24, 또는 32 비트/픽셀을 취할 수가 있다. 그 포맷은, Windows 비트 맵 (. bmp)인가 Portable Pixmap (. ppm) P6포맷의 어딘가에 할 필요가 있다.

구문

HRESULT LoadTexture(
  const char  *lpFileName,
  LPDIRECT3DRMTEXTURE3 *lplpD3DRMTexture
  );

파라미터

lpFileName
필요한. bmp 또는. ppm 파일의 이름의 주소.
lplpD3DRMTexture
이 호출이 성공했을 경우에, 유효한IDirect3DRMTexture3 포인터로 초기화되는 포인터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

LoadTexture는, 텍스쳐가 BMP 포맷일까 PPM 포맷인지를 체크한다. LoadTexture는, 양포맷을 로드할 수가 있다. 그 외의 포맷을 로드하려면 ,D3DRMIMAGE 구조체에의 이미지 로드용의 코드를 콜백 함수에 추가해, 그리고IDirect3DRM3::CreateTexture 를 사용한다.

독자적인 텍스쳐 콜백 함수를 쓸 때, 텍스쳐 콜백 함수의LoadTexture호출은 텍스쳐에의 참조를 받지 않는다. 예를 들어,

HRESULT loadTextures(char *name, void *arg, LPDIRECT3DRMTEXTURE2 *tex)
{
    return lpD3DRM2->LoadTexture(name, tex);
}

이 예로,tex의 참조를 받을 수 없다. 텍스쳐 콜백 함수로 로드한 각 텍스쳐에의 참조를 보관 유지하려면 , 텍스쳐에AddRef한다. 예를 들어,

LPDIRECT3DRMTEXTURE2 *texarray;

HRESULT loadTextures(char *name, void *arg, LPDIRECT3DRMTEXTURE2 *tex)
{
    if (FAILED(lpD3DRM2->LoadTexture(name, tex)) {
        return NULL;
    }

    texArray[current++] = tex;
    tex->AddRef();

    return tex;
}

IDirect3DRM3::LoadTextureFromResource

IDirect3DRM3

지정의 리소스로부터 Direct3DRMTexture2 텍스쳐를 로드한다.

구문

HRESULT LoadTextureFromResource(
  HMODULE hModule,
  LPCTSTR strName,
  LPCTSTR strType,
  LPDIRECT3DRMTEXTURE3  *lplpD3DRMTexture
  );

파라미터

hModule
모듈의 핸들. 그 모듈의 실행 가능 파일이 리소스를 포함한다.
strName
테키스체로서 사용되는 리소스명을 지정하는 눌 종단 캐릭터 라인.
strType
리소스의 타입명을 지정하는 눌 종단 캐릭터 라인을 가리킨다. 이 파라미터는, 이하의 리소스의 타입의 언젠가, 또는 유저 정의 타입으로 할 수 있다.
값 | 의미
RT_BITMAP | 비트 맵 리소스
RT_RCDATA | 어플리케이션 정의 리소스(생 데이터)
lplpD3DRMTexture
이 호출이 성공했을 경우에, 유효한IDirect3DRMTexture3 오브젝트로 초기화되는 포인터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRM3::RegisterClient

IDirect3DRM3

데이터를 관련짓는 클라이언트 (어플리케이션)를 등록한다.

구문

HRESULT RegisterClient(
  REFGUID rguid,
  LPDWORD lpdwID);

파라미터

rguid
어플리케이션을 나타내는 GUID에의 참조.
lpdwID
데이터를 보관 유지 모드 오브젝트에 관련짓기 위해서(때문에), 어플리케이션이IDirect3DRMObject2::SetClientData 와IDirect3DRMObject2::GetClientData 와 함께 사용하는 일의의 ID를 받는 주소.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DD_OK

주의

어플리케이션은 GUID를 건네주어, DWORD 식별자를 받는다. 다음에, 이 식별자를IDirect3DRMObject2::SetClientData 와IDirect3DRMObject2::GetClientData 로 사용해, 데이터를 보관 유지 모드 오브젝트에 관련짓는다. 어플리케이션이IDirect3DRMObject2::SetClientData 를 사용하는 경우,IDirect3DRMObject2::SetClientData 에 의해 어플리케이션이 저장 하는 임의의 데이터는, 그 타입에 응해 릴리스 된다. 같은 GUID를 가지는 이 메소드를 여러 차례 호출해도, 같은 ID가 돌려주어진다. 이 메소드는, DirectX version 6.0으로 도입되었다.

IDirect3DRM3::SetDefaultTextureColors

IDirect3DRM3

Direct3DRMTexture2 오브젝트에 대해서 사용하는 디폴트의 색을 설정한다.

구문

HRESULT SetDefaultTextureColors(
  DWORD dwColors
  );

파라미터

dwColors
색의 수.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는,IDirect3DRM3::CreateTexture 메소드의 전에 사용되었을 때에 한계 텍스쳐의 색에 영향을 준다. 벌써 생성 되고 있는 텍스쳐에는, 아무 효과도 없다.

IDirect3DRM3::SetDefaultTextureShades

IDirect3DRM3

Direct3DRMTexture2 오브젝트에 대해서 사용하는 디폴트의 쉐이드를 설정한다.

구문

HRESULT SetDefaultTextureShades(
  DWORD dwShades
  );

파라미터

dwShades
쉐이드수.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는,IDirect3DRM3::CreateTexture 메소드의 전에 사용되었을 때에 한계 텍스쳐의 쉐이드에 영향을 준다. 벌써 생성 되고 있는 텍스쳐에는, 아무 효과도 없다.

IDirect3DRM3::SetOptions

IDirect3DRM3

Direct3D 보관 유지 모드로 왼손 또는 오른손 지오메트리의 어느 쪽을 사용할까를 세트 한다.

구문

HRESULT SetOptions(
  LPDWORD dwOptions);

파라미터

dwOptions
현재의 Direct3D 보관 유지 모드 옵션을 나타내는 플래그값. 현재 정의되고 있는 플래그는, 다음과 같다.
D3DRMOPTIONS_LEFTHANDED
왼손 지오메트리를 사용한다. 이것은 디폴트값이다.
D3DRMOPTIONS_RIGHTHANDED
오른손 지오메트리를 사용한다.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

D3DRMOPTIONS_LEFTHANDED와D3DRMOPTIONS_RIGHTHANDED는, 피킹과 광선 피킹은 물론이거니와, 다음의 오브젝트에도 영향을 준다.

  • IDirect3DRMClippedVisual
  • IDirect3DRMMesh
  • IDirect3DRMMeshBuilder3
  • IDirect3DRMProgressiveMesh
  • IDirect3DRMShadow2
  • IDirect3DRMTexture3
  • IDirect3DRMViewport2

이 메소드는, DirectX version 6.0으로 도입되었다.

참조

「Direct3D의 좌표계」

IDirect3DRM3::GetOptions

IDirect3DRM3::SetSearchPath

IDirect3DRM3

디렉토리의 리스트로부터 현재의 파일 검색 패스를 설정한다. Windows에서는, 패스는, 세미콜론(;)으로 단락지어진 리스트로 할 필요가 있다.

구문

HRESULT SetSearchPath(
  LPCSTR lpPath
  );

파라미터

lpPath
현재의 검색 패스로 해서 설정하는 패스를 지정하는 눌 종단의 캐릭터 라인의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

디폴트의 검색 패스는, D3DPATH 환경 변수의 값이 채용된다. 환경 변수가 설정되어 있지 않으면, 검색 패스는 비운다. 파일의 오픈시, 시스템은, 우선, 현재의 작업 디렉토리안으로 파일을 찾아, 다음에, 검색 패스중의 각 디렉토리를 체크한다.

D3DPATH 는, 디폴트의 검색 패스를 설정하는 환경 변수이다.

참조

IDirect3DRM3::GetSearchPath

IDirect3DRM3::Tick

IDirect3DRM3

Direct3DRM 시스템의 하트 비트를 실시한다. 이 메소드가 사용되면(자), 모든 가동 프레임의 위치는, 현재의 운동 속성에 따라 갱신되어 장면이 현재의 디바이스에 렌더링 된다. 또, 관련한 콜백 함수가, 적절한 타이밍에 불려 간다. 이 메소드는, 렌더링 사이클이 완료했을 때에 제어를 돌려준다.

구문

HRESULT Tick(
  D3DVALUE d3dvalTick
  );

파라미터

d3dvalTick
IDirect3DRMFrame3::SetRotation 및IDirect3DRMFrame3::SetVelocity 메소드에 대한 속도와 회전의 스텝.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

장면의 렌더링에 유연성을 갖게하기 (위해)때문에, 보관 유지 모드의 다른 메소드를 사용해, 이 메소드를 이행 할 수도 있다.

IDirect3DRM3::UnregisterClient

IDirect3DRM3

IDirect3DRMObject2::SetClientData 에 의해 세트 한 모든 데이터와 오브젝트의 관련을 없애, 데이터를 그 타입에 응해 개방한다.

구문

HRESULT UnregisterClient(
  REFGUID rguid);

파라미터

rguid
어플리케이션을 나타내는 GUID에의 참조.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_CLIENTNOTREGISTERED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.


IDirect3DRMAnimation2

어플리케이션은IDirect3DRMAnimation2인터페이스의 메소드를 이용해, 위치, 향해, 비주얼 오브젝트의 스케일링, 조명, 뷰포트의 애니메이션을 실시할 수가 있다.

보관 유지 모드의 애니메이션은,키세트에 의해 정의된다. 키는 스케일링 조작, 방향, 또는 위치에 관련지을 수 있었던 시간값이다. Direct3DRMAnimation 오브젝트는, 시간값에 응한 변환의 수정 방법을 정의한다. 애니메이션을 Direct3DRMFrame 오브젝트상에서 동작하도록(듯이) 세트 해, Direct3DRMVisual, Direct3DRMLight 및 Direct3DRMViewport 오브젝트의 위치, 방향, 스케일링의 애니메이션을 실시하기 위해서(때문에) 사용할 수가 있다.

IDirect3DRMAnimation2::AddPositionKey ,AddRotateKey 및AddScaleKey 의 각 메소드는, 단위가 임의의 시간값을 지정한다. 어플리케이션이 시간값 99의 위치 키를 추가했을 경우, 예를 들어, 시간값 49의 새로운 위치 키는, 애니메이션의(0을 기준으로 한) 시작점과 최초의 위치 키와의 사이의 정확히 중간으로 발생한다.

애니메이션의 조작은,IDirect3DRMAnimation2::SetTime 메소드를 호출하는 것으로 행해진다. 이것은, 비주얼 오브젝트의 변환을 애니메이션중의 가까이의 키의 보간 위치, 방향, 스케일에 세트 한다. 애니메이션 키를 추가하는 메소드와 같게,IDirect3DRMAnimation2::SetTime의 시간값은, 어플리케이션이 벌써 추가제의 키 위치에 근거하는 임의의 값이다.

Microsoft DirectX version 6.0은,IDirect3DRMAnimation2인터페이스를 도입하고 있다. IDirect3DRMAnimation2는, 애니메이션의 키에의 액세스를 가능하게 하는AddKey ,DeleteKeyByID ,GetKeys 및ModifyKey 메소드를 추가하는 것으로, 그것이 치환하는 구의IDirect3DRMAnimation인터페이스를 확장한다. 이것은, 대응하는 애니메이션의 프레임을 돌려주는GetFrame 메소드도 추가한다. Direct3D 보관 유지 모드 인터페이스의 이력에 대해서는, 「인터페이스의 변경점」을 참조할것.

IDirect3DRMAnimation2인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

키 | AddKey
 | AddPositionKey
 | AddRotateKey
 | AddScaleKey
 | DeleteKey
 | DeleteKeyByID
 | GetKeys
 | ModifyKey
그 외 | GetFrame
 | SetFrame
 | SetTime
옵션 | GetOptions
 | SetOptions

모든 COM 인터페이스와 같이,IDirect3DRMAnimation2인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는 다음의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

한층 더IDirect3DRMAnimation2인터페이스는,IDirect3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMAnimation 오브젝트는,IDirect3DRM3::CreateAnimation 메소드의 호출에 의해 취득할 수 있다.

IDirect3DRMAnimation2::AddKey

IDirect3DRMAnimation2

새로운 키를 추가한다.

구문

HRESULT AddKey
(LPD3DRMANIMATIONKEY lpKey);

파라미터

lpKey
새로운 키를 정의하는 D3DRMANIMATIONKEY 구조체. 구조체의dwID멤버는 무시되어 돌아가는 시점에서 새로운 키의 ID가 세트 된다.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMAnimation2::AddPositionKey

IDirect3DRMAnimation2

애니메이션에 위치 키를 추가한다.

구문

HRESULT AddPositionKey(
  D3DVALUE rvTime,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ
  );

파라미터

rvTime
애니메이션 중(안)에서 위치 키를 설정 하면나무의 시간. 0을 원점으로 하는 임의의 단위의 시간을 지정할 수가 있다. 마지막 키의rvTime의 값이 99 때,rvTime가 49인 키가 애니메이션의 정확히 중간이다.
rvX, rvY, rvZ
위치.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드에 의해 이동 변환을 하게 된다. 변환을 포함한 행렬 계산에 대해서는, 「3 D변환」을 참조할것.

참조

IDirect3DRMAnimation2::DeleteKey

IDirect3DRMAnimation2::AddRotateKey

IDirect3DRMAnimation2

애니메이션에 회전 키를 추가한다.

구문

HRESULT AddRotateKey(
  D3DVALUE rvTime,
  D3DRMQUATERNION *rqQuat
  );

파라미터

rvTime
애니메이션 중(안)에서 회전 키를 설정 하면나무의 시간. 0을 기준으로 하는 임의의 단위의 시간을 지정할 수가 있다. 마지막 키의rvTime의 값이 99 때,rvTime가 49인 키가 애니메이션의 정확히 중간이다.
rqQuat
회전을 나타내는 4 차원 행렬.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드에 의해, 회전 변환이 적용된다. 변환을 포함한 행렬 계산에 대해서는, 「3 D변환」을 참조할것.

참조

IDirect3DRMAnimation2::DeleteKey

IDirect3DRMAnimation2::AddScaleKey

IDirect3DRMAnimation2

애니메이션에 스케일 키를 추가한다.

구문

HRESULT AddScaleKey(
  D3DVALUE rvTime,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ
  );

파라미터

rvTime
애니메이션 중(안)에서 스케일 키를 기억 하면나무의 시간. 0을 원점으로 하는 임의의 단위의 시간을 지정할 수 있다. 마지막 키의rvTime의 값이 99 때,rvTime가 49인 키가 애니메이션의 정확히 중간이다.
rvX, rvY, rvZ
스케일 계수.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드에 의해, 스케일 변환이 적용된다. 변환을 포함한 행렬 계산에 대해서는, 「3 D변환」을 참조할것.

참조

IDirect3DRMAnimation2::DeleteKey

IDirect3DRMAnimation2::DeleteKey

IDirect3DRMAnimation2

키를 애니메이션으로부터 삭제한다. 예를 들어, 애니메이션에 시간t의 스케일 키와 시간t의 회전 키가 있는 경우, 양쪽 모두의 키가 삭제된다.

구문

HRESULT DeleteKey(
  D3DVALUE rvTime
  );

파라미터

rvTime
애니메이션으로부터 삭제되는 키를 식별하는 시간.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMAnimation2::DeleteKeyByID

IDirect3DRMAnimation2

고유의 ID에 대응하는 키를 삭제한다.

구문

HRESULT DeleteKeyByID
(DWORD dwID);

파라미터

dwID
삭제하는 키의 ID.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_NOSUCHKEY
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMAnimation2::GetFrame

IDirect3DRMAnimation2

애니메이션에 대응하는 프레임을 꺼낸다.

구문

HRESULT GetFrame
(LPDIRECT3DRMFRAME3 *lplpFrame);

파라미터

lplpFrame
애니메이션이 참조하는 현재의Direct3DRMFrame오브젝트의 인터페이스를 받는 포인터. 이 값은 NULL가 가능하다.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMAnimation2::GetKeys

IDirect3DRMAnimation2

고유의 시간에 대응하는 키를 꺼낸다.

구문

HRESULT GetKeys
(D3DVALUE dvTimeMin,
D3DVALUE dvTimeMax,
LPDWORD lpdwNumKeys,
LPD3DRMANIMATIONKEY lpKey);

파라미터

dvTimeMin
돌려주어지는 키의 최소 시간값.
dvTimeMax
돌려주어지는 키의 최대 시간값.
lpdwNumKeys
안에 돌려주어지는 키의 수를 포함한 변수에의 포인터. lpKey가 NULL의 경우,lpdwNumKeys는 지정의 시간에 키의 수가 세트 된다.
lpKey
키값이 세트 되는D3DRMANIMATIONKEY구조체에의 포인터. lpKey가 NULL의 경우,lpdwNumKeys는 지정의 시간에 키의 수가 세트 된다. lpKey가 NULL가 아닌 경우,lpdwNumKeysi로 나타나는 키의 최대수까지 지정의 시간에 대응하는 키가 세트 된다.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_NOSUCHKEY
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMAnimation2::GetOptions

IDirect3DRMAnimation2

애니메이션 옵션을 취득한다.

구문

D3DRMANIMATIONOPTIONS GetOptions( );

반환값

애니메이션 옵션을 나타내는D3DRMANIMATIONOPTIONS 형의 값을 돌려준다.

참조

IDirect3DRMAnimation2::SetOptions

IDirect3DRMAnimation2::ModifyKey

IDirect3DRMAnimation2

키값을 수정한다.

구문

HRESULT Modify
(LPD3DRMANIMATIONKEY lpKey);

파라미터

lpKey
기존의 키의 값을 정의하는 D3DRMANIMATIONKEY 구조체. 구조체의dwID멤버는, 기존의 키가 아니면 안된다.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_INCOMPATIBLEKEY
D3DRMERR_NOSUCHKEY
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

키의 타입을 수정할 수 없다. 키의 타입을 변경하려면 , 오리지날 키를 삭제해, 새로운 키를 추가해야 한다. 키의 시간, 위치, 회전, 스케일값을 수정할 수 있다.

IDirect3DRMAnimation2::SetFrame

IDirect3DRMAnimation2

애니메이션에 프레임을 설정한다.

구문

HRESULT SetFrame(
  LPDIRECT3DRMFRAME3 lpD3DRMFrame
  );

파라미터

lpD3DRMFrame
애니메이션으로 설정하는 프레임을 지정하는 변수의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMAnimation2::SetOptions

IDirect3DRMAnimation2

애니메이션 옵션을 설정한다.

구문

HRESULT SetOptions(
  D3DRMANIMATIONOPTIONS d3drmanimFlags
  );

파라미터

d3drmanimFlags
애니메이션 옵션을 지정하는D3DRMANIMATIONOPTIONS 형의 값의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMAnimation2::GetOptions

IDirect3DRMAnimation2::SetTime

IDirect3DRMAnimation2

애니메이션에 현재의 시간을 설정한다.

구문

HRESULT SetTime(
  D3DVALUE rvTime
  );

파라미터

rvTime
애니메이션으로 설정하는 새로운 현재의 시간. 0을 원점으로 하는 임의의 단위의 시간을 지정할 수가 있다. 마지막 키의rvTime의 값이 99 때,rvTime가 49인 키가 애니메이션의 정확히 중간이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.


IDirect3DRMAnimationArray

IDirect3DRMAnimationArray인터페이스는, 배열중의 애니메이션의 수를 꺼내, 인터페이스에 애니메이션의 실행을 요구할 수 있도록(듯이) 한다.

IDirect3DRMAnimationArray인터페이스는,GetElement 및GetSize 메소드를 지원 한다.

모든 COM 인터페이스와 같게,IDirect3DRMAnimationArray인터페이스는IUnknown 인터페이스 메소드를 계승한다. 이 인터페이스는, 다음의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

IDirect3DRMAnimationArray::GetElement

IDirect3DRMAnimationArray

요구된 애니메이션에 대한 인터페이스를 취득한다.

구문

DWORD GetElement(
  DWORD dwIndex,
  LPDIRECT3DRMANIMATION2 &lplpDirect3DRMAnimation);

파라미터

dwIndex
취득되는 애니메이션의 배열내의 인덱스.
lplpDirect3DRMAnimation
Direct3DRMAnimation 오브젝트에의 포인터.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMAnimationArray::GetSize

IDirect3DRMAnimationArray

배열중의 애니메이션의 수를 취득한다.

구문

DWORD GetSize();

반환값

애니메이션의 수를 돌려준다.

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.


IDirect3DRMAnimationSet2

어플리케이션은, Direct3DRMAnimation 오브젝트를 그룹화 하기 위해서IDirect3DRMAnimationSet2인터페이스의 메소드를 사용할 수가 있다. 이 인터페이스에 의해 복잡한 애니메이션의 흐름을 재생하는 것이 간단하게 된다.

Direct3DRMAnimationSet 오브젝트에 의해, Direct3DRMAnimation 오브젝트를 그룹에 정리할 수가 있다. 이것으로, 애니메이션 세트중의 모든 애니메이션이 같은 시간 파라미터를 공유해, 복잡하게 분할된 애니메이션의 흐름을 간단하게 재생할 수 있게 된다. 어플리케이션은,IDirect3DRMAnimationSet2::AddAnimation 메소드를 사용해 애니메이션을 애니메이션 세트에 추가해,IDirect3DRMAnimationSet2::DeleteAnimation 메소드를 사용해 그것을 삭제할 수 있다. 애니메이션 세트는,IDirect3DRMAnimationSet2::SetTime 메소드를 호출하는 것으로 조작한다.

Microsoft DirectX version 6.0은,IDirect3DRMAnimationSet2인터페이스를 도입하고 있다. IDirect3DRMAnimationSet2는, 구성 애니메이션의 취득을 가능하게 하는GetAnimations 메소드를 추가하는 것으로, 그것이 치환하는 구의IDirect3DRMAnimationSet인터페이스를 확장한다. Direct3D 보관 유지 모드 인터페이스의 이력에 대해서는, 「인터페이스의 변경점」을 참조할것.

IDirect3DRMAnimationSet2인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

추가, 삭제, 취득, 로드 | AddAnimation
 | DeleteAnimation
 | GetAnimations
 | Load
시간 | SetTime

모든 COM 인터페이스와 같이,IDirect3DRMAnimationSet2인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

게다가IDirect3DRMAnimationSet2인터페이스는,IDirect3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMAnimationSet 오브젝트는,IDirect3DRM3::CreateAnimationSet 의 호출에 의해 취득할 수 있다.

IDirect3DRMAnimationSet2::AddAnimation

IDirect3DRMAnimationSet2

애니메이션을 애니메이션 세트에 추가한다.

구문

HRESULT AddAnimation(
  LPDIRECT3DRMANIMATION2 lpD3DRMAnimation
  );

파라미터

lpD3DRMAnimation
애니메이션 세트에 추가하는 Direct3DRMAnimation 오브젝트.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMAnimationSet2::DeleteAnimation

IDirect3DRMAnimationSet2

애니메이션을 애니메이션 세트로부터 삭제한다.

구문

HRESULT DeleteAnimation(
  LPDIRECT3DRMANIMATION2 lpD3DRMAnimation
  );

파라미터

lpD3DRMAnimation
애니메이션 세트로부터 삭제되는 Direct3DRMAnimation 오브젝트.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMAnimationSet2::GetAnimations

IDirect3DRMAnimationSet2

애니메이션 세트중의 애니메이션을 포함한 배열을 꺼낸다.

구문

HRESULT GetAnimations
(LPDIRECT3DRMANIMATIONARRAY *lplpArray);

파라미터

lplpArray
대응하는Direct3DRMAnimationArray오브젝트에의 포인터를 받는 배열.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMAnimationSet2::Load

IDirect3DRMAnimationSet2

애니메이션 세트를 로드한다.

구문

HRESULT Load(
  LPVOID lpvObjSource,
  LPVOID lpvObjID,
  D3DRMLOADOPTIONS d3drmLOFlags,
  D3DRMLOADTEXTURE3CALLBACK d3drmLoadTextureProc,
  LPVOID lpArgLTP,
  LPDIRECT3DRMFRAME3 lpParentFrame
  );

파라미터

lpvObjSource
오브젝트가 로드 되는 소스에의 포인터. d3drmLOFlags파라미터가 가리키는 소스 플래그에 의해, 파일, 리소스, 메모리 블록, 또는 스트림을 지정한다.
lpvObjID
로드하는 오브젝트의 이름 또는 위치에의 포인터. 이 파라미터는,d3drmLOFlags파라미터가 가리키는 식별자 플래그에 의해 해석된다. D3DRMLOAD_BYPOSITION 플래그를 지정했을 경우, 이 파라미터는, 파일안의 오브젝트의 순서를 나타내는DWORD값에의 포인터이다. 이 파라미터에는 NULL를 지정할 수도 있다.
d3drmLOFlags
로드 옵션을 나타내는D3DRMLOADOPTIONS 형의 값.
d3drmLoadTextureProc
D3DRMLOADTEXTURE3CALLBACK 콜백 함수. 이것은, 특별한 포맷을 필요로 하는 오브젝트가 이용하는 텍스쳐를 읽어낼 때 불려 간다. 이 파라미터에는 NULL를 지정할 수가 있다.
lpArgLTP
D3DRMLOADTEXTURE3CALLBACK콜백 함수에게 건네지는 어플리케이션 정의의 데이터.
lpParentFrame
친Direct3DRMFrame 오브젝트의 주소. 이 인수는, 애니메이션 세트의 로드에만 영향을 준다. x파일로부터 로드 된 애니메이션이, x파일중의 부모가 없는 프레임을 참조 하면나무는, 그 부모에게는,lpParentFram가 세트 된다. 다만, x파일중의 임의의 프레임을 로드하도록(듯이),Load를 사용했을 경우에는,lpParentFrame는, 부모가 없는 x파일중의 프레임에 대한 친프레임으로서 사용될 것은 없다. 즉,lpParentFrame는, 애니메이션 세트를 로드했을 때에 한계 사용된다. lpParentFrame의 값은 NULL로 할 수 있다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

디폴트에서는, 이 메소드는lpvObjSource파라미터로 지정되는 파일의 최초의 애니메이션 세트를 로드한다. 디폴트에서는, 퍼스펙티브 보정이온이다.

IDirect3DRMAnimationSet2::SetTime

IDirect3DRMAnimationSet2

애니메이션의 현재의 시간을 설정한다.

구문

HRESULT SetTime(
  D3DVALUE rvTime
  );

파라미터

rvTime
새로운 시간.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.


IDirect3DRMArray

IDirect3DRMArray인터페이스는 오브젝트의 그룹을 관리한다. 보통, 어플리케이션은 이 인터페이스를 직접 사용하지 않고, (IDirect3DRMFaceArray 등이) 특별한 배열 인터페이스를 이용한다.

IDirect3DRMArray인터페이스는,GetSize 메소드를 지원 한다.

모든 COM 인터페이스와 같이,IDirect3DRMArray인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

IDirect3DRMArray::GetSize

IDirect3DRMArray

Direct3DRMArray 오브젝트의 사이즈를, 오브젝트 단위로 취득한다.

구문

DWORD GetSize( );

반환값

사이즈를 돌려준다.


IDirect3DRMClippedVisual

Microsoft® DirectX® version 6.0은,IDirect3DRMClippedVisual인터페이스를 도입하고 있다. 이 인터페이스에 의해, 어플리케이션은, 렌더링의 전에 월드 공간안으로 지정된 임의의 프레인에 대해서 비주얼 오브젝트를 클립 할 수가 있다. 다른 비주얼로부터 그림자를 생성 하는 것과 거의 똑같이, 다른 비주얼로부터 클립 비주얼을 생성 한다. 예를 들어, 구(공)체로부터 클립 비주얼을 생성 해, 구(공)체의 한가운데로부터 직선적으로 클리핑 프레인을 건네주어, 구(공)체의 반만큼을 렌더링 시킬 수가 있다. IDirect3DRM3::CreateClippedVisual 메소드를 호출하는 것으로, 클립 비주얼 오브젝트를 생성 한다. 다음에,IDirect3DRMFrame3::AddVisual 메소드를 사용해, 클립 비주얼을 장면에 추가한다.

IDirect3DRMClippedVisual는, 그 외의 비주얼 인터페이스와 같게IDirect3DRMVisual 를 계승한다. 참조 프레임이 이동 하면 와, 클리핑 프레인은 이동하지 않는다 (상세한 것에 대하여는, 「AddPlane 메소드」를 참조할것).

Microsoft Direct3D® 보관 유지 모드 인터페이스의 이력에 대해서는, 「인터페이스의 변경점」을 참조할것.

IDirect3DRMClippedVisual인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.
초기화 | Init
프레인 | AddPlane
 | DeletePlane
 | GetPlane
 | GetPlaneIDs
 | SetPlane

모든 COM 인터페이스와 같이,IDirect3DRMClippedVisual인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

한층 더IDirect3DRMClippedVisual인터페이스는,IDirect3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

IDirect3DRM3 인터페이스를 사용해,Direct3DRMClippedVisual오브젝트를 생성 할 수가 있다.

IDirect3DRMClippedVisual::AddPlane

IDirect3DRMClippedVisual

클리핑 프레인을 추가한다.

구문

HRESULT AddPlane(
  LPDIRECT3DRMFRAME3 lpRef,
  LPD3DVECTOR lpdvPoint,
  LPD3DVECTOR lpdvNormal,
  DWORD dwFlags,
  LPDWORD lpdwReturnID);

파라미터

lpRef
포인트와 법선 파라미터의 참조 프레임.
lpdvPoint
참조 프레임을 기점으로 하는 프레인 위에의 포인트.
lpdvNormal
참조 프레임을 기점으로 하는 프레인에 수직인 벡터.
dwFlags
미사용 플래그. 0이 아니면 안된다.
lpdwReturnID
호출이 성공했을 경우에, 프레인의 일의인 ID번호를 받는 포인터.

반환값

DD_OK 또는DDERR_INVALIDPARAMS 를 돌려준다.

주의

클리핑 프레인은,월드 좌표로서 내부적으로 저장 된다. 참조 프레임이 이동 하면 와, 클리핑 프레인은 이동하지 않는다. 필요에 따라서 클리핑 프레인의 위치와 방향을 갱신하려면 ,SetPlane 메소드를 사용한다.

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMClippedVisual::DeletePlane

IDirect3DRMClippedVisual

클리핑 프레인을 삭제한다.

구문

HRESULT DeletePlane(
  DWORD dwID,
  DWORD dwFlags);

파라미터

dwID
삭제하는 프레인의 ID번호.
dwFlags
미사용 플래그.

반환값

성공하면DD_OK 를 돌려준다.

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMClippedVisual::GetPlane

IDirect3DRMClippedVisual

클리핑 프레인에 관한 정보를 꺼낸다.

구문

HRESULT GetPlane(
  DWORD dwID,
  LPDIRECT3DRMFRAME3 lpRef,
  LPD3DVECTOR lpdvPoint,
  LPD3DVECTOR lpdvNormal,
  DWORD dwFlags);

파라미터

lpRef
해당하는 조작의 참조 프레임.
dwID
프레인의 ID.
lpdvPoint
호출이 성공했을 경우에, 참조 프레임을 기점으로 하는 프레인 위에의 포인트를 받는 포인터.
lpdvNormal
호출이 성공했을 경우에, 참조 프레임을 기점으로 하는 프레인에 수직인 벡터를 받는 포인터.
dwFlags
미사용 플래그. 0이 아니면 안된다.

반환값

DD_OK 또는DDERR_INVALIDPARAMS 를 돌려준다.

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMClippedVisual::GetPlaneIDs

IDirect3DRMClippedVisual

ID의 배열을 꺼낸다.

구문

HRESULT GetPlanes(
  LPDWORD lpdwCount,
  LPDWORD lpdwID,
  DWORD dwFlags);

파라미터

lpdwCount
호출이 성공했을 경우에, 프레인의 수를 받는 포인터.
lpdwID
모든 프레인 ID번호의 배열을 넣는데 충분한 크기의 버퍼의 주소. 호출이 성공했을 경우, 프레인 ID가 들어가 있다. NULL라면, 프레인의 수만 돌려주어진다.
dwFlags
미사용 플래그. 0이 아니면 안된다.

반환값

DD_OK 또는DDERR_INVALIDPARAMS 를 돌려준다.

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMClippedVisual::Init

IDirect3DRMClippedVisual

클립 비주얼을 초기화한다.

구문

HRESULT Init(
  LPDIRECT3DRMVISUAL lpD3DRMVisual);

파라미터

lpD3DRMVisual
클립 해, 렌더링 하는 비주얼.

반환값

성공하면DD_OK 를 돌려준다.

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMClippedVisual::SetPlane

IDirect3DRMClippedVisual

벌써 추가된 클리핑 프레인의 파라미터를 변경한다.

구문

HRESULT SetPlane(
  DWORD dwID,
  LPDIRECT3DRMFRAME3 lpRef,
  LPD3DVECTOR lpdvPoint,
  LPD3DVECTOR lpdvNormal,
  DWORD dwFlags);

파라미터

dwID
변경하는 프레인의 ID번호.
lpRef
포인트와 법선 파라미터의 참조 프레임. 이 파라미터가 NULL라면,lpdvPoint와lpdvNormal는 월드 공간안에 있다.
lpdvPoint
참조 프레임을 기점으로 하는 프레인 위에의 포인트.
lpdvNormal
참조 프레임을 기점으로 하는 프레인에 수직인 벡터.
dwFlags
플래그값. 0이 아니면 안된다.
lpdwReturnID
호출이 성공했을 경우에, 프레인의 일의인 ID번호를 받는 포인터.

반환값

DD_OK 또는DDERR_INVALIDPARAMS 를 돌려준다.

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.


IDirect3DRMDevice3

어플리케이션은,IDirect3DRMDevice3 ,IDirect3DRMDevice2및IDirect3DRMDevice인터페이스를 사용해 출력 디바이스라고 회화한다. 개요에 대해서는, 「출력 디바이스」를 참조할것.

IDirect3DRMDevice3는, 구의IDirect3DRMDevice2와IDirect3DRMDevice인터페이스중의 모든 메소드를 포함하지만, 어느 기준에 근거해 텍스쳐 포맷을 선택하는FindPreferredTextureFormat 메소드를 추가해, 장황한 상태 변경 (상태에 현재의 값과 동일한 값의 설정)을 배제하는, 다음의 4개의 메소드도 추가한다. GetStateChangeOptions ,LightStateChange ,RenderStateChange 및SetStateChangeOptions 이다.

IDirect3DRMDevice2는,IDirect3DRMDevice의 모든 메소드에 가세해, 투명성의 제어를 가능하게 하는 2개의 메소드,GetRenderMode 과SetRenderMode , 1개의 초기화 메소드InitFromSurface , 한층 더IDirect3DRMDevice오브젝트는 아니고IDirect3DRMDevice2오브젝트를 꺼내거나 초기화하는 2개의 변경 메소드GetDirect3DDevice2 와InitFromD3D2 를 포함한다.

IDirect3DRMDevice3또는IDirect3DRMDevice2인터페이스를, 각각IDirect3DRM3또는IDirect3DRM2인터페이스로부터 생성 하든가, 혹은 대응하는IDirect3DRMDevice3메소드,InitFromClipper ,InitFromD3D2 , 또는InitFromSurface 를 사용해 어느 쪽인가의 인터페이스를 초기화하는 경우, 그 인터페이스는IDirect3DDevice3또는IDirect3DDevice2직접 모드 디바이스와 함께 각각 기능한다. IDirect3DDevice3와IDirect3DDevice2디바이스는,DrawPrimitive인터페이스와 함께 실행 버퍼도 지원 해, 프로그래시브 메쉬, 알파 블렌딩, 투명 오브젝트의 소트에 필요하다. IDirect3DRM인터페이스로부터 구의IDirect3DRMDevice인터페이스를 생성 하는 경우,IDirect3DRMDevice보관 유지 모드 인터페이스는IDirect3DDevice직접 모드 디바이스와 함께 기능한다.

InitFromClipper 와InitFromSurface 메소드는,IDirect3DRM3::CreateDevice 를 사용해Direct3DRMDevice3오브젝트를 생성한다.

InitFromD3D2 메소드는,IDirect3D2직접 모드 오브젝트와IDirect3DDevice2직접 모드 디바이스를 사용해IDirect3DDevice2 Direct3D 보관 유지 모드 디바이스를 초기화한다.

유저는, 계속IDirect3DRMDevice3,IDirect3DRMDevice2,IDirect3DRMDevice인터페이스의 사이를 조회할 수가 있다. 주된 차이점은, 기저의 직접 모드 디바이스의 생성 방법에 있다.

IDirect3DRMDevice3인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.
버퍼 카운트 | GetBufferCount
 | SetBufferCount
컬러 모델 | GetColorModel
디저링 | GetDither
 | SetDither
장황한 상태 변경의 삭제 | GetStateChangeOptions
 | LightStateChange
 | RenderStateChange
 | SetStateChangeOptions
초기화 | Init
 | InitFromClipper
 | InitFromD3D2
 | InitFromSurface
그 외 | GetDirect3DDevice2
 | GetHeight
 | GetTrianglesDrawn
 | GetViewports
 | GetWidth
 | GetWireframeOptions
 | Update
통지 | AddUpdateCallback
 | DeleteUpdateCallback
렌더링 퀄리티 | GetQuality
 | SetQuality
쉐이딩 | GetShades
 | SetShades
텍스쳐 | FindPreferredTextureFormat
 | GetTextureQuality
 | SetTextureQuality
투명성 | GetRenderMode
 | SetRenderMode

모든 COM 인터페이스와 같이,IDirect3DRMDevice3인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

게다가IDirect3DRMDevice3인터페이스는,IDirect3DRMObject 인터페이스로부터 이하의 메소드를 계승한다.
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMDevice3오브젝트는,IDirect3DRM3::CreateDevice 메소드를 호출하는 것에 의해 취득된다.

IDirect3DRMDevice3::AddUpdateCallback

IDirect3DRMDevice3

디바이스에 변화가 발생했을 때, 어플리케이션에 경고를 주는 콜백 함수를 추가한다. 시스템은, 어플리케이션이IDirect3DRMDevice3::Update 메소드를 사용했을 때에는 언제나, 반드시 이 콜백 함수를 호출한다.

구문

HRESULT AddUpdateCallback(
  D3DRMDEVICE3UPDATECALLBACK d3drmUpdateProc,
  LPVOID arg
  );

파라미터

d3drmUpdateProc
어플리케이션 정의 콜백 함수D3DRMDEVICE3UPDATECALLBACK 에의 포인터.
arg
갱신 콜백 함수에 건네주는 Private 데이터에의 포인터.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

IDirect3DRMDevice2::AddUpdateCallback와IDirect3DRMDevice::AddUpdateCallback는,d3drmUpdateProc파라미터에 대해서D3DRMUPDATECALLBACK타입의 콜백을 취한다. DirectX version 6.0에 대해서는,IDirect3DRMDevice3는, 보다 새로운D3DRMDEVICE3UPDATECALLBACK 콜백을 도입하고 있다.

참조

IDirect3DRMDevice3::DeleteUpdateCallback , IDirect3DRMDevice3::Update , D3DRMDEVICE3UPDATECALLBACK

IDirect3DRMDevice3::DeleteUpdateCallback

IDirect3DRMDevice3

IDirect3DRMDevice3::AddUpdateCallback 메소드를 사용해 추가된 갱신 콜백 함수를 삭제한다.

구문

HRESULT DeleteUpdateCallback(
  D3DRMDEVICE3UPDATECALLBACK d3drmUpdateProc,
  LPVOID arg
  );

파라미터

d3drmUpdateProc
어플리케이션 정의의D3DRMDEVICE3UPDATECALLBACK 콜백 함수의 주소.
arg
갱신 콜백 함수에게 건네지는 사적인 데이터에의 포인터.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

IDirect3DRMDevice2::DeleteUpdateCallback와IDirect3DRMDevice::DeleteUpdateCallback는,d3drmUpdateProc파라미터에 대해서D3DRMUPDATECALLBACK타입의 콜백을 취한다. DirectX version 6.0에 대해서는,IDirect3DRMDevice3는, 보다 새로운D3DRMDEVICE3UPDATECALLBACK 콜백을 도입하고 있다.

참조

IDirect3DRMDevice3::AddUpdateCallback , IDirect3DRMDevice3::Update , D3DRMDEVICE3UPDATECALLBACK

IDirect3DRMDevice3::FindPreferredTextureFormat

IDirect3DRMDevice3

유저의 기준을 채워, 하층의 직접 모드 디바이스가 지원 하는 텍스쳐 포맷을 검색한다. 텍스쳐 캐쉬의 최적인 퍼포먼스를 얻기 위해서(때문에)는, 이 함수를 사용해 텍스쳐 표면의 픽셀 포맷을 선택한다.

구문

HRESULT FindPreferredTextureFormat(
  DWORD dwBitDepths,
  DWORD dwFlags,
  LPDDPIXELFORMAT  lpDDPF);

파라미터

dwBitDepths
요구된 텍스쳐 포맷 비트 깊이. 비트 깊이가 일절 수용 할 수 없는 것을 나타내려면 , 0을 지정한다. 다음의 DirectDraw 비트 깊이 플래그의 하나 이상의 논리적인 편성을 사용해, 그 외의 값을 지정한다.
DDBD_4
DDBD_8
DDBD_16
DDBD_24
DDBD_32
dwFlags
추가의 요건을 지정하는 플래그. 디폴트의 설정을 사용하려면 , 0을 지정한다. 그 외의 유효값은, 다음의 값의 하나 이상의 논리적인 편성이 아니면 안된다.
D3DRMFPTF_ALPHA
돌려주어지는 텍스쳐 포맷에는, 알파 채널이 없으면 안 된다.
D3DRMFPTF_NOALPHA
돌려주어지는 텍스쳐 포맷에는, 알파 채널이 있어서는 안 된다. 알파 채널의 결핍을 희망하지만, 결핍을 필수로 하지 않는 것을 나타내려면 ,D3DRMFPTF_ALPHA와D3DRMFPTF_NOALPHA의 양플래그를 생략 한다.
D3DRMFPTF_PALETTIZED
D3DRMFPTF_PALETTIZED
돌려주어지는 텍스쳐 포맷은, 팔레트화하지 않으면 안 된다.
D3DRMFPTF_NOTPALETTIZED
돌려주어지는 텍스쳐 포맷은, 팔레트화해서는 안 된다. 팔레트의 결핍을 희망하지만, 결핍을 필수로 하지 않는 것을 나타내려면 ,D3DRMFPTF_PALETTIZED와D3DRMFPTF_NOTPALETTIZED의 양플래그를 생략 한다.
lpDDPF
텍스쳐 포맷을 받는 포인터.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_TEXTUREFORMATNOTFOUND
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

FindPreferredTextureFormat는, 수입 가능한 포맷을 검색할 수 없는 경우D3DRMERR_TEXTUREFORMATNOTFOUND를 돌려준다.

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMDevice3::GetBufferCount

IDirect3DRMDevice3

IDirect3DRMDevice3::SetBufferCount 메소드에 대한 호출로 세트 된 값을 취득한다.

구문

DWORD GetBufferCount( );

반환값

버퍼의 수이며, 싱글 버퍼링에 대해서는 1, 더블 버퍼링에 대해서는 2, 등을 돌려준다.

IDirect3DRMDevice3::GetColorModel

IDirect3DRMDevice3

디바이스의 컬러 모델을 취득한다.

구문

D3DCOLORMODEL GetColorModel( );

반환값

Direct3D 컬러 모델(RGB 또는 흑백)을 기술하는D3DCOLORMODEL 열거형으로부터 값을 돌려준다.

참조

「컬러 모델」

IDirect3DRMDevice3::GetDirect3DDevice2

IDirect3DRMDevice3

IDirect3DDevice2직접 모드 디바이스에의 포인터를 취득한다.

구문

HRESULT GetDirect3DDevice2(
  LPDIRECT3DDEVICE2 *lplpD3DDevice
  );

파라미터

lplpD3DDevice
IDirect3DDevice2직접 모드 디바이스 오브젝트에의 포인터를 사용해 초기화되는 포인터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

IDirect3DDevice2디바이스는, DrawPrimitive 인터페이스와 함께 실행 버퍼도 지원 해, 프로그래시브 메쉬, 알파 블렌딩, 및 투명 오브젝트의 소트에 필요하다.

IDirect3DRMDevice3::GetDither

IDirect3DRMDevice3

디바이스의 디저링 플래그를 취득한다.

구문

BOOL GetDither( );

반환값

디저링 플래그가 세트 되고 있으면 TRUE, 그렇지 않으면 FALSE를 돌려준다.

참조

IDirect3DRMDevice3::SetDither

IDirect3DRMDevice3::GetHeight

IDirect3DRMDevice3

디바이스의 높이를 픽셀 단위로 취득한다. 이 메소드는, 편리한 함수이다.

구문

DWORD GetHeight( );

반환값

높이를 돌려준다.

IDirect3DRMDevice3::GetQuality

IDirect3DRMDevice3

디바이스의 렌더링 퀄리티를 취득한다.

구문

D3DRMRENDERQUALITY GetQuality( );

반환값

D3DRMRENDERQUALITY 열거형으로 나타내진 열거형의 하나 또는 복수의 멤버를 돌려준다.

참조

IDirect3DRMDevice3::SetQuality

IDirect3DRMDevice3::GetRenderMode

IDirect3DRMDevice3

현재의 투명성 플래그를 취득한다.

구문

DWORD GetRenderMode( );

반환값

현재의 투명성 플래그의 값을 돌려준다.

주의

투명성 플래그는, 이하의 값을 가진다.
플래그 | 값
플래그세트 없음(디폴트) | 0
D3DRMRENDERMODE_BLENDEDTRANSPARENCY | 1
D3DRMRENDERMODE_DISABLESORTEDALPHAZWRITE | 32
D3DRMRENDERMODE_LIGHTINMODELSPACE | 8
D3DRMRENDERMODE_SORTEDTRANSPARENCY | 2
D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR | 16

참조

IDirect3DRMDevice3::SetRenderMode

IDirect3DRMDevice3::GetShades

IDirect3DRMDevice3

쉐이딩에 사용되는 색의 램프에서의 쉐이드수를 취득한다.

구문

DWORD GetShades( );

반환값

쉐이드수를 돌려준다.

참조

IDirect3DRMDevice3::SetShades

IDirect3DRMDevice3::GetStateChangeOptions

IDirect3DRMDevice3

렌더링 또는 조명 상태에 관련지을 수 있었던 상태 변경 옵션 플래그를 취득한다. 상세한 것에 대하여는, 「장황한 상태 변경의 삭제」를 참조할것.

구문

HRESULT GetStateChangeOptions(
  DWORD dwStateClass,
  DWORD dwStateNum,
  LPDWORD pdwFlags
  );

파라미터

해당하는 상태가 속하는 상태의 클래스. 이 값에는, D3DRMSTATECHANGE_LIGHT 또는 D3DRMSTATECHANGE_RENDER를 세트 할 수 있다.
dwStateNum
해당하는 D3DRENDERSTATE 또는 D3DLIGHTSTATE의 번호. 값 0은, 소정의 클래스의 모든 상태가 영향을 받는 것을 나타낸다.
pdwFlags
옵션 플래그에의 포인터. 다음의 값의 어떤 것이나 1개를 포함한다.
D3DRMSTATECHANGE_NONVOLATILE
D3DRMSTATECHANGE_VOLATILE

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

다음의 코드예는, 텍스쳐 핸들 렌더링 상태에 관한 옵션을 취득한다.

lpDirect3DRMDev3->GetStateChangeOptions(D3DRMSTATECHANGE_RENDER,
                          D3DRENDERSTATE_TEXTUREHANDLE, &dwFlags);

참조

IDirect3DRMDevice3::SetStateChangeOptions

IDirect3DRMDevice3::GetTextureQuality

IDirect3DRMDevice3

디바이스의 현재의 텍스쳐 퀄리티 파라미터를 취득한다. 텍스쳐 퀄리티는, RGB 디바이스인 만큼 관계한다.

구문

D3DRMTEXTUREQUALITY GetTextureQuality( );

반환값

D3DRMTEXTUREQUALITY 열거형의 멤버의 하나를 돌려준다.

참조

IDirect3DRMDevice3::SetTextureQuality

IDirect3DRMDevice3::GetTrianglesDrawn

IDirect3DRMDevice3

디바이스가 생성 된 이후, 그 디바이스에 드로잉(Drawing) 된 삼각형의 수를 취득한다. 이 메소드는, 편리한 함수이다.

구문

DWORD GetTrianglesDrawn( );

반환값

삼각형의 수를 돌려준다.

주의

삼각형의 수는, 렌더러에게 건네졌지만, 뒤(카메라의 방향과 역의면)에 숨겨졌기 때문에 드로잉(Drawing) 되지 않았던 것을 포함한다. 절두체의 외측에 있어 거절된 삼각형은 포함되지 않는다.

IDirect3DRMDevice3::GetViewports

IDirect3DRMDevice3

디바이스로부터 현재 구축되고 있는 뷰포트를 나타내는Direct3DRMViewportArray오브젝트를 구축한다.

구문

HRESULT GetViewports(
  LPDIRECT3DRMVIEWPORTARRAY *lplpViewports
  );

파라미터

lplpViewports
호출이 성공했을 경우에, 유효한Direct3DRMViewportArray오브젝트로 초기화되는 포인터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMDevice3::GetWidth

IDirect3DRMDevice3

디바이스의 픽셀 단위의 폭을 취득한다. 이 메소드는, 편리한 함수이다.

구문

DWORD GetWidth( );

반환값

픽셀 단위로, 디바이스의 폭을 돌려준다.

IDirect3DRMDevice3::GetWireframeOptions

IDirect3DRMDevice3

지정의 디바이스의 와이어 프레임 옵션을 취득한다.

구문

DWORD GetWireframeOptions( );

반환값

이하의 값의 비트마다의 OR연산의 결과를 돌려준다.

D3DRMWIREFRAME_CULL
뒤에 숨겨진 면은, 드로잉(Drawing) 되지 않는다.
D3DRMWIREFRAME_HIDDENLINE
와이어 프레임 렌더링 된 선은, 인접의 오브젝트로 숨겨진다.

IDirect3DRMDevice3::Init

IDirect3DRMDevice3

Microsoft® Windows®플랫폼에서는 미이행이다.

구문

HRESULT Init(
  ULONG width,
  ULONG height
  );

IDirect3DRMDevice3::InitFromClipper

IDirect3DRMDevice3

IDirect3DRM3::CreateDevice 를 사용해, 지정의DirectDrawClipper오브젝트의IDirect3DDevice2디바이스를 초기화한다.

구문

HRESULT InitFromClipper(
  LPDIRECTDRAWCLIPPER lpDDClipper,
  LPGUID lpGUID,
  int width,
  int height
  );

파라미터

lpDDClipper
초기화 수단으로서 사용하는DirectDrawClipper오브젝트에의 포인터.
lpGUID
사용하는 Direct3D 디바이스 드라이버.
width, height
픽셀 단위에서의 디바이스의 폭과 높이.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMDevice3::InitFromD3D2

IDirect3DRMDevice3

IDirect3D2직접 모드 오브젝트와IDirect3DDevice2직접 모드 디바이스로부터,IDirect3DRMDevice2보관 유지 모드 디바이스를 초기화한다.

구문

HRESULT InitFromD3D2(
  LPDIRECT3D2 lpD3D,
  LPDIRECT3DDEVICE2 lpD3DIMDev
  );

파라미터

lpD3D
보관 유지 모드 디바이스를 초기화하는데 사용하는IDirect3D2직접 모드 오브젝트에의 포인터.
lpD3DIMDev
보관 유지 모드 디바이스를 초기화하는데 사용하는 IDirect3DDevice2직접 모드 디바이스에의 포인터.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

IDirect3DRMDevice2로부터 초기화된IDirect3DDevice2디바이스는, DrawPrimitive 인터페이스와 함께 실행 버퍼도 지원 해, 프로그래시브 메쉬, 알파 블렌딩, 및 투명 오브젝트의 소트에 필요하게 된다.

IDirect3DRMDevice3::InitFromSurface

IDirect3DRMDevice3

IDirect3DRM3::CreateDevice 를 사용해, 지정한 DirectDraw 표면으로부터IDirect3DDevice2디바이스를 초기화한다.

구문

HRESULT InitFromSurface(
  LPGUID lpGUID,
  LPDIRECTDRAW lpDD,
  LPDIRECTDRAWSURFACE lpDDSBack
  );

파라미터

lpGUID
사용하는 Direct3D 디바이스를 식별하는 글로벌 유니크 식별자(GUID)에의 포인터.
lpDD
DirectDrawSurface를 생성한 DirectDraw 오브젝트의 인터페이스에의 포인터.
lpDDSBack
DirectDrawSurface 백 버퍼의 인터페이스에의 포인터. 그백 버퍼상에서 디바이스가 렌더링을 실시한다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

초기화된IDirect3DRMDevice2디바이스는, DrawPrimitive 인터페이스와 함께 실행 버퍼를 지원 해, 프로그래시브 메쉬, 알파 블렌딩, 및 투명 오브젝트의 소트에 필요하다.

IDirect3DRMDevice3::LightStateChange

IDirect3DRMDevice3

조명 상태를 변경하는지, 또는 Direct3D 보관 유지 모드에 렌더링 상태에의 변경을 통지한다. D3DRMSTATECHANGE_NONVOLATILE 플래그가 렌더링 상태에 관련지을 수 있고 있는 경우, 보관 유지 모드는IDirect3DRMDevice3 를 사용해 간 장황한 상태 변경을 배제한다(상태를 현재의 값에 동일한 값에 세트 하는 것을 하지 않는다). 상세한 것에 대하여는, 「장황한 상태 변경의 삭제」를 참조할것.

구문

HRESULT LightStateChange(
  DWORD dwStateNum,
  DWORD dwVal,
  DWORD dwFlags
  );

파라미터

dwStateNum
해당하는 D3DLIGHTSTATE 번호.
dwVal
상태의 새로운 값.
dwFlags
보관 유지 모드가 캐쉬만을 갱신할지 어떨지를 나타내는 플래그. 이 플래그가 D3DRMSTATECHANGE_UPDATEONLY에 세트 되고 있는 경우, 내장형 캐쉬에 보관 유지되고 있는 값만 갱신된다. D3DRMSTATECHANGE_UPDATEONLY를 사용해, 상태 변경을 나타낼 수가 있다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

다음의 코드는 머트리얼 핸들 조명 상태를 세트 해, D3DRMSTATECHANGE_NONVOLATILE 플래그가 그 상태에 관련지을 수 있고 있는 경우에는 장황한 변경을 배제한다.

lpDirect3DRMDev3->LightStateChange(D3DLIGHTSTATE_MATERIAL, hMat, 0);

다음에 포그(안개:fog) 모드에의 변경을 나타낸다.

lpDirect3DRMDev3->LightStateChange(D3DLIGHTSTATE_FOGMODE, D3DFOG_NONE,
                                   D3DRMSTATECHANGE_UPDATEONLY);

참조

IDirect3DRMDevice3::SetStateChangeOptions

IDirect3DRMDevice3::RenderStateChange

IDirect3DRMDevice3

렌더링 상태를 변경하는지, 또는 렌더링 상태에의 변경을 나타낸다. D3DRMSTATECHANGE_NONVOLATILE 플래그가 렌더링 상태에 관련지을 수 있고 있는 경우, 보관 유지 모드는IDirect3DRMDevice3를 사용해 간 장황한 상태 변경을 배제한다(상태를 현재의 값에 동일한 값에 세트 하는 것을 하지 않는다). 상세한 것에 대하여는, 「장황한 상태 변경의 삭제」를 참조할것.

구문

HRESULT RenderStateChange(
  DWORD dwStateNum,
  DWORD dwVal,
  DWORD dwFlags
  );

파라미터

dwStateNum
해당하는 D3DRENDERSTATE 번호.
dwVal
상태의 새로운 값.
dwFlags
캐쉬만 갱신할지 어떨지를 나타내는 플래그. 이 플래그가 D3DRMSTATECHANGE_UPDATEONLY에 세트 되고 있는 경우, 내장형 캐쉬에 보관 유지되고 있는 값만 갱신된다. D3DRMSTATECHANGE_UPDATEONLY를 사용해, 상태의 변경을 나타낼 수가 있다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

다음의 코드는 전부 칠해 모드 렌더링 상태를 세트 해, D3DRMSTATECHANGE_NONVOLATILE 플래그가 그 상태에 관련지을 수 있고 있는 경우에는 장황한 변경을 배제한다.

lpDirect3DRMDev3->RenderStateChange(D3DRENDERSTATE_FILLMODE,
                          D3DFILL_SOLID, 0);

다음의 코드는, 텍스쳐 핸들 렌더링 상태에의 변경을 나타낸다.

lpDirect3DRMDev3->RenderStateChange(D3DRENDERSTATE_TEXTUREHANDLE, hTex,
                                    D3DRMSTATECHANGE_UPDATEONLY);

참조

IDirect3DRMDevice3::SetStateChangeOptions

IDirect3DRMDevice3::SetBufferCount

IDirect3DRMDevice3

현재 어플리케이션으로 사용되고 있는 버퍼의 수를 설정한다.

구문

HRESULT SetBufferCount(
  DWORD dwCount
  );

파라미터

dwCount
버퍼의 수를, 싱글 버퍼링에 대해서는 1, 더블 버퍼링에 대해서는 2등과 지정한다. 디폴트값은 1이며, 싱글 버퍼링 윈도우 조작 에 대해서만 유효하다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

어플리케이션이, 더블 버퍼링이나 트리플 버퍼링을 실시할 때는, 이 메소드로, 사용하는 버퍼수를 시스템에 통지해, 시스템이 각 프레임에 대해서, 윈도우의 어느 부분을 클리어 및 갱신하는지를 계산할 수 있도록(듯이) 해야 한다.

참조

IDirect3DRMDevice3::GetBufferCount

IDirect3DRMDevice3::SetDither

IDirect3DRMDevice3

디바이스의 디저링 플래그를 설정한다.

구문

HRESULT SetDither(
  BOOL bDither
  );

파라미터

bDither
디바이스의 새로운 디저링 모드. 디폴트는 TRUE이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMDevice3::GetDither

IDirect3DRMDevice3::SetQuality

IDirect3DRMDevice3

디바이스의 렌더링 퀄리티를 설정한다.

구문

HRESULT SetQuality (
  D3DRMRENDERQUALITY rqQuality
  );

파라미터

rqQuality
D3DRMRENDERQUALITY 열거형으로 나타내진 열거형의 하나 또는 복수의 멤버. 디폴트 설정값은, D3DRMRENDER_FLAT이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

렌더링 퀄리티는, 디바이스의 렌더링 얼굴로 실행되는 렌더링의 퀄리티의 최대치이다.

오브젝트 퀄리티에는, 3개의 컴퍼넌트가 있다. 즉, 쉐이딩 모드 (플랫 또는 굿 로로, 폰은 이행되어 있지 않다. 디폴트는 gouraud shading), 조명 타입 (온 또는 오프) 및 전부 칠해 모드 (포인트, 와이어 프레임 또는 솔리드)이다.

디바이스의 퀄리티를 설정하려면 ,SetQuality를 이용한다. 디폴트에서는, 디바이스 퀄리티는 D3DRMRENDER_FLAT (flat shading, 조명 온 및 솔리드 전부 칠해)이다.

Direct3DRMProgressiveMesh , 또는Direct3DRMMeshBuilder3 오브젝트의 퀄리티는, 각각의SetQuality메소드를 이용해 설정할 수가 있다. 디폴트에서는, 이러한 오브젝트의 퀄리티는, D3DRMRENDER_GOURAUD(gouraud shading, 조명 온 및 솔리드 전부 칠해)이다.

힌트: gouraud shading는, 상세 레벨을 빈번하게 또는 재빠르게 변경하는 프로그래시브 메쉬 오브젝트에 대해, 보다 좋은 퍼포먼스를 얻을 수 있다.

Direct3D 보관 유지 모드는, 디바이스나 오브젝트의 각각의 컴퍼넌트에 대한 현재의 설정 중(안)에서, 가장 저위의 퀄리티로, 오브젝트에 렌더링을 실시한다. 예를 들어, 오브젝트의 현재의 퀄리티 설정이 D3DRMRENDER_GOURAUD로, 디바이스가 D3DRMRENDER_FLAT이라고, 오브젝트는 flat shading, 솔리드 전부 칠해, 및 조명 온으로 렌더링 된다.

오브젝트의 현재의 퀄리티 설정이 D3DRMSHADE_GOURAUD|D3DRMLIGHT_OFF|D3DRMFILL_WIREFRAME로, 디바이스의 퀄리티 설정이 D3DRMSHADE_FLAT|D3DRMLIGHT_ON|D3DRMFILL_POINT이라고, 오브젝트는 flat shading, 조명 오프, 및 포인트 전부 칠해 모드로 렌더링 된다.

이러한 룰은,Direct3DRMMeshBuilder3오브젝트 및Direct3DRMProgressiveMesh오브젝트에 적용된다. 그러나,Direct3DRMMesh오브젝트는 이러한 룰에 따르지 않다. 메쉬 오브젝트는 디바이스의 퀄리티 설정을 무시해, 그룹 퀄리티 설정을 이용한다(디폴트로 D3DRMRENDER_GOURAUD).

참조

IDirect3DRMDevice3::GetQuality

IDirect3DRMDevice3::SetRenderMode

IDirect3DRMDevice3

투명 모드를 설정한다. 모드 타입은, 오브젝트를 어느 정도 투명하게 렌더링 할까를 결정한다. 디폴트 모드에서는, 투명 점묘로 투명 오브젝트를 렌더링 한다.

구문

HRESULT SetRenderMode(
  DWORD dwFlags
  );

파라미터

dwFlags
1개또는 복수의 투명 모드 플래그. 디폴트 (dwFlags = 0)에서는, 투명 모드를 투명 점묘로 설정한다. 점묘 (또는 「스크린 문」)에 의한 투명 모드는, 어느 이미지중의 몇개의 픽셀을 그 외의 이미지의 픽셀로 치환 (마치, 어느 이미지를 2번째의 이미지로 칠해진 스크린 문을 통해 보는것 같이)하는 것으로써 달성된다.

게다가 플래그는 1개이상의, 이하의 값을 가질 수가 있다.

D3DRMRENDERMODE_BLENDEDTRANSPARENCY (dwFlags = 1)는, 투명 모드를 알파 블렌딩으로 설정한다. 블렌딩에 의한 투명 모드는, 각 픽셀로 컬러값을 추가해 2개의 이미지를 조합하는 것으로 달성된다.
D3DRMRENDERMODE_DISABLESORTEDALPHAZWRITE (dwFlags = 32)는, 소트 된 투명 오브젝트를 드로잉(Drawing) 할 때, z버퍼에 깊이 정보를 기입하지 않는 것을 지정한다.
D3DRMRENDERMODE_LIGHTINMODELSPACE (dwFlags = 8)는, 예약이 끝난 상태. 사용하지 않는 것.
D3DRMRENDERMODE_SORTEDTRANSPARENCY (dwFlags = 2)는, 장면안의 투명 다각형이 제2 패스로 버퍼링, 소트, 및 렌더링 되도록(듯이) 투명 모드를 설정한다. 이 플래그는, D3DRMRENDERMODE_BLENDEDTRANSPARENCY 플래그도 동시에 세트되어 있지 않은 경우에는, 아무 효과도 없다. 외부 비주얼 또는 유저 비주얼중의 투명 다각형은 소트 되지 않는다. 네이티브 D3DRM 비주얼 (D3DRMMesh 오브젝트와 D3DRMMeshBuilder 오브젝트등) 마셔 소트 된다.
D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR (dwFlags = 16)는, 광원 방향과 뷰아의 위치의 양쪽 모두에 의존하는, 보다 현실적인 반사광을 가능하게 한다. DirectX Foundation의 이전의 버젼만, 뷰아의 위치를 고려하지 않는 플랫인 반사광을 지원 한다. 이 플래그가 세트 되고 있으면(자), Direct3D 직접 모드는D3DLIGHT2구조체를 사용해, Direct3D 직접 모드의IDirect3DLight::SetLight호출시에 조명 타입을 정의한다. 이 플래그가 세트되어 있지 않은 경우, D3DRM는D3DLIGHT구조체를 사용해, DirectX의 이전의 버젼의 라이팅 동작을 얻게 된다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

D3DRMRENDERMODE_BLENDEDTRANSPARENCY 및 D3DRMRENDERMODE_SORTEDTRANSPARENCY의 양플래그가, 동시에 세트 되고 있으면, 2개의 투명 오브젝트가, 한편을 한편으로 렌더링 하도록(듯이) 보증해, 이미지는, 기대 그대로의 비주얼 효과를 만들어 내도록(듯이) 올바른 순서로 혼합된다.

D3DRMRENDERMODE_SORTEDTRANSPARENCY는, 알파 다각형의 삼각형마다의, 뒤로부터 전에의 소트를 온으로 한다. 네이티브 D3DRM 비주얼 (D3DRMMesh 오브젝트와 D3DRMMeshBuilder 오브젝트등) 마셔 소트 된다. 외부 비주얼의 삼각형을 소트 리스트에 추가할 수 없다.

D3DRMRENDERMODE_BLENDEDTRANSPARENCY 플래그는, 점묘 알파에 대항해 진정한 알파 블렌딩을 온으로 한다. 진정한 알파 블렌딩에서는, 중복 하는 삼각형의 픽셀은 정리해 혼합된다. 점묘 알파에서는, 전면에 있는 삼각형의 픽셀의 몇개인가는, 아래에 있는 삼각형을 표시하는 것 같은 드로잉(Drawing)를 하지 않는다 (이것은, 스크린 문의 투명이라고도 불린다). 점묘 알파를 실행하는 경우, 삼각형을 어떠한 순서로 렌더링 할까에 관계없이, 결과가 같기 때문에, 삼각형을 소트 할 필요는 없다.

SetSortMode에 대한 유효한 파라미터는, 0 (소트 없음의 점묘 알파), BLENDEDTRANSPARENCY (소트 없음의 진정한 알파), 및 BLENDEDTRANSPARENCY와 SORTEDTRANSPARENCY (삼각형 마다 소트 된 진정한 알파)의 양쪽 모두 뿐이다.

참조

IDirect3DRMDevice3::GetRenderMode

IDirect3DRMDevice3::SetShades

IDirect3DRMDevice3

흑백 (램프) 모델 쉐이딩에 사용되는 색의 램프에서의 쉐이드수를 설정한다.

구문

HRESULT SetShades(
  DWORD ulShades
  );

파라미터

ulShades
새로운 쉐이드수. 이 파라미터는, 2의 거듭제곱이 아니면 안된다. 디폴트는, 32이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMDevice3::GetShades

IDirect3DRMDevice3::SetStateChangeOptions

IDirect3DRMDevice3

1개이상의 렌더링 또는 조명 상태에 관련지을 수 있었던 옵션 플래그를 변경한다. 모든 렌더링과 조명 상태의 디폴트값은, D3DRMSTATECHANGE_VOLATILE이다. D3DRMSTATECHANGE_NONVOLATILE 플래그가 렌더링 또는 조명 상태에 관련지을 수 있고 있는 경우, Direct3D 보관 유지 모드는 그 값을 캐쉬해, 장황한 변경을 배제한다 (상태를 현재의 값에 동일한 값에 세트 하는 것을 하지 않는다). 그러나,LightStateChange 또는RenderStateChange 메소드의 어딘가에 따라 언제 상태를 변경했는지를 나타내지 않으면 안 된다. 상세한 것에 대하여는, 「장황한 상태 변경의 삭제」를 참조할것.

구문

HRESULT SetStateChangeOptions(
  DWORD dwStateClass,
  DWORD dwStateNum,
  DWORD dwFlags
  );

파라미터

dwStateClass
해당하는 상태가 속하는 상태의 클래스. 이 값에는, D3DRMSTATECHANGE_LIGHT 또는 D3DRMSTATECHANGE_RENDER를 세트 할 수 있다.
dwStateNum
해당하는 D3DRENDERSTATE 또는 D3DLIGHTSTATE의 번호. 값 0은, 소정의 클래스의 모든 상태가 영향을 받는 것을 나타낸다.
dwFlags
옵션 플래그. 다음의 값의 어떤 것이나 1개이다.
D3DRMSTATECHANGE_NONVOLATILE
D3DRMSTATECHANGE_VOLATILE

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

다음의 코드는, 모든 렌더링 상태로 D3DRMSTATECHANGE_NONVOLATILE 플래그를 온에 세트 한다.

lpDirect3DRMDev3->SetStateChangeOptions(D3DRMSTATECHANGE_RENDER, 0,
                                        D3DRMSTATECHANGE_NONVOLATILE);

다음의 코드는, 텍스쳐 핸들 렌더링 상태로 D3DRMSTATECHANGE_VOLATILE 플래그를 온에 세트 한다.

lpDirect3DRMDev3->SetStateChangeOptions(D3DRMSTATECHANGE_RENDER,
                                        D3DRENDERSTATE_TEXTUREHANDLE,
                                        D3DRMSTATECHANGE_VOLATILE);

참조

IDirect3DRMDevice3::GetStateChangeOptions

IDirect3DRMDevice3::SetTextureQuality

IDirect3DRMDevice3

디바이스에 대한 텍스쳐 퀄리티를 설정한다.

구문

HRESULT SetTextureQuality(
  D3DRMTEXTUREQUALITY tqTextureQuality
  );

파라미터

tqTextureQuality
D3DRMTEXTUREQUALITY 열거형의 멤버의 하나. 디폴트는,D3DRMTEXTURE_NEAREST 이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMDevice3::GetTextureQuality

IDirect3DRMDevice3::Update

IDirect3DRMDevice3

렌더링 되고 있는 이미지를 디스플레이에 카피한다. 또, 디바이스 드라이버에 하트 비트 함수도 준다. 그리고, 이미지를 언제 갱신할까를 알린다.

구문

HRESULT Update( );

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드에 대한 각 호출은, 시스템에 어플리케이션 정의 콜백 함수의D3DRMDEVICE3UPDATECALLBACK 를 호출하게 한다. 콜백 함수를 추가하려면 ,IDirect3DRMDevice3::AddUpdateCallback 메소드를 사용한다.

IDirect3DRMDevice2::Update와IDirect3DRMDevice::Update는, 시스템이D3DRMUPDATECALLBACK타입 콜백을 호출하도록(듯이) 한다. DirectX version 6.0에 대해서는,IDirect3DRMDevice3는, 보다 새로운D3DRMDEVICE3UPDATECALLBACK 콜백을 도입한다.

참조

IDirect3DRMDevice3::AddUpdateCallback , D3DRMDEVICE3UPDATECALLBACK


IDirect3DRMDeviceArray

어플리케이션은,IDirect3DRMDeviceArray인터페이스의 메소드를 사용해 디바이스 오브젝트를 정리한다. 이 항은, 이 인터페이스의 메소드의 레퍼런스이다. 개요에 대해서는, 「출력 디바이스」를 참조할것.

IDirect3DRMDeviceArray인터페이스는, 다음의 메소드를 지원 한다.
GetElement
GetSize

모든 COM 인터페이스와 같이,IDirect3DRMDeviceArray인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

Direct3DRMDeviceArray 오브젝트는,IDirect3DRM3::GetDevices 메소드의 호출에 의해 취득된다.

IDirect3DRMDeviceArray::GetElement

IDirect3DRMDeviceArray

Direct3DRMDeviceArray 오브젝트로부터 지정된 요소를 취득한다.

구문

HRESULT GetElement(
  DWORD index,
  LPDIRECT3DRMDEVICE *lplpD3DRMDevice
  );

파라미터

index
배열 요소.
lplpD3DRMDevice
IDirect3DRMDevice 인터페이스에의 포인터.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

QueryInterface를 사용해, 예를 들어,IDirect3DRMDevice3 등의 희망하는IDirect3DRMDevice의 버젼에의 포인터를 취득할 수가 있다. lplpD3DRMDevice파라미터를, 단순하게 다른 버젼에 형태 변환할 수 없다. QueryInterface를 사용해야 한다.

IDirect3DRMDeviceArray::GetSize

IDirect3DRMDeviceArray

Direct3DRMDeviceArray 오브젝트에 포함되는 요소수를 취득한다.

구문

DWORD GetSize( );

반환값

요소수를 돌려준다.


IDirect3DRMFace2

어플리케이션은, 면과 서로 교환하기 위해서IDirect3DRMFace2인터페이스의 메소드를 사용한다. 면은, 메쉬 위에의 1개의 다각형이다. 어플리케이션은,IDirect3DRMFace2::SetColor ,IDirect3DRMFace2::SetColorRGB ,IDirect3DRMFace2::SetTexture , 및IDirect3DRMFace2::SetMaterial 메소드를 사용해, 면의 색, 텍스쳐, 머트리얼을 세트 할 수가 있다.

면은,IDirect3DRMFace2::AddVertex 와IDirect3DRMFace2::AddVertexAndNormalIndexed 메소드를 사용해 버텍스로부터 구축한다. 어플리케이션은,IDirect3DRMFace2::GetVertices 와IDirect3DRMFace2::GetVertex 메소드를 사용해 면의 버텍스를 읽어들일 수가 있다.

IDirect3DRMFace2에서는,SetTexture 메소드는, 그 폭과 높이가 2의 거듭제곱이 아닌 텍스쳐를 지정할 수가 있다.

IDirect3DRMFace2인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

색 | GetColor
 | SetColor
 | SetColorRGB
머트리얼 | GetMaterial
 | SetMaterial
텍스쳐 | GetTexture
 | GetTextureCoordinateIndex
 | GetTextureCoordinates
 | SetTexture
 | SetTextureCoordinates
 | SetTextureTopology
버텍스와 법선 | AddVertex
 | AddVertexAndNormalIndexed
 | GetNormal
 | GetVertex
 | GetVertexCount
 | GetVertexIndex
 | GetVertices

모든 COM 인터페이스와 같이,IDirect3DRMFace2인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

게다가IDirect3DRMFace2인터페이스는,IDirect3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMFace2 오브젝트는,IDirect3DRM3::CreateFace 메소드의 호출에 의해 취득된다.

IDirect3DRMFace2::AddVertex

IDirect3DRMFace2

Direct3DRMFace2 오브젝트에 버텍스를 추가한다.

구문

HRESULT AddVertex(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z
  );

파라미터

x, y, z
새로운 버텍스 위치의 x, y, z좌표.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMFace2::AddVertexAndNormalIndexed

IDirect3DRMFace2

버텍스와 법선을 Direct3DRMFace2 오브젝트에 추가한다. 이 때, 메쉬 빌더에 포함되는 버텍스의 인덱스와 법선의 인덱스를 사용한다. 면, 버텍스, 법선은, Direct3DRMMeshBuilder3 오브젝트가 일부에서 없으면 안 된다.

구문

HRESULT AddVertexAndNormalIndexed(
  DWORD vertex,
  DWORD normal
  );

파라미터

vertex, normal
추가하는 버텍스와 법선의 인덱스.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMFace2::GetColor

IDirect3DRMFace2

Direct3DRMFace2 오브젝트의 색을 취득한다.

구문

D3DCOLOR GetColor( );

반환값

색을 돌려준다.

참조

IDirect3DRMFace2::SetColor

IDirect3DRMFace2::GetMaterial

IDirect3DRMFace2

Direct3DRMFace2 오브젝트의 머트리얼을 취득한다.

구문

HRESULT GetMaterial(
  LPDIRECT3DRMMATERIAL *lplpMaterial
  );

파라미터

lplpMaterial
면에 적용되고 있는 Direct3DRMMaterial 오브젝트에의 포인터를 받는 변수의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMFace2::SetMaterial

IDirect3DRMFace2::GetNormal

IDirect3DRMFace2

Direct3DRMFace2 오브젝트의법선 벡터를 취득한다.

구문

HRESULT GetNormal(
  D3DVECTOR *lpNormal
  );

파라미터

lpNormal
면의 법선 벡터를 받는D3DVECTOR 구조체의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMFace2::GetTexture

IDirect3DRMFace2

Direct3DRMFace2 오브젝트에 적용된 텍스쳐를 취득한다.

구문

HRESULT GetTexture(
  LPDIRECT3DRMTEXTURE *lplpTexture
  );

파라미터

lplpTexture
면에 적용된 텍스쳐에의 포인터를 받는 변수의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMFace2::SetTexture

IDirect3DRMFace2::GetTextureCoordinateIndex

IDirect3DRMFace2

면의 메쉬에 있는 버텍스의 인덱스를 텍스쳐 좌표로 취득한다. 면을 기점으로 하는 버텍스 인덱스를which파라미터로 건네주면(자), 이 메소드는, 대응하는 메쉬를 기점으로 하는 버텍스 인덱스를 돌려준다.

구문

int GetTextureCoordinateIndex(
  DWORD which
  );

파라미터

which
대응하는 메쉬 버텍스 인덱스를 꺼내 안의 버텍스의 면내의 인덱스.

반환값

면의 메쉬를 기점으로 하는 버텍스 인덱스를 돌려준다.

IDirect3DRMFace2::GetTextureCoordinates

IDirect3DRMFace2

Direct3DRMFace2 오브젝트중의 버텍스의 텍스쳐 좌표를 취득한다.

구문

HRESULT GetTextureCoordinates(
  DWORD index,
  D3DVALUE *lpU,
  D3DVALUE *lpV
  );

파라미터

index
버텍스의 인덱스.
lpU, lpV
점의 텍스쳐 좌표를 받는 변수의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMFace2::GetVertex

IDirect3DRMFace2

Direct3DRMFace2 오브젝트중의 버텍스의 위치와 법선을 취득한다.

구문

HRESULT GetVertex(
  DWORD index,
  D3DVECTOR *lpPosition,
  D3DVECTOR *lpNormal
  );

파라미터

index
버텍스의 인덱스.
lpPosition, lpNormal
버텍스의 위치와 법선을 받는D3DVECTOR 구조체의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMFace2::GetVertexCount

IDirect3DRMFace2

Direct3DRMFace2 오브젝트의 버텍스의 수를 취득한다.

구문

int GetVertexCount( );

반환값

버텍스의 수를 돌려준다.

IDirect3DRMFace2::GetVertexIndex

IDirect3DRMFace2

면의 메쉬에 있는 버텍스의 인덱스를 취득한다. 면을 기점으로 하는 버텍스 인덱스를which파라미터로 건네주면(자), 이 메소드는, 대응하는 메쉬를 기점으로 하는 버텍스 인덱스를 돌려준다.

구문

int GetVertexIndex (
  DWORD which
  );

파라미터

which
대응하는 메쉬 버텍스 인덱스를 꺼내 안의 버텍스의 면내의 인덱스.

반환값

메쉬를 기점으로 하는 버텍스 인덱스를 돌려준다.

IDirect3DRMFace2::GetVertices

IDirect3DRMFace2

Direct3DRMFace2 오브젝트중의 각각의 버텍스에 대해, 위치와법선 벡터를 취득한다.

구문

HRESULT GetVertices(
  DWORD *lpdwVertexCount,
  D3DVECTOR *lpPosition,
  D3DVECTOR *lpNormal
  );

파라미터

lpdwVertexCount
버텍스의 수를 받는 변수의 주소. 이 파라미터에 NULL를 지정할 수 없다.
lpPosition, lpNormal
버텍스의 위치와 법선 벡터를 받는D3DVECTOR 구조체의 배열. 양쪽 모두 NULL의 경우, 이 메소드는lpdwVertexCount파라미터에 버텍스의 수를 저장 한다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMFace2::SetColor

IDirect3DRMFace2

Direct3DRMFace2 오브젝트의 색을 설정한다.

구문

HRESULT SetColor(
  D3DCOLOR color
  );

파라미터

color
설정하는 색. 적, 초록, 파랑의 색요소 뿐만이 아니라, 알파 요소도 반드시 세트 한다. 그렇게 하지 않으면 오브젝트가 가시가 되지 않는 것이 있다. RGBA_MAKE DirectX 매크로에 의해 이러한 값을 지정할 수가 있다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMFace2::GetColor

IDirect3DRMFace2::SetColorRGB

IDirect3DRMFace2

Direct3DRMFace2 오브젝트의 색을 R, G, B값으로 설정한다.

구문

HRESULT SetColorRGB(
  D3DVALUE red,
  D3DVALUE green,
  D3DVALUE blue
  );

파라미터

red, green, blue
적, 초록, 파랑의 색요소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMFace2::SetMaterial

IDirect3DRMFace2

Direct3DRMFace2 오브젝트에 머트리얼을 세트 한다.

구문

HRESULT SetMaterial(
  LPDIRECT3DRMMATERIAL lpD3DRMMaterial
  );

파라미터

lpD3DRMMaterial
머트리얼의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMFace2::GetMaterial

IDirect3DRMFace2::SetTexture

IDirect3DRMFace2

Direct3DRMFace2 오브젝트에 텍스쳐를 세트 한다.

구문

HRESULT SetTexture(
  LPDIRECT3DRMTEXTURE lpD3DRMTexture
  );

파라미터

lpD3DRMTexture
텍스쳐의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

우선, DirectX Foundation 6에 대해서는, 텍스쳐의 폭과 높이가 2의 거듭제곱일 필요는 없다.

참조

IDirect3DRMFace2::GetTexture

IDirect3DRMFace2::SetTextureCoordinates

IDirect3DRMFace2

Direct3DRMFace2 오브젝트중의 버텍스의 텍스쳐 좌표를 설정한다.

구문

HRESULT SetTextureCoordinates(
  DWORD vertex,
  D3DVALUE u,
  D3DVALUE v
  );

파라미터

vertex
설정하는 버텍스의 인덱스. 예를 들어, 면이 삼각형 때, 버텍스는 0, 1, 2가 된다.
u, v
지정된 버텍스에 할당하는 텍스쳐 좌표.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMFace2::SetTextureTopology

IDirect3DRMFace2

Direct3DRMFace2 오브젝트에 텍스쳐 위상을 설정한다.

구문

HRESULT SetTextureTopology(
  BOOL cylU,
  BOOL cylV
  );

파라미터

cylU, cylV
텍스쳐가 u와 v의 어느 쪽의 차원에서 원기둥(실린더) 위상을 가지고 있는지를 나타낸다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

몇개의 인터페이스로SetTextureTopology메소드가 제공된다. SetTextureTopology메소드와의 관계의 상세, 및cylU,cylV파라미터의 목적에 관한 상세한 것에 대하여는, 「IDirect3DRMeshBuilder3::SetTextureTopology 」를 참조할것.


IDirect3DRMFaceArray

메쉬 위에의면을 그룹화 하려면 ,IDirect3DRMFaceArray인터페이스의 메소드를 이용한다. 면의 개요에 대해서는, 「IDirect3DRMFace2 」를 참조할것.

IDirect3DRMFaceArray인터페이스는, 다음의 메소드를 지원 한다.
GetElement
GetSize

모든 COM 인터페이스와 같이,IDirect3DRMFaceArray인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

Direct3DRMFaceArray 오브젝트는IDirect3DRMMeshBuilder3::GetFaces 메소드의 호출에 의해 취득된다.

IDirect3DRMFaceArray::GetElement

IDirect3DRMFaceArray

Direct3DRMFaceArray 오브젝트로부터 지정된 요소를 취득한다.

구문

HRESULT GetElement(
  DWORD index,
  LPDIRECT3DRMFACE *lplpD3DRMFace
  );

파라미터

index
배열 요소.
lplpD3DRMFace
IDirect3DRMFace 인터페이스에의 포인터.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMFaceArray::GetSize

IDirect3DRMFaceArray

Direct3DRMFaceArray 오브젝트에 포함되는 요소수를 취득한다.

구문

DWORD GetSize( );

반환값

요소수를 돌려준다.


IDirect3DRMFrame3

어플리케이션은,IDirect3DRMFrame3인터페이스의 메소드를 사용해 오브젝트의 참조 프레임이라고 대화한다. 이 개념의 개요에 대해서는, 「프레임」을 참조할것.

IDirect3DRMFrame3인터페이스는,IDirect3DRMFrame2인터페이스의 확장이다. IDirect3DRMFrame3는, 추가 변환 기능, 횡단 옵션세트와 꺼내, 장면 포그(안개:fog) 메소드세트와 취득을 가능하게 하는 메소드를 제공한다.

IDirect3DRMFrame2은, 머트리얼, 경계 박스, 프레임 첨부의 축을 유효하게 하는 추가 메소드를 제공하는 것으로,IDirect3DRMFrame기능을 구축한다. IDirect3DRMFrame2은, 지정의 위치와 방향의 광선과 프레임중의 비주얼의 교점을 계산하기 위한RayPick 메소드도 추가되었다. 게다가IDirect3DRMFrame2에는, 변경된 메소드AddMoveCallback2 가 포함되어 있다.

각 인터페이스에 의해 추가된 모든 메소드의 리스트에 대해서는, 「인터페이스의 변경점」을 참조할것.

IDirect3DRMFrame3인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

축 | GetAxes
 | GetInheritAxes
 | SetAxes
 | SetInheritAxes
배경 | GetSceneBackground
 | GetSceneBackgroundDepth
 | SetSceneBackground
 | SetSceneBackgroundDepth
 | SetSceneBackgroundImage
 | SetSceneBackgroundRGB
경계 박스 | GetBox
 | GetBoxEnable
 | GetHierarchyBox
 | SetBox
 | SetBoxEnable
색 | GetColor
 | SetColor
 | SetColorRGB
포그(안개:fog) | GetSceneFogColor
 | GetSceneFogEnable
 | GetSceneFogMethod
 | GetSceneFogMode
 | GetSceneFogParams
 | SetSceneFogColor
 | SetSceneFogEnable
 | SetSceneFogMethod
 | SetSceneFogMode
 | SetSceneFogParams
계층 | AddChild
 | DeleteChild
 | GetChildren
 | GetParent
 | GetScene
조명 | AddLight
 | DeleteLight
 | GetLights
로드 | Load
머트리얼 | GetMaterial
 | GetMaterialOverride
 | SetMaterial
 | SetMaterialOverride
머트리얼 모드 | GetMaterialMode
 | SetMaterialMode
위치 지정과 운동 | AddMoveCallback
 | AddRotation
 | AddScale
 | AddTranslation
 | DeleteMoveCallback
 | GetOrientation
 | GetPosition
 | GetRotation
 | GetVelocity
 | LookAt
 | Move
 | SetOrientation
 | SetPosition
 | SetQuaternion
 | SetRotation
 | SetVelocity
광선 픽 | RayPick
소트 | GetSortMode
 | GetZbufferMode
 | SetSortMode
 | SetZbufferMode
텍스쳐 | GetTexture
 | SetTexture
변환 | AddTransform
 | GetTransform
 | InverseTransform
 | InverseTransformVectors
 | Transform
 | TransformVectors
횡단 | GetTraversalOptions
 | SetTraversalOptions
비주얼 오브젝트 | AddVisual
 | DeleteVisual
 | GetVisuals

모든 COM 인터페이스와 같이,IDirect3DRMFrame3인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

게다가IDirect3DRMFrame3인터페이스는,IDirect3DRMObject 인터페이스로부터 이하의 메소드를 계승한다.
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMFrame3 오브젝트는,IDirect3DRM3::CreateFrame 메소드를 호출하는 것에 의해 취득된다.


IDirect3DRMFrameArray

어플리케이션은,IDirect3DRMFrameArray인터페이스의 메소드를 사용해 프레임 오브젝트를 정리한다. 이 항은, 이 인터페이스의 메소드의 레퍼런스이다. 개요에 대해서는, 「프레임」을 참조할것.

IDirect3DRMFrameArray인터페이스는, 다음의 메소드를 지원 한다.
GetElement
GetSize

모든 COM 인터페이스와 같이,IDirect3DRMFrameArra인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

IDirect3DRMPickedArray::GetPick ,IDirect3DRMPicked2Array::GetPick , 또는IDirect3DRMFrame3::GetChildren 메소드의 호출에 의해 취득된다.

IDirect3DRMFrameArray::GetElement

IDirect3DRMFrameArray

Direct3DRMFrameArray 오브젝트로부터 지정된 요소를 취득한다.

구문

HRESULT GetElement(
  DWORD index,
  LPDIRECT3DRMFRAME *lplpD3DRMFrame
  );

파라미터

index
배열 요소.
lplpD3DRMFrame
IDirect3DRMFrame 인터페이스에의 포인터를 받는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

QueryInterface를 사용해, 예를 들어, IDirect3DRMFrame3등의 희망하는IDirect3DRMFrame3 의 버젼에의 포인터를 취득할 수가 있다. lplpD3DRMFrame파라미터를 단순하게 다른 버젼에 형태 변환할 수 없다. QueryInterface를 사용해야 한다.

IDirect3DRMFrameArray::GetSize

IDirect3DRMFrameArray

Direct3DRMFrameArray 오브젝트에 포함되어 있는 요소수를 취득한다.

구문

DWORD GetSize( );

반환값

요소수를 돌려준다.


IDirect3DRMInterpolator

인타포레이타는, 액션을 저장 한 후, 중간값을 자동 계산해, 오브젝트에 액션을 적용하는 방법을 제공한다. 인타포레이타를 사용해, 색을 혼합해, 다른 위치간에서 오브젝트를 원활히 이동해, 메쉬를 morphing 해, 게다가 다른 다양한 변환도 실시할 수가 있다.

IDirect3DRMInterpolator인터페이스는,IDirect3DRMAnimation2인터페이스를 포함 하는 집합이며, 애니메이션을 실시할 수가 있는 오브젝트 파라미터의 종류가 많아지고 있다. IDirect3DRMAnimation2인터페이스가 오브젝트의 위치, 사이즈, 및 방향의 애니메이션을 가능하게 하는 한편으로,IDirect3DRMInterpolator는, 색, 메쉬, 텍스쳐, 및 머트리얼의 애니메이션도 사용 가능하게 하고 있다.

개요는, 「IDirect3DRMInterpolator 인터페이스」를 참조할것.

표준적인IUnknown 및IDirect3DRMObject 메소드에 가세해,IDirect3DRMInterpolator는, 이하의 멤버도 포함한다.

오브젝트의 접속 | AttachObject
 | DetachObject
 | GetAttachedObjects
보간의 실행 | GetIndex
 | Interpolate
 | SetIndex

모든 COM 인터페이스와 같이,IDirect3DRMInterpolator인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

게다가IDirect3DRMInterpolator인터페이스는,IDirect3DRMObject 인터페이스로부터 이하의 메소드를 계승한다.
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

IDirect3DRMInterpolator::AttachObject

IDirect3DRMInterpolator

오브젝트를 인타포레이타에 접속한다.

구문

HRESULT AttachObject(
  LPDIRECT3DRMOBJECT lpD3DRMObject
  )

파라미터

lpD3DRMObject
인타포레이타에 접속되는IDirect3DRMObject 오브젝트의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

접속되는 오브젝트는, 다른 인타포레이타에서도, 인타포레이타가xInterpolator형이 되는 타입x의 오브젝트에서도 좋다. 예를 들어, 뷰포트는, ViewportInterpolator에 접속할 수 있다. 인타포레이타의 타입은, 이하대로이다.

  • FrameInterpolator
  • LightInterpolator
  • MaterialInterpolator
  • MeshInterpolator
  • TextureInterpolator
  • ViewportInterpolator

IDirect3DRMInterpolator::DetachObject

IDirect3DRMInterpolator

인타포레이타로부터 오브젝트의 접속을 해제한다.

구문

HRESULT DetachObject(
  LPDIRECT3DRMOBJECT lpD3DRMObject
  )

파라미터

lpD3DRMObject
인타포레이타로부터 접속을 제외하는IDirect3DRMObject 오브젝트의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMInterpolator::GetAttachedObjects

IDirect3DRMInterpolator

인타포레이타에 현재 접속되고 있는 오브젝트의 배열을 취득한다.

구문

HRESULT GetAttachedObjects(
  LPDIRECT3DRMOBJECTARRAY lpD3DRMObjectArray
  )

파라미터

lpD3DRMObjectArray
현재 인타포레이타에 부가되고 있는IDirect3DRMObject 오브젝트를 포함한IDirect3DRMObjectArray 오브젝트의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMInterpolator::GetIndex

IDirect3DRMInterpolator

인타포레이타의 현재의 내부 인덱스(시간)를 취득한다.

구문

D3DVALUE GetIndex( )

반환값

인타포레이타의 현재의 내부 인덱스를 포함한D3DVALUE 를 돌려준다.

주의

인타포레이타에 저장 되고 있는 각 키는, 인덱스값을 가진다. 키를(메소드를 사용해) 기록 하면 와, 키에는, 현재의 인타포레이타의 인덱스값으로 스탬프가 밀린다. 키의 인덱스값은, 스탬프를 밀린 후, 바뀔 것은 없다.

IDirect3DRMInterpolator::Interpolate

IDirect3DRMInterpolator

인타포레이타에 저장 되고 있는 키간을 보간 해, 일련의 액션을 생성한다. 그 후, 액션은, 지정의 오브젝트에 적용된다. 오브젝트의 지정이 없으면, 액션은, 현재 접속되고 있는 오브젝트에 적용된다.

구문

HRESULT Interpolate(
  D3DVALUE d3dVal,
  LPDIRECT3DRMOBJECT lpD3DRMObject,
  D3DRMINTERPOLATIONOPTIONS d3drmInterpFlags
  )

파라미터

d3dVal
인타포레이타의 현재의 내부 인덱스를 포함한 D3DVALUE.
lpD3DRMObject
IDirect3DRMObject 오브젝트의 주소. 이 오브젝트는, 인타포레이타에 저장 떠날 수 있어 모든 프로퍼티에 대한 보간값을 할당하는 오브젝트를 나타낸다. 이 포인터는 NULL에서도 좋다. 그 경우에는, 모든 접속되고 있는 오브젝트의 프로퍼티값에는, 보간값이 세트 된다.
d3drmInterpFlags
실행하는 보간의 종류를 제어하는 1개또는 복수의 플래그. 가능한 값은, 이하대로이다.
D3DRMINTERPOLATION_CLOSED
D3DRMINTERPOLATION_LINEAR
D3DRMINTERPOLATION_NEAREST
D3DRMINTERPOLATION_OPEN
D3DRMINTERPOLATION_SLERPNORMALS
D3DRMINTERPOLATION_SPLINE
D3DRMINTERPOLATION_VERTEXCOLOR
이러한 옵션의 기술은, 「보간 옵션」을 참조할것.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMInterpolator::SetIndex

IDirect3DRMInterpolator

인타포레이타의 내부 인덱스(시간)로 지정의 값을 세트 한다. 다른 인타포레이타가 그 인타포레이타에 접속되고 있으면, 이 메소드는, 재귀적으로 그러한 인덱스를 같은 값에 동기 시킨다.

구문

HRESULT SetIndex(
  D3DVALUE d3dVal
  )

파라미터

d3dVal
인타포레이타의 내부 인덱스에 대해서 세트 되는 시간.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

인타포레이타에 저장 되고 있는 각 키는, 인덱스값을 가진다. 키를(메소드를 사용해) 기록 하면 와, 키에는, 현재의 인타포레이타의 인덱스값으로 스탬프가 밀린다. 키의 인덱스값은, 스탬프를 밀린 후, 바뀔 것은 없다.


IDirect3DRMLight

어플리케이션은, 조명과 서로 교환하기 위해서IDirect3DRMLight인터페이스의 메소드를 사용한다. 이 섹션은,IDirect3DRMLight인터페이스 메소드의 레퍼런스이다. 개념에 대해서는, 「조명」을 참조할것.

IDirect3DRMLight인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.
감쇠 | GetConstantAttenuation
 | GetLinearAttenuation
 | GetQuadraticAttenuation
 | SetConstantAttenuation
 | SetLinearAttenuation
 | SetQuadraticAttenuation
색 | GetColor
 | SetColor
 | SetColorRGB
유효 프레임 | GetEnableFrame
 | SetEnableFrame
조명 타입 | GetType
 | SetType
범위 | GetRange
 | SetRange
스포트 조명 옵션 | GetPenumbra
 | GetUmbra
 | SetPenumbra
 | SetUmbra

모든 COM 인터페이스와 같이,IDirect3DRMLight인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

게다가IDirect3DRMLight인터페이스는,IDirect3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMLight 오브젝트는,IDirect3DRM3::CreateLight 및IDirect3DRM3::CreateLightRGB 메소드의 호출에 의해 취득된다.

IDirect3DRMLight::GetColor

IDirect3DRMLight

현재의 Direct3DRMLight 오브젝트의 색을 취득한다.

구문

D3DCOLOR GetColor( );

반환값

색을 돌려준다.

참조

IDirect3DRMLight::SetColor

IDirect3DRMLight::GetConstantAttenuation

IDirect3DRMLight

Direct3DRMLight 오브젝트의 감쇠 정수를 취득한다.

구문

D3DVALUE GetConstantAttenuation( );

반환값

감쇠 정수를 돌려준다.

주의

위치를 가지는(무한하게 멀지 않다) 조명에는 감쇠 정수가 있어, 광원으로부터의 거리에 근거해 조명의 감쇠를 계산할 수 있다.

사용되는 조명의 감쇠 공식은, D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR 플래그가 세트 되고 있는지 어떤지에 의존한다. 이 플래그는,IDirect3DRMDevice3::SetRenderMode 중에 세트 되고 있다.

D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR 플래그가 세트 되고 있는 경우, 다음의 공식이 조명의 감쇠에 사용된다.

거리 정규화의 공식은 다음과 같다.

normalized_distance = (distance_from_light - light_range) /light_range

light_range의 디폴트값은, 256 모델 공간 단위이다.

전감쇠 계수의 공식은 다음과 같다.

constant_attenuation_factor + normalized_distance * linear_attenuation_factor + (normalized_distance**2) * quadratic_attenuation_factor

D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR 플래그가 세트되어 있지 않은 경우, 다음의 공식이 조명의 감쇠에 사용된다.

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

전감쇠 계수는 1보다 커지지 않는다.

감쇠 계수가 지정되지 않으면 디폴트값은, 감쇠 정수에 대해서는 1.0, 선형 감쇠 계수에 대해서는 0.0, 2차 감쇠 계수에 대해서는 0.0이다.

참조

IDirect3DRMLight::SetConstantAttenuation

IDirect3DRMLight::GetEnableFrame

IDirect3DRMLight

조명을 설정하는데유효 프레임을 취득한다.

구문

HRESULT GetEnableFrame(
  LPDIRECT3DRMFRAME  *lplpEnableFrame
  );

파라미터

lplpEnableFrame
현재의 Direct3DRMFrame 오브젝트의 유효 프레임을 받는 포인터에의 포인터.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMLight::SetEnableFrame

IDirect3DRMLight::GetLinearAttenuation

IDirect3DRMLight

조명의 1차 감쇠 계수를 취득한다.

구문

D3DVALUE GetLinearAttenuation( );

반환값

1차 감쇠 계수를 돌려준다.

주의

위치를 가지는(무한하게 멀지 않다) 조명에는 감쇠 정수가 있어, 광원으로부터의 거리에 근거해 조명의 감쇠를 계산할 수 있다.

사용되는 조명의 감쇠 공식은, D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR 플래그가 세트 되고 있는지 어떤지에 의존한다. 이 플래그는,IDirect3DRMDevice3::SetRenderMode 중에 세트 되고 있다.

D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR 플래그가 세트 되고 있는 경우, 다음의 공식이 조명의 감쇠에 사용된다.

거리 정규화의 공식은 다음과 같다.

normalized_distance = (distance_from_light - light_range) /light_range

light_range의 디폴트값은, 256 모델 공간 단위이다.

전감쇠 계수의 공식은 다음과 같다.

constant_attenuation_factor + normalized_distance * linear_attenuation_factor + (normalized_distance**2) * quadratic_attenuation_factor

D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR 플래그가 세트되어 있지 않은 경우, 다음의 공식이 조명의 감쇠에 사용된다.

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

전감쇠 계수는 1보다 커지지 않는다.

감쇠 계수가 지정되지 않으면 디폴트값은, 감쇠 정수에 대해서는 1.0, 선형 감쇠 계수에 대해서는 0.0, 2차 감쇠 계수에 대해서는 0.0이다.

참조

IDirect3DRMLight::SetLinearAttenuation

IDirect3DRMLight::GetPenumbra

IDirect3DRMLight

spotlight의암영부의 각도를 취득한다.

구문

D3DVALUE GetPenumbra( );

반환값

암영부의 값을 돌려준다.

주의

자세한 것은, 「조명」의 「spotlight」를 참조할것.

참조

IDirect3DRMLight::SetPenumbra

IDirect3DRMLight::GetQuadraticAttenuation

IDirect3DRMLight

조명의 2차 감쇠 계수를 취득한다.

구문

D3DVALUE GetQuadraticAttenuation( );

반환값

2차 감쇠 계수를 돌려준다.

주의

위치를 가지는(무한하게 멀지 않다) 조명에는 감쇠 정수가 있어, 조명으로부터의 거리에 근거해 조명의 감쇠를 계산할 수 있다.

사용되는 조명의 감쇠 공식은, D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR 플래그가 세트 되고 있는지 어떤지에 의존한다. 이 플래그는,IDirect3DRMDevice3::SetRenderMode 중에 세트 되고 있다.

D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR 플래그가 세트 되고 있는 경우, 다음의 공식이 조명의 감쇠에 사용된다.

거리 정규화의 공식은 다음과 같다.

normalized_distance = (distance_from_light - light_range) /light_range

light_range의 디폴트값은, 256 모델 공간 단위이다.

전감쇠 계수의 공식은 다음과 같다.

constant_attenuation_factor + normalized_distance * linear_attenuation_factor + (normalized_distance**2) * quadratic_attenuation_factor

D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR 플래그가 세트되어 있지 않은 경우, 다음의 공식이 조명의 감쇠에 사용된다.

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

전감쇠 계수는 1보다 커지지 않는다.

감쇠 계수가 지정되지 않으면 디폴트값은, 감쇠 정수에 대해서는 1.0, 선형 감쇠 계수에 대해서는 0.0, 2차 감쇠 계수에 대해서는 0.0이다.

참조

IDirect3DRMLight::SetQuadraticAttenuation

IDirect3DRMLight::GetRange

IDirect3DRMLight

현재의 Direct3DRMLight 오브젝트의 범위를 취득한다.

구문

D3DVALUE GetRange( );

반환값

범위를 나타내는 값을 돌려준다.

참조

IDirect3DRMLight::SetRange

IDirect3DRMLight::GetType

IDirect3DRMLight

지정된 조명의 타입을 취득한다.

구문

D3DRMLIGHTTYPE GetType( );

반환값

D3DRMLIGHTTYPE 열거형의 멤버의 하나를 돌려준다.

참조

IDirect3DRMLight::SetType

IDirect3DRMLight::GetUmbra

IDirect3DRMLight

Direct3DRMLight 오브젝트의명부의 각도를 취득한다. 디폴트는, 0.4 라디안이다.

구문

D3DVALUE GetUmbra( );

반환값

명부의 각도를 돌려준다.

주의

상세한 것에 대하여는, 「조명」의 「spotlight」를 참조할것.

참조

IDirect3DRMLight::SetUmbra

IDirect3DRMLight::SetColor

IDirect3DRMLight

지정된 조명의 색을 설정한다.

구문

HRESULT SetColor(
  D3DCOLOR rcColor
  );

파라미터

rcColor
조명의 새로운 색. 적, 초록, 파랑의 색요소 뿐만이 아니라, 알파 요소도 반드시 세트 한다. 그렇게 하지 않으면 오브젝트가 가시가 되지 않는 것이 있다. RGBA_MAKE DirectX 매크로에 의해 이러한 값을 지정할 수가 있다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, Direct3DRMLightInterpolator 오브젝트에 RGB 컬러 키를 추가하기 위해서도 사용한다.

참조

IDirect3DRMLight::GetColor

IDirect3DRMLight::SetColorRGB

IDirect3DRMLight

지정된 조명의 색을 R, B, G 각각의 값으로 설정한다.

구문

HRESULT SetColorRGB(
  D3DVALUE rvRed,
  D3DVALUE rvGreen,
  D3DVALUE rvBlue
  );

파라미터

rvRed, rvGreen, rvBlue
조명의 새로운 색.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, Direct3DRMLightInterpolator 오브젝트에 RGB 컬러 키를 추가하기 위해서도 사용한다.

IDirect3DRMLight::SetConstantAttenuation

IDirect3DRMLight

조명의 감쇠 계수를 설정한다.

구문

HRESULT SetConstantAttenuation(
  D3DVALUE rvAtt
  );

파라미터

rvAtt
새로운 감쇠 정수.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

위치를 가지는(무한하게 멀지 않다) 조명에는 감쇠 정수가 있어, 조명으로부터의 거리에 근거해 조명의 감쇠를 계산할 수 있다.

사용되는 조명의 감쇠 공식은, D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR 플래그가 세트 되고 있는지 어떤지에 의존한다. 이 플래그는,IDirect3DRMDevice3::SetRenderMode 중에 세트 되고 있다.

D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR 플래그가 세트 되고 있는 경우, 다음의 공식이 조명의 감쇠에 사용된다.

거리 정규화의 공식은 다음과 같다.

normalized_distance = (distance_from_light - light_range) /light_range

light_range의 디폴트값은, 256 모델 공간 단위이다.

전감쇠 계수의 공식은 다음과 같다.

constant_attenuation_factor + normalized_distance * linear_attenuation_factor + (normalized_distance**2) * quadratic_attenuation_factor

D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR 플래그가 세트되어 있지 않은 경우, 다음의 공식이 조명의 감쇠에 사용된다.

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

전감쇠 계수는 1보다 커지지 않는다.

감쇠 계수가 지정되지 않으면 디폴트값은, 감쇠 정수에 대해서는 1.0, 선형 감쇠 계수에 대해서는 0.0, 2차 감쇠 계수에 대해서는 0.0이다.

이 메소드는, Direct3DRMLightInterpolator 오브젝트에 감쇠 정수 키를 추가하기 위해서도 사용한다.

참조

IDirect3DRMLight::GetConstantAttenuation

IDirect3DRMLight::SetEnableFrame

IDirect3DRMLight

조명의유효 프레임을 설정한다.

구문

HRESULT SetEnableFrame(
  LPDIRECT3DRMFRAME lpEnableFrame
  );

파라미터

lpEnableFrame
조명의 유효 프레임에의 포인터. 이 프레임에는 친프레임과 같은 조명이 된다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMLight::GetEnableFrame

IDirect3DRMLight::SetLinearAttenuation

IDirect3DRMLight

조명의 1차 감쇠 계수를 설정한다.

구문

HRESULT SetLinearAttenuation(
  D3DVALUE rvAtt
  );

파라미터

rvAtt
새로운 선형 감쇠 계수.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

위치를 가지는(무한하게 멀지 않다) 조명에는 감쇠 정수가 있어, 조명으로부터의 거리에 근거해 조명의 감쇠를 계산할 수 있다.

사용되는 조명의 감쇠 공식은, D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR 플래그가 세트 되고 있는지 어떤지에 의존한다. 이 플래그는,IDirect3DRMDevice3::SetRenderMode 중에 세트 되고 있다.

D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR 플래그가 세트 되고 있는 경우, 다음의 공식이 조명의 감쇠에 사용된다.

거리 정규화의 공식은 다음과 같다.

normalized_distance = (distance_from_light - light_range) /light_range

light_range의 디폴트값은, 256 모델 공간 단위이다.

전감쇠 계수의 공식은 다음과 같다.

constant_attenuation_factor + normalized_distance * linear_attenuation_factor + (normalized_distance**2) * quadratic_attenuation_factor

D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR 플래그가 세트되어 있지 않은 경우, 다음의 공식이 조명의 감쇠에 사용된다.

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

전감쇠 계수는 1보다 커지지 않는다.

감쇠 계수가 지정되지 않으면 디폴트값은, 감쇠 정수에 대해서는 1.0, 선형 감쇠 계수에 대해서는 0.0, 2차 감쇠 계수에 대해서는 0.0이다.

이 메소드는, Direct3DRMLightInterpolator 오브젝트에 선형 감쇠 정수 키를 추가하기 위해서도 사용한다.

참조

IDirect3DRMLight::GetLinearAttenuation

IDirect3DRMLight::SetPenumbra

IDirect3DRMLight

원추의암영부의 각도를 세트 한다.

구문

HRESULT SetPenumbra(
  D3DVALUE rvAngle
  );

파라미터

rvAngle
라디안 단위의 새로운 암영부의 각도. 이 각도는 암부의 각도보다 큰지, 동일하지 않으면 안 된다. 암영부의 각도를 명부의 각도보다 작게 설정했을 경우, 암영부는 명부와 같은 각도가 된다. 디폴트값은 0.5 라디안이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, Direct3DRMLightInterpolator 오브젝트에 그림자 각도 키를 추가하기 위해서도 사용한다.

상세한 것에 대하여는, 「조명」의 「spotlight」를 참조할것.

참조

IDirect3DRMLight::GetPenumbra

IDirect3DRMLight::SetQuadraticAttenuation

IDirect3DRMLight

조명의 2차 감쇠 계수를 설정한다.

구문

HRESULT SetQuadraticAttenuation(
  D3DVALUE rvAtt
  );

파라미터

rvAtt
새로운 2차 감쇠 계수.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

위치를 가지는(무한하게 멀지 않다) 조명에는 감쇠 정수가 있어, 조명으로부터의 거리에 근거해 조명의 감쇠를 계산할 수 있다.

사용되는 조명의 감쇠 공식은, D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR 플래그가 세트 되고 있는지 어떤지에 의존한다. 이 플래그는,IDirect3DRMDevice3::SetRenderMode 중에 세트 되고 있다.

D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR 플래그가 세트 되고 있는 경우, 다음의 공식이 조명의 감쇠에 사용된다.

거리 정규화의 공식은 다음과 같다.

normalized_distance = (distance_from_light - light_range) /light_range

light_range의 디폴트값은, 256 모델 공간 단위이다.

전감쇠 계수의 공식은 다음과 같다.

constant_attenuation_factor + normalized_distance * linear_attenuation_factor + (normalized_distance**2) * quadratic_attenuation_factor

D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR 플래그가 세트되어 있지 않은 경우, 다음의 공식이 조명의 감쇠에 사용된다.

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

전감쇠 계수는 1보다 커지지 않는다.

감쇠 계수가 지정되지 않으면 디폴트값은, 감쇠 정수에 대해서는 1.0, 선형 감쇠 계수에 대해서는 0.0, 2차 감쇠 계수에 대해서는 0.0이다.

이 메소드는, Direct3DRMLightInterpolator 오브젝트에 2차 감쇠 키를 추가하기 위해서도 사용한다.

참조

IDirect3DRMLight::GetQuadraticAttenuation

IDirect3DRMLight::SetRange

IDirect3DRMLight

spotlight의 범위를 설정한다. 이 조명은, 범위내에 있는 오브젝트에 한정해 영향을 준다.

구문

HRESULT SetRange(
  D3DVALUE rvRange
  );

파라미터

rvRange
새로운 범위. 디폴트값은, 256 모델 공간 단위이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

범위 프로퍼티는, spotlight만의 것이다. 이 메소드는, Direct3DRMLightInterpolator 오브젝트에 범위 키를 추가하기 위해서도 사용한다.

참조

IDirect3DRMLight::GetRange

IDirect3DRMLight::SetType

IDirect3DRMLight

조명의 타입을 변경한다.

구문

HRESULT SetType(
  D3DRMLIGHTTYPE d3drmtType
  );

파라미터

d3drmtType
새로운 조명 타입을D3DRMLIGHTTYPE 열거형의 멤버의 하나로 지정한다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMLight::GetType

IDirect3DRMLight::SetUmbra

IDirect3DRMLight

원추의명부의 각도를 설정한다.

구문

HRESULT SetUmbra(
  D3DVALUE rvAngle
  );

파라미터

rvAngle
라디안 단위의 새로운 명부의 각도. 이 각도는, 암영부의 각도보다 작은지, 동일하지 않으면 안 된다. 명부의 각도를 암영부의 각도보다 크게 설정했을 경우, 명부는 암영부와 같은 각도가 된다. 디폴트값은 0.4 라디안이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, Direct3DRMLightInterpolator 오브젝트에 그림자 각도 키를 추가하기 위해서도 사용한다.

상세한 것에 대하여는, 「조명」의 「spotlight」를 참조할것.

참조

IDirect3DRMLight::GetUmbra


IDirect3DRMLightArray

어플리케이션은, 조명 오브젝트를 그룹화 하기 위해서IDirect3DRMLightArray인터페이스의 메소드를 이용한다. 이 섹션은, IDirect3DRMLightArray 인터페이스 메소드의 레퍼런스이다. 개념에 대한 개요는, 「조명」을 참조할것.

IDirect3DRMLightArray인터페이스는, 다음의 메소드를 지원 한다.
GetElement
GetSize

모든 COM 인터페이스와 같이,IDirect3DRMLightArray인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

Direct3DRMLightArray 오브젝트는,IDirect3DRMFrame3::GetLights 메소드의 호출에 의해 취득된다.

IDirect3DRMLightArray::GetElement

IDirect3DRMLightArray

Direct3DRMLightArray 오브젝트로부터 지정된 요소를 취득한다.

구문

HRESULT GetElement(
  DWORD index,
  LPDIRECT3DRMLIGHT  *lplpD3DRMLight
  );

파라미터

index
배열 요소.
lplpD3DRMLight
IDirect3DRMLight 인터페이스에의 포인터를 받는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMLightArray::GetSize

IDirect3DRMLightArray

Direct3DRMLightArray 오브젝트에 포함되어 있는 요소수를 취득한다.

구문

DWORD GetSize( );

반환값

요소수를 돌려준다.


IDirect3DRMMaterial2

어플리케이션은, 머트리얼 오브젝트와 서로 교환하기 위해서IDirect3DRMMaterial2인터페이스의 메소드를 사용한다.

머트리얼에서는, 표면이 어떻게 빛을 반사하는지를 정의한다. 머트리얼에는,방사 프로퍼티(빛을 방사할지 어떨지)와반사 프로퍼티의 2개의 요소가 있어, 그 휘도(Luminance)는강도설정에 의해 정해진다. 지수의 값은 반사하는 하이라이트의 날카로움을 결정해 5의 값은 금속의 외관을 주어보다 큰 값은 보다 플라스틱적인 외관을 준다.

어플리케이션은,GetEmissive 와SetEmissive 메소드를 사용해 머트리얼의 방사를,GetSpecular 와SetSpecular 메소드를 사용해 반사 요소를,GetPower 와SetPower 메소드를 사용해 지수를 제어할 수가 있다.

Microsoft DirectX version 6.0은,IDirect3DRMMaterial2인터페이스를 도입하고 있다. IDirect3DRMMaterial2는, 머트리얼 프로퍼티에 대하는 것보다 세련된 제어를 가능하게 하는GetAmbient 와SetAmbient 메소드를 추가하는 것으로, 그것이 치환하는 구의IDirect3DRMMaterial인터페이스를 확장한다. IDirect3DRMMaterial에 대해서는,앰비언트컬러를 수정하지 못하고, 항상 면의 색과 동일해진다. IDirect3DRMMaterial2오브젝트는,SetAmbient가 불려 갈 때까지, 오브젝트의 면의 색을 앰비언트 컬러로서 사용한다. Direct3D 보관 유지 모드 인터페이스의 이력에 대해서는, 「인터페이스의 변경점」을 참조할것.

IDirect3DRMMaterial2인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.
앰비언트 | GetAmbient
 | SetAmbient
방사 | GetEmissive
 | SetEmissive
반사 지수의 | GetPower
지수 | SetPower
반사 | GetSpecular
 | SetSpecular

모든 COM 인터페이스와 같이,IDirect3DRMMaterial2인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

게다가IDirect3DRMMaterial2인터페이스는,IDirect3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMMaterial 오브젝트는,IDirect3DRM3::CreateMaterial 메소드의 사용에 의해 취득된다.

IDirect3DRMMaterial2::GetAmbient

IDirect3DRMMaterial2

머트리얼의 현재의 앰비언트값을 취득한다.

구문

HRESULT GetAmbient(
LPD3DVALUE lpdvRed,
LPD3DVALUE lpdvGreen,
LPD3DVALUE lpdvBlue);

파라미터

lpdvRed
앰비언트 컬러의 빨강 요소가 세트 된다.
lpdvGreen
앰비언트 컬러의 초록 요소가 세트 된다.
lpdvBlue
앰비언트 컬러의 파랑 요소가 세트 된다.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMMaterial2::GetEmissive

IDirect3DRMMaterial2

머트리얼의방사 프로퍼티의 설정을 취득한다. 이 프로퍼티의 설정은, 색과 오브젝트가 발산하는 빛의 지수를 나타낸다.

구문

HRESULT GetEmissive(
  D3DVALUE *lpr,
  D3DVALUE *lpg,
  D3DVALUE *lpb
  );

파라미터

lpr, lpg, lpb
메소드가 제어를 돌려줄 때, 방사의 적, 초록, 파랑의 색요소를 받는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMMaterial2::SetEmissive

IDirect3DRMMaterial2::GetPower

IDirect3DRMMaterial2

지정된 머트리얼에서의 반사 지수의강도를 취득한다.

구문

D3DVALUE GetPower( );

반환값

반사 지수의 지수를 나타내는 값을 돌려준다.

참조

IDirect3DRMMaterial2::SetPower

IDirect3DRMMaterial2::GetSpecular

IDirect3DRMMaterial2

머트리얼의 반사 하이라이트의 색을 취득한다.

구문

HRESULT GetSpecular(
  D3DVALUE *lpr,
  D3DVALUE *lpg,
  D3DVALUE *lpb
  );

파라미터

lpr, lpg, lpb
메소드가 제어를 돌려줄 때, 반사 하이라이트의 적, 초록, 파랑의 색요소를 받는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMMaterial2::SetSpecular

IDirect3DRMMaterial2::SetAmbient

IDirect3DRMMaterial2

머트리얼의 앰비언트값을 설정한다. 디폴트는 확산색이다. 확산색이란, 표면의 난반사하는(윤기없다) 색이다.

구문

HRESULT SetAmbient(
    D3DVALUE dvRed,
    D3DVALUE dvGreen,
    D3DVALUE dvBlue);

파라미터

dvRed
앰비언트 컬러의 빨강 요소.
dvGreen
앰비언트 컬러의 초록 요소.
dvBlue
앰비언트 컬러의 파랑 요소.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMMaterial2::SetEmissive

IDirect3DRMMaterial2

머트리얼의방사 프로퍼티를 설정한다.

구문

HRESULT SetEmissive(
  D3DVALUE r,
  D3DVALUE g,
  D3DVALUE b
  );

파라미터

r, g, b
방사의 색의 적, 초록, 파랑 요소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, Direct3DRMMaterialInterpolator 오브젝트에 방사 프로퍼티 키를 추가하기 위해서도 사용한다.

참조

IDirect3DRMMaterial2::GetEmissive

IDirect3DRMMaterial2::SetPower

IDirect3DRMMaterial2

머트리얼의 반사 지수의강도를 설정한다.

구문

HRESULT SetPower(
  D3DVALUE rvPower
  );

파라미터

rvPower
새로운 반사 지수.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, Direct3DRMMaterialInterpolator 오브젝트에 반사 지수 키를 추가하기 위해서도 사용한다.

참조

IDirect3DRMMaterial2::GetPower

IDirect3DRMMaterial2::SetSpecular

IDirect3DRMMaterial2

머트리얼의 반사 하이라이트의 색을 설정한다.

구문

HRESULT SetSpecular(
  D3DVALUE r,
  D3DVALUE g,
  D3DVALUE b
  );

파라미터

r, g, b
반사 하이라이트의 색의 적, 초록, 파랑의 각 요소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, Direct3DRMMaterialInterpolator 오브젝트에 반사 컬러 키를 추가하기 위해서도 사용한다.

참조

IDirect3DRMMaterial2::GetSpecular


IDirect3DRMMesh

어플리케이션은,IDirect3DRMMesh인터페이스의 메소드를 사용해, 메쉬의 그룹이라고 회화한다. 메쉬는, 다각형면세트로부터 구성되는 비주얼 오브젝트이다. 메쉬는, 버텍스세트와 면세트 (면은 메쉬의 버텍스와 법선에 의해 정의된다)를 정의한다. 몇개의 면이 사용하고 있는 버텍스 또는 법선을 변경 하면, 그것을 공유하는 모든 면의 외관이 바뀐다.

메쉬의 버텍스는 메쉬중의 면의 위치를 정의해, 이것들을 사용해 텍스쳐 맵내의 2 D좌표를 정의할 수도 있다.

IDirect3DRMMesh와IDirect3DRMMeshBuilder3 를 사용해, 보관 유지 모드로 메쉬를 조작할 수가 있다.

어플리케이션으로, 같은 특성 (머트리얼, 텍스쳐등)을 몇개의 버텍스 또는 면에 할당할 필요가 있는 경우,IDirect3DRMMesh인터페이스를 사용해, 이것들을 1개의 그룹에 정리할 수가 있다. 어플리케이션이 2개가 다른 그룹간에 버텍스를 공유할 필요가 있는 경우 (예를 들어, 메쉬중의 인접하는 면의 색이 다른 경우), 버텍스는 양쪽 모두의 그룹에 중복 하고 있지 않으면 안 된다. IDirect3DRMMesh::AddGroup 메소드는, 그룹 식별자를 면의 집합에 할당한다. 이 식별자를 사용해, 후속의 호출로 그룹을 참조한다.

IDirect3DRMMeshBuilder3와IDirect3DRMMesh인터페이스에 의해, 어플리케이션은 3개 이상의 측면을 가지는 면을 생성 할 수가 있다. 예를 들어, 어플리케이션이 렌더링 하고 있는 하드웨어에 64 K의 제한이 있어, 메쉬가 그 사이즈를 넘고 있는 경우, 이것들은 메쉬를 자동적으로 복수의 버퍼에 분할한다. 이러한 기능은, Direct3DRMMesh와 Direct3DRMMeshBuilder3 API를 Direct3D API로부터 떼어내 세트 한다.

IDirect3DRMMesh::SetGroupColor ,SetGroupColorRGB ,SetGroupTexture 및SetGroupMaterial 메소드를 사용해, 메쉬의 각면 또는 메쉬의 모든 면에 대해서 동시에, 개별의 색, 텍스쳐, 머트리얼 프로퍼티를 정의할 수가 있다.

렌더링 하는 메쉬에 대해서는,IDirect3DRMFrame3::AddVisual 메소드를 사용해, 최초로 프레임에 추가해야 한다. 단일의 메쉬를 복수의 프레임에 추가해, 그 메쉬의 복수의 인스턴스를 생성 할 수가 있다.

IDirect3DRMMesh::SetGroupQuality 메소드에 대한 호출로 지정된 것처럼, 어플리케이션은, 플랫, 굿 로, 폰 쉐이드 모드를 사용할 수가 있다 (그러나, 폰 쉐이딩은 아직 이용 가능하지 않다). 이 메소드는,D3DRMRENDERQUALITY 열거형의 값을 사용한다. 쉐이딩 모드의 상세한 것에 대하여는, 「다각형」을 참조할것.

IDirect3DRMMesh인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.
색 | GetGroupColor
 | SetGroupColor
 | SetGroupColorRGB
생성과 | AddGroup
정보 | GetBox
 | GetGroup
 | GetGroupCount
머트리얼 | GetGroupMaterial
 | SetGroupMaterial
그 외 | Scale
 | Translate
렌더링 퀄리티 | GetGroupQuality
 | SetGroupQuality
텍스쳐 맵핑 | GetGroupMapping
 | SetGroupMapping
텍스쳐 | GetGroupTexture
 | SetGroupTexture
버텍스의 위치 | GetVertices
 | SetVertices

모든 COM 인터페이스와 같이,IDirect3DRMMesh인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

게다가IDirect3DRMMesh인터페이스는IDirect3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMMesh 오브젝트는,IDirect3DRM3::CreateMesh 메소드의 사용에 의해 취득된다.

IDirect3DRMMesh::AddGroup

IDirect3DRMMesh

면의 모임을 그룹화 해, 그 그룹의 식별자를 취득한다. 메쉬에 최초로 추가되는 그룹의 인덱스는, 항상 0이다. 이후의 그룹의 인덱스는, 각각 1씩 증가한다.

구문

HRESULT AddGroup(
  unsigned vCount,
  unsigned fCount,
  unsigned vPerFace,
  unsigned *fData,
  D3DRMGROUPINDEX *returnId
  );

파라미터

vCount, fCount
그룹에 포함되는 버텍스와 면의 수.
vPerFace
모든 면이 같은 수의 버텍스를 가지는 경우, 면 당의 버텍스의 수. 그룹중의 면이 가지는 버텍스의 수가 일정이 아닐 때는, 이 파라미터에 0을 지정하지 않으면 안 된다.
fData
면데이터의 주소. vPerFace파라미터에 값이 설정되어 있는 경우, 이 데이터는 단지, 그룹의 버텍스 배열에의 인덱스 리스트이다. vPerFace가 0 때는, 버텍스 인덱스보다, 그 면의 버텍스의 수를 나타내는 정수값을 우선하지 않으면 안 된다. 예를 들어,vPerFace가 0으로, 그룹을 구성하는 면이 삼각형과 사각형인 경우, 데이터는 다음과 같이 된다. [ 3, 인덱스, 인덱스, 인덱스, 4, 인덱스, 인덱스, 인덱스, 인덱스, 3, 인덱스, 인덱스, 인덱스, ...]
returnId
메소드가 제어를 돌려줄 때, 그룹의 식별자를 받는 변수에의 포인터.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

새롭게 추가된 그룹에는, 이하의 디폴트의 프로퍼티가 주어진다.

  • 흰색.
  • 텍스쳐 없음.
  • 반사 없음.
  • 버텍스 배열의 각 버텍스의 위치, 법선, 색은 0.

버텍스의 위치를 설정하려면 ,IDirect3DRMMesh::SetVertices 메소드를 사용한다.

IDirect3DRMMesh::GetBox

IDirect3DRMMesh

Direct3DRMMesh 오브젝트를 포함하는 (분)편 형태 범위를 취득한다. 방형 범위는, 각각의 차원의모델 좌표의 최소 값과 최대치를 나타낸다.

구문

HRESULT GetBox(
  D3DRMBOX  *lpD3DRMBox
  );

파라미터

lpD3DRMBox
경계 박스 좌표를 받는D3DRMBOX 구조체.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMMesh::GetGroup

IDirect3DRMMesh

지정된 그룹에 관련지을 수 있고 있는 데이터를 취득한다.

구문

HRESULT GetGroup(
  D3DRMGROUPINDEX id,
  unsigned *vCount,
  unsigned *fCount,
  unsigned *vPerFace,
  DWORD *fDataSize,
  unsigned *fData
  );

파라미터

id
그룹의 식별자. 이 식별자는IDirect3DRMMesh::AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.
vCount, fCount
메소드가 제어를 돌려줄 때, 그룹의 버텍스의 수와 면의 수를 받는 변수의 주소. 이러한 파라미터에는 NULL를 지정할 수가 있다.
vPerFace
메소드가 제어를 돌려줄 때, 면 당의 버텍스의 수를 받는 변수의 주소. 이러한 파라미터에는 NULL를 지정할 수가 있다.
fDataSize
fData파라미터가 가리키는 버퍼안의, 부호 없음 요소의 수를 나타내는 변수의 주소. 이 파라미터에 NULL를 지정할 수 없다.
fData
메소드가 제어를 돌려줄 때, 그룹의 면데이터를 저장 하는 버퍼의 주소. 이 데이터의 형식은,IDirect3DRMMesh::AddGroup 메소드의 호출로 지정한 것 것과 같다. 이 파라미터가 NULL 때, 필요한 버퍼의 사이즈가fDataSize파라미터에 돌려주어진다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMMesh::GetGroupColor

IDirect3DRMMesh

그룹의 색을 취득한다.

구문

D3DCOLOR GetGroupColor(
  D3DRMGROUPINDEX id
  );

파라미터

id
그룹의 식별자. 이 식별자는IDirect3DRMMesh::AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.

반환값

성공하면, 색을 나타내는 D3DCOLOR값을 돌려준다. 실패하면 0을 돌려준다.

참조

IDirect3DRMMesh::SetGroupColor , IDirect3DRMMesh::SetGroupColorRGB

IDirect3DRMMesh::GetGroupCount

IDirect3DRMMesh

지정된 Direct3DRMMesh 오브젝트중의 그룹의 수를 취득한다.

구문

unsigned GetGroupCount( );

반환값

성공하면 그룹의 수를 돌려준다. 실패하면 0을 돌려준다.

IDirect3DRMMesh::GetGroupMapping

IDirect3DRMMesh

Direct3DRMMesh 오브젝트중의 그룹에 대해서, 어떻게 텍스쳐가 맵 되는지를 취득한다.

구문

D3DRMMAPPING GetGroupMapping(
  D3DRMGROUPINDEX id
  );

파라미터

id
그룹의 식별자. 이 식별자는IDirect3DRMMesh::AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.

반환값

성공하면, 그룹에의 텍스쳐의 맵 방법을 나타내는D3DRMMAPPING 값의 하나를 돌려준다. 실패하면 0을 돌려준다.

참조

IDirect3DRMMesh::SetGroupMapping

IDirect3DRMMesh::GetGroupMaterial

IDirect3DRMMesh

Direct3DRMMesh 오브젝트중의 그룹에 관련지을 수 있었던 머트리얼에의 포인터를 취득한다.

구문

HRESULT GetGroupMaterial(
  D3DRMGROUPINDEX id,
  LPDIRECT3DRMMATERIAL *returnPtr
  );

파라미터

id
그룹의 식별자. 이 식별자는IDirect3DRMMesh::AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.
returnPtr
메소드가 제어를 되돌릴 때, 그룹의IDirect3DRMMaterial 인터페이스를 받는 변수에의 포인터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMMesh::SetGroupMaterial

IDirect3DRMMesh::GetGroupQuality

IDirect3DRMMesh

Direct3DRMMesh 오브젝트중의 지정된 그룹의 렌더링 퀄리티를 취득한다.

구문

D3DRMRENDERQUALITY GetGroupQuality(
  D3DRMGROUPINDEX id
  );

파라미터

id
그룹의 식별자. 이 식별자는IDirect3DRMMesh::AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.

반환값

성공하면,D3DRMRENDERQUALITY 로 나타나는 열거형의 값을 돌려준다. 실패하면 0을 돌려준다. 이러한 값에는, 오브젝트의 쉐이딩 모드나 조명 모드, 전부 칠해 모드가 포함되어 있다.

참조

IDirect3DRMMesh::SetGroupQuality

IDirect3DRMMesh::GetGroupTexture

IDirect3DRMMesh

Direct3DRMMesh 오브젝트중의 그룹에 관련지을 수 있었던 텍스쳐에의 포인터를 취득한다.

구문

HRESULT GetGroupTexture(
  D3DRMGROUPINDEX id,
  LPDIRECT3DRMTEXTURE *returnPtr
  );

파라미터

id
그룹의 식별자. 이 식별자는IDirect3DRMMesh::AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.
returnPtr
메소드가 제어를 돌려줄 때, 그룹의IDirect3DRMTexture 인터페이스를 받는 변수에의 포인터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMMesh::SetGroupTexture

IDirect3DRMMesh::GetVertices

IDirect3DRMMesh

Direct3DRMMesh 오브젝트중의 지정의 그룹에 대한 버텍스 정보를 취득한다.

구문

HRESULT GetVertices(
  D3DRMGROUPINDEX id,
  DWORD index,
  DWORD count,
  D3DRMVERTEX *returnPtr
  );

파라미터

id
그룹의 식별자. 이 식별자는IDirect3DRMMesh::AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.
index
버텍스 위치를 취득하는 시점을 나타내는D3DRMVERTEX 구조체의 배열의 인덱스.
count
파라미터로 주어지고 있는 인덱스 이후의, 취득하는D3DRMVERTEX구조체(버텍스)의 수. 이 파라미터는 NULL로 할 수 없다. 그룹중의 버텍스의 수를 취득하려면 ,IDirect3DRMMesh::GetGroup 메소드를 호출한다.
returnPtr
메소드가 돌아왔을 때, 버텍스 정보(버텍스 위치, 색, 텍스쳐 좌표등)를 저장 하는D3DRMVERTEX구조체로부터 되는 배열.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMMesh::GetGroup , IDirect3DRMMesh::SetVertices

IDirect3DRMMesh::Scale

IDirect3DRMMesh

모델 좌표의 x축, y축, z축으로 대해, 주어진 스케일 계수에 의해 Direct3DRMMesh 오브젝트를 스케일링 한다.

구문

HRESULT Scale(
  D3DVALUE sx,
  D3DVALUE sy,
  D3DVALUE sz
  );

파라미터

sx, sy, sz
x축, y축, z축으로 따라 적용되는 스케일 계수.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMMesh::SetGroupColor

IDirect3DRMMesh

Direct3DRMMesh 오브젝트중의 그룹의 색을 설정한다.

구문

HRESULT SetGroupColor(
  D3DRMGROUPINDEX id,
  D3DCOLOR value
  );

파라미터

id
그룹의 식별자. 이 식별자는IDirect3DRMMesh::AddGroup 를 사용해 생성된 것이 아니면 안 된다.
value
그룹의 색.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, Direct3DRMMeshInterpolator 오브젝트에 그룹 RGB 키를 추가하기 위해서도 사용한다.

참조

IDirect3DRMMesh::GetGroupColor , IDirect3DRMMesh::SetGroupColorRGB

IDirect3DRMMesh::SetGroupColorRGB

IDirect3DRMMesh

RGB값을 사용해, Direct3DRMMesh 오브젝트중의 그룹의 색을 설정한다.

구문

HRESULT SetGroupColorRGB(
  D3DRMGROUPINDEX id,
  D3DVALUE red,
  D3DVALUE green,
  D3DVALUE blue
  );

파라미터

id
그룹의 식별자. 이 식별자는IDirect3DRMMesh::AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.
red, green, blue
그룹의 색의 적, 초록, 파랑의 각 요소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, Direct3DRMMeshInterpolator 오브젝트에 그룹 RGB 키를 추가하기 위해서도 사용한다.

참조

IDirect3DRMMesh::GetGroupColor , IDirect3DRMMesh::SetGroupColor

IDirect3DRMMesh::SetGroupMapping

IDirect3DRMMesh

Direct3DRMMesh 오브젝트중의 그룹에 맵핑을 설정한다. 맵핑은, 어떻게 텍스쳐가 면에 맵 될까를 결정한다.

구문

HRESULT SetGroupMapping(
  D3DRMGROUPINDEX id,
  D3DRMMAPPING value
  );

파라미터

id
그룹의 식별자. 이 식별자는IDirect3DRMMesh::AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.
value
그룹의 맵핑을 지정하는D3DRMMAPPING 형의 값.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMMesh::GetGroupMapping

IDirect3DRMMesh::SetGroupMaterial

IDirect3DRMMesh

Direct3DRMMesh 오브젝트중의 그룹에 머트리얼을 관련짓는다.

구문

HRESULT SetGroupMaterial(
  D3DRMGROUPINDEX id,
  LPDIRECT3DRMMATERIAL value
  );

파라미터

id
그룹의 식별자. 이 식별자는IDirect3DRMMesh::AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.
value
Direct3DRMMesh 오브젝트에 관련짓는IDirect3DRMMaterial 인터페이스의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMMesh::GetGroupMaterial

IDirect3DRMMesh::SetGroupQuality

IDirect3DRMMesh

Direct3DRMMesh 오브젝트중의 지정된 그룹의 렌더링 퀄리티를 설정한다.

구문

HRESULT SetGroupQuality(
  D3DRMGROUPINDEX id,
  D3DRMRENDERQUALITY value
  );

파라미터

id
그룹의 식별자. 이 식별자는IDirect3DRMMesh::AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.
value
D3DRMRENDERQUALITY 형으로 나타내지는 열거형의 값. 이러한 값에는, 오브젝트의 쉐이딩 모드나 조명 모드, 전부 칠해 모드가 포함되어 있다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMMesh::GetGroupQuality

IDirect3DRMMesh::SetGroupTexture

IDirect3DRMMesh

Direct3DRMMesh 오브젝트중의 그룹에 텍스쳐를 관련짓는다.

구문

HRESULT SetGroupTexture(
  D3DRMGROUPINDEX id,
  LPDIRECT3DRMTEXTURE value
  );

파라미터

id
그룹의 식별자. 이 식별자는IDirect3DRMMesh::AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.
value
Direct3DRMMesh 오브젝트에 관련짓는IDirect3DRMTexture 인터페이스의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMMesh::GetGroupTexture

IDirect3DRMMesh::SetVertices

IDirect3DRMMesh

Direct3DRMMesh 오브젝트중의 지정된 그룹의 버텍스의 위치를 설정한다.

구문

HRESULT SetVertices(
  D3DRMGROUPINDEX id,
  unsigned index,
  unsigned count,
  D3DRMVERTEX *values
  );

파라미터

id
그룹의 식별자. 이 식별자는IDirect3DRMMesh::AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.
index
수정하는 메쉬 그룹의 최초의 버텍스의 인덱스.
count
세트 하는 연속 버텍스의 수. values배열은, 적어도count수의 요소를 저장 해야 한다.
values
설정하는 버텍스 위치를 나타내는D3DRMVERTEX 구조체의 배열.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

버텍스 정보는 그룹 마다 가진다. 2개(살)이 다른 그룹간에 버텍스를 공유할 필요가 있는 경우(예를 들어, 메쉬 위에의 인접한 면의 색이 다를 때), 양쪽 모두의 그룹에서 버텍스를 카피하지 않으면 안 된다.

이 메소드는, Direct3DRMMeshInterpolator 오브젝트에 버텍스 위치 키를 추가하기 위해서도 사용한다.

참조

IDirect3DRMMesh::GetVertices

IDirect3DRMMesh::Translate

IDirect3DRMMesh

Direct3DRMMesh 오브젝트중의 버텍스의 위치에, 지정된 오프셋(offset)를 추가한다.

구문

HRESULT Translate(
  D3DVALUE tx,
  D3DVALUE ty,
  D3DVALUE tz
  );

파라미터

tx, ty, tz
각 버텍스 위치의 x좌표, y좌표, z좌표에 추가되는 오프셋(offset).

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.


IDirect3DRMMeshBuilder3

어플리케이션은,IDirect3DRMMeshBuilder3인터페이스의 메소드를 사용해 메쉬 오브젝트라고 회화한다. 메쉬의 상세한 것에 대하여는, 「IDirect3DRMMesh 」를 참조할것. Microsoft® DirectX® version 6.0은,IDirect3DRMMeshBuilder3인터페이스를 도입하고 있다. Direct3D 보관 유지 모드 인터페이스의 이력에 대해서는, 「인터페이스의 변경점」을 참조할것.

IDirect3DRMMeshBuilder3::AddVertex ,AddFace , 및AddFaces 메소드를 사용해, 메쉬에 대해서 개별적으로 버텍스와 면을 추가할 수가 있다. GetFace 메소드에 의해 개별의 면을 취득할 수가 있다.

법선 (단위벡터가 아니면 안된다)을 세트 하든가, 혹은,GenerateNormals 메소드를 사용해, 둘러싸고 있는 면의 면법선을 평균화해 법선을 계산할 수가 있다.

IDirect3DRMMeshBuilder3는, 그것이 치환하는 구의IDirect3DRMMeshBuilder2와IDirect3DRMMeshBuilder의 인터페이스를 확장한다. 이것은, 이러한 오브젝트를 삭제하기 위해서DeleteFace ,DeleteNormals , 및DeleteVertices 메소드를 추가해, 이러한 오브젝트를 취득하기 위해서GetNormal 메소드와GetVertex 메소드를 추가한다. 또,IDirect3DRMMeshBuilder3는Empty 메소드와Optimize 메소드도 추가한다.

다른 새로운IDirect3DRMMeshBuilder3메소드는, 1개이상의 법선, 법선의 수, 면, 1개이상의 버텍스, 및 메쉬 빌더 상태 (유효 또는 무효)를 취득한다. 이 인터페이스에 의해, 버텍스와 법선세트, 메쉬 빌더의 새로운 서브 메쉬와 친메쉬의 생성과 취득을 실시할 수가 있다. 또,IDirect3DRMMeshBuilder3에서는, 어플리케이션이 새로운 삼각형 (일반적인 다각형과 대립적인 의미로)을IDirect3DRMMeshBuilder3오브젝트에 추가해,AddTriangles 메소드를 사용해, 처리중에 암묵에 새로운 면을 생성 할 수 있다.

IDirect3DRMMeshBuilder3와 구의IDirect3DRMMeshBuilder2는,IDirect3DRMMeshBuilder의 기능을 포함한 위에, 한층 더GenerateNormals 메소드를 확장해 생성 끝난 메쉬 법선에 대해서 보다 많은 제어를 할 수 있도록(듯이) 하고 있다. 또,IDirect3DRMMeshBuilder3와IDirect3DRMMeshBuilder2에서는,GetFace 에 의해 단일의 메쉬면을 취득하는 일도 가능하게 된다.

DirectX 6.0이후에서는,IDirect3DRM3 인터페이스를 사용해Direct3DRMMeshBuilder3 오브젝트를 생성 할 수가 있다. 이 경우,Direct3DRMMeshBuilder3오브젝트는, 그 임플리멘테이션을 위해서(때문에) 직접 모드의 DrawPrimitive 인터페이스를 사용한다.

IDirect3DRMMeshBuilder3인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.
색 | GetColorSource
 | SetColor
 | SetColorRGB
 | SetColorSource
생성 | GetBox
면 | AddFace
 | AddFaces
 | AddFacesIndexed
 | CreateFace
 | DeleteFace
 | GetFaceCount
 | GetFace
 | GetFaces
로드 | Load
메쉬 | AddMesh
 | CreateMesh
그 외 | AddFrame
 | AddMeshBuilder
 | AddTriangles
 | Empty
 | Enable
 | GetEnable
 | Optimize
 | ReserveSpace
 | Save
 | Scale
 | SetMaterial
 | Translate
법선 | AddNormal
 | DeleteNormals
 | GenerateNormals
 | GetNormal
 | GetNormals
 | GetNormalCount
 | SetNormal
 | SetNormals
퍼스펙티브 | GetPerspective
 | SetPerspective
렌더링 퀄리티 | GetQuality
 | SetQuality
서브 메쉬 |
 | CreateSubMesh
 | DeleteSubMesh
 | GetParentMesh
 | GetSubMeshes
텍스쳐 | GetTextureCoordinates
 | SetTexture
 | SetTextureCoordinates
 | SetTextureTopology
버텍스 | AddVertex
 | DeleteVertices
 | GetGeometry
 | GetVertex
 | GetVertexColor
 | GetVertexCount
 | GetVertices
 | SetVertex
 | SetVertices
 | SetVertexColor
 | SetVertexColorRGB

모든 COM 인터페이스와 같이,IDirect3DRMMeshBuilder3인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

게다가IDirect3DRMMeshBuilder3인터페이스는,IDirect3DRMObject 인터페이스로부터 이하의 메소드를 계승한다.
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMMeshBuilder3 오브젝트는,IDirect3DRM3::CreateMeshBuilder 메소드를 호출해 취득된다.


IDirect3DRMObject

어플리케이션은, Microsoft® Direct3D®보관 유지 모드 오브젝트의 슈퍼 클래스와 교환하기 위해서(때문에),IDirect3DRMObject인터페이스의 메소드를 사용한다.

Direct3DRMObject는, 시스템중의 모든 오브젝트의 공통 슈퍼 클래스이다. Direct3DRMObject 오브젝트에는, 모든 오브젝트에 공통되는 특성이 있다.

각 Direct3DRMObject 오브젝트는, COM 오브젝트로서 인스턴스화 된다. IUnknown 인터페이스의 메소드에 가세해, 각 오브젝트에는 모두에게 공통된 메소드의 표준 세트가 있다.

오브젝트를 생성 하려면 , 어플리케이션은, 최초로,Direct3DRMCreate 함수를 호출하는 것으로 Direct3D 보관 유지 모드 오브젝트를 인스턴스화하지 않으면 안 된다. 다음에, 어플리케이션은, 오브젝트를 생성 하는 오브젝트의 인터페이스 메소드를 호출해, 오브젝트에 고유의 파라미터를 지정한다. 예를 들어, Direct3DRMAnimation 오브젝트를 생성 하려면 , 어플리케이션은IDirect3DRM3::CreateAnimation 메소드를 호출하게 된다. 다음에, 생성 메소드는 새로운 오브젝트를 생성 해, 파라미터중에서 (그 외 모든 것은 디폴트값인 채) 건네받는 데이터의 오브젝트 속성의 몇개인가를 초기화해, 오브젝트를 돌려준다. 다음에, 어플리케이션은, 이 오브젝트의 인터페이스를 지정해, 오브젝트의 수정과 사용을 실시할 수 있다.

임의의 오브젝트는, 어플리케이션 고유 데이터의 32 비트를 저장 할 수가 있다. 이 데이터를 보관 유지 모드로 해석 또는 변경할 수 없다. 어플리케이션은,IDirect3DRMObject::GetAppData 메소드를 사용해 이 데이터를 읽어들여,IDirect3DRMObject::SetAppData 메소드를 사용해 이 데이터에 쓰기 할 수가 있다. 어플리케이션이 Direct3DRMFrame의 각 오브젝트의 구조체를 보관 유지하고 있으면, 이 데이터의 검색은 간단하게 된다. 예를 들어,IDirect3DRMFrame3::GetParent 메소드의 호출로 Direct3DRMFrame 오브젝트를 취득하는 경우, 어플리케이션은 그 Private 구조체에의 포인터를 사용해, 데이터를 간단하게 꺼내, 시간이 걸리는 검색을 피할 수가 있다.

어플리케이션을 편성하는 지원을 위해서(때문에), 또는 어플리케이션의 유저 인터페이스의 일부로서 「이름」을 오브젝트에 할당하고 싶은 경우도 있다고 생각된다. IDirect3DRMObject::SetName 과IDirect3DRMObject::GetName 메소드를 사용해, 오브젝트명을 세트 해, 취득할 수가 있다.

어플리케이션 고유 데이터의 가능한 용도의 이제(벌써) 1개의 예는, 어플리케이션으로 메쉬내의 면을 서브 세트 (예를 들어, 전면과 후면)에 그룹화 할 필요가 있는 경우이다. 면안의 어플리케이션 데이터를 사용해, 면을 이러한 그룹의 어디에 들어갈 수 있는지를 주기할 수가 있다.

어플리케이션에서는, 오브젝트가 파기되었을 경우에 호출하는 함수를 지정할 수가 있다. 예를 들어, 어플리케이션으로 오브젝트에 관련지을 수 있었던 메모리의 할당 해제를 실시할 필요가 있는 경우 등이다. 이 때문에는,IDirect3DRMObject::AddDestroyCallback 메소드를 사용한다. 이 메소드로 이전에 등록한 함수를 삭제하려면 ,IDirect3DRMObject::DeleteDestroyCallback 메소드를 사용한다.

콜백 함수는, 오브젝트가 파기되었을 경우에게만 불려 간다. 즉, 오브젝트의참조 카운트가 0이 되어, 시스템이 오브젝트의 메모리의 할당을 해제하려고 하는 경우이다. 어플리케이션이 오브젝트에 관한 추가 데이터를 보관 유지하고 있는 경우 (예를 들어, 다이내믹스를 인플리맨트 하기 위해서), 어플리케이션은 데이터의 처리가 가능한 것을 자기 자신에게 통지하는 수단으로서 이 콜백 함수를 사용할 수가 있다.

오브젝트의 그룹화에 대해서는, 「IDirect3DRMObjectArray 」를 참조할것.

IDirect3DRMObject인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.
어플리케이션 고유의 | GetAppData
데이터 | SetAppData
복제 | Clone
이름 | GetClassName
 | GetName
 | SetName
통지 | AddDestroyCallback
 | DeleteDestroyCallback

모든 COM 인터페이스와 같이,IDirect3DRMObject인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

Direct3DRMObject 오브젝트는, 적절한QueryInterface메소드를 호출하는 것으로, 어느 보관 유지 모드 오브젝트로부터에서도 취득할 수가 있다. 모든 보관 유지 모드 오브젝트는,IDirect3DRMObject인터페이스 메소드를 계승한다.

IDirect3DRMObject::AddDestroyCallback

IDirect3DRMObject

오브젝트가 파기될 때 불려 가는 함수를 등록한다.

구문

HRESULT AddDestroyCallback(
  D3DRMOBJECTCALLBACK lpCallback,
  LPVOID lpArg
  );

파라미터

lpCallback
오브젝트가 파기될 때 사용되는, 유저 정의의 콜백 함수.
lpArg
콜백 함수에게 건네진 어플리케이션 정의 데이터의 주소. 이 함수는 오브젝트가 파기된 후에 사용되기 (위해)때문에, 인수로서 오브젝트를 건네주어서는 안 된다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMObject::Clone

IDirect3DRMObject

오브젝트의 복제를 생성 한다.

구문

HRESULT Clone(
  LPUNKNOWN pUnkOuter,
  REFIID riid,
  LPVOID *ppvObj
  );

파라미터

pUnkOuter
COM 집합화를 가능하게 하는 외부IUnknown인터페이스에의 포인터.
riid
복제하는 오브젝트의 식별자.
ppvObj
메소드가 제어를 돌려줄 때, 오브젝트의 복제를 저장 하는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMObject::DeleteDestroyCallback

IDirect3DRMObject

IDirect3DRMObject::AddDestroyCallback 메소드에 의해 등록된 함수를 삭제한다.

구문

HRESULT DeleteDestroyCallback(
  D3DRMOBJECTCALLBACK d3drmObjProc,
  LPVOID lpArg
  );

파라미터

d3drmObjProc
오브젝트가 파기될 때 사용되는, 유저 정의의D3DRMOBJECTCALLBACK 콜백 함수.
lpArg
콜백 함수에게 건네진 어플리케이션 정의 데이터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMObject::GetAppData

IDirect3DRMObject

오브젝트로부터, 어플리케이션 고유의 32 비트 데이터를 취득한다. 데이터의 디폴트값은 0이다.

구문

DWORD GetAppData( );

반환값

어플리케이션에 의해 정의된 데이터값을 돌려준다.

참조

IDirect3DRMObject::SetAppData

IDirect3DRMObject::GetClassName

IDirect3DRMObject

오브젝트의 클래스명을 취득한다.

구문

HRESULT GetClassName(
  LPDWORD lpdwSize,
  LPSTR lpName
  );

파라미터

lpdwSize
lpName파라미터가 가리키는 버퍼의 사이즈가 바이트 단위로 들어가는 변수의 주소.
lpName
메소드가 제어를 돌려줄 때, 클래스명을 나타내는 NULL로 끝나는 캐릭터 라인의 주소. 이 파라미터가 NULL의 경우,lpdwSize파라미터에는 캐릭터 라인에 필요한 사이즈가 설정된다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMObject::GetName

IDirect3DRMObject

오브젝트명을 취득한다.

구문

HRESULT GetName(
  LPDWORD lpdwSize,
  LPSTR lpName
  );

파라미터

lpdwSize
lpName파라미터가 가리키는 버퍼의 사이즈가 바이트 단위로 들어가는 변수의 주소.
lpName
메소드가 제어를 돌려줄 때, 오브젝트의 이름을 나타내는 NULL로 끝나는 캐릭터 라인의 주소. 이 파라미터가 NULL의 경우,lpdwSize파라미터에는 캐릭터 라인에 필요한 사이즈가 설정된다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMObject::SetName

IDirect3DRMObject::SetAppData

IDirect3DRMObject

오브젝트에 어플리케이션 고유의 32 비트 데이터를 설정한다.

구문

HRESULT SetAppData(
  DWORD ulData
  );

파라미터

ulData
오브젝트에 저장 되는 유저 정의의 데이터.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMObject::GetAppData

IDirect3DRMObject::SetName

IDirect3DRMObject

오브젝트의 이름을 설정한다.

구문

HRESULT SetName(
  const char  *lpName
  );

파라미터

lpName
오브젝트의 이름을 나타내는 유저 정의의 데이터.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMObject::GetName


IDirect3DRMObject2

어플리케이션은,IDirect3DRMObject2인터페이스의 메소드를 사용해, Microsoft® Direct3D®보관 유지 모드 오브젝트의 오브젝트 2 슈퍼 클래스에 제의한다. Microsoft DirectX version 6.0은, 모든 보관 유지 모드 오브젝트가 인플리맨트 하는IDirect3DRMObject2인터페이스를 도입한다. 임의의 Direct3D 보관 유지 모드 오브젝트 위에의QueryInterface 를 사용해, 이 인터페이스에의 포인터를 취득할 수가 있다.

IDirect3DRMObject2는, 동명의IDirect3DRMObject 메소드와 등가인 다음의 메소드를 인플리맨트 한다.
AddDestroyCallback
Clone
DeleteDestroyCallback
GetName
SetName

IDirect3DRMObject2가IDirect3DRMObject 와 공유하는 메소드에 가세해, 다음의 메소드도 인플리맨트 한다.
GetDirect3DRM
GetClientData
GetAge
SetClientData

IDirect3DRMObject2::GetClientData 와IDirect3DRMObject2::SetClientData 는, 오브젝트와의 데이터 결합을 제공한다. 이것은, 구의IDirect3DRMObject::GetAppData 와IDirect3DRMObject::SetAppData 메소드보다 유연성이 높다.

구의 오브젝트 인터페이스의 개념의 개요에 대해서는, 「IDirect3DRMObject 」를 참조할것. Direct3D 보관 유지 모드 인터페이스의 이력에 대해서는, 「인터페이스의 변경점」을 참조할것.

IDirect3DRMObject2인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.
어플리케이션 고유의 데이터 | GetClientData
 | SetClientData
복제 | Clone
이름 | GetName
 | SetName
그 외 | GetAge
 | GetDirect3DRM
통지 | AddDestroyCallback
 | DeleteDestroyCallback

모든 COM 인터페이스와 같이,IDirect3DRMObject2인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

Direct3DRMObject2 오브젝트는, 적절한QueryInterface메소드를 호출하는 것으로, 어느 보관 유지 모드 오브젝트로부터에서도 취득할 수가 있다. 모든 보관 유지 모드 오브젝트는,IDirect3DRMObject2인터페이스 메소드를 계승한다.

IDirect3DRMObject2::AddDestroyCallback

IDirect3DRMObject2

오브젝트가 파기될 때 불려 가는 함수를 등록한다.

구문

HRESULT AddDestroyCallback(
  D3DRMOBJECTCALLBACK lpCallback,
  LPVOID lpArg
  );

파라미터

lpCallback
오브젝트가 파기될 때 사용되는, 유저 정의의 콜백 함수.
lpArg
콜백 함수에게 건네진 어플리케이션 정의 데이터의 주소. 이 함수는 오브젝트가 파기된 후에 사용되기 (위해)때문에, 인수로서 오브젝트를 건네주어서는 안 된다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는,IDirect3DRMObject 의 동명의 메소드와 동등하다.

IDirect3DRMObject2::Clone

IDirect3DRMObject2

오브젝트의 복제를 생성 한다.

구문

HRESULT Clone(
  LPUNKNOWN pUnkOuter,
  REFIID riid,
  LPVOID *ppvObj
  );

파라미터

pUnkOuter
COM 집합화를 가능하게 하는 외부IUnknown인터페이스에의 포인터.
riid
복제하는 오브젝트의 식별자.
ppvObj
메소드가 제어를 돌려줄 때, 오브젝트의 복제를 저장 하는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMObject2::DeleteDestroyCallback

IDirect3DRMObject2

IDirect3DRMObject2::AddDestroyCallback 메소드에 의해 등록된 함수를 삭제한다.

구문

HRESULT DeleteDestroyCallback(
  D3DRMOBJECTCALLBACK d3drmObjProc,
  LPVOID lpArg
  );

파라미터

d3drmObjProc
오브젝트가 파기될 때 사용되는, 유저 정의의D3DRMOBJECTCALLBACK 콜백 함수.
lpArg
콜백 함수에게 건네진 어플리케이션 정의 데이터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는,IDirect3DRMObject 의 동명의 메소드와 동등하다.

IDirect3DRMObject2::GetAge

IDirect3DRMObject2

오브젝트의 현재의 연령을 보고한다.

구문

HRESULT GetAge(
  DWORD dwFlags,
  LPDWORD lpdwAge);

파라미터

dwFlags
플래그값. 오브젝트가 메쉬 빌더가 아닌 경우, 0이 아니면 안된다. 오브젝트가 메쉬 빌더인 경우, 다음의 값의 어떤 것이나 1개를 세트 할 수 있다.
디폴트(0)
메쉬 빌더는 보통 대로에 나이를 먹는다(에이징은 메쉬 빌더에 대한 어떠한 변경에 의해 일으켜진다).
D3DRMMESHBUILDERAGE_GEOMETRY
메쉬 빌더는, 메쉬 지오메트리가 변경될 때마다 나이를 먹는다(예를 들어, 버텍스, 면 또는 다른 메쉬 빌더의 추가).
D3DRMMESHBUILDERAGE_MATERIALS
메쉬 빌더는, 메쉬의 머트리얼 관련 프로퍼티가 변경될 때마다, 혹은, 면 또는 다른 메쉬가 추가되었을 경우에 나이를 먹는다.
D3DRMMESHBUILDERAGE_TEXTURES
메쉬 빌더는, 메쉬의 텍스쳐 관련 프로퍼티가 변경될 때마다, 혹은, 면 또는 다른 메쉬가 추가되었을 경우에 나이를 먹는다.
lpdwAge
연령을 받는 포인터.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

오브젝트가 수정되면(자), 연령이 증가한다.

이 메소드는 DirectX version 6.0으로 도입되었다. DirectX 6.0이후에서는, 다음의 오브젝트만 에이징을 지원 한다.
Direct3DRMDevice3
Direct3DRMTexture3
Direct3DRMMeshBuilder3
Direct3DRMUserVisual
Direct3DRMShadow2
Direct3DRMWrap

IDirect3DRMObject2::GetClientData

IDirect3DRMObject2

SetClientData 의 호출을 개입시켜, 오브젝트에 이전에 관련지을 수 있었던 데이터를 취득한다.

구문

HRESULT GetClientData(
  DWORD dwID,
  LPVOID *lplpvData);

파라미터

dwID
RegisterClient의 호출에 의해 취득되는 어플리케이션 ID.
lplpvData
관련 데이터를 받는 변수의 주소.
NULL값은, 데이터가 세트되어 있지 않은 것을 나타낸다.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_CLIENTNOTREGISTERED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND
DDERR_NOTINITIALIZED
DD_OK

주의

데이터의 타입이IUnknown이다면, 이 메소드는, 데이터를 호출해 바탕으로 돌려주기 전에참조 카운트를 인크리먼트(increment) 한다. 이 메소드는, DirectX version 6.0으로 도입되었다.

IDirect3DRMObject2::GetDirect3DRM

IDirect3DRMObject2

이 오브젝트의 생성과 관계되는 마지막Direct3DRM오브젝트의 인터페이스에의 포인터를 취득한다.

구문

HRESULT GetDirect3DRM(
  LPLPDIRECT3DRM lplpD3DRM);

파라미터

lplpD3DRM
lpDirect3DRMObject로 지정한 오브젝트의 생성과 관계되는, 마지막 Direct3D 보관 유지 모드 오브젝트의 인터페이스에의 포인터를 받는 주소.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMObject2::GetName

IDirect3DRMObject2

오브젝트명을 취득한다.

구문

HRESULT GetName(
  LPDWORD lpdwSize,
  LPSTR lpName
  );

파라미터

lpdwSize
lpName파라미터가 가리키는 버퍼의 사이즈가 바이트 단위로 들어가는 변수의 주소.
lpName
메소드가 제어를 돌려줄 때, 오브젝트의 이름을 나타내는 NULL로 끝나는 캐릭터 라인의 주소. 이 파라미터가 NULL의 경우,lpdwSize파라미터에는 캐릭터 라인에 필요한 사이즈가 설정된다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMObject2::SetName

주의

이 메소드는,IDirect3DRMObject 의 동명의 메소드와 동등하다.

IDirect3DRMObject2::SetClientData

IDirect3DRMObject2

보관 유지 모드 오브젝트를 가지는 데이터 항목을 관련짓는다.

구문

HRESULT SetClientData(
  DWORD dwID,
  LPVOID lpvData,
  DWORD dwFlags);

파라미터

dwID
IDirect3DRM3::RegisterClient 의 호출에 의해 취득되는 어플리케이션 ID.
lpvData
오브젝트에 관련지을 수 있는 어플리케이션 고유의 데이터.
dwFlags
보관 유지 모드에 의한 데이터의 해석 방법을 결정하는 플래그.
플래그 | D3DRMCLIENTDATA_NONE | D3DRMCLIENTDATA_LOCALFREE | D3DRMCLIENTDATA_IUNKNOWN
데이터의 해석 | 해석 없음 | 데이터는 클라이언트에 의해 할당할 수 있다. Direct3DRM는, 결합 해제 시에 그것을 개방할 필요가 있다. | 데이터는IUnknown인터페이스를 포인트 하는 것을 전제로 한다.
SetClientData위에의 동작 | 동작 없음 | 동작 없음 | Direct3D 보관 유지 모드는, 인터페이스 위에의 참조 카운트를 인크리먼트(increment) 한다.
GetClientData 위에의 동작 | 동작 없음 | 동작 없음 | Direct3D 보관 유지 모드는, 호출 바탕으로 그것을 건네주기 전에 인터페이스 위에의 참조 카운트를 인크리먼트(increment) 한다.
데이터가 오브젝트로부터 결합 해제되었을 경우에 동작 | 동작 없음 | 데이터상에서는LocalFree가 사용된다. | Direct3D 보관 유지 모드는, 인터페이스 위에의 참조 카운트를 감소 한다.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_CLIENTNOTREGISTERED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

데이터의 삭제는, NULL를lpvData파라미터로서 이 메소드를 호출하는지, 오브젝트의 파기에 의하는지, 또는IDirect3DRM3::UnregisterClient 를 사용해 실시할 수가 있다. dwID로 지정되는 ID를 사용해 이전에 데이터를 오브젝트에 관련지었을 경우, 이전의 데이터는 릴리스 된다. 파기 메소드는,dwFlags파라미터중에서 이 메소드에게 건네지는 플래그에 의존한다. GetClientData 의 호출에 의해, 데이터를 취득할 수가 있다. 이 메소드는, DirectX version 6.0으로 도입되었다.

IDirect3DRMObject2::SetName

IDirect3DRMObject2

오브젝트의 이름을 설정한다.

구문

HRESULT SetName(
  const char  *lpName
  );

파라미터

lpName
오브젝트의 이름을 나타내는 유저 정의의 데이터.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는,IDirect3DRMObject 의 동명의 메소드와 동등하다.

참조

IDirect3DRMObject2::GetName


IDirect3DRMObjectArray

Direct3DRMObject 오브젝트를 그룹화 하려면 ,IDirect3DRMObjectArray인터페이스의 메소드를 이용한다. Direct3DRMObject에 대한 자세한 것은, 「IDirect3DRMObject 」를 참조할것.

IDirect3DRMObjectArray인터페이스는, 다음의 메소드를 지원 한다.
GetElement
GetSize

모든 COM 인터페이스와 같이,IDirect3DRMObjectArray인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

Direct3DRMObjectArray 오브젝트는,IDirect3DRMInterpolator::GetAttachedObjects 메소드의 호출에 의해 취득된다.

IDirect3DRMObjectArray::GetElement

IDirect3DRMObjectArray

Direct3DRMObjectArray 오브젝트로부터 지정된 요소를 취득한다.

구문

HRESULT GetElement(
  DWORD index,
  LPDIRECT3DRMOBJECT  *lplpD3DRMObject
  );

파라미터

index
배열 요소.
lplpD3DRMObject
IDirect3DRMObject 인터페이스에의 포인터를 받는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMObjectArray::GetSize

IDirect3DRMObjectArray

Direct3DRMObjectArray 오브젝트에 포함되어 있는 요소수를 취득한다.

구문

DWORD GetSize( );

반환값

요소수를 돌려준다.


IDirect3DRMPicked2Array

픽 오브젝트를 그룹화 해, 보다 많은 정보를 돌려주려면 , 어플리케이션은,IDirect3DRMPicked2Array인터페이스의 메소드를 이용한다. 픽의 상세한 것에 대하여는, 「IDirect3DRMPickedArray 」를 참조할것.

IDirect3DRMFrame3::RayPick 메소드를 사용해,IDirect3DRMPicked2Array 인터페이스를 취득한다. 다음에,IDirect3DRMPicked2Array::GetPick 메소드를 호출해,IDirect3DRMFrameArray 인터페이스, 비주얼 오브젝트, 및 광선이 교차하는 오브젝트에 관한 정보를 취득할 수가 있다. 이 정보에는, 면과 그룹의 식별자, 픽 위치, 및 오브젝트의 버텍스, 버텍스 법선, 색에 대한 수평과 수직 텍스쳐 좌표가 포함된다. 프레임의 배열은, 비주얼 오브젝트에 통하는 계층에의 패스이다.

IDirect3DRMPicked2Array::GetPick 에 의해 돌려주어지는D3DRMPICKDESC2 구조체에는, 면이나 그룹의 식별자, 픽의 위치, 버텍스의 수평 및 수직 텍스쳐 좌표, 버텍스의 법선 및 교차한 오브젝트의 색이 포함되어 있다. 이 인터페이스 포인터에의 포인터는, 광선의 픽중에IDirect3DRMFrame3::RayPick 메소드로 돌려주어진다.

IDirect3DRMPicked2Array인터페이스는, 다음의 메소드를 지원 한다.
GetPick
GetSize

모든 COM 인터페이스와 같이,IDirect3DRMPicked2Array인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

Direct3DRMPicked2Array 오브젝트는,IDirect3DRMFrame3::RayPick 메소드의 호출에 의해 취득된다.

IDirect3DRMPicked2Array::GetPick

IDirect3DRMPicked2Array

지정된 픽에 의해 교차하는 Direct3DRMVisual와 Direct3DRMFrame 오브젝트를 취득한다.

구문

HRESULT GetPick(
  DWORD index,
  LPDIRECT3DRMVISUAL  *lplpVisual,
  LPDIRECT3DRMFRAMEARRAY  *lplpFrameArray,
  LPD3DRMPICKDESC2 lpD3DRMPickDesc2
  );

파라미터

index
정보를 취득하는 픽을 식별하는, 픽 배열에의 인덱스.
lplpVisual
지정된 픽에 관련지을 수 있었던 Direct3DRMVisual 오브젝트의 포인터의 주소.
lplpFrameArray
지정된 픽에 관련지을 수 있었던 Direct3DRMFrameArray 오브젝트의 포인터의 주소.
lpD3DRMPickDesc
면이나 그룹의 식별자, 픽의 위치, 버텍스의 수평 및 수직 텍스쳐 좌표, 버텍스의 법선 및 교차한 오브젝트의 색이 지정하는D3DRMPICKDESC2 구조체에의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는,D3DRMPICKDESC 구조체는 아니고D3DRMPICKDESC2 구조 체내의 u값과 v값을 취득하는 점을 제외하면,IDirect3DRMPickedArray::GetPick 와 유사한다.

참조

IDirect3DRMFrame3::RayPick

IDirect3DRMPicked2Array::GetSize

IDirect3DRMPicked2Array

Direct3DRMPicked2Array 오브젝트에 포함되어 있는 요소수를 취득한다.

구문

DWORD GetSize( );

반환값

요소수를 돌려준다.


IDirect3DRMPickedArray

어플리케이션은,IDirect3DRMPickedArray인터페이스의 메소드를 사용해, 픽 오브젝트를 그룹화 한다. 피킹은, 뷰포트중에서 2 D좌표 또는 프레임중에서 벡터가 주어졌을 때에, 장면 위에의 비주얼을 검색하는 프로세스이다. 광선 픽에 대해서는, 「IDirect3DRMPicked2Array 」를 참조할것.

IDirect3DRMViewport2::Pick 메소드를 사용해,IDirect3DRMPickedArray 인터페이스를 취득한다. 다음에,IDirect3DRMPickedArray::GetPick 메소드를 호출해,IDirect3DRMFrameArray 인터페이스와 비주얼 오브젝트를 취득할 수가 있다. 프레임의 배열은, 계층을 거쳐 비주얼 오브젝트에 통하는 패스이다. 이것은, 즉, 계층안의 최상부의 부모가 배열의 최초로 오는 비주얼 오브젝트의 친프레임의 계층 리스트이다.

IDirect3DRMPickedArray인터페이스는, 다음의 메소드를 지원 한다.
GetPick
GetSize

모든 COM 인터페이스와 같이,IDirect3DRMPickedArray인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

Direct3DRMPickedArray 오브젝트는,IDirect3DRMViewport2::Pick 메소드의 호출에 의해 취득된다.

IDirect3DRMPickedArray::GetPick

IDirect3DRMPickedArray

지정된 픽에 의해 교차하는 Direct3DRMVisual와 Direct3DRMFrame 오브젝트를 취득한다.

구문

HRESULT GetPick(
  DWORD index,
  LPDIRECT3DRMVISUAL  *lplpVisual,
  LPDIRECT3DRMFRAMEARRAY  *lplpFrameArray,
  LPD3DRMPICKDESC lpD3DRMPickDesc
  );

파라미터

index
정보를 취득하는 픽을 식별하는, 픽 배열에의 인덱스.
lplpVisual
지정된 픽에 관련지을 수 있었던 Direct3DRMVisual 오브젝트의 포인터의 주소.
lplpFrameArray
지정된 픽에 관련지을 수 있었던 Direct3DRMFrameArray 오브젝트의 포인터의 주소.
lpD3DRMPickDesc
픽의 위치, 면, 취득하는 오브젝트의 그룹 식별자를 지정하는D3DRMPICKDESC 구조체에의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMViewport2::Pick

IDirect3DRMPickedArray::GetSize

IDirect3DRMPickedArray

Direct3DRMPickedArray 오브젝트에 포함되어 있는 요소수를 취득한다.

구문

DWORD GetSize( );

반환값

요소수를 돌려준다.


IDirect3DRMProgressiveMesh

메쉬는, 다각형면세트로부터 구성되는 비주얼 오브젝트이다. 메쉬는, 버텍스세트와 면세트를 정의한다. 메쉬의 상세한 것에 대하여는, 「IDirect3DRMMesh 」를 참조할것.

프로그래시브 메쉬는, 베이스 메쉬 (엉성한 버젼) 및 메쉬를 한층 더 정제 하기 위해서 사용되는버텍스 분할레코드세트로서 저장 되는 메쉬이다. 즉, 프로그래시브인 정제가 가능하다. 이것에 의해, 메쉬용의 렌더링의 상세 레벨을 세트 해, 리모트 소스로부터의 프로그래시브 다운로드도 가능하게 된다.

프로그래시브 메쉬는, Microsoft® Direct3D®보관 유지 모드의 비주얼이며, 비주얼 처리의 표준적인 방법으로 사용할 수가 있다. 즉, 프로그래시브 메쉬는, 프레임 계층에 추가하는 것, 여러 차례의 인스턴스화, 및 픽도 가능하다.

IDirect3DRMProgressiveMesh 인터페이스의 메소드를 사용해, 렌더링 하는 버텍스 또는 면의 수를 세트 해, 렌더링 상세를 제어할 수가 있다. 렌더링에 필요한 최소 상세 레벨을 지정할 수도 있다. 보통, 프로그래시브 메쉬는, 베이스 메쉬가 한 번 사용 가능하게 되면(자) 렌더링 되지만,IDirect3DRMProgressiveMesh::SetMinRenderDetail 메소드에 의해 렌더링의 전에 그 이상의 상세 레벨이 필요하다라고 지정할 수가 있다. 또,IDirect3DRMProgressiveMesh::CreateMesh 메소드를 사용해, 프로그래시브 메쉬 고유 상태로부터Direct3DRMMesh오브젝트를 구축할 수도 있다.

프로그래시브 메쉬를, 파일, 리소스, 메모리, 또는 URL로부터 로드할 수가 있다. 로딩은 동기식에서도 비동기식에서도 실시할 수 있다. 다운로드 상태는IDirect3DRMProgressiveMesh::GetLoadStatus 메소드에 의해 체크해,IDirect3DRMProgressiveMesh::Abort 메소드로 다운로드를 종료할 수가 있다. 로딩이 비동기식의 경우, 로드의 진행 상태를 조사하기 위해서(때문에)IDirect3DRMProgressiveMesh::RegisterEvents 와IDirect3DRMProgressiveMesh::GetLoadStatus메소드를 개입시켜 이벤트를 사용할지 어떨지는 어플리케이션 나름이다.

Direct3DRMProgressiveMesh 오브젝트는,IDirect3DRM3::CreateProgressiveMesh 메소드를 사용하는 것에 의해 생성 된다. 생성 후, 오브젝트는 계층에 추가할 수 있지만, 적어도 베이스 메쉬가 사용 가능하게 될 때까지, 렌더링 되지 않는다.

표준적인IUnknown 및IDirect3DRMObject 메소드에 가세해, 이 API는, 이하의 멤버를 포함한다.

메쉬의 생성과 카피 | Clone
 | CreateMesh
 | Duplicate
 | GetBox
로드 | Abort
 | GetLoadStatus
 | Load
퀄리티의 설정 | SetQuality
 | GetQuality
상세한 관리 | GetDetail
 | GetFaceDetail
 | GetFaceDetailRange
 | GetVertexDetail
 | GetVertexDetailRange
 | SetDetail
 | SetFaceDetail
 | SetMinRenderDetail
 | SetVertexDetail
이벤트의 등록 | RegisterEvents

모든 COM 인터페이스와 같이,IDirect3DRMProgressiveMesh인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

게다가IDirect3DRMProgressiveMesh인터페이스는,IDirect3DRMObject 인터페이스로부터 이하의 메소드를 계승한다.
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

IDirect3DRMProgressiveMesh::Abort

IDirect3DRMProgressiveMesh

현재 액티브한 다운로드를 중지한다.

구문

HRESULT Abort(
  DWORD dwFlags
  )

파라미터

dwFlags
0이 아니면 안된다.

반환값

성공하면 D3DRM_OK, 실패하면 다음의 몇개의 에러를 돌려준다.
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS

주의

이 메소드가 사용되기 전에 베이스 메쉬가 다운로드되고 있는 경우, 그 효과는, 프로그래시브 메쉬가 로드 되어 분할 버텍스가 유효한 상태에 있어, 프로그래시브 메쉬가 렌더링 가능한 경우와 같다. 다른 프로그래시브 메쉬 메소드도 사용할 수 있다. IDirect3DRMProgressiveMesh::Abort를 호출하기 전에 베이스 메쉬가 다운로드되지 않고, 장면에 프로그래시브 메쉬를 추가했을 경우,IDirect3DRMViewport2::Render 는 성공하지만, 프로그래시브 메쉬에의 렌더링은 행해지지 않는다. 또, 프로그래시브 메쉬를 사용할때 (예를 들어, 메쉬나 클론을 생성 하기 위한(해))에 베이스 메쉬가 다운로드되어 있지 않으면, 호출은 D3DRMERR_NOTENOUGHDATA를 돌려준다.

IDirect3DRMProgressiveMesh::Clone

IDirect3DRMProgressiveMesh

현재 로드 되고 있는Direct3DRMProgressiveMesh 오브젝트의 카피를 생성 한다.

구문

HRESULT Clone(
  LPDIRECT3DRMPROGRESSIVEMESH *lplpD3DRMPMesh
  )

파라미터

lplpD3DRMPMesh
새롭게 생성되는Direct3DRMProgressiveMesh 오브젝트에의 포인터로 세트 되는Direct3DRMProgressiveMesh포인터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 다음의 몇개의 에러를 돌려준다.
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_NOTENOUGHDATA

주의

클론중의 프로그래시브 메쉬에는, 적어도 그 베이스 메쉬를 로드해 두지 않으면 안 된다. 현재, 비동기에 로드안의 프로그래시브 메쉬상에서 이 메소드를 사용하면(자), 클론 된 메쉬는 로드하고 있는 프로그래시브 메쉬가 클론 되었을 때에 가지고 있던 상세 레벨 밖에 가지지 않는다. 복제 후에 로드 된 만큼 비율 버텍스는, 클론 된 메쉬에서는 이용할 수 없다.

이 메소드는 프로그래시브 메쉬의 내부 데이터를 공유하려고는 하지 않지만,IDirect3DRMProgressiveMesh::Duplicate 는 공유하려고 한다.

참조

IDirect3DRMProgressiveMesh::Duplicate

IDirect3DRMProgressiveMesh::CreateMesh

IDirect3DRMProgressiveMesh

현재의 상세 레벨로 메쉬를 생성 한다.

구문

HRESULT CreateMesh(
  LPDIRECT3DRMMESH *lplpD3DRMMesh
  )

파라미터

lplpD3DRMMesh
새롭게 생성되는Direct3DRMMesh오브젝트에의 포인터로 세트 되는Direct3DRMMesh포인터에의 포인터.

반환값

성공하면 D3DRM_OK, 실패하면 다음의 몇개의 에러를 돌려준다.
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_NOTENOUGHDATA

주의

어플리케이션이, 아직 사용 가능하게 되지 않은 상세 레벨을 요구하는지, 또는 베이스 메쉬가, 아직 사용 가능하게 되지 않은가의 몇개의 경우에는, 이 메소드는 에러D3DRMERR_NOTENOUGHDATA 를 돌려준다.

IDirect3DRMProgressiveMesh::Duplicate

IDirect3DRMProgressiveMesh

Direct3DRMProgressiveMesh 오브젝트의 카피를 생성 한다. 이 카피는, 오리지날과 기하 도형이나 면데이터를 모두 공유한다. 그러나, 오리지날과는 별도로 상세 레벨을 설정할 수가 있다. 이것은, 동일한 메쉬 데이터를 계층이 다른 부분에서, 다만, 다른 상세 레벨로 사용할 수 있도록(듯이) 한다. 본질적으로, 프레임 계층내에 프로그래시브 메쉬의 2개의 인스턴스가 있다고 말할 수 있다.

구문

HRESULT Duplicate(
  LPDIRECT3DRMPROGRESSIVEMESH *lplpD3DRMPMesh
  )

파라미터

lplpD3DRMPMesh
새롭게 생성되는Direct3DRMProgressiveMesh 오브젝트에의 포인터로 세트 되는Direct3DRMProgressiveMesh포인터의 주소.

반환값

실패하면 다음의 몇개의 에러를 돌려준다.
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_NOTENOUGHDATA

주의

복제중의 프로그래시브 메쉬에는, 적어도 그 베이스 메쉬를 로드해 두지 않으면 안 된다. 현재, 비동기에 로드안의 프로그래시브 메쉬상에서 이 메소드를 사용하면(자), 복제된 메쉬는 로드하고 있는 프로그래시브 메쉬가 복제되었을 때에 가지고 있던 상세 레벨 밖에 가지지 않는다. 복제 후에 로드 된 만큼 비율 버텍스는, 복제된 메쉬에서는 이용할 수 없다.

프로그래시브 메쉬는, 베이스 메쉬를 나타내는 데이터 세트와 분할 버텍스를 나타내는 데이터 세트를 가지고 있다. 베이스 메쉬 데이터 및 프로그래시브 메쉬의 현상이나 현재의 상세 레벨을 기술하는 데이터는, 복제된 메쉬간에 공유되지 않는다. 그러나, 분할 버텍스 데이터는 공유된다. 이 메소드는 프로그래시브 메쉬의 새로운 인스턴스를 생성 한다. 이 인스턴스는, 오리지날과 기하 도형이나 면데이터를 모두 공유하지만, 그 상세 레벨은 오리지날 (와)는 관계없는 것으로 설정할 수가 있다.

IDirect3DRMProgressiveMesh::GetBox

IDirect3DRMProgressiveMesh

Direct3DRMProgressiveMesh 오브젝트를 포함한 경계 박스를 취득한다. 경계 박스는, 각 차원에서, 아이 프레임을 기준으로 하는 최소 및 최대의 좌표를 준다.

구문

HRESULT GetBox(
  D3DRMBOX  *lpD3DRMBox
  );

파라미터

lpD3DRMBox
경계 박스의 좌표가 세트 되는D3DRMBOX 구조체의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMProgressiveMesh::GetDetail

IDirect3DRMProgressiveMesh

0.0으로 1.0의 사이에 정규화된 현재의 상세 레벨의 프로그래시브 메쉬를 돌려준다.

구문

HRESULT GetDetail(
  LPD3DVALUE lpdvVal
  )

파라미터

lpdvVal
현재의 상세 레벨의 프로그래시브 메쉬가 세트 되는D3DVALUE 의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 다음의 몇개의 에러를 돌려준다.
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING

주의

베이스 메쉬가 다운로드되어 있지 않으면, 이 메소드는,D3DRMERR_PENDING 를 돌려준다. 요구되고 있는 상세 레벨이 설정되어 있으면, 반환값은, 요구 레벨이 만족될 때까지 이후가 호출할 것에 증가된다. 레벨이 요구되어 있지 않으면, 상세 레벨은, 모든 분할 버텍스의 다운로드가 완료할 때까지 상승한다.

정규화된 값 0.0은 버텍스의 최소수를 나타내 (베이스 메쉬중의 버텍스수), 정규화된 값 1.0은 버텍스의 최대수를 나타낸다.

IDirect3DRMProgressiveMesh::GetFaceDetail

IDirect3DRMProgressiveMesh

프로그래시브 메쉬에 있는 면의 수를 취득한다.

구문

HRESULT GetFaceDetail(
  LPDWORD lpdwCount
  )

파라미터

lpdwCount
프로그래시브 메쉬의 면의 수가 세트 되는DWORD의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 다음의 몇개의 에러를 돌려준다.
D3DRMERR_CONNECTIONLOST
D3DRMERR_PENDING
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS

주의

면의 수를 이용할 수 없으면, 이 메소드는D3DRMERR_PENDING 를 돌려준다.

IDirect3DRMProgressiveMesh::GetFaceDetailRange

IDirect3DRMProgressiveMesh

프로그래시브 메쉬로 사용 가능한 최소 및 최대의 면카운트를 돌려준다.

구문

HRESULT GetFaceDetailRange(
  LPDWORD lpdwMinFaces,
  LPDWORD lpdwMaxFaces
  )

파라미터

lpdwMinFaces
면의 최소수가 세트 되는DWORD값의 주소.
lpdwMaxFaces
면의 최대수가 세트 되는DWORD값의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 다음의 몇개의 에러를 돌려준다.
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING

주의

면카운트를 취득할 수 없는 경우에는, D3DRMERR_PENDING를 돌려준다.

IDirect3DRMProgressiveMesh::GetLoadStatus

IDirect3DRMProgressiveMesh

로드의 현재 상태를 어플리케이션이 조회하는 것을 가능하게 한다.

구문

HRESULT GetLoadStatus(
  LPD3DRMPMESHLOADSTATUS lpStatus
  )

파라미터

lpStatus
프로그래시브 메쉬의 로드 상태를 포함한D3DRMPMESHLOADSTATUS 구조체의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 다음의 몇개의 에러를 돌려준다.
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS

주의

메쉬의 렌더링이 가능한(베이스 메쉬의 다운로드가 완료해, 데이터가 망가지지 않았다) 경우에는,dwFlags멤버에는, D3DRMPMESHSTATUS_RENDERABLE를 저장 한다. 다운로드가 세치기를 받았을 경우에는,dwFlags멤버에는, D3DRMPMESHSTATUS_INTERRUPTED를 저장 한다.

IDirect3DRMProgressiveMesh::GetQuality

IDirect3DRMProgressiveMesh

프로그래시브 메쉬의 렌더링 퀄리티를 지정하는D3DRMRENDERQUALITY 열거형의 멤버를 취득한다.

구문

HRESULT GetQuality(
  LPD3DRMRENDERQUALITY lpQuality
  );

파라미터

lpQuality
성공하면, 렌더링 퀄리티를 지정하는D3DRMRENDERQUALITY 멤버에의 포인터.

반환값

성공하면 D3DRM_OK, 실패하면 다음의 몇개의 에러를 돌려준다.

D3DRMERR_BADOBJECT
프로그래시브 메쉬는 무효.
D3DRMERR_BADVALUE
D3DRMRENDERQUALITY 멤버에의 포인터는 무효.

참조

IDirect3DRMProgressiveMesh::SetQuality

IDirect3DRMProgressiveMesh::GetVertexDetail

IDirect3DRMProgressiveMesh

프로그래시브 메쉬에 있는 버텍스의 수를 돌려준다.

구문

HRESULT GetVertexDetail(
  LPDWORD lpdwCount
  )

파라미터

lpdwCount
프로그래시브 메쉬에 있는 버텍스의 수가 세트 되는DWORD의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 다음의 몇개의 에러를 돌려준다.
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING

주의

버텍스의 수를 취득할 수 없는 경우에는, 이 메소드는 D3DRMERR_PENDING를 돌려준다.

IDirect3DRMProgressiveMesh::GetVertexDetailRange

IDirect3DRMProgressiveMesh

메쉬중에서 사용 가능한 최소 및 최대의 버텍스 카운트를 돌려준다.

구문

HRESULT GetVertexDetailRange(
  LPDWORD lpdwMinVertices,
  LPDWORD lpdwMaxVertices
  )

파라미터

lpdwMinVertices
버텍스의 최소수가 세트 되는DWORD값의 주소.
lpdwMaxVertices
버텍스의 최대수가 세트 되는DWORD값의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 다음의 몇개의 에러를 돌려준다.
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING

주의

버텍스 카운트를 취득할 수 없는 경우에는, 이 메소드는 D3DRMERR_PENDING를 돌려준다.

IDirect3DRMProgressiveMesh::Load

IDirect3DRMProgressiveMesh

프로그래시브 메쉬 오브젝트를 메모리, 파일, 리소스, 또는 URL로부터 로드한다. 로드는 동기식에서도 비동기식에서도 좋다.

구문

HRESULT Load(
  LPVOID lpSource,
  LPVOID lpObjID,
  D3DRMLOADOPTIONS dloLoadflags,
  D3DRMLOADTEXTURECALLBACK lpCallback,
  LPVOID lpArg
  )

파라미터

lpSource
로드하는 오브젝트의 소스의 주소. 이 소스는,dloLoadflags파라미터로 지정되고 있는 소스 플래그에 의해, 파일, 리소스, 메모리 블록, 또는 스트림의 어떤 것인가로 할 수 있다.
lpObjID
프로그래시브 메쉬인 DirectX 파일 레코드의 ID의 주소. 이것은, 캐릭터 라인 또는 UUID (dloLoadflags에 의해 정해진다)로 할 수 있다. lpObjID가 NULL의 경우,dloLoadflags는D3DRMLOAD_FIRST 가 아니면 안된다.
dloLoadflags
로드를 실행하는 방법을 기술하는D3DRMLOADOPTIONS 형의 값. 이하의 2개의 그룹의 플래그를 각각 1개씩 포함하지 않으면 안 된다.
  • DirectX 파일중의 어느 오브젝트를 로드할까를 결정하려면 , 이하의 플래그를 사용한다.
    D3DRMLOAD_BYNAME
    lpObjID파라미터는 캐릭터 라인이라고 해석한다.
    D3DRMLOAD_BYGUID
    lpObjID파라미터는 UUID라고 해석한다.
    D3DRMLOAD_FIRST
    최초로 발견된 프로그래시브 메쉬를 로드한다.
  • DirectX 파일의 소스를 결정하려면 , 이하의 플래그를 사용한다.
    D3DRMLOAD_FROMFILE
    lpSource파라미터는 로컬 파일명을 나타내는 캐릭터 라인이라고 해석한다.
    D3DRMLOAD_FROMRESOURCE
    lpSource파라미터는D3DRMLOADRESOURCE 구조체에의 포인터로서 해석한다.
    D3DRMLOAD_FROMMEMORY
    lpSource파라미터는D3DRMLOADMEMORY 구조체에의 포인터로서 해석한다.
    D3DRMLOAD_FROMURL
    lpSource파라미터는 URL로서 해석한다.

게다가 다운로드를 동기식이나 비동기식으로 하는지를 지정할 수 있다. 디폴트에서는, 로드는 동기식이며,Load호출은, 모든 데이터의 로드가 완료할 때까지, 혹은 에러가 발생할 때까지 돌아오지 않는다. 비동기식 로드를 지정하려면 , 이하의 플래그를 포함한다.

D3DRMLOAD_ASYNCHRONOUS － Load호출은 즉시 돌아온다. 로드의 진행 상태를 체크하는데,IDirect3DRMProgressiveMesh::RegisterEvents 및IDirect3DRMProgressiveMesh::GetLoadStatus 에 의해 이벤트를 사용하는 것은, 어플리케이션의 책임이 된다.

lpCallback
D3DRMLOADTEXTURECALLBACK 콜백 함수의 주소. 조우한 임의의 텍스쳐를 로드하는데 사용된다. 이 콜백 함수는, 로더가 조우한 텍스쳐명과 유저 정의의lpArg파라미터에 의해 사용된다. 새로운 thread는, 이 콜백 함수에 대해서는 생성되지 않는다. 어플리케이션이, 텍스쳐를 점차적으로 다운로드하고 싶으면, thread를 생성해, 여느 때처럼 LPDIRECT3DRMTEXTURE를 반환값으로서 돌아오지 않으면 안 된다.
lpArg
D3DRMLOADTEXTURECALLBACK 콜백 함수에게 건네지는 유저 정의 데이터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 다음의 몇개의 에러를 돌려준다.
D3DRMERR_BADPMDATA
D3DRMERR_BADFILE
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS

주의

프로그래시브 메쉬는, 초기화하지 않는 한 유효하게 안 된다. 비동기식 다운로드가 지정되고 있으면, 이 API는, 즉시 돌아와, 다른 thread가 다운로드를 실행하기 위해서 생성된다.

이 메소드,IDirect3DRMProgressiveMesh::Clone 및IDirect3DRMProgressiveMesh::Duplicate 는 모두, 프로그래시브 메쉬를 초기화한다. 오브젝트는 한 번 밖에 초기화할 수 없다. 따라서, 프로그래시브 메쉬를 클론 또는 복제하고 나서, 그 클론 또는 복제한 메쉬에 로드하는 일도, 이전에 로드한 메쉬에 로드하는 일도 할 수 없다.

IDirect3DRMProgressiveMesh::RegisterEvents

IDirect3DRMProgressiveMesh

어플리케이션이, 프로그래시브 메쉬 오브젝트에 이벤트를 등록하는 것을 가능하게 한다. 이벤트는, 적절한 조건이 만족되었을 때에 통지된다.

구문

HRESULT RegisterEvents(
  HANDLE hEvent,
  DWORD dwFlags,
  DWORD dwReserved
  )

파라미터

hEvent
필요한 조건이 만족되었을 때에 통지되는 이벤트.
dwFlags
이하의 플래그의 하나가 된다.
D3DRMPMESHEVENT_BASEMESH
베이스 메쉬의 다운로드가 완료 하면 통지되는 이벤트.
D3DRMPMESHEVENT_COMPLETE
모든 데이터의 다운로드가 완료 하면 통지되는 이벤트.
dwReserved
0이 아니면 안된다.

반환값

성공하면 D3DRM_OK, 실패하면 다음의 몇개의 에러를 돌려준다.

D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS

주의

이 메소드는, 로드의 진행 상태를 감시하기 위해서 사용할 수 있다. 이벤트는, 에러가 발생했을 경우에도 통지되므로, 어플리케이션은, 통지 후에IDirect3DRMProgressiveMesh::GetLoadStatus 메소드를 사용할 필요가 있다.

IDirect3DRMProgressiveMesh::SetDetail

IDirect3DRMProgressiveMesh

요구된 상세 레벨을 0.0으로 1.0의 사이에 정규화해 설정한다.

구문

HRESULT SetDetail(
  D3DVALUE dvVal
  )

파라미터

dvVal
상세한 요구 레벨.

반환값

성공하면 D3DRM_OK, 실패하면 다음의 몇개의 에러를 돌려준다.
D3DRMERR_BADPMDATA
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING

주의

충분한 상세 항목의 다운로드가 아직 완료하고 있지 않으면 (다만, 시간이 흐르면 사용 가능), 요구는 받아들여져,D3DRMERR_PENDING 가 돌아간다. 이 에러는 통지이며, 요구된 레벨이, 충분한 상세가 사용 가능하게 되면(자) 즉시 설정된다고 하는 것을 나타내는 것이다.

정규화한 값 0.0은 버텍스의 최소수를 나타내 (베이스 메쉬에 있는 버텍스의 수), 정규화한 값 1.0은 버텍스의 최대수를 나타낸다.

IDirect3DRMProgressiveMesh::SetFaceDetail

IDirect3DRMProgressiveMesh

요구된 면상세 레벨을 설정한다.

구문

HRESULT SetFaceDetail(
  DWORD dwCount
  )

파라미터

dwCount
요구되는 면의 수.

반환값

성공하면 D3DRM_OK, 실패하면 다음의 몇개의 에러를 돌려준다.
D3DRMERR_BADPMDATA
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING
D3DRMERR_REQUESTTOOLARGE

주의

때로는, 항상 요구된 값으로부터 1 이내인 것에도 불구하고, 프로그래시브 메쉬가 요구된 면의 수로 설정할 수 없는 것이 있다. 이것은, 분할 버텍스가 1내지 2면 더할 수가 있기 때문이다. 예를 들어,SetFaceDetail(20)를 사용하면(자), 프로그래시브 메쉬는 면의 상세를 19또는 21인 만큼 밖에 설정 할 수 없을 지도 모르다. 프로그래시브 메쉬에 있는 면의 실제의 수는, 항상IDirect3DRMProgressiveMesh::GetFaceDetail 메소드를 사용해 취득할 수가 있다.

충분한 상세 항목의 다운로드가 아직 완료하고 있지 않으면(다만, 시간이 흐르면 사용 가능), 요구는 받아들여져, D3DRMERR_PENDING가 돌아간다. 이 에러는, 통지이며, 요구된 레벨이, 충분한 상세가 사용 가능하게 되면(자) 즉시 설정된다고 하는 것을 나타내는 것이다. 요구되고 있는 상세 레벨이, 프로그래시브 메쉬로 사용 가능한 상세 레벨보다 크면, D3DRMERR_REQUESTTOOLARGE가 돌아간다.

참조

IDirect3DRMProgressiveMesh::GetFaceDetail

IDirect3DRMProgressiveMesh::SetMinRenderDetail

IDirect3DRMProgressiveMesh

0.0(최소 상세 레벨)에서 1.0(최대 상세 레벨)의 범위에서, 로드안에 렌더링 하는 상세한 최소 레벨을 설정한다. 보통, 프로그래시브 메쉬는, 베이스 메쉬가 사용 가능하게 된( 및 메쉬가 장면 그래프중에 존재하게 된) 다음에 렌더링 된다.

구문

HRESULT SetMinRenderDetail(
  D3DVALUE dvCount
  )

파라미터

dvCount
요구되고 있는 최소 상세.

반환값

성공하면 D3DRM_OK, 실패하면 다음의 몇개의 에러를 돌려준다.
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING
D3DRMERR_REQUESTTOOLARGE
D3DRMERR_REQUESTTOOSMALL

주의

이 API는, 로드안에 렌더링 되는 면 또는 버텍스의(베이스 메쉬보다 크다) 최소수를 설정한다.

이후의IDirect3DRMProgressiveMesh::SetDetail ,IDirect3DRMProgressiveMesh::SetFaceDetail , 또는IDirect3DRMProgressiveMesh::SetVertexDetail 호출은 언제라도, 이 메소드보다 우선된다.

IDirect3DRMProgressiveMesh::SetQuality

IDirect3DRMProgressiveMesh

Direct3DRMProgressiveMesh 오브젝트의 렌더링 퀄리티를 설정한다.

구문

HRESULT SetQuality(
  D3DRMRENDERQUALITY quality
  );

파라미터

quality
사용하는 새로운 렌더링 퀄리티를 지정하는D3DRMRENDERQUALITY 열거형의 멤버.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

오브젝트 퀄리티에는, 3개의 컴퍼넌트가 있다. 즉, 쉐이딩 모드 (플랫 또는 굿 로. 폰은 이행 되지 않고, 디폴트로 gouraud shading가 된다), 조명 타입 (온 또는 오프) 및 전부 칠해 모드 (포인트, 와이어 프레임 또는 솔리드)이다.

디바이스의 퀄리티를 설정하려면 ,IDirect3DRMDevice3::SetQuality 를 이용한다. 디폴트로, 디바이스 퀄리티는 D3DRMRENDER_FLAT (flat shading, 조명 온, 및 솔리드 전부 칠해)이다.

YDirect3DRMProgressiveMesh 오브젝트의 퀄리티를 설정하려면 ,SetQuality메소드를 이용한다. 디폴트로, Direct3DRMProgressiveMesh 오브젝트의 퀄리티는 D3DRMRENDER_GOURAUD (gouraud shading, 조명 온, 및 솔리드 전부 칠해)이다.

힌트: gouraud shading는, 상세 레벨을 빈번하게 또는 재빠르게 변경하는 프로그래시브 메쉬 오브젝트에 대해, 보다 좋은 퍼포먼스를 얻을 수 있다.

Direct3D 보관 유지 모드는, 디바이스나 오브젝트의 각각의 컴퍼넌트에 대한 현재의 설정 중(안)에서 가장 저위의 퀄리티로, 오브젝트에 렌더링을 실시한다. 예를 들어, 오브젝트의 현재의 퀄리티 설정이 D3DRMRENDER_GOURAUD로, 디바이스가 D3DRMRENDER_FLAT이라고, 오브젝트는 flat shading, 솔리드 전부 칠해, 및 조명 온으로 렌더링 된다.

오브젝트의 현재의 퀄리티 설정이 D3DRMSHADE_GOURAUD|D3DRMLIGHT_OFF|D3DRMFILL_WIREFRAME로, 디바이스의 퀄리티 설정이 D3DRMSHADE_FLAT|D3DRMLIGHT_ON|D3DRMFILL_POINT이라고, 오브젝트는 flat shading, 조명 오프, 및 포인트 전부 칠해 모드로 렌더링 된다.

이러한 룰은, Direct3DRMMeshBuilder3 오브젝트 및 Direct3DRMProgressiveMesh 오브젝트에 적용된다. 그러나, Direct3DRMMesh 오브젝트는 이러한 룰에 따르지 않다. 메쉬 오브젝트는 디바이스의 퀄리티 설정을 무시해, 그룹 퀄리티 설정을 이용한다(디폴트로 D3DRMRENDER_GOURAUD).

참조

IDirect3DRMProgressiveMesh::GetQuality

IDirect3DRMProgressiveMesh::SetVertexDetail

IDirect3DRMProgressiveMesh

요구된 버텍스 상세 레벨을 설정한다.

구문

HRESULT SetVertexDetail(
  DWORD dwCount
  )

파라미터

dwCount
요구되고 있는 버텍스의 수.

반환값

성공하면 D3DRM_OK, 실패하면 다음의 몇개의 에러를 돌려준다.
D3DRMERR_BADPMDATA
D3DRMERR_CONNECTIONLOST
D3DRMERR_INVALIDOBJECT
D3DRMERR_INVALIDPARAMS
D3DRMERR_PENDING
D3DRMERR_REQUESTTOOLARGE

주의

충분한 상세 항목의 다운로드가, 아직 완료하고 있지 않으면(다만, 시간이 지나면 사용 가능), 요구는 받아들여져, D3DRMERR_PENDING가 돌아간다. 이 에러는 통지이며, 요구된 레벨이, 충분한 상세가 사용 가능하게 되면(자) 즉시 설정된다고 하는 것을 나타내는 것이다. 요구되고 있는 상세 레벨이, 프로그래시브 메쉬로 사용 가능한 상세 레벨보다 크면, D3DRMERR_REQUESTTOOLARGE가 돌아간다.

참조

IDirect3DRMProgressiveMesh::GetVertexDetail


IDirect3DRMShadow2

어플리케이션은,Direct3DRMShadow2오브젝트 및Direct3DRMShadow오브젝트를 초기화하기 위해서IDirect3DRMShadow2인터페이스 및IDirect3DRMShadow인터페이스의 메소드를 각각 사용한다. 어플리케이션이IDirect3DRM3::CreateShadow 메소드를 사용할 때는, 이 초기화는 불필요하다. 초기화가 필요한 것은,IDirect3DRM3::CreateObject 메소드를 사용해 그림자를 생성하는 경우 뿐이다. IDirect3DRM3::CreateObject 를 호출하는 어플리케이션은, 다음에IDirect3DRMShadow2::Init 메소드를 호출해, 그림자를 초기화한다.

IDirect3DRMShadow2는, 비주얼, 조명, 프레인, 옵션의 그림자의 파라미터를 생성 후로 변경 가능하게 하는 것으로,IDirect3DRMShadow의 기능을 확장한다. IDirect3DRMShadow2::SetOptions 에 의해, 투명 블렌딩이 유효한 때에 비주얼 효과를 배제하는 옵션을 세트 할 수 있다. IDirect3DRMShadow2는,IDirect3DRMShadow가 제공하는Init 메소드에 가세해,SetVisual ,GetVisual ,SetLight ,GetLight ,SetPlane ,GetPlane ,SetOptions ,GetOptions 메소드를 제공한다.

IDirect3DRMShadow2인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.
초기화 | Init
파라미터의 설정과 취득 | GetLight
 | GetOptions
 | GetPlane
 | GetVisual
 | SetLight
 | SetOptions
 | SetPlane
 | SetVisual

모든 COM 인터페이스와 같이,IDirect3DRMShadow2및IDirect3DRMShadow인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

게다가IDirect3DRMShadow2및IDirect3DRMShadow인터페이스는,IDirect3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMShadow2오브젝트는,IDirect3DRM3::CreateShadow 메소드의 사용에 의해 취득된다.

IDirect3DRMShadow2::GetLight

IDirect3DRMShadow2

그림자의 생성시에 사용하는 조명 소스를 취득한다. 조명을 그림자에 관련지을 수 있지 않은 경우, 에러가 돌려주어진다.

구문

HRESULT GetLight(
  LPDIRECT3DRMLIGHT  *lplpDirect3DRMLight);

파라미터

lplpDirect3DRMLight
조명 소스를 받는 포인터.

반환값

다음의 값중 1개를 돌려준다.
DD_OK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMShadow2::GetOptions

IDirect3DRMShadow2

그림자의 옵션 플래그를 취득한다.

구문

HRESULT GetOptions(
  LPDWORD pdwOptions);

파라미터

pdwOptions
현재의 그림자의 옵션을 취득하는 포인터. 유효한 플래그는 다음과 같다.
D3DRMSHADOW_TRUEALPHA
진정한 알파가 유효한 때에 렌더링 했을 경우, 비주얼 효과를 가지지 않는 그림자를 생성 한다.

반환값

다음의 값중 1개를 돌려준다.
DD_OK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMShadow2::GetPlane

IDirect3DRMShadow2

그림자의 프레인을 취득한다. 포인트는 그림자의 프레임을 기점으로 한다. 법선은 월드 공간안에 있다.

구문

HRESULT SetPlane(
  LPD3DVALUE pdvPX,
  LPD3DVALUE pdvPY,
  LPD3DVALUE pdvPZ,
  LPD3DVALUE pdvNX,
  LPD3DVALUE pdvNY,
  LPD3DVALUE pdvNZ);

파라미터

pdvPX, pdvPY, pdvPZ
그림자의 프레임을 기점으로 하는 그림자의 프레인 위에의 포인트의 x, y, z값을 받는 포인터. 이 값은,D3DVALUE 데이터 타입에의 포인터로서 지정된다.
pdvNX, pdvNY, pdvNZ
그림자의 프레인에 대한 법선의 x, y, z값을 월드 공간 벡터로서 받는 포인터. 이 값은,D3DVALUE 데이터 타입에의 포인터로서 지정된다.

반환값

다음의 값중 1개를 돌려준다.
DD_OK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMShadow2::GetVisual

IDirect3DRMShadow2

그림자를 생성 하는 비주얼을 취득한다.

구문

HRESULT GetVisual(
  LPDIRECT3DRMVISUAL  *lplpDirect3DRMVisual);

파라미터

lplpDirect3DRMVisual
그림자를 생성 하는 비주얼을 받는 포인터.

반환값

다음의 값중 1개를 돌려준다.
DD_OK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMShadow2::Init

IDirect3DRMShadow2

Direct3DRMShadow2 오브젝트를 초기화한다.

구문

HRESULT Init(
  LPUNKNOWN pUnk,
  LPDIRECT3DRMLIGHT lpD3DRMLight,
  D3DVALUE px,
  D3DVALUE py,
  D3DVALUE pz,
  D3DVALUE nx,
  D3DVALUE ny,
  D3DVALUE nz);

파라미터

pUnk
그림자를 붙이는 오브젝트에의 포인터.
lpD3DRMLight
그림자의 바탕으로 되는 조명을 제공하는Direct3DRMLight오브젝트에의 포인터.
px, py, pz
그림자를 붙일 수 있는 프레인 위에의점의 좌표.
nx, ny, nz
그림자를 붙일 수 있는 프레인 위에의법선 벡터의 좌표.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

그림자를 초기화하기 위해(때문에) 이 메소드를 호출한 후,IDirect3DRMFrame3::AddVisual 를 사용해, 그림자를 생성 하는 비주얼이 존재하는 프레임과 같은 프레임에 그림자를 추가한다.

IDirect3DRMShadow2::SetLight

IDirect3DRMShadow2

그림자의 생성시에 사용하는 조명을 설정한다.

구문

HRESULT SetLight(
  LPDIRECT3DRMLIGHT lpDirect3DRMLight,
  DWORD dwFlags);

파라미터

lpDirect3DRMLight
그림자의 생성시에 사용하는 조명.
dwFlags
예약이 끝난 상태. 0이 아니면 안된다.

반환값

다음의 값중 1개를 돌려준다.
DD_OK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMShadow2::SetOptions

IDirect3DRMShadow2

그림자의 옵션 플래그를 설정한다.

구문

HRESULT SetOptions(
  DWORD dwOptions);

파라미터

dwOptions
그림자의 옵션. 유효한 플래그는 다음과 같다.
D3DRMSHADOW_TRUEALPHA
투명 블렌딩 (알파 블렌딩)이 유효한 때에 비주얼 효과를 가지지 않는 그림자를 생성 한다. IDirect3DRMDevice3::SetRenderMode 를 호출해, 투명 블렌딩을 유효하게 한다.

반환값

다음의 값중 1개를 돌려준다.
DD_OK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMShadow2::SetPlane

IDirect3DRMShadow2

그림자의 프레인을 설정한다. 포인트는 그림자의 프레임을 기점으로 한다. 법선은 월드 공간안에 있다.

구문

HRESULT SetPlane(
  D3DVALUE dvPX,
  D3DVALUE dvPY,
  D3DVALUE dvPZ,
  D3DVALUE dvNX,
  D3DVALUE dvNY,
  D3DVALUE dvNZ,
  DWORD dwFlags);

파라미터

dvPX, dvPY, dvPZ
D3DVALUE 데이터 타입으로 지정한 그림자의 프레임을 기점으로 하는, 그림자의 프레인 위에의 포인트.
dvNX, dvNY, dvNZ
D3DVALUE 데이터 타입으로서 지정한, 월드 공간 벡터로서의 그림자의 프레인에 대한 법선.
dwFlags
예약이 끝난 상태. 0이 아니면 안된다.

반환값

다음의 값중 1개를 돌려준다.
DD_OK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMShadow2::SetVisual

IDirect3DRMShadow2

그림자를 생성 하는 비주얼을 설정한다.

구문

HRESULT SetVisual(
    LPDIRECT3DRMVISUAL lpDirect3DRMVisual,
    DWORD dwFlags);

파라미터

lpDirect3DRMVisual
그림자를 생성 하는 비주얼.
dwFlags
예약이 끝난 상태. 0이 아니면 안된다.

반환값

다음의 값중 1개를 돌려준다.
DD_OK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.


IDirect3DRMTexture3

Microsoft DirectX version 6.0은,IDirect3DRMTexture3인터페이스를 도입하고 있다. IDirect3DRMTexture3은, 그것이 치환하는 구의IDirect3DRMTexture2과IDirect3DRMTexture인터페이스를 확장해, 텍스쳐 관리에 대하는 것보다 세련된 제어를 가능하게 한다. 테키스체 관리의 개요는, 「텍스쳐」를 참조할것. Direct3D 보관 유지 모드 인터페이스의 이력에 대해서는, 「인터페이스의 변경점」을 참조할것.

IDirect3DRMTexture3는, 텍스쳐의 변경 리젼을 지정 가능하게 하는 것으로,Changed 메소드의 기능을 확장한다. 또, 이것은, 텍스쳐 관리 캐싱 메소드의GetCacheOptions 와SetCacheOptions 도 제공한다. IDirect3DRMTexture3가 제공하는 그 외의 새로운 메소드로서GetSurface ,SetDownSampleCallback , 및<SetValidationCallback 가 있다.

구의IDirect3DRMTexture2이 추가해,IDirect3DRMTexture3도 지원 하기 이전의 새로운 메소드에는,InitFromResource2 가 포함된다. 이것은, DLL 및 현재의 실행 파일을 제외한 실행 가능 프로그램으로부터 리소스를 로드할 수 있도록(듯이) 한다. InitFromImage 메소드는, 메모리중의 이미지로부터 텍스쳐를 생성한다. 이 메소드는,IDirect3DRM3::CreateTexture 메소드와 동등하다. GenerateMIPMap 메소드는, 소스 이미지로부터밉맵을 만들어 낸다.

텍스쳐를 생성 할 경우에 불필요한 지연을 피하기 (위해)때문에, 재이용하는 텍스쳐는 보관 유지해 두어, 필요하게 될 때마다 생성 하지 않아도 되도록(듯이) 한다. 최적인 퍼포먼스를 얻으려면 , 사용하는 디바이스의 지원 하는 텍스쳐 표면 포맷을 사용한다. 이것에 의해, 텍스쳐를 생성 하고 나서 변경할 경우에, 수고가 걸리는 포맷 변환을 회피할 수가 있다.

IDirect3DRM3::LoadTexture 에 의해 텍스쳐 콜백 함수에 로드 된 텍스쳐에의 참조를 보관 유지하는 방법을 나타내는 예는,IDirect3DRM3::LoadTexture의 주의를 참조할것.

IDirect3DRMTexture3인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.
색 | GetColors
 | SetColors
디칼 | GetDecalOrigin
 | GetDecalScale
 | GetDecalSize
 | GetDecalTransparency
 | GetDecalTransparentColor
 | SetDecalOrigin
 | SetDecalScale
 | SetDecalSize
 | SetDecalTransparency
 | SetDecalTransparentColor
이미지 | GetImage
초기화 | InitFromFile
 | InitFromImage
 | InitFromResource2
 | InitFromSurface
밉맵 생성 | GenerateMIPMap
그 외 | GetCacheOptions
 | GetSurface
 | SetCacheOptions
 | SetDownsampleCallback
 | SetValidationCallback
렌더러 통지 | Changed
쉐이딩 | GetShades
 | SetShades

모든 COM 인터페이스와 같이,IDirect3DRMTexture3인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

게다가IDirect3DRMTexture3인터페이스는,IDirect3DRMObject 인터페이스로부터 이하의 메소드를 계승한다.
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

IDirect3DRMTexture3 오브젝트를 생성 하려면 ,IDirect3DRM3::CreateTexture 또는IDirect3DRM3::CreateTextureFromSurface 를 호출한다.

IDirect3DRMTexture3::Changed

IDirect3DRMTexture3

어플리케이션으로 텍스쳐의 어느 리젼을 변경하는지를 지정 가능하게 한다.

구문

HRESULT Changed(
  DWORD dwFlags,
  DWORD dwcRects,
  LPRECT pRects);

파라미터

dwFlags
다음의 플래그를 정의한다.
D3DRMTEXTURE_CHANGEDPIXELS
픽셀값이 변경된 것을 나타낸다.
D3DRMTEXTURE_CHANGEDPALETTE
팔레트가 변경된 것을 나타낸다.
D3DRMTEXTURE_INVALIDATEONLY
텍스쳐-존이 무효가 되었지만, 어플리케이션으로 갱신할 필요가 없는 것을 나타낸다. 이것은, Direct3D 보관 유지 모드가 텍스쳐를 렌더링 하기 전에, 어플리케이션을 호출해, 1차 소스를 갱신한다. 이 콜백은SetValidationCallback 에 의해 세트 된다.
dwcRects
pRects가 포인트 하는RECT구조체의 수. 이 값이 0으로,dwFlags에 D3DRMTEXTURE_CHANGEDPIXELS 또는 D3DRMTEXTURE_INVALIDATEONLY가 포함되는 경우, 텍스쳐 전체가 갱신된다.
pRects
변경된 픽셀의 리젼을 기술하는RECT구조체의 배열. dwFlags에 D3DRMTEXTURE_CHANGEDPIXELS 또는 D3DRMTEXTURE_INVALIDATEONLY가 포함되는 경우,pRects파라미터만이 유효하다.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입된 이 메소드는, 구의IDirect3DRMTexture::Changed메소드를 치환한다. 이 구의 메소드에는, 어플리케이션이 텍스쳐의 픽셀 또는 팔레트를 변경했는지 어떠했는지를 나타내는 2살의 불 파라미터가 있다.

IDirect3DRMTexture3::GenerateMIPMap

IDirect3DRMTexture3

단일의 이미지 소스로부터 밉맵을 생성한다.

구문

HRESULT GenerateMIPMap(
  DWORD dwFlags
  );

파라미터

dwFlags
0을 세트 할 필요가 있다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, 텍스쳐의 생성 후는 언제라도 호출할 수가 있다. 이 메소드는, 레벨간의 쌍일차 필터링에 의해 소스 이미지의 밉맵을 1×1의 해상도까지 생성할 수 있다. 밉맵이 생성되면(자), 맵은 언제라도 사용 가능해,IDirect3DRMTexture3::Changed 를 호출해, 갱신할 수가 있다. MIP Mapping를 사용하는 경우에는,IDirect3DRMDevice3::SetTextureQuality 를 사용해, 텍스쳐의 퀄리티를 D3DRMTEXTURE_MIPNEAREST, D3DRMTEXTURE_MIPLINEAR, D3DRMTEXTURE_LINEARMIPNEAREST, 또는 D3DRMTEXTURE_LINEARMIPLINEAR로 변경하는 것을 잊어서는 안된다. 특별한 밉맵 레벨은, 텍스쳐 퀄리티가 MIP Mapping형을 포함해, 한편 하드웨어 디바이스가 MIP Mapping를 지원 하지 않는 한, 하드웨어 디바이스의 비디오 메모리에 저장 되지 않는다.

참조

「밉맵」

IDirect3DRMTexture3::GetCacheOptions

IDirect3DRMTexture3

텍스쳐 메모리가 제한되고 있는 경우에, 텍스쳐 관리로 현재의 텍스쳐를 어떻게 처리할까에 관한 정보를 취득한다.

구문

HRESULT GetCacheOptions(
  LPLONG lplImportance,
  LPDWORD lpdwFlags);

파라미터

lplImportance
텍스쳐의 상대적인 중요도를 나타내는 부호 첨부의 값. 디폴트는 0이다. 값이 크면, 중요도가 높은 일을 나타낸다. 이 값을 사용해, 텍스쳐 메모리가 제한되고 있는 경우에 어느 텍스쳐를 마지막으로 다운 샘플 하는지를 계산한다.
lpdwFlags
현재의 텍스쳐에 관한 텍스쳐 관리 시스템을 제어하는 플래그. 현재 정의되고 있는 플래그는, 다음과 같다.
D3DRMTEXTURE_FORCERESIDENT
텍스쳐를(하드웨어 시나리오중의) 비디오 메모리 로 유지하는 것을 나타낸다.
D3DRMTEXTURE_STATIC
텍스쳐가 변함없는 것을 나타낸다. 어플리케이션은, 결코Changed 메소드를 사용하지 않는다.
D3DRMTEXTURE_DOWNSAMPLEPOINT
텍스쳐의 다운 샘플시에 포인트 필터링을 사용하는 것을 나타낸다.
D3DRMTEXTURE_DOWNSAMPLEBILINEAR
텍스쳐의 다운 샘플시에 쌍일차 필터링을 사용하는 것을 나타낸다.
D3DRMTEXTURE_DOWNSAMPLEREDUCEDEPTH
텍스쳐의 다운 샘플시에 픽셀 깊이가 감소하는 것을 나타낸다.
D3DRMTEXTURE_DOWNSAMPLENONE
텍스쳐를 결코 다운 샘플 하지 않는 것을 나타낸다.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMTexture3::GetColors

IDirect3DRMTexture3

Direct3DRMTexture2 오브젝트를 렌더링 하기 위해서 사용하는 색의 최대수를 취득한다.

구문

DWORD GetColors( );

반환값

색의 수를 돌려준다.

주의

이 메소드는, Direct3DRMTexture2 오브젝트가 생성 된 원의 이미지중의 색의 수는 아니고, Direct3DRMTexture2 오브젝트가 양자화된 색의 수를 돌려준다. 따라서, 반환값의 색의 수는 보통,IDirect3DRM3::SetDefaultTextureColors 메소드를 호출해 설정한 색에 일치한다. 다만,IDirect3DRMTexture3::SetColors 메소드를 명시적으로 호출해 Direct3DRMTexture2 오브젝트의 색을 변경했을 경우는, 그렇게는 안 된다.

참조

IDirect3DRMTexture3::SetColors

IDirect3DRMTexture3::GetDecalOrigin

IDirect3DRMTexture3

디칼의 현재의 원점을 취득한다.

구문

HRESULT GetDecalOrigin(
  LONG  *lplX,
  LONG  *lplY
  );

파라미터

lplX, lplY
메소드가 돌아왔을 때, 디칼의 원점이 세트 되는 변수의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMTexture3::SetDecalOrigin

IDirect3DRMTexture3::GetDecalScale

IDirect3DRMTexture3

지정의디칼의 스케일링 프로퍼티를 취득한다.

구문

DWORD GetDecalScale( );

반환값

성공하면 스케일링 프로퍼티, 실패하면―1을 돌려준다.

참조

IDirect3DRMTexture3::SetDecalScale

IDirect3DRMTexture3::GetDecalSize

IDirect3DRMTexture3

디칼의 사이즈를 취득한다.

구문

HRESULT GetDecalSize(
  D3DVALUE *lprvWidth,
  D3DVALUE *lprvHeight
  );

파라미터

lprvWidth, lprvHeight
메소드가 돌아왔을 때, 디칼의 폭과 높이가 세트 되는 변수의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMTexture3::SetDecalSize

IDirect3DRMTexture3::GetDecalTransparency

IDirect3DRMTexture3

디칼의 투명 프로퍼티를 취득한다.

구문

BOOL GetDecalTransparency( );

반환값

디칼이 투명한 색을 가지고 있으면(자) TRUE, 그렇지 않으면 FALSE를 돌려준다.

참조

IDirect3DRMTexture3::SetDecalTransparency

IDirect3DRMTexture3::GetDecalTransparentColor

IDirect3DRMTexture3

디칼의 투명한 색을 취득한다.

구문

D3DCOLOR GetDecalTransparentColor( );

반환값

투명한 색의 값을 돌려준다.

참조

IDirect3DRMTexture3::SetDecalTransparentColor

IDirect3DRMTexture3::GetImage

IDirect3DRMTexture3

텍스쳐를 생성 했을 때에 사용한 이미지의 주소를 돌려준다.

구문

D3DRMIMAGE *GetImage( );

반환값

현재의 Direct3DRMTexture2 오브젝트를 생성하는데 사용한D3DRMIMAGE 구조체의 주소를 돌려준다.

IDirect3DRMTexture3::GetShades

IDirect3DRMTexture3

렌더링시에 텍스쳐중의 각 색에 대해서 사용되는 쉐이드수를 돌려준다.

구문

DWORD GetShades( );

반환값

쉐이드수를 돌려준다.

참조

IDirect3DRMTexture3::SetShades

IDirect3DRMTexture3::GetSurface

IDirect3DRMTexture3

텍스쳐를 생성 하기 위해서 사용한 DirectDraw 표면을 취득한다. 이것은,CreateTextureFromSurface또는InitFromSurface가 텍스쳐의 생성에 사용되었을 경우에게만, 표면을 취득한다.

구문

HRESULT GetSurface(
  DWORD dwFlags,
  LPDIRECTDRAWSURFACE *lplpDDS);

파라미터

dwFlags
플래그값. 0이 아니면 안된다.
lplpDDS
대응하는 DirectDraw 표면의 인터페이스에의 포인터를 받는 변수의 주소. 인터페이스의참조 카운트는, 인터페이스가 호출해 바탕으로 건네받기 전에 인크리먼트(increment) 되는 것에 주의 해야 한다.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_NOTCREATEDFROMDDS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMTexture3::InitFromFile

IDirect3DRMTexture3

지정 파일중의 정보를 사용해 Direct3DRMTexture2 오브젝트를 초기화한다.

구문

HRESULT InitFromFile(
  LPCSTR filename
  );

파라미터

filename
텍스쳐의 초기화 정보를 취득하는 파일을 지정하는 캐릭터 라인.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

IDirect3DRM3::CreateTexture 또는IDirect3DRM3::CreateTextureFromSurface 메소드를 사용해, 초기화하는 Direct3DRMTexture2 오브젝트를 생성 해 두지 않으면 안 된다.

참조

IDirect3DRMTexture3::InitFromImage , IDirect3DRMTexture3::InitFromResource2 , IDirect3DRMTexture3::InitFromSurface

IDirect3DRMTexture3::InitFromImage

IDirect3DRMTexture3

메모리중의 이미지로부터 텍스쳐를 초기화한다.

구문

HRESULT InitFromImage(
  LPD3DRMIMAGE lpImage
  );

파라미터

lpImage
텍스쳐의 소스를 기술하는D3DRMIMAGE 구조체의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

IDirect3DRM3::CreateTexture 또는IDirect3DRM3::CreateTextureFromSurface 메소드를 사용해, 초기화하는 IDirect3DRMTexture3 오브젝트를 생성 해 두지 않으면 안 된다.

참조

IDirect3DRMTexture3::InitFromFile , IDirect3DRMTexture3::InitFromResource2 , IDirect3DRMTexture3::InitFromSurface

IDirect3DRMTexture3::InitFromResource2

IDirect3DRMTexture3

지정의 리소스로부터 Direct3DRMTexture2 오브젝트를 초기화한다.

구문

HRESULT InitFromResource2(
  HModule hModule,
  LPCTSTR strName,
  LPCTSTR strType
  );

파라미터

hModule
지정의 리소스의 핸들.
strName
텍스쳐를 초기화하는데 사용하는 리소스명.
strType
텍스쳐를 초기화하는데 사용하는 리소스의 타입명. 텍스쳐는, RT_BITMA 및 RT_RCDATA 리소스 타입 또는 유저 정의 타입안에 저장 할 수 있다. 리소스 타입이 유저 정의되고 있으면, 이 메소드는, 그 리소스 모듈 핸들, 리소스명, 및 리소스 타입을FindResource Win32 API에 건네준다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

IDirect3DRM3::CreateTexture 또는IDirect3DRM3::CreateTextureFromSurface 메소드를 사용해, 초기화하는 IDirect3DRMTexture3 오브젝트를 생성 해 두지 않으면 안 된다.

참조

IDirect3DRMTexture3::InitFromFile , IDirect3DRMTexture3::InitFromImage , IDirect3DRMTexture3::InitFromSurface

IDirect3DRMTexture3::InitFromSurface

IDirect3DRMTexture3

지정한 DirectDraw 표면으로부터의 데이터를 사용해, Direct3DRMTexture2 오브젝트를 초기화한다. 이 메소드는,IDirect3DRMTexture3::InitFromSurface와 같은 기능을 실행한다.

구문

HRESULT InitFromSurface(
  LPDIRECTDRAWSURFACE lpDDS
  );

파라미터

lpDDS
초기화 정보를 취득하는 DirectDraw 표면의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

DirectDraw 표면으로부터 텍스쳐를 생성 하는 경우, 표면을 시스템 메모리중에 생성 하는 것이 최선이다. 이것에 의해, 소프트웨어 디바이스의 최적인 퍼포먼스가 가능하게 되어, Direct3D 보관 유지 모드가 하드웨어 디바이스에 대해서 비디오 메모리의 사용을 보다 효율적으로 관리할 수 있게 된다.

참조

IDirect3DRMTexture3::InitFromFile , IDirect3DRMTexture3::InitFromImage , IDirect3DRMTexture3::InitFromResource2

IDirect3DRMTexture3::SetCacheOptions

IDirect3DRMTexture3

텍스쳐 메모리가 제한되고 있는 경우에, 텍스쳐 관리로 이 텍스쳐를 어떻게 처리할까에 관한 정보를 제공한다.

구문

HRESULT SetCacheOptions(
  LONG lImportance,
  DWORD dwFlags);

파라미터

lImportance
텍스쳐의 상대적인 중요도를 나타내는 부호 첨부의 값. 디폴트는 0이다. 값이 크면, 중요도가 높은 일을 나타낸다. 이 값을 사용해, 텍스쳐 메모리가 제한되고 있는 경우에 어느 텍스쳐를 마지막으로 다운 샘플 하는지를 계산한다.
dwFlags
현재의 텍스쳐에 관한 텍스쳐 관리 시스템을 제어하는 플래그. 현재 정의되고 있는 플래그는, 다음과 같다.
D3DRMTEXTURE_FORCERESIDENT
텍스쳐를(하드웨어 시나리오중의) 비디오 메모리 로 유지하는 것을 나타낸다.
D3DRMTEXTURE_STATIC
텍스쳐가 변함없는 것을 나타낸다.
D3DRMTEXTURE_DOWNSAMPLEPOINT
텍스쳐의 다운 샘플시에 포인트 필터링을 사용하는 것을 나타낸다.
D3DRMTEXTURE_DOWNSAMPLEBILINEAR
텍스쳐의 다운 샘플시에 쌍일차 필터링을 사용하는 것을 나타낸다.
D3DRMTEXTURE_DOWNSAMPLEREDUCEDEPTH
텍스쳐의 다운 샘플시에 픽셀 깊이가 감소하는 것을 나타낸다. 하위 비트의 깊이가 사용 가능하지 않으면, 텍스쳐의 사이즈가 감소한다.
D3DRMTEXTURE_DOWNSAMPLENONE
텍스쳐를 결코 다운 샘플 하지 않는 것을 나타낸다. 디폴트값은 D3DRMTEXTURE_DOWNSAMPLEPOINT이다.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMTexture3::SetColors

IDirect3DRMTexture3

Direct3DRMTexture2 오브젝트를 렌더링 하는데 사용하는 색의 최대수를 설정한다. 이 메소드는, 램프 컬러 모델에 한정해 필요하다.

구문

HRESULT SetColors(
  DWORD ulColors
  );

파라미터

ulColors
색의 수. 디폴트값은 8이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMTexture3::GetColors

IDirect3DRMTexture3::SetDecalOrigin

IDirect3DRMTexture3

디칼의 좌상으로부터의 오프셋(offset)로서 디칼의 원점을 설정한다.

구문

HRESULT SetDecalOrigin(
  LONG lX,
  LONG lY
  );

파라미터

lX, lY
디칼 좌표에서의 디칼의 새로운 원점. 디폴트의 원점은[0, 0]이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

디칼 원점은, 렌더링시에 그 프레임의 위치에 맵 된다. 예를 들어, 십자의 디칼의 원점은, 디칼의 중점으로 설정되어 아래로 향한 화살표의 원점은, 저변에 따른 중점으로 설정된다.

이 메소드는, Direct3DRMTextureInterpolator 오브젝트에 디칼 원점을 추가하기 위해서도 사용한다.

참조

IDirect3DRMTexture3::GetDecalOrigin

IDirect3DRMTexture3::SetDecalScale

IDirect3DRMTexture3

디칼의 스케일링 프로퍼티를 설정한다.

구문

HRESULT SetDecalScale(
  DWORD dwScale
  );

파라미터

dwScale
이 파라미터가 TRUE의 경우, 디칼을 스케일링 하는 경우에 깊이가 고려되어 디칼이 장면의 프레임 위에의 텍스쳐인 경우, 뷰아로부터 멀리 있으면 작고, 뷰아의 근처에 있으면 크고 스케일링 된다. FALSE의 경우, 깊이 정보는 무시되어 디칼은 뷰아로부터의 원근에 관계없이 같은 사이즈가 된다. 디폴트값은 TRUE이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMTexture3::GetDecalScale

IDirect3DRMTexture3::SetDecalSize

IDirect3DRMTexture3

장면안의디칼의 깊이에 따라, 디칼이 스케일링 되는 경우에, 사용되는 디칼의 사이즈를 설정한다.

구문

HRESULT SetDecalSize(
  D3DVALUE rvWidth,
  D3DVALUE rvHeight
  );

파라미터

rvWidth, rvHeight
모델 좌표에 있어서의, 디칼의 새로운 폭과 높이. 디폴트 사이즈는,[1, 1]이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, Direct3DRMTextureInterpolator 오브젝트에 디칼 사이즈 키를 추가하기 위해서도 사용한다.

참조

IDirect3DRMTexture3::GetDecalSize

IDirect3DRMTexture3::SetDecalTransparency

IDirect3DRMTexture3

디칼의 투명 프로퍼티를 설정한다.

구문

HRESULT SetDecalTransparency(
  BOOL bTransp
  );

파라미터

bTransp
이 파라미터가 TRUE의 경우, 디칼은 투명의 색을 가진다. FALSE의 경우, 불투명의 색을 가진다. 디폴트값은 FALSE이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMTexture3::GetDecalTransparency

IDirect3DRMTexture3::SetDecalTransparentColor

IDirect3DRMTexture3

디칼의 투명한 색을 설정한다.

구문

HRESULT SetDecalTransparentColor(
  D3DCOLOR rcTransp
  );

파라미터

rcTransp
새로운 투명한 색. 디폴트의 투명한 색은 흑이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, Direct3DRMTextureInterpolator 오브젝트에 디칼의 투명색키를 추가하기 위해서도 사용한다.

참조

IDirect3DRMTexture3::GetDecalTransparentColor

IDirect3DRMTexture3::SetDownsampleCallback

IDirect3DRMTexture3

텍스쳐의 다운 샘플시에, D3DRM 편입 메소드를 사용하는 것이 아니라, 텍스쳐 관리가 사용하는 콜백을 지정한다. 콜백이 벌써 지정되고 있는 경우, 새로운 콜백은 구의 것을 치환한다. 콜백이 NULL라면, 현재의 콜백은 삭제된다.

구문

typedef HRESULT (CDECL *D3DRMDOWNSAMPLECALLBACK)
  (LPVOID pArg,
  LPDIRECTDRAWSURFACE pDDSSrc,
  LPDIRECTDRAWSURFACE pDDSDst);

HRESULT SetDownsampleCallback(
  LPDIRECT3DRMTEXTURE3 lpDirect3DRMTexture,
  D3DRMDOWNSAMPLECALLBACK pCallback,
  LPVOID pArg);

파라미터

pCallback
다운 샘플링을 실행하기 위해서 불려 가는 콜백 함수에의 포인터. 값NULL는, 현재의 콜백이 삭제되는 것을 나타낸다.
pArg
호출시에 콜백에게 건네지는 어플리케이션 고유의 데이터.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

다운 샘플링은, 비디오 메모리가 overload가 되어, 텍스쳐 표면의 사이즈를 삭감할 필요가 있을 때 실행된다. Direct3D 보관 유지 모드에서는, DirectDraw 블록 전송이나 쌍일차 필터링등의, 텍스쳐 사이즈를 삭감하는 디폴트의 메소드가 제공되지만, 유저는 독자적인 메소드를 가지는 콜백을 정의해 텍스쳐 사이즈를 스케일 다운할 수가 있다.

이 메소드는, DirectX version 6.0과 함께 도입되었다.

참조

D3DRMDOWNSAMPLECALLBACK

IDirect3DRMTexture3::SetShades

IDirect3DRMTexture3

렌더링시에, Direct3DRMTexture2 오브젝트의 각 색에 대해서 사용하는 쉐이드의 최대수를 설정한다. 이 메소드는, 램프 컬러 모델에 한정해 필요하다.

구문

HRESULT SetShades(
  DWORD ulShades
  );

파라미터

ulShades
새로운 쉐이드수. 이 값은, 2의 거듭제곱이 아니면 안된다. 디폴트값은 16이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMTexture3::GetShades

IDirect3DRMTexture3::SetValidationCallback

IDirect3DRMTexture3

1차 소스 텍스쳐의 타당성 검사와 갱신을 실시하는 콜백 함수를 세트 한다.

구문

typedef HRESULT (CDECL *D3DRMVALIDATIONCALLBACK)
  (LPVOID pArg,
  DWORD dwFlags,
  DWORD dwcRects,
  LPRECT pRects);

HRESULT SetValidationCallback(
  LPDIRECT3DRMTEXTURE3 lpDirect3DRMTexture,
  D3DRMVALIDATIONCALLBACK pCallback,
  LPVOID pArg);

파라미터

pCallback
타당성 검사를 실행하기 위해서 불려 가는 콜백 함수에의 포인터. 콜백이 벌써 지정되고 있는 경우, 새로운 콜백은 구의 것을 치환한다. NULL가 지정되고 있으면, 현재의 콜백은 삭제된다.
pArg
호출시에 콜백에게 건네지는 어플리케이션 고유의 데이터.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

Direct3D 보관 유지 모드는, 변경이 끝난 상태이지만 갱신되어 있지 않은 것을 의미하는 무효의 마크를 붙일 수 있었던 텍스쳐-존을, 갱신할 필요가 있을 때, 텍스쳐 타당성 검사 콜백을 호출한다. 어플리케이션은 1차 소스를 갱신해, 돌아온다.

이 메소드는, DirectX version 6.0과 함께 도입되었다.

참조

D3DRMVALIDATIONCALLBACK


IDirect3DRMUserVisual

어플리케이션은, Direct3DRMUserVisual 오브젝트를 초기화하기 위해서IDirect3DRM3::CreateUserVisual 인터페이스의 메소드를 사용한다. 어플리케이션이IDirect3DRM3::CreateObject 메소드를 사용할 때는, 이 초기화는 불필요하다. 초기화가 필요한 것은,IDirect3DRM3::CreateObject메소드를 사용해 비주얼 오브젝트를 생성하는 경우 뿐이다. IDirect3DRM3::CreateObject를 호출하는 어플리케이션은, 다음에IDirect3DRMUserVisual::Init 메소드를 호출해, 오브젝트를 초기화한다.

유저 비주얼 오브젝트는 어플리케이션 정의 데이터이며, 어플리케이션은 이것을 장면에 추가해, 일반적으로는 커스터마이즈 한 렌더링 모듈을 사용해 렌더링 할 수가 있다. 예를 들어, 어플리케이션은, 사운드를 유저 비주얼 오브젝트로서 장면에 추가해, 재생중에 렌더링 할 수가 있다. D3DRMUSERVISUALCALLBACK 콜백 함수 실행중에 어플리케이션이 렌더링 상태를 변경하는 경우, 이 함수로부터 복귀하기 전에 렌더링 상태를 복원할 필요도 있다.

IDirect3DRMUserVisual인터페이스는Init메소드를 지원 한다.

모든 COM 인터페이스와 같이,IDirect3DRMUserVisua인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

게다가IDirect3DRMUserVisual인터페이스는,IDirect3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMUserVisual 오브젝트는,IDirect3DRM3::CreateUserVisual 메소드의 사용에 의해 취득된다.

IDirect3DRMUserVisual::Init

IDirect3DRMUserVisual

Direct3DRMUserVisual 오브젝트를 초기화한다.

구문

HRESULT Init(
  D3DRMUSERVISUALCALLBACK d3drmUVProc,
  void  *lpArg
  );

파라미터

d3drmUVProc
어플리케이션 정의의D3DRMUSERVISUALCALLBACK 콜백 함수.
lpArg
콜백 함수에게 건네지는 어플리케이션 정의의 데이터.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

어플리케이션은IDirect3DRM3::CreateUserVisual 메소드를 호출해, 유저 비주얼 오브젝트의 생성과 초기화를 동시에 실시할 수가 있다. IDirect3DRMUserVisual::Init를 사용할 필요가 있는 것은,IDirect3DRM3::CreateObject 메소드에 의해 유저 비주얼 오브젝트를 생성 했을 경우 뿐이다.


IDirect3DRMViewport2

어플리케이션은, 뷰포트 오브젝트와 서로 교환하기 위해서IDirect3DRMViewport2인터페이스의 메소드를 사용한다. 개념의 개요에 대해서는, 「뷰포트」를 참조할것. Microsoft DirectX version 6.0은,IDirect3DRMViewport2인터페이스를 도입하고 있다. IDirect3DRMViewport2는, 무엇을 클리어 하는지를 나타내는 플래그 파라미터를Clear 메소드에 추가하는 것으로, 그것이 치환하는 구의IDirect3DRMViewport인터페이스를 확장한다. Direct3D 보관 유지 모드 인터페이스의 이력에 대해서는, 「인터페이스의 변경점」을 참조할것.

IDirect3DRMViewport2인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

카메라 | GetCamera
 | SetCamera
클리핑 프레인 | GetBack
 | GetFront
 | GetPlane
 | SetBack
 | SetFront
 | SetPlane
사이즈 | GetHeight
 | GetWidth
뷰의 필드 | GetField
 | SetField
초기화 | Init
그 외 | Clear
 | Configure
 | ForceUpdate
 | GetDevice
 | GetDirect3DViewport
 | Pick
 | Render
오프셋(offset) | GetX
 | GetY
투영 타입 | GetProjection
 | SetProjection
스케일링 | GetUniformScaling
 | SetUniformScaling
변환 | InverseTransform
 | InverseTransformVectors
 | Transform
 | TransformVectors

모든 COM 인터페이스와 같이,IDirect3DRMViewport2인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

게다가IDirect3DRMViewport2인터페이스는IDirect3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMViewport 오브젝트는,IDirect3DRM3::CreateViewport 메소드의 사용에 의해 취득된다.

IDirect3DRMViewport2::Clear

IDirect3DRMViewport2

현재의 배경색으로, 지정된 뷰포트를 클리어 한다. 이것은, 무엇을 클리어 하는지를 나타내는 플래그를 제공하는IDirect3DRMViewport::Clear의 확장 버젼이다. IDirect3DRMViewport::Clear는 파라미터를 취하지 않는다.

구문

HRESULT Clear(
  DWORD dwFlags);

파라미터

dwFlags
다음의 플래그는, 현재 정의되고 있어서 , 논리적으로 조합하는 것이 가능하다.
D3DRMCLEAR_TARGET
출력처 렌더링 표면만을 클리어 한다.
D3DRMCLEAR_ZBUFFER
z버퍼 표면만을 클리어 한다.
D3DRMCLEAR_DIRTYRECTS
사용이 끝난 방형 리스트만을 클리어 한다.
D3DRMCLEAR_ALL
타겟, z버퍼, 사용이 끝난 방형 리스트를 클리어 한다. 이 플래그는IDirect3DRMViewport::Clear의 사용 과 유사한다.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMViewport2::Configure

IDirect3DRMViewport2

뷰포트의 원점과 사이즈를 재설정한다.

구문

HRESULT Configure(
  LONG lX,
  LONG lY,
  DWORD dwWidth,
  DWORD dwHeight
  );

파라미터

lX, lY
뷰포트의 새로운 위치.
dwWidth, dwHeight
뷰포트의 새로운 폭과 높이.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

lX + dwWidth가 디바이스의 폭보다 큰 경우,lY + dwHeight가 디바이스의 높이보다 큰 경우, 혹은lX,lY,dwWidth,dwHeight의 몇개의 값이 0 이하인 경우, 이 메소드는 D3DRMERR_BADVALUE를 돌려준다.

IDirect3DRMViewport2::ForceUpdate

IDirect3DRMViewport2

뷰포트의 영역을 강제적으로 갱신한다. 지정된 영역은, 다음번의IDirect3DRMDevice3::Update 메소드의 호출로 스크린에 카피된다.

구문

HRESULT ForceUpdate(
  DWORD dwX1,
  DWORD dwY1,
  DWORD dwX2,
  DWORD dwY2
  );

파라미터

dwX1, dwY1
갱신 영역의 좌상구석의 좌표.
dwX2, dwY2
갱신 영역의 우하구석의 좌표.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

시스템은, 지정된 직사각형보다 큰 리젼을 갱신하는 일이 있다. 경우에 따라서는, 윈도우 전체가 갱신되는 일도 있다.

IDirect3DRMViewport2::GetBack

IDirect3DRMViewport2

뷰포트의백 클리핑 프레인의 위치를 취득한다.

구문

D3DVALUE GetBack( );

반환값

백 클리핑 프레인과카메라와의 거리를 기술하는 값을 돌려준다.

참조

IDirect3DRMViewport2::SetBack , 「절두체」

IDirect3DRMViewport2::GetCamera

IDirect3DRMViewport2

뷰포트의카메라를 취득한다.

구문

HRESULT GetCamera(
  LPDIRECT3DRMFRAME3 *lpCamera
  );

파라미터

lpCamera
카메라를 나타내는 Direct3DRMFrame 오브젝트가 들어가는 변수에의 포인터.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMViewport2::SetCamera , 「카메라」

IDirect3DRMViewport2::GetDevice

IDirect3DRMViewport2

뷰포트와 관련지을 수 있었던 디바이스를 취득한다.

구문

HRESULT GetDevice(
  LPDIRECT3DRMDEVICE3 *lpD3DRMDevice
  );

파라미터

lpD3DRMDevice
디바이스 오브젝트를 나타내는 변수의 주소. 디바이스에 관한 자세한 것은, 「출력 디바이스」를 참조할것.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMViewport2::GetDirect3DViewport

IDirect3DRMViewport2

현재의 Direct3DRMViewport에 대응하는 Direct3D 뷰포트를 취득한다.

구문

HRESULT GetDirect3DViewport(
  LPDIRECT3DVIEWPORT  *lplpD3DViewport
  );

파라미터

lplpD3DViewport
Direct3DViewport 오브젝트에의 포인터가 들어가는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMViewport2::GetField

IDirect3DRMViewport2

뷰포트의 뷰 필드를 취득한다.

구문

D3DVALUE GetField( );

반환값

뷰의 필드를 나타내는 값을 돌려준다.

참조

IDirect3DRMViewport2::SetField , 「절두체」

IDirect3DRMViewport2::GetFront

IDirect3DRMViewport2

뷰포트의프런트 클리핑 프레인의 위치를 취득한다.

구문

D3DVALUE GetFront( );

반환값

카메라로부터 프런트 클리핑 프레인까지의 거리를 기술하는 값을 돌려준다.

참조

IDirect3DRMViewport2::SetFront , 「절두체」

IDirect3DRMViewport2::GetHeight

IDirect3DRMViewport2

뷰포트의 높이를 픽셀 단위로 취득한다.

구문

DWORD GetHeight( );

반환값

높이를 픽셀 단위로 돌려준다.

IDirect3DRMViewport2::GetPlane

IDirect3DRMViewport2

프런트 클리핑 프레인위에의 뷰포트의 사이즈를 취득한다.

구문

HRESULT GetPlane(
  D3DVALUE *lpd3dvLeft,
  D3DVALUE *lpd3dvRight,
  D3DVALUE *lpd3dvBottom,
  D3DVALUE *lpd3dvTop
  );

파라미터

lpd3dvLeft, lpd3dvRight, lpd3dvBottom, lpd3dvTop
프런트 클리핑 프레인 위에의 뷰포트의 사이즈를 받는 변수의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMViewport2::SetPlane

IDirect3DRMViewport2::GetProjection

IDirect3DRMViewport2

뷰포트의 투영 타입을 취득한다. 뷰포트에는, 평행 투영과 투시 투영의 어디라도 이용할 수가 있다.

구문

D3DRMPROJECTIONTYPE GetProjection( );

반환값

D3DRMPROJECTIONTYPE 열거형의 멤버의 하나를 돌려준다.

참조

IDirect3DRMViewport2::SetProjection

IDirect3DRMViewport2::GetUniformScaling

IDirect3DRMViewport2

윈도우의 사이즈보다 큰 표시 볼륨을 스케일링 하기 위해서 이용되는, 스케일 특성을 취득한다.

구문

BOOL GetUniformScaling( );

반환값

뷰포트가 일정한 비율로 스케일링 되는 경우는 TRUE, 그렇지 않으면 FALSE를 돌려준다.

참조

IDirect3DRMViewport2::SetUniformScaling

IDirect3DRMViewport2::GetWidth

IDirect3DRMViewport2

뷰포트의 폭을 픽셀 단위로 취득한다.

구문

DWORD GetWidth( );

반환값

폭을 픽셀 단위로 돌려준다.

IDirect3DRMViewport2::GetX

IDirect3DRMViewport2

디바이스의 위에의 뷰포트 시점의 x좌표 오프셋(offset)를 취득한다.

구문

LONG GetX( );

반환값

x오프셋(offset)를 돌려준다.

IDirect3DRMViewport2::GetY

IDirect3DRMViewport2

디바이스의 위에의 뷰포트 시점의 y좌표 오프셋(offset)를 취득한다.

구문

LONG GetY( );

반환값

y오프셋(offset)를 돌려준다.

IDirect3DRMViewport2::Init

IDirect3DRMViewport2

Direct3DRMViewport 오브젝트를 초기화한다.

구문

HRESULT Init(
  LPDIRECT3DRMDEVICE3 lpD3DRMDevice,
  LPDIRECT3DRMFRAME3 lpD3DRMFrameCamera,
  DWORD xpos,
  DWORD ypos,
  DWORD width,
  DWORD height
  );

파라미터

lpD3DRMDevice
이 뷰포트에 관련지을 수 있었던 디바이스 오브젝트의 주소. 디바이스에 관한 자세한 것은, 「출력 디바이스」를 참조할것.
lpD3DRMFrameCamera
이 뷰포트에 관련지을 수 있었던카메라프레임의 주소.
xpos, ypos
뷰포트의 좌상구석의 x좌표 및 y좌표.
width, height
뷰포트의 폭과 높이.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMViewport2::InverseTransform

IDirect3DRMViewport2

lprvSrc파라미터가 가리키는 벡터를월드 좌표로부터 모델 좌표로 변환해, 결과를lprvDst파라미터에 돌려준다.

구문

HRESULT InverseTransform(
  D3DVECTOR  *lprvDst,
  D3DRMVECTOR4D  *lprvSrc
  );

파라미터

lprvDst
메소드가 제어를 돌려줄 때 처리 결과를 받는D3DVECTOR 구조체의 주소.
lprvSrc
변환되는D3DRMVECTOR4D 구조체의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMViewport2::InverseTransformVectors , IDirect3DRMViewport2::Transform

IDirect3DRMViewport2::InverseTransformVectors

IDirect3DRMViewport2

이것은, 화면 좌표에 있어서의lpSrcVectors파라미터의 벡터의 배열을월드 좌표로 변환해, 결과를lprvDstVectors파라미터중에 돌려준다.

구문

HRESULT InverseTransformVectors(
   DWORD dwNumVectors,
   LPD3DVECTOR	lpDstVectors,
   LPD3DRMVECTOR4D lpSrcVectors);

파라미터

dwNumVectors
좌표를 변환할 필요가 있는 벡터수.
lpDstVectors
변환의 출력처.
lpSrcVectors
변환하는 벡터를 나타내는D3DRMVECTOR4D 구조체의 배열.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

참조

IDirect3DRMViewport2::TransformVectors , IDirect3DRMViewport2::InverseTransform

IDirect3DRMViewport2::Pick

IDirect3DRMViewport2

깊이에 의해 분류된 오브젝트(관련이 있으면 면도)의 리스트를 찾아낸다. 취득한 배열에는, 루트로부터 오브젝트를 포함한 프레임에 도달할 때까지의 계층 패스가 저장 된다.

구문

HRESULT Pick(
  LONG lX,
  LONG lY,
  LPDIRECT3DRMPICKEDARRAY *lplpVisuals
  );

파라미터

lX, lY
피킹에 사용되는 좌표.
lplpVisuals
호출이 성공했을 때,IDirect3DRMPickedArray 인터페이스에의 유효한 포인터가 들어가는 포인터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMViewport2::Render

IDirect3DRMViewport2

프레임 계층을, 지정된 뷰포트에 렌더링 한다. 지정된 프레임 위에의 비주얼과 그 아래의 계층의 프레임만이 렌더링 된다.

구문

HRESULT Render(
  LPDIRECT3DRMFRAME lpD3DRMFrame
  );

파라미터

lpD3DRMFrame
렌더링 하는 프레임 계층을 나타내는 Direct3DRMFrame 오브젝트를 나타내는 변수의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것. 이 메소드는,IDirect3DRM3::SetOptions 메소드의 사용에 의해 오른손 지원을 지시할 때에 에러를 돌려주어, 그것과 동시에 구의 방법 (IDirect3DRMViewport2::SetProjection )을 사용한 오른손 지원을 제공한다.

IDirect3DRMViewport2::SetBack

IDirect3DRMViewport2

뷰포트의백 클리핑 프레인의 위치를 설정한다.

구문

HRESULT SetBack(
  D3DVALUE rvBack
  );

파라미터

rvBack
카메라와 백 클리핑 프레인의 사이의 거리. 디폴트값은 100.0이다. 적정한 값은 그 외의 절두체 설정에 의존한다. 상세한 것에 대하여는, 「뷰포트」를 참조할것.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, Direct3DRMViewportInterpolator 오브젝트에 백 클리핑 프레인의 위치 키를 추가하기 위해서도 사용한다.

참조

IDirect3DRMViewport2::GetBack , IDirect3DRMViewport2::SetFront , 「절두체」

IDirect3DRMViewport2::SetCamera

IDirect3DRMViewport2

카메라프레임을 뷰포트로 설정한다.

구문

HRESULT SetCamera(
  LPDIRECT3DRMFRAME3 lpCamera
  );

파라미터

lpCamera
카메라를 나타내는 Direct3DRMFrame 오브젝트를 가리키는 변수의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, 뷰포트의 위치, 방향, 방향이 지정된 카메라 프레임과 같게 설정한다. 뷰는, 카메라 프레임의 정의 z축방향에 따라, 정의 y축의 윗방향으로 향해진다.

참조

IDirect3DRMViewport2::GetCamera , 「카메라」

IDirect3DRMViewport2::SetField

IDirect3DRMViewport2

뷰포트에 뷰의 필드를 설정한다.

구문

HRESULT SetField(
  D3DVALUE rvField
  );

파라미터

rvField
뷰의 새로운 필드. 이 값은 시각의 끝수이다. 디폴트값은 0.5이다. 이 값에 0 이하를 지정 하면, 이 메소드는 D3DRMERR_BADVALUE 에러를 돌려준다. 시각은, 프런트 클리핑 프레인의 arctangent의 2배 나누는 카메라로부터의 거리로서 정의된다. 시각의 상세한 것에 대하여는, 「절두체」를 참조할것. rvField의 값 0.5는, 「절두체」의 항으로 가리키는 시각A의 반이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, Direct3DRMViewportInterpolator 오브젝트에 뷰의 필드 키를 추가하기 위해서도 사용한다.

참조

IDirect3DRMViewport2::GetField , 「절두체」

IDirect3DRMViewport2::SetFront

IDirect3DRMViewport2

뷰포트의프런트 클리핑 프레인의 위치를 설정한다.

구문

HRESULT SetFront(
  D3DVALUE rvFront
  );

파라미터

rvFront
카메라로부터 프런트 클리핑 프레인까지의 거리. 디폴트값은 1.0이다. 적정한 값은 그 외의 절두체 설정에 의존한다. 상세한 것에 대하여는, 「뷰포트」를 참조할것.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

0 이하의 값이 건네받으면(자), 이 메소드는 D3DRMERR_BADVALUE 에러를 돌려준다.

이 메소드는, Direct3DRMViewportInterpolator 오브젝트에 프런트 클리핑 프레인 위치 키를 추가하기 위해서도 사용한다.

참조

IDirect3DRMViewport2::GetFront , 「절두체」

IDirect3DRMViewport2::SetPlane

IDirect3DRMViewport2

카메라의 z축으로 대하는 뷰포트의 사이즈를프런트 클리핑 프레인으로 설정한다.

구문

HRESULT SetPlane(
  D3DVALUE rvLeft,
  D3DVALUE rvRight,
  D3DVALUE rvBottom,
  D3DVALUE rvTop
  );

파라미터

rvLeft, rvRight, rvBottom, rvTop
뷰포트의 최소의 x좌표 , 최대의 x좌표, 최소의 y좌표, 최대의 y좌표.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

중앙에 조정된 뷰포트를 지정하는IDirect3DRMViewport2::SetField 메소드와 달리, 이 메소드에 의해, 임의의 비율과 위치의 뷰포트를 지정할 수가 있다. 예를 들어, 분리한절두체를 구축해, 우목이나 좌목의 스테레오 뷰를 인플리맨트 할 수가 있다.

이 메소드는, Direct3DRMViewportInterpolator 오브젝트에 프레인 키를 추가하기 위해서도 사용한다.

참조

IDirect3DRMViewport2::GetPlane , IDirect3DRMViewport2::SetField

IDirect3DRMViewport2::SetProjection

IDirect3DRMViewport2

뷰포트에 투영 타입을 설정한다.

구문

HRESULT SetProjection(
  D3DRMPROJECTIONTYPE rptType
  );

파라미터

rptType
D3DRMPROJECTIONTYPE 열거형의 멤버의 하나.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

DirectX version 6.0이후에서는,IDirect3DRM3::SetOptions 를 사용해 오른손 지오메트리를 지정한다.

참조

IDirect3DRMViewport2::GetProjection

IDirect3DRMViewport2::SetUniformScaling

IDirect3DRMViewport2

표시 볼륨을 윈도우의 사이즈보다 크고 스케일링 할 경우에 이용되는, 스케일 특성을 설정한다.

구문

HRESULT SetUniformScaling(
  BOOL bScale
  );

파라미터

bScale
새로운 스케일 특성. 이 파라미터에 TRUE를 지정 하면, 수평 방향과 수직 방향으로 같은 스케일 계수가 사용된다. 그렇지 않으면, 표시 볼륨을 윈도우에 일치시키기 (위해)때문에, 다른 스케일 계수가 이용된다. 디폴트의 설정은 TRUE이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

보통 이 메소드는, 밴딩을 지원 하기 위해서IDirect3DRMViewport2::SetPlane 메소드와 함께 사용된다.

참조

IDirect3DRMViewport2::GetUniformScaling

IDirect3DRMViewport2::Transform

IDirect3DRMViewport2

lprvSrc파라미터가 가리키는 벡터를월드 좌표로부터 화면 좌표로 변환해, 결과를lprvDst파라미터에 돌려준다.

구문

HRESULT Transform(
  D3DRMVECTOR4D  *lprvDst,
  D3DVECTOR  *lprvSrc
  );

파라미터

lprvDst
변환 조작의 출력처가 되는D3DRMVECTOR4D 구조체의 주소.
lprvSrc
변환 처리의 소스가 되는D3DVECTOR 구조체의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

변환 결과에는, 4 요소의 동종의 벡터가 돌려주어진다. 이하의 방정식이 진이면, 결과의 벡터가 가리키는 점은 가시 상태이다.

점이 가시 상태인가 어떤가를 테스트하는 (분)편 정도식

참조

IDirect3DRMViewport2::TransformVectors , IDirect3DRMViewport2::InverseTransform

IDirect3DRMViewport2::TransformVectors

IDirect3DRMViewport2

이것은,월드 좌표에 있어서의lpSrcVectors파라미터의 벡터의 배열을 화면 좌표로 변환해, 결과를lprvDstVectors파라미터중에 돌려준다.

구문

HRESULT TransformVectors(
  DWORD dwNumVectors,
  LPD3DRMVECTOR4D lpDstVectors,
  LPD3DVECTOR lpSrcVectors);

파라미터

dwNumVectors
변환할 필요가 있는 벡터수.
lpDstVectors
화면 좌표에 변환된 벡터를 나타내는D3DRMVECTOR4D 구조체의 배열.
lpSrcVectors
변환하는 벡터의 배열.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

참조

IDirect3DRMViewport2::Transform , IDirect3DRMViewport2::InverseTransformVectors


IDirect3DRMViewportArray

어플리케이션은, 뷰포트 오브젝트를 그룹화 하기 위한(해),IDirect3DRMViewportArray인터페이스의 메소드를 이용한다. 이 섹션은 이 인터페이스 메소드의 레퍼런스이다. 개념에 대한 개요는, 「뷰포트」를 참조할것.

IDirect3DRMViewportArray인터페이스는 다음의 메소드를 지원 한다.
GetElement
GetSize

모든 COM 인터페이스와 같이,IDirect3DRMViewportArray인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

Direct3DRMViewportArray 오브젝트는,IDirect3DRMDevice3::GetViewports 메소드의 호출에 의해 취득된다.

IDirect3DRMViewportArray::GetElement

IDirect3DRMViewportArray

Direct3DRMViewportArray 오브젝트로부터 지정된 요소를 취득한다.

구문

HRESULT GetElement(
  DWORD index,
  LPDIRECT3DRMVIEWPORT  *lplpD3DRMViewport
  );

파라미터

index
배열 요소.
lplpD3DRMViewport
IDirect3DRMViewport 인터페이스를 받는 주소에의 포인터.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

QueryInterface를 사용해, 예를 들어,IDirect3DRMViewport2 등의 희망하는IDirect3DRMViewport의 버젼에의 포인터를 취득할 수가 있다. lplpD3DRMViewport파라미터를, 다른 버젼에 단순하게 형태 변환할 수 없다. QueryInterface를 사용해야 한다.

IDirect3DRMViewportArray::GetSize

IDirect3DRMViewportArray

Direct3DRMViewportArray 오브젝트에 포함되어 있는 요소수를 취득한다.

구문

DWORD GetSize( );

반환값

요소수를 돌려준다.


IDirect3DRMVisual

IDirect3DRMVisual는, Microsoft® Direct3D® 보관 유지 모드 메소드를 아무것도 제공하지 않지만, 비주얼 오브젝트의 인터페이스는IDirect3DRMVisual인터페이스로부터 나타난다. 인터페이스 계층의 완전한 설명에 대해서는, 「Direct3D 보관 유지 모드의 인터페이스 계층」을 참조할것.

비주얼은, 장면상에 렌더링 할 수 있는 오브젝트이다. 비주얼이 가시가 되는 것은, 그 장면의 프레임에 추가되었을 경우뿐이다. 어플리케이션은,IDirect3DRMFrame3::AddVisual 메소드를 사용해, 비주얼을 프레임에 추가할 수가 있다. 프레임은, 렌더링을 위한 위치와 방향을 비주얼에 제공한다.

다음의 인터페이스는,IDirect3DRMVisual로부터 나타난다.

  • IDirect3DRMFrame3
  • IDirect3DRMMesh
  • IDirect3DRMProgressiveMesh
  • IDirect3DRMShadow2
  • IDirect3DRMTexture3
  • IDirect3DRMUserVisual

모든 COM 인터페이스와 같이,IDirect3DRMVisual인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release


IDirect3DRMVisualArray

어플리케이션은, 비주얼 오브젝트를 그룹화 하려면 ,IDirect3DRMVisualArray인터페이스의 메소드를 이용한다.

비주얼은, 장면상에 렌더링 할 수 있는 오브젝트이다. 비주얼이 가시가 되는 것은, 그 장면의 프레임에 추가되었을 경우뿐이다. 어플리케이션은,IDirect3DRMFrame3::AddVisual 메소드를 사용해, 비주얼을 프레임에 추가할 수가 있다. 프레임은, 비주얼에 렌더링을 위한 위치와 방향을 제공한다.

주: IDirect3DRMVisual COM 인터페이스는 있지만, 이것은 Direct3D 보관 유지 모드의 고유의 메소드를 가지지 않는다.

가장 일반적인 비주얼 타입은, Direct3DRMMeshBuilder3와 Direct3DRMTexture 오브젝트이다.

IDirect3DRMVisualArray인터페이스는 다음의 메소드를 지원 한다.
GetElement
GetSize

모든 COM 인터페이스와 같이,IDirect3DRMVisualArray인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

Direct3DRMVisualArray 오브젝트는IDirect3DRMFrame3::GetVisuals 메소드의 호출에 의해 취득된다.

IDirect3DRMVisualArray::GetElement

IDirect3DRMVisualArray

Direct3DRMVisualArray 오브젝트로부터 지정된 요소를 취득한다.

구문

HRESULT GetElement(
  DWORD index,
  LPDIRECT3DRMVISUAL  *lplpD3DRMVisual
  );

파라미터

index
배열 요소.
lplpD3DRMVisual
IDirect3DRMVisual 인터페이스를 받는 포인터.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMVisualArray::GetSize

IDirect3DRMVisualArray

Direct3DRMVisualArray 오브젝트에 포함되어 있는 요소수를 취득한다.

구문

DWORD GetSize( );

반환값

요소수를 돌려준다.


IDirect3DRMWinDevice

어플리케이션은, 윈도우 프로시저로 윈도우 메세지에 응답하기 위해서IDirect3DRMWinDevice인터페이스의 메소드를 사용한다. 이 섹션은 IDirect3DRMWinDevice 인터페이스 메소드의 레퍼런스이다. 개념에 대한 개요는, 「윈도우 관리」를 참조할것.

IDirect3DRMWinDevice인터페이스는 다음의 메소드를 지원 한다.
HandleActivate
HandlePaint

모든 COM 인터페이스와 같이,IDirect3DRMWinDevice인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

Direct3DRMWinDevice 오브젝트는, IID_IDirect3DRMWinDevice를 지정해IDirect3DRMObject::QueryInterface 메소드 호출하는지,IDirect3DRM3::CreateDeviceFromD3D 와 같은 메소드를 사용하면 취득할 수 있다. IDirect3DRMWinDevice메소드는,IDirect3DRMDevice3 인터페이스로부터 계승된다.

IDirect3DRMWinDevice::HandleActivate

IDirect3DRMWinDevice

Microsoft® Windows®의 WM_ACTIVATE 메세지에 응답한다. 이것에 의해, 액티브한 렌더링 윈도우로 정색해 구 유지할 수가 있다.

구문

HRESULT HandleActivate(
  WORD wParam
  );

파라미터

wParam
메세지 처리 프로시저에게 건네지는, WM_ACTIVATE의WPARAM파라미터.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMWinDevice::HandlePaint

IDirect3DRMWinDevice

Windows의 WM_PAINT 메세지에 응답한다. hDC파라미터는, Windows의BeginPaint함수에게 건네지는PAINTSTRUCT구조체로부터 취득된다. 이 메소드는, 디바이스상에 생성 된 뷰포트의 외측의 영역을 재드로잉(Drawing) 하는 일이 있기 (위해)때문에, 윈도우내의 어플리케이션 영역을 재드로잉(Drawing) 하기 전에 반드시 호출할 필요가 있다.

구문

HRESULT HandlePaint(
  HDC hDC
  );

파라미터

hDC
디바이스 콘텍스트(DC)의 핸들.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.


IDirect3DRMWrap

어플리케이션은, 랩 오브젝트와 교환하기 위해서IDirect3DRMWrap인터페이스의 메소드를 사용한다. 이 섹션은 IDirect3DRMWrap 인터페이스 메소드의 레퍼런스이다. 개념에 대한 개요는, 「랩」을 참조할것.

IDirect3DRMWrap인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.
초기화 | Init
랩 | Apply
 | ApplyRelative

모든 COM 인터페이스와 같이,IDirect3DRMWrap인터페이스는IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3개의 메소드를 지원 한다.
AddRef
QueryInterface
Release

게다가IDirect3DRMWrap인터페이스는IDirect3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.
AddDestroyCallback
Clone
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMWrap 오브젝트는,IDirect3DRM3::CreateWrap 메소드의 호출에 의해 취득된다.

IDirect3DRMWrap::Apply

IDirect3DRMWrap

Direct3DRMWrap 오브젝트를 그 출력처 오브젝트에 적용한다. 일반적으로 출력처 오브젝트는, 면 또는 메쉬이다.

구문

HRESULT Apply(
  LPDIRECT3DRMOBJECT lpObject
  );

파라미터

lpObject
출력처 오브젝트의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRM3::CreateWrap

IDirect3DRMWrap::ApplyRelative

IDirect3DRMWrap

오브젝트의 버텍스에 랩을 설정한다. 최초로 각 버텍스에 프레임의 월드 변환을 실시해, 다음에 랩의 참조 프레임의 역월드 변환을 설정한다.

구문

HRESULT ApplyRelative(
  LPDIRECT3DRMFRAME frame,
  LPDIRECT3DRMOBJECT mesh
  );

파라미터

frame
랩핑 하는 오브젝트를 포함한 Direct3DRMFrame 오브젝트.
mesh
적용하는 Direct3DRMWrap 오브젝트.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRM3::CreateWrap

IDirect3DRMWrap::Init

IDirect3DRMWrap

Direct3DRMWrap 오브젝트를 초기화한다.

구문

HRESULT Init(
  D3DRMWRAPTYPE d3drmwt,
  LPDIRECT3DRMFRAME lpd3drmfRef,
  D3DVALUE ox,
  D3DVALUE oy,
  D3DVALUE oz,
  D3DVALUE dx,
  D3DVALUE dy,
  D3DVALUE dz,
  D3DVALUE ux,
  D3DVALUE uy,
  D3DVALUE uz,
  D3DVALUE ou,
  D3DVALUE ov,
  D3DVALUE su,
  D3DVALUE sv
  );

파라미터

d3drmwt
D3DRMWRAPTYPE 열거형의 멤버의 하나.
lpd3drmfRef
이 Direct3DRMWrap 오브젝트의 참조 프레임을 나타내는 Direct3DRMFrame 오브젝트의 주소.
ox, oy, oz
랩의 원점.
dx, dy, dz
랩의 z축.
ux, uy, uz
랩의 y축.
ou, ov
텍스쳐의 원점.
su, sv
텍스쳐의 스케일 계수.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRM3::CreateWrap


C++비멤버 함수

Microsoft® Direct3D® 보관 유지 모드의 C++비멤버 함수는, 다음과 같다.

  • D3DRMColorGetAlpha
  • D3DRMColorGetBlue
  • D3DRMColorGetGreen
  • D3DRMColorGetRed
  • D3DRMCreateColorRGB
  • D3DRMCreateColorRGBA
  • D3DRMMatrixFromQuaternion
  • D3DRMQuaternionFromRotation
  • D3DRMQuaternionMultiply
  • D3DRMQuaternionSlerp
  • D3DRMVectorAdd
  • D3DRMVectorCrossProduct
  • D3DRMVectorDotProduct
  • D3DRMVectorModulus
  • D3DRMVectorNormalize
  • D3DRMVectorRandom
  • D3DRMVectorReflect
  • D3DRMVectorRotate
  • D3DRMVectorScale
  • D3DRMVectorSubtract
  • Direct3DRMCreate

D3DRMColorGetAlpha

색의 알파 요소를 취득한다.

구문

D3DVALUE D3DRMColorGetAlpha(
  D3DCOLOR d3drmc
  );

파라미터

d3drmc
알파 요소를 취득하는 색. 0에서 255의 사이의 값.

반환값

성공하면 알파값, 실패하면 0을 돌려준다.

참조

D3DRMColorGetBlue , D3DRMColorGetGreen , D3DRMColorGetRed

D3DRMColorGetBlue

색의 파랑 요소를 취득한다.

구문

D3DVALUE D3DRMColorGetBlue(
  D3DCOLOR d3drmc
  );

파라미터

d3drmc
파랑 요소를 취득하는 색. 0에서 255의 사이의 값.

반환값

성공하면 청색값, 실패하면 0을 돌려준다.

참조

D3DRMColorGetAlpha , D3DRMColorGetGreen , D3DRMColorGetRed

D3DRMColorGetGreen

색의 초록 요소를 취득한다.

구문

D3DVALUE D3DRMColorGetGreen(
  D3DCOLOR d3drmc
  );

파라미터

d3drmc
초록 요소를 취득하는 색. 0에서 255의 사이의 값.

반환값

성공하면 녹색값, 실패하면 0을 돌려준다.

참조

D3DRMColorGetAlpha , D3DRMColorGetBlue , D3DRMColorGetRed

D3DRMColorGetRed

색의 빨강 요소를 취득한다.

구문

D3DVALUE D3DRMColorGetRed(
  D3DCOLOR d3drmc
  );

파라미터

d3drmc
빨강 요소를 취득하는 색.

반환값

성공하면 적색값, 실패하면 0을 돌려준다.

참조

D3DRMColorGetAlpha , D3DRMColorGetBlue , D3DRMColorGetGreen

D3DRMCreateColorRGB

주어진 빨강, 초록 및 파랑 요소로부터 RGB색을 생성 한다.

구문

D3DCOLOR D3DRMCreateColorRGB(
  D3DVALUE red,
  D3DVALUE green,
  D3DVALUE blue
  );

파라미터

red, green, blue
RGB색의 원가요소.

반환값

성공하면 새로운 RGB값, 실패하면 0을 돌려준다.

참조

D3DRMCreateColorRGBA

D3DRMCreateColorRGBA

주어진 적, 초록, 청색, 및 알파 요소로부터 RGBA색을 생성 한다.

구문

D3DCOLOR D3DRMCreateColorRGBA(
  D3DVALUE red,
  D3DVALUE green,
  D3DVALUE blue,
  D3DVALUE alpha
  );

파라미터

red, green, blue, alpha
RGBA색의 원가요소. 0에서 1의 사이의 값.

반환값

성공하면 새로운 RGBA값, 실패하면 0을 돌려준다.

참조

D3DRMCreateColorRGB

D3DRMMatrixFromQuaternion

회전을 나타내는 행렬을 계산한다.

구문

void D3DRMMatrixFromQuaternion (
  D3DRMMATRIX4D mat,
  LPD3DRMQUATERNION lpquat
  );

파라미터

mat
함수가 제어를 돌려줄 때, 계산된 행렬이 들어가는 주소. (D3DRMMATRIX4D 형은 배열이다)
lpquat
D3DRMQUATERNION 구조체.

반환값

없음.

D3DRMQuaternionFromRotation

지정된 축을 중심으로, 지정된 각도(라디안 단위)의 회전을 실시한다.

구문

LPD3DRMQUATERNION D3DRMQuaternionFromRotation(
  LPD3DRMQUATERNION lpquat,
  LPD3DVECTOR lpv,
  D3DVALUE theta
  );

파라미터

lpquat
조작 결과를 받는D3DRMQUATERNION 구조체.
lpv
회전의 축을 지정하는D3DVECTOR 구조체.
theta
파라미터에 의해 지정된 축의 주위를 회전하는 각도(라디안 단위).

반환값

성공하면, 제1 파라미터로서 건네받은 4 다음 행열에의 포인터를 돌려준다. 실패하면 0을 돌려준다.

D3DRMQuaternionMultiply

2개의 벡터의 적을 계산한다.

구문

LPD3DRMQUATERNION D3DRMQuaternionMultiply(
  LPD3DRMQUATERNION lpq,
  LPD3DRMQUATERNION lpa,
  LPD3DRMQUATERNION lpb
  );

파라미터

lpq
곱셈의 결과를 받는D3DRMQUATERNION 구조체.
lpa, lpb
곱셈하는D3DRMQUATERNION구조체.

반환값

성공하면, 제1 파라미터로서 건네받은 구조체에의 포인터를 돌려준다. 실패하면 0을 돌려준다.

D3DRMQuaternionSlerp

구(공)면선형 보간을 사용해 2개의 구조체를 보완한다.

구문

LPD3DRMQUATERNION D3DRMQuaternionSlerp(
  LPD3DRMQUATERNION lpq,
  LPD3DRMQUATERNION lpa,
  LPD3DRMQUATERNION lpb,
  D3DVALUE alpha
  );

파라미터

lpq
보완한 결과를 받는D3DRMQUATERNION 구조체.
lpa, lpb
보완의 시작 위치와 종료 위치로서 이용되는D3DRMQUATERNION구조체.
alpha
lpa와lpb의 사이에 보간 하는 거리를 나타내는, 0에서 1의 사이의 값.

반환값

성공하면, 제1 파라미터로서 건네받은 구조체를 돌려준다. 실패하면 0을 돌려준다.

D3DRMVectorAdd

2개의 벡터를 덧셈 한다.

구문

LPD3DVECTOR D3DRMVectorAdd(
  LPD3DVECTOR lpd,
  LPD3DVECTOR lps1,
  LPD3DVECTOR lps2
  );

파라미터

lpd
덧셈의 결과를 받는D3DVECTOR 구조체.
lps1, lps2
덧셈 되는D3DVECTOR구조체.

반환값

성공하면, 제1 파라미터로서 건네받은 벡터를 돌려준다. 실패하면 0을 돌려준다.

D3DRMVectorCrossProduct

2개의 벡터의 외적을 계산한다.

구문

LPD3DVECTOR D3DRMVectorCrossProduct(
  LPD3DVECTOR lpd,
  LPD3DVECTOR lps1,
  LPD3DVECTOR lps2
  );

파라미터

lpd
외 적의 결과를 받는D3DVECTOR 구조체.
lps1, lps2
외 적이 계산되는D3DVECTOR구조체.

반환값

성공하면, 제1 파라미터로서 건네받은 벡터를 돌려준다. 실패하면 0을 돌려준다.

D3DRMVectorDotProduct

벡터의 내적을 돌려준다.

구문

D3DVALUE D3DRMVectorDotProduct(
  LPD3DVECTOR lps1,
  LPD3DVECTOR lps2
  );

파라미터

lps1, lps2
내적이 계산되는D3DVECTOR 구조체.

반환값

성공하면 내적의 결과, 실패하면 0을 돌려준다.

D3DRMVectorModulus

이하의 식에 따라 벡터의 길이를 돌려준다.

x2승 + y2승 + z2승의 제곱근

구문

D3DVALUE D3DRMVectorModulus(
  LPD3DVECTOR lpv
  );

파라미터

lpv
길이를 계산하는D3DVECTOR구조체.

반환값

성공하면,D3DVECTOR 구조체에 길이를 돌려준다. 실패하면 0을 돌려준다.

D3DRMVectorNormalize

절대치가 1이 되도록(듯이) 벡터를 스케일링 한다.

구문

LPD3DVECTOR D3DRMVectorNormalize(
  LPD3DVECTOR lpv
  );

파라미터

lpv
스케일링 조작의 결과를 받는D3DVECTOR 구조체.

반환값

성공하면, 제1 파라미터로서 건네받은 벡터를 돌려준다. 예를 들어 0 벡터가 건네받았을 경우 등, 에러가 발생 하면 0을 돌려준다.

D3DRMVectorRandom

랜덤인 벡터 유니트를 돌려준다.

구문

LPD3DVECTOR D3DRMVectorRandom(
  LPD3DVECTOR lpd
  );

파라미터

lpd
랜덤인 벡터 유니트를 받는D3DVECTOR 구조체.

반환값

성공하면, 제1 파라미터로서 건네받은 벡터를 돌려준다. 실패하면 0을 돌려준다.

D3DRMVectorReflect

지정된 법선에 대해, 광선을 반사한다.

구문

LPD3DVECTOR D3DRMVectorReflect(
  LPD3DVECTOR lpd,
  LPD3DVECTOR lpRay,
  LPD3DVECTOR lpNorm
  );

파라미터

lpd
처리 결과를 받는D3DVECTOR 구조체.
lpRay
법선으로 반사되는D3DVECTOR구조체.
lpNorm
lpRay로 지정된 광선을 반사하는 법선을 나타내는D3DVECTOR구조체.

반환값

성공하면, 제1 파라미터로서 건네받은 벡터를 돌려준다. 실패하면 0을 돌려준다.

D3DRMVectorRotate

지정된 축을 중심으로 벡터를 회전시킨다. 성공하면(자), 정규화된 벡터를 돌려준다.

구문

LPD3DVECTOR D3DRMVectorRotate(
  LPD3DVECTOR lpr,
  LPD3DVECTOR lpv,
  LPD3DVECTOR lpaxis,
  D3DVALUE theta
  );

파라미터

lpr
처리 결과를 받는D3DVECTOR 구조체.
lpv
주어진 축의 회전을 회전하는D3DVECTOR구조체.
lpaxis
회전의 축을 나타내는D3DVECTOR구조체.
theta
라디안 단위에서의 회전 각도.

반환값

성공하면, 제1 파라미터로서 건네받은 벡터를 돌려준다. 실패하면 0을 돌려준다. 이 벡터는 정규화되고 있다.

D3DRMVectorScale

3개의 축으로 붙어 같은 비율로, 벡터를 스케일링 한다.

구문

LPD3DVECTOR D3DRMVectorScale(
  LPD3DVECTOR lpd,
  LPD3DVECTOR lps,
  D3DVALUE factor
  );

파라미터

lpd
처리 결과를 받는D3DVECTOR 구조체.
lps
스케일링 되는D3DVECTOR구조체.
factor
스케일 계수. 이 값이 1 때, 스케일링은 행해지지 않는다. 이 값이 2 때는 2배가 된다.

반환값

성공하면, 제1 파라미터로서 건네받은 벡터를 돌려준다. 실패하면 0을 돌려준다.

D3DRMVectorSubtract

2개의 벡터간에 뺄셈을 실시한다.

구문

LPD3DVECTOR D3DRMVectorSubtract(
  LPD3DVECTOR lpd,
  LPD3DVECTOR lps1,
  LPD3DVECTOR lps2
  );

파라미터

lpd
처리 결과를 받는D3DVECTOR 구조체.
lps1
lps2가 끌리는D3DVECTOR구조체.
lps2
lps1로부터 당기는D3DVECTOR구조체.

반환값

성공하면, 제1 파라미터로서 건네받은 벡터를 돌려준다. 실패하면 0을 돌려준다.

Direct3DRMCreate

Direct3DRM 오브젝트의 인스턴스를 생성 한다.

구문

HRESULT Direct3DRMCreate(
  LPDIRECT3DRM FAR  *lplpD3DRM
  );

파라미터

lplpD3DRM
호출이 성공했을 경우, 유효한 Direct3DRM 포인터가 들어가는 포인터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMObject


C++정수

Microsoft® Direct3D®보관 유지 모드에는,구조체 또는열거형의 어느 쪽에도 들어가지 않는, 그 외의 타입의C++의 정의가 있다. 그것들을 다음에 나타낸다.

  • D3DRMANIMATIONOPTIONS
  • D3DRMCOLORMODEL
  • D3DRMINTERPOLATIONOPTIONS
  • D3DRMLOADOPTIONS
  • D3DRMMAPPING
  • D3DRMMATRIX4D
  • D3DRMSAVEOPTIONS

D3DRMANIMATIONOPTIONS

애니메이션의 재생 방법을 정의하는 값을 지정한다. IDirect3DRMAnimation2::GetOptions ,IDirect3DRMAnimation2::SetOptions 및D3DRMANIMATIONKEY 로 이용된다.

구문

typedef DWORD D3DRMANIMATIONOPTIONS;
#define D3DRMANIMATION_CLOSED             0x02L
#define D3DRMANIMATION_LINEARPOSITION     0x04L
#define D3DRMANIMATION_OPEN               0x01L
#define D3DRMANIMATION_POSITION           0x00000020L
#define D3DRMANIMATION_SCALEANDROTATION   0x00000010L
#define D3DRMANIMATION_SPLINEPOSITION     0x08L

파라미터

D3DRMANIMATION_CLOSED
애니메이션은 반복해 재생되어 종점에 이르면(자) 시작점에 돌아와 루프 한다. 닫혀진 애니메이션에서는, 종점으로부터 시작점에 매끄럽게 천이 시키고 싶은 경우, 애니메이션의 마지막 키는 최초의 키의 반복이 아니면 안 된다. 이 반복 키를 이용해, 루프 하는 애니메이션에 있어서의 최후와 최초의 키간의 시간의 차이가 나타내진다. 그러나, 마지막 키가 최초의 키의 반복이 아닌 경우, 새로운 인터페이스 (IDirect3DRMAnimation2, IDirect3DRMAnimationSet2 )로, 이것은 무시되지 않게 된다. 이것은 효과를 낳아, 애니메이션은 즉시에 시작점에 돌아온다.
D3DRMANIMATION_LINEARPOSITION
애니메이션의 위치는 선형으로 설정된다.
D3DRMANIMATION_OPEN
애니메이션은 1회만 재생되어 정지한다.
D3DRMANIMATION_POSITION
애니메이션의 위치 행렬에 의해, 다른 메소드가 설정하는 어떤 변환 행렬도 덧쓰기된다.
D3DRMANIMATION_SCALEANDROTATION
애니메이션의 스케일과 회전 행렬에 의해, 다른 메소드가 설정하는 어떤 변환 행렬도 덧쓰기된다.
D3DRMANIMATION_SPLINEPOSITION
애니메이션의 위치는 스플라인으로 설정된다.

D3DRMCOLORMODEL

디바이스가 인플리맨트 하는 컬러 모델을 나타낸다. 상세한 것에 대하여는D3DCOLORMODEL 열거형을 참조할것.

구문

typedef D3DCOLORMODEL D3DRMCOLORMODEL;

참조

D3DCOLORMODEL

D3DRMINTERPOLATIONOPTIONS

IDirect3DRMInterpolator::Interpolate 메소드에 대한 옵션을 정의한다. 그러한 옵션은, 오브젝트의 로드의 방법을 변경한다.

구문

typedef DWORD D3DRMINTERPOLATIONOPTIONS;
#define D3DRMINTERPOLATION_OPEN 0x01L
#define D3DRMINTERPOLATION_CLOSED 0x02L
#define D3DRMINTERPOLATION_NEAREST 0x0100L
#define D3DRMINTERPOLATION_LINEAR 0x04L
#define D3DRMINTERPOLATION_SPLINE 0x08L
#define D3DRMINTERPOLATION_VERTEXCOLOR 0x40L
#define D3DRMINTERPOLATION_SLERPNORMALS 0x80L

파라미터

D3DRMINTERPOLATION_OPEN
각 키 최인의 선두와 마지막 키가, 인덱스의 범위외의 보간값을 수정한다.
D3DRMINTERPOLATION_CLOSED
보간은 순환적이다. 키는, 실제로는, 인덱스 범위에 동일한 간격으로 무한하게 반복한다. 애니메이션과의 호환성이기 때문에, 범위의 마지막에 동일한 인덱스의 임의의 키는, 무시된다.
D3DRMINTERPOLATION_NEAREST
최근 닮은 키값이, 각 키 최인의 중간값을 결정하기 위해서(때문에) 사용된다(실행 thread).
D3DRMINTERPOLATION_LINEAR
2개의 최근 닮고 키간의 선형 보간이, 각 키 최인의 중간값을 결정하기 위해서(때문에) 사용된다.
D3DRMINTERPOLATION_SPLINE
4개의 최근 닮고 키에 대한 B스플라인 혼합 함수가, 각 키 최인의 중간값을 결정하기 위해서(때문에) 사용된다.
D3DRMINTERPOLATION_VERTEXCOLOR
버텍스의 색이 보간 되도록(듯이) 지정한다. IDirect3DRMMesh::SetVertices 의 보간인 만큼 영향을 준다.
D3DRMINTERPOLATION_SLERPNORMALS
버텍스의 법선이 구(공)면보간 되도록(듯이) 지정한다(현재미이행). IDirect3DRMMesh::SetVertices 의 보간인 만큼 영향을 준다.

D3DRMLOADOPTIONS

DIDirect3DRM3::Load ,IDirect3DRMAnimationSet2::Load ,IDirect3DRMFrame3::Load ,IDirect3DRMMeshBuilder3::Load , 및IDirect3DRMProgressiveMesh::Load 메소드의 옵션을 정의한다. 그러한 옵션은, 오브젝트의 로드의 방법을 변경한다.

구문

typedef DWORD D3DRMLOADOPTIONS;
#define D3DRMLOAD_FROMFILE             0x00L
#define D3DRMLOAD_FROMRESOURCE         0x01L
#define D3DRMLOAD_FROMMEMORY           0x02L
#define D3DRMLOAD_FROMURL              0x08L
#define D3DRMLOAD_BYNAME               0x10L
#define D3DRMLOAD_BYPOSITION           0x20L
#define D3DRMLOAD_BYGUID               0x30L
#define D3DRMLOAD_FIRST                0x40L
#define D3DRMLOAD_INSTANCEBYREFERENCE  0x100L
#define D3DRMLOAD_INSTANCEBYCOPYING    0x200L
#define D3DRMLOAD_ASYNCHRONOUS         0x400L

파라미터

소스 플래그
D3DRMLOAD_FROMFILE
파일로부터 로드한다. 이것은 디폴트 설정이다.
D3DRMLOAD_FROMRESOURCE
리소스로부터 로드한다. 이 플래그를 지정했을 경우,Load메소드의 호출의lpvObjSource파라미터는,D3DRMLOADRESOURCE 구조체를 가리키지 않으면 안 된다.
D3DRMLOAD_FROMMEMORY
메모리로부터 로드한다. 이 플래그를 지정했을 경우,Load메소드의 호출의lpvObjSource파라미터는,D3DRMLOADMEMORY 구조체를 가리키지 않으면 안 된다.
D3DRMLOAD_FROMURL
URL로부터 로드한다.
식별자 플래그
D3DRMLOAD_BYNAME
지정된 이름을 사용해 오브젝트를 로드한다.
D3DRMLOAD_BYPOSITION
주어진, 0으로부터 시작되는 위치에, 스탠드얼론의 오브젝트를 로드한다(즉, 파일중의n번째의 오브젝트를 로드한다). 스탠드얼론의 오브젝트는 다른 오브젝트를 포함할 수가 있지만, 다른 오브젝트에 포함될 것은 없다.
D3DRMLOAD_BYGUID
지정된 글로벌 유니크 식별자(GUID)를 사용해 오브젝트를 로드한다.
D3DRMLOAD_FIRST
이것은 디폴트 설정이다. 주어진 타입의 스탠드얼론의 오브젝트를 로드한다(예를 들어, 어플리케이션이IDirect3DRMMeshBuilder3::Load 를 호출하는 경우는 메쉬를 로드한다). 스탠드얼론의 오브젝트는 다른 오브젝트를 포함할 수가 있지만, 다른 오브젝트에 포함될 것은 없다.
인스턴스 플래그
D3DRMLOAD_INSTANCEBYREFERENCE
지정된 이름과 같은 이름의 오브젝트가 존재할지 어떨지를 체크한다. 존재하는 경우, 새로운 오브젝트를 생성 하는 대신에, 그 오브젝트의 인스턴스를 사용한다.
D3DRMLOAD_INSTANCEBYCOPYING
지정된 이름과 같은 이름의 오브젝트가 존재할지 어떨지를 체크한다. 존재하는 경우, 새로운 오브젝트를 생성 하는 대신에, 그 오브젝트를 카피한다.
소스 플래그
D3DRMLOAD_ASYNCHRONOUS
Load호출은, 즉시 돌아온다. 로드의 진행 상태를 체크하는데 이벤트를 사용하는 것은, 어플리케이션의 책임이 된다. 디폴트에서는, 로드는, 동기식에서 행해져Load호출은, 모든 데이터의 로드가 완료할 때까지, 또는 에러가 발생할 때까지는 돌아오지 않는다.

주의

각Load메소드는,lpvObjSource파라미터를 사용해 오브젝트의 소스를 지정해,lpvObjID파라미터에 의해 오브젝트를 식별한다. 시스템은 소스 플래그의 선택에 근거해lpvObjSource파라미터를 해석한다. 그리고, 식별자 플래그의 선택에 근거해lpvObjID파라미터의 내용을 해석한다.

인스턴스 플래그는, 파라미터의 해석 방법에는 아무것도 변경을 더하지 않는다. D3DRMLOAD_INSTANCEBYREFERENCE 플래그를 이용하면(자), 새로운 오브젝트를 생성 하는 일 없이 같은 파일을 2회 로드할 수가 있다. 오브젝트가 이름을 가지고 있지 않은 경우, D3DRMLOAD_INSTANCEBYREFERENCE 플래그를 세트 하면, D3DRMLOAD_INSTANCEBYCOPYING 플래그를 세트 했을 때와 같은 효과를 얻을 수 있다. 로더는, 동일한 오브젝트가 존재해도, 각 이름 없음 오브젝트를 새로운 오브젝트로서 생성 한다.

D3DRMMAPPING

텍스쳐의 그룹에의 맵핑 방법을 정의하는 값이다. IDirect3DRMMesh::GetGroupMapping 이나IDirect3DRMMesh::SetGroupMapping 메소드에 의해 이용된다.

구문

typedef DWORD D3DRMMAPPING, D3DRMMAPPINGFLAG;
static const D3DRMMAPPINGFLAG D3DRMMAP_WRAPU = 1;
static const D3DRMMAPPINGFLAG D3DRMMAP_WRAPV = 2;
static const D3DRMMAPPINGFLAG D3DRMMAP_PERSPCORRECT = 4;

파라미터

D3DRMMAPPINGFLAG
D3DRMMAPPING와 형태가 같다.
D3DRMMAP_WRAPU
u방향으로 텍스쳐를 랩 한다.
D3DRMMAP_WRAPV
v방향으로 텍스쳐를 랩 한다.
D3DRMMAP_PERSPCORRECT
텍스쳐 랩핑은 퍼스펙티브 보정된다.

주의

D3DRMMAP_WRAPU와 D3DRMMAP_WRAP 플래그는, 래스터라이저가 텍스쳐 좌표를 해석하는 방법을 결정한다. 래스터라이저는 항상, 텍스쳐 좌표로 가장 짧은 거리, 즉 직선을 보간 한다. 이 직선의 패스와 u 및 v좌표의 유효값은, 랩핑 플래그의 사용법에 따라서 다르다. 한편 또는 양쪽 모두의 플래그가 세트 되면(자), 직선은 u 또는 v방향의 텍스쳐의 옆을 rack-around 한다. 이 경우, 텍스쳐는 원기둥(실린더)장이나 도너츠 위에의 위상을 가지고 있는것 같이 보인다. 상세한 것에 대하여는 「랩」을 참조할것.

참조

「랩」, IDirect3DRMMesh::GetGroupMapping , IDirect3DRMMesh::SetGroupMapping

D3DRMMATRIX4D

변환을 행렬로서 나타낸다. 행렬 엔트리는, D3DRMMATRIX4D[row][column]로부터 구성된다.

구문

typedef D3DVALUE D3DRMMATRIX4D[4][4];

참조

IDirect3DRMFrame3::AddTransform , IDirect3DRMFrame3::GetTransform

D3DRMSAVEOPTIONS

IDirect3DRMMeshBuilder3::Save 메소드의 옵션을 정의한다.

구문

typedef DWORD D3DRMSAVEOPTIONS;
#define D3DRMXOFSAVE_NORMALS 1
#define D3DRMXOFSAVE_TEXTURECOORDINATES 2
#define D3DRMXOFSAVE_MATERIALS 4
#define D3DRMXOFSAVE_TEXTURENAMES 8
#define D3DRMXOFSAVE_ALL 15
#define D3DRMXOFSAVE_TEMPLATES 16
#define D3DRMSAVE_TEXTURETOPOLOGY 32

파라미터

D3DRMXOFSAVE_NORMALS
기본적인 면에 가세해법선 벡터를 보존한다.
D3DRMXOFSAVE_TEXTURECOORDINATES
기본적인 면에 가세해 텍스쳐 좌표를 보존한다.
D3DRMXOFSAVE_MATERIALS
기본적인 면에 가세해 머트리얼을 보존한다.
D3DRMXOFSAVE_TEXTURENAMES
기본적인 면에 가세해 텍스쳐의 이름을 보존한다.
D3DRMXOFSAVE_ALL
기본적인 면에 가세해 법선 벡터, 텍스쳐 좌표, 머트리얼, 텍스쳐의 이름을 보존한다.
D3DRMXOFSAVE_TEMPLATES
파일의 템플릿을 보존한다. 디폴트에서는 템플릿은 보존되지 않는다.
D3DRMSAVE_TEXTURETOPOLOGY
메쉬의 면랩값 (IDirect3DRMMeshBuilder3::SetTextureTopology 또는IDirect3DRMFace2::SetTextureTopology 에 의해 설정된다)을 보존한다. 이 플래그는,Save메소드에 D3DRMXOFSAVE_ALL를 건네주었을 경우에는 포함되지 않는다. 모든 것을 정말로 보존하고 싶으면, D3DRMSAVE_TEXTURETOPOLOGY|D3DRMXOFSAVE_ALL를 건네준다. IDirect3DRMMeshBuilder3::SetTextureTopology또는IDirect3DRMFace2::SetTextureTopology를 호출해, 설정한 값을 보관 유지하고 싶은 경우는, 이 플래그를 건네주는 것만으로 좋다.


C++열거형

Microsoft®Direct3D® 보관 유지 모드의 C++열거형은, 다음과 같다.

  • D3DRMCOLORSOURCE
  • D3DRMCOMBINETYPE
  • D3DRMFILLMODE
  • D3DRMFOGMODE
  • D3DRMFRAMECONSTRAINT
  • D3DRMLIGHTMODE
  • D3DRMLIGHTTYPE
  • D3DRMMATERIALMODE
  • D3DRMPALETTEFLAGS
  • D3DRMPROJECTIONTYPE
  • D3DRMRENDERQUALITY
  • D3DRMSHADEMODE
  • D3DRMSORTMODE
  • D3DRMTEXTUREQUALITY
  • D3DRMUSERVISUALREASON
  • D3DRMWRAPTYPE
  • D3DRMXOFFORMAT
  • D3DRMZBUFFERMODE

D3DRMCOLORSOURCE

Direct3DRMMeshBuilder3 오브젝트의 컬러 소스를 기술한다. 컬러 소스를 설정하려면 ,IDirect3DRMMeshBuilder3::SetColorSource 를 사용한다. 컬러 소스를 취득하려면 ,IDirect3DRMMeshBuilder3::GetColorSource 메소드를 사용한다.

구문

typedef enum _D3DRMCOLORSOURCE{
    D3DRMCOLOR_FROMFACE,
    D3DRMCOLOR_FROMVERTEX
} D3DRMCOLORSOURCE;

값

D3DRMCOLOR_FROMFACE
오브젝트의 컬러 소스는 면이다.
D3DRMCOLOR_FROMVERTEX
오브젝트의 컬러 소스는 버텍스이다.

참조

IDirect3DRMMeshBuilder3::SetColorSource , IDirect3DRMMeshBuilder3::GetColorSource

D3DRMCOMBINETYPE

2개의 행렬의 합성 방법을 지정한다.

구문

typedef enum _D3DRMCOMBINETYPE{
    D3DRMCOMBINE_REPLACE,
    D3DRMCOMBINE_BEFORE,
    D3DRMCOMBINE_AFTER
} D3DRMCOMBINETYPE;

값

D3DRMCOMBINE_REPLACE
주어진 행렬에 의해, 프레임의 현재의 행렬을 옮겨놓는다.
D3DRMCOMBINE_BEFORE
주어진 행렬과 프레임의 현재의 행렬의 적을 요구한다. 계산에 대해서는, 주어진 행렬이 현재의 행렬보다 먼저 지정된다.
D3DRMCOMBINE_AFTER
주어진 행렬과 프레임의 현재의 행렬의 적을 요구한다. 계산에 대해서는, 주어진 행렬이 현재의 행렬의 뒤로 지정된다.

주의

행렬의 곱셈은 가환은 아니기 때문에, 주어진 행렬과 현재의 행렬을 곱하는 순서는 중요하다.

참조

IDirect3DRMFrame3::AddRotation , IDirect3DRMFrame3::AddScale , IDirect3DRMFrame3::AddTransform , IDirect3DRMFrame3::AddTranslation

D3DRMFILLMODE

D3DRMRENDERQUALITY 형의 정의로 사용된다.

구문

typedef enum _D3DRMFILLMODE {
    D3DRMFILL_POINTS    = 0 *D3DRMLIGHT_MAX,
    D3DRMFILL_WIREFRAME = 1 *D3DRMLIGHT_MAX,
    D3DRMFILL_SOLID     = 2 *D3DRMLIGHT_MAX,
    D3DRMFILL_MASK      = 7 *D3DRMLIGHT_MAX,
    D3DRMFILL_MAX       = 8 *D3DRMLIGHT_MAX
} D3DRMFILLMODE;

값

D3DRMFILL_POINTS
점만을 전부 칠한다. 최소의 전부 칠해 모드.
D3DRMFILL_WIREFRAME
와이어 프레임을 바른다.
D3DRMFILL_SOLID
입체 오브젝트를 바른다.
D3DRMFILL_MASK
마스크를 사용해 바른다.
D3DRMFILL_MAX
전부 칠해 모드의 최대치.

참조

D3DRMLIGHTMODE , D3DRMSHADEMODE , D3DRMRENDERQUALITY

D3DRMFOGMODE

카메라로부터의 거리가 퍼지는 것에 따라, 포그(안개:fog) 효과가 어느 정도의 속도로 어떻게 강해지는지를 나타낸다.

흑백(램프) 라이팅 모드에서는, 포그(안개:fog)는, 그 색이 흑의 경우에 정상적으로 기능한다(라이팅이 없는 경우에는, 어느 포그(안개:fog)의 색으로도 일한다. 그 경우에는, 모든 포그(안개:fog)의 색이 실제적으로는 흑이 되기 때문이다).

구문

typedef enum _D3DRMFOGMODE{
    D3DRMFOG_LINEAR,
    D3DRMFOG_EXPONENTIAL,
    D3DRMFOG_EXPONENTIALSQUARED
} D3DRMFOGMODE;

값

D3DRMFOG_LINEAR
포그(안개:fog) 효과는, 시점에서 종점까지의 사이에 비례적으로 강해진다. 다음의 공식에서 표현된다.

거리에 대한 포그(안개:fog) 효과의 비례 증가를 나타내는 공식

현재 지원 되고 있는 포그(안개:fog) 모드는, 이만큼이다.

D3DRMFOG_EXPONENTIAL
포그(안개:fog) 효과는, 지수함수적으로 강해진다. 다음의 공식에서 표현된다.

거리에 대한 포그(안개:fog) 효과의 지수 증가를 나타내는 공식

D3DRMFOG_EXPONENTIALSQUARED
포그(안개:fog) 효과는, 거리의 2승 에 비례해 지수함수적으로 강해진다. 다음의 공식에서 표현된다.

거리의2승에 대한 포그(안개:fog) 효과의 지수 증가를 나타내는 공식

주의

포그(안개:fog)는 시야의 기준이라고 보여지는 것에 주의하지 않으면 안 된다. 방정식의 하나로부터 요구되는 포그(안개:fog)값이 낮을 정도(수록), 오브젝트는 보이기 어려워진다.

포그(안개:fog)의 밀도, 시점, 종점은,IDirect3DRMFrame3::SetSceneFogParams 메소드에 의해 지정할 수가 있다. 지수 포그(안개:fog) 모드의 방정식에서는,e는 자연대수의 바닥을 나타내, 그 값은 약 2.71828이다.

참조

IDirect3DRMFrame3::SetSceneFogMode , IDirect3DRMFrame3::SetSceneFogParams

D3DRMFRAMECONSTRAINT

Direct3DRMFrame 오브젝트를 표시할 경우에 강제적으로 회전하는 축을 기술한다. 이 열거형은IDirect3DRMFrame3::LookAt 메소드에 의해 사용된다.

구문

typedef enum _D3DRMFRAMECONSTRAINT {
    D3DRMCONSTRAIN_Z,
    D3DRMCONSTRAIN_Y,
    D3DRMCONSTRAIN_X
} D3DRMFRAMECONSTRAINT;

값

D3DRMCONSTRAIN_Z
x 및 y회전만 사용한다.
D3DRMCONSTRAIN_Y
x 및 z회전만 사용한다.
D3DRMCONSTRAIN_X
y 및 z회전만 사용한다.

참조

IDirect3DRMFrame3::LookAt

D3DRMLIGHTMODE

D3DRMRENDERQUALITY 형의 정의로 사용된다.

구문

typedef enum _D3DRMLIGHTMODE {
    D3DRMLIGHT_OFF      = 0 *D3DRMSHADE_MAX,
    D3DRMLIGHT_ON       = 1 *D3DRMSHADE_MAX,
    D3DRMLIGHT_MASK     = 7 *D3DRMSHADE_MAX,
    D3DRMLIGHT_MAX      = 8 *D3DRMSHADE_MAX
} D3DRMLIGHTMODE;

값

D3DRMLIGHT_OFF
조명은 오프이다.
D3DRMLIGHT_ON
조명은 온이다.
D3DRMLIGHT_MASK
조명은 마스크를 사용한다.
D3DRMLIGHT_MAX
조명 모드의 최대치.

참조

D3DRMFILLMODE , D3DRMSHADEMODE , D3DRMRENDERQUALITY

D3DRMLIGHTTYPE

IDirect3DRM3::CreateLight 메소드를 사용해, 조명 타입을 정의한다.

구문

typedef enum _D3DRMLIGHTTYPE{
    D3DRMLIGHT_AMBIENT,
    D3DRMLIGHT_POINT,
    D3DRMLIGHT_SPOT,
    D3DRMLIGHT_DIRECTIONAL,
    D3DRMLIGHT_PARALLELPOINT
} D3DRMLIGHTTYPE;

값

D3DRMLIGHT_AMBIENT
앰비언트조명.
D3DRMLIGHT_POINT
포인트조명.
D3DRMLIGHT_SPOT
spotlight조명.
D3DRMLIGHT_DIRECTIONAL
디렉셔널조명.
D3DRMLIGHT_PARALLELPOINT
패러럴 포인트조명.

D3DRMMATERIALMODE

프레임과 함께 렌더링 되는 비주얼의 머트리얼 정보의 소스를 기술한다.

구문

typedef enum _D3DRMMATERIALMODE{
    D3DRMMATERIAL_FROMMESH,
    D3DRMMATERIAL_FROMPARENT,
    D3DRMMATERIAL_FROMFRAME
} D3DRMMATERIALMODE;

값

D3DRMMATERIAL_FROMMESH
머트리얼 정보는 비주얼 오브젝트(메쉬) 그 자체로부터 취득된다. 이것은 디폴트 설정이다.
D3DRMMATERIAL_FROMPARENT
머트리얼 정보는, 색이나 텍스쳐 정보와 함께 친프레임으로부터 계승된다.
D3DRMMATERIAL_FROMFRAME
머트리얼 정보는 프레임으로부터 취득되어 비주얼 오브젝트가 보관 유지하고 있던 이전의 정보를 오버라이드(override) 한다.

참조

IDirect3DRMFrame3::GetMaterialMode , IDirect3DRMFrame3::SetMaterialMode

D3DRMPALETTEFLAGS

D3DRMPALETTEENTRY 구조체에서의 색의 사용 방법을 정의한다.

구문

typedef enum _D3DRMPALETTEFLAGS {
    D3DRMPALETTE_FREE,
    D3DRMPALETTE_READONLY,
    D3DRMPALETTE_RESERVED
} D3DRMPALETTEFLAGS;

값

D3DRMPALETTE_FREE
렌더러-는 이 엔트리를 자유롭게 사용할 수 있다.
D3DRMPALETTE_READONLY
고정되고 있지만, 렌더러-가 사용할 수 있다.
D3DRMPALETTE_RESERVED
렌더러-가 사용할 수 없다.

참조

D3DRMPALETTEENTRY

D3DRMPROJECTIONTYPE

Direct3DRMViewport 오브젝트로 사용되는 투영의 타입을 정의한다. IDirect3DRMViewport2::GetProjection 및IDirect3DRMViewport2::SetProjection 메소드는, 이 열거형을 사용한다. 오른손 타입은, 오른손 투영을 enable로 한다.

주: DirectX version 6.0이후에서는,IDirect3DRM3::SetOptions 를 사용해 오른손 지오메트리를 지정한다.

카메라의 축(IDirect3DRMFrame3::SetAxes 참조)은, 카메라의 면 할 방향을 결정하기 위해서(때문에), 왼손 투영과 오른손 투영의 양쪽 모두로 사용된다.

구문

typedef enum _D3DRMPROJECTIONTYPE{
    D3DRMPROJECT_PERSPECTIVE,
    D3DRMPROJECT_ORTHOGRAPHIC,
    D3DRMPROJECT_RIGHTHANDPERSPECTIVE,
    D3DRMPROJECT_RIGHTHANDORTHOGRAPHIC
} D3DRMPROJECTIONTYPE;

값

D3DRMPROJECT_PERSPECTIVE
투영은, 왼손의 퍼스펙티브이다.
D3DRMPROJECT_ORTHOGRAPHIC
투영은, 왼손의 정사영법이다.
D3DRMPROJECT_RIGHTHANDPERSPECTIVE
투영은, 오른손의 퍼스펙티브이다.
D3DRMPROJECT_RIGHTHANDORTHOGRAPHIC
투영은, 오른손의 정사영법이다.

참조

IDirect3DRMViewport2::GetProjection , IDirect3DRMViewport2::SetProjection

D3DRMRENDERQUALITY

Direct3DRMMesh 오브젝트의 쉐이딩 모드, 조명 모드, 전부 칠해 모드를 결합한다.

구문

typedef enum _D3DRMSHADEMODE {
    D3DRMSHADE_FLAT        = 0,
    D3DRMSHADE_GOURAUD     = 1,
    D3DRMSHADE_PHONG       = 2,
    D3DRMSHADE_MASK        = 7,
    D3DRMSHADE_MAX         = 8
} D3DRMSHADEMODE;
typedef enum _D3DRMLIGHTMODE {
    D3DRMLIGHT_OFF          = 0 *D3DRMSHADE_MAX,
    D3DRMLIGHT_ON           = 1 *D3DRMSHADE_MAX,
    D3DRMLIGHT_MASK         = 7 *D3DRMSHADE_MAX,
    D3DRMLIGHT_MAX          = 8 *D3DRMSHADE_MAX
} D3DRMLIGHTMODE;
typedef enum _D3DRMFILLMODE {
    D3DRMFILL_POINTS        = 0 *D3DRMLIGHT_MAX,
    D3DRMFILL_WIREFRAME     = 1 *D3DRMLIGHT_MAX,
    D3DRMFILL_SOLID         = 2 *D3DRMLIGHT_MAX,
    D3DRMFILL_MASK          = 7 *D3DRMLIGHT_MAX,
    D3DRMFILL_MAX           = 8 *D3DRMLIGHT_MAX
} D3DRMFILLMODE;

typedef DWORD D3DRMRENDERQUALITY;

#define D3DRMRENDER_WIREFRAME   (D3DRMSHADE_FLAT+D3DRMLIGHT_OFF+D3DRMFILL_WIREFRAME)
#define D3DRMRENDER_UNLITFLAT   (D3DRMSHADE_FLAT+D3DRMLIGHT_OFF+D3DRMFILL_SOLID)
#define D3DRMRENDER_FLAT        (D3DRMSHADE_FLAT+D3DRMLIGHT_ON+D3DRMFILL_SOLID)
#define D3DRMRENDER_GOURAUD     (D3DRMSHADE_GOURAUD+D3DRMLIGHT_ON+D3DRMFILL_SOLID)
#define D3DRMRENDER_PHONG       (D3DRMSHADE_PHONG+D3DRMLIGHT_ON+D3DRMFILL_SOLID)

값

D3DRMSHADEMODE , D3DRMLIGHTMODE , D3DRMFILLMODE
쉐이딩, 조명, 전부 칠해 모드를 나타낸다.

D3DRMRENDER_WIREFRAME
옆만을 표시한다.
D3DRMRENDER_UNLITFLAT
조명 없음의 flat shading.
D3DRMRENDER_FLAT
flat shading.
D3DRMRENDER_GOURAUD
gouraud shading.
D3DRMRENDER_PHONG
폰 쉐이딩. 이 쉐이딩 모드는 현재는 지원되어 있지 않다.

참조

IDirect3DRMMesh::GetGroupQuality , IDirect3DRMMesh::SetGroupQuality ,IDirect3DRMDevice3::SetRenderMode

D3DRMSHADEMODE

D3DRMRENDERQUALITY 형의 정의로 사용된다.

구문

typedef enum _D3DRMSHADEMODE {
    D3DRMSHADE_FLAT     = 0,
    D3DRMSHADE_GOURAUD  = 1,
    D3DRMSHADE_PHONG    = 2,
    D3DRMSHADE_MASK     = 7,
    D3DRMSHADE_MAX      = 8
} D3DRMSHADEMODE;

참조

D3DRMFILLMODE , D3DRMLIGHTMODE , D3DRMRENDERQUALITY

D3DRMSORTMODE

장면상에 어떻게 아이 프레임이 소트 되는지를 나타낸다.

구문

typedef enum _D3DRMSORTMODE {
    D3DRMSORT_FROMPARENT,
    D3DRMSORT_NONE,
    D3DRMSORT_FRONTTOBACK,
    D3DRMSORT_BACKTOFRONT
} D3DRMSORTMODE;

값

D3DRMSORT_FROMPARENT
아이 프레임은 친프레임의 소트 순서를 계승한다. 이것은 디폴트 설정이다.
D3DRMSORT_NONE
아이 프레임은 소트 되지 않는다.
D3DRMSORT_FRONTTOBACK
아이 프레임은 전부터 뒤에 소트 된다.
D3DRMSORT_BACKTOFRONT
아이 프레임은 뒤로부터 전에 소트 된다.

참조

IDirect3DRMFrame3::GetSortMode , IDirect3DRMFrame3::SetSortMode

D3DRMTEXTUREQUALITY

디바이스가, 얼마나 텍스쳐의 픽셀과 뷰포트의 픽셀의 사이를 보간 하는지를 기술한다. 이 열거형은IDirect3DRMDevice3::SetTextureQuality 및IDirect3DRMDevice3::GetTextureQuality 메소드에 의해 사용된다.

구문

typedef enum _D3DRMTEXTUREQUALITY{
    D3DRMTEXTURE_NEAREST,
    D3DRMTEXTURE_LINEAR,
    D3DRMTEXTURE_MIPNEAREST,
    D3DRMTEXTURE_MIPLINEAR,
    D3DRMTEXTURE_LINEARMIPNEAREST,
    D3DRMTEXTURE_LINEARMIPLINEAR
} D3DRMTEXTUREQUALITY;

값

D3DRMTEXTURE_NEAREST
텍스쳐의 가장 가까운 픽셀을 선택한다. MIP Mapping를 지원 하지 않는다.
D3DRMTEXTURE_LINEAR
4개(살)의 가장 가까운 픽셀을 선형에 보간 한다. MIP Mapping를 지원 하지 않는다.
D3DRMTEXTURE_MIPNEAREST
D3DRMTEXTURE_NEAREST를 닮아 있지만, 텍스쳐 대신에 적절한밉맵을 사용한다. 픽셀 샘플링과 MIP Mapping는 양쪽 모두 최근 닮고이다.
D3DRMTEXTURE_MIPLINEAR
D3DRMTEXTURE_LINEAR를 닮아 있지만, 텍스쳐 대신에 적절한 밉맵을 사용한다. 픽셀 샘플링은 선형이다. MIP Mapping는 최근 닮고이다.
D3DRMTEXTURE_LINEARMIPNEAREST
D3DRMTEXTURE_MIPNEAREST를 닮아 있지만, 2개의 최근 닮고 밉맵간을 보간 한다. 픽셀 샘플링은 최근 닮고이다. MIP Mapping는 선형이다.
D3DRMTEXTURE_LINEARMIPLINEAR
D3DRMTEXTURE_MIPLINEAR를 닮아 있지만, 2개의 최근 닮고 밉맵간을 보간 한다. 픽셀 샘플링과 MIP Mapping는, 양쪽 모두 선형이다.

D3DRMUSERVISUALREASON

시스템이D3DRMUSERVISUALCALLBACK 콜백 함수를 사용한 이유를 정의한다.

구문

typedef enum _D3DRMUSERVISUALREASON {
    D3DRMUSERVISUAL_CANSEE,
    D3DRMUSERVISUAL_RENDER
} D3DRMUSERVISUALREASON;

값

D3DRMUSERVISUAL_CANSEE
유저 비주얼 오브젝트가 뷰포트상에서 가시 상태이면, 콜백 함수는 TRUE를 돌려주지 않으면 안 된다.
D3DRMUSERVISUAL_RENDER
콜백 함수는 유저 비주얼 오브젝트를 렌더링 하지 않으면 안 된다.

참조

D3DRMUSERVISUALCALLBACK

D3DRMWRAPTYPE

IDirect3DRM3::CreateWrap 메소드에 의해 생성 되는 Direct3DRMWrap 오브젝트의 타입을 정의한다. 또IDirect3DRMWrap::Init 메소드의 호출 중(안)에서, Direct3DRMWrap 오브젝트를 초기화하기 위해서 이 열거형을 사용할 수가 있다.

구문

typedef enum _D3DRMWRAPTYPE{
    D3DRMWRAP_FLAT,
    D3DRMWRAP_CYLINDER,
    D3DRMWRAP_SPHERE,
    D3DRMWRAP_CHROME
} D3DRMWRAPTYPE;

값

D3DRMWRAP_FLAT
프레인 랩.
D3DRMWRAP_CYLINDER
원기둥(실린더) 랩.
D3DRMWRAP_SPHERE
구(공)체 랩.
D3DRMWRAP_CHROME
랩은, 텍스쳐가 오브젝트상에서 반사되도록(듯이) 텍스쳐 좌표를 할당한다.

참조

IDirect3DRM3::CreateWrap , IDirect3DRMWrap::Init , 「랩」

D3DRMXOFFORMAT

IDirect3DRMMeshBuilder3::Save 메소드로 사용되는 파일 타입을 정의한다.

구문

typedef enum _D3DRMXOFFORMAT{
    D3DRMXOF_BINARY,
    D3DRMXOF_COMPRESSED,
    D3DRMXOF_TEXT
} D3DRMXOFFORMAT;

값

D3DRMXOF_BINARY
파일은 바이너리 포맷이다. 이것은 디폴트 설정이다.
D3DRMXOF_COMPRESSED
현재는 지원되어 있지 않다.
D3DRMXOF_TEXT
파일은 텍스트 포맷이다.

주의

D3DRMXOF_BINARY와 D3DRMXOF_TEXT 설정을 동시에 사용할 수 없다.

참조

IDirect3DRMMeshBuilder3::Save

D3DRMZBUFFERMODE

Z버퍼가 유효한가 어떤가를 나타낸다.

구문

typedef enum _D3DRMZBUFFERMODE {
    D3DRMZBUFFER_FROMPARENT,
    D3DRMZBUFFER_ENABLE,
    D3DRMZBUFFER_DISABLE
} D3DRMZBUFFERMODE;

값

D3DRMZBUFFER_FROMPARENT
프레임은 친프레임으로부터 Z버퍼의 설정을 계승한다. 이것은 디폴트 설정이다.
D3DRMZBUFFER_ENABLE
Z버퍼는 유효하다.
D3DRMZBUFFER_DISABLE
Z버퍼는 무효이다.

참조

IDirect3DRMFrame3::GetZbufferMode , IDirect3DRMFrame3::SetZbufferMode


C++구조체

Microsoft® Direct3D®보관 유지 모드의 C++구조체는, 다음과 같다.

  • D3DRMANIMATIONKEY
  • D3DRMBOX
  • D3DRMIMAGE
  • D3DRMLOADMEMORY
  • D3DRMLOADRESOURCE
  • D3DRMMATERIALOVERRIDE
  • D3DRMPALETTEENTRY
  • D3DRMPICKDESC
  • D3DRMPICKDESC2
  • D3DRMPMESHLOADSTATUS
  • D3DRMQUATERNION
  • D3DRMRAY
  • D3DRMVECTOR4D
  • D3DRMVERTEX

D3DRMANIMATIONKEY

IDirect3DRMAnimation2::AddKey 메소드,GetKeys 메소드,ModifyKey 메소드가 사용하는 키를 정의한다.

구문

typedef struct _D3DRMANIMATIONKEY
{
    DWORD dwSize;
    DWORD dwKeyType;
    D3DVALUE dvTime;
    DWORD dwId ;
    union
    {
        D3DRMQUATERNION dqRotateKey;
        D3DVECTOR dvScaleKey;
        D3DVECTOR dvPositionKey;
    };
} D3DRMANIMATIONKEY;
typedef D3DRMANIMATIONKEY *LPD3DRMANIMATIONKEY;

멤버

dwSize
애니메이션의 사이즈.
dwKeyType
키의 타입. 애니메이션의 재생 방법을 정의하는D3DRMANIMATIONOPTIONS 정수의 하나.
dvTime
D3DVALUE 형의 임의의 단위와 멤버의 시간값.
dwId
키 식별자.
dqRotateKey
회전을 정의하는D3DRMQUATERNION 구조체 타입의 값.
dvScaleKey
스케일을 정의하는D3DVECTOR 구조체 타입의 값.
dvPositionKey
위치를 정의하는D3DVECTOR 구조체 타입의 값.

D3DRMBOX

IDirect3DRMMesh::GetBox 이나IDirect3DRMMeshBuilder3::GetBox 메소드로 취득하는 직사각형 범위를 정의한다.

구문

typedef struct _D3DRMBOX {
    D3DVECTOR min, max;
}D3DRMBOX;
typedef D3DRMBOX *LPD3DRMBOX;

멤버

min , max
직사각형 범위를 정의하는 값. 이러한 값은D3DVECTOR 구조체이다.

참조

D3DVECTOR , IDirect3DRMMesh::GetBox , IDirect3DRMMeshBuilder3::GetBox

D3DRMIMAGE

IDirect3DRM3::CreateTexture 메소드에 의해 텍스쳐에 Attach 되는 이미지를 기술한다. IDirect3DRMTexture3::GetImage 는, 이 이미지의 주소를 돌려준다.

구문

typedef struct _D3DRMIMAGE {
    int                width, height;
    int                aspectx, aspecty;
    int                depth;
    int                rgb;
    int                bytes_per_line;
    void               *buffer1;
    void               *buffer2;
    unsigned long      red_mask;
    unsigned long      green_mask;
    unsigned long      blue_mask;
    unsigned long      alpha_mask;
    int                palette_size;
    D3DRMPALETTEENTRY  *palette;
}D3DRMIMAGE;
typedef D3DRMIMAGE, *LPD3DRMIMAGE;

멤버

width , height
픽셀 단위에서의 이미지의 폭과 높이.
aspectx , aspecty
비정방형 픽셀의 어스펙트비(가로세로 비율).
depth
픽셀 당의 비트수.
rgb
픽셀이 RGB값일까 팔레트 인덱스인지를 나타내는 플래그. 이 멤버가 FALSE의 경우, 픽셀은 팔레트의 인덱스를 나타낸다. 이 멤버가 TRUE 때는, 픽셀은 코드화 된 RGB값이다.
bytes_per_line
1 라인 당의 바이트수. 이 값은 4의 배수이다.
buffer1
렌더링을 하는 메모리(최초의 버퍼)의 주소.
buffer2
더블 버퍼링의 2번째의 렌더링 버퍼. 싱글 버퍼링 때는 NULL를 설정한다.
red_mask , green_mask , blue_mask , alpha_mask
RGB 픽셀 또는 픽셀 팔레트 인덱스의 마스크. rgb가 TRUE 때, 이러한 멤버는 픽셀의 적, 초록, 아오베 분의 마스크이다. rgb가 FALSE 때는, 팔레트중에서 중요한 적, 초록, 파랑의 각 요소 비트의 마스크이다. 예를 들어 많은 슈퍼 VGA(SVGA) 디스플레이에서는, 사용하는 적, 초록, 파랑의 정도는 64이기 (위해)때문에, 모든 마스크는 0 xfc에 세트 된다.
palette_size
팔레트 엔트리의 수.
palette
사용되는 컬러 팔레트를 나타내는D3DRMPALETTEENTRY 구조체의 포인터. 이 구조체는,D3DRMIMAGE의rgb 멤버가 FALSE의 경우에만 사용된다.

참조

IDirect3DRM3::CreateTexture , IDirect3DRMTexture3::GetImage

D3DRMLOADMEMORY

어플리케이션이D3DRMLOAD_FROMMEMORY 를 지정해IDirect3DRM3::Load 메소드(또는 다른Load메소드)를 사용했을 때에 로드 되는 리소스를 나타낸다.

구문

typedef struct _D3DRMLOADMEMORY {
    LPVOID lpMemory;
    DWORD  dSize;
} D3DRMLOADMEMORY, *LPD3DRMLOADMEMORY;

멤버

lpMemory
로드 되는 메모리 블록.
dSize
로드 되는 메모리 블록의 사이즈를 바이트 단위로 가리킨다.

참조

IDirect3DRM3::Load , IDirect3DRMAnimationSet2::Load , IDirect3DRMFrame3::Load , IDirect3DRMMeshBuilder3::Load , D3DRMLOADOPTIONS , D3DRMLOADRESOURCE

D3DRMLOADRESOURCE

어플리케이션이D3DRMLOAD_FROMRESOURCE 를 지정해IDirect3DRM3::Load 메소드(또는 다른Load메소드의 하나)를 사용했을 때에 로드 되는 리소스를 나타낸다.

구문

typedef struct _D3DRMLOADRESOURCE {
    HMODULE hModule;
    LPCTSTR lpName;
    LPCTSTR lpType;
} D3DRMLOADRESOURCE, *LPD3DRMLOADRESOURCE;

멤버

hModule
로드 되는 리소스를 포함한 모듈의 핸들. 리소스가, 호출원의 실행 가능 파일, 또는 리소스를 사용하고 있는 동적 링크 라이브러리(DLL)에 Attach 되고 있을 때는, 이 멤버에 NULL를 지정한다.

lpName
로드 되는 리소스의 이름. 예를 들어, 리소스가 메쉬이면, 이 멤버에 메쉬 파일의 이름을 지정한다.
lpType
리소스를 식별하는 유저 정의의 타입.

주의

lpName나lpType멤버의 상위 워드가 0의 경우, 하위 워드는, 그 이름의 정수 식별자 또는 지정된 리소스의 타입을 나타낸다. 그렇지 않으면, 이러한 파라미터는 NULL로 끝나는 캐릭터 라인에의 롱 포인터이다. 캐릭터 라인의 선두 문자가 샤프 기호(#) 때는, 나머지의 문자는 리소스의 이름이나 타입의 정수 식별자를 나타내는 10 진수를 나타낸다. 예를 들어, 캐릭터 라인"#258"은 정수 식별자 258을 나타낸다. 이름 대신에 정수 식별자를 참조하면, 리소스가 필요로 하는 메모리의 양을 줄일 수가 있다.

D3DRMLOAD_FROMRESOURCE를 지정해Load메소드를 사용하면, 어플리케이션으로 리소스를 찾거나 언락 할 필요는 없다. 이 경우, 시스템이 자동적으로 그 처리를 실시한다.

참조

IDirect3DRM3::Load , IDirect3DRMAnimationSet2::Load , IDirect3DRMFrame3::Load , IDirect3DRMMeshBuilder3::Load , D3DRMLOADMEMORY , D3DRMLOADOPTIONS

D3DRMMATERIALOVERRIDE

IDirect3DRMFrame3::SetMaterialOverride 메소드와IDirect3DRMFrame3::GetMaterialOverride 메소드의 오버라이드(override)를 기술한다.

구문

typedef struct _D3DRMMATERIALOVERRIDE
{
    DWORD         dwSize;
    DWORD         dwFlags;
    D3DCOLORVALUE dcDiffuse;
    D3DCOLORVALUE dcAmbient;
    D3DCOLORVALUE dcEmissive;
    D3DCOLORVALUE dcSpecular;
    D3DVALUE      dvPower;
    LPUNKNOWN     lpD3DRMTex;
} D3DRMMATERIALOVERRIDE, *LPD3DRMMATERIALOVERRIDE;

멤버

dwSize
이 구조체의 바이트 사이즈.
dwFlags
이 구조체의 어느 필드가 유효한가를 나타내는, 플래그의 논리적 편성. 가능한 값은 다음과 같다.
D3DRMMATERIALOVERRIDE_DIFFUSE_ALPHAONLY
D3DRMMATERIALOVERRIDE_DIFFUSE_RGBONLY
D3DRMMATERIALOVERRIDE_DIFFUSE
D3DRMMATERIALOVERRIDE_AMBIENT
D3DRMMATERIALOVERRIDE_EMISSIVE
D3DRMMATERIALOVERRIDE_SPECULAR
D3DRMMATERIALOVERRIDE_POWER
D3DRMMATERIALOVERRIDE_TEXTURE
D3DRMMATERIALOVERRIDE_ALL
dcDiffuse
D3DCOLORVALUE 형의 확산 RGBA 컬러 설정.
dcAmbient
D3DCOLORVALUE 형의앰비언트RGB 컬러 설정.
dcEmissive
D3DCOLORVALUE 형의 방사 RGB 컬러 설정.
dcSpecular
D3DCOLORVALUE 형의 반사 RGB 컬러 설정.
dvPower
D3DVALUE 형의강도설정.
lpD3DRMTex
텍스쳐 인터페이스에의 포인터.

D3DRMPALETTEENTRY

D3DRMIMAGE 구조체로 사용되는 컬러 팔레트를 기술한다. 이 구조체는,D3DRMIMAGE구조체의rgb멤버에 FALSE가 지정되고 있을 때 마셔 이용된다(TRUE가 지정되고 있을 때는, RGB값이 이용된다).

구문

typedef struct _D3DRMPALETTEENTRY {
    unsigned char red;
    unsigned char green;
    unsigned char blue;
    unsigned char flags;
}D3DRMPALETTEENTRY;
typedef D3DRMPALETTEENTRY, *LPD3DRMPALETTEENTRY;

멤버

red , green , blue
팔레트를 정의하는 원색 요소를 정의하는 값. 0에서 255의 범위의 값을 지정할 수가 있다.
flags
렌더링시에 팔레트가 어떻게 사용되는지를 정의하는 값. 이 값은D3DRMPALETTEFLAGS 열거형의 멤버의 하나이다.

참조

D3DRMIMAGE , D3DRMPALETTEFLAGS

D3DRMPICKDESC

IDirect3DRMPickedArray::GetPick 메소드에 의해 취득된, 픽의 위치, 면, 그룹 식별자를 저장 한다.

구문

typedef struct _D3DRMPICKDESC {
    ULONG       ulFaceIdx;
    LONG        lGroupIdx;
    D3DVECTOR   vPosition;
} D3DRMPICKDESC, *LPD3DRMPICKDESC;

멤버

ulFaceIdx
취득된 오브젝트의 면의 인덱스.
lGroupIdx
취득된 오브젝트의 그룹 식별자.
vPosition
취득된 오브젝트의 위치를 나타내는 값. 이 값은D3DVECTOR 구조체이다.

참조

D3DVECTOR , IDirect3DRMPickedArray::GetPick

D3DRMPICKDESC2

IDirect3DRMPicked2Array::GetPick 메소드에 의해 꺼내진 면이나 그룹의 식별자, 픽의 위치, 버텍스의 수평 및 수직 텍스쳐 좌표, 버텍스의 법선 및 오브젝트의 색을 저장 한다.

구문

typedef struct _D3DRMPICKDESC2
{
    ULONG	ulFaceIdx;
    LONG	lGroupIdx;
    D3DVECTOR	dvPosition;
    D3DVALUE	tu;
    D3DVALUE	tv;
    D3DVECTOR	dvNormal;
    D3DCOLOR	dcColor;

} D3DRMPICKDESC2, *LPD3DRMPICKDESC2;

멤버

ulFaceIdx
취득된 오브젝트의 면의 인덱스.
lGroupIdx
취득된 오브젝트의 그룹 식별자.
vPosition
취득된 오브젝트의 위치를 나타내는 값. 이 값은D3DVECTOR 구조체이다.
tu , tv
버텍스의 수평 및 수직 텍스쳐 좌표.
dvNormal
버텍스의법선 벡터.
dcColor
버텍스의 색.

D3DRMPMESHLOADSTATUS

IDirect3DRMProgressiveMesh::Load 메소드를 사용해 로드 된 프로그래시브 메쉬의 로드 상태를 저장 한다. 이 구조체는,IDirect3DRMProgressiveMesh::GetLoadStatus 메소드를 사용해 취득할 수 있다.

구문

typedef struct _D3DRMPMESHLOADSTATUS {
    DWORD dwSize;
    DWORD dwPMeshSize;
    DWORD dwBaseMeshSize;
    DWORD dwBytesLoaded;
    DWORD dwVerticesLoaded;
    DWORD dwFacesLoaded;
    DWORD dwFlags;
} D3DRMPMESHLOADSTATUS;
typedef D3DRMPMESHLOADSTATUS *LPD3DRMPMESHLOADSTATUS;

멤버

dwSize
구조체의 사이즈.
dwPMeshSize
프로그래시브 메쉬의 바이트 단위의 전체 사이즈.
dwBaseMeshSize
베이스 메쉬의 바이트 단위의 사이즈.
dwBytesLoaded
로드 된 합계 바이트수.
dwVerticesLoaded
로드 된 버텍스의 수.
dwFacesLoaded
로드 된 면의 수.
dwFlags
프로그래시브 메쉬 로드 상태를 나타내는 플래그. 이하의 값의 하나를 취할 수가 있다.

D3DRMPMESHSTATUS_VALID － 프로그래시브 메쉬 오브젝트는, 유효한 데이터를 포함한다.
D3DRMPMESHSTATUS_INTERRUPTED － 다운로드는, 어플리케이션이IDirect3DRMProgressiveMesh::Abort 를 사용했는지, 또는 접속이 없어졌는지의 몇개의 이유로써 세치기를 받았다.
D3DRMPMESHSTATUS_BASEMESHCOMPLETE － 베이스 메쉬의 다운로드가 완료했다.
D3DRMPMESHSTATUS_COMPLETE － 모든 데이터의 다운로드가 완료했다.
D3DRMPMESHSTATUS_RENDERABLE － 메쉬의 렌더링은, 현재 가능하다.

참조

IDirect3DRMProgressiveMesh::GetLoadStatus , IDirect3DRMProgressiveMesh::Load

D3DRMQUATERNION

IDirect3DRMAnimation2::AddRotateKey 메소드로 이용되는 회전과IDirect3DRMFrame3::SetQuaternion 로 이용되는 4원수를 기술한다. 또, Direct3D의 수학 함수의 몇개인가에서도 사용된다.

구문

typedef struct _D3DRMQUATERNION {
    D3DVALUE   s;
    D3DVECTOR  v;
}D3DRMQUATERNION;
typedef D3DRMQUATERNION, *LPD3DRMQUATERNION;

참조

IDirect3DRMAnimation2::AddRotateKey , IDirect3DRMFrame3::SetQuaternion , D3DRMQuaternionFromRotation , D3DRMQuaternionMultiply , D3DRMQuaternionSlerp , D3DRMMatrixFromQuaternion

D3DRMRAY

광선의 방향과 시작 위치를IDirect3DRMFrame3::RayPick 에 정의한다.

구문

typedef struct _D3DRMRAY
{   D3DVECTOR dvDir;
    D3DVECTOR dvPos;
} D3DRMRAY, *LPD3DRMRAY;

멤버

dvDir
광선 픽으로 이용되는 광선의 방향.
dvPos
광선 픽으로 이용되는 광선의 시작 위치.

D3DRMVECTOR4D

화면 좌표를 기술한다. 이 구조체는,IDirect3DRMViewport2::Transform 및IDirect3DRMViewport2::TransformVectors 메소드에 의한 변환의 출력처로서 및IDirect3DRMViewport2::InverseTransform 및IDirect3DRMViewport2::InverseTransformVectors 메소드에 의한 변환의 소스로서 사용된다.

구문

typedef struct _D3DRMVECTOR4D {
    D3DVALUE x;
    D3DVALUE y;
    D3DVALUE z;
    D3DVALUE w;
}D3DRMVECTOR4D;
typedef D3DRMVECTOR4D, *LPD3DRMVECTOR4D;

멤버

x , y , z , w
D3DVALUE 형의 값. 변환 결과가 들어간다.

참조

IDirect3DRMViewport2::Transform , IDirect3DRMViewport2::TransformVectors , IDirect3DRMViewport2::InverseTransform , IDirect3DRMViewport2::InverseTransformVectors

D3DRMVERTEX

Direct3DRMMesh 오브젝트중의 버텍스를 기술한다.

구문

typedef struct _D3DRMVERTEX{
    D3DVECTOR position;
    D3DVECTOR normal;
    D3DVALUE  tu, tv;
    D3DCOLOR  color;
} D3DRMVERTEX;

멤버

position
버텍스의 위치.
normal
버텍스의 법선 벡터.
tu , tv
버텍스의 수평 및 수직 텍스쳐 좌표.
color
버텍스의 색.

참조

IDirect3DRMMesh::GetVertices , IDirect3DRMMesh::SetVertices


C++반환값

Microsoft® Direct3D®보관 유지 모드(COM) 인터페이스 메소드는, 다음의 값을 돌려준다.

D3DRM_OK
성공. DD_OK 와 동등.
D3DRMERR_BADALLOC
메모리 부족.
D3DRMERR_BADDEVICE
디바이스는 렌더러-와 호환성이 없다.
D3DRMERR_BADFILE
데이터 파일이 부정.
D3DRMERR_BADMAJORVERSION
DLL의 메이저 버젼이 부정.
D3DRMERR_BADMAJORVERSION
DLL의 마이너 버젼이 부정.
D3DRMERR_BADOBJECT
인수에는 오브젝트가 필요.
D3DRMERR_BADPMDATA
. x파일중의 데이터가 부정. 프로그래시브 메쉬에의 변환은 성공했지만, 무효인 프로그래시브 메쉬가. x파일에 생성 되었다.
D3DRMERR_BADTYPE
부정한 형태의 인수가 건네받았다.
D3DRMERR_BADVALUE
부정한 값의 인수가 건네받았다.
D3DRMERR_BOXNOTSET
경계 박스가 프레임으로 설정되지 않을 때에, 경계 박스에 액세스 하려고 했다(예를 들어,IDirect3DRMFrame3::GetBox 를 이용해).
D3DRMERR_CLIENTNOTREGISTERED
클라이언트가 등록되지 않았다. IDirect3DRM3::RegisterClient 를 호출한다.
D3DRMERR_CONNECTIONLOST
로드, 클론 또는 복제중에 데이터 접속이 없어졌다.
D3DRMERR_ELEMENTINUSE
사용중은 요소의 수정 또는 삭제는 할 수 없다. 서브 메쉬를 비우려면 , 그 부모에 대해서 Empty()를 호출한다.
D3DRMERR_ENTRYINUSE
버텍스 또는 법선 엔트리는 현재면이 사용중이며, 삭제할 수 없다.
D3DRMERR_FACEUSED
면은 메쉬상에서 사용 종료이다.
D3DRMERR_FILENOTFOUND
파일을 열 수가 없다.
D3DRMERR_INCOMPATIBLEKEY
지정된 애니메이션 키는 호환성이 없다. 키를 수정할 수 없다.
D3DRMERR_INVALIDLIBRARY
지정된 라이브러리는 무효이다.
D3DRMERR_INVALIDOBJECT
메소드가, 무효인 오브젝트에의 포인터를 받았다.
D3DRMERR_INVALIDPARAMS
메소드에게 건네진 파라미터의 하나가 무효이다.
D3DRMERR_LIBRARYNOTFOUND
지정된 라이브러리가 발견되지 않는다.
D3DRMERR_LOADABORTED
로드가 유저에 의해 강제 종료 당했다.
D3DRMERR_NOSUCHKEY
지정된 애니메이션 키는 존재하지 않는다.
D3DRMERR_NOTCREATEDFROMDDS
지정된 텍스쳐가 DirectDraw 표면으로부터 생성되어 있지 않다.
D3DRMERR_NOTDONEYET
이행되어 있지 않다.
D3DRMERR_NOTENOUGHDATA
요구된 처리를 실시하기 위해서(때문에) 충분한 데이터가 로드되어 있지 않다.
D3DRMERR_NOTFOUND
지정된 프레인에 오브젝트가 발견되지 않는다.
D3DRMERR_OUTOFRANGE
지정된 값은 범위외이다.
D3DRMERR_PENDING
요구된 정보를 공급하기 위해서 필요한 데이터의 로드가 종료하고 있지 않다.
D3DRMERR_REQUESTTOOLARGE
이용 가능한 최대 상세 레벨보다 큰 상세 레벨을 프로그래시브 메쉬로 설정하려고 했다.
D3DRMERR_REQUESTTOOSMALL
베이스 메쉬의 상세보다 작은 프로그래시브 메쉬의 최저 렌더링 상세를 설정하려고 했다 (렌더링의 최소 값).
D3DRMERR_TEXTUREFORMATNOTFOUND
지정된 기준을 채워, 하층의 직접 모드 디바이스가 지원 하는 텍스쳐 포맷이 발견되지 않았다.
D3DRMERR_UNABLETOEXECUTE
프로시저를 실행할 수 없다.
DD_OK
요구는 성공해 완료했다. D3DRM_OK 와 동등.
DDERR_INVALIDOBJECT
무효인 오브젝트의 포인터를 받았다.
DDERR_INVALIDPARAMS
메소드에게 건네진 1개이상의 파라미터가 부정하다.
DDERR_NOTFOUND
요구된 항목이 발견되지 않았다.
DDERR_NOTINITIALIZED
오브젝트가 초기화되기 전에,CoCreateInstance로 생성 한 오브젝트의 인터페이스 메소드를 호출하려고 했다.
DDERR_OUTOFMEMORY
DirectDraw가 처리를 실시하는데 충분한 메모리가 없다.


C++/COM 프로그래머를 위한 추가 정보

이 항에는, Microsoft® Direct3D® 보관 유지 모드의 C++/COM 레퍼런스에 관한 다음의 주제가 포함된다.

  • 컬러 키잉
  • D3DCOLOR_MONO
  • D3DCOLOR_RGB
  • D3DCOLORMODEL
  • D3DCOLORVALUE
  • D3DDEVICEDESC
  • D3DENUMDEVICESCALLBACK
  • D3DMATRIX
  • D3DPRIMCAPS
  • D3DRECT
  • D3DTRIANGLE
  • D3DVALUE
  • D3DVECTOR
  • DirectDrawCreate
  • DirectDrawCreateClipper
  • DrawPrimitive
  • IDirect3D3
  • IDirectDrawClipper
  • IUnknown 인터페이스
  • 밉맵
  • 텍스쳐 맵 포맷

컬러 키잉
컬러 키는, 일반적으로는 아티스트가 투명성을 위해서(때문에) 밖에 사용하지 않는 단일로 공통성이 없는 색이지만, 이것을 지정한 색범위로 할 수도 있다. IDirectDrawSurface3::SetColorKey메소드를 사용해, 표면의 컬러 키를 세트 할 수가 있다. 컬러 키를 세트 하면,IDirectDrawSurface3::BltFast에 대한 후속의 호출은 그 컬러 키를 활용해, 일치하는 픽셀을 무시한다. 이 타입의 컬러 키는, 소스 컬러 키로 불린다. 소스 컬러 키는 「투명」인 픽셀이 출력 먼저 기입해지지 않게 하기 위한(해), 오리지날의 배경 픽셀은 이러한 장소에 보존되어 비방형 오브젝트인 스프라이트가 배경을 횡단해 있는 것과 같게 보인다. 출력처 표면에 효과를 주는 컬러 키 (출력처 컬러 키)를 사용할 수도 있다.

출력처 컬러 키는, 스프라이트로 덧쓰기 가능한 픽셀에 사용되는 표면 위에의색이다. 재차, 아티스트는, 이미지중의 다른 장소에서 사용되어 있지 않은 임의의 색을 선택해, 블록 전송 가능한 이미지의 일부로서 그것을 예약한다. 지정된 출력처 컬러 키에 의해 스프라이트를 출력처 표면에 블록 전송 하면, 스프라이트의 픽셀은, 출력처 컬러 키를 사용중의 출력처 위에의 픽셀에게만 블록 전송 된다. 법선의 출력처 픽셀은 보존되고 있으므로, 스프라이트가 출력처 표면 위에의 이미지의 배후를 횡단해 있는 것과 같게 보인다. 상세한 것에 대하여는, DirectX Foundation SDK의 「DirectDraw의 요점」섹션의 「표면」의 항내의 「투과형 블록 전송」을 참조할것.

D3DCOLOR_MONO
흑백 모델 (램프 모델)의 사용을 시스템에 지시하는D3DRMCOLORMODEL 정수의 값. 이 모델에서는, 버텍스의 색의 파랑 요소를 사용해, 비추어지는 버텍스의 휘도(Luminance)을 정의한다.
D3DCOLOR_RGB
풀 RGB 모델의 사용을 시스템에 지시하는D3DRMCOLORMODEL 정수의 값.
D3DCOLORMODEL
시스템이 실행하는 컬러 모델을 정의하는 정수.
typedef enum _D3DCOLORMODEL {
    D3DCOLOR_MONO = 1,
    D3DCOLOR_RGB  = 2,
} D3DCOLORMODEL;
D3DCOLORVALUE
색의 값을 기술하는 구조체. dvR, dvG, dvB, dvA는, 색의 적, 록, 청, 알파 요소를 지정하는D3DVALUE 형의 값이다. 이러한 값은, 일반적으로는 0.0에서 1.0의 범위에 있어, 0.0은 흑을 지정한다.
typedef struct _D3DCOLORVALUE {
    union {
        D3DVALUE r;
        D3DVALUE dvR;
    };
    union {
        D3DVALUE g;
        D3DVALUE dvG;
    };
    union {
        D3DVALUE b;
        D3DVALUE dvB;
    };
    union {
        D3DVALUE a;
        D3DVALUE dvA;
    };
} D3DCOLORVALUE;
D3DDEVICEDESC
현재의 디바이스의 기술을 포함한 구조체. 상세한 것에 대하여는, 「Direct3D 직접 모드 레퍼런스」의 「구조체」의 항의D3DDEVICEDESC를 참조할것.
D3DENUMDEVICESCALLBACK
도입 끝난 Direct3D 디바이스를 열거하는 콜백 함수의 prototype 정의. 상세한 것에 대하여는, 「Direct3D 직접 모드 레퍼런스」의 「콜백 함수」를 참조할것.
typedef HRESULT (FAR PASCAL * LPD3DENUMDEVICESCALLBACK)
  (LPGUID lpGuid,
  LPSTR lpDeviceDescription,
  LPSTR lpDeviceName,
  LPD3DDEVICEDESC lpD3DHWDeviceDesc,
  LPD3DDEVICEDESC lpD3DHELD9eviceDesc,
  LPVOID lpUserArg
);
D3DMATRIX
행렬을 기술하는 구조체.
typedef struct _D3DMATRIX {
    D3DVALUE _11, _12, _13, _14;
    D3DVALUE _21, _22, _23, _24;
    D3DVALUE _31, _32, _33, _34;
    D3DVALUE _41, _42, _43, _44;
} D3DMATRIX, *LPD3DMATRIX;
D3DPRIMCAPS
각 프리미티브 타입의 기능을 정의하는 구조체. IDirect3DRM3::CreateDeviceFromClipper 를 사용해, 이러한 디폴트 기능을 세트 한다.

D3DPCMPCAPS_LESSEQUAL － 새로운 z값이 현재의 z값이하의 경우, z버퍼 비교를 건네준다.

D3DPMISCCAPS_CULLCCW － 이 드라이버는,D3DRENDERSTATE_CULLMODE상태를 개입시켜, 시계와 역회전의 컬링(Culling)를 지원 한다 (이것은 삼각형 원시적으로 마셔 적용된다).

D3DPRASTERCAPS_FOGVERTEX － 이 디바이스는, 라이팅 조작중에 포그(안개:fog)값을 계산해,D3DTLVERTEX구조체의 반사 멤버에게 줄 수 있었던 D3DCOLOR값의 알파 요소에 그 값을 배치해, 래스터화 시에 포그(안개:fog)값을 보간 한다.

D3DPSHADECAPS_ALPHAFLATSTIPPLED － 이 디바이스는, 플랫 투명 블렌딩과 투명 점묘 (D3DSHADEMODE 열거형의 D3DSHADE_FLAT 상태)의 알파 요소를 각각 지원 할 수가 있다. 이러한 모드에서는, 프리미티브의 알파색요소는, 프리미티브의 최초의 버텍스의 색의 일부로서 제공된다.

D3DPTADDRESSCAPS_WRAP － 이 디바이스는, 주소에 대해서 텍스쳐를 랩 할 수가 있다.

D3DPTBLENDCAPS_COPY | D3DPTBLENDCAPS_MODULATE － 카피 텍스쳐 블렌딩 모드 (D3DTEXTUREBLEND 열거형으로부터의 D3DTBLEND_COPY)와 변조 텍스쳐 블렌딩 모드 (D3DTEXTUREBLEND 열거형으로부터의 D3DTBLEND_MODULATE)가 지원 된다.

D3DPTEXTURECAPS_PERSPECTIVE | D3DPTEXTURECAPS_TRANSPARENCY － 퍼스펙티브 보정과 텍스쳐 투명성이 지원 된다.

D3DPTFILTERCAPS_NEAREST － 희망하는 픽셀값에 가장 가까운 좌표를 가지는 텍셀 (텍스쳐의 단일 요소)이 사용된다. 이것은, 줌인과 줌 아웃의 양쪽 모두에 적용된다. 줌인과 줌 아웃의 어느 쪽인지를 지원 하고 있는 경우, 양쪽 모두를 지원 해야 한다.

D3DRECT
방형을 정의하는 구조체.
typedef struct _D3DRECT {
    union {
        LONG x1;
        LONG lX1;  //좌상 x
    };
    union {
        LONG y1;
        LONG lY1;  //좌상 y
    };
    union {
        LONG x2;
        LONG lX2; //우하 x
    };
    union {
        LONG y2;
        LONG lY2;  //우하 y
    };
} D3DRECT, *LPD3DRECT;
D3DTRIANGLE
모든 삼각형의 베이스 타입을 기술하는 구조체. 삼각형은 주요한 렌더링 원시적이다.
D3DVALUE
기본적인 Direct3D fractional 데이터형.
typedef float D3DVALUE, *LPD3DVALUE;
D3DVECTOR
Direct3D와 Direct3D 보관 유지 모드가 많은 메소드와 구조체의 벡터를 정의하는 구조체.
typedef struct _D3DVECTOR {
    union {
        D3DVALUE x;
        D3DVALUE dvX;
    };
    union {
        D3DVALUE y;
        D3DVALUE dvY;
    };
    union {
        D3DVALUE z;
        D3DVALUE dvZ;
    };
} D3DVECTOR, *LPD3DVECTOR;
DirectDrawCreate
DirectDraw 오브젝트의 인스턴스를 생성 하는 함수. 상세한 것에 대하여는, 「DirectDraw 레퍼런스」의DirectDrawCreate 함수를 참조할것.
DirectDrawCreateClipper
DirectDraw 오브젝트와 관련지을 수 있지 않은 DirectDrawClipper 오브젝트의 인스턴스를 생성 하는 함수. 상세한 것에 대하여는, 「DirectDraw 레퍼런스」의DirectDrawCreateClipper 함수를 참조할것.
DrawPrimitive
IDirect3DDevice3::DrawPrimitive메소드는, 지정된 버텍스 배열을 특정의 타입의 기하 프리미티브의 순서로서 드로잉(Drawing) 한다. 기하 프리미티브의 타입에는, 점, 선, 삼각형, 삼각형의 선형, 삼각형의 전개등이 있다.
IDirect3D3
어플리케이션은,IDirect3D3인터페이스의 메소드를 사용해 Direct3D 오브젝트를 생성 해, 환경을 세트 한다. 상세한 것에 대하여는, 「Direct3D 직접 모드 레퍼런스」의 「IDirect3D3 인터페이스」를 참조할것.
IDirect3D3::EnumDevices － 이 메소드는, 시스템에 도입 끝난 모든 Direct3D 디바이스 드라이버를 열거한다.
IDirect3D3::FindDevice － 이 메소드는, 지정한 특성을 가지는 디바이스를 찾아내 그 기술을 취득한다.
IDirectDrawClipper
어플리케이션은,IDirectDrawClipper인터페이스의 메소드를 사용해, 클립 리스트를 관리한다. 상세한 것에 대하여는, 「DirectDraw 레퍼런스」의 「IDirectDrawClipper 인터페이스」를 참조할것.
IDirectDrawClipper::SetHWnd － 이 메소드는, 클리핑 정보를 취득하는 윈도우 핸들을 세트 한다.
IUnknown 인터페이스
모든 COM (Component Object Model) 인터페이스는,IUnknown 인터페이스로부터 나타난다. 이 인터페이스는, 오브젝트의 존속 기간의 제어와 복수의 인터페이스를 이동하는 기능을 제공한다. IUnknown에는 다음의 3개의 메소드가 있다. AddRef. 이것은, 인터페이스 또는 다른 어플리케이션이 자기 자신을 오브젝트에 바인드 했을 때에, 오브젝트의참조 카운트를 1만 인크리먼트(increment) 한다. QueryInterface. 이것은, 고유의 인터페이스에 대해서 포인터를 요구하는 것으로, 그것이 지원 하는 기능에 대해 오브젝트의 조회를 실시한다. Release. 이것은, 오브젝트의 참조 카운트를 1만 감소 한다. 카운트가 0이 되면(자), 오브젝트의 할당은 해제된다.

IUnknown::AddRef 및IUnknown::Release － 이러한IUnknown 메소드는, 오브젝트의 참조 카운트를 보수한다. 예를 들어, DirectPlay 오브젝트를 (예를 들어,CoCreateInstance에 의해) 생성 하는 경우, 오브젝트의 참조 카운트는 1에 세트 된다. 함수가 포인터를 그 오브젝트의 인터페이스에 돌려줄 때마다, 함수는 그 포인터를 개입시켜AddRef를 호출해, 참조 카운트를 인크리먼트(increment) 해야 한다. 또, 각각의AddRef호출과Release의 호출을 조합해야 한다. 포인터를 파기하기 전에, 그 포인터를 개입시켜Release를 호출하지 않으면 안 된다. 오브젝트의 참조 카운트가 0이 되면(자), 오브젝트는 파기되어 그에 대하는 모든 인터페이스가 무효가 된다.
IUnknown::QueryInterface － 이IUnknown 메소드는, 오브젝트가 고유의 인터페이스를 지원 할지 어떨지를 결정한다. 오브젝트가 인터페이스를 지원 하는 경우,QueryInterface은 포인터를 그 인터페이스에 돌려준다. 이것으로, 그 인터페이스에 포함되는 메소드를 사용해, 오브젝트라고 회화할 수가 있다. QueryInterface가 포인터를 인터페이스에 돌려주는 것에 성공했을 경우, 그것은 암묵에AddRef를 호출해, 참조 카운트를 인크리먼트(increment) 한다. 이 때문에, 어플리케이션은, 인터페이스에의 포인터를 파기하기 전에,Release를 호출해, 참조 카운트를 감소 해야 한다.
밉맵
밉맵은, 각각의 텍스쳐는 해상도가 점차 낮아진다, 같은 이미지를 사전에 필터링 한 표현이다. 밉맵중의 각 필터링 이미지 또는 레벨은, 이전의 레벨보다 2의 거듭제곱씩 작아지고 있다. 고해상도 레벨은, 뷰아에 가까운 오브젝트에 사용된다. 오브젝트가 멀리 이동하는 것에 따라, 보다 저해상도의 레벨이 사용된다. MIP Mapping는, 텍스쳐의 렌더링 퀄리티를 향상하는, 계산상 비용이 들지 않는 방법이다. 상세한 것에 대하여는, 「Direct3D 직접 모드」의 「텍스쳐」의 「밉맵」을 참조할것.
텍스쳐 맵 포맷
광범위한 텍스쳐 픽셀 포맷이, Microsoft® DirectX® 하드웨어 에뮬레이션 계층으로 지원 되고 있다. 이러한 포맷에 대해서는, 「DirectDraw 레퍼런스」의 「텍스쳐 맵 포맷」의 겉(표)를 참조할것.


Visual Basic 레퍼런스

Microsoft® Direct3D® 보관 유지 모드의 Microsoft Visual Basic® 레퍼런스는, 인터페이스, 클래스, 메소드, 및 콜백 인터페이스에 대해, 구문, 파라미터 기술, 플래그 기술등의 상세 정보를 제공한다. 또, Direct3D 보관 유지 모드형의 멤버, 열거형, 그 외의 정의제타입, 돌려주어질 가능성이 있는 에러값에 대해서도 기술한다. 이 항에는, 다음의 주제가 포함된다.

인터페이스

  • 콜백 인터페이스
  • 인터페이스

데이터 타입

  • 열거형
  • 형

그 외의 주제

  • 에러값
  • 추가 정보


Visual Basic 콜백 인터페이스

Microsoft® Direct3D® 보관 유지 모드의 Microsoft Visual Basic® 콜백 인터페이스는 다음과 같다.

  • Direct3DRMCallback
  • Direct3DRMDeviceUpdateCallback3
  • Direct3DRMEnumerateObjectsCallback
  • Direct3DRMFrameMoveCallback3
  • Direct3DRMLoadCallback
  • Direct3DRMLoadTextureCallback3

콜백 인터페이스를 사용하려면 , 예를 들어Direct3DRMDeviceUpdateCallback3의 경우이면, 다음과 같은 조작을 실시한다.

  1. 코드 에디터 윈도우에 다음의 행을 카피한다.
    Implements Direct3DRMDeviceUpdateCallback3
  2. Enter키를 누른다.
  3. [오브젝트] 박스의 [Direct3DRMDeviceUpdateCallback3] 를 클릭한다. Direct3DRMDeviceUpdateCallback3 인터페이스의 구문 블록이 표시된다.
    Private Sub Direct3DRMDeviceUpdateCallback3_CallbackRMUpdate(
    ByVal f As DxVBLib.Direct3DRMDevice3, ByVal arg As Object,
    ByVal n As Long, Update As DxVBLib.D3DRECT)
    'do something
End Sub

Direct3DRMCallback.CallbackRMDestroyObject

오브젝트를 삭제한다.

구문

object_CallbackRMDestroyObject(ByVal args As Object)

요소

object
Direct3DRMCallback오브젝트를 나타내는오브젝트식.
args
이 콜백에게 건네지는 어플리케이션 정의의 데이터.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMDeviceUpdateCallback3.CallbackRMUpdate

디바이스가 변경되었을 때는 어플리케이션에 경고한다. 이 콜백은 어플리케이션으로 정의된다.

구문

object_CallbackRMUpdate(ByVal f As DxVBLib.Direct3DRMDevice3,
  ByVal arg As Object,
  ByVal n As Long,
  Update As DxVBLib.D3DRECT)

요소

object
Direct3DRMDeviceUpdateCallback3오브젝트를 나타내는오브젝트식.
f
이 콜백이 적용되는Direct3DRMDevice3 오브젝트.
arg
이 콜백에게 건네지는 어플리케이션 정의의 데이터.
n
Update파라미터로 지정된 직사각형의 수.
Update
갱신하는 영역을 나타내는D3DRECT 의 타입. 좌표는 디바이스 단위로 지정된다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMEnumerateObjectsCallback.CallbackRMEnumerateObjects

Direct3DRM3.EnumerateObjects 메소드의 호출해에 응답하는 오브젝트를 열거한다. 이 콜백은 어플리케이션으로 정의된다.

구문

object_CallbackRMEnumerateObjects(ByVal Object As DxVBLib.Direct3DRMObject,
  ByVal userArgument As Object)

요소

object
Direct3DRMEnumerateObjectsCallback오브젝트를 나타내는오브젝트식.
object
Direct3DRMObject 오브젝트.
userArgument
이 콜백에게 건네지는 어플리케이션 정의의 데이터.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrameMoveCallback3.CallbackRMFrameMove

프레임의 이동이나 갱신시에, 어플리케이션이 커스터마이즈 한 알고리즘을 적용할 수 있도록(듯이) 한다. frame rate를 변경하기 위해서 이 콜백을 사용할 수가 있다. 이 콜백은 어플리케이션으로 정의된다.

구문

object_CallbackRMFrameMove(ByVal f As DxVBLib.Direct3DRMFrame3,
  ByVal arg As Object,
  ByVal delta As Single)

요소

object
Direct3DRMFrameMoveCallback3오브젝트를 나타내는오브젝트식.
f
변경하려고 하고 있는Direct3DRMFrame3 오브젝트.
arg
이 콜백에게 건네지는 어플리케이션 정의의 데이터.
delta
운동에 적용되는 변화량. 프레임의 위치를 변경하려면 , 직선과 회전의 2개의 요소가 있다. 각 요소에 있어서의 변경은,velocity_of_component × delta에 동일하다. 이러한 한편 또는 양쪽 모두의 속도는, 임의의 프레임을 기점으로서 설정할 수가 있지만, 시스템은, 자동적으로 델타 시간을 적용하므로, 친프레임을 기점으로 한 속도로 변환한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

어플리케이션은, 친프레임을 기준으로 해 프레임의 가속을 합성할 수가 있다. 그 때문에(위해)는, 각 틱으로, 어플리케이션은, 아이 프레임의 속도를 어플리케이션 자신을 기준으로 한(1 틱 근처a유니트)× 1 틱으로 설정할 필요가 있다. 여기서, a는 요구된 가속도이다. 이것은, 틱 당의a× delta에 동일하다. 내부적으로는, 아이 프레임을 기준으로 한 틱 당의a × delta는, 친프레임을 기준으로 한(v + (a × delta)) 유니트에 변환된다. 여기서,v는, 부모를 기준으로 하는 아이 프레임의 현재의 속도이다.

이 콜백을 추가 또는 삭제하려면 ,Direct3DRMFrame3.AddMoveCallback 및Direct3DRMFrame3.DeleteMoveCallback 메소드를 사용한다.

시스템은, 콜백을 사용하는 순서를 결정하기 (위해)때문에, 우선 계층의 톱 레벨에 있는 오브젝트를 검색한다. 다음에, 생성 된 차례로 콜백을 사용한다.

Direct3DRMLoadCallback.CallbackRMLoad

Direct3DRM3.LoadFromFile 메소드 내부에서 오브젝트의 로드를 실시한다. 이 콜백은 어플리케이션으로 정의된다.

구문

object_CallbackRMLoad(Obj As DxVBLib.Direct3DRMObject,
  ByVal guid As String,
  ByVal userArgument As Object)

요소

object
Direct3DRMLoadCallback오브젝트를 나타내는오브젝트식.
Obj
로드 되는Direct3DRMObject 오브젝트.
guid
로드 되는 오브젝트의 글로벌 유니크 식별자(GUID).
userArgument
이 콜백에게 건네지는 어플리케이션 정의의 데이터.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

시스템은, 콜백을 사용하는 순서를 결정하기 (위해)때문에, 우선 계층의 톱 레벨에 있는 오브젝트를 검색한다. 다음에, 생성 된 차례로 콜백을 사용한다.

참조

Direct3DRM3.LoadFromFile

Direct3DRMLoadTextureCallback3.CallbackRMLoadTexture

LoadFromFile메소드의 내부에서, 텍스쳐 파일 (또는 리소스)의 실제의 read를 실시한다. 텍스쳐는, 2로 갈라지는 폭과 길이가 아니면 안된다. 이 콜백은 어플리케이션으로 정의된다.

구문

object_CallbackRMLoadTexture(ByVal textureName As String,
  ByVal userArgument As Object) As DxVBLib.Direct3DRMTexture3

요소

object
Direct3DRMLoadTextureCallback3오브젝트를 나타내는오브젝트식.
textureName
텍스쳐명에 포함되는 캐릭터 라인.
userArgument
이 콜백에게 건네지는 어플리케이션 정의의 데이터.

반환값

Direct3DRMTexture3 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

어플리케이션은, Microsoft® Windows®비트 맵(. bmp)나 휴대용 픽셀 맵 비트 맵(. ppm) P6형식 이외의 텍스쳐의 지원을 인플리맨트 하기 위한(해), 이 콜백을 사용할 수가 있다. P6포맷은, 색이미지의 바이노리필드 포맷이다

시스템은, 콜백을 사용하는 순서를 결정하기 (위해)때문에, 우선 계층의 톱 레벨에 있는 오브젝트를 검색한다. 다음에, 생성 된 차례로 콜백을 사용한다.

참조

Direct3DRM3.LoadFromFile ,Direct3DRMAnimationSet2.LoadFromFile ,Direct3DRMFrame3.LoadFromFile ,Direct3DRMMeshBuilder3.LoadFromFile


Visual Basic 인터페이스

Microsoft® Direct3D® 보관 유지 모드의 Microsoft Visual Basic®인터페이스는 다음과 같다.

  • Direct3DRM3
  • Direct3DRMAnimation2
  • Direct3DRMAnimationArray
  • Direct3DRMAnimationSet2
  • Direct3DRMClippedVisual
  • Direct3DRMDevice3
  • Direct3DRMDeviceArray
  • Direct3DRMFace2
  • Direct3DRMFaceArray
  • Direct3DRMFrame3
  • Direct3DRMFrameArray
  • Direct3DRMFrameInterpolator
  • Direct3DRMLight
  • Direct3DRMLightArray
  • Direct3DRMLightInterpolator
  • Direct3DRMMaterial2
  • Direct3DRMMaterialInterpolator
  • Direct3DRMMesh
  • Direct3DRMMeshBuilder3
  • Direct3DRMMeshInterpolator
  • Direct3DRMObject
  • Direct3DRMObjectArray
  • Direct3DRMPick2Array
  • Direct3DRMPickArray
  • Direct3DRMProgressiveMesh
  • Direct3DRMShadow2
  • Direct3DRMTexture3
  • Direct3DRMTextureInterpolator
  • Direct3DRMViewport2
  • Direct3DRMViewportArray
  • Direct3DRMViewportInterpolator
  • Direct3DRMVisual
  • Direct3DRMVisualArray
  • Direct3DRMWrap


Direct3DRM3

어플리케이션은,Direct3DRM3인터페이스를 사용해Direct3DRM3오브젝트를 생성해, 시스템 레벨 변수에 따라 동작한다.

Direct3DRM3 인터페이스의 메소드는, 다음의 오브젝트를 생성 한다.

  • 애니메이션과 애니메이션 세트
  • 클립 비주얼
  • 디바이스
  • 면
  • 프레임
  • 범비초기화 오브젝트
  • 조명
  • 머트리얼
  • 메쉬와 메쉬 빌더
  • 영
  • 텍스쳐
  • 뷰포트
  • 랩

어플리케이션은Direct3DRMDevice3 인터페이스를 사용해 출력 디바이스라고 대화한다. Direct3DRM3인터페이스를 사용해 생성 할 때의 출력 디바이스 기능의 상세한 것에 대하여는, 「Direct3DRMDevice3 」를 참조할것.

Direct3DRM3인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

애니메이션 | CreateAnimation
CreateAnimationSet
클립 비주얼 | CreateClippedVisual
디바이스 | CreateDeviceFromClipper
CreateDeviceFromD3D
CreateDeviceFromSurface
GetDevices
열거 | EnumerateObjects
면 | CreateFace
프레임 | CreateFrame
인타포레이타 | CreateInterpolatorFrame
CreateInterpolatorLight
CreateInterpolatorMaterial
CreateInterpolatorMesh
CreateInterpolatorTexture
CreateInterpolatorViewport
조명 | CreateLight
CreateLightRGB
머트리얼 | CreateMaterial
메쉬 | CreateMesh
CreateMeshBuilder
그 외 | GetNamedObject
GetOptions
LoadFromFile
SetOptions
Tick
프로그래시브 메쉬 | CreateProgressiveMesh
패스 검색 | AddSearchPath
GetSearchPath
SetSearchPath
영 | CreateShadow
텍스쳐 | CreateTextureFromSurface
LoadTexture
SetDefaultTextureColors
SetDefaultTextureShades
뷰포트 | CreateViewport
랩 | CreateWrap

Direct3DRM3.AddSearchPath

Direct3DRM3

현재의 파일 검색 패스의 마지막에 디렉토리의 리스트를 추가한다.

구문

object. AddSearchPath(name As String)

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
name
현재의 검색 패스에 추가하는 패스를 지정하는 캐릭터 라인.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

Microsoft® Windows®에서는, 패스는, 세미콜론(;)으로 단락지어진 리스트로 할 필요가 있다.

참조

Direct3DRM3.SetSearchPath

Direct3DRM3.CreateAnimation

Direct3DRM3

하늘의Direct3DRMAnimation2 오브젝트를 생성한다.

구문

object. CreateAnimation( ) As Direct3DRMAnimation2

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMAnimation2 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRM3.CreateAnimationSet

Direct3DRM3

하늘의Direct3DRMAnimationSet2 오브젝트를 생성 한다.

구문

object. CreateAnimationSet( ) As Direct3DRMAnimationSet2

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMAnimationSet2 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRM3.CreateClippedVisual

Direct3DRM3

Direct3DRMClippedVisual 오브젝트를 생성 한다.

구문

object. CreateClippedVisual(vis As Direct3DRMVisual)
  As Direct3DRMClippedVisual

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
vis
Direct3DRMMeshBuilder3 오브젝트등의Direct3DRMVisual 오브젝트.

반환값

Direct3DRMClippedVisual 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRM3.CreateDeviceFromClipper

Direct3DRM3

지정된DirectDrawClipper오브젝트를 사용해Direct3DRMDevice3 오브젝트를 생성 한다.

구문

object. CreateDeviceFromClipper(DDClipper As DirectDrawClipper,
  guid As String,
  width As Long,
  height As Long) As Direct3DRMDevice3

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
DDClipper
DirectDrawClipper오브젝트.
guid
글로벌 유니크 식별자(GUID). 이 파라미터는""으로 할 수 있다.
width, height
생성 하는 디바이스의 픽셀 단위의 폭과 높이.

반환값

Direct3DRMDevice3 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

guid파라미터가""의 경우, 시스템은, 디바이스 성능의 디폴트 세트를 검색한다. 이것은, 보관 유지 모드 디바이스를 생성하는 방법으로서 추천 한다. 왜냐하면, 유저가 새로운 하드웨어를 인스톨 했을 경우에서도, 항상 기능하기 때문이다.

시스템은, 내부 디바이스 열거의 호출로,D3DPRIMCAPS 형을 사용해, 디폴트 설정값을 기술한다.

하드웨어 데이 버스가 검출되지 않았던 경우에는, 흑백(램프)의 소프트웨어 드라이버가 로드 된다. 디폴트 설정값의 이 리스트에서는 채워지지 않은 특별한 요건이 있는 경우, 어플리케이션은,guid파라미터에 대해서""를 지정하는 대신에 디바이스를 열거할 필요가 있다. guid파라미터에""를 지정 하면, 사용 가능한 것이 있으면 하드웨어 디바이스가 선택되지 않으면 디폴트로 소프트웨어 래스터라이저로 설정된다.

디바이스를 지정하려면 ,GetDirect3D메소드를 호출해, DirectDraw4를 개입시켜 Direct3D3 오브젝트를 취득하는 것으로 적절한 GUID를 검색한다. 다음에, Direct3D3 오브젝트 위에의GetDevicesEnum를 호출해 Direct3DEnumDevices 오브젝트를 취득한다. Direct3DEnumDevices 오브젝트로부터, GUID를 디바이스의 기술과 기능에 맞출 수가 있다.

디바이스의 상세한 것에 대하여는, 「Direct3DRMDevice3 」를 참조할것.

Direct3DRM3.CreateDeviceFromD3D

Direct3DRM3

지정된 Direct3D를 사용해 Direct3D 보관 유지 모드 Windows 디바이스를 생성한다.

구문

object. CreateDeviceFromD3D(D3D As Direct3D3,
  dev As Direct3DDevice3) As Direct3DRMDevice3

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
D3D
Direct3D3직접 모드 오브젝트의 인스턴스.
dev
Direct3DDevice3직접 모드 디바이스 오브젝트.

반환값

Direct3DRMDevice3 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

디바이스의 상세한 것에 대하여는, 「Direct3DRMDevice3 」를 참조할것.

Direct3DRM3.CreateDeviceFromSurface

Direct3DRM3

지정된 DirectDraw 표면으로부터 렌더링하기 위한 Direct3D 보관 유지 모드 Windows 디바이스를 생성한다.

구문

object. CreateDeviceFromSurface(g As String,
  dd As DirectDraw4,
  ddS As DirectDrawSurface4,
  flags As CONST_D3DRMCREATEDEVICEFLAGS) As Direct3DRMDevice3

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
g
요구된 디바이스 드라이버로서 사용되는 글로벌 유니크 식별자(GUID). 이 파라미터가""의 경우, 디폴트의 디바이스 드라이버가 사용된다.
dd
DirectDraw 표면의 소스인DirectDraw4오브젝트
ddS
백 버퍼를 나타내는DirectDrawSurface4오브젝트
flags
CONST_D3DRMCREATEDEVICEFLAGS 열거형으로부터의 하나 이상의 값.

반환값

Direct3DRMDevice3 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

디바이스의 상세한 것에 대하여는, 「Direct3DRMDevice3 」를 참조할것.

Direct3DRM3.CreateFace

Direct3DRM3

Direct3DRMFace2 인터페이스의 인스턴스를 생성한다.

구문

object. CreateFace( ) As Direct3DRMFace2

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMFace2 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRM3.CreateFrame

Direct3DRM3

지정의 친프레임의 새로운 아이 프레임을 생성한다.

구문

object. CreateFrame(parent As Direct3DRMFrame3) As Direct3DRMFrame3

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
parent
새로운 프레임의 부모가 되는Direct3DRMFrame3 오브젝트.

반환값

Direct3DRMFrame3오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

아이 프레임은, 그 부모로부터 운동 속성을 계승한다. 예를 들어, 부모가 일정한 속도로 움직이고 있을 때는, 아이 프레임도 같은 속도로 움직인다. 게다가 부모에게 회전이 세트 되면(자), 아이 프레임은, 부모의 원점의 주위를 회전한다. 부모를 가지지 않는 프레임은, 장면으로 불린다. 장면을 생성 하려면 , 부모로서 NOTHING를 지정한다. 어플리케이션은, 부모가 없는 프레임을 생성 한 후,Direct3DRMFrame3.AddChild 메소드를 사용해, 다음에 친프레임에 관련시킬 수가 있다.

어플리케이션이 오른손 지오메트리를 세트 하기 위해서Direct3DRM3.SetOptions 를 호출했을 경우,루트 프레임 (부모로서 NOTHING를 가지는 프레임)의 디폴트축은, v = (0, 0, -1) 또한 u = (0, 1, 0)가 된다. 이 때문에,Direct3DRMFrame3.GetOrientation 와Direct3DRMFrame3.SetOrientation 는, 오른손 모드로 올바르게 기능한다.

Direct3DRM3.CreateInterpolatorFrame

Direct3DRM3

Direct3DRMFrameInterpolator 인터페이스의 인스턴스를 생성한다.

구문

object. CreateInterpolatorFrame( ) As Direct3DRMFrameInterpolator

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMFrameInterpolator오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRM3.CreateInterpolatorLight

Direct3DRM3

Direct3DRMLightInterpolator 인터페이스의 인스턴스를 생성한다.

구문

object. CreateInterpolatorLight( ) As Direct3DRMLightInterpolator

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMLightInterpolator오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRM3.CreateInterpolatorMaterial

Direct3DRM3

Direct3DRMMaterialInterpolator 인터페이스의 인스턴스를 생성한다.

구문

object. CreateInterpolatorMaterial( ) As Direct3DRMMaterialInterpolator

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMMaterialInterpolator오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRM3.CreateInterpolatorMesh

Direct3DRM3

Direct3DRMMeshInterpolator 인터페이스의 인스턴스를 생성한다.

구문

object. CreateInterpolatorMesh( ) As Direct3DRMMeshInterpolator

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMMeshInterpolator오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRM3.CreateInterpolatorTexture

Direct3DRM3

Direct3DRMTextureInterpolator 인터페이스의 인스턴스를 생성한다.

구문

object. CreateInterpolatorTexture( ) As Direct3DRMTextureInterpolator

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMTextureInterpolator오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRM3.CreateInterpolatorViewport

Direct3DRM3

Direct3DRMViewportInterpolator 인터페이스의 인스턴스를 생성한다.

구문

object. CreateInterpolatorViewport( ) As Direct3DRMViewportInterpolator

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMViewportInterpolator오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRM3.CreateLight

Direct3DRM3

지정의 타입과 색으로, 새로운 조명을 생성 한다.

구문

object. CreateLight(lt As CONST_D3DRMLIGHTTYPE,
  color As Long) As Direct3DRMLight

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
lt
CONST_D3DRMLIGHTTYPE 열거형으로 주어지는 조명 타입의 하나.
color
조명의 색을 나타내는 4바이트의Long값. 마지막 3바이트는, 색의 RGB 요소를 나타낸다. 색의Long값을 돌려주기 위해서(때문에), DirectX 7 오브젝트의CreateColorRGB를 사용할 수 있다. 다른 조명 타입의 기술에 대해서는, Direct3D 보관 유지 모드의 C++에 관한 메뉴얼의 개요 섹션을 참조할것.

반환값

Direct3DRMLight 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRM3.CreateLightRGB

Direct3DRM3

지정의 적, 초록, 파랑의 요소로, 새로운 조명을 생성 한다.

구문

object. CreateLightRGB(lt As CONST_D3DRMLIGHTTYPE,
  vred As Single,
  vgreen As Single,
  vblue As Single) As Direct3DRMLight

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
lt
CONST_D3DRMLIGHTTYPE 열거형으로 주어지는 조명 타입의 하나.
vred, vgreen, vblue
조명의 색. 색의 각 요소는, 0.0에서 1.0의 범위에 있을 필요가 있다.

반환값

Direct3DRMLight 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRM3.CreateMaterial

Direct3DRM3

C지정의반사 프로퍼티를 가지는 머트리얼을 생성 한다.

구문

object. CreateMaterial(d As Single) As Direct3DRMMaterial2

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
d
반사하는 하이라이트의 날카로움. 렌더링 하는 표면에, 5의 값은 금속의 외관을 주어보다 큰 값은 보다 플라스틱적인 외관을 준다.

반환값

Direct3DRMMaterial2 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRM3.CreateMesh

Direct3DRM3

면을 갖지 않는 새로운 메쉬 오브젝트를 생성한다. 이 메쉬는, 프레임에 추가될 때까지는 눈에 보이지 않는다.

구문

object. CreateMesh( ) As Direct3DRMMesh

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMMesh 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRM3.CreateMeshBuilder

Direct3DRM3

새로운 메쉬 빌더 오브젝트를 생성한다.

구문

object. CreateMeshBuilder( ) As Direct3DRMMeshBuilder3

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMMeshBuilder3 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

디폴트에서는, 퍼스펙티브 보정이온이다.

Direct3DRM3.CreateProgressiveMesh

Direct3DRM3

면을 갖지 않는 새로운 프로그래시브 메쉬 오브젝트를 생성한다. 메쉬는, 프레임에 추가될 때까지 눈에 보이지 않는다.

구문

object. CreateProgressiveMesh( ) As Direct3DRMProgressiveMesh

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMProgressiveMesh 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRM3.CreateShadow

Direct3DRM3

지정의 비주얼과 조명을 사용해 그림자를 생성 해, 지정의 평면에 그 그림자를 투영 한다. 그림자도 일종의 비주얼이며, 비주얼을 포함한 프레임에 추가할 필요가 있다.

구문

object. CreateShadow(visual As Direct3DRMVisual,
  light As Direct3DRMLight,
  px As Single,
  py As Single,
  pz As Single,
  nx As Single,
  ny As Single,
  nz As Single) As Direct3DRMShadow2

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
visual
Direct3DRMVisual 오브젝트.
light
조명인Direct3DRMLight 오브젝트.
px, py, pz
그림자가 투영 되는 평면.
nx, ny, nz
그림자가 투영 되는 평면에 대한 법선.

반환값

Direct3DRMShadow2 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRM3.CreateTextureFromSurface

Direct3DRM3

지정된 DirectDraw 표면으로부터 텍스쳐를 생성 한다.

구문

object. CreateTextureFromSurface(
    ddS As DirectDrawSurface4)
    As Direct3DRMTexture3

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
ddS
텍스쳐를 저장 하는DirectDrawSurface4오브젝트.

반환값

Direct3DRMTexture3 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRM3.CreateViewport

Direct3DRM3

디바이스 좌표가(x, y)로부터(x + w, y + h)까지의 디바이스상에서, 뷰포트를 생성 한다.

구문

object. CreateViewport(dev As Direct3DRMDevice3,
  fr As Direct3DRMFrame3,
  x As Long,
  y As Long,
  w As Long,
  h As Long) As Direct3DRMViewport2

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
dev
뷰포트의 생성처인Direct3DRMDevice3 오브젝트.
fr
뷰의 위치와 방향을 기술하는Direct3DRMFrame3 오브젝트.
x, y, w, h
디바이스 좌표에서의 뷰포트의 위치와 사이즈. 뷰포트 사이즈는 물리 디바이스보다 크게 할 수 없다. 크고 하면, 메소드는 실패에 끝난다.

반환값

Direct3DRMViewport2 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

뷰포트는,카메라 (fr)를 포함한 장면 중(안)에서, 카메라로부터 취한 뷰 방향과 업 벡터를 사용해 오브젝트를 표시한다. 뷰포트 사이즈는, 물리 디바이스보다 크게 할 수 없다.

디바이스의 상세한 것에 대하여는, 「Direct3DRMDevice3 」를 참조할것.

Direct3DRM3.CreateWrap

Direct3DRM3

면과 메쉬에 텍스쳐 좌표를 할당하는데 사용할 수 있는 랩핑 함수를 생성 한다.

구문

object. CreateWrap(t As CONST_D3DRMWRAPTYPE,
  f As Direct3DRMFrame3,
  ox As Single,
  oy As Single,
  oz As Single,
  dx As Single,
  dy As Single,
  dz As Single,
  ux As Single,
  uy As Single,
  uz As Single,
  ou As Single,
  ov As Single,
  su As Single,
  sv As Single) As Direct3DRMWrap

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
t
CONST_D3DRMWRAPTYPE 열거형의 멤버의 하나.
f
랩의 참조Direct3DRMFrame3 오브젝트.
ox, oy, oz
랩의 원점.
dx, dy, dz
랩의 z축.
ux, uy, uz
랩의 y축.
ou, ov
텍스쳐의 원점.
su, sv
텍스쳐의 스케일 계수.

반환값

Direct3DRMWrap 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

랩의 기술에 대해서는, Direct3D 보관 유지 모드의 C++에 관한 메뉴얼의 개요 섹션을 참조할것.

Direct3DRM3.EnumerateObjects

Direct3DRM3

액티브한 Direct3D 보관 유지 모드의 오브젝트상으로 지정되는 콜백을 사용한다.

구문

object. EnumerateObjects(
    enumerateObjectsImplementation As Direct3DRMEnumerateObjectsCallback,
    userArgument As object)

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
enumerateObjectsImplementation
각Direct3DRMObject 오브젝트 및 어플리케이션 정의 인수에 의해 사용되는 어플리케이션 정의의Direct3DRMEnumerateObjectsCallback 콜백 인터페이스.
userArgument
콜백에게 건네지는 어플리케이션 정의 데이터.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRM3.GetDevices

Direct3DRM3

시스템으로 생성 된 모든 Direct3D 보관 유지 모드 디바이스를 취득한다.

구문

object. GetDevices( ) As Direct3DRMDeviceArray

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMDeviceArray 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRM3.GetNamedObject

Direct3DRM3

지정의 이름으로Direct3DRMObject 오브젝트를 검색한다.

구문

object. GetNamedObject(name As String) As Direct3DRMObject

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
name
검색하는 오브젝트의 이름.

반환값

Direct3DRMObject 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

시스템이name파라미터로 지정한 이름의 오브젝트를 발견하지 않았던 경우에, 이 메소드는, D3DRM_OK를 돌려주지만,name파라미터는""된다.

례

Set O = rm.GetNamedObject("object")
If O is Nothing then
    Debug.Print "Object not found"
End If

Direct3DRM3.GetOptions

Direct3DRM3

Direct3D 보관 유지 모드로 왼손 또는 오른손 지오메트리의 어느 쪽을 사용하는지를 취득한다.

구문

object. GetOptions( ) As CONST_D3DRMHANDEDNESS

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.

반환값

현재의 Direct3D 보관 유지 모드 옵션을 나타내는CONST_D3DRMHANDEDNESS 열거형으로부터 값을 돌려준다.

에러값

에러가 발생했을 경우는,DDERR_INVALIDOBJECT 또는DDERR_INVALIDPARAMS 를 돌려준다.

참조

Direct3DRM3.SetOptions

Direct3DRM3.GetSearchPath

Direct3DRM3

현재의 검색 패스를 돌려준다. Windows에서는, 패스는, 세미콜론(;)으로 단락지어진 디렉토리의 리스트이다.

구문

object. GetSearchPath( ) As String

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.

반환값

캐릭터 라인으로 현재의 검색 패스를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRM3.SetSearchPath

Direct3DRM3.LoadFromFile

Direct3DRM3

오브젝트를 로드한다.

구문

object. LoadFromFile(filename As String,
  id As String,
  guidArray() As String,
  count As Long,
  options As CONST_D3DRMLOADFLAGS,
  loadCallbackImplementation As Direct3DRMLoadCallback,
  loadArgument As object,
  loadTextureImplementation As Direct3DRMLoadTextureCallback3,
  loadTextureArgument As object,
  parentFrame As Direct3DRMFrame3)

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
filename
파일의 풀 패스.
id
로드하는 오브젝트의 이름 또는 위치. id가""의 경우,options파라미터를D3DRMLOAD_FIRST로 설정해야 한다. Microsoft Visual Basic® 는,String 데이터형이 지정되고 있는 경우에서도, 로드하는 아이템의 위치를 나타내는id파라미터안의Integer를 받아들인다. 예를 들어,id파라미터에1이 설정되어 있으면(자), 1번째의 위치의 오브젝트가 로드 된다.
guidArray
로드하는 인터페이스 식별자. 예를 들어, 이 파라미터가IID_Direct3DRMMeshBuilder3및IID_Direct3DRMAnimationSet2를 저장 하는 2개의 요소의 배열이면, 이 메소드는, 모든 애니메이션 세트 오브젝트와 메쉬 빌더 오브젝트를 로드한다. 가능한 GUID는,IID_Direct3DRMProgressiveMesh,IID_Direct3DRMMeshBuilder3,IID_Direct3DRMAnimationSet2,IID_Direct3DRMAnimation2,IID_Direct3DRMFrame3안의 1개이상이 아니면 안된다. 「주의」를 참조할것.
count
guidArray파라미터로 지정되고 있는 요소의 수.
options
로드 옵션을 기술하는CONST_D3DRMLOADFLAGS 열거형의 하나 이상의 값.
loadCallbackImplementation
시스템이 지정의 오브젝트를 읽어들였을 때에 사용되는Direct3DRMLoadCallback 콜백 인터페이스.
loadArgument
Direct3DRMLoadCallback콜백 인터페이스에게 건네지는 어플리케이션 정의 데이터.
loadTextureImplementation
Direct3DRMLoadTextureCallback3 콜백 인터페이스. 이것은, 특별한 포맷을 필요로 하는 오브젝트가 이용하는 텍스쳐를 읽어낼 때 불려 간다. 텍스쳐는 2로 갈라지는 폭과 길이가 아니면 안된다. 이 파라미터에는 NOTHING를 지정할 수가 있다.
loadTextureArgument
Direct3DRMLoadTextureCallback3콜백 인터페이스에게 건네지는 어플리케이션 정의 데이터.
parentFrame
친Direct3DRMFrame3 오브젝트. 이 인수는, 애니메이션 세트의 로드에만 영향을 준다. X파일로부터 로드 된 애니메이션이, X파일중의 부모가 없는 프레임을 참조 하면나무는, 그 부모에게는,f가 세트 된다. 다만, X파일중의 임의의 프레임을 로드하도록(듯이),LoadFromFile가 세트 된다. 다만, X파일중의 임의의 프레임을 로드하도록(듯이),parentFrame는, 부모가 없는 X파일중의 프레임에 대한 친프레임으로서 사용될 것은 없다. 즉,parentFrame는, 애니메이션 세트를 로드했을 때에 한계 사용된다. f파라미터는 NOTHING로 할 수 있다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

디폴트에서는, 퍼스펙티브 보정이온이다.

각LoadFromFile메소드는,filename파라미터를 사용해 오브젝트의 소스를 지정해,id파라미터에 의해 오브젝트를 식별한다. 시스템은 소스 플래그의 선택에 근거해filename파라미터를 해석한다. 그리고, 식별자 플래그의 선택에 근거해id파라미터의 내용을 해석한다.

인스턴스 플래그는, 파라미터의 해석 방법에는 아무것도 변경을 더하지 않는다. D3DRMLOAD_INSTANCEBYREFERENCE플래그를 이용하면(자), 새로운 오브젝트를 생성 하는 일 없이 같은 파일을 2회 로드할 수가 있다. 오브젝트가 이름을 가지고 있지 않은 경우,D3DRMLOAD_INSTANCEBYREFERENCE플래그를 세트 하면,D3DRMLOAD_INSTANCEBYCOPYING플래그를 세트 했을 때와 같은 효과를 얻을 수 있다. 로더는, 동일한 오브젝트가 존재해도, 각 이름 없음 오브젝트를 새로운 오브젝트로서 생성 한다.

주의

count값이 3의 경우,guidArray는 다음과 같이 된다.

Dim guidArray(3) As String

guidArray(0)="IID_Direct3DRMMeshBuilder3"
guidArray(1)="IID_Direct3DRMFrame3"
guidArray(2)="IID_Direct3DRMAnimationSet2"

Direct3DRM3.LoadTexture

Direct3DRM3

지정 파일로부터Direct3DRMTexture3 텍스쳐를 로드한다. 이 텍스쳐는, 8, 24, 또는 32 비트/픽셀을 취할 수가 있다. 그 포맷은, Windows 비트 맵(. bmp)인가 Portable Pixmap (. ppm) P6포맷의 어딘가에 할 필요가 있다.

구문

object. LoadTexture(name As String) As Direct3DRMTexture3

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
name
필요한. bmp 또는. ppm 파일의 이름

반환값

Direct3DRMTexture3 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

LoadTexture는, 텍스쳐가 BMP 포맷일까 PPM 포맷인지를 체크한다. LoadTexture는, 양포맷을 로드할 수가 있다.

Direct3DRM3.SetDefaultTextureColors

Direct3DRM3

Direct3DRMTexture3 오브젝트로 사용하는 디폴트의 색을 설정한다.

구문

object. SetDefaultTextureColors(numTextureColors As Long)

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
numTextureColors
색 가지수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRM3.CreateTextureFromSurface 메소드의 전에 사용되었을 때에 한계 텍스쳐의 색에 영향을 준다. 이미 생성 되고 있는 텍스쳐에는, 아무 효과도 없다.

Direct3DRM3.SetDefaultTextureShades

Direct3DRM3

Direct3DRMTexture3 오브젝트에 대해서 사용하는 디폴트의 쉐이드를 설정한다.

구문

object. SetDefaultTextureShades(numTextureShades As Long)

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
numTextureShades
쉐이드수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRM3.CreateTextureFromSurface 메소드의 전에 사용되었을 때에 한계 텍스쳐의 쉐이드에 영향을 준다. 이미 생성 되고 있는 텍스쳐에는, 아무 효과도 없다.

Direct3DRM3.SetOptions

Direct3DRM3

Direct3D 보관 유지 모드로 왼손 또는 오른손 지오메트리의 어느 쪽을 사용하는지를 설정한다.

구문

object. SetOptions(options As CONST_D3DRMHANDEDNESS)

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
options
현재의 Direct3D 보관 유지 모드 옵션을 나타내는CONST_D3DRMHANDEDNESS 로부터의 값.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRM3.GetOptions

Direct3DRM3.SetSearchPath

Direct3DRM3

디렉토리의 리스트로부터 현재의 파일 검색 패스를 설정한다. Windows에서는, 패스는, 세미콜론(;)으로 단락지어진 리스트로 할 필요가 있다.

구문

object. SetSearchPath(name As String)

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
name
현재의 검색 패스로 해서 설정하는 패스의 캐릭터 라인.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRM3.GetSearchPath

Direct3DRM3.Tick

Direct3DRM3

시스템의 하트 비트를 실시한다. 이 메소드가 사용되면(자), 모든 가동 프레임의 위치는, 현재의 운동 속성에 따라 갱신되어 장면이 현재의 디바이스에 렌더링 된다. 또, 관련한 콜백이, 적절한 타이밍에 불려 간다. 이 메소드는, 렌더링 사이클이 완료했을 때에 제어를 돌려준다.

구문

object. Tick(tic As Single)

요소

object
Direct3DRM3오브젝트를 나타내는오브젝트식.
tic
임의의 단위를 나타내는 값. 예를 들어, 속도를 1,0,0으로 설정해 ( 「Direct3DRMFrame3.SetVelocity 」를 참조), 틱값 (tic)을 1으로 설정 하면, 애니메이션은 x방향으로 1단위 이동한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

장면의 렌더링에 유연성을 갖게하기 (위해)때문에, 보관 유지 모드의 다른 메소드를 사용해, 이 메소드를 이행 할 수도 있다.

  • Direct3DRMFrame3.SetRotation
  • Direct3DRMFrame3.SetVelocity
  • Direct3DRMFrame3.Move


Direct3DRMAnimation2

어플리케이션은Direct3DRMAnimation2인터페이스의 메소드를 이용해, 위치, 향해, 비주얼 오브젝트의 스케일링, 조명, 뷰포트의 애니메이션을 실시할 수가 있다.

보관 유지 모드의 애니메이션은,키세트에 의해 정의된다. 키는 스케일링 조작, 방향, 또는 위치에 관련지을 수 있었던 시간값이다. Direct3DRMAnimation오브젝트는, 시간값에 응한 변환의 수정 방법을 정의한다. 애니메이션을Direct3DRMFrame 오브젝트상에서 동작하도록(듯이) 세트 해,Direct3DRMVisual ,Direct3DRMLight 및Direct3DRMViewport 오브젝트의 위치, 방향, 스케일링의 애니메이션을 실시하기 위해서(때문에) 사용할 수가 있다.

Direct3DRMAnimation2.AddPositionKey ,AddRotateKey 및AddScaleKey 의 각 메소드는, 단위가 임의의 시간값을 지정한다. 어플리케이션이 시간값 99의 위치 키를 추가했을 경우, 예를 들어, 시간값 49의 새로운 위치 키는, 애니메이션의 (제로를 기준으로 한) 시작점과 최초의 위치 키와의 사이의 정확히 중간으로 발생한다.

애니메이션의 조작은,Direct3DRMAnimation2.SetTime 메소드를 호출하는 것으로 행해진다. 이것은, 비주얼 오브젝트의 변환을 애니메이션중의 가까이의 키의 보간 위치, 방향, 스케일에 세트 한다. 애니메이션 키를 추가하는 메소드와 같게,SetTime의 시간값은, 어플리케이션이 이미 추가 끝난 키 위치에 근거하는 임의의 값이다.

IDirect3DRMAnimation2인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

키 | AddKey
 | AddPositionKey
 | AddRotateKey
 | AddScaleKey
 | DeleteKey
 | DeleteKeyByID
 | GetKeys
 | GetKeysCount
 | ModifyKey
그 외 | GetFrame
 | SetFrame
 | SetTime
옵션 | GetOptions
 | SetOptions

Direct3DRMAnimation2인터페이스는,Direct3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.

  • AddDestroyCallback
  • CloneObject
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMAnimation오브젝트는,Direct3DRM3.CreateAnimation 메소드의 호출에 의해 취득할 수 있다.

Direct3DRMAnimation2.AddKey

Direct3DRMAnimation2

새로운 키를 추가한다.

구문

object. AddKey(key As D3DRMANIMATIONKEY)

요소

object
Direct3DRMAnimation2오브젝트를 나타내는오브젝트식.
key
새로운 키를 정의하는D3DRMANIMATIONKEY 의 타입. 타입의id멤버는 무시되어 돌아가는 시점에서 새로운 키의 ID가 세트 된다.

에러값

에러가 발생했을 경우는,DDERR_INVALIDOBJECT 또는DDERR_INVALIDPARAMS 를 돌려준다.

Direct3DRMAnimation2.AddPositionKey

Direct3DRMAnimation2

애니메이션에 위치 키를 추가한다.

구문

object. AddPositionKey(time As Single,
  x As Single,
  y As Single,
  z As Single)

요소

object
Direct3DRMAnimation2오브젝트를 나타내는오브젝트식.
time
애니메이션 중(안)에서 위치 키를 설정 하면나무의 시간. 0을 원점으로 하는 임의의 단위의 시간을 지정할 수가 있다. 마지막 키의time의 값이 99 때,time가 49인 키가 애니메이션의 정확히 중간이다.
x, y, z
애니메이션에 추가하는 위치 키의 좌표.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드에 의해 적용되는 변환은 평행이동이다. 점 (x, y, z)은 새로운 점 (x', y', z')에 평행이동 한다.

점을 평행이동 하는 행렬.

참조

Direct3DRMAnimation2.DeleteKey

Direct3DRMAnimation2.AddRotateKey

Direct3DRMAnimation2

애니메이션에 회전 키를 추가한다.

구문

object. AddRotateKey(time As Single,
  q As D3DRMQUATERNION)

요소

object
Direct3DRMAnimation2오브젝트를 나타내는오브젝트식.
time
애니메이션 중(안)에서 회전 키를 설정 하면나무의 시간. 0을 기준으로 하는 임의의 단위의 시간을 지정할 수가 있다. 마지막 키의time의 값이 99 때,time가 49인 키가 애니메이션의 정확히 중간이다.
q
회전을 나타내는D3DRMQUATERNION 의 타입.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드에 의해, 회전 변환이 적용된다.

참조

Direct3DRMAnimation2.DeleteKey

Direct3DRMAnimation2.AddScaleKey

Direct3DRMAnimation2

애니메이션에 스케일 키를 추가한다.

구문

object. AddScaleKey(time As Single,
  x As Single,
  y As Single,
  z As Single)

요소

object
Direct3DRMAnimation2오브젝트를 나타내는오브젝트식.
time
애니메이션 중(안)에서 스케일 키를 기억 하면나무의 시간. 0을 원점으로 하는 임의의 단위의 시간을 지정할 수 있다. 마지막 키의time의 값이 99 때,time가 49인 키가 애니메이션의 정확히 중간이다.
x, y, z
애니메이션에 추가하는 스케일 키의 좌표.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드에 의해, 스케일 변환이 적용된다.

참조

Direct3DRMAnimation2.DeleteKey

Direct3DRMAnimation2.DeleteKey

Direct3DRMAnimation2

키를 애니메이션으로부터 삭제한다. 예를 들어, 애니메이션에 시간t의 스케일 키와 시간t의 회전 키가 있는 경우, 양쪽 모두의 키가 삭제된다.

구문

object. DeleteKey(time As Single)

요소

object
Direct3DRMAnimation2오브젝트를 나타내는오브젝트식.
time
애니메이션으로부터 삭제되는 키를 식별하는 시간.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMAnimation2.DeleteKeyByID

Direct3DRMAnimation2

고유의 ID에 대응하는 키를 삭제한다.

구문

object. DeleteKeyByID(id As Long)

요소

object
Direct3DRMAnimation2오브젝트를 나타내는오브젝트식.
id
삭제하는 키의 ID.

에러값

에러가 발생했을 경우는, 다음의 값 가운데 하나를 돌려준다.

  • D3DRMERR_NOSUCHKEY
  • DDERR_INVALIDOBJECT
  • DDERR_INVALIDPARAMS

Direct3DRMAnimation2.GetFrame

Direct3DRMAnimation2

애니메이션에 대응하는 프레임을 꺼낸다.

구문

object. GetFrame( ) As Direct3DRMFrame3

요소

object
Direct3DRMAnimation2오브젝트를 나타내는오브젝트식.

반환값

애니메이션이 참조하는 현재의Direct3DRMFrame 오브젝트의 인터페이스를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMAnimation2.GetKeys

Direct3DRMAnimation2

고유의 시간에 대응하는 키를 꺼낸다.

구문

object. GetKeys(timeMin As Single,
  timeMax As Single,
  keyArray() As D3DRMANIMATIONKEY)

요소

object
Direct3DRMAnimation2오브젝트를 나타내는오브젝트식.
timeMin
돌려주어지는 키의 최소 시간값.
timeMax
돌려주어지는 키의 최대 시간값.
keyArray
키값이 세트 되는D3DRMANIMATIONKEY 의 타입의 배열.

에러값

에러가 발생했을 경우는, 다음의 값 가운데 하나를 돌려준다.

  • D3DRMERR_NOSUCHKEY
  • DDERR_INVALIDOBJECT
  • DDERR_INVALIDPARAMS
  • DD_OK

Direct3DRMAnimation2.GetKeysCount

Direct3DRMAnimation2

2개의 고유의 시간의 사이에 있는 키를 취득한다.

구문

object. GetKeysCount(timeMin As Single,
  timeMax As Single) As Long

요소

object
Direct3DRMAnimation2오브젝트를 나타내는오브젝트식.
timeMin
돌려주어지는 키의 최소 시간값.
timeMax
돌려주어지는 키의 최대 시간값.

반환값

timeMin와timeMax의 사이에 있는 키의 수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMAnimation2.GetOptions

Direct3DRMAnimation2

애니메이션 옵션을 취득한다.

구문

object. GetOptions( ) As CONST_D3DRMANIMATIONFLAGS

요소

object
Direct3DRMAnimation2오브젝트를 나타내는오브젝트식.

반환값

애니메이션 옵션을 나타내는CONST_D3DRMANIMATIONFLAGS 열거의 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMAnimation2.SetOptions

Direct3DRMAnimation2.ModifyKey

Direct3DRMAnimation2

키값을 수정한다.

구문

object. ModifyKey(key As D3DRMANIMATIONKEY)

요소

object
Direct3DRMAnimation2오브젝트를 나타내는오브젝트식.
key
기존의 키의 값을 정의하는D3DRMANIMATIONKEY 의 타입. 구조체의ID멤버는, 기존의 키가 아니면 안된다.

에러값

에러가 발생했을 경우는, 다음의 값 가운데 하나를 돌려준다.

  • D3DRMERR_INCOMPATIBLEKEY
  • D3DRMERR_NOSUCHKEY
  • DDERR_INVALIDOBJECT
  • DDERR_INVALIDPARAMS

주의

키의 타입을 수정할 수 없다. 키의 타입을 변경하려면 , 오리지날 키를 삭제해, 새로운 키를 추가해야 한다. 키의 시간, 위치, 회전, 및 스케일값을 수정할 수 있다.

Direct3DRMAnimation2.SetFrame

Direct3DRMAnimation2

애니메이션에 프레임을 설정한다.

구문

object. SetFrame(frame As Direct3DRMFrame3)

요소

object
Direct3DRMAnimation2오브젝트를 나타내는오브젝트식.
frame
애니메이션으로 설정하는Direct3DRMFrame3 오브젝트를 지정하는 변수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMAnimation2.SetOptions

Direct3DRMAnimation2

애니메이션 옵션을 설정한다.

구문

object. SetOptions(flags As CONST_D3DRMANIMATIONFLAGS)

요소

object
Direct3DRMAnimation2오브젝트를 나타내는오브젝트식.
flags
애니메이션 옵션을 지정하는CONST_D3DRMANIMATIONFLAGS 열거의 하나 또는 복수의 값.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMAnimation2.GetOptions

Direct3DRMAnimation2.SetTime

Direct3DRMAnimation2

애니메이션에 현재의 시간을 설정한다.

구문

object. SetTime(time As Single)

요소

object
Direct3DRMAnimation2오브젝트를 나타내는오브젝트식.
time
애니메이션으로 설정하는 새로운 현재의 시간. 0을 원점으로 하는 임의의 단위의 시간을 지정할 수가 있다. 마지막 키의time의 값이 99 때,time가 49인 키가 애니메이션의 정확히 중간이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.


Direct3DRMAnimationArray

Direct3DRMAnimationArray인터페이스는, 배열중의 애니메이션의 수를 꺼내, 인터페이스에 애니메이션의 실행을 요구할 수 있도록(듯이) 한다. 애니메이션의 배열은 0이 기준이 되어 있다(0~N-1).

이 인터페이스는,GetElement 및GetSize 메소드를 지원 한다.

Direct3DRMAnimationArray.GetElement

Direct3DRMAnimationArray

요구된 애니메이션에 대한 인터페이스를 취득한다.

구문

object. GetElement( ) As Direct3DRMAnimation2

요소

object
Direct3DRMAnimationArray오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMAnimation2 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMAnimationArray.GetSize

Direct3DRMAnimationArray

배열중의 애니메이션의 수를 취득한다.

구문

object. GetSize( ) As Long

요소

object
Direct3DRMAnimationArray오브젝트를 나타내는오브젝트식.

반환값

애니메이션의 수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.


Direct3DRMAnimationSet2

Direct3DRMAnimationSet2오브젝트에 의해,Direct3DRMAnimation2 오브젝트를 그룹에 정리할 수가 있다. 이것으로, 애니메이션 세트중의 모든 애니메이션이 같은 시간 파라미터를 공유해, 복잡하게 분할된 애니메이션의 흐름을 간단하게 재생할 수 있게 된다. 어플리케이션은,Direct3DRMAnimationSet2.AddAnimation 메소드를 사용해 애니메이션을 애니메이션 세트에 추가해,Direct3DRMAnimationSet2.DeleteAnimation 메소드를 사용해 그것을 삭제할 수 있다. 애니메이션 세트는,Direct3DRMAnimationSet2.SetTime 메소드를 호출하는 것으로 조작한다.

Direct3DRMAnimationSet2인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

추가, 삭제, 취득, 로드 | AddAnimation
DeleteAnimation
GetAnimations
LoadFromFile
시간 | SetTime

Direct3DRMAnimationSet2인터페이스는,Direct3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.

AddDestroyCallback
CloneObject
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMAnimationSet2오브젝트는,Direct3DRM3.CreateAnimationSet 메소드의 호출에 의해 취득할 수 있다.

Direct3DRMAnimationSet2.AddAnimation

Direct3DRMAnimationSet2

애니메이션을 애니메이션 세트에 추가한다.

구문

object. AddAnimation(aid As Direct3DRMAnimation2)

요소

object
Direct3DRMAnimationSet2오브젝트를 나타내는오브젝트식.
aid
애니메이션 세트에 추가하는Direct3DRMAnimation2 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMAnimationSet2.DeleteAnimation

Direct3DRMAnimationSet2

애니메이션을 애니메이션 세트로부터 삭제한다.

구문

object. DeleteAnimation(aid As Direct3DRMAnimation2)

요소

object
Direct3DRMAnimationSet2오브젝트를 나타내는오브젝트식.
aid
애니메이션 세트로부터 삭제되는Direct3DRMAnimation2 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMAnimationSet2.GetAnimations

Direct3DRMAnimationSet2

애니메이션 세트중의 애니메이션을 포함한 배열을 꺼낸다.

구문

object. GetAnimations( ) As Direct3DRMAnimationArray

요소

object
Direct3DRMAnimationSet2오브젝트를 나타내는오브젝트식.

반환값

애니메이션 세트중의 애니메이션에 액세스 할 수 있도록(듯이) 하는Direct3DRMAnimationArray 인터페이스를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMAnimationSet2.LoadFromFile

Direct3DRMAnimationSet2

애니메이션 세트를 로드한다.

구문

object. LoadFromFile(filename As String,
  id As String,
  options As CONST_D3DRMLOADFLAGS,
  loadTextureImplementation As Direct3DRMLoadTextureCallback3,
  userArgument As object,
  parentFrame As Direct3DRMFrame3)

요소

object
Direct3DRMAnimationSet2오브젝트를 나타내는오브젝트식.
filename
오브젝트가 로드 되는 소스에의 포인터. flags파라미터가 가리키는 소스 플래그에 의해, 파일, 리소스, 메모리 블록, 또는 스트림을 지정한다.
id
로드하는 오브젝트의 이름 또는 위치에의 포인터. id가""의 경우는,D3DRMLOAD_FIRST에options파라미터를 설정할 필요가 있다. Microsoft Visual Basic®는,String데이터형이 지정되고 있어도, 로드 되는 항목의 위치를 나타내는id파라미터안의Integer를 해석한다. 예를 들어,id파라미터로1을 지정 하면, 오브젝트는 1번째의 위치에 로드 된다.
options
로드 옵션을 나타내는CONST_D3DRMLOADFLAGS 열거형으로부터의 하나 또는 복수의 값.
loadTextureImplementation
Direct3DRMLoadTextureCallback3 인터페이스. 이것은, 특별한 포맷을 필요로 하는 오브젝트가 이용하는 텍스쳐를 읽어낼 때 사용된다. 텍스쳐는, 2로 갈라지는 폭과 길이가 아니면 안된다. 이 파라미터에는 NOTHING를 지정할 수가 있다.
userArgument
Direct3DRMLoadTextureCallback3인터페이스에게 건네지는 어플리케이션 정의의 데이터.
parentFrame
친Direct3DRMFrame 오브젝트. 이 인수는, 애니메이션 세트의 로드에만 영향을 준다. x파일로부터 로드 된 애니메이션이, x파일중의 부모가 없는 프레임을 참조 하면나무는, 그 부모에게는,parentFrame가 세트 된다. 다만, x파일중의 임의의 프레임을 로드하도록(듯이),LoadFromFile를 사용했을 경우에는,parentFrame는, 부모가 없는 x파일중의 프레임에 대한 친프레임으로서 사용될 것은 없다. 즉,lpParentFrame는, 애니메이션 세트를 로드했을 때에 한계 사용된다. parentFrame의 값은 NOTHING로 할 수 있다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

디폴트에서는, 이 메소드는filename파라미터로 지정되는 파일의 최초의 애니메이션 세트를 로드한다. 디폴트에서는, 퍼스펙티브 보정이온이다.

Direct3DRMAnimationSet2.SetTime

Direct3DRMAnimationSet2

애니메이션의 현재의 시간을 설정한다.

구문

object. SetTime(time As Single)

요소

object
Direct3DRMAnimationSet2오브젝트를 나타내는오브젝트식.
time
새로운 시간.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.


Direct3DRMClippedVisual

Direct3DRMClippedVisual인터페이스에 의해, 어플리케이션은, 렌더링의 전에 월드 공간에서 지정된 임의의 프레인에 대해서 비주얼 오브젝트를 클립 할 수가 있다. 다른 비주얼로부터 그림자를 생성 하는 것과 거의 똑같이, 다른 비주얼로부터 클립 비주얼을 생성 한다. 예를 들어, 구(공)체로부터 클립 비주얼을 생성 해, 구(공)체의 한가운데로부터 직선적으로 클리핑 프레인을 건네주어, 구(공)체의 반만큼을 렌더링 시킬 수가 있다. Direct3DRM3.CreateClippedVisual 메소드를 호출하는 것으로, 클립 비주얼 오브젝트를 생성 한다. 다음에,Direct3DRMFrame3.AddVisual 메소드를 사용해, 클립 비주얼을 장면에 추가한다.

Direct3DRMClippedVisual는, 그 외의 비주얼 인터페이스와 같게Direct3DRMVisual 를 계승한다. 참조 프레임이 이동 하면 와, 클리핑 프레인은 이동하지 않는다 (상세한 것에 대하여는, 「AddPlane 메소드」를 참조할것).

Direct3DRMClippedVisual인터페이스는, 이하의 메소드를 지원 한다.

  • AddPlane
  • DeletePlane
  • GetPlane
  • GetPlaneIds
  • GetPlaneIdsCount
  • SetPlane

Direct3DRMClippedVisual인터페이스는,Direct3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.

  • AddDestroyCallback
  • CloneObject
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRM3 인터페이스를 사용해,Direct3DRMClippedVisual오브젝트를 생성 할 수가 있다.

Direct3DRMClippedVisual.AddPlane

Direct3DRMClippedVisual

클리핑 프레인을 추가한다.

구문

object. AddPlane(ref As Direct3DRMFrame3,
  point As D3DVECTOR,
  normal As D3DVECTOR) As Long

요소

object
Direct3DRMClippedVisual오브젝트를 나타내는오브젝트식.
ref
포인트와 법선 파라미터의 참조 프레임.
point
참조 프레임을 기점으로 하는 프레인 위에의 포인트.
normal
참조 프레임을 기점으로 하는 프레인에 수직인 벡터.

반환값

호출이 성공했을 경우에, 프레인의 일의인 ID번호를 돌려준다.

에러값

에러가 발생했을 경우는,DDERR_INVALIDPARAMS 를 돌려준다.

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

클리핑 프레인은,월드 좌표로서 내부적으로 저장 된다. 참조 프레임이 이동 하면 와, 클리핑 프레인은 이동하지 않는다. 필요에 따라서 클리핑 프레인의 위치와 방향을 갱신하려면 ,SetPlane 메소드를 사용한다.

참조

D3DVECTOR

Direct3DRMClippedVisual.DeletePlane

Direct3DRMClippedVisual

클리핑 프레인을 삭제한다.

구문

object. DeletePlane(id As Long)

요소

object
Direct3DRMClippedVisual오브젝트를 나타내는오브젝트식.
id
삭제하는 프레인의 ID번호.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMClippedVisual.GetPlane

Direct3DRMClippedVisual

클리핑 프레인에 관한 정보를 꺼낸다.

구문

object. GetPlane(id As Long,
  ref As Direct3DRMFrame3,
  point As D3DVECTOR,
  normal As D3DVECTOR)

요소

object
Direct3DRMClippedVisual오브젝트를 나타내는오브젝트식.
id
프레인의 ID.
ref
이 조작의 참조Direct3DRMFrame3 오브젝트.
point
호출 성공시의 참조 프레임을 기점으로 하는 프레인 위에의 포인트.
normal
호출 성공시의 참조 프레임을 기점으로 하는 프레인에 수직인 벡터.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

D3DVECTOR

Direct3DRMClippedVisual.GetPlaneIds

Direct3DRMClippedVisual

ID의 배열을 꺼낸다.

구문

object. GetPlaneIds(count As Long,
  arrayOfIds() As Long)

요소

object
Direct3DRMClippedVisual오브젝트를 나타내는오브젝트식.
count
arrayOfIds배열의 바이트 단위의 사이즈.
arrayOfIds
모든 프레인 ID번호의 배열. 호출이 성공했을 경우, 프레인 ID가 들어가 있다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMClippedVisual.GetPlaneIdsCount

Direct3DRMClippedVisual

프레인의 수를 꺼낸다.

구문

object. GetPlaneIdsCount( ) As Long

요소

object
Direct3DRMClippedVisual오브젝트를 나타내는오브젝트식.

반환값

프레인의 수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMClippedVisual.SetPlane

Direct3DRMClippedVisual

이미 추가된 클리핑 프레인의 파라미터를 변경한다.

구문

object. SetPlane(id As Long,
  ref As Direct3DRMFrame3,
  point As D3DVECTOR,
  normal As D3DVECTOR)

요소

object
Direct3DRMClippedVisual오브젝트를 나타내는오브젝트식.
id
변경하는 프레인의 ID번호.
ref
포인트와 법선 파라미터의 참조Direct3DRMFrame3 오브젝트. 이 파라미터가 NOTHING라면,point와normal는 월드 공간안에 있다.
point
참조 프레임을 기점으로 하는 프레인 위에의 포인트.
normal
참조 프레임을 기점으로 하는 프레인에 수직인 벡터.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

D3DVECTOR


Direct3DRMDevice3

Direct3DRMDevice3인터페이스를Direct3DRM3 인터페이스로부터 생성 하는 경우,Direct3DDevice3인터페이스는 직접 모드 디바이스와 함께 기능한다. Direct3DDevice3디바이스는, 버퍼를 실행해, 프로그래시브 메쉬, 알파 블렌딩, 투명 오브젝트에 필요하다.

Direct3DRMDevice3인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

버퍼 카운트 | GetBufferCount
SetBufferCount
컬러 모델 | GetColorModel
디저링 | GetDither
SetDither
그 외 | GetDirect3DDevice3
GetHeight
GetTrianglesDrawn
GetViewports
GetWidth
GetWireframeOptions
Update
통지 | AddUpdateCallback
DeleteUpdateCallback
렌더링 퀄리티 | GetQuality
SetQuality
쉐이딩 | GetShades
SetShades
텍스쳐 | FindPreferredTextureFormat
GetTextureQuality
SetTextureQuality
투과성 | GetRenderMode
SetRenderMode

Direct3DRMDevice3인터페이스는,Direct3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.

  • AddDestroyCallback
  • CloneObject
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMDevice3오브젝트는,Direct3DRM3.CreateDeviceFromClipper ,Direct3DRM3.CreateDeviceFromD3D 또는Direct3DRM3.CreateDeviceFromSurface 메소드를 호출하는 것에 의해 취득된다.

Direct3DRMDevice3.AddUpdateCallback

Direct3DRMDevice3

디바이스에 변화가 발생했을 때, 어플리케이션에 경고를 주는 콜백을 추가한다. 시스템은, 어플리케이션이Direct3DRMDevice3.Update 메소드를 사용했을 때에, 이 콜백을 호출한다.

구문

object. AddUpdateCallback(
    updateCallbackImplementation As Direct3DRMDeviceUpdateCallback3,
    userArgument As object)

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.
updateCallbackImplementation
어플리케이션 정의의 콜백 인터페이스 Direct3DRMDeviceUpdateCallback3 .
userArgument
갱신 콜백에 건네주는 Private 데이터.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMDevice3.DeleteUpdateCallback

Direct3DRMDevice3.DeleteUpdateCallback

Direct3DRMDevice3

Direct3DRMDevice3.AddUpdateCallback 메소드를 사용해 추가된 갱신 콜백을 삭제한다.

구문

object. DeleteUpdateCallback(
    updateCallbackImplementation As Direct3DRMDeviceUpdateCallback3,
    userArgument As Object)

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.
updateCallbackImplementation
어플리케이션 정의의 콜백 Direct3DRMDeviceUpdateCallback3 .
userArgument
갱신 콜백에게 건네지는 Private 데이터.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMDevice3.Update

Direct3DRMDevice3.FindPreferredTextureFormat

Direct3DRMDevice3

유저의 기준을 채워, 하층의 직접 모드 디바이스가 지원 하는 텍스쳐 포맷을 검색한다. 텍스쳐 캐쉬의 최적인 퍼포먼스를 얻기 위해서(때문에)는, 이 메소드를 사용해 텍스쳐 표면의 픽셀 포맷을 선택한다.

구문

object. FindPreferredTextureFormat(bitDepth As CONST_DDBITDEPTHFLAGS,
  flags As CONST_D3DRMFPTFFLAGS,
  ddpf As DDPIXELFORMAT)

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.
CONST_DDBITDEPTHFLAGS
요구된 텍스쳐 포맷 비트 깊이. 비트 깊이가 일절 수용 할 수 없는 것을 나타내려면 , 제로를 지정한다. 다음의 Microsoft® DirectDraw® 비트 깊이 플래그의 하나 이상의 논리적인 편성을 사용해, 그 외의 값을 지정한다.
  • DDBD_4
  • DDBD_8
  • DDBD_16
  • DDBD_24
  • DDBD_32
flags
CONST_D3DRMFPTFFLAGS 열거형으로부터의 하나 이상의 값.
ddpf
텍스쳐 포맷을 받는 변수.

에러값

에러가 발생했을 경우는, 다음의 값 가운데 하나를 돌려준다.

  • D3DRMERR_TEXTUREFORMATNOTFOUND
  • DDERR_INVALIDOBJECT
  • DDERR_INVALIDPARAMS

이 메소드는, 수입 가능한 포맷을 검색할 수 없는 경우,D3DRMERR_TEXTUREFORMATNOTFOUND를 돌려준다.

Direct3DRMDevice3.GetBufferCount

Direct3DRMDevice3

Direct3DRMDevice3.SetBufferCount 메소드에 대한 호출로 세트 된 값을 취득한다.

구문

object. GetBufferCount( ) As Long

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.

반환값

버퍼의 수이며, 싱글 버퍼링에 대해서는 1, 더블 버퍼링에 대해서는 2, 등을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMDevice3.GetColorModel

Direct3DRMDevice3

디바이스의 컬러 모델을 취득한다.

구문

object. GetColorModel( ) As CONST_D3DCOLORMODEL

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.

반환값

Direct3D 컬러 모델(RGB 또는 흑백)을 기술하는CONST_D3DCOLORMODEL열거형으로부터 값을 돌려준다. CONST_D3DCOLORMODEL열거형과 그 설정에 대해서는, 추가 정보의 「CONST_D3DCOLORMODEL 」를 참조할것.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMDevice3.GetDirect3DDevice3

Direct3DRMDevice3

Direct3DDevice3직접 모드 디바이스를 취득한다.

구문

object. GetDirect3DDevice3( ) As Direct3DDevice3

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.

반환값

Direct3DDevice3직접 모드 디바이스 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

Direct3DDevice3디바이스는, Microsoft DirectX® DrawPrimitive인터페이스와 함께 버퍼의 실행도 지원 해, 프로그래시브 메쉬, 알파 블렌딩, 및 투명 오브젝트의 소트에 필요하다.

Direct3DRMDevice3.GetDither

Direct3DRMDevice3

디바이스의 디저링 플래그를 취득한다.

구문

object. GetDither( ) As CONST_DBOOLFLAGS

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.

반환값

디저링 플래그가 세트 되고 있으면 1, 그렇지 않으면 0을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMDevice3.SetDither

Direct3DRMDevice3.GetHeight

Direct3DRMDevice3

디바이스의 높이를 취득한다. 이 메소드는, 편리한 함수이다.

구문

object. GetHeight( ) As Long

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.

반환값

높이를 픽셀 단위로 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMDevice3.GetQuality

Direct3DRMDevice3

디바이스의 렌더링 퀄리티를 취득한다.

구문

object. GetQuality( ) As CONST_D3DRMRENDERQUALITY

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.

반환값

CONST_D3DRMRENDERQUALITY 열거형으로부터 1개이상의 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

렌더링 퀄리티는, 디바이스의 렌더링 얼굴로 실행되는 렌더링의 퀄리티의 최대치이다.

오브젝트 퀄리티에는, 3개의 컴퍼넌트가 있다. 즉, 쉐이딩 모드 (플랫 또는 굿 로), 조명 타입 (온 또는 오프) 및 전부 칠해 모드 (포인트, 와이어 프레임 또는 솔리드)이다.

이 메소드가 퀄리티의q를 돌려준 후는, 조명이 온인가 어떤가((q And D3DRMLIGHT_MASK) = D3DRMLIGHT_ON), 쉐이딩의 사용((q And D3DRMSHADE_MASK)= D3DRMSHADE_PHONG), 및 칠해의 사용((q And D3DRMFILL_MASK) =D3DRMFILL_SOLID)를 판별하기 위해서 조회할 수가 있다.

참조

Direct3DRMDevice3.SetQuality

Direct3DRMDevice3.GetRenderMode

Direct3DRMDevice3

현재의 투과성 플래그를 취득한다.

구문

object. GetRenderMode( ) As CONST_D3DRMRENDERMODEFLAGS

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.

반환값

CONST_D3DRMRENDERMODEFLAGS 열거형으로부터 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMDevice3.SetRenderMode

Direct3DRMDevice3.GetShades

Direct3DRMDevice3

흑백 (램프) 모델 쉐이딩에 사용되는 색의 램프에서의 쉐이드수를 취득한다.

구문

object. GetShades( ) As Long

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.

반환값

쉐이드수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMDevice3.SetShades

Direct3DRMDevice3.GetTextureQuality

Direct3DRMDevice3

디바이스의 현재의 텍스쳐 퀄리티 파라미터를 취득한다. 텍스쳐 퀄리티는, RGB 디바이스인 만큼 관계한다.

구문

object. GetTextureQuality( ) As CONST_D3DRMTEXTUREQUALITY

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.

반환값

CONST_D3DRMTEXTUREQUALITY 열거형의 멤버의 하나를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMDevice3.SetTextureQuality

Direct3DRMDevice3.GetTrianglesDrawn

Direct3DRMDevice3

디바이스가 생성 된 이후, 그 디바이스에 드로잉(Drawing) 된 삼각형의 수를 취득한다. 이 메소드는, 편리한 함수이다.

구문

object. GetTrianglesDrawn( ) As Long

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.

반환값

삼각형의 수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

삼각형의 수는, 렌더러에게 건네졌지만, 뒤(카메라의 방향과 역의면)에 숨겨졌기 때문에 드로잉(Drawing) 되지 않았던 것을 포함한다. 절두체의 외측에 있어 거절된 삼각형은 포함되지 않는다.

Direct3DRMDevice3.GetViewports

Direct3DRMDevice3

디바이스로부터 현재 구축되고 있는 뷰포트를 나타내는Direct3DRMViewportArray 오브젝트를 구축한다.

구문

object. GetViewports( ) As Direct3DRMViewportArray

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.

반환값

호출이 성공했을 경우는,Direct3DRMViewportArray오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMDevice3.GetWidth

Direct3DRMDevice3

디바이스의 폭을 취득한다. 이 메소드는, 편리한 함수이다.

구문

object. GetWidth( ) As Long

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.

반환값

디바이스의 폭을 픽셀 단위로 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMDevice3.GetWireframeOptions

Direct3DRMDevice3

지정의 디바이스의 와이어 프레임 옵션을 취득한다.

구문

object. GetWireframeOptions( ) As CONST_D3DRMWIREFRAMEFLAGS

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.

반환값

CONST_D3DRMWIREFRAMEFLAGS 열거형으로부터 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMDevice3.SetBufferCount

Direct3DRMDevice3

현재 어플리케이션으로 사용되고 있는 버퍼의 수를 설정한다.

구문

object. SetBufferCount(count As Long)

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.
count
버퍼의 수를, 싱글 버퍼링에 대해서는 1, 더블 버퍼링에 대해서는 2등과 지정한다. 디폴트값은 1이며, 싱글 버퍼링 윈도우 조작 에 대해서만 유효하다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

어플리케이션이, 더블 버퍼링이나 트리플 버퍼링을 실시할 때는, 이 메소드로, 사용하는 버퍼수를 시스템에 통지해, 시스템이 각 프레임에 대해서, 윈도우의 어느 부분을 클리어 및 갱신하는지를 계산할 수 있도록(듯이) 해야 한다.

참조

Direct3DRMDevice3.GetBufferCount

Direct3DRMDevice3.SetDither

Direct3DRMDevice3

디바이스의 디저링 플래그를 설정한다.

구문

object. SetDither(ditherEnabled As CONST_DBOOLFLAGS)

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.
ditherEnabled
디바이스의 새로운 디저링 모드. 디저링을 유효하게 하려면 D_TRUE, 그렇지 않으면 D_FALSE 를 지정한다. 디폴트는 D_TRUE 이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMDevice3.GetDither

Direct3DRMDevice3.SetQuality

Direct3DRMDevice3

디바이스의 렌더링 퀄리티를 설정한다.

구문

object. SetQuality(q As CONST_D3DRMRENDERQUALITY)

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.
q
CONST_D3DRMRENDERQUALITY 열거형으로부터의 하나 이상의 값.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

렌더링 퀄리티는, 디바이스의 렌더링 얼굴로 실행되는 렌더링의 퀄리티의 최대치이다.

오브젝트 퀄리티에는, 3개의 컴퍼넌트가 있다. 즉, 쉐이딩 모드 (플랫 또는 굿 로로, 폰은 이행되어 있지 않다. 디폴트는 gouraud shading), 조명 타입 (온 또는 오프) 및 전부 칠해 모드 (포인트, 와이어 프레임 또는 솔리드)이다.

쉐이드 모드, 조명 타입, 및 전부 칠해 모드는,CONST_D3DRMRENDERQUALITY 열거의 멤버와 함께 지정된다.

Direct3DRMProgressiveMesh 또는Direct3DRMMeshBuilder3 오브젝트의 퀄리티는, 각각SetQuality메소드를 이용해 설정할 수 있다. 디폴트에서는, 이러한 오브젝트의 퀄리티는D3DRMRENDER_GOURAUD이다. D3DRMRENDER_GOURAUD는,D3DRMLIGHT_ON,D3DRMFILL_SOLID또는D3DRMSHADE_GOURAUD와 같다.

힌트 gouraud shading는, 상세 레벨을 빈번하게 또는 재빠르게 변경하는 프로그래시브 메쉬 오브젝트에 대해, 보다 좋은 퍼포먼스를 얻을 수 있다.

Direct3D 보관 유지 모드는, 디바이스나 오브젝트의 각각의 컴퍼넌트에 대한 현재의 설정 중(안)에서, 가장 저위의 퀄리티로, 오브젝트에 렌더링을 실시한다. 예를 들어, 오브젝트의 현재의 퀄리티 설정이D3DRMRENDER_GOURAUD로, 디바이스가D3DRMRENDER_FLAT이라고, 오브젝트는 flat shading, 솔리드 전부 칠해 및 조명 온으로 렌더링 된다.

이러한 룰은,Direct3DRMMeshBuilder3오브젝트 및Direct3DRMProgressiveMesh오브젝트에 적용된다. 그러나,Direct3DRMMesh오브젝트는 이러한 룰에 따르지 않다. 메쉬 오브젝트는 디바이스의 퀄리티 설정을 무시해, 그룹 퀄리티 설정을 이용한다(디폴트로D3DRMRENDER_GOURAUD).

참조

Direct3DRMDevice3.GetQuality

Direct3DRMDevice3.SetRenderMode

Direct3DRMDevice3

투명 모드를 설정한다. 모드 타입은, 오브젝트를 어느 정도 투명하게 렌더링 할까를 결정한다.

구문

object. SetRenderMode(flags As CONST_D3DRMRENDERMODEFLAGS)

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.
flags
투명 모드를 나타내는CONST_D3DRMRENDERMODEFLAGS 열거형으로부터의 하나 이상의 값.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMDevice3.GetRenderMode

Direct3DRMDevice3.SetShades

Direct3DRMDevice3

흑백 (램프) 모델 쉐이딩에 사용되는 색의 램프에서의 쉐이드수를 설정한다.

구문

object. SetShades(numShades As Long)

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.
numShades
새로운 쉐이드수. 이 파라미터는, 2의 거듭제곱이 아니면 안된다. 디폴트는, 32이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMDevice3.GetShades

Direct3DRMDevice3.SetTextureQuality

Direct3DRMDevice3

디바이스에 대한 텍스쳐 퀄리티를 설정한다.

구문

object. SetTextureQuality(d As CONST_D3DRMTEXTUREQUALITY)

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.
d
CONST_D3DRMTEXTUREQUALITY 열거형의 멤버의 하나. 디폴트는,D3DRMTEXTURE_NEAREST 이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMDevice3.GetTextureQuality

Direct3DRMDevice3.Update

Direct3DRMDevice3

렌더링 되고 있는 이미지를 디스플레이에 카피한다. 또, 디바이스 드라이버에 하트 비트 함수를 주어 이미지를 언제 갱신할까를 알린다.

구문

object. Update( )

요소

object
Direct3DRMDevice3오브젝트를 나타내는오브젝트식.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드에 대한 각 호출은, 시스템에 어플리케이션 정의 콜백 인터페이스의D3DRMDeviceUpdateCallback3 를 호출하게 한다. 콜백을 추가하려면 ,Direct3DRMDevice3.AddUpdateCallback 메소드를 사용한다.


Direct3DRMDeviceArray

어플리케이션은,Direct3DRMDeviceArray인터페이스의 메소드를 사용해 디바이스 오브젝트를 정리한다. 이 항은, 이 인터페이스의 다음의 메소드의 레퍼런스이다.

디바이스의 배열은, 0이 기준이 되어 있다 (0~N-1).

  • GetElement
  • GetSize

Direct3DRMDeviceArray오브젝트는, Direct3DRM3.GetDevices 메소드의 호출에 의해 취득된다.

Direct3DRMDeviceArray.GetElement

Direct3DRMDeviceArray

Direct3DRMDeviceArray오브젝트로부터 지정된 요소를 취득한다.

구문

object. GetElement(index As Long) As Direct3DRMDevice3

요소

object
Direct3DRMDeviceArray오브젝트를 나타내는오브젝트식.
index
배열 요소.

반환값

Direct3DRMDeviceArray오브젝트의index파라미터에 의해 지정된 요소를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMDeviceArray.GetSize

Direct3DRMDeviceArray

Direct3DRMDeviceArray오브젝트에 포함되는 요소수를 취득한다.

구문

object. GetSize( ) As Long

요소

object
Direct3DRMDeviceArray오브젝트를 나타내는오브젝트식.

반환값

요소수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.


Direct3DRMFace2

어플리케이션은, 면과 서로 교환하기 위해서Direct3DRMFace2인터페이스의 메소드를 사용한다. 면은, 메쉬 위에의 1개의 다각형이다. 어플리케이션은,Direct3DRMFace2.SetColor ,Direct3DRMFace2.SetColorRGB ,Direct3DRMFace2.SetTexture , 및Direct3DRMFace2.SetMaterial 메소드를 사용해, 면의 색, 텍스쳐, 머트리얼을 세트 할 수가 있다.

면은,Direct3DRMFace2.AddVertex 와Direct3DRMFace2.AddVertexAndNormalIndexed 메소드를 사용해 버텍스로부터 구축한다. 어플리케이션은,Direct3DRMFace2.GetVertices 와Direct3DRMFace2.GetVertex 메소드를 사용해 면의 버텍스를 읽어들일 수가 있다.

Direct3DRMFace2에서는,SetTexture메소드는, 그 폭과 높이가 2의 거듭제곱이 아닌 텍스쳐를 지정할 수가 있다.

Direct3DRMFace2인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

색 | GetColor
SetColor
SetColorRGB
머트리얼 | GetMaterial
SetMaterial
텍스쳐 | GetTexture
GetTextureCoordinateIndex
GetTextureCoordinates
GetTextureTopology
SetTexture
SetTextureCoordinates
SetTextureTopology
버텍스와 법선 | AddVertex
AddVertexAndNormalIndexed
GetNormal
GetVertex
GetVertexCount
GetVertexIndex
GetVertices

Direct3DRMFace2인터페이스는,Direct3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.

  • AddDestroyCallback
  • CloneObject
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMFace2오브젝트는,Direct3DRM3.CreateFace 메소드의 호출에 의해 취득된다.

Direct3DRMFace2.AddVertex

Direct3DRMFace2

Direct3DRMFace2오브젝트에 버텍스를 추가한다.

구문

object. AddVertex(x As Single,
  y As Single,
  z As Single)

요소

object
Direct3DRMFace2오브젝트를 나타내는오브젝트식.
x, y, z
새로운 버텍스 위치의 x, y, z좌표.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFace2.AddVertexAndNormalIndexed

Direct3DRMFace2

버텍스와 법선을Direct3DRMFace2오브젝트에 추가한다. 이 때, 메쉬 빌더에 포함되는 버텍스의 인덱스와 법선의 인덱스를 사용한다. 면, 버텍스, 법선은,Direct3DRMMeshBuilder3 오브젝트가 일부에서 없으면 안 된다.

구문

object. AddVertexAndNormalIndexed(vertexIndex As Long,
  normalIndex As Long)

요소

object
Direct3DRMFace2오브젝트를 나타내는오브젝트식.
vertexIndex, normal
추가하는 버텍스와 법선의 인덱스.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFace2.GetColor

Direct3DRMFace2

Direct3DRMFace2오브젝트의 색을 취득한다.

구문

object. GetColor( ) As Long

요소

object
Direct3DRMFace2오브젝트를 나타내는오브젝트식.

반환값

색을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFace2.SetColor

Direct3DRMFace2.GetMaterial

Direct3DRMFace2

Direct3DRMFace2오브젝트의 머트리얼을 취득한다.

구문

object. GetMaterial( ) As Direct3DRMMaterial2

요소

object
Object expression that resolves to a Direct3DRMFace2 object.

반환값

면에 적용되고 있는Direct3DRMMaterial 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFace2.SetMaterial

Direct3DRMFace2.GetNormal

Direct3DRMFace2

Direct3DRMFace2오브젝트의법선 벡터를 취득한다.

구문

object. GetNormal(val As D3DVECTOR)

요소

object
Direct3DRMFace2오브젝트를 나타내는오브젝트식.
val
면의 법선 벡터를 받는D3DVECTOR 타입.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFace2.GetTexture

Direct3DRMFace2

Direct3DRMFace2오브젝트에 적용된Direct3DRMTexture3 를 취득한다.

구문

object. GetTexture( ) As Direct3DRMTexture3

요소

object
Direct3DRMFace2오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMTexture3오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFace2.SetTexture

Direct3DRMFace2.GetTextureCoordinateIndex

Direct3DRMFace2

면의 메쉬에 있는 버텍스의 인덱스를 텍스쳐 좌표로 취득한다.

구문

object. GetTextureCoordinateIndex(which As Long) As Long

요소

object
Direct3DRMFace2오브젝트를 나타내는오브젝트식.
which
대응하는 메쉬 버텍스 인덱스를 꺼내 안의 버텍스의 면내의 인덱스.

반환값

면의 메쉬를 기점으로 하는 버텍스 인덱스를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFace2.GetTextureCoordinates

Direct3DRMFace2

Direct3DRMFace2오브젝트중의 버텍스의 텍스쳐 좌표를 취득한다.

구문

object. GetTextureCoordinates(Vertex As Long,
  u As Single,
  v As Single)

요소

object
Direct3DRMFace2오브젝트를 나타내는오브젝트식.
Vertex
버텍스의 인덱스.
u, v
점의 텍스쳐 좌표를 받는 변수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFace2.GetTextureTopology

Direct3DRMFace2

Direct3DRMFace2오브젝트의 텍스쳐 위상을 취득한다.

구문

object. GetTextureTopology(u As Long,
  v As Long)

요소

object
Direct3DRMFace2오브젝트를 나타내는오브젝트식.
u, v
텍스쳐 좌표를 받는 변수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFace2.GetVertex

Direct3DRMFace2

Direct3DRMFace2오브젝트중의 버텍스의 위치와 법선을 취득한다.

구문

object. GetVertex(idx As Long,
  vert As D3DVECTOR,
  norm As D3DVECTOR)

요소

object
Direct3DRMFace2오브젝트를 나타내는오브젝트식.
idx
버텍스의 인덱스.
vert, norm
각각, 버텍스의 위치와 법선을 받는D3DVECTOR 타입.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFace2.GetVertexCount

Direct3DRMFace2

Direct3DRMFace2오브젝트의 버텍스의 수를 취득한다.

구문

object. GetVertexCount( ) As Long

요소

object
Direct3DRMFace2오브젝트를 나타내는오브젝트식.

반환값

버텍스의 수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFace2.GetVertexIndex

Direct3DRMFace2

면의 메쉬에 있는 버텍스의 인덱스를 취득한다.

구문

object. GetVertexIndex(which As Long) As Long

요소

object
Direct3DRMFace2오브젝트를 나타내는오브젝트식.
which
대응하는 메쉬 버텍스 인덱스를 꺼내 안의 버텍스의 면내의 인덱스.

반환값

메쉬를 기점으로 하는 버텍스 인덱스를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFace2.GetVertices

Direct3DRMFace2

Direct3DRMFace2 오브젝트중의 각각의 버텍스에 대해, 위치와법선 벡터를 취득한다.

구문

object. GetVertices(vertexCount As Long,
  coord() As D3DVECTOR,
  normals() As D3DVECTOR)

요소

object
Direct3DRMFace2오브젝트를 나타내는오브젝트식.
vertexCount
버텍스의 수를 받는 변수. 이 파라미터에 NOTHING를 지정할 수 없다.
coord, normals
각각, 버텍스의 위치와 법선 벡터를 받는D3DVECTOR 타입의 배열.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

vertexCount를 결정해,coord와normals에 그 사이즈를 설정하려면 ,GetVertexCount를 사용한다.

Direct3DRMFace2.SetColor

Direct3DRMFace2

Direct3DRMFace2오브젝트의 색을 설정한다.

구문

object. SetColor(c As Long)

요소

object
Direct3DRMFace2오브젝트를 나타내는오브젝트식.
c
설정하는 색. 적, 초록, 파랑의 색요소 뿐만이 아니라, 알파 요소도 반드시 세트 한다. 그렇게 하지 않으면 오브젝트가 가시가 되지 않는 것이 있다. 색은 4바이트의Long로 나타내진다. 고바이트는 알파 요소이며, 후속의 바이트가 적, 초록, 파랑을 정의한다. 보다 간단하게 색을 구축하려면 DirectX7 오브젝트의CreateColorRGBA를 사용해, 풀 알파를 희망하고 있을 뿐(만큼)의 경우는SetColorRGB를 사용한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFace2.GetColor

Direct3DRMFace2.SetColorRGB

Direct3DRMFace2

Direct3DRMFace2오브젝트의 적, 초록, 파랑의 색요소를 설정한다.

구문

object. SetColorRGB(r As Single,
  g As Single,
  b As Single)

요소

object
Direct3DRMFace2오브젝트를 나타내는오브젝트식.
r, g, b
적, 초록, 파랑의 색요소.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFace2.SetMaterial

Direct3DRMFace2

Direct3DRMFace2오브젝트의 머트리얼을 설정한다.

구문

object. SetMaterial(ref As Direct3DRMMaterial2)

요소

object
Direct3DRMFace2오브젝트를 나타내는오브젝트식.
ref
머트리얼로서 사용하는Direct3DRMMaterial 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFace2.GetMaterial

Direct3DRMFace2.SetTexture

Direct3DRMFace2

Direct3DRMFace2오브젝트의 텍스쳐를 설정한다.

구문

object. SetTexture(ref As Direct3DRMTexture3)

요소

object
Direct3DRMFace2오브젝트를 나타내는오브젝트식.
ref
텍스쳐로서 사용하는Direct3DRMTexture3 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

우선, DirectX Foundation 6에 대해서는, 텍스쳐의 폭과 높이가 2의 거듭제곱일 필요는 없다.

참조

Direct3DRMFace2.GetTexture

Direct3DRMFace2.SetTextureCoordinates

Direct3DRMFace2

Direct3DRMFace2오브젝트중의 버텍스의 텍스쳐 좌표를 설정한다.

구문

object. SetTextureCoordinates(Vertex As Long,
  u As Single,
  v As Single)

요소

object
Direct3DRMFace2오브젝트를 나타내는오브젝트식.
Vertex
설정하는 버텍스의 인덱스. 예를 들어, 면이 삼각형 때, 버텍스는 0, 1, 2가 된다.
u, v
지정된 버텍스에 할당하는 텍스쳐 좌표.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFace2.SetTextureTopology

Direct3DRMFace2

Direct3DRMFace2오브젝트에 텍스쳐 위상을 설정한다.

구문

object. SetTextureTopology(wrap_u As CONST_DBOOLFLAGS,
  wrap_v As CONST_DBOOLFLAGS)

요소

object
Direct3DRMFace2오브젝트를 나타내는오브젝트식.
wrap_u, wrap_v
텍스쳐의 위상을 u와 v의 차원에서 원기둥(실린더)로 하고 싶은 경우는, 이러한 파라미터의 언젠가, 또는 양쪽 모두에 D_TRUE를 지정한다. 그렇지 않으면, D_FALSE를 지정한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

몇개의 인터페이스로SetTextureTopology메소드가 제공된다. SetTextureTopology메소드와의 관계의 상세, 및wrap_u와wrap_v파라미터의 목적에 관한 상세한 것에 대하여는, 「Direct3DRMeshBuilder3.SetTextureTopology 」를 참조할것.


Direct3DRMFaceArray

메쉬 위에의면을 그룹화 하려면 ,Direct3DRMFaceArray인터페이스의 메소드를 이용한다. 면의 배열은, 0이 기준이 되어 있다 (0~N-1). 면의 개요에 대해서는, 「Direct3DRMFace2 」를 참조할것.

Direct3DRMFaceArray인터페이스는, 다음의 메소드를 지원 한다.

  • GetElement
  • GetSize

Direct3DRMFaceArray오브젝트는,Direct3DRMMeshBuilder3.GetFaces 메소드의 호출에 의해 취득된다.

Direct3DRMFaceArray.GetElement

Direct3DRMFaceArray

Direct3DRMFaceArray오브젝트로부터 지정된 요소를 취득한다.

구문

object. GetElement(index As Long) As Direct3DRMFace2

요소

object
Direct3DRMFaceArray오브젝트를 나타내는오브젝트식.
index
배열 요소.

반환값

Direct3DRMFaceArray오브젝트의index파라미터로 지정된Direct3DRMFace 요소를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFaceArray.GetSize

Direct3DRMFaceArray

Direct3DRMFaceArray오브젝트에 포함되는 요소수를 취득한다.

구문

object. GetSize( ) As Long

요소

object
Direct3DRMFaceArray오브젝트를 나타내는오브젝트식.

반환값

요소수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.


Direct3DRMFrame3

어플리케이션은,Direct3DRMFrame3인터페이스의 메소드를 사용해 오브젝트의 참조 프레임이라고 대화한다.

Direct3DRMFrame3는, 추가 변환 기능, 횡단 옵션세트와 꺼내, 장면 포그(안개:fog) 메소드세트와 취득을 가능하게 하는 메소드를 제공한다. 메소드는, 「Direct3DRMFrame3 메소드 A~M 」와「Direct3DRMFrame3 메소드 N~Z 」의 2개의 섹션으로 나누어져 있다.

Direct3DRMFrame3인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

축 | GetAxes
GetInheritAxes
SetAxes
SetInheritAxes
배경 | GetSceneBackground
GetSceneBackgroundDepth
SetSceneBackground
SetSceneBackgroundDepth
SetSceneBackgroundImage
SetSceneBackgroundRGB
경계 박스 | GetBox
GetBoxEnable
GetHierarchyBox
SetBox
SetBoxEnable
색 | GetColor
SetColor
SetColorRGB
포그(안개:fog) | GetSceneFogColor
GetSceneFogEnable
GetSceneFogMethod
GetSceneFogMode
GetSceneFogParams
SetSceneFogColor
SetSceneFogEnable
SetSceneFogMethod
SetSceneFogMode
SetSceneFogParams
계층 | AddChild
DeleteChild
GetChildren
GetParent
GetScene
조명 | AddLight
DeleteLight
GetLights
로드 | LoadFromFile
머트리얼 | GetMaterial
GetMaterialOverride
GetMaterialOverrideTexture
SetMaterial
SetMaterialOverride
SetMaterialOverrideTexture
머트리얼 모드 | GetMaterialMode
SetMaterialMode
위치 지정과 운동 | AddMoveCallback
AddRotation
AddScale
AddTranslation
DeleteMoveCallback
GetOrientation
GetPosition
GetRotation
GetVelocity
LookAt
Move
SetOrientation
SetPosition
SetQuaternion
SetRotation
SetVelocity
광선 픽 | RayPick
보존 | Save
소트 | GetSortMode
GetZbufferMode
SetSortMode
SetZbufferMode
텍스쳐 | GetTexture
SetTexture
변환 | AddTransform
GetTransform
InverseTransform
InverseTransformVectors
Transform
TransformVectors
횡단 | GetTraversalOptions
SetTraversalOptions
비주얼 오브젝트 | AddVisual
DeleteVisual
GetVisual
GetVisuals
GetVisualCount

Direct3DRMFrame3인터페이스는,Direct3DRMObject 인터페이스로부터 이하의 메소드를 계승한다.

  • AddDestroyCallback
  • CloneObject
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMFrame3오브젝트는,Direct3DRM3.CreateFrame 메소드를 호출하는 것에 의해 취득된다.


Direct3DRMFrameArray

어플리케이션은,Direct3DRMFrameArray인터페이스의 메소드를 사용해 프레임 오브젝트를 정리한다. 프레임의 배열은, 0이 기준이 되어 있다 (0~N-1). 이 항은, 이 인터페이스의 메소드의 레퍼런스이다.

Direct3DRMFrameArray다음의 메소드를 지원 한다.

  • GetElement
  • GetSize

Direct3DRMFrameArray오브젝트는,Direct3DRMPickArray.GetPickFrame ,Direct3DRMPick2Array.GetPickFrame 또는Direct3DRMFrame3.GetChildren 메소드의 호출에 의해 취득된다.

Direct3DRMFrameArray.GetElement

Direct3DRMFrameArray

Direct3DRMFrameArray오브젝트로부터 지정된 요소를 취득한다.

구문

object. GetElement(index As Long) As Direct3DRMFrame3

요소

object
Direct3DRMFrameArray오브젝트를 나타내는오브젝트식.
index
배열 요소.

반환값

Direct3DRMFrame3 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrameArray.GetSize

Direct3DRMFrameArray

Direct3DRMFrameArray오브젝트에 포함되어 있는 요소수를 취득한다.

구문

object. GetSize( ) As Long

요소

object
Direct3DRMFrameArray오브젝트를 나타내는오브젝트식.

반환값

요소수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.


Direct3DRMFrameInterpolator

인타포레이타는, 액션을 저장 한 후, 중간값을 자동 계산해, 오브젝트에 액션을 적용하는 방법을 제공한다. 인타포레이타를 사용해, 색을 혼합해, 다른 위치간에서 오브젝트를 원활히 이동해, 메쉬를 morphing 해, 게다가 다른 다양한 변환도 실시할 수가 있다.

Direct3DRMFrame3 오브젝트는,Direct3DRMFrameInterpolator오브젝트에 Attach 할 수 있다. 인타포레이타의 상세한 것에 대하여는, 추가 정보의 「인타포레이타」를 참조할것.

Direct3DRMFrameInterpolator에는 다음의 메소드가 포함된다.

오브젝트의 Attach | AttachObject
DetachObject
GetAttachedObjects
배경 | SetSceneBackground
SetSceneBackgroundRGB
색 | SetColor
SetColorRGB
포그(안개:fog) | SetSceneFogColor
SetSceneFogParams
보간의 실행 | GetIndex
Interpolate
SetIndex
위치 지정과 이동 | SetOrientation
SetPosition
SetQuaternion
SetRotation
SetVelocity

게다가Direct3DRMFrameInterpolator는,Direct3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.

  • AddDestroyCallback
  • Clone
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMFrameInterpolator.AttachObject

Direct3DRMFrameInterpolator

오브젝트를 인타포레이타에 접속한다.

구문

object. AttachObject(mObject As Direct3DRMObject)

요소

object
Direct3DRMFrameInterpolator오브젝트를 나타내는오브젝트식.
mObject
인타포레이타에 접속하는Direct3DRMObject 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

접속되는 오브젝트는, 다른 인타포레이타에서도, 인타포레이타가xInterpolator형이 되는 타입x의 오브젝트에서도 좋다. 예를 들어,Direct3DRMFrame3 오브젝트는,Direct3DRMFrameInterpolator오브젝트에 Attach 할 수 있다.

Direct3DRMFrameInterpolator.DetachObject

Direct3DRMFrameInterpolator

인타포레이타로부터 오브젝트의 Attach를 해제한다.

구문

object. DetachObject(mObject As Direct3DRMObject)

요소

object
Direct3DRMFrameInterpolator오브젝트를 나타내는오브젝트식.
mObject
인타포레이타로부터 Attach를 해제하는Direct3DRMObject 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrameInterpolator.GetAttachedObjects

Direct3DRMFrameInterpolator

인타포레이타에 현재 Attach 되고 있는 오브젝트의 배열을 취득한다.

구문

object. GetAttachedObjects( ) As Direct3DRMObjectArray

요소

object
Direct3DRMFrameInterpolator오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMObjectArray 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrameInterpolator.GetIndex

Direct3DRMFrameInterpolator

인타포레이타의 현재의 내부 인덱스(시간)를 취득한다.

구문

object. GetIndex( ) As Single

요소

object
Direct3DRMFrameInterpolator오브젝트를 나타내는오브젝트식.

반환값

인타포레이타의 현재의 내부 인덱스를 포함한 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

인타포레이타에 저장 되고 있는 각 키는, 인덱스값을 가진다. 키를(메소드를 사용해) 기록 하면 와, 키에는, 현재의 인타포레이타의 인덱스값으로 스탬프가 밀린다. 키의 인덱스값은, 스탬프를 밀린 후, 바뀔 것은 없다.

Direct3DRMFrameInterpolator.Interpolate

Direct3DRMFrameInterpolator

인타포레이타에 저장 되고 있는 키간을 보간 해, 일련의 액션을 생성한다. 그 후, 액션은, 지정의 오브젝트에 적용된다. 오브젝트의 지정이 없으면, 액션은, 현재 Attach 되고 있는 오브젝트에 적용된다.

구문

object. Interpolate(val As Single,
  mObject As Direct3DRMObject,
  options As CONST_D3DRMINTERPOLATIONFLAGS)

요소

object
Direct3DRMFrameInterpolator오브젝트를 나타내는오브젝트식.
val
인타포레이타의 현재의 내부 인덱스를 포함한 값.
mObject
Direct3DRMObject 오브젝트. 이 오브젝트는, 인타포레이타에 저장 떠날 수 있어 모든 프로퍼티에 대한 보간값을 할당하는 오브젝트를 나타낸다. 이 포인터는 NOTHING에서도 좋다. 그 경우, 모든 Attach 되고 있는 오브젝트의 프로퍼티값에는, 보간값이 세트 된다.
options
실행하는 보간의 종류를 제어하는CONST_D3DRMINTERPOLATIONFLAGS 열거형의 값의 하나.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrameInterpolator.SetColor

Direct3DRMFrameInterpolator

Direct3DRMFrameInterpolator오브젝트에 컬러 키를 추가한다.

구문

object. SetColor(c As Long)

요소

object
Direct3DRMFrameInterpolator오브젝트를 나타내는오브젝트식.
c
프레임의 새로운 색. 적, 초록, 파랑의 색요소 외에 알파 요소 도 세트 한다. 그렇게 하지 않으면 오브젝트가 가시가 되지 않는 것이 있다. 오브젝트의 색을 알파 요소를 포함해 지정하려면 , 오브젝트 위에의DirectX7인터페이스로부터CreateColorRGBA메소드를 호출한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrameInterpolator.SetColorRGB

Direct3DRMFrameInterpolator

Direct3DRMFrameInterpolator오브젝트에 RGB 컬러 키를 추가한다.

구문

object. SetColorRGB(r As Single,
  g As Single,
  b As Single)

요소

object
Direct3DRMFrameInterpolator오브젝트를 나타내는오브젝트식.
r, g, b
프레임의 새로운 색. 각 색요소는, 0.0~1.0의 범위 일 필요가 있다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrameInterpolator.SetIndex

Direct3DRMFrameInterpolator

인타포레이타의 내부 인덱스(시간)로 지정의 값을 세트 한다. 다른 인타포레이타가 그 인타포레이타에 Attach 되고 있으면, 이 메소드는, 재귀적으로 그러한 인덱스를 같은 값에 동기 시킨다.

구문

object. SetIndex(val As Single)

요소

object
Direct3DRMFrameInterpolator오브젝트를 나타내는오브젝트식.
val
인타포레이타의 내부 인덱스에 대해서 세트 되는 시간.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

인타포레이타에 저장 되고 있는 각 키는, 인덱스값을 가진다. 키를(메소드를 사용해) 기록 하면 와, 키에는, 현재의 인타포레이타의 인덱스값으로 스탬프가 밀린다. 키의 인덱스값은, 스탬프를 밀린 후, 바뀔 것은 없다.

Direct3DRMFrameInterpolator.SetOrientation

Direct3DRMFrameInterpolator

Direct3DRMFrameInterpolator오브젝트에 방향 키를 추가한다.

구문

object. SetOrientation(reference As Direct3DRMFrame3,
  dx As Single,
  dy As Single,
  dz As Single,
  ux As Single,
  uy As Single,
  uz As Single)

요소

object
Direct3DRMFrameInterpolator오브젝트를 나타내는오브젝트식.
reference
참조로서 사용되는Direct3DRMFrame3 오브젝트를 나타내는 변수.
dx, dy, dz
프레임의 새로운 z축. 벡터의 각 요소는, 1. 0~1.0의 범위일 필요가 있다.
ux, uy, uz
프레임의 새로운 y축. 벡터의 각 요소는, 1. 0~1.0의 범위일 필요가 있다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

프레임의 디폴트 방향은,[0, 0, 1] 의 방향 벡터와 [0, 1, 0] 의 업 벡터를 가진다.

[ux, uy, uz] 가 [dx, dy, dz]에 평행한 경우에는,D3DRMERR_BADVALUE에러값이 돌아온다. 그렇지 않은 경우에는, 건네받은 [ux, uy, uz] 벡터는,[dx, dy, dz]에 수직인 프레인에 투영 된다.

Direct3DRMFrameInterpolator.SetPosition

Direct3DRMFrameInterpolator

Direct3DRMFrameInterpolator오브젝트에 위치 키를 추가한다.

구문

object. SetPosition(reference As Direct3DRMFrame3,
  x As Single,
  y As Single,
  z As Single)

요소

object
Direct3DRMFrameInterpolator오브젝트를 나타내는오브젝트식.
reference
참조로서 사용되는Direct3DRMFrame3 오브젝트를 나타내는 변수.
x, y, z
프레임의 새로운 위치. 위치에는 단위가 없다. 절두체를 사용해 적당한 수를 선택한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrameInterpolator.SetQuaternion

Direct3DRMFrameInterpolator

단위 4원수를 이용해, 참조 프레임에 대해서 프레임의 방향을 설정한다.

구문

object. SetQuaternion(reference As Direct3DRMFrame3,
  quat As D3DRMQUATERNION)

요소

object
Direct3DRMFrameInterpolator오브젝트를 나타내는오브젝트식.
reference
참조로서 사용되는Direct3DRMFrame3 오브젝트를 나타내는 변수.
quat
프레임의 방향을 설정하는D3DRMQUATERNION 형.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

4원수란, 임의의 회전을 나타내기 위해서(때문에) 이용되는 4값벡터로, 방향의 사이에 보간을 실시할 때 유용한 특성을 가지고 있다. 4원수는,s**2 + x**2 + y**2 + z**2 = 1이면 단위 4원수이다.

Direct3DRMFrameInterpolator.SetRotation

Direct3DRMFrameInterpolator

Direct3DRM3.Tick 또는Direct3DRMFrame3.Move 메소드에 대한 호출할 것에, 지정의 벡터의 주위로 지정의 각도로 프레임의 회전을 설정한다. 방향 벡터 [x, y, z] 는 참조 프레임으로 정의된다.

구문

object. SetRotation(reference As Direct3DRMFrame3,
  x As Single,
  y As Single,
  z As Single,
  theta As Single)

요소

object
Direct3DRMFrameInterpolator오브젝트를 나타내는오브젝트식.
reference
참조 프레임으로서 사용되는Direct3DRMFrame3 오브젝트를 나타내는 변수.
x, y, z
V회전의 중심의 벡터. 유효한 값은, 1. 0~1.0의 범위에 있을 필요가 있다.
theta
라디안 단위의 회전각. 각도가 크면 큰 만큼, 오브젝트의 회전은 빨라진다. Move와Tick메소드가, 이 값을 스케일링 한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

지정된 회전은 렌더링 마다 행렬을 변경한다.

Direct3DRMFrameInterpolator.SetSceneBackground

Direct3DRMFrameInterpolator

Direct3DRMFrameInterpolator오브젝트에 배경 컬러 키를 추가한다.

구문

object. SetSceneBackground(c As Long)

요소

object
Direct3DRMFrameInterpolator오브젝트를 나타내는오브젝트식.
c
배경의 새로운 색. 오브젝트의 색을 알파 요소를 포함해 지정하려면 , 오브젝트 위에의DirectX7인터페이스로부터CreateColorRGBA메소드를 호출한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrameInterpolator.SetSceneBackgroundRGB

Direct3DRMFrameInterpolator

Direct3DRMFrameInterpolator오브젝트에 배경 RGB 컬러 키를 추가한다.

구문

object. SetSceneBackgroundRGB(r As Single,
  g As Single,
  b As Single)

요소

object
Direct3DRMFrameInterpolator오브젝트를 나타내는오브젝트식.
r, g, b
배경의 새로운 색. 적, 초록, 파랑의 각 색요소는 0.0~1.0의 범위일 필요가 있다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrameInterpolator.SetSceneFogColor

Direct3DRMFrameInterpolator

Direct3DRMRFrameInterpolator오브젝트에 포그(안개:fog) 컬러 키를 추가한다.

구문

object. SetSceneFogColor(c As Long)

요소

object
Direct3DRMFrameInterpolator오브젝트를 나타내는오브젝트식.
c
포그(안개:fog)의 새로운 색.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrameInterpolator.SetSceneFogParams

Direct3DRMFrameInterpolator

Direct3DRMRFrameInterpolator오브젝트에 포그(안개:fog) 파라미터 키를 추가한다.

구문

object. SetSceneFogParams(start As Single,
  End As Single,
  density As Single)

요소

object
Direct3DRMFrameInterpolator오브젝트를 나타내는오브젝트식.
start, End
선형 포그(안개:fog) 모드의 포그(안개:fog) 시작 및 종료 포인트. 이 설정은, 포그(안개:fog) 효과가 최초로 보이게 될 때의카메라로부터의 거리와 포그(안개:fog)가 최대 밀도가 될 때의 거리를 결정한다.
density
지수 포그(안개:fog) 모드에서의 포그(안개:fog) 밀도. 이 값은, 0에서 1의 값이 아니면 안된다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrameInterpolator.SetVelocity

Direct3DRMFrameInterpolator

참조 프레임을 기준으로서 지정의 프레임의 속도를 설정한다. 프레임은Direct3DRM3.Tick 또는Direct3DRMFrame3.Move 메소드에 대한 연속 호출할 것에, 참조 프레임을 기준으로서 [x, y, z] 벡터분만큼 이동한다.

구문

object. SetVelocity(reference As Direct3DRMFrame3,
  x As Single,
  y As Single,
  z As Single,
  with_rotation As CONST_DBOOLFLAGS)

요소

object
Direct3DRMFrameInterpolator오브젝트를 나타내는오브젝트식.
reference
참조로서 사용되는Direct3DRMFrame3 오브젝트.
x, y, z
프레임의 새로운 속도. 회전 속도에는 단위가 없기 때문에, 임의의 값으로 할 수 있다. Move와Tick메소드는, 이 값을 스케일링 한다.
with_rotation
직선 속도를 설정할 경우에, 오브젝트의 회전 속도를 고려한다 화도인지를 지정하는 플래그. D_TRUE의 경우, 오브젝트의 회전 속도가 계산에 포함된다. 그렇지 않으면, D_FALSE로 설정한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.


Direct3DRMLight

A어플리케이션은, 조명과 서로 교환하기 위해서Direct3DRMLight인터페이스의 메소드를 사용한다.

Direct3DRMLight인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

감쇠 | GetConstantAttenuation
GetLinearAttenuation
GetQuadraticAttenuation
SetConstantAttenuation
SetLinearAttenuation
SetQuadraticAttenuation
색 | GetColor
SetColor
SetColorRGB
유효 프레임 | GetEnableFrame
SetEnableFrame
조명 타입 | GetType
SetType
범위 | GetRange
SetRange
스포트 조명 옵션 | GetPenumbra
GetUmbra
SetPenumbra
SetUmbra

Direct3DRMLight인터페이스는,Direct3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.

  • AddDestroyCallback
  • CloneObject
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMLight오브젝트는,Direct3DRM3.CreateLight 또는Direct3DRM3.CreateLightRGB 메소드의 호출에 의해 취득된다.

Direct3DRMLight.GetColor

Direct3DRMLight

현재의Direct3DRMLight오브젝트의 색을 취득한다.

구문

object. GetColor( ) As Long

요소

object
Direct3DRMLight오브젝트를 나타내는오브젝트식.

반환값

색을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMLight.SetColor

Direct3DRMLight.GetConstantAttenuation

Direct3DRMLight

Direct3DRMLight오브젝트의 감쇠 정수를 취득한다.

구문

object. GetConstantAttenuation( ) As Single

요소

object
Direct3DRMLight오브젝트를 나타내는오브젝트식.

반환값

감쇠 정수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

위치를 가지는(무한하게 멀지 않다) 조명에는 감쇠 정수가 있어, 광원으로부터의 거리에 근거해 조명의 감쇠를 계산할 수 있다.

전감쇠 계수의 공식은 다음과 같다.

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

전감쇠 계수는 1보다 커지지 않는다. 감쇠 계수가 지정되지 않으면 디폴트값은, 감쇠 정수에 대해서는 1.0, 1차 감쇠 계수에 대해서는 0.0, 2차 감쇠 계수에 대해서는 0.0이다.

참조

Direct3DRMLight.SetConstantAttenuation

Direct3DRMLight.GetEnableFrame

Direct3DRMLight

조명의유효 프레임을 취득한다.

구문

object. GetEnableFrame( ) As Direct3DRMFrame3

요소

object
Direct3DRMLight오브젝트를 나타내는오브젝트식.

반환값

성공하면Direct3DRMFrame3 오브젝트를, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMLight.SetEnableFrame

Direct3DRMLight.GetLinearAttenuation

Direct3DRMLight

조명의 1차 감쇠 계수를 취득한다.

구문

object. GetLinearAttenuation( ) As Single

요소

object
Direct3DRMLight오브젝트를 나타내는오브젝트식.

반환값

1차 감쇠 계수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

위치를 가지는(무한하게 멀지 않다) 조명에는 감쇠 정수가 있어, 광원으로부터의 거리에 근거해 조명의 감쇠를 계산할 수 있다.

T전감쇠 계수의 공식은 다음과 같다.

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

전감쇠 계수는 1보다 커지지 않는다. 감쇠 계수가 지정되지 않으면 디폴트값은, 감쇠 정수에 대해서는 1.0, 1차 감쇠 계수에 대해서는 0.0, 2차 감쇠 계수에 대해서는 0.0이다.

참조

Direct3DRMLight.SetLinearAttenuation

Direct3DRMLight.GetPenumbra

Direct3DRMLight

spotlight의암영부의 각도를 취득한다.

구문

object. GetPenumbra( ) As Single

요소

object
Direct3DRMLight오브젝트를 나타내는오브젝트식.

반환값

라디안 단위의 암영부의 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMLight.SetPenumbra

Direct3DRMLight.GetQuadraticAttenuation

Direct3DRMLight

조명의 2차 감쇠 계수를 취득한다.

구문

object. GetQuadraticAttenuation( ) As Single

요소

object
Direct3DRMLight오브젝트를 나타내는오브젝트식.

반환값

2차 감쇠 계수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

위치를 가지는(무한하게 멀지 않다) 조명에는 감쇠 정수가 있어, 조명으로부터의 거리에 근거해 조명의 감쇠를 계산할 수 있다.

전감쇠 계수의 공식은 다음과 같다.

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

전감쇠 계수는 1보다 커지지 않는다. 감쇠 계수가 지정되지 않으면 디폴트값은, 감쇠 정수에 대해서는 1.0, 1차 감쇠 계수에 대해서는 0.0, 2차 감쇠 계수에 대해서는 0.0이다.

참조

Direct3DRMLight.SetQuadraticAttenuation

Direct3DRMLight.GetRange

Direct3DRMLight

현재의Direct3DRMLight오브젝트의 범위를 취득한다.

구문

object. GetRange( ) As Single

요소

object
Direct3DRMLight오브젝트를 나타내는오브젝트식.

반환값

범위를 나타내는 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMLight.SetRange

Direct3DRMLight.GetType

Direct3DRMLight

지정된 조명의 타입을 취득한다.

구문

object. GetType( ) As CONST_D3DRMLIGHTTYPE

요소

object
Direct3DRMLight오브젝트를 나타내는오브젝트식.

반환값

CONST_D3DRMLIGHTTYPE 열거형의 멤버의 하나를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMLight.SetType

Direct3DRMLight.GetUmbra

Direct3DRMLight

Direct3DRMLight오브젝트의명부의 각도를 취득한다. 디폴트는, 0.4 라디안이다.

구문

object. GetUmbra( ) As Single

요소

object
Direct3DRMLight오브젝트를 나타내는오브젝트식.

반환값

라디안 단위의 명부의 각도를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMLight.SetUmbra

Direct3DRMLight.SetColor

Direct3DRMLight

지정된 조명의 색을 설정한다.

구문

object. SetColor(c As Long)

요소

object
Direct3DRMLight오브젝트를 나타내는오브젝트식.
c
조명의 새로운 색. 적, 초록, 파랑의 색요소 뿐만이 아니라, 알파 요소도 반드시 세트 한다. 그렇게 하지 않으면 오브젝트가 가시가 되지 않는 것이 있다. 색은 4바이트의Long로 나타내진다. 고바이트는 알파 요소이며, 후속의 바이트가 적, 초록, 파랑을 정의한다. 보다 간단하게 색을 구축하려면 DirectX7 오브젝트의CreateColorRGBA를 사용해, 풀 알파를 희망하고 있을 뿐(만큼)의 경우는SetColorRGB를 사용한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMLightInterpolator 오브젝트에 컬러 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMLight.GetColor

Direct3DRMLight.SetColorRGB

Direct3DRMLight

지정된 조명의 색을 R, B, G 각각의 값으로 설정한다.

구문

object. SetColorRGB(r As Single,
  g As Single,
  b As Single)

요소

object
Direct3DRMLight오브젝트를 나타내는오브젝트식.
r, g, b
조명의 새로운 색.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMLightInterpolator 오브젝트에 RGB 컬러 키를 추가하기 위해서도 사용한다.

Direct3DRMLight.SetConstantAttenuation

Direct3DRMLight

조명의 감쇠 계수를 설정한다.

구문

object. SetConstantAttenuation(atn As Single)

요소

object
Direct3DRMLight오브젝트를 나타내는오브젝트식.
atn
새로운 감쇠 정수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

위치를 가지는(무한하게 멀지 않다) 조명에는 감쇠 정수가 있어, 조명으로부터의 거리에 근거해 조명의 감쇠를 계산할 수 있다.

전감쇠 계수의 공식은 다음과 같다.

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

전감쇠 계수는 1보다 커지지 않는다. 감쇠 계수가 지정되지 않으면 디폴트값은, 감쇠 정수에 대해서는 1.0, 1차 감쇠 계수에 대해서는 0.0, 2차 감쇠 계수에 대해서는 0.0이다.

이 메소드는,Direct3DRMLightInterpolator 오브젝트에 감쇠 정수 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMLight.GetConstantAttenuation

Direct3DRMLight.SetEnableFrame

Direct3DRMLight

조명의유효 프레임을 설정한다.

구문

object. SetEnableFrame(f As Direct3DRMFrame3)

요소

object
Direct3DRMLight오브젝트를 나타내는오브젝트식.
f
Direct3DRMLight오브젝트의Direct3DRMFrame3 인터페이스. 이 프레임의 아이 프레임도, 이 조명이 유효하게 된다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMLight.GetEnableFrame

Direct3DRMLight.SetLinearAttenuation

Direct3DRMLight

조명의 1차 감쇠 계수를 설정한다.

구문

object. SetLinearAttenuation(atn As Single)

요소

object
Direct3DRMLight오브젝트를 나타내는오브젝트식.
atn
새로운 1차 감쇠 계수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

위치를 가지는(무한하게 멀지 않다) 조명에는 감쇠 정수가 있어, 조명으로부터의 거리에 근거해 조명의 감쇠를 계산할 수 있다.

전감쇠 계수의 공식은 다음과 같다.

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

전감쇠 계수는 1보다 커지지 않는다. 감쇠 계수가 지정되지 않으면 디폴트값은, 감쇠 정수에 대해서는 1.0, 1차 감쇠 계수에 대해서는 0.0, 2차 감쇠 계수에 대해서는 0.0이다.

이 메소드는,Direct3DRMLightInterpolator 오브젝트에 1차 감쇠 정수 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMLight.GetLinearAttenuation

Direct3DRMLight.SetPenumbra

Direct3DRMLight

원추의암영부의 각도를 설정한다.

구문

object. SetPenumbra(p As Single)

요소

object
Direct3DRMLight오브젝트를 나타내는오브젝트식.
p
라디안 단위의 새로운 암영부의 각도. 이 각도는 암부의 각도보다 큰지, 동일하지 않으면 안 된다. 암영부의 각도를 명부의 각도보다 작게 설정했을 경우, 암영부는 명부와 같은 각도가 된다. 디폴트값은 0.5 라디안이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMLightInterpolator 오브젝트에 그림자 각도 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMLight.GetPenumbra

Direct3DRMLight.SetQuadraticAttenuation

Direct3DRMLight

조명의 2차 감쇠 계수를 설정한다.

구문

object. SetQuadraticAttenuation(atn As Single)

요소

object
Direct3DRMLight오브젝트를 나타내는오브젝트식.
atn
새로운 2차 감쇠 계수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

위치를 가지는(무한하게 멀지 않다) 조명에는 감쇠 정수가 있어, 조명으로부터의 거리에 근거해 조명의 감쇠를 계산할 수 있다.

전감쇠 계수의 공식은 다음과 같다.

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

전감쇠 계수는 1보다 커지지 않는다. 감쇠 계수가 지정되지 않으면 디폴트값은, 감쇠 정수에 대해서는 1.0, 1차 감쇠 계수에 대해서는 0.0, 2차 감쇠 계수에 대해서는 0.0이다.

이 메소드는,Direct3DRMLightInterpolator 오브젝트에 2차 감쇠 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMLight.GetQuadraticAttenuation

Direct3DRMLight.SetRange

Direct3DRMLight

spotlight의 범위를 설정한다. 이 조명은, 범위내에 있는 오브젝트에 한정해 영향을 준다.

구문

object. SetRange(mg As Single)

요소

object
Direct3DRMLight오브젝트를 나타내는오브젝트식.
mg
새로운 범위. 디폴트값은, 256 모델 공간 단위이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

범위 프로퍼티는, spotlight만의 것이다. 이 메소드는,Direct3DRMLightInterpolator 오브젝트에 범위 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMLight.GetRange

Direct3DRMLight.SetType

Direct3DRMLight

조명의 타입을 변경한다.

구문

object. SetType(t As CONST_D3DRMLIGHTTYPE)

요소

object
Direct3DRMLight오브젝트를 나타내는오브젝트식.
t
새로운 조명 타입을CONST_D3DRMLIGHTTYPE 열거형의 멤버의 하나로 지정한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMLight.GetType

Direct3DRMLight.SetUmbra

Direct3DRMLight

원추의명부의 각도를 설정한다.

구문

object. SetUmbra(u As Single)

요소

object
Direct3DRMLight오브젝트를 나타내는오브젝트식.
u
라디안 단위의 새로운 명부의 각도. 이 각도는, 암영부의 각도보다 작은지, 동일하지 않으면 안 된다. 명부의 각도를 암영부의 각도보다 크게 설정했을 경우, 명부는 암영부와 같은 각도가 된다. 디폴트값은 0.4 라디안이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMLightInterpolator 오브젝트에 그림자 각도 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMLight.GetUmbra


Direct3DRMLightArray

어플리케이션은,Direct3DRMLightArray인터페이스의 메소드를 사용해 조명 오브젝트를 그룹화 한다. 조명의 배열은, 0이 기준이 되어 있다 (0~N-1).

Direct3DRMLightArray인터페이스는, 다음의 메소드를 지원 한다.

  • GetElement
  • GetSize

Direct3DRMLightArray오브젝트는,Direct3DRMFrame3.GetLights 메소드의 호출에 의해 취득된다.

Direct3DRMLightArray.GetElement

Direct3DRMLightArray

Direct3DRMLightArray오브젝트로부터 지정된 요소를 취득한다.

구문

object. GetElement(index As Long) As Direct3DRMLight

요소

object
Direct3DRMLightArray오브젝트를 나타내는오브젝트식.
index
배열 요소.

반환값

Direct3DRMLight 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMLightArray.GetSize

Direct3DRMLightArray

Direct3DRMLightArray오브젝트에 포함되어 있는 요소수를 취득한다.

구문

object. GetSize( ) As Long

요소

object
Direct3DRMLightArray오브젝트를 나타내는오브젝트식.

반환값

요소수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.


Direct3DRMLightInterpolator

인타포레이타는, 액션을 저장 한 후, 중간값을 자동 계산해, 오브젝트에 액션을 적용하는 방법을 제공한다. 인타포레이타를 사용해, 색을 혼합해, 다른 위치간에서 오브젝트를 원활히 이동해, 메쉬를 morphing 해, 게다가 다른 다양한 변환도 실시할 수가 있다.

Direct3DRMLight 오브젝트는,Direct3DRMLightInterpolator오브젝트에 Attach 할 수 있다. 인타포레이타의 상세한 것에 대하여는, 추가 정보의 「인타포레이타」를 참조할것.

Direct3DRMLightInterpolator인터페이스에는, 다음의 메소드가 포함된다.

오브젝트의 Attach | AttachObject
DetachObject
GetAttachedObjects
감쇠 | SetConstantAttenuation
SetLinearAttenuation
SetQuadraticAttenuation
색 | SetColor
SetColorRGB
보간의 실행 | GetIndex
Interpolate
SetIndex
범위 | SetRange
spotlight 옵션 | SetPenumbra
SetUmbra

게다가Direct3DRMLightInterpolator는,Direct3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.

  • AddDestroyCallback
  • Clone
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMLightInterpolator.AttachObject

Direct3DRMLightInterpolator

오브젝트를 인타포레이타에 접속한다.

구문

object. AttachObject(mObject As Direct3DRMObject)

요소

object
Direct3DRMLightInterpolator오브젝트를 나타내는오브젝트식.
mObject
인타포레이타에 Attach 하는Direct3DRMObject 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

Attach 되는 오브젝트는, 다른 인타포레이타에서도, 인타포레이타가xInterpolator형이 되는 타입x의 오브젝트에서도 좋다. 예를 들어,Direct3DRMLight 오브젝트는,Direct3DRMLightInterpolator오브젝트에 Attach 할 수 있다.

Direct3DRMLightInterpolator.DetachObject

Direct3DRMLightInterpolator

인타포레이타로부터 오브젝트의 Attach를 해제한다.

구문

object. DetachObject(mObject As Direct3DRMObject)

요소

object
Direct3DRMLightInterpolator오브젝트를 나타내는오브젝트식.
mObject
인타포레이타로부터 Attach를 제외하는Direct3DRMObject 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMLightInterpolator.GetAttachedObjects

Direct3DRMLightInterpolator

인타포레이타에 현재 Attach 되고 있는 오브젝트를 취득한다.

구문

object. GetAttachedObjects( ) As Direct3DRMObjectArray

요소

object
Direct3DRMLightInterpolator오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMObjectArray 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMLightInterpolator.GetIndex

Direct3DRMLightInterpolator

인타포레이타의 현재의 내부 인덱스(시간)를 취득한다.

구문

object. GetIndex( ) As Single

요소

object
Direct3DRMLightInterpolator오브젝트를 나타내는오브젝트식.

반환값

인타포레이타의 현재의 내부 인덱스를 포함한 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

인타포레이타에 저장 되고 있는 각 키는, 인덱스값을 가진다. 키를(메소드를 사용해) 기록 하면 와, 키에는, 현재의 인타포레이타의 인덱스값으로 스탬프가 밀린다. 키의 인덱스값은, 스탬프를 밀린 후, 바뀔 것은 없다.

Direct3DRMLightInterpolator.Interpolate

Direct3DRMLightInterpolator

인타포레이타에 저장 되고 있는 키간을 보간 해, 일련의 액션을 생성한다. 그 후, 액션은, 지정의 오브젝트에 적용된다. 오브젝트의 지정이 없으면, 액션은, 현재 Attach 되고 있는 오브젝트에 적용된다.

구문

object. Interpolate(val As Single,
  mObject As Direct3DRMObject,
  options As CONST_D3DRMINTERPOLATIONFLAGS)

요소

object
Direct3DRMLightInterpolator오브젝트를 나타내는오브젝트식.
val
인타포레이타의 현재의 내부 인덱스를 포함한 값.
mObject
Direct3DRMObject 오브젝트. 이 오브젝트는, 인타포레이타에 저장 떠날 수 있어 모든 프로퍼티에 대한 보간값을 할당하는 오브젝트를 나타낸다. 이 포인터는 NOTHING에서도 좋다. 그 경우에는, 모든 접속되고 있는 오브젝트의 프로퍼티값에는, 보간값이 세트 된다.
options
실행하는 보간의 종류를 제어하는CONST_D3DRMINTERPOLATIONFLAGS 열거형의 값의 하나.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMLightInterpolator.SetColor

Direct3DRMLightInterpolator

Direct3DRMLightInterpolator오브젝트에 컬러 키를 추가한다.

구문

object. SetColor(c As Long)

요소

object
Direct3DRMLightInterpolator오브젝트를 나타내는오브젝트식.
c
프레임의 새로운 색. 적, 초록, 파랑의 색요소 외에 알파 요소도 세트 한다. 그렇게 하지 않으면 오브젝트가 가시가 되지 않는 것이 있다. 색은 4바이트의Long로 나타내진다. 고바이트는 알파 요소이며, 후속의 바이트가 적, 초록, 파랑을 정의한다. 보다 간단하게 색을 구축하려면 DirectX7 오브젝트의CreateColorRGBA를 사용해, 풀 알파를 희망하고 있을 뿐(만큼)의 경우는SetColorRGB를 사용한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMLightInterpolator.SetColorRGB

Direct3DRMLightInterpolator

Direct3DRMLightInterpolator오브젝트에 RGB 컬러 키를 추가한다.

구문

object. SetColorRGB(r As Single,
  g As Single,
  b As Single)

요소

object
Direct3DRMLightInterpolator오브젝트를 나타내는오브젝트식.
r, g, b
조명의 새로운 적, 초록, 파랑의 색요소.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMLightInterpolator.SetConstantAttenuation

Direct3DRMLightInterpolator

Direct3DRMLightInterpolator오브젝트에 감쇠 정수 키를 추가한다.

구문

object. SetConstantAttenuation(atn As Single)

요소

object
Direct3DRMLightInterpolator오브젝트를 나타내는오브젝트식.
atn
새로운 감쇠 정수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

위치를 가지는(무한하게 멀지 않다) 조명에는 감쇠 정수가 있어, 조명으로부터의 거리에 근거해 조명의 감쇠를 계산할 수 있다.

전감쇠 계수의 공식은 다음과 같다.

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

전감쇠 계수는 1보다 커지지 않는다. 감쇠 계수가 지정되지 않으면 디폴트값은, 감쇠 정수에 대해서는 1.0, 1차 감쇠 계수에 대해서는 0.0, 2차 감쇠 계수에 대해서는 0.0이다.

이 메소드는,Direct3DRMLightInterpolator 오브젝트에 감쇠 정수 키를 추가하기 위해서도 사용한다.

Direct3DRMLightInterpolator.SetIndex

Direct3DRMLightInterpolator

인타포레이타의 내부 인덱스(시간)로 지정의 값을 세트 한다. 다른 인타포레이타가 그 인타포레이타에 Attach 되고 있으면, 이 메소드는, 재귀적으로 그러한 인덱스를 같은 값에 동기 시킨다.

구문

object. SetIndex(val As Single)

요소

object
Direct3DRMLightInterpolator오브젝트를 나타내는오브젝트식.
val
인타포레이타의 내부 인덱스에 대해서 세트 되는 시간.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

인타포레이타에 저장 되고 있는 각 키는, 인덱스값을 가진다. 키를(메소드를 사용해) 기록 하면 와, 키에는, 현재의 인타포레이타의 인덱스값으로 스탬프가 밀린다. 키의 인덱스값은, 스탬프를 밀린 후, 바뀔 것은 없다.

Direct3DRMLightInterpolator.SetLinearAttenuation

Direct3DRMLightInterpolator

Direct3DRMLightInterpolator오브젝트에 1차 감쇠 키를 추가한다.

구문

object. SetLinearAttenuation(atn As Single)

요소

object
Direct3DRMLightInterpolator오브젝트를 나타내는오브젝트식.
atn
새로운 1차 감쇠 계수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

위치를 가지는(무한하게 멀지 않다) 조명에는 감쇠 정수가 있어, 조명으로부터의 거리에 근거해 조명의 감쇠를 계산할 수 있다.

전감쇠 계수의 공식은 다음과 같다.

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

전감쇠 계수는 1보다 커지지 않는다. 감쇠 계수가 지정되지 않으면 디폴트값은, 감쇠 정수에 대해서는 1.0, 1차 감쇠 계수에 대해서는 0.0, 2차 감쇠 계수에 대해서는 0.0이다.

Direct3DRMLightInterpolator.SetPenumbra

Direct3DRMLightInterpolator

Direct3DRMLightInterpolator오브젝트에 그림자 각도 키를 추가한다.

구문

object. SetPenumbra(p As Single)

요소

object
Direct3DRMLightInterpolator오브젝트를 나타내는오브젝트식.
p
라디안 단위의 새로운 암영부의 각도. 이 각도는 암부의 각도보다 큰지, 동일하지 않으면 안 된다. 암영부의 각도를 명부의 각도보다 작게 설정했을 경우, 암영부는 명부와 같은 각도가 된다. 디폴트값은 0.5 라디안이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMLightInterpolator.SetQuadraticAttenuation

Direct3DRMLightInterpolator

Direct3DRMLightInterpolator오브젝트에 2차 감쇠 키를 추가한다

구문

object. SetQuadraticAttenuation(atn As Single)

요소

object
Direct3DRMLightInterpolator오브젝트를 나타내는오브젝트식.
atn
새로운 2차 감쇠 계수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

위치를 가지는(무한하게 멀지 않다) 조명에는 감쇠 정수가 있어, 조명으로부터의 거리에 근거해 조명의 감쇠를 계산할 수 있다.

전감쇠 계수의 공식은 다음과 같다.

1 / [constant_attenuation_factor + distance * linear_attenuation_factor + (distance**2) * quadratic_attenuation_factor]

전감쇠 계수는 1보다 커지지 않는다. 감쇠 계수가 지정되지 않으면 디폴트값은, 감쇠 정수에 대해서는 1.0, 1차 감쇠 계수에 대해서는 0.0, 2차 감쇠 계수에 대해서는 0.0이다.

이 메소드는,Direct3DRMLightInterpolator 오브젝트에 2차 감쇠 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMLight.GetQuadraticAttenuation

Direct3DRMLightInterpolator.SetRange

Direct3DRMLightInterpolator

Direct3DRMLightInterpolator오브젝트에 범위 키를 추가한다.

구문

object. SetRange(mg As Single)

요소

object
Direct3DRMLightInterpolator오브젝트를 나타내는오브젝트식.
mg
새로운 범위. 디폴트값은, 256 모델 공간 단위이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

범위 프로퍼티는, spotlight만의 것이다.

Direct3DRMLightInterpolator.SetUmbra

Direct3DRMLightInterpolator

Direct3DRMLightInterpolator오브젝트에 그림자 각도 키를 추가한다.

구문

object. SetUmbra(u As Single)

요소

object
Direct3DRMLightInterpolator오브젝트를 나타내는오브젝트식.
u
라디안 단위의 새로운 명부의 각도. 이 각도는, 암영부의 각도보다 작은지, 동일하지 않으면 안 된다. 명부의 각도를 암영부의 각도보다 크게 설정했을 경우, 명부는 암영부와 같은 각도가 된다. 디폴트값은 0.4 라디안이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.


Direct3DRMMaterial2

어플리케이션은, 머트리얼 오브젝트와 서로 교환하기 위해서Direct3DRMMaterial2인터페이스의 메소드를 사용한다.

머트리얼에서는, 표면이 어떻게 빛을 반사하는지를 정의한다. 머트리얼에는,방사 프로퍼티와반사 프로퍼티의 2개의 요소가 있어, 그 휘도(Luminance)는강도설정에 의해 정해진다. 지수의 값은 반사하는 하이라이트의 날카로움을 결정해 5의 값은 금속의 외관을 주어보다 큰 값은 보다 플라스틱적인 외관을 준다.

어플리케이션은,GetEmissive 와SetEmissive 메소드를 사용해 머트리얼의 방사를,GetSpecular 와SetSpecular 메소드를 사용해 반사 요소를,GetPower 와SetPower 메소드를 사용해 지수를 제어할 수가 있다.

Direct3DRMMaterial2오브젝트는,SetAmbient 가 불려 갈 때까지, 오브젝트의 면의 색을 앰비언트의 색으로서 사용한다.

Direct3DRMMaterial2인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

앰비언트 | GetAmbient
SetAmbient
방사 | GetEmissive
SetEmissive
반사 지수 | GetPower
SetPower
반사 | GetSpecular
SetSpecular

Direct3DRMMaterial2인터페이스는,Direct3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.

  • AddDestroyCallback
  • CloneObject
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMMaterial오브젝트는,Direct3DRM3.CreateMaterial 메소드의 사용에 의해 취득된다.

Direct3DRMMaterial2.GetAmbient

Direct3DRMMaterial2

머트리얼의 현재의 앰비언트값을 취득한다.

구문

object. GetAmbient(r As Single,
  g As Single,
  b As Single)

요소

object
Direct3DRMMaterial2오브젝트를 나타내는오브젝트식.
r
앰비언트 컬러의 빨강 요소.
g
앰비언트 컬러의 초록 요소.
b
앰비언트 컬러의 파랑 요소.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMaterial2.GetEmissive

Direct3DRMMaterial2

머트리얼의방사 프로퍼티의 설정을 취득한다. 이 프로퍼티의 설정은, 색과 오브젝트가 발산하는 빛의 지수를 나타낸다.

구문

object. GetEmissive(r As Single,
  g As Single,
  b As Single)

요소

object
Direct3DRMMaterial2오브젝트를 나타내는오브젝트식.
r, g, b
방사의 적, 초록, 파랑의 색요소.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMaterial2.SetEmissive

Direct3DRMMaterial2.GetPower

Direct3DRMMaterial2

지정된 머트리얼에서의 반사 지수를 취득한다.

구문

object. GetPower( ) As Single

요소

object
Direct3DRMMaterial2오브젝트를 나타내는오브젝트식.

반환값

반사 지수의 지수를 나타내는 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMaterial2.SetPower

Direct3DRMMaterial2.GetSpecular

Direct3DRMMaterial2

머트리얼의 반사 하이라이트의 색을 취득한다.

구문

object. GetSpecular(r As Single,
  g As Single,
  b As Single)

요소

object
Direct3DRMMaterial2오브젝트를 나타내는오브젝트식.
r, g, b
메소드가 제어를 돌려줄 때의 반사 하이라이트의 적, 초록, 파랑의 색요소.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMaterial2.SetSpecular

Direct3DRMMaterial2.SetAmbient

Direct3DRMMaterial2

머트리얼의 앰비언트값을 설정한다. 디폴트는 확산색이다.

구문

object. SetAmbient(r As Single,
  g As Single,
  b As Single)

요소

object
Direct3DRMMaterial2오브젝트를 나타내는오브젝트식.
r
앰비언트 컬러의 빨강 요소.
g
앰비언트 컬러의 초록 요소.
b
앰비언트 컬러의 파랑 요소.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMaterial2.SetEmissive

Direct3DRMMaterial2

머트리얼의 방사 프로퍼티를 설정한다.

구문

object. SetEmissive(r As Single,
  g As Single,
  b As Single)

요소

object
Direct3DRMMaterial2오브젝트를 나타내는오브젝트식.
r, g, b
방사의 색의 적, 초록, 파랑 요소.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMMaterialInterpolator 오브젝트에 방사 프로퍼티 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMMaterial2.GetEmissive

Direct3DRMMaterial2.SetPower

Direct3DRMMaterial2

머트리얼의 반사 지수의 지수를 설정한다.

구문

object. SetPower(power As Single)

요소

object
Direct3DRMMaterial2오브젝트를 나타내는오브젝트식.
power
새로운 반사 지수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMMaterialInterpolator 오브젝트에 반사 지수 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMMaterial2.GetPower

Direct3DRMMaterial2.SetSpecular

Direct3DRMMaterial2

머트리얼의 반사 하이라이트의 색을 설정한다.

구문

object. SetSpecular(r As Single,
  g As Single,
  b As Single)

요소

object
Direct3DRMMaterial2오브젝트를 나타내는오브젝트식.
r, g, b
반사 하이라이트의 색의 적, 초록, 파랑의 각 요소.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMMaterialInterpolator 오브젝트에 반사 컬러 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMMaterial2.GetSpecular


Direct3DRMMaterialInterpolator

인타포레이타는, 액션을 저장 한 후, 중간값을 자동 계산해, 오브젝트에 액션을 적용하는 방법을 제공한다. 인타포레이타를 사용해, 색을 혼합해, 다른 위치간에서 오브젝트를 원활히 이동해, 메쉬를 morphing 해, 게다가 다른 다양한 변환도 실시할 수가 있다.

Direct3DRMMaterial2 오브젝트는,Direct3DRMMaterialInterpolator오브젝트에 Attach 할 수 있다. 인타포레이타의 상세한 것에 대하여는, 추가 정보의 「인타포레이타」를 참조할것.

Direct3DRMMaterialInterpolator에는 다음의 메소드가 포함된다.

오브젝트의 Attach | AttachObject
DetachObject
GetAttachedObjects
방사 | SetEmissive
보간의 실행 | GetIndex
Interpolate
SetIndex
반사 지수 | SetPower
반사 | SetSpecular

게다가Direct3DRMMaterialInterpolator는,Direct3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.

  • AddDestroyCallback
  • Clone
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMMaterialInterpolator.AttachObject

Direct3DRMMaterialInterpolator

오브젝트를 인타포레이타에 접속한다.

구문

object. AttachObject(mObject As Direct3DRMObject)

요소

object
Direct3DRMMaterialInterpolator오브젝트를 나타내는오브젝트식.
mObject
인타포레이타에 Attach 하는Direct3DRMObject 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

Attach 되는 오브젝트는, 다른 인타포레이타에서도, 인타포레이타가xInterpolator형이 되는 타입x의 오브젝트에서도 좋다. 예를 들어,Direct3DRMMaterial2 오브젝트는,Direct3DRMMaterialInterpolator오브젝트에 Attach 할 수 있다.

Direct3DRMMaterialInterpolator.DetachObject

Direct3DRMMaterialInterpolator

인타포레이타로부터 오브젝트의 Attach를 해제한다.

구문

object. DetachObject(mObject As Direct3DRMObject)

요소

object
Direct3DRMMaterialInterpolator오브젝트를 나타내는오브젝트식.
mObject
인타포레이타로부터 Attach를 제외하는Direct3DRMObject 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMaterialInterpolator.GetAttachedObjects

Direct3DRMMaterialInterpolator

인타포레이타에 현재 Attach 되고 있는 오브젝트를 취득한다.

구문

object. GetAttachedObjects( ) As Direct3DRMObjectArray

요소

object
Direct3DRMMaterialInterpolator오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMObjectArray 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMaterialInterpolator.GetIndex

Direct3DRMMaterialInterpolator

인타포레이타의 현재의 내부 인덱스(시간)를 취득한다.

구문

object. GetIndex( ) As Single

요소

object
Direct3DRMMaterialInterpolator오브젝트를 나타내는오브젝트식.

반환값

인타포레이타의 현재의 내부 인덱스를 포함한 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

인타포레이타에 저장 되고 있는 각 키는, 인덱스값을 가진다. 키를(메소드를 사용해) 기록 하면 와, 키에는, 현재의 인타포레이타의 인덱스값으로 스탬프가 밀린다. 키의 인덱스값은, 스탬프를 밀린 후, 바뀔 것은 없다.

Direct3DRMMaterialInterpolator.Interpolate

Direct3DRMMaterialInterpolator

인타포레이타에 저장 되고 있는 키간을 보간 해, 일련의 액션을 생성한다. 그 후, 액션은, 지정의 오브젝트에 적용된다. 오브젝트의 지정이 없으면, 액션은, 현재 Attach 되고 있는 오브젝트에 적용된다.

구문

object. Interpolate(val As Single,
  mObject As Direct3DRMObject,
  options As CONST_D3DRMINTERPOLATIONFLAGS)

요소

object
Direct3DRMMaterialInterpolator오브젝트를 나타내는오브젝트식.
val
인타포레이타의 현재의 내부 인덱스를 포함한 값.
mObject
Direct3DRMObject 오브젝트. 이 오브젝트는, 인타포레이타에 저장 떠날 수 있어 모든 프로퍼티에 대한 보간값을 할당하는 오브젝트를 나타낸다. 이 포인터는 NOTHING에서도 좋다. 그 경우, 모든 Attach 되고 있는 오브젝트의 프로퍼티값에는, 보간값이 세트 된다.
options
실행하는 보간의 종류를 제어하는CONST_D3DRMINTERPOLATIONFLAGS 열거형의 값의 하나.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMaterialInterpolator.SetEmissive

Direct3DRMMaterialInterpolator

Direct3DRMMaterialInterpolator오브젝트에 방사 프로퍼티 키를 추가한다.

구문

object. SetEmissive(r As Single,
  g As Single,
  b As Single)

요소

object
Direct3DRMMaterialInterpolator오브젝트를 나타내는오브젝트식.
r, g, b
방사의 색의 적, 초록, 파랑 요소.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMaterialInterpolator.SetIndex

Direct3DRMMaterialInterpolator

인타포레이타의 내부 인덱스(시간)로 지정의 값을 세트 한다. 다른 인타포레이타가 그 인타포레이타에 Attach 되고 있으면, 이 메소드는, 재귀적으로 그러한 인덱스를 같은 값에 동기 시킨다.

구문

object. SetIndex(val As Single)

요소

object
Direct3DRMMaterialInterpolator오브젝트를 나타내는오브젝트식.
val
인타포레이타의 내부 인덱스에 대해서 세트 되는 시간.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

인타포레이타에 저장 되고 있는 각 키는, 인덱스값을 가진다. 키를(메소드를 사용해) 기록 하면 와, 키에는, 현재의 인타포레이타의 인덱스값으로 스탬프가 밀린다. 키의 인덱스값은, 스탬프를 밀린 후, 바뀔 것은 없다.

Direct3DRMMaterialInterpolator.SetPower

Direct3DRMMaterialInterpolator

Direct3DRMMaterialInterpolator오브젝트에 반사 지수 키를 추가한다.

구문

object. SetPower(power As Single)

요소

object
Direct3DRMMaterialInterpolator오브젝트를 나타내는오브젝트식.
power
새로운 반사 지수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

머트리얼의 반사 프로퍼티에서는,power파라미터의 값에 의해 반사하는 하이라이트의 날카로움이 정해진다. 5의 값은 금속의 외관을 주어보다 큰 값은 보다 플라스틱적인 외관을 준다.

Direct3DRMMaterialInterpolator.SetSpecular

Direct3DRMMaterialInterpolator

Direct3DRMMaterialInterpolator오브젝트에 반사 컬러 키를 추가한다.

구문

object. SetSpecular(r As Single,
  g As Single,
  b As Single)

요소

object
Direct3DRMMaterialInterpolator오브젝트를 나타내는오브젝트식.
r, g, b
반사 하이라이트의 색의 적, 초록, 파랑의 각 요소.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.


Direct3DRMMesh

어플리케이션은,Direct3DRMMesh인터페이스의 메소드를 사용해, 메쉬의 그룹이라고 회화한다. 메쉬는, 다각형면세트로부터 구성되는비주얼 오브젝트이다. 메쉬는, 버텍스세트와 면세트 (면은 메쉬의 버텍스와 법선에 의해 정의된다)를 정의한다. 몇개의 면이 사용하고 있는 버텍스 또는 법선을 변경 하면, 그것을 공유하는 모든 면의 외관이 바뀐다.

메쉬의 버텍스는 메쉬중의 면의 위치를 정의해, 이것들을 사용해 텍스쳐 맵내의 2 D좌표를 정의할 수도 있다.

Direct3DRMMesh와Direct3DRMMeshBuilder3 를 사용해, Microsoft® Direct3D® 보관 유지 모드로 메쉬를 조작할 수가 있다.

어플리케이션으로, 같은 특성 (머트리얼, 텍스쳐등)을 몇개의 버텍스 또는 면에 할당할 필요가 있는 경우,Direct3DRMMesh인터페이스를 사용해, 이것들을 1개의 그룹에 정리할 수가 있다. 어플리케이션이 2개가 다른 그룹간에 버텍스를 공유할 필요가 있는 경우 (예를 들어, 메쉬중의 인접하는 면의 색이 다른 경우), 버텍스는 양쪽 모두의 그룹에 중복 하고 있지 않으면 안 된다. Direct3DRMMesh.AddGroup 메소드는, 그룹 식별자를 면의 집합에 할당한다. 이 식별자를 사용해, 후속의 호출로 그룹을 참조한다.

Direct3DRMMeshBuilder3와Direct3DRMMesh인터페이스에 의해, 어플리케이션은 3개 이상의 측면을 가지는 면을 생성 할 수가 있다. 예를 들어, 어플리케이션이 렌더링 하고 있는 하드웨어에 64 K의 제한이 있어, 메쉬가 그 사이즈를 넘고 있는 경우, 이것들은 메쉬를 자동적으로 복수의 버퍼에 분할한다. 이러한 기능은,Direct3DRMMesh와Direct3DRMMeshBuilder3 API를 Direct3D API로부터 떼어내 세트 한다.

Direct3DRMMesh.SetGroupColor ,SetGroupColorRGB ,SetGroupTexture , 및SetGroupMaterial 메소드를 사용해, 메쉬의 각면 또는 메쉬의 모든 면에 대해서 동시에, 개별의 색, 텍스쳐, 머트리얼 프로퍼티를 정의할 수가 있다.

렌더링 하는 메쉬에 대해서는,Direct3DRMFrame3.AddVisual 메소드를 사용해, 최초로 프레임에 추가해야 한다. 단일의 메쉬를 복수의 프레임에 추가해, 그 메쉬의 복수의 인스턴스를 생성 할 수가 있다.

Direct3DRMMesh.SetGroupQuality 메소드에 대한 호출로 지정된 것처럼, 어플리케이션은, 플랫, 굿 로, 폰 쉐이드 모드를 사용할 수가 있다(그러나, 폰 쉐이딩은 아직 이용 가능하지 않다).

Direct3DRMMesh인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

색 | GetGroupColor
SetGroupColor
SetGroupColorRGB
생성과 정보 | AddGroup
GetBox
GetGroupCount
GetGroupData
GetSizes
GetGroupDataSize
머트리얼 | GetGroupMaterial
SetGroupMaterial
그 외 | Scale
Translate
렌더링 퀄리티 | GetGroupQuality
SetGroupQuality
텍스쳐 맵핑 | GetGroupMapping
SetGroupMapping
텍스쳐 | GetGroupTexture
SetGroupTexture
버텍스의 위치 | GetVertex
GetVertexCount
GetVertices
SetVertex
SetVertices

Direct3DRMMesh인터페이스는,Direct3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.

  • AddDestroyCallback
  • Clone
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMMesh오브젝트는,Direct3DRM3.CreateMesh 메소드의 사용에 의해 취득된다.

Direct3DRMMesh.AddGroup

Direct3DRMMesh

면의 모임을 그룹화 해, 그 그룹의 식별자를 취득한다. 메쉬에 최초로 추가되는 그룹의 인덱스는, 항상 0이다. 이후의 그룹의 인덱스는, 각각 1씩 증가한다.

구문

object. AddGroup(vertexCount As Long,
  faceCount As Long,
  verticesPerFace As Long,
  fdata() As Long) As Long

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
vertexCount, faceCount
그룹에 포함되는 버텍스와 면의 수.
verticesPerFace
모든 면이 같은 수의 버텍스를 가지는 경우, 면 당의 버텍스의 수. 그룹중의 면이 가지는 버텍스의 수가 일정이 아닐 때는, 이 파라미터에 0을 지정하지 않으면 안 된다.
fdata
면데이터. verticesPerFace파라미터에 값이 설정되어 있는 경우, 이 데이터는 단지, 그룹의 버텍스 배열에의 인덱스 리스트이다. verticesPerFace가 0 때는, 버텍스 인덱스보다, 그 면의 버텍스의 수를 나타내는 정수값을 우선하지 않으면 안 된다. 예를 들어,verticesPerFace가 0으로, 그룹을 구성하는 면이 삼각형과 사각형인 경우, 데이터는 다음과 같이 된다. [ 3, 인덱스, 인덱스, 인덱스, 4, 인덱스, 인덱스, 인덱스, 인덱스, 3, 인덱스, 인덱스, 인덱스, ...]

반환값

그룹을 식별하는 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

새롭게 추가된 그룹에는, 이하의 디폴트의 프로퍼티가 주어진다.

  • 흰색.
  • 텍스쳐 없음.
  • 반사 없음.
  • 버텍스 배열의 각 버텍스의 위치, 법선, 색은 0.

버텍스의 위치를 설정하려면 ,Direct3DRMMesh.SetVertices 메소드를 사용한다.

Direct3DRMMesh.GetBox

Direct3DRMMesh

Direct3DRMMesh오브젝트를 포함한 경계 박스를 취득한다. 경계 박스는, 각각의 차원의모델 좌표의 최소 값과 최대치를 나타낸다.

구문

object. GetBox(vector As D3DRMBOX)

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
vector
경계 박스 좌표를 받는D3DRMBOX 형.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMesh.GetGroupColor

Direct3DRMMesh

그룹의 색을 취득한다.

구문

object. GetGroupColor(id As Long) As Long

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.

반환값

성공하면, 색을 나타내는 값을 돌려준다. 실패하면 0을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMesh.SetGroupColor ,Direct3DRMMesh.SetGroupColorRGB

Direct3DRMMesh.GetGroupCount

Direct3DRMMesh

지정된Direct3DRMMesh오브젝트중의 그룹의 수를 취득한다.

구문

object. GetGroupCount( ) As Long

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.

반환값

성공하면 그룹의 수를 돌려준다. 실패하면 0을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMesh.GetGroupData

Direct3DRMMesh

지정된 그룹에 관련지을 수 있었던 면데이터를 취득한다.

구문

object. GetGroupData(id As Long,
  psa() As Long)

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.
psa
면데이터를 받는 배열. 이 데이터는, 그 면의 버텍스의 수를 나타내는 정수값이 전으로 지정된 그룹의 버텍스 배열에의 인덱스 리스트이다. 예를 들어, 그룹을 구성하는 면이 삼각형과 사각형인 경우, 데이터는 다음과 같이 된다. [ 3, 인덱스, 인덱스, 인덱스, 4, 인덱스, 인덱스, 인덱스, 인덱스, 3, 인덱스, 인덱스, 인덱스, ...]

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMesh.GetGroupDataSize

Direct3DRMMesh

특정의 그룹에 관련지을 수 있었던 데이터 배열중의 요소수를 취득한다.

구문

object. GetGroupDataSize(id As Long) As Long

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.

반환값

요소수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMesh.GetGroupMapping

Direct3DRMMesh

Direct3DRMMesh오브젝트중의 그룹에 대해서, 어떻게 텍스쳐가 맵 되는지를 취득한다.

구문

object. GetGroupMapping(id As Long) As CONST_D3DRMMAPPINGFLAGS

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.

반환값

그룹에의 텍스쳐의 맵 방법을 나타내는CONST_D3DRMMAPPINGFLAGS 열거형으로부터 다음의 값 가운데 하나를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMesh.SetGroupMapping

Direct3DRMMesh.GetGroupMaterial

Direct3DRMMesh

Direct3DRMMesh오브젝트중의 그룹에 관련지을 수 있었던 머트리얼을 취득한다.

구문

object. GetGroupMaterial(id As Long) As Direct3DRMMaterial2

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.

반환값

Direct3DRMMaterial2 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMesh.SetGroupMaterial

Direct3DRMMesh.GetGroupQuality

Direct3DRMMesh

Direct3DRMMesh오브젝트중의 지정된 그룹의 렌더링 퀄리티를 취득한다.

구문

object. GetGroupQuality(id As Long) As CONST_D3DRMRENDERQUALITY

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.

반환값

성공하면, 렌더링 퀄리티를 나타내는CONST_D3DRMRENDERQUALITY 열거형의 값을 돌려준다. 실패하면 0을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

렌더링 퀄리티란, 디바이스의 렌더링 표면상에서 실행되는 렌더링의 퀄리티의 최대치이다.

오브젝트의 퀄리티에는, 3개의 컴퍼넌트가 있다. 즉, 쉐이딩 모드 (플랫 또는 굿 로), 조명 타입 (온 또는 오프) 및 전부 칠해 모드 (포인트, 와이어 프레임 또는 솔리드)이다.

참조

Direct3DRMMesh.SetGroupQuality

Direct3DRMMesh.GetGroupTexture

Direct3DRMMesh

Direct3DRMMesh오브젝트중의 그룹에 관련지을 수 있었던 텍스쳐를 취득한다.

구문

object. GetGroupTexture(id As Long) As Direct3DRMTexture3

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.

반환값

Direct3DRMTexture3 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMesh.SetGroupTexture

Direct3DRMMesh.GetSizes

Direct3DRMMesh

Direct3DRMMesh오브젝트중의 지정의 그룹에 대한 정보를 취득한다.

구문

object. GetSizes(id As Long, cnt1 As Long,
  cnt2 As Long,
  cnt3 As Long,
  cnt4 As Long)

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.
cnt1
그룹중의 버텍스의 수를 받는다.
cnt2
그룹중의 면의 수를 받는다.
cnt3
모든 면이 같은 버텍스 카운트를 가지는 경우는, 그룹중의 각면의 버텍스의 수를 받는다. 그룹에 다른 버텍스 카운트를 가지는 면이 있는 경우, 이 파라미터는 0을 받는다.
cnt4
GetGroupData에 의해 요구된psa의 필수 사이즈를 받는다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMesh.SetVertices

Direct3DRMMesh.GetVertex

Direct3DRMMesh

특정의 그룹으로부터 1개의 버텍스를 취득한다.

구문

object. GetVertex(id As Long,
  idx As Long,
  ret As D3DRMVERTEX)

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 를 사용해 생성된 것이 아니면 안 된다.
idx
버텍스 위치를 취득하는 시점을 나타내는D3DRMVERTEX 형의 배열의 인덱스.
ret
메소드가 돌아왔을 때, 버텍스 정보(버텍스 위치, 색, 텍스쳐 좌표등)를 저장 하는D3DRMVERTEX형.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMesh.SetVertices

Direct3DRMMesh.GetVertexCount

Direct3DRMMesh

지정된Direct3DRMMesh오브젝트의 버텍스의 수를 취득한다.

구문

object. GetVertexCount(id As Long) As Long

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 를 사용해 생성된 것이 아니면 안 된다.

반환값

성공하면 버텍스의 수를 돌려준다. 실패하면 0을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMesh.SetVertices

Direct3DRMMesh.GetVertices

Direct3DRMMesh

Direct3DRMMesh오브젝트중의 지정의 그룹에 대한 버텍스 정보를 취득한다.

구문

object. GetVertices(id As Long,
  idx As Long,
  cnt As Long,
  vertexArray() As D3DRMVERTEX)

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.
idx
버텍스 위치를 취득하는 시점을 나타내는D3DRMVERTEX 형의 배열의 인덱스.
cnt
idx파라미터로 주어지고 있는 인덱스 이후의, 취득하는D3DRMVERTEX형 (버텍스)의 수. 이 파라미터는 NOTHING로 할 수 없다. 그룹중의 버텍스의 수를 취득하려면 ,Direct3DRMMesh.GetVertexCount 메소드를 호출한다.
vertexArray
메소드가 돌아왔을 때, 버텍스 정보(버텍스 위치, 색, 텍스쳐 좌표등)를 저장 하는D3DRMVERTEX형의 배열.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMesh.SetVertices

Direct3DRMMesh.Scale

Direct3DRMMesh

모델 좌표의 x축, y축, z축으로 대해, 주어진 스케일 계수에 의해Direct3DRMMesh오브젝트를 스케일링 한다.

구문

object. Scale(sx As Single,
  sy As Single,
  sz As Single)

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
sx, sy, sz
x축, y축, z축으로 따라 적용되는 스케일 계수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMesh.SetGroupColor

Direct3DRMMesh

Direct3DRMMesh오브젝트중의 그룹의 색을 설정한다.

구문

object. SetGroupColor(id As Long,
  val As Long)

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 를 사용해 생성된 것이 아니면 안 된다.
val
그룹의 색.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMMeshInterpolator 오브젝트에 그룹 컬러 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMMesh.GetGroupColor ,Direct3DRMMesh.SetGroupColorRGB

Direct3DRMMesh.SetGroupColorRGB

Direct3DRMMesh

RGB값을 사용해,Direct3DRMMesh오브젝트중의 그룹의 색을 설정한다.

구문

object. SetGroupColorRGB(id As Long,
  r As Single,
  g As Single,
  b As Single)

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.
r, g, b
그룹의 색의 적, 초록, 파랑의 각 요소.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMMeshInterpolator 오브젝트에 그룹 RGB 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMMesh.GetGroupColor ,Direct3DRMMesh.SetGroupColor

Direct3DRMMesh.SetGroupMapping

Direct3DRMMesh

Direct3DRMMesh오브젝트중의 그룹에 맵핑을 설정한다. 맵핑은, 어떻게 텍스쳐가 면에 맵 될까를 결정한다.

구문

object. SetGroupMapping(id As Long,
  value As CONST_D3DRMMAPPINGFLAGS)

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.
value
그룹의 맵핑을 지정하는CONST_D3DRMMAPPINGFLAGS 열거형으로부터의 값.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMesh.GetGroupMapping

Direct3DRMMesh.SetGroupMaterial

Direct3DRMMesh

Direct3DRMMesh오브젝트중의 그룹에 머트리얼을 관련짓는다.

구문

object. SetGroupMaterial(id As Long,
  val As Direct3DRMMaterial2)

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.
val
Direct3DRMMesh오브젝트의Direct3DRMMaterial2 인터페이스.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMesh.GetGroupMaterial

Direct3DRMMesh.SetGroupQuality

Direct3DRMMesh

Direct3DRMMesh오브젝트중의 지정된 그룹의 렌더링 퀄리티를 설정한다.

구문

object. SetGroupQuality(id As Long,
  value As CONST_D3DRMRENDERQUALITY)

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.
value
렌더링 퀄리티를 나타내는CONST_D3DRMRENDERQUALITY 열거형의 값. 이러한 값에는, 오브젝트의 쉐이딩 모드나 조명 모드, 전부 칠해 모드가 포함되어 있다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

렌더링 퀄리티는, 디바이스의 렌더링 얼굴로 실행되는 렌더링의 퀄리티의 최대치이다.

오브젝트 퀄리티에는, 3개의 컴퍼넌트가 있다. 즉, 쉐이딩 모드 (플랫 또는 굿 로로, 폰은 이행되어 있지 않다. 디폴트는 gouraud shading), 조명 타입 (온 또는 오프) 및 전부 칠해 모드 (포인트, 와이어 프레임 또는 솔리드)이다.

참조

Direct3DRMMesh.GetGroupQuality

Direct3DRMMesh.SetGroupTexture

Direct3DRMMesh

Direct3DRMMesh오브젝트중의 그룹에 텍스쳐를 관련짓는다.

구문

object. SetGroupTexture(id As Long,
  val As Direct3DRMTexture3)

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.
val
Direct3DRMMesh오브젝트에 관련짓는Direct3DRMTexture3 인터페이스.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMesh.GetGroupTexture

Direct3DRMMesh.SetVertex

Direct3DRMMesh

Direct3DRMMesh오브젝트중의 기존 그룹의 지오메트리를 수정한다.

구문

object. SetVertex(id As Long,
  idx As Long,
  values As D3DRMVERTEX)

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.
idx
수정하는 메쉬 그룹의 최초의 버텍스의 인덱스.
values
세트 하는 버텍스 위치를 지정하는D3DRMVERTEX 형.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

버텍스 정보는 그룹 마다 가진다. 2개(살)이 다른 그룹간에 버텍스를 공유할 필요가 있는 경우(예를 들어, 메쉬 위에의 인접한 면의 색이 다를 때), 양쪽 모두의 그룹에서 버텍스를 카피하지 않으면 안 된다.

이 메소드는,Direct3DRMMeshInterpolator 오브젝트에 버텍스 위치 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMMesh.GetVertices

Direct3DRMMesh.SetVertices

Direct3DRMMesh

Direct3DRMMesh오브젝트중의 지정된 그룹에 버텍스 위치를 설정한다.

구문

object. SetVertices(id As Long,
  idx As Long,
  count As Long,
  vertexArray() As D3DRMVERTEX)

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.
idx
수정하는 메쉬 그룹의 최초의 버텍스의 인덱스.
count
세트 하는 연속 버텍스의 수. vertexArray배열은, 적어도count수의 요소를 저장 해야 한다.
vertexArray
설정하는 버텍스 위치를 나타내는D3DRMVERTEX 형의 배열.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

버텍스 정보는 그룹 마다 가진다. 2개(살)이 다른 그룹간에 버텍스를 공유할 필요가 있는 경우(예를 들어, 메쉬 위에의 인접한 면의 색이 다를 때), 양쪽 모두의 그룹에서 버텍스를 카피하지 않으면 안 된다.

이 메소드는,Direct3DRMMeshInterpolator 오브젝트에 버텍스 위치 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMMesh.GetVertices

Direct3DRMMesh.Translate

Direct3DRMMesh

Direct3DRMMesh오브젝트중의 버텍스의 위치에, 지정된 오프셋(offset)를 추가한다.

구문

object. Translate(tx As Single,
  ty As Single,
  tz As Single)

요소

object
Direct3DRMMesh오브젝트를 나타내는오브젝트식.
tx, ty, tz
각 버텍스 위치의 x좌표, y좌표, z좌표에 추가되는 오프셋(offset).

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.


Direct3DRMMeshBuilder3

어플리케이션은,IDirect3DRMMeshBuilder3인터페이스의 메소드를 사용해 메쉬 오브젝트라고 대화한다. 메쉬의 상세한 것에 대하여는, 「Direct3DRMMesh 」를 참조할것.

Direct3DRMMeshBuilder3.AddVertex ,AddFace 및AddFaces 메소드를 사용해, 메쉬에 대해서 개별적으로 버텍스와 면을 추가할 수가 있다.

법선 (단위벡터가 아니면 안된다)을 세트 하는지, 또는GenerateNormals 메소드를 사용해, 둘러싸고 있는 면의 면법선을 평균화해 법선을 계산할 수가 있다.

Direct3DRMMeshBuilder3메소드는, 1개이상의 법선, 법선의 수, 면, 1개이상의 버텍스, 및 메쉬 빌더 상태 (유효 또는 무효)를 취득한다. 이 인터페이스에 의해, 버텍스와 법선세트, 메쉬 빌더의 새로운 서브 메쉬와 친메쉬의 생성과 취득을 실시할 수가 있다. 또,Direct3DRMMeshBuilder3에서는, 어플리케이션이 새로운 삼각형 (일반적인 다각형과 대립적인 의미로)을Direct3DRMMeshBuilder3오브젝트에 추가해,AddTriangles 메소드를 사용해, 처리중에 암묵에 새로운 면을 생성 할 수 있다.

보관 유지 모드 6. x에서는,Direct3DRM3 인터페이스를 사용해Direct3DRMMeshBuilder3 오브젝트를 생성 할 수가 있다. 이 경우,Direct3DRMMeshBuilder3오브젝트는, 그 이행을 위해서(때문에) 직접 모드의DrawPrimitive인터페이스를 사용한다.

Direct3DRMMeshBuilder3인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

색 | GetColorSource
SetColor
SetColorRGB
SetColorSource
생성 | GetBox
면 | AddFace
AddFaces
AddFacesIndexed
CreateFace
DeleteFace
GetFaceCount
GetFaceDataSize
GetFace
GetFaces
로드 | LoadFromFile
메쉬 | AddMesh
CreateMesh
그 외 | AddFrame
AddMeshBuilder
AddTriangles
Empty
Enable
GetEnable
Optimize
Save
ScaleMesh
SetMaterial
Translate
법선 | AddNormal
GenerateNormals
GetNormals
GetNormalCount
SetNormal
퍼스펙티브 | GetPerspective
SetPerspective
렌더링 퀄리티 | GetQuality
SetQuality
서브 메쉬 | CreateSubMesh
DeleteSubMesh
GetParentMesh
GetSubMeshCount
GetSubMeshes
텍스쳐 | GetTextureCoordinates
SetTexture
SetTextureCoordinates
SetTextureTopology
버텍스 | AddVertex
GetGeometry
GetVertex
GetVertexColor
GetVertexCount
SetVertex
SetVertexColor
SetVertexColorRGB

Direct3DRMMeshBuilder3인터페이스는,Direct3DRMObject 인터페이스로부터 이하의 메소드를 계승한다.

  • AddDestroyCallback
  • CloneObject
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMMeshBuilder3오브젝트는,Direct3DRM3.CreateMeshBuilder 메소드의 호출에 의해 취득된다.

Direct3DRMMeshBuilder3.AddFace

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트에 1개의 면을 추가한다.

구문

object. AddFace(f As Direct3DRMFace2)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
f
추가하는Direct3DRMFace2 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

어느 1개의 면도, 한 번에 1개의 메쉬 밖에 존재할 수 없다.

Direct3DRMMeshBuilder3.AddFaces

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트에 복수의 면을 추가한다.

구문

object. AddFaces(vc As Long,
  vertexArray() As D3DVECTOR,
  nc As Long,
  normalArray() As D3DVECTOR,
  data() As Long) As Direct3DRMFaceArray

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
vc
버텍스의 수.
vertexArray
버텍스 위치를 저장 하는D3DVECTOR 형의 배열.
nc
법선의 수.
normalArray
법선의 위치를 저장 하는D3DVECTOR형의 배열.
data
각면에 대해서, 이 파라미터는, 버텍스 카운트와 거기에 계속되어 버텍스 배열의 인덱스를 포함할 필요가 있다. nc가 0이 아니면, 이 파라미터는, 버텍스 카운트와 거기에 계속되어 인덱스의 대를 포함할 필요가 있다. 그 인덱스의 대의 최초의 인덱스는, 버텍스 배열에 대한 인덱스이며, 2번째의 인덱스는, 법선의 배열에 대한 인덱스이다. 인덱스의 리스트는, 0으로 종료해야 한다.

반환값

새롭고 생성 된 면에의 포인터가 세트 되는Direct3DRMFaceArray 인터페이스를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.AddFacesIndexed

Direct3DRMMeshBuilder3

기존의 버텍스와 법선 (옵션)을 사용하는 메쉬 빌더상에, 다수의 면을 생성 할 수 있도록(듯이) 한다.

구문

object. AddFacesIndexed(flags As CONST_D3DRMADDFACESFLAGS,
  indexArray() As Long) As Long

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
flags
법선 인덱스의 처리 방법을 지정하는CONST_D3DRMADDFACESFLAGS 열거형의 값. 값이D3DRMADDFACES_DEFAULT라면, 기존의 법선 인덱스는indexArray파라미터중으로 지정되어 있지 않으면 안 된다. 그렇지 않은 경우, 대응하는 인덱스를 가지는 법선이 각 버텍스에 대해서 자동적으로 사용된다.
indexArray
각면에 대해서 다음의 것을 지정하는, 부호 없음 정수의 tuple가 연속하는 배열.
  • 버텍스의 수 n, 여기서 n는 3이상
  • 버텍스 인덱스
  • 법선 인덱스 (옵션)

다음의 테이블은,flags파라미터의 값과indexArray파라미터의 필수면tuple 형식과의 관계를 나타낸다.

flags | 필수면tuple 형식
D3DRMADDFACES_DEFAULT | {<n>, <vIndex0>, <nIndex0>,...,<vIndex n-1>, <nIndex n-1>}
D3DRMADDFACES_VERTICESONLY | {<n>, <vIndex0>,...,<vIndex n-1>}

vIndex와 nIndex의 값은, 메쉬 빌더내에 이미 존재하고 있는 버텍스와 법선에 인덱스 붙이고 하는데 필요하다. tuple의 배열은 값 0으로 종료할 필요가 있다.

반환값

메쉬 빌더에 추가되는 최초의 새로운 면의 인덱스를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.AddFrame

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트에 프레임의 내용을 추가한다.

구문

object. AddFrame(f As Direct3DRMFrame3)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
f
그 내용이 추가되는Direct3DRMFrame3 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는, 지정된 프레임 계층 (보다 큰 프레임 계층의 서브 분기도 가능)으로부터Direct3DRMMeshBuilder3 오브젝트에, 모든 메쉬와 메쉬 빌더의 면의 카피를 추가한다. 프레임 트리는,루트 프레임을 건네주는 것으로 지정한다. 면은, 그것들이 내포 하는 요소 프레임의 위치와 방향에 의해 추가된다. 루트 프레임에 부모가 있어도, 지정된 루트 프레임의 변환은 무시된다.

소스 프레임은, 이 조작에 의해 변경 또는 참조도 되지 않는다.

Direct3DRMMeshBuilder3.AddMesh

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트에 메쉬를 추가한다.

구문

object. AddMesh(m As Direct3DRMMesh)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
m
추가되는Direct3DRMMesh 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.AddMeshBuilder

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 내용을 다른Direct3DRMMeshBuilder3오브젝트에 추가한다. 내포 하는Direct3DRMMeshBuilder3소스 오브젝트와 면의 아래에서 있는 모든 서브 메쉬 빌더는,Direct3DRMMeshBuilder3타겟 오브젝트의 아래에서 중복 한다.

구문

object. AddMeshBuilder(meshbuilder As Direct3DRMMeshBuilder3,
  flags As CONST_D3DRMADDMESHBUILDERFLAGS)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
meshbuilder
그 내용을 추가하는Direct3DRMMeshBuilder3오브젝트.
flags
카피 옵션을 나타내는CONST_D3DRMADDMESHBUILDERFLAGS 열거형의 하나 이상의 값.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

소스의Direct3DRMMeshBuilder3오브젝트는, 이 조작으로 변경 또는 참조도 되지 않는다.

Direct3DRMMeshBuilder3.AddNormal

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트에 법선을 추가한다.

구문

object. AddNormal(x As Single,
  y As Single,
  z As Single) As Long

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
x, y, z
새로운 법선의 방향의 x, y, z의 각 요소.

반환값

법선의 인덱스를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.AddTriangles

Direct3DRMMeshBuilder3

어플리케이션이 (일반적인 다각형과 대립적인 의미로) 새로운 삼각형을Direct3DRMMeshBuilder3오브젝트에 추가해, 처리중에 암묵에 새로운 면을 생성 할 수 있도록(듯이) 한다.

구문

object. AddTriangles(flags As Long,
  format As CONST_D3DRMADDTRIANGLESVT,
  vertexCount As Long,
  data As Any)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
flags
0이 아니면 안된다.
format
버텍스 데이터의 포맷을 기술하는CONST_D3DRMADDTRIANGLESVT 열거형의 값의 논리적인 편성. 모든 유효한 값이 포함되어 있는 경우, 버텍스 데이터는 다음의D3DRMFLEXVERTEX유저 정의형에 의해 기술할 수 있다.

구문

Type D3DRMFLEXVERTEX
  IType As Long
  color As Long
  normal As D3DVECTOR
  position As D3DVECTOR
  tu As Single
  tv As Single
End Type

Dim verts(100) As D3DRMFLEXVERTEX

AddTriangles(D3DRMFVF_TYPE Or D3DRMFVF_NORMAL Or D3DRMFVF_COLOR Or D3DRMFVF_TEXTURECOORDS, 100, verts(0))

유효한 값으로서는, 다음의 값의 임의의 논리적 편성이 가능하고, 이것들은D3DRMFLEXVERTEX형의 어느 멤버를 각 요소의 기술에 포함하는지를 나타낸다. position멤버는 항상 존재한다.

D3DRMFVF_TYPE
IType멤버를 포함한다. IType멤버가 존재하는 경우, 그 중에는 다음의 어떤 것이나 1개가 없으면 안 된다.
D3DRMVERTEX_LIST
새로운 리스트를 시작 하든가, 혹은 이전에 시작 한 리스트의 멤버이다. 이전의 버텍스 (또는 그 전의 버텍스)에 이 플래그의 마크가 뒤따르지 않은 경우, 최저 1개의 삼각형이 형성될 때까지, 다음의 버텍스에 이 플래그의 마크가 뒤따르지 않으면 안 된다.
D3DRMVERTEX_STRIP
이전의 2개의 버텍스를 가지는 새로운 삼각형을 작은 조각 포맷으로 형성한다.
D3DRMVERTEX_FAN
이전의 버텍스와 부채의 최초의 버텍스를 가지는 새로운 삼각형을 형성한다.
D3DRMFVF_NORMAL
normal멤버를 포함한다.
D3DRMFVF_COLOR
color멤버를 포함한다.
D3DRMFVF_TEXTURECOORDS
tu와tv멤버를 포함한다.
vertexCount
버텍스의 수.
data
format로 기술되는 데이터.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는, 삼각형을 기술하는 어플리케이션에 유연성을 제공한다. 삼각형은 버텍스세트로 기술된다. 각 버텍스는 위치를 가지지만, 옵션으로 법선, 텍스쳐 좌표, 또는 색을 가지는 일도, 가지지 않는 것도 할 수 있다.

다음의 예는, 그림중의 각 버텍스에 대해서 적절한IType플래그를 나타낸다.

버텍스수 | IType플래그
0 | D3DRMVERTEX_STRIP
1 | D3DRMVERTEX_STRIP
2 | D3DRMVERTEX_STRIP
3 | D3DRMVERTEX_STRIP
4 | D3DRMVERTEX_STRIP
5 | D3DRMVERTEX_FAN
6 | D3DRMVERTEX_FAN
7 | D3DRMVERTEX_FAN
8 | D3DRMVERTEX_LIST
9 | D3DRMVERTEX_LIST
10 | D3DRMVERTEX_LIST
11 | D3DRMVERTEX_LIST
12 | D3DRMVERTEX_LIST
13 | D3DRMVERTEX_LIST

Direct3DRMMeshBuilder3.AddVertex

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트에 버텍스를 추가한다.

구문

object. AddVertex(x As Single,
  y As Single,
  z As Single) As Long

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
x, y, z
새로운 버텍스의 위치의 x, y, z의 각 요소.

반환값

버텍스의 인덱스를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.CreateFace

Direct3DRMMeshBuilder3

버텍스가 없는 새로운 면을 생성 해,Direct3DRMMeshBuilder3오브젝트에 추가한다.

구문

object. CreateFace( ) As Direct3DRMFace2

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.

반환값

새롭고 생성 된 면을 받는Direct3DRMFace2 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.CreateMesh

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트로부터 새로운 메쉬를 생성 한다.

구문

object. CreateMesh( ) As Direct3DRMMesh

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMMesh 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.CreateSubMesh

Direct3DRMMeshBuilder3

현재의Direct3DRMMeshBuilder3오브젝트에 대해서, 새로운 서브 메쉬를 생성 한다.

구문

object. CreateSubMesh( ) As Direct3DRMMeshBuilder3

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMMeshBuilder3 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

서브 메쉬는,Direct3DRMMeshBuilder3인터페이스를 지원 해, 그 자체도 서브 메쉬를 가질 수 있다고 하는 점으로써, 메쉬 빌더 오브젝트에 유사하고 있다. 서브 메쉬와 메쉬 빌더의 상위는, 모든 서브 메쉬가 버텍스와 법선을, 서브 메쉬의 연쇄중의 오모토의 조상과 공유하는 것이다. 메쉬 빌더는 버텍스와 법선을 공유하지 않는다.

참조

Direct3DRMMeshBuilder3.DeleteSubMesh ,Direct3DRMMeshBuilder3.GetSubMesh ,Direct3DRMMeshBuilder3.GetParentMesh

Direct3DRMMeshBuilder3.DeleteFace

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 면을 삭제한다.

구문

object. DeleteFace(face As Direct3DRMFace2)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
face
Direct3DRMMeshBuilder3오브젝트로부터 삭제하는Direct3DRMFace2 오브젝트의 인터페이스.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.DeleteSubMesh

Direct3DRMMeshBuilder3

서브 메쉬를 삭제한다. 서브 메쉬는, 현재의Direct3DRMMeshBuilder3오브젝트의 바로 아래의 아이가 아니면 안된다.

구문

object. DeleteSubMesh(mesh As Direct3DRMMeshBuilder3)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
mesh
삭제하는 서브 메쉬의Direct3DRMMeshBuilder3 인터페이스.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMeshBuilder3.CreateSubMesh ,Direct3DRMMeshBuilder3.GetSubMesh ,Direct3DRMMeshBuilder3.GetParentMesh

Direct3DRMMeshBuilder3.Empty

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트로부터, 모든 면, 버텍스, 법선을 삭제한다.

구문

object. Empty( )

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.Enable

Direct3DRMMeshBuilder3

이Direct3DRMMeshBuilder3오브젝트를, 렌더링과 피킹용으로 유효하게 할까 무효로 하는지를 지정한다.

구문

object. Enable(flags As CONST_D3DRMADDMESHBUILDERFLAGS)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
flags
렌더링과 피킹을 유효하게 할지 어떨지를 지정하는CONST_D3DRMMESHBUILDERENABLEFLAGS 열거형의 하나 이상의 값.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMeshBuilder3.GetEnable

Direct3DRMMeshBuilder3.GenerateNormals

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트를 처리해, 버텍스를 공유하는 각면에 대한 면법선을 평균화하는 것에 의해, 메쉬중의 각 버텍스에 대해서 법선을 생성한다. 새로운 법선은, 버텍스를 공유하는 면이, 면끼리의 각도가 접힌 곳의 각도보다 큰 경우에 생성된다.

구문

object. GenerateNormals(angle As Single,
  flags As CONST_D3DRMGENERATENORMALSFLAGS)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
angle
라디안 단위의, 새로운 법선을 생성할 수 있는 면끼리의 최소 가능 각도.
flags
CONST_D3DRMGENERATENORMALSFLAGS 열거형의 하나 이상의 값.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

D3DRMGENERATENORMALS_PRECOMPACT플래그를 지정 하면, 프리콘파크트파스는, 메쉬중의 모든 버텍스를 검색해, 같은 버텍스를 모두 머지 한다. 이것은, 로드 되고 있는 메쉬를 컴팩트하게 하는데 현명한 방법이다. 메쉬안에는, 버텍스에 복수의 법선을 가지는 경우에, 복수의 버텍스를 가지는 것이 있다. 이것은, Direct3D 보관 유지 모드에서는 필요하지 않는다. 이 플래그의 지정은, 복수의 버텍스를 제거하는 경우의 정평적 방법이다.

컴팩트 처리의 뒤, 법선이 생성된다. 면끼리의 사이의 옆이 조사할 수 있어 면이 옆으로 하는 각도가, 접은 자국각보다 작은 경우에는, 면법선은 평균화되어 버텍스 법선이 생성된다. 각도가 접은 자국각보다 큰 경우에는, 새로운 법선이 생성된다. 새로운 버텍스는, 생성되지 않는 것에 주의한다.

Direct3DRMMeshBuilder3.GetBox

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트를 포함한 경계 박스를 취득한다. 경계 박스는, 각 차원에서의 최소, 최대의모델 좌표를 준다.

구문

object. GetBox(retV As D3DRMBOX)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
retV
경계 박스의 좌표가 세트 되는D3DRMBOX 형.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.GetColorSource

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 색소스를 취득한다. 색소스는, 면에서도 버텍스에서도 좋다.

구문

object. GetColorSource( ) As CONST_D3DRMCOLORSOURCE

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.

반환값

CONST_D3DRMCOLORSOURCE 열거형의 멤버를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMeshBuilder3.SetColorSource

Direct3DRMMeshBuilder3.GetEnable

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트를 유효하게 할까 무효로 하는지를 나타내는 값을 취득한다.

구문

object. GetEnable( ) As CONST_D3DRMADDMESHBUILDERFLAGS

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.

반환값

이Direct3DRMMeshBuilder3오브젝트의 현재의 유효 상태를 나타내는CONST_D3DRMMESHBUILDERENABLEFLAGS 열거형으로부터 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMeshBuilder3.Enable

Direct3DRMMeshBuilder3.GetFace

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 단일면을 취득한다.

구문

object. GetFace(id As Long) As Direct3DRMFace2

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
id
취득하는 메쉬면의 인덱스. 이 면은Direct3DRMMeshBuilder3오브젝트의 일부로 되어 있지 않으면 안 된다.

반환값

면을 받는Direct3DRMFace2 인터페이스를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.GetFaceCount

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 면의 수를 취득한다.

구문

object. GetFaceCount( ) As Long

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.

반환값

면의 수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.GetFaceDataSize

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 면데이터 배열의 사이즈를 취득한다.

구문

object. GetFaceDataSize( ) As Long

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.

반환값

GetGeometry에 필요한sizeData인수의 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMMeshBuilder3.GetGeometry 에 필요한faceData배열의 사이즈를 취득한다.

Direct3DRMMeshBuilder3.GetFaces

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 면을 취득한다.

구문

object. GetFaces( ) As Direct3DRMFaceArray

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.

반환값

면을 받는Direct3DRMFaceArray 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.GetGeometry

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 버텍스, 법선, 면데이터를 취득한다.

구문

object. GetGeometry(vertexCount As Long,
  vertexArray() As D3DVECTOR,
  normalCount As Long,
  normalArray() As D3DVECTOR,
  sizeData As Long,
  faceData() As Long)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
vertexCount
vertexArray중의 버텍스의 수.
vertexArray
D3DVECTOR 형의 배열. 이것은Direct3DRMMeshBuilder3 오브젝트의 버텍스를 포함한다. GetVertexCount를 사용해, 이 배열의 최소 사이즈를 결정한다.
normalCount
normalArray중의 법선의 수.
normalArray
D3DVECTOR형의 배열. 이것은Direct3DRMMeshBuilder3오브젝트의 법선을 포함한다. GetNormalCount을 사용해, 이 배열의 사이즈를 결정한다.
sizeData
faceData중의 요소수를 지정하는 값.
faceData
Direct3DRMMeshBuilder3오브젝트의 면데이터. 이 데이터는, NULL로 끝나는 점을 제외해,Direct3DRMMeshBuilder3.AddFaces 메소드로 지정된 포맷과 같다. GetFaceDataSize를 호출해 배열의 사이즈를 결정한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.GetNormal

Direct3DRMMeshBuilder3

법선 벡터를 취득한다.

구문

object. GetNormal(index As Long,
  desc As D3DVECTOR)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
index
돌려주는 법선의 인덱스.
desc
법선의 x, y, z좌표가 세트 되는D3DVECTOR 형.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.GetNormalCount

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트중의 법선의 수를 취득한다.

구문

object. GetNormalCount( ) As Long

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMMeshBuilder3오브젝트중의 법선의 수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMeshBuilder3.GetNormal ,Direct3DRMMeshBuilder3.SetNormal

Direct3DRMMeshBuilder3.GetParentMesh

Direct3DRMMeshBuilder3

이Direct3DRMMeshBuilder3오브젝트의 친메쉬를 취득한다.

구문

object. GetParentMesh(
    flags As CONST_D3DRMPARENTINGFLAGS)
    As Direct3DRMMeshBuilder3

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
flags
어느Direct3DRMMeshBuilder3오브젝트를 취득하는지를 정의하는CONST_D3DRMPARENTINGFLAGS 열거형의 하나 이상의 값.

반환값

Direct3DRMMeshBuilder3 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMeshBuilder3.GetSubMesh

Direct3DRMMeshBuilder3.GetPerspective

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트에 대해서, 퍼스펙티브 보정이 온일지 어떨지를 판별한다.

구문

object. GetPerspective( ) As Long

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.

반환값

퍼스펙티브 보정이 온의 경우는–1, 온이 아닌 경우는 0을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.GetQuality

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 렌더링 퀄리티를 취득한다.

구문

object. GetQuality( ) As CONST_D3DRMRENDERQUALITY

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.

반환값

메쉬의 렌더링 퀄리티를 지정하는CONST_D3DRMRENDERQUALITY 열거형으로부터 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

렌더링 퀄리티는, 디바이스의 렌더링 얼굴로 실행되는 렌더링의 퀄리티의 최대치이다.

오브젝트 퀄리티에는, 3개의 컴퍼넌트가 있다. 즉, 쉐이딩 모드 (플랫 또는 굿 로로, 폰은 이행되어 있지 않다. 디폴트는 gouraud shading), 조명 타입 (온 또는 오프) 및 전부 칠해 모드 (포인트, 와이어 프레임 또는 솔리드)이다.

참조

Direct3DRMMeshBuilder3.SetQuality

Direct3DRMMeshBuilder3.GetSubMeshCount

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트에 포함되는 서브 메쉬의 수를 취득한다.

구문

object. GetSubMeshCount( ) As Long

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.

반환값

서브 메쉬의 수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMeshBuilder3.GetParentMesh

Direct3DRMMeshBuilder3.GetSubMeshes

Direct3DRMMeshBuilder3

이Direct3DRMMeshBuilder3오브젝트에 포함되는 서브 메쉬의 리스트를 취득한다.

구문

object. GetSubMeshes(count As Long,
  arrayOfMeshBuilders() As Direct3DRMMeshBuilder3)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
count
돌려주어질 예정의 서브 메쉬의 수. count가 포인트 하는 값은, 실제로 취득된 서브 메쉬의 수를 받는다.
arrayOfMeshBuilders
아이 서브 메쉬를 포함한Direct3DRMMeshBuilder3 오브젝트의 배열.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMeshBuilder3.GetParentMesh

Direct3DRMMeshBuilder3.GetTextureCoordinates

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 지정되고 있는 버텍스의 텍스쳐 좌표를 취득한다.

구문

object. GetTextureCoordinates(idx As Long,
  u As Single,
  v As Single)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
idx
버텍스의 인덱스.
u, v
돌려주어진 버텍스의 텍스쳐 좌표.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMeshBuilder3.SetTextureCoordinates

Direct3DRMMeshBuilder3.GetVertex

Direct3DRMMeshBuilder3

버텍스 벡터를 취득한다.

구문

object. GetVertex(id As Long,
  vec As D3DVECTOR)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
id
돌려주는 버텍스의 ID.
vec
버텍스의 x, y, z좌표가 세트 되는D3DVECTOR 형.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.GetVertexColor

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 지정되고 있는 버텍스의 색을 취득한다.

구문

object. GetVertexColor(index As Long) As Long

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
index
버텍스의 인덱스.

반환값

색을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMeshBuilder3.SetVertexColor

Direct3DRMMeshBuilder3.GetVertexCount

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트중의 버텍스의 수를 취득한다.

구문

object. GetVertexCount( ) As Long

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.

반환값

버텍스의 수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.LoadFromFile

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트를 로드한다.

구문

object. LoadFromFile(filename As String,
  id As String,
  options As CONST_D3DRMLOADFLAGS,
  loadTextureImplementation As Direct3DRMLoadTextureCallback3,
  userArgument As Object)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
filename
로드하는 오브젝트의 소스. 소스는,flags파라미터로 지정된 소스 플래그에 따라, 파일, 리소스, 메모리 블록, 또는 스트림으로 할 수 있다.
id
로드하는 오브젝트의 이름 또는 위치. id가""의 경우는,options파라미터를D3DRMLOAD_FIRST로 설정해야 한다. Microsoft Visual Basic® 는,String데이터형이 지정되고 있는 경우에서도, 로드하는 아이템의 위치를 나타내는id파라미터안의Integer를 받아들인다. 예를 들어,id파라미터에1이 설정되어 있으면(자), 1번째의 위치의 오브젝트가 로드 된다.
options
로드 옵션을 기술하는CONST_D3DRMLOADFLAGS 열거형의 하나 이상의 값.
loadTextureImplementation
Direct3DRMLoadTextureCallback3 콜백 인터페이스. 특수한 formatting를 필요로 하는 오브젝트에 의해 사용되는, 임의의 텍스쳐를 로드하기 위해서(때문에) 사용된다. 텍스쳐는, 2로 갈라지는 폭과 길이가 아니면 안된다. 이 파라미터는 NOTHING로 할 수 있다.
userArgument
콜백에게 건네지는 어플리케이션 정의 데이터.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

디폴트에서는, 이 메소드는filename파라미터로 지정되고 있는 소스로부터 최초의 메쉬를 로드한다.

이 메소드는,Direct3DRM3.SetOptions 가 세트 하는 오른손과 왼손 지오메트리 옵션을 고려한다.

그 로드 메소드를 여러 차례를 호출하는 것으로, 복수의 오브젝트를Direct3DRMMeshBuilder3오브젝트에 로드할 수가 있다.

각LoadFromFile메소드는,filename파라미터를 사용해 오브젝트의 소스를 지정해,id파라미터에 의해 오브젝트를 식별한다. 시스템은 소스 플래그의 선택에 근거해filename파라미터를 해석한다. 그리고, 식별자 플래그의 선택에 근거해id파라미터의 내용을 해석한다.

인스턴스 플래그는, 파라미터의 해석 방법에는 아무것도 변경을 더하지 않는다. D3DRMLOAD_INSTANCEBYREFERENCE플래그를 이용하면(자), 새로운 오브젝트를 생성 하는 일 없이 같은 파일을 2회 로드할 수가 있다. 오브젝트가 이름을 가지고 있지 않은 경우,D3DRMLOAD_INSTANCEBYREFERENCE플래그를 세트 하면,D3DRMLOAD_INSTANCEBYCOPYING플래그를 세트 했을 때와 같은 효과를 얻을 수 있다. 로더는, 동일한 오브젝트가 존재해도, 각 이름 없음 오브젝트를 새로운 오브젝트로서 생성 한다.

Direct3DRMMeshBuilder3.Optimize

Direct3DRMMeshBuilder3

현재의 디바이스에 대해서Direct3DRMMeshBuilder3오브젝트를 최적화한다. 이 조작은 고가로 되는 일이 있다.

구문

object. Optimize( )
object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.Save

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트를 보존한다.

구문

object. Save(fname As String,
  xFormat As CONST_D3DRMXOFFORMAT,
  Save As CONST_D3DRMSAVEFLAGS)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
fname
생성 되는 파일의 이름. 이 파일의 파일명 확장자(extension)는,. x가 아니면 안된다.
xFormat
CONST_D3DRMXOFFORMAT 열거형의D3DRMXOF_TEXT값.
Save
보존 옵션을 나타내는CONST_D3DRMSAVEFLAGS 열거형의 하나 이상의 값.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.ScaleMesh

Direct3DRMMeshBuilder3

지정의 스케일링 계수를 사용해모델 좌표로 x축, y축, z축으로 평행에Direct3DRMMeshBuilder3오브젝트를 스케일링 한다.

구문

object. ScaleMesh(sx As Single,
  sy As Single,
  sz As Single)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
sx, sy, sz
x축, y축, z축으로 따라 적용되는 스케일링 계수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.SetColor

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 모든 면으로 지정의 색을 설정한다.

구문

object. SetColor(col As Long)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
col
면의 색. 적, 초록, 파랑의 색요소 뿐만이 아니라, 알파 요소도 반드시 세트 한다. 그렇게 하지 않으면 오브젝트가 가시가 되지 않는 것이 있다. 색은 4바이트의Long로 나타내진다. 고바이트는 알파 요소이며, 후속의 바이트가 적, 초록, 파랑을 정의한다. 보다 간단하게 색을 구축하려면 DirectX7 오브젝트의CreateColorRGBA를 사용해, 풀 알파를 희망하고 있을 뿐(만큼)의 경우는SetColorRGB를 사용한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.SetColorRGB

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 모든 면에 적, 초록, 파랑의 색요소를 설정한다.

구문

object. SetColorRGB(red As Single,
  green As Single,
  blue As Single)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
red, green, blue
색의 적, 초록, 파랑의 각 성분.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.SetColorSource

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 색소스를 설정한다.

구문

object. SetColorSource(val As CONST_D3DRMCOLORSOURCE)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
val
사용하는 새로운 색소스 지정하는CONST_D3DRMCOLORSOURCE 열거형의 멤버.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMeshBuilder3.GetColorSource

Direct3DRMMeshBuilder3.SetMaterial

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 모든 면의 머트리얼을 설정한다.

구문

object. SetMaterial(mat As Direct3DRMMaterial2)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
mat
Direct3DRMMeshBuilder3오브젝트의Direct3DRMMaterial2 인터페이스.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.SetNormal

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 지정되고 있는 버텍스의법선 벡터를 설정한다.

구문

object. SetNormal(idx As Long,
  x As Single,
  y As Single,
  z As Single)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
idx
설정하는 법선의 인덱스.
x, y, z
지정의 법선에 할당하는 벡터의 x, y, z의 각 요소.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.SetPerspective

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트에 대한 퍼스펙티브 보정 텍스쳐 맵핑을 유효 또는 무효로 한다.

구문

object. SetPerspective(perspectiveEnabled As CONST_DBOOLFLAGS)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
perspectiveEnabled
메쉬를 퍼스펙티브 보정으로 텍스쳐 맵 할 필요가 있으면 D_TRUE를, 그렇지 않으면 D_FALSE를 지정한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.SetQuality

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 렌더링 퀄리티를 설정한다.

구문

object. SetQuality(q As CONST_D3DRMRENDERQUALITY)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
q
사용하는 새로운 렌더링 퀄리티를 지정하는CONST_D3DRMRENDERQUALITY 열거형의 멤버.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

오브젝트 퀄리티에는, 3개의 컴퍼넌트가 있다. 즉, 쉐이딩 모드 (플랫 또는 굿 로. 폰은 이행 되지 않고, 디폴트로 gouraud shading가 된다), 조명 타입 (온 또는 오프) 및 전부 칠해 모드 (포인트, 와이어 프레임 또는 솔리드)이다.

디바이스의 퀄리티를 설정하려면 ,Direct3DRMDevice3.SetQuality 를 이용한다. 디폴트로, 디바이스 퀄리티는D3DRMRENDER_FLAT (flat shading, 조명 온 및 솔리드 전부 칠해)이다.

Direct3DRMMeshBuilder3오브젝트의 퀄리티를 설정하려면 ,SetQuality메소드를 이용한다. 디폴트로,Direct3DRMMeshBuilder3오브젝트의 퀄리티는D3DRMRENDER_GOURAUD (gouraud shading, 조명 온 및 솔리드 전부 칠해)이다.

힌트: gouraud shading는, 상세 레벨을 빈번하게 또는 재빠르게 변경하는 프로그래시브 메쉬 오브젝트에 대해, 폰 쉐이딩보다 좋은 퍼포먼스를 얻을 수 있다.

Direct3D 보관 유지 모드는, 디바이스나 오브젝트의 각각의 컴퍼넌트에 대한 현재의 설정 중(안)에서 가장 저위의 퀄리티로, 오브젝트에 렌더링을 실시한다. 예를 들어, 오브젝트의 현재의 퀄리티 설정이D3DRMRENDER_GOURAUD로, 디바이스가D3DRMRENDER_FLAT이라고, 오브젝트는 flat shading, 솔리드 전부 칠해, 및 조명 온으로 렌더링 된다.

오브젝트의 현재의 퀄리티 설정이D3DRMSHADE_GOURAUD|D3DRMLIGHT_OFF|D3DRMFILL_WIREFRAME로, 디바이스의 퀄리티 설정이D3DRMSHADE_FLAT|D3DRMLIGHT_ON|D3DRMFILL_POINT이라고, 오브젝트는 flat shading, 조명 오프, 및포인트전부 칠해 모드로 렌더링 된다.

이러한 룰은,Direct3DRMMeshBuilder3오브젝트 및Direct3DRMProgressiveMesh 오브젝트에 적용된다. 그러나,Direct3DRMMesh 오브젝트는 이러한 룰에 따르지 않다. 메쉬 오브젝트는 디바이스의 퀄리티 설정을 무시해, 그룹 퀄리티 설정을 이용한다(디폴트로D3DRMRENDER_GOURAUD).

참조

Direct3DRMMeshBuilder3.GetQuality

Direct3DRMMeshBuilder3.SetTexture

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 모든 면의 텍스쳐를 설정한다.

구문

object. SetTexture(tex As Direct3DRMTexture3)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
tex
필요한Direct3DRMTexture3 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.SetTextureCoordinates

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 지정되고 있는 버텍스의 텍스쳐 좌표를 설정한다.

구문

object. SetTextureCoordinates(idx As Long,
  u As Single,
  v As Single)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
idx
설정하는 버텍스의 인덱스.
u, v
T지정의 메쉬 버텍스에 할당하는 텍스쳐 좌표.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMeshBuilder3.GetTextureCoordinates

Direct3DRMMeshBuilder3.SetTextureTopology

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 텍스쳐 위상기하학을 설정한다.

구문

object. SetTextureTopology(wrap_u As CONST_DBOOLFLAGS,
  wrap_v As CONST_DBOOLFLAGS)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
wrap_u, wrap_v
텍스쳐 위상기하학을 나타내는 값. 원통형 위상기하학을, 각각 u차원 및 v차원에서 텍스쳐에 갖게하고 싶은 경우, 이 2개의 파라미터의, 적어도 한편에 D_TRUE를, 그렇지 않은 경우에는, D_FALSE를 지정한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

텍스쳐 위상기하학 플래그,wrap_u,wrap_v는 Direct3D 직접 모드 렌더링 상태D3DRENDERSTATE_WRAPU,D3DRENDERSTATE_WRAPV의 설정을 제어한다. 랩핑 플래그가 D_TRUE 때, 래스터라이저는, 그것이 2개의 텍스쳐 좌표간에 짧은 (분)편 패스이면, 텍스쳐의 하나의 옆으로부터 반대측의 옆에 횡단 (토로이달 맵핑)한다.

1개의 옆을 따라 0.1에서 0.9의 범위의 v좌표를 가지는 삼각형이 있다고 한다. WRAPV가 D_FALSE이면, 텍스쳐의 거의 전체 길이가 삼각형에 따라 렌더링 된다. WRAPV가 D_TRUE이면, 텍스쳐의 상부와 하부의 스라이바가 렌더링 된다. 게다가 랩핑 플래그가 D_TRUE 때, 텍스쳐 좌표의 일부분만큼이 1.0보다 큰 값을 가진다고 보이기 (위해)때문에, 랩이 D_TRUE 때 텍스쳐는 면을 따라 타일화 되지 않게 된다.

랩핑 동작의 제어는, 텍스쳐 좌표의 올바른 해석에 있어 필요하다. 단일의 텍스쳐가 많은 면을 따라 랩 되고 있는 경우,wrap_u와wrap_v파라미터를 D_TRUE에 세트 한다. 모델이 면 당 1개의 텍스쳐 밖에 가지지 않는가, 또는 1보다 큰 텍스쳐 좌표를 사용해 텍스쳐의 복수의 카피를 단일의 면을 따라 타일화하는 경우,wrap_u와wrap_v를 D_FALSE에 세트 한다.

몇개의 인터페이스는,SetTextureTopology메소드를 에크스포즈 한다. Direct3DRMMeshBuilder3.SetTextureTopology는, 모든 요소 얼굴의 위상기하학을 갱신해,Direct3DRMFace2.SetTextureTopology 에 의한 설정을 오버라이드(override) 한다. 디폴트에서는,Direct3DRMFrame3.SetTextureTopology 는, 디폴트의 머트리얼 모드가D3DRMMATERIAL_FROMMESH 이기 (위해)때문에, 메쉬를 읽어들인다. 머트리얼 모드가D3DRMMATERIAL_FROMMESH이 아닌 경우,Direct3DRMFrame3.SetTextureTopology는Direct3DRMMeshBuilder3.SetTextureTopology에 의한 설정을 오버라이드(override) 한다.

Direct3DRMMeshBuilder3.SetVertex

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 지정되고 있는 버텍스의 위치를 설정한다.

구문

object. SetVertex(idx As Long,
  x As Single,
  y As Single,
  z As Single)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
idx
설정하는 버텍스의 인덱스.
x, y, z
지정의 버텍스에 할당하는 위치의 x, y, z의 각 요소.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.SetVertexColor

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 지정되고 있는 버텍스의 색을 설정한다.

구문

object. SetVertexColor(idx As Long,
  c As Long)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
idx
설정하는 버텍스의 인덱스.
c
지정의 버텍스에 할당하는 색.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMMeshBuilder3.GetVertexColor

Direct3DRMMeshBuilder3.SetVertexColorRGB

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 지정되고 있는 버텍스의 적, 초록, 파랑의 색요소를 설정한다.

구문

object. SetVertexColorRGB(idx As Long,
  r As Single,
  g As Single,
  b As Single)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
idx
설정하는 버텍스의 인덱스.
r, g, b
지정의 버텍스에 할당하는 색의 적, 초록, 파랑의 각 성분.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshBuilder3.Translate

Direct3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트의 버텍스의 위치로 지정의 오프셋(offset)을 추가한다.

구문

object. Translate(tx As Single,
  ty As Single,
  tz As Single)

요소

object
Direct3DRMMeshBuilder3오브젝트를 나타내는오브젝트식.
tx, ty, tz
각 버텍스 위치의 x좌표, y좌표, z좌표에 추가되는 오프셋(offset).

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.


Direct3DRMMeshInterpolator

인타포레이타는, 액션을 저장 한 후, 중간값을 자동 계산해, 오브젝트에 액션을 적용하는 방법을 제공한다. 인타포레이타를 사용해, 색을 혼합해, 다른 위치간에서 오브젝트를 원활히 이동해, 메쉬를 morphing 해, 게다가 다른 다양한 변환도 실시할 수가 있다.

Direct3DRMMesh 오브젝트는,Direct3DRMMeshInterpolator오브젝트에 Attach 할 수 있다. 인타포레이타의 상세한 것에 대하여는, 추가 정보의 「인타포레이타」를 참조할것.

Direct3DRMMeshInterpolator인터페이스에는, 다음의 메소드가 포함된다.

오브젝트의 Attach | AttachObject
DetachObject
GetAttachedObjects
색 | SetGroupColor
SetGroupColorRGB
보간의 실행 | GetIndex
Interpolate
SetIndex
그 외 | Translate
버텍스 위치 | SetVertices

게다가Direct3DRMMeshInterpolator는,Direct3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.

  • AddDestroyCallback
  • Clone
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMMeshInterpolator.AttachObject

Direct3DRMMeshInterpolator

오브젝트를 인타포레이타에 접속한다.

구문

object. AttachObject(mObject As Direct3DRMObject)

요소

object
Direct3DRMMeshInterpolator오브젝트를 나타내는오브젝트식.
mObject
인타포레이타에 Attach 하는Direct3DRMObject 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

Attach 되는 오브젝트는, 다른 인타포레이타에서도, 인타포레이타가xInterpolator형이 되는 타입x의 오브젝트에서도 좋다. 예를 들어,Direct3DRMMesh 오브젝트는,Direct3DRMMeshInterpolator오브젝트에 Attach 할 수 있다.

Direct3DRMMeshInterpolator.DetachObject

Direct3DRMMeshInterpolator

인타포레이타로부터 오브젝트의 Attach를 해제한다.

구문

object. DetachObject(mObject As Direct3DRMObject)

요소

object
Direct3DRMMeshInterpolator오브젝트를 나타내는오브젝트식.
mObject
인타포레이타로부터 Attach를 제외하는Direct3DRMObject 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshInterpolator.GetAttachedObjects

Direct3DRMMeshInterpolator

인타포레이타에 현재 Attach 되고 있는 오브젝트를 취득한다.

구문

object. GetAttachedObjects( ) As Direct3DRMObjectArray

요소

object
Direct3DRMMeshInterpolator오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMObjectArray 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshInterpolator.GetIndex

Direct3DRMMeshInterpolator

인타포레이타의 현재의 내부 인덱스(시간)를 취득한다.

구문

object. GetIndex( ) As Single

요소

object
Direct3DRMMeshInterpolator오브젝트를 나타내는오브젝트식.

반환값

인타포레이타의 현재의 내부 인덱스를 포함한 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

인타포레이타에 저장 되고 있는 각 키는, 인덱스값을 가진다. 키를(메소드를 사용해) 기록 하면 와, 키에는, 현재의 인타포레이타의 인덱스값으로 스탬프가 밀린다. 키의 인덱스값은, 스탬프를 밀린 후, 바뀔 것은 없다.

Direct3DRMMeshInterpolator.Interpolate

Direct3DRMMeshInterpolator

인타포레이타에 저장 되고 있는 키간을 보간 해, 일련의 액션을 생성한다. 그 후, 액션은, 지정의 오브젝트에 적용된다. 오브젝트의 지정이 없으면, 액션은, 현재 Attach 되고 있는 오브젝트에 적용된다.

구문

object. Interpolate(val As Single,
  mObject As Direct3DRMObject,
  options As CONST_D3DRMINTERPOLATIONFLAGS)

요소

object
Direct3DRMMeshInterpolator오브젝트를 나타내는오브젝트식.
val
인타포레이타의 현재의 내부 인덱스를 포함한 값.
mObject
Direct3DRMObject 오브젝트. 이 오브젝트는, 인타포레이타에 저장 떠날 수 있어 모든 프로퍼티에 대한 보간값을 할당하는 오브젝트를 나타낸다. 이 포인터는 NOTHING에서도 좋다. 그 경우, 모든 Attach 되고 있는 오브젝트의 프로퍼티값에는, 보간값이 세트 된다.
options
실행하는 보간의 종류를 제어하는CONST_D3DRMINTERPOLATIONFLAGS 열거형의 값의 하나.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshInterpolator.SetGroupColor

Direct3DRMMeshInterpolator

Direct3DRMMeshInterpolator오브젝트에 컬러 키를 추가한다.

구문

object. SetGroupColor(id As Long,
  val As Long)

요소

object
Direct3DRMMeshInterpolator오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 를 사용해 생성된 것이 아니면 안 된다.
val
그룹의 색. 적, 초록, 파랑의 색요소 뿐만이 아니라, 알파 요소도 반드시 세트 한다. 그렇게 하지 않으면 오브젝트가 가시가 되지 않는 것이 있다. 색은 4바이트의Long로 나타내진다. 고바이트는 알파 요소이며, 후속의 바이트가 적, 초록, 파랑을 정의한다. 보다 간단하게 색을 구축하려면 DirectX7 오브젝트의CreateColorRGBA를 사용해, 풀 알파를 희망하고 있을 뿐(만큼)의 경우는SetColorRGB를 사용한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshInterpolator.SetGroupColorRGB

Direct3DRMMeshInterpolator

Direct3DRMMeshInterpolator오브젝트에 그룹 RGB 키를 추가한다.

구문

object. SetGroupColorRGB(id As Long,
  r As Single,
  g As Single,
  b As Single)

요소

object
Direct3DRMMeshInterpolator오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 를 사용해 생성된 것이 아니면 안 된다.
r, g, b
그룹 컬러의 적, 초록, 파랑의 색요소.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshInterpolator.SetIndex

Direct3DRMMeshInterpolator

인타포레이타의 내부 인덱스(시간)로 지정의 값을 세트 한다. 다른 인타포레이타가 그 인타포레이타에 Attach 되고 있으면, 이 메소드는, 재귀적으로 그러한 인덱스를 같은 값에 동기 시킨다.

구문

object. SetIndex(val As Single)

요소

object
Direct3DRMMeshInterpolator오브젝트를 나타내는오브젝트식.
val
인타포레이타의 내부 인덱스에 대해서 세트 되는 시간.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

인타포레이타에 저장 되고 있는 각 키는, 인덱스값을 가진다. 키를(메소드를 사용해) 기록 하면 와, 키에는, 현재의 인타포레이타의 인덱스값으로 스탬프가 밀린다. 키의 인덱스값은, 스탬프를 밀린 후, 바뀔 것은 없다.

Direct3DRMMeshInterpolator.SetVertices

Direct3DRMMeshInterpolator

Direct3DRMMeshInterpolator오브젝트에 버텍스 위치 키를 추가한다.

구문

object. SetVertices(id As Long,
  idx As Long,
  count As Long,
  vertexArray() As D3DRMVERTEX)

요소

object
Direct3DRMMeshInterpolator오브젝트를 나타내는오브젝트식.
id
그룹의 식별자. 이 식별자는Direct3DRMMesh.AddGroup 메소드를 사용해 생성된 것이 아니면 안 된다.
idx
수정하는 메쉬 그룹의 최초의 버텍스의 인덱스.
count
세트 하는 연속 버텍스의 수. vertexArray배열은, 적어도count수의 요소를 저장 해야 한다.
vertexArray
설정하는 버텍스 위치를 나타내는D3DRMVERTEX 형의 배열.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMMeshInterpolator.Translate

Direct3DRMMeshInterpolator

Direct3DRMMeshInterpolator오브젝트중의 버텍스의 위치에, 지정된 오프셋(offset)를 추가한다.

구문

object. Translate(tx As Single,
  ty As Single,
  tz As Single)

요소

object
Direct3DRMMeshInterpolator오브젝트를 나타내는오브젝트식.
tx, ty, tz
각 버텍스 위치의 x좌표, y좌표, z좌표에 추가되는 오프셋(offset).

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.


Direct3DRMObject

어플리케이션은, Microsoft® Direct3D® 보관 유지 모드 오브젝트의 슈퍼 클래스와 교환하기 위해서(때문에),Direct3DRMObject인터페이스의 메소드를 사용한다.

Direct3DRMObject는, 시스템중의 모든 오브젝트의 공통 슈퍼 클래스이다. Direct3DRMObject오브젝트에는, 모든 오브젝트에 공통되는 특성이 있다.

오브젝트를 생성 하려면 , 어플리케이션은, 최초로, Direct3D 보관 유지 모드 오브젝트를 인스턴스화하지 않으면 안 된다. 다음에, 어플리케이션은, 오브젝트를 생성 하는 오브젝트의 인터페이스 메소드를 호출해, 오브젝트에 고유의 파라미터를 지정한다. 예를 들어,Direct3DRMAnimation 오브젝트를 생성 하려면 , 어플리케이션은Direct3DRM3.CreateAnimation 메소드를 호출하게 된다. 다음에, 생성 메소드는 새로운 오브젝트를 생성 해, 파라미터중에서 (그 외 모든 것은 디폴트값인 채) 건네받는 데이터의 오브젝트 속성의 몇개인가를 초기화해, 오브젝트를 돌려준다. 다음에, 어플리케이션은, 이 오브젝트의 인터페이스를 지정해, 오브젝트를 수정 및 사용할 수가 있다.

임의의 오브젝트는, 어플리케이션 고유 데이터의 32 비트를 저장 할 수가 있다. 이 데이터를 보관 유지 모드로 해석 또는 변경할 수 없다. 어플리케이션은,Direct3DRMObject.GetAppData 메소드를 사용해 이 데이터를 읽어들여,Direct3DRMObject.SetAppData 메소드를 사용해 이 데이터에 쓰기 할 수가 있다. 어플리케이션이Direct3DRMFrame 의 각 오브젝트의 구조체를 보관 유지하고 있으면, 이 데이터의 검색은 간단하게 된다. 예를 들어,Direct3DRMFrame3.GetParent 메소드의 호출로Direct3DRMFrame 오브젝트를 취득하는 경우, 어플리케이션은 그 Private 구조체에 액세스 해, 데이터를 간단하게 꺼내, 시간이 걸리는 검색을 피할 수가 있다.

어플리케이션을 편성하는 지원을 위해서(때문에), 또는 어플리케이션의 유저 인터페이스의 일부로서 이름을 오브젝트에 할당하고 싶은 경우도 있다고 생각된다. Direct3DRMObject.SetName 과Direct3DRMObject.GetName 메소드를 사용해, 오브젝트명을 세트 해, 취득할 수가 있다.

어플리케이션 고유 데이터의 가능한 용도의 이제(벌써) 1개의 예는, 어플리케이션으로 메쉬내의 면을 서브 세트 (예를 들어, 전면과 후면)에 그룹화 할 필요가 있는 경우이다. 면안의 어플리케이션 데이터를 사용해, 면을 이러한 그룹의 어디에 들어갈 수 있는지를 주기할 수가 있다.

어플리케이션에서는, 오브젝트가 파기되었을 경우에 호출하는 함수를 지정할 수가 있다. 예를 들어, 어플리케이션으로 오브젝트에 관련지을 수 있었던 메모리의 할당 해제를 실시할 필요가 있는 경우 등이다. 이 때문에는,Direct3DRMObject.AddDestroyCallback 메소드를 사용한다. 이 메소드로 이전에 등록한 함수를 삭제하려면 ,Direct3DRMObject.DeleteDestroyCallback 메소드를 사용한다.

콜백은, 오브젝트가 파기되어 시스템이 오브젝트의 메모리 할당을 해제하려고 했을 경우에게만 불려 간다. 어플리케이션이 오브젝트에 관한 추가 데이터를 보관 유지하고 있는 경우 (예를 들어, 다이내믹스를 이행 하기 위해서), 어플리케이션은 데이터의 처리가 가능한 것을 자기 자신에게 통지하는 수단으로서 이 콜백을 사용할 수가 있다.

Direct3DRMObject인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

어플리케이션 고유의 데이터 | GetAppData
SetAppData
복제 | CloneObject
이름 | GetClassName
GetName
SetName
통지 | AddDestroyCallback
DeleteDestroyCallback

모든 보관 유지 모드 오브젝트는,Direct3DRMObject인터페이스 메소드를 계승한다.

Direct3DRMObject.AddDestroyCallback

Direct3DRMObject

오브젝트가 파기될 때 불려 가는 함수를 등록한다.

이 메소드는 이행되어 있지 않다.

구문

object. AddDestroyCallback(fn As Direct3DRMCallback,
  arg As Variant)

요소

object
Direct3DRMObject오브젝트를 나타내는오브젝트식.
fn
오브젝트가 파기될 때 사용되는, 유저 정의의Direct3DRMCallback 콜백 인터페이스.
arg
콜백에게 건네지는 어플리케이션 정의 데이터. 이 함수는 오브젝트가 파기된 후에 사용되기 (위해)때문에, 인수로서 오브젝트와 함께 사용해서는 안 된다.

에러값

이 메소드는 E_NOTIMPL를 돌려준다.

Direct3DRMObject.CloneObject

Direct3DRMObject

오브젝트의 복제를 생성 한다.

구문

object. CloneObject( ) As Direct3DRMObject

요소

object
Direct3DRMObject오브젝트를 나타내는오브젝트식.

반환값

오브젝트의 복제를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMObject.DeleteDestroyCallback

Direct3DRMObject

Direct3DRMObject.AddDestroyCallback 메소드에 의해 등록된 함수를 삭제한다.

이 메소드는 이행되어 있지 않다.

구문

object. DeleteDestroyCallback(fn As Direct3DRMCallback,
  args As Variant)

요소

object
Direct3DRMObject오브젝트를 나타내는오브젝트식.
fn
오브젝트가 파기될 때 사용되는, 유저 정의의Direct3DRMCallback 인터페이스.
args
콜백에게 건네지는 어플리케이션 정의 데이터.

에러값

이 메소드는 E_NOTIMPL를 돌려준다.

Direct3DRMObject.GetAppData

Direct3DRMObject

오브젝트로부터, 어플리케이션 고유의 32 비트 데이터를 취득한다. 데이터의 디폴트값은 0이다.

구문

object. GetAppData( ) As Long

요소

object
Direct3DRMObject오브젝트를 나타내는오브젝트식.

반환값

어플리케이션에 의해 정의된 데이터값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMObject.SetAppData

Direct3DRMObject.GetClassName

Direct3DRMObject

오브젝트의 클래스명을 취득한다.

구문

object. GetClassName( ) As String

요소

object
Direct3DRMObject오브젝트를 나타내는오브젝트식.

반환값

클래스명을 식별하는 캐릭터 라인을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMObject.GetName

Direct3DRMObject

오브젝트명을 취득한다.

구문

object. GetName( ) As String

요소

object
Direct3DRMObject오브젝트를 나타내는오브젝트식.

반환값

오브젝트를 식별하는 캐릭터 라인을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMObject.SetName

Direct3DRMObject.SetAppData

Direct3DRMObject

오브젝트에 어플리케이션 고유의 32 비트 데이터를 설정한다.

구문

object. SetAppData(data As Long)

요소

object
Direct3DRMObject오브젝트를 나타내는오브젝트식.
data
오브젝트에 저장 되는 유저 정의의 데이터.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMObject.GetAppData

Direct3DRMObject.SetName

Direct3DRMObject

오브젝트의 이름을 설정한다.

구문

object. SetName(name As String)

요소

object
Direct3DRMObject오브젝트를 나타내는오브젝트식.
name
오브젝트의 이름을 나타내는 유저 정의의 데이터.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMObject.GetName


Direct3DRMObjectArray

어플리케이션은,Direct3DRMObject오브젝트를 그룹화 하기 위해서Direct3DRMObjectArray인터페이스의 메소드를 이용한다. 오브젝트 배열은, 0이 기준이 되어 있다 (0~N-1).

Direct3DRMObjectArray인터페이스는, 다음의 메소드를 지원 한다.

  • GetElement
  • GetSize

Direct3DRMObjectArray오브젝트는, 인타포레이타오브제크트 위에의GetAttachedObjects의 호출에 의해 취득된다.

Direct3DRMObjectArray.GetElement

Direct3DRMObjectArray

Direct3DRMObjectArray오브젝트로부터 지정된 요소를 취득한다.

구문

object. GetElement(index As Long) As Direct3DRMObject

요소

object
Direct3DRMObjectArray오브젝트를 나타내는오브젝트식.
index
배열 요소.

반환값

Direct3DRMObject 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMObjectArray.GetSize

Direct3DRMObjectArray

Direct3DRMObjectArray오브젝트에 포함되어 있는 요소수를 취득한다.

구문

object. GetSize( ) As Long

요소

object
Direct3DRMObjectArray오브젝트를 나타내는오브젝트식.

반환값

요소수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.


Direct3DRMPick2Array

어플리케이션은, 픽 오브젝트를 그룹화 해, 보다 많은 정보를 돌려주기 위해서(때문에),Direct3DRMPick2Array인터페이스의 메소드를 이용한다. 픽 배열은, 0이 기준이 되어 있다 (0~N-1). 픽의 상세한 것에 대하여는, 「Direct3DRMPickArray 」를 참조할것.

Direct3DRMFrame3.RayPick 메소드를 사용해,Direct3DRMPick2Array 오브젝트를 취득한다. 다음에,Direct3DRMPick2Array.GetPickFrame 메소드를 호출해,Direct3DRMFrameArray 인터페이스, 비주얼 오브젝트, 및 광선이 교차하는 오브젝트에 관한 정보를 취득할 수가 있다. 이 정보에는, 면과 그룹의 식별자, 픽 위치, 및 오브젝트의 버텍스, 버텍스 법선, 색에 대한 수평과 수직 텍스쳐 좌표가 포함된다. 프레임의 배열은, 비주얼 오브젝트에 통하는 계층에의 패스이다.

Direct3DRMPick2Array인터페이스는, 다음의 메소드를 지원 한다.

  • GetPickFrame
  • GetPickVisual
  • GetSize

Direct3DRMPick2Array오브젝트는,Direct3DRMFrame3.RayPick메소드의 호출에 의해 취득된다.

Direct3DRMPick2Array.GetPickFrame

Direct3DRMPick2Array

지정된 픽에 의해 교차하는Direct3DRMFrameArray 오브젝트를 취득한다.

구문

object. GetPickFrame(index As Long,
  pickDesc As D3DRMPICKDESC2) As Direct3DRMFrameArray

요소

object
Direct3DRMPick2Array오브젝트를 나타내는오브젝트식.
index
정보를 취득하는 픽을 식별하는, 픽 배열에의 인덱스.
pickDesc
면이나 그룹의 식별자, 픽의 위치, 버텍스의 수평 및 수직 텍스쳐 좌표, 버텍스의 법선 및 교차한 오브젝트의 색이 지정하는D3DRMPICKDESC2 형.

반환값

지정된 픽에 관련지을 수 있었던Direct3DRMFrameArray 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,D3DRMPICKDESC 형은 아니고D3DRMPICKDESC2형의 u값과 v값을 취득하는 점을 제외하면,Direct3DRMPickedArray.GetPickFrame 와 유사한다.

참조

Direct3DRMFrame3.RayPick

Direct3DRMPick2Array.GetPickVisual

Direct3DRMPick2Array

지정된 픽에 의해 교차한Direct3DRMVisual 오브젝트를 취득한다.

구문

object. GetPickVisual(index As Long,
  pickDesc As D3DRMPICKDESC2) As Direct3DRMVisual

요소

object
Direct3DRMPick2Array오브젝트를 나타내는오브젝트식.
index
정보를 취득하는 픽을 식별하는, 픽 배열에의 인덱스.
pickDesc
면이나 그룹의 식별자, 픽의 위치, 버텍스의 수평 및 수직 텍스쳐 좌표, 버텍스의 법선 및 교차한 오브젝트의 색이 지정하는D3DRMPICKDESC2 형.

반환값

지정된 픽에 관련지을 수 있었던Direct3DRMVisual 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,D3DRMPICKDESC 형은 아니고D3DRMPICKDESC2형의 u값과 v값을 취득하는 점을 제외하면,Direct3DRMPickArray.GetPickVisual 와 유사한다.

참조

Direct3DRMFrame3.RayPick

Direct3DRMPick2Array.GetSize

Direct3DRMPick2Array

Direct3DRMPick2Array오브젝트에 포함되는 요소수를 취득한다.

구문

object. GetSize( ) As Long

요소

object
Direct3DRMPick2Array오브젝트를 나타내는오브젝트식.

반환값

요소수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.


Direct3DRMPickArray

어플리케이션은,Direct3DRMPickArray인터페이스의 메소드를 사용해, 픽 오브젝트를 그룹화 한다. 픽 배열은, 0이 기준이 되어 있다 (0~N-1).

피킹은, 뷰포트중에서 2 D좌표 또는 프레임중에서 벡터가 주어졌을 때에, 장면 위에의 비주얼을 검색하는 프로세스이다. 광선 픽에 대해서는, 「Direct3DRMPick2Array 」를 참조할것.

Direct3DRMViewport2.Pick 메소드를 사용해,Direct3DRMPickArray 오브젝트를 취득한다. 다음에,Direct3DRMPickArray.GetPickFrame 메소드를 호출해,Direct3DRMFrameArray 인터페이스와 비주얼 오브젝트를 취득할 수가 있다. 프레임의 배열은, 계층을 거쳐 비주얼 오브젝트에 통하는 패스이다. 이것은, 즉, 계층안의 최상부의 부모가 배열의 최초로 오는 비주얼 오브젝트의 친프레임의 계층 리스트이다.

Direct3DRMPickArray인터페이스는, 다음의 메소드를 지원 한다.

  • GetPickFrame
  • GetPickVisual
  • GetSize

Direct3DRMPickArray오브젝트는,Direct3DRMViewport2.Pick 메소드의 호출에 의해 취득된다.

Direct3DRMPickArray.GetPickFrame

Direct3DRMPickArray

지정된 픽에 의해 교차하는Direct3DRMFrameArray 오브젝트를 취득한다.

구문

object. GetPickFrame(index As Long,
  pickDesc As D3DRMPICKDESC) As Direct3DRMFrameArray

요소

object
Direct3DRMPickArray오브젝트를 나타내는오브젝트식.
index
정보를 취득하는 픽을 식별하는, 픽 배열에의 인덱스.
pickDesc
픽의 위치, 면, 취득하는 오브젝트의 그룹 식별자를 지정하는D3DRMPICKDESC 형.

반환값

지정된 픽에 관련지을 수 있었던Direct3DRMFrameArray 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMViewport2.Pick

Direct3DRMPickArray.GetPickVisual

Direct3DRMPickArray

지정된 픽에 의해 교차하는Direct3DRMVisual 오브젝트를 돌려준다.

구문

object. GetPickVisual(index As Long,
  pickDesc As D3DRMPICKDESC) As Direct3DRMVisual

요소

object
Direct3DRMPickArray오브젝트를 나타내는오브젝트식.
index
정보를 취득하는 픽을 식별하는, 픽 배열에의 인덱스.
pickDesc
픽의 위치, 면, 취득하는 오브젝트의 그룹 식별자를 지정하는D3DRMPICKDESC 형.

반환값

지정된 픽에 관련지을 수 있었던Direct3DRMVisual 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMViewport2.Pick

Direct3DRMPickArray.GetSize

Direct3DRMPickArray

Direct3DRMPickArray오브젝트에 포함되어 있는 요소수를 취득한다.

구문

object. GetSize( ) As Long

요소

object
Direct3DRMPickArray오브젝트를 나타내는오브젝트식.

반환값

요소수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.


Direct3DRMProgressiveMesh

메쉬는, 다각형면세트로부터 구성되는 비주얼 오브젝트이다. 메쉬는, 버텍스세트와 면세트를 정의한다. 메쉬의 상세한 것에 대하여는, 「Direct3DRMMesh 」를 참조할것.

프로그래시브 메쉬는, 베이스 메쉬 (엉성한 버젼) 및 메쉬를 한층 더 정제 하기 위해서 사용되는버텍스 분할레코드세트로서 저장 되는 메쉬이다. 즉, 프로그래시브인 정제가 가능하다. 이것에 의해, 메쉬용의 렌더링의 상세 레벨을 세트 해, 리모트 소스로부터의 프로그래시브 다운로드도 가능하게 된다.

프로그래시브 메쉬는, Microsoft® Direct3D®보관 유지 모드의 비주얼이며, 비주얼 처리의 표준적인 방법으로 사용할 수가 있다. 즉, 프로그래시브 메쉬는, 프레임 계층에 추가하는 것, 여러 차례의 인스턴스화, 및 픽도 가능하다.

Direct3DRMProgressiveMesh 인터페이스의 메소드를 사용해, 렌더링 하는 버텍스 또는 면의 수를 세트 해, 렌더링 상세를 제어할 수가 있다. 렌더링에 필요한 최소 상세 레벨을 지정할 수도 있다. 보통, 프로그래시브 메쉬는, 베이스 메쉬가 한 번 사용 가능하게 되면(자) 렌더링 되지만,Direct3DRMProgressiveMesh.SetMinRenderDetail 메소드에 의해 렌더링의 전에 그 이상의 상세 레벨이 필요하다라고 지정할 수가 있다. 또,Direct3DRMProgressiveMesh.CreateMesh 메소드를 사용해, 프로그래시브 메쉬 고유 상태로부터Direct3DRMMesh 오브젝트를 구축할 수도 있다.

프로그래시브 메쉬를, 파일, 리소스, 메모리, 또는 URL로부터 로드할 수가 있다. 로딩은 동기식에서도 비동기식에서도 실시할 수 있다. 다운로드 상태는Direct3DRMProgressiveMesh.GetLoadStatus 메소드에 의해 체크해,Direct3DRMProgressiveMesh.Abort 메소드로 다운로드를 종료할 수가 있다. 로딩이 비동기식의 경우, 로드의 진행 상태를 조사하기 위해서(때문에)Direct3DRMProgressiveMesh.RegisterEvents 와Direct3DRMProgressiveMesh.GetLoadStatus 메소드를 개입시켜 이벤트를 사용할지 어떨지는 어플리케이션 나름이다.

Direct3DRMProgressiveMesh 오브젝트는,Direct3DRM3.CreateProgressiveMesh 메소드를 사용하는 것에 의해 생성 된다. 생성 후, 오브젝트는 계층에 추가할 수 있지만, 적어도 베이스 메쉬가 사용 가능하게 될 때까지, 렌더링 되지 않는다.

Direct3DRMProgressiveMesh인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

메쉬의 생성과 카피 | CreateMesh
 | Duplicate
 | GetBox
로드 | Abort
 | GetLoadStatus
 | LoadFromFile
퀄리티의 설정 | SetQuality
 | GetQuality
상세한 관리 | GetDetail
 | GetFaceDetail
 | GetFaceDetailRange
 | GetVertexDetail
 | GetVertexDetailRange
 | SetDetail
 | SetFaceDetail
 | SetMinRenderDetail
 | SetVertexDetail
이벤트의 등록 | RegisterEvents

Direct3DRMProgressiveMesh인터페이스는,Direct3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.
AddDestroyCallback
CloneObject
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMProgressiveMesh.Abort

Direct3DRMProgressiveMesh

현재 액티브한 다운로드를 중지한다.

구문

object. Abort( )

요소

object
Direct3DRMProgressiveMesh오브젝트를 나타내는오브젝트식.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드가 사용되기 전에 베이스 메쉬가 다운로드되고 있는 경우, 그 효과는, 프로그래시브 메쉬가 로드 되어 분할 버텍스가 유효한 상태에 있어, 프로그래시브 메쉬가 렌더링 가능한 경우와 같다. 다른 프로그래시브 메쉬 메소드도 사용할 수 있다. Direct3DRMProgressiveMesh.Abort를 호출하기 전에 베이스 메쉬가 다운로드되지 않고, 장면에 프로그래시브 메쉬를 추가했을 경우,Direct3DRMViewport2.Render 메소드는 성공하지만, 프로그래시브 메쉬에의 렌더링은 행해지지 않는다. 또, 프로그래시브 메쉬를 사용할때 (예를 들어, 메쉬나 클론을 생성 하기 위한(해))에 베이스 메쉬가 다운로드되어 있지 않으면, 호출은D3DRMERR_NOTENOUGHDATA 를 돌려준다.

미해결의 이벤트가 있으면, 그것들이 통지된다.

Direct3DRMProgressiveMesh.CreateMesh

Direct3DRMProgressiveMesh

현재의 상세 레벨로 메쉬를 구축한다.

구문

object. CreateMesh( ) As Direct3DRMMesh

요소

object
Direct3DRMProgressiveMesh오브젝트를 나타내는오브젝트식.

반환값

새롭게 생성된Direct3DRMMesh 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

어플리케이션이 아직 사용 가능하게 되지 않은 상세 레벨을 요구하거나 베이스 메쉬가 사용 가능하게 되지 않은 경우, 이 메소드는D3DRMERR_NOTENOUGHDATA 라고 하는 에러를 돌려준다.

Direct3DRMProgressiveMesh.Duplicate

Direct3DRMProgressiveMesh

Direct3DRMProgressiveMesh 오브젝트의 카피를 생성 한다. 이 카피는, 오리지날과 기하 도형이나 면데이터를 모두 공유한다. 그러나, 오리지날과는 별도로 상세 레벨을 설정할 수가 있다. 이것은, 동일한 메쉬 데이터를 계층이 다른 부분에서, 다만, 다른 상세 레벨로 사용할 수 있도록(듯이) 한다. 본질적으로, 프레임 계층내에 프로그래시브 메쉬의 2개의 인스턴스가 있다고 말할 수 있다.

구문

object. Duplicate( ) As Direct3DRMProgressiveMesh

요소

object
Direct3DRMProgressiveMesh오브젝트를 나타내는오브젝트식.

반환값

새롭게 생성되는Direct3DRMProgressiveMesh 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

복제중의 프로그래시브 메쉬에는, 적어도 그 베이스 메쉬를 로드해 두지 않으면 안 된다. 현재, 비동기에 로드안의 프로그래시브 메쉬상에서 이 메소드를 사용하면(자), 복제된 메쉬는 로드하고 있는 프로그래시브 메쉬가 복제되었을 때에 가지고 있던 상세 레벨 밖에 가지지 않는다. 복제 후에 로드 된 만큼 비율 버텍스는, 복제된 메쉬에서는 이용할 수 없다.

프로그래시브 메쉬는, 베이스 메쉬를 나타내는 데이터 세트와 분할 버텍스를 나타내는 데이터 세트를 가지고 있다. 베이스 메쉬 데이터 및 프로그래시브 메쉬의 현상이나 현재의 상세 레벨을 기술하는 데이터는, 복제된 메쉬간에 공유되지 않는다. 그러나, 분할 버텍스 데이터는 공유된다.

Direct3DRMProgressiveMesh.GetBox

Direct3DRMProgressiveMesh

Direct3DRMProgressiveMesh오브젝트를 포함한 경계 박스를 취득한다. 경계 박스는, 각 차원에서, 아이 프레임을 기준으로 하는 최소 및 최대의 좌표를 준다.

구문

object. GetBox(box As D3DRMBOX)

요소

object
Direct3DRMProgressiveMesh오브젝트를 나타내는오브젝트식.
box
경계 박스의 좌표가 세트 되는D3DRMBOX 형.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMProgressiveMesh.GetDetail

Direct3DRMProgressiveMesh

0.0으로 1.0의 사이에 정규화된 현재의 상세 레벨의 프로그래시브 메쉬를 돌려준다.

구문

object. GetDetail( ) As Single

요소

object
Direct3DRMProgressiveMesh오브젝트를 나타내는오브젝트식.

반환값

현재의 상세 레벨의 프로그래시브 메쉬가 세트 되는 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

베이스 메쉬가 다운로드되어 있지 않으면, 이 메소드는,D3DRMERR_PENDING 를 돌려준다. 요구되고 있는 상세 레벨이 설정되어 있으면, 반환값은, 요구 레벨이 채워질 때까지 이후의 호출마다 증가된다. 레벨이 요구되어 있지 않으면, 상세 레벨은, 모든 분할 버텍스의 다운로드가 완료할 때까지 상승한다.

정규화된 값 0.0은 버텍스의 최소수를 나타내 (베이스 메쉬중의 버텍스수), 정규화된 값 1.0은 버텍스의 최대수를 나타낸다.

Direct3DRMProgressiveMesh.GetFaceDetail

Direct3DRMProgressiveMesh

프로그래시브 메쉬에 있는 면의 수를 취득한다.

구문

object. GetFaceDetail( ) As Long

요소

object
Direct3DRMProgressiveMesh오브젝트를 나타내는오브젝트식.

반환값

프로그래시브 메쉬의 면의 수가 세트 되는 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

면의 수를 이용할 수 없으면, 이 메소드는D3DRMERR_PENDING 를 돌려준다.

Direct3DRMProgressiveMesh.GetFaceDetailRange

Direct3DRMProgressiveMesh

프로그래시브 메쉬로 사용 가능한 최소 및 최대의 면카운트를 취득한다.

구문

object. GetFaceDetailRange(min As Long,
  max As Long)

요소

object
Direct3DRMProgressiveMesh오브젝트를 나타내는오브젝트식.
min
면의 최소수가 세트 되는 값.
max
면의 최대수가 세트 되는 값.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

면카운트를 취득할 수 없는 경우, 이 메소드는D3DRMERR_PENDING 를 돌려준다.

Direct3DRMProgressiveMesh.GetLoadStatus

Direct3DRMProgressiveMesh

로드의 현재 상태를 어플리케이션이 조회하는 것을 가능하게 한다.

구문

object. GetLoadStatus(loadStatus As D3DRMPMESHLOADSTATUS)

요소

object
Direct3DRMProgressiveMesh오브젝트를 나타내는오브젝트식.
loadStatus
프로그래시브 메쉬의 로드 상태를 나타내는D3DRMPMESHLOADSTATUS 형.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMProgressiveMesh.GetQuality

Direct3DRMProgressiveMesh

프로그래시브 메쉬의 렌더링 퀄리티를 나타내는 값을 취득한다.

구문

object. GetQuality( ) As CONST_D3DRMRENDERQUALITY

요소

object
Direct3DRMProgressiveMesh오브젝트를 나타내는오브젝트식.

반환값

프로그래시브 메쉬의 렌더링 퀄리티를 지정하는CONST_D3DRMRENDERQUALITY 열거형의 멤버를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMProgressiveMesh.SetQuality

Direct3DRMProgressiveMesh.GetVertexDetail

Direct3DRMProgressiveMesh

프로그래시브 메쉬에 있는 버텍스의 수를 취득한다.

구문

object. GetVertexDetail( ) As Long

요소

object
Direct3DRMProgressiveMesh오브젝트를 나타내는오브젝트식.

반환값

프로그래시브 메쉬에 있는 버텍스의 수가 세트 되는 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

버텍스의 수를 취득할 수 없는 경우, 이 메소드는D3DRMERR_PENDING 를 돌려준다.

Direct3DRMProgressiveMesh.GetVertexDetailRange

Direct3DRMProgressiveMesh

메쉬중에서 사용 가능한 최소 및 최대의 버텍스 카운트를 취득한다

구문

object. GetVertexDetailRange(min As Long,
  max As Long)

요소

object
Direct3DRMProgressiveMesh오브젝트를 나타내는오브젝트식.
min
버텍스의 최소수가 세트 되는 값.
max
버텍스의 최대수가 세트 되는 값.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

버텍스 카운트를 취득할 수 없는 경우, 이 메소드는D3DRMERR_PENDING 를 돌려준다.

Direct3DRMProgressiveMesh.LoadFromFile

Direct3DRMProgressiveMesh

프로그래시브 메쉬 오브젝트를 메모리, 파일, 리소스, 또는 URL로부터 로드한다. 로드는 동기식에서도 비동기식에서도 좋다.

구문

object. LoadFromFile(sFile As String,
  id As String,
  options As CONST_D3DRMLOADFLAGS,
  loadTextureImplementation As Direct3DRMLoadTextureCallback3,
  userArgument As Object)

요소

object
Direct3DRMProgressiveMesh오브젝트를 나타내는오브젝트식.
sFile
로드하는 오브젝트의 소스. 이 소스는,options파라미터로 지정되고 있는 소스 플래그에 의해, 파일, 리소스, 메모리 블록, 또는 스트림의 어떤 것인가로 할 수 있다.
id
로드하는 오브젝트의 이름 또는 위치. id가""의 경우는,options파라미터를D3DRMLOAD_FIRST로 설정한다. Microsoft Visual Basic® 는,String 데이터형이 지정되고 있는 경우에서도, 로드하는 아이템의 위치를 나타내는id파라미터안의Integer를 받아들인다. 예를 들어,id파라미터에1이 설정되어 있으면(자), 1번째의 위치의 오브젝트가 로드 된다.
options
로드를 실행하는 방법을 기술하는CONST_D3DRMLOADFLAGS 열거형의 하나 이상의 값.
loadTextureImplementation
Direct3DRMLoadTextureCallback3 콜백 인터페이스. 조우한 임의의 텍스쳐를 로드하는데 사용된다. 텍스쳐는, 2로 갈라지는 폭과 길이가 아니면 안된다. 이 콜백은, 로더가 조우한 텍스쳐명과 유저 정의의args파라미터에 의해 사용된다. 새로운 thread는, 이 콜백에 대해서는 생성되지 않는다.
userArgument
콜백에게 건네지는 유저 정의 데이터.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

프로그래시브 메쉬는, 초기화하지 않는 한 유효하게 안 된다. 비동기식 다운로드가 지정되고 있으면, 이 API는 즉시 돌아와, 다른 thread가 다운로드를 실행하기 위해서 생성된다. 로드의 진행 상태를 조사하기 위해서(때문에),Direct3DRMProgressiveMesh.RegisterEvents 와Direct3DRMProgressiveMesh.GetLoadStatus 를 사용해 이벤트를 사용할지 어떨지는 어플리케이션 나름이다.

이 메소드와Direct3DRMProgressiveMesh.Duplicate 메소드는, 프로그래시브 메쉬를 초기화한다. 오브젝트는 한 번 밖에 초기화할 수 없다. 따라서, 프로그래시브 메쉬를 클론 또는 복제하고 나서, 그 클론 또는 복제한 메쉬에 로드하는 일도, 이전에 로드한 메쉬에 로드하는 일도 할 수 없다.

Direct3DRMProgressiveMesh.RegisterEvents

Direct3DRMProgressiveMesh

어플리케이션이, 프로그래시브 메쉬 오브젝트에 이벤트를 등록하는 것을 가능하게 한다. 이벤트는, 적절한 조건이 채워졌을 때에 통지된다.

구문

object. RegisterEvents(hEvent As Long,
  flags As Long,
  reserved As Long)

요소

object
Direct3DRMProgressiveMesh오브젝트를 나타내는오브젝트식.
hEvent
필요한 조건이 채워졌을 때에 통지되는 이벤트.
flags
CONST_D3DRMPMESHSTATUSFLAGS 열거형의 하나 이상의 값.
reserved
0이 아니면 안된다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는, 로드의 진행 상태를 감시하기 위해서 사용할 수 있다. 이벤트는, 에러가 발생했을 경우에도 통지되므로, 어플리케이션은, 통지 후에Direct3DRMProgressiveMesh.GetLoadStatus 메소드를 사용할 필요가 있다.

Direct3DRMProgressiveMesh.SetDetail

Direct3DRMProgressiveMesh

요구된 상세 레벨을 0.0 (최소)으로 1.0 (최대)의 사이에 정규화해 설정한다.

구문

object. SetDetail(detail As Single)

요소

object
Direct3DRMProgressiveMesh오브젝트를 나타내는오브젝트식.
detail
요구된 상세 레벨.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

충분한 상세 항목의 다운로드가 아직 완료하고 있지 않으면(다만, 시간이 흐르면 사용 가능), 요구는 받아들여져,D3DRMERR_PENDING 가 돌아간다. 이 에러는 통지이며, 요구된 레벨이, 충분한 상세가 사용 가능하게 되면(자) 즉시 설정된다고 하는 것을 나타내는 것이다.

정규화한 값 0.0은 버텍스의 최소수를 나타내 (베이스 메쉬에 있는 버텍스의 수), 정규화한 값 1.0은 버텍스의 최대수를 나타낸다.

Direct3DRMProgressiveMesh.SetFaceDetail

Direct3DRMProgressiveMesh

요구되는 면의 수를 설정한다.

구문

object. SetFaceDetail(count As Long)

요소

object
Direct3DRMProgressiveMesh오브젝트를 나타내는오브젝트식.
count
요구되는 면의 수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

때로는, 항상 요구된 값으로부터 1 이내인 것에도 불구하고, 프로그래시브 메쉬가 요구된 면의 수로 설정할 수 없는 것이 있다. 이것은, 분할 버텍스가 1내지 2면 더할 수가 있기 때문이다. 예를 들어,SetFaceDetail(20)를 사용하면(자), 프로그래시브 메쉬는 면의 상세를 19또는 21인 만큼 밖에 설정 할 수 없을 지도 모르다. 프로그래시브 메쉬에 있는 면의 실제의 수는, 항상Direct3DRMProgressiveMesh.GetFaceDetail 메소드를 사용해 취득할 수가 있다.

충분한 상세 항목의 다운로드가 아직 완료하고 있지 않으면(다만, 시간이 흐르면 사용 가능), 요구는 받아들여져,D3DRMERR_PENDING 가 돌아간다. 이 에러는, 통지이며, 요구된 레벨이, 충분한 상세가 사용 가능하게 되면(자) 즉시 설정된다고 하는 것을 나타내는 것이다. 요구되고 있는 상세 레벨이, 프로그래시브 메쉬로 사용 가능한 상세 레벨보다 크면,D3DRMERR_REQUESTTOOLARGE 가 돌아간다.

참조

Direct3DRMProgressiveMesh.GetFaceDetail

Direct3DRMProgressiveMesh.SetMinRenderDetail

Direct3DRMProgressiveMesh

0.0(최소 상세 레벨)에서 1.0(최대 상세 레벨)의 범위에서, 로드안에 렌더링 하는 상세한 최소 레벨을 설정한다. 보통, 프로그래시브 메쉬는, 베이스 메쉬가 사용 가능하게 된( 및 메쉬가 장면 그래프중에 존재하게 된) 다음에 렌더링 된다.

구문

object. SetMinRenderDetail(val As Single)

요소

object
Direct3DRMProgressiveMesh오브젝트를 나타내는오브젝트식.
val
요구되고 있는 최소 상세.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는, 로드안에 렌더링 되는 면 또는 버텍스의 최소수를 설정한다. 이 값은, 베이스 메쉬로 이미 렌더링 되고 있는 것에 추가한 값이다.

이후의Direct3DRMProgressiveMesh.SetDetail ,Direct3DRMProgressiveMesh.SetFaceDetail , 또는Direct3DRMProgressiveMesh.SetVertexDetail 호출은 언제라도, 이 메소드보다 우선된다.

Direct3DRMProgressiveMesh.SetQuality

Direct3DRMProgressiveMesh

Direct3DRMProgressiveMesh오브젝트의 렌더링 퀄리티를 설정한다.

구문

object. SetQuality(quality As CONST_D3DRMRENDERQUALITY)

요소

object
Direct3DRMProgressiveMesh오브젝트를 나타내는오브젝트식.
quality
사용하는 새로운 렌더링 퀄리티를 지정하는CONST_D3DRMRENDERQUALITY 열거형의 멤버.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

오브젝트 퀄리티에는, 3개의 컴퍼넌트가 있다. 즉, 쉐이딩 모드 (플랫 또는 굿 로. 폰은 이행 되지 않고, 디폴트로 gouraud shading가 된다), 조명 타입 (온 또는 오프) 및 전부 칠해 모드 (포인트, 와이어 프레임 또는 솔리드)이다.

디바이스의 퀄리티를 설정하려면 ,Direct3DRMDevice3.SetQuality 를 이용한다. 디폴트로, 디바이스 퀄리티는D3DRMRENDER_FLAT (flat shading, 조명 온 및 솔리드 전부 칠해)이다.

Direct3DRMProgressiveMesh오브젝트의 퀄리티를 설정하려면 ,SetQuality메소드를 이용한다. 디폴트로,Direct3DRMProgressiveMesh오브젝트의 퀄리티는D3DRMRENDER_GOURAUD (gouraud shading, 조명 온 및 솔리드 전부 칠해)이다.

힌트: gouraud shading는, 상세 레벨을 빈번하게 또는 재빠르게 변경하는 프로그래시브 메쉬 오브젝트에 대해, 보다 좋은 퍼포먼스를 얻을 수 있다.

Direct3D 보관 유지 모드는, 디바이스나 오브젝트의 각각의 컴퍼넌트에 대한 현재의 설정 중에서 가장 저위의 퀄리티로, 오브젝트에 렌더링을 실시한다. 예를 들어, 오브젝트의 현재의 퀄리티 설정이D3DRMRENDER_GOURAUD로, 디바이스가D3DRMRENDER_FLAT이라고, 오브젝트는 flat shading, 솔리드 전부 칠해, 및 조명 온으로 렌더링 된다.

오브젝트의 현재의 퀄리티 설정이D3DRMSHADE_GOURAUD|D3DRMLIGHT_OFF|D3DRMFILL_WIREFRAME로, 디바이스의 퀄리티 설정이D3DRMSHADE_FLAT|D3DRMLIGHT_ON|D3DRMFILL_POINT이라고, 오브젝트는 flat shading, 조명 오프, 및포인트전부 칠해 모드로 렌더링 된다.

이러한 룰은,Direct3DRMMeshBuilder3 오브젝트 및Direct3DRMProgressiveMesh 오브젝트에 적용된다. 그러나,Direct3DRMMesh오브젝트는 이러한 룰에 따르지 않다. 메쉬 오브젝트는 디바이스의 퀄리티 설정을 무시해, 그룹 퀄리티 설정을 이용한다(디폴트로D3DRMRENDER_GOURAUD).

참조

Direct3DRMProgressiveMesh.GetRenderQuality

Direct3DRMProgressiveMesh.SetVertexDetail

Direct3DRMProgressiveMesh

요구된 버텍스 상세 레벨을 설정한다.

구문

object. SetVertexDetail(count As Long)

요소

object
Direct3DRMProgressiveMesh오브젝트를 나타내는오브젝트식.
count
요구되고 있는 버텍스의 수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

충분한 상세 항목의 다운로드가, 아직 완료하고 있지 않으면(다만, 시간이 흐르면 사용 가능), 요구는 받아들여져,D3DRMERR_PENDING 가 돌아간다. 이 에러는 통지이며, 요구된 레벨이, 충분한 상세가 사용 가능하게 되면(자) 즉시 설정된다고 하는 것을 나타내는 것이다. 요구되고 있는 상세 레벨이, 프로그래시브 메쉬로 사용 가능한 상세 레벨보다 크면,D3DRMERR_REQUESTTOOLARGE 가 돌아간다.

참조

Direct3DRMProgressiveMesh.GetVertexDetail


Direct3DRMShadow2

어플리케이션은,Direct3DRMShadow2오브젝트를 초기화하기 위해서Direct3DRM3.CreateShadow 인터페이스의 메소드를 사용한다. 이러한 그림자 오브젝트는, 비주얼로서 프레임 계층에 생성 및 추가된다.

Direct3DRMShadow2인터페이스는,Direct3DRMObject 인터페이스로부터 이하의 메소드를 계승한다.
AddDestroyCallback
CloneObject
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMShadow2오브젝트는,Direct3DRM3.CreateShadow 메소드의 사용에 의해 취득된다.


Direct3DRMTexture3

Direct3DRMTexture3인터페이스는, 텍스쳐 관리에 대하는 것보다 세련된 제어를 가능하게 한다. Changed 메소드는, 텍스쳐의 변경 리젼을 지정 가능하게 한다. 또,Direct3DRMTexture3는 텍스쳐 관리 캐싱 메소드의GetCacheFlags ,SetCacheOptions , 및GetCacheImportance 도 제공한다.

GenerateMIPMap 메소드는, 소스 이미지로부터밉맵을 생성한다.

텍스쳐를 생성 할 경우에 불필요한 지연을 피하기 (위해)때문에, 재이용하는 텍스쳐는 보관 유지해 두어, 필요하게 될 때마다 생성 하지 않아도 되도록(듯이) 한다. 최적인 퍼포먼스를 얻으려면 , 사용하는 디바이스의 지원 하는 텍스쳐 표면 포맷을 사용한다. 이것에 의해, 텍스쳐를 생성 하고 나서 변경할 경우에, 수고가 걸리는 포맷 변환을 회피할 수가 있다.

Direct3DRMTexture3인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

색 | GetColors
SetColors
디칼 | GetDecalOrigin
GetDecalScale
GetDecalSize
GetDecalTransparency
GetDecalTransparentColor
SetDecalOrigin
SetDecalScale
SetDecalSize
SetDecalTransparency
SetDecalTransparentColor
밉맵 생성 | GenerateMIPMap
그 외 | GetCacheFlags
GetCacheImportance
GetSurface
SetCacheOptions
렌더러 통지 | Changed
쉐이딩 | GetShades
SetShades

Direct3DRMTexture3인터페이스는,Direct3DRMObject 인터페이스로부터 이하의 메소드를 계승한다.

AddDestroyCallback
CloneObject
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMTexture3오브젝트를 생성 하려면 ,Direct3DRM3.CreateTextureFromSurface 메소드를 호출한다.

Direct3DRMTexture3.Changed

Direct3DRMTexture3

어플리케이션이 텍스쳐의 어느 리젼을 변경하는지를 지정할 수 있도록(듯이) 한다.

구문

object. Changed(flags As CONST_D3DRMTEXTURECHANGEDFLAGS,
  nRects As Long,
  rects() As RECT)

요소

object
Direct3DRMTexture3오브젝트를 나타내는오브젝트식.
flags
텍스쳐의 변경을 나타내는CONST_D3DRMTEXTURECHANGEDFLAGS 열거형의 하나 이상의 값.
nRects
rects중의RECT형의 수. 이 값이 0으로,flags에D3DRMTEXTURE_CHANGEDPIXELS또는D3DRMTEXTURE_INVALIDATEONLY가 포함되는 경우는, 텍스쳐 전체가 갱신된다.
rects
변경된 픽셀의 리젼을 기술하는RECT형의 배열. flags에D3DRMTEXTURE_CHANGEDPIXELS또는D3DRMTEXTURE_INVALIDATEONLY가 포함되는 경우는,rects파라미터만이 유효하다. RECT는, 방형 정의의 형태이다.
Type RECT
  Bottom As Long
  Left As Long
  Right As Long
  Top As Long
End Type

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMTexture3.GenerateMIPMap

Direct3DRMTexture3

단일의 이미지 소스로부터밉맵을 생성한다.

구문

object. GenerateMIPMap( )

요소

object
Direct3DRMTexture3오브젝트를 나타내는오브젝트식.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는, 텍스쳐의 생성 후는 언제라도 호출할 수가 있다. 이 메소드는, 레벨간의 쌍일차 필터링에 의해 소스 이미지의 밉맵을 1×1의 해상도까지 생성할 수 있다. 밉맵이 생성되면(자), 맵은 언제라도 사용 가능해,Direct3DRMTexture3.Changed 를 호출해, 갱신할 수가 있다. MIP Mapping를 사용하는 경우에는,Direct3DRMDevice3.SetTextureQuality 를 사용해, 텍스쳐의 퀄리티를D3DRMTEXTURE_MIPNEAREST,D3DRMTEXTURE_MIPLINEAR,D3DRMTEXTURE_LINEARMIPNEAREST, 또는D3DRMTEXTURE_LINEARMIPLINEAR로 변경하는 것을 잊어서는 안된다. 특별한 밉맵 레벨은, 텍스쳐 퀄리티가 MIP Mapping형을 포함해, 한편 하드웨어 디바이스가 MIP Mapping를 지원 하지 않는 한, 하드웨어 디바이스의 비디오 메모리에 저장 되지 않는다.

Direct3DRMTexture3.GetCacheFlags

Direct3DRMTexture3

텍스쳐 메모리가 제한되고 있는 경우에, 텍스쳐 관리로 현재의 텍스쳐를 어떻게 처리할까에 관한 정보를 취득한다.

구문

object. GetCacheFlags( ) As CONST_D3DRMTEXTURECACHEFLAGS

요소

object
Direct3DRMTexture3오브젝트를 나타내는오브젝트식.

반환값

CONST_D3DRMTEXTURECACHEFLAGS 열거형으로부터 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMTexture3.GetCacheImportance

Direct3DRMTexture3

텍스쳐 메모리가 제한되고 있는 경우에, 텍스쳐의 상대적인 중요도에 관한 정보를 취득한다.

구문

object. GetCacheImportance( ) As Long

요소

object
Direct3DRMTexture3오브젝트를 나타내는오브젝트식.

반환값

텍스쳐의 상대적인 중요도를 나타내는 값을 돌려준다. 디폴트는 0이다. 값이 크면, 중요도가 높은 일을 나타낸다. 이 값을 사용해, 텍스쳐 메모리가 제한되고 있는 경우에 어느 텍스쳐를 마지막으로 다운 샘플 하는지를 계산한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMTexture3.GetColors

Direct3DRMTexture3

Direct3DRMTexture3오브젝트를 렌더링 하기 위해서 사용하는 색의 최대수를 취득한다.

구문

object. GetColors( ) As Long

요소

object
Direct3DRMTexture3오브젝트를 나타내는오브젝트식.

반환값

색 가지수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMTexture3오브젝트가 생성 된 원의 이미지중의 색의 수는 아니고,Direct3DRMTexture3오브젝트가 양자화된 색의 수를 돌려준다. 따라서, 반환값의 색의 수는 보통,Direct3DRM3.SetDefaultTextureColors 메소드를 호출해 설정한 색에 일치한다. 다만,Direct3DRMTexture3.SetColors 메소드를 명시적으로 호출해Direct3DRMTexture3오브젝트의 색을 변경했을 경우는, 그렇게는 안 된다.

Direct3DRMTexture3.GetDecalOrigin

Direct3DRMTexture3

디칼의 현재의 원점을 취득한다.

구문

object. GetDecalOrigin(x As Long,
  y As Long)

요소

object
Direct3DRMTexture3오브젝트를 나타내는오브젝트식.
x, y
디칼의 원점의 x 및 y좌표.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMTexture3.SetDecalOrigin

Direct3DRMTexture3.GetDecalScale

Direct3DRMTexture3

지정의 디칼의 스케일링 프로퍼티를 취득한다.

구문

object. GetDecalScale( ) As CONST_DBOOLFLAGS

요소

object
Direct3DRMTexture3오브젝트를 나타내는오브젝트식.

반환값

디칼을 스케일링 하는 경우에 깊이가 고려될 때는–1을 돌려주어, 디칼이 장면의 프레임 위에의 텍스쳐인 경우는, 뷰아로부터 멀리 있으면 작고, 뷰아의 근처에 있으면 크고 스케일링 된다. 그렇지 않으면, 깊이 정보는 무시되어 디칼은 뷰아로부터의 원근에 관계없이 같은 사이즈가 되어, 0이 돌려주어진다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMTexture3.SetDecalScale

Direct3DRMTexture3.GetDecalSize

Direct3DRMTexture3

디칼의 사이즈를 취득한다.

구문

object. GetDecalSize(w As Single,
  h As Single)

요소

object
Direct3DRMTexture3오브젝트를 나타내는오브젝트식.
w, h
디칼의 폭과 높이.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMTexture3.SetDecalSize

Direct3DRMTexture3.GetDecalTransparency

Direct3DRMTexture3

디칼의 투명 프로퍼티를 취득한다.

구문

object. GetDecalTransparency( ) As CONST_DBOOLFLAGS

요소

object
Direct3DRMTexture3오브젝트를 나타내는오브젝트식.

반환값

디칼이 투명한 색을 가지고 있는 경우는–1, 그렇지 않으면 0을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMTexture3.SetDecalTransparency

Direct3DRMTexture3.GetDecalTransparentColor

Direct3DRMTexture3

디칼의 투명한 색을 취득한다.

구문

object. GetDecalTransparentColor( ) As Long

요소

object
Direct3DRMTexture3오브젝트를 나타내는오브젝트식.

반환값

투명한 색의 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMTexture3.SetDecalTransparentColor

Direct3DRMTexture3.GetShades

Direct3DRMTexture3

렌더링시에 텍스쳐중의 각 색에 대해서 사용되는 쉐이드수를 돌려준다.

구문

object. GetShades( ) As Long

요소

object
Direct3DRMTexture3오브젝트를 나타내는오브젝트식.

반환값

쉐이드수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMTexture3.SetShades

Direct3DRMTexture3.GetSurface

Direct3DRMTexture3

텍스쳐를 생성 하기 위해서 사용한 Microsoft® DirectDraw®표면을 취득한다. 이 메소드는,Direct3DRM3.CreateTextureFromSurface 가 텍스쳐의 생성에 사용되었을 경우에게만, 표면을 취득한다.

구문

object. GetSurface(flags As Long) As DirectDrawSurface4

요소

object
Direct3DRMTexture3오브젝트를 나타내는오브젝트식.
flags
플래그값. 0이 아니면 안된다.

반환값

대응하는DirectDrawSurface4오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMTexture3.SetCacheOptions

Direct3DRMTexture3

텍스쳐 메모리가 제한되고 있는 경우에, 텍스쳐 관리로 현재의 텍스쳐를 어떻게 처리할까에 관한 정보를 제공한다.

구문

object. SetCacheOptions(importance As Long
  CONST_D3DRMTEXTURECACHEFLAGS As Long)

요소

object
Direct3DRMTexture3오브젝트를 나타내는오브젝트식.
importance
텍스쳐의 상대적인 중요도를 나타내는 값. 디폴트는 0이다. 값이 크면, 중요도가 높은 일을 나타낸다. 이 값을 사용해, 텍스쳐 메모리가 제한되고 있는 경우에 어느 텍스쳐를 마지막으로 다운 샘플 하는지를 계산한다.
flags
CONST_D3DRMTEXTURECACHEFLAGS 열거형으로부터의 하나 이상의 값.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMTexture3.SetColors

Direct3DRMTexture3

Direct3DRMTexture3오브젝트를 렌더링 하는데 사용하는 색의 최대수를 설정한다. 이 메소드는, 램프 컬러 모델에 한정해 필요하다.

구문

object. SetColors(c As Long)

요소

object
Direct3DRMTexture3오브젝트를 나타내는오브젝트식.
c
색의 수. 디폴트값은 8이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMTexture3.GetColors

Direct3DRMTexture3.SetDecalOrigin

Direct3DRMTexture3

디칼의 좌상으로부터의 오프셋(offset)로서 디칼의 원점을 설정한다.

구문

object. SetDecalOrigin(x As Long,
  y As Long)

요소

object
Direct3DRMTexture3오브젝트를 나타내는오브젝트식.
x, y
디칼 좌표에서의 디칼의 새로운 원점. 디폴트의 원점은 (0, 0)이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

디칼 원점은, 렌더링시에 그 프레임의 위치에 맵 된다. 예를 들어, 십자의 디칼의 원점은, 디칼의 중점으로 설정되어 아래로 향한 화살표의 원점은, 저변에 따른 중점으로 설정된다.

이 메소드는,Direct3DRMTextureInterpolator 오브젝트에 디칼 원점 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMTexture3.GetDecalOrigin

Direct3DRMTexture3.SetDecalScale

Direct3DRMTexture3

디칼의 스케일링 프로퍼티를 설정한다.

구문

object. SetDecalScale(considerScale As CONST_DBOOLFLAGS)

요소

object
Direct3DRMTexture3오브젝트를 나타내는오브젝트식.
considerScale
디칼의 스케일링시에 깊이 정보를 사용할지 어떨지를 나타내는 값. 이 파라미터가 D_TRUE의 경우, 디칼을 스케일링 하는 경우에 깊이가 고려되어 디칼이 장면의 프레임 위에의 텍스쳐인 경우, 뷰아로부터 멀리 있으면 작고, 뷰아의 근처에 있으면 크고 스케일링 된다. D_FALSE의 경우, 깊이 정보는 무시되어 디칼은 뷰아로부터의 원근에 관계없이 같은 사이즈가 된다. 디폴트값은 D_TRUE이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMTexture3.GetDecalScale

Direct3DRMTexture3.SetDecalSize

Direct3DRMTexture3

장면안의 깊이에 따라 디칼이 스케일링 되는 경우에, 사용되는 디칼의 사이즈를 설정한다.

구문

object. SetDecalSize(width As Single,
  height As Single)

요소

object
Direct3DRMTexture3오브젝트를 나타내는오브젝트식.
width, height
모델 좌표에 있어서의, 디칼의 새로운 폭과 높이. 디폴트 사이즈는,[1, 1]이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMTextureInterpolator 오브젝트에 디칼 사이즈 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMTexture3.GetDecalSize

Direct3DRMTexture3.SetDecalTransparency

Direct3DRMTexture3

디칼의 투명 프로퍼티를 설정한다.

구문

object. SetDecalTransparency(transparencyEnabled As CONST_DBOOLFLAGS)

요소

object
Direct3DRMTexture3오브젝트를 나타내는오브젝트식.
transparencyEnabled
디칼이 투명과 불투명의 어느 쪽의 색을 가지고 있는지를 지정하는 값. D_TRUE로 설정되어 있으면(자) 디칼은 투명의 색을 가져, D_FALSE로 설정되어 있으면(자) 불투명의 색을 가진다. 디폴트는 D_FALSE이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMTexture3.GetDecalTransparency

Direct3DRMTexture3.SetDecalTransparentColor

Direct3DRMTexture3

디칼의 투명한 색을 설정한다.

구문

object. SetDecalTransparentColor(tcolor As Long)

요소

object
Direct3DRMTexture3오브젝트를 나타내는오브젝트식.
tcolor
새로운 투명한 색. 디폴트의 투명한 색은 흑이다. 오브젝트의 색을 알파 요소를 포함해 지정하려면 , 오브젝트 위에의DirectX7인터페이스로부터CreateColorRGBA메소드를 호출한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMTextureInterpolator 오브젝트에 디칼의 투명색키를 추가하기 위해서도 사용한다.

참조

Direct3DRMTexture3.GetDecalTransparentColor

Direct3DRMTexture3.SetShades

Direct3DRMTexture3

렌더링시에,Direct3DRMTexture3 오브젝트의 각 색에 대해서 사용하는 쉐이드의 최대수를 설정한다. 이 메소드는, 램프 컬러 모델에 한정해 필요하다.

구문

object. SetShades(numShades As Long)

요소

object
Direct3DRMTexture3오브젝트를 나타내는오브젝트식.
numShades
새로운 쉐이드수. 이 값은, 2의 거듭제곱이 아니면 안된다. 디폴트값은 16이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMTexture3.GetShades


Direct3DRMTextureInterpolator

인타포레이타는, 액션을 저장 한 후, 중간값을 자동 계산해, 오브젝트에 액션을 적용하는 방법을 제공한다. 인타포레이타를 사용해, 색을 혼합해, 다른 위치간에서 오브젝트를 원활히 이동해, 메쉬를 morphing 해, 게다가 다른 다양한 변환도 실시할 수가 있다.

Direct3DRMTexture3 오브젝트는,Direct3DRMTextureInterpolator오브젝트에 Attach 할 수 있다. 인타포레이타의 상세한 것에 대하여는, 추가 정보의 「인타포레이타」를 참조할것.

Direct3DRMTextureInterpolator인터페이스에는, 다음의 메소드가 포함된다.

오브젝트의 Attach | AttachObject
DetachObject
GetAttachedObjects
색 | SetDecalOrigin
SetDecalSize
SetDecalTransparentColor
보간의 실행 | GetIndex
Interpolate
SetIndex

게다가Direct3DRMTextureInterpolator는,Direct3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.

  • AddDestroyCallback
  • Clone
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMTextureInterpolator.AttachObject

Direct3DRMTextureInterpolator

오브젝트를 인타포레이타에 접속한다.

구문

object. AttachObject(mObject As Direct3DRMObject)

요소

object
Direct3DRMTextureInterpolator오브젝트를 나타내는오브젝트식.
mObject
인타포레이타에 Attach 하는Direct3DRMObject 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

Attach 되는 오브젝트는, 다른 인타포레이타에서도, 인타포레이타가xInterpolator형이 되는 타입x의 오브젝트에서도 좋다. 예를 들어,Direct3DRMTexture3 오브젝트는,Direct3DRMTextureInterpolator오브젝트에 Attach 할 수 있다.

Direct3DRMTextureInterpolator.DetachObject

Direct3DRMTextureInterpolator

인타포레이타로부터 오브젝트의 Attach를 해제한다.

구문

object. DetachObject(mObject As Direct3DRMObject)

요소

object
Direct3DRMTextureInterpolator오브젝트를 나타내는오브젝트식.
mObject
인타포레이타로부터 Attach를 제외하는Direct3DRMObject 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMTextureInterpolator.GetAttachedObjects

Direct3DRMTextureInterpolator

인타포레이타에 현재 Attach 되고 있는 오브젝트를 취득한다.

구문

object. GetAttachedObjects( ) As Direct3DRMObjectArray

요소

object
Direct3DRMTextureInterpolator오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMObjectArray 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMTextureInterpolator.GetIndex

Direct3DRMTextureInterpolator

인타포레이타의 현재의 내부 인덱스(시간)를 취득한다.

구문

object. GetIndex( ) As Single

요소

object
Direct3DRMTextureInterpolator오브젝트를 나타내는오브젝트식.

반환값

인타포레이타의 현재의 내부 인덱스를 포함한 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

인타포레이타에 저장 되고 있는 각 키는, 인덱스값을 가진다. 키를(메소드를 사용해) 기록 하면 와, 키에는, 현재의 인타포레이타의 인덱스값으로 스탬프가 밀린다. 키의 인덱스값은, 스탬프를 밀린 후, 바뀔 것은 없다.

Direct3DRMTextureInterpolator.Interpolate

Direct3DRMTextureInterpolator

인타포레이타에 저장 되고 있는 키간을 보간 해, 일련의 액션을 생성한다. 그 후, 액션은, 지정의 오브젝트에 적용된다. 오브젝트의 지정이 없으면, 액션은, 현재 Attach 되고 있는 오브젝트에 적용된다.

구문

object. Interpolate(val As Single,
  mObject As Direct3DRMObject,
  options As CONST_D3DRMINTERPOLATIONFLAGS)

요소

object
Direct3DRMTextureInterpolator오브젝트를 나타내는오브젝트식.
val
인타포레이타의 현재의 내부 인덱스를 포함한 값.
mObject
Direct3DRMObject 오브젝트. 이 오브젝트는, 인타포레이타에 저장 떠날 수 있어 모든 프로퍼티에 대한 보간값을 할당하는 오브젝트를 나타낸다. 이 포인터는 NOTHING에서도 좋다. 그 경우, 모든 Attach 되고 있는 오브젝트의 프로퍼티값에는, 보간값이 세트 된다.
options
실행하는 보간의 종류를 제어하는CONST_D3DRMINTERPOLATIONFLAGS 열거형

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMTextureInterpolator.SetDecalOrigin

Direct3DRMTextureInterpolator

Direct3DRMTextureInterpolator오브젝트에 디칼 원점 키를 추가한다.

구문

object. SetDecalOrigin(x As Long,
  y As Long)

요소

object
Direct3DRMTextureInterpolator오브젝트를 나타내는오브젝트식.
x, y
디칼 좌표에서의 디칼의 새로운 원점. 디폴트의 원점은 [0, 0]이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMTextureInterpolator.SetDecalSize

Direct3DRMTextureInterpolator

Direct3DRMTextureInterpolator오브젝트에 디칼 사이즈 키를 추가한다.

구문

object. SetDecalSize(width As Single,
  height As Single)

요소

object
Direct3DRMTextureInterpolator오브젝트를 나타내는오브젝트식.
width, height
모델 좌표에 있어서의, 디칼의 새로운 폭과 높이. 디폴트 사이즈는,[1, 1]이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMTextureInterpolator.SetDecalTransparentColor

Direct3DRMTextureInterpolator

Direct3DRMTextureInterpolator오브젝트에 디칼 투명색키를 추가한다.

구문

object. SetDecalTransparentColor(tcolor As Long)

요소

object
Direct3DRMTextureInterpolator오브젝트를 나타내는오브젝트식.
tcolor
새로운 투명한 색. 디폴트의 투명한 색은 흑이다. 오브젝트의 색을 알파 요소를 포함해 지정하려면 , 오브젝트 위에의DirectX7인터페이스로부터CreateColorRGBA메소드를 호출한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMTextureInterpolator.SetIndex

Direct3DRMTextureInterpolator

인타포레이타의 내부 인덱스(시간)로 지정의 값을 세트 한다. 다른 인타포레이타가 그 인타포레이타에 Attach 되고 있으면, 이 메소드는, 재귀적으로 그러한 인덱스를 같은 값에 동기 시킨다.

구문

object. SetIndex(val As Single)

요소

object
Direct3DRMTextureInterpolator오브젝트를 나타내는오브젝트식.
val
인타포레이타의 내부 인덱스에 대해서 세트 되는 시간.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

인타포레이타에 저장 되고 있는 각 키는, 인덱스값을 가진다. 키를(메소드를 사용해) 기록 하면 와, 키에는, 현재의 인타포레이타의 인덱스값으로 스탬프가 밀린다. 키의 인덱스값은, 스탬프를 밀린 후, 바뀔 것은 없다.


Direct3DRMViewport2

어플리케이션은, 뷰포트 오브젝트와 서로 교환하기 위해서Direct3DRMViewport2인터페이스의 메소드를 사용한다. Direct3DRMViewport2는, 무엇을 클리어 하는지를 나타내는 플래그 파라미터를Clear 메소드에 추가한다.

Direct3DRMViewport2인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

카메라 | GetCamera
SetCamera
클리핑 프레인 | GetBack
GetFront
GetPlane
SetBack
SetFront
SetPlane
사이즈 | GetHeight
GetWidth
뷰의 필드 | GetField
SetField
그 외 | Clear
Configure
ForceUpdate
GetDevice
GetDirect3DViewport3
Pick
Render
오프셋(offset) | GetX
GetY
투영 타입 | GetProjection
SetProjection
스케일링 | GetUniformScaling
SetUniformScaling
변환 | InverseTransform
Transform

Direct3DRMViewport2인터페이스는,Direct3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.

  • AddDestroyCallback
  • CloneObject
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMViewport오브젝트는,Direct3DRM3.CreateViewport 메소드의 사용에 의해 취득된다.

Direct3DRMViewport2.Clear

Direct3DRMViewport2

현재의 배경색으로, 지정된 뷰포트를 클리어 한다.

구문

object. Clear(flags As CONST_D3DRMVIEWPORTCLEARFLAGS)

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.
flags
CONST_D3DRMVIEWPORTCLEARFLAGS 열거형의 값의 논리적인 편성.

에러값

에러가 발생했을 경우는,DDERR_INVALIDOBJECT 또는DDERR_INVALIDPARAMS 를 돌려준다.

모든 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMViewport2.Configure

Direct3DRMViewport2

뷰포트의 원점과 사이즈를 재설정한다.

구문

object. Configure(x As Long,
  y As Long,
  width As Long,
  height As Long)

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.
x, y
뷰포트의 새로운 위치.
width, height
뷰포트의 새로운 폭과 높이.

에러값

x + width가 디바이스의 폭보다 큰 경우,y + height가 디바이스의 높이보다 큰 경우, 혹은x,y,width,height의 몇개의 값이 0 이하인 경우, 이 메소드는D3DRMERR_BADVALUE를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMViewport2.ForceUpdate

Direct3DRMViewport2

뷰포트의 영역을 강제적으로 갱신한다. 지정된 영역은, 다음번의Direct3DRMDevice3.Update 메소드의 호출로 스크린에 카피된다.

구문

object. ForceUpdate(x1 As Long,
  y1 As Long,
  x2 As Long,
  y2 As Long)

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.
x1, y1
갱신 영역의 좌상구석.
x2, y2
갱신 영역의 우하구석.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

시스템은, 지정된 직사각형보다 큰 리젼을 갱신하는 일이 있다. 경우에 따라서는, 윈도우 전체가 갱신되는 일도 있다.

Direct3DRMViewport2.GetBack

Direct3DRMViewport2

뷰포트의백 클리핑 프레인의 위치를 취득한다.

구문

object. GetBack( ) As Single

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.

반환값

백 클리핑 프레인과카메라와의 거리를 기술하는 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMViewport2.SetBack

Direct3DRMViewport2.GetCamera

Direct3DRMViewport2

뷰포트의카메라를 취득한다.

구문

object. GetCamera( ) As Direct3DRMFrame3

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.

반환값

카메라를 나타내는Direct3DRMFrame3 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMViewport2.SetCamera

Direct3DRMViewport2.GetDevice

Direct3DRMViewport2

뷰포트와 관련지을 수 있었던 디바이스를 취득한다.

구문

object. GetDevice( ) As Direct3DRMDevice3

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.

반환값

디바이스를 나타내는Direct3DRMDevice3 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMViewport2.GetDirect3DViewport

Direct3DRMViewport2

현재의Direct3DRMViewport2오브젝트에 대응하는 Direct3D 뷰포트를 취득한다.

구문

object. GetDirect3DViewport( ) As Direct3DViewport3

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.

반환값

Direct3DViewport3오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMViewport2.GetField

Direct3DRMViewport2

절두체의 각도를 라디안 단위로 취득한다.

구문

object. GetField( ) As Single

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.

반환값

뷰의 필드를 기술하는 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMViewport2.SetField

Direct3DRMViewport2.GetFront

Direct3DRMViewport2

뷰포트의프런트 클리핑 프레인의 위치를 취득한다.

구문

object. GetFront( ) As Single

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.

반환값

카메라로부터 프런트 클리핑 프레인까지의 거리를 기술하는 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMViewport2.SetFront

Direct3DRMViewport2.GetHeight

Direct3DRMViewport2

뷰포트의 높이를 취득한다.

구문

object. GetHeight( ) As Long

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.

반환값

높이를 픽셀 단위로 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMViewport2.GetPlane

Direct3DRMViewport2

프런트 클리핑 프레인위에의 뷰포트의 사이즈를 취득한다.

구문

object. GetPlane(l As Single,
  r As Single,
  b As Single,
  t As Single)

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.
l, r, b, t
프런트 클리핑 프레인 위에의 뷰포트의 상하 좌우의 사이즈. 사이즈는 픽셀 단위로 기록된다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMViewport2.SetPlane

Direct3DRMViewport2.GetProjection

Direct3DRMViewport2

뷰포트의 투영 타입을 취득한다. 뷰포트에는, 평행 투영과 투시 투영의 어디라도 이용할 수가 있다.

구문

object. GetProjection( ) As CONST_D3DRMPROJECTIONTYPE

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.

반환값

CONST_D3DRMPROJECTIONTYPE 열거형의 멤버의 1 개를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMViewport2.SetProjection

Direct3DRMViewport2.GetUniformScaling

Direct3DRMViewport2

윈도우의 사이즈보다 큰 표시 볼륨을 스케일링 하기 위해서 이용되는, 스케일 특성을 취득한다.

구문

object. GetUniformScaling( ) As Long

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.

반환값

뷰포트가 일정한 비율로 스케일링 되는 경우는–1, 그렇지 않으면 0을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMViewport2.SetUniformScaling

Direct3DRMViewport2.GetWidth

Direct3DRMViewport2

뷰포트의 폭을 취득한다.

구문

object. GetWidth( ) As Long

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.

반환값

폭을 픽셀 단위로 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMViewport2.GetX

Direct3DRMViewport2

디바이스의 위에의 뷰포트 시점의 x오프셋(offset)를 취득한다.

구문

object. GetX( ) As Long

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.

반환값

x오프셋(offset)를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMViewport2.GetY

Direct3DRMViewport2

디바이스의 위에의 뷰포트 시점의 y오프셋(offset)를 취득한다.

구문

object. GetY( ) As Long

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.

반환값

y오프셋(offset)를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMViewport2.InverseTransform

Direct3DRMViewport2

화면 좌표의 지정된 벡터를월드 좌표로 변환해, 결과를 돌려준다.

구문

object. InverseTransform(d As D3DVECTOR,
  s As D3DRMVECTOR4D)

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.
d
메소드가 값을 돌려줄 때 처리 결과를 받는D3DVECTOR 형.
s
처리의 소스를 나타내는D3DRMVECTOR4D 형.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMViewport2.Pick

Direct3DRMViewport2

깊이에 의해 분류된 오브젝트(관련이 있으면 면도)의 리스트를 찾아낸다. 취득한 배열에는, 루트로부터 오브젝트를 포함한 프레임에 도달할 때까지의 계층 패스가 저장 된다.

구문

object. Pick(x As Long,
  y As Long) As Direct3DRMPickArray

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.
x, y
피킹에 사용되는 x 및 y좌표.

반환값

호출이 성공하면(자),Direct3DRMPickArray 인터페이스를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMViewport2.Render

Direct3DRMViewport2

프레임 계층을, 지정된 뷰포트에 렌더링 한다. 지정된 프레임 위에의 비주얼과 그 아래의 계층의 프레임만이 렌더링 된다.

구문

object. Render(rootFrame As Direct3DRMFrame3)

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.
rootFrame
렌더링 하는 프레임 계층을 나타내는Direct3DRMFrame3 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

이 메소드는, 오른손 지원을 나타내는데Direct3DRM3.SetOptions 메소드를 사용하려고 하거나 동시에 오른손 지원을 제공하는 낡은 방법 (Direct3DRMViewport2.SetProjection )을 사용하면(자), 에러를 돌려준다.

Direct3DRMViewport2.SetBack

Direct3DRMViewport2

뷰포트의백 클리핑 프레인의 위치를 설정한다.

구문

object. SetBack(v As Single)

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.
v
카메라와 백 클리핑 프레인의 사이의 거리. 디폴트값은 100.0이다. 적정한 값은 그 외의 절두체 설정에 의존한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMViewportInterpolator 오브젝트에 백 클리핑 프레인의 위치 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMViewport2.GetBack ,Direct3DRMViewport2.SetFront

Direct3DRMViewport2.SetCamera

Direct3DRMViewport2

카메라를 뷰포트로 설정한다.

구문

object. SetCamera(f As Direct3DRMFrame3)

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.
f
카메라를 나타내는Direct3DRMFrame3 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는, 뷰포트의 위치, 방향, 방향이 지정된 카메라 프레임과 같게 설정한다. 뷰는, 카메라 프레임의 정의 z축방향에 따라, 정의 y축의 윗방향으로 향해진다.

참조

Direct3DRMViewport2.GetCamera

Direct3DRMViewport2.SetField

Direct3DRMViewport2

절두체의 각도를 라디안 단위로 설정한다.

구문

object. SetField(v As Single)

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.
v
뷰의 새로운 필드. 이 값은 시각의 끝수이다. 디폴트값은 0.5이다. 이 값에 0 이하를 지정 하면, 이 메소드는D3DRMERR_BADVALUE에러를 돌려준다. 시각은, 프런트 클리핑 프레인의 arctangent의 2배 나누는 카메라로부터의 거리로서 정의된다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMViewportInterpolator 오브젝트에 뷰의 필드 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMViewport2.GetField

Direct3DRMViewport2.SetFront

Direct3DRMViewport2

뷰포트의프런트 클리핑 프레인의 위치를 설정한다.

구문

object. SetFront(v As Single)

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.
v
카메라로부터 프런트 클리핑 프레인까지의 거리. 디폴트값은 1.0이다. 적정한 값은 그 외의 절두체 설정에 의존한다.

에러값

0 이하의 값이 건네받으면(자), 이 메소드는D3DRMERR_BADVALUE에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMViewportInterpolator 오브젝트에 프런트 클리핑 프레인 위치 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMViewport2.GetFront

Direct3DRMViewport2.SetPlane

Direct3DRMViewport2

카메라의 z축으로 대하는 뷰포트의 사이즈를프런트 클리핑 프레인으로 설정한다.

구문

object. SetPlane(Left As Single,
  Right As Single,
  Bottom As Single,
  Top As Single)

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.
Left, Right, Bottom, Top
뷰포트의 최소의 x좌표 , 최대의 x좌표, 최소의 y좌표, 최대의 y좌표.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

중앙에 조정된 뷰포트를 지정하는Direct3DRMViewport2.SetField 메소드와 달리, 이 메소드에 의해, 임의의 비율과 위치의 뷰포트를 지정할 수가 있다. 예를 들어, 분리한절두체를 구축해, 우목이나 좌목의 스테레오 뷰를 인플리맨트 할 수가 있다.

이 메소드는,Direct3DRMViewportInterpolator 오브젝트에 프레인 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMViewport2.GetPlane

Direct3DRMViewport2.SetProjection

Direct3DRMViewport2

뷰포트에 투영 타입을 설정한다.

구문

object. SetProjection(val As CONST_D3DRMPROJECTIONTYPE)

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.
val
CONST_D3DRMPROJECTIONTYPE 열거형의 멤버의 하나.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

Direct3DRM3.SetOptions 를 사용해 오른손 지오메트리를 지정한다.

참조

Direct3DRMViewport2.GetProjection

Direct3DRMViewport2.SetUniformScaling

Direct3DRMViewport2

표시 볼륨을 윈도우의 사이즈보다 크고 스케일링 할 경우에 이용되는, 스케일 특성을 설정한다.

구문

object. SetUniformScaling(flag As CONST_DBOOLFLAGS)

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.
flag
새로운 스케일 특성. 이 파라미터에 D_TRUE를 지정 하면, 수평 방향과 수직 방향으로 같은 스케일 계수가 사용된다. 반대로, 파라미터에 D_FALSE가 설정되어 있으면(자), 표시 볼륨을 윈도우에 일치시키기 (위해)때문에, 다른 스케일 계수가 이용된다. 디폴트의 설정은 D_TRUE이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

보통 이 메소드는, 밴딩을 지원 하기 위해서Direct3DRMViewport2.SetPlane 메소드와 함께 사용된다.

참조

Direct3DRMViewport2.GetUniformScaling

Direct3DRMViewport2.Transform

Direct3DRMViewport2

월드 좌표의 지정된 벡터를 화면 좌표로 변환해, 결과를 돌려준다.

구문

object. Transform(d As D3DRMVECTOR4D,
  s As D3DVECTOR)

요소

object
Direct3DRMViewport2오브젝트를 나타내는오브젝트식.
d
변환 조작의 출력처가 되는D3DRMVECTOR4D 형.
s
변환 처리의 소스가 되는D3DVECTOR 형.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

변환 결과에는, 4 요소의 동종의 벡터가 돌려주어진다. 이하의 방정식이 진이면, 결과의 벡터가 가리키는포인트는 가시 상태이다.

포인트가 가시 상태인가 어떤가를 테스트하는 (분)편 정도식

참조

Direct3DRMViewport2.InverseTransform


Direct3DRMViewportArray

어플리케이션은, 뷰포트 오브젝트를 그룹화 하기 위해서Direct3DRMViewportArray인터페이스의 메소드를 이용한다. 뷰포트의 배열은, 0이 기준이 되어 있다 (0~N-1).

Direct3DRMViewportArray인터페이스는 다음의 메소드를 지원 한다.
GetElement
GetSize

Direct3DRMViewportArray오브젝트는,Direct3DRMDevice3.GetViewports 메소드의 호출에 의해 취득된다.

Direct3DRMViewportArray.GetElement

Direct3DRMViewportArray

Direct3DRMViewportArray오브젝트로부터 지정된 요소를 취득한다.

구문

object. GetElement(index As Long) As Direct3DRMViewport2

요소

object
Direct3DRMViewportArray오브젝트를 나타내는오브젝트식.
index
배열 요소.

반환값

Direct3DRMViewport2 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMViewportArray.GetSize

Direct3DRMViewportArray

Direct3DRMViewportArray오브젝트에 포함되어 있는 요소수를 취득한다.

구문

object. GetSize( ) As Long

요소

object
Direct3DRMViewportArray오브젝트를 나타내는오브젝트식.

반환값

요소수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.


Direct3DRMViewportInterpolator

인타포레이타는, 액션을 저장 한 후, 중간값을 자동 계산해, 오브젝트에 액션을 적용하는 방법을 제공한다. 인타포레이타를 사용해, 색을 혼합해, 다른 위치간에서 오브젝트를 원활히 이동해, 메쉬를 morphing 해, 게다가 다른 다양한 변환도 실시할 수가 있다.

Direct3DRMViewport2 오브젝트는,Direct3DRMViewportInterpolator오브젝트에 Attach 할 수 있다. 인타포레이타의 상세한 것에 대하여는, 추가 정보의 「인타포레이타」를 참조할것.

Direct3DRMViewportInterpolator인터페이스에는 다음의 메소드가 포함된다.

오브젝트의 Attach | AttachObject
DetachObject
GetAttachedObjects
클리핑 프레인 | SetBack
SetFront
뷰의 필드 | SetField
보간의 실행 | GetIndex
Interpolate
SetIndex

게다가Direct3DRMViewportInterpolator는,Direct3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.

  • AddDestroyCallback
  • Clone
  • DeleteDestroyCallback
  • GetAppData
  • GetClassName
  • GetName
  • SetAppData
  • SetName

Direct3DRMViewportInterpolator.AttachObject

Direct3DRMViewportInterpolator

오브젝트를 인타포레이타에 접속한다.

구문

object. AttachObject(mObject As Direct3DRMObject)

요소

object
Direct3DRMViewportInterpolator오브젝트를 나타내는오브젝트식.
mObject
인타포레이타에 Attach 하는Direct3DRMObject 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

Attach 되는 오브젝트는, 다른 인타포레이타에서도, 인타포레이타가xInterpolator형이 되는 타입x의 오브젝트에서도 좋다. 예를 들어,Direct3DRMViewport2 오브젝트는,Direct3DRMViewportInterpolator오브젝트에 Attach 할 수 있다.

Direct3DRMViewportInterpolator.DetachObject

Direct3DRMViewportInterpolator

인타포레이타로부터 오브젝트의 Attach를 해제한다.

구문

object. DetachObject(mObject As Direct3DRMObject)

요소

object
Direct3DRMViewportInterpolator오브젝트를 나타내는오브젝트식.
mObject
인타포레이타로부터 Attach를 제외하는Direct3DRMObject 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMViewportInterpolator.GetAttachedObjects

Direct3DRMViewportInterpolator

인타포레이타에 현재 Attach 되고 있는 오브젝트를 취득한다.

구문

object. GetAttachedObjects( ) As Direct3DRMObjectArray

요소

object
Direct3DRMViewportInterpolator오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMObjectArray 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMViewportInterpolator.GetIndex

Direct3DRMViewportInterpolator

인타포레이타의 현재의 내부 인덱스(시간)를 취득한다.

구문

object. GetIndex( ) As Single

요소

object
Direct3DRMViewportInterpolator오브젝트를 나타내는오브젝트식.

반환값

인타포레이타의 현재의 내부 인덱스를 포함한 값을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

인타포레이타에 저장 되고 있는 각 키는, 인덱스값을 가진다. 키를(메소드를 사용해) 기록 하면 와, 키에는, 현재의 인타포레이타의 인덱스값으로 스탬프가 밀린다. 키의 인덱스값은, 스탬프를 밀린 후, 바뀔 것은 없다.

Direct3DRMViewportInterpolator.Interpolate

Direct3DRMViewportInterpolator

인타포레이타에 저장 되고 있는 키간을 보간 해, 일련의 액션을 생성한다. 그 후, 액션은, 지정의 오브젝트에 적용된다. 오브젝트의 지정이 없으면, 액션은, 현재 Attach 되고 있는 오브젝트에 적용된다.

구문

object. Interpolate(val As Single,
  mObject As Direct3DRMObject,
  options As CONST_D3DRMINTERPOLATIONFLAGS)

요소

object
Direct3DRMViewportInterpolator오브젝트를 나타내는오브젝트식.
val
인타포레이타의 현재의 내부 인덱스를 포함한 값.
mObject
Direct3DRMObject 오브젝트. 이 오브젝트는, 인타포레이타에 저장 떠날 수 있어 모든 프로퍼티에 대한 보간값을 할당하는 오브젝트를 나타낸다. 이 포인터는 NOTHING에서도 좋다. 그 경우, 모든 Attach 되고 있는 오브젝트의 프로퍼티값에는, 보간값이 세트 된다.
options
실행하는 보간의 종류를 제어하는CONST_D3DRMINTERPOLATIONFLAGS 열거형의 값의 하나.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMViewportInterpolator.SetBack

Direct3DRMViewportInterpolator

Direct3DRMViewportInterpolator오브젝트에 백 클리핑 프레인의 위치 키를 추가한다.

구문

object. SetBack(v As Single)

요소

object
Direct3DRMViewportInterpolator오브젝트를 나타내는오브젝트식.
v
카메라와 백 클리핑 프레인의 사이의 거리. 디폴트값은 100.0이다. 적정한 값은 그 외의 절두체 설정에 의존한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMViewportInterpolator.SetField

Direct3DRMViewportInterpolator

Direct3DRMViewportInterpolator오브젝트에 뷰의 필드 키를 추가한다.

구문

object. SetField(v As Single)

요소

object
Direct3DRMViewportInterpolator오브젝트를 나타내는오브젝트식.
v
뷰의 새로운 필드. 이 값은 시각의 끝수이다. 디폴트값은 0.5이다. 이 값에 0 이하를 지정 하면, 이 메소드는D3DRMERR_BADVALUE에러를 돌려준다. 시각은, 프런트 클리핑 프레인의 arctangent의 2배 나누는 카메라로부터의 거리로서 정의된다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMViewportInterpolator.SetFront

Direct3DRMViewportInterpolator

Direct3DRMViewportInterpolator오브젝트에 프런트 클리핑 프레인 위치 키를 추가한다.

구문

object. SetFront(v As Single)

요소

object
Direct3DRMViewportInterpolator오브젝트를 나타내는오브젝트식.
v
카메라로부터 프런트 클리핑 프레인까지의 거리. 디폴트값은 1.0이다. 적정한 값은 그 외의 절두체 설정에 의존한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMViewportInterpolator.SetIndex

Direct3DRMViewportInterpolator

인타포레이타의 내부 인덱스(시간)로 지정의 값을 세트 한다. 다른 인타포레이타가 그 인타포레이타에 Attach 되고 있으면, 이 메소드는, 재귀적으로 그러한 인덱스를 같은 값에 동기 시킨다.

구문

object. SetIndex(val As Single)

요소

object
Direct3DRMViewportInterpolator오브젝트를 나타내는오브젝트식.
val
인타포레이타의 내부 인덱스에 대해서 세트 되는 시간.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

인타포레이타에 저장 되고 있는 각 키는, 인덱스값을 가진다. 키를(메소드를 사용해) 기록 하면 와, 키에는, 현재의 인타포레이타의 인덱스값으로 스탬프가 밀린다. 키의 인덱스값은, 스탬프를 밀린 후, 바뀔 것은 없다.


Direct3DRMVisual

Direct3DRMVisual는, Microsoft® Direct3D® 보관 유지 모드 메소드를 아무것도 제공하지 않지만, 비주얼 오브젝트의 인터페이스는Direct3DRMVisual인터페이스로부터 나타난다.

비주얼은, 장면상에 렌더링 할 수 있는 오브젝트이다. 비주얼이 가시가 되는 것은, 그 장면의 프레임에 추가되었을 경우뿐이다. 어플리케이션은,Direct3DRMFrame3.AddVisual 메소드를 사용해, 비주얼을 프레임에 추가할 수가 있다. 프레임은, 비주얼에 렌더링을 위한 위치와 방향을 제공한다.

비주얼은, 이하의 코드로부터 캐스트 할 수 있다.

Sub test(visual As Direct3DRMVisual)
    Dim mb As Direct3DRMMeshBuilder3
    Dim mesh As Direct3DRMMesh
    Dim pmesh As Direct3DRMProgressiveMesh
    Dim shadow As Direct3DRMShadow2

    Select Case UCase(visual.GetClassName())
        Case "MESHBUILDER"
            Set mb = visual
        Case "MESH"
            Set mesh = visual
        Case "PROGRESSIVEMESH"
            Set pmesh = visual
        Case "SHADOW"
            Set shadow = visual
    End Select

    '목적의 코드를 추가

End Sub

이하의 인터페이스는,Direct3DRMVisual오브젝트로부터 나타난다.

  • Direct3DRMFrame3
  • Direct3DRMMesh
  • Direct3DRMProgressiveMesh
  • Direct3DRMShadow2
  • Direct3DRMTexture3


Direct3DRMVisualArray

어플리케이션은,Direct3DRMVisualArray인터페이스의 메소드를 이용해비주얼 오브젝트를 그룹화 한다. 비주얼의 배열은, 0이 기준이 되어 있다 (0~N-1).

비주얼은, 장면상에 렌더링 할 수 있는 오브젝트이다. 비주얼이 가시가 되는 것은, 그 장면의 프레임에 추가되었을 경우뿐이다. 어플리케이션은,Direct3DRMFrame3.AddVisual 메소드를 사용해, 비주얼을 프레임에 추가할 수가 있다. 프레임은, 비주얼에 렌더링을 위한 위치와 방향을 제공한다.

가장 일반적인 비주얼 타입은,Direct3DRMMeshBuilder3 와Direct3DRMTexture3 오브젝트이다.

Direct3DRMVisualArray인터페이스는 다음의 메소드를 지원 한다.
GetElement
GetSize

Direct3DRMVisualArray오브젝트는,Direct3DRMFrame3.GetVisuals 메소드의 호출에 의해 취득된다.

Direct3DRMVisualArray.GetElement

Direct3DRMVisualArray

Direct3DRMVisualArray오브젝트로부터 지정된 요소를 취득한다.

구문

object. GetElement(index As Long) As Direct3DRMVisual

요소

object
Direct3DRMVisualArray오브젝트를 나타내는오브젝트식.
index
배열 요소.

반환값

단일의Direct3DRMVisual 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMVisualArray.GetSize

Direct3DRMVisualArray

Direct3DRMVisualArray오브젝트에 포함되어 있는 요소수를 취득한다.

구문

object. GetSize( ) As Long

요소

object
Direct3DRMVisualArray오브젝트를 나타내는오브젝트식.

반환값

요소수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.


Direct3DRMWrap

어플리케이션은, 랩 오브젝트와 교환하기 위해서Direct3DRMWrap인터페이스의 메소드를 사용한다. 이 섹션은, 이 인터페이스 메소드의 레퍼런스이다.

Direct3DRMWrap인터페이스는, 이하의 메소드를 지원 한다.

  • Apply
  • ApplyRelative

Direct3DRMWrap인터페이스는,Direct3DRMObject 인터페이스로부터 다음의 메소드를 계승한다.
AddDestroyCallback
CloneObject
DeleteDestroyCallback
GetAppData
GetClassName
GetName
SetAppData
SetName

Direct3DRMWrap오브젝트는,Direct3DRM3.CreateWrap 메소드의 사용에 의해 취득된다.

Direct3DRMWrap.Apply

Direct3DRMWrap

Direct3DRMWrap오브젝트를 그 출력처 오브젝트에 적용한다. 일반적으로 출력처 오브젝트는, 면 또는 메쉬이다.

구문

object. Apply(visual As Direct3DRMObject)

요소

object
Direct3DRMWrap오브젝트를 나타내는오브젝트식.
visual
출력처오브젝트 .

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRM3.CreateWrap

Direct3DRMWrap.ApplyRelative

Direct3DRMWrap

오브젝트의 버텍스에 랩을 설정한다. 최초로 각 버텍스에 프레임의 월드 변환을 실시해, 다음에 랩의 참조 프레임의 역월드 변환을 설정한다.

구문

object. ApplyRelative(f As Direct3DRMFrame3,
  visual As Direct3DRMObject)

요소

object
Direct3DRMWrap오브젝트를 나타내는오브젝트식.
f
랩핑 하는 오브젝트를 포함한Direct3DRMFrame 오브젝트.
visual
적용하는오브젝트 .

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRM3.CreateWrap


Visual Basic 열거형

Microsoft® Direct3D® 보관 유지 모드의 Microsoft Visual Basic® 열거형은, 다음과 같다.

  • CONST_D3DRMADDFACESFLAGS
  • CONST_D3DRMADDMESHBUILDERFLAGS
  • CONST_D3DRMADDTRIANGLESFLAGS
  • CONST_D3DRMADDTRIANGLESVT
  • CONST_D3DRMANIMATIONFLAGS
  • CONST_D3DRMCALLBACKORDERFLAGS
  • CONST_D3DRMCOLORSOURCE
  • CONST_D3DRMCOMBINETYPE
  • CONST_D3DRMCREATEDEVICEFLAGS
  • CONST_D3DRMFOGMETHOD
  • CONST_D3DRMFOGMODE
  • CONST_D3DRMFPTFFLAGS
  • CONST_D3DRMFRAMECONSTRAINT
  • CONST_D3DRMGENERATENORMALSFLAGS
  • CONST_D3DRMHANDEDNESS
  • CONST_D3DRMINTERPOLATIONFLAGS
  • CONST_D3DRMLIGHTTYPE
  • CONST_D3DRMLOADFLAGS
  • CONST_D3DRMMAPPINGFLAGS
  • CONST_D3DRMMATERIALMODE
  • CONST_D3DRMMATERIALOVERRIDEFLAGS
  • CONST_D3DRMMESHBUILDERAGEFLAGS
  • CONST_D3DRMMESHBUILDERENABLEFLAGS
  • CONST_D3DRMPALETTEFLAGS
  • CONST_D3DRMPARENTINGFLAGS
  • CONST_D3DRMPMESHEVENTFLAGS
  • CONST_D3DRMPMESHSTATUSFLAGS
  • CONST_D3DRMPROJECTIONTYPE
  • CONST_D3DRMRAYPICKFLAGS
  • CONST_D3DRMRENDERMODEFLAGS
  • CONST_D3DRMRENDERQUALITY
  • CONST_D3DRMSAVEFLAGS
  • CONST_D3DRMSORTMODE
  • CONST_D3DRMSTATECHANGEFLAGS
  • CONST_D3DRMTEXTURECACHEFLAGS
  • CONST_D3DRMTEXTURECHANGEDFLAGS
  • CONST_D3DRMTEXTUREQUALITY
  • CONST_D3DRMTRAVERALFLAGS
  • CONST_D3DRMVIEWPORTCLEARFLAGS
  • CONST_D3DRMWIREFRAMEFLAGS
  • CONST_D3DRMWRAPTYPE
  • CONST_D3DRMXOFFORMAT
  • CONST_D3DRMZBUFFERMODE

CONST_D3DRMADDFACESFLAGS

법선 인덱스의 처리 방법을 나타낸다.

구문

Enum CONST_D3DRMADDFACESFLAGS
  D3DRMADDFACES_DEFAULT
  D3DRMADDFACES_VERTICESONLY
End Enum

값

D3DRMADDFACES_DEFAULT
기존의 법선의 인덱스가 사용된다.
D3DRMADDFACES_VERTICESONLY
대응하는 인덱스를 가지는 법선이 각 버텍스에 대해서 자동적으로 사용된다.

CONST_D3DRMADDMESHBUILDERFLAGS

카피의 옵션을 나타낸다.

구문

Enum CONST_D3DRMADDMESHBUILDERFLAGS
  D3DRMADDMESHBUILDER_DONTCOPYAPPDATA  = 1
  D3DRMADDMESHBUILDER_FLATTENSUBMESHES = 2
  D3DRMADDMESHBUILDER_NOSUBMESHES      = 4
End Enum

값

D3DRMADDMESHBUILDER_DONTCOPYAPPDATA
디폴트에서는,Direct3DRMMeshBuilder3.AddMeshBuilder 는, 소스 메쉬 빌더의 어플리케이션 데이터를 출력 먼저 카피한다. D3DRMADDMESHBUILDER_DONTCOPYAPPDATA를 지정 하면, 이것이 방지된다.
D3DRMADDMESHBUILDER_FLATTENSUBMESHES
서브 메쉬 오브젝트가 중복 하지 않게 한다. 이러한 면은 여전히 카피 가능하지만, 출력처 메쉬 빌더의 톱 레벨 에 대해서만이다.
D3DRMADDMESHBUILDER_NOSUBMESHES
서브 메쉬 빌더를 무시하도록(듯이) 한다.

CONST_D3DRMADDTRIANGLESFLAGS

새롭게 형성된 삼각형의 옵션을 나타낸다.

구문

Enum CONST_D3DRMADDTRIANGLESFLAGS
  D3DRMVERTEX_STRIP = 1
  D3DRMVERTEX_FAN   = 2
  D3DRMVERTEX_LIST  = 4
End Enum

값

D3DRMVERTEX_STRIP
이전의 2개의 버텍스를 가지는 새로운 삼각형을 작은 조각 포맷으로 형성한다.
D3DRMVERTEX_FAN
이전의 버텍스와 부채의 최초의 버텍스를 가지는 새로운 삼각형을 형성한다.
D3DRMVERTEX_LIST
새로운 리스트를 시작 하는지, 또는 이전에 시작 한 리스트의 멤버이다. 이전의 버텍스 (또는 그 전의 버텍스)에 이 플래그의 마크가 뒤따르지 않은 경우, 최저 1개의 삼각형이 형성될 때까지, 다음의 버텍스에 이 플래그의 마크가 뒤따르지 않으면 안 된다.

CONST_D3DRMADDTRIANGLESVT

각 요소의 기술에 포함하는 메소드를 나타낸다.

구문

Enum CONST_D3DRMADDTRIANGLESVT
  D3DRMFVF_TYPE          = 1
  D3DRMFVF_NORMAL        = 2
  D3DRMFVF_COLOR         = 4
  D3DRMFVF_TEXTURECOORDS = 8
End Enum

값

D3DRMFVF_TYPE
CONST_D3DRMADDTRIANGLESFLAGS 열거형으로부터의 값.
D3DRMFVF_NORMAL
normal멤버를 포함한다.
D3DRMFVF_COLOR
color멤버를 포함한다.
D3DRMFVF_TEXTURECOORDS
tu및tv멤버를 포함한다.

CONST_D3DRMANIMATIONFLAGS

애니메이션 옵션을 설정한다.

구문

Enum CONST_D3DRMANIMATIONFLAGS
  D3DRMANIMATION_OPEN             = 1
  D3DRMANIMATION_CLOSED           = 2
  D3DRMANIMATION_LINEARPOSITION   = 4
  D3DRMANIMATION_SPLINEPOSITION   = 8
  D3DRMANIMATION_SCALEANDROTATION = 16 (&H10)
  D3DRMANIMATION_POSITION         = 32 (&H20)
End Enum

값

D3DRMANIMATION_OPEN
애니메이션은 1회만 재생되어 정지한다.
D3DRMANIMATION_CLOSED
애니메이션은 반복해 재생되어 종점에 이르면(자) 시작점에 돌아와 루프 한다. 닫혀진 애니메이션에서는, 종점으로부터 시작점에 매끄럽게 천이 시키고 싶은 경우, 애니메이션의 마지막 키는 최초의 키의 반복이 아니면 안 된다. 이 반복 키를 이용해, 루프 하는 애니메이션에 있어서의 최후와 최초의 키간의 시간의 차이가 나타내진다. 그러나, 마지막 키가 최초의 키의 반복이 아닌 경우, 새로운 인터페이스 (Direct3DRMAnimation2 ,Direct3DRMAnimationSet2 )로, 이것은 무시되지 않게 된다. 이것은 효과를 낳아, 애니메이션은 즉시에 시작점에 돌아온다.
D3DRMANIMATION_LINEARPOSITION
애니메이션의 위치는 선형으로 설정된다.
D3DRMANIMATION_SPLINEPOSITION
애니메이션의 위치는 스플라인으로 설정된다.
D3DRMANIMATION_SCALEANDROTATION
애니메이션의 스케일과 회전 행렬에 의해, 다른 메소드가 설정하는 어떤 변환 행렬도 덧쓰기된다.
D3DRMANIMATION_POSITION
애니메이션의 위치 행렬에 의해, 다른 메소드가 설정하는 어떤 변환 행렬도 상서된다.

CONST_D3DRMCALLBACKORDERFLAGS

프레임의 콜백을, 아이 프레임을 더듬기 전과 후의 어느 쪽으로 사용하는지를 지정하기 위해서,Direct3DRMFrame3.AddMoveCallback 메소드에 의해 사용된다.

구문

Enum CONST_D3DRMCALLBACKORDERFLAGS
  D3DRMCALLBACK_PREORDER
  D3DRMCALLBACK_POSTORDER
End Enum

값

D3DRMCALLBACK_PREORDER
디폴트값. Direct3DRMFrame3.Move 메소드가 계층을 더듬어 갈 때, 프레임의 콜백은 아이 프레임을 더듬기 전에 불려 간다.
D3DRMCALLBACK_POSTORDER
Move가 계층을 더듬어 갈 때, 프레임의 콜백은 아이 프레임을 더듬은 후에 불려 간다.

CONST_D3DRMCOLORSOURCE

Direct3DRMMeshBuilder3 오브젝트의 컬러 소스를 기술한다. 컬러 소스를 설정하려면 ,Direct3DRMMeshBuilder3.SetColorSource 메소드를 사용한다. 컬러 소스를 취득하려면 ,Direct3DRMMeshBuilder3.GetColorSource 메소드를 사용한다.

구문

Enum CONST_D3DRMCOLORSOURCE
  D3DRMCOLOR_FROMFACE
  D3DRMCOLOR_FROMVERTEX
End Enum

값

D3DRMCOLOR_FROMFACE
오브젝트의 컬러 소스는 면이다.
D3DRMCOLOR_FROMVERTEX
오브젝트의 컬러 소스는 버텍스이다.

CONST_D3DRMCOMBINETYPE

2개의 행렬의 합성 방법을 지정한다.

구문

Enum CONST_D3DRMCOMBINETYPE
  D3DRMCOMBINE_REPLACE
  D3DRMCOMBINE_BEFORE
  D3DRMCOMBINE_AFTER
End Enum

값

D3DRMCOMBINE_REPLACE
주어진 행렬에 의해, 프레임의 현재의 행렬을 옮겨놓는다.
D3DRMCOMBINE_BEFORE
주어진 행렬과 프레임의 현재의 행렬의 적을 요구한다. 계산에 대해서는, 주어진 행렬이 현재의 행렬보다 먼저 지정된다.
D3DRMCOMBINE_AFTER
주어진 행렬과 프레임의 현재의 행렬의 적을 요구한다. 계산에 대해서는, 주어진 행렬이 현재의 행렬의 뒤로 지정된다.

주의

행렬의 곱셈은 가환은 아니기 때문에, 주어진 행렬과 현재의 행렬을 곱하는 순서는 중요하다.

참조

Direct3DRMFrame3.AddRotation ,Direct3DRMFrame3.AddScale ,Direct3DRMFrame3.AddTransform ,Direct3DRMFrame3.AddTranslation

CONST_D3DRMCREATEDEVICEFLAGS

Direct3DRMDevice3 오브젝트의 생성시에 옵션을 정의한다.

구문

Enum CONST_D3DRMCREATEDEVICEFLAGS
  D3DRMDEVICE_DEFAULT
  D3DRMDEVICE_NOZBUFFER
End Enum

값

D3DRMDEVICE_DEFAULT
디폴트의 옵션을 사용한다.
D3DRMDEVICE_NOZBUFFER
Z버퍼는 무효이다.

CONST_D3DRMFOGMETHOD

현재의 포그(안개:fog) 메소드를 나타낸다.

구문

Enum CONST_D3DRMFOGMETHOD
  D3DRMFOGMETHOD_VERTEX = 1
  D3DRMFOGMETHOD_TABLE  = 2
  D3DRMFOGMETHOD_ANY    = 4
End Enum

값

D3DRMFOGMETHOD_VERTEX
버텍스 포그(안개:fog)를 사용한다.
D3DRMFOGMETHOD_TABLE
테이블 포그(안개:fog)를 사용한다.
D3DRMFOGMETHOD_ANY
Direct3D 보관 유지 모드가 적용 가능한 메소드를 선택한다.

CONST_D3DRMFOGMODE

카메라로부터의 거리가 퍼지는 것에 따라, 포그(안개:fog) 효과가 어느 정도의 속도로 어떻게 강해지는지를 나타낸다.

흑백(램프) 라이팅 모드에서는, 포그(안개:fog)는, 그 색이 흑의 경우에 정상적으로 기능한다(라이팅이 없는 경우에는, 어느 포그(안개:fog)의 색으로도 일한다. 그 경우에는, 모든 포그(안개:fog)의 색이 실제적으로는 흑이 되기 때문이다).

구문

Enum CONST_D3DRMFOGMODE
  D3DRMFOG_LINEAR
  D3DRMFOG_EXPONENTIAL
  D3DRMFOG_EXPONENTIALSQUARED
End Enum

값

D3DRMFOG_LINEAR
포그(안개:fog) 효과는, 시점에서 종점까지의 사이에 비례적으로 강해진다. 다음의 공식에서 나타내진다.

거리에 대한 포그(안개:fog) 효과의 비례 증가를 나타내는 공식

현재 지원 되고 있는 포그(안개:fog) 모드는, 이만큼이다.

D3DRMFOG_EXPONENTIAL
포그(안개:fog) 효과는, 지수함수적으로 강해진다. 다음의 공식에서 나타내진다.

거리에 대한 포그(안개:fog) 효과의 지수 증가를 나타내는 공식

D3DRMFOG_EXPONENTIALSQUARED
포그(안개:fog) 효과는, 거리의 2승 에 비례해 지수함수적으로 강해진다. 다음의 공식에서 나타내진다.

거리의2승에 대한 포그(안개:fog) 효과의 지수 증가를 나타내는 공식

주의

포그(안개:fog)는 시야의 기준이라고 보여지는 것에 주의하지 않으면 안 된다. 방정식의 하나로부터 요구되는 포그(안개:fog)값이 낮을 정도(수록), 오브젝트는 보이기 어려워진다.

포그(안개:fog)의 밀도, 시점, 종점은,Direct3DRMFrame3.SetSceneFogParams 메소드에 의해 지정할 수가 있다. 지수 포그(안개:fog) 모드의 방정식에서는,e는 자연대수의 바닥을 나타내, 그 값은 약 2.71828이다.

참조

Direct3DRMFrame3.SetSceneFogMode

CONST_D3DRMFPTFFLAGS

돌려주어지는 텍스쳐 포맷의 옵션을 설정한다.

구문

Enum CONST_D3DRMFPTFFLAGS
  D3DRMFPTF_ALPHA         = 1
  D3DRMFPTF_NOALPHA       = 2
  D3DRMFPTF_PALETTIZED    = 4
  D3DRMFPTF_NOTPALETTIZED = 8
End Enum

값

D3DRMFPTF_ALPHA
돌려주어지는 텍스쳐 포맷에는, 알파 채널이 없으면 안 된다.
D3DRMFPTF_NOALPHA
돌려주어지는 텍스쳐 포맷에는, 알파 채널이 있어서는 안 된다. 알파 채널의 결핍을 희망하지만, 결핍을 필수로 하지 않는 것을 나타내려면 ,D3DRMFPTF_ALPHA와D3DRMFPTF_NOALPHA의 양플래그를 생략 한다.
D3DRMFPTF_PALETTIZED
돌려주어지는 텍스쳐 포맷은, 팔레트화하지 않으면 안 된다.
D3DRMFPTF_NOTPALETTIZED
돌려주어지는 텍스쳐 포맷은, 팔레트화해서는 안 된다. 팔레트의 결핍을 희망하지만, 결핍을 필수로 하지 않는 것을 나타내려면 ,D3DRMFPTF_PALETTIZED와D3DRMFPTF_NOTPALETTIZED의 양플래그를 생략 한다.

CONST_D3DRMFRAMECONSTRAINT

Direct3DRMFrame3 오브젝트를 표시할 경우에 강제적으로 회전하는 축을 기술한다. Direct3DRMFrame3.LookAt 메소드는 이 열거형을 사용한다.

구문

Enum CONST_D3DRMFRAMECONSTRAINT
  D3DRMCONSTRAIN_Z
  D3DRMCONSTRAIN_Y
  D3DRMCONSTRAIN_X
End Enum

값

D3DRMCONSTRAIN_Z
x축과 y축의 회전만을 사용한다.
D3DRMCONSTRAIN_Y
x축과 z축의 회전만을 사용한다.
D3DRMCONSTRAIN_X
y축과 z축의 회전만을 사용한다.

CONST_D3DRMGENERATENORMALSFLAGS

법선의 생성 방법을 정의하기 위해서Direct3DRMMeshBuilder3.GenerateNormals 메소드에 의해 사용되는 값을 지정한다.

구문

Enum CONST_D3DRMGENERATENORMALSFLAGS
  D3DRMGENERATENORMALS_PRECOMPACT     = 1
  D3DRMGENERATENORMALS_USECREASEANGLE = 2
End Enum

값

D3DRMGENERATENORMALS_PRECOMPACT
알고리즘은, 법선의 생성전에 메쉬의 버텍스의 컴팩트화를 시도한다.
D3DRMGENERATENORMALS_USECREASEANGLE
접은 자국각을 나타내는 파라미터를 사용한다. 그렇지 않으면, 접은 자국각은 무시된다.

CONST_D3DRMHANDEDNESS

Direct3D 보관 유지 모드의 좌표계의 현재의 옵션을 나타낸다.

구문

Enum CONST_D3DRMHANDEDNESS
  D3DRMOPTIONS_LEFTHANDED  = 1
  D3DRMOPTIONS_RIGHTHANDED = 2
End Enum

값

D3DRMOPTIONS_LEFTHANDED
왼손 지오메트리를 사용한다. 이 값이 디폴트이다.
D3DRMOPTIONS_RIGHTHANDED
오른손 지오메트리를 사용한다.

주의

D3DRMOPTIONS_LEFTHANDED와D3DRMOPTIONS_RIGHTHANDED는, 피킹, 광선 피킹, 및 다음의 인터페이스에 영향을 준다.

  • Direct3DRMClippedVisual
  • Direct3DRMMesh
  • Direct3DRMMeshBuilder3
  • Direct3DRMProgressiveMesh
  • Direct3DRMShadow2
  • Direct3DRMTexture3
  • Direct3DRMViewport2

CONST_D3DRMINTERPOLATIONFLAGS

인타포레이타오브제크트 위에의Interpolate메소드의 옵션을 정의해, 오브젝트의 로드 방법을 변경한다.

구문

Enum CONST_D3DRMINTERPOLATIONFLAGS
  D3DRMINTERPOLATION_OPEN         = 1
  D3DRMINTERPOLATION_CLOSED       = 2
  D3DRMINTERPOLATION_LINEAR       = 4
  D3DRMINTERPOLATION_SPLINE       = 8
  D3DRMINTERPOLATION_VERTEXCOLOR  = 64 (&H40)
  D3DRMINTERPOLATION_SLERPNORMALS = 128 (&H80)
  D3DRMINTERPOLATION_NEAREST      = 256 (&H100)
End Enum

값

D3DRMINTERPOLATION_OPEN
각 키 최인 (실행 thread)의 최초와 마지막 키가, 인덱스 범위외의 보간값을 수정한다.
D3DRMINTERPOLATION_CLOSED
보간은 순환적으로 된다. 키는, 실제로는, 인덱스 범위에 동일한 시간에 영원히 반복해진다. 애니메이션과의 호환성을 취하기 위해서(때문에), 인덱스 범위의 종점에 동일한 인덱스의 키는, 모두 무시된다.
D3DRMINTERPOLATION_LINEAR
각 키 최인간의 중간값을 결정하기 위해서(때문에), 2개(살)의 가장 가까운 키의 사이에 실시하는 선형 보간이 사용된다.
D3DRMINTERPOLATION_SPLINE
각 키 최인간의 중간값을 결정하기 위해서(때문에), 4개(살)의 가장 가까운 키의 B스플라인 혼합 함수가 사용된다.
D3DRMINTERPOLATION_VERTEXCOLOR
버텍스의 색이 보간 된다. Direct3DRMMesh.SetVertices 의 보간인 만큼 영향을 준다.
D3DRMINTERPOLATION_SLERPNORMALS
버텍스의 법선이 구(공)면보간 된다 (현재미이행). SetVertices의 보간에만 영향을 준다.
D3DRMINTERPOLATION_NEAREST
각 키 최인의 중간값을 결정하기 위해서(때문에), 제일 가까운 키의 값이 사용된다.

CONST_D3DRMLIGHTTYPE

Direct3DRM3.CreateLight 메소드로 사용되는 조명 타입을 정의한다.

구문

Enum CONST_D3DRMLIGHTTYPE
  D3DRMLIGHT_AMBIENT
  D3DRMLIGHT_POINT
  D3DRMLIGHT_SPOT
  D3DRMLIGHT_DIRECTIONAL
  D3DRMLIGHT_PARALLELPOINT
End Enum

값

D3DRMLIGHT_AMBIENT
조명은앰비언트소스이다.
D3DRMLIGHT_POINT
조명은포인트소스이다.
D3DRMLIGHT_SPOT
조명은spotlight소스이다.
D3DRMLIGHT_DIRECTIONAL
조명은디렉셔널소스이다.
D3DRMLIGHT_PARALLELPOINT
조명은패러럴 포인트소스이다.

CONST_D3DRMLOADFLAGS

Direct3DRM3.LoadFromFile ,Direct3DRMAnimationSet2.LoadFromFile ,Direct3DRMFrame3.LoadFromFile ,Direct3DRMMeshBuilder3.LoadFromFile , 및Direct3DRMProgressiveMesh.LoadFromFile 메소드의 옵션을 정의한다. 이러한 옵션은, 오브젝트의 로드 방법을 변경한다.

구문

Enum CONST_D3DRMLOADFLAGS
  D3DRMLOAD_FROMFILE            = 0
  D3DRMLOAD_FROMRESOURCE        = 1
  D3DRMLOAD_FROMMEMORY          = 2
  D3DRMLOAD_FROMSTREAM          = 4
  D3DRMLOAD_FROMUR              = 8
  D3DRMLOAD_BYNAME              = 16 (&H10)
  D3DRMLOAD_BYPOSITION          = 32 (&H20)
  D3DRMLOAD_BYGUID              = 64 (&H40)
  D3DRMLOAD_FIRST               = 128 (&H80)
  D3DRMLOAD_INSTANCEBYREFERENCE = 256 (&H100)
  D3DRMLOAD_INSTANCEBYCOPYING   = 512 (&H200)
  D3DRMLOAD_ASYNCHRONOUS        = 1024 (&H400)
End Enum

값

소스 플래그

D3DRMLOAD_FROMFILE
파일로부터 로드한다. 이것은 디폴트 설정이다.
D3DRMLOAD_FROMRESOURCE
리소스로부터 로드한다.
D3DRMLOAD_FROMMEMORY
메모리로부터 로드한다.
D3DRMLOAD_FROMSTREAM
스트림으로부터 로드한다.
D3DRMLOAD_FROMUR
URL로부터 로드한다.

식별자 플래그

D3DRMLOAD_BYNAME
지정된 이름을 사용해 오브젝트를 로드한다.
D3DRMLOAD_BYPOSITION
주어진, 0으로부터 시작되는 위치에, 스탠드얼론의 오브젝트를 로드한다(즉, 파일중의n번째의 오브젝트를 로드한다). 스탠드얼론의 오브젝트는 다른 오브젝트를 포함할 수가 있지만, 다른 오브젝트에 포함될 것은 없다.
D3DRMLOAD_BYGUID
지정된 글로벌 유니크 식별자(GUID)를 사용해 오브젝트를 로드한다.
D3DRMLOAD_FIRST
이것은 디폴트 설정이다. 주어진 타입의 스탠드얼론의 오브젝트를 로드한다 (예를 들어, 어플리케이션이Direct3DRMMeshBuilder3.LoadFromFile를 호출하는 경우는 메쉬를 로드한다). 스탠드얼론의 오브젝트는 다른 오브젝트를 포함할 수가 있지만, 다른 오브젝트에 포함될 것은 없다.

인스턴스 플래그

D3DRMLOAD_INSTANCEBYREFERENCE
지정된 이름과 같은 이름의 오브젝트가 존재할지 어떨지를 체크한다. 존재하는 경우, 새로운 오브젝트를 생성 하는 대신에, 그 오브젝트의 인스턴스를 사용한다.
D3DRMLOAD_INSTANCEBYCOPYING
지정된 이름과 같은 이름의 오브젝트가 존재할지 어떨지를 체크한다. 존재하는 경우, 새로운 오브젝트를 생성 하는 대신에, 그 오브젝트를 카피한다.

로드 플래그

D3DRMLOAD_ASYNCHRONOUS
LoadFromFile호출은, 즉시 돌아온다. 로드의 진행 상태를 체크하는데 이벤트를 사용하는 것은, 어플리케이션의 책임이 된다. 디폴트에서는, 로드는, 동기식에서 행해져LoadFromFile호출은, 모든 데이터의 로드가 완료할 때까지, 또는 에러가 발생할 때까지는 돌아오지 않는다.

주의

각LoadFromFile메소드는,filename파라미터를 사용해 오브젝트의 소스를 지정해,id파라미터에 의해 오브젝트를 식별한다. 시스템은 소스 플래그의 선택에 근거해filename파라미터를 해석한다. 그리고, 식별자 플래그의 선택에 근거해id파라미터의 내용을 해석한다.

인스턴스 플래그는, 파라미터의 해석 방법에는 아무것도 변경을 더하지 않는다. D3DRMLOAD_INSTANCEBYREFERENCE플래그를 이용하면(자), 새로운 오브젝트를 생성 하는 일 없이 같은 파일을 2회 로드할 수가 있다. 오브젝트가 이름을 가지고 있지 않은 경우,D3DRMLOAD_INSTANCEBYREFERENCE플래그를 세트 하면,D3DRMLOAD_INSTANCEBYCOPYING플래그를 세트 했을 때와 같은 효과를 얻을 수 있다. 로더는, 동일한 오브젝트가 존재해도, 각 이름 없음 오브젝트를 새로운 오브젝트로서 생성 한다.

CONST_D3DRMMAPPINGFLAGS

텍스쳐를 그룹에 맵핑 하는 방법을 정의하는 값이다. Direct3DRMMesh.GetGroupMapping 과Direct3DRMMesh.SetGroupMapping 메소드에 의해 이용된다.

구문

Enum CONST_D3DRMMAPPINGFLAGS
  D3DRMMAP_WRAPU        = 1
  D3DRMMAP_WRAPV        = 2
  D3DRMMAP_PERSPCORRECT = 4
End Enum

값

D3DRMMAP_WRAPU
u방향으로 텍스쳐를 랩 한다.
D3DRMMAP_WRAPV
v방향으로 텍스쳐를 랩 한다.
D3DRMMAP_PERSPCORRECT
텍스쳐 랩핑은 퍼스펙티브 보정된다.

주의

D3DRMMAP_WRAPU와D3DRMMAP_WRAPV플래그는, 래스터라이저가 텍스쳐 좌표를 해석하는 방법을 결정한다. 래스터라이저는 항상, 텍스쳐 좌표로 가장 짧은 거리, 즉 직선을 보간 한다. 이 직선의 패스와 u 및 v좌표의 유효값은, 랩핑 플래그의 사용법에 따라서 다르다. 한편 또는 양쪽 모두의 플래그가 세트 되면(자), 직선은 u 또는 v방향의 텍스쳐의 옆을 rack-around 한다. 이 경우, 텍스쳐는 원기둥(실린더)장이나 도너츠 위에의 위상을 가지고 있는것 같이 보인다.

D3DRMMAP_WRAPU또는D3DRMMAP_WRAPV중 한쪽이 세트 되었을 경우, 텍스쳐는 원주 1.0의 마지막이 없는 원통형이 된다. 1.0이상의 텍스쳐 좌표는, 랩되어 있지 않은 범위내만 유효하다. 텍스쳐 좌표간의 최단 거리는 랩핑 플래그에 따라서 다르다. D3DRMMAP_WRAPU가 세트 되고 있을 때는, 점(0.1, 0.1)으로부터(0.9, 0.9)까지의 최단의 직선은, 점(0, 0.5)을 통과한다.

D3DRMMAP_WRAPU와D3DRMMAP_WRAPV플래그의 양쪽 모두가 세트 되었을 때는, 텍스쳐는 원환체(도너츠) 장이 된다. 시스템은 폐쇄하고 있기 (위해)때문에, 1.0이상의 텍스쳐 좌표는 무효이다. 점(0.1, 0.1)으로부터(0.9, 0.9)까지의 최단의 직선은, 점(0, 0)을 통과한다.

CONST_D3DRMMATERIALMODE

프레임과 함께 렌더링 되는 비주얼의 머트리얼 정보의 소스를 기술한다.

구문

Enum CONST_D3DRMMATERIALMODE
  D3DRMMATERIAL_FROMMESH
  D3DRMMATERIAL_FROMPARENT
  D3DRMMATERIAL_FROMFRAME
End Enum

값

D3DRMMATERIAL_FROMMESH
머트리얼 정보는 비주얼 오브젝트 (메쉬) 그 자체로부터 취득된다. 이것은 디폴트 설정이다.
D3DRMMATERIAL_FROMPARENT
머트리얼 정보는, 색이나 텍스쳐 정보와 함께 친프레임으로부터 계승된다.
D3DRMMATERIAL_FROMFRAME
머트리얼 정보는 프레임으로부터 취득되어 비주얼 오브젝트가 보관 유지하고 있던 이전의 정보를 오버라이드(override) 한다.

참조

Direct3DRMFrame3.GetMaterialMode ,Direct3DRMFrame3.SetMaterialMode

CONST_D3DRMMATERIALOVERRIDEFLAGS

고유의 머트리얼 속성을 세트 한다.

구문

Enum CONST_D3DRMMATERIALOVERRIDEFLAGS
  D3DRMMATERIALOVERRIDE_DIFFUSE_ALPHAONLY     = 1
  D3DRMMATERIALOVERRIDE_DIFFUSE_RGBONLY       = 2
  D3DRMMATERIALOVERRIDE_DIFFUSE               = 3
  D3DRMMATERIALOVERRIDE_AMBIENT               = 4
  D3DRMMATERIALOVERRIDE_EMISSIVE              = 8
  D3DRMMATERIALOVERRIDE_SPECULAR              = 16 (&H10)
  D3DRMMATERIALOVERRIDE_POWER                 = 32 (&H20)
  D3DRMMATERIALOVERRIDE_TEXTURE               = 64 (&H40)
  D3DRMMATERIALOVERRIDE_DIFFUSE_ALPHAMULTIPLY = 128 (&H80)
  D3DRMMATERIALOVERRIDE_ALL                   = 255 (&HFF)
End Enum

값

D3DRMMATERIALOVERRIDE_DIFFUSE_ALPHAONLY
머트리얼의 확산 알파값만을 오버라이드(override) 한다.
D3DRMMATERIALOVERRIDE_DIFFUSE_RGBONLY
머트리얼의 확산 RGB값만을 오버라이드(override) 한다.
D3DRMMATERIALOVERRIDE_DIFFUSE
머트리얼의 확산 프로퍼티를 오버라이드(override) 한다.
D3DRMMATERIALOVERRIDE_AMBIENT
머트리얼의 앰비언트 프로퍼티를 오버라이드(override) 한다.
D3DRMMATERIALOVERRIDE_EMISSIVE
머트리얼의 방사 프로퍼티를 오버라이드(override) 한다.
D3DRMMATERIALOVERRIDE_SPECULAR
머트리얼의 반사 프로퍼티를 오버라이드(override) 한다.
D3DRMMATERIALOVERRIDE_POWER
머트리얼의 반사 강도 프로퍼티를 오버라이드(override) 한다.
D3DRMMATERIALOVERRIDE_TEXTURE
머트리얼의 텍스쳐 프로퍼티를 오버라이드(override) 한다.
D3DRMMATERIALOVERRIDE_DIFFUSE_ALPHAMULTIPLY
머트리얼의 확산 알파 곱셈 프로퍼티를 오버라이드(override) 한다.
D3DRMMATERIALOVERRIDE_ALL
머트리얼의 모든 프로퍼티를 오버라이드(override) 한다.

CONST_D3DRMMESHBUILDERAGEFLAGS

메쉬 빌더의 옵션을 나타낸다. 디폴트값은 0이다. 이 경우, 메쉬 빌더는 보통대로 나이를 먹는다 (에이징은 메쉬 빌더에 대한데 등인가의 변경에 의해 일으켜진다).

구조

Enum CONST_D3DRMMESHBUILDERAGEFLAGS
  D3DRMMESHBUILDERAGE_GEOMETRY  = 1
  D3DRMMESHBUILDERAGE_MATERIALS = 2
  D3DRMMESHBUILDERAGE_TEXTURES  = 4
End Enum

값

D3DRMMESHBUILDERAGE_GEOMETRY
메쉬 빌더는, 메쉬 지오메트리가 변경될 때마다 나이를 먹는다 (예를 들어, 버텍스, 면 또는 다른 메쉬 빌더의 추가).
D3DRMMESHBUILDERAGE_MATERIALS
메쉬 빌더는, 메쉬의 머트리얼 관련 프로퍼티가 변경될 때마다, 혹은, 면 또는 다른 메쉬가 추가되었을 경우에 나이를 먹는다.
D3DRMMESHBUILDERAGE_TEXTURES
메쉬 빌더는, 메쉬의 텍스쳐 관련 프로퍼티가 변경될 때마다, 혹은, 면 또는 다른 메쉬가 추가되었을 경우에 나이를 먹는다.

CONST_D3DRMMESHBUILDERENABLEFLAGS

렌더링과 피킹이 유효한가 어떤가를 나타낸다.

구문

Enum CONST_D3DRMMESHBUILDERENABLEFLAGS
  D3DRMMESHBUILDER_RENDERENABLE = 1
  D3DRMMESHBUILDER_PICKENABLE   = 2
End Enum

값

D3DRMMESHBUILDER_RENDERENABLE
현재의 오브젝트상에서는 렌더링이 유효하다.
D3DRMMESHBUILDER_PICKENABLE
현재의 오브젝트상에서는 피킹이 유효하다.

CONST_D3DRMPALETTEFLAGS

컬러가 어떻게 사용되는지를 정의한다. Microsoft DirectDraw® 로 생성 한 팔레트를 Direct3D 보관 유지 모드로 사용할때, 팔레트 엔트리에 팔레트 플래그를 세트 해, 그 엔트리를 보관 유지 모드로 변경할 수 있을지 어떨지 마크를 붙일 수가 있다.

구문

Enum CONST_D3DRMPALETTEFLAGS
  D3DRMPALETTE_FREE
  D3DRMPALETTE_READONLY
  D3DRMPALETTE_RESERVED
End Enum

값

D3DRMPALETTE_FREE
렌더러는 이 엔트리를 자유롭게 사용할 수 있다.
D3DRMPALETTE_READONLY
고정되고 있지만, 렌더러는 사용할 수 있다.
D3DRMPALETTE_RESERVED
렌더러는 사용할 수 없다.

CONST_D3DRMPARENTINGFLAGS

취득하는Direct3DRMMeshBuilder3 오브젝트를 정의한다

구문

Enum CONST_D3DRMPARENTINGFLAGS
  D3DRMMESHBUILDER_DIRECTPARENT = 1
  D3DRMMESHBUILDER_ROOTMESH     = 2
End Enum

값

D3DRMMESHBUILDER_DIRECTPARENT
현재의Direct3DRMMeshBuilder3오브젝트의 직접적인 부모를 취득한다.
D3DRMMESHBUILDER_ROOTMESH
현재의Direct3DRMMeshBuilder3오브젝트의 마지막 부모 (부모를 가지지 않는 부모)를 취득한다.

CONST_D3DRMPMESHEVENTFLAGS

베이스 메쉬, 또는 모든 데이터가 다운로드된 것을 통지하는 값이다. Direct3DRMProgressiveMesh.RegisterEvents 에 의해 사용된다.

구문

Enum CONST_D3DRMPMESHEVENTFLAGS
  D3DRMPMESHEVENT_BASEMESH = 1
  D3DRMPMESHEVENT_COMPLETE = 2
End Enum

값

D3DRMPMESHEVENT_BASEMESH
베이스 메쉬의 다운로드가 완료 하면 통지되는 이벤트.
D3DRMPMESHEVENT_COMPLETE
모든 데이터의 다운로드가 완료 하면 통지되는 이벤트.

CONST_D3DRMPMESHSTATUSFLAGS

Direct3DRMProgressiveMesh.GetLoadStatus 메소드에 돌려주어지는 메쉬 상태를 정의한다.

구문

Enum CONST_D3DRMPMESHSTATUSFLAGS
  D3DRMPMESHSTATUS_VALID            = 1
  D3DRMPMESHSTATUS_INTERRUPTED      = 2
  D3DRMPMESHSTATUS_BASEMESHCOMPLETE = 4
  D3DRMPMESHSTATUS_COMPLETE         = 8
  D3DRMPMESHSTATUS_RENDERABLE       = 16 (&H10)
End Enum

값

D3DRMPMESHSTATUS_VALID
데이터는 유효하다.
D3DRMPMESHSTATUS_INTERRUPTED
다운로드는 세치기를 받았다.
D3DRMPMESHSTATUS_BASEMESHCOMPLETE
베이스 메쉬의 다운로드가 완료했다.
D3DRMPMESHSTATUS_COMPLETE
로드가 완료했다.
D3DRMPMESHSTATUS_RENDERABLE
베이스 메쉬의 다운로드가 완료해, 데이터는 유효하다.

CONST_D3DRMPROJECTIONTYPE

Direct3DRMViewport 오브젝트로 사용되는 투영의 타입을 정의한다. Direct3DRMViewport2.GetProjection 와Direct3DRMViewport2.SetProjection 메소드는 이 열거형을 사용한다. 오른손 타입은, 오른손 투영을 유효하게 한다.

주: Direct3DRM3.SetOptions 를 사용해 오른손 지오메트리를 지정한다.

카메라의 축( 「Direct3DRMFrame3.SetAxes 」를 참조)은, 카메라의 면 할 방향을 결정하기 위해서(때문에), 왼손 투영과 오른손 투영의 양쪽 모두로 사용된다.

구문

Enum CONST_D3DRMPROJECTIONTYPE
  D3DRMPROJECT_PERSPECTIVE
  D3DRMPROJECT_ORTHOGRAPHIC
  D3DRMPROJECT_RIGHTHANDPERSPECTIVE
  D3DRMPROJECT_RIGHTHANDORTHOGRAPHIC
End Enum

값

D3DRMPROJECT_PERSPECTIVE
투영은, 왼손의 퍼스펙티브이다.
D3DRMPROJECT_ORTHOGRAPHIC
투영은, 왼손의 정사영법이다.
D3DRMPROJECT_RIGHTHANDPERSPECTIVE
투영은, 오른손의 퍼스펙티브이다.
D3DRMPROJECT_RIGHTHANDORTHOGRAPHIC
투영은, 오른손의 정사영법이다.

CONST_D3DRMRAYPICKFLAGS

비주얼과 지정된 광선의 교차 부분을 계산하는 값을 지정한다. DirectDRMFrame3.RayPick 메소드에 의해 사용된다

구문

Enum CONST_D3DRMRAYPICKFLAGS
  D3DRMRAYPICK_ONLYBOUNDINGBOXES       = 1
  D3DRMRAYPICK_IGNOREFURTHERPRIMITIVES = 2
  D3DRMRAYPICK_INTERPOLATEUV           = 4
  D3DRMRAYPICK_INTERPOLATECOLOR        = 8
  D3DRMRAYPICK_INTERPOLATENORMAL       = 16 (&H10)
End Enum

값

최적화 플래그

D3DRMRAYPICK_ONLYBOUNDINGBOXES
계층안의 비주얼의 경계 박스가 있는 교차 부분만큼이 돌려주어진다. 정확한 면의 교차는 체크하지 않는다.
D3DRMRAYPICK_IGNOREFURTHERPRIMITIVES
광선에 교차하는 가장 가까운 비주얼만이 돌려주어진다. 지금까지의 검색중에 발견된 가장 가까운 것보다 멀리 있는 비주얼을 무시한다.

보간 플래그

D3DRMRAYPICK_INTERPOLATEUV
텍스쳐 좌표를 보간 한다.
D3DRMRAYPICK_INTERPOLATECOLOR
색을 보간 한다.
D3DRMRAYPICK_INTERPOLATENORMAL
법선을 보간 한다.

CONST_D3DRMRENDERMODEFLAGS

투명 오브젝트의 투명 모드를 지정한다.

구문

Enum CONST_D3DRMRENDERMODEFLAGS
  D3DRMRENDERMODE_BLENDEDTRANSPARENCY      = 1
  D3DRMRENDERMODE_SORTEDTRANSPARENCY       = 2
  D3DRMRENDERMODE_LIGHTINMODELSPACE        = 8
  D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR    = 16 (&H10)
  D3DRMRENDERMODE_DISABLESORTEDALPHAZWRITE = 32 (&H20)
End Enum

값

D3DRMRENDERMODE_BLENDEDTRANSPARENCY
투명 모드를 알파 블렌딩으로 설정한다. 블렌딩에 의한 투명 모드는, 각 픽셀로 컬러값을 추가해, 2개의 이미지를 조합한다.
D3DRMRENDERMODE_SORTEDTRANSPARENCY
장면안의 투명 다각형이 제2 패스로 버퍼링, 소트, 및 렌더링 되도록(듯이) 투명 모드를 설정한다. 이 플래그는,D3DRMRENDERMODE_BLENDEDTRANSPARENCY플래그도 동시에 세트되어 있지 않은 경우에는, 아무 효과도 없다. 외부 비주얼 또는 유저 비주얼중의 투명 다각형은 소트 되지 않는다. 네이티브 D3DRM 비주얼 (D3DRMMesh 오브젝트와D3DRMMeshBuilder 오브젝트등) 마셔 소트 된다.
D3DRMRENDERMODE_LIGHTINMODELSPACE
조명이 모델 공간에서 렌더링 되도록(듯이) 투명 모드를 설정한다.
D3DRMRENDERMODE_VIEWDEPENDENTSPECULAR
의존하는 반사를 표시하도록(듯이) 투명 모드를 설정한다.
D3DRMRENDERMODE_DISABLESORTEDALPHAZWRITE
소트를 무효로 하도록(듯이) 투명 모드를 설정한다.

주의

D3DRMRENDERMODE_BLENDEDTRANSPARENCY와D3DRMRENDERMODE_SORTEDTRANSPARENCY의 양플래그가, 동시에 세트 되고 있으면, 2개의 투명 오브젝트가, 한편을 한편으로 렌더링 하도록(듯이) 보증해, 이미지는, 기대 대로의 비주얼 효과를 만들어 내도록(듯이) 올바른 순서로 혼합된다.

D3DRMRENDERMODE_SORTEDTRANSPARENCY는, 알파 다각형의 삼각형마다의, 뒤로부터 전에의 소트를 온으로 한다.

D3DRMRENDERMODE_BLENDEDTRANSPARENCY플래그는, 점묘 알파에 대항해 진정한 알파 블렌딩을 온으로 한다. 진정한 알파 블렌딩에서는, 중복 하는 삼각형의 픽셀은 정리해 혼합된다. 점묘 알파에서는, 전면에 있는 삼각형의 픽셀의 몇개인가는, 아래에 있는 삼각형을 표시하는 것 같은 드로잉(Drawing)를 하지 않는다 (이것은, 스크린 문의 투명이라고도 불린다). 점묘 알파를 실행하는 경우, 삼각형을 어떠한 순서로 렌더링 할까에 관계없이, 결과가 같기 때문에, 삼각형을 소트 할 필요는 없다.

CONST_D3DRMRENDERQUALITY

Direct3DRMDevice3.SetQuality ,Direct3DRMMeshBuilder3.SetQuality 및Direct3DRMProgressiveMesh.SetQuality 메소드에 의해 설정되는 퀄리티 옵션을 정의한다. 게다가CONST_D3DRMRENDERQUALITY는, 전부 칠해 모드, 조명 모드 및 쉐이딩 모드를 정의한다

구문

Enum CONST_D3DRMRENDERQUALITY
  D3DRMFILL_POINTS      = 0
  D3DRMFILL_WIREFRAME   = 64(&H40)
  D3DRMFILL_SOLID       = 128(&H80)
  D3DRMFILL_MASK        = 448(&H1C0)
  D3DRMFILL_MAX         = 512(&H200)

  D3DRMLIGHT_OFF        = 0
  D3DRMLIGHT_ON         = 8
  D3DRMLIGHT_MASK       = 56(&H38)
  D3DRMLIGHT_MAX        = 64(&H40)

  D3DRMRENDER_WIREFRAME = 64  (&H40)
  D3DRMRENDER_UNLITFLAT = 128 (&H80)
  D3DRMRENDER_FLAT      = 136 (&H88)
  D3DRMRENDER_GOURAUD   = 137 (&H89)
  D3DRMRENDER_PHONG     = 138 (&H8A)

  D3DRMSHADE_FLAT       = 0
  D3DRMSHADE_GOURAUD    = 1
  D3DRMSHADE_PHONG      = 2
  D3DRMSHADE_MASK       = 7
  D3DRMSHADE_MAX        = 8
End Enum

값

D3DRMFILL_POINTS
점만을 전부 칠한다. 최소의 전부 칠해 모드.
D3DRMFILL_WIREFRAME
와이어 프레임을 전부 칠한다.
D3DRMFILL_SOLID
솔리드 오브젝트를 전부 칠한다.
D3DRMFILL_MASK
마스크를 사용해 전부 칠한다.
D3DRMFILL_MAX
전부 칠해 모드의 최대치.
D3DRMLIGHT_OFF
조명은 오프이다.
D3DRMLIGHT_ON
조명은 온이다.
D3DRMLIGHT_MASK
조명은 마스크를 사용한다.
D3DRMLIGHT_MAX
최대 조명 모드.
D3DRMRENDER_WIREFRAME
와이어 프레임 전부 칠해 모드를 지정한다.
D3DRMRENDER_UNLITFLAT
flat shading와 조명 오프를 지정한다.
D3DRMRENDER_FLAT
flat shading, 조명 온, 솔리드 칠해를 지정한다.
D3DRMRENDER_GOURAUD
gouraud shading, 조명 온, 솔리드 칠해를 지정한다.
D3DRMRENDER_PHONG
이 쉐이딩 모드는 이행되어 있지 않다. 디폴트는 gouraud shading.
D3DRMSHADE_FLAT
오브젝트를 flat shading으로 렌더링 한다. 이것은 디폴트 설정이다.
D3DRMSHADE_GOURAUD
오브젝트를 gouraud shading로 렌더링 한다.
D3DRMSHADE_PHONG
오브젝트를 폰 쉐이딩으로 렌더링 한다.
D3DRMSHADE_MASK
오브젝트를 마스크 쉐이딩으로 렌더링 한다.
D3DRMSHADE_MAX
오브젝트를 최대의 쉐이딩으로 렌더링 한다.

주의

렌더링 퀄리티란, 디바이스의 렌더링 표면상에서 실행되는 렌더링의 퀄리티의 최대치이다.

오브젝트의 퀄리티에는, 3개의 컴퍼넌트가 있다. 즉, 쉐이딩 모드 (플랫 또는 굿 로), 조명 타입 (온 또는 오프) 및 전부 칠해 모드 (포인트, 와이어 프레임 또는 솔리드)이다.

CONST_D3DRMSAVEFLAGS

Direct3DRMMeshBuilder3.Save 메소드의 보존 옵션을 정의한다.

구문

Enum CONST_D3DRMSAVEFLAGS
  D3DRMXOFSAVE_NORMALS            = 1
  D3DRMXOFSAVE_TEXTURECOORDINATES = 2
  D3DRMXOFSAVE_MATERIALS          = 4
  D3DRMXOFSAVE_TEXTURENAMES       = 8
  D3DRMXOFSAVE_ALL                = 15
  D3DRMXOFSAVE_TEMPLATES          = 16 (&H10)
  D3DRMXOFSAVE_TEXTURETOPOLOGY    = 32 (&H20)
End Enum

값

D3DRMXOFSAVE_NORMALS
기본적인 면에 가세해법선 벡터를 보존한다.
D3DRMXOFSAVE_TEXTURECOORDINATES
기본적인 면에 가세해 텍스쳐 좌표를 보존한다.
D3DRMXOFSAVE_MATERIALS
기본적인 면에 가세해 머트리얼을 보존한다.
D3DRMXOFSAVE_TEXTURENAMES
기본적인 면에 가세해 텍스쳐의 이름을 보존한다.
D3DRMXOFSAVE_ALL
기본적인 면에 가세해 법선 벡터, 텍스쳐 좌표, 머트리얼, 텍스쳐의 이름을 보존한다.
D3DRMXOFSAVE_TEMPLATES
파일의 템플릿을 보존한다. 디폴트에서는 템플릿은 보존되지 않는다.
D3DRMSAVE_TEXTURETOPOLOGY
메쉬의 면랩값 (Direct3DRMMeshBuilder3.SetTextureTopology 또는Direct3DRMFace2.SetTextureTopology 에 의해 설정된다)을 보존한다. 이 플래그는,Save메소드에D3DRMXOFSAVE_ALL를 건네주었을 경우에는 포함되지 않는다. 모든 것을 실제로 보존하고 싶으면,D3DRMSAVE_TEXTURETOPOLOGY와D3DRMXOFSAVE_ALL을 건네준다. Direct3DRMMeshBuilder3.SetTextureTopology또는Direct3DRMFace2.SetTextureTopology를 호출해, 설정한 값을 보관 유지하고 싶은 경우는, 이 플래그를 건네주는 것만으로 좋다.

CONST_D3DRMSORTMODE

장면에서 아이 프레임을 어떻게 소트 하는지를 기술한다

구문

Enum CONST_D3DRMSORTMODE
  D3DRMSORT_FROMPARENT
  D3DRMSORT_NONE
  D3DRMSORT_FRONTTOBACK
  D3DRMSORT_BACKTOFRONT
End Enum

값

D3DRMSORT_FROMPARENT
아이 프레임은 친프레임의 소트 순서를 계승한다. 이것은 디폴트 설정이다.
D3DRMSORT_NONE
아이 프레임은 소트 되지 않는다.
D3DRMSORT_FRONTTOBACK
아이 프레임은 전부터 뒤에 소트 된다.
D3DRMSORT_BACKTOFRONT
아이 프레임은 뒤로부터 전에 소트 된다.

참조

Direct3DRMFrame3.GetSortMode ,Direct3DRMFrame3.SetSortMode

CONST_D3DRMSTATECHANGEFLAGS

상태 변경의 옵션을 설정한다.

구문

Enum CONST_D3DRMSTATECHANGEFLAGS
  D3DRMSTATECHANGE_UPDATEONLY  = 1
  D3DRMSTATECHANGE_VOLATILE    = 2
  D3DRMSTATECHANGE_NONVOLATILE = 4
  D3DRMSTATECHANGE_RENDER      = 32 (&H20)
  D3DRMSTATECHANGE_LIGHT       = 64 (&H40)
End Enum

값

D3DRMSTATECHANGE_UPDATEONLY
상태 변경을 나타내는 플래그.
D3DRMSTATECHANGE_VOLATILE
상태 변경을 나타내는 플래그.
D3DRMSTATECHANGE_NONVOLATILE
상태 변경을 나타내는 플래그.
D3DRMSTATECHANGE_RENDER
상태 변경을 나타내는 플래그.
D3DRMSTATECHANGE_LIGHT
상태 변경을 나타내는 플래그.

CONST_D3DRMTEXTURECACHEFLAGS

현재의 텍스쳐에 관한 텍스쳐 관리 시스템을 제어한다.

구문

Enum CONST_D3DRMTEXTURECACHEFLAGS
  D3DRMTEXTURE_FORCERESIDENT         = 1
  D3DRMTEXTURE_STATIC                = 2
  D3DRMTEXTURE_DOWNSAMPLEPOINT       = 4
  D3DRMTEXTURE_DOWNSAMPLEBILINEAR    = 8
  D3DRMTEXTURE_DOWNSAMPLEREDUCEDEPTH = 16 (&H10)
  D3DRMTEXTURE_DOWNSAMPLENONE        = 32 (&H20)
End Enum

값

D3DRMTEXTURE_FORCERESIDENT
텍스쳐를 (하드웨어 시나리오중의) 비디오 메모리 로 유지하는 것을 나타낸다.
D3DRMTEXTURE_STATIC
텍스쳐가 변함없는 것을 나타낸다.
D3DRMTEXTURE_DOWNSAMPLEPOINT
텍스쳐의 다운 샘플시에 포인트 필터링을 사용하는 것을 나타낸다.
D3DRMTEXTURE_DOWNSAMPLEBILINEAR
텍스쳐의 다운 샘플시에 쌍일차 필터링을 사용하는 것을 나타낸다.
D3DRMTEXTURE_DOWNSAMPLEREDUCEDEPTH
텍스쳐의 다운 샘플시에 픽셀 깊이가 감소하는 것을 나타낸다. 낮은 비트 깊이를 사용할 수 없는 경우는, 텍스쳐의 사이즈가 감소한다.
D3DRMTEXTURE_DOWNSAMPLENONE
텍스쳐를 결코 다운 샘플 하지 않는 것을 나타낸다. 디폴트값은,D3DRMTEXTURE_DOWNSAMPLEPOINT이다.

CONST_D3DRMTEXTURECHANGEDFLAGS

텍스쳐에서의 변경을 나타낸다.

구문

Enum CONST_D3DRMTEXTURECHANGEDFLAGS
  D3DRMTEXTURE_CHANGEDPIXELS  = 64 (&H40)
  D3DRMTEXTURE_CHANGEDPALETTE = 128 (&H80)
  D3DRMTEXTURE_INVALIDATEONLY = 256 (&H100)
End Enum

값

D3DRMTEXTURE_CHANGEDPIXELS
픽셀값이 변경된 것을 나타낸다.
D3DRMTEXTURE_CHANGEDPALETTE
팔레트가 변경된 것을 나타낸다.
D3DRMTEXTURE_INVALIDATEONLY
텍스쳐-존이 무효가 되었지만, 어플리케이션으로 갱신할 필요가 없는 것을 나타낸다.

CONST_D3DRMTEXTUREQUALITY

디바이스가 텍스쳐의 픽셀과 뷰포트의 픽셀을 보간 하는 방법을 기술한다. 이 열거형은,Direct3DRMDevice3.SetTextureQuality 와Direct3DRMDevice3.GetTextureQuality 에 의해 사용된다.

구문

Enum CONST_D3DRMTEXTUREQUALITY
  D3DRMTEXTURE_NEAREST
  D3DRMTEXTURE_LINEAR
  D3DRMTEXTURE_MIPNEAREST
  D3DRMTEXTURE_MIPLINEAR
  D3DRMTEXTURE_LINEARMIPNEAREST
  D3DRMTEXTURE_LINEARMIPLINEAR
End Enum

값

D3DRMTEXTURE_NEAREST
텍스쳐의 가장 가까운 픽셀을 선택한다. MIP Mapping를 지원 하지 않는다.
D3DRMTEXTURE_LINEAR
4개(살)의 가장 가까운 픽셀을 선형에 보간 한다. MIP Mapping를 지원 하지 않는다.
D3DRMTEXTURE_MIPNEAREST
D3DRMTEXTURE_NEAREST를 닮아 있지만, 텍스쳐 대신에 적절한밉맵을 사용한다. 픽셀 샘플링과 MIP Mapping는 양쪽 모두 최근 닮고이다.
D3DRMTEXTURE_MIPLINEAR
D3DRMTEXTURE_LINEAR를 닮아 있지만, 텍스쳐 대신에 적절한 밉맵을 사용한다. 픽셀 샘플링은 선형이다. MIP Mapping는 최근 닮고이다.
D3DRMTEXTURE_LINEARMIPNEAREST
D3DRMTEXTURE_MIPNEAREST를 닮아 있지만, 2개의 최근 닮고 밉맵간을 보간 한다. 픽셀 샘플링은 최근 닮고이다. MIP Mapping는 선형이다.
D3DRMTEXTURE_LINEARMIPLINEAR
D3DRMTEXTURE_MIPLINEAR를 닮아 있지만, 2개의 최근 닮고 밉맵간을 보간 한다. 픽셀 샘플링과 MIP Mapping는, 양쪽 모두 선형이다.

CONST_D3DRMTRAVERALFLAGS

현재의 프레임의 횡단 상태를 나타낸다.

구문

Enum CONST_D3DRMTRAVERALFLAGS
  D3DRMFRAME_RENDERENABLE        = 1
  D3DRMFRAME_PICKENABLE          = 2
  D3DRMFRAME_RENDERANDPICKENABLE = 3
End Enum

값

D3DRMFRAME_RENDERENABLE
이 프레임 또는 그 아이 프레임을 렌더링 한다.
D3DRMFRAME_PICKENABLE
이 프레임 또는 그 아이 프레임내의 비주얼을 피킹 한다.
D3DRMFRAME_RENDERANDPICKENABLE
이 프레임 또는 그 아이 프레임내의 비주얼을 렌더링 및 피킹 한다.

CONST_D3DRMVIEWPORTCLEARFLAGS

클리어 옵션을 설정한다.

구문

Enum CONST_D3DRMVIEWPORTCLEARFLAGS
  D3DRMCLEAR_TARGET     = 1
  D3DRMCLEAR_ZBUFFER    = 2
  D3DRMCLEAR_DIRTYRECTS = 4
  D3DRMCLEAR_ALL        = 7
End Enum

값

D3DRMCLEAR_TARGET
출력처 렌더링 표면만을 클리어 한다.
D3DRMCLEAR_ZBUFFER
z버퍼 표면만을 클리어 한다.
D3DRMCLEAR_DIRTYRECTS
사용이 끝난 방형 리스트만을 클리어 한다.
D3DRMCLEAR_ALL
타겟, z버퍼, 사용이 끝난 방형 리스트를 클리어 한다. 이 플래그는Direct3DRMViewport.Clear 의 사용 과 유사한다

CONST_D3DRMWIREFRAMEFLAGS

와이어 프레임 옵션을 설정한다.

구문

Enum CONST_D3DRMWIREFRAMEFLAGS
  D3DRMWIREFRAME_CULL       = 1
  D3DRMWIREFRAME_HIDDENLINE = 2
End Enum

값

D3DRMWIREFRAME_CULL
뒤에 숨겨진 면은, 드로잉(Drawing) 되지 않는다.
D3DRMWIREFRAME_HIDDENLINE
와이어 프레임 렌더링 된 선은, 인접의 오브젝트로 숨겨진다.

CONST_D3DRMWRAPTYPE

Direct3DRM3.CreateWrap 메소드로 생성 된Direct3DRMWrap 오브젝트의 타입을 정의한다.

구문

Enum CONST_D3DRMWRAPTYPE
  D3DRMWRAP_FLAT
  D3DRMWRAP_CYLINDER
  D3DRMWRAP_SPHERE
  D3DRMWRAP_CHROME
End Enum

값

D3DRMWRAP_FLAT
랩은 평면이다.
D3DRMWRAP_CYLINDER
랩은 원기둥(실린더)이다.
D3DRMWRAP_SPHERE
랩은 구(공)체이다.
D3DRMWRAP_CHROME
랩은, 텍스쳐가 오브젝트상에서 반사되도록(듯이) 텍스쳐 좌표를 할당한다.

CONST_D3DRMXOFFORMAT

Direct3DRMMeshBuilder3.Save 메소드로 사용되는 파일 타입을 정의한다.

구문

Enum CONST_D3DRMXOFFORMAT
  D3DRMXOF_BINARY
  D3DRMXOF_COMPRESSED
  D3DRMXOF_TEXT
End Enum

값

D3DRMXOF_BINARY
파일은 바이너리 포맷이다. 이것은 디폴트 설정이다.
D3DRMXOF_COMPRESSED
현재는 지원되어 있지 않다.
D3DRMXOF_TEXT
파일은 텍스트 포맷이다.

주의

D3DRMXOF_BINARY와D3DRMXOF_TEXT설정을 동시에 사용할 수 없다.

CONST_D3DRMZBUFFERMODE

Z버퍼가 유효한가 어떤가를 나타낸다.

구문

Enum CONST_D3DRMZBUFFERMODE
  D3DRMZBUFFER_FROMPARENT
  D3DRMZBUFFER_ENABLE
  D3DRMZBUFFER_DISABLE
End Enum

값

D3DRMZBUFFER_FROMPARENT
프레임은 친프레임으로부터 Z버퍼의 설정을 계승한다. 이것은 디폴트 설정이다.
D3DRMZBUFFER_ENABLE
Z버퍼는 유효하다.
D3DRMZBUFFER_DISABLE
Z버퍼는 무효이다.

참조

Direct3DRMFrame3.GetZbufferMode ,Direct3DRMFrame3.SetZbufferMode


Visual Basic의 형태

Microsoft® Direct3D® 보관 유지 모드의 Microsoft Visual Basic® 의 형태는 이하대로이다.

  • D3DRMANIMATIONKEY
  • D3DRMBOX
  • D3DRMMATERIALOVERRIDE
  • D3DRMPICKDESC
  • D3DRMPICKDESC2
  • D3DRMPMESHLOADSTATUS
  • D3DRMQUATERNION
  • D3DRMRAY
  • D3DRMVECTOR4D
  • D3DRMVERTEX

D3DRMANIMATIONKEY

Direct3DRMAnimation2.AddKey ,GetKeys , 및ModifyKey 메소드가 사용하는 키를 정의한다.

구문

Type D3DRMANIMATIONKEY
  x As Single
  y As Single
  z As Single
  s As Single
  dvTime As Single
  lID As Long
  lKeyType As Long
End Type

멤버

x
벡터를 정의하는 x값.
y
벡터를 정의하는 y값.
z
벡터를 정의하는 z값.
s
회전 키로 사용되는 라디안 단위의 각도.
dvTime
임의의 단위의 시간값.
lID
키 식별자.
lKeyType
키의 타입. 애니메이션의 재생 방법을 정의한다.

주의

멤버의x,y,z, 및s는, 각각D3DRMQUATERNION 형의 멤버 [x, y, z, s] 인가,D3DVECTOR 형의 멤버 [x, y, z] 를 나타낸다. 회전 키는 회전을 정의하는D3DRMQUATERNION 형, 스케일 키는 스케일을 정의하는D3DVECTOR형의 값, 그리고 위치 키는 위치를 정의하는D3DVECTOR형의 값이다. 특정의 인스턴스로 유효한 키는, 1개뿐이다.

D3DRMBOX

Direct3DRMMesh.GetBox 와Direct3DRMMeshBuilder3.GetBox 메소드에 의해 취득되는 경계 박스를 정의한다.

구문

Type D3DRMBOX
  max As D3DVECTOR
  min As D3DVECTOR
End Type

멤버

min , max
박스의 경계를 정의하는 값. 이러한 값은D3DVECTOR 형이다.

D3DRMMATERIALOVERRIDE

Direct3DRMFrame3.SetMaterialOverride 과Direct3DRMFrame3.GetMaterialOverride 메소드의 오버라이드(override)를 기술한다.

구문

Type D3DRMMATERIALOVERRIDE
  dcAmbient As D3DCOLORVALUE
  dcDiffuse As D3DCOLORVALUE
  dcEmissive As D3DCOLORVALUE
  dcSpecular As D3DCOLORVALUE
  dvPower As Single
  lFlags As Long
End Type

멤버

dcAmbient
D3DCOLORVALUE 형의앰비언트RGB 컬러 설정.
dcDiffuse
D3DCOLORVALUE형의 확산 RGBA 컬러 설정.
dcEmissive
D3DCOLORVALUE형의 방사 RGB 컬러 설정.
dcSpecular
D3DCOLORVALUE형의 반사 RGB 컬러 설정.
dvPower
강도설정.
lFlags
이 형태의 어느 필드가 유효한가를 나타내는, 플래그의 논리적 편성. 가능한 값은 이하대로이다.
D3DRMMATERIALOVERRIDE_ALL
D3DRMMATERIALOVERRIDE_AMBIENT
D3DRMMATERIALOVERRIDE_DIFFUSE
D3DRMMATERIALOVERRIDE_DIFFUSE_ALPHAONLY
D3DRMMATERIALOVERRIDE_DIFFUSE_RGBONLY
D3DRMMATERIALOVERRIDE_EMISSIVE
D3DRMMATERIALOVERRIDE_POWER
D3DRMMATERIALOVERRIDE_SPECULAR
D3DRMMATERIALOVERRIDE_TEXTURE

D3DRMPICKDESC

Direct3DRMPickArray.GetPickFrame 메소드에 의해 취득된, 픽의 위치, 면, 그룹 식별자를 저장 한다.

구문

Type D3DRMPICKDESC
  lFaceIdx As Long
  lGroupIdx As Long
  vPosition As D3DVECTOR
End Type

멤버

lFaceIdx
취득된 오브젝트의 면의 인덱스.
lGroupIdx
취득된 오브젝트의 그룹의 인덱스.
vPosition
취득된 오브젝트의 위치를 나타내는 값. 이 값은D3DVECTOR 형이다.

D3DRMPICKDESC2

Direct3DRMPick2Array.GetPickFrame 메소드에 의해 꺼내진 면이나 그룹의 식별자, 픽의 위치, 버텍스의 수평 및 수직 텍스쳐 좌표, 버텍스의 법선 및 오브젝트의 색을 저장 한다.

구문

Type D3DRMPICKDESC2
  lFaceIdx As Long
  lGroupIdx As Long
  vPosition As D3DVECTOR
  tu As Single
  tv As Single
  vNormal As D3DVECTOR
  color As Long
End Type

멤버

lFaceIdx
취득된 오브젝트의 면의 인덱스.
lGroupIdx
취득된 오브젝트의 그룹의 인덱스.
vPosition
취득된 오브젝트의 위치를 나타내는 값. 이 값은D3DVECTOR 형이다.
tu , tv
버텍스의 수평 및 수직 텍스쳐 좌표.
vNormal
버텍스의법선 벡터. 이 값은D3DVECTOR형이다.
color
버텍스의 색. 오브젝트의 색을 알파 요소를 포함해 지정하려면 , 오브젝트 위에의DirectX7인터페이스로부터CreateColorRGBA메소드를 호출한다.

D3DRMPMESHLOADSTATUS

Direct3DRMProgressiveMesh.LoadFromFile 메소드를 사용해 로드 된 프로그래시브 메쉬의 로드 상태를 저장 한다. 이 형태는,Direct3DRMProgressiveMesh.GetLoadStatus 메소드를 사용해 취득할 수 있다.

구문

Type D3DRMPMESHLOADSTATUS
  lBytesLoaded As Long
  lVerticesLoaded As Long
  lFacesLoaded As Long
  lFlags As Long
End Type

멤버

lBytesLoaded
로드 된 합계 바이트수.
lVerticesLoaded
로드 된 버텍스의 수.
lFacesLoaded
로드 된 면의 수.
lFlags
프로그래시브 메쉬 로드 상태를 나타내는 플래그. 이하의 값의 하나를 취할 수가 있다.
D3DRMPMESHSTATUS_VALID
프로그래시브 메쉬 오브젝트는, 유효한 데이터를 포함한다.
D3DRMPMESHSTATUS_INTERRUPTED
다운로드는, 어플리케이션이Direct3DRMProgressiveMesh.Abort 를 사용했는지, 또는 접속이 없어졌는지의 몇개의 이유로써 새치기를 받았다.
D3DRMPMESHSTATUS_BASEMESHCOMPLETE
베이스 메쉬의 다운로드가 완료했다.
D3DRMPMESHSTATUS_COMPLETE
모든 데이터의 다운로드가 완료했다.
D3DRMPMESHSTATUS_RENDERABLE
메쉬의 렌더링은, 현재 가능하다.

D3DRMQUATERNION

Direct3DRMAnimation2.AddRotateKey 메소드로 이용되는 회전과Direct3DRMFrame3.SetQuaternion 로 이용되는 4원수를 기술한다. 또, Direct3D의 수학 함수의 몇개인가에서도 사용된다.

구문

Type D3DRMQUATERNION
  s As Single
  v As D3DVECTOR
End Type

멤버

s
각도.
v
이 값은D3DVECTOR 형이다.

D3DRMRAY

광선의 방향과 시작 위치를Direct3DRMFrame3.RayPick 메소드로 정의한다.

구문

Type D3DRMRAY
  dir As D3DVECTOR
  pos As D3DVECTOR
End Type

멤버

dir
광선 픽으로 이용되는 광선의 방향. 이 값은D3DVECTOR 형이다.
pos
광선 픽으로 이용되는 광선의 시작 위치. 이 값은D3DVECTOR형이다.

D3DRMVECTOR4D

화면 좌표를 기술한다. 이러한 좌표는,Direct3DRMViewport2.Transform 메소드에 의한 변환의 출력처로서 및Direct3DRMViewport2.InverseTransform 메소드에 의한 변환의 소스로서 사용된다.

구문

Type D3DRMVECTOR4D
  x As Single
  y As Single
  z As Single
  w As Single
End Type

멤버

x , y , z , w
동종의 값을 나타내는 변수. 이러한 값은, 변환 결과를 정의한다.

D3DRMVERTEX

Direct3DRMMesh 오브젝트중의 버텍스를 기술한다.

구문

Type D3DRMVERTEX
  position As D3DVECTOR
  normal As D3DVECTOR
  tu As Single
  tv As Single
  color As Long
End Type

멤버

position
버텍스의 위치. 이 값은D3DVECTOR 형이다.
normal
버텍스의 법선 벡터. 이 값은D3DVECTOR형이다.
tu , tv
버텍스의 수평 및 수직 텍스쳐 좌표.
color
버텍스의 색. 오브젝트의 색을 알파 요소를 포함해 지정하려면 , 오브젝트 위에의DirectX7인터페이스로부터CreateColorRGBA메소드를 호출한다.

참조

Direct3DRMMesh.GetVertices ,Direct3DRMMesh.SetVertices


Visual Basic 에러값

Microsoft® Direct3D® 보관 유지 모드의 인터페이스의 메소드는, Microsoft Visual Basic® 로 이하의 값을 돌려준다.

D3DRM_OK
성공. DD_OK 와 동등.
D3DRMERR_BADALLOC
메모리 부족.
D3DRMERR_BADDEVICE
디바이스는 렌더러와 호환성이 없다.
D3DRMERR_BADFILE
데이터 파일이 부정.
D3DRMERR_BADMAJORVERSION
DLL의 메이저 버젼이 부정.
D3DRMERR_BADMINORVERSION
DLL의 마이너 버젼이 부정.
D3DRMERR_BADOBJECT
인수에는 오브젝트가 필요.
D3DRMERR_BADPMDATA
. x파일중의 데이터가 부정. 프로그래시브 메쉬에의 변환은 성공했지만, 무효인 프로그래시브 메쉬가. x파일에 생성 되었다.
D3DRMERR_BADTYPE
부정한 형태의 인수가 건네받았다.
D3DRMERR_BADVALUE
부정한 값의 인수가 건네받았다.
D3DRMERR_BOXNOTSET
경계 박스가 프레임으로 설정되지 않을 때에, 경계 박스에 액세스 하려고 했다(예를 들어,Direct3DRMFrame3.GetBox 를 이용해).
D3DRMERR_CLIENTNOTREGISTERED
클라이언트가 등록되지 않았다.
D3DRMERR_CONNECTIONLOST
로드, 클론 또는 복제중에 데이터 접속이 없어졌다.
D3DRMERR_ELEMENTINUSE
사용중은 요소의 수정 또는 삭제는 할 수 없다. 서브 메쉬를 비우려면 , 그 부모에 대해서 Direct3DRMMeshBuilder3.Empty 를 호출한다.
D3DRMERR_ENTRYINUSE
버텍스 또는 법선 엔트리는 현재면이 사용중이며, 삭제할 수 없다.
D3DRMERR_FACEUSED
면은 메쉬상에서 사용 종료이다.
D3DRMERR_FILENOTFOUND
지정된 장소에 파일이 발견되지 않는다.
D3DRMERR_INCOMPATIBLEKEY
지정된 애니메이션 키는 호환성이 없다. 키를 수정할 수 없다.
D3DRMERR_INVALIDLIBRARY
지정된 라이브러리는 무효이다.
D3DRMERR_INVALIDOBJECT
메소드가, 무효인 오브젝트를 받았다.
D3DRMERR_INVALIDPARAMS
메소드에게 건네진 파라미터가 적어도 1개 무효이다.
D3DRMERR_LIBRARYNOTFOUND
지정된 라이브러리가 발견되지 않는다.
D3DRMERR_LOADABORTED
로드가 유저에 의해 강제 종료 당했다.
D3DRMERR_NOSUCHKEY
지정된 애니메이션 키는 존재하지 않는다.
D3DRMERR_NOTCREATEDFROMDDS
지정된 텍스쳐가 Microsoft DirectDraw®표면으로부터 생성되어 있지 않다.
D3DRMERR_NOTDONEYET
에러 플래그가 이행되어 있지 않다.
D3DRMERR_NOTENOUGHDATA
요구된 처리를 실시하기 위해서(때문에) 충분한 데이터가 로드되어 있지 않다.
D3DRMERR_NOTFOUND
지정된 장소에 오브젝트가 발견되지 않는다.
D3DRMERR_OUTOFRANGE
지정된 값은 범위외이다.
D3DRMERR_PENDING
요구된 정보를 공급하기 위해서 필요한 데이터의 로드가 종료하고 있지 않다.
D3DRMERR_REQUESTTOOLARGE
이용 가능한 최대 상세 레벨보다 큰 상세 레벨을 프로그래시브 메쉬로 설정하려고 했다.
D3DRMERR_REQUESTTOOSMALL
베이스 메쉬의 상세보다 작은 프로그래시브 메쉬의 최저 렌더링 상세를 설정하려고 했다 (렌더링의 최소 값).
D3DRMERR_TEXTUREFORMATNOTFOUND
지정된 기준을 채워, 하층의 직접 모드 디바이스가 지원 하는 텍스쳐 포맷이 발견되지 않았다.
D3DRMERR_UNABLETOEXECUTE
프로시저를 실행할 수 없다.
DD_OK
요구는 성공해 완료했다. D3DRM_OK 와 동등.
DDERR_INVALIDOBJECT
무효인 오브젝트의 포인터를 받았다.
DDERR_INVALIDPARAMS
O메소드에게 건네진 1개이상의 파라미터가 부정하다.
DDERR_NOTFOUND
요구된 항목이 발견되지 않았다.
DDERR_NOTINITIALIZED
오브젝트가 초기화되기 전에, 오브젝트의 인터페이스 메소드를 호출하려고 했다.
DDERR_OUTOFMEMORY
DirectDraw가 처리를 실시하는데 충분한 메모리가 없다.


Visual Basic 프로그래머를 위한 추가 정보

이 항에는, Microsoft® Direct3D® 보관 유지 모드의 Microsoft Visual Basic®레퍼런스에 관한 다음의 주제가 포함된다.

  • 컬러 키잉
  • CONST_D3DCOLORMODEL
  • D3DCOLOR_MONO
  • D3DCOLOR_RGB
  • D3DCOLORVALUE
  • D3DMATRIX
  • D3DPRIMCAPS
  • D3DRECT
  • D3DTRIANGLE
  • D3DVECTOR
  • DirectDrawCreate
  • DirectDrawCreateClipper
  • Direct3D3
  • DirectDrawClipper
  • 인타포레이타
  • 밉맵
  • 텍스쳐 맵 포맷

컬러 키잉
컬러 키는, 일반적으로는 아티스트가 투명성을 위해서(때문에) 밖에 사용하지 않는 단일로 공통성이 없는 색이지만, 이것을 지정한 색범위로 할 수도 있다. DirectDrawSurface4.SetColorKey메소드를 사용해, 표면의 컬러 키를 세트 할 수가 있다. 컬러 키를 세트 하면,DirectDrawSurface3.BltFast에 대한 후속의 호출은 그 컬러 키를 활용해, 일치하는 픽셀을 무시한다. 이 타입의 컬러 키는, 소스 컬러 키로 불린다. 소스 컬러 키는 「투명」인 픽셀이 출력 먼저 기입해지지 않게 하기 위한(해), 오리지날의 배경 픽셀은 이러한 장소에 보존되어 비방형 오브젝트인 스프라이트가 배경을 횡단해 있는 것과 같게 보인다. 출력처 표면에 효과를 주는 컬러 키 (출력처 컬러 키)를 사용할 수도 있다.

출력처 컬러 키는, 스프라이트로 덧쓰기 가능한 픽셀에 사용되는 표면 위에의색이다. 재차, 아티스트는, 이미지중의 다른 장소에서 사용되어 있지 않은 임의의 색을 선택해, 블록 전송 가능한 이미지의 일부로서 그것을 예약한다. 지정된 출력처 컬러 키에 의해 스프라이트를 출력처 표면에 블록 전송 하면, 스프라이트의 픽셀은, 출력처 컬러 키를 사용중의 출력처 위에의 픽셀에게만 블록 전송 된다. 법선의 출력처 픽셀은 보존되고 있으므로, 스프라이트가 출력처 표면 위에의 이미지의 배후를 횡단해 있는 것과 같게 보인다. 상세한 것에 대하여는, DirectX Foundation SDK의 「DirectDraw의 요점」섹션의 「표면」의 항내의 「투과형 블록 전송」을 참조할것.

CONST_D3DCOLORMODEL
디바이스에 의해 이행 되는 컬러 모델을 기술하는 열거형.

구문

Enum CONST_D3DCOLORMODEL
  D3DCOLOR_MONO = 1
  D3DCOLOR_RGB  = 2
End Enum
D3DCOLOR_MONO
흑백 모델 (램프 모델)의 사용을 시스템에 지시하는CONST_D3DCOLORMODEL 열거형으로부터의 값. 이 모델에서는, 버텍스의 색의 파랑 요소를 사용해, 비추어지는 버텍스의 휘도(Luminance)를 정의한다.
D3DCOLOR_RGB
풀 RGB 모델의 사용을 시스템에 지시하는CONST_D3DCOLORMODEL 열거형으로부터의 값.
D3DCOLORVALUE
색의 값을 기술하는 형태. r, g, b, a 는, 색의 적, 록, 청, 알파 요소를 지정한다. 이러한 값은, 일반적으로는 0.0에서 1.0의 범위에 있어, 0.0은 흑을 지정한다.

구문

Type D3DCOLORVALUE
  r As Single
  g As Single
  b As Single
  a As Single
End Type
D3DMATRIX
행렬을 기술하는 형태.

구문

Type D3DMATRIX
  rc11 As Single, rc12 As Single, rc13 As Single, rc14 As Single
  rc21 As Single, rc22 As Single, rc23 As Single, rc24 As Single
  rc31 As Single, rc32 As Single, rc33 As Single, rc34 As Single
  rc41 As Single, rc42 As Single, rc43 As Single, rc44 As Single
End Type
D3DPRIMCAPS
각 프리미티브 타입의 기능을 정의하는 형태. 상세한 것에 대하여는, 「DirectX Foundation SDK」를 참조할것.
D3DRECT
방형을 정의하는 형태.

구문

Type D3DRECT
  x1 As Long
  x2 As Long
  y1 As Long
  y2 As Long
End Type
D3DTRIANGLE
모든 삼각형의 베이스 타입을 기술하는 형태. 삼각형은 주요한 렌더링 원시적이다.
D3DVECTOR
Microsoft® Direct3D® 와 Direct3D 보관 유지 모드가 많은 메소드와 형태의 벡터를 정의하는 형태.

구문

Type D3DVECTOR
  x As Single
  y As Single
  z As Single
End Type
DirectDrawCreate
DirectDraw 오브젝트의 인스턴스를 생성 하는 함수.
DirectDrawCreateClipper
DirectDraw 오브젝트와 관련지을 수 있지 않은DirectDrawClipper오브젝트의 인스턴스를 생성 하는 함수.
Direct3D3
어플리케이션은,Direct3D3인터페이스의 메소드를 사용해 Direct3D 오브젝트를 생성 해, 환경을 세트 한다.
Direct3D3.GetDevicesEnum
이 메소드는, 시스템에 도입 끝난 모든 Direct3D 디바이스 드라이버를 열거한다.
DirectDrawClipper
어플리케이션은,IDirectDrawClipper인터페이스의 메소드를 사용해, 클립 리스트를 관리한다.
DirectDrawClipper.SetHWnd
이 메소드는, 클리핑 정보를 취득하는 윈도우 핸들을 세트 한다.
인타포레이타
인타포레이타는, 액션을 저장 한 후, 중간값을 자동 계산해, 오브젝트에 액션을 적용하는 방법을 제공한다. 예를 들어, 유저는 시간 0으로 빨강을, 시간 10으로 초록을 장면의 배경색에 세트 할 수가 있다. 그 후, 인타포레이타는 자동적으로, 연속하는 장면에 색조를 붙여 빨강으로부터 초록에 혼합하도록 할 수 있다. 인타포레이타를 사용해, 색을 혼합해, 다른 위치간에서 오브젝트를 원활히 이동해, 메쉬를 morphing 해, 게다가 다른 다양한 변환도 실시할 수가 있다.

Direct3D 보관 유지 모드에서는, 인타포레이타는, 유저가 애니메이션 할 수 있는 오브젝트 파라미터의 종류를 늘리는Direct3DRMAnimation2 인터페이스의 일반화이다. Direct3DRMAnimation2인터페이스가 오브젝트의 위치, 사이즈 및 방향의 애니메이션을 가능하게 하는 한편으로, 인타포레이타인타페이스는, 게다가 색, 메쉬, 텍스쳐, 머트리얼의 애니메이션을 가능하게 한다.

인타포레이타키
인타포레이타에 의해 저장 된 액션을 키라고 부른다. 키는, 저장 된 프로시저 호출로, 거기에 관련한 인덱스를 가진다. 인타포레이타는, 자동적으로 중간의 키값을 계산한다. 지원 되고 있는 인타포레이트 가능한 인터페이스 메소드의 하나를 호출해, 키를 인타포레이타안에 저장 한다. 메소드와 메소드에게 건네지는 파라미터값이 키를 구성한다. 인타포레이타 내부에 저장 되고 있는 각 키에는, 인덱스값이 있다. 키가 기록될 때, 키에는, 현재의 인타포레이타인젝스값의 스탬프가 밀린다. 이 키의 인덱스값은, 이 값을 일단 설정 하면 절대로 변할 것은 없다.
인타포레이타의 타입
오브젝트를 관련 타입의 인타포레이타에 접속할 수가 있다. 예를 들어,Direct3DRMMesh 오브젝트는,Direct3DRMMeshInterpolator 오브젝트에 접속할 수 있다. 인타포레이타의 타입은 다음과 같다.
  • FrameInterpolator
  • LightInterpolator
  • MaterialInterpolator
  • MeshInterpolator
  • TextureInterpolator
  • ViewportInterpolator

어느 인타포레이타를 다른 인타포레이타에 접속할 수 있다. 인타포레이타의 인덱스를 변경 하면, 접속된 인타포레이타의 인덱스가 같은 값으로 설정된다.

Direct3DRMMeshInterpolator에서는,Direct3DRMMeshInterpolator오브젝트의Direct3DRMMesh 인터페이스상에 있는SetVertices 를 호출하는 것으로,Direct3DRMMeshInterpolator오브젝트에SetVertices키를 추가한다. SetVertices와 함께 사용되는 그룹 인덱스는,Direct3DRMMesh 오브젝트 또는 인타포레이타가 적용되고 있는 오브젝트의 유효한 그룹 인덱스에 대응하고 있지 않으면 안 된다.

인타포레이타의 인덱스값
인타포레이타는, 어느 범위의 인덱스값을 받아들인다. 인덱스 범위는, 다음의 규칙에 의해 정해진다.
  • 범위의 시점은, 모든 키인덱스값과 현재의 인덱스안의 최소 값이다.
  • 범위의 종점은, 모든 키인덱스값과 현재의 인덱스안의 최대치이다.

보간 옵션의 상세한 것에 대하여는,CONST_D3DRMINTERPOLATIONFLAGS 열거형을 참조할것.

밉맵
밉맵과는 연속한 텍스쳐로, 각각의 텍스쳐는 해상도가 점차 낮아진다, 같은 이미지를 사전에 필터링 한 표현이다. 밉맵중의 각 필터링 이미지 또는 레벨은, 이전의 레벨보다 2의 거듭제곱씩 작아지고 있다. 고해상도 레벨은, 뷰아에 가까운 오브젝트에 사용된다. 오브젝트가 멀리 이동하는 것에 따라, 보다 저해상도의 레벨이 사용된다. MIP Mapping는, 텍스쳐의 렌더링 퀄리티를 향상하는, 계산상 비용이 들지 않는 방법이다. 상세한 것에 대하여는, 「Direct3D 직접 모드」의 「텍스쳐」의 「밉맵」을 참조할것.
텍스쳐 맵 포맷
광범위한 텍스쳐 픽셀 포맷이, Microsoft DirectX® 하드웨어 에뮬레이션 계층으로 지원 되고 있다. 이러한 포맷에 대해서는, 「DirectX Foundation DirectDraw 레퍼런스」의 「텍스쳐 맵 포맷」의 겉(표)를 참조할것.


샘플의 인트러덕션

이 마디에서는, Microsoft Developer Studio™를 사용해, Microsoft® Direct3D®보관 유지 모드의 샘플을 구축하는 방법을 설명한다. 샘플의 해설을 읽어, 참조하는 샘플을 결정하는 것.

  • Developer Studio 5.0을 사용한 샘플의 구축
  • 샘플


Developer Studio 5.0을 사용한 샘플의 구축

Microsoft® DirectX® Software Devepoler Kit에 동고 되고 있는 샘플에는, 커멘드 라인으로 샘플을 구축하는 makefile가 포함되어 있다. 샘플을 실행 하면, 내용을 확인할 수 있다. 흥미가 있는 샘플에 대해서는, 이해가 깊어져 코드를 변경한다. Microsoft Developer Studio™를 사용해, 샘플(또는 유저의 코드)을 구축해 디버그 하려면 , Developer Studio로 프로젝트를 생성 한다. 이 항에서는, Developer Studio Version 5.0으로 프로젝트를 생성 하는 방법에 대해 설명한다. 프로젝트 파일에는, 필요한 소스 파일과 라이브러리를 인클루드 해, Developer Studio를 적절한 라이브러리에서 구성해, 패스를 인클루드 해, 컴파일러가 필요한 라이브러리와 헤더 파일을 검출할 수 있도록(듯이) 할 필요가 있다.

주 샘플을 커멘드 라인으로 구축하는 정보에 대해서는, DirectX SDK Samples 디렉토리의 readme.txt를 읽는 것.

이 항에서는, 다음의 항목에 대해 설명한다.

  • 툴 옵션
  • 새로운 프로젝트의 생성
  • 프로젝트의 설정
  • 라이브러리의 추가
  • 작업 디렉토리의 설정
  • 파일을 프로젝트에 추가

툴 옵션

Developer Studio를 사용하려면 , DirectX SDK의 헤더 파일과 라이브러리 파일을 저장 하고 있는 패스를 지정할 필요가 있다. 여기서의 설정은, Developer Studio의 글로벌인 설정이 되어, 프로젝트 마다 설정을 반복할 필요는 없다.

이하의 순서에 따라, DirectX SDK의 헤더 파일과 라이브러리 파일의 저장처 디렉토리를 인클루드 및 라이브러리 파일의 검색 패스에 추가한다.

  1. Developer Studio의 [툴] 메뉴의 [옵션] 을 클릭한다.
  2. [디렉토리] 탭을 클릭한다.
  3. [표시하는 디렉토리] 박스의 [인클루드 파일] 을 클릭한다.
  4. [디렉토리] 박스의 점선으로 둘러싸인 사각형의 버튼을 클릭해, DirectX SDK의 인클루드 디렉토리를 풀 패스로 입력한다. 또는, 사각형의 버튼을 클릭했을 때에 엔트리 필드의 우측으로 표시되는 "..."(참조) 버튼을 클릭해, 적절한 디렉토리로 이동한다. 헤더 (인클루드) 파일은, 디폴트로 c:\mssdk\include에 인스톨 되고 있다.
  5. Enter키를 눌러, 입력을 완료한다. 필요에 따라서, 새로운 엔트리를 다시 선택해, 입력한 디렉토리명이 일람의 맨 위로 이동할 때까지, [아이템을 위에 이동] 버튼 (아이템을 위에 이동)을 클릭한다. 이렇게 하면(자), DirectX 파일이 검색 패스의 선두에 들어가, 파일명의 복제로 사용되게 된다.

    다음의 화면은,[옵션] 다이알로그 박스의 [디렉토리] 탭을 나타내고 있다. 디폴트의 인클루드 디렉토리가 디렉토리 일람의 맨 위에 있다.

    [옵션] 다이얼로그 박스의 [디렉토리] 탭

  6. 인클루드 디렉토리를 추가하면(자), 라이브러리 디렉토리를 추가한다. [표시하는 디렉토리] 박스의 [라이브러리 파일] 을 클릭한다.
  7. [디렉토리] 박스의 점선으로 둘러싸인 사각형의 버튼을 클릭해, DirectX SDK의 라이브러리 디렉토리를 풀 패스로 입력한다. 또는, "..."(참조) 버튼을 클릭해, 검색 패스를 지정한다. 라이브러리 파일은, 디폴트에서는 c:\mssdk\lib에 인스톨 되고 있다.
  8. Enter키를 눌러 입력을 완료한다. 필요에 따라서, 새로운 엔트리를 다시 선택해, 입력한 아이템이 디렉토리 일람의 맨 위로 이동할 때까지,[아이템을 위에 이동] 버튼을 클릭한다.

새로운 프로젝트의 생성

새로운 프로젝트를 생성 하려면 , 다음의 순서에 따른다.

  1. Developer Studio의 [파일] 메뉴의 [신규 생성] 을 클릭한다.
  2. [프로젝트] 탭을 클릭한다.
  3. 적절한 프로젝트 타입을 클릭한다. Windows®어플리케이션을 생성 하려면 ,[Win32 Application] 를 클릭한다.
  4. 프로젝트명을 입력한다.
  5. 장소를 지정해 프로젝트에의 패스를 편집하는지, 또는, "..."(참조) 버튼을 클릭해, 디렉토리를 지정한다. 프로젝트명이 패스에 추가되는 것에 주의한다.

프로젝트의 설정

이 마디에서는, 적절한 라이브러리를 프로젝트에 추가해, 작업 디렉토리를 설정하는 순서를 설명한다. 작업을 진행시키기 전에, Developer Studio로 프로젝트를 연다.

라이브러리의 추가

  1. Developer Studio의 [프로젝트] 메뉴의 [설정] 을 클릭한다.
  2. [링크] 탭을 클릭한다.
  3. [카테고리] 박스의 [일반] 을 클릭한다.
  4. [설정의 대상] 박스의 [모든 구성] 을 클릭한다.
  5. [오브젝트/라이브러리 모듈] 박스에 프로젝트에 필요한 라이브러리의 이름을 입력한다. 라이브러리명은 보통, 일람의 선두에 기술해, 정의가 코아라이브라리로부터 최초로 선택되도록(듯이) 한다.

    필요한 라이브러리는, 코드로 사용하는 기술에 의해, 프로젝트 마다 다르다. 특정의 샘플에 필요한 라이브러리를 모르는 경우는, 샘플 디렉토리에 있는 makefile를 검색해, 같은 라이브러리 리스트를 인클루드 한다. 다음의 표는, DirectX SDK로 일반적으로 인클루드 되는 라이브러리의 일람이다. Platform SDK로 인클루드 하는 Winmm.lib 라이브러리는, 멀티미디어 기능도 추가한다.
    DirectDraw | ddraw.lib
    Direct3D 보관 유지 모드 | d3drm.lib
    DirectSound | dsound.lib
    DirectPlay | dplayx.lib
    DirectInput | dinput.lib

    예를 들어, Tex1 샘플의makefile는, Microsoft DirectDraw®와 Direct3D®보관 유지 모드를 사용하기 위해(때문에), ddraw.lib와 d3drm.lib의 일람을 표시한다.

다음의 화면은,[프로젝트의 설정] 다이알로그 박스의 [링크] 탭을 나타내고 있다. 모든 구성의 설정이 지정되어 멀티미디어와 DirectX 라이브러리가, Developer Studio의 디폴트의 [오브젝트/라이브러리 모듈] 리스트에 추가되고 있다.

[프로젝트의 설정] 다이얼로그 박스의 [링크] 탭

작업 디렉토리의 설정

작업 디렉토리를 설정해, 프로그램이 특정의 파일을 검출할 수 있도록(듯이) 할 필요가 있다. 예를 들어, 프로그램이 상주하는 디렉토리로부터, 화면을 로드할 필요가 있다. 디폴트에서는, Developer Studio는 현재의 작업 디렉토리를 프로그램이 상주하는 디렉토리는 아니고, Developer Studio가 상주하는 디렉토리로 설정한다.

작업 디렉토리를 설정하려면 , 다음의 순서에 따른다.

  1. Developer Studio의 [프로젝트] 메뉴의 [설정] 을 클릭한다.
  2. [디버그] 탭을 클릭한다.
  3. [설정의 대상] 박스로 적절한 구성 (예를 들어,[모든 구성] 또는 [Win32 Debug])을 클릭한다.
  4. [작업용의 디렉토리] 박스에 작업 디렉토리를 풀 패스로 입력한다.

다음의 화면은,[프로젝트의 설정] 다이알로그 박스의 [디버그] 탭을 나타내고 있다. Win32 Debug 구성의 작업용 디렉토리가 지정되고 있다.

[프로젝트의 설정] 다이얼로그 박스의 [디버그] 탭

파일을 프로젝트에 추가

필요한 파일을 프로젝트에 추가하려면 , 다음의 순서에 따른다. 작업을 진행시키기 전에, Developer Studio를 열어 둔다.

  1. Developer Studio의 [프로젝트] 메뉴의 [프로젝트에 추가] 를 포인트 한다.
  2. 파일을 신규 생성 하는 경우는,[신규 생성] 을 클릭해, 파일 타입을 선택해, 파일명을 지정한다.
  3. 기존의 파일을 열고 있는 경우는,[파일] 을 클릭해, 프로젝트에 추가하는 파일을 선택한다.
  4. 모든 소스 파일 (. cpp 또는. c 파일), 리소스 파일 (. rc 파일), 그 외의 필요한 파일을 모두 추가할 때까지, 이상의 순서를 반복한다.
  5. Developer Studio의 [파일] 메뉴의 [모두 보존] 을 클릭해, 소스 코드, 프로젝트 파일, 작업 스페이스등의 모든 파일을 보존한다.


샘플

이 항에서는, Microsoft® Direct3D®보관 유지 모드의 샘플에 대해 해설한다. 각 샘플의 요약에서는, 샘플 마다, Microsoft DirectX®소프트웨어 개발 킷 (SDK)에 디폴트로 인스톨 되는 디렉토리와 샘플의 간단한 설명을 나타내 있다.

Direct3D 보관 유지 모드의 샘플은,RMBegin1 ,RMBegin2 ,RMEnum ,Viewer 를 제외해, 모든 샘플이RMMain 헬퍼 코드를 사용하고 있다. RMMain헬퍼 코드를 사용하는 전샘플은, Rmmain.cpp에 의해 어플리케이션의 메인 윈도우를 제공해, Rmmain.rc에 의해 메뉴와 가속기를 제공한다. 이러한 샘플은, Ddraw.lib 및 D3drm.lib libraries에도 링크하고 있다. 샘플의 각 디렉토리에는, Microsoft Developer Studio의 프로젝트 파일 (. dsp)가 인클루드 된다.. dsp 파일은, Developer Studio로 열려, 샘플을 구축하기 위해서 사용할 수 있다.

Direct3D 보관 유지 모드를 처음으로 사용하는 경우는, 최초로RMBegin1 ,RMBegin2 ,RMEnum ,Egg ,Globe ,Hier1 , 및Tex1 샘플을 참조할것.

다음의 항목에서는, 샘플 코드를 순서를 쫓아 상술하고 있다.

  • 오브젝트의 회전：RMBegin1 샘플
  • 프레임 계층：RMBegin2 샘플
  • 디바이스의 열거：RMEnum 샘플

샘플 일람

  • Egg
  • Faces
  • Fly
  • Globe
  • Hier1
  • Hier2
  • Morph
  • Quat
  • RMBegin1
  • RMBegin2
  • RMEnum
  • RMMain
  • Shadow
  • Tex1
  • Tex3
  • Tex4
  • Tex5
  • Trans
  • Uvis
  • Viewer

일부의 DirectX Foundation SDK 샘플은, 복수의 기술을 사용하고 있다. 이러한 샘플을 참조해, 각 기술이 어떻게 연계하고 있는지 확인할 수가 있다. 예를 들어,DS3dView DirectSound 샘플은, Direct3D 보관 유지 모드의 3 D오브젝트인Viewer 샘플의 단순한 확장이다. DS3dView를 사용 하면, 사운드를 오브젝트에 Attach 해, 오브젝트를 3 차원 공간에서 이동할 수 있다.

Egg

패스

mssdk\samples\multimedia\d3drm\src\Egg

설명

이 샘플은, 단일의 메쉬 오브젝트로 구성한 단순한 DirectX 파일을 로드한다. Egg.x는 Dxsdk\Media 디렉토리에 저장 되고 있다. 이 샘플은, 장면의 조명의 초기화, 메쉬 파일의 로드, 장면 위에의 egg 프레임의 생성, 메쉬의 프레임에의 추가, 프레임의 위치, 방향, 회전의 설정을 실시한다. 샘플은,IDirect3DRM3 (CreateFrame, CreateLightRGB, CreateMeshBuilder),IDirect3DRMFrame3 (SetPosition, AddLight, SetRotation, AddVisual, SetOrientation),IDirect3DRMMeshBuilder3 (Load)의 메소드를 사용하고 있다.

필요한 라이브러리

  • Ddraw.lib
  • D3drm.lib

필요한RMMain 코드

  • Rmmain.cpp
  • Rmmain.rc

Faces

패스

mssdk\samples\multimedia\d3drm\src\Faces

설명

이 샘플에서는, 메쉬 오브젝트를 1회에 대해 1개의 면을 생성 한다.

필요한 라이브러리

  • Ddraw.lib
  • D3drm.lib.

필요한RMMain 코드

  • Rmmain.cpp
  • Rmmain.rc

Fly

패스

mssdk\samples\multimedia\d3drm\src\Fly

설명

이 샘플은, 애니메이션을 사용해, 커브한 패스에 따라, 우주선의 위치를 설정한다.

필요한 라이브러리

  • Ddraw.lib
  • D3drm.lib

필요한RMMain 코드

  • Rmmain.cpp
  • Rmmain.rc

Globe

패스

mssdk\samples\multimedia\d3drm\src\Globe

설명

이 샘플은, 텍스쳐를 수반하는 단순한 단일의 메쉬로 구성한 DirectX 파일을 로드한다. 이것은 이하의 메소드를 사용한다.

  • IDirect3DRM3
    • CreateFrame
    • CreateLightRGB
    • CreateMeshBuilder
    • CreateMaterial
    • CreateWrap
    • LoadTexture
    • CreateAnimation
  • IDirect3DRMFrame3
    • GetScene
    • LookAt
    • SetPosition
    • AddLight
    • SetOrientation
    • SetRotation
    • AddVisual
    • AddMoveCallback
    • AddDestroyCallback
  • IDirect3DRMMeshBuilder3
    • Load
    • SetMaterial
    • Scale
    • SetColorRGB
    • GetBox
    • SetTexture
  • IDirect3DRMAnimation
    • SetFrame
    • SetTime
    • SetOptions
    • AddPositionKey
  • IDirect3DRMWrap
    • Apply
  • IDirect3DRMTexture3
    • SetShades

필요한 라이브러리

  • Ddraw.lib
  • D3drm.lib

필요한RMMain 코드

  • Rmmain.cpp
  • Rmmain.rc

Hier1

패스

mssdk\samples\multimedia\d3drm\src\Hier1

설명

이 샘플은, 2개의 메쉬로 구성하는 단순한 계층을 생성 해, 프레임의 개념을 구체적으로 가리킨다. 장면의 조명을 초기화해, 2개의 메쉬 파일을 로드해, 프레임 계층 (프레임내의 프레임) 생성 한다. Hier1는 텍스쳐를 로드해, 메쉬에 랩핑 해, 메쉬를 프레임에 추가해, 프레임의 위치, 방향, 회전을 설정한다.

필요한 라이브러리

  • Ddraw.lib
  • D3drm.lib

필요한RMMain 코드

  • Rmmain.cpp
  • Rmmain.rc

참조

Hier2

Hier2

패스

mssdk\samples\multimedia\d3drm\src\Hier2

설명

이 샘플은, 4개의 메쉬로 구성하는 단순한 계층을 구체적으로 가리키고 있다.

필요한 라이브러리

  • Ddraw.lib
  • D3drm.lib

필요한RMMain 코드

  • Rmmain.cpp
  • Rmmain.rc

참조

Hier1

Morph

패스

mssdk\samples\multimedia\d3drm\src\Morph

설명

이 샘플은, 보간의 사용법을 나타내고 있다.

필요한 라이브러리

  • Ddraw.lib
  • D3drm.lib

필요한RMMain 코드

  • Rmmain.cpp
  • Rmmain.rc

참조

IDirect3DRMInterpolator

Quat

패스

mssdk\samples\multimedia\d3drm\src\Quat

설명

이 샘플은, 쿼터니온을 사용해, 공간내의 2개의 벡터를 보간 한다.

필요한 라이브러리

  • Ddraw.lib
  • D3drm.lib

필요한RMMain 코드

  • Rmmain.cpp
  • Rmmain.rc

RMBegin1

패스

mssdk\samples\multimedia\d3drm\src\RMBegin1

설명

이 샘플은, Direct3D 보관 유지 모드의 디폴트 디바이스의 생성, DirectX 파일로부터의 메쉬의 로드, 조명의 추가, 메쉬 오브젝트 회전의 「요점」을 나타내고 있다. 샘플 코드 전체에 정중한 코멘트를 붙여, 코드의 목적을 설명하고 있다.

이 샘플은, 대부분의 Direct3D 보관 유지 모드 샘플과 달리,RMMain 헬퍼 파일, Rmmain.cpp, Rmmain.rc가 제공하는 확장 메뉴를 사용하지 않는다.

RMBegin1샘플의 코드의 자세한 것은, 「오브젝트의 회전: RMBegin1 샘플」을 참조할것.

RMBegin1샘플 코드로부터 구축한 샘플에 대해서는,RMBegin2 를 참조할것.

필요한 라이브러리

  • Ddraw.lib
  • D3drm.lib

RMBegin2

패스

mssdk\samples\multimedia\d3drm\src\RMBegin2

설명

이 샘플은, 프레임 계층의 「요점」을 나타내고 있다. DirectX 파일로부터 3개의 오브젝트를 로드해, 스케일링, 조명, 맵핑을 실시한다. 3개의 오브젝트는, 태양, 지구, 달을 나타내, 달은 지구의 주위를, 지구와 달은 태양의 주위를 돈다. 이 샘플은,RMBegin1 샘플로 사용한 코드로부터 구축한 것이다. RMBegin1 위에 의해 복잡한 장면을 구축해, 윈도우 사이즈를 변경해, WM_ACTIVATE와 WM_PAINT 메세지를 처리하고 있다. 샘플 코드 전체에 정중한 코멘트를 붙여, 코드의 목적을 설명하고 있다.

이 샘플은, 대부분의 Direct3D 보관 유지 모드 샘플과 달리,RMMain 헬퍼 파일, Rmmain.cpp, Rmmain.rc가 제공하는 확장 메뉴를 사용하지 않는다.

RMBegin2샘플의 코드의 자세한 것은, 「프레임 계층：RMBegin2 샘플」을 참조할것.

필요한 라이브러리

  • Ddraw.lib
  • D3drm.lib

RMEnum

패스

mssdk\samples\multimedia\d3drm\src\Rmenum

설명

이것은, 디바이스를 열거해, 최적인 디바이스를 선택해, Direct3D 보관 유지 모드 디바이스를 생성 하는 「요점」을 나타낸 샘플이다. 이 샘플에서는 렌더링은 전혀 실시하지 않는다. 코드를 읽기 쉽게 하기 위해서, 디바이스의 열거만을 취급하고 있다. 또, 유저가 메뉴로부터 디바이스를 선택할 수 있도록(듯이) 한다.

이 샘플은, 대부분의 Direct3D 보관 유지 모드 샘플과 달리,RMMain 헬퍼 파일, Rmmain.cpp, Rmmain.rc가 제공하는 확장 메뉴를 사용하지 않는다. Rmerror.c 파일의 에러 보고 기능을 사용하고 있다.

RMEnum샘플의 코드의 자세한 것은, 「디바이스의 열거：RMEnum 샘플」을 참조할것.

필요한 라이브러리

  • Ddraw.lib
  • D3drm.lib

RMMain

패스

mssdk\samples\multimedia\d3drm\src\Misc

설명

RMMain 헬퍼 코드는, Microsoft DirectDraw® 및 Direct3D 보관 유지 모드 오브젝트의 생성, 열거, 관리등이 일반적인 태스크를 처리해, 메뉴에 공통의 리소스를 제공한다. RMMain는, Direct3D 보관 유지 모드를 사용해, 렌더링용의 윈도우를 설정해, 샘플이 제공하는BuildScene함수를 호출해, 샘플의 장면을 구축해, Direct3D 보관 유지 모드를 사용해 장면을 렌더링 한다. 대부분의 Direct3D 보관 유지 모드 샘플은, 이 공통 코드에 링크하고 있어, 어플리케이션 고유의 코드를 매우 단순화 하고 있다. RMMain를 사용하는 샘플은, 윈도우 모드만으로 동작한다.

RMMain는 다수의 메뉴 항목도 제공하고 있어, 유저는 렌더링 옵션의 효과를 확인할 수 있다. 애니메이션을 1 순서씩 조작해, 렌더링용의 디바이스를 선택해, 쉐이딩 모드 (플랫 또는 그로)를 선택해, 조명과 디저링을 온 또는 오프로 설정해, 전부 칠해 옵션 (점, 와이어 프레임 또는 솔리드)을 선택할 수 있다.

RMMain 헬퍼 코드는, 다음의 파일로 구성되어 있다.
Rmmain.cpp | WinMain 및 메세지 핸들러를 인클루드 한 기본적인 소스 파일. Direct3D 보관 유지 모드를 생성 해, 보관 유지 모드를 사용해 렌더링용의 윈도우를 설정한 후, 샘플을 호출해 장면을 구축한다.
Resource.h | Rmmain.rc의 헤더 파일.
Rmmain.rc | Rmmain.cpp의 리소스 파일. 메뉴, 키보드 가속기, 및 [About] 다이알로그 박스를 제공한다.

Shadow

패스

mssdk\samples\multimedia\d3drm\src\Shadow

설명

이 샘플은 메쉬 오브젝트의 그림자를 생성 한다.

필요한 라이브러리

  • Ddraw.lib
  • D3drm.lib

필요한RMMain 코드

  • Rmmain.cpp
  • Rmmain.rc

Tex1

패스

mssdk\samples\multimedia\d3drm\src\Tex1

설명

이 샘플은, 원기둥(실린더) 맵핑을 사용해 텍스쳐를 맵핑 한 단순한 메쉬 오브젝트를 로드한다.

필요한 라이브러리

  • Ddraw.lib
  • D3drm.lib

필요한RMMain 코드

  • Rmmain.cpp
  • Rmmain.rc

참조

Tex3 , Tex4 , Tex5

Tex3

패스

mssdk\samples\multimedia\d3drm\src\Tex3

설명

이 샘플은, 프레임에 관련한 구(공)체 맵핑을 사용해, 특수 효과의 텍스쳐 랩핑을 사용한다.

필요한 라이브러리

  • Ddraw.lib
  • D3drm.lib

필요한RMMain 코드

  • Rmmain.cpp
  • Rmmain.rc

참조

Tex1 , Tex4 , Tex5

Tex4

패스

mssdk\samples\multimedia\d3drm\src\Tex4

설명

이 샘플은,카메라에 관련한 구(공)체 맵핑을 사용해, 특수 효과를 내기 위해서(때문에) 텍스쳐 랩핑을 사용한다. 텍스쳐는, 장면의 배경이라고 해도 사용되고 있다.

필요한 라이브러리

  • Ddraw.lib
  • D3drm.lib

필요한RMMain 코드

  • Rmmain.cpp
  • Rmmain.rc

참조

Tex1 , Tex3 , Tex5

Tex5

패스

mssdk\samples\multimedia\d3drm\src\Tex5

설명

이 샘플은, 크롬 맵핑의 랩핑, 및디칼로서 텍스쳐 맵핑을 사용하고 있다.

필요한 라이브러리

  • Ddraw.lib
  • D3drm.lib

필요한RMMain 코드

  • Rmmain.cpp
  • Rmmain.rc

참조

Tex1 , Tex3 , Tex4

Trans

패스

mssdk\samples\multimedia\d3drm\src\Trans

설명

이 샘플은, 투명한 텍스쳐 맵핑의 실례를 나타내고 있다. 입체의 구(공)을 회전시켜, 부분적으로 투명한 격자 모양의 입방체 2개(살)을 개별적으로 회전해, 구(공)체와 교차시킨다. 샘플은, 프레임, 조명, 메쉬 빌더, 메쉬, 텍스쳐, 머트리얼을 생성 한다. IDirect3DRMTexture3::SetDecalTransparency 를 호출해 디칼을 투명하게 한다.

필요한 라이브러리

  • Ddraw.lib
  • D3drm.lib

필요한RMMain 코드

  • Rmmain.cpp
  • Rmmain.rc

Uvis

패스

mssdk\samples\multimedia\d3drm\src\Uvis

설명

이 샘플은, Direct3D 보관 유지 모드로 Direct3D를 사용하는 방법을 나타내고 있다. Direct3D 보관 유지 모드 신의 비주얼로서 Direct3D 직접 모드의 실행 버퍼를 사용하는 방법을 나타낸다.

필요한 라이브러리

  • Ddraw.lib
  • D3drm.lib

필요한RMMain 코드

  • Rmmain.cpp
  • Rmmain.rc

Viewer

패스

mssdk\samples\multimedia\d3drm\src\Viewer

설명

Viewer (Direct3D Retained Mode Object Viewer)는, 3 D오브젝트를 로드해 표시하는 스탠드얼론 타입의 보관 유지 모드 어플리케이션이다.

최초의 장면에는 우상구석에 조명이 배치되고 있다. 조명을 보려면 ,T또는R키를 사용해, 전후로 이동한다. 추가의 오브젝트는,[File] 메뉴로부터 로드해, 새로운 조명은 [Lights] 메뉴로 추가한다. 마우스의 왼쪽 버튼으로 오브젝트를 회전해, 오른쪽 버튼으로 드러그 할 수 있다.

마지막에 회전 또는 드러그 한 오브젝트가 현재의 선택 아이템이 된다.

디바이스의 질은,[Renderer] 메뉴로 변경한다. 이 메뉴를 사용 하면, 사용하는 디바이스의 타입을 램프로부터 RGB로 전환할 수 있다. RGB 디바이스를 사용 하면, 장면의 조명이, 오브젝트의 컬러를 변경하는 것과 같이 변경할 수 있다. 256색모드에서는, RGB 디바이스를 디저링 처리 하면 최적인 결과를 얻을 수 있다.

제어 키는 다음과 같다.
T | 전방
R | 후방
Z | 현재의 선택 아이템을 전방으로 이동
X | 현재의 선택 아이템을 후방에 이동
Ctrl+G | gouraud shading
Ctrl+F | flat shading
Ctrl+D | dither(타글)
커서 키 | 좌/오른쪽/상/하에 이동
Del | 현재의 선택 범위를 삭제

필요한 라이브러리

  • Ddraw.lib
  • D3drm.lib
  • Comdlg32.lib
  • Winmm.lib
  • Msvcrt.lib


DirectX 파일 포맷

Microsoft® DirectX® version 6.0에서는, DirectX (. x) 파일의 읽기와 쓰기를 가능하게 하는 인터페이스와 메소드가 도입되었다. 상세한 것에 대하여는 「DirectX 파일 레퍼런스」를 참조할것.

이 마디는, DirectX 2.0으로 도입된 파일 포맷을 규정하는 것이다. 이 포맷의 바이너리판은, 계속되는 DirectX3. 0으로 릴리스 된 것이지만, 이 레퍼런스에서도 상술한다.

DirectX 파일 포맷은, 풍부한 템플릿 구동의 포맷으로, 메쉬, 텍스쳐, 애니메이션, 및 유저 정의 가능한 오브젝트를 저장 할 수가 있다. 애니메이션 세트를 사용하면, 미리 정의된 패스를, 리얼타임에서의 재생을 위해서(때문에) 저장 할 수가 있다. 인스턴스화나 계층도 지원 되고 있다. 인스턴스화는, 데이터는 1개의 파일에 한 번 만일 수 있는 저장 하는 한편으로, 메쉬등의 오브젝트에 대한 멀티 참조를 가능하게 한다. 계층은, 데이터 레코드간의 관계를 표현하는데 이용된다. DirectX 파일 포맷은, Microsoft Direct3D®보관 유지 모드 API에 의해, 네이티브의 파일 포맷으로서 사용되어 미리 정의된 오브젝트를 어플리케이션중에 읽어들이거나 리얼타임에 어플리케이션이 만들어낸 메쉬 정보를 기입하거나 하는 것을 지원 한다.

DirectX 파일 포맷은, 로 레벨의 데이터 프리미티브를 제공한다. 어플리케이션은, 그 위에 템플릿을 개입시켜보다 하이레벨의 프리미티브를 정의한다. 이 방법에 따라, Direct3D 보관 유지 모드는, 벡터, 메쉬, 행렬, 색등의 하이레벨의 프리미티브를 정의한다.

이하의 항으로, 파일 포맷의 API 독립의 기능과 Direct3D 보관 유지 모드가 파일 포맷을 사용하는 방법을 설명한다.

  • DirectX 파일 포맷 아키텍쳐
  • DirectX 파일 템플릿
  • DirectX 파일의 입방체의 예
  • DirectX 파일 바이너리 포맷
  • DirectX 파일 Conv3ds.exe 유틸리티
  • DirectX 파일 샘플
  • DirectX 파일 레퍼런스


DirectX 파일 포맷 아키텍쳐

Microsoft® DirectX®파일 포맷은, 아키텍쳐로부터 독립해, 문맥에 의존하지 않는 파일 포맷이다. 또, 템플릿 구동이며, 사용하는데 있어서 전제로 하는 지식을 필요로 하지 않는다. 이 파일 포맷은, 모든 클라이언트 어플리케이션이 사용할 수가 있어 현재, Microsoft Direct3D®보관 유지 모드가, 기하 데이터, 프레임 계층, 및 애니메이션을 기술하기 위해서 사용하고 있다.

이하의 섹션에서는, 이 파일 포맷의 내용과 구문을 설명한다. 파일 포맷은, DirectX Software Development Kit (SDK)에서의 사용시에는 확장자(extension). x를 사용한다.

  • 예약어(reserved word)
  • 헤더
  • 코멘트
  • 템플릿
  • 데이터
  • 콤마와 세미콜론의 사용법

예약어(reserved word)

이하의 말은, 예약되고 있으므로 사용해서는 안 된다.

  • ARRAY
  • BINARY
  • BINARY_RESOURCE
  • CHAR
  • CSTRING
  • DOUBLE
  • DWORD
  • FLOAT
  • SDWORD
  • STRING
  • SWORD
  • TEMPLATE
  • UCHAR
  • ULONGLONG
  • UNICODE
  • WORD

헤더

가변장 헤더는 필수이며, 데이터 스트림의 선두에 없으면 안 된다. 헤더는, 이하의 것을 포함한다.
타입 | 서브 타입 | 사이즈 | 내용 | 내용의 의미
magic number(필수) |  | 4바이트 | "xof " |
버젼 번호(필수) | 메이저 번호 | 2바이트 | 03 | 메이저 버젼 3
 | 마이너 번호 | 2바이트 | 02 | 마이너 버젼 2
포맷 타입(필수) |  | 4바이트 | "txt " | 텍스트 파일
 |  |  | "bin " | 바이노리필드
 |  |  | "tzip" | MSZip 압축 텍스트 파일
 |  |  | "bzip" | MSZip 압축 바이노리필드
부동 소수점 사이즈(필수) |  | 4바이트 | 0064 | 64 비트 부동 소수점
 |  |  | 0032 | 32 비트 부동 소수점

례

xof 0302txt 0064

코멘트

코멘트는, 텍스트 파일안만으로 적용할 수 있다. 코멘트는, 데이터 스트림중의 어디에라도 나타날 수가 있다. 코멘트는, C++식의 이중 slash "//"또는 샤프 문자 "#"로 시작된다. 코멘트는, 다음의 행에 계속할 수 있다.

# 이것은 코멘트이다.
// 이것도 코멘트이다.

템플릿

템플릿은, 데이터 스트림을 해석하는 방법을 정의한다. 데이터는, 템플릿 정의에 의해 조절된다. 이 마디에서는, 템플릿에 대해 설명한다.

  • 템플릿의 형식
  • 템플릿명
  • UUID
  • 멤버
  • 제약

템플릿의 예는 「예」에 나타낸다.

템플릿의 형식

템플릿의 형식은, 이하대로이다.

template <template-name> {
<UUID>
<member 1>;
...
<member n>;
[restrictions]
}

템플릿명

이것은, 영숫자로부터 되는 이름으로, 밑줄 문자의 것"_"을 포함해도 좋다. 숫자로 시작해는 안 된다.

UUID

국제적으로 결정할 수 있던 일의인 식별자(UUID)로, OSF DCE(Open Software Foundation's Distributed Computing Environment) 규격으로 포매트화 되어 꺾쇠 괄호의"<"와">"로 둘러싸인다. 예를 들어, <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> ]    // 제약 템플릿
}

특수한 템플릿이 1개있다. 그것은헤더템플릿이다. 각 어플리케이션이 헤더 템플릿을 정의해, 버젼 정보등의 어플리케이션에 특유의 정보를 정의하는 것을 추천 한다. 이 헤더는, DirectX 파일 포맷 API가 읽어들여,flags멤버가 사용 가능하면, 이하의 데이터를 해석하는 방법을 결정하는데 사용된다. flags멤버는, 정의하는 경우에는 DWORD로 할 필요가 있다. 비트 0의 1 비트가 현재 정의되고 있다. 이 비트가 클리어 되고 있으면, 파일중의 이하의 데이터는, 바이너리이며, 세트 되고 있으면, 이하의 데이터는, 텍스트이다. 멀티 헤더 데이터 오브젝트는, 파일 중(안)에서 바이너리와 텍스트를 바꾸는데 사용할 수 있다.

데이터

데이터 오브젝트는 실제의 데이터인가, 데이터에 대한 참조를 포함한다. 각각, 데이터형을 지정하는 대응하는 템플릿을 가진다.

데이터 오브젝트의 형식은 이하대로이다.

<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의 종료(container내부), 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;;
}


DirectX 파일 템플릿

Microsoft® Direct3D®보관 유지 모드에 의해 사용되는 템플릿의 일람을 다음에 나타낸다. Direct3D 보관 유지 모드의 데이터형에 정통하고 있는 것이 전제이다.

  • 템플릿명：Header
  • 템플릿명：Vector
  • 템플릿명：Coords2d
  • 템플릿명：Quaternion
  • 템플릿명：Matrix4x4
  • 템플릿명：ColorRGBA
  • 템플릿명：ColorRGB
  • 템플릿명：Indexed Color
  • 템플릿명：Boolean
  • 템플릿명：Boolean2d
  • 템플릿명：Material
  • 템플릿명：TextureFilename
  • 템플릿명：MeshFace
  • 템플릿명：MeshFaceWraps
  • 템플릿명：MeshTextureCoords
  • 템플릿명：MeshNormals
  • 템플릿명：MeshVertexColors
  • 템플릿명：MeshMaterialList
  • 템플릿명：Mesh
  • 템플릿명：FrameTransformMatrix
  • 템플릿명：Frame
  • 템플릿명：FloatKeys
  • 템플릿명：TimedFloatKeys
  • 템플릿명：AnimationKey
  • 템플릿명：AnimationOptions
  • 템플릿명：Animation
  • 템플릿명：AnimationSet

템플릿명：Header

UUID

<3D82AB43-62DA-11cf-AB39-0020AF71E433>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
major | WORD |  | 없음
minor | WORD |  |
flags | DWORD |  |

설명

이 템플릿은, DirectX 파일 포맷의 Direct3D 보관 유지 모드의 사용에 대해서 어플리케이션 고유의 헤더를 정의한다. 보관 유지 모드는, major 및 minor 플래그를 사용해, 보관 유지 모드 파일 포맷의 현재의 주버젼과 부버젼을 지정한다.

템플릿명：Vector

UUID

<3D82AB5E-62DA-11cf-AB39-0020AF71E433>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
x | FLOAT |  | 없음
y | FLOAT |  |
z | FLOAT |  |

설명

이 템플릿은, 벡터를 정의한다.

템플릿명：Coords2d

UUID

<F6F23F44-7686-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
u | FLOAT |  | 없음
v | FLOAT |  |

설명

메쉬의 텍스쳐 좌표를 정의하는데 사용하는 2 차원 벡터.

템플릿명：Quaternion

UUID

<10DD46A3-775B-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
s | FLOAT |  | 없음
v | Vector |  |

설명

현재미사용.

템플릿명：Matrix4x4

UUID

<F6F23F45-7686-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
matrix | array FLOAT | 16 | 없음

설명

이 템플릿은, 4×4 행렬을 정의한다. 프레임 변환 행렬에 사용된다.

템플릿명：ColorRGBA

UUID

<35FF44E0-6C7C-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
red | FLOAT |  | 없음
green | FLOAT |  |
blue | FLOAT |  |
alpha | FLOAT |  |

설명

이 템플릿은, 알파 성분을 가지는 컬러 오브젝트를 정의한다. 머트리얼 템플릿 정의중의 면의 색에 사용된다.

템플릿명：ColorRGB

UUID

<D3E16E81-7835-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
red | FLOAT |  | 없음
green | FLOAT |  |
blue | FLOAT |  |

설명

이 템플릿은, 기본적인 RGB 컬러 오브젝트를 정의한다.

템플릿명：Indexed Color

UUID

<1630B820-7842-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션 배열 사이즈
index | DWORD |
indexColor | ColorRGBA |

설명

이 템플릿은, 인덱스 파라미터와 RGBA 컬러로 구성되어 메쉬의 버텍스의 색을 정의하는데 사용한다. 인덱스는, 색을 적용하는 대상의 버텍스를 정의한다.

템플릿명：Boolean

UUID

<4885AE61-78E8-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
DWORD | truefalse |  | 없음

설명

단순한 불형을 정의한다. 이 템플릿은, 0또는 1을 세트 한다.

템플릿명：Boolean2d

UUID

<4885AE63-78E8-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
u | Boolean |  | 없음
v | Boolean |  |

설명

이 템플릿은, MeshFaceWraps 템플릿으로 사용되는 2개의 불리언 값세트를 정의해, 개별의 면의 텍스쳐 위상기하학을 정의한다.

템플릿명：Material

UUID

<3D82AB4D-62DA-11cf-AB39-0020AF71E433>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
faceColor | ColorRGBA |  | Any
power | FLOAT |  |
specularColor | ColorRGB |  |
emissiveColor | ColorRGB |  |

설명

이 템플릿은, 메쉬 전체 또는 메쉬의 개별의 면의 어딘가에 적용할 수 있는 기본적인 머트리얼의 색을 정의한다. power는, 머트리얼의 반사 지수이다. 앰비언트조명의 색이 알파 성분을 필요로 하는 것에 주의한다.

TextureFilename는, Direct3D 보관 유지 모드가 사용하는 옵션의 데이터 오브젝트이다. 이 오브젝트가 존재하지 않는 경우, 면은 텍스쳐화 되지 않는다.

템플릿명：TextureFilename

UUID

<A42790E1-7810-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
filename | STRING |  | 없음

설명

이 템플릿은, 메쉬 또는 면에 적용되는 텍스쳐의 파일명을 지정하는 것을 가능하게 한다. 이 템플릿이 머트리얼 오브젝트 내부에 나타날 필요가 있다.

템플릿명：MeshFace

UUID

<3D82AB5F-62DA-11cf-AB39-0020AF71E433>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
nFaceVertexIndices | DWORD |  | 없음
faceVertexIndices | array DWORD | nFaceVertexIndicies |

설명

이 템플릿은, 메쉬의 면을 정의하기 위해서, Mesh 템플릿이 사용한다. nFaceVertexIndices 배열의 각 요소는, 면을 만드는데 사용되는 메쉬 버텍스를 참조한다.

템플릿명：MeshFaceWraps

UUID

<4885AE62-78E8-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
nFaceWrapValues | DWORD |  | 없음
faceWrapValues | Boolean2d |  |

설명

이 템플릿은, 랩중의 각면의 텍스쳐 위상기하학을 정의하는데 사용한다. nFaceWrapValues 멤버의 값은, 메쉬내의 면의 수에 동일하게 할 필요가 있다.

템플릿명：MeshTextureCoords

UUID

<F6F23F40-7686-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
nTextureCoords | DWORD |  | 없음
textureCoords | array Coords2d | nTextureCoords |

설명

이 템플릿은, 메쉬의 텍스쳐 좌표를 정의한다.

템플릿명：MeshNormals

UUID

<F6F23F43-7686-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
nNormals | DWORD |  | 없음
normals | array Vector | nNormals |
nFaceNormals | DWORD |  |
faceNormals | array MeshFace | nFaceNormals |

설명

이 템플릿은, 메쉬의 법선을 정의한다. 벡터의 선두의 배열은, 그 자체가법선 벡터이며, 2번째의 배열은, 지정의 면에 어느 법선을 적용하는지를 지정하는 인덱스의 배열이다. nFaceNormals 멤버의 값은, 메쉬내의 면의 수에 동일하게 할 필요가 있다.

템플릿명：MeshVertexColors

UUID

<1630B821-7842-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
nVertexColors | DWORD |  | 없음
vertexColors | array IndexedColor | nVertexColors |

설명

이 템플릿은, 면 마다 또는 메쉬 마다 머트리얼을 적용하는 대신에, 메쉬의 버텍스의 색을 지정한다.

템플릿명：MeshMaterialList

UUID

<F6F23F42-7686-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
nMaterials | DWORD |  | Material
nFaceIndexes | DWORD |  |
FaceIndexes | array DWORD | nFaceIndexes |

설명

이 템플릿은, 메쉬 오브젝트로 사용되어 어느 머트리얼을 어느 면에 적용하는지를 지정한다. nMaterials 멤버는, 존재하는 머트리얼의 수 및 적용하는 머트리얼의 수를 지정한다.

템플릿명：Mesh

UUID

<3D82AB44-62DA-11cf-AB39-0020AF71E433>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
nVertices | DWORD |  | Any
vertices | array Vector | nVertices |
nFaces | DWORD |  |
faces | array MeshFace | nFaces |

설명

이 템플릿은, 단순한 메쉬를 정의한다. 1번째의 배열은, 버텍스의 리스트이며, 2번째의 배열은, 버텍스 배열에 대한 인덱스로서 메쉬의 면을 정의한다.

옵션의 데이터 요소

이하의 옵션의 데이터 요소가 Direct3D 보관 유지 모드에 의해 사용된다.

MeshFaceWraps | 지정하지 않는 경우, 디폴트로 u와 v의 양쪽 모두가 false로 설정된다.
MeshTextureCoords | 지정하지 않는 경우, 텍스쳐 좌표가 존재하지 않는다.
MeshNormals | 지정하지 않는 경우, 법선은 API의 GenerateNormals 메소드를 사용해 생성된다.
MeshVertexColors | 지정하지 않는 경우, 디폴트로 색은 흰색으로 설정된다.
MeshMaterialList | 지정하지 않는 경우, 디폴트로 머트리얼은 흰색으로 설정된다.

템플릿명：FrameTransformMatrix

UUID

<F6F23F41-7686-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
frameMatrix | Matrix4x4 |  | 없음

설명

이 템플릿은, 프레임 ( 및 그 아이 오브젝트 모두)에 대한 로컬 변환을 정의한다.

템플릿명：Frame

UUID

<3D82AB46-62DA-11cf-AB39-0020AF71E433>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
없음 |  |  | 임의

설명

이 템플릿은, 프레임을 정의한다. 현재, 프레임은 Mesh형의 오브젝트와 FrameTransformMatrix를 포함할 수가 있다.

옵션의 데이터 요소

이하의 옵션의 데이터 요소가 Direct3D 보관 유지 모드에 의해 사용된다.

FrameTransformMatrix | 이 요소를 지정하지 않는 경우, 로컬 변환이 프레임에 적용되지 않는다.
Mesh | 임의의 수의 메쉬 오브젝트가 프레임의 아이가 된다. 그러한 오브젝트는, 인 라인 또는 참조로 지정할 수가 있다.

템플릿명：FloatKeys

UUID

<10DD46A9-775B-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
nValues | DWORD |  | 없음
values | array FLOAT | nValues |

설명

이 템플릿은, 부동 소수점수(실수)의 배열과 그 배열중의 부동 소수점수(실수)의 수를 정의한다. 애니메이션 키세트를 정의하기 위해서 사용한다.

템플릿명：TimedFloatKeys

UUID

<F406B180-7B3B-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
time | DWORD |  | 없음
tfkeys | FloatKeys |  |

설명

이 템플릿은, 부동 소수점수(실수)세트와 애니메이션으로 사용되는 정의 시간을 정의한다.

템플릿명：AnimationKey

UUID

<10DD46A8-775B-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
keyType | DWORD |  | 없음
nKeys | DWORD |  |
keys | array TimedFloatKeys | nKeys |

설명

이 템플릿은, 애니메이션 키세트를 정의한다. keyType 멤버는, 키가 회전, 스케일 또는 위치 키 (각각 정수의 0, 1, 2를 사용해)의 어느쪽이든을 지정한다.

템플릿명：AnimationOptions

UUID

<E2BF56C0-840F-11cf-8F52-0040333594A3>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
openclosed | DWORD |  | 없음
positionquality | DWORD |  |

설명

이 템플릿은, Direct3D 보관 유지 모드의 애니메이션 옵션의 설정을 가능하게 한다. openclosed 멤버는, 클로즈드 애니메이션에 대해서는 0, 오픈 애니메이션에 대해서는 1으로 할 수 있다. positionquality 멤버는, 지정되고 있는 임의의 위치 키에 대해서 위치의 성질을 설정하기 위해서 사용해, 스플라인 위치에 대해서는 0, 선형 위치에 대해서는 1으로 할 수 있다. 디폴트에서는, 애니메이션은 클로우즈이다.

템플릿명：Animation

UUID

<3D82AB4F-62DA-11cf-AB39-0020AF71E433>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
없음 |  |  | 임의

설명

이 템플릿은, 이전의 프레임을 참조하는 애니메이션을 포함한다. 프레임에 대한 1개의 참조와 적어도AnimationKeys 의 1 세트를 포함할 필요가 있다. 또, AnimationOptions 데이터 오브젝트를 포함할 수도 있다.

옵션의 데이터 요소

이하의 옵션의 데이터 요소가 Direct3D 보관 유지 모드에 의해 사용된다.
AnimationKey | 애니메이션은, AnimationKey가 없으면 무의미하게 된다.
AnimationOptions | 이 요소를 지정하지 않는 경우, 애니메이션은 클로우즈이다.

템플릿명：AnimationSet

UUID

<3D82AB50-62DA-11cf-AB39-0020AF71E433>

멤버명 | 형 | 옵션 배열 사이즈 | 옵션 데이터 오브젝트
없음 |  |  | Animation

설명

AnimationSet 템플릿은, 복수의 Animation 오브젝트를 포함해, Direct3D 보관 유지 모드의 애니메이션 세트와 동등하다. 이것은, 애니메이션 세트내의 각 애니메이션의 시간이 임의의 점으로써 같은 것을 의미한다. 애니메이션 세트의 시간을 크고 하면, 그것이 포함한 모든 애니메이션에 대한 시간을 크게 하게 된다.


DirectX 파일의 입방체의 예

이 마디에서는, 단순한 입방체를 예로서 텍스쳐, 프레임, 애니메이션을 입방체에 추가하는 방법을 설명한다.

  • 단순한 입방체
  • 텍스쳐의 추가
  • 프레임과 애니메이션

단순한 입방체

이 파일은, 4개(살)의 붉은 면과 2살의 초록의 면을 가지는 단순한 입방체를 정의한다. 이 파일중의 옵션 정보가, Mesh 템플릿에 의해 정의되는 데이터 오브젝트에 정보를 추가하는데 사용되고 있는 것에 주의한다.

Material RedMaterial {
1.000000;0. 000000;0. 000000;1. 000000;;    // R = 1.0, G = 0.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 = 1.0, G = 0.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";
}
}

프레임과 애니메이션

이 항에서는, 프레임과 애니메이션을 단순한 입방체에 추가하는 방법을 설명한다.

  • 프레임
  • 애니메이션 세트와 애니메이션

프레임

프레임은 이하의 구조몸을 잡는 것이 요구된다.

Frame Aframe {        // 프레임명은 편의상 선택한 것이다.
FrameTransformMatrix {
...변환 데이터...
}
[메쉬 ]및/혹은[한층 더 프레임]
}

사전에 정의한 입방체 메쉬를 프레임 내부에 항등변환으로 둔다. 그 후, 애니메이션을 이 프레임에 추가한다.

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}        // 메쉬 인 라인을 사용할 수도 있다
                  // 하지만, 대신에 오브젝트 참조를 사용한다.
}

애니메이션 세트와 애니메이션

DirectX 파일 포맷중의 애니메이션과 애니메이션 세트는, Direct3D 보관 유지 모드의 애니메이션의 개념에 직접 맵 된다.

Animation Animation0 {        // 이름은 편의적으로 선택된 것이다.
{ 보통, 참조가 적용되는 프레임 }
AnimationKey {
...애니메이션 키 데이터...
}
{ ...한층 더 애니메이션 키... }
}

이 후, 다음과 같이 애니메이션은, 애니메이션 세트에 그룹화 된다.

AnimationSet AnimationSet0 { // 이름은 편의적으로 선택한 것이다.
{ 애니메이션 - 인 라인에서도 참조에서도 좋다 }
{ ... 한층 더 애니메이션 ... }
}

여기서 하는 것은, 애니메이션을 통해 입방체를 취하는 것이다.

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;;;
}
}
}


DirectX 파일 바이너리 포맷

이 마디에서는, DirectX 3.0의 릴리스로 도입된 Microsoft® DirectX®파일 포맷의 바이너리판을 상술한다. 이하는, 「DirectX 파일 포맷 아키텍쳐」를 이해한 후에 읽는 것이 바람직하다.

바이너리 포맷은, 텍스트 포맷의 토큰화 된 형식이다. 토큰은, standalone에서도, 프리미티브 데이터 레코드를 수반하고 있어도 좋다. standalone 토큰은, 문법의 구조를 주어 레코드 부수 토큰은, 필요한 데이터를 공급한다.

모든 데이터는, 승순의 포맷으로 저장 되는 것에 주의한다.

유효한 바이너리 데이터 스트림은, 헤더와 거기에 계속되는 템플릿과 데이터 오브젝트의 적어도 1개로부터 구성된다.

이 마디에서는, 바이노리필드 포맷의 이하의 부분을 설명한다.

  • 헤더
  • 토큰
  • 토큰 레코드
  • 템플릿
  • 데이터

게다가 템플릿의 예가 「템플릿의 예」로 제공되고 있다. 바이너리 데이터 오브젝트는 「데이터의 예」로 가리킨다.

헤더

이하의 정의는, 바이너리 헤더의 직접적인 읽고 쓰기를 실시할 때에 사용할 필요가 있다. 압축 데이터 스트림은, 현재 지원되어 있지 않기 때문에, 여기서 상술되어 있지 않은 것에 주의한다.

#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))

토큰

토큰은, 승순의 WORD로서 기입해진다. 토큰값의 리스트가 계속된다. 리스트는, 레코드 부수와 standalone 토큰으로 나눌 수 있다.

레코드 부수

#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_NAME는 가변장 레코드이다. token의 뒤에는 바이트수를 지정하는count값이 계속된다. count필드의 뒤에name필드가 계속된다. count 장의 ASCII명이 레코드의 마지막에 온다.
필드 | 형 | 사이즈(바이트) | 내용
token | WORD | 2 | TOKEN_NAME
count | DWORD | 4 | 바이트 단위의name필드장
name | BYTE array | Count | ASCII명

TOKEN_STRING

TOKEN_STRING는 가변장 레코드이다. token의 뒤에는, 바이트수를 지정하는count값이 계속된다. count필드의 뒤에string필드가 계속된다. count 장의 ASCII 캐릭터 라인이 종단 토큰의 앞에 온다. terminator의 선택은, 다른 개소에서 설명한 구문의 항목으로 결정된다.
필드 | 형 | 사이즈(바이트) | 내용
token | WORD | 2 | TOKEN_STRING
count | DWORD | 4 | 바이트 단위의string필드장
string | BYTE array | Count | ASCII 캐릭터 라인
terminator | DWORD | 4 | TOKEN_SEMICOLON 또는 TOKEN_COMMA

TOKEN_INTEGER

TOKEN_INTEGER는 고정장 레코드이다. token의 뒤에는, 필수의 정수값이 계속된다.
필드 | 형 | 사이즈(바이트) | 내용
token | WORD | 2 | TOKEN_INTEGER
value | DWORD | 4 | 단일 정수

TOKEN_GUID

TOKEN_GUID는 고정장 레코드이다. token의 뒤에는, 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 array | 8 | UUID 데이터 필드 4

TOKEN_INTEGER_LIST

TOKEN_INTEGER_LIST는 가변장 레코드이다. token의 뒤에는, 정수의 수를 지정하는count값이 계속된다. count필드의 뒤에는list필드가 계속된다. 효율을 올리기 (위해)때문에, 연속하는 정수 리스트는, 단일의 리스트에 결합할 필요가 있다.
필드 | 형 | 사이즈(바이트) | 내용
token | WORD | 2 | TOKEN_INTEGER_LIST
count | DWORD | 4 | list필드내의 정수의 수
list | DWORD array | 4 x count | 정수 리스트

TOKEN_FLOAT_LIST

TOKEN_FLOAT_LIST는 가변장 레코드이다. token의 뒤에는, 부동 소수점수(실수) 또는 배정밀도 부동 소수점수(실수)의 수를 지정하는count값이 계속되어,count필드의 값에는list필드가 계속된다. 부동 소수점수(실수)값의 사이즈(float 또는 double)는, 파일헤더중의float 사이즈값으로 결정된다. 효율을 올리기 (위해)때문에 연속하는 TOKEN_FLOAT_LIST는, 단일 리스트에 결합할 필요가 있다.
필드 | 형 | 사이즈(바이트) | 내용
token | WORD | 2 | TOKEN_FLOAT_LIST
count | DWORD | 4 | 필드안의 부동 소수점 또는 배정밀도 부동 소수점수(실수)의 수.
list | float/double array | 4×count 또는 8×count | 부동 소수점수(실수) 또는 배정밀도 부동 소수점수(실수)의 리스트

템플릿

템플릿의 구문 정의는, 이하대로이다.

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

데이터

데이터 오브젝트의 구문 정의는, 이하대로이다.

바이노리필드의 number_list 데이터와 float_list 데이터에는, TOKEN_COMMA와 TOKEN_SEMICOLON는 사용하지 않는다. string_list 데이터에는, 콤마와 세미콜론을 사용한다. 또, 옵션의 데이터 멤버에는, data_reference 밖에 사용할 수 없다.

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

템플릿의 예

2개의 바이너리 템플릿의 정의를 이하에 나타낸다. 데이터는, 이하의 예에는 나타나지 않은 승순 포맷으로 저장 되는 것에 주의한다.

클로즈드 템플릿의 RGB는, UUID {55b6d780-37ec-11d0-ab39-0020af71e433}로 식별되어 각각 float형의r,g,b의 3 멤버를 가진다.

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이다. 이하의 예에는 나타나지 않은 승순 포맷으로 저장 되는 것에 주의한다.

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 파일 Conv3ds.exe 유틸리티

Conv3ds.exe 유틸리티는, Autodesk 3-D Studio나 다른 모델링 패키지로 생성 된 3 D모델을 Microsoft® DirectX®파일 포맷으로 변환한다. 디폴트로, 템플릿 없음의 바이너리. x파일을 생성한다.

이 마디에서는, 이하의 항목을 설명한다.

  • Conv3ds.exe의 사용
  • Conv3ds.exe 옵션 인수
  • 광파 오브젝트로부터 생성 되는 3 DS파일
  • 힌트와 조언

Conv3ds.exe의 사용

Conv3ds.exe는 옵션없이 기동할 수가 있어 프레임의 계층을 포함한다. x파일을 생성한다. 예를 들어, 이하의 커멘드를 생각해 본다.

conv3ds File. 3ds

이 커멘드는,. 3 ds파일로부터,. x파일을 생성한다. 프레임을 로드하기 위해서(때문에)는IDirect3DRMFrame3::Load 를 이용할 수가 있다.

Conv3ds.exe 옵션 인수

Conv3ds.exe -A

. 3 ds파일에 키 프레임 데이터가 포함되는 경우, 애니메이션 세트를 저장 한다. x파일을 생성 하려면 ,-A옵션을 이용한다. 커멘드는 이하와 같이 된다.

conv3ds -A File. 3ds

File. 3ds파라미터는, 변환하려고 하는 파일의 이름이다. IDirect3DRMAnimationSet2::Load 를 이용해, 애니메이션을 로드할 수가 있다.

Conv3ds.exe -m

. 3 ds파일에 있는 모든 오브젝트로부터 되는 1개의 메쉬를 저장 한다. x파일을 만들려면 ,-m옵션을 이용한다.

conv3ds -m File. 3ds

메쉬를 로드하려면 ,IDirect3DRMMeshBuilder3::Load 를 이용한다.

Conv3ds.exe -T

1개의 톱 레벨 프레임에 있는 모든 오브젝트 및 프레임 계층을 랩 하려면 ,-T옵션을 이용한다. 이 옵션을 사용하면(자),IDirect3DRMFrame3::Load 를 한 번 호출하는 것만으로,. 3 ds파일중의 모든 프레임이나 오브젝트를 로드할 수가 있다.. x파일의 최초의 톱 레벨 프레임 계층이 로드 된다. 다른 모든 프레임이나 메쉬를 저장 하는 프레임은,"x3ds_filename" (. 3 ds확장자(extension) 없음)으로 불린다. -T옵션은-m옵션과 함께 이용되면(자), 아무런 효과는 없다.

Conv3ds.exe -s

-s옵션을 이용하면(자),. 3 ds파일중의 모든 오브젝트를 변환하는 축척 계수를 지정할 수가 있다. 예를 들어, 다음의 커멘드는 모든 오브젝트를 10배 크게 한다.

conv3ds -s10 File. 3ds

다음의 커멘드는 모든 오브젝트를1/10로 한다.

conv3ds -s0. 1 File. 3ds

Conv3ds.exe -r

-r옵션은,. 3 ds파일이 변환될 때, 면을 감는 순서를 역전시킨다.. 3 ds파일을 변환해 Direct3D로 보았을 때에 오브젝트가 반대가 되어 있는 것 같으면,-r옵션으로 변환을 시도하는 것.. 3 ds파일로서 export 되는 모든 광파 모델은, 이 옵션을 필요로 한다. 상세한 것에 대하여는, 「광파 오브젝트로부터 생성 되는 3 DS파일」을 참조할것.

Conv3ds.exe -v

-v옵션은, 장황 출력 모드를 온으로 한다. 그 때에 정수를 지정한다. 현재 지원 되고 있는 정수를, 이하의 겉(표)에 나타낸다.
옵션 | 의미
-v0 | 디폴트. 장황 모드를 오프로 한다.
-v1 | 부정한 오브젝트에 대한 경고를 인쇄해, 컨버터가 가고 있는 것 붙은 일반 정보를 인쇄한다.
-v2 | 기본 키 프레임 정보, 변환 프로세스에 포함할 수 있고 있는 오브젝트, 및 보존중의 오브젝트에 대한 일반 정보를 인쇄한다.
-v3 | 매우 장황. 대부분은, 디버그 정보에 유용.

Conv3ds.exe -e

-e옵션에 의해, 텍스쳐 맵 파일의 확장자(extension)를 변경할 수가 있다. 예를 들어, 다음의 커멘드를 생각한다.

conv3ds -e"ppm" File. 3ds

File. 3 ds가 텍스쳐 맵 파일 Brick.gif를 참조하는 오브젝트를 저장 하고 있으면(자),. x파일은 텍스쳐 맵 파일 Brick.ppm을 참조한다. 컨버터는 텍스쳐 맵 파일을 변환하지 않는다. 생성된다. x파일을 로드할 때, 텍스쳐 맵 파일은 D3DPATH에 없으면 안 된다. D3DPATH는, 디폴트 검색 패스로 설정되어 있는 환경 변수이다.

Conv3ds.exe -x

-x옵션을 사용하면(자), 바이너리. x파일은 아니고, 텍스트. x파일을 생성 할 수가 있다. 텍스트 파일은 커지지만, 편집은 간단하다.

Conv3ds.exe -X

-X옵션을 사용하면(자), 파일에 Direct3D 보관 유지 모드의. x파일의 템플릿을 포함할 수가 있다. 디폴트로, 템플릿은 포함되지 않는다.

Conv3ds.exe -t

-t옵션은, 생성 된다. x파일이 텍스쳐 정보를 저장 하지 않게 지정한다.

Conv3ds.exe -N

-N옵션은, 생성 된다. x파일이법선 벡터정보를 저장 하지 않게 지정한다. Direct3D 보관 유지 모드의 로드 호출은 모두,. x파일에 법선 벡터를 가지지 않는 오브젝트에 대해서 법선 벡터를 생성한다.

Conv3ds.exe -c

-c옵션은, 생성 된다. x파일이 텍스쳐 좌표를 저장 하지 않게 지정한다. 디폴트에서는,-m옵션을 이용하고 있는 경우,. 3 ds오브젝트가 텍스쳐 좌표를 가지지 않으면, 출력되는 메쉬는 (0,0) uv 텍스쳐 좌표를 가진다.

Conv3ds.exe -f

-f옵션은, 생성 된다. x파일이 프레임 변환 행렬을 저장 하지 않게 지정한다.

Conv3ds.exe - z및Conv3ds.exe -Z

-z및-Z옵션에 의해,. x파일에 있는 오브젝트에 의해 참조되는 모든 머트리얼의 알파면컬러값을 조정할 수 있게 된다. 예를 들어, 다음의 커멘드에 의해,Conv3ds.exe는 0.2 미만의 모든 알파값에 0.1을 더한다.

conv3ds -z0. 1 -Z0. 2 File. 3ds

다음의 커멘드에 의해, Conv3ds.exe는 모든 알파의 알파값으로부터 0.2를 공제한다.

conv3ds-z"-0. 2" -z1 File. 3ds

Conv3ds.exe -o

-o옵션에 의해, 생성 되는 x파일의 파일명을 지정할 수 있게 된다.

Conv3ds.exe -h

-h옵션은, 3 ds파일(보통은 키 프레머로 생성 된다)의 계층 정보를 분석하지 않게 컨버터에게 전한다. -m옵션이 이용되지 않으면, 모든 오브젝트는 톱 레벨 프레임으로 출력된다.

광파 오브젝트로부터 생성 되는 3 DS파일

광파의 Trans3d 플러그 인에 의해 export 된다. 3 ds파일에는, 몇개의 문제가 있다. 이것들을 처리하려면 , 다음의 Conv3ds.exe 커멘드를 이용하는 것이 좋다.

conv3ds -r -N -f -h -T|m trans3dfile. 3ds

Trans3d나 광파 오브젝트 에디터에 의해 생성 되는 모든. 3 ds오브젝트는, 그 권 순서를 역전할 필요가 있다. 그렇게 하지 않으면, 표시할 경우에 「반대」가 되어 버린다. 이러한 오브젝트에는, 표면 법선 벡터 정보는 저장 하고 있지 않다.

힌트와 조언

Conv3ds.exe에 의해 생성 된 오브젝트를 Direct3D 보관 유지 모드뷰와에 로드해 볼 수가 없을 때, 축척 계수를 약 100으로 해 스케일링 옵션-s를 이용한다. 이것은,. x파일중의 오브젝트의 척도를 증대시킨다.

오브젝트를 뷰와에 로드해, flat shading로부터 gouraud shading로 바꾼 후, 오브젝트가 다크 그레이에 변색했을 경우,-N 옵션으로 재차 변환을 시도한다.

오브젝트가 변환되고 나서 텍스쳐가 로드 되지 않는 경우,-e 옵션을 이용해 오브젝트가. ppm 파일 또는. bmp 파일을 참조하고 있는 것을 확인한다. 또, 텍스쳐의 폭 및 높이가 2의 거듭제곱인 일도 확인한다. 게다가 텍스쳐가 D3DPATH안의 하나의 디렉토리에 저장 되고 있는 것을 확인한다.

현재, Conv3ds.exe는,. 3 ds애니메이션으로 이용되는 더미 프레임을 처리하지 못하고, 무시해 버린다. 다만, 아이 오브젝트는 변환한다.


DirectX 파일 샘플

이하의 샘플로, Microsoft® DirectX®파일 포맷의 로드, 변환, 및 보존의 데먼스트레이션을 실시한다. 이러한 샘플은 DirectX Foundation 6. x Software Development Kit (SDK)에 포함되어 있어 Mssdk\Samples\Multimedia\D3drm\Src 디렉토리하의 폴더에 들어가 있다.

  • CONVXFMT
  • XOFLOAD
  • XOFSAVE
  • XOFUSER

CONVXFMT

패스

Mssdk\Samples\Multimedia\D3drm\Src\Convxfmt

설명

어느 DirectX 파일 포맷을, 다른 포맷으로 변환한다.

XOFLOAD

패스

Mssdk\Samples\Multimedia\D3drm\Src\Xofload

설명

Direct3D 보관 유지 모드의 템플릿을 사용해 파일을 로드한다.

XOFSAVE

패스

Mssdk\Samples\Multimedia\D3drm\Src\Xofsave

설명

Direct3D 보관 유지 모드의 템플릿을 사용해 파일을 보존한다.

XOFUSER

패스

Mssdk\Samples\Multimedia\D3drm\Src\Xofuser

설명

유저 정의의 템플릿을 사용해 파일을 보존한다.


DirectX 파일 레퍼런스

이 마디에서는, DirectX version 6.0으로 도입된, Microsoft® DirectX® (. x) 파일의 읽고 쓰기에 사용하는 함수, 인터페이스, 오브젝트, 데이터형에 대해 해설한다. 또, 인터페이스간의 관계를 간단하게 소개해, 인터페이스의 계승을 나타내는 계층도도 가리킨다. DirectX 파일의 메소드는, 텍스트 파일과 바이노리필드의 어느 쪽의 읽고 쓰기에도 사용할 수 있다.

이러한 인터페이스를 사용할때는, 「DirectX 파일 포맷 아키텍쳐」로 해설하고 있는DirectX 파일의 포맷에 정통해 둘 필요가 있다. 파일 포맷을 이해하고 있으면(자), 인터페이스와 그 메소드의 목적을 보다 이해하기 쉬워진다.

이 마디에는, 다음의 항목이 포함되어 있다.

  • 처음에
  • 인터페이스 계층
  • 함수와 인터페이스
  • 데이터형
  • 반환값

처음에

DirectX (. x) 파일로부터의 데이터의 로드 방법과 DirectX (. x) 파일에의 데이터의 보존 방법에 대해, 개요를 설명한다. DirectX 파일 메소드는, 텍스트와 바이너리의 양쪽 모두의 DirectX 파일을 취급해, 파일, 메모리, 리소스, URL 등, 각종 소스로부터의 로드를 지원 하고 있다.

DirectX 파일의 인터페이스를 사용하려면 , 우선DirectXFileCreate 함수를 사용해 IDirectXFile 오브젝트를 생성 한다.

파일의 로드

다음의 순서로 DirectX 파일을 로드한다.

  1. DirectXFileCreate 함수를 사용해,IDirectXFile 오브젝트를 생성 한다.
  2. 로드하는 DirectX 파일에 템플릿이 존재하지 않는 경우,IDirectXFile::RegisterTemplates 메소드를 사용해 템플릿을 등록한다.
  3. IDirectXFile::CreateEnumObject 메소드를 사용해,IDirectXFileEnumObject 열거 오브젝트를 생성 한다.
  4. 파일내의 오브젝트 마다 반복한다. 오브젝트 마다, 다음의 스텝을 실행한다.
    1. IDirectXFileEnumObject::GetNextDataObject 메소드를 사용해,IDirectXFileData 오브젝트를 취득한다.
    2. IDirectXFileData::GetType 메소드를 사용해, 데이터형을 취득한다.
    3. IDirectXFileData::GetData 메소드를 사용해, 데이터를 로드한다.
    4. 오브젝트에 옵션의 멤버가 있을 때는,IDirectXFileData::GetNextObject 메소드를 호출해, 그 옵션의 멤버를 취득한다.
  5. IDirectXFileData 오브젝트를 릴리즈 한다.
  6. IDirectXFileEnumObject 오브젝트를 릴리즈 한다.
  7. IDirectXFile 오브젝트를 릴리즈 한다.

파일의 보존

다음의 순서로, DirectX 파일의 템플릿과 데이터를 DirectX 파일에 보존한다.

  1. DirectXFileCreate 함수를 사용해,IDirectXFile 오브젝트를 생성 한다.
  2. IDirectXFile::RegisterTemplates 메소드를 사용해, 지금부터 사용하는 템플릿을 DirectX 파일 시스템에 통지한다.
  3. IDirectXFile::CreateSaveObject 메소드를 사용해,IDirectXFileSaveObject 오브젝트를 생성 한다.
  4. 필요하게 응해IDirectXFileSaveObject::SaveTemplates 메소드를 사용해, 템플릿을 보존한다.
  5. 보존하는 오브젝트 마다 반복한다. 톱 레벨의 오브젝트 마다, 다음의 스텝을 실행한다.
    1. IDirectXFileSaveObject::CreateDataObject 메소드를 사용해, 파일의 톱 레벨의 오브젝트로서IDirectXFileData 오브젝트를 생성 한다. 톱 레벨의 데이터 오브젝트에 옵션의 아이 오브젝트가 있는 경우, 다음의 스텝의 「추가 방법」의 란에 있는 적절한 메소드를 사용해, 오브젝트에 아이 오브젝트를 추가한다.
    2. IDirectXFileData 오브젝트의 템플릿이 허가하고 있으면, 각 오브젝트는 옵션의 아이 오브젝트를 가질 수가 있다. 아이 오브젝트는,IDirectXFileData,IDirectXFileDataReference , 또는IDirectXFileBinary 의 3개의 오브젝트 타입 가운데, 어떤 것이라도 좋다. 보존할 필요가 있는 오브젝트 마다 반복해, 다음 표에 있는, 오브젝트 타입에 맞은 방법으로, 옵션의 아이 멤버를 오브젝트 리스트에 추가한다.
      오브젝트 타입 | 추가 방법
      데이터 | IDirectXFileSaveObject::CreateDataObject 메소드를 호출해IDirectXFileData 오브젝트를 생성 해, 다음에IDirectXFileData::AddDataObject 메소드를 호출해 오브젝트의 자식으로 추가한다.
      데이터 참조 | IDirectXFileData::AddDataReference 메소드를 호출해, 데이터 참조 오브젝트를 오브젝트의 자식으로 생성 해 추가한다.
      바이너리 | IDirectXFileData::AddBinaryObject 메소드를 호출해, 바이너리 오브젝트를 오브젝트의 자식으로 생성 해 추가한다.
    3. IDirectXFileSaveObject::SaveData 메소드를 호출해, 데이터 오브젝트와 아이 오브젝트를 모두 보존한다.
    4. IDirectXFileData 오브젝트를 릴리즈 한다.
  6. IDirectXFileSaveObject 오브젝트를 릴리즈 한다.
  7. IDirectXFile 오브젝트를 릴리즈 한다.

인터페이스 계층

DirectX 파일 인터페이스간의 관계를 이하에 나타낸다.

 IUnknown
 |
 +--IDirectXFile
 |
 +--IDirectXFileEnumObject
 |
 +--IDirectXFileObject
 |  |
 |  +--IDirectXFileBinary
 |  |
 |  +--IDirectXFileData
 |  |
 |  +--IDirectXFileDataReference
 |
 +--IDirectXFileSaveObject

함수와 인터페이스

DirectX에서는, 다음의 DirectX 파일 함수와 인터페이스가 준비되어 있다.

  • DirectXFileCreate 함수
  • IDirectXFile
  • IDirectXFileBinary
  • IDirectXFileData
  • IDirectXFileDataReference
  • IDirectXFileEnumObject
  • IDirectXFileObject
  • IDirectXFileSaveObject

다음 표로, DirectX 파일의 각 인터페이스에 대응하는 글로벌 유니크 식별자(GUID)를 나타낸다. QueryInterface메소드로 GUID를 사용해, 아이 오브젝트의 타입을 판별하는 방법에 대해서는,IDirectXFileData 인터페이스의 「처음에」를 참조할것.
인터페이스 | GUID
IDirectXFile | IID_IDirectXFile
IDirectXFileBinary | IID_IDirectXFileBinary
IDirectXFileData | IID_IDirectXFileData
IDirectXFileDataReference | IID_IDirectXFileDataReference
IDirectXFileEnumObject | IID_IDirectXFileEnumObject
IDirectXFileObject | IID_IDirectXFileObject
IDirectXFileSaveObject | IID_IDirectXFileSaveObject

DirectXFileCreate 함수

DirectXFileCreate함수는,IDirectXFile 인터페이스를 생성 한다.

구문

STDAPI DirectXFileCreate(LPDIRECTXFILE *ppDirectXFile);

파라미터

ppDirectXFile
생성 된IDirectXFile 인터페이스를 받는 포인터의 주소.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

주의

이 함수를 사용한 후,IDirectXFile 메소드를 사용해, 템플릿의 등록 (RegisterTemplates ), 열거 오브젝트의 생성 (CreateEnumObject ), 또는 보존 오브젝트의 생성 (CreateSaveObject )을 실시한다.

IDirectXFile

IDirectXFile 인터페이스에 의해,IDirectXFileEnumObject 오브젝트와IDirectXFileSaveObject 오브젝트를 생성 해, 템플릿을 등록할 수가 있다.

DirectXFileCreate 함수를 사용해, 이 오브젝트의 인스턴스를 생성 한다.

IDirectXFile인터페이스에서는, 다음의 메소드가 준비되어 있다.

  • CreateEnumObject
  • CreateSaveObject
  • RegisterTemplates

IDirectXFile::CreateEnumObject

IDirectXFile

열거 오브젝트를 생성 한다.

구문

HRESULT CreateEnumObject(
  LPVOID pvSource,
  DXFILELOADOPTIONS dwLoadOptions,
  LPDIRECTXFILEENUMOBJECT * ppEnumObj);

파라미터

pvSource
이 포인터가 가리키는 데이터의 내용은,dwLoadOptions의 값에 의해 다음 표와 같이 다르다.
dwLoadOptions값 | pvSource의 내용
DXFILELOAD_FROMFILE | 파일명
DXFILELOAD_FROMRESOURCE | DXFILELOADRESOURCE 구조체
DXFILELOAD_FROMMEMORY | DXFILELOADMEMORY 구조체
DXFILELOAD_FROMURL | URL(Uniform Resource Locator)의 이름
dwLoadOptions
데이터의 소스를 지정하는 값. DXFILELOADOPTIONS 값의 하나.
ppEnumObj
생성 된IDirectXFileEnumObject 인터페이스를 받는 포인터의 주소.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADALLOC
DXFILEERR_BADFILEFLOATSIZE
DXFILEERR_BADFILETYPE
DXFILEERR_BADFILEVERSION
DXFILEERR_BADRESOURCE
DXFILEERR_BADVALUE
DXFILEERR_FILENOTFOUND
DXFILEERR_RESOURCENOTFOUND
DXFILEERR_URLNOTFOUND

주의

이 메소드를 사용한 후,IDirectXFileEnumObject 메소드의 하나를 사용해, 데이터 오브젝트를 취득한다.

IDirectXFile::CreateSaveObject

IDirectXFile

IDirectXFileSaveObject 오브젝트의 인스턴스를 생성 한다.

구문

HRESULT CreateSaveObject(
  LPCSTR szFileName,
  DXFILEFORMAT dwFileFormat,
  LPDIRECTXFILESAVEOBJECT * ppSaveObj);

파라미터

szFileName
데이터를 보존하는 파일의 이름에의 포인터.
dwFileFormat
파일 포맷. DXFILEFORMAT 정수의 하나.
ppSaveObj
생성 된IDirectXFileSaveObject 오브젝트를 받는 포인터의 주소.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADALLOC
DXFILEERR_BADFILE
DXFILEERR_BADVALUE

주의

이 메소드를 사용한 후,IDirectXFileSaveObject 인터페이스의 메소드를 사용해, 데이터 오브젝트를 생성 해, 템플릿이나 데이터를 보존한다.

IDirectXFile::RegisterTemplates

IDirectXFile

커스텀 템플릿을 등록한다.

구문

HRESULT RegisterTemplates(
  LPVOID pvData,
  DWORD cbSize);

파라미터

pvData
DirectX 파일을 구성하는 버퍼에의 포인터. DirectX 파일은, 템플릿을 포함한 텍스트 또는 바이너리 포맷이다.
cbSize
pvData가 가리키는 버퍼의 사이즈. 단위는 바이트.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADFILEFLOATSIZE
DXFILEERR_BADFILETYPE
DXFILEERR_BADFILEVERSION
DXFILEERR_BADVALUE
DXFILEERR_PARSEERROR

주의

다음의 코드는,RegisterTemplates의 호출예와pvData가 가리키는 버퍼 내용의 예이다.

IDirectXFile * 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 (유니버설 유니크 식별자)를 지정해야 한다.

IDirectXFileBinary

IDirectXFileBinary 인터페이스에 의해, 바이너리 데이터의 read와 데이터에 관한 정보의 취득을 할 수 있다.

IDirectXFileBinary인터페이스에서는, 다음의 메소드가 준비되어 있다.

  • GetMimeType
  • GetSize
  • Read

또,IDirectXFileBinary는,IDirectXFileObject::GetId 메소드와IDirectXFileObject::GetName 메소드를 계승한다.

IDirectXFileBinary::GetMimeType

IDirectXFileBinary

바이너리 데이터의 mime 타입을 취득한다.

구문

HRESULT GetMimeType(LPCSTR * pszMimeType);

파라미터

pszMimeType
mime 타입의 캐릭터 라인을 받는 포인터의 주소.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADVALUE

지정되었다. X파일의 바이너리 오브젝트에 Mime 타입이 지정되어 있지 않은 경우, 이 함수는*pszMimeType에 NULL를 설정한다.

IDirectXFileBinary::GetSize

IDirectXFileBinary

바이너리 데이터의 사이즈를 취득한다.

구문

HRESULT GetSize(DWORD * pcbSize);

파라미터

pcbSize
바이너리 데이터의 사이즈를 받는 포인터. 단위는 바이트.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADVALUE

IDirectXFileBinary::Read

IDirectXFileBinary

바이너리 데이터를 읽어낸다.

구문

HRESULT Read(
  LPVOID pvData,
  DWORD cbSize,
  LPDWORD pcbRead);

파라미터

pvData
읽어내진 데이터를 받는 버퍼에의 포인터.
cbSize
pvData가 가리키는 버퍼의 사이즈. 단위는 바이트.
pcbRead
읽어내진 바이트수에의 포인터.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADVALUE
DXFILEERR_NOMOREDATA

IDirectXFileData

IDirectXFileData인터페이스에서는, 데이터 오브젝트의 직접 계층의 구축 또는 액세스가 생기는 메소드가 준비되어 있다. 템플릿의 제약이 계층을 결정한다. 템플릿에 의해 허가된 데이터형은, 옵션 멤버로 불린다. 옵션 멤버는 필수는 아니지만, 이것이 없으면 오브젝트로부터 중요한 정보가 결핍 하는 일이 있다. 옵션 멤버는, 데이터 오브젝트의 자식으로 보존된다. 아이 오브젝트는, 다른 데이터 오브젝트, 이전의 데이터 오브젝트에의 참조, 또는 바이너리 오브젝트이다.

오브젝트를 DirectX 파일에 보존 하면나무는,AddBinaryObject ,AddDataObject , 또는AddDataReference 를 사용해, 각각 바이너리 오브젝트, 데이터 오브젝트, 또는 데이터 참조 오브젝트를 파일에 추가한다. 상세한 것에 대하여는, 「파일의 보존」을 참조할것.

기존의 DirectX 파일의 오브젝트를 열거 하면나무는, 다음과 같이,GetData ,GetNextObject , 및GetType 메소드를 사용한다.

  1. GetType 를 사용해, 오브젝트의 템플릿의 GUID를 취득한다. 예를 들어, 메쉬 오브젝트의 경우, 메쉬 템플릿의 GUID를 취득한다.
  2. GetData 를 사용해, 연속하는 메모리체크로부터, 필요한 오브젝트 멤버를 취득한다.
  3. 아이 오브젝트 마다, 다음의 스텝을 실행한다.
    1. GetNextObject 를 사용해, 아이 오브젝트를 취득한다.
    2. QueryInterface를 사용해,IDirectXFileData,IDirectXFileDataReference, 및IDirectXFileBinary인터페이스를 지원 할지 어떨지를 순서에 문의해, 아이 오브젝트의 타입 (데이터, 데이터 참조, 또는 바이너리)을 판별한다. 지원 되는 인터페이스가, 오브젝트의 타입을 나타내고 있다. 다음의 코드에서는, 오브젝트가IDirectXFileBinary를 지원 할지 어떨지를 판별하는 것으로써, 바이너리 오브젝트인가 어떤가를 판별하고 있다.
      IDirectXFileObject *DXFileObj;
IDirectXFileBinary *DXFileBinary;

if (FAILED(DXFileObj->QueryInterface(IID_IDirectXFileBinary,
                                     (LPVOID *) &DXFileBinary))
{
    // 오브젝트는 IDirectXFileBinary를 지원 하지 않기 때문에,
    // 바이너리 오브젝트는 아니다.
}
else
{
    // 오브젝트는 바이너리이다.
}
    3. 아이 오브젝트의 타입을 판별한 후, 그 타입에 맞은 인터페이스 (IDirectXFileData ,IDirectXFileDataReference , 또는IDirectXFileBinary )의 메소드를 사용해, 아이 오브젝트의 조작을 실시한다.

IDirectXFileData인터페이스에서는, 다음의 메소드가 준비되어 있다.

  • AddBinaryObject
  • AddDataObject
  • AddDataReference
  • GetData
  • GetNextObject
  • GetType

또,IDirectXFileData는IDirectXFileObject::GetId 메소드와IDirectXFileObject::GetName 메소드를 계승한다.

IDirectXFileData::AddBinaryObject

IDirectXFileData

아이 오브젝트로서 바이너리 오브젝트를 생성 해 추가한다.

구문

HRESULT AddBinaryObject(
  LPCSTR szName,
  const GUID * pguid,
  LPCSTR szMimeType,
  LPVOID pvData,
  DWORD cbSize);

파라미터

szName
오브젝트의 이름에의 포인터. 옵션으로, 오브젝트가 이름을 필요로 하지 않을 때는, NULL를 지정한다.
pguid
오브젝트를 나타내는 GUID에의 포인터. 옵션으로, 오브젝트가 GUID를 필요로 하지 않을 때는, NULL를 지정한다.
szMimeType
오브젝트의 mime 타입에의 포인터.
pvData
오브젝트의 데이터에의 포인터.
cbSize
pvData가 가리키는 버퍼의 사이즈. 단위는 바이트.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

주의

아이 오브젝트의 보존의 상세한 것에 대하여는, 이 인터페이스,IDirectXFileData 의 「처음에」를 참조할것.

IDirectXFileData::AddDataObject

IDirectXFileData

아이 오브젝트로서 데이터 오브젝트를 추가한다.

구문

HRESULT AddDataObject(LPDIRECTXFILEDATA pDataObj);

파라미터

pDataObj
아이 오브젝트로서 추가하는IDirectXFileData 오브젝트에의 포인터.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

주의

이 메소드를 호출하기 전에,IDirectXFileSaveObject::CreateDataObject 메소드를 사용해,IDirectXFileData 오브젝트를 생성 한다.

오브젝트의 보존의 상세한 것에 대하여는, 이 인터페이스,IDirectXFileData 의 「처음에」를 참조할것.

IDirectXFileData::AddDataReference

IDirectXFileData

아이 오브젝트로서 데이터 참조 오브젝트를 생성 해 추가한다.

구문

HRESULT AddDataReference(
  LPCSTR szRef,
  const GUID * pguidRef);

파라미터

szRef
참조되는 데이터 오브젝트의 이름에의 포인터. pguidRef로 GUID를 참조할 수 있는 경우는, NULL로 좋다.
pguidRef
데이터를 나타내는 GUID에의 포인터. szRef로 이름을 참조할 수 있는 경우는, NULL로 좋다.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

주의

파라미터szRef또는pguidRef가 적어도 어느 쪽인지 하나는, 비NULL가 아니면 안된다.

오브젝트의 보존의 상세한 것에 대하여는, 이 인터페이스,IDirectXFileData 의 「처음에」를 참조할것.

IDirectXFileData::GetData

IDirectXFileData

1개의 오브젝트 멤버의 데이터, 또는 모든 멤버의 데이터를 취득한다.

구문

HRESULT GetData(
  LPCSTR szMember,
  DWORD * pcbSize,
  void ** ppvData);

파라미터

szMember
데이터를 취득하는 멤버의 이름. 요구된 전멤버의 데이터를 취득 하면나무는, NULL를 지정한다.
pcbSize
ppvData의 버퍼 사이즈를 받는 포인터. 단위는 바이트.
ppvData
szMember에 관련하는 데이터를 받는 포인터의 주소. szMember가 NULL 때,*ppvData는, 연속하는 메모리 블록에 요구된 전멤버의 데이터가 들어가 있는 버퍼를 가리키도록(듯이) 설정된다.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADARRAYSIZE
DXFILEERR_BADDATAREFERENCE
DXFILEERR_BADVALUE

주의

이 메소드는, 요구된 데이터 오브젝트의 멤버의 데이터를 취득하지만, 옵션 (아이) 멤버의 데이터는 취득하지 않는다. 아이 오브젝트를 취득하려면 ,GetNextObject 를 사용한다.

오브젝트의 열거의 상세한 것에 대하여는, 이 인터페이스,IDirectXFileData 의 「처음에」를 참조할것.

IDirectXFileData::GetNextObject

IDirectXFileData

DirectX 파일의, 다음의 아이 데이터 오브젝트, 데이터 참조 오브젝트, 또는 바이너리 오브젝트를 취득한다.

구문

HRESULT GetNextObject(LPDIRECTXFILEOBJECT * ppChildObj);

파라미터

ppChildObj
아이 오브젝트의IDirectXFileObject 인터페이스에의 포인터를 받는 주소.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADVALUE
DXFILEERR_NOMOREOBJECTS

주의

취득하는 오브젝트의 타입을 판별하려면 ,QueryInterface를 사용해, 취득하는 오브젝트에IDirectXFileData ,IDirectXFileDataReference , 또는IDirectXFileBinary 인터페이스를 지원 할지 어떨지를 문의한다. 지원 되는 인터페이스가, 오브젝트 타입 (데이터, 데이터 참조, 또는 바이너리)을 나타내고 있다.

아이 오브젝트, 오브젝트의 열거, 및 오브젝트 타입의 판별에 관한 상세한 것에 대하여는, 이 인터페이스,IDirectXFileData 의 「처음에」를 참조할것.

IDirectXFileData::GetType

IDirectXFileData

오브젝트의 템플릿의 GUID를 취득한다.

구문

HRESULT GetType(const GUID ** ppguid);

파라미터

ppguid
오브젝트의 템플릿의 GUID를 받는 포인터의 주소.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADVALUE

IDirectXFileDataReference

IDirectXFileDataReference인터페이스는, 데이터 참조 오브젝트를 지원 한다. 데이터 참조 오브젝트는, 파일내에서 이미 정의되고 있는 데이터 오브젝트를 참조한다. 이것에 의해, 파일내에서 정의를 반복하지 않아도, 같은 오브젝트를 몇번이나 사용할 수가 있다.

오브젝트가 데이터 참조 오브젝트이라고 판별된 후, 이 인터페이스의Resolve 메소드를 사용해, 파일내에서 이미 정의되고 있는 실제의 오브젝트를 취득한다. 데이터 참조 오브젝트의 판별 방법의 상세한 것에 대하여는,IDirectXFileData 인터페이스를 참조할것.

또,IDirectXFileDataReference는,IDirectXFileObject::GetId 와IDirectXFileObject::GetName 메소드를 계승한다.

IDirectXFileDataReference::Resolve

IDirectXFileDataReference

데이터 참조를 해결한다.

구문

HRESULT Resolve(LPDIRECTXFILEDATA * ppDataObj);

파라미터

ppDataObj
IDirectXFileData 오브젝트를 받는 포인터의 주소.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADVALUE
DXFILEERR_NOTFOUND

IDirectXFileEnumObject

IDirectXFileEnumObject인터페이스에서는, 처리를 반복해, 파일의 전데이터 오브젝트를 취득하거나 GUID 또는 이름으로 데이터 오브젝트를 취득할 수가 있다.

IDirectXFileEnumObject인터페이스에서는, 다음의 메소드가 준비되어 있다.

  • GetDataObjectById
  • GetDataObjectByName
  • GetNextDataObject

IDirectXFileEnumObject::GetDataObjectById

IDirectXFileEnumObject

지정한 GUID를 가지는 데이터 오브젝트를 취득한다.

구문

HRESULT GetDataObjectById(
  REFGUID rguid,
  LPDIRECTXFILEDATA * ppDataObj);

파라미터

rguid
지정한 GUID에의 참조.
ppDataObj
취득한IDirectXFileData 오브젝트를 받는 포인터.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADVALUE
DXFILEERR_NOTFOUND

IDirectXFileEnumObject::GetDataObjectByName

IDirectXFileEnumObject

지정한 이름을 가지는 데이터 오브젝트를 취득한다.

구문

HRESULT GetDataObjectByName(
  LPCSTR szName,
  LPDIRECTXFILEDATA * ppDataObj);

파라미터

szName
지정된 이름에의 포인터.
ppDataObj
취득한IDirectXFileData 오브젝트를 받는 포인터.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADVALUE
DXFILEERR_NOTFOUND

IDirectXFileEnumObject::GetNextDataObject

IDirectXFileEnumObject

DirectX 파일의 톱 레벨의 다음의 오브젝트를 취득한다. 톱 레벨의 오브젝트는 항상 데이터 오브젝트이다. 데이터 참조 오브젝트와 바이너리 오브젝트는, 데이터 오브젝트의 아이 밖에 될 수 없다.

구문

HRESULT GetNextDataObject(
  LPDIRECTXFILEDATA * ppDataObj);

파라미터

ppDataObj
취득한IDirectXFileData 오브젝트를 받는 포인터.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADVALUE
DXFILEERR_NOMOREOBJECTS

IDirectXFileObject

IDirectXFileObject인터페이스는, DirectX 파일 오브젝트의 기본 인터페이스이다. IDirectXFileData ,IDirectXFileDataReference , 및IDirectXFileBinary 인터페이스는, 모두 이 인터페이스로부터 계승된다.

IDirectXFileObject인터페이스에서는, 다음의 메소드가 준비되어 있다.

  • GetId
  • GetName

IDirectXFileObject::GetId

IDirectXFileObject

DirectX 파일 오브젝트를 식별하는 GUID에의 포인터를 취득한다.

구문

HRESULT GetId (LPGUID pGuid)

파라미터

pGuid
오브젝트의 ID를 받는 GUID에의 포인터. 오브젝트가 ID를 가지고 있지 않은 경우, 이 함수는 GUID에 NULL GUID를 설정한다.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADVALUE

IDirectXFileObject::GetName

IDirectXFileObject

DirectX 파일 오브젝트의 이름에의 포인터를 취득한다.

구문

HRESULT GetName (LPSTR pstrNameBuf, LPDWORD pdwBufLen)

파라미터

pstrNameBuf
DirectX 파일 오브젝트의 이름을 카피하는 버퍼에의 포인터. 버퍼장의 보고가 필요한 경우는, NULL로 설정한다.
pdwBufLen
pstrNameBuf가 가리키는 버퍼의 길이를 지정하는 DWORD에의 포인터. pstrNameBuf가 NULL여도,pdwBufLen는 오브젝트명을 보관 유지하기 위해서 필요한 버퍼장으로 변경된다. 어느 쪽의 경우에서도,pdwBufLen의 원의 값이 오브젝트명을 보관 유지하기 위해서 필요한 길이 기에 부족할 때에는, 함수는 DXFILEERR_BADVALUE를 돌려준다.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADALLOC

IDirectXFileSaveObject

IDirectXFileSaveObject인터페이스에 의해, 데이터 오브젝트를 생성 해, 템플릿과 데이터 오브젝트를 보존할 수가 있다. IDirectXFile::CreateSaveObject 를 사용해, 이 오브젝트의 인스턴스를 생성 한다. 다음에,SaveTemplates 를 사용해, 템플릿을 보존한다. 데이터 오브젝트의 생성에는,CreateDataObject 를 사용해, 데이터의 보존에는SaveData 를 사용한다.

반드시 모든 파일에 템플릿이 필요한 것은 아니다. 예를 들어, 모든 DirectX 파일에 각각 템플릿을 복제하는 것이 아니라, 1개의 DirectX 파일에 템플릿 모든 것을 둘 수도 있다.

IDirectXFileSaveObject인터페이스에서는, 다음의 메소드가 준비되어 있다.

  • CreateDataObject
  • SaveData
  • SaveTemplates

IDirectXFileSaveObject::CreateDataObject

IDirectXFileSaveObject

데이터 오브젝트를 생성 한다.

구문

HRESULT CreateDataObject(
  REFGUID rguidTemplate,
  LPCSTR szName,
  const GUID * pguid,
  DWORD cbSize,
  LPVOID pvData,
  LPDIRECTXFILEDATA * ppDataObj);

파라미터

rguidTemplate
데이터 오브젝트의 템플릿을 나타내는 GUID.
szName
데이터 오브젝트의 이름에의 포인터. 옵션으로, 오브젝트가 이름을 가지고 있지 않은 경우는, NULL를 지정한다. 이 오브젝트를 데이터 참조 오브젝트에 의해 참조하려면 ,szName또는pguid파라미터의, 적어도 어느 쪽인지 1개는 비NULL가 아니면 안된다.
pguid
데이터 오브젝트를 나타내는 GUID에의 포인터. 옵션으로, 오브젝트가 GUID를 가지고 있지 않은 경우는, NULL를 지정한다. 이 오브젝트를 데이터 참조 오브젝트에 의해 참조하려면 ,szName또는pguid파라미터의, 적어도 어느 쪽인지 1개는 비NULL가 아니면 안된다.
cbSize
데이터 오브젝트의 사이즈. 단위는 바이트.
pvData
요구된 멤버의 데이터 모든 것을 저장 하는 버퍼에의 포인터.
ppDataObj
생성 된IDirectXFileData 오브젝트를 받는 포인터의 주소.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

주의

SaveTemplates 메소드를 사용해 템플릿을 보존하고 나서, 이 메소드로 생성 한 데이터를 보존한다. 생성 한 데이터는,SaveData 메소드를 사용해 보존한다. 옵션 데이터를 보존할 필요가 있을 때는, 이 메소드의 뒤,SaveData의 전에,IDirectXFileData::AddDataObject 메소드를 사용한다. 오브젝트에 아이 오브젝트가 있을 때는,SaveData를 호출하기 전에 아이 오브젝트를 추가한다.

IDirectXFileSaveObject::SaveData

IDirectXFileSaveObject

데이터 오브젝트와 그 아이 오브젝트를, DirectX 파일에 보존한다.

구문

HRESULT SaveData(
  LPDIRECTXFILEDATA pDataObj);

파라미터

pDataObj
보존하는IDirectXFileData 오브젝트에의 포인터.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADARRAYSIZE
DXFILEERR_BADVALUE

IDirectXFileSaveObject::SaveTemplates

IDirectXFileSaveObject

템플릿을 DirectX 파일에 보존한다.

구문

HRESULT SaveTemplates(
  DWORD cTemplates,
  const GUID ** ppguidTemplates);

파라미터

cTemplates
보존하는 템플릿의 총수.
ppguidTemplates
보존하는 모든 템플릿에 대한 GUID의 배열에의 포인터의 주소.

반환값

다음의 값중 1개를 돌려준다.
DXFILE_OK
DXFILEERR_BADVALUE

주의

다음의 코드는,SaveTemplates의 호출예와ppuuid가 가리키는 배열의 내용의 예이다.

IDirectXFileSaveObject * pDXFileSaveObject;

const GUID *aIds[] = {
    &DXFILEOBJ_SimpleData,
    &DXFILEOBJ_ArrayData,
    &DXFILEOBJ_RestrictedData};

hr = pDXFileSaveObject->SaveTemplates(3, aIds);

이 메소드로 템플릿을 보존한 후,IDirectXFileSaveObject::CreateDataObject 메소드를 사용해 데이터 오브젝트를 생성 한다.

데이터형

DirectX 파일의 인터페이스에서는, 다음의 정수와 구조체를 사용한다.

  • DXFILEFORMAT 정수
  • DXFILELOADMEMORY 구조체
  • DXFILELOADOPTIONS 정수
  • DXFILELOADRESOURCE 구조체

DXFILEFORMAT 정수

IDirectXFile::CreateSaveObject 메소드로 사용되는 값을 지정해, DirectX 파일을 보존할 경우에 사용하는 포맷을 나타낸다.

구문

typedef DWORD DXFILEFORMAT;
#define DXFILEFORMAT_BINARY     0
#define DXFILEFORMAT_TEXT       1
#define DXFILEFORMAT_COMPRESSED 2

값

DXFILEFORMAT_BINARY
바이노리필드를 나타낸다.
DXFILEFORMAT_TEXT
텍스트 파일을 나타낸다.
DXFILEFORMAT_COMPRESSED
압축파일을 나타낸다.
파일 포맷의 디폴트값은, DXFILEFORMAT_BINARY이다. 파일 포맷의 값을 논리 OR로 결합해, 압축 텍스트 파일이나 압축 바이노리필드를 생성 할 수도 있다. 파일이 바이너리 (0)와 텍스트 (1)의 양쪽 모두로서 지정되고 있는 경우, 그 값은 텍스트 파일 포맷의 값 (0 + 1 = 1)과 구별이 되지 않기 때문에, 텍스트 파일로서 보존된다. 파일 포맷으로서 텍스트와 압축을 지정 하면, 파일은 우선 텍스트로서 기입해지고 나서 압축된다. 다만, 압축 텍스트 파일은 바이너리 텍스트 파일(정도)만큼 효율이 좋지 않기 때문에, 많은 경우, 바이너리로 압축을 지정한다. 포맷을 지정하지 않고 파일을 압축하도록(듯이) 설정 하면, 바이너리로 압축된 파일이 된다.

DXFILELOADMEMORY 구조체

어플리케이션이IDirectXFile::CreateEnumObject 메소드를 사용해DXFILELOAD_FROMMEMORY 를 지정 하면 와, 로드하는 리소스를 식별한다.

구문

typedef struct _DXFILELOADMEMORY {
    LPVOID lpMemory;
    DWORD dSize;
}DXFILELOADMEMORY, *LPDXFILELOADMEMORY;

멤버

lpMemory
로드하는 메모리 블록에의 포인터.
dSize
로드하는 메모리 블록의 사이즈. 단위는 바이트.

DXFILELOADOPTIONS 정수

IDirectXFile::CreateEnumObject 메소드로 사용하는 값을 지정해, 파일 데이터의 소스를 나타낸다.

구문

typedef DWORD DXFILELOADOPTIONS;
#define DXFILELOAD_FROMFILE  0x00L
#define DXFILELOAD_FROMRESOURCE 0x01L
#define DXFILELOAD_FROMMEMORY 0x02L
#define DXFILELOAD_FROMSTREAM 0x04L
#define DXFILELOAD_FROMURL 0x08L

값

DXFILELOAD_FROMFILE
파일로부터 읽어내진 데이터를 나타낸다.
DXFILELOAD_FROMRESOURCE
리소스로부터 읽어내진 데이터를 나타낸다.
DXFILELOAD_FROMMEMORY
메모리로부터 읽어내진 데이터를 나타낸다.
DXFILELOAD_FROMSTREAM
스트림으로부터 읽어내진 데이터를 나타낸다. 현재는 지원되어 있지 않다.
DXFILELOAD_FROMURL
URL (Uniform Resource Locator)로부터 읽어내진 데이터를 나타낸다.

DXFILELOADRESOURCE 구조체

어플리케이션이IDirectXFile::CreateEnumObject 메소드를 사용해DXFILELOAD_FROMRESOURCE 를 지정 하면 와, 로드하는 리소스를 식별한다.

구문

typedef struct _DXFILELOADRESOURCE {
    HMODULE hModule;
    LPCTSTR lpName;
    LPCTSTR lpType;
}DXFILELOADRESOURCE, *LPDXFILELOADRESOURCE;

멤버

hModule
로드하는 리소스를 포함한 모듈의 핸들. 이 멤버가 NULL 때는, 사용하는 실행 파일에 리소스를 Attach 해야 한다.
lpName
로드하는 리소스의 이름. 예를 들어, 리소스가 메쉬 때는, 이 멤버는 메쉬 파일의 이름을 지정한다.
lpType
리소스를 식별하는 유저 정의의 타입.

반환값

DirectX 파일의 COM (Component Object Model) 인터페이스의 메소드는, 표준의 COM 반환값 외에 다음의 값을 돌려주는 일이 있다.

DXFILE_OK
커멘드는 정상적으로 완료했다. DD_OK 와 같다.
DXFILEERR_BADVALUE
파라미터가 무효이다.
DXFILEERR_BADTYPE
오브젝트 타입이 무효이다.
DXFILEERR_BADALLOC
메모리 할당해에 실패했다.
DXFILEERR_NOTFOUND
오브젝트가 발견되지 않는다.
DXFILEERR_FILENOTFOUND
파일이 발견되지 않는다.
DXFILEERR_RESOURCENOTFOUND
리소스가 발견되지 않는다.
DXFILEERR_URLNOTFOUND
URL가 발견되지 않는다.
DXFILEERR_BADRESOURCE
리소스가 무효이다.
DXFILEERR_BADFILETYPE
파일이 DirectX 파일은 아니다.
DXFILEERR_BADFILEVERSION
파일의 버젼이 무효이다.
DXFILEERR_BADFILEFLOATSIZE
부동 소수점의 사이즈가 무효이다.
DXFILEERR_BADFILE
파일이 무효이다.
DXFILEERR_PARSEERROR
파일이 구문 분석 할 수 없다.
DXFILEERR_BADARRAYSIZE
배열의 사이즈가 무효이다.
DXFILEERR_BADDATAREFERENCE
데이터 참조가 무효이다.
DXFILEERR_NOMOREOBJECTS
오브젝트는 이미, 모두 열거되고 있다.
DXFILEERR_NOMOREDATA
이 이후의 데이터는 취득할 수 없다.


동작환경

API 요소의 구문을 소개하는 각 주제에는, 이러한 요소를 사용할 때에 필요한, 빌드 및 실행시의 동작환경에 대한 정보가 포함되어 있다. 동작환경의 서식은, 다음과 같다.

Windows NT/2000 : Windows NT 3.1 이후가 필요.
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 버젼으로 지원되어 있지 않은 경우, 이 행은 생략 된다.


컬러 키 포맷

[C++]

컬러 키는 DDCOLORKEY 구조체에 기술된다. 컬러 키가 단색의 경우, 이 구조체의 양멤버는 같은 값에 할당할 수 있다. 또는, 컬러 키가 색역이 된다.

컬러 키는, 표면의 픽셀 포맷을 이용해 지정된다. 표면이 팔레트화 된 포맷인 경우, 컬러 키는 인덱스 또는 인덱스역으로서 지정된다. 표면이 비팔레트화 디스플레이 모드에 있는 경우, 컬러 키는 미처리의 픽셀 포맷으로 지정된다. 예를 들어, 진자의 컬러 키를 16 비트의 5:6:5 모드로 설정하려면 , 0xf81F (빨강과 파랑의 5 비트를 모두 설정)의 값을 사용한다.

유효한 컬러 키의 예를 몇개인가 이하에 나타낸다.

8 비트 팔레트화 모드

// 팔레트 엔트리 26 은 컬러 키.
dwColorSpaceLowValue = 26;
dwColorSpaceHighValue = 26;

16 비트 팔레트화 모드

// 색은 진자.
dwColorSpaceLowValue = 0xf81F;
dwColorSpaceHighValue = 0xf81F;

단색은 아니고 색역에 대한 지원은 하드웨어에 의한다. 하드웨어에 대한 DDCAPS 구조체의 dwCKeyCaps 멤버를 체크하는 것. HEL 는 색역을 지원 하지 않는다.

[Visual Basic]

컬러 키는 DDCOLORKEY 형에 기술된다. 컬러 키가 단색의 경우, 이 형태의 양멤버는 같은 값에 할당할 수 있다. 또는, 컬러 키가 색역이 된다.

컬러 키는, 표면의 픽셀 포맷을 이용해 지정된다. 표면이 팔레트화 된 포맷인 경우, 컬러 키는 인덱스 또는 인덱스역으로서 지정된다. 표면이 비팔레트화 디스플레이 모드에 있는 경우, 컬러 키는 미처리의 픽셀 포맷으로 지정된다. 예를 들어, 빨강의 컬러 키를 24 비트 트루 컬러 모드로 설정하려면 , &HFF (빨강의 5 비트를 모두 설정)의 값을 사용한다.

유효한 컬러 키의 예를 몇개인가 이하에 나타낸다.

8 비트 팔레트화 모드

'팔레트 엔트리 26 은 컬러 키.
low = 26
high = 26

24 비트 트루 컬러 모드

// 16 진의 빨강의 값이 컬러 키가 된다.
low = &HFF
high = &HFF

단색은 아니고 색역에 대한 지원은 하드웨어에 의한다. 하드웨어에 대한 DDCAPS 형의 lCKeyCaps 멤버를 체크하는 것. HEL 는 색역을 지원 하지 않는다.


감마 램프 레벨의 설정과 취득

[C++]

감마 램프 레벨은 효과적인 참조 테이블이며, DirectDraw 가 표시되는 새로운 레벨에 frame buffer색성분을 맵 하기 위해서 사용한다. 상세한 것에 대하여는, 「감마 램프 레벨에 대하며」를 참조할것. IDirectDrawGammaControl::SetGammaRamp 및 IDirectDrawGammaControl::GetGammaRamp 메소드를 호출하는 것으로, 프라이머리 표면에 대한 램프 레벨을 설정해, 취득할 수 있다. 양메소드에서는 2 개의 파라미터를 받지만, 최초의 파라미터는 후의 사용을 위해서(때문에) 확보해, 제로로 설정하지 않으면 안 된다. 2 번째의 파라미터 lpRampData 는,DDGAMMARAMP 구조체의 주소로 한다. DDGAMMARAMP 구조체에는,WORD 의 256 요소 배열을 3 개 (1 개의 배열 마다 적, 초록, 파랑의 감마 램프) 포함한다.

IDirectDrawGammaControl::SetGammaRamp 를 호출하면나무에 DDSGR_CALIBRATE 값을 포함하면(자), 새로운 감마 레벨을 설정할 경우에 구경 측정기를 기동할 수 있다. 감마 램프를 calibration 하면 얼마인가 오버헤드가 있으므로, 빈번하게는 사용할 수 없다. 조정된 감마 램프의 설정은, 뷰워나 디스플레이 어댑터 및 모니터에 관계없이, 일관성이 있는 완전한 감마값을 제공한다.

모든 시스템으로 감마 calibration를 지원 하는 것은 아니다. 감마 calibration를 지원 하는 경우를 결정하려면 ,IDirectDraw7::GetCaps 을 호출해, 메소드가 돌아온 후에 관련지을 수 있었던 DDCAPS 구조체의 dwCaps2 멤버를 조사한다. DDCAPS2_CANCALIBRATEGAMMA 능력 플래그가 나타나고 있으면, 감마 calibration가 지원 된다.

새로운 램프 레벨을 설정하는 경우, 그 배열로 설정한 레벨은 어플리케이션이 풀 스크린 (배타 모드)의 경우에만 사용된다. 어플리케이션이 노멀 모드로 변경되면(자), 항상 램프 레벨은 일시적으로 설정되어 어플리케이션이 풀 스크린 모드에 복귀될 때 다시 취득된다. 게다가 프라이머리 표면 이외의 표면에 대해서는, 램프 레벨을 설정할 수 없는 것을 생각해 내는 것.

주 ： Win32® API 에 매우 정통하고 있는 (분)편은, Win32 가 GetDeviceGammaRamp 와 SetDeviceGammaRamp 함수를 같은 표면에 대해서 제공하는 경우에, DirectDraw 가 IDirectDrawGammaControl 와 같은 인터페이스를 공개 슬슬 일을 이상하게 생각할지도 모른다. Win32 API 에도 이러한 함수는 있지만,IDirectDrawGammaControl 인터페이스의 메소드와 같이, 모든 Windows 플랫폼에서 반드시 성공한다고는 할 수는 없다.

[Visual Basic]

감마 램프 레벨은 효과적인 참조 테이블이며, DirectDraw 가 표시되는 새로운 레벨에 frame buffer색성분을 맵 하기 위해서 사용한다. 상세한 것에 대하여는, 「감마 램프 레벨에 대하며」를 참조할것. DirectDrawGammaControl.SetGammaRamp 및 DirectDrawGammaControl.GetGammaRamp 메소드를 호출하는 것으로, 프라이머리 표면에 대한 램프 레벨을 설정해, 취득할 수 있다. 양메소드에서는 2 개의 파라미터를 받지만, 최초의 파라미터를 사용해 calibration를 지정한다. 2 번째의 파라미터 gammaRamp 는,DDGAMMARAMP 형이다. DDGAMMARAMP 형에는,Integer 의 256 요소 배열을 3 개 (1 개의 배열 마다 적, 초록, 파랑의 감마 램프) 포함한다.

DirectDrawGammaControl.SetGammaRamp 를 호출하면나무에 DDSGR_CALIBRATE 값을 포함하면(자), 새로운 감마 레벨을 설정할 경우에 구경 측정기를 기동할 수 있다. 감마 램프를 calibration 하면 얼마인가 오버헤드가 있으므로, 빈번하게는 사용할 수 없다. 조정된 감마 램프의 설정은, 뷰워나 디스플레이 어댑터 및 모니터에 관계없이, 일관성이 있는 완전한 감마값을 제공한다.

모든 시스템으로 감마 calibration를 지원 하는 것은 아니다. 감마 calibration를 지원 하는 경우를 결정하려면 ,DirectDraw7.GetCaps 를 호출해, 메소드가 돌아온 후에 관련지을 수 있었던 DDCAPS 형의 lCaps2 멤버를 조사한다. DDCAPS2_CANCALIBRATEGAMMA 능력 플래그가 나타나고 있으면, 감마 calibration가 지원 된다.

새로운 램프 레벨을 설정하는 경우, 그 배열로 설정한 레벨은 어플리케이션이 풀 스크린 (배타 모드)의 경우에만 사용된다. 어플리케이션이 노멀 모드로 변경되면(자), 항상 램프 레벨은 측에 설정되어 어플리케이션이 풀 스크린 모드에 복귀될 때 다시 취득된다. 게다가 프라이머리 표면 이외의 표면에 대해서는, 램프 레벨을 설정할 수 없는 것을 생각해 내는 것.

주 ： Win32® API 에 매우 정통하고 있는 (분)편은, Win32 가 GetDeviceGammaRamp 와 SetDeviceGammaRamp 함수를 같은 표면에 대해서 제공하는 경우에, DirectDraw 가 DirectDrawGammaControl 와 같은 인터페이스를 공개 슬슬 일을 이상하게 생각할지도 모른다. Win32 API 에도 이러한 함수는 있지만,DirectDrawGammaControl 인터페이스의 메소드와 같이, 모든 Windows 플랫폼에서 반드시 성공한다고는 할 수는 없다.


수동 디스플레이 디바이스

헤드 마운트 디스플레이나 자동 스테레오 그래픽스 디스플레이등의 수동 스테레오 디스플레이는, 능동 디바이스보다 제어가 간단하다. 수동 디스플레이에는, 각각의 눈이 다른 뷰를 받도록(듯이) 구성된 개별의 표시 (또는 단일의 표시 영역)가 있다. DirectDraw 는, 단일의 표시 표면에 왼쪽과 오른쪽의 표면을 생성 한다. 표시 표면의 스캔 데이터가 디바이스에 보내져 디바이스는 그 데이터를 적절한 장소에 배치한다. 예를 들어, 헤드 마운트 디스플레이에서는, 단일의 640 × 480 표시 표면을, 좌우 각각 320 × 480 의 표면으로 구성된 병렬 유니트로서 취급할 필요가 있다. 이 경우, 디스플레이 디바이스는 적절한 이미지를 각 눈의 전에 배치한다.

수동 디바이스에서는 동기의 문제가 없기 때문에, 표면 플립은, 플립 된 표면에 논리적으로 2 개 (왼쪽과 오른쪽)의 표면이 존재하는 것을 제외하면, 기본적으로 비스테레오 표면 플립과 같다.

일반적으로, 수동 디스플레이 디바이스에서는, 디스플레이의 픽셀의 것 1/2 을 왼쪽의 눈에, 나머지의 것 1/2 을 오른쪽의 눈에 표시한다. 이러한 디바이스로서는, 헤드 마운트 디스플레이나, 픽셀열을 왼쪽과 오른쪽의 눈에 교대로 필터링 하는 화면의 회색 팅 오버레이 기능을 가지는 모니터등이 있다. 각 눈은, 모니터의 refresh rate로 이미지를 표시한다.


알파 채널에 의한 텍스쳐

보다 복잡한 투과성을 나타내는 텍스쳐 맵의 encode에는, 2 방법의 방법이 있다. 어느 쪽의 경우도, 투과성을 기술하는 블록은 이미 기술되고 있는 64 비트 블록보다 먼저 일어난다. 투과성은 픽셀 마다 4 비트의 4 × 4 비트 맵 (명시적인 encode), 또는 그것 이하의 비트의 비트 맵의 어느 쪽인지여, 선형 보간은 색encode로 사용되는 것으로 유사한다.

투과성 블록과 색블록의 배치

단어 주소 | 64 비트 블록
3:0 | 투과성 블록
7:4 | 이미 기술된 64 비트 블록

명시적인 텍스쳐 encode

명시적인 텍스쳐 encode (DXT2 와 DXT3 포맷)를 위해서(때문에), 투과성을 기술하는 텍셀의 알파 컴퍼넌트는, 텍셀 마다 4 비트의 4 × 4 비트 맵으로 encode 된다. 이러한 4 비트는, 알파 데이터로 제일 중요한 4 개의 비트의 디저링이나 단순한 사용등이 다양한 방법으로 달성할 수 있다. 다만, 생성 되면(자), 모든 보간의 폼이 없으면 그 만큼으로 밖에 사용할 수 없다.

주 ： DirectDraw 의 압축 메소드는, 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]

3 비트 선형 알파 보간

DXT4 및 DXT5 포맷에 대한 투과성의 부호는, 색에 사용되는 선형 부호 와 유사한 개념이 기가 된다. 2 개의 8 비트 알파값과 픽셀 마다 3 비트의 4 × 4 비트 맵은, 블록의 최초의 8 바이트에 저장 된다. 전형적인 알파값은, 중간 알파값을 보간 하기 위해서 사용된다. 추가 정보는, 2 개의 알파값을 저장 하는 방법으로 이용할 수 있다. 알파 _0 가 알파 _1 보다 큰 경우, 6 개의 중간 알파값이 보간에 의해 생성 된다. 또, 4 개의 중간 알파값이 지정되는 알파 극값간에 보간 된다. 2 개의 추가의 명시적인 알파값은, 0 (완전하게 투과형)으로 255 (완전하게 불투명)가 된다.

[C++]

다음의 유사 코드로 이 알고리즘을 나타낸다.

// 8 알파 또는 6 알파 블록?
if (alpha_0 > alpha_1) {
     // 8 알파 블록 : 다른 6 개의 알파를 파생한다.
    // 000 = 알파 0, 001 = 알파 1, 그 외는 보간 된다.
    alpha_2 = (6 * alpha_0 + alpha_1) / 7;      // 비트 코드 010
    alpha_3 = (5 * alpha_0 + 2 * alpha_1) / 7;  // 비트 코드 011
    alpha_4 = (4 * alpha_0 + 3 * alpha_1) / 7;  // 비트 코드 100
    alpha_5 = (3 * alpha_0 + 4 * alpha_1) / 7;  // 비트 코드 101
    alpha_6 = (2 * alpha_0 + 5 * alpha_1) / 7;  // 비트 코드 110
    alpha_7 = (alpha_0 + 6 * alpha_1) / 7;      // 비트 코드 111
  }
else {  // 6 알파 블록 : 다른 알파를 파생한다.
    // 000 = 알파 0, 001 = 알파 1, 그 외는 보간 된다.
    alpha_2 = (4 * alpha_0 + alpha_1) / 5;      // 비트 코드 010
    alpha_3 = (3 * alpha_0 + 2 * alpha_1) / 5;  // 비트 코드 011
    alpha_4 = (2 * alpha_0 + 3 * alpha_1) / 5;  // 비트 코드 100
    alpha_5 = (alpha_0 + 4 * alpha_1) / 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)

[C++, Visual Basic]


불투명과 1 비트 알파 텍스쳐

텍스쳐 포맷 DXT1 는, 불투명 또는 단일의 투과형색이 있는 텍스쳐용이다.

각 불투명 또는 1 비트 알파 블록을 위해서(때문에), 2 개의 16 비트값 (RGB 5:6:5 포맷)과 픽셀 마다 2 비트의 4 × 4 비트 맵이 저장 된다. 이것은, 16 텍셀 또는 4 비트/텍셀에 대해서 합계 64 비트가 된다. 블록 비트 맵에는, 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 에 유사하고 있다.

[C++]

다음에 나타내는 유사 코드의 일부로, 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) / 3;
     color_3 = (color 0 + 2 * color_1) / 3;
}
else
{
// 3 색블록 :다른 색을 파생한다.
// 00 = 색 0, 01 = 색 1, 10 = 색 2,
// 11 = 투과형.
// 64 비트 블록에 확보된다
// 2 비트 필드에 대응하는 2 비트 코드.
color_2 = (color_0 + color_1) / 2;
color_3 = transparent;
}

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 번째의 색은 보간 한 색이 된다.

색과 투과성에 대한 비트 맵 부호는, 다음의 계산식을 사용해 결정된다.

00 ?  color_0
01 ?  color_1
10 ?  1/2 color_0 + 1/2 color_1
11   ?    Transparent

[C++, Visual Basic]


능동 디스플레이 디바이스

LCD 셔터 렌즈등의 능동 디바이스에서는, 좌안의 뷰와 우안의 뷰로 단일의 디스플레이 디바이스를 때 다중화한다. DirectDraw 는, 능동 디바이스에 동기화하는 2 개의 표면을 생성 한다. 능동 디바이스는, 각 눈의 뷰를 언제 디스플레이에 표시하는지를 제어해, 시스템이 모니터의 좌안의 뷰와 우안의 뷰를 교대로 블록 한다. 각 눈은, 모니터의 것 1/2 의 refresh rate의 이미지로 나타내진다. 따라서, 어플리케이션은 스테레오 뷰 기능을 고refresh rate로 사용할 필요가 있다. 셔터 렌즈를 사용하려면 , 모니터가 충분한 refresh rate를 지원 하고 있지 않으면 안 된다. 이상적이게는, 각 눈으로 60 Hz (또는 그 이상)의 refresh rate가 필요하다. refresh rate에 대해서는, 「refresh rate의 열거」를 참조할것.

셔터 렌즈등의 시퀀셜 디스플레이에서는, 드라이버는 디스플레이와 능동 디바이스의 동기를 유지해야 한다. 보통, 드라이버가 능동 디바이스 상태를 모니터 한다. 예를 들어, VESA (Video Electronics Standards Association)의 표준 스테레오 연결기는, 능동 LCD 디바이스의 셔터를 제어할 수 있다. 또, 드라이버는, 특정의 시간에 어느 쪽의 눈이 액티브하게 되어 있을까를 모니터 할 수 있다. 이 정보에 근거해, 표면 플립은 왼쪽과 오른쪽의 이미지가 항상 페어로 디스플레이에 표시되도록(듯이) 한다.

DirectDraw 는, 다이렉트 스테레오 연결기 첨부 그래픽 카드가 있는 능동 디바이스만을 공개한다. 애드 인(Add In) 고글은 지원 되지 않는다.


투과형 블리트란?

투과형 블리트에 의해, 스프라이트를 애니메이션 할 때에 비직사각형의 블리트에 의한 동영상을 생성 할 수 있다. 보통, 스프라이트 이미지는 비직사각형이지만, 블리트는 항상 직사각형이기 (위해)때문에, 스프라이트의 경계 직사각형내의 각 픽셀이 데이터 전송의 일부가 된다. 투과형 블리트에 의해, 스프라이트 이미지 부분 이외의 각 픽셀은, 블리트가 그 목적지에 이미지를 이동할 때에 투과형으로서 다루어져 전송 된다. 이 때문에, 이러한 픽셀은, 백그라운드 이미지 위에의 픽셀의 색을 over-write 하지 않는다.

스프라이트를 생성 하는 경우, 투과성컬러 키로서 사용하는 임의의 색이나 색역을 선택한다. 이것은, 결코 투과성 컬러 키 이외에 사용하지 않는 단일의 색으로, 요구되는 이미지 부분 이외의 스프라이트 직사각형 부분 전체를 채우기 위해서(때문에) 사용된다. 스프라이트를 포함한 표면의 컬러 키를 설정하는 것은 실행시이다 (필요하면, 이 컬러 키는 이미지의 좌상구석의 픽셀색에 자동적으로 설정할 수 있다). 계속되어 일어나는 블리트는, 색에 적합하는 픽셀을 무시하도록(듯이) 컬러 키를 이용할 수 있다. 이런 종류의 컬러 키는전송원컬러 키라고 한다.

또, 하드웨어가 목적지 컬러 키잉을 지원 하는 목적지 표면의 컬러 키도 사용할 수 있다. 이목적지 컬러 키는, 스프라이트를 over-write 할 수 있는 픽셀에 대해서 사용된다. 예를 들어, 전경 이미지로 태스크를 하고 있다고 한다. 이 이미지는, 창첨부의 방의 벽과 같이 뒤로 건네주기 위한 스프라이트를 지원 한다. 작업자는 임의의 색 (이미지 이외의 장소에서 사용되지 않는 색)을 선택해, 창 밖에 하늘을 나타낸다. 목적지 표면에 대해서 이 컬러 키를 설정해, 그 표면에 스프라이트를 블리트 하는 경우, 스프라이트의 픽셀은 목적지 컬러 키를 사용하는 픽셀만을 over-write 한다. 이 예에서는, 스프라이트는 벽이나 창틀은 아니고 창 속인 만큼 표시된다. 이 결과, 스프라이트는 방의 외측에 있는 것처럼 보인다.

전송원 및 목적지 컬러 키를 조합할 수가 있다. 이 예에서는, 스프라이트가 전송원컬러 키를 사용할 수도 있지만, 그 경우 스프라이트의 경계 직사각형 전체로부터 하늘의 백그라운드를 자를 수가 없다.


감마 램프 레벨에 대해

DirectDraw 의감마 램프란, 일련의 값을 기술하기 위해서 사용하는 항이다. 이 일련의 값은, frame buffer의 모든 픽셀에 대해서, 모니터 위에의 디스플레이에 대한 디지털-아날로그 컨버터 (DAC)에 의해 수취되는 새로운 레벨에, 특정의 색성분 (적, 초록, 및 파랑)의 레벨을 맵 하는 값이다. 재맵핑은, 3 개(살)의 단순한 참조 테이블 (각각의 색성분에 대해서 1 개)에 의해 실행된다.

여기에서는 그방법에 대해 설명한다. DirectDraw 는 frame buffer로부터 픽셀을 취득해, 그 고유의 적, 초록, 및 파랑의 색성분의 항으로 픽셀을 취득한다. 각각의 컴퍼넌트는 0 에서 65535 까지의 값으로 나타내진다. DirectDraw 는 원의 값을 취득해, 그 값을 사용해 256 요소 배열 (램프)에 인덱스를 붙인다. 이 배열에는, 각각의 요소를 원의 요소와 옮겨놓는 값을 포함한다. DirectDraw 에서는, frame buffer내의 각 픽셀의 각 색성분에 대해서 " 참조와 치환 " 의 프로세스를 실행해, 스크린 위에의 모든 픽셀에 대한 최종적인 색을 변경한다.

램프값의 그래프를 생성 하면, 시각화 되어 용이하게 이해할 수 있다. 다음에, 2 개의 그래프를 나타낸다. 좌측의 그래프는 색이 전혀 변경되지 않는 램프를 나타내, 우측의 그래프는 부의 바이어스를 적용하는 색성분에 두는 램프를 나타낸다.

좌측의 그래프의 배열 요소에는, 그러한 인덱스와 동일한 값 (인덱스 0 에는 요소 0, 및 인덱스 65535 에는 255)이 포함된다. 이러한 값이 표시되기 전의 입력값은 변경할 수 없기 때문에, 램프의 이 타입이 디폴트가 된다. 우측의 그래프가 보다 흥미롭다. 이 램프에는, 최초의 요소의 0 으로부터 마지막 요소의 32768 까지의 값이, 중간의 비교적 한결같은 범위의 값으로 포함된다. 이 이펙트는, 이 램프를 사용하는 색성분이 디스플레이상에서 소리를 지워 표시된다. 선형 그래프의 이용인 만큼 할 수는 없다. 즉, 어플리케이션으로 임의의 맵핑을 할당하지 않으면 안 되는 경우에도와 같이 실시할 수 있다. 게다가 입력을 모두 제로로 설정 하면, 디스플레이로부터 특정의 색성분을 설정할 수 있다.


감마 램프 지원의 검출

[C++]

IDirectDraw7::GetCaps 메소드를 호출하는 것으로, 하드웨어가 다이나믹 감마 램프 조절을 지원 할지 어떨지를 결정할 수 있다. 이 호출의 뒤, DDCAPS2_PRIMARYGAMMA 플래그가 관련하는 DDCAPS 구조체의 dwCaps2 멤버로 나타나는 경우, 그 하드웨어는 다이나믹 감마 램프를 지원 한다. 하드웨어가 다이나믹 감마를 지원 하지 않는 경우는 그것을 사용할 수 없기 때문에, DirectDraw 는 이 기능을 에뮬레이트 하려고 한다.

[Visual Basic]

DirectDraw7.GetCaps 메소드를 호출하는 것으로, 하드웨어가 다이나믹 감마 램프 조정을 지원 할지 어떨지를 결정할 수 있다. 이 호출의 뒤, DDCAPS2_PRIMARYGAMMA 플래그가 관련하는 DDCAPS 형의 lCaps2 멤버로 나타나는 경우, 그 하드웨어는 다이나믹 감마 램프를 지원 한다. 하드웨어가 다이나믹 감마를 지원 하지 않는 경우는 그것을 사용할 수 없기 때문에, DirectDraw 는 이 기능을 에뮬레이트 하려고 한다.


컬러 키의 설정

[C++]

표면의 생성시 혹은 그 후로, 표면에 대한 전송원 또는 목적지 컬러 키를 설정할 수 있다.

표면의 생성시에 컬러 키 또는 키를 설정하는 경우는,IDirectDraw7::CreateSurface 에 건네주는 DDSURFACEDESC2 구조체의 ddckCKSrcBlt 및 ddckCKDestBlt 멤버의 어느 쪽인지 또는 양쪽 모두에, 적절한 컬러값을 할당한다. 블리트의 컬러 키를 확인하려면 ,dwFlags 멤버의 DDSD_CKSRCBLT 및 DDSD_CKDESTBLT 의 어느 쪽인지 또는 양쪽 모두에도 컬러값을 포함하지 않으면 안 된다.

기존 표면의 컬러 키를 설정하려면 ,IDirectDrawSurface7::SetColorKey 메소드를 사용한다. lpDDColorKey 파라미터의 키를 지정해,dwFlags 파라미터에 DDCKEY_SRCBLT 또는 DDCKEY_DESTBLT 의 어느 쪽인지를 설정한다. 이 플래그는, 전송원 또는 목적지 키의 설정의 유무를 나타낸다. DDCOLORKEY 구조체에 색역이 포함되는 경우, DDCKEY_COLORSPACE 플래그도 설정하지 않으면 안 된다. 이 플래그를 설정하지 않는 경우, 구조체의 dwColorSpaceLowValue 멤버만이 사용된다.

[Visual Basic]

표면의 생성시 혹은 그 후로, 표면에 대한 전송원 또는 목적지 컬러 키를 설정할 수 있다.

표면의 생성시에 컬러 키 또는 키를 설정하는 경우는,DirectDraw7.CreateSurface 에 건네주는 DDSURFACEDESC2 형의 ddckCKSrcBlt 및 ddckCKDestBlt 멤버의 어느 쪽인지 또는 양쪽 모두에, 적절한 컬러값을 할당한다. 블리트의 컬러 키를 확인하려면 ,lFlags 멤버의 DDSD_CKSRCBLT 및 DDSD_CKDESTBLT 의 어느 쪽인지 또는 양쪽 모두에도 컬러값을 포함하지 않으면 안 된다.

기존 표면의 컬러 키를 설정하려면 ,DirectDrawSurface7.SetColorKey 메소드를 사용한다. val 파라미터의 키를 지정해,flags 파라미터에 DDCKEY_SRCBLT 또는 DDCKEY_DESTBLT 의 어느 쪽인지를 설정한다. 이 플래그는, 전송원 또는 목적지 키의 설정의 유무를 나타낸다. DDCOLORKEY 형에 색역이 포함되는 경우, DDCKEY_COLORSPACE 플래그도 설정하지 않으면 안 된다. 이 플래그를 설정하지 않는 경우, 구조체의 low 멤버만이 사용된다.


컬러 키에 의한 블리트

[C++]

IDirectDrawSurface7::BltFast 메소드의 호출시에 표면에 컬러 키를 사용하고 싶은 경우,dwTrans 파라미터에 DDBLTFAST_SRCCOLORKEY 또는 DDBLTFAST_DESTCOLORKEY 플래그의 1 개 혹은 양쪽 모두를 설정하지 않으면 안 된다.

IDirectDrawSurface7:Blt 의 호출시에 컬러 키를 사용하려면 ,dwFlags 파라미터의 DDBLT_KEYSRC 또는 DDBLT_KEYDEST 플래그의 1 개 혹은 양쪽 모두를 건네주지 않으면 안 된다. 대신에,DDBLTFX 구조체의 ddckDestColorkey 및 ddckSrcColorkey 멤버에 적절한 컬러값을 배치할 수 있다. 이 구조체는,lpDDBltFx 파라미터로 메소드에게 건네진다. 이 경우에서도, DBLT_KEYSRCOVERRIDE 또는 DDBLT_KEYDESTOVERRIDE 플래그, 혹은 그 양쪽 모두를 dwFlags 파라미터로 설정하지 않으면 안 된다. 이 때문에, 선택된 키는 표면 프로퍼티는 아니고 DDBLTFX 구조체로부터 취득된다.

[Visual Basic]

DirectDrawSurface7.BltFast 메소드의 호출시에 표면에 컬러 키를 사용하고 싶은 경우,trans 파라미터에 DDBLTFAST_SRCCOLORKEY 또는 DDBLTFAST_DESTCOLORKEY 플래그의 1 개 혹은 양쪽 모두를 설정하지 않으면 안 된다.

DirectDrawSurface7.Blt 의 호출시에 컬러 키를 사용하려면 ,flags 파라미터의 DDBLT_KEYSRC 또는 DDBLT_KEYDEST 플래그의 1 개 혹은 양쪽 모두를 건네주지 않으면 안 된다. 혹은,DirectDrawSurface7:BltFx 메소드를 사용해,DDBLTFX 형의 ddckDestColorkey_high,ddckDestColorkey_low,ddckSrcColorkey_high 및 ddckSrcColorkey_low 멤버에 적절한 컬러값을 넣을 수가 있다. 이 형태는,BltFx 파라미터에 의해 메소드에게 건네진다. 이 경우에서도, DBLT_KEYSRCOVERRIDE 또는 DDBLT_KEYDESTOVERRIDE 플래그, 혹은 그 양쪽 모두를 flags 파라미터로 설정하지 않으면 안 된다. 이 때문에, 선택된 키는 표면 프로퍼티는 아니고 DDBLTFX 형으로부터 취득된다.


스텝 4.2 : 전송원직사각형과 목적지 직사각형의 셋업

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

드라이버의 오버레이 제한을 취득한 후, 거기에 응해 전송원 및 목적지 직사각형에 그 값을 설정한다. 이것에 의해, 오버레이를 잘 표시할 수 있게 된다. Mosquito 샘플 어플리케이션의 이하의 샘플은, 전송원직사각형의 특성을 설정하는 것으로써 시작된다.

// 전송원 RECT 에 초기값을 설정한다.
    rs.left=0; rs.top=0;
    rs.right = 320;
    rs.bottom = 240;

// 필요하면, 사이즈아라이먼트 제한을 적용한다.
    if (capsDrv.dwCaps & DDCAPS_ALIGNSIZESRC && uSrcSizeAlign)
        rs.right -= rs.right % uSrcSizeAlign;

위의 코드에서는, 표면 전체의 치수를 포함한 표면에 대한 초기값을 설정한다. 디바이스 드라이버에 전송원직사각형의 사이즈아라이먼트가 필요한 경우, 거기에 따르도록(듯이) 전송원직사각형을 조정한다. 표면을 완전하게 재생성 하지 않으면 폭을 확장할 수 없기 때문에, 이 예에서는 전송원직사각형의 폭을 원의 사이즈보다 좁아지도록(듯이) 조정한다. 다만, 작은 직사각형으로 코드를 시작하도록(듯이) 조정해, 드라이버의 제한으로 적합하도록(듯이) 직사각형을 넓혀 갈 수도 있다.

전송원직사각형의 치수를 설정해 하드웨어 제한에 따르도록(듯이) 한 후, 목적지 직사각형의 치수의 설정과 조정이 필요하다. 직사각형을 처음에 신축(스트레치) 하고 나서 사이즈아라이먼트 제한으로 적합하도록(듯이) 조정할 필요가 있는 경우도 있기 (위해)때문에, 이 프로세스에서는 다소 여분의 태스크가 필요하다. 다음의 코드에서는, 최소 신축(스트레치) 계수를 확보하기 위한 태스크를 실행한다.

// 전송원 RECT 값으로 시작되는 목적지 RECT 를 셋업 한다.
// RECT 값. 표면 치수와 전송원 RECT 치수가 다른 경우는,
// 전송원 RECT 치수를 사용한다.
    rd.left=0; rd.top=0;
    rd.right  = (rs.right*uStretchFactor1000+999)/1000;
// (999 를 더해, 정수 잘라서 버림 문제를 회피한다).

// (이것은 Ddraw 에서는 요구되지 않지만, 어스펙트비(가로세로 비율)을
//  보관 유지하기 위해서 높이도 신축(스트레치) 한다).
    rd.bottom = rs.bottom*uStretchFactor1000/1000;

위의 코드에서는, 목적지 직사각형의 맨 왼쪽 위쪽을 스크린의 맨 왼쪽 위쪽으로 설정한 후, 최소 신축(스트레치) 계수에 알맞는 폭을 설정한다. 신축(스트레치) 계수에 의한 조정중에, 폭과 신축(스트레치) 계수의 적에 999 를 더하는 것에 주의한다. 이것에 의해, 정수 잘라서 버림을 위해서(때문에) 직사각형이 최소 신축(스트레치) 계수의 요구하는 폭에 이르지 않는 사태를 회피할 수 있다. 상세 정보는, 「최소 및 최대 신축(스트레치) 계수」를 참조할것. 또, 이 예에서는, 폭을 신축(스트레치) 한 후에 높이도 신축(스트레치) 하고 있다. 높이의 신축(스트레치)는 필요하다고는되어 있지 않기는 하지만, 비트 맵의 어스펙트비(가로세로 비율)을 보관 유지해 외관의 일그러짐을 방지하기 위해서 실행한다.

목적지 직사각형을 신축(스트레치) 한 후, 그 직사각형을 사이즈아라이먼트 제한에 따르도록(듯이) 조정한다. 다음에 예를 나타낸다.

// 부과된 아라이먼트 제한으로 적합하도록,
// 목적지 RECT 의 폭을 조정한다.
    if (capsDrv.dwCaps & DDCAPS_ALIGNSIZEDEST && uDestSizeAlign)
        rd.right = (int)((rd.right+uDestSizeAlign-1) /uDestSizeAlign) *uDestSizeAlign;

이 예에서는, 능력 플래그를 조사해, 드라이버가 목적지 사이즈아라이먼트 제한을 부과하고 있을까를 본다. 제한을 부과하고 있는 경우, 목적지 직사각형의 폭은 아라이먼트 제한을 채우는데 충분한 픽셀분만큼 늘린다. 직사각형은 폭을 좁히는 것이 아니라, 넓히는 것으로 조정하는 것에 주의한다. 이것은, 폭을 좁히면(자) 목적지 직사각형이 최소 신축(스트레치) 계수로 요구된 폭보다 좁아질 가능성이 있어, 오버레이 표면의 표시가 실패하기 위해(때문에)이다.

다음 방향 :스텝 4.3 : 오버레이 표면의 표시


스텝 4.2 : 표면의 생성

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

DDSURFACEDESC2 구조체에 정보가 파묻히면(자), 그 구조체와DirectDrawCreateEx 함수로 생성 한 DirectDraw 오브젝트에의 포인터 g_pDD, 를 사용해,IDirectDraw7::CreateSurface 메소드를 호출한다. 다음에 예를 나타낸다.

hRet = g_pDD->CreateSurface(&ddsd, &g_pDDSPrimary, NULL);
if (hRet ! = DD_OK)
{
// g_pDDSPrimary 는 새로운 표면에의 포인터가 된다.
}
else
{
//  표면이 생성 되지 않았다.
return FALSE;
}

호출이 성공했을 경우,g_pDDSPrimary 파라미터는 CreateSurface 가 돌려주는프라이머리 표면에의 포인터가 된다.

프라이머리 표면에의 포인터가 이용 가능하게 되면(자),백 버퍼에의 포인터를 취득하기 위해서 IDirectDrawSurface7::GetAttachedSurface 메소드를 사용할 수 있다. 다음에 예를 나타낸다.

ZeroMemory(&ddscaps, sizeof(ddscaps));
ddscaps.dwCaps = DDSCAPS_BACKBUFFER;
hRet = g_pDDSPrimary->GetAttachedSurface(&ddscaps, &g_pDDSBack);
if (hRet ! = DD_OK)
{
    // g_pDDSBack 는 백 버퍼에의 포인터가 된다.
}
else
{
    return FALSE;
}

표면의프라이머리 표면의 주소를 제공해,DDSCAPS_BACKBUFFER 플래그로 그 능력값을 설정하는 것으로써,IDirectDrawSurface7::GetAttachedSurface 의 호출이 성공했을 경우에,g_pDDSBack 파라미터는백 버퍼에의 포인터가 된다.

다음 방향 :스텝 5 : 표면에의 쓰기


스텝 4.1 : 표면 요건의 정의

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

플립핑 표면을 생성 하는 최초의 스텝은,DDSURFACEDESC2 구조체로 표면 요건을 정의하는 것이다. 다음의 예에서는, 플립핑 표면을 생성 하는데 필요한, 구조체 정의와 플래그를 나타내고 있다.

// 1 개의 백 버퍼가 있는 프라이머리 표면을 생성 한다.
ZeroMemory(&ddsd, sizeof(ddsd));
ddsd.dwSize = sizeof(ddsd);
ddsd.dwFlags = DDSD_CAPS | DDSD_BACKBUFFERCOUNT;
ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE | DDSCAPS_FLIP |
                      DDSCAPS_COMPLEX;
ddsd.dwBackBufferCount = 1;

이 예에서는,dwSize 멤버가 DDSURFACEDESC2 구조체의 사이즈로 설정된다. 이것은, DirectDraw 메소드의 호출로 무효인 멤버 에러가 돌아가지 않게 하기 위한(해)이다 (dwSize 멤버는,DDSURFACEDESC2 구조체의 장래의 확장 기능에 대해서 준비된 것이다).

dwFlags 멤버는,DDSURFACEDESC2 구조체의 어느 멤버에 유효한 정보를 묻는지를 결정한다. DDEx1 의 예에서는,dwFlags 를 설정하는 것으로,DDSCAPS 구조체 (DDSD_CAPS)를 사용해백 버퍼 (DDSD_BACKBUFFERCOUNT)를 생성 하는 것을 지정한다.

이 예의 dwCaps 멤버는,DDSCAPS 구조체로 사용되는 플래그를 나타내고 있다. 이 경우,프라이머리 표면 (DDSCAPS_PRIMARYSURFACE),플립핑 표면 (DDSCAPS_FLIP), 및복합 표면 (DDSCAPS_COMPLEX)을 지정한다.

마지막으로, 이 예에서는 백 버퍼를 1 개 지정한다. 백 버퍼는, 배경과 스프라이트가 실제로 기입해지는 장소이다. 그리고, 백 버퍼는 프라이머리 표면에 플립 된다. DDEx1 의 예에서는, 백 버퍼의 수는 1 으로 설정되어 있다. 다만, 디스플레이 메모리의 허용 범위내이면, 몇개(살)에서도 백 버퍼를 생성 할 수 있다. 1 개(살) 이상의 백 버퍼의 생성에 관한 상세 정보는, 「트리플 버퍼링」을 참조할것.

표면 메모리는, 디스플레이 메모리 또는 시스템 메모리의 어느 쪽인지이다. 어플리케이션이 디스플레이 메모리를 다 사용하는 경우 (예를 들어, 1 MB 의 RAM 밖에 없는 디스플레이 어댑터상에서 복수의백 버퍼를 지정했을 경우),DirectDraw 는 시스템 메모리를 사용한다. 또,DDSCAPS 구조체의 dwCaps 멤버를 DDSCAPS_SYSTEMMEMORY 또는 DDSCAPS_VIDEOMEMORY 로 설정하는 것으로써, 시스템 메모리만, 또는 디스플레이 메모리만을 사용하도록(듯이) 지정할 수 있다. (DDSCAPS_VIDEOMEMORY 를 지정했지만, 표면을 생성하기 위한 충분한 메모리를 얻을 수 없는 경우,IDirectDraw7::CreateSurface 는 DDERR_OUTOFVIDEOMEMORY 에러를 돌려준다).

다음 방향 :스텝 4.2 : 표면의 생성


스텝 4.3 : 오버레이 표면의 표시

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

전송원 및 목적지의 직사각형을 셋업 한 후에, 처음으로 오버레이를 표시할 수가 있다. 올바르게 준비 되어 있으면, 간단한 것이다. Mosquito 샘플에서는 다음의 코드를 사용해, 최초로 오버레이를 표시한다.

// UpdateOverlay 에 보내는 플래그를 설정한다.
    dwUpdateFlags = DDOVER_SHOW | DDOVER_DDFX;

// 오버레이 하드웨어가 목적지 컬러 키잉을 지원 할까 ?
// 지원 하는 경우, 이미지의 주위의 검은 백그라운드를 은폐 할 수 있다.
// 아마, YUV 포맷에서는 작용할 수 없다.
    if (capsDrv.dwCKeyCaps & DDCKEYCAPS_SRCOVERLAY)
        dwUpdateFlags |= DDOVER_KEYSRCOVERRIDE;

// 전송원컬러 키를 지정하기 위한 오버레이 FX 구조체를
// 생성 한다. DDOVER_SRCKEYOVERRIDE 플래그가 설정되어 있지 않은 경우,
// 이 정보는 무시된다.
    ZeroMemory(&ovfx, sizeof(ovfx));
    ovfx.dwSize = sizeof(ovfx);

// 흑을 컬러 키로서 지정한다.
    ovfx.dckSrcColorkey.dwColorSpaceLowValue=0;
    ovfx.dckSrcColorkey.dwColorSpaceHighValue=0;

// UpdateOverlay()를 호출해, 스크린에 오버레이를 표시한다.
// screen.
    ddrval = g_lpddsOverlay->UpdateOverlay(&rs, g_lpddsPrimary, &rd, dwUpdateFlags, &ovfx);
    if(FAILED(ddrval))
        return FALSE;

위의예에서는, 일시 변수 dwUpdateFlags 에 DDOVER_SHOW 및 DDOVER_DDFX 플래그를 설정하는 것으로 시작된다. 이러한 플래그는, 오버레이의 첫회의 표시, 및 그 때문에(위해) 관련하는 DDOVERLAYFX 구조체의 이펙트 정보를 사용해야 할 하드웨어를 나타내고 있다. 다음에, 기존의 DDCAPS 구조체를 조사해, 오버레이 전송원컬러 키잉이 지원 되고 있을까를 판단한다. 지원 되고 있는 경우, 전송원컬러 키잉을 이용하기 위해서 dwUpdateFlags 변수에 DDOVER_KEYSRCOVERRIDE 를 포함해 거기에 응해 컬러 키값을 설정한다.

준비가 완료 하면,IDirectDrawSurface7::UpdateOverlay 메소드를 호출해 오버레이를 표시한다. 이 호출에서는, 최초와 3 번째의 파라미터가 조정된 전송원 및 목적지 직사각형의 주소가 된다. 2 번째의 파라미터는, 표시되는 오버레이의 프라이머리 표면의 주소가 된다. 4 번째의 파라미터는, 전에 준비한 dwUpdateFlags 변수로 설정한 플래그가 된다. 5 번째의 파라미터는, 4 번째의 파라미터로 설정한 플래그에 적합하도록(듯이) 설정된 멤버가 있는 DDOVERLAYFX 구조체의 주소가 된다.

하드웨어가 1 개의 오버레이 표면만을 지원 해, 그 표면이 사용되고 있는 경우,UpdateOverlay 메소드는 DDERR_OUTOFCAPS 를 돌려주어 실패한다. 또,UpdateOverlay 가 실패 하면, 하드웨어가 너무 작은 최소 신축(스트레치) 계수를 부정확하게 보고한 가능성을 고려해, 목적지 직사각형의 폭을 넓히려고 할지도 모른다. 그러나, 이것은 보기 드물게 밖에 일어나지 않고,UpdateOverlay 가 성공하지 않는 경우, Mosquito 는 단지 실패한다.

다음 방향 :스텝 5 : 오버레이 표시 위치의 갱신


스텝 4.1 : 최소 표시 요건의 결정

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「DirectDraw Visual Basic 튜토리얼」을 참조할것.

[C++]

대부분의 디스플레이 하드웨어는, 오버레이 표면의 표시에 제한을 부과한다. 오버레이 표면을 잘 표시하려면 , 주의 깊고 이러한 제한을 봐 가지 않으면 안 된다. 이러한 제한에 대한 정보를 취득하려면 ,IDirectDraw7::GetCaps 메소드를 호출한다. 이 메소드가 묻는 DDCAPS 구조체에는, 오버레이 능력이나 그 사용법의 제한에 대한 정보가 포함되어 있다. 하드웨어 제한은 다양해서, 항상 dwFlags 멤버의 플래그를 조사 적용하는 제한을 결정한다.

Mosquito 샘플에서는, 하드웨어 능력의 취득으로부터 시작 해, 다음에 최소 신축(스트레치) 계수에 근거해 액션을 실시한다. 다음에 이 코드를 나타낸다

    // 드라이버 능력을 취득한다.
    ddrval = g_lpdd->GetCaps(&capsDrv, NULL);
    if (FAILED(ddrval))
        return FALSE;

    // 최소 신축(스트레치)를 조사해 거기에 대응해
    // 로컬 변수를 설정한다.
    if(capsDrv.dwCaps & DDCAPS_OVERLAYSTRETCH)
        uStretchFactor1000 = (capsDrv.dwMinOverlayStretch>1000) ?  capsDrv.dwMinOverlayStretch : 1000;
    else
        uStretchFactor1000 = 1000;

위의 코드에서는, 하드웨어 능력만을 취득하기 위해서 GetCaps 를 호출한다. 이 호출로, 최초의 파라미터는, 디바이스 드라이버 능력의 정보를 묻는 DDCAPS 구조체에의 포인터가 된다. 2 번째의 파라미터는, 에뮬레이션 정보를 취득하지 않는 것을 나타내기 위해서(때문에) NULL 로 한다.

이 예에서는, 다음에 사용하기 위해(때문에), 일시 변수에 최소 신축(스트레치) 계수를 보관 유지한다 (신축(스트레치) 계수는 1000 을 걸어 보고되므로, 1300 은 실제로는 1.3 을 의미하는 것에 주의 해야 한다). 드라이버가 1000 이상의 값을 보고하는 경우, 드라이버는, 보고된 비율만 모든 목적지 직사각형이 x 축으로 따라 신축(스트레치) 되지 않으면 안 된다. 예를 들어, 드라이버가 신축(스트레치) 계수 1.3 을 보고해, 전송원직사각형의 폭이 320 픽셀인 경우, 목적지 직사각형의 폭은 적어도 416 픽셀 없으면 안 된다. 드라이버가 1000 이하의 값을 보고하는 경우, 드라이버는 전송원직사각형보다 작은 오버레이를 표시할 수 있지만, 필요에 따라서 오버레이를 신축(스트레치) 할 수 있다.

다음에, 드라이버의 사이즈아라이먼트 제한을 기술하는 값을 조사한다. 다음에 예를 나타낸다.

// 아라이먼트 제한을 취득해, 거기에 대응해
// 로컬 변수를 설정한다.
    uSrcSizeAlign = (capsDrv.dwCaps & DDCAPS_ALIGNSIZESRC)? capsDrv.dwAlignSizeSrc:0;
    uDestSizeAlign= (capsDrv.dwCaps & DDCAPS_ALIGNSIZESRC)? capsDrv.dwAlignSizeDest:0;

이 샘플에서는, 보다 많은 일시 변수를 사용해,dwAlignSizeSrc 및 dwAlignSizeDest 멤버로부터 보고되는 사이즈아라이먼트 제한을 보관 유지한다. 이러한 값은, 픽셀폭아라이먼트 제한에 대한 정보를 제공해, 다음에 이러한 제한을 반영시키기 위해서(때문에), 전송원 및 목적지 직사각형의 치수를 설정할 때에 필요하다. 전송원 및 목적지 직사각형에는, 이러한 멤버값의 배수가 되는 픽셀폭이 없으면 안 된다.

마지막으로, 목적지 직사각형의 경계 아라이먼트를 기술하는 값을 조사한다.

// "목적지 위치 아라이먼트" 글로벌을 설정해
// 오버레이 표면을 움직일 때마다 GetCaps()를 호출한다
// 필요가 없게 한다.
    if (capsDrv.dwCaps & DDCAPS_ALIGNBOUNDARYDEST)
        g_dwOverlayXPositionAlignment = capsDrv.dwAlignBoundaryDest;
    else
        g_dwOverlayXPositionAlignment = 0;

위의 코드에서는,dwAlignBoundaryDest 멤버로부터 취득한 목적지 직사각형의 경계 아라이먼트에 대한 값을 보관 유지하기 위해서, 글로벌 변수를 사용하고 있다. 이 값은, 프로그램이 다음에 오버레이를 재배치할 경우에 사용된다 (상세 정보는, 「스텝 5 : 오버레이 표시 위치의 갱신」을 참조할것). 목적지 직사각형의 맨 왼쪽 위쪽의 x 좌표는, 픽셀 단위로 이 값과 연속하도록(듯이) 설정하지 않으면 안 된다. 즉, 지정된 값이 4 이면, 목적지 직사각형의 맨 왼쪽 위쪽의 x 좌표는, 픽셀로 0, 4, 8, 12 등에 지정할 수 밖에 할 수 없다. Mosquito 어플리케이션에서는, 최초로 오버레이를 0,0 에 표시한다. 따라서, 아라이먼트 준거이라고 가정해, 오버레이가 최초로 표시될 때까지 제약 정보를 취득할 필요는 없다. 이행 방법은 다양해서, 아마, 이 정보를 조사해, 오버레이를 표시하기 전에 목적지 직사각형을 조정할 필요가 있다.

다음 방향 :스텝 4.2 : 전송원직사각형과 목적지 직사각형의 셋업


GUID_Unload

[C++]
트랙 타입 | 밴드.
목적 | 트랙의 밴드의 음색 데이터를 언로드한다. 「GUID_Download 」를 참조할것.
데이터 타입 (*pParam) | IDirectMusicPerformance 포인터.
mtTime | 미사용.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


GUID_EnableTimeSig

[C++]
트랙 타입 | 박자 기호, 스타일, 및 모티프.
목적 | 박자 기호 메세지를 무효로 한다. 「메세지의 무효화와 유효화」를 참조할것.
데이터 타입 (*pParam) | 없음.
mtTime | 미사용.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


GUID_SeedVariations

[C++]
트랙 타입 | 스타일 및 모티프.
목적 | 제로 이외의 숫자는, 바리에이션 선택에 사용하는 랜덤값을 생성할 때의 배정이 된다. 값이 0 의 경우는 디폴트 상태에 돌아와, 시스템 클록으로부터 배정을 취득한다.
데이터 타입 (*pParam) | Long.
mtTime | 미사용.

주의

이 파라미터에 제로 이외의 값을 설정 하면, 매회 같은 순서로 랜덤인 숫자가 생성되므로, 테스트 시에 도움이 된다. 파라미터는, 트랙을 연주하기 전에 한 번만 설정한다. 스타일과 커멘드 트랙은, 세그먼트(segment)가 연주될 때마다, 세그먼트(segment)의 같은 장소에서 같은 패턴이 선택되도록(듯이) 설계해야 한다. 각 루프는, 전회와는 다른 바리에이션으로 연주되지만, 세그먼트(segment) 전체가 최초부터 연주될 때마다, 각 루프는 세그먼트(segment)가 최초로 연주되었을 때 것과 같이 들린다.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


GUID_DisableTempo

[C++]
트랙 타입 | 템포.
목적 | 템포 메세지를 무효로 한다. 「메세지의 무효화와 유효화」를 참조할것.
데이터 타입 (*pParam) | 없음.
mtTime | 미사용.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


수동에 의한 밴드의 다운로드

[C++]

다음의 몇개의 방법을 사용하면(자), 밴드를 수동으로 다운로드할 수가 있다.

  • 로드 된 오브젝트로부터 IDirectMusicBand 인터페이스를 취득해,IDirectMusicBand::Download 메소드를 호출한다 (다음의 예를 참조할것). 밴드를 사용하는 세그먼트(segment)가 릴리즈 된 후에 밴드를 언로드하는 경우는, 이 방법이 적절하다.
  • GUID_Download 파라미터를 사용해 IDirectMusicSegment::SetParam 메소드를 호출해, 세그먼트(segment)의 최초의 밴드 트랙에 밴드를 다운로드한다. IDirectMusicPerformance::SetParam 를 사용해, 프라이머리 세그먼트(segment)으로 이 파라미터를 설정하거나IDirectMusicTrack::SetParam 를 사용해, 직접 밴드 트랙으로 설정할 수도 있다. 「트랙 파라미터의 설정과 꺼내」를 참조할것.

같은 음색을 반복해 다운로드해도 문제는 생기지 않는다. 1 개의 밴드내에 있는 음색이 몇번이나 나타나는 경우나, 복수의 밴드를 동시에 열어 다운로드할 경우에 같은 음색이 이러한 밴드로 사용되고 있는 경우에서도, 그 음색의 데이터는 1 회만 신디사이저에 다운로드된다.

다음의 함수는, 디스크로부터 밴드를 로드해, 그 밴드를 다운로드한다.

HRESULT myDownloadBand(
    IDirectMusicLoader *pILoader,      // 로더 인터페이스.
    IDirectMusicBand **ppBand,         // 포인터를 꺼낸다.
    IDirectMusicPerformance *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_IDirectMusicBand,
            (void **) ppBand);
    if (SUCCEEDED(hr))
    {

        // 퍼포먼스를 통해 밴드를 다운로드한다.
        hr = (*ppBand) ->Download(pPerf);

    }
    return hr;
}
[Visual Basic]

파일, 리소스, 또는 DirectMusicStyle 오브젝트로부터 DirectMusicBand 오브젝트를 취득한 후,DirectMusicBand.Download 메소드를 사용해, 밴드를 수동으로 다운로드할 수가 있다.


코드 트랙 리스트

코드 트랙 리스트에는,트랙 형식의 코드 데이터가 포함된다. 구조는 다음과 같다.

<cord-list> -> LIST( 'cord'
<crdh-ck>       // 헤더
<crdb-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 >...
    )


시스템에크스크루시브트락크체크

시스템에크스크루시브트락크체크에는,트랙 형식의 데이터가 포함된다. 다음 표 기법으로 나타내도록(듯이), 시스템에크스크루시브 항목의 배열이다.

<syex-ck> -> syex(
<DMUS_IO_SYSEX_ITEM >
<BYTE>...// 데이터
    )...


순서 트랙 리스트

순서 트랙 리스트에는,트랙 형식의 데이터가 포함된다. 리스트의 구조는 다음과 같다.

<seqt-list> -> LIST('seqt'
<evtl-ck>
<curl-ckt>
    )

리스트에는, 순서 항목과 곡선 항목의, 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 >...
    )


GUID_IDirectMusicStyle

[C++]
트랙 타입 | 스타일.
목적 | 스타일을 설정 또는 취득한다.
데이터 타입 (*pParam) | IDirectMusicStyle 포인터 (SetParam), 또는 이 포인터를 받는 변수의 주소 (GetParam).
mtTime | 트랙에 스타일을 추가하는 타임. 또는, 트랙으로부터 스타일을 꺼내는 타임, 또는 그 직후의 타임. 트랙 시간에 지정한다.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


GUID_MuteParam

[C++]
트랙 타입 | 뮤트.
목적 | 채널 (맵핑 정보)을 설정 또는 취득한다.
데이터 타입 (*pParam) | DMUS_MUTE_PARAM . 이 구조체를 GetParam 에 건네주기 전에,dwPChannel 멤버를 초기화해야 한다.
mtTime | 트랙에 뮤트 이벤트를 추가하는 타임. 또는, 트랙으로부터 뮤트 이벤트를 꺼내는 타임, 또는 그 직후의 타임. 트랙 시간에 지정한다.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


스타일 트랙 리스트

스타일 트랙 리스트에는,트랙 형식의 데이터가 포함된다. 리스트의 구조는 다음과 같다.

<sttr-list> -> LIST('sttr'(
<strf-list>...
    )

데이터는, 타임 스탬프와 스타일에의 참조를 포함한, 1 개(살) 또는 복수의 리스트로 구성된다.

<strf-list> -> LIST('strf'(
<stmp-ck>
<DMRF-list>
    )

<DMRF-list> 의 상세한 것에 대하여는, 「공통의 체크」를 참조할것.


뮤트트락크체크

뮤트트락크체크에는,트랙 형식의 데이터가 포함된다. 체크의 구조는 다음과 같다.

<mute-ck> -> mute(
<DWORD>     //DMUS_IO_MUTE 의 사이즈
<DMUS_IO_MUTE >...
    )


코만드트락크체크

코만드트락크체크에는,트랙 형식의 데이터가 포함된다. 체크의 구조는 다음과 같다.

<cmnd-ck> -> cmnd(
    <DWORD>    //Size of DMUS_IO_COMMAND
    <DMUS_IO_COMMAND >...
    )


GUID_IDirectMusicBand

[C++]
트랙 타입 | 밴드.
목적 | 밴드를 설정한다.
데이터 타입 (*pParam) | IDirectMusicBand .
mtTime | 트랙에 밴드를 추가하는 타임. 트랙 시간에 지정한다.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


밴드 트랙 형식

밴드 트랙 형식은 최상정도의 형식에도 사용할 수 있지만,트랙 형식의 데이터 부분이라고 해도 사용된다. 밴드 트랙 형식의 구조는, 다음과 같다.

RIFF( 'DMBT'
[<bdth-ck>]     // 밴드 트랙 헤더
[<guid-ck>]     // 밴드 트랙의 GUID
[<vers-ck>]     // 옵션의 버젼 정보
[<UNFO-list>]   // 이름, 작자, 저작권 정보, 코멘트
<lbdl-list>     // 밴드 리스트의 리스트
    )

사브체크는 다음과 같다.

<bnth-ck> -> bdth( <DMUS_IO_BAND_TRACK_HEADER > )

이 옵션의 체크에는, 밴드 트랙의 헤더 정보가 포함된다. 구조체의 데이터는, 자동 다운로드의 플래그뿐이다.

다음의 3 개의 요소는 옵션이다. 「공통의 체크」를 참조할것.

마지막 체크에는, 1 개(살) 또는 복수의 밴드가 포함된다.

<lbdl-list> -> LIST( 'lbdl'
<lbnd-list>...
    )

각 밴드는, 다음의 리스트에 캡슐화된다.

<lbnd-list> -> LIST( 'lbnd'
<bdih-ck>
<DMBD-form>
    )

밴드 리스트는 다음의 헤더로 시작된다.

<bdih-ck> -> ( <DMUS_IO_BAND_ITEM_HEADER > )

헤더의 뒤에밴드 형식이 계속되어, 밴드의 음색에 관한 정보가 포함된다.


밴드의 자동 다운로드

[C++]

밴드의 자동 다운로드는, 다음의 몇개의 방법으로 유효하게 할 수 있다.

  • GUID_PerfAutoDownload 파라미터를 사용해 IDirectMusicPerformance::SetParam 메소드를 호출한다. 「글로벌 파라미터의 설정과 꺼내」를 참조할것.
  • GUID_Enable_Auto_Download 파라미터를 사용해 IDirectMusicSegment::SetParam 또는 IDirectMusicTrack::SetParam 메소드를 호출한다. 「트랙 파라미터의 설정과 꺼내」를 참조할것.

다음의 코드예에서는, 퍼포먼스 pPerf 의 글로벌 파라미터를, 밴드의 자동 다운로드가 유효하게 되도록(듯이) 설정해 있다.

BOOL fAuto = TRUE;
pPerf->SetGlobalParam(GUID_PerfAutoDownload, &fAuto, sizeof(BOOL));
[Visual Basic]

DirectMusicPerformance.SetMasterAutoDownload 메소드를 사용해, 퍼포먼스 전체로 밴드의 자동 다운로드를 유효하게 하거나DirectMusicSegment.SetAutoDownloadEnable 메소드를 사용해, 세그먼트(segment) 마다 자동 다운로드를 유효하게 할 수가 있다.


GUID_Disable_Auto_Download

[C++]
트랙 타입 | 밴드.
목적 | 음색의 자동 다운로드를 무효로 한다. 「밴드의 사용법」을 참조할것.
데이터 타입 (*pParam) | 없음.
mtTime | 미사용.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


GUID_EnableTempo

[C++]
트랙 타입 | 템포.
목적 | 템포 메세지를 유효하게 한다. 「메세지의 무효화와 유효화」를 참조할것.
데이터 타입 (*pParam) | 없음.
mtTime | 미사용.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


GUID_ConnectToDLSCollection

[C++]
트랙 타입 | 밴드.
목적 | 밴드를 DLS 콜렉션에 접속한다. 「커스텀 음색에 의한 MIDI 파일의 연주」를 참조할것.
데이터 타입 (*pParam) | IDirectMusicCollection 포인터.
mtTime | 미사용.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


GUID_TempoParam

[C++]
트랙 타입 | 템포.
목적 | 템포를 설정 또는 취득한다.
데이터 타입 (*pParam) | DMUS_TEMPO_PARAM . SetParam 의 경우, 구조체의 mtTime 멤버는 무시된다. GetParam 의 경우,mtTime 멤버는, 요구된 타임부터의 템포 체인지의 오프셋(offset)를 받는다. 항상 0 이하이다.
mtTime | 템포를 설정하는 타임. 또는, 템포 체인지를 꺼내는 타임, 또는 그 직후의 타임. 트랙 시간에 지정한다.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


GUID_DisableTimeSig

[C++]
트랙 타입 | 박자 기호, 스타일, 및 모티프.
목적 | 박자 기호 메세지를 무효로 한다. 「메세지의 무효화와 유효화」를 참조할것.
데이터 타입 (*pParam) | 없음.
mtTime | 미사용.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


GUID_CommandParam2

[C++]
트랙 타입 | 커멘드.
목적 | 그루브 또는 장식 커멘드를 설정 또는 취득한다.
데이터 타입 (*pParam) | DMUS_COMMAND_PARAM2 . 이 구조체의 mtTime 멤버는, 커멘드의 실제의 타임을 준다.
mtTime | 트랙에 커멘드를 추가하는 타임. 또는, 트랙으로부터 커멘드를 꺼내는 타임, 또는 그 직후의 타임. 트랙 시간에 지정한다.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


GUID_IDirectMusicChordMap

[C++]
트랙 타입 | 코드 맵.
목적 | 코드 맵을 설정 또는 취득한다.
데이터 타입 (*pParam) | IDirectMusicChordMap 포인터 (SetParam), 또는 이 포인터를 받는 변수의 주소 (GetParam).
mtTime | 트랙에 코드 맵을 추가하는 타임. 또는, 트랙으로부터 코드 맵을 꺼내는 타임, 또는 그 직후의 타임. 트랙 시간에 지정한다.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


GUID_Download

[C++]
트랙 타입 | 밴드.
목적 | 트랙의 밴드에 음색 데이터를 다운로드한다. 「커스텀 음색에 의한 MIDI 파일의 연주」를 참조할것. 「GUID_Unload 」도 참조할것.
데이터 타입 (*pParam) | IDirectMusicPerformance 포인터.
mtTime | 미사용.

주의

IDirectMusicSegment::SetParam 를 사용해 이 파라미터를 설정 하면, 최초의 밴드 트랙의 음색만이 다운로드된다. 다른 트랙의 음색을 다운로드하려면 , 각 밴드 트랙으로 IDirectMusicSegment::GetTrack 를 사용해, 각 트랙으로 IDirectMusicTrack::SetParam 를 호출한다.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


GUID_Enable_Auto_Download

[C++]
트랙 타입 | 밴드.
목적 | 음색의 자동 다운로드를 유효하게 한다. 「밴드의 사용법」을 참조할것.
데이터 타입 (*pParam) | 없음.
mtTime | 미사용.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


GUID_TimeSignature

[C++]
트랙 타입 | 박자 기호 및 스타일.
목적 | 박자 기호를 취득한다.
데이터 타입 (*pParam) | DMUS_TIMESIGNATURE . mtTime 멤버는, 요구한 타임부터의 박자 기호의 변경의 오프셋(offset)를 받는다. 이 값은, 항상 0 이하이다.
mtTime | 박자 기호를 설정하는 타임. 또는, 박자 기호의 변경을 꺼내는 타임, 또는 그 직후의 타임. 트랙 시간에 지정한다.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


밴드의 언로드

[C++]

밴드는 메모리를 소비하기 위해(때문에), 사용하지 않게 된 밴드는 언로드해야 하는 것이다. 자동 다운로드를 유효하게 하고 있는 경우는, 세그먼트(segment)가 종료했을 때에, 세그먼트(segment)에 관련지을 수 있고 있는 밴드가 자동적으로 언로드된다. 그렇지 않은 경우는, 다음의 몇개의 방법을 사용해, 수동으로 밴드를 언로드할 수가 있다.

  • IDirectMusicBand::Unload 메소드를 호출한다.
  • GUID_Unload 파라미터를 사용해 IDirectMusicSegment::SetParam 메소드를 호출해, 세그먼트(segment)의 밴드 트랙에 있는 밴드를 언로드한다. IDirectMusicPerformance::SetParam 를 사용해, 프라이머리 세그먼트(segment)으로 이 파라미터를 설정하거나IDirectMusicTrack::SetParam 를 사용해, 직접 밴드 트랙으로 설정할 수도 있다. 「트랙 파라미터의 설정과 꺼내」를 참조할것. 예로서 「튜토리얼 1」의 「스텝 6 : DirectMusic 의 슛다운」을 참조할것.

IDirectMusicPerformance::CloseDown 메소드에서도, 다운로드된 나머지의 음색이 언로드된다.

[Visual Basic]

밴드는 메모리를 소비하기 위해(때문에), 사용하지 않게 된 밴드는 언로드해야 하는 것이다. 자동 다운로드를 유효하게 하고 있는 경우는, 세그먼트(segment)가 종료했을 때에, 세그먼트(segment)에 관련지을 수 있고 있는 밴드가 자동적으로 언로드된다. 그렇지 않은 경우는,DirectMusicBand.Unload 메소드를 사용해, 수동으로 밴드를 언로드할 수가 있다.

DirectMusicPerformance.CloseDown 메소드에서도, 다운로드된 나머지의 음색이 언로드된다.


GUID_Clear_All_Bands

[C++]
트랙 타입 | 밴드.
목적 | 트랙으로부터 모든 밴드를 소거한다.
데이터 타입 (*pParam) | 없음.
mtTime | 미사용.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


GUID_ChordParam

[C++]
트랙 타입 | 코드.
목적 | 코드 변경을 설정 또는 취득한다.
데이터 타입 (*pParam) | DMUS_CHORD_PARAM .
mtTime | 트랙에 코드를 추가하는 타임. 또는, 트랙으로부터 코드를 꺼내는 타임, 또는 그 직후의 타임. 트랙 시간에 지정한다.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


GUID_StandardMIDIFile

[C++]
트랙 타입 | 밴드.
목적 | 스탠다드 MIDI 파일 (DirectMusic 용으로 특별히 오쏘링되어 있지 않은 MIDI 파일)이, 올바르게 연주되도록(듯이) 보증한다.
데이터 타입 (*pParam) | 없음.
mtTime | 미사용.

주 : 이 파라미터는, 음색이 다운로드되기 전에, MIDI 파일에 근거하는 세그먼트(segment)로 설정되지 않으면 안 된다.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


박자 기호 트락크체크

박자 기호 트락크체크에는,트랙 형식의 데이터가 포함된다. 체크의 구조는 다음과 같다.

<tims-ck> -> tims(
<DWORD>    // DMUS_IO_TIMESIGNATURE_ITEM 의 사이즈
<DMUS_IO_TIMESIGNATURE_ITEM >...
    )


코드 맵 트랙 리스트

코드 맵 트랙 리스트에는,트랙 형식의 데이터가 포함된다. 리스트의 구조는 다음과 같다.

<pftr-list> -> LIST('pftr'
<pfrf-list>...
    )

데이터는, 타임 스탬프와 코드 맵에의 참조를 포함한, 1 개(살) 또는 복수의 리스트로 구성된다.

<pfrf-list> -> LIST('pfrf'
<stmp-ck>
<DMRF-list>
    )

타임스탄프체크의 표기법은, 다음과 같다.

<stmp-ck> -> stmp( <DWORD> )

<DMRF-list> 의 상세한 것에 대하여는, 「공통의 체크」를 참조할것.


GUID_RhythmParam

[C++]
트랙 타입 | 코드.
목적 | 트랙의 소절에 저장 되고 있는, 코드의 순서의 리듬 패턴을 취득한다.
데이터 타입 (*pParam) | DMUS_RHYTHM_PARAM . 이 구조체를 GetParam 에 건네주기 전에,TimeSig 멤버를 초기화해야 한다.
mtTime | 트랙으로부터 꺼내는 리듬 패턴이 포함되어 있는 소절의 시작, 또는 시작 직후의 타임. 트랙 시간에 지정한다.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


사인포스트트락크체크

사인포스트트락크체크에는,트랙 형식의 데이터가 포함된다. 체크의 구조는 다음과 같다.

<sgnp-list> -> sgnp(
<DWORD>    // DMUS_IO_SIGNPOST 의 사이즈
<DMUS_IO_SIGNPOST >...
    )


텐포트락크체크

텐포트락크체크에는,트랙 형식의 데이터가 포함된다. 체크의 구조는 다음과 같다.

<tetr-ck> -> tetr(
<DWORD>    // DMUS_IO_TEMPO_ITEM 의 사이즈
<DMUS_IO_TEMPO_ITEM >...
    )


GUID_CommandParam

[C++]
트랙 타입 | 커멘드.
목적 | 그루브 또는 장식 커멘드를 설정 또는 취득한다.
데이터 타입 (*pParam) | DMUS_COMMAND_PARAM2 .
mtTime | 트랙에 커멘드를 추가하는 타임. 또는, 트랙으로부터 커멘드를 꺼내는 타임, 또는 그 직후의 타임. 트랙 시간에 지정한다.

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.


구조체

여기에서는, DirectMusic 로 사용되는 다음의 실행시 구조체에 관한 레퍼런스 정보를 제공한다.

  • DMUS_BUFFERDESC
  • DMUS_CHORD_PARAM
  • DMUS_CHORD_PARAM
  • DMUS_CLOCKINFO
  • DMUS_COMMAND_PARAM
  • DMUS_COMMAND_PARAM2
  • DMUS_EVENTHEADER
  • DMUS_MUTE_PARAM
  • DMUS_NOTERANGE
  • DMUS_OBJECTDESC
  • DMUS_PORTCAPS
  • DMUS_PORTPARAMS
  • DMUS_RHYTHM_PARAM
  • DMUS_SUBCHORD
  • DMUS_SYNTHSTATS
  • DMUS_TEMPO_PARAM
  • DMUS_TIMESIGNATURE
  • DMUS_VERSION
  • DMUS_WAVES_REVERB_PARAMS
  • KSPROPERTY

구조체의 특별한 카테고리는, 이하의 주제에 기재한다.

  • 메세지
  • 파일 구조체
  • DLS 구조체

주 : 모든 DirectX 구조체의 메모리는, 사용하기 전에 0 에 초기화해야 한다. 또,dwSize 멤버를 포함한 모든 구조체는, 사용하기 전에, 멤버를 구조체의 사이즈에 바이트 단위로 설정해야 한다. 다음에 나타내는 DirectDraw 의 샘플 코드에서는, 일반적인 구조체 DDCAPS 에 대해서 이러한 태스크를 실행한다.

DDCAPS ddcaps; // 아직 사용할 수 없다.

ZeroMemory(&ddcaps, sizeof(ddcaps));
ddcaps.dwSize = sizeof(ddcaps);

// 이것으로 구조체를 사용할 수 있다.
.
.


Platform SDK: DirectX

$ IDirectMusicBuffer

IDirectMusicBuffer 는, 포트에 의해 순서화 되는, 타임 스탬프를 할당할 수 있었던 데이터 (보통은 MIDI 메세지 형식)를 포함한 버퍼를 나타낸다. 세그먼트(segment)와는 달라, 버퍼는 몇 안 되는 양의 데이터 (보통은 200ms 미만 )를 보관 유지해, 어플리케이션은 이벤트의 미소성을 제어할 때에 이 데이터를 이용한다.

어플리케이션이 독자적인 순서화를 실시하지 않는 이상 이 인터페이스의 이 메소드를 사용할 필요는 없다.

IDirectMusicPort::PlayBuffer 나 IDirectMusicPort::Read 어느 쪽인가의 메소드를 호출해 버퍼를 포트에 건네줄 때까지는, 버퍼 오브젝트는 포트 오브젝트로부터 완전하게 독립하고 있다. 그 후 어플리케이션은 버퍼를 릴리즈 해, 재이용을 가능하게 한다.

IDirectMusicBuffer 인터페이스의 메소드는, 이하의 그룹에 정리할 수가 있다.

데이터 | Flush
 | GetNextEvent
 | GetRawBufferPtr
 | PackStructured
 | PackUnstructured
 | ResetReadPtr
파라미터 | GetBufferFormat
 | GetMaxBytes
 | GetUsedBytes
 | SetUsedBytes
시간 | GetStartTime
 | SetStartTime
 | TotalTime

모든 COM 인터페이스는,IUnknown 인터페이스 메소드를 계승한다. IUnknown 인터페이스는, 이하의 3 개의 메소드를 지원 한다.

IUnknown | AddRef
 | QueryInterface
 | Release

LPDIRECTMUSICBUFFER 형은,IDirectMusicBuffer 인터페이스에의 포인터로서 정의되고 있다.

typedef IDirectMusicBuffer *LPDIRECTMUSICBUFFER;

동작환경

Windows NT/2000 : Windows 2000 이 필요.
Windows 95/98 : Windows 95 이후가 필요. Windows 95 용으로재배포 가능한 형태로 사용 가능.
헤더 : dmusicc.h 로 선언.


메세지

DirectMusic 의 메세지 구조체는, 모두 DMUS_PMSG 구조체에 근거하고 있다. C 는 계승을 지원 하고 있지 않기 때문에, 이 구조체의 멤버는 DMUS_PMSG_PART 매크로에 의해 각파생 구조체에 포함된다.

메세지의 개요에 대해서는, 「DirectMusic 메세지」를 참조할것.

여기에서는, 메세지 정보의 보관 유지에 사용되는 다음의 구조체에 관한 정보를 제공한다.

  • DMUS_PMSG
  • DMUS_CHANNEL_PRIORITY_PMSG
  • DMUS_CURVE_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

참조

IDirectMusicPerformance::AllocPMsg ,IDirectMusicPerformance::SendPMsg ,IDirectMusicPerformance::FreePMsg ,IDirectMusicTool::ProcessPMsg


spotlight 프로퍼티

[C++]

C++ 의 D3DLIGHT7 구조체에는, spotlight에서만 사용하는 3 개의 멤버가 포함되어 있다. 이러한 멤버 (dvFalloff,dvTheta,dvPhi)는, spotlight 오브젝트의 내부 콘과 외부 콘의 크기를 제어해, 양쪽 모두의 콘의 사이에 라이트가 어떻게 감소하는지를 제어한다. 이러한 특성의 일반적인 설명에 대해서는, 「spotlight」를 참조할것.

dvTheta 값은 spotlight의 내부 콘의 라디안 각도를 나타내,dvPhi 값은 외부 콘의 라디안 각도를 나타낸다. dvFalloff 값은, 내부 콘의 외측 엣지와 외부 콘의 안쪽 엣지와의 사이로, 라이트의 강도가 어떻게 감소하는지를 제어한다. 대부분의 어플리케이션에서는,dvFalloff 를 1.0 으로 설정해 2 개의 콘간에 폴 오프가 한결같게 생기도록(듯이) 하지만, 필요에 따라서 이외의 값을 설정할 수도 있다. 폴 오프의 계산에 대해 Direct3D 가 사용하는 수학적 모델의 상세한 것에 대하여는, 「spotlight 폴 오프 모델」을 참조할것.

다음의 그림은, 멤버의 값의 사이에 있는 관계와 이러한 값이 spotlight의 내부 콘과 외부 콘에게 주는 영향을 나타낸다.

[Visual Basic]

Visual Basic 의 D3DLIGHT7 형에는, spotlight에서만 사용하는 3 개의 멤버가 포함되어 있다. 이러한 멤버 (falloff,theta,phi)는, spotlight 오브젝트의 내부 콘과 외부 콘의 크기를 제어해, 양쪽 모두의 콘의 사이에 라이트가 어떻게 감소하는지를 제어한다. 이러한 특성의 일반적인 설명에 대해서는, 「spotlight」를 참조할것.

theta 값은 spotlight의 내부 콘의 라디안 각도를 나타내,phi 값은 외부 콘의 라디안 각도를 나타낸다. falloff 값은, 내부 콘의 외측 엣지와 외부 콘의 안쪽 엣지와의 사이로, 라이트의 강도가 어떻게 감소하는지를 제어한다. 대부분의 어플리케이션에서는,falloff 를 1.0 으로 설정해 2 개의 콘간에 폴 오프가 한결같게 생기도록(듯이) 하지만, 필요에 따라서 이외의 값을 설정할 수도 있다. 폴 오프의 계산에 대해 Direct3D 가 사용하는 수학적 모델의 상세한 것에 대하여는, 「spotlight 폴 오프 모델」을 참조할것.

다음의 그림은, 멤버의 값의 사이에 있는 관계와 이러한 값이 spotlight의 내부 콘과 외부 콘에게 주는 영향을 나타낸다.


큐브 환경 맵이란

큐브 환경 맵 ("큐브 맵" 으로 불리는 일도 있다)이란, 오브젝트의 주위의 경치를 오브젝트가 입방체의 중심으로 있는 것 같게 표현한 화면 데이터를 포함한 텍스쳐이다. 큐브 환경 맵의 각면은, 수평 방향과 수직 방향의 90о의 시야를 대상으로 해, 1 개의 큐브 맵에는 6 개의 면이 있다. 각면의 방향은, 다음의 그림에 나타내는 대로이다.

입방체의 각면은, 월드 공간의 x/y, y/z, 또는 x/z 평면에 수직에 위치 좌표 한다. 다음의 그림은, 각 평면과 면의 대응을 나타낸다.

큐브 환경 맵은, 일련의 Attach 된 텍스쳐 표면으로서 이행 되어 1 회의 호출로 생성 된다. 이러한 텍스쳐 표면에의 액세스는, 그 외의 Attach 되고 있는 표면 세트와 같게 실시할 수가 있다. 어플리케이션에서는, 큐브 환경 맵에 정적인 화면을 사용하거나 큐브 맵의 면에 렌더링을 실시하는 것으로 동적인 환경 맵핑을 실행할 수가 있다 (이 경우, 큐브 맵 표면은 유효한 렌더링 타겟 표면이 아니면 안되어, DDSCAPS_3DDEVICE 로 생성 되고 있을 필요가 있다).

큐브 맵의 각면에는, 주위의 장면이 치밀하게 렌더링 될 필요는 없다. 대부분의 경우, 환경 맵은 만곡 표면에 적용된다. 대부분의 어플리케이션으로 사용하는 만곡의 정도가 주어졌다고 하면, 결과적으로 히않고 다 화면이 생성되기 (위해)때문에, 환경 맵의 치밀함은 메모리의 점으로부터도 렌더링의 오버헤드의 점으로부터도 쓸데없게 된다.


뷰포트 클리핑 볼륨의 설정

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

[C++]

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

    memset(&viewData, 0, sizeof(D3DVIEWPORT7));
    viewData.dwX = 0;
    viewData.dwY = 0;
    viewData.dwWidth  = width;
    viewData.dwHeight = height;
    viewData.dvMinZ = 0.0f;
    viewData.dvMaxZ = 1.0f;

D3DVIEWPORT7 구조체에 값을 설정한 후,IDirect3DViewport7::SetViewport 메소드를 호출해 디바이스에 뷰포트 파라미터를 적용한다. 다음의 예는 이 호출을 나타낸다.

    HRESULT hr;

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

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

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

[Visual Basic]

다음의 Visual Basic 코드에서는, 이 내용을 실현하기 위해서(때문에) D3DVIEWPORT7 형의 설정을 실시한다.

Dim viewData As D3DVIEWPORT7

With viewData
. lX = 0:. lY = 0
. lWidth = Width:.lHeight = Height
. minz = 0#:. maxz = 1#
End With

D3DVIEWPORT7 형에 값을 설정한 후,Direct3DDevice7.SetViewport 메소드를 호출해 디바이스에 뷰포트 파라미터를 적용한다.

' dev 변수에는 Direct3DDevice7 오브젝트에의 유효한 참조가 저장 된다.
Call dev.SetViewport(viewData)

이 호출의 뒤, 뷰포트 파라미터가 설정되어 다음번 렌더링 메소드를 호출했을 때에 이 뷰포트 파라미터가 유효하게 된다. 뷰포트 파라미터값을 변경할 필요가 있는 경우는,D3DVIEWPORT7 형의 값을 갱신해, 재차 SetViewport 호출하는 것만으로 좋다.


텍스쳐 좌표의 자동 생성에 대해

Platform SDK: DirectX

텍스쳐 좌표의 자동 생성에 대해

시스템에서는, 트랜스 폼 후의 카메라 공간 위치 좌표 또는 버텍스의 법선을 텍스쳐 좌표로서 사용할 수 있다. 또, 큐브 환경 맵을 실행하기 위한 3 요소 벡터를 계산하는 일도 가능하다. 버텍스로써 명시적으로 지정하는 텍스쳐 좌표와 같이, 자동 생성된 텍스쳐 좌표는, 텍스쳐 좌표 트랜스 폼용의 입력으로서 사용된다.

텍스쳐 좌표의 자동 생성에서는, 버텍스 포맷에서의 명시적인 텍스쳐 좌표의 필요성을 배제하는 것으로, 지오메트리 데이터로 필요한 대역폭을 큰폭으로 삭감할 수 있다. 많은 경우, 시스템으로 생성된 텍스쳐 좌표는, 특수 효과를 베푸는 트랜스 폼과 함께 사용할 수 있다. 물론, 이 기능은 특수한 용도에 사용되는 것이어, 명시적인 텍스쳐 좌표를 사용하는 케이스도 많이 있다.


클립면의 유효/무효

[C++]

클립면은,IDirect3DDevice7::SetClipPlane 메소드를 호출해도 자동적으로는 유효하게 안 되기 때문에 주의할 필요가 있다. 디바이스에 현재 설정되어 있는 클립면을 유효 또는 무효로 하려면 ,D3DRENDERSTATE_CLIPPLANEENABLE 렌더링 스테이트를 사용한다. 이 렌더링 스테이트는 DWORD 값을 받는다. 최하정도 비트로부터 시작되는 각 비트가 클립면에 대응한다. 1 비트가 설정되면(자) 클립면이 유효하게 되어, 이 비트가 클리어 되면(자) 그 클립면이 무효가 된다. 값에 대해서는, 비트 0 은 인덱스 0 의 클립면을 유효 및 무효로 해, 비트 1 은 인덱스 1 의 클립면을 제어한다, 라고 하는 순서로 비트 31 까지 있다 (Direct3D 에서는 한 번에 최대 32 개의 평면에서 클리핑이 가능하지만, 디바이스로 그것이 가능한가 어떤가는 가지각색이다). 이러한 의미들에 의해, 어플리케이션에서는 1 회의 호출로 모든 클립면을 유효 또는 무효로 할 수 있다.

d3dtypes.h 헤더 파일에는 D3DCLIPPLANEn 매크로가 정의되고 있다. 이 매크로는, D3DRENDERSTATE_CLIPPLANEENABLE 렌더링 스테이트의 값으로서 조합해 건네줄 수가 있는 값의 패턴을 생성 한다. 다음의 C++ 코드에서는, 이 매크로를 사용한다.

// 이 예에서는, pd3dDevice 변수는 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다.

// 클립면의 0 및 1 을 유효하게 한다.
// 그 외 모든 유저 정의 클립면은 무효이다고 한다.
pd3dDevice->SetRenderState( D3DRENDERSTATE_CLIPPLANEENABLE,
D3DCLIPPLANE0 | D3DCLIPPLANE1);
[Visual Basic]

클립면은,Direct3DDevice7.SetClipPlane 메소드를 호출해도 자동적으로는 유효하게 안 되기 때문에 주의할 필요가 있다. 디바이스에 현재 설정되어 있는 클립면을 유효 또는 무효로 하려면 ,D3DRENDERSTATE_CLIPPLANEENABLE 렌더링 스테이트를 사용한다. 이 렌더링 스테이트의 값은,CONST_D3DCLIPPLANEFLAGS 열거로부터의 값이다. 이 열거로부터의 값의 편성을 지정 하면, 대응하는 클립면이 유효하게 되어, 이러한 값을 생략 하면, 대응하는 클립면이 무효가 된다 (D3DCPF_DISABLEALL 를 사용 하면, 모든 클립면이 무효가 된다). 이러한 의미들에 의해, 어플리케이션에서는 1 회의 호출로 모든 클립면을 유효 또는 무효로 할 수 있다.

다음의 Visual Basic 코드는, 이 메소드의 사용 방법을 나타낸다.

'이 예에서는, d3dDevice 변수는 Direct3DDevice7 오브젝트에의
'유효한 참조이다.

'클립면의 0 및 1 을 유효하게 한다.
'그 외 모든 유저 정의 클립면은 무효이다고 한다.
Call d3dDevice.SetRenderState(D3DRENDERSTATE_CLIPPLANEENABLE, _
(D3DCPF_ENABLEPLANE0 Or D3DCPF_ENABLEPLANE1))


라이트 프로퍼티의 취득

[C++]

C++ 로, 기존의 광원의 프로퍼티를 모두 취득하려면 , 디바이스에 대해서 IDirect3DDevice7::GetLight 메소드를 호출한다. GetLight 메소드를 호출하면 와, 프로퍼티를 취득하는 광원의 0 으로부터 시작되는 인덱스를 제 1 파라미터에 건네주어,D3DLIGHT7 구조체의 주소를 제 2 파라미터에 건네준다. 디바이스는,D3DLIGHT7 구조체에 값을 설정해, 지정된 인덱스의 광원에서 그 디바이스가 사용하는 라이트 프로퍼티를 기술한다.

다음의 C++ 코드는 이 처리를 나타낸다.

    /*
* 이 예에서는, g_lpd3dDev 변수는 IDirect3DDevice7 인터페이스에의
* 유효한 포인터이다.
     */
HRESULT hr;
D3DLIGHT7 light;

// 최초의 라이트에 대한 프로퍼티 정보를 취득한다.
hr = g_lpd3dDev->GetLight(0, light);
if (FAILED(hr))
    {
// 에러 처리 코드
    }

디바이스내에서 할당할 수 있고 있는 광원의 범위외의 인덱스를 지정 하면,GetLight 메소드는 실패해,DDERR_INVALIDPARAMS 를 돌려준다.

[Visual Basic]

Visual Basic 어플리케이션으로, 기존의 광원의 프로퍼티를 취득하려면 , 디바이스에 대해서 Direct3DDevice7.GetLight 메소드를 호출한다. GetLight 메소드를 호출하면 와, 프로퍼티를 취득하는 광원의 0 으로부터 시작되는 인덱스를 제 1 파라미터에 건네주어,D3DLIGHT7 형의 변수를 제 2 파라미터에 건네준다. 디바이스는,D3DLIGHT7 형에 값을 설정해, 지정된 인덱스의 광원에서 그 디바이스가 사용하는 라이트 프로퍼티를 기술한다.

다음의 Visual Basic 코드는 이 처리를 나타낸다.

'
'이 예에서는, d3dDevice 변수에 Direct3DDevice7 오브젝트에의
'유효한 참조가 저장 된다.
'
Dim lightDesc As D3DLIGHT7

'최초의 라이트에 대한 프로퍼티 정보를 취득한다.
Call d3dDevice.GetLight(0, lightDesc)
If Err.Number <> DD_OK Then
'에러 처리 코드
End If

디바이스내에서 할당할 수 있고 있는 광원의 범위외의 인덱스를 지정 하면,GetLight 메소드는 실패해,Err.Number 의 값이 DDERR_INVALIDPARAMS 가 된다.


스테이트 블록 핸들

스테이트 블록 핸들이란, 캐쉬되고 있는, 디바이스 스테이트의 그룹을 일의에 식별하는 32 비트값으로, 렌더링 디바이스내의 대응하는 스테이트값이다. 이러한 핸들은, 디바이스에 스테이트를 적용하기 위해서 사용하거나 렌더링 디바이스의 현재의 스테이트를 취득하거나 혹은 캐쉬되고 있는 스테이트가 불필요하게 되었을 경우는 그 스테이트를 삭제하기 위해서 사용할 수 있다.

[C++]

C++ 에서는, 스테이트 블록 핸들을 받는 것은,IDirect3DDevice7::EndStateBlock 메소드를 호출해 스테이트 블록의 기록을 종료했을 때, 및 IDirect3DDevice7::CreateStateBlock 메소드를 호출해 사전 정의되고 있는 디바이스 스테이트 데이터 세트를 취득했을 때이다.

[Visual Basic]

Visual Basic 에서는, 스테이트 블록 핸들을 받는 것은,Direct3DDevice7.EndStateBlock 메소드를 호출해 스테이트 블록의 기록을 종료했을 때, 및 Direct3DDevice7.CreateStateBlock 메소드를 호출해 사전 정의되고 있는 디바이스 스테이트 데이터 세트를 취득했을 때이다.


스테이트 블록의 적용

[C++]

IDirect3DDevice7::ApplyStateBlock 메소드는, 기존의 스테이트 블록을 디바이스에 적용한다. ApplyStateBlock 메소드는, 파라미터 dwBlockHandle 를 1 개만 받는다. 이 파라미터는, 적용하는 스테이트 블록을 식별한다.

주 : 스테이트 블록의 기록중 (즉,IDirect3DDevice7::BeginStateBlock 로부터 IDirect3DDevice7::EndStateBlock 의 호출동안), 다른 스테이트 블록을 적용할 수 없다. 이것을 실행하려고 하면(자) 실패해,D3DERR_INBEGINSTATEBLOCK 가 돌려주어진다.

[Visual Basic]

Direct3DDevice7.ApplyStateBlock 메소드는, 기존의 스테이트 블록을 디바이스에 적용한다. ApplyStateBlock 메소드는, 파라미터 blockHandle 를 1 개만 받는다. 이 파라미터는, 적용하는 스테이트 블록을 식별한다.

주 : 스테이트 블록의 기록중 (즉,Direct3DDevice7.BeginStateBlock 로부터 Direct3DDevice7.EndStateBlock 의 호출동안), 다른 스테이트 블록을 적용할 수 없다. 이것을 실행하려고 하면(자) 실패해,D3DERR_INBEGINSTATEBLOCK 가 돌려주어진다.


텍스쳐 좌표 처리의 흐름

다음의 그림은, 텍스쳐 좌표가 처리를 통해 래스터라이저에 보내질 때까지의 흐름을 나타낸다.

[C++]

시스템에서는, 2 개의 소스로부터 텍스쳐 좌표를 드로잉(Drawing) 할 수 있다. 소정의 텍스쳐 스테이지에서는, 버텍스 포맷 (D3DFVF_TEX1 ~ D3DFVF_TEX8)에 포함되는 텍스쳐 좌표를 사용하는지, 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 텍스쳐 좌표를 생성할 수 있다.

[Visual Basic]

시스템에서는, 2 개의 소스로부터 텍스쳐 좌표를 드로잉(Drawing) 할 수 있다. 소정의 텍스쳐 스테이지에서는, 버텍스 포맷 (D3DFVF_TEX1 ~ D3DFVF_TEX8)에 포함되는 텍스쳐 좌표를 사용하는지, Direct3D 로 자동 생성한 텍스쳐 좌표를 사용할 수 있다. 문자의 대문자/소문자의 구별의 상세한 것에 대하여는, 「텍스쳐 좌표의 자동 생성」을 참조할것. 현재의 텍스쳐 스테이지의 D3DTSS_TEXTURETRANSFORMFLAGS 텍스쳐 스테이지 스테이트를 D3DTTFF_DISABLE 로 설정 하면 (디폴트 설정), 입력 좌표는 트랜스 폼 되지 않는다. D3DTSS_TEXTURETRANSFORMFLAGS 를 다른 값으로 설정 하면, 그 스테이지의 트랜스 폼 행렬이 입력 좌표에 적용된다.

CONST_D3DTEXTURETRANSFORMFLAGS 열거는, D3DTSS_TEXTURETRANSFORMFLAGS 텍스쳐 스테이지 스테이트에 유효한 값을 정의한다. 텍스쳐 좌표 트랜스 폼을 실행하지 않는 D3DTTFF_DISABLE 플래그를 제외해, 이 열거에 정의되는 값은, 시스템에 의해 래스터라이저에게 건네지는 출력 좌표의 개수를 설정한다. D3DTTFF_COUNT1 ~ D3DTTFF_COUNT4 플래그의 경우, 1, 2, 3, 또는 4 개의 요소가 출력 좌표로부터 래스터라이저에게 건네진다.

D3DTTFF_PROJECTED 플래그는 특별한 플래그이다. 이 플래그는, 텍스쳐 좌표가 투영 텍스쳐용의 것임을 시스템에 알린다. D3DTTFF_PROJECTED 플래그와 CONST_D3DTEXTURETRANSFORMFLAGS 의 그 외의 멤버를 조합하는 것으로, 모든 요소를 마지막 요소로 나눗셈 하고 나서 라스터화를 실행하도록(듯이) 래스터라이저에 알린다. 예를 들어, 3 요소의 텍스쳐 좌표 (또는, 트랜스 폼 후의, 3 요소의 텍스쳐 좌표)를 명시적으로 사용할때, D3DTTFF_COUNT3 및 D3DTTFF_PROJECTED 플래그를 조합해 사용 하면, 래스터라이저로 최초의 2 개의 요소를 마지막 요소로 나눗셈 해, 2D 텍스쳐의 처리에 필요한 2D 텍스쳐 좌표를 생성할 수 있다.

주 : 큐브 환경 맵을 제외해, 래스터라이저에서는 3 개 이상의 요소를 사용해 텍스쳐를 처리할 수 없다. 현재 텍스쳐를 처리하기 위해서 사용할 수 있는 요소수보다 많은 요소를, 텍스쳐 스테이지로 지정했을 경우, 무관계한 요소는 무시된다. 이것은, 1D 텍스쳐에 대해서 2D 텍스쳐 좌표를 사용할때에도 들어맞는다.


라이팅 스테이트

Direct3D 의 지오메트리 파이프라인을 사용하는 어플리케이션에서는, 라이팅 계산을 유효 또는 무효로 할 수 있다. 버텍스 법선을 포함한 버텍스에게만, 라이팅이 올바르게 적용된다. 버텍스 법선이 없는 경우는, 모든 라이팅 계산으로 0 의 내적이 사용된다. 즉, 법선을 사용하지 않는 버텍스에는 라이팅이 적용되지 않는다. 상세한 것에 대하여는, 「Direct3D 의 라이팅에 있어서의 수학적 계산」을 참조할것.

[C++]

어플리케이션으로 Direct3D 의 라이팅을 유효하게 하려면 ,D3DRENDERSTATE_LIGHTING 렌더링 스테이트를 TRUE (디폴트 설정)로 설정해, Direct3D 의 라이팅을 무효로 하려면 FALSE 로 설정한다.

라이팅 렌더링 스테이트는, 버텍스 버퍼내의 버텍스로써 가능한 라이팅 계산에는 전혀 의존하지 않는다. IDirect3DVertexBuffer7::ProcessVertices 및 IDirect3DVertexBuffer7::ProcessVerticesStrided 메소드는, 버텍스 처리 시에 라이팅 계산을 제어하는, 독자적인 플래그를 받는다.

주 : 이 렌더링 스테이트는, 반대이지만 종래의 렌더링 메소드로 사용된 D3DDP_DONOTLIGHT 플래그 와 유사한다. DirectX 7.0 에서는, 이 렌더링 스테이트가 D3DDP_DONOTLIGHT 플래그에 옮겨지고 있다. D3DDP_DONOTLIGHT 플래그로 1 회가 호출할 것에 라이팅을 무효로 하는 경우, 스테이트값이 어플리케이션에 의해 재차 변경될 때까지는, 렌더링에 관한 모든 호출이 이 렌더링 스테이트의 영향을 받는다.

[Visual Basic]

어플리케이션으로 Direct3D 의 라이팅을 유효하게 하려면 ,D3DRENDERSTATE_LIGHTING 렌더링 스테이트를 TRUE (디폴트값)로 설정해, 무효로 하려면 FALSE 로 설정한다.

라이팅 렌더링 스테이트는, 버텍스 버퍼내의 버텍스로써 가능한 라이팅 계산에는 전혀 의존하지 않는다. IDirect3DVertexBuffer7::ProcessVertices 및 IDirect3DVertexBuffer7::ProcessVerticesStrided 메소드는, 버텍스 처리 시에 라이팅 계산을 제어하는, 독자적인 플래그를 받는다.

주 : 이 렌더링 스테이트는, 반대이지만 종래의 렌더링 메소드로 사용된 D3DDP_DONOTLIGHT 플래그 와 유사한다. DirectX 7.0 에서는, 이 렌더링 스테이트가 D3DDP_DONOTLIGHT 플래그에 옮겨지고 있다. D3DDP_DONOTLIGHT 플래그로 1 회가 호출할 것에 라이팅을 무효로 하는 경우, 스테이트값이 어플리케이션에 의해 재차 변경될 때까지는, 렌더링에 관한 모든 호출이 이 렌더링 스테이트의 영향을 받는다.


포그(안개:fog) 스테이트

포그(안개:fog) 이펙트를 사용 하면, 3D 신을 한층 리얼하게 표현할 수 있다. 포그(안개:fog) 이펙트는, 단순한 안개의 시뮬레이션 이외에도 사용할 수 있다. 포그(안개:fog) 이펙트로 먼 경치를 애매하게 할 수가 있다. 이것은, 현실의 세계에서 일어나는 것을 반영한 것이다. 오브젝트가 뷰아로부터 멀어지는 만큼, 오브젝트의 세부가 불명료하게 된다. 어플리케이션에서의 포그(안개:fog)의 사용의 상세한 것에 대하여는, 「포그(안개:fog)」를 참조할것.

[C++]

C++ 어플리케이션에서는, 디바이스 렌더링 스테이트를 개입시켜 포그(안개:fog)를 제어한다. D3DRENDERSTATETYPE 열거형에는, 픽셀 (테이블) 또는 버텍스 포그(안개:fog)의 머지않아가 사용되고 있는지, 그 색, 시스템이 적용하는 포그(안개:fog) 공식, 및 그 공식에의 파라미터등을 제어하는 스테이트가 포함된다.

포그(안개:fog)를 유효하게 하려면 ,D3DRENDERSTATE_FOGENABLE 렌더링 스테이트를 TRUE 로 설정한다. 포그(안개:fog) 컬러는, 임의의 D3DCOLOR 값으로 설정할 수 있다 (포그(안개:fog) 컬러의 알파 성분은 무시된다). 상세한 것에 대하여는, 「D3DRENDERSTATE_FOGCOLOR .」(을)를 참조할것.

D3DRENDERSTATE_FOGTABLEMODE 및 D3DRENDERSTATE_FOGVERTEXMODE 렌더링 스테이트는, 포그(안개:fog)의 계산에 적용되는 포그(안개:fog) 공식을 제어해, 적용되는 포그(안개:fog)의 종류를 간접적으로 제어한다. 이 양쪽 모두의 렌더링 스테이트는,D3DFOGMODE 열거형의 멤버의 어느 쪽인가에 설정할 수 있다. 렌더링 스테이트의 어느쪽이든을 D3DFOG_NONE 로 설정 하면, 거기에 응해 픽셀 또는 버텍스 포그(안개:fog)가 무효가 된다. 양쪽 모두의 렌더링 스테이트를 유효한 모드로 설정했을 경우는, 픽셀 포그(안개:fog) 이펙트만 적용된다.

D3DRENDERSTATE_FOGSTART 및 D3DRENDERSTATE_FOGEND 렌더링 스테이트는, D3DFOG_LINEAR 모드용의 포그(안개:fog) 공식 파라미터를 제어한다. D3DRENDERSTATE_FOGDENSITY 렌더링 스테이트는, 지수 포그(안개:fog) 모드의 포그(안개:fog) 농도를 제어한다.

상세한 것에 대하여는, 「포그(안개:fog) 파라미터」를 참조할것.

[Visual Basic]

Visual Basic 어플리케이션에서는, 디바이스 렌더링 스테이트를 개입시켜 포그(안개:fog)를 제어한다. CONST_D3DRENDERSTATETYPE 열거형에는, 픽셀 (테이블) 또는 버텍스 포그(안개:fog)의 머지않아가 사용되고 있는지, 그 색, 시스템이 적용하는 포그(안개:fog) 공식, 및 그 공식에의 파라미터등을 제어하는 스테이트가 포함된다.

포그(안개:fog)를 유효하게 하려면 ,D3DRENDERSTATE_FOGENABLE 렌더링 스테이트를 TRUE 로 설정한다. 포그(안개:fog) 컬러는,DirectX7.CreateColorRGB 메소드가 돌려주는, 임의의 Long 형의 값으로 설정할 수 있다. 「D3DRENDERSTATE_FOGCOLOR 」를 참조할것.

D3DRENDERSTATE_FOGTABLEMODE 및 D3DRENDERSTATE_FOGVERTEXMODE 렌더링 스테이트는, 포그(안개:fog)의 계산에 적용되는 포그(안개:fog) 공식을 제어해, 적용되는 포그(안개:fog)의 종류를 간접적으로 제어한다. 이 양쪽 모두의 렌더링 스테이트는,CONST_D3DFOGMODE 열거의 멤버의 어느 쪽인가에 설정할 수 있다. 렌더링 스테이트의 어느쪽이든을 D3DFOG_NONE 로 설정 하면, 거기에 응해 픽셀 또는 버텍스 포그(안개:fog)가 무효가 된다. 양쪽 모두의 렌더링 스테이트를 유효한 모드로 설정했을 경우는, 픽셀 포그(안개:fog) 이펙트만 적용된다.

D3DRENDERSTATE_FOGSTART 및 D3DRENDERSTATE_FOGEND 렌더링 스테이트는, D3DFOG_LINEAR 모드용의 포그(안개:fog) 공식 파라미터를 제어한다. D3DRENDERSTATE_FOGDENSITY 렌더링 스테이트는, 지수 포그(안개:fog) 모드의 포그(안개:fog) 농도를 제어한다.

상세한 것에 대하여는, 「포그(안개:fog) 파라미터」를 참조할것.


렌더링 커멘드 배치처리 스테이트

[Visual Basic]

여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

주 : 이 렌더링 스테이트는, 텍스쳐 핸들로 (IDirect3DDevice2 인터페이스를 사용) 렌더링 하는 어플리케이션 이외에서는 사용할 수 없다. IDirect3DDevice7 인터페이스로 렌더링 하면, 배치처리 된 프리미티브는 암묵적으로 플래시 된다.


표면의 클리어

장면의 오브젝트를 렌더링 하기 전에, 렌더링 타겟 표면의 뷰포트 (또는 뷰포트의 서브 세트)를 클리어 한다. 뷰포트를 클리어 하면, 시스템은 렌더링 타겟 표면의 드로잉(Drawing) 부분, 및 Attach 된 깊이 버퍼 또는 스텐실 버퍼를 지정의 스테이트로 설정한다. 그 결과, 재차 렌더링 하는 표면의 영역이 리셋 되어 깊이 버퍼와 스텐실 버퍼를 사용하고 있는 경우는, 그 대응하는 영역이 리셋 된다. 렌더링 타겟 표면을 클리어 하면, 지정한 영역을 디폴트의 색이나 텍스쳐로 설정할 수 있다. 깊이 버퍼 및 스텐실 버퍼에 대해서는, 깊이 및 스텐실값을 설정할 수 있다.

[C++]

IDirect3DDevice7 인터페이스에는, 뷰포트를 클리어 하는 IDirect3DDevice7::Clear 메소드가 있다. 이러한 메소드의 사용 방법의 상세한 것에 대하여는, 「뷰포트와 클리핑」섹션의 「뷰포트의 클리어」를 참조할것.

[Visual Basic]

Visual Basic 의 Direct3DDevice7 클래스에는, 뷰포트를 클리어 하는 Direct3DDevice7.Clear 메소드가 있다. 이러한 메소드의 사용 방법의 상세한 것에 대하여는, 「뷰포트와 클리핑」섹션의 「뷰포트의 클리어」를 참조할것.

최적화에 관한 주의 : 렌더링 타겟 표면의 전영역에 이르는 장면을 렌더링 하는 어플리케이션으로, 퍼포먼스를 개선하려면 , 렌더링 타겟은 아니고, Attach 된 깊이 및 스텐실 버퍼 표면 (있는 경우)을 클리어 한다. 이 경우, 깊이 버퍼를 클리어 하면, Direct3D 는 다음에 렌더링 하는 프레임에 렌더링 타겟을 재쓰기 하는 것으로, 렌더링 타겟으로 대하는 명시적인 클리어 처리를 장황하게 한다. 다만, 렌더링 타겟 표면의 일부에게만 렌더링 하는 경우는, 명시적인 클리어 처리가 필요하다.


디퓨즈 반사 모델

[C++]

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

이 공식에서는,Rd 는 디퓨즈 반사 계수,D 는 빛의 방향,N 는 버텍스 법선이다. 벡터 D 는 정규화된다. 벡터 N 는,D3DRENDERSTATE_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) 가 덧셈 된다.

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

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

[Visual Basic]

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

이 공식에서는,Rd 는 디퓨즈 반사 계수,D 의 방향,N 는 버텍스 법선이다. 벡터 D 는 정규화된다. 벡터 N 는,D3DRENDERSTATE_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) 가 덧셈 된다.

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

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


라이트 프로퍼티의 설정

[C++]

C++ 어플리케이션으로 라이트 프로퍼티를 설정하려면 ,D3DLIGHT7 구조체를 준비해, 다음에 IDirect3DDevice7::SetLight 메소드를 호출한다. SetLight 메소드는, 디바이스가 라이트 프로퍼티 세트를 디바이스 내부의 라이트 프로퍼티의 리스트에 배치할 때의 인덱스와 그 라이트 프로퍼티를 정의하는 D3DLIGHT7 구조체의 주소를 받는다. 라이트 프로퍼티의 갱신이 필요한 때는, 새로운 정보로 SetLight 를 호출할 수가 있다.

프로퍼티를 할당할 수 있지 않은 인덱스로 SetLight 메소드를 호출할 때마다, 시스템은 라이트 프로퍼티 세트를 저장하기 위한 메모리를 할당한다. 어플리케이션에서는, 할당할 수 있고 있는 라이트의 서브 세트를 한 번에 유효하게 해, 수많은 라이트를 설정할 수 있다. 디바이스가 지원 하는 액티브한 라이트의 최대수를 결정하기 위해서(때문에) 디바이스 기능을 취득 하면나무는,D3DDEVICEDESC7 구조체의 dwMaxActiveLights 멤버를 체크한다. 특정의 라이트를 사용할 필요가 없어졌을 경우는, 그 라이트를 무효로 하는지, 새로운 라이트 프로퍼티 세트로 덧쓰기할 수가 있다.

다음의 C++ 코드는, 거리의 증가에 의해 감쇠하지 않는, 백색의 포인트 라이트의 프로퍼티를 준비 및 설정한다.

    /*
* 이 예에서는, g_lpd3dDev 변수는, IDirect3DDevice7 인터페이스에의
* 유효한 포인터이다.
     */
    D3DLIGHT7 d3dLight;
    HRESULT   hr;

// 구조체를 초기화한다.
    ZeroMemory(&d3dLight, sizeof(D3DLIGHT7));

// 백색의 포인트 라이트의 설정을 실시한다.
    d3dLight.dltType = D3DLIGHT_POINT;
d3dLight.dcvDiffuse.r = 1.0f;
d3dLight.dcvDiffuse.g = 1.0f;
d3dLight.dcvDiffuse.b = 1.0f;
d3dLight.dcvAmbient.r = 1.0f;
d3dLight.dcvAmbient.g = 1.0f;
d3dLight.dcvAmbient.b = 1.0f;
d3dLight.dcvSpecular.r = 1.0f;
d3dLight.dcvSpecular.g = 1.0f;
d3dLight.dcvSpecular.b = 1.0f;

// 포인트 라이트를 장면의 상부에서 뷰아의 배후에 배치한다.
// (이러한 좌표는 월드 공간의 것이다. 따라서,
//  "뷰아" 는 월드 공간내의 어느 위치 좌표라도 존재할 수 있다.
이 예에서는,
//  뷰아는 월드 공간의 원점에 있다고 한다).
    d3dLight.dvPosition.x = 0.0f;
    d3dLight.dvPosition.y = 1000.0f;
    d3dLight.dvPosition.z = -100. 0f;

// 감쇠시키지 않다.
    d3dLight.dvAttenuation0 = 1.0f;
    d3dLight.dvRange = D3DLIGHT_RANGE_MAX;

// 최초의 라이트의 프로퍼티 정보를 설정한다.
hr = g_lpd3dDev->SetLight(0, d3dLight);
if (FAILED(hr))
    {
// 에러 처리 코드
    }

라이트 프로퍼티 세트는, 재차 SetLight 를 호출해 언제라도 갱신할 수 있다. 갱신하는 라이트 프로퍼티 세트의 인덱스와 새로운 프로퍼티를 포함한 D3DLIGHT7 구조체의 주소를 지정하는 것만으로 있다.

주 : 라이트 프로퍼티 세트를 디바이스에 할당해도, 추가되는 프로퍼티를 가지는 광원이 유효하게 되는 것은 아니다. 광원을 유효하게 하려면 , 디바이스에 대해서 IDirect3DDevice7::LightEnable 메소드를 호출한다.

[Visual Basic]

Visual Basic 어플리케이션으로 라이트 프로퍼티를 설정하려면 ,D3DLIGHT7 형을 준비해, 다음에 Direct3DDevice7.SetLight 메소드를 호출한다. SetLight 메소드는, 디바이스가 라이트 프로퍼티 세트를 디바이스 내부의 라이트 프로퍼티의 리스트에 배치할 때의 인덱스와 그 라이트 프로퍼티를 정의하는 D3DLIGHT7 형의 주소를 받는다. 라이트 프로퍼티의 갱신이 필요한 때는, 새로운 정보로 SetLight 를 호출할 수가 있다.

프로퍼티를 할당할 수 있지 않은 인덱스로 SetLight 메소드를 호출할 때마다, 시스템은 라이트 프로퍼티 세트를 저장하기 위한 메모리를 할당한다. 어플리케이션에서는, 할당할 수 있고 있는 라이트의 서브 세트를 한 번에 유효하게 해, 수많은 라이트를 설정할 수가 있다. 디바이스가 지원 하는 액티브한 라이트의 최대수를 결정하기 위해서(때문에) 디바이스 기능을 취득 하면나무는,D3DDEVICEDESC7 형의 lMaxActiveLights 멤버를 체크한다. 특정의 라이트를 사용할 필요가 없어졌을 경우는, 그 라이트를 무효로 하는지, 새로운 라이트 프로퍼티 세트로 덧쓰기할 수가 있다.

다음의 Visual Basic 코드는, 거리의 증가에 의해 감쇠하지 않는, 백색의 포인트 라이트의 프로퍼티를 준비 및 설정한다.

'
'이 예에서는, d3dDevice 변수에 Direct3DDevice7 오브젝트에의
'유효한 참조가 저장 된다.
'
Dim LightDesc As D3DLIGHT7
Dim c As D3DCOLORVALUE
Dim vPos As D3DVECTOR

'모든 방사광색에 같은 색설정을 사용한다.
With c
. r = 1#:. g = 1#:. b = 1#
. a = 1# '알파 성분은 사용하지 않는다.
End With

With vPos
. x = 0:. y = 1000:. z = -100
End With

With LightDesc
. dltType = D3DLIGHT_POINT
. position = vPos
. Ambient = c:.diffuse = c:.specular = c
. attenuation0 = 1# '빛을 감쇠시키지 않다.
End With

d3dDevice.SetLight 0, LightDesc

라이트 프로퍼티 세트는, 재차 SetLight 를 호출해 언제라도 갱신할 수 있다. 갱신하는 라이트 프로퍼티 세트의 인덱스와 새로운 프로퍼티를 포함한 D3DLIGHT7 형의 주소를 지정하는 것만으로 있다.

주 : 라이트 프로퍼티 세트를 디바이스에 할당해도, 추가되는 프로퍼티를 가지는 광원이 유효하게 되는 것은 아니다. 광원을 유효하게 하려면 , 디바이스에 대해서 Direct3DDevice7.LightEnable 메소드를 호출한다.


스펙큐러 라이트 맵

광원에서 비추었을 때,"미츠를 출발하는" 오브젝트 (반사성의 높은 머트리얼을 사용하는 오브젝트)는 스펙큐러 하이라이트를 받는다. 라이팅 모듈로 생성된 스펙큐러 하이라이트는 정확하지 않은 경우가 있다. 보다 효과적인 하이라이트를 생성하기 위해서, 많은 Direct3D 어플리케이션에서는 원시적으로 스펙큐러 라이트 맵을 적용한다.

스펙큐러 라이트 맵핑을 실행하려면 , 우선 스펙큐러 라이트 맵을 프리미티브의 기존의 텍스쳐에 맞추어 조절한다. 다음에, 흑백 또는 RGB 라이트 맵을 추가한다.

[C++]

다음의 코드는, C++ 에 있어서의 이 처리를 나타낸다.

// 이 예에서는, lpD3DDev 은 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다고 한다.
// lptexBaseTexture 는, 텍스쳐에의 유효한 포인터이다.
// lptexSpecLightMap 는, RGB 스펙큐러 라이트 맵 데이터를 포함한다
// 텍스쳐에의 유효한 포인터이다.
// lptexLightMap 는, RGB 라이트 맵 데이터를 포함한다
// 텍스쳐에의 유효한 포인터이다.

// 베이스 텍스쳐를 설정한다.
lpD3DDev->SetTexture(0, lptexBaseTexture );

// 베이스 텍스쳐 처리와 인수를 설정한다.
lpD3DDev->SetTextureStageState(0, D3DTSS_COLOROP,
       D3DTOP_MODULATE );
lpD3DDev->SetTextureStageState(0, D3DTSS_COLORARG1, D3DTA_TEXTURE );
lpD3DDev->SetTextureStageState(0, D3DTSS_COLORARG2, D3DTA_DIFFUSE );

// 스펙큐러 라이트 맵을 설정한다.
lpD3DDev->SetTexture(1, lptexSpecLightMap );

// 스펙큐러 라이트 맵과 인수를 설정한다.
lpD3DDev->SetTextureStageState(1, D3DTSS_COLOROP,
       D3DTOP_ADD );
lpD3DDev->SetTextureStageState(1, D3DTSS_COLORARG1, D3DTA_TEXTURE );
lpD3DDev->SetTextureStageState(1, D3DTSS_COLORARG2, D3DTA_CURRENT );

// RGB 라이트 맵을 설정한다.
lpD3DDev->SetTexture(2, lptexLightMap);

// RGB 라이트 맵 처리와 인수를 설정한다.
lpD3DDev->SetTextureStageState(2, D3DTSS_COLOROP, D3DTOP_MODULATE);
lpD3DDev->SetTextureStageState(2, D3DTSS_COLORARG1, D3DTA_TEXTURE );
lpD3DDev->SetTextureStageState(2, D3DTSS_COLORARG2, D3DTA_CURRENT );
[Visual Basic]

다음의 Visual Basic 코드는, 이 처리를 나타낸다.

'이 예에서는, d3dDev 는 Direct3DDevice7 오브젝트에의
'유효한 참조이다고 한다.
' texBaseTexture 는 텍스쳐에의 유효한 참조이다.
' texSpecLightMap 는, RGB 스펙큐러 라이트 맵 데이터를 포함한다
'텍스쳐에의 유효한 참조이다.
' texLightMap 는, RGB 라이트 맵 데이터를 포함한다
'텍스쳐에의 유효한 참조이다.

'베이스 텍스쳐를 설정한다.
Call d3dDev.SetTexture(0, texBaseTexture)

'베이스 텍스쳐 처리와 인수를 설정한다.
Call d3dDev.SetTextureStageState(0, D3DTSS_COLOROP, _
D3DTOP_MODULATE );
Call d3dDev.SetTextureStageState(0, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call d3dDev.SetTextureStageState(0, D3DTSS_COLORARG2, D3DTA_DIFFUSE)

'스펙큐러 라이트 맵을 설정한다.
Call d3dDev.SetTexture(1, texSpecLightMap)

'스펙큐러 라이트 맵 처리와 인수를 설정한다.
Call d3dDev.SetTextureStageState(1, D3DTSS_COLOROP, _
D3DTOP_ADD)
Call d3dDev.SetTextureStageState(1, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call d3dDev.SetTextureStageState(1, D3DTSS_COLORARG2, D3DTA_CURRENT)

' RGB 라이트 맵을 설정한다.
Call d3dDev.SetTexture(2, texLightMap)

' RGB 라이트 맵 처리와 인수를 설정한다.
Call d3dDev.SetTextureStageState(2, D3DTSS_COLOROP, D3DTOP_MODULATE)
Call d3dDev.SetTextureStageState(2, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call d3dDev.SetTextureStageState(2, D3DTSS_COLORARG2, D3DTA_CURRENT)


장면의 시작과 종료

[C++]

C++ 로 기술된 어플리케이션에서는,IDirect3DDevice7::BeginScene 메소드를 호출해, Direct3D 에 장면의 렌더링의 시작을 알린다. BeginScene 의 명령을 받은 시스템은, 내부 데이터 구조 및 렌더링 하는 표면의 가용성과 타당성을 체크해, 장면이 처리중인 것을 알리는 내부 플래그를 설정한다. 장면의 시작 후는, 다양한 렌더링 메소드를 호출해 프리미티브를 렌더링 하거나 장면의 오브젝트를 구성하는 버텍스를 개별적으로 렌더링 할 수가 있다. 장면의 처리중이 아닐 때에 렌더링 메소드를 호출하려고 하면 실패해,D3DERR_SCENE_NOT_IN_SCENE 가 돌려주어진다. 상세한 것에 대하여는, 「프리미티브의 렌더링」을 참조할것.

장면이 완료하면(자),IDirect3DDevice7::EndScene 메소드를 호출한다. EndScene 메소드는, 장면의 처리중인 것을 알리는 내부 플래그를 클리어 해, 캐쉬되고 있던 데이터를 플래시 해, 렌더링 표면의 정합성을 검증한다.

렌더링 메소드는 모두,BeginScene 메소드를 호출하고 나서 EndScene 메소드를 호출할 때까지 에 실행해야 한다. 표면이 없어지는지, 또는 내부 에러가 발생 하면, 장면의 메소드는 에러값을 돌려준다. BeginScene 메소드가 실패했을 경우, 장면은 시작 되지 않고, 거기에 계속되는 EndScene 의 호출도 실패한다. 렌더링중에 표면이 없어졌을 경우는,EndScene 가 DDERR_SURFACELOST 를 돌려준다. BeginScene 를 호출하기 전에 표면이 정상적으로 복원되지 않았던 경우,BeginScene 도 DDERR_SURFACELOST 를 돌려준다.

이러한 케이스를 이하에 정리한다.

  • BeginScene 가 어떠한 에러를 돌려주었을 경우, 장면은 정상적으로 시작되어 있지 않기 때문에,EndScene 를 호출해서는 안 된다.
  • BeginScene 는 성공했지만 장면의 렌더링중에 에러가 발생했을 경우는,EndScene 를 호출할 필요가 있다.
  • 어떠한 이유로써 EndScene 가 실패했을 경우는, 이것을 재차 호출할 필요는 없다.

예를 들어, 단순한 장면을 처리하는 코드는 다음과 같이 된다.

HRESULT hr;

if(SUCCEEDED(lpDevice->BeginScene()))
{
// 장면의 시작에 성공했을 경우만,
// 프리미티브를 렌더링 한다.

// 장면을 닫는다.
    hr = lpDevice->EndScene();
    if(FAILED(hr))
        return hr;
}

장면을 묻을 수 없다. 즉, 다음의 장면을 렌더링 하려면 , 현재 렌더링중의 장면을 완료할 필요가 있다. IDirect3DDevice7::BeginScene 가 불려 가지 않았는데 IDirect3DDevice7::EndScene 를 호출했을 경우,D3DERR_SCENE_NOT_IN_SCENE 에러가 돌려주어진다. 같이 전의 장면이 EndScene 메소드로 아직 완료하고 있지 않을 때에 BeginScene 를 호출하면,D3DERR_SCENE_IN_SCENE 에러가 발생한다.

장면의 렌더링중 (BeginScene 를 호출하고 나서 EndScene 를 호출할 때까지 ), 렌더링 타겟이나 텍스쳐등의 DirectDraw 표면에 대해서 GDI 함수를 호출해서는 안 된다. 이 함수를 호출하려고 하면, GDI 조작의 결과가 표시되지 않게 될 가능성이 있다. 어플리케이션으로 GDI 함수를 사용하는 경우는, 장면 함수의 밖에서 모든 GDI 의 호출을 실시하도록(듯이) 한다.

[Visual Basic]

Visual Basic 어플리케이션에서는,Direct3DDevice7.BeginScene 메소드를 호출해, Direct3D 에 장면의 렌더링의 시작을 알린다. BeginScene 의 명령을 받은 시스템은, 내부 데이터 구조, 렌더링 하는 표면의 가용성과 타당성을 체크해, 장면이 처리중인 것을 알리는 내부 플래그를 설정한다. 장면의 시작 후는, 다양한 렌더링 메소드를 호출해 프리미티브를 렌더링 하거나 장면의 오브젝트를 구성하는 버텍스를 개별적으로 렌더링 할 수가 있다. 장면의 처리중이 아닐 때에 렌더링 메소드를 호출하려고 하면 실패해,D3DERR_SCENE_NOT_IN_SCENE 가 돌려주어진다. 상세한 것에 대하여는, 「프리미티브의 렌더링」을 참조할것.

장면이 완료하면(자),Direct3DDevice7.EndScene 메소드를 호출한다. EndScene 메소드는, 장면의 처리중인 것을 알리는 내부 플래그를 클리어 해, 캐쉬되고 있던 데이터를 플래시 해, 렌더링 표면의 정합성을 검증한다.

렌더링 메소드는 모두,BeginScene 메소드를 호출하고 나서 EndScene 메소드를 호출할 때까지 에 실행해야 한다. 표면이 없어지는지, 또는 내부 에러가 발생했을 경우는, 장면의 메소드가 실패해,Err.Number 에 에러 코드가 설정된다. BeginScene 가 실패했을 경우, 장면은 시작 되지 않고, 거기에 계속되는 EndScene 의 호출도 실패한다. 렌더링중에 표면이 없어졌을 경우는,EndScene 가 실패해,DDERR_SURFACELOST 에러가 발생한다. BeginScene 를 호출하기 전에 표면이 정상적으로 복원되지 않았던 경우,BeginScene 도 DDERR_SURFACELOST 를 돌려준다.

이러한 케이스를 이하에 정리한다.

  • BeginScene 가 어떠한 에러를 돌려주었을 경우, 장면은 정상적으로 시작되어 있지 않기 때문에,EndScene 를 호출해서는 안 된다.
  • BeginScene 는 성공했지만 장면의 렌더링중에 에러가 발생했을 경우,EndScene 를 호출할 필요가 있다.
  • 어떠한 이유로써 EndScene 가 실패했을 경우는, 이것을 재차 호출할 필요는 없다.

예를 들어, 단순한 장면을 처리하는 코드는 다음과 같이 된다.

On Local Error Resume Next

Call d3dDev.BeginScene
If Err.Number = DD_OK Then
'장면의 시작에 성공했을 경우만,
'프리미티브를 렌더링 한다.

'장면을 닫는다.
Call d3dDev.EndScene
If Err.Number <> DD_OK Then
'에러 처리 코드
End If
End If

장면을 묻을 수 없다. 즉, 다음의 장면을 렌더링 하려면 , 현재 렌더링중의 장면을 완료할 필요가 있다. Direct3DDevice7.BeginScene 가 불려 가지 않을 때에 Direct3DDevice7.EndScene 를 호출했을 경우,D3DERR_SCENE_NOT_IN_SCENE 에러가 발생한다. 같이 전의 장면이 EndScene 메소드로 아직 완료하고 있지 않을 때에 BeginScene 를 호출하면,D3DERR_SCENE_IN_SCENE 에러가 발생한다.

장면의 렌더링중 (BeginScene 를 호출하고 나서 EndScene 를 호출할 때까지 ), 렌더링 타겟이나 텍스쳐등의 DirectDraw 표면에 대해서 GDI 함수를 호출해서는 안 된다. 이 함수를 호출하려고 하면, GDI 조작의 결과가 표시되지 않게 될 가능성이 있다. 어플리케이션으로 GDI 함수를 사용하는 경우는, 장면 함수의 밖에서 모든 GDI 의 호출을 실시하도록(듯이) 한다.


구(공)체 환경 맵의 적용

[C++]

환경 맵을 오브젝트에 적용 하면나무는, 그 외의 텍스쳐의 경우와 같이,IDirect3DDevice7::SetTexture 메소드로 적절한 텍스쳐 스테이지에 텍스쳐를 설정한다. 제 1 파라미터에는, 희망의 텍스쳐 스테이지의 인덱스를 설정해, 제 2 파라미터에는, 환경 맵의 텍스쳐의 생성시에 돌려주어진 IDirectDrawSurface7 인터페이스의 주소를 설정한다. 필요에 따라서 색 및 알파 블렌딩 처리와 인수를 설정해, 희망의 텍스쳐 블렌딩 이펙트를 얻을 수 있다.

[Visual Basic]

환경 맵을 오브젝트에 적용 하면나무는, 그 외의 텍스쳐의 경우와 같이,Direct3DDevice7.SetTexture 메소드로 적절한 텍스쳐 스테이지에 텍스쳐를 설정한다. 제 1 파라미터에는, 희망의 텍스쳐 스테이지의 인덱스를 설정해, 제 2 파라미터에는, 환경 맵의 텍스쳐의 생성시에 돌려주어진 DirectDrawSurface7 인터페이스의 주소를 설정한다. 필요에 따라서 색 및 알파 블렌딩 처리와 인수를 설정해, 희망의 텍스쳐 블렌딩 이펙트를 얻을 수 있다.


아우트라인 및 전부 칠해 스테이트

[C++]

텍스쳐가 적용되지 않은 프리미티브는, 머트리얼에 의해 지정되는 색, 또는 버텍스로 지정된 색이 있으면, 그 어느쪽이든으로 렌더링 된다. 프리미티브를 전부 칠하는 방법은,D3DFILLMODE 열거형으로 선택할 수 있다. 「D3DRENDERSTATE_FILLMODE 」를 참조할것.

어플리케이션으로 디저링을 유효하게 하려면 , 제 1 파라미터로서 D3DRENDERSTATE_DITHERENABLE 열거값을 IDirect3DDevice7::SetRenderState 에 건네줄 필요가 있다. 디저링을 유효하게 하려면 제 2 파라미터를 TRUE 로 설정해, 무효로 하려면 FALSE 로 설정한다.

선의 마지막 픽셀을 드로잉(Drawing) 하면 주위의 프리미티브와 겹쳐, 외형이 나빠지는 일이 있다. 이것은,D3DRENDERSTATE_LASTPIXEL 열거값을 사용해 제어할 수 있다. 다만, 이 설정을 변경 하면나무는 주의가 필요하다. 경우에 따라서는, 마지막 픽셀을 드로잉(Drawing) 하지 않게 하면 프리미티브간에 틈새가 생겨 보기 흉해지는 일이 있다.

디폴트에서는, Direct3D 디바이스는 원시적으로 실선의 아우트라인을 사용한다. 아우트라인 패턴은,D3DLINEPATTERN 구조체를 사용해 변경할 수 있다. 「D3DRENDERSTATE_LINEPATTERN 」를 참조할것.

주 : 종래의 렌더링 스테이트 D3DRENDERSTATE_ROP2, D3DRENDERSTATE_STIPPLEENABLE, 및 D3DRENDERSTATE_STIPPLEPATTERN00 ~ D3DRENDERSTATE_STIPPLEPATTERN31 는, DirectX 7.0 릴리스에서는 사용되지 않는다.

[Visual Basic]

텍스쳐가 적용되지 않은 프리미티브는, 머트리얼에 의해 지정되는 색, 또는 버텍스로 지정된 색이 있으면, 그 어느쪽이든으로 렌더링 된다. 프리미티브를 전부 칠하는 방법은,CONST_D3DFILLMODE 열거형으로 선택할 수 있다. 「D3DRENDERSTATE_FILLMODE 」를 참조할것.

어플리케이션으로 디저링을 유효하게 하려면 , 제 1 파라미터로서 D3DRENDERSTATE_DITHERENABLE 열거값을 Direct3DDevice7::SetRenderState 에 건네줄 필요가 있다. 디저링을 유효하게 하려면 제 2 파라미터를 True 로 설정해, 무효로 하려면 False 로 설정한다.

선의 마지막 픽셀을 드로잉(Drawing) 하면 주위의 프리미티브와 겹쳐, 외형이 나빠지는 일이 있다. 이것은,D3DRENDERSTATE_LASTPIXEL 열거값을 사용해 제어할 수 있다. 다만, 이 설정을 변경 하면나무는 주의가 필요하다. 경우에 따라서는, 마지막 픽셀을 드로잉(Drawing) 하지 않게 하면 프리미티브간에 틈새가 생겨 보기 흉해지는 일이 있다.

DirectX for Visual Basic 에서는,D3DRENDERSTATE_LINEPATTERN 렌더링 스테이트는 지원 하고 있지 않다.


스테이트 블록의 기록

[C++]

IDirect3DDevice7 인터페이스에는, 어플리케이션으로부터 디바이스 스테이트의 요구가 있었을 때에 그 디바이스 스테이트를 스테이트 블록에 기록하는 IDirect3DDevice7::BeginStateBlock 메소드가 있다. BeginStateBlock 메소드는, 디바이스 스테이트의 변경을 디바이스에 적용하는 것이 아니라, 디바이스 스테이트의 변경을 스테이트 블록에 기록하기 시작한다. BeginStateBlock 를 호출한 후, 이하의 모든 메소드의 호출이 디바이스 스테이트 블록에 기록된다.

  • IDirect3DDevice7::LightEnable
  • IDirect3DDevice7::SetClipPlane
  • IDirect3DDevice7::SetLight
  • IDirect3DDevice7::SetMaterial
  • IDirect3DDevice7::SetRenderState
  • IDirect3DDevice7::SetTexture
  • IDirect3DDevice7::SetTextureStageState
  • IDirect3DDevice7::SetTransform
  • IDirect3DDevice7::SetViewport

스테이트 블록의 기록이 종료하면(자),IDirect3DDevice7::EndStateBlock 메소드를 호출해 기록의 정지를 시스템에 알린다. EndStateBlock 메소드는, 기록한 스테이트 블록의 핸들을 변수에 저장 한다. 이 변수의 주소는 lpdwBlockHandle 파라미터에 건네준다. 어플리케이션에서는, 이 핸들을 사용해, 필요에 따라서 스테이트 블록을 디바이스에 적용하거나 새로운 스테이트 데이터를 블록에 기록하거나 불필요하게 된 스테이트 블록을 삭제할 수가 있다.

[Visual Basic]

Direct3DDevice7 오브젝트에는, 어플리케이션으로부터 디바이스 스테이트의 요구가 있었을 때에 그 디바이스 스테이트를 스테이트 블록에 기록하는 Direct3DDevice7.BeginStateBlock 메소드가 있다. BeginStateBlock 메소드는, 디바이스 스테이트의 변경을 디바이스에 적용하는 것이 아니라, 디바이스 스테이트의 변경을 스테이트 블록에 기록하기 시작한다. BeginStateBlock 를 호출한 후, 이하의 모든 메소드의 호출이 디바이스 스테이트 블록에 기록된다.

  • Direct3DDevice7.LightEnable
  • Direct3DDevice7.SetClipPlane
  • Direct3DDevice7.SetLight
  • Direct3DDevice7.SetMaterial
  • Direct3DDevice7.SetRenderState
  • Direct3DDevice7.SetTexture
  • Direct3DDevice7.SetTextureStageState
  • Direct3DDevice7.SetTransform
  • Direct3DDevice7.SetViewport

스테이트 블록의 기록이 종료하면(자),Direct3DDevice7.EndStateBlock 메소드를 호출해 기록의 정지를 시스템에 알린다. EndStateBlock 메소드는, 기록한 스테이트 블록의 핸들을,blockHandle 파라미터에 건네주는 변수에 저장 한다. 어플리케이션에서는, 이 핸들을 사용해, 필요에 따라서 스테이트 블록을 디바이스에 적용하거나 새로운 스테이트 데이터를 블록에 기록하거나 불필요하게 된 스테이트 블록을 삭제할 수가 있다.

퍼포먼스에 관한 주의 : 최선의 결과를 얻기 위해서(때문에)는,BeginStateBlock/EndStateBlock 의 페어간에서의 모든 스테이트 변경을 그룹화 한다.

EndStateBlock 메소드가 돌려주는 에러 코드를 체크하는 것이 중요하다. 이 메소드가 실패했을 경우, 그 원인의 상당수는 디스플레이 모드가 변경된 것이다고 생각된다 (에러 코드 DDERR_SURFACELOST). 어플리케이션의 표면을 생성 다시 해 , 재차 스테이트 블록을 기록하는 것으로, 이러한 장해로부터 어플리케이션이 회복하도록(듯이) 설계한다.


spotlight

spotlight는, 색, 위치 좌표, 및 빛을 방사할 방향을 가진다. spotlight로부터 방사되는 빛은, C++ 의 D3DLIGHT7 구조체 (Visual Basic 에서는 D3DLIGHT7 형)의 관련 멤버에 가세해, 밝은 내부 콘과 이것보다 큰 외부 콘으로 구성된다. 다음의 그림에 나타내도록(듯이), 빛의 강도는 2 개의 콘간에 감소한다.

spotlight는, 폴 오프, 감쇠, 및 범위의 영향을 받는다. 이러한 요인은, 빛이 각 버텍스까지 진행되는 거리와 같이, 장면내의 오브젝트에의 라이팅 이펙트를 계산할 경우에 고려에 넣는다. 각 버텍스에 대한 이러한 이펙트를 모두 계산하는 경우, Direct3D 직접 모드의 모든 라이트중에서 컴퓨터에의 부하가 가장 큰 것은 spotlight이다.


라이트의 위치 좌표, 범위, 및 감쇠

[C++]

위치 좌표, 범위, 및 감쇠 프로퍼티는,월드 공간에서의 라이트의 위치 좌표, 및 라이트가 방사하는 빛이 거리의 증가에 수반해 어떻게 변화하는지를 정의한다. C++ 로 사용하는 모든 라이트 프로퍼티와 같이, 이러한 프로퍼티는 라이트의 D3DLIGHT7 구조체에 포함된다.

위치 좌표

라이트의 위치 좌표는,D3DLIGHT7 구조체의 dvPosition 멤버에 D3DVECTOR 구조체를 사용해 지정한다. x, y, z 좌표는 월드 공간에 있으면(자) 가정한다. 디렉셔널 라이트는, 위치 좌표 프로퍼티를 사용하지 않는 유일한 라이트이다.

범위

라이트의 범위 프로퍼티는, 오브젝트가 방사한 빛을 장면내의 메쉬가 납득할 수 없게 될 때까지의, 월드 공간에서의 거리를 결정한다. dvRange 멤버에는, 월드 공간에서의 라이트의 최대 범위를 나타내는 부동 소수점값이 포함된다. 대부분의 어플리케이션에서는, 이 범위를 D3d.h 에 정의되고 있는 최대치 D3DLIGHT_RANGE_MAX 로 설정한다. 디렉셔널 라이트에서는 범위 프로퍼티는 사용하지 않는다.

감쇠

감쇠는, 범위 프로퍼티로 지정한 최대 거리에 가까워지는 것에 따라 라이트의 강도가 어떻게 감소하는지를 제어한다. 라이트의 감쇠는, 3 개의 D3DLIGHT7 구조체의 dvAttenuation0,dvAttenuation1, 및 dvAttenuation2 멤버로 나타낸다. 이러한 멤버에는, 라이트의 감쇠를 제어하는 0.0 ~무한대의 부동 소수점값이 포함된다. 어플리케이션에 따라서는,dvAttenuation1 멤버를 1.0 으로 설정해, 그 외의 멤버를 0.0 으로 설정하는 것으로, 라이트의 강도가 1 / D 로서 변화하도록(듯이) 한다. 여기서,D 는 광원으로부터 버텍스까지의 거리이다. 광원에서는 라이트의 강도가 최대로, 거기로부터 멀어지는에 따라 1 / (라이트의 범위)에 감소한다. 보통, 어플리케이션에서는 dvAttenuation0 를 0.0 으로 설정해,dvAttenuation1 를 정수로 설정해,dvAttenuation2 를 0.0 으로 설정한다.

감쇠값을 조합해, 보다 복잡한 감쇠 이펙트를 낼 수가 있다. 또, 감쇠값을 보통의 범위외의 값으로 설정해, 한층 더 드문 감쇠 이펙트를 낼 수가 있다. 예를 들어, 부의 감쇠값을 설정 하면, 거리가 증가하는에 따라 라이트가 밝아진다.

Direct3D 로 감쇠의 계산에 사용하는 수학 모델의 상세한 것에 대하여는, 「거리의 증가에 의한 라이트의 감쇠」를 참조할것. 범위 프로퍼티와 같이, 디렉셔널 라이트에서는 감쇠 프로퍼티는 사용하지 않는다.

[Visual Basic]

D3DLIGHT7 형에는, Visual Basic 어플리케이션으로 라이트의 위치 좌표, 범위, 및 감쇠 프로퍼티를 정의하기 위해서 사용하는 멤버가 포함된다. 이러한 프로퍼티는,월드 공간에서의 라이트의 위치 좌표와 라이트가 방사하는 빛이 거리의 증가에 수반해 어떻게 변화하는지를 정의한다.

위치 좌표

라이트의 위치 좌표는,D3DLIGHT7 형의 position 멤버에 D3DVECTOR 형을 사용해 기술한다. x, y, z 좌표는 월드 공간에 있으면(자) 가정한다. 디렉셔널 라이트는, 위치 좌표 프로퍼티를 사용하지 않는 유일한 라이트이다.

범위

라이트의 범위 프로퍼티는, 오브젝트가 방사한 빛을 장면내의 메쉬가 납득할 수 없게 될 때까지의, 월드 공간에서의 거리를 결정한다. range 멤버에는, 월드 공간에서의 라이트의 최대 범위를 나타내는 부동 소수점값이 포함된다. 대부분의 어플리케이션에서는, 이 범위를 최대치 (18.446+e18)로 설정한다. 디렉셔널 라이트에서는 범위 프로퍼티는 사용하지 않는다.

감쇠

감쇠는, 범위 프로퍼티로 지정한 최대 거리에 가까워지는 것에 따라 라이트의 강도가 어떻게 감소하는지를 제어한다. 라이트의 감쇠는, 3 개의 D3DLIGHT7 멤버 attenuation0,attenuation1, 및 attenuation2 로 나타낸다. 이러한 멤버에는, 라이트의 감쇠를 제어하는 0.0 ~무한대의 부동 소수점값이 포함된다. 어플리케이션에 따라서는,attenuation1 멤버를 1.0 으로 설정해, 그 외의 멤버를 0.0 으로 설정하는 것으로, 라이트의 강도가 1 / D 로서 변화하도록(듯이) 한다. 여기서,D 는 광원으로부터 버텍스까지의 거리이다. 광원에서는 라이트의 강도가 최대로, 거기로부터 멀어지는에 따라 1 / (라이트의 범위)에 감소한다. 보통, 어플리케이션에서는 dvAttenuation0 를 0.0 으로 설정해,dvAttenuation1 를 정수로 설정해,dvAttenuation2 를 0.0 으로 설정한다.

감쇠값을 조합해, 보다 복잡한 감쇠 이펙트를 낼 수가 있다. 또, 감쇠값을 보통의 범위외의 값으로 설정해, 한층 더 드문 감쇠 이펙트를 낼 수가 있다. 예를 들어, 부의 감쇠값을 설정 하면, 거리가 증가하는에 따라 라이트가 밝아진다.

Direct3D 로 감쇠의 계산에 사용하는 수학 모델의 상세한 것에 대하여는, 「거리의 증가에 의한 라이트의 감쇠」를 참조할것. 범위 프로퍼티와 같이, 디렉셔널 라이트에서는 감쇠 프로퍼티는 사용하지 않는다.


범위의 갱신 스테이트

[C++]

Direct3D 에서는, 뷰포트 범위를 갱신하는 것으로, 렌더링 메소드에 의한 영향을 뷰포트 영역에 반영할 수가 있다. C++ 로 기술된 어플리케이션에서는, 시스템에 의해 실행되는 범위의 갱신을 D3DRENDERSTATE_EXTENTS 렌더링 스테이트를 사용해 제어한다. 이 스테이트의 디폴트 설정은 FALSE 로, 범위의 갱신은 무효이다. 어플리케이션으로 IDirect3DDevice7::GetClipStatus 및 IDirect3DDevice7::SetClipStatus 메소드를 사용해 뷰포트 범위를 조작하는 경우는,D3DRENDERSTATE_EXTENTS 를 TRUE 로 설정하는 것으로 범위의 갱신을 유효하게 할 수 있다.

범위의 갱신 렌더링 스테이트는, 버텍스 버퍼로 가능한 범위의 갱신 처리에는 전혀 의존하지 않는다. IDirect3DVertexBuffer7::ProcessVertices 및 IDirect3DVertexBuffer7::ProcessVerticesStrided 메소드는, 버텍스 처리 시에 범위의 갱신 처리를 제어하는, 독자적인 플래그를 받는다.

주 : 이 렌더링 스테이트는, 반대이지만 종래의 렌더링 메소드로 사용된 D3DDP_DONOTUPDATEEXTENTS 플래그 와 유사한다. DirectX 7.0 에서는, 이 렌더링 스테이트가 D3DDP_DONOTUPDATEEXTENTS 플래그에 옮겨지고 있다. D3DDP_DONOTUPDATEEXTENTS 플래그로 1 회가 호출할 것에 범위의 갱신을 무효로 하는 경우, 스테이트값이 어플리케이션에 의해 재차 변경될 때까지는, 렌더링에 관한 모든 호출이 이 렌더링 스테이트의 영향을 받는다.

[Visual Basic]

Direct3D 에서는, 뷰포트 범위를 갱신하는 것으로, 렌더링 메소드에 의한 영향을 뷰포트 영역에 반영할 수가 있다. Visual Basic 어플리케이션에서는, 시스템에 의해 실행되는 범위의 갱신을 D3DRENDERSTATE_EXTENTS 렌더링 스테이트를 사용해 제어할 수 있다. 이 스테이트의 디폴트 설정은 False 로, 범위의 갱신은 무효이다. 어플리케이션으로 Direct3DDevice7.GetClipStatus 및 Direct3DDevice7.SetClipStatus 메소드를 사용해 뷰포트 범위를 조작하는 경우는,D3DRENDERSTATE_EXTENTS 를 True 로 설정하는 것으로 범위의 갱신을 유효하게 할 수 있다.

범위의 갱신 렌더링 스테이트는, 버텍스 버퍼내에서 가능한 범위의 갱신 처리에는 전혀 의존하지 않는다. Direct3DVertexBuffer7.ProcessVertices 메소드는, 버텍스 처리 시에 범위의 갱신 처리를 제어하는, 독자적인 플래그를 받는다.


flat shading

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

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


현재 텍스쳐의 할당

Direct3D 에서는, 최대 8 개(살)까지의 현재 텍스쳐의 리스트를 이용할 수 있다. Direct3D 에서는, 렌더링 하는 모든 원시적으로, 이러한 텍스쳐를 블렌드 한다. 텍스쳐 인터페이스 포인터로서 생성 한 텍스쳐만, 현재 텍스쳐 세트로 사용할 수 있다.

[C++]

어플리케이션에서는,IDirect3DDevice7::SetTexture 메소드를 호출해 현재 텍스쳐 세트에 텍스쳐를 할당한다. 제 1 파라미터는, 0 ~ 7 의 범위의 수치가 아니면 안된다. 제 2 파라미터로서 텍스쳐 인터페이스 포인터를 건네준다.

다음의 C++ 코드는, 텍스쳐를 현재 텍스쳐 세트에 할당하는 방법을 나타낸다.

// 이 코드에서는, 변수 lpd3dDev 이 IDirect3DDevice7 인터페이스에의 유효한 포인터로,
// 변수 lpd3dTexture 가 IDirectDrawSurface7 인터페이스에의
// 유효한 포인터이다고 한다.

// 3 번째의 텍스쳐를 설정한다.
lpd3dDev->SetTexture(2, lpd3dTexture);
[Visual Basic]

Visual Basic 로 기술된 어플리케이션에서는,Direct3DDevice7.SetTexture 를 호출해 현재 텍스쳐 세트에 텍스쳐를 할당한다. 제 1 파라미터는, 0 ~ 7 의 범위의 수치가 아니면 안된다. 제 2 파라미터로서 텍스쳐 인터페이스 포인터를 건네준다.

다음의 Visual Basic 코드는, 텍스쳐를 현재 텍스쳐 세트에 할당하는 방법을 나타낸다.

'이 코드에서는, 변수 d3dDev 가 Direct3DDevice7 오브젝트에의 유효한 참조로,
' d3dTexture 가 DirectDrawSurface7 오브젝트에의
'유효한 참조이다고 한다.

' 3 번째의 텍스쳐를 설정한다.
Call d3dDev.SetTexture(2, d3dTexture)

소프트웨어 디바이스에서는, 텍스쳐를 한 번에 복수의 텍스쳐 스테이지에 할당할 수 없다.


프리미티브의 렌더링

이하의 주제에서는, DrawPrimitive 렌더링 메소드에 대해, 및 이 메소드의 어플리케이션에서의 사용 방법에 대해 설명한다.

  • DrawPrimitive 메소드
  • 보폭 버텍스의 렌더링


머트리얼 프로퍼티의 설정

Direct3D 렌더링 디바이스에서는, 한 번에 1 개의 머트리얼 프로퍼티세트로 렌더링 할 수 있다.

[C++]

C++ 어플리케이션의 경우, 시스템으로 사용하는 머트리얼 프로퍼티를 설정하려면 ,D3DMATERIAL7 구조체를 준비해, 다음에 IDirect3DDevice7::SetMaterial 메소드를 호출한다.

D3DMATERIAL7 구조체를 준비하려면 , 이 구조체에 프로퍼티 정보를 설정해, 렌더링에서의 희망의 이펙트를 생성 한다. 다음의 코드는, 백색의 스펙큐러 하이라이트가 있는, 보라색의 머트리얼용의 D3DMATERIAL7 구조체를 설정한다.

    D3DMATERIAL7 mat;

// 디퓨즈 반사를 나타내는 RGBA 를 설정한다.
    mat.dcvDiffuse.r = (D3DVALUE) 0.5;
    mat.dcvDiffuse.g = (D3DVALUE) 0.0;
    mat.dcvDiffuse.b = (D3DVALUE) 0.5;
    mat.dcvDiffuse.a = (D3DVALUE) 1.0;

// 앰비언트 반사를 나타내는 RGBA 를 설정한다.
    mat.dcvAmbient.r = (D3DVALUE) 0.5;
    mat.dcvAmbient.g = (D3DVALUE) 0.0;
    mat.dcvAmbient.b = (D3DVALUE) 0.5;
    mat.dcvAmbient.a = (D3DVALUE) 1.0;

// 스펙큐러 하이라이트의 색과 샤프함을 설정한다.
    mat.dcvSpecular.r = (D3DVALUE) 1.0;
    mat.dcvSpecular.g = (D3DVALUE) 1.0;
    mat.dcvSpecular.b = (D3DVALUE) 1.0;
    mat.dcvSpecular.a = (D3DVALUE) 1.0;
    mat.dvPower = (float) 50.0;

D3DMATERIAL7 구조체를 준비하면(자), 렌더링 디바이스의 IDirect3DDevice7::SetMaterial 메소드를 호출해 이 구조체를 적용한다. 이 메소드에는, 준비한 D3DMATERIAL7 구조체의 주소를 유일한 파라미터로서 지정한다. 디바이스의 머트리얼 프로퍼티의 갱신이 필요한 때는, 새로운 정보로 SetMaterial 를 호출할 수가 있다. 다음의 예는, 이상의 처리를 코드로 가리킨다.

// 이 코드에서는, 이 주제의 전의 예로 mat 변수에 대해서 정의했다
// 머트리얼 프로퍼티를 사용한다. lpd3dDev 은, IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다.
HRESULT hr;
hr = lpd3dDev->SetMaterial(&mat);
if(FAILED(hr))
    {
// 에러 처리 코드
    }
[Visual Basic]

Visual Basic 의 경우, 시스템으로 사용하는 머트리얼 프로퍼티를 설정하려면 ,D3DMATERIAL7 형을 준비해, 다음에 Direct3DDevice7.SetMaterial 메소드를 호출한다.

D3DMATERIAL7 형을 준비하려면 , 이 형태에 프로퍼티 정보를 설정해, 렌더링에서의 희망의 이펙트를 생성 한다. 다음의 코드는, 백색의 스펙큐러 하이라이트가 있는, 보라색의 머트리얼용의 D3DMATERIAL7 형을 설정한다.

Dim mat As D3DMATERIAL7

'디퓨즈 반사를 나타내는 RGBA 를 설정한다.
mat.diffuse.r = 0.5
mat.diffuse.g = 0#
mat.diffuse.b = 0.5
mat.diffuse.a = 1#

'앰비언트 반사를 나타내는 RGBA 를 설정한다.
mat.ambient.r = 0.5
mat.ambient.g = 0#
mat.ambient.b = 0.5
mat.ambient.a = 1#

'스펙큐러 하이라이트의 색과 샤프함을 설정한다.
mat.specular.r = 1#
mat.specular.g = 1#
mat.specular.b = 1#
mat.specular.a = 1#
mat.power = 50#

D3DMATERIAL7 형을 준비하면(자), 렌더링 디바이스의 Direct3DDevice7.SetMaterial 메소드를 호출해 이 구조체를 적용한다. 이 메소드에는, 준비한 D3DMATERIAL7 형의 주소를 유일한 파라미터로서 지정한다. 디바이스의 머트리얼 프로퍼티의 갱신이 필요한 때는, 새로운 정보로 SetMaterial 를 호출할 수가 있다. 다음의 예는, 이상의 처리를 코드로 가리킨다.

'이 코드에서는, 이 주제의 전의 예로 mat 변수에 대해서 정의했다
'머트리얼 프로퍼티를 사용한다. d3dDev 에는, Direct3DDevice7 오브젝트에의
'유효한 참조가 저장 되고 있다고 한다.
On Local Error Resume Next

Call d3dDev.SetMaterial(mat)
If Err.Number <> DD_OK Then
'에러 처리 코드
End If


알파 블렌딩 스테이트

색의 알파값은 투명도를 제어한다. 알파 블렌딩을 유효하게 하면, 어느 표면의 색, 머트리얼, 및 텍스쳐를 투명도와 블렌드 해, 다른 표면에 적용할 수 있다. 상세한 것에 대하여는, 「알파 텍스쳐 블렌딩」 및 「멀티 패스 텍스쳐 블렌딩」을 참조할것.

[C++]

C++ 로 기술된 어플리케이션에서는,D3DRENDERSTATE_ALPHABLENDENABLE 렌더링 스테이트를 사용해 알파 투명 블렌딩을 유효하게 한다. Direct3D API 에서는, 다양한 종류의 알파 블렌딩을 사용할 수 있다. 다만, 유저의 3D 하드웨어가 Direct3D 로 가능한 블렌딩 스테이트의 모두에게 대응 하면은 한정되지 않기 때문에 주의가 필요하다.

실행되는 알파 블렌딩의 종류는,D3DRENDERSTATE_SRCBLEND 및 D3DRENDERSTATE_DESTBLEND 렌더링 스테이트에 따라서 다르다. 전송원 및 목적지의 블렌딩 스테이트는 페어로 사용한다. 다음의 코드는, 전송원의 블렌딩 스테이트를 D3DBLEND_SRCCOLOR 로 설정해, 목적지의 블렌딩 스테이트를 D3DBLEND_INVSRCCOLOR 로 설정하는 방법을 나타낸다.

// 이 코드에서는, lpD3DDevice 는 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다고 한다.

// 전송원의 블렌딩 스테이트를 설정한다.
lpD3DDevice->SetRenderState(D3DRENDERSTATE_SRCBLEND,
                            D3DBLEND_SRCCOLOR);

// 목적지의 블렌딩 스테이트를 설정한다.
lpD3DDevice->SetRenderState(D3DRENDERSTATE_DESTBLEND,
                            D3DBLEND_INVSRCCOLOR);

이 호출의 결과, Direct3D 는, 전송원의 색 (현재 위치 좌표에서의 렌더링 타겟의 프리미티브의 색) 및 목적지의 색 (frame buffer내의 현재 위치 좌표의 색)의 사이에 선형 블렌딩을 실행한다. 이 처리에 의해, 색조를 가지는 유리와 같은 외관이 된다. 목적지 오브젝트의 색의 일부는, 전송원오브젝트로부터 전해진 것처럼 보인다. 그 외의 부분은 흡수된 것처럼 보인다.

전송원 및 목적지의 블렌딩 스테이트의 설정을 바꾸면(자), 안개나 먼지 중(안)에서 오브젝트가 빛나고 있는 것 같은 외관이 된다. 예를 들어, 어플리케이션으로, 불길, 전자력계, 플라스마 광선, 또는 멍하니 한 중에서 빛나고 있는 것 같은 오브젝트를 모델링 하는 경우, 전송원 및 목적지의 블렌딩 스테이트를 D3DBLEND_ONE 로 설정한다.

또, 알파 블렌딩은 3D 신의 라이팅을 제어한다. 이것은 라이트 맵핑으로 불리는 일도 있다. 전송원의 블렌딩 스테이트를 D3DBLEND_ZERO 로 설정해, 목적지의 블렌딩 스테이트를 D3DBLEND_SRCALPHA 로 설정 하면, 전송원의 알파 정보에 따라 장면이 어두워진다. 전송원의 프리미티브는, frame buffer의 내용을 스케일링 하는 라이트 맵으로서 사용되어 필요에 따라서 장면을 어둡게 한다. 이것에 의해, 흑백의 라이트 맵핑이 생성된다.

컬러 라이트 맵핑은, 전송원의 알파 블렌딩 스테이트를 D3DBLEND_ZERO 로 설정해, 목적지의 블렌딩 스테이트를 D3DBLEND_SRCCOLOR 로 설정하는 것으로 실현될 수 있다.

Direct3D 디바이스가 디스플레이 하드웨어로 지원 되고 있는 경우는, 알파값점묘를 실행할 수 있다. 「D3DRENDERSTATE_STIPPLEDALPHA 」를 참조할것. 어플리케이션으로 RGB 또는 램프 소프트웨어 에뮬레이션 디바이스를 생성 하는 경우, Direct3D 는 이 열거값을 무시한다.

[Visual Basic]

Visual Basic 어플리케이션에서는,D3DRENDERSTATE_ALPHABLENDENABLE 렌더링 스테이트를 사용해 알파 투명 블렌딩을 유효하게 한다. Direct3D API 에서는, 다양한 종류의 알파 블렌딩을 사용할 수 있다. 다만, 유저의 3D 하드웨어가 Direct3D 로 가능한 블렌딩 스테이트의 모두에게 대응 하면은 한정되지 않기 때문에 주의가 필요하다.

실행되는 알파 블렌딩의 종류는,D3DRENDERSTATE_SRCBLEND 및 D3DRENDERSTATE_DESTBLEND 렌더링 스테이트에 따라서 다르다. 전송원 및 목적지의 블렌딩 스테이트는 페어로 사용한다. 다음의 코드는, 전송원의 블렌딩 스테이트를 D3DBLEND_SRCCOLOR 로 설정해, 목적지의 블렌딩 스테이트를 D3DBLEND_INVSRCCOLOR 로 설정하는 방법을 나타낸다.

'이 코드에서는, D3DDevice 에 Direct3DDevice7 오브젝트에의
'참조가 저장 되고 있다고 한다.

'전송원의 블렌딩 스테이트를 설정한다.
Call D3DDevice.SetRenderState(D3DRENDERSTATE_SRCBLEND, _
                              D3DBLEND_SRCCOLOR);

'목적지의 블렌딩 스테이트를 설정한다.
Call D3DDevice.SetRenderState(D3DRENDERSTATE_DESTBLEND, _
                              D3DBLEND_INVSRCCOLOR);

이 호출의 결과, Direct3D 는, 전송원의 색 (현재 위치 좌표에서의 렌더링 타겟의 프리미티브의 색) 및 목적지의 색 (frame buffer내의 현재 위치 좌표의 색)의 사이에 선형 블렌딩을 실행한다. 이 처리에 의해, 색조를 가지는 유리와 같은 외관이 된다. 목적지 오브젝트의 색의 일부는, 전송원오브젝트로부터 전해진 것처럼 보인다. 그 외의 부분은 흡수된 것처럼 보인다.

전송원 및 목적지의 블렌딩 스테이트의 설정을 바꾸면(자), 안개나 먼지 중(안)에서 오브젝트가 빛나고 있는 것 같은 외관이 된다. 예를 들어, 어플리케이션으로, 불길, 전자력계, 플라스마 광선, 또는 멍하니 한 중에서 빛나고 있는 것 같은 오브젝트를 모델링 하는 경우, 전송원 및 목적지의 블렌딩 스테이트를 D3DBLEND_ONE 로 설정한다.

또, 알파 블렌딩은 3D 신의 라이팅을 제어한다. 이것은 라이트 맵핑으로 불리는 일도 있다. 전송원의 블렌딩 스테이트를 D3DBLEND_ZERO 로 설정해, 목적지의 블렌딩 스테이트를 D3DBLEND_SRCALPHA 로 설정 하면, 전송원의 알파 정보에 따라 장면이 어두워진다. 전송원의 프리미티브는, frame buffer의 내용을 스케일링 하는 라이트 맵으로서 사용되어 필요에 따라서 장면을 어둡게 한다. 이것에 의해, 흑백의 라이트 맵핑이 생성된다.

컬러 라이트 맵핑은, 전송원의 알파 블렌딩 스테이트를 D3DBLEND_ZERO 로 설정해, 목적지의 블렌딩 스테이트를 D3DBLEND_SRCCOLOR 로 설정하는 것으로 실현될 수 있다.

Direct3D 디바이스가 디스플레이 하드웨어로 지원 하고 있는 경우는, 알파값점묘를 실행할 수 있다. 「D3DRENDERSTATE_STIPPLEDALPHA 」를 참조할것. 어플리케이션으로 RGB 또는 램프 소프트웨어 에뮬레이션 디바이스를 생성 하는 경우, Direct3D 는 이 열거값을 무시한다.


점리스트

Platform SDK: DirectX

점리스트

점리스트란, 각각의 점으로서 렌더링 되는 버텍스의 집합이다. 어플리케이션에서는, 별의 필드 또는 다각형의 표면 위에의 점선에, 3D 신의 점리스트를 사용할 수 있다. 어플리케이션에서는, 버텍스의 배열에 값을 설정하는 것으로 점리스트를 생성 한다.

[C++]

다음의 C++ 코드는, 점리스트를 생성 하는 처리를 나타낸다.

const DWORD TOTAL_VERTS=6;
D3DVERTEX lpVerts[TOTAL_VERTS];

lpVerts[0] = D3DVERTEX(D3DVECTOR(-5,-5, 0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[1] = D3DVERTEX(D3DVECTOR(0,5,0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[2] = D3DVERTEX(D3DVECTOR(5,-5, 0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[3] = D3DVERTEX(D3DVECTOR(10,5,0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[4] = D3DVERTEX(D3DVECTOR(15,-5, 0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[5] = D3DVERTEX(D3DVECTOR(20,5,0), D3DVECTOR(0,0,-1), 0,0);

IDirect3DDevice7::DrawPrimitive 메소드를 사용해 점리스트를 렌더링 한다. 다음의 코드는,IDirect3DDevice7::DrawPrimitive 를 사용해, 위에의 예의 점리스트를 드로잉(Drawing) 하는 방법을 나타낸다. IDirect3DDevice7::DrawPrimitive 의 호출은,IDirect3DDevice7::BeginScene 와 IDirect3DDevice7::EndScene 의 사이에 실시할 필요가 있다.

HRESULT hResult;
// 이 코드에서는, lpDirect3DDevice 은 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다고 한다.
hResult =
    lpDirect3DDevice->DrawPrimitive(D3DPT_POINTLIST,
                                     D3DFVF_VERTEX,
                                     lpVerts,
                                     TOTAL_VERTS,
                                     D3DDP_WAIT);
[Visual Basic]

Visual Basic 로 기술하는 어플리케이션에서는, 다음의 코드로 가리키도록(듯이), 버텍스의 배열에 값을 설정해 점리스트를 생성 한다.

'이 코드에서는, dx 는 DirectX7 오브젝트에의
'유효한 참조이다고 한다.
On Local Error Resume Next
Const TOTAL_VERTS As Integer = 6
Dim Verts(TOTAL_VERTS) As D3DVERTEX

Verts(0) = dx.CreateD3DVertex(-5, -5, 0, 0, 0, -1, 0, 0)
Verts(1) = dx.CreateD3DVertex(0, 5, 0, 0, 0, -1, 0, 0)
Verts(2) = dx.CreateD3DVertex(5, -5, 0, 0, 0, -1, 0, 0)
Verts(3) = dx.CreateD3DVertex(10, 5, 0, 0, 0, -1, 0, 0)
Verts(4) = dx.CreateD3DVertex(15, -5, 0, 0, 0, -1, 0, 0)
Verts(5) = dx.CreateD3DVertex(20, 5, 0, 0, 0, -1, 0, 0)

Direct3DDevice7.DrawPrimitive 메소드를 사용해 점리스트를 렌더링 한다. 다음의 코드는,Direct3DDevice7.DrawPrimitive 를 사용해, 위에의 예의 점리스트를 드로잉(Drawing) 하는 방법을 나타낸다. Direct3DDevice7.DrawPrimitive 의 호출은,Direct3DDevice7.BeginScene 와 Direct3DDevice7.EndScene 의 사이에 실시할 필요가 있다.

'이 코드에서는, d3ddev 는 Direct3DDevice7 오브젝트에의
'유효한 참조이다고 한다.
Call d3ddev.DrawPrimitive(D3DPT_POINTLIST, _
D3DFVF_VERTEX, _
Verts(0), _
TOTAL_VERTS, _
                          D3DDP_WAIT)

If Err.Number <> DD_OK Then
'에러 처리 코드
End If

다음의 그림은, 결과적으로 드로잉(Drawing) 되는 점을 나타낸다.

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


컬러 키잉 스테이트

컬러 키를 설정 하면, Direct3D 는 키 컬러를 투명색으로서 취급한다. Direct3D 에서는, DDSD_CKSRCBLT 플래그를 사용해 생성 된 텍스쳐를 원시적으로 적용 하면 와, 키 컬러와 일치하는 텍셀은 모두 원시적인 것은 렌더링 되지 않는다. DDSD_CKSRCBLT 플래그를 사용하지 않고 생성 된 텍스쳐의 경우는, 그 중에 컬러 키가 포함되어 있어도 컬러 키 이펙트가 표시되지 않는 것에 주의한다.

[C++]

C++ 어플리케이션에서는, 컬러 키를 사용하는 표면 (이 경우 렌더링 타겟 표면)에 대해서,IDirectDrawSurface7::SetColorKey 메소드로 컬러 키를 설정한다. 다만,IDirect3DDevice7::SetRenderState 메소드를 호출해 컬러 키의 온/오프를 바꿀 수가 있다. 제 1 파라미터를 D3DRENDERSTATE_COLORKEYENABLE 로 설정한다. 컬러 키를 유효하게 하려면 제 2 파라미터를 TRUE 로 설정해, 무효로 하려면 FALSE 로 설정한다. 디폴트는 FALSE 이다.

// 이 코드에서는, lpD3DDevice 는 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다고 한다.

// 컬러 키를 무효로 한다.
lpD3DDevice->SetRenderState(D3DRENDERSTATE_COLORKEYENABLE,
                            FALSE);
[Visual Basic]

Visual Basic 로 기술된 어플리케이션에서는, 컬러 키를 사용하는 표면 (이 경우 렌더링 타겟 표면)에 대해서,DirectDrawSurface7.SetColorKey 메소드로 컬러 키를 설정한다. 다만,Direct3DDevice7::SetRenderState 메소드를 호출해 컬러 키의 온/오프를 바꿀 수가 있다. 제 1 파라미터를 D3DRENDERSTATE_COLORKEYENABLE 로 설정한다. 컬러 키를 유효하게 하려면 제 2 파라미터를 True 로 설정해, 무효로 하려면 False 로 설정한다. 디폴트는 False 이다.

'이 코드에서는, D3DDevice 에 Direct3DDevice7 오브젝트에의
'유효한 참조가 저장 되고 있다고 한다.

'컬러 키를 무효로 한다.
Call D3DDevice.SetRenderState(D3DRENDERSTATE_COLORKEYENABLE, _
                              FALSE)


현재 텍스쳐

[Visual Basic]

주 : 여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에서는, 표면 오브젝트 및 Direct3DDevice7.SetTexture 메소드를 사용해 현재 텍스쳐를 디바이스에 할당한다.

[C++]

D3DRENDERSTATE_TEXTUREHANDLE 렌더링 스테이트는 현재는 사용되어 있지 않다. 어플리케이션에서는,IDirect3DDevice7::SetTexture 메소드를 호출해 현재 텍스쳐를 설정한다.


범프 맵핑의 지원의 검출

[C++]

Direct3D 디바이스가 D3DTOP_BUMPENVMAP 또는 D3DTOP_BUMPENVMAPLUMINANCE 텍스쳐 블렌딩 처리의 어느쪽이든을 지원 하고 있는 경우, 그 디바이스에서는 범프 맵핑을 실행할 수 있다. 또, 어플리케이션에서는 디바이스 기능을 조사하는 것으로, 그 어플리케이션으로 적절한 블렌딩 스테이지수 (보통은 3 개 이상)가 지원 되어 적어도 1 개의 범프 맵핑 픽셀 포맷이 공개되고 있는 것을 확인할 필요가 있다.

다음의 코드는, 지정된 조건에 의해 디바이스 기능을 조사해, 현재의 디바이스에서의 범프 맵핑의 지원을 검출한다.

BOOL SupportsBumpMapping()
{
DDPIXELFORMAT ddpfBumpMap;
D3DDEVICEDESC7 d3dDevDesc;
ZeroMemory( &d3dDevDesc, sizeof(d3dDevDesc) );

// 디바이스 기능을 취득한다.
g_pd3dDevice->GetCaps( &d3dDevDesc );

// 이 디바이스가 2 개의 범프 맵핑 블렌드 처리를 지원 하고 있을지 어떨지.
DWORD dwBumpOps = d3dDevDesc.dwTextureOpCaps &
(D3DTEXOPCAPS_BUMPENVMAP | D3DTEXOPCAPS_BUMPENVMAPLUMINANCE);
if ( 0 == dwBumpOps)
return FALSE;

// 이 디바이스가 최대 3 개의 블렌딩 스테이지를 지원 하고 있을지 어떨지.
if( d3dDevDesc.wMaxTextureBlendStages < 3)
return FALSE;

    //
// 유효한 범프 맵 픽셀 포맷이 있을지 어떨지를 조사한다.
    //

// 유효한 포맷이 검출되었을 경우,
// 콜백 함수에 의해 g_bFoundBumpFormat 글로벌 변수가 TRUE 로 설정된다.
g_bFoundBumpFormat = FALSE;

g_pd3dDevice->EnumTextureFormats(TextureCallback, (LPVOID) &ddpfBumpMap);
if( FALSE == g_bFoundBumpFormat )
return FALSE;

// 현재 ddpfBumpMap 에 있는 픽셀 포맷은,
// 유효하다라고 하는 것이 보증되고 있는 표면 포맷을 생성 하기 위해서 사용할 수 있다.
return TRUE;
}

다음의 코드는, 콜백 함수가 IDirect3DDevice7::EnumTextureFormats 메소드에 건넌다.

HRESULT CALLBACK TextureCallback( DDPIXELFORMAT* pddpf, VOID* pddpfOut)
{
// 최초로 열거되고 있는 DuDv 포맷을 취득한다.
if( DDPF_BUMPDUDV == pddpf->dwFlags ){
// 다음에 표면을 생성 할 경우에 사용할 수 있도록(듯이),
// 포맷을 pddpfOut 의 변수에 카피한다.
memcpy( pddpfOut, (LPVOID) pddpf, sizeof(DDPIXELFORMAT) );

// 성공을 알리는 글로벌 플래그를 설정한다.
g_bFoundBumpFormat = TRUE;
return D3DENUMRET_CANCEL;
    }

return D3DENUMRET_OK;
}
[Visual Basic]

Direct3D 디바이스가 D3DTOP_BUMPENVMAP 또는 D3DTOP_BUMPENVMAPLUMINANCE 텍스쳐 블렌딩의 어느쪽이든을 지원 하고 있는 경우, 그 디바이스에서는 범프 맵핑을 실행할 수 있다. 또, 어플리케이션에서는 디바이스 기능을 조사하는 것으로, 그 어플리케이션으로 적절한 블렌딩 스테이지수 (보통은 3 개 이상)가 지원 되어 적어도 1 개의 범프 맵핑 픽셀 포맷이 공개되고 있는 것을 확인할 필요가 있다.

다음의 코드는, 지정된 조건에 의해 디바이스 기능을 조사해, 현재의 디바이스에서의 범프 맵핑의 지원을 검출한다.

Function SupportsBumpMapping() As Boolean
Dim ddpfBumpMap As DDPIXELFORMAT
Dim d3dDevDesc As D3DDEVICEDESC7

SupportsBumpMapping = True

'디바이스 기능을 취득한다.
Call g_d3dDevice.GetCaps(d3dDevDesc)

'이 디바이스가 2 개의 범프 맵핑 블렌드 처리를 지원 하고 있을지 어떨지.
Dim lBumpOps As Long
lBumpOps = (d3dDevDesc.lTextureOpCaps And _
(D3DTEXOPCAPS_BUMPENVMAP Or D3DTEXOPCAPS_BUMPENVMAPLUMINANCE))

If lBumpOps = 0 Then SupportsBumpMapping = False

'이 디바이스가 최대 3 개의 블렌딩 스테이지를 지원 하고 있을지 어떨지.
If d3dDevDesc.nMaxTextureBlendStages < 3 Then SupportsBumpMapping = False

    '
'유효한 범프 맵 픽셀 포맷이 있을지 어떨지를 조사한다.
    '
Dim BumpEnum As Direct3DEnumPixelFormats
Set BumpEnum = g_d3dDevice.GetTextureFormatsEnum

Dim iLoop As Integer
For iLoop = 0 To BumpEnum.GetCount
Call BumpEnum.GetItem(iLoop, ddpfBumpMap)

'포맷이 검출되면(자), 루프를 정지한다.
If ddpfBumpMap.lFlags And DDPF_BUMPDUDV Then Exit For
Next iLoop

If Not (ddpfBumpMap.lFlags And DDPF_BUMPDUDV) Then
SupportsBumpMapping = False
End If
End Function


삼각형 스트립

Platform SDK: DirectX

삼각형 스트립

삼각형 스트립이란, 일련의 결합된 삼각형이다. 삼각형은 결합되고 있기 (위해)때문에, 각 삼각형에 대해서 3 개의 버텍스 모든 것을 어플리케이션으로 반복해 지정할 필요는 없다. 예를 들어, 다음의 삼각형 스트립을 정의하는 경우, 7 개의 버텍스만 필요하다.

시스템에서는, 버텍스의 v1, v2, v3 를 사용해 최초의 삼각형을, v2, v4, v3 를 사용해 2 번째의 삼각형을, v3, v4, v5 를 사용해 3 번째의 삼각형을, v4, v6, v5 를 사용해 4 번째의 삼각형을, 이라고 하는 순서로 드로잉(Drawing) 해 나간다. 2 번째와 4 번째의 삼각형의 버텍스가 순서 대로가 아닌 것에 주의한다. 이것은, 모든 삼각형이 시계회전의 방향으로 드로잉(Drawing) 되는 것을 보증하기 위해서 필요하다.

3D 신의 대부분의 오브젝트는 삼각형 스트립으로 구성되어 있다. 이것은, 삼각형 스트립을 사용해 복잡한 오브젝트를 지정 하면, 메모리를 효율적으로 이용해 처리 시간을 단축할 수 있기 때문이다. 삼각형 스트립은, 버텍스의 배열에 값을 설정해 생성 한다.

[C++]

다음의 C++ 코드에서는, 삼각형 스트립으로서 사용하기 위해서 버텍스를 배열에 저장 한다.

const DWORD TOTAL_VERTS=6;
D3DVERTEX lpVerts[TOTAL_VERTS];

lpVerts[0] = D3DVERTEX(D3DVECTOR(-5,-5, 0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[1] = D3DVERTEX(D3DVECTOR(0,5,0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[2] = D3DVERTEX(D3DVECTOR(5,-5, 0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[3] = D3DVERTEX(D3DVECTOR(10,5,0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[4] = D3DVERTEX(D3DVECTOR(15,-5, 0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[5] = D3DVERTEX(D3DVECTOR(20,5,0), D3DVECTOR(0,0,-1), 0,0);

이 후,IDirect3DDevice7::DrawPrimitive 메소드를 사용해 삼각형 스트립을 렌더링 할 수 있다. 다음의 코드는,IDirect3DDevice7::DrawPrimitive 를 사용해, 위에의 예의 삼각형 스트립을 드로잉(Drawing) 하는 방법을 나타낸다. IDirect3DDevice7::DrawPrimitive 의 호출은,IDirect3DDevice7::BeginScene 와 IDirect3DDevice7::EndScene 의 사이에 실시할 필요가 있다.

HRESULT hResult;
// 이 코드에서는, lpDirect3DDevice7 은 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다고 한다.
hResult =
    lpDirect3DDevice->DrawPrimitive(D3DPT_TRIANGLESTRIP,
                                      D3DFVF_VERTEX,
                                      lpVerts,
                                      TOTAL_VERTS,
                                      D3DDP_WAIT);
[Visual Basic]

Visual Basic 로 기술된 어플리케이션에서는, 다음과 같은 코드로 삼각형 스트립을 설정할 수 있다.

'이 코드에서는, dx 는 DirectX7 오브젝트에의
'유효한 참조이다고 한다.
On Local Error Resume Next
Const TOTAL_VERTS As Integer = 6
Dim Verts(TOTAL_VERTS) As D3DVERTEX

Verts(0) = dx.CreateD3DVertex(-5, -5, 0, 0, 0, -1, 0, 0)
Verts(1) = dx.CreateD3DVertex(0, 5, 0, 0, 0, -1, 0, 0)
Verts(2) = dx.CreateD3DVertex(5, -5, 0, 0, 0, -1, 0, 0)
Verts(3) = dx.CreateD3DVertex(10, 5, 0, 0, 0, -1, 0, 0)
Verts(4) = dx.CreateD3DVertex(15, -5, 0, 0, 0, -1, 0, 0)
Verts(5) = dx.CreateD3DVertex(20, 5, 0, 0, 0, -1, 0, 0)

이 후,Direct3DDevice7.DrawPrimitive 메소드를 사용해 삼각형 스트립을 렌더링 할 수 있다. 다음의 코드는,Direct3DDevice7.DrawPrimitive 를 사용해, 위에의 예의 삼각형 스트립을 드로잉(Drawing) 하는 방법을 나타낸다. Direct3DDevice7.DrawPrimitive 의 호출은,Direct3DDevice7.BeginScene 와 Direct3DDevice7.EndScene 의 사이에 실시할 필요가 있다.

'이 코드에서는, d3ddev 가 Direct3DDevice7 오브젝트에의
'유효한 참조이다고 한다.
Call d3ddev.DrawPrimitive(D3DPT_TRIANGLESTRIP, _
D3DFVF_VERTEX, _
Verts(0), _
TOTAL_VERTS, _
D3DDP_WAIT);

If Err.Number <> DD_OK Then
'에러 처리 코드
End If

다음의 그림은, 결과적으로 드로잉(Drawing) 되는 삼각형 스트립을 나타낸다.


텍스쳐 addressing mode와 텍스쳐 랩핑

Direct3D 에 의해, 어플리케이션은 텍스쳐 랩핑을 실행할 수 있다. 다만, 텍스쳐 addressing mode를 D3DTADDRESS_WRAP 로 설정하는 것으로, 텍스쳐 랩핑을 실행하는 것은 같지 않기 때문에 주의가 필요하다. 텍스쳐 addressing mode를 D3DTADDRESS_WRAP 로 설정 하면, 현재의 원시적으로 적용되고 있는 텍스쳐의 카피를 복수 할 수 있다. 한편, 텍스쳐 랩핑을 유효하게 하면, 텍스쳐 처리한 다각형에 대한 시스템의 라스터화의 방법이 변경된다. 상세한 것에 대하여는, 「텍스쳐 랩핑」을 참조할것.

텍스쳐 랩핑을 유효하게 하면, 효율적으로 [0.0, 1.0] 의 범위외의 텍스쳐 좌표를 무효로 할 수 있다. 이 경우, 이 범위외에 있는 텍스쳐 좌표등의 라스터화의 동작은 정의되지 않는다. 텍스쳐 랩핑을 유효하게 하면, 텍스쳐 addressing mode는 사용되지 않는다. 텍스쳐 랩핑이 유효하게 되어 있을 때는, 0.0 미만 또는 1.0 을 넘는 텍스쳐 좌표를 어플리케이션으로 지정하지 않게 주의 해야 한다.


큐브 환경 맵의 밉맵화

큐브 환경 맵은 밉맵화할 수 있다. DDSCAPS_MIPMAP 를 포함하면(자), Attach 된 밉맵 표면이 있는 각 표면이 생성 된다. 이러한 표면의 형상으로서는, 다음과 같은 것이 있다.

[C++]

밉맵화 큐브 환경 맵을 생성 하는 어플리케이션으로 각 표면에 액세스 하려면 ,IDirectDrawSurface7::GetAttachedSurface 메소드를 호출해,"DDSCAPS2_CUBEMAP_" 플래그로 시작되는 플래그의 어느쪽이든을 건네주어 대응하는 표면에 액세스 한다 ( 「큐브 환경 맵 표면에의 액세스」로 설명한다). 다음에, 그 표면에 대해서 IDirectDrawSurface7::GetAttachedSurface 를 호출해, DDSCAPS_MIPMAP 플래그를 건네주면(자), 종속 밉맵 레벨을 취득할 수 있다.

[Visual Basic]

밉맵화 큐브 환경 맵을 생성 하는 어플리케이션으로 각 표면에 액세스 하려면 ,DirectDrawSurface7.GetAttachedSurface 메소드를 호출해,"DDSCAPS2_CUBEMAP_" 으로 시작되는 CONST_DDSURFACECAPS2FLAGS 열거로부터의 플래그의 어느쪽이든을 건네주어 대응하는 표면에 액세스 한다 ( 「큐브 환경 맵 표면에의 액세스」를 설명한다). 다음에, 그 표면에 대해서 DirectDrawSurface7.GetAttachedSurface 를 호출해, DDSCAPS_MIPMAP 플래그를 건네주면(자), 종속 밉맵 레벨을 취득할 수 있다.


깊이 버퍼링 스테이트

깊이 버퍼링이란, 은선 및 은면을 삭제하는 방법이다. 개요에 대해서는, 「깊이 버퍼란」을 참조할것. 디폴트에서는, 깊이 버퍼링은 사용되지 않는다.

[C++]

C++ 어플리케이션에서는,D3DZBUFFERTYPE 열거의 멤버의 어느쪽이든을 사용해 새로운 스테이트값을 지정하는 것으로,D3DRENDERSTATE_ZENABLE 렌더링 스테이트에서 깊이 버퍼링 스테이트를 갱신한다.

무엇인가의 이유로써, Direct3D 에 의한 깊이 버퍼에의 쓰기를 방지할 필요가 있는 경우는,D3DRENDERSTATE_ZWRITEENABLE 열거값을 사용해,IDirect3DDevice7::SetRenderState 의 호출의 제 2 파라미터로서 FALSE 를 지정한다.

다음의 코드는, z 버퍼링이 유효하게 되도록(듯이) 깊이 버퍼 스테이트를 설정하는 방법을 나타낸다.

// 이 코드에서는, lpD3DDevice 는 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다고 한다.

// z 버퍼링을 유효하게 한다.
lpD3DDevice->SetRenderState(D3DRENDERSTATE_ZENABLE,
                            D3DZB_TRUE); // D3DZB_TRUE is the same as TRUE

어플리케이션에서는, 또,D3DRENDERSTATE_ZFUNC 렌더링 스테이트를 사용해, 깊이 버퍼링의 실행시에 Direct3D 로 사용하는 비교 함수를 제어할 수 있다.

z 바이어스란, 서로의 깊이값이 같아도, 한편의 표면을 한편의 표면보다 앞에 표시하는 방법이다. 이 테크닉은, 다양한 이펙트를 기대할 수 있다. 일반적인 예로서 벽에 그림자를 붙이는 경우를 생각한다. 그림자도 벽도 깊이값은 같다. 그러나, 아무래도 벽에 그림자를 붙이려고 하는 경우가 있다. 이러한 경우, 그림자에 z 바이어스를 적용하는 것으로, 벽 위에 그림자를 적절히 표시할 수 있다 ( 「D3DRENDERSTATE_ZBIAS 」를 참조할것).

[Visual Basic]

Visual Basic 어플리케이션에서는,CONST_D3DZBUFFERTYPE 열거의 멤버의 어느쪽이든을 사용해 새로운 스테이트값을 지정하는 것으로,D3DRENDERSTATE_ZENABLE 렌더링 스테이트에서 깊이 버퍼링 스테이트를 갱신한다.

무엇인가의 이유로써, Direct3D 에 의한 깊이 버퍼에의 쓰기를 방지할 필요가 있는 경우는,D3DRENDERSTATE_ZWRITEENABLE 렌더링 스테이트를 사용해,Direct3DDevice7::SetRenderState 의 호출의 제 2 파라미터로서 D3DZB_FALSE 를 지정한다.

다음의 Visual Basic 코드는, z 버퍼링이 유효하게 되도록(듯이) 깊이 버퍼 스테이트를 설정하는 방법을 나타낸다.

'이 코드에서는, D3DDevice 에 Direct3DDevice7 오브젝트에의
'유효한 참조가 저장 되고 있다고 한다.

' z 버퍼링을 유효하게 한다.
Call D3DDevice.SetRenderState(D3DRENDERSTATE_ZENABLE, _
                              D3DZB_TRUE)

어플리케이션에서는, 또,D3DRENDERSTATE_ZFUNC 렌더링 스테이트를 사용해, 깊이 버퍼링의 실행시에 Direct3D 로 사용하는 비교 함수를 제어할 수 있다.

z 바이어스란, 서로의 깊이값이 같아도, 한편의 표면을 한편의 표면보다 앞에 표시하는 방법이다. 이 테크닉은, 다양한 이펙트를 기대할 수 있다. 일반적인 예로서 벽에 그림자를 붙이는 경우를 생각한다. 그림자도 벽도 깊이값은 같다. 그러나, 아무래도 벽에 그림자를 붙이려고 하는 경우가 있다. 이러한 경우, 그림자에 z 바이어스를 적용하는 것으로, 벽 위에 그림자를 적절히 표시할 수 있다 (D3DRENDERSTATE_ZBIAS 를 참조할것).


포인트 라이트

포인트 라이트는, 장면내에서 색과 위치 좌표를 가지지만, 단일의 방향은 가지지 않는다. 다음의 그림에 나타내도록(듯이), 포인트 라이트는 모든 방향으로 균등하게 미츠루를 추방한다.

포인트 라이트의 예로서는 전구가 있다. 포인트 라이트는 감쇠와 범위의 영향을 받아 버텍스 마다 메쉬를 비춘다. 라이팅의 실행중, Direct3D 는, 월드 공간에서의 포인트 라이트의 위치 좌표와 라이팅 하는 버텍스의 좌표를 사용해, 라이트의 방향을 나타내는 벡터와 빛이 진행된 거리를 취득한다. 버텍스 법선에 가세해, 이 벡터와 거리의 양쪽 모두를 사용해, 표면에 어느 정도 빛이 맞는지를 계산한다.


큐브 환경 맵 표면의 생성

큐브 환경 맵을 생성 하려면 , C++ 의 경우는 IDirectDraw7::CreateSurface 메소드를, Visual Basic 의 경우는 DirectDraw7.CreateSurface 를 호출한다. 큐브 맵은복합 표면이다. 즉, 큐브 맵은 Attach 된 표면세트이며, 1 회의 호출로 DirectDraw 에 의해 생성 된다. 개별적으로 생성 된 표면은, 서로 Attach 해 큐브 환경 맵을 생성 할 수 없다. 큐브 환경 맵 텍스쳐는 직사각형이 아니면 안되어, 그 크기는 2 의 거듭제곱이다.

[C++]

다음의 코드는, C++ 어플리케이션으로 단순한 큐브 환경 맵을 생성 하는 방법을 나타낸다.

// 이 예에서는, pDD 변수는 IDirectDraw7 인터페이스에의
// 유효한 포인터이다.
DDSURFACEDESC2 ddsd;

ZeroMemory((LPVOID) &ddsd, sizeof(DDSURFACEDESC2));

ddsd.dwSize         = sizeof(DDSURFACEDESC2);
ddsd.dwFlags        = DDSD_CAPS | DDSD_WIDTH |
                      DDSD_HEIGHT | DDSD_PIXELFORMAT;
ddsd.ddsCaps.dwCaps = DDSCAPS_TEXTURE;

// 픽셀 포맷을 유효한 텍스쳐 포맷으로 설정한다.

// 크기는 임의로 지정할 수 있지만, 2 의 거듭제곱이 아니면 안된다.
ddsd.dwWidth  = 64;
ddsd.dwHeight = 64;

// 유효한 렌더링 타겟 표면인, 시스템 메모리의 큐브 맵 텍스쳐의
// 능력을 설정한다.
ddsd.ddsCaps.dwCaps  = DDSCAPS_COMPLEX | DDSCAPS_3DDEVICE |
DDSCAPS_TEXTURE;
ddsd.ddsCaps.dwCaps2 = DDSCAPS2_CUBEMAP|DDSCAPS2_CUBEMAP_ALLFACES;

LPDIRECTDRAWSURFACE7 pddsCubeMap;

// 큐브 맵을 생성 한다.
if( FAILED( pDD->CreateSurface( &ddsd, pddsCubeMap, NULL ) ) )
{
// 에러 처리 코드
}

주 : 큐브 맵의 표면에 대해서 렌더링 하는 경우는, 표면을 생성 할 경우에 정의하는 표면 기술에 DDSCAPS_3DDEVICE 를 포함할 필요가 있다.

큐브 맵은 관리하의 텍스쳐로 할 수 있다. 표면을 생성 하면 와, 표면 능력에 DDSCAPS2_TEXTUREMANAGE 또는 DDSCAPS2_TEXTUREMANAGE 플래그의 어느쪽이든을 포함하면(자) 관리하의 텍스쳐가 된다. 상세한 것에 대하여는, 「자동 텍스쳐 관리」를 참조할것.

[Visual Basic]

다음의 코드는, Visual Basic 어플리케이션으로 단순한 큐브 환경 맵을 생성 하는 방법을 나타낸다.

'이 예에서는, dd 변수는 DirectDraw7 오브젝트에의
'유효한 참조이다.
On Local Error Resume Next

Dim ddsd As DDSURFACEDESC2

ddsd.lFlags = DDSD_CAPS Or DDSD_WIDTH Or _
DDSD_HEIGHT Or DDSD_PIXELFORMAT

ddsd.ddsCaps.dwCaps = DDSCAPS_TEXTURE

'픽셀 포맷을 유효한 텍스쳐 포맷으로 설정한다.

'크기는 임의로 지정할 수 있지만, 2 의 거듭제곱이 아니면 안된다.
ddsd.dwWidth = 64:ddsd.dwHeight = 64

'유효한 렌더링 타겟 표면인, 시스템 메모리의 큐브 맵 텍스쳐의
'능력을 설정한다.
ddsd.ddsCaps.dwCaps = DDSCAPS_COMPLEX Or DDSCAPS_3DDEVICE Or _
DDSCAPS_TEXTURE
ddsd.ddsCaps.dwCaps2 = DDSCAPS2_CUBEMAP Or DDSCAPS2_CUBEMAP_ALLFACES

Dim ddsCubeMap As DirectDrawSurface7

'큐브 맵을 생성 한다.
Set ddsCubeMap = dd.CreateSurface(ddsd)

If Err.Number <> DD_OK Then
'에러 처리 코드
End If

주 : 큐브 맵의 표면에 대해서 렌더링 하는 경우는, 표면을 생성 할 경우에 정의하는 표면 기술에 DDSCAPS_3DDEVICE 를 포함할 필요가 있다.

큐브 맵은 관리하의 텍스쳐로 할 수 있다. 표면을 생성 하면 와, 표면 능력에 DDSCAPS2_TEXTUREMANAGE 또는 DDSCAPS2_TEXTUREMANAGE 플래그의 어느쪽이든을 포함하면(자) 관리하의 텍스쳐가 된다. 상세한 것에 대하여는, 「자동 텍스쳐 관리」를 참조할것.


랩 텍스쳐 addressing mode에 대해

[C++]

D3DTEXTUREADDRESS 열거형의 D3DTADDRESS_WRAP 멤버로 지정하는 "랩" 텍스쳐 addressing mode에서는, Direct3D 는 모든 정수 접합으로 텍스쳐를 반복해 적용한다. 예를 들어, 프로그램으로 정방형 프리미티브를 생성 해, 텍스쳐 좌표 (0.0, 0.0), (0.0, 3.0), (3.0, 3.0), 및 (3.0, 0.0)을 지정하는 경우를 생각한다. 텍스쳐 addressing mode를 D3DTADDRESS_WRAP 로 설정 하면, u 및 v 의 양방향에서 텍스쳐가 3 회 적용된다.

[Visual Basic]

CONST_D3DTEXTUREADDRESS 열거의 D3DTADDRESS_WRAP 멤버로 지정하는 "랩" 텍스쳐 addressing mode에서는, 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에 대하며」를 참조할것.


밉맵이란

밉맵과는 연속한 텍스쳐로, 각 텍스쳐는 같은 화면을 서서히 저해상도로 한 것이다. 밉맵에서의 각 화면의 높이와 폭, 즉 레벨은, 직전의 레벨보다 2 의 거듭제곱만 작다. 밉맵은 정방형일 필요는 없다.

시점에 가까운 오브젝트에는, 고해상도 밉맵 화면이 사용된다. 오브젝트가 시점으로부터 멀어지는에 따라, 저해상도의 밉맵 화면이 사용된다. 밉맵 처리에 의해, 렌더링 한 텍스쳐의 품질이 향상하지만, 사용하는 메모리는 증가한다.

Direct3D 에서는, 밉맵은 Attach 된 표면의 체인으로서 나타내진다. 이 체인의 선두에는 최고 해상도의 텍스쳐가 있어, 그 후에는 다음의 밉맵 레벨의 텍스쳐가 계속된다. 이 레벨의 뒤에는 다음의 레벨의 밉맵이 계속된다, 라고 하는 순으로 최저 해상도의 밉맵이 될 때까지 계속되어 간다.

다음의 그림은 이 예를 나타낸다. 비트 맵 텍스쳐 세트는, 일인용 게임의 3D 컨테이너의 측면에 있는 기호를 나타내고 있다. 밉맵으로서 생성 하면, 최고 해상도의 텍스쳐가 이 세트의 선두에 온다. 이 밉맵 세트가 연속하는 각 텍스쳐는, 높이와 폭이 2 의 거듭제곱씩 작게 되어 간다. 이 경우는, 최고 해상도의 밉맵은, 256 x 256 픽셀이다. 다음의 텍스쳐는 128x128 이다. 마지막 텍스쳐는 64x64 이다.

이 기호는, 가시 범위내의 최대 거리에 있다. 이 기호로부터 멀게 멀어진 위치 좌표로부터 게임을 시작 하는 경우는, 밉맵 체인 중(안)에서 최소의 64x64 텍스쳐가 표시된다.

플레이어의 시점이 이 기호에 가까워지는 것에 따라, 서서히 고해상도의 텍스쳐가 사용된다.

최고 해상도의 텍스쳐가 사용되는 것은, 플레이어의 시점이 이 기호에 가장 가까워졌을 때이다.

이것은, 텍스쳐의 원근 이펙트를 시뮬레이트 하는 방법 중(안)에서는 오버헤드가 낮은 방법이다. 1 개의 텍스쳐를 많은 해상도로 렌더링 하는 것보다도, 다양한 해상도로 복수의 텍스쳐를 사용하는 (분)편이 고속으로 있다.

Direct3D 에서는, 밉맵 세트 중(안)에서 어느 텍스쳐가 가장 희망 출력에 가까운 해상도인지를 평가해, 픽셀을 그 텍셀 공간에 맵핑 할 수 있다. 최종적인 화면의 해상도가 밉맵 세트내의 텍스쳐간에 있는 경우, Direct3D 에서는 양쪽 모두의 밉맵의 텍셀을 조사해 그 컬러값을 블렌드 한다.

어플리케이션으로 밉맵을 사용하는 경우는, 밉맵 세트를 생성 할 필요가 있다. 상세한 것에 대하여는, 「밉맵 세트의 생성」을 참조할것. 어플리케이션에서는, 밉맵 세트를 현재 텍스쳐 세트의 최초의 텍스쳐로서 선택해, 밉맵을 적용한다. 상세한 것에 대하여는, 「멀티 텍스쳐 블렌딩」을 참조할것.

다음에, Direct3D 로 텍셀의 샘플링에 사용하는 필터링 방법을 설정해야 한다. 가장 처리가 빠른 밉맵 필터링은, Direct3D 로 가장 가까운 텍셀을 선택하는 방법이다. 이것 선택하려면 , D3DTFP_POINT 열거값을 사용한다. Direct3D 에서는, D3DTFP_LINEAR 열거값을 사용 하면, 보다 고품질인 필터링 결과를 얻을 수 있다. 이 필터링에서는, 가장 가까운 밉맵이 선택되어 다음에 현재의 픽셀이 맵핑 되는, 텍스쳐내의 위치 좌표의 주변 텍셀의 가중평균이 계산된다.


텍스쳐 랩핑 스테이트

[C++]

주 : u- 및 v- 랩핑 렌더링 스테이트의 D3DRENDERSTATE_WRAPU 및 D3DRENDERSTATE_WRAPV 는, 현재는 사용되어 있지 않다. 이것들은,D3DRENDERSTATE_WRAP0 ~ D3DRENDERSTATE_WRAP7 까지의 렌더링 스테이트로 옮겨지고 있다.

이러한 랩핑 렌더링 스테이트는, 디바이스의 멀티 텍스쳐 cascade의 각종 텍스쳐에 대해서, u- 및 v- 랩핑을 유효 또는 무효로 한다. 이러한 렌더링 스테이트를 D3DWRAPCOORD_0, D3DWRAPCOORD_1, D3DWRAPCOORD_2, 및 D3DWRAPCOORD_3 플래그의 조합해로 설정해, 텍스쳐의 제 1, 제 2, 제 3, 및 제 4 방향에서의 랩핑을 유효하게 한다. 제로를 설정 하면, 랩핑은 모두 무효가 된다. 디폴트에서는, 텍스쳐 랩핑은, 모든 텍스쳐 스테이지의 전방향으로 무효가 되어 있다. 개요에 대해서는, 「텍스쳐 랩핑」을 참조할것.

D3DRENDERSTATE_WRAPU 및 D3DRENDERSTATE_WRAPV 는 새로운 렌더링 스테이트로 옮겨지고 있지만,IDirect3DDevice7 인터페이스에서는 이것들은 인식된다. 이러한 구렌더링 스테이트를 IDirect3DDevice7::SetRenderState 에 건네주면(자), 최초의 텍스쳐 스테이지 (스테이지 0)의 u- 및 v- 텍스쳐 랩핑이 영향을 받는다.

[Visual Basic]

D3DRENDERSTATE_WRAP0 ~ D3DRENDERSTATE_WRAP7 렌더링 스테이트는, 디바이스의 멀티 텍스쳐 cascade의 각종 텍스쳐에 대해서, 텍스쳐 랩핑을 제어한다. 이러한 렌더링 스테이트를,CONST_D3D 열거로부터의 D3DWRAPCOORD_0, D3DWRAPCOORD_1, D3DWRAPCOORD_2, 및 D3DWRAPCOORD_3 의 값의 조합해로 설정해, 텍스쳐의 제 1, 제 2, 제 3, 및 제 4 방향에서의 랩핑을 유효하게 한다. 제로를 설정 하면, 랩핑은 모두 무효가 된다. 디폴트에서는, 텍스쳐 랩핑은, 모든 텍스쳐 스테이지의 전방향으로 무효가 되어 있다. 개요에 대해서는, 「텍스쳐 랩핑」을 참조할것.


텍스쳐 좌표의 자동 생성

Direct3D 에서는, 버텍스에 대해서 텍스쳐 좌표를 자동적으로 생성할 수 있다. 이 섹션에서는, 시스템이 제공하는 기능과 그 사용 방법에 대해 자세하게 설명한다. 설명하는 주제는 다음과 같다.

  • 텍스쳐 좌표의 자동 생성에 대해
  • 텍스쳐 좌표의 자동 생성의 구성


큐브 환경 맵의 텍스쳐 좌표

[C++]

큐브 환경 맵을 지시하는 텍스쳐 좌표는, 표준 텍스쳐의 적용시에 사용하는 단순한 u, v 스타일의 좌표와는 다르다. 실제, 큐브 환경 맵에서는 텍스쳐 좌표를 전혀 사용하지 않는다. 텍스쳐 좌표 세트 대신에, 큐브 환경 맵에서는 3D 벡터가 필요하다. 적절한 버텍스 포맷을 지정하는 것이 중요하다. 또, 시스템에 어플리케이션으로 사용하는 텍스쳐 좌표세트수를 알리는 것 외에도, 각 세트내의 요소수에 대한 정보를 알릴 필요가 있다. 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 플래그를 사용해, 시스템에 카메라 공간의 트랜스 폼이 끝난 버텍스 법선을 텍스쳐의 애드레싱 벡터로서 사용하는 것을 알릴 수가 있다). 인덱스는, 시스템이 텍스쳐의 랩핑 모드를 결정하기 위해서(때문에) 마셔 사용한다.

다음의 코드는, 이 값의 사용 방법을 나타낸다.

// pd3dDevice 변수는, IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다.

// 스테이지 2 에 대해서 텍스쳐 좌표를 자동 생성한다.
// 여기에서는, 스테이지 2 에 큐브 맵을 할당할 수 있고 있다고 한다
// (인덱스 1 의 텍스쳐 좌표 세트로부터의 랩 모드를 사용한다).
pd3dDevice->SetTextureStageState( 2, D3DTSS_TEXCOORDINDEX,
D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR | 1);

자동 텍스쳐 좌표 생성을 유효하게 하면, 2 개의 공식의 어느쪽이든을 사용해 각 버텍스의 반사 벡터가 계산된다. D3DRENDERSTATE_LOCALVIEWER 렌더링 스테이트를 TRUE 로 설정 하면, 다음의 공식이 사용된다.

이 공식에서는,R 는 계산하는 반사 벡터,E 는 위치 좌표로부터 시점까지의 정규화된 벡터,N 는 카메라 공간의 버텍스 법선이다.

D3DRENDERSTATE_LOCALVIEWER 렌더링 스테이트를 FALSE 로 설정 하면, 다음의 공식이 사용된다.

이 공식에서는,R 및 N 요소에 대해서는 전의 공식과 같다. Nz 요소는 버텍스 법선의 월드 공간 z,I 는 무한대 거리에 있는 뷰포트의 벡터 (0,0,1)이다. 시스템에서는, 몇개의 공식에서 요구한 반사 벡터를 사용해, 큐브 맵의 적절한 표면을 선택 및 처리한다.

주 : 대부분의 경우, 어플리케이션에서는 버텍스 법선의 자동 정규화를 유효하게 할 필요가 있다. 이것을 유효하게 하려면 ,D3DRENDERSTATE_NORMALIZENORMALS 를 TRUE 로 설정한다. 이 렌더링 스테이트를 유효하게 하고 있지 않는 경우, 환경 맵의 외관이 기대와는 크게 다른 것이 된다.

[Visual Basic]

큐브 환경 맵을 지시하는 텍스쳐 좌표는, 표준 텍스쳐의 적용시에 사용하는 단순한 u, v 스타일의 좌표와는 다르다. 실제, 큐브 환경 맵에서는 텍스쳐 좌표를 전혀 사용하지 않는다. 텍스쳐 좌표 세트 대신에, 큐브 환경 맵에서는 3D 벡터가 필요하다. 적절한 버텍스 포맷을 지정하는 것이 중요하다. 또, 시스템에 어플리케이션으로 사용하는 텍스쳐 좌표세트수를 알리는 것 외에도, 각 세트내의 요소수에 대한 정보를 알릴 필요가 있다. Direct3D 는, 이것을 실시하기 위해서(때문에) 헬퍼-함수의 D3DFVF_TEXCOORDSIZEn 세트를 Math.bas 소스 파일에 준비해 있다 (Math.bas 파일은 이 SDK 에 부속되어 있다). 이러한 헬퍼-함수에는 파라미터가 1 개 있어, 사이즈가 기술되는 텍스쳐 좌표 세트의 인덱스를 식별한다. 3D 벡터의 경우는,D3DFVF_TEXCOORDSIZE3 헬퍼-함수로 생성 하는 비트 패턴을 포함한다. 다음의 코드는, 이 함수의 사용 방법을 나타낸다.

'버텍스의 유연한 버텍스 포맷 기술자를 생성 한다.
'이것에는, 위치 좌표, 법선, 및
' 3D 텍스쳐 좌표세트가 1 개 포함된다.
Dim lFVF As Long
lFVF = D3DFVF_XYZ Or D3DFVF_NORMAL Or
D3DFVF_TEX1 Or D3DFVF_TEXCOORDSIZE3(0)

디퓨즈 라이트 맵핑등의 경우에는, 벡터에 카메라 공간의 버텍스 법선을 사용한다. 스펙큐러 환경 맵핑등의 경우에는, 반사 벡터를 사용한다 (트랜스 폼이 끝난 버텍스 법선에 대해서는 넓게 이해되고 있기 (위해)때문에, 여기에서는 반사 벡터의 계산에 대해 자세하게 설명한다).

독자적으로 반사 벡터를 계산하려면 , 각 버텍스의 위치 좌표와 뷰포트로부터 그 버텍스에의 벡터를 알고 있을 필요가 있다. Direct3D 에서는 지오메트리의 반사 벡터를 자동적으로 계산할 수 있다. 이 기능을 사용하면, 메모리를 절약할 수 있다 (환경 맵의 텍스쳐 좌표를 포함할 필요가 없다). 즉, 대역폭이 감소해,TnLHAL 디바이스의 경우는, 어플리케이션으로 독자적으로 계산하는 것 보다 훨씬 빠르게 계산을 실행할 수 있다. 이 기능을 이용하려면 , 큐브 환경 맵을 포함한 텍스쳐 스테이지에 있어,D3DTSS_TEXCOORDINDEX 텍스쳐 스테이지 스테이트를, D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR 플래그의 편성과 텍스쳐 좌표 세트의 인덱스로 설정하는 것만으로 있다 (디퓨즈 라이트 맵핑의 경우등에는, D3DTSS_TCI_CAMERASPACENORMAL 플래그를 사용해, 시스템에 카메라 공간의 트랜스 폼이 끝난 버텍스 법선을 텍스쳐의 애드레싱 벡터로서 사용하는 것을 알릴 수가 있다). 인덱스는, 시스템이 텍스쳐의 랩핑 모드를 결정하기 위해서(때문에) 마셔 사용한다.

다음의 코드는, 이 값의 사용 방법을 나타낸다.

' pd3dDevice 변수는, Direct3DDevice7 오브젝트에의
'유효한 참조이다.

'스테이지 2 에 대해서 텍스쳐 좌표를 자동 생성한다.
'여기에서는, 스테이지 2 에 큐브 맵을 할당할 수 있고 있다고 한다
' (인덱스 1 의 텍스쳐 좌표 세트로부터의 랩 모드를 사용한다)
Call d3dDevice.SetTextureStageState(2, D3DTSS_TEXCOORDINDEX,
D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR Or 1)

자동 텍스쳐 좌표 생성을 유효하게 하면, 2 개의 공식의 어느쪽이든을 사용해 각 버텍스의 반사 벡터가 계산된다. D3DRENDERSTATE_LOCALVIEWER 렌더링 스테이트를 True 로 설정 하면, 다음의 공식이 사용된다.

이 공식에서는,R 는 계산하는 반사 벡터,E 는 위치 좌표로부터 시점까지의 정규화된 벡터,N 는 카메라 공간의 버텍스 법선이다.

D3DRENDERSTATE_LOCALVIEWER 렌더링 스테이트를 False 로 설정 하면, 다음의 공식이 사용된다.

이 공식에서는,R 및 N 요소에 대해서는 전의 공식과 같다. Nz 요소는 버텍스 법선의 월드 공간 z,I 는 무한대 거리에 있는 뷰포트의 벡터 (0,0,1)이다. 시스템에서는, 몇개의 공식에서 요구한 반사 벡터를 사용해, 큐브 맵의 적절한 표면을 선택 및 처리한다.

주 : 대부분의 경우, 어플리케이션에서는 버텍스 법선의 자동 정규화를 유효하게 할 필요가 있다. 이것을 유효하게 하려면 ,D3DRENDERSTATE_NORMALIZENORMALS 를 True 로 설정한다. 이 렌더링 스테이트를 유효하게 하고 있지 않는 경우, 환경 맵의 외관이 기대와는 크게 다른 것이 된다.


블렌딩 행렬의 설정

[C++]

IDirect3DDevice7::SetTransform 메소드를 호출해, 시스템이 블렌드 할 때의 트랜스 폼 행렬을 설정한다. 제 1 파라미터에 D3DTRANSFORMSTATETYPE 열거형으로부터 "D3DTRANSFORMSTATE_WORLD" 멤버를 설정해, 제 2 파라미터에는 설정하는 행렬의 주소를 설정한다.

다음의 C++ 코드는, 2 개의 월드 행렬을 설정한다. 이러한 행렬간에 지오메트리를 블렌드 해 팔을 연결한다.

// 이 예에서는, pd3dDevice 변수는
// 초기화된 3D 신용의 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다고 한다.
float     fBendAngle = 3.1415926f / 4.0f; // 45о
D3DMATRIX matUpperArm, matLowerArm;

// 상완은 움직이지 않는다. 단위행렬을 사용한다.
D3DUtil_SetIdentityMatrix( matUpperArm );
pd3dDevice->SetTransform( D3DTRANSFORMSTATE_WORLD,  &matUpperArm );

// 팔뚝은 x 축을 중심으로 회전한다. 이것은 상완에 연결한다.
D3DUtil_SetRotateXMatrix( matLowerArm, -fBendAngle );
pd3dDevice->SetTransform( D3DTRANSFORMSTATE_WORLD1, &matLowerArm );

블렌딩 행렬을 설정해도, 시스템은 그 행렬을 다음에 사용할 수 있도록(듯이) 단지 캐쉬하는 것만으로, 버텍스의 블렌드를 시작 하는 것은 아니다. 상세한 것에 대하여는, 「지오메트리 블렌딩의 유효화」를 참조할것.

[Visual Basic]

Direct3DDevice7.SetTransform 메소드를 호출해, 시스템이 블렌드 할 때의 트랜스 폼 행렬을 설정한다. 제 1 파라미터에 CONST_D3DTRANSFORMSTATETYPE 열거로부터 "D3DTRANSFORMSTATE_WORLD" 멤버를 설정해, 제 2 파라미터에는 설정하는 행렬의 주소를 설정한다.

다음의 Visual Basic 코드는, 2 개의 월드 행렬을 설정한다. 이러한 행렬간에 지오메트리를 블렌드 해 팔을 연결한다.

'이 예에서는, d3dDevice 변수는
'초기화된 3D 신용의 Direct3DDevice7 오브젝트에의
유효한 참조이다고 한다. dx 변수는 DirectX7 오브젝트에의 유효한 참조이다.
Dim nBendAngle As Single
Dim matUpperArm As D3DMATRIX, _
matLowerArm As D3DMATRIX

nBendAngle = 3.1415926 / 4#  ' 45о

'상완은 움직이지 않는다. 단위행렬을 사용한다.
Call dx.IdentityMatrix(matUpperArm)
Call d3dDevice.SetTransform(D3DTRANSFORMSTATE_WORLD, matUpperArm)

'팔뚝은 x 축을 중심으로 회전한다. 이것은 상완에 연결한다.
Call dx.RotateXMatrix(matLowerArm, -nBendAngle)
Call d3dDevice.SetTransform(D3DTRANSFORMSTATE_WORLD1, matLowerArm)

블렌딩 행렬을 설정해도, 시스템은 그 행렬을 다음에 사용할 수 있도록(듯이) 단지 캐쉬하는 것만으로, 버텍스의 블렌드를 시작 하는 것은 아니다. 상세한 것에 대하여는, 「지오메트리 블렌딩의 유효화」를 참조할것.


서브 픽셀 보정 스테이트

D3DRENDERSTATE_SUBPIXEL 및 D3DRENDERSTATE_SUBPIXELX 렌더링 스테이트는 사용되지 않고, 시스템에서는 이것을 무시한다.


버텍스 버퍼 렌더링 메소드의 호출

[C++]

IDirect3DDevice7::DrawPrimitiveVB 메소드는,IDirect3DDevice7::DrawPrimitive 메소드에 대응한다. 같이DrawPrimitiveVB 메소드도, 버텍스가 버텍스 버퍼내에 순서대로 나타난다고 본다.

DrawPrimitiveVB 메소드는 5 개의 파라미터를 받는다. d3dptPrimitiveType 파라미터에는,D3DPRIMITIVETYPE 열거형의 멤버의 1 개를 사용해, 렌더링 하는 프리미티브의 종류를 설정한다. 제 2 파라미터 lpd3dVertexBuffer 에는, 버텍스를 포함한 버텍스 버퍼의 주소를 지정해, 다음에,dwStartVertex 파라미터와 dwNumVertices 파라미터에, 렌더링 하는 제 1 버텍스와 버텍스의 합계수를 나타내는 값을 설정한다. 버텍스 버퍼에 포함되는 모든 버텍스를 렌더링 할 필요는 없지만, 프리미티브의 종류에 응한 적절한 수의 버텍스를 사용해야 한다 (D3DPRIMITIVETYPE 의 참조 정보에 기술). 마지막 파라미터 dwFlags 는, 렌더링의 동작을 결정한다. 이 플래그는 다른 렌더링 메소드로 사용되는 플래그와 동일하다. 렌더링중에 플래그를 설정해, 라이팅 및 클리핑을 유효하게 하거나 클립 범위를 갱신할 수가 있다.

IDirect3DDevice7::DrawIndexedPrimitiveVB 메소드는, 버텍스 버퍼내의 버텍스에 인덱스를 붙여 프리미티브를 렌더링 한다. 최초의 2 개의 파라미터는,DrawPrimitiveVB 메소드의 파라미터와 같다. 제 3 및 제 4 파라미터에는, 버퍼내의 최초의 버텍스의 인덱스 및 렌더링 하는 버텍스의 합계수를 각각 설정한다. 제 5 파라미터 lpwIndices 에는, 렌더링 하는 버텍스에 액세스 하기 위해서 메소드가 사용하는 WORD 인덱스의 순서 첨부 배열의 주소를 설정해, 제 6 파라미터 dwIndexCount 에는, 그 배열에 포함되는 인덱스값의 개수를 설정한다. dwFlags 파라미터는,DrawPrimitiveVB 메소드의 대응하는 파라미터와 같다.

[Visual Basic]

Direct3DDevice7.DrawPrimitiveVB 메소드는,Direct3DDevice7.DrawPrimitive 메소드에 대응한다. 똑같이,DrawPrimitiveVB 메소드도, 버텍스가 버텍스 버퍼내에 순서대로 나타난다고 본다.

DrawPrimitiveVB 메소드는 5 개의 파라미터를 받는다. d3dpt 파라미터에는,CONST_D3DPRIMITIVETYPE 열거의 멤버의 어느쪽이든을 사용해, 렌더링 하는 프리미티브의 종류를 설정한다. 제 2 파라미터 vertexBuffer 에는, 버텍스를 포함한 Direct3DVertexBuffer7 오브젝트를 지정해,startVertex 및 numVertices 파라미터에는, 최초의 버텍스 및 렌더링 하는 버텍스의 합계수를 나타내는 값을 지정한다. 버텍스 버퍼에 포함되는 모든 버텍스를 렌더링 할 필요는 없지만, 프리미티브의 종류에 응한 적절한 수의 버텍스를 사용해야 한다 (D3DPRIMITIVETYPE 의 참조 정보에 기술). 마지막 파라미터 flags 는, 렌더링의 동작을 결정한다. 이것들 플래그는, 그 외의 렌더링 메소드로 사용되는 플래그와 같다. 렌더링중에 플래그를 설정해, 라이팅 및 클리핑을 유효하게 하거나 클립 범위를 갱신할 수가 있다.

Direct3DDevice7.DrawIndexedPrimitiveVB 메소드는, 버텍스 버퍼내의 버텍스에 인덱스를 붙여 프리미티브를 렌더링 한다. 최초의 2 개의 파라미터는,DrawPrimitiveVB 메소드의 파라미터와 같다. 제 3 및 제 4 파라미터에는, 버퍼내의 최초의 버텍스의 인덱스 및 렌더링 하는 버텍스의 합계수를 각각 설정한다. 제 5 파라미터 indexArray 에는, 렌더링 하는 버텍스에 액세스 하기 위해서 메소드가 사용하는 Integer 인덱스의 순서 첨부 배열의 주소를 설정해, 제 6 파라미터 indexCount 에는, 그 배열에 포함되는 인덱스값의 개수를 설정한다. flags 파라미터는,DrawPrimitiveVB 메소드의 대응하는 파라미터와 같다.

버퍼내의 버텍스 포맷에 버텍스 법선이 포함되지 않은 경우는, 버텍스 버퍼 렌더링 메소드에 라이팅을 요구할 수 없다. 또, D3DDP_DONOTCLIP 플래그를 사용해 생성 된, 트랜스 폼 된 버텍스 버퍼로부터의 렌더링을 실시하는 경우, 렌더링 메소드에 버텍스의 클립을 요구할 수 없다 (이것은, 트랜스폼 되지 않은의 버텍스 버퍼에 대해서는 요구할 수 있다. 렌더링시에 시스템이 클리핑 가능한 버퍼를 생성 하기 때문이다). 이용할 수 없는 서비스를 요구해도, 디버그 빌드로 메소드가 실패하는 원인이 될 것은 없지만, 서비스는 적용되지 않는다.

하드웨어 가속화 트랜스 폼 & 라이팅이 가능한 TnLHAL 디바이스 (IID_IDirect3DTnLHALDevice)와는 대조적으로, 소프트웨어 디바이스 또는 HAL 디바이스 (IID_IDirect3DHALDevice)에서는, D3DVBCAPS_SYSTEMMEMORY 플래그로 생성 된 버텍스 버퍼로부터의 렌더링만 실행할 수 있다. 상세한 것에 대하여는, 「디바이스의 종류와 버텍스 처리의 요건」을 참조할것.


텍스쳐 스테이지와 텍스쳐 블렌딩 cascade

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)로 설정 하면, 모든 텍스쳐 맵핑을 무효로 할 수 있다.


버텍스 포그(안개:fog)의 사용

어플리케이션으로 버텍스 포그(안개:fog)를 유효하게 하려면 , 다음의 순서에 따른다.

[C++]

C++ 어플리케이션으로 버텍스 포그(안개:fog)를 유효하게 하려면

  1. D3DRENDERSTATE_FOGENABLE 를 TRUE 로 설정해, 포그(안개:fog) 블렌딩을 유효하게 한다.
  2. D3DRENDERSTATE_FOGCOLOR 렌더링 스테이트에서 필요한 포그(안개:fog) 컬러를 설정한다.
  3. D3DRENDERSTATE_FOGVERTEXMODE 렌더링 스테이트를 D3DFOGMODE 열거형의 멤버로 설정해, 희망의 포그(안개:fog) 공식을 선택한다.
  4. 선택한 포그(안개:fog) 공식에서 필요한 포그(안개:fog) 파라미터를 렌더링 스테이트로 설정한다.

다음에, 이상의 순서를 C++ 코드로 가리킨다.

// 간단하게 하기 위해서, 이 예에서는, 호출의 후에
// 에러값을 체크하지 않는다. 실제의 어플리케이션에서는,
// 에러값을 올바르게 체크하는 것.
//
// 이 예에서는, g_lpDevice 는 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다.
void SetupVertexFog(DWORD dwColor, DWORD dwMode, BOOL fUseRange, FLOAT fDensity)
{
    float fStart = 0.5f,    // 선형 포그(안개:fog) 거리.
          fEnd   = 0.8f;

    // 포그(안개:fog) 블렌딩을 유효하게 한다.
    g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGENABLE, TRUE);

    // 포그(안개:fog) 컬러를 설정한다.
    g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGCOLOR, dwColor);

    // 포그(안개:fog) 파라미터를 설정한다.
    if(D3DFOG_LINEAR == dwMode)
    {
        g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGVERTEXMODE, dwMode);
        g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGSTART, *(DWORD *)(&fStart));
        g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGEND,   *(DWORD *)(&fEnd));
    }
    else
    {
        g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGVERTEXMODE, dwMode);
        g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGDENSITY, *(DWORD *)(&fDensity));
    }

    // 필요에 따라서, 범위 베이스의 포그(안개:fog)를 유효하게 한다 (버텍스 포그(안개:fog)에서만 지원 된다).
    // 이 예에서는, 드라이버가 D3DPRASTERCAPS_FOGRANGE 능력을 공개하는 경우에게만,
    // fUseRange 는 제로 이외의 값으로 설정된다고 한다.
    //
    // 주 :  이 (분)편이, 범위에 근거하지 않는 포그(안개:fog)보다
    //       약간 퍼포먼스가 좋다.
    if(fUseRange)
        g_lpDevice->SetRenderState(
                       D3DRENDERSTATE_RANGEFOGENABLE,
                       TRUE);
}

주 : IDirect3DDevice7::SetRenderState 메소드는, 제 2 파라미터에 DWORD 값만 받지만, 부동 소수점값의 포그(안개:fog) 파라미터가 요구되는 일도 있다. 전술의 예에서는 부동 소수점의 값을 메소드에 건네주기 위해서(때문에), 데이터를 트랜스 폼 하는 것이 아니라, 부동 소수점 변수의 주소를 DWORD 포인터에 캐스트 해, 다음에 그것을 참조하고 있다.

[Visual Basic]

Visual Basic 어플리케이션으로 버텍스 포그(안개:fog)를 유효하게 하려면

  1. D3DRENDERSTATE_FOGENABLE 를 True 로 설정해, 포그(안개:fog) 블렌딩을 유효하게 한다.
  2. 희망의 포그(안개:fog) 컬러를 D3DRENDERSTATE_FOGCOLOR 렌더링 스테이트로 설정한다.
  3. D3DRENDERSTATE_FOGVERTEXMODE 렌더링 스테이트를 CONST_D3DFOGMODE 열거의 멤버로 설정해, 희망의 포그(안개:fog) 공식을 선택한다.
  4. 선택한 포그(안개:fog) 공식에서 필요한 포그(안개:fog) 파라미터를 렌더링 스테이트로 설정한다.

다음에, 이상의 순서를 Visual Basic 코드로 가리킨다.

'간단하게 하기 위해서, 이 예에서는, 호출의 후에
'에러값을 체크하지 않는다. 실제의 어플리케이션에서는,
'에러값을 올바르게 체크하는 것.
'
'이 예에서는, g_d3dDevice 는 Direct3DDevice7 오브젝트에의
'유효한 참조를 나타낸다.
Sub SetupVertexFog(lColor As Long, Mode As CONST_D3DFOGMODE, _
bUseRange As Boolean, Optional Density As Single)

Dim StartFog As Single, _
EndFog As Single

'선형 포그(안개:fog)의 거리를 설정한다.
StartFog = 0.5:EndFog = 0.8

'포그(안개:fog) 블렌딩을 유효하게 한다.
Call g_d3dDevice.SetRenderState(D3DRENDERSTATE_FOGENABLE, True)

'포그(안개:fog) 컬러를 설정한다.
Call g_d3dDevice.SetRenderState(D3DRENDERSTATE_FOGCOLOR, lColor)

'포그(안개:fog) 파라미터를 설정한다.
If Mode = D3DFOG_LINEAR Then
Call g_d3dDevice.SetRenderState(D3DRENDERSTATE_FOGVERTEXMODE, Mode)
Call g_d3dDevice.SetRenderStateSingle(D3DRENDERSTATE_FOGSTART, StartFog)
Call g_d3dDevice.SetRenderStateSingle(D3DRENDERSTATE_FOGEND, EndFog)
Else
Call g_d3dDevice.SetRenderState(D3DRENDERSTATE_FOGVERTEXMODE, Mode)
Call g_d3dDevice.SetRenderStateSingle(D3DRENDERSTATE_FOGDENSITY, Density)
End If

'필요에 따라서, 범위 베이스의 포그(안개:fog)를 유효하게 한다 (버텍스 포그(안개:fog)에서만 지원 된다).
'이 예에서는, 드라이버가 D3DPRASTERCAPS_FOGRANGE 능력을 공개하는 경우에게만,
' bUseRange 는 True 로 설정된다고 한다.
    '
'주 :  이 (분)편이, 범위에 근거하지 않는 포그(안개:fog)보다
'약간 퍼포먼스가 좋다.
If bUseRange = True Then
Call g_d3dDevice.SetRenderState( _
D3DRENDERSTATE_RANGEFOGENABLE, True)
End If
End Sub


프리미티브 클리핑 스테이트

[C++]

Direct3D 에서는, 뷰포트외에서 부분적으로 렌더링 하는 프리미티브를 클리핑 할 수가 있다. C++ 의 경우, Direct3D 클리핑은 D3DRENDERSTATE_CLIPPING 렌더링 스테이트에서 제어한다. 이 렌더링 스테이트를 TRUE (디폴트값)로 설정 하면, 프리미티브 클리핑이 유효하게 된다. 렌더링 스테이트를 FALSE 로 설정 하면, Direct3D 의 그리핑 서비스는 무효가 된다.

프리미티브 클리핑 렌더링 스테이트는, 버텍스 버퍼내의 버텍스로써 가능한 클리핑 처리에는 전혀 의존하지 않는다. IDirect3DVertexBuffer7::ProcessVertices 및 IDirect3DVertexBuffer7::ProcessVerticesStrided 메소드는, 버텍스 처리 시에 프리미티브 클리핑을 제어하는, 독자적인 플래그를 받는다.

주 : 이 렌더링 스테이트는, 반대이지만 종래의 렌더링 메소드로 사용된 D3DDP_DONOTCLIP 플래그 와 유사한다. DirectX 7.0 에서는, 이 렌더링 스테이트가 D3DDP_DONOTCLIP 플래그에 옮겨지고 있다. D3DDP_DONOTCLIP 플래그로 1 회가 호출할 것에 클리핑을 무효 하는 경우, 스테이트값이 어플리케이션에 의해 재차 변경될 때까지는, 렌더링에 관한 모든 호출이 이 렌더링 스테이트의 영향을 받는다.

[Visual Basic]

Direct3D 에서는, 뷰포트외에서 부분적으로 렌더링 하는 프리미티브를 클리핑 할 수가 있다. Visual Basic 어플리케이션에서는, Direct3D 클리핑은 D3DRENDERSTATE_CLIPPING 렌더링 스테이트에서 제어한다. 이 렌더링 스테이트를 TRUE (디폴트값)로 설정 하면, 프리미티브 클리핑이 유효하게 된다. 렌더링 스테이트를 FALSE 로 설정 하면, Direct3D 의 그리핑 서비스는 무효가 된다.

프리미티브 클리핑 렌더링 스테이트는, 버텍스 버퍼내의 버텍스로써 가능한 클리핑 처리에는 전혀 의존하지 않는다. Direct3DVertexBuffer7.ProcessVertices 메소드는, 버텍스 처리 시에 프리미티브 클리핑을 제어하는, 독자적인 플래그를 받는다.


디퓨즈 라이트 맵

광원에서 비추었을 때, 광택이 없는 표면은 디퓨즈 라이트를 추방한다. 디퓨즈 라이트의 빛남은, 광원으로부터의 거리, 및 표면 법선과 광원의 방향 벡터와의 각도에 따라서 다르다. 라이팅 계산에 의해 시뮬레이트 하는 디퓨즈 라이트의 이펙트는 일반적인 것이다.

[C++]

텍스쳐 라이트 맵을 사용해 디퓨즈 라이트를 시뮬레이트 할 수 있다. 이것을 실시하려면 , 다음의 C++ 코드로 가리키도록(듯이), 디퓨즈 라이트 맵을 베이스 텍스쳐에 추가한다.

// 이 예에서는, lpD3DDev 은 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다고 한다.
// lptexBaseTexture 는, 텍스쳐에의 유효한 포인터이다.
// lptexDiffuseLightMap 는, RGB 디퓨즈 라이트 맵 데이터를 포함한다
// 텍스쳐에의 유효한 포인터이다.

// 베이스 텍스쳐를 설정한다.
lpD3DDev->SetTexture(0, lptexBaseTexture );

// 베이스 텍스쳐 처리와 인수를 설정한다.
lpD3DDev->SetTextureStageState(0, D3DTSS_COLOROP,
       D3DTOP_MODULATE );
lpD3DDev->SetTextureStageState(0, D3DTSS_COLORARG1, D3DTA_TEXTURE );
lpD3DDev->SetTextureStageState(0, D3DTSS_COLORARG2, D3DTA_DIFFUSE );

// 디퓨즈 라이트 맵을 설정한다.
lpD3DDev->SetTexture(1, lptexDiffuseLightMap );

// 블렌딩 스테이지를 설정한다.
lpD3DDev->SetTextureStageState(1, D3DTSS_COLOROP, D3DTOP_MODULATE );
lpD3DDev->SetTextureStageState(1, D3DTSS_COLORARG1, D3DTA_TEXTURE );
lpD3DDev->SetTextureStageState(1, D3DTSS_COLORARG2, D3DTA_CURRENT );
[Visual Basic]

텍스쳐 라이트 맵을 사용해 디퓨즈 라이트를 시뮬레이트 할 수 있다. 이것을 실시하려면 , 다음의 Visual Basic 코드로 가리키도록(듯이), 디퓨즈 라이트 맵을 베이스 텍스쳐에 추가한다.

'이 예에서는, d3dDev 는 Direct3DDevice7 오브젝트에의
'유효한 참조이다고 한다.
' texBaseTexture 는, 텍스쳐에의 유효한 참조이다.
' texDiffuseLightMap 는, RGB 디퓨즈 라이트 맵 데이터를 포함한다
'텍스쳐에의 유효한 참조이다.

'베이스 텍스쳐를 설정한다.
Call d3dDev.SetTexture(0, texBaseTexture)

'베이스 텍스쳐 처리와 인수를 설정한다.
Call d3dDev.SetTextureStageState(0, D3DTSS_COLOROP, _
D3DTOP_MODULATE );
Call d3dDev.SetTextureStageState(0, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call d3dDev.SetTextureStageState(0, D3DTSS_COLORARG2, D3DTA_DIFFUSE)

'디퓨즈 라이트 맵을 설정한다.
Call d3dDev.SetTexture(1, texDiffuseLightMap)

'블렌딩 스테이지를 설정한다.
Call d3dDev.SetTextureStageState(1, D3DTSS_COLOROP, D3DTOP_MODULATE)
Call d3dDev.SetTextureStageState(1, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call d3dDev.SetTextureStageState(1, D3DTSS_COLORARG2, D3DTA_CURRENT)


선스트립

Platform SDK: DirectX

선스트립

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

[C++]

다음의 C++ 코드는, 버텍스의 배열에 값을 설정하는 처리를 나타낸다.

const DWORD TOTAL_VERTS=6;
D3DVERTEX lpVerts[TOTAL_VERTS];

lpVerts[0] = D3DVERTEX(D3DVECTOR(-5,-5, 0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[1] = D3DVERTEX(D3DVECTOR(0,5,0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[2] = D3DVERTEX(D3DVECTOR(5,-5, 0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[3] = D3DVERTEX(D3DVECTOR(10,5,0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[4] = D3DVERTEX(D3DVECTOR(15,-5, 0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[5] = D3DVERTEX(D3DVECTOR(20,5,0), D3DVECTOR(0,0,-1), 0,0);

IDirect3DDevice7::DrawPrimitive 메소드를 사용해 선리스트를 렌더링 한다. 다음의 코드는,IDirect3DDevice7::DrawPrimitive 를 사용해, 위에의 예의 선스트립을 드로잉(Drawing) 하는 방법을 나타낸다. IDirect3DDevice7::DrawPrimitive 의 호출은,IDirect3DDevice7::BeginScene 와 IDirect3DDevice7::EndScene 의 사이에 실시할 필요가 있다.

HRESULT hResult;
// 이 코드에서는, lpDirect3DDevice 은 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다고 한다.
hResult =
    lpDirect3DDevice->DrawPrimitive(D3DPT_LINESTRIP,
                                      D3DFVF_VERTEX,
                                      lpVerts,
                                      TOTAL_VERTS,
                                      D3DDP_WAIT);
[Visual Basic]

다음의 Visual Basic 코드는, 버텍스의 배열에 값을 설정하는 처리를 나타낸다.

'이 코드에서는, dx 는 DirectX7 오브젝트에의
'유효한 참조이다고 한다.
On Local Error Resume Next
Const TOTAL_VERTS As Integer = 6
Dim Verts(TOTAL_VERTS) As D3DVERTEX

Verts(0) = dx.CreateD3DVertex(-5, -5, 0, 0, 0, -1, 0, 0)
Verts(1) = dx.CreateD3DVertex(0, 5, 0, 0, 0, -1, 0, 0)
Verts(2) = dx.CreateD3DVertex(5, -5, 0, 0, 0, -1, 0, 0)
Verts(3) = dx.CreateD3DVertex(10, 5, 0, 0, 0, -1, 0, 0)
Verts(4) = dx.CreateD3DVertex(15, -5, 0, 0, 0, -1, 0, 0)
Verts(5) = dx.CreateD3DVertex(20, 5, 0, 0, 0, -1, 0, 0)

Direct3DDevice7.DrawPrimitive 메소드를 사용해 선리스트를 렌더링 한다. 다음의 코드는,Direct3DDevice7.DrawPrimitive 를 사용해, 위에의 예의 선스트립을 드로잉(Drawing) 하는 방법을 나타낸다. Direct3DDevice7.DrawPrimitive 의 호출은,Direct3DDevice7.BeginScene 와 Direct3DDevice7.EndScene 의 사이에 실시할 필요가 있다.

'이 코드에서는, d3ddev 는 Direct3DDevice7 오브젝트에의
'유효한 참조이다고 한다.
Call d3ddev.DrawPrimitive(D3DPT_LINESTRIP, _
D3DFVF_VERTEX, _
Verts(0), _
TOTAL_VERTS, _
                          D3DDP_WAIT)

If Err.Number <> DD_OK Then
'에러 처리 코드
End If

다음의 그림은, 위에의 코드에 의해 생성 되는 선스트립을 나타낸다.


렌더링 스테이트에 대해

디바이스 렌더링 스테이트는, Direct3D 디바이스의 라스터화 모듈의 동작을 제어한다. 렌더링 스테이트의 속성을 변경 하면, 사용하는 쉐이딩 타입, 포그(안개:fog) 속성 등, 다수의 라스터화를 지정할 수 있다.

[C++]

C++ 로 기술된 어플리케이션에서는,IDirect3DDevice7::SetRenderState 메소드를 호출해, 렌더링 스테이트의 그 외의 특성을 제어한다. D3DRENDERSTATETYPE 열거형은, 가능한 렌더링 스테이트를 모두 지정한다. 어플리케이션에서는,D3DRENDERSTATETYPE 열거로부터의 값을 제 1 파라미터로서 IDirect3DDevice7::SetRenderState 메소드에 건네준다.

렌더링 스테이트는, 텍스쳐의 스타일 및 텍스쳐 필터링의 방법도 제어한다. DirectX 6.0 이후에서는, 텍스쳐에 관한 모든 렌더링 스테이트는,IDirect3DDevice7::SetTextureStageState 메소드가 제공하는 대응 기능으로 옮겨지고 있다. 이것들 옮겨놓을 수 있었던 렌더링 스테이트를 IDirect3DDevice7 인터페이스로 사용 하면 실패한다.

D3DRENDERSTATE_TEXTUREADDRESS, D3DRENDERSTATE_TEXTUREADDRESSU, 및 D3DRENDERSTATE_TEXTUREADDRESSV
D3DTSS_ADDRESS, D3DTSS_ADDRESSU, D3DTSS_ADDRESSV 텍스쳐 스테이지 스테이트로 옮겨지고 있다.
D3DRENDERSTATE_BORDERCOLOR
D3DTSS_BORDERCOLOR 텍스쳐 스테이지 스테이트로 옮겨지고 있다.
D3DRENDERSTATE_TEXTUREMAG
D3DTSS_MAGFILTER 텍스쳐 스테이지 스테이트로 옮겨지고 있다.
D3DRENDERSTATE_TEXTUREMIN
D3DTSS_MINFILTER 텍스쳐 스테이지 스테이트로 옮겨지고 있다. 밉맵 축소 필터링은 D3DTSS_MIPFILTER 로 옮겨지고 있다.
D3DRENDERSTATE_TEXTUREMAPBLEND
D3DTSS_COLOROP 및 D3DTSS_ALPHAOP 텍스쳐 스테이지 스테이트로 옮겨지고 있다.
[Visual Basic]

Visual Basic 어플리케이션에서는,Direct3DDevice7.SetRenderState 메소드를 호출해, 렌더링 스테이트의 특성을 제어한다. CONST_D3DRENDERSTATETYPE 열거형은, 가능한 렌더링 스테이트를 모두 지정한다. 어플리케이션에서는,CONST_D3DRENDERSTATETYPE 열거의 값을 제 1 파라미터로서 Direct3DDevice7.SetRenderState 메소드에 건네준다.


버텍스색스테이트

[C++]

D3DVERTEX ,D3DLVERTEX , 및 D3DTLVERTEX 형의 버텍스는, 색정보와 법선 정보를 동시에 가질 수 없다. 디폴트의 쉐이딩 모드는 gouraud shading로, 이 모드는 버텍스의 색정보와 법선 정보의 양쪽 모두에 의존하기 위해(때문에), Direct3D 에서는 라이팅 계산에 버텍스색을 사용하지 않았다.

그런데 , DirectX 5.0 으로 유연한 버텍스 포맷이 도입된 것에 의해, 버텍스는 색정보와 법선 정보의 양쪽 모두를 가질 수 있게 되었다. 디폴트에서는, 이 정보를 사용해 라이팅 계산이 실행된다. 어플리케이션으로 버텍스의 컬러 라이팅 정보의 사용을 무효로 하는 경우,IDirect3DDevice7::SetRenderState 메소드를 호출해, 제 1 파라미터로서 D3DRENDERSTATE_COLORVERTEX 를 건네준다. 제 2 파라미터를 FALSE 로 설정 하면 버텍스의 컬러 라이팅이 무효가 되어, TRUE 로 설정 하면 유효하게 된다.

버텍스 단위색이 유효한은 있는 경우, 어플리케이션에서는, 버텍스의 색정보의 정보 소스를 설정할 수 있다. D3DRENDERSTATE_DIFFUSEMATERIALSOURCE ,D3DRENDERSTATE_SPECULARMATERIALSOURCE ,D3DRENDERSTATE_AMBIENTMATERIALSOURCE , 및 D3DRENDERSTATE_EMISSIVEMATERIALSOURCE 렌더링 스테이트에 의해, 디퓨즈, 스펙큐러, 앰비언트, 및 에미션(emission)색의 색성분 소스의 색소스를 제어한다. 이러한 각 렌더링 스테이트는,D3DMATERIALCOLORSOURCE 열거형의 멤버로 설정할 수 있다. 이 열거형은, 현재의 머트리얼, 디퓨즈색, 또는 스펙큐러색을, 지정된 색성분의 소스로서 사용하도록(듯이) 시스템에 알리는 정수를 정의한다.

[Visual Basic]

D3DVERTEX ,D3DLVERTEX , 및 D3DTLVERTEX 형의 버텍스는, 색정보와 법선 정보를 동시에 가질 수 없다. 디폴트의 쉐이딩 모드는 gouraud shading이며, 이 모드는 버텍스의 색정보와 법선 정보의 양쪽 모두에 의존하기 위해(때문에), Direct3D 에서는 라이팅 계산에 버텍스색을 사용하지 않았다.

유연한 버텍스 포맷을 사용 하면, 이미 설명한 버텍스 타입과는 대조적으로, 버텍스는 색정보와 법선 정보의 양쪽 모두를 가질 수가 있다. 디폴트에서는, 이 정보를 사용해 라이팅 계산이 실행된다. 어플리케이션으로 버텍스의 컬러 라이팅 정보에 사용을 무효로 하는 경우,Direct3DDevice7.SetRenderState 메소드를 호출해, 제 1 파라미터로서 D3DRENDERSTATE_COLORVERTEX 를 건네준다. 제 2 파라미터를 FALSE 로 설정 하면 버텍스의 컬러 라이팅이 무효가 되어, TRUE 로 설정 하면 유효하게 된다.

버텍스 단위색이 유효하게 되어 있는 경우, 어플리케이션에서는, 버텍스의 색정보의 정보 소스를 설정할 수 있다. D3DRENDERSTATE_DIFFUSEMATERIALSOURCE ,D3DRENDERSTATE_SPECULARMATERIALSOURCE ,D3DRENDERSTATE_AMBIENTMATERIALSOURCE , 및 D3DRENDERSTATE_EMISSIVEMATERIALSOURCE 렌더링 스테이트에 의해, 디퓨즈, 스펙큐러, 앰비언트, 및 에미션(emission)색의 색성분 소스의 색소스를 제어한다. 이러한 각 렌더링 스테이트는,CONST_D3DMATERIALCOLORSOURCE 열거형의 멤버로 설정할 수 있다. 이러한 열거형은, 현재의 머트리얼, 디퓨즈색, 또는 스펙큐러색을, 지정된 색성분의 소스로서 사용하도록(듯이) 시스템에 알리는 정수를 정의한다.


스텐실 버퍼 스테이트

어플리케이션에서는, 스텐실 버퍼를 사용해, 렌더링 타겟 표면에 픽셀을 기입할지 어떨지를 결정한다. 상세한 것에 대하여는, 「스텐실 버퍼」를 참조할것.

[C++]

C++ 로 기술된 어플리케이션으로, 스텐실 처리를 유효 또는 무효로 하려면 ,IDirect3DDevice7::SetRenderState 메소드를 호출한다. 제 1 파라미터의 값으로서 D3DRENDERSTATE_STENCILENABLE 를 건네준다. 스텐실 처리를 유효하게 하려면 제 2 파라미터의 값을 TRUE 로 설정해, 무효로 하려면 FALSE 로 설정한다.

Direct3D 의 스텐실 테스트로 사용하는 비교 함수는,IDirect3DDevice7::SetRenderState 메소드를 호출해 설정한다. 제 1 파라미터를 D3DRENDERSTATE_STENCILFUNC 로 설정한다. 제 2 파라미터의 값으로서 D3DCMPFUNC 열거형의 멤버를 건네준다.

스텐실 참조값이란, 스텐실 함수가 테스트에 사용하는, 스텐실 버퍼내의 값이다. 디폴트에서는 스텐실 참조값은 제로이다. 어플리케이션에서는,IDirect3DDevice7::SetRenderState 메소드를 호출해 이 값을 설정할 수 있다. 제 1 파라미터의 값으로서 D3DRENDERSTATE_STENCILREF 를 건네준다. 제 2 파라미터의 값을 새로운 참조값으로 설정한다.

Direct3D 모듈은, 픽셀에 대한 스텐실 테스트를 실행하기 전에, 스텐실 참조값과 스텐실 마스크값의 비트적을 계산한다. 다음에, 그 결과가, 스텐실 비교 함수를 사용해 스텐실 버퍼의 내용이라고 비교된다. 어플리케이션에서는 이 스텐실 마스크를 설정할 수 있다. IDirect3DDevice7::SetRenderState 메소드를 사용해, 제 1 파라미터의 값으로서 D3DRENDERSTATE_STENCILMASK 를 건네준다. 제 2 파라미터를 새로운 스텐실 마스크로 설정한다.

스텐실 테스트가 실패했을 때의 Direct3D 의 처리를 설정하려면 ,IDirect3DDevice7::SetRenderState 메소드를 호출해, 제 1 파라미터로서 D3DRENDERSTATE_STENCILFAIL 를 건네준다. 제 2 파라미터는 D3DSTENCILOP 열거형의 멤버가 아니면 안된다.

또, 스텐실 테스트는 성공했지만 z 버퍼 테스트가 실패했을 때의 Direct3D 의 처리도 어플리케이션으로 제어할 수 있다. IDirect3DDevice7::SetRenderState 메소드를 호출해, 제 1 파라미터로서 D3DRENDERSTATE_STENCILZFAIL 를 건네주어, 제 2 파라미터에 D3DSTENCILOP 열거형의 멤버를 설정한다.

게다가 스텐실 테스트와 z 버퍼 테스트의 양쪽 모두가 성공했을 때의 Direct3D 의 처리도 제어할 수 있다. IDirect3DDevice7::SetRenderState 메소드를 호출해, 제 1 파라미터로서 D3DRENDERSTATE_STENCILPASS 를 건네준다. 이 경우도, 제 2 파라미터는 D3DSTENCILOP 열거형의 멤버가 아니면 안된다.

[Visual Basic]

Visual Basic 로 스텐실 처리를 유효 또는 무효로 하려면 ,Direct3DDevice7.SetRenderState 메소드를 호출한다. 제 1 파라미터의 값으로서 D3DRENDERSTATE_STENCILENABLE 를 건네준다. 스텐실 처리를 유효하게 하려면 제 2 파라미터의 값을 True 로 설정해, 무효로 하려면 False 로 설정한다.

Direct3D 의 스텐실 테스트로 사용하는 비교 함수는,Direct3DDevice7::SetRenderState 메소드를 호출해 설정한다. 제 1 파라미터의 값을 D3DRENDERSTATE_STENCILFUNC 로 설정한다. 제 2 파라미터의 값으로서 CONST_D3DCMPFUNC 열거형의 멤버를 건네준다.

스텐실 참조값이란, 스텐실 함수가 테스트에 사용하는, 스텐실 버퍼내의 값이다. 디폴트에서는 스텐실 참조값은 제로이다. 어플리케이션에서는,Direct3DDevice7.SetRenderState 메소드를 호출해 이 값을 설정할 수 있다. 제 1 파라미터의 값으로서 D3DRENDERSTATE_STENCILREF 를 건네준다. 제 2 파라미터의 값에는 새로운 참조값으로 설정한다.

Direct3D 모듈은, 픽셀에 대한 스텐실 테스트를 실행하기 전에, 스텐실 참조값과 스텐실 마스크값의 비트적을 계산한다. 다음에, 그 결과가, 스텐실 비교 함수를 사용해 스텐실 버퍼의 내용이라고 비교된다. 어플리케이션에서는,D3DRENDERSTATE_STENCILMASK 렌더링 스테이트를 호출해, 이 스텐실 마스크를 설정할 수 있다. 렌더링 스테이트값을 새로운 스텐실 마스크로 설정한다.

스텐실 테스트가 실패했을 때의 Direct3D 의 처리를 설정하려면 ,Direct3DDevice7::SetRenderState 메소드를 호출해, 제 1 파라미터로서 D3DRENDERSTATE_STENCILFAIL 를 건네준다. 제 2 파라미터는 CONST_D3DSTENCILOP 열거의 멤버가 아니면 안된다.

또, 스텐실 테스트는 성공했지만 z 버퍼 테스트가 실패했을 때의 Direct3D 의 처리도 어플리케이션으로 제어할 수 있다. Direct3DDevice7::SetRenderState 메소드를 호출해, 제 1 파라미터로서 D3DRENDERSTATE_STENCILZFAIL 를 건네주어, 제 2 파라미터에 D3DSTENCILOP 열거의 멤버를 설정한다.

게다가 스텐실 테스트와 z 버퍼 테스트의 양쪽 모두가 성공했을 때의 Direct3D 의 처리도 제어할 수 있다. Direct3DDevice7::SetRenderState 메소드를 사용해, 제 1 파라미터로서 D3DRENDERSTATE_STENCILPASS 를 건네준다. 이 경우도, 제 2 파라미터는 D3DSTENCILOP 열거의 멤버가 아니면 안된다.


라이트의 종류

[C++]

라이트의 종류 프로퍼티는, 사용하는 광원의 종류를 정의한다. C++ 의 경우, 라이트의 종류는, 라이트의 D3DLIGHT7 구조체의 dltType 멤버에 D3DLIGHTTYPE 열거로부터의 값을 사용해 설정한다. Direct3D 직접 모드에서는, 포인트 라이트, spotlight, 및 디렉셔널 라이트의 3 종류의 라이트가 있다. 라이트의 종류 마다, 장면내의 오브젝트의 비추는 방법이 달라, 계산에 있어서의 오버헤드의 레벨도 다르다. 각 라이트의 작용에 관한 일반적인 정보에 대해서는, 「라이트 오브젝트의 개요」를 참조할것.

[Visual Basic]

라이트의 종류 프로퍼티는, 사용하는 광원의 종류를 정의한다. Visual Basic 의 경우, 라이트의 종류는, 라이트의 D3DLIGHT7 형의 dltType 멤버에 CONST_D3DLIGHTTYPE 열거로부터의 값을 사용해 설정한다. Direct3D 직접 모드에서는, 포인트 라이트, spotlight, 및 디렉셔널 라이트의 3 종류의 라이트가 있다. 라이트의 종류 마다, 장면내의 오브젝트의 비추는 방법이 달라, 계산에 있어서의 오버헤드의 레벨도 다르다. 각 라이트의 작용에 관한 일반적인 정보에 대해서는, 「라이트 오브젝트의 개요」를 참조할것.


프리미티브의 종류

Direct3D 에서는, 이하의 종류의 프리미티브를 생성 및 조작할 수 있다.

  • 점리스트
  • 선리스트
  • 선스트립
  • 삼각형 리스트
  • 삼각형 스트립
  • 삼각형 팬
[C++]

C++ 어플리케이션에서는,IDirect3DDevice7 인터페이스의 렌더링 메소드를 사용해, 이러한 종류의 프리미티브를 렌더링 할 수 있다. 상세한 것에 대하여는, 「렌더링」을 참조할것 (인덱스 첨부 프리미티브 렌더링 메소드를 사용해, 점리스트를 렌더링 할 수 없다).

[Visual Basic]

Visual Basic 어플리케이션에서는,Direct3DDevice7 인터페이스의 렌더링 메소드를 사용해, 이것들 모든 종류의 프리미티브를 렌더링 할 수 있다. 상세한 것에 대하여는, 「렌더링」을 참조할것.


사전 정의하는 스테이트 블록의 생성

[C++]

IDirect3DDevice7::CreateStateBlock 메소드는, 디바이스 스테이트 세트의 전체를 포함하든가, 혹은 버텍스 또는 픽셀 처리에 관한 디바이스 스테이트만 포함한 새로운 스테이트 블록을 생성 한다. CreateStateBlock 메소드는 2 개의 파라미터를 받는다. 제 1 파라미터는, 새로운 스테이트 블록에 수중에 넣는 스테이트 정보의 종류를 식별한다. 제 2 파라미터는, 호출이 성공했을 때에 유효한 스테이트 블록 핸들을 받는 변수의 주소이다.

제 1 파라미터의 유효값은,D3DSTATEBLOCKTYPE 열거형으로 정의된다. 이것에 포함되는 멤버를 사용해, 디바이스 스테이트 세트의 전체 (D3DSBT_ALL), 혹은 점 또는 픽셀 처리 (D3DSBT_VERTEX 또는 D3DSBT_PIXEL)에 관한 스테이트만 수중에 넣을 수가 있다. 다음의 일람은, D3DSBT_VERTEX 또는 D3DSBT_PIXEL 값을 건네주었을 때에 시스템에 의해 받아들여지는 스테이트를 나타낸다.

  • 버텍스 관련의 스테이트 (D3DSBT_VERTEX)

    모든 라이팅의 스테이트 (유효 또는 무효)

    트랜스 폼행예

    유저 정의 클립면

    이하의 렌더링 스테이트에 대한 설정값
    D3DRENDERSTATE_AMBIENT

    D3DRENDERSTATE_AMBIENTMATERIALSOURCE

    D3DRENDERSTATE_CLIPPING

    D3DRENDERSTATE_CLIPPLANEENABLE

    D3DRENDERSTATE_COLORVERTEX

    D3DRENDERSTATE_CULLMODE

    D3DRENDERSTATE_DIFFUSEMATERIALSOURCE

    D3DRENDERSTATE_EMISSIVEMATERIALSOURCE

    D3DRENDERSTATE_EXTENTS

    D3DRENDERSTATE_FOGCOLOR

    D3DRENDERSTATE_FOGDENSITY

    D3DRENDERSTATE_FOGENABLE

    D3DRENDERSTATE_FOGEND

    D3DRENDERSTATE_FOGSTART

    D3DRENDERSTATE_FOGTABLEMODE

    D3DRENDERSTATE_FOGVERTEXMODE

    D3DRENDERSTATE_LIGHTING

    D3DRENDERSTATE_LOCALVIEWER

    D3DRENDERSTATE_NORMALIZENORMALS

    D3DRENDERSTATE_RANGEFOGENABLE

    D3DRENDERSTATE_SHADEMODE

    D3DRENDERSTATE_SPECULARENABLE

    D3DRENDERSTATE_SPECULARMATERIALSOURCE

    D3DRENDERSTATE_VERTEXBLEND

    이하의 텍스쳐 스테이지 스테이트에 대한 설정값
    D3DTSS_TEXCOORDINDEX

    D3DTSS_TEXTURETRANSFORMFLAGS

  • 픽셀 관련의 스테이트 (D3DSBT_PIXEL)
    이하의 렌더링 스테이트에 대한 설정값
    D3DRENDERSTATE_ALPHABLENDENABLE

    D3DRENDERSTATE_ALPHAFUNC

    D3DRENDERSTATE_ALPHAREF

    D3DRENDERSTATE_ALPHATESTENABLE

    D3DRENDERSTATE_ANTIALIAS

    D3DRENDERSTATE_COLORKEYBLENDENABLE

    D3DRENDERSTATE_COLORKEYENABLE

    D3DRENDERSTATE_DESTBLEND

    D3DRENDERSTATE_DITHERENABLE

    D3DRENDERSTATE_EDGEANTIALIAS

    D3DRENDERSTATE_FILLMODE

    D3DRENDERSTATE_FOGDENSITY

    D3DRENDERSTATE_FOGEND

    D3DRENDERSTATE_FOGSTART

    D3DRENDERSTATE_LASTPIXEL

    D3DRENDERSTATE_LINEPATTERN

    D3DRENDERSTATE_SHADEMODE

    D3DRENDERSTATE_SRCBLEND

    D3DRENDERSTATE_STENCILENABLE

    D3DRENDERSTATE_STENCILFAIL

    D3DRENDERSTATE_STENCILFUNC

    D3DRENDERSTATE_STENCILMASK

    D3DRENDERSTATE_STENCILPASS

    D3DRENDERSTATE_STENCILREF

    D3DRENDERSTATE_STENCILWRITEMASK

    D3DRENDERSTATE_STENCILZFAIL

    D3DRENDERSTATE_STIPPLEDALPHA

    D3DRENDERSTATE_TEXTUREFACTOR

    D3DRENDERSTATE_TEXTUREPERSPECTIVE

    D3DRENDERSTATE_WRAP0 ~ D3DRENDERSTATE_WRAP7

    D3DRENDERSTATE_ZBIAS

    D3DRENDERSTATE_ZENABLE

    D3DRENDERSTATE_ZFUNC

    D3DRENDERSTATE_ZWRITEENABLE

    이하의 텍스쳐 스테이지 스테이트에 대한 설정값
    D3DTSS_ADDRESS

    D3DTSS_ADDRESSU

    D3DTSS_ADDRESSV

    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

[Visual Basic]

Direct3DDevice7.CreateStateBlock 메소드는, 디바이스 스테이트 세트의 전체를 포함하는지, 또는 버텍스 또는 픽셀 처리에 관한 디바이스 스테이트만 포함한 새로운 스테이트 블록을 생성 한다. CreateStateBlock 메소드는 2 개의 파라미터를 받는다. 제 1 파라미터는, 새로운 스테이트 블록에 수중에 넣는 스테이트 정보의 종류를 식별한다. 제 2 파라미터는, 호출이 성공했을 때에 유효한 스테이트 블록 핸들을 받는 변수의 주소이다.

제 1 파라미터의 유효값은,CONST_D3DSTATEBLOCKTYPE 열거로 정의된다. 이 열거에 포함되는 멤버를 사용해, 디바이스 스테이트 세트의 전체 (D3DSBT_ALL), 혹은 점 또는 픽셀 처리 (D3DSBT_VERTEX 또는 D3DSBT_PIXEL)에 관한 스테이트만 수중에 넣을 수가 있다. 다음의 일람은, D3DSBT_VERTEX 또는 D3DSBT_PIXEL 값을 건네주었을 때에 시스템에 의해 받아들여지는 스테이트를 나타낸다.

  • 버텍스 관련의 스테이트 (D3DSBT_VERTEX)

    모든 라이팅의 스테이트 (유효 또는 무효)

    트랜스 폼행예

    유저 정의 클립면

    이하의 렌더링 스테이트에 대한 설정값
    D3DRENDERSTATE_AMBIENT

    D3DRENDERSTATE_AMBIENTMATERIALSOURCE

    D3DRENDERSTATE_CLIPPING

    D3DRENDERSTATE_CLIPPLANEENABLE

    D3DRENDERSTATE_COLORVERTEX

    D3DRENDERSTATE_CULLMODE

    D3DRENDERSTATE_DIFFUSEMATERIALSOURCE

    D3DRENDERSTATE_EMISSIVEMATERIALSOURCE

    D3DRENDERSTATE_EXTENTS

    D3DRENDERSTATE_FOGCOLOR

    D3DRENDERSTATE_FOGDENSITY

    D3DRENDERSTATE_FOGENABLE

    D3DRENDERSTATE_FOGEND

    D3DRENDERSTATE_FOGSTART

    D3DRENDERSTATE_FOGTABLEMODE

    D3DRENDERSTATE_FOGVERTEXMODE

    D3DRENDERSTATE_LIGHTING

    D3DRENDERSTATE_LOCALVIEWER

    D3DRENDERSTATE_NORMALIZENORMALS

    D3DRENDERSTATE_RANGEFOGENABLE

    D3DRENDERSTATE_SHADEMODE

    D3DRENDERSTATE_SPECULARENABLE

    D3DRENDERSTATE_SPECULARMATERIALSOURCE

    D3DRENDERSTATE_VERTEXBLEND

    이하의 텍스쳐 스테이지 스테이트에 대한 설정값
    D3DTSS_TEXCOORDINDEX

    D3DTSS_TEXTURETRANSFORMFLAGS

  • 픽셀 관련의 스테이트 (D3DSBT_PIXEL)
    이하의 렌더링 스테이트에 대한 설정값
    D3DRENDERSTATE_ALPHABLENDENABLE

    D3DRENDERSTATE_ALPHAFUNC

    D3DRENDERSTATE_ALPHAREF

    D3DRENDERSTATE_ALPHATESTENABLE

    D3DRENDERSTATE_ANTIALIAS

    D3DRENDERSTATE_COLORKEYBLENDENABLE

    D3DRENDERSTATE_COLORKEYENABLE

    D3DRENDERSTATE_DESTBLEND

    D3DRENDERSTATE_DITHERENABLE

    D3DRENDERSTATE_EDGEANTIALIAS

    D3DRENDERSTATE_FILLMODE

    D3DRENDERSTATE_FOGDENSITY

    D3DRENDERSTATE_FOGEND

    D3DRENDERSTATE_FOGSTART

    D3DRENDERSTATE_LASTPIXEL

    D3DRENDERSTATE_LINEPATTERN

    D3DRENDERSTATE_SHADEMODE

    D3DRENDERSTATE_SRCBLEND

    D3DRENDERSTATE_STENCILENABLE

    D3DRENDERSTATE_STENCILFAIL

    D3DRENDERSTATE_STENCILFUNC

    D3DRENDERSTATE_STENCILMASK

    D3DRENDERSTATE_STENCILPASS

    D3DRENDERSTATE_STENCILREF

    D3DRENDERSTATE_STENCILWRITEMASK

    D3DRENDERSTATE_STENCILZFAIL

    D3DRENDERSTATE_STIPPLEDALPHA

    D3DRENDERSTATE_TEXTUREFACTOR

    D3DRENDERSTATE_TEXTUREPERSPECTIVE

    D3DRENDERSTATE_WRAP0 ~ D3DRENDERSTATE_WRAP7

    D3DRENDERSTATE_ZBIAS

    D3DRENDERSTATE_ZENABLE

    D3DRENDERSTATE_ZFUNC

    D3DRENDERSTATE_ZWRITEENABLE

    이하의 텍스쳐 스테이지 스테이트에 대한 설정값
    D3DTSS_ADDRESS

    D3DTSS_ADDRESSU

    D3DTSS_ADDRESSV

    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 메소드가 돌려주는 에러 코드를 체크하는 것이 중요하다. 이 메소드가 실패했을 경우, 그 원인의 상당수는 디스플레이 모드가 변경된 것인 생각된다 (에러 코드 DDERR_SURFACELOST). 어플리케이션의 표면을 생성 다시 해 스테이트 블록을 기록하는 것으로, 이러한 장해로부터 어플리케이션이 회복하도록(듯이) 설계한다.


텍스쳐 블렌딩 처리와 인수

어플리케이션에서는, 블렌딩 스테이지를 현재 텍스쳐 세트의 각 텍스쳐에 관련짓는다. 「텍스쳐 스테이지와 텍스쳐 블렌딩 cascade」로 설명하도록(듯이),Direct3D 에서는, 세트의 최초의 텍스쳐로부터 순서에 8 번째의 텍스쳐까지 각 블렌딩 스테이지를 평가한다.

[C++]

Direct3D 에서는, 현재 텍스쳐 세트의 각 텍스쳐의 정보를, 관련지을 수 있고 있는 블렌딩 스테이지에 적용한다. 어플리케이션에서는,IDirect3DDevice7::SetTextureStageState 를 호출해, 소정의 텍스쳐 스테이지로부터 어느 정보를 사용하는지를 제어한다. 색채널과 알파 채널의 처리는, 개별적으로 설정할 수가 있다. 각 처리에서는 2 개의 인수를 사용한다. 색채널 처리를 지정하려면 , D3DTSS_COLOROP 스테이지 스테이트를 사용해, 알파 처리를 지정하려면 , D3DTSS_ALPHAOP 스테이지 스테이트를 사용한다. 이것들은 함께,D3DTEXTUREOP 열거형으로부터의 값을 사용한다.

텍스쳐 블렌딩 인수에는,D3DTEXTURESTAGESTATETYPE 열거형의 D3DTSS_COLORARG1, D3DTSS_COLORARG2, D3DTSS_ALPHARG1, 및 D3DTSS_ALPHARG2 멤버를 사용한다. 대응하는 인수는,텍스쳐 인수 플래그를 사용해 식별한다.

주 : 있는 텍스쳐 스테이지의 색처리를 D3DTOP_DISABLE 로 설정하는 것으로, 그 텍스쳐 스테이지와 거기에 계속되는 cascade내의 텍스쳐 블렌딩 스테이지를 무효로 할 수 있다. 색처리를 무효 하면, 알파 처리도 이와 같이 무효가 된다. 색처리가 유효하게 되어 있을 때, 알파 처리를 무효로 하는 것은 할 수 없다. 색블렌딩이 유효한 경우에 알파 처리를 D3DTOP_DISABLE 로 설정 하면, 부정의 처리가 발생한다.

디바이스로 지원 되고 있는 텍스쳐 블렌딩 처리를 조사하는,D3DDEVICEDESC7 구조체의 dwTextureOpCaps 멤버에 문의한다.

[Visual Basic]

Direct3D 에서는, 현재 텍스쳐 세트의 각 텍스쳐의 정보를, 관련지을 수 있고 있는 블렌딩 스테이지에 적용한다. 어플리케이션에서는,Direct3DDevice7.SetTextureStageState 를 호출해, 소정의 텍스쳐 스테이지로부터 어느 정보를 사용하는지를 제어한다. 색채널과 알파 채널의 처리는, 개별적으로 설정할 수가 있다. 각 처리에서는 2 개의 인수를 사용한다. 색채널 처리를 지정하려면 , D3DTSS_COLOROP 스테이지 스테이트를 사용해, 알파 처리를 지정하려면 , D3DTSS_ALPHAOP 스테이지 스테이트를 사용한다. 이것들은 함께,CONST_D3DTEXTUREOP 열거로부터의 값을 사용한다.

텍스쳐 블렌딩 인수에는,CONST_D3DTEXTURESTAGESTATETYPE 열거의 D3DTSS_COLORARG1, D3DTSS_COLORARG2, D3DTSS_ALPHARG1, 및 D3DTSS_ALPHARG2 멤버를 사용한다. 대응하는 인수는,텍스쳐 인수 플래그를 사용해 식별한다.

주 : 있는 텍스쳐 스테이지의 색처리를 D3DTOP_DISABLE 로 설정하는 것으로, 그 텍스쳐 스테이지와 거기에 계속되는 cascade내의 텍스쳐 블렌딩 스테이지를 무효로 할 수 있다. 색처리를 무효 하면, 알파 처리도 이와 같이 무효가 된다. 색처리가 유효하게 되어 있을 때는, 알파 처리를 무효로 하는 것은 할 수 없다. 색블렌딩이 유효한 경우에 알파 처리를 D3DTOP_DISABLE 로 설정 하면, 부정의 처리가 발생한다.

디바이스로 지원 되고 있는 텍스쳐 블렌딩 처리를 조사하려면 ,D3DDEVICEDESC7 형의 lTextureOpCaps 멤버에 문의한다.


라이트의 색

Direct3D 의 라이트는, 시스템에 의한 라이팅 계산으로 독립해 사용되는, 디퓨즈색, 앰비언트색, 및 스펙큐러색의 3 개의 색을 방사한다. 각각의 색은, Direct3D 라이팅 모듈에 의해 짜넣어져 현재의 머트리얼의 색과 상호작용 해, 최종적으로 렌더링으로 사용되는 색이 생성된다. 디퓨즈색은 현재의 머트리얼의 디퓨즈 프로퍼티와 상호작용 해, 스펙큐러색은 머트리얼의 스펙큐러 속성과 상호작용 한다, 라고 하는 상태에 처리된다 (Direct3D 에서의 이러한 색의 적용 방법에 대해서는, 「Direct3D 의 라이팅에 있어서의 수학적 계산」을 참조할것).

[C++]

C++ 어플리케이션의 경우,D3DLIGHT7 구조체에 이러한 색을 나타내는 3 개의 멤버 dcvDiffuse,dcvAmbient, 및 dcvSpecular 가 포함된다. 각 멤버는, 방사하는 색을 정의하는 D3DCOLORVALUE 구조체이다.

[Visual Basic]

Visual Basic 의 경우,D3DLIGHT7 형에 이러한 색을 나타내는 3 개의 멤버 dcvDiffuse,dcvAmbient, 및 dcvSpecular 가 포함된다. 각 멤버는, 방사하는 색을 정의하는 D3DCOLORVALUE 형이다.

시스템의 계산 부하가 가장 큰 것은, 디퓨즈색이다. 가장 일반적인 디퓨즈색은 백색 (R:1. 0 G:1. 0 B:1. 0)이지만, 희망의 이펙트를 내기 위해서(때문에) 필요에 따라서 색을 생성 할 수 있다. 예를 들어, 난로에 적색의 라이트를 사용하거나"Go" 가 된 교통신호에 녹색을 사용할 수가 있다.

일반적으로는, 라이트의 색성분을 0.0 으로 1.0 을 포함한 0.0 ~ 1.0 의 값으로 설정하지만, 이외의 값으로 설정할 수도 있다. 예를 들어, 모든 성분을 2.0 으로 설정해,"백색보다 밝은" 라이트를 생성 할 수 있다. 이러한 설정은, 정수 이외의 감쇠 설정을 사용할때에는 특히 편리하다.

Direct3D 에서는 라이트로 RGBA 값을 사용하지만, 알파 성분은 사용하지 않는다. 상세한 것에 대하여는, 「라이팅과 머트리얼의 컬러값」을 참조할것.


픽셀 포그(안개:fog)에 대해

픽셀 포그(안개:fog)라는 이름은, 디바이스 드라이버로 픽셀 단위에 계산이 실행되는 것으로부터 붙어 있다 (이것은 버텍스 포그(안개:fog)와는 다르다. 버텍스 포그(안개:fog)의 경우, Direct3D 는 트랜스 폼 & 라이팅의 실행 시에 포그(안개:fog) 이펙트를 계산한다). 드라이버가 블렌딩 계산에 적용하는 포그(안개:fog) 계수 ( 각 픽셀의 깊이를 사용)를 결정하기 위해서(때문에) 사전에 계산된 룩 업 테이블을 사용하기 위해(때문에), 픽셀 포그(안개:fog)는, 「테이블 포그(안개:fog)」라고 불리는 일도 있다.

[C++]

픽셀 포그(안개:fog)는,D3DFOGMODE 열거형의 멤버에 의해 식별되는 포그(안개:fog) 공식의 어느쪽이든을 사용해 적용한다. 픽셀 포그(안개:fog) 공식의 이행은 드라이버 고유하고, 드라이버가 복잡한 포그(안개:fog) 공식을 지원 하고 있지 않는 경우는, 그다지 복잡하지 않은 공식을 사용하는 것.

[Visual Basic]

픽셀 포그(안개:fog)는,CONST_D3DFOGMODE 열거의 멤버로 식별하는 포그(안개:fog) 공식의 어느쪽이든을 사용해 적용할 수 있다. 픽셀 포그(안개:fog) 공식의 이행은 드라이버 고유하고, 드라이버가 복잡한 포그(안개:fog) 공식을 지원 하고 있지 않는 경우는, 그다지 복잡하지 않은 공식을 사용하는 것.

주 : 「범위 베이스의 포그(안개:fog)」로 설명하도록(듯이), 픽셀 포그(안개:fog)는 범위 베이스의 계산에서는 실행되지 않는다.


버텍스의 메뉴얼 트랜스 폼

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

[C++]
트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스
어플리케이션으로 라이팅도 트랜스 폼도 적용하지 않는 버텍스. 장면을 렌더링 하기 전에 버텍스에 트랜스 폼 & 라이팅을 적용하지 않는 C++ 어플리케이션에서는,D3DVERTEX 버텍스 (또는 동등의 유연한 버텍스 포맷)를 사용할 수 있다. 라이팅 파라미터나 트랜스 폼 행렬을 지정해도, 계산은 Direct3D 가 실행한다.
트랜스폼 되지 않은 라이팅 끝난 버텍스
어플리케이션으로 라이팅은 적용하지만, 트랜스 폼은 적용하지 않는 버텍스. 커스터마이즈 한 라이팅 이펙트를 사용하는 C++ 어플리케이션에서는,D3DLVERTEX 버텍스 (또는 동등의 유연한 버텍스 포맷)를 사용할 수 있다.
트랜스 폼이 끝난 라이팅 끝난 버텍스
어플리케이션으로 라이팅과 트랜스 폼의 양쪽 모두를 적용하는 버텍스. 버텍스에 라이팅과 트랜스 폼을 적용하는 C++ 어플리케이션에서는,D3DTLVERTEX 버텍스 (또는 동등의 유연한 버텍스 포맷)를 사용할 수 있다. 이러한 버텍스는 지오메트리 파이프라인으로 트랜스 폼 되지 않지만, 필요에 따라서 시스템으로 클리핑 할 수가 있다. 어플리케이션 자체로 버텍스를 클리핑 하는 경우에 가장 좋은 방법은, 렌더링 메소드를 호출하면나무에 D3DDP_DONOTCLIP 플래그를 지정하는 것이다. Direct3D 로 버텍스를 클리핑 하는 경우는, D3DDP_DONOTCLIP 플래그는 지정하지 않는다. 다만, 트랜스 폼이 끝난 라이팅 끝난 버텍스의 클리핑을 Direct3D 로 실행하는 경우, Direct3D 는 클리핑을 위해서(때문에) 버텍스를 투영 공간에 역변환하고 나서 스크린 공간다시 로 변환하기 (위해)때문에 , 처리 오버헤드가 생기는 것에 주의한다.

DirectX 7.0 에서는, 버텍스 버퍼를 사용해, 단순한 버텍스 타입을 복잡한 버텍스 타입으로 바꿀 수가 있다 ( 구릴리스의 DirectX 에서는, 어플리케이션으로 IDirect3DViewport3 인터페이스의 TransformVertices 메소드를 호출할 수가 있었다. DirectX 6.0 으로 버텍스 버퍼가 도입된 것에 의해, 이 메소드는 사용되지 않게 되었다). 버텍스 버퍼란, 고속의 렌더링을 실행하기 위해서 버텍스를 정리해 저장 해 배치처리하기 위한 오브젝트로, 프로세서 고유의 기능을 이용하도록(듯이) 최적화할 수 있다. 버텍스 버퍼에는, 자동적으로 버텍스 트랜스 폼을 실행하는 IDirect3DVertexBuffer7::ProcessVertices 및 IDirect3DVertexBuffer7::ProcessVerticesStrided 메소드가 있다. 이 메소드는, 보통 TransformVertices 메소드보다 아득하게 처리가 빠르다. ProcessVertices 패밀리의 메소드는 트랜스폼 되지 않은의 버텍스만 받지만, 옵션으로서 버텍스에의 라이팅의 적용과 클리핑이 가능하다. 라이팅은 ProcessVertices 를 호출했을 때에 적용되지만, 클리핑이 실행되는 것은 렌더링 때이다.

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

[Visual Basic]
트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스
어플리케이션으로 라이팅과 트랜스 폼을 적용하지 않는 버텍스. 장면을 렌더링 하기 전에 버텍스에 트랜스 폼 & 라이팅을 적용하지 않는 Visual Basic 어플리케이션에서는,D3DVERTEX 버텍스 (또는 동등의 유연한 버텍스 포맷)를 사용할 수 있다. 라이팅 파라미터나 트랜스 폼 행렬을 지정해도, 계산은 Direct3D 가 실행한다.
트랜스폼 되지 않은 라이팅 끝난 버텍스
어플리케이션으로 라이팅은 적용하지만, 트랜스 폼은 적용하지 않는 버텍스. 커스터마이즈 한 라이팅 이펙트를 사용하는 Visual Basic 어플리케이션에서는,D3DLVERTEX 버텍스 (또는 동등의 유연한 버텍스 포맷)를 사용할 수 있다.
트랜스 폼이 끝난 라이팅 끝난 버텍스
어플리케이션으로 라이팅과 트랜스 폼의 양쪽 모두를 적용하는 버텍스. 버텍스에 라이팅과 트랜스 폼을 적용하는 Visual Basic 어플리케이션에서는,D3DTLVERTEX 버텍스 (또는 동등의 유연한 버텍스 포맷)를 사용할 수 있다. 이러한 버텍스는 지오메트리 파이프라인으로 트랜스 폼 되지 않지만, 필요에 따라서 시스템으로 클리핑 할 수가 있다. 어플리케이션 자체로 버텍스를 클리핑 하는 경우에 가장 좋은 방법은, 렌더링 메소드를 호출하면나무에 D3DDP_DONOTCLIP 플래그를 지정하는 것이다. Direct3D 로 버텍스를 클리핑 하는 경우는, D3DDP_DONOTCLIP 플래그는 지정하지 않는다. 다만, 트랜스 폼이 끝난 라이팅 끝난 버텍스의 클리핑을 Direct3D 로 실행하는 경우, Direct3D 는 클리핑을 위해서(때문에) 버텍스를 투영 공간에 역변환하고 나서 스크린 공간다시 로 변환하기 (위해)때문에 , 처리 오버헤드가 생기는 것에 주의한다.

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

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


스테이트 블록의 삭제

[C++]

IDirect3DDevice7::DeleteStateBlock 는, 기존의 스테이트 블록을 삭제해, 이 스테이트 블록으로 사용한 메모리의 할당을 해제한다. DeleteStateBlock 메소드에는, 그 파라미터에서만 삭제하는 스테이트 블록에의 핸들을 받는다. 스테이트 블록을 삭제 하면, 그 스테이트 블록에의 핸들은 무효가 되어, 이후 사용할 수 없다.

[Visual Basic]

Direct3DDevice7.DeleteStateBlock 는, 기존의 스테이트 블록을 삭제해, 이 스테이트 블록으로 사용한 메모리의 할당을 해제한다. DeleteStateBlock 메소드에는, 그 파라미터에서만 삭제하는 스테이트 블록에의 핸들을 받는다. 스테이트 블록을 삭제 하면, 그 스테이트 블록에의 핸들은 무효가 되어, 이후 사용할 수 없다.


경계색텍스쳐 addressing mode에 대해

[C++]

D3DTEXTUREADDRESS 열거형의 D3DTADDRESS_BORDER 멤버로 지정하는 "경계색" 텍스쳐 addressing mode에서는, Direct3D 는 0.0 으로 1.0 을 포함한 0.0 ~ 1.0 의 범위외의 모든 텍스쳐 좌표에 대해서, 경계색으로 불리는 임의의 색을 사용한다.

[Visual Basic]

CONST_D3DTEXTUREADDRESS 열거의 D3DTADDRESS_BORDER 멤버로 지정하는 "경계색" 텍스쳐 addressing mode에서는, Direct3D 는 0.0 으로 1.0 을 포함한 0.0 ~ 1.0 의 범위외의 모든 텍스쳐 좌표에 대해서, 경계색으로 불리는 임의의 색을 사용한다.

다음의 그림에 이 처리를 나타낸다. 이 그림에서는, 어플리케이션은 적색의 경계색을 사용해 텍스쳐를 원시적으로 적용하도록(듯이) 지정하고 있다.

[C++]

어플리케이션에서는,IDirect3DDevice7::SetTextureStageState 를 호출해 경계색을 설정한다. 이 호출의 제 1 파라미터에는 희망의 텍스쳐 스테이지 식별자를 설정해, 제 2 파라미터에는 D3DTSS_BORDERCOLOR 스테이지 스테이트값을 설정해, 제 3 파라미터에는 새로운 RGBA 경계색을 설정한다.

종래의 IDirect3DDevice2 인터페이스를 사용하는 경우, 경계색을 설정하려면 ,IDirect3DDevice2::SetRenderState 메소드를 호출해, D3DRENDERSTATE_BORDERCOLOR 렌더링 스테이트값과 새로운 RGBA 경계색을 파라미터로서 지정한다 (D3DRENDERSTATE_BORDERCOLOR 렌더링 스테이트는, 현재는 사용되어 있지 않기 때문에,IDirect3DDevice7 인터페이스에서는 인식되지 않는다).

[Visual Basic]

Visual Basic 어플리케이션에서는,Direct3DDevice7.SetTextureStageState 를 호출해 경계색을 설정한다. 이것을 호출하면나무의 제 1 파라미터에는 희망의 텍스쳐 스테이지 식별자를 설정해, 제 2 파라미터에는 D3DTSS_BORDERCOLOR 스테이지 스테이트값을 설정해, 제 3 파라미터에는 새로운 RGBA 경계색을 설정한다.


스펙큐러 반사 모델

[C++]

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

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

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

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

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

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

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

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

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

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

[Visual Basic]

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

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

이 방법으로 중간 벡터를 결정하는 경우, 얼마인가의 계산 부하가 걸린다. 다른 방법으로서는, D3DRENDERSTATE_LOCALVIEWER 를 False 로 설정한다. 이 경우, z 축의 무한 먼 곳에 시점이 존재 하면 해 처리된다. 이 설정은 계산 부하는 적지만, 정확함으로 뒤떨어진다. 따라서, 이 방법은, 정사영을 사용하는 어플리케이션에 최적이다. D3DRENDERSTATE_LOCALVIEWER 를 False, Direct3D 로 설정했을 경우, Direct3D 에서는 다음의 공식을 사용해 중간 벡터를 계산한다.

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

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

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

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

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

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

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


범프 맵핑 파라미터의 설정

어플리케이션으로 범프 맵의 생성과 각 픽셀의 내용의 설정이 완료하면(자), 범프 맵핑 파라미터를 설정해 렌더링의 준비를 실시할 수가 있다. 범프 맵핑 파라미터에는, 필요한 텍스쳐와 그 블렌딩 처리나, 범프 맵 자체에 대한 트랜스 폼과 휘도(Luminance)의 제어등을 설정한다.

[C++]

C++ 로 범프 맵핑 파라미터를 설정하려면:

  1. 베이스 텍스쳐 맵 (사용되고 있는 경우), 범프 맵, 및 환경 맵 텍스쳐를 텍스쳐 블렌딩 스테이지로 설정한다.
  2. 각 텍스쳐 스테이지의 색 및 알파 블렌딩 처리를 설정한다.
  3. 범프 맵 트랜스 폼 행렬을 설정한다.
  4. 필요에 따라서, 휘도(Luminance) 스케일값 및 오프셋(offset)값을 설정한다.

다음의 코드에서는, 베이스 텍스쳐 맵, 범프 맵, 및 스펙큐러 환경 맵의 3 개의 텍스쳐를, 적절한 텍스쳐 블렌딩 스테이지로 설정한다.

// 3 개의 텍스쳐를 설정한다.
    g_pd3dDevice->SetTexture( 0, lpd3dBaseTexture);
    g_pd3dDevice->SetTexture( 1, lpd3dBumpMap);
    g_pd3dDevice->SetTexture( 2, lpd3dEnvMap);

텍스쳐를 블렌딩 스테이지로 설정한 후, 다음의 코드로, 각 스테이지의 블렌딩 처리 및 인수를 준비한다.

    //
// 색처리 및 인수를 설정해 범프 맵핑을 준비한다.
    //

// 스테이지 0:베이스 텍스쳐
    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_SELECTARG1 );
    g_pd3dDevice->SetTextureStageState( 0, D3DTSS_ALPHAARG1, D3DTA_TEXTURE );
    g_pd3dDevice->SetTextureStageState( 0, D3DTSS_TEXCOORDINDEX, 1 );

// 스테이지 1:범프 맵
    g_pd3dDevice->SetTextureStageState( 1, D3DTSS_TEXCOORDINDEX, 1 );
// 이 예에서는 휘도(Luminance)를 사용한다.
    g_pd3dDevice->SetTextureStageState( 1, D3DTSS_COLOROP, D3DTOP_BUMPENVMAPLUMINANCE);
    g_pd3dDevice->SetTextureStageState( 1, D3DTSS_COLORARG1, D3DTA_TEXTURE );
    g_pd3dDevice->SetTextureStageState( 1, D3DTSS_COLORARG2, D3DTA_CURRENT );

// 스테이지 2:스펙큐러 환경 맵
    g_pd3dDevice->SetTextureStageState( 2, D3DTSS_TEXCOORDINDEX, 0 );
    g_pd3dDevice->SetTextureStageState( 2, D3DTSS_COLOROP, D3DTOP_ADD );
    g_pd3dDevice->SetTextureStageState( 2, D3DTSS_COLORARG1, D3DTA_TEXTURE );
    g_pd3dDevice->SetTextureStageState( 2, D3DTSS_COLORARG2, D3DTA_CURRENT );

블렌딩 처리 및 인수를 설정한 후, 다음의 코드로,D3DTSS_BUMPENVMAT00 및 D3DTSS_BUMPENVMAT11 텍스쳐 스테이지 스테이트를 1.0 으로 설정해, 2×2 범프 맵핑 행렬을 단위행렬로 설정한다. 행렬을 단위행렬로 설정 하면, 시스템에서는 미수정의 범프 맵의 델타값이 사용되게 되지만, 이것은 반드시 필요하지 않다.

// 범프 맵핑 행렬을 설정한다.
    //
// 주:
//    이러한 호출은, 이하의 인 라인 쇼트 컷 함수에 의존한다.
//       inline DWORD F2DW( FLOAT f ) { return *((DWORD*) &f); }
    g_pd3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVMAT00, F2DW(1.0f) );
    g_pd3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVMAT01, F2DW(0.0f) );
    g_pd3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVMAT10, F2DW(0.0f) );
    g_pd3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVMAT11, F2DW(1.0f) );

범프 맵핑 처리에 휘도(Luminance) (D3DTOP_BUMPENVMAPLUMINANCE )를 포함하는 경우는, 휘도(Luminance) 제어를 설정할 필요가 있다. 휘도(Luminance) 제어에 의해, 다음의 스테이지의 텍스쳐로부터 색을 조정하기 전에 시스템이 실시하는 휘도(Luminance)의 계산방법을 설정한다 (상세한 것에 대하여는, 「범프 맵핑의 공식」을 참조할것).

// 휘도(Luminance) 제어를 설정한다. 이것은, 범프 맵에 휘도(Luminance)이 포함되어 있는 경우, 및
// D3DTOP_BUMPENVMAPLUMINANCE 텍스쳐 블렌딩 처리가 사용되는 경우에게만
// 필요하다.
    //
// 주:
//    이러한 호출은, 이하의 인 라인 쇼트 컷 함수에 의존한다.
//       inline DWORD F2DW( FLOAT f ) { return *((DWORD*) &f); }
    g_pd3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVLSCALE, F2DW(0.5f) );
    g_pd3dDevice->SetTextureStageState( 1, D3DTSS_BUMPENVLOFFSET, F2DW(0.0f) );

어플리케이션으로 범프 맵핑 파라미터를 설정한 후는, 보통대로 렌더링을 실행할 수 있어 렌더링 되는 다각형에 범프 맵핑 이펙트가 적용된다.

[Visual Basic]

Visual Basic 로 범프 맵핑 파라미터를 설정하려면:

  1. 베이스 텍스쳐 맵 (사용되고 있는 경우), 범프 맵, 및 환경 맵 텍스쳐를 텍스쳐 블렌딩 스테이지로 설정한다.
  2. 각 텍스쳐 스테이지의 색 및 알파 블렌딩 처리를 설정한다.
  3. 범프 맵 트랜스 폼 행렬을 설정한다.
  4. 필요에 따라서, 휘도(Luminance) 스케일값 및 오프셋(offset)값을 설정한다.

다음의 코드에서는, 베이스 텍스쳐 맵, 범프 맵, 및 스펙큐러 환경 맵의 3 개의 텍스쳐를, 적절한 텍스쳐 블렌딩 스테이지로 설정한다.

' 3 개의 텍스쳐를 설정한다.
Call g_d3dDevice.SetTexture(0, d3dBaseTexture)
Call g_d3dDevice.SetTexture(1, d3dBumpMap)
Call g_d3dDevice.SetTexture(2, d3dEnvMap)

텍스쳐를 블렌딩 스테이지로 설정한 후, 다음의 코드로, 각 스테이지의 블렌딩 처리 및 인수를 준비한다.

'범프 맵 텍스쳐를 생성 한다.

    '
'색처리 및 인수를 설정해 범프 맵핑을 준비한다.
    '

'스테이지 0:베이스 텍스쳐
Call g_d3dDevice.SetTextureStageState(0, D3DTSS_COLOROP, D3DTOP_MODULATE)
Call g_d3dDevice.SetTextureStageState(0, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call g_d3dDevice.SetTextureStageState(0, D3DTSS_COLORARG2, D3DTA_DIFFUSE)
Call g_d3dDevice.SetTextureStageState(0, D3DTSS_ALPHAOP, D3DTOP_SELECTARG1)
Call g_d3dDevice.SetTextureStageState(0, D3DTSS_ALPHAARG1, D3DTA_TEXTURE)
Call g_d3dDevice.SetTextureStageState(0, D3DTSS_TEXCOORDINDEX, 1)

'스테이지 1:범프 맵
Call g_d3dDevice.SetTextureStageState(1, D3DTSS_TEXCOORDINDEX, 1)
'이 예에서는 휘도(Luminance)를 사용한다.
Call g_d3dDevice.SetTextureStageState(1, D3DTSS_COLOROP, D3DTOP_BUMPENVMAPLUMINANCE)
Call g_d3dDevice.SetTextureStageState(1, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call g_d3dDevice.SetTextureStageState(1, D3DTSS_COLORARG2, D3DTA_CURRENT)

'스테이지 2:스펙큐러 환경 맵
Call g_d3dDevice.SetTextureStageState(2, D3DTSS_TEXCOORDINDEX, 0)
Call g_d3dDevice.SetTextureStageState(2, D3DTSS_COLOROP, D3DTOP_ADD)
Call g_d3dDevice.SetTextureStageState(2, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call g_d3dDevice.SetTextureStageState(2, D3DTSS_COLORARG2, D3DTA_CURRENT)

블렌딩 처리 및 인수를 설정한 후, 다음의 코드로,D3DTSS_BUMPENVMAT00 및 D3DTSS_BUMPENVMAT11 텍스쳐 스테이지 스테이트를 1.0 으로 설정해, 2×2 범프 맵핑 행렬을 단위행렬로 설정한다. 행렬을 단위행렬로 설정 하면, 시스템에서는 미수정의 범프 맵의 델타값이 사용되게 되지만, 이것은 반드시 필요하지 않다.

'범프 맵핑 행렬을 설정한다.
Call g_d3dDevice.SetTextureStageStateSingle(1, D3DTSS_BUMPENVMAT00, 1#)
Call g_d3dDevice.SetTextureStageStateSingle(1, D3DTSS_BUMPENVMAT01, 0#)
Call g_d3dDevice.SetTextureStageStateSingle(1, D3DTSS_BUMPENVMAT10, 0#)
Call g_d3dDevice.SetTextureStageStateSingle(1, D3DTSS_BUMPENVMAT11, 1#)

범프 맵핑 처리에 휘도(Luminance) (D3DTOP_BUMPENVMAPLUMINANCE )를 포함하는 경우는, 휘도(Luminance) 제어를 설정할 필요가 있다. 휘도(Luminance) 제어에 의해, 다음의 스테이지의 텍스쳐로부터 색을 조정하기 전에 시스템이 실시하는 휘도(Luminance)의 계산방법을 설정한다 (상세한 것에 대하여는, 「범프 맵핑의 공식」을 참조할것).

'휘도(Luminance) 제어를 설정한다. 이것은, 범프 맵에 휘도(Luminance)이 포함되어 있는 경우, 및
' D3DTOP_BUMPENVMAPLUMINANCE 텍스쳐 블렌딩 처리가 사용되는 경우에게만
'필요하다.
Call g_d3dDevice.SetTextureStageStateSingle(1, D3DTSS_BUMPENVLSCALE, 0.5)
Call g_d3dDevice.SetTextureStageStateSingle(1, D3DTSS_BUMPENVLOFFSET, 0#)

어플리케이션으로 범프 맵핑 파라미터를 설정한 후는, 보통대로 렌더링을 실행할 수 있어 렌더링 되는 다각형에 범프 맵핑 이펙트가 적용된다.

주 : 이 예에서는, 파라미터는 스펙큐러 환경 맵핑용으로 설정되어 있다. 디퓨즈 라이트 맵핑을 실시하는 경우는, 마지막 스테이지의 텍스쳐 블렌딩 처리를 D3DTOP_MODULATE 로 설정한다. 상세한 것에 대하여는, 「디퓨즈 라이트 맵」을 참조할것.


클립면의 설정과 취득

[C++]

유저 정의 클립면은,IDirect3DDevice7::SetClipPlane 및 IDirect3DDevice7::GetClipPlane 메소드를 호출해 설정 및 취득한다. 평면을 정의하는 계수는, 4 개의 요소를 가지는 D3DVALUE 형의 배열에 저장 된다.

SetClipPlane 메소드는, 2 개의 파라미터를 받는다. 제 1 파라미터에는, 설정하는 클립면의 0 으로부터 시작되는 인덱스를 지정한다. 제 2 파라미터에는, 일반 평면식의 계수를 저장 하는 버퍼의 주소를 지정한다.

주 : SetClipPlane 에 건네주는 계수는 일반 평면식의 형태를 취한다. 메소드로 건네주는 배열의 값이 A, B, C, 및 D (메모리내에서 나타나는 순서)이라고 하면, 이러한 값은 이 식에 따라 Ax + By + Cz + D = 0 이 된다. Ax + By + Cz + D >= 0 이 성립되는 경우, 월드 공간 좌표 (x, y, z)의 점이 평면에서 단락지어진 반의 공간에 표시된다. 클립 얼굴 또는 그 후 (분)편에게 있는 점은 장면으로부터 잘라내진다.

다음의 코드는, C++ 에 있어서의 이 메소드의 호출 방법을 나타낸다.

// 이 예에서는, pd3dDevice 변수는 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다.

// x<=0 를 채우는 버텍스를 클리핑 하도록(듯이)
// 클립면을 설정한다.
D3DVALUE clip[4];
ZeroMemory( (LPVOID) clip, sizeof(clip) );

clip[0] = 1.0f;
pd3dDevice->SetClipPlane( 0, clip );

클립면의 계수를 설정해도, 그 면에 의한 클리핑이 유효하게 되는 것은 아니다. 상세한 것에 대하여는, 「클립면의 유효/무효」를 참조할것.

클립면은 최대 32 개 (D3DMAXUSERCLIPPLANES)까지 정의할 수 있다. 따라서,SetClipPlane 메소드에 건네줄 수가 있는 최대 인덱스는 31 이다. 무효인 값을 건네주면(자) 메소드는 실패해,DDERR_INVALIDPARAMS 를 돌려준다.

IDirect3DDevice7::GetClipPlane 메소드는, 의미론적으로는 IDirect3DDevice7::SetClipPlane 메소드에 유사한 메소드이다. 다음의 C++ 코드는, 인덱스 2 의 클립면에 현재 설정되어 있는 계수를 취득한다.

// 이 예에서는, pd3dDevice 변수는 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다.

D3DVALUE clip[4];
pd3dDevice->GetClipPlane( 2, clip );
[Visual Basic]

유저 정의 클립면은,Direct3DDevice7.SetClipPlane 및 Direct3DDevice7.GetClipPlane 메소드를 호출해 설정 및 취득한다. 평면을 정의하는 계수는, 4 개의 요소를 가지는 D3DVALUE 형의 배열에 저장 된다.

SetClipPlane 에의 제 1 파라미터에는, 설정하는 클립면의 0 으로부터 시작되는 인덱스를 지정한다. 그 외의 파라미터에는, 일반 평면식의 계수를 저장 한다.

주 : SetClipPlane 에 건네주는 계수는 일반 평면식의 형태를 취한다. 메소드로 건네주는 배열의 값이 A, B, C, 및 D (메모리내에서 나타나는 순서)이라고 하면, 이러한 값은 이 식에 따라 Ax + By + Cz + D = 0 이 된다. Ax + By + Cz + D >= 0 이 성립되는 경우, 월드 공간 좌표 (x, y, z)의 점이 평면에서 단락지어진 반의 공간에 표시된다. 클립 얼굴 또는 그 후 (분)편에게 있는 점은 장면으로부터 잘라내진다.

다음의 코드는, Visual Basic 에 있어서의 이 메소드의 호출 방법을 나타낸다.

'이 예에서는, d3dDevice 변수는 Direct3DDevice 오브젝트에의
'유효한 참조이다.

' x<=0 를 채우는 버텍스를 클리핑 하도록(듯이)
'클립면을 설정한다.
Dim A As Single, B As Single, _
C As Single, D As Single

A = 1#

Call d3dDevice.SetClipPlane(0, A, B, C, D)

클립면의 계수를 설정해도, 그 면에 의한 클리핑이 유효하게 되는 것은 아니다. 상세한 것에 대하여는, 「클립면의 유효/무효」를 참조할것.

클립면은 최대 32 개 (D3DMAXUSERCLIPPLANES)까지 정의할 수 있다. 따라서,SetClipPlane 메소드에 건네줄 수가 있는 최대 인덱스는 31 이다. 무효인 값을 건네주면(자) 메소드는 실패해,DDERR_INVALIDPARAMS 를 돌려준다.

Direct3DDevice7.GetClipPlane 메소드는, 의미론적으로는 Direct3DDevice7.SetClipPlane 메소드에 유사한 메소드이다. 다음의 Visual Basic 코드는, 인덱스 2 의 클립면에 현재 설정되어 있는 계수를 취득한다.

'이 예에서는, d3dDevice 변수는 Direct3DDevice 오브젝트에의
'유효한 참조이다.

Dim A As Single, B As Single, _
C As Single, D As Single

Call d3dDevice.GetClipPlane(2, A, B, C, D)


버텍스 포그(안개:fog)에 대해

시스템은 버텍스 포그(안개:fog)를 실행 하면 와, 다각형의 각 버텍스에 포그(안개:fog) 계산을 적용해, 다음에, rasterize때, 다각형의 면에 결과를 보간 한다. 버텍스 포그(안개:fog)의 이펙트는, Direct3D 의 라이팅 & 트랜스 폼 엔진에 의해 계산된다. 상세한 것에 대하여는, 「포그(안개:fog) 파라미터」를 참조할것.

어플리케이션으로 Direct3D 를 사용하지 않고 트랜스 폼 & 라이팅을 실행하는 경우는, 어플리케이션으로 독자적으로 포그(안개:fog) 계산을 실시할 필요가 있다. 이 경우, 어플리케이션은 포그(안개:fog) 계수를 계산해, 각 버텍스의 스펙큐러색의 알파 성분에 둔다. 공식으로는, 범위 베이스의 공식, 체적을 이용하는 공식적인 , 어떠한 것에서도 사용할 수 있다. Direct3D 는 주어진 포그(안개:fog) 계수를 사용해, 각 다각형의 면을 보간 한다. Direct3D 의 트랜스 폼 & 라이팅을 사용하지 않는 어플리케이션에서는, 버텍스 포그(안개:fog) 파라미터를 설정할 필요는 없지만, 포그(안개:fog)를 유효하게 해, 관련하는 렌더링 스테이트에 의해 포그(안개:fog) 컬러를 설정해야 한다. 상세한 것에 대하여는, 「포그(안개:fog) 파라미터」를 참조할것.

주 : 어플리케이션으로 독자적인 트랜스 폼 & 라이팅을 실행하는 경우는, 그것 독자적인 포그(안개:fog) 계산을 실행할 필요가 있다. 따라서, 그러한 어플리케이션에서는, 「포그(안개:fog) 블렌딩」 및 「포그(안개:fog) 컬러」로 설명하도록(듯이), 포그(안개:fog) 블렌딩을 유효하게 해, 관련하는 렌더링 스테이트에 의해 포그(안개:fog) 컬러를 설정하는 것만으로 좋다.


선리스트

Platform SDK: DirectX

선리스트

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

[C++]

다음의 코드는, C++ 로 이 태스크를 실행하는 방법을 나타낸다.

const DWORD TOTAL_VERTS=6;
D3DVERTEX lpVerts[TOTAL_VERTS];

lpVerts[0] = D3DVERTEX(D3DVECTOR(-5,-5, 0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[1] = D3DVERTEX(D3DVECTOR(0,5,0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[2] = D3DVERTEX(D3DVECTOR(5,-5, 0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[3] = D3DVERTEX(D3DVECTOR(10,5,0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[4] = D3DVERTEX(D3DVECTOR(15,-5, 0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[5] = D3DVERTEX(D3DVECTOR(20,5,0), D3DVECTOR(0,0,-1), 0,0);

IDirect3DDevice7::DrawPrimitive 메소드를 사용해 선리스트를 렌더링 한다. 다음의 코드는,IDirect3DDevice7::DrawPrimitive 를 사용해, 위에의 예의 선리스트를 드로잉(Drawing) 하는 방법을 나타낸다. IDirect3DDevice7::DrawPrimitive 의 호출은,IDirect3DDevice7::BeginScene 와 IDirect3DDevice7::EndScene 의 사이에 실시할 필요가 있다.

HRESULT hResult;
// 이 코드에서는, lpDirect3DDevice 이 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다고 한다.
hResult =
    lpDirect3DDevice->DrawPrimitive(D3DPT_LINELIST,
                                      D3DFVF_VERTEX,
                                      lpVerts,
                                      TOTAL_VERTS,
                                      D3DDP_WAIT);
[Visual Basic]

Visual Basic 어플리케이션에서는, 다음의 코드로 가리키도록(듯이), 배열에 값을 저장 한다.

'이 코드에서는, dx 가 DirectX7 오브젝트에의
'유효한 참조이다고 한다.
On Local Error Resume Next
Const TOTAL_VERTS As Integer = 6
Dim Verts(TOTAL_VERTS) As D3DVERTEX

Verts(0) = dx.CreateD3DVertex(-5, -5, 0, 0, 0, -1, 0, 0)
Verts(1) = dx.CreateD3DVertex(0, 5, 0, 0, 0, -1, 0, 0)
Verts(2) = dx.CreateD3DVertex(5, -5, 0, 0, 0, -1, 0, 0)
Verts(3) = dx.CreateD3DVertex(10, 5, 0, 0, 0, -1, 0, 0)
Verts(4) = dx.CreateD3DVertex(15, -5, 0, 0, 0, -1, 0, 0)
Verts(5) = dx.CreateD3DVertex(20, 5, 0, 0, 0, -1, 0, 0)

Direct3DDevice7.DrawPrimitive 메소드를 사용해 점리스트를 렌더링 한다. 다음의 코드는,Direct3DDevice7.DrawPrimitive 를 사용해, 위에의 예의 선리스트를 드로잉(Drawing) 하는 방법을 나타낸다. Direct3DDevice7.DrawPrimitive 의 호출은,Direct3DDevice7.BeginScene 와 Direct3DDevice7.EndScene 의 사이에 실시할 필요가 있다.

'이 코드에서는, d3ddev 가 Direct3DDevice7 오브젝트에의
'유효한 참조이다고 한다.
Call d3ddev.DrawPrimitive(D3DPT_LINELIST, _
D3DFVF_VERTEX, _
Verts(0), _
TOTAL_VERTS, _
                          D3DDP_WAIT)

If Err.Number <> DD_OK Then
'에러 처리 코드
End If

다음의 그림은, 결과적으로 드로잉(Drawing) 되는 선을 나타낸다.

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


컬링(Culling) 스테이트

Direct3D 에서는, 프리미티브를 렌더링 할 경우에 프리미티브의 뒷면이 잘라내진다.

[C++]

C++ 어플리케이션으로 컬링(Culling) 모드를 설정하려면 ,D3DCULL 열거형을 사용한다. 「D3DRENDERSTATE_CULLMODE 」를 참조할것. 디폴트에서는, 반시계회전의 버텍스를 가지는 뒷면이 잘라내진다.

다음의 샘플 코드는, 시계회전의 버텍스를 가지는 뒷면을 잘라내는 컬링(Culling) 모드를 설정하는 처리를 나타낸다.

// 이 코드에서는, lpDirect3DDevice 는 IDirect3DDevice 인터페이스에의
// 유효한 포인터이다고 한다.

// 컬링(Culling) 스테이트를 설정한다.
lpD3DDevice->SetRenderState(D3DRENDERSTATE_CULLMODE,
                            D3DCULL_CW);
[Visual Basic]

Visual Basic 어플리케이션으로 컬링(Culling) 모드를 설정하려면 ,CONST_D3DCULL 열거의 멤버를 설정할 수 있는 D3DRENDERSTATE_CULLMODE 렌더링 스테이트를 사용한다. 디폴트에서는, 반시계회전의 버텍스를 가지는 뒷면이 잘라내진다.

다음의 샘플 코드는, 시계회전의 버텍스를 가지는 뒷면을 잘라내는 컬링(Culling) 모드를 설정하는 처리를 나타낸다.

'이 코드에서는,
' D3DDevice 에 Direct3DDevice 오브젝트에의 참조가 저장 되고 있다고 한다.

'컬링(Culling) 스테이트를 설정한다.
Call D3DDevice.SetRenderState(D3DRENDERSTATE_CULLMODE, _
                              D3DCULL_CW)


텍스쳐 경계

[Visual Basic]

주 : 여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 의 경우,Direct3DDevice7.SetTextureStageState 메소드로 D3DTSS_BORDERCOLOR 텍스쳐 스테이지 스테이트를 설정해, 텍스쳐 경계에서의 처리를 설정할 필요가 있다.

[C++]

D3DRENDERSTATE_BORDERCOLOR 렌더링 스테이트는, 현재는 사용되어 있지 않다. 이것은,IDirect3DDevice7::SetTextureStageState 메소드가 지원 하는 D3DTSS_BORDERCOLOR 텍스쳐 스테이지 스테이트로 옮겨지고 있다. 상세한 것에 대하여는, 「경계색텍스쳐 addressing mode에 대하며」를 참조할것.

주 : D3DRENDERSTATE_BORDERCOLOR 렌더링 스테이트는,IDirect3DDevice7 인터페이스에서는 인식되지 않는다. 이 렌더링 스테이트를 IDirect3DDevice7 인터페이스로 사용 하면 실패한다.


쉐이딩 스테이트

[C++]

Direct3D 에서는, flat shading와 gouraud shading의 양쪽 모두를 지원 하고 있다. 디폴트에서는 gouraud shading가 설정된다. 현재의 쉐이딩 모드를 제어하기 위해서, C++ 어플리케이션에서는 D3DSHADEMODE 열거형을 사용한다. 「D3DRENDERSTATE_SHADEMODE 」를 참조할것.

다음의 C++ 코드는, 쉐이딩 스테이트를 flat shading 모드로 설정하는 처리를 나타낸다.

// 이 코드에서는, lpD3DDevice 는 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다고 한다.

// 쉐이딩 스테이트를 설정한다.
lpD3DDevice->SetRenderState(D3DRENDERSTATE_SHADEMODE,
                            D3DSHADE_FLAT);
[Visual Basic]

Direct3D 에서는, flat shading와 gouraud shading의 양쪽 모두를 지원 하고 있다. 디폴트에서는 gouraud shading가 설정된다. Visual Basic 어플리케이션으로 현재의 쉐이딩 모드를 제어하려면 ,CONST_D3DSHADEMODE 열거형을 사용한다. 「D3DRENDERSTATE_SHADEMODE 」를 참조할것.

다음의 코드는, 쉐이딩 스테이트를 flat shading 모드로 설정하는 처리를 나타낸다.

'이 예에서는, D3DDevice 는 Direct3DDevice7 오브젝트에의
'유효한 참조이다고 한다.

'쉐이딩 스테이트를 설정한다.
Call D3DDevice.SetRenderState(D3DRENDERSTATE_SHADEMODE, D3DSHADE_FLAT)


컬러 라이팅 맵

일반적으로, 컬러 라이팅 맵을 사용하면, 3D 신을 보다 리얼하게 렌더링 할 수 있다. 컬러 라이팅 맵은, 라이팅 정보로서 라이트 맵의 RGB 데이터를 사용한다.

[C++]

다음의 C++ 코드는, RGB 색데이터를 사용한 라이트 맵핑을 나타낸다.

// 이 예에서는, lpD3DDev 은 IDirect3DDevice7 인터페이스에의 유효한 포인터로,
// lptexLightMap 는 RGB 라이트 맵 데이터를 포함한 텍스쳐에의
// 유효한 포인터이다고 한다.

// 라이트 맵 텍스쳐를 최초의 텍스쳐로서 설정한다.
lpD3DDev->SetTexture(0, lptexLightMap);

lpD3DDev->SetTextureStageState(0, D3DTSS_COLOROP,
       D3DTOP_MODULATE);

lpD3DDev->SetTextureStageState(0, D3DTSS_COLORARG1,
       D3DTA_TEXTURE);

lpD3DDev->SetTextureStageState(0, D3DTSS_COLORARG2,
       D3DTA_DIFFUSE);

이 예에서는, 라이트 맵을 최초의 텍스쳐로서 설정해 있다. 그 다음에, 최초의 블렌딩 스테이지의 스테이트를 설정해, 입력 텍스쳐 데이터를 조정하고 있다. 또, 최초의 텍스쳐와 프리미티브의 현재 컬러를 조정 처리용의 인수로서 사용하고 있다.

[Visual Basic]

다음의 Visual Basic 코드는, RGB 색데이터를 사용한 라이트 맵핑을 나타낸다.

'이 예에서는, D3DDev 는 Direct3DDevice7 오브젝트에의 유효한 참조로,
' texLightMap 는 RGB 라이트 맵 데이터를 포함한 DirectDrawSurface7 텍스쳐 표면에의
'유효한 포인터이다고 한다.

'라이트 맵 텍스쳐를 최초의 텍스쳐로서 설정한다.
Call d3dDev.SetTexture(0, texLightMap)

Call d3dDev.SetTextureStageState(0, D3DTSS_COLOROP, _
D3DTOP_MODULATE );

Call d3dDev.SetTextureStageState(0, D3DTSS_COLORARG1, _
D3DTA_TEXTURE);

Call d3dDev.SetTextureStageState(0, D3DTSS_COLORARG2, _
D3DTA_DIFFUSE);

이 예에서는, 라이트 맵을 최초의 텍스쳐로서 설정해 있다. 그 다음에, 최초의 블렌딩 스테이지의 스테이트를 설정해, 입력 텍스쳐 데이터를 조정하고 있다. 또, 최초의 텍스쳐와 프리미티브의 현재 컬러를 조정 처리용의 인수로서 사용하고 있다.


밉맵의 선택과 표시

[C++]

IDirect3DDevice7::SetTexture 메소드를 호출해, 현재 텍스쳐의 일람내의 선두의 텍스쳐로서 밉맵 텍스쳐를 설정한다. 상세한 것에 대하여는, 「멀티 텍스쳐 블렌딩」을 참조할것.

밉맵 텍스쳐 세트를 선택한 후,D3DTEXTUREMIPFILTER 열거형으로부터의 값을 D3DTSS_MIPFILTER 텍스쳐 스테이지 스테이트에 할당하지 않으면 안 된다. 이것에 의해, Direct3D 에서는 밉맵 텍스쳐 필터링을 자동적으로 실행한다.

또,IDirectDrawSurface7::GetAttachedSurface 메소드를 사용해,DDSCAPS2 구조체의 DDSCAPS_MIPMAP 및 DDSCAPS_TEXTURE 플래그를 지정하는 것으로, 밉맵 표면의 체인을 수동으로 암벽 횡단 할 수 있다. 다음의 예에서는, 최고 해상도로부터 최저 해상도까지 밉맵 체인을 암벽 횡단 한다.

LPDIRECTDRAWSURFACE7 lpDDLevel, lpDDNextLevel;
DDSCAPS2 ddsCaps;
HRESULT ddres;

lpDDLevel = lpDDMipMap;
lpDDLevel->AddRef();
ddsCaps.dwCaps = DDSCAPS_TEXTURE | DDSCAPS_MIPMAP;
ddres = DD_OK;
while (ddres == DD_OK)
{
// 이 레벨을 처리한다.
    .
    .
    .
    ddres = lpDDLevel->GetAttachedSurface(
&ddsCaps, &lpDDNextLevel);
    lpDDLevel->Release();
    lpDDLevel = lpDDNextLevel;
}
if ((ddres ! = DD_OK) && (ddres ! = DDERR_NOTFOUND))
{
// 에러 처리 코드
}
.
.
.

체인의 각 표면에 비트 맵 데이터를 로드하기 위해서(때문에), 어플리케이션에서는 밉맵 체인을 수동으로 암벽 횡단 할 필요가 있다. 보통, 이 이유로부터 체인을 암벽 횡단 한다.

Direct3D 에서는, 밉맵 체인의 레벨의 수를 명시적으로 저장 한다. 어플리케이션으로 밉맵의 표면 정보를 취득 하면 (IDirectDrawSurface7::Lock 또는 IDirectDrawSurface7::GetSurfaceDesc 메소드를 호출한다),DDSURFACEDESC2 구조체의 dwMipMapCount 멤버에, 최상정도 레벨을 포함 밉맵의 레벨의 수가 저장 된다. 밉맵의 최상정도 레벨 이외의 레벨에 대해서는,dwMipMapCount 멤버가, 그 밉맵으로부터 최소 밉맵까지의 레벨의 수를 지정한다.

[Visual Basic]

Direct3DDevice7.SetTexture 메소드를 호출해, 현재 텍스쳐의 일람내의 선두의 텍스쳐로서 밉맵 텍스쳐를 설정한다. 상세한 것에 대하여는, 「멀티 텍스쳐 블렌딩」을 참조할것.

밉맵 텍스쳐 세트를 선택한 후,CONST_D3DTEXTUREMIPFILTER 열거형으로부터의 값을 D3DTSS_MIPFILTER 텍스쳐 스테이지 스테이트에 할당하지 않으면 안 된다. 이것에 의해, Direct3D 에서는 밉맵 텍스쳐 필터링을 자동적으로 실행한다.

또,DirectDrawSurface7.GetAttachedSurface 메소드를 사용해,DDSCAPS2 형의 DDSCAPS_MIPMAP 및 DDSCAPS_TEXTURE 플래그를 지정하는 것으로, 밉맵 표면의 체인을 수동으로 암벽 횡단 할 수 있다. 다음의 예에서는, 최고 해상도로부터 최저 해상도까지 밉맵 체인을 암벽 횡단 한다.

On Local Error Resume Next

Dim DDLevel As DirectDrawSurface7, _
DDNextLevel As DirectDrawSurface7

Dim ddsCaps As DDSCAPS2

DDLevel = DDMipMap
ddsCaps.lCaps = DDSCAPS_TEXTURE Or DDSCAPS_MIPMAP
While Err.Number = DD_OK
'이 레벨을 처리한다.
    ' .
    ' .
    ' .
Set DDNextLevel = DDLevel.GetAttachedSurface(ddsCaps)
DDLevel = DDNextLevel
Wend
If ((Err.Number <> DD_OK) And (Err.Number <> DDERR_NOTFOUND)) Then
'에러 처리 코드
End If
.
.
.

체인의 밉맵 표면의 각 표면에 비트 맵 데이터를 로드하기 위해서(때문에), 어플리케이션에서는 밉맵 체인을 수동으로 암벽 횡단 할 필요가 있다. 보통, 이 이유로부터 체인을 암벽 횡단 한다.

Direct3D 에서는, 밉맵 체인의 레벨의 수를 명시적으로 저장 한다. 어플리케이션으로 밉맵의 표면 정보를 취득 하면 (DirectDrawSurface7.Lock 또는 DirectDrawSurface7.GetSurfaceDesc 메소드를 호출한다),DDSURFACEDESC2 형의 lMipMapCount 멤버에, 최상정도 레벨을 포함 밉맵의 레벨의 수가 저장 된다. 밉맵의 최상정도 레벨 이외의 레벨에 대해서는,lMipMapCount 멤버가, 그 밉맵으로부터 최소 밉맵까지의 레벨의 수를 지정한다.


텍스쳐 좌표 트랜스 폼을 유효하게 하는 [C++]

Platform SDK: DirectX
텍스쳐 좌표 트랜스 폼을 유효하게 하는 [C++]

D3DTSS_TEXTURETRANSFORMFLAGS 텍스쳐 스테이지 스테이트는, 텍스쳐 좌표 트랜스 폼의 적용을 제어한다. 이 텍스쳐 스테이지 스테이트의 값은,D3DTEXTURETRANSFORMFLAGS 열거형으로 정의된다.

D3DTSS_TEXTURETRANSFORMFLAGS 가 D3DTTFF_DISABLE (디폴트값)로 설정되어 있을 때는, 텍스쳐 좌표 트랜스 폼은 무효이다. 텍스쳐 좌표 트랜스 폼이 스테이지 0 에 대해서 유효한 경우, 다음의 코드는 이것을 무효로 한다.

// 이 예에서는, lpd3dDevice 변수에 IDirect3DDevice7 인터페이스에의
// 유효한 포인터가 저장 되고 있다.

lpd3dDevice->SetTextureStageState( 0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_DISABLE);

D3DTEXTURETRANSFORMFLAGS 에 정의되고 있는 그 외의 값은, 텍스쳐 좌표 트랜스 폼을 유효하게 하기 위한(해), 및 결과적으로 생성되는 텍스쳐 좌표의 요소를 래스터라이저에 도 더하는 개수를 제어하기 위해서 사용한다. 예로서 다음의 코드를 생각한다.

// 이 예에서는, lpd3dDevice 변수에 IDirect3DDevice7 인터페이스에의
// 유효한 포인터가 저장 되고 있다.

lpd3dDevice->SetTextureStageState( 0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT2);

D3DTTFF_COUNT2 값에 의해, 텍스쳐 스테이지 0 용의 트랜스 폼 행렬 세트를 적용해, 트랜스 폼 후의 텍스쳐 좌표의 최초의 2 개의 요소를 래스터라이저에 건네주도록(듯이) 시스템에 지시한다.

D3DTTFF_PROJECTED 텍스쳐 트랜스 폼 플래그는, 투영 되는 텍스쳐의 좌표를 나타낸다. 이 플래그가 지정되고 있는 경우, 래스터라이저는 트랜스 폼 대상의 요소를 마지막 요소로 나눗셈 한다. 예로서 다음의 코드를 생각한다.

// 이 예에서는, lpd3dDevice 변수에 IDirect3DDevice7 인터페이스에의
// 유효한 포인터가 저장 되고 있다.

lpd3dDevice->SetTextureStageState( 0, D3DTSS_TEXTURETRANSFORMFLAGS,
D3DTTFF_COUNT3 | D3DTTFF_PROJECTED );

이 코드에서는, 3 개의 텍스쳐 좌표 요소를 래스터라이저에 건네주도록(듯이) 시스템에 알린다. 래스터라이저에서는, 최초의 2 개의 요소를 3 번째의 요소로 나눗셈 해, 텍스쳐의 처리에 필요한 2D 텍스쳐 좌표를 생성한다.

[Visual Basic]

D3DTSS_TEXTURETRANSFORMFLAGS 텍스쳐 스테이지 스테이트는, 텍스쳐 좌표 트랜스 폼의 적용을 제어한다. 이 텍스쳐 스테이지 스테이트의 값은,CONST_D3DTEXTURETRANSFORMFLAGS 열거로 정의되고 있다.

D3DTSS_TEXTURETRANSFORMFLAGS 가 D3DTTFF_DISABLE (디폴트값)로 설정되어 있을 때는, 텍스쳐 좌표 트랜스 폼은 무효이다. 텍스쳐 좌표 트랜스 폼이 스테이지 0 에 대해서 유효한 경우, 다음의 코드는 이것을 무효로 한다.

'이 예에서는, d3dDevice 변수에 Direct3DDevice7 오브젝트에의
'유효한 참조가 저장 되고 있다.

Call d3dDevice.SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, _
D3DTTFF_DISABLE)

CONST_D3DTEXTURETRANSFORMFLAGS 에 정의되고 있는 그 외의 값은, 텍스쳐 좌표 트랜스 폼을 유효하게 하기 위한(해), 및 결과적으로 생성되는 텍스쳐 좌표의 요소를 래스터라이저에 도 더하는 개수를 제어하기 위해서 사용한다. 예로서 다음의 코드를 생각한다.

'이 예에서는, d3dDevice 변수에 Direct3DDevice7 오브젝트에의
'유효한 참조가 저장 되고 있다.

Call d3dDevice.SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, _
D3DTTFF_COUNT2)

D3DTTFF_COUNT2 값은, 텍스쳐 스테이지 0 용의 트랜스 폼 행렬 세트를 적용해, 트랜스 폼 후의 텍스쳐 좌표의 최초의 2 개의 요소를 래스터라이저에 건네주도록(듯이) 시스템에 지시한다.

D3DTTFF_PROJECTED 텍스쳐 트랜스 폼 플래그는, 투영 되는 텍스쳐의 좌표를 나타낸다. 이 플래그가 지정되고 있는 경우, 래스터라이저는 트랜스 폼 대상의 요소를 마지막 요소로 나눗셈 한다. 예로서 다음의 코드를 생각한다.

'이 예에서는, d3dDevice 변수에 IDirect3DDevice7 인터페이스에의
// 유효한 포인터가 저장 되고 있다.

Call d3dDevice.SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, _
D3DTTFF_COUNT3 | D3DTTFF_PROJECTED)

이 코드에서는, 3 개의 텍스쳐 좌표 요소를 래스터라이저에 건네주도록(듯이) 시스템에 알린다. 래스터라이저에서는, 최초의 2 개의 요소를 3 번째의 요소로 나눗셈 해, 텍스쳐의 처리에 필요한 2D 텍스쳐 좌표를 생성한다.


면마스크 스테이트

[Visual Basic]

주 : 여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다.

[C++]

주 : D3DRENDERSTATE_PLANEMASK 렌더링 스테이트는, DirectX 7.0 릴리스에서는 사용되지 않는다. 알파 블렌딩에 의한 색버퍼에의 쓰기를 무효로 하려면 ,D3DRENDERSTATE_SRCBLEND 를 D3DBLEND_ZERO 로 설정해,D3DRENDERSTATE_DESTBLEND 를 D3DBLEND_ONE 로 설정한다.


텍스쳐 퍼스펙티브 스테이트

[C++]

어플리케이션에서는, 퍼스펙티브 보정을 텍스쳐에 적용하는 것으로, 뷰아로부터 멀어지는 것에 따라 사이즈가 작아지는 원시적으로 텍스쳐를 올바르게 적용할 수 있다. 「D3DRENDERSTATE_TEXTUREPERSPECTIVE 」를 참조할것.

다음의 코드는, 텍스쳐 퍼스펙티브 보정을 유효하게 하는 처리를 나타낸다.

// 이 코드에서는, lpD3DDevice 는 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다고 한다.

// 텍스쳐 퍼스펙티브를 유효하게 한다.
lpD3DDevice7->SetRenderState(D3DRENDERSTATE_TEXTUREPERSPECTIVE,
                             TRUE);

IDirect3DDevice3 및IDirect3DDevice7 인터페이스에서는, 디폴트값이 TRUE 가 되어, 퍼스펙티브 보정 텍스쳐 맵핑이 유효하게 된다. 구인터페이스의 경우, 디폴트값은 FALSE 이다. 많은 3D 어댑터는, 텍스쳐 퍼스펙티브 보정을 무조건 적용하므로 주의가 필요하다. w 베이스 포그(안개:fog) 및 w 버퍼를 사용하려면 , 퍼스펙티브 보정을 유효하게 할 필요가 있다. 상세한 것에 대하여는, 「포그(안개:fog)」섹션의 「시점으로부터의 상대 깊이대 Z 베이스의 깊이」 및 「깊이 버퍼」섹션의 「깊이 버퍼링의 유효화」를 참조할것.

[Visual Basic]

어플리케이션에서는, 퍼스펙티브 보정을 텍스쳐에 적용하는 것으로, 뷰아로부터 멀어지는 것에 따라 사이즈가 작아지는 원시적으로 텍스쳐를 올바르게 적용할 수 있다. 「D3DRENDERSTATE_TEXTUREPERSPECTIVE 」를 참조할것.

다음의 코드는, 텍스쳐 퍼스펙티브 보정을 유효하게 하는 처리를 나타낸다.

'이 코드에서는, d3dD3DDevice 는 Direct3DDevice7 오브젝트에의
'유효한 참조이다고 한다.

'텍스쳐 퍼스펙티브를 유효하게 한다.
Call d3dDevice7.SetRenderState(D3DRENDERSTATE_TEXTUREPERSPECTIVE, _
                               True)

디폴트값은 True 로, 퍼스펙티브 보정 텍스쳐 맵핑이 유효하게 된다.

많은 3D 어댑터는, 텍스쳐 퍼스펙티브 보정을 무조건 적용하므로 주의가 필요하다. w 베이스 포그(안개:fog) 및 w 버퍼를 사용하려면 , 퍼스펙티브 보정을 유효하게 할 필요가 있다. 상세한 것에 대하여는, 「포그(안개:fog)」섹션의 「시점으로부터의 상대 깊이대 Z 베이스의 깊이」 및 「깊이 버퍼」섹션의 「깊이 버퍼링의 유효화」를 참조할것.


텍스쳐 좌표 트랜스 폼

여기에서는, Direct3D 직접 모드로 제공되는 텍스쳐 좌표 트랜스 폼 기능의 조작에 대해 설명한다.

  • 텍스쳐 좌표 트랜스 폼에 대해
  • 텍스쳐 좌표 트랜스 폼의 설정과 취득
  • 텍스쳐 좌표 트랜스 폼을 유효하게 한다


블렌딩 스테이지의 생성

[C++]

블렌딩 스테이지란, 인수를 사용해 텍스쳐의 블렌딩 방법을 정의하는, 일련의 텍스쳐 처리이다. 블렌딩 스테이지를 생성 하면 와, C++ 어플리케이션에서는 IDirect3DDevice7::SetTextureStageState 메소드를 호출한다. 최초의 호출로, 실행하는 처리를 지정한다. 게다가 2 회의 호출로, 처리를 적용하는 인수를 정의한다. 다음의 코드는, 블렌딩 스테이지의 생성 방법을 나타낸다.

// 이 예에서는, lpD3DDev 이 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다고 한다.

// 최초의 텍스쳐의 처리를 설정한다.
lpD3DDev->SetTextureStageState(0, D3DTSS_COLOROP, D3DTOP_ADD);

// 텍스쳐 처리용의 arg1 를 설정한다.
lpD3DDev->SetTextureStageState(0, // 최초의 텍스쳐.
       D3DTSS_COLORARG1,  // 색인수 1 을 설정한다.
       D3DTA_TEXTURE);    // 색인수 1 의 값.

// 텍스쳐 처리용의 arg2 를 설정한다.
lpD3DDev->SetTextureStageState(0, // 최초의 텍스쳐.
       D3DTSS_COLORARG2,  // 색인수 2 를 설정한다.
       D3DTA_DIFFUSE);    // 색인수 2 의 값.

텍스쳐의 텍셀 데이터에는, 컬러값과 알파값이 포함된다. 프로그램에서는, 단일의 블렌딩 스테이지에서 컬러값과 알파값의 양쪽 모두를 정의할 수 있다. 색처리와 알파 처리에는, 각각 독자적인 인수가 있다. 상세한 것에 대하여는, 「D3DTEXTURESTAGESTATETYPE 」를 참조할것.

다음의 매크로는 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 );
[Visual Basic]

블렌딩 스테이지란, 인수를 사용해 텍스쳐의 블렌딩 방법을 정의하는, 일련의 텍스쳐 처리이다. 블렌딩 스테이지를 생성 하면 와, Visual Basic 어플리케이션에서는 Direct3DDevice7.SetTextureStageState 메소드를 호출한다. 최초의 호출로, 실행하는 처리를 지정한다. 게다가 2 회의 호출로, 처리를 적용하는 인수를 정의한다. 다음의 코드는, 블렌딩 스테이지의 생성 방법을 나타낸다.

'이 예에서는, d3dDev 는 Direct3DDevice7 오브젝트에의
'유효한 참조이다고 한다.

'최초의 텍스쳐의 처리를 설정한다.
Call d3dDev.SetTextureStageState(0, D3DTSS_COLOROP, D3DTOP_ADD)

' arg1 를 텍스쳐색으로 설정한다.
Call d3dDev.SetTextureStageState(0, D3DTSS_COLORARG1, D3DTA_TEXTURE)

' arg2 를, 반복하는 디퓨즈색으로 설정한다.
Call d3dDev.SetTextureStageState(0, D3DTSS_COLORARG2, D3DTA_DIFFUSE)

텍스쳐의 텍셀 데이터에는, 컬러값과 알파값이 포함된다. 프로그램에서는, 단일의 블렌딩 스테이지에서 컬러값과 알파값의 양쪽 모두를 정의할 수 있다. 색처리와 알파 처리에는, 각각 독자적인 인수가 있다. 상세한 것에 대하여는, 「CONST_D3DTEXTURESTAGESTATETYPE 」를 참조할것.


범위 베이스의 포그(안개:fog)

Direct3D 에서는, Direct3D 의 트랜스 폼 & 라이팅 엔진으로 버텍스 포그(안개:fog)를 사용하는 경우에게만, 범위 베이스의 포그(안개:fog)의 계산을 실행한다. 이것은, 픽셀 포그(안개:fog)는 디바이스 드라이버에 이행 되어 현재로서는, 픽셀 단위의 범위 베이스의 포그(안개:fog)를 지원 하는 하드웨어는 존재하지 않기 때문이다. 어플리케이션으로 독자적인 트랜스 폼 & 라이팅을 실행하는 경우는, 범위 베이스의 계산이나 그 외의 계산에 의한 독자적인 포그(안개:fog) 계산을 실시할 필요가 있다.

포그(안개:fog)를 사용 하면, 오브젝트가 포그(안개:fog) 컬러와 직감적이 아닌 방법으로 블렌드 되기 위해서(때문에) 생기는 부자연스러운 그래픽스 효과가 보이는 일이 있다. 예를 들어, 2 개의 오브젝트가 보이고 있어, 한편은 포그(안개:fog)의 영향을 받을 정도로에 멀리 있어, 한편은 영향을 받지 않을 정도 에 근처에 있다고 하는 장면을 상정한다. 표시 영역이 같은 장소에서 회전했을 경우, 오브젝트가 정지하고 있었다고 해도, 나타나는 포그(안개:fog) 이펙트는 변화하는 일이 있다. 다음의 그림은 이러한 상황을 내려다 본 스테이트를 나타낸다.

범위 베이스의 포그(안개:fog)는, 포그(안개:fog) 이펙트를 보다 정확하게 결정하는 방법이다. 범위 베이스의 포그(안개:fog)에서는, Direct3D 는 시점으로부터 버텍스까지의 실제의 거리를 포그(안개:fog)의 계산에 사용해, 장면의 범위내에서의 버텍스의 깊이는 아니고 2 점간의 거리의 증가에 따라 포그(안개:fog)의 이펙트를 증가하기 위해(때문에), 부자연스러운 회전 효과가 회피된다.

[C++]

현재의 디바이스가 범위 베이스의 포그(안개:fog)를 지원 하고 있는 경우,IDirect3DDevice7::GetCaps 메소드를 호출했을 때에, 디바이스는 D3DPRIMCAPS 구조체의 dwRasterCaps 멤버에 D3DPRASTERCAPS_FOGRANGE 능력 플래그를 설정한다. 범위 베이스의 포그(안개:fog)를 유효하게 하려면 ,D3DRENDERSTATE_RANGEFOGENABLE 렌더링 스테이트를 TRUE 로 설정한다.

[Visual Basic]

현재의 디바이스가 범위 베이스의 포그(안개:fog)를 지원 하고 있는 경우,Direct3DDevice7.GetCaps 메소드를 호출하면, 디바이스는 D3DPRIMCAPS 형의 lRasterCaps 멤버에 D3DPRASTERCAPS_FOGRANGE 능력 플래그를 설정한다. 범위 베이스의 포그(안개:fog)를 유효하게 하려면 ,D3DRENDERSTATE_RANGEFOGENABLE 렌더링 스테이트를 TRUE 로 설정한다.

범위 베이스의 포그(안개:fog)는, Direct3D 에 의해, 트랜스 폼 & 라이팅의 사이에 계산된다. 「버텍스 포그(안개:fog)에 대하며」로 설명한 것처럼,Direct3D 트랜스 폼 & 라이팅 엔진을 사용하지 않는 어플리케이션은, 독자적으로 버텍스 포그(안개:fog)의 계산도 실시하지 않으면 안 된다. 이 경우, 범위 베이스의 포그(안개:fog) 계수를, 각 버텍스의 스펙큐러 성분의 알파 성분으로 설정한다.


흑백 라이트 맵

일부의 낡은 3D 가속기 보드에서는, 목적지 픽셀의 알파값을 사용하는 텍스쳐 블렌딩을 지원 하고 있지 않는 경우가 있다 ( 「알파 텍스쳐 블렌딩」을 참조할것). 이러한 어댑터에서는, 일반적으로 멀티 텍스쳐 블렌딩도 지원 하고 있지 않다. 이러한 어댑터로 어플리케이션을 실행하는 경우는, 멀티 패스 텍스쳐 블렌딩을 사용해 흑백 라이트 맵핑을 실행할 수 있다.

흑백 라이트 맵핑을 실행하려면 , 어플리케이션으로 라이팅 정보를 라이트 맵 텍스쳐의 알파 데이터에 저장 한다. 프로그램은, Direct3D 의 텍스쳐 필터링 기능을 사용해, 프리미티브 화면의 각 픽셀로부터, 라이트 맵의 대응하는 텍셀에의 맵핑을 실행한다. 프로그램으로, 전송원블렌딩 계수를 대응하는 텍셀의 알파값으로 설정한다.

[C++]

다음의 C++ 코드는, 어플리케이션으로 텍스쳐를 흑백 라이트 맵으로서 사용하는 방법을 나타낸다.

// 이 예에서는, lpD3DDev 은 IDirect3DDevice7 인터페이스에의 유효한 포인터로,
// lptexLightMap 는 흑백 라이트 맵 데이터를 포함한 텍스쳐에의
// 유효한 포인터이다고 한다.

// 라이트 맵 텍스쳐를 현재 텍스쳐로서 설정한다.
lpD3DDev->SetTexture(0, lptexLightMap);

// 색처리를 설정한다.
lpD3DDev->SetTextureStageState(0, D3DTSS_COLOROP,
       D3DTOP_SELECTARG1);

// 인수 1 을 색처리로 설정한다.
lpD3DDev->SetTextureStageState(0, D3DTSS_COLORARG1,
       D3DTA_TEXTURE | D3DTA_ALPHAREPLICATE);
[Visual Basic]

다음의 Visial Basic 코드는, 어플리케이션으로 텍스쳐를 흑백 라이트 맵으로서 사용하는 방법을 나타낸다.

'이 예에서는, d3dDev 는 Direct3DDevice7 오브젝트에의 유효한 참조이며,
' texLightMap 는 흑백 라이트 맵 데이터를 포함한 DirectDrawSurface7 텍스쳐에의
'유효한 참조이다고 한다.

'라이트 맵 텍스쳐를 현재 텍스쳐로서 설정한다.
Call d3dDev.SetTexture(0, texLightMap)

'색처리를 설정한다.
Call d3dDev.SetTextureStageState(0, D3DTSS_COLOROP, _
D3DTOP_SELECTARG1);

'인수 1 을 색처리로 설정한다.
Call d3dDev.SetTextureStageState(0, D3DTSS_COLORARG1, _
D3DTA_TEXTURE | D3DTA_ALPHAREPLICATE);

목적지 알파 블렌딩을 지원 하고 있지 않는 디스플레이 어댑터는, 보통 멀티 텍스쳐 블렌딩을 지원 하고 있지 않기 때문에, 이 예에서는, 모든 3D accelerator card로 사용할 수 있는 라이트 맵을 최초의 텍스쳐로서 설정해 있다. 또, 이 예에서는, 텍스쳐의 블렌딩 스테이지에 대한 컬러값을 설정해, 텍스쳐 데이터를 프리미티브의 기존의 색과 블렌드 하고 있다. 그 다음에, 입력 데이터로서 최초의 텍스쳐와 프리미티브의 기존의 색을 선택하고 있다.


gouraud shading

Direct3D 에서는, 다각형을 gouraud shading로 렌더링 하면 와, 버텍스의 법선 파라미터 및 라이팅 파라미터를 사용해 각 버텍스의 색을 계산한다. 그리고, 다각형의 면전체에 걸쳐서 색이 보간 된다 ( 「면법선 벡터와 버텍스 법선 벡터」를 참조할것). 보간은 선형적으로 행해진다. 예를 들어, 버텍스 1 의 색의 빨강 성분이 0.8 으로 버텍스 2 의 빨강 성분이 0.4 의 경우, Direct3D 의 라이팅 모듈은, gouraud shading 모드 및 RGB 색모델을 이용해, 2 개의 버텍스의 사이의 선의 중간점에 해당하는 픽셀에 0.6 의 빨강 성분을 할당한다.

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

gouraud shading 모드로, 날카로운 엣지를 가지는 오브젝트를 표시할 수도 있다. 상세한 것에 대하여는, 「면법선 벡터와 버텍스 법선 벡터」를 참조할것.


보폭 버텍스의 렌더링

[Visual Basic]

주 : 여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에서는, 보폭 버텍스의 렌더링은 지원 하고 있지 않다.

[C++]

보폭 버텍스는 간접적인 기법이므로, 어플리케이션으로 버텍스를 적절히 설정하려면 주의가 필요가 있다. 상세한 것에 대하여는, 「보폭 버텍스 포맷」섹션을 참조할것. 개발자는, 버텍스 성분을 D3DDRAWPRIMITIVESTRIDEDDATA 구조체에 저장 하고 있지 않는 것이 많다. 이러한 경우에서도, 렌더링 메소드가 반드시 실패하는 것은 아니지만, 지오메트리가 「없어진다」가능성이 있어, 트러블 슈팅이 곤란하게 된다.

다음의 코드는, 보폭 버텍스를 설정해 렌더링 하는 방법을 나타낸다.

//---------------------------------------------
// XYZ, 디퓨즈색, 및 2 조의 텍스쳐 좌표를 포함한다
// 커스텀 버텍스 포맷.
//---------------------------------------------
struct MTVERTEX
{
    FLOAT x, y, z;
    DWORD dwColor;
    FLOAT tuBase, tvBase;
    FLOAT tuLightMap, tvLightMap;
};

// 커스텀 버텍스의 배열을 생성 한다.
MTVERTEX g_avVertices[36];
// 배열에 버텍스를 저장 한다.
//  (인덱스 0 의 버텍스)
//  .
//  .
//  .
//  (인덱스 35 의 버텍스)

// 정의가 끝난 커스텀 버텍스의 배열을 사용해,
// 보폭 버텍스를 구축한다.
D3DDRAWPRIMITIVESTRIDEDDATA g_StridedData;

// 교대로 배치한 각종 컴퍼넌트의 주소를
// 대응하는 보폭 멤버에 할당한다.
g_StridedData.position.lpvData          = &g_avWallVertices[24]. x;
g_StridedData.diffuse.lpvData           = &g_avWallVertices[24]. dwColor;
g_StridedData.textureCoords[0]. lpvData  = &g_avWallVertices[24]. tuBase;
g_StridedData.textureCoords[1]. lpvData  = &g_avWallVertices[24]. tuLightMap;
g_StridedData.position.dwStride         = sizeof(MTVERTEX);
g_StridedData.diffuse.dwStride          = sizeof(MTVERTEX);
g_StridedData.textureCoords[0]. dwStride = sizeof(MTVERTEX);
g_StridedData.textureCoords[1]. dwStride = sizeof(MTVERTEX);

// 복수의 텍스쳐 블렌딩 (조정)으로 버텍스를 렌더링 한다.
g_pd3dDevice->SetTextureStageState( 1, D3DTSS_COLOROP, D3DTOP_MODULATE );
g_pd3dDevice->SetTexture( 0, g_BaseTextureMap);
g_pd3dDevice->SetTexture( 1, g_LightMap);
g_pd3dDevice->DrawPrimitiveStrided( D3DPT_TRIANGLELIST,
                        D3DFVF_XYZ|D3DFVF_DIFFUSE|D3DFVF_TEX2,
                        &g_StridedData, 12, NULL );


구(공)체 환경 맵의 텍스쳐 좌표

환경 맵핑의 대상이 되는 각 버텍스로 지정하는 텍스쳐 좌표는, 텍스쳐를 만곡한 표면에 비치는 왜곡의 함수로서 처리할 필요가 있다. 어플리케이션에서는, 각 버텍스의 텍스쳐 좌표를 계산해, 희망의 이펙트를 실현되지 않으면 안 된다. 텍스쳐 좌표를 간단하고 효과적으로 생성하는 방법은, 버텍스 법선을 입력으로서 사용하는 것이다. 방법에는 몇 종류인가 있지만, 다음의 공식은, 구(공)체 맵에 의한 환경 맵핑을 실행하는 어플리케이션으로 공통의 공식이다.

이 공식에서는,u 및 v 는 계산하는 텍스쳐 좌표,Nx 및 Ny 는 카메라 공간의 버텍스 법선의 x 및 y 성분이다. 이 공식은 단순하지만, 유효하다. 법선에 정방향의 x 성분이 있는 경우, 법선은 우측향을 가리키고 있어u 좌표는 텍스쳐를 적절히 처리할 수 있도록(듯이) 조정된다. v 좌표도 마찬가지, 정방향의 y 는, 법선이 윗방향을 가리키고 있는 것을 나타낸다. 물론, 각 성분의 부의 값에 대해서는 이 반대가 성립된다.

법선이 직접 카메라를 가리키고 있는 경우, 결과의 좌표에는 왜곡이 생기지 않는다. 양쪽 모두의 좌표에 +0. 5 바이어스를 더하면(자), 왜곡이 없는 점은 구(공)체 맵의 중앙에 배치되어(0, 0, z)의 버텍스 법선에 의해 이 점이 처리된다. 이 공식에서는, 법선의 z 성분은 고려되지 않는 것에 주의한다. 다만, 이 공식을 사용하는 어플리케이션에서는, 정방향의 z 요소가 있는 법선을 가지는 버텍스를 생략 하는 것으로 계산을 최적화할 수 있다. 이러한 처리를 하는 것은, 카메라 공간에서 법선이 카메라로부터 멀어질 방향 (z 의 정방향)을 가리키고 있는 경우에, 오브젝트의 렌더링시에 버텍스가 생략해지기 때문에 있다.


텍스쳐 필터링 스테이트

[Visual Basic]

주 : 여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 의 경우, 어플리케이션에서는,Direct3DDevice7.SetTextureStageState 메소드를 사용해, 텍스쳐 필터링 처리를 설정할 필요가 있다.

[C++]

주 : 종래의 렌더링 스테이트 D3DRENDERSTATE_TEXTUREMAG, D3DRENDERSTATE_TEXTUREMIN, 및 D3DRENDERSTATE_ANISOTROPY 는, DirectX 7.0 릴리스에서는 사용되지 않는다.

어플리케이션에서는,D3DTSS_MAGFILTER ,D3DTSS_MINFILTER , 및 D3DTSS_MAXANISOTROPY 텍스쳐 스테이지 스테이트를 사용해, 텍스쳐 필터링을 제어할 필요가 있다.


텍스쳐 좌표의 자동 생성의 구성

Platform SDK: DirectX

텍스쳐 좌표의 자동 생성의 구성

[C++]

C++ 의 경우, (D3DTEXTURESTAGESTATETYPE 열거형으로부터의) D3DTSS_TEXCOORDINDEX 텍스쳐 스테이지 스테이트를 사용해, 텍스쳐 좌표의 생성 방법을 제어한다.

[Visual Basic]

Visual Basic 의 경우, (CONST_D3DTEXTURESTAGESTATETYPE 열거로부터의) D3DTSS_TEXCOORDINDEX 텍스쳐 스테이지 스테이트를 사용해, 텍스쳐 좌표의 생성 방법을 제어한다.

보통, 이 스테이트는, 버텍스 포맷으로 encode 된 특정의 텍스쳐 좌표 세트를 사용하도록(듯이) 시스템에 알린다. 이 스테이트에 할당하는 값안에, D3DTSS_TCI_CAMERASPACENORMAL, D3DTSS_TCI_CAMERASPACEPOSITION, 또는 D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR 플래그를 포함했을 경우, 시스템으로 실행되는 처리는 크게 달라 진다. 이러한 플래그의 어느쪽이든에서도 존재하고 있을 때, 텍스쳐 스테이지는 버텍스 포맷의 텍스쳐 좌표를 무시해, 시스템이 생성하는 좌표를 우선한다. 각 플래그의 의미는, 다음과 같다.

D3DTSS_TCI_CAMERASPACENORMAL
버텍스 법선을 입력 텍스쳐 좌표로서 사용한다. 버텍스 법선은 카메라 공간에 트랜스 폼 된다.
D3DTSS_TCI_CAMERASPACEPOSITION
버텍스 위치 좌표를 입력 텍스쳐 좌표로서 사용한다. 버텍스 위치 좌표가 카메라 공간에 트랜스 폼 된다.
D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR
반사 벡터를 입력 텍스쳐 좌표로서 사용한다. 반사 벡터가 카메라 공간에 트랜스 폼 된다. 반사 벡터는, 입력 버텍스 위치 좌표와 법선 벡터로부터 계산된다.

이러한 플래그는 서로 배타적이기 때문에, 조합해 사용할 수 없다. 이러한 플래그의 어느쪽이든을 사용하는 경우는, 텍스쳐 랩핑 모드를 결정하기 위해서(때문에) 시스템으로 사용하는 인덱스값을 지정할 수 있다.

[C++]

다음의 코드는, C++ 에서의 이러한 플래그의 사용 방법을 나타낸다.

// 이 예에서는, lpd3dDevice 변수는 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다.

// 이 텍스쳐 스테이지의 입력 텍스쳐 좌표로서
// 버텍스 위치 좌표 (카메라 공간)를 사용해,
// D3DRENDERSTATE_WRAP1 렌더링 스테이트의 랩 모드 세트를 사용한다.
lpd3dDevice->SetTextureStageState( 0, D3DTSS_TEXCOORDINDEX,
D3DTSS_TCI_CAMERASPACEPOSITION | 1 );
[Visual Basic]

다음의 코드는, Visual Basic 에서의 이러한 플래그의 사용 방법을 나타낸다.

'이 예에서는, d3dDevice 변수는 Direct3DDevice7 오브젝트에의
'유효한 참조이다.

'이 텍스쳐 스테이지의 입력 텍스쳐 좌표로서
'버텍스 위치 좌표 (카메라 공간)를 사용해,
' D3DRENDERSTATE_WRAP1 렌더링 스테이트의 랩 모드 세트를 사용한다.
Call d3dDevice.SetTextureStageState(0, D3DTSS_TEXCOORDINDEX, _
D3DTSS_TCI_CAMERASPACEPOSITION Or 1)

주 : 자동 생성된 텍스쳐 좌표는, 텍스쳐 좌표 트랜스 폼의 입력값으로서 매우 편리하고, 또 큐브 환경 맵의 3 요소 벡터를 계산할 필요가 없다고 하는 점에서도 편리하다.

참조

텍스쳐 좌표 트랜스 폼,큐브 환경 맵


지오메트리 블렌딩의 유효화

[C++]

디폴트에서는, 지오메트리 블렌딩은 무효이다. 지오메트리 블렌딩을 유효하게 하려면 ,IDirect3DDevice7::SetRenderState 메소드를 호출해 D3DRENDERSTATE_VERTEXBLEND 렌더링 스테이트를 D3DVERTEXBLENDFLAGS 열거형으로부터의 값으로 설정한다. 다음의 코드는, 2 개의 월드 행렬간에서 블렌드하기 위한 , 렌더링 스테이트의 설정을 나타낸다.

pd3dDevice->SetRenderState( D3DRENDERSTATE_VERTEXBLEND, D3DVBLEND_1WEIGHT );

D3DRENDERSTATE_VERTEXBLEND 가 D3DVBLEND_DISABLE 이외의 값으로 설정되어 있는 경우는, 버텍스 포맷에 적절한 개수의 블렌딩의 중량감이 포함되어 있다고 보여진다. 적절한 버텍스 포맷을 생성 하는 것, 및 그 포맷의 올바른 기술을 Direct3D 렌더링 메소드에 제공하는 것은 개발자의 책임이다. 상세한 것에 대하여는, 「블렌딩용의 버텍스의 정의」를 참조할것.

지오메트리 블렌딩이 유효하게 되어 있는 경우, DrawPrimitive 렌더링 메소드로 렌더링 되는 모든 오브젝트에 대해서 지오메트리 블렌딩이 실행된다.

[Visual Basic]

디폴트에서는, 지오메트리 블렌딩은 무효이다. 지오메트리 블렌딩을 유효하게 하려면 ,Direct3DDevice7.SetRenderState 메소드를 호출해 D3DRENDERSTATE_VERTEXBLEND 렌더링 스테이트를 CONST_D3DVERTEXBLENDFLAGS 열거로부터의 값으로 설정한다. 다음의 코드는, 2 개의 월드 행렬간에서 블렌드하기 위한 , 렌더링 스테이트의 설정을 나타낸다.

Call d3dDevice.SetRenderState(D3DRENDERSTATE_VERTEXBLEND, D3DVBLEND_1WEIGHT)

D3DRENDERSTATE_VERTEXBLEND 가 D3DVBLEND_DISABLE 이외의 값으로 설정되어 있는 경우는, 버텍스 포맷에 적절한 개수의 블렌딩의 중량감이 포함되어 있다고 보여진다. 적절한 버텍스 포맷을 생성 하는 것, 및 그 포맷의 올바른 기술을 Direct3D 렌더링 메소드에 제공하는 것은 개발자의 책임이다. 상세한 것에 대하여는, 「블렌딩용의 버텍스의 정의」를 참조할것.

지오메트리 블렌딩이 유효하게 되어 있는 경우, DrawPrimitive 렌더링 메소드로 렌더링 되는 모든 오브젝트에 대해서 지오메트리 블렌딩이 실행된다.


머트리얼 프로퍼티의 취득

[C++]

디바이스에 대해서 IDirect3DDevice7::GetMaterial 메소드를 호출해, 렌더링 디바이스로 현재 사용하고 있는 머트리얼 프로퍼티를 취득한다. IDirect3DMaterial7::SetMaterial 메소드의 경우와는 달라,GetMaterial 에서는 준비는 필요없다. GetMaterial 메소드에는,D3DMATERIAL7 구조체의 주소를 지정한다. 이 메소드는, 종료전에 이 구조체에 현재의 머트리얼 프로퍼티의 정보를 기입한다.

// 이 예에서는, lpd3dDev 변수는 IDerect3DDevice7 인터페이스에의
// 유효한 포인터이다고 한다.
HRESULT hr;
D3DMATERIAL7 mat;

hr = lpd3dDev->GetMaterial(&mat);
if(FAILED(hr))
    {
// 에러 처리 코드
    }
[Visual Basic]

디바이스에 대해서 Direct3DDevice7.GetMaterial 메소드를 호출해, 렌더링 디바이스로 현재 사용하고 있는 머트리얼 프로퍼티를 취득한다. Direct3DDevice7.SetMaterial 메소드의 경우와는 달라,GetMaterial 에서는 준비는 필요없다. GetMaterial 메소드에는,D3DMATERIAL7 형의 변수를 지정한다. 이 메소드는, 종료전에 이 변수에 현재의 머트리얼 프로퍼티의 정보를 기입한다.

'이 예에서는, d3dDev 변수에 Direct3DDevice7 오브젝트에의
'유효한 참조가 저장 되고 있다고 한다.
On Local Error Resume Next
Dim mat As D3DMATERIAL7

Call d3dDev.GetMaterial(mat)
If Err.Number <> DD_OK Then
'에러 처리 코드
End If


DrawPrimitive 메소드

[C++]

Direct3D 에는, 1 회의 호출로 프리미티브 및 인덱스 첨부 프리미티브를 렌더링 할 수 있는 몇개의 메소드가 있다. IDirect3DDevice7 인터페이스에 있는 모든 렌더링 메소드는, 어플리케이션으로 사용하는 버텍스의 종류를 기술하는유연한 버텍스 포맷 플래그의 편성을 받는다. 이 플래그는, 시스템이 적용하는 지오메트리 파이프라인의 부분도 결정한다 (이것은 IDirect3DDevice2 의 메소드와는 달라, 이 경우의 메소드는,D3DPRIMITIVETYPE 열거의 멤버에 의해 식별하는 구체적인 버텍스 포맷만 받는다). 이러한 상세한 것에 대하여는, 「버텍스 포맷」을 참조할것.

DrawPrimitive 패밀리의 렌더링 메소드에는, 이하와 같이 그룹 나누고 할 수 있는 렌더링 메소드가 있다.

기본적인 렌더링
IDirect3DDevice7::DrawPrimitive 및 IDirect3DDevice7::DrawIndexedPrimitive
버텍스 버퍼 렌더링
IDirect3DDevice7::DrawPrimitiveVB 및 IDirect3DDevice7::DrawIndexedPrimitiveVB
보폭 버텍스
IDirect3DDevice7::DrawPrimitiveStrided 및 IDirect3DDevice7::DrawIndexedPrimitiveStrided . 버텍스 버퍼는, 보폭 버텍스의 렌더링에 사용할 수 있지만, 버텍스의 처리에는 IDirect3DVertexBuffer7::ProcessVerticesStrided 메소드를 사용할 필요가 있다.

프리미티브를 렌더링 하면 와, 대응하는 메소드는, 렌더링 하는 프리미티브의 종류 (삼각형 스트립, 삼각형 리스트 등), 버텍스 포맷, 렌더링 방법을 정의하는 플래그, 및 버텍스에 관한 정보를 나타내는 파라미터를 받는다. 이러한 플래그와 이펙트에 대해서는, 렌더링 메소드의 설명에 기술되고 있다.

메소드로 지정하는 버텍스의 수는, 렌더링 하는 프리미티브의 종류에 따라서 다르기 (위해)때문에 주의 해야 한다. 예를 들어, 선리스트를 렌더링 하는 경우, 1 개의 라인을 정의하는 적어도 2 개의 버텍스가 필요해, 버텍스의 총수는 짝수가 아니면 안된다. 삼각형 리스트의 경우도 마찬가지, 적어도 3 개의 버텍스가 필요해, 버텍스의 총수는 3 의 배수가 아니면 안된다. 그 외의 종류의 프리미티브의 버텍스수에 대해서는, 「프리미티브의 종류」 및 「D3DPRIMITIVETYPE 」를 참조할것.

버텍스 버퍼, 및 렌더링에 버텍스 버퍼를 사용하는 메소드에 의해, 퍼포먼스와 편리한 사용이 향상해, 독자적인 데이터 구조에 의한 버텍스의 렌더링이 개선된다. 상세한 것에 대하여는, 「버텍스 버퍼」를 참조할것.

[Visual Basic]

Direct3D 에는, Visual Basic 어플리케이션으로 1 회의 호출로 프리미티브를 렌더링 할 수 있는 몇개의 메소드가 있다. Direct3DDevice7 클래스에 있는 모든 렌더링 메소드는, 어플리케이션으로 사용하는 버텍스의 종류를 기술하는유연한 버텍스 포맷 플래그의 편성을 받는다. 이 플래그는 시스템이 적용하는 지오메트리 파이프라인의 부분도 결정한다. 이러한 상세한 것에 대하여는, 「버텍스 포맷」을 참조할것.

DrawPrimitive 패밀리의 렌더링 메소드에는, 이하와 같이 그룹 나누고 할 수 있는 렌더링 메소드가 있다.

기본적인 렌더링
Direct3DDevice7.DrawPrimitive 및 Direct3DDevice7.DrawIndexedPrimitive
버텍스 버퍼 렌더링
Direct3DDevice7.DrawPrimitiveVB 및 Direct3DDevice7.DrawIndexedPrimitiveVB

프리미티브를 렌더링 하면 와, 대응하는 메소드는, 렌더링 하는 프리미티브의 종류 (삼각형 스트립, 삼각형 리스트 등), 버텍스 포맷, 렌더링 방법을 정의하는 플래그, 및 버텍스에 관한 정보를 나타내는 파라미터를 받는다. 이러한 플래그와 이펙트에 대해서는, 렌더링 메소드의 설명에 기술되고 있다.

메소드로 지정하는 버텍스의 수는, 렌더링 하는 프리미티브의 종류에 따라서 다르기 (위해)때문에 주의 해야 한다. 예를 들어, 선리스트를 렌더링 하는 경우, 1 개의 라인을 정의하는 적어도 2 개의 버텍스가 필요해, 버텍스의 총수는 짝수가 아니면 안된다. 삼각형 리스트의 경우도 마찬가지, 적어도 3 개의 버텍스가 필요해, 버텍스의 총수는 3 의 배수가 아니면 안된다. 그 외의 종류의 프리미티브의 버텍스수에 대해서는, 「프리미티브의 종류」 및 「CONST_D3DPRIMITIVETYPE 」를 참조할것.

버텍스 버퍼, 및 렌더링에 버텍스 버퍼를 사용하는 메소드에 의해, 퍼포먼스와 편리한 사용이 향상해, 독자적인 데이터 구조에 의한 버텍스의 렌더링이 개선된다. 상세한 것에 대하여는, 「버텍스 버퍼」를 참조할것.

주 : DirectX for Visual Basic 에서는, 보폭 버텍스의 렌더링은 지원 하고 있지 않다.


텍스쳐 애드레싱에 있어서의 디바이스 제한

[C++]

시스템에서는, 일반적으로 0.0 으로 1.0 을 포함한 0.0 ~ 1.0 의 범위외의 텍스쳐 좌표를 허가하고 있지만, 그 범위로부터의 일탈이 어디까지 허용 될까는, 하드웨어 제한에 따라서 다른 것이 많다. 디바이스 기능을 취득 하면 와, 렌더링 디바이스는 D3DDEVICEDESC7 구조체의 dwMaxTextureRepeat 멤버로 이 제한을 알린다. 이 멤버의 값은, 디바이스로 허용 되는 텍스쳐 좌표의 전범위를 나타낸다. 예를 들어, 이 값이 128 의 경우, 텍스쳐 좌표는 -128. 0 ~ +128. 0 의 범위내에서 입력해야 한다. 이 범위외의 텍스쳐 좌표를 건네주는 것은 무효이다. 텍스쳐 좌표의 자동 생성 및 텍스쳐 좌표 트랜스 폼에 의해 생성되는 텍스쳐 좌표에 대해서도, 같은 제한이 적용된다.

dwMaxTextureRepeat 의 해석은, 또, D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE 능력 비트에 의해 영향을 받는다. 이 비트를 설정했을 경우,D3DDEVICEDESC7 의 dwMaxTextureRepeat 멤버는 기술대로 사용된다. 그러나, D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE 를 설정하고 있지 않는 경우, 텍스쳐 반복 제한은 텍스쳐 좌표가 가리키는 텍스쳐의 사이즈에 의존한다. 이 경우,dwMaxTextureRepeat 는, 현재 텍스쳐의 사이즈 (상세한 최대 레벨)에 의해 조정해, 유효한 텍스쳐 범위를 계산해야 한다. 예를 들어, 텍스쳐의 사이즈가 32,dwMaxTextureRepeat 값이 512 의 경우, 실제로 유효한 텍스쳐 좌표의 범위는,512/32 = 16 이다. 따라서, 이 디바이스의 텍스쳐 좌표는,-16. 0 ~ +16. 0 의 범위내에 없으면 안 된다.

[Visual Basic]

시스템에서는, 일반적으로 0.0 으로 1.0 을 포함한 0.0 ~ 1.0 의 범위외의 텍스쳐 좌표를 허가하고 있지만, 그 범위로부터의 일탈이 어디까지 허용 될까는, 하드웨어 제한에 따라서 다른 것이 많다. 디바이스 기능을 취득 하면 와, 렌더링 디바이스는 D3DDEVICEDESC7 형의 lMaxTextureRepeat 멤버로 이 제한을 알린다. 이 멤버의 값은, 디바이스로 허용 되는 텍스쳐 좌표의 전범위를 나타낸다. 예를 들어, 이 값이 128 의 경우, 텍스쳐 좌표는 -128. 0 ~ +128. 0 의 범위내에서 입력해야 한다. 이 범위외의 텍스쳐 좌표를 건네주는 것은 무효이다. 텍스쳐 좌표의 자동 생성 및 텍스쳐 좌표 트랜스 폼에 의해 생성되는 텍스쳐 좌표에 대해서도, 같은 제한이 적용된다.

lMaxTextureRepeat 의 해석은, 또, D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE 능력 비트에 의해 영향을 받는다. 이 비트를 설정했을 경우,D3DDEVICEDESC7 의 멤버 lMaxTextureRepeat 는 기술대로 사용된다. 그러나, D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE 를 설정하고 있지 않는 경우, 텍스쳐 반복 제한은 텍스쳐 좌표가 가리키는 텍스쳐의 사이즈에 의존한다. 이 경우,lMaxTextureRepeat 는, 현재 텍스쳐의 사이즈 (상세한 최대 레벨)에 의해 조정해, 유효한 텍스쳐 범위를 계산해야 한다. 예를 들어, 텍스쳐의 사이즈가 32,lMaxTextureRepeat 값이 512 의 경우, 실제로 유효한 텍스쳐 좌표의 범위는,512/32 = 16 이다. 따라서, 이 디바이스의 텍스쳐 좌표는,-16. 0 ~ +16. 0 의 범위내에 없으면 안 된다.


삼각형 리스트

Platform SDK: DirectX

삼각형 리스트

삼각형 리스트란, 각각의 삼각형의 리스트이다. 삼각형은 서로 인접하고 있어도 떨어져 있어도 괜찮다. 삼각형 리스트에는, 적어도 3 개의 버텍스가 필요하다. 버텍스의 총수는 3 의 배수가 아니면 안된다.

분리한 파츠로부터 구성되는 오브젝트를 생성 하면나무는, 삼각형 리스트를 사용한다. 예를 들어, 3D 게임에서 전자력계벽을 생성 하려면 , 단독의 작은 삼각형을 다수 모은 리스트를 지정한다. 다음에, 이 삼각형 리스트에 머트리얼이나 텍스쳐를 적용해 미츠를 출발하고 있도록(듯이) 보이게 한다. 벽의 삼각형 각각이 빛나 보이게 된다. 플레이어가 전자력계라고는 이렇게 보일 것이라고 기대 하면 우리에, 벽의 배후의 장면이 삼각형의 사이의 틈새를 통해 부분적으로 보이게 된다.

또, 삼각형 리스트는, gouraud shading로 음영을 붙인, 날카로운 엣지를 가지는 프리미티브를 생성 할 경우에 편리하다. 「면법선 벡터와 버텍스 법선 벡터」를 참조할것.

[C++]

C++ 에서는, 다음의 코드로 가리키도록(듯이), 버텍스의 배열에 값을 설정해 삼각형 리스트를 생성 한다.

const DWORD TOTAL_VERTS=6;
D3DVERTEX lpVerts[TOTAL_VERTS];

lpVerts[0] = D3DVERTEX(D3DVECTOR(-5,-5, 0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[1] = D3DVERTEX(D3DVECTOR(0,5,0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[2] = D3DVERTEX(D3DVECTOR(5,-5, 0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[3] = D3DVERTEX(D3DVECTOR(10,5,0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[4] = D3DVERTEX(D3DVECTOR(15,-5, 0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[5] = D3DVERTEX(D3DVECTOR(20,5,0), D3DVECTOR(0,0,-1), 0,0);

IDirect3DDevice7::DrawPrimitive 메소드를 사용해 삼각형 리스트를 렌더링 한다. 다음의 코드는,IDirect3DDevice7::DrawPrimitive 를 사용해, 위에의 예의 삼각형 리스트를 드로잉(Drawing) 하는 방법을 나타낸다. IDirect3DDevice7::DrawPrimitive 의 호출은,IDirect3DDevice7::BeginScene 와 IDirect3DDevice7::EndScene 의 사이에 실시할 필요가 있다.

HRESULT hResult;
// 이 코드에서는, lpDirect3DDevice 은 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다고 한다.
hResult =
    lpDirect3DDevice->DrawPrimitive(D3DPT_TRIANGLELIST,
                                      D3DFVF_VERTEX,
                                      lpVerts,
                                      TOTAL_VERTS,
                                      D3DDP_WAIT);
[Visual Basic]

Visual Basic 에서는, 다음의 코드로 가리키도록(듯이), 버텍스의 배열에 값을 설정해 삼각형 리스트를 생성 한다.

'이 코드에서는, dx 는 DirectX7 오브젝트에의
'유효한 참조이다고 한다.
On Local Error Resume Next
Const TOTAL_VERTS As Integer = 6
Dim Verts(TOTAL_VERTS) As D3DVERTEX

Verts(0) = dx.CreateD3DVertex(-5, -5, 0, 0, 0, -1, 0, 0)
Verts(1) = dx.CreateD3DVertex(0, 5, 0, 0, 0, -1, 0, 0)
Verts(2) = dx.CreateD3DVertex(5, -5, 0, 0, 0, -1, 0, 0)
Verts(3) = dx.CreateD3DVertex(10, 5, 0, 0, 0, -1, 0, 0)
Verts(4) = dx.CreateD3DVertex(15, -5, 0, 0, 0, -1, 0, 0)
Verts(5) = dx.CreateD3DVertex(20, 5, 0, 0, 0, -1, 0, 0)

Direct3DDevice7.DrawPrimitive 메소드를 사용해 삼각형 리스트를 렌더링 한다. 다음의 예는,Direct3DDevice7.DrawPrimitive 를 사용해, 위에의 예의 삼각형 리스트를 드로잉(Drawing) 하는 방법을 나타낸다. Direct3DDevice7.DrawPrimitive 의 호출은,Direct3DDevice7.BeginScene 와 Direct3DDevice7.EndScene 의 사이에 실시할 필요가 있다.

'이 코드에서는, d3ddev 는 Direct3DDevice7 오브젝트에의
'유효한 참조이다고 한다.
Call d3ddev.DrawPrimitive(D3DPT_TRIANGLELIST, _
D3DFVF_VERTEX, _
Verts(0), _
TOTAL_VERTS, _
                          D3DDP_WAIT)

If Err.Number <> DD_OK Then
'에러 처리 코드
End If

다음의 그림은, 결과적으로 드로잉(Drawing) 되는 삼각형 리스트를 나타낸다.


알파 실험 스테이트

[C++]

C++ 어플리케이션에서는, 알파 실험을 사용해, 언제 픽셀을 렌더링 타겟 표면에 기입하는지를 제어한다. D3DRENDERSTATE_ALPHATESTENABLE 열거값을 사용하는 것으로써, 어플리케이션에서는, 알파 테스트 함수에 근거해 각 픽셀을 테스트할 수 있도록(듯이) 현재의 Direct3D 디바이스를 설정한다. 테스트가 성공하면(자), 픽셀이 표면에 기입해진다. 테스트가 실패 하면, 픽셀은 무시된다. 알파 테스트 함수는,D3DRENDERSTATE_ALPHAFUNC 열거값으로 선택한다. D3DRENDERSTATE_ALPHAREF 렌더링 스테이트를 사용하는 것으로써, 어플리케이션에서는, 비교하는 모든 픽셀에 참조 알파값을 설정한다.

알파 실험은, 보통, 투명하게 가까운 오브젝트를 라스터화할 때의 퍼포먼스를 개선하기 위해서 사용한다. 라스터화하는 색데이터가 지정의 픽셀 (D3DPCMPCAPS_GREATEREQUAL)보다 불투명의 경우, 픽셀이 기입해진다. 그렇지 않은 경우는, 래스터라이저는 픽셀을 무시해, 2 색의 블렌드에 필요한 처리를 생략 한다. 다음의 코드는, 지정의 비교 함수가 지원 되고 있는지 어떤지를 조사해 지원 되고 있는 경우는, 렌더링의 퍼포먼스 개선에 필요한 비교 함수의 파라미터를 설정한다.

// 이 예에서는, pd3dDeviceDesc 는,
// 전의 IDirect3DDevice7::GetCaps 의 호출에 의해 저장 되었다
// D3DDEVICEDESC7 구조체이다고 한다.
if (pd3dDeviceDesc.dpcTriCaps.dwAlphaCmpCaps & D3DPCMPCAPS_GREATEREQUAL)
{
    dev->SetRenderState( D3DRENDERSTATE_ALPHAREF, (DWORD) 0x00000001);
    dev->SetRenderState( D3DRENDERSTATE_ALPHATESTENABLE, TRUE );
    dev->SetRenderState( D3DRENDERSTATE_ALPHAFUNC, D3DCMP_GREATEREQUAL );
}

// 비교 함수가 지원되어 있지 않은 경우에도 렌더링을 실행한다.
// 다만, 퍼포먼스는 개선되지 않는다.

모든 하드웨어가 알파 실험 기능을 지원 하고 있는 것은 아니다. 디바이스 기능을 조사하려면 ,IDirect3DDevice7::GetCaps 메소드를 호출한다. 디바이스 기능을 취득한 후, 사용하는 비교 함수의 D3DPRIMCAPS 구조체 (관련지을 수 있었던 D3DDEVICEDESC7 구조체에 저장 되고 있다)의 dwAlphaCmpCaps 멤버를 조사한다. dwAlphaCmpCaps 멤버가 D3DPCMPCAPS_ALWAYS 마셔, 또는 D3DPCMPCAPS_NEVER 마셔 포함하고 있는 경우, 드라이버는 알파 테스트를 전혀 지원 하고 있지 않다.

[Visual Basic]

Visual Basic 로 기술된 어플리케이션에서는, 알파 실험을 사용해, 언제 픽셀을 렌더링 타겟 표면에 기입하는지를 제어한다. D3DRENDERSTATE_ALPHATESTENABLE 열거값을 사용하는 것으로써, 어플리케이션에서는, 알파 테스트 함수에 근거해 각 픽셀을 테스트할 수 있도록(듯이) 현재의 Direct3D 디바이스를 설정한다. 테스트가 성공하면(자), 픽셀이 표면에 기입해진다. 테스트가 실패 하면, 픽셀은 무시된다. 알파 테스트 함수는,D3DRENDERSTATE_ALPHAFUNC 열거값으로 선택한다. D3DRENDERSTATE_ALPHAREF 렌더링 스테이트를 사용하는 것으로써, 어플리케이션에서는, 비교하는 모든 픽셀에 참조 알파값을 설정한다.

알파 실험은, 보통, 투명하게 가까운 오브젝트를 라스터화할 때의 퍼포먼스를 개선하기 위해서 사용한다. 라스터화하는 색데이터가 지정의 픽셀 (D3DPCMPCAPS_GREATEREQUAL)보다 불투명하게 가까운 경우, 픽셀이 기입해진다. 그렇지 않은 경우는, 래스터라이저는 픽셀을 무시해, 2 색의 블렌드에 필요한 처리를 생략 한다. 다음의 코드는, 지정의 비교 함수가 지원 되고 있는지 어떤지를 조사해 지원 되고 있는 경우는, 렌더링의 퍼포먼스 개선에 필요한 비교 함수의 파라미터를 설정한다.

'이 예에서는, d3dDeviceDesc 는,
' Direct3DDevice7::GetCaps 의 호출에 의해 저장 되었다
' D3DDEVICEDESC7 형이다고 한다.
If (d3dDeviceDesc.dpcTriCaps.lAlphaCmpCaps And D3DPCMPCAPS_GREATEREQUAL) Then
        Call dev.SetRenderState(D3DRENDERSTATE_ALPHAREF, &H1)
        Call dev.SetRenderState(D3DRENDERSTATE_ALPHATESTENABLE, True)
        Call dev.SetRenderState(D3DRENDERSTATE_ALPHAFUNC, D3DCMP_GREATEREQUAL)
End If

'비교 함수가 지원되어 있지 않은 경우에도 렌더링을 실행한다.
'다만, 퍼포먼스는 개선되지 않는다.

모든 하드웨어가 알파 실험 기능을 지원 하고 있는 것은 아니다. 디바이스 기능을 조사하려면 ,Direct3DDevice7.GetCaps 메소드를 호출한다. 디바이스의 기능을 검색한 후, 사용하는 비교 함수의 D3DPRIMCAPS 형 (관련지을 수 있었던 D3DDEVICEDESC7 형에 저장 되고 있다)의 lAlphaCmpCaps 멤버를 조사한다. lAlphaCmpCaps 멤버가 D3DPCMPCAPS_ALWAYS 마셔, 또는 D3DPCMPCAPS_NEVER 마셔 포함하고 있는 경우, 드라이버는 알파 테스트를 전혀 지원 하고 있지 않다.


텍스쳐 애드레싱 스테이트

[Visual Basic]

주 : 여기에서는, C 또는 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 에서는,Direct3DDevice7.SetTextureStageState 메소드를 사용해 텍스쳐 애드레싱 스테이트를 설정할 필요가 있다.

[C++]

D3DRENDERSTATE_TEXTUREADDRESS, D3DRENDERSTATE_TEXTUREADDRESSU, 및 D3DRENDERSTATE_TEXTUREADDRESSV 렌더링 스테이트는, 현재는 사용되어 있지 않다. 이것들은,D3DTSS_ADDRESS ,D3DTSS_ADDRESSU , 및 D3DTSS_ADDRESSV 텍스쳐 스테이지 스테이트로 옮겨지고 있다.

주 : IDirect3DDevice7 인터페이스에서는, 종래의 D3DRENDERSTATE_TEXTUREADDRESS, D3DRENDERSTATE_TEXTUREADDRESSU, 및 D3DRENDERSTATE_TEXTUREADDRESSV 렌더링 스테이트는 인식되지 않는다. 이러한 렌더링 스테이트를 사용 하면 실패한다.


삼각형 팬

Platform SDK: DirectX

삼각형 팬

삼각형 팬이란, 다음의 그림에 나타내도록(듯이), 모든 삼각형이 1 개의 버텍스를 공유 하면 말하는 점을 제외해서는, 삼각형 스트립에 유사한 것이다.

시스템에서는, 버텍스 v2, v3, v1 를 사용해 최초의 삼각형을, v3, v4, v1 를 사용해 2 번째의 삼각형을, v4, v5, v1 를 사용해 3 번째의 삼각형을, 이라고 하는 순서로 드로잉(Drawing) 해 나간다 (flat shading가 유효한 경우, 삼각형은 최초의 버텍스의 색으로 쉐이딩 된다).

[C++]

C++ 어플리케이션에서는, 다음의 코드로 가리키도록(듯이), 버텍스의 배열에 값을 설정해 삼각형 팬을 생성 한다.

const DWORD TOTAL_VERTS=6;
D3DVERTEX lpVerts[TOTAL_VERTS];

lpVerts[0] = D3DVERTEX(D3DVECTOR(0,0,0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[1] = D3DVERTEX(D3DVECTOR(-5,-5, 0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[2] = D3DVERTEX(D3DVECTOR(-3, 7,0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[3] = D3DVERTEX(D3DVECTOR(0,10,0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[4] = D3DVERTEX(D3DVECTOR(3,7,0), D3DVECTOR(0,0,-1), 0,0);
lpVerts[5] = D3DVERTEX(D3DVECTOR(5,5,0), D3DVECTOR(0,0,-1), 0,0);

이 후,IDirect3DDevice7::DrawPrimitive 메소드를 사용해 삼각형 팬을 렌더링 할 수 있다. 다음의 코드는,IDirect3DDevice7::DrawPrimitive 를 사용해, 위에의 예의 삼각형 팬을 드로잉(Drawing) 하는 방법을 나타낸다. IDirect3DDevice7::DrawPrimitive 의 호출은,IDirect3DDevice7::BeginScene 와 IDirect3DDevice7::EndScene 의 사이에 실시할 필요가 있다.

HRESULT hResult;
// 이 코드에서는, lpDirect3DDevice 은 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다고 한다.
hResult =
    lpDirect3DDevice->DrawPrimitive(D3DPT_TRIANGLEFAN,
                                     D3DFVF_VERTEX,
                                     lpVerts,
                                     TOTAL_VERTS,
                                     D3DDP_WAIT);
[Visual Basic]

Visual Basic 어플리케이션에서는, 다음의 코드로 가리키도록(듯이), 버텍스의 배열에 값을 설정해 삼각형 팬을 생성 한다.

'이 코드에서는, dx 는 DirectX7 오브젝트에의
'유효한 참조이다고 한다.
On Local Error Resume Next
Const TOTAL_VERTS As Integer = 6
Dim Verts(TOTAL_VERTS) As D3DVERTEX

Verts(0) = dx.CreateD3DVertex(0, 0, 0, 0, 0, -1, 0, 0)
Verts(1) = dx.CreateD3DVertex(-5, -5, 0, 0, 0, -1, 0, 0)
Verts(2) = dx.CreateD3DVertex(-3, 7, 0, 0, 0, -1, 0, 0)
Verts(3) = dx.CreateD3DVertex(0, 10, 0, 0, 0, -1, 0, 0)
Verts(4) = dx.CreateD3DVertex(3, 7, 0, 0, 0, -1, 0, 0)
Verts(5) = dx.CreateD3DVertex(5, 5, 0, 0, 0, -1, 0, 0)

이 후,Direct3DDevice7.DrawPrimitive 메소드를 사용해 삼각형 팬을 렌더링 할 수 있다. 다음의 코드는,Direct3DDevice7.DrawPrimitive 를 사용해, 위에의 예의 삼각형 팬을 드로잉(Drawing) 하는 방법을 나타낸다. Direct3DDevice7.DrawPrimitive 의 호출은,Direct3DDevice7.BeginScene 와 Direct3DDevice7.EndScene 의 사이에 실시할 필요가 있다.

'이 코드에서는, d3ddev 가 Direct3DDevice7 오브젝트에의
'유효한 참조이다고 한다.
Call d3ddev.DrawPrimitive(D3DPT_TRIANGLEFAN, _
D3DFVF_VERTEX, _
Verts(0), _
TOTAL_VERTS, _
D3DDP_WAIT);

If Err.Number <> DD_OK Then
'에러 처리 코드
End If

다음의 그림은, 결과적으로 드로잉(Drawing) 되는 삼각형 팬을 나타낸다.


밀러 텍스쳐 addressing mode에 대해

[C++]

D3DTEXTUREADDRESS 열거형의 D3DTADDRESS_MIRROR 멤버로 지정하는 "밀러" 텍스쳐 addressing mode에서는, Direct3D 는 모든 정수 경계에서 텍스쳐를 미러링 한다. 예를 들어, 프로그램으로 정방형 프리미티브를 생성 해, 텍스쳐 좌표 (0.0, 0.0), (0.0, 3.0), (3.0, 3.0), 및 (3.0, 0.0)을 지정하는 경우를 생각한다. 텍스쳐 addressing mode를 D3DTADDRESS_MIRROR 로 설정 하면, u 및 v 의 양방향에서 텍스쳐가 3 회 적용된다. 텍스쳐가 적용되는 그 외의 모든 행과 열은, 직전의 행 또는 열의 경상이 된다.

[Visual Basic]

CONST_D3DTEXTUREADDRESS 열거의 D3DTADDRESS_MIRROR 멤버로 지정하는 "밀러" 텍스쳐 addressing mode에서는, 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에 대하며」를 참조할것.


디바이스 열거의 시작

[C++]

C++ 어플리케이션에서는,IDirect3D7::EnumDevices 메소드를 호출해 디바이스의 열거를 시작 한다. 이 메소드는, 하드웨어로 지원 되고 있는 Direct3D 디바이스를 모두 열거한다. Direct3D 는,D3DEnumDevicesCallback7 함수를 호출해, 사용하는 디바이스를 선택한다. D3DEnumDevicesCallback7 함수를 어플리케이션에 준비해 둔다. 이 콜백 함수는 어플리케이션으로부터 제공되기 (위해)때문에, 독자적인 이름을 붙일 수가 있다.

다음의 코드는, Direct3D 디바이스의 열거하는 처리를 나타낸다. 이 예에서는, 디바이스 열거 콜백 함수의 이름을 EnumDeviceCallback 로 한다. 다음의 코드에서는, EnumDeviceCallback 에의 포인터를 IDirect3D7::EnumDevices 메소드에 건네준다. 그 후, 이 메소드는 열거하는 각 디바이스에 대해서 EnumDeviceCallback 를 호출해, 디바이스를 돌려준다. 이 콜백은, D3DENUMRET_CANCEL 를 돌려주는 것으로, 모든 디바이스가 열거되기 전에 열거 처리를 정지할 수 있다.

// 이 코드에서는, 코드를 실행하기 전에 어플리케이션이 취득한 IDirect3D7 인터페이스에의
//
// 유효한 포인터가 변수 lpd3d 에 저장 되고 있다.

BOOL fDeviceFound = FALSE;
hRes = lpd3d->EnumDevices(EnumDeviceCallback, &fDeviceFound);
if (FAILED(hRes))
{
// 에러 처리 코드
}

if (! fDeviceFound)
{
// 에러 처리 코드
}
[Visual Basic]

Visual Basic 어플리케이션에서는,Direct3D7.GetDevicesEnum 메소드를 호출해 Direct3DEnumDevices 클래스에의 참조를 취득하는 것으로써, 디바이스의 열거를 시작 한다. Direct3DEnumDevices 클래스는, 열거하는 디바이스의 수, 및 각 디바이스의 정보를 취득하는 메소드를 정의한다.

다음의 코드는,Direct3DEnumDevices 클래스를 취득하는 처리를 나타낸다.

'이 예에서는, d3d 변수는 Direct3D7 클래스에의
'유효한 참조이다.
Dim d3dEnum As Direct3DEnumDevices

'열거 클래스를 취득한다.
Set d3dEnum = d3d.GetDevicesEnum


클램프 텍스쳐 addressing mode에 대해

[C++]

D3DTEXTUREADDRESS 열거형의 D3DTADDRESS_CLAMP 멤버로 지정하는 "클램프" 텍스쳐 addressing mode에서는, 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 회 적용된다. 최초의 열과 마지막 행의 픽셀 컬러가, 프리미티브 위와 오른쪽으로 각각 퍼져 간다.

[Visual Basic]

CONST_D3DTEXTUREADDRESS 열거의 D3DTADDRESS_CLAMP 멤버로 지정하는 "클램프" 텍스쳐 addressing mode에서는, 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 회 적용된다. 최초의 열과 마지막 행의 픽셀 컬러가, 프리미티브 위와 오른쪽으로 각각 퍼져 간다.

다음의 그림에 이것을 나타낸다.


디렉셔널 라이트

디렉셔널 라이트는, 색과 방향을 가져, 위치 좌표는 가지지 않는다. 이 라이팅은 평행한 미츠루를 추방한다. 즉, 이 빛은 모두 장면내에서 같은 방향으로 나아간다. 디렉셔널 라이트는, 태양과 같이 멀게 멀어진 광원에 비유할 수가 있다. 디렉셔널 라이트는 감쇠와 범위의 영향을 받지 않기 때문에, Direct3D 에서는 지정된 색과 방향만 고려해, 버텍스의 색을 계산한다. 라이팅 계수의 개수가 적기 때문에, 디렉셔널 라이트는 컴퓨터에의 부하가 가장 가벼운 라이트이다.


anti-aliasing 스테이트

에일리어징 제거란, 선과 엣지를 스크린상에서 보다 매끄럽게 표시하는 방법이다. Direct3D 에서는, 엣지 anti-aliasing 및 풀 신 anti-aliasing의 2 종류의 anti-aliasing가 지원 되고 있다. 이러한 테크닉의 상세한 것에 대하여는, 「공통의 테크놀러지와 특수 효과」섹션의 「anti-aliasing」을 참조할것.

[C++]

디폴트에서는, Direct3D 는 anti-aliasing를 실행하지 않는다. D3DRENDERSTATE_ANTIALIAS 렌더링 스테이트를 D3DANTIALIASMODE 의 멤버로 설정해, 풀 신 anti-aliasing를 유효하게 할 수 있다 (디폴트값의 D3DANTIALIAS_NONE 는, 풀 신 anti-aliasing를 무효로 한다).

엣지 anti-aliasing ( 제 2 렌더링 패스가 필요)를 유효하게 하려면 ,D3DRENDERSTATE_EDGEANTIALIAS 렌더링 스테이트를 TRUE 로 설정한다. 엣지 anti-aliasing를 무효로 하려면 , D3DRENDERSTATE_EDGEANTIALIAS 를 FALSE 로 설정한다.

[Visual Basic]

디폴트에서는, Direct3D 는 anti-aliasing를 실행하지 않는다. D3DRENDERSTATE_ANTIALIAS 렌더링 스테이트를 CONST_D3DANTIALIASMODE 열거의 멤버로 설정해, 풀 신 anti-aliasing를 유효하게 할 수 있다 (디폴트값의 D3DANTIALIAS_NONE 는, 풀 신 anti-aliasing를 무효로 한다).

엣지 anti-aliasing ( 제 2 렌더링 패스가 필요)를 유효하게 하려면 ,D3DRENDERSTATE_EDGEANTIALIAS 렌더링 스테이트를 제로 이외의 값으로 설정한다. 엣지 anti-aliasing를 무효로 하려면 , D3DRENDERSTATE_EDGEANTIALIAS 를 제로로 설정한다.


밉맵 세트의 생성

[C++]

밉맵 체인을 생성 하려면 ,IDirectDraw7::CreateSurface 메소드에 건네주는 DDSURFACEDESC2 구조체의 DDSCAPS_MIPMAP 및 DDSCAPS_COMPLEX 플래그를 지정한다. 밉맵은 모두 텍스쳐이기도 하기 (위해)때문에, DDSCAPS_TEXTURE 플래그를 지정할 필요도 있다.

다음의 예는,IDirectDraw7::CreateSurface 메소드를 사용해, 사이즈 256 x256, 128 x128, 64 x64, 32 x32, 및 16x16 의 5 개의밉맵 레벨을 생성 하는 방법을 나타낸다.

// 이 코드에서는, 변수 lpDD 는 DirectDraw 인터페이스에의
// 유효한 포인터이다고 한다.

DDSURFACEDESC2       ddsd;
LPDIRECTDRAWSURFACE7 lpDDMipMap;
ZeroMemory(&ddsd, sizeof(ddsd));
ddsd.dwSize = sizeof(ddsd);
ddsd.dwFlags = DDSD_CAPS | DDSD_MIPMAPCOUNT;
ddsd.dwMipMapCount = 5;
ddsd.ddsCaps.dwCaps = DDSCAPS_TEXTURE |
    DDSCAPS_MIPMAP | DDSCAPS_COMPLEX;
ddsd.dwWidth = 256UL;
ddsd.dwHeight = 256UL;

ddres = lpDD->CreateSurface(&ddsd, &lpDDMipMap);
if (FAILED(ddres))
.
.
.

밉맵 레벨의 수는 생략 할 수 있다. 이 경우,IDirectDraw7::CreateSurface 는 표면의 체인을 생성 한다. 각 표면은, 직전의 표면보다 2 의 거듭제곱씩 작아져, 최종적으로 최소 사이즈가 된다. 폭과 높이도 생략 할 수 있다. 이 경우,IDirectDraw7::CreateSurface 는 지정된 레벨수를 생성 한다. 이 때의 최소 레벨 사이즈는 1x1 이다.

주 : 밉맵 체인의 각 표면의 크기는, 직전의 표면의 반이 된다. 최상정도 밉맵의 크기가 256�1 128 의 경우, 다음의 레벨의 밉맵의 크기는 128�6 64 가 되어, 그 다음의 레벨은 64�3 32 라고 하는 순으로 밉맵의 크기는 작아져, 최종적으로는 2×1 가 된다. dwWidth 및 dwHeight 멤버에 명시적으로 크기를 지정했을 경우는, 몇개의 제약이 있다. 즉,dwMipMapCount 로 밉맵 레벨의 수를 지정할 수 없다. dwMipMapCount 에서는, 체인의 밉맵의 폭 또는 높이의 어느쪽이든을 1 보다 작아지는 일이 있다. 예로서 4×2 의 최상정도 밉맵 표면의 경우를 생각한다. 이 경우,dwMipMapCount 로 지정 가능한 최대치는 2 이다. 최상정도의 크기는 4�2 2 로, 다음의 레벨의 크기는 2�1 1 이다. dwMipMapCount 의 값이 2 보다 크면 제 2 레벨의 밉맵의 높이는 분수가 된다. 따라서, 이것은 허가되지 않는다.

[Visual Basic]

밉맵 체인을 생성 하려면 ,DirectDraw7.CreateSurface 메소드에 건네주는 DDSURFACEDESC2 형의 DDSCAPS_MIPMAP 및 DDSCAPS_COMPLEX 플래그를 지정한다. 밉맵은 모두 텍스쳐이기도 하기 (위해)때문에, DDSCAPS_TEXTURE 플래그를 지정할 필요도 있다.

다음의 예는,DirectDraw7.CreateSurface 메소드를 사용해, 사이즈 256 x256, 128 x128, 64 x64, 32 x32, 및 16x16 의 5 개의밉맵 레벨을 생성 하는 방법을 나타낸다.

'이 코드에서는, 변수 DD 에 DirectDraw7 오브젝트에의
'유효한 참조가 저장 되고 있다고 한다.
On Local Error Resume Next
Dim ddsd As DDSURFACEDESC2
Dim DDMipMap As DirectDrawSurface7

ddsd.lFlags = DDSD_CAPS Or DDSD_MIPMAPCOUNT
ddsd.lMipMapCount = 5
ddsd.ddsCaps.lCaps = DDSCAPS_TEXTURE Or DDSCAPS_MIPMAP Or DDSCAPS_COMPLEX
ddsd.lWidth = 256
ddsd.lHeight = 256

Set DDMipMap = DD.CreateSurface(ddsd)
If Err.Number <> DD_OK Then
'에러 처리 코드
End If

밉맵 레벨의 수는 생략 할 수 있다. 이 경우,DirectDraw7.CreateSurface 는 표면의 체인을 생성 한다. 각 표면은, 직전의 표면보다 2 의 거듭제곱씩 작아져, 최종적으로 최소 사이즈가 된다. 폭과 높이도 생략 할 수 있다. 이 경우,DirectDraw7.CreateSurface 는 지정된 레벨수를 생성 한다. 이 때의 최소 레벨 사이즈는 1x1 이다.

주 : 밉맵 체인의 각 표면의 크기는, 직전의 표면의 반이 된다. 최상정도 밉맵의 크기가 256�1 128 의 경우, 다음의 레벨의 밉맵의 크기는 128�6 64 가 되어, 그 다음의 레벨은 64�3 32 라고 하는 순으로 밉맵의 크기는 작아져, 최종적으로는 2×1 가 된다. lWidth 및 lHeight 멤버에 명시적으로 크기를 지정했을 경우는, 몇개의 제약이 있다. 즉,lMipMapCount 로 밉맵 레벨의 수를 지정할 수 없다. lMipMapCount 에서는, 체인의 밉맵의 폭 또는 높이의 어느쪽이든을 1 보다 작아지는 일이 있다. 예로서 4×2 의 최상정도 밉맵 표면의 경우를 생각한다. 이 경우,lMipMapCount 로 지정 가능한 최대치는 2 이다. 최상정도의 크기는 4�2 2 로, 다음의 레벨의 크기는 2�1 1 이다. lMipMapCount 의 값이 2 보다 크면 제 2 레벨의 밉맵의 높이는 분수가 된다. 따라서, 이것은 허가되지 않는다.


텍스쳐 좌표 트랜스 폼에 대해

Platform SDK: DirectX

텍스쳐 좌표 트랜스 폼에 대해

Direct3D 디바이스에서는, 4×4 행렬을 적용해, 버텍스의 텍스쳐 좌표를 트랜스 폼 할 수 있다. 시스템은, 텍스쳐 좌표에 대해서, 지오메트리의 경우와 같게 트랜스 폼을 적용한다. 적용 가능한 트랜스 폼에는, 스케일링, 회전, 평행이동, 투영, 전단, 또는 이러한 편성 등, 4×4 행렬로 가능한 모든 트랜스 폼이 있다.

주 : Direct3D 에서는, 「트랜스 폼이 끝난 라이팅 끝난 버텍스」는 수정되지 않는다. 따라서, 「트랜스 폼이 끝난 라이팅 끝난 버텍스」를 사용하는 어플리케이션에서는, Direct3D 에 의해 버텍스의 텍스쳐 좌표를 트랜스 폼 할 수 없다.

하드웨어 가속화에 의한 트랜스 폼 & 라이팅 처리를 지원 하는 디바이스 (TnLHAL 디바이스)에서는, 또, 텍스쳐 좌표 트랜스 폼은 고속 처리된다. 하드웨어 가속화에 의한 트랜스 폼을 이용할 수 없는 경우는, Direct3D 지오메트리 파이프라인의 플랫폼 고유의 최적화에 의해 텍스쳐 좌표 트랜스 폼이 실행된다.

텍스쳐 좌표 트랜스 폼은, 지오메트리의 텍스쳐 좌표를 직접 변경하지 않고 특수 효과를 내려고 하는 경우에 편리하다. 단순한 평행이동 행렬이나 회전 행렬을 사용해, 오브젝트 위에의 텍스쳐를 리얼하게 표현하거나 Direct3D 에 의해 자동 생성되는 텍스쳐 좌표를 트랜스 폼 하는 것으로, 투영 텍스쳐나 동적 라이트 맵핑 등 고도의 이펙트를 단순화 해, 고속 처리하는 일도 가능하다. 또, 텍스쳐 좌표 트랜스 폼을 사용해, 텍스쳐 좌표의 단일 세트를 (복수의 텍스쳐 스테이지에서의) 다양한 목적을 위해서(때문에) "재이용" 할 수 있다.

상세한 것에 대하여는, 「텍스쳐 좌표 처리의 사용」


앰비언트 라이트 스테이트

앰비언트 라이트란, 전방향으로부터 비추는 환경빛이다. Direct3D 의 앰비언트 라이트의 사용에 관한 특정의 정보에 대해서는, 「다이렉트 라이트와 앰비언트 라이트의 비교」 및 「Direct3D 의 라이팅에 있어서의 수학적 계산」을 참조할것.

[C++]

C++ 어플리케이션으로 앰비언트 라이트의 색을 설정하려면 ,IDirect3DDevice7::SetRenderState 메소드를 호출해, 제 1 파라미터로서 열거값 D3DRENDERSTATE_AMBIENT 를 건네준다. 제 2 파라미터는 RGBA 포맷으로 나타내는 색이다. 디폴트는 제로이다.

// 이 코드에서는, lpD3DDevice 는 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다고 한다.

// 앰비언트 라이트를 설정한다.
D3DCOLOR d3dclrAmbientLightColor = D3DRGBA(1.0f, 1.0f, 1.0f, 1.0f);
lpD3DDevice->SetRenderState(D3DRENDERSTATE_AMBIENT,
                            d3dclrAmbientLightColor);
[Visual Basic]

Visual Basic 어플리케이션으로 앰비언트 라이트의 색을 설정하려면 ,Direct3DDevice7.SetRenderState 메소드를 호출해, 열거값 D3DRENDERSTATE_AMBIENT 를 제 1 파라미터로서 건네준다. 제 2 파라미터는 RGBA 포맷으로 나타내는 색이다. 디폴트는 제로이다.

'이 코드에서는, D3DDevice 에 Direct3DDevice7 오브젝트에의
'유효한 참조가 저장 되어 및 dx 에 DirectX7 오브젝트에의
'유효한 참조가 저장 되고 있다고 한다.
Dim AmbientLightColor As Long

'앰비언트 라이트를 설정한다.
AmbientLightColor = dx.CreateColorRGBA(1#, 1#, 1#, 1#)
Call D3DDevice.SetRenderState(D3DRENDERSTATE_AMBIENT, _
                              AmbientLightColor)


텍스쳐 좌표 처리의 사용

[C++]

이하에 나타내는 것은, 텍스쳐 좌표 처리에 의해 특수한 텍스쳐 이펙트를 내는 방법 및 그 코드예이다.

모델상에서 텍스쳐를 애니메이션 한다 (평행이동 또는 회전을 이용)

  • 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 = D3DUtil_SetIdentityMatrix(); // 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(D3DTRANSFORMSTATE_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)
[Visual Basic]

이하에 나타내는 것은, 텍스쳐 좌표 처리에 의해 특수한 텍스쳐 이펙트를 내는 방법 및 그 코드예이다.

모델상에서 텍스쳐를 애니메이션 한다 (평행이동 또는 회전을 이용)

  • 2D 텍스쳐 좌표를 버텍스 포맷에 정의한다.
    ' 2D 텍스쳐 좌표를 가지는 단일의 텍스쳐를 사용한다. 이 비트 패턴은,
'필요에 따라서, 위치 좌표, 법선, 및 색정보를 추가할 수 있도록(듯이)
'확장할 필요가 있다.
lFVFTex = (D3FVF_TEX1 Or D3DFVF_TEXCOORDSIZE2(0))
  • 2D 텍스쳐 좌표를 사용하도록(듯이) 래스터라이저를 설정한다.
    SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT2)
  • 적절한 텍스쳐 좌표 트랜스 폼 행렬을 정의해 설정한다.
    ' M 는, U 및 V 방향의 텍스쳐 좌표를 평행이동하기 위한
' D3DMATRIX 이다.
'      1   0  0  0
'      0   1  0  0
'      du dv  0  0 (du 및 dv 는 각 프레임을 변경한다)
'      0   0  0  0
dx.IdentityMatrix(M)
M.rc31 = du
M.ec32 = 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(D3DTRANSFORMSTATE_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)


텍스쳐 좌표의 트랜스 폼과 취득 [C++]

Platform SDK: DirectX
텍스쳐 좌표의 트랜스 폼과 취득 [C++]

어플리케이션으로 지오메트리에 사용하는 행렬과 같이,IDirect3DDevice7::SetTransform 및 IDirect3DDevice7::GetTransform 메소드를 호출해 텍스쳐 좌표 트랜스 폼을 설정 및 취득할 수 있다. 이러한 메소드는, 텍스쳐 스테이지의 0 ~ 7 의 트랜스 폼 행렬을 각각 식별하는,D3DTRANSFORMSTATETYPE 열거형의 D3DTRANSFORMSTATE_TEXTURE0 ~ D3DTRANSFORMSTATE_TEXTURE7 멤버를 받는다.

다음의 코드는, 텍스쳐 스테이지 0 의 텍스쳐 좌표에 적용되는 행렬을 설정한다.

// 이 예에서는, lpd3dDevice 변수에 IDirect3DDevice7 인터페이스에의
// 유효한 포인터가 저장 되고 있다.

D3DMATRIX matTrans  = D3DUtil_SetIdentityMatrix(); // d3dutil.h 에 선언된다.

// 희망의 트랜스 폼용의 행렬을 설정한다.
lpd3dDevice->SetTransform(D3DTRANSFORMSTATE_TEXTURE0, &matTrans);
[Visual Basic]

어플리케이션으로 지오메트리에 사용하는 행렬과 같이,Direct3DDevice7.SetTransform 및 Direct3DDevice7.GetTransform 메소드를 호출해 텍스쳐 좌표 트랜스 폼을 설정 및 취득할 수 있다. 이러한 메소드는, 텍스쳐 스테이지의 0 ~ 7 의 트랜스 폼 행렬을 각각 식별하는,CONST_D3DTRANSFORMSTATETYPE 열거의 D3DTRANSFORMSTATE_TEXTURE0 ~ D3DTRANSFORMSTATE_TEXTURE7 멤버를 받는다.

다음의 코드는, 텍스쳐 스테이지 0 의 텍스쳐 좌표에 적용되는 행렬을 설정한다.

'이 예에서는, d3dDevice 변수에 Direct3DDevice7 오브젝트에의
'유효한 참조가 저장 되고 있어
' dx 에는 DirectX7 오브젝트에의 유효한 참조가 저장 되고 있다.
Dim matTrans As D3DMATRIX
Call dx.IdentityMatrix(matTrans)

'희망의 트랜스 폼용의 행렬을 설정한다.
Call d3dDevice.SetTransform(D3DTRANSFORMSTATE_TEXTURE0, matTrans)


뷰포트의 클리어

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

[C++]

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

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

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

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

[Visual Basic]

Visual Basic 의 Direct3DDevice7 클래스에는, 뷰포트를 클리어 하는 Direct3DDevice7.Clear 메소드가 있다. 이 메소드는, 클리어 하는 표면 위에의 영역을 정의하는 1 개(살) 또는 복수의 직사각형을 받는다. 렌더링 하는 장면에 뷰포트 직사각형 전체의 모션이 포함되는 경우 (예를 들어, 플레이어의 시점으로부터 본 원근법을 사용하는 게임), 각 프레임의 뷰포트 전체를 클리어 할 수가 있다. 이 경우,count 파라미터를 1 으로 설정해,recs() 파라미터를 D3DRECT 변수의 단일 요소 배열로 설정한다 (여기에서는, 렌더링 타겟 표면의 영역 전체에 이르는 직사각형을 최초의 요소에서만 기술한다).

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

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


시점으로부터의 상대 깊이대 Z 베이스의 깊이

[C++]

깊이 버퍼내에서의 z 값의 불균등인 격차에 의해 생기는, 포그(안개:fog)의 부자연스러운 그래픽스 효과를 억제하기 위해서(때문에), 대부분의 하드웨어 디바이스에서는, 픽셀 포그(안개:fog)에 z 베이스 깊이값은 아니고 시점으로부터의 상대 깊이를 사용한다. 시점으로부터의 상대 깊이란, 본질적으로는 동차 좌표 세트로부터의 w 요소이다 (Direct3D 는, 디바이스 공간 좌표로부터 RHW 요소의 역수를 취득해 진정한 w 를 재생성한다). 디바이스가 시점으로부터의 상대 포그(안개:fog)를 지원 하고 있는 경우,IDirect3DDevice7::GetCaps 메소드를 호출하면, 그 디바이스는 D3DPRIMCAPS 의 dwRasterCaps 멤버에 D3DPRASTERCAPS_WFOG 플래그를 설정한다 (GetCaps 에 건네주는 D3DDEVICEDESC7 구조체에는, 각종 프리미티브의 능력을 기술하는 복수의 D3DPRIMCAPS 구조체가 포함되어 있다).

주 : 레퍼런스 래스터라이저를 제외해, 소프트웨어 디바이스는 항상 z 를 사용해 픽셀 포그(안개:fog) 이펙트를 계산한다.

시점으로부터의 상대 포그(안개:fog)가 지원 되고 있는 경우, 설정된 투영 행렬로 디바이스 공간의 w 값에 대응하는, 월드 공간의 z 값을 생성 하면 와, 시스템은 z 베이스 깊이보다 시점으로부터의 상대 깊이를 우선해 자동적으로 사용한다 (투영 행렬을 설정하려면 ,IDirect3DDevice7::SetTransform 메소드를 호출해, D3DTRANSFORMSTATE_PROJECTION 값을 사용해, 희망의 행렬을 나타내는 D3DMATRIX 구조체를 건네준다). 투영 행렬이 이 요건에 대응하고 있지 않는 경우는, 포그(안개:fog) 이펙트가 올바르게 적용되지 않는다. 적절한 행렬의 생성의 상세한 것에 대하여는, 「W 버퍼에 유효한 투영 행렬」을 참조할것 ( 「투영 트랜스 폼이란」으로 설명하는 퍼스펙티브 투영 행렬은, 적절한 투영 행렬을 생성한다).

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

Direct3D 는 투영 행렬의 제 4 열을 조사해 요소가 [0,0,0,1] (아핀 투영)의 경우에는, 시스템은 z 베이스의 깊이값을 포그(안개:fog)에 사용한다. 이 경우, 디바이스 공간의 선형 포그(안개:fog) 이펙트의 시작 거리 및 종료 거리를 지정할 필요도 있다. 이 범위는, 유저에게 가장 가까운 점을 0.0 으로 해, 가장 먼 점을 1.0 으로 한 범위이다.

[Visual Basic]

깊이 버퍼내에서의 z 값의 불균등인 격차에 의해 생기는, 포그(안개:fog)의 부자연스러운 그래픽스 효과를 억제하기 위해서(때문에), 대부분의 하드웨어 디바이스에서는, 픽셀 포그(안개:fog)에 z 베이스 깊이값은 아니고 시점으로부터의 상대 깊이를 사용한다. 시점으로부터의 상대 깊이란, 본질적으로는 동차 좌표 세트로부터의 w 요소이다 (Direct3D 는, 디바이스 공간 좌표로부터 RHW 요소의 역수를 취득해 진정한 w 를 재생성한다). 디바이스가 시점으로부터의 상대 포그(안개:fog)를 지원 하고 있는 경우,Direct3DDevice7.GetCaps 메소드를 호출하면, 그 디바이스는 D3DPRIMCAPS 형의 lRasterCaps 멤버에 D3DPRASTERCAPS_WFOG 플래그를 설정한다 (GetCaps 에 건네주는 D3DDEVICEDESC7 형에는, 각종 프리미티브의 능력을 기술하는 복수의 D3DPRIMCAPS 형이 포함되어 있다).

주 : 레퍼런스 래스터라이저를 제외해, 소프트웨어 디바이스는 항상 z 를 사용해 픽셀 포그(안개:fog) 이펙트를 계산한다.

시점으로부터의 상대 포그(안개:fog)가 지원 되고 있는 경우, 설정된 투영 행렬로 디바이스 공간의 w 값에 대응하는, 월드 공간의 z 값을 생성 하면 와, 시스템은 z 베이스 깊이보다 시점으로부터의 상대 깊이를 우선해 자동적으로 사용한다 (투영 행렬을 설정하려면 ,Direct3DDevice7.SetTransform 메소드를 호출해,CONST_D3DTRANSFORMSTATETYPE 로부터 D3DTRANSFORMSTATE_PROJECTION 값을 사용해, 희망의 행렬을 나타내는 D3DMATRIX 형을 건네준다). 투영 행렬이 이 요건에 대응하고 있지 않는 경우는, 포그(안개:fog) 이펙트가 올바르게 적용되지 않는다. 적절한 행렬의 생성의 상세한 것에 대하여는, 「W 버퍼에 유효한 투영 행렬」을 참조할것 ( 「투영 트랜스 폼이란」으로 설명하는 퍼스펙티브 투영 행렬은, 적절한 투영 행렬을 생성한다).

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

Direct3D 는 투영 행렬의 제 4 열을 조사해 요소가 [0,0,0,1] (아핀 투영)의 경우에는, 시스템은 z 베이스의 깊이값을 포그(안개:fog)에 사용한다. 이 경우, 디바이스 공간의 선형 포그(안개:fog) 이펙트의 시작 거리 및 종료 거리를 지정할 필요도 있다. 이 범위는, 유저에게 가장 가까운 점을 0.0 으로 해, 가장 먼 점을 1.0 으로 한 범위이다.


열거된 디바이스의 선택

[C++]

C++ 의 경우, Direct3D 는, 어플리케이션에 준비되어 있는 D3DEnumDevicesCallback7 함수를, 시스템에 인스톨 되고 있는 각 Direct3D 디바이스에 대해서 호출한다. 이 함수의 호출에서는, 제 1 파라미터는 디바이스를 설명하는 캐릭터 라인으로, 제 2 파라미터는 알기 쉬운 디바이스명을 나타내는 캐릭터 라인이다.

제 3 파라미터는, 디바이스의 하드웨어 기능에 대한 정보를 저장 하는 D3DDEVICEDESC7 구조체에의 포인터이다. 열거되는 디바이스가 HAL 디바이스여도, Direct3D 로 사용 가능한 기능을 특정의 하드웨어가 모두 지원 하면은 한정되지 않는다. 마지막 파라미터는, 프로그래머가 정의하는 값이다. 어플리케이션에서는, 이 값을 IDirect3D7::EnumDevices 메소드에 건네준다. 다음에, 이 값을 D3DEnumDevicesCallback7 함수에 건네준다.

다음의 코드는,D3DEnumDevicesCallback7 함수의 생성 방법을 나타낸다. 이 예에서는, 어플리케이션에 준비되어 있는 콜백 함수의 이름을 EnumDeviceCallback 로 한다. EnumDeviceCallback 함수에서는, 이하의 알고리즘을 사용해, 적절한 Direct3D 디바이스를 선택한다.

  1. 현재의 디스플레이 깊이에 일치하지 않는 디바이스를 모두 폐기한다.
  2. 삼각형을 gouraud shading 처리할 수 없는 디바이스를 모두 폐기한다.
  3. 위에의 1 으로 2 에 들어맞지 않는 하드웨어 디바이스가 있으면, 그것을 사용한다. 다만, 어플리케이션을 디버그 모드로 실행하고 있는 경우는, 하드웨어 디바이스는 사용하지 않는다.

EnumDeviceCallback 함수의 코드예를 이하에 나타낸다.

// 이 함수에서는, 다음의 글로벌 변수가
// 프로그램으로 선언되고 있다고 한다.
// DWORD                   g_dwDeviceBitDepth          = 0;
// GUID                    g_guidDevice;
// char                    g_szDeviceName[MAX_PATH];
// char                    g_szDeviceDesc[MAX_PATH];
// D3DDEVICEDESC7          g_d3dDeviceDesc;

static HRESULT WINAPI
EnumDeviceCallback(LPSTR            lpszDeviceDesc,
                   LPSTR            lpszDeviceName,
                   LPD3DDEVICEDESC7 lpd3dEnumDeviceDesc,
                   LPVOID           lpUserArg)
{
    BOOL fIsHardware = FALSE;

    fIsHardware = (lpd3dEnumDeviceDesc->dwDevCaps & D3DDEVCAPS_HWRASTERIZATION);

// 디바이스의 렌더링이 희망의 깊이로 행해질지 어떨지.
    if ((lpd3dEnumDeviceDesc->dwDeviceRenderBitDepth & g_dwDeviceBitDepth) == 0)
    {
// 그렇지 않으면, 이 디바이스는 스킵 한다.

        return D3DENUMRET_OK;
    }

// 디바이스는, gouraud shading 처리한 삼각형을 지원 할 필요가 있다.
    if (! (lpd3dEnumDeviceDesc->dpcTriCaps.dwShadeCaps &
          D3DPSHADECAPS_COLORGOURAUDRGB))
    {
// gouraud shading를 지원 하고 있지 않다. 이 디바이스는 스킵 한다.

        return D3DENUMRET_OK;
    }

    //
// 이 디바이스는 필요한 기능을 갖추고 있다. 상세를 보존한다.
    //
    *(BOOL*) lpUserArg = TRUE;
    CopyMemory(&g_guidDevice, &lpd3dEnumDeviceDesc->deviceGUID, sizeof(GUID));
    strcpy(g_szDeviceDesc, lpszDeviceDesc);
    strcpy(g_szDeviceName, lpszDeviceName);
    CopyMemory(&g_d3dDeviceDesc, lpd3dEnumDeviceDesc,
               sizeof(D3DDEVICEDESC7));

// 이것이 하드웨어 디바이스의 경우,
// 필요한 기능을 갖추고 있다.
    if (fIsHardware)
        return D3DENUMRET_CANCEL;

// 그렇지 않으면, 검색을 계속한다.

    return D3DENUMRET_OK;
}
[Visual Basic]

Visual Basic 에서는,Direct3DEnumDevices 클래스에 의해, 시스템에 인스톨 되고 있는 Direct3D 디바이스를 열거한다. 이 클래스에 문의를 실시해, 클래스내의 열거되는 디바이스를 그 인덱스로 식별하는 것으로, 각 디바이스의 정보를 취득한다. 디바이스의 인덱스는, 최초의 디바이스에는 1, 2 번째의 디바이스에는 2, 라고 하는 순서로 붙는다. Direct3DEnumDevices.GetCount 메소드는, 열거되는 디바이스의 수, 즉 최대 허용 인덱스값을 돌려준다.

열거되는 디바이스의 GUID 를 텍스트 캐릭터 라인으로서 취득하려면 ,Direct3DEnumDevices.GetGuid 메소드를 호출한다. 캐릭터 라인은 디바이스 마다 다르다.

디바이스의 이름이라고 알기 쉬운 설명을 포함한 텍스트 캐릭터 라인을 취득하려면 ,Direct3DEnumDevices.GetName 및 Direct3DEnumDevices.GetDescription 메소드를 호출한다.

D3DDEVICEDESC7 형의 형식에서 디바이스의 기능에 대한 설명을 취득하려면 ,Direct3DEnumDevices.GetDesc 메소드를 호출한다. 열거되는 디바이스가 하드웨어 디바이스여도, Direct3D API 로 사용 가능한 기능을 특정의 하드웨어가 모두 지원 하면은 한정되지 않는다.

다음의 코드는, 디바이스 기능을 결정하기 위해서(때문에) Direct3DEnumDevices 클래스의 메소드를 호출하는 함수의 생성 방법을 나타낸다. 이 예의 어플리케이션 정의 함수에서는, 이하의 알고리즘을 사용해, 적절한 Direct3D 디바이스를 선택한다.

  1. 현재의 디스플레이 깊이에 일치하지 않는 디바이스를 모두 폐기한다.
  2. 삼각형을 gouraud shading 처리할 수 없는 디바이스를 모두 폐기한다.
  3. 위에의 1 으로 2 에 들어맞지 않는 하드웨어 디바이스가 있으면, 그것을 사용한다.
Private Sub EnumerateDevices(d3denum As Direct3DEnumDevices)
'이 예에서는, 이하의 글로벌 변수가 선언되고 있다고 한다.
'   g_lDeviceBitDepth 는 희망의 비트 깊이를 나타낸다 (CONST_DDBITDEPTHFLAGS 의 정수의 편성).
'   g_DeviceDesc 에는 디바이스 기능을 나타내는 D3DDEVICEDESC7 가 저장 된다.
'   g_strDeviceGUID 에는 디바이스의 GUID 캐릭터 라인이 저장 된다.
'   g_strDeviceDescription 에는 디바이스를 설명하는 텍스트 캐릭터 라인이 저장 된다.
'   g_strDeviceName 에는 디바이스명을 나타내는 캐릭터 라인이 저장 된다.

'디바이스의 열거에 사용하는 로컬 변수.
Dim iDevice As Integer
Dim DevDesc As D3DDEVICEDESC7
Dim bIsHardware As Boolean

'디바이스의 열거를 시작 한다.
For iDevice = 1 To d3denum.GetCount
Dim checkDesc As D3DDEVICEDESC7
Call d3denum.GetDesc(iDevice, DevDesc)

'이 디바이스로 사용하는 기능이 하드웨어로 지원되어 있지 않은 경우
bIsHardware = (DevDesc.lDevCaps Or D3DDEVCAPS_HWRASTERIZATION)

'디바이스의 렌더링이 희망의 깊이로 행해질지 어떨지. 행해지지 않는 경우는 중지한다.
'체크를 실시해, 다음의 디바이스를 취득한다.
If checkDesc.lDeviceRenderBitDepth And Not g_lDeviceBitDepth Then
GoTo NEXT_DEVICE
End If

'디바이스는, gouraud shading 처리한 삼각형을 지원 할 필요가 있다.
If (Not checkDesc.dpcTriCaps.lShadeCaps And D3DPSHADECAPS_COLORGOURAUDRGB) Then
' RGB 모드의 gouraud shading를 지원 하고 있지 않다. 이 디바이스는 스킵 한다.
GoTo NEXT_DEVICE
End If

        '
'여기에 처리가 달하기까지 적절한 디바이스가 검출된다.
'그 결과를 글로벌 변수에 저장 한다.
        '
g_strDeviceGUID = d3denum.GetGuid(iDevice)
g_strDeviceDescription = d3denum.GetDescription(iDevice)
g_strDeviceName = d3denum.GetName(iDevice)
g_DeviceDesc = DevDesc

'이 현재의 디바이스가 하드웨어 가속화를 갖추고 있는 경우,
'이것은 적절한 디바이스이다.
If bIsHardware = True Then Exit For

'하드웨어 가속화를 갖추지 않은 경우는 처리를 다음으로 옮긴다.
NEXT_DEVICE:
Next iDevice
End Sub ' EnumerateDevices


범프 맵 텍스쳐의 생성

다른 텍스쳐의 경우와 같게, 범프 맵 텍스쳐를 생성 한다. 어플리케이션으로 범프 맵핑의 지원을 확인해, 유효한 픽셀 포맷을 취득하면(자) ( 「범프 맵핑의 지원의 검출」로 설명하도록(듯이)), 범프 맵 텍스쳐 표면을 생성 할 수 있다. 표면의 생성에 대해서는, 「텍스쳐 표면 오브젝트의 취득」 및 「표면의 생성」을 참조할것.

표면의 생성 후는, 적절한 델타값을 가지는 각 픽셀과 휘도(Luminance) (표면 포맷에 휘도(Luminance)가 포함되는 경우)를 로드할 수 있다. 각 픽셀 컴퍼넌트의 값에 대해서는, 「범프 맵 픽셀 포맷」으로 설명한다.


라이트의 유효/무효

[C++]

장면내의 광원의 라이트 프로퍼티 세트를 일단 할당하면(자), 디바이스에 대해서 IDirect3DDevice7::LightEnable 메소드를 호출하는 것으로, 그 광원을 액티브하게 할 수가 있다. 새롭게 할당한 광원은, 디폴트에서는 무효가 되어 있다. LightEnable 메소드는, 2 개의 파라미터를 받는다. 제 1 파라미터에는, 메소드로 처리하는 광원의 인덱스 (0 으로부터 시작된다)를 설정한다. 제 2 파라미터에는, 라이트를 유효하게 하는 경우는 TRUE 를, 무효로 하는 경우는 FALSE 를 설정한다.

다음의 코드는, LightEnable 메소드를 사용해, 디바이스의 광원 프로퍼티의 리스트내의 최초의 광원을 유효하게 하는 방법을 나타낸다.

/*
* 이 예에서는, g_lpd3dDev 는 IDirevt3DDevice7 인터페이스에의
* 유효한 포인터이다.
 */
HRESULT hr;

hr = g_lpd3dDev->LightEnable(0, TRUE);
if (FAILED(hr))
{
// 에러 처리 코드
}
[Visual Basic]

장면내의 광원의 라이트 프로퍼티 세트를 일단 할당하면(자), 디바이스에 대해서 Direct3DDevice7.LightEnable 메소드를 호출하는 것으로, 그 광원을 액티브하게 할 수가 있다. 새롭게 할당한 광원은, 디폴트에서는 무효가 되어 있다. LightEnable 메소드는, 2 개의 파라미터를 받는다. 제 1 파라미터에는, 메소드로 처리하는 광원의 인덱스 (0 으로부터 시작된다)를 설정한다. 제 2 파라미터에는, 라이트를 유효하게 하는 경우는 TRUE 를, 무효로 하는 경우는 FALSE 를 설정한다.

다음의 코드는, LightEnable 메소드를 사용해, 디바이스의 광원 프로퍼티의 리스트내의 최초의 광원을 유효하게 하는 방법을 나타낸다.

'
'이 예에서는, d3dDevice 변수에 Direct3DDevice7 오브젝트에의
'유효한 참조가 저장 된다.
'
On Local Error Resume Next

Call d3dDevice.LightEnable(0, True)
If Err.Number <> DD_OK Then
'에러 처리 코드
End If

프로퍼티가 없는 라이트를 유효하게 하는 경우, 또는 디바이스내에서 할당할 수 있고 있는 라이트 프로퍼티 세트의 범위외의 인덱스를 지정했을 경우,LightEnable 메소드는 이하의 프로퍼티를 가지는 광원을 생성 해, 그 광원을 유효 또는 무효로 한다.

멤버 | 디폴트
dltType | D3DLIGHT_DIRECTIONAL
dcvDiffuse | (R:1, G:1, B:1, A:0)
dcvSpecular | (R:0, G:0, B:0, A:0)
dcvAmbient | (R:0, G:0, B:0, A:0)
dvPosition | (0, 0, 0)
dvDirection | (0, 0, 1)
dvRange | 0
dvFalloff | 0
dvAttenuation0 | 0
dvAttenuation1 | 0
dvAttenuation2 | 0
dvTheta | 0
dvPhi | 0


텍스쳐 addressing mode란

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에 대해


스테이트 블록의 취득

[C++]

IDirect3DDevice7::CaptureStateBlock 메소드는, 기존의 스테이트 블록내의 값을 갱신해 디바이스의 현재의 스테이트에 반영한다. 이 메소드는, 파라미터 dwBlockHandle 를 1 개만 받는다. 이 파라미터는, 호출이 성공했을 경우에 디바이스의 현재의 스테이트의 혼잡처가 되는 스테이트 블록을 식별한다.

어플리케이션으로 기록 끝난 스테이트 블록을 갱신해 약간 다른 스테이트 설정을 포함하는 경우에는,IDirect3DDevice7::CaptureStateBlock 메소드가 특히 편리하다. 이것을 실시하려면 , 기존의 스테이트 블록을 적용해, 필요한 설정 변경을 실시해, 시스템의 스테이트를 스테이트 블록에 수중에 넣는다. 이것에 대해, 다음의 코드예로 가리킨다.

// dwMyBlock 변수에는, 이전에 기록된 디바이스 스테이트 세트에의
// 핸들이 저장 되고 있다.

// 현재의 스테이트 블록을 설정한다.
d3dDevice->ApplyStateBlock(dwMyBlock);

// 필요에 따라서 스테이트 블록을 변경한다.
.
.
.

// 수정한 디바이스 스테이트 데이터를 기존의 블록에 수중에 넣는다.
d3dDevice->CaptureStateBlock(dwMyBlock);

CaptureStateBlock 메소드는, 디바이스의 스테이트 전체를 수중에 넣는 것이 아니라, 스테이트 블록내의 기존의 스테이트값을 갱신할 뿐이다. 예를 들어, 다음의 코드예로 나타내는 2 개의 처리가 기록된 스테이트 블록이 있다고 한다.

SetRenderState(D3DRENDERSTATE_SHADEMODE, D3DSHADE_GOURAUD);
SetTexture(0, lpd3dAnyTexture);

스테이트 블록이 처음에 기록된 이후, 2 개의 설정의 어느쪽이든을 변경했을 경우,IDirect3DDevice7::CaptureStateBlock 메소드는, 블록내에서 변경된 스테이트만 새로운 값에 갱신한다.

[Visual Basic]

Direct3DDevice7.CaptureStateBlock 메소드는, 기존의 스테이트 블록내의 값을 갱신해 디바이스의 현재의 스테이트에 반영한다. 이 메소드는, 파라미터 blockHandle 를 1 개만 받는다. 이 파라미터는, 호출이 성공했을 경우에 디바이스의 현재의 스테이트의 혼잡처가 되는 스테이트 블록을 식별한다.

어플리케이션으로 기록 끝난 스테이트 블록을 갱신해 약간 다른 스테이트 설정을 포함하는 경우에는,Direct3DDevice7.CaptureStateBlock 메소드가 특히 편리하다. 이것을 실시하려면 , 기존의 스테이트 블록을 적용해, 필요한 설정 변경을 실시해, 시스템의 스테이트를 스테이트 블록에 수중에 넣는다. 이것에 대해, 다음의 코드예로 가리킨다.

' MyBlock 변수에는, 이전에 기록된 디바이스 스테이트 세트에의
'핸들이 저장 되고 있다.

'현재의 스테이트 블록을 설정한다.
Call d3dDevice.ApplyStateBlock(MyBlock)

'필요에 따라서 디바이스 스테이트를 변경한다.
.
.
.

'수정한 디바이스 스테이트 데이터를 기존의 블록에 수중에 넣는다.
Call d3dDevice.CaptureStateBlock(MyBlock)

CaptureStateBlock 메소드는, 디바이스의 스테이트 전체를 수중에 넣는 것이 아니라, 스테이트 블록내의 기존의 스테이트값을 갱신할 뿐이다. 예를 들어, 다음의 코드예로 나타내는 2 개의 처리가 기록된 스테이트 블록이 있다고 한다.

Call SetRenderState(D3DRENDERSTATE_SHADEMODE, D3DSHADE_GOURAUD)
Call SetTexture(0, d3dAnyTexture)

스테이트 블록이 처음에 기록된 이후, 2 개의 설정의 어느쪽이든을 변경했을 경우,Direct3DDevice7.CaptureStateBlock 메소드는, 블록내에서 변경된 스테이트만 새로운 값에 갱신한다.


램프 스테이트

D3DRENDERSTATE_MONOENABLE 렌더링 스테이트는, 현재는 사용되어 있지 않다. 어플리케이션으로 램프 디바이스를 사용 하면, 램프 라이팅이 자동적으로 유효하게 된다. 상세한 것에 대하여는, 「종래의 디바이스의 종류」를 참조할것.


버텍스의 그룹화

프리미티브의 버텍스는, 기본적으로는 이하의 2 개의 방법으로 그룹화 할 수 있다.

  • 프리미티브의 모든 버텍스를 순서에 배열에 저장 한다.
  • 버텍스를 임의의 순서로 배열에 저장 한다. 이 배열에 저장 되는 버텍스의 인덱스값을 순서에 저장 한 배열을 수반한다. 이러한 프리미티브는, 인덱스 첨부 프리미티브로 불린다.

DrawPrimitive 아키텍쳐를 사용 하면, 프리미티브를 정의하는 버텍스의 그룹을 1 회의 메소드 호출로 렌더링 하거나 프리미티브를 형성하는 버텍스를 개별적으로 렌더링 할 수가 있다. 상세한 것에 대하여는, 「프리미티브의 렌더링」을 참조할것.


텍스쳐 블렌딩 스테이트

[Visual Basic]

주 : 여기에서는, C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. DirectX for Visual Basic 의 경우, 어플리케이션에서는,Direct3DDevice7.SetTextureStageState 메소드를 D3DTSS_COLOROP 및 D3DTSS_ALPHAOP 텍스쳐 스테이지 스테이트에서 사용해, 텍스쳐 블렌딩을 제어할 필요가 있다.

[C++]

D3DRENDERSTATE_TEXTUREMAPBLEND 렌더링 스테이트는,D3DTSS_COLOROP 및 D3DTSS_ALPHAOP 텍스쳐 스테이지 스테이트를 개입시켜 사용할 수 있는 텍스쳐 블렌딩 스테이트로 옮겨지고 있다. 상세한 것에 대하여는, 「멀티 텍스쳐 블렌딩」을 참조할것.

주 : D3DRENDERSTATE_TEXTUREMAPBLEND 렌더링 스테이트는, 현재는 사용되어 있지 않기 때문에,IDirect3DDevice7 인터페이스에서는 인식되지 않는다. 이 렌더링 스테이트를 IDirect3DDevice7 인터페이스로 사용 하면 실패한다.


라이트의 방향

라이트의 방향 프로퍼티는, 오브젝트의 방사하는 빛이월드 공간내로 나아갈 방향을 결정한다. 방향은, 디렉셔널 라이트와 spotlight에서만 사용해, 벡터로 정의한다.

[C++]

C++ 어플리케이션에서는,D3DLIGHT7 구조체의 dvDirection 멤버 (D3DVECTOR 구조체)를 사용한다. 방향 벡터는, 장면내의 라이트의 위치 좌표 (와)는 관계없는 것으로, 논리 원점으로부터의 거리로서 기술한다. 따라서, 장면에 똑바로 입사 하는 (z 축의 정방향에 따라) spotlight의 방향 벡터는, 그 위치 좌표가 어디에 정의되고 있어도 <0, 0,1> 이다. 같이 장면을 바로 위로부터 비추는 태양광을 시뮬레이트 하려면 , 방향이 <0,-1, 0> 의 디렉셔널 라이트를 사용하면 좋다. 반드시 좌표축에 따라 비추는 라이트를 생성 할 필요가 없는 것은 분명하다. 값을 조합하거나 가지런히 하거나 해, 재미있는 각도로부터 라이트를 비출 수가 있다.

[Visual Basic]

Visual Basic 어플리케이션에서는, 라이트의 D3DLIGHT7 형의 direction 멤버에 라이트의 방향을 설정한다. direction 멤버는,D3DVECTOR 형에 속한다. 방향 벡터는, 장면내의 라이트의 위치 좌표 (와)는 관계없는 것으로, 논리 원점으로부터의 거리로서 기술한다. 따라서, 장면에 똑바로 입사 하는 (z 축의 정방향에 따라) spotlight의 방향 벡터는, 그 위치 좌표가 어디에 정의되고 있어도 <0, 0,1> 이다. 같이 장면을 바로 위로부터 비추는 태양광을 시뮬레이트 하려면 , 방향이 <0,-1, 0> 의 디렉셔널 라이트를 사용하면 좋다. 반드시 좌표축에 따라 비추는 라이트를 생성 할 필요가 없는 것은 분명하다. 값을 조합하거나 가지런히 하거나 해, 재미있는 각도로부터 라이트를 비출 수가 있다.

주 : 라이트의 방향 벡터를 정규화할 필요는 없지만, 반드시 벡터의 크기를 지정하는 것. 즉, <0, 0,0> 의 방향 벡터는 사용하지 않는다.


블렌딩용의 버텍스의 정의

[C++]

다음의 유저 정의 구조체는, 2 개의 행렬간에 블렌드 하는 버텍스에 사용할 수 있다.

//
// 이 버텍스의 유연한 버텍스 포맷 기술자는 다음과 같다.
//
//     dwFVF = D3DFVF_XYZB1 | D3DFVF_NORMAL | D3DFVF_TEX1;
//
struct D3DBLENDVERTEX {
D3DVECTOR v;
FLOAT     blend;
D3DVECTOR n;
FLOAT     tu, tv;
};

「블렌딩의 중량감」으로 설명하도록(듯이), 블렌드의 중량감은 유연한 버텍스 포맷내의 위치 좌표 및 RHW 데이터의 뒤로, 한편 버텍스 법선의 전에 없으면 안 된다.

전의 버텍스 포맷에는, 블렌딩의 중량감이 1 개 밖에 없는 것에 주의한다. 이것은,D3DTRANSFORMSTATE_WORLD 및 D3DTRANSFORMSTATE_WORLD1 트랜스 폼 스테이트에서 정의되는 2 개의 월드 행렬이 있기 때문에 있다. 이것들 2 개의 행렬간에 각각의 버텍스가, 1 개의 중량감을 사용해 블렌드 된다. 행렬이 3 개 있는 경우, 중량감은 2 개 필요하다.

[Visual Basic]

다음의 유저 정의형은, 2 개의 행렬간에 블렌드 하는 버텍스에 사용할 수 있다.

'
'이 버텍스의 유연한 버텍스 포맷 기술자는 다음과 같다.
'
'     lFVF = (D3DFVF_XYZB1 Or D3DFVF_NORMAL Or D3DFVF_TEX1)
'
Type D3DBLENDVERTEX
v As D3DVECTOR
blend As Single
n As D3DVECTOR
tu As Single
tv As Single
End Type

「블렌딩의 중량감」으로 설명하도록(듯이), 블렌드의 중량감은 유연한 버텍스 포맷내의 위치 좌표 및 RHW 데이터의 뒤로, 한편 버텍스 법선의 전에 없으면 안 된다.

전의 버텍스 포맷에는, 블렌딩의 중량감이 1 개 밖에 없는 것에 주의한다. 이것은,D3DTRANSFORMSTATE_WORLD 및 D3DTRANSFORMSTATE_WORLD1 트랜스 폼 스테이트에서 정의되는 2 개의 월드 행렬이 있기 때문에 있다. 이것들 2 개의 행렬간에 각각의 버텍스가, 1 개의 중량감을 사용해 블렌드 된다. 행렬이 3 개 있는 경우, 중량감은 2 개 필요하다.

주 : 스킨의 중량감은 간단하게 정의할 수 있다. Joint 하는 오브젝트간의 거리의 선형 함수를 사용 하면이야 겉껍데기, 보다 매끄러운 S 자 함수를 사용 하면 한층 더 좋다. 스킨의 중량감 분포 함수를 선택 하면, 필요에 따라서 Joint부에 선명 없음원을 붙일 수가 있다 (짧은 거리간에 스킨의 중량감의 변화를 크게 한다).

참조

버텍스 포맷에 대해,유연한 버텍스 포맷 플래그


텍스쳐 addressing mode의 설정과 취득

[C++]

IDirect3DDevice7::SetTextureStageState 메소드를 호출하는 것으로, 각각의 텍스쳐 스테이지에 텍스쳐 addressing mode를 설정할 수 있다. 제 1 파라미터에는, 희망의 텍스쳐 스테이지 식별자를 지정한다. 제 2 파라미터에는, u 및 v 의 양쪽 모두의 텍스쳐 addressing mode를 동시에 변경하는 D3DTSS_ADDRESS 를 설정하는지, u 또는 v 의 addressing mode를 개별적으로 갱신하는 D3DTSS_ADDRESSU 또는 D3DTSS_ADDRESSV 를 설정한다. SetTextureStageState 에 건네주는 제 3 파라미터에는, 설정하는 모드의 종류를 지정한다. 이 파라미터에는,D3DTEXTUREADDRESS 열거형의 멤버의 어느쪽이든을 설정할 수 있다. 지정한 텍스쳐 스테이지의 현재의 텍스쳐 addressing mode를 취득하려면 ,IDirect3DDevice7::GetTextureStageState 를 호출해,D3DTEXTURESTAGESTATETYPE 열거의 D3DTSS_ADDRESS, D3DTSS_ADDRESSU, 또는 D3DTSS_ADDRESSV 멤버를 사용해 정보를 취득하는 addressing mode를 지정한다.

종래의 IDirect3DDevice2 인터페이스를 사용하는 경우, 텍스쳐 addressing mode를 설정하려면 ,IDirect3DDevice2::SetRenderState 메소드를 호출해, u 및 v 의 텍스쳐 addressing mode를 동시에 설정하는 D3DRENDERSTATE_TEXTUREADDRESS 렌더링 스테이트를 사용한다. D3DRENDERSTATE_TEXTUREADDRESSU 또는 D3DRENDERSTATE_TEXTUREADDRESSV 렌더링 스테이트를 사용해, u 및 v 의 addressing mode를 개별적으로 설정할 수 있다. SetTextureStageState 에 대응하는, 새로운 렌더링 스테이트와 같이, 이러한 렌더링 스테이트도 D3DTEXTUREADDRESS 열거형의 값을 사용한다.

주 : IDirect3DDevice7::SetRenderState 메소드는,IDirect3DDevice2 버젼과는 대조적으로,D3DRENDERSTATE_TEXTUREADDRESS ,D3DRENDERSTATE_TEXTUREADDRESSU ,D3DRENDERSTATE_TEXTUREADDRESSV 렌더링 스테이트가 다른 렌더링 스테이트로 옮겨지고 있어도, 이러한 스테이트를 인식한다. IDirect3DDevice7 는 종래의 렌더링 스테이트를 인식해, 그 이펙트를 최초의 텍스쳐 스테이지 (스테이지 0)에 맵핑 한다. 종래의 렌더링 스테이트와 거기에 대응하는 텍스쳐 스테이지 스테이트를 병용 하지 않는 것. 예기치 못한 결과가 생기는 일이 있다.

[Visual Basic]

Visual Basic 에서는,Direct3DDevice7.SetTextureStageState 메소드를 호출하는 것으로, 각각의 텍스쳐 스테이지에 대해서 텍스쳐 addressing mode를 설정한다. 제 1 파라미터에는, 희망의 텍스쳐 스테이지 식별자를 지정한다. 제 2 파라미터에는, u 및 v 의 양쪽 모두의 텍스쳐 addressing mode를 동시에 변경하는 D3DTSS_ADDRESS 를 설정하는지, u 또는 v 의 addressing mode를 개별적으로 갱신하는 D3DTSS_ADDRESSU 또는 D3DTSS_ADDRESSV 를 설정한다. SetTextureStageState 에 건네주는 제 3 파라미터에는, 설정하는 모드의 종류를 지정한다. 이 파라미터에는,CONST_D3DTEXTUREADDRESS 열거의 멤버의 어느쪽이든을 설정할 수 있다.

지정한 텍스쳐 스테이지의 현재의 텍스쳐 addressing mode을 취득하려면 ,Direct3DDevice7::GetTextureStageState 를 호출해, 정보를 취득하는 addressing mode에의 CONST_D3DTEXTURESTAGESTATETYPE 열거의 D3DTSS_ADDRESS, D3DTSS_ADDRESSU, 또는 D3DTSS_ADDRESSV 멤버를 사용한다.


구(공)체 환경 맵이란

구(공)체 환경 맵, 또는 "구(공)체 맵" 은, 오브젝트의 주위의 장면의 화면 또는 오브젝트의 주위의 라이팅 이펙트를 포함한 특수한 텍스쳐이다. 큐브 환경 맵과는 달라, 구(공)체 맵은 오브젝트의 주위의 모습을 직접 표현하는 것은 아니다. 「환경 맵핑이란」의 주제의 티폿(주전자)의 화면은, 구(공)체 맵핑으로 실현될 수 있는 반사 이펙트를 나타내고 있다.

구(공)체 맵은, 오브젝트의 주위의 360о의 시야를, 어안 렌즈로 본 것처럼 2D 표현한 것이다. 다음은,Spheremap 샘플 (C++) 로 사용하는 구(공)체 맵이다.


큐브 환경 맵에의 렌더링

큐브 환경 맵을 DDSCAPS_3DDEVICE 로 생성 하는 경우, 그 외의 렌더링 타겟 표면과 같게, 큐브 맵의 각각의 표면에 렌더링 할 수가 있다. 이 렌더링을 실시하기 전에 실행하는 가장 중요한 일은, 카메라를 올바르게 배치해, 그 표면에 대해서 올바를 방향을 향하도록(듯이) 트랜스 폼 행렬을 설정하는 것이다. 올바를 방향이란, 전방 (+z), 후방 (-z), 좌 (-x), 우 (+x), 윗쪽 (+y), 또는 하부 (-y)이다.

[C++]

다음의 C++ 코드는, 렌더링 하는 표면에 응해 뷰 행렬을 준비해 설정한다.

//
// ppddsFaces 변수는, 각 표면에 대해서 1 개 있다
// IDirectDrawSurface7 인터페이스 포인터의 배열의 주소이다.
//
void RenderFaces(LPDIRECTDRAWSURFACE7* ppddsFaces)
{
// 큐브 맵의 6 개의 표면에 대해서 루프 처리를 실행한다.
for( DWORD i=0; i<6; i++ )
    {
DDSCAPS2 ddsc;
ZeroMemory( (LPVOID) &ddsc, sizeof(DDSCAPS2) );

// 표면 능력을 취득한다 (이것에 의해, 어느 표면인지를 파악한다).
ppddsFaces[i]->GetCaps( &ddsc );

// 이하와 같이, 표준 뷰를 옮겨놓는다.
D3DVECTOR vEnvEyePt = D3DVECTOR( 0.0f, 0.0f, 0.0f );
D3DVECTOR vLookatPt, vUpVec;

switch( ddsc.dwCaps2 & DDSCAPS2_CUBEMAP_ALLFACES )
        {
case DDSCAPS2_CUBEMAP_POSITIVEX:
vLookatPt = D3DVECTOR( 1.0f, 0.0f, 0.0f );
vUpVec    = D3DVECTOR( 0.0f, 1.0f, 0.0f );
break;
case DDSCAPS2_CUBEMAP_NEGATIVEX:
vLookatPt = D3DVECTOR(-1. 0f, 0.0f, 0.0f );
vUpVec    = D3DVECTOR( 0.0f, 1.0f, 0.0f );
break;
case DDSCAPS2_CUBEMAP_POSITIVEY:
vLookatPt = D3DVECTOR( 0.0f, 1.0f, 0.0f );
vUpVec    = D3DVECTOR( 0.0f, 0.0f,-1. 0f );
break;
case DDSCAPS2_CUBEMAP_NEGATIVEY:
vLookatPt = D3DVECTOR( 0.0f,-1. 0f, 0.0f );
vUpVec    = D3DVECTOR( 0.0f, 0.0f, 1.0f );
break;
case DDSCAPS2_CUBEMAP_POSITIVEZ:
vLookatPt = D3DVECTOR( 0.0f, 0.0f, 1.0f );
vUpVec    = D3DVECTOR( 0.0f, 1.0f, 0.0f );
break;
case DDSCAPS2_CUBEMAP_NEGATIVEZ:
vLookatPt = D3DVECTOR( 0.0f, 0.0f,-1. 0f );
vUpVec    = D3DVECTOR( 0.0f, 1.0f, 0.0f );
break;
        }

D3DMATRIX matView;
D3DUtil_SetViewMatrix( matView, vEnvEyePt, vLookatPt, vUpVec );
g_pd3dDevice->SetTransform( D3DTRANSFORMSTATE_VIEW, &matView );

큐브 환경 맵의 각 표면에는 90о의 시야가 포함되는 것을 생각해 내는 것. 어플리케이션으로 특수 효과등을 (위해)때문에에 시야의 각도를 변경하지 않는 한, 이 각도에 응해 투영 행렬을 설정하도록(듯이) 주의가 필요하다.

다음의 코드는, 가장 일반적으로 사용하는 투영 행렬을 생성 및 설정한다.

// 90о의 시야를 투영에 사용한다.
D3DMATRIX matProj;
D3DUtil_SetProjectionMatrix( matProj, g_PI/2, 1.0f, 0.5f, 1000.0f );
g_pd3dDevice->SetTransform( D3DTRANSFORMSTATE_PROJECTION, &matProj );

카메라를 올바르게 배치해, 투영 행렬을 설정 하면, 장면을 렌더링 할 수 있다. 장면의 각 오브젝트는, 보통 배치 하면 내려에 배치한다. 다음의 코드에서는, 처리를 완전하게 가리키기 위해서(때문에), 이 태스크에 대해서는 대략적으로 가리킨다.

        //
// 장면의 렌더링
        //

// 깊이 버퍼를 표면으로 바꾸어 넣어 렌더링 타겟 해 설정한다.
// 이 함수에 대해서는, 다음에 자세하게 설명한다.
ChangeRenderTarget( ppddsFaces[i] );

// z 버퍼를 클리어 한다.
g_pd3dDevice->Clear( 0, NULL, D3DCLEAR_ZBUFFER, 0x000000ff, 1.0f, 0L );

// anti-aliasing를 유효한다. 이것에 의해, 환경 맵의 외형이 예쁘게 된다.
g_pd3dDevice->SetRenderState( D3DRENDERSTATE_ANTIALIAS,
D3DANTIALIAS_TRANSLUCENTSORTINDEPENDENT );

// 장면을 시작 한다.
if( SUCCEEDED( g_pd3dDevice->BeginScene() ) )
        {
// 장면의 지오메트리를 보통대로 배치한다.
// 이 때문에는, 렌더링 하는 각 오브젝트의 월드 행렬을 설정한다.

            g_pd3dDevice->DrawPrimitive( D3DPT_TRIANGLELIST,
D3DFVF_XYZ | D3DFVF_NORMAL | D3DFVF_TEX1 | D3DFVF_TEXCOORDSIZE3(0),
lpVertices, VERTEX_COUNT, 0);

// 장면을 종료한다.
g_pd3dDevice->EndScene();
        }
    }
}

주 : 큐브 환경 맵에의 렌더링을 실행할 때는, 대부분의 어플리케이션으로 anti-aliasing를 유효하게 할 필요가 있다. 각 표면은 비교적 작은 것이기 (위해)때문에, 그 표면에의 렌더링 시에 anti-aliasing를 유효하게 해 두면(자), 외형이 매우 깨끗한 환경 맵을 생성할 수 있다.

ChangeRenderTarget 함수의 호출에는 주의 해야 한다. 큐브 맵 표면에 렌더링 하면나무는, 그 표면을 현재 렌더링 타겟 표면으로서 할당할 필요가 있다. 깊이 버퍼를 사용하는 어플리케이션에서는, 그 렌더링 타겟으로 명시적으로 깊이 버퍼를 생성 하거나 기존의 깊이 버퍼를 렌더링 타겟 표면에 재할인 맞히고 할 수가 있다. 다음의 코드는, 후자의 방법을 사용한다.

HRESULT ChangeRenderTarget( LPDIRECTDRAWSURFACE7 pddsNewTarget)
{
LPDIRECTDRAWSURFACE7 pddsOldRenderTarget = NULL;
g_pd3dDevice->GetRenderTarget( &pddsOldRenderTarget );

if( pddsOldRenderTarget )
    {
LPDIRECTDRAWSURFACE7 pddsZBuffer = NULL;
DDSCAPS2 ddscaps = { DDSCAPS_ZBUFFER, 0, 0, 0 };
pddsOldRenderTarget->GetAttachedSurface( &ddscaps, &pddsZBuffer );

if( pddsZBuffer )
        {
pddsOldRenderTarget->DeleteAttachedSurface( 0, pddsZBuffer );
pddsNewRenderTarget->AddAttachedSurface( pddsZBuffer );
pddsZBuffer->Release();
        }
        pddsOldRenderTarget->Release();
    }

g_pd3dDevice->SetRenderTarget( pddsNewRenderTarget, 0 );
    return S_OK;
}
[Visual Basic]

다음의 Visual Basic 코드는, 렌더링 하는 표면에 응해 뷰 행렬을 준비해 설정한다.

'
' ddsFaces 변수는, 각 표면에 대해서 1 개 있다
' DirectDrawSurface7 오브젝트의 배열의 주소이다.
'
Sub RenderFaces(ddsFaces() As DirectDrawSurface7)
Dim i As Integer

'큐브 맵의 6 개의 표면에 대해서 루프 처리를 실행한다.
For i = 0 To UBound(ddsFaces)
Dim ddsc As DDSCAPS2
Dim vEnvEyePt As D3DVECTOR, _
vLookatPt As D3DVECTOR, _
vUpVec As D3DVECTOR

'표면 능력을 취득한다 (이것에 의해, 어느 표면인지를 파악한다).
Call ddsFaces(i). GetCaps(ddsc)

Select Case (ddsc.dwCaps2 And DDSCAPS2_CUBEMAP_ALLFACES)
Case DDSCAPS2_CUBEMAP_POSITIVEX:
vLookatPt.x = 1#:vUpVec.y = 1#

Case DDSCAPS2_CUBEMAP_NEGATIVEX:
vLookatPt.x = -1#:vUpVec = 1#

Case DDSCAPS2_CUBEMAP_POSITIVEY:
vLookatPt.y = 1#:vUpVec.z = -1#

Case DDSCAPS2_CUBEMAP_NEGATIVEY:
vLookatPt.y = -1#:vUpVec.z = 1#

Case DDSCAPS2_CUBEMAP_POSITIVEZ:
vLookatPt.z = 1#:vUpVec.y = 1#

Case DDSCAPS2_CUBEMAP_NEGATIVEZ:
vLookatPt.z = -1#:vUpVec.y = 1#

End Select

Dim matView As D3DMATRIX
Call g_dx.ViewMatrix(matView, vEnvEyePt, vLookatPt, vUpVec)
Call g_pd3dDevice.SetTransform(D3DTRANSFORMSTATE_VIEW, matView)

큐브 환경 맵의 각 표면에는 90о의 시야가 포함되는 것을 생각해 내는 것. 어플리케이션으로 특수 효과등을 (위해)때문에에 시야의 각도를 변경하지 않는 한, 이 각도에 응해 투영 행렬을 설정하도록(듯이) 주의가 필요하다.

다음의 코드는, 가장 일반적으로 사용하는 투영 행렬을 생성 및 설정한다.

' 90о의 시야를 투영에 사용한다.
Dim matProj As D3DMATRIX
Call g_dx.ProjectionMatrix(matProj, 0.5, 1000#, 3.1415926535 / 2)
Call g_d3dDevice.SetTransform(D3DTRANSFORMSTATE_PROJECTION, matProj)

카메라를 올바르게 배치해, 투영 행렬을 설정 하면, 장면을 렌더링 할 수 있다. 장면의 각 오브젝트는, 보통 배치 하면 내려에 배치한다. 다음의 코드에서는, 처리를 완전하게 가리키기 위해서(때문에), 이 태스크에 대해서는 대략적으로 가리킨다.

        '
'장면의 렌더링
        '

'깊이 버퍼를 표면으로 바꾸어 넣어 렌더링 타겟 해 설정한다.
'이 함수에 대해서는, 다음에 자세하게 설명한다.
Call ChangeRenderTarget(ddsFaces(i))

Dim rec(1) As RECT
rec.Top = 0:rec.Left = 0

'표면의 크기는 64x64 이다고 한다.
rec.Bottom = 64:rec.Right = 64

' z 버퍼를 클리어 한다.
Call g_d3dDevice.Clear(0, rec(), D3DCLEAR_ZBUFFER, _
g_dx.CreateColorRGBA(0, 0, 256, 0), 1#, 0)

'anti-aliasing를 유효한다. 이것에 의해, 환경 맵의 외형이 예쁘게 된다.
Call g_d3dDevice.SetRenderState(D3DRENDERSTATE_ANTIALIAS, _
D3DANTIALIAS_TRANSLUCENTSORTINDEPENDENT)

'장면을 시작 한다.
Call g_d3dDevice.BeginScene
If Err.Number = DD_OK Then
'장면의 지오메트리를 보통대로 배치한다.
'이 때문에는, 렌더링 하는 각 오브젝트의 월드 행렬을 설정한다.

Call g_pd3dDevice.DrawPrimitive(D3DPT_TRIANGLELIST, D3DFVF_XYZ Or D3DFVF_NORMAL Or _
D3DFVF_TEX1 Or D3DFVF_TEXCOORDSIZE3(0), _
g_Vertices(0), VERTEX_COUNT, 0)

// 장면을 종료한다.
Call g_d3dDevice.EndScene
End If
Next i
End Sub

주 : 큐브 환경 맵에의 렌더링을 실행할 때는, 대부분의 어플리케이션으로 anti-aliasing를 유효하게 할 필요가 있다. 각 표면은 비교적 작은 것이기 (위해)때문에, 그 표면에의 렌더링 시에 anti-aliasing를 유효하게 해 두면(자), 외형이 매우 깨끗한 환경 맵을 생성할 수 있다.

ChangeRenderTarget 서브 루틴의 호출에는 주의 해야 한다. 큐브 맵 표면에 렌더링 하면나무는, 그 표면을 현재 렌더링 타겟 표면으로서 할당할 필요가 있다. 깊이 버퍼를 사용하는 어플리케이션에서는, 그 렌더링 타겟으로 명시적으로 깊이 버퍼를 생성 하거나 기존의 깊이 버퍼를 렌더링 타겟 표면에 재할인 맞히고 할 수가 있다. 다음의 코드는, 후자의 방법을 사용한다.

Sub ChangeRenderTarget(ddsNewTarget As DirectDrawSurface7)
Dim ddsOldRenderTarget As DirectDrawSurface7

Set ddsOldRenderTarget = g_pd3dDevice.GetRenderTarget

If (ddsOldRenderTarget Is Not Nothing) Then
Dim ddsZBuffer As DirectDrawSurface7
Dim ddscaps As DDSCAPS2

ddscaps.lCaps = DDSCAPS_ZBUFFER
Set ddsZBuffer = ddsOldRenderTarget.GetAttachedSurface

If (ddsZBuffer Is Not Nothing) Then
Call ddsOldRenderTarget.DeleteAttachedSurface(ddsZBuffer)
Call ddsNewRenderTarget.AddAttachedSurface(ddsZBuffer)
End If
End If

Call g_pd3dDevice.SetRenderTarget(pddsNewRenderTarget)
End Sub


큐브 환경 맵 표면에의 액세스

[C++]

그 외의 복합 표면과 같이,IDirectDrawSurface7::GetAttachedSurface 메소드를 사용해 큐브 환경 맵의 표면으로부터 표면으로 이동할 수 있다. GetAttachedSurface 메소드는, 이 메소드로 취득할 필요가 있는 Attach 된 표면을 기술하는 DDSCAPS2 구조체에의 포인터를 받는다. dwCaps2 멤버에,"DDSCAPS2_CUBEMAP_" 으로 시작되는 플래그의 어느쪽이든을 DDSCAPS2_CUBEMAP 플래그와 조합해 설정해, 대응하는 표면을 취득한다.

다음의 코드는, 정방향의 y 면 (표면 2)의 큐브 맵 표면을 취득한다.

// 이 예에서는, 큐브 맵이 최초로 생성 되었을 때에 CreateSurface 가 돌려주는 표면에의
// 유효한 포인터가
// pddsMainFace 변수에 저장 되고 있다.
LPDIRECTDRAWSURFACE7 pddsFace2;

DDSCAPS2 ddsCaps;
ddsCaps.dwCaps2 = DDSCAPS2_CUBEMAP_POSITIVEY | DDSCAPS2_CUBEMAP;

HRESULT hr;
hr = pddsMainFace->GetAttachedSurface( &ddsCaps,
&pddsFace2);

if( FAILED(hr) )
{
// 에러 처리 코드
}
[Visual Basic]

그 외의 복합 표면과 같이,DirectDrawSurface7.GetAttachedSurface 메소드를 사용해 큐브 환경 맵의 표면으로부터 표면으로 이동할 수 있다. GetAttachedSurface 메소드는, 이 메소드로 취득할 필요가 있는 Attach 된 표면을 기술하는 DDSCAPS2 형을 받는다. lCaps2 멤버에,"DDSCAPS2_CUBEMAP_" 으로 시작되는,CONST_DDSURFACECAPS2FLAGS 열거로부터의 플래그의 어느쪽이든을 DDSCAPS2_CUBEMAP 플래그와 조합해 지정해, 대응하는 표면을 취득한다.

다음의 코드는, 정방향의 y 면 (표면 2)의 큐브 맵 표면을 취득한다.

'이 예에서는, 큐브 맵이 최초로 생성 되었을 때에 CreateSurface 가 돌려주는 표면에의
'유효한 참조가
' ddsMainFace 변수에 저장 되고 있다.
Dim ddsFace2 As DirectDrawSurface7
Dim ddsCaps As DDSCAPS2

ddsCaps.lCaps2 = DDSCAPS2_CUBEMAP_POSITIVEY Or DDSCAPS2_CUBEMAP

Set ddsFace2 = ddsMainFace.GetAttachedSurface(ddsCaps)

If Err.Number <> DD_OK Then
'에러 처리 코드
End If


버텍스 버퍼 렌더링에 대해

어플리케이션이 버텍스를 버텍스 버퍼로부터 렌더링 하는 일반적인 스테이트는 2 개 있다. 가장 기본적인 레벨로, 2 개의 스테이트는, 「렌더링시」에 버텍스 버퍼내에 있는 버텍스의 종류에 의해 나눌 수 있다. 그러나, 간접적으로는, 어플리케이션의 사용하는 순서가, 언제 버텍스 조작과 렌더링 조작을 실행할까를 결정한다. 어플리케이션으로 버텍스 버퍼로부터 렌더링 하는 경우는, 버텍스 버퍼 메소드를 사용할 필요가 있다. 다음의 도표로, 트랜스폼 되지 않은 버텍스 버퍼로부터의 렌더링 처리를 설명한다.

[C++]

위에의도에 나타내도록(듯이),IDirect3DDevice7::DrawPrimitiveVB 및 IDirect3DDevice7::DrawIndexedPrimitiveVB 메소드에서는, 트랜스폼 되지 않은의 버텍스 버퍼로부터의 렌더링을 실행할 수 있다. 이 경우, 렌더링 메소드를 호출할 때마다, 시스템은 버텍스 조작과 렌더링 조작을 실시한다. 이 방법을 사용해도, 종래의 DrawPrimitive 렌더링 메소드보다 뛰어난 퍼포먼스를 얻을 수 것은 아니지만, 경우에 따라서는 편리한 때도 있다. 다음의 그림에 나타내도록(듯이), 가능하면 트랜스 폼 된 버텍스 데이터를 재사용해, 퍼포먼스를 최적화할 수 있다.

[Visual Basic]

위에의도에 나타내도록(듯이), Visual Basic 의 Direct3DDevice7.DrawPrimitiveVB 및 Direct3DDevice7.DrawIndexedPrimitiveVB 메소드에서는, 트랜스폼 되지 않은의 버텍스 버퍼로부터의 렌더링을 실행할 수 있다. 이 경우, 렌더링 메소드를 호출할 때마다, 시스템은 버텍스 조작과 렌더링 조작을 실시한다. 이 방법을 사용해도, 종래의 DrawPrimitive 렌더링 메소드보다 뛰어난 퍼포먼스를 얻을 수 것은 아니지만, 경우에 따라서는 편리한 때도 있다. 다음의 그림에 나타내도록(듯이), 가능하면 트랜스 폼 된 버텍스 데이터를 재사용해, 퍼포먼스를 최적화할 수 있다.

[C++]

이 경우, 어플리케이션은 2 개의 버텍스 버퍼를 생성 한다. 1 개(살)은 트랜스폼 되지 않은의 지오메트리용으로, 이제(벌써) 1 개(살)은 트랜스 폼 된 지오메트리용이다. IDirect3DVertexBuffer7::ProcessVertices 가 불려 갔을 때, 제 2 버퍼는 트랜스 폼이 끝난 버텍스 데이터를 취득한다. ProcessVertices 메소드는, 전송원버퍼내의 버텍스를 읽어내, 요구된 버텍스 조작을 실시해, 결과를 목적지 버퍼에 넣는다. 트랜스폼 되지 않은의 버텍스를 렌더링 하도록(듯이), 트랜스 폼 된 버텍스에 대해서 같은 렌더링 메소드를 호출할 수가 있다. 다만, 트랜스폼 되지 않은의 버텍스와 달리, Direct3D 는 버텍스 버퍼내의 데이터가 트랜스 폼 되고 있는 것을 자동적으로 검출해, 즉시 rasterize 되도록(듯이) 전송 한다. 불필요한 트랜스 폼을 생략 해, 퍼포먼스의 오버헤드는 최소로 유지된다.

주 : IDirect3DVertexBuffer7 인터페이스는, 새로운 메소드로서 IDirect3DVertexBuffer7::ProcessVerticesStrided 를 제공한다. 이 메소드는, 보폭 버텍스를 목적지 버텍스 버퍼에 처리한다.

[Visual Basic]

이 경우, 어플리케이션은 2 개의 버텍스 버퍼를 생성 한다. 1 개(살)은 트랜스폼 되지 않은의 지오메트리용으로, 이제(벌써) 1 개(살)은 트랜스 폼 된 지오메트리용이다. Direct3DVertexBuffer7.ProcessVertices 가 불려 갔을 때, 제 2 버퍼는 트랜스 폼이 끝난 버텍스 데이터를 받는다. ProcessVertices 메소드는, 전송원버퍼내의 버텍스를 읽어내, 요구된 버텍스 조작을 실시해, 결과를 목적지 버퍼에 넣는다. 트랜스폼 되지 않은의 버텍스를 렌더링 하도록(듯이), 변환된 버텍스에 대해서 같은 렌더링 메소드를 호출할 수가 있다. 다만, 미변환의 버텍스와 달리, Direct3D 는 버텍스 버퍼내의 데이터가 트랜스 폼 되고 있는 것을 자동적으로 검출해, 즉시 rasterize 되도록(듯이) 전송 한다. 불필요한 트랜스 폼을 생략 해, 퍼포먼스의 오버헤드는 최소로 유지된다.

버텍스 버퍼의 내용을 최적화 하면, 퍼포먼스를 한층 더 향상할 수 있다. 상세한 것에 대하여는, 「버텍스 버퍼의 최적화」를 참조할것.


픽셀 포그(안개:fog)의 사용

어플리케이션으로 픽셀 포그(안개:fog)를 유효하게 하려면 , 다음의 순서를 실행한다.

[C++]

C++ 어플리케이션으로 픽셀 포그(안개:fog)를 유효하게 하려면

  1. D3DRENDERSTATE_FOGENABLE 렌더링 스테이트를 TRUE 로 설정해, 포그(안개:fog) 블렌딩을 유효하게 한다.
  2. D3DRENDERSTATE_FOGCOLOR 렌더링 스테이트에서, 희망의 포그(안개:fog) 컬러를 설정한다.
  3. D3DRENDERSTATE_FOGTABLEMODE 렌더링 스테이트를 D3DFOGMODE 열거형의 대응하는 멤버로 설정해, 사용하는 포그(안개:fog) 공식을 선택한다.
  4. 선택한 포그(안개:fog) 모드에 필요한 포그(안개:fog) 파라미터를, 관련하는 렌더링 스테이트로 설정한다. 선형 포그(안개:fog)의 시작 거리와 종료 거리, 지수 포그(안개:fog)의 포그(안개:fog) 밀도도 포함한다.

다음의 예는, 이상의 순서를 코드로 가리킨다.

// 간단하게 하기 위해서, 이 예에서는 각 호출의 후에
// 에러값을 체크하지 않는다. 실제의 어플리케이션에서는,
// 에러값을 적절히 체크하는 것.
//
// 이 예에서는, g_lpDevice 는 IDirect3DDevice7 인터페이스에의
// 유효한 포인터이다.
void SetupPixelFog(DWORD dwColor, DWORD dwMode)
{
    float fStart = 0.5f,    // 선형 모드용
          fEnd   = 0.8f,
          fDensity = 0.66;  // 지수 모드용

    // 포그(안개:fog) 블렌딩을 유효하게 한다.
    g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGENABLE, TRUE);

    // 포그(안개:fog) 컬러를 설정한다.
    g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGCOLOR, dwColor);

    // 포그(안개:fog) 파라미터를 설정한다.
    if(D3DFOG_LINEAR == dwMode)
    {
        g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGTABLEMODE, dwMode);
        g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGSTART, *(DWORD *)(&fStart));
        g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGEND,   *(DWORD *)(&fEnd));
    }
    else
    {
        g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGTABLEMODE, dwMode);
        g_lpDevice->SetRenderState(D3DRENDERSTATE_FOGDENSITY, *(DWORD *)(&fDensity));
    }

}

주 : IDirect3DDevice7::SetRenderState 메소드는, 제 2 파라미터에 DWORD 값만을 받지만, 부동 소수점의 포그(안개:fog) 파라미터가 요구되는 일도 있다. 위에의예에서는 부동 소수점의 값을 SetRenderState 에 건네주기 위해서(때문에), 데이터를 트랜스 폼 하는 것이 아니라, 부동 소수점 변수의 주소를 DWORD 포인터에 캐스트 해, 다음에 그것을 참조하고 있다.

[Visual Basic]

Visual Basic 어플리케이션으로 픽셀 포그(안개:fog)를 유효하게 하려면

  1. D3DRENDERSTATE_FOGENABLE 렌더링 스테이트를 True 로 설정해, 포그(안개:fog) 블렌딩을 유효하게 한다.
  2. D3DRENDERSTATE_FOGCOLOR 렌더링 스테이트에서, 필요한 포그(안개:fog) 컬러를 설정한다.
  3. D3DRENDERSTATE_FOGTABLEMODE 렌더링 스테이트를 CONST_D3DFOGMODE 열거의 대응하는 멤버로 설정해, 사용하는 포그(안개:fog) 공식을 선택한다.
  4. 선택한 포그(안개:fog) 모드에 필요한 포그(안개:fog) 파라미터를, 관련하는 렌더링 스테이트로 설정한다. 선형 포그(안개:fog)의 시작 거리와 종료 거리, 지수 포그(안개:fog)의 포그(안개:fog) 밀도도 포함한다.

다음의 예는, 이상의 순서를 코드로 가리킨다.

'간단하게 하기 위해서, 이 예에서는 각 호출의 후에
'에러값을 체크하지 않는다. 실제의 어플리케이션에서는,
'에러값을 적절히 체크하는 것.
'
'이 예에서는, g_d3dDevice 는 Direct3DDevice7 오브젝트에의
'유효한 포인터이다.
Sub SetupPixelFog(lColor As Long, Mode As CONST_D3DFOGMODE)
Dim StartFog As Single, _
EndFog As Single, _
Density As Single

'선형 모드용
StartFog = 0.5:EndFog = 0.8

'지수 모드용
Density = 0.66

'포그(안개:fog) 블렌딩을 유효하게 한다.
Call g_d3dDevice.SetRenderState(D3DRENDERSTATE_FOGENABLE, True)

'포그(안개:fog) 컬러를 설정한다.
Call g_d3dDevice.SetRenderState(D3DRENDERSTATE_FOGCOLOR, lColor)

'포그(안개:fog) 파라미터를 설정한다.
If Mode = D3DFOG_LINEAR Then
Call g_d3dDevice.SetRenderState(D3DRENDERSTATE_FOGTABLEMODE, Mode)
Call g_d3dDevice.SetRenderStateSingle(D3DRENDERSTATE_FOGSTART, StartFog)
Call g_d3dDevice.SetRenderStateSingle(D3DRENDERSTATE_FOGEND, EndFog)
Else
Call g_d3dDevice.SetRenderState(D3DRENDERSTATE_FOGTABLEMODE, Mode)
Call g_d3dDevice.SetRenderStateSingle(D3DRENDERSTATE_FOGDENSITY, Density)
End If
End Sub


스텝 2.1 : 뷰 포인트를 정의한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

이 튜토리얼에서는, 어플리케이션 정의 서브 루틴 App_FrameMove 를 사용해, 엔 위에서 뷰 포인트를 회전시킨다. 뷰 포인트는, 시점, 주시점, 및 윗방향을 정의하는 벡터의 3 개의 D3DVECTOR 구조체로 정의하는 것이 가장 간단하다.

HRESULT App_FrameMove( LPDIRECT3DDEVICE7 pd3dDevice, FLOAT fTimeKey )
{
    D3DVECTOR vEyePt    = D3DVECTOR( 5*sinf( fTimeKey), 3, 5*cosf( fTimeKey ) );
    D3DVECTOR vLookatPt = D3DVECTOR( 4*sinf( fTimeKey+0. 1f), 2.5, 4*cosf( fTimeKey+0. 1f ) );
    D3DVECTOR vUpVec    = D3DVECTOR( 0, 1, 0 );

3 개의 벡터를 사용해 새로운 뷰 행렬을 생성 한다.

    D3DMATRIX matView;
    SetViewMatrix( matView, vEyePt, vLookatPt, vUpVec );

위의 코드에서는, 시점, 주시점, 및 윗방향을 정의하는 벡터를 프로그래머 정의의 SetViewMatrix 메소드에 건네주어 디바이스에 새로운 뷰 행렬을 생성 한다. 이것에 대해서는, 「스텝 2.2 : 뷰 행렬을 생성 및 설정한다」로 설명한다.


스텝 1.3 : 디바이스 정보를 열거한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

IDirect3D7::EnumDevices 메소드는, 시스템에 인스톨 떠날 수 있어 모든 Direct3D 디바이스 드라이버를 열거한다. Enumeration 어플리케이션에서는, 다음의 파라미터를 사용해 EnumDevices 함수를 호출한다.

    pD3D->EnumDevices( DeviceEnumCallback, &d3dDeviceInfo );

제 1 인수 DeviceEnumCallback, 는, 열거때 Direct3D 디바이스가 건네받을 때마다 불려 가는 D3DEnumDevicesCallback7 콜백 함수의 주소이다. 제 2 파라미터는, 열거중의 디바이스를 기술하는 D3DDEVICEINFO 구조체에의 참조이다.

열거되는 디바이스 마다, 다음의 함수가 불려 간다.

static HRESULT WINAPI DeviceEnumCallback(LPSTR strDesc,
                                  LPSTR strName, D3DDEVICEDESC7* pDesc,
                                  VOID* pParentInfo )
{

최초의 2 개의 파라미터는, 각각 디바이스의 설명 및 이름의 캐릭터 라인이다. 제 3 파라미터 pDesc 는, Direct3D 디바이스의 하드웨어 능력을 기술하는 D3DDEVICEDESC7 구조체이다. 이 함수의 상세한 것에 대하여는, SDK 레퍼런스의 「D3DEnumDevicesCallback7」의 항목을 참조할것.

다음의 코드로, 열거중의 디바이스에 디바이스 정보를 설정할 수 있다.

    D3DDEVICEINFO* pDriverInfo = (D3DDEVICEINFO*) pParentInfo;
    D3DDEVICEINFO* pDeviceInfo = &g_d3dDevices[g_dwNumDevices];
    memcpy( &pDeviceInfo->ddDeviceDesc, pDesc, sizeof(D3DDEVICEDESC7) );
    pDeviceInfo->guidDevice   = pDesc->deviceGUID;
    pDeviceInfo->pDeviceGUID  = &pDeviceInfo->guidDevice;
    pDeviceInfo->bHardware    = pDesc->dwDevCaps & D3DDEVCAPS_HWRASTERIZATION;
    pDeviceInfo->dwNumModes   = 0;
    pDeviceInfo->ddDriverCaps = pDriverInfo->ddDriverCaps;
    pDeviceInfo->ddHELCaps    = pDriverInfo->ddHELCaps;

위의 코드에서는,D3DDEVICEINFO 구조체 pDeviceInfo 에 디바이스 능력이 저장 된다. pParentInfo 는, 여기로부터 드라이버의 GUID 및 설명을 꺼낼 수 있도록(듯이) D3DDEVICEINFO 형에 캐스트 되는 것에 주의한다.

디바이스 정보를 취득할 수 있었으므로, 디바이스 정보를 보관 유지하는 D3DDEVICEINFO 구조체에 디바이스의 드라이버 GUID 및 설명을 카피한다.

        pDeviceInfo->guidDriver  = pDriverInfo->guidDriver;
        pDeviceInfo->pDriverGUID = &pDeviceInfo->guidDriver;
        strncpy( pDeviceInfo->strDesc, pDriverInfo->strDesc, 39 );

디스플레이 드라이버, 디스플레이 모드, 및 디바이스를 열거하면(자), 다음은 어플리케이션으로 사용하는 디바이스를 이러한 안으로부터 선택한다. 이것에 대해서는, 「스텝 2 : 열거된 디바이스의 선택」으로 설명한다.


스텝 2.4 : 뷰포트를 준비한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

렌더링 디바이스를 생성 한 후, 뷰포트를 생성 해 디바이스에 할당할 수가 있다. 간단하게 말하면, 뷰포트란, 3D 신의 지오메트리를 클립 해 2D 표시 공간에 표현하는 방법을 결정하는 것이다. (뷰포트의 개요에 대해서는, 「뷰포트와 클리핑」을 참조할것).

뷰포트의 설정은 간단해,D3DVIEWPORT7 구조체에 뷰포트 파라미터를 준비하는 것으로부터 시작된다. 샘플 Triangle 에서는, 뷰포트 파라미터를 렌더링 타겟 표면의 사이즈로 설정해 있다.

    // 뷰포트를 생성 한다.
    DWORD dwRenderWidth  = g_rcScreenRect.right - g_rcScreenRect.left;
    DWORD dwRenderHeight = g_rcScreenRect.bottom - g_rcScreenRect.top;
    D3DVIEWPORT7 vp = { 0, 0, dwRenderWidth, dwRenderHeight, 0.0f, 1.0f };

뷰포트 구조체를 준비 하면, 이 구조체는 Triangle 어플리케이션에 의해 렌더링 디바이스에 할당할 수 있다.

    hr = g_pd3dDevice->SetViewport( &vp );
    if( FAILED( hr ) )
        return hr;

여기서, 기본적인 DirectX 오브젝트의 생성이 종료했으므로, 장면의 렌더링에 필요한 종속 오브젝트의 준비를 시작할 수가 있다. 이것이, 「스텝 3 : 신을 초기화한다」의 설명 내용이다.


스텝 1.2 : 디스플레이 모드 정보를 열거한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

IDirectDraw7::EnumDisplayModes 메소드는, 하드웨어가 DirectDraw 오브젝트를 개입시켜 공개하는 모든 디스플레이 모드를 열거한다. Enumeration 어플리케이션에서는, 다음의 파라미터를 사용해 EnumDisplayModes 함수를 호출한다.

    // 풀 스크린 디스플레이 모드를 열거한다.
    pDD->EnumDisplayModes( 0, NULL, &d3dDeviceInfo, ModeEnumCallback );

인수 NULL 는 모든 모드의 열거를 지정한다. 제 3 파라미터 &d3dDeviceInfo 는, 드라이버 정보를 저장 하는 D3DDEVICEINFO 구조체의 주소이며, 각 열거 멤버에게 건네진다. 제 4 파라미터는,EnumModesCallback2 콜백 함수의 주소 ModeEnumCallback 이며, 하드웨어가 공개하는 전모드에 대해서 열거 프로시저로 불려 간다.

static HRESULT WINAPI ModeEnumCallback( DDSURFACEDESC2* pddsd,
                                        VOID* pParentInfo )
{
    // 드라이버로 지원 되는 모드의 리스트에 모드를 카피한다.
    D3DDEVICEINFO* pDriverInfo = (D3DDEVICEINFO*) pParentInfo;
    pDriverInfo->ddsdModes[pDriverInfo->dwNumModes++] = (*pddsd);

    return DDENUMRET_OK;
}

위의 코드에서는, 최초의 파라미터 pddsd, 는, 생성 가능한 디스플레이 모드에 관한 정보를 저장 하는 read 전용의 DDSURFACEDESC2 구조체이다. pParentInfo 파라미터 (디스플레이 드라이버를 나타내는 어플리케이션 정의 데이터)는, 확실히 참조되도록(듯이) D3DDEVICEINFO 구조체에 캐스트 된다. 모든 디스플레이 모드가 열거되면(자), 다음은 Direct3D 디바이스를 열거한다. 이 스텝에 대해서는, 「스텝 1.3 : 디바이스 정보를 열거한다」로 설명한다.


스텝 2.2 : 뷰 행렬을 생성 및 설정한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

시점, 주시점, 윗방향 벡터를 지정 하면, 어플리케이션에 수동으로 4×4 뷰 행렬을 생성 할 수 있다. 우선, 깊이를 나타내는 z 축벡터를 취득한다.

HRESULT SetViewMatrix( D3DMATRIX& mat, D3DVECTOR& vFrom, D3DVECTOR& vAt,
                       D3DVECTOR& vWorldUp )
{
    // 깊이를 나타내는 z 축벡터를 취득한다. 이것은 주시점에 대한다
    // 시점과는 다르다.
    D3DVECTOR vView = vAt - vFrom;

z 축벡터는, 주시점에 대한 시점과는 다르다. z 축벡터는, 계산에 사용하기 전에 정규화할 필요가 있다.

    FLOAT fLength = Magnitude( vView );
    if( fLength < 1e-6f )
        return E_INVALIDARG;

    // z 축벡터를 정규화한다.
    vView /= fLength;

위의 코드에서는, 뷰 벡터의 절대치를 돌려주는 Magnitude 함수를 사용하고 있다. Magnitude 함수는, 프로젝트로 D3D_OVERLOADS 를 정의하는 프로그래머가 사용한다. D3D_OVERLOADS 의 C++ 확장 기능에 의해 제공된다. 헬퍼-함수의 상세한 것에 대하여는, 「D3D_OVERLOADS 헬퍼-함수」를 참조할것.

이 시점에서, 내적을 취득해 z 축벡터에 있어서의 윗방향 벡터에의 투영을 계산할 수 있다. 최종적으로 이 투영은 y 축벡터가 된다.

    FLOAT fDotProduct = DotProduct( vWorldUp, vView );

    D3DVECTOR vUp = vWorldUp - fDotProduct * vView;

주 : DotProduct 는 D3D_OVERLOADS 에 정의되는 함수이다.

다음의 코드는, y 축벡터를 정규화한다.

    vUp /= fLength;

x 축벡터를 검출하려면 , y 축 및 z 축벡터의 외적을 요구한다.

    D3DVECTOR vRight = CrossProduct( vUp, vView );

주 : CrossProduct 는 D3D_OVERLOADS 에 정의되는 함수이다.

이 시점에서, 새로운 뷰 행렬의 생성을 시작하기 위한 정보가 갖추어져 있다. 다음의 코드에서는, 최초의 3 개의 행에, 주시점을 가리키는 뷰를 회전시키기 위한 기저 벡터를 포함한다.

    mat. _11 = vRight.x;  mat. _12 = vUp.x;  mat. _13 = vView.x;  mat. _14 = 0.0f;
    mat. _21 = vRight.y;  mat. _22 = vUp.y;  mat. _23 = vView.y;  mat. _24 = 0.0f;
    mat. _31 = vRight.z;  mat. _32 = vUp.z;  mat. _33 = vView.z;  mat. _34 = 0.0f;

다음에 평행이동값을 설정한다. 다만, 시점의 주위에서 회전하는 것에 주의한다.

    mat. _41 = - DotProduct( vFrom, vRight );
    mat. _42 = - DotProduct( vFrom, vUp );
    mat. _43 = - DotProduct( vFrom, vView );
    mat. _44 = 1.0f;

평행이동값을 설정 하면, 제어가 어플리케이션 정의 함수 App_FrameMove 의 호출하러 돌아온다. IDirect3DDevice7::SetTransform 메소드를 호출해, 새로운 뷰 행렬을 유효하게 한다.

    pd3dDevice->SetTransform( D3DTRANSFORMSTATE_VIEW, &matView );

입방체의 버텍스는 프로그래머 정의 함수 TransformVertices 에 의해 트랜스 폼 된다. 이것에 대해서는, 「스텝 2.3 : 3D 트랜스 폼을 실행한다」로 설명한다.


스텝 2.4 : 신을 렌더링 한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

다음의 IDirect3DDevice7::DrawPrimitive 의 호출은,D3DVERTEX 형의 삼각형 스트립으로부터 구성되는 벽세그먼트(segment)를 그린다.

    pd3dDevice->DrawPrimitive( D3DPT_TRIANGLESTRIP, D3DFVF_VERTEX,
                               g_pvWall, NUM_WALL_VERTICES, NULL );

다음의 DrawPrimitive 의 호출은, 커스텀화한 「유연한 버텍스 포맷」을 가지는 삼각형 팬을 그린다.

    pd3dDevice->DrawPrimitive( D3DPT_TRIANGLEFAN, D3DFVF_XYZ|D3DFVF_NORMAL,
                               g_pvCone, NUM_CONE_VERTICES, NULL );

마지막으로, 다음의 IDirect3DDevice7::DrawIndexedPrimitive 호출은, 어플리케이션으로 트랜스 폼 & 라이팅이 적용되어 인덱스부를 한 버텍스로부터 구성되는 입방체를 그린다.

    pd3dDevice->DrawIndexedPrimitive( D3DPT_TRIANGLELIST, D3DFVF_TLVERTEX,
                                      g_pvCube, NUM_CUBE_VERTICES,
                                      g_pwCubeIndices, NUM_CUBE_INDICES, NULL );


스텝 1.3 : 입방체를 준비한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

입방체는, 인덱스 붙이고 된 프리미티브로서 나타내진다. 이 때문에, 입방체의 렌더링은, 버텍스의 배열을 인덱스 붙이고 하는 것으로 실행된다. 특히, 렌더링중은, 입방체의 버텍스 리스트에 인덱스를 붙이기 위해서(때문에) 다음의 인덱스가 사용된다.

    WORD* pwIndex = g_pwCubeIndices;
    *pwIndex++ = 1;  *pwIndex++ = 2;  *pwIndex++ = 3;
    *pwIndex++ = 2;  *pwIndex++ = 1;  *pwIndex++ = 0;
    *pwIndex++ = 4;  *pwIndex++ = 5;  *pwIndex++ = 6;
    *pwIndex++ = 6;  *pwIndex++ = 5;  *pwIndex++ = 7;
    *pwIndex++ = 3;  *pwIndex++ = 2;  *pwIndex++ = 6;
    *pwIndex++ = 3;  *pwIndex++ = 6;  *pwIndex++ = 7;
    *pwIndex++ = 0;  *pwIndex++ = 1;  *pwIndex++ = 4;
    *pwIndex++ = 4;  *pwIndex++ = 1;  *pwIndex++ = 5;
    *pwIndex++ = 2;  *pwIndex++ = 0;  *pwIndex++ = 4;
    *pwIndex++ = 2;  *pwIndex++ = 4;  *pwIndex++ = 6;
    *pwIndex++ = 1;  *pwIndex++ = 3;  *pwIndex++ = 5;
    *pwIndex++ = 5;  *pwIndex++ = 3;  *pwIndex++ = 7;

장면의 모든 오브젝트에 지오메트리를 정의하면(자), 다음은 장면을 렌더링 및 표시한다. 이것이, 「스텝 2 : 신을 렌더링, 표시한다」의 설명 내용이다.


스텝 3.2 : 머트리얼과 초기 라이팅 스테이트를 셋업 한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

기본적인 3D 렌더링 오브젝트 (DirectDraw 오브젝트, 렌더링 디바이스, 및 뷰포트)를 생성 하면, 단순한 장면을 렌더링 하는데 필요한 모든 것이, 거의 갖추어진 것이 된다. 다음으로 하는 것은, 머트리얼을 생성, 구성해, 초기 라이팅 스테이트를 설정하는 것이다. 설정은 모두, 필요에 따라서, 다음에 변경할 수가 있다. 개념적인 설명에 대해서는, 「라이팅과 머트리얼」을 참조할것.

샘플 Triangle 에서는, 다음과 같이 머트리얼 파라미터를 설정한다.

    D3DMATERIAL7 mtrl;
    ZeroMemory( &mtrl, sizeof(mtrl) );
    mtrl.ambient.r = 1.0f;
    mtrl.ambient.g = 1.0f;
    mtrl.ambient.b = 0.0f;
    pd3dDevice->SetMaterial( &mtrl );

위의 코드에서는,D3DMATERIAL7 구조체로 나타내는 머트리얼 프로퍼티를 준비해 있다. 또,D3DMATERIAL7 구조체에 의해, 앰비언트 라이트의 빨강 및 초록 성분을 반사하는 머트리얼을 기술하고 있다. 이것에 의해, 머트리얼은 장면 중(안)에서 황색으로 보인다 (이 튜토리얼에서는, 앰비언트 라이트만을 사용하므로, 앰비언트 반사율 프로퍼티만을 설정한다. 실제의 어플리케이션에서는, 앰비언트 라이트 뿐만이 아니라 다이렉트 라이트도 사용하므로, 디퓨즈 및 스펙큐러 반사율의 프로퍼티도 설정한다). 머트리얼 프로퍼티를 준비한 후, 이 코드에서는,IDirect3DDevice7::SetMaterial 메소드를 호출해 이 프로퍼티를 디바이스에 적용하고 있다.

주 : 텍스쳐를 사용하는 경우, 오브젝트 머트리얼은 보통 생략 될까 백색으로 된다.

현재의 머트리얼을 선택 하면, 모든 다각형이, 이 머트리얼을 사용해 렌더링 된다. 다만, 장면안의 무엇인가를 가시 상태로 하려면 , 라이팅을 줄 필요가 있다. Triangle 어플리케이션에서는, 백색 앰비언트 라이트의 D3DRENDERSTATE_AMBIENT 렌더링 스테이트를 지정한 IDirect3DDevice7::SetRenderState 메소드를 호출해, 앰비언트 라이트 레벨을 설정한다.

    // 앰비언트 라이트값은 다른 상태로 설정되어 있다. 여기에서는, 앰비언트 라이트를
    // 완전한 백색으로 설정한다.
    pd3dDevice->SetRenderState( D3DRENDERSTATE_AMBIENT, 0xffffffff );

여기서, 지오메트리, 머트리얼, 및 초기 라이팅 파라미터가 설정되었으므로, 샘플 Triangle 는, 좌표 트랜스 폼 행렬의 셋업에 진행된다. 이것에 대해서는, 「스텝 3.3 : 좌표 트랜스 폼 행렬을 준비, 설정한다」로 설명한다.


스텝 2.1 : 디바이스를 취득한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

디바이스를 테스트하려면 , 우선 테스트하는 디바이스를 취득해야 한다. 이 항에서는, 디바이스로 지원 되는 모든 디스플레이 설정으로 디바이스를 테스트할 수 있도록(듯이), 디바이스 정보를 취득하는 방법에 대해 설명한다.

 for( DWORD i=0; i<pDriverInfo->dwNumModes; i++ )
    {
        DDSURFACEDESC2 ddsdMode = pDriverInfo->ddsdModes[i];
        DWORD dwModeDepth = ddsdMode.ddpfPixelFormat.dwRGBBitCount;
        DWORD dwBitDepth  = pDeviceInfo->ddDeviceDesc.dwDeviceRenderBitDepth;
        BOOL  bCompatible = FALSE;

위의 코드에 의한 변수 할당에 의해, 디바이스의 비디오 모드 기술을 취득해, 돌려주어진 비디오 모드 기술내에서 픽셀 근처의 비트 지원을 취득해, 디바이스의 렌더링 비트 깊이를 취득한다. 이 정보는, 디바이스 능력의 테스트에 사용된다.

테스트하는 디바이스의 정보를 취득하면(자), 다음은 디바이스를 테스트한다. 이 스텝에 대해서는, 「스텝 2.2 : 디바이스를 테스트한다」로 설명한다.


스텝 2.3 : Direct3D 를 초기화한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

어플리케이션으로 장면을 렌더링 및 표시하기 위해서 필요한 표면을 생성 한 후, DirectDraw 오브젝트의 IDirect3D7 인터페이스에의 포인터를 취득해, Direct3D 오브젝트를 초기화할 수가 있다. 이 인터페이스는, 장면의 렌더링에 필요한 모든 오브젝트를 생성 하는데 사용한다. 이 인터페이스는, DirectDraw 오브젝트에 의해 개시되어 다른 오브젝트는 아니고, 다른 기능세트를 나타내는 것에 주의한다. IDirect3D7 인터페이스는, DirectDraw 오브젝트의 IUnknown::QueryInterface 메소드를 호출해 취득한다. Triangle 의 다음의 코드가, 이 태스크를 실행한다.

    // Direct3D 에 액세스 하기 위한(해), DirectDraw 에 문의한다.
    g_pDD->QueryInterface( IID_IDirect3D7, (VOID**) &g_pD3D );
    if( FAILED( hr) )
        return hr;

IDirect3D7 인터페이스에의 포인터를 취득 하면,IDirect3D7::CreateDevice 메소드를 호출해 렌더링 디바이스를 생성 할 수가 있다. CreateDevice 메소드는, 목적의 디바이스의 글로벌 유니크 식별자 (GUID), 디바이스가 렌더링 하는 표면의 IDirectDrawSurface7 인터페이스의 주소, 및 디바이스 오브젝트의 생성이 성공했을 경우에 메소드가 IDirect3DDevice7 인터페이스 포인터로 설정하는 변수의 주소를 받는다. 튜토리얼에서는, GUID 를 코드중에 기입해 사용하고 있지만, 실제의 어플리케이션에서는, 디바이스를 열거해 GUID 를 취득할 필요가 있다. 디바이스의 열거에 대해서는, 「Direct3D 디바이스의 열거」를 참조할것.

(샘플 Triangle 에서는, 디바이스의 생성전에 디스플레이 모드를 체크하고 있다. 디스플레이에 팔레트 모드가 설정되어 있는 경우, 코드는 종료한다. 관련하는 팔레트를 가지지 않는 팔레트 표면에 디바이스를 생성 하려고 하면(자),CreateDevice 메소드의 실패를 일으킨다. 이것은, 코드를 간단하게 하기 위해서 간 것이다. 실제의 어플리케이션에서는, 렌더링 타겟 표면을 생성 해, 팔레트를 Attach 하는지, 디스플레이 모드를 16 비트 컬러 이상으로 설정하도록, 유저에게 요구할까의 어느 쪽인지를 실시한다).

Triangle 로부터 발췌한 다음의 코드가, 디스플레이 모드의 체크를 실시해, 렌더링 디바이스를 생성 한다.

    // 디스플레이 모드를 체크한다.
    ddsd.dwSize = sizeof(DDSURFACEDESC2);
    g_pDD->GetDisplayMode( &ddsd );
    if( ddsd.ddpfPixelFormat.dwRGBBitCount <= 8 )
        return DDERR_INVALIDMODE;

    // 여기서의 GUID 는 코드중에 기입해지고 있다. 실제의 어플리케이션에서는
    // GUID 를 디바이스의 열거에 의해 취득할 필요가 있다.
    hr = g_pD3D->CreateDevice( IID_IDirect3DHALDevice, g_pddsBackBuffer,
                               &g_pd3dDevice );
    if( FAILED( hr ) )
    {
        // 하드웨어 GUID 가 기능하지 않는 경우에는, 소프트웨어 디바이스를 시험해 본다.
        hr = g_pD3D->CreateDevice( IID_IDirect3DRGBDevice, g_pddsBackBuffer,
                                   &g_pd3dDevice );
        if( FAILED( hr ) )
            return hr;
    }

CreateDevice 메소드는 많은 이유로부터 실패하는 일이 있다. 가장 일어나기 쉬운 원인은, 프라이머리 디스플레이 디바이스가 3D 기능을 지원 하지 않는 경우이다. 다른 가능성으로서 표시 하드웨어가, 현재의 디스플레이 모드에서는 렌더링을 할 수 없다고 하는 경우가 있다. 이러한 가능성을 디바이스 열거 시에 체크해 둘 필요가 있다. 코드를 간단하게 하기 위한(해), Triangle 에서는, 하드웨어 디바이스가 생성 할 수 없는 경우, 소프트웨어 렌더링 디바이스의 생성을 시도하기로 하고 있다.

주 : CreateDevice 메소드는 DirectDrawSurface 오브젝트에의 포인터를 받지만, 렌더링 디바이스는 표면은 아니다. 렌더링 디바이스는, 렌더링 되는 장면의 그래픽스를 포함한 표면을 사용하는, 이산형 COM 오브젝트이다.

디바이스가 생성 되면(자), 다음은 뷰포트를 생성 해 디바이스에 할당한다. 이것에 대해서는, 「스텝 2.4 : 뷰포트를 준비한다」로 설명한다.


스텝 5.3 : 디스플레이를 갱신한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

렌더링 타겟 표면에 대한 장면의 렌더링을 종료 하면, 그 결과를 화면상에 표시할 수가 있다. 윈도우 어플리케이션의 경우, 보통, 렌더링 타겟 표면의 내용을 프라이머리 표면에 블리트 하는 것으로써 표시를 실시한다. 페이지 플립핑을 채용하고 있는 풀 스크린 어플리케이션의 경우, 플립핑 체인의 표면을 플립 하는 것만으로 표시를 실시한다. 샘플 Triangle 는, 윈도우로 실행되기 (위해)때문에, 다음의 코드에 의해, 전자의 방법을 사용한다.

HRESULT ShowFrame()
{
    if( NULL == g_pddsPrimary )
        return E_FAIL;

    // 윈도우 모드이므로, 백 버퍼로부터
    // 프라이머리 표면의 정확한 위치에, 블리트를 실행한다.
    return g_pddsPrimary->Blt( &g_rcScreenRect, g_pddsBackBuffer,
                               &g_rcViewportRect, DDBLT_WAIT, NULL );
}

위의 어플리케이션 정의 함수는, 렌더링 타겟 표면의 내용 전체를, 데스크탑의 윈도우에 블리트 하는 것만으로 있는 것에 주의한다. 이 튜토리얼에서는, 블리트 대상의 직사각형을, 글로벌 변수 g_rcScreenRect 로 추적한다. 이 직사각형은, 유저가 윈도우를 이동할 때마다 갱신된다. 이것에 대해서는, 「윈도우의 이동을 처리한다」로 설명한다.


스텝 2.2 : 새로운 표면을 생성 한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

텍스쳐에 새로운 표면을 생성 하려면 ,IDirectDraw7::CreateSurface 메소드를 사용한다.

    if( FAILED( hr = pDD->CreateSurface( &ddsd, &pddsTexture, NULL ) ) )
    {
        pDD->Release();
        return NULL;
    }

CreateSurface 메소드의 제 1 파라미터는, 표면 텍스쳐 오브젝트를 기술하는 DDSURFACEDESC2 구조체이다. 호출이 종료 하면, 제 2 파라미터가 텍스쳐 표면의 IDirectDrawSurface7 인터페이스 포인터로 설정된다.

여기에서는, 텍스쳐 표면으로서 사용하는 표면을 생성 했다. 다음은, 이 텍스쳐 표면에 비트 맵을 카피한다. 이 스텝에 대해서는, 「스텝 2.3 : 렌더링 표면에 카피한다」로 설명한다.


스텝 1.3 : 텍스쳐 관리를 유효하게 한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

텍스쳐 표면 오브젝트를 생성 하는 경우는, 우선 디바이스의 텍스쳐 관리를 유효할 필요가 있다. 텍스쳐 관리 속성을 사용하는 것으로, 복잡한 텍스쳐 관리가 Direct3D 측에서 행해지게 된다.

하드웨어 디바이스의 텍스쳐 관리는, 다음의 코드로 유효하게 할 수 있다.

    if( ddDesc.deviceGUID == IID_IDirect3DHALDevice )
        ddsd.ddsCaps.dwCaps2 = DDSCAPS2_TEXTUREMANAGE;
    else if( ddDesc.deviceGUID == IID_IDirect3DTnLHalDevice )
        ddsd.ddsCaps.dwCaps2 = DDSCAPS2_TEXTUREMANAGE;
    else
        ddsd.ddsCaps.dwCaps |= DDSCAPS_SYSTEMMEMORY;

텍스쳐 관리의 상세한 것에 대하여는, 「자동 텍스쳐 관리」를 참조할것.

다음에,ddDesc (렌더링 디바이스의 기술을 포함한 D3DDEVICEDESC7 구조체)를 사용해 디바이스 능력을 조사한다. 드라이버에서의 필요에 따라서, 표면 기술의 폭과 높이를 조정한다.

    if( ddDesc.dpcTriCaps.dwTextureCaps & D3DPTEXTURECAPS_POW2 )
    {
        for( ddsd.dwWidth=1;  dwWidth>ddsd.dwWidth;   ddsd.dwWidth<<=1 );
        for( ddsd.dwHeight=1; dwHeight>ddsd.dwHeight; ddsd.dwHeight<<=1 );
    }
    if( ddDesc.dpcTriCaps.dwTextureCaps & D3DPTEXTURECAPS_SQUAREONLY )
    {
        if( ddsd.dwWidth > ddsd.dwHeight ) ddsd.dwHeight = ddsd.dwWidth;
        else                               ddsd.dwWidth  = ddsd.dwHeight;
    }

여기에서는, 텍스쳐 관리를 유효하게 해, 표면 기술과 드라이버와의 호환성을 확인했다. 다음은, 텍스쳐 포맷을 열거한다. 이 태스크에 대해서는, 「스텝 1.4 : 텍스쳐 포맷을 열거한다」로 설명한다.


스텝 1.2 : 원추를 준비한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

원추의 지오메트리의 준비에는, 위치 벡터 및 법선 벡터를 선언하는 것만으로 좋다. 이 때문에, DrawPrims 어플리케이션의 원추 오브젝트는, 다음의 프로그래머 정의 구조로 정의된다.

struct MyFlexibleVertex
{
    D3DVECTOR vPosition;
    D3DVECTOR vNormal;
};

다음의 코드로, 원추의 첨단을 정의한다.

    g_pvCone[0]. vPosition = D3DVECTOR( 0, CONE_HEIGHT/2, 0 );
    g_pvCone[0]. vNormal   = Normalize( D3DVECTOR( 0, 1, 0 ) );

다음의 삼각함수로, 원추의 각 측면을 계산한다.

    for( i=0; i<NUM_CONE_SIDES; i++ )
    {
        FLOAT x = (FLOAT) sin( 2*g_PI*i/(NUM_CONE_SIDES-1) );
        FLOAT y = -CONE_HEIGHT/2;
        FLOAT z = (FLOAT) cos( 2*g_PI*i/(NUM_CONE_SIDES-1) );
        g_pvCone[i+1]. vPosition = CONE_RADIUS * D3DVECTOR( x, y, z );

다음의 코드로, 원추의 각 측면의 위치 벡터를 계산한다.

    g_pvCone[i+1]. vNormal   = Normalize( D3DVECTOR( x, 0.5f, z ) );
    }

지오메트리 공간에 벽세그먼트(segment)와 원추를 정의하면(자), 다음은 입방체를 준비한다. 이 처리에 대해서는, 「스텝 1.3 : 입방체를 준비한다」로 설명한다.


스텝 1.4 : 텍스쳐 포맷을 열거한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

텍스쳐 포맷을 열거하는 것으로, 렌더링 디바이스로 지원 되는 텍스쳐 포맷을 어플리케이션으로 선택할 수 있게 된다. IDirect3DDevice7::EnumTextureFormats 메소드를 사용해, 지원 되는 텍스쳐 포맷의 리스트에 대해 현재의 드라이버에 문의한다.

    pd3dDevice->EnumTextureFormats( TextureSearchCallback, &ddsd.ddpfPixelFormat );

위의 함수 호출에서는,TextureSearchCallback 파라미터는, 열거 프로세스로 각 텍스쳐 포맷에 대해서 불려 가는 어플리케이션 정의 콜백 함수 D3DEnumPixelFormatsCallback 의 주소이다.

다음의 코드는 TextureSearchCallback 콜백 함수의 일부이다. 이 코드에서는, 루프 처리를 사용해, 디바이스로 지원 되는 텍스쳐 픽셀 포맷을 검색한다. 특히, 여기서 검색하는 것은 16 비트 텍스쳐이다. 알파 텍스쳐 등, 다른 포맷은 무시된다.

    if( pddpf->dwFlags & (DDPF_LUMINANCE|DDPF_BUMPLUMINANCE|DDPF_BUMPDUDV) )
        return DDENUMRET_OK;

    // 모든 FourCC 포맷을 스킵 한다.
    if( pddpf->dwFourCC ! = 0 )
        return DDENUMRET_OK;

    // 알파 모드를 스킵 한다.
    if( pddpf->dwFlags&DDPF_ALPHAPIXELS )
        return DDENUMRET_OK;

    // 검색하는 것은 16 비트 포맷이며, 그 이외의 포맷은 모두 스킵 한다.
    if( pddpf->dwRGBBitCount ! = 16 )
        return DDENUMRET_OK;

    // 일치하는 포맷이 발견되었을 경우는, 현재의 픽셀 포맷을 출력 파라미터에
    // 카피한다.
    memcpy( (DDPIXELFORMAT*) param, pddpf, sizeof(DDPIXELFORMAT) );

    // DDENUMRET_CANCEL 를 돌려주어 열거를 종료한다.
    return DDENUMRET_CANCEL;
}

여기에서는, 텍스쳐 포맷의 열거 TextureEnum 로부터, 렌더링 디바이스로 지원 되는 텍스쳐 포맷을 선택했다. 다음은, 텍스쳐에 표면을 생성 한다. 이 스텝에 대해서는, 「스텝 2 : 텍스쳐 표면을 생성 한다」로 자세하게 설명한다.


스텝 1.1 : 텍스쳐 좌표를 설정한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

Direct3D 에서는, 텍스쳐는 2 차원 배열의 컬러값으로서 나타내진다. 배열내의 각 요소는, 텍셀로서 참조된다. 텍셀은, 각각 U 및 V 와 라벨 붙이고 된 열 및 행으로 식별할 수 있다.

어플리케이션에서는, 버텍스의 텍스쳐 좌표를 기술하는 값으로 D3DVERTEX 구조체를 초기화해, 텍스쳐 좌표를 버텍스에 직접 할당한다. 다음은 Texture 어플리케이션의 코드의 일부이다. 이 코드에서는, 입방체의 전면을 기술하는 4 개의 버텍스를 생성 하고 있다.

    *pVertices++ = D3DVERTEX( D3DVECTOR(-1. 0f, 1.0f,-1. 0f), n0, 0.0f, 0.0f );
    *pVertices++ = D3DVERTEX( D3DVECTOR( 1.0f, 1.0f,-1. 0f), n0, 1.0f, 0.0f );
    *pVertices++ = D3DVERTEX( D3DVECTOR(-1. 0f,-1. 0f,-1. 0f), n0, 0.0f, 1.0f );
    *pVertices++ = D3DVERTEX( D3DVECTOR( 1.0f,-1. 0f,-1. 0f), n0, 1.0f, 1.0f );

D3DVERTEX 의 할당을 실시할 때는, 제 1 인수로 버텍스를 정의해, 제 2 인수로 버텍스의 법선 벡터 (법선의 정의에 대해서는, SDK 부속의 Texture 어플리케이션의 코드를 참조)의 방향을 정의해, 다음의 2 개의 인수로 버텍스의 텍스쳐 좌표를 나타낸다. 이 예에서는, 어플리케이션으로 입방체의 전면에 비트 맵 텍스쳐 전체를 맵 하므로, 텍스쳐 좌표는 (0, 0), (1, 0), (0, 1), (1, 1)가 된다.

텍스쳐 좌표의 상세한 것에 대하여는, 「텍스쳐 좌표」를 참조할것.

지금까지 입방체의 뒷면, 표면, 저면, 우측면, 및 좌측면에 정의했을 때와 같은 방법을 이용할 필요가 있다. 이 방법에 대해서는, SDK 부속의 Texture 어플리케이션의 코드를 참조할것.

Texture 어플리케이션은, 텍스쳐 표면 오브젝트로서 IDirectDrawSurface7 오브젝트를 돌려주는 프로그래머 정의 함수 CreateTexture 를 이행 하고 있다.

    g_pddsTexture1 = CreateTexture( pd3dDevice, "tree1.bmp" );
    g_pddsTexture2 = CreateTexture( pd3dDevice, "tex1.bmp" );
    g_pddsTexture3 = CreateTexture( pd3dDevice, "earth.bmp" );

위의 코드에서는, 파일 베이스의 비트 맵 "tree1.bmp","tex1.bmp", 및 "earth.bmp" 로부터 3 개의 텍스쳐 표면 오브젝트를 생성 하고 있다. 각각의 함수 호출에 대해, 제 1 인수 pd3dDevice 는 어플리케이션의 렌더링 디바이스에의 참조이다. 돌려주어지는 텍스쳐 표면 오브젝트 (g_pddsTexture1,g_pddsTexture2, 및 g_pddsTexture3)는, 렌더링중에 입방체 원시적으로 설정된다.

프로그래머 정의 함수 CreateTexture 를 상세하게 조사해, 텍스쳐 표면 오브젝트의 준비 방법 및 생성 방법을 확인할 수 있다. 이 태스크의 최초의 스텝에 대해서는, 「스텝 1.2 : 텍스쳐 표면을 준비한다」로 설명한다.


스텝 2.3 : 렌더링 표면에 카피한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

텍스쳐 표면에 비트 맵을 카피하려면 , 비트 맵의 디바이스 콘텍스트 (DC) 및 표면의 DC 를 생성 한다.

주 : DC 는 그래픽스 오브젝트의 속성을 저장, 취득, 및 수정하는 GDI 구조체이며, 그래픽스 모드를 지정한다. 표면의 DC 에는, 렌더링 디바이스에서의 그래픽스 표시를 제어하는 정보를 거둘 수 있다. 비트 맵의 DC 에 저장 되는 그래픽스 오브젝트는, 카피용의 비트 맵이다.

비트 맵의 DC 는, 다음의 코드로 취득할 수 있다.

    HDC hdcBitmap = CreateCompatibleDC( NULL );
    if( NULL == hdcBitmap )
    {
        pddsTexture->Release();
        return NULL;
    }
    SelectObject( hdcBitmap, hbm );

CreateCompatibleDC 함수는, 지정된 디바이스 (어플리케이션의 현재의 스크린 설정)와의 호환성을 가지는 메모리 DC 를 생성 하는 GDI 함수이다. 상세한 것에 대하여는, 「플랫폼 SDK」를 참조할것.

다음에, 표면의 DC 를 취득한다.

    HDC hdcTexture;
    if( SUCCEEDED( pddsTexture->GetDC( &hdcTexture ) ) )
    {

위의 코드에서는,IDirectDrawSurface7::GetDC 메소드가 표면의 DC 를 돌려준다.

다음의 코드로, 비트 맵 화면을 표면에 카피한다.

        BitBlt( hdcTexture, 0, 0, bm.bmWidth, bm.bmHeight, hdcBitmap,
                0, 0, SRCCOPY );
        pddsTexture->ReleaseDC( hdcTexture );
    }
    DeleteDC( hdcBitmap );

    // 새롭고 생성 된 텍스쳐를 돌려준다.
    return pddsTexture;
}

BitBlt 함수는, 지정된 전송원 DC (hdcBitmap)로부터 목적지 DC (hdcTexture)에 색데이터의 비트 블리트를 실시하는 그래픽스 디바이스 인터페이스 (GDI) 함수이다. 상세한 것에 대하여는, 「플랫폼 SDK」를 참조할것.

여기에서는, 텍스쳐에 새로운 표면을 생성 했다. 다음은, 이 텍스쳐를 사용해 프리미티브의 렌더링을 실행한다. 이 태스크에 대해서는, 「스텝 3 : 텍스쳐 프리미티브의 렌더링」으로 설명한다.


스텝 1.2 : 텍스쳐 표면을 준비한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

일반적으로, 실제의 텍스쳐 표면을 준비하는 경우는, 우선 비트 맵의 핸들을 생성 해, 그 핸들에 텍스쳐 표면을 로드할 필요가 있다. 다만, 비트 맵의 핸들을 생성 하는 경우는, 어플리케이션이 비트 맵 파일 ("tree1.bmp","tex1.bmp", 및 "earth.bmp")을 확실히 검출할 수 없으면 안 된다. 최초의 스텝으로서 비트 맵 파일의 실행 가능 파일의 리소스를 체크한다.

    HBITMAP hbm = (HBITMAP) LoadImage( GetModuleHandle(NULL), strName,
                              IMAGE_BITMAP, 0, 0,
                              LR_CREATEDIBSECTION);

위의 LoadImage 함수의 호출에서는, 최초의 인수는 호출해 프로세스를 생성하기 위한 파일의 핸들, 즉 실행 가능 파일의 리소스이다. 이 최초의 파라미터에 의해, 로드하는 화면을 저장 하는 모듈의 인스턴스에의 핸들을 돌려줄 수가 있다. 제 2 파라미터는, 로드하는 비트 맵 화면을 특정한다. 제 3, 제 4, 및 제 5 파라미터는, 비트 맵 타입의 로드, 및 비트 맵 화면의 실제의 폭과 높이를 지정한다. 마지막 인수는 로드 플래그이다. 이것에 의해, 디스플레이 디바이스의 컬러에 맵핑 하지 않고 비트 맵을 로드한다.

LoadImage 의 상세한 것에 대하여는, 「플랫폼 SDK」를 참조할것.

Texture 어플리케이션에서는, 호출 프로세스의 생성에 사용되는 파일에의 핸들을 사용해 파일을 검출할 수 없었던 경우, 비트 맵 화면을 파일로서 로드하려고 한다. 다만, 실제의 어플리케이션에서는, 복수의 파일 패스를 검색해 비트 맵을 찾으려고 한다.

      hbm = (HBITMAP) LoadImage( NULL, strName, IMAGE_BITMAP, 0, 0,
                                LR_LOADFROMFILE|LR_CREATEDIBSECTION );

위의 LoadImage 함수의 호출에서는, 화면을 저장 하는 인스턴스의 핸들이 지정되어 있지 않지만, LR_LOADFROMFILE 로드 플래그를 설정하는 것으로,strName 파라미터가 비트 맵 화면을 저장 하는 파일명인 것을 나타내고 있다.

텍스쳐를 준비 및 생성 하는 태스크는, 다음의 프로그래머 정의 함수 CreateTextureFromBitmap 를 호출해 실시한다. 이 함수에는, 렌더링 디바이스에의 참조, 및 텍스쳐로서 사용하는 비트 맵에의 핸들을 건네준다.

    return CreateTextureFromBitmap( pd3dDevice, hbm );

CreateTextureFromBitmap 는 디바이스 능력을 취득한다. 이것에 의해, 디바이스에 텍스쳐의 사용에 관한 제약이 있을지 어떨지를 조사할 수가 있다.

    D3DDEVICEDESC7 ddDesc;
    ddDesc.dwSize = sizeof(D3DDEVICEDESC7);
    if( FAILED( pd3dDevice->GetCaps( &ddDesc ) ) )
        return NULL;

위의 코드에서는,D3DDEVICEDESC7 구조체의 ddDesc 가 초기화된다. 다음에,IDirect3DDevice7::GetCaps 메소드를 사용해 렌더링 디바이스의 기술을 취득한다.

다음에,GetObject 함수를 사용해, 텍스쳐로서 사용하는 비트 맵을 취득한다. 이것에 의해, 비트 맵 그래픽스 오브젝트의 폭과 높이를 취득할 수 있게 된다.

    BITMAP bm;
    GetObject( hbm, sizeof(BITMAP), &bm );
    DWORD dwWidth  = (DWORD) bm.bmWidth;
    DWORD dwHeight = (DWORD) bm.bmHeight;

BITMAP 구조체는, 비트 맵을 정의하는 GDI 구조체이다. 상세한 것에 대하여는, 「플랫폼 SDK」를 참조할것.

GetObject 함수는, 지정된 그래픽스 오브젝트에 관한 정보를 취득하는 GDI 함수이다. 상세한 것에 대하여는, 「플랫폼 SDK」를 참조할것.

텍스쳐 표면의 기술에는 DDSURFACEDESC2 구조체를 사용한다. 이 시점에서, 텍스쳐에 새로운 표면 기술을 설정할 수 있다.

    DDSURFACEDESC2 ddsd;
    ZeroMemory( &ddsd, sizeof(DDSURFACEDESC2) );
    ddsd.dwSize          = sizeof(DDSURFACEDESC2);
    ddsd.dwFlags         = DDSD_CAPS|DDSD_HEIGHT|DDSD_WIDTH|
                           DDSD_PIXELFORMAT|DDSD_TEXTURESTAGE;
    ddsd.ddsCaps.dwCaps  = DDSCAPS_TEXTURE;
    ddsd.dwWidth         = dwWidth;
    ddsd.dwHeight        = dwHeight;

특히 제어 플래그 DDSCAPS_TEXTURE 를 설정하는 것으로, 표면에 의해 텍스쳐 표면을 기술하는 것을 시스템에 알린다. 다음은, 자동 텍스쳐 관리를 유효하게 한다. 이 스텝에 대해서는, 「스텝 1.3 : 텍스쳐 관리를 유효하게 한다」로 설명한다.


스텝 2.3 : 3D 트랜스 폼을 실행한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

장면은 거의 완성하고 있지만, 입방체의 버텍스를 수동으로 회전, 평행이동, 및 스케일링 하는 처리가 남아 있다. 우선,D3DTLVERTEX 구조체의 배열 g_pvCube 에 입방체의 트랜스폼 되지 않은 데이터를 저장 한다. 최초의 3 개의 파라미터는, 화면 좌표의 각 버텍스의 트랜스폼 되지 않은의 위치 좌표를 나타내고 있다.

    g_pvCube[0] = D3DTLVERTEX( D3DVECTOR(-1,-1,-1 ), 0, 0xffffffff, 0, 0, 0 );
    g_pvCube[1] = D3DTLVERTEX( D3DVECTOR( 1,-1,-1 ), 0, 0xff00ffff, 0, 0, 0 );
    g_pvCube[2] = D3DTLVERTEX( D3DVECTOR(-1, 1,-1 ), 0, 0xffff00ff, 0, 0, 0 );
    g_pvCube[3] = D3DTLVERTEX( D3DVECTOR( 1, 1,-1 ), 0, 0xff0000ff, 0, 0, 0 );
    g_pvCube[4] = D3DTLVERTEX( D3DVECTOR(-1,-1, 1 ), 0, 0xffffff00, 0, 0, 0 );
    g_pvCube[5] = D3DTLVERTEX( D3DVECTOR( 1,-1, 1 ), 0, 0xff00ff00, 0, 0, 0 );
    g_pvCube[6] = D3DTLVERTEX( D3DVECTOR(-1, 1, 1 ), 0, 0xffff0000, 0, 0, 0 );
    g_pvCube[7] = D3DTLVERTEX( D3DVECTOR( 1, 1, 1 ), 0, 0xff000000, 0, 0, 0 );

다음에, 프로그래머 정의 함수 TransformVertices 를 호출해, 입방체의 8 개의 버텍스를 수동으로 트랜스 폼 한다.

    TransformVertices( pd3dDevice, g_pvCube, 8 );

다만, 3D 트랜스 폼을 이행 하기 전에, 뷰포트의 높이와 폭을 취득할 필요가 있다. 이 정보는, 렌더링 윈도우에 맞추어 트랜스 폼이 끝난 버텍스를 스케일링 하기 위해서 사용된다.

HRESULT TransformVertices( LPDIRECT3DDEVICE7 pd3dDevice,
                           D3DTLVERTEX* pvVertices, DWORD dwNumVertices )
{
    // 뷰포트의 폭과 높이를 취득한다. 이 정보는, 렌더링 윈도우에 맞추어
    // 트랜스 폼이 끝난 버텍스를 스케일링 하는데 필요하다.
    D3DVIEWPORT7 vp;
    pd3dDevice->GetViewport( &vp );
    DWORD dwClipWidth  = vp.dwWidth/2;
    DWORD dwClipHeight = vp.dwHeight/2;

Direct3D 하행열을 사용해 트랜스 폼을 실시한다. 3D 트랜스 폼을 실행하려면 , 현재의 행렬 세트의 값을 취득할 필요가 있다. 이 때문에는, 렌더링 디바이스로 IDirect3DDevice7::GetTransform 를 호출한다.

    D3DMATRIX matWorld, matView, matProj;
    pd3dDevice->GetTransform( D3DTRANSFORMSTATE_WORLD,      &matWorld );
    pd3dDevice->GetTransform( D3DTRANSFORMSTATE_VIEW,       &matView );
    pd3dDevice->GetTransform( D3DTRANSFORMSTATE_PROJECTION, &matProj );

행렬 연결에는 행렬 곱셈을 사용한다.

    D3DMATRIX matTemp = matWorld * matView;
    D3DMATRIX matSet = matTemp * matProj;

위의 코드에서는, 트랜스 폼의 연결값이 합성 행렬 matSet, 로부터 산출된다. 연결 시에는, 처리를 실시하는 순서로 행렬이 곱셈되고 있는 것을 확인한다.

행렬 연결의 상세한 것에 대하여는, 「행렬 연결」을 참조할것.

다음에, 현재의 행렬 세트를 사용해 각 버텍스를 트랜스 폼 한다.

    for( DWORD i=0; i<dwNumVertices; i++ )
    {
        // 트랜스폼 되지 않은의 버텍스의 위치를 취득한다.
        FLOAT x = pvVertices[i]. sx;
        FLOAT y = pvVertices[i]. sy;
        FLOAT z = pvVertices[i]. sz;

        // 현재의 행렬 세트로 트랜스 폼 한다.
        FLOAT xp = matSet. _11*x + matSet. _21*y + matSet. _31*z + matSet. _41;
        FLOAT yp = matSet. _12*x + matSet. _22*y + matSet. _32*z + matSet. _42;
        FLOAT zp = matSet. _13*x + matSet. _23*y + matSet. _33*z + matSet. _43;
        FLOAT wp = matSet. _14*x + matSet. _24*y + matSet. _34*z + matSet. _44;

마지막으로, 화면 좌표에 맞추어 버텍스를 스케일링 한다. 다음의 코드에서는, 우선 각 좌표가 wp 값으로 나눗셈 되어, 좌표가 3D 공간에서 2D 디바이스 좌표에 평면화된다. 그 다음에, x 및 y 성분이 디바이스 좌표로부터 화면 좌표에 변환된다.

        pvVertices[i]. sx  = ( 1.0f + (xp/wp) ) * dwClipWidth;
        pvVertices[i]. sy  = ( 1.0f - (yp/wp) ) * dwClipHeight;
        pvVertices[i]. sz  = zp / wp;
        pvVertices[i]. rhw = wp;
    }

3D 트랜스 폼의 상세한 것에 대하여는, 「3D 트랜스 폼」을 참조할것.

주 : 뷰포트로 디바이스 좌표가 취하는 범위는,-1 으로부터 +1 의 사이의 값이다. 또, sz 좌표가 Z 버퍼로 사용된다.

이것으로 입방체의 8 개의 버텍스를 트랜스 폼 할 수 있었다. 다음은, 완성한 장면의 프레임을 렌더링 한다. 이것에 대해서는, 「스텝 2.4 : 신을 렌더링 한다」로 설명한다.


스텝 3.3 : 좌표 트랜스 폼 행렬을 준비, 설정한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

단순한 장면을 셋업 하는 이제(벌써) 1 개의 스텝은, 월드 행렬, 뷰 행렬, 및 투영 행렬의 설정에 관계하는 것이다. 시스템에 의해 이러한 행렬이 지오메트리에 적용되는 것으로, 그 지오메트리가 장면에 배치되어 카메라의 위치와 방향이 조정되어 멀리 있는 오브젝트가 근처에 있는 오브젝트보다 작게 보이도록(듯이) 버텍스 데이터가 스케일링 된다. (개요에 대해서는, 「지오메트리 파이프라인」을 참조할것).

샘플 Triangle 에서는, 우선,D3DMATRIX 구조체로 단위행렬을 생성 한 후, 행렬을 조작해, 목적의 좌표 트랜스 폼을 생성한다. 행렬을 준비한 후, 이 코드에서는, D3DTRANSFORMSTATE_WORLD, D3DTRANSFORMSTATE_VIEW, 또는 D3DTRANSFORMSTATE_PROJECTION 값을 지정해 IDirect3DDevice7::SetTransform 메소드를 호출해, 행렬을 디바이스에 할당한다.

    // 우선, 단위행렬을 셋업 한다.
    D3DMATRIX mat;
    mat. _11 = mat. _22 = mat. _33 = mat. _44 = 1.0f;
    mat. _12 = mat. _13 = mat. _14 = mat. _41 = 0.0f;
    mat. _21 = mat. _23 = mat. _24 = mat. _42 = 0.0f;
    mat. _31 = mat. _32 = mat. _34 = mat. _43 = 0.0f;

    // 월드 행렬은, 월드 공간에 있는 다각형의
    // 위치와 방향을 제어한다. 다음에 이것을 사용해
    // 삼각형을 회전한다.
    D3DMATRIX matWorld = mat;
    pd3dDevice->SetTransform( D3DTRANSFORMSTATE_WORLD, &matWorld );

    // 뷰 행렬은,
    // 카메라의 위치와 방향을 정의한다. 여기에서는, 카메라를 z 축으로 따라 10 단위 뒤로
    // 움직이는 것만으로 있다.
    D3DMATRIX matView = mat;
    matView. _43 = 10.0f;
    pd3dDevice->SetTransform( D3DTRANSFORMSTATE_VIEW, &matView );

    // 투영 행렬은, 2D 렌더링 타겟 표면상에,
    // 3D 신을 어떻게 「투영」하는지를 정의한다.
    // 상세한 것에 대하여는, 「투영 트랜스 폼이란」을 참조할것.

    // x 와 y 를 2 배가 되어, z 를 -1. 0 만 평행이동 하는,
    // 매우 단순한 투영 행렬을 셋업 한다.
    D3DMATRIX matProj = mat;
    matProj. _11 =  2.0f;
    matProj. _22 =  2.0f;
    matProj. _34 =  1.0f;
    matProj. _43 = -1. 0f;
    matProj. _44 =  0.0f;
    pd3dDevice->SetTransform( D3DTRANSFORMSTATE_PROJECTION, &matProj );

좌표 트랜스 폼을 설정 하면, Triangle 는, 장면의 셋업을 종료한 것이 된다. 어플리케이션 정의 함수 App_InitDeviceObjects 가, 호출측의 어플리케이션 정의 함수 Initialize3DEnvironment 에 S_OK 를 돌려준다. 게다가 Initialize3DEnvironment 함수가 이 값을 WinMain 에 돌려준다. 이것에 의해,WinMain 는 「스텝 4 : 시스템 메세지를 감시한다」로 설명하는 시스템 메세지의 처리로 옮긴다.


스텝 5.1 : 신을 갱신한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

샘플 Triangle 의 어플리케이션 정의 함수 Render3DEnvironment 는, 불려 가자마자, App_FrameMove (다른 어플리케이션 정의 함수)를 호출한다. App_FrameMove 함수는,fTimeKey 파라미터에 의해 함수에게 건네진 내부 카운트값에 근거해, y 축을 중심으로 하는 회전을 반영시키기 (위해)때문에, Direct3D 가 지오메트리에 적용하는 월드 행렬을 갱신하는 것만으로 있다. 회전은, 1 프레임에 대해 한 번만 적용되기 (위해)때문에, 결과적으로, 모델이 소정의 위치에서 회전하고 있는 것처럼 보인다.

HRESULT App_FrameMove( LPDIRECT3DDEVICE7 pd3dDevice, FLOAT fTimeKey )
{
    // 이 단순한 튜토리얼에서는, 삼각형을 y 축을 중심으로서 회전시킨다.
    // 그 때문에(위해)는, 새로운 월드 좌표 트랜스 폼으로서 회전을 결정하는 4×4 행렬을 설정하는 것만으로 있다.
    D3DMATRIX matSpin;
    matSpin. _11 = matSpin. _22 = matSpin. _33 = matSpin. _44 = 1.0f;
    matSpin. _12 = matSpin. _13 = matSpin. _14 = matSpin. _41 = 0.0f;
    matSpin. _21 = matSpin. _23 = matSpin. _24 = matSpin. _42 = 0.0f;
    matSpin. _31 = matSpin. _32 = matSpin. _34 = matSpin. _43 = 0.0f;

    matSpin. _11 = (FLOAT) cos( fTimeKey );
    matSpin. _33 = (FLOAT) cos( fTimeKey );
    matSpin. _13 = -(FLOAT) sin( fTimeKey );
    matSpin. _31 = (FLOAT) sin( fTimeKey );

    pd3dDevice->SetTransform( D3DTRANSFORMSTATE_WORLD, &matSpin );

    return S_OK;
}

물론, 실제의 어플리케이션에서는, 단일의 모델에 대해서 회전을 적용하는 것 외에도 다수의 처리를 실시한다. (회전 행렬의 상세한 것에 대하여는, 「3D 트랜스 폼」의 「회전」을 참조할것).

장면의 지오메트리를 갱신하면(자), 다음은 그 지오메트리를 렌더링 타겟 표면에 렌더링 한다. 샘플 Triangle 에서는, 이 처리를 「스텝 5.2 : 신을 렌더링 한다」로 실시한다.


스텝 2.1 : 렌더링 타겟을 취득한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

여기에서는, 디바이스의 렌더링 타겟을 취득할 필요가 있다. 이것에 의해, 그 렌더링 타겟을 사용해 DirectDraw 오브젝트에의 포인터를 취득할 수 있게 된다. 다음에, DirectDraw 인터페이스를 취득해야 한다. 이것에 의해, 표면을 생성 할 수 있게 된다.

    LPDIRECTDRAWSURFACE7 pddsRender;
    LPDIRECTDRAW7        pDD;
    pd3dDevice->GetRenderTarget( &pddsRender );
    pddsRender->GetDDInterface( (VOID**) &pDD );
    pddsRender->Release();

위의 코드에서는,IDirect3DDevice7::GetRenderTarget 메소드를 사용해, 렌더링 타겟으로서 사용하는 DirectDraw 표면에의 포인터를 취득하고 있다. 다음에,IDirectDrawSurface7::GetDDInterface 메소드를 사용해, 렌더링 타겟 표면의 생성에 사용한 DirectDraw 오브젝트에의 인터페이스를 취득하고 있다.

렌더링 타겟 및 DirectDraw 인터페이스에의 포인터를 취득하면(자), 다음은 텍스쳐에 표면을 생성 한다. 이 태스크에 대해서는, 「스텝 2.2 : 새로운 표면을 생성 한다」로 설명한다.


스텝 2.2 : DirectDraw 표면을 셋업 한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

DirectDraw 오브젝트를 생성 해, 그 협조 레벨을 설정 하면, 어플리케이션이 장면의 렌더링, 표시에 사용하는 표면을 생성 할 수 있다. 표면의 생성 방법은, 어플리케이션이 윈도우내 또는 풀 스크린 모드의 어디에서 실행될까에 의해, 거의 결정된다.

풀 스크린 어플리케이션에 대해 : 풀 스크린 모드로 실행하는 어플리케이션에서는, 위의 코드로 가리키도록(듯이) 해 표면을 생성 할 수 있다. 풀 스크린 어플리케이션에서는, 풀 스크린 배타 모드에 한해서 사용할 수 있는 기능인 페이지 플립핑을 이용하는 것이 빈번하게 행해지고 있다. 이 경우, 2 개의 표면을 명시적으로 생성 하는 것이 아니라, 단일의 호출로, 표면의 플립핑 체인을 생성 할 수가 있다. 상세한 것에 대하여는, 「복합 표면과 플립핑 체인의 생성」을 참조할것.

샘플 Triangle 는, 윈도우내에서 실행되도록(듯이) 설계되고 있어 디스플레이를 나타내는 프라이머리 표면의 생성으로부터 시작된다.

    DDSURFACEDESC2 ddsd;
    ZeroMemory( &ddsd, sizeof(DDSURFACEDESC2) );
    ddsd.dwSize         = sizeof(DDSURFACEDESC2);
    ddsd.dwFlags        = DDSD_CAPS;
    ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE;

    // 프라이머리 표면을 생성 한다.
    hr = g_pDD->CreateSurface( &ddsd, &g_pddsPrimary, NULL );
    if( FAILED( hr ) )
        return hr;

프라이머리 표면 기술에는, 치수나 픽셀 포맷의 정보는 포함되지 않는다. 이러한 특징은, 디스플레이 모드와 같다라고 보여지고 있기 때문이다. 현재의 디스플레이 모드가, 800×600 의 16 비트 컬러이면, DirectDraw 는, 프라이머리 표면도 같은 것을 보증한다. 프라이머리 표면을 생성 하면, 렌더링 타겟의 표면을 생성 하는 것이 가능하게 된다. Triangle 의 경우, 이것은 다음과 같이 해 생성 되는, 다른 오프 스크린 표면이 된다.

    ddsd.dwFlags        = DDSD_WIDTH | DDSD_HEIGHT | DDSD_CAPS;
    ddsd.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN | DDSCAPS_3DDEVICE;

    // 백 버퍼의 사이즈를 설정한다.
    // 윈도우의 사이즈가 바뀌는 경우는, 이 표면을 파기해, 새로운 표면을 생성 할 필요가 있다.
    GetClientRect( hWnd, &g_rcScreenRect );
    GetClientRect( hWnd, &g_rcViewportRect );
    ClientToScreen( hWnd, (POINT*) &g_rcScreenRect.left );
    ClientToScreen( hWnd, (POINT*) &g_rcScreenRect.right );
    ddsd.dwWidth  = g_rcScreenRect.right - g_rcScreenRect.left;
    ddsd.dwHeight = g_rcScreenRect.bottom - g_rcScreenRect.top;

    // 백 버퍼를 생성 한다.
    // 가장 가능성이 있는 에러 원인은, 비디오 메모리의 부족하다 (세련된 어플리케이션이라면, 이 에러에 대처해야 하는 것이다).
    hr = g_pDD->CreateSurface( &ddsd, &g_pddsBackBuffer, NULL );
    if( FAILED( hr ) )
        return hr;

위의 코드는, 프로그램 윈도우의 사이즈와 동일한 오프 스크린 표면을 생성 한다. 유저에게로의 표시 범위는 윈도우의 사이즈에 의해 정해지기 (위해)때문에, 이 사이즈보다 큰 표면을 생성 할 필요는 없다. (이 코드에서는, 다음에 뷰포트의 설정 및 어플리케이션 윈도우의 사이즈와 위치의 추적에 사용하는 2 개의 글로벌 변수도 초기화한다). 위의 코드가 가리키도록(듯이), 렌더링 타겟으로서 사용하는 표면에는, DDSCAPS_3DDEVICE 능력을 지정할 필요가 있다. 이 능력에 의해, 시스템은, 3D 렌더링에만 사용되는 추가의 내부 데이터 구조체를 할당한다. 프라이머리 표면을 생성 하는 경우와 같게, 오프 스크린 표면의 픽셀 포맷은, 표면 기술로 지정되어 있지 않으면, 디스플레이 모드로 같은으로 여겨진다.

주 : 깊이 버퍼를 사용하는 어플리케이션에서는, 이 시점에서, 1 개의 깊이 버퍼를 생성 해, 렌더링 타겟 표면에 Attach 할 필요가 있다. 이 튜토리얼에서는 복잡하게 되는 것을 피해 깊이 버퍼를 사용하고 있지 않지만, 「튜토리얼 2 : 깊이 버퍼를 추가한다」 및 「깊이 버퍼」에서는 사용한다.

렌더링 타겟의 프라이머리 표면을 생성 하면, DirectDrawClipper 오브젝트를 생성 해 표시 표면에 Attach 하는 것이 가능하게 된다. 클립퍼를 사용 하면, 윈도우가 부분적으로 다른 윈도우에 의해 숨겨졌을 경우나, 윈도우가 부분적으로 표시 영역을 넘었을 경우의 처리를 하지 않아도 된다. 클립퍼는, 풀 스크린 모드로 실행되는 어플리케이션에는 필요없다. 샘플 Triangle 는, 다음의 코드를 사용해 클립퍼를 생성 해, 표시 윈도우에 결합하고 있다.

    LPDIRECTDRAWCLIPPER pcClipper;
    hr = g_pDD->CreateClipper( 0, &pcClipper, NULL );
    if( FAILED( hr ) )
        return hr;

    // 윈도우 핸들에 클립퍼를 할당한 후,
    // 클립퍼를 목적의 표면으로 설정한다.
    pcClipper->SetHWnd( 0, hWnd );
    g_pddsPrimary->SetClipper( pcClipper );
    pcClipper->Release();

기본적인 DirectDraw 오브젝트의 생성을 종료 하면, 장면을 렌더링 하는 Direct3D 주요 오브젝트의 생성에 진행될 수가 있다. 샘플 Triangle 에서는, 이 태스크를 「스텝 2.3 : Direct3D 를 초기화한다」로 실시한다.


스텝 5.2 : 신을 렌더링 한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

목적의 움직임을 반영하도록(듯이) 지오메트리의 갱신을 종료 하면, 장면의 렌더링을 실시할 수가 있다. 샘플 Triangle 에서는, 전형적인 방법을 채용하고 있다. 샘플의 Render3DEnvironment 함수로부터 불려 가는 어플리케이션 정의 함수 App_Render 는, 우선, 뷰포트를 클리어 한다.

HRESULT App_Render( LPDIRECT3DDEVICE7 pd3dDevice, D3DRECT* prcViewRect )
{
    // 뷰포트를 청색에 클리어 한다.
    pd3dDevice->Clear( 1UL, prcViewRect, D3DCLEAR_TARGET, 0x000000ff,
                       0L, 0L );

위의 코드에서는,IDirect3DDevice7::Clear 메소드를 호출해 뷰포트를 클리어 하고 있다. Clear 메소드가 받는 최초의 2 개의 인수는, 렌더링 타겟 표면 위에의 클리어 대상 영역을 기술하는 직사각형의 배열의 주소, 및 그 배열로부터 클리어 하는 직사각형의 개수를 메소드에 알리는 값이다. 보통, 렌더링 타겟 전체를 가리는 1 개의 직사각형을 사용한다. 3 번째의 파라미터는, 메소드의 동작을 결정한다. 렌더링 타겟 표면, 관련 깊이 버퍼, 스텐실 버퍼, 또는 이 3 개의 임의의 편성을 클리어 할 수가 있다. 이 튜토리얼에서는, 깊이 버퍼를 사용하지 않기 때문에, D3DCLEAR_TARGET 이외의 플래그는 사용하지 않는다. 마지막 3 개의 파라미터는, 렌더링 타겟, 깊이 버퍼, 스텐실 버퍼의 클리어값을 반영하도록(듯이) 설정한다. 샘플 Triangle 에서는, 렌더링 타겟 표면의 클리어 컬러를 파랑으로 설정해 있다. 나머지의 파라미터는, 이 튜토리얼에서는 사용하지 않기 때문에, 코드에서는 제로를 설정해 있다. Clear 메소드는, 대응하는 플래그가 존재하지 않는 경우는 파라미터를 무시한다.

뷰포트를 클리어 한 후, 샘플 Triangle 는 다음에 나타내도록(듯이), 렌더링의 시작을 Direct3D 에 알려 장면을 렌더링 해, 렌더링의 종료를 알린다.

    // 장면을 시작 한다.
    if( FAILED( pd3dDevice->BeginScene() ) )
        return E_FAIL;

    // DrawPrimitive() 콜을 사용해, 삼각형을 드로잉(Drawing) 한다.
    // 튜토리얼에서는, 이후 다각형을 드로잉(Drawing) 하는 다양한 호출을
    // 자세하게 소개해 나간다.
    pd3dDevice->DrawPrimitive( D3DPT_TRIANGLELIST, D3DFVF_VERTEX,
                               g_pvTriangleVertices, 6, NULL );

    // 장면을 종료한다.
    pd3dDevice->EndScene();

    return S_OK;
}

IDirect3DDevice7::BeginScene 및 IDirect3DDevice7::EndScene 메소드는, 렌더링의 시작시 및 종료시를 각각 시스템에 알린다. 렌더링 메소드는, 이 2 개의 메소드의 호출동안에서 밖에 호출할 수가 없다. 렌더링 메소드가 정상적으로 종료하지 않았던 경우에서도,BeginScene 를 재차 호출하기 전에,EndScene 를 호출할 필요가 있다.

장면을 오프 스크린 렌더링 타겟으로 렌더링 하면, 유저의 디스플레이를 갱신하는 것이 가능하게 된다. 튜토리얼의 샘플에서는, 이 처리를 「스텝 5.3 : 디스플레이를 갱신한다」로 실시한다.


스텝 2.2 : 디바이스를 테스트한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

다음의 코드는, 모든 8 비트 모드를 스킵 하면서, 디스플레이 모드의 디바이스와의 호환성을 체크한다.

        if( (32==dwModeDepth) && (dwBitDepth&DDBD_32) ) bCompatible = TRUE;
        if( (24==dwModeDepth) && (dwBitDepth&DDBD_24) ) bCompatible = TRUE;
        if( (16==dwModeDepth) && (dwBitDepth&DDBD_16) ) bCompatible = TRUE;

특히 위의 코드에서는, 지정된 디바이스의 비디오 모드가, 열거된 디바이스의 렌더링 깊이와 호환성을 가질지 어떨지를 체크한다.

디바이스에 호환성이 있으면, 그 디바이스는 받아들일 수 있어 디바이스로 지원 되는 디스플레이 모드의 배열에 카피된다.

       if( bCompatible )
            pDeviceInfo->ddsdModes[pDeviceInfo->dwNumModes++] = ddsdMode;
    }

이 루프가 종료해 모든 디바이스가 열거되면(자), 디스플레이 모드의 배열 ddsdModes 는 지정 조건을 채우는 디스플레이 모드의 리스트를 저장 해, 그 외의 디스플레이 모드는 무시된다.


스텝 1.1 : 드라이버 정보를 열거한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

Enumeration 어플리케이션에서는, 다음의 어플리케이션 정의 콜백 함수를 사용해, 시스템에 인스톨 떠날 수 있어 모든 DirectDraw 디바이스를 열거한다.

static BOOL WINAPI DriverEnumCallback( GUID* pGUID, LPSTR strDesc,
                                       LPSTR strName, VOID*, HMONITOR )

제 1 파라미터 pGUID 는, DirectDraw 오브젝트에 고유의 식별자의 주소이다. 다음의 2 개의 파라미터는, 드라이버의 설명 및 이름을 기술하는 캐릭터 라인이다. 이 함수의 상세한 것에 대하여는, SDK 레퍼런스의 「DDEnumCallbackEx 」의 항목을 참조할것.

드라이버 정보를 열거하기 전에, 디스플레이 드라이버를 생성 할 필요가 있다. 어플리케이션 정의 콜백 함수 DriverEnumCallback 에게 건네지는 글로벌 유니크 식별자 (GUID)를 사용해, 어플리케이션의 디스플레이 드라이버를 생성 한다.

hr = DirectDrawCreateEx( pGUID, (VOID**) &pDD, IID_IDirectDraw7, NULL );

인수 NULL 는, 액티브한 디스플레이 드라이버의 사용을 지정한다. 이 시점에서, Enumeration 어플리케이션에는, 모든 Direct3D 디바이스의 열거에 사용되는 IDirect3D7 오브젝트가 생성 된다.

드라이버 데이터를 D3DDEVICEINFO 구조체에 카피할 수 있다. 이것에 의해, 드라이버 정보가 유저의 어플리케이션 정의 콜백 함수에게 건네진다.

    // 데이터를 데이터 정보 구조체에 카피한다.
    ZeroMemory( &d3dDeviceInfo, sizeof(D3DDEVICEINFO) );
    strncpy( d3dDeviceInfo.strDesc, strDesc, 39 );
    d3dDeviceInfo.ddDriverCaps.dwSize = sizeof(DDCAPS);
    d3dDeviceInfo.ddHELCaps.dwSize    = sizeof(DDCAPS);
    pDD->GetCaps( &d3dDeviceInfo.ddDriverCaps, &d3dDeviceInfo.ddHELCaps );
    d3dDeviceInfo.pDriverGUID = pGUID;

다음의 샘플 코드를 조사해,D3DDEVICEINFO 구조체의 ddsdModes 멤버가, 특정의 디바이스로 지원 되는 디스플레이 모드를 기술 (리스트)하는 DDSURFACEDESC2 형의 배열인 것에 주목한다. 최종적으로는, combobox를 유저에게 표시해, 현재의 디스플레이 모드 (윈도우)의 리스트에 이어, 디바이스로 지원 되는 풀 스크린 디스플레이 모드의 리스트를 표시할 수 있다.

주 : 이 튜토리얼에서는, Enumeration 어플리케이션의 그래피컬 유저 인터페이스 (GUI)의 설계 및 구조에 대해서는 접하지 않는다. 상세한 것에 대하여는, SDK 의 코드를 참조할것.

다음의 샘플 코드에서는, 현재의 디스플레이 모드 설정의 디스플레이 모드에 관한 정보를 취득한다.

    if( ( NULL == d3dDeviceInfo.pDriverGUID ) &&
        ( d3dDeviceInfo.ddDriverCaps.dwCaps2 & DDCAPS2_CANRENDERWINDOWED ) )
    {
        // 현재의 디스플레이 깊이를 취득한다.
        DEVMODE devmode;
        devmode.dmSize = sizeof(DEVMODE);
        EnumDisplaySettings( NULL, ENUM_CURRENT_SETTINGS, &devmode );

        // 모드 정보를 설정한다.
        DDSURFACEDESC2* pMode = &d3dDeviceInfo.ddsdModes[0];
        pMode->ddpfPixelFormat.dwRGBBitCount = devmode.dmBitsPerPel;
        pMode->dwWidth  = 0;
        pMode->dwHeight = 0;

        d3dDeviceInfo.dwNumModes = 1;
    }

위의 샘플 코드는,ddsdModes 배열의 요소에 현재의 디스플레이 설정을 저장 하는 방법을 나타내고 있다. ddsdModes 배열의 나머지의 요소에 값이 저장 되는 것은, 각 디바이스에 풀 스크린 디스플레이 모드가 열거되어 선택된 다음에 있다. EnumDisplaySettings 메소드는, 현재의 디스플레이 깊이에 관한 정보의 취득에 사용되는 것에 주의한다. 깊이 설정은 DEVMODE 구조체에 보존된 후,ddsdModes 배열의 최초의 요소인 ddpfPixelFormat.dwRGBBitCount 멤버에 카피된다.

        pMode->ddpfPixelFormat.dwRGBBitCount = devmode.dmBitsPerPel;

여기에서는, 시스템의 DirectDraw 드라이버를 열거해, 현재의 디스플레이 설정을 보존했다. 다음은, 디스플레이 모드를 열거한다.

디스플레이 모드의 열거에 대해서는, 「스텝 1.2 : 디스플레이 모드 정보를 열거한다」로 자세하게 설명한다.


스텝 2.1 : DirectDraw 를 초기화한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

어플리케이션 윈도우의 생성 후, 최초로 생성 하는 오브젝트는, DirectDraw 오브젝트이다. 이것은, 어플리케이션의 협조 레벨을 설정하는 경우나, 표시나 렌더링 디바이스의 렌더링 타겟으로서 사용하는 표면을 생성 하는 경우에 필요하다.

샘플 Triangle 는, 다음의 코드에 나타내도록(듯이), DirectDraw 오브젝트를 생성 해, 어플리케이션의 협조 레벨을 설정해, 초기화의 실행을 시작 한다.

HRESULT Initialize3DEnvironment( HWND hWnd )
{
    HRESULT hr;

    hr = DirectDrawCreateEx( NULL, (VOID**) &g_pDD, IID_IDirectDraw7, NULL );
    if( FAILED( hr ) )
        return hr;

위의 코드에서는, DirectDraw 글로벌 함수 DirectDrawCreateEx 를 호출해 DirectDraw 오브젝트를 생성 하고 있다. 최초의 파라미터로서 NULL 를 건네주어, DirectDraw 오브젝트를 액티브한 디스플레이 드라이버용으로 생성 하도록(듯이) 함수에 요구한다. 3D 전용 하드웨어한 어느, GDI 를 지원 하지 않는 하드웨어에 대해서는, 최초의 파라미터에, 적절한 드라이버의 글로벌 유니크 식별자 (GUID)를 명시적으로 지정할 필요가 있다. GUID 는 보통, 열거형으로부터 취득한다. 2 번째의 파라미터는 글로벌 변수의 주소로,DirectDrawCreateEx 가 DirectDraw 오브젝트에 대한 IDirectDraw7 인터페이스의 주소를 설정한다. 마지막 파라미터에는 NULL 를 설정해, 새로운 오브젝트가 COM 집약 기능으로 사용되지 않는 것을 나타낸다.

샘플 코드는, 계속해, 다음과 같이 해 어플리케이션의 협조 레벨을 설정한다.

    hr = g_pDD->SetCooperativeLevel( hWnd, DDSCL_NORMAL );
    if( FAILED( hr ) )
        return hr;

샘플에서는,IDirectDraw7::SetCooperativeLevel 메소드를 호출해 협조 레벨을 설정해 있다. 협조 레벨을 설정하는 것으로, 어플리케이션으로 렌더링을 풀 스크린 모드 또는 윈도우의 어디에서 실행할지가 시스템에 통지된다. (하드웨어에 따라서는 윈도우에 렌더링 할 수 없는 경우가 있다. 그러한 하드웨어는,IDirectDraw7::GetCaps 를 호출해 체크해 보면, DDCAPS2_CANRENDERWINDOWED 능력 플래그가 설정되어 있지 않다). 이 코드에서는,SetCooperativeLevel 에게 건네지는 DDSCL_NORMAL 플래그를 제 2 파라미터로 설정해,"표준" 협조 레벨이라고도 불리는 윈도우 협조 레벨을 요구하고 있다. SetCooperativeLevel 메소드는, 다른 어플리케이션이 배타 모드로 풀 스크린을 이미 제어하고 있는 경우에는 실패하는 일이 있다.

주 : DDSCL_FPUSETUP 협조 레벨 플래그를 지정 하면, 퍼포먼스가 향상한다. 이 협조 플래그 레벨의 상세한 것에 대하여는, 「DirectDraw 협조 레벨과 FPU 정밀도」를 참조할것. 일반적인 설명에 대해서는, DirectDraw 의 「협조 레벨」을 참조할것.

DirectDraw 오브젝트를 생성 해, 협조 레벨을 설정 하면, 렌더링 되는 장면을 포함해, 표시에 사용하는 표면의 준비가 가능한 상태가 된다. 샘플 Triangle 에서는, 이 태스크를 「스텝 2.2 : DirectDraw 표면을 셋업 한다」로 설명하는 방법에 따라 실시한다.


스텝 1.1 : 벽세그먼트(segment)를 준비한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

튜토리얼 「다양한 프리미티브 스타일을 사용한다」에서는, 「트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스」인 D3DVERTEX 구조체를 사용해 장면의 벽세그먼트(segment)를 기술한다. 「트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스」를 사용 하면, Direct3D 로 독자적인 내부 알고리즘에 의해 트랜스 폼 & 라이팅 처리를 실행하도록(듯이) 요구할 수 있다.

3D 공간에서 각 벽세그먼트(segment)를 정의하려면 , 다음의 DrawPrims 어플리케이션의 코드로 가리키도록(듯이), 1 조의 버텍스 정보를 계산해 결과를 보존한다.

HRESULT App_InitDeviceObjects( LPDIRECT3DDEVICE7 pd3dDevice )
{
    DWORD i;

    for( i=0; i<NUM_WALL_SIDES; i++ )
    {
        FLOAT x = (FLOAT) sin( 2*g_PI*i/(NUM_WALL_SIDES-1) );
        FLOAT z = (FLOAT) cos( 2*g_PI*i/(NUM_WALL_SIDES-1) );

        g_pvWall[2*i+0] = D3DVERTEX( 10.0f * D3DVECTOR( x, -0. 1f, z ),
                          D3DVECTOR( -x, 0, -z ), 0, 0 );
        g_pvWall[2*i+1] = D3DVERTEX( 10.0f * D3DVECTOR( x, 0.1f, z ),
                          D3DVECTOR( -x, 0, -z ), 0, 0 );

    }

위의 코드에서는,D3DVERTEX 구조체의 배열 g_pvWall 에 버텍스 성분 데이터를 저장 하고 있다. 또, 삼각함수를 사용해 버텍스의 x 좌표 및 z 좌표를 결정하고 있다. D3DVERTEX 구조체에서는,모델 좌표에 좌표를 지정할 필요가 있다. 「트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스」를 사용하고 있기 (위해)때문에, 모델 좌표에는 월드 트랜스 폼, 뷰 트랜스 폼, 및 투영 트랜스 폼이 적용되어 장면내에 적절히 배치된다. 또, 버텍스의 x, y, 및 z 좌표를 10 두개스케일링 해 벽세그먼트(segment)를 적절한 사이즈로 설정한다.

장면의 벽세그먼트(segment)에 지오메트리를 정의한 후, 다른 지오메트리 원시적인 원추를 준비한다. 이 경우도, 특정의 오브젝트의 정의 순서는 중요하지 않다.

3D 공간에서의 원추의 정의에 대해서는, 「스텝 1.2 : 원추를 준비한다」로 설명한다.


스텝 3.1 : 지오메트리를 준비한다

[Visual Basic]

여기에서는, C 및 C++ 에서의 어플리케이션 카이하츠에 도착해 설명한다. Visual Basic 에 대해서는, 「Direct3D 직접 모드 Visual Basic 튜토리얼」을 참조할것.

[C++]

DirectDraw 와 Direct3D 로 사용하는 프라이머리 시스템 오브젝트를 생성 하면, 장면의 초기화를 시작 할 수 있다. 샘플 Triangle 에서는, 동시에,D3DVERTEX 구조체의 배열로 버텍스를 정의해, 지오메트리의 초기화도 가고 있다. 기술적으로는, 이 시점에서 지오메트리의 셋업을 실시할 필요는 없다.

HRESULT App_InitDeviceObjects( LPDIRECT3DDEVICE7 pd3dDevice )
{
    // 삼각형의 지오메트리의 데이터. 이 튜토리얼에서는,
    // 앰비언트 라이트만을 사용하고 있으므로, 버텍스의 법선은, 실제로는 사용되지 않는 것에 주의한다.
    D3DVECTOR p1( 0.0f, 3.0f, 0.0f );
    D3DVECTOR p2( 3.0f,-3. 0f, 0.0f );
    D3DVECTOR p3(-3. 0f,-3. 0f, 0.0f );
    D3DVECTOR vNormal( 0.0f, 0.0f, 1.0f );

    // 삼각형의 전면의 3 버텍스를 초기화한다.
    g_pvTriangleVertices[0] = D3DVERTEX( p1, vNormal, 0, 0 );
    g_pvTriangleVertices[1] = D3DVERTEX( p2, vNormal, 0, 0 );
    g_pvTriangleVertices[2] = D3DVERTEX( p3, vNormal, 0, 0 );

    // 삼각형의 뒷면의 3 버텍스를 초기화한다.
    g_pvTriangleVertices[3] = D3DVERTEX( p1, -vNormal, 0, 0 );
    g_pvTriangleVertices[4] = D3DVERTEX( p3, -vNormal, 0, 0 );
    g_pvTriangleVertices[5] = D3DVERTEX( p2, -vNormal, 0, 0 );

위의 부분 코드에서는, z=0 의 평면상에 직립 하는 삼각형을 정의하는, 3D 공간의 3 점을 정의하고 있다. 표시하는 지오메트리를 정의한 후, 샘플 Triangle 에서는 머트리얼 및 라이팅 파라미터를 준비한다. 이것에 대해서는, 「스텝 3.2 : 머트리얼과 초기 라이팅 스테이트를 셋업 한다」로 설명한다.


스텝 1.1 : 텍스쳐 좌표를 설정한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

Direct3D 에서는, 텍스쳐를 컬러값의 2 차원 배열로 나타낸다. 배열의 각 요소를텍셀이라고 부른다. 텍셀에는, 열번호와 행 번호에 의해 액세스 할 수 있다. 이러한 번호에는, 각각 U 와 V 의 라벨이 붙어 있다.

어플리케이션으로 텍스쳐 좌표를 직접 버텍스에 할당하려면 ,DirectX7.CreateD3DVertex 메소드를 사용한다. 샘플 Texture 의 다음의 코드에서는, 입방체의 전면을 나타내는 4 버텍스를 생성 한다.

g_dx.CreateD3DVertex -1, 1, -1, 0, 0, -1, 0, 0, vertices(0)
g_dx.CreateD3DVertex 1, 1, -1, 0, 0, -1, 1, 0, vertices(1)
g_dx.CreateD3DVertex -1, -1, -1, 0, 0, -1, 0, 1, vertices(2)
g_dx.CreateD3DVertex 1, -1, -1, 0, 0, -1, 1, 1, vertices(3)

CreateD3DVertex 메소드를 호출할 때 마다, 최초의 3 개의 인수가 버텍스를, 다음의 3 개의 인수가 버텍스 법선 벡터의 방향을 정의한다. 이 경우, 어플리케이션에 의해 비트 맵 텍스쳐 전체를 입방체의 전면에 맵 해, 다음의 텍스쳐 좌표, (0, 0), (1, 0), (0, 1), 및 (1, 1)을 사용한다.

텍스쳐 좌표의 상세한 것에 대하여는, 「텍스쳐 좌표」를 참조할것.

입방체의 뒷면, 표면, 저면, 우면, 및 좌면에도, 같은 순서를 실행할 필요가 있다. 이 순서에 대해서는, SDK 의 샘플 Texture 코드를 참조할것.

샘플 Texture 에서는, 프로그래머 정의 함수 CreateTextureSurface 를 사용해 DirectDrawSurface7 오브젝트를 돌려준다. 돌려주어진 텍스쳐 표면 오브젝트는, 렌더링시에 원시적으로 설정된다.

Set g_ddsTexture1 = CreateTextureSurface("tree1.bmp")
Set g_ddsTexture2 = CreateTextureSurface("tex1.bmp")
Set g_ddsTexture3 = CreateTextureSurface("earth.bmp")

위의 코드에서는, 비트 맵 파일 (tree1.bmp, tex1.bmp, 및 earth.bmp)로부터 3 개의 텍스쳐 표면 오브젝트가 생성 되고 있다.

주 : 샘플 Texture 를 실행하려면 , Visual Basic 어플리케이션이 텍스쳐 파일 (tree1.bmp, tex1.bmp, 및 earth.bmp)을 검색할 수 있도록(듯이) 해 두지 않으면 안 된다. 샘플 Texture 에서는, 샘플 Texture 의 프로젝트 파일 (. vbp)가 등록된 폴더로 이러한 파일을 검색한다.

이것으로, 프로그래머 정의 서브 루틴 CreateTextureSurface 의 설명은 종료해, 텍스쳐 표면 오브젝트의 준비와 생성에 진행된다. 이 태스크의 최초의 스텝이,스텝 1.2 : 텍스쳐 표면을 준비한다」이다.


스텝 3.3 : 지오메트리를 준비한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

샘플 Triangle 에서는, 삼각형을 정의하는 3 개의 버텍스와 3D 공간에서의 버텍스 법선을 정의하는 1 개의 점의 벡터형, 합계 4 개의 D3DVECTOR 형을 정의하는 것으로써, 어플리케이션 정의 서브 루틴 InitGeometry 로 지오메트리를 초기화한다. 기술적으로는, 이 시점에서 지오메트리의 셋업을 실시할 필요는 없다. 지오메트리의 셋업은, 렌더링 메소드를 호출하기 전에 수시 실행할 수 있다.

Private Sub InitGeometry()

'삼각형의 지오메트리를 셋업 한다.
Dim p1 As D3DVECTOR, _
p2 As D3DVECTOR, _
p3 As D3DVECTOR, _
vNormal As D3DVECTOR

'삼각형을 정의하는 3 버텍스의 값을 설정한다.
p1.x = 0#:p1.y = 5#:p1.z = 0#
p2.x = 5#:p2.y = -5#:p2.z = 0#
p3.x = -5#:p3.y = -5#:p3.z = 0#

'삼각형의 버텍스로써 공유되는 버텍스 법선 벡터를 생성 한다.
'이 벡터는 시점의 방향을 가리킨다. 이 튜토리얼에서는,
'삼각형의 뒷면을 정의하는 버텍스 법선의 z 좌표가
'반전되고 있으므로 주의한다.
vNormal.x = 0#:vNormal.y = 0#:vNormal.z = -1#

DirectX7.CreateD3DVertex 메소드에서는,D3DVECTOR 형의 멤버를 사용해, 각 버텍스 성분을 나타내는 값을 D3DVERTEX 형에 묻는다. 글로벌 D3DVERTEX 형 배열 g_TriangleVert 에는, 삼각형의 버텍스 정보를 묻는다.

'삼각형의 전면의 3 버텍스를 생성 한다.
g_dx.CreateD3DVertex p1.x, p1.y, p1.z, vNormal.x, vNormal.y, vNormal.z, 0, 0, _
g_TriangleVert(0)
g_dx.CreateD3DVertex p2.x, p2.y, p2.z, vNormal.x, vNormal.y, vNormal.z, 0, 0, _
g_TriangleVert(1)
g_dx.CreateD3DVertex p3.x, p3.y, p3.z, vNormal.x, vNormal.y, vNormal.z, 0, 0, _
g_TriangleVert(2)

'삼각형의 뒷면에 대해서 같은 처리를 실행한다.
g_dx.CreateD3DVertex p3.x, p3.y, p3.z, vNormal.x, vNormal.y, -vNormal.z, 0, 0, _
g_TriangleVert(3)
g_dx.CreateD3DVertex p2.x, p2.y, p2.z, vNormal.x, vNormal.y, -vNormal.z, 0, 0, _
g_TriangleVert(4)
g_dx.CreateD3DVertex p1.x, p1.y, p1.z, vNormal.x, vNormal.y, -vNormal.z, 0, 0, _
g_TriangleVert(5)

위의 부분 코드에서는, z=0 의 평면상에 직립 하는 삼각형을 정의하는, 3D 공간의 3점을 정의하고 있다. Direct3D 관련의 오브젝트를 모두 생성 해, 장면을 초기화해, 장면의 지오메트리를 정의하면(자), 「스텝 4 : 렌더링 루프를 실행한다」에 나타내는 순서로 장면을 렌더링 할 수 있다.


스텝 2.3 : 신을 렌더링 한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

다음의 Direct3DDevice7.DrawPrimitive 호출에 의해,D3DVERTEX 형 삼각형 스트립으로 구성되는 벽세그먼트(segment)를 드로잉(Drawing) 한다.

Call g_d3dDevice.DrawPrimitive(D3DPT_TRIANGLESTRIP, D3DFVF_VERTEX, g_vWall(0), _
NUM_WALL_VERTICES, D3DDP_DEFAULT)

다음의 DrawPrimitive 호출에 의해, 커스텀화한 「유연한 버텍스 포맷」의 삼각형 팬으로 원추를 드로잉(Drawing) 한다.

Call g_d3dDevice.DrawPrimitive(D3DPT_TRIANGLEFAN, D3DFVF_XYZ Or D3DFVF_NORMAL, g_vCone(0), _
NUM_CONE_VERTICES, D3DDP_DEFAULT)

마지막으로, 다음의 Direct3DDevice7.DrawIndexedPrimitive 호출에 의해, 어플리케이션으로 트랜스 폼 & 라이팅, 및 인덱스를 붙일 수 있었던 버텍스로부터 완성되는 입방체를 드로잉(Drawing) 한다.

Call g_d3dDevice.DrawIndexedPrimitive(D3DPT_TRIANGLELIST, D3DFVF_TLVERTEX, g_vCube(0), _
NUM_CUBE_VERTICES, g_nCubeIndices, NUM_CUBE_INDICES, D3DDP_DEFAULT)


스텝 2.3 : Direct3D 를 초기화한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

어플리케이션이 장면의 렌더링과 표시에 필요로 하는 표면을 생성 하면, 오브젝트를 생성 해, Direct3D 오브젝트의 초기화를 시작 할 수가 있다. 이 오브젝트는, 장면의 렌더링에 필요한 모든 오브젝트를 생성 하기 위해서 사용한다. Direct3D7 오브젝트는,DirectDraw7.GetDirect3D 를 호출해 생성 한다. 샘플 Triangle 의 다음의 코드가, 이 태스크를 실행한다.

Sub InitD3D()
Dim d3d As Direct3D7
Dim ddsd As DDSURFACEDESC2

' DirectDraw7 오브젝트로부터
' Direct3D7 클래스에의 참조를 취득한다.
Set d3d = g_dd.GetDirect3D

Direct3D7 오브젝트를 생성 하면(자), 렌더링 디바이스를 생성 해,Direct3D7.CreateDevice 메소드를 호출할 필요가 있다. CreateDevice 메소드는, 목적의 디바이스의 글로벌 유니크 식별자 (GUID)와 디바이스가 렌더링 하는 DirectDrawSurface7 오브젝트,g_ddsBackBuffer 를 받는다. 이 표면은, DDSCAPS_3DDEVICE 능력을 사용해 3D 디바이스로서 생성 해야 한다.

튜토리얼에서는, GUID 를 코드중에 기입해 사용하고 있지만, 실제의 어플리케이션에서는, 디바이스를 열거해 GUID 를 취득할 필요가 있다. 디바이스의 열거에 대해서는, 「Direct3D 디바이스의 열거」를 참조할것.

(샘플 Triangle 에서는, 디바이스의 생성전에 디스플레이 모드를 체크하고 있다. 디스플레이가 팔레트 모드로 설정되어 있는 경우, 코드는 종료한다. 관련하는 팔레트를 가지지 않는 팔레트 표면을 생성 하려고 하면(자),CreateDevice 메소드의 실패를 일으키기 때문이다. 이것은, 코드를 간단하게 슬슬 유익이며, 실제의 어플리케이션에서는, 렌더링 타겟 표면을 생성 해, 팔레트를 Attach 하는지, 디스플레이 모드를 16 비트 컬러 이상으로 설정하도록(듯이) 유저에게 요구할 필요가 있다).

샘플 Triangle 의 다음의 코드에 의해, 디스플레이 모드를 체크한다.

g_dd.GetDisplayMode ddsd

If ddsd.ddpfPixelFormat.lRGBBitCount <= 8 Then
MsgBox "이 어플리케이션에서는," & _
"16 비트 미만의 스크린 디스플레이 모드를 지원 하고 있지 않다. "
End
End If

샘플 Triangle 에서는 다음에 렌더링 디바이스를 생성 한다.

Set g_d3dDevice = d3d.CreateDevice("IID_IDirect3DHALDevice", g_ddsBackBuffer)

Direct3D7.CreateDevice 의 호출이 실패하는 원인은 다양하다. 가장 자주(잘) 볼 수 있는 원인은, 프라이머리 디스플레이 디바이스가 3D 기능을 지원 하지 않는 경우이다. 다른 가능성으로서 표시 하드웨어가, 현재의 디스플레이 모드에서는 렌더링을 할 수 없다고 하는 경우가 있다. 이러한 가능성을 디바이스 열거 시에 체크해 둘 필요가 있다. 코드를 간단하게 하기 위한(해), 샘플 Triangle 에서는, 하드웨어 디바이스가 생성 할 수 없는 경우, 소프트웨어 렌더링 디바이스의 생성을 시도하기로 하고 있다.

주 : CreateDevice 메소드는 DirectDrawSurface7 오브젝트를 받아들이지만, DirectDraw 표면 오브젝트와는 다른 디바이스 오브젝트를 생성 한다. 디바이스는, 렌더링 타겟으로서 DirectDraw 표면을 사용한다.

디바이스를 생성 하면, 「스텝 2.4 : 뷰포트를 준비한다」로 설명하도록(듯이), 뷰포트 오브젝트를 생성 해, 디바이스에 할당할 수가 있게 된다.


스텝 1.2 : 텍스쳐 표면을 준비한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

DDSURFACEDESC2 형을 사용해, 텍스쳐 표면을 기술할 수가 있다.

Public Function CreateTextureSurface(sFile As String) As DirectDrawSurface7
Dim ddsTexture As DirectDrawSurface7
Dim i As Long
Dim bIsFound As Boolean

'텍스쳐 표면을 준비한다.
Dim ddsd As DDSURFACEDESC2

ddsd.lFlags = DDSD_CAPS Or DDSD_HEIGHT Or DDSD_WIDTH Or DDSD_PIXELFORMAT Or DDSD_TEXTURESTAGE

이것으로, 텍스쳐 표면을 준비할 수 있었으므로, 텍스쳐 포맷을 열거할 수가 있다. 이것에 대해서는, 「스텝 1.3 : 텍스쳐 포맷을 열거한다」로 설명한다.


스텝 4.3 : 디스플레이를 갱신한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

렌더링 타겟 표면에 대한 장면의 렌더링을 종료 하면, 그 결과를 화면상에 표시할 수가 있다. 윈도우 어플리케이션의 경우, 보통, 렌더링 타겟 표면의 내용을 프라이머리 표면에 블리트 하는 것으로써 표시를 실시한다. 페이지 플립핑을 사용하는 풀 스크린 어플리케이션의 경우, 플립핑 체인의 표면을 플립 하는 것만으로 표시를 실시한다. 샘플 Triangle 는, 윈도우로 실행되기 (위해)때문에, 다음의 코드에 의해, 전자의 방법을 사용한다.

g_dx.GetWindowRect Me.hWnd, g_rcDest

j = g_ddsPrimary.Blt(g_rcDest, g_ddsBackBuffer, g_rcSrc, DDBLT_WAIT)

위의 메소드는, 렌더링 타겟 표면의 내용 전체를, 데스크탑의 윈도우에 블리트 하는 것만으로 있다. 이 튜토리얼에서는, 블리트 대상의 직사각형을, 글로벌 변수 g_rcDest 로 추적한다.

어플리케이션의 실행중, 주기적으로 제어를 operating system로 이행할 필요가 있다. 이것에 대해서는, 「스텝 4.4 : DoEvents 를 호출한다」로 설명한다.


스텝 4.2 : 신을 렌더링 한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

목적의 움직임을 반영하도록(듯이) 모델의 지오메트리를 갱신 하면, 장면의 렌더링을 실시할 수가 있다. 샘플 Triangle 에서는, 전형적인 방법을 채용하고 있다. 어플리케이션 정의 서브 루틴 RenderScene 는, 우선, 뷰포트를 클리어 한다.

Private Sub RenderScene()
'뷰포트를 청색에 클리어 한다.
g_d3dDevice.Clear 1, g_d3drcViewport(), D3DCLEAR_TARGET, &HFF, 0, 0

위의 코드에서는,Direct3DDevice7.Clear 메소드를 호출해, 뷰포트를 클리어 하고 있다. Clear 메소드가 받아들이는 최초의 2 개의 인수는, 렌더링 타겟 표면 위에의 클리어 대상 영역을 기술하는 직사각형의 배열, 및, 그 배열로부터 몇개의 직사각형을 클리어 할까를 메소드에 통지하는 값이다. 보통, 샘플 Triangle 로 가고 있도록(듯이), 렌더링 타겟 전체를 가리는 1 개의 직사각형을 사용한다. 3 번째의 인수는, 메소드의 동작을 결정한다. Clear 에 의해, 렌더링 타겟 표면, 관련 깊이 버퍼, 스텐실 버퍼, 혹은 이 3 개의 임의의 편성을 클리어 할 수가 있다. 이 튜토리얼에서는, 깊이 버퍼를 사용하지 않기 때문에, D3DCLEAR_TARGET 이외의 플래그는 사용하지 않는다. 마지막 3 개의 파라미터는, 렌더링 타겟, 깊이 버퍼, 스텐실 버퍼의 클리어값을 반영하도록(듯이) 설정한다. 샘플 Triangle 에서는, 렌더링 타겟 표면의 클리어 컬러를 파랑으로 설정해 있다. 나머지의 파라미터는, 이 튜토리얼에서는 사용하지 않기 때문에, 코드에서는 제로로 설정해 있다. Clear 메소드는, 대응하는 플래그가 지정되어 있지 않은 경우, 인수를 무시한다.

뷰포트를 클리어 한 후, 샘플 Triangle 는 다음에 나타내도록(듯이), 렌더링의 시작을 Direct3D 에 알려 장면을 렌더링 해, 렌더링의 종료를 알린다.

'장면을 시작 해, 삼각형을 렌더링 해, 장면을 종료한다.
g_d3dDevice.BeginScene
Call g_d3dDevice.DrawPrimitive(D3DPT_TRIANGLELIST, D3DFVF_VERTEX, _
g_TriangleVert(0), 6, D3DDP_DEFAULT)
g_d3dDevice.EndScene

Direct3DDevice7.BeginScene 및 Direct3DDevice7.EndScene 메소드는, 각각, 렌더링이 시작되는 것, 또는 종료한 것을 시스템에 통지한다. 렌더링 메소드는, 이 2 개의 메소드의 호출동안에서 밖에 호출할 수가 없다. 렌더링 메소드가 정상적으로 종료하지 않았던 경우에서도,BeginScene 를 재차 호출하기 전에,EndScene 를 호출할 필요가 있다.

장면을 오프 스크린 렌더링 타겟으로 렌더링 하면, 유저의 디스플레이를 갱신하는 것이 가능하게 된다. 샘플 Triangle 에서는, 이것을 「스텝 4.3 : 디스플레이를 갱신한다」로 실행하고 있다.


스텝 4.4 : DoEvents 를 호출한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

DoEvents 함수를 사용 하면, 어플리케이션에 적용하는 이벤트를 operating system를 기동할 수 있다. 이 경우, operating system가 큐에 들어가 있는 이벤트를 처리한 다음에, 어플리케이션이 장면의 각 프레임을 렌더링 한다. 샘플 Triangle 에서는, 다음의 코드를 사용해 이벤트 큐를 클리어 한다.

DoEvents

이 호출이 완료하면(자), 어플리케이션은 루프의 최초로 돌아와, 어플리케이션 정의 서브 루틴 RenderScene 와 FrameMove 를 호출해, 단일 프레임의 장면을 렌더링 한다.

이것으로, 어플리케이션의 실행이 완료했으므로, 이 튜토리얼의 마지막 스텝, 「스텝 5 : 슛다운을 실시한다」에 진행된다.


스텝 1.3 : 디바이스 정보를 열거한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

디바이스의 열거를 시작 하기 전에, 현재의 디스플레이 디바이스에 대한 Direct3D 오브젝트를 취득할 필요가 있다.

Set g_d3d = g_dd.GetDirect3D()

여기서,Direct3D7.GetDevicesEnum 메소드를 호출하는 것으로,Direct3DEnumDevices 클래스에의 참조를 취득한다.

Set g_d3dEnumDevices = g_d3d.GetDevicesEnum()
For i = 1 To g_d3dEnumDevices.GetCount()
cmbDevice.AddItem g_d3dEnumDevices.GetName(i)
Next

위의 코드에서는, 열거된 각 디바이스를 나타내는 알기 쉬운 이름을, combobox cmbDevice 에 넣는다. Direct3DEnumDevices 클래스에의 참조를 취득하면(자), 열거된 디바이스의 수와 각 디바이스에 관한 정보를 돌려주는 메소드를 호출할 수가 있다.

Direct3DEnumDevices.GetCount 메소드를 호출하면, 열거된 디바이스의 수가 돌려주어진다. 최초의 디바이스는 인덱스 1 이며, 0 은 아니기 때문에 주의한다.

Direct3DEnumDevices.GetGuid 메소드를 호출하면, 열거된 디바이스의 글로벌 유니크 식별자 (GUID)를 나타내는 캐릭터 라인이 돌려주어진다.

Direct3DEnumDevices.GetName 및 Direct3DEnumDevices.GetDescription 메소드를 호출하면, 디바이스의 이름과 유저가 입력한 설명을 포함한 캐릭터 라인이 돌려주어진다.

Direct3DEnumDevices.GetDesc 메소드를 호출하면, 디바이스의 능력의 기술이,D3DDEVICEDESC7 형으로 돌려주어진다.

디스플레이 드라이버, 디스플레이 모드, 및 디바이스를 열거하면(자), 어플리케이션으로 사용하는 디바이스를 선택할 수가 있다. 이것이, 「스텝 2 : 열거된 디바이스의 선택」의 설명 내용이다.


스텝 2.1 : 신을 갱신한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

이 튜토리얼에서는, 어플리케이션 정의 서브 루틴 FrameMove 를 사용해, 엔을 중심으로 시점을 회전한다. 보통, 다음의 코드에 나타내도록(듯이), 시점은 3 개의 D3DVECTOR 형, 시점, 주시점, 및 정방향을 정의하는 벡터에 의해 정의된다.

Dim vEyePt As D3DVECTOR, _
vLookatPt As D3DVECTOR, _
vUpVec As D3DVECTOR

vEyePt = MakeVector(5 * Sin(stepVal), 3, 5 * Cos(stepVal))
vLookatPt = MakeVector(4 * Sin(stepVal + 0.1), 2.5, 4 * Cos(stepVal + 0.1))
vUpVec = MakeVector(0, 1, 0)

여기서, 3 개의 벡터를 사용해, 새로운 뷰 행렬을 생성 해 설정할 수가 있다.

Dim matView As D3DMATRIX

Call g_dx.ViewMatrix(matView, vEyePt, vLookatPt, vUpVec, stepVal / 360)

g_d3dDevice.SetTransform D3DTRANSFORMSTATE_VIEW, matView

위의 코드에서는, 새로운 카메라 위치를 DirectX7.ViewMatrix 메소드에 건네주는 것에 의해, 렌더링 된 장면의 프레임 마다 새로운 뷰 행렬을 생성 한다. 다음에,Direct3DDevice7.SetTransform 메소드가, 디바이스에 새롭게 생성된 뷰 행렬을 설정한다. stepValue 의 값 (어플리케이션 정의 메소드 FrameMove 에게 건네진 값)에 의해, 시점을 1 번씩 회전한다. 이것에 의해, 벽세그먼트(segment)와 원추가 360 번 회전한 것처럼 보인다.

이것으로, 장면은 거의 완성이지만, 게다가 입방체의 버텍스를 수동으로 회전, 평행이동, 스케일 할 필요가 있다. 최초로,DirectX7.CreateD3DTLVertex 메소드를 사용해,D3DTLVERTEX 형에 입방체의 트랜스폼 되지 않은 데이터를 묻는다. DirectX7.CreateD3DTLVertex 의 최초의 3 개의 파라미터는, 각 버텍스의 트랜스폼 되지 않은 위치 좌표를 화면 좌표로 나타낸다.

g_dx.CreateD3DTLVertex -1, -1, -1, 0, &HFFFFFF, 0, 0, 0, g_vCube(0)
g_dx.CreateD3DTLVertex 1, -1, -1, 0, &HFF&, 0, 0, 0, g_vCube(1)
g_dx.CreateD3DTLVertex -1, 1, -1, 0, &HFF00&, 0, 0, 0, g_vCube(2)
g_dx.CreateD3DTLVertex 1, 1, -1, 0, &HFF0000, 0, 0, 0, g_vCube(3)
g_dx.CreateD3DTLVertex -1, -1, 1, 0, &HFFFF&, 0, 0, 0, g_vCube(4)
g_dx.CreateD3DTLVertex 1, -1, 1, 0, &HFF0066, 0, 0, 0, g_vCube(5)
g_dx.CreateD3DTLVertex -1, 1, 1, 0, &H9966FF, 0, 0, 0, g_vCube(6)
g_dx.CreateD3DTLVertex 1, 1, 1, 0, &HFF00FF, 0, 0, 0, g_vCube(7)

여기서, 입방체의 8 개의 버텍스를 트랜스 폼 할 수 있다.

Call TransformVertices(g_d3dDevice, g_vCube, NUM_CUBE_VERTICES)

입방체의 버텍스는, 어플리케이션 정의 함수 TransformVertices 에 의해 트랜스 폼 된다. 이 트랜스 폼에 대해서는, 「스텝 2.2 : 3D 트랜스 폼을 실행한다」로 설명한다.


스텝 1.4 : 텍스쳐에 신규 표면을 생성 한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

텍스쳐 표면 오브젝트를 생성 하기 전에, DDSCAPS2_TEXTUREMANAGE 플래그를 사용해 디바이스의 텍스쳐 관리를 온으로 할 필요가 있다.

ddsd.ddsCaps.lCaps = DDSCAPS_TEXTURE
ddsd.ddsCaps.lCaps2 = DDSCAPS2_TEXTUREMANAGE
ddsd.lTextureStage = 0

또, 제어 플래그 DDSCAPS_TEXTURE 를 세트 해, 텍스쳐 표면인 것을 시스템에 통지한다.

텍스쳐의 관리에 대해서는, 「자동 텍스쳐 관리」를 참조할것.

이것으로, 자동 텍스쳐 관리가 유효하게 되어, DDSCAPS_TEXTURE 플래그가 세트 되었으므로, 텍스쳐에 새로운 표면을 생성 해, 그 텍스쳐를 돌려줄 수가 있다.

Set ddsTexture = g_dd.CreateSurfaceFromFile(sFile, ddsd)

'새롭고 생성 된 텍스쳐를 돌려준다.
Set CreateTextureSurface = ddsTexture

텍스쳐 표면에 대해서는, 「텍스쳐 표면 오브젝트」를 참조할것.

이것으로, 텍스쳐에 새로운 표면을 생성 했으므로, 프리미티브의 렌더링시에 그 텍스쳐를 사용할 수가 있다. 이 처리를, 「스텝 2 : 텍스쳐를 적용한 프리미티브를 렌더링 한다」로 실행한다.


스텝 2.1 : DirectDraw 를 초기화한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

어플리케이션 윈도우의 생성 후, 최초로 생성 하는 오브젝트는, DirectDraw 오브젝트이다. 이것은, 어플리케이션의 협조 레벨의 설정에 필요하다. 또, 이 DirectDraw 오브젝트를 사용해, 장면의 표시나, 어플리케이션의 렌더링 디바이스의 렌더링 타겟으로서 사용하는 표면을 생성 한다.

샘플 Triangle 는, 다음의 코드에 나타내도록(듯이), DirectDraw 오브젝트를 생성 해 초기화의 실행을 시작 한다.

Private Sub InitDDraw()
' DirectDraw 오브젝트를 생성 해 어플리케이션을 설정한다.
'협조 레벨.
Set g_dd = g_dx.DirectDrawCreate("")

위의 코드는, DirectDraw 글로벌 함수 DirectDrawCreate 를 호출해, DirectDraw 오브젝트를 생성 한다. 하늘의 캐릭터 라인을 건네주어, DirectDraw 오브젝트를 액티브한 디스플레이 드라이버용으로 생성 하도록(듯이) 함수에 요구한다. 3D 전용 하드웨어한 어느, GDI 를 지원 하지 않는 하드웨어에 대해서는, 적절한 드라이버의 글로벌 유니크 식별자 (GUID)를 명시적으로 지정할 필요가 있다.

샘플 Triangle 는,DirectDraw7.SetCooperativeLevel 메소드를 호출해, 협조 레벨을 설정한다. 협조 레벨의 설정에 의해, 어플리케이션이, 풀 스크린 모드 또는 표준 윈도우내의 어디에서 렌더링 할까를 시스템에 지시한다 (윈도우내에 렌더링 할 수 없는 하드웨어도 존재하는 것에 주의한다. 그러한 하드웨어는,DirectDraw7.GetCaps 를 호출해, DDCAP2_CANRENDERWINDOWED 능력 플래그가 존재하지 않는 것을 체크해, 검출할 수가 있다). 위의 코드는, 2 번째의 파라미터에 DDSCL_NORMAL 플래그를 지정해,SetCooperativeLevel 에 건네주어, 「표준」협조 레벨이라고도 하는 윈도우 협조 레벨을 요구하고 있다. SetCooperativeLevel 메소드는, 다른 어플리케이션이 배타 모드로 전화면을 이미 제어하고 있는 경우에는 실패하는 일이 있다.

다음의 코드는, 어플리케이션의 협조 레벨의 설정 방법법을 나타낸다.

g_dd.SetCooperativeLevel Me.hWnd, DDSCL_NORMAL

DirectDraw 오브젝트를 생성 해, 협조 레벨을 설정 하면, 렌더링 되는 장면을 포함해, 표시에 사용하는 표면의 준비가 가능한 상태가 된다. 샘플 Triangle 에서는, 이 준비를, 「스텝 2.2 : DirectDraw 표면을 셋업 한다」로 실시한다.


스텝 1.1 : 벽세그먼트(segment)를 준비한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

이 튜토리얼에서는,D3DVERTEX 형의 장면에 있어서의 벽세그먼트(segment)에 대해 설명한다. 이 버텍스는, 「트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스」이다. 「트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스」를 사용 하면, Direct3D 가 독자적인 내부 알고리즘을 사용해 트랜스 폼 & 라이팅 처리를 실행하도록(듯이) 요구할 수가 있다.

3D 공간에서 벽세그먼트(segment)를 정의하려면 , 샘플 DrawPrims 의 이하의 코드에 나타내는 방법으로, 버텍스의 정보를 계산해 보존한다.

Private Sub InitGeometry()

'벽지오메트리를 셋업 한다
Dim x As Double, _
y As Double, _
z As Double

Dim i As Integer

For i = 0 To NUM_WALL_SIDES - 1
x = Sin(2 * pi * i / (NUM_WALL_SIDES - 1))
z = Cos(2 * pi * i / (NUM_WALL_SIDES - 1))

Call g_dx.CreateD3DVertex(x * 10#, -0. 1 * 10#, z * 10#, -x, 0, -z, 0, 0, g_vWall(2 * i + 0))
Call g_dx.CreateD3DVertex(x * 10#, 0.1 * 10#, z * 10#, -x, 0, -z, 0, 0, g_vWall(2 * i + 1))

Next i

위의 코드에서는,DirectX7.CreateD3DVertex 메소드를 사용해,D3DVERTEX 형의 배열 g_vWall 에 버텍스 성분 정보를 묻는다. 이 코드에서는, 삼각함수를 사용해 버텍스의 x 좌표와 z 좌표를 결정한다. CreateD3DVertex 메소드를 사용하는 경우,모델 좌표로 좌표를 지정할 필요가 있다. 「트랜스폼 되지 않은 라이팅 계산 되지 않은의 버텍스」를 사용하므로, 시스템은 모델 좌표에 월드 트랜스 폼, 뷰 트랜스 폼, 및 투영 트랜스 폼을 적용해, 장면내의 적절한 위치에 배치한다. 또, 버텍스의 x, y, 및 z 좌표를 10 으로 스케일 해, 벽세그먼트(segment)를 적절한 사이즈로 한다.

장면내의 벽세그먼트(segment)의 지오메트리를 정의하면(자), 그 외의 지오메트리 프리미티브의 준비하러 진행될 수가 있다. 오브젝트를 정의하는 순서를 의식할 필요는 없다.

3D 공간에서의 원추의 정의에 대해서는, 「스텝 1.2 : 원추를 준비한다」로 설명한다.


스텝 1.1 : 드라이버 정보를 열거한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

글로벌 오브젝트 DirectX7 로 DirectX7.DirectDrawCreate 를 호출하는 것으로, 어플리케이션의 디스플레이 드라이버를 생성 한다.

Set g_dd = g_dx.DirectDrawCreate("")

이것으로, 드라이버 정보를 취득할 수가 있다. 이 튜토리얼에서는, 프라이머리 디스플레이 드라이버만을 사용한다.

Set g_ddEnum = g_dx.GetDDEnum()

For i = 1 To g_ddEnum.GetCount()
g_sDriverGUID = g_ddEnum.GetDescription(i)
Next I

위의 코드에서는,DirectX7.GetDDEnum 메소드를 사용해 DirectDrawEnum 오브젝트를 생성 한다. 다음에,DirectDrawEnum 오브젝트 g_ddEnum 를 사용해, 시스템에 인스톨 되고 있는 비디오 드라이버 디스플레이 어댑터를 열거한다. 프라이머리 디스플레이 드라이버가 검출되면(자),DirectDrawEnum.GetDescription 를 사용해, 지정된 DirectDraw 디바이스의 드라이버 기술을 돌려준다.

샘플 Enumeration 에서는, 다음의 어플리케이션 정의 서브 루틴 호출을 사용해, 디스플레이 모드 열거를 실행한다.

'디스플레이 모드를 열거한다.
EnumModes

디스플레이 모드 열거의 상세한 것에 대하여는,스텝 1.2 : 디스플레이 모드 정보를 열거한다」로 설명한다.


스텝 3.1 : 머트리얼과 초기 라이팅 스테이트를 셋업 한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

기본적인 3D 렌더링 오브젝트 (DirectDraw 오브젝트, 렌더링 디바이스, 및 뷰포트)를 생성 하면, 단순한 장면을 렌더링 하는데 필요한 모든 것이, 거의 갖추어진 것이 된다. 다음으로 하는 것은, 초기 라이팅 스테이트를 설정해, 머트리얼을 생성 및 구성하는 것이다. 설정은 모두, 필요에 따라서, 다음에 변경할 수가 있다. 개념적인 설명에 대해서는, 「라이팅과 머트리얼」을 참조할것.

다음의 코드는,Direct3DDevice7.SetRenderState 메소드를 호출해, 초기 라이팅 스테이트를 렌더링 디바이스 g_d3dDevice 에 적용한다.

g_d3dDevice.SetRenderState D3DRENDERSTATE_AMBIENT, _
g_dx.CreateColorRGBA(1#, 1#, 1#, 1#)

최초의 파라미터,SetRenderState 은, D3DRENDERSTATE_AMBIENT 플래그를 건네주어, 이 호출을 장면의 앰비언트 라이트의 색설정과 관련짓는다. 2 번째의 인수에서는,DirectX7.CreateColorRGBA 메소드를 사용해, 앰비언트 라이트의 적, 초록, 파랑의 컬러값을, 각각 1.0 으로 설정한다. 이 결과 얻을 수 있던 라이팅은, 백색광을 방사한다. 라이팅에서는 알파 성분을 사용하지 않는다. 위의 코드에서는, 알파값도 1.0 으로 설정되어 있다.

D3DMATERIAL7 형을 사용해, 머트리얼의 프로퍼티를 지정한다.

Dim mtrl As D3DMATERIAL7

mtrl.Ambient.r = 1#:mtrl.Ambient.g = 1#:mtrl.Ambient.b = 0#

'머트리얼을 디바이스에 위탁한다.
g_d3dDevice.SetMaterial mtrl

생성 된 새로운 머트리얼에는 프로퍼티가 없기 때문에, 렌더링에는 사용할 수 없다. 위의 코드에서는, 앰비언트 라이트의 빨강과 초록의 요소를 반사하는 머트리얼을 기술해, 장면내에서는 그 머트리얼을 황색으로 나타내는 D3DMATERIAL7 형의 머트리얼 프로퍼티를 설정해 있다 (샘플 Triangle 에서는, 앰비언트 라이트만을 사용하므로, 앰비언트 반사율 프로퍼티만을 설정한다. 실제의 어플리케이션에서는, 앰비언트 라이트 뿐만이 아니라 다이렉트 라이트도 사용하므로, 디퓨즈 및 스펙큐러 반사율의 프로퍼티도 설정할 필요가 있다).

주 : 텍스쳐를 사용하는 경우, 오브젝트 머트리얼은 보통 생략 될까 백색으로 된다.

여기서, 머트리얼, 및 초기 라이팅 파라미터가 설정되었으므로, 샘플 Triangle 는, 좌표 트랜스 폼 행렬의 셋업에 진행된다. 이것에 대해서는, 「스텝 3.2 : 좌표 트랜스 폼 행렬을 준비, 설정한다」로 설명한다.


스텝 2.1 : 디바이스를 취득한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

디바이스를 테스트하기 전에, 테스트하는 디바이스를 취득해야 한다. 이하의 주제에서는, 현재의 디스플레이 설정과 디바이스 참조를 취득하는 방법에 대해 설명한다. 이것에 의해, 그 디바이스로 지원 떠날 수 있어 모든 디스플레이 설정으로 디바이스를 테스트할 수가 있다.

샘플 Enumeration 에서는,DirectDraw7.GetDisplayMode 메소드를 사용해, 현재의 디스플레이 모드 정보를 DDSURFACEDESC2 형으로 취득한다.

g_dd.GetDisplayMode desc
currMode = desc.ddpfPixelFormat.lRGBBitCount

위의 코드에서는, 현재의 디스플레이의 비트/픽셀 설정을 currMode 에 보존한다. 다음에, 현재의 디스플레이 모드를 combobox cmbMode 에 추가한다. 이 박스의 내용이 유저에게 표시된다.

cmbMode.Clear
cmbMode.AddItem Str(currMode) + "- 비트 디스플레이 윈도우"

여기서, 테스트하는 디바이스를 취득하려면 ,Direct3DEnumDevices.GetDesc 메소드를 사용해, combobox cmbDevice 로 유저가 선택하고 있는 디바이스를 확인한다.

Call g_d3dEnumDevices.GetDesc(cmbDevice.ListIndex + 1, deviceDesc)

위의 코드에서는,DDSURFACEDESC2 형 deviceDesc 를 사용해, 테스트하는 디바이스의 표면 기술 정보를 보관 유지한다. 이 디바이스로 지원 되는 디스플레이 모드의 리스트가 생성 된다. 최종적으로는, 이러한 지원 되는 디스플레이 모드가 combobox에 표시되므로, 유저가 샘플 Enumeration 로 디스플레이 모드를 선택할 수가 있다.

주 : 이 튜토리얼에서는, 샘플 Enumeration 의 그라피카르유자인타페이스 (GUI)의 설계와 구조에 대해서는 채택하지 않는다. 이 튜토리얼의 샘플 코드와 GUI 의 관계에 대해서는, SDK 에 포함되는 샘플 Enumeration 전체의 코드를 참조할것.

이것으로, 테스트하는 디바이스에의 참조를 취득했으므로, 디바이스를 테스트할 수가 있다. 디바이스의 테스트에 대해서는, 「스텝 2.2 : 디바이스를 테스트한다」로 설명한다.


스텝 3.2 : 좌표 트랜스 폼 행렬을 준비, 설정한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

단순한 장면을 셋업 하는 이제(벌써) 1 개의 스텝은, 월드 행렬, 뷰 행렬, 및 투영 행렬의 설정에 관계하는 것이다. 시스템은, 모델을 장면안에 두기 (위해)때문에, 카메라의 위치와 방향을 조절하기 위해(때문에), 및 버텍스 데이터를 스케일 해 먼 오브젝트를 가까이의 오브젝트보다 작게 보이게 하기 위해서(때문에), 행렬을 모델의 지오메트리에 적용한다 (개념적인 개요에 대해서는, 「지오메트리 파이프라인」을 참조할것).

월드 행렬을 생성 하려면 ,D3DMATRIX 형 matWorld 를 선언해, 그리고 단위행렬을 생성 한다. 다음에, D3DTRANSFORMSTATE_WORLD 플래그가 세트 된 Direct3DDevice7.SetTransform 메소드를 사용해, 월드 뷰의 행렬을 정의한다.

'월드 행렬은, 월드 공간에 있는 다각형의 위치와 방향을 제어한다.
'다음에, 삼각형을 회전시키기 위해서(때문에) 사용한다.
Dim matWorld As D3DMATRIX

g_dx.IdentityMatrix matWorld
g_d3dDevice.SetTransform D3DTRANSFORMSTATE_WORLD, matWorld

뷰 행렬을 생성 하려면 ,D3DMATRIX 형 matView 를 선언해, 그리고 단위행렬을 생성 한다. 다음에, 카메라 좌표를 DirectX7.ViewMatrix 메소드에 건네주어, 뷰 행렬을 생성 한다. 렌더링 디바이스의 뷰 행렬을 정의하려면 ,SetTransform 메소드를 사용한다.

'뷰 행렬은, 카메라의 위치와 방향을 정의한다.
'여기에서는, 카메라를 z 축으로 따라 15 단위 뒤로 움직이는 것만으로 있다.
Dim matView  As D3DMATRIX

g_dx.IdentityMatrix matView

Call g_dx.ViewMatrix(matView, MakeVector(0, 0, -15), MakeVector(0, 0, 0), _
MakeVector(0, 1, 0), 0)

g_d3dDevice.SetTransform D3DTRANSFORMSTATE_VIEW, matView

위의 코드에서는, Private의 어플리케이션 정의 함수 MakeVector 를 사용해, 3 버텍스를 D3DVECTOR 형에 트랜스 폼 한다.

Private Function MakeVector(a As Double, b As Double, c As Double) As D3DVECTOR
Dim vecOut As D3DVECTOR

With vecOut
. x = a
. y = b
. z = c
End With

MakeVector = vecOut
End Function

투영 행렬을 생성 하려면 ,D3DMATRIX 형 matProj 를 선언해, 그리고 단위행렬을 생성 한다. 다음에, 클립면과 시야 각도를 DirectX7.ProjectionMatrix 메소드에 건네주어, 투영 행렬을 생성 한다. 렌더링 디바이스의 투영 행렬을 정의하려면 ,SetTransform 메소드를 사용한다.

'투영 행렬은, 2D 렌더링 타겟 표면 (백 버퍼 표면) 상에,
' 3D 신을 어떻게 「투영」하는지를 정의한다. 상세한 것에 대하여는,
'투영 행렬의 설명을 참조할것.
Dim matProj As D3DMATRIX

g_dx.IdentityMatrix matProj

Call g_dx.ProjectionMatrix(matProj, 1, 1000, pi / 2)
g_d3dDevice.SetTransform D3DTRANSFORMSTATE_PROJECTION, matProj

위의 코드에서는,ProjectionMatrix 에게 건네지는 2 번째의 파라미터가 전방 클리핑 평면까지의 거리를, 3 번째의 파라미터가 후방 클리핑 평면까지의 거리를, 어플리케이션 지정의 단위로 가리킨다. 4 번째의 파라미터는, 시야 각도를 라디안으로 나타낸다.

머트리얼의 준비와 트랜스 폼 행렬의 설정이 완료하면(자), 장면의 지오메트리를 셋업 할 수가 있다. 이것에 대해서는, 「스텝 3.3 : 지오메트리를 준비한다」로 설명한다.


스텝 4.1 : 신을 갱신한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

장면은 렌더링 하기 전에 갱신해야 한다. RenderScene 는, 불려 가자마자, FrameMove (다른 어플리케이션 정의 서브 루틴)를 호출한다. FrameMove 는, Direct3D 가 모델의 지오메트리에 적용하는 월드 행렬을 갱신하는 것만으로 있다. 어플리케이션은,stepValue 파라미터에 의해 FrameMove 에게 건네진 내부 카운트값에 근거해, y 축을 중심으로 하는 회전을 반영시킨다. 회전은, 1 프레임에 대해 1 번만 적용되기 (위해)때문에, 결과적으로, 모델이 소정의 위치에서 회전하고 있는 것처럼 보인다.

Private Sub FrameMove(stepVal As Single)
Dim matSpinY As D3DMATRIX

Call g_dx.RotateYMatrix(matSpinY, stepVal)
Call g_d3dDevice.SetTransform(D3DTRANSFORMSTATE_WORLD, matSpinY)
End Sub

물론, 현실에는, 어플리케이션은 단일의 모델에 단일의 회전을 적용할 뿐만 아니라, 다양한 일을 실시한다 (회전 행렬의 상세한 것에 대하여는, 「3D 트랜스 폼」의 「회전」을 참조할것).

장면내의 모델의 지오메트리를 갱신 하면, 「스텝 4.2 : 신을 렌더링 한다」로 샘플 Triangle 가 가고 있도록(듯이), 렌더링 타겟 표면에 지오메트리를 렌더링 할 수가 있다.


스텝 1.2 : 디스플레이 모드 정보를 열거한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

DirectDraw7.GetDisplayModesEnum 메소드를 사용해,DirectDrawEnumModes 클래스에의 참조를 돌려줄 수가 있다. 취득된 디스플레이 모드 정보는,DDSURFACEDESC2 형 g_enumInfo: 에 보존된다.

Set g_ddEnumModes = g_dd.GetDisplayModesEnum(DDEDM_DEFAULT, g_enumInfo)

위의 코드에서는, DDEDM_DEFAULT 플래그에 의해, 디스플레이 모드의 표준 열거를 실행하도록(듯이) 어플리케이션에 지시한다. 사용 가능한 옵션에 대해서는, SDK 레퍼런스의 「CONST_DDEDMFLAGS 」의 주제를 참조할것. 이것으로, DirectDraw 드라이버와 디스플레이 모드가 열거되었으므로, 디바이스의 열거하러 진행될 수가 있다. 샘플 Enumeration 에서는, 다음의 어플리케이션 정의 서브 루틴을 사용해 디바이스를 열거한다.

'디바이스를 열거한다.
EnumDevices

디바이스의 열거에 대해서는, 「스텝 1.3 :디바이스 정보를 열거한다」로 설명한다.


스텝 1.3 : 텍스쳐 포맷을 열거한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

텍스쳐를 열거하기 전에,Direct3DEnumPixelFormats 오브젝트를 선언할 필요가 있다.

Dim TextureEnum As Direct3DEnumPixelFormats

다음에, 렌더링 디바이스로 Direct3DDevice7.GetTextureFormatsEnum 메소드를 호출해,Direct3DEnumPixelFormats 오브젝트를 돌려준다.

Set TextureEnum = g_d3dDevice.GetTextureFormatsEnum()

이것으로,Direct3DEnumPixelFormats 오브젝트,TextureEnum 로 메소드를 호출해, 디바이스가 그 텍스쳐로 지원 하는 픽셀 포맷 정보를 취득할 수 있다.

샘플 Texture 의 이하의 코드에서는, 디바이스가 지원 하는 텍스쳐 픽셀 포맷을 루프에 의해 검색한다. 이 코드에서는, 16 비트 텍스쳐를 검색하고 있다. 알파 텍스쳐 등, 그 외의 포맷은 모두 무시되므로 주의한다.

For i = 1 To TextureEnum.GetCount()
bIsFound = True
Call TextureEnum.GetItem(i, ddsd.ddpfPixelFormat)

With ddsd.ddpfPixelFormat
'미지의 모드는 스킵 한다.
If . lFlags And (DDPF_LUMINANCE Or DDPF_BUMPLUMINANCE Or DDPF_BUMPDUDV) Then bIsFound = False

' FourCC 포맷은 모두 스킵 한다.
If . lFourCC <> 0 Then bIsFound = False

'알파 모드는 스킵 한다.
If . lFlags And DDPF_ALPHAPIXELS Then bIsFound = False

' 16 비트 모드 이외의 모드는 모두 스킵 한다.
If . lRGBBitCount <> 16 Then bIsFound = False
End With

If bIsFound Then Exit For

Next i

이것으로, 열거된 텍스쳐 포맷 TextureEnum 로부터, 렌더링 디바이스로 지원 되는 텍스쳐 포맷이 선택되었으므로, 그 텍스쳐에 표면을 생성 할 수가 있다. 이것에 대해서는, 「스텝 1.4 : 텍스쳐에 신규 표면을 생성 한다」로 설명한다.


스텝 1.3 : 입방체를 준비한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

입방체는, 인덱스 붙어 원시적이어 나타내진다. 즉, 버텍스의 배열에 인덱스를 붙이는 것에 의해 정의된다. 렌더링시에 입방체의 버텍스 리스트에 인덱스를 붙이려면 , 다음의 인덱스를 사용한다.

g_nCubeIndices(0) = 1:g_nCubeIndices(1) = 2:g_nCubeIndices(2) = 3
g_nCubeIndices(3) = 2:g_nCubeIndices(4) = 1:g_nCubeIndices(5) = 0
g_nCubeIndices(6) = 4:g_nCubeIndices(7) = 5:g_nCubeIndices(8) = 6
g_nCubeIndices(9) = 6:g_nCubeIndices(10) = 5:g_nCubeIndices(11) = 7
g_nCubeIndices(12) = 3:g_nCubeIndices(13) = 2:g_nCubeIndices(14) = 6
g_nCubeIndices(15) = 3:g_nCubeIndices(16) = 6:g_nCubeIndices(17) = 7
g_nCubeIndices(18) = 0:g_nCubeIndices(19) = 1:g_nCubeIndices(20) = 4
g_nCubeIndices(21) = 4:g_nCubeIndices(22) = 1:g_nCubeIndices(23) = 5
g_nCubeIndices(24) = 2:g_nCubeIndices(25) = 0:g_nCubeIndices(26) = 4
g_nCubeIndices(27) = 2:g_nCubeIndices(28) = 4:g_nCubeIndices(29) = 6
g_nCubeIndices(30) = 1:g_nCubeIndices(31) = 3:g_nCubeIndices(32) = 5
g_nCubeIndices(33) = 5:g_nCubeIndices(34) = 3:g_nCubeIndices(35) = 7

장면내의 모든 오브젝트의 지오메트리를 정의하면(자), 장면을 렌더링 해 표시할 수가 있다. 이것이, 「스텝 2 : 신을 렌더링, 표시한다」의 설명 내용이다.


스텝 2.4 : 뷰포트를 준비한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

렌더링 디바이스를 생성 하면, 뷰포트 오브젝트를 생성 해, 디바이스에 할당하는 것이 가능하게 된다. 간단하게 말하면(자), 뷰포트란, 3D 신에 있어서의 지오메트리를 클립 해, 2D 의 표시 화면 공간에 표현하는 방법을 결정하는 것이다. 뷰포트의 개념적인 개요에 대해서는, 「뷰포트와 클리핑」을 참조할것.

뷰포트의 셋업은 단순명료한 프로세스이며,D3DVIEWPORT7 형의 뷰포트 파라미터를 준비하는 것으로부터 시작된다. 샘플 Triangle 에서는, 장면이 렌더링 되는 최소 깊이와 최대 깊이, 즉 0, 0 에서 1, 0 의 표준 범위에 있는 렌더링 타겟 표면의 치수를, 뷰포트의 파라미터로 설정해 있다.

Dim VPDesc As D3DVIEWPORT7

VPDesc.lWidth = g_rcDest.Right - g_rcDest.Left
VPDesc.lHeight = g_rcDest.Bottom - g_rcDest.Top
VPDesc.minz = 0#
VPDesc.maxz = 1#

뷰포트 파라미터형의 준비가 종료 하면, Triangle 는 렌더링 디바이스의 뷰포트 파라미터를 설정한다.

g_d3dDevice.SetViewport VPDesc

여기서, 뷰포트 파라미터를 RECT 형의 캐쉬에 넣는다. 이 값은, 다음에 처리를 클리어 할 때에 사용한다.

With g_d3drcViewport(0)
. X1 = 0:. Y1 = 0
. X2 = VPDesc.lWidth
. Y2 = VPDesc.lHeight
End With

여기서, 기본적인 DirectX 오브젝트의 생성이 종료했으므로, 장면의 렌더링에 필요한 종속 오브젝트의 준비를 시작할 수가 있다. 이것이, 「스텝 3 : 신을 초기화한다」의 설명 내용이다.


스텝 2.2 : 디바이스를 테스트한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

다음의 코드는, 디바이스의 능력을 확인하는 방법을 나타낸다. 샘플 Enumeration 에서는, 다음의 알고리즘을 사용해, 지정된 디바이스로 지원 되는 디스플레이 모드를 선택한다.

  1. DirectDrawEnumModes 오브젝트로 지정된 요소의 비디오 모드 기술을 돌려준다.
  2. 돌려주어진 비디오 모드 기술로부터, 지원 되는 비트/픽셀을 취득한다.
  3. 지정된 디바이스의 렌더링 깊이를 취득한다.
  4. DirectDrawEnumModes 오브젝트로 지정된 요소의 비디오 모드가, 취득된 디바이스의 렌더링 깊이와 호환성이 있을지 어떨지를 체크한다. 호환성이 있는 경우는 그 디스플레이 모드를 받아, 없는 경우는 거부한다. 8 비트 모드는 모두 스킵 한다.

샘플 Enumeration 에서는, 다음의 코드를 실행해 이 알고리즘을 이행 한다.

For j = 1 To g_ddEnumModes.GetCount()
'이 디스플레이 모드는 테스트되어 있지 않기 때문에, 호환성이 없는 것이라고 본다.
bCompatible = False
'스텝 1:
g_ddEnumModes.GetItem j, g_enumInfo

'스텝 2:
modeDepth = g_enumInfo.ddpfPixelFormat.lRGBBitCount

'스텝 3:
bitDepth = deviceDesc.lDeviceRenderBitDepth

'스텝 4:
If (32 = modeDepth) And (bitDepth And DDBD_32) Then bCompatible = True
If (24 = modeDepth) And (bitDepth And DDBD_24) Then bCompatible = True
If (16 = modeDepth) And (bitDepth And DDBD_16) Then bCompatible = True

'필요한 디스플레이 모드만을 combobox에 표시한다.
If bCompatible Then
cmbMode.AddItem Str(g_enumInfo.lWidth) + " x" + Str(g_enumInfo.lHeight) + " x" + Str(g_enumInfo.ddpfPixelFormat.lRGBBitCount)
End If
Next j

이 알고리즘이 완료 하면, 지정된 조건에 합치하는 디스플레이 모드의 리스트가 combobox cmbMode 에 보관 유지되어 그 이외의 디스플레이 모드는 모두 무시된다.


스텝 2.2 : DirectDraw 표면을 셋업 한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

DirectDraw 오브젝트를 생성 해, 그 협조 레벨을 설정 하면, 어플리케이션이 장면의 렌더링, 표시에 사용하는 표면을 생성 할 수 있다. 표면의 생성 방법은, 어플리케이션이 윈도우내 또는 풀 스크린 모드의 어디에서 실행될까에 의해, 거의 결정된다.

풀 스크린 어플리케이션에 대해 ： 풀 스크린 모드로 실행되는 어플리케이션은, 위의 코드예에 나타내도록(듯이) 표면을 생성 할 수가 있다. 풀 스크린 어플리케이션에서는, 풀 스크린 배타 모드에 한해서 사용할 수 있는 기능인 페이지 플립핑을 이용하는 것이 빈번하게 행해지고 있다. 풀 스크린 모드의 사용에 대해서는, 이하의 튜토리얼로 설명한다. 이 경우, 2 개의 표면을 명시적으로 생성 하는 것이 아니라, 단일 콜로, 표면의 플립핑 체인을 생성 할 수가 있다. 상세한 것에 대하여는, 「복합 표면과 플립핑 체인의 생성」을 참조할것.

샘플 Triangle 는, 윈도우내에서 실행되도록(듯이) 설계되고 있어 디스플레이로서 기능하는 프라이머리 표면의 생성으로부터 시작된다.

'프라이머리 표면을 준비해 생성 한다.
    g_ddsd.lFlags = DDSD_CAPS
    g_ddsd.ddsCaps.lCaps = DDSCAPS_PRIMARYSURFACE

    Set g_ddsPrimary = g_dd.CreateSurface(g_ddsd)

프라이머리 표면 기술에는, 치수나 픽셀 포맷의 정보는 포함되지 않는다. 이러한 특징은, 디스플레이 모드와 같다라고 보여지고 있기 때문이다. 현재의 디스플레이 모드가, 800×600 의 16 비트 컬러이면, DirectDraw 는, 프라이머리 표면도 같은 것을 보증한다. 프라이머리 표면을 생성 하면, 렌더링 타겟의 표면을 생성 하는 것이 가능하게 된다. 샘플 Triangle 의 경우, 이것은, 다음과 같이 해 생성 되는, 다른 오프 스크린 표면이 된다.

'렌더링 타겟의 표면을 생성 한다. 여기서 g_ddsd 를 재사용한다.
g_ddsd.lFlags = DDSD_HEIGHT Or DDSD_WIDTH Or DDSD_CAPS
g_ddsd.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN Or DDSCAPS_3DDEVICE

'폼의 사이즈를 사용해 렌더링 타겟의 사이즈와
'뷰포트의 직사각형을 지정한다.
g_dx.GetWindowRect Me.hWnd, g_rcDest

'표면 기술의 사이즈를 설정한다.
g_ddsd.lWidth = g_rcDest.Right - g_rcDest.Left
g_ddsd.lHeight = g_rcDest.Bottom - g_rcDest.Top

'렌더링 타겟의 표면을 생성 한다.
Set g_ddsBackBuffer = g_dd.CreateSurface(g_ddsd)

'렌더링 타겟의 사이즈를 캐쉬에 넣는다. 이 사이즈는,
'블리트로 사용된다.
With g_rcSrc
. Left = 0:. Top = 0
. Bottom = g_ddsd.lHeight
. Right = g_ddsd.lWidth
End With

위의 코드는, 어플리케이션 윈도우의 사이즈와 동일한 오프 스크린 표면을 생성 한다. 오프 스크린 표면을 사용해, 다음에 프라이머리 표면에 블리트 되는 이미지를 캐쉬에 넣는다. 그것보다 큰 표면은, 윈도우의 사이즈에 의해 유저로 보이는 범위가 결정되기 (위해)때문에, 필요하게 되지 않는다 (이 코드는, 뷰포트의 셋업 및 어플리케이션 윈도우의 사이즈와 위치의 추적을 실시하기 위해서(때문에) 사용하는, 글로벌 변수 g_rcDest 의 초기화도 가고 있다). 위의 코드가 가리키도록(듯이), 렌더링 타겟으로서 사용되는 표면에는 모두, DDSCAPS_3DDEVICE 능력을 포함하지 않으면 안 된다. 이 능력에 의해, 시스템은 3D 렌더링에 사용되는 추가의 내부 데이터 구조를 할당한다. 프라이머리 표면을 생성 하는 경우와 같게, 오프 스크린 표면의 픽셀 포맷은, 표면 기술로 지정되어 있지 않으면, 디스플레이 모드로 같은으로 여겨진다.

주 : 깊이 버퍼를 사용하는 어플리케이션에서는, 이 시점에서, 1 개의 깊이 버퍼를 생성 해, 렌더링 타겟 표면에 Attach 할 필요가 있다. 이해하기 쉽게하기 위해(때문에), 이 튜토리얼에서는 깊이 버퍼를 사용하고 있지 않지만, 깊이 버퍼에 대해서는, 「튜토리얼 2 : 깊이 버퍼를 추가한다」 및 「깊이 버퍼」로 설명한다.

렌더링 타겟의 프라이머리 표면을 생성 하면,DirectDrawClipper 오브젝트를 생성 해 표시 표면에 Attach 하는 것이 가능하게 된다. 클립퍼를 사용 하면, 윈도우가 부분적으로 다른 윈도우에 의해 숨겨졌을 경우나, 윈도우가 부분적으로 표시 영역을 넘었을 경우의 처리를 하지 않아도 된다. 따라서, 클립퍼는, 풀 스크린 모드로 실행되는 어플리케이션에는 필요없다. 샘플 Triangle 는, 다음의 코드를 사용해 클립퍼를 생성 해, 표시 윈도우에 결합하고 있다.

' DirectDrawClipper 를 생성 해, 프라이머리 표면에 Attach 한다.
Dim pcClipper As DirectDrawClipper

Set pcClipper = g_dd.CreateClipper(0)
pcClipper.SetHWnd Me.hWnd

g_ddsPrimary.SetClipper pcClipper

기본적인 DirectDraw 오브젝트의 생성을 종료 하면, 장면을 렌더링 하는 Direct3D 주요 오브젝트의 셋업에 진행될 수가 있다. 샘플 Triangle 는, 「스텝 2.3 : Direct3D 를 초기화한다」로 이 태스크를 실시하고 있다.


스텝 2.2 : 3D 트랜스 폼을 실행한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

이 튜토리얼에서는, 지오메트리 트랜스 폼을 사용해, 입방체의 위치 좌표를 장면내외의 오브젝트와의 관계로 정의해, 입방체를 회전해, 장면내에서 입방체를 스케일 한다.

3D 트랜스 폼을 이행 하기 전에, 뷰포트의 높이와 폭을 취득할 필요가 있다. 이 정보를 사용해, 트랜스 폼 된 버텍스를 렌더링 윈도우에 맞추어 스케일 한다.

Private Sub TransformVertices(d3dDevice As Direct3DDevice7, vVertices() As D3DTLVERTEX, nNumVertices As Integer)

Dim vp As D3DVIEWPORT7
Dim nClipWidth As Integer
Dim nClipHeight As Integer

'뷰포트의 높이와 폭을 취득한다. 이 조작은, 트랜스 폼 된 버텍스를 렌더링 윈도우에
'맞추어 스케일 하기 위해서 필요하다.
d3dDevice.GetViewport vp
nClipWidth = vp.lWidth / 2
nClipHeight = vp.lHeight / 2

Direct3D 에서는, 행렬을 사용해 트랜스 폼을 실행한다. 3D 트랜스 폼을 실행하려면 , 현재의 행렬 설정의 값을 취득할 필요가 있다. 이 값을 취득하려면 , 렌더링 디바이스로 Direct3DDevice7.GetTransform 를 호출한다.

d3dDevice.GetTransform D3DTRANSFORMSTATE_WORLD, matWorld
d3dDevice.GetTransform D3DTRANSFORMSTATE_VIEW, matView
d3dDevice.GetTransform D3DTRANSFORMSTATE_PROJECTION, matProj

행렬을 연결하려면 , 행렬 곱셈을 사용한다.

Dim matSet As D3DMATRIX

g_dx.IdentityMatrix matSet

'행렬을 연결한다.
g_dx.MatrixMultiply matSet, matWorld, matView
g_dx.MatrixMultiply matSet, matSet, matProj

위의 코드에서는, 합성 행렬 matSet 를 계산해, 필요한 트랜스 폼의 적을 얻는다. 연결시에는, 행렬이 처리순서에 곱셈되도록(듯이) 한다.

행렬 연결에 대해서는, 「행렬 연결」을 참조할것.

여기서, 현재의 행렬 설정에 의해 각 버텍스를 트랜스 폼 한다.

For i = 0 To nNumVertices - 1
'트랜스폼 되지 않은의 버텍스 위치를 취득한다.
x = vVertices(i). sx
y = vVertices(i). sy
z = vVertices(i). sz

xp = matSet.rc11 * x + matSet.rc21 * y + matSet.rc31 * z + matSet.rc41
yp = matSet.rc12 * x + matSet.rc22 * y + matSet.rc32 * z + matSet.rc42
zp = matSet.rc13 * x + matSet.rc23 * y + matSet.rc33 * z + matSet.rc43
wp = matSet.rc14 * x + matSet.rc24 * y + matSet.rc34 * z + matSet.rc44

마지막으로, 화면 좌표에 맞추어 버텍스를 스케일 한다. 다음의 코드에서는, 최초의 스텝에서, 각 좌표를 wp 값으로 나눗셈 하는 것으로써, 3D 공간에서 2D 디바이스 좌표로 변환한다. 다음에, x 좌표와 y 좌표를 디바이스 좌표로부터 화면 좌표로 변환한다.

vVertices(i). sx = (1# + (xp / wp)) * nClipWidth
vVertices(i). sy = (1# - (yp / wp)) * nClipHeight
vVertices(i). sz = zp / wp
vVertices(i). rhw = wp
Next i

3D 트랜스 폼의 상세한 것에 대하여는, 「3D 트랜스 폼」을 참조할것.

주 : 디바이스 좌표는, 뷰포트의 것 -1 으로부터 +1 의 범위가 된다. 또, z 버퍼에서는 sz 좌표를 사용한다.

이것으로, 입방체의 8 개의 버텍스를 트랜스 폼 했으므로, 완성한 장면의 프레임을 렌더링 할 수가 있다. 이것이, 「스텝 2.3 : 신을 렌더링 한다」의 설명 내용이다.


스텝 1.2 : 원추를 준비한다

[C++]

여기에서는, Visual Basic 에서의 어플리케이션 카이하츠에 도착해 설명한다. C++ 에 대해서는, 「Direct3D 직접 모드의 C/C++ 튜토리얼」을 참조할것.

[Visual Basic]

원추의 지오메트리는, 위치 벡터와 법선 벡터를 선언하는 것만으로 준비할 수 있다. 샘플 DrawPrims 에서는, 다음의 프로그래머 정의형에 의해 원추 오브젝트를 정의한다.

Private Type MyFlexibleVertex
vPosition As D3DVECTOR
vNormal As D3DVECTOR
End Type

원추의 첨단은, 다음의 코드로 정의할 수 있다.

Dim vectorNorm As D3DVECTOR

g_vCone(0). vPosition = MakeVector(0, CONE_HEIGHT / 2, 0)

vectorNorm = MakeVector(0, 1, 0)
Call g_dx.vectorNormalize(vectorNorm)
g_vCone(0). vNormal = vectorNorm

원추의 각면은, 다음의 삼각함수로 계산할 수 있다.

For i = 0 To NUM_CONE_SIDES - 1
x = Sin(2 * pi * i / (NUM_CONE_SIDES - 1))
y = -CONE_HEIGHT / 2
z = Cos(2 * pi * i / (NUM_CONE_SIDES - 1))

g_vCone(i + 1). vPosition = MakeVector(x * CONE_RADIUS, y * CONE_RADIUS, z * CONE_RADIUS)

원추의 각면의 위치 벡터는, 다음의 코드로 계산할 수 있다.

vectorNorm = MakeVector(x, 0.5, z)
Call g_dx.vectorNormalize(vectorNorm)
g_vCone(i + 1). vNormal = vectorNorm
Next i

지오메트리 공간에서 벽세그먼트(segment)와 원추를 정의하면(자), 입방체의 준비하러 진행될 수가 있다. 이 처리에 대해서는, 「스텝 1.3 : 입방체를 준비한다」로 설명한다.


Copyright

본사이트에서 이용 가능한 소프트웨어에 대한 주의

본사용 허락 계약서 (이하 「본계약서」라고 합니다)는, 이 사이트 (이하 「본사이트」라고 합니다)에서 이용 가능한 소프트웨어 (이하 「본소프트웨어 제품」이라고 합니다)에 관해서 손님 (개인 또는 법인의 머지않아일까를 묻지 않습니다)과 Microsoft® Corporation (이하 「마이크로 소프트」라고 합니다)와의 사이에 체결되는 법적인 계약서입니다. 본소프트웨어 제품을 인스톨, 복제, 또는 사용하는 것에 의해, 손님은 본계약서의 조항에 구속되는 것에 승낙된 것으로 합니다. 본계약서의 조항에 동의 되지 않는 경우, 마이크로 소프트는, 손님에게 본소프트웨어 제품의 인스톨, 사용, 또는 복제의 모두 허락할 수 없습니다.

본소프트웨어 제품은, 손님이 본계약서의 조항에 동의 되는 경우에게만 사용할 수가 있습니다. 본계약서의 조항에 근거하지 말고 본소프트웨어 제품을 재빌드 또는 재반포하는 것은, 저작권법 및 저작권에 관한 조약을 시작해 그 외의 지적재산권에 관한 법률 및 조약에 의해 금지되고 있습니다.

앞에서 본 제한에 관계없이, 본소프트웨어 제품을, 재빌드 또는 재반포를 목적으로, 어떠한 서버 또는 사이트에 대해서도 카피 및 재빌드 하는 것은 단단하게 금지되고 있습니다.

본소프트웨어 제품은, 본계약서의 조항에 근거해서만 품질이 보증되고 있습니다. 마이크로 소프트는, 상품성 및 특정의 목적에 대한 적합성을 포함한 본계약서에 규정되어 있지 않은 그 외의 보증을, 명시든 묵시든을 불문하고 일절 하지 않습니다.

권리의 제한. 미국 및 그 기관 (이하 「U.S. 정부」라고 합니다)가 대표로 해 본사이트로부터 취득해 도미 가나소프트웨어도, 제한된 권리아래에서만 제공됩니다. U.S. 정부에 의한 본소프트웨어 제품의 사용, 복제, 또는 개시는, DFARS 252.227-7013 의 Technical Data and Computer Software 조항의 「Rights」의 (c)(1)(ii), 또는 48 CFR 52.227-19 의 Commercial Computer Software 조항의 「Restricted Rights」의 (c)(1) 및 (2)의 항으로 기술되고 있는 제한아래에서만 허가되고 있습니다. 본소프트웨어 제품의 제조원은, Microsoft Corporation, One Microsoft Way, Redmond, WA 98052-6399 입니다.

본사이트에서 이용 가능한 문서에 대한 주의

본사이트의 문서 (화이트 페이퍼, 프레스 릴리스, 데이타베이스, FAQ 등)의 사용은, (1) 아래와 같은 저작권 표시를 문서의 모든 복제물에 표기하는, (2) 본사이트의 문서를 사용하는 목적이, 정보 제공, 비영리, 또는 개인적 사용으로 한정되고 있는 것, 또, 본사이트의 문서가 네트워크 컴퓨터에 카피 또는 투고되지 않는 것, 게다가 어떠한 미디어를 통해서도 본사이트의 문서가 전달되지 않는 것, (3) 문서가 있고개찬도 실시하지 않는 것, 이라고 하는 조건이 준수되는 경우에게만 허가됩니다. 상기 이외의 목적으로, 본사이트의 문서를 사용하는 것은, 저작권법 및 저작권에 관한 조약에 의해 금지되고 있습니다.

상기로 규정하고 있는 문서에는, 마이크로 소프트의 . com Web 사이트, 또는 마이크로 소프트가 관리, 운영하는 그 외의 사이트의 디자인 및 레이아웃은 포함되어 있지 않습니다. 마이크로 소프트의 Web 사이트의 이러한 원가요소는, 트레이드 드레스 또는 그 외의 법률에 의해 보호되고 있습니다. 또, 부분적, 전체를 불문하고, 이러한 원가요소를 복사 또는 모방하는 것은 금지되고 있습니다. 마이크로 소프트의 Web 사이트의 로고, 그래픽스, 사운드, 및 이미지의 사용 또는 변환은, 마이크로 소프트로부터 명시적으로 허가되어 있지 않은 한, 금지되고 있습니다.

마이크로 소프트 또는 그 공급자는, 본사이트의 문서 및 관련하는 그래픽스에 포함되는 정보의 적합성을 보증하는 것이 아닙니다. 본사이트의 문서 및 관련하는 그래픽스는, 어떠한 보증도 없고, 현상유자로 제공됩니다. 마이크로 소프트 또는 그 공급자는, 본사이트의 문서 및 관련하는 그래픽스에 포함되는 정보에 관해서, 상품성 및 특정의 목적에 대한 적합성을 포함한 본계약서에 규정되어 있지 않은 그 외의 보증을, 명시든 묵시든을 불문하고 일절 하지 않습니다. 어떠한 경우에도, 본사이트의 정보의 이용으로부터 생기는 손해 (부수적, 직접, 간접, 특별, 파생적 손해, 영업이익 손실 손해, 영업의 중단, 영업상의 정보의 상실, 그 외 금전적 손해를 포함합니다만, 그런 만큼 한정하지 않습니다)에 대해서, 마이크로 소프트에 걸리는 손해의 가능성의 통지가 있었을 경우에서도, 마이크로 소프트 또는 그 공급자는, 일절 책임을 지기 어렵습니다.

본사이트의 문서 및 관련하는 그래픽스에 포함되는 정보는, 정확하지 않을 가능성이 있습니다. 또, 이러한 정보는 정기적으로 갱신됩니다. 마이크로 소프트 또는 그 공급자는, 본소프트웨어 제품의 개선 또는 변경을 필요에 따라서 실시합니다.

본사이트에서 이용 가능한 소프트웨어, 문서, 및 서비스에 대한 주의

어떠한 경우에도, 본소프트웨어 제품, 본사이트의 문서, 및 본사이트의 서비스의 사용 혹은 사용 불능으로부터 생기는 손해 (부수적, 직접, 간접, 특별, 파생적 손해, 영업이익 손실 손해, 영업의 중단, 영업상의 정보의 상실, 그 외 금전적 손해를 포함합니다만, 그런 만큼 한정하지 않습니다)에 대해서, 마이크로 소프트에 걸리는 손해의 가능성의 통지가 있었을 경우에서도, 마이크로 소프트 또는 그 공급자는, 일절 책임을 지기 어렵습니다.

써드파티의 사이트로의 링크

써드파티의 사이트로부터 책 사이트로 링크가 설정되어 있는 경우, 그 링크가 클릭되는 것으로, 유저는 본사이트로 이동할 수가 있습니다. 책 사이트로 링크를 설정해 있는 써드파티의 사이트는, 마이크로 소프트의 관리하에는 않고, 마이크로 소프트는, 이러한 써드파티의 사이트의 컨텐츠 및 링크에 대해서 일절 책임을 지지 않습니다. 마이크로 소프트는, 이러한 링크를 편의를 꾀하기 위해서(때문에) 마셔 제공하고 있습니다. 써드파티의 사이트에 책 사이트로의 링크가 포함되어 있어도, 마이크로 소프트가 그 써드파티의 사이트의 안전성을 보증하고 있는 것은 아닙니다.

저작권에 대한 주의. Copyright © 1999 Microsoft 및 그 공급자, One Microsoft Way, Redmond, Washington 98052-6399 U.S.A. All rights reserved.

상표. Microsoft, Windows, Windows NT, MSN, The Microsoft Network 또는 본사이트에서 언급되고 있는 그 외의 Microsoft 의 제품은, Microsoft 의 상표 또는 등록상표입니다. 본사이트에서 언급되고 있는 실재의 회사명 및 제품명은, 각사의 상표입니다.

본사이트에서 예로서 취하는 기업, 조직, 제품, 인물, 및 이벤트는 모두 가공의 것입니다. 실재의 기업, 조직, 제품, 인물, 또는 이벤트와의 관련성을 시사하는 것이 아닙니다.

본계약서의 아래 명백하게 허락되어 있지 않을 권리는, 모두 마이크로 소프트에 유보되고 있습니다.

본사이트의 서비스에 대해서 불명한 점이나 질문이 있는 경우는,Microsoft 까지 연락해 주십시오.
**

** ** © 1999 Microsoft Corporation. All rights reserved. Terms of Use.


A

앰비언트(ambient)
오브젝트의 향해, 위치, 표면 특성 등에 관계없이, 장면 위에의 모든 것을 비추는 광원. 장면의 모든 장소를 같은 광도로 비추기 (위해)때문에, 거기에 놓여진 프레임의 위치나 방향은 중요하지 않다. 1개의 장면에서는, 복수의 앰비언트 광원이 결합되고 있다.
배열 오브젝트(array object)
1개의 배열에 정리된 오브젝트군. 배열 오브젝트를 사용하면(자), 일련의 오브젝트 모두에게 어떠한 처리를 실시하는 경우의 조작이 간단하게 된다. 배열 오브젝트를 취급할 수가 있는 COM 인터페이스에는,GetElement와GetSize라고 하는 메소드가 준비되어 있다. 이 2개의 메소드는 각각, 배열 요소에의 포인터의 취득, 및 배열 사이즈의 취득을 실시한다.


B

백 버퍼(back buffer)
화면에 표시되지 않는 표면. 어플리케이션은, 프라이머리 표면의 이미지가 화면에 표시되고 있는 동안에, 비트 맵이나 그 외의 이미지를 백 버퍼에 그려 넣을 수가 있다.
백 클리핑 프레인(back clipping plane)
절두체의 깊이의 한계. 이 저쪽 편에 있는 오브젝트는 렌더링 되지 않는다. 「프런트 클리핑 프레인」을 참조.


C

카메라(camera)
표시 위치와 방향을 정의하기 위해(때문에), 뷰포트가 이용하는 Direct3DRMFrame 오브젝트. 뷰포트는, 카메라 프레임의 정의 z축상에 있는 가시 오브젝트만을, y축위에의 정방향에 렌더링 한다.


D

디칼(decal)
비주얼 오브젝트로서 직접 렌더링 되는 텍스쳐. 뷰포트에 위치를 맞춘 직사각형에 렌더링 된다.
디렉셔널(directional)
프레임에 Attach 되지만, 모든 오브젝트를 같은 휘도(Luminance)로 비추는 광원. 마치 광원이 오브젝트로부터 무한의 거리에 위치할 것 같은 효과를 준다. 디렉셔널빛은, 방향은 가지지만 위치를 가지지 않고, 일반적으로, 태양과 같이 멀게 멀어진 광원을 시뮬레이트 하기 위해서 이용된다.


E

방사 특성(emissive property)
머트리얼(소재)이 빛을 방사할지 어떨지를 나타내는 머트리얼 특성. 머트리얼의 빛의 반사 상태를 결정하는 특성은 2개 있지만, 방사 특성은 그 중의 1 개(살)이다. 「반사 특성」을 참조.
유효 프레임(enable frame)
조명을 적용할 수가 있는 프레임.


F

프런트 클리핑 프레인(front clipping plane)
절두체의 전면의 한계. 프런트 클리핑 프레인보다 카메라 집합에 있는 오브젝트는 렌더링 되지 않는다. 프런트 클리핑 프레인의 높이에 의해, 뷰의 필드가 정해진다. 「백 클리핑 프레인」을 참조.


M

밉맵(mipmap)
동일 이미지가 서서히 저해상도가 되어 가는 일련의 텍스쳐로, 1 개의 이미지에 몇 종류의 필터를 걸치는 것으로 생성 된다. 오브젝트가 근처에 표시될 때는 고해상도의 이미지가 사용되어 오브젝트가 멀어지는에 따라(즉 화면에서의 표시가 작아지는에 따라) 저해상도의 이미지가 사용된다.
모델 좌표(model coordinates)
아이 프레임에 대한 상대 좌표. 「월드 좌표」를 참조.


N

법선 벡터(normal vector)
표면으로부터 수직에 뻗는 가공의 선으로, 면의 방향의 정의에 사용된다.


P

패러럴 포인트(parallel point)
평행한 광선으로 오브젝트를 비춘다. 빛의 방향은 그 위치로부터 결정되는 것 같은 광원. 예를 들어, 패러럴 포인트 광원의 양측에 있던 2개의 메쉬가 있는 경우, 각 메쉬는 광원에 접하고 있는 (분)편의 면이 비추어진다.
암영부(penumbra)
spotlight 조명에서의 주위의 어슴푸레한 부분. 암영부는 명부를 둘러싸, 그 주변의 어두운 그림자와 머지 된다. 「명부」, 「spotlight」를 참조.
포인트(point)
그 기점으로부터 모든 방향에 균등하게 빛을 방사하는 조명.
강도(power)
머트리얼의 반사 특성으로, 반사 하이라이트의 선명도를 결정하는 값. 이 값이 5 때는 금속적인 외관이 되어, 값이 좀 더 높아지면(자)보다 플라스틱적인 외관이 된다.


R

참조 카운트(reference count)
COM(컴퍼넌트 오브젝트 모델) 오브젝트를 컨트롤하기 위한 카운터. 참조 카운트는, 오브젝트가 생성 되었을 때에 1으로 설정된다. 포인터가 오브젝트의 인터페이스의 하나에 포인트를 할당할 수 있으면(자), 그 오브젝트의 참조 카운트는 인크리먼트(increment) 된다. 인터페이스 접속이 파기되면(자) 감소 된다. 참조 카운트가 0이 되면(자), 오브젝트는 파기된다. 파기된 오브젝트에의 인터페이스는 모두 무효가 된다. 상세한 것에 대하여는, 「IUnknown 인터페이스」를 참조할것.
루트 프레임(root frame)
Direct3D에서의, 친프레임을 가지지 않는(즉, 프레임의 계층 구조의 최상정도에 위치한다) 프레임. 루트 프레임에는, 장면을 구성하는 일련의 오브젝트 모든 것이 저장 된다.


S

반사 특성(specular property)
빛나는 오브젝트 위에의빛의 점이, 반사된 광원과 어떻게 대응하는지를 나타내는 머트리얼 특성. 머트리얼의 빛의 반사 상태를 결정하는 특성은 2개 있지만, 반사 특성은 그 중의 1 개(살)이다. 「방사 특성」을 참조.
spotlight(spotlight)
원추형의 미츠루를 추방하는 조명. 원추안에 있는 오브젝트만이 비추어진다. 원추는 2개의 휘도(Luminance)를 생성한다. 중앙의 밝은 부분(명부)은 포인트 조명과 같은 기능을 해, 주위의 어슴푸레한 부분(암영부)은 주변의 어두운 그림자와 머지 된다.


T

텍스쳐 블렌딩(texture blending)
텍스쳐의 색을 맵처의 표면의 색과 조합하는 기술.


U

명부(umbra)
조명 각도에서의 중앙의 밝은 부분. 명부는 포인트 조명으로서 작용한다. 「암영부」, 「spotlight」를 참조.


V

버텍스 분할(vertex split)
버텍스 분할은, 기존의 버텍스의 옆에 새로운 버텍스를 추가해, 2개의 면을 추가한다. 단일의 메쉬, 및 그 메쉬를 서서히 정제 하는 버텍스 분할 레코드세트에 의해, 복합 메쉬를 구축할 수가 있다. 이것에 의해, 리모트 사이트로부터의 메쉬의 프로그래시브 다운로드도 가능하게 된다.
절두체(viewing frustum)
뷰포트의 카메라에 대해서 상대적으로 배치된 장면내의 3 D볼륨. 절두체안에 있는 오브젝트는, 화면에 표시된다. 원근 뷰에서는, 프런트 클리핑 프레인과 백 클리핑 프레인의 사이에 있는 가상적인 피라미드형의 볼륨이 된다. 정 쏘아 맞히고 뷰에서는, 입방체가 된다.


W

월드 좌표(world coordinates)
루트 프레임에 대한 상대 좌표. 「모델 좌표」를 참조.


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


IDirect3DRMFrame3 메소드 A~M

이 항은,IDirect3DRMFrame3 인터페이스의 메소드 가운데, 메소드명이 A로부터 M의 것을 취하는 레퍼런스 페이지이다.

IDirect3DRMFrame3::AddChild

IDirect3DRMFrame3

아이 프레임을 프레임 계층에 추가한다.

구문

HRESULT AddChild(
  LPDIRECT3DRMFRAME3 lpD3DRMFrameChild
  );

파라미터

lpD3DRMFrameChild
자식으로 추가하는 Direct3DRMFrame 오브젝트의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

자식으로 추가하는 프레임에, 벌써 친프레임이 존재하는 경우에는, 이 메소드는, 그 프레임을 현재의 부모로부터 삭제한 후에 새로운 부모에게 추가한다. 아이 프레임은, Direct3DRMFrameArray 오브젝트의 마지막에 추가된다. Direct3DRMFrameArray 오브젝트는,IDirect3DRMFrame3::GetChildren 를 사용해 취득할 수 있다.

오브젝트의 변환을 보존하기 위해서는,IDirect3DRMFrame3::GetTransform 메소드를 사용해AddChild메소드를 사용하기 전에 오브젝트의 변환을 취득한다. 그 후, 프레임이 추가된 다음에 그 변환을 재적용한다.

참조

「계층」

IDirect3DRMFrame3::AddLight

IDirect3DRMFrame3

조명을 프레임에 추가한다.

구문

HRESULT AddLight(
  LPDIRECT3DRMLIGHT lpD3DRMLight
  );

파라미터

lpD3DRMLight
프레임에 추가하는 Direct3DRMLight 오브젝트를 나타내는 변수의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

조명은, Direct3DRMLightArray 오브젝트의 마지막에 추가된다. Direct3DRMLightArray 오브젝트는,IDirect3DRMFrame3::GetLights 를 사용해 취득할 수 있다.

IDirect3DRMFrame3::AddMoveCallback

IDirect3DRMFrame3

특수한 운동의 처리용으로 콜백 함수를 추가한다. 프레임을 이동시 또는 갱신시에, 이 콜백이 불려 간다.

구문

HRESULT AddMoveCallback(
  D3DRMFRAME3MOVECALLBACK d3drmFMC,
  VOID *lpArg,
  DWORD dwFlags
  );

파라미터

d3drmFMC
어플리케이션 정의D3DRMFRAME3MOVECALLBACK콜백 함수.
lpArg
콜백 함수에게 건네지는 어플리케이션 정의 데이터.
dwFlags
이하의 값의 하나.
D3DRMCALLBACK_PREORDER － 디폴트값. IDirect3DRMFrame3::Move 가 계층을 더듬어 갈 때, 프레임의 콜백 함수는, 아이 프레임을 더듬기 전에 불려 간다.
D3DRMCALLBACK_POSTORDER － IDirect3DRMFrame3::Move 가 계층을 더듬어 갈 때, 프레임의 콜백 함수는, 아이 프레임을 더듬은 후에 불려 간다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는,IDirect3DRMFrame2::AddMoveCallback2를 치환한다. 각각의 프레임에 대한 복수의 콜백 함수는, 그러한 함수의 생성순서에 불려 간다.

참조

IDirect3DRMFrame3::Move , IDirect3DRMFrame3::DeleteMoveCallback

IDirect3DRMFrame3::AddRotation

IDirect3DRMFrame3

(rvX, rvY, rvZ)(을)를 중심으로 하는 회전을,rvTheta로 지정된 라디안으로 추가한다.

구문

HRESULT AddRotation(
  D3DRMCOMBINETYPE rctCombine,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ,
  D3DVALUE rvTheta
  );

파라미터

rctCombine
새로운 회전을 현재의 임의의 프레임 변환과 결합하는 방법을 지정하는D3DRMCOMBINETYPE 열거형의 멤버.
rvX, rvY, rvZ
회전축.
rvTheta
라디안 단위의 회전각.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

지정의 회전은, 이IDirect3DRMFrame3 인터페이스가 식별하는 프레임에 대한 행렬만을 변경한다. 이 메소드는, 렌더링 마다 행렬을 변경하는IDirect3DRMFrame3::SetRotation 과는 달리 프레임을 한 번 밖에 변경하지 않는다.

참조

「3 D변환」, IDirect3DRMFrame3::SetRotation

IDirect3DRMFrame3::AddScale

IDirect3DRMFrame3

프레임의 로컬 변환을 (rvX, rvY, rvZ)로 스케일링 한다.

구문

HRESULT AddScale(
  D3DRMCOMBINETYPE rctCombine,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ
  );

파라미터

rctCombine
새로운 스케일을 현재의 임의의 프레임 변환과 결합하는 방법을 지정하는D3DRMCOMBINETYPE 열거형의 멤버.
rvX, rvY, rvZ
x, y, z의 각방향의 스케일 팩터.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

지정의 변환은, 이IDirect3DRMFrame3 인터페이스가 식별하는 프레임에 대한 행렬만을 변경한다.

참조

「3 D변환」

IDirect3DRMFrame3::AddTransform

IDirect3DRMFrame3

rctCombine와rmMatrix에 의해 지정된 아핀 변환으로 프레임의 로컬 좌표를 변환한다.

구문

HRESULT AddTransform(
  D3DRMCOMBINETYPE rctCombine,
  D3DRMMATRIX4D rmMatrix
  );

파라미터

rctCombine
새로운 변환을 현재의 임의의 변환과 결합하는 방법을 지정하는D3DRMCOMBINETYPE 열거형의 멤버.
rmMatrix
결합되는 변환 행렬을 정의하는D3DRMMATRIX4D 배열의 멤버.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

4×4 행렬이 주어졌지만, 변환이 아핀 변환이기 위해서(때문에)는, 마지막 열은[0 0 0 1]의 전치가 아니면 안된다.

지정의 변환은, 이IDirect3DRMFrame3 인터페이스가 식별하는 프레임에 대한 행렬만을 변경한다.

참조

「3 D변환」

IDirect3DRMFrame3::AddTranslation

IDirect3DRMFrame3

프레임의 로컬 좌표계에 (rvX, rvY, rvZ)에 의한 평행이동을 추가한다.

구문

HRESULT AddTranslation(
  D3DRMCOMBINETYPE rctCombine,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ
  );

파라미터

rctCombine
새로운 변환을 현재의 임의의 변환과 결합하는 방법을 지정하는D3DRMCOMBINETYPE 열거형의 멤버.
rvX, rvY, rvZ
x, y, z의 각방향에서의 위치 변화를 정의한다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

지정의 변환은, 이IDirect3DRMFrame3 인터페이스가 식별하는 프레임에 대한 행렬만을 변경한다.

참조

「3 D변환」

IDirect3DRMFrame3::AddVisual

IDirect3DRMFrame3

비주얼 오브젝트를 프레임에 추가한다.

구문

HRESULT AddVisual(
  LPUNKNOWN lpD3DRMVisual
  );

파라미터

lpD3DRMVisual
프레임에 추가하는 비주얼 오브젝트를 나타내는 변수에의 포인터.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

비주얼 오브젝트에는, 메쉬, 프로그래시브 메쉬, 텍스쳐, 그림자, 유저 비주얼, 및 3D DirectX 변환 오브젝트가 포함된다. 비주얼 오브젝트가 프레임에 추가되면(자), 비주얼 오브젝트는, 프레임이 뷰중에 있는 경우에 가시 상태가 된다. 프레임은 비주얼 오브젝트를 참조한다.

IDirect3DRMFrame3::DeleteChild

IDirect3DRMFrame3

계층으로부터 프레임을 삭제한다. 그 프레임이 참조되어 있지 않으면, 아이 프레임, 조명, 및 메쉬의 모든 것이 함께 파기된다.

구문

HRESULT DeleteChild(
  LPDIRECT3DRMFRAME3 lpChild
  );

파라미터

lpChild
자식으로 사용하는 Direct3DRMFrame 오브젝트의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

「계층」

IDirect3DRMFrame3::DeleteLight

IDirect3DRMFrame3

프레임으로부터 조명을 삭제해, 프레임이 참조되는 것이 없으면 파기한다. 조명이 프레임으로부터 삭제되면(자), 그 프레임이 있던 장면안의 메쉬에 이후 영향을 줄 것은 없다.

구문

HRESULT DeleteLight(
  LPDIRECT3DRMLIGHT lpD3DRMLight
  );

파라미터

lpD3DRMLight
삭제하는 Direct3DRMLight 오브젝트를 나타내는 변수의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMFrame3::DeleteMoveCallback

IDirect3DRMFrame3

AddMoveCallback 에 의해 추가된 프레임 이동 콜백 함수를 삭제한다.

구문

HRESULT DeleteMoveCallback(
  D3DRMFRAME3MOVECALLBACK d3drmFMC,
  VOID *lpArg
  );

파라미터

d3drmFMC
어플리케이션 정의D3DRMFRAME3MOVECALLBACK 콜백 함수.
lpArg
콜백 함수에게 건네진 어플리케이션 정의 데이터.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMFrame3::AddMoveCallback , IDirect3DRMFrame3::Move

IDirect3DRMFrame3::DeleteVisual

IDirect3DRMFrame3

비주얼 오브젝트를 프레임으로부터 삭제해, 이후 참조되지 않는 경우에는 파기한다.

구문

HRESULT DeleteVisual(
  LPUNKNOWN lpD3DRMVisual
  );

파라미터

lpD3DRMVisual
삭제하는 Direct3DRMVisual 오브젝트를 나타내는 변수의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMFrame3::GetAxes

IDirect3DRMFrame3

IDirect3DRMFrame3::SetOrientation 메소드에 공급될 방향 벡터 (rvDx, rvDy, rvDz)와 업 벡터 (rvUx, rvUy, rvUz)와 정렬하는 벡터를 취득한다.

구문

HRESULT GetAxes(
  LPD3DVECTOR dir,
  LPD3DVECTOR up
  );

파라미터

dir
프레임의 z축. 디폴트는 (0,0,1)이다.
up
프레임의 y축. 디폴트는 (0,1,0)이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는,IDirect3DRMFrame3::SetAxes 와 함께 일해, 왼손 좌표계와 오른손 좌표계의 양쪽 모두를 지원한다. SetAxes는, 부의 z축이 오브젝트의 전면을 나타내도록(듯이) 지정하는 것을 가능하게 한다.

참조

IDirect3DRMFrame3::SetAxes , IDirect3DRMFrame3::GetInheritAxes , IDirect3DRMFrame3::SetInheritAxes

IDirect3DRMFrame3::GetBox

IDirect3DRMFrame3

DIRECT3DRMFRAME2 오브젝트를 포함한 경계 박스를 취득한다. 경계 박스는, 각 차원에서의 최소 및 최대의모델 좌표를 준다.

구문

HRESULT GetBox(
  D3DRMBOX *lpD3DRMBox
  );

파라미터

lpD3DRMBox
경계 박스 좌표가 세트 되는D3DRMBOX 구조체의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 유효한 경계 박스가 벌써 프레임으로 설정되어 있지 않은 경우는D3DRMERR_BOXNOTSET 를 돌려준다. 그 외의 가능한 반환값의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, 계층적 선별에 대한 프레임 위에의 경계 박스를 지원 한다. 유효한 경계 박스는,IDirect3DRMFrame3::SetBox 로 프레임상으로 설정할 필요가 있다. 경계 박스를 enable로 하려면 ,IDirect3DRMFrame3::SetBoxEnable 메소드를 사용해 enable 플래그를 TRUE로 할 필요가 있다. 디폴트로, 박스 enable 플래그는 FALSE이다. 디폴트의 경계 박스는 없다.

참조

IDirect3DRMFrame3::SetBox , IDirect3DRMFrame3::SetBoxEnable , IDirect3DRMFrame3::GetBoxEnable

IDirect3DRMFrame3::GetBoxEnable

IDirect3DRMFrame3

경계 박스가 이 Direct3DRMFrame2 오브젝트에 대해서, enable가 되어 있는지 어떤지를 판별하는 플래그를 취득한다.

구문

BOOL GetBoxEnable( );

반환값

경계 박스가 enable이면 TRUE, enable가 아니면 FALSE를 돌려준다.

주의

경계 박스를 enable로 하려면 ,IDirect3DRMFrame3::SetBoxEnable 메소드를 사용해 enable 플래그를 TRUE로 할 필요가 있다. 디폴트에서는, 박스 enable 플래그는 FALSE이다.

참조

IDirect3DRMFrame3::SetBoxEnable IDirect3DRMFrame3::GetBox , IDirect3DRMFrame3::SetBox

IDirect3DRMFrame3::GetChildren

IDirect3DRMFrame3

Direct3DRMFrameArray 오브젝트의 형식에서, 아이 프레임의 리스트를 취득한다.

구문

HRESULT GetChildren(
  LPDIRECT3DRMFRAMEARRAY *lplpChildren
  );

파라미터

lplpChildren
이 호출이 성공했을 경우에, 유효한 Direct3DRMFrameArray 포인터로 초기화되는 포인터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

DIRECT3DRMFRAMEARRAY , 「계층」

IDirect3DRMFrame3::GetColor

IDirect3DRMFrame3

프레임의 색을 취득한다.

구문

D3DCOLOR GetColor( );

반환값

Direct3DRMFrame2 오브젝트의 색을 돌려준다.

참조

IDirect3DRMFrame3::SetColor

IDirect3DRMFrame3::GetHierarchyBox

IDirect3DRMFrame3

이 Direct3DRMFrame2 오브젝트를 루트로 하는 계층안의 모든 기하 도형을 포함한 경계 박스를 계산한다.

구문

HRESULT GetHierarchyBox(
  D3DRMBOX *lpD3DRMBox
  );

파라미터

lpD3DRMBox
경계 박스의 좌표가 세트 되는D3DRMBOX 구조체의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMFrame3::GetBox , IDirect3DRMFrame3::SetBox , IDirect3DRMFrame3::SetBoxEnable , IDirect3DRMFrame3::GetBoxEnable

IDirect3DRMFrame3::GetInheritAxes

IDirect3DRMFrame3

프레임의 축이 친프레임으로부터 계승한 것일지 어떨지를 나타내는 플래그를 취득한다.

구문

BOOL GetInheritAxes( );

반환값

프레임이 축을 계승하는(디폴트)와 TRUE, 축을 계승하지 않으면 FALSE를 돌려준다.

주의

디폴트에서는, 축은 부모로부터 계승한 것이다. 프레임에 부모로부터의 계승과 설정되어 있어, 부모가 존재하지 않으면, 프레임은 디폴트축(방향=(0,0,1) 업=(0,1,0))을 가지는 부모로부터 계승한 것처럼 동작한다.

이 메소드 및IDirect3DRMFrame3::SetInheritAxes 메소드는, 계층 루트로 설정되는 축의 단일의 방침을 허락한다.

참조

IDirect3DRMFrame3::SetInheritAxes , IDirect3DRMFrame3::GetAxes , IDirect3DRMFrame3::SetAxes

IDirect3DRMFrame3::GetLights

IDirect3DRMFrame3

Direct3DRMLightArray 오브젝트의 형식에서 프레임중의 조명의 리스트를 취득한다.

구문

HRESULT GetLights(
  LPDIRECT3DRMLIGHTARRAY *lplpLights
  );

파라미터

lplpLights
이 호출이 성공했을 경우에, 유효한 Direct3DRMLightArray 포인터로 초기화되는 포인터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMLightArray

IDirect3DRMFrame3::GetMaterial

IDirect3DRMFrame3

Direct3DRMFrame2 오브젝트의 머트리얼을 취득한다.

구문

HRESULT GetMaterial(
  LPDIRECT3DRMMATERIAL2 *lplpMaterial
  );

파라미터

lplpMaterial
프레임에 적용되는 Direct3DRMMaterial 오브젝트에의 포인터가 세트 되는 변수의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMFrame3::SetMaterial

IDirect3DRMFrame3::GetMaterialMode

IDirect3DRMFrame3

프레임의 머트리얼 모드를 취득한다.

구문

D3DRMMATERIALMODE GetMaterialMode( );

반환값

현재의 머트리얼 모드를 지정하는D3DRMMATERIALMODE 열거형의 멤버를 돌려준다.

참조

IDirect3DRMFrame3::SetMaterialMode

IDirect3DRMFrame3::GetOrientation

IDirect3DRMFrame3

지정의 참조 프레임을 기준으로 하는 프레임의 방향을 취득한다.

구문

HRESULT GetOrientation(
  LPDIRECT3DRMFRAME lpRef,
  LPD3DVECTOR lprvDir,
  LPD3DVECTOR lprvUp
  );

파라미터

lpRef
참조에 사용되는 Direct3DRMFrame 오브젝트를 나타내는 변수의 주소. 이것은 NULL로 할 수 있다. NULL의 경우, 메소드는 참조 프레임의 변환 매트릭스는 아니고, 로컬의 변환 매트릭스를 사용한다.
lprvDir, lprvUp
D3DVECTOR 구조체의 주소. 구조체에는, 각각 프레임의 z축 및 y축의 정규화된 방향이 세트 된다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMFrame3::SetOrientation

IDirect3DRMFrame3::GetMaterialOverride

IDirect3DRMFrame3

머트리얼 속성에 대한 현재의 속성마다의 오버라이드(override) 설정을 취득한다.

구문

HRESULT GetMaterialOverride(
  LPD3DRMMATERIALOVERRIDE lpdmOverride);

파라미터

lpdmOverride
오버라이드(override) 하는 프로퍼티를 기술하는D3DRMMATERIALOVERRIDE 구조체에의 포인터.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

텍스쳐가 오버라이드(override)안에 있는 경우, 그참조 카운트는 되돌려지기 전에 (AddRef로) 인크리먼트(increment) 되고 있어 종료시에 텍스쳐를 릴리스 할 필요가 있다. 이 때문에, 텍스쳐 오버라이드(override)를 적용하는 경우, 릴리스를 잊지 않는 것.

참조

SetMaterialOverride

IDirect3DRMFrame3::GetParent

IDirect3DRMFrame3

현재의 프레임의 친프레임을 취득한다.

구문

HRESULT GetParent(
  LPDIRECT3DRMRAME3 *lplpParent
  );

파라미터

lplpParent
프레임의 부모를 나타내는 Direct3DRMFrame 오브젝트에의 포인터가 세트 된 포인터의 주소. 현재의 프레임이 루트인 경우, 메소드의 귀가시에, 이 포인터는 NULL가 된다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMFrame3::GetPosition

IDirect3DRMFrame3

지정의 참조 프레임을 기준으로 하는 프레임의 위치를 취득한다. 즉, 참조 프레임으로부터의 프레임의 거리를 취득한다. 거리는, 직선적인 값은 아니고, 벡터로서lprvPos파라미터에 저장 된다.

구문

HRESULT GetPosition(
  LPDIRECT3DRMFRAME3 lpRef,
  LPD3DVECTOR lprvPos
  );

파라미터

lpRef
참조 프레임으로서 사용되는 Direct3DRMFrame 오브젝트를 나타내는 변수의 주소. 이것은 NULL로 할 수 있다. NULL의 경우, 메소드는 참조 프레임의 변환 매트릭스는 아니고, 로컬의 변환 매트릭스를 사용한다.
lprvPos
프레임의 위치가 세트 되는D3DVECTOR 구조체의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMFrame3::SetPosition

IDirect3DRMFrame3::GetRotation

IDirect3DRMFrame3

지정의 참조 프레임을 기준으로 하는 프레임의 회전을 취득한다.

구문

HRESULT GetRotation(
  LPDIRECT3DRMFRAME3 lpRef,
  LPD3DVECTOR lprvAxis,
  LPD3DVALUE lprvTheta
  );

파라미터

lpRef
참조 프레임으로서 사용되는 Direct3DRMFrame 오브젝트를 나타내는 변수의 주소. 이것은 NULL로 할 수 있다. NULL의 경우, 메소드는 참조 프레임의 변환 매트릭스는 아니고, 로컬의 변환 매트릭스를 사용한다.
lprvAxis
프레임의 회전축이 세트 되는D3DVECTOR 구조체의 주소.
lprvTheta
라디안 단위의 프레임의 회전이 되는 변수의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMFrame3::SetRotation , 「변환」

IDirect3DRMFrame3::GetScene

IDirect3DRMFrame3

지정의 프레임을 포함한 계층의루트 프레임을 취득한다.

구문

HRESULT GetScene(
  LPDIRECT3DRMFRAME3 lplpRoot
  );

파라미터

lplpRoot
신의 루트 프레임을 나타내는 Direct3DRMFrame 오브젝트에의 포인터가 세트 되고 있는 포인터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMFrame3::GetSceneBackground

IDirect3DRMFrame3

장면의 배경색을 취득한다.

구문

D3DCOLOR GetSceneBackground( );

반환값

색을 돌려준다.

IDirect3DRMFrame3::GetSceneBackgroundDepth

IDirect3DRMFrame3

장면의 현재의 배경 깊이 버퍼를 취득한다.

구문

HRESULT GetSceneBackgroundDepth(
  LPDIRECTDRAWSURFACE *lplpDDSurface
  );

파라미터

lplpDDSurface
현재의 배경 깊이 버퍼를 나타내는 DirectDraw 표면의 주소로 초기화되는 포인터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMFrame3::SetSceneBackgroundDepth

IDirect3DRMFrame3::GetSceneFogColor

IDirect3DRMFrame3

장면의 포그(안개:fog)색을 취득한다.

구문

D3DCOLOR GetSceneFogColor( );

반환값

포그(안개:fog)색을 돌려준다.

IDirect3DRMFrame3::GetSceneFogEnable

IDirect3DRMFrame3

현재 이 장면에 대해서 포그(안개:fog)가 enable 되고 있는지 어떤지를 돌려준다.

구문

BOOL GetSceneFogEnable( );

반환값

포그(안개:fog)가 enable 되고 있으면 TRUE, enable되어 있지 않으면 FALSE를 돌려준다.

IDirect3DRMFrame3::GetSceneFogMethod

IDirect3DRMFrame3

현재의 포그(안개:fog) 메소드를 취득한다.

구문

HRESULT GetSceneFogMethod(
  LPDWORD lpdwFlags);

파라미터

lpdwFlags
현재의 포그(안개:fog) 메소드를 받는 DWORD에의 포인터. 현재 정의되고 있는 플래그는, 다음과 같다.
D3DRMFOGMETHOD_ANY
Direct3DRM가 적용 가능한 메소드를 선택하는 것을 나타낸다.
D3DRMFOGMETHOD_VERTEX
버텍스 포그(안개:fog)를 사용한다.
D3DRMFOGMETHOD_TABLE
테이블 포그(안개:fog)를 사용한다.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_BADVALUE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMFrame3::GetSceneFogMode

IDirect3DRMFrame3

이 장면에 대한 현재의 포그(안개:fog) 모드를 돌려준다.

구문

D3DRMFOGMODE GetSceneFogMode( );

반환값

현재의 포그(안개:fog) 파라미터를 지정하는D3DRMFOGMODE 열거형의 멤버를 돌려준다.

IDirect3DRMFrame3::GetSceneFogParams

IDirect3DRMFrame3

이 장면에 대한 현재의 포그(안개:fog) 파라미터를 취득한다.

구문

HRESULT GetSceneFogParams(
  D3DVALUE *lprvStart,
  D3DVALUE *lprvEnd,
  D3DVALUE *lprvDensity
  );

파라미터

lprvStart, lprvEnd, lprvDensity
포그(안개:fog) 시작, 종료 및 밀도값이 되는 변수의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMFrame3::GetSortMode

IDirect3DRMFrame3

아이 프레임을 처리하는데 사용되는 소트 모드를 취득한다.

구문

D3DRMSORTMODE GetSortMode( );

반환값

소트 모드를 지정하는D3DRMSORTMODE 열거형의 멤버를 돌려준다.

참조

IDirect3DRMFrame3::SetSortMode

IDirect3DRMFrame3::GetTexture

IDirect3DRMFrame3

지정 프레임의 텍스쳐를 취득한다.

구문

HRESULT GetTexture(
  LPDIRECT3DRMTEXTURE3 *lplpTexture
  );

파라미터

lplpTexture
프레임의 텍스쳐를 나타내는 Direct3DRMTexture 오브젝트의 주소가 세트 되고 있는 포인터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMFrame3::SetTexture

IDirect3DRMFrame3::GetTransform

IDirect3DRMFrame3

프레임의 로컬 변환을 4×4 아핀 행렬로서 취득한다.

구문

HRESULT GetTransform(
  LPDIRECT3DRMFRAME lpRefFrame,
  D3DRMMATRIX4D rmMatrix);

파라미터

lpRefFrame
이 호출을 위해서(때문에) 장면의 루트로서 기능하는 프레임. 이 인수가 NULL의 경우, 현재의 루트 프레임 (GetScene 가 돌려주는 프레임)이 사용된다.
rmMatrix
프레임의 변환이 세트 되는D3DRMMATRIX4D배열. 이것은, 배열이므로 값은 주소가 된다.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다. 이 메소드는,lpRefFrame파라미터를 추가하는 것으로IDirect3DRMFrame::GetTransform를 확장한다.

참조

「3 D변환」

IDirect3DRMFrame3::GetTraversalOptions

IDirect3DRMFrame3

현재의 프레임의 횡단 상태를 취득한다.

구문

HRESULT GetTraversalOptions(
  LPDWORD lpdwFlags);

파라미터

lpdwFlags
현재의 유효 상태가 세트 되는 DWORD에의 포인터. 현재 정의되고 있는 플래그는, 다음과 같다.
D3DRMFRAME_RENDERENABLE
이 프레임 또는 그 아이 프레임을 렌더링 하는 것을 나타낸다.
D3DRMFRAME_PICKENABLE
이 프레임 또는 그 아이 프레임중의, 임의의 비주얼을 픽 하는 것을 나타낸다.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_BADVALUE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMFrame3::GetVelocity

IDirect3DRMFrame3

지정의 참조 프레임을 기준으로 하는 프레임의 속도를 취득한다. 속도는, 틱 당의 단위로 지정된다. 상세한 것에 대하여는,IDirect3DRM3::Tick 를 참조할것.

구문

HRESULT GetVelocity(
  LPDIRECT3DRMFRAME3 lpRef,
  LPD3DVECTOR lprvVel,
  BOOL fRotVel
  );

파라미터

lpRef
참조 프레임으로서 사용되는 Direct3DRMFrame 오브젝트를 나타내는 변수의 주소. 이것은 NULL로 할 수 있다. NULL의 경우, 메소드는 참조 프레임의 변환 매트릭스는 아니고, 로컬의 변환 매트릭스를 사용한다.
lprvVel
프레임의 속도가 세트 되는D3DVECTOR 구조체의 주소.
fRotVel
직선 속도를 취득할 경우에, 오브젝트의 회전 속도를 고려할지 어떨지를 지정하는 플래그. 이 파라미터가 TRUE의 경우, 오브젝트의 회전 속도가 계산에 포함된다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMFrame3::SetVelocity

IDirect3DRMFrame3::GetVisuals

IDirect3DRMFrame3

프레임중의 비주얼의 리스트를 취득한다.

구문

HRESULT GetVisuals(
  LPDWORD pdwNumVisuals, LPUNKNOWN *ppUnk
  );

파라미터

pdwNumVisuals
돌려주어질 예정의 벡터수를 포함한 DWORD값에의 포인터. ppUnk가 NULL라면,GetVisuals는 프레임에 포함되는 비주얼수를 돌려준다. ppUnk가 NULL가 아닌 경우, DWORD값은 실제로 꺼내진 비주얼수를 받는다.
ppUnk
초기화되는 비주얼의 배열에의 포인터. 이것을 NULL에 세트 하면,GetVisuals는 프레임에 포함되는 비주얼수를 돌려주게 된다. 그렇지 않은 경우, 이것은pdwNumVisuals에 대해서 유저가 할당한 공간의 배열이 된다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMFrame3::GetZbufferMode

IDirect3DRMFrame3

Z버퍼 모드를 취득한다. 즉, Z버퍼링이 enable 또는 디세블일지 어떨지를 확인한다.

구문

D3DRMZBUFFERMODE GetZbufferMode( );

반환값

D3DRMZBUFFERMODE 열거형의 멤버의 하나를 돌려준다.

참조

IDirect3DRMFrame3::SetZbufferMode

IDirect3DRMFrame3::InverseTransform

IDirect3DRMFrame3

월드 좌표의lprvSrc파라미터중의 벡터를모델 좌표로 변환해, 그 결과를lprvDst파라미터에 돌려준다.

구문

HRESULT InverseTransform(
  D3DVECTOR *lprvDst,
  D3DVECTOR *lprvSrc
  );

파라미터

lprvDst
변환의 결과가 세트 되는D3DVECTOR 구조체의 주소.
lprvSrc
변환의 소스인D3DVECTOR구조체의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMFrame3::Transform , 「3 D변환」

IDirect3DRMFrame3::InverseTransformVectors

IDirect3DRMFrame3

벡터의 배열을 월드로부터 모델 공간으로 변환한다.

구문

HRESULT InverseTransformVectors
(LPDIRECT3DRMFRAME3 lpRefFrame,
DWORD dwNumVectors,
LPD3DVECTOR	lpDstVectors,
LPD3DVECTOR	lpSrcVectors);

파라미터

lpRefFrame
이 호출을 위해서(때문에) 장면의 루트로서 사용되는 프레임. 이 인수가 NULL의 경우, 현재의 루트 프레임 (GetScene가 돌려주는 프레임)이 사용된다.
dwNumVectors
좌표를 변환할 필요가 있는 벡터수.
lpDstVectors
변환의 출력처.
lpSrcVectors
변환하는 벡터의 배열.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMFrame3::Load

IDirect3DRMFrame3

Direct3DRMFrame2 오브젝트를 로드한다.

구문

HRESULT Load(
  LPVOID lpvObjSource,
  LPVOID lpvObjID,
  D3DRMLOADOPTIONS d3drmLOFlags,
  D3DRMLOADTEXTURE3CALLBACK d3drmLoadTextureProc,
  LPVOID lpArgLTP
  );

파라미터

lpvObjSource
로드하는 오브젝트의 소스. 이 소스는,d3drmLOFlags파라미터로 지정되고 있는 소스 플래그에 따라, 파일, 리소스, 메모리 블록, 또는 스트림의 어느 쪽인가에 할 수 있다.
lpvObjID
로드하는 오브젝트의 이름 또는 위치. 이 파라미터의 사용은,d3drmLOFlags파라미터로 지정되고 있는 식별 플래그에 의존한다. D3DRMLOAD_BYPOSITION 플래그가 지정되고 있으면, 이 파라미터는, 파일중의 오브젝트의 순서를 주는DWORD값에의 포인터가 된다. 이 파라미터는 NULL로 할 수 있다.
d3drmLOFlags
로드 옵션을 기술하는D3DRMLOADOPTIONS 형의 값.
d3drmLoadTextureProc
특수한 formatting를 요구하는 오브젝트에 의해 사용되는, 임의의 텍스쳐를 로드하기 위해서(때문에) 불려 가는D3DRMLOADTEXTURE3CALLBACK 콜백 함수. 이 파라미터는 NULL로 할 수 있다.
lpArgLTP
D3DRMLOADTEXTURE3CALLBACK 콜백 함수에게 건네지는 어플리케이션 정의 데이터에의 포인터.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

디폴트에서는, 이 메소드는,lpvObjSource파라미터로 지정되고 있는 파일중의 최초의 프레임 계층을 로드한다. 이 메소드를 호출한 프레임은, 새로운 프레임 계층의 부모로서 사용된다. 디폴트에서는, 퍼스펙티브 보정이온이다.

IDirect3DRMFrame3::LookAt

IDirect3DRMFrame3

지정의 참조 프레임을 기준으로서 지정의 제약에 의해 회전을 잠근 상태로 프레임을 대상의 프레임에 직면시킨다.

구문

HRESULT LookAt(
  LPDIRECT3DRMFRAME3 lpTarget,
  LPDIRECT3DRMFRAME3 lpRef,
  D3DRMFRAMECONSTRAINT rfcConstraint
  );

파라미터

lpTarget
대상으로 해 사용되는 Direct3DRMFrame 오브젝트를 나타내는 변수의 주소.
lpRef
참조 프레임으로서 사용되는 Direct3DRMFrame 오브젝트를 나타내는 변수의 주소. 이것은 NULL로 할 수 있다. NULL의 경우, 메소드는 참조 프레임의 변환 매트릭스는 아니고, 로컬의 변환 매트릭스를 사용한다.
rfcConstraint
D3DRMFRAMECONSTRAINT 열거형의 멤버로, 축회전을 제약하도록(듯이) 지정한다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMFrame3::Move

IDirect3DRMFrame3

회전과 속도를 지정의 계층의 모든 프레임에 적용한다.

구문

HRESULT Move(
  D3DVALUE delta
  );

파라미터

delta
직선과 회전 속도에 대한 변화량. 각 요소에 있어서의 변경은, 그 요소의 속도×delta에 동일하다. 이러한 한편 또는 양쪽 모두의 속도는, 임의의 프레임을 기점으로서 설정할 수가 있지만, 시스템은, 자동적으로 델타 시간을 적용하므로, 친프레임을 기점으로 한 속도로 변환한다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.


IDirect3DRMFrame3 메소드 N~Z

이 항은,IDirect3DRMFrame3 인터페이스의 메소드 가운데, 메소드명이 N로부터 Z의 것을 취하는 레퍼런스 페이지이다.

IDirect3DRMFrame3::RayPick

IDirect3DRMFrame3

이 Direct3DRMFrame3 오브젝트를 기점으로서 계층을 검색해,lpRefFrame파라미터에 의해 지정되는 좌표 공간에서, 임의의 비주얼과dvPosition,dvDirection파라미터에 의해 지정되는 광선과의 교차 부분을 계산한다.

구문

HRESULT RayPick(
  LPDIRECT3DRMFRAME3 lpRefFrame,
  LPD3DRMRAY ray,
  DWORD dwFlags,
  LPD3DRMPICKED2ARRAY *lplpPicked2Array
  );

파라미터

lpRefFrame
광선을 저장 하는 Direct3DRMFrame3 오브젝트의 주소.
ray
2개의 D3DVECTOR 구조체를 포함한D3DRMRAY 구조체에의 포인터. 최초의 D3DVECTOR 구조체는, 광선의 벡터 방향이다. 두번째의 D3DVECTOR 구조체는, 광선의 원점의 위치이다.
dwFlags
이하의 몇개의 값이 된다.
D3DRMRAYPICK_ONLYBOUNDINGBOXES － 계층안의 비주얼의 경계 박스가 있는 교차 부분만큼이 돌려주어진다. 정확한 면의 교차는 체크하지 않는다.
D3DRMRAYPICK_IGNOREFURTHERPRIMITIVES － 광선에 교차하는 가장 가까운 비주얼만이 돌려주어진다. 지금까지의 검색중에 발견된 가장 가까운 것보다 멀리 있는 비주얼을 무시한다.
D3DRMRAYPICK_INTERPOLATEUV － 텍스쳐 좌표를 보간 한다.
D3DRMRAYPICK_INTERPOLATECOLOR － 색을 보간 한다.
D3DRMRAYPICK_INTERPOLATENORMAL － 법선을 보간 한다.
lplpPicked2Array
IDirect3DRMPicked2Array 인터페이스에의 유효한 포인터로 초기화되는 포인터의 주소. IDirect3DRMPicked2Array::GetPick 메소드를 사용해, 비주얼 오브젝트,IDirect3DRMFrameArray 인터페이스, 및D3DRMPICKDESC2 구조체를 취득한다. 프레임의 배열은 계층을 통과하는 패스로, 광선에 교차한 비주얼 오브젝트에 도달한다. D3DRMPICKDESC2 구조체에는, 면이나 그룹의 식별자, 픽의 위치, 버텍스의 수평 및 수직 텍스쳐 좌표, 버텍스의 법선 및 교차한 오브젝트의 색이 포함된다.

D3DRMRAYPICK_ONLYBOUNDINGBOXES를 지정 하면,D3DRMPICKDESC2 구조체의 텍스쳐, 법선 및 색데이터는 무효가 된다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

플래그에는, 최적화 플래그와 보간 플래그의 2종류가 있다. 최적화 플래그는, 검색을 제한할 수가 있어 따라 그것을 고속으로 한다. 보간 플래그는, 원시적으로 맞닥뜨렸을 때에 무엇을 보간해야할 것인가 지정한다. 3개의 보간 선택사항은, 색, 법선 및 텍스쳐 좌표이다.

광선은, 참조 프레임 좌표 공간에서 지정된다(lpRefFrame가 가리킨다). 참조 프레임이 NULL의 경우에는, 광선은,월드 좌표로 지정된다.

IDirect3DRMFrame3::Save

IDirect3DRMFrame3

지정한 파일에 Direct3DRMFrame2 오브젝트를 보존한다.

구문

HRESULT Save(
  LPCSTR lpFilename,
  D3DRMXOFFORMAT d3dFormat,
  D3DRMSAVEOPTIONS d3dSaveFlags
  );

파라미터

lpFilename
생성 한 파일의 이름을 지정하는 주소. 이 파일은,. x파일명 확장을 가지지 않으면 안 된다.
d3dFormat
D3DRMXOFFORMAT 열거형으로부터 D3DRMXOF_TEXT의 값.
d3dSaveFlags
보존 옵션을 기술하는D3DRMSAVEOPTIONS 형의 값.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMFrame3::SetAxes

IDirect3DRMFrame3

IDirect3DRMFrame3::SetOrientation 벡터를 변환하는 좌표 공간을 정의하는 벡터를 설정한다.

구문

HRESULT SetAxes(
  D3DVALUE dx,
  D3DVALUE dy,
  D3DVALUE dz,
  D3DVALUE ux,
  D3DVALUE uy,
  D3DVALUE uz
  );

파라미터

dx, dy, dz
프레임의 z축. 디폴트는(0,0,1)이다.
ux, uy, uz
프레임의 y축. 디폴트는(0,1,0)이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, 왼손 좌표계와 오른손 좌표계의 양쪽 모두를 지원한다. 또, 부의 z축이 오브젝트의 전면을 나타내도록(듯이) 지정하는 일도 가능하게 한다.

IDirect3DRMFrame3::SetOrientation 방향 벡터(rvDx, rvDy, rvDz)와 업 벡터(rvUx, rvUy, rvUz)는,SetAxes벡터의 값에 따라 변환된다.

IDirect3DRMFrame3::SetInheritAxes 로 지정되고 있도록(듯이), 축은 아이 프레임에 의해 계승된다.

참조

IDirect3DRMFrame3::GetAxes , IDirect3DRMFrame3::GetInheritAxes , IDirect3DRMFrame3::SetInheritAxes

IDirect3DRMFrame3::SetBox

IDirect3DRMFrame3

경계 박스 테스트로 사용하는 박스를 설정한다. 경계 박스가 유효하기 때문에 는, 최소 x는 최대 x이하가 아니면 안되어, 최소 y는 최대 y이하가 아니면 안되어, 또 최소 z는 최대 z이하가 아니면 안된다.

구문

HRESULT SetBox(
  D3DRMBOX *lpD3DRMBox
  );

파라미터

lpD3DRMBox
경계 박스 좌표를 포함한D3DRMBOX 구조체의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, 계층적 선별에 대한 프레임 위에의 경계 박스를 지원 한다. 경계 박스를 enable로 하려면 ,IDirect3DRMFrame3::SetBoxEnable 메소드를 사용해, enable 플래그에 TRUE를 세트 해야 한다. 디폴트에서는, 박스 enable 플래그는 FALSE이다.

참조

IDirect3DRMFrame3::GetBox , IDirect3DRMFrame3::SetBoxEnable , IDirect3DRMFrame3::GetBoxEnable

IDirect3DRMFrame3::SetBoxEnable

IDirect3DRMFrame3

이 Direct3DRMFrame2 오브젝트에 대해서, 경계 박스 테스트를 enable 또는 디세블 한다. 경계 박스 테스트를 enable로 하려면 , 유효한 경계 박스가 프레임에 벌써 설정되어 있지 않으면 안 된다.

구문

HRESULT SetBoxEnable(
  BOOL bEnableFlag
  );

파라미터

bEnableFlag
플래그는, 경계 박스가 enable인가 어떤가를 지정한다. TRUE는, 경계 박스를 enable로 한다. 경계 박스가 enable가 아니면 FALSE. 디폴트는 FALSE이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

경계 박스를 enable로 하려면 , 이 메소드를 사용해 enable 플래그에 TRUE를 세트 해야 한다. 디폴트에서는, 박스 enable 플래그는 FALSE이다.

경계 박스 테스트는, 이하와 같이 실시한다. 렌더링시에는, 경계 박스는 모델 공간으로 변환해,절두체와의 교차 부분이 없는가 조사한다. 박스 전체가 절두체의 밖에 있는 경우, 프레임이나 아이 프레임에 있는 비주얼의 렌더링은 실시하지 않는다. 그 이외의 경우는, 보통의 렌더링을 계속한다.

{0,0,0,0}의 박스로 경계 박스 테스트를 enable 하면, 프레임은 전혀 렌더링 되지 않는다.

참조

IDirect3DRMFrame3::GetBoxEnable , IDirect3DRMFrame3::GetBox , IDirect3DRMFrame3::SetBox

IDirect3DRMFrame3::SetColor

IDirect3DRMFrame3

프레임의 색을 설정한다. 이 색은,D3DRMMATERIALMODE 열거형이 D3DRMMATERIAL_FROMFRAME인 경우에, 프레임중의 메쉬에 대해서 사용된다.

구문

HRESULT SetColor(
  D3DCOLOR rcColor
  );

파라미터

rcColor
프레임의 새로운 색. 적, 초록, 파랑의 색요소 뿐만이 아니라, 알파 요소도 반드시 세트 한다. 그렇게 하지 않으면 오브젝트가 가시가 되지 않는 것이 있다. RGBA_MAKE DirectX 매크로에 의해, 이러한 값을 지정할 수가 있다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, 컬러 키를DIRECT3DRMFRAMEINTERPOLATOR 오브젝트에 추가하기 위해서도 사용한다.

참조

IDirect3DRMFrame3::GetColor , IDirect3DRMFrame3::SetMaterialMode

IDirect3DRMFrame3::SetColorRGB

IDirect3DRMFrame3

프레임의 색을 설정한다. 이 색은,D3DRMMATERIALMODE 열거형이 D3DRMMATERIAL_FROMFRAME인 경우에, 프레임중의 메쉬에 대해서 사용된다.

구문

HRESULT SetColorRGB(
  D3DVALUE rvRed,
  D3DVALUE rvGreen,
  D3DVALUE rvBlue
  );

파라미터

rvRed, rvGreen, rvBlue
프레임의 새로운 색. 색의 각 요소는, 0.0에서 1.0의 범위에 있을 필요가 있다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, RGB 컬러 키를 DIRECT3DRMFRAMEINTERPOLATOR 오브젝트에 추가하기 위해서도 사용한다.

참조

IDirect3DRMFrame3::SetMaterialMode

IDirect3DRMFrame3::SetInheritAxes

IDirect3DRMFrame3

프레임의 축이 친프레임으로부터 계승한 것일지 어떨지를 지정한다.

구문

HRESULT SetInheritAxes(
  BOOL inherit_from_parent
  );

파라미터

inherit_from_parent
프레임이 그 부모로부터 축을 계승할지 어떨지를 나타내는 플래그. TRUE의 경우, 프레임은 축을 계승한다(디폴트). FALSE의 경우, 프레임은, 축을 계승하지 않는다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

디폴트에서는, 축은 부모로부터 계승한 것이다. 프레임에 부모로부터의 계승과 설정되어 있어, 부모가 존재하지 않는 경우에는, 프레임은, 디폴트축(방향=(0,0,1) 업=(0,1,0))을 가지는 부모로부터 계승한 것처럼 동작한다. 이 메소드는, 계층 루트로 설정되는 축의 단일의 방침을 허락한다.

참조

IDirect3DRMFrame3::GetInheritAxes , IDirect3DRMFrame3::GetAxes , IDirect3DRMFrame3::SetAxes

IDirect3DRMFrame3::SetMaterial

IDirect3DRMFrame3

Direct3DRMFrame2 오브젝트의 머트리얼을 설정한다.

구문

HRESULT SetMaterial(
  LPDIRECT3DRMMATERIAL2 *lplpMaterial
  );

파라미터

lplpMaterial
프레임에 적용되는 Direct3DRMMaterial 오브젝트의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMFrame3::GetMaterial

IDirect3DRMFrame3::SetMaterialMode

IDirect3DRMFrame3

프레임의 머트리얼 모드를 설정한다. 머트리얼 모드는, 프레임과 렌더링 되는 비주얼의 머트리얼 정보의 소스를 결정한다.

구문

HRESULT SetMaterialMode(
  D3DRMMATERIALMODE rmmMode
  );

파라미터

rmmMode
D3DRMMATERIALMODE 열거형의 멤버의 하나.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMFrame3::GetMaterialMode

IDirect3DRMFrame3::SetMaterialOverride

IDirect3DRMFrame3

고유의 머트리얼 속성을 세트 할 수 있도록(듯이) 한다. 예를 들어, 이 메소드는 머트리얼의방사 프로퍼티만을 오버라이드(override) 할 수 있도록(듯이) 한다.

구문

HRESULT SetMaterialOverride(
  LPD3DRMMATERIALOVERRIDE lpdmOverride);

파라미터

lpdmOverride
오버라이드(override) 하는 프로퍼티를 기술하는D3DRMMATERIALOVERRIDE 구조체에의 포인터.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

오버라이드(override)에서는, 항상 계층을 더듬어 모든 것이 오버라이드(override) 된다. 어느 프레임의 방사 프로퍼티를 오버라이드(override) 하는 경우, 계층을 한층 더 더듬어 같은 프로퍼티를 오버라이드(override) 하려고 해도 무시된다. 이 오버라이드(override)은, 고유의 메쉬 위에의 머트리얼 프로퍼티 뿐만이 아니라, 표준 프레임의 오버라이드(override)보다 우선한다. SetMaterial 와SetTexture 등의 오버라이드(override)는, 이 메소드의 동작에 대해서 어떤 효과도 가지지 않는다.

이 메소드는, DirectX version 6.0과 함께 도입되었다.

참조

GetMaterialOverride

IDirect3DRMFrame3::SetOrientation

IDirect3DRMFrame3

z방향이 방향 벡터 [rvDx, rvDy, rvDz] 와 동방향을 가리켜, y방향이 벡터 [rvUx, rvUy, rvUz] 와 동방향을 가리키도록(듯이) 프레임을 정렬한다.

구문

HRESULT SetOrientation(
  LPDIRECT3DRMFRAME3 lpRef,
  D3DVALUE rvDx,
  D3DVALUE rvDy,
  D3DVALUE rvDz,
  D3DVALUE rvUx,
  D3DVALUE rvUy,
  D3DVALUE rvUz
  );

파라미터

lpRef
참조 프레임으로서 사용되는 Direct3DRMFrame 오브젝트를 나타내는 변수의 주소. 이것은 NULL로 할 수 있다. NULL의 경우, 메소드는 참조 프레임의 변환 매트릭스는 아니고, 로컬의 변환 매트릭스를 사용한다.
rvDx, rvDy, rvDz
프레임의 새로운 z축. 벡터의 각 요소는,-1. 0에서 1.0의 범위에 있을 필요가 있다.
rvUx, rvUy, rvUz
프레임의 새로운 y축. 벡터의 각 요소는,-1. 0에서 1.0의 범위에 있을 필요가 있다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

프레임의 디폴트의 방향은, 방향 벡터 [0, 0, 1] 및 업 벡터 [0, 1, 0] 을 가진다.

[rvUx, rvUy, rvUz] 가 [rvDx, rvDy, rvDz] 에 평행한 경우에는, D3DRMERR_BADVALUE 에러값이 돌아온다. 그렇지 않은 경우에는, 건네받은 [rvUx, rvUy, rvUz] 벡터는,[rvDx, rvDy, rvDz] 에 수직인 프레인에 투영 된다.

이 메소드는,Direct3DRMFrameInterpolator 오브젝트에 방향 키를 추가하기 위해서도 사용한다.

DirectX version 6.0 이전으로는,SetOrientation는 스케일과 전단에 대해 고려하고 있지 않았다. 이것은, DirectX version 6.0에서는 수정되고 있다.

다음의 코드 부분은,SetOrientation를 호출해, 디폴트의 방향을 세트 한다. 이것은,IDirect3DRM3::CreateFrame 메소드를 사용해,카메라와 장면 프레임이 벌써 생성 되고 있는 것을 전제로 하고 있다.

LPDIRECT3DRMFRAME3 camera;
LPDIRECT3DRMFRAME3 scene;

if (FAILED(camera->SetOrientation(scene, D3DVAL(0), D3DVAL(0), D3DVAL(1),
                                  D3DVAL(0), D3DVAL(1), D3DVAL(0)))
{
    // 에러
}

참조

IDirect3DRMFrame3::GetOrientation

IDirect3DRMFrame3::SetPosition

IDirect3DRMFrame3

참조 프레임을 기준으로 하는 프레임의 위치를 설정한다. 프레임을 참조 프레임으로부터[rvX, rvY, rvZ]의 거리에 둔다. 아이 프레임이 친프레임내에 생성 되는 경우, 친프레임의[0, 0, 0]에 놓여진다.

구문

HRESULT SetPosition(
  LPDIRECT3DRMFRAME3 lpRef,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ
  );

파라미터

lpRef
참조 프레임으로서 사용되는 Direct3DRMFrame 오브젝트를 나타내는 변수의 주소. 이것은 NULL로 할 수 있다. NULL의 경우, 메소드는 참조 프레임의 변환 매트릭스는 아니고, 로컬의 변환 매트릭스를 사용한다.
rvX, rvY, rvZ
프레임의 새로운 위치. 위치는 단위를 가지지 않는다. 절두체를 사용해, 적정한 숫자를 선택한다. 상세한 것에 대하여는, 「뷰포트」를 참조할것.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는,Direct3DRMFrameInterpolator 오브젝트에 위치 키를 추가하기 위해서도 사용한다.

다음의 코드 부분은,SetPosition를 호출한다. 이것은,IDirect3DRM3::CreateFrame 메소드를 사용해, 카메라와 장면 프레임이 벌써 생성 되고 있는 것을 전제로 하고 있다.

LPDIRECT3DRMFRAME3 camera;
LPDIRECT3DRMFRAME3 scene;

if (FAILED(camera->SetPosition(scene, D3DVAL(0), D3DVAL(0), -D3DVAL(10)))
{
    // 에러
}

참조

IDirect3DRMFrame3::GetPosition

IDirect3DRMFrame3::SetQuaternion

IDirect3DRMFrame3

단위 4원수를 이용해, 참조 프레임에 대해서 프레임의 방향을 설정한다.

구문

HRESULT SetQuaternion(
  LPDIRECT3DRMFRAME3 lpRef,
  D3DRMQUATERNION *quat
  )

파라미터

lpRef
참조로서 이용하는 Direct3DRMFrame2 오브젝트를 나타내는 변수의 주소. 이것은 NULL로 할 수 있다. NULL의 경우, 메소드는 참조 프레임의 변환 매트릭스는 아니고, 로컬의 변환 매트릭스를 사용한다.
quat
단위 4원수를 보관 유지하는D3DRMQUATERNION 구조체.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

4원수란, 임의의 회전을 나타내기 위해서(때문에) 이용되는 4값벡터로, 방향의 사이에 보간을 실시할 때 유용한 특성을 가지고 있다. 4원수는, s**2 + x**2 + y**2 + z**2 = 1이면 단위 4원수이다.

함수D3DRMQuaternionFromRotation 는, 임의의 회전값으로부터 단위 4원수를 생성할 경우에 이용한다.

SetQuaternion메소드는, FrameInterpolators에 의해 지원 되고 있다. 인타포레이타에 대한 자세한 것은, 「인타포레이타」를 참조할것.

IDirect3DRMFrame3::SetRotation

IDirect3DRMFrame3

IDirect3DRM3::Tick 또는IDirect3DRMFrame3::Move 메소드에 대한 호출할 것에, 지정의 벡터의 주위로 지정의 각도로 프레임의 회전을 설정한다. 방향 벡터 [rvX, rvY, rvZ] 는, 참조 프레임으로 정의된다.

구문

HRESULT SetRotation(
  LPDIRECT3DRMFRAME3 lpRef,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ,
  D3DVALUE rvTheta
  );

파라미터

lpRef
참조 프레임으로서 사용되는 Direct3DRMFrame 오브젝트를 나타내는 변수의 주소. 이것은 NULL로 할 수 있다. NULL의 경우, 메소드는 참조 프레임의 변환 매트릭스는 아니고, 로컬의 변환 매트릭스를 사용한다.
rvX, rvY, rvZ
회전의 중심의 벡터. 유효한 값은,-1. 0에서 1.0의 범위에 있을 필요가 있다.
rvTheta
라디안 단위의 회전각. 각도가 크면 큰 만큼, 오브젝트의 회전은 빨라진다. IDirect3DRMFrame3::Move 와IDirect3DRM3::Tick 메소드가, 이 값을 스케일링 한다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

지정의 회전은, 프레임중의 오브젝트를 한 번 밖에 변경하지 않는IDirect3DRMFrame3::AddRotation 메소드와는 달라, 렌더링 마다 행렬을 변경한다.

다음의 코드 부분은,SetRotation를 호출한다. 이것은,IDirect3DRM3::CreateFrame 메소드를 사용해, 아이와 장면 프레임이 벌써 생성 되고 있는 것을 전제로 하고 있다.

LPDIRECT3DRMFRAME3 child;
LPDIRECT3DRMFRAME3 scene;

if (FAILED(child->SetRotation(scene, D3DVAL(0), D3DVAL(1), D3DVAL(1), D3DVAL(0.02)))
{
    // 에러
}

참조

IDirect3DRMFrame3::AddRotation , IDirect3DRMFrame3::GetRotation

IDirect3DRMFrame3::SetSceneBackground

IDirect3DRMFrame3

장면의 배경색을 설정한다.

구문

HRESULT SetSceneBackground(
  D3DCOLOR rcColor
  );

파라미터

rcColor
배경의 새로운 색.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, Direct3DRMFrameInterpolator 오브젝트에의 배경 컬러 키를 추가하기 위해서도 사용된다.

IDirect3DRMFrame3::SetSceneBackgroundDepth

IDirect3DRMFrame3

장면의 배경 깊이 버퍼를 지정한다.

구문

HRESULT SetSceneBackgroundDepth(
  LPDIRECTDRAWSURFACE lpImage
  );

파라미터

lpImage
신의 새로운 배경 깊이를 보존하는 DirectDraw 표면의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이미지는 픽셀 단위의 깊이 16을 가지지 않으면 안 된다. 이미지와 뷰포트의 사이즈가 다르면(자), 처음에 이미지의 스케일링을 실시한다. 배경 깊이 버퍼를 아니메이트 할 경우에 최적인 퍼포먼스를 얻으려면 , 이미지는 뷰포트와 같은 사이즈가 아니면 안된다. 그렇다면, 여분의 오버헤드없이, 깊이 버퍼는 이미지 메모리로부터 직접 갱신할 수가 있다.

참조

IDirect3DRMFrame3::GetSceneBackgroundDepth

IDirect3DRMFrame3::SetSceneBackgroundImage

IDirect3DRMFrame3

장면의 배경 이미지를 지정한다.

구문

HRESULT SetSceneBackgroundImage(
  LPDIRECT3DRMTEXTURE3 lpTexture
  );

파라미터

lpTexture
새로운 배경 신을 포함한 Direct3DRMTexture 오브젝트의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이미지의 사이즈 또는 컬러 깊이가 뷰포트와 다른 경우, 우선 이미지의 스케일링을 실시하는지, 올바른 깊이로 변환한다. 배경을 아니메이트 할 경우에 최적인 퍼포먼스를 얻으려면 , 이미지는 뷰포트와 같은 사이즈 및 컬러 깊이가 아니면 안된다. 그렇다면, 여분의 오버헤드없이, 직접 이미지 메모리로부터 배경의 렌더링을 실시할 수가 있다.

IDirect3DRMFrame3::SetSceneBackgroundRGB

IDirect3DRMFrame3

장면의 배경색을 설정한다.

구문

HRESULT SetSceneBackgroundRGB(
  D3DVALUE rvRed,
  D3DVALUE rvGreen,
  D3DVALUE rvBlue
  );

파라미터

rvRed, rvGreen, rvBlue
배경의 새로운 색. 색의 각 요소는, 0.0에서 1.0의 범위에 있을 필요가 있다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, Direct3DRMFrameInterpolator 오브젝트에 배경 RGB 컬러 키를 추가하기 위해서도 이용된다.

IDirect3DRMFrame3::SetSceneFogColor

IDirect3DRMFrame3

장면의 포그(안개:fog)색을 설정한다.

구문

HRESULT SetSceneFogColor(
  D3DCOLOR rcColor
  );

파라미터

rcColor
포그(안개:fog)의 새로운 색.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, Direct3DRMRFrameInterpolator 오브젝트에 포그(안개:fog) 컬러 키를 추가하기 위해서도 이용된다.

IDirect3DRMFrame3::SetSceneFogEnable

IDirect3DRMFrame3

포그(안개:fog) enable 상태를 설정한다.

구문

HRESULT SetSceneFogEnable(
  BOOL bEnable
  );

파라미터

bEnable
새로운 포그(안개:fog) enable 상태.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMFrame3::SetSceneFogMethod

IDirect3DRMFrame3

버텍스 포그(안개:fog) 또는 테이블 포그(안개:fog)를 개입시켜 포그(안개:fog)를 실행할지 어떨지를 지정한다.

구문

HRESULT SetSceneFogMethod(
  DWORD dwFlags);

파라미터

dwFlags
현재 정의되고 있는 플래그는, 다음과 같다.
D3DRMFOGMETHOD_ANY
Direct3D 보관 유지 모드가 적용 가능한 메소드를 선택하는 것을 나타낸다.
D3DRMFOGMETHOD_VERTEX
버텍스 포그(안개:fog)를 사용한다.
D3DRMFOGMETHOD_TABLE
테이블 포그(안개:fog)를 사용한다.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_BADVALUE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

IDirect3DRM3인터페이스에 의해 생성 되는Direct3DRMFrame오브젝트의 디폴트의 동작은D3DRMFOGMETHOD_ANY이며, 포그(안개:fog) 메소드는 디바이스의 기능에 근거해 선택된다. 디바이스가 버텍스와 테이블을 기준으로 한 양쪽 모두의 포그(안개:fog)를 지원 하는 경우, 버텍스 포그(안개:fog)가 사용된다. 어플리케이션으로 테이블 포그(안개:fog)가 요구되었지만, 테이블 포그(안개:fog)가 사용 가능하지 않은 경우도, 버텍스 포그(안개:fog)가 사용된다. IDirect3DRM또는IDirect3DRM2인터페이스에 의해 생성 되는Direct3DRMFrame오브젝트의 동작은,D3DRMFOGMETHOD_VERTEX이다.

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMFrame3::SetSceneFogMode

IDirect3DRMFrame3

포그(안개:fog) 모드를 설정한다.

구문

HRESULT SetSceneFogMode(
  D3DRMFOGMODE rfMode
  );

파라미터

rfMode
D3DRMFOGMODE 열거형의 멤버의 하나로, 새로운 포그(안개:fog) 모드를 지정한다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMFrame3::SetSceneFogParams

IDirect3DRMFrame3::SetSceneFogParams

IDirect3DRMFrame3

이 장면의 현재의 포그(안개:fog) 파라미터를 설정한다.

구문

HRESULT SetSceneFogParams(
  D3DVALUE rvStart,
  D3DVALUE rvEnd,
  D3DVALUE rvDensity
  );

파라미터

rvStart, rvEnd
선형 포그(안개:fog) 모드의 포그(안개:fog) 시작 및 종료 포인트. 이 설정은, 포그(안개:fog) 효과가 최초로 보이게 될 때의카메라로부터의 거리와 포그(안개:fog)가 최대 밀도가 될 때의 거리를 결정한다.
rvDensity
지수 포그(안개:fog) 모드에서의 포그(안개:fog) 밀도. 이 값은, 0에서 1의 값이 아니면 안된다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, Direct3DRMRFrameInterpolator 오브젝트에 포그(안개:fog) 파라미터 키를 추가하기 위해서도 이용된다.

참조

D3DRMFOGMODE , IDirect3DRMFrame3::SetSceneFogMode

IDirect3DRMFrame3::SetSortMode

IDirect3DRMFrame3

아이 프레임을 처리하는데 사용하는 소트 모드를 설정한다. 이 메소드를 사용해 은면삭제 알고리즘의 프로퍼티를 변경할 수가 있다.

구문

HRESULT SetSortMode(
  D3DRMSORTMODE d3drmSM
  );

파라미터

d3drmSM
소트 모드를 지정하는D3DRMSORTMODE 열거형의 멤버의 하나. 디폴트값은, D3DRMSORT_FROMPARENT이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMFrame3::GetSortMode

IDirect3DRMFrame3::SetTexture

IDirect3DRMFrame3

프레임의 텍스쳐를 설정한다.

구문

HRESULT SetTexture(
  LPDIRECT3DRMTEXTURE3 lpD3DRMTexture
  );

파라미터

lpD3DRMTexture
사용하는 Direct3DRMTexture 오브젝트를 나타내는 변수의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 텍스쳐는,D3DRMMATERIALMODE 열거형이 D3DRMMATERIAL_FROMFRAME인 경우에 프레임중의 메쉬에 대해서 사용된다. 프레임의 텍스쳐를 디세블로 하려면 , NULL 텍스쳐를 사용한다.

참조

IDirect3DRMFrame3::GetTexture , IDirect3DRMFrame3::SetMaterialMode

IDirect3DRMFrame3::SetTraversalOptions

IDirect3DRMFrame3

렌더링과 피킹 시에 이 프레임을 횡단할지 어떨지를 지정한다. 즉,D3DRMFRAME_RENDERENABLE의 값없이 이 API를 사용 하면, 렌더링에 대해서 프레임이 효율적으로 오프에 완전히 교체된다. 디폴트에서는, 프레임은 렌더링과 피킹에 대해서 유효하게 된다.

구문

HRESULT SetTraversalOptions
(DWORD dwFlags);

파라미터

dwFlags
현재 정의되고 있는 플래그는, 다음과 같다.
D3DRMFRAME_RENDERENABLE
이 프레임 또는 그 아이 프레임을 렌더링 하는 것을 나타낸다.
D3DRMFRAME_PICKENABLE
이 프레임 또는 그 아이 프레임중의, 임의의 비주얼을 픽 하는 것을 나타낸다.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_BADVALUE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMFrame3::SetVelocity

IDirect3DRMFrame3

참조 프레임을 기준으로서 지정의 프레임의 속도를 설정하는 프레임은,IDirect3DRM3::Tick 또는IDirect3DRMFrame3::Move 메소드에 대한 연속 호출할 것에, 참조 프레임을 기준으로서 [rvX, rvY, rvZ] 벡터분만큼 이동한다.

구문

HRESULT SetVelocity(
  LPDIRECT3DRMFRAME3 lpRef,
  D3DVALUE rvX,
  D3DVALUE rvY,
  D3DVALUE rvZ,
  BOOL fRotVel
  );

파라미터

lpRef
참조 프레임으로서 사용되는 Direct3DRMFrame 오브젝트를 나타내는 변수의 주소. 이것은 NULL로 할 수 있다. NULL의 경우, 메소드는 참조 프레임의 변환 매트릭스는 아니고, 로컬의 변환 매트릭스를 사용한다.
rvX, rvY, rvZ
프레임의 새로운 속도. 회전 속도는 단위를 가지지 않고, 임의의 값을 세트 할 수 있다. IDirect3DRMFrame3::Move 와IDirect3DRM3::Tick 메소드는, 이 값을 스케일링 한다.
fRotVel
직선 속도를 설정할 경우에, 오브젝트의 회전 속도를 고려할지 어떨지를 지정하는 플래그. TRUE의 경우, 오브젝트의 회전 속도가 계산에 포함된다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMFrame3::GetVelocity

IDirect3DRMFrame3::SetZbufferMode

IDirect3DRMFrame3

Z버퍼 모드를 설정한다. 즉, Z버퍼링을 enable 또는 디세블로 하는지를 설정한다.

구문

HRESULT SetZbufferMode(
  D3DRMZBUFFERMODE d3drmZBM
  );

파라미터

d3drmZBM
Z버퍼 모드를 지정하는D3DRMZBUFFERMODE 열거형의 멤버의 하나. 디폴트값은 D3DRMZBUFFER_FROMPARENT이다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMFrame3::GetZbufferMode

IDirect3DRMFrame3::Transform

IDirect3DRMFrame3

모델 좌표의lpd3dVSrc파라미터중의 벡터를 변환해, 그 결과를월드 좌표의lpd3dVDst파라미터에 돌려준다.

구문

HRESULT Transform(
  D3DVECTOR *lpd3dVDst,
  D3DVECTOR *lpd3dVSrc
  );

파라미터

lpd3dVDst
변환 조작의 결과가 세트 되는D3DVECTOR 구조체의 주소.
lpd3dVSrc
변환 조작의 소스인D3DVECTOR 구조체의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMFrame3::InverseTransform , 「3 D변환」

IDirect3DRMFrame3::TransformVectors

IDirect3DRMFrame3

벡터의 배열을, 모델로부터 월드 공간으로 변환한다.

구문

HRESULT TransformVectors(
  LPDIRECT3DRMFRAME3 lpRefFrame,
  DWORD dwNumVectors,
  LPD3DVECTOR lpDstVectors,
  LPD3DVECTOR lpSrcVectors);

파라미터

lpRefFrame
이 호출을 위해서(때문에) 장면의 루트로서 사용되는 프레임. 이 인수가 NULL의 경우, 현재의루트 프레임(GetScene가 돌려주는 프레임)이 사용된다.
dwNumVectors
변환할 필요가 있는 벡터수.
lpDstVectors
변환의 출력처.
lpSrcVectors
변환하는 벡터의 배열.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.


IDirect3DRMMeshBuilder3

IDirect3DRMMeshBuilder3 메소드 A~M

이 항은,IDirect3DRMMeshBuilder3 인터페이스의 메소드 가운데, 메소드명이 A로부터 M의 것을 취하는 레퍼런스 페이지이다.

IDirect3DRMMeshBuilder3::AddFace

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트에 1개의 면을 추가한다.

구문

HRESULT AddFace(
  LPDIRECT3DRMFACE2 lpD3DRMFace
  );

파라미터

lpD3DRMFace
추가하는 면에의 포인터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

어느 1개의 면도, 한 번에 1개의 메쉬 밖에 존재할 수 없다.

IDirect3DRMMeshBuilder3::AddFaces

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트에 복수의 면을 추가한다.

구문

HRESULT AddFaces(
  DWORD dwVertexCount,
  D3DVECTOR  *lpD3DVertices,
  DWORD normalCount,
  D3DVECTOR *lpNormals,
  DWORD *lpFaceData,
  LPDIRECT3DRMFACEARRAY *lplpD3DRMFaceArray
  );

파라미터

dwVertexCount
버텍스의 수.
lpD3DVertices
버텍스 위치를 저장 하는D3DVECTOR 구조체로부터 되는 배열의 베이스 주소.
normalCount
법선의 수.
lpNormals
법선의 위치를 저장 하는D3DVECTOR 구조체로부터 되는 배열의 베이스 주소.
lpFaceData
각면에 대해서, 이 파라미터는, 버텍스 카운트와 거기에 계속되어 버텍스 배열의 인덱스를 포함할 필요가 있다. normalCount가 0이 아니면, 이 파라미터는, 버텍스 카운트와 거기에 계속되어 인덱스의 대를 포함할 필요가 있다. 그 인덱스의 대의 최초의 인덱스는, 버텍스 배열에 대한 인덱스이며, 2번째의 인덱스는, 법선의 배열에 대한 인덱스이다. 인덱스의 리스트는, 0으로 종료해야 한다.
lplpD3DRMFaceArray
IDirect3DRMFaceArray 인터페이스에의 포인터의 주소. 새롭고 생성 된 면에의 포인터가 세트 된다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMMeshBuilder3::AddFacesIndexed

IDirect3DRMMeshBuilder3

기존의 버텍스와 법선 (옵션)을 사용하는 메쉬 빌더상에, 다수의 면을 생성 할 수 있도록(듯이) 한다.

구문

IDirect3DRMMeshBuilder3::AddFacesIndexed(
  DWORD dwFlags,
  DWORD *lpdwvIndices,
  DWORD *lpdwIndexFirst,
  DWORD *lpdwCount);

파라미터

dwFlags
법선 인덱스의 처리 방법을 지정하는 플래그값. 0또는D3DRMADDFACES_VERTICESONLY 의 어느 쪽인지가 아니면 안된다. 값이 0이라면, 기존의 법선 인덱스는lpdwvIndices파라미터중으로 지정되어 있지 않으면 안 된다. 그렇지 않은 경우, 대응하는 인덱스를 가지는 법선이 각 버텍스에 대해서 자동적으로 사용된다.
lpdwvIndices
각면에 대해서 다음의 것을 지정하는, 부호 없음 정수의 tuple가 연속하는 배열에의 포인터.
  • 버텍스의 수n, 여기서 n는 3이상
  • 버텍스 인덱스
  • 법선 인덱스 (옵션)

다음의 테이블은,dwFlags파라미터의 값과lpdwvIndices파라미터의 필수면tuple 형식과의 관계를 나타낸다.
dwFlags | 필수면tuple 형식
0 | {<n>, <vIndex0>, <nIndex0>,...,<vIndexn-1>, <nIndexn-1>}
D3DRMADDFACES_VERTICESONLY | {<n>, <vIndex0>,...,<vIndexn-1>}

vIndex와 nIndex의 값은, 메쉬 빌더내에 벌써 존재하고 있는 버텍스와 법선에 색인하는데 필요하다. tuple의 배열은 값 0으로 종료할 필요가 있다.

lpdwIndexFirst
메쉬 빌더에 추가된 최초의 새로운 면의 인덱스가 세트 되는 DWORD에의 옵션의 포인터. 계속되는 면에는 연속하는 인덱스를 붙일 수 있다. 면은,lpdwvIndices파라미터로 지정된 순서에 추가된다.
lpdwCount
메쉬 빌더에 추가된 면의 수가 세트 되는 DWORD에의 옵션의 포인터.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMMeshBuilder3::AddFrame

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트에 프레임의 내용을 추가한다.

구문

HRESULT AddFrame(
  LPDIRECT3DRMFRAME3 lpD3DRMFrame
  );

파라미터

lpD3DRMFrame
그 내용이 추가되는 프레임에의 포인터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, 지정된 프레임 계층 (보다 큰 프레임 계층의 서브 분기도 가능)으로부터Direct3DRMMeshBuilder3 오브젝트에, 모든 메쉬와 메쉬 빌더의 면의 카피를 추가한다. 프레임 트리는,루트 프레임을 건네주는 것으로 지정한다. 면은, 그것들이 내포 하는 요소 프레임의 위치와 방향에 의해 추가된다. 루트 프레임에 부모가 있어도, 지정된 루트 프레임의 변환은 무시된다.

소스 프레임은, 이 조작에 의해 변경 또는 참조도 되지 않는다.

IDirect3DRMMeshBuilder3::AddMesh

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트에 메쉬를 추가한다.

구문

HRESULT AddMesh(
  LPDIRECT3DRMMESH lpD3DRMMesh
  );

파라미터

lpD3DRMMesh
추가하는 메쉬에의 포인터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMMeshBuilder3::AddMeshBuilder

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트의 내용을 다른 Direct3DRMMeshBuilder3 오브젝트에 추가한다. 내포 하는 Direct3DRMMeshBuilder3 소스 오브젝트와 면의 아래에서 있는 모든 서브 메쉬 빌더는, Direct3DRMMeshBuilder3 타겟 오브젝트의 아래에서 중복 한다.

구문

HRESULT
AddMeshBuilder(
  LPDIRECT3DRMMESHBUILDER3 lpD3DRMMeshBuild
  DWORD dwFlags);
  );

파라미터

lpD3DRMMeshBuild
그 내용을 추가하는 Direct3DRMMeshBuilder3 오브젝트에의 포인터.
dwFlags

다음에 정의하는 플래그의 하나.

D3DRMADDMESHBUILDER_FLATTENSUBMESHES
서브 메쉬 오브젝트가 중복 하지 않게 한다. 이러한 면은 여전히 카피 가능하지만, 출력처 메쉬 빌더의 톱 레벨 에 대해서만이다.
D3DRMADDMESHBUILDER_NOSUBMESHES
서브 메쉬 빌더를 무시하도록(듯이) 한다.
D3DRMADDMESHBUILDER_DONTCOPYAPPDATA
AddMeshBuilder3는, 소스 메쉬 빌더의 어플리케이션 데이터를 출력 먼저 카피한다. D3DRMADDMESHBUILDER_DONTCOPYAPPDATA를 지정 하면, 이것이 방지된다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

소스의 Direct3DRMMeshBuilder3 오브젝트는, 이 조작으로 변경 또는 참조도 되지 않는다.

IDirect3DRMMeshBuilder3::AddNormal

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트에 법선을 추가한다.

구문

int AddNormal(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z
  );

파라미터

x, y, z
새로운 법선의 방향의 x, y, z의 각 요소.

반환값

법선의 인덱스를 돌려준다.

IDirect3DRMMeshBuilder3::AddTriangles

IDirect3DRMMeshBuilder3

어플리케이션이 새로운 삼각형 (일반적인 다각형과 대립적인 의미로)을IDirect3DRMMeshBuilder3오브젝트에 추가해, 처리중에 암묵에 새로운 면을 생성 할 수 있도록(듯이) 한다. 이 메소드는, 삼각형을 기술하는 어플리케이션에 유연성을 제공한다. 삼각형은 버텍스세트에 의해 기술할 수 있다. 각 버텍스는 위치를 가지지 않으면 안 되지만, 옵션으로, 법선, 텍스쳐 좌표 또는 색중 어떤 것인지를 가지는지, 전혀 가지지 않아도 좋다. 또, 버텍스에는, 이 새로운 버텍스가 리스트, 작은 조각, 또는 부채를 기술할지 어떨지를 나타내는 타입을 가진다. 또, 이 플래그는, 해당하는 삼각형을 이전의 삼각형의 면에 추가할지 어떨지, 또는 새로운 면을 생성 할지 어떨지도 가리킨다.

구문

HRESULT AddTriangles(
  DWORD dwFlags,
  DWORD dwFormat,
  DWORD dwVertexCount,
  LPVOID lpData);

파라미터

dwFlags
0이 아니면 안된다.
dwFormat
버텍스 데이터의 포맷을 기술하는 값의 논리적인 편성. 모든 유효한 값이 포함되어 있는 경우, 버텍스 데이터는 다음의Element구조체에 의해 기술할 수 있다.
struct Element
{
    DWORD     dwType;
    D3DVECTOR dvPosition;
    D3DVECTOR dvNormal;
    D3DCOLOR  dcColor;
    D3DVALUE  tu;
    D3DVALUE  tv;
};

유효한 값으로서는, 다음의 값의 임의의 편성이 가능하고, 이것들은Element구조체의 어느 멤버를 각 요소의 기술에 포함하는지를 나타낸다. dvPosition멤버는 항상 존재한다.

D3DRMFVF_TYPE
dwType구조체 멤버를 포함한다. dwType구조체 멤버가 존재하는 경우, 그 중에는 다음의 어떤 것이나 1개가 없으면 안 된다.
D3DRMVERTEX_LIST
새로운 리스트를 시작 하든가, 혹은 이전에 시작 한 리스트의 멤버이다. 이전의 버텍스 (또는 그 전의 버텍스)에 이 플래그의 마크가 뒤따르지 않은 경우, 최저 1개의 삼각형이 형성될 때까지, 다음의 버텍스에 이 플래그의 마크가 뒤따르지 않으면 안 된다.
D3DRMVERTEX_STRIP
이전의 2개의 버텍스를 가지는 새로운 삼각형을 작은 조각 포맷으로 형성한다.
D3DRMVERTEX_FAN
이전의 버텍스와 부채의 최초의 버텍스를 가지는 새로운 삼각형을 형성한다.
D3DRMFVF_NORMAL
dvNormal구조체 멤버를 포함한다.
D3DRMFVF_COLOR
dcColor구조체 멤버를 포함한다.
D3DRMFVF_TEXTURECOORDS
tu와tv구조체 멤버를 포함한다.
dwVertexCount
버텍스의 수.
lpvData
dwFormat로 기술되는 데이터에의 포인터.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

다음의 예는, 그림중의 각 버텍스에 대해서 적절한dwType플래그를 나타낸다.
버텍스수 | dwType플래그
0 | D3DRMVERTEX_STRIP
1 | D3DRMVERTEX_STRIP
2 | D3DRMVERTEX_STRIP
3 | D3DRMVERTEX_STRIP
4 | D3DRMVERTEX_STRIP
5 | D3DRMVERTEX_FAN
6 | D3DRMVERTEX_FAN
7 | D3DRMVERTEX_FAN
8 | D3DRMVERTEX_FAN
9 | D3DRMVERTEX_LIST
10 | D3DRMVERTEX_LIST
11 | D3DRMVERTEX_LIST
12 | D3DRMVERTEX_LIST
13 | D3DRMVERTEX_LIST
14 | D3DRMVERTEX_LIST

IDirect3DRMMeshBuilder3::AddVertex

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트에 버텍스를 추가한다.

구문

int AddVertex(
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z
  );

파라미터

x, y, z
새로운 버텍스의 위치의 x, y, z의 각 요소.

반환값

버텍스의 인덱스를 돌려준다.

IDirect3DRMMeshBuilder3::CreateFace

IDirect3DRMMeshBuilder3

버텍스의 새로운 면을 생성 해, Direct3DRMMeshBuilder3 오브젝트에 추가한다.

구문

HRESULT CreateFace(
  LPDIRECT3DRMFACE2 *lplpD3DRMFace2
  );

파라미터

lplpD3DRMFace2
IDirect3DRMFace2 인터페이스에의 포인터의 주소. 생성 된 면에의 포인터가 세트 된다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMMeshBuilder3::CreateMesh

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트로부터 새로운 메쉬를 생성 한다.

구문

HRESULT CreateMesh(
  LPDIRECT3DRMMESH *lplpD3DRMMesh
  );

파라미터

lplpD3DRMMesh
<IDirect3DRMMesh 인터페이스에의 포인터가 세트 되는 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMMeshBuilder3::CreateSubMesh

IDirect3DRMMeshBuilder3

현재의Direct3DRMMeshBuilder3오브젝트에 대해서, 새로운 서브 메쉬를 생성 한다. 서브 메쉬는,IDirect3DRMMeshBuilder3인터페이스를 지원 해, 그 자체도 서브 메쉬를 가질 수 있다고 하는 점으로써, 메쉬 빌더 오브젝트에 유사하고 있다. 서브 메쉬와 메쉬 빌더의 상위는, 모든 서브 메쉬가 버텍스와 법선을, 서브 메쉬의 연쇄중의 오모토의 조상과 공유하는 것이다. 메쉬 빌더는 버텍스와 법선을 공유하지 않는다.

구문

HRESULT CreateSubMesh(
  LPUNKNOWN  *lplpUnk);

파라미터

lplpUnk
새로운 서브 메쉬의IUnknown 인터페이스에의 포인터를 받는 주소. IUnknown인터페이스 위에의QueryInterface 를 사용해,IDirect3DRMMeshBuilder3지원의 조회를 실시할 수가 있다.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

참조

DeleteSubMesh , GetSubMeshes , GetParentMesh

IDirect3DRMMeshBuilder3::DeleteFace

IDirect3DRMMeshBuilder3

IDirect3DRMMeshBuilder3오브젝트의 면을 삭제한다.

구문

HRESULT DeleteFace
(LPDIRECT3DRMFACE2 lpFace);

파라미터

lpFace
Direct3DRMMeshBuilder3오브젝트로부터 삭제하는Direct3DRMFace2오브젝트의 인터페이스에의 포인터.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMMeshBuilder3::DeleteNormals

IDirect3DRMMeshBuilder3

법선의 내포 범위를 삭제한다. 면이 어떤 것인가의 법선을 현재 사용중이면, 에러가 돌려주어지므로, 주의 해야 한다.

구문

HRESULT DeleteNormals
(DWORD dwFirstIndex,
DWORD dwCount);

파라미터

dwFirstIndex
삭제하는 최초의 법선의 인덱스.
dwCount
삭제하는 버텍스의 카운트.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_ENTRYINUSE
D3DRMERR_OUTOFRANGE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMMeshBuilder3::DeleteSubMesh

IDirect3DRMMeshBuilder3

서브 메쉬를 삭제한다. 서브 메쉬는, 현재의Direct3DRMMeshBuilder3오브젝트의 바로 아래의 아이가 아니면 안된다.

구문

HRESULT DeleteSubMesh(
  LPUNKNOWN lplpUnk);

파라미터

lplpUnk
삭제하는 서브 메쉬의IUnknown 인터페이스에의 포인터.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

참조

CreateSubMesh , GetSubMeshes , GetParentMesh

IDirect3DRMMeshBuilder3::DeleteVertices

IDirect3DRMMeshBuilder3

버텍스의 내포 범위를 삭제한다. 면이 어떤 것인가의 버텍스를 현재 사용중이면, 에러가 돌려주어지므로, 주의 해야 한다.

구문

HRESULT DeleteVertices
(DWORD dwFirstIndex,
DWORD dwCount);

파라미터

dwFirstIndex
삭제하는 최초의 버텍스의 인덱스.
dwCount
삭제하는 버텍스의 카운트.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_ENTRYINUSE
D3DRMERR_OUTOFRANGE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMMeshBuilder3::Empty

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트로부터, 모든 면, 버텍스, 법선을 삭제한다.

구문

HRESULT Empty
(DWORD dwFlags);

파라미터

dwFlags
플래그. 0이 아니면 안된다.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_OUTOFRANGE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMMeshBuilder3::Enable

IDirect3DRMMeshBuilder3

이Direct3DRMMeshBuilder3오브젝트를, 렌더링과 피킹용으로 유효하게 할까 무효로 하는지를 지정한다.

구문

HRESULT Enable(
  DWORD dwFlags);

파라미터

dwFlags

현재 정의되고 있는 플래그는, 다음과 같다.

D3DRMADDMESHBUILDER_RENDERENABLE
이Direct3DRMMeshBuilder3오브젝트상에서는 렌더링이 유효하게 되어 있다. 이 설정은 디폴트이다.
D3DRMADDMESHBUILDER_PICKENABLE
이Direct3DRMMeshBuilder3오브젝트상에서는, 피킹이 유효하게 되어 있다. 이 설정은 디폴트이다.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

참조

GetEnable

IDirect3DRMMeshBuilder3::GenerateNormals

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트를 처리해, 버텍스를 공유하는 각면에 대한 면법선을 평균화하는 것에 의해, 메쉬중의 각 버텍스에 대해서 법선을 생성한다. 새로운 법선은, 버텍스를 공유하는 면이, 면끼리의 각도가 접힌 곳의 각도보다 큰 경우에 생성된다.

구문

HRESULT GenerateNormals(
  D3DVALUE dvCreaseAngle,
  DWORD dwFlags
  );

파라미터

dvCreaseAngle
라디안 단위의, 새로운 법선을 생성할 수 있는 면끼리의 최소 가능 각도.
dwFlags
이하의 값의 하나.
D3DRMGENERATENORMALS_PRECOMPACT (dwFlags = 1)
법선의 생성전에, 알고리즘은, 메쉬의 버텍스를 컴팩트하게 해야할 것인가를 지정하게 되어 있다. 아래의 「주의」를 참조할것.
D3DRMGENERATENORMALS_USECREASEANGLE (dwFlags = 2)
dvCreaseAngle파라미터를 사용하는 것을 지정한다. 지정하지 않으면 접은 자국각은 무시된다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는,IDirect3DRMMeshBuilder2::GenerateNormals2를 치환한다. D3DRMGENERATENORMALS_PRECOMPACT 플래그를 지정 하면, 프리콘파크트파스는, 메쉬중의 모든 버텍스를 검색해, 같은 버텍스를 모두 머지 한다. 이것은, 로드 되고 있는 메쉬를 컴팩트하게 하는데 현명한 방법이다. 메쉬안에는, 버텍스에 복수의 법선을 가지는 경우에, 복수의 버텍스를 가지는 것이 있다. 이것은, Direct3D 보관 유지 모드에서는 필요하지 않는다. 이 플래그의 지정은, 복수의 버텍스를 제거하는 경우의 정평적 방법이다.

컴팩트 처리의 뒤, 법선이 생성된다. 면끼리의 사이의 옆이 조사할 수 있어 면이 옆으로 하는 각도가, 접은 자국각보다 작은 경우에는, 면법선은 평균화되어 버텍스 법선이 생성된다. 각도가 접은 자국각보다 큰 경우에는, 새로운 법선이 생성된다. 새로운 버텍스는, 생성되지 않는 것에 주의한다.

IDirect3DRMMeshBuilder3::GetBox

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트를 포함한 경계 박스를 취득한다. 경계 박스는, 각 차원에서의 최소, 최대의모델 좌표를 준다.

구문

HRESULT GetBox(
  D3DRMBOX *lpD3DRMBox
  );

파라미터

lpD3DRMBox
경계 박스의 좌표가 세트 되는D3DRMBOX 구조체의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMMeshBuilder3::GetColorSource

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트의 색소스를 취득한다. 색소스는, 면에서도 버텍스에서도 좋다.

구문

D3DRMCOLORSOURCE GetColorSource( );

반환값

D3DRMCOLORSOURCE 열거형의 멤버를 돌려준다.

참조

IDirect3DRMMeshBuilder3::SetColorSource

IDirect3DRMMeshBuilder3::GetEnable

IDirect3DRMMeshBuilder3

이Direct3DRMMeshBuilder3오브젝트를 유효하게 할까 무효로 하는지를 나타내는 값을 취득한다.

구문

HRESULT GetEnable(
  LPDWORD lpdwFlags);

파라미터

lpdwFlags
이Direct3DRMMeshBuilder3오브젝트의 현재의 유효 상태를 나타내는 플래그를 받는 포인터. 현재 정의되고 있는 플래그는, 다음과 같다.
D3DRMADDMESHBUILDER_PICKENABLE
이Direct3DRMMeshBuilder3오브젝트상에서는, 피킹이 유효하게 되어 있다. 이 플래그는 디폴트로 세트 된다.
D3DRMADDMESHBUILDER_RENDERENABLE
이Direct3DRMMeshBuilder3오브젝트상에서는, 렌더링이 유효하게 되어 있다. 이 플래그는 디폴트로 세트 된다.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

참조

Enable

IDirect3DRMMeshBuilder3::GetFace

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트의 단일면을 취득한다.

구문

HRESULT GetFace(
  DWORD dwIndex,
  LPDIRECT3DRMFACE2 *lplpD3DRMFace2
  );

파라미터

dwIndex
취득하는 메쉬면의 인덱스. 이 면은 Direct3DRMMeshBuilder3 오브젝트의 일부로 되어 있지 않으면 안 된다.
lplpD3DRMFace2
IDirect3DRMFace2 인터페이스에의 포인터의 주소. 면의 주소가 세트 된다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMMeshBuilder3::GetFaceCount

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트의 면의 수를 취득한다.

구문

int GetFaceCount( );

반환값

면의 수를 돌려준다.

IDirect3DRMMeshBuilder3::GetFaces

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트의 면을 취득한다.

구문

HRESULT GetFaces(
  LPDIRECT3DRMFACEARRAY *lplpD3DRMFaceArray
  );

파라미터

lplpD3DRMFaceArray
IDirect3DRMFaceArray 인터페이스에의 포인터의 주소. 면의 주소가 세트 된다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMMeshBuilder3::GetGeometry

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트의 버텍스, 법선, 면데이터를 취득한다.

구문

HRESULT GetGeometry(
  DWORD *vcount,
  D3DVECTOR *vertices,
  DWORD *ncount,
  D3DVECTOR *normals,
  DWORD *face_data_size,
  DWORD *face_data
  );

파라미터

vcount
버텍스의 수가 들어가 있는 변수의 주소.
vertices
Direct3DRMMeshBuilder3 오브젝트의 버텍스를 포함한D3DVECTOR 구조체의 배열의 주소. 이 파라미터가 NULL라면, 이 메소드는vcount파라미터중에 버텍스의 수를 돌려준다.
ncount
법선의 수가 들어가 있는 변수의 주소.
normals
Direct3DRMMeshBuilder3 오브젝트의 법선을 포함한D3DVECTOR 구조체의 배열의 주소. 이 파라미터가 NULL라면, 이 메소드는ncount파라미터중에 법선의 수를 돌려준다.
face_data_size
파라미터가 포인트 하는 버퍼의 사이즈를 지정하는 변수의 주소. 사이즈는DWORD값의 단위로 주어진다. 이 파라미터는 NULL에 세트 할 수 없다.
face_data
Direct3DRMMeshBuilder3 오브젝트의 면데이터의 주소. 이 데이터는, NULL로 끝나는 점을 제외해,IDirect3DRMMeshBuilder3::AddFaces 메소드로 지정된 포맷과 같다. 이 파라미터가 NULL라면, 이 메소드는face_data_size파라미터중에 면데이터 버퍼의 필요 사이즈의 수를 돌려준다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다. IDirect3DRMMeshBuilder와IDirect3DRMMeshBuilder2인터페이스는,GetVertices메소드를 개입시켜 이 기능을 제공한다. 구의 메소드의 이름은GetGeometry로 변경이 되는 것과 동시에,IDirect3DRMMeshBuilder3인터페이스에서는 이 메소드로 실시하는 것을 기술해, 새로운GetVertices 메소드와의 충돌을 피할 수가 있다.

IDirect3DRMMeshBuilder3::GetNormal

IDirect3DRMMeshBuilder3

법선 벡터를 취득한다.

구문

HRESULT GetNormal
(DWORD dwIndex,
LPD3DVECTOR lpVector);

파라미터

dwIndex
돌려주는 법선의 인덱스.
lpVector
법선의 x, y, z좌표가 세트 되는D3DVECTOR구조체에의 포인터.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_OUTOFRANGE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMMeshBuilder3::GetNormalCount

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트중의 법선의 수를 돌려준다.

구문

DWORD GetNormalCount(void);

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

참조

GetNormals , SetNormals

IDirect3DRMMeshBuilder3::GetNormals

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트중에서 이전에 정의한 법선의 배열을 취득한다.

구문

HRESULT GetNormals(
  DWORD dwFirst,
  LPDWORD lpdwCount,
  LPD3DVECTOR lpdvVector);

파라미터

dwFirst
돌려주어지는 최초의 법선의 인덱스.
lpdwCount
돌려주어질 예정의 법선수를 포함한 DWORD에의 포인터. lpdvVector가 NULL라면, 이 파라미터는dwFirst로 주어지는 인덱스를 기점으로 한 사용 가능한 법선수를 받는다. lpdvVector가 NULL가 아닌 경우, 이 파라미터에는 실제로 꺼내진 법선수가 들어간다. dwFirst로부터 시작되는 모든 사용 가능한 법선을 확실히 받으려면 ,lpdvVector를 NULL에 세트 해 이 메소드를 호출한다. 다음에,lpdwCount 중에 돌려주어진 값을 사용해,lpdvVector중의 배열의 사이즈를 재어, 재차 이 메소드를 호출한다.
lpdvVector
법선 데이터를 받는 벡터의 배열에의 포인터.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_OUTOFRANGE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

참조

GetNormalCount , SetNormals

IDirect3DRMMeshBuilder3::GetParentMesh

IDirect3DRMMeshBuilder3

이Direct3DRMMeshBuilder3오브젝트의 친메쉬를 취득한다. 현재의 메쉬가 서브 메쉬가 아니면, 이 메소드는 자신의IUnknown 인터페이스에의 포인터를 취득한다.

구문

HRESULT GetParentMesh(
  DWORD dwFlags,
  LPUNKNOWN  *lplpUnk);

파라미터

dwFlags
어느Direct3DRMMeshBuilder3오브젝트를 취득하는지를 정의하는 플래그값. 현재 정의되고 있는 플래그는, 다음과 같다.
D3DRMMESHBUILDER_DIRECTPARENT
이Direct3DRMMeshBuilder3오브젝트의 직접적인 부모.
D3DRMMESHBUILDER_ROOTMESH
부모를 가지지 않는 아이의Direct3DRMMeshBuilder3오브젝트의 최종의 부모.
lplpUnk
부모의IUnknown 인터페이스를 받는 포인터의 주소.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

참조

GetSubMeshes

IDirect3DRMMeshBuilder3::GetPerspective

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트에 대해서, 퍼스펙티브 보정이 온일지 어떨지를 판별한다.

구문

BOOL GetPerspective( );

반환값

퍼스펙티브 보정이 온의 경우는 TRUE, 온이 아닌 경우는 FALSE를 돌려준다.

IDirect3DRMMeshBuilder3::GetQuality

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트의 렌더링 퀄리티를 취득한다.

구문

D3DRMRENDERQUALITY GetQuality( );

반환값

메쉬의 렌더링 퀄리티를 지정하는D3DRMRENDERQUALITY 열거형의 멤버를 돌려준다.

참조

IDirect3DRMMeshBuilder3::SetQuality

IDirect3DRMMeshBuilder3::GetSubMeshes

IDirect3DRMMeshBuilder3

이Direct3DRMMeshBuilder3오브젝트에 포함되는 서브 메쉬의 리스트를 취득한다.

구문

HRESULT GetSubMeshes(
  LPDWCOUNT lpdwCount,
  LPUNKNOWN lpUnk);

파라미터

lpdwCount
돌려주어질 예정의IUnknown 인터페이스 포인터수를 포함한 DWORD값을 가리키는 포인터. lpUnk가 NULL라면,lpdwCount가 포인트 하는 값은 사용 가능한 포인터수를 받는다. 그렇지 않은 경우는,lpdwCount가 포인트 하는 값은 실제로 꺼내진IUnknown 포인터수를 받는다.
lpUnk
아이 서브 메쉬에 대한IUnknown 포인터의 배열.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_OUTOFRANGE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

참조

GetParentMesh

IDirect3DRMMeshBuilder3::GetTextureCoordinates

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트의 지정되고 있는 버텍스의 텍스쳐 좌표를 취득한다.

구문

HRESULT GetTextureCoordinates(
  DWORD index,
  D3DVALUE *lpU,
  D3DVALUE *lpV
  );

파라미터

index
버텍스의 인덱스.
lpU, lpV
메소드가 돌아왔을 때, 버텍스의 텍스쳐 좌표가 세트 되는 변수의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMMeshBuilder3::SetTextureCoordinates

IDirect3DRMMeshBuilder3::GetVertex

IDirect3DRMMeshBuilder3

버텍스 벡터를 취득한다.

구문

HRESULT GetVertex
(DWORD dwIndex,
LPD3DVECTOR lpVector);

파라미터

dwIndex
돌려주는 버텍스의 인덱스.
lpVector
버텍스의 x, y, z좌표가 세트 되는D3DVECTOR구조체에의 포인터.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_OUTOFRANGE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMMeshBuilder3::GetVertexColor

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트의 지정되고 있는 버텍스의 색을 돌려준다.

구문

D3DCOLOR GetVertexColor(
  DWORD index
  );

파라미터

index
버텍스의 인덱스.

반환값

색을 돌려준다.

참조

IDirect3DRMMeshBuilder3::SetVertexColor

IDirect3DRMMeshBuilder3::GetVertexCount

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트중의 버텍스의 수를 취득한다.

구문

int GetVertexCount( );

반환값

버텍스의 수를 돌려준다.

IDirect3DRMMeshBuilder3::GetVertices

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트에 대한 버텍스, 법선, 면데이터를 취득한다.

구문

HRESULT GetVertices(
  DWORD dwFirst,
  LPDWORD lpdwCount,
  LPD3DVECTOR lpdvVector);

파라미터

dwFirst
돌려주어지는 최초의 버텍스의 인덱스.
lpdwCount
돌려주어질 예정의 벡터수를 포함한 DWORD값에의 포인터. lpdvVector가 NULL라면, DWORD값은 소정의 오프셋(offset)로부터 사용 가능한 버텍스수를 받는다. 그렇지 않은 경우, DWORD값은 실제로 꺼내진 벡터수를 받는다.
lpdvVector
버텍스 데이터로 초기화되는 벡터의 배열에의 포인터.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_OUTOFRANGE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되어 구의IDirect3DRMMeshBuilder와IDirect3DRMMeshBuilder2인터페이스가 제공한GetVertices메소드와는 다르다. IDirect3DRMMeshBuilder3에 대해서는, 구의 메소드의 이름은 그 기능을 보다 좋게 나타내는GetGeometry 로 변경되었다.

참조

SetVertices , GetGeometry

IDirect3DRMMeshBuilder3::Load

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트를 로드한다.

구문

HRESULT Load(
  LPVOID lpvObjSource,
  LPVOID lpvObjID,
  D3DRMLOADOPTIONS d3drmLOFlags,
  D3DRMLOADTEXTURE3CALLBACK d3drmLoadTextureProc,
  LPVOID lpvArg
  );

파라미터

lpvObjSource
로드하는 오브젝트의 소스. d3drmLOFlags파라미터로 지정되고 있는 소스 플래그에 의해, 이 소스는 파일, 리소스, 메모리 블록, 또는 스트림으로 할 수 있다.
lpvObjID
로드하는 오브젝트의 이름 또는 위치. 이 파라미터의 사용은,d3drmLOFlags파라미터로 지정되고 있는 식별 플래그에 의존한다. D3DRMLOAD_BYPOSITION 플래그가 지정되고 있으면, 이 파라미터는, 파일중의 오브젝트의 순서를 주는DWORD값에의 포인터가 된다. 이 파라미터는 NULL로 할 수 있다.
d3drmLOFlags
로드 옵션을 기술하는D3DRMLOADOPTIONS 형의 값.
d3drmLoadTextureProc
D3DRMLOADTEXTURE3CALLBACK 콜백 함수. 특수한 formatting를 필요로 하는 오브젝트에 의해 사용되는, 임의의 텍스쳐를 로드하기 위해서(때문에) 사용된다. 이 파라미터는 NULL로 할 수 있다.
lpvArg
D3DRMLOADTEXTURE3CALLBACK 콜백 함수에게 건네지는 어플리케이션 정의 데이터의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

디폴트에서는, 이 메소드는lpvObjSource파라미터로 지정되고 있는 소스로부터 최초의 메쉬를 로드한다.

이 메소드는,IDirect3DRM3::SetOptions 가 세트 하는 오른손과 왼손 지오메트리 옵션을 고려한다.

그 로드 메소드를 여러 차례를 호출하는 것으로, 복수의 오브젝트를 로드할 수가 있다.


IDirect3DRMMeshBuilder3

IDirect3DRMMeshBuilder3 메소드 N~Z

이 항은,IDirect3DRMMeshBuilder3 인터페이스의 메소드 가운데, 메소드명이 N로부터 Z의 것을 취하는 레퍼런스 페이지이다.

IDirect3DRMMeshBuilder3::Optimize

IDirect3DRMMeshBuilder3

현재의 디바이스에 대해서MeshBuilder오브젝트를 최적화한다. 이 조작은 고가인 것으로 주의 해야 한다.

구문

HRESULT Optimize
(DWORD dwFlags);

파라미터

dwFlags
0이 아니면 안된다.

반환값

다음의 값중 1개를 돌려준다.
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

IDirect3DRMMeshBuilder3::ReserveSpace

IDirect3DRMMeshBuilder3

지정된 버텍스, 법선, 및 면에 대해서 Direct3DRMMeshBuilder3 오브젝트내의 스페이스를 예약한다. 이것에 의해, 시스템이 메모리를, 보다 효율적으로 사용할 수 있게 된다.

구문

HRESULT ReserveSpace(
  DWORD vertexCount,
  DWORD normalCount,
  DWORD faceCount
  );

파라미터

vertexCount, normalCount, faceCount
스페이스를 할당하는 버텍스, 법선, 및 면의 수.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMMeshBuilder3::Save

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트를 보존한다.

구문

HRESULT Save(
  const char * lpFilename,
  D3DRMXOFFORMAT d3drmXOFFormat,
  D3DRMSAVEOPTIONS d3drmSOContents
  );

파라미터

lpFilename
생성 하는 파일의 이름을 지정하는 주소. 이 파일의 파일명 확장자(extension)는,. x가 아니면 안된다.
d3drmXOFFormat
D3DRMXOFFORMAT 열거형의 D3DRMXOF_TEXT값.
d3drmSOContents
보존 옵션을 지정하는D3DRMSAVEOPTIONS 형의 값.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMMeshBuilder3::Scale

IDirect3DRMMeshBuilder3

지정의 스케일링 팩터를 사용해모델 좌표로 x축, y축, z축으로 평행에 Direct3DRMMeshBuilder3 오브젝트를 스케일링 한다.

구문

HRESULT Scale(
  D3DVALUE sx,
  D3DVALUE sy,
  D3DVALUE sz
  );

파라미터

sx, sy, sz
x축, y축, z축으로 따라 적용되는 스케일링 팩터.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMMeshBuilder3::SetColor

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트의 모든 면으로 지정의 색을 설정한다.

구문

HRESULT SetColor(
  D3DCOLOR color
  );

파라미터

color
면의 색. 적, 초록, 파랑의 색요소 뿐만이 아니라, 알파 요소도 반드시 세트 한다. 그렇게 하지 않으면 오브젝트가 가시가 되지 않는 것이 있다. RGBA_MAKE DirectX 매크로에 의해 이러한 값을 지정할 수가 있다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMMeshBuilder3::SetColorRGB

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트의 모든 면으로 지정의 색을 설정한다.

구문

HRESULT SetColorRGB(
  D3DVALUE red,
  D3DVALUE green,
  D3DVALUE blue
  );

파라미터

red, green, blue
색의 적, 초록, 파랑의 각 성분.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMMeshBuilder3::SetColorSource

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트의 색소스를 설정한다.

구문

HRESULT SetColorSource(
  D3DRMCOLORSOURCE source
  );

파라미터

source
사용하는 새로운 색소스 지정하는D3DRMCOLORSOURCE 열거형의 멤버.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMMeshBuilder3::GetColorSource

IDirect3DRMMeshBuilder3::SetMaterial

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트의 모든 면의 머트리얼을 설정한다.

구문

HRESULT SetMaterial(
  LPDIRECT3DRMMATERIAL2 lpIDirect3DRMmaterial
  );

파라미터

lpIDirect3DRMmaterial
Direct3DRMMeshBuilder3 오브젝트의IDirect3DRMMaterial2 인터페이스의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMMeshBuilder3::SetNormal

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트의 지정되고 있는 버텍스의법선 벡터를 설정한다.

구문

HRESULT SetNormal(
  DWORD index,
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z
  );

파라미터

index
세트 하는 법선의 인덱스.
x, y, z
지정의 법선에 할당하는 벡터의 x, y, z의 각 요소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMMeshBuilder3::SetNormals

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트중에 이전에 정의한 법선을 설정한다.

구문

HRESULT SetNormals(
  DWORD dwFirst,
  DWORD dwCount,
  LPD3DVECTOR lpdvVector);

파라미터

dwFirst
수정하는 최초의 법선의 인덱스.
dwCount
수정하는 법선의 수.
lpdvVector
새로운 법선 데이터를 기술하는 벡터의 배열.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_OUTOFRANGE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

참조

GetNormals

IDirect3DRMMeshBuilder3::SetPerspective

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트에 대한 퍼스펙티브 보정 텍스쳐 맵핑을 enable 또는 디세블로 한다.

구문

HRESULT SetPerspective(
  BOOL perspective
  );

파라미터

perspective
메쉬를 퍼스펙티브 보정으로 텍스쳐 맵 할 필요가 있으면 TRUE를, 그렇지 않으면 FALSE를 지정한다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMMeshBuilder3::SetQuality

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트에 대한 렌더링 퀄리티를 설정한다.

구문

HRESULT SetQuality(
  D3DRMRENDERQUALITY quality
  );

파라미터

quality
사용하는 새로운 렌더링 퀄리티를 지정하는D3DRMRENDERQUALITY 열거형의 멤버.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

오브젝트 퀄리티에는, 3개의 컴퍼넌트가 있다. 즉, 쉐이딩 모드 (플랫 또는 굿 로. 폰은 이행 되지 않고, 디폴트로 gouraud shading이 된다), 조명 타입 (온 또는 오프) 및 전부 칠해 모드 (포인트, 와이어 프레임 또는 솔리드)이다.

디바이스의 퀄리티를 설정하려면 ,IDirect3DRMDevice3::SetQuality 를 이용한다. 디폴트로, 디바이스 퀄리티는 D3DRMRENDER_FLAT (flat shading, 조명 온 및 솔리드 전부 칠해)이다.

Direct3DRMMeshBuilder3 오브젝트의 퀄리티를 설정하려면 ,SetQuality메소드를 이용한다. 디폴트로, Direct3DRMMeshBuilder3 오브젝트의 퀄리티는 D3DRMRENDER_GOURAUD (gouraud shading, 조명 온 및 솔리드 전부 칠해)이다.

힌트: gouraud shading는, 상세 레벨을 빈번하게 또는 재빠르게 변경하는 프로그래시브 메쉬 오브젝트에 대해, 폰 쉐이딩보다 좋은 퍼포먼스를 얻을 수 있다.

Direct3D 보관 유지 모드는, 디바이스나 오브젝트의 각각의 컴퍼넌트에 대한 현재의 설정 중(안)에서 가장 저위의 퀄리티로, 오브젝트에 렌더링을 실시한다. 예를 들어, 오브젝트의 현재의 퀄리티 설정이 D3DRMRENDER_GOURAUD로, 디바이스가 D3DRMRENDER_FLAT이라고, 오브젝트는 flat shading, 솔리드 전부 칠해, 및 조명 온으로 렌더링 된다.

오브젝트의 현재의 퀄리티 설정이 D3DRMSHADE_GOURAUD|D3DRMLIGHT_OFF|D3DRMFILL_WIREFRAME로, 디바이스의 퀄리티 설정이 D3DRMSHADE_FLAT|D3DRMLIGHT_ON|D3DRMFILL_POINT이라고, 오브젝트는 flat shading, 조명 오프, 및 포인트 전부 칠해 모드로 렌더링 된다.

이러한 룰은, Direct3DRMMeshBuilder3 오브젝트 및 Direct3DRMProgressiveMesh 오브젝트에 적용된다. 그러나, Direct3DRMMesh 오브젝트는 이러한 룰에 따르지 않다. 메쉬 오브젝트는 디바이스의 퀄리티 설정을 무시해, 그룹 퀄리티 설정을 이용한다(디폴트로 D3DRMRENDER_GOURAUD).

참조

IDirect3DRMMeshBuilder3::GetQuality

IDirect3DRMMeshBuilder3::SetTexture

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트의 모든 면의 텍스쳐를 설정한다.

구문

HRESULT SetTexture(
  LPDIRECT3DRMTEXTURE3 lpD3DRMTexture
  );

파라미터

lpD3DRMTexture
필요한 Direct3DRMTexture 오브젝트의 주소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMMeshBuilder3::SetTextureCoordinates

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트의 지정되고 있는 버텍스의 텍스쳐 좌표를 설정한다.

구문

HRESULT SetTextureCoordinates(
  DWORD index,
  D3DVALUE u,
  D3DVALUE v
  );

파라미터

index
세트 하는 버텍스의 인덱스.
u, v
지정의 메쉬 버텍스에 할당하는 텍스쳐 좌표.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMMeshBuilder3::GetTextureCoordinates

IDirect3DRMMeshBuilder3::SetTextureTopology

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트의 텍스쳐 토폴러지를 설정한다.

구문

HRESULT SetTextureTopology(
  BOOL cylU,
  BOOL cylV
  );

파라미터

cylU, cylV
원통형 토폴러지를, 각각 u차원 및 v차원에서 텍스쳐에 갖게하고 싶은 경우, 이 2개의 파라미터의, 적어도 한편에 TRUE를, 그렇지 않은 경우에는, FALSE를 지정한다.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

주의

텍스쳐 토폴러지 플래그,cylU와cylV는 Direct3D 직접 모드 렌더링 상태D3DRENDERSTATE_WRAPU,D3DRENDERSTATE_WRAPV의 설정을 제어한다. 랩핑 플래그가 TRUE 때, 래스터라이저는, 그것이 2개의 텍스쳐 좌표간에 짧은 편의 패스이면, 텍스쳐의 하나의 옆으로부터 반대측의 옆에 횡단 (토로이달 맵핑)한다. 1개의 옆을 따라 0.1에서 0.9의 범위의 v좌표를 가지는 삼각형이 있다고 한다. WRAPV가 FALSE이면, 텍스쳐의 거의 전체 길이가 삼각형에 따라 렌더링 된다. WRAPV가 TRUE이면, 텍스쳐의 상부와 하부의 스라이바가 렌더링 된다. 게다가 랩핑 플래그가 TRUE 때, 텍스쳐 좌표의 일부분만큼이 1.0보다 큰 값을 가진다고 보이기 (위해)때문에, 랩이 TRUE 때 텍스쳐는 면을 따라 타일화 되지 않게 된다.

랩핑 동작의 제어는, 텍스쳐 좌표의 올바른 해석에 있어 필요하다. 단일의 텍스쳐가 많은 면을 따라 랩 되고 있는 경우,cylU와cylV파라미터를 TRUE에 세트 한다. 모델이 면 당 1개의 텍스쳐 밖에 가지지 않는가, 또는 1보다 큰 텍스쳐 좌표를 사용해 텍스쳐의 복수의 카피를 단일의 면을 따라 타일화하는 경우,cylU와cylV를 FALSE에 세트 한다.

몇개의 인터페이스는,SetTextureTopology메소드를 에크스포즈 한다. IDirect3DRMMeshBuilder3::SetTextureTopology는, 모든 요소 얼굴의 토폴러지를 갱신해,IDirect3DRMFace2::SetTextureTopology 에 의한 설정을 오버라이드(override) 한다. 디폴트에서는,IDirect3DRMFrame3::SetTexture 는, 디폴트의 머트리얼 모드가D3DRMMATERIAL_FROMMESH 이기 (위해)때문에, 메쉬를 읽어들인다. 머트리얼 모드가D3DRMMATERIAL_FROMMESH가 아닌 경우,IDirect3DRMFrame3::SetTexture는IDirect3DRMMeshBuilder3::SetTextureTopology에 의한 설정을 오버라이드(override) 한다.

IDirect3DRMMeshBuilder3::SetVertex

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트의 지정되고 있는 버텍스의 위치를 설정한다.

구문

HRESULT SetVertex(
  DWORD index,
  D3DVALUE x,
  D3DVALUE y,
  D3DVALUE z
  );

파라미터

index
세트 하는 버텍스의 인덱스.
x, y, z
지정의 버텍스에 할당하는 위치의 x, y, z의 각 요소.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMMeshBuilder3::SetVertexColor

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트의 지정되고 있는 버텍스의 색을 설정한다.

구문

HRESULT SetVertexColor(
  DWORD index,
  D3DCOLOR color
  );

파라미터

index
세트 하는 버텍스의 인덱스.
color
지정의 버텍스에 할당하는 색.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

참조

IDirect3DRMMeshBuilder3::GetVertexColor

IDirect3DRMMeshBuilder3::SetVertexColorRGB

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트의 지정되고 있는 버텍스의 색을 설정한다.

구문

HRESULT SetVertexColorRGB(
  DWORD index,
  D3DVALUE red,
  D3DVALUE green,
  D3DVALUE blue
  );

파라미터

index
세트 하는 버텍스의 인덱스.
red, green, blue
지정의 버텍스에 할당하는 색의 적, 초록, 파랑의 각 성분.

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.

IDirect3DRMMeshBuilder3::SetVertices

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3오브젝트중에 이전에 정의한 버텍스를 설정한다.

구문

HRESULT SetVertices(
  DWORD dwFirst,
  DWORD dwCount,
  LPD3DVECTOR lpdvVector);

파라미터

dwFirst
수정하는 최초의 버텍스의 인덱스.
dwCount
수정하는 버텍스의 수.
lpdvVector
새로운 버텍스 데이터를 기술하는 벡터의 배열.

반환값

다음의 값중 1개를 돌려준다.
D3DRMERR_OUTOFRANGE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DD_OK

주의

이 메소드는, DirectX version 6.0과 함께 도입되었다.

참조

GetVertices

IDirect3DRMMeshBuilder3::Translate

IDirect3DRMMeshBuilder3

Direct3DRMMeshBuilder3 오브젝트의 버텍스의 위치로 지정의 오프셋(offset)를 덧셈 한다.

구문

HRESULT Translate(
  D3DVALUE tx,
  D3DVALUE ty,
  D3DVALUE tz
  );

파라미터

tx, ty, tz
각 버텍스 위치의 x좌표, y좌표, z좌표에 추가되는 오프셋(offset).

반환값

성공하면 D3DRM_OK, 실패하면 에러를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 반환값」을 참조할것.


Direct3DRMFrame3 메소드 A~M

이 항은,Direct3DRMFrame3 인터페이스의 메소드 가운데, 메소드명이 A로부터 M의 것을 취하는 레퍼런스 페이지이다.

Direct3DRMFrame3.AddChild

Direct3DRMFrame3

아이 프레임을 프레임 계층에 추가한다.

구문

object. AddChild(child As Direct3DRMFrame3)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
child
자식으로 추가하는Direct3DRMFrame3오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

자식으로 추가하는 프레임에, 이미 친프레임이 존재하는 경우에는, 이 메소드는, 그 프레임을 현재의 부모로부터 삭제한 후에 새로운 부모에게 추가한다.

오브젝트의 변환을 보존하기 위해서는,Direct3DRMFrame3.GetTransform 메소드를 사용해AddChild메소드를 사용하기 전에 오브젝트의 변환을 취득한다. 그 후, 프레임이 추가된 다음에 그 변환을 재적용한다.

Direct3DRMFrame3.AddLight

Direct3DRMFrame3

조명을 프레임에 추가한다.

구문

object. AddLight(val As Direct3DRMLight)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
val
프레임에 추가하는Direct3DRMLight 오브젝트를 나타내는 변수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrame3.AddMoveCallback

Direct3DRMFrame3

특수한 운동의 처리용으로 콜백을 추가한다. 프레임의 이동시 또는 갱신시에, 이 콜백이 불려 간다.

구문

object. AddMoveCallback(frameMoveImplementation As Direct3DRMFrameCallback3
  userArgument As object,
  flags As CONST_D3DRMCALLBACKORDERFLAGS)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
frameMoveImplementation
어플리케이션에 의해 이행 되는Direct3DRMFrameCallback3 인터페이스.
userArgument
콜백에게 건네지는 어플리케이션 정의의 데이터.
flags
CONST_D3DRMCALLBACKORDERFLAGS 열거형으로부터의 하나 이상의 값.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMFrame2.AddMoveCallback2를 치환한다. 각각의 프레임에 대한 복수의 콜백은, 콜백의 생성순서에 불려 간다.

참조

Direct3DRMFrame3.DeleteMoveCallback

Direct3DRMFrame3.AddRotation

Direct3DRMFrame3

특정의 좌표에 대한 회전이 지정된 라디안으로 추가한다.

구문

object. AddRotation(combineType As CONST_D3DRMCOMBINETYPE,
  x As Single,
  y As Single,
  z As Single,
  theta As Single)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
combineType
새로운 회전을 현재의 임의의 프레임 변환과 결합하는 방법을 지정하는CONST_D3DRMCOMBINETYPE 열거형의 멤버.
x, y, z
회전축.
theta
라디안 단위의 회전각.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

지정의 회전은, 이Direct3DRMFrame3 인터페이스가 식별하는 프레임에 대한 행렬만을 변경한다. 이 메소드는, 렌더링마다 행렬을 변경하는Direct3DRMFrame3.SetRotation 과는 달리 프레임을 한 번 밖에 변경하지 않는다.

Direct3DRMFrame3.AddScale

Direct3DRMFrame3

프레임의 로컬 변환을 특정의 좌표로 스케일링 한다.

구문

object. AddScale(combineType As CONST_D3DRMCOMBINETYPE,
  sx As Single,
  sy As Single,
  sz As Single)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
combineType
새로운 스케일을 현재의 임의의 프레임 변환과 결합하는 방법을 지정하는CONST_D3DRMCOMBINETYPE 열거형의 멤버.
sx, sy, sz
x, y, z의 각방향의 스케일 계수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

지정의 변환은, 이Direct3DRMFrame3 인터페이스가 식별하는 프레임에 대한 행렬만을 변경한다.

Direct3DRMFrame3.AddTransform

Direct3DRMFrame3

지정된 아핀 변환으로 프레임의 로컬 좌표를 변환한다.

구문

object. AddTransform(t As CONST_D3DRMCOMBINETYPE,
  val() As Single)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
t
새로운 변환을 현재의 임의의 변환과 결합하는 방법을 지정하는CONST_D3DRMCOMBINETYPE 열거형의 멤버.
val
4×4 행렬을 나타내는 렬순의 배열.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

4×4 행렬이 주어졌지만, 변환이 아핀 변환이기 위해서(때문에)는, 마지막 열은[0 0 0 1]의 전조가 아니면 안된다. 지정의 변환은, 이Direct3DRMFrame3 인터페이스가 식별하는 프레임에 대한 행렬만을 변경한다.

Direct3DRMFrame3.AddTranslation

Direct3DRMFrame3

프레임의 로컬 좌표계에 특정의 위치 변경에 의한 평행이동을 추가한다.

구문

object. AddTranslation(t As CONST_D3DRMCOMBINETYPE,
  x As Single,
  y As Single,
  z As Single)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
t
새로운 변환을 현재의 임의의 변환과 결합하는 방법을 지정하는CONST_D3DRMCOMBINETYPE 열거형의 멤버.
x, y, z
x, y, z의 각방향에서의 위치 변화를 정의한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

지정의 변환은, 이Direct3DRMFrame3 인터페이스가 식별하는 프레임에 대한 행렬만을 변경한다.

Direct3DRMFrame3.AddVisual

Direct3DRMFrame3

비주얼 오브젝트를 프레임에 추가한다.

구문

object. AddVisual(v As Direct3DRMVisual)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
v
프레임에 추가하는Direct3DRMVisual 오브젝트를 나타내는 변수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

비주얼 오브젝트에는, 메쉬, 프로그래시브 메쉬, 텍스쳐, 그림자, 유저 비주얼, 및 3-D Microsoft® DirectX® 변환 오브젝트가 포함된다. 비주얼 오브젝트가 프레임에 추가되면(자), 비주얼 오브젝트는, 프레임이 뷰중에 있는 경우에 가시 상태가 된다. 프레임은 비주얼 오브젝트를 참조한다.

Direct3DRMFrame3.DeleteChild

Direct3DRMFrame3

계층으로부터 프레임을 삭제한다. 그 프레임이 참조되어 있지 않으면, 아이 프레임, 조명, 및 메쉬의 모든 것이 모두 파기된다.

구문

object. DeleteChild(c As Direct3DRMFrame3)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
c
계층으로부터 삭제되는Direct3DRMFrame3 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrame3.DeleteLight

Direct3DRMFrame3

프레임으로부터 조명을 삭제해, 프레임이 참조되는 것이 없으면 파기한다. 조명이 프레임으로부터 삭제되면(자), 그 프레임이 있던 장면안의 메쉬에 이후 영향을 줄 것은 없다.

구문

object. DeleteLight(l As Direct3DRMLight)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
l
삭제하는Direct3DRMLight 오브젝트를 나타내는 변수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrame3.DeleteMoveCallback

Direct3DRMFrame3

AddMoveCallback 에 의해 추가된 프레임 이동 콜백을 삭제한다.

구문

object. DeleteMoveCallback(frameMoveImplementation As Direct3DRMFrameCallback3,
  userArgument As object)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
frameMoveImplementation
어플리케이션에 의해 이행 되는Direct3DRMFrameCallback3 인터페이스.
userArgument
콜백에게 건네진 어플리케이션 정의의 데이터.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.Move

Direct3DRMFrame3.DeleteVisual

Direct3DRMFrame3

비주얼 오브젝트를 프레임으로부터 삭제해, 이후 참조되지 않는 경우에는 파기한다.

구문

object. DeleteVisual(v As Direct3DRMVisual)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
v
삭제하는Direct3DRMVisual 오브젝트를 나타내는 변수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

비주얼 오브젝트에는, 메쉬, 프로그래시브 메쉬, 텍스쳐, 그림자, 유저 비주얼, 및 3D DirectX 변환 오브젝트가 포함된다. 비주얼 오브젝트가 프레임에 추가되면(자), 비주얼 오브젝트는, 프레임이 뷰중에 있는 경우에 가시 상태가 된다. 프레임은 비주얼 오브젝트를 참조한다.

Direct3DRMFrame3.GetAxes

Direct3DRMFrame3

Direct3DRMFrame3.SetOrientation 메소드에 공급될 방향 벡터 (dx, dy, dz)와 업 벡터 (ux, uy, uz)와 정렬하는 벡터를 취득한다.

구문

object. GetAxes(dir As D3DVECTOR,
  up As D3DVECTOR)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
dir
프레임의 z축. 디폴트는(0,0,1)이다.
up
프레임의 y축. 디폴트는(0,1,0)이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMFrame3.SetAxes 와 함께 일해, 왼손 좌표계와 오른손 좌표계의 양쪽 모두를 지원한다. SetAxes는, 부의 z축이 오브젝트의 전면을 나타내도록(듯이) 지정하는 것을 가능하게 한다.

참조

Direct3DRMFrame3.GetInheritAxes ,Direct3DRMFrame3.SetInheritAxes , D3DVECTOR

Direct3DRMFrame3.GetBox

Direct3DRMFrame3

Direct3DRMFrame3 오브젝트를 포함한 경계 박스를 취득한다. 경계 박스는, 각 차원에서의 최소 및 최대의모델 좌표를 준다.

구문

object. GetBox(box As D3DRMBOX)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
box
경계 박스 좌표를 취득하는D3DRMBOX 형.

에러값

유효한 경계 박스가 이미 프레임에 세트되어 있지 않은 한,D3DRMERR_BOXNOTSET 를 돌려준다. 에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는, 계층적 선별에 대한 프레임 위에의 경계 박스를 지원 한다. 유효한 경계 박스는,Direct3DRMFrame3.SetBox 메소드로 프레임상으로 설정할 필요가 있다. 경계 박스를 유효하게 하려면 ,Direct3DRMFrame3.SetBoxEnable 메소드를 사용해 enable 플래그를 D_TRUE로 할 필요가 있다. 디폴트로, 박스 enable 플래그는 FALSE이다. 디폴트의 경계 박스는 없다.

참조

Direct3DRMFrame3.GetBoxEnable

Direct3DRMFrame3.GetBoxEnable

Direct3DRMFrame3

경계 박스가 이Direct3DRMFrame3오브젝트에 대해서, enable가 되어 있는지 어떤지를 판별하는 플래그를 취득한다.

구문

object. GetBoxEnable( ) As CONST_DBOOLFLAGS

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.

반환값

경계 박스가 enable이면–1, enable가 아니면 0을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

경계 박스를 enable로 하려면 ,Direct3DRMFrame3.SetBoxEnable 메소드를 사용해 enable 플래그를 D_TRUE로 할 필요가 있다. 디폴트에서는, 박스 enable 플래그는 D_FALSE이다.

참조

Direct3DRMFrame3.GetBox , Direct3DRMFrame3.SetBox

Direct3DRMFrame3.GetChildren

Direct3DRMFrame3

Direct3DRMFrameArray 오브젝트의 형식에서, 아이 프레임의 리스트를 취득한다.

구문

object. GetChildren( ) As Direct3DRMFrameArray

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMFrameArray오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrame3.GetColor

Direct3DRMFrame3

프레임의 색을 취득한다.

구문

object. GetColor( ) As Long

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMFrame3 오브젝트의 색을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.SetColor

Direct3DRMFrame3.GetHierarchyBox

Direct3DRMFrame3

이Direct3DRMFrame3 오브젝트를 루트로 하는 계층안의 모든 기하 도형을 포함한 경계 박스를 계산한다.

구문

object. GetHierarchyBox(box As D3DRMBOX)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
box
경계 박스의 좌표를 취득하는D3DRMBOX 형.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.GetBox ,Direct3DRMFrame3.SetBox ,Direct3DRMFrame3.SetBoxEnable ,Direct3DRMFrame3.GetBoxEnable

Direct3DRMFrame3.GetInheritAxes

Direct3DRMFrame3

프레임의 축이 친프레임으로부터 계승한 것일지 어떨지를 나타내는 플래그를 취득한다.

구문

object. GetInheritAxes( ) As CONST_DBOOLFLAGS

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.

반환값

프레임이 축을 계승 하면–1을 돌려주어 (디폴트), 계승하지 않으면 0을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

디폴트에서는, 축은 부모로부터 계승한 것이다. 프레임에 부모로부터의 계승과 설정되어 있어, 부모가 존재하지 않으면, 프레임은 디폴트축(방향=(0,0,1) 업=(0,1,0))을 가지는 부모로부터 계승한 것처럼 동작한다.

이 메소드 및Direct3DRMFrame3.SetInheritAxes 메소드는, 계층 루트로 설정되는 축의 단일의 방침을 허락한다.

참조

Direct3DRMFrame3.GetAxes ,Direct3DRMFrame3.SetAxes

Direct3DRMFrame3.GetLights

Direct3DRMFrame3

Direct3DRMLightArray 오브젝트의 형식에서 프레임중의 조명의 리스트를 취득한다.

구문

object. GetLights( ) As Direct3DRMLightArray

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMLightArray오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrame3.GetMaterial

Direct3DRMFrame3

Direct3DRMFrame3오브젝트의 머트리얼을 취득한다.

구문

object. GetMaterial(ret As Direct3DRMMaterial2)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
ret
프레임에 적용되는Direct3DRMMaterial2 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.SetMaterial

Direct3DRMFrame3.GetMaterialMode

Direct3DRMFrame3

프레임의 머트리얼 모드를 취득한다.

구문

object. GetMaterialMode( ) As CONST_D3DRMMATERIALMODE

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.

반환값

현재의 머트리얼 모드를 지정하는CONST_D3DRMMATERIALMODE 열거형의 멤버를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.SetMaterialMode

Direct3DRMFrame3.GetMaterialOverride

Direct3DRMFrame3

머트리얼 속성에 대한 현재의 속성마다의 오버라이드(override) 설정을 취득한다.

구문

object. GetMaterialOverride(override As D3DRMMATERIALOVERRIDE)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
override
오버라이드(override) 정보를 가지는D3DRMMATERIALOVERRIDE 형.

에러값

메소드가 실패했을 경우는,DDERR_INVALIDOBJECT 또는DDERR_INVALIDPARAMS 를 돌려준다.

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.SetMaterialOverride

Direct3DRMFrame3.GetMaterialOverrideTexture

Direct3DRMFrame3

오버라이드(override) 텍스쳐를 취득한다.

구문

object. GetMaterialOverrideTexture( ) As Direct3DRMTexture3

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.

반환값

오버라이드(override) 텍스쳐가 있는 경우는,Direct3DRMTexture3 오브젝트를 돌려준다. 그렇지 않으면, NOTHING를 돌려준다.

에러값

메소드가 실패했을 경우,DDERR_INVALIDOBJECT 또는DDERR_INVALIDPARAMS 를 돌려준다.

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것. .

참조

Direct3DRMFrame3.SetMaterialOverrideTexture

Direct3DRMFrame3.GetOrientation

Direct3DRMFrame3

지정의 참조 프레임을 기준으로 하는 프레임의 방향을 취득한다.

구문

object. GetOrientation(ref As Direct3DRMFrame3,
  dir As D3DVECTOR,
  up As D3DVECTOR)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
ref
참조에 사용되는Direct3DRMFrame3 오브젝트를 나타내는 변수.
dir, up
각각 프레임의 z축 및 y축의 정규화된 방향이 설정된D3DVECTOR 형.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.SetOrientation

Direct3DRMFrame3.GetParent

Direct3DRMFrame3

현재의 프레임의 친프레임을 취득한다.

구문

object. GetParent( ) As Direct3DRMFrame3

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMFrame3 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrame3.GetPosition

Direct3DRMFrame3

지정의 참조 프레임을 기준으로 하는 프레임의 위치를 취득한다. 즉, 참조 프레임으로부터의 프레임의 거리를 취득한다. 거리는, 직선적인 값은 아니고, 벡터로서position파라미터에 저장 된다.

구문

object. GetPosition(ref As Direct3DRMFrame3,
  position As D3DVECTOR)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
ref
참조로서 사용되는Direct3DRMFrame 오브젝트를 나타내는 변수.
position
프레임의 위치가 세트 되는D3DVECTOR 형.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.SetPosition

Direct3DRMFrame3.GetRotation

Direct3DRMFrame3

지정의 참조 프레임을 기준으로 하는 프레임의 회전을 취득한다.

구문

object. GetRotation(ref As Direct3DRMFrame3,
  axis As D3DVECTOR,
  theta As Single)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
ref
참조로서 사용되는Direct3DRMFrame3 오브젝트를 나타내는 변수.
axis
프레임의 회전축이 세트 되는D3DVECTOR 형.
theta
라디안 단위의 프레임의 회전이 되는 변수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.SetRotation

Direct3DRMFrame3.GetScene

Direct3DRMFrame3

지정의 프레임을 포함한 계층의루트 프레임을 취득한다.

구문

object. GetScene( ) As Direct3DRMFrame3

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMFrame3오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrame3.GetSceneBackground

Direct3DRMFrame3

장면의 배경색을 취득한다.

구문

object. GetSceneBackground( ) As Long

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.

반환값

색을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrame3.GetSceneBackgroundDepth

Direct3DRMFrame3

장면의 현재의 배경 깊이 버퍼를 취득한다.

구문

object. GetSceneBackgroundDepth( ) As DirectDrawSurface4

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.

반환값

DirectDrawSurface4오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.SetSceneBackgroundDepth

Direct3DRMFrame3.GetSceneFogColor

Direct3DRMFrame3

장면의 포그(안개:fog)색을 취득한다.

object. GetSceneFogColor( ) As Long

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.

반환값

포그(안개:fog)색을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrame3.GetSceneFogEnable

Direct3DRMFrame3

현재 이 장면에 대해서 포그(안개:fog)가 enable 되고 있는지 어떤지를 취득한다.

구문

object. GetSceneFogEnable( ) As CONST_DBOOLFLAGS

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.

반환값

포그(안개:fog)가 enable 되고 있으면–1, enable되어 있지 않으면 0을 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrame3.GetSceneFogMethod

Direct3DRMFrame3

현재의 포그(안개:fog) 메소드를 취득한다.

구문

object. GetSceneFogMethod( ) As CONST_D3DRMFOGMETHOD

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.

반환값

CONST_D3DRMFOGMETHOD 열거형으로부터 값을 1개돌려준다.

에러값

에러가 발생했을 경우는, 다음의 값 가운데 하나를 돌려준다.

  • D3DRMERR_BADVALUE
  • DDERR_INVALIDOBJECT
  • DDERR_INVALIDPARAMS

Direct3DRMFrame3.GetSceneFogMode

Direct3DRMFrame3

이 장면에 대한 현재의 포그(안개:fog) 모드를 돌려준다.

구문

object. GetSceneFogMode( ) As CONST_D3DRMFOGMODE

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.

반환값

현재의 포그(안개:fog) 모드를 지정하는CONST_D3DRMFOGMODE 열거형의 멤버를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrame3.GetSceneFogParams

Direct3DRMFrame3

이 장면에 대한 현재의 포그(안개:fog) 파라미터를 취득한다.

구문

object. GetSceneFogParams(start As Single,
  end As Single,
  density As Single)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
start, end, density
포그(안개:fog) 시작, 종료 및 밀도값이 되는 변수.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrame3.GetSortMode

Direct3DRMFrame3

아이 프레임을 처리하는데 사용되는 소트 모드를 취득한다.

구문

object. GetSortMode( ) As CONST_D3DRMSORTMODE

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.

반환값

소트 모드를 지정하는CONST_D3DRMSORTMODE 열거형의 멤버를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.SetSortMode

Direct3DRMFrame3.GetTexture

Direct3DRMFrame3

지정 프레임의 텍스쳐를 취득한다.

구문

object. GetTexture( ) As Direct3DRMTexture3

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMTexture3 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.SetTexture

Direct3DRMFrame3.GetTransform

Direct3DRMFrame3

프레임의 로컬 변환을 4×4 아핀 행렬로서 취득한다.

구문

object. GetTransform(referenceFrame As Direct3DRMFrame3
  val() As Single)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
referenceFrame
참조 프레임으로서 사용되는Direct3DRMFrame3 오브젝트.
val
4×4 행렬을 나타내는 렬순의 배열.

에러값

에러가 발생했을 경우는,DDERR_INVALIDOBJECT 또는DDERR_INVALIDPARAMS 를 돌려준다.

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrame3.GetTraversalOptions

Direct3DRMFrame3

현재의 프레임의 횡단 상태를 취득한다.

구문

object. GetTraversalOptions( ) As CONST_D3DRMTRAVERALFLAGS

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.

반환값

CONST_D3DRMTRAVERALFLAGS 열거형으로부터 값을 1개돌려준다.

에러값

에러가 발생했을 경우는, 다음의 값 가운데 하나를 돌려준다.

  • D3DRMERR_BADVALUE
  • DDERR_INVALIDOBJECT
  • DDERR_INVALIDPARAMS

Direct3DRMFrame3.GetVelocity

Direct3DRMFrame3

지정의 참조 프레임을 기준으로 하는 프레임의 속도를 취득한다. 속도는, 틱 당의 단위로 지정된다. 상세한 것에 대하여는, 「IDirect3DRM3.Tick 」를 참조할것.

구문

object. GetVelocity(ref As Direct3DRMFrame3,
  vel As D3DVECTOR,
  includeRotationalVelocity As CONST_DBOOLFLAGS)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
ref
참조로서 사용되는Direct3DRMFrame3 오브젝트를 나타내는 변수.
vel
프레임의 속도가 세트 되는D3DVECTOR 형.
includeRotationalVelocity
D_FALSE 또는 D_TRUE. D_TRUE의 경우, 오브젝트의 회전 속도가 계산에 포함된다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.SetVelocity

Direct3DRMFrame3.GetVisual

Direct3DRMFrame3

프레임중의 비주얼을 1개 취득한다.

구문

object. GetVisual(index As Long) As Direct3DRMVisual

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
index
취득하는 단일의Direct3DRMVisual 오브젝트의 인덱스를 나타내는 변수. 사이즈 N의 배열에 대해서 지정할 수 있는 값의 범위는, 0~N이다.

반환값

Direct3DRMVisual오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrame3.GetVisualCount

Direct3DRMFrame3

프레임중의 비주얼의 수를 취득한다.

구문

object. GetVisualCount( ) As Long

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.

반환값

프레임에 포함되는 비주얼수를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrame3.GetVisuals

Direct3DRMFrame3

프레임중의 비주얼의 리스트를 취득한다.

구문

object. GetVisuals( ) As Direct3DRMVisualArray

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.

반환값

Direct3DRMVisualArray 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrame3.GetZbufferMode

Direct3DRMFrame3

Z버퍼 모드를 취득한다. 즉, Z버퍼링이 enable 또는 디세블일지 어떨지를 확인한다.

구문

object. GetZbufferMode( ) As CONST_D3DRMZBUFFERMODE

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.

반환값

CONST_D3DRMZBUFFERMODE 열거형의 멤버의 하나를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.SetZbufferMode

Direct3DRMFrame3.InverseTransform

Direct3DRMFrame3

월드 좌표의 지정 벡터를모델 좌표로 변환해, 그 결과를 돌려준다.

구문

object. InverseTransform(d As D3DVECTOR,
  s As D3DVECTOR)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
d
변환의 결과가 세트 되는D3DVECTOR 형.
s
변환의 소스인D3DVECTOR형.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.Transform

Direct3DRMFrame3.InverseTransformVectors

Direct3DRMFrame3

벡터의 배열을월드 좌표로부터모델 좌표로 변환한다.

구문

object. GetVelocity(reference As Direct3DRMFrame3,
  num As Long,
  DstVectors() As D3DVECTOR,
  SrcVectors() As D3DVECTOR)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
reference
이 호출을 위해서(때문에) 장면의 루트로서 사용되는 프레임. 이 인수가 NOTHING의 경우, 현재의 루트 프레임 (Direct3DRMFrame3.GetScene 가 돌려주는 프레임)이 사용된다.
num
좌표를 변환할 필요가 있는 벡터수.
DstVectors()
변환의 출력처.
SrcVectors()
변환하는 벡터의 배열.

에러값

에러가 발생했을 경우는,DDERR_INVALIDOBJECT 또는DDERR_INVALIDPARAMS 를 돌려준다.

참조

D3DVECTOR

Direct3DRMFrame3.LoadFromFile

Direct3DRMFrame3

Direct3DRMFrame3오브젝트를 로드한다.

구문

object. LoadFromFile(filename As String,
  id As String,
  options As CONST_D3DRMLOADFLAGS,
  loadTextureImplementation As Direct3DRMLoadTextureCallback3,
  userArgument As Object)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
filename
로드하는 오브젝트의 소스. 이 소스는,flags파라미터로 지정되고 있는 소스 플래그에 따라, 파일, 리소스, 메모리 블록, 또는 스트림의 어느 쪽인가에 할 수 있다.
id
로드하는 오브젝트의 이름 또는 위치. id가""의 경우는,options파라미터를D3DRMLOAD_FIRST로 설정한다. Microsoft Visual Basic® 는,String데이터형이 지정되고 있는 경우에서도, 로드하는 아이템의 위치를 나타내는id파라미터안의Integer를 받아들인다. 예를 들어,id파라미터에1이 설정되어 있으면(자), 1번째의 위치의 오브젝트가 로드 된다.
options
로드 옵션을 기술하는CONST_D3DRMLOADFLAGS 열거형의 하나 이상의 값.
loadTextureImplementation
특수한 formatting를 요구하는 오브젝트에 의해 사용되는, 임의의 텍스쳐를 로드하기 위해서(때문에) 불려 가는Direct3DRMLoadTextureCallback3 인터페이스. 텍스쳐는, 2로 갈라지는 폭과 길이가 아니면 안된다. 이 파라미터는 NOTHING로 할 수 있다.
userArgument
콜백에게 건네지는 어플리케이션 정의의 데이터.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

디폴트에서는, 이 메소드는,filename파라미터로 지정되고 있는 파일중의 최초의 프레임 계층을 로드한다. 이 메소드를 호출한 프레임은, 새로운 프레임 계층의 부모로서 사용된다. 디폴트에서는, 퍼스펙티브 보정이온이다.

인스턴스 플래그는, 파라미터의 해석 방법에는 아무것도 변경을 더하지 않는다. D3DRMLOAD_INSTANCEBYREFERENCE플래그를 이용하면(자), 새로운 오브젝트를 생성 하는 일 없이 같은 파일을 2회 로드할 수가 있다. 오브젝트가 이름을 가지고 있지 않은 경우,D3DRMLOAD_INSTANCEBYREFERENCE플래그를 세트 하면,D3DRMLOAD_INSTANCEBYCOPYING플래그를 세트 했을 때와 같은 효과를 얻을 수 있다. 로더는, 동일한 오브젝트가 존재해도, 각 이름 없음 오브젝트를 새로운 오브젝트로서 생성 한다.

Direct3DRMFrame3.LookAt

Direct3DRMFrame3

지정의 참조 프레임을 기준으로서 지정의 제약에 의해 회전을 잠근 상태로 프레임을 대상의 프레임에 직면시킨다.

구문

object. LookAt(tgt As Direct3DRMFrame3,
  reference As Direct3DRMFrame3,
  contraint As CONST_D3DRMFRAMECONSTRAINT)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
tgt, reference
각각, 대상 및 참조로서 사용되는Direct3DRMFrame3 오브젝트를 나타내는 변수.
contraint
제약하는 축회전을 지정하는CONST_D3DRMFRAMECONSTRAINT 열거형.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrame3.Move

Direct3DRMFrame3

직선과 회전의 속도를 지정의 계층의 모든 프레임에 적용한다.

구문

object. Move(delta As Single)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
delta
직선과 회전 속도에 대한 변화량. 각 요소에 있어서의 변경은, 그 요소의 속도× delta에 동일하다. 이러한 한편 또는 양쪽 모두의 속도는, 임의의 프레임을 기점으로서 설정할 수가 있지만, 시스템은, 자동적으로 델타 시간을 적용하므로, 친프레임을 기점으로 한 속도로 변환한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.


Direct3DRMFrame3 메소드 N~Z

이 항은,Direct3DRMFrame3 인터페이스의 메소드 가운데, 메소드명이 N로부터 Z의 것을 취하는 레퍼런스 페이지이다.

Direct3DRMFrame3.RayPick

Direct3DRMFrame3

이Direct3DRMFrame3오브젝트를 기점으로서 계층을 검색해, 임의의 비주얼과refer파라미터에 의해 참조되는Direct3DRMFrame3 인터페이스로 지정되는 광선과의 교차 부분을 계산한다.

구문

object. RayPick(refer As Direct3DRMFrame3,
  ray As D3DRMRAY,
  flags As CONST_D3DRMRAYPICKFLAGS) As Direct3DRMPick2Array

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
refer
광선을 포함한Direct3DRMFrame3 오브젝트.
ray
2개의D3DVECTOR 형을 포함한D3DRMRAY 형. 최초의D3DVECTOR형은, 광선의 벡터 방향이다. 2번째의D3DVECTOR형은, 광선의 원점의 위치이다.
flags
계산되는 교차 부분의 타입 또는 보간 옵션을 나타내는CONST_D3DRMRAYPICKFLAGS 열거형으로부터의 하나 이상의 값.

반환값

Direct3DRMPick2Array 오브젝트를 돌려준다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

플래그에는, 최적화 플래그와 보간 플래그의 2 종류가 있다. 최적화 플래그는, 검색을 제한할 수가 있어 따라 그것을 고속으로 한다. 보간 플래그는, 원시적으로 맞닥뜨렸을 때에 무엇을 보간해야할 것인가 지정한다. 3개의 보간 선택사항은, 색, 법선 및 텍스쳐 좌표이다.

광선은, 참조 프레임 좌표 공간에서 지정된다(refer가 가리킨다). 참조 프레임이 NOTHING의 경우에는, 광선은,월드 좌표로 지정된다.

Direct3DRMFrame3.Save

Direct3DRMFrame3

지정한 파일에Direct3DRMFrame3오브젝트를 보존한다.

구문

object. Save(name As String,
  format As CONST_D3DRMXOFFORMAT,
  flags As CONST_D3DRMSAVEFLAGS)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
name
생성 한 파일의 이름. 이 파일은,. x파일명 확장을 가지지 않으면 안 된다.
format
파일이 텍스트 포맷인 것을 나타내는CONST_D3DRMXOFFORMAT 열거형으로부터의D3DRMXOF_TEXT값.
flags
보존 옵션을 기술하는CONST_D3DRMSAVEFLAGS 열거형의 하나 이상의 값.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrame3.SetAxes

Direct3DRMFrame3

Direct3DRMFrame3.SetOrientation 벡터를 변환하는 좌표 공간을 정의하는 벡터를 설정한다.

구문

object. SetAxes(dx As Single,
  dy As Single,
  dz As Single,
  ux As Single,
  uy As Single,
  uz As Single)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
dx, dy, dz
프레임의 z축. 디폴트는(0,0,1)이다.
ux, uy, uz
프레임의 y축. 디폴트는(0,1,0)이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는, 왼손 좌표계와 오른손 좌표계의 양쪽 모두를 지원한다. 또, 부의 z축이 오브젝트의 전면을 나타내도록(듯이) 지정하는 일도 가능하게 한다.

Direct3DRMFrame3.SetOrientation방향 벡터 (dx, dy, dz)와 업 벡터 (ux, uy, uz)는,SetAxes벡터의 값에 따라 변환된다.

Direct3DRMFrame3.SetInheritAxes 로 지정되고 있도록(듯이), 축은 아이 프레임에 의해 계승된다.

참조

Direct3DRMFrame3.GetAxes ,Direct3DRMFrame3.GetInheritAxes

Direct3DRMFrame3.SetBox

Direct3DRMFrame3

경계 박스 테스트로 사용하는 박스를 설정한다. 경계 박스가 유효하기 때문에 는, 최소 x는 최대 x이하가 아니면 안되어, 최소 y는 최대 y이하가 아니면 안되어, 또 최소 z는 최대 z이하가 아니면 안된다.

구문

object. SetBox(box As D3DRMBOX)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
box
경계 박스 좌표를 포함한D3DRMBOX 형.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는, 계층적 선별에 대한 프레임 위에의 경계 박스를 지원 한다. 경계 박스를 enable로 하려면 ,Direct3DRMFrame3.SetBoxEnable 메소드를 사용해, enable 플래그에 D_TRUE를 세트 해야 한다. 디폴트에서는, 박스 enable 플래그는 D_FALSE이다.

참조

Direct3DRMFrame3.GetBox ,Direct3DRMFrame3.GetBoxEnable

Direct3DRMFrame3.SetBoxEnable

Direct3DRMFrame3

이Direct3DRMFrame3오브젝트에 대해서, 경계 박스 테스트를 enable 또는 디세블 한다. 경계 박스 테스트를 enable로 하려면 , 유효한 경계 박스가 프레임에 이미 설정되어 있지 않으면 안 된다.

구문

object. SetBoxEnable(boxEnable As CONST_DBOOLFLAGS)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
boxEnable
경계 박스가 enable인가 어떤가를 지정하는 플래그. 경계 박스를 enable로 하려면 D_TRUE를, 경계 박스를 디세블로 하려면 D_FALSE를 지정한다. 디폴트는 D_FALSE이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

경계 박스 테스트는, 이하와 같이 실시한다. 렌더링시에는, 경계 박스는 모델 공간으로 변환해,절두체와의 교차 부분이 없는가 조사한다. 박스 전체가 절두체의 밖에 있는 경우, 프레임이나 아이 프레임에 있는 비주얼의 렌더링은 실시하지 않는다. 그 이외의 경우는, 보통의 렌더링을 계속한다.

{0,0,0,0}의 박스로 경계 박스 테스트를 enable 하면, 프레임은 전혀 렌더링 되지 않는다.

참조

Direct3DRMFrame3.GetBoxEnable ,Direct3DRMFrame3.GetBox ,Direct3DRMFrame3.SetBox

Direct3DRMFrame3.SetColor

Direct3DRMFrame3

프레임의 색을 설정한다. 이 색은,CONST_D3DRMMATERIALMODE 열거형이D3DRMMATERIAL_FROMFRAME인 경우에, 프레임중의 메쉬에 대해서 사용된다.

구문

object. SetColor(c As Long)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
c
프레임의 새로운 색. 적, 초록, 파랑의 색요소 뿐만이 아니라, 알파 요소도 반드시 세트 한다. 그렇게 하지 않으면 오브젝트가 가시가 되지 않는 것이 있다. 오브젝트의 색을 알파 요소를 포함해 지정하려면 , 오브젝트 위에의DirectX7인터페이스로부터CreateColorRGBA메소드를 호출한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.GetColor ,Direct3DRMFrame3.SetMaterialMode

Direct3DRMFrame3.SetColorRGB

Direct3DRMFrame3

프레임의 색을 설정한다. 이 색은,CONST_D3DRMMATERIALMODE 열거형이D3DRMMATERIAL_FROMFRAME인 경우에, 프레임중의 메쉬에 대해서 사용된다.

구문

object. SetColorRGB(r As Single,
  g As Single,
  b As Single)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
r, g, b
프레임의 새로운 색. 색의 각 요소는, 0.0에서 1.0의 범위에 있을 필요가 있다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.SetMaterialMode

Direct3DRMFrame3.SetInheritAxes

Direct3DRMFrame3

프레임의 축이 친프레임으로부터 계승한 것일지 어떨지를 지정한다.

구문

object. SetInheritAxes(inheritFromParent As CONST_DBOOLFLAGS)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
inheritFromParent
프레임이 그 부모로부터 축을 계승할지 어떨지를 나타낸다. D_TRUE의 경우, 프레임은 축을 계승한다(디폴트). D_FALSE의 경우, 프레임은 축을 계승하지 않는다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

디폴트에서는, 축은 부모로부터 계승한 것이다. 프레임에 부모로부터의 계승과 설정되어 있어, 부모가 존재하지 않는 경우에는, 프레임은, 디폴트축(방향=(0,0,1) 업=(0,1,0))을 가지는 부모로부터 계승한 것처럼 동작한다. 이 메소드는, 계층 루트로 설정되는 축의 단일의 방침을 허락한다.

참조

Direct3DRMFrame3.GetInheritAxes , Direct3DRMFrame3.GetAxes ,Direct3DRMFrame3.SetAxes

Direct3DRMFrame3.SetMaterial

Direct3DRMFrame3

Direct3DRMFrame3오브젝트의 머트리얼을 설정한다.

구문

object. SetMaterial(mat As Direct3DRMMaterial2)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
mat
프레임에 적용되는Direct3DRMMaterial 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.GetMaterial

Direct3DRMFrame3.SetMaterialMode

Direct3DRMFrame3

프레임의 머트리얼 모드를 설정한다. 머트리얼 모드는, 프레임과 렌더링 되는 비주얼의 머트리얼 정보의 소스를 결정한다.

구문

object. SetMaterialMode(val As CONST_D3DRMMATERIALMODE)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
val
프레임과 렌더링 되는 비주얼의 머트리얼 정보를 기술하는CONST_D3DRMMATERIALMODE 열거형의 멤버의 하나.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.GetMaterialMode

Direct3DRMFrame3.SetMaterialOverride

Direct3DRMFrame3

고유의 머트리얼 속성을 세트 할 수 있도록(듯이) 한다. 예를 들어, 이 메소드는 머트리얼의방사 프로퍼티만을 오버라이드(override) 할 수 있도록(듯이) 한다.

구문

object. SetMaterialOverride(override As D3DRMMATERIALOVERRIDE)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
override
오버라이드(override) 하는 프로퍼티를 기술하는D3DRMMATERIALOVERRIDE 형.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

오버라이드(override)에서는, 항상 계층을 더듬어 모든 것이 오버라이드(override) 된다. 어느 프레임의 방사 프로퍼티를 오버라이드(override) 하는 경우, 계층을 한층 더 더듬어 같은 프로퍼티를 오버라이드(override) 하려고 해도 무시된다. 이 오버라이드(override)은, 고유의 메쉬 위에의 머트리얼 프로퍼티 뿐만이 아니라, 표준 프레임의 오버라이드(override)보다 우선한다. SetMaterial 나SetTexture 등의 오버라이드(override)는, 이 메소드의 동작에 대해서 어떤 효과도 가지지 않는다.

참조

Direct3DRMFrame3.GetMaterialOverride

Direct3DRMFrame3.SetMaterialOverrideTexture

Direct3DRMFrame3

머트리얼 속성에 대한 현재의 속성마다의 오버라이드(override) 설정을 세트 한다.

구문

object. SetMaterialOverrideTexture(tex As Direct3DRMTexture3)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
tex
오버라이드(override) 텍스쳐로서 설정되는Direct3DRMTexture3 인터페이스.

에러값

메소드가 실패했을 경우는,DDERR_INVALIDOBJECT 또는DDERR_INVALIDPARAMS 를 돌려준다.

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.GetMaterialOverrideTexture

Direct3DRMFrame3.SetOrientation

Direct3DRMFrame3

z방향이 방향 벡터 [dx, dy, dz]와 동방향을 가리켜, y방향이 벡터[ux, uy, uz]와 동방향을 가리키도록(듯이) 프레임을 정렬한다.

구문

object. SetOrientation(reference As Direct3DRMFrame3,
  dx As Single,
  dy As Single,
  dz As Single,
  ux As Single,
  uy As Single,
  uz As Single)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
reference
참조로서 사용되는Direct3DRMFrame 오브젝트를 나타내는 변수.
dx, dy, dz
프레임의 새로운 z축. 벡터의 각 요소는, 1. 0에서 1.0의 범위에 있을 필요가 있다.
ux, uy, uz
프레임의 새로운 y축. 벡터의 각 요소는, 1. 0에서 1.0의 범위에 있을 필요가 있다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

프레임의 디폴트의 방향은, 방향 벡터[0, 0, 1]및 업 벡터[0, 1, 0]을 가진다.

[ux, uy, uz] 가 [dx, dy, dz]에 평행한 경우에는,D3DRMERR_BADVALUE에러값이 돌아온다. 그렇지 않은 경우에는, 건네받은 [ux, uy, uz] 벡터는,[dx, dy, dz]에 수직인 프레인에 투영 된다.

이 메소드는,Direct3DRMFrameInterpolator 오브젝트에 방향 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMFrame3.GetOrientation

Direct3DRMFrame3.SetPosition

Direct3DRMFrame3

참조 프레임을 기준으로 해 프레임의 위치를 설정한다. 프레임을 참조 프레임으로부터 [x, y, z] 의 거리에 둔다. 부모중에 아이 프레임이 생성 되는 경우, 아이 프레임은 친프레임의 [0, 0, 0] 의 위치에 놓여진다.

구문

object. SetPosition(reference As Direct3DRMFrame3,
  x As Single,
  y As Single,
  z As Single)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
reference
참조로서 사용되는Direct3DRMFrame 오브젝트를 나타내는 변수.
x, y, z
프레임의 새로운 위치. 위치에는 단위가 없다. 절두체를 사용해, 적정한 숫자를 선택한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMFrameInterpolator 오브젝트에 위치 키를 추가하기 위해서도 사용한다.

참조

Direct3DRMFrame3.GetPosition

Direct3DRMFrame3.SetQuaternion

Direct3DRMFrame3

단위 4원수를 이용해, 참조 프레임에 대해서 프레임의 방향을 설정한다.

구문

object. SetQuaternion(reference As Direct3DRMFrame3,
  quat As D3DRMQUATERNION)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
reference
참조로서 사용되는Direct3DRMFrame 오브젝트를 나타내는 변수
quat
프레임의 방향을 설정하는D3DRMQUATERNION 형.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

4원수란, 임의의 회전을 나타내기 위해서(때문에) 이용되는 4값벡터로, 방향의 사이에 보간을 실시할 때 유용한 특성을 가지고 있다. 4원수는,s**2 + x**2 + y**2 + z**2 = 1이면 단위 4원수이다.

SetQuaternion메소드는, 인타포레이타에 의해 지원 되고 있다.

Direct3DRMFrame3.SetRotation

Direct3DRMFrame3

Direct3DRM3.Tick 또는Direct3DRMFrame3.Move 메소드에 대한 호출할 것에, 지정의 벡터의 주위로 지정의 각도로 프레임의 회전을 설정한다. 방향 벡터 [x, y, z] 는, 참조 프레임으로 정의된다.

구문

object. SetRotation(reference As Direct3DRMFrame3,
  x As Single,
  y As Single,
  z As Single,
  theta As Single)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
reference
참조로서 사용되는Direct3DRMFrame 오브젝트를 나타내는 변수.
x, y, z
회전의 중심의 벡터. 유효한 값은, 1. 0에서 1.0의 범위에 있을 필요가 있다.
theta
라디안 단위의 회전각. 각도가 크면 큰 만큼, 오브젝트의 회전은 빨라진다. Move와Tick메소드가, 이 값을 스케일링 한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

지정의 회전은, 프레임중의 오브젝트를 한 번 밖에 변경하지 않는Direct3DRMFrame3.AddRotation 메소드와는 달라, 렌더링 마다 행렬을 변경한다.

참조

Direct3DRMFrame3.GetRotation

Direct3DRMFrame3.SetSceneBackground

Direct3DRMFrame3

장면의 배경색을 설정한다.

구문

object. SetSceneBackground(c As Long)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
c
배경의 새로운 색.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMFrameInterpolator 오브젝트에의 배경 컬러 키를 추가하기 위해서도 사용된다.

Direct3DRMFrame3.SetSceneBackgroundDepth

Direct3DRMFrame3

장면의 배경 깊이 버퍼를 지정한다.

구문

object. SetSceneBackgroundDepth(s As DirectDrawSurface4)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
s
장면의 새로운 배경 깊이를 보존하는 Microsoft DirectDraw® 표면.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이미지는 픽셀 단위의 깊이 16을 가지지 않으면 안 된다. 이미지와 뷰포트의 사이즈가 다르면(자), 처음에 이미지의 스케일링을 실시한다. 배경 깊이 버퍼를 애니메이션 할 경우에 최적인 퍼포먼스를 얻으려면 , 이미지는 뷰포트와 같은 사이즈가 아니면 안된다. 그렇다면, 여분의 오버헤드없이, 깊이 버퍼는 이미지 메모리로부터 직접 갱신할 수가 있다.

참조

Direct3DRMFrame3.GetSceneBackgroundDepth

Direct3DRMFrame3.SetSceneBackgroundImage

Direct3DRMFrame3

장면의 배경 이미지를 지정한다.

구문

object. SetSceneBackgroundImage(i As Direct3DRMTexture3)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
i
새로운 배경 신을 포함한Direct3DRMTexture3 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이미지의 사이즈 또는 컬러 깊이가 뷰포트와 다른 경우, 우선 이미지의 스케일링을 실시하는지, 올바른 깊이로 변환한다. 배경을 애니메이션 할 경우에 최적인 퍼포먼스를 얻으려면 , 이미지는 뷰포트와 같은 사이즈 및 컬러 깊이가 아니면 안된다. 그렇다면, 여분의 오버헤드없이, 직접 이미지 메모리로부터 배경의 렌더링을 실시할 수가 있다.

Direct3DRMFrame3.SetSceneBackgroundRGB

Direct3DRMFrame3

장면의 배경색을 설정한다.

구문

object. SetSceneBackgroundRGB(r As Single,
  g As Single,
  b As Single)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
r, g, b
배경의 새로운 색. 색의 각 요소는, 0.0에서 1.0의 범위에 있을 필요가 있다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMFrameInterpolator 오브젝트에 배경 RGB 컬러 키를 추가하기 위해서도 이용된다.

Direct3DRMFrame3.SetSceneFogColor

Direct3DRMFrame3

장면의 포그(안개:fog)색을 설정한다.

구문

object. SetSceneFogColor(c As Long)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
c
포그(안개:fog)의 새로운 색.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMRFrameInterpolator 오브젝트에 포그(안개:fog) 컬러 키를 추가하기 위해서도 이용된다.

Direct3DRMFrame3.SetSceneFogEnable

Direct3DRMFrame3

포그(안개:fog) enable 상태를 설정한다.

구문

object. SetSceneFogEnable(enable As CONST_DBOOLFLAGS)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
enable
새로운 포그(안개:fog) enable 상태. 포그(안개:fog) enable 상태를 무효로 하려면 , 이 파라미터를 D_FALSE로 설정해, 포그(안개:fog) enable 상태를 유효하게 하려면 D_TRUE로 설정한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrame3.SetSceneFogMethod

Direct3DRMFrame3

버텍스 포그(안개:fog) 또는 테이블 포그(안개:fog)를 개입시켜 포그(안개:fog)를 실행할지 어떨지를 지정한다.

구문

object. SetSceneFogMethod(enable As CONST_D3DRMFOGMETHOD)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
enable
포그(안개:fog)의 이행 방법을 나타내는 값. CONST_D3DRMFOGMETHOD 열거형으로부터의 값.

에러값

에러가 발생했을 경우는, 다음의 값 가운데 하나를 돌려준다.

  • D3DRMERR_BADVALUE
  • DDERR_INVALIDOBJECT
  • DDERR_INVALIDPARAMS

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

Direct3DRM3 인터페이스에 의해 생성 되는Direct3DRMFrame3오브젝트의 디폴트의 동작은D3DRMFOGMETHOD_ANY이며, 포그(안개:fog) 메소드는 디바이스의 기능에 근거해 선택된다. 디바이스가 버텍스와 테이블을 기준으로 한 양쪽 모두의 포그(안개:fog)를 지원 하는 경우, 버텍스 포그(안개:fog)가 사용된다. 어플리케이션으로 테이블 포그(안개:fog)가 요구되었지만, 테이블 포그(안개:fog)가 사용 가능하지 않은 경우도, 버텍스 포그(안개:fog)가 사용된다.

Direct3DRMFrame3.SetSceneFogMode

Direct3DRMFrame3

포그(안개:fog) 모드를 설정한다.

구문

object. SetSceneFogMode(c As CONST_D3DRMFOGMODE)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
c
CONST_D3DRMFOGMODE 열거형의 멤버의 하나로, 새로운 포그(안개:fog) 모드를 지정한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.SetSceneFogParams

Direct3DRMFrame3.SetSceneFogParams

Direct3DRMFrame3

장면의 포그(안개:fog) 시작 및 종료 포인트와 포그(안개:fog)의 밀도를 설정한다.

구문

object. SetSceneFogParams(start As Single,
  End As Single,
  density As Single)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
start, End
선형 포그(안개:fog) 모드의 포그(안개:fog) 시작 및 종료 포인트. 이 설정은, 포그(안개:fog) 효과가 최초로 보이게 될 때의카메라로부터의 거리와 포그(안개:fog)가 최대 밀도가 될 때의 거리를 결정한다.
density
지수 포그(안개:fog) 모드에서의 포그(안개:fog) 밀도. 이 값은, 0에서 1의 값이 아니면 안된다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 메소드는,Direct3DRMRFrameInterpolator 오브젝트에 포그(안개:fog) 파라미터 키를 추가하기 위해서도 이용된다.

참조

CONST_D3DRMFOGMODE ,Direct3DRMFrame3.SetSceneFogMode

Direct3DRMFrame3.SetSortMode

Direct3DRMFrame3

아이 프레임을 처리하는데 사용하는 소트 모드를 설정한다. 이 메소드를 사용해 은면삭제 알고리즘의 프로퍼티를 변경할 수가 있다.

구문

object. SetSortMode(val As CONST_D3DRMSORTMODE)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
val
소트 모드를 지정하는CONST_D3DRMSORTMODE 열거형의 멤버의 하나. 디폴트값은,D3DRMSORT_FROMPARENT이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.GetSortMode

Direct3DRMFrame3.SetTexture

Direct3DRMFrame3

프레임의 텍스쳐를 설정한다.

구문

object. SetTexture(t As Direct3DRMTexture3)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
t
사용되는Direct3DRMTexture3 오브젝트.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

주의

이 텍스쳐는,CONST_D3DRMMATERIALMODE 열거형이D3DRMMATERIAL_FROMFRAME인 경우에, 프레임중의 메쉬에 대해서 사용된다. 프레임의 텍스쳐를 디세블로 하려면 , NOTHING 텍스쳐를 사용한다.

참조

Direct3DRMFrame3.GetTexture ,Direct3DRMFrame3.SetMaterialMode

Direct3DRMFrame3.SetTraversalOptions

Direct3DRMFrame3

렌더링과 피킹 시에 이 프레임을 횡단할지 어떨지를 지정한다.

구문

object. SetTraversalOptions(flags As CONST_D3DRMTRAVERALFLAGS)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
flags
이 프레임이 렌더링과 피킹의 어느 쪽이 가능한가 가리키는CONST_D3DRMTRAVERALFLAGS 열거형의 하나 이상의 값. D3DRMFRAME_RENDERENABLE의 값없이 이 메소드를 사용 하면, 렌더링에 대해서 프레임이 효율적으로 오프에 완전히 교체된다. 디폴트에서는, 프레임은 렌더링과 피킹에 대해서 유효하게 된다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

Direct3DRMFrame3.SetVelocity

Direct3DRMFrame3

참조 프레임을 기준으로서 지정의 프레임의 속도를 설정한다. 프레임은,Direct3DRM3.Tick 또는Direct3DRMFrame3.Move 메소드에 대한 연속 호출마다, 참조 프레임을 기준으로서 [x, y, z] 벡터분만큼 이동한다.

구문

object. SetVelocity(reference As Direct3DRMFrame3,
  x As Single,
  y As Single,
  z As Single,
  with_rotation As CONST_DBOOLFLAGS)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
reference
참조로서 사용되는Direct3DRMFrame 오브젝트
x, y, z
프레임의 새로운 속도. 회전 속도는 단위를 가지지 않고, 임의의 값을 세트 할 수 있다. Move와Tick메소드는, 이 값을 스케일링 한다.
with_rotation
직선 속도를 설정할 경우에, 오브젝트의 회전 속도를 고려할지 어떨지를 지정하는 플래그. D_TRUE의 경우, 오브젝트의 회전 속도가 계산에 포함된다. 그렇지 않으면, D_FALSE를 설정한다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.GetVelocity

Direct3DRMFrame3.SetZbufferMode

Direct3DRMFrame3

Z버퍼링을 enable 또는 디세블로 하는지를 설정한다.

구문

object. SetZbufferMode(val As CONST_D3DRMZBUFFERMODE)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
val
Z버퍼 모드를 지정하는CONST_D3DRMZBUFFERMODE 열거형의 멤버의 하나. 디폴트값은D3DRMZBUFFER_FROMPARENT이다.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.GetZbufferMode

Direct3DRMFrame3.Transform

Direct3DRMFrame3

지정의 벡터를 변환해, 결과를 돌려준다.

구문

object. Transform(d As D3DVECTOR,
  s As D3DVECTOR)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
d
변환 조작의 결과가 세트 되는D3DVECTOR 형.
s
변환 조작의 소스인D3DVECTOR형.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

Direct3DRMFrame3.InverseTransform

Direct3DRMFrame3.TransformVectors

Direct3DRMFrame3

벡터의 배열을, 모델로부터 월드 공간으로 변환한다.

구문

object. TransformVectors(reference As DIRECT3DRMFrame3,
  num As Long,
  DstVectors() As D3DVECTOR,
  SrcVectors() As D3DVECTOR)

요소

object
Direct3DRMFrame3오브젝트를 나타내는오브젝트식.
reference
이 호출을 위해서(때문에) 장면의 루트로서 사용되는 프레임. 이 인수가 NOTHING의 경우, 현재의루트 프레임(GetScene가 돌려주는 프레임)이 사용된다.
num
변환할 필요가 있는 벡터수.
DstVectors()
변환의 출력처.
SrcVectors()
변환하는 벡터의 배열.

에러값

에러의 리스트에 대해서는, 「Direct3D 보관 유지 모드의 에러값」을 참조할것.

참조

D3DVECTOR