Rename colorspace() to vertexColorSpace()

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';

packages/functions/src/colorspace.ts → 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;
 		}

packages/functions/test/colorspace.test.ts → 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;