------------------------------------------------------------------------------
HSPOGG ver3.7 REFERENCE MANUAL                      HSP : Hot Soup Processor  
ＨＳＰ拡張拡張DLLリファレンス         copyright 2007-2023 (c) onion software  
------------------------------------------------------------------------------

・はじめに

	このDLLは、Hot Soup Processor ver3以降とともに使用することで、
	Direct Soundを使用した波形の再生、及びOggVorbis形式による音楽データの
	再生を行なうことができるプラグインです。

	HSPOGGの機能は、HGIMG3で使用することができるサウンド機能命令(dmm〜)
	と同等です。3D機能などは使用しないが、サウンド機能のみ利用したい時、
	他の描画系プラグインと組み合わせたい時などに使用することができます。


・HSPOGGの機能概要

	HSPOGGを使用することにより、単純な音の再生から、高音質な音楽の再生
	まで幅広く行なうことができます。
	HSPOGGで扱うことのできるフォーマットは、以下の通りです。

	・WAV形式       効果音など短い音の再生に利用します。
	                モノラル(1ch)またはステレオ(2ch)、
			8/16bit PCM形式に対応しています。
	                複数の波形を同時に再生可能。
	                任意の波形が再生中かどうかを取得することが可能。

	・OGG形式       OggVorbis形式の波形圧縮フォーマットに対応しています。
	                モノラル(1ch)またはステレオ(2ch)、
	                任意のビットレートに対応。
			任意のループポイントを指定して繰り返し演奏が可能。
	                再生中のストリームポジションを取得することが可能。


・インストール

	拡張プラグインのファイル、HSPOGG.DLLは、HSED3.EXEおよび、HSP3.EXEのある
	ディレクトリと同じ場所に置いてください。
	(実行に使われているHSP3.EXEと同じディレクトリに、HSPOGG.DLLがない場合は
	エラーになります)
	また、HSPOGG.ASをスクリプトと同じディレクトリか、またはcommonフォルダ内に
	コピーされている必要があります。
	HSPOGGを使用する場合は、スクリプトの先頭に必ず「#include "hspogg.as"」
	という行を追加してください。以上で、HSPの機能が拡張され、この
	リファレンスで説明をしている命令を使用することができるようになります。
	(HGIMG3プラグインと同時に使用する場合は、"hspogg.as"を指定する必要は
	ありません。"hgimg3.as"に同等の機能が既に入っています。)


・更新履歴

	2023/07/18 ( Ver3.7β6 )

		oggファイル再生時のメモリ使用量を抑制するように修正


	2022/04/13 ( Ver3.7β5 )

		メモリリークを修正

	2022/10/22 ( Ver3.7β4 )

		oggファイルの再生をストリームからオンメモリ再生に切り替え
		(拡張子が.sのファイルは従来通りストリーミング再生を行います)

	2010/03/17 ( Ver3.21RC4 )

		一部のOSでoggストリームの再生直後にdmmstatで再生時間を取るとフリーズする不具合を修正
		dmmloadのファイル名に全角文字があった際に無効となる不具合を修正

	2010/02/16 ( Ver3.21RC2 )

		HSPOGGでサウンド機能使用時にスレッドが解放されないことがある不具合を修正

	2007/6/1 ver3.1

		最初のバージョン。


・注意点

	HSPOGG.DLLは、HSP3.EXEと同時に使用されるプラグインファイルです。
	使用するHSPは、ver3.1以上をお使い下さい。ver2.61やそれ以前のHSPには
	対応していませんのでご注意下さい。
	EXEファイルを作成した場合でも、HSPOGG.DLLをEXEファイルと同じディレクトリ
	に置かないと動作しません。また、packfileにDLLを追加することはできません。
	また、exeファイルにデータを埋め込む場合、wav形式のファイル及び
	ogg形式(拡張子が「.ogg」のファイル)は指定可能ですが、
	拡張子が「.s」のファイル(ストリームデータ)は指定できません。


