h6. [[Hardware Abstraction Layer]] h6(. [[HAL entry points from RISC OS]] h6((. » HAL_VideoUpdatePointer h2. HAL_VideoUpdatePointer h5. (HAL entry #46) <pre> int HAL_VideoUpdatePointer(uint flags, int x, int y, const shape_t *shape) </pre> |_<. Entry | | |/3^. flags |Bit 0 = Pointer display enable (0=off, 1=on) | |Bit 1 = Pointer shape update (0=no change, 1=updated) | |Bits 2..31 reserved (0) | |xpos |X position of top left of pointer (xpos = 0 for left of display) | |ypos |Y position of top left of pointer (ypos = 0 for top of display) | |shape |shape_t descriptor block (see below) | |_<. Exit | | |0 |Request was not handled by hardware pointer | |Non-zero |Request was handled by hardware pointer | h4. Use This is an internal call for OS use only and should not be used by user software. User software should use [[GraphicsV]] instead of interacting with the HAL directly. _shape_ points to shape_t descriptor block: <pre> typedef struct shape_t { uint8 width; /* unpadded width in bytes (see notes) */ uint8 height; /* in pixels */ uint8 padding[2]; /* 2 bytes of padding for field alignment */ void *buffLA; /* logical address of buffer holding pixel data */ void *buffPA; /* corresponding physical address of buffer */ } </pre> Notes: # If _flags_ bit 0 is 0 (pointer off), _x_, _y_, _shape_ are undefined # The shape data from RISC OS is always padded with transparent pixels on the rhs, to a width of 32 pixels (8 bytes) # Pointer clipping is the responsibility of the HAL (eg. may be able to allow display of pointer in border region on some h/w) # Buffer for pixel data is aligned to a multiple of 256 bytes or better The HAL may need to take note of the shape updated flag, and make its own new copies if true. This is to handle cases like dual scan LCD pointer, which typically needs two or more shape buffers for the hardware, or possibly to handle clipping properly. This work should only be done when the updated flag is true. A simple HAL, where hardware permits, can use the shape data in the buffer directly, ignoring the updated flag. The OS guarantees that the buffer data is valid for the whole time it is to be displayed. The return value is used to indicate to the OS whether the software pointer is needed or not. If [[HAL_VideoFeatures]] indicates that the hardware pointer is not supported, and this function returns zero, then the OS will render a software pointer instead. This allows for situations where the hardware pointer can only be displayed in some portions of the screen (the HAL must take care to disable the hardware pointer when it moves into an area in which it cannot be displayed). h4. See also * [[HAL Video API]] h6. Information source: Kernel.Docs.HAL.HAL_API in CVS