パッケージ 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()

    • メソッドの詳細

      • getLastProcessedCharset

        public final Charset getLastProcessedCharset()
        このセーバで最後に書き込んだBMSコンテンツで使用した文字セットを取得します。

        当メソッドは以下のメソッドによりBMSコンテンツの読み込みを行った場合に使用された文字セットを取得します。

        一度も読み込みを行っていない場合当メソッドはnullを返します。 また、読み込み処理の途中で例外がスローされると文字セットの更新は行われません。

        戻り値:
        最後に書き込んだBMSコンテンツで使用した文字セット、またはnull
        関連項目:
        setCharsets(Charset...), BmsLibrary.setDefaultCharsets(Charset...)

      • 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...)

      • setAddBom

        public final BmsStandardSaver setAddBom​(boolean addBom)
        BMS書き込み時、BOM(Byte Order Mark)を付加するかどうかを設定します。

        この設定を有効にすると、BOMに対応する文字セットの場合にそれぞれの文字セットに対応したBOMを付加します。 BMSライブラリでBOMの付加に対応する文字セットは「UTF-8」「UTF-16LE」「UTF-16BE」です。 それ以外の文字セットではBOMの付加は行われません。

        デフォルトではこの設定は無効になっています。

        パラメータ:
        addBom - BOMを付加するかどうか
        戻り値:
        このオブジェクトのインスタンス

      • isCompatible

        public static boolean isCompatible​(BmsContent content)
        指定BMSコンテンツが標準フォーマットと互換性があるかを検査します。

        BMSの標準フォーマットでは表現可能なデータの範囲に制限があり、 BMSコンテンツの構成次第では標準フォーマットでの出力ができない場合があります。 当メソッドは標準フォーマットとしての出力が可能かどうか検査し、その結果を返します。 当メソッドでは具体的に以下の観点で標準フォーマットとの互換性の有無を検査します。

        • データ型がBmsType.BASE, BmsType.ARRAYのメタ情報が設定された基数の最大値を超過していないか
        • 索引付きメタ情報で、設定された基数の最大値を超えるインデックスにデータを設定していないか
        • 小節数がMEASURE_COUNT_MAXを超過していないか
        • データ型がBmsType.BASEの小節データが、設定された基数の最大値を超過していないか
        • ノートの値が、データ型ごとの基数(BmsType.ARRAYの場合選択された基数)の最大値を超過していないか

        ※ユーザーチャンネルのタイムライン要素は検査対象外です。

        以上の検査を行い1つでも該当するデータが見つかった場合、標準フォーマットとの互換性はありません。 尚、当クラスでの出力を行う際にも当メソッドと同じ検査が行われます。

        パラメータ:
        content - 検査対象のBMSコンテンツ
        戻り値:
        標準フォーマットとの互換性があればtrue、そうでなければfalse
        例外:
        NullPointerException - contentがnull
        IllegalArgumentException - contentが編集モード

      • 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をスローします。検査は内部的に isCompatible(BmsContent) と同じ検査アルゴリズムを使用します。具体的な検査処理の詳細は同メソッドの説明を参照してください。

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