CSS Painting API Level 1

`registerPaint(name, paintCtor)@m ~method手続きは： ◎ When the registerPaint(name, paintCtor) method is called, the user agent must run the following steps:

1. ~IF［ %name ~EQ 空~文字列 ］ ⇒ ~THROW `TypeError$E ◎ If the name is an empty string, throw a TypeError and abort all these steps.
2. %塗り定義~map ~LET `PaintWorkletGlobalScope$I の`塗り定義~map$ ◎ Let paintDefinitionMap be PaintWorkletGlobalScope's paint definitions map.
3. ~IF［ %塗り定義~map[ %name ] ~NEQ ε ］ ⇒ ~THROW `InvalidModificationError$E ◎ If paintDefinitionMap[name] exists throw a "InvalidModificationError" DOMException and abort all these steps.
4. %入力~prop~list ~LET `Get$jA( %paintCtor, `inputProperties^l ) の結果に応じて ⇒＃ `undefined^jv ならば空な ~SeqDS ／ ~ELSE_ `~IDL値に変換する$( 結果, ~SeqDS )（例外投出あり） ◎ Let inputProperties be an empty sequence<DOMString>. ◎ Let inputPropertiesIterable be the result of Get(paintCtor, "inputProperties"). ◎ If inputPropertiesIterable is not undefined, then set inputProperties to the result of converting inputPropertiesIterable to a sequence<DOMString>. If an exception is thrown, rethrow the exception and abort all these steps.

5. %入力~prop~list から［ `~supportされる~CSS~prop$, `~custom~prop$ ］以外の~itemを取り除く ◎ Filter inputProperties so that it only contains supported CSS properties and custom properties.

   注記： 入力~prop~list取得子 【 `get inputProperties()^c 】 が供する~CSS~propの~listは、~custom~prop, 略式~propも含めれることに加え、塗り画像~classを前方-互換にするため，~UAにとって現在~妥当でない~prop（例： `margin-nanjasorya-property^p ）も含めれる。 ◎ Note: The list of CSS properties provided by the input properties getter can either be custom or native CSS properties. ◎ Note: The list of CSS properties may contain shorthands. ◎ Note: In order for a paint image class to be forwards compatible, the list of CSS properties can also contains currently invalid properties for the user agent. For example margin-bikeshed-property.

6. %入力~引数~list ~LET `Get$jA( %paintCtor, `inputArguments^l ) の結果に応じて ⇒＃ `undefined^jv ならば空な ~SeqDS ／ ~ELSE_ `~IDL値に変換する$( 結果, ~SeqDS )（例外投出あり） ◎ Let inputArguments be an empty sequence<DOMString>. ◎ Let inputArgumentsIterable be the result of Get(paintCtor, "inputArguments"). ◎ If inputArgumentsIterable is not undefined, then set inputArguments to the result of converting inputArgumentsIterable to a sequence<DOMString>. If an exception is thrown, rethrow the exception and abort all these steps.
7. %入力~引数~list構文~list ~LET 新たな`~list$ ◎ Let inputArgumentSyntaxes be an empty list.

8. %入力~引数~list 内の ~EACH( %~item ) に対し： ◎ For each item in inputArguments perform the following substeps:

   1. %構文解析した構文 ~LET `構文~定義を消費する$( %~item ) ◎ Attempt to consume a syntax definition from item.＼
   2. ~IF［ %構文解析した構文 ~EQ `失敗^i ］ ⇒ ~THROW `TypeError$E ◎ If failure was returned, throw a TypeError and abort all these steps. Otherwise, let parsedSyntax be the returned syntax definition.
   3. %入力~引数~list構文~list に %構文解析した構文 を`付加する$ ◎ Append parsedSyntax to inputArgumentSyntaxes.

9. %塗り~2D描画~文脈~設定群 ~LET `~IDL値に変換する$( `Get$jA( %paintCtor, `contextOptions^l ), `PaintRenderingContext2DSettings$I )（例外投出あり） ◎ Let contextOptionsValue be the result of Get(paintCtor, "contextOptions"). ◎ Let paintRenderingContext2DSettings be the result of converting contextOptionsValue to a PaintRenderingContext2DSettings. If an exception is thrown, rethrow the exception and abort all these steps.

   注記： %塗り~2D描画~文脈~設定群 の `alpha$m を ~F に設定した場合、~textに対する “可視性” の最適化を遂行する（例：塗り画像が不透明なときには、その背後にある画像を塗らない）ことに加え，~anti-aliasすることを~UAに許容する。 ◎ Note: Setting paintRenderingContext2DSettings.alpha is false allows user agents to anti-alias text in addition to performing "visibility" optimizations, e.g. not painting an image behind the paint image as the paint image is opaque.

10. ~IF［ `IsConstructor$jA( %paintCtor ) ~EQ ~F ］ ⇒ ~THROW `TypeError$E ◎ If the result of IsConstructor(paintCtor) is false, throw a TypeError and abort all these steps.
11. %~prototype ~LET `Get$jA( %paintCtor, `prototype^l ) ◎ Let prototype be the result of Get(paintCtor, "prototype").
12. ~IF［ `Type$jA( %~prototype ) ~NEQ `Object^jC ］ ⇒ ~THROW `TypeError$E ◎ If the result of Type(prototype) is not Object, throw a TypeError and abort all these steps.
13. %塗り関数 ~LET `~IDL値に変換する$( `Get$jA( %~prototype, `paint^l ), `Function$I )（例外投出あり） ◎ Let paintValue be the result of Get(prototype, "paint"). ◎ Let paint be the result of converting paintValue to the Function callback function type. Rethrow any exceptions from the conversion.
14. %定義 ~LET 次のようにされた新たな`塗り定義$ ⇒＃ `~class構築子$pD ~SET %paintCtor, `塗り関数$pD ~SET %塗り関数, `構築子は妥当か$pD ~SET ~T, `入力~prop~list$pD ~SET %入力~prop~list, `塗り~2D描画~文脈~設定群$pD ~SET %塗り~2D描画~文脈~設定群 ◎ Let definition be a new paint definition with: • class constructor being paintCtor. • paint function being paint. • constructor valid flag being true. • input properties being inputProperties. • PaintRenderingContext2DSettings object being paintRenderingContext2DSettings.
15. %塗り定義~map[ %name ] ~SET %定義 ◎ Set paintDefinitionMap[name] to definition.

16. 次を走らす`~taskを~queueする$ ◎ Queue a task to run the following steps:

    1. %文書~塗り定義~map ~LET 結付けられた`文書$【！＊】の`文書~塗り定義~map$ ◎ Let documentPaintDefinitionMap be the associated document’s document paint definitions map.
    2. %文書~塗り定義 ~LET 次のようにされた新たな`文書~塗り定義$ ⇒＃ `入力~prop~list$dPD ~SET %入力~prop~list, `入力~引数~構文$dPD ~SET %入力~引数~list構文~list, `塗り~2D描画~文脈~設定群$dPD ~SET %塗り~2D描画~文脈~設定群 ◎ Let documentDefinition be a new document paint definition with: • input properties being inputProperties. • input argument syntaxes being inputArgumentSyntaxes. • PaintRenderingContext2DSettings object being paintRenderingContext2DSettings.

    3. ~IF［ %文書~塗り定義~map[ %name ] ~NEQ ε ］： ◎ If documentPaintDefinitionMap[name] exists, run the following steps:

       1. %既存の文書~塗り定義 ~LET %文書~塗り定義~map[ %name ] ◎ Let existingDocumentDefinition be the result of get documentPaintDefinitionMap[name].

       2. ~IF［ %既存の文書~塗り定義 ~NEQ `invalid^l ］~AND［ ［ %既存の文書~塗り定義, %文書~塗り定義 ］は等価でない（すなわち，［ `入力~prop~list$dPD, `入力~引数~構文$dPD, `塗り~2D描画~文脈~設定群$dPD ］【のいずれか】が異なる) ］： ◎ If existingDocumentDefinition is "invalid", abort all these steps. ◎ If existingDocumentDefinition and documentDefinition are not equivalent, (that is input properties, input argument syntaxes, and PaintRenderingContext2DSettings object are different), then:

          1. %文書~塗り定義~map[ %name ] ~SET `invalid^l ◎ Set documentPaintDefinitionMap[name] to "invalid".
          2. 同じ~classが等価でない`文書~塗り定義$で登録されようとしたことを言明する~errorを，~debug用~consoleに~logする ◎ Log an error to the debugging console stating that the same class was registered with different inputProperties, inputArguments, or paintRenderingContext2DSettings.
    4. ~ELSE ⇒ %文書~塗り定義~map[ %name ] ~SET %文書~塗り定義 ◎ Otherwise, set documentPaintDefinitionMap[name] to documentDefinition.

注記： 入力~prop~listは、一度だけ検索されるベキである — 当の~classが、その入力~prop~listを動的に変更する機会を得ないよう。 ◎ Note: The list of input properties should only be looked up once, the class doesn’t have the opportunity to dynamically change its input properties.

`塗り~2D描画~文脈を作成する@ ときは、所与の ( %~size, %塗り~2D描画~文脈~設定群 ) に対し，次の手続きを走らすモノトスル： ◎ When the user agent is to create a PaintRenderingContext2D object for a given width, height, and paintRenderingContext2DSettings, it must run the following steps:

1. %文脈 ~LET 新たな `PaintRenderingContext2D$I ◎ Create a new PaintRenderingContext2D.
2. %文脈 の`出力~bitmap$用の`~bitmap寸法を設定する$( %~size の横幅, 縦幅を丸めた結果 ) ◎ Set bitmap dimensions for the context’s output bitmap to the rounded values of width and height.
3. `PaintRenderingContext2D$I の`~alpha~flag$ ~SET %塗り~2D描画~文脈~設定群 の `alpha$m ◎ Set the PaintRenderingContext2D's alpha flag to paintRenderingContext2DSettings’s alpha.
4. ~RET %文脈 ◎ Return the new PaintRenderingContext2D.

注記： 描画~文脈の初期~状態は、`~bitmap寸法を設定する$ ~algoの内側で設定され、それに伴い 描画~文脈を`既定の状態に設定し直す$ことに加え，`出力~bitmap$を【`透明な黒$に】~clearする。 ◎ Note: The initial state of the rendering context is set inside the set bitmap dimensions algorithm, as it invokes reset the rendering context to its default state and clears the output bitmap.

~UAは， `塗り関数の画像を描く@ ときは、所与の ( %~box, `その時点の具象-~obj~size$ %具象-~obj~size ) に対し，次の手続きを走らせて生産される画像~出力を［ %~box 用に適切な積層~level（ %~box の~CSS~propにより定義される）の中へ描く ］モノトスル： ◎ When the user agent wants to draw a paint image of a <paint()> function for a box into its appropriate stacking level (as defined by the property the CSS property its associated with), given snappedConcreteObjectSize it must run the following steps:

1. %塗り関数 ~LET %~box 上の `paint$f 関数 ◎ Let paintFunction be the <paint()> function on the box which the user agent wants to draw.
2. %名前 ~LET %塗り関数 の最初の引数 ◎ Let name be the first argument of the paintFunction.
3. %文書~塗り定義~map ~LET 結付けられた`文書$【 %~box が生成される文書】の`文書~塗り定義~map$ ◎ Let documentPaintDefinitionMap be the associated document’s document paint definitions map.
4. ~IF［ %文書~塗り定義~map[ %名前 ] ~EQ ε ］ ⇒＃ 画像~出力は`無効な画像$； ~RET ◎ If documentPaintDefinitionMap[name] does not exist, let the image output be an invalid image and abort all these steps.
5. %文書~塗り定義 ~LET %文書~塗り定義~map[ %名前 ] ◎ Let documentDefinition be the result of get documentPaintDefinitionMap[name].
6. ~IF［ %文書~塗り定義 ~EQ `invalid^l ］ ⇒＃ 画像~出力は`無効な画像$； ~RET ◎ If documentDefinition is "invalid", let the image output be an invalid image and abort all these steps.
7. %入力~引数~list構文~list ~LET %文書~塗り定義 の`入力~引数~構文$dPD ◎ Let inputArgumentSyntaxes be documentDefinition’s input argument syntaxes.
8. %入力~引数~list ~LET %塗り関数 の `declaration-value$t 引数を成す成分たちからなる`~list$ ◎ Let inputArguments be the list of all the paintFunction arguments after the "paint name" argument.

9. ~IF［ %入力~引数~list は %入力~引数~list構文~list に与えられた登録-済み文法に合致しない ］ ⇒＃ 画像~出力は`無効な画像$； ~RET ◎ If inputArguments do not match the registered grammar given by inputArgumentSyntaxes, let the image output be an invalid image and abort all these steps.

   この段は、次の事例では失敗し得る： ◎ This step may fail in the following cases:

   // paint.js
   `registerPaint$m('failing-argument-syntax', class {
       static get inputArguments() { return ['<length>']; }
       paint(%ctx, %size, %styleMap, %args) { /* paint code here. */ }
   });
   

   <style>
       .example-1 {
           background-image: paint(failing-argument-syntax, red);
       }
       .example-2 {
           background-image: paint(failing-argument-syntax, 1px, 2px);
       }
   </style>
   <div class=example-1></div>
   <div class=example-2></div>
   <script>
       CSS.`paintWorklet$m.`addModule$m('paint.js');
   </script>
   

   `example-1^c は`無効な画像$を生産する — `red^l は登録-済み文法に合致しないので。 ◎ example-1 produces an invalid image as "red" does not match the registered grammar.

   `example-2^c は`無効な画像$を生産する — 関数の引数が多過ぎるので。 ◎ example-2 produces an invalid image as there are too many function arguments.

10. %~worklet大域~scope ~LET § 大域~scopeの選定に定義される規則に従って， 塗り `Worklet$I の`大域~scope~list$wLから選んだ `PaintWorkletGlobalScope$I ~obj ◎ Let workletGlobalScope be a PaintWorkletGlobalScope from the paint Worklet's global scopes, following the rules defined in § 7.1 Global Scope Selection.

    ~UAは、この時点で次を行っても`ヨイ^em ⇒ `~worklet大域~scopeを作成する$( 塗り `Worklet$I【！＊】 ) ◎ The user agent may also create a worklet global scope at this time, given the paint Worklet.

11. この段は、任意選択で`並列的$に, または同期的に走らす ⇒ `塗り~callbackを呼出す$( %名前, %入力~引数~list, %具象-~obj~size, %~worklet大域~scope ) ◎ Run invoke a paint callback given name, inputArguments, snappedConcreteObjectSize, workletGlobalScope optionally in parallel.

    注記： `並列的$な~thread内で`塗り~callbackを呼出す$場合、~UAは，その~thread上で利用できる塗り~worklet大域~scopeを選定するベキである。 ◎ Note: If the user agent runs invoke a paint callback on a thread in parallel, it should select a paint worklet global scope which can be used on that thread.

`塗り~callbackを呼出す@ ときは、所与の ( %名前, %入力~引数~list, %具象-~obj~size, %~worklet大域~scope ) に対し，次の手続きを走らすモノトスル： ◎ When the user agent wants to invoke a paint callback given name, inputArguments, snappedConcreteObjectSize, and workletGlobalScope, it must run the following steps:

1. %塗り定義~map ~LET %~worklet大域~scope の`塗り定義~map$ ◎ Let paintDefinitionMap be workletGlobalScope’s paint definitions map.
2. %定義 ~LET %塗り定義~map[ %名前 ] ◎ ↓

3. ~IF［ %定義 ~EQ ε ］： ◎ If paintDefinitionMap[name] does not exist, run the following steps:

   1. 次を走らす`~taskを~queueする$： ◎ Queue a task to run the following steps:

      1. %文書~塗り定義~map ~LET 結付けられた`文書$【！＊】の`文書~塗り定義~map$ ◎ Let documentPaintDefinitionMap be the associated document's document paint definitions map.
      2. %文書~塗り定義~map[ %名前 ] ~SET `invalid^l ◎ Set documentPaintDefinitionMap[name] to "invalid".
      3. ~UAは、~debug用~consoleに次を~logする`ベキ^emである ⇒ どの `PaintWorkletGlobalScope$I にも~classは登録されていないことを言明する~error ◎ The user agent should log an error to the debugging console stating that a class wasn’t registered in all PaintWorkletGlobalScopes.
   2. 画像~出力は`無効な画像$ ◎ Let the image output be an invalid image and＼
   3. ~RET ◎ abort all these steps.

   注記： 塗り~worklet大域~scopeには、 %名前 用の `registerPaint()$m を受取らなかったものもある（しかしながら，受取った大域~scopeもある）かもしれない — これは、そのような事例を取扱う。 他の大域~scope上で呼出された塗り~callbackは成功したとしても、後続な~frameでは，`塗り関数の画像を描く$が~callされても成功しないことになる。 ◎ Note: This handles the case where there could be a paint worklet global scope which didn’t receive the registerPaint(name, paintCtor) for name (however another global scope did). A paint callback which is invoked on the other global scope could succeed, but wont succeed on a subsequent frame when draw a paint image is called.

4. %塗り~class~instance~map ~LET %~worklet大域~scope の`塗り~class~instance~map$pD ◎ ↑Let definition be the result of get paintDefinitionMap[name]. ◎ Let paintClassInstanceMap be workletGlobalScope’s paint class instances map.
5. %塗り~instance ~LET %塗り~class~instance~map[ %名前 ] ◎ Let paintInstance be the result of get paintClassInstanceMap[|name]|.＼

6. ~IF［ %塗り~instance ~EQ ε ］： ◎ If paintInstance is null, run the following steps:

   1. ~IF［ %定義 の`構築子は妥当か$pD ~EQ ~F ］ ⇒＃ 画像~出力は`無効な画像$； ~RET ◎ If the constructor valid flag on definition is false, let the image output be an invalid image and abort all these steps.
   2. %塗り構築子 ~LET %定義 上の`~class構築子$pD ◎ Let paintCtor be the class constructor on definition.
   3. %塗り~instance ~SET `Construct$jA( %塗り構築子 ) ◎ Let paintInstance be the result of Construct(paintCtor).
   4. ~IF［ 前~段にて例外が投出された ］ ⇒＃ %定義 の`構築子は妥当か$pD ~SET ~F； 画像~出力は`無効な画像$； ~RET ◎ If construct throws an exception, set the definition’s constructor valid flag to false, let the image output be an invalid image and abort all these steps.
   5. %塗り~class~instance~map[ %名前 ] ~SET %塗り~instance ◎ Set paintClassInstanceMap[name] to paintInstance.
7. %入力~prop~list ~LET %定義 の`入力~prop~list$pD ◎ Let inputProperties be definition’s input properties.
8. %~style~map ~LET 新たな `StylePropertyMapReadOnly$I ◎ Let styleMap be a new StylePropertyMapReadOnly＼
9. %~style~map の `declarations$sl 内部~slot を［ %入力~prop~list 内に~listされた~prop用の`算出d値$ ］`のみ^emで拡充する ◎ populated with only the computed value's for properties listed in inputProperties.

10. %描画~文脈 ~LET `塗り~2D描画~文脈を作成する$( %具象-~obj~size, %定義 の`塗り~2D描画~文脈~設定群$pD )： ◎ Let renderingContext be the result of create a PaintRenderingContext2D object given: • "width" - The width given by snappedConcreteObjectSize. • "height" - The height given by snappedConcreteObjectSize. • "paintRenderingContext2DSettings" - The PaintRenderingContext2DSettings object given by definition.

    注記： %描画~文脈 は、塗りの各~呼出nの間で再利用されることはない。 これは、各~呼出nの間では %描画~文脈 上に格納-済みな~dataや状態は無いことを暗黙的に意味する。 例えば， %描画~文脈 上で `clip()$m により切抜き領域を設定しておいても、次回に塗り~methodが~callされるとき同じ切抜き領域が適用されることは，期待できない。 ◎ Note: The renderingContext is not be re-used between invocations of paint. Implicitly this means that there is no stored data, or state on the renderingContext between invocations. For example you can’t setup a clip on the context, and expect the same clip to be applied next time the paint method is called.

    注記： これは、［ %描画~文脈 は実質的に塗り~methodが完了した後に “無力化される” ］ことを暗黙的に意味する。 作者~codeは %描画~文脈 への参照を保持して，それに対し~methodを呼出すこともできるが、［ 現在の画像／後続な画像 ］に対する効果は無い。 ◎ Note: Implicitly this also means that renderingContext is effectively "neutered" after a paint method is complete. The author code may hold a reference to renderingContext and invoke methods on it, but this will have no effect on the current image, or subsequent images.

11. %塗り~size ~LET 次のように初期化された新たな `PaintSize$I ~obj ⇒＃ `width$m ~SET %具象-~obj~size の横幅, `height$m ~SET %具象-~obj~size の縦幅 ◎ Let paintSize be a new PaintSize initialized to the width and height defined by snappedConcreteObjectSize.

12. ~UAは、この段階で以前の呼出nからの画像を再利用してもヨイ — ［ %塗り~size, %~style~map, %入力~引数~list ］は以前の呼出nに等価であるならば — その場合 ⇒＃ 画像~出力はその~cache済み画像； ~RET ◎ At this stage the user agent may re-use an image from a previous invocation if paintSize, styleMap, inputArguments are equivalent to that previous invocation. If so let the image output be that cached image and abort all these steps.

    下の例では， `div-1^css, `div-2^css の両者とも等価な~JS引数~listをとる塗り関数を持つ。 ~UAは、ある回の呼出nの結果を~cacheして，それを両~要素~用に利用できる。 ◎ In the example below, both div-1 and div-2 have paint functions which have equivalent javascript arguments. A user-agent can cache the result of one invocation and use it for both elements.

    // paint.js
    `registerPaint$m('simple', class {
        paint(%ctx, %size) {
            %ctx.fillStyle = 'green';
            %ctx.fillRect(0, 0, %size.width, %size.height);
        }
    });
    

    <style>
        .div-1 {
            width: 50px;
            height: 50px;
            background-image: paint(simple);
        }
        .div-2 {
            width: 100px;
            height: 100px;
    
            background-size: 50% 50%;
            background-image: paint(simple);
        }
    </style>
    <div class=div-1></div>
    <div class=div-2></div>
    <script>
        CSS.`paintWorklet$m.`addModule$m('paint.js');
    </script>
    

13. %塗り関数~callback ~LET %定義 の`塗り関数$pD ◎ Let paintFunctionCallback be definition’s paint function.

14. `~callback関数を呼出す$( %塗り関数~callback, 次に与える~list, %塗り~instance ) ⇒ « %描画~文脈, %塗り~size, %~style~map, %入力~引数~list » ◎ Invoke paintFunctionCallback with arguments «renderingContext, paintSize, styleMap, inputArguments», and with paintInstance as the callback this value.

    • ~IF［ %塗り関数~callback は （~UAが決定する）受容-可能な時間~内に完了しなかった（すなわち， “~scriptは長い間~走っている”） ］ ⇒＃ ~UAは~scriptを終了しても`ヨイ^em； 画像~出力は`無効な画像$； ~RET ◎ If paintFunctionCallback does not complete within an acceptable time (as determined by the user agent, i.e. it is a "long running script") the user agent may terminate the script, let the image output be an invalid image, and abort all these steps.

      注記： ~UAは、自身の~debug用~toolの中で，それらの塗り~classがどう高価か作者に示す~~仕掛けを供することもできる。 この事例では，~UAは、適切になるならば， “~scriptは応答-不能である” 様子を~dialogに示すこともできる。 ◎ Note: User agents could provide tooling within their debugging tools to show authors how expensive their paint classes are. User agents could also how an "unresponsive script" dialog in this case if appropriate.

    • ~IF［ %塗り関数~callback から例外が投出された ］ ⇒＃ 画像~出力は`無効な画像$； ~RET ◎ ↓
15. 画像~出力は前~段により %描画~文脈 から生産されたそれ ◎ The image output is to be produced from the renderingContext given to the method. ◎ If an exception is thrown the let the image output be an invalid image.

注記： 結果の画像の内容は、~access可能になるものと設計されていない。 作者は、有用な情報があれば，標準な~accessibility~APIを通して通信できる。 ◎ Note: The contents of the resulting image are not designed to be accessible. Authors can communicate any useful information through the standard accessibility APIs.