Recommend `objc2-metal` instead of `metal`

[grovesNL]

The metal crate has been around for a while now and was historically maintained by the teams of gfx pre-ll/gfx-hal (legacy) and wgpu (current). wgpu is planning to switch over to objc2 though, so that will remove one of the biggest maintainers of this crate.

As a maintainer, I'm happy to continue maintaining metal where it makes sense, but I'd like to start recommending that people switch over to obj2-metal. I'd like to add this at the beginning of the README to start directing people there. Many of the other crates in the ecosystem have already started to switch over (e.g., winit uses objc2), so I'd like to help push this forward while giving people some time to gradually transition from metal.

If anyone has concerns about recommending objc2-metal and metal maintenance, let's discuss them here.

[grovesNL]

@kvark would you be ok with this?

[kvark]

Totally ok. Currently trying to get first-hand experience with objc2.
Auto-generated bindings make total sense here.

[madsmtm]

Nice! Feel free to say if you need help or anything, I can be reached on the Wgpu Matrix if that's convenient, otherwise feel free to ask questions here or open an issue in the repo.

[madsmtm]

Cool that you've decided to mark the project as deprecated @cwfitzgerald! To make sure that nothing important is lost in the transition, I went through the list of open issues, and related them to objc2-metal (didn't want to post it on each issue, I feared that'd be quite spammy):

• Dependency Dashboard #355
  • Specific to the repo.
• Calling metal::Buffer.label() panics if there is no label set. #347
  • label getters return Option<Retained<NSString>> in objc2.
• Compute example counter sampling not working on M4 #346
  • A question. Not really an issue with metal-rs itself.
• Unable to run texture example -- shader_bindings.rs file not found #334
  • Issue with an example.
• Missing functions #325
  • objc2-metal is complete (all functions present in the headers are available).
• Is this crate umaintained? #313
  • The status of the crate is now stated explicitly in the README.
• raytracing example bugg #305
  • Issue with an example.
• Metal Compiler header file caching #302
  • Not an issue with metal-rs itself.
• Example does not support the latest winit #294
  • Issue with an example.
• Discrepency between GPU timing and CPU timing #288
  • A question. Not really an issue with metal-rs itself.
• Inconsistent Performance across runs #287
  • A question. Not really an issue with metal-rs itself.
• Kernel stops running when I click on another window. #286
  • A question. Not really an issue with metal-rs itself.
• UB in new_texture if newTextureWithDescriptor fails? #284
  • Fixed in objc2-metal (all objects are implicitly unwrapped).
• MPS Matrix Multiplication #283
  • MPS is supported in objc2-metal-performance-shaders.
• new_render_command_encoder assumes the return value can never be NULL #282
  • Fixed in objc2-metal (all objects are implicitly unwrapped).
• computation performs slower than cpu version in benchmark #246
  • A question/local perf problem. Not really an issue with metal-rs itself.
• Make auto-release pools visible #225
  • Autorelease pools are done by using a closure objc2::rc::autoreleasepool.
• Investigate use of objc_retainAutoreleasedReturnValue #222
  • objc2 uses objc_retainAutoreleasedReturnValue internally.
• Using metal-cpp for auto-generating bindings #220
  • objc2-metal is auto-generated. metal-cpp doesn't make sense for auto-generating, since Rust has a bunch of problems with C++ interop.
• Don't use auto-release pool in string-related methods #218
  • objc2-* crates manage the string with a wrapper Retained<NSString> that releases on Drop.
• MTLPixelFormat and related enumeration types are unsound? #209
  • This is fixed in objc2-metal. I've submitted RFC 3803 for avoiding this in the future.
• Debug groups and signposts on render passes #205
  • Unsure what the confusion is? MTLRenderCommandEncoder is a sub-protocol of MTLCommandEncoder, so pushDebugGroup: is available there too.
• Document function availability on platforms #202
  • Tracked as part of How do we handle availability? madsmtm/objc2#266.
• Naming conventions #190
  • Tracked in Figure out naming scheme in framework crates madsmtm/objc2#284. Current status is that enums are great, method names can definitely still be improved.
