Model I/O – How to use `makeVerticesUniqueAndReturnError()` instance method?

Question

An instance method makeVerticesUnique() modified the mesh’s vertex buffers so that no vertices were shared by multiple faces. But it was deprecated in macOS 10.13 High Sierra and in iOS 11:

mdlMesh.makeVerticesUnique()            /* deprecated in macOS 10.13 and iOS 11 */

Now developers must use a new instance method:

func makeVerticesUniqueAndReturnError() throws

But it's not documented. How to use it?

When I'm using this new instance method Xcode gives me an error:

'throws' may only occur before '->'

Answer 1

Whenever you don't find docs on developer.apple.com or in the Xcode Documentation Viewer, check the framework headers or Swift interface — those often have code comments that can at least serve as a rough form of documentation.

In Xcode, use Open Quickly (⌘⇧O) and type the name of the header in question (MDLMesh.h) or one of the symbols inside it (MDLMesh, makeVerticesUnique, etc). Or ⌘-click one of those symbols in your source and choose Jump to Definition. (If at that point you end up in an Objective-C header and want to see the Swift version, choose Generated Interface from the related items menu at the top of the file.)

In this case, you'll see that both methods are equivalent in usage (but for the ability of the new method to throw errors):

/*!
 @method makeVerticesUnique:
 @abstract Deindexes the vertex array
 @discussion If any vertices are shared on multiple faces, duplicate those
             vertices so faces do not share vertices. The vertex buffer and index
             buffers on submeshes may grow to accomadate any vertices added.
 */
@available(OSX, introduced: 10.11, deprecated: 10.13)
open func makeVerticesUnique()


/*!
 @method makeVerticesUniqueAndReturnError:
 @abstract Deindexes the vertex array
 @discussion If any vertices are shared on multiple faces, duplicate those
 vertices so faces do not share vertices. The vertex buffer and index
 buffers on submeshes may grow to accomadate any vertices added.
 */
@available(OSX 10.13, *)
open func makeVerticesUniqueAndReturnError() throws

Presumably Apple determined that the original method wasn't handling failures gracefully (fatal-error halting? crashing? producing bad output? dunno) and decided it'd be better to let callers know when something goes wrong.

Answer 2

This new instance method perfectly works with try! keyword:

try! mdlMesh.makeVerticesUniqueAndReturnError()

In my particular case a throwing method won’t throw an error at runtime. So I can write try! before the expression to disable error propagation and wrap the call in a runtime assertion that no error will be thrown. If an error actually is thrown, I’ll get a runtime error.