From 61da8e4720134faabbe0b70b94591e3c809ac12d Mon Sep 17 00:00:00 2001
From: Egor Larionov <egor.larionov@gmail.com>
Date: Sun, 1 Oct 2017 14:23:07 -0700
Subject: [PATCH] Update README to describe the new swizzling feature

---
 README.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/README.md b/README.md
index 833c03e..d5f8b8e 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,32 @@ vectors"), meaning when transforming a vector with a matrix, the matrix goes
 on the left. This is reflected in the fact that cgmath implements the
 multiplication operator for Matrix * Vector, but not Vector * Matrix.
 
+## Features
+
+### Swizzling
+This library offers an optional feature called
+["swizzling"](https://en.wikipedia.org/wiki/Swizzling_(computer_graphics))
+widely familiar to GPU programmers. To enable swizzle operators, pass the
+`--features="swizzle"` option to cargo. Enabling this feature will increase
+the size of the cgmath library by approximately 0.6MB. This isn't an
+issue if the library is linked in the "normal" way by adding cgmath as a
+dependency in Cargo.toml, which will link cgmath statically so all unused
+swizzle operators will be optimized away by the compiler in release mode.
+
+#### Example
+If we have
+```rust
+let v = Vector3::new(1.0, 2.0, 3.0);
+```
+then `v.xyxz()` produces a
+```rust
+Vector4 { x: 1.0, y: 2.0, z: 1.0, w: 3.0 }
+```
+and `v.zy()` produces a
+```rust
+Vector2 { x: 3.0, y: 2.0 }
+```
+
 ## Limitations
 
 cgmath is _not_ an n-dimensional library and is aimed at computer graphics