CSS 페인팅 API 레벨 1

1. name이 빈 문자열이면, throw TypeError를 발생시키고 모든 단계를 중단합니다.

2. paintDefinitionMap을 PaintWorkletGlobalScope의 페인트 정의 map으로 설정합니다.

3. paintDefinitionMap[name] 존재하면, throw "InvalidModificationError" DOMException 을 발생시키고 모든 단계를 중단합니다.

4. inputProperties를 빈 sequence<DOMString>으로 설정합니다.

5. inputPropertiesIterable을 Get(paintCtor, "inputProperties")의 결과로 설정합니다.

6. inputPropertiesIterable이 undefined가 아니면, inputProperties를 변환 결과로 설정합니다. inputPropertiesIterable을 sequence<DOMString>으로 변환합니다. 예외가 발생하면 예외를 다시 발생시키고 모든 단계를 중단합니다.

7. inputProperties를 지원되는 CSS 속성과 커스텀 속성만 포함하도록 필터링합니다.

참고: input properties getter로 제공되는 CSS 속성 목록은 커스텀 또는 기본 CSS 속성 모두 가능합니다.

참고: CSS 속성 목록에는 shorthand가 포함될 수 있습니다.

참고: paint 이미지 클래스가 미래 호환성을 위해, CSS 속성 목록은 현재 사용자 에이전트에 유효하지 않은 속성도 포함할 수 있습니다. 예시: margin-bikeshed-property.

8. inputArguments를 빈 sequence<DOMString>으로 설정합니다.

9. inputArgumentsIterable을 Get(paintCtor, "inputArguments")의 결과로 설정합니다.

10. inputArgumentsIterable이 undefined가 아니면, inputArguments를 변환 결과로 설정합니다. inputArgumentsIterable을 sequence<DOMString>으로 변환합니다. 예외가 발생하면 예외를 다시 발생시키고 모든 단계를 중단합니다.

11. inputArgumentSyntaxes를 빈 리스트로 설정합니다.

12. inputArguments의 각 item에 대해 다음 하위 단계를 수행합니다:

    1. consume a syntax definition을 item에서 시도합니다. 실패하면 throw TypeError를 발생시키고 모든 단계를 중단합니다. 성공하면 parsedSyntax를 반환된 syntax definition으로 설정합니다.

    2. parsedSyntax를 inputArgumentSyntaxes에 추가합니다.

13. contextOptionsValue를 Get(paintCtor, "contextOptions")의 결과로 설정합니다.

14. paintRenderingContext2DSettings를 변환 결과로 설정합니다. contextOptionsValue를 PaintRenderingContext2DSettings로 변환합니다. 예외가 발생하면 예외를 다시 발생시키고 모든 단계를 중단합니다.

    참고: paintRenderingContext2DSettings.alpha를 false로 설정하면 사용자 에이전트가 텍스트를 안티앨리어싱하는 것 외에도 "visibility" 최적화(예: paint 이미지가 불투명할 때 paint 이미지 뒤의 이미지를 그리지 않음)를 수행할 수 있습니다.

15. IsConstructor(paintCtor)의 결과가 false이면, throw TypeError를 발생시키고 모든 단계를 중단합니다.

16. prototype을 Get(paintCtor, "prototype")의 결과로 설정합니다.

17. Type(prototype)의 결과가 Object가 아니면, throw TypeError를 발생시키고 모든 단계를 중단합니다.

18. paintValue를 Get(prototype, "paint")의 결과로 설정합니다.

19. paint를 변환 결과로 설정합니다. paintValue를 Function 콜백 함수 타입으로 변환합니다. 변환 중 발생하는 예외는 다시 발생시킵니다.

20. definition을 새로운 페인트 정의로 생성하며, 다음과 같이 구성됩니다:

    • 클래스 생성자: paintCtor

    • paint 함수: paint

    • 생성자 유효 플래그: true

    • 입력 속성: inputProperties

    • PaintRenderingContext2DSettings 객체: paintRenderingContext2DSettings

21. paintDefinitionMap[name]을 definition으로 설정합니다.

