DirectSound

最終更新日:2002年2月11日

はじめに

このドキュメントについて
DirectSoundについて
DirectSoundの使用方法


DirectSoundを使うための関数(DSound API)

変数型
構造体
フラグ(定数)
関数が返すコード(定数)
アルゴリズム
	
	
戻る

はじめに
このドキュメントについて
　このドキュメントはDirectSoundについての情報を記述したものです.このドキュメント
のなかにはC/C++コンパイラに標準で付属しているインクルードファイルの中のdsound.h(
Copyright 1995-1998 Microsoft Corp.)から情報を取り出したもの,コメントを和訳したも
のが一部含まれています.
　空白部分は未稿記事です.気になる場合は自分で調べるか更新をお待ちください.


DirectSoundの利用方法

	・dsound.hをインクルードし,dsound.libをリンクする

なお、当然ですがDirectSoundに非対応の環境では利用できません.


DirectSoundについて
	
	DirectSoundはその名前の通り直接(Direct)サウンドドライバをコントロールするための
	APIです.C言語で用いるためにはdsound.hをインクルードし,dsound.libをリンクする必要
	があります.この二つはコンパイラに付属しています.
	
	

戻る



DirectSoundリファレンス
DirectSound命令系の構造体
それぞれはtypedef struct _???{〜}??? *LP???;typedef const ??? *0LP???;というように定義
されているので
	??? 宣言する変数;
という形で用い,さらにconstを付加して定数としても使われています

DSCAPS
{
    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;
}

DSBCAPS
{
    DWORD           dwSize;
    DWORD           dwFlags;
    DWORD           dwBufferBytes;
    DWORD           dwUnlockTransferRate;
    DWORD           dwPlayCpuOverhead;
}

DSBUFFERDESC
{
    DWORD           dwSize;
    DWORD           dwFlags;
    DWORD           dwBufferBytes;
    DWORD           dwReserved;
    LPWAVEFORMATEX  lpwfxFormat;
    GUID            guid3DAlgorithm;	//DirectSound7以上のみ(DIRECTSOUND_VERSION>=0x0700)
}

DSBUFFERDESC1
{
    DWORD           dwSize;
    DWORD           dwFlags;
    DWORD           dwBufferBytes;
    DWORD           dwReserved;
    LPWAVEFORMATEX  lpwfxFormat;
}

DS3DBUFFER
{
    DWORD           dwSize;
    D3DVECTOR       vPosition;
    D3DVECTOR       vVelocity;
    DWORD           dwInsideConeAngle;
    DWORD           dwOutsideConeAngle;
    D3DVECTOR       vConeOrientation;
    LONG            lConeOutsideVolume;
    D3DVALUE        flMinDistance;
    D3DVALUE        flMaxDistance;
    DWORD           dwMode;
}

DS3DLISTENER
{
    DWORD           dwSize;
    D3DVECTOR       vPosition;
    D3DVECTOR       vVelocity;
    D3DVECTOR       vOrientFront;
    D3DVECTOR       vOrientTop;
    D3DVALUE        flDistanceFactor;
    D3DVALUE        flRolloffFactor;
    D3DVALUE        flDopplerFactor;
}

DSCCAPS
{
    DWORD           dwSize;
    DWORD           dwFlags;
    DWORD           dwFormats;
    DWORD           dwChannels;
}

DSCBUFFERDESC
{
    DWORD           dwSize;
    DWORD           dwFlags;
    DWORD           dwBufferBytes;
    DWORD           dwReserved;
    LPWAVEFORMATEX  lpwfxFormat;
}

DSCBCAPS
{
    DWORD           dwSize;
    DWORD           dwFlags;
    DWORD           dwBufferBytes;
    DWORD           dwReserved;
}

DSBPOSITIONNOTIFY
{
    DWORD           dwOffset;
    HANDLE          hEventNotify;
}


戻る



DSound API関数

はじめのexternを除き,
	#if !defined(__cplusplus) || defined(CINTERFACE)
	#define xxx_???(p,〜) (p)->lpVtbl->???(p,〜)
	#else xxx_???(p,〜) (p)->???()
	#endif
