2 パラメータのセマンティクスとアノテーション

以降では、MMEffect用のエフェクトファイルで使用できる、パラメータのセマンティクスとアノテーションについて説明する。

パラメータの宣言をセマンティクスやアノテーションで修飾することで、レンダリングに必要な様々な情報を、そのパラメータを解して取得できる。

パラメータのセマンティクスとアノテーションは、以下のように記述する。

型名 パラメータ名 : セマンティクス名 < 型名 アノテーション1 = 値; 型名 アノテーション2 = 値; ... > ;

セマンティクスによっては、アノテーションを指定しないものもある。

なお、セマンティクス名とアノテーション名の大文字小文字の違いは無視される。

2.1 ジオメトリ変換

参考：MSDNの参考資料

頂点の座標変換に使用する変換行列。

座標変換には、ワールド変換、ビュー変換、プロジェクション変換（射影変換）がある。

6つのセマンティクスは、それぞれ、

を表す。型はfloat4x4。

"WORLDINVERSE"のように、セマンティクスの末尾に"INVERSE"を付加すると、各行列の逆行列が得られる。

また、"WORLDTRANSPOSE"のように、末尾に"TRANSPOSE"を付加すると、各行列の転置行列が得られる。

逆行列の転置行列を得るには、末尾に"INVERSETRANSPOSE"を付加する。

○アノテーション

○使用例

float4x4 WorldMatrix : WORLD ;
float4x4 WorldViewProjMatrix : WORLDVIEWPROJECTION ;
float4x4 LightViewMatrix : VIEW < string Object = "Light"; > ;
float4x4 WorldInvMatrix : WORLDINVERSE ;
float4x4 WorldViewProjTransMatrix : WORLDVIEWPROJECTIONTRANSPOSE ;

○補足

2.2 ライトとマテリアル

参考：MSDN

3Dオブジェクトのマテリアル(材質)の色値、またはライトの色値。

6つのセマンティクスは、それぞれ、

を表す。

トゥーン色は、PMDモデルのトゥーンレンダリングにおける、影の色（具体的にはtoon??.bmpの左下隅の色）を表す。

型は、"SPECULARPOWER"のみfloatで、それ以外はfloat3またはfloat4ある。色は4つの成分（赤・緑・青・アルファ(透明度)）で構成される。型にfloat3を指定するとアルファ値が省略される。

○アノテーション

・string Object (必須)

ライト色と、オブジェクトのマテリアル色のどちらを取得するかを指定する。"Light"または"Geometry"が指定できる。

オブジェクトのマテリアル色を取得するには、"Geometry"を指定する。ライト色を取得するには、"Light"を指定する。"SPECULARPOWER"と"EMISSIVE"および"TOONCOLOR"には、ライト色がないため、"Light"は指定できない。

○使用例

float4 MaterialDiffuse  : DIFFUSE  < string Object = "Geometry"; >;
float3 MaterialAmbient  : AMBIENT  < string Object = "Geometry"; >;
float3 MaterialEmmisive : EMISSIVE < string Object = "Geometry"; >;
float3 MaterialSpecular : SPECULAR < string Object = "Geometry"; >;
float  SpecularPower    : SPECULARPOWER < string Object = "Geometry"; >;
float3 MaterialToon     : TOONCOLOR;
float3 EdgeColor        : EDGECOLOR;
float3 LightDiffuse     : DIFFUSE   < string Object = "Light"; >;
float3 LightAmbient     : AMBIENT   < string Object = "Light"; >;
float3 LightSpecular    : SPECULAR  < string Object = "Light"; >;
static float4 DiffuseColor  = MaterialDiffuse  * float4(LightDiffuse, 1.0f);
static float3 AmbientColor  = MaterialAmbient  * LightAmbient + MaterialEmmisive;
static float3 SpecularColor = MaterialSpecular * LightSpecular;
float4 GroundShadowColor : GROUNDSHADOWCOLOR;

