Merge lp://staging/~dandrader/frame/backend into lp://staging/frame

This is a great start! With a few changes we will hopefully be good to go :).

* The Doxygen comments for functions should have an extra newline between the summary and the extra description. The following function comments should be updated:
  frame_event_set_device()
  frame_device_add_axis()

* I would rather namespace the backend functions so they are clearly distinct from the frontend functions. For example, frame_device_new() should be frame_backend_device_new(), and frame_device_get_frontend() could be frame_backend_device_get_device().

* UFBackendDevice_ isn't an invariant because it is not fully initialized after the constructor returns. The constructor could be UFBackendDevice_(oif::frame::UFDevice* device), where the shared_ptr is initialized with the value of device. Then frame_backend_device_new() could simply be:

UFBackendDevice frame_device_new()
{
  return new UFBackendDevice_(new oif::frame::UFDevice);
}

This holds for UFBackendFrame and UFBackendTouch as well.

* Why can't we infer the number of axes from the number of added axes, rather than by having to manually set the value. The same for number of touches in the frame.

The simple fix would be to get the current value, increment it, then reinsert it into the device or frame when an axis or touch is added. The number of active touches would be set to the same value as the number of touches in the frame. The caller would need to set the total number of active touches *after* all frame touches have been added. A sanity check that the number of active touches is greater than or equal to the number of frame touches would be good.

* I understand how events are created, but how are they enqueued to a frame instance? How are devices added to a frame instance?

> * Why can't we infer the number of axes from the number of added axes, rather
> than by having to manually set the value. The same for number of touches in
> the frame.

Because it's inefficient. If you add 10 items you will redefine the counter property 10 times.

It also hides the fact that number_of_foo is just a property that can be set independently from the entities they refer to. Besides, the idea of the backend interface is to enable the user to manually and directly build frame data as they will, to feed grail. No real logic expected here. All responsibility is in the hands of the user. The equivalent of a header defining some structs.

> * I understand how events are created, but how are they enqueued to a frame
> instance? How are devices added to a frame instance?

There's no need for a frame instance if you're using the backend interface. The whole point is that you manually create frame events to feed them to grail (through grail_process_frame_event). In that sense, libframe is reduced to being just a header defining some data containers that grail understands.

> * I would rather namespace the backend functions so they are clearly distinct
> from the frontend functions. For example, frame_device_new() should be
> frame_backend_device_new(), and frame_device_get_frontend() could be
> frame_backend_device_get_device().

Makes all the sense.
I was striving for shorter function names. :)

Updated according to comments (expect for auto-setting "count" properties)

* The frame_backend_device_delete() doxygen comment is a bit wonky, since it's one sentence split up for the summary and extended detail. It just needs to be slightly fixed up wording-wise.

* Daniel and I chatted on IRC about fixing up how the number of device axes and number of touches in a frame are calculated and reported. Those will be fixed in this proposal as well.

> * The frame_backend_device_delete() doxygen comment is a bit wonky, since it's
> one sentence split up for the summary and extended detail. It just needs to be
> slightly fixed up wording-wise.

Yeah, that was a mistake. Autopilot was on when that happened.

>
> * Daniel and I chatted on IRC about fixing up how the number of device axes
> and number of touches in a frame are calculated and reported. Those will be
> fixed in this proposal as well.

Done.

* In frame_device_get_property(), the value parameter should be reinterpret_cast'd instead of static_cast'd. The same is true for frame_frame_get_property(). Casts from void* to a concrete pointer should always be reinterpret casted (according to thumper).

* frame_frame_get_property_unsigned_int_() has an erroneously added empty line at the top.

Everything else looks good. I'm approving based on these changes. Great stuff!