/**************************************************************************** * * Copyright 2012 - 2020 Vivante Corporation, Santa Clara, California. * All Rights Reserved. * * Permission is hereby granted, free of charge, to any person obtaining * a copy of this software and associated documentation files (the * 'Software'), to deal in the Software without restriction, including * without limitation the rights to use, copy, modify, merge, publish, * distribute, sub license, and/or sell copies of the Software, and to * permit persons to whom the Software is furnished to do so, subject * to the following conditions: * * The above copyright notice and this permission notice (including the * next paragraph) shall be included in all copies or substantial * portions of the Software. * * THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. * IN NO EVENT SHALL VIVANTE AND/OR ITS SUPPLIERS BE LIABLE FOR ANY * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. * *****************************************************************************/ #ifndef ELM_H_ #define ELM_H_ #ifdef __cplusplus extern "C" { #endif #define ELM_VERSION 0x00010000 /* Current Version: 1.0. */ #define ELM_NULL_HANDLE 0 /*! NULL object handle, represent a void object. */ /*! @typedef ELM_EVO_PROP_BIT evo property bits to control evo manipulation. */ typedef enum { ELM_PROP_ROTATE_BIT = 1 << 0, /*! rotate bit of evo/ego/ebo transformation property. */ ELM_PROP_TRANSFER_BIT = 1 << 1, /*! transfer bit of evo/ego/ebo transformation property. */ ELM_PROP_SCALE_BIT = 1 << 2, /*! scale bit of evo/ego/ebo transformation property. */ ELM_PROP_BLEND_BIT = 1 << 3, /*! blending bit of evo/ebo rendering property. */ ELM_PROP_QUALITY_BIT = 1 << 4, /*! quality bit of evo/ebo rendering property. */ ELM_PROP_FILL_BIT = 1 << 5, /*! fill rule bit of evo rendering property. */ ELM_PROP_COLOR_BIT = 1 << 6, /*! fill color bit of evo rendering property. */ ELM_PROP_PAINT_BIT = 1 << 7, /*! paint type bit of evo. */ ELM_PROP_ALL_BIT = 0xFFFFFFFF, /*! all transformation property bits of evo. */ } ELM_EVO_PROP_BIT; /*! @typedef ELM_EVO_BLEND The blending property of the evo object when it's drawn. D is Destination color, S is Source color; Da is Destination alpha, S is Source alpha. */ typedef enum { ELM_BLEND_NONE = 0, /*! D = S. */ ELM_BLEND_SRC_OVER, /*! D = S + (1 - Sa) * D */ ELM_BLEND_DST_OVER, /*! D = (1 - Da) * S + D */ ELM_BLEND_SRC_IN, /*! D = Da * S */ ELM_BLEND_DST_IN, /*! D = Sa * D */ ELM_BLEND_SCR, /*! D = S + D - S * D */ ELM_BLEND_MUL, /*! D = S * (1 - Da) + D * (1 - Sa) + S * D */ ELM_BLEND_ADD, /*! S + D */ ELM_BLEND_SUB /*! D * (1 - S) */ } ELM_BLEND; /*! @typedef ELM_EVO_QUALITY The drawing quality of the evo object. */ typedef enum { ELM_QUALITY_LOW = 0, /*! NOAA for evo, POINT SAMPLE for ebo. */ ELM_QUALITY_MED = 1, /*! 2XAA for evo, LINEAR SAMPLE for ebo. */ ELM_QULIATY_HI = 2, /*! 4XAA for evo, BI-LINEAR SAMPLE for ebo. */ } ELM_QUALITY; /*! @typedef ELM_PAINT_TYPE Those are types for evo fill paint. COLOR means solid color fill; PATTERN means fill with an image (evo); GRADIENT means fill with linear gradient. */ typedef enum { ELM_PAINT_COLOR = 0, /*! Paint evo with solid color */ ELM_PAINT_PATTERN = 1, /*! Paint evo with ebo */ ELM_PAINT_GRADIENT = 2, /*! Paint evo with a linear gradient built-in evo object */ ELM_PAINT_RADIAL_GRADIENT = 3, /*! Paint evo with a radial gradient built-in evo object */ ELM_PAINT_TEXT = 4, /*! Paint evo-text */ } ELM_PAINT_TYPE; /*! @typedef ELM_PATTERN_MODE Those are enum types for pattern fill mode. COLOR means fill the area outside the pattern with a solid color; PAD means extend the border color to the area outside the pattern. */ typedef enum { ELM_PATTERN_MODE_COLOR = 0, ELM_PATTERN_MODE_PAD = 1, } ELM_PATTERN_MODE; /*! @typedef ELM_EVO_FILL The filling rule of for an evo object. EO = EVEN_ODD; NZ = NONE_ZERO; */ typedef enum { ELM_EVO_FILL_NZ = 0, /*! none-zero fill rule */ ELM_EVO_FILL_EO = 1, /*! Even-odd fill rule */ } ELM_EVO_FILL; /*! @typedef ELM_EVO_TYPE the type of an evo object. could be pathes, images, or a group which contains other EVOs. */ typedef enum { ELM_OBJECT_TYPE_EVO = 0, /*! elementary vector object, representing a path object. */ ELM_OBJECT_TYPE_EGO = 1, /*! elementary group object, containing multiple path objects. */ ELM_OBJECT_TYPE_EBO = 2, /*! elementary bitmap object, representing image data. */ ELM_OBJECT_TYPE_BUF = 3, /*! rendering buffer object, created by application. */ ELM_OBJECT_TYPE_FONT = 4, /*! elementary font object, representing character data. */ ELM_OBJECT_TYPE_TEXT = 5, /*! elementary text object, representing text data. */ } ELM_OBJECT_TYPE; /*! @typedef ELM_BUFFER_FORMAT Enumeration for buffer format, all format name definiton is sequenced from LSB to MSB. */ typedef enum { ELM_BUFFER_FORMAT_RGBA8888, /*! 32-bit RGBA format with 8 bits per color channel. Red is in bits 7:0, green in bits 15:8, blue in bits 23:16, and the alpha channel is in bits 31:24. */ ELM_BUFFER_FORMAT_BGRA8888, /*! 32-bit RGBA format with 8 bits per color channel. Red is in bits 23:16, green in bits 15:8, blue in bits 7:0, and the alpha channel is in bits 31:24. */ ELM_BUFFER_FORMAT_RGBX8888, /*! 32-bit RGBX format with 8 bits per color channel. Red is in bits 7:0, green in bits 15:8, blue in bits 23:16, and the x channel is in bits 31:24. */ ELM_BUFFER_FORMAT_BGRX8888, /*! 32-bit RGBX format with 8 bits per color channel. Red is in bits 23:16, green in bits 15:8, blue in bits 7:0, and the x channel is in bits 31:24. */ ELM_BUFFER_FORMAT_RGB565, /*! 16-bit RGB format with 5 and 6 bits per color channel. Red is in bits 4:0, green in bits 10:5, and the blue color channel is in bits 15:11. */ ELM_BUFFER_FORMAT_BGR565, /*! 16-bit RGB format with 5 and 6 bits per color channel. Red is in bits 15:11, green in bits 10:5, and the blue color channel is in bits 4:0. */ ELM_BUFFER_FORMAT_RGBA4444, /*! 16-bit RGBA format with 4 bits per color channel. Red is in bits 3:0, green in bits 7:4, blue in bits 11:8 and the alpha channel is in bits 15:12. */ ELM_BUFFER_FORMAT_BGRA4444, /*! 16-bit RGBA format with 4 bits per color channel. Red is in bits 11:8, green in bits 7:4, blue in bits 3:0 and the alpha channel is in bits 15:12. */ ELM_BUFFER_FORMAT_BGRA5551, /*! 16-bit RGBA format with 4 bits per color channel. Red is in bits 14:10, green in bits 9:5, blue in bits 4:0 and the alpha channel is in bit 15:15. */ ELM_BUFFER_FORMAT_INDEX_1, /*! 1-bit indexed format. */ ELM_BUFFER_FORMAT_INDEX_2, /*! 2-bits indexed format. */ ELM_BUFFER_FORMAT_INDEX_4, /*! 4-bits indexed format. */ ELM_BUFFER_FORMAT_INDEX_8, /*! 8-bits indexed format. */ } ELM_BUFFER_FORMAT; /*! @typedef ElmHandle common handle type for object reference. */ typedef unsigned int ElmHandle; /*! @typedef ElmVecObj evo object handle (elemtry vector object). Created from an external binary evo file. */ typedef ElmHandle ElmVecObj; /*! @typedef ElmBitmapObj ebo object handle (elementry image object). Created from an external ebo file. */ typedef ElmHandle ElmBitmapObj; /*! @typedef ElmGroupObj group object handle. Create from an external ego file. */ typedef ElmHandle ElmGroupObj; /*! @typedef ElmBuffer render buffer object handle. */ typedef ElmHandle ElmBuffer; #define TRUE 1 #define FALSE 0 /*! @typedef BOOL boolean type define. */ typedef unsigned int BOOL; /*! @abstract Initialize Elementary context. @discussion It should be called as the first function of Elemenatary libary, which initializes the library. Currently Elementary library doesn't support context concept, neigher multi-threading. Elementary library defines origin of coordinate system is at top-left. @param none @return none */ BOOL ElmInitialize(uint32_t width, uint32_t height); /*! @abstract Terminate Elementary context. @discussion This should be called when an app exits. It frees all the resource. @param none @return none */ void ElmTerminate(void); /*! @abstract Create an elementary object from an existing binary file. @discussion This function creates an elementary object from the file whose file name is specified by param name. Caller must match type with the binary file, otherwise create mail fail by returning ELM_NULL_HANDLE. @param type Specify what type of object to be created. @param name The name of the binary resource file. @return ElmHandle An object handle depending on the corresponding type. If type mismatches, it returns ELM_NULL_HANDLE. */ ElmHandle ElmCreateObjectFromFile(ELM_OBJECT_TYPE type, const char *name); /*! @abstract Create an elementary object from build-in data within the appplication. @discussion This function creates an elementar object from local data pointer, which is specially useful for environment without filesystem support. @param type Specify what type of object to be created. @param data The pointer to the binary data which has exactly same layout as external resource file. @return ElmHandle An object handle depending on the corresponding type. If type mismatches with the binary data, it returns ELM_NULL_HANDLE. */ ElmHandle ElmCreateObjectFromData(ELM_OBJECT_TYPE type, void *data, int size); /*! @abstract Rotate a graphics object with centain degree @discussion This function sets an evo/ebo/ego object rotated with specified angle. Without reset, these setting will be accumulated. @param obj The graphics object will be rotated. @param angle A radian value to be applied on the evo object. @return bool Rotate is set successfully. */ BOOL ElmRotate(ElmHandle obj, float angle); /*! @abstract Transfer an graphics object at different directions. @discussion This function put an evo/ebo/ego object away at different directions. Without reset, the setting will be accumulated. @param obj The graphics object will be transfered. @param x The units in pixel of X direction. @param y The units in pixel of Y direction. @return bool Transfer is set successfully. */ BOOL ElmTransfer(ElmHandle obj, int x, int y); /*! @abstract Scale an graphics object at different directions. @discussion This function scale up or down an evo/ego/ebo object at different directions. Without reset, the setting will be accumateled. @param obj The graphics object which is targeted to manipulate. @param x The scale ratio in X direction. @param y The scale ratio in Y direction. @return bool Scale is set succefully. */ BOOL ElmScale(ElmHandle obj, float x, float y); /*! @abstract Reset the attribute of a graphics object for specified property bit. @discussion This funcion resets specified property for an elementary object. It can be applied all types of objects. But some properties are only valid for centain types of objects. If the function is called to reset an invalid property for this type of object, it will be siliently ignored. After reset, the specifed property of an evo/ebo/ego object is set to the initial state. The initial states are decided by the binary resource file. The resource creator should set right value for all properties if they want to directly render the object without any adjustment in application. There is one issue, at present, application has no way to query current value of each property, is it required? @param obj The graphics object which is targeted to manipulate. @param mask Specify which property or properties need to reset to initial value. @return bool Reset is done successfully. If some mask is not valid for this type of object, it would return false. */ BOOL ElmReset(ElmHandle obj, ELM_EVO_PROP_BIT mask); /*! @abstract Draw a graphics object onto current render target @discussion This is an enssentail function to do the real job, it takes all current setting of the elementary object and render into theb buffer target. @param buffer The render target that an elmentary object will be rendered into. @param obj The elmentary object will be draw into render target. @return bool The draw operation for this elmentary object is sucessful. */ BOOL ElmDraw(ElmBuffer buffer, ElmHandle object); /*! @abstract Set the rendering quality of an graphics object. @discussion This function sets the rendering quality of an evo/ebo object. Avaliable quality setting contains: ELM_EVO_QUALITY_LOW, ELM_EVO_QUALITY_MED, ELM_EVO_QUALITY_HI. This function is only applied to an evo or an ebo. Group object can't be set quality. It always use the setting from its binary. @param obj The elementary object. @param quality The quality enum. @return bool The operation for this object is sucessful, for group object and invalid enum, would return false. */ BOOL ElmSetQuality(ElmHandle obj, ELM_QUALITY quality); /*! @abstract Set the fill rule of an evo object. @discussion This function sets the fill rule of an elementary object. Avaliable quality setting contains: ELM_EVO_EO, ELM_EVO_NZ. It only applies to evo object. @param evo The evo object. @param fill The fill rule enum. @return bool The operation for this evo is sucessful. For non-evo object an ENUM is not a valid enum, would return false. */ BOOL ElmSetFill(ElmVecObj evo, ELM_EVO_FILL fill); /*! @abstract Set the blending mode of an evo/ebo object. @discussion This function sets the blending mode of an evo/ebo object. It's not applied to group object. @param obj The graphics object. @param blend The blending mode enum. @return bool The operation for this evo/ebo is sucessful. If object is a group object or blend mode is not a legal one, it would return false. */ BOOL ElmSetBlend(ElmHandle obj, ELM_BLEND blend); /*! @abstract Set the solid fill color of an evo object. @discussion This function sets the solid fill color of an evo object. @param evo The evo object. @param color The uint32 color value in rgba order. @return bool The operation for this evo is sucessful. If the object is not a evo object, it would return false. */ BOOL ElmSetColor(ElmVecObj evo, uint32_t color); /*! @abstract Set the image paint fill of an evo. @discussion This function sets the image pattern for filling an evo. The image pattern is a loaded ebo. The ebo's transformation is applied when drawing the evo. @param evo The evo object. @param pattern The image pattern to be set for the evo. @return bool The operation is successful or not. */ BOOL ElmSetPattern(ElmVecObj evo, ElmBitmapObj pattern); /*! @abstract Set the image paint fill of an evo. @discussion This function sets the image pattern for filling an evo. The image pattern is a loaded ebo. The ebo's transformation is applied when drawing the evo. @param evo The evo object. @param pattern The image pattern to be set for the evo. @return bool The operation is successful or not. */ BOOL ElmSetPatternMode(ElmVecObj evo, ELM_PATTERN_MODE mode, uint32_t color); /*! @abstract Set the paint type of an evo. @discussion This function selects the paint type for evo to use. An evo may have 3 types of paint: COLOR, PATTERN, and LINEAR GRADIENT. The Linear graident is always a built-in resource, which can not be altered. If a binary resource doesn't have built-in gradient paint resource, it can't be selected as the paint source. Solid color is also a built-in attribute, but it can be changed by ElmSetColor(). Paint with a pattern always need an external ebo object, which is impossible to be embedded in resource file,i.e. ebo object. Before select paint type to be PATTERN, ElmSetPattern() must be called to attach an EBO to an EVO. @param evo The evo object. @param type The paint type to be set for the evo. @return bool The operation is successful or not. If the corresponding type is not avaiable for the evo, it returns false and type paint type falls back to COLOR. */ BOOL ElmSetPaintType(ElmVecObj evo, ELM_PAINT_TYPE type); /*! @abstract Create internal render buffer. @discussion This functiois is to create an internal render buffer for Elementary rendering, ussually it's not for direct display. The buffer which is displayed on pannel is wrapped up by another API, whose address is managed by display controller side. @param width The buffer's width. @param height The buffer's height. @param format The buffer's format, check enumeration of ELM_BUFFER_FORMAT. @return The buffer handle. */ ElmBuffer ElmCreateBuffer(unsigned int width, unsigned int height, ELM_BUFFER_FORMAT format); /*! @abstract Wrap a customized buffer. @discussion The application may wrap a user created buffer by giving the information of the buffer including the size, the memory addresses and format. E.g., the application can wrap a system framebuffer thus ELM can directly render onto the screen. @return The buffer handle. */ ElmBuffer ElmWrapBuffer(int width, int height, int stride, void *logical, uint32_t physical, ELM_BUFFER_FORMAT format); /*! @abstract Get buffer address. @discussion The function is to get the address of ElmBuffer. @return The buffer address. */ uint32_t ElmGetBufferAddress(ElmBuffer buffer); /*! @abstract Destroy a render buffer. @discussion This function is to release all internal resource inside Elementary libary belonging to this buffer. Applicatoin need make sure the buffer is not being used by elmentary library any more when calling this function. @param buffer The render buffer handle @return If destroying is completed successfully. */ BOOL ElmDestroyBuffer(ElmBuffer buffer); /*! @abstract Save a buffer to PNG file. @discussion This function can save the buffer into a PNG file. @param buffer The render buffer handle. @param name The name of the PNG file to sve. @return Save OK or NOT. */ BOOL ElmSaveBuffer(ElmBuffer buffer, const char *name); /*! @abstract Clear a render buffer with specified color and dimension. @discussion This function is called to clear full or partial of the buffer. If the rectangle is out of buffer space, the intersect portion will be cleared. @param buffer A render buffer handle. @param color Clear color value. @param x x origin of partical clear rectangle. @param y y origin of partial clear rectangle. @param width width of partical clear rectangle. @param height height of partical clear rectangle. @param full Flag to indicate a full buffer clear. If true, the dimension parameters will be ignored. @return bool Indicate the clear operation is set up correctly. */ BOOL ElmClear(ElmBuffer buffer, uint32_t color, uint32_t x, uint32_t y, uint32_t width, uint32_t height, BOOL full); /*! @abstract Destroy an ELM object. @discussion This function is to release all internal resource inside Elementary libary belonging to this object. Applicatoin need make sure the object is not being used by elmentary library any more when calling this function. If an EBO is being destroyed and it's attached to one EVO, it need to guarantee that EVO is not being used by elementary library too. @param object The object handle @return If destroying is completed successfully. */ BOOL ElmDestroyObject(ElmHandle object); /*! @abstract Finish all rendering on GPU issued before this call. @discussion This function tells the engine that it has finished the frame data and GPU can draw it now. It's blocked until GPU rendering done. @return If the opeartion is successfully done or not. */ BOOL ElmFinish(); /*! @abstract Flush all rendering command to GPU issued before this call. @discussion This function tells the engine to start kicking off command to GPU side, it will return immediately after firing off GPU. @return If the opeartion is successfully done or not. */ BOOL ElmFlush(); /*! @abstract Query the paint color of an evo object. */ BOOL ElmGetColor(ElmVecObj evoHandle,uint32_t *color); /*! @abstract Query the vectory path count of an EGO object. If the given object is an evo/ebo, the count is 0. */ uint32_t ElmGetVectorCount(ElmHandle handle); /*! @abstract Query the type of an object (by handle). */ ELM_OBJECT_TYPE ElmGetObjectType(ElmHandle handle); /*! @abstract Set the current vectory object index to operate on. */ BOOL ElmSetCurrentVector(int32_t id); BOOL ElmScalePaint(ElmHandle handle, float sx, float sy); BOOL ElmRotatePaint(ElmHandle handle, float degrees); BOOL ElmTranslatePaint(ElmHandle handle, float tx, float ty); /*! @abstract Get handle of the framebuffer. */ ElmBuffer ElmGetBuffer(vg_lite_buffer_t *buffer); #ifdef __cplusplus } #endif #endif /* ELM_H_ */