PTC for X documentation

 

Table of Contents

1. How to get the maximum out of PTC for X11

2. PTC's ways of addressing the screen in X11

2.1. Direct Graphics Access (DGA)

2.2. MIT Shared Memory Extension (MIT-Shm)

2.3. XImage

3. Options specific to the X version of PTC

3.1. Using Console::option



 

1. How to get the maximum out of PTC for X11

Here are a few short tips on how to get the maximum out of PTC for X11. If you stick to all of them you can get a 100% speed increase (this is NOT exaggerated!). The other way round, if you ignore them, you can lose half the speed of your application.
 



 

2. PTC's ways of addressing the screen in X11

PTC at the moment implements three different ways of accessing the screen which are totally transparent to you, the programmer (i.e. you don't have to worry which one is selected when you write your code). Before I explain what they mean, here is the order in which they are tried at runtime, the ones which are tried first are given priority because they are faster.

The different modes will be tried in the following order:

There are several reasons why DGA and MIT Shm can fail to initialise properly, and these will be presented in the respective sections. Again, the policy is to try the faster access modes first.
 
 

2.1. Direct Graphics Access(DGA)

DGA is an extension to the X protocol found, amongst others, in XFree86 servers. It allows direct writes to the frame buffer and thus it is quite fast. It is also the only way to get fullscreen access in X apart from stretching, which we really don't want ;)

For these reasons, PTC will try to open a DGA mode first. Due to the nature of DGA there are however quite a few restrictions:

All of these restrictions are due to the nature of the DGA extension, not to the way PTC is implemented. If you can't meet one of them, PTC will automatically fall back to the next lower level, which is MITShm.
 
 

2.2. MIT Shared Memory Extension (MIT-Shm)

This X server extension, present in most X servers (tested on SGI, Linux) on systems with shared memory capabilities allows PTC to store its images in a shared memory segment and to skip the Xlib IPC channel.

This is not much slower than DGA, maybe a tiny bit because the surface you use has to be copied twice (once to the image, then to the window), but of course it is not fullscreen. Then again, your application does not have to run with root permissions.

The only restriction of SHM is that it will not run over a network. For remote display, only the next method is applicable.
 
 

2.3. XImage

The last option in the chain. This is certainly much slower than the ones mentioned above. A normal XImage is created as an offscreen surface to draw into and is put into the window when update is called.

The already mentioned advantages: No access right restrictions and it runs over a network (which is quite slow for realtime graphics, but
this is about the concept :). Don't worry, though, this mode won't be entered on too many occasions at today's standard of X servers.
 


 

3. Options specific to the X version of PTC

Contrary to what's mentioned above, PTC is not completely transparent across all platforms. You do have control to some degree, otherwise it just wouldn't be flexible enough.

First of all, you can choose between a couple of Console::open routines that will allow you to do different things:

 
- Console::open(const char title[],int width,int height,const Format &format)

This is the standard routine. If will try and open a console of size width*height. First in DGA mode, then in MIT-Shm mode and then in XImage mode.
 

- Console::open(Display *disp,int screen,Window w,const Format &format)

Your next option. Suppose you already have a window open in your application and just want PTC to render into it. Pass your display pointer, your screen and the window - and of course the format you desire - to this open routine. PTC can then be used to render into this window. If you just want to draw into a part of your window, use the next routine.
 

- Console::open(Display *disp,int screen,Window window,const Format& format,int x,int y,int w,int h)

Create your own window and then use this to instruct PTC to draw into a part of that window. Nuff said.

Note that your window will be destroyed when PTC exits. Read the options below carefully if you want to continue using a window when PTC exists. Also look at the unix/ example.
 

3.1. Using Console::option

If you've used PTC X11 2.0.0 to 2.0.9 you might have noticed that the flags() routine is gone. There is a routine called option now which you can use to pass option strings to PTC. This allows PTC some more platform independence because platforms that do not support specific strings can just ignore them. PTC X11 will recognize the following: If you want an example now, just look into the unix/ example directory and see what Window.cc does.