22. 테스크를 큐에 추가하여 다음 단계를 실행합니다:

    1. documentPaintDefinitionMap을 연결된 문서의 문서 페인트 정의 map으로 설정합니다.

    2. documentDefinition을 새로운 문서 페인트 정의로 생성하며, 다음과 같이 구성됩니다:

       • 입력 속성: inputProperties

       • 입력 인자 문법: inputArgumentSyntaxes

       • PaintRenderingContext2DSettings 객체: paintRenderingContext2DSettings

    3. documentPaintDefinitionMap[name] 존재하면, 다음 단계를 실행합니다:

       1. existingDocumentDefinition을 get documentPaintDefinitionMap[name]의 결과로 설정합니다.

       2. existingDocumentDefinition이 "invalid"이면 모든 단계를 중단합니다.

       3. existingDocumentDefinition과 documentDefinition이 동등하지 않으면 (입력 속성, 입력 인자 문법, PaintRenderingContext2DSettings 객체가 다르면), 다음을 실행합니다:

          documentPaintDefinitionMap[name]을 "invalid"로 설정합니다.

          동일한 클래스가 다른 inputProperties, inputArguments, paintRenderingContext2DSettings와 함께 등록되었다는 오류를 디버깅 콘솔에 기록합니다.

    4. 그렇지 않으면 documentPaintDefinitionMap[name]을 documentDefinition으로 설정합니다.

참고: 입력 속성 목록은 반드시 한 번만 조회되어야 하며, 클래스는 입력 속성을 동적으로 변경할 기회가 없습니다.

참고: 향후 명세 버전에서는 저자가 다른 타입의 RenderingContext를 받을 수 있는 기능이 추가될 수 있습니다. 저자가 3D 효과를 렌더링하기 위해 WebGL 렌더링 컨텍스트를 원할 수도 있습니다. WebGL 렌더링 컨텍스트를 PaintSize와 StylePropertyMap을 입력으로 받도록 설정하는 데는 복잡성이 있습니다.

1. 새 PaintRenderingContext2D를 생성합니다.

2. 컨텍스트의 출력 비트맵에 대해 비트맵 크기 설정을 width와 height의 반올림 값으로 합니다.

3. PaintRenderingContext2D의 alpha 플래그를 paintRenderingContext2DSettings의 alpha 값으로 설정합니다.

4. 새 PaintRenderingContext2D를 반환합니다.

참고: 렌더링 컨텍스트의 초기 상태는 비트맵 크기 설정 알고리즘에서 설정되며, 여기서 렌더링 컨텍스트를 초기 상태로 리셋하고 출력 비트맵을 지웁니다.

1. paintFunction을 그리려는 box의 <paint()> 함수로 설정합니다.

2. name을 paintFunction의 첫 번째 인자로 설정합니다.

3. documentPaintDefinitionMap을 연결된 문서의 문서 페인트 정의 map으로 설정합니다.

4. documentPaintDefinitionMap[name]이 존재하지 않으면, 이미지 출력은 잘못된 이미지로 하고, 모든 단계를 중단합니다.

5. documentDefinition을 get documentPaintDefinitionMap[name]의 결과로 설정합니다.

6. documentDefinition이 "invalid"이면, 이미지 출력을 잘못된 이미지로 하고, 모든 단계를 중단합니다.

7. inputArgumentSyntaxes를 documentDefinition의 입력 인자 문법으로 설정합니다.

8. inputArguments를 리스트로, "paint name" 인자 이후의 paintFunction의 모든 인자로 설정합니다.

