エレメント

エレメントは、ユーザーインターフェース内の矩形です。インターフェース内のすべての画像、テキスト、グループはElementコンポーネントを持つエンティティで、親エレメントを基準に、またはスクリーンの直下にある場合はそのスクリーンを基準にレイアウトされます。このページでは、すべてのエレメントに共通するレイアウトを扱います。エレメントが何を描画するかは、イメージエレメントとテキストエレメントのページで扱います。

エレメントのタイプ

エレメントのtypeは、そのエレメントが何を描画するかを決めます。

タイプ	描画するもの	用途
Group（`pc.ELEMENTTYPE_GROUP`）	なし	コンテナ、レイアウトグループ、不可視の入力領域。グループエレメントを参照してください
Image（`pc.ELEMENTTYPE_IMAGE`）	単色、テクスチャ、またはスプライト	パネル、アイコン、ボタン、マスク。イメージエレメントを参照してください
Text（`pc.ELEMENTTYPE_TEXT`）	フォントアセットで描画する文字列	ラベルやその他のテキスト。テキストエレメントを参照してください

アンカー

アンカーは、エレメントが親のどこに取り付けられるかを表します。親の幅と高さに対する割合で、左下隅の0, 0から右上の1, 1までの範囲で指定し、アンカーの左辺、下辺、右辺、上辺を表す4つの数値を持ちます。左辺と右辺が等しく、下辺と上辺が等しい場合、アンカーは1つの点になります。このときエレメントは自身の幅と高さを保ち、その位置はその点からのオフセットになります。角にアンカーすると、親のサイズがどう変わっても、エレメントはその角にとどまります。

大きなパネルの中にある9つの小さな矩形。各隅に1つ、各辺の中央に1つ、中心に1つある。それぞれのアンカー点をひし形で示している

エディターのPresetフィールドは、よく使う組み合わせを設定します。Stretch以外の各プリセットには2つのバージョンがあります。Anchorはアンカーのみを設定し、Anchor & Pivotはピボットも同じ点に移動するため、エレメントは角や辺を中心とする位置ではなく、角や辺の内側に収まります。

プリセット	アンカー	ピボット
Top Left Anchor & Pivot	`0, 1, 0, 1`	`0, 1`
Top Anchor & Pivot	`0.5, 1, 0.5, 1`	`0.5, 1`
Top Right Anchor & Pivot	`1, 1, 1, 1`	`1, 1`
Left Anchor & Pivot	`0, 0.5, 0, 0.5`	`0, 0.5`
Center Anchor & Pivot	`0.5, 0.5, 0.5, 0.5`	`0.5, 0.5`
Right Anchor & Pivot	`1, 0.5, 1, 0.5`	`1, 0.5`
Bottom Left Anchor & Pivot	`0, 0, 0, 0`	`0, 0`
Bottom Anchor & Pivot	`0.5, 0, 0.5, 0`	`0.5, 0`
Bottom Right Anchor & Pivot	`1, 0, 1, 0`	`1, 0`
Stretch	`0, 0, 1, 1`	変更されません。マージンも0に設定します

例えば、次のスコアはスクリーンの右上隅にあり、各辺から20単位内側に配置されます。

Engine
Editor
React
Web Components

const score = new pc.Entity('score');
score.addComponent('element', {
    type: pc.ELEMENTTYPE_TEXT,
    fontAsset: font.id,
    text: '1250',
    anchor: [1, 1, 1, 1],
    pivot: [1, 1]
});
score.setLocalPosition(-20, -20, 0);
screen.addChild(score);

<Entity name="score" position={[-20, -20, 0]}>
  <Element type="text" fontAsset={font} text="1250" anchor={[1, 1, 1, 1]} pivot={[1, 1]} />
</Entity>

<pc-entity name="score" position="-20 -20 0">
    <pc-element type="text" font-asset="arial" text="1250" anchor="1 1 1 1" pivot="1 1"></pc-element>
</pc-entity>

コード、React、Web Componentsのいずれの場合も、アンカーとピボットを指定せずに作成したエレメントは、アンカーが0, 0, 0, 0、ピボットが0, 0、つまり親の左下隅に配置されます。エレメントを作成するときは、必ず両方を設定してください。

ピボット

ピボットは、エレメントの位置に置かれるエレメント上の点で、エレメント自身の幅と高さに対する割合で指定します。0, 0は左下隅、0.5, 0.5は中心、1, 1は右上隅です。中央のアンカーと中央のピボットを持つエレメントは親の真ん中に配置されますが、中央のアンカーと0, 0のピボットを持つエレメントは、左下隅が真ん中に来ます。

ピボットは、エレメントの回転とスケーリングの中心となる点でもあります。

同じ矩形の3つのコピーを、それぞれ異なるピボット（左下隅、中心、右上隅）を中心に20度回転させたもの

// アイコンを中心の周りに回転させる
icon.element.pivot = new pc.Vec2(0.5, 0.5);
icon.setLocalEulerAngles(0, 0, 20);

分割アンカー

