def _setup_shader_prefs(self):
        # note: as of bruce 090304 these all should work as same-session prefs,
        # and most of them have been tested that way.

        self.use_sphere_shaders_pref = debug_pref(
            "GLPane: use sphere-shaders?",
            _choices[self.use_sphere_shaders_default],
            non_debug = True,
            prefs_key = self.use_sphere_shaders_prefs_key )

        self.use_cylinder_shaders_pref = debug_pref(
            "GLPane: use cylinder-shaders?",
            _choices[self.use_cylinder_shaders_default],
            non_debug = True,
            prefs_key = self.use_cylinder_shaders_prefs_key )

        self.use_cone_shaders_pref = debug_pref(
            "GLPane: use cone-shaders?",
            _choices[self.use_cone_shaders_default],
            non_debug = True,
            prefs_key = self.use_cone_shaders_prefs_key )

        self.use_batched_primitive_shaders_pref = debug_pref(
            "GLPane: use batched primitive shaders?",
            _choices[ self.use_batched_primitive_shaders_default],
            non_debug = True,
            prefs_key = self.use_batched_primitive_shaders_prefs_key )

        #russ 080403: Added drawing variant selection for unbatched spheres
        # (update, bruce 090304: mainly of historical interest or for testing,
        #  but does matter on older machines that can't use shaders;
        #  could be extended to affect other primitives, but hasn't been
        #  as of 090304)
        variants = [
            "0. OpenGL 1.0 - glBegin/glEnd tri-strips vertex-by-vertex.",
            "1. OpenGL 1.1 - glDrawArrays from CPU RAM.",
            "2. OpenGL 1.1 - glDrawElements indexed arrays from CPU RAM.",
            "3. OpenGL 1.5 - glDrawArrays from graphics RAM VBO.",
            "4. OpenGL 1.5 - glDrawElements, verts in VBO, index in CPU.",
            "5. OpenGL 1.5 - VBO/IBO buffered glDrawElements.",
         ]
        self.use_drawing_variant = debug_pref(
            "GLPane: drawing method (unbatched spheres)",
            Choice(names = variants,
                   values = range(len(variants)),
                   defaultValue = self.use_drawing_variant_default),
            prefs_key = self.use_drawing_variant_prefs_key)
        return

def debug_pref_enable_pam_convert_sticky_ends(): #bruce 080514; remove when this feature fully works
    res = debug_pref("DNA: ghost bases when converting sticky ends to PAM5?", #bruce 080529 revised text
                     Choice_boolean_True, #bruce 080602 revised default value & prefs_key
                     non_debug = True, #bruce 080529
                     prefs_key = "v1.1/DNA: PAM3+5 make ghost bases for sticky ends?"
                    )
    return res

def debug_pref_remove_ghost_bases_from_pam3(): #bruce 080602
    res = debug_pref("DNA: remove ghost bases when converting to PAM3?",
                     Choice_boolean_True, # because they mess up DNA ui ops
                     non_debug = True, # because you should keep them for more accurate repeated Minimize
                     prefs_key = "v1.1/DNA: remove ghost bases when converting to PAM3?"
                    )
    return res

 def _show_all_kids_for_debug(self):
     classname_short = self.__class__.__name__.split('.')[-1]
     debug_pref_name = "Model Tree: show content of %s?" % classname_short
         # typical examples (for text searches to find them here):
         # Model Tree: show content of DnaGroup?
         # Model Tree: show content of Block?
     return debug_pref( debug_pref_name, Choice_boolean_False )

    def _compute_remake_display_lists_now(self): #bruce 090224
        """
        [can be overridden in subclasses, but isn't so far]
        """
        # as of 090317, defined and used only in this class
        remake_during_movies = debug_pref(
            "GLPane: remake display lists during movies?",
            Choice_boolean_True,
                # Historically this was hardcoded to False;
                # but I don't know whether it's still a speedup
                # to avoid remaking them (on modern graphics cards),
                # or perhaps a slowdown, so I'm making it optional.
                # Also, when active it will disable shader primitives,
                # forcing use of polygonal primitives instead;
                #### REVIEW whether it makes sense at all in that case.
                # [bruce 090224]
                # update: I'll make it default True, since that's more reliable,
                # and we might not have time to test it.
                # [bruce 090225]
            non_debug = True,
            prefs_key = "v1.2/GLPane: remake display lists during movies?" )

        # whether to actually remake is more complicated -- it depends on self
        # (thumbviews always remake) and on movie_is_playing flag (external).
        remake_during_movies = remake_during_movies or \
                               self._always_remake_during_movies
        remake_now = remake_during_movies or not self._movie_is_playing()
        if remake_now != self._remake_display_lists:
            # (kluge: knows how calling code uses value)
            # leave this in until we've tested the performance of movie playing
            # for both prefs values; it's not verbose
            print "fyi: setting _remake_display_lists = %r" % remake_now
        return remake_now

