Changeset 33110 in project


Ignore:
Timestamp:
01/22/16 04:11:22 (3 years ago)
Author:
jacius
Message:

sdl2: Added docs related to textures.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/sdl2

    r33109 r33110  
    26722672
    26732673
     2674<procedure>(gl-bind-texture! texture) → [tex-w tex-h]</procedure>
     2675
     2676Bind the given sdl2:texture for use with the current OpenGL context.
     2677See [[https://wiki.libsdl.org/SDL_GL_BindTexture|SDL_GL_BindTexture]].
     2678
     2679Returns multiple values:
     2680
     2681; tex-w : The bound OpenGL texture's width, as a float (usually 1.0)
     2682; tex-h : The bound OpenGL texture's height, as a float (usually 1.0)
     2683
     2684Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     2685
     2686This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     2687
     2688
     2689<procedure>(gl-unbind-texture! texture)</procedure>
     2690
     2691Unbind the given sdl2:texture from the OpenGL context.
     2692See [[https://wiki.libsdl.org/SDL_GL_UnbindTexture|SDL_GL_UnbindTexture]].
     2693
     2694Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     2695
     2696This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     2697
     2698
    26742699
    26752700==== sdl2:gl-context
     
    40514076
    40524077Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     4078
     4079
     4080
     4081=== Texture
     4082
     4083==== sdl2:texture
     4084
     4085sdl2:texture is a record type that wraps a pointer to an
     4086[[https://wiki.libsdl.org/SDL_Texture|SDL_Texture]] struct.
     4087
     4088Textures are available in '''sdl2 egg version 0.2.0 and higher'''.
     4089
     4090
     4091<procedure>(texture? obj) → boolean</procedure>
     4092
     4093Returns #t if {{obj}} is an sdl2:texture.
     4094
     4095This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     4096
     4097
     4098<procedure>(create-texture renderer format access w h) → sdl2:texture</procedure>
     4099<procedure>(create-texture* renderer format access w h) → sdl2:texture</procedure>
     4100
     4101Create a new sdl2:texture using the given sdl2:renderer and settings.
     4102
     4103* {{renderer}} must be a sdl2:renderer.
     4104* {{format}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format enum symbol]] or equivalent integer.
     4105* {{access}} must be a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#texture-access|texture access enum symbol]] or equivalent integer:
     4106** {{'static}}
     4107** {{'streaming}}
     4108** {{'target}}
     4109* {{w}} must be an integer, specifying the texture's width in pixels.
     4110* {{h}} must be an integer, specifying the texture's height in pixels.
     4111
     4112These procedures signal an exception of kind {{(exn sdl2)}} if the sdl2:texture could not be created.
     4113
     4114* {{create-texture}} returns a managed sdl2:texture.
     4115* {{create-texture*}} returns an unmanaged sdl2:texture,
     4116  which must be destroyed with {{destroy-texture!}} when you are done with it.
     4117
     4118These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     4119
     4120
     4121<procedure>(create-texture-from-surface renderer surface) → sdl2:texture</procedure>
     4122<procedure>(create-texture-from-surface* renderer surface) → sdl2:texture</procedure>
     4123
     4124Create a new sdl2:texture from a sdl2:surface.
     4125
     4126The texture will contain a copy of the pixel data from the surface.
     4127The texture will have the same color mod and alpha mod as the surface.
     4128If the surface had a color key, the texture will have {{'blend}} blend mode;
     4129otherwise it will have the same blend mode as the surface.
     4130
     4131* {{create-texture-from-surface}} returns a managed sdl2:texture.
     4132* {{create-texture-from-surface*}} returns an unmanaged sdl2:texture,
     4133  which must be destroyed with {{destroy-texture!}} when you are done with it.
     4134
     4135These procedures signal an exception of kind {{(exn sdl2)}} if the sdl2:texture could not be created.
     4136
     4137These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     4138
     4139
     4140<procedure>(destroy-texture! texture)</procedure>
     4141
     4142Destroy the sdl2:texture, freeing its underlying struct.
     4143{{texture}}'s pointer will be set to null (see {{struct-null?}}).
     4144It is safe to call tihs procedure with managed on unmanaged sdl2:textures.
     4145It is safe (but has no effect) to destroy an sdl2:texture multiple times.
     4146
     4147See [[https://wiki.libsdl.org/SDL_DestroyTexture|SDL_DestroyTexture]].
     4148
     4149This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     4150
     4151
     4152<procedure>(query-texture texture) → [format access w h]</procedure>
     4153<procedure>(query-texture-raw texture) → [format-int access-int w h]</procedure>
     4154
     4155Get multiple pieces of information about the texture.
     4156See [[https://wiki.libsdl.org/SDL_QueryTexture|SDL_QueryTexture]].
     4157
     4158{{query-texture}} returns multiple values:
     4159
     4160; format : The sdl2:texture's pixel format, as a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#pixel-formats|pixel format enum symbol]]
     4161; access : The sdl2:texture's access mode, as a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#texture-access|texture access enum symbol]]
     4162; w : The sdl2:texture's width, as a nonnegative integer measured in pixels
     4163; h : The sdl2:texture's height, as a nonnegative integer measured in pixels
     4164
     4165{{query-texture-raw}} is similar, except it returns raw integer values (not symbols) for format and access.
     4166
     4167These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     4168
     4169If you only want one of these pieces of information,
     4170it is more convenient and efficient to use one of these procedures instead:
     4171
     4172* {{texture-format}}
     4173* {{texture-access}}
     4174* {{texture-w}}
     4175* {{texture-h}}
     4176
     4177
     4178<procedure>(texture-format texture) → symbol</procedure>
     4179
     4180Get the sdl2:texture's pixel format, as a pixel format enum symbol.
     4181This is equivalent to {{(nth-value 0 (query-texture texture))}},
     4182but more convenient and efficient.
     4183
     4184This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     4185
     4186
     4187<procedure>(texture-access texture) → symbol</procedure>
     4188
     4189Get the sdl2:texture's access mode, as a texture access enum symbol.
     4190This is equivalent to {{(nth-value 1 (query-texture texture))}},
     4191but more convenient and efficient.
     4192
     4193This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     4194
     4195
     4196<procedure>(texture-w texture) → integer</procedure>
     4197
     4198Get the sdl2:texture's width, as a nonnegative integer measured in pixels.
     4199This is equivalent to {{(nth-value 2 (query-texture texture))}},
     4200but more convenient and efficient.
     4201
     4202This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     4203
     4204
     4205<procedure>(texture-h texture) → integer</procedure>
     4206
     4207Get the sdl2:texture's height, as a nonnegative integer measured in pixels.
     4208This is equivalent to {{(nth-value 3 (query-texture texture))}},
     4209but more convenient and efficient.
     4210
     4211This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     4212
     4213
     4214<procedure>(texture-alpha-mod texture) → integer</procedure>
     4215<setter>(set! (texture-alpha-mod texture) mod)</setter>
     4216<setter>(texture-alpha-mod-set! texture mod)</setter>
     4217
     4218See [[https://wiki.libsdl.org/SDL_GetTextureAlphaMod|SDL_GetTextureAlphaMod]]
     4219and [[https://wiki.libsdl.org/SDL_SetTextureAlphaMod|SDL_SetTextureAlphaMod]].
     4220
     4221These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
     4222
     4223These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     4224
     4225
     4226<procedure>(texture-blend-mode texture) → symbol</procedure>
     4227<procedure>(texture-blend-mode-raw texture) → integer</procedure>
     4228<setter>(set! (texture-blend-mode texture) mode)</setter>
     4229<setter>(texture-blend-mode-set! texture mode)</setter>
     4230
     4231See [[https://wiki.libsdl.org/SDL_GetTextureBlendMode|SDL_GetTextureBlendMode]]
     4232and [[https://wiki.libsdl.org/SDL_SetTextureBlendMode|SDL_SetTextureBlendMode]].
     4233
     4234* {{texture-blend-mode}} returns a [[https://gitlab.com/chicken-sdl2/chicken-sdl2/blob/master/docs/enums.md#blend-mode|blend mode symbol]]:
     4235** {{'none}}
     4236** {{'blend}}
     4237** {{'add}}
     4238** {{'mod}}
     4239* {{texture-blend-mode-raw}} returns an integer.
     4240* The setters accept either a symbol or integer.
     4241
     4242These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
     4243
     4244These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     4245
     4246
     4247<procedure>(texture-color-mod texture) → [r g b]</procedure>
     4248<procedure>(texture-colour-mod texture) → [r g b]</procedure>
     4249<setter>(set! (texture-color-mod texture) rgb)</setter>
     4250<setter>(set! (texture-colour-mod texture) rgb)</setter>
     4251<setter>(texture-color-mod-set! texture rgb)</setter>
     4252<setter>(texture-colour-mod-set! texture rgb)</setter>
     4253
     4254See [[https://wiki.libsdl.org/SDL_GetTextureColorMod|SDL_GetTextureColorMod]]
     4255and [[https://wiki.libsdl.org/SDL_SetTextureColorMod|SDL_SetTextureColorMod]].
     4256
     4257{{texture-color-mod}} and {{texture-colour-mod}} return multiple values.
     4258
     4259The setters accept either a list {{(r g b)}} of color values, or an sdl2:color (the sdl2:color's "a" field will be ignored).
     4260
     4261These procedures signal an exception of kind {{(exn sdl2)}} if an error occurs.
     4262
     4263These procedures are available in '''sdl2 egg version 0.2.0 and higher'''.
     4264
     4265
     4266<procedure>(lock-texture-raw! texture rect) → [pixels pitch]</procedure>
     4267
     4268Lock the texture so that its pixel data can be overwritten.
     4269This is for advanced users, and must be used with caution.
     4270See [[https://wiki.libsdl.org/SDL_LockTexture|SDL_LockTexture]].
     4271See also {{unlock-texture!}}.
     4272
     4273* {{texture}} is the sdl2:texture that you wish to modify
     4274* {{rect}} is either an sdl2:rect (to lock part of the texture), or #f (to lock all of the texture).
     4275
     4276This procedure returns multiple values:
     4277
     4278; pixels : A raw pointer that you can write pixel data to. Does not necessarily contain the old data.
     4279; pitch : An integer indicating the pitch of the pixel data
     4280
     4281Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     4282
     4283This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     4284
     4285
     4286<procedure>(unlock-texture! texture)</procedure>
     4287
     4288Unlock the texture, applying the new pixel data to the texture.
     4289This is for advanced users, and must be used with caution.
     4290See [[https://wiki.libsdl.org/SDL_UnlockTexture|SDL_UnlockTexture]].
     4291See also {{lock-texture-raw!}}.
     4292
     4293This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     4294
     4295
     4296<procedure>(update-texture-raw! texture rect pixels pitch)</procedure>
     4297
     4298Overwrite part or all of the texture's pixel data.
     4299This is for advanced users, and must be used with caution.
     4300See [[https://wiki.libsdl.org/SDL_UpdateTexture|SDL_UpdateTexture]].
     4301
     4302* {{texture}} is the sdl2:texture that you wish to update
     4303* {{rect}} is either an sdl2:rect (to update part of the texture), or #f (to update all of the texture)
     4304* {{pixels}} is a pointer or locative to raw pixel data
     4305* {{pitch}} is an integer describing the pitch of the pixel data
     4306
     4307Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     4308
     4309This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     4310
     4311
     4312<procedure>(update-yuv-texture-raw! texture rect y-plane y-pitch u-plane u-pitch v-plane v-pitch)</procedure>
     4313
     4314Overwrite part or all of a YV12- or IYUV-formatted texture's pixel data.
     4315This is for advanced users, and must be used with caution.
     4316See [[https://wiki.libsdl.org/SDL_UpdateYUVTexture|SDL_UpdateYUVTexture]].
     4317
     4318* {{texture}} is the sdl2:texture that you wish to update
     4319* {{rect}} is either an sdl2:rect (to update part of the texture), or #f (to update all of the texture)
     4320* {{y-plane}} is a pointer or locative to raw pixel data for the Y plane
     4321* {{y-pitch}} is an integer describing the pitch of the Y pixel data
     4322* {{u-plane}} is a pointer or locative to raw pixel data for the U plane
     4323* {{u-pitch}} is an integer describing the pitch of the U pixel data
     4324* {{v-plane}} is a pointer or locative to raw pixel data for the V plane
     4325* {{v-pitch}} is an integer describing the pitch of the V pixel data
     4326
     4327Signals an exception of kind {{(exn sdl2)}} if an error occurs.
     4328
     4329This procedure is available in '''sdl2 egg version 0.2.0 and higher'''.
     4330It requires '''SDL 2.0.1 or higher'''.
     4331It signals an error if the compiled version of SDL is not high enough.
     4332Use the [[#version-feature-identifiers|{{libSDL-2.0.1+}} feature identifier]]
     4333to check before calling this procedure.
    40534334
    40544335
Note: See TracChangeset for help on using the changeset viewer.