ある軸でアンカーの2つの辺が異なる場合、アンカーはその軸で分割されます。エレメントの辺は親の異なる2点に取り付けられ、エレメントはその軸で親と一緒に伸縮します。このとき、その軸の幅または高さはアンカーとマージンから決まり、widthまたはheightの値は無視されます。

例えば、スクリーンの上部に横に渡るバーは、水平方向に分割され、高さは固定のままです。

// バーの左右の辺を、親の上端の左右に取り付ける
bar.element.anchor = new pc.Vec4(0, 1, 1, 1);
bar.element.pivot = new pc.Vec2(0.5, 1);
bar.element.left = 0;
bar.element.right = 0;
bar.element.height = 80;

アンカーを変更してもエレメントの現在のマージンは保たれるため、ここでleftとrightを設定しているように、新しく分割した軸のマージンも設定してください。分割アンカーでエレメントを作成する場合も同じです。marginを指定しないと、デフォルトのサイズ32 × 32の辺にあたるデフォルトのマージン0, 0, -32, -32で始まり、右と上のアンカーから32単位はみ出します。

幅の広い親と狭い親の中にある同じ2つの子。四辺のマージンを除いて親を埋めるパネルと、上部に横に伸ばしたバー。どちらも親の幅に追従する

マージン

マージンは、アンカーが分割されている軸での、エレメントの各辺とアンカーとの距離です。左、下、右、上の順に4つの数値を持ち、正の値は各辺を内側に移動します。20単位の縁を残して親を埋めるパネルは、Stretchアンカー（0, 0, 1, 1）と、四辺すべてに20のマージンを持ちます。

Engine
Editor
React
Web Components

const background = new pc.Entity('background');
background.addComponent('element', {
    type: pc.ELEMENTTYPE_IMAGE,
    anchor: [0, 0, 1, 1],
    margin: [20, 20, 20, 20],
    color: new pc.Color(0.16, 0.18, 0.23)
});
panel.addChild(background);

<Entity name="background">
  <Element type="image" anchor={[0, 0, 1, 1]} margin={[20, 20, 20, 20]} color="#292e3b" />
</Entity>

<pc-entity name="background">
    <pc-element type="image" anchor="0 0 1 1" margin="20 20 20 20" color="#292e3b"></pc-element>
</pc-entity>

left、bottom、right、topプロパティは、4つのマージンを1つずつ読み書きします。コードから4つすべてを一度に設定するには、新しいpc.Vec4を代入します。marginのセッターは、代入されたベクトルから値をコピーするためです。

background.element.left = 40;
background.element.margin = new pc.Vec4(10, 10, 10, 10);

幅と高さ

エレメントには2つのサイズがあります。

widthとheight：設定されたサイズで、スクリーンの単位で表されます。アンカーが点である軸に適用されます。
calculatedWidthとcalculatedHeight：エレメントが実際に持つサイズです。アンカーが分割されている軸や、レイアウトグループがエレメントのサイズを決める場合に、widthやheightとは異なる値になります。

テキストエレメントは、テキストに合わせて自身のサイズを設定することもできます。エレメントが表示されているサイズが必要なとき、例えばラベルに背景を合わせるときは、計算されたサイズを読み取ります。

background.element.width = label.element.calculatedWidth + 40;

エディターでのサイズ変更

エディターでエレメントを選択し、ツールバーでResize Element Componentを選ぶか4を押してから、ビューポートで角のハンドルをドラッグすると、エレメントの幅と高さを変更できます。反対側の角はその場にとどまります。スクリーン上のエレメントを選択しているときは、ビューポートにそのアンカーの角を示す灰色のハンドルも表示され、それらをドラッグするとアンカーが変わります。

ビューポートは、2Dスクリーンを3Dシーン内の平らな矩形として描画します。正面から見るには、ビューポートのカメラをFrontに切り替えます。

グループエレメント

グループエレメントは何も描画しませんが、他のエレメントと同じように位置とサイズを持つため、インターフェースを整理するための手段になります。

コンテナ：パネル、メニュー、HUDのパーツをグループの下に置くと、まとめて移動、サイズ変更、表示、非表示にできます。グループのエンティティを無効にすると、その下にあるものがすべて非表示になります。
レイアウト：レイアウトグループは通常、子を並べるグループエレメントです。
不可視の入力領域：入力を有効にしたグループは、矩形全体で入力を受け取ります。これにより、スクロールビューのコンテンツを、何もない部分でもドラッグできます。

エレメントの色と不透明度は、そのエレメントにのみ適用されます。子には引き継がれないため、パネルをフェードさせるには、その下にあるすべてのイメージエレメントとテキストエレメントをフェードさせる必要があります。よく使うウィジェットを参照してください。

回転、スケール、深度

上のピボットの例のように、エレメントはエンティティのトランスフォームを通じて、setLocalEulerAnglesとsetLocalScaleでピボットを中心に回転・スケーリングします。エレメントをスクリーンの平面内に保つには、z軸を中心に回転させます。

スクリーン空間のスクリーンではz位置は効果がなく、何が上に描画されるかはヒエラルキーで決まります（描画順とパフォーマンスを参照）。ワールド空間のスクリーンでは、z位置によってエレメントがスクリーンの平面から離れます。