と命令が定義されている。
また、全ての命令においてIUnknown_???が含まれている
たとえば IDirectSoundにおいては
    // IUnknown methods
    STDMETHOD(QueryInterface)       (THIS_ REFIID, LPVOID *) PURE;
    STDMETHOD_(ULONG,AddRef)        (THIS) PURE;
    STDMETHOD_(ULONG,Release)       (THIS) PURE;
    // IDirectSound methods
    ..
    ..
と宣言されているが、実体は
	#define IDirectSound_QueryInterface(p,a,b)       IUnknown_QueryInterface(p,a,b)
	#define IDirectSound_AddRef(p)                   IUnknown_AddRef(p)
	#define IDirectSound_Release(p)                  IUnknown_Release(p)
となっている。

　また、全ての関数はHRESULT型の定数を返す。
それぞれの定数の意味は「関数が返すコード」の項に記載しています。

これらは全ての関数において同じなので省略してある。


コアとなっているAPI(extern HRESULT WINAPI DirectSound〜();)
DirectSoundCreate(LPCGUID, LPDIRECTSOUND *, LPUNKNOWN);
DirectSoundオブジェクトを作成する.
HRESULT DirectSoundCreate
(LPGUID lpGuid              //サウンドドライバを列挙した時得られるGUID。NULL=デフォルトデバイスを使用.
,LPDIRECTSOUND * lpDS       //DirectSoundオブジェクトへのポインタ(グローバルで定義したもの)
,IUnknown FAR * pUnkOuter   //未定義で,常にNULL.
);


DirectSoundCaptureCreate(LPCGUID, LPDIRECTSOUNDCAPTURE *, LPUNKNOWN);
　


基本オブジェクト(IUnknown)

IUnknown_QueryInterface(p,a,b);
　

IUnknown_AddRef(p);
　

IUnknown_Release(p);
　


IDirectSound…DirectSoundオブジェクト(LPDIRECTSOUND)のメンバー関数

IDirectSound_CreateSoundBuffer(LPDIRECTSOUND,LPCDSBUFFERDESC, LPDIRECTSOUNDBUFFER *, LPUNKNOWN);
　

IDirectSound_GetCaps(LPDIRECTSOUND,LPDSCAPS);
　

IDirectSound_DuplicateSoundBuffer(LPDIRECTSOUND,LPDIRECTSOUNDBUFFER, LPDIRECTSOUNDBUFFER *);
　

IDirectSound_SetCooperativeLevel(LPDIRECTSOUND,HWND, DWORD);
プログラムのサウンドカードに対する協調レベルをセットする.
IDirectSound_SetCooperateiveLevel
(LPDIRECTSOUND        //作成したDirectSoundオブジェクト
,HWND                 //ウィンドウハンドル
,DWORD                //レベルを設定するフラグ.(DSSCL_????)
);


IDirectSound_Compact(LPDIRECTSOUND);
　

IDirectSound_GetSpeakerConfig(LPDIRECTSOUND,LPDWORD);
　

IDirectSound_SetSpeakerConfig(LPDIRECTSOUND,DWORD);
　

IDirectSound_Initialize(LPDIRECTSOUND,LPCGUID);
　


IDirectSoundBuffer

IDirectSoundBuffer_GetCaps(LPDSBCAPS);
　

IDirectSoundBuffer_GetCurrentPosition(LPDWORD, LPDWORD);
　

IDirectSoundBuffer_GetFormat(LPWAVEFORMATEX, DWORD, LPDWORD);
　

IDirectSoundBuffer_GetVolume(LPLONG);
　

IDirectSoundBuffer_GetPan(LPLONG);
　

IDirectSoundBuffer_GetFrequency(LPDWORD);
　

IDirectSoundBuffer_GetStatus(LPDWORD);
　

IDirectSoundBuffer_Initialize(LPDIRECTSOUND, LPCDSBUFFERDESC);
　

