Skip to content

Metal Rendering for Cocos2D

Jump to bottom
christinakelly edited this page Sep 30, 2014 · 7 revisions

Metal Rendering for Cocos2D:

(See also: Custom Metal Shaders)

Metal is a new high performance graphics API created by Apple for new iOS devices. Starting in Cocos2D 3.3, the Metal renderer is now an option. The short term benefits of the Metal renderer will be small, but over time as the hardware support grows we could start adding more Metal specific features.

Some of the current benefits include:

  • Good performance even when batching isn't possible.
  • A powerful new shader language.
  • Full support for NPOT textures including mipmapping and repeating textures.

There are some downsides to using Metal as well:

  • Metal is an extra platform to support and test. Supporting Metal only right now is not really an option.
  • CCEffects have not been implemented for Metal yet.
  • CCClippingNode has not been implemented yet.
  • PVR texture files are not supported yet, and many internal formats will never be supported.
  • Depth and stencil buffers have not been implemented yet.

How to Enable Metal Rendering:

1) Ensure You Are Deploying to a Metal Capable Device:

Apple only supports Metal on certain devices. Currently only the following:

  • iPhone 5s, 6 and 6+
  • iPad Air and Retina Mini.

Metal is NOT supported on the following devices:

  • iPhone 5 or lesser
  • Any current iPod Touch (up to and including the iPod 5G)
  • iPad 4 or lesser
  • iPad Mini
  • iOS Simulator

The lack of Metal support for the iOS simulator is problematic. More on that later.

2) Enable Metal Support in ccConfig.h:

Open ccConfig.h and change the define for CC_ENABLE_METAL_RENDERING to 1. Easiest step in the whole process!

3) Adjust your Target's Build Settings:

(TODO: Can SB users skip this step if we update the templates?)

First, you must add a header search path for the Metal shader compiler. In your app target's build settings locate the Header Search Paths option under the Metal Compiler - Build Options section. You need to add the cocos2d/ directory to the search paths. This directory contains the Cocos2D source and header files. For a SpriteBuilder project, the path should be "$(SRCROOT)/Source/libs/cocos2d-iphone/cocos2d", but you should double check.

Metal header search paths

Secondly, since the Metal framework is not available for the iOS Simulator SDK, you must weakly link against it. Go to your app target's build settings and add -weak_framework Metal to the Other Linker Flags option.

weakly linking

Unfortunately this is only a half solution since it will still fail to compile any Metal shader files. Hopefully this is an issue that Apple will fix eventually.

4) Add CCShaders.metal to your Target:

The final step! Now you need to add the CCShaders.metal file located in the cocos2d/Platforms/iOS directory. This is the inside the same cocos2d directory used in step 3.

NOTE: Unfortunately your target cannot contain any .metal files if you want to deploy to the iOS Simulator. If you do want to deplay to the simulator you will need to remove the Metal shaders from your target's sources list. If anybody has a workaround for this I'm all ears!

Clone this wiki locally