Tuesday, May 24, 2011

eglChooseConfig example c c++ objc java

Name

eglChooseConfig - return a list of EGL frame buffer configurations that match specified attributes

C Specification

EGLBoolean eglChooseConfig(EGLDisplay display,
    EGLint const * attrib_list,
    EGLConfig * configs,
    EGLint config_size,
    EGLint * num_config)

Parameters

display
Specifies the EGL display connection.
attrib_list
Specifies attributes required to match by configs.
configs
Returns an array of frame buffer configurations.
config_size
Specifies the size of the array of frame buffer configurations.
num_config
Returns the number of frame buffer configurations returned.

Description

eglChooseConfig returns a list of all EGL frame buffer configurations that match the attributes specified in attrib_list. The items in the list can be used in any EGL function that requires an EGL frame buffer configuration.
configs does not return values, if it is specified as NULL. This is useful for querying just the number of matching frame buffer configurations.(eglChooseConfig)
All attributes in attrib_list, including boolean attributes, are immediately followed by the corresponding desired value. The list is terminated with EGL_NONE. If an attribute is not specified in attrib_list then the default value (see below) is used (and the attribute is said to be specified implicitly). For example, if EGL_DEPTH_SIZE is not specified then it is assumed to be 0. For some attributes, the default is EGL_DONT_CARE meaning that any value is OK for this attribute, so the attribute will not be checked.(eglChooseConfig)
Attributes are matched in an attribute-specific manner. Some of the attributes, such as EGL_LEVEL, must match the specified value exactly. Others, such as, EGL_RED_SIZE must meet or exceed the specified minimum values. If more than one EGL frame buffer configuration is found, then a list of configurations, sorted according to the ``best'' match criteria, is returned. The match criteria for each attribute and the exact sorting order is defined below.
The interpretations of the various EGL frame buffer configuration attributes are as follows:
EGL_BUFFER_SIZE
Must be followed by a nonnegative integer that indicates the desired color buffer size. The smallest color buffer of at least the specified size is preferred. The default value is 0.
EGL_RED_SIZE
Must be followed by a nonnegative minimum size specification. If this value is zero, the smallest available red buffer is preferred. Otherwise, the largest available red buffer of at least the minimum size is preferred. The default value is 0.
EGL_GREEN_SIZE
Must be followed by a nonnegative minimum size specification. If this value is zero, the smallest available green buffer is preferred. Otherwise, the largest available green buffer of at least the minimum size is preferred. The default value is 0.
EGL_BLUE_SIZE
Must be followed by a nonnegative minimum size specification. If this value is zero, the smallest available blue buffer is preferred. Otherwise, the largest available blue buffer of at least the minimum size is preferred. The default value is 0. (eglChooseConfig)
EGL_ALPHA_SIZE
Must be followed by a nonnegative minimum size specification. If this value is zero, the smallest available alpha buffer is preferred. Otherwise, the largest available alpha buffer of at least the minimum size is preferred. The default value is 0.
EGL_CONFIG_CAVEAT
Must be followed by one of EGL_DONT_CARE, EGL_NONE, EGL_SLOW_CONFIG, EGL_NON_CONFORMANT_CONFIG. If EGL_NONE is specified, then only frame buffer configurations with no caveats will be considered. If EGL_SLOW_CONFIG is specified, then only slow frame buffer configurations will be considered. If EGL_NON_CONFORMANT_CONFIG is specified, then only non-conformant frame buffer configurations will be considered. The default value is EGL_DONT_CARE.
EGL_CONFIG_ID
Must be followed by a valid ID that indicates the desired EGL frame buffer configuration. When a EGL_CONFIG_ID is specified, all attributes are ignored. The default value is EGL_DONT_CARE.
EGL_DEPTH_SIZE
Must be followed by a nonnegative integer that indicates the desired depth buffer size. The smallest available depth buffer of at least the minimum size is preferred. If the desired value is zero, frame buffer configurations with no depth buffer are preferred. The default value is 0.
EGL_LEVEL
Must be followed by an integer buffer-level specification. This specification is honored exactly. Buffer level 0 corresponds to the default frame buffer of the display. Buffer level 1 is the first overlay frame buffer, level two the second overlay frame buffer, and so on. Negative buffer levels correspond to underlay frame buffers. The default value is 0. (eglChooseConfig)
EGL_NATIVE_RENDERABLE
Must be followed by EGL_DONT_CARE, EGL_TRUE, or EGL_FALSE. If EGL_TRUE is specified, then only frame buffer configurations that allow native rendering into the surface will be considered. The default value is EGL_DONT_CARE.
EGL_NATIVE_VISUAL_TYPE
Must be followed by a platform dependent value or EGL_DONT_CARE. The default value is EGL_DONT_CARE.
EGL_SAMPLE_BUFFERS
Must be followed by the minimum acceptable number of multisample buffers. Configurations with the smallest number of multisample buffers that meet or exceed this minimum number are preferred. Currently operation with more than one multisample buffer is undefined, so only values of zero or one will produce a match. The default value is 0.
EGL_SAMPLES
Must be followed by the minimum number of samples required in multisample buffers. Configurations with the smallest number of samples that meet or exceed the specified minimum number are preferred. Note that it is possible for color samples in the multisample buffer to have fewer bits than colors in the main color buffers. However, multisampled colors maintain at least as much color resolution in aggregate as the main color buffers.
EGL_STENCIL_SIZE
Must be followed by a nonnegative integer that indicates the desired number of stencil bitplanes. The smallest stencil buffer of at least the specified size is preferred. If the desired value is zero, frame buffer configurations with no stencil buffer are preferred. The default value is 0.
EGL_SURFACE_TYPE
Must be followed by a mask indicating which EGL surface types the frame buffer configuration must support. Valid bits are EGL_WINDOW_BIT, EGL_PBUFFER_BIT, and EGL_PIXMAP_BIT. For example, if mask is set to EGL_WINDOW_BIT | EGL_PIXMAP_BIT, only frame buffer configurations that support both windows and pixmaps will be considered. The default value is EGL_WINDOW_BIT.
EGL_TRANSPARENT_TYPE
Must be followed by one of EGL_NONE or EGL_TRANSPARENT_RGB. If EGL_NONE is specified, then only opaque frame buffer configurations will be considered. If EGL_TRANSPARENT_RGB is specified, then only transparent frame buffer configurations will be considered. The default value is EGL_NONE.
EGL_TRANSPARENT_RED_VALUE
Must be followed by an integer value indicating the transparent red value. The value must be between 0 and the maximum color buffer value for red. Only frame buffer configurations that use the specified transparent red value will be considered. The default value is EGL_DONT_CARE. This attribute is ignored unless EGL_TRANSPARENT_TYPE is included in attrib_list and specified as EGL_TRANSPARENT_RGB. (eglChooseConfig)
EGL_TRANSPARENT_GREEN_VALUE
Must be followed by an integer value indicating the transparent green value. The value must be between 0 and the maximum color buffer value for red. Only frame buffer configurations that use the specified transparent green value will be considered. The default value is EGL_DONT_CARE. This attribute is ignored unless EGL_TRANSPARENT_TYPE is included in attrib_list and specified as EGL_TRANSPARENT_RGB.
EGL_TRANSPARENT_BLUE_VALUE
Must be followed by an integer value indicating the transparent blue value. The value must be between 0 and the maximum color buffer value for red. Only frame buffer configurations that use the specified transparent blue value will be considered. The default value is EGL_DONT_CARE. This attribute is ignored unless EGL_TRANSPARENT_TYPE is included in attrib_list and specified as EGL_TRANSPARENT_RGB.
When more than one EGL frame buffer configuration matches the specified attributes, a list of matching configurations is returned. The list is sorted according to the following precedence rules, which are applied in ascending order (i.e., configurations that are considered equal by a lower numbered rule are sorted by the higher numbered rule):
  1. By EGL_CONFIG_CAVEAT, where the precedence is EGL_NONE, EGL_SLOW_CONFIG, and EGL_NON_CONFORMANT_CONFIG.
  2. Larger total number of color components (EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_SIZE, and EGL_ALPHA_SIZE) that have higher number of bits. If the requested number of bits in attrib_list is zero or EGL_DONT_CARE for a particular color component, then the number of bits for that component is not considered.
  3. Smaller EGL_BUFFER_SIZE.
  4. Smaller EGL_SAMPLE_BUFFERS.
  5. Smaller EGL_SAMPLES.
  6. Smaller EGL_DEPTH_SIZE.
  7. Smaller EGL_STENCIL_SIZE.
  8. By EGL_NATIVE_VISUAL_TYPE, where the precedence order is platform dependent.
  9. Smaller EGL_CONFIG_ID.

