middleware/khronos/egl/egl_disp.h

   1 /*
   2 Copyright (c) 2012, Broadcom Europe Ltd
   3 All rights reserved.
   4
   5 Redistribution and use in source and binary forms, with or without
   6 modification, are permitted provided that the following conditions are met:
   7     * Redistributions of source code must retain the above copyright
   8       notice, this list of conditions and the following disclaimer.
   9     * Redistributions in binary form must reproduce the above copyright
  10       notice, this list of conditions and the following disclaimer in the
  11       documentation and/or other materials provided with the distribution.
  12     * Neither the name of the copyright holder nor the
  13       names of its contributors may be used to endorse or promote products
  14       derived from this software without specific prior written permission.
  15
  16 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  17 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  18 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  19 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
  20 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  21 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  22 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  23 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  25 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26 */
  27
  28 #ifndef EGL_DISP_H
  29 #define EGL_DISP_H
  30
  31 #include "interface/khronos/common/khrn_int_common.h"
  32 #include "middleware/khronos/common/khrn_mem.h"
  33
  34 extern bool egl_disp_init(void);
  35 extern void egl_disp_term(void);
  36
  37 typedef enum {
  38    EGL_DISP_HANDLE_INVALID = -1,
  39    EGL_DISP_HANDLE_FORCE_32BIT = (int)0x80000000
  40 } EGL_DISP_HANDLE_T;
  41
  42 /* there are only a fixed number of handles available; EGL_DISP_HANDLE_INVALID
  43  * may be returned even when there is plenty of free memory. todo: fix this?
  44  *
  45  * khdispatch_send_async(ASYNC_COMMAND_POST, pid, sem) is called every time an
  46  * image comes off the display
  47  *
  48  * call from master task */
  49 extern EGL_DISP_HANDLE_T egl_disp_alloc(
  50    uint64_t pid, uint32_t sem,
  51    uint32_t n, const MEM_HANDLE_T *images);
  52
  53 /* this will not return until all images are off the display
  54  *
  55  * call from master task */
  56 extern void egl_disp_free(EGL_DISP_HANDLE_T disp_handle);
  57
  58 /* wait until we're ready to display the next image, ie we're idle. this implies
  59  * we won't call egl_server_platform_display until the next image comes along */
  60 extern void egl_disp_finish(EGL_DISP_HANDLE_T disp_handle);
  61
  62 /* equivalent to calling egl_disp_finish on all valid handles */
  63 extern void egl_disp_finish_all(void);
  64
  65 /* display the next image in the chain. image_handle is optional -- if provided,
  66  * it is merely checked against the handle of the image to be displayed
  67  *
  68  * we will wait (asynchronously) until the image is actually ready to be
  69  * displayed (ie there are no outstanding writes) before calling
  70  * egl_server_platform_display
  71  *
  72  * images are displayed in sequence (even if they become ready out of sequence)
  73  *
  74  * swap_interval is the minimum display time of the image in v-sync periods. a
  75  * swap_interval of 0 is special: in addition to not requiring any display time
  76  * at all, we won't hold back rendering to wait for the (previous) image to
  77  * come off the display. this can result in tearing
  78  *
  79  * the image parameters (size/stride) are read before returning from this
  80  * function to make resizing (in the case where the storage handle and size
  81  * aren't changed) safe. this won't prevent visual glitches with swap interval
  82  * 0
  83  *
  84  * call from master task */
  85 extern void egl_disp_next(EGL_DISP_HANDLE_T disp_handle,
  86    MEM_HANDLE_T image_handle, uint32_t win, uint32_t swap_interval);
  87
  88 typedef enum {
  89    EGL_DISP_SLOT_HANDLE_INVALID = -1,
  90    EGL_DISP_SLOT_HANDLE_FORCE_32BIT = (int)0x80000000
  91 } EGL_DISP_SLOT_HANDLE_T;
  92
  93 /* mark the slot as ready. if skip, the swap interval of the image is forced to
  94  * 0 and we won't actually display the image
  95  *
  96  * call from any task */
  97 extern void egl_disp_ready(EGL_DISP_SLOT_HANDLE_T slot_handle, bool skip);
  98
  99 typedef enum {
 100    EGL_DISP_IMAGE_HANDLE_INVALID = -1,
 101    EGL_DISP_IMAGE_HANDLE_FORCE_32BIT = (int)0x80000000
 102 } EGL_DISP_IMAGE_HANDLE_T;
 103
 104 /* wait until the image is not on the display. an image is considered to be on
 105  * the display between an egl_disp_next call that queues the image for display
 106  * and the image coming off the display
 107  *
 108  * call from master task */
 109 extern void egl_disp_wait(EGL_DISP_IMAGE_HANDLE_T image_handle);
 110
 111 /* post a wait-for-display message to fifo. this function will filter out
 112  * unnecessary waits, but otherwise just forwards (with transformed arguments)
 113  * to khrn_delayed_wait_for_display(). the wait-for-display message itself
 114  * should wait until egl_disp_on() returns false
 115  *
 116  * call egl_disp_post_wait() from master task. call egl_disp_on() from any
 117  * task */
 118 extern void egl_disp_post_wait(uint32_t fifo, EGL_DISP_IMAGE_HANDLE_T image_handle);
 119 extern bool egl_disp_on(EGL_DISP_HANDLE_T disp_handle, uint32_t pos);
 120
 121 extern void egl_disp_callback(uint32_t cb_arg);
 122
 123 #endif