○補足

  • ●POSITION

  • ●DIRECTION

    • ライトまたはカメラの、ワールド空間内における位置および向き。型は、float3またはfloat4である。

    ○アノテーション

    ・string Object (必須)

    カメラおよびライトのどちらの座標を取得するかを指定する。"Camera"または"Light"が指定できる。

    ○使用例

    float3 LightDirection : DIRECTION < string Object = "Light"; >;
float3 CameraPosition : POSITION  < string Object = "Camera"; >;

    ○補足

    MMDのライトは、ディレクショナルライトであるため、ライトの位置座標は、ライトの向きと逆方向の無限遠点になる。

    ●MATERIALTEXTURE

    マテリアルに設定されているテクスチャ。

    ○アノテーション

    なし

    ○使用例

    texture ObjectTexture : MATERIALTEXTURE;
    
sampler ObjTexSampler = sampler_state
{
    texture = <ObjectTexture>;
    MINFILTER = LINEAR;
    MAGFILTER = LINEAR;
    MIPFILTER = LINEAR;
    ADDRESSU  = WRAP;
    ADDRESSV  = WRAP;
};
// tex2D(ObjTexSampler, float2(x,y)) で内容を参照できる

    ○補足

    ・各色値は、MMDPass="zplot"またはMMDPass="edge"のTechniqueにおいては、正しく取得できない。

    ●MATERIALSPHEREMAP

    マテリアルに設定されている、スフィアマップテクスチャ。

    ○アノテーション

    なし

    ○使用例

    texture ObjectSphereMap : MATERIALSPHEREMAP;
sampler ObjSphSampler = sampler_state
{
    texture = <ObjectSphereMap>;
    MINFILTER = LINEAR;
    MAGFILTER = LINEAR;
    MIPFILTER = LINEAR;
    ADDRESSU  = WRAP;
    ADDRESSV  = WRAP;
};
// tex2D(ObjSphSampler, float2(x,y)) で内容を参照できる

    ○補足

    ・各色値は、MMDPass="zplot"またはMMDPass="edge"のTechniqueにおいては、正しく取得できない。

    ●MATERIALTOONTEXTURE

    マテリアルに設定されている、トゥーンマップテクスチャ。

    ○アノテーション

    なし

    ○使用例

    texture ObjectToonTexture : MATERIALTOONTEXTURE;
    
sampler ObjToonSampler = sampler_state
{
    texture = <ObjectSphereMap>;
    MINFILTER = LINEAR;
    MAGFILTER = LINEAR;
    MIPFILTER = NONE;
    ADDRESSU  = CLAMP;
    ADDRESSV  = CLAMP;
};
// tex2D(ObjToonSampler, float2(x,y)) で内容を参照できる

    ○補足

    ●ADDINGTEXTURE

    ●MULTIPLYINGTEXTURE

    ●ADDINGSPHERETEXTURE

    ●MULTIPLYINGSPHERETEXTURE

    PMX材質モーフのための、テクスチャおよびスフィアマップのテクスチャに対しての、加算値および乗算値。

    ○アノテーション

    なし

    ○使用例

    float4   TextureAddValue   : ADDINGTEXTURE;
