Added Display increments, more controls, and a readme to the replayer

using namespace android;

BufferQueueScheduler::BufferQueueScheduler(

        const sp<SurfaceControl>& surfaceControl, const RGB& color, int id)

        const sp<SurfaceControl>& surfaceControl, const HSV& color, int id)

      : mSurfaceControl(surfaceControl), mColor(color), mSurfaceId(id), mContinueScheduling(true) {}

void BufferQueueScheduler::startScheduling() {

            bufferUpdate(event.dimensions);

            fillSurface(event.event);

            mColor.modulate();

            lock.lock();

            mBufferEvents.pop();

        }

}

void BufferQueueScheduler::setSurfaceControl(

        const sp<SurfaceControl>& surfaceControl, const RGB& color) {

        const sp<SurfaceControl>& surfaceControl, const HSV& color) {

    std::lock_guard<std::mutex> lock(mMutex);

    mSurfaceControl = surfaceControl;

    mColor = color;

    s->setBuffersDimensions(dimensions.width, dimensions.height);

}

void BufferQueueScheduler::fillSurface(std::shared_ptr<Event> event) {

void BufferQueueScheduler::fillSurface(const std::shared_ptr<Event>& event) {

    ANativeWindow_Buffer outBuffer;

    sp<Surface> s = mSurfaceControl->getSurface();

        return;

    }

    auto color = mColor.getRGB();

    auto img = reinterpret_cast<uint8_t*>(outBuffer.bits);

    for (int y = 0; y < outBuffer.height; y++) {

        for (int x = 0; x < outBuffer.width; x++) {

            uint8_t* pixel = img + (4 * (y * outBuffer.stride + x));

            pixel[0] = mColor.r;

            pixel[1] = mColor.g;

            pixel[2] = mColor.b;

            pixel[0] = color.r;

            pixel[1] = color.g;

            pixel[2] = color.b;

            pixel[3] = LAYER_ALPHA;

        }

    }

class BufferQueueScheduler {

  public:

    BufferQueueScheduler(const sp<SurfaceControl>& surfaceControl, const RGB& color, int id);

    BufferQueueScheduler(const sp<SurfaceControl>& surfaceControl, const HSV& color, int id);

    void startScheduling();

    void addEvent(const BufferEvent&);

    void stopScheduling();

    void setSurfaceControl(const sp<SurfaceControl>& surfaceControl, const RGB& color);

    void setSurfaceControl(const sp<SurfaceControl>& surfaceControl, const HSV& color);

  private:

    void bufferUpdate(const Dimensions& dimensions);

    // Lock and fill the surface, block until the event is signaled by the main loop,

    // then unlock and post the buffer.

    void fillSurface(std::shared_ptr<Event>);

    void fillSurface(const std::shared_ptr<Event>& event);

    sp<SurfaceControl> mSurfaceControl;

    RGB mColor;

    HSV mColor;

    const int mSurfaceId;

    bool mContinueScheduling;

namespace android {

typedef struct RGB {

    RGB() = default;

constexpr double modulateFactor = .0001;

constexpr double modulateLimit = .80;

struct RGB {

    RGB(uint8_t rIn, uint8_t gIn, uint8_t bIn) : r(rIn), g(gIn), b(bIn) {}

    uint8_t r = 0;

    uint8_t g = 0;

    uint8_t b = 0;

} RGB;

};

typedef struct HSV {

struct HSV {

    HSV() = default;

    HSV(double hIn, double sIn, double vIn) : h(hIn), s(sIn), v(vIn) {}

    double h = 0;

    double s = 0;

    double v = 0;

} HSV;

static inline RGB HSVToRGB(HSV hsv) {

    RGB getRGB() const;

    bool modulateUp = false;

    void modulate();

};

void inline HSV::modulate() {

    if(modulateUp) {

        v += modulateFactor;

    } else {

        v -= modulateFactor;

    }

    if(v <= modulateLimit || v >= 1) {

        modulateUp = !modulateUp;

    }

}

inline RGB HSV::getRGB() const {

    using namespace std;

    double r = 0, g = 0, b = 0;

    if (hsv.s == 0) {

        r = hsv.v;

        g = hsv.v;

        b = hsv.v;

    if (s == 0) {

        r = v;

        g = v;

        b = v;

    } else {

        hsv.h = static_cast<int>(hsv.h) % 360;

        hsv.h = hsv.h / 60;

        auto tempHue = static_cast<int>(h) % 360;

        tempHue = tempHue / 60;

        int i = static_cast<int>(trunc(hsv.h));

        double f = hsv.h - i;

        int i = static_cast<int>(trunc(tempHue));

        double f = h - i;

        double x = hsv.v * (1.0 - hsv.s);

        double y = hsv.v * (1.0 - (hsv.s * f));

        double z = hsv.v * (1.0 - (hsv.s * (1.0 - f)));

        double x = v * (1.0 - s);

        double y = v * (1.0 - (s * f));

        double z = v * (1.0 - (s * (1.0 - f)));

        switch (i) {

            case 0:

                r = hsv.v;

                r = v;

                g = z;

                b = x;

                break;

            case 1:

                r = y;

                g = hsv.v;

                g = v;

                b = x;

                break;

            case 2:

                r = x;

                g = hsv.v;

                g = v;

                b = z;

                break;

            case 3:

                r = x;

                g = y;

                b = hsv.v;

                b = v;

                break;

            case 4:

                r = z;

                g = x;

                b = hsv.v;

                b = v;

                break;

            default:

                r = hsv.v;

                r = v;

                g = x;

                b = y;

                break;

    std::cout << "  -m  Stops the replayer at the start of the trace and switches ";

                 "to manual replay\n";

    std::cout << "  -t [Number of Threads]  Specifies the number of threads to be used while "

    std::cout << "\n  -t [Number of Threads]  Specifies the number of threads to be used while "

                 "replaying (default is " << android::DEFAULT_THREADS << ")\n";

    std::cout << "\n  -s [Timestamp]  Specify at what timestamp should the replayer switch "

                 "to manual replay\n";

    std::cout << "  -n  Ignore timestamps and run through trace as fast as possible\n";

    std::cout << "  -l  Indefinitely loop the replayer\n";

    std::cout << "  -h  Display help menu\n";

    std::cout << std::endl;

int main(int argc, char** argv) {

    std::string filename;

    bool loop = false;

    bool wait = true;

    bool pauseBeginning = false;

    int numThreads = DEFAULT_THREADS;

    long stopHere = -1;

    int opt = 0;

    while ((opt = getopt(argc, argv, "pt:h?")) != -1) {

    while ((opt = getopt(argc, argv, "mt:s:nlh?")) != -1) {

        switch (opt) {

            case 'm':

                pauseBeginning = true;

            case 't':

                numThreads = atoi(optarg);

                break;

            case 's':

                stopHere = atol(optarg);

                break;

            case 'n':

                wait = false;

                break;

            case 'l':

                loop = true;

                break;

            case 'h':

            case '?':

                printHelpMenu();

    }

    filename.assign(input[0]);

    android::Replayer r(filename, pauseBeginning, numThreads);

    auto status = r.replay();

    status_t status = NO_ERROR;

    do {

        android::Replayer r(filename, pauseBeginning, numThreads, wait, stopHere);

        status = r.replay();

    } while(loop);

    if (status == NO_ERROR) {

        std::cout << "Successfully finished replaying trace" << std::endl;

SurfaceReplayer Documentation

===================

[go/SurfaceReplayer](go/SurfaceReplayer)

SurfaceReplayer is a playback mechanism that allows the replaying of traces recorded by

[SurfaceInterceptor](go/SurfaceInterceptor) from SurfaceFlinger. It specifically replays

* Creation and deletion of surfaces/displays

* Alterations to the surfaces/displays called Transactions

* Buffer Updates to surfaces

* VSync events

At their specified times to be as close to the original trace.

Usage

--------

###Creating a trace

SurfaceInterceptor is the mechanism used to create traces. The device needs to be rooted in order to

utilize it. To allow it to write to the device, run

`setenforce 0`

To start recording a trace, run

`service call SurfaceFlinger 1020 i32 1`

To stop recording, run

`service call SurfaceFlinger 1020 i32 0`

The default location for the trace is `/data/SurfaceTrace.dat`

###Executable

To replay a specific trace, execute

`/data/local/tmp/surfacereplayer /absolute/path/to/trace`

inside the android shell. This will replay the full trace and then exit. Running this command

outside of the shell by prepending `adb shell` will not allow for manual control and will not turn

off VSync injections if it interrupted in any way other than fully replaying the trace

The replay will not fill surfaces with their contents during the capture. Rather they are given a

random color which will be the same every time the trace is replayed. Surfaces modulate their color

at buffer updates.

**Options:**

- -m    pause the replayer at the start of the trace for manual replay

- -t [Number of Threads] uses specified number of threads to queue up actions (default is 3)

- -s [Timestamp] switches to manual replay at specified timestamp

- -n    Ignore timestamps and run through trace as fast as possible

- -l    Indefinitely loop the replayer

- -h    displays help menu

**Manual Replay:**

When replaying, if the user presses CTRL-C, the replay will stop and can be manually controlled

by the user. Pressing CTRL-C again will exit the replayer.

Manual replaying is similar to debugging in gdb. A prompt is presented and the user is able to

input commands to choose how to proceed by hitting enter after inputting a command. Pressing enter

without inputting a command repeats the previous command.

- n  - steps the replayer to the next VSync event

- ni - steps the replayer to the next increment

- c  - continues normal replaying

- c [milliseconds] - continue until specified number of milliseconds have passed

- s [timestamp]    - continue and stop at specified timestamp

- l  - list out timestamp of current increment

- h  - displays help menu

###Shared Library

To use the shared library include these shared libraries

`libsurfacereplayer`

`libprotobuf-cpp-full`

`libutils`

And the static library

`libtrace_proto`

Include the replayer header at the top of your file

`#include <replayer/Replayer.h>`

There are two constructors for the replayer

`Replayer(std::string& filename, bool replayManually, int numThreads, bool wait, nsecs_t stopHere)`

`Replayer(Trace& trace, ... ditto ...)`

The first constructor takes in the filepath where the trace is located and loads in the trace

object internally.

- replayManually - **True**: if the replayer will immediately switch to manual replay at the start

- numThreads - Number of worker threads the replayer will use.

- wait - **False**: Replayer ignores waits in between increments

- stopHere - Time stamp of where the replayer should run to then switch to manual replay

The second constructor includes all of the same parameters but takes in a preloaded trace object.

To use add

`#include <frameworks/native/cmds/surfacereplayer/proto/src/trace.pb.h>`

To your file

After initializing the Replayer call

    replayer.replay();

And the trace will start replaying. Once the trace is finished replaying, the function will return.

The layers that are visible at the end of the trace will remain on screen until the program

terminates.

**If VSyncs are broken after running the replayer** that means `enableVSyncInjections(false)` was

never executed. This can be fixed by executing

`service call SurfaceFlinger 23 i32 0`

in the android shell

Code Breakdown

-------------

The Replayer is composed of 5 components.

- The data format of the trace (Trace.proto)

- The Replayer object (Replayer.cpp)

- The synchronization mechanism to signal threads within the Replayer (Event.cpp)

- The scheduler for buffer updates per surface (BufferQueueScheduler.cpp)

- The Main executable (Main.cpp)

### Traces

Traces are represented as a protobuf message located in surfacereplayer/proto/src.

**Traces** contain *repeated* **Increments** (events that have occurred in SurfaceFlinger).

**Increments** contain the time stamp of when it occurred and a *oneof* which can be a

 - Transaction

 - SurfaceCreation

 - SurfaceDeletion

 - DisplayCreation

 - DisplayDeleteion

 - BufferUpdate

 - VSyncEvent

 - PowerModeUpdate

**Transactions** contain whether the transaction was synchronous or animated and *repeated*

**SurfaceChanges** and **DisplayChanges**

- **SurfaceChanges** contain an id of the surface being manipulated and can be changes such as

position, alpha, hidden, size, etc.

- **DisplayChanges** contain the id of the display being manipulated and can be changes such as

size, layer stack, projection, etc.

**Surface/Display Creation** contain the id of the surface/display and the name of the

surface/display

**Surface/Display Deletion** contain the id of the surface/display to be deleted

**Buffer Updates** contain the id of the surface who's buffer is being updated, the size of the

buffer, and the frame number.

**VSyncEvents** contain when the VSync event has occurred.

**PowerModeUpdates** contain the id of the display being updated and what mode it is being

changed to.

To output the contents of a trace in a readable format, execute

`**aprotoc** --decode=Trace \

-I=$ANDROID_BUILD_TOP/frameworks/native/cmds/surfacereplayer/proto/src \

$ANDROID_BUILD_TOP/frameworks/native/cmds/surfacereplayer/proto/src/trace.proto \

 < **YourTraceFile.dat** > **YourOutputName.txt**`

###Replayer

Fundamentally the replayer loads a trace and iterates through each increment, waiting the required

amount of time until the increment should be executed, then executing the increment. The first

increment in a trace does not start at 0, rather the replayer treats its time stamp as time 0 and

goes from there.

Increments from the trace are played asynchronously rather than one by one, being dispatched by

the main thread, queued up in a thread pool and completed when the main thread deems they are

ready to finish execution.

When an increment is dispatched, it completes as much work as it can before it has to be

synchronized (e.g. prebaking a buffer for a BufferUpdate). When it gets to a critical action

(e.g. locking and pushing a buffer), it waits for the main thread to complete it using an Event

object. The main thread holds a queue of these Event objects and completes the

corresponding Event base on its time stamp. After completing an increment, the main thread will

dispatch another increment and continue.

The main thread's execution flow is outlined below

    initReplay() //queue up the initial increments

    while(!pendingIncrements.empty()) { //while increments remaining

        event = pendingIncrement.pop();

        wait(event.time_stamp(); //waitUntil it is time to complete this increment

        event.complete() //signal to let event finish

        if(increments remaing()) {

            dispatchEvent() //queue up another increment

        }

    }

A worker thread's flow looks like so

    //dispatched!

    Execute non-time sensitive work here

    ...

    event.readyToExecute() //time sensitive point...waiting for Main Thread

    ...

    Finish execution

### Event

An Event is a simple synchronization mechanism used to facilitate communication between the main

and worker threads. Every time an increment is dispatched, an Event object is also created.

An Event can be in 4 different states:

- **SettingUp** - The worker is in the process of completing all non-time sensitive work

- **Waiting** - The worker is waiting on the main thread to signal it.

- **Signaled** - The worker has just been signaled by the main thread

- **Running** - The worker is running again and finishing the rest of its work.

When the main thread wants to finish the execution of a worker, the worker can either still be

**SettingUp**, in which the main thread will wait, or the worker will be **Waiting**, in which the

main thread will **Signal** it to complete. The worker thread changes itself to the **Running**

state once **Signaled**. This last step exists in order to communicate back to the main thread that

the worker thread has actually started completing its execution, rather than being preempted right

after signalling. Once this happens, the main thread schedules the next worker. This makes sure

there is a constant amount of workers running at one time.

This activity is encapsulated in the `readyToExecute()` and `complete()` functions called by the

worker and main thread respectively.

### BufferQueueScheduler

During a **BuferUpdate**, the worker thread will wait until **Signaled** to unlock and post a

buffer that has been prefilled during the **SettingUp** phase. However if there are two sequential

**BufferUpdates** that act on the same surface, both threads will try to lock a buffer and fill it,

which isn't possible and will cause a deadlock. The BufferQueueScheduler solves this problem by

handling when **BufferUpdates** should be scheduled, making sure that they don't overlap.

When a surface is created, a BufferQueueScheduler is also created along side it. Whenever a

**BufferUpdate** is read, it schedules the event onto its own internal queue and then schedules one

every time an Event is completed.

### Main

The main exectuable reads in the command line arguments. Creates the Replayer using those

arguments. Executes `replay()` on the Replayer. If there are no errors while replaying it will exit

gracefully, if there are then it will report the error and then exit.