IDirectSoundBuffer_Lock(DWORD, DWORD, LPVOID *, LPDWORD, LPVOID *, LPDWORD, DWORD);
　

IDirectSoundBuffer_Play(DWORD, DWORD, DWORD);
　

IDirectSoundBuffer_SetCurrentPosition(DWORD);
　

IDirectSoundBuffer_SetFormat(LPCWAVEFORMATEX);
　

IDirectSoundBuffer_SetVolume(LONG);
　

IDirectSoundBuffer_SetPan(LONG);
　

IDirectSoundBuffer_SetFrequency(DWORD);
　

IDirectSoundBuffer_Stop();
　

IDirectSoundBuffer_Unlock(LPVOID, DWORD, LPVOID, DWORD);
　

IDirectSoundBuffer_Restore();
　


IDirectSound3DListener

IDirectSound3DListener_GetAllParameters(LPDS3DLISTENER);
　

IDirectSound3DListener_GetDistanceFactor(LPD3DVALUE);
　

IDirectSound3DListener_GetDopplerFactor(LPD3DVALUE);
　

IDirectSound3DListener_GetOrientation(LPD3DVECTOR, LPD3DVECTOR);
　

IDirectSound3DListener_GetPosition(LPD3DVECTOR);
　

IDirectSound3DListener_GetRolloffFactor(LPD3DVALUE);
　

IDirectSound3DListener_GetVelocity(LPD3DVECTOR);
　

IDirectSound3DListener_SetAllParameters(LPCDS3DLISTENER, DWORD);
　

IDirectSound3DListener_SetDistanceFactor(D3DVALUE, DWORD);
　

IDirectSound3DListener_SetDopplerFactor(D3DVALUE, DWORD);
　

IDirectSound3DListener_SetOrientation(D3DVALUE, D3DVALUE, D3DVALUE, D3DVALUE, D3DVALUE, D3DVALUE, DWORD);
　

IDirectSound3DListener_SetPosition(D3DVALUE, D3DVALUE, D3DVALUE, DWORD);
　

IDirectSound3DListener_SetRolloffFactor(D3DVALUE, DWORD);
　

IDirectSound3DListener_SetVelocity(D3DVALUE, D3DVALUE, D3DVALUE, DWORD);
　

IDirectSound3DListener_CommitDeferredSettings();
　


IDirectSound3DBuffer

IDirectSound3DBuffer_GetAllParameters(LPDS3DBUFFER);
　

IDirectSound3DBuffer_GetConeAngles(LPDWORD, LPDWORD);
　

IDirectSound3DBuffer_GetConeOrientation(LPD3DVECTOR);
　

IDirectSound3DBuffer_GetConeOutsideVolume(LPLONG);
　

IDirectSound3DBuffer_GetMaxDistance(LPD3DVALUE);
　

IDirectSound3DBuffer_GetMinDistance(LPD3DVALUE);
　

IDirectSound3DBuffer_GetMode(LPDWORD);
　

IDirectSound3DBuffer_GetPosition(LPD3DVECTOR);
　

IDirectSound3DBuffer_GetVelocity(LPD3DVECTOR);
　

IDirectSound3DBuffer_SetAllParameters(LPCDS3DBUFFER, DWORD);
　

IDirectSound3DBuffer_SetConeAngles(DWORD, DWORD, DWORD);
　

IDirectSound3DBuffer_SetConeOrientation(D3DVALUE, D3DVALUE, D3DVALUE, DWORD);
　

IDirectSound3DBuffer_SetConeOutsideVolume(LONG, DWORD);
　

IDirectSound3DBuffer_SetMaxDistance(D3DVALUE, DWORD);
　

IDirectSound3DBuffer_SetMinDistance(D3DVALUE, DWORD);
　

IDirectSound3DBuffer_SetMode(DWORD, DWORD);
　

IDirectSound3DBuffer_SetPosition(D3DVALUE, D3DVALUE, D3DVALUE, DWORD);
　