float4   TextureMulValue   : MULTIPLYINGTEXTURE;
float4   SphereAddValue    : ADDINGSPHERETEXTURE;
float4   SphereMulValue    : MULTIPLYINGSPHERETEXTURE;

    ○補足

    2.3 スクリーン情報

    ●VIEWPORTPIXELSIZE

    レンダリングターゲットのスクリーンのサイズ。型はfloat2。単位はピクセル。

    ※この値は、MMDのスクリーンもしくはオフスクリーンレンダリングターゲットのサイズを指す

    Scriptsの"RenderColorTarget"コマンドで、レンダリングターゲットが変更しても、この値は変化しない

    ○アノテーション

    なし

    ○使用例

    float2 ScreenSize : VIEWPORTPIXELSIZE;

    ○補足

    ・内部的には、Viewportの.Widthと.Heightの値を参照している。

    2.4 時間

    ●TIME

    ●ELAPSEDTIME

    時間情報。
    型はfloat。単位は秒。

    "TIME"は、0フレーム目からの再生時間を表す。
    例えば、0フレーム目では、0.0（秒）となり、45フレーム目では1.5（秒）となる。

    "ELAPSEDTIME"は、前回の描画からの経過時間を表す。
    例えば、60fpsでAVI出力時には、"ELAPSEDTIME"の値は、1/60 で一定になる。

    ○アノテーション

    MMDが編集モードである場合でも、フレームと連動するかを指定する。
    trueまたはfalseを指定する。デフォルトはfalse。

    MMDが編集モードのときには、フレームの再生は停止しているため、
    TIMEの値が常にフレーム時間と連動していると、
    編集モード中は、この値を使用しているアニメーションも停止することになる。

    このアノテーションにfalseが指定されていると、
    編集モード中、TIMEおよびELAPSEDTIMEの値には、フレーム時間ではなくシステム時間が使用される。
    これにより、編集モード中でもアニメーションが停止しなくなる。

    ○使用例

    float ftime : TIME <bool SyncInEditMode=true;>;
        float elapsed_time : ELAPSEDTIME;
        static float fps = 1.0 / elapsed_time;

    補足

    ・SyncInEditMode=trueの場合、ELAPSEDTIMEの値は、MMD上でのフレーム移動操作により、0やマイナスになりうる。

    2.5 マウス

    ●MOUSEPOSITION

    マウスの現在位置。
    型はfloat2。

    MMDの描画領域の中心を(0,0)とし、左下隅が(-1,-1)、右上隅が(1,1)になる。
    このxy座標の取り方は、プロジェクション変換した後の、頂点座標と同じである。

    ○アノテーション

    なし

    ○使用例

    float2 pos : MOUSEPOSITION;

    ●LEFTMOUSEDOWN

    ●MIDDLEMOUSEDOWN

    ●RIGHTMOUSEDOWN

    マウスボタンに関する情報。
    型はfloat4。

    取得できる値は、以下の4成分からなる。
    ・最後にボタンが押されたときのマウスの座標（xとy）
    ・現在ボタンが押されているか （0 or 1）
    ・最後にボタンが押された時点のTIME値(秒)

    なお、マウスの座標の取り方は、MOUSEPOSITIONと同じである。

    ○アノテーション

    なし

    ○使用例

    float4 mouse_down : LEFTMOUSEDOWN;
static float2 pos = mouse_down.xy;
static bool is_pressed = (mouse_down.z != 0);

    2.6 コントロールオブジェクト

    ●CONTROLOBJECT

    指定したオブジェクトの、座標やワールド変換行列を取得する。
    主に、シェーダに必要なパラメータをMMD上から制御する場合に使用する。

    型はbool, float, float3, float4またはfloat4x4。

    使用する型によって、取得できる情報が異なる。

    また、itemアノテーションに特殊な文字列を指定することにより、
    これら以外の値も取得できる。

    ○アノテーション

    ○使用例

    //"stage01.x"が表示されているか否かを取得
bool flag : CONTROLOBJECT < string name = "stage01.x"; >;
    
//"negi.x"のスケーリング値を取得
float scaling : CONTROLOBJECT < string name = "negi.x"; >;

//"negi.x"の回転Xを取得
float rot_x : CONTROLOBJECT < string name = "negi.x"; string item = "Rx"; >;

//"negi.x"の回転Xを度数単位で取得
float rot_x_rad : CONTROLOBJECT < string name = "negi.x"; string item = "Rx"; >;
static float rot_x = rot_x_rad * 180 / 3.14159265;

//"弱音ハク.pmd"のボーン「ポニテＩＫ」の座標取得
float3 pos : CONTROLOBJECT < string name = "弱音ハク.pmd"; string item = "ポニテＩＫ"; >;

