Event Consumption

Events are meant to be interpreted inside the game process. You first need to subscribe to specific events, then poll for outstanding events at regular interval, and finally handle any received data however you see fit.

Subscription

To receive the results of the filtering step, the game uses Genvid_Subscribe() to subscribe to the output of a reduce rule using the rule’s id value.

    gs = Genvid_Subscribe(sEvent_changeColor.c_str(), &GenvidSubscriptionCallback, nullptr);
    if (GENVID_FAILED(gs))
        return E_FAIL;
    gs = Genvid_Subscribe(sEvent_reset.c_str(), &GenvidSubscriptionCallback, nullptr);
    if (GENVID_FAILED(gs))
        return E_FAIL;
    gs = Genvid_Subscribe(sEvent_cheer.c_str(), &GenvidSubscriptionCallback, nullptr);
    if (GENVID_FAILED(gs))
        return E_FAIL;

For Unity, you should use the GenvidEvents prefab.

For Unreal, you should use the blueprint UGenvidEvents.

This subscription tells the system to send the reduce result associated with the id to the callback assigned.

This callback must follow the appropriate definition assigned during the subscription process using the GenvidEventSummaryCallback format.

For Unity, this definition is EventSummaryCallback.

For Unreal, this definition is FOnGenvidEvent.

During the execution

During the execution of the application, you need to make sure to call Genvid_CheckForEvents() at a regular interval to verify if any events are received.

For Unity, this call is handled by the prefab.

For Unreal, this call is handled by the blueprint.

Once it is executed, the callback assigned in the subscription step will be called.

//--------------------------------------------------------------------------------------
// Callback invoked when Genvid Events are received.
//--------------------------------------------------------------------------------------
void GenvidSubscriptionCallback(const GenvidEventSummary * summary, void * /*userData*/)
{
    std::cout << "color change received" << std::endl;
    if (summary->id == sEvent_changeColor)
    {
        // Change the color of the cube.
        const char * cubeName  = summary->results[0].key.fields[0];
        const char * cubeColor = summary->results[0].key.fields[1];
        // Finding the cube and change the color
        std::cout << "color change received " << cubeName << std::endl;
        for (int i = 0; i < g_cubeTotal; ++i)
        {
            if (g_cubeList[i].GetName() == cubeName)
            {
                std::map<std::string, XMFLOAT4>::iterator colorToFind = sNameToColor.find(cubeColor);
                if (colorToFind != sNameToColor.end())
                {
                    g_cubeList[i].SetColor(colorToFind->second);
                    std::cout << "color changed for " << cubeName << std::endl;
                }
            }
        }
        OnUpdateColor();
    }
    else if (summary->id == sEvent_reset)
    {
        // Reset the cube position.
        const char * cubeName = summary->results[0].key.fields[0];
        for (int i = 0; i < g_cubeTotal; ++i)
        {
            if (g_cubeList[i].GetName() == cubeName)
            {
                g_cubeList[i].ResetPosition();
                return;
            }
        }
    }
    else if (summary->id == sEvent_cheer)
    {
        // Handle cube cheering.
        const char * cubeName = summary->results[0].key.fields[0];
        for (int i = 0; i < g_cubeTotal; ++i)
        {
            if (g_cubeList[i].GetName() == cubeName)
            {
                // GENVID - Get cheer min value.
                g_cubeList[i].Cheer(float(summary->results[0].values[0].value));
                // GENVID - Cheer value set.
                return;
            }
        }
    }
}

The callback will receive a structure containing the summary of your event. This structure is a GenvidEventSummary.

For Unity, it will be an EventSummary.

For Unreal, it will be an FGenvidEventSummary.

Note: The event filtering system is memory-less once it transmits results it wipes and resets all data.

Event structure content

In this structure, you need to access the data to know what are the viewers interactions. This data is contained in a layered structure level which we explain in details in this section.

First structure level

id: This id corresponds to the event id you used during the subscription step. This information is useful when you associate multiple events with the same callback like in the tutorial sample.

results: The results contains an array of GenvidEventResult.

For Unity, it will be an array of EventResult.

For Unreal, it will be an array of FGenvidEventResult.

This is where you are getting the key and value filtered through.

Second structure level - > Inside results

key: This is a structure GenvidEventKey.

For Unity, it will be a structure EventKey.

For Unreal, it will be a class FGenvidEventKey.

This is where you are getting the key of your event.

values: This is an array of GenvidEventValue.

For Unity, it will be an array of EventValue.

For Unreal, it will be an array of FGenvidEventValue.

This is where you retrieve the final value corresponding to your event.

Third structure level - > Inside results - > key

fields : This is an array of string containing all the keys associated for this event. In case that you associated multiple keys for an event, you will need to retrieve all the fields that you need.

        const char * cubeName  = summary->results[0].key.fields[0];
        const char * cubeColor = summary->results[0].key.fields[1];

Third structure level - > Inside results - > values

This is an array of 4 GenvidEventValue following the order of the enum GenvidReduceOp.

reduce: Enumerator corresponding to the GenvidReduceOp. Depending of the reduce that you want the value of, you can select the value that you need.

In this example, we use the first value in the array which is the minimum.

                g_cubeList[i].Cheer(float(summary->results[0].values[0].value));