Motor resource properties

Name

ggiGA_motor_props : Motor resource properties

#include <ggi/ga_prop.h>

struct ggiGA_motor_props {

      /* All units as per the GA_COORDBASE* bits set in 
       * the common .flags member. 
       */

      /* When positioned and sized on the screen, some features must 
       * be positioned and sized on a snap grid.
       */
      ggi_coord pos_snap;     /* Size of grid for positioning */
      ggi_coord size_snap;    /* Size of grid for sizing */
      ggi_coord grid_start;   /* Upper left of the snap grid */
      ggi_coord grid_size;    /* Size of the snap grid */

      /* For resources that support pixeldoubling/scaling or for 
       * overlay windows that drive the DAC directly, these 
       * define the available scaling factors.
       */
      ggi_coord mul_min, mul_max;     /* dot double, triple, etc. */
      ggi_coord div_min, div_max;     /* Sub-dot resolution (scan windows) */

      /* Available raster operations e.g. XOR with current screen data. */
      uint32_t rops;
};

Description

A motor resource is a chipset feature that moves data (hence the name). As such, the properties used by motor resources all involve limits and attributes concerning what capabilities the motor has to move/position the data. Motor properties area accessible through the union member sub.motor in the resource properties structure. The common properties member qty will usually refer to the number of simultaneous objects that can be positioned/moved by the motor. The common properties members storage_ok and storage_need are reserved for future use.

The Snap Grid

Most motor resources allow you to position something on the screen, but many have limitations about where on the screen you are able to position that something. The snap grid defines the rules for positioning with a motor resource. The grid_start and grid_size members offer x,y coordinates within which the motor can position things.

In addition, some motors can only place things on a grid (for example, it might place things at 0,0 or 10,0 or 0,10 or 10,10 or 0,20 but not at 3,5 or any other location whose coordinates are not divisible by 10.) This is a lot like the snap-to-grid feature in many common desktop publishing programs.

The pos_snap member defines x and y snap intervals, and if they are set to values other than 1, attempting to position the resource at coordinates off the snap grid will result in your coordinates being rounded to the nearest grid snap point. Likewise, there is a size_snap member which tells you if the motor has similar restrictions when it is resizing something.

Sub-Pixel Accuracy and Scaling

Many motor resources have a different resolution than the main framebuffer, or the capability to scale things. In some cases, the motor is immune to the main framebuffer's double-scan and pixel-doubling settings, and is able to position and size with sub-pixel accuracy. Even further, some motors use an entirely different pixel clock which is gated into the CRTC when the raster beam is traversing the object defined by the motor resource, so sub dot accuracy is possible. In addition, many resources support their own pixel doubling or double-scan, allowing the motor to scale the object.

The scaling factors possible are defined by four vectors contained in the mul_min, mul_max, div_min, and div_max members. The base units that these members operate on are either known implicitly, or are determined by flags. The flag values 'GA_PIXEL_MODE' and 'GA_DOT_MODE' are provided for this purpose, and specify that the scaling factors apply to pixels or dots, respectively. It is important to note that the snap grid described in the last section uses units of '1/div_max' pixels or dots, as indicated by the presence of these flag values. Users will generally be sheilded from this fact by an API using integer pixel coordinates or fixed-point sub-pixel coordinates, but extension authors are advised to check their units after negotiating a motor.

See Also