Guides/Window Driver/gl2 Command Reference

From J Wiki
Jump to navigation Jump to search

2-D Graphics in J

gl2 commands draw 2-D graphics onto a form. Drawing is done inside isigraph and isidraw controls.

Graphics model

gl2 commands are defined in the jgl2 locale by ide/qt/gl2.ijs which is typically referenced using require'ide/qt/gl2'. The drawing commands, such as gltext and glrect, implicitly refer to previously-set state information, which includes:

  • current color, with components R, G, B, and A. The A value is opacity, with 0=transparent and 255=opaque. glrgb R,G,B sets A to 255 (opaque). When a pixel with opacity less than 255 is drawn, it is blended with the previous value at the pixel, with the component c being set to 
    (previous_c*(255-A)+new_c*A)/255
    • pixel values are given as one integer per pixel, in ARGB format, with B occupying the least-significant byte.
  • current pen-width
  • current brush-style
  • current color to use for text
  • current font to use for text
  • current xy position for text
  • current window origin, an xy pair that is added to the position of all drawn graphics.
  • current clip window. Drawing commands may range over the entire screen space; only pixels inside the clip window will be drawn.

Control of the drawing buffer

In isidraw controls, you may draw whenever you like, and you control the display of the drawn pixels by issuing glpaint'' or glpaintx'' to make the drawing buffer visible.

In isigraph controls, drawing to the screen is allowed only during the paint event for the control, and the drawing buffer is automatically made visible when that event completes. If the isigraph control is named g and it is in form abc, then the sentence abc_g_paint'' is called in the form's locale. You may issue glpaint'' to request a paint event; sources beyond your control, such as user actions, may also cause a paint event.

Drawing command coordinates are in pixels where 0 0 is the upper left corner and positive x and y values are to the right and down.

gl2 events allow user interaction with the drawing control, including keyboard and mouse, and window focus and resizing.

gl2 commands

glarc x y w h xa ya xz yz ; draw arc on the ellipse defined by rectangle. Arc starts at xa,ya and ends at xz,yz. Start and end points need not lie on the ellipse, they define a line from the center that intersects the ellipse.

glbrush '' ; select solid brush in current color (which was set by glrgb or glrgba)

glbrushnull '' ; select null brush (leaves area painted with it unchanged)

glcaret x y w h ; create a text caret at x,y with a width and height of w,h.

glclear '' ; Initialize drawing context: default system font; glrgb 0 0 0; glpen 1 0; glbrushnull''; gltextxy 0 0; gltextcolor''; glwindoworg 0 0 . Also, if the control is an isidraw, or an isigraph that is running its paint event, the drawing area is cleared to white. Performing glclear on an isigraph control outside of its paint event does not modify the drawing area.

glclip x y w h ; intersect this rectangle with the original clip rectangle to restrict drawing

glclipreset '' ; restore original clip rectangle

glcmds ... ; takes a series of gl2 commands. Each command starts with an integer count followed by the command and data. Commands that return results can not be used in glcmds. Character data is passed as integer values, one integer per character. The command code for glxxx is defined as glxxx_n in gl2.ijs which can be viewed with open 'gl2'. 

   glcmds 4 2056 100 100 6 2038 , a.i.'test' NB. gltextxy , gltext

glcursor n ; sets mouse cursor. Values are defined as IDC_... in gl2.ijs which can be viewed with open 'gl2'. (added in J804).

glellipse x y w h ; draw an ellipse in the rectangle with pen and brush

glfill r g b a ; fill with color. On J803, the alpha component a is ignored but should be set to 255 for compatibility with later versions.

glfont fontspec ; set font for all subsequent commands, see fontspec. The font set by glfont overwrites any font set by a previous glfont or glfontextent.

glfontextent fontspec ; set font for text-query commands (glqextent, glqextentw, glqtextmetrics) see fontspec.

gllines pts ; draw connected lines. pts is 0 or more points, each an x,y.

glnodblbuf b ; (not implemented) turns off double buffering (drawing to memory context). Drawing commands draw directly to the screen surface.

glpaint '' ; for isidraw: put an event into the Qt event queue that will, when executed, complete drawing by copying pixmap to screen. For isigraph: request a paint event.

glpaintx '' ; for isidraw: immediately complete drawing by copying pixmap to screen (normally required only when continuously updating a drawing). For isigraph: ignored.

glpen i [style] ; select pen. pen color is current color (which was set by glrgb or glrgba) and is (1 >. i) units wide. If you need a null pen for the border of a filled area, make sure the pen color is the same as the interior color. style is from the gl2.ijs PS_...

glpie x y w h xa ya xz yz ; draw pie shaped wedge with pen and brush. Same parameters as glarc.

glpixel i j ; draw pixel at i,j in current color

glpixels x y w h pixeldata ; pixeldata is an integer per pixel with ARGB values. ARGB values without a non-zero alpha (A) component will be invisible.

glpolygon pts ; draw polygon in pen and brush

glqextent text ; return width and height text. The font must have been set by glfont or glfontextent.

glqextentw texts ; return widths for LF delimited texts. The font must have been set by glfont or glfontextent.

glqhandles '' ; returns hwnd, 0, 0. Used in OpenGL support and probably should be restricted to that use.

glqpixels x y w h; return pixeldata as integer per pixel with ARGB values. This will not work during an isigraph paint event. If using an isigraph control, wait for a paint event to complete before calling it. The requested region must lie entirely within the screen.

glqpixelm x y w h; as glqpixels, except returns results as a table. The requested region must lie entirely within the screen.

glqtextmetrics '' ; return font information: Height, Ascent, Descent, InternalLeading, ExternalLeading, AverageCharWidth, MaxCharWidth

glqwh '' ; return width and height of the drawable area, in pixels

glrect x y w h ; draw rectangle with pen and brush. The rectangle is drawn using the current brush; then the outline is drawn atop the rectangle. The outline has width given by the width of the current pen (always at least 1), and is always solid regardless of the pen style. The minimum outline is 1 pixel and is drawn outside the rectangle; wider outlines are centered on that position.

glrgb r g b ; set current color (alpha is 255)

glrgba r g b a ; set current color with alpha

glsel id ; select isigraph child of currently selected parent for graphic commands

glsel hwndc ; hwndc is the result of wd'qhwndc' for an isigraph control. Parent and child are selected as the targets of subsequent wd and gl... commands.

gltext text ; write text in glfont and gltextcolor at gltextxy . gltext expects 8 bit characters, so you may need to use gltext 8 u: text if you are working with unicode text.

gltextcolor '' ; current color (which was set by glrgb or glrgba) is saved as color of text for subsequent gltext

gltextxy x y ; position for subsequent gltext

glwindoworg x y ; changes origin: that is, x,y are automatically added to subsequent command coordinates

Retrieved from "https://code.jsoftware.com/mediawiki/index.php?title=Guides/Window_Driver/gl2_Command_Reference&oldid=42577"