Naming conventions

[bsekura]

TLDR
Take Metal Objective C and Swift API and change names to Rust idiomatic names where applicable.

General

Rust bindings are based on Objective C protocol bindings.
Follow Objective C protocol definition to determine properties and methods.

Swift API adds some higher level stuff that is beyond the scope of Rust bindings.

Struct (Object) and Enum names

Same as Objective C/Swift API, e.g.

MTLDevice, MTLCommandBufferStatus, MTLCommandBuffer etc.

Enums

Swift

enum MTLCommandBufferStatus : UInt {
  case notEnqueued
  case enqueued
  case committed
  case scheduled
  case completed
  case error
}

Rust: change variant names following Rust conventions:
(basically capitalize first word)

pub enum MTLCommandBufferStatus {
  NotEnqueued,
  Enqueued,
  Committed,
  Scheduled,
  Completed,
  Error,
}

NOTE: Some enums contain Apple brand names that intentionally start with lowercase.
In those cases respect that, adding necessary #allow to keep Rust happy. For example:

#[allow(non_camel_case_types)]
#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
enum OS {
    iOS,
    tvOS,
    macOS,
}

Method names

Objective C

- (void)addCompletedHandler:(MTLCommandBufferHandler)block;

Swift

func addCompletedHandler(_ block: @escaping MTLCommandBufferHandler)

Rust: change to lowercase snake case:

pub fn add_completed_handler(&self, block: &CommandBufferHandler)

Special Case

Some methods create new objects (aka factory methods).

Objective C:

- (id<MTLComputeCommandEncoder>)computeCommandEncoderWithDescriptor:(MTLComputePassDescriptor *)computePassDescriptor;
- (id<MTLComputeCommandEncoder>)computeCommandEncoderWithDispatchType:(MTLDispatchType)dispatchType;
- (id<MTLComputeCommandEncoder>)computeCommandEncoder;

Swift:
NOTE: overloading

func makeComputeCommandEncoder(descriptor computePassDescriptor: MTLComputePassDescriptor) -> MTLComputeCommandEncoder?
func makeComputeCommandEncoder(dispatchType: MTLDispatchType) -> MTLComputeCommandEncoder?
func makeComputeCommandEncoder() -> MTLComputeCommandEncoder?

Rust:

• use Objective C name (we don't want overloading)
• change to lowercase snake case as usual
• follow Swift way to emphasize the intention; change make to new, as we do in Rust:

pub fn new_compute_command_encoder_with_descriptor(desc: MTLComputePassDescriptor) -> &ComputeCommandEncoderRef {}
pub fn new_compute_command_encoder_with_dispatch_type(&self, ty: MTLDispatchType) -> &ComputeCommandEncoderRef {}
pub fn new_compute_command_encoder(&self) -> &ComputeCommandEncoderRef {}

[chinedufn]

Awesome! Thanks so much for putting this together and including examples!

This looks fine to me.

If @kvark doesn't have any issues, want to just PR this into guide/naming-conventions/README.md.

Really like that you included examples, this was easy to follow.

Thanks!

[kvark]

My ❤️ emoji agrees with you!

[xixixao]

What about MTLComputeCommandEncoder::new_with_descriptor(), would that be possible?

[kvark]

That would be an improvement, I think.

[kvark]

We want to release gfx-backend-metal very soon. Would anybody want to help with these naming changes in metal-rs? It's not a blocker for us, we can release an intermediate version.