X11 Extension tutorial - Revision history

imported_>amigadave: cut down to just a link

2010-06-14T08:47:48Z

cut down to just a link

← Older revision		Revision as of 08:47, 14 June 2010
Line 1:		Line 1:
	~~{{Midgard article}}~~		This tutorial was moved to http://www.x.org/wiki/X11_Extension_tutorial

	This tutorial briefly explains what an X11 extension is and how to implement one. Extensibility is a core requirement for a windowing system, and the X extension interface may be used to add new functionality to the X server, thereby fulfilling the extensibility requirement. The X extension interface depends upon functionality in the DDX (driver) itself.

	~~==Programming extensions==~~

	This tutorial was moved to http://www.x.org/wiki/X11_Extension_tutorial !

	[[Category:Development]]		[[Category:Development]]
	~~[[Category:Midgard wiki]]~~

imported_>lemody: /* Programming extensions */

2010-06-14T06:16:37Z

Programming extensions

@@ Line 5: / Line 5: @@
 ==Programming extensions==
-X extension code can be logically divided in 3 parts :
+This tutorial was moved to http://www.x.org/wiki/X11_Extension_tutorial !
 [[Category:Development]]
 [[Category:Midgard wiki]]

imported_>amigadave: use `and`


2010-06-03T13:02:03Z
use <code> and <source>

				
				
				
				
				
				← Older revision
				Revision as of 13:02, 3 June 2010
				
Line 14:
Line 14:
===Extension file structure in Kdrive=== ===Extension file structure in Kdrive===



Directory 'mi' contains the machine-independent library which is a set of common DDX routines. Initialization of server extensions is made by 'InitExtensions()' function found at 'xserver_root/mi/miinitext.c'. This file has to be changed in order to initialize extension on server startup. Other files that have to be changed in order to build and link the extension with X server are 'xserver_root/Makefile.am' and 'xserver_root/configure.ac'. Directory 'mi' contains the machine-independent library which is a set of common DDX routines. Initialization of server extensions is made by <code>InitExtensions()</code> function found in <code>xserver_root/mi/miinitext.c</code>. This file has to be changed in order to initialize extension on server startup. Other files that have to be changed in order to build and link the extension with X server are <code>xserver_root/Makefile.am</code> and <code>xserver_root/configure.ac</code>.



Extension itself should be located in a directory of it's own, for example 'xserver_root/sample'. This directory should be added to 'xserver_root/Makefile.am' SUBDIRS section. Figure below shows an example of extension directory structure. The client interface can be compiled anywhere else. Client interface is usually put in it's own directory under libs directory, which contains all other libraries X uses. Extension itself should be located in a directory of its own, for example <code>xserver_root/sample</code>. This directory should be added to <code>xserver_root/Makefile.am</code> SUBDIRS section. Figure below shows an example of extension directory structure. The client interface can be compiled anywhere else. Client interface is usually put in it's own directory under libs directory, which contains all other libraries X uses.



<pre> <pre>
Line 39:
Line 39:
The basic structure of request packet is predefined and every request must contain this 4-byte header information. After the header data, request can contain any amount of optional data limited only by the max packet size of the transport protocol. The basic structure of request packet is predefined and every request must contain this 4-byte header information. After the header data, request can contain any amount of optional data limited only by the max packet size of the transport protocol.



<pre> <source lang="c">
typedef struct _xReq { typedef struct _xReq {
   CARD8 reqType;            /* major opcode of request, allocated by server on extension initialization          */    CARD8 reqType;            /* major opcode of request, allocated by server on extension initialization          */
Line 46:
Line 46:
   ...    ...
} xReq; } xReq;
</source>



The structure skeleton of a request packet. All request structures must be multiple of 4 bytes long. The structure skeleton of a request packet. All request structures must be multiple of 4 bytes long.
</pre> 



<pre> <source lang="c">
typedef struct _xRep { typedef struct _xRep {
   CARD8 type;                  /* X_Reply                                */    CARD8 type;                  /* X_Reply                                */
Line 70:
Line 70:
} sample_data_reply; } sample_data_reply;
#define sz_sample_data_reply 32 #define sz_sample_data_reply 32
</source>
An example structure for reply packet returning data in form of 2 CARD16 variables. All reply packages must be at least 32 bytes. You also have to define a macro for returning size of the structure as <code>sz_<struct_name></code>. Server will use this macro to check package sizes (using macro <code>REQUEST_SIZE_MATCH</code>).



