Added ImagePipe

mojo/services/gfx/images/interfaces/image_pipe.mojom

+// Copyright 2016 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.
+
+module mojo.gfx;
+
+import "geometry/interfaces/geometry.mojom";
+import "gfx/images/interfaces/image.mojom";
+
+//The status of the last time this image was presented
+enum PresentationStatus {
+  PRESENTED = 0,
+  //Image properties are not supported by the consumer (this is not neccessarily

[jeffbrown, 2016/03/03 23:09:58]

style nit: space after //

[Forrest Reiling, 2016/03/04 21:04:28]

Done.

+  // an error, as these properties could have changed after the image was added)
+  NOT_PRESENTED_INVALID_PROPERTIES,

[jeffbrown, 2016/03/03 23:09:58]

assign explicit values to each one

[Forrest Reiling, 2016/03/04 21:04:28]

Done.

+  //Producer flushed the image pool
+  NOT_PRESENTED_FLUSHED,
+};
+
+//ImagePipe is a collection of semantics for streaming shared images between two

[jeffbrown, 2016/03/03 23:09:58]

nit: ImagePipe is a mechanism for streaming...

[Forrest Reiling, 2016/03/04 21:04:28]

Done.

+//Mojo entities, one of which provides the image contents (the 'producer') and
+//one of which does something with the image contents (the 'consumer').
+//It operates conceptually on a pool of image descriptors that the pipe knows

[jeffbrown, 2016/03/03 23:09:58]

Conceptually, it operates on a poll of |Image| objects...

[Forrest Reiling, 2016/03/04 21:04:28]

Done.

+//about, allows image producers to add/remove images to/from this pool, and
+//provides mechanisms for the producer and the consumer to negotiate about who
+//owns each image in the pool at a given point in time
+interface ImagePipe {
+
+  //Add an image persistently to the pipe's image pool
+  //Adding an image that is already added, or using an ID that is already in use
+  //are both errors and will cause the connection to terminate

[jeffbrown, 2016/03/03 23:09:58]

instead of terminate, say closed

[Forrest Reiling, 2016/03/04 21:04:28]

Done.

+  AddImage(Image image, uint32 id);

[jeffbrown, 2016/03/03 23:09:58]

AddImage(uint32 id, Image image);

[Forrest Reiling, 2016/03/04 21:04:28]

I'm skipping this one because I don't think it has any effect on the objective
quality of the code and it would take significant work to implement. Also, from
a completely subjective perspective, I think putting the Image first makes more
sense anyway because the image is the thing you're adding. Either way, this
function only has two arguments and they have different types, so even if you do
get it backwards the compiler will yell at you about it.

+
+  //Remove an image from the pipe's pool
+  //Use of an invalid ID will cause the connection to be terminated
+  RemoveImage(uint32 id);
+
+  //Mark the image as available for consumption by the consumer

[jeffbrown, 2016/03/03 23:09:58]

period at the end of each sentence (here and elsewhere)

[Forrest Reiling, 2016/03/04 21:04:28]

Done.

+  //The reply will be sent when the consumer is done using this image and
+  //is ready to release ownership back to the producer.
+  //The reply will not be sent until another Image is presented to replace it
+  //presentuing an id that is added will cause the connection to terminate
+  PresentImage(uint32 id) => (uint32 id, PresentationStatus status);

[jeffbrown, 2016/03/03 23:27:49]

remove the returned id, the caller should just bind the id into the callback on
its side

[Forrest Reiling, 2016/03/04 21:04:28]

Done.

+
+  //Ask the consumer to release all images in the pipe's pool
+  //this will send the presentation reply with FLUSHED on all images in the pool
+  //not being used by the consumer if the consumer is presenting this image,
+  //that image may still be presented and its Present reply will reflect that
+  FlushImages();
+
+  //Get supported propertied for images added to this pipe
+  //The reply to this method will only be sent when the values change compared

[jeffbrown, 2016/03/03 23:09:58]

So what's interesting is that this is the Producer asking the Consumer what
kinds of images it wants.  I think perhaps that if the Consumer wants to start
receiving Images with a new size or properties, it should ask the Producer out
of band to do that.

eg. MGLResize / glResizeCHROMIUM

But if the Consumer is communicating that out of band, then the Producer
shouldn't have to ask for the information through this interface at all.  So
perhaps the only thing we need to push through SupportedImageProperties is the
format (not the size).

We could perhaps even get rid of this method altogether.

[Forrest Reiling, 2016/03/04 21:04:28]

Removing as per our discussion

+  //to the last time they were sent (immediately for the first time they are
+  //called), so to listen for continuous updates call this method immediately
+  //after recieving the reply
+  GetSupportedImageProperties() => (SupportedImageProperties supported_properties);
+};