Articles on treamous's Blog

Panda3D iOS Support - A Postmortem

treamology@gmail.com (treamous) — Mon, 26 Aug 2019 00:00:47 +0000

Hi everyone!

Well, it appears that this is the end of the line when it comes to my GSoC portion of my work. I got a huge amount of work done and am extremely proud of it, and I can't wait to continue working on this project in the coming months and make it the best it can be. This blog post is here to detail the work I completed over the summer, and also what I didn't have time to get to. So, let's begin!

Everything I completed

CMake Build Support

This actually ended up taking a lot of my time this summer (around a month). Currently, Panda3D uses a custom build system known as makepanda. Although this is a venerable and versatile build script, it was decided that a more standardized build system would be a better choice, so work began on replicating our current system with CMake. Because I began my iOS work before the CMake system was actually complete, this led to a couple of instances where I wasn't sure if there was an issue with my own code or with the Panda's experimental CMake implementation. In the end, however, thanks to CMake 3.14's new support for iOS devices, I was able to complete this task within the expected time frame.

eagldisplay

David Rose, who briefly worked on an iOS port (back when iOS was iPhoneOS), created the iphonedisplay module as an experimental method of running Panda apps. While this was a good starting point, I felt it was best to start from scratch considering the number of changes iOS has seen since the days of the iPhone 3G. This new display module should be easier to extend in the future when adding in a Metal backend, for example. Most of this is complete - there is support both for GraphicsWindows and GraphicsBuffers, along with some basic features such as autorotation.

PandaViewController

PandaViewController is a helper UIView that encapsulates the entirety of Panda on the Cocoa side of things. All one needs to do is specify where the Python source is, and PandaViewController will handle initializing Python and handing control to the Python script. I decided to go with this method of starting Panda mostly so existing apps can easily integrate Panda - it doesn't take over the main application loop or anything, so it quite very nicely with existing systems.

make_xcodeproj and makewheel.py

In addition to actually getting iOS support working, I also wanted to get started on the deployment process. Firstly, this required modifying makewheel.py to allow for the creation of wheels for iOS. This actually ended up being more complicated than I was first expecting, since makewheel had been designed to only generate wheels for the host system. I got it working in the end, though, and was able to begin churning out iOS-specific wheels. In addition, I had to add a new command to our setuptools-based deployment system that allows for the creation of Xcode projects, since that is the only way to test and deploy iOS apps on-device.

Multitouch (only partially)

I had gotten mouse emulation working well pretty early on in the project, since it was just a matter of converting touch events to the existing mouse events Panda is used to. Adding full-blown multitouch, however, has been much more of a challenge. Panda is not accustomed to handling multiple pointers (or anything other than a mouse, for that matter), so it took some changing at the architectural level, but I got a partial implementation working.

Stuff I didn't get to

DirectGUI touch support

This is something that I simply didn't have time for. It took me longer than expected to change Panda's architecture to allow for multiple pointers. While the DirectGUI widgets will indeed work, any touch specific gestures such as swiping to scroll are not present.

C++ app support

I had decided to prioritize getting Python working over C++, since the vast majority of Panda apps are written in Python. This should not be too difficult to accomplish; it should just be a matter of changing the entrypoint that PandaViewController uses when spawning a new thread.

Custom file handler for make_xcodeproj

Currently, make_xcodeproj just does a straight copy of all the game files, and ignores the custom handlers that can be specified in build_apps.

Documentation

Although I documented a lot of the code through comments, I failed to write any manual entries or longform docstrings. When I do this in the future, I would like to wait until we are filly migrated to the Sphinx manual instead of our custom MediaWiki stack.

Unit Tests

I never got to these simply because it would have taken a while to figure out what to actually test. As far as I know, there also isn't any good method of running tests on the C++ side of things; most of the existing unit tests utilize the generated Python bindings and call into the codebase from there.

What I could have done differently

Better communication with mentors

I did not talk to and consult with my mentors over Discord as much as I should have. I have a habit where I am hesitant to get feedback on my work unless it is in a somewhat completed state; I would end up telling myself, "I just need to finish up this one last feature/bug/whatever, then I'll push my work." And before I knew it, a week had passed by! This led to me dumping large changes all at once, which certainly was not helpful in quickly getting feedback.

Separation and organization of my work