An example structure for reply packet returning data in form of 2 CARD16 variables. Every X extension has a <code>Dispatch()</code> function, which works as a request-handler. When X-server receives a request package, it will check the major opcode. If major opcode belongs to some extension it calls extension's Dispatch routine. Dispatch checks the minor opcode of request and returns a pointer to appropriate function to call or BadRequest in error situation. If protocol requires a reply packet, function will send a reply packet.
All reply packages must be at least 32 bytes. 
You also have to define a macro for returning size of the structure as 'sz_<struct_name>'. 
Server will use this macro to check package sizes (using macro REQUEST_SIZE_MATCH). 
</pre> 
  
Every X extension has a Dispatch() function, which works as a request-handler. When X-server receives a request package, it will check the major opcode. If major opcode belongs to some extension it calls extension's Dispatch routine. Dispatch checks the minor opcode of request and returns a pointer to appropriate function to call or BadRequest in error situation. If protocol requires a reply packet, function will send a reply packet. 



===Function wrapping=== ===Function wrapping===



imported_>sjgadsby: further revision of introductory paragraph
2009-03-19T15:08:50Z
further revision of introductory paragraph

				
				
				
				
				
				← Older revision
				Revision as of 15:08, 19 March 2009
				
Line 1:
Line 1:
{{Midgard article}} {{Midgard article}}



This tutorial briefly explains what an X11 extension is and how to implement one. Extensibility is a core requirement for a windowing system. The X extension interface may be used to add new functionality to the X server, thereby fulfilling the extensibility requirement for X11. The X extension interface depends upon functionality in the DDX (driver) itself. This tutorial briefly explains what an X11 extension is and how to implement one. Extensibility is a core requirement for a windowing system, and the X extension interface may be used to add new functionality to the X server, thereby fulfilling the extensibility requirement. The X extension interface depends upon functionality in the DDX (driver) itself.



==Programming extensions== ==Programming extensions==



imported_>sjgadsby: rewriting the introductory paragraph
2009-03-19T15:07:44Z
rewriting the introductory paragraph

				
				
				
				
				
				← Older revision
				Revision as of 15:07, 19 March 2009
				
Line 1:
Line 1:
{{Midgard article}} {{Midgard article}}



This tutorial briefly explains what is X11 extension and how to implement one. Extensibility is one of the requirements for a windowing system. X extension interface can be used to add new functionality to X server, it also requires additional functionality from the DDX (driver) itself. This tutorial briefly explains what an X11 extension is and how to implement one. Extensibility is a core requirement for a windowing system. The X extension interface may be used to add new functionality to the X server, thereby fulfilling the extensibility requirement for X11. The X extension interface depends upon functionality in the DDX (driver) itself.



==Programming extensions== ==Programming extensions==



imported_>dneary at 15:50, 11 June 2008
2008-06-11T15:50:43Z


				
				
				
				
				
				← Older revision
				Revision as of 15:50, 11 June 2008
				
Line 1:
Line 1:
{{Midgard article}}

This tutorial briefly explains what is X11 extension and how to implement one. Extensibility is one of the requirements for a windowing system. X extension interface can be used to add new functionality to X server, it also requires additional functionality from the DDX (driver) itself. This tutorial briefly explains what is X11 extension and how to implement one. Extensibility is one of the requirements for a windowing system. X extension interface can be used to add new functionality to X server, it also requires additional functionality from the DDX (driver) itself.



Line 82:
Line 84:



to be continued ... will contain more examples etc. (please send comments to [mailto:tapani.palli@nokia.com Tapani Palli] ) to be continued ... will contain more examples etc. (please send comments to [mailto:tapani.palli@nokia.com Tapani Palli] )


[[Category:Development]]
[[Category:Midgard wiki]]



70.242.115.107: /* Function wrapping */
2008-06-11T15:47:33Z
Function wrapping

				
				
				
				
				
				← Older revision
				Revision as of 15:47, 11 June 2008
				
Line 79:
Line 79:
===Function wrapping=== ===Function wrapping===