IDirectSound3DBuffer_SetVelocity(D3DVALUE, D3DVALUE, D3DVALUE, DWORD);
　


IDirectSoundCapture

IDirectSoundCapture_CreateCaptureBuffer(LPCDSCBUFFERDESC, LPDIRECTSOUNDCAPTUREBUFFER *, LPUNKNOWN);
　

IDirectSoundCapture_GetCaps(LPDSCCAPS );
　

IDirectSoundCapture_Initialize(LPCGUID);
　


IDirectSoundCaptureBuffer

IDirectSoundCaptureBuffer_GetCaps(LPDSCBCAPS );
　

IDirectSoundCaptureBuffer_GetCurrentPosition(LPDWORD, LPDWORD );
　

IDirectSoundCaptureBuffer_GetFormat(LPWAVEFORMATEX, DWORD, LPDWORD );
　

IDirectSoundCaptureBuffer_GetStatus(LPDWORD );
　

IDirectSoundCaptureBuffer_Initialize(LPDIRECTSOUNDCAPTURE, LPCDSCBUFFERDESC);
　

IDirectSoundCaptureBuffer_Lock(DWORD, DWORD, LPVOID *, LPDWORD, LPVOID *, LPDWORD, DWORD);
　

IDirectSoundCaptureBuffer_Start(DWORD);
　

IDirectSoundCaptureBuffer_Stop();
　

IDirectSoundCaptureBuffer_Unlock(LPVOID, DWORD, LPVOID, DWORD);
　


IDirectSoundNotify

IDirectSoundNotify_SetNotificationPositions(DWORD, LPCDSBPOSITIONNOTIFY);
　


IKsPropertySet

IKsPropertySet_Get(REFGUID, ULONG, LPVOID, ULONG, LPVOID, ULONG, PULONG);
　

IKsPropertySet_Set(REFGUID, ULONG, LPVOID, ULONG, LPVOID, ULONG);
　

IKsPropertySet_QuerySupport(REFGUID, ULONG, PULONG);
　



戻る




関数が返すコード(定数)


返すコード
意味
DS_OK
成功
DS_NO_VIRTUALIZATION
成功したが3Dアルゴリズムに問題があった(we had to substitute the 3D algorithm)
DSERR_ALLOCATED
優先度(プライオリティレベル)のようなリソースが既に他に呼び出されているために呼び出しに失敗
DSERR_CONTROLUNAVAIL
要求されたコントロール(ボリュームやパンなど)が利用できない
DSERR_INVALIDPARAM
不正なパラメータが関数の引数にされた
(An invalid parameter was passed to the returning function)
DSERR_INVALIDCALL
呼び出しが無効なオブジェクトを指定した
(This call is not valid for the current state of this object)
DSERR_GENERIC
DirectSoundコンポーネントで不明な内部エラーが起こった
DSERR_PRIOLEVELNEEDED
関数を正常に実行するのに十分な優先度がないのに呼び出した
DSERR_OUTOFMEMORY
作業用メモリの不足
DSERR_BADFORMAT
サポートされていないWAVEフォーマットを指定した
DSERR_UNSUPPORTED
現在未対応の関数
DSERR_NODRIVER
利用可能なサウンドドライブがない
DSERR_ALREADYINITIALIZED
既に初期化されているオブジェクト
DSERR_NOAGGREGATION
集合体(aggregation)をサポートしていないオブジェクト
DSERR_BUFFERLOST
破損したバッファメモリであり、修復の必要がある
DSERR_OTHERAPPHASPRIO
他の優先度が高いアプリケーションが実行を邪魔している
DSERR_UNINITIALIZED
初期化されていないオブジェクト
DSERR_NOINTERFACE
要求されたCOMインターフェースが利用不可
DSERR_ACCESSDENIED
アクセスが拒否された


戻る




フラグ(定数)