I mainly used two branches for development: one called "cmake-ios" that I used to add CMake support and also write the display backend, and then a separate "multitouch" branch that is based from "cmake-ios". For my GitHub pull request, I ended up just merging everything into an "ios" branch, so a lot of different types of commit are all intertwined. There's not a lot of separation where someone can think to themselves, "oh, they added this feature in this commit, then continued working on it in this next commit". It's more like a developer with ADHD jumping around between features and bugs whenever they get noticed.

Although this is the end of my GSoC experience for this year, it is not the end of my work with Panda. I had already fixed a few bugs and gotten a few pull requests merged before I started this project, and I don't plan to stop that trend. Additionally, I am excited to continue my work on the iOS backend into the fall (on my own time, without a deadline looming over my head!). I am extremely happy with how everything has turned out so far, and am super excited to continue working with my mentors and everyone else in the community!

So long!

Multi-touch update

treamology@gmail.com (treamous) — Sat, 24 Aug 2019 20:26:32 +0000

Alas, time has caught up to me. I will not be able to get the touch trackball controls working in time for the submission deadline. Instead, I need to use this remaining time to package up my work and create a more thorough write-up that details what I have done and what is left to be done.

I'm still excited, though, since I got all of the minimum requirements of my proposal done and have gotten a good start on a few extras. I will be working beyond the end of GSoC to get iOS support to a ready state.

See you soon!

Weekly Check-in #9

treamology@gmail.com (treamous) — Thu, 08 Aug 2019 23:17:26 +0000

Hello!

This week, I've been working a lot on Panda's multi-touch support. The goal is to make some headway towards modifying Panda's architecture to not make the assumption of a single mouse. Since Panda is around two decades old at this point, and multi-touch hardware was not widely available during the time it was written, this is a very formidable task. I'd like to get at least of baseline level of support, but some large changes will need to be made throughout Panda's code in order to bring its pointer handling up to modern standards. In order to ensure the support I finish is at least somewhat usable, I will probably need to skip out on my stretch goals. But, that's why they're stretch goals in the first place, right?

See you next week!

Packaging your Panda3D game for iOS

treamology@gmail.com (treamous) — Wed, 31 Jul 2019 03:10:26 +0000

HI everyone,

I'd like to quickly detail how you can help test out the iOS port using your own game. I am making available a wheel that contains all of the files required to develop a Panda app on iOS. To build your game for iOS, there is a new command, `make_xcodeproj` that comes as an addition to the recently released deploy-ng system. There is no formal documentation available yet, but one should be able to surmise how it works based on the source code, located in direct/dist/commands.py. It is best if you get a build of your app using the build_apps command going first, since make_xcodeproj piggy-backs off of it in order to generate an Xcode project.

You can download the wheel here.

See you later!

Weekly Check-in #7 & #8

treamology@gmail.com (treamous) — Thu, 25 Jul 2019 20:36:59 +0000

Hello!

I have been quite busy these past two weeks. I have been working on fleshing out a design for Panda's multitouch support, along with trying to get a deployment pipeline working on iOS. I got Travis CI working on the panda3d-thirdparty repository, so now anyone can go download and build the thirdparty packages for iOS. Once I'm done wrapping up the initial deployment pipeline, I am going to package up some of the sample apps for people to try out!

Weekly Check-in #6

treamology@gmail.com (treamous) — Mon, 15 Jul 2019 17:22:31 +0000

Hi everyone!

Time for another update. These past two weeks I've been trying to clean up how I've been implementing things, since a lot of my code thus far has been pretty prototypey. I have the backend at a point where I can start to turn to other features, like multitouch. This past week I implemented some basic mouse emulation, which you can take a look at here:

See you next week!

Weekly Check-in #5

treamology@gmail.com (treamous) — Wed, 03 Jul 2019 14:48:51 +0000

Hello!

This week has been one where work has been less visible. I've been trying to get the Panda lifecycle completely working, which has been quite difficult without good debug tools. I guess that's good motivation to get PStats and the like working! I also have a build going for the iOS simulator, and I'd like to figure out a way of lipo-ing those two libraries together for distribution. I'm pretty sure CMake supports something like this, but I still need to look into it. For this next week, I'll be trying to get Panda startup and shutdown completely working, so you can properly switch between samples without memory leaks.

That's my brain dump, see you next week!

Weekly Check-in #4

treamology@gmail.com (treamous) — Wed, 26 Jun 2019 04:06:00 +0000