・HSP3Dish,HGIMG4との併用について

	HSP3.7β5版から、Windows版のHSP3Dish、HGIMG4のプラグイン互換性向上により
	hspoggが使用可能になりました。
	ただし、この機能はまだβ版のため、もともとサポートされているmmload,mmplay等の命令と
	重複して使用するとノイズが混じることがあります。
	hspoggとHSP3Dish,HGIMG4を同時に使用する場合は、hspoggプラグイン側のdmmload、dmmplayだけを
	使用するようにしてください。


・OggVorbisストリーム再生について

	OggVorbis形式は、ライセンスフリーの圧縮音声ファイルフォーマットです。
	mp3形式などに比べて、ライセンスの問題がなく、OS環境に左右されずに
	使用できる点で、ゲーム等の組み込み形式に向いています。

	HSPOGGのver3.7β4以降では、拡張子「.ogg」を持つファイルを
	オンメモリで読み込み再生する形に変更されました。
	これにより、「.ogg」ファイルのサイズがメモリに確保されますが、
	#packや#epack命令によるファイルの埋め込みに対応しています。
	(外部からファイルを隠蔽することができます)
	メモリの確保が困難なファイルの場合は、拡張子「.s」を持つファイルを
	ストリームにより再生することが可能です。
	拡張子「.ogg」を「.s」に変更して、dmmload命令で登録すれば、
	そのファイルはストリーミングにより再生されることになります。

	OggVorbis形式ファイルの作成やエンコードの詳細については、サポートを
	行なっていませんので、別途資料やツールをご用意下さい。


・著作権とライセンス

	ユーザーがHSPOGGを使って作成したオリジナルのソフトウェア(実行ファイル)の権利は、
	それを作成したユーザーに属します。
	ただし、HSPOGGランタイムには、OggVorvis形式のファイルデコードにXiph.org Foundation
	のライブラリを使用しており、配布規定に従って以下の表記をする必要があります。

	--------------------------------------------------------------------------------
	OggVorvis形式のファイルデコードに以下のライブラリを使用しています
	libvorbis : Copyright (c) 2002-2004 Xiph.org Foundation
	--------------------------------------------------------------------------------

	(ライセンス表記は、配布物の中に上記の内容を含むテキストを含めるようにしてください。)

	以上の項目を満たしていれば、ユーザーがHSPOGG.DLLを使って作成したオリジナルの
	ソフトウェア(実行ファイル)を、自由に通信、即売会、店頭などで展示、配布、販売
	することができます。ライセンス料は必要ありません。

	HSPOGGの著作権はonion softwareにあります。
	onion softwareは本プログラムによって生じた、いかなる損害についても保証いたしません。
	自己の責任の範囲で使用してください。
	また、付属のサンプルスクリプトも自由に改変、公開していただいて構いません。

	HSPOGG.DLLは、基本的にBSDライセンスのもと有償・無償を問わず
	添付、複製、改編、再配布することができます。
	ただし、その際には必ずライセンス表記も含めるようにしてください。


・命令一覧

	dmmini		サウンド機能初期化
	dmmbye		サウンド機能終了処理
	dmmreset	サウンド機能の設定をリセット
	dmmdel		サウンドデータを削除
	dmmvol		サウンドデータの音量設定
	dmmpan		サウンドデータのパン設定
	dmmloop		サウンドデータのループ設定
	dmmload		サウンドデータの読み込み
	dmmplay		サウンドデータの再生
	dmmstop		サウンドデータの再生停止
	dmmstat		サウンドデータの状態取得

	命令の詳細は、ヘルプを参照してください。
	サウンド関連機能は、3D機能と同様にDirectX8以降のDirectSoundを
	使用しています。HSP3の内蔵マルチメディア機能と比較して、
	音量の設定や、複数音声の同時再生、状態の取得などを利用することが
	できるようになります。


-------------------------------------------------------------------------------
                                                HSP users manual / end of file 
-------------------------------------------------------------------------------
