= CD-ROM
* ((<CD-ROM機能概説>))
* ((<SDL::CD>))
* ((<CD-ROM関連メソッド>))
  * ((<SDL::CD.num_drives>)) -- システム上の CD-ROM の数を返します。
  * ((<SDL::CD.index_name>)) -- CD-ROM について、人間に読めるシステム非依存の ID を返します。
  * ((<SDL::CD.open>)) -- CD-ROM ドライブにアクセスするためにオープンします。
  * ((<SDL::CD#status>)) -- 指定されたドライブの現在の状態を返します。
  * ((<SDL::CD#play>)) -- CD を再生します。
  * ((<SDL::CD#play_tracks>)) -- 指定された CD トラックを再生します。
  * ((<SDL::CD#pause>)) -- CD-ROM の再生を一時停止します。
  * ((<SDL::CD#resume>)) -- CD-ROM の再生を再開します。
  * ((<SDL::CD#stop>)) -- CD-ROM の再生を停止します。
  * ((<SDL::CD#eject>)) -- CD-ROM を取り出します。
  * ((<SDL::CD#num_tracks>)) -- CD のトラック数を返します。
  * ((<SDL::CD#current_track>)) -- 現在のトラックを返します。
  * ((<SDL::CD#current_frame>)) -- トラック内の現在のフレームオフセット値を返します。
  * ((<SDL::CD#track_type>)) -- トラックの種類を返します。
  * ((<SDL::CD#track_length>)) -- トラックの長さを返します。
  * ((<SDL::CD#in_drive?>)) -- ドライブにディスクがあるかどうかを調べます。
  * ((<SDL::CD.frames_to_msf>)) -- フレーム数を分/秒/フレームに分解します。
  * ((<SDL::CD.msf_to_frames>)) -- 分/秒/フレームという値をフレーム数に変換します。
  * ((<SDL::CD#close>)) -- CDデバイスをクローズします。
  * ((<SDL::CD#closed?>)) -- CDデバイスがクローズされたかどうかを返します。

== CD-ROM機能概説
SDL は一度に 32 までのローカル CD-ROM ドライブの
オーディオ制御をサポートします。

トラック一覧の取得・再生・停止そして CD-ROM の取り出しを含む、
CD プレーヤの全ての基本的な機能を実行するためにこの API を使います。
(現在はマルチチェンジャーの CD ドライブはサポートしていません)

Ruby/SDL のどの CD-ROM 関連メソッドを呼ぶ前に、
まず ((<SDL.init>))(SDL::INIT_CDROM) を呼ばなければいけません。
これは CD-ROM ドライブを探してシステムをスキャンし、
プログラムがオーディオ制御できるようセットアップします。

ライブラリを初期化した後は、
((<SDL::CD.num_drives>)) を使って
利用可能なドライブがいくつあるかを知ることができます。
リストの最初のドライブはデフォルト CD-ROM ドライブです。
ドライブを選択し、((<SDL::CD.open>)) でオープンした後は、
ステータスをチェックし CD がドライブにあるなら再生を開始することができます。

CD-ROM は 1 つまたはそれ以上のトラックで構成され、
個々のトラックはある数の「フレーム」で構成されています。
フレームは CD の基礎データの単位で、
それぞれのフレームはサイズにして 2K であり、
CD は通常の再生スピードにおいて 1 秒間に 75(= SDL::CD::FPS)
フレーム再生されます。
SDL は CD 上のフレーム数を使って動作しますが、
((<SDL::CD.frames_to_msf>)) を使うことで、
より見慣れた分/秒のフォーマットに簡単に変換することができます。
またこの変換の逆は ((<SDL::CD.msf_to_frames>)) でできます。

== SDL::CD
((<SDL::CD.open>)) によってオープンされた CDROM デバイスを表し、
ディスクにおけるトラックのレイアウトの情報を格納します。

== CD-ROM関連メソッド

--- SDL::CD.num_drives
--- SDL::CD.numDrives

    システム上の CD-ROM の数を返します。

    * See Also
      
      ((<SDL::CD.open>))

--- SDL::CD.index_name(drive)
--- SDL::CD.indexName(drive)

    CD-ROM について、人間に読めるシステム非依存の ID を文字列で返します。
    ((|drive|)) はドライブのインデックス番号です。
    インデックス番号は 0 で始まり、((<SDL::CD.num_drives>))-1 で
    終わります。
    
    返り値は例えば以下のような文字列です。
    * "/dev/cdrom"
    * "E:"
    * "/dev/disk/ide/1/master"

    * See Also
      
      ((<SDL::CD.num_drives>))

--- SDL::CD.open(drive)

    CD-ROM ドライブにアクセスするためにオープンします。
    成功した場合は ((<SDL::CD>)) のインスタンスを返します。

    ドライブが正しくないか、ビジー状態のときは例外 ((<SDL::Error>)) を発生させます。


    EXAMPLE
      SDL.init SDL::INIT_CDROM
      
      # CD ドライブをチェック 
      if SDL::CD.num_drives == 0
        # 見つからなかった 
        STDERR.print "利用可能な CDROM デバイスがありません\n"
        exit 255
      end
      
      begin
        # デフォルトドライブをオープン
        cdrom = SDL::CD.open(0)
      rescue SDL::Error
        # オープンできなかった
        STDERR.puts "ドライブがオープンできませんでした"
        exit 255
      end
      
      # ボリュームの情報を表示 
      printf "名前: %s\n", SDL::CD.index_name(0)
      printf "トラック数: %d\n", cdrom.num_tracks
      num_tracks.times do |cur_track|
        min, sec, frame = SDL::CD.frames_to_msf(cdrom.track_length(cur_track))
        printf "\tトラック %d: 長さ %d:%d\n", cur_track, min, sec
      end

--- SDL::CD#status

    この関数は指定されたドライブの現在の状態を返します。
    状態は次のいずれかです。
    * SDL::CD::TRAYEMPTY
    * SDL::CD::STOPPED
    * SDL::CD::PLAYING
    * SDL::CD::PAUSED
    * SDL::CD::ERROR
    
    ドライブに CD が入っていると、
    ((<SDL.current_track>)), ((<SDL.current_frame>)), ((<SDL.num_tracks>)), ((<SDL.track_type>)),
    ((<SDL.track_lenght>))の情報が更新されます。


    EXAMPLE
      def play_track(track)
        raise "not cd in drive" unless $cdrom.in_drive?
      
        # 実際の CD のトラック数で切り捨て
        track = $cdrom.num_tracks-1 if track >= $cdrom.num_tracks
        $cdrom.play_tracks(track, 0, 1, 0)
      end

--- SDL::CD#play(start, length)

    ((|self|)) で示されるCDを
    フレーム ((|start|))から
    ((|length|)) フレームだけ
    再生します。

    失敗したときには例外((<SDL::Error>))を発生させます。

    * See Also
      
      ((<SDL::CD#play_tracks>))

--- SDL::CD#play_tracks(start_track, start_frame, ntracks, nframes)

    ((|start_track|)) 番目のトラックから
    ((|ntracks|)) トラック分、
    指定された CD を再生します。
    
    ((|start_frame|)) は
    再生を始める ((|start_track|)) の先頭から数えた
    フレームのオフセット値です。
    ((|nframes|)) は
    再生を終了する最後のトラック
    (((|start_track|))+((|ntracks|))) の
    先頭から数えたフレームのオフセット値です。
    
    このメソッドは、((<SDL::CD#status>))を
    呼んで CD のトラック情報を取得した後にのみ、呼ぶべきです。

    失敗したときには例外((<SDL::Error>))を発生させます。


    EXAMPLE
      # 前もって cdrom がオープンされたデバイスだと仮定 
      # CD 全体を再生 
      if cdrom.in_drive?
        cdrom.play_tracks 0, 0, 0, 0
      end
      # 最初のトラックを再生 
      if cdrom.in_drive?
        cdrom.play_tracks 0, 0, 1, 0
      end
      # 2 番目のトラックの最初から 15 秒を再生 
      if cdrom.in_drive?
        cdrom.play_tracks 1, 0, 0, SDL::CD::FPS*15
      end

    * NOTES

      データトラックは無視されます。

    * See Also
      
      ((<SDL::CD#play>)), ((<SDL::CD#status>))

--- SDL::CD#pause

    指定された CD-ROM の再生を一時停止します。

    失敗したときには例外((<SDL::Error>))を発生させます。

    * See Also
      
      ((<SDL::CD#play>)), ((<SDL::CD#resume>))

--- SDL::CD#resume

    指定した CD-ROM の再生を再開します。

    失敗したときには例外((<SDL::Error>))を発生させます。

    * See Also
      
      ((<SDL::CD#play>)), ((<SDL::CD#pause>))

--- SDL::CD#stop

    指定された CD-ROM の再生を停止します。

    失敗したときには例外((<SDL::Error>))を発生させます。

    * See Also
      
      ((<SDL::CD#play>))

--- SDL::CD#eject

    指定された CD-ROM を取り出します。

    失敗したときには例外((<SDL::Error>))を発生させます。

--- SDL::CD#num_tracks
--- SDL::CD#numTracks

    指定された CD-ROM のトラック数を返します。
    ((<SDL::CD#status>))で内容が更新されます。

    * See Also
      
      ((<SDL::CD#status>))

--- SDL::CD#current_track
--- SDL::CD#currentTrack

    指定された CD-ROM の現在のトラックを返します。
    ((<SDL::CD#status>))で内容が更新されます。

    * See Also
      
      ((<SDL::CD#status>))

--- SDL::CD#current_frame
--- SDL::CD#currentFrame

    指定された CD-ROM のトラック内の現在演奏しているフレームオフセット値を返します。
    ((<SDL::CD#status>))で内容が更新されます。

    * See Also
      
      ((<SDL::CD#status>))

--- SDL::CD#track_type(track)
--- SDL::CD#trackType(track)

    ((|track|)) で指定したトラックの種類を返します。
    SDL::CD::AUDIO_TRACK か SDL::CD::DATA_TRACK のいずれかを返します。

--- SDL::CD#track_length(track)
--- SDL::CD#trackLength(track)

    ((|track|)) で指定したトラックの長さをフレーム単位で返します。

--- SDL::CD#in_drive?

    ドライブにディスクがあるなら true を返します。

    * See Also
      
      ((<SDL::CD#status>))

--- SDL::CD.frames_to_msf(frames)
--- SDL::CD.framesToMSF(frames)

    フレーム数を分/秒/フレームに変換し、[分, 秒, フレーム] という整数3個の
    配列にして返します。

    * See Also
      
      ((<SDL::CD.msf_to_frames>))

--- SDL::CD.msf_to_frames(min, sec, frames)
--- SDL::CD.MSFToFrames(min, sec, frames)

    分/秒/フレームという値をフレーム数に変換します。

    * See Also
      
      ((<SDL::CD.frames_to_msf>))

--- SDL::CD#close

    ((|self|))をクローズします。

    * See Also
      
      ((<SDL::CD.open>)), ((<SDL::CD#closed?>))

--- SDL::CD#closed?

    ((<SDL::CD#close>))によってデバイスがクローズされたかどうかを
    返します。

    * See Also
      
      ((<SDL::CD#close>))

