"""ctypes-based OpenGL wrapper for Python

This is the PyOpenGL 3.x tree, it attempts to provide
a largely compatible API for code written with the 
PyOpenGL 2.x series using the ctypes foreign function 
interface system.

Configuration Variables:

There are a few configuration variables in this top-level
module.  Applications should be the only code that tweaks 
these variables, mid-level libraries should not take it 
upon themselves to disable/enable features at this level.
The implication there is that your library code should be 
able to work with any of the valid configurations available
with these sets of flags.

    ERROR_CHECKING -- if set to a False value before
        importing any OpenGL.* libraries will completely 
        disable error-checking.  This can dramatically
        improve performance, but makes debugging far 
        harder.
        
        This is intended to be turned off *only* in a 
        production environment where you *know* that 
        your code is entirely free of situations where you 
        use exception-handling to handle error conditions,
        i.e. where you are explicitly checking for errors 
        everywhere they can occur in your code.
        
        Default: True 

    ERROR_LOGGING -- If True, then wrap array-handler 
        functions with  error-logging operations so that all exceptions 
        will be reported to log objects in OpenGL.logs, note that 
        this means you will get lots of error logging whenever you 
        have code that tests by trying something and catching an 
        error, this is intended to be turned on only during 
        development so that you can see why something is failing.
        
        Errors are normally logged to the OpenGL.errors logger.
        
        Only triggers if ERROR_CHECKING is True
        
        Default: False
        
    ERROR_ON_COPY -- if set to a True value before 
        importing the numpy/lists support modules, will 
        cause array operations to raise 
        OpenGL.error.CopyError if the operation 
        would cause a data-copy in order to make the 
        passed data-type match the target data-type.
        
        This effectively disables all list/tuple array 
        support, as they are inherently copy-based.
        
        This feature allows for optimisation of your 
        application.  It should only be enabled during 
        testing stages to prevent raising errors on 
        recoverable conditions at run-time.  
        
        Note: this feature does not currently work with 
            numarray or Numeric arrays.
        
        Default: False
    
    CONTEXT_CHECKING -- if set to True, PyOpenGL will wrap 
        *every* GL and GLU call with a check to see if there 
        is a valid context.  If there is no valid context 
        then will throw OpenGL.errors.NoContext.  This is an 
        *extremely* slow check and is not enabled by default,
        intended to be enabled in order to track down (wrong)
        code that uses GL/GLU entry points before the context 
        has been initialized (something later Linux GLs are 
        very picky about).
        
        Default: False
    
    STORE_POINTERS -- if set to True, PyOpenGL array operations 
        will attempt to store references to pointers which are 
        being passed in order to prevent memory-access failures 
        if the pointed-to-object goes out of scope.  This 
        behaviour is primarily intended to allow temporary arrays 
        to be created without causing memory errors, thus it is 
        trading off performance for safety.
        
        To use this flag effectively, you will want to first set 
        ERROR_ON_COPY to True and eliminate all cases where you 
        are copying arrays.  Copied arrays *will* segfault your 
        application deep within the GL if you disable this feature!
        
        Once you have eliminated all copying of arrays in your 
        application, you will further need to be sure that all 
        arrays which are passed to the GL are stored for at least 
        the time period for which they are active in the GL.  That 
        is, you must be sure that your array objects live at least 
        until they are no longer bound in the GL.  This is something 
        you need to confirm by thinking about your application's 
        structure.
        
        When you are sure your arrays won't cause seg-faults, you 
        can set STORE_POINTERS=False in your application and enjoy 
        a (slight) speed up.
        
        Note: this flag is *only* observed when ERROR_ON_COPY == True,
            as a safety measure to prevent pointless segfaults
        
        Default: True
    
    WARN_ON_FORMAT_UNAVAILABLE -- If True, generates
        logging-module warn-level events when a FormatHandler
        plugin is not loadable (with traceback).
    
        Default: False
    
    FULL_LOGGING -- If True, then wrap functions with 
        logging operations which reports each call along with its 
        arguments to  the OpenGL.calltrace logger at the INFO 
        level.  This is *extremely* slow.  You should *not* enable 
        this in production code! 
        
        You will need to have a  logging configuration (e.g. 
            logging.basicConfig() 
        ) call  in your top-level script to see the results of the 
        logging.
        
        Default: False
    
    ALLOW_NUMPY_SCALARS -- if True, we will wrap 
        all GLint/GLfloat calls conversions with wrappers 
        that allow for passing numpy scalar values.
        
        Note that this is experimental, *not* reliable,
        and very slow!
        
        Note that byte/char types are not wrapped.
        
        Default: False
    
    UNSIGNED_BYTE_IMAGES_AS_STRING -- if True, we will return
        GL_UNSIGNED_BYTE image-data as strings, istead of arrays
        for glReadPixels and glGetTexImage

        Default: True
    
    FORWARD_COMPATIBLE_ONLY -- only include OpenGL 3.1 compatible 
        entry points.  Note that this will generally break most 
        PyOpenGL code that hasn't been explicitly made "legacy free"
        via a significant rewrite.
    
        Default: False
        
    SIZE_1_ARRAY_UNPACK -- if True, unpack size-1 arrays to be 
        scalar values, as done in PyOpenGL 1.5 -> 3.0.0, that is,
        if a glGenList( 1 ) is done, return a uint rather than 
        an array of uints.

        Default: True
    
    USE_ACCELERATE -- if True, attempt to use the OpenGL_accelerate
        package to provide Cython-coded accelerators for core wrapping
        operations.
        
        Default: True
"""
from OpenGL.version import __version__