Examples

The following example specifies a frame buffer configuration in the normal frame buffer (not an overlay or underlay). The returned frame buffer configuration supports at least 4 bits each of red, green and blue and possible no alpha bits. The code shown in the example may or may not have a depth buffer, or a stencil buffer.
EGLint const attrib_list[] = {
    EGL_RED_SIZE, 4,
    EGL_GREEN_SIZE, 4,
    EGL_BLUE_SIZE, 4,
    EGL_NONE
};

Notes

eglGetConfigs and eglGetConfigAttrib can be used to implement selection algorithms other than the generic one implemented by eglChooseConfig. Call eglGetConfigs to retrieve all the frame buffer configurations, or alternatively, all the frame buffer configurations with a particular set of attributes. Next call eglGetConfigAttrib to retrieve additional attributes for the frame buffer configurations and then select between them.
EGL implementors are strongly discouraged, but not proscribed, from changing the selection algorithm used by eglChooseConfig. Therefore, selections may change from release to release of the client-side library.

Errors

EGL_FALSE is returned on failure, EGL_TRUE otherwise. configs and num_config are not modified when EGL_FALSE is returned.
EGL_BAD_DISPLAY is generated if display is not an EGL display connection.
EGL_BAD_ATTRIBUTE is generated if attribute_list contains an invalid frame buffer configuration attribute or an attribute value that is unrecognized or out of range.
EGL_NOT_INITIALIZED is generated if display has not been initialized.
EGL_BAD_PARAMETER is generated if num_config is NULL.