//"弱音ハク.pmd"の表情「まばたき」の値取得
float morph : CONTROLOBJECT < string name = "弱音ハク.pmd"; string item = "まばたき"; >;

    ○補足

    ・PMDモデルのワールド変換行列は単位行列で変化しないため、
    通常は、Xファイル（アクセサリ）に対して使用する。

    ・アクセサリのスケーリング値は、MMD上でアクセサリのSizeに指定した値を10倍した値になる。
    （内部的には、length(world_matrix._11_12_13) で得られる値を使用している）

    ・指定したファイル名のオブジェクトが存在しない場合、以下の値が設定される。

    ・MME ver0.20より、参照先のオブジェクトが参照元のオブジェクトよりも後に描画されていても、
    値を取得できるようになった。

    ・指定した名前を持つオブジェクトが複数存在する場合、以下の優先順位で選択される。

    ・ダミーボーン.pmdなどのように、頂点を一つも持たないオブジェクトについては、
    参照先に指定しても座標を取得できない。

    2.7 テクスチャ関連

    ●通常テクスチャ

    テクスチャを生成する。

    型はtexture, texture2D, texture3D, textureCUBEのうちいずれか。RENDERCOLORTARGET, RENDERDEPTHSTENCILTARGET, ANIMATEDTEXTURE 以外のセマンティクスは指定しても無視される。

    生成したテクスチャの内容は、サンプラを設定した上で、tex2D(s, t)関数などを呼び出すことで参照できる。

    ○アノテーション

    ○使用例

    texture negi_tex < string ResourceName = "negi.bmp"; >;
sampler TexSampler = sampler_state {
    texture = ;
};

texture2D map_tex <
    string ResourceName = "map.png";
    int Miplevels = 1;
    int Width = 64;
    int Height = 64;
>;

    ●RENDERCOLORTARGET

    レンダリングターゲットに指定可能なサーフェイスを生成する。
    このセマンティクスを指定して生成したテクスチャは、スクリプトのRenderColorTargetに
    指定することができる。
    レンダリング後は、通常のテクスチャと同様に、tex2D()関数で内容を参照できる。
    型はtexture, texture2Dのうちいずれか。

    ○アノテーション

    ○使用例

    texture2D ScnMap : RENDERCOLORTARGET <
    float2 ViewPortRatio = {1.0,1.0};
    int MipLevels = 1;
    string Format = "A8R8G8B8" ;
>;
sampler2D ScnSamp = sampler_state {
    texture = ;
};

technique Tech <
    string Script = "RenderColorTarget0=ScnMap;
    ...
>;

    ●RENDERDEPTHSTENCILTARGET

    深度ステンシルサーフェイス（いわゆるZバッファ）を生成する。 このセマンティクスを指定して生成したテクスチャは、スクリプトのRenderDepthStencilTargetに 指定することができる。 RENDERCOLORTARGETで生成したテクスチャとは違い、このセマンティクスで生成したテクスチャは、 レンダリング後も、内容を参照することはできない。
    型はtexture, texture2Dのうちいずれか。

    ○アノテーション

    ○使用例

    texture2D DepthBuffer : RENDERDEPTHSTENCILTARGET <
    float2 ViewPortRatio = {2.0,2.0};
    string Format = "D24S8";
>;

technique Tech <
    string Script = "RenderDepthStencilTarget=DepthBuffer;
    ...
>;

    ●ANIMATEDTEXTURE

    アニメーションテクスチャを生成する。 デフォルトでは、フレーム時間に連動して自動的にアニメーションするほか、 コントロールオブジェクトなどの、別のパラメータに連動してアニメーションさせることもできる。
    型はtexture, texture2Dのうちいずれか。

    ○アノテーション

    ○使用例

    float atime: ControlObject < string name = "seek.x"; >;

texture AnimeTex : ANIMATEDTEXTURE <
    string ResourceName = "anime.png";
    string SeekVariable="atime";