def pref_MMKit_include_experimental_PAM_atoms(): #bruce 080412
    res = debug_pref("MMKit: include experimental PAM atoms (next session)?",
                     Choice_boolean_False,
                         # not on by default, and not visible without ATOM_DEBUG,
                         # since these elements would confuse users
                     prefs_key = "A10/MMKit: include experimental PAM atoms?" )
    return res

def set_Color_Theme_from_pref():
    global COLOR_THEME
    COLOR_THEME = debug_pref("Color Theme (next session)",
                                       _colortheme_Choice,
                                       non_debug = True,
                                       prefs_key = COLOR_THEME_prefs_key)
    return

def pref_fix_deprecated_PAM3_atoms():
    res = debug_pref("DNA: fix deprecated PAM3 atoms?",
                     Choice_boolean_True,
                     ## non_debug = True, # disabled, bruce 080317
                     prefs_key = "A10/DNA: fix deprecated PAM3 atoms?", # changed, bruce 080317
                     call_with_new_value = _changed_dna_updater_behavior_pref )
    return res

def pref_draw_internal_markers():
    res = debug_pref("DNA: draw internal DnaMarkers?", #bruce 080317 revised text
                     Choice_boolean_False,
                     non_debug = True,
                     prefs_key = "A10/DNA: draw internal markers?", # changed, bruce 080317
                     call_with_new_value = (lambda val: env.mainwindow().glpane.gl_update()) )
    return res

def pref_dna_updater_convert_to_PAM3plus5():
    res = debug_pref("DNA: edit as PAM3+5? ",
                      Choice_boolean_False, # when True, I'll remove the ending space
                      ## non_debug = True,
                      prefs_key = True,
                      call_with_new_value = _changed_dna_updater_behavior_pref )
    return res

 def displist_disabled(self): #070215 split this out, modified it to notice _exprs__warpfuncs
     """
     Is the use of our displist (or of all displists) disabled at the moment?
     """
     return self._disabled or \
            debug_pref("disable DisplayListChunk?", Choice_boolean_False, prefs_key = True) or \
            getattr(self.env.glpane, '_exprs__warpfuncs', None) ###BUG: this will be too inefficient a response for nice dragging.

def pref_fix_bare_PAM5_atoms():
    res = debug_pref("DNA: fix bare PAM5 atoms?",
                     Choice_boolean_True, # False -> True, 080201
                     ## non_debug = True, # disabled, bruce 080317
                     prefs_key = "A10/DNA: fix bare PAM5 atoms?", # changed, bruce 080317
                     call_with_new_value = _changed_dna_updater_behavior_pref )
    return res

    def _loadTexture(self):
        """
        Load texture data from current image object
        """
        ix, iy, image = self.image_obj.getTextureData() 

        # allocate texture object if never yet done [bruce 060207 revised all related code, to fix bug 1059]
        if self.tex_name is None:
            self.tex_name = glGenTextures(1)
            # note: by experiment (iMac G5 Panther), this returns a single number (1L, 2L, ...), not a list or tuple,
            # but for an argument >1 it returns a list of longs. We depend on this behavior here. [bruce 060207]

        # initialize texture data
        glBindTexture(GL_TEXTURE_2D, self.tex_name)   # 2d texture (x and y size)

        glPixelStorei(GL_UNPACK_ALIGNMENT,1)
        self.have_mipmaps = False
        if debug_pref("smoother tiny textures", Choice_boolean_False, prefs_key = True):
            #bruce 060212 new feature; only takes effect when image is reloaded for some reason (like "load image" button)
            gluBuild2DMipmaps(GL_TEXTURE_2D, GL_RGBA, ix, iy, GL_RGBA, GL_UNSIGNED_BYTE, image)
            self.have_mipmaps = True
        else:
            glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, ix, iy, 0, GL_RGBA, GL_UNSIGNED_BYTE, image)
                # 0 is mipmap level, GL_RGBA is internal format, ix, iy is size, 0 is borderwidth,
                # and (GL_RGBA, GL_UNSIGNED_BYTE, image) describe the external image data. [bruce 060212 comment]

        ## self._initTextureEnv() #bruce 060207 do this in draw method, not here
        self.assy.o.gl_update()
        return

