1/*
2 * Copyright (c) 2008 NVIDIA, Corporation
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a copy
5 * of this software and associated documentation files (the "Software"), to deal
6 * in the Software without restriction, including without limitation the rights
7 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8 * copies of the Software, and to permit persons to whom the Software is
9 * furnished to do so, subject to the following conditions:
10 *
11 * The above copyright notice and this permission notice (including the next
12 * paragraph) shall be included in all copies or substantial portions of the
13 * Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
18 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 * SOFTWARE.
22 */
23
24#ifndef __NVCTRLLIB_H
25#define __NVCTRLLIB_H
26
27#include "NVCtrl.h"
28
29#if defined __cplusplus
30extern "C" {
31#endif
32
33/*
34 *  XNVCTRLQueryExtension -
35 *
36 *  Returns True if the extension exists, returns False otherwise.
37 *  event_basep and error_basep are the extension event and error
38 *  bases.  Currently, no extension specific errors or events are
39 *  defined.
40 */
41
42Bool XNVCTRLQueryExtension (
43    Display *dpy,
44    int *event_basep,
45    int *error_basep
46);
47
48
49/*
50 *  XNVCTRLQueryVersion -
51 *
52 *  Returns True if the extension exists, returns False otherwise.
53 *  major and minor are the extension's major and minor version
54 *  numbers.
55 */
56
57Bool XNVCTRLQueryVersion (
58    Display *dpy,
59    int *major,
60    int *minor
61);
62
63
64/*
65 *  XNVCTRLIsNvScreen
66 *
67 *  Returns True is the specified screen is controlled by the NVIDIA
68 *  driver.  Returns False otherwise.
69 */
70
71Bool XNVCTRLIsNvScreen (
72    Display *dpy,
73    int screen
74);
75
76
77/*
78 *  XNVCTRLQueryTargetCount -
79 *
80 *  Returns True if the target type exists.  Returns False otherwise.
81 *  If XNVCTRLQueryTargetCount returns True, value will contain the
82 *  count of existing targets on the server of the specified target
83 *  type.
84 *
85 *  Please see "Attribute Targets" in NVCtrl.h for the list of valid
86 *  target types.
87 *
88 *  Possible errors:
89 *     BadValue - The target doesn't exist.
90 */
91
92Bool XNVCTRLQueryTargetCount (
93    Display *dpy,
94    int target_type,
95    int *value
96);
97
98
99/*
100 *  XNVCTRLSetAttribute -
101 *
102 *  Sets the attribute to the given value.  The attributes and their
103 *  possible values are listed in NVCtrl.h.
104 *
105 *  Not all attributes require the display_mask parameter; see
106 *  NVCtrl.h for details.
107 *
108 *  Calling this function is equivalent to calling XNVCTRLSetTargetAttribute()
109 *  with the target_type set to NV_CTRL_TARGET_TYPE_X_SCREEN and
110 *  target_id set to 'screen'.
111 *
112 *  Possible errors:
113 *     BadValue - The screen or attribute doesn't exist.
114 *     BadMatch - The NVIDIA driver is not present on that screen.
115 */
116
117void XNVCTRLSetAttribute (
118    Display *dpy,
119    int screen,
120    unsigned int display_mask,
121    unsigned int attribute,
122    int value
123);
124
125
126/*
127 *  XNVCTRLSetTargetAttribute -
128 *
129 *  Sets the attribute to the given value.  The attributes and their
130 *  possible values are listed in NVCtrl.h.
131 *
132 *  Not all attributes require the display_mask parameter; see
133 *  NVCtrl.h for details.
134 *
135 *  Possible errors:
136 *     BadValue - The target or attribute doesn't exist.
137 *     BadMatch - The NVIDIA driver is not present on that target.
138 */
139
140void XNVCTRLSetTargetAttribute (
141    Display *dpy,
142    int target_type,
143    int target_id,
144    unsigned int display_mask,
145    unsigned int attribute,
146    int value
147);
148
149
150/*
151 *  XNVCTRLSetAttributeAndGetStatus -
152 *
153 * Same as XNVCTRLSetAttribute().
154 * In addition, XNVCTRLSetAttributeAndGetStatus() returns
155 * True if the operation succeeds, False otherwise.
156 *
157 */
158
159Bool XNVCTRLSetAttributeAndGetStatus (
160    Display *dpy,
161    int screen,
162    unsigned int display_mask,
163    unsigned int attribute,
164    int value
165);
166
167
168/*
169 *  XNVCTRLSetTargetAttributeAndGetStatus -
170 *
171 * Same as XNVCTRLSetTargetAttribute().
172 * In addition, XNVCTRLSetTargetAttributeAndGetStatus() returns
173 * True if the operation succeeds, False otherwise.
174 *
175 */
176
177Bool XNVCTRLSetTargetAttributeAndGetStatus (
178    Display *dpy,
179    int target_type,
180    int target_id,
181    unsigned int display_mask,
182    unsigned int attribute,
183    int value
184);
185
186
187/*
188 *  XNVCTRLQueryAttribute -
189 *
190 *  Returns True if the attribute exists.  Returns False otherwise.
191 *  If XNVCTRLQueryAttribute returns True, value will contain the
192 *  value of the specified attribute.
193 *
194 *  Not all attributes require the display_mask parameter; see
195 *  NVCtrl.h for details.
196 *
197 *  Calling this function is equivalent to calling
198 *  XNVCTRLQueryTargetAttribute() with the target_type set to
199 *  NV_CTRL_TARGET_TYPE_X_SCREEN and target_id set to 'screen'.
200 *
201 *  Possible errors:
202 *     BadValue - The screen doesn't exist.
203 *     BadMatch - The NVIDIA driver is not present on that screen.
204 */
205
206Bool XNVCTRLQueryAttribute (
207    Display *dpy,
208    int screen,
209    unsigned int display_mask,
210    unsigned int attribute,
211    int *value
212);
213
214
215/*
216 * XNVCTRLQueryTargetAttribute -
217 *
218 *  Returns True if the attribute exists.  Returns False otherwise.
219 *  If XNVCTRLQueryTargetAttribute returns True, value will contain the
220 *  value of the specified attribute.
221 *
222 *  Not all attributes require the display_mask parameter; see
223 *  NVCtrl.h for details.
224 *
225 *  Possible errors:
226 *     BadValue - The target doesn't exist.
227 *     BadMatch - The NVIDIA driver does not control the target.
228 */
229
230Bool XNVCTRLQueryTargetAttribute (
231    Display *dpy,
232    int target_Type,
233    int target_id,
234    unsigned int display_mask,
235    unsigned int attribute,
236    int *value
237);
238
239
240/*
241 * XNVCTRLQueryTargetAttribute64 -
242 *
243 *  Returns True if the attribute exists.  Returns False otherwise.
244 *  If XNVCTRLQueryTargetAttribute returns True, value will contain the
245 *  value of the specified attribute.
246 *
247 *  Not all attributes require the display_mask parameter; see
248 *  NVCtrl.h for details.
249 *
250 *  Note: this function behaves like XNVCTRLQueryTargetAttribute(),
251 *  but supports 64-bit integer attributes.
252 *
253 *  Possible errors:
254 *     BadValue - The target doesn't exist.
255 *     BadMatch - The NVIDIA driver does not control the target.
256 */
257
258Bool XNVCTRLQueryTargetAttribute64 (
259    Display *dpy,
260    int target_Type,
261    int target_id,
262    unsigned int display_mask,
263    unsigned int attribute,
264    int64_t *value
265);
266
267
268/*
269 *  XNVCTRLQueryStringAttribute -
270 *
271 *  Returns True if the attribute exists.  Returns False otherwise.
272 *  If XNVCTRLQueryStringAttribute returns True, *ptr will point to an
273 *  allocated string containing the string attribute requested.  It is
274 *  the caller's responsibility to free the string when done.
275 *
276 *  Calling this function is equivalent to calling
277 *  XNVCTRLQueryTargetStringAttribute() with the target_type set to
278 *  NV_CTRL_TARGET_TYPE_X_SCREEN and target_id set to 'screen'.
279 *
280 *  Possible errors:
281 *     BadValue - The screen doesn't exist.
282 *     BadMatch - The NVIDIA driver is not present on that screen.
283 *     BadAlloc - Insufficient resources to fulfill the request.
284 */
285
286Bool XNVCTRLQueryStringAttribute (
287    Display *dpy,
288    int screen,
289    unsigned int display_mask,
290    unsigned int attribute,
291    char **ptr
292);
293
294
295/*
296 *  XNVCTRLQueryTargetStringAttribute -
297 *
298 *  Returns True if the attribute exists.  Returns False otherwise.
299 *  If XNVCTRLQueryTargetStringAttribute returns True, *ptr will point
300 *  to an allocated string containing the string attribute requested.
301 *  It is the caller's responsibility to free the string when done.
302 *
303 *  Possible errors:
304 *     BadValue - The target doesn't exist.
305 *     BadMatch - The NVIDIA driver does not control the target.
306 *     BadAlloc - Insufficient resources to fulfill the request.
307 */
308
309Bool XNVCTRLQueryTargetStringAttribute (
310    Display *dpy,
311    int target_type,
312    int target_id,
313    unsigned int display_mask,
314    unsigned int attribute,
315    char **ptr
316);
317
318
319/*
320 *  XNVCTRLSetStringAttribute -
321 *
322 *  Returns True if the operation succeded.  Returns False otherwise.
323 *
324 *  Possible X errors:
325 *     BadValue - The screen doesn't exist.
326 *     BadMatch - The NVIDIA driver is not present on that screen.
327 *     BadAlloc - Insufficient resources to fulfill the request.
328 */
329
330Bool XNVCTRLSetStringAttribute (
331    Display *dpy,
332    int screen,
333    unsigned int display_mask,
334    unsigned int attribute,
335    char *ptr
336);
337
338
339/*
340 *  XNVCTRLSetTargetStringAttribute -
341 *
342 *  Returns True if the operation succeded.  Returns False otherwise.
343 *
344 *  Possible X errors:
345 *     BadValue - The screen doesn't exist.
346 *     BadMatch - The NVIDIA driver is not present on that screen.
347 *     BadAlloc - Insufficient resources to fulfill the request.
348 */
349
350Bool XNVCTRLSetTargetStringAttribute (
351    Display *dpy,
352    int target_type,
353    int target_id,
354    unsigned int display_mask,
355    unsigned int attribute,
356    char *ptr
357);
358
359
360/*
361 * XNVCTRLQueryValidAttributeValues -
362 *
363 * Returns True if the attribute exists.  Returns False otherwise.  If
364 * XNVCTRLQueryValidAttributeValues returns True, values will indicate
365 * the valid values for the specified attribute; see the description
366 * of NVCTRLAttributeValidValues in NVCtrl.h.
367 *
368 *  Calling this function is equivalent to calling
369 *  XNVCTRLQueryValidTargetAttributeValues() with the target_type set to
370 *  NV_CTRL_TARGET_TYPE_X_SCREEN and target_id set to 'screen'.
371 */
372
373Bool XNVCTRLQueryValidAttributeValues (
374    Display *dpy,
375    int screen,
376    unsigned int display_mask,
377    unsigned int attribute,
378    NVCTRLAttributeValidValuesRec *values
379);
380
381
382
383/*
384 * XNVCTRLQueryValidTargetAttributeValues -
385 *
386 * Returns True if the attribute exists.  Returns False otherwise.  If
387 * XNVCTRLQueryValidTargetAttributeValues returns True, values will indicate
388 * the valid values for the specified attribute.
389 */
390
391Bool XNVCTRLQueryValidTargetAttributeValues (
392    Display *dpy,
393    int target_type,
394    int target_id,
395    unsigned int display_mask,
396    unsigned int attribute,
397    NVCTRLAttributeValidValuesRec *values
398);
399
400
401/*
402 * XNVCTRLQueryValidTargetStringAttributeValues -
403 *
404 * Returns True if the attribute exists.  Returns False otherwise.  If
405 * XNVCTRLQueryValidTargetStringAttributeValues returns True, values will
406 * indicate the valid values for the specified attribute.
407 */
408
409 Bool XNVCTRLQueryValidTargetStringAttributeValues (
410    Display *dpy,
411    int target_type,
412    int target_id,
413    unsigned int display_mask,
414    unsigned int attribute,
415    NVCTRLAttributeValidValuesRec *values
416);
417
418
419/*
420 * XNVCTRLQueryAttributePermissions -
421 *
422 * Returns True if the attribute exists.  Returns False otherwise.  If
423 * XNVCTRLQueryAttributePermissions returns True, permissions will
424 * indicate the permission flags for the attribute.
425 */
426
427Bool XNVCTRLQueryAttributePermissions (
428    Display *dpy,
429    unsigned int attribute,
430    NVCTRLAttributePermissionsRec *permissions
431);
432
433
434/*
435 * XNVCTRLQueryStringAttributePermissions -
436 *
437 * Returns True if the attribute exists.  Returns False otherwise.  If
438 * XNVCTRLQueryStringAttributePermissions returns True, permissions will
439 * indicate the permission flags for the attribute.
440 */
441
442 Bool XNVCTRLQueryStringAttributePermissions (
443    Display *dpy,
444    unsigned int attribute,
445    NVCTRLAttributePermissionsRec *permissions
446);
447
448
449/*
450 * XNVCTRLQueryBinaryDataAttributePermissions -
451 *
452 * Returns True if the attribute exists.  Returns False otherwise.  If
453 * XNVCTRLQueryBinaryDataAttributePermissions returns True, permissions
454 * will indicate the permission flags for the attribute.
455 */
456
457 Bool XNVCTRLQueryBinaryDataAttributePermissions (
458    Display *dpy,
459    unsigned int attribute,
460    NVCTRLAttributePermissionsRec *permissions
461);
462
463
464/*
465 * XNVCTRLQueryStringOperationAttributePermissions -
466 *
467 * Returns True if the attribute exists.  Returns False otherwise.  If
468 * XNVCTRLQueryStringOperationAttributePermissions returns True,
469 * permissions will indicate the permission flags for the attribute.
470 */
471
472 Bool XNVCTRLQueryStringOperationAttributePermissions (
473    Display *dpy,
474    unsigned int attribute,
475    NVCTRLAttributePermissionsRec *permissions
476);
477
478
479/*
480 *  XNVCTRLSetGvoColorConversion -
481 *
482 *  Sets the color conversion matrix, offset, and scale that should be
483 *  used for GVO (Graphic to Video Out).
484 *
485 *  The Color Space Conversion data is ordered like this:
486 *
487 *   colorMatrix[0][0] // r.Y
488 *   colorMatrix[0][1] // g.Y
489 *   colorMatrix[0][2] // b.Y
490 *
491 *   colorMatrix[1][0] // r.Cr
492 *   colorMatrix[1][1] // g.Cr
493 *   colorMatrix[1][2] // b.Cr
494 *
495 *   colorMatrix[2][0] // r.Cb
496 *   colorMatrix[2][1] // g.Cb
497 *   colorMatrix[2][2] // b.Cb
498 *
499 *   colorOffset[0]    // Y
500 *   colorOffset[1]    // Cr
501 *   colorOffset[2]    // Cb
502 *
503 *   colorScale[0]     // Y
504 *   colorScale[1]     // Cr
505 *   colorScale[2]     // Cb
506 *
507 *  where the data is used according to the following formulae:
508 *
509 *   Y  =  colorOffset[0] + colorScale[0] *
510 *           (R * colorMatrix[0][0] +
511 *            G * colorMatrix[0][1] +
512 *            B * colorMatrix[0][2]);
513 *
514 *   Cr =  colorOffset[1] + colorScale[1] *
515 *           (R * colorMatrix[1][0] +
516 *            G * colorMatrix[1][1] +
517 *            B * colorMatrix[1][2]);
518 *
519 *   Cb =  colorOffset[2] + colorScale[2] *
520 *           (R * colorMatrix[2][0] +
521 *            G * colorMatrix[2][1] +
522 *            B * colorMatrix[2][2]);
523 *
524 *  Possible errors:
525 *     BadMatch - The NVIDIA driver is not present on that screen.
526 *     BadImplementation - GVO is not available on that screen.
527 */
528
529void XNVCTRLSetGvoColorConversion (
530    Display *dpy,
531    int screen,
532    float colorMatrix[3][3],
533    float colorOffset[3],
534    float colorScale[3]
535);
536
537
538
539/*
540 *  XNVCTRLQueryGvoColorConversion -
541 *
542 *  Retrieves the color conversion matrix and color offset
543 *  that are currently being used for GVO (Graphic to Video Out).
544 *
545 *  The values are ordered within the arrays according to the comments
546 *  for XNVCTRLSetGvoColorConversion().
547 *
548 *  Possible errors:
549 *     BadMatch - The NVIDIA driver is not present on that screen.
550 *     BadImplementation - GVO is not available on that screen.
551 */
552
553Bool XNVCTRLQueryGvoColorConversion (
554    Display *dpy,
555    int screen,
556    float colorMatrix[3][3],
557    float colorOffset[3],
558    float colorScale[3]
559);
560
561
562/*
563 *  XNVCTRLQueryBinaryData -
564 *
565 *  Returns True if the attribute exists.  Returns False otherwise.
566 *  If XNVCTRLQueryBinaryData returns True, *ptr will point to an
567 *  allocated block of memory containing the binary data attribute
568 *  requested.  It is the caller's responsibility to free the data
569 *  when done.  len will list the length of the binary data.
570 *
571 *  Calling this function is equivalent to calling
572 *  XNVCTRLQueryTargetBinaryData() with the target_type set to
573 *  NV_CTRL_TARGET_TYPE_X_SCREEN and target_id set to 'screen'.
574 *
575 *  Possible errors:
576 *     BadValue - The screen doesn't exist.
577 *     BadMatch - The NVIDIA driver is not present on that screen.
578 *     BadAlloc - Insufficient resources to fulfill the request.
579 */
580
581Bool XNVCTRLQueryBinaryData (
582    Display *dpy,
583    int screen,
584    unsigned int display_mask,
585    unsigned int attribute,
586    unsigned char **ptr,
587    int *len
588);
589
590
591/*
592 * XNVCTRLQueryTargetBinaryData -
593 *
594 *  Returns True if the attribute exists.  Returns False otherwise.
595 *  If XNVCTRLQueryTargetBinaryData returns True, *ptr will point to an
596 *  allocated block of memory containing the binary data attribute
597 *  requested.  It is the caller's responsibility to free the data
598 *  when done.  len will list the length of the binary data.
599 *
600 *  Possible errors:
601 *     BadValue - The target doesn't exist.
602 *     BadMatch - The NVIDIA driver does not control the target.
603 *     BadAlloc - Insufficient resources to fulfill the request.
604 */
605
606Bool XNVCTRLQueryTargetBinaryData (
607    Display *dpy,
608    int target_type,
609    int target_id,
610    unsigned int display_mask,
611    unsigned int attribute,
612    unsigned char **ptr,
613    int *len
614);
615
616
617/*
618 * XNVCTRLStringOperation -
619 *
620 * Takes a string as input and returns a Xmalloc'ed string as output.
621 * Returns True on success and False on failure.
622 */
623
624Bool XNVCTRLStringOperation (
625    Display *dpy,
626    int target_type,
627    int target_id,
628    unsigned int display_mask,
629    unsigned int attribute,
630    char *pIn,
631    char **ppOut
632);
633
634
635
636/*
637 * XNVCtrlSelectNotify -
638 *
639 * This enables/disables receiving of NV-CONTROL events.  The type
640 * specifies the type of event to enable (currently, the only
641 * type that can be requested per-screen with XNVCtrlSelectNotify()
642 * is ATTRIBUTE_CHANGED_EVENT); onoff controls whether receiving this
643 * type of event should be enabled (True) or disabled (False).
644 *
645 * Returns True if successful, or False if the screen is not
646 * controlled by the NVIDIA driver.
647 */
648
649Bool XNVCtrlSelectNotify (
650    Display *dpy,
651    int screen,
652    int type,
653    Bool onoff
654);
655
656
657/*
658 * XNVCtrlSelectTargetNotify -
659 *
660 * This enables/disables receiving of NV-CONTROL events that happen on
661 * the specified target.  The notify_type specifies the type of event to
662 * enable (currently, the only type that can be requested per-target with
663 * XNVCtrlSelectTargetNotify() is TARGET_ATTRIBUTE_CHANGED_EVENT); onoff
664 * controls whether receiving this type of event should be enabled (True)
665 * or disabled (False).
666 *
667 * Returns True if successful, or False if the target is not
668 * controlled by the NVIDIA driver.
669 */
670
671Bool XNVCtrlSelectTargetNotify (
672    Display *dpy,
673    int target_type,
674    int target_id,
675    int notify_type,
676    Bool onoff
677);
678
679
680/*
681 * XNVCtrlEvent structure
682 */
683
684typedef struct {
685    int type;
686    unsigned long serial;
687    Bool send_event;  /* always FALSE, we don't allow send_events */
688    Display *display;
689    Time time;
690    int screen;
691    unsigned int display_mask;
692    unsigned int attribute;
693    int value;
694} XNVCtrlAttributeChangedEvent;
695
696typedef union {
697    int type;
698    XNVCtrlAttributeChangedEvent attribute_changed;
699    long pad[24];
700} XNVCtrlEvent;
701
702
703/*
704 * XNVCtrlEventTarget structure
705 */
706
707typedef struct {
708    int type;
709    unsigned long serial;
710    Bool send_event;  /* always FALSE, we don't allow send_events */
711    Display *display;
712    Time time;
713    int target_type;
714    int target_id;
715    unsigned int display_mask;
716    unsigned int attribute;
717    int value;
718} XNVCtrlAttributeChangedEventTarget;
719
720typedef union {
721    int type;
722    XNVCtrlAttributeChangedEventTarget attribute_changed;
723    long pad[24];
724} XNVCtrlEventTarget;
725
726
727/*
728 * XNVCtrlEventTargetAvailability structure
729 */
730
731typedef struct {
732    int type;
733    unsigned long serial;
734    Bool send_event;  /* always FALSE, we don't allow send_events */
735    Display *display;
736    Time time;
737    int target_type;
738    int target_id;
739    unsigned int display_mask;
740    unsigned int attribute;
741    int value;
742    Bool availability;
743} XNVCtrlAttributeChangedEventTargetAvailability;
744
745typedef union {
746    int type;
747    XNVCtrlAttributeChangedEventTargetAvailability attribute_changed;
748    long pad[24];
749} XNVCtrlEventTargetAvailability;
750
751
752/*
753 * XNVCtrlStringEventTarget structure
754 */
755
756typedef struct {
757    int type;
758    unsigned long serial;
759    Bool send_event;  /* always FALSE, we don't allow send_events */
760    Display *display;
761    Time time;
762    int target_type;
763    int target_id;
764    unsigned int display_mask;
765    unsigned int attribute;
766} XNVCtrlStringAttributeChangedEventTarget;
767
768typedef union {
769    int type;
770    XNVCtrlStringAttributeChangedEventTarget attribute_changed;
771    long pad[24];
772} XNVCtrlStringEventTarget;
773
774
775
776/*
777 * XNVCtrlBinaryEventTarget structure
778 */
779
780typedef struct {
781    int type;
782    unsigned long serial;
783    Bool send_event;  /* always FALSE, we don't allow send_events */
784    Display *display;
785    Time time;
786    int target_type;
787    int target_id;
788    unsigned int display_mask;
789    unsigned int attribute;
790} XNVCtrlBinaryAttributeChangedEventTarget;
791
792typedef union {
793    int type;
794    XNVCtrlBinaryAttributeChangedEventTarget attribute_changed;
795    long pad[24];
796} XNVCtrlBinaryEventTarget;
797
798#if defined __cplusplus
799} /* extern "C" */
800#endif
801
802#endif /* __NVCTRLLIB_H */
803