Create a new surface
int gf_surface_create( gf_surface_t* psurface,
const gf_palette_t* palette,
unsigned flags );
- An address where the function can store a handle to the surface.
- The handle to the graphical device (acquired by gf_dev_attach()) that will manage the surface.
- w, h
- The width and height of the surface, in pixels.
- The gf_format_t display format of the surface. If you are using a packed type, you should pass the non-endian-specific variant to make your application more portable.
- A pointer to a gf_palette_t structure, which represents the surface palette. Pass NULL if the surface format isn't palette-based (GF_FORMAT_PAL8).
- Flags for the surface's properties. These can be:
- GF_SURFACE_CREATE_2D_ACCESSIBLE — the surface will be used by the 2D API (that is, rendered to and blitted from).
- GF_SURFACE_CREATE_3D_ACCESSIBLE — the surface will be used by the 3D API (OpenGL ES) or OpenVG API.
- GF_SURFACE_CREATE_ALPHA_MAP —
the surface must be usable as the alpha map source for 2D rendering.
- GF_SURFACE_CREATE_CPU_FAST_ACCESS — the surface is allocated so that CPU access speed is optimized. Satisfying this request typically precludes accelerated hardware rendering. The default is to allocate a surface optimize for rendering performance; that is, try to allocate such that hardware accelerated rendering is possible.
- GF_SURFACE_CREATE_CPU_LINEAR_ACCESSIBLE — the surface memory is linearly accessible. Note that this request may preclude hardware accelerated rendering if, for example, the hardware uses tiled video memory. In general, though, this is not the case.
- GF_SURFACE_CREATE_PHYS_CONTIG — the surface memory must be physically contiguous. This is not a usual requirement; however it may be needed in some cases. Some video capture hardware, for instance, requires that the memory be physically contiguous.
- GF_SURFACE_CREATE_PAGE_ALIGNED — the allocated surface must be aligned on a page boundary. You may require this if you are doing your own advanced manipulation of allocated memory, or if you have some hardware with alignment restrictions. Otherwise this is not usually a requirement.
- GF_SURFACE_CREATE_SHAREABLE — Allows server side surfaces to be allocated. Creates a shared memory object, which allows gf_surface_create() to return a valid SID.
||Formats and flags are supported on a per-graphics card basis. If a specified format or flag
is not supported, it will return an error.
The GF_SURFACE_CREATE_CPU_LINEAR_ACCESSIBLE and GF_SURFACE_CREATE_CPU_FAST_ACCESS flags
are not compatible with the Carmine (devg-carmine.so) graphics driver.
This function creates a new surface. A surface provides an area of memory that can be rendered to via draw contexts. Use this function for “offscreen” buffers that will not be targeted by any layers (that is, you will only render to the surface, then blit the results somewhere else). If you plan to directly target the surface with any layers, you must use gf_surface_create_layer() instead.
When the graphics driver (specified by gdev) returns NULL, the behavior of the function depends on the value
of the flags that are returned by the driver's get_alloc_info/get_alloc_layer_info methods, and whether or not the
GF_SURFACE_CREATE_SHAREABLE is set.
If the GF_SURFACE_CREATE_SHAREABLE flag is not set, the surface will be allocated by Advanced Graphics, but will
return an invalid surface id (SID). If you need a valid SID you must pass
GF_SURFACE_CREATE_SHAREABLE, which will cause a shared memory object
to be created. Other processes can then open this shared memory object.
- Memory allocation failure.
- Unable to satisfy the criteria; verify that the pixel format meets the requirements set out by the flags for the given hardware.
- Unsupported flag.
QNX Graphics Framework