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 GenvidEventsListener 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*/)
{
    if (!summary->isFinal)
    {
        // Ignoring partial results.
        return;
    }
    if (summary->id == sEvent_changeColor)
    {
        for (int resultIdx = 0; resultIdx < summary->numResults; ++resultIdx)
        {
            // Change the color of the cube.
            std::string cubeName  = summary->results[resultIdx].key.fields[0];
            const char* cubeColor = summary->results[resultIdx].key.fields[1];
            // Finding the cube and change the color
            std::cout << "color change received " << cubeName << std::endl;

            auto color = ConvertStringToColor(cubeColor);
            if (color != nullptr)
            {
                auto cube = g_cubes.find(cubeName);
                if (cube != g_cubes.end())
                {
                    cube->second.SetColor(*color);
                    std::cout << "color changed for " << cubeName << std::endl;
                }
            }
        }
        OnUpdateColor();
    }
    else if (summary->id == sEvent_reset)
    {
        for (int resultIdx = 0; resultIdx < summary->numResults; ++resultIdx)
        {
            // Reset the cube position.
            std::string cubeName = summary->results[resultIdx].key.fields[0];
            auto        cube     = g_cubes.find(cubeName);
            if (cube != g_cubes.end())
            {
                cube->second.ResetPosition();
            }
        }
    }
    else if (summary->id == sEvent_cheer)
    {
        for (int resultIdx = 0; resultIdx < summary->numResults; ++resultIdx)
        {
            // Handle cube cheering.
            std::string cubeName = summary->results[resultIdx].key.fields[0];
            auto        cube     = g_cubes.find(cubeName);
            if (cube != g_cubes.end())
            {
                // GENVID - Get cheer min value.
                cube->second.Cheer(float(summary->results[resultIdx].values[0].value));
                // GENVID - Cheer value set.
            }
        }
    }
}

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.

Important

The event filtering system is stateless once it transmits results it wipes and resets all data to zero.

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.

            std::string cubeName  = summary->results[resultIdx].key.fields[0];
            const char* cubeColor = summary->results[resultIdx].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.

                cube->second.Cheer(float(summary->results[resultIdx].values[0].value));