What is a MirRenderSurface?

[Kevin DuBois]

Two ways to answer this question make sense to me:

1) A MirRenderSurface is an EGLNativeWindowType
2) A MirRenderSurface is a mf::BufferStreamId (ie, it is the token
representing server-side)

We currently seem to be saying that MirRenderSurface are both. [1]

(crux of my point)
Given that there exists software, vulkan, multimedia, and
nested-passthrough, it doesn't make sense to me to answer that "A
MirRenderSurface is 1) AND 2)", because all of those technologies don't
care about EGL.
We shouldn't make an assumption that the user will be using EGL, because we
have clients who specifically want a place to draw without having anything
to do with EGL.

So, given that, I wrote up how the headers would look if we decide
MirRenderSurface is an EGLNativeWindowType or if we decide MirRenderSurface
is a mf::BufferStreamId. I attached a sketch of the headers to this mail,
and also catted the contents to pastebin
<http://pastebin.ubuntu.com/23146845/>. [2]

I think first we have to agree that the answer is "1) OR 2)" instead of "1)
AND 2)".
Both versions of the headers make sense from the client's perspective,
although we should go back-and-forth on the merits of both approaches of
course, once we've figured out what MirRenderSurface is.

Thanks,
Kevin

[1]
In the last version of the headers that I've seen, we have a conversion to
a MirBufferStream (ie, MirRenderSurface is a mf::BufferStreamId) here
<http://bazaar.launchpad.net/%7Ecemil-azizoglu/mir/mir-render-surface-v3/view/head:/src/include/client/mir_toolkit/mir_render_surface.h#L55>,
and we have an implicit conversion here
<http://bazaar.launchpad.net/%7Ecemil-azizoglu/mir/mir-render-surface-v3/view/head:/playground/eglflash_render_surface.c#L112>
(ie, MirRenderSurface is also a EGLNativeWindowType)

P.S.
Topic has come up in discussions here:
https://code.launchpad.net/~cemil-azizoglu/mir/use_egl_native_window/+merge/304726
and the WIP branch here:
https://code.launchpad.net/~cemil-azizoglu/mir/mir-render-surface-v3/+merge/304536

P.P.S
We also discussed a bit about client vs driver interfaces. I think
answering this mail is the primary topic, and will send a follow up mail to
make sure we're on the same page about the different technologies/semantics
going on.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/mir-devel/attachments/20160907/17ad61ad/attachment.html>
-------------- next part --------------
//Option 2:
//MirRenderSurface represents a mf::BufferStreamId to the user. It is the content that
//you can add to the user.
//
//Creating a MirRenderSurface is effectively negotiating with the server for a mf::BufferStreamId,
//so there are sync and async versions.
//
//The 3 semantics we provide (EGL, MirPresentationChain, MirBufferStream) take MirRenderSurface
//as a parameter they're constructed from, and we don't have to negotiate anything with the server to
//use the MirRenderSurface in accordance with the semantics of the chosen object.
//
//We can just have a function to add content to MirSurfaceSpec.

MirRenderSurface* mir_connection_create_render_surface_sync(MirConnection* connection);
MirWaitHandle* mir_connection_create_render_surface(
    MirConnection* connection);

MirPresentationChain* mir_render_surface_create_presentation_chain(
    MirRenderSurface* render_surface);

MirBufferStream* mir_render_surface_create_buffer_stream(
    MirRenderSurface* render_surface,
    int physical_width, int physical_height,
    MirPixelFormat const format);

EGLNativeWindowType mir_render_surface_create_eglnativewindowtype(
    MirRenderSurface* render_surface,
    int physical_width, int physical_height,
    void *egldisplay, void* eglconfig); //see mir_connection_get_pixel_format()

void mir_surface_spec_add_render_surface(
    MirSurfaceSpec* spec,
    int onscreen_width, int onscreen_height,
    int displacement_x, int displacement_y,
    MirRenderSurface* render_surface);
-------------- next part --------------
//Option 1:
//MirRenderSurface is effectively just EGLNativeWindowType for users.
//  (and we could probably s/MirRenderSurface/EGLNativeWindowType)
//
//MirRenderSurface is NOT the same concept to the client user as the resource
//represented by mf::BufferStreamId. That resource is hidden from the users.
//
//Since we're hiding that we're negotiating a mf::BufferStreamId from the
//user, all 3 content semantics (EGLNativeWindowType, MirPresentationChain, MirBufferStream)
//have sync and async functions. All 3 need a function to be added to MirSurfaceSpec.

//mir_render_surface.h
MirRenderSurface* mir_connection_create_render_surface(
    MirConnection* connection,
    int const width, int const height,
    MirPixelFormat const format);

bool mir_render_surface_is_valid(
    MirRenderSurface* render_surface);

void mir_surface_spec_add_render_surface(
    MirSurfaceSpec* spec,
    int scaled_width, int scaled_height,
    int displacement_x, int displacement_y,
    MirRenderSurface* render_surface);

//mir_presentation_chain.h
MirPresentationChain* mir_connection_create_presentation_chain_sync(
    MirConnection* connection);

void mir_connection_create_presentation_chain(
    MirConnection* connection,
    mir_presentation_chain_callback callback,
    void* context);

void mir_surface_spec_add_presentation_chain(
    MirSurfaceSpec* spec,
    int width, int height,
    int displacement_x, int displacement_y,
    MirPresentationChain* chain);

//mir_buffer_stream.h
MirWaitHandle* mir_connection_create_buffer_stream(MirConnection *connection,
    int width, int height,
    MirPixelFormat format,
    MirBufferUsage buffer_usage,
    mir_buffer_stream_callback callback,
    void* context);

MirBufferStream* mir_connection_create_buffer_stream_sync(MirConnection *connection,
    int width, int height,
    MirPixelFormat format,
    MirBufferUsage buffer_usage);

void mir_surface_spec_add_buffer_stream(
    MirSurfaceSpec* spec,
    int displacement_x, int displacement_y,
    MirBufferStream* stream);