Adding Support for Newtyping

[Radbuglet]

Users will oftentimes have various coordinate systems in their applications and many would like to enforce certain additional usage semantics on logically distinct vector types at compile time. To address this problem, we could expose a simple macro to generate a new type and provide some mechanism for defining implicit conversions between several vector newtypes. In doing so, users could benefit from better type safety and could expose relevant methods directly on the vector newtype. Here's an example of a potential interface for this system demonstrated with an example use case:

// Requires the `newtype` feature.
use glam::newtype::{new_vec_type, VecType, VecConvertFrom, glam_assert};

struct ChunkPosDef;

const CHUNK_POS_RANGE: std::ops::Range<i64> = ...;
const CHUNK_SIZE: u8 = 16;

impl VecType for ChunkPosDef {
	// Backing: BackingVec
	type Backing = glam::i64::Vec3;

	// An handler to run optional vector validation code. Maybe this
	// could be exposed to non-debug builds as an `is_valid` check?
	fn post_op_validate(&self) {
		glam_assert!(
			CHUNK_POS_RANGE.contains(&self.x) &&
			CHUNK_POS_RANGE.contains(&self.y) &&
			CHUNK_POS_RANGE.contains(&self.z)
		);
	}
}

struct WorldPosDef;

impl VecType for WorldPosDef {
	type Backing = glam::i64::Vec3;

	// `post_op_validate` has a default no-op implementation.
}

// There's a reason we use a custom converter trait on the `Def` struct
// as opposed to implementing `From` on the new-type struct. See justification
// further down in the proposal for details.
impl VecConvertFrom<ChunkPosDef> for WorldPosDef {
	fn convert_backing(vec: Self::Backing) -> ChunkPosDef::Backing {
		vec * CHUNK_SIZE as i64
	}
}

struct BlockPosDef;

impl VecType for BlockPosDef {
	type Backing = glam::u8::Vec3;

	fn post_op_validate(&self) {
		glam_assert!(
			self.x < CHUNK_SIZE &&
			self.y < CHUNK_SIZE &&
			self.z < CHUNK_SIZE
		);
	}
}

new_vec_type! {
	pub struct WorldPos(WorldPosDef);
	pub struct ChunkPos(ChunkPosDef);
	pub struct BlockPos(BlockPosDef);
}

pub trait WorldPosExt {
	fn compose(chunk: ChunkPos, block: BlockPos) -> WorldPos;
	fn chunk(self) -> ChunkPos;
	fn block(self) -> BlockPos;
}

// There's a reason we use newtypes here. See justification further down in the
// proposal for details.
impl WorldPosExt for WorldPos {
	pub fn compose(chunk: ChunkPos, block: BlockPos) -> Self {
		// ...
	}

	pub fn chunk(self) -> ChunkPos {
		// ...
	}

	pub fn block(self) -> BlockPos {
		// ...
	}
}

There are a few ways we could implement this. The naïve approach would be to forward every single method from the user's new type vector struct to the underlying backing vector. This will likely have a detrimental impact on compile times, however. We can improve on compile times by expressing newtypes as a dummy "flavor" generic parameter on some central NewVectorType struct maintained by glam. To illustrate how this could help us, here's a proof-of-concept of what the macro could produce:

new_vec_type! {
	pub struct WorldPos(WorldPosDef);
}

// ==>

pub type WorldPos = ::glam::newtype::NewVectorType<WorldPosDef>;

// ...somewhere in `glam::newtype`:

#[repr(transparent)]
pub struct NewVectorType<#[fundamental] T: VecType>(T::Backing);

In essence, new_vec_type! just becomes a fancy macro for defining a type alias (we might not even need/want this macro anymore). Because of trait coherence rules, users are not allowed to introduce inherent impls onto their newtypes. This is actually a blessing in disguise, because we can now ensure that new inherent impls introduced by glam will not conflict with a user's existing inherent impls, ensuring that adding new methods is always non-breaking.

You might have also noticed the #[fundamental] attribute. This is a nightly-only attribute that allows users to implement traits from upstream crates on Vector<T> so long as they are the owner of T. This is a useful attribute to expose but it isn't strictly necessary for the actual system. impls affecting the behavior of the newtype (e.g. vector conversions) are handled by moving these traits to the "flavor"/VecType struct (notice how we implement VecConvertFrom on the struct implementing VecType directly, rather than using the STL's From trait?) and the user's inherent impls are turned into extension methods.

Open Questions

