XPLMSetGraphicsState

XPLM_API void       XPLMSetGraphicsState(
                         int                  inEnableFog,
                         int                  inNumberTexUnits,
                         int                  inEnableLighting,
                         int                  inEnableAlphaTesting,
                         int                  inEnableAlphaBlending,
                         int                  inEnableDepthTesting,
                         int                  inEnableDepthWriting);

XPLMSetGraphicsState changes OpenGL’s fixed function pipeline state. You are not responsible for restoring any state that is accessed via XPLMSetGraphicsState, but you are responsible for not accessing this state directly.

• inEnableFog - enables or disables fog, equivalent to: glEnable(GL_FOG);
• inNumberTexUnits - enables or disables a number of multitexturing units. If the number is 0, 2d texturing is disabled entirely, as in glDisable(GL_TEXTURE_2D); Otherwise, 2d texturing is enabled, and a number of multitexturing units are enabled sequentially, starting with unit 0, e.g. glActiveTextureARB(GL_TEXTURE0_ARB); glEnable (GL_TEXTURE_2D);
• inEnableLighting - enables or disables OpenGL lighting, e.g. glEnable(GL_LIGHTING); glEnable(GL_LIGHT0);
• inEnableAlphaTesting - enables or disables the alpha test per pixel, e.g. glEnable(GL_ALPHA_TEST);
• inEnableAlphaBlending - enables or disables alpha blending per pixel, e.g. glEnable(GL_BLEND);
• inEnableDepthTesting - enables per pixel depth testing, as in glEnable(GL_DEPTH_TEST);
• inEnableDepthWriting - enables writing back of depth information to the depth buffer, as in glDepthMask(GL_TRUE);

The purpose of this function is to change OpenGL state while keeping X-Plane aware of the state changes; this keeps X-Plane from getting surprised by OGL state changes, and prevents X-Plane and plug-ins from having to set all state before all draws; XPLMSetGraphicsState internally skips calls to change state that is already properly enabled.

X-Plane does not have a ‘default’ OGL state for plug-ins with respect to the above state vector; plug-ins should totally set OGL state using this API before drawing. Use XPLMSetGraphicsState instead of any of the above OpenGL calls.

WARNING: Any routine that performs drawing (e.g. XPLMDrawString or widget code) may change X-Plane’s state. Always set state before drawing after unknown code has executed.

Deprecation Warnings: X-Plane’s lighting and fog environment is significantly more complex than the fixed function pipeline can express; do not assume that lighting and fog state is a good approximation for 3-d drawing. Prefer to use XPLMInstancing to draw objects. All calls to XPLMSetGraphicsState should have no fog or lighting.

XPLMBindTexture2d

XPLM_API void       XPLMBindTexture2d(
                         int                  inTextureNum,
                         int                  inTextureUnit);

XPLMBindTexture2d changes what texture is bound to the 2d texturing target. This routine caches the current 2d texture across all texturing units in the sim and plug-ins, preventing extraneous binding. For example, consider several plug-ins running in series; if they all use the ‘general interface’ bitmap to do UI, calling this function will skip the rebinding of the general interface texture on all but the first plug-in, which can provide better frame rates on some graphics cards.

inTextureID is the ID of the texture object to bind; inTextureUnit is a zero-based texture unit (e.g. 0 for the first one), up to a maximum of 4 units. (This number may increase in future versions of X-Plane.)

Use this routine instead of glBindTexture(GL_TEXTURE_2D, ….);

XPLMGenerateTextureNumbers

XPLM_API void       XPLMGenerateTextureNumbers(
                         int *                outTextureIDs,
                         int                  inCount);

Use this routine instead of glGenTextures to generate new texture object IDs. This routine historically ensured that plugins don’t use texure IDs that X-Plane is reserving for its own use.

XPLM_API int        XPLMGetTexture(
                         XPLMTextureID        inTexture);

XPLMWorldToLocal

XPLM_API void       XPLMWorldToLocal(
                         double               inLatitude,
                         double               inLongitude,
                         double               inAltitude,
                         double *             outX,
                         double *             outY,
                         double *             outZ);

This routine translates coordinates from latitude, longitude, and altitude to local scene coordinates. Latitude and longitude are in decimal degrees, and altitude is in meters MSL (mean sea level). The XYZ coordinates are in meters in the local OpenGL coordinate system.

XPLMLocalToWorld

XPLM_API void       XPLMLocalToWorld(
                         double               inX,
                         double               inY,
                         double               inZ,
                         double *             outLatitude,
                         double *             outLongitude,
                         double *             outAltitude);

This routine translates a local coordinate triplet back into latitude, longitude, and altitude. Latitude and longitude are in decimal degrees, and altitude is in meters MSL (mean sea level). The XYZ coordinates are in meters in the local OpenGL coordinate system.

NOTE: world coordinates are less precise than local coordinates; you should try to avoid round tripping from local to world and back.

XPLMDrawTranslucentDarkBox

XPLM_API void       XPLMDrawTranslucentDarkBox(
                         int                  inLeft,
                         int                  inTop,
                         int                  inRight,
                         int                  inBottom);

This routine draws a translucent dark box, partially obscuring parts of the screen but making text easy to read. This is the same graphics primitive used by X-Plane to show text files.

XPLMDrawString

XPLM_API void       XPLMDrawString(
                         float *              inColorRGB,
                         int                  inXOffset,
                         int                  inYOffset,
                         const char *         inChar,
                         int *                inWordWrapWidth,    /* Can be NULL */
                         XPLMFontID           inFontID);

This routine draws a NULL terminated string in a given font. Pass in the lower left pixel that the character is to be drawn onto. Also pass the character and font ID. This function returns the x offset plus the width of all drawn characters. The color to draw in is specified as a pointer to an array of three floating point colors, representing RGB intensities from 0.0 to 1.0.

XPLMDrawNumber

XPLM_API void       XPLMDrawNumber(
                         float *              inColorRGB,
                         int                  inXOffset,
                         int                  inYOffset,
                         double               inValue,
                         int                  inDigits,
                         int                  inDecimals,
                         int                  inShowSign,
                         XPLMFontID           inFontID);

This routine draws a number similar to the digit editing fields in PlaneMaker and data output display in X-Plane. Pass in a color, a position, a floating point value, and formatting info. Specify how many integer and how many decimal digits to show and whether to show a sign, as well as a character set. This routine returns the xOffset plus width of the string drawn.

XPLMGetFontDimensions

XPLM_API void       XPLMGetFontDimensions(
                         XPLMFontID           inFontID,
                         int *                outCharWidth,    /* Can be NULL */
                         int *                outCharHeight,    /* Can be NULL */
                         int *                outDigitsOnly);    /* Can be NULL */

This routine returns the width and height of a character in a given font. It also tells you if the font only supports numeric digits. Pass NULL if you don’t need a given field. Note that for a proportional font the width will be an arbitrary, hopefully average width.

XPLM_API float      XPLMMeasureString(
                         XPLMFontID           inFontID,
                         const char *         inChar,
                         int                  inNumChars);