When adding and modifying functionality of normal DDX functions, extension has to wrap those functions. This means that extension will replace existing function with it's own version containing needed new functionality. X server calls all DDX functions through a function pointer and wrapping means switching of these pointers. Different extensions can wrap same functions, and depending on the order of extension initialization, they wrap each others functions. This will create a function chain. Wrapper function can call down to this function chain (it is recommended way, so that other extensions can do their work aswell unless you plan to replace larger part of the functionality but in this case you really have to know what you are doing). When adding and modifying functionality of normal DDX functions, extension has to wrap those functions. This means that extension will replace existing function with it's own version containing needed new functionality. X server calls all DDX functions through a function pointer and wrapping means switching of these pointers. Different extensions can wrap same functions, and depending on the order of extension initialization, they wrap each others functions. This will create a function chain. Wrapper function can call down to this function chain (it is recommended way, so that other extensions can do their work as well ''unless'' you plan to replace larger part of the functionality but in this case you really have to know what you are doing).



to be continued ... will contain more examples etc. (please send comments to [mailto:tapani.palli@nokia.com Tapani Palli] ) to be continued ... will contain more examples etc. (please send comments to [mailto:tapani.palli@nokia.com Tapani Palli] )



70.242.115.107: /* Function wrapping */
2008-06-11T15:45:58Z
Function wrapping

				
				
				
				
				
				← Older revision
				Revision as of 15:45, 11 June 2008
				
Line 81:
Line 81:
When adding and modifying functionality of normal DDX functions, extension has to wrap those functions. This means that extension will replace existing function with it's own version containing needed new functionality. X server calls all DDX functions through a function pointer and wrapping means switching of these pointers. Different extensions can wrap same functions, and depending on the order of extension initialization, they wrap each others functions. This will create a function chain. Wrapper function can call down to this function chain (it is recommended way, so that other extensions can do their work aswell unless you plan to replace larger part of the functionality but in this case you really have to know what you are doing). When adding and modifying functionality of normal DDX functions, extension has to wrap those functions. This means that extension will replace existing function with it's own version containing needed new functionality. X server calls all DDX functions through a function pointer and wrapping means switching of these pointers. Different extensions can wrap same functions, and depending on the order of extension initialization, they wrap each others functions. This will create a function chain. Wrapper function can call down to this function chain (it is recommended way, so that other extensions can do their work aswell unless you plan to replace larger part of the functionality but in this case you really have to know what you are doing).



to be continued ... will contain more examples etc. (please send comments to [mailto:tapani.palli@nokia.com] Tapani Palli) to be continued ... will contain more examples etc. (please send comments to [mailto:tapani.palli@nokia.com Tapani Palli] )



70.242.115.107: New page: This tutorial briefly explains what is X11 extension and how to implement one. Extensibility is one of the requirements for a windowing system. X extension interface can be used to add new...
2008-06-11T15:44:52Z
New page: This tutorial briefly explains what is X11 extension and how to implement one. Extensibility is one of the requirements for a windowing system. X extension interface can be used to add new...
New page
This tutorial briefly explains what is X11 extension and how to implement one. Extensibility is one of the requirements for a windowing system. X extension interface can be used to add new functionality to X server, it also requires additional functionality from the DDX (driver) itself.



==Programming extensions==



X extension code can be logically divided in 3 parts :

* protocol definition

* server side functional implementation

* library offering API for client programs



(+ additions to driver code to use extension)



===Extension file structure in Kdrive===



Directory 'mi' contains the machine-independent library which is a set of common DDX routines. Initialization of server extensions is made by 'InitExtensions()' function found at 'xserver_root/mi/miinitext.c'. This file has to be changed in order to initialize extension on server startup. Other files that have to be changed in order to build and link the extension with X server are 'xserver_root/Makefile.am' and 'xserver_root/configure.ac'.



Extension itself should be located in a directory of it's own, for example 'xserver_root/sample'. This directory should be added to 'xserver_root/Makefile.am' SUBDIRS section. Figure below shows an example of extension directory structure. The client interface can be compiled anywhere else. Client interface is usually put in it's own directory under libs directory, which contains all other libraries X uses.



<pre>

<xlibs_root>

         |

         |_ Sampleext (protocol header)

         |

         |_ Xsample (client interface)





<xserver_root> (Makefile.am, configure.ac)

           |

           |_ mi (miinitext.c)

           |

           |_ sample (extension files)

