motorcar.xml

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="motorcar">
	<interface name="motorcar_shell" version="1">
		<description summary="a 3D compositor shell">
	      	An interface to allow a copositor to composite 3D data from multiple clients
	      	in a manner that makes it appear to be in the same 3D space. Combined with
	      	embedding tradtional wayland surfaces on quads in the same space it provides the 
	      	framework needed to achieve a seamless mixture of 2D and 3D user interfaces while 
	      	still giving clients full flexibility in how their content is drawn to 2D

      		It allows clients to associate a motorcar_surface with a basic surface, which
      		both tells the compositor to perform 3D compositing on the client surface, and also
      		provides a mechanism for the compositor to give the client the information it needs to draw
      		its content to 2D correctly.
   		</description>


	    <request name="get_motorcar_surface">
	      <description summary="create a motorcar surface from a surface">
		 		Create a motorcar surface for an existing surface.

				Only one motorcar surface can be associated with a given surface.
	      </description>
	      <arg name="id" type="new_id" interface="motorcar_surface" summary="the id of the new motorcar surface to be created"/>
	      <arg name="surface" type="object" interface="wl_surface" summary="the wl_surface which the motorcar_surface is to be associated with"/>
	      <arg name="clipping_mode" type="uint" summary="the clipping mode to be used by the compositor for this  surface"/>
	      <arg name="enable_depth_compositing" type="uint" summary="boolean value indicating whether to use depth buffer compositing on this surface"/>
	    </request>
	</interface>

	<interface name="motorcar_surface" version="1">

	    <description summary="a 3D, view dependent, depth composited meta-data surface">
	      An interface that may be implemented by a wl_surface, for
	      implementations that provide motorcar style depth composited 3D surfaces

	      A motorcar_surface can be created from an exisitng surface, and provides the client
	      with the information needed to draw its content in a way that can be depth composited by
	      a motorcar compliant compositor.

	      A motorcar surface is handled in the compositor as a 3D analog of a traditional window. Rather than the window being a 2 dimensional region of a 2 dimensional interface space, the window represents a 3 dimensional region of a 3 dimensional interface space, essentially a 3D box in which the client can draw 3D geometry

	      The 3D window has its own 3D space whose origin is at the center of the window. The window's position refers to the location of this origin in the world space, and its rotation is around this point. The window also has a 3D size, which is defined in its local space. Each component of the size indicates one dimension of the window bounds, so the window extends for one half this distance on each side of the origin in its local space.
	    </description>


   		<enum name="clipping_mode">
	    	<description summary="clipping behavior used by the compositor for a surface">
	    		The compositor clips the fragments composing the 3D window to lie within its 3D window bounds.
	    		The behavior of this clipping mechanism depends on the type of 3D window being clipped. This
	    		compositor supports two clippling modes, called cuboid and portal clippling

	    		Cuboid clipping treats the 3D window as a box shaped region of the space (defined by the motorcar_surface size_3d)
	    		and clips any fragments which do not lie withing this box.

	    		Portal clipping treats the 3D window as a 2D opening which connects two disjoint 3D spaces, much like a 
	    		physical window. This drops any fragments which lie outside the projection of the window opening 
	    		(defined by the first two dimensions of the motorcar_surface size_3d) and any fragments which lie closer 
	    		to the viewpoint than the window opening 
	      	</description>
	      	<entry name="cuboid" value="0"
		    	summary="Use the cuboid clipping mode"/>
	     	<entry name="portal" value="1"
		    	summary="Use the portal clipping mode"/>
	    </enum>

	   	<event name="transform_matrix">
	      <description summary="sets the tranformation of the 3D window">
			This event is sent to indicate a change in the transform of the client's 3D window

			This matrix can be though of as the model matrix for the client's 3D window, which brings vectors from the window local space into world space. 

			It is represented here as a column-major 4x4 matrix of 32 bit floats, with all values are specified in meters.
	      </description>
	      <arg name="transform" type="array" summary="the new transform matrix"/>
	    </event>

	   	<event name="request_size_3d">
	      <description summary="requests that the client resize the 3D window to the given scale">
			Allows the compositor to request the window take a new size. Much like the traditional 2D size mechanisms, the compositor cannot set this explicitly, rather, it can only request that the client take a certain dimension, and the client then chooses any size which fits completely within the requested size and sends a resize event back to the compositor.

			The size is represented here as a vector of three 32-bit floats, representing the size of the 3D window along each of the cardinal axes in the window's local space.	
	      </description>
	      <arg name="dimensions" type="array" summary="the requested size vector"/>
	    </event>

	    <request name="set_size_3d">
	      <description summary="requests that the client resize the 3D window to the given scale">
			Sets the new size of the 3D window. If this size is larger than the size most recently requested by the compositor the compositor is free to clip the window to a new size, provided that it immediatly requests the client resize to those dimensions.

			The size is represented here as a vector of three 32-bit floats, representing the size of the 3D window along each of the cardinal axes in the window's local space.	
	      </description>
	      <arg name="dimensions" type="array" summary="the new size vector"/>
	    </request>


	</interface>

	<interface name="motorcar_viewpoint" version="1">
		<description summary="represents a single viewpoint in the compositor, essentially a view and projection matrix">
	      This interface represents a viewpoint (essentially a virtual camera) in the compositor's 3D compositing space, 
	      and the events it contains are designed to keep the compositor and client viewpoints synced so that the viewpoints 
	      in the client and compositor space stay consistent;

	    </description>

	    <event name="view_matrix">
	      <description summary="sets the view matrix of this viewpoint for the next frame">
			This event is sent (ideally) at the beginning of each frame to give the client the view
			matrix it needs to draw its content to 2D in the same manner as the compositor.

			This matrix is the view matrix, which brings vectors from world space into view (or camera) space, which is the inverse of the camera transform. 

			It is represented here as a column-major 4x4 matrix of 32 bit floats, with all values are specified in meters.	
	      </description>
	      <arg name="view" type="array" summary="the view matrix for this frame"/>
	    </event>

	    <event name="projection_matrix">
	      <description summary="change the projection matrix of this viewpoint">
			This event is sent immediately after the viewpoint global is bound by the client, and is only resent if the projection
			matrix for this viewpoint changes in the compoisitor (which would be unusual but is certainly possible)

			This matrix is in the form of the projection matrices used by OpenGL, which (with the help of a homogeneous divide
			done in hardware) brings vectors from view space into uniform device coordinate space in which vertices are projected from
			3D to 2D. 

			It is represented here as a column-major 4x4 matrix of 32 bit floats, with all values are specified in meters.
	      </description>
	      <arg name="projection" type="array" summary="the new projection matrix for this viewpoint"/>
	    </event>

	    <event name="view_port">
	      <description summary="sets the view ports of this viewpoint to be used when rendering into motorcar surface buffers">
			This event tells the client where in its surface buffer it needs to draw the output associated with this viewpoint,
			which allows the compositor to extract the correct output for each viewpoint. Like the projection matrix, this event 
			is sent immediately after the client binds this viewpoint global and is only sent again if the viewport changes on the 
			compositor side.

			Viewport consists of a position and a size in surface local coordinates. Each viewpoint has two viewports associated with it,
			one to hold the color buffer from the client, and one to hold the depth buffer contents (which is encoded in the color buffer 
			since EGL does not support a color mode that includes depth). If an EGL extension was written which creates a format that includes
			the depth buffer, then the depth viewport could hypothetically be ignored when that extension was present.
	      </description>
	      <arg name="color_x" type="int" summary="x position of the color viewport, in pixels"/>
	      <arg name="color_y" type="int" summary="y position of the color viewport, in pixels"/>
	      <arg name="color_width" type="uint" summary="width of the color viewport, in pixels"/>
	      <arg name="color_height" type="uint" summary="height of the color viewport, in pixels"/>
	      <arg name="depth_x" type="int" summary="x position of the depth viewport, in pixels"/>
	      <arg name="depth_y" type="int" summary="y position of the depth viewport, in pixels"/>
	      <arg name="depth_width" type="uint" summary="width of the depth viewport, in pixels"/>
	      <arg name="depth_height" type="uint" summary="height of the depth viewport, in pixels"/>
	    </event>


	</interface>


	 <interface name="motorcar_six_dof_pointer" version="1">
    <description summary="six degree of freedom pointer input device">
      This interface represents a six degree of freedom pointing device which behaves much like a traditional pointing device except that 
      rather then event being associated with a 2D position they are associated with a 3D position and orientation, 
      represented as a 3-vector position and column major 3x3 rotation matrix as packed 32 bit float arrays (all values in meters).
      Most of the events are the same as the traditional wayaland pointer events other than this. 

      The motorcar_six_dof_pointer interface generates motion, enter and leave
      events for the surfaces that the six_dof pointer is located over,
      and button and axis events for button presses, button releases
      and scrolling.
    </description>

    <request name="release" type="destructor">
      <description summary="release the six_dof pointer object"/>
    </request>

    <event name="enter">
      <description summary="enter event">
		Notification that this seat's six_dof pointer is focused on a certain
		surface.
      </description>

      <arg name="serial" type="uint"/>
      <arg name="surface" type="object" interface="motorcar_surface"/>
      <arg name="position" type="array" summary="position of pointing device in meters at the time of this event, represented as a packed array of three 32 bit floats"/>
      <arg name="orientation" type="array" summary="orientation of the pointing device in meters at the time of this event, represented as a packed column major 3x3 rotation matrix of 32 bit floats"/>
    </event>

    <event name="leave">
      <description summary="leave event">
	Notification that this seat's six_dof pointer is no longer focused on
	a certain surface.

	The leave notification is sent before the enter notification
	for the new focus.
      </description>
      <arg name="serial" type="uint"/>
      <arg name="surface" type="object" interface="motorcar_surface"/>
    </event>

    <event name="motion">
      <description summary="six_dof pointer motion event">
		Notification of six_dof pointer location change. The arguments
		are the postion and orientation of the six_dof pointer device 
      </description>

      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
      <arg name="position" type="array" summary="position of pointing device in meters at the time of this event, represented as a packed array of three 32 bit floats"/>
      <arg name="orientation" type="array" summary="orientation of the pointing device in meters at the time of this event, represented as a packed column major 3x3 rotation matrix of 32 bit floats"/>
    </event>


    <event name="button">
      <description summary="pointer button event">
		Mouse button click and release notifications.

		The location of the click is given by the last motion or
		enter event.
        The time argument is a timestamp with millisecond
        granularity, with an undefined base.
      </description>

      <arg name="serial" type="uint"/>
      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
      <arg name="button" type="uint"/>
      <arg name="state" type="uint"/>
    </event>

 
  </interface>

</protocol>