defineで定義された定数値
値または説明
DSCAPS_PRIMARYMONO
　
DSCAPS_PRIMARYSTEREO
　
DSCAPS_PRIMARY8BIT
　
DSCAPS_PRIMARY16BIT
　
DSCAPS_CONTINUOUSRATE
　
DSCAPS_EMULDRIVER
　
DSCAPS_CERTIFIED
　
DSCAPS_SECONDARYMONO
　
DSCAPS_SECONDARYSTEREO
　
DSCAPS_SECONDARY8BIT
　
DSCAPS_SECONDARY16BIT
　
協調レベル(優先度)   ※SetCooperativeLevel()参照
DSSCL_NORMAL
標準.手軽に演奏可能だが8bits,22KHz,ステレオサウンドのみ.サウンドメモリのプライマリバッファにサウンドフォーマット設定・書き込みができない.オンボードメモリのコンパクト化不可.
DSSCL_PRIORITY
優先.プライマリバッファの操作とオンボードメモリのコンパクト化が可能
DSSCL_EXCLUSIVE
独占.全ての機能を利用可能.プログラム実行中においてプライマリバッファの全領域を利用できる.
DSSCL_WRITEPRIMARY
書き込み優先.プライマリバッファに直接アクセスしてデータを書き込める.セカンダリバッファは利用不可.
スピーカー設定
DSSPEAKER_HEADPHONE
ヘッドホン
DSSPEAKER_MONO
モノラル
DSSPEAKER_QUAD
　
DSSPEAKER_STEREO
ステレオ
DSSPEAKER_SURROUND
サラウンド
DSSPEAKER_5POINT1
5.1ch
スピーカー設定(2)
DSSPEAKER_GEOMETRY_MIN
 最低値…5度
DSSPEAKER_GEOMETRY_NARROW
ナロー(狭角)…10度
DSSPEAKER_GEOMETRY_WIDE
ワイド(広角)…20度
DSSPEAKER_GEOMETRY_MAX
 最大値…180度
スピーカー関係のマクロ
DSSPEAKER_COMBINED(c, g)
(DWORD)(((BYTE)(c)) | ((DWORD)((BYTE)(g))) << 16)
DSSPEAKER_CONFIG(a)
(BYTE)(a)
DSSPEAKER_GEOMETRY(a)
(BYTE)(((DWORD)(a) >> 16) & 0x00FF)
(複数選択可)
DSBCAPS_PRIMARYBUFFER
　
DSBCAPS_STATIC
　
DSBCAPS_LOCHARDWARE
　
DSBCAPS_LOCSOFTWARE
　
DSBCAPS_CTRL3D
　
DSBCAPS_CTRLFREQUENCY
　
DSBCAPS_CTRLPAN
　
DSBCAPS_CTRLVOLUME
　
DSBCAPS_CTRLPOSITIONNOTIFY
　
DSBCAPS_STICKYFOCUS
　
DSBCAPS_GLOBALFOCUS
　
DSBCAPS_GETCURRENTPOSITION2
　
DSBCAPS_MUTE3DATMAXDISTANCE
　
DSBCAPS_LOCDEFER
　
(複数選択可)
DSBPLAY_LOOPING
　
DSBPLAY_LOCHARDWARE
　
DSBPLAY_LOCSOFTWARE
　
DSBPLAY_TERMINATEBY_TIME
　
DSBPLAY_TERMINATEBY_DISTANCE
　
DSBPLAY_TERMINATEBY_PRIORITY
　
(複数選択可)
DSBSTATUS_PLAYING
　
DSBSTATUS_BUFFERLOST
　
DSBSTATUS_LOOPING
　
DSBSTATUS_LOCHARDWARE
　
DSBSTATUS_LOCSOFTWARE
　
DSBSTATUS_TERMINATED
　
　
DSBLOCK_FROMWRITECURSOR
　
DSBLOCK_ENTIREBUFFER
　
周波数
DSBFREQUENCY_MIN
最低…100
DSBFREQUENCY_MAX
最大…100000
DSBFREQUENCY_ORIGINAL
オリジナル(0)
音響位置
DSBPAN_LEFT	
左端(-10000)
DSBPAN_CENTER
中央(0)
DSBPAN_RIGHT
右端(10000)
ボリューム
DSBVOLUME_MIN
最低(-10000)
DSBVOLUME_MAX
最大(0)
　
DSBSIZE_MIN	
4
DSBSIZE_MAX	
0x0FFFFFFF
(どれか選択)
DS3DMODE_NORMAL
　
DS3DMODE_HEADRELATIVE
　
DS3DMODE_DISABLE
　
(どれか選択)
DS3D_IMMEDIATE
すぐ反映
DS3D_DEFERRED
遅らせる
距離
DS3D_MINDISTANCEFACTOR
最低(FLT_MIN)
DS3D_MAXDISTANCEFACTOR
最大(FLT_MAX)
DS3D_DEFAULTDISTANCEFACTOR
デフォルト…1.0f
ロールオフ
DS3D_MINROLLOFFFACTOR
最低…0.0f
DS3D_MAXROLLOFFFACTOR
最大…10.0f
DS3D_DEFAULTROLLOFFFACTOR
デフォルト…1.0f
ドップラー
DS3D_MINDOPPLERFACTOR
最低…0.0f
DS3D_MAXDOPPLERFACTOR
最大…10.0f
DS3D_DEFAULTDOPPLERFACTOR
デフォルト…1.0f
距離のデフォルト範囲
DS3D_DEFAULTMINDISTANCE
最低…1.0f
DS3D_DEFAULTMAXDISTANCE
最大…1000000000.0f
角度
DS3D_MINCONEANGLE
最小…0度
DS3D_MAXCONEANGLE
最大…360度
DS3D_DEFAULTCONEANGLE
デフォルト…360度
　
DS3D_DEFAULTCONEOUTSIDEVOLUME
 (DSBVOLUME_MAX)
　
