Skip to content

A proxy for MetalPerformanceShaders which takes to a stub on a simulator and to the real implementation on iOS devices.

License

Notifications You must be signed in to change notification settings

xmartlabs/MetalPerformanceShadersProxy

Repository files navigation

MetalPerformanceShadersProxy

Build status Platform iOS Swift 4 compatible Carthage compatible CocoaPods compatible License: MIT

By Xmartlabs SRL

A proxy for MetalPerformanceShaders (and dependents) which takes to a stub on a simulator and to the real implementation on a device. It works both for Swift and Objective-C.

It's usually a problem not to be able to compile for a simulator target when using Metal shaders. By using this proxy, you are being able to compile and to run on simulators. Note that trying to run the Metal shaders on a simulator will fail. Nevertheless, it allows a project that implements Metal shaders to:

  • Upload a pod to CocoaPods.
  • Make a framework to work with Carthage.
  • Run an app on a simulator to use features that don't depend on Metal shaders.
  • Compile unit tests.
  • Test automatically (maybe with a CI server) with simulators the parts of an app that don't depend on Metal shaders.

Usage

If you use Metal, you probably use CVMetalTexture.h and CVMetalTextureCache.h from CoreVideo or CAMetalDrawable.h from QuartzCore. But they are not available when targetting the simulator. To make them available, just do:

import MetalPerformanceShadersProxy

This pod will add no stub to devices (no footprint!), as the proxy uses preprocessor macros to decide which implementation to use.

Note that if a stub method is called, a exception will be thrown.

currentDrawable from MTKView

currentDrawable property of MTKView is of type CAMetalDrawable in the device but of type MTLDrawable in the simulator. So you need to cast it in your code to use it properly. E.g., if you have

let texture = view.currentDrawable.texture

change it to

let texture = (view.currentDrawable as? CAMetalDrawable)?.texture

This is the best workaround we came up with. If you happen to have a better idea, please open an issue.

Advanced: Control when to use the stub

If for some reason you want to control when to use the stub, you can import the stub like:

#if condition
    import MetalPerformanceShadersStub
#endif

How it was created

See CREATION for an explanation.

Requirements

  • iOS 9.0+
  • Xcode 9.0+

To use with previous Xcode versions, see previous releases.

Getting involved

  • If you want to contribute please feel free to submit pull requests.
  • If you have a feature request please open an issue.
  • If you found a bug or need help please check older issues before submitting an issue..

In particular, if you find a missing Metal-dependent framework, open an issue or better submit a pull request 😄

Before contribute check the CONTRIBUTING file for more info.

If you use MetalPerformanceShadersProxy in your app, we would love to hear about it! Drop us a line on Twitter.

Examples

Follow these 3 steps to run Example project: clone MetalPerformanceShadersProxy repository, open MetalPerformanceShadersProxy workspace and run the Example project.

As a real example, you can check out the Bender library.

Installation

CocoaPods

CocoaPods is a dependency manager for Cocoa projects.

To install MetalPerformanceShadersProxy, simply add the following line to your Podfile:

pod 'MetalPerformanceShadersProxy', '~> 0.3'

If you just want the stub:

pod 'MetalPerformanceShadersProxy/Stub', '~> 0.3'

Carthage

Carthage is a simple, decentralized dependency manager for Cocoa.

To install MetalPerformanceShadersProxy, simply add the following line to your Cartfile:

github "xmartlabs/MetalPerformanceShadersProxy" ~> 0.2

Author

Changelog

It can be found in the CHANGELOG file.