9. inputArguments가 등록된 문법 inputArgumentSyntaxes와 일치하지 않으면, 이미지 출력을 잘못된 이미지로 하고, 모든 단계를 중단합니다.

   이 단계는 다음과 같은 경우 실패할 수 있습니다:

   // paint.js
   registerPaint('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.addModule('paint.js');
   </script>
   

   example-1은 "red"가 등록된 문법과 일치하지 않으므로 잘못된 이미지가 생성됩니다.

   example-2는 함수 인자가 너무 많으므로 잘못된 이미지가 생성됩니다.

10. workletGlobalScope를 PaintWorkletGlobalScope 중 하나로 설정합니다. (글로벌 스코프 선택 규칙은 § 7.1 글로벌 스코프 선택 참조)

    사용자 에이전트는 이 시점에 페인트 Worklet이 주어지면 임의로 워크렛 글로벌 스코프를 생성할 수도 있다.

11. invoke a paint callback을 name, inputArguments, snappedConcreteObjectSize, workletGlobalScope로 실행합니다. 선택적으로 병렬로 실행할 수 있습니다.

    참고: 만약 사용자 에이전트가 invoke a paint callback을 별도 스레드에서 병렬로 실행할 경우, 해당 스레드에서 사용할 수 있는 페인트 워클릿 글로벌 스코프를 선택해야 합니다.

1. paintDefinitionMap을 workletGlobalScope의 페인트 정의 map으로 설정합니다.

2. paintDefinitionMap[name]이 존재하지 않으면, 다음 단계를 실행합니다:

   1. 테스크를 큐에 추가하여 다음 단계를 실행합니다:

      1. documentPaintDefinitionMap을 연결된 문서의 문서 페인트 정의 map으로 설정합니다.

      2. documentPaintDefinitionMap[name]을 "invalid"로 설정합니다.

      3. 사용자 에이전트는 PaintWorkletGlobalScope에 클래스가 등록되지 않았음을 디버깅 콘솔에 오류로 표시해야 합니다.

   2. 이미지 출력을 잘못된 이미지로 하고, 모든 단계를 중단합니다.

   참고: 이 단계는 어떤 페인트 워클릿 글로벌 스코프가 registerPaint(name, paintCtor)를 받지 못한 경우를 처리합니다(다른 글로벌 스코프는 받았을 수 있음). 다른 글로벌 스코프에서 호출된 페인트 콜백은 성공할 수 있지만, 다음 프레임의 draw a paint image 호출에서는 성공하지 않을 수 있습니다.

3. definition을 get paintDefinitionMap[name]의 결과로 설정합니다.

4. paintClassInstanceMap을 workletGlobalScope의 페인트 클래스 인스턴스 map으로 설정합니다.

5. paintInstance를 get paintClassInstanceMap[|name|]의 결과로 설정합니다. paintInstance가 null이면, 다음 단계를 실행합니다:

   1. definition의 생성자 유효 플래그가 false이면, 이미지 출력을 잘못된 이미지로 하고, 모든 단계를 중단합니다.

   2. paintCtor를 definition의 클래스 생성자로 설정합니다.

   3. paintInstance를 Construct(paintCtor)의 결과로 설정합니다.

      construct가 예외를 발생시키면, definition의 생성자 유효 플래그를 false로 설정하고, 이미지 출력을 잘못된 이미지로 하고, 모든 단계를 중단합니다.

   4. paintClassInstanceMap[name]을 paintInstance로 설정합니다.

6. inputProperties를 definition의 입력 속성으로 설정합니다.

7. styleMap을 StylePropertyMapReadOnly로 새로 생성하여, inputProperties에 나열된 속성들의 계산된 값만 포함시킵니다.

8. renderingContext를 create a PaintRenderingContext2D object로 생성합니다:

   • "width" - snappedConcreteObjectSize가 제공한 너비

   • "height" - snappedConcreteObjectSize가 제공한 높이

   • "paintRenderingContext2DSettings" - definition이 제공한 PaintRenderingContext2DSettings 객체

   참고: renderingContext는 paint 호출 간에 재사용되지 않습니다. 암묵적으로 renderingContext에는 저장된 데이터나 상태가 없습니다. 예를 들어 컨텍스트에 clip을 설정하고 다음 호출 때 같은 clip 적용을 기대할 수 없습니다.

   참고: 암묵적으로 이는 paint 메서드가 끝나면 renderingContext가 사실상 "무효화"됨을 의미합니다. 저자 코드가 renderingContext 참조를 유지하고 메서드를 호출해도, 현재 이미지나 이후 이미지에 아무런 영향이 없습니다.

9. paintSize를 PaintSize로 새로 생성하고, snappedConcreteObjectSize가 정의한 너비와 높이로 초기화합니다.

10. 이 단계에서는 paintSize, styleMap, inputArguments가 이전 호출과 동일하다면, 이전 호출의 이미지를 재사용할 수 있습니다. 이 경우, 이미지 출력을 캐시된 이미지로 하고 모든 단계를 중단합니다.

    아래 예제에서 div-1과 div-2 모두 자바스크립트 인자가 동일한 paint 함수를 사용합니다. 사용자 에이전트는 한 번의 호출 결과를 캐시해 두 요소에 모두 사용할 수 있습니다.

    // paint.js
    registerPaint('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.addModule('paint.js');
    </script>
    

11. paintFunctionCallback을 definition의 paint 함수로 설정합니다.

12. Invoke paintFunctionCallback을 인자 «renderingContext, paintSize, styleMap, inputArguments»로 호출하며, paintInstance를 콜백 this 값으로 사용합니다.

    paintFunctionCallback이 허용 가능한 시간 내에 완료되지 않으면(사용자 에이전트가 판단, 즉 "장시간 실행되는 스크립트") 사용자 에이전트는 스크립트를 종료하고, 이미지 출력을 잘못된 이미지로 하고, 모든 단계를 중단할 수 있습니다.

    참고: 사용자 에이전트는 디버깅 도구 내에서 저자가 페인트 클래스를 얼마나 비용이 많이 드는지 보여주는 툴을 제공할 수 있습니다. 또한 "응답 없음 스크립트" 대화상자를 보여줄 수도 있습니다.

13. 이미지 출력은 메서드에 전달된 renderingContext에서 생성됩니다.

    예외가 발생하면 이미지 출력을 잘못된 이미지로 합니다.

참고: 결과 이미지의 내용은 접근성을 고려하여 설계되지 않았습니다. 저자는 표준 접근성 API를 통해 필요한 정보를 전달할 수 있습니다.