※この翻訳ドキュメントはスクリプトによって出力・同期されています。内容が怪しそうな場合はGitHubにissueを追加したり英語の原文の確認をお願いします。

SvgMask クラスと関連インターフェース

このページではSvgMaskクラスとそれに関連したadd_svg_masking_objectメソッドやsvg_mask属性などのインターフェイスについて説明します。

クラス概要

SvgMaskクラスはSVGグラフィックのマスク設定を扱います。

重なりあった領域のみを表示する形でSVGのDisplayObject（例 : Rectangle）に別のSVGのDisplayObjectを設定することができます。

基本的な使い方

以下のステップでマスク設定を適用することができます。

  1. SvgMaskインスタンスを作成します。

  2. add_svg_masking_objectメソッドを使って作成したSvgMaskのインスタンスにDisplayObjectを追加します。

  3. マスクのインスタンスを対象のDisplayObjectのsvg_mask属性に設定します。

import apysc as ap

ap.Stage(
    background_color=ap.Color("#333"),
    stage_width=150,
    stage_height=150,
    stage_elem_id="stage",
)

# 1. Create an `SvgMask` instance.
mask: ap.SvgMask = ap.SvgMask()
circle: ap.Circle = ap.Circle(x=100, y=100, radius=50)

# 2. Add a `DisplayObject` to the created `SvgMask` instance.
mask.add_svg_masking_object(masking_object=circle)
rectangle: ap.Rectangle = ap.Rectangle(
    x=0, y=0, width=100, height=100, fill_color=ap.Colors.CYAN_00AAFF
)

# 3. Set a mask instance to the target `DisplayObject`'s `svg_mask` property.
rectangle.svg_mask = mask

ap.save_overall_html(dest_dir_path="svg_mask_basic_usage/")

DisplayObjectとマスクの座標を同期させたい場合のケース

マスクを設定する対象のDisplayObjectとマスク用のDisplayObjectはそれぞれ分離された座標値を持っています。

もし両方のDisplayObjectの座標を同じ量だけ変更したい場合にはSpriteのコンテナーを使用すると便利です。

Spriteのコンテナーの座標のみを変更することで、マスクの座標を維持したままDisplayObjectの座標を変更することができます。

特記事項 : マスク処理用のDisplayObjectはSpriteのコンテナーへと追加する必要はありません。

import apysc as ap

ap.Stage(
    background_color=ap.Color("#333"),
    stage_width=400,
    stage_height=300,
    stage_elem_id="stage",
)
mask: ap.SvgMask = ap.SvgMask()
circle: ap.Circle = ap.Circle(x=150, y=100, radius=100)
mask.add_svg_masking_object(masking_object=circle)
rectangle: ap.Rectangle = ap.Rectangle(
    x=50, y=50, width=100, height=100, fill_color=ap.Colors.CYAN_00AAFF
)
rectangle.svg_mask = mask

sprite: ap.Sprite = ap.Sprite()
# Notes: You do not need to add the circle for masking.
sprite.add_child(rectangle)
sprite.x = ap.Number(100)
sprite.y = ap.Number(50)

ap.save_overall_html(dest_dir_path="svg_mask_sprite_container_example/")

SvgMask クラスのコンストラクタのAPI

特記事項: このAPIドキュメントはドキュメントビルド用のスクリプトによって自動で生成・同期されています。そのためもしかしたらこの節の内容は前節までの内容と重複している場合があります。

[インターフェイスの構造] __init__(self, *, variable_name_suffix: str = '') -> None

[インターフェイス概要]

SVGのマスク処理のためのクラスです。

[引数]

  • variable_name_suffix: str, default “”

    • JavaScript上の変数のサフィックスの設定です。この設定はJavaScriptのデバッグ時に役立つことがあります。

[コードサンプル]

>>> import apysc as ap
>>> _ = ap.Stage()
>>> mask: ap.SvgMask = ap.SvgMask()
>>> circle: ap.Circle = ap.Circle(
...     x=50, y=50, radius=50, fill_color=ap.Colors.CYAN_00AAFF
... )
>>> mask.add_svg_masking_object(masking_object=circle)
>>> rectangle: ap.Rectangle = ap.Rectangle(
...     x=0, y=0, width=100, height=100, fill_color=ap.Colors.CYAN_00AAFF
... )
>>> rectangle.svg_mask = mask

SvgMask クラスの add_svg_masking_object メソッドのAPI

特記事項: このAPIドキュメントはドキュメントビルド用のスクリプトによって自動で生成・同期されています。そのためもしかしたらこの節の内容は前節までの内容と重複している場合があります。

[インターフェイスの構造] add_svg_masking_object(self, *, masking_object: apysc._display.graphics_base.GraphicsBase) -> None

[インターフェイス概要]

このマスクにマスク処理用のSVGのオブジェクトを追加します。このインスタンスは他のSVGのグラフィックスオブジェクトをマスクするためにそのオブジェクトを使用します。マスクへ複数のマスク処理用のオブジェクトを追加することができます。

[引数]

  • masking_object: GraphicsBase

    • 追加するマスク処理用のオブジェクト。

[コードサンプル]

>>> import apysc as ap
>>> _ = ap.Stage()
>>> mask: ap.SvgMask = ap.SvgMask()
>>> circle: ap.Circle = ap.Circle(
...     x=50, y=50, radius=50, fill_color=ap.Colors.CYAN_00AAFF
... )
>>> mask.add_svg_masking_object(masking_object=circle)
>>> rectangle: ap.Rectangle = ap.Rectangle(
...     x=0, y=0, width=100, height=100, fill_color=ap.Colors.CYAN_00AAFF
... )
>>> rectangle.svg_mask = mask

svg_mask 属性のAPI

特記事項: このAPIドキュメントはドキュメントビルド用のスクリプトによって自動で生成・同期されています。そのためもしかしたらこの節の内容は前節までの内容と重複している場合があります。

[インターフェイス概要]

SVGのマスク設定を取得します。もしマスク設定がされていなければ、この属性の値はNoneとなります。

[返却値]

  • mask: Optional[SvgMask]

    • マスク設定。

[コードサンプル]

>>> import apysc as ap
>>> _ = ap.Stage()
>>> mask: ap.SvgMask = ap.SvgMask()
>>> circle: ap.Circle = ap.Circle(
...     x=50, y=50, radius=50, fill_color=ap.Colors.CYAN_00AAFF
... )
>>> mask.add_svg_masking_object(masking_object=circle)
>>> rectangle: ap.Rectangle = ap.Rectangle(
...     x=0, y=0, width=100, height=100, fill_color=ap.Colors.CYAN_00AAFF
... )
>>> rectangle.svg_mask = mask
>>> assert rectangle.svg_mask == mask