ERROR_CHECKING = True
ERROR_LOGGING = False
ERROR_ON_COPY = False
ARRAY_SIZE_CHECKING = True
STORE_POINTERS = True
WARN_ON_FORMAT_UNAVAILABLE = False
FORWARD_COMPATIBLE_ONLY = False
SIZE_1_ARRAY_UNPACK = True
USE_ACCELERATE = True
CONTEXT_CHECKING = False

FULL_LOGGING = False 
ALLOW_NUMPY_SCALARS = False
UNSIGNED_BYTE_IMAGES_AS_STRING = True

# Declarations of plugins provided by PyOpenGL itself
from OpenGL.plugins import PlatformPlugin, FormatHandler
PlatformPlugin( 'nt', 'OpenGL.platform.win32.Win32Platform' )
PlatformPlugin( 'linux2', 'OpenGL.platform.glx.GLXPlatform' )
PlatformPlugin( 'darwin', 'OpenGL.platform.darwin.DarwinPlatform' )
PlatformPlugin( 'posix', 'OpenGL.platform.glx.GLXPlatform' )

FormatHandler( 'none', 'OpenGL.arrays.nones.NoneHandler' )
FormatHandler( 'str', 'OpenGL.arrays.strings.StringHandler' )
FormatHandler( 'list', 'OpenGL.arrays.lists.ListHandler', ['__builtin__.list','__builtin__.tuple'] )
FormatHandler( 'numbers', 'OpenGL.arrays.numbers.NumberHandler' )
FormatHandler( 
    'ctypesarray', 'OpenGL.arrays.ctypesarrays.CtypesArrayHandler',
    [
        '_ctypes.ArrayType',
    ],
)
FormatHandler( 
    'ctypesparameter',
    'OpenGL.arrays.ctypesparameters.CtypesParameterHandler',
)
FormatHandler( 'ctypespointer', 'OpenGL.arrays.ctypespointers.CtypesPointerHandler' )
FormatHandler( 'numpy', 'OpenGL.arrays.numpymodule.NumpyHandler', ['numpy.ndarray'] )
FormatHandler( 'numeric', 'OpenGL.arrays.numeric.NumericHandler', )