Hi!

This past week was very productive. I got many of the Panda samples running inside an iOS app. Here's one of them:

This app allows you to go back and forth between all of the samples included with the Panda3D game engine. Since the samples cover a wide range of features, it's great for testing. It was (and still is) quite a challenge to get Panda and iOS melding properly, but I'm glad I'm finally getting some visible results. For this next week I'm going to see if I can get baseline version of the iOS display backend up for other people to try. See you all then!

Weekly Check-in #3

treamology@gmail.com (treamous) — Mon, 17 Jun 2019 13:50:12 +0000

Hello!

Welcome to my third weekly check-in. I got a lot done over the past week, so let's talk about it.

During the first part of the week, I spent a large amount of my time attempting to wrangle the Python interpreter into actually running inside an iOS app. During the build process, Python generates a sysconfig file that contains variables that were used during the build that may be useful to Python later on. Unfortunately, this generation cannot happen on iOS easily, since it requires an arm64 device to actually run on. The solution to this ended up being to generate this sysconfig file in the Simulator, and make some changes to it manually for the Device version. This works well enough, and I haven't run into any issues with it yet, but we'll see.

The second half of this week, I turned towards brainstorming about how to adapt Panda's startup process to the iOS app lifecycle. Up until this point, Panda has been a game engine that runs exclusively on desktops, and as such, it is used to having complete control over the application lifecycle. Things work a bit differently on iOS (and Android!), however, which will require me to make some changes with how Panda handles it. Coming up with a formal design for this will be one of my primary tasks for this coming week.

Along with this, I am going to try and come up with a way to get Panda along with the Python interpreter to run in a separate thread entirely from the main UI thread. This will make it so I will have to make fewer changes to Panda in order for the UI thread to get the time it needs. I plan on publishing a more detailed write-up about how I will accomplish this soon.

That's all I have for this week. See you next time!

Weekly Check-in #2

treamology@gmail.com (treamous) — Mon, 10 Jun 2019 22:49:06 +0000

Hello again!

With the second week of work wrapping up, I believe an update is in order. I have successfully gotten both the thirdparty tools and Panda itself to compile for both iOS devices and the simulator. It was a bit of a slog getting this to work, to be honest, since it's mainly a loop of trial and error trying to get things to fit together correctly. The following libraries are now ready for inclusion on iOS:

ARToolkit
Bullet
Eigen
FFMpeg
Freetype
Harfbuzz
JPEG
ODE
OpenSSL
Opus
PNG
Python
Squish
TIFF
Vorbis
ZLib

This leaves only a few libraries that aren't working (and are probably impractical for iOS anyways, like VRPN). I'm quite happy with this, because although I was able to get Panda itself to compile several months ago, this is the first time I have done it with almost all of the thirdparty libraries included. It has been quite a struggle wrangling with the often strange ways Apple does things, but I believe this thorough preparation I've performed will be worth it down the road.

This post comes at an odd time, admittedly, since these next two weeks are where the real meat of the work is going to start. But, posts are required every two weeks, so here it is. Hopefully the work going forward will be a bit more exciting for people to read about, and won't involve me waiting for rebuilds for nearly as long ;)

Weekly Check-in #1

treamology@gmail.com (treamous) — Sun, 02 Jun 2019 19:31:17 +0000

What did you do this week?

This week, I got the cross-compilation toolchain up and running. Now all of Panda3D’s requisite libraries, including Python, can be compiled for iOS devices with just one command.
What is coming up next?

Next week, I will be getting the engine itself to compile for iOS. I’ve already gotten this semi-working before, so this shouldn’t be too monumental of a task.
Did you get stuck anywhere?

I got stuck several times while wrangling with various autotools scripts, which needed to interact with the CMake script used to download and compile everything. With enough trial and error, I was able to solve all of the issues I ran into.

Hello!

treamology@gmail.com (treamous) — Tue, 28 May 2019 18:23:34 +0000

Hello to everyone who stumbles upon this post! I'm going to be working on iOS support for the Panda3D game engine. During the community bonding period, I worked on porting the manual to a Sphinx website hosted on Read The Docs. Work on the port is pretty much finished; there just needs to be a bit of proofreading and jankiness-fixing. For this first week, I will be working on getting Panda's thirdparty libraries to compile successfully on iOS.

See you next week!