'\" t
.\"     Title: waffle_init
.\"    Author: Chad Versace <chad.versace@linux.intel.com>
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 09/02/2021
.\"    Manual: Waffle Manual
.\"    Source: waffle
.\"  Language: English
.\"
.TH "WAFFLE_INIT" "3" "09/02/2021" "waffle" "Waffle Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
waffle_init \- Initialize waffle\*(Aqs per\-process global state
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <waffle\&.h>
.fi
.ft
.HP \w'bool\ waffle_init('u
.BI "bool waffle_init(const\ int32_t\ " "attrib_list" "[]);"
.SH "DESCRIPTION"
.PP
\fBwaffle_init()\fR
initializes the per\-process global state of the waffle library with the attributes specified in
\fIattrib_list\fR\&. The set of attributes is documented below\&.
\fIattrib_list\fR
consists of a zero\-terminated sequence of name/value pairs\&.
.PP
Most waffle functions emit an error if called when waffle is unitialized\&. The small set of functions that can be successfully called before initialization are explicitly documented as such\&.
.PP
If a call to
\fBwaffle_init()\fR
fails, no global state is initialized and the caller may safely attempt to call
\fBwaffle_init()\fR
again\&. If waffle has already been initialized by a successful call to
\fBwaffle_init()\fR
one has to call
\fBwaffle_teardown()\fR
to clear the global state\&. Otherwise calling
\fBwaffle_init()\fR
again emits the error
\fBWAFFLE_ERROR_ALREADY_INITIALIZED\fR\&.
.SH "ATTRIBUTES"
.PP
\fBWAFFLE_PLATFORM\fR
.RS 4
This attribute is required\&. Possible values are:
.PP
\fBWAFFLE_PLATFORM_ANDROID\fR
.RS 4
[Android] Use EGL on Android\&.
.RE
.PP
\fBWAFFLE_PLATFORM_GBM\fR
.RS 4
[Linux] Use EGL with GBM, the "Generic Buffer Manager" provided by libgbm\&. This platform is capable of OpenGL rendering without a display manager\&.
.RE
.PP
\fBWAFFLE_PLATFORM_CGL\fR
.RS 4
[MacOS] Use CGL to create the
\fBwaffle_config\fR(3)
and
\fBwaffle_context\fR(3)\&. Use Cocoa to create the
\fBwaffle_window\fR(3)\&.
.RE
.PP
\fBWAFFLE_PLATFORM_GLX\fR
.RS 4
[Linux only, MacOS not yet supported]
.RE
.PP
\fBWAFFLE_PLATFORM_NACL\fR
.RS 4
[Linux only, other systems not yet supported]
.RE
.PP
\fBWAFFLE_PLATFORM_SURFACELESS_EGL\fR
.RS 4
[Linux] Use EGL\*(Aqs "surfaceless" platform,
\m[blue]\fBEGL_MESA_platform_surfaceless\fR\m[]\&\s-2\u[1]\d\s+2\&.
.RE
.PP
\fBWAFFLE_PLATFORM_WAYLAND\fR
.RS 4
[Linux] Use EGL with the Wayland display server\&.
.RE
.PP
\fBWAFFLE_PLATFORM_WGL\fR
.RS 4
[Windows] Use WGL on Windows\&.
.RE
.PP
\fBWAFFLE_PLATFORM_X11_EGL\fR
.RS 4
[Linux] Use EGL with the X11 display server\&.
.RE
.sp
.RE
.SH "RETURN VALUE"
.PP
Functions whose return type is
\fBbool\fR
return true on success and false on failure\&. Functions whose return type is a pointer return
\fBNULL\fR
on failure\&. Use
\fBwaffle_error_get_info\fR(3)
to get information about any errors\&.
.SH "ERRORS"
.PP
See
\fBwaffle_error\fR(3)
for the complete list of waffle\*(Aqs error codes\&.
.PP
Listed are the errors specific to
\fBwaffle_init()\fR\&.
.PP
\fBWAFFLE_ERROR_ALREADY_INITIALIZED\fR
.RS 4
Waffle has already been initialized with a successful call to
\fBwaffle_init()\fR\&.
.RE
.PP
\fBWAFFLE_ERROR_BAD_ATTRIBUTE\fR
.RS 4
An item in
\fIattrib_list\fR
is unrecognized or has an invalid value, or a required attribute is missing\&.
.RE
.PP
\fBWAFFLE_ERROR_BUILT_WITHOUT_SUPPORT\fR
.RS 4
Waffle was built without support for the requested attribute\&.
.RE
.SH "EXAMPLE"
.PP
Initialize waffle for X11/EGL\&.
.sp
.if n \{\
.RS 4
.\}
.nf

#include <waffle\&.h>

static const int32_t init_attrib_list[] = {
    WAFFLE_PLATFORM, WAFFLE_PLATFORM_X11_EGL,
    0,
};

int
main()
{
    bool ok = waffle_init(init_attrib_list);
    if (ok)
        return EXIT_SUCCESS;
    else
        return EXIT_FAILURE;
}

    
.fi
.if n \{\
.RE
.\}
.SH "ISSUES"
.PP
Please report bugs or and feature requests to
\m[blue]\fB\%https://gitlab.freedesktop.org/mesa/waffle/issues\fR\m[]\&.
.SH "SEE ALSO"
.PP
\fBwaffle\fR(7)
.SH "AUTHOR"
.PP
\fBChad Versace\fR <\&chad\&.versace@linux\&.intel\&.com\&>
.RS 4
Maintainer
.RE
.SH "COPYRIGHT"
.br
Copyright \(co 2013 Intel
.br
.PP
This manual page is licensed under the Creative Commons Attribution\-ShareAlike 3\&.0 United States License (CC BY\-SA 3\&.0)\&. To view a copy of this license, visit
\m[blue]\fB\%http://creativecommons.org.license/by-sa/3.0/us\fR\m[]\&.
.sp
.SH "NOTES"
.IP " 1." 4
EGL_MESA_platform_surfaceless
.RS 4
\%https://www.khronos.org/registry/egl/extensions/MESA/EGL_MESA_platform_surfaceless.txt
.RE