Copyright

Copyright © 2003 Silicon Graphics, Inc.
This document is licensed under the SGI Free Software B License. For details, see http://oss.sgi.com/projects/FreeB/.

See Also

eglCreateContext, eglCreatePbufferSurface, eglCreatePixmapSurface, eglCreateWindowSurface, eglGetConfigs, eglGetConfigAttrib


Examples of eglChooseConfig

void CXXXView::OnInitialUpdate()
{
 CView::OnInitialUpdate();
 // TODO: Add your specialized code here and/or call the base class
 if (m_eglDisplay != EGL_NO_DISPLAY)
  return;
 const EGLint attrs[] = {
  EGL_LEVEL, 0,
  EGL_SURFACE_TYPE, EGL_WINDOW_BIT,
  EGL_RENDERABLE_TYPE, EGL_OPENGL_ES2_BIT,
  EGL_NATIVE_RENDERABLE, EGL_FALSE,
  EGL_DEPTH_SIZE, EGL_DONT_CARE,
  EGL_NONE
 };
 EGLint numConfig =0;
 m_eglDisplay = eglGetDisplay(GetDC()->GetSafeHdc());
 if (m_eglDisplay == EGL_NO_DISPLAY)
  if ((m_eglDisplay = eglGetDisplay((EGLNativeDisplayType) EGL_DEFAULT_DISPLAY)) == EGL_NO_DISPLAY)
   return;
 // Initialize the display
 EGLint major = 0;
 EGLint minor = 0;
 if (!eglInitialize(m_eglDisplay, &major, &minor))
  return;
 if (major < 1 || minor < 3)
 {
  // Does not support EGL 1.3
  printf("System does not support at least EGL 1.3 \n");
  return;
 }
 EGLConfig eglConfig;
 // Obtain the first configuration with a depth buffer
 if (!eglChooseConfig(m_eglDisplay, attrs, &eglConfig, 1, &numConfig))
  return;
 // Create a surface for the main window
 if ((m_eglSurface = eglCreateWindowSurface(m_eglDisplay, eglConfig, (EGLNativeWindowType) GetSafeHwnd(), NULL)) == EGL_NO_SURFACE)
  return;
 // Bind the API (It could be OpenGLES or OpenVG)
 // eglBindAPI(EGL_OPENGL_ES_API);
 EGLint ai32ContextAttribs[] = { EGL_CONTEXT_CLIENT_VERSION, 2, EGL_NONE };
 // Create an OpenGL ES context
 if ((m_eglContext = eglCreateContext(m_eglDisplay, eglConfig, EGL_NO_CONTEXT, ai32ContextAttribs)) == EGL_NO_CONTEXT)
  return;
 // Make the context and surface current
 if (!eglMakeCurrent(m_eglDisplay, m_eglSurface, m_eglSurface, m_eglContext))
  return;
 ///
 glClearColor(0.5f, 0.5f, 0.5f, 0.0f);
}
void CXXXView::PostNcDestroy()
{
 // TODO: Add your specialized code here and/or call the base class
 eglMakeCurrent(EGL_NO_DISPLAY, EGL_NO_SURFACE, EGL_NO_SURFACE, EGL_NO_CONTEXT);
 eglDestroyContext(m_eglDisplay, m_eglContext);
 eglDestroySurface(m_eglDisplay, m_eglSurface);
 eglTerminate(m_eglDisplay);
 CView::PostNcDestroy();
}
void CXXXView::onDraw(void)
{
 glClear(GL_COLOR_BUFFER_BIT);
 ///
 IGameImporter * gameImport = NULL;
 auto pDoc = GetDocument();
 if (pDoc && pDoc->IsKindOf(RUNTIME_CLASS(CXXXDoc)))
  gameImport = dynamic_cast<cxxxdoc *=""> (pDoc)->getGameImport();
 ///
 eglSwapBuffers(m_eglDisplay, m_eglSurface);
}
BOOL CXXXView::OnEraseBkgnd(CDC* pDC)
{
 // TODO: Add your message handler code here and/or call default
 /// return CView::OnEraseBkgnd(pDC);
 return FALSE;
}
void CXXXView::OnSize(UINT nType, int cx, int cy)
{
 CView::OnSize(nType, cx, cy);
 // TODO: Add your message handler code here
 glViewport(0, 0, cx, cy);
}
/// CXXXApp.cpp
BOOL CXXXApp::OnIdle(LONG lCount)
{
 // TODO: Add your specialized code here and/or call the base class
// return CWinAppEx::OnIdle(lCount);
 CMainFrame * pFrame = (CMainFrame *) AfxGetMainWnd();
 CView * pView = pFrame->GetActiveView();
 if (pView && pView->IsKindOf(RUNTIME_CLASS(CXXXView)))
  dynamic_cast<cxxxview *=""> (pView)->onDraw();
 return TRUE;
}
/// CViewTree.h
#define WM_TVN_SELCHANGED (WM_USER+3)
class CViewTree : public CTreeCtrl
{
public:
 afx_msg void OnTvnSelchanged(NMHDR *pNMHDR, LRESULT *pResult);
};
/// CViewTree.cpp
BEGIN_MESSAGE_MAP(CViewTree, CTreeCtrl)
 ON_NOTIFY_REFLECT(TVN_SELCHANGED, &CViewTree::OnTvnSelchanged)
END_MESSAGE_MAP()
void CViewTree::OnTvnSelchanged(NMHDR *pNMHDR, LRESULT *pResult)
{
 LPNMTREEVIEW pNMTreeView = reinterpret_cast<lpnmtreeview>(pNMHDR);
 // TODO: Add your control notification handler code here
 GetParent()->SendNotifyMessage(WM_TVN_SELCHANGED, (WPARAM) pNMTreeView, (LPARAM) pResult);
 *pResult = 0;
}