Usage - OPTPiX/IndexColorShaderForUnity GitHub Wiki

使用方法

IndexColorShader for Unity（以降「ICS」）は以下の方法で使用します。


インストール方法

A. パッケージでインポートする場合

  1. ダウンロードからパッケージを取得します。
  2. Unity公式の手順 を参考にインポートしてください。

B. クローンまたはダウンロードzipを使う場合

  1. リポジトリをクローンか・ZIPでダウンロードします。
    クローンもしくはZIPデータの展開対象フォルダは、Unityのプロジェクトとは別にしておくことを推奨します。

  2. クローンもしくはZIPを展開したフォルダから、Unityのプロジェクト内にAssets以下のIndexColorShaderフォルダおよびIndexColorShader.metaファイルをコピーします。
    コピーする前にUnityを終了させておくことを推奨します。
    Unityのプロジェクト内のAssetsの直下にIndexColorShaderのフォルダが置かれるようにコピーすることを推奨します。

正常にインストールされたことを確認する。

Unity を起動してプロジェクトを開きます。
Unityの Tools メニューに IndexColorShader の項目があれば、ICSが組み込まれています。
存在しない場合、プロジェクト内のAssetsの下にIndexColorShaderフォルダが存在することを確認してください。
フォルダが存在しない場合は、新規プロジェクトを作成し、上記のインストール手順を1.から再度お試しください。


インポート方法

  1. OPTPiX ImageStudioなどを使用して、インポートする256色のPNG画像を用意します。
    この画像は、Unityプロジェクト外の任意のフォルダに置かれていても問題ありません。

  2. インポート先のアセットフォルダを、Unityの「Project」ウィンドウ内で選択してください。
    本選択はインポーターのウィンドウを開いてからでも行うことは可能です。

  3. Unityの上部メニュー[Tools]から、[IndexColorShader]-[Importer]を選択します。

    ICSのインポーターのウィンドウが開きます。

    インポーターの設定については後述の「インポーターの設定」を参照ください。

  4. インポーターのウィンドウ内にある「Import」のボタンを押すと、インポートするテクスチャーを選択するためのファイルダイアログが開きますので、始めに用意したインポートする256色のPNG画像を選択します。

  5. インポート中はプログレスバーが表示されますが、プログレスバーを表示したウィンドウが消えるとインポートが終了したことを意味します。
    インポートされたデータは2で選択しておいたアセットフォルダの中に格納されています。


インポートしたデータの表示方法

インポートしたデータは、下記の方法で確認や表示することができます。

  1. Unityの「Hierarchy」ウィンドウ内に、新しいGameObjectを作ります（Hierarchyウィンドウ内で、右クリックすると開くメニューの中から「Create Empty」を選ぶか、上部メニューバー[GameObject]-[CreateEmpty]を選択してください）。

  2. 1で設置したGameObjectを選択して、インスペクタの「Add Component」を選択して、下記の3つのコンポーネントを設置します。

    • [Mesh]-[MeshFilter]で、MeshFilterを設置します。このMeshFilterのMeshには、QuadかPlaneなどを設定します。
      Planeを設置した場合、（上方を向いているため）このGameObjectのTransformのRotationをX:90・Y:180などにして回転させないと、一見すると表示されませんので注意してください。

    • [Mesh]-[MeshRenderer]で、MeshRendererを設置します。このMeshRendererのMaterials（Size=1）のElement0に、インポートしたアセットのMaterialフォルダ内にあるマテリアルを設定します。

    • [Scripts]の中から「Script_IndexColorShader_SpritePalette」を設置します。このScript_IndexColorShader_SpritePaletteのDataPaletteに、インポートしたアセットのPaletteフォルダの中にあるパレットデータを設定します。

  3. 2で設置したGameObjectのScaleのXとY（MeshFilterに設定したのがPlaneの場合はXとZ）及びPositionを調節して、好みの大きさになるようにします。
    この際に、カメラの位置・方向と、GameObjectの位置には注意してください（カメラの視錐台=視野の外にGameObjectがある場合、特にGameウィンドウ上には表示されません）。

設定例

※インポートしたデータについては、インポーターの設定によっては、ファイル名の先頭に識別文字列が付加されている場合があります（デフォルトでは、パレットデータには「icsp_」・マテリアルには「iscm_」が付加される設定になっています）。

3のGameObjedctのサイズを調整する際の適した値については、後述の「オブジェクトの描画サイズとカメラとの関係」を参照してください。


（描画に使用するスクリプトがScript_IndexColorShader_SpritePaletteである場合に限り）上記の2の代わりに、SpriteRendererを使用することも可能で、2が下記の手順に変わります。

  1. 1で設置したGameObjectを選択して、インスペクタの「Add Component」を選択して、下記の2つのコンポーネントを設置します。

    • [Rendering]-[SpriteRenderer]で、SpriteRendererを設置します。このSpriteRendererのSpriteにSquereなど・MaterialにインポートしたアセットのMaterialフォルダ内にあるマテリアルを設定します。

    • [Scripts]の中から「Script_IndexColorShader_SpritePalette」を設置します。このScript_IndexColorShader_SpritePaletteのDataPaletteに、インポートしたアセットのPaletteフォルダの中にあるパレットデータを設定します。

このSpriteRendererを使った場合、SpriteRendererに設定したSpriteとTextureの「Pixels Per Unit」などの設定値も描画の大きさも絡んでくるため、通常のMeshRendererを使う場合とは（Transformの）Scaleの値が変わることに注意してください。


