/* File: CGDirectDisplay.h Contains: CoreGraphics direct display Version: QuickTime 7.3 Copyright: (c) 2007 (c) 2000-2001 by Apple Computer, Inc., all rights reserved. Bugs?: For bug reports, consult the following page on the World Wide Web: http://developer.apple.com/bugreporter/ */ #ifndef CGDIRECTDISPLAY_H_ #define CGDIRECTDISPLAY_H_ #ifndef __CGBASE__ #include #endif #ifndef __CGGEOMETRY__ #include #endif #ifndef __CGERROR__ #include #endif #ifndef __CFARRAY__ #include #endif #ifndef __CFSTRING__ #include #endif #ifndef __CFDICTIONARY__ #include #endif #include #if PRAGMA_ONCE #pragma once #endif #ifdef __cplusplus extern "C" { #endif #if PRAGMA_IMPORT #pragma import on #endif typedef struct _CGDirectDisplayID* CGDirectDisplayID; typedef struct _CGDirectPaletteRef* CGDirectPaletteRef; typedef uint32_t CGDisplayCount; typedef uint32_t CGTableCount; typedef int32_t CGDisplayCoord; typedef uint8_t CGByteValue; typedef uint32_t CGOpenGLDisplayMask; typedef uint32_t CGBeamPosition; typedef int32_t CGMouseDelta; typedef double CGRefreshRate; typedef CGError CGDisplayErr; enum { CGDisplayNoErr = kCGErrorSuccess }; /* A NULL value points to the main display device as a programming convention */ #define kCGDirectMainDisplay ((CGDirectDisplayID)NULL) /* * Mechanisms used to find screen IDs * An array length (maxDisplays) and array of CGDirectDisplayIDs are passed in. * Up to maxDisplays of the array are filled in with the displays meeting the * specified criteria. The actual number of displays filled in is returned in * dspyCnt. * * If the dspys array is NULL, maxDisplays is ignored, and *dspyCnt is filled * in with the number of displays meeting the function's requirements. */ /* * CGGetDisplaysWithPoint() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGDisplayErr ) CGGetDisplaysWithPoint( CGPoint point, CGDisplayCount maxDisplays, CGDirectDisplayID * dspys, CGDisplayCount * dspyCnt); /* * CGGetDisplaysWithRect() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGDisplayErr ) CGGetDisplaysWithRect( CGRect rect, CGDisplayCount maxDisplays, CGDirectDisplayID * dspys, CGDisplayCount * dspyCnt); /* * CGGetDisplaysWithOpenGLDisplayMask() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGDisplayErr ) CGGetDisplaysWithOpenGLDisplayMask( CGOpenGLDisplayMask mask, CGDisplayCount maxDisplays, CGDirectDisplayID * dspys, CGDisplayCount * dspyCnt); /* * Get lists of displays. Use this to determine display IDs * * If the activeDspys array is NULL, maxDisplays is ignored, and *dspyCnt is filled * in with the number of displays meeting the function's requirements. * * The first display returned in the list is the main display, * the one with the menu bar. * When mirroring, this will be the largest display, * or if all are the same size, the one with the deepest pixel depth. */ /* * CGGetActiveDisplayList() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGDisplayErr ) CGGetActiveDisplayList( CGDisplayCount maxDisplays, CGDirectDisplayID * activeDspys, CGDisplayCount * dspyCnt); /* Map a display to an OpenGL display mask; returns 0 on invalid display */ /* * CGDisplayIDToOpenGLDisplayMask() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGOpenGLDisplayMask ) CGDisplayIDToOpenGLDisplayMask(CGDirectDisplayID display); /* Return screen size and origin in global coords; Empty rect if display is invalid */ /* * CGDisplayBounds() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGRect ) CGDisplayBounds(CGDirectDisplayID display); /* * CGDisplayPixelsWide() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( size_t ) CGDisplayPixelsWide(CGDirectDisplayID display); /* * CGDisplayPixelsHigh() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( size_t ) CGDisplayPixelsHigh(CGDirectDisplayID display); /* * Display mode selection * Display modes are represented as CFDictionaries * All dictionaries and arrays returned via these mechanisms are * owned by the framework and should not be released. The framework * will not release them out from under your application. * * Values associated with the following keys are CFNumber types. * With CFNumberGetValue(), use kCFNumberLongType for best results. */ /* * Keys used in mode dictionaries. Source C strings shown won't change. * Some CFM environments cannot import data variables, and so * duplicate these CFStringRefs locally. */ /* * kCGDisplayWidth * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ extern CFStringRef kCGDisplayWidth; /* * kCGDisplayHeight * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ extern CFStringRef kCGDisplayHeight; /* * kCGDisplayMode * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ extern CFStringRef kCGDisplayMode; /* * kCGDisplayBitsPerPixel * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ extern CFStringRef kCGDisplayBitsPerPixel; /* * kCGDisplayBitsPerSample * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ extern CFStringRef kCGDisplayBitsPerSample; /* * kCGDisplaySamplesPerPixel * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ extern CFStringRef kCGDisplaySamplesPerPixel; /* * kCGDisplayRefreshRate * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ extern CFStringRef kCGDisplayRefreshRate; /* * kCGDisplayModeUsableForDesktopGUI * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ extern CFStringRef kCGDisplayModeUsableForDesktopGUI; /* * kCGDisplayIOFlags * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ extern CFStringRef kCGDisplayIOFlags; /* * Return a CFArray of CFDictionaries describing all display modes. * Returns NULL if the display is invalid. */ /* * CGDisplayAvailableModes() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CFArrayRef ) CGDisplayAvailableModes(CGDirectDisplayID display); /* * Try to find a display mode of specified depth with dimensions equal or greater than * specified. * If no depth match is found, try for the next larger depth with dimensions equal or greater * than specified. If no luck, then just return the current mode. * * exactmatch, if not NULL, is set to 'true' if an exact match in width, height, and depth is found, * and 'false' otherwise. * Returns NULL if display is invalid. */ /* * CGDisplayBestModeForParameters() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CFDictionaryRef ) CGDisplayBestModeForParameters( CGDirectDisplayID display, size_t bitsPerPixel, size_t width, size_t height, boolean_t * exactMatch); /* * CGDisplayBestModeForParametersAndRefreshRate() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CFDictionaryRef ) CGDisplayBestModeForParametersAndRefreshRate( CGDirectDisplayID display, size_t bitsPerPixel, size_t width, size_t height, CGRefreshRate refresh, boolean_t * exactMatch); /* * Return a CFDictionary describing the current display mode. * Returns NULL if display is invalid. */ /* * CGDisplayCurrentMode() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CFDictionaryRef ) CGDisplayCurrentMode(CGDirectDisplayID display); /* * Switch display mode. Note that after switching, * display parameters and addresses may change. * The selected display mode persists for the life of the program, and automatically * reverts to the permanent setting made by Preferences when the program terminates. * The mode dictionary passed in must be a dictionary vended by other CGDirectDisplay * APIs such as CGDisplayBestModeForParameters() and CGDisplayAvailableModes(). */ /* * CGDisplaySwitchToMode() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGDisplayErr ) CGDisplaySwitchToMode( CGDirectDisplayID display, CFDictionaryRef mode); /* Query parameters for current mode */ /* * CGDisplayBitsPerPixel() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( size_t ) CGDisplayBitsPerPixel(CGDirectDisplayID display); /* * CGDisplayBitsPerSample() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( size_t ) CGDisplayBitsPerSample(CGDirectDisplayID display); /* * CGDisplaySamplesPerPixel() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( size_t ) CGDisplaySamplesPerPixel(CGDirectDisplayID display); /* * CGDisplayBytesPerRow() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( size_t ) CGDisplayBytesPerRow(CGDirectDisplayID display); /* * Set a display gamma/transfer function from a formula specifying * min and max values and a gamma for each channel. * Gamma values must be greater than 0.0. * To get an antigamma of 1.6, one would specify a value of (1.0 / 1.6) * Min values must be greater than or equal to 0.0 and less than 1.0. * Max values must be greater than 0.0 and less than or equal to 1.0. * Out of range values, or Max greater than or equal to Min result * in a kCGSRangeCheck error. * * Values are computed by sampling a function for a range of indices from 0 through 1: * value = Min + ((Max - Min) * pow(index, Gamma)) * The resulting values are converted to a machine specific format * and loaded into hardware. */ typedef float CGGammaValue; /* * CGSetDisplayTransferByFormula() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGDisplayErr ) CGSetDisplayTransferByFormula( CGDirectDisplayID display, CGGammaValue redMin, CGGammaValue redMax, CGGammaValue redGamma, CGGammaValue greenMin, CGGammaValue greenMax, CGGammaValue greenGamma, CGGammaValue blueMin, CGGammaValue blueMax, CGGammaValue blueGamma); /* * CGGetDisplayTransferByFormula() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGDisplayErr ) CGGetDisplayTransferByFormula( CGDirectDisplayID display, CGGammaValue * redMin, CGGammaValue * redMax, CGGammaValue * redGamma, CGGammaValue * greenMin, CGGammaValue * greenMax, CGGammaValue * greenGamma, CGGammaValue * blueMin, CGGammaValue * blueMax, CGGammaValue * blueGamma); /* * Set a display gamma/transfer function using tables of data for each channel. * Values within each table should have values in the range of 0.0 through 1.0. * The same table may be passed in for red, green, and blue channels. 'tableSize' * indicates the number of entries in each table. * The tables are interpolated as needed to generate the number of samples needed * by hardware. */ /* * CGSetDisplayTransferByTable() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGDisplayErr ) CGSetDisplayTransferByTable( CGDirectDisplayID display, CGTableCount tableSize, const CGGammaValue * redTable, const CGGammaValue * greenTable, const CGGammaValue * blueTable); /* * Get transfer tables. Capacity should contain the number of samples each * array can hold, and *sampleCount is filled in with the number of samples * actually copied in. */ /* * CGGetDisplayTransferByTable() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGDisplayErr ) CGGetDisplayTransferByTable( CGDirectDisplayID display, CGTableCount capacity, CGGammaValue * redTable, CGGammaValue * greenTable, CGGammaValue * blueTable, CGTableCount * sampleCount); /* As a convenience, allow setting of the gamma table by byte values */ /* * CGSetDisplayTransferByByteTable() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGDisplayErr ) CGSetDisplayTransferByByteTable( CGDirectDisplayID display, CGTableCount tableSize, const CGByteValue * redTable, const CGByteValue * greenTable, const CGByteValue * blueTable); /* Restore gamma tables of system displays to the user's ColorSync specified values */ /* * CGDisplayRestoreColorSyncSettings() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( void ) CGDisplayRestoreColorSyncSettings(void); /* Display capture and release */ /* * CGDisplayIsCaptured() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( boolean_t ) CGDisplayIsCaptured(CGDirectDisplayID display); /* * CGDisplayCapture() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGDisplayErr ) CGDisplayCapture(CGDirectDisplayID display); /* * CGDisplayRelease() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGDisplayErr ) CGDisplayRelease(CGDirectDisplayID display); /* * Capture all displays; this has the nice effect of providing an immersive * environment, and preventing other apps from trying to adjust themselves * to display changes only needed by your app. */ /* * CGCaptureAllDisplays() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGDisplayErr ) CGCaptureAllDisplays(void); /* * Release all captured displays, and restore the display modes to the * user's preferences. May be used in conjunction with CGDisplayCapture() * or CGCaptureAllDisplays(). */ /* * CGReleaseAllDisplays() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGDisplayErr ) CGReleaseAllDisplays(void); /* * Returns CoreGraphics raw shield window ID or NULL if not shielded * This value may be used with drawing surface APIs. */ /* * CGShieldingWindowID() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( void * ) CGShieldingWindowID(CGDirectDisplayID display); /* * Returns the window level used for the shield window. * This value may be used with Cocoa windows to position the * Cocoa window in the same window level as the shield window. */ /* * CGShieldingWindowLevel() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( int32_t ) CGShieldingWindowLevel(void); /* * Returns base address of display or NULL for an invalid display. * If the display has not been captured, the returned address may refer * to read-only memory. */ /* * CGDisplayBaseAddress() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( void * ) CGDisplayBaseAddress(CGDirectDisplayID display); /* * return address for X,Y in screen coordinates; * (0,0) represents the upper left corner of the display. * returns NULL for an invalid display or out of bounds coordinates * If the display has not been captured, the returned address may refer * to read-only memory. */ /* * CGDisplayAddressForPosition() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( void * ) CGDisplayAddressForPosition( CGDirectDisplayID display, CGDisplayCoord x, CGDisplayCoord y); /* Mouse Cursor controls */ /* * CGDisplayHideCursor() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGDisplayErr ) CGDisplayHideCursor(CGDirectDisplayID display); /* increments hide cursor count */ /* * CGDisplayShowCursor() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGDisplayErr ) CGDisplayShowCursor(CGDirectDisplayID display); /* decrements hide cursor count */ /* * Move the cursor to the specified point relative to the display origin * (the upper left corner of the display). Returns CGDisplayNoErr on success. * No events are generated as a result of this move. * Points that would lie outside the desktop are clipped to the desktop. */ /* * CGDisplayMoveCursorToPoint() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGDisplayErr ) CGDisplayMoveCursorToPoint( CGDirectDisplayID display, CGPoint point); /* * Report the mouse position change associated with the last mouse move event * recieved by this application. */ /* * CGGetLastMouseDelta() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( void ) CGGetLastMouseDelta( CGMouseDelta * deltaX, CGMouseDelta * deltaY); /* Palette controls (8 bit pseudocolor only) */ /* * Returns TRUE if the current display mode supports palettes */ /* * CGDisplayCanSetPalette() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( boolean_t ) CGDisplayCanSetPalette(CGDirectDisplayID display); /* * Set a palette. The current gamma function is applied to the palette * elements before being loaded into hardware. */ /* * CGDisplaySetPalette() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGDisplayErr ) CGDisplaySetPalette( CGDirectDisplayID display, CGDirectPaletteRef palette); /* * Wait until the beam position is outside the range specified by upperScanLine and lowerScanLine. * Note that if upperScanLine and lowerScanLine encompass the entire display height, * the function returns an error. * lowerScanLine must be greater than or equal to upperScanLine. * * Some display systems may not conventional video vertical and horizontal sweep in painting. * These displays report a kCGDisplayRefreshRate of 0 in the CFDictionaryRef returned by * CGDisplayCurrentMode(). On such displays, this function returns at once. * * Some drivers may not implement support for this mechanism. * On such displays, this function returns at once. * * Returns CGDisplayNoErr on success, and an error if display or upperScanLine and * lowerScanLine are invalid. * * The app should set the values of upperScanLine and lowerScanLine to allow enough lead time * for the drawing operation to complete. A common strategy is to wait for the beam to pass * the bottom of the drawing area, allowing almost a full vertical sweep period to perform drawing. * To do this, set upperScanLine to 0, and set lowerScanLine to the bottom of the bounding box: * lowerScanLine = (CGBeamPosition)(cgrect.origin.y + cgrect.size.height); * * IOKit may implement this as a spin-loop on the beam position call used for CGDisplayBeamPosition(). * On such system the function is CPU bound, and subject to all the usual scheduling pre-emption. * In particular, attempting to wait for the beam to hit a specific scanline may be an exercise in frustration. * * These functions are advisary in nature, and depend on IOKit and hardware specific drivers to implement * support. If you need extremely precise timing, or access to vertical blanking interrupts, * you should consider writing a device driver to tie into hardware-specific capabilities. */ /* * CGDisplayWaitForBeamPositionOutsideLines() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGDisplayErr ) CGDisplayWaitForBeamPositionOutsideLines( CGDirectDisplayID display, CGBeamPosition upperScanLine, CGBeamPosition lowerScanLine); /* * Returns the current beam position on the display. If display is invalid, * or the display does not implement conventional video vertical and horizontal * sweep in painting, or the driver does not implement this functionality, 0 is returned. */ /* * CGDisplayBeamPosition() * * Availability: * Non-Carbon CFM: not available * CarbonLib: not available * Mac OS X: in version 10.0 and later */ EXTERN_API_C( CGBeamPosition ) CGDisplayBeamPosition(CGDirectDisplayID display); #ifdef PRAGMA_IMPORT_OFF #pragma import off #elif PRAGMA_IMPORT #pragma import reset #endif #ifdef __cplusplus } #endif #endif /* CGDIRECTDISPLAY_H_ */