• Derive PartialEq on MTlScissorRect #183
  • Done in objc2-metal (on all structs).
• Add documentation on debugging by generating a .gpuTrace file #152
  • Tracked in Better Xcode Metal debugging documentation madsmtm/objc2#749.
• Make function parameter names and order consistent with Apple's documentation #144
  • Bindings are auto-generated, so this is a non-issue in objc2-metal.
• Automated code review for metal-rs #133
  • The discussed project is dead.
• Rename methods according to the new convention #128
  • See Figure out naming scheme in framework crates madsmtm/objc2#284.
• Apply unsafe more consistently #122
  • Methods that take pointers are unsafe in objc2-metal. For the rest, see Safety of methods appear to be illogical madsmtm/objc2#685.
• Link to associated projects from the readme #107
  • The mentioned projects are now very out of date, and probably no longer relevant.
• Explicitly load Metal symbols #105

  • Non-issue nowadays, macOS 10.12 is the lowest supported macOS version in Rust. Otherwise, -weak_framework Metal is still a good solution, can be done manually by the user in .config/cargo.toml:

    [target.'cfg(target_vendor = "apple")']
    rustflags = ["-C", "link-args=-weak_framework Metal"]

• Faster way to assign labels #100
  • objc2-metal requires constructing the NSString separately from setting the label (so the user has great control over how to create the string).
• Migrate to foreign_type! macro #99
  • objc2 has it's own system here.
• Integrate auto-release pool into the type system #86
  • Autorelease pools are supported with objc2::rc::autoreleasepool, it takes a pool parameter. Rust's type system cannot fully express the lifetimes involved though, so it's unsound to use. Instead, objc2-metal retains all returned objects.
• Naming convention #80
  • Tracked in Figure out naming scheme in framework crates madsmtm/objc2#284.
• Properly deprecate the old crate metal-rs #65
  • Fixed already in Deprecate metal-rs #66.
• Consider using objc_retain and objc_release instead of sending -retain and -release message #58
  • This is done by the objc2::rc::Retained wrapper.
• Determine supported functions #52
  • objc2 provides the objc2::available! macro, which can be used for OS detection at runtime. Feature detection can be done with either respondsToSelector: or Metal-specific things like MTLFeatureSet. See also How do we handle availability? madsmtm/objc2#266.
• True Array semantics #44
  • Index + IndexMut requires that arrays return references, which isn't safely possible with Objective-C arrays (see NSArray::objectAtIndex_unchecked).
• Byte data arguments #42
  • Tracked in Convert ptr, count arguments into slice pointers madsmtm/objc2#610. objc2-metal doesn't ever take &str, the conversion to NSString is left to the user (allows them control over the performance implications of that).
• RFC: Send+Sync on metal objects #40
  • Most objects aren't Send+Sync, since they aren't in Swift either. Mutability is also not done (objc2-metal uses &self everywhere instead for soundness). This mirrors the current state in metal-rs. See also The deal with mutability madsmtm/objc2#265.
• metal-rs examples fail with SIGILL on recent nightlies, still works on stable #35
  • Fixed in metal-rs already (and in objc2-metal)
• Add offsets to the Encoder::set_buffers #23
  • Fixed in metal-rs already (and in objc2-metal)
• Crash when running caps example #8
  • Issue with an example.

For the open PRs, all of them are only about adding new API, and all of those APIs are available in objc2-metal.

[madsmtm]

I'd like to migrate the examples you have as well, would you be okay with me merging basically git filter-repo --subdirectory-filter examples --to-subdirectory-filter examples/metal into objc2, and noted in the LICENSE.md that the Metal examples are differently licensed?

[madsmtm]

Also @grovesNL, @cwfitzgerald and @kvark, would you mind if I pinged you in objc2 if/when I get questions specifically about Metal usage? I'm only really familiar with the Objective-C parts, the Metal API itself is fairly unfamiliar to me.

[cwfitzgerald]

Oh that's an amazing overview! Thanks for that!

Yes feel free to ping me whenever, happy to help!

I think examples are fine to copy - they're meant to be ripped from.