パッケージ com.lmt.lib.bms

クラス BmsChannel

  • すべての実装されたインタフェース:
    Comparable<BmsChannelKey>
    public final class BmsChannel
extends BmsChannelKey
    BMSコンテンツにおいて時間軸を必要とする要素を表す情報です。

    通常、楽曲を構成するには同じ時間軸上に複数の異なる情報が混在している必要があります。チャンネルはそれらの 情報1個分に番号を付け、データ形式などの属性を決定するために用いられます。

    チャンネルを構成する情報には「番号」「データ型」「チャンネルと関連付いたメタ情報」 「データが定義されなかった場合の初期値」「データの重複可否」「同一性チェック対象かどうか」が 存在します。それぞれの情報の詳細については以下の記述を参照してください。

    番号
    当該チャンネルの番号を示します。チャンネル番号には「仕様チャンネル」「ユーザーチャンネル」の2種類が存在します。
    仕様チャンネルはBmsSpec.SPEC_CHANNEL_MIN～BmsSpec.SPEC_CHANNEL_MAXの範囲で指定し、
    ユーザーチャンネルはBmsSpec.USER_CHANNEL_MIN～BmsSpec.USER_CHANNEL_MAXの範囲で指定します。
    仕様チャンネルはBMS仕様として定義するチャンネルを示し、このチャンネルのデータは外部データからの入出力の 対象として扱われます。一方、ユーザーチャンネルはアプリケーションがBMSコンテンツを制御する目的で使用出来る 一時的なデータとしての扱いになり、外部データからの入出力対象にはなりません。

    データ型(BmsType)
    チャンネルのデータを記述する際の型を決定します。
    詳細はBmsTypeを参照してください。

    チャンネルと関連付いたメタ情報
    チャンネルのデータは、しばしば索引付きメタ情報のインデックス値を示すことがあります。例えば、チャンネルのデータが 時間軸上で鳴らす音の種類を示し、関連付いたメタ情報がその音のファイル名を示す場合などです。このような表現を行う ためにはチャンネルのデータ型が「配列型」であり、且つ関連付けようとするメタ情報の構成要素が「索引付き」である 必要があります。

    初期値
    BMSの仕様として、全てのチャンネルは指定必須とすることが出来ません。そのため、チャンネルには必ず初期値を 定義しなければなりません。初期値の記述は文字列のみですが記述の書式はデータ型の指定内容に依存します。

    データの重複可否
    チャンネルに登録するデータの中には、同じ種類のデータを複数重複して登録したい場合があります。例えば、 任意のタイミングで発音したい音(BGM)等がそれに該当します。そのようなデータはチャンネルを複数作成して重ねるのではなく チャンネルをデータ重複可能にすることで実現できます。BMSライブラリでは、このような機能をサポートします。

    同一性チェック
    同一性チェックの詳細な説明に関してはBmsMetaの説明を参照してください。
    同一性についてはチャンネルに対しても適用することができ、データの内容が同一であるかどうかをチェックする必要が あるかどうかについての情報を付与することが出来るようになっています。

    任意型チャンネル
    データ型をBmsType.OBJECTに指定したチャンネルは「任意型チャンネル」という扱いになります。 任意型チャンネルは、その他のチャンネルとは下記の点が異なります。

    • 仕様チャンネルの番号は指定出来ません。
    • 初期値はnullでなければいけません。
    • 同一性チェックをONにすることは出来ません。

    • ネストされたクラスの概要

      ネストされたクラス 
      修飾子とタイプ クラス 説明
      static interface  BmsChannel.Tester
      チャンネルを検査するI/Fを提供します。

    • コンストラクタの概要

      コンストラクタ 
      コンストラクタ 説明
      BmsChannel​(int number, BmsType type, String ref, String defaultValue, boolean multiple, boolean uniqueness)
      新しいチャンネルオブジェクトを生成します。
      BmsChannel​(String number, BmsType type, String ref, String defaultValue, boolean multiple, boolean uniqueness)
      新しいチャンネルオブジェクトを生成します。

    • メソッドの概要

      すべてのメソッド インスタンス・メソッド concreteメソッド 
      修飾子とタイプ メソッド 説明
      Object getDefaultValue()
      このチャンネルにデータが設定されていない場合の初期値を取得します。
      String getRef()
      チャンネルの参照先メタ情報の名称を取得します。
      BmsType getType()
      チャンネルのデータ型を取得します。
      boolean isArrayType()
      チャンネルのデータ型が配列型であるかどうかを取得します。
      boolean isBpm()
      BPM変更チャンネルであるかどうかを習得します。
      boolean isLength()
      小節長変更チャンネルであるかどうかを取得します。
      boolean isMultiple()
      チャンネルが1小節内に複数のデータを持つことができるかどうかを取得します。
      boolean isRelatedToTime()
      チャンネルがBMSの演奏時間に関連するデータを持つかどうかを取得します。
      boolean isSpec()
      仕様チャンネルかどうかを取得します。
      boolean isStop()
      譜面停止チャンネルであるかどうかを取得します。
      boolean isUniqueness()
      チャンネルのデータがBMS定義の同一性を判定するために使用されるべきかどうかを取得します。
      boolean isUser()
      ユーザーチャンネルかどうかを取得します。
      boolean isValueType()
      チャンネルのデータ型が値型であるかどうかを取得します。
      String toString()
      チャンネル番号とデータ型が分かる形式の文字列を返します。

    • コンストラクタの詳細

      • BmsChannel

        public BmsChannel​(int number,
                  BmsType type,
                  String ref,
                  String defaultValue,
                  boolean multiple,
                  boolean uniqueness)
        新しいチャンネルオブジェクトを生成します。
        パラメータ:
        number - チャンネル番号
        type - チャンネルデータ型
        ref - 参照先メタ情報
        defaultValue - チャンネルデータの初期値
        multiple - チャンネルデータの重複許可フラグ
        uniqueness - 同一性チェックを行う際に参照されるチャンネルかどうかを示すフラグ
        例外:
        NullPointerException - typeがnull
        NullPointerException - typeがOBJECT以外の時、defaultValueがnull
        IllegalArgumentException - typeがOBJECTの時、defaultValueがnullではない
        IllegalArgumentException - numberに登録できないチャンネル番号を指定した
        IllegalArgumentException - typeがOBJECTの時、仕様チャンネルを指定した
        IllegalArgumentException - typeがOBJECTの時、refがnullではない
        IllegalArgumentException - データ型が値型で参照先メタ情報を指定した
        IllegalArgumentException - typeがOBJECT以外の時、defaultValueがtypeのテストに失敗した
        IllegalArgumentException - ユーザーチャンネルでuniquenessをtrueにしようとした

      • BmsChannel

        public BmsChannel​(String number,
                  BmsType type,
                  String ref,
                  String defaultValue,
                  boolean multiple,
                  boolean uniqueness)
        新しいチャンネルオブジェクトを生成します。
        パラメータ:
        number - チャンネル番号(36進数で指定)
        type - チャンネルデータ型
        ref - 参照先メタ情報
        defaultValue - チャンネルデータの初期値
        multiple - チャンネルデータの重複許可フラグ
        uniqueness - 同一性チェックを行う際に参照されるチャンネルかどうかを示すフラグ
        例外:
        NullPointerException - numberがnull
        NumberFormatException - numberの内容が36進数ではない
        NullPointerException - typeがnull
        NullPointerException - typeがOBJECT以外の時、defaultValueがnull
        IllegalArgumentException - typeがOBJECTの時、defaultValueがnullではない
        IllegalArgumentException - numberに登録できないチャンネル番号を指定した
        IllegalArgumentException - typeがOBJECTの時、仕様チャンネルを指定した
        IllegalArgumentException - typeがOBJECTの時、refがnullではない
        IllegalArgumentException - データ型が値型で参照先メタ情報を指定した
        IllegalArgumentException - typeがOBJECT以外の時、defaultValueがtypeのテストに失敗した
        IllegalArgumentException - ユーザーチャンネルでuniquenessをtrueにしようとした

    • メソッドの詳細

      • toString

        public String toString()
        チャンネル番号とデータ型が分かる形式の文字列を返します。
        オーバーライド:
        toString クラス内 BmsChannelKey
        戻り値:
        チャンネル番号とデータ型が分かる形式の文字列

      • getType

        public final BmsType getType()
        チャンネルのデータ型を取得します。
        戻り値:
        チャンネルのデータ型

      • getRef

        public final String getRef()
        チャンネルの参照先メタ情報の名称を取得します。

        参照先メタ情報の単位(BmsUnit)はINDEXEDである必要があります。 また、参照先メタ情報を持つチャンネルのデータ型は配列型であることを想定しています。配列の要素の値が メタ情報へアクセスするためのインデックス値になります。

        参照先メタ情報を持たないチャンネルに対してこのメソッドを呼び出すとnullを返します。

        戻り値:
        参照先メタ情報の名称。参照先メタ情報を持たない場合はnull。

      • getDefaultValue

        public final Object getDefaultValue()
        このチャンネルにデータが設定されていない場合の初期値を取得します。

        このメソッドが返す初期値のデータ型はBmsTypeのネイティブデータ型によって決定されます。 ネイティブデータ型はBmsType.getNativeType()で参照できます。型を変換してデータにアクセスする場合は BmsTypeの仕様に従ってください。

        BMSの定義では、ある小節のあるチャンネルのデータが必ず定義されているという保証はありません。 従って、各チャンネルには明確に初期値が規定されるべきであることから、BMSライブラリの仕様としても このメソッドがnullを返さないことを保証します。

        戻り値:
        このチャンネルのデータの初期値

      • isMultiple

        public final boolean isMultiple()
        チャンネルが1小節内に複数のデータを持つことができるかどうかを取得します。

        この値がtrueになるチャンネルでは、1小節内に2つ以上のデータを持つことができます。

        戻り値:
        複数データを持つことができる場合はtrue

      • isUniqueness

        public final boolean isUniqueness()
        チャンネルのデータがBMS定義の同一性を判定するために使用されるべきかどうかを取得します。
        戻り値:
        同一性判定に使用されるべきである場合はtrue

      • isArrayType

        public final boolean isArrayType()
        チャンネルのデータ型が配列型であるかどうかを取得します。
        戻り値:
        データ型が配列型の場合はtrue
        関連項目:
        BmsType.isArrayType()

      • isValueType

        public final boolean isValueType()
        チャンネルのデータ型が値型であるかどうかを取得します。
        戻り値:
        データ型が値型の場合はtrue
        関連項目:
        BmsType.isValueType()

      • isRelatedToTime

        public final boolean isRelatedToTime()
        チャンネルがBMSの演奏時間に関連するデータを持つかどうかを取得します。

        「演奏時間に関連するデータ」とは、「小節長変更」「BPM変更」「譜面停止」のいずれかであることを示します。 これらのデータが変更されると、影響の大小に関わらず演奏時間に変化が生じます。演奏時間に変化が生じることは BMSの同一性を損なうことと同義であり、先に示したチャンネルはisUniquenessが trueを返すことを表します。

        このメソッドがtrueを返すチャンネルはBMSライブラリ側で仕様として規定されています。それらのチャンネルの 定義方法についてはBmsSpecBuilderを参照してください。

        戻り値:
        演奏時間に関連するチャンネルである場合はtrue

      • isLength

        public final boolean isLength()
        小節長変更チャンネルであるかどうかを取得します。
        戻り値:
        小節長変更チャンネルである場合はtrue

      • isBpm

        public final boolean isBpm()
        BPM変更チャンネルであるかどうかを習得します。
        戻り値:
        BPM変更チャンネルである場合はtrue

      • isStop

        public final boolean isStop()
        譜面停止チャンネルであるかどうかを取得します。
        戻り値:
        譜面停止チャンネルである場合はtrue

      • isSpec

        public final boolean isSpec()
        仕様チャンネルかどうかを取得します。
        戻り値:
        仕様チャンネルである場合はtrue

      • isUser

        public final boolean isUser()
        ユーザーチャンネルかどうかを取得します。
        戻り値:
        ユーザーチャンネルである場合はtrue