ppapi_simple

native_client_sdk/src/libraries/ppapi_simple/ppapi_event.h

+// Copyright (c) 2013 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+
+#ifndef PPAPI_SIMPLE_PPAPI_EVENT_H_
+#define PPAPI_SIMPLE_PPAPI_EVENT_H_
+
+#include "ppapi/c/pp_bool.h"
+#include "ppapi/c/pp_resource.h"
+#include "ppapi/c/pp_var.h"
+
+#include "utils/macros.h"
+
+EXTERN_C_BEGIN
+
+
+
+/**
+ * PSEvent
+ *
+ * The PSEvent system provides a lock-less in-order event processing mechanism.

[nfullagar1, 2013/05/23 21:58:36]

remove lock-less

[noelallen1, 2013/05/24 18:08:31]

Done.

+ * As Pepper events such as input, or focus and view changes arive on the,

[binji, 2013/05/23 18:06:49]

sp: arrive

[binji, 2013/05/23 18:06:49]

remove , after the

[noelallen1, 2013/05/23 22:01:24]

Done.

[noelallen1, 2013/05/23 22:01:24]

Done.

+ * main pepper thread, they are placed on various FIFOs based on event type.
+ * For any given event type, only a single thread will process those events.
+ *
+ * By default, the "EventThread" will receive all messages.  However any thread
+ * can call PSRequestEventsType to request that all new events of that type
+ * are placed on that particular thread's Q.

[binji, 2013/05/23 18:06:49]

s/Q/queue/

[noelallen1, 2013/05/23 22:01:24]

Done.

+ *
+ * This allows the developer to choose which threads handle which event types
+ * while keeping all events belonging to a particular thread in order.  This
+ * is useful, for example, in the case of graphics to synchronize the size
+ * of the graphics context, with mouse clicks to correctly interpret location.
+ */
+
+
+typedef enum {
+  PS_NO_EVENTS = 0,      // Mask off all events
+  PS_MESSAGE_EVENT = 1,  // From HandleMessage, contains a PP_Var
+  PS_VIEW_EVENT    = 2,  // From DidChangeView, contains a view resource
+  PS_INPUT_EVENT   = 4,  // From HandleInputEvent, conatins an input resource
+  PS_FOCUS_EVENT   = 8,  // Focus change, contains a PP_Bool
+  PS_LOST_EVENT = 16,    // When the 3D context is lost, no resource.

[binji, 2013/05/23 18:06:49]

PS_LOST_EVENT is a bit generic, maybe PS_3D_LOST_EVENT

[noelallen1, 2013/05/23 22:01:24]

Done.

+  PS_LOCK_EVENT = 32,    // When the mouse lock is lost.

[binji, 2013/05/23 18:06:49]

same, maybe PS_MOUSELOCK_LOST_EVENT?

[noelallen1, 2013/05/23 22:01:24]

Done.

+  PS_ALL_EVENTS = -1,    // Enable all events
+} PSEventType;
+
+
+// Generic Event
+typedef struct {
+  PSEventType type_;

[binji, 2013/05/23 18:06:49]

event type is a bitmask, but are we ensured that type_ only has 1 bit set?

[noelallen1, 2013/05/23 22:01:24]

The PostEvent functions verify that type_ is an expected value for the data
associated with it.

+  union {
+    PP_Bool bool_;

[binji, 2013/05/23 18:06:49]

which union members are matched to which event types?

[noelallen1, 2013/05/23 22:01:24]

In the comments above by the event type enum.  Seemed redundant to have it here
as well.

+    PP_Resource resource_;
+    struct PP_Var var_;
+  };
+} PSEvent;
+
+
+/**
+ * Function for queuing, acquiring, and releasing events.
+ */
+PSEvent* PSCreateEvent();
+PSEvent* PSAcquireEvent(int block);
+void PSReleaseEvent(PSEvent* event);
+void PSSetEventFilter(uint32_t);
+
+/**
+ * PSPostEvent
+ *
+ * Creates and adds an event of the specified type to the event queue if
+ * that event type is not currently filtered.
+ */
+void PSPostEvent(PSEventType type);
+void PSPostBoolEvent(PSEventType type, PP_Bool state);
+void PSPostVarEvent(PSEventType type, struct PP_Var var);
+void PSPostResourceEvent(PSEventType type, PP_Resource resource);
+
+EXTERN_C_END
+
+#endif  // PPAPI_SIMPLE_PPAPI_EVENT_H_
+