>;

    ○補足

    ●OFFSCREENRENDERTARGET

    オフスクリーンレンダリングターゲット生成する。オフスクリーンレンダリングターゲットを生成すると、自動的に、指定した条件で全オブジェクトの描画が、このレンダリングターゲットに対して行われるようになる。レンダリング結果は、通常のテクスチャと同様にtex2D()関数で参照できる
    型はtexture, texture2Dのうちいずれか。

    ○アノテーション

    ○使用例

    texture MirrorRT: OFFSCREENRENDERTARGET <
    string Description = "OffScreen RenderTarget for Mirror.fx";
    int Width = 256;
    int Height = 256;
    float4 ClearColor = { 1, 1, 1, 1 };
    float ClearDepth = 1.0;
    bool AntiAlias = true;
    string DefaultEffect = 
        "self = hide;"
        "Mirror*.x = hide;"
        "*=MirrorObject.fx;";
>;

    ●TEXTUREVALUE

    指定したテクスチャの、テクセル情報を取得して配列に格納する。 これを使用すると、VTF(Vertex Texture Fetching)に対応しない環境でも、 頂点シェーダからテクスチャの値を参照できる（※制限あり。補足参照）
    型はfloat4の2次元配列（[縦幅][横幅]）、もしくは1次元配列。

    ○アノテーション

    ○使用例

    float4 ParticleBaseArray[TEX_HEIGHT][TEX_WIDTH] : TEXTUREVALUE <
    string TextureName = "ParticleBaseTex";
>;

float4 ParticleBaseArray2[TEX_HEIGHT] : TEXTUREVALUE <
    string TextureName = "ParticleBaseTex2";
>;

float4 color1 = ParticleBaseArray[v][u];
float3 color2 = ParticleBaseArray2[idx].rgb;

    ○補足

    2.8 エフェクトファイル

    ●STANDARDSGLOBAL

    SAS（Standard Annotations and Semantics）のバージョンを指定する。 また、エフェクトファイル全体に関するアノテーションを記述するためにも用いられる。

    パラメータ名は "Script"、型は float、値としてバージョン番号の 0.8 を指定すること。

    ○アノテーション

    ○使用例

    //通常エフェクトの場合
float Script : STANDARDSGLOBAL <
    string ScriptOutput = "color";
    string ScriptClass = "object";
    string ScriptOrder = "standard";
> = 0.8;

//ポストエフェクトの場合
float Script : STANDARDSGLOBAL <
    string ScriptOutput = "color";
    string ScriptClass = "scene";
    string ScriptOrder = "postprocess";
> = 0.8;

    2.9 特殊パラメータ

    以下の名前のパラメータは、セマンティクス無しで自動的に値が設定される。

    ○使用例

    bool parthf;
bool use_texture;
bool use_toon;
int VertexCount;

    ○補足

    ・MMDPass="object","object_ss"以外の場合、これらのパラメータに正しい値が設定される保証はない。

    2.10 頂点シェーダセマンティクス

    ●_INDEX

    頂点シェーダにおいて、頂点のインデックス値を取得するためのセマンティクス。頂点シェーダの入力パラメータで使用できる。型はint。

    ○使用例

    VS_OUTPUT Basic_VS(float4 Pos : POSITION, int index: _INDEX) {
    VS_OUTPUT Out;
    Out.Pos = mul( Pos, WorldViewProjMatrix );

    float f = (float)index/VertexCount;
    Out.Color = float4(f,f,f,1);
    
    return Out;
}

    ○補足

    ・頂点シェーダに渡す過程で一旦float型に変換しているため、インデックス値が 2^24=16777216 を超えると、正確な値を取得できない。

    2.11 マクロ

    ●MME_MIPMAP

    MMDが、テクスチャのミップマップに対応している場合に定義される。

    ○使用例

    sampler ObjTexSampler = sampler_state {
      texture = ;
#ifdef MME_MIPMAP
    MIPFILTER = LINEAR;
#endif
};