1 /* Copyright (c) 2009 The Khronos Group Inc.

     2  *

     3  * Permission is hereby granted, free of charge, to any person obtaining a

     4  * copy of this software and/or associated documentation files (the

     5  * "Materials"), to deal in the Materials without restriction, including

     6  * without limitation the rights to use, copy, modify, merge, publish,

     7  * distribute, sublicense, and/or sell copies of the Materials, and to

     8  * permit persons to whom the Materials are furnished to do so, subject to

     9  * the following conditions:

    10  *

    11  * The above copyright notice and this permission notice shall be included

    12  * in all copies or substantial portions of the Materials.

    13  *

    14  * THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

    15  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

    16  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

    17  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY

    18  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,

    19  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE

    20  * MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.

    21  */

    22 

    23 #ifndef OWFATTRIBUTES_H_

    24 #define OWFATTRIBUTES_H_

    25 

    26 #include "owftypes.h"

    27 #include "owfutils.h"

    28 

    29 

    30 #ifdef __cplusplus

    31 extern "C"

    32 {

    33 #endif

    34 

    35 

    36 /*!

    37  *  \file Attribute interface

    38  *

    39  *  Attribute interface provides mechanism for controlled reading/writing

    40  *  access of different object properties in WFC and WFD APIs by proxying

    41  *  object instances' properties.

    42  *

    43  */

    44 #define RANGE_UNDEFINED     0xFFFFFFFF

    45 #define ATTR_LENGTH_BITS    20

    46 #define MAX_ATTR_LENGTH     (1 << ATTR_LENGTH_BITS)-1

    47 #define NUM_ATTR_VALUE_COPIES 3

    48 #define COMMITTED_ATTR_VALUE_INDEX 0

    49 #define WORKING_ATTR_VALUE_INDEX 1

    50 #define SNAPSHOT_ATTR_VALUE_INDEX 2

    51 

    52 typedef enum {

    53     ATTR_ERROR_NONE             = 0,

    54     ATTR_ERROR_NOT_FOUND        = -1,

    55     ATTR_ERROR_ALREADY_IN_USE   = -2,

    56     ATTR_ERROR_INVALID_ATTRIBUTE= -3,

    57     ATTR_ERROR_INVALID_VALUE    = -4,

    58     ATTR_ERROR_INVALID_ARGUMENT = -5,

    59     ATTR_ERROR_INVALID_CONTEXT  = -6,

    60     ATTR_ERROR_NO_MEMORY        = -7,

    61     ATTR_ERROR_INSANE           = -8,

    62     ATTR_ERROR_ACCESS_DENIED    = -9,

    63     ATTR_ERROR_INVALID_TYPE     = -10,

    64     ATTR_ERROR_CANT_HANDLE      = -11

    65 } OWF_ATTRIBUTE_LIST_STATUS;

    66 

    67 /* Attribute value element types */

    68 typedef enum {

    69     AT_UNDEFINED = 0,

    70     AT_INTEGER = 1,

    71     AT_FLOAT = 2,

    72     AT_BOOLEAN = 3

    73 } OWF_ATTRIBUTE_TYPE;

    74 

    75 

    76 /*

    77  * Attribute information (header)

    78  *

    79  * Dirty field is internal. Do not fiddle with it.

    80  * 

    81  * Comment on use of bitfields: 

    82  * 1: It stops generic use of split dirty flag

    83  * 2: Some compilers will not reorder members to merge length into earier fields.

    84  */

    85 typedef struct {

    86     OWFuint                 type: 2;

    87     OWFuint                 dirty: 1;

    88     OWFuint                 dirtysnapshot: 1;

    89     OWFuint                 readonly: 1;

    90     OWFuint                 size;                       //Size of one primitive

    91     OWFuint                 length: ATTR_LENGTH_BITS;   //Number of primitives in vector

    92 } OWF_ATTRIBUTE_INFO;

    93 

    94 /*

    95  * Attribute may be a scalar (1-element) or vector (n-element),

    96  * containing a reference to either integer, boolean or float value(s).

    97  * Attribute type cannot be changed after it has been initialized.

    98  *

    99  * Attributes don't own the data they refer to; attributes only

   100  * control the reading and writing of the data they refer to.

   101  */

   102 

   103 typedef OWFfloat*           OWF_FLOAT_REF;

   104 typedef OWFint*             OWF_INT_REF;

   105 typedef OWFboolean*         OWF_BOOL_REF;

   106 typedef OWFfloat*           OWF_FLOAT_VECTOR_REF;

   107 typedef OWFint*             OWF_INT_VECTOR_REF;

   108 

   109 typedef struct {

   110     OWF_ATTRIBUTE_INFO      attr_info;

   111     union {

   112         OWF_INT_REF             int_value;

   113         OWF_FLOAT_REF           float_value;

   114         void*                   gen_ptr;

   115         /*

   116         OWF_INT_VECTOR_REF      int_vector_value;

   117         OWF_FLOAT_VECTOR_REF    float_vector_value;

   118         */

   119     } attr_value[NUM_ATTR_VALUE_COPIES];

   120 } OWF_ATTRIBUTE;

   121 

   122 /*

   123  * Attribute list/context. Container for attributes.

   124  *

   125  * One list/context can contain constant number of

   126  * attributes (amount of which is defined at construction

   127  * time)

   128  */

   129 typedef struct {

   130     OWFint                  range_start;

   131     OWFint                  range_end;

   132     OWF_ATTRIBUTE*          attributes;

   133     OWF_ATTRIBUTE_LIST_STATUS  last_error;

   134 } OWF_ATTRIBUTE_LIST;

   135 

   136 /*

   137  * \brief Initializes attribute context

   138  *

   139  * \param aContext Attribute context to initialize

   140  * \param aStart Attribute range start

   141  * \param aEnd Attribute range end. Must be greater than range start.

   142  *

   143  * \return ERR_INVALID_ARGUMENT

   144  * ERR_NO_MEMORY

   145  */

   146 OWF_API_CALL void

   147 OWF_AttributeList_Create(OWF_ATTRIBUTE_LIST* aContext,

   148                          OWFint aStart,

   149                          OWFint aEnd);

   150 

   151 /*

   152  * \brief Destroy attribute context and free any resources (memory

   153  * blocks) allocated to it. All attributes are destroyed.

   154  *

   155  * \param aContext Attribute context to destroy

   156  *

   157  * \return ERR_INVALID_ARGUMENT

   158  * ERR_INVALID_CONTEXT

   159  */

   160 OWF_API_CALL void

   161 OWF_AttributeList_Destroy(OWF_ATTRIBUTE_LIST* aContext);

   162 

   163 /*

   164  * \brief Gets the last error from the attribute.

   165  * Resets the error state.

   166  *

   167  * \return	Error code.

   168  *

   169  */

   170 OWF_API_CALL OWF_ATTRIBUTE_LIST_STATUS

   171 OWF_AttributeList_GetError(OWF_ATTRIBUTE_LIST* aContext);

   172 

   173 /*

   174  * \brief Intialize integer attribute

   175  *

   176  * \param aContext Attibute context

   177  * \param aName Attribute name

   178  * \param aValue Attribute initial value

   179  * \param aRdOnly Read-only flag

   180  *

   181  * \return ERR_INVALID_ARGUMENT

   182  * ERR_INVALID_ATTRIBUTE

   183  * ERR_INVALID_CONTEXT

   184  */

   185 OWF_API_CALL void

   186 OWF_Attribute_Initi(OWF_ATTRIBUTE_LIST* aContext,

   187                     OWFint aName,

   188                     OWF_INT_REF aValue,

   189                     OWFboolean aRdOnly);

   190 

   191 /*

   192  * \brief Initialize float attribute

   193  *

   194  * \param aContext Attribute context

   195  * \param aName Attribute name

   196  * \param aValue Initial value for attribute

   197  * \param aRdOnly Read-only flag

   198  *

   199  * \return ERR_INVALID_ARGUMENT

   200  * ERR_INVALID_ATTRIBUTE

   201  * ERR_INVALID_CONTEXT

   202  */

   203 OWF_API_CALL void

   204 OWF_Attribute_Initf(OWF_ATTRIBUTE_LIST* aContext,

   205                     OWFint aName,

   206                     OWF_FLOAT_REF aValue,

   207                     OWFboolean aRdOnly);

   208 

   209 /*

   210  * \brief Initialize boolean attribute

   211  *

   212  * \param aContext Attribute context

   213  * \param aName Attribute name

   214  * \param aValue Initial value for attribute

   215  * \param aRdOnly Read-only flag

   216  *

   217  * \return ERR_INVALID_ARGUMENT

   218  * ERR_INVALID_ATTRIBUTE

   219  * ERR_INVALID_CONTEXT

   220  */

   221 OWF_API_CALL void

   222 OWF_Attribute_Initb(OWF_ATTRIBUTE_LIST* aContext,

   223                     OWFint aName,

   224                     OWF_BOOL_REF aValue,

   225                     OWFboolean aRdOnly);

   226 

   227 /*

   228  * \brief Initialize vector attribute

   229  *

   230  * \param aContext Attribute context

   231  * \param aName Attribute name

   232  * \param aLength Attribute (vector) length

   233  * \param aValues Initial value(s) for attribute

   234  * \param aRdOnly Read-only flag

   235  *

   236  * \return ERR_INVALID_ARGUMENT

   237  * ERR_INVALID_ATTRIBUTE

   238  * ERR_INVALID_CONTEXT

   239  * ERR_CANT_HANDLE

   240  */

   241 OWF_API_CALL void

   242 OWF_Attribute_Initiv(OWF_ATTRIBUTE_LIST* aContext,

   243                      OWFint aName,

   244                      OWFint aLength,

   245                      OWF_INT_VECTOR_REF aValues,

   246                      OWFboolean aRdOnly);

   247 

   248 /*

   249  * \brief Initialize vector attribute

   250  *

   251  * \param aContext Attribute context

   252  * \param aName Attribute name

   253  * \param aLength Attribute (vector) length

   254  * \param aValues Initial value(s) for attributes

   255  * \param aRdOnly Read-only flag

   256  *

   257  * \return

   258  */

   259 OWF_API_CALL void

   260 OWF_Attribute_Initfv(OWF_ATTRIBUTE_LIST* aContext,

   261                      OWFint aName,

   262                      OWFint aLength,

   263                      OWF_FLOAT_VECTOR_REF aValues,

   264                      OWFboolean aRdOnly);

   265 

   266 /*

   267  * \brief Get attribute integer value.

   268  *

   269  * \param aContext Attribute context

   270  * \param aName Attribute name

   271  *

   272  * \return Attribute integer value (floats are floor()ed). For vector

   273  * attributes the return value will be error ERR_INVALID_TYPE.

   274  * ERR_INVALID_ATTRIBUTE

   275  * ERR_INVALID_CONTEXT

   276  */

   277 OWF_API_CALL OWFint

   278 OWF_Attribute_GetValuei(OWF_ATTRIBUTE_LIST* aContext,

   279                         OWFint aName);

   280 

   281 /*

   282  * \brief Return boolean attribute value

   283  *

   284  * \param aContext Attribute context

   285  * \param aName Attribute name

   286  *

   287  * \return Attribute value

   288  * ERR_INVALID_ATTRIBUTE

   289  * ERR_INVALID_TYPE

   290  */

   291 OWF_API_CALL OWFboolean

   292 OWF_Attribute_GetValueb(OWF_ATTRIBUTE_LIST* aContext,

   293                         OWFint aName);

   294 

   295 /*

   296  * \brief Get attribute float value

   297  *

   298  * \param aContext

   299  * \param aName

   300  * \param aValue

   301  *

   302  * \return Attribute

   303  */

   304 OWF_API_CALL OWFfloat

   305 OWF_Attribute_GetValuef(OWF_ATTRIBUTE_LIST* aContext,

   306                         OWFint aName);

   307 

   308 /*

   309  * \brief

   310  *

   311  * \param aContext

   312  * \param aName

   313  * \param aSize

   314  * \param aValue

   315  *

   316  * \return

   317  */

   318 OWF_API_CALL OWFint

   319 OWF_Attribute_GetValueiv(OWF_ATTRIBUTE_LIST* aContext,

   320                          OWFint aName,

   321                          OWFint aLength,

   322                          OWFint* aValue);

   323 

   324 /*

   325  * \brief

   326  *

   327  * \param aContext

   328  * \param aName

   329  * \param aSize

   330  * \param aValue

   331  *

   332  * \return

   333  */

   334 OWF_API_CALL OWFint

   335 OWF_Attribute_GetValuefv(OWF_ATTRIBUTE_LIST* aContext,

   336                          OWFint aName,

   337                          OWFint aLength,

   338                          OWFfloat* aValue);

   339 

   340 /*

   341  * \brief

   342  *

   343  * \param aContext

   344  * \param aName

   345  * \param aValue

   346  *

   347  * \return

   348  */

   349 OWF_API_CALL void

   350 OWF_Attribute_SetValuei(OWF_ATTRIBUTE_LIST* aContext,

   351                         OWFint aName,

   352                         OWFint aValue);

   353 

   354 /*

   355  * \brief

   356  *

   357  * \param aContext

   358  * \param aName

   359  * \param aValue

   360  *

   361  * \return

   362  */

   363 OWF_API_CALL void

   364 OWF_Attribute_SetValuef(OWF_ATTRIBUTE_LIST* aContext,

   365                         OWFint aName,

   366                         OWFfloat aValue);

   367 

   368 /*

   369  * \brief

   370  *

   371  * \param

   372  * \param

   373  * \param

   374  *

   375  * \return

   376  */

   377 OWF_API_CALL void

   378 OWF_Attribute_SetValueb(OWF_ATTRIBUTE_LIST* aContext,

   379                         OWFint aName,

   380                         OWFboolean aValue);

   381 

   382 /*

   383  * \brief

   384  *

   385  * \param

   386  * \param

   387  * \param

   388  *

   389  * \return

   390  */

   391 OWF_API_CALL void

   392 OWF_Attribute_SetValueiv(OWF_ATTRIBUTE_LIST* aContext,

   393                          OWFint aName,

   394                          OWFint aLength,

   395                          const OWFint* aValue);

   396 

   397 /*

   398  * \brief

   399  *

   400  * \param

   401  * \param

   402  * \param

   403  *

   404  * \return

   405  */

   406 OWF_API_CALL void

   407 OWF_Attribute_SetValuefv(OWF_ATTRIBUTE_LIST* aContext,

   408                          OWFint aName,

   409                          OWFint aLength,

   410                          const OWFfloat* aValue);

   411 

   412 

   413 OWF_API_CALL void

   414 OWF_AttributeList_Commit(OWF_ATTRIBUTE_LIST* aContext, OWFint aStart, OWFint aEnd, OWFint aCopyTo );

   415 

   416 

   417 #ifdef __cplusplus

   418 }

   419 #endif

   420 

   421 #endif /* ATTRIBUTES_H_ */