</pre>



===Protocol===



Protocol consists of requests, events, replies and error messages. These are sent between client and server. Example : client sends a request for server using the library provided by extension, extension-code on serverside processes this request and performs required action + sends a reply to client.



The basic structure of request packet is predefined and every request must contain this 4-byte header information. After the header data, request can contain any amount of optional data limited only by the max packet size of the transport protocol.



<pre>

typedef struct _xReq {

  CARD8 reqType;            /* major opcode of request, allocated by server on extension initialization          */

  CARD8 data;               /* undefined, usually used as 'minor opcode' by the extension to differiate requests */

  CARD16 length;            /* total length of request (including header) in 4 byte quantities                   */

  ...

} xReq;



The structure skeleton of a request packet. All request structures must be multiple of 4 bytes long.

</pre>



<pre>

typedef struct _xRep {

  CARD8 type;                  /* X_Reply                                */

  CARD8 pad1;                  /* can be anything, used for padding here */

  CARD16 sequenceNumber B16;   /* last sequence number                   */

  CARD32 length B32;           /* length of the reply                    */



  /* now the actual content ... */



  CARD16 data B16;             /* data                                   */

  CARD16 moredata B16;         /* some more data                         */



  CARD32 pad2 B32;             /* padding just to have 32B               */

  CARD32 pad3 B32;

  CARD32 pad4 B32;

  CARD32 pad5 B32;

  CARD32 pad6 B32;



} sample_data_reply;

#define sz_sample_data_reply 32



An example structure for reply packet returning data in form of 2 CARD16 variables.

All reply packages must be at least 32 bytes.

You also have to define a macro for returning size of the structure as 'sz_<struct_name>'.

Server will use this macro to check package sizes (using macro REQUEST_SIZE_MATCH).

</pre>



Every X extension has a Dispatch() function, which works as a request-handler. When X-server receives a request package, it will check the major opcode. If major opcode belongs to some extension it calls extension's Dispatch routine. Dispatch checks the minor opcode of request and returns a pointer to appropriate function to call or BadRequest in error situation. If protocol requires a reply packet, function will send a reply packet.



===Function wrapping===



When adding and modifying functionality of normal DDX functions, extension has to wrap those functions. This means that extension will replace existing function with it's own version containing needed new functionality. X server calls all DDX functions through a function pointer and wrapping means switching of these pointers. Different extensions can wrap same functions, and depending on the order of extension initialization, they wrap each others functions. This will create a function chain. Wrapper function can call down to this function chain (it is recommended way, so that other extensions can do their work aswell unless you plan to replace larger part of the functionality but in this case you really have to know what you are doing).



to be continued ... will contain more examples etc. (please send comments to [mailto:tapani.palli@nokia.com] Tapani Palli)

← Older revision		Revision as of 13:02, 3 June 2010
Line 14:		Line 14:
	===Extension file structure in Kdrive===		===Extension file structure in Kdrive===

	Directory 'mi' contains the machine-independent library which is a set of common DDX routines. Initialization of server extensions is made by 'InitExtensions()' function found ~~at '~~xserver_root/mi/miinitext.c'. This file has to be changed in order to initialize extension on server startup. Other files that have to be changed in order to build and link the extension with X server are 'xserver_root/Makefile.am' and 'xserver_root/configure.ac'.		Directory 'mi' contains the machine-independent library which is a set of common DDX routines. Initialization of server extensions is made by <code>InitExtensions()</code> function found in <code>xserver_root/mi/miinitext.c</code>. This file has to be changed in order to initialize extension on server startup. Other files that have to be changed in order to build and link the extension with X server are <code>xserver_root/Makefile.am</code> and <code>xserver_root/configure.ac</code>.

	Extension itself should be located in a directory of ~~it's~~ own, for example 'xserver_root/sample'. This directory should be added to 'xserver_root/Makefile.am' SUBDIRS section. Figure below shows an example of extension directory structure. The client interface can be compiled anywhere else. Client interface is usually put in it's own directory under libs directory, which contains all other libraries X uses.		Extension itself should be located in a directory of its own, for example <code>xserver_root/sample</code>. This directory should be added to <code>xserver_root/Makefile.am</code> SUBDIRS section. Figure below shows an example of extension directory structure. The client interface can be compiled anywhere else. Client interface is usually put in it's own directory under libs directory, which contains all other libraries X uses.

	<pre>		<pre>