1. Should this be implemented in the same crate as glam or should it be implemented in a different crate that's maintained under the same source tree. If so, how should glam's "raw" vectors interact with newtyped ones?
2. How could users encode more specific rules for their custom vectors' behaviors? For example, if vectors ever get a .checked_add or a .saturating_add method, how would this interact with newtypes? Should users be allowed to deny/override specific methods?
3. Is there some existing impl composition framework for Rust that this should interact with?
4. Is the forwards-compatability provided by the macro actually worth it?

[bitshifter]

I think that this is probably out of scope for glam right now. It's not something I would have time to work on myself and I'm not sure I'd want to commit to maintaining it either although that would depend on what the feature looked like in reality. However, it seems like there isn't any reason this couldn't be experimented with in a separate crate. Or are there glam internals that this would need to access? I don't think I have a complete understanding of what this does right now so a separate proof of concept would help there as well.

I'm guessing a generic version of glam wouldn't solve your problem as you still have the issue of needing to implement necessary traits on the newtype? Although that might be a simpler problem to solve.

[Radbuglet]

Sorry for the long delay in my reply. I wrote a proof-of-concept implementation of the newtyping systen. Available in this repository is an implementation of the TypedVector<F> type with support for glam::f32::Vec3 as a backing vector. Here's how it's used:

// Nothing from `typed-glam` needs to be imported here. These behave as if they truly were their own
// types.
pub use decl::{ChunkPos, WorldPos, WorldPosExt};

mod decl {
	use typed_glam::{FlavorCastFrom, TypedVector, VecFlavor};

	// `TypedVector` takes a dummy struct implementing `VecFlavor` (also called a "flavor") and produces
	// a strongly typed wrapper around the flavor's `Backing` vector. Newtyping a vector takes 7 lines
	// instead of just under 700.
	pub type WorldPos = TypedVector<WorldPosFlavor>;

	pub struct WorldPosFlavor;

	impl VecFlavor for WorldPosFlavor {
		type Backing = glam::Vec3;
	}

	pub type ChunkPos = TypedVector<ChunkPosFlavor>;

	pub struct ChunkPosFlavor;

	impl VecFlavor for ChunkPosFlavor {
		type Backing = glam::Vec3;
	}

	// Users can still implement extension methods on their vector "newtypes."
	pub trait WorldPosExt {
		fn do_something(&self);
	}

	impl WorldPosExt for WorldPos {
		fn do_something(&self) {
			println!("Something! {self}");
		}
	}

	// Users can define custom casts from one newtype vector flavor to another. This works because
	// we're defining the conversion on the flavor rather than on the vector directly.
	impl FlavorCastFrom<ChunkPosFlavor> for WorldPosFlavor {
		fn vec_from(vec: ChunkPos) -> WorldPos {
			(vec * 16.).raw_cast()
		}
	}
}

fn main() {
	// The interface of newtyped vectors and regular `glam` vectors are almost identical. The only
	// exceptions to this parity are:
	// - Swizzling is disabled because it doesn't really make sense in this context.
	// - Users cannot use the bare struct constructor because we need to introduce a `PhantomData`.
	//   This is also the reason for which we introduced a newtype wrapper instead of just adding the
	//   flavor parameter directly to the vector types.
	let mut world_pos = WorldPos::new(1., 1., 1.);
	world_pos += 0.4 * (WorldPos::X + WorldPos::NEG_Y).normalize();

	let mut chunk_pos = ChunkPos::new(3., 2., 4.);

	// Raw vectors can always be used with newtyped vectors.
	chunk_pos *= 3. * glam::Vec3::X;
	chunk_pos -= ChunkPos::new(1., 3., 4.);

	// Oh look, contextual extension methods.
	world_pos.do_something();

	// Users can `cast` flavors directly if they need to.
	chunk_pos += world_pos.raw_cast();

	// But they really should be using the safe casts provided by the flavor.
	chunk_pos.cast::<WorldPos>().do_something();
}

This snippet was taken directly from examples/basic.rs.

The following features still need to be implemented:

1. Generate the remaining files so all other vectors become backing vectors.
2. Integration with Matrix, Affine, and Quat transformations.
3. Support SIMD-backed vectors as backing vectors.
4. Documentation forwarding.

Or are there glam internals that this would need to access? I don't think I have a complete understanding of what this does right now so a separate proof of concept would help there as well.

In my opinion, the typed-glam crate/cargo feature should be maintained under the same tree since there's a lot of overlap in codegen. Ideally, adding a new method to an existing vector type would add the corresponding forwarding method to TypedVector.

[bitshifter]

Just want to update that it might be a while before I can take a proper look at this. Busy with work/life things right now and there's a couple of glam issues I'd like to get on top of as well.