═══ 1. General Help for Palview ═══ PalView is a utility which allows the hardware color palette of the video display device to be monitored in real-time. It displays the colors that the hardware palette is currently set to, and will show any color changes as they happen. PalView can also display information about the individual color entries of the hardware color palette. PalView was designed to be used exclusively with the Presentation Manager's (PM) Palette Manager subsystem. The Palette Manager subsystem allows the "limited resource" of the hardware color palette to be fairly shared among PM applications which may want to set the hardware color palette to their own liking. PalView displays the results of the Palette Manager subsystem's arbitration of palette requests as they happen. The capabilities of PalView make it both a fun utility for the casual computer user and a handy debugging aid for the serious graphics application developer. PalView was designed so that it can be run continuously, constantly monitoring the color palette, with negligible impact on the total system performance. The serious graphics developer or aficionado may want to have PalView be a permanent fixture of their PM/WPS desktop. This help system contains information on all features and operations of PalView. It also contains information on color palettes, color palette manipulating PM applications, and PalView's relationship and interaction with both. Help is available for any of the following items: o How Color Palettes Work. o Menu Choices o Mouse Actions o Limitations o Technical Support o Legalities ═══ 2. Menu Choices ═══ The main menu for PalView is a "pop-up" style context menu (i.e. it is not a menu invoked from a menu bar). It can be invoke by clicking the mouse with the right mouse button anywhere in the palette entry display field (i.e. on any of the colored squares ) or by pressing Shift-F10 while the PalView window is the active window. This menu offers the following choices of action: o Settings... o Device Color Info... o Reset Palette o Help ═══ 3. 'Settings...' Menu Choice ═══ Select Settings... to bring up the Settings Dialog. The Settings Dialog allows the user to configure PalView. ═══ 4. 'Device Color Info..." Menu Choice ═══ Select Device Color Info... to bring up the Device Color Info Dialog The Device Color Info Dialog lists color capabilities of the Screen. ═══ 5. 'Reset Palette' Menu Choice ═══ Select Reset Palette to cause the system color palette to be reset to it's default (i.e. start-up) values. The results of the reset depend upon whether any running applications are manipulating the palette or not. When this menu choice is selected, the system color palette is immediately reset to it's default values. The PM system then broadcasts a message to all running applications, asking the applications to "realize" their custom palettes. At that point, the applications can claim and set any unclaimed palette entries. Note that all entries in the default palette are considered unclaimed. In other words, if palette manipulating applications are running, resetting the default palette may only trigger a quick round of palette arbitration, with the resulting palette being identical to the palette before the arbitration (i.e. resetting the palette has no lasting effect). However, if there are no palette manipulation applications running and the system palette is set to a custom color palette, resetting the palette can have long term effects. This situation is often the case when an app that changes the system palette doesn't "cleanup" after itself when it is closed. Currently PM doesn't immediately reset the system palette to the default palette when all palette manipulating apps are closed. This can leave the desktop and any running applications "discolored". It is in these cases where this menu item is most handy. For more information on how the system color palette works and arbitrates the system colors among palette manipulating applications, please see the section How Color Palettes Work. Note: PalView provides a quick "short-cut for selecting the reset feature: the system palette may also be reset by double-clicking the left mouse button anywhere in the palette entry display field (i.e. on any of the colored squares). ═══ 6. 'Help' Menu Choice ═══ Select Help to display the PalView help submenu allowing selection from the following help categories: o Help Index o General Help o Using Help o About PalView ═══ 7. 'Help Index' Menu Choice ═══ Select Help Index to display an alphabetic list of references to the help topics in PalView. Select an index entry to display the help topic that is related to that index entry. Note: To see all text of the index entries, maximize the Index window. ═══ 8. 'General Help' Menu Choice ═══ Select General Help as the starting point for help on PalView. General Help brings up a top level contents page and provides access to most all help entries. Note: Help for specific windows, features, and controls can be displayed by setting the cursor focus on the control or window in question and pressing the F1 key. ═══ 9. 'Using Help' Menu Choice ═══ Select Using Help to find out how to use this help facility. ═══ 10. 'About PalView' Menu Choice ═══ Select About PalView to get a window displaying version, copyright, and acknowledgement information about the application. ═══ 11. Keys Help ═══ There is no key specific help for PalView, as there is no special key input for the application. However PalView does, in general, handle key input as defined for WPS/PM (e.g. Shift-F10 for context menu, spacebar for select, accelerator keys, etc). For information on default WPS/PM key input see the section Key Assignments section in the OS/2 Master Help Index. For information on mouse specific assignments or actions, see the section Mouse Actions ═══ 12. Settings Dialog ═══ The Settings Dialog allows the operation and features of PalView to be configured. Changes to the Settings information are automatically saved each time PalView is run. The following features can be configured from the Settings Dialog: o 'Size' Setting o 'Floating Window' Settings o 'RGB Component Display' Setting There is also help available for the buttons on the Setting Dialog: o The 'Set' Button o The 'Cancel' Button o The 'Defaults' Button o The 'Help' Button ═══ 13. 'Size' Setting ═══ Currently, PalView can be sized to any of three fixed-dimension sizes: Small, Medium, and Large. The size can be changed by looping through the choices, either by using the keyboard "Up" and "Down" arrow keys, or by clicking on the arrow buttons with the mouse. These fixed sizes are based on the unit size of a single palette entry color square: Size Unit Size of Color Square Small @ 8x8 pels or pixels Medium @ 16x16 pels or pixels Large @ 32x32 pels or pixels The PalView window dimensions are based upon a square lay-out of entry color squares. For example, for a 256 color palette, the palette entry display field is an area of 16 rows and 16 columns of entry color squares. This leads to the rough window dimensions as follows: Size Rough Dimensions of Window Small @ 146x198 pels or pixels Medium @ 274x326 pels or pixels Large @ 530x582 pels or pixels Note that the above listed window sizes assume that the RGB Component Display feature is enable and is being drawn. Default: The default size is Medium ═══ 14. 'Floating Window' Settings ═══ PalView has an optional feature that allows it to maintain it's window on top of the PM Window Z-order stack; that is, there is a feature which allows PalView to remain on top of and completely unobscured by all other PM Windows. This allows the user to monitor the palette entry color field, even with a maximized active window which would otherwise hide the PalView window. The PalView window will always "float to the top". Since there is no functionality built in to OS/2 or PM to allow a window to automatically "float" above all other windows, PalView uses a technique of periodically checking it's position and moving itself to the top if necessary. The interval, or frequency with which PalView checks it's position is configurable. Note: This feature in no way affects which window is the active or focus window. Normally, the top level window is the active or focus window (i.e. it is the window that currently receives all user input). If this feature "floats" the PalView window on top of the current active window, the active window retains it's active status and will continue to receive all user input. Enabling the "Floating Window" Feature The floating window feature is completely optional, and can be enabled or disable by the user. To enable the floating window feature, put a check (by clicking with the mouse, or by pressing the space bar) in the check-box control labeled "Enable Float Feature". Default: The default setting is enabled Setting the "Floating Window" Interval The "Floating Window Interval" is the number of seconds PalView waits in between checking whether it is covered by a window or not. If PalView finds it is covered, it will move itself on top of all other windows. The fewer number of seconds the interval is set to, the quicker PalView will move itself to the top; however, the quicker PalView checks on it's position the more demand it will place on the System. While a one second interval will not, in general, slow the overall system performance, it is, in most cases, over-kill and unnecessary short. At the other end of the spectrum, the maximum interval of 60 second is probably too long to be of any practical use. Experimentation and usage should dictate the "best" setting. The interval can be changed by looping thru the number of seconds ( from 1 to 60 ) by using the keyboard "Up" and "Down" arrow keys, or by clicking on the arrow buttons with the mouse. Note: If the Float Feature is disabled, then the interval input control (i.e. the spin button) is "grayed-out", and the interval timeout value cannot be changed. Default: The default interval timeout is three seconds. ═══ 15. 'RGB Component Display' Setting ═══ The RGB Component Display is an optional feature and is one of the most powerful aspects of PalView. This feature allows each individual color palette entry to be queried and will report the entry color by the intensity value of each of it's RGB (i.e. Red, Green, Blue ) components. The possible intensity value range for a component is 0 to 255. As an example, a pure, bright red would be reported as RED=255, GREEN=0, BLUE=0; as another example, a pure, bright cyan would be reported as RED=0, GREEN=255, BLUE=255. When this feature is enabled, PalView's window is expanded to display an area above the palette entry display field where the RGB components and the palette index of a selected entry is displayed. The RGB component display area can look like: Starting from the left, the first number is the entry index in the hardware palette slot. Note that hardware palette indices do not, in general, match the "logical" palette indices set by the application creating the palette. The next three numbers are the values of the Red, Blue, and Green components,respectively, for this color entry. The entry to be displayed is selected with the mouse pointer. When the feature is enable, the mouse pointer is changed from it's default (normally an arrow) to a magnifying glass whenever it is over the PalView window. The magnifying glass pointer looks like: An entry is selected by placing the magnifying glass pointer so that the center of the glass is over the color square of the entry of interest. The RGB Component Display updates as pointer moves over the color squares. Note: Normally, the RGB Component values for a given entry are sampled once (when the magnifying glass pointer first moves over the entry color square) and is not updated until the pointer moves off the entry color square and then back on. This greatly improves performance and is fine for most cases of querying a static palette. However, this sampling rate may not prove sufficient if the palette is being "animated", or the palette entry is being changed rapidly due to palette switches. For these cases, PalView has a feature that allows it to monitor a dynamic palette entry. If the left mouse button is press and held down while the magnifying glass pointer is over a color entry square, the RGB Component value will be sampled and the RGB Component Display updated approximately every 1/10th of a second. For more information about this feature see the section Mouse Actions ═══ 16. The 'Set' Button ═══ The Set button configures PalView according to the settings entered via the PalView Settings Dialog. The settings take effect immediately. The Set button also closes the Settings Dialog. Note: These settings will be automatically stored when PalView is closed, and will be used the next time it is run. ═══ 17. The 'Cancel' Button ═══ The Cancel button closes the Settings Dialog without changing the configuration of PalView. Any changes entered via the Settings Dialog are discarded. ═══ 18. The 'Defaults' Button ═══ The Defaults button sets all the settings on the Settings Dialog to their default state and value. The default state and value for each Setting item is: ┌─────────────────────────┬────────────────────┐ │SETTING │DEFAULT STATE/VALUE │ ├─────────────────────────┼────────────────────┤ │Size │Medium │ ├─────────────────────────┼────────────────────┤ │Floating Window │Enabled │ ├─────────────────────────┼────────────────────┤ │Floating Window Interval │Three seconds │ ├─────────────────────────┼────────────────────┤ │RGB Component Display │Enabled │ └─────────────────────────┴────────────────────┘ Note: The Default button only sets the values/states but does not re-configure PalView or activate the new settings.The Set button must be pressed to activate the new settings, or the Cancel button must be pressed to discard the changes and retain the old settings. ═══ 19. The 'Help' Button ═══ The Help button brings up help for the Settings Dialog. Information about each Settings option and feature is explained. ═══ 20. The Screen Device Color Info Dialog ═══ The Screen Device Color Info Dialog is an informational dialog which lists the graphic and color capabilities of the current PM screen device as reported by the screen presentation driver. For an description of all the capabilities and characteristics reported on, see the section The Device Color Info List Note: None of the capabilities listed may be changed with this dialog; this dialog is informational only. ═══ 21. The Device Color Info List ═══ The capabilities and characteristics reported on are: Driver version The release version of the Screen Presentation Driver. Width in pels The maximum horizontal width of the Screen in pels or pixels. Height in pels The maximum vertical height of the Screen in pels or pixels. Horizontal resolution The maximum horizontal resolution of the Screen in pels or pixels per meter. Vertical resolution The maximum vertical resolution of the Screen in pels or pixels per meter. Number of color planes The number of color planes supported by the Screen. Most commonly, this is one. Number of color bits The number of color bits per pel (per plane) supported by the Screen. Color bits are used to represent color indices (or RGB values for 24-bits). Normally, one bit allows for monochrome support, four bits for 16 colors, 8 bits for 256 color, and 16 bits for 64K colors. Max colors supported The maximum number of distinct colors simultaneously support by the Screen. Max 'physical' colors supported The maximum number of distinct physical colors support by the Screen. These may or may not be supported simultaneously. Commonly, this number is equal to that reported by Max colors supported. Max color index available The maximum index value supported by the Screen for color palettes and logical color tables. Note that the range of color indices start at zero, rather than one. Color table support A category of features relating to Color Table support. The possible reported features in this category are: Min. 8 bits per RGB component support A color table with a minimum of 8 bits per RGB component can be loaded. Other than 8 bits per RGB component support A color table with some number other than 8 bits per RGB component can be loaded. True color mixing support True color mixing of the realized color table can occur (assuming that the number of color entries in the table is less than or equal to number of supported colors as reported by Max colors supported). Realizable color table support Logical color tables can be realized into the hardware color table/palette by an application. None There is no special color table support. Extended color graphics capabilities A category of miscellaneous features reported by the presentation driver. The possible reported features in this category are: Palette Manager support Color palettes, as opposed to color tables, are supported by the Screen. For more information on color palettes, see the section How Color Palettes Work. Color cursor support Color cursors are supported by the Screen. Note: None of the capabilities listed may be changed with this dialog; this dialog is informational only. ═══ 22. The 'OK' Button ═══ The OK button dismisses the Screen Device Color Info Dialog. ═══ 23. The 'Help' Button ═══ The Help button brings up help for the Screen Device Color Info Dialog. Information about each of the reported characteristics and features is explained. ═══ 24. How Color Palettes Work ═══ How Color Palettes Work All output devices, such as printers and monitors, have an associated hardware color palette. This hardware color palette contains the colors which are simultaneously supported in hardware by the device at a given instant. For simple printers, this might be just two colors: black and white. For VGA displays, the hardware color palette will contain 16 colors. For many SVGA and XGA displays, the number is more commonly 256 supported colors. A device is said to support "true-color" when it can support 24-bit color definitions, or 16.7 million colors; that is, true-color devices can simultaneously support and display the full color spectrum of human perception. For devices which don't support true-color, only a subset of those colors can be displayed at any given time. The art of color management on these devices is to manipulate the subset of colors to simulate true-color display. The OS/2 Palette Manager system was designed to facilitate and simplify color subset manipulation. The OS/2 Palette Manager system is an Presentation Manager subsystem which allows the equitable sharing among OS/2 applications of the "limited resource" of the hardware color palette. Additionally, Palette Manager allows the applications extensive control over the hardware color palette. The system is typically available only on devices with hardware color palettes of 256 colors. It should be noted that the Palette Manager system is implemented by the device driver, not by OS/2 itself, and therefore may not be supported on all devices. For the rest of this discussion, only screen devices with hardware color palettes of 256 colors will be covered. These are the devices on which Palette Manager is most commonly used, and the only devices that PalView monitors. By default, OS/2 sets the hardware color palette of the screen to a color palette that has been psychometrically tuned to provide a robust, generic spectrum, suitable for most general applications. However, there are specialized applications for which the default color palette is not sufficient; these applications have a need to display custom colors not available in the default palette. Take, for example, a photo touchup/editing application needing to display a picture of a red balloon. Assume that to accurately display the gradients of the balloon, the application needs 128 shades of red. The default color palette doesn't contain anywhere near 128 shades of red. The application could override the default palette by directly setting the hardware color palette to contain 128 shades of red. This would make the balloon look great. However, other applications running on the Desktop, which are depending on the default color palette, will also be displayed with 128 shades of red; this is probably not what the applications' authors had in mind, and would most likely lead to horrendous looking results for these other applications. Now assume that a second graphics application directly sets the hardware color palette to 192 shades of green to accurately represent it's own graphic. Since the hardware color palette was snatched away from the first application, the red balloon won't display properly (because many of the red shades will now have become green). It's important to note that the application displaying the red balloon has no way to know that it has lost it's entries in the hardware color palette, and that it's display is incorrect. These are the nature of problems which OS/2's Palette Manager system addresses and prevents. Palette Manager provides a controlled mechanism for an application to set the hardware color palette by making requests for custom colors. It provides arbitration when multiple applications are trying to concurrently request custom color be set. This arbitration follows a few simple rules: o If the application is the active foreground window, then it gets all of it's color requests assigned to the hardware palette. If the active foreground windows doesn't request all of the hardware palette slots, then the remaining colors slots are considered as unclaimed. o If the application is a background window, then it is granted it's requests only from the color slots which are unclaimed. In this case the application may only be granted a subset of it's requests. The remaining color requests for the application are mapped to the closest matching color available in the hardware color palette. o All slots of the default color palette are considered unclaimed. o When a new application becomes the active foreground window, all the applications are notified by the system to reclaim their color requests. This allows the arbitration to start anew. It also allows the applications to repaint their windows, thereby utilizing the new color palette resulting from the arbitration. With the Palette Manager's arbitration, the foreground application -- usually the one the user is concentrating on -- is always assured of being displayed with the most accurate color selection possible. The background applications are assured of, if not the most accurate color selection, then the best use of the colors available. Other Functions Palette Manager also allows applications a special function: animating color palette slots. The color value of an animated color palette slot can be changed very rapidly. The change is visible immediately, without the need for window repainting. PalView uses palette animation to create the color effect seen on the "About PalView" dialog box. Special Notes Palette Manager withholds 20 hardware color palette slots to maintain the default colors necessary for a consistent looking Desktop. These 20 slots are divided up as the first 10 and last 10 slots of the palette, as can be seen with PalView. This leaves a maximum 236 slots available for application usage. Although it is programmatically possible for an application to claim and override these 20 slots, thereby using the full 256 slots, it is generally discouraged. More On Palettes For more information on Palette Manager and color palette management, particularly from a programming standpoint, see: "Color Palette Management with OS/2", John D. Webb, OS/2 Developer Magazine, November 1994. ═══ 25. Mouse Actions ═══ This sections describes the mouse actions or assignments that are particular to PalView. Mouse action that are, in general, standard for PM/WPS application are not discussed; for information about the standard PM/WPS mouse action assignments, see the manual OS/2 2.1 Using the Operating System or run the OS/2 Tutorial that is optionally installed with OS/2. The following list describes the actions that can be performed with the mouse, along with the necessary conditions and locations : "Pop Up" the Main Menu Action Single-click the right mouse button (i.e. mouse button 2). Location Anywhere on the palette entry display field (i.e. on any of the colored squares). Condition At any time. Select color entry for the RGB Component Display Action Move the mouse pointer over the palette entry display field (i.e. on any of the colored squares). Location Anywhere on the palette entry display field. Condition Only when the RGB Component Display has been enabled via the Settings Dialog. Note When the RGB Component Display is enabled, the mouse pointer is set to look like a magnifying glass: Dynamically update the RGB Component Display of an "animated" palette entry Action Click and hold the left mouse button (i.e. mouse button 1). Location Over the palette entry (i.e. the colored square) of interest. Condition Only when the RGB Component Display has been enabled via the Settings Dialog. Note For information on animated palette entries, see the section How Color Palettes Work. Reset the default System Color Palette Action Double-click the left mouse button. Location Anywhere on the palette entry display field (i.e. on any of the colored squares). Condition At any time. Note: This section describes PalView mouse actions for an OS/2 system using the default mouse mappings. If changes have been made to the default System mouse action settings via the Mappings page of the Mouse Settings object (under the System Setup object), then PalView will conform to these changes. For example, if the action to display pop-up menus is changed from the PM/WPS default of Single-clicking button 2 to Single-clicking button 1 with the ALT key pressed, then PalView will require the new action to display it's pop-up menu rather than the default action described in the section above. ═══ 26. Limitations ═══ This section will describe the known caveats or limitations of PalView. o PalView only works on machines capable of supporting Palette Manager. For example, VGA does not support Palette Manager, therefore if PalView is run on a VGA machine, it will report that Palette Manager is not supported and exit. Most current SVGA, XGA, and 8514A drivers support Palette Manager. If in doubt, check with the video driver manufacturer. o PalView is currently only designed to work with palettes of 256 colors. This is due to the lack of palette arbitration in true-color (or near true color) configurations (i.e. there wouldn't be any changes for PalView to display); it is also due, in no small part, to the difficulties of displaying 65,536 or more color entries in a meaningful way that doesn't also cover the entire screen area. o The 'Reset Palette' feature of PalView may not work in all cases. There is no explicit function built into the PM system to reset the palette, so PalView must try to trick PM into resetting the palette. PM is not always fooled by the trick. Hopefully, this will change in the future. o Because PalView saves information about it window size and position between invocations of the application, if the screen resolution is changed (e.g. changed from 1024x768 to 640x480) between invocations, the PalView window may size and position itself incorrectly the next time it is run. This is because, under OS/2, size and position are resolution dependent. Incorrect sizing can be easily corrected by pulling up the Settings panel and changing (i.e. setting) the size to another size and then changing it back. Incorrect positioning may be corrected by moving the window to the desired location. o If one of PalView's dialog boxes is opened and then closed while monitoring a palette animating application, and the dialog was covering the main PalView window, the palette animation may suspend. This is caused by PalView repainting it's window (and grabbing the palette to do so) while being the active focus window; this takes away the reserved animating palette slots from the palette animating application. If the palette animating application is made the active focus window, then palette animation should resume as normal. o If the "About PalView" dialog box (which is a palette animating window) is opened while monitoring a palette animating application, and another palette managing application is also running, it is possible that the palette managing application may not be draw properly when the "About PalView" dialog is close. To fix the drawing, simply cause a repaint of the palette animating application while it is the active focus window; an easy way to do this is to minimize and then restore the applications window. o If the 'Floating Window' feature of PalView is enabled, then in a few special cases the PalView window may float to the top of OS/2's desktop Lockup window. The special cases are limited to when a message box is generated by the Lockup screen, as in the case of typing in an incorrect password or pressing the help button. This is due to how PM handles the Z-ordering during the Lockup Screen process. This is a cosmetic problem only; because PalView does not influence the active window or the window modal state of PM, this problem will never inhibit the user's ability to unlock the OS/2 desktop Lockup window ! ═══ 27. Technical Support ═══ PalView, as stated in the section Legalities is provided free of charge on a strictly "as is" basis. However, the author will make a good faith effort to address: o Errors, traps, unexpected behavior, and problems encountered with PalView. o Errors and typos in PalView's help system documentation. o Questions about PalView's general operation. o Questions about distributing PalView. o Comments and criticisms of PalView. o Feature suggestions and enhancements for PalView. Please send all correspondence to the author, John D. Webb, at the following E-mail address: Compuserve 71075,1117 Internet 71075.1117@compuserve.com Note: The author cannot guarantee a timely response to all inquiries. ═══ 28. Legalities ═══ Copyright Program and documentation copyright(c) 1994, John D. Webb. All rights reserved. License The author, John D. Webb, licenses the program, PalView, to you under the following conditions: o There is no monetary charge or fee for your use of the program. o You may make copies of the program. o You may distribute copies of the program, under the following conditions: - The components that comprise the PalView program, including the program executable file (.EXE) and the program help file (.HLP), are always distributed together. - The components that comprise the PalView program, including the program executable file (.EXE) and the program help file (.HLP), are not tampered with or altered in any way. - The copyright and warranty notices for the program are not tampered with, altered, or removed. - There is never a direct monetary charge, sales fee, or rental fee attached to a distributed copy. If you want to include and distribute PalView in a collection of programs, where a charge or fee applies solely to the distribution media or to the collection as a whole, please first receive written permission from the author at the address listed in the Technical Support. o You may not reverse engineer, decompile, disassemble or create derivative work from the program. Disclaimer of Warranties This program, PalView, is not warranted in any manner and is provided strictly "as is". There is no warranty, either express or implied, oral or written, including implied warranties of merchantability and fitness for a particular purpose. Note that your state laws may disallow exclusion of implied warranties. Limitation of Liability The author, John D. Webb, shall not be liable for any direct, indirect, incidental, consequential, special, or punitive damages arising out of your use, or inability to use, this program, even if he has been advised of the possibility of such damages. Note: If you do not agree to and accept all terms and conditions stated in this document, simply delete all copies of the PalView program in your possession. Your continued use of this program constitutes your acceptance of all the terms and conditions as stated.