Line 39:		Line 39:
	The basic structure of request packet is predefined and every request must contain this 4-byte header information. After the header data, request can contain any amount of optional data limited only by the max packet size of the transport protocol.		The basic structure of request packet is predefined and every request must contain this 4-byte header information. After the header data, request can contain any amount of optional data limited only by the max packet size of the transport protocol.

	<~~pre~~>		<source lang="c">
	typedef struct _xReq {		typedef struct _xReq {
	CARD8 reqType; /* major opcode of request, allocated by server on extension initialization */		CARD8 reqType; /* major opcode of request, allocated by server on extension initialization */
Line 46:		Line 46:
	...		...
	} xReq;		} xReq;
			</source>

	The structure skeleton of a request packet. All request structures must be multiple of 4 bytes long.		The structure skeleton of a request packet. All request structures must be multiple of 4 bytes long.
	~~</pre>~~

	<~~pre~~>		<source lang="c">
	typedef struct _xRep {		typedef struct _xRep {
	CARD8 type; /* X_Reply */		CARD8 type; /* X_Reply */
Line 70:		Line 70:
	} sample_data_reply;		} sample_data_reply;
	#define sz_sample_data_reply 32		#define sz_sample_data_reply 32
			</source>
			An example structure for reply packet returning data in form of 2 CARD16 variables. All reply packages must be at least 32 bytes. You also have to define a macro for returning size of the structure as <code>sz_<struct_name></code>. Server will use this macro to check package sizes (using macro <code>REQUEST_SIZE_MATCH</code>).

	~~An example structure for reply packet returning data in form of 2 CARD16 variables.~~		Every X extension has a <code>Dispatch()</code> function, which works as a request-handler. When X-server receives a request package, it will check the major opcode. If major opcode belongs to some extension it calls extension's Dispatch routine. Dispatch checks the minor opcode of request and returns a pointer to appropriate function to call or BadRequest in error situation. If protocol requires a reply packet, function will send a reply packet.
	~~All reply packages must be at least 32 bytes.~~
	~~You also have to define~~ a ~~macro for returning size of the structure as 'sz_~~<~~struct_name~~>'.
	~~Server will use this macro to check package sizes~~ (~~using macro REQUEST_SIZE_MATCH~~).
	</~~pre~~>

	~~Every X extension has a Dispatch()~~ function, which works as a request-handler. When X-server receives a request package, it will check the major opcode. If major opcode belongs to some extension it calls extension's Dispatch routine. Dispatch checks the minor opcode of request and returns a pointer to appropriate function to call or BadRequest in error situation. If protocol requires a reply packet, function will send a reply packet.

	===Function wrapping===		===Function wrapping===

← Older revision		Revision as of 15:08, 19 March 2009
Line 1:		Line 1:
	{{Midgard article}}		{{Midgard article}}

	This tutorial briefly explains what an X11 extension is and how to implement one. Extensibility is a core requirement for a windowing system~~. The~~ X extension interface may be used to add new functionality to the X server, thereby fulfilling the extensibility requirement ~~for X11~~. The X extension interface depends upon functionality in the DDX (driver) itself.		This tutorial briefly explains what an X11 extension is and how to implement one. Extensibility is a core requirement for a windowing system, and the X extension interface may be used to add new functionality to the X server, thereby fulfilling the extensibility requirement. The X extension interface depends upon functionality in the DDX (driver) itself.

	==Programming extensions==		==Programming extensions==

← Older revision		Revision as of 15:07, 19 March 2009
Line 1:		Line 1:
	{{Midgard article}}		{{Midgard article}}

	This tutorial briefly explains what is X11 extension and how to implement one. Extensibility is ~~one of the requirements~~ for a windowing system. X extension interface ~~can~~ be used to add new functionality to X server, ~~it also requires additional~~ functionality ~~from~~ the DDX (driver) itself.		This tutorial briefly explains what an X11 extension is and how to implement one. Extensibility is a core requirement for a windowing system. The X extension interface may be used to add new functionality to the X server, thereby fulfilling the extensibility requirement for X11. The X extension interface depends upon functionality in the DDX (driver) itself.

	==Programming extensions==		==Programming extensions==