def initTextureEnv(have_mipmaps):
    "have_mipmaps is boolean #doc"
    glTexParameterf(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP)
        # [looks like a bug that we overwrite clamp with repeat, just below?
        # bruce 060212 comment]
    glTexParameterf(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP)
    glTexParameterf(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_REPEAT)
    glTexParameterf(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_REPEAT)
    if (0 and "kluge" and
        debug_pref("smoother textures", Choice_boolean_False,
                   prefs_key = True)): ###@@@ revise to param
        #bruce 060212 new feature (only visible in debug version so far);
        # ideally it'd be controllable per-jig for side-by-side comparison;
        # also, changing its menu item ought to gl_update but doesn't ##e
        glTexParameterf(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR)
        if have_mipmaps: #####@@@@@
            glTexParameterf(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER,
                            GL_LINEAR_MIPMAP_LINEAR)
        else:
            glTexParameterf(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR)
    else:
        glTexParameterf(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_NEAREST)
        glTexParameterf(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST)
    glTexEnvf(GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_DECAL)
    return

def setupUi(win):
    """
    Populates the "Build Structures" menu, a submenu of the "Tools" menu.

    @param win: NE1's main window object.
    @type  win: Ui_MainWindow
    """
    
    # Populate the "Build Structures" menu. 
    # Start with "Builders", then add single shot "Generators".
    win.buildStructuresMenu.addAction(win.toolsDepositAtomAction)
    win.buildStructuresMenu.addAction(win.buildDnaAction)
    
    #  New Nanotube Builder or old Nanotube Generator?
    if debug_pref("Use new 'Build > Nanotube' builder? (next session)", 
                      Choice_boolean_True, 
                      prefs_key = "A10 devel/Old Nanotube Generator"):
        win.buildStructuresMenu.addAction(win.buildNanotubeAction) 
    else:
        # Original "Build > Nanotube"
        win.buildStructuresMenu.addAction(win.nanotubeGeneratorAction)
        
    win.buildStructuresMenu.addAction(win.toolsCookieCutAction)
    
    win.buildStructuresMenu.addSeparator() # Generators after this separator.
    win.buildStructuresMenu.addAction(win.insertPeptideAction) # piotr 080304
    win.buildStructuresMenu.addAction(win.insertGrapheneAction)
    win.buildStructuresMenu.addAction(win.insertAtomAction)

    def _recompile_if_needed_and_return_sublists_dict(self):
        """[private helper method for glpane.ensure_dlist_ready_to_call()]
        Ensure updatedness of our displist's contents (i.e. the OpenGL instructions last emitted for it)
        and of our record of its direct sublists (a dict of owners of other displists it directly calls).
        Return the dict of direct sublists.
           As an optim [mostly nim], it's ok to return a subset of that, which includes all direct sublists
        whose drawing effects might be invalid. (In particular, if our own drawing effects are valid,
        except perhaps for our own displist's contents, it's ok to return {}. [That's the part of this optim we do.])
        """ # doc revised 070102
        if not self.contents_valid:
            # we need to recompile our own displist.
            if self._debug_print_name:
                print "%s: compiling our displist(%r)" % (self._debug_print_name, self.displist)
            
            self._direct_sublists_dict = 3 # intentional error if this temporary value is used as a dict
                # (note: this might detect the error of a recursive direct or indirect call -- untested ##k)
            self.__new_sublists_dict = new_sublists_dict = {}
                # this is added to by draw methods of owners of display lists we call
            mc = self.begin_tracking_usage()
                # Note: we use this twice here, for different implicit values, which is ok since it doesn't store anything on self.
                # [#e i should make these non-methods to clarify that.]
                # This begin/end pair is to track whatever affects the OpenGL commands we compile;
                # the one below is to track the total drawing effects of the display lists called during that
                # (or more generally, any other drawing effects not included in that, but tracking for any other
                #  kinds of effects, like contents of textures we draw to the screen ### WHICH MIGHT MATTER, is nim).
                #
                # Note that track_use and track_inval do NOT have that property -- they store self.__subslist.
            try:
                self.recompile_our_displist()
                    # render our contents into our displist using glNewList, self.drawkid( self.delegate), glEndList
                    # note: has try/except so always does endlist ##e make it tell us if error but no exception??
            finally:
                self.contents_valid = True
                    # Q: is it ok that we do this now but caller might look at it?
                    # A: yes, since caller never needs to see it -- it's effectively private.
                self.end_tracking_usage( mc, self.invalidate_contents) # same invalidator even if exception during recompile or its draw
                self._direct_sublists_dict = dict(new_sublists_dict)
                    #e optim: this copy is only for bug-safety in case something kept a ref and modifies it later
                self.__new_sublists_dict = 4 # illegal dict value

            mc2 = self.begin_tracking_usage() # this tracks how our drawing effects depend on those of the sublists we call
            try:
                for sublist in self._direct_sublists_dict.itervalues():
                    sublist.track_use() # really track_use_of_drawing_effects (note: that's tracked into the global env, as always for track_use)
            finally:
                self.end_tracking_usage( mc2, self.invalidate_drawing_effects )
                    # this subscribes invalidate_drawing_effects to inval of total effects of all sublists
                    # (effectively including indirectly called ones too);
                    # the only thing it doesn't cover is subscribing it to inval of our own displist's contents,
                    # so we manually call it in invalidate_contents.
        if self.drawing_effects_valid:
            if debug_pref("DisplayListChunk: permit optim 070204?", Choice_boolean_False):
                ###BUG: this old optim seems to cause the bug 070203 -- I don't know why, but disabling it seems to fix the bug ###k
                print "doing optim 070204"#e and listnames [#e only print if the optim makes a difference?]
                return {} # optim; only possible when self.contents_valid,
                    # tho if we had a separate flag for sublist contents alone,
                    # we could correctly use that here as a better optim #e
            else:
                pass ## print "not doing optim 070204"#e and listnames
        return self._direct_sublists_dict

