Home | History | Annotate | Download | only in pipe
      1 /**************************************************************************
      2  *
      3  * Copyright 2007 VMware, Inc.
      4  * All Rights Reserved.
      5  *
      6  * Permission is hereby granted, free of charge, to any person obtaining a
      7  * copy of this software and associated documentation files (the
      8  * "Software"), to deal in the Software without restriction, including
      9  * without limitation the rights to use, copy, modify, merge, publish,
     10  * distribute, sub license, and/or sell copies of the Software, and to
     11  * permit persons to whom the Software is furnished to do so, subject to
     12  * the following conditions:
     13  *
     14  * The above copyright notice and this permission notice (including the
     15  * next paragraph) shall be included in all copies or substantial portions
     16  * of the Software.
     17  *
     18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
     19  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
     20  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
     21  * IN NO EVENT SHALL VMWARE AND/OR ITS SUPPLIERS BE LIABLE FOR
     22  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
     23  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
     24  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
     25  *
     26  **************************************************************************/
     27 
     28 /**
     29  * @file
     30  *
     31  * Screen, Adapter or GPU
     32  *
     33  * These are driver functions/facilities that are context independent.
     34  */
     35 
     36 
     37 #ifndef P_SCREEN_H
     38 #define P_SCREEN_H
     39 
     40 
     41 #include "pipe/p_compiler.h"
     42 #include "pipe/p_format.h"
     43 #include "pipe/p_defines.h"
     44 #include "pipe/p_video_enums.h"
     45 
     46 
     47 
     48 #ifdef __cplusplus
     49 extern "C" {
     50 #endif
     51 
     52 
     53 /** Opaque types */
     54 struct winsys_handle;
     55 struct pipe_fence_handle;
     56 struct pipe_resource;
     57 struct pipe_surface;
     58 struct pipe_transfer;
     59 struct pipe_box;
     60 struct pipe_memory_info;
     61 
     62 
     63 /**
     64  * Gallium screen/adapter context.  Basically everything
     65  * hardware-specific that doesn't actually require a rendering
     66  * context.
     67  */
     68 struct pipe_screen {
     69    void (*destroy)( struct pipe_screen * );
     70 
     71    const char *(*get_name)( struct pipe_screen * );
     72 
     73    const char *(*get_vendor)( struct pipe_screen * );
     74 
     75    /**
     76     * Returns the device vendor.
     77     *
     78     * The returned value should return the actual device vendor/manufacturer,
     79     * rather than a potentially generic driver string.
     80     */
     81    const char *(*get_device_vendor)( struct pipe_screen * );
     82 
     83    /**
     84     * Query an integer-valued capability/parameter/limit
     85     * \param param  one of PIPE_CAP_x
     86     */
     87    int (*get_param)( struct pipe_screen *, enum pipe_cap param );
     88 
     89    /**
     90     * Query a float-valued capability/parameter/limit
     91     * \param param  one of PIPE_CAP_x
     92     */
     93    float (*get_paramf)( struct pipe_screen *, enum pipe_capf param );
     94 
     95    /**
     96     * Query a per-shader-stage integer-valued capability/parameter/limit
     97     * \param param  one of PIPE_CAP_x
     98     */
     99    int (*get_shader_param)( struct pipe_screen *, unsigned shader, enum pipe_shader_cap param );
    100 
    101    /**
    102     * Query an integer-valued capability/parameter/limit for a codec/profile
    103     * \param param  one of PIPE_VIDEO_CAP_x
    104     */
    105    int (*get_video_param)( struct pipe_screen *,
    106 			   enum pipe_video_profile profile,
    107 			   enum pipe_video_entrypoint entrypoint,
    108 			   enum pipe_video_cap param );
    109 
    110    /**
    111     * Query a compute-specific capability/parameter/limit.
    112     * \param ir_type shader IR type for which the param applies, or don't care
    113     *                if the param is not shader related
    114     * \param param   one of PIPE_COMPUTE_CAP_x
    115     * \param ret     pointer to a preallocated buffer that will be
    116     *                initialized to the parameter value, or NULL.
    117     * \return        size in bytes of the parameter value that would be
    118     *                returned.
    119     */
    120    int (*get_compute_param)(struct pipe_screen *,
    121 			    enum pipe_shader_ir ir_type,
    122 			    enum pipe_compute_cap param,
    123 			    void *ret);
    124 
    125    /**
    126     * Query a timestamp in nanoseconds. The returned value should match
    127     * PIPE_QUERY_TIMESTAMP. This function returns immediately and doesn't
    128     * wait for rendering to complete (which cannot be achieved with queries).
    129     */
    130    uint64_t (*get_timestamp)(struct pipe_screen *);
    131 
    132    /**
    133     * Create a context.
    134     *
    135     * \param screen      pipe screen
    136     * \param priv        a pointer to set in pipe_context::priv
    137     * \param flags       a mask of PIPE_CONTEXT_* flags
    138     */
    139    struct pipe_context * (*context_create)(struct pipe_screen *screen,
    140 					   void *priv, unsigned flags);
    141 
    142    /**
    143     * Check if the given pipe_format is supported as a texture or
    144     * drawing surface.
    145     * \param bindings  bitmask of PIPE_BIND_*
    146     */
    147    boolean (*is_format_supported)( struct pipe_screen *,
    148                                    enum pipe_format format,
    149                                    enum pipe_texture_target target,
    150                                    unsigned sample_count,
    151                                    unsigned bindings );
    152 
    153    /**
    154     * Check if the given pipe_format is supported as output for this codec/profile.
    155     * \param profile  profile to check, may also be PIPE_VIDEO_PROFILE_UNKNOWN
    156     */
    157    boolean (*is_video_format_supported)( struct pipe_screen *,
    158                                          enum pipe_format format,
    159                                          enum pipe_video_profile profile,
    160                                          enum pipe_video_entrypoint entrypoint );
    161 
    162    /**
    163     * Check if we can actually create the given resource (test the dimension,
    164     * overall size, etc).  Used to implement proxy textures.
    165     * \return TRUE if size is OK, FALSE if too large.
    166     */
    167    boolean (*can_create_resource)(struct pipe_screen *screen,
    168                                   const struct pipe_resource *templat);
    169 
    170    /**
    171     * Create a new texture object, using the given template info.
    172     */
    173    struct pipe_resource * (*resource_create)(struct pipe_screen *,
    174 					     const struct pipe_resource *templat);
    175 
    176    struct pipe_resource * (*resource_create_front)(struct pipe_screen *,
    177                                                    const struct pipe_resource *templat,
    178                                                    const void *map_front_private);
    179 
    180    /**
    181     * Create a texture from a winsys_handle. The handle is often created in
    182     * another process by first creating a pipe texture and then calling
    183     * resource_get_handle.
    184     *
    185     * NOTE: in the case of DRM_API_HANDLE_TYPE_FD handles, the caller
    186     * retains ownership of the FD.  (This is consistent with
    187     * EGL_EXT_image_dma_buf_import)
    188     *
    189     * \param usage  A combination of PIPE_HANDLE_USAGE_* flags.
    190     */
    191    struct pipe_resource * (*resource_from_handle)(struct pipe_screen *,
    192 						  const struct pipe_resource *templat,
    193 						  struct winsys_handle *handle,
    194 						  unsigned usage);
    195 
    196    /**
    197     * Create a resource from user memory. This maps the user memory into
    198     * the device address space.
    199     */
    200    struct pipe_resource * (*resource_from_user_memory)(struct pipe_screen *,
    201                                                        const struct pipe_resource *t,
    202                                                        void *user_memory);
    203 
    204    /**
    205     * Get a winsys_handle from a texture. Some platforms/winsys requires
    206     * that the texture is created with a special usage flag like
    207     * DISPLAYTARGET or PRIMARY.
    208     *
    209     * The context parameter can optionally be used to flush the resource and
    210     * the context to make sure the resource is coherent with whatever user
    211     * will use it. Some drivers may also use the context to convert
    212     * the resource into a format compatible for sharing. The use case is
    213     * OpenGL-OpenCL interop. The context parameter is allowed to be NULL.
    214     *
    215     * NOTE: in the case of DRM_API_HANDLE_TYPE_FD handles, the caller
    216     * takes ownership of the FD.  (This is consistent with
    217     * EGL_MESA_image_dma_buf_export)
    218     *
    219     * \param usage  A combination of PIPE_HANDLE_USAGE_* flags.
    220     */
    221    boolean (*resource_get_handle)(struct pipe_screen *,
    222                                   struct pipe_context *context,
    223 				  struct pipe_resource *tex,
    224 				  struct winsys_handle *handle,
    225 				  unsigned usage);
    226 
    227 
    228    void (*resource_destroy)(struct pipe_screen *,
    229 			    struct pipe_resource *pt);
    230 
    231 
    232    /**
    233     * Do any special operations to ensure frontbuffer contents are
    234     * displayed, eg copy fake frontbuffer.
    235     * \param winsys_drawable_handle  an opaque handle that the calling context
    236     *                                gets out-of-band
    237     * \param subbox an optional sub region to flush
    238     */
    239    void (*flush_frontbuffer)( struct pipe_screen *screen,
    240                               struct pipe_resource *resource,
    241                               unsigned level, unsigned layer,
    242                               void *winsys_drawable_handle,
    243                               struct pipe_box *subbox );
    244 
    245    /** Set ptr = fence, with reference counting */
    246    void (*fence_reference)( struct pipe_screen *screen,
    247                             struct pipe_fence_handle **ptr,
    248                             struct pipe_fence_handle *fence );
    249 
    250    /**
    251     * Wait for the fence to finish.
    252     *
    253     * If the fence was created with PIPE_FLUSH_DEFERRED, and the context is
    254     * still unflushed, and the ctx parameter of fence_finish is equal to
    255     * the context where the fence was created, fence_finish will flush
    256     * the context prior to waiting for the fence.
    257     *
    258     * In all other cases, the ctx parameter has no effect.
    259     *
    260     * \param timeout  in nanoseconds (may be PIPE_TIMEOUT_INFINITE).
    261     */
    262    boolean (*fence_finish)(struct pipe_screen *screen,
    263                            struct pipe_context *ctx,
    264                            struct pipe_fence_handle *fence,
    265                            uint64_t timeout);
    266 
    267    /**
    268     * For fences created with PIPE_FLUSH_FENCE_FD (exported fd) or
    269     * by create_fence_fd() (imported fd), return the native fence fd
    270     * associated with the fence.  This may return -1 for fences
    271     * created with PIPE_FLUSH_DEFERRED if the fence command has not
    272     * been flushed yet.
    273     */
    274    int (*fence_get_fd)(struct pipe_screen *screen,
    275                        struct pipe_fence_handle *fence);
    276 
    277    /**
    278     * Returns a driver-specific query.
    279     *
    280     * If \p info is NULL, the number of available queries is returned.
    281     * Otherwise, the driver query at the specified \p index is returned
    282     * in \p info. The function returns non-zero on success.
    283     */
    284    int (*get_driver_query_info)(struct pipe_screen *screen,
    285                                 unsigned index,
    286                                 struct pipe_driver_query_info *info);
    287 
    288    /**
    289     * Returns a driver-specific query group.
    290     *
    291     * If \p info is NULL, the number of available groups is returned.
    292     * Otherwise, the driver query group at the specified \p index is returned
    293     * in \p info. The function returns non-zero on success.
    294     */
    295    int (*get_driver_query_group_info)(struct pipe_screen *screen,
    296                                       unsigned index,
    297                                       struct pipe_driver_query_group_info *info);
    298 
    299    /**
    300     * Query information about memory usage.
    301     */
    302    void (*query_memory_info)(struct pipe_screen *screen,
    303                              struct pipe_memory_info *info);
    304 
    305    /**
    306     * Get IR specific compiler options struct.  For PIPE_SHADER_IR_NIR this
    307     * returns a 'struct nir_shader_compiler_options'.  Drivers reporting
    308     * NIR as the preferred IR must implement this.
    309     */
    310    const void *(*get_compiler_options)(struct pipe_screen *screen,
    311                                       enum pipe_shader_ir ir,
    312                                       unsigned shader);
    313 };
    314 
    315 
    316 #ifdef __cplusplus
    317 }
    318 #endif
    319 
    320 #endif /* P_SCREEN_H */
    321