Grafika

Welcome to Grafika, a dumping ground for Android graphics & media hacks.

Grafika is:

• A collection of hacks exercising graphics features.
• An SDK app, developed for API 18 (Android 4.3). While some of the code
  may work with older versions of Android, some sporatic work is done to
  support them.
• Open source (Apache 2 license), copyright by Google. So you can use the
  code according to the terms of the license (see “LICENSE”).
• A perpetual work-in-progress. It’s updated whenever the need arises.

However:

• It’s not stable.
• It’s not polished or well tested. Expect the UI to be ugly and awkward.
• It’s not intended as a demonstration of the proper way to do things.
  The code may handle edge cases poorly or not at all. Logging is often
  left enabled at a moderately verbose level.
• It’s barely documented.
• It’s not part of the Android Open Source Project. We cannot accept
  contributions to Grafika, even if you have an AOSP CLA on file.
• It’s NOT AN OFFICIAL GOOGLE PRODUCT. It’s just a bunch of stuff that
  got thrown together on company time and equipment.
• It’s generally just not supported.

To some extent, Grafika can be treated as a companion to the
Android System-Level Graphics Architecture
document. The doc explains the technology that the examples rely on, and uses some of
Grafika’s activities as examples. If you want to understand how the code here works, start
by reading that.

There is some overlap with the code on http://www.bigflake.com/mediacodec/.
The code there largely consists of “headless” CTS tests, which are designed
to be robust, self-contained, and largely independent of the usual app
lifecycle issues. Grafika is a conventional app, and makes an effort to
handle app issues correctly (like not doing lots of work on the UI thread).

Features are added to Grafika as the need arises, often in response to
developer complaints about correctness or performance problems in the
platform (either to confirm that the problems exist, or demonstrate an
approach that works).

There are two areas where some amount of care is taken:

• Thread safety. It’s really easy to get threads crossed in subtly dangerous ways when
  working with the media classes. (Read the
  Android SMP Primer
  for a detailed introduction to the problem.) GL/EGL’s reliance on thread-local storage
  doesn’t help. Threading issues are frequently called out in comments in the source code.
• Garbage collection. GC pauses cause jank. Ideally, none of the activities will do any
  allocations while in a “steady state”. Allocations may occur while changing modes,
  e.g. starting or stopping recording.

All code is written in the Java programming language – the NDK is not used.

The first time Grafika starts, two videos are generated (gen-eight-rects, gen-sliders).
If you want to experiment with the generation code, you can cause them to be re-generated
from the main activity menu (“Regenerate content”).

Current features

* Play video (TextureView). Plays the video track from an MP4 file.

• Only sees files in /data/data/com.android.grafika/files/. All of the activities that
  create video leave their files there. You’ll also find two automatically-generated videos
  (gen-eight-rects.mp4 and gen-slides.mp4).
• By default the video is played once, at the same rate it was recorded. You can use the
  checkboxes to loop playback and/or play the frames at a fixed rate of 60 FPS.
• Uses a TextureView for output.
• Name starts with an asterisk so it’s at the top of the list of activities.

Continuous capture. Stores video in a circular buffer, saving it when you hit the “capture” button. (Formerly “Constant capture”.)

• Currently hard-wired to try to capture 7 seconds of video from the camera at 6MB/sec,
  preferably 15fps 720p. That requires a buffer size of about 5MB.
• The time span of frames currently held in the buffer is displayed. The actual
  time span saved when you hit “capture” will be slightly less than what is shown because
  we have to start the output on a sync frame, which are configured to appear once per second.
• Output is a video-only MP4 file (“constant-capture.mp4”). Video is always 1280x720, which
  usually matches what the camera provides; if it doesn’t, the recorded video will have the
  wrong aspect ratio.

Double decode. Decodes two video streams side-by-side to a pair of TextureViews.

• Plays the two auto-generated videos. Note they play at different rates.
• The video decoders don’t stop when the screen is rotated. We retain the SurfaceTexture
  and just attach it to the new TextureView. Useful for avoiding expensive codec reconfigures.
  The decoders do stop if you leave the activity, so we don’t tie up hardware codec
  resources indefinitely. (It also doesn’t stop if you turn the screen off with the power
  button, which isn’t good for the battery, but might be handy if you’re feeding an external
  display or your player also handles audio.)
• Unlike most activities in Grafika, this provides different layouts for portrait and landscape.
  The videos are scaled to fit.

Hardware scaler exerciser. Shows GL rendering with on-the-fly surface size changes.

• The motivation behind the feature this explores is described in a developer blog post:
  http://android-developers.blogspot.com/2013/09/using-hardware-scaler-for-performance.html
• You will see one frame rendered incorrectly when changing sizes. This is because the
  render size is adjusted in the “surface changed” callback, but the surface’s size doesn’t
  actually change until we latch the next buffer. This is straightforward to fix (left as
  an exercise for the reader).

Live camera (TextureView). Directs the camera preview to a TextureView.

• This comes more or less verbatim from the TextureView documentation.
• Uses the default (rear-facing) camera. If the device has no default camera (e.g.
  Nexus 7 (2012)), the Activity will crash.

Multi-surface test. Simple activity with three overlapping SurfaceViews, one marked secure.

• Useful for examining HWC behavior with multiple static layers, and
  screencap / screenrecord behavior with a secure surface. (If you record the screen one
  of the circles should be missing, and capturing the screen should just show black.)
• If you tap the “bounce” button, the circle on the non-secure layer will animate. It will
  update as quickly as possible, which may be slower than the display refresh rate because
  the circle is rendered in software. The frame rate will be reported in logcat.

