Progress of new backend API

Progress of new backend API

If you don’t know what’s backend API, then you can refer to this ticket for detail information. The backend API is to design a API that cross metal/opengl/vulkan. This ticket will update the progress of the API design and implementation.

After about one or two months discussion and learning, i started implementing the API about weeks ago, and i added some test cases. My plan is to implement opengl backend first to polish the API, then use metal to implement it. Of course the API may change when implementing metal backend, but i think the architecture will not change, just adjust some API, such as the API names, parameters and so on.

You can download the codes to take a look of the API and run the test cases. The steps of downloading source codes and running tests are:

  • clone
  • check out metal-support branch
  • open test/Test.xcodeproj
  • select Test-ios -> simulator or device and run the test on GL backend, if you want to run metal backend, then you can select Test -> Mac.

Currently, there are 3 test cases, you can change tests/main.cpp to run different test cases.

All the codes of new backend API is in src/backend, all the test cases are in test/tests/backend. As you can see, in order to draw a frame, you should use command buffer to commit things:

  • start render pass
  • set view port
  • set renderpipeline
  • set vertex buffer/index buffer
  • draw arrays/elements
  • end render pass

The backend API is not completed, but most parts are included. Some questions i have currently are:

  • Is it too complex to clear color/depth/stencil? But metal clear these values like this.
  • Device.createXXX return autoreleased objects as other cocos2d-x API, but most times, you don’t want autoreleased objects, they are retained to be used later. Should change it? Or use other better function names?
  • Command queue seems not needed in opengl, and metal also can have only one queue, should remove command queue, and use default command queue in metal?
  • Are there any important features missed?

Any feedback is appreciated. Thanks in advanced.

Graphics backend for opengl and metal
Graphics backend for opengl and metal
Getting Started with Cocos2D
Progress of graphics backend integration
How about remove 3D related and some other codes when integrating metal?
Graphics backend for opengl and metal
pinned globally #2


  • add depth texture test
  • iOS can work too
  • can touch the screen to switch test cases
  • fix sampler usage
  • add TextureFormat::D16
  • fix some logic error in RenderCommandGL

Works left:

  • add blending support
  • add more test cases


  • add blending support and test case

I will start metal backend implementation tomorrow. I think it is time to do it. Though the API is not completed, but it covers at least 90% usage. Starting metal backend implementation will polish the API ASAP.


Great Work @zhangxm Can we expect Metal support cocos release in 5 or 6 months? Also initially are you planning to support Vulkan as well?


@kiranb47 if only implementing metal backend without adapting cocos2d-x, then i think it is not problem. Currently, i am not sure how long it should to adapt cocos2d-x, since it is not easily copy/paste. Vulkan supporting will be started after cocos2d-x supports metal.


Great Work @zhangxm.
We can do custom openGL rendering in current version of cocos.
Can we do same thing with metal in the future?
Thanks a lot.


@amin13a yep, i think it is possible. But you should not use opengl/metal API directly, use the backend API.

1 Like

I’m waiting for a metal support cocos2dx version. May be Cocos2dx V4.x. I know it takes time. I will wait. Thank you

1 Like

Thanks. And yes, it can be named v4.x since it may break some API, and i may remove 3d related codes to simplify the adaption.


On which iOS devices all this will be tested, confirmed and optimized?
I believe you have all of them to profile and done all thing right. Right?

Obviously, if compare for example: iPhone 6 and iPhone 6s - the iPhone 6S has a faster hardware, so all this needs to test on iPhone 6 only(as minimum), but ideally need to test and confirm stable work on all other devices, which is even faster but share same model type.

And this list is:

iPhone 5S and ideally to confirm on iPhone SE
iPhone 6 and to confirm on iPhone 6S and/or iPhone 7 and/or iPhone 8
iPhone 6 Plus and to confirm on iPhone 6S Plus and/or iPhone 7 Plus and/or iPhone 8 Plus

iPhone X and to confirm on iPhone XS
iPhone XS Max
iPhone XR

iPad Air and to confirm on iPad Air 2 and/or on iPad (2017) and/or on iPad (2018)
iPad mini 2 and to confirm iPad mini 3 and on iPad mini 4

iPad Pro 9.7-inch
iPad Pro 10.5-inch
iPad Pro 12.9-inch


Iphone 5 or iphone 5c cannot have metal api, only a7 and above, 64 bit chips has.


Thanks, I forgot about this :smiley: minus a couple of devices.


@zhangxm Would you please clarify what you mean by “remove 3d related codes”. Would that mean we can’t use 3D at all with that specific release? How soon would it be before 3D related code is added again?

The reason I’m asking is that we have just decided to use 3D for certain aspects of our product (it’s a 2D product, but with a few 3D animations), but if it won’t be supported by the time it is released (mid-2019), then we need to re-evaluate our decision. Best case, we don’t use 3D and just do the animations in Spine, worst case, we switch to another engine (which I really would prefer not to do).


@cc_x Yep, i think i have to test on these devices after adapting to cocos2d-x. Sorry, i don’t have all the devices, but i think the community can help to test too.

@R101 we haven’t made the final decision to remove 3d, we may discuss it in another thread. I will create a new thread. And even we don’t make sure if it should be renamed v4 or a new 3.x. It will break some API, but it doesn’t bring more new features.


I created this thread to remove some codes when integrating metal.


@zhangxm Whenever you need any testing help, let me know.
I can test on whatever devices we have. (Android/iOS both)


Thats very bad, for quality profiling and optimizing you need a real device to do so in Xcode and quickly test/fix/improve anything. Am I talking about standard and obvious things?


@smitpatel88 thanks.
@cc_x i will test as more devices as i can, but i don’t have all the devices.