← Older revision		Revision as of 15:50, 11 June 2008
Line 1:		Line 1:
			{{Midgard article}}

	This tutorial briefly explains what is X11 extension and how to implement one. Extensibility is one of the requirements for a windowing system. X extension interface can be used to add new functionality to X server, it also requires additional functionality from the DDX (driver) itself.		This tutorial briefly explains what is X11 extension and how to implement one. Extensibility is one of the requirements for a windowing system. X extension interface can be used to add new functionality to X server, it also requires additional functionality from the DDX (driver) itself.

Line 82:		Line 84:

	to be continued ... will contain more examples etc. (please send comments to [mailto:tapani.palli@nokia.com Tapani Palli] )		to be continued ... will contain more examples etc. (please send comments to [mailto:tapani.palli@nokia.com Tapani Palli] )


			[[Category:Development]]
			[[Category:Midgard wiki]]

← Older revision		Revision as of 15:47, 11 June 2008
Line 79:		Line 79:
	===Function wrapping===		===Function wrapping===

	When adding and modifying functionality of normal DDX functions, extension has to wrap those functions. This means that extension will replace existing function with it's own version containing needed new functionality. X server calls all DDX functions through a function pointer and wrapping means switching of these pointers. Different extensions can wrap same functions, and depending on the order of extension initialization, they wrap each others functions. This will create a function chain. Wrapper function can call down to this function chain (it is recommended way, so that other extensions can do their work ~~aswell~~ unless you plan to replace larger part of the functionality but in this case you really have to know what you are doing).		When adding and modifying functionality of normal DDX functions, extension has to wrap those functions. This means that extension will replace existing function with it's own version containing needed new functionality. X server calls all DDX functions through a function pointer and wrapping means switching of these pointers. Different extensions can wrap same functions, and depending on the order of extension initialization, they wrap each others functions. This will create a function chain. Wrapper function can call down to this function chain (it is recommended way, so that other extensions can do their work as well ''unless'' you plan to replace larger part of the functionality but in this case you really have to know what you are doing).

	to be continued ... will contain more examples etc. (please send comments to [mailto:tapani.palli@nokia.com Tapani Palli] )		to be continued ... will contain more examples etc. (please send comments to [mailto:tapani.palli@nokia.com Tapani Palli] )

← Older revision		Revision as of 15:45, 11 June 2008
Line 81:		Line 81:
	When adding and modifying functionality of normal DDX functions, extension has to wrap those functions. This means that extension will replace existing function with it's own version containing needed new functionality. X server calls all DDX functions through a function pointer and wrapping means switching of these pointers. Different extensions can wrap same functions, and depending on the order of extension initialization, they wrap each others functions. This will create a function chain. Wrapper function can call down to this function chain (it is recommended way, so that other extensions can do their work aswell unless you plan to replace larger part of the functionality but in this case you really have to know what you are doing).		When adding and modifying functionality of normal DDX functions, extension has to wrap those functions. This means that extension will replace existing function with it's own version containing needed new functionality. X server calls all DDX functions through a function pointer and wrapping means switching of these pointers. Different extensions can wrap same functions, and depending on the order of extension initialization, they wrap each others functions. This will create a function chain. Wrapper function can call down to this function chain (it is recommended way, so that other extensions can do their work aswell unless you plan to replace larger part of the functionality but in this case you really have to know what you are doing).

	to be continued ... will contain more examples etc. (please send comments to [mailto:tapani.palli@nokia.com] Tapani Palli)		to be continued ... will contain more examples etc. (please send comments to [mailto:tapani.palli@nokia.com Tapani Palli] )

X11 Extension tutorial - Revision history

imported_>amigadave: cut down to just a link

imported_>lemody: /* Programming extensions */

imported_>amigadave: use and

imported_>sjgadsby: further revision of introductory paragraph

imported_>sjgadsby: rewriting the introductory paragraph

imported_>dneary at 15:50, 11 June 2008

70.242.115.107: /* Function wrapping */

70.242.115.107: /* Function wrapping */

70.242.115.107: New page: This tutorial briefly explains what is X11 extension and how to implement one. Extensibility is one of the requirements for a windowing system. X extension interface can be used to add new...

imported_>amigadave: use `and`