Play video (SurfaceView). Plays the video track from an MP4 file.

• Works very much like “Play video (TextureView)”, though not all features are present.
  See the class comment for a list of advantages to using SurfaceView.

Record GL app. Simultaneously draws to the display and to a video encoder with OpenGL ES, using framebuffer objects to avoid re-rendering.

• It can write to the video encoder three different ways: (1) draw twice; (2) draw offscreen and
  blit twice; (3) draw onscreen and blit framebuffer. #3 doesn’t work yet.
• The renderer is trigged by Choreographer to update every vsync. If we get too far behind,
  we will skip frames. This is noted by an on-screen drop counter and a border flash. You
  generally won’t see any stutter in the animation, because we don’t skip the object
  movement, just the render.
• The encoder is fed every-other frame, so the recorded output will be ~30fps rather than ~60fps
  on a typical device.
• The recording is letter- or pillar-boxed to maintain an aspect ratio that matches the
  display, so you’ll get different results from recording in landscape vs. portrait.
• The output is a video-only MP4 file (“fbo-gl-recording.mp4”).

Record Screen using MediaProjectionManager.
Records the screen to a movie using the MediaProjectionManager. This API
requires API level 23 (Marshmallow) or greater.

Scheduled swap. Exercises a SurfaceFlinger feature that allows you to submit buffers to be displayed at a specific time.

• Requires API 19 (Android 4.4 “KitKat”) to do what it’s supposed to. The current implementation
  doesn’t really look any different on API 18 to the naked eye.
• You can configure the frame delivery timing (e.g. 24fps uses a 3-2 pattern) and how far
  in advance frames are scheduled. Selecting “ASAP” disables scheduling.
• Use systrace with tags sched gfx view --app=com.android.grafika to observe the effects.
• The moving square changes colors when the app is unhappy about timing.

Show + capture camera. Attempts to record at 720p from the front-facing camera, displaying the preview and recording it simultaneously.

• Use the record button to toggle recording on and off.
• Recording continues until stopped. If you back out and return, recording will start again,
  with a real-time gap. If you try to play the movie while it’s recording, you will see
  an incomplete file (and probably cause the play movie activity to crash).
• The recorded video is scaled to 640x480, so it will probably look squished. A real app
  would either set the recording size equal to the camera input size, or correct the aspect
  ratio by letter- or pillar-boxing the frames as they are rendered to the encoder.
• You can select a filter to apply to the preview. It does not get applied to the recording.
  The shader used for the filters is not optimized, but seems to perform well on most devices
  (the original Nexus 7 (2012) being a notable exception). Demo
  here: http://www.youtube.com/watch?v=kH9kCP2T5Gg
• The output is a video-only MP4 file (“camera-test.mp4”).

Simple Canvas in TextureView. Exercises software rendering to a TextureView with a Canvas.

• Renders as quickly as possible. Because it’s using software rendering, this will likely
  run more slowly than the “Simple GL in TextureView” activity.
• Toggles the use of a dirty rect every 64 frames. When enabled, the dirty rect extends
  horizontally across the screen.

Simple GL in TextureView. Demonstates simple use of GLES in a TextureView, rather than a GLSurfaceView.

• Renders as quickly as possible. On most devices it will exceed 60fps and flicker wildly,
  but in 4.4 (“KitKat”) a bug prevents the system from dropping frames.

Texture from Camera. Renders Camera preview output with a GLES texture.

• Adjust the sliders to set the size, rotation, and zoom. Touch anywhere else to center
  the rect at the point of the touch.

Color bars. Displays RGB color bars.

OpenGL ES Info. Dumps version info and extension lists.

• The “Save” button writes a copy of the output to the app’s file area.

glTexImage2D speed test. Simple, unscientific measurement of the time required to upload a 512x512 RGBA texture with glTexImage2D().

glReadPixels speed test. Simple, unscientific measurement of the time required for glReadPixels() to read a 720p frame.

Known issues

• Nexus 4 running Android 4.3 (JWR67E): “Show + capture camera” crashes if you select one of
  the filtered modes. Appears to be a driver bug (Adreno “Internal compiler error”).

Feature & fix ideas

In no particular order.

• Stop using AsyncTask for anything where performance or latency matters.
• Add a “fat bits” viewer for camera (single SurfaceView; left half has live camera feed
  and a pan rect, right half has 8x pixels)
• Change the “Simple GL in TextureView” animation. Or add an epilepsy warning.
• Cross-fade from one video to another, recording the result. Allow specification of
  the resolution (maybe QVGA, 720p, 1080p) and generate appropriately.
• Add features to the video player, like a slider for random access, and buttons for
  single-frame advance / rewind (requires seeking to nearest sync frame and decoding frames
  until target is reached).
• Convert a series of PNG images to video.
• Play continuous video from a series of MP4 files with different characteristics. Will
  probably require “preloading” the next movie to keep playback seamless.
• Experiment with alternatives to glReadPixels(). Add a PBO speed test. (Doesn’t seem
  to be a way to play with eglCreateImageKHR from Java.)
• Do something with ImageReader class (req API 19).
• Figure out why “double decode” playback is sometimes janky.
• Add fps indicator to “Simple GL in TextureView”.
• Capture audio from microphone, record + mux it.
• Enable preview on front/back cameras simultaneously, display them side-by-side. (This
  appears to be impossible except on specific devices.)
• Add a test that renders to two different TextureViews using different EGLContexts
  from a single renderer thread.