def get_gl_info_string(glpane): # grantham 20051129
    """Return a string containing some useful information about the OpenGL
    implementation.

    Use the GL context from the given QGLWidget glpane (by calling
    glpane.makeCurrent()).
    """

    glpane.makeCurrent() #bruce 070308 added glpane arg and makeCurrent call

    gl_info_string = ''

    gl_info_string += 'GL_VENDOR : "%s"\n' % glGetString(GL_VENDOR)
    gl_info_string += 'GL_VERSION : "%s"\n' % glGetString(GL_VERSION)
    gl_info_string += 'GL_RENDERER : "%s"\n' % glGetString(GL_RENDERER)
    gl_info_string += 'GL_EXTENSIONS : "%s"\n' % glGetString(GL_EXTENSIONS)

    from utilities.debug_prefs import debug_pref, Choice_boolean_False
    if debug_pref("get_gl_info_string call glAreTexturesResident?",
                  Choice_boolean_False):
        # Give a practical indication of how much video memory is available.
        # Should also do this with VBOs.

        # I'm pretty sure this code is right, but PyOpenGL seg faults in
        # glAreTexturesResident, so it's disabled until I can figure that
        # out. [grantham] [bruce 070308 added the debug_pref]

        all_tex_in = True
        tex_bytes = '\0' * (512 * 512 * 4)
        tex_names = []
        tex_count = 0
        tex_names = glGenTextures(1024)
        glEnable(GL_TEXTURE_2D)
        while all_tex_in:
            glBindTexture(GL_TEXTURE_2D, tex_names[tex_count])
            gluBuild2DMipmaps(GL_TEXTURE_2D, 4, 512, 512, GL_RGBA,
                              GL_UNSIGNED_BYTE, tex_bytes)
            tex_count += 1

            glTexCoord2f(0.0, 0.0)
            glBegin(GL_QUADS)
            glVertex2f(0.0, 0.0)
            glVertex2f(1.0, 0.0)
            glVertex2f(1.0, 1.0)
            glVertex2f(0.0, 1.0)
            glEnd()
            glFinish()

            residences = glAreTexturesResident(tex_names[:tex_count])
            all_tex_in = reduce(lambda a,b: a and b, residences)
                # bruce 070308 sees this exception from this line:
                # TypeError: reduce() arg 2 must support iteration

        glDisable(GL_TEXTURE_2D)
        glDeleteTextures(tex_names)

        gl_info_string += "Could create %d 512x512 RGBA resident textures\n" \
                          % tex_count
    return gl_info_string

def pref_dna_updater_slow_asserts(): # 080228; note: accessed using debug_flags.DNA_UPDATER_SLOW_ASSERTS
    res = debug_pref("DNA: updater slow asserts?",
                     ## Choice_boolean_True, # todo: test speed effect; revise before release if too slow
                     Choice_boolean_False, #bruce 080702 revised this, and the prefs key
                     non_debug = True,
                     prefs_key = "v111/DNA updater: slow asserts?", # changed, bruce 080317, 080702
                     call_with_new_value = _update_our_debug_flags )
    return res

def pref_fix_after_readmmp_before_updaters():
    res = debug_pref("DNA: do fix_after_readmmp_before_updaters? ",
                      Choice_boolean_True, # might change to False for release -- risky, maybe slow, and no huge need
                         # update, bruce 080408: for now, leave it on, just remove debug prints and non_debug = True
                         # for both related prefs; decide later whether it's slow based on profiles
                      ## non_debug = True,
                      prefs_key = True )
    return res

def pref_print_bond_direction_errors():
    # really this means "print verbose details of them" -- they're always summarized, even when this is off
    res = debug_pref( "DNA: debug: print bond direction errors?", #bruce 080317 revised text
                      Choice_boolean_False,
                      ## non_debug = True, # disabled, bruce 080317
                      prefs_key = "A10/DNA updater: print bond direction errors?", # changed, bruce 080317
                     )
    return res