os/graphics/graphicscomposition/openwfcompositionengine/common/include/owfattributes.h
author sl@SLION-WIN7.fritz.box
Fri, 15 Jun 2012 03:10:57 +0200
changeset 0 bde4ae8d615e
permissions -rw-r--r--
First public contribution.
     1 /* Copyright (c) 2009 The Khronos Group Inc.
     2  * Portions copyright (c) 2009-2010  Nokia Corporation and/or its subsidiary(-ies)
     3  *
     4  * Permission is hereby granted, free of charge, to any person obtaining a
     5  * copy of this software and/or associated documentation files (the
     6  * "Materials"), to deal in the Materials without restriction, including
     7  * without limitation the rights to use, copy, modify, merge, publish,
     8  * distribute, sublicense, and/or sell copies of the Materials, and to
     9  * permit persons to whom the Materials are furnished to do so, subject to
    10  * the following conditions:
    11  *
    12  * The above copyright notice and this permission notice shall be included
    13  * in all copies or substantial portions of the Materials.
    14  *
    15  * THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    18  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    19  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    20  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    21  * MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
    22  */
    23 
    24 #ifndef OWFATTRIBUTES_H_
    25 #define OWFATTRIBUTES_H_
    26 
    27 #include "owftypes.h"
    28 #include "owfutils.h"
    29 
    30 
    31 #ifdef __cplusplus
    32 extern "C"
    33 {
    34 #endif
    35 
    36 
    37 /*!
    38  *  \file Attribute interface
    39  *
    40  *  Attribute interface provides mechanism for controlled reading/writing
    41  *  access of different object properties in WFC and WFD APIs by proxying
    42  *  object instances' properties.
    43  *
    44  */
    45 #define RANGE_UNDEFINED     0xFFFFFFFF
    46 #define ATTR_LENGTH_BITS    20
    47 #define MAX_ATTR_LENGTH     (1 << ATTR_LENGTH_BITS)-1
    48 #define NUM_ATTR_VALUE_COPIES 3
    49 #define COMMITTED_ATTR_VALUE_INDEX 0
    50 #define WORKING_ATTR_VALUE_INDEX 1
    51 #define SNAPSHOT_ATTR_VALUE_INDEX 2
    52 #define COMMIT_ATTR_DIRECT_FROM_WORKING -1
    53 
    54 typedef enum {
    55     ATTR_ERROR_NONE             = 0,
    56     ATTR_ERROR_NOT_FOUND        = -1,
    57     ATTR_ERROR_ALREADY_IN_USE   = -2,
    58     ATTR_ERROR_INVALID_ATTRIBUTE= -3,
    59     ATTR_ERROR_INVALID_VALUE    = -4,
    60     ATTR_ERROR_INVALID_ARGUMENT = -5,
    61     ATTR_ERROR_INVALID_CONTEXT  = -6,
    62     ATTR_ERROR_NO_MEMORY        = -7,
    63     ATTR_ERROR_INSANE           = -8,
    64     ATTR_ERROR_ACCESS_DENIED    = -9,
    65     ATTR_ERROR_INVALID_TYPE     = -10,
    66     ATTR_ERROR_CANT_HANDLE      = -11
    67 } OWF_ATTRIBUTE_LIST_STATUS;
    68 
    69 /* Attribute value element types */
    70 typedef enum {
    71     AT_UNDEFINED = 0,
    72     AT_INTEGER = 1,
    73     AT_FLOAT = 2,
    74     AT_BOOLEAN = 3
    75 } OWF_ATTRIBUTE_TYPE;
    76 
    77 
    78 /*
    79  * Attribute information (header)
    80  *
    81  * Dirty field is internal. Do not fiddle with it.
    82  * 
    83  * Comment on use of bitfields: 
    84  * 1: It stops generic use of split dirty flag
    85  * 2: Some compilers will not reorder members to merge length into earier fields.
    86  */
    87 typedef struct {
    88     OWFuint                 type: 2;
    89     OWFuint                 dirty: 1;
    90     OWFuint                 dirtysnapshot: 1;
    91     OWFuint                 readonly: 1;
    92     OWFuint                 size;                       /* Size of one primitive */
    93     OWFuint                 length: ATTR_LENGTH_BITS;   /* Number of primitives in vector */
    94 } OWF_ATTRIBUTE_INFO;
    95 
    96 /*
    97  * Attribute may be a scalar (1-element) or vector (n-element),
    98  * containing a reference to either integer, boolean or float value(s).
    99  * Attribute type cannot be changed after it has been initialized.
   100  *
   101  * Attributes don't own the data they refer to; attributes only
   102  * control the reading and writing of the data they refer to.
   103  */
   104 
   105 typedef OWFfloat*           OWF_FLOAT_REF;
   106 typedef OWFint*             OWF_INT_REF;
   107 typedef OWFboolean*         OWF_BOOL_REF;
   108 typedef OWFfloat*           OWF_FLOAT_VECTOR_REF;
   109 typedef OWFint*             OWF_INT_VECTOR_REF;
   110 
   111 typedef struct {
   112     OWF_ATTRIBUTE_INFO      attr_info;
   113     union {
   114         OWF_INT_REF             int_value;
   115         OWF_FLOAT_REF           float_value;
   116         void*                   gen_ptr;
   117         /*
   118         OWF_INT_VECTOR_REF      int_vector_value;
   119         OWF_FLOAT_VECTOR_REF    float_vector_value;
   120         */
   121     } attr_value[NUM_ATTR_VALUE_COPIES];
   122 } OWF_ATTRIBUTE;
   123 
   124 /*
   125  * Attribute list/context. Container for attributes.
   126  *
   127  * One list/context can contain constant number of
   128  * attributes (amount of which is defined at construction
   129  * time)
   130  */
   131 typedef struct {
   132     OWFint                  range_start;
   133     OWFint                  range_end;
   134     OWF_ATTRIBUTE*          attributes;
   135     OWF_ATTRIBUTE_LIST_STATUS  last_error;
   136 } OWF_ATTRIBUTE_LIST;
   137 
   138 /*
   139  * \brief Initializes attribute context
   140  *
   141  * \param aContext Attribute context to initialize
   142  * \param aStart Attribute range start
   143  * \param aEnd Attribute range end. Must be greater than range start.
   144  *
   145  * \return ERR_INVALID_ARGUMENT
   146  * ERR_NO_MEMORY
   147  */
   148 OWF_API_CALL void
   149 OWF_AttributeList_Create(OWF_ATTRIBUTE_LIST* aContext,
   150                          OWFint aStart,
   151                          OWFint aEnd);
   152 
   153 /*
   154  * \brief Destroy attribute context and free any resources (memory
   155  * blocks) allocated to it. All attributes are destroyed.
   156  *
   157  * \param aContext Attribute context to destroy
   158  *
   159  * \return ERR_INVALID_ARGUMENT
   160  * ERR_INVALID_CONTEXT
   161  */
   162 OWF_API_CALL void
   163 OWF_AttributeList_Destroy(OWF_ATTRIBUTE_LIST* aContext);
   164 
   165 /*
   166  * \brief Gets the last error from the attribute.
   167  * Resets the error state.
   168  *
   169  * \return	Error code.
   170  *
   171  */
   172 OWF_API_CALL OWF_ATTRIBUTE_LIST_STATUS
   173 OWF_AttributeList_GetError(OWF_ATTRIBUTE_LIST* aContext);
   174 
   175 /*
   176  * \brief Intialize integer attribute
   177  *
   178  * \param aContext Attibute context
   179  * \param aName Attribute name
   180  * \param aValue Attribute initial value
   181  * \param aRdOnly Read-only flag
   182  *
   183  * \return ERR_INVALID_ARGUMENT
   184  * ERR_INVALID_ATTRIBUTE
   185  * ERR_INVALID_CONTEXT
   186  */
   187 OWF_API_CALL void
   188 OWF_Attribute_Initi(OWF_ATTRIBUTE_LIST* aContext,
   189                     OWFint aName,
   190                     OWF_INT_REF aValue,
   191                     OWFboolean aRdOnly);
   192 
   193 /*
   194  * \brief Initialize float attribute
   195  *
   196  * \param aContext Attribute context
   197  * \param aName Attribute name
   198  * \param aValue Initial value for attribute
   199  * \param aRdOnly Read-only flag
   200  *
   201  * \return ERR_INVALID_ARGUMENT
   202  * ERR_INVALID_ATTRIBUTE
   203  * ERR_INVALID_CONTEXT
   204  */
   205 OWF_API_CALL void
   206 OWF_Attribute_Initf(OWF_ATTRIBUTE_LIST* aContext,
   207                     OWFint aName,
   208                     OWF_FLOAT_REF aValue,
   209                     OWFboolean aRdOnly);
   210 
   211 /*
   212  * \brief Initialize boolean attribute
   213  *
   214  * \param aContext Attribute context
   215  * \param aName Attribute name
   216  * \param aValue Initial value for attribute
   217  * \param aRdOnly Read-only flag
   218  *
   219  * \return ERR_INVALID_ARGUMENT
   220  * ERR_INVALID_ATTRIBUTE
   221  * ERR_INVALID_CONTEXT
   222  */
   223 OWF_API_CALL void
   224 OWF_Attribute_Initb(OWF_ATTRIBUTE_LIST* aContext,
   225                     OWFint aName,
   226                     OWF_BOOL_REF aValue,
   227                     OWFboolean aRdOnly);
   228 
   229 /*
   230  * \brief Initialize vector attribute
   231  *
   232  * \param aContext Attribute context
   233  * \param aName Attribute name
   234  * \param aLength Attribute (vector) length
   235  * \param aValues Initial value(s) for attribute
   236  * \param aRdOnly Read-only flag
   237  *
   238  * \return ERR_INVALID_ARGUMENT
   239  * ERR_INVALID_ATTRIBUTE
   240  * ERR_INVALID_CONTEXT
   241  * ERR_CANT_HANDLE
   242  */
   243 OWF_API_CALL void
   244 OWF_Attribute_Initiv(OWF_ATTRIBUTE_LIST* aContext,
   245                      OWFint aName,
   246                      OWFint aLength,
   247                      OWF_INT_VECTOR_REF aValues,
   248                      OWFboolean aRdOnly);
   249 
   250 /*
   251  * \brief Initialize vector attribute
   252  *
   253  * \param aContext Attribute context
   254  * \param aName Attribute name
   255  * \param aLength Attribute (vector) length
   256  * \param aValues Initial value(s) for attributes
   257  * \param aRdOnly Read-only flag
   258  *
   259  * \return
   260  */
   261 OWF_API_CALL void
   262 OWF_Attribute_Initfv(OWF_ATTRIBUTE_LIST* aContext,
   263                      OWFint aName,
   264                      OWFint aLength,
   265                      OWF_FLOAT_VECTOR_REF aValues,
   266                      OWFboolean aRdOnly);
   267 
   268 /*
   269  * \brief Get attribute integer value.
   270  *
   271  * \param aContext Attribute context
   272  * \param aName Attribute name
   273  *
   274  * \return Attribute integer value (floats are floor()ed). For vector
   275  * attributes the return value will be error ERR_INVALID_TYPE.
   276  * ERR_INVALID_ATTRIBUTE
   277  * ERR_INVALID_CONTEXT
   278  */
   279 OWF_API_CALL OWFint
   280 OWF_Attribute_GetValuei(OWF_ATTRIBUTE_LIST* aContext,
   281                         OWFint aName);
   282 
   283 /*
   284  * \brief Return boolean attribute value
   285  *
   286  * \param aContext Attribute context
   287  * \param aName Attribute name
   288  *
   289  * \return Attribute value
   290  * ERR_INVALID_ATTRIBUTE
   291  * ERR_INVALID_TYPE
   292  */
   293 OWF_API_CALL OWFboolean
   294 OWF_Attribute_GetValueb(OWF_ATTRIBUTE_LIST* aContext,
   295                         OWFint aName);
   296 
   297 /*
   298  * \brief Get attribute float value
   299  *
   300  * \param aContext
   301  * \param aName
   302  * \param aValue
   303  *
   304  * \return Attribute
   305  */
   306 OWF_API_CALL OWFfloat
   307 OWF_Attribute_GetValuef(OWF_ATTRIBUTE_LIST* aContext,
   308                         OWFint aName);
   309 
   310 /*
   311  * \brief
   312  *
   313  * \param aContext
   314  * \param aName
   315  * \param aSize
   316  * \param aValue
   317  *
   318  * \return
   319  */
   320 OWF_API_CALL OWFint
   321 OWF_Attribute_GetValueiv(OWF_ATTRIBUTE_LIST* aContext,
   322                          OWFint aName,
   323                          OWFint aLength,
   324                          OWFint* aValue);
   325 
   326 /*
   327  * \brief
   328  *
   329  * \param aContext
   330  * \param aName
   331  * \param aSize
   332  * \param aValue
   333  *
   334  * \return
   335  */
   336 OWF_API_CALL OWFint
   337 OWF_Attribute_GetValuefv(OWF_ATTRIBUTE_LIST* aContext,
   338                          OWFint aName,
   339                          OWFint aLength,
   340                          OWFfloat* aValue);
   341 
   342 /*
   343  * \brief
   344  *
   345  * \param aContext
   346  * \param aName
   347  * \param aValue
   348  *
   349  * \return
   350  */
   351 OWF_API_CALL void
   352 OWF_Attribute_SetValuei(OWF_ATTRIBUTE_LIST* aContext,
   353                         OWFint aName,
   354                         OWFint aValue);
   355 
   356 /*
   357  * \brief
   358  *
   359  * \param aContext
   360  * \param aName
   361  * \param aValue
   362  *
   363  * \return
   364  */
   365 OWF_API_CALL void
   366 OWF_Attribute_SetValuef(OWF_ATTRIBUTE_LIST* aContext,
   367                         OWFint aName,
   368                         OWFfloat aValue);
   369 
   370 /*
   371  * \brief
   372  *
   373  * \param
   374  * \param
   375  * \param
   376  *
   377  * \return
   378  */
   379 OWF_API_CALL void
   380 OWF_Attribute_SetValueb(OWF_ATTRIBUTE_LIST* aContext,
   381                         OWFint aName,
   382                         OWFboolean aValue);
   383 
   384 /*
   385  * \brief
   386  *
   387  * \param
   388  * \param
   389  * \param
   390  *
   391  * \return
   392  */
   393 OWF_API_CALL void
   394 OWF_Attribute_SetValueiv(OWF_ATTRIBUTE_LIST* aContext,
   395                          OWFint aName,
   396                          OWFint aLength,
   397                          const OWFint* aValue);
   398 
   399 /*
   400  * \brief
   401  *
   402  * \param
   403  * \param
   404  * \param
   405  *
   406  * \return
   407  */
   408 OWF_API_CALL void
   409 OWF_Attribute_SetValuefv(OWF_ATTRIBUTE_LIST* aContext,
   410                          OWFint aName,
   411                          OWFint aLength,
   412                          const OWFfloat* aValue);
   413 
   414 
   415 OWF_API_CALL void
   416 OWF_AttributeList_Commit(OWF_ATTRIBUTE_LIST* aContext, OWFint aStart, OWFint aEnd, OWFint aCopyTo );
   417 
   418 
   419 #ifdef __cplusplus
   420 }
   421 #endif
   422 
   423 #endif /* ATTRIBUTES_H_ */