From fa068b0d1bd2212e816b36c8639d4b508a285db4 Mon Sep 17 00:00:00 2001
From: Don McCurdy <dm@donmccurdy.com>
Date: Mon, 3 Apr 2023 21:56:10 -0400
Subject: [PATCH] [functions] Rename colorspace() to vertexColorSpace()

---
 packages/functions/src/index.ts               |  2 +-
 .../{colorspace.ts => vertex-color-space.ts}  | 43 +++++++++++++------
 ...ace.test.ts => vertex-color-space.test.ts} |  4 +-
 3 files changed, 33 insertions(+), 16 deletions(-)
 rename packages/functions/src/{colorspace.ts => vertex-color-space.ts} (50%)
 rename packages/functions/test/{colorspace.test.ts => vertex-color-space.test.ts} (94%)

diff --git a/packages/functions/src/index.ts b/packages/functions/src/index.ts
index 2b825653f..80212bf80 100644
--- a/packages/functions/src/index.ts
+++ b/packages/functions/src/index.ts
@@ -53,7 +53,6 @@
 export * from './center.js';
 export * from './clear-node-parent.js';
 export * from './clear-node-transform.js';
-export * from './colorspace.js';
 export * from './dedup.js';
 export * from './dequantize.js';
 export * from './draco.js';
@@ -88,4 +87,5 @@ export * from './unlit.js';
 export * from './unpartition.js';
 export { getGLPrimitiveCount, isTransformPending, createTransform } from './utils.js';
 export * from './unweld.js';
+export * from './vertex-color-space.js';
 export * from './weld.js';
diff --git a/packages/functions/src/colorspace.ts b/packages/functions/src/vertex-color-space.ts
similarity index 50%
rename from packages/functions/src/colorspace.ts
rename to packages/functions/src/vertex-color-space.ts
index 368e39dc3..979cf79d1 100644
--- a/packages/functions/src/colorspace.ts
+++ b/packages/functions/src/vertex-color-space.ts
@@ -1,32 +1,49 @@
 import type { Accessor, Document, Primitive, Transform, vec3 } from '@gltf-transform/core';
 import { createTransform } from './utils.js';
 
-const NAME = 'colorspace';
+const NAME = 'vertexColorSpace';
 
-/** Options for the {@link colorspace} function. */
-export interface ColorspaceOptions {
-	/** Must be `"sRGB"`. Required. */
-	inputEncoding: string;
+/** Options for the {@link vertexColorSpace} function. */
+export interface ColorSpaceOptions {
+	/** Input color space of vertex colors, to be converted to "srgb-linear". Required. */
+	inputColorSpace: 'srgb' | 'srgb-linear' | 'sRGB';
+	/** @deprecated Renamed to 'colorSpace'. */
+	inputEncoding?: 'srgb' | 'srgb-linear' | 'sRGB';
 }
 
+/** @deprecated Renamed to {@link vertexColorSpace}. */
+export const colorspace = vertexColorSpace;
+
 /**
- * Vertex color colorspace correction. The glTF format requires vertex colors to be stored
- * as linear values, and this function provides a way to correct vertex colors that are
- * (incorrectly) sRGB.
+ * Vertex color color space correction. The glTF format requires vertex colors to be stored
+ * in Linear Rec. 709 D65 color space, and this function provides a way to correct vertex
+ * colors that are (incorrectly) stored in sRGB.
+ *
+ * Example:
+ *
+ * ```typescript
+ * import { vertexColorSpace } from '@gltf-transform/functions';
+ *
+ * await document.transform(
+ *   vertexColorspace({ inputColorSpace: 'srgb' })
+ * );
+ * ```
  */
-export function colorspace(options: ColorspaceOptions): Transform {
+export function vertexColorSpace(options: ColorSpaceOptions): Transform {
 	return createTransform(NAME, (doc: Document): void => {
 		const logger = doc.getLogger();
 
-		if (options.inputEncoding === 'linear') {
+		const inputColorSpace = (options.inputColorSpace || options.inputEncoding || '').toLowerCase();
+
+		if (inputColorSpace === 'srgb-linear') {
 			logger.info(`${NAME}: Vertex colors already linear. Skipping conversion.`);
 			return;
 		}
 
-		if (options.inputEncoding !== 'sRGB') {
+		if (inputColorSpace !== 'srgb') {
 			logger.error(
-				`${NAME}: Unknown input encoding "${options.inputEncoding}" – should be "sRGB" or ` +
-					'"linear". Skipping conversion.'
+				`${NAME}: Unknown input color space "${inputColorSpace}" – should be "srgb" or ` +
+					'"srgb-linear". Skipping conversion.'
 			);
 			return;
 		}
diff --git a/packages/functions/test/colorspace.test.ts b/packages/functions/test/vertex-color-space.test.ts
similarity index 94%
rename from packages/functions/test/colorspace.test.ts
rename to packages/functions/test/vertex-color-space.test.ts
index 53c993de9..3399917b4 100644
--- a/packages/functions/test/colorspace.test.ts
+++ b/packages/functions/test/vertex-color-space.test.ts
@@ -1,6 +1,6 @@
 import test from 'ava';
 import { Accessor, Document } from '@gltf-transform/core';
-import { colorspace } from '@gltf-transform/functions';
+import { vertexColorSpace } from '@gltf-transform/functions';
 
 test('basic', (t) => {
 	const input = [0.25882352941176473, 0.5215686274509804, 0.9568627450980393]; // sRGB
@@ -22,7 +22,7 @@ test('basic', (t) => {
 	primitive1.setAttribute('COLOR_0', accessor1).setAttribute('COLOR_1', accessor2);
 	primitive2.setAttribute('COLOR_0', accessor1);
 
-	colorspace({ inputEncoding: 'sRGB' })(doc);
+	vertexColorSpace({ inputColorSpace: 'srgb' })(doc);
 
 	let actual;