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

クラス BmsStandardSaver

  • public class BmsStandardSaver
extends BmsSaver
    BMSコンテンツを標準フォーマットで出力するセーバーです。

    当クラスを通してBMSコンテンツを外部データ出力すると、一般的なBMS仕様に基づく形式となります。 具体的な出力内容についてはonWrite(BmsContent, OutputStream)を参照してください。

    • フィールドの詳細

      • PRECISION_DEFAULT

        public static final int PRECISION_DEFAULT
        配列データの最大分解能デフォルト値
        関連項目:
        定数フィールド値

      • PRECISION_MIN

        public static final int PRECISION_MIN
        配列データの最大分解能に指定可能な最小の値
        関連項目:
        定数フィールド値

      • PRECISION_MAX

        public static final int PRECISION_MAX
        配列データの最大分解能に指定可能な最大の値
        関連項目:
        定数フィールド値

      • MEASURE_COUNT_MAX

        public static final int MEASURE_COUNT_MAX
        標準フォーマットで対応する小節数の最大値
        関連項目:
        定数フィールド値

      • META_INDEX_MAX

        public static final int META_INDEX_MAX
        標準フォーマットで対応する索引付きメタ情報のインデックス値の最大値
        関連項目:
        定数フィールド値

    • コンストラクタの詳細

      • BmsStandardSaver

        public BmsStandardSaver()

    • メソッドの詳細

      • setMaxPrecision

        public final BmsStandardSaver setMaxPrecision​(int maxPrecision)
        小数部を持つ刻み位置が存在する場合の配列データ最大分解能を設定します。

        小数部を持つ刻み位置が存在すると最大公約数によるチャンネルの配列データ分割数の計算ができなくなり、 分割数を容易に決定できなくなります。小数部の値次第ではどの位置にノートの値を記録しても元の値の復元が困難になり、 最悪の場合、配列の長さが無限個数になっても元の値が復元不可能になることがあります。

        当メソッドで指定する配列データの最大分解能は、配列データの最大長を決定するために使用されます。 指定された値がそのまま実際の配列データの最大要素数になります。 ノートの値は実際の刻み位置に最も近い場所に記録されますが、出力されたBMSコンテンツを再度読み込んでも、 ノートの値は完全に同じ値にはなりません。

        分解能を高くすると出力されるBMSコンテンツのサイズが大きくなる可能性がありますが、 再度読み込んだ時の刻み位置の再現度は高くなります。一方、分解能を低くするとBMSコンテンツのサイズは小さくなりますが、 刻み位置の再現度が低くなり、刻み位置の近いノート同士の記録場所が競合してしまう危険性が上がります。

        分解能のデフォルト値はPRECISION_DEFAULTに規定されており、分解能を設定しない場合この値が使用されます。 分解能の指定可能範囲はPRECISION_MIN, PRECISION_MAXを参照してください。

        パラメータ:
        maxPrecision - 配列データ最大分解能
        戻り値:
        このオブジェクトのインスタンス
        例外:
        IllegalArgumentException - maxPrecisionがPRECISION_MIN未満、またはPRECISION_MAX超過
        関連項目:
        PRECISION_DEFAULT, PRECISION_MIN, PRECISION_MAX

      • setMetaComments

        public final BmsStandardSaver setMetaComments​(Collection<String> metaComments)
        メタ情報コメントを設定します。

        コメントの内容は1行につき1文字列、複数行記述する場合は複数の文字列をCollectionに設定して渡してください。

        文字列中の改行コード<CR>、<LF>は消去したうえで出力されます。

        パラメータ:
        metaComments - メタ情報コメント
        戻り値:
        このオブジェクトのインスタンス
        例外:
        NullPointerException - metaCommentsがnull
        NullPointerException - metaCommentsの中にnullが含まれる

      • setChannelComments

        public final BmsStandardSaver setChannelComments​(Collection<String> channelComments)
        チャンネルコメントを設定します。

        コメントの内容は1行につき1文字列、複数行記述する場合は複数の文字列をCollectionに設定して渡してください。

        文字列中の改行コード<CR>、<LF>は消去したうえで出力されます。

        パラメータ:
        channelComments - チャンネルコメント
        戻り値:
        このオブジェクトのインスタンス
        例外:
        NullPointerException - channelCommentsがnull
        NullPointerException - channelCommentsの中にnullが含まれる

      • setFooterComments

        public final BmsStandardSaver setFooterComments​(Collection<String> footerComments)
        フッターコメントを設定します。

        コメントの内容は1行につき1文字列、複数行記述する場合は複数の文字列をCollectionに設定して渡してください。

        文字列中の改行コード<CR>、<LF>は消去したうえで出力されます。

        パラメータ:
        footerComments - フッターコメント
        戻り値:
        このオブジェクトのインスタンス
        例外:
        NullPointerException - footerCommentsがnull
        NullPointerException - footerCommentsの中にnullが含まれる

      • setCharsets

        public final BmsStandardSaver setCharsets​(Charset... charsets)
        BMS書き込み時、BMSコンテンツのエンコードに使用する文字セットを設定します。

        同じ文字セットを複数追加しても意味はありません。後方で指定したほうの同一の文字セットが無視されます。

        文字セットの登録は省略可能です。省略した場合BmsLibrary.getDefaultCharsets()を呼び出し、 BMSライブラリのデフォルト文字セットリストを使用してエンコード処理が行われます。 これは、当メソッドで文字セットを1個も指定しなかった場合も同様です。

        パラメータ:
        charsets - BMSコンテンツのエンコード処理時に使用する文字セットリスト
        戻り値:
        このオブジェクトのインスタンス
        例外:
        NullPointerException - charsetsにnullが含まれている
        関連項目:
        BmsLibrary.setDefaultCharsets(Charset...)

      • onWrite

        protected void onWrite​(BmsContent content,
                       OutputStream dst)
                throws IOException,
                       BmsException
        指定された出力ストリームへ標準フォーマットでBMSコンテンツを出力します。

        当クラスによる標準フォーマットのBMSコンテンツ出力では、以下の順に各要素が出力されます。
        1. BMS宣言(存在する場合のみ)
        2. メタ情報コメント(指定した場合のみ)
        3. メタ情報
        4. チャンネルコメント(指定した場合のみ)
        5. チャンネルデータ
        6. フッターコメント(指定した場合のみ)

        指定BMSコンテンツに1件でもBMS宣言が存在する場合、BMSの先頭行には";?bms"が出力されます。

        メタ情報は原則としてBMS仕様で規定されたメタ情報のソート順で出力されますが、 構成単位が単体・複数のメタ情報が先に出力され、その後で残りの索引付きメタ情報が出力されます。

        出力するBMSコンテンツはsetCharsets(Charset...)で指定した順の文字セットでテキストをエンコードします。 文字セットを指定しなかった場合はBmsLibrary.getDefaultCharsets() でBMSライブラリのデフォルト文字セットリストを取得し使用します。全ての文字セットでテキストのエンコードに失敗した場合、 BMSコンテンツの出力は中止されBmsCompatExceptionをスローします。

        小数点以下の刻み位置を持つノートが含まれるチャンネルデータで出力位置に端数が発生する場合、 配列データの最大分解能の範囲で最も近い場所にノートの値を出力します。 分解能が不足していると、刻み位置の値が近いノート同士が同じ場所に出力しようとする現象が発生する場合があります。 その場合先に出力したほうの値が上書きされてしまい、データの欠落が発生することになりますので、 上書きを検出した時点でBMSコンテンツの出力は中止されBmsCompatExceptionをスローします。

        標準フォーマットのBMSでは小節数、索引付きメタ情報のインデックス値などで上限値の制約が厳しく、 楽曲の構成次第では標準フォーマットでは全ての情報を完全に出力できない場合があります。 そのようなケースでは、出力できない情報を欠落させ不完全な状態で出力するようなことはせず、 出力を中止してBmsCompatExceptionをスローします。

        定義:
        onWrite クラス内 BmsSaver
        パラメータ:
        content - 出力対象のBMSコンテンツ
        dst - 出力先ストリーム
        例外:
        IOException - dstへのBMSコンテンツ出力時に入出力エラーが発生した
        BmsException - BMSに関連する要因、または出力処理で例外がスローされエラー終了した
        BmsCompatException - 指定された全ての文字セットでテキストのエンコードが失敗した
        BmsCompatException - 配列データの分解能不足によりチャンネルデータの欠落が発生した
        BmsCompatException - 楽曲の構成が標準フォーマットのデータ表現可能範囲を超えた