h6. [[Hardware Abstraction Layer]] h6(. » [[List of HAL APIs]] h6((. » HAL Video API The HAL only attempts to abstract the hardware controller aspects of the OS video. It does not (yet) consider pixel formats, framestore layout, hardware graphics acceleration. All these would affect a great deal of RISC OS graphics code that forms much of the value of the OS. This means that the envisaged HAL/RISC OS combination makes some specific assumptions about graphics framestore layout as follows: * Memory mapped framestore * Expected to be contiguous physical memory, can be specific memory (eg. VRAM) * Mapped as contiguous logical memory * Progressive raster scan in logical memory from top left pixel to bottom right * Start of each raster row must be word aligned * Number of pixels in a row should be such that row is a whole number of words * Spacing between start of each row is a constant number of words, possibly greater than row length (via mode variable, LineLength) * 1,2,4,8,16 or 32 bits per pixel (bpp) * Little endian pixel packing for 1,2,4 bpp (least significant bits are leftmost pixels) * Presence of palette assumed for 1,2,4,8 bpp (8-bits per r,g,b component in each entry) * 16 bpp format: |_<. Bits |_<. Meaning | |0-4 |Red | |5-9 |Green | |10-14 |Blue | |15 |Supremacy (0=solid, 1=transparent) | * 32 bpp format: |_<. Bits |_<. Meaning | |0-7 |Red | |8-15 |Green | |16-23 |Blue | |24-31 |Supremacy (0=solid, 255=transparent) | * Palette words are 32 bits: |_<. Bits |_<. Meaning | |0-7 |Reserved (0), or Supremacy (0=solid, 255=transparent) | |8-15 |Red | |16-23 |Green | |24-31 |Blue | * Pointer/cursor is assumed supported in hardware, 32x32 pixels, each pixel either transparent or one of 3 paletted colours * Support for physically interlaced, logically progressive framestore via MMU tricks and use of LineLength mode variable, currently not fully integrated into kernel Note that it is possible to support hardware where only some pixel depths are available, or only some fit the RISC OS assumptions. Also some hardware has some configurability for 'arbitrary' choices like RGB versus BGR ordering. Hence, the restrictions are typically much less severe than might first be thought. Supporting a software only pointer/cursor is feasible (much less work than new pixel formats) but not yet considered. h4. Entry points Items marked ¶ are internal calls for OS use only; their functionality and availability is subject to change without warning. User programs interested in using these calls should instead use the equivalent RISC OS SWI call (if available). * [[HAL_VideoFlybackDevice]] ¶ * [[HAL_VideoSetMode]] ¶ * [[HAL_VideoWritePaletteEntry]] ¶ * [[HAL_VideoWritePaletteEntries]] ¶ * [[HAL_VideoReadPaletteEntry]] ¶ * [[HAL_VideoSetInterlace]] ¶ * [[HAL_VideoSetBlank]] ¶ * [[HAL_VideoSetPowerSave]] ¶ * [[HAL_VideoUpdatePointer]] ¶ * [[HAL_VideoSetDAG]] ¶ * [[HAL_VideoVetMode]] ¶ * [[HAL_VideoPixelFormats]] ¶ * [[HAL_VideoFeatures]] ¶ * [[HAL_VideoBufferAlignment]] ¶ * [[HAL_VideoOutputFormat]] ¶ * [[HAL_VideoRender]] ¶ * [[HAL_VideoIICOp]] ¶ * [[HAL_VideoFramestoreAddress]] ¶ * [[HAL_VideoStartupMode]] ¶ * [[HAL_VideoPixelFormatList]] ¶ h2. Integration with GraphicsV Starting with RISC OS 5.21, on startup the OS will issue a call to [[HAL_VideoPixelFormats]] to detect if the HAL video API is implemented. If this call returns non-zero then the OS will register a "HAL" driver with [[GraphicsV]] and map GraphicsV calls to HAL calls as follows: |_<^{width:3em}. # |<^. GraphicsV call |<^. HAL call(s) | |<^. 1|<^. [[GraphicsV 1|VSync interrupt occurred]]| - | |<^. 2|<^. [[GraphicsV 2|Set mode]]| [[HAL_VideoSetMode]] | |<^. 3|<^. [[GraphicsV 3|Set interlace]]| [[HAL_VideoSetInterlace]] | |<^. 4|<^. [[GraphicsV 4|Set blank]]| [[HAL_VideoSetBlank]] | |<^. 5|<^. [[GraphicsV 5|Update pointer]]| [[HAL_VideoUpdatePointer]] | |<^. 6|<^. [[GraphicsV 6|Set DAG]]| [[HAL_VideoSetDAG]] | |<^. 7|<^. [[GraphicsV 7|Vet mode]]| [[HAL_VideoVetMode]] | |/3<^. 8|/3<^. [[GraphicsV 8|Features]]| [[HAL_VideoFeatures]] (R0) | | [[HAL_VideoPixelFormats]] (R1) | | [[HAL_VideoBufferAlignment]] (R2) | |<^. 9|<^. [[GraphicsV 9|Framestore information]]| [[HAL_VideoFramestoreAddress]] | |<^. 10|<^. [[GraphicsV 10|Write palette entry]]| [[HAL_VideoWritePaletteEntry]] | |<^. 11|<^. [[GraphicsV 11|Write palette entries]]| [[HAL_VideoWritePaletteEntries]] | |<^. 12|<^. [[GraphicsV 12|Read palette entry]]| [[HAL_VideoReadPaletteEntry]] | |<^. 13|<^. [[GraphicsV 13|Render]]| [[HAL_VideoRender]] | |<^. 14|<^. [[GraphicsV 14|IIC op]]| [[HAL_VideoIICOp]] | |<^. 15|<^. [[GraphicsV 15|Select head]]| Unsuported | |<^. 16|<^. [[GraphicsV 16|Select startup mode]]| [[HAL_VideoStartupMode]] | |<^. 17|<^. [[GraphicsV 17|List pixel formats]]| [[HAL_VideoPixelFormatList]] | For VSync events, the OS will use [[HAL_VideoFlybackDevice]] to determine the IRQ device number to respond to, and will call [[GraphicsV 1]] as appropriate whenever the interrupt fires. Note that [[HAL_VideoSetPowerSave]] is currently not available via GraphicsV. Prior to RISC OS 5.21, any calls made to GraphicsV which were for driver zero and were not handled by a driver module would be forwarded onto the HAL. Additionally, some HAL video calls were required to be implemented for module-based drivers to operate correctly. h6. Information source: Kernel.Docs.HAL.HAL_API in CVS