Adds Watch Face Format (WFF) v2 specification (#17)

* Adds v2 specification * Update links
google · May 15, 2024 · 8457239 · 8457239
1 parent fb6fbda
commit 8457239
Show file tree

Hide file tree

Showing 96 changed files with 4,977 additions and 8 deletions.
diff --git a/README.md b/README.md
@@ -11,6 +11,11 @@ Face Format to build both watch faces and watch face design tools.
 The [XSD specification][xsd-specs] provides you with the specification needed in
 order to build validation into your watch face creation tools and processes.
 
+There are different versions of the specification: The latest is version 2 which
+builds and expands on version 1. Different versions have different Wear OS
+version support. To understand the differences in capabilities and compatibility
+please [see this guide][wff-features].
+
 ## XSD Validator
 
 The [XSD validator][xsd-validator] is a tool that allows you to check whether
@@ -42,4 +47,5 @@ Watch Face Format is distributed under the Apache 2.0 license, see the
 [wff]: https://developer.android.com/training/wearables/wff/
 [samples]: https://github.com/android/wear-os-samples/tree/main/WatchFaceFormat
 [xsd-specs]: third_party/wff/specification/documents/1/
-[xsd-validator]: third_party/wff/README.md
+[xsd-validator]: third_party/wff/README.md
+[wff-features]: https://developer.android.com/training/wearables/wff/features
diff --git a/play-validations/README.md b/play-validations/README.md
@@ -39,7 +39,7 @@ in Google Play reviews, but these represent reasonable settings for evaluation:
 
 ```shell
 java -jar ./memory-footprint.jar --watch-face MyWatchFace.apk \
-  --schema-version 1 \
+  --schema-version 2 \
   --ambient-limit-mb 10 \
   --active-limit-mb 100 \
   --apply-v1-offload-limitations \

diff --git a/third_party/wff/README.md b/third_party/wff/README.md
@@ -6,6 +6,10 @@ The watch face format specifcation allows you to validate your watch faces and
 operation of watch face generating tools. The specification is  
 [provided as XSD files][xsd-files].
 
+There are different versions of the specification, which have different
+capabilities and compatibilities. Please see [this guide][wff-features] for more
+details.
+
 ## Format validator
 
 In addition to the XSD files, a validator is provided that can be used to check
@@ -18,20 +22,21 @@ cd third_party/wff
 ./gradlew :specification:validator:build
 ```
 
-The resulting JAR file can then be found at: `specification/validator/build/libs/dwf-format-1-validator-1.0.jar`
+The resulting JAR file can then be found at: `specification/validator/build/libs/dwf-format-2-validator-1.0.jar`
 
 ### Usage
 
 To check whether a watch face is valid, invoke the validator as follows:
 
 ```shell
-java -jar dwf-format-1-validator-1.0.jar <format-version> <any options> <your-watchface.xml> <more-watchface.xml>
+java -jar dwf-format-2-validator-1.0.jar <format-version> <any options> <your-watchface.xml> <more-watchface.xml>
 ```
 
 For example:
 
 ```shell
-java -jar dwf-format-1-validator-1.0.jar 1 ~/MyWatchface/res/raw/watchface.xml
+java -jar dwf-format-2-validator-1.0.jar 2 ~/MyWatchface/res/raw/watchface.xml
 ```
 
-[xsd-files]: specification/documents/1
+[xsd-files]: specification/documents/1
+[wff-features]: https://developer.android.com/training/wearables/wff/features
diff --git a/third_party/wff/specification/documents/2/bitmapFontsElement.xsd b/third_party/wff/specification/documents/2/bitmapFontsElement.xsd
@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2023 Samsung Electronics Co., Ltd All Rights Reserved
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+  <xs:include schemaLocation="common/attributes/geometricAttributes.xsd"/>
+
+  <xs:complexType name="_bitmapImportDataType">
+    <xs:attribute name="name" type="xs:string" use="required"/>
+    <xs:attribute name="resource" type="xs:string" use="required"/>
+    <xs:attributeGroup ref="sizeAttributesRequired"/>
+    <xs:attributeGroup ref="margins"/>
+  </xs:complexType>
+
+  <xs:element name="BitmapFonts">
+    <xs:complexType>
+      <xs:annotation>
+        <xs:documentation>
+          User-defined bitmap fonts can be declared in this scope.
+        </xs:documentation>
+      </xs:annotation>
+
+      <xs:choice maxOccurs="unbounded">
+        <xs:element name="BitmapFont" minOccurs="1" maxOccurs="unbounded">
+          <xs:complexType>
+            <xs:annotation>
+              <xs:documentation>
+                User-defined bitmap font can be declared with this element.
+                Put the name for the family attribute in the font element.
+              </xs:documentation>
+            </xs:annotation>
+
+            <xs:choice minOccurs="1" maxOccurs="unbounded">
+              <xs:choice>
+                <xs:element name="Character" type="_bitmapImportDataType"/>
+                <xs:element name="Word" type="_bitmapImportDataType"/>
+              </xs:choice>
+            </xs:choice>
+
+            <xs:attribute name="name" type="xs:string" use="required"/>
+          </xs:complexType>
+
+          <xs:unique name="Validation.Unique.BitmapFont.Child.Name">
+            <xs:selector xpath="*"/>
+            <xs:field xpath="@name"/>
+          </xs:unique>
+        </xs:element>
+      </xs:choice>
+    </xs:complexType>
+  </xs:element>
+</xs:schema>
diff --git a/third_party/wff/specification/documents/2/clock/analogClock.xsd b/third_party/wff/specification/documents/2/clock/analogClock.xsd
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2023 Samsung Electronics Co., Ltd All Rights Reserved
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+  <xs:include schemaLocation="../group/renderModeType.xsd"/>
+  <xs:include schemaLocation="../common/attributes/geometricAttributes.xsd"/>
+  <xs:include schemaLocation="../common/transform/pivotType.xsd"/>
+  <xs:include schemaLocation="../common/variant/variantElements.xsd" />
+  <xs:include schemaLocation="hourHand.xsd"/>
+  <xs:include schemaLocation="minuteHand.xsd"/>
+  <xs:include schemaLocation="secondHand.xsd"/>
+
+  <xs:element name="AnalogClock">
+    <xs:annotation>
+      <xs:documentation>
+        AnalogClock is a container that represents a traditional clock with
+        rotating hands.
+      </xs:documentation>
+    </xs:annotation>
+    <xs:complexType>
+      <xs:all>
+        <xs:element ref="HourHand" minOccurs="0" maxOccurs="2"/>
+        <xs:element ref="MinuteHand" minOccurs="0" maxOccurs="2"/>
+        <xs:element ref="SecondHand" minOccurs="0" maxOccurs="2"/>
+        <xs:element ref="Localization" minOccurs="0" maxOccurs="1"/>
+        <xs:element ref="Variant" minOccurs="0" maxOccurs="unbounded"/>
+      </xs:all>
+
+      <xs:attributeGroup ref="geometricAttributesRequired"/>
+      <xs:attributeGroup ref="pivot2D"/>
+      <xs:attribute name="angle" type="angleType"/>
+      <xs:attribute ref="alpha"/>
+      <xs:attribute name="scaleX" type='xs:float'/>
+      <xs:attribute name="scaleY" type='xs:float'/>
+      <xs:attribute name="renderMode" type="renderModeType" default="SOURCE"/>
+      <xs:attribute name="tintColor" type='colorAttributeType'/>
+    </xs:complexType>
+  </xs:element>
+</xs:schema>
diff --git a/third_party/wff/specification/documents/2/clock/digitalClock.xsd b/third_party/wff/specification/documents/2/clock/digitalClock.xsd
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2023 Samsung Electronics Co., Ltd All Rights Reserved
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+  <xs:include schemaLocation="../group/renderModeType.xsd"/>
+  <xs:include schemaLocation="../common/attributes/geometricAttributes.xsd"/>
+  <xs:include schemaLocation="../common/transform/pivotType.xsd"/>
+  <xs:include schemaLocation="../userConfiguration/listConfigurationElement.xsd"/>
+  <xs:include schemaLocation="../common/variant/variantElements.xsd" />
+  <xs:include schemaLocation="timeText.xsd"/>
+
+  <xs:element name="DigitalClock">
+    <xs:annotation>
+      <xs:documentation>
+        DigitalClock is a container for text-based formatted time.
+      </xs:documentation>
+    </xs:annotation>
+    <xs:complexType>
+      <xs:all>
+        <xs:element ref="Localization" minOccurs="0" maxOccurs="1"/>
+        <xs:element ref="Variant" minOccurs="0" maxOccurs="unbounded"/>
+        <xs:element ref="TimeText" minOccurs="1" maxOccurs="unbounded"/>
+      </xs:all>
+
+      <xs:attributeGroup ref="geometricAttributesRequired"/>
+      <xs:attributeGroup ref="pivot2D"/>
+      <xs:attribute name="angle" type="angleType"/>
+      <xs:attribute ref="alpha"/>
+      <xs:attribute name="scaleX" type='xs:float'/>
+      <xs:attribute name="scaleY" type='xs:float'/>
+      <xs:attribute name="renderMode" type="renderModeType" default="SOURCE"/>
+      <xs:attribute name="tintColor" type='colorAttributeType'/>
+    </xs:complexType>
+  </xs:element>
+</xs:schema>
diff --git a/third_party/wff/specification/documents/2/clock/hourHand.xsd b/third_party/wff/specification/documents/2/clock/hourHand.xsd
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2023 Samsung Electronics Co., Ltd All Rights Reserved
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+  <xs:include schemaLocation="../common/attributes/geometricAttributes.xsd"/>
+  <xs:include schemaLocation="../common/transform/pivotType.xsd"/>
+  <xs:include schemaLocation="../userConfiguration/listConfigurationElement.xsd"/>
+  <xs:include schemaLocation="../common/variant/variantElements.xsd" />
+
+  <xs:element name="HourHand">
+    <xs:annotation>
+      <xs:documentation>
+        A image that represents an hour hand, it rotates 360 degree in 12 hours.
+      </xs:documentation>
+    </xs:annotation>
+    <xs:complexType>
+      <xs:choice maxOccurs="unbounded">
+        <xs:element ref="Variant" minOccurs="0" maxOccurs="unbounded"/>
+      </xs:choice>
+
+      <xs:attribute name="resource" type="xs:string" use="required"/>
+      <xs:attributeGroup ref="geometricAttributesRequired"/>
+      <xs:attributeGroup ref="pivot2D"/>
+      <xs:attribute ref="alpha"/>
+      <xs:attribute name="tintColor" type='colorAttributeType'/>
+    </xs:complexType>
+  </xs:element>
+</xs:schema>
diff --git a/third_party/wff/specification/documents/2/clock/minuteHand.xsd b/third_party/wff/specification/documents/2/clock/minuteHand.xsd
@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2023 Samsung Electronics Co., Ltd All Rights Reserved
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+  <xs:include schemaLocation="../common/attributes/geometricAttributes.xsd"/>
+  <xs:include schemaLocation="../common/transform/pivotType.xsd"/>
+  <xs:include schemaLocation="../userConfiguration/listConfigurationElement.xsd"/>
+  <xs:include schemaLocation="../common/variant/variantElements.xsd" />
+
+  <xs:element name="MinuteHand">
+    <xs:annotation>
+      <xs:documentation>
+        A image that represent a minute hand, it rotates 360 degree in 1 hour.
+      </xs:documentation>
+    </xs:annotation>
+    <xs:complexType>
+      <xs:choice maxOccurs="unbounded">
+        <xs:element ref="Variant" minOccurs="0" maxOccurs="unbounded"/>
+      </xs:choice>
+
+      <xs:attribute name="resource" type="xs:string" use="required"/>
+      <xs:attributeGroup ref="geometricAttributesRequired"/>
+      <xs:attributeGroup ref="pivot2D"/>
+      <xs:attribute ref="alpha"/>
+      <xs:attribute name="tintColor" type='colorAttributeType'/>
+    </xs:complexType>
+  </xs:element>
+</xs:schema>