DSCCAPS_EMULDRIVER	
DSCAPS_EMULDRIVER
DSCCAPS_CERTIFIED	
DSCAPS_CERTIFIED
DSCBCAPS_WAVEMAPPED	
0x80000000
　
DSCBLOCK_ENTIREBUFFER
0x00000001
　
DSCBSTATUS_CAPTURING
0x00000001
DSCBSTATUS_LOOPING	
0x00000002
　
DSCBSTART_LOOPING
0x00000001
　
DSBPN_OFFSETSTOP
0xFFFFFFFF


戻る



DirectSound3Dのアルゴリズム
アルゴリズムを利用するときはアルゴリズム名を用いる

DirectSound3Dの標準アルゴリズム
アルゴリズム名
DS3DALG_DEFAULT
式
{00000000-0000-0000-0000-000000000000}
定義式
GUID_NULL

ヴァーチャライズ(より実物に近づける処理)をしない
アルゴリズム名
DS3DALG_NO_VIRTUALIZATION
式
{C24133F-1C1B-11d2-94F5-00C04FC28ACA}
定義式
0xc241333f, 0x1c1b, 0x11d2, 0x94, 0xf5, 0x0, 0xc0, 0x4f, 0xc2, 0x8a, 0xca

HRTFによる高品質アルゴリズム
アルゴリズム名
DS3DALG_HRTF_FULL
式

{C2413340-1C1B-11d2-94F5-00C04FC28ACA}
定義式
0xc2413340, 0x1c1b, 0x11d2, 0x94, 0xf5, 0x0, 0xc0, 0x4f, 0xc2, 0x8a, 0xca

HRTFによる低品質アルゴリズム
アルゴリズム名
DS3DALG_HRTF_LIGHT
式
{C2413342-1C1B-11d2-94F5-00C04FC28ACA}
定義式
0xc2413342, 0x1c1b, 0x11d2, 0x94, 0xf5, 0x0, 0xc0, 0x4f, 0xc2, 0x8a, 0xca


戻る



DirectSoundの宣言型
	
	IUnknown               未定義またはデフォルトの型
	LPGUID                 GUIDへのポインタ
	LPCGUID                GUIDへのポインタ
	LPDIRECTSOUND *        DirectSoundオブジェクトへのポインタ
	

戻る