プレハブを利用した表示方法

  1. インポート時にプレハブを作る設定にしておきます。
  2. 画像ファイルをインポートすると下記のフォルダに生成されます。
    icsui_ で始まるプレハブはUI用、icss_ で始まるものは Sprite用です。
    UI用は CanvasRenderer が追加され、UI.MaskableGraphic を継承しており、Sprite用は SpriteRenderer が追加されています。
  3. UI用プレハブは、Scene に Canvas を追加し、子オブジェクトとして配置することで表示され、Sprite用プレハブは任意の位置に追加することで表示されます。

インポーターの設定

ICSはインポート時の設定を、インポーターのウィンドウ内で行うことができます。
下記に、それぞれの設定項目の役割の解説をします。

  • Options: Basic
    • Create Materiarl
      インポートしたテクスチャーと、ICSのシェーダを設定したマテリアルを作成します。
      ランタイムで独自でマテリアルを作成するような場合には本チェックを外すと、マテリアルを生成しません。
    • Source Material
      Create Materialにチェックが付いていた場合に出現する設定項目です。
      マテリアルを作成する際にマテリアルの元データとなるマテリアルを設定します。 初期状態で設定されているマテリアルは、ICSのシェーダを割り当てて・テクスチャーが空になっているものになっています。

  • Options : Overwrite Confirm
    下記の各項目のアセットに対して、上書が発生する場合に、上書を行って良いかの確認ダイアログを出します。
    • Texture : テクスチャー
    • Palette : パレットデータ
    • Material : マテリアル

  • Advanced Options
    ※比較的上級者向けの設定群です（通常使用している場合には変更する必要がないと思われます）。

    • Advanced Options: Naming Assets
      インポート時に下記の各項目のデータのファイル名の先頭に付加する文字列を設定します。
      ※このオプションを正常に設定し、インポートしたデータのファイル名が重ならないようにすることで、データをアセットバンドルに格納する時に名前の衝突が起こることを回避できます。

      • Texture : テクスチャー（初期値: 空文字列＝追加文字列なし）
      • Palette : パレットデータ（初期値: 「icsp_」）
      • Material : マテリアル（初期値: 「icsm_」）

    • Advanced Options: Naming Asset-Folders
      インポート時に下記の各項目のデータを格納するサブフォルダ名を設定します。

      • Texture : テクスチャー（初期値: 「Texture」）
      • Palette : パレットデータ（初期値: 「Palette」）
      • Material : マテリアル（初期値: 「Material」）

オブジェクトの描画サイズとカメラとの関係

これは参考情報となりますが……Unity上でインポートした画像をドット・バイ・ドット（完全な等倍）で出力するには、カメラの設定値とオブジェクトのTransformのScaleの値を正確に合わせる必要があります。

カメラのProjectionの設定が「Perspective（遠近法）」である場合には、表示位置やカメラからの距離によって表示される大きさが変わってしまうために、正確にドット・バイ・ドットに合わせるのはほぼ無理ですので、ScaleのXとYの比率が、インポートしたテクスチャー（もしくは表示しようとしている範囲）のピクセル数の比率になるようにして・目視で大きさを合わせてください。

一方、カメラのProjectionが「Orthograph（平行投影）」である場合には、カメラの「Size」の値の倍が「画面のサイズ」と同じになります。そのため、Sizeの値を「画面の縦ピクセル数÷2」の値に設定して、表示オブジェクトのScaleのXとYを「テクスチャー（ないしは表示範囲）のピクセル数」の値を設定すると、「画面上に等倍で出力した」状態になります。
※例えば、カメラのSizeを360（720÷2なので、全画面で720pと同様の画面の大きさだと計算されます）に設定した時に、表示オブジェクトのXを1280・Yを720（720pの画面のピクセルサイズ）に設定すると、画面いっぱいに画像が表示されるはずです。

また、MeshFilterのモデルとして（Quadではなく）Planeを設定した場合には、Quadのモデルの大きさが1×1であるのに対して、Planeは10×10のため、Scaleの設定を1/10してやる必要があります。

これらの原則をご理解の上、表示サイズを調整すると、想定通りの大きさで画面に出力することができるはずです。


その他（注意事項など）

  • ICSはUnityのGPUインスタンシング描画に対応しています。
    パレットの内容やテクスチャーを変更していたりする場合には、動的バッチングやGPUインスタンシングから漏れる場合がありますが、同じ設定で多数の描画を行う場合にはバッチングやGPUインスタンシングの対象になります。

  • インポート後に作成されるテクスチャー（通常はインポートしたアセットフォルダのTexture/の中に格納されています）の圧縮設定を圧縮テクスチャー（None以外）に設定してしまうと、描画時に再現される色が壊れる場合があります。
    具体的には、テクスチャーのインスペクタ内にある「Compression」の設定を「None」以外に設定しないようにしてください。
    ※これは、一般的には圧縮テクスチャーがピクセルの色データが（圧縮の都合から）破壊されるために起こる事象で、ICSのテクスチャーは色そのものではなく「パレットに定義されている色の番号」がテクスチャーに格納されているため、ピクセルの色データが破壊されると「参照するパレット内の色の番号がずれる」ために起こる描画色の破壊になります。


⚠️ **GitHub.com Fallback** ⚠️