library for cursors and mode setting
Egbert Eich
eich at pdx.freedesktop.org
Wed May 5 00:57:48 EST 2004
Jon,
The suggested API below has been designed mainly form an OpenGL programmers
point of view. There seem to be pieces missing from a mode setting standpoint.
Writing mode setting code is not easy. The stuff that is documented
in the specs consumes about 10 percent of your time. What is not
in documented provides the most grief. It would therefore be desireable
having to do this only once (Today we do it at least twice already-
in the Xserver and in the Linux kernel).
I would therefore *strongly recommend* we come up with a solution
that is usable everywhere: For everything that's interesteted in mode
setting both on Linux and non-Linux OSes.
I would suggest to look at existing mode setting code both in the Xserver
and in the kernel and see what is required and I have a plan to do this
once I find the time.
Jon Smirl writes:
> At xdevconf we briefly discussed doing a library for cursors and mode setting.
> First, what do we want to call it? Second, I'll attach a preliminary design for
> this API that Brian Paul did. What does it need to be complete? For example it
> is missing color management.
Why do you want color management for mode setting? You can already set
colormaps. That's all you need.
>
> X must have a parallel API, what is it, or is it scattered in hundreds of
> places?
No, most of this is reflected in the driver API. You may want to
look at xc/programs/Xserver/hw/xfree86/doc/DESIGN.
>
> Designing this API should help in determining what is needed in terms of device
> driver support.
>
To me the API below attempts to provide a description of the
capabilities of the hardware as we know it today. This was an apporach
that was used by XFree86 prior to version 4. It turned out to be a complete
failure. We ended up having to extend structures for features of individual
chipsets and had to deal with properties of these chipsets in code that
was ment to be generic.
The opposite approach was taken in version 4: The driver is the central
agent in charge of the initialization and determining which mode to select.
It is in charge of mapping a relatively stable set of supported X server
DIX/MI modes onto sets of widely differing chipset and driver capabilities.
This of course means that there is no mode setting API as the one
below exposed from the driver to the rest of the Xserver which describes
mode capabilities capabilities.
Egbert.
> =====
> Jon Smirl
> jonsmirl at yahoo.com
>
>
>
>
> __________________________________
> Do you Yahoo!?
> Win a $20,000 Career Makeover at Yahoo! HotJobs
> http://hotjobs.sweepstakes.yahoo.com/careermakeover /*
> * Platform independent OpenGL interface, with functions for:
> * - describing supported pixel formats
> * - allocating/managing image buffers
> * - allocating/managing visuals and drawing surfaces
> * - creating/managing rendering contexts
> * - setting dislay modes
> * - setting the cursor image/position
> * - monitor queries
> * - etc...
> */
>
> #ifndef IGL_H
> #define IGL_H
>
>
> #define IGL_MAJOR_VERSION 0
> #define IGL_MINOR_VERSION 0
>
>
> /*
> * IGL datatypes
> */
> typedef char IGLchar;
> typedef char IGLbyte;
> typedef unsigned char IGLubyte;
> typedef short IGLshort;
> typedef unsigned short IGLushort;
> typedef int IGLint;
> typedef unsigned int IGLuint;
> typedef float IGLfloat;
> typedef unsigned char IGLboolean;
> typedef unsigned int IGLenum;
> typedef unsigned int IGLbitfield;
>
>
> /*
> * IGL constants
> */
>
> /* boolean */
> #define IGL_FALSE 0x0
> #define IGL_TRUE 0x1
>
> /* pixel format channels */
> #define IGL_RED 0x1100
> #define IGL_GREEN 0x1101
> #define IGL_BLUE 0x1102
> #define IGL_ALPHA 0x1103
> #define IGL_LUMINANCE 0x1104
> #define IGL_CR_CB 0x1105
> #define IGL_CB_CR 0x1106
> #define IGL_COLOR_INDEX 0x1107
> #define IGL_DEPTH 0x1108
> #define IGL_STENCIL 0x1109
> #define IGL_AUX 0x1110
>
> /* pixel format datatypes */
> #define IGL_UNSIGNED_INT 0x1000
> #define IGL_INT 0x1001
> #define IGL_FLOAT 0x1002
>
> /* pixel format targets */
> #define IGL_FRAMEBUFFER_BIT 0x1
> #define IGL_TEXTURE_BIT 0x2
> #define IGL_PBUFFER_BIT 0x4
> #define IGL_POINTER_BIT 0x8
>
> /* display mode options */
> #define IGL_INTERLACED_BIT 0x8
>
> /* GetString targets */
> #define IGL_VERSION 0x1300
> #define IGL_VENDOR 0x1301
> #define IGL_EXTENSIONS 0x1302
> #define IGL_RENDERER 0x1303
> #define IGL_LAST_ERROR 0x1304
>
> /* memory map modes */
> #define IGL_READ_ONLY 0x1400
> #define IGL_WRITE_ONLY 0x1401
> #define IGL_READ_WRITE 0x1402
>
>
>
> /* limits */
> #define IGL_MAX_PIXEL_FORMAT_CHANNELS 4
> #define IGL_MAX_PIXEL_FORMATS_PER_VISUAL 16
>
>
> /**
> * IGLRect: for specifying clip rects.
> */
> typedef struct {
> IGLint x0, y0; /* inclusive */
> IGLint x1, y1; /* exclusive */
> } IGLRect;
>
>
> /**
> * IGLPixelFormat: describes arrangement of pixel bits for an image buffer.
> */
> typedef struct {
> IGLenum ChannelType; /* IGL_INT, IGL_UNSIGNED_INT, or IGL_FLOAT */
> IGLuint BitsPerPixel;
> IGLuint NumChannels;
> IGLenum ChannelName[IGL_MAX_PIXEL_FORMAT_CHANNELS];
> IGLuint ChannelSize[IGL_MAX_PIXEL_FORMAT_CHANNELS];
> IGLuint ChannelShift[IGL_MAX_PIXEL_FORMAT_CHANNELS];
> IGLbitfield Targets; /* or of IGL_FRAMEBUFFER/TEXTURE/PBUFFER_BIT */
> } IGLPixelFormat;
>
>
> /**
> * IGLVisual: describes a set of pixelformats for a drawing surface.
> * A typical visual will describe pixel formats for one or two color buffers,
> * a depth buffer, a stencil buffer, etc.
> */
> typedef struct {
> IGLuint NumPixelFormats;
> IGLPixelFormat Formats[IGL_MAX_PIXEL_FORMATS_PER_VISUAL];
> } IGLVisual;
>
>
> /**
> * IGLBuffer: an image buffer (pixels store color or Z or stencil, etc).
> * May be 1D, 2D or 3D (for textures).
> */
> typedef struct {
> IGLPixelFormat Format;
> IGLuint Width, Height, Depth;
> IGLbitfield Flags;
> IGLuint RowStride, ImageStride;
> void *Address; /* address in VRAM */
> void *MappedAddress; /* address in user space if mapped */
> } IGLBuffer;
>
>
> /**
> * IGLCanvas: a set of IGBuffers which composes a drawing surface
> * (one or more color buffers, depth buffers, stencil buffers, etc).
> */
> typedef struct {
> IGLVisual Visual;
> IGLBuffer Buffer[IGL_MAX_PIXEL_FORMATS_PER_VISUAL];
> IGLuint NumClipRects;
> IGLRect *ClipRects;
> } IGLCanvas;
>
>
> /**
> * IGLContext: a GL rendering context
> */
> typedef struct {
> IGLVisual Visual;
> IGLBuffer *CurrentBuffer;
> } IGLContext;
>
>
> /**********************************************************************
> * Pixel format functions.
> */
>
>
> /**
> * Query if the given pixel format is supported by all the specified targets.
> * <targets> is a bitmask of the IGL_FRAMEBUFFER_BIT, IGL_TEXTURE_BIT, and
> * IGL_PBUFFER_BIT bits.
> * \return IGL_TRUE if supported, IGL_FALSE otherwise.
> */
> extern IGLboolean
> iglIsSupportedPixelFormat(IGLbitfield targets,
> const IGLPixelFormat *pixelFormat);
>
> /**
> * Return array of pixel formats supported by all the specified targets.
> * \param targets is a bitmask of the IGL_FRAMEBUFFER_BIT, IGL_TEXTURE_BIT,
> * and IGL_PBUFFER_BIT bits.
> * \param maxResults indicates the maximum number of results to put into the
> * <pixelFormats> array.
> * \return number of pixel formats returned.
> */
> extern IGLuint
> iglGetSupportedPixelFormats(IGLbitfield targets,
> IGLuint maxResults, IGLPixelFormat *pixelFormats);
>
>
>
> /**********************************************************************
> * Screen functions.
> */
>
>
> /**
> * Return the number of screens supported by the device.
> * \return number of screens
> */
> extern IGLuint
> iglGetNumScreens(void);
>
> /**
> * Test if the given display mode is supported.
> * \param pixelFormat pixel format of display mode.
> * \param width width (in pixels) of display mode.
> * \param height height (in pixels) of display mode.
> * \param refreshRate refresh rate (in Hz) of display mode.
> * \param flags various options such as IGL_INTERLACED_BIT.
> * \return IGL_TRUE if suported, IGL_FALSE otherwise
> */
> extern IGLboolean
> iglIsSupportedDisplayMode(IGLuint screen, const IGLPixelFormat *pixelFormat,
> IGLuint width, IGLuint height, IGLuint refreshRate,
> IGLbitfield flags);
>
> /**
> * Set the current display mode (resolution, refresh, etc) for the given
> * screen.
> * \param pixelFormat pixel format of display mode.
> * \param width width (in pixels) of display mode.
> * \param height height (in pixels) of display mode.
> * \param refreshRate refresh rate (in Hz) of display mode.
> * \param flags various options such as IGL_INTERLACED_BIT.
> * \return IGL_TRUE if successful, IGL_FALSE otherwise
> */
> extern IGLboolean
> iglSetDisplayMode(IGLuint screen, const IGLPixelFormat *pixelFormat,
> IGLuint width, IGLuint height, IGLuint refreshRate,
> IGLbitfield flags);
>
> /**
> * Enable (scan-out) the given screen.
> */
> extern void
> iglEnableScreen(IGLuint screen);
>
> /**
> * Disable (turn off) the given screen.
> */
> extern void
> iglDisableScreen(IGLuint screen);
>
> /**
> * Specify the region of VRAM to display on the monitor.
> */
> extern IGLboolean
> iglSetScreenPointer(IGLuint screen, IGLuint start, IGLuint stride);
>
> /**
> * Wait for start of vertical retrace on given screen.
> * Return immediately if the screen is disabled.
> */
> extern void
> iglWaitRetrace(IGLuint screen);
>
>
>
> /**********************************************************************
> * Image buffer functions.
> */
>
> /**
> * Allocate an image buffer (might be color, depth, etc, 1D, 2D or 3D)
> * Initial buffer contents are undefined.
> * XXX will probably need more, similar functions for allocating
> * mipmapped textures.
> * \return new IGLBuffer pointer or NULL if we fail.
> */
> extern IGLBuffer *
> iglAllocateBuffer(IGLenum target, const IGLPixelFormat *pixelformat,
> IGLuint width, IGLuint height, IGLuint depth,
> IGLbitfield flags);
>
> /**
> * Deallocate the given image buffer.
> */
> extern void
> iglFreeBuffer(IGLBuffer *buffer);
>
> /**
> * Resize the given image buffer. The buffer contents after resize are
> * undefined.
> * \return IGL_TRUE if successful, IGL_FALSE otherwise
> */
> extern IGLboolean
> iglResizeBuffer(IGLBuffer *buffer,
> IGLuint width, IGLuint height, IGLuint depth);
>
> /**
> * Map the given image buffer into the caller's address space.
> * \param buffer the image buffer to map
> * \param access one of IGL_READ_ONLY, IGL_WRITE_ONLY, IGL_READ_WRITE.
> * \param size returns the size of the mapped region.
> * \return the mapped address or NULL if we fail.
> */
> extern void *
> iglMapBuffer(IGLBuffer *buffer, IGLenum access, IGLuint *size);
>
> /**
> * Unmap the given image buffer from the caller's address space.
> */
> extern void
> iglUnmapBuffer(IGLBuffer *buffer);
>
> /**
> * Bind the given image buffer as a texture image.
> * XXX tentative.
> */
> extern void
> iglBindTextureBuffer(IGLBuffer *buffer, IGLenum textureTarget,
> IGLuint textureID, IGLuint textureLevel);
>
>
>
> /**********************************************************************
> * Canvas functions.
> */
>
> /**
> * Allocate a new drawing canvas.
> * \param targets a bitmask of IGL_FRAMEBUFFER_BIT, IGL_TEXTURE_BIT,
> * and IGL_PBUFFER_BIT which indicates how the canvas
> * might be used.
> * A canvas that will also be used as a texture source would
> * specify IGL_TEXTURE_BIT | IGL_PBUFFER_BIT.
> * \return pointer to new IGLCanvas or NULL if we fail.
> */
> extern IGLCanvas *
> iglAllocateCanvas(IGLbitfield targets, const IGLVisual *visual,
> IGLuint width, IGLuint height, IGLuint depth,
> IGLbitfield flags);
>
> /**
> * Deallocate the given drawing canvas.
> */
> extern void
> iglFreeCanvas(IGLCanvas *canvas);
>
> /**
> * Resize the given canvas. The buffers' contents after resize are
> * undefined.
> * \return IGL_TRUE if successful, IGL_FALSE otherwise
> */
> extern void
> iglResizeCanvas(IGLCanvas *canvas,
> IGLuint width, IGLuint height, IGLuint depth);
>
> /**
> * Specify a list of clipping rectangles for rendering into the given
> * canvas.
> */
> extern void
> iglSetClipList(IGLCanvas *canvas, IGLuint numRects, const IGLRect *rectList);
>
>
>
> /**********************************************************************
> * Rendering context functions.
> */
>
> /**
> * Create a new OpenGL rendering context.
> */
> extern IGLContext *
> iglCreateContext(const IGLVisual *visual, IGLContext *shareList);
>
> /**
> * Destroy the given OpenGL rendering context.
> */
> extern void
> iglDestroyContext(IGLContext *context);
>
> /**
> * Bind the given rendering context to a read/draw canvas pair for the
> * calling thread.
> * Typically, readCanvas == drawCanvas.
> * \return IGL_TRUE if successful, IGL_FALSE otherwise.
> */
> extern IGLboolean
> iglMakeCurrent(IGLContext *context,
> IGLCanvas *readCanvas, IGLCanvas *drawCanvas);
>
> /**
> * Return the current IGLContext for the calling thread.
> * \return IGLContext pointer or NULL if no current context.
> */
> extern IGLContext *
> iglGetCurrentContext(void);
>
> /**
> * Return the current IGLCanvas for drawing for the calling thread.
> * \return IGLCanvas pointer or NULL if no current canvas.
> */
> extern IGLCanvas *
> iglGetCurrentDrawCanvas(void);
>
> /**
> * Return the current IGLCanvas for reading for the calling thread.
> * \return IGLCanvas pointer or NULL if no current canvas.
> */
> extern IGLCanvas *
> iglGetCurrentReadCanvas(void);
>
>
>
> /**********************************************************************
> * Misc functions.
> */
>
> /**
> * Initialize the IGL driver.
> * XXX any parameters???
> */
> extern void
> iglInitialize(void);
>
> /**
> * Return string information.
> * \param pname one of IGL_VERSION, IGL_VENDOR, IGL_EXTENSIONS, IGL_RENDERER,
> * or IGL_LAST_ERROR.
> * \return the string or NULL. If non-null the first and last characters
> * will be spaces.
> */
> extern IGLchar *
> iglGetString(IGLenum pname);
>
> /**
> * Return the address of any IGL or OpenGL function.
> */
> extern void *
> iglGetProcAddress(const char *functionName);
>
>
>
> /**********************************************************************
> * Cursor functions.
> */
>
> /**
> * Return max pointer/sprite size supported on given screen.
> */
> extern void
> iglGetMaxPointerSize(IGLuint screen, IGLuint *width, IGLuint *height);
>
> /**
> * Set the pointer/sprite image for the given screen.
> */
> extern void
> iglPointerImage(IGLuint screen, IGLuint width, IGLuint height,
> const IGLPixelFormat *format, const void *image);
>
> /**
> * Show/Hide the pointer/sprite on given screen.
> */
> extern void
> iglShowPointer(IGLuint screen, IGLboolean visible);
>
> /**
> * Set pointer/sprite's current position.
> */
> extern void
> iglPointerPosition(IGLuint screen, IGLint x, IGLint y);
>
>
>
> /**********************************************************************
> * Colormap (palette) functions.
> */
>
> /**
> * Specify the colormap to use for the given screen when scanning
> * out color indexed framebuffers.
> * \param screen
> * \param type datatype of colormap values: IGL_UNSIGNED_BYTE, etc
> * \param components number of components per colortable entry
> * \param size number of colortable entries (typically 256)
> * \param colormap the colormap values
> */
> extern void
> iglSetColormap(IGLuint screen, IGLenum type, IGLuint components,
> IGLuint size, const IGLvoid *colormap);
>
>
>
> /**********************************************************************
> * XXX to be determined functions:
> * - monitor info / DDC?
> * - DMA negotiation?
> */
>
>
>
>
> #endif /* IGL_H */
> _______________________________________________
> xserver mailing list
> xserver at freedesktop.org
> http://freedesktop.org/mailman/listinfo/xserver
More information about the xserver
mailing list